---
phase: 14-documentation-content-refinement-and-quality-pass
plan: 05
type: execute
wave: 3
depends_on: ["14-02", "14-03", "14-04"]
files_modified:
  - docs/development.md
  - docs/plugin-guide.md
  - docs/api-reference.md
  - docs/mcp.md
  - docs/dev/index.md
  - mkdocs.yml
  - docs/llms.txt
  - scripts/gen_llms_full_txt.py
  - docs/llms-full.txt
autonomous: true
requirements: []

must_haves:
  truths:
    - "All Developer Guide pages have source-verified content"
    - "plugin-guide.md acknowledges deprecated hookspecs with deprecation callout"
    - "mkdocs.yml nav includes best-practices.md and agents.md"
    - "llms.txt includes entries for best-practices.md and agents.md"
    - "gen_llms_full_txt.py NAV_ORDER includes best-practices.md and agents.md"
    - "llms-full.txt is regenerated and includes content from new pages"
    - "mkdocs build --strict passes with all pages"
  artifacts:
    - path: "docs/development.md"
      provides: "Source-verified contributor guide"
      min_lines: 160
    - path: "docs/plugin-guide.md"
      provides: "Plugin authoring guide with deprecated hookspec acknowledgment"
      min_lines: 720
    - path: "docs/mcp.md"
      provides: "Source-verified MCP documentation"
      min_lines: 110
    - path: "mkdocs.yml"
      provides: "Nav with best-practices.md and agents.md entries"
      contains: "best-practices.md"
    - path: "docs/llms.txt"
      provides: "Agent discovery file with new page entries"
      contains: "best-practices"
    - path: "scripts/gen_llms_full_txt.py"
      provides: "Updated NAV_ORDER with new pages"
      contains: "best-practices.md"
    - path: "docs/llms-full.txt"
      provides: "Regenerated concatenated corpus including new pages"
      contains: "Best Practices"
  key_links:
    - from: "mkdocs.yml"
      to: "docs/best-practices.md"
      via: "nav entry"
      pattern: "best-practices"
    - from: "mkdocs.yml"
      to: "docs/agents.md"
      via: "nav entry"
      pattern: "agents"
    - from: "scripts/gen_llms_full_txt.py"
      to: "docs/best-practices.md"
      via: "NAV_ORDER entry"
      pattern: "best-practices.md"
---

<objective>
Apply the ThatDev Quality Bar to all Developer Guide pages, then wire the two new pages (best-practices.md, agents.md) into mkdocs.yml nav, llms.txt, and gen_llms_full_txt.py. Regenerate llms-full.txt and verify mkdocs build --strict passes.

Purpose: Complete the quality pass for Developer Guide content and finalize all infrastructure wiring so new pages are discoverable in navigation, agent artifacts, and site builds.
Output: Five enhanced Developer Guide pages + updated infrastructure files + regenerated llms-full.txt.
</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 Developer Guide pages (development, plugin-guide, api-reference, mcp, dev/index)</name>
  <files>docs/development.md, docs/plugin-guide.md, docs/api-reference.md, docs/mcp.md, docs/dev/index.md</files>
  <read_first>
    - docs/development.md (current: 154 lines)
    - docs/plugin-guide.md (current: 719 lines)
    - docs/api-reference.md (current: 69 lines)
    - docs/mcp.md (current: 105 lines)
    - docs/dev/index.md (current: 12 lines)
    - src/ztlctl/plugins/hookspecs.py (verify all 16 active + 9 deprecated hookspec signatures)
    - src/ztlctl/actions/definitions.py (verify ActionDefinition, ActionParam for architecture docs)
    - src/ztlctl/actions/registry.py (verify ActionRegistry for architecture docs)
    - src/ztlctl/mcp/tools.py (verify MCP tool names and categories)
    - src/ztlctl/mcp/resources.py (verify MCP resource URIs)
    - src/ztlctl/mcp/prompts.py (verify MCP prompt definitions)
  </read_first>
  <action>
Enhance all five Developer Guide pages with source-verified content. Senior-to-senior peer tone.

**docs/dev/index.md** (target: 20-30 lines, currently 12):
- Add agents.md entry to the "In This Guide" table: `| [Agent System Manual](../agents.md) | Machine-readable schemas, state machines, and interaction flows for LLM consumers |`
- Verify all existing entries are accurate and add brief descriptions if missing

