Fix docs that disagree with the code; split architecture.md (cleanup S2c)

.agents/skills/lci-autonomous-improvement/SKILL.md

@@ -43,7 +43,7 @@ Repeat until the stop rule fires or the roadmap has no ready item.
 3. **Implement.** Brief an implementer with the plan, the allowed-file list, the relevant contract files, and whether the `lci` MCP tools are connected. Inspect the saved diff for file scope and intent before anything else; a valid diff counts even without prose. Fix small gaps yourself or send one focused continuation; do not start a second implementer on the same files. A slice that depends on an unmerged one starts on a branch stacked on that one's branch instead of waiting for its merge; merge `origin/main` into it once the base lands, before its own gate and PR (d476).
 4. **Gate.** Run the focused suite first (`cargo xtask test --suite <name>` or `cargo test -p lci-core --lib <module>::`), then `cargo xtask test --suite Full` once the slice is complete. When the diff adds or changes process-wide state (a `static`, `OnceLock`, `thread_local!`, `task_local!` or a process-wide memo), also run the library tests of the affected crates once with `-- --test-threads=1` before pushing: such state can make a test pass only in some orders, and CI runs another order (d476; a serial pass of all library tests costs about 2.5 extra minutes, too much for every push). See "When a gate fails".
 5. **Evaluate (when the plan says so).** Follow `lci-retrieval-evaluation/references/evaluation-workflow.md` exactly: frozen `lci-base`/`lci-new` binaries, scratch configs with short separate data directories, sequential runs, reranked and reranker-unreachable pairs for prior/role/fusion changes, reports under `test-results/`. Do not compile or run tests while a timed run is in progress. Decide with the workflow's decision rule; if the change does not hold up, revert it and record why in `docs/decisions.md` (the roadmap row keeps a status only).
-6. **Review.** Brief a reviewer who did not write the code with the diff, the slice plan, and the evidence. It checks correctness, `AGENTS.md` boundaries (ports, data location, fail-open, freshness semantics), test honesty (no weakened or vacuous tests; suites that still match tests), documentation drift (README tables, `config.example.toml`, skill references, MCP tool descriptions), and scope creep. Address every finding or record why not; a disputed finding goes to the human, not silently dropped -- unless the human has delegated disputes, in which case pick one side (at random if both are defensible), log the dispute and the pick in `docs/decisions.md`, and continue.
+6. **Review.** Brief a reviewer who did not write the code with the diff, the slice plan, and the evidence. It checks correctness, `AGENTS.md` boundaries (ports, data location, fail-open, freshness semantics), test honesty (no weakened or vacuous tests; suites that still match tests), documentation drift (README tables, `docs/reference` guides, `config.example.toml`, skill references, MCP tool descriptions), and scope creep. Address every finding or record why not; a disputed finding goes to the human, not silently dropped -- unless the human has delegated disputes, in which case pick one side (at random if both are defensible), log the dispute and the pick in `docs/decisions.md`, and continue.
 7. **Commit and push.** One logical change per commit, message per the template: imperative subject under about 70 characters, a body saying what changed and why, the evidence (test counts, suites, live metrics before/after, report names), and limitations. The client adds the co-author trailer. Stage only the slice's files; never `git add -A` with scratch material present (`reports/`, `research_notes/`, `test-results/` are not slice files). Push the feature branch.
 8. **Record.** In the commit that does the work, remove the finished item's row from the roadmap and append its outcome (commit hash, evidence summary, measured results, dropped ideas) to `docs/decisions.md` as one line under the next free id; set the status of a successor whose only blocker it was and add follow-ups as new rows under the next free id of their letter (roadmap "How to use this file", step 5). An unfinished item keeps its row with a status (`in-progress`, `blocked(reason)`, `ready`) and what remains, and no result text. Update any docs the reviewer flagged in the same commit as the code, or in an immediately following one.
 9. **Check usage and continue.** Every fifth slice, run the triage pass first. Then check usage: below the stop threshold, run an explorer in the background if none is running and pick the next item; otherwise follow "Stopping at the usage limit".

.agents/skills/lci-autonomous-improvement/references/templates.md

@@ -9,14 +9,14 @@ Roadmap item: <id or title>
 Goal: <one sentence; the observable behavior that changes>
 Not in scope: <what this slice deliberately leaves alone>
 Allowed files: <explicit list; tests included>
