@f5-sales-demo/xcsh 22.4.7 → 22.4.8

package/src/internal-urls/api-spec-resolve.ts

@@ -393,9 +393,8 @@ function renderDomainDetail(domain: string, entry: ApiSpecDomainEntry, spec: Ope
 	if (entry.cliMetadata?.quickStart?.command) {
 		const cli = entry.cliMetadata;
 		sections.push("", "## CLI Quick Start", "");
-		// Never surface a deprecated CLI (e.g. vesctl) or raw curl against the F5 XC
-		// API as an instruction — even if the upstream spec carries one. Substitute
-		// xcsh-native guidance instead.
+		// Filter deprecated CLIs (e.g. vesctl) while preserving supported curl examples.
+		// Substitute xcsh-native guidance for deprecated commands only.
 		if (isDisallowedCliCommand(cli.quickStart.command)) {
 			sections.push(`${cli.quickStart.description} — ${XCSH_NATIVE_API_GUIDANCE}`);
 		} else {

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

@@ -17,17 +17,17 @@ export interface BuildInfo {
 }
 
 export const BUILD_INFO: BuildInfo = {
-	"version": "22.4.7",
-	"commit": "180856c33d8a793f403341e0f8688c09c683a553",
-	"shortCommit": "180856c",
+	"version": "22.4.8",
+	"commit": "11f58262229b820d744a2007597c8b0183df9bad",
+	"shortCommit": "11f5826",
 	"branch": "main",
-	"tag": "v22.4.7",
-	"commitDate": "2026-09-30T01:36:22-04:00",
-	"buildDate": "2026-09-30T06:22:56.746Z",
+	"tag": "v22.4.8",
+	"commitDate": "2026-09-30T06:21:51Z",
+	"buildDate": "2026-09-30T06:59:02.863Z",
 	"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/180856c33d8a793f403341e0f8688c09c683a553",
-	"releaseUrl": "https://github.com/f5-sales-demo/xcsh/releases/tag/v22.4.7"
+	"commitUrl": "https://github.com/f5-sales-demo/xcsh/commit/11f58262229b820d744a2007597c8b0183df9bad",
+	"releaseUrl": "https://github.com/f5-sales-demo/xcsh/releases/tag/v22.4.8"
 };

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

@@ -10,7 +10,7 @@ export const EMBEDDED_DOCS: Readonly<Record<string, string>> = {
 	"en/architecture-contribution/native-development.mdx": "---\ntitle: \"Develop the native layer\"\ndescription: \"Choose native work deliberately, add a binding, build variants, test cancellation, and debug loader failures.\"\nsidebar:\n  order: 7\n  label: \"Native development\"\n---\n\nPort code to Rust only for measured performance, platform integration, or resource-control needs. Keep orchestration and product policy in TypeScript.\n\n## How do I add or change a native export?\n\nDefine the Rust implementation and Node-application programming interface (API) signature, expose it from the Rust package, update TypeScript declarations and wrappers, then extend validation and contract tests. Preserve the JavaScript fallback when the public contract requires one; otherwise fail explicitly when the addon is unavailable.\n\n## How do I build target variants?\n\nThe build pipeline selects target triples and optional hardware variants, compiles release artifacts, and packages names the loader can resolve. Environment flags affect the build target or diagnostics, not the public API. Test the ordinary target plus any variant whose resolution order changed.\n\n## How do I diagnose loading and cancellation?\n\nStart with the resolved candidate list, platform identity, file permissions, and `validateNative` mismatch. For asynchronous work, test cancellation before start, during execution, and after completion; a cancellation token must never resolve the same task twice.\n\nChange `crates/pi-natives/src` and `packages/natives` together; a signature that exists on only one side fails at load rather than at build.\n\nBuild from the repository root with `bun scripts/ensure-dev-native.ts`, then run the focused\nTypeScript contract test in a fresh process so the loader cannot reuse an already loaded addon.\nInspect `git status --short` afterward: generated binaries and target directories are build\nproducts, not source changes. If the test fails, compare the exported Rust symbol, generated\nbinding, wrapper name, and packaged filename before changing loader fallback behavior.\n",
 	"en/architecture-contribution/native-runtime.mdx": "---\ntitle: \"Native runtime architecture\"\ndescription: \"Understand TypeScript wrappers, addon loading, Rust Node-API exports, binary selection, and binding validation.\"\nsidebar:\n  order: 6\n  label: \"Native runtime\"\n---\n\nThe public TypeScript layer owns ergonomic types and fallbacks. The loader selects a platform-specific addon, validates its exports, and exposes Rust Node-application programming interface (API) implementations for performance-sensitive work.\n\n## How is an addon selected and validated?\n\nResolution considers operating system, CPU architecture, and supported hardware variants before trying packaged and extracted binary candidates. Embedded binaries are materialized in a controlled cache. `validateNative` checks the runtime surface so a mismatched binary fails near loading instead of at an unrelated call.\n\n## How do I keep bindings synchronized?\n\nModule augmentation describes native exports to TypeScript, wrappers translate public inputs and outputs, and Rust functions implement the Node-API boundary. Synchronous and asynchronous variants must agree on names, data conversions, error shapes, and cancellation. Update all three layers and their contract tests together.\n\n## Which subsystems does the addon cover?\n\nThe addon covers terminal and pseudo-terminal (PTY) processes, filesystem scanning and text search, media/system utilities, and cancellable task primitives. Data crossing Node-API must have an explicit encoding and ownership rule; native tasks must release resources on both completion and cancellation.\n\n`PowerAssertion.start(options?)` returns an idempotently stoppable session handle. Its\n`PowerAssertionOptions` fields are `reason`, `idle`, `display`, `system`, and `user`; an omitted set\nof mode flags defaults to idle-sleep prevention. The implementation uses IOKit on macOS, login1\nand best-effort ScreenSaver inhibition on Linux, and a dedicated execution-state thread on Windows.\n\nRead `packages/natives` for the TypeScript wrappers and loader, and `crates/pi-natives/src` for the Rust implementations.\n\nAddon selection is a trust boundary: the loader accepts only a candidate for the current operating\nsystem, architecture, and declared variant, then validates the complete export surface. A missing or\nmismatched export is a startup error, not permission to mix binaries from another build. For\ndiagnosis, record the selected candidate and host tuple, rebuild with `bun\nscripts/ensure-dev-native.ts`, and repeat the validation in a new process.\n",
 	"en/architecture-contribution/parallelism-qualification.mdx": "---\ntitle: \"File-test parallelism qualification\"\ndescription: \"Expand bounded Bun file-test parallelism without leaving workflow and harness contracts out of sync.\"\nsidebar:\n  order: 11\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\n## Purpose\n\nUse this guide when qualifying a new bounded Bun file-worker count on the D16\ncandidate runner. A worker count is a contract that crosses the workflow, the\nprofile harness, the TypeScript test launcher, and their tests. Update every\ncontract in one change before dispatching a sample.\n\nUse `<WORKER_COUNT>` below for the proposed count, such as `10`. Keep the\nexperiment name and count paired: `d16-parallel-<WORKER_COUNT>` must always\nmap to `<WORKER_COUNT>`.\n\n## Required changes\n\n| Boundary | File | Required change |\n| --- | --- | --- |\n| Dispatch input | `.github/workflows/compute-benchmark.yml` | Add `d16-parallel-<WORKER_COUNT>` to `workflow_dispatch.inputs.experiment.options`. |\n| Candidate route | `.github/workflows/compute-benchmark.yml` | Add the experiment to the D16 candidate route allowlist. This keeps the D16 image and runner label selected. |\n| Worker mapping | `.github/workflows/compute-benchmark.yml` | Add `d16-parallel-<WORKER_COUNT>) file_workers=<WORKER_COUNT> ;;`. |\n| Setup profile | `scripts/prepare-runner-optimization-toolchain.sh` | Add the experiment to the accepted experiment allowlist. |\n| Workload profile | `scripts/runner-optimization-profile.sh` | Update the usage text, accepted experiment list, accepted worker-count list, exact experiment-to-worker pairing, and serial-only guard. |\n| TypeScript launcher | `scripts/run-ts-tests.ts` | Add the count to `FileWorkers`, the accepted raw values, and the error message. This is the code that converts the count to `--parallel=<WORKER_COUNT>`. |\n| Direct launcher test | `packages/coding-agent/test/scripts/run-ts-tests.test.ts` | Cover the new accepted count and retain rejection coverage for unsupported values. |\n| Workflow contracts | `tests/test_ci_capacity_contract.py` and `packages/coding-agent/test/scripts/arc-runner-workflow-contract.test.ts` | Update exact route assertions so workflow and harness drift fail locally. |\n\nThe performance-qualification evaluator is parameterized by the candidate\nvariant. It does not need a new hardcoded worker count; invoke it with the new\ncandidate variant when evaluating collected artifacts.\n\n### Source and harness must agree\n\nThe qualification workflow checks out the workload source at its frozen source\nrevision and checks out the qualification harness separately at the workflow\nrevision. Some package test scripts import `scripts/run-ts-tests.ts` from the\nfrozen source rather than from the harness. Therefore, a harness-only worker\ncount change is insufficient: a package can reject the count even though the\nharness accepts it.\n\nBefore screening a new count, create a deliberately refrozen source revision\nthat includes the TypeScript launcher and direct-test changes above. Record the\nnew source revision, keep it fixed for every sample in that screen, and collect\na new serial baseline from that same source. Do not compare that screen to a\nbaseline produced from the preceding frozen source revision.\n\n## Bounded implementation pattern\n\nThe following relationships must all be true for a candidate named\n`d16-parallel-<WORKER_COUNT>`:\n\n```text\nworkflow choice\n  -> D16 candidate route\n  -> file_workers=<WORKER_COUNT>\n  -> profile allowlist and exact pair\n  -> FileWorkers accepts <WORKER_COUNT>\n  -> bun ... --max-concurrency=2 --parallel=<WORKER_COUNT>\n```\n\nDo not add a broad numeric range or an unbounded mode. Each count is explicitly\nqualified so a future change cannot silently alter CI scheduling.\n\n## Preflight before dispatch\n\nRun these checks after all files above are updated and before a candidate\nworkload is dispatched:\n\n```bash\nactionlint .github/workflows/compute-benchmark.yml\nbash -n scripts/runner-optimization-profile.sh scripts/prepare-runner-optimization-toolchain.sh\npython3 -m unittest tests.test_ci_capacity_contract\nbun test packages/coding-agent/test/scripts/run-ts-tests.test.ts\nbun test packages/coding-agent/test/scripts/arc-runner-workflow-contract.test.ts\n```\n\nIf the worktree does not have Bun workspace dependencies, install them with\n`bun install --frozen-lockfile` before treating a TypeScript test startup error\nas a source failure. Do not substitute npm, Yarn, or pnpm.\n\nBefore dispatching, confirm that the candidate ARC pool has zero current and\npending runners. Dispatch one matched sample at a time and record the run ID at\ndispatch.\n\n## Settings that remain fixed during a screen\n\nChanging any of these changes the experiment rather than merely increasing\nfile-test parallelism:\n\n- Keep the frozen source revision and immutable runner image unchanged.\n- Keep the D16 candidate runner class, ARC pool, `min=0`, and `max=1`.\n- Keep `--max-concurrency=2`.\n- Never add Bun `--concurrent`.\n- Keep one candidate workload active at a time.\n- Keep serial production CI at `XCSH_TEST_FILE_WORKERS: \"0\"` until the\n  qualification gates pass.\n\n## Failure signatures and the missing contract\n\n| Failure point | Likely missing update |\n| --- | --- |\n| `Validate bounded experiment` exits with code 2 | The workflow experiment is absent from the D16 candidate route allowlist. |\n| `Profile legacy setup or baked verification` prints its usage line | The setup-profile experiment allowlist is missing the candidate. |\n| `Profile workload phases` rejects the worker value | The workload-profile accepted count or exact experiment-to-worker pair is missing. |\n| `run-ts-tests.ts` says the worker count is unsupported | `FileWorkers` and its parsed string allowlist were not updated. |\n| Exact-string workflow contract test fails | Update its expected D16 candidate route only after the workflow route is intentionally changed. |\n\nResolve the missing contract, run the focused preflight again, and then rerun\nonly the failed sample. Do not infer a benchmark result from setup-only runs.\n\n## Promotion boundary\n\nQualification changes only make a candidate runnable. They do not change normal\nCI. Promote a count only after matched artifact evidence demonstrates expected\noutput, no failures, no OOMs or evictions, memory below the defined threshold,\nnon-regressing p95, and the required median TypeScript improvement.\n\nThe production change is intentionally separate:\n\n1. Change `.github/workflows/ci.yml` from `XCSH_TEST_FILE_WORKERS: \"0\"` to\n   the chosen qualified value.\n2. Update the serial-default assertion in `tests/test_ci_capacity_contract.py`.\n3. Run the focused contracts and an ordinary CI verification after merge.\n\nIf ordinary CI becomes unstable or regresses unacceptably, restore\n`XCSH_TEST_FILE_WORKERS: \"0\"`.\n",
-	"en/architecture-contribution/prompt-authoring.mdx": "---\ntitle: \"Author system prompts\"\ndescription: \"Apply the system-prompt checklist, progressive composition, deduplication, and audit tests.\"\nsidebar:\n  order: 10\n  label: \"Prompt authoring\"\n---\n\nSystem prompts are executable product policy. Edit the smallest owned prompt fragment and verify the composed result; do not paste a second copy of guidance already supplied by a capability or plugin.\n\n## What does the eight-point checklist require?\n\nState role and scope, concrete objectives, available tools, tool-use rules, constraints, output contract, uncertainty behavior, and completion criteria. Use direct instructions with observable conditions. Keep provider-specific details out of shared prompts unless the adapter cannot represent them elsewhere.\n\n## How is the system prompt composed?\n\nThe runtime builds the system prompt from the core fragment plus active capabilities, workspace guidance, plan state, memory, and extension contributions. Ordering and deduplication tests protect mandatory boundaries. An absent optional plugin must not remove core safety or file-operation instructions.\n\n## How do I audit a prompt change?\n\nInspect the final composed prompt for representative capability sets, then run the template, application programming interface (API) spec, deduplication, deprecation, workspace-boundary, start-folder, and absent-plugin tests.\n\nRecord why each new sentence belongs at that layer, and remove a stale alias rather than documenting both paths.\n\nRead `packages/coding-agent/src/prompts` for the composed fragments and their ordering tests.\n\nTreat the composed prompt, not an individual fragment, as the review artifact. Compare\nrepresentative runs with and without the capability that contributes the fragment, and verify that\nrequired instructions occur once and in the intended order. Prompt text can change model behavior\nwithout changing TypeScript types, so a passing build is insufficient; retain a focused composition\nassertion and an end-to-end behavior test for the policy being changed.\n",
+	"en/architecture-contribution/prompt-authoring.mdx": "---\ntitle: \"Author system prompts\"\ndescription: \"Apply the system-prompt checklist, progressive composition, deduplication, and audit tests.\"\nsidebar:\n  order: 10\n  label: \"Prompt authoring\"\n---\n\nSystem prompts are executable product policy. Edit the smallest owned prompt fragment and verify the composed result; do not paste a second copy of guidance already supplied by a capability or plugin.\n\n## What does the eight-point checklist require?\n\nState role and scope, concrete objectives, available tools, tool-use rules, constraints, output contract, uncertainty behavior, and completion criteria. Use direct instructions with observable conditions. Keep provider-specific details out of shared prompts unless the adapter cannot represent them elsewhere.\n\n## How is the system prompt composed?\n\nThe runtime builds the system prompt from the core fragment plus active capabilities, workspace guidance, plan state, memory, and extension contributions. Ordering and deduplication tests protect mandatory boundaries. An absent optional plugin must not remove core safety or file-operation instructions.\n\n## How do I audit a prompt change?\n\nInspect the final composed prompt for representative capability sets, then run the template, application programming interface (API) spec, deduplication, deprecation, workspace-boundary, start-folder, and absent-plugin tests.\n\nRecord why each new sentence belongs at that layer, and remove a stale alias rather than documenting both paths.\n\nRead `packages/coding-agent/src/prompts` for the composed fragments and their ordering tests.\n\nTreat the composed prompt, not an individual fragment, as the review artifact. Compare\nrepresentative runs with and without the capability that contributes the fragment, and verify that\nrequired instructions occur once and in the intended order. Prompt text can change model behavior\nwithout changing TypeScript types, so a passing build is insufficient; retain a focused composition\nassertion and an end-to-end behavior test for the policy being changed.\n\n## How should API examples differ from execution?\n\nPrefer `xcsh_api` for F5 Distributed Cloud API execution. Requested cURL examples belong in explanations,\ndocumentation, and scripts. Generating an example does not authorize execution: example-only requests must not\nperform resource discovery, creation, updates, or deletion. An explicit request to execute cURL uses the existing\nshell tool and context, credential, approval, and execution controls, after verifying the effective target.\n\nGround examples in embedded catalog methods and paths and API-spec payload schemas. Use quoted\n`\"$XCSH_API_URL/api/...\"` and `\"Authorization: APIToken $XCSH_API_TOKEN\"`; explain the API base URL and token\nvariables without displaying their values. Match the documented method, substituted path parameters, Content-Type,\nand valid JSON payload. Keep minimum-configuration reads compact and synthesize cURL only when requested.\nDeprecated commands such as `vesctl` remain filtered.\n\nThe shared `api-curl-guidance.md` fragment survives eager, progressive, custom, and transformed prompt composition.\nScope native discovery and deletion instructions to default execution requests, and retain tests for both\nexample-only behavior and explicit execution through the shell path.\n",
 	"en/architecture-contribution/provider-streaming.mdx": "---\ntitle: \"Provider streaming\"\ndescription: \"Follow provider events through normalized assistant messages, tool JSON accumulation, cancellation, and fallback.\"\nsidebar:\n  order: 4\n  label: \"Provider streaming\"\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\nProvider adapters translate distinct wire events into one `AssistantMessageEvent` stream consumed by the agent loop. Text deltas, reasoning, tool starts, tool arguments, completion, usage, and errors retain their meaning across adapters.\n\n```text\nprovider wire events        adapter                      agent loop\n  text delta          ->  text delta               ->  append to message\n  reasoning delta     ->  reasoning delta          ->  append to message\n  tool start          ->  buffer call id\n  tool arg fragment   ->  accumulate JSON          (no event yet)\n  tool arg complete   ->  tool request             ->  dispatch tool\n  usage               ->  usage                    ->  account tokens\n  error or cancel     ->  terminal settle (once)   ->  stop the turn\n```\n\n## How are tool calls normalized incrementally?\n\nTool arguments can arrive as JavaScript Object Notation (JSON) fragments. The adapter accumulates fragments per call identifier and emits a tool request only after a complete valid value exists. Parse failure remains an error with provider context; silently truncating or inventing arguments would cross the provider boundary.\n\n## How does a stream cancel and finish exactly once?\n\nCancellation propagates to the active provider request and prevents later deltas from reopening the turn. A terminal success, cancellation, or error settles the stream once. Retry and model fallback happen above normalization so an adapter does not conceal which provider produced an event.\n\nRead `packages/ai/src/stream.ts` for the normalized event stream and `packages/ai/src/providers` for the per-vendor adapters.\n\nThe adapter may buffer incomplete tool arguments, but it must not execute them or expose them as a\ncomplete call. Once a terminal event wins, later provider frames are ignored and cleanup still runs.\nTest a normal text turn, fragmented tool JSON, malformed JSON, caller cancellation, provider error,\nand a late event after settlement. The final session record should identify the actual provider and\nretain the error or cancellation boundary.\n",
 	"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",

package/src/prompts/system/api-curl-guidance.md

@@ -0,0 +1,5 @@
+Prefer `xcsh_api` when executing F5 Distributed Cloud API operations. Provide accurate cURL examples when requested, including in explanations, documentation, and scripts. Generating an example does not authorize executing it. Example-only requests must not trigger resource operations, including discovery or deletion.
+
+Ground cURL examples in the embedded `xcsh://api-catalog/` method/path evidence and `xcsh://api-spec/` payload schemas. Never guess endpoints or fields. Use the read tool for catalog and schema evidence; follow continuation selectors or bounded field/CRUD projections when content is long. Do not use the shell to inspect API metadata for example-only requests. Use quoted environment variables such as `"$XCSH_API_URL/api/…"` and `"Authorization: APIToken $XCSH_API_TOKEN"`. Explain that `XCSH_API_URL` is the tenant API base URL and `XCSH_API_TOKEN` is the API token; never print credential values. Substitute path parameters and use valid JSON with the documented Content-Type for request bodies.
+
+When the user explicitly requests cURL execution, use the shell tool within the existing context, credential, approval, and execution controls. Verify the effective target and any requested context selection before executing; failed or cancelled context selection must stop the request. Use the existing credential environment without exposing or inventing credentials. Native discovery and deletion requirements apply to default execution requests; explicitly requested cURL execution follows the shell path.

package/src/prompts/system/progressive-system-prompt.md

@@ -15,7 +15,8 @@ or production systems or use real user data.
   changes and supported current interfaces. Verify actual behavior and report evidence concisely.
 - Do not claim access, results, or completion you did not verify. Separate fact, inference, and uncertainty.
 - Use schema-first F5 XC operations: inspect `xcsh://api-spec/` for fields and `xcsh://api-catalog/` for operations;
-  use `xcsh_api` for execution. Read before mutate, avoid guessing paths or payloads, and re-read after mutation.
+  prefer `xcsh_api` for default execution. Follow the shared cURL guidance for examples and explicit cURL execution.
+  Avoid guessing paths or payloads. Read the target before updates; a successful mutation response verifies the effect.
 - For repositories, follow the nearest instructions and contribution workflow. Read `xcsh://fleet` before changing
   an F5 fleet repository. Never commit directly to a protected default branch.
 - Final responses lead with the outcome, name material changes, and include the checks proving it.

package/src/prompts/system/system-prompt.md

@@ -400,17 +400,17 @@ Set a session-wide default with `set_presentation_profile`.
   Conceptual F5 XC questions remain documentation-first through the pinned offline snapshot.
   Conceptual, product, operational, and support questions route through `xcsh://documentation/` first.
 
-  When the user needs to **make an API call** (create, read, update, delete):
+  For default execution requests, when the user needs to **make an API call** (create, read, update, delete):
   1. `xcsh://api-catalog/?resource={resource_name}&compact=true` → get endpoint path, method,
      minimum payload JSON, OneOf recommendations, and response summary
   2. Call `xcsh_api` tool with `method`, `path`, `params` (all `{placeholder}` substitutions), and `payload`
 
-  When the resource type and required parameters are clear, your first output
+  For these default execution requests, when the resource type and required parameters are clear, your first output
   **MUST** be the catalog tool call — do not preface with explanation or deliberation.
   If required parameters (e.g., namespace) are ambiguous, ask first.
 
   The `xcsh_api` tool handles authentication, URL construction, and HTTP execution.
-  Never construct cURL commands for F5 XC API calls — use `xcsh_api` instead.
+  Prefer `xcsh_api` for default execution. Follow the shared cURL guidance for requested examples or explicit cURL execution.
 
   **CLI portability:** Prefer broadly supported flags and output fields. Before using version-specific diagnostics, inspect the installed tool version or help. If an optional diagnostic field is unsupported (for example cURL 8.7.1 does not provide ssl_cipher), retry without that field while preserving and reporting the underlying command result. Do not add command interception layers or tool-specific compatibility shims.
 
@@ -421,7 +421,7 @@ Set a session-wide default with `set_presentation_profile`.
   For xcsh_api mutations, the 200 response satisfies the "verify the effect" requirement — do not GET the resource again.
   For CREATE, you **MUST NOT** GET referenced dependencies (origin pools, firewalls) to verify they exist — include them by name. For UPDATE, GET the target resource for its current spec, but you **MUST NOT** GET other referenced resources.
 
-  **Namespace discovery** — when the user asks what resources exist in a namespace
+  **Namespace discovery** — for default execution requests, when the user asks what resources exist in a namespace
   (e.g. "what's in my namespace", "list everything configured", "show all resources"),
   you **MUST** call `xcsh_api` with `method: "GET"`, `paths: ["*"]`.
   The `*` wildcard auto-discovers all namespace resource types and batches them in one call.

package/src/prompts/tools/xcsh-api.md

@@ -1,5 +1,7 @@
 Execute an F5 Distributed Cloud API call directly.
 
+Prefer this tool for default execution. Example-only requests must not trigger resource operations. Use catalog/schema evidence for cURL examples and the shell for explicitly requested cURL execution under existing controls.
+
 Handles authentication, URL construction, and HTTP execution.
 Credentials are resolved from the active context profile (`/context`). Environment variables
 `XCSH_API_URL` and `XCSH_API_TOKEN` override context values when set.
@@ -26,13 +28,13 @@ Response format:
 **Error**: `{"code": <int>, "message": "…"}` — codes: 3=INVALID_ARGUMENT, 5=NOT_FOUND, 6=ALREADY_EXISTS, 7=PERMISSION_DENIED, 13=INTERNAL.
 GET requests auto-retry once on transient errors (429/503) after 1s backoff. POST/PUT/DELETE are never retried.
 API calls to the same F5 XC tenant reuse a single TLS connection — sequential calls are faster than parallel calls.
-**Namespace discovery**: When asked about resources in a namespace, you **MUST** use `paths: ["*"]` to auto-discover and batch all namespace resource types in ONE call. Do NOT enumerate types individually.
+**Namespace discovery**: For default execution requests, when asked about resources in a namespace, you **MUST** use `paths: ["*"]` to auto-discover and batch all namespace resource types in ONE call. Do NOT enumerate types individually.
 Preserve the exact confirmed-member total and the labels `External-visible results` and `Unknown-scope results` in the final answer. External-visible and unknown-scope items are not namespace members and must not be described as owned or mutation-valid.
 
 **Relationship queries**: When the batch response includes a `Resource summary:` section, the specs and relationships for confirmed namespace members in that section are already fetched. Answer directly from that evidence. Do NOT make additional GET calls to read those individual resources again. External-visible and unknown-scope count summaries are not membership, ownership, or mutation-safety evidence.
-**Tenant-wide queries**: When asked about resources across ALL namespaces (e.g. "show all LBs in the entire tenant"), use `paths: ["*"]` with `params: {namespace: "*"}` to batch every namespace in ONE call. Do NOT list namespaces first — the wildcard handles discovery automatically.
+**Tenant-wide queries**: For default execution requests, when asked about resources across ALL namespaces (e.g. "show all LBs in the entire tenant"), use `paths: ["*"]` with `params: {namespace: "*"}` to batch every namespace in ONE call. Do NOT list namespaces first — the wildcard handles discovery automatically.
 
-**Deleting resources** — when asked to delete, remove, or destroy an F5 XC resource, you **MUST** call `xcsh_api`
+**Deleting resources** — For default execution requests, when asked to delete, remove, or destroy an F5 XC resource, you **MUST** call `xcsh_api`
 with `method: "DELETE"` and `path` set to the resource's API endpoint including the resource name, e.g. `DELETE
 /api/config/namespaces/{namespace}/http_loadbalancers/{name}`. Pass `namespace` and `name` via `params`. No `payload`
 is needed for standard deletes. Do NOT respond with explanatory text instead of making the DELETE call — execute the