Docs: top-level index + troubleshooting

[noeljackson]

Why

docs/ has 15+ files now: writing-matchers, writing-ast-matchers, bench-task-format, refreshing-grammars, bake-off, ci-integration, compliance-reporting, agentic-tools, auto-learn-loop, bounded-patch-agent, juice-shop-validation, external-comparison, bench-corpus-brief, bench-corpus-critique, etc. A new visitor has no map.

What lands

docs/index.md

A one-page navigation map organized by user intent:

• Start here: install, quickstart, deepsec doctor
• Day-to-day: scan, process, report, patch
• CI integration: --fail-on, pre-commit, GitHub Actions
• Compliance: SOC2 / SSDF formats, signing
• Authoring: matchers, AST patterns, bench tasks
• Operating: troubleshooting, spend, configuration
• Internals: architecture, RFCs, refreshing grammars
• Evidence: Juice Shop validation, external-scanner comparison, bench critique

docs/troubleshooting.md

The "things go wrong" doc that pairs with the deepsec doctor issue:

• "0 candidates" — gating diagnosis
• "AI investigation refused" — provider/key checks
• "AST grammar failed to load" — version + libc imports
• "go build failed in CI" — Go version mismatch (1.25.10 required)
• "docker build-grammar-wasm.sh permission denied" — /tmp noexec workaround
• "ensemble: agent produced 0 findings" — provider auth (Coding-Plan vs paid endpoint)

Each entry: symptom → check → fix.

Cross-linking

Every existing doc gets a one-line "see also" at the bottom pointing at index.md.

Acceptance

• docs/index.md and docs/troubleshooting.md checked in.
• README links to both.
• The docs/ folder no longer feels like an unsorted drawer.