---
phase: 09-navigation-structure
plan: 01
type: execute
wave: 1
depends_on: []
files_modified:
  - mkdocs.yml
  - docs/guide/index.md
  - docs/dev/index.md
autonomous: true
requirements:
  - UGDE-01

must_haves:
  truths:
    - "The MkDocs sidebar shows User Guide and Developer Guide as distinct collapsible sections"
    - "All 8 user guide pages (tutorial, concepts, paradigms, obsidian, agentic-workflows, commands, configuration, troubleshooting) appear under User Guide"
    - "Both developer pages (development, mcp) appear under Developer Guide"
    - "docs/guide/index.md exists with a table listing all 8 user guide pages with one-line descriptions"
    - "docs/dev/index.md exists with a table listing both developer pages with one-line descriptions"
    - "mkdocs build --strict passes with no errors or warnings"
    - "All 13 existing pages remain reachable with no URL changes (files stay in docs/ root)"
  artifacts:
    - path: "mkdocs.yml"
      provides: "Restructured nav: section with two nested tracks"
      contains: "User Guide"
    - path: "docs/guide/index.md"
      provides: "User Guide section landing page"
      min_lines: 20
    - path: "docs/dev/index.md"
      provides: "Developer Guide section landing page"
      min_lines: 10
  key_links:
    - from: "mkdocs.yml nav:"
      to: "docs/guide/index.md"
      via: "- guide/index.md (first child of User Guide section)"
      pattern: "guide/index.md"
    - from: "mkdocs.yml nav:"
      to: "docs/dev/index.md"
      via: "- dev/index.md (first child of Developer Guide section)"
      pattern: "dev/index.md"
---

<objective>
Restructure the MkDocs nav section from a flat 13-page list into two nested tracks (User Guide and Developer Guide), and create the two new section landing pages that anchor each track.

Purpose: Users landing on the docs site need to immediately identify which track serves them. The two-track nav is the primary usability improvement in Phase 9.
Output: Updated mkdocs.yml with nested nav, docs/guide/index.md, docs/dev/index.md — site builds clean with mkdocs build --strict.
</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/09-navigation-structure/09-CONTEXT.md
@.planning/phases/09-navigation-structure/09-RESEARCH.md

<interfaces>
<!-- Current mkdocs.yml nav (flat — to be replaced): -->
```yaml
nav:
  - Home: index.md
  - Installation: installation.md
  - Quick Start: quickstart.md
  - Tutorial: tutorial.md
  - Core Concepts: concepts.md
  - Knowledge Paradigms: paradigms.md
  - Obsidian Starter Kit: obsidian.md
  - Command Reference: commands.md
  - Configuration: configuration.md
  - MCP Server: mcp.md
  - Agentic Workflows: agentic-workflows.md
  - Troubleshooting: troubleshooting.md
  - Development: development.md
```

<!-- Locked nav structure from 09-CONTEXT.md (exact YAML to use): -->
```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
    - Agentic Workflows: agentic-workflows.md
    - Command Reference: commands.md
    - Configuration: configuration.md
    - Troubleshooting: troubleshooting.md
  - Developer Guide:
    - dev/index.md
    - Contributing: development.md
    - MCP Server: mcp.md
```

<!-- site_url from mkdocs.yml: https://thatdevstudio.github.io/ztlctl/ -->
</interfaces>
</context>

<tasks>

<task type="auto">
  <name>Task 1: Restructure mkdocs.yml nav and create section landing pages</name>
  <files>mkdocs.yml, docs/guide/index.md, docs/dev/index.md</files>
  <read_first>
    - mkdocs.yml (current nav structure to replace)
    - .planning/phases/09-navigation-structure/09-CONTEXT.md (locked decisions, exact nav YAML)
    - .planning/phases/09-navigation-structure/09-RESEARCH.md (section landing page content examples, pitfalls)
  </read_first>
  <action>
**Step 1: Update mkdocs.yml nav section.**

Replace the current flat `nav:` block entirely with the locked structure from CONTEXT.md. The rest of mkdocs.yml (theme, plugins, markdown_extensions, copyright) stays unchanged. The exact nav YAML to use:

```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
    - Agentic Workflows: agentic-workflows.md
    - Command Reference: commands.md
    - Configuration: configuration.md
    - Troubleshooting: troubleshooting.md
  - Developer Guide:
    - dev/index.md
    - Contributing: development.md
    - MCP Server: mcp.md
```

Note: `guide/index.md` has no label — MkDocs will use the page's H1 as the sidebar label. Same for `dev/index.md`. This is the correct MkDocs pattern for section landing pages.

**Step 2: Create docs/guide/index.md.**

Create the `docs/guide/` directory and write `docs/guide/index.md` with this exact content:

