# Phase 9: Navigation Structure - Context

**Gathered:** 2026-03-20
**Status:** Ready for planning

<domain>
## Phase Boundary

Build two-track navigation (User Guide / Developer Guide) in MkDocs. Publish llms.txt and llms-full.txt for agent discovery. All existing 13 docs pages must be reachable under the new structure with no broken internal links. No new content pages are written in this phase — only reorganization and agent accessibility files.

</domain>

<decisions>
## Implementation Decisions

### Page assignment
Existing 13 pages split by audience:
- **Root (shared):** `index.md` (landing page), `installation.md`, `quickstart.md` — these serve all audiences
- **User Guide section:** `tutorial.md`, `concepts.md`, `paradigms.md`, `obsidian.md`, `agentic-workflows.md`, `commands.md`, `configuration.md`, `troubleshooting.md` — 8 pages for knowledge workers
- **Developer Guide section:** `development.md`, `mcp.md` — 2 pages for plugin authors and contributors

### Section landing pages
- Create `docs/guide/index.md` — User Guide landing with brief intro + listing of all pages in the section with one-line descriptions
- Create `docs/dev/index.md` — Developer Guide landing with brief intro + listing of developer pages with descriptions
- These are NEW files — not moved from existing content

### Navigation structure
- Flat within each track (no sub-sections) — 13 pages doesn't warrant deeper nesting
- MkDocs `nav:` uses nested structure:
  ```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
  ```
- Pages stay in `docs/` root (no directory moves) — MkDocs nav handles grouping without file relocation, avoiding URL changes

### llms.txt
- Place at `docs/llms.txt` — served at `/ztlctl/llms.txt`
- Format per llmstxt.org spec: H1 + blockquote summary + H2 sections (Getting Started, User Guide, Developer Guide) with `[name](url): description` links
- Hand-authored initially, kept under 10KB
- Add to mkdocs.yml `extra_files` or similar mechanism so it's included in the build output

### llms-full.txt
- Generated by `scripts/gen_llms_full_txt.py` — walks `docs/*.md`, concatenates with section headers
- Placed at `docs/llms-full.txt` — served at `/ztlctl/llms-full.txt`
- Script runs as pre-commit or CI step (not part of mkdocs build)

### Claude's Discretion
- Exact wording of section landing page descriptions
- Whether to add a visual separator or icon between sections in nav
- llms-full.txt concatenation order (follow nav order is fine)

</decisions>

<canonical_refs>
## Canonical References

**Downstream agents MUST read these before planning or implementing.**

### MkDocs configuration
- `mkdocs.yml` — Current nav structure to update (13 flat pages → nested sections)

### Research findings
- `.planning/research/FEATURES.md` — llms.txt spec details, multi-audience nav patterns
- `.planning/research/ARCHITECTURE.md` — Proposed docs/ directory structure, llms.txt placement
- `.planning/research/PITFALLS.md` — parent: string matching pitfalls (N/A for MkDocs nav: config), URL preservation concerns

### Prior phase context
- `.planning/phases/08-mkdocs-infrastructure/08-CONTEXT.md` — Migration decisions, theme config, URL preservation strategy

</canonical_refs>

<code_context>
## Existing Code Insights

### Reusable Assets
- `mkdocs.yml` nav section — already has all 13 pages listed, just needs restructuring into nested groups
- `mkdocs-redirects` plugin — already wired with empty `redirect_maps: {}`, ready for any URL redirects if needed
- 13 existing markdown files — content stays in `docs/` root, no file moves needed

### Established Patterns
- MkDocs `nav:` config drives sidebar structure (not directory layout or front matter)
- `exclude_docs: plans/` already excludes internal docs
- `mkdocs build --strict` is the validation command

### Integration Points
- `mkdocs.yml` nav section is the primary file to update
- `docs/guide/index.md` and `docs/dev/index.md` are new files to create
- `docs/llms.txt` and `docs/llms-full.txt` are new static files
- `scripts/gen_llms_full_txt.py` is a new build script
- Internal cross-links within docs pages may need updating if they reference pages by relative path

</code_context>

<specifics>
## Specific Ideas

- Pages stay in `docs/` root — MkDocs nav grouping is config-driven, not directory-driven. This avoids all URL change issues.
- llms.txt mirrors the nav structure so agents see the same organization as humans
- User decided during milestone questioning: end users may be using agents, so agentic-workflows.md belongs in User Guide (not Developer Guide)

</specifics>

<deferred>
## Deferred Ideas

None — discussion stayed within phase scope

</deferred>

---

*Phase: 09-navigation-structure*
*Context gathered: 2026-03-20*
