[Code Quality] Add per-engine auth table to how-they-work.mdx and architecture.mdx

[github-actions]

Description

docs/src/content/docs/concepts/how-they-work.mdx (line 26) and docs/src/content/docs/concepts/architecture.mdx (line 42) both introduce the four supported engines (Copilot, Claude, Codex, Gemini) but provide zero auth/setup guidance at that point. A Claude user reading these docs must follow a link to a separate reference page to discover they need ANTHROPIC_API_KEY. This friction is identified as a Major Obstacle in the Claude Code User Documentation Review.

Suggested Changes

Add a compact per-engine auth + defaults table near the first engine mention in both files:

| Engine | Secret required | Notes |
|---|---|---|
| Copilot | `copilot-requests: write` permission *or* `COPILOT_GITHUB_TOKEN` | Default engine |
| Claude | `ANTHROPIC_API_KEY` | Pass `engine: claude` in frontmatter |
| Codex | `OPENAI_API_KEY` or `CODEX_API_KEY` | Pass `engine: codex` |
| Gemini | `GEMINI_API_KEY` | Pass `engine: gemini` |

Also name which engines require a third-party MCP server for web-search (tools.md:65).

Files Affected

• docs/src/content/docs/concepts/how-they-work.mdx (near line 26)
• docs/src/content/docs/concepts/architecture.mdx (near line 42)
• docs/src/content/docs/reference/tools.md (line 65 — name engines needing third-party MCP for web-search)

Success Criteria

• Per-engine auth table appears near first engine mention in how-they-work.mdx and architecture.mdx
• tools.md names which engines need a third-party MCP server for web-search
• A Claude user reading either concepts page can determine their required secret without following an external link
• No broken links or formatting issues in the docs

Effort

~45 min · XS

Source

Extracted from Claude Code User Documentation Review discussion #45994

Priority

Medium — directly reduces onboarding friction for non-Copilot engine users

🔍 Task mining by Discussion Task Miner - Code Quality Improvement Agent · 156.6 AIC · ⌖ 7.84 AIC · ⊞ 7K · ◷

• expires on Jul 17, 2026, 5:23 AM UTC-08:00

[github-actions]

This issue was automatically closed because it expired on 2026-07-17T13:23:18.918Z.

Closed by Workflow