docs: experimental flags table in CLI reference is out of sync with runtime-flags.ts

[gzb1128]

Description

The CLI reference's Experimental environment variables table is missing OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS even though the flag exists in packages/opencode/src/effect/runtime-flags.ts and is required for the background subagents feature added in #27084.

The docs table is manually maintained across localized packages/web/src/content/docs/*/cli.mdx files, so it can drift from the runtime flags in code.

Related PR: #27708

Plugins

N/A

OpenCode version

Current dev

Steps to reproduce

1. Open packages/opencode/src/effect/runtime-flags.ts.
2. Confirm OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS is defined.
3. Open packages/web/src/content/docs/cli.mdx or localized cli.mdx docs.
4. Confirm the Experimental environment variables table does not list the flag.

Screenshot and/or share link

N/A

Operating System

N/A

Terminal

N/A

[github-actions]

This issue doesn't fully meet our contributing guidelines.

What needs to be fixed:

• This issue was not submitted using one of the required issue templates (Bug Report, Feature Request, or Question). Please resubmit using the appropriate template — for a documentation bug like this, use the Bug Report template and fill in the required Description field.

Please edit this issue to address the above within 2 hours, or it will be automatically closed.

If you believe this was flagged incorrectly, please let a maintainer know.

[github-actions]

Thanks for updating the issue! It now follows the contributing guidelines and bug report template. The description clearly identifies the problem, includes steps to reproduce, and references the related PR. Appreciate you taking the time to fix it up.

[gzb1128]

I want to propose a follow-up fix for the root cause here before implementing it, because it would add a deterministic CI guard.

Proposed approach

Add a small docs consistency check, likely script/check-experimental-docs.ts, that:

• Extracts OPENCODE_EXPERIMENTAL / OPENCODE_EXPERIMENTAL_* string literals from the canonical flag sources:
  • packages/opencode/src/effect/runtime-flags.ts
  • packages/core/src/flag/flag.ts
• Checks that public experimental flags are documented in the English CLI docs Experimental table.
• Uses an explicit allowlist for intentionally undocumented flags, with a reason for each entry.
• Optionally checks that locale cli.mdx files contain the same Experimental flag set as the English docs, without validating translated descriptions.
• Runs in CI with actionable output: missing English docs entry, missing locale entry, or add to allowlist with a reason if intentionally internal/private/legacy.

Why

The current docs-update.yml flow is useful, but it is not deterministic. A small check would make drift visible during PR review instead of relying on a later docs update pass.

Open questions for maintainers

• Should active OPENCODE_EXPERIMENTAL_* flags be documented by default unless explicitly allowlisted?
• Which existing flags should be considered intentionally internal or legacy, e.g. SCOUT, EVENT_SYSTEM, WORKSPACES, SESSION_SWITCHING, PARALLEL, legacy EXA?
• Should locale parity block CI, or should CI only enforce English docs and leave locale sync to a separate process?
• Would you prefer this deterministic check, a generated docs table from a single flag registry, or improving the existing docs-update automation?

If this direction sounds acceptable, I can send a separate focused PR for the check rather than expanding the current docs-only PR.