docs: refresh feature flag audit

FEATURES.md

@@ -1,197 +1,316 @@
-# Feature Flags
+# Feature Flags Audit
 
-This repository has two different "experimental" mechanisms:
+Audit date: 2026-03-31
 
-1. `bun run build:dev`
-   Builds a dev-stamped binary (`cli-dev`) and marks it as an experimental build.
-   It does not automatically enable every compile-time feature flag in the source.
+This repository currently references 88 `feature('FLAG')` compile-time flags.
+I re-checked them by bundling the CLI once per flag on top of the current
+external-build defines and externals. Result:
 
-2. `feature('FLAG_NAME')`
-   Bun compile-time flags that include or strip code paths at build time.
+- 54 flags bundle cleanly in this snapshot
+- 34 flags still fail to bundle
+
+Important: "bundle cleanly" does not always mean "runtime-safe". Some flags
+still depend on optional native modules, claude.ai OAuth, GrowthBook gates, or
+externalized `@ant/*` packages.
 
 ## Build Variants
 
 - `bun run build`
   Builds the regular external binary at `./cli`.
+- `bun run compile`
+  Builds the regular external binary at `./dist/cli`.
 - `bun run build:dev`
-  Builds `./cli-dev` with a `-dev.YYYYMMDD.tHHMMSS.sha...` version and the experimental GrowthBook client key.
+  Builds `./cli-dev` with a dev-stamped version and experimental GrowthBook key.
 - `bun run build:dev:full`
-  Builds `./cli-dev` with the snapshot-safe experimental bundle listed below.
-
-## Snapshot-Safe Experimental Bundle
+  Builds `./cli-dev` with the current compile-safe experimental bundle:
+  `QUICK_SEARCH`, `HISTORY_PICKER`, `TOKEN_BUDGET`, `ULTRAPLAN`,
+  `CACHED_MICROCOMPACT`, and `PROMPT_CACHE_BREAK_DETECTION`.
 
-The following flags were smoke-tested against this leaked source snapshot and compile successfully together:
+## Default Build Flags
 
-- `QUICK_SEARCH`
-  Enables prompt quick-search UI paths.
-- `HISTORY_PICKER`
-  Enables interactive prompt history picker UI.
-- `TOKEN_BUDGET`
-  Enables token budget tracking and related UI warnings.
 - `VOICE_MODE`
-  Enables voice-mode UI and command paths.
-  Runtime still depends on optional native audio support.
-- `ULTRAPLAN`
-  Enables ultraplan command and prompt-input triggers.
-- `CACHED_MICROCOMPACT`
-  Enables cached microcompact plumbing.
-- `PROMPT_CACHE_BREAK_DETECTION`
-  Enables cache-break detection around compact/query flow.
+  This is now included in the default build pipeline, not just the dev build.
+  It enables `/voice`, push-to-talk UI, voice notices, and dictation plumbing.
+  Runtime still depends on claude.ai OAuth plus either the native audio module
+  or a fallback recorder such as SoX.
 
-These are the flags used by `build:dev:full`.
+## Working Experimental Features
 
-`CHICAGO_MCP` compiles from this snapshot, but the resulting binary is not
-runtime-safe because it reaches unresolved `@ant/*` computer-use modules.
-It is intentionally excluded from `build:dev:full`.
+These are the user-facing or behavior-changing flags that currently bundle
+cleanly and should still be treated as experimental in this snapshot unless
+explicitly called out as default-on.
 
-## Flags Present In Source
+### Interaction and UI Experiments
 
-The codebase references these compile-time flags:
+- `AWAY_SUMMARY`
+  Adds away-from-keyboard summary behavior in the REPL.
+- `HISTORY_PICKER`
+  Enables the interactive prompt history picker.
+- `HOOK_PROMPTS`
+  Passes the prompt/request text into hook execution flows.
+- `KAIROS_BRIEF`
+  Enables brief-only transcript layout and BriefTool-oriented UX without the
+  full assistant stack.
+- `KAIROS_CHANNELS`
+  Enables channel notices and channel callback plumbing around MCP/channel
+  messaging.
+- `LODESTONE`
+  Enables deep-link / protocol-registration related flows and settings wiring.
+- `MESSAGE_ACTIONS`
+  Enables message action entrypoints in the interactive UI.
+- `NEW_INIT`
+  Enables the newer `/init` decision path.
+- `QUICK_SEARCH`
+  Enables prompt quick-search behavior.
+- `SHOT_STATS`
+  Enables additional shot-distribution stats views.
+- `TOKEN_BUDGET`
+  Enables token budget tracking, prompt triggers, and token warning UI.
+- `ULTRAPLAN`
+  Enables `/ultraplan`, prompt triggers, and exit-plan affordances.
+- `ULTRATHINK`
+  Enables the extra thinking-depth mode switch.
+- `VOICE_MODE`
+  Enables voice toggling, dictation keybindings, voice notices, and voice UI.
+
+### Agent, Memory, and Planning Experiments
 
