@f5-sales-demo/xcsh 22.4.2 → 22.4.5

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

@@ -17,17 +17,17 @@ export interface BuildInfo {
 }
 
 export const BUILD_INFO: BuildInfo = {
-	"version": "22.4.2",
-	"commit": "d0215416d1a292f96f3e30d641260730fb2233bd",
-	"shortCommit": "d021541",
+	"version": "22.4.5",
+	"commit": "88cedf5e2812ed04e6ce255c7a109c18f05635b7",
+	"shortCommit": "88cedf5",
 	"branch": "main",
-	"tag": "v22.4.2",
-	"commitDate": "2026-09-29T12:29:41Z",
-	"buildDate": "2026-09-29T13:06:20.087Z",
+	"tag": "v22.4.5",
+	"commitDate": "2026-09-30T00:55:42Z",
+	"buildDate": "2026-09-30T01:34:17.001Z",
 	"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/d0215416d1a292f96f3e30d641260730fb2233bd",
-	"releaseUrl": "https://github.com/f5-sales-demo/xcsh/releases/tag/v22.4.2"
+	"commitUrl": "https://github.com/f5-sales-demo/xcsh/commit/88cedf5e2812ed04e6ce255c7a109c18f05635b7",
+	"releaseUrl": "https://github.com/f5-sales-demo/xcsh/releases/tag/v22.4.5"
 };

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

