Add handoff documentation

Overview, architecture notes, and next steps for anyone
picking this up — including Rails API gotchas discovered
during implementation.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

handoff/next-steps.md

@@ -0,0 +1,72 @@
+# Next Steps
+
+## Immediate: Rails Engine (browser UI)
+
+Mount a UI at `/whetrails` inside the host Rails app. A developer adds the gem to their
+Gemfile, mounts the engine in `config/routes.rb`, starts the server, and visits `/whetrails`.
+
+### What the UI needs to show
+
+- A list of all models in the app (left sidebar or index page)
+- Click a model → full chain view (same data as CLI, but visual)
+- Lifecycle timeline: each stage as a row, callbacks as nodes within it
+- Source file/line as a clickable link (opens in editor via `vscode://` URI scheme)
+- Conditions rendered inline (`if: :paid?` shown as a badge)
+- Callbacks from concerns/gems visually distinguished from model-defined ones
+
+### Technical approach for the engine
+
+```ruby
+# lib/whetrails/engine.rb
+module Whetrails
+  class Engine < ::Rails::Engine
+    isolate_namespace Whetrails
+  end
+end
+```
+
+Rails engine conventions:
+- Routes go in `config/routes.rb` inside the gem
+- Controllers in `app/controllers/whetrails/`
+- Views in `app/views/whetrails/`
+- The host app mounts it: `mount Whetrails::Engine, at: "/whetrails"`
+
+The engine controllers call `Whetrails::Inspector` directly — no duplication of logic.
+
+### Model discovery
+
+The engine index page needs to list all AR models in the host app:
+
+```ruby
+Rails.application.eager_load!
+models = ApplicationRecord.descendants  # or ActiveRecord::Base.descendants
+```
+
+## After engine: Test Gap Analysis
+
+Once the chain is extracted, gap analysis is:
+
+1. Run the test suite with SimpleCov (or equivalent) to get line coverage data
+2. For each callback method in the chain, check whether its source lines are covered
+3. For each validator, check whether the validation path is exercised
+4. Report: "these 3 callbacks have no test coverage"
+
+The chain data structure (`ModelChain`) is already the right shape for this — each
+`CallbackEntry` has `source_file` and `source_line`, which can be cross-referenced
+against SimpleCov's coverage report.
+
+## Product / distribution
+
+- Publish to RubyGems.org once the engine is working
+- The gem should be dev/test-only (add to Gemfile under `group :development`)
+- Pricing model TBD — could be open source with a paid cloud version, or MIT with
+  a commercial license for teams
+
+## Environment notes
+
+- Ruby 3.3.6 installed via rbenv (`~/.rbenv/versions/3.3.6`)
+- rbenv init added to `~/.zshrc`
+- Rails 8.1.3
+- Dev database: SQLite at `storage/development.sqlite3`
+- Gitea running in Docker on localhost:3000 (container name: `gitea`)
+- Gitea API token for `bill`: `c2948775b80bcaa0ba65c6359658d0d48c340c4e`