-- `ABLATION_BASELINE`
 - `AGENT_MEMORY_SNAPSHOT`
+  Stores extra custom-agent memory snapshot state in the app.
 - `AGENT_TRIGGERS`
+  Enables local cron/trigger tools and bundled trigger-related skills.
 - `AGENT_TRIGGERS_REMOTE`
-- `ALLOW_TEST_VERSIONS`
-- `ANTI_DISTILLATION_CC`
-- `AUTO_THEME`
-- `AWAY_SUMMARY`
-- `BASH_CLASSIFIER`
-- `BG_SESSIONS`
-- `BREAK_CACHE_COMMAND`
-- `BRIDGE_MODE`
-- `BUDDY`
-- `BUILDING_CLAUDE_APPS`
+  Enables the remote trigger tool path.
 - `BUILTIN_EXPLORE_PLAN_AGENTS`
-- `BYOC_ENVIRONMENT_RUNNER`
+  Enables built-in explore/plan agent presets.
 - `CACHED_MICROCOMPACT`
+  Enables cached microcompact state through query and API flows.
+- `COMPACTION_REMINDERS`
+  Enables reminder copy around compaction and attachment flows.
+- `EXTRACT_MEMORIES`
+  Enables post-query memory extraction hooks.
+- `PROMPT_CACHE_BREAK_DETECTION`
+  Enables cache-break detection around compaction/query/API flow.
+- `TEAMMEM`
+  Enables team-memory files, watcher hooks, and related UI messages.
+- `VERIFICATION_AGENT`
+  Enables verification-agent guidance in prompts and task/todo tooling.
+
+### Tools, Permissions, and Remote Experiments
+
+- `BASH_CLASSIFIER`
+  Enables classifier-assisted bash permission decisions.
+- `BRIDGE_MODE`
+  Enables Remote Control / REPL bridge command and entitlement paths.
 - `CCR_AUTO_CONNECT`
+  Enables the CCR auto-connect default path.
 - `CCR_MIRROR`
+  Enables outbound-only CCR mirror sessions.
 - `CCR_REMOTE_SETUP`
+  Enables the remote setup command path.
 - `CHICAGO_MCP`
-- `COMMIT_ATTRIBUTION`
-- `COMPACTION_REMINDERS`
+  Enables computer-use MCP integration paths and wrapper loading.
 - `CONNECTOR_TEXT`
-- `CONTEXT_COLLAPSE`
-- `COORDINATOR_MODE`
+  Enables connector-text block handling in API/logging/UI paths.
+- `MCP_RICH_OUTPUT`
+  Enables richer MCP UI rendering.
+- `NATIVE_CLIPBOARD_IMAGE`
+  Enables the native macOS clipboard image fast path.
+- `POWERSHELL_AUTO_MODE`
+  Enables PowerShell-specific auto-mode permission handling.
+- `TREE_SITTER_BASH`
+  Enables the tree-sitter bash parser backend.
+- `TREE_SITTER_BASH_SHADOW`
+  Enables the tree-sitter bash shadow rollout path.
+- `UNATTENDED_RETRY`
+  Enables unattended retry behavior in API retry flows.
+
+## Bundle-Clean Support Flags
+
+These also bundle cleanly, but they are mostly rollout, platform, telemetry,
+or plumbing toggles rather than user-facing experimental features.
+
+- `ABLATION_BASELINE`
+  CLI ablation/baseline entrypoint toggle.
+- `ALLOW_TEST_VERSIONS`
+  Allows test versions in native installer flows.
+- `ANTI_DISTILLATION_CC`
+  Adds anti-distillation request metadata.
+- `BREAK_CACHE_COMMAND`
+  Injects the break-cache command path.
 - `COWORKER_TYPE_TELEMETRY`
-- `DAEMON`
-- `DIRECT_CONNECT`
+  Adds coworker-type telemetry fields.
 - `DOWNLOAD_USER_SETTINGS`
+  Enables settings-sync pull paths.
 - `DUMP_SYSTEM_PROMPT`
