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

[github-actions]

Self-Healing Documentation Fixes

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

Gaps Fixed

• Added a Max Effective Tokens (max-effective-tokens) entry to docs/src/content/docs/reference/glossary.md. The field was added to the workflow schema (and AWF apiProxy.maxEffectiveTokens enforcement) by Refactor engine.max-runs to top-level max-runs with AWF enforcement #31418 / Set frontmatter defaults and add shared import/expression support for max limits #31484 but was only referenced in a single bullet inside engines.md. Cross-references point to the existing Effective Tokens Specification and Cost Management pages.
• Updated the existing Max Runs (max-runs) glossary entry to document the new default value (100) and accepted formats (integer or GitHub Actions expression). PR Set frontmatter defaults and add shared import/expression support for max limits #31484 set the default and broadened the schema to accept expressions, but the glossary still described the field without a default.

Root Cause

DDUw's most recent run (PR #31491) explicitly evaluated #31418 but only verified engines.md and glossary.md for the renamed max-runs field — it did not check whether the companion field max-effective-tokens had analogous glossary coverage. PR #31484 (which set the new defaults of max-runs=100 and max-effective-tokens=25000000 and added expression / shared-import support) merged at 12:03 UTC on 2026-05-11, after DDUw's run at 11:49 UTC, so DDUw could not have processed it in the same 24-hour window.

💡 DDUw Improvement Suggestions

DDUw Improvement Suggestions

1. Sibling-field coverage check (Step 2 of daily-doc-updater.md). When DDUw processes a PR that adds or renames a top-level frontmatter field, it should look at the JSON Schema diff (pkg/parser/schemas/main_workflow_schema.json) for all sibling properties touched in the same PR, not only the renamed field. Concretely: after analyzing Refactor engine.max-runs to top-level max-runs with AWF enforcement #31418, DDUw should have noticed the schema diff also touched max-effective-tokens block alignment and confirmed it had glossary coverage equivalent to max-runs.

   Suggested wording to add under Step 2. Analyze Changes:

   For PRs that modify pkg/parser/schemas/main_workflow_schema.json, list every top-level property name in the diff. For each property, verify it has an entry in docs/src/content/docs/reference/glossary.md and that the entry mentions the default value from the schema description (look for "Defaults to ... when omitted").

2. Same-day late-merge re-scan. PR Set frontmatter defaults and add shared import/expression support for max limits #31484 merged 14 minutes after DDUw's run. DDUw's 24-hour scanning window starts from the run time, so any PR merging in the trailing window of the same day is missed by the current day's DDUw and not re-evaluated tomorrow if the next DDUw's window begins exactly 24h later. Two options:

   • Widen the look-back window to 26 hours so adjacent runs overlap, OR
   • Re-scan only the trailing 4 hours from the previous DDUw run timestamp at the start of each run.

3. frontmatter-full.md regeneration verification. DDUw assumed frontmatter-full.md would be "regenerated by build tooling" after the schema change. The healer verified the file does not yet include top-level max-runs or max-effective-tokens sections (only max-runs-per-window under user-rate-limit). DDUw should explicitly check whether scripts/generate-schema-docs.js has been re-run after a schema change rather than assume.

   Suggested wording to add under Step 4. Identify Documentation Gaps:

   When a PR modifies pkg/parser/schemas/main_workflow_schema.json, verify that the corresponding sections in docs/src/content/docs/reference/frontmatter-full.md have been updated. If the auto-generated file is out of sync, flag this as a follow-up (the generator is scripts/generate-schema-docs.js).

Related Issues

• Confirms gap related to [cli-consistency] CLI Consistency Issues - 2026-05-08 #31023 (CLI consistency — only item 1 about --codespaces was addressed by DDUw in [docs] Update documentation for features from 2026-05-11 #31491; items about CLI help text remain unaddressed but require code changes, not docs edits)
• Schema changes from PR Refactor engine.max-runs to top-level max-runs with AWF enforcement #31418 (max-runs refactor) and PR Set frontmatter defaults and add shared import/expression support for max limits #31484 (defaults + expression support)

What Was Verified But Not Fixed

• Artifact constants: All 10 *ArtifactName constants in pkg/constants/ are already documented in docs/src/content/docs/reference/artifacts.md ✅
• Closed issue scan: 23 closed documentation issues in the last 7 days; the only feature-level gap was max-effective-tokens glossary coverage.
• frontmatter-full.md: This file is auto-generated by scripts/generate-schema-docs.js and would be best regenerated rather than hand-edited. Flagged in the DDUw Improvement Suggestions above instead of edited here.
• CLI help text items from [cli-consistency] CLI Consistency Issues - 2026-05-08 #31023, [cli-consistency] CLI Consistency Issues - 2026-05-06 #30630, [cli-consistency] CLI Consistency Issues - 2026-05-07 #30833: These are CLI --help strings in cobra commands (code changes), not docs files, so out of scope for the healer.

Generated by Daily Documentation Healer · ● 21.5M · ◷

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

[Copilot]

Pull request overview

This PR updates the documentation glossary to cover recently added/updated workflow frontmatter limit fields so the reference docs match current schema/runtime defaults.

Changes:

• Added a new glossary entry for top-level max-effective-tokens, including default value and accepted formats.
• Updated the existing max-runs glossary entry to document the new default (100) and that GitHub Actions expressions are accepted.

Show a summary per file

File	Description
docs/src/content/docs/reference/glossary.md	Adds/updates glossary entries for max-effective-tokens and max-runs to reflect current defaults and supported value formats.

Copilot's findings

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

• Files reviewed: 1/1 changed files
• Comments generated: 1

[github-actions]

Skills-Based Review 🧠

Applied /grill-with-docs — the appropriate skill for documentation-only changes.

Key Themes

• Both new/updated glossary entries accurately match the JSON schema definitions in pkg/parser/schemas/main_workflow_schema.json
• Terminology is consistent with existing glossary vocabulary (effective tokens, AWF proxy, apiProxy.*, GitHub Actions expression)
• The max-effective-tokens entry mirrors the structure of the adjacent max-runs entry — parallel phrasing, same format, appropriate cross-links

Positive Highlights

• ✅ Default values (25000000 / 100) match the schema and PR #31484
• ✅ The aw wrap code block fencing matches the pattern used throughout the glossary
• ✅ Cross-references to the Effective Tokens Specification and Cost Management pages are correct
• ✅ The DDUw Improvement Suggestions in the PR body are well-reasoned and actionable

Verdict

Changes are accurate, well-scoped, and consistent with the project's domain vocabulary. No issues found.

🧠 Reviewed using Matt Pocock's skills by Matt Pocock Skills Reviewer · ● 4.9M