-Contracts to read first: <AGENTS.md sections, skill references, README section>
+Contracts to read first: <AGENTS.md sections, skill references, README section or docs/reference guide>
 Acceptance:
   - <behavior 1, how it is observed>
   - <behavior 2>
 Tests to add or change: <file and case names>
 Gate: cargo xtask test --suite <focused>; then --suite Full
 Live evaluation: <none | evaluation-workflow.md steps 3-9, rerank on/off, workspaces>
-Docs to update: <README section, config.example.toml, skill reference, none>
+Docs to update: <README section, docs/reference guide, config.example.toml, skill reference, none>
 Revert condition: <what result means the slice is reverted, not fixed>
 ```
 
@@ -48,7 +48,7 @@ a one-line reason. Check in this order:
      freshness semantics, no client-specific code, no new service.
   3. Tests: honest (no weakened assertions, no #[ignore], no vacuous
      suite filters), cover the changed behavior and its failure path.
-  4. Doc drift: README tables and prose, config.example.toml, skill
+  4. Doc drift: README tables and prose, docs/reference guides, config.example.toml, skill
      references, MCP tool descriptions, evaluations/core.toml comments.
   5. Scope: files outside the allowed list, unrelated refactors.
 Say explicitly if you found nothing in a category. Do not edit files.
@@ -86,7 +86,7 @@ The diff is the deliverable; keep prose short.
 
 ```text
 Reviewer: slice <ID>. Read <plans_dir>/<plan file>, then `git diff <base>..<head>` and <evidence paths>. Do not edit.
-Check in order: correctness against the acceptance; AGENTS.md "Hard rules"; test honesty; doc drift (README, config.example.toml, skill references, decision line in `docs/decisions.md` if a default moved); scope.
+Check in order: correctness against the acceptance; AGENTS.md "Hard rules"; test honesty; doc drift (README, docs/reference guides, config.example.toml, skill references, decision line in `docs/decisions.md` if a default moved); scope.
 Report file:line, severity (blocker | should-fix | nit), one line each; say "none" for an empty category.
 lci MCP: <connected | not connected; use Grep/Read>.
 Do not run live evaluations or start services.

.agents/skills/lci-language-adapter/references/acceptance.md

@@ -14,7 +14,7 @@ A language-support claim requires evidence for the affected language:
 10. Compatible reuse after application restart.
 11. Semantic and lexical retrieval plus reranking and reranker fail-open behavior.
 12. A production implementation ranked against a realistic test, example, or documentation decoy.
-13. README, MCP, CLI, filter, and evaluation-definition updates.
+13. README, docs/reference guides, MCP, CLI, filter, and evaluation-definition updates.
 14. LSP navigation available via the language-server adapter contract, passing `lci-lsp-adapter`'s own acceptance bar (real workspace symbol/definition/reference evidence, provider isolation, and recovery).
 
 ## Where each class of evidence comes from
@@ -24,7 +24,7 @@ A language-support claim requires evidence for the affected language:
 | 1-4, 6-10 (mocked) | `lci-core` unit tests plus `tests/cases/indexing.rs` with the fake model service | `cargo test -p lci-core --lib chunk::`, `cargo xtask test --suite Indexing` |
 | 5-11 (live) | mixed-language fixture indexing, update, delete, restart, failed-update retention, live reranking | `cargo xtask acceptance multilingual` (8766/8767 up; reports `test-results/multilingual-*.json`) |
 | 12 | a scratch decoy evaluation TOML kept outside the repo, run with and without the reranker | `lci-retrieval-evaluation/references/evaluation-workflow.md` |
-| 13 | README language table and chunk description, `config.example.toml` (if an LSP section exists), `evaluations/core.toml` chunking query, MCP tool descriptions | review the diff against `.github/instructions/documentation.instructions.md` |
+| 13 | README language table and chunk description, `docs/reference` guides, `config.example.toml` (if an LSP section exists), `evaluations/core.toml` chunking query, MCP tool descriptions | review the diff against `.github/instructions/documentation.instructions.md` |
 | 14 | real server symbol/definition/reference, provider isolation, recovery | `cargo xtask acceptance <lang>-lsp`, `<lang>-missing`, `<lang>-recovery` |
 
 Use mocks for deterministic automated coverage and the configured 8766/8767 services for one bounded live acceptance. Report those evidence classes separately.

