docs: README visibility overhaul — problem-first hook, dashboard hero, MCP quickstart

[TheAmericanMaker]

What

The product has real adoption (~1,800 npm installs/month) but almost no social signal (1 GitHub star). People install and leave without starring or talking about it. This PR closes the discoverability + conversion gap — it is a marketing problem, not a quality problem.

Changes

• README opening rewritten for the 5-second test: leads with the problem (understand an unfamiliar codebase + get a validated spec), drops "cartography" from line 1, names supported agents (Pi, Claude Code, Cursor, Codex, MCP) up front.
• Dashboard hero screenshot added (docs/demo-dashboard-hero.png). Generated from a hand-authored demo workspace via the real writeDashboard() renderer — no LLM run needed. Build script: scripts/build-demo-dashboard.mjs (output gitignored except the hero PNG).
• "Why CodeCartographer" section: filesystem-as-memory, validated phases, spec-not-chatlog output. The three things that differentiate from "just prompt the LLM to analyze the repo."
• Star nudge near the top: "If CodeCartographer saves you a day of codebase archaeology, star the repo."
• docs/mcp-quickstart.md: 30-second setup for Claude Code, Cursor, Codex, Claude Desktop, opencode. Linked prominently from the README install section.
• .gitignore: demo workspace + non-hero screenshots gitignored as build artifacts.

Review fixes (second pass)

The first draft of docs/mcp-quickstart.md shipped wrong setup instructions for 4 of the 5 agents it documents. Since this doc is the conversion path for the whole PR, every path was re-verified against vendor sources and the local machine:

Agent	Was documented	Actually
Claude Code	~/.config/claude-code/config.json	path does not exist — now uses claude mcp add, or a project-root .mcp.json
Cursor	~/.cursor/config.json	~/.cursor/mcp.json
Codex	~/.codex/config.json (JSON)	~/.codex/config.toml (TOML, [mcp_servers.*])
opencode	config.json + mcpServers	opencode.json + "mcp" key, type: local, command as an array
Claude Desktop	correct	unchanged

Also fixed: Step 1 told users to run codecarto-mcp --version, which is not a supported flag. The bin has no argv handling, so it starts the stdio server and blocks — a new user's first command was a frozen terminal. Replaced with which codecarto-mcp plus a note explaining why running it directly appears to hang.

docs/visibility-roadmap.md is no longer included. It is an internal planning note — it states the current star/fork counts, calls out the lack of social signal, and lays out where to post. Publishing that to the audience it describes, in the repo whose perception it is trying to improve, is self-defeating. It is now gitignored and kept locally as a working document. Nothing linked to it.

Verification

• Tests: 270/270 pass
• Build: tsc clean
• Doc-mention test: passes

Depends on

CI on this branch fails on the npm audit --omit=dev --audit-level=high step, which has been failing on main and is unrelated to this PR's content. #78 fixes it. Merge #78 first, then update this branch and CI should go green.

Not in this PR (done separately / needs user)

• GitHub repo topics updated via gh repo edit (already applied to the repo, not a commit): added codebase, ai-agent, context-engineering, code-understanding, spec-driven (was 7 topics, now 12).
• Real LLM-backed analysis run + case study (needs user sign-off on token cost)
• codecarto.dev homepage content (needs user to point at hosting)
• Demo video (needs interactive Pi session)

Hero screenshot was rendering broken data

The committed hero showed 0 recorded tokens, 0 tool uses, and defect-scan-mechanical as PENDING — while its own alt text claimed completed phases and per-phase telemetry. Three bugs in scripts/build-demo-dashboard.mjs, all from demo data not matching the real pipeline contract:

• Phase ids — status.yaml said defect-scan-mech; the shipped pipeline declares defect-scan-mechanical, so the phase never matched and rendered pending.
• Primary outputs — the script wrote architecture.md / defect-scan/defects.md; the pipeline declares architecture-map.md / defect-scan-mechanical/mechanical-defects.md. Missing primary outputs raised spurious blockers.
• Usage log — loadUsage expects {version, runs: [...]} with status completed|aborted|error. The script emitted a bare top-level list with complete/in-progress, so every entry failed isUsageRun() and was silently dropped. Hence the zeros.

Hero now renders 3.43M tokens, 167 tool uses, 11m33s, and both completed phases.

The dashboard still reads "Attention Required" because the active contracts phase has not yet written its artifact — that is the honest mid-run state, and any mid-run screenshot will show it. Worth a separate call on whether the hero should instead depict a finished run.

Also fixed: the quickstart's "What you get" list documented six output paths that do not exist. All seven now match primary_output in pipeline-full-with-deep-audit.yaml.