**docs/development.md** (target: 160-200 lines, currently 154):
- Verify the Action Model section against definitions.py and registry.py
- Verify ActionDefinition fields: name, category, description, params, handler, returns
- Verify the 4-layer architecture description matches current code (domain → infrastructure → services → commands)
- Add cross-link to plugin-guide.md for plugin development, api-reference.md for API details
- Add "Architecture Decision" callout: why ActionRegistry exists (define-once, generate CLI+MCP)
- Ensure heading hierarchy consistency
- Eliminate hedging

**docs/plugin-guide.md** (target: 720-780 lines, currently 719):
- This is already the most detailed page — verify, don't rewrite
- Verify every hookspec signature shown against hookspecs.py (name, parameters, return type, firstresult)
- Add a `!!! warning "Deprecated Hookspecs"` section acknowledging the 9 deprecated hookspecs:
  ```
  !!! warning "Deprecated Hookspecs"
      The following hookspecs still work but are deprecated. Use `pre_action` / `post_action` instead:

      - `post_create`, `post_update`, `post_close`, `post_reweave`
      - `post_session_start`, `post_session_close`
      - `post_check`, `post_init`, `post_init_profile`

      These will emit `DeprecationWarning` when called.
  ```
- Verify the "16 hookspecs" claim is explicitly stated as "16 active hookspecs" (distinct from the 9 deprecated)
- Add cross-link to api-reference.md
- Check for any outdated class names (ZtlctlHookSpec is correct, not ZtlctlSpec)

**docs/api-reference.md** (target: 70-90 lines, currently 69):
- Light touch — this is auto-generated via mkdocstrings ::: directives
- Verify the 5 module paths in ::: directives are still correct
- Add brief intro paragraph explaining what auto-generated means and how to navigate
- Add cross-link to plugin-guide.md for hookspec usage examples

**docs/mcp.md** (target: 110-150 lines, currently 105):
- Verify MCP tool categories and counts against mcp/tools.py
- Verify resource URIs against mcp/resources.py
- Verify prompt definitions against mcp/prompts.py
- Add concrete example: a full MCP tool call and response for creating a note
- Add cross-link to agents.md for machine-readable interaction patterns
- Ensure tool count is accurate (should be 59 tools per v2.0 milestone)
  </action>
  <verify>
    <automated>wc -l docs/development.md docs/plugin-guide.md docs/api-reference.md docs/mcp.md docs/dev/index.md | tail -1 | awk '{print ($1 >= 1080) ? "OK: "$1" total lines" : "TOO SHORT: "$1" total lines"}'</automated>
  </verify>
  <acceptance_criteria>
    - docs/dev/index.md contains "Agent System Manual" or "agents.md" entry
    - docs/development.md >= 160 lines, contains "ActionRegistry" or "ActionDefinition"
    - docs/development.md contains cross-link to plugin-guide.md
    - docs/plugin-guide.md >= 720 lines
    - docs/plugin-guide.md contains "Deprecated" section or admonition mentioning post_create, post_update
    - docs/plugin-guide.md contains "16 active" (not just "16 hookspecs")
    - docs/plugin-guide.md contains "ZtlctlHookSpec" (correct class name)
    - docs/api-reference.md >= 70 lines
    - docs/mcp.md >= 110 lines, contains cross-link to agents.md
    - docs/mcp.md contains tool count or tool categories verified against source
  </acceptance_criteria>
  <done>All Developer Guide pages are source-verified: development.md has accurate architecture docs, plugin-guide.md acknowledges deprecated hookspecs, api-reference.md has navigation intro, mcp.md has verified tool/resource counts, dev/index.md has agents.md entry</done>
</task>

<task type="auto">
  <name>Task 2: Wire new pages into mkdocs.yml, llms.txt, gen script, and regenerate llms-full.txt</name>
  <files>mkdocs.yml, docs/llms.txt, scripts/gen_llms_full_txt.py, docs/llms-full.txt</files>
  <read_first>
    - mkdocs.yml (current nav structure)
    - docs/llms.txt (current 32-line agent discovery file)
    - scripts/gen_llms_full_txt.py (current NAV_ORDER)
    - docs/best-practices.md (verify it exists from Plan 02)
    - docs/agents.md (verify it exists from Plan 02)
  </read_first>
  <action>
Wire best-practices.md and agents.md into all infrastructure files, then regenerate llms-full.txt and run mkdocs build --strict.

