Documentation and landing page audit ahead of release

[AliRezaTaleghani]

Docs-only accuracy audit ahead of the next release, ~24 PRs / 12 days since v0.1.17. Cross-checked every file in docs/NexusContext-Wiki/, docs/index.html, README.md, and INSTALL.md against the real current code (crates/nexusd/src/tools.rs's tool_definitions(), crates/nexus-cli/src/main.rs, crates/nexus-core/src/config.rs/paths.rs).

What was wrong/missing, per file

README.md — the biggest finding. Sections 1-3 (Architecture Overview, Component Breakdown, Technical Stack) still described the removed embeddings/semantic-search subsystem, a never-actually-built LanceDB vector store, and search_codebase/query_memory tools that no longer exist, presented as current architecture rather than history. Rewrote all three sections to describe the real current system: graph-first with optional Rust-only LSP enrichment, the actual 12-tool MCP surface, this cycle's resource bounds (watcher channel bound, traversal depth cap, MAX_INDEXABLE_FILE_BYTES, query timeout), allowed_roots enforced uniformly, and correct Windows/macOS/Linux platform tiering. Added a note at the top clarifying that section 4 (the phase-by-phase build log) is intentionally frozen history and legitimately keeps old references — left untouched, per the doc-drift test's own stated scoping. Sections 5-6 were already accurate.

INSTALL.md — missing NEXUS_CONFIG_DIR from the env-var-overrides line (only NEXUS_CACHE_DIR was listed). Added.

docs/NexusContext-Wiki/Configuration.md — the allowed_roots inline comment only named 4 gated tools (index_repository/reindex/get_file_context/detect_changes), stale from before issue #61 extended enforcement to nearly every repo_path-accepting tool. Updated to list the real current coverage.

docs/NexusContext-Wiki/Known-Limitations.md — was missing the O_NOFOLLOW-is-defense-in-depth-not-full-TOCTOU-proofing gap (ADR 0015); it was only documented in Security-Model.md. Added a section here too, since this file is meant to be the single "what's really not handled" reference.

docs/NexusContext-Wiki/Security-Model.md — content was already accurate and current (dated through today), but reads as a patchwork of dated addenda as flagged in the task. Added a short orientation note at the top distinguishing the "current standing behavior" sections from the chronological review-pass log below them, without touching/reordering the substantive content (didn't want to risk breaking cross-references for a cosmetic reorg this close to release).

docs/index.html (landing page) — the "Hardened against its own audits" section had a leftover embeddings reference (the markdown-OOM fix was described as happening "during embedding", from before the subsystem was removed) and was missing this cycle's two biggest security findings entirely: the resource-bounds work (issue #58) and the symlink-substitution TOCTOU defense-in-depth (issue #72/ADR 0015). Fixed the wording and added both findings, stated with the same "here's the honest remaining gap" framing the wiki uses. Everything else on the page (tool count, tool list, language-support tiering, architecture diagram, benchmark section, version number, install instructions) was already accurate — no semantic-search/embeddings claims, no overclaiming on multi-language LSP support, benchmark section already presents mixed (2 win / 2 lose) results honestly.

Verified

• cargo build --workspace and cargo test --workspace: clean, no failures.
• tools::tests::doc_prose_tool_counts_match_the_real_tool_set (the doc-drift regression test that cross-checks tool counts in MCP-Tools.md/Configuration.md/Home.md/INSTALL.md/docs/index.html against the real tool_definitions()) passes.
• No .rs files touched.

Files reviewed, found already accurate — no changes made

MCP-Tools.md, CLI-Reference.md, Architecture.md, Home.md, Storage-and-Data-Model.md, Indexing-Pipeline.md, Language-Support.md, Watcher-and-Freshness.md, GUI-and-Extension.md, MCP-Surface-Evaluation.md, Product-Thesis-Validation.md, ADRs/README.md (its index matches all 15 ADR files on disk through 0015, confirmed by listing).

Honest gaps — what I did not fix

• A repo-wide case-insensitive grep for "embed" turned up only the expected: historical ADR references, README.md's frozen phase log (now clearly labeled as such), and accurate present-tense statements that embeddings were removed. Nothing live was missed as far as I can tell, but I did not exhaustively re-read every line of README.md's ~320-line Phase 1-33 roadmap section — I skimmed it for anything read as current rather than historical, and I'm reasonably but not 100% confident there's no stray "current-tense" embeddings sentence buried in there.
• Security-Model.md got an orientation note, not a structural rewrite — I judged a full reorg riskier than valuable this close to a release, given how many cross-references ([[...]] wikilinks and inline "see above") the existing chronological structure has. If a cleaner structure is wanted, it deserves its own pass with more room to verify nothing breaks.
• I did not attempt to update the landing page's benchmark section's underlying numbers (still v0.1.4) — it's a separate, already-labeled-honest benchmark from Product-Thesis-Validation.md's newer one, and the task's directive was specifically not to overclaim vs. [Architecture/Product] Validate NexusContext's core value as persistent structural memory for coding agents #57's findings, which this section doesn't do (it already states 2 losses alongside 2 wins).

https://claude.ai/code/session_01D6ND42psexN5cWTKewSpBG