-- `ENHANCED_TELEMETRY_BETA`
-- `EXPERIMENTAL_SKILL_SEARCH`
-- `EXTRACT_MEMORIES`
+  Enables the system-prompt dump path.
 - `FILE_PERSISTENCE`
-- `FORK_SUBAGENT`
+  Enables file persistence plumbing.
 - `HARD_FAIL`
-- `HISTORY_PICKER`
-- `HISTORY_SNIP`
-- `HOOK_PROMPTS`
+  Enables stricter failure/logging behavior.
 - `IS_LIBC_GLIBC`
+  Forces glibc environment detection.
 - `IS_LIBC_MUSL`
-- `KAIROS`
-- `KAIROS_BRIEF`
-- `KAIROS_CHANNELS`
-- `KAIROS_DREAM`
-- `KAIROS_GITHUB_WEBHOOKS`
-- `KAIROS_PUSH_NOTIFICATION`
-- `LODESTONE`
-- `MCP_RICH_OUTPUT`
-- `MCP_SKILLS`
-- `MEMORY_SHAPE_TELEMETRY`
-- `MESSAGE_ACTIONS`
-- `MONITOR_TOOL`
+  Forces musl environment detection.
 - `NATIVE_CLIENT_ATTESTATION`
-- `NATIVE_CLIPBOARD_IMAGE`
-- `NEW_INIT`
-- `OVERFLOW_TEST_TOOL`
+  Adds native attestation marker text in the system header.
 - `PERFETTO_TRACING`
-- `POWERSHELL_AUTO_MODE`
-- `PROACTIVE`
-- `PROMPT_CACHE_BREAK_DETECTION`
-- `QUICK_SEARCH`
-- `REACTIVE_COMPACT`
-- `REVIEW_ARTIFACT`
-- `RUN_SKILL_GENERATOR`
-- `SELF_HOSTED_RUNNER`
-- `SHOT_STATS`
+  Enables perfetto tracing hooks.
 - `SKILL_IMPROVEMENT`
+  Enables skill-improvement hooks.
+- `SKIP_DETECTION_WHEN_AUTOUPDATES_DISABLED`
+  Skips updater detection when auto-updates are disabled.
 - `SLOW_OPERATION_LOGGING`
-- `SSH_REMOTE`
-- `TEAMMEM`
-- `TEMPLATES`
-- `TERMINAL_PANEL`
-- `TOKEN_BUDGET`
-- `TORCH`
-- `TRANSCRIPT_CLASSIFIER`
-- `TREE_SITTER_BASH`
-- `TREE_SITTER_BASH_SHADOW`
-- `UDS_INBOX`
-- `ULTRAPLAN`
-- `ULTRATHINK`
-- `UNATTENDED_RETRY`
+  Enables slow-operation logging.
 - `UPLOAD_USER_SETTINGS`
-- `VERIFICATION_AGENT`
+  Enables settings-sync push paths.
+
+## Compile-Safe But Runtime-Caveated
+
+These bundle today, but I would still treat them as experimental because they
+have meaningful runtime caveats:
+
 - `VOICE_MODE`
-- `WEB_BROWSER_TOOL`
-- `WORKFLOW_SCRIPTS`
+  Bundles cleanly, but requires claude.ai OAuth and a local recording backend.
+  The native audio module is optional now; on this machine the fallback path
+  asks for `brew install sox`.
+- `NATIVE_CLIPBOARD_IMAGE`
+  Bundles cleanly, but only accelerates macOS clipboard reads when
+  `image-processor-napi` is present.
+- `BRIDGE_MODE`, `CCR_AUTO_CONNECT`, `CCR_MIRROR`, `CCR_REMOTE_SETUP`
+  Bundle cleanly, but are gated at runtime on claude.ai OAuth plus GrowthBook
+  entitlement checks.
+- `KAIROS_BRIEF`, `KAIROS_CHANNELS`
+  Bundle cleanly, but they do not restore the full missing assistant stack.
+  They only expose the brief/channel-specific surfaces that still exist.
+- `CHICAGO_MCP`
+  Bundles cleanly, but the runtime path still reaches externalized
+  `@ant/computer-use-*` packages. This is compile-safe, not fully
+  runtime-safe, in the external snapshot.
+- `TEAMMEM`
+  Bundles cleanly, but only does useful work when team-memory config/files are
+  actually enabled in the environment.
 
-## High-Traffic Feature Families
+## Broken Flags With Easy Reconstruction Paths
 
-These are the most prominent feature families in the snapshot:
+These are the failed flags where the current blocker looks small enough that a
+focused reconstruction pass could probably restore them without rebuilding an
+entire subsystem.
 
