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

[github-actions]

Self-Healing Documentation Fixes

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

Gaps Fixed

• Removed tools.serena example in blog post — docs/src/content/docs/blog/2026-02-05-how-workflows-work.md showed tools.serena (with mode: remote, version: latest) as a built-in MCP example. The schema marks tools.serena as REMOVED (x-removed: true) and PR Reject removed tools.serena in parser and align with schema #32909 made the parser reject it at compile time. Users copying the example would now hit a hard compile error directing them to import shared/mcp/serena.md instead. Replaced the entry with a valid tools.playwright example (mode: cli) so the three-tool illustration remains intact. The reference page docs/src/content/docs/reference/serena.md already documents the migration, so no further change was needed.

Root Cause

DDUw Step 2 ("Removed Features in Docs") scans for properties present in docs but absent from the schema. tools.serena is still present in the schema as a property — only with "x-removed": true and a REMOVED: description prefix. A simple property-exists check would not flag it. The scan needs to also flag any schema property whose description starts with REMOVED: or whose x-removed flag is true, regardless of whether the property name itself still appears in the schema.

Additionally, the gap sits in a blog post, and the existing scan focuses on docs/src/content/docs/reference/, setup/, and guides/. Blog posts (docs/src/content/docs/blog/) hold concrete code examples that can age out the same way reference examples do, so they should be in scope when the check is for invalid example syntax.

💡 DDUw Improvement Suggestions

DDUw Improvement Suggestions

Add a schema-removed property scan to .github/workflows/daily-doc-updater.md Step 2, alongside the existing Removed Features in Docs bullet:

Schema-removed properties in docs: Parse pkg/parser/schemas/main_workflow_schema.json for any property whose object contains "x-removed": true OR whose description starts with "REMOVED:". For each such property P, grep the entire docs/src/content/docs/ tree (including blog/) for code-fenced YAML/aw blocks containing P: under a tools: key. Any match is a documentation gap, even if the surrounding prose acknowledges the removal. The fix is either to replace the example with a still-valid property or to remove the offending block.

Concrete grep pattern for the workflow to run:

# 1. Extract removed top-level tool names from the schema
jq -r '.["$defs"].tools.properties | to_entries[] | select(.value["x-removed"] == true or (.value.description // "" | startswith("REMOVED:"))) | .key' pkg/parser/schemas/main_workflow_schema.json

# 2. For each NAME, search ALL doc directories (not just reference)
grep -rn "^[[:space:]]*<NAME>:" docs/src/content/docs/ --include='*.md' --include='*.mdx'

Also widen Step 1's documentation directory list: add docs/src/content/docs/blog/ to the directories scanned for invalid example code. Blog posts are historical commentary, but the code examples inside them must still compile against the current schema — otherwise the post becomes a trap for new readers who copy from it.

Other Closed-Issue Outcomes (No Action Needed)

For full transparency, the other documentation issues closed in the last 7 days were verified and required no additional fixes in this run:

• [deep-report] Schema: add pi and opencode to engine_config description (missing built-in engines) #32418 (engine_config: pi, opencode) — already addressed by previous healer PRs [docs] Self-healing documentation fixes from issue analysis - 2026-05-16 #32496 and [docs] Self-healing documentation fixes from issue analysis - 2026-05-17 #32714; schema descriptions and engines.md rows are complete.
• [deep-report] Docs: define "frontmatter" and explain .lock.yml in the Quick Start #32421 (define frontmatter, explain .lock.yml in Quick Start) — closed not_planned; the Quick Start at docs/src/content/docs/setup/quick-start.mdx already defines frontmatter inline in Step 4 (per merged PR docs: define frontmatter and demystify jargon in Quick Start #29352, 2026-04-30) and explains the .md / .lock.yml split in the same step. No additional code change motivates new doc work.
• [deep-report] Quick Start sample workflow defaults to Copilot — Claude-only users will fail their first run #32423 (Quick Start defaults to Copilot) — closed not_planned; add-wizard prompts for engine choice in Step 2 and Step 4 demonstrates engine: claude (per merged PR around 2026-05-13, "Improve Claude onboarding parity in Quick Start"). No code change in the 7-day window motivates further restructuring.
• [deep-report] Add inline-sub-agents and max-effective-tokens to canonical frontmatter reference #31968 (inline-sub-agents, max-effective-tokens in frontmatter reference) — addressed by merged PR docs: sync frontmatter-full.md and cli.md with schema/CLI surface changes from #32200 and #32213 #32236; both fields are present in frontmatter.md (lines 543, 556) and frontmatter-full.md.
• Specification Audit — 2026-05-17 — 4 issues found #32821 (missing pkg/errorutil spec, pkg/cli and pkg/parser dependency drift) — addressed by merged PR Add missing errorutil package spec and align dependency sections in package READMEs #32822.
• Specification Audit — 2026-05-14 — 2 issues found #32135, Specification Audit — 2026-05-13 — 1 issue found #31949 (spec-audit issues) — addressed by merged PRs Add missing pkg/linters package spec and complete pkg/cli dependency list #32136 and Document pkg/testutil dependency on pkg/constants in package spec #31950 respectively.
• CLI consistency issues ([cli-consistency] CLI Consistency Issues - 2026-05-15 #32384, [cli-consistency] CLI Consistency Issues - 2026-05-14 #32129, [cli-consistency] CLI Consistency Issues - 2026-05-13 #31948, [cli-consistency] CLI Consistency Issues - 2026-05-12 #31697, [cli-consistency] CLI Consistency Issues - 2026-05-11 #31512) — closed by maintainer with no cross-referenced PR; these are largely judgement calls on automated cookie-labeled reports and do not represent a single doc gap actionable in this run.
• Artifact constants check — all 10 ArtifactName constants in pkg/constants/{constants,job_constants}.go are present in the Quick Reference table of docs/src/content/docs/reference/artifacts.md. No drift detected.

Related Issues

No specific issue is closed by this PR — the gap was identified by direct cross-reference against pkg/parser/schemas/main_workflow_schema.json and merged PR #32909.

Generated by 📝 Daily Documentation Healer · ● 27.9M · ◷

• expires on May 21, 2026, 12:14 AM UTC

[Copilot]

Pull request overview

This PR replaces an outdated tools.serena example in a blog post with a valid tools.playwright example. The serena built-in was removed (per PR #32909) and the parser now rejects it at compile time, so the blog example would have failed for users copying it. The surrounding prose (which still mentions serena as an extension via imports) is left intact.

Changes:

• Replace the serena: {mode: remote, version: latest} block in the three-tool YAML illustration with playwright: {mode: cli} so the example continues to compile against the current schema.

Show a summary per file

File	Description
docs/src/content/docs/blog/2026-02-05-how-workflows-work.md	Replaces removed serena built-in MCP example with the still-valid playwright (CLI mode) example.

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: 0

[github-actions]

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