PR A: align v5 docs and generated instructions

[ohjonathan]

Summary

PR A closes the documentation-accuracy slice of the audit-remediation tail from origin/main@bbbad203ee826a1994f609890e6a70fb7dbe7a34.

• Rewrites the Agent Instructions and Manual against the shipped v5 command registry, global flags, typed .ontos.toml surface, migration, MCP, hooks, and upgrade workflows.
• Adds an indexed architecture reference covering package boundaries, dispatch, document-to-map/MCP flow, safe writes, extension points, testing, and generated-artifact policy.
• Fixes the generated quick-reference query to ontos query --depends-on <id> and regenerates AGENTS.md, .cursorrules, and CLAUDE.md through Ontos while preserving USER CUSTOM content.
• Makes Recent Activity summaries useful and deterministic: explicit summary, first substantive body paragraph, then No summary, capped at 200 characters and ordered by date/created/ID.
• Begins the inherited generated-artifact cleanup by making timestamp-only instruction updates semantic no-ops, avoiding unnecessary backups, and marking only the context map as generated.

This is user-visible but non-breaking patch work. It does not change package metadata or perform any release action.

Findings implemented

• D8-docs-clarity-1
• D8-docs-clarity-2
• D8-docs-clarity-3
• D8-docs-clarity-4
• D8-docs-clarity-5
• D8-docs-clarity-6
• D8-docs-clarity-8
• Inherited D5a-repo-redundancy-7 PR A slice

Relates to #148 and #149. Their checkboxes/closure remain gated on merge and independent verification.

Verification

• 163 focused regressions passed.
• Final complete run: 1,572 passed; the sole failure was the pre-existing WAL/SHM isolation flake in test_read_only_portfolio_queries_existing_snapshot_without_mutation. That exact test passes alone. The Phase 0 review accepted this as non-blocking and assigned its natural fix to PR C.
• Ontos activation: usable, 213/213 documents, zero validation warnings.
• Ontos doctor: 10 passed, 0 failed; only the existing non-Ontos-hook and stale PATH-CLI warnings.
• Ontos link-check: clean.
• llm-dev manifest conformance, review seats, scope, cardinality, branch, and staged-snapshot gates passed.
• Repeated forced instruction export reports all artifacts unchanged with stable hashes and no new backups; repeated map generation is hash-stable.
• git diff --check passed.
• Independent final integration audit found no blockers or later-phase scope drift.

Review and residuals

• Draft only: strict external llm-dev lifecycle reviews and CI are pending.
• PR C retains activation-writer routing and the WAL/SHM test-tail fix.
• PR D must revise the manual when it changes the currently shipped portfolio defaults and 15/20 consolidate-retention discrepancy.
• No merge, version bump, tag, PyPI upload, or issue closure is performed here.

[ohjonathan]

PR A review — Claude — approve to merge (no blockers, no majors)

Verified every claim independently against a fresh worktree at the PR head (0a7671c) with a real venv — not the summary report.

All 7 D8-docs-clarity findings correctly implemented + behaviorally verified

• D8-2 (the user-visible payoff). All three generated artifacts (AGENTS.md/CLAUDE.md/.cursorrules) now ship ontos query --depends-on <id> and zero ontos query <id>. Confirmed --depends-on is a real flag (cli.py:745, query.py:237). USER CUSTOM sections preserved.
• D8-4. Recent Activity now renders real one-line summaries (explicit summary → first substantive body paragraph → No summary; HTML-comment/heading/rule/placeholder aware; 200-char cap + ... truncation) where every row previously read "No summary". Regeneration is hash-stable (idempotent — no churn). _log_date_sort_key was also reworked date→created→ID (adjacent improvement; golden baselines updated to match).
• D8-1/3/5. Docs accuracy holds: extracted every ontos <cmd> invocation from the rewrites and cross-checked against the live v5 CLI. Every command form is valid; all known-broken v4-era commands are gone (log --enhance, ontos update, bare migrate --check, map --include-rejected, ontos_verify.py, ontos_end_session.py, the v2.9.4 curl installer); schema-migrate --check, consolidate --by-age, and ontos hook pre-commit are the correct forms.
• D8-6/8. docs/reference/Architecture.md added + registered in the graph; CLAUDE.md regenerated to the real v5 protocol.

Mechanical health

• CI green (3.9/3.10/3.11 + non-editable + v5-release-gates; 3.12 pending at review time).
• 114 focused tests pass locally.
• The WAL/SHM isolation flake is provably main's, not this PR's — the diff touches zero bytes of tests/mcp/test_portfolio.py and ontos/mcp/portfolio.py. Its fix stays assigned to PR C.

Two notes (neither a blocker)

1. Scope expansion accepted. The PR pulls a D5a-repo-redundancy-7 slice forward (instruction_artifacts.py: idempotent writes, backup-only-on-change, .cursorrules USER CUSTOM preservation, and a genuine created-flag correctness fix — created now means created, not processed). Well-tested and strictly safer, and it's what keeps PR A's own artifact regeneration from being churny. Bookkeeping ask: record D5a-repo-redundancy-7 as addressed here so PR B's dead-code scope stays accurate.
2. Honest residuals the PR declares. D8-4 is solved via the map.py fallback; having ontos log/session_end write a summary: field at log-time is deferred to PR C. A 15-vs-20 consolidate-retention doc/behavior mismatch is flagged for PR D to reconcile. Both are legitimate forward-references.

Verdict: no blockers, no majors — ready to merge as a v5.0.1-track patch. Release actions remain maintainer-deferred.

(Mild recurring note, same as #166: the full lifecycle packet — spec + tracker + manifest + session log — is heavier than a docs-accuracy patch needs; harmless, and already captured upstream as llm-dev-framework#214.)