#458 docs: rewrite README and docs/ for accuracy and voice; split README into guides

[Anonymous]

Originally created by: fu351

What

A full accuracy + voice pass over the public docs, and the README split so it reads as a front door. These files are also the source the new documentation site (docs.trydoberman.dev, served from the landing project) renders from.

• README.md 6,893 → 3,518 words. Keeps: why, quick start (agent table, install, setup), verify end-to-end, who it's for, roadmap link + the full Known limitations list, contributing, license. Deep sections moved out:
• docs/TUNING.md (new): modes, enforcement dial, default role, prefs, tune, message-tone
• docs/PLUGINS.md (new): custom guardrail + webhook audit sink via entry points
• docs/RECOVERY.md (new): taint clear, tools approve, memory reset/prune, uninstall / uninstall-hooks
• docs/TURN_GATE.md (new): the README turn-gate section plus the module map and invariants
• docs/CLI.md: now covers all 37 commands/subcommands (the 2fa group, uninstall, message-tone, tools approve were undocumented); exit-code collision audit corrected to the real count (45); JSON-contract sections re-verified against cli/main.py and cli/doctor.py.
• docs/REASON_CODES.md: header 56 → 57 (matches the enum); five raise-site columns corrected (secret_exfiltration, multi_step_exfil, confirmed_exfil → hosthooks/hookio.py; correlated_trifecta, correlated_destructive_flow → engine/correlator.py); redundant Value column dropped; plan-chip group names replaced with subsystem names.
• docs/SETUP.md 3,618 → 2,815 words; the three README-linked anchors (Claude Code hooks, MCP proxy, OpenClaw) kept verbatim.
• docs/RELEASING.md is now the one release doc (root RELEASING.md is a pointer); the sdist file list now matches pyproject.toml (tools/ was missing). CHANGELOG.md/SECURITY.md links updated to the new anchor location.
• docs/audit_otel.md: failed POSTs are logged at warning, not debug (checked against otel_sink.py).
• docs/PARITY.md prose only; tools/parity/generate_parity.py header strings updated so --check stays byte-identical.
• docs/ADAPTER_GUIDE.md, adapters/openclaw/README.md, CONTRIBUTING.md, docs/BENCHMARKS.md: voice pass; every number and command kept or verified.

Ground truth for every command and flag was a full --help dump of every command from src/ at v0.18.1. No claim was kept that could not be traced to code or help text.

Ordering note (ADR 0080)

[#447] (docs/CLI.md) and [#414] (README.md, docs/SETUP.md) touch files rewritten here and are already conflicting with main. Whichever lands second needs its doc delta re-applied by hand; this PR is not merged by the session that opened it.

Test plan

• [x] pytest tests/unit/test_markdown_links.py tests/unit/test_reason_codes_documented.py tests/unit/test_parity_matrix.py tests/unit/test_cli_scan_json.py — 71 passed
• [x] python scripts/check_markdown_links.py --root . — 51 files, no broken links
• [x] python -m tools.parity.generate_parity --check — exit 0
• [ ] CI green (docs-only change; the full matrix still runs)

Update (2026-08-25, second commit)

• Repo URLs now point at DobermanCore/Doberman-Core (README badges and images, CONTRIBUTING, SECURITY, CHANGELOG, PARITY via its generator, pyproject [project.urls], issue template, codex plugin manifest). Old fu351/ URLs redirect.
• ci.yml forwards GITLEAKS_LICENSE to gitleaks-action, which organization repos require. secret-scan stays red until the GITLEAKS_LICENSE repository secret exists; then re-run the failed job.
• Merge plan (fu351, 2026-08-25): merge this PR first; when [#447] and [#414] land, re-apply their doc deltas by hand (--quiet row for doberman demo in docs/CLI.md; the global-hook exclusion section in README / docs/SETUP.md).

[Anonymous]

Ticket changed by: fu351

• status: open --> closed