---
phase: 08-mkdocs-infrastructure
plan: "03"
type: execute
wave: 2
depends_on:
  - "08-02"
files_modified:
  - .github/workflows/docs.yml
autonomous: false
requirements:
  - INFR-04
must_haves:
  truths:
    - ".github/workflows/docs.yml exists and triggers on push to develop"
    - "The workflow uses `contents: write` permission"
    - "The workflow runs `mkdocs gh-deploy --force`"
    - "GitHub Pages source is switched to gh-pages branch (after first successful deploy)"
  artifacts:
    - path: ".github/workflows/docs.yml"
      provides: "GitHub Actions MkDocs deploy workflow"
      contains: "mkdocs gh-deploy"
  key_links:
    - from: ".github/workflows/docs.yml"
      to: "gh-pages branch"
      via: "mkdocs gh-deploy --force"
      pattern: "gh-deploy"
---

<objective>
Create the GitHub Actions workflow that deploys the MkDocs site to GitHub Pages on every push to develop. Then pause for the user to update the GitHub Pages source setting from `develop/docs/` to the `gh-pages` branch — a one-time manual step that cannot be automated.

Purpose: Without this workflow, the MkDocs site never deploys. Without the Pages source switch, the workflow runs successfully but the live site still shows the old Jekyll content.
Output: .github/workflows/docs.yml created; user verifies Pages source setting is updated.
</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/08-mkdocs-infrastructure/08-CONTEXT.md
@.planning/phases/08-mkdocs-infrastructure/08-RESEARCH.md
@.planning/phases/08-mkdocs-infrastructure/08-02-SUMMARY.md

<interfaces>
<!-- Existing CI workflow pattern to follow -->
<!-- .github/workflows/release-pipeline.yml trigger pattern: -->
<!--   on: -->
<!--     push: -->
<!--       branches: [develop] -->
<!--     workflow_dispatch: -->
<!-- This docs.yml must use the same trigger pattern -->

<!-- mkdocs gh-deploy requirements: -->
<!-- - permissions: contents: write  (must push to gh-pages branch) -->
<!-- - fetch-depth: 0                (must see gh-pages branch history) -->
<!-- - git config user.name + user.email before deploy -->
<!-- - pip install (not uv) — CI only needs docs tools, not full ztlctl env -->
</interfaces>
</context>

<tasks>

<task type="auto">
  <name>Task 1: Create .github/workflows/docs.yml</name>
  <files>.github/workflows/docs.yml</files>

  <read_first>
    - .github/workflows/release-pipeline.yml — read first 40 lines for trigger pattern and job structure to follow
    - .github/workflows/pr-ci.yml — read first 30 lines for steps pattern (actions/checkout@v4, actions/setup-python@v5 versions)
    - .planning/phases/08-mkdocs-infrastructure/08-RESEARCH.md — "GitHub Actions Docs Workflow" section has the verified workflow template
  </read_first>

  <action>
    Create `.github/workflows/docs.yml` with this exact content:

    ```yaml
    name: Deploy Docs

    on:
      push:
        branches: [develop]
      workflow_dispatch:

    permissions:
      contents: write

    jobs:
      deploy:
        name: Deploy to GitHub Pages
        runs-on: ubuntu-latest
        steps:
          - name: Check out repository
            uses: actions/checkout@v4
            with:
              fetch-depth: 0

          - name: Set up Python
            uses: actions/setup-python@v5
            with:
              python-version: '3.x'

          - name: Install MkDocs dependencies
            run: pip install mkdocs==1.6.1 mkdocs-shadcn==0.10.2 mkdocs-redirects==1.2.2

          - name: Configure git identity
            run: |
              git config user.name "github-actions[bot]"
              git config user.email "41898282+github-actions[bot]@users.noreply.github.com"

          - name: Deploy docs
            run: mkdocs gh-deploy --force
    ```

    Key points:
    - `permissions: contents: write` is a top-level key (workflow level), not inside the job — this grants the `GITHUB_TOKEN` write access to push to the `gh-pages` branch
    - `fetch-depth: 0` is required so `mkdocs gh-deploy` can find the `gh-pages` branch in the remote refs
    - Versions are pinned exactly: `mkdocs==1.6.1 mkdocs-shadcn==0.10.2 mkdocs-redirects==1.2.2` — matches the versions in pyproject.toml dev dependencies
    - `pip install` (not `uv`) — CI only needs the docs tools, not the full ztlctl project environment
    - `workflow_dispatch:` allows manual triggering from the GitHub Actions UI during migration testing
  </action>

  <verify>
    <automated>test -f .github/workflows/docs.yml && grep -c "mkdocs gh-deploy" .github/workflows/docs.yml && grep -c "contents: write" .github/workflows/docs.yml && grep -c "fetch-depth: 0" .github/workflows/docs.yml</automated>
  </verify>

  <acceptance_criteria>
    - `test -f .github/workflows/docs.yml` exits 0
    - `grep "mkdocs gh-deploy --force" .github/workflows/docs.yml` returns a match
    - `grep "contents: write" .github/workflows/docs.yml` returns a match
    - `grep "fetch-depth: 0" .github/workflows/docs.yml` returns a match
    - `grep "workflow_dispatch" .github/workflows/docs.yml` returns a match
    - `grep "branches: \[develop\]" .github/workflows/docs.yml` returns a match
    - `grep "mkdocs==1.6.1" .github/workflows/docs.yml` returns a match
    - `grep "actions/checkout@v4" .github/workflows/docs.yml` returns a match
    - YAML is valid: `python3 -c "import yaml; yaml.safe_load(open('.github/workflows/docs.yml'))"` exits 0
  </acceptance_criteria>

  <done>.github/workflows/docs.yml exists with correct trigger, permissions, pinned versions, and deploy command</done>
