@robota-sdk/agent-framework 3.0.0-beta.78 → 3.0.0-beta.81

package/README.md

@@ -1,5 +1,10 @@
 # @robota-sdk/agent-framework
 
+Runtime hosts are owned by this package: import `createHeadlessTransport`,
+`HeadlessInteractionChannel`, `createProgrammaticAgent`, `ProgrammaticInteractionChannel`,
+`TransportRegistry`, and its file/memory settings repositories from the root. Their implementation
+lives in `src/transport-host/`; terminal `PrintTerminal` and `promptInput` are local to the CLI.
+
 Programmatic SDK for building AI agents with Robota. Provides `InteractiveSession` as the central client-facing API, `createQuery()` for one-shot use, `createAgentRuntime()` as a composition factory for headless and multi-session consumers, session management, SDK-owned command/common APIs, permissions, hooks, streaming, context loading, bounded prompt file references, and context reference inventory.
 
 This is the **assembly layer** of the Robota ecosystem — it composes lower-level packages (`agent-core`, `agent-tools`, `agent-session`, `agent-provider`) into a cohesive SDK.
@@ -16,7 +21,7 @@ pnpm add @robota-sdk/agent-framework
 
 ```typescript
 import { createQuery } from '@robota-sdk/agent-framework';
-import { AnthropicProvider } from '@robota-sdk/agent-provider/anthropic';
+import { AnthropicProvider } from '@robota-sdk/agent-provider-anthropic';
 
 const provider = new AnthropicProvider({ apiKey: process.env.ANTHROPIC_API_KEY });
 const query = createQuery({ provider });
@@ -28,6 +33,8 @@ const response = await query('Show me the file list');
 const queryWithOptions = createQuery({
   provider,
   cwd: '/path/to/project',
+  // A bare cwd is provenance only. Pass a host-issued TWorkspaceProjectAccess decision
+  // when this query may consume project context or settings.
   permissionMode: 'acceptEdits',
   maxTurns: 10,
   onTextDelta: (delta) => process.stdout.write(delta),
@@ -44,7 +51,7 @@ store, transports):
 
 ```typescript
 import { createAgentRuntime } from '@robota-sdk/agent-framework';
