feat(experimental): gate experimental commands behind OBSERVE_CLI_EXPERIMENTAL

[obs-gh-abhinavpappu]

Summary

Adds experimental command gating to the CLI (OB-61541). A command marked experimental is:

• hidden from help unless OBSERVE_CLI_EXPERIMENTAL=1,
• non-runnable without the flag (friendly message + exit 1, even if the command name is known),
• badged [experimental] in help when visible.

SemVer covers only the default (non-experimental) surface; opting in carries no stability guarantees.

What's here

New src/lib/experimental.ts with the toolkit:

• isExperimentalEnabled(env?) — reads OBSERVE_CLI_EXPERIMENTAL (1/true)
• withExperimentalBadge(brief) — prefixes the [experimental] badge
• hideExperimentalRoutes([names], env?) — builds a docs.hideRoute map that hides routes until the flag is set
• gateExperimental(handler, env?) — wraps a command loader to block execution
• experimentalDisabledMessage() — the friendly message shown when a gated command is run without the flag

Demonstrated on real commands

To make the change obvious, two existing commands are marked experimental:

• data-connection generate-stack-url — the single-command case: gate the loader, badge the brief, add the name to the parent map's hideRoute.
• The content group — the whole-group case: badge the group brief, hide content in app.ts, and (because hiding does not block execution) wrap each of the 6 leaf loaders with gateExperimental.

Marking a command experimental (and un-marking at GA)

Three touches, all from src/lib/experimental.ts: gateExperimental on the loader, withExperimentalBadge on the brief, and the route name in the parent's hideRoute. Promoting to GA = deleting those three markers. Full guide in AGENTS.md.

Notes for reviewers

• Group gating cost: hiding + badging a group are one line each, but stricli has no group-level execution hook, so blocking execution requires wrapping every leaf loader (6 files for content). That per-leaf friction motivates a possible follow-up (a single declarative experimental: true).
• Existing unit tests for the gated commands are unaffected — they call the handler functions directly, not the gated loader.
• generate-stack-url and content are removed from the README command table while experimental (experimental commands are intentionally undocumented for users).

Verification

• bun run typecheck, bun run lint, bun run format — clean
• bun test — 263 pass
• Manual: with the flag off, gated commands are hidden and refuse to run; with OBSERVE_CLI_EXPERIMENTAL=1 they appear with the [experimental] badge and execute.

🤖 Generated with Claude Code