@f5-sales-demo/xcsh 21.45.0 → 21.45.2

package/src/internal-urls/build-info.generated.ts

@@ -17,17 +17,17 @@ export interface BuildInfo {
 }
 
 export const BUILD_INFO: BuildInfo = {
-	"version": "21.45.0",
-	"commit": "1a7543cf3b387497a063638d4272702fa34615af",
-	"shortCommit": "1a7543c",
+	"version": "21.45.2",
+	"commit": "03750851e444f62aa128f72454749f7ab824afdd",
+	"shortCommit": "0375085",
 	"branch": "main",
-	"tag": "v21.45.0",
-	"commitDate": "2026-09-25T12:46:49Z",
-	"buildDate": "2026-09-25T13:23:22.662Z",
+	"tag": "v21.45.2",
+	"commitDate": "2026-09-25T14:32:18Z",
+	"buildDate": "2026-09-25T15:08:16.358Z",
 	"dirty": true,
 	"prNumber": "",
 	"repoUrl": "https://github.com/f5-sales-demo/xcsh",
 	"repoSlug": "f5-sales-demo/xcsh",
-	"commitUrl": "https://github.com/f5-sales-demo/xcsh/commit/1a7543cf3b387497a063638d4272702fa34615af",
-	"releaseUrl": "https://github.com/f5-sales-demo/xcsh/releases/tag/v21.45.0"
+	"commitUrl": "https://github.com/f5-sales-demo/xcsh/commit/03750851e444f62aa128f72454749f7ab824afdd",
+	"releaseUrl": "https://github.com/f5-sales-demo/xcsh/releases/tag/v21.45.2"
 };

package/src/internal-urls/docs-index.generated.ts

