[docs] Self-healing documentation fixes from issue analysis - 2026-06-20

[github-actions]

Summary

Documents the engine.extensions field for the Pi engine in the engines reference page. This field allows workflows to declare a list of npm plugins that are installed (via pi install <extension>) before the agent runs. The new subsection also clarifies that only the Pi engine reads this field and that, when engine.command is set, the same executable is used for extension installation.

---

Changes

docs/src/content/docs/reference/engines.md — modified

Added a new "Pi Extensions (extensions)" subsection under the Pi engine reference section. The addition (14 lines) covers:

• What engine.extensions does: lists npm packages installed before the agent run.
• A YAML example showing two extensions (@pi/web-search, @pi/file-browser).
• Scope note: only the Pi engine reads this field; all other engines ignore it.
• Interaction with engine.command: the same executable is used for both agent runs and extension installation when engine.command is set.

---

Impact Assessment

Dimension	Assessment
Breaking change	No
Risk	Low — documentation-only change
Affected files	1 (docs/src/content/docs/reference/engines.md)
Engines affected	Pi engine (documentation only)
Tests required	None (docs only)

---

Checklist

• Documentation only — no code changes
• New section is consistent with existing reference page structure
• YAML example uses wrap fence attribute (consistent with surrounding examples)
• Scope limitations clearly documented (Pi-only field, engine.command interaction)

Generated by PR Description Updater for issue #40402 · 33.7 AIC · ⌖ 9.33 AIC · ⊞ 4.5K · ◷

[github-actions]

✅ PR Code Quality Reviewer completed the code quality review.

[github-actions]

✅ Design Decision Gate 🏗️ completed the design decision gate check.

No ADR enforcement needed: PR #40402 does not have the 'implementation' label and has 0 new lines of code in business logic directories (threshold 100).

[github-actions]

🧠 Matt Pocock Skills Reviewer has completed the skills-based review. ✅

[github-actions]

✅ Test Quality Sentinel completed test quality analysis.

No test files were added or modified in this PR. Test Quality Sentinel skipped. PR #40402 only modifies docs/src/content/docs/reference/engines.md (14 lines added, documentation only).

[Copilot]

Pull request overview

This PR updates the gh-aw engine reference documentation to cover Pi’s engine.extensions configuration, aligning the docs with an existing Pi-engine feature that installs additional plugins prior to running the agent.

Changes:

• Adds a new “Pi Extensions (extensions)" subsection to reference/engines.md.
• Includes a YAML example showing how to configure engine.extensions for the Pi engine.

Show a summary per file

File	Description
docs/src/content/docs/reference/engines.md	Documents Pi’s engine.extensions field with a new subsection and 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: 2

[github-actions]

Documentation correctness issue in engine.extensions section

One factual error in the new Pi Extensions subsection — the last sentence contradicts the source code.

🔍 Finding details

Claim (line 434): "If engine.command is set, the same executable is used to install the extensions."

Reality (pkg/workflow/pi_engine.go:180–183): GetInstallationSteps returns []GitHubActionStep{} immediately when engine.command != "", before the extension-install loop is ever reached. The commandName = workflowData.EngineConfig.Command branch inside that loop is dead code.

Users who set both engine.command and engine.extensions will silently get no extension install steps — the opposite of what the docs promise. A follow-up PR should correct this sentence and also fix the dead code in pi_engine.go.

🔎 Code quality review by PR Code Quality Reviewer · 46.9 AIC · ⌖ 7.29 AIC · ⊞ 5.1K

[github-actions]

Factual error: the claim that engine.command delegates extension installation to the same executable is incorrect — extensions are silently skipped when engine.command is set.

💡 What the code actually does

GetInstallationSteps in pkg/workflow/pi_engine.go has an early-return guard:

if workflowData.EngineConfig != nil && workflowData.EngineConfig.Command != "" {
    // Skipping installation steps: custom command specified
    return []GitHubActionStep{}
}

This causes the function to return an empty step list before it ever reaches the extension-install loop. The commandName = workflowData.EngineConfig.Command assignment inside that loop is dead code.

A user who sets both engine.command and engine.extensions will find their extensions are never installed — no error is emitted, just silence.

Suggested correction:

Each listed extension produces one additional install step in the compiled workflow.
Note: engine.extensions has no effect when engine.command is set — the Pi CLI install step and all extension install steps are skipped in that configuration.

[github-actions]

Skills-Based Review 🧠

Applied /grill-with-docs — requesting changes on one factual inaccuracy in the new engine.extensions documentation.

📋 Key Themes & Highlights

Issue Found

• Inaccurate engine.command claim (line 434): The new section states that when engine.command is set, the same executable is used to install extensions. The source code (pi_engine.go:GetInstallationSteps) contradicts this: it has an early return that skips all installation steps — including extensions — when engine.command is set. The commandName = workflowData.EngineConfig.Command branch inside the extensions loop is unreachable dead code.

Suggestions

• Missing feature table row (unchanged lines): engine.extensions is absent from the Engine Feature Comparison table (line ~35). Other Pi-specific capabilities are already listed there; adding engine.extensions | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ would make discoverability consistent.

Positive Highlights

• ✅ Section title format ### Pi Extensions (\extensions`)exactly matches the existing### Custom Token Weights (`token-weights`)` pattern
• ✅ The "Only the Pi engine reads this field" statement is accurate to the source
• ✅ YAML code block examples are clean, realistic, and use the same yaml wrap convention as the rest of the page
• ✅ The root cause and DDUw improvement notes in the PR description are a nice value-add

🧠 Reviewed using Matt Pocock's skills by Matt Pocock Skills Reviewer · 61.8 AIC · ⌖ 7.86 AIC · ⊞ 6.9K

[github-actions]

[/grill-with-docs] The claim about engine.command is contradicted by the source code — extensions are not installed when engine.command is set.

💡 Details

pi_engine.go:GetInstallationSteps has an early return when engine.command is set:

if workflowData.EngineConfig != nil && workflowData.EngineConfig.Command != "" {
    return []GitHubActionStep{} // skips ALL install steps
}

The commandName = workflowData.EngineConfig.Command branch inside the extensions loop (line 206) is therefore dead code — it can never be reached.

The last sentence should instead read something like:

Extensions are only installed when the default Pi CLI installer runs. If engine.command is set, all installation steps (including extensions) are skipped.

This matters for users who supply a custom engine.command and expect extensions to be auto-installed.