.agents/skills/lci-lsp-adapter/SKILL.md

@@ -7,7 +7,7 @@ description: Add or change an optional language-server integration in local-code
 
 Keep LSP optional and fail-open for code search while returning clear errors from direct navigation tools.
 
-Where things live: one adapter module per server under `lci-core/src/lsp/` (`rust.rs`, `csharp.rs`, `typescript.rs`, `python.rs`, `go.rs`, `java.rs`, `clangd.rs`) behind the shared trait in `adapter.rs` and the JSON-RPC transport in `transport.rs`; registration in `Manager::new` (`lci-core/src/lsp.rs`); the per-server `[<section>]` config in `lci-core/src/config.rs` (rust-analyzer: top-level `rust_analyzer_*` keys); the real-server acceptance specs under `xtask/src/acceptance/`.
+Where things live: one adapter module per server under `lci-core/src/lsp/` (`rust.rs`, `csharp.rs`, `typescript.rs`, `python.rs`, `go.rs`, `java.rs`, `clangd.rs`, `markdown.rs`) behind the shared trait in `adapter.rs` and the JSON-RPC transport in `transport.rs`; registration in `Manager::new` (`lci-core/src/lsp.rs`); the per-server `[<section>]` config in `lci-core/src/config.rs` (rust-analyzer: top-level `rust_analyzer_*` keys); the real-server acceptance specs under `xtask/src/acceptance/`.
 
 1. Read [the lifecycle and routing contract](references/lifecycle.md).
 2. Reuse a persistent process per compatible workspace and server configuration.

.agents/skills/lci-lsp-adapter/references/acceptance.md

