docs(config): document the full opener configuration - #1356

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.