```markdown
# User Guide

ztlctl's User Guide is for knowledge workers building personal knowledge systems — whether you're a researcher, writer, product manager, or student. These guides show you how to think in zettelkasten, capture ideas, build connections, and retrieve knowledge on demand.

**Not sure where to start?** Try the [Quick Start](../quickstart.md) or the [Tutorial](../tutorial.md).

## In This Guide

| Page | What it covers |
|------|----------------|
| [Tutorial](../tutorial.md) | Hands-on walkthrough: create notes, link them, run a session |
| [Core Concepts](../concepts.md) | Content types, lifecycle states, and vault structure |
| [Knowledge Paradigms](../paradigms.md) | Second-brain vs knowledge garden — which fits your workflow |
| [Obsidian Starter Kit](../obsidian.md) | Set up Obsidian as a visual frontend for your vault |
| [Agentic Workflows](../agentic-workflows.md) | Orchestrate AI agents with ztlctl as their note substrate |
| [Command Reference](../commands.md) | Every CLI command and flag |
| [Configuration](../configuration.md) | Config file options, vault settings, and environment variables |
| [Troubleshooting](../troubleshooting.md) | Common problems and solutions |
```

Note: Links use `../` relative paths because this file is in `docs/guide/` while the target files are in `docs/`. This is required for MkDocs to resolve links correctly in the nested directory.

**Step 3: Create docs/dev/index.md.**

Create the `docs/dev/` directory and write `docs/dev/index.md` with this exact content:

```markdown
# Developer Guide

The Developer Guide is for contributors and integrators — those building plugins, extending ztlctl's capabilities, or integrating it into agent systems via MCP.

## In This Guide

| Page | What it covers |
|------|----------------|
| [Contributing](../development.md) | Architecture overview, branch workflow, and contribution process |
| [MCP Server](../mcp.md) | MCP tools, resources, prompts, and agent integration patterns |
```

**Step 4: Run mkdocs build --strict to validate.**

```bash
mkdocs build --strict
```

This validates: all `nav:` entries resolve to real files, no broken internal links, no warnings treated as errors. If it fails, diagnose and fix before committing.

**Step 5: Verify nav label for guide/index.md.**

After the build, check that `site/guide/index.html` exists and that the sidebar would label this page "User Guide" (from its H1). If `mkdocs serve` shows a different label, add an explicit label to mkdocs.yml: `- User Guide: guide/index.md`.
  </action>
  <verify>
    <automated>cd /Users/shparki/Documents/Workspace/thatdev/ztlctl && mkdocs build --strict 2>&amp;1 | tail -5 &amp;&amp; test -f docs/guide/index.md &amp;&amp; test -f docs/dev/index.md &amp;&amp; grep -c "User Guide" mkdocs.yml &amp;&amp; grep -c "Developer Guide" mkdocs.yml &amp;&amp; test -f site/guide/index.html &amp;&amp; test -f site/dev/index.html &amp;&amp; echo "PASS"</automated>
  </verify>
  <acceptance_criteria>
    - `mkdocs build --strict` exits 0 with no warnings
    - `grep "User Guide" mkdocs.yml` matches at least once
    - `grep "Developer Guide" mkdocs.yml` matches at least once
    - `grep "guide/index.md" mkdocs.yml` matches
    - `grep "dev/index.md" mkdocs.yml` matches
    - `test -f docs/guide/index.md` passes
    - `test -f docs/dev/index.md` passes
    - `test -f site/guide/index.html` passes (build output present)
    - `test -f site/dev/index.html` passes (build output present)
    - `grep "Tutorial" docs/guide/index.md` matches (content present)
    - `grep "MCP Server" docs/dev/index.md` matches (content present)
    - All 13 original docs pages still exist in docs/ root (no files moved)
  </acceptance_criteria>
  <done>mkdocs.yml nav is restructured into two nested tracks. Both section landing pages exist with content tables. mkdocs build --strict passes. No files were moved from docs/ root.</done>
</task>

</tasks>

<verification>
After plan completes:
1. `mkdocs build --strict` passes with exit code 0
2. `test -f docs/guide/index.md && test -f docs/dev/index.md` both pass
3. `grep "User Guide" mkdocs.yml` shows the section container
4. `grep "Developer Guide" mkdocs.yml` shows the section container
5. All 13 original docs files still exist at `docs/*.md` root level (no moves)
6. `site/guide/index.html` and `site/dev/index.html` exist in build output
</verification>

<success_criteria>
- mkdocs.yml nav contains two nested sections: User Guide (8 pages + index) and Developer Guide (2 pages + index)
- docs/guide/index.md exists with H1 "User Guide" and a table of all 8 user-guide pages
- docs/dev/index.md exists with H1 "Developer Guide" and a table of both developer pages
- mkdocs build --strict passes with no errors
- All 13 original pages remain at docs/*.md (no URL-breaking file moves)
</success_criteria>

<output>
After completion, create `.planning/phases/09-navigation-structure/09-01-SUMMARY.md`
</output>
