---
phase: 14-documentation-content-refinement-and-quality-pass
plan: 01
type: execute
wave: 1
depends_on: []
files_modified:
  - docs/configuration.md
  - docs/troubleshooting.md
  - docs/guide/index.md
autonomous: true
requirements: []

must_haves:
  truths:
    - "configuration.md shows [plugins.git] not [git] for git plugin config"
    - "configuration.md documents all config sections from models.py including [tags] and [workflow]"
    - "troubleshooting.md documents ZTLCTL_DOCS_PATH env var fix"
    - "troubleshooting.md documents GitHub Pages source setting manual step"
    - "guide/index.md has Built-in Plugins row in the In This Guide table"
  artifacts:
    - path: "docs/configuration.md"
      provides: "Source-verified configuration reference"
      contains: "[plugins.git]"
    - path: "docs/troubleshooting.md"
      provides: "ZTLCTL_DOCS_PATH and Pages source fixes"
      contains: "ZTLCTL_DOCS_PATH"
    - path: "docs/guide/index.md"
      provides: "Complete User Guide landing with Built-in Plugins row"
      contains: "Built-in Plugins"
  key_links:
    - from: "docs/configuration.md"
      to: "src/ztlctl/config/models.py"
      via: "source verification"
      pattern: "plugins\\.git"
    - from: "docs/troubleshooting.md"
      to: "src/ztlctl/services/docs.py"
      via: "env var documentation"
      pattern: "ZTLCTL_DOCS_PATH"
---

<objective>
Fix all three known audit gaps (INT-01, FLOW-01, ZTLCTL_DOCS_PATH) and rewrite configuration.md to match models.py source of truth. These are the highest-priority corrections that close verified discrepancies.

Purpose: Eliminate known factual errors and documentation gaps identified in the v2.1 milestone audit before the broader quality pass begins.
Output: Three corrected documentation files with source-verified content.
</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: Rewrite configuration.md with source-verified config sections</name>
  <files>docs/configuration.md</files>
  <read_first>
    - src/ztlctl/config/models.py (source of truth for all config sections, fields, defaults)
    - docs/configuration.md (current state — 96 lines, has incorrect [git] section)
    - docs/plugins.md (reference for correct [plugins.git] usage pattern)
  </read_first>
  <action>
Rewrite docs/configuration.md to be a complete, source-verified configuration reference. Read every Pydantic model class in models.py and document every field with its type, default value, and purpose.

**Critical fix**: Replace the incorrect top-level `[git]` TOML section with `[plugins.git]`. The correct TOML block is:
```toml
[plugins.git]
enabled = true
batch_commits = true
auto_push = false
auto_ignore = true
branch = "develop"
commit_style = "conventional"
```

**Missing sections to add** (verified from models.py):
1. `[tags]` section — `TagsConfig` has field `auto_register: bool = True`
2. `[workflow]` section — `WorkflowConfig` has fields `template: str = ""`, `skill_set: str = ""`
3. Missing fields in `[agent_context]` — add `layer_0_min` (default: 500), `layer_1_min` (default: 1000)
4. Missing fields in `[search]` — add `semantic_enabled` (default: false), `embedding_model` (default: "local"), `embedding_dim` (default: 384)
5. Missing field in `[session]` — add `orphan_reweave_threshold` (default: 0.2)

**Environment Variables section**: Add `ZTLCTL_DOCS_PATH` as a special environment variable:
- Purpose: Override package-relative docs path for `ztlctl docs search`
- When needed: Non-editable (pip) installs where package-relative path resolution fails
- Example: `export ZTLCTL_DOCS_PATH=/path/to/ztlctl/docs`

**Structure**: Use tables for each config section showing field name, type, default, and description. Follow mentor tone. Add a complete TOML example at the end showing all sections with their defaults.

**Heading hierarchy**: H1 title, H2 for major sections (File Location, Config Sections, Environment Variables, Complete Example), H3 for individual config sections ([vault], [reweave], etc.).

Ensure at least 2 concrete real-world examples (e.g., "research-heavy vault config" and "minimal daily notes config" showing different setting combinations).
  </action>
  <verify>
    <automated>grep -c "plugins.git" docs/configuration.md && grep -c "ZTLCTL_DOCS_PATH" docs/configuration.md && grep -c "\[tags\]" docs/configuration.md && grep -c "\[workflow\]" docs/configuration.md && ! grep "^\[git\]" docs/configuration.md</automated>
  </verify>
  <acceptance_criteria>
    - docs/configuration.md contains `[plugins.git]` (not bare `[git]`)
    - docs/configuration.md contains `ZTLCTL_DOCS_PATH`
    - docs/configuration.md contains `[tags]` section with `auto_register`
    - docs/configuration.md contains `[workflow]` section with `template` and `skill_set`
    - docs/configuration.md contains `layer_0_min` and `layer_1_min` in agent_context section
    - docs/configuration.md contains `semantic_enabled`, `embedding_model`, `embedding_dim` in search section
    - docs/configuration.md contains `orphan_reweave_threshold` in session section
    - `grep "^\[git\]" docs/configuration.md` returns no matches (no bare [git] section)
    - File has at least 150 lines (was 96, now covers all sections)
  </acceptance_criteria>
  <done>configuration.md is a complete, source-verified config reference with every section from models.py documented, all fields with types and defaults, ZTLCTL_DOCS_PATH env var, and the incorrect [git] section replaced with [plugins.git]</done>
