---
phase: 14-documentation-content-refinement-and-quality-pass
plan: 03
type: execute
wave: 2
depends_on: ["14-01"]
files_modified:
  - docs/index.md
  - docs/installation.md
  - docs/quickstart.md
  - docs/concepts.md
  - docs/paradigms.md
autonomous: true
requirements: []

must_haves:
  truths:
    - "Every page has consistent heading hierarchy (H1 title, H2 major sections, H3 subsections)"
    - "Every page has at least 2 concrete real-world examples"
    - "No hedging language remains (should, might, could → use, do, run)"
    - "Every CLI example is verified against Click command source"
    - "Cross-links added between related pages"
  artifacts:
    - path: "docs/index.md"
      provides: "Enhanced landing page with clear audience paths"
      min_lines: 50
    - path: "docs/installation.md"
      provides: "Complete installation guide with all methods"
      min_lines: 90
    - path: "docs/quickstart.md"
      provides: "Quick start with real-world examples"
      min_lines: 80
    - path: "docs/concepts.md"
      provides: "Core concepts with lifecycle diagrams and examples"
      min_lines: 130
    - path: "docs/paradigms.md"
      provides: "Enhanced paradigms guide (already 192 lines)"
      min_lines: 200
  key_links:
    - from: "docs/index.md"
      to: "docs/quickstart.md"
      via: "Get Started link"
      pattern: "quickstart"
    - from: "docs/quickstart.md"
      to: "docs/tutorial.md"
      via: "Next Steps cross-link"
      pattern: "tutorial"
    - from: "docs/concepts.md"
      to: "docs/paradigms.md"
      via: "cross-link for paradigm deep dive"
      pattern: "paradigms"
---

<objective>
Apply the ThatDev Quality Bar to the Getting Started pages (index, installation, quickstart) and foundational User Guide pages (concepts, paradigms). These are the first pages users encounter — they must be sharp, decisive, and example-rich.

Purpose: Ensure the entry-point documentation meets the quality standard: source-verified CLI examples, consistent heading hierarchy, no hedging, real-world examples, and cross-links.
Output: Five enhanced documentation pages with verified content.
</objective>

<execution_context>
@/Users/shparki/.claude/get-shit-done/workflows/execute-plan.md
@/Users/shparki/.claude/get-shit-done/templates/summary.md
</execution_context>

<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/STATE.md
@.planning/phases/14-documentation-content-refinement-and-quality-pass/14-CONTEXT.md
@.planning/phases/14-documentation-content-refinement-and-quality-pass/14-RESEARCH.md
</context>

<tasks>

<task type="auto">
  <name>Task 1: Enhance Getting Started pages (index, installation, quickstart)</name>
  <files>docs/index.md, docs/installation.md, docs/quickstart.md</files>
  <read_first>
    - docs/index.md (current: 35 lines — sparse landing page)
    - docs/installation.md (current: 69 lines — basic install methods)
    - docs/quickstart.md (current: 50 lines — minimal quick start)
    - src/ztlctl/commands/main.py (verify top-level CLI commands for accurate examples)
    - src/ztlctl/commands/create.py (verify create command syntax)
    - src/ztlctl/commands/init_cmd.py (verify init command flags and profiles)
    - pyproject.toml (verify package name, Python version requirement, install methods)
  </read_first>
  <action>
Enhance the three Getting Started pages to meet the ThatDev Quality Bar.

**docs/index.md** (target: 50-70 lines, currently 35):
- Keep the existing project description but sharpen it — remove any vague language
- Add clear audience paths: "For Knowledge Workers" → User Guide, "For Developers" → Developer Guide, "For AI Agents" → agents.md / llms.txt
- Add a "What Makes ztlctl Different" section (3-4 bullet points: local-first SQLite, graph-native, agent-native MCP, plugin ecosystem)
- Add "Quick Links" section with the 4-5 most important pages
- Ensure H1 title, H2 sections, consistent hierarchy

**docs/installation.md** (target: 90-120 lines, currently 69):
- Verify every install command against pyproject.toml package metadata
- Add system requirements section (Python 3.13+, verify from pyproject.toml `requires-python`)
- Ensure all install methods are documented: pip, uv, pipx, Homebrew (if available)
- Add "Verify Installation" section: `ztlctl --version` and expected output
- Add "Development Install" section for contributors: `git clone` + `uv sync --group dev`
- Add "Next Steps" cross-link to quickstart.md
- Remove any hedging — "you may want to" → "run"

