woods 1.6.1 → 2.0.0.beta2

data/docs/INTERNALS.md

@@ -0,0 +1,418 @@
+# Woods internals
+
+This doc explains how Woods works from the inside, how extraction, storage, retrieval, and the two MCP servers fit together.
+
+---
+
+## How does Woods work?
+
+Woods runs in three phases across two environments:
+
+```
+Inside Rails app (rake task):
+  1. Extract, 35 extractors introspect the live Rails environment
+  2. Resolve, dependency graph is built and enriched with git data
+  3. Write, one JSON file per code unit to tmp/woods/
+
+On the host / in CI:
+  4. Embed, units are chunked and embedded into a vector store
+  5. Query, MCP server reads the JSON index and answers questions
+```
+
+The key insight: **extraction requires a booted Rails application** (`ActiveRecord::Base.descendants`, `Rails.application.routes`, etc.), but *querying* does not. The Index MCP server reads static JSON, no Rails, no database.
+
+---
+
+## Pipeline overview
+
+```
+┌──────────────────────────────────────────────────────────┐
+│                    Rails Application                     │
+│  ┌──────────┐   ┌──────────┐   ┌──────────┐             │
+│  │ Extract  │──▶│ Resolve  │──▶│  Enrich  │             │
+│  │ 35 types │   │  graph   │   │   git    │             │
+│  └──────────┘   └──────────┘   └──────────┘             │
+│                                     │                    │
+│                                     ▼                    │
+│                            ┌──────────────┐              │
+│                            │ Write JSON   │              │
+│                            │ tmp/woods/   │              │
+│                            └──────────────┘              │
+└──────────────────────────────────────────────────────────┘
+                                     │
+                                     ▼
+┌──────────────────────────────────────────────────────────┐
+│                 Host / CI Environment                    │
+│  ┌──────────┐   ┌──────────┐   ┌──────────────────────┐ │
+│  │  Embed   │──▶│  Index   │   │   MCP Index Server   │ │
+│  │  OpenAI  │   │  pgvector│   │ 14 default, no Rails │ │
+│  │  Ollama  │   │  Qdrant  │   └──────────────────────┘ │
+│  └──────────┘   └──────────┘                            │
+└──────────────────────────────────────────────────────────┘
+                                                 ▲
+                        ┌────────────────────────┘
+                        │  Console MCP Server
+                        │  9 tools default, live Rails
+                        │  (runs inside the app)
+```
+
+---
+
+## What is an ExtractedUnit?
+
+`ExtractedUnit` is the universal currency of Woods. Extractors produce them, the dependency graph connects them, the embedding pipeline consumes them, and the retrieval pipeline returns them.
+
+Every unit carries:
+
+- **`identifier`**: unique key, usually the class name (`"User"`, `"OrdersController"`) or a descriptive string for non-class units (`"POST /orders"`)
+- **`type`**: what kind of thing this is (`:model`, `:controller`, `:service`, `:route`, etc.)
+- **`file_path`**: relative path from `Rails.root` (e.g., `"app/models/user.rb"`). Gem-owned units (engine models such as `ActiveStorage::Blob`, framework sources) keep their absolute gem path, since nothing under `Rails.root` defines them
+- **`source_code`**: the annotated source: for models this includes concerns inlined and schema prepended; for controllers this includes a route context header
+- **`metadata`**: type-specific structured data (associations, callbacks, actions, fields, etc.)
+- **`dependencies`**: forward edges: `[{ type:, target:, via: }]`
+- **`dependents`**: reverse edges, populated in a second pass after all units are registered
+- **`chunks`**: semantic sub-sections for large units (populated by `SemanticChunker`)
+- **`estimated_tokens`**: approximate token count using 4.0 chars/token (benchmarked conservative floor)
+
+Units are serialized to JSON with two additional fields: `extracted_at` (timestamp) and `source_hash` (SHA-256 of source_code for change detection).
+
+See [EXTRACTOR_REFERENCE.md](EXTRACTOR_REFERENCE.md) for the full field table and a complete example JSON.
+
+### Internal static self-map
+
+`woods:self_map[output_dir]` is an internal Woods developer tool. It snapshots
+and statically maps Woods Ruby sources, rake tasks, and executables, then
+publishes them through the ordinary atomic index layout. It exposes typed
+`ruby_class`, `ruby_module`, `ruby_method`, and `ruby_file` units to the Index
+MCP reader. It does not boot Rails or include tests and documentation, and
+must not be presented as equivalent to runtime Rails extraction.
+
+---
+
+## How does extraction work?
+
+### Eager loading
+
+Before any extractor runs, `Rails.application.eager_load!` is called once to load all application classes into memory. If `eager_load!` fails with a `NameError` (common when `app/graphql/` references an uninstalled gem. Zeitwerk processes directories alphabetically, so a failure in `graphql/` can prevent `models/` from loading), the orchestrator falls back to per-directory loading across the 19 directories in `EXTRACTION_DIRECTORIES`.
+
+### Five phases
+
+```ruby
+# Phase 1: Extract
+EXTRACTORS.each { |type, klass| @results[type] = klass.new.extract_all }
+
+# Phase 1.5: Deduplicate
+# Duplicate identifiers (e.g., engine routes duplicating app routes) are dropped
+
+# Phase 2: Resolve dependents
+# Second pass: if A.dependencies includes B, B.dependents gets a back-reference to A
+
+# Phase 3: Enrich with git
+# batch git log for all file paths → last_modified, contributors, change_frequency
+
+# Phase 4: Graph analysis
+# PageRank, orphans, dead ends, hubs, cycles, bridges
+
+# Phase 5: Write
+# One JSON file per unit + _index.json per type + dependency_graph.json + SUMMARY.md + manifest.json
+```
+
+### Concurrent mode
+
+Set `config.concurrent_extraction = true` to run extractors in parallel threads. Thread safety is ensured by:
+- Pre-computing `ModelNameCache` before threads start (avoids a `||=` race)
+- Each thread gets its own extractor instance (no shared mutable state)
+- Results are collected via `Mutex`-protected hash
+- Dependency graph registration happens sequentially after all threads join
+
+### Incremental extraction
+
+`extract_changed(changed_files)` re-extracts only the units affected by a set of changed files. It:
+1. Loads the existing `dependency_graph.json`
+2. Finds directly-changed units via the file map
+3. BFS-traverses reverse edges to find transitively affected units
+4. Re-extracts each affected unit using the appropriate extractor method
+5. Updates only the affected JSON files and the type-level `_index.json`
+
+**Incremental extraction re-runs wholesale**, rather than skipping, the ten unit types that don't map to individual files: `route`, `middleware`, `engine`, `scheduled_job`, `state_machine`, `factory`, `event`, `database_view`, `rails_source` (gated by `include_framework_sources`), and `package`. Each has its own trigger path (e.g. `config/routes.rb` for routes, `Gemfile.lock` for middleware/engines), when it changes, `Extractor::WHOLE_APP_EXTRACTORS` re-runs that extractor in full instead of diffing files. `gem_source` works the same way, also triggered by `Gemfile.lock`.
+
+---
+
+## How does the dependency graph work?
+
+The `DependencyGraph` is a directed graph where nodes are `ExtractedUnit` identifiers and edges are dependency relationships. It tracks:
+
+- **Forward edges** (`@edges`): what each unit depends on, populated when units are registered
+- **Reverse edges** (`@reverse`): what depends on each unit, built during registration and in the resolve phase
+
+```ruby
+graph = DependencyGraph.new
+graph.register(user_unit)     # adds User to nodes, adds User→Order edge (from belongs_to)
+graph.register(order_unit)    # adds Order to nodes
+
+graph.dependencies_of("User")  # => ["Order", "UserService"]
+graph.dependents_of("Order")   # => ["User", "OrdersController"]
+
+# Blast radius: what needs re-indexing if user.rb changes?
+graph.affected_by(["app/models/user.rb"])  # BFS over reverse edges
+```
+
+### PageRank scoring
+
+`DependencyGraph#pagerank` computes importance scores using the reverse edge structure: units with many dependents score higher. This matches the intuition that "important" units are the ones many other units depend on, the same insight as Google's PageRank applied to code graphs. Package units (#280) add nodes and `package_dependency` edges to the graph, so scores shift slightly wherever they land.
+
+Scores feed into the retrieval ranker as one signal in the final ranking formula.
+
+### GraphAnalyzer: Structural metrics
+
+`GraphAnalyzer` computes read-only structural reports from the graph:
+
+| Metric | What it means |
+|--------|--------------|
+| **Orphans** | Units with no dependents, potential dead code or public entry points. Framework sources are excluded (they're naturally unreferenced in the reverse index). |
+| **Dead ends** | Units with no dependencies, self-contained leaf nodes (value objects, standalone utilities) |
+| **Hubs** | Units with many dependents, architectural bottlenecks; changes here have high blast radius |
+| **Cycles** | Circular dependencies, A→B→C→A. Detected via DFS, and capped: `graph_cycle_limit` (default 500) bounds how many are enumerated and `graph_cycle_max_length` (default 50) skips one longer than that. Either cap firing sets `stats.cycle_limit_reached`. Set both to `nil` for exhaustive enumeration. |
+| **Bridges** | Edges whose removal would disconnect the graph, high-risk structural connections |
+| **Cross-database edges** | Association or foreign-key edges whose two ends resolve to different databases. A `has_many :through` is reported as `join_through_across_databases` when `disable_joins` is false and `from_db`, `through_db` (the join model's database), or `to_db` disagree. A foreign key never resolves to an owner in the source database, even when another database also claims the table; when every owner sits elsewhere and they span more than one database, the entry comes back with `to: nil` and an `ambiguous_owners` list instead of guessing. Read from graph node and edge attributes, so full and incremental runs agree. Scoped to primary nodes (units registered in the graph), not variants. |
+| **Volatile dependencies** | Edges that point at a unit changing at least `volatile_dependency_ratio` times more often than the dependent (POODR: depend on things that change less often than you do). Dependencies with fewer than 5 commits or a `new` change frequency are skipped. Ranked by the dependency's PageRank; the persisted list keeps the top 20, while `stats.volatile_dependency_count` reports the full qualifying count and `stats.volatile_dependencies_limit` reports the cap. |
+| **Undeclared package edges** | Edges that cross a Packwerk package boundary the source package does not list in `dependencies`. Membership comes from each unit's `package` node attribute, declarations from the package unit's own `package_dependency` edges. Woods reports the boundary; enforcement stays with `packwerk check` / `pks check`. |
+
+Analysis results are written to `graph_analysis.json` and surfaced in `SUMMARY.md`.
+
+#### Sections, their stat keys, and which are capped
+
+Section names are plural, stat keys are singular. Do not derive one from the
+other: `bridges` has no stat key at all, and `hub_count` counts the array as
+persisted rather than every hub in the graph.
+
+| Section in `graph_analysis.json` | Stat key | Capped in the artifact | What the stat counts |
+|---|---|---|---|
+| `orphans` | `stats.orphan_count` | no | every orphan |
+| `dead_ends` | `stats.dead_end_count` | no | every dead end |
+| `hubs` | `stats.hub_count` | yes, top 20 by dependent count | the persisted array, so it stops at 20 |
+| `cycles` | `stats.cycle_count`, `stats.cycle_limit_reached` | yes, `graph_cycle_limit` cycles of at most `graph_cycle_max_length` nodes | the count is the persisted array; the flag says whether either cap fired |
+| `bridges` | none | yes, top 10 by score | not counted |
+| `cross_database_edges` | `stats.cross_database_edge_count` | no | every crossing edge |
+| `volatile_dependencies` | `stats.volatile_dependency_count`, `stats.volatile_dependencies_limit` | yes, top 20 by the dependency's PageRank | the count is every qualifying edge; the limit is the cap |
+| `undeclared_package_edges` | `stats.undeclared_package_edge_count` | no | every undeclared crossing |
+
+A capped section means the array on disk is a page, not the population.
+`volatile_dependencies` publishes both numbers and `cycles` publishes a
+truncation flag, so those two are the ones where a reader can tell truncation
+from a short list without re-running the analysis. Cycle enumeration stops at
+the cap rather than counting past it, which is why `cycles` gets a flag and not
+a population count.
+The `graph_analysis` MCP tool pages each section independently when given
+`limit` or `offset`, and its `Showing N of M (truncated)` line counts the array
+it read from disk, not the population the stat keys count.
+
+---
+
+## How does retrieval work?
+
+Retrieval is a four-stage pipeline coordinated by `Retriever`:
+
+```
+Query → [Classify] → [Execute] → [Rank] → [Assemble] → Context string
+```
+
+### Stage 1: Query classification (`QueryClassifier`)
+
+Classifies the query to determine:
+- **Intent**: lookup, explanation, tracing, search, framework
+- **Scope**: specific identifier, type filter, or broad
+- **Target type**: `:model`, `:controller`, `:service`, etc. (or nil for cross-type)
+
+Classification determines which search strategy to use and whether framework source context is relevant.
+
+### Stage 2: Search execution (`SearchExecutor`)
+
+Executes one or more search strategies based on classification:
+
+| Strategy | When used | How |
+|----------|-----------|-----|
+| **Vector** | Semantic/conceptual queries | Embeds the query and finds nearest neighbors |
+| **Keyword** | Identifier lookups by name | Exact or prefix match on `identifier` field |
+| **Graph** | "What uses X?" / "What does X depend on?" | Traverses forward/reverse edges from a starting node |
+| **Hybrid** | Default for ambiguous queries | Combines vector + keyword, re-ranked via RRF |
+
+### Stage 3: Ranking (`Ranker`)
+
+Re-ranks candidates using multiple signals with weighted combination:
+
+- Vector similarity score
+- Keyword match quality
+- PageRank importance score
+- Recency (git `last_modified`)
+- Type relevance to the query's target type
+
+Uses **Reciprocal Rank Fusion (RRF)** to merge ranked lists from multiple search strategies without score normalization.
+
+### Stage 4: Context assembly (`ContextAssembler`)
+
+Allocates token budget across layers:
+
+```
+Token Budget Allocation:
+├── 10%  Structural overview ("Codebase: 42 units, 10 models, 5 controllers, ...")
+└── 90%  Remaining budget, split by framework context:
+    ├── framework active:   55% primary / 25% supporting / 20% framework reference
+    └── framework inactive: 65% primary / 35% supporting (framework gets nothing)
+```
+
+Units that exceed the budget are truncated to their first semantic chunk. The assembled context string is then optionally post-processed by a formatter (`context_format: :claude`, `:markdown`, `:plain`, `:json`).
+
+---
+
+## What storage backends are available?
+
+Woods uses three independent store abstractions:
+
+| Store | Purpose | Available Backends |
+|-------|---------|-------------------|
+| **VectorStore** | Embedding vectors for semantic search | In-memory (dev/test), pgvector (PostgreSQL), Qdrant |
+| **MetadataStore** | Unit metadata for keyword search and type filtering | In-memory, SQLite |
+| **GraphStore** | Dependency graph for graph-based traversal | In-memory, JSON file (via `dependency_graph.json`) |
+
+The gem is backend-agnostic by design. MySQL and PostgreSQL have different JSON querying, indexing, and CTE syntax, no backend-specific SQL is written into the core.
+
+### Configuration presets
+
+```ruby
+# Local development (SQLite + in-memory vector, single process)
+Woods.configure_with_preset(:local)
+
+# Shared filesystem (rake embed writes a dump; a separate MCP server reads it)
+Woods.configure_with_preset(:shared_filesystem)
+
+# PostgreSQL with pgvector (complete credentials/connection are required)
+Woods.configure_with_preset(:postgresql) do |config|
+  config.embedding_options = { api_key: ENV.fetch('OPENAI_API_KEY') }
+  config.vector_store_options = { connection: ActiveRecord::Base.connection }
+end
+
+# Production (Qdrant for vectors, SQLite for metadata)
+Woods.configure_with_preset(:production) do |config|
+  config.embedding_options = { api_key: ENV.fetch('OPENAI_API_KEY') }
+  config.vector_store_options = {
+    url: ENV.fetch('QDRANT_URL'),
+    collection: ENV.fetch('WOODS_QDRANT_COLLECTION', 'woods'),
+    allow_private_hosts: true # only when QDRANT_URL is deliberately private
+  }
+end
+```
+
+Or wire backends manually:
+
+```ruby
+Woods.configure do |config|
+  config.vector_store = :qdrant
+  config.vector_store_options = {
+    url: "http://localhost:6333",
+    collection: "woods",
+    allow_private_hosts: true # explicit opt-in for trusted localhost
+  }
+  config.metadata_store = :sqlite
+  config.embedding_provider = :openai
+  config.embedding_options = { api_key: ENV.fetch("OPENAI_API_KEY") }
+  config.embedding_model = "text-embedding-3-small"
+end
+```
+
+---
+
+## Why are there two MCP servers?
+
+The two servers have fundamentally different runtime requirements:
+
+### Index server (`woods-mcp`)
+
+**29 schemas; 14 register in the packaged default. Two resources and two templates. Reads pre-extracted JSON without booting Rails.**
+
+Starts with a path to the extraction output directory and reads from it:
+
+```bash
+woods-mcp-start /path/to/rails-app/tmp/woods
+```
+
+Use the Index Server for:
+- Looking up models, controllers, services by name
+- Dependency graph traversal ("what depends on User?")
+- Semantic search across the codebase
+- Pipeline management (status, trigger re-extraction)
+- Temporal snapshots (comparing codebase state over time)
+- Feedback collection
+
+Note: pipeline management and feedback collection require specialized builder collaborators. The packaged `woods-mcp` executable wires neither, so those tools are not registered in a standard launch. Snapshot tools register only when snapshots are enabled (`enable_snapshots: true`, `WOODS_SNAPSHOTS=true`, or an existing snapshot database in the index directory).
+
+The Index Server is safe to run anywhere, it has no database connection and makes no writes to the Rails application.
+
+### Console server (`woods-console-mcp`)
+
+**31 tool schemas across 4 tiers, but only 9 are registered by default (11 with read tools enabled). Runs embedded inside the Rails process, no separate bridge process.**
+
+Starts via rake task inside the Rails app (or `docker compose exec`):
+
+```bash
+bundle exec rake woods:console
+```
+
+Use the Console Server for:
+- Live database queries (`User.where(...)` with schema awareness). Tier 1, registered by default
+- Model diagnostics, job queue monitoring, cache inspection. Tier 2/3 schemas exist but are **not registered** in any supported mode today
+- SQL/query. Tier 4, opt-in via `console_embedded_read_tools`; `console_eval` is inventory-only and unavailable
+
+All Console Server queries run inside a **rolled-back transaction** (`SafeContext`). SQL is validated by `SqlValidator` (rejects DML/DDL at the string level) before any database interaction. Writes are silently discarded by the rollback, this is intentional defense-in-depth. See [MCP_SERVERS.md](MCP_SERVERS.md#console-server) for the full tool inventory and tier breakdown.
+
+### Which should I use?
+
+| Task | Server |
+|------|--------|
+| Find the User model source | Index |
+| What jobs does CheckoutService enqueue? | Index |
+| How many pending orders are in the database? | Console |
+| What does our middleware stack look like? | Index |
+| Run a query against the live database | Console |
+| Trigger a re-extraction | Index |
+| Check Sidekiq queue depth | Console |
+
+---
+
+## How does semantic chunking work?
+
+Large units are split into semantic chunks before embedding. The `SemanticChunker` is type-aware, it doesn't split on arbitrary token counts.
+
+### Model chunking
+
+Models are split into purpose-specific sections:
+
+```
+summary, class declaration, table info, concerns list
+associations, all has_many, belongs_to, has_one, HABTM
+callbacks, all before/after/around hooks with side-effects
+validations, all validates and validate calls
+scopes, named scopes
+methods, remaining public and private methods
+```
+
+Each chunk includes a header with the unit's identifier, type, and file path so it's self-contained when retrieved without the parent.
+
+### Controller chunking
+
+Controllers chunk per-action:
+
+```
+summary, class declaration, before_action filters, layout
+<action>, each public action method with its applicable filters and route context
+```
+
+This matches how queries actually come in: "how does the create action work?" retrieves only the `create` chunk and the filter context, not the entire controller.
+
+### Threshold
+
+Units below 200 estimated tokens stay as a single `:whole` chunk. Above that, the semantic chunker applies type-specific splitting, with a line-based fallback for units that are still too large. The fallback's per-chunk limits are not fixed constants, they derive from the embedding provider's input budget (`max_chars` from `max_input_tokens` scaled by the provider's chars-per-token ratio, or an exact `max_tokens` when a tokenizer is available), so a provider with a larger context yields larger chunk ceilings.
+
+### Why not just split by token count?
+
+Token-count splits break semantic units arbitrarily, an `associations` section split mid-way loses context. Semantic splits align with how the code is actually understood: "tell me about the associations" maps to the associations chunk, not to arbitrary line ranges 150–300.

data/docs/MCP_HTTP_TRANSPORT.md

@@ -0,0 +1,144 @@
+# MCP HTTP Transport
+
+Reference for `exe/woods-mcp-http`, the Index Server's HTTP transport, for hosts where a stdio subprocess isn't practical (shared access, multiple clients, a remote agent).
+
+## What's shipped
+
+- **`exe/woods-mcp-http`**: the only HTTP entry point. There is no `--http` flag on `woods-mcp` and no `Woods::MCP::RackMiddleware` for the Index Server (the Console Server has its own separate `RackMiddleware`, see [CONSOLE_MCP_SETUP.md](CONSOLE_MCP_SETUP.md)).
+- Built on `MCP::Server::Transports::StreamableHTTPTransport` from the `mcp` gem (`>= 1.2, < 2.0`), which implements MCP protocol version 2026-07-28 (legacy `initialize` still served for older clients).
+- **Stateless by default.** `WOODS_MCP_HTTP_STATELESS=0` restores legacy session mode.
+- **Bearer auth** (`WOODS_MCP_HTTP_TOKEN`) and an **origin guard** (`WOODS_MCP_HTTP_ALLOWED_ORIGINS`), see [Security](#security).
+- Needs a Rack-compatible server (e.g. `puma`) in the host bundle. Uses the `rackup` gem when present, falls back to Rack 2's handler registry otherwise.
+
+## Running it
+
+```bash
+bundle exec woods-mcp-http ./tmp/woods                          # loopback, stateless, no auth
+HOST=0.0.0.0 PORT=9292 WOODS_MCP_HTTP_TOKEN=$(bundle exec rake woods:generate_token 2>/dev/null) \
+  bundle exec woods-mcp-http ./tmp/woods                        # non-loopback requires a token
+```
+
+| Env var | Default | Meaning |
+|---|---|---|
+| `PORT` | `9292` | Listen port |
+| `HOST` | `localhost` | Listen host. Anything non-loopback requires `WOODS_MCP_HTTP_TOKEN` (server refuses to boot otherwise) |
+| `WOODS_MCP_HTTP_TOKEN` | unset | Bearer token required on every request when set |
+| `WOODS_MCP_HTTP_STATELESS` | `1` | `0` restores legacy session mode (`Mcp-Session-Id`, GET SSE stream, DELETE teardown) |
+| `WOODS_MCP_HTTP_ALLOWED_ORIGINS` | unset (loopback origins only) | Comma-separated origin allow-list for the `Origin` header guard |
+| `WOODS_DIR` / `ARGV[0]` | cwd | Index directory to serve |
+
+## Statelessness
+
+MCP 2026-07-28 ([SEP-2567](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2567)) removes protocol-level sessions, and `woods-mcp-http` runs stateless by default.
+
+For this server the session was never carrying anything: the index lives on disk, `IndexReader` self-refreshes off the published generation, and no tool holds per-client state. What the session *did* do was tie every client to one server process, so restarting the server (gem upgrade, machine sleep, worktree rebuild) invalidated every session and forced each client through a re-initialize. Stateless makes a restart invisible, and lets several instances serve one volume-mounted index without sticky routing.
+
+What changes in stateless mode:
+
+| Behaviour | Stateless (default) | Session mode (`=0`) |
+|---|---|---|
+| `Mcp-Session-Id` | never issued or required | issued on `initialize`, required after |
+| `GET` on the MCP endpoint | `405 Method Not Allowed` | opens a standalone SSE stream |
+| `DELETE` on the MCP endpoint | `200` no-op (see note) | terminates the session |
+| A request carrying a stale `Mcp-Session-Id` | ignored, served normally | `404`, client must re-initialize |
+| Server-initiated notifications | **not delivered**: there is no stream to push on | delivered to the session's SSE stream |
+| Server restart | invisible to clients | every client must re-initialize |
+| Horizontal scaling | any POST may hit any instance | requires sticky routing |
+
+> **`Mcp-Session-Id` and CORS.** In stateless mode the header is neither read nor emitted, so it is absent from `Access-Control-Expose-Headers`. A client that depends on it needs `WOODS_MCP_HTTP_STATELESS=0`, a transitional escape hatch, since the header is gone from the specification.
+
+> **DELETE returns 200, not 405.** The specification says a server supporting only this revision *should* answer `405` to DELETE; the `mcp` gem instead answers `200 {"success": true}` in stateless mode. This is the SDK's call, not Woods', there is no session to terminate either way, so the request is a no-op whichever status it carries.
+
+The last row is the one that matters in practice: a client holding a session id from *before* a restart is simply served, rather than getting a `404` and having to re-initialize.
+
+> **Notifications and long-running tools.** Stateless mode has no channel to push server-initiated notifications on at all (no `Last-Event-ID` resumability either, per SEP-2567). Woods' packaged Index tools are short reads. Custom embedded servers that wire pipeline tools use durable task polling rather than depending on a push; those tools are not registered by the normal packaged executable.
+
+## Security
+
+The `mcp` gem does not authenticate at the transport layer, so `exe/woods-mcp-http` enforces authentication itself:
+
+| `HOST`                            | `WOODS_MCP_HTTP_TOKEN` set? | Result                                                      |
+|-----------------------------------|------------------------------|---------------------------------------------------------------|
+| `localhost` / `127.0.0.1` / `::1` | no                           | Boots with a warning; unauthenticated loopback access only  |
+| `localhost` / `127.0.0.1` / `::1` | yes                          | Boots; every request must present `Authorization: Bearer …` |
+| anything else                     | no                           | **Refuses to boot**: aborts with a pointer to this section |
+| anything else                     | yes                          | Boots; every request must present `Authorization: Bearer …` |
+
+This matches the posture used by other unauthenticated local servers (Redis `protected-mode`, Postgres `listen_addresses`): loopback works freely, non-loopback requires an explicit credential.
+
+### Generating a token
+
+```bash
+bundle exec rake woods:generate_token
+# prints a 64-char hex token to stdout
+```
+
+Any cryptographically random string works; `openssl rand -hex 32` is equivalent.
+
+### Running the server with a token
+
+```bash
+export WOODS_MCP_HTTP_TOKEN=$(bundle exec rake woods:generate_token 2>/dev/null)
+HOST=0.0.0.0 PORT=9292 bundle exec woods-mcp-http ./tmp/woods
+```
+
+Clients must send `Authorization: Bearer $WOODS_MCP_HTTP_TOKEN` on every request. Missing or mismatched tokens get `HTTP 401` with a `WWW-Authenticate: Bearer` header; comparison is constant-time (`Rack::Utils.secure_compare`).
+
+### Browser origins (DNS rebinding defense)
+
+A second middleware, `Woods::MCP::OriginGuard`, rejects requests whose `Origin` header is outside an allow-list. Requests without an `Origin` header (curl, MCP stdio clients, server-to-server) pass through, bearer auth still gates them.
+
+| Scenario          | `WOODS_MCP_HTTP_ALLOWED_ORIGINS`      | Origins accepted                                                |
+|--------------------|-----------------------------------------|-------------------------------------------------------------------|
+| default            | unset                                    | `http(s)://localhost`, `127.0.0.1`, `::1` (any port)              |
+| explicit list      | `https://app.example.com`                | exactly `https://app.example.com`, loopback no longer allowed  |
+| multiple origins   | `https://a.example,https://b.example`    | each listed origin                                                |
+
+`OPTIONS` preflights are answered with the matching `Access-Control-Allow-*` headers; successful responses carry `Access-Control-Allow-Origin` and `Vary: Origin`. `Access-Control-Expose-Headers: Mcp-Session-Id` appears only in legacy session mode (`WOODS_MCP_HTTP_STATELESS=0`).
+
+### TLS termination
+
+The server speaks plain HTTP. Any deployment beyond a single trusted host should front it with a reverse proxy that handles TLS, HTTP/2, and connection limits.
+
+**Caddy** (automatic HTTPS via Let's Encrypt):
+
+```caddyfile
+mcp.example.com {
+  reverse_proxy 127.0.0.1:9292
+}
+```
+
+**nginx** (bring-your-own cert):
+
+```nginx
+server {
+  listen 443 ssl http2;
+  server_name mcp.example.com;
+
+  ssl_certificate     /etc/letsencrypt/live/mcp.example.com/fullchain.pem;
+  ssl_certificate_key /etc/letsencrypt/live/mcp.example.com/privkey.pem;
+
+  location / {
+    proxy_pass http://127.0.0.1:9292;
+    proxy_set_header Host $host;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_set_header X-Forwarded-Proto $scheme;
+    proxy_http_version 1.1;
+    proxy_set_header Connection "";
+
+    # SSE streaming: disable buffering, raise timeouts
+    proxy_buffering off;
+    proxy_read_timeout 3600s;
+    proxy_send_timeout 3600s;
+  }
+}
+```
+
+Bind `woods-mcp-http` to `HOST=127.0.0.1` when a proxy handles the public surface; keep `WOODS_MCP_HTTP_TOKEN` set so the proxy-to-app hop still requires a bearer.
+
+### Known limitations
+
+- **Plaintext tokens on the wire.** Bearer auth over HTTP leaks the token to anything on the network path. Terminate TLS at a reverse proxy (nginx, Caddy, Cloudflare) for any deployment beyond a single trusted host.
+- **No rotation primitive.** There is one static token. Rotating it requires restarting the server and updating clients.
+- **No per-client identity.** Every valid request is equally trusted; there are no scopes or audit trails. Treat the token as a shared secret for a trust boundary you already control.
+- **No in-process TLS.** TLS is a reverse-proxy concern. Caddy/nginx/Cloudflare handle certs, HSTS, and cipher policy better than a Rack-level implementation would.