Refine auxiliary local command surface coverage

product-surface/auxiliary-local-command-surfaces.md

@@ -6,7 +6,7 @@ soft_links: [/product-surface/command-dispatch-and-composition.md, /product-surf
 
 # Auxiliary Local Command Surfaces
 
-Claude Code includes a small class of commands that are user-facing but do not behave like ordinary transcript turns. They may open a self-contained local JSX surface, execute a sidecar query without mutating the main conversation, or hand off to a gated plugin-backed local experience with hidden helper steps.
+Claude Code includes a small class of commands that are user-facing but do not behave like ordinary transcript turns. They may open a self-contained local JSX surface, execute a sidecar query without mutating the main conversation, hand off to a gated plugin-backed local experience with hidden helper steps, or run a narrow local-support action that never becomes a normal chat turn.
 
 ## Scope boundary
 
@@ -15,6 +15,8 @@ This leaf covers:
 - local-only command surfaces that intentionally stay outside the ordinary transcript-turn contract
 - quick side-question flows that reuse the current context without interrupting the main conversation
 - gated experiential or celebratory commands that may bootstrap plugin or artifact state before rendering locally
+- one-shot local handoff commands that open an external destination or helper surface without creating transcript content
+- hidden or support-only local actions that may ship in some builds while staying outside the ordinary product promise
 
 It intentionally does not re-document:
 
@@ -52,6 +54,17 @@ Equivalent behavior should preserve:
 
 This keeps optional or seasonal experiences cleanly separable from the baseline coding runtime without making them feel like broken stubs.
 
+## Some local commands are one-shot handoff helpers
+
+Equivalent behavior should preserve:
+
+- a user-visible local command being allowed to do one narrow local action such as opening a browser destination or another OS-level handoff target
+- that handoff remaining explicit and user-visible instead of silently backgrounding side effects
+- success and failure returning concise local confirmation text rather than creating a fake assistant turn
+- these helpers staying in the same auxiliary-command family as side-question and experiential surfaces, not being misclassified as generic web or shell automation
+
+The clean-room point is that some command names exist to bridge the user into another local or browser surface, not to run a model workflow.
+
 ## Hidden helper steps stay hidden
 
 Equivalent behavior should preserve:
@@ -62,6 +75,16 @@ Equivalent behavior should preserve:
 
 The tree should capture the existence of hidden helper stages, not their implementation trivia.
 
+## Support-only local actions can stay shipped but non-promoted
+
+Equivalent behavior should preserve:
+
+- some local commands existing primarily for support, diagnostics, or build-specific operator workflows rather than routine end-user discovery
+- hidden support actions being allowed to produce a narrow local result without implying that the same surface must appear in help, onboarding, or SDK-visible inventories
+- disabled or stubbed command names remaining explicitly non-promissory: a rebuild should not invent behavior merely because a hidden directory or registration point exists
+
+This lets the product carry operational helper surfaces and inert stubs without collapsing them into the public compatibility contract.
+
 ## Local surfaces may still hand off to external artifacts
 
 Equivalent behavior should preserve:
@@ -75,6 +98,7 @@ Equivalent behavior should preserve:
 - **transcript pollution**: a local side-question or experiential command writes ordinary transcript turns even though it should remain a local surface
 - **gate bypass**: a gated local surface becomes reachable in builds or accounts where the parent capability should not exist
 - **helper overshare**: support-only commands become visible in help, SDK bootstrap, or bridge inventories
+- **fake public promise**: hidden stubs or support-only locals are rebuilt as ordinary supported commands even though the observed product kept them non-promoted
 - **half-installed experience**: a plugin-backed local experience is exposed before its prerequisites can be checked or repaired coherently
 - **dismissal breakage**: leaving the local surface mutates the main conversation state instead of returning the user to the unchanged primary shell