docs: slim README and reconcile duplicated doc pairs

[BunsDev]

Context

• Summary: Slims the README from 908 to 714 lines by converting the three deep-detail sections (Commands Reference, Local API, Configuration) into short pointer tables backed by existing reference docs, and reconciles the duplicated/diverged doc pairs (GLOSSARY, API-CONTRACT, roadmap/harness-adapters stubs, MVP-PLAN historical banner, es/ru translation note).
• Files changed: README.md, docs/MVP-PLAN.md, docs/GLOSSARY.md, docs/reference/glossary.md, docs/API-CONTRACT.md, docs/reference/api-contract.md, docs/reference/harness-adapters.md, docs/reference/roadmap.md, docs/DOCS-MAINTENANCE.md
• Closes docs: slim README and reconcile duplicated doc pairs in place #447
• Stacked on docs: fix broken links and stale harness claims across entry-point docs #446 (merged as docs: fix broken links and stale harness claims in entry-point docs #453) — this is the second PR of the docs track.

Implementation

• Approach:
  • README slimming (908 → 714 lines). Identity/marketing sections (hero, badges, ecosystem table, MVP warning, What is Coven, Why Coven, Features, Requirements, Install, Quick Start, FAQ, Contributing, licensing/community) preserved intact. Slimmed bodies:
    • Commands Reference (~137 → ~33 lines): core-verb table with per-command links into docs/reference/cli-*.md; kept the unique-prefix note and the rituals table (identity content).
    • Local API (~91 → ~28 lines): contract summary pointing at docs/reference/api.md, docs/API.md, docs/API-CONTRACT.md; kept the curl handshake + 4-step negotiation checklist and error-envelope rule.
    • Configuration (~48 → ~16 lines): 3-row surface table pointing at docs/daemon/coven-home.md, docs/daemon/configuration.md, docs/SETTINGS.md; kept CI tip, retention pointer, never-commit rule.
    • Accuracy fixes while slimming: harness claims and install steps now include GitHub Copilot CLI (built-in harness id copilot, crates/coven-cli/src/harness.rs); authority-boundary allowlist line now reads (codex, claude, copilot).
  • docs/MVP-PLAN.md: historical banner under the H1 pointing at docs/ROADMAP.md + docs/reference/roadmap.md. Nothing else changed.
  • Stubs: docs/reference/harness-adapters.md and docs/reference/roadmap.md now point at their canonical pages (docs/HARNESS-ADAPTERS.md, docs/ROADMAP.md).
  • Diverged pairs: cross-reference banners added to both members of GLOSSARY / reference-glossary and API-CONTRACT / reference-api-contract identifying which is canonical/fuller. One outright contradiction fixed: docs/reference/api-contract.md claimed error codes are <dotted.code>; the daemon emits snake_case codes (session_not_found, … — crates/coven-cli/src/api.rs), matching docs/API-CONTRACT.md. No content merged or moved.
  • docs/DOCS-MAINTENANCE.md: new Translations section noting docs/es/docs/ru lag English (last synced ~2026-06-24) and English is authoritative.
  • Chunks deliberately kept in README (verified target docs before every cut): rituals semantics table, session-id unique-prefix note, curl health handshake + negotiation checklist, error-envelope rule, CI COVEN_HOME tip, never-commit-state rule. Everything cut is covered by the linked reference pages (verified per section).
• User-visible behavior: docs-only; README shorter with pointers into the docs site tree. No route/file moves — all edits in place.
• Compatibility notes: none (no code, no file renames; docs-site absolute routes untouched).

Verification

• python scripts/check-secrets.py — passed (no current-tree or history findings)
• git diff --check — clean
• node --test scripts/onboarding-docs-test.mjs — 13/13 pass
• cargo fmt/clippy/test — n/a, docs-only change
• Relative-link sweep over root + docs (skipping es/ru/dist): 0 broken relative links after the change.

Risk and Rollback

• Risk: low — docs-only, in-place edits. Worst case a pointer link is unclear; no information deleted that isn't covered by a linked doc.
• Rollback: revert the single squash commit.

Agent Handoff

• Claims issue-447 held for this work; release after merge.
• Follow-ups spotted (not in scope): docs/reference/cli.md "Current harness ids" line still omits copilot; --add-dir flag documented in HARNESS-ADAPTERS.md but missing from docs/reference/cli-run.md; es/ru translation sync pass pending (now documented in DOCS-MAINTENANCE.md); Windows CI flake tracked in flaky: threads_scheduler_recovers_veto_claimed_before_deadline times out its veto-deadline margin on windows-latest #455.

[Copilot]

Pull request overview

Docs-focused cleanup that makes README.md a slimmer entry point by replacing deep-detail sections with pointer tables into the existing docs/reference/* suite, while also adding “canonical/condensed” cross-links to reduce drift between duplicated doc pairs.

Changes:

• Slimmed README.md by replacing the Commands Reference / Local API / Configuration deep sections with short link-backed tables and pointers.
• Added canonical-content banners to stub reference pages (docs/reference/roadmap.md, docs/reference/harness-adapters.md) and added “see also” cross-links between duplicated docs (Glossary + API contract pairs).
• Added a historical banner to docs/MVP-PLAN.md and documented translation staleness policy in docs/DOCS-MAINTENANCE.md.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
README.md	Slims command/API/config sections into pointer tables; updates harness mentions to include GitHub Copilot CLI.
docs/MVP-PLAN.md	Adds a “historical doc” banner pointing to the current roadmap.
docs/GLOSSARY.md	Adds a cross-link banner to the condensed reference glossary.
docs/reference/glossary.md	Adds a cross-link banner back to the canonical repo-root glossary.
docs/API-CONTRACT.md	Adds a cross-link banner to the condensed reference contract page.
docs/reference/api-contract.md	Adds a cross-link banner to the full contract and fixes error-code placeholder to snake_case.
docs/reference/harness-adapters.md	Adds a canonical-content pointer to docs/HARNESS-ADAPTERS.md.
docs/reference/roadmap.md	Adds a canonical-content pointer to docs/ROADMAP.md.
docs/DOCS-MAINTENANCE.md	Adds a Translations section describing es/ru lag and English authority.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.