-import { AnthropicProvider } from '@robota-sdk/agent-provider/anthropic';
+import { AnthropicProvider } from '@robota-sdk/agent-provider-anthropic';
 
 const runtime = createAgentRuntime({
   cwd: process.cwd(),
@@ -55,31 +62,81 @@ const runtime = createAgentRuntime({
 const session = runtime.createSession({});
 ```
 
+Without `projectAccess`, the runtime exposes an observable Restricted decision and does not construct
+project context, settings, memory, session, or log adapters. A host that has inspected or granted a
+workspace through `WorkspaceTrustService` passes that exact `TWorkspaceProjectAccess` decision.
+Project persistence is then composed explicitly from its named state facets; a bare `cwd` never
+creates a project store. A per-session `sessionStore` replaces the runtime store, while an explicit
+`sessionStore: undefined` disables persistence. Trusted runtime/query construction accepts the frozen
+workspace root and its real descendants while rejecting a working directory outside that identity; a
+completed revoke makes the previously issued authority and all of its facets unusable. Explicit host
+contribution sources also remain root-bounded and refuse links at every path component.
+
+Authority-backed project mutations share one stable-root boundary: on Linux, open root and parent
+directory descriptors prevent parent renames or symlink swaps from redirecting writes, replacements,
+appends, or deletes. Hosts without equivalent stable handle semantics fail closed with
+`WorkspaceAuthorityRequiredError` instead of falling back to pathname mutation.
+
+Replay-only project recovery validates the versioned JSONL before reconstructing a session. Loads and
+listings report malformed logs as `corrupt` and unsupported versions as `unsupported`, rather than
+hiding them as missing sessions. Snapshot encoding is unchanged; unversioned legacy logs are not replayed.
+
+The maintained offline examples verify explicit persist→resume composition and the workspace
+authority boundary with no provider credentials:
+
+```bash
+pnpm --filter @robota-sdk/agent-framework scenario:verify
+```
+
+### Runtime host (`robota --serve`)
+
+`buildRuntimeSession()` is the single session-construction seam: every presentation — the TUI channel
+and the headless `robota --serve` entry — builds its `InteractiveSession` from resolved options through
+it, instead of calling `new InteractiveSession` directly. `startRuntimeHost()` adds the transport
+`startAll`/`stopAll` lifecycle plus a bounded shutdown handle on top, and is used by the headless
+`--serve` path (which the desktop GUI spawns as a loopback-WS sidecar). It lives in `agent-framework`,
+not the product shell — it takes already-resolved options and is presentation-neutral (RUNTIME-001).
+
+```typescript
+import { startRuntimeHost } from '@robota-sdk/agent-framework';
+import type { IRuntimeHostOptions, IRuntimeHostHandle } from '@robota-sdk/agent-framework';
+
+// `session` holds the resolved session options; `transportRegistry` is the loopback WS sidecar.
+declare const options: IRuntimeHostOptions;
+const host: IRuntimeHostHandle = await startRuntimeHost(options);
+// host.session — the live runtime session every presentation drives
+// await host.shutdown() — bounded transport teardown + session shutdown
+```
+
 ## Features
 
 - **InteractiveSession** — Event-driven session wrapper (composition over Session). Central client-facing API for CLI, web, API server, or any other client
 - **SystemCommandExecutor + ISystemCommand** — SDK-level command execution infrastructure for product-composed command modules
 - **CommandRegistry, BuiltinCommandSource, SkillCommandSource** — Command registry and SDK common discovery APIs. User-visible built-ins are composed through `agent-command` packages.
 - **Model Command Common APIs** — Provider-neutral `/model` helpers that resolve active provider catalogs and optionally invoke provider-owned refresh hooks
+- **Model effort selection** — A typed provider-neutral selection record and command-host adapter keep source and provisional display state consistent across startup, live commands, and headless output; `auto` remains unpinned until the provider adapter reports its outcome
 - **createQuery()** — Provider-bound factory for one-shot AI agent interactions with streaming support
+- **Runtime host (RUNTIME-001)** — `startRuntimeHost()` builds and serves a headless session over a loopback WS (used by `robota --serve` and the desktop GUI sidecar); `buildRuntimeSession()` is the shared session-construction seam every presentation builds its `InteractiveSession` through
 - **Session assembly** — Internal factory wires tools, provider, config, and context for `InteractiveSession`
-- **Built-in Tools** — Bash, Read, Write, Edit, Glob, Grep, WebFetch, WebSearch are assembled for SDK sessions; direct tool usage imports from `@robota-sdk/agent-tools`
+- **Built-in Tools** — Shell/Bash, Read, Write, Edit, Glob, Grep, WebFetch, WebSearch, AskUserQuestion are assembled for SDK sessions. The set itself lives in `@robota-sdk/agent-tool-defaults` (a composition leaf, ARCH-035) and is loaded lazily; import it from there to compose your own tier, or `@robota-sdk/agent-tools` for individual tools
 - **Sandbox Execution** — Optional `sandboxClient` injection routes Bash and core file tools through a provider-backed execution plane; `workspaceManifest` can prepare a fresh sandbox workspace before session creation
 - **Sandbox Hydration** — Snapshot-capable sandbox clients persist `sandboxSnapshotId` on shutdown and restore it before saved message replay on non-fork resume
 - **Agent Tool** — Sub-agent session creation for multi-agent workflows
-- **Permissions** — 3-step evaluation (deny list, allow list, mode policy) with four modes: `plan`, `default`, `acceptEdits`, `bypassPermissions`
+- **Permissions** — one evaluation order for every caller (deny, ask and allow lists, never-auto-approved calls, mode policy) with four modes: `plan`, `default`, `acceptEdits`, `bypassPermissions`
 - **Hooks** — `PreToolUse`, `PostToolUse`, `PreCompact`, `PostCompact`, `SessionStart`, `UserPromptSubmit`, `Stop` events with shell command execution
 - **Streaming** — Real-time text delta callbacks via `onTextDelta`
 - **Context Loading** — AGENTS.md / CLAUDE.md walk-up discovery and system prompt assembly
 - **Prompt File References** — Path-like `@file` prompt references are resolved by the SDK under the session `cwd`, bounded by size/recursion limits, recorded as structured history events, and registered as observed context references
+- **Stable Project Reads** — Project byte and text reads use a bounded retained-root authority on qualified Linux, macOS, and Windows hosts; unsafe link/reparse replacement fails closed while project purpose, liveness, generation, and identity checks remain framework-owned
 - **Context Reference Inventory** — Manual `/context add` references are stored by `InteractiveSession`, included in future prompt model input, and exposed through SDK command common APIs
 - **Config Loading** — 6-file settings merge with provider profiles, legacy provider compatibility, and `$ENV:VAR` substitution for provider credentials
 - **Context Window Management** — Token tracking, configurable auto-compaction (default ~83.5%), manual `session.compact()`
 - **Background Jobs** — Runtime-managed subagent tasks with transcripts and task snapshots
-- **Agent Batch Jobs** — `Agent({ jobs: [...] })` starts explicit parallel subagent requests deterministically
+- **Agent Batch Jobs** — the model-facing Agent tool's `jobs` argument (`Agent` invoked with `{ jobs: [...] }`) starts explicit parallel subagent requests deterministically
 - **Edit Checkpoints** — Checkpoint/rewind support for safer edit workflows
 - **Project Memory** — Command-driven memory capture and retrieval surfaces
 - **Replay Events** — Session execution can forward provider/tool boundary events and provider-native raw payload events into append-only logs
+- **Usage observations** — Each accepted top-level turn records one content-free outcome observation, including the active model and driver surface when known, even when token usage is absent
 - **Bundle Plugin System** — Install and manage reusable extensions packaged as bundle plugins
 
 ## Architecture
@@ -95,8 +152,9 @@ agent-framework (assembly layer)
   ├── createQuery()       ← one-shot entry point factory
   ├── createSession()     ← internal assembly factory
   └── deps:
-        agent-session   (Session, SessionStore)
-        agent-tools     (tool infrastructure + 8 built-in tools)
+        agent-session   (Session, neutral session ports, explicit Node host adapters)
+        agent-file-authority (stable bounded project byte reads over retained native handles)
+        agent-tools     (tool infrastructure + 9 built-in tools)
         agent-provider  (consolidated AI providers: /anthropic, /openai, /gemini, …)
         agent-core      (Robota engine, providers, permissions, hooks)
 
@@ -104,7 +162,7 @@ agent-cli (TUI layer — bridges InteractiveSession events to React/Ink state)
   → agent-framework
 ```
 
-The SDK is **pure TypeScript with no React dependency**. The CLI is a thin TUI-only layer that consumes `InteractiveSession` events and maps them to React state. Any other client (web app, API server, worker) can do the same.
+The SDK is **pure TypeScript with no React dependency**. The CLI is a thin presentation layer (TUI, plus the `--serve` runtime host) that consumes `InteractiveSession` events and maps them to React state. Any other client (web app, API server, worker) can do the same.
 
 ## API
 
@@ -113,17 +171,33 @@ The SDK is **pure TypeScript with no React dependency**. The CLI is a thin TUI-o
 `InteractiveSession` wraps `Session` (composition over inheritance) to provide event-driven interaction for any client. It manages streaming text accumulation, tool execution state tracking, prompt queuing, abort orchestration, and message history. Logic that was previously embedded in CLI React hooks now lives here.
 
 ```typescript
-import { InteractiveSession, createProjectSessionStore } from '@robota-sdk/agent-framework';
+import {
+  InteractiveSession,
+  createProjectSessionStore,
+  getWorkspaceProjectStateStorage,
+} from '@robota-sdk/agent-framework';
 import type { IAIProvider } from '@robota-sdk/agent-core';
+import type { TWorkspaceProjectAccess } from '@robota-sdk/agent-framework';
 
 declare const provider: IAIProvider;
+// Supplied by a host-owned WorkspaceTrustService configured with projectStateDirectories
+// after identity/trust validation.
+declare const projectAccess: TWorkspaceProjectAccess;
 const cwd = process.cwd();
-const sessionStore = createProjectSessionStore(cwd);
+
+const sessionStore =
+  projectAccess.status === 'trusted'
+    ? createProjectSessionStore(
+        getWorkspaceProjectStateStorage(projectAccess.authority, 'sessions'),
+        getWorkspaceProjectStateStorage(projectAccess.authority, 'session-logs'),
+      )
+    : undefined;
 
 const session = new InteractiveSession({
   cwd,
   provider,
-  sessionStore, // SDK-owned project-local persistence facade
+  projectAccess,
+  sessionStore,
   resumeSessionId: 'sess_123', // Session ID to restore, incl. sandbox snapshot (optional)
   forkSession: false, // Fork the resumed session into a new one (optional)
   permissionMode: 'default',
@@ -156,8 +230,11 @@ session.on('interrupted', (result) => {
   // abort completed
 });
 
-// Submit a prompt (queues if already executing, max 1 queued)
-await session.submit('Explain this code');
+// Submit a prompt. The handle identifies this accepted turn even if it waits in the queue.
+const handle = await session.submit('Explain this code', undefined, undefined, {
+  driverId: 'owner',
+});
+await handle.completed;
 
 // Path-like @file references are expanded into model-only prompt context by the SDK.
 // The user-visible history keeps the original prompt plus a structured file-reference event.
@@ -199,6 +276,22 @@ session.setName('my-task'); // sets the session name
 session.getSession(); // Session
 ```
 
+`WorkspaceTrustService` accepts host-owned identity and trust-store adapters. Its authority is opaque,
+runtime-registered, root-bound, and cannot be reconstructed from a path or serialized marker. See the
+maintained offline `verify-workspace-project-authority.ts` example for a complete inspect/grant/revoke
+composition and Restricted-versus-trusted observable.
+
+The Node host supplies the production lifecycle through
+`createNodeWorkspaceTrustService(trustStorePath, projectStateDirectories)`. The caller chooses the
+user-owned store path and all four project-state directories; the Robota CLI uses
+`~/.robota/workspace-trust.json` for the trust store. Omitting project-state directories still permits
+trust inspection, but deriving project-state storage then fails closed.
+The service binds grants to the canonical Git worktree and repository common-directory identity,
+stores only owner-readable generation records, and treats non-Git paths, repository replacement,
+revocation, and trust-store errors as Restricted. A later provider settings layer that changes `baseURL`
+without its own credential also clears inherited `apiKey` and `apiKeyEnv` fields; endpoint provenance
+diagnostics can report the quarantine without exposing the credential.
+
 ### SystemCommandExecutor — SDK-Level Commands
 
 `SystemCommandExecutor` executes named system commands against an `InteractiveSession`. Commands are pure TypeScript — no React, no TUI dependency. The CLI wraps them as slash commands with UI chrome.
@@ -206,7 +299,7 @@ session.getSession(); // Session
 ```typescript
 import { SystemCommandExecutor, createSystemCommands } from '@robota-sdk/agent-framework';
 import type { ICommandHostContext } from '@robota-sdk/agent-framework';
-import type { ICommandResult } from '@robota-sdk/agent-interface-transport';
+import type { ICommandResult } from '@robota-sdk/agent-interface-command';
 
 declare const session: ICommandHostContext;
 const executor = new SystemCommandExecutor(); // starts empty unless commands are supplied
@@ -253,11 +346,15 @@ validate the current JSONL session log. Hosts may override `validateCurrentSessi
 These classes provide slash command discovery and aggregation for clients that expose a command palette or autocomplete UI.
 
 ```typescript
-import { CommandRegistry } from '@robota-sdk/agent-framework';
+import { CommandRegistry, createNodeHostContributionSource } from '@robota-sdk/agent-framework';
 import { createSkillsCommandModule } from '@robota-sdk/agent-command';
 
 const registry = new CommandRegistry();
-registry.addModule(createSkillsCommandModule({ cwd: process.cwd() }));
+registry.addModule(
+  createSkillsCommandModule({
+    contributionSources: [createNodeHostContributionSource(process.cwd())],
+  }),
+);
 
 // Get all commands (returns ICommand[])
 const commands = registry.getCommands();
@@ -269,25 +366,33 @@ const filtered = registry.getCommands('mod'); // matches "mode", "model"
 registry.resolveQualifiedName('audit'); // "my-plugin:audit"
 ```
 
-`SkillCommandSource` is the SDK common API used by the skills command module. It discovers skills from (highest priority first):
-
-- `<cwd>/.claude/skills/*/SKILL.md`
-- `<cwd>/.claude/commands/*.md` (Claude Code compatible)
-- `~/.robota/skills/*/SKILL.md`
-- `<cwd>/.agents/skills/*/SKILL.md`
+`SkillCommandSource` is the SDK common API used by the skills command module. The host supplies both
+the contribution sources and ordered root descriptors; absent sources or roots means no skill file
+discovery. This keeps product directory choices out of the framework and lets inspection use the same
+roots as activation.
 
 Model-invocable skills are exposed to the model as metadata only when the session has a composed
 model-invocable `skills` command descriptor. `@robota-sdk/agent-command` owns `skills` and
-activates skills through the SDK host API. Models use the SDK-projected `robota_command_skills`
-tool with skill arguments in `args`. Mentioning a skill in ordinary prose,
+activates skills through the SDK host API. Models use the SDK-projected `command_skills`
+tool by default, with skill arguments in `args`. A product host can set
+`modelCommandToolPrefix` on its session options to choose another prefix; Robota sets
+`robota_command_`. Mentioning a skill in ordinary prose,
 recommending a skill in assistant text, or matching a natural-language phrase in SDK/TUI code does
 not activate the skill.
 
+The framework's default prompt enclosure for attached `@file` content is
+`<file_references>`. Product hosts can set `promptFileReferenceTag` on session options to
+choose a different enclosure; Robota sets `robota_file_references`. SDK consumers that
+need the previous identifiers should pass `modelCommandToolPrefix: 'robota_command_'`
+and `promptFileReferenceTag: 'robota_file_references'` explicitly. Direct calls to
+`createProviderSafeModelCommandToolName`, `createModelCommandToolProjection`, and
+`buildPromptWithFileReferences` can pass the same values as their optional arguments.
+
 ### createQuery()
 
 ```typescript
 import { createQuery } from '@robota-sdk/agent-framework';
-import { AnthropicProvider } from '@robota-sdk/agent-provider/anthropic';
+import { AnthropicProvider } from '@robota-sdk/agent-provider-anthropic';
 
 const provider = new AnthropicProvider({ apiKey: process.env.ANTHROPIC_API_KEY });
 const query = createQuery({ provider });
@@ -316,19 +421,39 @@ one-shot calls.
 `@robota-sdk/agent-framework` assembles built-in tools for SDK sessions, but direct tool usage imports
 from the owner package:
 
+Each file tool is a FACTORY that requires the containment root it operates in (ARCH-010) — there is
+no ready-made instance, because one bound at import time can carry no root, and a file tool without a
+root has no boundary:
+
 ```typescript
 import {
-  bashTool,
-  editTool,
-  globTool,
-  grepTool,
-  readTool,
+  createShellTool,
+  createBashTool,
+  createEditTool,
+  createGlobTool,
+  createGrepTool,
+  createReadTool,
+  createWriteTool,
   webFetchTool,
   webSearchTool,
-  writeTool,
+  askUserQuestionTool,
 } from '@robota-sdk/agent-tools';
+
+const cwd = process.cwd();
+const fileTools = [
+  createShellTool({ cwd }),
+  createBashTool({ cwd }),
+  createEditTool({ cwd }),
+  createGlobTool({ cwd }),
+  createGrepTool({ cwd }),
+  createReadTool({ cwd }),
+  createWriteTool({ cwd }),
+];
 ```
 
+`webFetchTool`, `webSearchTool` and `askUserQuestionTool` remain instances: they touch no filesystem,
+so there is no root for them to be contained by.
+
 ### Sandbox Execution
 
 SDK sessions can receive a provider-neutral sandbox client. When provided, Bash, Read, Write, and Edit use the sandbox execution plane instead of the host process/filesystem:
@@ -337,7 +462,7 @@ SDK sessions can receive a provider-neutral sandbox client. When provided, Bash,
 
 ```typescript
 import { InteractiveSession } from '@robota-sdk/agent-framework';
-import { AnthropicProvider } from '@robota-sdk/agent-provider/anthropic';
+import { AnthropicProvider } from '@robota-sdk/agent-provider-anthropic';
 import { E2BSandboxClient } from '@robota-sdk/agent-tools';
 import type { IWorkspaceManifest } from '@robota-sdk/agent-tools';
 import { Sandbox } from 'e2b';
@@ -367,7 +492,7 @@ When `sessionStore` and a snapshot-capable `sandboxClient` are both provided, `I
 
 ## Subagent Sessions
 
-`createSubagentSession()` creates an isolated child session for delegating subtasks. The subagent receives pre-resolved config and context from the parent — it does not load config files or context from disk. Callers may provide a stable `sessionId` and `sessionLogger` so the child session writes a durable transcript.
+`createSubagentSession()` creates an isolated child session for delegating subtasks. The subagent receives pre-resolved config and context from the parent — it does not load config files or context from disk. Callers may provide a stable `sessionId`, `sessionLogger`, and `sessionStore` so the child session writes durable state.
 
 ```typescript
 import { createSubagentSession } from '@robota-sdk/agent-framework';
@@ -389,6 +514,13 @@ Built-in agents: `general-purpose` (full tool access), `Explore` (read-only, Hai
 
 `createAgentTool()` wraps subagent creation into a tool the AI can invoke directly. The parent session's hooks, permissions, and context are forwarded to the child.
 
+When a background job resumes a forked record, the runner passes the record's `resumeSessionId` as
+both the child session ID and the persistence key, together with the same session store that holds
+the copied record. Each completed child turn then updates that copied record, so `attach` sees the
+conversation after the fork as well as the conversation copied at fork time. Ordinary subagent jobs
+remain transient when they do not carry `resumeSessionId`; attaching is still a view switch, never a
+merge with the parent record.
+
 Background subagent lifecycle events are persisted through `InteractiveSession` when an SDK session persistence facade is configured. Streaming chunks are written to append-only JSONL logs/transcripts rather than rewriting the main session JSON per token.
 
 ## Replay-Grade Session Events
@@ -397,6 +529,17 @@ Background subagent lifecycle events are persisted through `InteractiveSession`
 
 Provider-native payload events are emitted by concrete provider packages through `IChatOptions.onProviderNativeRawPayload`, then redacted and externalized by the session logger before they are written to disk. The SDK exposes session command APIs so command modules such as `/validate-session` can validate replay coverage without adding file-log logic to CLI/TUI hosts.
 
+## Interactive Prompt Settlement
+
+`InteractiveSession` emits transport-neutral `permission_request` and `ask_request` events. Attached
+surfaces answer through `resolvePermission()` and `resolveAsk()`; the first answer wins and produces one
+`prompt_resolved` event. Session construction does not expose parallel `permissionHandler` or `askHandler`
+options, so local and remote surfaces share the same request/settlement path.
+
+Persisted checkpoint operations emit `branch_event` only after the transition and session save succeed.
+Transport-owned listeners must isolate their own delivery failures without changing arbitrary SDK listener
+exception behavior.
+
 ## Hook Executors (SDK-Specific)
 
 `agent-framework` provides two `IHookTypeExecutor` implementations beyond the `command` and `http` executors in `agent-core`:
@@ -513,19 +656,25 @@ Settings are merged from lowest to highest priority:
 
 ## Dependencies
 
-| Package                                | Purpose                               |
-| -------------------------------------- | ------------------------------------- |
-| `@robota-sdk/agent-core`               | Engine, providers, permissions, hooks |
-| `@robota-sdk/agent-session`            | Session, SessionStore                 |
-| `@robota-sdk/agent-tools`              | Tool infrastructure + built-in tools  |
-| `@robota-sdk/agent-provider/anthropic` | Anthropic LLM provider                |
-| `chalk`                                | Terminal colors (permission prompt)   |
-| `zod`                                  | Settings schema validation            |
+| Package                                | Purpose                                                       |
+| -------------------------------------- | ------------------------------------------------------------- |
+| `@robota-sdk/agent-core`               | Engine, providers, permissions, hooks                         |
+| `@robota-sdk/agent-session`            | Session, neutral log/store ports, explicit Node host adapters |
+| `@robota-sdk/agent-tools`              | Tool infrastructure + built-in tools                          |
+| `@robota-sdk/agent-provider-anthropic` | Anthropic LLM provider                                        |
+| `chalk`                                | Terminal colors (permission prompt)                           |
+| `zod`                                  | Settings schema validation                                    |
 
 ## Documentation
 
 See [docs/SPEC.md](./docs/SPEC.md) for the full specification, architecture details, and design decisions.
 
+From `packages/agent-framework` in a built repository, run
+`pnpm exec tsx examples/verify-goal-cassette-replay.mts` for offline goal replay through the public
+testing SDK. The credentialed recorder now lives at `scripts/record-goal-cassette.mts`; it is
+non-published development tooling, not a runtime provider dependency. Recording is an explicit
+live-provider operation; replay needs no credentials and preserves the committed cassette.
+
 ## License
 
 Robota is dual-licensed under the [GNU AGPL-3.0](../../LICENSE) or a [commercial license](../../COMMERCIAL.md). See [LICENSING.md](../../LICENSING.md).