@@ -12,7 +12,7 @@ Automated coverage (fake LSP in `tests/support`, `tests/cases/navigation.rs`, `l
 - Search fallback when the executable or request is unavailable.
 - Direct-navigation error behavior.
 
-Real acceptance must use the actual language-server executable against a known workspace and verify at least one workspace symbol, definition, and reference. The three xtask subcommands per language are the standard form: `cargo xtask acceptance <lang>-lsp` (full flow), `<lang>-missing` (provider isolation when the executable is absent), `<lang>-recovery` (persistent process reuse and forced-kill recovery). They start fixture servers on port 8769 and write normalized responses under `test-results/`. Record the executable and version, and distinguish unavailable tooling (`PREREQUISITE_UNAVAILABLE`) from a code failure. Do not claim support from a mocked server alone.
+Real acceptance must use the actual language-server executable against a known workspace and verify at least one workspace symbol, definition, and reference. The three xtask subcommands per language are the standard form (markdown has the first two only): `cargo xtask acceptance <lang>-lsp` (full flow), `<lang>-missing` (provider isolation when the executable is absent), `<lang>-recovery` (persistent process reuse and forced-kill recovery). They start fixture servers on port 8769 and write normalized responses under `test-results/`. Record the executable and version, and distinguish unavailable tooling (`PREREQUISITE_UNAVAILABLE`) from a code failure. Do not claim support from a mocked server alone.
 
 Known, documented limitations are not failures: `workspace/symbol` for TypeScript, Python, and C/C++ only sees files the server has been told about, and a fresh `clangd` process does not find cross-file references. The acceptance specs encode these as informational (TypeScript, C/C++) or skipped (Python) stages; do not "fix" them by weakening an assertion for another language.
 
@@ -26,6 +26,7 @@ Each language's three subcommands run against a real fixture and the real server
 - `go`: a real `go.mod`-rooted module and `gopls` (`--gopls <path>`).
 - `java`: a real Eclipse `.project`/`.classpath` fixture and jdtls (`--java <jdtls install directory>`, a directory and not an executable, matching `[java].path`; `$LCI_ACCEPTANCE_JDTLS` sets the same directory for repeated local runs).
 - `c` and `cpp`: real standalone C/C++ fixtures and one shared `clangd` (`--clangd <path>`, for each).
+- `markdown`: two real documents (prose indexing on) and `marksman` (`--marksman <path>`, or `$LCI_ACCEPTANCE_MARKSMAN`); only `markdown-lsp` (heading symbols, a link definition, references to a heading) and `markdown-missing` exist.
 
 All of them skip gracefully when their server is not found. Prerequisites per tool: `docs/development/live-acceptance-ci.md` "Prerequisites".
 

.agents/skills/lci-release-validation/references/validation-matrix.md

@@ -9,7 +9,7 @@ Choose rows affected by the change; a release candidate should cover the full ma
 | Persistence | temporary LanceDB, manifest compatibility, restart reuse, failed-update preservation (`--suite Indexing`, `--suite Watching`) | external data directory survives process restart |
 | Retrieval | mock semantic/lexical/LSP/fusion/reranker and filter coverage (`--suite Filter`, `--suite Evaluation`) | `evaluate ./evaluations/core.toml` against 8766/8767 with auditable source results |
 | Languages | parser/chunk/update/delete/restart tests per adapter (`--suite Chunk`, `--suite Indexing`) | `cargo xtask acceptance multilingual`; production-versus-decoy query per added language |
-| LSP | protocol/lifecycle/location tests (`--suite Lsp`) | `cargo xtask acceptance <lang>-lsp` / `-missing` / `-recovery` per language |
+| LSP | protocol/lifecycle/location tests (`--suite Lsp`) | `cargo xtask acceptance <lang>-lsp` / `-missing` / `-recovery` per language (markdown: no `-recovery`) |
 | Windows tools | resolver unit/integration tests | resolved `rg.exe`, optional language-server executables |
 | Packaging | staged-file and artifact scan | clean extraction and smoke test when distributing |
 

.agents/skills/lci-retrieval-evaluation/references/evaluation-workflow.md

@@ -32,7 +32,7 @@ Scope: the embedder-plus-reranker sets (`evaluations/core.toml`, the mined sets)
 
 ## Replaying a dump instead of running live
 
-For a live service rather than an evaluation run, `LCI_CANDIDATE_DUMP=<file>` (README) appends the same pool per search to a JSON Lines file.
+For a live service rather than an evaluation run, `LCI_CANDIDATE_DUMP=<file>` ([retrieval reference](../../../../docs/reference/retrieval.md), "Offline scoring") appends the same pool per search to a JSON Lines file.
 
 `evaluate --dump-candidates` records every query's whole fused candidate pool, the dumped configuration (`arm`), and the reranker's scores; `<bin> replay dump.json --output <file> [options]` then scores other settings from that file in seconds, offline (no services, config, or index), through the unchanged metrics. Its output is an evaluate-shaped report, so `<bin> compare dump.json <file>` pairs it with real reports and with other replays. Run one dump live; replay the grid.
 

.github/instructions/documentation.instructions.md

@@ -1,7 +1,7 @@
 ---
 name: LCI documentation
-description: Accuracy rules for README, evaluation definitions, configuration examples, and MCP descriptions.
-applyTo: "{README.md,config.example.toml,evaluations/**/*,src/server.rs}"
+description: Accuracy rules for README, the docs/reference guides, evaluation definitions, configuration examples, and MCP descriptions.
+applyTo: "{README.md,docs/reference/*.md,config.example.toml,evaluations/**/*,src/server.rs}"
 ---
 
 - Describe current behavior and independently verified evidence. Label unavailable live prerequisites and fail-open fallbacks precisely.

.github/instructions/rust-code.instructions.md

@@ -4,7 +4,7 @@ description: Architectural and implementation rules for Rust source in local-cod
 applyTo: "{src/**/*.rs,lci-core/src/**/*.rs}"
 ---
 
-- Keep client-neutral behavior in the Rust service. Do not import editor, Copilot, Kilo, or generation-model concerns. Keep tracing on stderr and structured CLI JSON on stdout.
+- Keep client-neutral behavior in the Rust service. Do not import editor, client, or generation-model concerns. Keep tracing on stderr and structured CLI JSON on stdout.
 - Use the existing module boundaries: configuration/workspace identity, language/chunk/manifest, models, store, LSP, filtering/evaluation, application coordination, and MCP/HTTP transport.
 - The workspace has four crates, split along dependency lines: `lci-core` (chunk, language, filter, lexical, manifest, workspace, config, models, lsp; no LanceDB/arrow, compiles and tests in seconds), `lci-maps`, `xtask`, and the root crate (app, evaluate, init, rest, server, store, main). Put new pure-logic code (a language adapter, a filter rule, an LSP adapter) in `lci-core` unless it needs `Store`/`App`. Never add a `lci-core -> local-code-intelligence` dependency edge.
 - Preserve external storage boundaries and per-workspace coordination. Never hold a workspace read guard while entering an indexing path that needs its write guard.