diff --git a/.github/templates/api-reference-update-pr.md b/.github/templates/api-reference-update-pr.md
deleted file mode 100644
index 143cf016..00000000
--- a/.github/templates/api-reference-update-pr.md
+++ /dev/null
@@ -1,5 +0,0 @@
-
-
-closes #{{ISSUE_NUMBER}}
-
-{{SHORT_DESCRIPTION}}
diff --git a/.github/templates/docs/demos-issue.md b/.github/templates/docs/demos-issue.md
deleted file mode 100644
index 28a5dfe8..00000000
--- a/.github/templates/docs/demos-issue.md
+++ /dev/null
@@ -1,22 +0,0 @@
-
-
-
-
-## Summary
-Demo code for `{{COMPONENT_NAME}}` may use APIs that changed in a recent PR. Demo fixes need human judgment — this issue is for triage.
-
-## References
-- Triggering PR(s): {{SOURCE_PR_URLS}}
-
-## Affected Demos
-| Demo File | Issue | API Change | Suggested Fix |
-|---|---|---|---|
-{{AFFECTED_DEMOS_TABLE_ROWS}}
-
-### Demo Locations
-- HTML demos: `site/src/components/docs/demos/{{COMPONENT_SLUG}}/html/css/`
-- React demos: `site/src/components/docs/demos/{{COMPONENT_SLUG}}/react/css/`
-
-## Notes
-- Demo updates require human review — automated fixes are not attempted.
-- Check both HTML and React demo variants.
diff --git a/.github/templates/docs/guide-references-issue.md b/.github/templates/docs/guide-references-issue.md
deleted file mode 100644
index b9c5e7fb..00000000
--- a/.github/templates/docs/guide-references-issue.md
+++ /dev/null
@@ -1,24 +0,0 @@
-
-
-
-
-## Summary
-Pages outside `/reference/` mention APIs that changed in a recent PR. These references may be stale and need human triage.
-
-## References
-- Triggering PR(s): {{SOURCE_PR_URLS}}
-
-## Stale References Found
-| File | Line(s) | Stale Reference | API Change | Confidence | Action |
-|---|---|---|---|---|---|
-{{STALE_REFERENCES_TABLE_ROWS}}
-
-### Directories Checked
-- `site/src/content/docs/concepts/`
-- `site/src/content/docs/how-to/`
-- `packages/*/README.md`
-
-## Notes
-- **Confidence levels**: `high` = definitely stale, `medium` = likely stale, `low` = needs human review.
-- All items in this issue need human triage — false positives are possible.
-- Related APIs are grouped into a single issue when they affect the same files.
diff --git a/.github/templates/docs/reference-copy-issue.md b/.github/templates/docs/reference-copy-issue.md
deleted file mode 100644
index 7cd559ba..00000000
--- a/.github/templates/docs/reference-copy-issue.md
+++ /dev/null
@@ -1,40 +0,0 @@
-
-
-
-
-
-## Summary
-The hand-written MDX reference page for `{{COMPONENT_NAME}}` has drifted from the auto-generated API JSON.
-
-> The API JSON files are rebuilt on every sync run and are always current.
-> Drift listed here is in the **MDX prose**, not the generated data.
-
-## References
-- Triggering PR(s): {{SOURCE_PR_URLS}}
-- Triggering issue(s): {{SOURCE_PR_ISSUE_URLS}}
-
-## API Changes Summary
-| Surface | Change Type | Before | After | Source |
-|---|---|---|---|---|
-{{API_CHANGES_TABLE_ROWS}}
-
-## Out-of-Sync Docs
-| MDX File | Section | Drift Type | Current (MDX) | Expected (from JSON) | Action |
-|---|---|---|---|---|---|
-{{OUT_OF_SYNC_TABLE_ROWS}}
-
-## Sidebar Status
-- `site/src/docs.config.ts` entry: {{SIDEBAR_STATUS}}
-
-## Implementation Notes
-- Target files: {{TARGET_FILES_LIST}}
-- Drift-specific tasks: {{IMPLEMENTATION_TASKS}}
-- Validation commands:
- - `pnpm -C site api-docs`
- - `pnpm -C site build`
-
-## Scope Checklist
-- [ ] Update MDX reference page content for `{{COMPONENT_NAME}}`.
-- [ ] Update sidebar entries in `site/src/docs.config.ts` if required.
-- [ ] Regenerate API reference JSON (`pnpm -C site api-docs`).
-- [ ] Verify build (`pnpm -C site build`).
diff --git a/.github/workflows/api-reference-sync.yml b/.github/workflows/api-reference-sync.yml
index 5b884bec..c03069f5 100644
--- a/.github/workflows/api-reference-sync.yml
+++ b/.github/workflows/api-reference-sync.yml
@@ -1,7 +1,6 @@
name: API Reference Sync
on:
- workflow_dispatch:
pull_request:
types: [closed]
@@ -10,7 +9,6 @@ permissions:
contents: write
pull-requests: write
issues: write
- repository-projects: write
id-token: write
concurrency:
@@ -18,62 +16,14 @@ concurrency:
cancel-in-progress: true
jobs:
- # ─── Job 0: Lightweight shell gate ───────────────────────────────────
+ # ─── Job 0: Build API JSON at HEAD~1 and HEAD, diff them ─────────────
analyze:
- if: github.event_name == 'workflow_dispatch' || (github.event.pull_request.merged == true && github.event.pull_request.base.ref == 'main')
+ if: github.event.pull_request.merged == true && github.event.pull_request.base.ref == 'main'
runs-on: ubuntu-latest
outputs:
- has_changes: ${{ steps.check.outputs.has_changes }}
- pr_number: ${{ steps.context.outputs.pr_number }}
- pr_title: ${{ steps.context.outputs.pr_title }}
- pr_url: ${{ steps.context.outputs.pr_url }}
- pr_body: ${{ steps.context.outputs.pr_body }}
-
- steps:
- - name: Checkout code
- uses: actions/checkout@v5
-
- - name: Set PR context
- id: context
- env:
- PR_TITLE: ${{ github.event.pull_request.title || '' }}
- PR_BODY: ${{ github.event.pull_request.body || '' }}
- run: |
- echo "pr_number=${{ github.event.pull_request.number || '' }}" >> "$GITHUB_OUTPUT"
- echo "pr_title=$PR_TITLE" >> "$GITHUB_OUTPUT"
- echo "pr_url=${{ github.event.pull_request.html_url || '' }}" >> "$GITHUB_OUTPUT"
- EOF=$(dd if=/dev/urandom bs=15 count=1 status=none | base64)
- echo "pr_body<<$EOF" >> "$GITHUB_OUTPUT"
- echo "$PR_BODY" >> "$GITHUB_OUTPUT"
- echo "$EOF" >> "$GITHUB_OUTPUT"
-
- - name: Check for API-relevant changes
- id: check
- env:
- GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
- run: |
- if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
- echo "has_changes=true" >> "$GITHUB_OUTPUT"
- echo "workflow_dispatch — full scan"
- exit 0
- fi
-
- CHANGED=$(gh pr diff ${{ github.event.pull_request.number }} --name-only || true)
-
- if echo "$CHANGED" | grep -qE '^packages/(core/src/core/(ui|selectors)|html/src/ui|react/src/ui|store/src)/'; then
- echo "has_changes=true" >> "$GITHUB_OUTPUT"
- echo "API-relevant files changed"
- else
- echo "has_changes=false" >> "$GITHUB_OUTPUT"
- echo "No API-relevant changes detected"
- fi
-
- # ─── Job 1: Reference copy drift (Claude Opus) ──────────────────────
- docs-reference-copy:
- needs: analyze
- if: needs.analyze.outputs.has_changes == 'true'
- runs-on: ubuntu-latest
+ has_diff: ${{ steps.classify.outputs.has_diff }}
+ has_new: ${{ steps.classify.outputs.has_new }}
steps:
- name: Checkout code
@@ -81,204 +31,397 @@ jobs:
with:
fetch-depth: 0
- - name: Check reference copy drift
+ - uses: pnpm/action-setup@v4
+ - uses: actions/setup-node@v5
+ with:
+ node-version-file: '.nvmrc'
+ cache: pnpm
+
+ - name: Collect PR metadata
+ id: meta
+ env:
+ PR_TITLE: ${{ github.event.pull_request.title || 'manual run' }}
+ run: |
+ mkdir -p /tmp/api-sync
+
+ jq -n \
+ --arg number "${{ github.event.pull_request.number || '' }}" \
+ --arg url "${{ github.event.pull_request.html_url || '' }}" \
+ --arg author "${{ github.event.pull_request.user.login || '' }}" \
+ --arg title "$PR_TITLE" \
+ '{number: $number, url: $url, author: $author, title: $title}' \
+ > /tmp/api-sync/pr-meta.json
+
+ cat /tmp/api-sync/pr-meta.json
+
+ - name: Build API JSON at HEAD
+ run: |
+ pnpm install --frozen-lockfile
+ pnpm -C site api-docs
+
+ mkdir -p /tmp/api-sync/after-components /tmp/api-sync/after-utils
+ cp -r site/src/content/generated-component-reference/* /tmp/api-sync/after-components/ 2>/dev/null || true
+ cp -r site/src/content/generated-util-reference/* /tmp/api-sync/after-utils/ 2>/dev/null || true
+
+ - name: Build API JSON at HEAD~1
+ run: |
+ git checkout HEAD~1
+
+ # If install or build fails (e.g. api-docs-builder itself changed),
+ # treat everything as new by leaving before dirs empty
+ mkdir -p /tmp/api-sync/before-components /tmp/api-sync/before-utils
+
+ if pnpm install --frozen-lockfile && pnpm -C site api-docs; then
+ cp -r site/src/content/generated-component-reference/* /tmp/api-sync/before-components/ 2>/dev/null || true
+ cp -r site/src/content/generated-util-reference/* /tmp/api-sync/before-utils/ 2>/dev/null || true
+ else
+ echo "::warning::HEAD~1 build failed — treating all components/utils as new"
+ fi
+
+ git checkout -
+
+ - name: Classify changes
+ id: classify
+ run: |
+ # Unified diff of both JSON directories
+ diff -ruN /tmp/api-sync/before-components /tmp/api-sync/after-components > /tmp/api-sync/diff.patch || true
+ diff -ruN /tmp/api-sync/before-utils /tmp/api-sync/after-utils >> /tmp/api-sync/diff.patch || true
+
+ # New: files in after but not in before
+ comm -23 \
+ <(ls /tmp/api-sync/after-components/ 2>/dev/null | sort) \
+ <(ls /tmp/api-sync/before-components/ 2>/dev/null | sort) \
+ > /tmp/api-sync/new-components.txt
+
+ comm -23 \
+ <(ls /tmp/api-sync/after-utils/ 2>/dev/null | sort) \
+ <(ls /tmp/api-sync/before-utils/ 2>/dev/null | sort) \
+ > /tmp/api-sync/new-utils.txt
+
+ # Changed: files in both, but content differs
+ comm -12 \
+ <(ls /tmp/api-sync/after-components/ 2>/dev/null | sort) \
+ <(ls /tmp/api-sync/before-components/ 2>/dev/null | sort) \
+ | while read -r f; do
+ if ! diff -q "/tmp/api-sync/before-components/$f" "/tmp/api-sync/after-components/$f" >/dev/null 2>&1; then
+ echo "$f"
+ fi
+ done > /tmp/api-sync/changed-components.txt
+
+ comm -12 \
+ <(ls /tmp/api-sync/after-utils/ 2>/dev/null | sort) \
+ <(ls /tmp/api-sync/before-utils/ 2>/dev/null | sort) \
+ | while read -r f; do
+ if ! diff -q "/tmp/api-sync/before-utils/$f" "/tmp/api-sync/after-utils/$f" >/dev/null 2>&1; then
+ echo "$f"
+ fi
+ done > /tmp/api-sync/changed-utils.txt
+
+ # Log results
+ echo "=== New components ===" && cat /tmp/api-sync/new-components.txt
+ echo "=== New utils ===" && cat /tmp/api-sync/new-utils.txt
+ echo "=== Changed components ===" && cat /tmp/api-sync/changed-components.txt
+ echo "=== Changed utils ===" && cat /tmp/api-sync/changed-utils.txt
+ echo "=== Diff ===" && head -100 /tmp/api-sync/diff.patch
+
+ # Set outputs
+ if [ -s /tmp/api-sync/diff.patch ]; then
+ echo "has_diff=true" >> "$GITHUB_OUTPUT"
+ else
+ echo "has_diff=false" >> "$GITHUB_OUTPUT"
+ fi
+
+ if [ -s /tmp/api-sync/new-components.txt ] || [ -s /tmp/api-sync/new-utils.txt ]; then
+ echo "has_new=true" >> "$GITHUB_OUTPUT"
+ else
+ echo "has_new=false" >> "$GITHUB_OUTPUT"
+ fi
+
+ - name: Upload artifact
+ if: steps.classify.outputs.has_diff == 'true'
+ uses: actions/upload-artifact@v4
+ with:
+ name: api-diff
+ path: /tmp/api-sync/
+ retention-days: 1
+
+ # ─── Job 1: Open issues for new components/utils without reference pages
+ new-references:
+ needs: analyze
+ if: needs.analyze.outputs.has_new == 'true'
+ runs-on: ubuntu-latest
+
+ steps:
+ - name: Checkout code
+ uses: actions/checkout@v5
+
+ - name: Download artifact
+ uses: actions/download-artifact@v4
+ with:
+ name: api-diff
+ path: /tmp/api-sync
+
+ - name: Open issues for missing reference pages
+ env:
+ GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+ run: |
+ set -euo pipefail
+
+ PR_NUMBER=$(jq -r .number /tmp/api-sync/pr-meta.json)
+ PR_URL=$(jq -r .url /tmp/api-sync/pr-meta.json)
+ PR_AUTHOR=$(jq -r .author /tmp/api-sync/pr-meta.json)
+
+ REF_DIR="site/src/content/docs/reference"
+
+ # --- New components ---
+ if [ -s /tmp/api-sync/new-components.txt ]; then
+ while read -r filename; do
+ JSON_PATH="/tmp/api-sync/after-components/$filename"
+ NAME=$(jq -r .name "$JSON_PATH")
+ SLUG="${filename%.json}"
+
+ # Check if a reference page already uses this component
+ if grep -rq "\`
+ - [ ] Add sidebar entry in \`site/src/docs.config.ts\`
+ - [ ] Verify build: \`pnpm -C site build\`
+
+ ### Context
+ - Triggering PR: $PR_URL
+ - Generated JSON: \`site/src/content/generated-component-reference/$filename\`
+
+ > Use the \`/api-reference $SLUG\` skill to scaffold this page.
+ EOF
+ )"
+
+ gh issue create \
+ --title "docs(reference): add $NAME API reference page" \
+ --body "$BODY" \
+ --label "docs,docs:reference,site,components" \
+ $ASSIGNEE_FLAG
+
+ echo "Created issue for component $NAME"
+
+ done < /tmp/api-sync/new-components.txt
+ fi
+
+ # --- New utils ---
+ if [ -s /tmp/api-sync/new-utils.txt ]; then
+ while read -r filename; do
+ JSON_PATH="/tmp/api-sync/after-utils/$filename"
+ NAME=$(jq -r .name "$JSON_PATH")
+ SLUG="${filename%.json}"
+
+ # Check if a reference page already uses this util
+ if grep -rq "\`
+ - [ ] Add sidebar entry in \`site/src/docs.config.ts\`
+ - [ ] Verify build: \`pnpm -C site build\`
+
+ ### Context
+ - Triggering PR: $PR_URL
+ - Generated JSON: \`site/src/content/generated-util-reference/$filename\`
+
+ > Use the \`/api-reference $SLUG\` skill to scaffold this page.
+ EOF
+ )"
+
+ gh issue create \
+ --title "docs(reference): add $NAME API reference page" \
+ --body "$BODY" \
+ --label "docs,docs:reference,site" \
+ $ASSIGNEE_FLAG
+
+ echo "Created issue for util $NAME"
+
+ done < /tmp/api-sync/new-utils.txt
+ fi
+
+ # ─── Job 2: Detect stale docs (Claude Opus) ─────────────────────────
+ stale-docs:
+ needs: analyze
+ if: needs.analyze.outputs.has_diff == 'true'
+ runs-on: ubuntu-latest
+
+ steps:
+ - name: Checkout code
+ uses: actions/checkout@v5
+
+ - name: Download artifact
+ uses: actions/download-artifact@v4
+ with:
+ name: api-diff
+ path: /tmp/api-sync
+
+ - name: Detect stale docs
uses: anthropics/claude-code-action@v1
with:
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
github_token: ${{ secrets.GITHUB_TOKEN }}
claude_args: |
--model opus
- --max-turns 20
- --allowedTools "Bash(pnpm:*)" "Bash(node:*)" "Bash(git:*)" "Bash(gh:*)" "Bash(cat:*)" "Bash(rg:*)"
+ --max-turns 25
+ --allowedTools "Read" "Glob" "Grep" "Bash(gh:*)" "Bash(cat:*)" "Bash(jq:*)" "Bash(diff:*)" "Bash(ls:*)" "Bash(head:*)" "Bash(tail:*)" "Bash(wc:*)" "Bash(sort:*)"
prompt: |
- You are the API reference copy-sync agent.
- Your sole job: detect drift between auto-generated API JSON and hand-written MDX prose in reference pages.
+ You are the stale-docs detection agent. Your job: given a pre-computed API diff,
+ find documentation that may need updating and open ONE GitHub issue summarizing all findings.
- Trigger context:
- - Event: ${{ github.event_name }}
- - PR Number: #${{ needs.analyze.outputs.pr_number }}
- - PR Title: ${{ needs.analyze.outputs.pr_title }}
- - PR URL: ${{ needs.analyze.outputs.pr_url }}
- - PR Body:
- ${{ needs.analyze.outputs.pr_body }}
+ ## Inputs
- Load context before acting:
- - Read `CLAUDE.md` and `.claude/skills/README.md`.
- - Load and follow these skills in order:
- 1. `.claude/skills/api-reference/SKILL.md`
- 2. `.claude/skills/docs/SKILL.md`
- 3. `.claude/skills/commit-pr/SKILL.md`
+ The following files are at /tmp/api-sync/:
+ - `diff.patch` — unified diff of API JSON between HEAD~1 and HEAD
+ - `changed-components.txt` — filenames of changed component JSONs (one per line, may be empty)
+ - `changed-utils.txt` — filenames of changed util JSONs (one per line, may be empty)
+ - `after-components/` — current component JSON files
+ - `after-utils/` — current util JSON files
+ - `pr-meta.json` — `{number, url, author, title}` of the triggering PR
- Step 1 — Identify impacted components:
- - Use `gh pr diff ${{ needs.analyze.outputs.pr_number }} --name-only` (or `git log` for workflow_dispatch) to find which components/utils changed.
- - Focus only on those components for the rest of the analysis.
+ Important: Focus on items in `changed-components.txt` and `changed-utils.txt`.
+ Skip any components/utils listed in `new-components.txt` or `new-utils.txt` —
+ a separate job already opens issues for those.
- Step 2 — Build API JSON:
- - Run `pnpm install` and `pnpm -C site api-docs`.
- - The generated JSON files are the source of truth — they are always current.
+ ## Process
- Step 3 — Compare JSON against MDX:
- - For each impacted component, compare the generated API JSON with the hand-written MDX in `site/src/content/docs/reference/`.
- - "Drift" means the MDX prose doesn't match the JSON. Look for:
- - Missing or removed props/state fields in prose sections.
- - Outdated descriptions that contradict JSON.
- - Missing data attributes in Styling sections.
- - Stale type signatures in prose.
- - Missing sidebar entry in `site/src/docs.config.ts`.
- - For new components with no MDX yet: open an issue noting scaffold is needed, don't attempt it.
+ Step 1: Read `pr-meta.json` and `diff.patch`. Understand what API surfaces changed and how.
- Step 4 — Create/update issues and PRs:
- - Create/update one canonical issue per component using `.github/templates/docs/reference-copy-issue.md`.
- - Issue title: `docs(site): {component_name} api reference update`.
- - Keep at most one active canonical issue per component.
- - If a canonical issue exists, update it and append new trigger references.
- - Fully render template fields; no placeholders.
- - If drift is clear and actionable, create or update one canonical PR per component.
- - PR title: `docs(site): {component_name} api reference update`.
- - PR body must use `.github/templates/api-reference-update-pr.md`.
- - Do not open a PR when analysis is uncertain — use `triage` label instead.
+ Step 2: For each changed component/util, read the "after" JSON to understand the current API shape.
- Labels:
- - Required: `docs`, `api`, `site`, `docs:reference-copy`.
- - Add `components` for component pages.
- - Add `triage` when uncertain.
+ Step 3: Search for documentation that references these APIs. Check ALL of:
+ - `site/src/content/docs/reference/` — MDX reference pages (look for stale prop descriptions,
+ missing new props/state/data-attributes, outdated type signatures)
+ - `site/src/content/docs/concepts/` — concept pages mentioning these APIs
+ - `site/src/content/docs/how-to/` — how-to guides mentioning these APIs
+ - `site/src/components/docs/demos/` — demo code using changed props/state/signatures
+ - `packages/*/README.md` — package READMEs mentioning these APIs
- Scope restrictions:
- - ONLY check `site/src/content/docs/reference/` — no demos, no concept pages.
- - Do NOT check demo code (separate job handles that).
- - Do NOT check concept/how-to pages (separate job handles that).
+ Use Grep and Glob to search efficiently. Look for:
+ - The component/util name (PascalCase, camelCase)
+ - Specific prop/state/parameter names that were added, removed, or changed in the diff
+ - HTML element names from `platforms.html.tagName` in the JSON (e.g. `media-play-button`)
+ - Data attribute names that changed
- # ─── Job 2: Demo code drift (Claude Sonnet) ─────────────────────────
- docs-demos:
- needs: analyze
- if: needs.analyze.outputs.has_changes == 'true'
- runs-on: ubuntu-latest
+ Step 4: For each file with hits, read the relevant section and assess:
+ - `high` — definitely stale (references a removed/renamed prop by old name, shows old signature)
+ - `medium` — likely stale (mentions API whose behavior/type changed)
+ - `low` — possibly stale (mentions the component but may not be affected)
- steps:
- - name: Checkout code
- uses: actions/checkout@v5
- with:
- fetch-depth: 0
+ Discard clear false positives. Include borderline cases for human review.
- - name: Check demo code drift
- uses: anthropics/claude-code-action@v1
- with:
- anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
- github_token: ${{ secrets.GITHUB_TOKEN }}
- claude_args: |
- --model sonnet
- --max-turns 14
- --allowedTools "Bash(git:*)" "Bash(gh:*)" "Bash(cat:*)" "Bash(rg:*)"
- prompt: |
- You are the API reference demo-sync agent.
- Your sole job: check if demo code uses APIs that changed in a recent PR.
+ Step 5: If you found ANY stale references, open exactly ONE issue using `gh issue create`.
+ If you found NOTHING stale, do NOT create an issue — just output "No stale docs detected."
- Trigger context:
- - Event: ${{ github.event_name }}
- - PR Number: #${{ needs.analyze.outputs.pr_number }}
- - PR Title: ${{ needs.analyze.outputs.pr_title }}
- - PR URL: ${{ needs.analyze.outputs.pr_url }}
+ ## Issue format
- Load context before acting:
- - Read `CLAUDE.md`.
+ Read `pr-meta.json` to get PR_NUMBER, PR_URL, PR_AUTHOR, and PR_TITLE.
- Step 1 — Identify impacted components:
- - Use `gh pr diff ${{ needs.analyze.outputs.pr_number }} --name-only` (or `git log` for workflow_dispatch) to find which components changed.
- - Then use `gh pr diff ${{ needs.analyze.outputs.pr_number }}` to see what specifically changed in their APIs (renamed props, removed options, changed signatures, new data attributes).
+ Assign the issue to the PR author: `--assignee $PR_AUTHOR` (skip if author is empty).
- Step 2 — Check demos:
- - For each impacted component, read all demo files in `site/src/components/docs/demos/{component}/`.
- - Check both `html/css/` and `react/css/` variants.
- - Look for: renamed props, removed options, changed signatures, deprecated patterns, new data attributes demos should show.
- - Skip components with no demo directory.
+ Title: `docs(site): stale docs from #$PR_NUMBER`
- Step 3 — Create/update issues:
- - Create issues ONLY (no PRs — demo fixes need human judgment).
- - Use `.github/templates/docs/demos-issue.md`.
- - Issue title: `docs(site): {component_name} demo code update`.
- - Keep at most one active canonical issue per component.
- - If a canonical issue exists, update it and append new trigger references.
- - Fully render template fields; no placeholders.
- - Do NOT create an issue if no drift is found.
+ Labels: `docs,docs:reference,site,triage`
- Labels (always all of these):
- - `docs`, `api`, `site`, `docs:demos`, `components`, `triage`.
+ Body (use this structure exactly):
+ ```
+
+
- Scope restrictions:
- - ONLY check `site/src/components/docs/demos/` — no MDX prose, no concept pages.
- - Do NOT check reference page content (separate job handles that).
- - Do NOT check concept/how-to pages (separate job handles that).
+ ## Summary
+ API changes in #{PR_NUMBER} ({PR_TITLE}) may have made the following documentation stale.
- # ─── Job 3: Guide references drift (Claude Sonnet) ──────────────────
- docs-guide-references:
- needs: analyze
- if: needs.analyze.outputs.has_changes == 'true'
- runs-on: ubuntu-latest
+ ## Triggering PR
+ {PR_URL}
- steps:
- - name: Checkout code
- uses: actions/checkout@v5
- with:
- fetch-depth: 0
+ ## API Changes
+ {Brief summary of what changed in the API — new props, removed props, type changes, etc.}
- - name: Check cross-site references
- uses: anthropics/claude-code-action@v1
- with:
- anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
- github_token: ${{ secrets.GITHUB_TOKEN }}
- claude_args: |
- --model sonnet
- --max-turns 14
- --allowedTools "Bash(git:*)" "Bash(gh:*)" "Bash(cat:*)" "Bash(rg:*)"
- prompt: |
- You are the cross-site reference sync agent.
- Your sole job: find mentions of changed APIs in docs OUTSIDE `/reference/` that may be stale.
+ ## Stale Documentation Found
- Trigger context:
- - Event: ${{ github.event_name }}
- - PR Number: #${{ needs.analyze.outputs.pr_number }}
- - PR Title: ${{ needs.analyze.outputs.pr_title }}
- - PR URL: ${{ needs.analyze.outputs.pr_url }}
+ ### High Confidence
+ | File | Line(s) | Issue | API Change |
+ |---|---|---|---|
+ {rows or "None found"}
- Load context before acting:
- - Read `CLAUDE.md`.
+ ### Medium Confidence
+ | File | Line(s) | Issue | API Change |
+ |---|---|---|---|
+ {rows or "None found"}
- Step 1 — Identify changed APIs:
- - Use `gh pr diff ${{ needs.analyze.outputs.pr_number }} --name-only` (or `git log` for workflow_dispatch) to find which components/utils changed.
- - Then use `gh pr diff ${{ needs.analyze.outputs.pr_number }}` to identify the specific API changes (renamed props, removed exports, changed signatures, etc.).
- - Build a list of API names to search for (PascalCase, camelCase, kebab-case, `media-{name}` variants).
+ ### Low Confidence
+ | File | Line(s) | Issue | API Change |
+ |---|---|---|---|
+ {rows or "None found"}
- Step 2 — Grep for references:
- - Run targeted `rg` commands to find files mentioning changed APIs in:
- - `site/src/content/docs/concepts/`
- - `site/src/content/docs/how-to/`
- - `packages/*/README.md`
- - Search for all name variants (kebab, PascalCase, camelCase, `media-{name}` element names).
- - Do NOT search in `site/src/content/docs/reference/` (separate job handles that).
- - Do NOT search in `site/src/components/docs/demos/` (separate job handles that).
+ ## Recommended Actions
+ {Bulleted list of specific things to fix}
+ ```
- Step 3 — Analyze hits:
- - For each file with grep hits, read the surrounding context and determine:
- - `high` confidence: definitely stale (references removed/renamed API by old name).
- - `medium` confidence: likely stale (references API whose behavior changed).
- - `low` confidence / false positive: grep hit in unrelated context.
- - Be conservative — include borderline cases for human review.
- - Discard clear false positives.
-
- Step 4 — Create/update triage issues:
- - Create issues ONLY (no PRs).
- - Use `.github/templates/docs/guide-references-issue.md`.
- - Issue title: `docs(site): cross-site api references update`.
- - Group related APIs into one issue when they affect the same files.
- - Keep at most one active canonical issue (search for existing open issues with `drift-type:cross-site-refs` in body).
- - If a canonical issue exists, update it and append new trigger references.
- - Fully render template fields; no placeholders.
- - Do NOT create an issue if no stale references are found.
-
- Labels (always all of these):
- - `docs`, `site`, `docs:guide-references`, `triage`.
-
- Scope restrictions:
- - ONLY check docs outside `/reference/` and package READMEs.
- - Do NOT check reference pages (separate job handles that).
- - Do NOT check demo files (separate job handles that).
+ ## Rules
+ - Open at most ONE issue per run. Group everything into one issue.
+ - Do NOT create or modify any files. Do NOT create PRs. Issues only.
+ - Do NOT open an issue if there is nothing stale.
+ - Before creating an issue, check for existing open issues that have BOTH
+ `` and `` in their body.
+ If one exists, skip creation to avoid duplicates.
+ - Be thorough but efficient — use Grep to find files, then Read only relevant sections.