---
phase: 11-developer-guide-api-reference
plan: 01
type: execute
wave: 1
depends_on: []
files_modified:
  - pyproject.toml
  - mkdocs.yml
  - .github/workflows/docs.yml
autonomous: true
requirements:
  - DVGD-02

must_haves:
  truths:
    - "mkdocstrings[python]>=1.0.3 is installed in the dev dependency group"
    - "mkdocs.yml plugins section includes mkdocstrings with paths: [src] and allow_inspection: false"
    - "docs.yml CI workflow pip install line includes mkdocstrings[python]>=1.0.3"
    - "`mkdocs build` completes without errors after the plugin is wired"
  artifacts:
    - path: "pyproject.toml"
      provides: "mkdocstrings[python]>=1.0.3 in dev deps"
      contains: "mkdocstrings"
    - path: "mkdocs.yml"
      provides: "mkdocstrings plugin block with handler config"
      contains: "mkdocstrings"
    - path: ".github/workflows/docs.yml"
      provides: "pip install line with mkdocstrings[python]>=1.0.3"
      contains: "mkdocstrings"
  key_links:
    - from: "mkdocs.yml plugins.mkdocstrings.handlers.python"
      to: "src/ztlctl"
      via: "paths: [src]"
      pattern: "paths: \\[src\\]"
    - from: ".github/workflows/docs.yml pip install"
      to: "mkdocstrings[python]>=1.0.3"
      via: "pip install line"
      pattern: "mkdocstrings"
---

<objective>
Install mkdocstrings tooling and wire it into both the local MkDocs config and the CI deploy workflow so that `docs/api-reference.md` (Plan 03) can use `::: module.path` directives successfully.

Purpose: Unblocks DVGD-02 (auto-generated API reference). Without this plan, `mkdocs build` will fail when it encounters `::: ztlctl.plugins.hookspecs` directives.
Output: pyproject.toml with new dev dep, mkdocs.yml with mkdocstrings plugin block, docs.yml with updated pip install.
</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/11-developer-guide-api-reference/11-RESEARCH.md
</context>

<tasks>

<task type="auto">
  <name>Task 1: Install mkdocstrings dev dependency</name>
  <files>pyproject.toml, uv.lock</files>
  <read_first>
    - pyproject.toml (locate [dependency-groups] dev section, confirm mkdocstrings is not already present)
  </read_first>
  <action>
Run `uv add --group dev "mkdocstrings[python]>=1.0.3"` from the project root. This installs mkdocstrings 1.0.3 + mkdocstrings-python 2.0.3 + griffe 2.0.0 (transitive). Do NOT add `mkdocstrings-python` separately — the meta-package handles it.

After running, verify pyproject.toml shows `mkdocstrings[python]` in the dev group and uv.lock is updated.
  </action>
  <verify>
    <automated>cd /Users/shparki/Documents/Workspace/thatdev/ztlctl && grep 'mkdocstrings' pyproject.toml</automated>
  </verify>
  <done>pyproject.toml has `mkdocstrings[python]>=1.0.3` in dev dependency group; uv.lock updated</done>
</task>

<task type="auto">
  <name>Task 2: Wire mkdocstrings plugin into mkdocs.yml and update CI workflow</name>
  <files>mkdocs.yml, .github/workflows/docs.yml</files>
  <read_first>
    - mkdocs.yml (current plugins: block — only search + redirects present)
    - .github/workflows/docs.yml (line 27: `pip install mkdocs==1.6.1 mkdocs-shadcn==0.10.2 mkdocs-redirects==1.2.2`)
  </read_first>
  <action>
**mkdocs.yml** — Add mkdocstrings to the plugins: block after the existing redirects entry:

```yaml
plugins:
  - search
  - redirects:
      redirect_maps: {}
  - mkdocstrings:
      handlers:
        python:
          paths: [src]
          options:
            docstring_style: google
            show_source: true
            heading_level: 2
            show_root_heading: true
            show_symbol_type_heading: true
            members_order: source
            filters:
              - "!^_"
            show_signature_annotations: true
            separate_signature: true
            allow_inspection: false
```

Key constraints from RESEARCH.md:
- `paths: [src]` is MANDATORY — without it griffe cannot locate ztlctl in the docs CI env (which uses bare pip, not uv). This forces AST visitor mode.
- `allow_inspection: false` — forces griffe to use static AST analysis; prevents dynamic import attempts that would fail because ztlctl's runtime deps (SQLAlchemy, pluggy, etc.) are not installed in the docs CI env.
- Do NOT add `show_inheritance_diagram: true` — mkdocs-shadcn has alpha-status mkdocstrings support; mermaid/inheritance diagrams may not render.

**docs.yml** — Update the pip install step (line 27) to add mkdocstrings:

```
pip install mkdocs==1.6.1 mkdocs-shadcn==0.10.2 mkdocs-redirects==1.2.2 "mkdocstrings[python]>=1.0.3"
```

After both changes, run `mkdocs build` locally to confirm it completes without errors (even though api-reference.md does not yet exist — the plugin should load cleanly with no directives to parse). If `mkdocs build` is not available locally, verify the YAML syntax is correct by reading it back.
  </action>
  <verify>
    <automated>cd /Users/shparki/Documents/Workspace/thatdev/ztlctl && grep -c 'mkdocstrings' mkdocs.yml && grep 'mkdocstrings' .github/workflows/docs.yml</automated>
  </verify>
  <done>
mkdocs.yml plugins block contains mkdocstrings handler with paths: [src] and allow_inspection: false.
docs.yml pip install line includes "mkdocstrings[python]>=1.0.3".
`mkdocs build` completes without errors (warning: api-reference.md not yet present is acceptable).
  </done>
</task>

</tasks>

<verification>
- `grep 'mkdocstrings' pyproject.toml` returns a line with `mkdocstrings[python]>=1.0.3`
- `grep 'paths' mkdocs.yml` returns `paths: [src]`
- `grep 'allow_inspection' mkdocs.yml` returns `allow_inspection: false`
- `grep 'mkdocstrings' .github/workflows/docs.yml` returns the updated pip install line
</verification>

<success_criteria>
mkdocstrings is installed as a dev dep and configured in mkdocs.yml with the correct handler options (paths: [src], allow_inspection: false, docstring_style: google). CI docs workflow includes mkdocstrings in its pip install. `mkdocs build` runs without errors.
</success_criteria>

<output>
After completion, create `.planning/phases/11-developer-guide-api-reference/11-01-SUMMARY.md`
</output>
