[docs] Self-healing documentation fixes from issue analysis - 2026-05-28

[github-actions]

Self-Healing Documentation Fixes

This PR was automatically created by the Daily Documentation Healer workflow.

Gaps Fixed

• Issue [deep-report] [quick-win] Fix 3 broken doc-link anchors in main_workflow_schema.json #34686 — Fix 3 broken doc-link anchors in main_workflow_schema.json: added the missing Update Check (check-for-updates:) and Install Scripts (run-install-scripts:) reference sections to docs/src/content/docs/reference/frontmatter.md, and updated the corresponding schema See: URLs in pkg/parser/schemas/main_workflow_schema.json (and the generated frontmatter-full.md) to point at the actual Starlight anchor slugs (#update-check-check-for-updates and #install-scripts-run-install-scripts). The third anchor flagged by the issue, #strict-mode-strict, already exists and was not touched.

Root Cause

The broken anchors were not caught by DDUw because:

1. DDUw scans only the file content of docs vs. code changes, not the integrity of cross-references between the JSON Schema and Starlight-generated anchors. Its “Identify Documentation Gaps” step (### 4. in daily-doc-updater.md) looks for missing pages but does not validate that anchor fragments referenced from outside the docs (schema, source comments) resolve to a real heading inside the docs.
2. The closed-issue scan (### 1c.) was performed, but issue [deep-report] [quick-win] Fix 3 broken doc-link anchors in main_workflow_schema.json #34686 was auto-closed by expiry (the DeepReport tracker gh-aw-expires mechanism), not via a [docs] PR that resolved it. DDUw’s current heuristic treats any closure as a signal of resolution unless a same-window merged PR explicitly references the issue. Expiry-based closures of deep-report and similar tracker issues therefore look identical to resolved closures and slip past the recently-closed-issue check.

💡 DDUw Improvement Suggestions

DDUw Improvement Suggestions

The following targeted changes to .github/workflows/daily-doc-updater.md would prevent this class of gap from recurring:

1. Add an anchor-integrity scan step (new sub-step inside ### 4. Identify Documentation Gaps):

   • For every https://github.github.com/gh-aw/reference/<page>/#<anchor> URL found in pkg/parser/schemas/*.json and in pkg/**/*.go doc comments, verify a heading whose Starlight slug equals <anchor> exists in the corresponding docs/src/content/docs/reference/<page>.md.
   • Suggested command:

     grep -roE 'github\.github\.com/gh-aw/reference/[a-z-]+/#[a-z0-9-]+' pkg/ | sort -u

     Then cross-check each anchor against the heading slugs in the referenced docs file.
   • Treat any unresolved anchor as a documentation gap, same severity as a missing section.

2. Tighten the closed-issue heuristic in ### 1c. to distinguish expiry-based auto-closures from resolution-based closures:

   • Before treating a closed documentation issue as “already addressed,” check whether the issue body contains a gh-aw-expires HTML comment with a timestamp in the past.
   • If yes, and there is no PR that explicitly references the issue (#NNN, closes #NNN, etc.), treat the issue as unaddressed, not resolved.
   • This is especially relevant for [deep-report] and [doc-healer] tracker issues, which auto-close on expiry rather than on fix.

3. Add the JSON Schema to DDUw's primary watch list. Currently pkg/parser/schemas/*.json is listed under tools.bash (so it can be read) but the analysis steps never explicitly diff it for outbound documentation links. Adding a step like “Diff main_workflow_schema.json for new/changed See: URLs and verify each anchor resolves” would have caught these broken anchors the day they were introduced.

Related Issues

Closes #34686

Generated by 📝 Daily Documentation Healer · opus47 19.5M · ◷

• expires on May 31, 2026, 12:10 AM UTC

[pelikhan]

@copilot review what these features do.

[Copilot]

@copilot review what these features do.

This PR adds documentation for two existing frontmatter fields that were referenced in the JSON Schema but had no corresponding reference section in the docs (causing broken anchor links):

check-for-updates: (default: true)
Controls whether the activation job verifies the workflow was compiled with a supported version of gh-aw. When enabled, the activation job downloads config.json from the gh-aw repository at runtime to check that the compiled version is not blocked and meets the minimum supported version. Setting it to false skips this — useful in air-gapped environments — but the workflow will no longer detect stale or blocked compiler versions. Disabling it is not permitted in strict mode.

run-install-scripts: (default: false)
Controls whether npm pre/post install scripts are permitted to run during package installation. By default the compiler appends --ignore-scripts to every generated npm install command to block install-time hooks, which are a common supply-chain attack vector. Setting run-install-scripts: true disables that protection globally across all runtimes that generate npm install commands. The compiler emits a supply-chain security warning; in strict mode this is a compilation error. Finer-grained per-runtime control is also available under runtimes.<runtime>.run-install-scripts.

The schema See: URLs in main_workflow_schema.json (and the generated frontmatter-full.md) were also updated to point at the correct Starlight-generated anchor slugs (#update-check-check-for-updates and #install-scripts-run-install-scripts).