---
phase: 14-documentation
plan: 01
type: documentation
wave: 1
depends_on: []
files_modified: [docs/README.md, docs/architecture/overview.md, docs/architecture/graph-subsystem.md, docs/architecture/tag-subsystem.md, docs/api/graph.md, docs/api/tagsweep.md, README.md]
autonomous: true
requirements: [DOC-01, DOC-02]

must_haves:
  truths:
    - "docs/README.md exists with project overview and how to contribute"
    - "docs/architecture/overview.md exists with system architecture diagram and data flow"
    - "docs/architecture/graph-subsystem.md exists covering graph store, rebuild, query layer"
    - "docs/architecture/tag-subsystem.md exists covering tag suggestion, bulk sweep, apply path"
    - "docs/api/ covers graph and tagsweep endpoint contracts"
    - "All docs cross-link to relevant code files"
    - "Root README.md updated with v1.0 features (graph, backlinks, LLM tagging)"
  artifacts:
    - path: "docs/"
      provides: "Contributor-facing architecture documentation"
      contains: "README.md + architecture/*.md + api/*.md"
---

<objective>
Create `docs/` with contributor-facing architecture documentation for the v1.0 graph and tag subsystems, plus update root README to reflect current features. No code changes — documentation only.
</objective>

<execution_context>
@$HOME/.claude/anvil/workflows/execute-plan.md
</execution_context>

<context>
@.planning/ROADMAP.md
@.planning/REQUIREMENTS.md §DOC-01, DOC-02
@.planning/phases/14-documentation/14-CONTEXT.md
</context>

<tasks>

<task type="implement" tdd="false">
  <name>Task 1: Create docs/README.md and architecture overview</name>
  <read_first>
    - internal/graph/ — understand the graph subsystem structure
    - internal/tagsweep/ — understand the tag subsystem structure
    - internal/server/ — handlers and routes
    - .planning/ROADMAP.md — project overview and milestones
    - CLAUDE.md — tech stack and conventions
  </read_first>
  <behavior>
    Create two files:
    1. `docs/README.md` — project overview, how to contribute, link to architecture docs
    2. `docs/architecture/overview.md` — system architecture diagram (ASCII), data flow, component relationships
  </behavior>
  <action>
    1. mkdir -p docs/architecture docs/api
    2. Write docs/README.md with: project name, what it does, tech stack summary, how to run, how to contribute, link to architecture/
    3. Write docs/architecture/overview.md with: ASCII architecture diagram, data flow description (Markdown files → Git → Graph Store → Bleve Index → API → SPA), component list with brief descriptions, cross-links to source files
  </action>
  <acceptance_criteria>
    - docs/README.md exists and is non-empty
    - docs/architecture/overview.md exists and is non-empty
    - grep 'contribut' docs/README.md returns match
    - grep 'graph' docs/architecture/overview.md returns match
    - grep 'internal/' docs/architecture/overview.md returns match (cross-links)
  </acceptance_criteria>
  <done>docs/README.md and architecture overview created with cross-links.</done>
</task>

<task type="implement" tdd="false">
  <name>Task 2: Create subsystem deep-dives (graph + tag)</name>
  <read_first>
    - internal/graph/ — all Go files for graph subsystem
    - internal/tagsweep/ — all Go files for tag subsystem
  </read_first>
  <behavior>
    Create two subsystem architecture docs:
    1. `docs/architecture/graph-subsystem.md` — graph store (SQLite tables, rebuild), query layer (GraphData, Neighborhood, Backlinks), HTTP endpoints
    2. `docs/architecture/tag-subsystem.md` — tag suggestion flow (LLM → propose → approve → apply), bulk sweep, review queue, byte-stable apply path
    Both cross-link to actual source files.
  </behavior>
  <action>
    1. Read internal/graph/*.go to understand the subsystem
    2. Read internal/tagsweep/*.go to understand the subsystem
    3. Write docs/architecture/graph-subsystem.md with: data model, store/recompile design, query layer API, endpoints, rebuild flow
    4. Write docs/architecture/tag-subsystem.md with: suggest→propose→approve→apply flow, bulk sweep architecture, review queue, byte-stable guarantee
  </action>
  <acceptance_criteria>
    - docs/architecture/graph-subsystem.md exists and is non-empty
    - docs/architecture/tag-subsystem.md exists and is non-empty
    - grep 'internal/graph/' docs/architecture/graph-subsystem.md returns match
    - grep 'internal/tagsweep/' docs/architecture/tag-subsystem.md returns match
    - grep 'rebuild' docs/architecture/graph-subsystem.md returns match
    - grep 'approve' docs/architecture/tag-subsystem.md returns match
  </acceptance_criteria>
  <done>Graph and tag subsystem docs created with source cross-links.</done>
</task>

<task type="implement" tdd="false">
  <name>Task 3: Create API docs and update README</name>
  <read_first>
    - internal/server/handlers_graph.go — graph endpoints
    - internal/server/handlers_tagsweep.go — tagsweep endpoints
    - README.md — existing root README
  </read_first>
  <behavior>
    1. Create `docs/api/graph.md` — GraphData, Neighborhood, Backlinks endpoint contracts (URL, method, params, response shape)
    2. Create `docs/api/tagsweep.md` — Tag suggestion, bulk sweep, review queue endpoint contracts
    3. Update root `README.md` to add v1.0 features: graph view, backlinks panel, LLM tagging, local graph dock
  </behavior>
  <action>
    1. Read handlers to extract endpoint contracts
    2. Write docs/api/graph.md with each endpoint documented
    3. Write docs/api/tagsweep.md with each endpoint documented
    4. Read root README.md, add v1.0 feature section after existing content
  </action>
  <acceptance_criteria>
    - docs/api/graph.md exists and is non-empty
    - docs/api/tagsweep.md exists and is non-empty
    - grep '/api/v1/graph' docs/api/graph.md returns match
    - grep 'suggest' docs/api/tagsweep.md returns match
    - grep 'graph' README.md returns match (v1.0 features added)
    - grep 'backlinks' README.md returns match
    - grep 'LLM' README.md returns match
  </acceptance_criteria>
  <done>API docs created and README updated with v1.0 features.</done>
</task>

</tasks>

<success_criteria>
- 6 docs files created (README, overview, 2 subsystem deep-dives, 2 API docs)
- Root README updated
- All docs cross-link to source files
</success_criteria>
