From 6163bb779bf13e8ce9d4946ac3f6d61699eb5460 Mon Sep 17 00:00:00 2001 From: Bingran You Date: Tue, 14 Apr 2026 16:08:25 -0700 Subject: [PATCH] docs: refine auxiliary local command surfaces --- .../auxiliary-local-command-surfaces.md | 26 ++++++++++++++++++- 1 file changed, 25 insertions(+), 1 deletion(-) diff --git a/product-surface/auxiliary-local-command-surfaces.md b/product-surface/auxiliary-local-command-surfaces.md index 9723fc5..64227d2 100644 --- a/product-surface/auxiliary-local-command-surfaces.md +++ b/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