-- Assistant / brief / channels
-  `KAIROS`, `KAIROS_BRIEF`, `KAIROS_CHANNELS`, `KAIROS_GITHUB_WEBHOOKS`, `KAIROS_PUSH_NOTIFICATION`, `KAIROS_DREAM`
-- Classifiers / auto mode
-  `TRANSCRIPT_CLASSIFIER`, `BASH_CLASSIFIER`, `TREE_SITTER_BASH`, `TREE_SITTER_BASH_SHADOW`
-- Remote / bridge / computer-use
-  `BRIDGE_MODE`, `DAEMON`, `DIRECT_CONNECT`, `SSH_REMOTE`, `CHICAGO_MCP`, `WEB_BROWSER_TOOL`
-- Planning / agents / automation
-  `ULTRAPLAN`, `COORDINATOR_MODE`, `FORK_SUBAGENT`, `AGENT_TRIGGERS`, `AGENT_TRIGGERS_REMOTE`, `VERIFICATION_AGENT`
-- Context / compact / memory
-  `CONTEXT_COLLAPSE`, `REACTIVE_COMPACT`, `CACHED_MICROCOMPACT`, `PROMPT_CACHE_BREAK_DETECTION`, `TOKEN_BUDGET`, `HISTORY_SNIP`, `BG_SESSIONS`, `TEAMMEM`, `EXTRACT_MEMORIES`
-- UI extras
-  `QUICK_SEARCH`, `HISTORY_PICKER`, `VOICE_MODE`, `MESSAGE_ACTIONS`, `AUTO_THEME`, `SHOT_STATS`
+- `AUTO_THEME`
+  Fails on missing `src/utils/systemThemeWatcher.js`. `systemTheme.ts` and the
+  theme provider already contain the cache/parsing logic, so the missing piece
+  looks like the OSC 11 watcher only.
+- `BG_SESSIONS`
+  Fails on missing `src/cli/bg.js`. The CLI fast-path dispatch in
+  `src/entrypoints/cli.tsx` is already wired.
+- `BUDDY`
+  Fails on missing `src/commands/buddy/index.js`. The buddy UI components and
+  prompt-input hooks already exist.
+- `BUILDING_CLAUDE_APPS`
+  Fails on missing `src/claude-api/csharp/claude-api.md`. This looks like an
+  asset/document gap, not a missing runtime subsystem.
+- `COMMIT_ATTRIBUTION`
+  Fails on missing `src/utils/attributionHooks.js`. Setup and cache-clear code
+  already call into that hook module.
+- `FORK_SUBAGENT`
+  Fails on missing `src/commands/fork/index.js`. Command slot and message
+  rendering support are already present.
+- `HISTORY_SNIP`
+  Fails on missing `src/commands/force-snip.js`. The surrounding SnipTool and
+  query/message comments are already there.
+- `KAIROS_GITHUB_WEBHOOKS`
+  Fails on missing `src/tools/SubscribePRTool/SubscribePRTool.js`. The command
+  slot and some message handling already exist.
+- `KAIROS_PUSH_NOTIFICATION`
+  Fails on missing `src/tools/PushNotificationTool/PushNotificationTool.js`.
+  The tool slot already exists in `src/tools.ts`.
+- `MCP_SKILLS`
+  Fails on missing `src/skills/mcpSkills.js`. `mcpSkillBuilders.ts` already
+  exists specifically to support that missing registry layer.
+- `MEMORY_SHAPE_TELEMETRY`
+  Fails on missing `src/memdir/memoryShapeTelemetry.js`. The hook call sites
+  are already in place in `sessionFileAccessHooks.ts`.
+- `OVERFLOW_TEST_TOOL`
+  Fails on missing `src/tools/OverflowTestTool/OverflowTestTool.js`. This
+  appears isolated and test-only.
+- `RUN_SKILL_GENERATOR`
+  Fails on missing `src/runSkillGenerator.js`. The bundled skill registration
+  path already expects it.
+- `TEMPLATES`
+  Fails on missing `src/cli/handlers/templateJobs.js`. The CLI fast-path is
+  already wired in `src/entrypoints/cli.tsx`.
+- `TORCH`
+  Fails on missing `src/commands/torch.js`. This looks like a single command
+  entry gap.
+- `TRANSCRIPT_CLASSIFIER`
+  The first hard failure is missing
+  `src/utils/permissions/yolo-classifier-prompts/auto_mode_system_prompt.txt`.
+  The classifier engine, parser, and settings plumbing already exist, so the
+  missing prompt/assets are likely the first reconstruction target.
 
