---
phase: 11-developer-guide-api-reference
plan: 03
type: execute
wave: 2
depends_on:
  - 11-01
files_modified:
  - docs/api-reference.md
autonomous: true
requirements:
  - DVGD-02

must_haves:
  truths:
    - "docs/api-reference.md exists with ::: directives for all 5 public API modules"
    - "`mkdocs build` succeeds with mkdocstrings rendering the API reference without errors"
    - "The API reference page covers: hookspecs, contracts, _version, actions.definitions, actions.registry"
    - "griffe resolves all 5 modules via static AST visitor (paths: [src], allow_inspection: false)"
  artifacts:
    - path: "docs/api-reference.md"
      provides: "Auto-generated API reference via mkdocstrings directives"
      min_lines: 40
      contains: "ztlctl.plugins.hookspecs"
  key_links:
    - from: "docs/api-reference.md"
      to: "src/ztlctl/plugins/hookspecs.py"
      via: "::: ztlctl.plugins.hookspecs directive"
      pattern: "ztlctl\\.plugins\\.hookspecs"
    - from: "docs/api-reference.md"
      to: "src/ztlctl/actions/registry.py"
      via: "::: ztlctl.actions.registry directive"
      pattern: "ztlctl\\.actions\\.registry"
---

<objective>
Create `docs/api-reference.md` — the auto-generated API reference page using mkdocstrings `::: module.path` directives for all 5 public API modules. This page is rendered at build time by griffe reading source AST.

Purpose: Satisfies DVGD-02. The API reference stays current with the code automatically — no manual maintenance of parameter tables.
Output: docs/api-reference.md with 5 module directives; `mkdocs build` succeeds without errors.
</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/phases/11-developer-guide-api-reference/11-RESEARCH.md
@.planning/phases/11-developer-guide-api-reference/11-01-SUMMARY.md
</context>

<tasks>

<task type="auto">
  <name>Task 1: Create docs/api-reference.md with mkdocstrings directives</name>
  <files>docs/api-reference.md</files>
  <read_first>
    - src/ztlctl/plugins/hookspecs.py (confirm module path and public class name: ZtlctlSpec or ZtlctlHookSpec)
    - src/ztlctl/plugins/contracts.py (confirm module path and what's exported)
    - src/ztlctl/plugins/_version.py (confirm PLUGIN_API_VERSION, PluginLoadError, check_plugin_api_version are public)
    - src/ztlctl/actions/definitions.py (confirm ActionParam, ActionDefinition are public)
    - src/ztlctl/actions/registry.py (confirm ActionRegistry, get_action_registry are public)
    - mkdocs.yml (verify mkdocstrings plugin is present from Plan 01)
  </read_first>
  <action>
Create `docs/api-reference.md` with the structure below. The exact module paths in `::: ztlctl.*` directives must match the actual Python module structure — read the source files above to verify paths before writing.

**File content:**

```markdown
# API Reference

Auto-generated from Python source using [mkdocstrings](https://mkdocstrings.github.io/python/).
All signatures and docstrings reflect the current `src/ztlctl/` codebase.

!!! note "Scope"
    This reference covers the **plugin public API** only — the contracts, hookspecs, and action system
    that plugin authors and advanced integrators interact with. Internal service and infrastructure
    layers are not documented here.

## Plugin Hookspecs

The `ZtlctlSpec` class defines all pluggy hookspecs. Implement any subset of these in your plugin class.

::: ztlctl.plugins.hookspecs
    options:
      show_root_heading: true
      heading_level: 3
      members_order: source
      show_source: true
      show_signature_annotations: true
      separate_signature: true
      filters:
        - "!^_"

## Plugin Contracts

Data classes returned from and passed to hookspecs.

::: ztlctl.plugins.contracts
    options:
      show_root_heading: true
      heading_level: 3
      members_order: source
      show_source: false
      show_signature_annotations: true

## API Versioning

::: ztlctl.plugins._version
    options:
      show_root_heading: true
      heading_level: 3
      show_source: false
      members_order: source
      filters:
        - "!^_COMPATIBILITY"

## Action System

`ActionDefinition` and `ActionParam` are the frozen dataclasses that describe every registered action.
Plugin authors use these when implementing `register_note_types()` — PluginManager auto-creates
`ActionDefinition` instances for each `NoteTypeDefinition` returned.

::: ztlctl.actions.definitions
    options:
      show_root_heading: true
      heading_level: 3
      show_source: false
      show_signature_annotations: true

::: ztlctl.actions.registry
    options:
      show_root_heading: true
      heading_level: 3
      show_source: false
      show_signature_annotations: true
      filters:
        - "!^_"
```

**Critical constraints from RESEARCH.md:**
- Do NOT add `::: ztlctl.services.*` or `::: ztlctl.infrastructure.*` — internal modules only; would produce massive unintended output
- Do NOT use `members: true` override on hookspecs — the default `!^_` filter handles private members correctly
- The `show_source: true` on hookspecs is intentional — plugin authors benefit from seeing real signatures
- `show_source: false` on contracts/registry keeps the page focused on API surface, not implementation
- Use `heading_level: 3` for module-level headings (page uses H2 for sections, H3 for modules within sections)

**After writing the file:**
Run `mkdocs build` locally to verify it succeeds. If griffe emits warnings about unresolved cross-references (e.g., `~ztlctl.plugins.contracts.ActionRejection`), these are expected behavior and not errors — cross-module ref formatting is correct. If `mkdocs build` fails with errors, check:
1. Module path typos in directives (must match actual Python package structure)
2. `paths: [src]` and `allow_inspection: false` are present in mkdocs.yml (from Plan 01)
3. `mkdocstrings[python]` is in the virtual environment

If build fails due to griffe warnings treated as errors in strict mode, do NOT use `--strict` flag. The existing docs.yml CI workflow uses `mkdocs gh-deploy` without `--strict` — this is the correct behavior.
  </action>
  <verify>
    <automated>cd /Users/shparki/Documents/Workspace/thatdev/ztlctl && test -f docs/api-reference.md && grep -c "ztlctl\." docs/api-reference.md</automated>
  </verify>
  <done>
docs/api-reference.md exists with 5 module directives covering: ztlctl.plugins.hookspecs, ztlctl.plugins.contracts, ztlctl.plugins._version, ztlctl.actions.definitions, ztlctl.actions.registry.
`mkdocs build` completes without errors (griffe warnings about cross-refs are acceptable; errors are not).
  </done>
</task>

</tasks>

<verification>
- `test -f docs/api-reference.md` passes
- `grep "ztlctl.plugins.hookspecs" docs/api-reference.md` matches
- `grep "ztlctl.actions.registry" docs/api-reference.md` matches
- `grep -c "^:::" docs/api-reference.md` returns 5
- `mkdocs build` exits 0
</verification>

<success_criteria>
docs/api-reference.md contains 5 mkdocstrings directives. `mkdocs build` completes without errors. griffe successfully parses all 5 modules using static AST visitor mode (paths: [src], allow_inspection: false).
</success_criteria>

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