</task>

<task type="auto">
  <name>Task 2: Add troubleshooting entries for ZTLCTL_DOCS_PATH and GitHub Pages source</name>
  <files>docs/troubleshooting.md</files>
  <read_first>
    - docs/troubleshooting.md (current state — 107 lines)
    - src/ztlctl/services/docs.py (lines 42-59 for ZTLCTL_DOCS_PATH behavior)
  </read_first>
  <action>
Add two new troubleshooting entries to docs/troubleshooting.md:

**Entry 1: "ztlctl docs search returns 'docs path not found'"**
```markdown
### ztlctl docs search returns "docs path not found"

**Cause**: `ztlctl docs search` needs access to the `docs/` directory. In a pip-installed (non-editable) environment, the package-relative path discovery fails.

**Fix**:

```bash
# Point ztlctl to your local docs checkout
export ZTLCTL_DOCS_PATH=/path/to/ztlctl/docs
ztlctl docs search "your query"
```

This is the designed behavior — `ZTLCTL_DOCS_PATH` is the user-facing override for non-editable installs. See [Configuration > Environment Variables](configuration.md#environment-variables) for details.
```

**Entry 2: "GitHub Pages not updating after deploy"**
```markdown
### GitHub Pages not updating after deploy

**Cause**: The GitHub Pages source must be set to "GitHub Actions" in repository settings. The default "Deploy from a branch" setting will not pick up artifact-based deployments.

**Fix**:

1. Go to your repository Settings > Pages
2. Under "Build and deployment" > Source > select **GitHub Actions**
3. Trigger a new deploy by pushing any change or re-running the docs workflow

This is a one-time setup step. Once configured, all subsequent pushes to `develop` will auto-deploy.
```

Place these entries in a logical position within the existing troubleshooting page (after existing entries). Preserve all existing content verbatim.
  </action>
  <verify>
    <automated>grep -c "ZTLCTL_DOCS_PATH" docs/troubleshooting.md && grep -c "GitHub Pages not updating" docs/troubleshooting.md</automated>
  </verify>
  <acceptance_criteria>
    - docs/troubleshooting.md contains "ZTLCTL_DOCS_PATH"
    - docs/troubleshooting.md contains "GitHub Pages not updating after deploy"
    - docs/troubleshooting.md contains "GitHub Actions" (the fix)
    - docs/troubleshooting.md contains cross-link to configuration.md
    - All existing troubleshooting entries are preserved (file >= 140 lines)
  </acceptance_criteria>
  <done>troubleshooting.md has both new entries: ZTLCTL_DOCS_PATH fix and GitHub Pages source setting, with cross-links to configuration.md</done>
</task>

<task type="auto">
  <name>Task 3: Fix guide/index.md — add Built-in Plugins row (INT-01)</name>
  <files>docs/guide/index.md</files>
  <read_first>
    - docs/guide/index.md (current state — 18 lines, missing Built-in Plugins row)
    - docs/plugins.md (first few lines for accurate description)
  </read_first>
  <action>
Add the Built-in Plugins row to the "In This Guide" table in docs/guide/index.md. Insert after the Obsidian Starter Kit row:

```markdown
| [Built-in Plugins](../plugins.md) | Git and Reweave plugin guides — config, triggers, and scenarios |
```

This closes audit gap INT-01. The row links to plugins.md using relative path `../plugins.md` (guide/index.md is one level deep).
  </action>
  <verify>
    <automated>grep "Built-in Plugins" docs/guide/index.md</automated>
  </verify>
  <acceptance_criteria>
    - docs/guide/index.md contains "Built-in Plugins" in a table row
    - docs/guide/index.md contains "../plugins.md" link
    - docs/guide/index.md contains "Git and Reweave" description text
  </acceptance_criteria>
  <done>guide/index.md has the Built-in Plugins row in the "In This Guide" table, closing INT-01</done>
</task>

</tasks>

<verification>
All three audit gaps closed:
- INT-01: `grep "Built-in Plugins" docs/guide/index.md` returns a match
- FLOW-01: `grep "GitHub Pages not updating" docs/troubleshooting.md` returns a match
- ZTLCTL_DOCS_PATH: `grep "ZTLCTL_DOCS_PATH" docs/troubleshooting.md docs/configuration.md` returns matches in both files
- Config fix: `grep "^\[git\]" docs/configuration.md` returns NO matches (replaced with [plugins.git])
</verification>

<success_criteria>
- All three audit gaps (INT-01, FLOW-01, ZTLCTL_DOCS_PATH) are closed
- configuration.md is source-verified against models.py with all sections documented
- No bare [git] section exists in configuration.md
- troubleshooting.md has both new entries with cross-links
- guide/index.md has the Built-in Plugins table row
</success_criteria>

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