@@ -15,7 +15,7 @@ export const EMBEDDED_DOCS: Readonly<Record<string, string>> = {
 	"en/architecture-contribution/storage-artifacts.mdx": "---\ntitle: \"Storage, blobs, and artifacts\"\ndescription: \"Trace configuration roots, session JSONL, binary blobs, text artifacts, scan caches, and move semantics.\"\nsidebar:\n  order: 2\n  label: \"Storage and artifacts\"\n---\n\nxcsh separates append-only conversation state from large or generated payloads. Session JSON Lines (JSONL) preserves the event graph; blob and artifact stores keep bulky data addressable without inflating every session entry.\n\n## How are stored values allocated and resolved?\n\nStorage helpers choose user or project roots, allocate collision-resistant identifiers, and record names separately from content addresses. Text artifacts remain inspectable; binary blobs are externalized and referenced by uniform resource locator (URL)-like identifiers. URL handlers validate the scheme and authority before opening the backing object.\n\n## How do resume, fork, and move treat state?\n\nResume rebuilds context from the selected session leaf. Forking creates a new branch without rewriting the source branch. Moves must update the session reference and its dependent stored values as one operation or leave the original valid; partial copies are not a successful move.\n\n## How is filesystem discovery cached?\n\nThe scan cache partitions keys by root and discovery options, evicts by freshness policy, and uses a short empty-result recheck so a newly created configuration file is noticed. Mutating code owns invalidation. A new consumer must define its cache key, freshness need, and invalidation points explicitly.\n\nRead `packages/coding-agent/src/session` for the append-only event graph and `packages/coding-agent/src/discovery` for the scan cache.\n\nTreat a session reference as durable only after its referenced artifact is readable. A failed move\nor fork must leave the original graph usable and must not publish a half-written destination. To\nverify a storage change, create a session with a text artifact and a binary blob, resume its leaf,\nfork it, and confirm that both branches resolve their own references. Remove only the temporary test\nroot after those reads succeed.\n",
 	"en/architecture-contribution/tool-runtime.mdx": "---\ntitle: \"Tool runtime\"\ndescription: \"Trace Bash, notebook, deferred-action, custom-tool, context, and task-agent execution boundaries.\"\nsidebar:\n  order: 3\n  label: \"Tool runtime\"\n---\n\nThe agent loop sees a common tool contract, but each runtime owns its validation, cancellation, output, and side effects.\n\n## How do shell and notebook work execute?\n\nThe Bash tool validates the request, launches through the configured shell boundary, streams bounded output, and spills oversized results to an artifact. Notebook editing changes cell structure; kernel execution is a separate Python gateway operation with its own environment and Multipurpose Internet Mail Extensions (MIME) rendering.\n\n## How are deferred actions resolved?\n\nDeferred actions are pushed onto a last-in, first-out stack and resolved only at the runtime checkpoint that owns them. Custom tools use the host application programming interface (API) to register actions; they must pair cancellation and cleanup with any external resource they create.\n\n## How are commands and task agents discovered?\n\nSlash-command templates and agent definitions are discovered from normalized user, project, plugin, and bundled providers. Precedence resolves duplicate identifiers before execution. Argument expansion produces prompt input; it must not bypass tool policy or agent execution guardrails.\n\nRead `packages/coding-agent/src/tools/bash.ts` for the shell boundary, `packages/coding-agent/src/tools/notebook.ts` for cell editing, and `packages/coding-agent/src/slash-commands/builtin-registry.ts` for command discovery.\n\nTool completion has three independent outcomes: the process or handler settles, bounded output is\nstored, and the agent loop receives a normalized result. Cancellation must settle all three without\na second completion. Test successful output, nonzero exit, oversized output, cancellation, and\ncleanup. Any tool that writes files, starts a process, or calls a service owns that side effect; the\nrenderer only displays the recorded request and result.\n",
 	"en/architecture-contribution/tui-runtime.mdx": "---\ntitle: \"TUI runtime\"\ndescription: \"Trace component contracts, differential rendering, terminal input, modal UI, and custom tool renderers.\"\nsidebar:\n  order: 8\n  label: \"TUI runtime\"\n---\n\nThe terminal user interface (TUI) renders session and runtime state through components. Components return terminal cells and semantic styles; the renderer computes a differential update instead of repainting unrelated rows.\n\n## How are input and rendering routed?\n\nTerminal decoding turns bytes and escape sequences into key events. Focused overlays receive input before the prompt editor and global actions. State changes schedule a render, layout produces the next frame, and the diff layer emits only changed terminal regions.\n\n## How do I extend interactive surfaces?\n\nExtensions can open a modal through `ctx.ui.custom` only when an interactive UI host exists. Custom tools may provide renderers for calls and results while preserving a plain-text representation for headless clients. A renderer must not become the only copy of durable tool output.\n\nRead `packages/tui/src` for the component and rendering contracts, and `packages/coding-agent/src/tui` for the session-aware components built on them.\n\nUse the [TUI interaction style guide](/xcsh/en/architecture-contribution/tui-style-guide/) when adding a selector or manager. It\ndefines the shared frame, responsive density, search and escape behavior, plain-text state semantics,\nand asynchronous feedback expected from interactive surfaces.\n\n## How are development native prerequisites kept current?\n\n`bun run dev`, `bun run test:ts`, and the coding-agent package's `bun run test` prepare the\nsource-matched native addon automatically. The bootstrap checks a fingerprint of native sources,\nbuild inputs, and the host binary, then validates all runtime exports declared by the generated\nbindings in a fresh subprocess. Changed sources, missing artifacts, or incompatible bindings trigger\na build; readiness is recorded only after the rebuilt addon passes another fresh-process check.\nAn unchanged, verified checkout does not rebuild on every invocation.\n\nFor direct `bun test <file>` or direct source CLI invocation, first run\n`bun scripts/ensure-dev-native.ts`. Bare `bun test` does not run package lifecycle scripts.\nDo not patch a JavaScript stub to add `PowerAssertion` or another missing export: the source and\nnative addon must match. A failed bootstrap reports the build or compatibility error and exits\nnonzero; follow the Rust/Zig prerequisites in `DEVELOPING.md`. Development checks require a host\nbuild, so unset cross-compilation targets before running them.\n\nValidate visual changes in a real pseudo-terminal at narrow and wide widths, in light and dark\nthemes, and with keyboard focus visible. A component must clip or wrap to the width it receives,\nrestore terminal modes after failure, and expose the same durable result to headless clients. When\nan overlay closes, focus returns to the prior owner; when the terminal disconnects, cleanup must\nremain safe to run again.\n",
-	"en/architecture-contribution/tui-style-guide.mdx": "---\ntitle: \"TUI interaction style guide\"\ndescription: \"Build predictable selectors with shared structure, navigation, semantics, and feedback.\"\nsidebar:\n  order: 9\n  label: \"TUI interaction style\"\nhead:\n  - tag: style\n    content: |\n      .sl-markdown-content .expressive-code { max-width: 100%; overflow-x: auto; }\n      .sl-markdown-content table { display: block; max-width: 100%; overflow-x: auto; }\n---\n\nUse this guide for interactive terminal user interface (TUI) selectors and managers. It defines a\nshared interaction contract and adaptable presentation defaults. It does not require unrelated\nscreens to be redesigned in the same change.\n\n## What flow should an interactive manager use?\n\nPrefer one stable, single-column flow:\n\n```text\nbrowse → inspect → choose an explicitly labeled action → see its outcome\n```\n\nGive the frame a clear title. Add a purpose only when the title and choices do not explain the task.\nKeep navigation in a stable position, make the choices searchable, summarize the selected choice\nbriefly, and show contextual keyboard hints.\nPut long descriptions and secondary metadata in a detail view rather than beside the list.\n\nThe `/login` provider list follows this pattern by opening connection management before changing a\nsaved connection. `/model` separates model selection from scope and reasoning choices. `/plugin`\nuses the same pattern for install, update, enable, disable, and removal actions.\n\n## How should a selector look?\n\nUse `selectorFrame` and its adaptive gutters. The shared frame provides rounded Unicode borders,\nan ASCII fallback, joined section dividers, and a maximum width of 100 columns. Keep every rendered\nrow the same width so selection highlighting reaches both inside edges without breaking the border.\n\nUse two spaces between aligned columns. Keep headings subdued and reserve emphasis for selection,\nstate, and outcomes. Color may reinforce meaning, but plain text must carry it:\n\n```text\nPlugin                         Status              Scope\n› source-control               Enabled             project\n  observability                Update 2.1.0        user\n  cloud-tools                  Available           —\n```\n\nAt narrow widths, keep the name in the row and move status, scope, version, and other secondary\ncolumns into the selected summary. Remove optional blank rows before hiding choices, controls, or\nselected information.\n\n## How should input and navigation behave?\n\nTreat familiar terminal conventions as the default interaction vocabulary. Avoid \"captain obvious\"\nindicators: instructions that merely repeat what a recognizable control already communicates.\nMake the layout self-descriptive before adding instructional copy. Removing a hint is appropriate\nonly when the control, its state, and its outcome remain discoverable.\n\nThe following manifest defines the expectations xcsh should consistently support. These are design\ncommitments for this interface, not a claim that every person has identical experience. Preserve\naccessible labels and provide help for unfamiliar or remapped controls.\n\n| Visible situation | Expected human intuition | Interface commitment | Hint policy |\n| --- | --- | --- | --- |\n| A highlighted menu item | Arrows move selection; Enter opens or activates it. | Show one clear selection and make the label predict the result. | Omit `Up/Down: navigate` and `Enter: choose action`. |\n| An item naming a plugin, provider, or other object | Opening it reveals information or choices about that object. | Open details before a management mutation. | Let the object label and detail title explain the transition. |\n| An action naming a verb and target | Activating it performs that named action or opens its clearly labeled review. | Use `Disable plugin`, `Review installation`, or `Remove from project scope`; avoid ambiguous `Select` or `Continue`. | Explain consequences or scope when they affect the decision, not how to press Enter. |\n| A search field | Typing searches; normal editing and paste work. | Keep search visibly associated with its list and preserve editor behavior. | Use a field label; omit `Type to search` when the field already says Search. |\n| A nested menu | Escape returns to the parent. | Return one level and retain the parent's query and selection. | A compact `Esc: back` can clarify the hierarchy; never advertise Ctrl+C as Back. |\n| An active search in a list | Escape clears the search before leaving the list. | Clear the query on the first Escape, then return on the next. | Show `Esc: clear search` only while a query exists. |\n| Section tabs | Changing sections preserves a stable navigation structure. | Keep tab order and selected section visible; use Tab and Shift+Tab consistently here. | A compact section-switching hint is useful because Tab behavior varies between interfaces. |\n| Content longer than the viewport | Navigation reveals the remaining content. | Use available space first; keep selection visible and make all details reachable. | Show paging controls only during overflow, especially when arrows move actions instead of details. |\n| A destructive confirmation | Cancel is safe; the destructive choice names the effect. | Select Cancel initially and show the exact target and scope. | Keep consequence text; omit instructions to select a choice. |\n| An operation underway | Work is proceeding, and another activation should not duplicate it. | Show progress, prevent duplicate submission, and report whether interruption is supported. | Reserve Ctrl+C for interruption; never imply cancellation unless work actually stopped. |\n| An operation completes or fails | The state reflects the outcome and recovery is apparent. | Update the affected item; keep failure context and a usable retry path. | Report the result and any remaining work, not `Action selected` or `Press Enter to continue`. |\n\nUse the shared `Input` component for search. Forward ordinary input to it so spaces, Unicode,\nbracketed paste, cursor movement, deletion, undo, and configured editor bindings work together.\nDo not reserve printable letters as hidden actions while search is active.\n\n- Typing edits the active search; Up and Down move through the filtered choices.\n- Enter inspects a choice, or activates the action whose label is visibly selected.\n- Escape returns one level. In a list it clears an active search before closing the selector.\n- Ctrl+C is reserved for interruption; it must not act as Back or close a menu.\n\nFirst-party extension select/input dialogs use the shared frame and editable input. Selection search\naccepts printable letters; Tab/Shift+Tab changes supplied sections while arrows edit search. Escape\nclears search before closing. Selection timeout closes without activating an option; explicit caller\ntimeout policies remain separate. Confirmation starts on No, and plan approval starts on Stay in plan\nmode. Callback signatures and return types are unchanged.\n\nChoosing `Approve and execute` is an action request, not final consent. Follow it with one Cancel-first\nreview that names the planning session, new execution-session destination, draft and finalized plan\npaths, restored tool scope, prompt submission, and execution consequences. Revalidate plan bytes,\nsession identity, and destination before committing. Extension veto happens before old-session mutation;\npartial session persistence retries the same identity. Do not open a nested `/new` review or continue\nexecution when any approval review is cancelled.\n\nA typed `/plan <prompt>` uses the same review and lifecycle adapters. When planning is already active,\nreview the prompt without toggling or pausing the mode; persist outstanding session state before\nqueueing it, then distinguish queued/model-pending from completion. If an enable save is unresolved,\nshow prompt replacement as old→new. If a pause save is unresolved, review the combined recovery,\npersist the pause, re-enable and persist plan mode, and only then queue the prompt. Never silently drop\nan argument because a prior mode transition is awaiting persistence.\n\nThe application and standalone editor now default `app.interrupt` to Ctrl+C. Idle Ctrl+C retains\ndraft clearing, while double-Escape navigation remains separate from execution. Existing explicit\ninterrupt remaps (including disabled bindings) are respected; there is no configuration migration.\nActive-work hints must display the configured key, not hardcode Escape. Cooperative actions receive\nan abort signal, but an interrupt request alone does not establish cancellation: keep the operation\nvisible until it acknowledges interruption or completes. Normal completion after an interrupt request\nis still success. Unaccounted-for partial failures remain unresolved rather than being labelled cancelled.\n\n- Tab and Shift+Tab move through stable categories when a manager has categories.\n- Page Up and Page Down make long detail content reachable.\n\nHints should explain non-obvious controls, not narrate familiar interaction. Omit `Enter: choose\naction`, `Up/Down: navigate`, and purpose text such as `Browse, inspect, choose an action, and review\nits outcome`. Keep compact hints for section switching, refresh or retry, and the Escape hierarchy.\nShow a paging hint only when content actually exceeds the available space; use the terminal's\navailable height before introducing scrolling. A short detail view needs no scroll instructions.\n\nDocument an exception beside the component when its task genuinely requires different behavior.\nRemapped selector bindings must continue to work; do not hardcode only one escape sequence.\n\nReview each proposed hint against three questions: does it reveal a control that is otherwise\nundiscoverable, explain an exception to these conventions, or clarify a consequence or recovery\nstep? If none applies, remove it. If a conventional interaction needs a paragraph of instructions,\nfirst repair the label, grouping, focus, or navigation behavior. Do not use explanatory copy to\ncompensate for an inconsistent menu.\n\n## How do question-and-answer flows work?\n\nBlocking and asynchronous questions use the same framed, theme-aware presentation as other\nfirst-party selectors. Show one question at a time with its position and unanswered count. The\nhighlight spans the full choice row, while checkbox state distinguishes a highlighted draft from a\ncommitted answer without relying on color. Numbered shortcuts submit their matching choice. Omit a\ndescription row when the option has no description.\n\nKeep notes and free-text answers inside the question frame. Secret input is masked by grapheme in\nevery render, including resize, and the visible transcript must never disclose the secret. Preserve\nthe current question and draft when the terminal resizes. Keep the highlighted choice visible when\nheight is constrained and show scrolling guidance only when content actually overflows.\n\nUnanswered confirmation uses the same frame and keeps `Proceed` as the existing default. Escape\nreturns to the first unanswered question. Hints are contextual and derived from the active selector\nand interrupt bindings; hardcoded hints are limited to controls that are not configurable.\n\nAsynchronous announcements are compact question summaries with a visible `/questions` action.\nCompleted replies remain the exact structured `user_input_reply` payload in model context and\nsession persistence, but the terminal correlates that payload with the preceding question item and\nrenders a friendly answer summary. Correlation IDs and transport envelopes are never visible. A\nmessage that does not correlate to an existing async question is rendered normally rather than\nbeing mistaken for an internal reply.\n\nRead the screen without its keyboard footer. Its title should identify the current task or object;\nhighlighting should identify the active choice; action labels should identify what happens next;\ngrouping should distinguish navigation, actions, facts, and outcomes. Use the same words and order\nfor the same concepts across screens. Keep the affected object identifiable after an operation,\nand explain a change of section when an item moves out of the current list.\n\n## Which states must the copy distinguish?\n\nAvailability, installation, enabled state, scope, and update availability are separate facts. Use\nspecific phrases such as `Available`, `Installed · Disabled`, `project scope`, and\n`Update 2.1.0`. Avoid unexplained symbols and avoid treating an item that exists in a catalog as an\ninstalled or enabled item.\n\nFeedback also needs distinct language and styling:\n\n| State | Copy pattern | Required next step |\n| --- | --- | --- |\n| Loading | `Refreshing plugin catalogs…` | Keep navigation and cached data visible. |\n| Progress | `Installation in progress…` | Prevent duplicate submission. |\n| Success | `Installation completed.` | Show the updated state. |\n| Warning | `Installed 2 of 3 plugins. 1 failed.` | Name remaining work. |\n| Failure | `Refresh failed: catalog unavailable.` | Offer Retry and retain context. |\n| Empty | `No plugins match “trace”.` | Explain how to clear or broaden the search. |\n\nClosing a view does not mean an asynchronous operation was cancelled. Ignore stale completions from\nsuperseded refreshes, keep retry context after failure, and describe continuing work accurately.\n\nDialog creation and teardown are part of this lifecycle contract. A synchronous factory exception,\nrejected asynchronous factory, or failed presentation must settle the caller with an error and\nrelease duplicate-operation guards. Do not replace the draft before a component is ready. Attempt\nremaining cleanup even if one disposal step fails, and report that failure rather than leaving a\nhidden command pending. These internal safeguards must preserve extension callback signatures.\n\n## How do confirmation and review screens work?\n\nEnter from a browse list opens details; it must not install, remove, or toggle the selected item.\nDetails list only actions backed by a persistent manager operation.\n\nInstallation review identifies the source, destination scope, and declared prerequisites before an\ninstall action is available. Removal confirmation starts on `Cancel removal`, not on the destructive\nchoice. A bulk action is a visible row such as `Review recommended setup…`; its review lists every\naffected plugin, the destination scope, prerequisite commands, and partial failures.\n\nClipboard reviews identify the source and replacement effect without reading existing clipboard data.\nExplain that clipboard-history services may retain the text. Wait for the backing copy operation;\nan OSC 52 terminal request has no delivery acknowledgement and must be described as unverified,\nnot as a confirmed copy. On Linux without a clipboard manager, clipboard text may disappear when\nxcsh exits. `/dump`, typed `/copy` subcommands and transcript-selector picks share this review\nand feedback adapter. Other clipboard surfaces must adopt it before candidate acceptance.\n\n## What should reviewers check?\n\n- The title, purpose, choices, selected summary, and controls remain understandable without color.\n- With keyboard hints hidden, the task, selection, action consequences, and current state are clear.\n- Every remaining hint reveals a non-obvious control, an exception, a consequence, or recovery;\n  none merely narrates Enter, arrows, selection, or an already labeled search field.\n- The intuition manifest holds across parent and child menus: consistent labels, stable focus,\n  Escape hierarchy, retained context, and feedback tied to the affected object.\n- Scrolling hints disappear when content fits; Ctrl+C never substitutes for Back.\n- The frame is continuous in Unicode and ASCII, each row has equal width, and highlighting stays\n  inside both borders.\n- Width never exceeds 100 columns; 60×20 still keeps the selected choice and recovery controls.\n- Search handles spaces, Unicode, paste, cursor edits, and no-match results.\n- Enter opens details before mutation; destructive confirmation starts on Cancel.\n- Selection uses the full stable identity, including source, identifier, and scope.\n- Empty, loading, progress, success, warning, failure, retry, and partial failure are\n  distinguishable.\n- Refresh and resize retain tab, query, selection, and available data.\n- Duplicate operations and stale asynchronous updates cannot produce a second or misleading outcome.\n- Long details remain reachable and exceptions to the shared contract are documented.\n\n## Where should the guide be adopted next?\n\nUse focused improvement passes rather than a repository-wide redesign:\n\n1. Keep `/login`, `/model`, and `/plugin` as the reference implementations and regression baseline.\n2. Move settings and extension management to the shared frame and escape hierarchy.\n3. Align session, tree, and agent dashboards where they contain inspectable choices and actions.\n4. Review one-off confirmation and input dialogs for explicit labels, outcome feedback, and narrow\n   terminal behavior.\n5. Document intentional exceptions after usability evidence shows the shared contract is unsuitable.\n\n## What did the slash-command library review identify?\n\nThis inventory covers every built-in entry in `src/slash-commands/builtin-registry.ts`, its\nregistered subcommands, and the extension-command discovery surfaces. The coverage regression\nrequires new built-ins to receive an entry here. It is a source review, not a claim that every\ncommand has received live visual acceptance. Do not exercise cloud mutations, credential removal,\npublication, or session deletion merely to review presentation; use isolated fixtures.\n\nPriorities: P0 protects consequential actions and truthful outcomes; P1 improves everyday navigation;\nP2 improves discovery and presentation. “Next” means proposed work, not completed adoption.\n\n| Command | Surface and enhancement opportunity | Priority / adoption |\n| --- | --- | --- |\n| `/settings` | Tabbed settings and nested editors: shared Escape default and concise hints applied; next, shared frame, retained submenu context, and saved-value feedback. | P1 / partial |\n| `/questions` | Opens pending asynchronous questions through the shared session interaction owner; announcements, framed answers, automatic handoff, and correlated transcript summaries share the question presentation. | Focused protocol, interaction, renderer, privacy, and 16-variant terminal tests pass. |\n| `/plan` | Enable, pause, typed prompts, and approval use session-qualified Cancel-first review, fresh plan and destination validation, veto-before-mutation, same-identity save retry, and truthful queued or completed outcomes. | Focused tests and the 16-variant terminal matrix pass. |\n| `/model` | Browse with stable tabs, editable search, exact identity, explicit scope, and reasoning steps. Mutations use Cancel-first review, fresh catalog resolution, persistence-before-success, and exact no-op handling; `/models` shares this path. | Focused tests and the 16-variant terminal matrix pass. |\n| `/fast` | Offer Cancel, Enable, and Disable. Typed `on`, `off`, and `toggle` use the same session-scoped review; `status` is read-only. Persist before success; cancellation, status, and unchanged requests do not write. | Focused tests and the 16-variant terminal matrix pass. |\n| `/export` | Transcript export: show destination, format, overwrite implications, and an actionable failure. | P1 / next |\n| `/dump` | Cancel-first conversation-to-clipboard review; session/content revalidation; awaited delivery, duplicate rejection, unresolved retry. Distinguish completed local copy from an unverified terminal clipboard request. | Adapter and 16-variant actual-terminal visual/readback/persistence matrix pass; complete-candidate gate pending |\n| `/share` | Publication: review destination, visibility, and content before external submission. | P0 / next |\n| `/browser` | Cancel, headless, visible, and typed paths share a saved-default and effective-state review. Status and no-op are read-only; save precedes optional reset, and retry repeats only unresolved work. | Focused tests and the 16-variant terminal matrix pass. |\n| `/chrome` | Status probes the selected loopback endpoint. Relaunch review identifies endpoint, executable, profiles, authentication uncertainty, and restart impact; stale targets renew review and failures remain unresolved. | Focused tests and the 16-variant terminal matrix pass. |\n| `/copy` | Typed and selector copies share Cancel-first review, fresh source resolution, and delivery feedback. Framed search preserves identity and parent context while history loading and details paging remain explicit. | Focused tests and the 16-variant terminal matrix pass. |\n| `/open` | External opener: identify selected artifact and recovery when no suitable opener exists. | P2 / next |\n| `/remote` | Read-only native remote-host status: report relay reachability and the current live terminal-session count without changing runtime state. | Focused remote-control tests pass; full terminal UAT pending. |\n| `/session` | Info/delete: retain target identity through cancellation and show the actual deletion outcome. | P0 / next |\n| `/jobs` | Current-session queued/running/completed/failed work uses the bounded report frame, with distinct unavailable and empty states, overflow-only paging, Escape closure, and Ctrl+C kept separate from Back. | Focused state regressions and a directly judged 16-variant actual-terminal empty-state matrix pass; complete-candidate job integration remains pending |\n| `/usage` | Non-cancellable provider refresh rejects duplicates, retains cached data after failure, distinguishes empty/unavailable/error states, and renders complete account identities in responsive one/two-column layouts. | Focused lifecycle regressions and a directly judged 16-variant local-provider/unchanged-credential matrix pass; complete-candidate gate pending |\n| `/changelog` | Recent and explicit `full` reports use responsive Markdown in the bounded pager; unrelated arguments fail, long content remains complete, and paging narration appears only during overflow. | Focused paging/parser regressions and a directly judged 16-variant actual-terminal recent/full/invalid matrix pass; complete-candidate gate pending |\n| `/hotkeys` | The intentional instructional exception now uses the shared bounded pager, reports configured/disabled bindings, groups controls by context, and only shows paging controls on overflow. | Focused binding regressions and a directly judged 16-variant first/final-page matrix pass; complete-candidate gate pending |\n| `/tools` | The active-model tool inventory uses bounded responsive Markdown and paging while keeping availability, enabled state, provenance, and configuration requirements explicit. | Focused tests and the 16-variant terminal matrix pass. |\n| `/extensions` | Split inventory/inspector: Ctrl+C no longer closes; next, shared search without j/k/space collisions, inspect-before-toggle, stable tabs, and single-column details. | P1 / partial |\n| `/agents` | Dashboard: redundant arrow hint removed; next, replace letter shortcuts that collide with search and label persistent actions. | P1 / partial |\n| `/branch` | Tree or message selector: explain branch destination and distinguish navigation from creating a fork. | P1 / next |\n| `/fork` | Session mutation: identify source and new session, preserving a clear route back. | P1 / next |\n| `/tree` | Tree navigation: Ctrl+C no longer closes; next, show page controls only for overflow and preserve node identity. | P1 / partial |\n| `/login` | Configured providers and the full catalog use framed identity-qualified search with retained parent context. Typed and menu setup share masked Cancel-first review and distinguish saved configuration, authentication, validation, and catalog readiness. | Focused tests and the 16-variant terminal matrix pass. |\n| `/logout` | Stored-credential removal names provider and credential-store scope, masks the old value, starts on Cancel and refreshes only after deletion. A failed refresh warns without denying completed removal; empty storage is explicit. | Focused review/outcome tests and a directly judged 16-variant actual-terminal database-reopen matrix pass; complete-candidate gate pending |\n| `/mcp` | Add/list/authentication/configuration/resource commands: wizard hints simplified; next, consistent server identity, retry, connection state, and removal review. | P0 / partial |\n| `/ssh` | Connection add/list/remove: scope-qualified identity, removal review, and clear distinction between saved configuration and a tested connection. | P0 / next |\n| `/media` | Play/pause/stop: identify the media target and report unsupported or unavailable playback. | P2 / next |\n| `/new` | Cancel-first review identifies old session, destination, queued prompts and interruption consequences. UI resets only after confirmed persistence; veto preserves view; in-dialog partial-save retry retains the created identity. | P1 / full UAT pending |\n| `/compact` | Default and typed instructions share a stale-checked session review. Escape navigates and Ctrl+C requests interruption; completed output survives persistence failure for save-only retry. Too-small and unchanged requests do not write. | Focused tests and the 16-variant terminal matrix pass. |\n| `/handoff` | Context transfer: preview destination and report what was transferred or omitted. | P1 / next |\n| `/resume` | Session picker: Ctrl+C no longer exits; retain deletion hint; next, contextual search-clear and stable selected identity. | P1 / partial |\n| `/btw` | Side question: make its separation from the main conversation and completion state visible. | P2 / next |\n| `/background` | Transfer running work without review: identify stable session/work, state non-cancellation, stop UI activity, and detach streams before suspension. `bg` continues, `fg` waits, reopen returns, and `/jobs` inspects work. | Focused tests and the 16-variant terminal matrix pass. |\n| `/debug` | Diagnostic selector: concise choices and safe export boundaries; shared cancel default applies. | P2 / partial |\n| `/memory` | Read-only view is pageable and distinguishes populated, empty, and unavailable states. Clear/reset and enqueue/rebuild use stale-checked reviews with exact project/database scope and report persisted requests rather than worker completion. | Focused tests and the 16-variant terminal matrix pass. |\n| `/rename` | Prefilled editor when omitted; typed/editor names share cancel-first review, session identity revalidation, unchanged no-write, persistence-before-success and retry tracking. Disposable session cancel/reopen tests pass. | P2 / full UAT pending |\n| `/move` | Required destination: offer destination review, collision feedback, and resulting session location. | P1 / next |\n| `/exit` | Clean sessions exit immediately. Outstanding work opens one session-qualified Cancel-first review; confirmation interrupts supported work, waits for settlement, flushes state, clears transient UI, and returns the shell. | Focused tests and the 16-variant terminal matrix pass. |\n| `/plugin` | Canonical commands and aliases share one framed dashboard. Mutations use exact-version Cancel-first review, fresh catalog/target validation, duplicate and stale guards, explicit partial/offline outcomes, and unresolved-only retry. `--force` is replacement, not consent. | Focused tests and the 16-variant terminal matrix pass. |\n| `/reload-plugins` | Clear capability and plugin-root caches, refresh command/skill/hook/tool/agent/MCP metadata in the current process, reject duplicates, and distinguish completion from restart. | Focused lifecycle tests and a directly judged 16-variant actual-terminal refreshed-command discovery matrix pass; complete-candidate gate pending |\n| `/force` | Argument-free use opens searchable active-tool actions with Cancel first. Typed colon/space syntax remains supported. Feedback describes one forced tool call followed by no tools, queued behind any earlier directives—not immediate execution. No persistent setting is changed; stale session choices, removed tools and duplicate selectors are rejected. | P1 / full UAT pending |\n| `/quit` | Exact alias of the `/exit` review, revalidation, settlement, persistence, and shell-return contract. | Shared focused and actual-terminal evidence passes; complete-candidate gate pending |\n| `/apply` | Resource mutation: review tenant, namespace, target, and diff; separate dry-run from applied results. | P0 / next |\n| `/create` | Resource mutation: identify target and scope, distinguish validation from creation and existing-resource conflicts. | P0 / next |\n| `/delete` | Resource deletion: cancel-first target review, explicit force semantics, and partial-result feedback. | P0 / next |\n| `/describe` | Resource details: scrollable long output, stable identity, and actionable missing-context errors. | P1 / next |\n| `/diff` | Change preview: distinguish no changes from unavailable comparison and prevent preview implying application. | P0 / next |\n| `/get` | Resource inventory: aligned responsive columns, readable empty results, and distinct failure styling. | P1 / next |\n| `/manifest` | Resource export: destination/overwrite review, partial-export warning, and error styling instead of ordinary status. | P0 / next |\n| `/context` | Context list/activation/wizard and configuration subcommands: concise wizard hints applied; next, masked identity, scope, confirmation, and retained validation failures. | P0 / partial |\n| `/route` | Strict paths distinguish saved, project, runtime, and effective policy. Mutations use stale-checked reviews, bounded preparation, exact no-op handling, unresolved-save retry, and unavailable-catalog recovery. | Focused tests and the 16-variant terminal matrix pass. |\n\nAliases share their canonical command's review: `models` → `model`, `status` → `extensions`,\n`bg` → `background`, and `marketplace`/`plugins` → `plugin`. Keep explicit-argument paths efficient:\nthe browse → inspect → act contract applies to menus, not an extra mandatory menu for every typed verb.\n\nThe library is also extensible. `extensibility/slash-commands.ts`, `capability/slash-command.ts`,\nand embedded task templates contribute extension, prompt, skill, and file-based commands. Review\ntheir discovery contract: show source and user/project scope, explain shadowed names, preserve\nargument completion, and distinguish a prompt expansion from an immediately executable action.\nTheir installed contents vary by workspace; do not claim an exhaustive live inventory from the\nbuilt-in registry alone. Apply this checklist when each command is introduced or changed.\n\nThe complete source-derived inventory is verified by focused regressions and current-source terminal\nmatrices. Keep simple text reports simple; enrich them only where inspection, recovery, or\ndecision-making benefits from interaction, and require the same evidence whenever a surface changes.\n",
+	"en/architecture-contribution/tui-style-guide.mdx": "---\ntitle: \"TUI interaction style guide\"\ndescription: \"Build predictable selectors with shared structure, navigation, semantics, and feedback.\"\nsidebar:\n  order: 9\n  label: \"TUI interaction style\"\nhead:\n  - tag: style\n    content: |\n      .sl-markdown-content .expressive-code { max-width: 100%; overflow-x: auto; }\n      .sl-markdown-content table { display: block; max-width: 100%; overflow-x: auto; }\n---\n\nUse this guide for interactive terminal user interface (TUI) selectors and managers. It defines a\nshared interaction contract and adaptable presentation defaults. It does not require unrelated\nscreens to be redesigned in the same change.\n\n## What flow should an interactive manager use?\n\nPrefer one stable, single-column flow:\n\n```text\nbrowse → inspect → choose an explicitly labeled action → see its outcome\n```\n\nGive the frame a clear title. Add a purpose only when the title and choices do not explain the task.\nKeep navigation in a stable position, make the choices searchable, summarize the selected choice\nbriefly, and show contextual keyboard hints.\nPut long descriptions and secondary metadata in a detail view rather than beside the list.\n\nThe `/login` provider list follows this pattern by opening connection management before changing a\nsaved connection. `/model` separates model selection from scope and reasoning choices. `/plugin`\nuses the same pattern for install, update, enable, disable, and removal actions.\n\n## How should a selector look?\n\nUse `selectorFrame` and its adaptive gutters. The shared frame provides rounded Unicode borders,\nan ASCII fallback, joined section dividers, and a maximum width of 100 columns. Keep every rendered\nrow the same width so selection highlighting reaches both inside edges without breaking the border.\n\nUse two spaces between aligned columns. Keep headings subdued and reserve emphasis for selection,\nstate, and outcomes. Color may reinforce meaning, but plain text must carry it:\n\n```text\nPlugin                         Status              Scope\n› source-control               Enabled             project\n  observability                Update 2.1.0        user\n  cloud-tools                  Available           —\n```\n\nAt narrow widths, keep the name in the row and move status, scope, version, and other secondary\ncolumns into the selected summary. Remove optional blank rows before hiding choices, controls, or\nselected information.\n\n## How should input and navigation behave?\n\nTreat familiar terminal conventions as the default interaction vocabulary. Avoid \"captain obvious\"\nindicators: instructions that merely repeat what a recognizable control already communicates.\nMake the layout self-descriptive before adding instructional copy. Removing a hint is appropriate\nonly when the control, its state, and its outcome remain discoverable.\n\nThe following manifest defines the expectations xcsh should consistently support. These are design\ncommitments for this interface, not a claim that every person has identical experience. Preserve\naccessible labels and provide help for unfamiliar or remapped controls.\n\n| Visible situation | Expected human intuition | Interface commitment | Hint policy |\n| --- | --- | --- | --- |\n| A highlighted menu item | Arrows move selection; Enter opens or activates it. | Show one clear selection and make the label predict the result. | Omit `Up/Down: navigate` and `Enter: choose action`. |\n| An item naming a plugin, provider, or other object | Opening it reveals information or choices about that object. | Open details before a management mutation. | Let the object label and detail title explain the transition. |\n| An action naming a verb and target | Activating it performs that named action or opens its clearly labeled review. | Use `Disable plugin`, `Review installation`, or `Remove from project scope`; avoid ambiguous `Select` or `Continue`. | Explain consequences or scope when they affect the decision, not how to press Enter. |\n| A search field | Typing searches; normal editing and paste work. | Keep search visibly associated with its list and preserve editor behavior. | Use a field label; omit `Type to search` when the field already says Search. |\n| A nested menu | Escape returns to the parent. | Return one level and retain the parent's query and selection. | A compact `Esc: back` can clarify the hierarchy; never advertise Ctrl+C as Back. |\n| An active search in a list | Escape clears the search before leaving the list. | Clear the query on the first Escape, then return on the next. | Show `Esc: clear search` only while a query exists. |\n| Section tabs | Changing sections preserves a stable navigation structure. | Keep tab order and selected section visible; use Tab and Shift+Tab consistently here. | A compact section-switching hint is useful because Tab behavior varies between interfaces. |\n| Content longer than the viewport | Navigation reveals the remaining content. | Use available space first; keep selection visible and make all details reachable. | Show paging controls only during overflow, especially when arrows move actions instead of details. |\n| A destructive confirmation | Cancel is safe; the destructive choice names the effect. | Select Cancel initially and show the exact target and scope. | Keep consequence text; omit instructions to select a choice. |\n| An operation underway | Work is proceeding, and another activation should not duplicate it. | Show progress, prevent duplicate submission, and report whether interruption is supported. | Reserve Ctrl+C for interruption; never imply cancellation unless work actually stopped. |\n| An operation completes or fails | The state reflects the outcome and recovery is apparent. | Update the affected item; keep failure context and a usable retry path. | Report the result and any remaining work, not `Action selected` or `Press Enter to continue`. |\n\nUse the shared `Input` component for search. Forward ordinary input to it so spaces, Unicode,\nbracketed paste, cursor movement, deletion, undo, and configured editor bindings work together.\nDo not reserve printable letters as hidden actions while search is active.\n\n- Typing edits the active search; Up and Down move through the filtered choices.\n- Enter inspects a choice, or activates the action whose label is visibly selected.\n- Escape returns one level. In a list it clears an active search before closing the selector.\n- Ctrl+C is reserved for interruption; it must not act as Back or close a menu.\n\nFirst-party extension select/input dialogs use the shared frame and editable input. Selection search\naccepts printable letters; Tab/Shift+Tab changes supplied sections while arrows edit search. Escape\nclears search before closing. Selection timeout closes without activating an option; explicit caller\ntimeout policies remain separate. Confirmation starts on No, and plan approval starts on Stay in plan\nmode. Callback signatures and return types are unchanged.\n\nChoosing `Approve and execute` is an action request, not final consent. Follow it with one Cancel-first\nreview that names the planning session, new execution-session destination, draft and finalized plan\npaths, restored tool scope, prompt submission, and execution consequences. Revalidate plan bytes,\nsession identity, and destination before committing. Extension veto happens before old-session mutation;\npartial session persistence retries the same identity. Do not open a nested `/new` review or continue\nexecution when any approval review is cancelled.\n\nA typed `/plan <prompt>` uses the same review and lifecycle adapters. When planning is already active,\nreview the prompt without toggling or pausing the mode; persist outstanding session state before\nqueueing it, then distinguish queued/model-pending from completion. If an enable save is unresolved,\nshow prompt replacement as old→new. If a pause save is unresolved, review the combined recovery,\npersist the pause, re-enable and persist plan mode, and only then queue the prompt. Never silently drop\nan argument because a prior mode transition is awaiting persistence.\n\nThe application and standalone editor now default `app.interrupt` to Ctrl+C. Idle Ctrl+C retains\ndraft clearing, while double-Escape navigation remains separate from execution. Existing explicit\ninterrupt remaps (including disabled bindings) are respected; there is no configuration migration.\nActive-work hints must display the configured key, not hardcode Escape. Cooperative actions receive\nan abort signal, but an interrupt request alone does not establish cancellation: keep the operation\nvisible until it acknowledges interruption or completes. Normal completion after an interrupt request\nis still success. Unaccounted-for partial failures remain unresolved rather than being labelled cancelled.\n\n- Tab and Shift+Tab move through stable categories when a manager has categories.\n- Page Up and Page Down make long detail content reachable.\n\nHints should explain non-obvious controls, not narrate familiar interaction. Omit `Enter: choose\naction`, `Up/Down: navigate`, and purpose text such as `Browse, inspect, choose an action, and review\nits outcome`. Keep compact hints for section switching, refresh or retry, and the Escape hierarchy.\nShow a paging hint only when content actually exceeds the available space; use the terminal's\navailable height before introducing scrolling. A short detail view needs no scroll instructions.\n\nDocument an exception beside the component when its task genuinely requires different behavior.\nRemapped selector bindings must continue to work; do not hardcode only one escape sequence.\n\nReview each proposed hint against three questions: does it reveal a control that is otherwise\nundiscoverable, explain an exception to these conventions, or clarify a consequence or recovery\nstep? If none applies, remove it. If a conventional interaction needs a paragraph of instructions,\nfirst repair the label, grouping, focus, or navigation behavior. Do not use explanatory copy to\ncompensate for an inconsistent menu.\n\n## How do question-and-answer flows work?\n\nBlocking and asynchronous questions use the same framed, theme-aware presentation as other\nfirst-party selectors. Show one question at a time with its position and unanswered count. The\nhighlight spans the full choice row, while checkbox state distinguishes a highlighted draft from a\ncommitted answer without relying on color. Numbered shortcuts submit their matching choice. Omit a\ndescription row when the option has no description.\n\nKeep notes and free-text answers inside the question frame. Secret input is masked by grapheme in\nevery render, including resize, and the visible transcript must never disclose the secret. Preserve\nthe current question and draft when the terminal resizes. Keep the highlighted choice visible when\nheight is constrained and show scrolling guidance only when content actually overflows.\n\nUnanswered confirmation uses the same frame and keeps `Proceed` as the existing default. Escape\nreturns to the first unanswered question. Hints are contextual and derived from the active selector\nand interrupt bindings; hardcoded hints are limited to controls that are not configurable.\n\nAsynchronous announcements are compact question summaries with a visible `/questions` action.\nCompleted replies remain the exact structured `user_input_reply` payload in model context and\nsession persistence, but the terminal correlates that payload with the preceding question item and\nrenders a friendly answer summary. Correlation IDs and transport envelopes are never visible. A\nmessage that does not correlate to an existing async question is rendered normally rather than\nbeing mistaken for an internal reply.\n\nRead the screen without its keyboard footer. Its title should identify the current task or object;\nhighlighting should identify the active choice; action labels should identify what happens next;\ngrouping should distinguish navigation, actions, facts, and outcomes. Use the same words and order\nfor the same concepts across screens. Keep the affected object identifiable after an operation,\nand explain a change of section when an item moves out of the current list.\n\n## Which states must the copy distinguish?\n\nAvailability, installation, enabled state, scope, and update availability are separate facts. Use\nspecific phrases such as `Available`, `Installed · Disabled`, `project scope`, and\n`Update 2.1.0`. Avoid unexplained symbols and avoid treating an item that exists in a catalog as an\ninstalled or enabled item.\n\nFeedback also needs distinct language and styling:\n\n| State | Copy pattern | Required next step |\n| --- | --- | --- |\n| Loading | `Refreshing plugin catalogs…` | Keep navigation and cached data visible. |\n| Progress | `Installation in progress…` | Prevent duplicate submission. |\n| Success | `Installation completed.` | Show the updated state. |\n| Warning | `Installed 2 of 3 plugins. 1 failed.` | Name remaining work. |\n| Failure | `Refresh failed: catalog unavailable.` | Offer Retry and retain context. |\n| Empty | `No plugins match “trace”.` | Explain how to clear or broaden the search. |\n\nClosing a view does not mean an asynchronous operation was cancelled. Ignore stale completions from\nsuperseded refreshes, keep retry context after failure, and describe continuing work accurately.\n\nDialog creation and teardown are part of this lifecycle contract. A synchronous factory exception,\nrejected asynchronous factory, or failed presentation must settle the caller with an error and\nrelease duplicate-operation guards. Do not replace the draft before a component is ready. Attempt\nremaining cleanup even if one disposal step fails, and report that failure rather than leaving a\nhidden command pending. These internal safeguards must preserve extension callback signatures.\n\n## How do confirmation and review screens work?\n\nEnter from a browse list opens details; it must not install, remove, or toggle the selected item.\nDetails list only actions backed by a persistent manager operation.\n\nInstallation review identifies the source, destination scope, and declared prerequisites before an\ninstall action is available. Removal confirmation starts on `Cancel removal`, not on the destructive\nchoice. A bulk action is a visible row such as `Review recommended setup…`; its review lists every\naffected plugin, the destination scope, prerequisite commands, and partial failures.\n\nClipboard reviews identify the source and replacement effect without reading existing clipboard data.\nExplain that clipboard-history services may retain the text. Wait for the backing copy operation;\nan OSC 52 terminal request has no delivery acknowledgement and must be described as unverified,\nnot as a confirmed copy. On Linux without a clipboard manager, clipboard text may disappear when\nxcsh exits. `/dump`, typed `/copy` subcommands and transcript-selector picks share this review\nand feedback adapter. Other clipboard surfaces must adopt it before candidate acceptance.\n\n## What should reviewers check?\n\nThe repository-wide readability contract is recorded in\n`packages/coding-agent/tui-readability-ledger.json`. Each known use of `selectorFrame`,\n`selectorRow`, `SelectList`, `TruncatedText`, or `truncateToWidth` is bound to a presentation policy\nand captured in generated source evidence. Run `bun run audit:tui-readability` from\n`packages/coding-agent` to verify it, or `bun run audit:tui-readability:write` after intentionally\nclassifying a changed sink.\n\nUse `wrap` for prompts, instructions, descriptions, errors, statuses, and other prose. Reserve\n`intentionally-compact` for terminal chrome, code, and intrinsically compact labels. Use\n`truncate-with-full-detail` for dense identifiers or table cells only when selecting the row exposes\nthe complete value in a wrapped detail view. An unresolved exception must remain a\n`finding-open` ledger entry linked to a child issue; it is not evidence that the surface meets the\ncontract.\n\n- The title, purpose, choices, selected summary, and controls remain understandable without color.\n- With keyboard hints hidden, the task, selection, action consequences, and current state are clear.\n- Every remaining hint reveals a non-obvious control, an exception, a consequence, or recovery;\n  none merely narrates Enter, arrows, selection, or an already labeled search field.\n- The intuition manifest holds across parent and child menus: consistent labels, stable focus,\n  Escape hierarchy, retained context, and feedback tied to the affected object.\n- Scrolling hints disappear when content fits; Ctrl+C never substitutes for Back.\n- The frame is continuous in Unicode and ASCII, each row has equal width, and highlighting stays\n  inside both borders.\n- Width never exceeds 100 columns; 60×20 still keeps the selected choice and recovery controls.\n- Search handles spaces, Unicode, paste, cursor edits, and no-match results.\n- Enter opens details before mutation; destructive confirmation starts on Cancel.\n- Selection uses the full stable identity, including source, identifier, and scope.\n- Empty, loading, progress, success, warning, failure, retry, and partial failure are\n  distinguishable.\n- Refresh and resize retain tab, query, selection, and available data.\n- Duplicate operations and stale asynchronous updates cannot produce a second or misleading outcome.\n- Long details remain reachable and exceptions to the shared contract are documented.\n\n## Where should the guide be adopted next?\n\nUse focused improvement passes rather than a repository-wide redesign:\n\n1. Keep `/login`, `/model`, and `/plugin` as the reference implementations and regression baseline.\n2. Move settings and extension management to the shared frame and escape hierarchy.\n3. Align session, tree, and agent dashboards where they contain inspectable choices and actions.\n4. Review one-off confirmation and input dialogs for explicit labels, outcome feedback, and narrow\n   terminal behavior.\n5. Document intentional exceptions after usability evidence shows the shared contract is unsuitable.\n\n## What did the slash-command library review identify?\n\nThis inventory covers every built-in entry in `src/slash-commands/builtin-registry.ts`, its\nregistered subcommands, and the extension-command discovery surfaces. The coverage regression\nrequires new built-ins to receive an entry here. It is a source review, not a claim that every\ncommand has received live visual acceptance. Do not exercise cloud mutations, credential removal,\npublication, or session deletion merely to review presentation; use isolated fixtures.\n\nPriorities: P0 protects consequential actions and truthful outcomes; P1 improves everyday navigation;\nP2 improves discovery and presentation. “Next” means proposed work, not completed adoption.\n\n| Command | Surface and enhancement opportunity | Priority / adoption |\n| --- | --- | --- |\n| `/settings` | Tabbed settings and nested editors: shared Escape default and concise hints applied; next, shared frame, retained submenu context, and saved-value feedback. | P1 / partial |\n| `/questions` | Opens pending asynchronous questions through the shared session interaction owner; announcements, framed answers, automatic handoff, and correlated transcript summaries share the question presentation. | Focused protocol, interaction, renderer, privacy, and 16-variant terminal tests pass. |\n| `/plan` | Enable, pause, typed prompts, and approval use session-qualified Cancel-first review, fresh plan and destination validation, veto-before-mutation, same-identity save retry, and truthful queued or completed outcomes. | Focused tests and the 16-variant terminal matrix pass. |\n| `/model` | Browse with stable tabs, editable search, exact identity, explicit scope, and reasoning steps. Mutations use Cancel-first review, fresh catalog resolution, persistence-before-success, and exact no-op handling; `/models` shares this path. | Focused tests and the 16-variant terminal matrix pass. |\n| `/fast` | Offer Cancel, Enable, and Disable. Typed `on`, `off`, and `toggle` use the same session-scoped review; `status` is read-only. Persist before success; cancellation, status, and unchanged requests do not write. | Focused tests and the 16-variant terminal matrix pass. |\n| `/export` | Transcript export: show destination, format, overwrite implications, and an actionable failure. | P1 / next |\n| `/dump` | Cancel-first conversation-to-clipboard review; session/content revalidation; awaited delivery, duplicate rejection, unresolved retry. Distinguish completed local copy from an unverified terminal clipboard request. | Adapter and 16-variant actual-terminal visual/readback/persistence matrix pass; complete-candidate gate pending |\n| `/share` | Publication: review destination, visibility, and content before external submission. | P0 / next |\n| `/browser` | Cancel, headless, visible, and typed paths share a saved-default and effective-state review. Status and no-op are read-only; save precedes optional reset, and retry repeats only unresolved work. | Focused tests and the 16-variant terminal matrix pass. |\n| `/chrome` | Status probes the selected loopback endpoint. Relaunch review identifies endpoint, executable, profiles, authentication uncertainty, and restart impact; stale targets renew review and failures remain unresolved. | Focused tests and the 16-variant terminal matrix pass. |\n| `/copy` | Typed and selector copies share Cancel-first review, fresh source resolution, and delivery feedback. Framed search preserves identity and parent context while history loading and details paging remain explicit. | Focused tests and the 16-variant terminal matrix pass. |\n| `/open` | External opener: identify selected artifact and recovery when no suitable opener exists. | P2 / next |\n| `/remote` | Read-only native remote-host status: report relay reachability and the current live terminal-session count without changing runtime state. | Focused remote-control tests pass; full terminal UAT pending. |\n| `/session` | Info/delete: retain target identity through cancellation and show the actual deletion outcome. | P0 / next |\n| `/jobs` | Current-session queued/running/completed/failed work uses the bounded report frame, with distinct unavailable and empty states, overflow-only paging, Escape closure, and Ctrl+C kept separate from Back. | Focused state regressions and a directly judged 16-variant actual-terminal empty-state matrix pass; complete-candidate job integration remains pending |\n| `/usage` | Non-cancellable provider refresh rejects duplicates, retains cached data after failure, distinguishes empty/unavailable/error states, and renders complete account identities in responsive one/two-column layouts. | Focused lifecycle regressions and a directly judged 16-variant local-provider/unchanged-credential matrix pass; complete-candidate gate pending |\n| `/changelog` | Recent and explicit `full` reports use responsive Markdown in the bounded pager; unrelated arguments fail, long content remains complete, and paging narration appears only during overflow. | Focused paging/parser regressions and a directly judged 16-variant actual-terminal recent/full/invalid matrix pass; complete-candidate gate pending |\n| `/hotkeys` | The intentional instructional exception now uses the shared bounded pager, reports configured/disabled bindings, groups controls by context, and only shows paging controls on overflow. | Focused binding regressions and a directly judged 16-variant first/final-page matrix pass; complete-candidate gate pending |\n| `/tools` | The active-model tool inventory uses bounded responsive Markdown and paging while keeping availability, enabled state, provenance, and configuration requirements explicit. | Focused tests and the 16-variant terminal matrix pass. |\n| `/extensions` | Split inventory/inspector: Ctrl+C no longer closes; next, shared search without j/k/space collisions, inspect-before-toggle, stable tabs, and single-column details. | P1 / partial |\n| `/agents` | Dashboard: redundant arrow hint removed; next, replace letter shortcuts that collide with search and label persistent actions. | P1 / partial |\n| `/branch` | Tree or message selector: explain branch destination and distinguish navigation from creating a fork. | P1 / next |\n| `/fork` | Session mutation: identify source and new session, preserving a clear route back. | P1 / next |\n| `/tree` | Tree navigation: Ctrl+C no longer closes; next, show page controls only for overflow and preserve node identity. | P1 / partial |\n| `/login` | Configured providers and the full catalog use framed identity-qualified search with retained parent context. Typed and menu setup share masked Cancel-first review and distinguish saved configuration, authentication, validation, and catalog readiness. | Focused tests and the 16-variant terminal matrix pass. |\n| `/logout` | Stored-credential removal names provider and credential-store scope, masks the old value, starts on Cancel and refreshes only after deletion. A failed refresh warns without denying completed removal; empty storage is explicit. | Focused review/outcome tests and a directly judged 16-variant actual-terminal database-reopen matrix pass; complete-candidate gate pending |\n| `/mcp` | Add/list/authentication/configuration/resource commands: wizard hints simplified; next, consistent server identity, retry, connection state, and removal review. | P0 / partial |\n| `/ssh` | Connection add/list/remove: scope-qualified identity, removal review, and clear distinction between saved configuration and a tested connection. | P0 / next |\n| `/media` | Play/pause/stop: identify the media target and report unsupported or unavailable playback. | P2 / next |\n| `/new` | Cancel-first review identifies old session, destination, queued prompts and interruption consequences. UI resets only after confirmed persistence; veto preserves view; in-dialog partial-save retry retains the created identity. | P1 / full UAT pending |\n| `/compact` | Default and typed instructions share a stale-checked session review. Escape navigates and Ctrl+C requests interruption; completed output survives persistence failure for save-only retry. Too-small and unchanged requests do not write. | Focused tests and the 16-variant terminal matrix pass. |\n| `/handoff` | Context transfer: preview destination and report what was transferred or omitted. | P1 / next |\n| `/resume` | Session picker: Ctrl+C no longer exits; retain deletion hint; next, contextual search-clear and stable selected identity. | P1 / partial |\n| `/btw` | Side question: make its separation from the main conversation and completion state visible. | P2 / next |\n| `/background` | Transfer running work without review: identify stable session/work, state non-cancellation, stop UI activity, and detach streams before suspension. `bg` continues, `fg` waits, reopen returns, and `/jobs` inspects work. | Focused tests and the 16-variant terminal matrix pass. |\n| `/debug` | Diagnostic selector: concise choices and safe export boundaries; shared cancel default applies. | P2 / partial |\n| `/memory` | Read-only view is pageable and distinguishes populated, empty, and unavailable states. Clear/reset and enqueue/rebuild use stale-checked reviews with exact project/database scope and report persisted requests rather than worker completion. | Focused tests and the 16-variant terminal matrix pass. |\n| `/rename` | Prefilled editor when omitted; typed/editor names share cancel-first review, session identity revalidation, unchanged no-write, persistence-before-success and retry tracking. Disposable session cancel/reopen tests pass. | P2 / full UAT pending |\n| `/move` | Required destination: offer destination review, collision feedback, and resulting session location. | P1 / next |\n| `/exit` | Clean sessions exit immediately. Outstanding work opens one session-qualified Cancel-first review; confirmation interrupts supported work, waits for settlement, flushes state, clears transient UI, and returns the shell. | Focused tests and the 16-variant terminal matrix pass. |\n| `/plugin` | Canonical commands and aliases share one framed dashboard. Mutations use exact-version Cancel-first review, fresh catalog/target validation, duplicate and stale guards, explicit partial/offline outcomes, and unresolved-only retry. `--force` is replacement, not consent. | Focused tests and the 16-variant terminal matrix pass. |\n| `/reload-plugins` | Clear capability and plugin-root caches, refresh command/skill/hook/tool/agent/MCP metadata in the current process, reject duplicates, and distinguish completion from restart. | Focused lifecycle tests and a directly judged 16-variant actual-terminal refreshed-command discovery matrix pass; complete-candidate gate pending |\n| `/force` | Argument-free use opens searchable active-tool actions with Cancel first. Typed colon/space syntax remains supported. Feedback describes one forced tool call followed by no tools, queued behind any earlier directives—not immediate execution. No persistent setting is changed; stale session choices, removed tools and duplicate selectors are rejected. | P1 / full UAT pending |\n| `/quit` | Exact alias of the `/exit` review, revalidation, settlement, persistence, and shell-return contract. | Shared focused and actual-terminal evidence passes; complete-candidate gate pending |\n| `/apply` | Resource mutation: review tenant, namespace, target, and diff; separate dry-run from applied results. | P0 / next |\n| `/create` | Resource mutation: identify target and scope, distinguish validation from creation and existing-resource conflicts. | P0 / next |\n| `/delete` | Resource deletion: cancel-first target review, explicit force semantics, and partial-result feedback. | P0 / next |\n| `/describe` | Resource details: scrollable long output, stable identity, and actionable missing-context errors. | P1 / next |\n| `/diff` | Change preview: distinguish no changes from unavailable comparison and prevent preview implying application. | P0 / next |\n| `/get` | Resource inventory: aligned responsive columns, readable empty results, and distinct failure styling. | P1 / next |\n| `/manifest` | Resource export: destination/overwrite review, partial-export warning, and error styling instead of ordinary status. | P0 / next |\n| `/context` | Context list/activation/wizard and configuration subcommands: concise wizard hints applied; next, masked identity, scope, confirmation, and retained validation failures. | P0 / partial |\n| `/route` | Strict paths distinguish saved, project, runtime, and effective policy. Mutations use stale-checked reviews, bounded preparation, exact no-op handling, unresolved-save retry, and unavailable-catalog recovery. | Focused tests and the 16-variant terminal matrix pass. |\n\nAliases share their canonical command's review: `models` → `model`, `status` → `extensions`,\n`bg` → `background`, and `marketplace`/`plugins` → `plugin`. Keep explicit-argument paths efficient:\nthe browse → inspect → act contract applies to menus, not an extra mandatory menu for every typed verb.\n\nThe library is also extensible. `extensibility/slash-commands.ts`, `capability/slash-command.ts`,\nand embedded task templates contribute extension, prompt, skill, and file-based commands. Review\ntheir discovery contract: show source and user/project scope, explain shadowed names, preserve\nargument completion, and distinguish a prompt expansion from an immediately executable action.\nTheir installed contents vary by workspace; do not claim an exhaustive live inventory from the\nbuilt-in registry alone. Apply this checklist when each command is introduced or changed.\n\nThe complete source-derived inventory is verified by focused regressions and current-source terminal\nmatrices. Keep simple text reports simple; enrich them only where inspection, recovery, or\ndecision-making benefits from interaction, and require the same evidence whenever a surface changes.\n",
 	"en/architecture-contribution/upstream-pi.mdx": "---\ntitle: \"Relationship to pi\"\ndescription: \"Understand what xcsh inherits from pi and where the project deliberately specializes.\"\nsidebar:\n  order: 9\n  label: \"Relationship to pi\"\n---\n\nxcsh is derived from the open-source pi coding agent and adds F5 Distributed Cloud resource workflows, integrations, packaging, and project-specific governance.\n\n## Which upstream range was reviewed?\n\nThe last proven sync with `can1357/oh-my-pi` was `d350ea60e` on April 9, 2026. The first-pass\nsecurity and shared-runtime audit reviewed the divergent line through `b2f25dbfe1` on September 5,\n2026. The second-pass TUI and renderer audit extends that lineage through the frozen tip\n`6d3bc569d16cd7351073eaa767caed51021befbb` on September 6, 2026.\nThe third-pass terminal-interaction audit extends the reviewed lineage through\n`a1b254047d12e143b7c6011536e918c6c35c5906`, also frozen on September 6, 2026.\nThe fourth-pass hyperlink, login-launch, and transcript-copy audit extends the reviewed lineage\nthrough `6e48b5ce564aa1d7eff60ffe92748f451385ad7d`, frozen on September 7, 2026.\nBecause the repositories no longer share a usable linear history, accepted changes are semantic\nports with adapted regressions rather than merges or ancestry-based cherry-picks.\n\n## Which changes were accepted?\n\nThe four implementation waves accepted these upstream pull requests:\n\n| Wave | Upstream pull requests | xcsh delivery |\n| --- | --- | --- |\n| Provider and prompt security | #2147, the opaque-thinking portion of #3239, #7067, and #8727 | #3710 |\n| Configuration and execution security | #7362 and #5636 | #3720 |\n| Core runtime | #7743, #10415, #10523, #10325, and #10550 | #3723 |\n| Terminal and platform | #10613, #10997, #10492, #9233, and #7634 | #3724 |\n| TUI and renderer crash containment | #1989, #4497, #4529, #2047, #5837, and #6788 | #3743 |\n| Herdr, signals, and mouse interaction | #7810, #8433, #11054, #4121, #3463, #3402, and #11045 | #3748 |\n| Hyperlinks, login launch, and copy picker | #10196, #10606, #11002, #10922, #11086, #5887, and #6282 | #3758 |\n\nThese ports protect provider-bound secrets and compaction boundaries, enforce exact-case\nenvironment references and complete protocol tails, repair Responses replay and shared MCP\nresults, improve rate-limit and retained-string behavior, chain directory completion, extend\npower assertions across supported platforms, and harden stats persistence and network exposure.\nThe source pull requests remain attributable to `can1357/oh-my-pi`; the xcsh deliveries link the\nexact commits and regression evidence.\n\nThe second-pass renderer work normalizes malformed task result data, accepts only strings at path\nboundaries, bounds ANSI-heavy rows before width measurement, and treats terminal disconnect\ncleanup as best effort before SIGHUP. Upstream #5438 is equivalent because `Container.render()`\nalready isolates child-render exceptions; its richer fallback display remains deferred.\n\nThe third-pass work adds a shared fullscreen/mouse framework, applies it to the session picker,\nextension dashboard, and debug-log viewer, and keeps terminal state restoration idempotent across\nnormal exit, resize, disconnect, and emergency cleanup. Herdr pane identity now participates in\nmultiplexer redraw decisions, while notifications use validated argv-only `herdr notification show`\ndelivery with terminal fallback. Interactive and signal exits share one draft-preserving teardown,\nand POSIX Ctrl-Z suspends only the xcsh process with `SIGSTOP`.\n\nThe fourth-pass work applies an immutable startup capability snapshot to `off`, `auto`, and\n`always` hyperlink policy; safely renders and physically wraps OSC 8 spans; launches local Vertex\nlogin through an HTTP(S)-only opener while retaining manual recovery; and projects the bounded copy\npicker directly from xcsh `SessionMessageEntry` history. The semantic ports correspond to upstream\nmerge commits `db2f55888b9f500b51010d7958a9cc8712e19f5c`,\n`4d13034f5dc70e93a6dad502ea7313792480760e`,\n`72767b81bd2911ebd650cfd0fdd5f92afc7470a6`,\n`4a56732e45c6b13b01e72aeaab113d0a257df0bd`,\n`43a2913d1ee2e88ceff0851a9ed9d0345f12d8c6`,\n`c081dedd3a696c872fd818f89d2b8c6c81a45b1e`, and\n`d1979782e7851b46451e956a5855d69e7781a5f5`.\n\n| Third-pass candidate | Disposition |\n| --- | --- |\n| Herdr #7810, #8433, and #11054 | Ported: scrollback-safe rendering, resize behavior, and notification delivery |\n| Herdr #10356 and #10479 | Equivalent: explicit `HERDR_KITTY_GRAPHICS` gating and synchronized rendering already cover the behavior |\n| Herdr #7554 | Not applicable: xcsh uses its compiled executable and dedicated launcher |\n| Signal #4121 (`73a12c7e`) | Ported: shared idempotent teardown and one-shot draft recovery |\n| Signal #3463 (`8506fbdf`) | Ported: interactive self-`SIGSTOP`; deliberate background process-group `SIGTSTP` remains unchanged |\n| Mouse #3402 and #11045 | Ported: shared SGR parsing/routing and horizontal-wheel rejection |\n| `cffb804d`, `27ed9f7a`, and log-viewer portion of `5fbe8876` | Ported to the session picker, extension dashboard, and debug-log viewer |\n| `7eca774c` and raw-SSE portion of `5fbe8876` | Not applicable: those surfaces do not exist in xcsh |\n| Plan Review `2976847e` | Deferred: xcsh retains its compact plan-review selector |\n| MCP, OpenCode, and unrelated renderer/UI changes | Excluded from this pass |\n\n## Where does xcsh deliberately diverge?\n\nxcsh retains its own:\n\n- F5-scoped packages, prompts-as-files, tool factories, and capability discovery;\n- SQLite multi-credential storage, multi-account authentication, and provider routing;\n- MCP, SSH, F5 Distributed Cloud, Office, and browser integrations;\n- Bun-first runtime, session semantics, release pipeline, branding, and governance.\n\nPublic interfaces use prerelease clean breaks. In this wave,\n`MacOSPowerAssertion`/`MacOSPowerAssertionOptions` became\n`PowerAssertion`/`PowerAssertionOptions` without aliases, and `power.sleepPrevention` was added with\nan `idle` default.\n\n## What remains excluded or deferred?\n\nUpstream workflows, branding, release machinery, generated model catalogs, compatibility shims,\nnew packages, and large unrelated subsystems are excluded. The security-scan subsystem in #7048\nand the native minimizer in #2176 remain deferred. The range-dashboard optimization in #9327 and\nearendil-works/pi-only fullscreen transcript, mouse, clipboard, and renderer subsystems also remain\noutside this campaign. MCP, OpenCode, Herdr, #10625, and #10491 were explicitly excluded from the\nsecond-pass batch; the Herdr work is now covered by the third pass. Commits after the new frozen\nsource tip require a later audit.\n\n## How do I decide where a fix belongs?\n\nTrace the affected module and compare it with the pinned upstream lineage. A generic agent-loop\ndefect may belong upstream; an xcsh resource command, integration, or packaging change belongs\nhere.\n\n## How do I preserve attribution?\n\nKeep upstream license notices and document imported changes. Avoid copying a patch blindly across\ndiverged modules; port the behavior with tests against the current xcsh architecture.\n\nAn upstream commit is evidence of intent, not a patch that is safe to apply unchanged. Freeze the\nreviewed upstream commit, identify the xcsh modules that implement the same contract, port the\nbehavior with a regression test, and record deliberate differences. A candidate remains excluded\nuntil its prerequisites and product fit are reviewed; omission from one batch does not imply\nacceptance or rejection in a later audit.\n",
 	"en/automate-extend/extensions-custom-tools.mdx": "---\ntitle: \"Build extensions and custom tools\"\ndescription: \"Add TypeScript behavior, slash commands, providers, or schema-validated tools.\"\nsidebar:\n  order: 3\n  label: \"Extensions and tools\"\n---\n\nExtensions load TypeScript behavior with `--extension` or `--hook`; project discovery can also load extensions, tools, hooks, commands, and rules under `.xcsh/`.\n\n## How do I test an extension boundary?\n\nLoad one explicit file with `-e <PATH>` and disable discovery with `--no-extensions`. Confirm its registered command or tool, then test shutdown and error handling.\n\n## Where do hooks and rules belong?\n\nHooks observe or alter lifecycle events; rules add durable instructions. Keep each rule narrow and each hook deterministic. Use `--no-rules` to prove whether a rule changes the result.\n\nStart from a temporary extension that registers one uniquely named capability. Launch `xcsh\n--no-extensions -e ./path/to/extension.ts`, invoke that capability, and then exit the session to\nexercise teardown. The extension runs with the xcsh process account and can create the same local or\nremote side effects as its code; review it before loading. Delete the temporary file and repeat\nwithout `-e` to confirm discovery no longer exposes it.\n",
 	"en/automate-extend/headless-protocols.mdx": "---\ntitle: \"Headless modes\"\ndescription: \"Integrate xcsh with scripts through print, JSON, JSON-RPC, agent client protocol, manager, and worker modes.\"\nsidebar:\n  order: 1\n  label: \"Headless modes\"\nhead:\n  - tag: style\n    content: |\n      .sl-markdown-content .expressive-code { max-width: 100%; overflow-x: auto; }\n      .sl-markdown-content table { display: block; max-width: 100%; overflow-x: auto; }\n---\n\nHeadless integrations select `json`, `rpc`, or `acp` with `--mode`: a JavaScript Object Notation (JSON) event stream, JSON remote procedure call (RPC), or the agent client protocol (ACP). Each mode has a different framing contract; consumers must parse that protocol rather than decorated terminal text.\n\n## How do I start with the smallest surface?\n\n```bash\nxcsh --mode json --no-session --no-tools -p \"Return one sentence\"\n```\n\nCapture stdout as protocol data and stderr as diagnostics. Pin the xcsh version in automation and test framing against the exact release.\n\n## How do I retain and resume a JSON-mode session?\n\nUse a dedicated session directory when the JSON stream must survive process loss:\n\n```bash\nxcsh --mode json --session-dir /var/lib/my-controller/xcsh-sessions -p \"Return one sentence\"\n```\n\nThe first stdout line is a `SessionHeader`. Its `id` is a 16-character lowercase hexadecimal xcsh session ID.\nWith `--session-dir`, xcsh atomically writes and fsyncs the matching `<timestamp>_<id>.jsonl` file before\nemitting that header. The header's persisted `cwd`, `id`, and timestamp are the resumable record. Keep the path\ndiscovered in the session directory (or resolve the ID there), then continue through the documented resume argument:\n\n```bash\nxcsh --resume /var/lib/my-controller/xcsh-sessions/<timestamp>_<id>.jsonl \"Continue the task\"\n```\n\n`--no-session` deliberately produces no resumable file or session header. The stream's wire-only `model`, `provider`, and `thinking` fields describe the launch; they are not additional persisted session-header fields.\n\n## When do I use the software development kit (SDK) instead?\n\nUse the SDK when the host process needs in-memory session control, tool registration, or provider events. See [SDK automation](/xcsh/en/automate-extend/sdk/).\n\nChoose the boundary by ownership: JSON is a one-way event transcript, RPC supports a controlling\nclient, ACP integrates an editor or agent host, and the SDK shares a process. Never parse progress\ntext as protocol data. On shutdown, wait for the protocol's terminal event, close the input stream,\nand verify the child exits. Remove the dedicated session directory only when its retained transcript\nis no longer needed.\n",