docs: complete brownfield reference documentation

[aksOps]

Summary

User-requested full reference-doc set ahead of stopping codeiq work with Claude Code. Replaces the doc-wipe slate (PR #168) with a coherent, source-grounded reference tree.

Files created (15 / ~2,200 lines / ~180 KB)

File	Topic
`README.md`	User-facing entry + for-the-badge style badges
`CLAUDE.md`	Agent-facing repo guide (architecture rules + gotchas + how-to-add-a-detector)
`docs/00-project-overview.md`	What it is, who it's for, current production-ready vs experimental surface
`docs/01-local-setup.md`	Prereqs, build/test/run, common setup issues
`docs/02-architecture.md`	Component map + data flow + 8-row tradeoff table
`docs/03-code-map.md`	Directory-by-directory tour of every package
`docs/04-main-flows.md`	index / enrich / mcp / review entry points + failure modes
`docs/05-configuration.md`	Persistent flags + per-subcommand flags + env + config files + safe defaults
`docs/06-data-model.md`	Kuzu `CodeNode` table + 28 REL tables + SQLite cache schema + canonical NodeKind/EdgeKind taxonomy
`docs/07-integrations.md`	Only Ollama + Sigstore — everything else explicitly NOT integrated
`docs/08-testing.md`	884+ tests, fixtures, perf-gate, gaps
`docs/09-build-deploy-release.md`	Goreleaser + cosign keyless + verification commands
`docs/10-known-risks-and-todos.md`	Gotchas / debt / security-sensitive surfaces / migration risks
`docs/11-agent-handoff.md`	20-line summary + top 20 files + commands-to-use + commands-to-avoid
`docs/adr/0001-current-architecture.md`	Retrospective ADR for today's architecture

Grounding policy

Every concrete claim references a file (`internal/cli/root.go`, `internal/graph/mutation.go`, etc.) so a future reader can verify in seconds. Anything not directly verified is marked Inference. Anything unknown is marked Unknown.

Most important findings (also covered in the docs)

1. Detector registration choke point at `internal/cli/detectors_register.go`. Forget the blank import → empty registry. Caught the most production bugs in Phase 4.
2. Mutation gate is regex-based at `internal/graph/mutation.go`. Allow-listed CALL prefixes now include `query_fts_index` for FTS reads. Adversarial inputs may bypass; fuzzing recommended.
3. CSV bulk-load uses `DELIM='|', QUOTE='"', ESCAPE='"'` after three production bugs (comma, pipe, quote). Any future structured-output channel must verify quoting end-to-end.
4. Service IDs are path-qualified (`service::`) post-PR fix(analyzer): path-qualify SERVICE node IDs to break PK collisions #151. Future "container" node types need the same discipline.
5. proxy.golang.org caches version content immutably — deleted tags can never be re-used. Any new release must move forward (next is v0.4.2 once PR fix(release): make README.md / CHANGELOG.md optional in archive bundling #169 lands).

Biggest risks (from docs/10-known-risks-and-todos.md)

• Detector blank-import being forgotten silently.
• Mutation gate bypass via comment/string smuggling.
• Tree-sitter grammar drift breaking pattern-matching detectors.
• Kuzu on-disk format change across minor versions (mitigated: graph is rebuildable from SQLite cache).

Unclear areas (Inference / Unknown markers)

• `internal/review/client.go` Ollama env variables — `OLLAMA_API_KEY` is verified; `OLLAMA_HOST` etc. marked Unknown pending source-level verification.
• `internal/cache/inspect.go` `snippet` column purpose — marked Inference.
• `internal/mcp/tools_graph.go` `read_file` exact path-sandbox mechanism — marked Inference; recommend a focused fuzz test.
• `docs/codeiq.yml.example` was deleted in docs: wipe all documentation for clean reference-docs rewrite #168 — the YAML config loader is referenced in the root `--config` flag help but the schema isn't formally documented.

Recommended next documentation pass

1. Inline doc-comment audit — many `internal/` packages have rich Go doc comments. A `godoc`-style auto-extracted reference would complement the prose docs without duplicating effort.
2. Per-detector matrix — auto-generated table of all 100 detectors with name, languages, default confidence, and emission examples. Could come from `codeiq plugins list --json`.
3. MCP tool reference — formal JSON-schema for each of the 10 tools' arguments. The schemas exist in code (`Tool.Schema json.RawMessage`); just unloaded for docs.
4. An ADR for each major decision after 0001 — e.g. "ADR 0002: Kuzu 0.7.1 → 0.11.3", "ADR 0003: stdio MCP over alternatives".

Test plan

• No source code touched; full test suite unaffected.
• Doc structure matches the user's specified layout.
• Every claim grounded in source or marked Inference/Unknown.
• After merge: README renders correctly on GitHub home page.

🤖 Generated with Claude Code