---
# .github/workflows/docs-sync.md  ·  GitHub Agentic Workflow (gh-aw)
# QRefAI AI Coding Field Guide, Part 3 (Q3.6)
#
# Keeps docs in sync with code. READ-ONLY token; proposes changes via the
# create-pull-request safe output (a sanitized, declarative op) — it never pushes
# to a branch directly. Compile with:  gh aw compile --strict
on:
  push:
    branches: [main]
    paths:
      - "internal/**/*.go"
      - "docs/**"

permissions:
  contents: read

safe-outputs:
  create-pull-request:    # declarative, limited — not raw git write access
    max: 1
    draft: true
---

# Docs sync

When code on `main` changes in a way that affects documented behavior:

1. Compare the changed code against the relevant docs in `docs/`.
2. Where docs are now stale (changed signatures, new/removed endpoints, altered
   behavior), draft the minimal doc updates to match the code.
3. Open ONE draft pull request with those doc-only changes and a summary of what
   drifted and why.

Only touch files under `docs/`. Do not change code. If nothing drifted, do nothing.
Keep edits surgical — match the existing doc voice and structure.