docs: overhaul the README and restructure the docs tree (#957)

* docs: overhaul the README and restructure the docs tree

The README led with code health and buried everything else, so a reader who
did not care about a health score had little reason to keep reading. It now
leads with the outcome (your agent stops rediscovering the codebase) and gives
the agent surface, distillation, change risk, the dashboard, workspaces and
worktrees the same weight as health, which stays the deepest layer but is no
longer the whole pitch.

New composite hero (.github/assets/one-index.svg, plus a dark variant selected
via prefers-color-scheme) generated by scripts/gen_readme_hero.py from the
resolved theme tokens. Four dashboard GIFs compressed with ffmpeg to under 2MB
each, down from 17MB and 30MB originals, since the repo has no git-lfs and
every byte is permanent clone weight.

docs/ moves from 23 flat files into start/, layers/, agent/, scale/,
reference/ and business/, with CHANGELOG.md kept at the root because the
bundled-copy drift guard and several links depend on that path. All 251
inbound references were rewritten by resolving each link against its old
location and re-emitting it relative to the new one; recorded test fixtures
were left byte-identical on purpose.

Seven new docs: BENCHMARKS.md (so the README carries a teaser rather than
three studies), plus DASHBOARD, DECISIONS, DEAD_CODE, TEST_INTELLIGENCE,
BUG_HISTORY and SECURITY_COMPLIANCE, which covered shipped features that had
no documentation at all. Each benchmark and the bug-history doc carries a
"what this does not show" section; BUG_HISTORY documents the SZZ work that was
measured at 74.5% precision and deliberately not shipped to any UI.

Corrects counts that had drifted: 16 parsed languages and 11 at the Full tier
(was 15/9 in five places), and ten MCP tools (COMMERCIAL.md and two others
still said nine). Benchmark-scope "9 languages" references are left alone.
Also fixes two long-broken relative links and the "zero telemetry" claim in
COMMERCIAL.md, which contradicted TELEMETRY.md.

* docs: drop the parity claim from the README, fix two stale references

"answer quality at parity" reads as a hedge rather than a result, so the
headline stat is now just the three reductions. The caveat stays in
BENCHMARKS.md where the methodology is being described.

Also: `repowise coverage status` pointed at `repowise coverage contexts`, a
command that does not exist, so its two hint lines now name the real path
(`coverage run --contexts=test` then `repowise coverage add .coverage`).
INTELLIGENCE_LAYERS.md called the evidence tiers "verified / fuzzy /
unverified" where the extractor stamps "exact".

* docs: rewrite the quickstart, and stop documenting provider extras that do not exist

`pip install "repowise[anthropic]"` was documented in five places and has never
worked: the only extras in pyproject.toml are postgres, graph-extra and dev.
pip treats an unknown extra as a warning, not an error, so this installed the
base package and looked like it worked, which is worse. All four provider SDKs
(anthropic, openai, google-genai, litellm) are base dependencies already, so
`pip install repowise` is the complete install.

The USER_GUIDE troubleshooting entry for "Provider X requires the Y package"
was pointing at the same non-existent extras. The error is real, but it names
the package it wants and the fix is a plain `pip install <package>` or a
reinstall, so it now says that.

Quickstart is reordered around what a new user actually needs. It used to open
with picking a provider extra and exporting an API key, which is friction
before any payoff. It now goes install, index with no key, connect your agent
and ask it something, and only then offers a provider for the wiki and semantic
search. Adds the verification steps that were missing (what to run to confirm
the index works, which tools work without a key, and `repowise doctor` when it
does not), and drops the fixed "5-15 minutes" estimate in favour of pointing at
the cost estimate `init` already shows before it spends anything.

Also lists which MCP tools work in index-only mode, verified against the tools
themselves rather than inferred: get_symbol, get_risk, get_change_risk,
get_dead_code and get_health hold no WikiPage references, so they need no
provider.

* docs: collapse the user guide down to a guide

It had grown into a second CLI reference. About 520 of its 1080 lines
re-documented every command and flag alongside docs/reference/CLI_REFERENCE.md,
and the rest restated the dashboard, hooks, distill, auto-sync and env-var docs.
Two copies of the same reference is how the phantom `repowise[anthropic]` extra
survived in both files at once.

Now 448 lines, and it reads as a guide: the mental model (index, ask, keep
fresh, and why a stale index is the thing to avoid), what the commands are for
grouped by intent rather than enumerated with flags, and then the two sections
that were always the unique value here, common workflows and troubleshooting,
both expanded. Reference material points at the file that owns it.

New workflows for things people actually do and previously had to work out for
themselves: what to run before opening a PR, reviewing someone else's branch,
onboarding, CI, and cutting cost on a large repo. Troubleshooting leads with
`repowise doctor` and gains an entry for the agent answering from a stale index.

The CORS entry assumed you run the frontend separately, which stopped being true
when `repowise serve` started running the API and dashboard together. It now
covers the case where that is actually possible, running a frontend from source
against a different REPOWISE_API_URL.

No inbound link deep-links into a removed section, and no anchors break.

Author: RaghavChamadiya

.github/CONTRIBUTING.md

@@ -109,10 +109,10 @@ repowise/
 
 5. **Add tests** in `tests/unit/test_providers/` — mock the subprocess, test success/error/timeout paths (see `test_codex_cli_provider.py` for the pattern)
 
-6. **Write docs** — `docs/<NAME>.md` and `website/<name>.md`, following `docs/CODEX.md` and `docs/OPENCODE.md`.
+6. **Write docs** — `docs/<NAME>.md` and `website/<name>.md`, following `docs/agent/CODEX.md` and `docs/agent/OPENCODE.md`.
 
 Adding a new language or LLM provider has a dedicated recipe — see
-[docs/LANGUAGE_SUPPORT.md](../docs/LANGUAGE_SUPPORT.md).
+[docs/layers/LANGUAGE_SUPPORT.md](../docs/layers/LANGUAGE_SUPPORT.md).
 
 ## Testing