**mkdocs.yml** — Add two nav entries:
```yaml
nav:
  - Home: index.md
  - Installation: installation.md
  - Quick Start: quickstart.md
  - User Guide:
    - guide/index.md
    - Tutorial: tutorial.md
    - Core Concepts: concepts.md
    - Knowledge Paradigms: paradigms.md
    - Obsidian Starter Kit: obsidian.md
    - Built-in Plugins: plugins.md
    - Agentic Workflows: agentic-workflows.md
    - Command Reference: commands.md
    - Configuration: configuration.md
    - Troubleshooting: troubleshooting.md
    - Best Practices: best-practices.md       # NEW
  - Developer Guide:
    - dev/index.md
    - Contributing: development.md
    - Plugin Authoring: plugin-guide.md
    - API Reference: api-reference.md
    - MCP Server: mcp.md
    - Agent System Manual: agents.md           # NEW
```

**docs/llms.txt** — Add two entries:
- In User Guide section, after Troubleshooting line, add:
  ```
  - [Best Practices](https://thatdevstudio.github.io/ztlctl/best-practices/): Opinionated anti-patterns and correct patterns for vault, notes, tags, sessions, and agent workflows
  ```
- In Developer Guide section, after MCP Server line, add:
  ```
  - [Agent System Manual](https://thatdevstudio.github.io/ztlctl/agents/): Machine-readable schemas, state machines, constraint rules, and interaction flows for LLM systems
  ```

**scripts/gen_llms_full_txt.py** — Update NAV_ORDER:
- In "User Guide" list, add `"best-practices.md"` after `"troubleshooting.md"`
- In "Developer Guide" list, add `"agents.md"` after `"mcp.md"`

**Regenerate llms-full.txt:**
```bash
cd /Users/shparki/Documents/Workspace/thatdev/ztlctl && python scripts/gen_llms_full_txt.py
```

**Verify build:**
```bash
cd /Users/shparki/Documents/Workspace/thatdev/ztlctl && uv run --with mkdocs==1.6.1 --with mkdocs-shadcn==0.10.2 --with mkdocs-redirects==1.2.2 --with "mkdocstrings[python]>=1.0.3" mkdocs build --strict
```

Fix any build errors (broken links, missing pages, render failures) before completing.
  </action>
  <verify>
    <automated>grep "best-practices" mkdocs.yml && grep "agents.md" mkdocs.yml && grep "best-practices" docs/llms.txt && grep "agents" docs/llms.txt && grep "best-practices.md" scripts/gen_llms_full_txt.py && grep "agents.md" scripts/gen_llms_full_txt.py && grep "Best Practices" docs/llms-full.txt</automated>
  </verify>
  <acceptance_criteria>
    - mkdocs.yml nav contains "Best Practices: best-practices.md" entry
    - mkdocs.yml nav contains "Agent System Manual: agents.md" entry
    - docs/llms.txt contains "Best Practices" entry with URL
    - docs/llms.txt contains "Agent System Manual" entry with URL
    - scripts/gen_llms_full_txt.py NAV_ORDER contains "best-practices.md"
    - scripts/gen_llms_full_txt.py NAV_ORDER contains "agents.md"
    - docs/llms-full.txt contains "Best Practices" content (from best-practices.md)
    - docs/llms-full.txt contains "Agent System Manual" content (from agents.md)
    - `mkdocs build --strict` exits 0 with no errors
  </acceptance_criteria>
  <done>Both new pages wired into mkdocs.yml nav, llms.txt, gen script NAV_ORDER; llms-full.txt regenerated with new page content; mkdocs build --strict passes clean</done>
</task>

</tasks>

<verification>
Full phase verification:
- `mkdocs build --strict` passes with all 20 pages (18 existing + 2 new)
- `grep "best-practices" mkdocs.yml` — nav entry present
- `grep "agents.md" mkdocs.yml` — nav entry present
- `grep "Best Practices" docs/llms-full.txt` — content included in agent corpus
- `grep "Agent System Manual" docs/llms-full.txt` — content included in agent corpus
- `grep "ZTLCTL_DOCS_PATH" docs/configuration.md docs/troubleshooting.md` — documented in both
- `grep "Built-in Plugins" docs/guide/index.md` — INT-01 closed
- No `grep "^\[git\]" docs/configuration.md` matches — config fix applied
</verification>

<success_criteria>
- All Developer Guide pages are source-verified with accurate hookspec, ActionRegistry, and MCP content
- plugin-guide.md acknowledges 9 deprecated hookspecs
- mkdocs.yml, llms.txt, gen script all include both new pages
- llms-full.txt regenerated with new page content
- mkdocs build --strict passes clean — zero errors, zero warnings
- The full documentation site is ready for deployment
</success_criteria>

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