**docs/quickstart.md** (target: 80-110 lines, currently 50):
- Verify every CLI command against Click source (init, create, search, session)
- Add a complete real-world example: "Research Project Quick Start" showing init → create reference → create note → link → search → session
- Add a second example: "Daily Notes Quick Start" for simple note-taking workflow
- Ensure every command shows expected output (or a representative excerpt)
- Add "Next Steps" with cross-links to tutorial.md, concepts.md, configuration.md
- Be decisive: "Run this" not "You might want to run"
  </action>
  <verify>
    <automated>wc -l docs/index.md docs/installation.md docs/quickstart.md | tail -1 | awk '{print ($1 >= 220) ? "OK: "$1" total lines" : "TOO SHORT: "$1" total lines"}'</automated>
  </verify>
  <acceptance_criteria>
    - docs/index.md is >= 50 lines and contains "Knowledge Workers" or "For Users" audience path
    - docs/index.md contains cross-link to quickstart.md
    - docs/installation.md is >= 90 lines and contains "ztlctl --version" verification step
    - docs/installation.md contains "Python 3.13" or appropriate version requirement
    - docs/installation.md contains "Next Steps" section
    - docs/quickstart.md is >= 80 lines and contains at least 2 distinct workflow examples
    - docs/quickstart.md contains "Next Steps" section with link to tutorial.md
    - No page contains "you may want to", "you might", "you could" (hedging eliminated)
  </acceptance_criteria>
  <done>All three Getting Started pages are enhanced with source-verified CLI examples, real-world workflows, consistent heading hierarchy, no hedging, and cross-links</done>
</task>

<task type="auto">
  <name>Task 2: Enhance foundational User Guide pages (concepts, paradigms)</name>
  <files>docs/concepts.md, docs/paradigms.md</files>
  <read_first>
    - docs/concepts.md (current: 91 lines — accurate but thin)
    - docs/paradigms.md (current: 192 lines — already expanded in Phase 10)
    - src/ztlctl/domain/types.py (content types, lifecycle states — verify all enums)
    - src/ztlctl/domain/ids.py (ID patterns — N-XXXX, R-XXXX, T-XXXX, L-XXXX)
    - src/ztlctl/services/create.py (6-stage pipeline for lifecycle explanation)
  </read_first>
  <action>
Enhance the two foundational User Guide pages.

**docs/concepts.md** (target: 130-180 lines, currently 91):
- Verify all content types against domain/types.py enums (Note, Reference, Task, Log)
- Verify all lifecycle states against domain/types.py (ACTIVE, REVIEW, DORMANT, ARCHIVED, DONE, BLOCKED)
- Add a lifecycle state diagram (ASCII art table showing valid transitions):
  ```
  Note/Reference: ACTIVE → REVIEW → DORMANT → ARCHIVED
  Task:           ACTIVE → DONE | ACTIVE → BLOCKED → ACTIVE
  ```
- Verify ID patterns: N-XXXX (notes), R-XXXX (references), T-XXXX (tasks), L-XXXX (logs)
- Add "Vault Structure" subsection explaining the SQLite vault + graph index
- Add concrete examples: "A note about Python decorators" → show its ID, tags, links, lifecycle
- Add "Relationships" section: how notes connect via wikilinks, reweave suggestions, graph edges
- Add cross-links to paradigms.md, tutorial.md
- Eliminate hedging, use decisive language

**docs/paradigms.md** (target: 200-240 lines, currently 192):
- This was already expanded in Phase 10 — light touch only
- Verify CLI command examples against Click source (any create, search, session commands used)
- Add an anti-patterns section or callout (2-3 entries): "Don't force one paradigm", "Don't mix paradigm tags in one vault without namespacing"
- Add cross-link to best-practices.md (when it exists from Plan 02)
- Ensure "Next Steps" section exists with links to tutorial.md, plugins.md
- Check heading hierarchy consistency (H1/H2/H3)
  </action>
  <verify>
    <automated>wc -l docs/concepts.md docs/paradigms.md | tail -1 | awk '{print ($1 >= 330) ? "OK: "$1" total lines" : "TOO SHORT: "$1" total lines"}'</automated>
  </verify>
  <acceptance_criteria>
    - docs/concepts.md is >= 130 lines
    - docs/concepts.md contains lifecycle state names: "ACTIVE", "REVIEW", "DORMANT", "ARCHIVED"
    - docs/concepts.md contains ID patterns: "N-", "R-", "T-", "L-"
    - docs/concepts.md contains a state diagram or transition table
    - docs/concepts.md contains cross-link to paradigms.md
    - docs/paradigms.md is >= 200 lines
    - docs/paradigms.md contains "Next Steps" section
    - docs/paradigms.md contains link to best-practices.md or tutorial.md
  </acceptance_criteria>
  <done>Both foundational pages are enhanced: concepts.md has verified lifecycle states, ID patterns, state diagrams, and examples; paradigms.md has anti-pattern callouts and cross-links</done>
</task>

</tasks>

<verification>
- All 5 pages have consistent H1/H2/H3 heading hierarchy
- All CLI examples verified against Click command source
- No hedging language ("you may want to", "you might", "you could")
- Each page has at least 2 concrete examples
- Cross-links exist between related pages
- `wc -l` totals meet minimum thresholds
</verification>

<success_criteria>
- index.md is a sharp landing page with audience paths and quick links
- installation.md covers all install methods with verification steps
- quickstart.md has 2 real-world workflow examples
- concepts.md has verified lifecycle states, ID patterns, and state diagrams
- paradigms.md has anti-pattern callouts and cross-links
- All 5 pages meet ThatDev Quality Bar: no hedging, decisive, example-rich
</success_criteria>

<output>
After completion, create `.planning/phases/14-documentation-content-refinement-and-quality-pass/14-03-SUMMARY.md`
</output>
