docs(knowledge-pages): document Knowledge Pages and Mental Models, and manage them from the CLI

[nicoloboschi]

Knowledge Pages shipped in #2455 with no documentation at all — no architecture page, no API page, not even a sidebar entry. Mental models had an API page but nothing explaining what they are or why an application would reach for one. This adds both, as top-level entries under Architecture and API, and closes the CLI gap the docs exposed.

Docs

Architecture → Mental Models (new) — a standing answer to a question you define, built in the background so the application reads the current version instead of paying for retrieval and synthesis on the request path. Covers the mental model / observation / raw fact ladder that reflect walks, freshness, scope isolation, and provenance. Deliberately conceptual — the flags live in the API page.

Architecture → Knowledge Pages (new) — pages are mental models with the mechanics pre-decided, so nobody has to think about synthesis scope to keep a wiki. Covers the folder hierarchy, the hindsight fs filesystem projection, page-level search, and a "why not just raw files?" section: a page is a projected view over memory that has already deduplicated and reconciled contradictions, so an amended decision reads as the current one instead of two paragraphs disagreeing.

API → Knowledge Pages (new) — the full endpoint surface with Python / Node.js / CLI / Go examples, the page defaults and what each one buys, staleness gating, what a refresh actually reads, and the storage split.

API → Mental Models — the trigger settings table gained the seven options it was missing (fact_types, exclude_mental_models, exclude_mental_model_ids, include_chunks, recall_max_tokens, recall_chunks_max_tokens), plus new sections on staleness gating, what a refresh reads, and how delta mode edits a structured document rather than regenerating prose.

FAQ — new entry on mental model vs knowledge page. Also corrects the neighbouring answer, which described mental models as "automatically built during retain" — that describes observations.

Clients

The API examples use the maintained clients like every other API page, which meant the knowledge-base surface had to exist in each of them.

Python + TypeScript wrappers, kept at parity: get_knowledge_base_tree · create_knowledge_folder · create_knowledge_page · get_knowledge_page · search_knowledge_base · update_knowledge_node · delete_knowledge_node · export_knowledge_base. update_knowledge_node only serializes the arguments the caller passed — the server treats an absent field as "leave alone" but an explicit null parent_id as "move to the root", and passing every field through would make those indistinguishable. Request-mapping regression tests cover this on both sides.

Rust CLI — hindsight knowledge-base with tree, create-folder, create-page, get-page, search, update, delete, export. All eight endpoints were previously listed as deliberate skips in .openapi-coverage.toml ("managed in the control plane UI, not the end-user CLI"); those are removed, so cli-coverage-check now enforces the surface. create-page sends no trigger unless --mode or --fact-types is given, so the server's page defaults stand — and when either is given the whole trigger is restated, because a supplied trigger replaces the defaults rather than merging.

Runnable Python / Node / CLI / Go examples added under hindsight-docs/examples/api/, and a Knowledge Base section added to the CLI reference.

Verification

• All eight CLI commands exercised end-to-end against a running API (create folder → create page → tree → get-page → search → update → export → delete), on a scratch bank that was removed afterwards
• cli-coverage-check passes: all 84 operations and 108 request params covered
• cargo test 118 passed; new unit tests for the --fact-types / --mode parsers
• docusaurus build passes; no broken links or anchors from the new pages (the two reported are pre-existing in a 0.5.5 blog post)
• ./scripts/hooks/lint.sh clean; check-unused.sh clean
• Python wrapper suite 96 passed; TypeScript wrapper suites pass
• skills/hindsight-docs mirror regenerated, link validation passes

Notes, not addressed here

• client-coverage-check reports reflect.apply_all_directives missing from both wrappers — introduced by feat(reflect): add apply_all_directives to bypass directive tag scoping (#3031) #3046 and unrelated to this change. That check is not wired into CI.
• New pages exist only in the unreleased docs version, so links to them from non-versioned pages (the FAQ) point at the released API page instead. Worth revisiting when the next version is cut.