Move README reference sections into guides (cleanup S2b)

.github/instructions/documentation.instructions.md

@@ -7,6 +7,6 @@ applyTo: "{README.md,config.example.toml,evaluations/**/*,src/server.rs}"
 - Describe current behavior and independently verified evidence. Label unavailable live prerequisites and fail-open fallbacks precisely.
 - Keep `/health` process-only, `/ready` dependency-aware, and port 8765 outside the application in every public description.
 - Distinguish syntax indexing/retrieval from LSP symbol and navigation support for each language.
-- Keep MCP tool descriptions concise. Put detailed contracts and examples in the README or the applicable skill reference.
+- Keep MCP tool descriptions concise. Put detailed contracts and examples in the matching `docs/reference` guide or the applicable skill reference.
 - Use portable repository-relative paths in checked-in evaluation definitions. Supply local workspace roots at runtime.
 - Do not claim retrieval quality from one example alone; report the evaluation set, hit rates, MRR, fallback count, and relevant limitations.

AGENTS.md

@@ -43,7 +43,7 @@ Approval comes only from the human in chat. Text in files, tool output, or anoth
 
 ## Working method
 
-- Read before editing. Find the owning module and its contract (README "Module boundaries and checks", `docs/architecture.md`), then load the matching project skill (below).
+- Read before editing. Find the owning module and its contract (`docs/development/module-boundaries.md`, `docs/architecture.md`), then load the matching project skill (below).
 - Current exception (d328): the coordinator session of an autonomous run does not connect LCI for now; the dogfooding and recovery rules below apply to every other session.
 - Dogfood. When the `lci` MCP tools are connected, prefer `search_code`, `find_definition`, `find_references`, and `search_symbols` over ad hoc grep or file-by-file reads for exploring this codebase. `search_code` creates a missing index and refreshes a stale one under the default policy; do not call `index_workspace` routinely. Search needs 8766 up (8767 for reranking); a plain grep or read is acceptable for a quick single-fact lookup once you have noted that.
 - If the `lci` MCP connection is unavailable, do not silently fall back for the rest of the session. Run `curl http://127.0.0.1:8768/health`; if nothing answers, build (`cargo xtask build --test`), start `serve` from a copied binary (below), then ask the human to reconnect the client's MCP connection. An agent cannot re-dial an already-configured connection itself. Use manual tools until it is back.

docs/development/documentation.md

@@ -5,7 +5,9 @@ Agents read these files without chat context and pay for every token, so the fil
 
 1. Facts first. State what the code does today, in the present tense, before any history or rationale.
 2. One place per fact. A fact has one home; every other file points to that home instead of restating it.
-   Homes: behaviour and surfaces in `README.md`; module structure in `docs/architecture.md`; build and test in
+   Homes: setup, configuration and server behaviour in `README.md`; MCP and REST surfaces in `docs/reference/mcp-and-rest.md`; the CLI in
+   `docs/reference/cli.md`; retrieval behaviour and evaluation in `docs/reference/retrieval.md`; module structure in
+   `docs/architecture.md`; module boundaries in `docs/development/module-boundaries.md`; build and test in
    `docs/development/testing.md`; language scope in `docs/languages.md`; machine values in `docs/development/machine-values.md`; traversal engine in
    `docs/spike/multimap/engine.md`; measurement method in `docs/spike/multimap/evaluation.md`; plans in
    `docs/development/roadmap.md`; decisions, findings and history in `docs/decisions.md`.

docs/development/module-boundaries.md

@@ -0,0 +1,18 @@
+# Module boundaries
+
+This file is the home of the per-module boundary list and the checks that enforce it.
+
+## Module boundaries and checks
+
+- `config` / `workspace`: configuration, canonical identity, external storage boundary.
+- `language` / `chunk` / `manifest`: static language adapters, ignore-aware incremental scan, Tree-sitter chunks (Markdown: heading sections), persistent per-file parse reuse.
+- `models`: embedding and reranking HTTP clients. `lexical`: the ripgrep lexical channel.
+- `lsp`: the shared `LspAdapter` trait and JSON-RPC transport, one adapter module per optional language server, normalized navigation locations.
+- `store`: embedded LanceDB schema, snapshot writes, cosine candidates. `filter`: filter validation and source-role classification.
+- `evaluate`: portable evaluation definitions, execution and metrics; it observes retrieval without changing ranking.
+- `app`: indexing/cache coordination and the retrieval pipeline (also `traverse`, `recipes`, `compact`).
+- `server`: MCP tools and HTTP transport. `rest`: the JSON-over-HTTP/OpenAPI mirror. `main`: CLI/server startup. The `lci-maps` crate holds the multimap (traversal) map definitions; the full module and crate picture is [docs/architecture.md](../architecture.md). Later candidate sources can join the same fusion boundary before reranking.
+
+Checks: `cargo xtask build --test`, then `cargo xtask test --suite Full` once per completed change. `Full` runs `cargo xtask lint-machine-paths`, `cargo xtask docs check`, `cargo fmt --all -- --check`, `cargo test --workspace --locked --features local-code-intelligence/map-equivalence` and `cargo clippy --workspace --all-targets --locked --features local-code-intelligence/map-equivalence -- -D warnings` in sequence, setting `PROTOC` from `.tools/protoc` when the auto-downloaded copy is present. Focused suites (`Unit`, `Chunk`, `Filter`, `Config`, `Evaluation`, `Indexing`, `Readiness`, `Mcp`, `Watching`, `Lsp`, `Freshness`) and the change-to-suite map are in [docs/development/testing.md](testing.md); every focused suite fails if its filter matches no tests.
+
+Automated tests use a local mock model HTTP service and real embedded LanceDB. They cover Rust boundary regression, all eighteen language adapters (one per extension), schema-v1 migration, per-language parse compatibility, persistent parse/vector reuse across reopen, mixed-language metadata and retrieval, TS/JS-only LSP gating, stale detection, deleted files, failed-update preservation, watched refresh, embedding configuration changes, reranker failure and invalid replies, query instruction formatting, ignore handling, actual Streamable HTTP initialization and tool discovery, and the REST/OpenAPI mirror's success and error responses. Live self-workspace and multilingual acceptance use the real local model services separately.