docs: restructure into navigable docs/ tree and add MCP user guide

[artyomsv]

Summary

Restructures project documentation so that the GitHub repo browser is easy to navigate and the headline MCP feature finally has a user-facing guide.

Before — 8 markdown files at the repo root totalling 2735 lines; the README alone was 307 lines covering Features + Architecture + Quick start + Configuration + Project Structure + Roadmap. No user-facing MCP guide existed (only a PRD in docs/roadmap/mcp-server.md).

After — 4 files at the root (the GitHub-conventional set: README, CHANGELOG, CONTRIBUTING, LICENSE), everything else under docs/ as a navigable tree. README is a 95-line landing page. New docs/mcp.md documents all 17 MCP tools with input schemas pulled directly from cmd/quil/mcp_tools.go, plus client wiring for Claude Desktop, Claude Code, Cursor, and VS Code Copilot.

Structure

quil/
├── README.md             95 lines — landing page only (was 307)
├── CHANGELOG.md          (unchanged — convention)
├── CONTRIBUTING.md       rewritten as a thin pointer page (was 119 lines of duplicated build info)
├── LICENSE
└── docs/
    ├── README.md         NEW — documentation index, github.com renders it on `docs/` click
    ├── installation.md   NEW — every install path + build-from-source
    ├── quick-start.md    NEW — first-launch walkthrough
    ├── features.md       NEW — capability tour grouped by area
    ├── keybindings.md    NEW — full keymap + customization
    ├── configuration.md  NEW — ~/.quil/config.toml reference
    ├── mcp.md            NEW — 317-line MCP user guide (the headline)
    ├── plugin-reference.md  (existing)
    ├── troubleshooting.md  NEW — daemon won't start, MCP not detected, log locations, reset
    ├── architecture.md   moved from root via git mv (history preserved)
    ├── roadmap.md        moved
    ├── vision.md         moved
    ├── prd.md            moved
    ├── versioning.md     moved
    ├── plans/            (existing)
    ├── roadmap/          (existing)
    └── superpowers/      (existing)

What changed by file

File	Lines (before → after)	Purpose
README.md	307 → 95	Landing page: hero + install (3 paths) + 5-key quick start + MCP wiring snippet + Documentation table
CONTRIBUTING.md	119 → 111	Thin pointer page: branch/commit conventions + doc-maintenance checklist. Build instructions moved into docs/installation.md.
docs/README.md	new (48 lines)	Documentation index — what github.com auto-renders when a visitor clicks the docs/ folder
docs/installation.md	new (142 lines)	Linux/macOS one-liner, Windows zip, Go install, Docker + native build paths, dev/debug variants, uninstall
docs/quick-start.md	new (111 lines)	What to do after install — 5 keys, opening a typed pane, automatic persistence, AI assistant connection
docs/features.md	new (224 lines)	Feature catalog grouped: persistence, layout, clipboard, plugins, observability, pane notes, operations
docs/keybindings.md	new (143 lines)	Full keymap + customization syntax, why Tab/Shift+Tab are not bound
docs/configuration.md	new (153 lines)	Every section + every key of ~/.quil/config.toml with defaults and effects
docs/mcp.md	new (317 lines)	Headline doc. Architecture diagram, wiring snippets for Claude Desktop / Claude Code / Cursor / VS Code Copilot, all 17 tools with input schemas, redaction model, per-pane logging, troubleshooting
docs/troubleshooting.md	new (197 lines)	Daemon won't start, blank TUI, MCP not detected, version mismatch, log file locations, force-stop, full reset
ARCHITECTURE.md → docs/architecture.md	moved	git mv preserves history
PRD.md → docs/prd.md	moved	Cross-references inside fixed up
ROADMAP.md → docs/roadmap.md	moved	Internal docs/roadmap/... links rewritten as sibling links
VISION.md → docs/vision.md	moved
VERSIONING.md → docs/versioning.md	moved
.claude/CLAUDE.md	edited	Documents section rewritten to reflect new tree
site/src/pages/docs.astro	edited	Reorganised into 5 sections (Getting started / Using Quil / Authoring / Project context / Future roadmap) with current paths + 4 new entries
site/src/components/Footer.astro	edited	Doc links updated; MCP guide added
docs/plans/2026-03-09-m1-foundation.md	1 line	Historical plan's Reference: pointers updated to ../prd.md and ../vision.md

Why MCP got its own user guide

quil mcp is the project's headline AI feature — Quil becomes the bridge between your AI assistant and your terminal. But until this PR, the only MCP documentation was docs/roadmap/mcp-server.md, which is a PRD describing the architecture, not a user guide. A user could not figure out how to wire Quil into Claude Desktop or Cursor without reading the source code.

docs/mcp.md solves that. It contains:

1. A diagram of how quil mcp bridges MCP JSON-RPC over stdio to the daemon IPC over the Unix socket
2. Copy-pasteable JSON config snippets for 4 popular MCP clients (Claude Desktop, Claude Code CLI, Cursor, VS Code Copilot Chat)
3. All 17 tools documented in a single table per group (Discovery, Reading, Interacting, Lifecycle, TUI cooperation, Event observation, Memory reporting) with input schemas pulled directly from cmd/quil/mcp_tools.go so the docs cannot drift
4. Example AI prompts showing real workflows: build monitoring, cross-pane context, workspace setup, triaging a stuck pane
5. Security model — the <<REDACT>>...<</REDACT>> marker contract + the regex-fallback layer (OpenAI keys, GitHub PATs, JWTs, BIP-32 extended keys) that catches secrets the AI forgot to wrap
6. Per-pane MCP logging — where the log files live, what gets logged, the orange border highlight
7. Troubleshooting — daemon connect failure, AI client not seeing the server, send_keys racing the target TUI, where to look in the logs

Cross-reference verification

A custom relative-link checker was written for the new docs/ tree:

for f in docs/*.md; do
  while IFS= read -r link; do
    target=$(echo "$link" | sed -nE 's/.*\]\(([^)#]+)(#[^)]*)?\).*/\1/p')
    case "$target" in http*|/*) continue;; *.md)
      full="$(dirname "$f")/$target"
      [ ! -f "$full" ] && echo "BROKEN in $f: $target"
    esac
  done < <(grep -oE '\]\([^)]+\.md(#[^)]*)?\)' "$f")
done

All internal MD links resolve. The recursive grep for stale root-MD path mentions across the whole repo (excluding historical content under docs/plans/, docs/roadmap/, docs/superpowers/) returns only:

• Historical CHANGELOG entries that describe past releases (won't touch)
• Intentional "moved from root X.md" labels in CLAUDE.md
• One historical PRD note in docs/roadmap/pane-notes.md (preserved for archaeology)

Verification

• astro check + astro build against site/ — 0 errors, 0 warnings, 11 pages built
• Relative-link checker walks every MD link in docs/ — all resolve
• git mv preserved file history for all 5 moved files (verify with git log --follow docs/architecture.md)
• README went 307 → 95 lines; root .md count went 8 → 4

Independence from other open PRs

This PR is independent of #34 (feat(tui): add Stop daemon action). They touch disjoint files:

• This PR: docs/, README.md, CONTRIBUTING.md, .claude/CLAUDE.md, site/
• feat(tui): add Stop daemon action to Settings dialog (F1) #34: internal/tui/, internal/claudehook/

Either can land first; merging order does not require re-basing.