@@ -40,7 +40,7 @@ export const EMBEDDED_DOCS: Readonly<Record<string, string>> = {
 	"en/getting-started/first-manifest.mdx": "---\ntitle: \"Complete your first manifest lifecycle\"\ndescription: \"Validate, compare, apply, inspect, export, and delete one resource manifest.\"\nsidebar:\n  order: 5\n  label: \"First manifest\"\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\nA manifest names one F5 Distributed Cloud resource with `kind`, `metadata`, and `spec`. Begin from an exported or catalog-backed example for the exact resource kind; do not invent schema fields. This page walks one resource from local validation to proven deletion, so run it against a lab namespace you are authorized to change.\n\n## How do I check a manifest without credentials?\n\n```bash\nxcsh validate -f manifest.yaml --result-file validation.json\n```\n\nValidation reads the file locally and returns a nonzero status for malformed or unsupported input. Review the aggregate JavaScript Object Notation (JSON) report before moving to a live context.\n\n## How do I preview the live change?\n\n```bash\nxcsh diff -f manifest.yaml --result-file diff.json\nxcsh apply -f manifest.yaml --dry-run client --result-file dry-run.json\n```\n\nA diff requires the intended context. A dry run calculates the mutation path without applying it. Read every create, update, and preserve entry before you continue.\n\n## How do I apply and verify the resource?\n\n```bash\nxcsh apply -f manifest.yaml --result-file apply.json\nxcsh get <KIND> <NAME> -n <NAMESPACE> --result-file get.json\n```\n\nCompare the identity and the fields you set in `get.json` against the manifest. A zero exit status records that the request was accepted; only the retrieved object records the resulting state.\n\n## How do I export and remove it?\n\n```bash\nxcsh export <KIND> <NAME> -n <NAMESPACE> -f exported.yaml\nxcsh delete <KIND> <NAME> -n <NAMESPACE> --result-file delete.json\nxcsh get <KIND> <NAME> -n <NAMESPACE>\n```\n\nSanitize server-managed metadata out of `exported.yaml` before you store it. The closing `get` must return the not-found response for that kind; a delete request without the absence check leaves the lifecycle unfinished.\n",
 	"en/getting-started/index.mdx": "---\ntitle: \"Getting started\"\ndescription: \"Install xcsh, connect a model and an F5 Distributed Cloud tenant, and complete a safe first workflow.\"\nsidebar:\n  order: 0\n  label: \"Overview\"\n---\n\nUse this section to reach the first useful command without configuring every optional integration.\n\n## What do I need before I begin?\n\nYou need a supported xcsh build and one model provider. F5 Distributed Cloud credentials are needed only for live resource commands; local manifest validation works without them.\n\n## Which path matches my goal?\n\n1. [Install, update, or remove xcsh](/xcsh/en/#install-xcsh).\n2. [Authenticate a model](/xcsh/en/getting-started/model-authentication/), which the quickstart requires.\n3. Run the [general quickstart](/xcsh/en/#quickstart).\n4. Connect an [F5 Distributed Cloud context](/xcsh/en/f5-distributed-cloud/contexts-namespaces/) when you intend to reach a tenant.\n5. Complete [your first manifest lifecycle](/xcsh/en/getting-started/first-manifest/) against a lab namespace you are authorized to change.\n",
 	"en/getting-started/model-authentication.mdx": "---\ntitle: \"Authenticate a model provider\"\ndescription: \"Configure an API key or supported subscription login without placing credentials in project files.\"\nsidebar:\n  order: 2\n  label: \"Model authentication\"\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\nModel credentials belong in the provider-supported environment or subscription login, not in prompts, settings committed to a repository, or command arguments.\n\n## Which authentication method should I choose?\n\nUse a provider application programming interface (API) key for service-style automation. Use a supported subscription login for an interactive user session. Run `xcsh --list-models <PROVIDER>` after authentication to confirm the credential can enumerate models.\n\n## How do I select a model explicitly?\n\n```bash\nxcsh --model p-openai/gpt-5.2 --no-tools -p \"Summarize README.md\"\n```\n\nReplace the example with a model shown by your installed build. Provider-qualified names avoid an accidental fuzzy match when several providers expose similar model names.\n\nFor Anthropic, either complete `/login anthropic` with a Claude subscription or export\n`ANTHROPIC_API_KEY` for direct API billing. `--model fable` and `--model anthropic/fable` are exact\naliases for `anthropic/claude-fable-5-1`; use `anthropic/claude-fable-5` when you specifically need\nthe earlier Fable 5 model. Fable access depends on the selected account's entitlement.\n\nStart xcsh, enter `/login`, and choose only the provider you intend to use. Complete the\nprovider-owned sign-in flow, return to the model picker, and select an explicit model.\nAuthentication may store a refresh token or subscription session outside the repository; a prompt\nnever needs the credential value. Send a no-tool prompt, inspect the selected provider and model,\nthen use `/logout` when the account must not remain available on that workstation.\n",
-	"en/index.mdx": "---\ntitle: xcsh\ndescription: Install xcsh, authenticate a model provider, and begin a reviewable terminal or F5 Distributed Cloud workflow.\ntemplate: splash\neditUrl: false\nsidebar:\n  hidden: true\n  order: 0\nhead:\n  - tag: style\n    content: |\n      main:has(.landing-hero) > .content-panel:first-of-type { padding-block-end: .5rem; }\n      main:has(.landing-hero) > .content-panel:first-of-type + .content-panel { border-top: 0; padding-block-start: 0; }\n      .landing-hero { display: grid; gap: clamp(2rem, 4vw, 4rem); grid-template-columns: minmax(0, 1fr) minmax(18rem, 35rem); align-items: center; margin-block: .75rem 2rem; }\n      .landing-hero__content, .landing-hero__image, .landing-installer, .landing-installer .expressive-code, .landing-command { min-width: 0; }\n      h1#_top { max-width: 13ch; margin-block-end: 0; text-wrap: balance; }\n      .landing-hero__lede { max-width: 42rem; color: var(--sl-color-gray-2); font-size: var(--sl-text-lg); }\n      .landing-installer { margin-block: 0 4rem; padding: clamp(1rem, 2vw, 1.5rem); border: 1px solid var(--sl-color-gray-5); border-radius: .75rem; background: var(--sl-color-bg-nav); }\n      .landing-installer h2 { margin: 0; font-size: var(--sl-text-lg); }\n      .landing-installer p { margin-block: .5rem 0; }\n      .landing-installer pre { max-width: 100%; overflow-x: auto; }\n      .landing-installer .expressive-code .ec-line .code { padding-inline-end: 3.5rem; white-space: pre; overflow-wrap: normal; }\n      .landing-installer .expressive-code .copy button { opacity: 1; }\n      .landing-hero__image { margin: 0; }\n      .landing-hero__image img { display: block; width: 100%; height: auto; aspect-ratio: 1442 / 1268; object-fit: contain; filter: drop-shadow(0 1rem 2.5rem color-mix(in srgb, var(--sl-color-accent) 28%, transparent)); }\n      .landing-grid { display: grid; gap: 1rem; grid-template-columns: repeat(3, minmax(0, 1fr)); margin-block: 1.5rem; }\n      .landing-explore { grid-template-columns: repeat(2, minmax(0, 1fr)); }\n      details.landing-disclosure { margin-block: 1rem 0; padding: .75rem 1rem; border: 1px solid var(--sl-color-gray-5); border-radius: .5rem; background: var(--sl-color-bg-nav); }\n      details.landing-disclosure summary { cursor: pointer; font-weight: 600; }\n      :is(.landing-hero, .landing-installer, .landing-grid, .landing-disclosure) :is(a, button, summary):focus-visible { outline: 2px solid var(--sl-color-accent-high); outline-offset: 3px; }\n      @media (max-width: 50rem) { .landing-hero { grid-template-columns: minmax(0, 1fr); gap: 2rem; margin-block: .5rem 2rem; } .landing-installer { margin-block-end: 3rem; padding: 1rem; } .landing-grid { grid-template-columns: minmax(0, 1fr); } }\n---\n\nimport { Aside, Card, LinkCard, TabItem, Tabs } from '@astrojs/starlight/components';\n\n<section class=\"landing-hero\" aria-labelledby=\"_top\">\n  <div class=\"landing-hero__content\">\n    <p class=\"landing-hero__lede\">An AI-native terminal assistant for engineering, automation, and reviewable F5 Distributed Cloud workflows.</p>\n    <p>xcsh is an independent open-source project derived from pi/pi-mono, specialized for F5 Distributed Cloud workflows; it is not an F5 product.</p>\n  </div>\n\n  <figure class=\"landing-hero__image\">\n    <img src=\"/xcsh/images/xcsh-ghostty-terminal.png\" width=\"1442\" height=\"1268\" alt=\"xcsh running in a Ghostty terminal with the model selector, prompt, and session status visible.\" />\n  </figure>\n</section>\n\n<section class=\"landing-installer\" aria-labelledby=\"install-xcsh\">\n\n## Install xcsh\n\n  <p>Universal installer for macOS and Linux.</p>\n\n  ```bash\n  curl -fsSL https://raw.githubusercontent.com/f5-sales-demo/xcsh/main/scripts/install.sh | sh\n  ```\n\n  <p>It installs the latest prebuilt release and a schema-v2 provenance receipt into <code>~/.local/bin</code>. The native addon is embedded in the executable, so those are the only two standalone payloads. This is the only channel that <code>xcsh self-update</code> replaces in process. Need a managed or platform-specific channel? Compare the <a href=\"#installation-options\">installation options</a>.</p>\n</section>\n\n## What xcsh helps you do\n\n<div class=\"landing-grid landing-capabilities\">\n  <Card title=\"Agentic terminal work\" icon=\"terminal\">\n    Run interactive or print-mode prompts, inspect files, use tools, and keep durable session history when the task needs it. [Learn the agent loop](/xcsh/en/use-xcsh/agent-loop/).\n  </Card>\n  <Card title=\"Reviewable F5 Distributed Cloud workflows\" icon=\"document\">\n    Discover schemas, validate manifests, and inspect proposed differences before an authorized resource change. [Use resource workflows](/xcsh/en/f5-distributed-cloud/).\n  </Card>\n  <Card title=\"Extensible automation\" icon=\"puzzle\">\n    Add headless workflows, custom tools, skills, or plugins when built-in commands are not enough. [Automate and extend](/xcsh/en/automate-extend/).\n  </Card>\n</div>\nThese workflows start with a working executable; choose another channel only when the universal installer is not the right fit.\n\n## Installation options\n\nUse one channel for install and upgrades. Mixing package-manager and standalone installations can leave more than one `xcsh` on `PATH`; the universal installer above is not repeated here.\n\n<Tabs syncKey=\"install-platform\">\n<TabItem label=\"macOS\" icon=\"seti:apple\">\nInstall the signed and notarized macOS archive through the Homebrew cask. The cask preserves the released executable and native addon byte for byte and does not require `sudo`:\n\n```bash\nbrew install --cask f5-sales-demo/tap/xcsh\n```\n\n<details class=\"landing-disclosure\">\n<summary>Upgrade or remove</summary>\n\nUpgrade with `brew upgrade --cask f5-sales-demo/tap/xcsh`. Remove the cask with `brew uninstall --cask xcsh`. `xcsh self-update` reports the tap-qualified command but never invokes Homebrew. These commands preserve configuration, credentials, and sessions under `~/.xcsh`.\n</details>\n\n<Aside type=\"caution\" title=\"Clean break from the historical package cask\">\nBefore installing this cask on a Mac that received an earlier xcsh package,\nuninstall both old Homebrew entries (`brew uninstall --formula xcsh` and\n`brew uninstall --cask xcsh`). Then have MDM forget the `com.f5.xcsh` receipt\nand remove only the package-owned `/usr/local/bin/xcsh` and\n`/Library/Application Support/xcsh` payload. Do not remove `~/.xcsh`. The signed\nand stapled `.pkg` release assets remain available only for direct MDM\ndeployment.\n</Aside>\n</TabItem>\n\n<TabItem label=\"Ubuntu or Debian\" icon=\"seti:ubuntu\">\nThe signed apt repository supports amd64 and arm64 and follows normal system upgrades:\n\n```bash\nsudo install -d -m 0755 /etc/apt/keyrings\ncurl -fsSL https://f5-sales-demo.github.io/apt-repo/f5xc-archive-keyring.gpg \\\n  | sudo tee /etc/apt/keyrings/f5xc-archive-keyring.gpg >/dev/null\necho \"deb [arch=amd64,arm64 signed-by=/etc/apt/keyrings/f5xc-archive-keyring.gpg] https://f5-sales-demo.github.io/apt-repo stable main\" \\\n  | sudo tee /etc/apt/sources.list.d/f5xc.list\nsudo apt-get update && sudo apt-get install xcsh\n```\n\n<details class=\"landing-disclosure\">\n<summary>Upgrade or remove</summary>\n\nUpgrade with `sudo apt-get update && sudo apt-get install --only-upgrade xcsh`. Remove the package with `sudo apt-get remove xcsh`. `xcsh self-update` reports this command when `dpkg-query` proves that package `xcsh` owns the running executable; it never invokes apt.\n</details>\n</TabItem>\n\n<TabItem label=\"Windows\" icon=\"seti:windows\">\nRun the PowerShell installer, then restart the terminal so its user `PATH` refreshes:\n\n```powershell\nirm https://raw.githubusercontent.com/f5-sales-demo/xcsh/main/scripts/install.ps1 | iex\n```\n\nIt installs `xcsh.exe` and its schema-v2 provenance receipt to `%LOCALAPPDATA%\\\\xcsh`; the native addon is embedded. **Bash is required for tool-backed sessions.** Install Git for Windows, WSL, Cygwin, or MSYS2; set `shellPath` in `%USERPROFILE%\\\\.xcsh\\\\agent\\\\settings.json` when Bash is elsewhere.\n\n<details class=\"landing-disclosure\">\n<summary>Upgrade or remove</summary>\n\nRe-run the installer to upgrade. `xcsh self-update` reports the PowerShell installer command but does not replace a Windows installer-owned executable. To uninstall, remove `%LOCALAPPDATA%\\\\xcsh` and its entry from the user `PATH`.\n</details>\n</TabItem>\n\n<TabItem label=\"Container\" icon=\"seti:docker\">\nDocker and Podman use the same multi-architecture image. Pin a release tag, resolve its digest for deployment, and mount only the workspace and state required by the task:\n\n```bash\ndocker pull ghcr.io/f5-sales-demo/xcsh:vX.Y.Z\ndocker image inspect --format '{{index .RepoDigests 0}}' ghcr.io/f5-sales-demo/xcsh:vX.Y.Z\ndocker run --rm ghcr.io/f5-sales-demo/xcsh@sha256:<digest> --version\n```\n\nPodman accepts the same pull, inspect, and run arguments. Pass provider credentials at runtime through a secret manager or environment file; never bake them into an image layer.\n\n<details class=\"landing-disclosure\">\n<summary>Upgrade or remove</summary>\n\nPull a newer pinned tag to upgrade. Remove an unused image with `docker image rm IMAGE` or `podman image rm IMAGE`.\n</details>\n</TabItem>\n\n<TabItem label=\"Packages and source\" icon=\"seti:config\">\nUse a JavaScript package or a source/ref install when you need a toolchain or an unreleased ref. Source installs require Git and Bun 1.4.2 or newer:\n\n```bash\nbun install --global @f5-sales-demo/xcsh\nnpm install --global @f5-sales-demo/xcsh\ncurl -fsSL https://raw.githubusercontent.com/f5-sales-demo/xcsh/main/scripts/install.sh \\\n  | sh -s -- --source --ref vX.Y.Z\n```\n\nThe explicit `--source` and `--ref` arguments select a reproducible source install.\n\n<details class=\"landing-disclosure\">\n<summary>Upgrade or remove</summary>\n\nUpgrade with `bun update --global @f5-sales-demo/xcsh` or\n`npm update --global @f5-sales-demo/xcsh`. `xcsh self-update` reports the matching\ncommand for a validated compiled-release launcher but never invokes the package\nmanager. Remove the package with `bun remove --global @f5-sales-demo/xcsh` or\n`npm uninstall --global @f5-sales-demo/xcsh`; re-run the source command at a new\nref to replace that unsupported development channel.\n</details>\n</TabItem>\n</Tabs>\n\nRun `xcsh self-update --check` for a read-only version and installation-channel report. A direct MDM package remains organization-managed. Missing, stale, spoofed, or conflicting provenance is blocked without downloading, invoking a package manager, or changing the executable; reinstall through the documented channel instead of mixing installers.\n\n<Aside type=\"caution\" title=\"Standalone receipt schema v2\">\nStandalone installations with an older schema-v1 receipt must run the documented installer once before using `xcsh self-update`. There is no compatibility parser or automatic receipt migration. A successful self-update advances the executable and adjacent receipt together and restores both if the transaction fails.\n</Aside>\n\nWhichever installation channel you choose, open xcsh next.\n\n<span id=\"verification\" aria-hidden=\"true\"></span>\n\n## Verify installation\n\n<span id=\"verify-the-active-installation\" aria-hidden=\"true\"></span>\n\nStart the interactive terminal UI:\n\n<div class=\"landing-command\">\n\n```bash\nxcsh\n```\n\n</div>\n\nWhen the xcsh prompt appears, connect a model provider from inside the TUI.\n\n<span id=\"authentication\" aria-hidden=\"true\"></span>\n\n## Authenticate a provider\n\nAt the xcsh prompt, open the provider picker:\n\n<div class=\"landing-command\">\n\n```text\n/login\n```\n\n</div>\n\nChoose a provider and follow its sign-in flow. You can also enter `/login PROVIDER` to open a known provider directly. Keep credentials in the provider-supported environment or subscription login—never in a prompt or committed settings file. See [model authentication](/xcsh/en/getting-started/model-authentication/) for provider-specific options.\n\nGPT-6 Luna and Sol use a 272K-token context window by default for ChatGPT subscription sessions.\nTo opt in to their published 1.05M-token window, open `/settings`, select **Providers**, and enable\n**OpenAI Codex Maximum Context**. OpenAI applies higher token pricing to requests above 272K.\nInternal LiteLLM GPT routes use the same 272K default independently; enable **LiteLLM Maximum\nContext** to opt those routes into their verified 1.05M-token window.\n\nAfter sign-in selects a model, stay in the TUI and send a small first prompt.\n\n## Quickstart\n\nAt the xcsh prompt, enter:\n\n<div class=\"landing-command\">\n\n```text\nReply with only: xcsh is ready\n```\n\n</div>\n\nA matching response confirms the installation, provider, and selected model are working together\nwithout granting a tool any file or network side effect. If it fails, verify the active executable\nwith `command -v xcsh`, reopen `/login`, and confirm the selected model is available to that\naccount. Next, learn the [interactive TUI](/xcsh/en/use-xcsh/interactive-tui/) or choose a [context and\nnamespace](/xcsh/en/f5-distributed-cloud/contexts-namespaces/) before an authorized F5 Distributed Cloud\nchange.\n\nFrom here, continue with the documentation path that matches your goal.\n\n<span id=\"exploration\" aria-hidden=\"true\"></span>\n\n## Explore by goal\n\nChoose the goal closest to your next task; each path starts from the verified installation above.\n\n<div class=\"landing-grid landing-explore\">\n  <LinkCard title=\"Use xcsh\" icon=\"terminal\" href=\"./use-xcsh/\">Daily terminal use, tools, sessions, plans, and agents.</LinkCard>\n  <LinkCard title=\"F5 Distributed Cloud\" icon=\"cloud\" href=\"./f5-distributed-cloud/\">Contexts, manifests, validation, and reviewable resource changes.</LinkCard>\n  <LinkCard title=\"Configure and secure\" icon=\"setting\" href=\"./configure-secure/\">Providers, settings, secrets, and sandbox boundaries.</LinkCard>\n  <LinkCard title=\"Automate and extend\" icon=\"puzzle\" href=\"./automate-extend/\">Headless modes, extensions, skills, plugins, and SDKs.</LinkCard>\n  <LinkCard title=\"Integrations and deployment\" icon=\"rocket\" href=\"./integrations-deployment/\">Containers plus VS Code, Chrome, Office, and Herdr.</LinkCard>\n  <LinkCard title=\"Reference and troubleshooting\" icon=\"information\" href=\"./reference-troubleshooting/\">Diagnostics, command reference, hotkeys, and configuration schema.</LinkCard>\n</div>\n",
+	"en/index.mdx": "---\ntitle: xcsh\ndescription: Install xcsh, authenticate a model provider, and begin a reviewable terminal or F5 Distributed Cloud workflow.\ntemplate: splash\neditUrl: false\nsidebar:\n  hidden: true\n  order: 0\nhead:\n  - tag: style\n    content: |\n      main:has(.landing-hero) > .content-panel:first-of-type { padding-block-end: .5rem; }\n      main:has(.landing-hero) > .content-panel:first-of-type + .content-panel { border-top: 0; padding-block-start: 0; }\n      .landing-hero { display: grid; gap: clamp(2rem, 4vw, 4rem); grid-template-columns: minmax(0, 1fr) minmax(18rem, 35rem); align-items: center; margin-block: .75rem 2rem; }\n      .landing-hero__content, .landing-hero__image, .landing-installer, .landing-installer .expressive-code, .landing-command { min-width: 0; }\n      h1#_top { max-width: 13ch; margin-block-end: 0; text-wrap: balance; }\n      .landing-hero__lede { max-width: 42rem; color: var(--sl-color-gray-2); font-size: var(--sl-text-lg); }\n      .landing-installer { margin-block: 0 4rem; padding: clamp(1rem, 2vw, 1.5rem); border: 1px solid var(--sl-color-gray-5); border-radius: .75rem; background: var(--sl-color-bg-nav); }\n      .landing-installer h2 { margin: 0; font-size: var(--sl-text-lg); }\n      .landing-installer p { margin-block: .5rem 0; }\n      .landing-installer pre { max-width: 100%; overflow-x: auto; }\n      .landing-installer .expressive-code .ec-line .code { padding-inline-end: 3.5rem; white-space: pre; overflow-wrap: normal; }\n      .landing-installer .expressive-code .copy button { opacity: 1; }\n      .landing-hero__image { margin: 0; }\n      .landing-hero__image img { display: block; width: 100%; height: auto; aspect-ratio: 1442 / 1268; object-fit: contain; filter: drop-shadow(0 1rem 2.5rem color-mix(in srgb, var(--sl-color-accent) 28%, transparent)); }\n      .landing-grid { display: grid; gap: 1rem; grid-template-columns: repeat(3, minmax(0, 1fr)); margin-block: 1.5rem; }\n      .landing-explore { grid-template-columns: repeat(2, minmax(0, 1fr)); }\n      details.landing-disclosure { margin-block: 1rem 0; padding: .75rem 1rem; border: 1px solid var(--sl-color-gray-5); border-radius: .5rem; background: var(--sl-color-bg-nav); }\n      details.landing-disclosure summary { cursor: pointer; font-weight: 600; }\n      :is(.landing-hero, .landing-installer, .landing-grid, .landing-disclosure) :is(a, button, summary):focus-visible { outline: 2px solid var(--sl-color-accent-high); outline-offset: 3px; }\n      @media (max-width: 50rem) { .landing-hero { grid-template-columns: minmax(0, 1fr); gap: 2rem; margin-block: .5rem 2rem; } .landing-installer { margin-block-end: 3rem; padding: 1rem; } .landing-grid { grid-template-columns: minmax(0, 1fr); } }\n---\n\nimport { Aside, Card, LinkCard, TabItem, Tabs } from '@astrojs/starlight/components';\n\n<section class=\"landing-hero\" aria-labelledby=\"_top\">\n  <div class=\"landing-hero__content\">\n    <p class=\"landing-hero__lede\">An AI-native terminal assistant for engineering, automation, and reviewable F5 Distributed Cloud workflows.</p>\n    <p>xcsh is an independent open-source project derived from pi/pi-mono, specialized for F5 Distributed Cloud workflows; it is not an F5 product.</p>\n  </div>\n\n  <figure class=\"landing-hero__image\">\n    <img src=\"/xcsh/images/xcsh-ghostty-terminal.png\" width=\"1442\" height=\"1268\" alt=\"xcsh running in a Ghostty terminal with the model selector, prompt, and session status visible.\" />\n  </figure>\n</section>\n\n<section class=\"landing-installer\" aria-labelledby=\"install-xcsh\">\n\n## Install xcsh\n\n  <p>Universal installer for macOS and Linux.</p>\n\n  ```bash\n  curl -fsSL https://raw.githubusercontent.com/f5-sales-demo/xcsh/main/scripts/install.sh | sh\n  ```\n\n  <p>\n    It installs the latest prebuilt release and a schema-v2 provenance receipt into <code>~/.local/bin</code>.\n    The native addons are embedded in the executable.\n  </p>\n  <p>\n    On Linux, the installer also retains the published SHA-256 checksums and build provenance,\n    and verifies them before running or replacing the binary.\n    A failed download, validation, or replacement restores the previous installation.\n  </p>\n  <p>\n    The binary installer requires cURL, <code>jq</code>, and <code>sha256sum</code> or <code>shasum</code>.\n    This is the only channel that <code>xcsh self-update</code> replaces in process.\n    Need a managed or platform-specific channel? Compare the <a href=\"#installation-options\">installation options</a>.\n  </p>\n</section>\n\n## What xcsh helps you do\n\n<div class=\"landing-grid landing-capabilities\">\n  <Card title=\"Agentic terminal work\" icon=\"terminal\">\n    Run interactive or print-mode prompts, inspect files, use tools, and keep durable session history when the task needs it. [Learn the agent loop](/xcsh/en/use-xcsh/agent-loop/).\n  </Card>\n  <Card title=\"Reviewable F5 Distributed Cloud workflows\" icon=\"document\">\n    Discover schemas, validate manifests, and inspect proposed differences before an authorized resource change. [Use resource workflows](/xcsh/en/f5-distributed-cloud/).\n  </Card>\n  <Card title=\"Extensible automation\" icon=\"puzzle\">\n    Add headless workflows, custom tools, skills, or plugins when built-in commands are not enough. [Automate and extend](/xcsh/en/automate-extend/).\n  </Card>\n</div>\nThese workflows start with a working executable; choose another channel only when the universal installer is not the right fit.\n\n## Installation options\n\nUse one channel for install and upgrades. Mixing package-manager and standalone installations can leave more than one `xcsh` on `PATH`; the universal installer above is not repeated here.\n\n<Tabs syncKey=\"install-platform\">\n<TabItem label=\"macOS\" icon=\"seti:apple\">\nInstall the signed and notarized macOS archive through the Homebrew cask. The cask preserves the released executable and native addon byte for byte and does not require `sudo`:\n\n```bash\nbrew install --cask f5-sales-demo/tap/xcsh\n```\n\n<details class=\"landing-disclosure\">\n<summary>Upgrade or remove</summary>\n\nUpgrade with `brew upgrade --cask f5-sales-demo/tap/xcsh`. Remove the cask with `brew uninstall --cask xcsh`. `xcsh self-update` reports the tap-qualified command but never invokes Homebrew. These commands preserve configuration, credentials, and sessions under `~/.xcsh`.\n</details>\n\n<Aside type=\"caution\" title=\"Clean break from the historical package cask\">\nBefore installing this cask on a Mac that received an earlier xcsh package,\nuninstall both old Homebrew entries (`brew uninstall --formula xcsh` and\n`brew uninstall --cask xcsh`). Then have MDM forget the `com.f5.xcsh` receipt\nand remove only the package-owned `/usr/local/bin/xcsh` and\n`/Library/Application Support/xcsh` payload. Do not remove `~/.xcsh`. The signed\nand stapled `.pkg` release assets remain available only for direct MDM\ndeployment.\n</Aside>\n</TabItem>\n\n<TabItem label=\"Ubuntu or Debian\" icon=\"seti:ubuntu\">\nThe signed apt repository supports amd64 and arm64 and follows normal system upgrades:\n\n```bash\nsudo install -d -m 0755 /etc/apt/keyrings\ncurl -fsSL https://f5-sales-demo.github.io/apt-repo/f5xc-archive-keyring.gpg \\\n  | sudo tee /etc/apt/keyrings/f5xc-archive-keyring.gpg >/dev/null\necho \"deb [arch=amd64,arm64 signed-by=/etc/apt/keyrings/f5xc-archive-keyring.gpg] https://f5-sales-demo.github.io/apt-repo stable main\" \\\n  | sudo tee /etc/apt/sources.list.d/f5xc.list\nsudo apt-get update && sudo apt-get install xcsh\n```\n\n<details class=\"landing-disclosure\">\n<summary>Upgrade or remove</summary>\n\nUpgrade with `sudo apt-get update && sudo apt-get install --only-upgrade xcsh`. Remove the package with `sudo apt-get remove xcsh`. `xcsh self-update` reports this command when `dpkg-query` proves that package `xcsh` owns the running executable; it never invokes apt.\n</details>\n</TabItem>\n\n<TabItem label=\"Windows\" icon=\"seti:windows\">\nRun the PowerShell installer, then restart the terminal so its user `PATH` refreshes:\n\n```powershell\nirm https://raw.githubusercontent.com/f5-sales-demo/xcsh/main/scripts/install.ps1 | iex\n```\n\nIt installs `xcsh.exe` and its schema-v2 provenance receipt to `%LOCALAPPDATA%\\\\xcsh`; the native addon is embedded. **Bash is required for tool-backed sessions.** Install Git for Windows, WSL, Cygwin, or MSYS2; set `shellPath` in `%USERPROFILE%\\\\.xcsh\\\\agent\\\\settings.json` when Bash is elsewhere.\n\n<details class=\"landing-disclosure\">\n<summary>Upgrade or remove</summary>\n\nRe-run the installer to upgrade. `xcsh self-update` reports the PowerShell installer command but does not replace a Windows installer-owned executable. To uninstall, remove `%LOCALAPPDATA%\\\\xcsh` and its entry from the user `PATH`.\n</details>\n</TabItem>\n\n<TabItem label=\"Container\" icon=\"seti:docker\">\nDocker and Podman use the same multi-architecture image. Pin a release tag, resolve its digest for deployment, and mount only the workspace and state required by the task:\n\n```bash\ndocker pull ghcr.io/f5-sales-demo/xcsh:vX.Y.Z\ndocker image inspect --format '{{index .RepoDigests 0}}' ghcr.io/f5-sales-demo/xcsh:vX.Y.Z\ndocker run --rm ghcr.io/f5-sales-demo/xcsh@sha256:<digest> --version\n```\n\nPodman accepts the same pull, inspect, and run arguments. Pass provider credentials at runtime through a secret manager or environment file; never bake them into an image layer.\n\n<details class=\"landing-disclosure\">\n<summary>Upgrade or remove</summary>\n\nPull a newer pinned tag to upgrade. Remove an unused image with `docker image rm IMAGE` or `podman image rm IMAGE`.\n</details>\n</TabItem>\n\n<TabItem label=\"Packages and source\" icon=\"seti:config\">\nUse a JavaScript package or a source/ref install when you need a toolchain or an unreleased ref. Source installs require Git and Bun 1.4.2 or newer:\n\n```bash\nbun install --global @f5-sales-demo/xcsh\nnpm install --global @f5-sales-demo/xcsh\ncurl -fsSL https://raw.githubusercontent.com/f5-sales-demo/xcsh/main/scripts/install.sh \\\n  | sh -s -- --source --ref vX.Y.Z\n```\n\nThe explicit `--source` and `--ref` arguments select a reproducible source install.\n\n<details class=\"landing-disclosure\">\n<summary>Upgrade or remove</summary>\n\nUpgrade with `bun update --global @f5-sales-demo/xcsh` or\n`npm update --global @f5-sales-demo/xcsh`. `xcsh self-update` reports the matching\ncommand for a validated compiled-release launcher but never invokes the package\nmanager. Remove the package with `bun remove --global @f5-sales-demo/xcsh` or\n`npm uninstall --global @f5-sales-demo/xcsh`; re-run the source command at a new\nref to replace that unsupported development channel.\n</details>\n</TabItem>\n</Tabs>\n\nRun `xcsh self-update --check` for a read-only version and installation-channel report. A direct MDM package remains organization-managed. Missing, stale, spoofed, or conflicting provenance is blocked without downloading, invoking a package manager, or changing the executable; reinstall through the documented channel instead of mixing installers.\n\n<Aside type=\"caution\" title=\"Standalone receipt schema v2\">\nStandalone installations with an older schema-v1 receipt must run the documented installer once before using `xcsh self-update`. There is no compatibility parser or automatic receipt migration. A successful self-update advances the executable and adjacent receipt together and restores both if the transaction fails.\n</Aside>\n\nWhichever installation channel you choose, open xcsh next.\n\n<span id=\"verification\" aria-hidden=\"true\"></span>\n\n## Verify installation\n\n<span id=\"verify-the-active-installation\" aria-hidden=\"true\"></span>\n\nStart the interactive terminal UI:\n\n<div class=\"landing-command\">\n\n```bash\nxcsh\n```\n\n</div>\n\nWhen the xcsh prompt appears, connect a model provider from inside the TUI.\n\n<span id=\"authentication\" aria-hidden=\"true\"></span>\n\n## Authenticate a provider\n\nAt the xcsh prompt, open the provider picker:\n\n<div class=\"landing-command\">\n\n```text\n/login\n```\n\n</div>\n\nChoose a provider and follow its sign-in flow. You can also enter `/login PROVIDER` to open a known provider directly. Keep credentials in the provider-supported environment or subscription login—never in a prompt or committed settings file. See [model authentication](/xcsh/en/getting-started/model-authentication/) for provider-specific options.\n\nGPT-6 Luna and Sol use a 272K-token context window by default for ChatGPT subscription sessions.\nTo opt in to their published 1.05M-token window, open `/settings`, select **Providers**, and enable\n**OpenAI Codex Maximum Context**. OpenAI applies higher token pricing to requests above 272K.\nInternal LiteLLM GPT routes use the same 272K default independently; enable **LiteLLM Maximum\nContext** to opt those routes into their verified 1.05M-token window.\n\nAfter sign-in selects a model, stay in the TUI and send a small first prompt.\n\n## Quickstart\n\nAt the xcsh prompt, enter:\n\n<div class=\"landing-command\">\n\n```text\nReply with only: xcsh is ready\n```\n\n</div>\n\nA matching response confirms the installation, provider, and selected model are working together\nwithout granting a tool any file or network side effect. If it fails, verify the active executable\nwith `command -v xcsh`, reopen `/login`, and confirm the selected model is available to that\naccount. Next, learn the [interactive TUI](/xcsh/en/use-xcsh/interactive-tui/) or choose a [context and\nnamespace](/xcsh/en/f5-distributed-cloud/contexts-namespaces/) before an authorized F5 Distributed Cloud\nchange.\n\nFrom here, continue with the documentation path that matches your goal.\n\n<span id=\"exploration\" aria-hidden=\"true\"></span>\n\n## Explore by goal\n\nChoose the goal closest to your next task; each path starts from the verified installation above.\n\n<div class=\"landing-grid landing-explore\">\n  <LinkCard title=\"Use xcsh\" icon=\"terminal\" href=\"./use-xcsh/\">Daily terminal use, tools, sessions, plans, and agents.</LinkCard>\n  <LinkCard title=\"F5 Distributed Cloud\" icon=\"cloud\" href=\"./f5-distributed-cloud/\">Contexts, manifests, validation, and reviewable resource changes.</LinkCard>\n  <LinkCard title=\"Configure and secure\" icon=\"setting\" href=\"./configure-secure/\">Providers, settings, secrets, and sandbox boundaries.</LinkCard>\n  <LinkCard title=\"Automate and extend\" icon=\"puzzle\" href=\"./automate-extend/\">Headless modes, extensions, skills, plugins, and SDKs.</LinkCard>\n  <LinkCard title=\"Integrations and deployment\" icon=\"rocket\" href=\"./integrations-deployment/\">Containers plus VS Code, Chrome, Office, and Herdr.</LinkCard>\n  <LinkCard title=\"Reference and troubleshooting\" icon=\"information\" href=\"./reference-troubleshooting/\">Diagnostics, command reference, hotkeys, and configuration schema.</LinkCard>\n</div>\n",
 	"en/integrations-deployment/chrome.mdx": "---\ntitle: \"Chrome\"\ndescription: \"Use the xcsh Chrome extension and native host with an isolated automation profile.\"\nsidebar:\n  order: 3\n  label: \"Chrome\"\n---\n\nThe Chrome integration connects xcsh to a browser session for supported console automation. The installed `xcsh chrome --help` output is the command authority.\n\n## What is the safe operating boundary?\n\nUse a dedicated profile and an authorized target. Confirm the visible account, uniform resource locator (URL), and object before an action that changes state. Prefer deterministic F5 Distributed Cloud resource commands whenever they cover the same operation.\n\n## Which Chrome capabilities does xcsh expose?\n\nThe `chrome` command inspects and arranges browser sessions, and `chrome-host` runs the native messaging host that connects the extension to the executable. Page-level interaction is driven by the browser tool inside a session rather than by a subcommand, so scope it with `--tools` in the same way as any other tool.\n\n| Need | Use Chrome integration? | Boundary |\n| --- | --- | --- |\n| Inspect a visible page or perform a supported console-only task | Yes | The browser profile and signed-in session define authority. |\n| Manage a resource with an xcsh catalog command | No | Prefer the typed resource workflow and its diff. |\n| Automate an unsupported site or a third-party account | No | The integration does not expand authorization. |\n\nStart with a read-only inspection and confirm the selected tab, URL, tenant, and browser profile. A click or submitted form can create an external side effect; the transcript must identify that boundary. Close temporary tabs and verify the intended page state after the task.\n",
 	"en/integrations-deployment/containers.mdx": "---\ntitle: \"Containers\"\ndescription: \"Run the published multi-architecture Alpine image with explicit mounts and credentials.\"\nsidebar:\n  order: 4\n  label: \"Containers\"\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\nThe published container packages xcsh for process isolation and repeatable deployment. It does not grant cloud credentials or filesystem access by itself.\n\n## How do I verify an image?\n\n```bash\ndocker pull ghcr.io/f5-sales-demo/xcsh:latest\ndocker run --rm ghcr.io/f5-sales-demo/xcsh:latest --version\n```\n\nPin a version tag or digest for automation. Mount only the task directory and inject credentials through the runtime's secret mechanism.\n\n## What must remain outside the image?\n\nKeep user contexts, provider tokens, and writable session data in explicit mounts or secret stores. Do not bake them into a derived layer.\n\nPull a versioned image, resolve its immutable digest, and run `xcsh --version` from that digest\nbefore mounting a workspace. The container image supplies the executable, not model or tenant\nauthority. Mount only required paths read-only where possible and inject credentials at runtime\nthrough the platform's secret mechanism. Remove the test container after exit; delete the pinned\nimage only when no deployment still references its digest.\n",
 	"en/integrations-deployment/herdr.mdx": "---\ntitle: \"Integrate with Herdr\"\ndescription: \"Understand Herdr workspace launch, terminal actions, protocol negotiation, and isolation.\"\nsidebar:\n  order: 5\n  label: \"Herdr\"\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\nHerdr support is optional and host-dependent. When the host does not provide it, xcsh terminal operation is unaffected.\n\n## How is the host protocol negotiated?\n\nThe integration checks the available socket protocol and media or graphics capabilities before it requests a workspace. Missing negotiation support leaves ordinary xcsh terminal operation intact.\n\n## How is a conversation-owned workspace launched?\n\nA workspace is tied to the conversation identity supplied at startup. Terminal-management actions create or address panes within that workspace, and lifecycle reporting stays anchored to the same startup context. Do not reuse an unrelated workspace merely because its socket is reachable.\n\n## How do I recover from socket failure?\n\nConnection and framing failures surface as integration diagnostics. The client must not open an inbound listener as a fallback. Close conversation-owned resources through the supported lifecycle and preserve unrelated Herdr workspaces.\n\n## What lifecycle state does xcsh publish?\n\nxcsh publishes native turn phases rather than inferring completion from terminal idleness or process\nexit. With a supported Herdr protocol through 26 and the advertised `agent_turn_journal` capability, a tracked\nexecution publishes a persisted session/turn identity and a bounded semantic result to Herdr's\ndurable journal. The existing 80-character metadata preview remains display-only and is never\ncompletion evidence.\nCommentary, prompt content, tool data, and failed or cancelled partial output are excluded.\n\n### External execution driver contract\n\nThe supported producer is the normal `xcsh` executable launched by Herdr's execution backend; it is not a mock or a no-provider/offline actor. For a journal-tracked invocation, that backend must inject the exact allocated `HERDR_EXECUTION_ID` and decimal safe-integer `HERDR_EXECUTION_GENERATION` into the child environment before it starts `xcsh`.\n\nxcsh never guesses a generation: without both values it retains ordinary pane lifecycle reporting but emits no semantic journal event. A continuation must be launched with its newly allocated generation.\n\nProtocol 27 is the current producer-native contract. Herdr injects a one-time `HERDR_NATIVE_CAPABILITY` into the child. xcsh includes it only in authenticated turn-report and action requests; it is never written to the session journal, logs, diagnostics, or receipts.\nHerdr does not authorize actions until the first `starting` report has been durably journaled and bound to the owned PTY, pane, session, generation, and turn.\n\nEach semantic report has a five-second deadline. xcsh retries exactly once only when timeout,\nEOF, or a transport error leaves admission ambiguous. The retry preserves the method and complete\nsemantic payload and changes only the transport request ID. Either correlated receipt marks the\nevent delivered; protocol, validation, malformed-response, and explicit remote errors are definitive\nand are not retried. Degraded tracking is shown only after both ambiguous attempts fail.\n\nThe producer wire shapes align with [Herdr PR #49](https://github.com/f5-sales-demo/herdr/pull/49) at cancellation-settlement commit `2c838cf545ed06439b4988cedb3e044f1d436264`, starting-replay recovery commit `edd5611cfd7685c0f069f244ceee0ac6c0a0678e`, and native-argv alignment commit `3397302960593a552fb37ceb71053cf99f2619a3`.\nThose commits are an integration contract under independent review, not released-backend evidence.\n\nAfter that registration, xcsh polls `agent.turn.action.get` with the same immutable provenance. A `cancel` action dismisses an active managed UI prompt and calls the real `AgentSession` abort path. xcsh persists the requested action and local safe point before sending the exact `agent.turn.action.ack`; it emits `cancelled` only after Herdr confirms that safe point.\nA lost ACK response is retried with the same action ID and revision, including after reporter restart. A backend `timed_out` action never triggers a late abort. PTY exit alone is not semantic cancellation.\n\nSession shutdown releases pane authority. It does not convert an unfinished turn into a successful completion.\n\n### Producer-native acceptance driver\n\n`xcsh lifecycle --json` prints the version 3 machine-readable producer contract. To execute a source or installed\nproducer check, supply a fresh absolute session directory, a normally configured model, and one scenario:\n\n```bash\nxcsh lifecycle --json \\\n  --scenario await-continue \\\n  --model openai-codex/gpt-5.6-luna \\\n  --session-dir /absolute/fresh/xcsh-lifecycle-session\n```\n\nSupported scenarios are `success`, `failure`, `await-continue`, `cancel`, `managed-cancel`, `managed-working-cancel`, `local-operation-failure`, and `reply-loss-replay`. The driver first\nuses the prompt-free JSON session contract to persist one canonical 16-character lowercase hexadecimal session\nheader, then reopens that exact path in an ordinary interactive xcsh child. It generates a random mode-0600 fixture\nfor successful reads. `await-continue` selects the explicit `await_user_v1` producer control and pauses in the real\n`ExtensionUIController` input surface before the configured\nmodel runs; `cancel` sends SIGINT through `PtySession.interrupt()` and requires xcsh's native `cancelled` transition.\n`managed-cancel` uses a local protocol-27 control fixture to request the action and requires the executable child to\nacknowledge its safe point before its native `cancelled` report. That fixture validates the producer adapter only; it\nis not evidence for Herdr's durable action journal, manager generation replacement, or consumer deduplication.\n`managed-working-cancel` requests the same cooperative action after the real child reports `working`, without opening\nthe acceptance prompt, and verifies cancellation through the active `AgentSession` path.\n`local-operation-failure` selects `local_operation_failure_v1` in a noninteractive native child. The producer creates\na private directory under the child cwd, performs a real read of a guaranteed-missing path inside it, cleans up the\nowned directory, and propagates the resulting ENOENT through normal `AgentSession` failed settlement. It does not use\nan invalid credential, an offline model, or a fabricated lifecycle frame.\n\nThe producer accepts these exact explicit argv mappings; no control is active when the flag is omitted. The published\n`await-user` spelling remains an alias for `await_user_v1` for existing acceptance callers.\n\n| Typed lifecycle mode | Producer argv | Constraint |\n| --- | --- | --- |\n| `managed_turn_v1` | no additional argv | Existing protocol-27 v3 behavior. |\n| `await_user_v1` | `--native-lifecycle-control await_user_v1` | `interactive: true`. |\n| `local_operation_failure_v1` | `--native-lifecycle-control local_operation_failure_v1` | `interactive: false`. |\n\nThe current Herdr protocol-27 schema exposes only `managed_turn_v1`; the other two rows define the producer side of a\nfuture typed schema extension, not permission for a caller to supply arbitrary argv. xcsh does not invent action\nmethods for response loss or restart. Real Herdr-bound retry and restart controls must use a committed authenticated\nbackend schema and preserve the same session, generation, pane, turn, report revision, and request-only capability.\n\nThe reply-loss scenario owns a temporary local protocol-27 socket that acknowledges ordinary reporter traffic but\ndrops both bounded `agent.turn.report` attempts. xcsh creates and persists the semantic event before transport, runs the\nconfigured provider and `read` tool, then a second xcsh process resumes the exact session path. The scenario passes\nonly when the reporter redelivers the byte-equivalent execution, pane, session, turn, generation, event revision, and\nstate fields. The socket never authors a lifecycle frame or substitutes an offline model.\n\nThe receipt's `evidenceClass` is `source_native_child`. This proves the measured source or executable behavior only;\nthe Control Manager remains responsible for its own admission, authenticated execution binding, generation changes,\nconsumer receipts, and installed-artifact acceptance. The command does not install or release xcsh or Herdr and does\nnot change normal launch defaults.\n\nThe verified contract is:\n\n| Concern | xcsh signal | Herdr disposition |\n| --- | --- | --- |\n| Session start and identity | Persisted native session ID/path | Herdr resume reference plus stable semantic session identity. |\n| Turn start/progress | Persisted UUID and normalized `turn_phase` | `starting`/`working` journal events with producer revision and server revision. |\n| Waiting for input/approval | `awaiting_user` and closed prompt kind | `waiting_input` with fixed safe reason; private prompt content is excluded. |\n| Successful completion | Settlement-aware `idle` after `agent_end` | `completed` with at most 8,000 UTF-8 bytes and a matching SHA-256 digest. |\n| Failure/cancellation | `error` or `cancelled` | Distinct terminal state and bounded safe reason; no partial result. |\n| Managed cancellation | Persisted action receipt, Extension UI signal, and `AgentSession.abort()` | Authenticated `safe_point` precedes and is linked to the native `cancelled` report. |\n| Resume/fork | Session events and persisted custom turn entries | Resume preserves identity; unfinished recovered work becomes `interrupted`; fork has separate session lineage. |\n| Reconnect/order | Serialized queue and persisted event revision | Exact duplicates are idempotent; stale/conflicting revisions fail; terminal state is immutable. |\n| Application exit | `session_shutdown` | Active turn becomes `interrupted`, then pane authority is released; never success. |\n\nThe protocol-26 native-interaction update is tracked by\n[issue #4161](https://github.com/f5-sales-demo/xcsh/issues/4161); its producer lifecycle foundation is\ntracked by [issue #3791](https://github.com/f5-sales-demo/xcsh/issues/3791) and\n[issue #3768](https://github.com/f5-sales-demo/xcsh/issues/3768). The active protocol and lifecycle\nbehavior is described on this page; obsolete delivery checklists are not part of the runtime contract.\n\nHerdr lifecycle reconciliation is tracked by issue #5 in the F5 Herdr fork. Current source already recognizes the exact `(\"herdr:xcsh\", \"xcsh\")` resume pair; deployed build provenance and live resume/fork acceptance remain required before feature acceptance.\n\nTreat the negotiated protocol and the pane lifecycle as separate checks. First confirm that the\nHerdr socket and protocol version are compatible, then launch one conversation-owned workspace and\nobserve its published state through exit. xcsh owns only workspaces it created for that\nconversation; it must not close unrelated panes. After a forced socket failure, reconnect and verify\nthat stale workspace state is reconciled before another launch.\n",

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

@@ -30,12 +30,13 @@ export const TERRAFORM_INDEX: TerraformIndex = {
 			name: "Uncategorized",
 			slug: "uncategorized",
 			description: "Resources pending categorization",
-			resource_count: 33,
+			resource_count: 34,
 			resources: [
 				"healthcheck",
 				"application_profiles",
 				"authorization_server",
 				"bot_infrastructure",
+				"cloud_user_account",
 				"cluster",
 				"cminstance",
 				"crl",
@@ -322,6 +323,20 @@ export const TERRAFORM_INDEX: TerraformIndex = {
 			},
 			import_syntax: "terraform import xcsh_bot_infrastructure.example namespace/name",
 		},
+		{
+			name: "cloud_user_account",
+			category: "uncategorized",
+			description: "Cloud user account object create specifications. configuration",
+			required: ["name", "namespace"],
+			minimal_config: {
+				format: "terraform",
+				source: "_llms-txt/resources/cloud_user_account.txt#minimal-valid-config",
+			},
+			dependencies: {
+				requires: [],
+			},
+			import_syntax: "terraform import xcsh_cloud_user_account.example namespace/name",
+		},
 		{
 			name: "cluster",
 			category: "uncategorized",

package/src/modes/components/btw-panel.ts

@@ -2,7 +2,12 @@ import { Container, Markdown, type TUI } from "@f5-sales-demo/pi-tui";
 import { replaceTabs } from "../../tools/render-utils";
 import { getMarkdownTheme, theme } from "../theme/theme";
 import { appInterruptHint } from "../utils/keybinding-matchers";
-import { selectorCancelHint, selectorFrame, selectorFrameContentWidth, selectorProse } from "./selector-frame";
+import {
+	selectorCancelHint,
+	selectorFrameContentWidth,
+	selectorProse,
+	selectorTranscriptFrame,
+} from "./selector-frame";
 
 type BtwPanelState = "running" | "complete" | "aborted" | "error";
 
@@ -69,18 +74,15 @@ export class BtwPanelComponent extends Container {
 			? new Markdown(answer, 0, 0, getMarkdownTheme()).render(innerWidth)
 			: [theme.fg("dim", this.#state === "running" ? "Waiting for response…" : "No text returned.")];
 		const state = this.#stateLine();
-		return selectorFrame(
+		return selectorTranscriptFrame(
 			width,
-			body.length + 12,
 			"BTW",
 			"Ephemeral side answer from a snapshot of the current session; it is not added to the transcript.",
-			[],
 			[
 				selectorProse(theme.fg("contentAccent", replaceTabs(this.#question))),
 				...body.map(line => selectorProse(line)),
 			],
-			state ? [state] : [],
-			[this.#footerLine()],
+			[this.#footerLine(), ...(state ? [state] : [])],
 		);
 	}
 

package/src/modes/components/plan-preview.ts

@@ -1,6 +1,6 @@
 import { Container, Markdown } from "@f5-sales-demo/pi-tui";
 import { getMarkdownTheme } from "../theme/theme";
-import { selectorFrame, selectorFrameContentWidth, selectorProse } from "./selector-frame";
+import { selectorFrameContentWidth, selectorProse, selectorTranscriptFrame } from "./selector-frame";
 
 /** Static transcript-adjacent plan preview; approval controls live in the separate review overlay. */
 export class PlanPreviewComponent extends Container {
@@ -11,15 +11,11 @@ export class PlanPreviewComponent extends Container {
 	override render(width: number): string[] {
 		const inner = selectorFrameContentWidth(width);
 		const body = new Markdown(this.content, 0, 0, getMarkdownTheme()).render(inner);
-		return selectorFrame(
+		return selectorTranscriptFrame(
 			width,
-			body.length + 7,
 			"Plan review",
 			"Prepared execution plan; use the active review overlay to approve, revise, or cancel.",
-			[],
 			body.map(line => selectorProse(line)),
-			[],
-			[],
 		);
 	}
 }

package/src/modes/components/question-transcript.ts

@@ -1,7 +1,7 @@
 import type { Component } from "@f5-sales-demo/pi-tui";
 import type { AsyncInputQuestion, AsyncQuestionItem } from "../../../../chat-ui/src/interactions/contract";
 import { theme } from "../theme/theme";
-import { selectorFrame, selectorFrameContentWidth, selectorProse, selectorRow } from "./selector-frame";
+import { selectorProse, selectorTranscriptFrame } from "./selector-frame";
 
 export interface AsyncInputReply {
 	type: "user_input_reply";
@@ -97,19 +97,13 @@ export class QuestionTranscriptComponent implements Component {
 	}
 
 	render(width: number): string[] {
-		const inner = selectorFrameContentWidth(width);
 		if (this.state.kind === "pending") {
 			const count = this.state.item.questions.length;
-			return selectorFrame(
+			return selectorTranscriptFrame(
 				width,
-				Math.max(8, count + 7),
 				"Questions pending",
 				`${count} ${count === 1 ? "question" : "questions"} · Work continues while you answer`,
-				[],
-				this.state.item.questions.map((question, index) =>
-					selectorRow([`${index + 1}. ${question.title}`], [inner - 2], false),
-				),
-				[],
+				this.state.item.questions.map((question, index) => selectorProse(`${index + 1}. ${question.title}`)),
 				[`${theme.fg("contentAccent", "/questions")} to answer`],
 			);
 		}
@@ -117,16 +111,10 @@ export class QuestionTranscriptComponent implements Component {
 		const answer = question.isSecret
 			? theme.fg("muted", "Answer hidden")
 			: reply.answer.replace(/^user_note:\s*/, "");
-		return selectorFrame(
-			width,
-			8,
-			"Answer recorded",
-			`Question ${position + 1} of ${total}`,
-			[question.title],
-			[selectorProse(`${theme.symbol("checkbox.checked")} ${answer}`)],
-			[],
-			[],
-		);
+		return selectorTranscriptFrame(width, "Answer recorded", `Question ${position + 1} of ${total}`, [
+			selectorProse(question.title),
+			selectorProse(`${theme.symbol("checkbox.checked")} ${answer}`),
+		]);
 	}
 
 	invalidate(): void {}

package/src/modes/components/searchable-select-list.ts

@@ -5,9 +5,11 @@ import {
 	type SelectListTheme,
 	type SgrMouseEvent,
 	truncateToWidth,
+	wrapTextWithAnsi,
 } from "@f5-sales-demo/pi-tui";
 import {
 	matchesSelectorKey,
+	SelectorDetailPager,
 	selectorCancelHint,
 	selectorFrame,
 	selectorFrameContentWidth,
@@ -28,6 +30,7 @@ export class SearchableSelectList extends SelectList {
 	#searchOrigin = 0;
 	#visible = 1;
 	#hitRows = new Map<number, number>();
+	#details = new SelectorDetailPager();
 
 	constructor(
 		private readonly title: string,
@@ -71,6 +74,16 @@ export class SearchableSelectList extends SelectList {
 		const start = Math.max(0, Math.min(position - Math.floor(this.#visible / 2), filtered.length - this.#visible));
 		const visible = filtered.slice(start, start + this.#visible);
 		const selected = this.sourceItems[this.#selectedIndex];
+		const details = this.#details.render(
+			[
+				...(wrapTextWithAnsi(this.purpose, inner).length > 2 ? [this.purpose] : []),
+				selected?.label ?? "",
+				selected?.description ?? "",
+				selected && selected.value !== selected.label ? `Identity: ${selected.value}` : "",
+			],
+			inner,
+			Math.max(1, Math.floor(rows / 5)),
+		);
 		const body = visible.length
 			? visible.map(index => {
 					const item = this.sourceItems[index]!;
@@ -84,17 +97,16 @@ export class SearchableSelectList extends SelectList {
 			this.purpose,
 			[`${filtered.length} of ${this.sourceItems.length} options`, ...this.#search.render(inner)],
 			body,
-			selected
-				? [selected.description ?? "", selected.value !== selected.label ? `Identity: ${selected.value}` : ""]
-				: [],
+			details,
 			[
 				selectorNavigationHint(),
 				selectorCancelHint(this.#search.getValue() ? "clear search" : "back"),
-				...(filtered.length > this.#visible
+				...this.#details.hint,
+				...(this.#details.hint.length === 0 && filtered.length > this.#visible
 					? [`${selectorKeys("pageUp")}/${selectorKeys("pageDown")}: options`]
 					: []),
 			],
-			{ selectedBodyIndex: visible.indexOf(this.#selectedIndex) },
+			{ selectedBodyIndex: visible.indexOf(this.#selectedIndex), selectedDetail: "provided" },
 		);
 		this.#hitRows.clear();
 		let cursor = 0;
@@ -161,7 +173,9 @@ export class SearchableSelectList extends SelectList {
 			return;
 		}
 		if (matchesSelectorKey(data, "pageUp") || matchesSelectorKey(data, "pageDown")) {
-			this.#move((matchesSelectorKey(data, "pageUp") ? -1 : 1) * this.#visible);
+			const direction = matchesSelectorKey(data, "pageUp") ? -1 : 1;
+			if (this.#details.page(direction)) return;
+			this.#move(direction * this.#visible);
 			return;
 		}
 		if (matchesSelectorKey(data, "confirm")) {

package/src/modes/components/selector-frame.ts

@@ -243,6 +243,23 @@ export function selectorProse(content: string, tone: "text" | "muted" = "text"):
 	return { kind: "wrapped-prose", content, tone };
 }
 
+/** Static transcript content scrolls with the transcript rather than a bounded overlay. */
+export function selectorTranscriptFrame(
+	width: number,
+	title: string,
+	purpose: string,
+	body: SelectorFrameLine[],
+	footer: string[] = [],
+): string[] {
+	const prose = [...(purpose ? [selectorProse(purpose, "muted")] : []), ...body];
+	const inner = selectorFrameContentWidth(width);
+	const bodyRows = prose.reduce(
+		(count, value) => count + (value.kind === "wrapped-prose" ? wrapSection([value.content], inner).length : 1),
+		0,
+	);
+	return selectorFrame(width, bodyRows + wrapSection(footer, inner).length + 8, title, "", [], prose, [], footer);
+}
+
 export function selectorCompactRow(
 	content: string,
 	selected = false,
@@ -401,8 +418,46 @@ export class ReportDetailsComponent extends Container {
 	}
 }
 
+/** Reusable viewport for complete selected prose without changing the selected item. */
+export class SelectorDetailPager {
+	#offset = 0;
+	#capacity = 1;
+	#length = 0;
+	#source = "";
+
+	reset(): void {
+		this.#offset = 0;
+	}
+
+	render(text: string[], width: number, capacity: number): string[] {
+		const source = text.join("\n");
+		if (source !== this.#source) this.reset();
+		this.#source = source;
+		const lines = wrapSection(text, width);
+		this.#length = lines.length;
+		this.#capacity = Math.max(1, capacity);
+		this.#offset = Math.min(this.#offset, Math.max(0, lines.length - this.#capacity));
+		return lines.slice(this.#offset, this.#offset + this.#capacity);
+	}
+
+	page(direction: -1 | 1): boolean {
+		if (this.#length <= this.#capacity) return false;
+		this.#offset = Math.max(0, Math.min(this.#length - this.#capacity, this.#offset + direction * this.#capacity));
+		return true;
+	}
+
+	get hint(): string[] {
+		return this.#length > this.#capacity
+			? [
+					`${selectorKeys("pageUp")}/${selectorKeys("pageDown")}: details ${this.#offset + 1}–${Math.min(this.#length, this.#offset + this.#capacity)} of ${this.#length}`,
+				]
+			: [];
+	}
+}
+
 export class ConnectionChoiceComponent extends Container {
 	#selected = 0;
+	#details = new SelectorDetailPager();
 	constructor(
 		private title: string,
 		private purpose: string,
@@ -415,19 +470,32 @@ export class ConnectionChoiceComponent extends Container {
 	}
 	override render(width: number): string[] {
 		const contentWidth = selectorFrameContentWidth(width);
+		const rows = this.rows();
+		const choice = this.choices[this.#selected];
+		const details = this.#details.render(
+			[
+				...(wrapSection([this.purpose], contentWidth).length > 2 ? [this.purpose] : []),
+				choice?.label ?? "",
+				choice?.description ?? "",
+			],
+			contentWidth,
+			Math.max(1, Math.floor(rows / 5)),
+		);
 		return selectorFrame(
 			width,
-			this.rows(),
+			rows,
 			this.title,
 			this.purpose,
 			[],
 			this.choices.map((choice, index) => selectorRow([choice.label], [contentWidth - 2], index === this.#selected)),
-			[this.choices[this.#selected]?.description ?? ""],
-			[selectorNavigationHint(), selectorCancelHint()],
-			{ selectedBodyIndex: this.#selected },
+			details,
+			[selectorNavigationHint(), selectorCancelHint(), ...this.#details.hint],
+			{ selectedBodyIndex: this.#selected, selectedDetail: "provided" },
 		);
 	}
 	handleInput(data: string): void {
+		if (matchesSelectorKey(data, "pageUp") && this.#details.page(-1)) return;
+		if (matchesSelectorKey(data, "pageDown") && this.#details.page(1)) return;
 		if (matchesSelectorKey(data, "cancel")) this.onCancel();
 		else if (matchesSelectorKey(data, "up"))
 			this.#selected = (this.#selected - 1 + this.choices.length) % this.choices.length;

package/src/modes/components/transcript-notice.ts

@@ -1,5 +1,10 @@
 import { type Component, Container } from "@f5-sales-demo/pi-tui";
-import { selectorCompactRow, selectorFrame, selectorFrameContentWidth, selectorProse } from "./selector-frame";
+import {
+	selectorCompactRow,
+	selectorFrameContentWidth,
+	selectorProse,
+	selectorTranscriptFrame,
+} from "./selector-frame";
 
 /** Frame arbitrary static transcript-adjacent content, including OSC links. */
 export class TranscriptComponentFrame extends Container {
@@ -14,18 +19,12 @@ export class TranscriptComponentFrame extends Container {
 
 	override render(width: number): string[] {
 		const body = this.content.render(selectorFrameContentWidth(width));
-		return selectorFrame(
+		return selectorTranscriptFrame(
 			width,
-			body.length + this.footer.length + 7,
 			this.title,
 			this.purpose,
-			[],
 			body.map(line => selectorCompactRow(line)),
-			[],
 			this.footer,
-			{
-				maxBodyRows: Math.max(1, body.length),
-			},
 		);
 	}
 }
@@ -42,18 +41,11 @@ export class TranscriptNoticeComponent extends Container {
 
 	override render(width: number): string[] {
 		const body = this.content.split("\n").filter(line => Bun.stripANSI(line).trim());
-		return selectorFrame(
+		return selectorTranscriptFrame(
 			width,
-			body.length + 7,
 			this.title,
 			this.purpose,
-			[],
 			body.map(line => selectorProse(line)),
-			[],
-			[],
-			{
-				maxBodyRows: Math.max(1, body.length),
-			},
 		);
 	}
 }