-## Known Broken In This Snapshot
+## Broken Flags With Partial Wiring But Medium-Sized Gaps
 
-These flags do appear in source, but turning them on currently fails to build because referenced modules are missing from the leaked snapshot:
+These do have meaningful surrounding code, but the missing piece is larger
+than a single wrapper or asset.
 
-- `KAIROS`
-- `KAIROS_BRIEF`
-- `PROACTIVE`
-- `BRIDGE_MODE`
+- `BYOC_ENVIRONMENT_RUNNER`
+  Missing `src/environment-runner/main.js`.
+- `CONTEXT_COLLAPSE`
+  Missing `src/tools/CtxInspectTool/CtxInspectTool.js`.
+- `COORDINATOR_MODE`
+  Missing `src/coordinator/workerAgent.js`.
 - `DAEMON`
+  Missing `src/daemon/workerRegistry.js`.
 - `DIRECT_CONNECT`
-- `SSH_REMOTE`
-- `COORDINATOR_MODE`
-- `CHICAGO_MCP`
-- `BUDDY`
-- `UDS_INBOX`
-- `CONTEXT_COLLAPSE`
-- `REACTIVE_COMPACT`
+  Missing `src/server/parseConnectUrl.js`.
 - `EXPERIMENTAL_SKILL_SEARCH`
-- `MCP_SKILLS`
-- `WORKFLOW_SCRIPTS`
+  Missing `src/services/skillSearch/localSearch.js`.
 - `MONITOR_TOOL`
+  Missing `src/tools/MonitorTool/MonitorTool.js`.
+- `REACTIVE_COMPACT`
+  Missing `src/services/compact/reactiveCompact.js`.
 - `REVIEW_ARTIFACT`
-- `TEAMMEM`
-- `TRANSCRIPT_CLASSIFIER`
+  Missing `src/hunter.js`.
+- `SELF_HOSTED_RUNNER`
+  Missing `src/self-hosted-runner/main.js`.
+- `SSH_REMOTE`
+  Missing `src/ssh/createSSHSession.js`.
+- `TERMINAL_PANEL`
+  Missing `src/tools/TerminalCaptureTool/TerminalCaptureTool.js`.
+- `UDS_INBOX`
+  Missing `src/utils/udsMessaging.js`.
+- `WEB_BROWSER_TOOL`
+  Missing `src/tools/WebBrowserTool/WebBrowserTool.js`.
+- `WORKFLOW_SCRIPTS`
+  Fails first on `src/commands/workflows/index.js`, but there are more gaps:
+  `tasks.ts` already expects `LocalWorkflowTask`, and `tools.ts` expects a
+  real `WorkflowTool` implementation while only `WorkflowTool/constants.ts`
+  exists in this snapshot.
 
-The failures are mostly missing files such as assistant-mode modules, remote/server modules, workflow/monitor tools, skill-search modules, classifier prompt files, and team-memory helpers.
+## Broken Flags With Large Missing Subsystems
+
+These are the ones that still look expensive to restore because the first
+missing import is only the visible edge of a broader absent subsystem.
+
+- `KAIROS`
+  Missing `src/assistant/index.js` and much of the assistant stack with it.
+- `KAIROS_DREAM`
+  Missing `src/dream.js` and related dream-task behavior.
+- `PROACTIVE`
+  Missing `src/proactive/index.js` and the proactive task/tool stack.
 
 ## Useful Entry Points
 
 - Feature-aware build logic:
   [scripts/build.ts](/Users/paolo/Repos/claude-code/scripts/build.ts)
-- Experimental GrowthBook key selection:
-  [src/constants/keys.ts](/Users/paolo/Repos/claude-code/src/constants/keys.ts)
 - Feature-gated command imports:
   [src/commands.ts](/Users/paolo/Repos/claude-code/src/commands.ts)
 - Feature-gated tool imports:
   [src/tools.ts](/Users/paolo/Repos/claude-code/src/tools.ts)
+- Feature-gated task imports:
+  [src/tasks.ts](/Users/paolo/Repos/claude-code/src/tasks.ts)
 - Feature-gated query behavior:
   [src/query.ts](/Users/paolo/Repos/claude-code/src/query.ts)
-- Feature-gated CLI options and startup flow:
-  [src/main.tsx](/Users/paolo/Repos/claude-code/src/main.tsx)
+- Feature-gated CLI entry paths:
+  [src/entrypoints/cli.tsx](/Users/paolo/Repos/claude-code/src/entrypoints/cli.tsx)