---
phase: 05-publish-and-deploy
plan: 02
subsystem: infra
tags: [mkdocs, github-actions, github-pages, docs, custom-domain, deploy]

# Dependency graph
requires:
  - phase: 04-docs
    provides: MkDocs docs site with material theme, CNAME, requirements.txt
provides:
  - CNAME updated to docs.guard.meshulash.ai (GitHub Pages custom domain preserved)
  - mkdocs.yml site_url updated to https://docs.guard.meshulash.ai
  - GitHub Actions workflow auto-deploying docs to gh-pages on push to main
affects:
  - docs repo deployment
  - any phase referencing docs site URL

# Tech tracking
tech-stack:
  added: [github-actions, actions/checkout@v4, actions/setup-python@v5, actions/cache@v4]
  patterns: [mkdocs gh-deploy with git user config, pip cache keyed on requirements.txt hash]

key-files:
  created: [docs/.github/workflows/deploy.yml]
  modified: [docs/docs/CNAME, docs/mkdocs.yml]

key-decisions:
  - "docs.guard.meshulash.ai replaces docs.meshulash.ai as the custom domain for the docs site"
  - "Git user configured as github-actions[bot] before mkdocs gh-deploy to satisfy git identity requirement"
  - "pip cache key uses hashFiles('requirements.txt') for deterministic caching"

patterns-established:
  - "CNAME in docs/docs/ (docs_dir) so mkdocs copies it to site/ and gh-deploy preserves custom domain"
  - "workflow-level permissions: contents: write sufficient for single-job gh-pages deploy"

# Metrics
duration: 1min
completed: 2026-02-27
---

# Phase 5 Plan 02: Docs Domain and Deploy Workflow Summary

**CNAME updated to docs.guard.meshulash.ai and GitHub Actions workflow created to auto-deploy MkDocs site to gh-pages on push to main in the docs repo**

## Performance

- **Duration:** ~1 min
- **Started:** 2026-02-27T13:24:02Z
- **Completed:** 2026-02-27T13:24:59Z
- **Tasks:** 2
- **Files modified:** 3

## Accomplishments
- Updated CNAME from `docs.meshulash.ai` to `docs.guard.meshulash.ai` so GitHub Pages serves on the correct custom domain
- Updated `mkdocs.yml` `site_url` to `https://docs.guard.meshulash.ai` so canonical URLs and sitemap point to the new domain
- Created `.github/workflows/deploy.yml` inside the docs repo triggering `mkdocs gh-deploy --force` on every push to `main`

## Task Commits

Each task was committed atomically (inside docs submodule):

1. **Task 1: Update CNAME and mkdocs.yml for new domain** - `f844da6` (chore)
2. **Task 2: Create docs deploy workflow** - `f6bb0ca` (feat)

## Files Created/Modified
- `docs/docs/CNAME` - Changed from `docs.meshulash.ai` to `docs.guard.meshulash.ai`
- `docs/mkdocs.yml` - `site_url` changed to `https://docs.guard.meshulash.ai`
- `docs/.github/workflows/deploy.yml` - New workflow: push to main → mkdocs gh-deploy --force

## Decisions Made
- Used `github-actions[bot]` with the canonical no-reply email `41898282+github-actions[bot]@users.noreply.github.com` for git user config — required by mkdocs gh-deploy to commit to gh-pages
- workflow-level `permissions: contents: write` (not job-level) — sufficient for single-job deploy, simpler
- pip cache restore key is `mkdocs-material-` (prefix) so partial cache hits still work on requirements.txt changes

## Deviations from Plan

None - plan executed exactly as written. The `docs/` directory being a git submodule required committing from within it rather than the root repo, but this was consistent with how the submodule is structured.

## Issues Encountered
- `docs/` is a git submodule — staging files with `git add docs/...` from the root repo fails with "Pathspec is in submodule". Committed from within `cd docs/` instead. Not a blocker, resolved immediately.

## User Setup Required
None - no external service configuration required beyond what was already in place for the docs GitHub repo (GitHub Pages must already be enabled pointing to gh-pages branch).

## Next Phase Readiness
- Docs repo now has auto-deploy workflow and correct custom domain config
- Ready for Plan 03: PyPI publishing and SDK CI/CD setup
- No blockers

---
*Phase: 05-publish-and-deploy*
*Completed: 2026-02-27*