</task>

<task type="checkpoint:human-verify" gate="blocking">
  <name>Checkpoint: Verify GitHub Pages source and live site</name>
  <files>N/A — no files modified in this checkpoint</files>

  <action>
    This is a human verification checkpoint. No automated action. After the PR merges to develop:
    1. Confirm the "Deploy Docs" GitHub Actions workflow ran green at https://github.com/ThatDevStudio/ztlctl/actions
    2. Update GitHub Pages source to gh-pages branch at https://github.com/ThatDevStudio/ztlctl/settings/pages: change from "Deploy from a branch: develop / docs" to "Deploy from a branch: gh-pages / (root)" and save
    3. Wait ~60 seconds for Pages to rebuild, then verify the live site at https://thatdevstudio.github.io/ztlctl/
  </action>

  <verify>
    <automated>echo "Manual verification required — see how-to-verify steps below"</automated>
  </verify>

  <what-built>
    GitHub Actions docs.yml workflow created. When merged to develop, it will run `mkdocs gh-deploy --force` which pushes the built site to the `gh-pages` branch.

    REQUIRED MANUAL STEP: After the first successful workflow run, you must update GitHub Pages source from "develop/docs/" to "gh-pages branch" in repository settings. Without this change, the live site will continue showing the old Jekyll content even though the workflow runs successfully.
  </what-built>
  <how-to-verify>
    After this PR is merged to develop and the docs.yml workflow completes successfully:

    1. Go to https://github.com/ThatDevStudio/ztlctl/actions — confirm "Deploy Docs" workflow ran green
    2. Go to https://github.com/ThatDevStudio/ztlctl/settings/pages
    3. Under "Build and deployment" → "Source": change from "Deploy from a branch: develop / docs" to "Deploy from a branch: gh-pages / (root)"
    4. Save the setting
    5. Wait ~60 seconds for Pages to rebuild from the gh-pages branch
    6. Visit https://thatdevstudio.github.io/ztlctl/ — confirm the site shows the new MkDocs/shadcn theme (not the old Just the Docs theme)
    7. Verify the search bar is present (confirms search plugin is wired correctly)
    8. Verify dark/light mode toggle is present (confirms shadcn theme loaded)
    9. Verify the navigation shows exactly: Home, Installation, Quick Start, Tutorial, Core Concepts, Knowledge Paradigms, Obsidian Starter Kit, Command Reference, Configuration, MCP Server, Agentic Workflows, Troubleshooting, Development (13 items)
    10. Visit https://thatdevstudio.github.io/ztlctl/backlog/ — confirm 404 (internal artifact correctly excluded)
  </how-to-verify>
  <resume-signal>Type "approved" once the live site shows MkDocs/shadcn theme and Pages source has been updated. Or describe any issues observed.</resume-signal>

  <done>Live site at https://thatdevstudio.github.io/ztlctl/ renders MkDocs/shadcn theme and GitHub Pages source is set to gh-pages branch</done>
</task>

</tasks>

<verification>
Pre-merge (automated):
- `test -f .github/workflows/docs.yml` — file exists
- `python3 -c "import yaml; yaml.safe_load(open('.github/workflows/docs.yml'))"` — valid YAML
- `grep "contents: write" .github/workflows/docs.yml` — permission present
- `grep "mkdocs gh-deploy --force" .github/workflows/docs.yml` — deploy command present

Post-merge (manual — see checkpoint task):
- GitHub Actions "Deploy Docs" workflow green
- GitHub Pages source updated to gh-pages branch
- Live site at https://thatdevstudio.github.io/ztlctl/ renders MkDocs/shadcn theme
</verification>

<success_criteria>
.github/workflows/docs.yml created with correct trigger (push to develop), permissions (contents: write), pinned dependency versions, and deploy command (mkdocs gh-deploy --force). After merge and Pages source update, the live site shows the new MkDocs/shadcn theme.
</success_criteria>

<output>
After completion, create `.planning/phases/08-mkdocs-infrastructure/08-03-SUMMARY.md`
</output>
