docs(config): document the full opener configuration

[ChampPABA]

Status

LGTM. Ready for human review at 6d6b552ca. Two fresh reviews found one overbroad documentation claim, now corrected, and no further actionable issues. The final commit changes one documentation sentence; code and tests are unchanged from 66a4b7732, whose CI and Security passed on Linux, macOS, and Windows. The final commit's workflow runs require maintainer approval. No merge has been performed.

What was missing

The opener documentation did not explain the full configuration contract, especially static args and how overrides affect built-in tools. This made an existing capability hard to discover (#1347).

What it does

• Documents all five fields, their types, new-tool defaults, built-in overrides, argument replacement/clearing, and validation timing.
• Uses working VS Code and VS Code Insiders configurations instead of demonstrating a disabled terminal-agent opener.
• States that attach-dirs launches are temporarily disabled by default and that custom workspace editors must accept .code-workspace files.
• Moves the reference to the published docs-lab/reference/configuration/config-json.md page. The legacy docs/cli.md is unchanged from main, following the current docs policy.
• Extends existing tests to exercise both documented editor configurations and replacement/clearing of built-in arguments.

Proof it works

• Build, TypeScript checking, lint, and diff whitespace checks pass.
• At 66a4b7732, CI and Security pass, including Linux/macOS/Windows tests, dependency review, audits, and website lockfile validation. Final-commit CI and Security await approval.
• Opener/workset suites: 64 tests pass, including CLI launches through recording executables under default settings.
• Full local suite: 4,211 tests initially passed; all 21 failures passed targeted reruns. Sixteen required local HTTP fixture server permission, and five required isolation from installed user tools and shell settings. No product changes were needed.
• A separate reviewer parsed the actual documentation example and verified its generated argv, field contracts, and disabled behavior against source.
• Two additional reviewers checked core-design alignment and test quality, then reran all 64 focused tests successfully. Their only finding was that interactive creation can save a disabled opener preference; the documentation now states only the consistently enforced launch restriction. No runtime behavior was changed.
• Rendered the actual website page at 1,280 px and 390 px; the new table and example fit without horizontal scrolling.

Notes

The branch includes main through a0ddb60d0. There are no production-code changes and no merge has been performed. Real editors were not launched; VS Code executable names and the example flag were also checked against its official CLI documentation. The original author's commits remain in the PR history.

Summary by CodeRabbit

• Documentation

  • Expanded CLI configuration guidance for custom and built-in openers.
  • Documented opener fields, launch styles, validation behavior, availability restrictions, and configuration examples.
  • Clarified how to override built-in opener settings and pass additional command-line arguments.

• Tests

  • Added coverage for VS Code and VS Code Insiders opener configurations, including launch arguments.
  • Added coverage confirming custom arguments override built-in opener arguments without changing other defaults.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: e803c361-b6a2-4551-bcaf-269690d1f920

📥 Commits

Reviewing files that changed from the base of the PR and between 66a4b77 and 6d6b552.

📒 Files selected for processing (1)

• docs-lab/reference/configuration/config-json.md

🚧 Files skipped from review as they are similar to previous changes (1)

• docs-lab/reference/configuration/config-json.md

Included review availability: Your plan provides up to 10 included reviews per hour; 6 remain after this review.

---

📝 Walkthrough

Walkthrough

The PR updates the opener configuration reference and adds tests for custom opener arguments, launch logs, and built-in Codex argument overrides.

Changes

Opener configuration

Layer / File(s)	Summary
Document opener configuration docs-lab/reference/configuration/config-json.md	The reference documents opener fields, launch styles, built-in overrides, validation failures, availability restrictions, and configuration examples.
Validate configured opener behavior test/commands/workset.test.ts, test/core/openers.test.ts	Tests cover code-insiders, code with --new-window, complete launch logs, and non-mutating Codex argument overrides.

Estimated code review effort: 2 (Simple) | ~10 minutes

Merge Risk: ⚪ Minimal · up to 6d6b5

This PR documents the opener configuration and extends related tests without changing runtime behavior; no actionable merge-blocking risk remains after normal checks and review.

Suggested reviewers: tabishb

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 2…
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: documenting the full opener configuration for the CLI.

Full details: Docstring Coverage

Explanation

No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 2 files. (1 skipped: 1 unsupported.)

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/cli.md`:
- Around line 368-374: Update the “claude” CLI example to avoid silently
disabling permission checks: replace “--dangerously-skip-permissions” with a
neutral example flag, or add an explicit warning that it is only appropriate for
trusted or sandboxed workspaces.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: f0cac2bd-7876-4eb0-9213-f60b3d9dbfe7

📥 Commits

Reviewing files that changed from the base of the PR and between 0a99f41 and 6a2cc2f.

📒 Files selected for processing (1)

• docs/cli.md

[ChampPABA]

Good catch, fixed in 2c26e4b. The example now uses ["--model", "opus"], which demonstrates args just as well without putting a permission-bypass flag in the docs.

[coderabbitai]

Note

GitHub couldn't provide a complete incremental comparison for this pull request, so CodeRabbit is performing a full review instead. This review may take a little longer.

[clay-good]

Ready for human review at 66a4b7732.

Thanks @ChampPABA for identifying the documentation gap and contributing the original fix. Your commits remain in the PR history. The follow-up moves the reference to the current published docs, clarifies the existing contract, and verifies both examples with regression tests; there are no production-code changes.

Build, type checking, lint, and all 64 opener/workset tests pass. Independent review and the latest CodeRabbit review found no remaining actionable issues. The rendered page was checked at desktop and phone widths. Full-suite results and environment-specific rerun evidence are in the PR description.

The remaining gate is human approval of the CI and Security workflows, followed by review of their results before merging. Those runs have not executed for this commit. No merge or release has been performed.

[ChampPABA]

Thanks for picking this up. Looks good to me. Ping me if anything needs changing on my end after CI runs.

[alfred-openspec]

Reviewed at 66a4b77. The opener reference matches the current configuration and launch behavior, including built-in overrides and disabled attach-dirs handling. Build and all 64 focused tests pass.