@kodax-ai/kodax 0.7.77 → 0.7.79

package/README.md

@@ -41,21 +41,30 @@
 ```bash
 npm i -g @kodax-ai/kodax
 
-# Pick any one you have an API key for:
-export ZHIPU_API_KEY=...        # or ANTHROPIC_API_KEY / OPENAI_API_KEY / KIMI_API_KEY /
-                                # MINIMAX_API_KEY / MIMO_API_KEY / ARK_API_KEY / QWEN_API_KEY /
-                                # QWEN_TOKEN_API_KEY /
-                                # DEEPSEEK_API_KEY / GEMINI_API_KEY
+# Pick any one you have an API key for (`kodax setup --help` lists all):
+export ZHIPU_API_KEY=...        # ANTHROPIC_API_KEY / OPENAI_API_KEY / DEEPSEEK_API_KEY /
+                                # KIMI_API_KEY / KIMI_CODE_API_KEY / QWEN_API_KEY /
+                                # QWEN_TOKEN_API_KEY / ZHIPU_CODING_API_KEY /
+                                # ZAI_CODING_API_KEY / MINIMAX_CODING_API_KEY /
+                                # MIMO_API_KEY / MIMO_CODING_API_KEY / ARK_CODING_API_KEY
 
 kodax
 ```
 
-That's it. You're in the REPL — ask anything in natural language. If this is a
-new machine with no provider selection or supported API-key environment
-variable, the bare `kodax` launch opens a metadata-only setup flow first. It
-never asks for the key itself; after choosing a provider/model, set the named
-environment variable, restart the terminal, and run `kodax` again. Use
-`kodax setup` to rerun that flow explicitly.
+That's it. You're in the REPL — ask anything in natural language. On a new
+machine, bare interactive `kodax` first checks for supported API-key environment
+variables. If none exists, KodaX only prints Windows, macOS, and Linux setup
+instructions and exits without creating configuration or collecting a key.
+After setting the variable, close the current terminal, open a new one, and run
+`kodax` again. If a supported credential exists but no provider is selected,
+KodaX opens the provider/model metadata setup. Use `kodax setup` to rerun the
+flow, `kodax setup --custom` for a guided custom provider, and
+`kodax setup --help` (or REPL `/setup --help`) for paths, provider variables,
+commands, and shortcuts. Interactive setup also checks the optional ASRT sandbox once:
+Windows may show a one-time UAC prompt; macOS/Linux report any required
+Seatbelt/bubblewrap dependencies. Declining or missing a dependency does not
+break ordinary permission handling, and normal startup will not keep reminding
+you.
 
 > **No-Node target machines:** download a Bun-compiled single binary for Windows / macOS / Linux × x64 + arm64 from the [GitHub Releases](https://github.com/icetomoyo/KodaX/releases) page. See [docs/release.md](docs/release.md) for the build pipeline.
 
@@ -150,10 +159,33 @@ KodaX reads API keys from environment variables. For built-in providers, the fas
 ```bash
 # Interactive metadata-only provider/model setup (does not collect a key)
 kodax setup
+
+# Guided custom OpenAI/Anthropic-compatible provider
+kodax setup --custom
+
+# Complete guide; does not change files
+kodax setup --help
 ```
 
-The command tells you the exact environment-variable name to set and exits so
-you can restart the terminal. You can also configure it directly:
+Setup checks these active files and matching `*.example.jsonc` references:
+
+- `~/.kodax/config.json` and `~/.kodax/config.example.jsonc`
+- `~/.kodax/integrations/mcp.json`
+- `~/.kodax/integrations/extensions.json`
+- `~/.kodax/integrations/a2a.json`
+
+The core active file remains strict JSON. The first line of the annotated
+`config.example.jsonc` points to all split files and documents every supported
+core setting. Setup preserves existing files and stages readable legacy
+`config.json#mcpServers` / `config.json#extensions` before creating empty
+authoritative split files. It tells you the exact environment-variable name to
+set and exits so you can restart the terminal. Existing active files are
+validated first; an invalid file is reported without creating or overwriting
+configuration. For a custom provider, setup asks for an `apiKeyEnv` name such
+as `MY_LLM_API_KEY`, not the API key itself. `config.json` stores that name
+only; after setup, set the environment variable with exactly that name to the
+provider's actual API key. KodaX does not set the OS environment variable for
+you. You can also configure it directly:
 
 ```bash
 # macOS / Linux
@@ -163,6 +195,54 @@ export ZHIPU_API_KEY=your_api_key
 $env:ZHIPU_API_KEY="your_api_key"
 ```
 
+### 2.1 Activate the optional sandbox
+
+`kodax setup` and first-run setup check sandbox readiness. You can inspect or
+activate it explicitly:
+
+```bash
+kodax sandbox doctor
+kodax sandbox setup
+```
+
+- Windows uses a restricted sandbox account and network policy. A normal
+  terminal is sufficient; approve the one-time UAC prompt.
+- macOS uses Seatbelt/`sandbox-exec` and requires ripgrep
+  (`brew install ripgrep`).
+- Linux uses bubblewrap and requires `bubblewrap`, `socat`, and `ripgrep`
+  (install them with your distro's `apt`, `dnf`, or `pacman`).
+
+KodaX never runs `sudo` or a package manager automatically. If the sandbox is
+not active, deterministic safe operations and Auto[LLM] decisions keep the
+same permission behavior; only OS-level containment is absent. Ordinary runs
+do not repeatedly prompt for setup. In the REPL, `/sandbox` refreshes readiness
+and diagnostics without activating the backend or requesting elevation.
+Per-command sandbox routing remains internal and is not shown in normal command
+history. SDK embedders can use the same capability independently through
+`@kodax-ai/kodax/sandbox`; see the
+[SDK sandbox guide](docs/SDK_EMBEDDER_GUIDE.md#30-standalone-sandbox-sdk-v0778).
+
+Credential-shaped environment variables are filtered from model-issued shell
+commands by default. To expose exact host variables to those command targets,
+including ASRT, add only their names to the user-level core config:
+
+```json
+{
+  "sandbox": {
+    "envPass": ["GH_TOKEN", "GITHUB_TOKEN", "OPENAI_API_KEY"]
+  }
+}
+```
+
+The default list is empty. Values remain in the host environment and are never
+stored in `config.json`; project configuration cannot extend the list.
+Matching is exact (case-insensitive on Windows), and execution-control
+variables such as `NODE_OPTIONS` and `BASH_ENV` remain blocked. Restart KodaX
+after changing the host variables or this setting; stop/restart a persistent
+KodaX daemon so it receives the new environment and configuration.
+SDK callers pass the same shape per Run as `KodaXOptions.sandbox`, so concurrent
+Runs can use different lists without mutating process-global configuration.
+
 For Qwen Token Plan, select `qwen-token-plan` and use its separate credential;
 `QWEN_API_KEY` does not authenticate this route:
 
@@ -202,6 +282,11 @@ If you need a custom base URL or an OpenAI/Anthropic-compatible endpoint, define
 }
 ```
 
+Here, `"apiKeyEnv": "MY_LLM_API_KEY"` is a reference to an environment-variable
+name, not an API key value. Put the custom provider's actual API key in the
+`MY_LLM_API_KEY` environment variable, then close the current terminal and open
+a new one before running `kodax`.
+
 `userAgentMode` defaults to `"compat"`, which sends `KodaX` instead of the official SDK User-Agent. Switch it to `"sdk"` only when your gateway expects the upstream SDK header.
 For custom reasoning models, `reasoning: { efforts, default }` is the preferred v0.7.57 shape; use `"reasoning": "none"` for models without thinking capability. SDK hosts should render effort pickers from `reasoningProfile.supportedEfforts` / `defaultEffort` rather than assuming a fixed five-option ladder.
 
@@ -218,36 +303,45 @@ Some OpenAI-compatible reasoning models require KodaX to replay the previous ass
       "baseUrl": "https://example.com/v1",
       "apiKeyEnv": "MY_DEEPSEEK_API_KEY",
       "model": "deepseek-v4-flash",
-      "reasoningPreset": "deepseek-v4-openai",
+      "maxOutputTokensField": "max_tokens",
+      "reasoningPreset": "deepseek-v4-flash-openai",
       "replayReasoningContent": true
     }
   ]
 }
 ```
 
-Keep `replayReasoningContent` unset or `false` for OpenAI proper and gateways that reject unknown assistant-message fields. If one gateway routes mixed models, prefer per-model overrides:
+DeepSeek Chat Completions uses `max_tokens`; OpenAI proper defaults to
+`max_completion_tokens`. Keep `replayReasoningContent` unset or `false` for
+OpenAI proper and gateways that reject unknown assistant-message fields. If one
+gateway routes mixed models, prefer per-model overrides for both fields:
 
 ```json
 {
   "models": [
-    { "id": "deepseek-v4-flash", "replayReasoningContent": true },
+    {
+      "id": "deepseek-v4-flash",
+      "maxOutputTokensField": "max_tokens",
+      "reasoningPreset": "deepseek-v4-flash-openai",
+      "replayReasoningContent": true
+    },
     { "id": "gpt-5", "replayReasoningContent": false }
   ]
-}
-```
-
-If a custom endpoint is confirmed to support cache-affinity routing, set
-`"promptCacheAffinity": true`. Anthropic-compatible requests then receive the
-opaque logical-context key as `metadata.user_id`; OpenAI-compatible requests
-receive `prompt_cache_key`. The default is `false` because some strict
-compatible gateways reject unknown request fields. Do not enable it solely
-because an endpoint claims protocol compatibility.
-
-Sidecar verifier judge calls use provider-level forced tool choice when supported. If a compatible endpoint rejects the `tool_choice` parameter, KodaX retries that verifier request once without forced tool choice and still fails open rather than blocking the main Worker.
+}
+```
+
+If a custom endpoint is confirmed to support cache-affinity routing, set
+`"promptCacheAffinity": true`. Anthropic-compatible requests then receive the
+opaque logical-context key as `metadata.user_id`; OpenAI-compatible requests
+receive `prompt_cache_key`. The default is `false` because some strict
+compatible gateways reject unknown request fields. Do not enable it solely
+because an endpoint claims protocol compatibility.
+
+Sidecar verifier judge calls use provider-level forced tool choice when supported. If a compatible endpoint rejects the `tool_choice` parameter, KodaX retries that verifier request once without forced tool choice and still fails open rather than blocking the main Worker.
 
 #### Opting a custom provider into image / vision input (FEATURE_134 v0.7.40)
 
-If your custom provider's underlying model supports image input (vision), add a `capabilityProfile.multimodalSupport: "image-input"` block so KodaX does not artificially block multimodal requests at the SA-path policy gate. Built-in vision-capable aliases (Anthropic, OpenAI, Anthropic-/OpenAI-compatible aliases such as DeepSeek, Kimi, Qwen, Zhipu, MiniMax, MiMo, Ark, plus Gemini-CLI via the CLI's `@<path>` file-include syntax) already ship with this flag enabled by default; Codex-CLI and custom providers need to opt in when their underlying model supports image input.
+If your custom provider's underlying model supports image input (vision), add a `capabilityProfile.multimodalSupport: "image-input"` block so KodaX does not artificially block multimodal requests at the SA-path policy gate. Built-in vision-capable aliases (Anthropic, OpenAI, compatible aliases such as Kimi, Qwen, Zhipu, MiniMax, MiMo, Ark, plus Gemini-CLI via the CLI's `@<path>` file-include syntax) already ship with this flag enabled by default. DeepSeek V4 and Codex-CLI are text-only; custom providers need to opt in when their underlying model supports image input.
 
 ```json
 {
@@ -406,66 +500,124 @@ clarification required to finish the current request, emits budget-approval
 state only for eligible Sidecar revisions, and preserves structured blocked
 reasons across embedded and daemon Runtime boundaries.
 
-**v0.7.76 Kimi Code catalog refresh:** `kimi-code` now defaults to the official
-`k3-256k` Model ID and sends it unchanged. `kimi-for-coding` remains selectable
-for K2.7 Code, alongside `kimi-for-coding-highspeed` and the 1M `k3` tier. K3
-supports `low` / `high` / `max` reasoning with `high` as default; the 256K
-route supports image input but not video input.
-
-**v0.7.77 release-ready candidate:** AMA now chooses and composes six named
-problem-solving patterns through the existing Actor control plane instead of
-using a fixed topology or hidden Workflow. Optional strategy metadata becomes
-a bounded, fact-only `PatternTrace`; the existing Sidecar remains the only
-terminal-answer quality judge. Governed memory can also react sparsely after a
-tool failure, verification failure, or committed compaction and place at most
-three prompt-safe, low-authority evidence items before the next Action-LLM
-request. The default path adds no selector model call; SDK hosts may opt into
-`memoryRecallRunner` in process. Public `kimi` also gains the 1M `kimi-k3`
-route while retaining K2.7 Code as its default. See the
-[v0.7.77 design](docs/features/v0.7.77.md) and
-[release checklist](docs/release.md#v0777-release-ready-candidate-verification).
-The frozen F274/F275 paid evaluation completed with `recommend-ship` from the
-final F274 Layer 2/Layer 3 reviews and the F275 pilot review, followed by a
-joint `SHIP` decision for the deterministic contracts. Semantic memory
-selection remains experimental and host opt-in; no task-quality, token, or
-latency improvement is claimed.
-
-The same candidate adds an opt-in, host-configurable Shell Execution Contract.
-Runtime Session settings or an individual Run can select `pwsh`, Windows
-PowerShell, `cmd`, `bash`, `zsh`, or an explicit Git Bash executable; KodaX
-resolves the shell environment in the effective project cwd and then executes
-the command through that same interpreter. Resolved environments are isolated
-by contract and cwd, expire after a bounded TTL, and can be explicitly
-refreshed. Provider credentials and execution-control variables are removed
-before profile/setup code and again before the command starts. When
-`shellExecution` is absent, established command behavior is unchanged. See
-[SDK Embedder Guide section 28](docs/SDK_EMBEDDER_GUIDE.md#28-host-configurable-shell-execution-contract-v0777)
-and the [Issue 214 regression guide](docs/test-guides/ISSUE_214_v0.7.77_REGRESSION_GUIDE.md).
-
-Kimi Code requests also receive a stable, opaque prompt-cache affinity key
-derived from the logical Runtime context. It is reused across Runs, retries,
-fallback, resume, and compaction; recursive child Agents receive distinct keys
-based on their canonical Agent path rather than their temporary transcript
-Session. Public Kimi and official OpenAI use the corresponding
-`prompt_cache_key` field, while other compatible gateways remain opt-in because
-some reject unknown request fields. This improves routing stability but cannot
-override Provider TTL or cache sharding. See the
-[Issue 215 regression guide](docs/test-guides/ISSUE_215_v0.7.77_REGRESSION_GUIDE.md).
-Codex CLI cache reads/writes and Gemini CLI cache reads now flow through the
-CLI bridge and Runtime diagnostics without estimation. A reported `0` remains
-distinct from an unreported field; see the
-[Issue 216 regression guide](docs/test-guides/ISSUE_216_v0.7.77_REGRESSION_GUIDE.md).
-The bridge also starts the first native CLI turn fresh, resumes only a native
-session ID reported by that CLI, creates fresh ACP sessions for stateless
-calls, recreates a closed pseudo transport, and validates the process exit even
-after a terminal CLI event. User cancellation stays quiet, while hard/idle
-timeout aborts remain failures eligible for Runtime recovery, and a CLI that
-reports success but never exits is terminated at its configured deadline; see the
-[Issue 217 regression guide](docs/test-guides/ISSUE_217_v0.7.77_REGRESSION_GUIDE.md).
-
-One daemon owns many sessions. Different sessions may run concurrently; starts
-within the same session are queued so that only one run is active for that
-session. Multiple `kodax` processes can attach to the same daemon and open or
+**v0.7.76 Kimi Code catalog refresh:** `kimi-code` now defaults to the official
+`k3-256k` Model ID and sends it unchanged. `kimi-for-coding` remains selectable
+for K2.7 Code, alongside `kimi-for-coding-highspeed` and the 1M `k3` tier. K3
+supports `low` / `high` / `max` reasoning with `high` as default; the 256K
+route supports image input but not video input.
+
+**v0.7.77 release:** AMA now chooses and composes six named
+problem-solving patterns through the existing Actor control plane instead of
+using a fixed topology or hidden Workflow. Optional strategy metadata becomes
+a bounded, fact-only `PatternTrace`; the existing Sidecar remains the only
+terminal-answer quality judge. Governed memory can also react sparsely after a
+tool failure, verification failure, or committed compaction and place at most
+three prompt-safe, low-authority evidence items before the next Action-LLM
+request. The default path adds no selector model call; SDK hosts may opt into
+`memoryRecallRunner` in process. Public `kimi` also gains the 1M `kimi-k3`
+route while retaining K2.7 Code as its default. See the
+[v0.7.77 design](docs/features/v0.7.77.md) and
+[release checklist](docs/release.md#v0777-release-ready-candidate-verification).
+The frozen F274/F275 paid evaluation completed with `recommend-ship` from the
+final F274 Layer 2/Layer 3 reviews and the F275 pilot review, followed by a
+joint `SHIP` decision for the deterministic contracts. Semantic memory
+selection remains experimental and host opt-in; no task-quality, token, or
+latency improvement is claimed.
+
+**v0.7.78 evidence-gated learning, setup, and permission/sandbox release:**
+Background learning is Memory-first. Only repeated independently verified
+evidence, or an explicit preserve-as-Skill request with verified terminal
+evidence, can admit a low-risk declarative Skill to a bounded immutable
+project canary; three exact-revision uses and independently verified success
+are required before automatic project trust. Every revision remains visible
+and reversible in `/learn`. Protected/formal Skills, global promotion, and
+Extension authoring remain explicit user actions.
+
+First-run setup now creates and validates the split core/MCP/Extensions/A2A
+files and annotated templates without overwriting existing configuration or
+collecting secrets. Auto[LLM] admits precisely modeled ordinary reads and
+workspace/temp mutations before classifier latency, retries classifier
+infrastructure failure once, then falls back at the Accept-edits boundary
+without switching to rules. ASRT is optional execution containment rather
+than permission authority; `/sandbox` is the explicit diagnostic surface, and
+SDK hosts can use the standalone `/sandbox` subpath without a silent
+unsandboxed fallback. KodaX's workspace containment denies reads from common
+home credential paths and the complete resolved agent home without turning
+ordinary external reads into an allowlist. See the
+[v0.7.78 design](docs/features/v0.7.78.md), the
+[release checklist](docs/release.md#v0778-release-verification), and
+[SDK guide sections 29–30](docs/SDK_EMBEDDER_GUIDE.md#29-evidence-gated-background-skill-learning-feature_263-v0778).
+
+The release closure also preserves intent across adjacent surfaces: static
+Skill instructions load in Edit/Plan without granting later side effects,
+dynamic Skill commands require an explicit host-controlled executor, root AMA
+uses the governed `memory_intent` lifecycle (including explicit intent captured
+before a later cancellation), Workflow Actor waits remain
+unbounded unless the workflow sets a deadline, and Runtime Auto capability v4
+advertises `fallbackPersistsEngine:false` across embedded, Worker, and daemon
+hosts. Actor ownership additionally uses Runtime identity rather than PID alone,
+so PID reuse cannot pin a crashed owner. The resume Session picker also renders
+timestamps in the host's local timezone.
+
+**v0.7.79 release-preparation candidate:** Configured outbound A2A Agents can persist two
+independent, default-deny network permissions: private-address access and
+non-loopback plaintext HTTP. The embedded Worker and shared daemon reconcile
+and execute the same authorized configuration. Runtime embedders also gain one
+authoritative Session status, bounded read-only diagnostics, byte-preserving
+Session export, strict transcript observation, a provenance-checked ordinary
+conversation projection, and bounded streaming-event coalescing with
+capability-gated idle daemon upgrade. Standalone child-process, Session lineage,
+shell cleanup, packaged sidecar, and parallel admission paths receive the
+corresponding release hardening.
+
+OpenAI-compatible custom providers can now choose `max_tokens` or
+`max_completion_tokens` per provider or model. DeepSeek V4 Flash and Pro use
+separate reasoning profiles and are advertised as text-only. See the
+[v0.7.79 design](docs/features/v0.7.79.md) and
+[release preparation checklist](docs/release.md#v0779-release-preparation).
+FEATURE_280 was explicitly rescheduled to v0.7.81 and is not represented as
+shipped by this candidate.
+Issue 256 was explicitly rescheduled to v0.7.84 and is likewise not represented
+as shipped by this candidate.
+
+The v0.7.77 release also adds an opt-in, host-configurable Shell Execution Contract.
+Runtime Session settings or an individual Run can select `pwsh`, Windows
+PowerShell, `cmd`, `bash`, `zsh`, or an explicit Git Bash executable; KodaX
+resolves the shell environment in the effective project cwd and then executes
+the command through that same interpreter. Resolved environments are isolated
+by contract and cwd, expire after a bounded TTL, and can be explicitly
+refreshed. Provider credentials and execution-control variables are removed
+before profile/setup code and again before the command starts. Credential-shaped
+variables are also filtered on the legacy platform-shell path; explicit names
+in user-level `sandbox.envPass` are restored only for the final command target.
+When `shellExecution` is absent, the established interpreter path is unchanged. See
+[SDK Embedder Guide section 28](docs/SDK_EMBEDDER_GUIDE.md#28-host-configurable-shell-execution-contract-v0777)
+and the [Issue 214 regression guide](docs/test-guides/ISSUE_214_v0.7.77_REGRESSION_GUIDE.md).
+
+Kimi Code requests also receive a stable, opaque prompt-cache affinity key
+derived from the logical Runtime context. It is reused across Runs, retries,
+fallback, resume, and compaction; recursive child Agents receive distinct keys
+based on their canonical Agent path rather than their temporary transcript
+Session. Public Kimi and official OpenAI use the corresponding
+`prompt_cache_key` field, while other compatible gateways remain opt-in because
+some reject unknown request fields. This improves routing stability but cannot
+override Provider TTL or cache sharding. See the
+[Issue 215 regression guide](docs/test-guides/ISSUE_215_v0.7.77_REGRESSION_GUIDE.md).
+Codex CLI cache reads/writes and Gemini CLI cache reads now flow through the
+CLI bridge and Runtime diagnostics without estimation. A reported `0` remains
+distinct from an unreported field; see the
+[Issue 216 regression guide](docs/test-guides/ISSUE_216_v0.7.77_REGRESSION_GUIDE.md).
+The bridge also starts the first native CLI turn fresh, resumes only a native
+session ID reported by that CLI, creates fresh ACP sessions for stateless
+calls, recreates a closed pseudo transport, and validates the process exit even
+after a terminal CLI event. User cancellation stays quiet, while hard/idle
+timeout aborts remain failures eligible for Runtime recovery, and a CLI that
+reports success but never exits is terminated at its configured deadline; see the
+[Issue 217 regression guide](docs/test-guides/ISSUE_217_v0.7.77_REGRESSION_GUIDE.md).
+
+One daemon owns many sessions. Different sessions may run concurrently; starts
+within the same session are queued so that only one run is active for that
+session. Multiple `kodax` processes can attach to the same daemon and open or
 observe the same session. FEATURE_269 adds atomic snapshot-plus-stream joining,
 durable idempotent mutations, revision-safe settings and grants, transport-safe
 AskUser/permission responses, run-scoped credential and Host Tool bridges, and
@@ -488,11 +640,13 @@ The Space/IDE shared-daemon contract is documented in
 
 **v0.7.72–v0.7.73 Runtime permission contract:** Auto Mode is owned by the Runtime session,
 not by a UI hook. It reuses its LLM/rules guardrail across turns, classifies
-before the shared permission bridge, and persists an automatic fallback to
-rules. The same session settings can select a classifier model and bounded
+before the shared permission bridge, and persists explicit engine selection.
+The same session settings can select a classifier model and bounded
 timeout; `auto` defaults to LLM classification and fails with a recoverable
 configuration error when no effective classifier model exists, rather than
-silently falling back. Runtime permission prompts now offer opaque, exact
+silently falling back. In v0.7.78, classifier failures retry once and then use
+the Accept-edits safety boundary; they never change the engine to rules.
+Runtime permission prompts offer opaque, exact
 allow-once/session/persistent grant suggestions; persistent grants are
 daemon-owned and revisioned. Host plan exit is exposed only when the host
 supplies an approval callback. See the [Runtime Auto Mode integration guide](docs/SDK_EMBEDDER_GUIDE.md#24-runtime-owned-auto-mode-and-plan-approval-bridges-v0772v0773).
@@ -510,7 +664,7 @@ kodax --repo-intelligence full --repo-intelligence-trace
 
 ## Architecture
 
-KodaX uses a **monorepo architecture** with npm workspaces. Source layout currently has 4 workspace packages; published as a single bundled npm package `@kodax-ai/kodax` with 11 SDK subpath exports (`/agent`, `/llm`, `/coding`, `/media`, `/repl`, `/skills`, `/mcp`, `/session`, `/runtime`, `/a2a`, `/experimental-memory`; ADR-024 + ADR-032 + ADR-038, with ADR-036 consolidation):
+KodaX uses a **monorepo architecture** with npm workspaces. Source layout currently has 4 workspace packages; published as a single bundled npm package `@kodax-ai/kodax` with 12 SDK subpath exports (`/agent`, `/llm`, `/coding`, `/media`, `/repl`, `/skills`, `/mcp`, `/session`, `/runtime`, `/sandbox`, `/a2a`, `/experimental-memory`; ADR-024 + ADR-032 + ADR-038, with ADR-036 consolidation):
 
 ```
 KodaX/
@@ -536,9 +690,9 @@ KodaX/
 │
 ├── src/                     # CLI entry + SDK subpath entries
 │   ├── kodax_cli.ts         # Main CLI entry point (bin: `kodax`)
-│   └── sdk-*.ts             # SDK subpath re-exports → @kodax-ai/kodax/{agent,llm,coding,media,repl,skills,mcp,session,runtime,a2a,experimental-memory}
+│   └── sdk-*.ts             # SDK subpath re-exports → @kodax-ai/kodax/{agent,llm,coding,media,repl,skills,mcp,session,runtime,sandbox,a2a,experimental-memory}
 │
-└── package.json             # Root workspace config; release.mjs rewrites name + injects subpath exports
+└── package.json             # Publish-shaped exports; release.mjs only toggles private during pack/publish
 ```
 
 ### Package Dependencies
@@ -585,9 +739,9 @@ Source-side workspace package names (`@kodax-ai/*`). npm consumers install the s
 KodaX has two layers that consumers should understand separately:
 
 - **Source-side**: 4 workspace packages above (what developers see when reading the repo).
-- **npm-published**: a single bundled package `@kodax-ai/kodax` with 11 SDK subpaths (what SDK consumers `import` from). The subpaths are split into two roles:
+- **npm-published**: a single bundled package `@kodax-ai/kodax` with 12 SDK subpaths (what SDK consumers `import` from). The subpaths are split into two roles:
   - **Full-package subpaths** (`/agent`, `/llm`, `/coding`, `/repl`) — each one maps 1:1 to a source workspace and exposes its complete public API.
-  - **Integration and narrow subpaths** (`/media`, `/skills`, `/mcp`, `/session`, `/runtime`, `/a2a`, `/experimental-memory`) — focused host surfaces. `/a2a` composes the neutral F258 plane with the Runtime facade; it does not add A2A wire types to `/agent`.
+  - **Integration and narrow subpaths** (`/media`, `/skills`, `/mcp`, `/session`, `/runtime`, `/sandbox`, `/a2a`, `/experimental-memory`) — focused host surfaces. `/a2a` composes the neutral F258 plane with the Runtime facade; it does not add A2A wire types to `/agent`.
 
 | Source package | npm subpath | Type | What you get | Example consumer |
 |---|---|---|---|---|
@@ -601,6 +755,7 @@ KodaX has two layers that consumers should understand separately:
 | `packages/repl`   | `@kodax-ai/kodax/repl`    | Full package | Ink TUI + permission modes + commands (217 exports) | Terminal-UI consumers |
 | `packages/repl`   | `@kodax-ai/kodax/session` | **Narrow subset** | Session management only — `listSessions` / `loadFullTranscript` / `appendClientNotice` / `forkSession` / `compactSession` / `watchSessions` / ... (17 exports) | IDE plugins and desktop hosts reading session history |
 | `src`             | `@kodax-ai/kodax/runtime` | Host API | Embedded/Worker/daemon runtime facade, sessions/runs/events/permissions/catalog/MCP/artifacts/diagnostics/external agents, daemon protocol schema (10 exports) | SDK hosts, Space/IDE clients, daemon clients |
+| `src`             | `@kodax-ai/kodax/sandbox` | Host API | Explicit ASRT capability/doctor/setup and host-owned contained command execution; unavailability never means silent ordinary execution | SDK hosts that need standalone process containment |
 | `src`             | `@kodax-ai/kodax/a2a` | Integration edge | A2A 1.0 Agent Card discovery, JSON-RPC/SSE F258 executor, safe fetch policy, and authenticated Runtime-backed Agent server | Agent orchestrators and KodaX hosts |
 
 **Rule of thumb**: if you need Runner / Agent / fan-out, import from `/agent`. If you only need skills or mcp APIs, import from `/skills` or `/mcp` to get a smaller bundle. The narrow subsets are subsets of the full packages — they do **not** expose extra symbols.
@@ -633,7 +788,7 @@ KodaX has two layers that consumers should understand separately:
 
 **Experimental Memory Agent SDK (FEATURE_260, v0.7.68)**: `/experimental-memory` exposes the thin agent-layer `MemoryAgent` and scoped `MemorySession` lifecycle over the existing governed F228 plane. Passive recall is zero-wait; `query()` is read-only and deliberate; durable changes still require the proposal/preview/fingerprint/apply path. The Action LLM remains the final decision maker, recalled content stays low-authority, and safety/scope gates remain deterministic. See the [direct session and boundary guide](docs/SDK_EMBEDDER_GUIDE.md#21-experimental-governed-memory--experimental-memory-feature_260-v0768).
 
-**Bidirectional A2A 1.0 (FEATURE_267, v0.7.69)**: `/a2a` discovers allowed Agent Cards and installs a JSON-RPC/SSE executor through the existing F258 plane. Configured outbound Agents are also registered automatically as `external:<name>` in embedded CLI and user-daemon Runtimes, so the main Agent can orchestrate them without host code. One `a2a.json` may hold many outbound registrations and at most one inbound server, which publishes either the Runtime default or one validated `~/.kodax/agents/*.md` Agent behind an authenticated Runtime facade. The built-in listener is loopback-only; public deployment uses `handle()` behind host-owned TLS and authorization. A2A 0.3, gRPC, HTTP+JSON, push notifications, and automatic public exposure are not advertised. See the [client/server recipes and security boundaries](docs/SDK_EMBEDDER_GUIDE.md#22-bidirectional-a2a-10--a2a-feature_267-v0769).
+**Bidirectional A2A 1.0 (FEATURE_267, v0.7.69)**: `/a2a` discovers allowed Agent Cards and installs a JSON-RPC/SSE executor through the existing F258 plane. Configured outbound Agents are also registered automatically as `external:<name>` in embedded CLI and user-daemon Runtimes, so the main Agent can orchestrate them without host code. One `a2a.json` may hold many outbound registrations and at most one inbound server, which publishes either the Runtime default or one validated `~/.kodax/agents/*.md` Agent behind an authenticated Runtime facade. The built-in listener is loopback-only and will not return a port blocked by Fetch-compatible clients; public deployment uses `handle()` behind host-owned TLS and authorization. A2A 0.3, gRPC, HTTP+JSON, push notifications, and automatic public exposure are not advertised. See the [client/server recipes and security boundaries](docs/SDK_EMBEDDER_GUIDE.md#22-bidirectional-a2a-10--a2a-feature_267-v0769).
 
 **A2A interoperability and authentication hardening** keeps a discovered
 interface on the trusted Agent Card origin and sends credentials only when one
@@ -671,6 +826,10 @@ kodax a2a add research https://agent.example/.well-known/agent-card.json --effec
 kodax a2a test research
 kodax a2a call research "Summarize this topic"
 
+# Explicitly authorize a private plaintext endpoint (prefer HTTPS when available)
+kodax a2a add intranet http://10.20.30.40/.well-known/agent-card.json \
+  --allow-private --allow-insecure-http --effect read
+
 # Stage an OAuth-protected Agent, then hot-activate/deactivate it
 export RESEARCH_A2A_CLIENT_SECRET='provisioned-by-your-authorization-server'
 # PowerShell: $env:RESEARCH_A2A_CLIENT_SECRET='provisioned-by-your-authorization-server'
@@ -693,7 +852,8 @@ kodax a2a serve                  # loopback http://127.0.0.1:8765
 ```
 
 MCP, A2A, and Extension declarations live in one user file per domain under
-`~/.kodax/integrations/`. Use `kodax config template <mcp|a2a|extensions>`,
+`~/.kodax/integrations/`. Use `kodax config paths`,
+`kodax config template <core|mcp|a2a|extensions>`,
 `kodax integrations migrate --apply`, and the `kodax mcp`, `kodax a2a`, or
 `kodax extensions` commands to manage them. Migration imports only legacy
 `config.json#mcpServers` and `config.json#extensions`; A2A has no legacy source.
@@ -713,7 +873,12 @@ the Card by default unless `--no-test` is supplied, while `a2a test` performs
 discovery/security planning without requesting an OAuth token. The fixed
 `KODAX_A2A_TOKEN` example is an operator-provisioned compatibility credential;
 KodaX does not generate or issue it. Disabled entries remain available for
-later re-enable. `a2a serve` loads
+later re-enable. Private-address access and non-loopback plaintext HTTP are
+independent, persisted, default-deny permissions (`--allow-private` and
+`--allow-insecure-http`); exact loopback HTTP remains available without either.
+OAuth token endpoints retain their stricter HTTPS-or-exact-loopback rule.
+Worker-hosted SDK Runtimes can load this same configured plane inside the Worker
+owner with `worker: { configuredA2A: true }`. `a2a serve` loads
 its configured MCP/Extension capability surface before listening and pins that
 execution authority; it hot-reloads publication, authentication, and limits.
 
@@ -846,10 +1011,12 @@ import { loadConfig } from '@kodax-ai/kodax/repl';              // REPL config /
 import { createMcpManager } from '@kodax-ai/kodax/mcp';         // MCP popout manager (v0.7.42)
 import { listSessions } from '@kodax-ai/kodax/session';         // session history helpers
 import { createKodaXRuntime } from '@kodax-ai/kodax/runtime';   // embedded/daemon runtime API
+import { runKodaXSandboxed } from '@kodax-ai/kodax/sandbox';    // standalone ASRT containment
 import { createKodaXA2AServer } from '@kodax-ai/kodax/a2a';    // A2A 1.0 client/server edge
+import { createMemoryAgent } from '@kodax-ai/kodax/experimental-memory'; // opt-in memory SDK
 ```
 
-All 12 SDK entries (root + 11 subpaths) share internal code via ESM chunk splitting — importing from `/agent` does not pull in `/repl`'s Ink + React surface.
+All 13 SDK entries (root + 12 subpaths) share internal code via ESM chunk splitting — importing from `/agent` does not pull in `/repl`'s Ink + React surface.
 
 For the complete host-facing contract — including embedded/Worker/daemon ownership,
 external-agent registration and task control, session cursor pagination, workflow
@@ -1000,16 +1167,19 @@ KodaX provides 3 permission modes for fine-grained control:
 **Features:**
 - In `accept-edits` mode, choosing "always" can persist safe Bash allow-patterns
 - Plan mode includes system prompt context for LLM awareness
-- Permanent protection zones: `.kodax/`, `~/.kodax/`, paths outside project
+- Sensitive/protected or unresolved targets enter Auto[LLM]/approval review;
+  ordinary reads outside the project are allowed
 - Pattern-based permission: Allow specific Bash commands (e.g., `Bash(npm install)`)
 - Unified diff display for write/edit operations
-- Auto Mode runs guardrail classification before the permission UI; a safe
-  allow verdict does not create a pending approval request. The session records
-  an automatic LLM-to-rules fallback for later turns.
+- Auto Mode first admits exactly modeled safe reads and workspace/temp
+  mutations without classifier latency. Remaining actions are reviewed against
+  bounded user intent and exact operation facts; a safe verdict creates no
+  pending approval request. Classifier failures retry once, then use the
+  Accept-edits safety boundary rather than silently switching to Auto[rules].
 - Shift-Tab cycles `Plan -> Edits -> Auto`; Shift+Enter inserts a newline. Auto
   immediately displays `Auto[LLM]` or `Auto[RULES]`, and rapid mode changes are
-  persisted in input order. `Auto[RULES]` is a valid sticky fallback/manual
-  state; use `/auto-engine llm` to opt back into LLM classification.
+  persisted in input order. `Auto[RULES]` remains an explicit/manual engine;
+  use `/auto-engine llm` to select LLM classification.
 - Runtime-backed prompts can offer exact `allow once`, `allow this session`,
   and `always allow` choices. Return the Runtime-issued opaque suggestion;
   never derive or widen a permission rule from the displayed command or path.
@@ -1176,7 +1346,7 @@ await runKodaX({
 
 ## SDK Usage
 
-KodaX ships as a single npm package `@kodax-ai/kodax` with 11 SDK subpath exports (ADR-024 v0.7.39 + ADR-032 v0.7.42 + ADR-038 v0.7.49 + v0.7.56 `/media` + v0.7.64 `/runtime` + v0.7.68 `/experimental-memory` + v0.7.69 `/a2a`). Each subpath is tree-shake-friendly so consumers pull only what they need:
+KodaX ships as a single npm package `@kodax-ai/kodax` with 12 SDK subpath exports (ADR-024 v0.7.39 + ADR-032 v0.7.42 + ADR-038 v0.7.49 + v0.7.56 `/media` + v0.7.64 `/runtime` + v0.7.68 `/experimental-memory` + v0.7.69 `/a2a` + v0.7.78 `/sandbox`). Each subpath is tree-shake-friendly so consumers pull only what they need:
 
 ```bash
 npm install @kodax-ai/kodax
@@ -1193,6 +1363,7 @@ import { SkillRegistry } from '@kodax-ai/kodax/skills';           // zero-dep sk
 import { createMcpManager } from '@kodax-ai/kodax/mcp';           // MCP popout manager (v0.7.42)
 import { listSessions } from '@kodax-ai/kodax/session';           // session history helpers
 import { createKodaXRuntime } from '@kodax-ai/kodax/runtime';     // embedded/daemon runtime API
+import { runKodaXSandboxed } from '@kodax-ai/kodax/sandbox';      // explicit standalone containment
 import { createKodaXA2AServer } from '@kodax-ai/kodax/a2a';      // A2A 1.0 client/server edge
 import { createMemoryAgent } from '@kodax-ai/kodax/experimental-memory'; // opt-in experimental memory SDK
 ```
@@ -1359,7 +1530,7 @@ await runInkInteractiveMode({ provider: 'zhipu-coding', effort: 'auto' });
 | kimi | `KIMI_API_KEY` | Native | kimi-k2.7-code (262,144-token context; `kimi-k3` 1M / `kimi-k2.7-code-highspeed` / `kimi-k2.6` / `kimi-k2.5` via `/model`) |
 | kimi-code | `KIMI_CODE_API_KEY` | Native | k3-256k (Moderato+, 256K, direct upstream ID; `k3` 1M / `kimi-for-coding` K2.7 Code / `kimi-for-coding-highspeed` via `/model`) |
 | qwen | `QWEN_API_KEY` | Native | qwen3.5-plus |
-| qwen-token-plan | `QWEN_TOKEN_API_KEY` | Native | qwen3.8-max-preview (Anthropic-compat; `qwen3.7-max` / `qwen3.7-plus` / `qwen3.6-flash` / `glm-5.2` / `deepseek-v4-pro` via `/model`; all 1M context; image input on Qwen 3.8 / 3.7 Plus / 3.6 Flash) |
+| qwen-token-plan | `QWEN_TOKEN_API_KEY` | Native | qwen3.8-max (Anthropic-compat; legacy `qwen3.8-max-preview` plus `qwen3.7-max` / `qwen3.7-plus` / `qwen3.6-flash` / `glm-5.2` / `deepseek-v4-pro` via `/model`; all 1M context; image input on both Qwen 3.8 IDs / 3.7 Plus / 3.6 Flash) |
 | zhipu | `ZHIPU_API_KEY` | Native | glm-5 (`glm-5.2` 1M ctx / `glm-5.1` / `glm-5-turbo` via `/model`) |
 | zhipu-coding | `ZHIPU_CODING_API_KEY` | Native | glm-5.2 (1M ctx; legacy `glm-5.1` and `glm-5-turbo` remain selectable via `/model`) |
 | zai-coding | `ZAI_CODING_API_KEY` | Native | glm-5.2 (Zhipu Coding Plan overseas mirror via `api.z.ai`, Anthropic-compat — same model lineup as `zhipu-coding`, served from outside CN) |
@@ -1368,8 +1539,8 @@ await runInkInteractiveMode({ provider: 'zhipu-coding', effort: 'auto' });
 | mimo-coding | `MIMO_CODING_API_KEY` | Native | mimo-v2.5-pro (Xiaomi Token Plan, Anthropic-compat) |
 | ark-coding | `ARK_CODING_API_KEY` | Native | glm-5.2 (Volcengine Ark Coding Plan — GLM-5.2 (alias: `glm-latest`) · Kimi K2.7 Code / K2.6 · MiniMax M3 / M2.7 · DeepSeek V4 Pro / V4 Flash · Doubao Seed 2.0 Code / Pro / Lite · Doubao Seed Code) |
 | deepseek | `DEEPSEEK_API_KEY` | Native | deepseek-v4-flash (`deepseek-v4-pro` via `/model`) |
-| gemini-cli | `GEMINI_API_KEY` | Prompt-only / CLI bridge | (via gemini CLI) |
-| codex-cli | `OPENAI_API_KEY` | Prompt-only / CLI bridge | (via codex CLI) |
+| gemini-cli | Provider CLI authentication (no KodaX API-key variable) | Prompt-only / CLI bridge | (via gemini CLI) |
+| codex-cli | Provider CLI authentication (no KodaX API-key variable) | Prompt-only / CLI bridge | (via codex CLI) |
 
 > **Custom providers**: any OpenAI- or Anthropic-compatible endpoint can be added via `customProviders[]` in `~/.kodax/config.json` (CLI) or `registerCustomProviders()` (library). See the [Quick Start](#2-configure-a-provider) for the configuration shape.
 
@@ -1484,6 +1655,42 @@ Built-in skills include:
 - **git-workflow** - Git commit and workflow automation
 
 Skills are stored in `~/.kodax/skills/` and can be extended with custom skills.
+F263 background learning is Memory-first: a single correction does not create
+a Skill. Repeated independently verified evidence can create a low-risk,
+immutable project-scoped testing revision for at most three exact-revision
+uses. Promotion requires independently verified success. Use `/learn` to
+inspect, disable, rollback, trust, or reject learned revisions. Protected or
+formal Skills, user-global promotion, and Extension authoring remain explicit
+user actions.
+
+### Promote a learned Skill to the user catalog
+
+Automatic canary activation and user-catalog promotion are different:
+
+- independently verified canary success changes `testing` to
+  `active_learned` inside the project-scoped Learned Area;
+- `/learn promote` is an explicit ownership transfer that copies one exact
+  reviewed `ready` or `active_learned` revision into the formal user Skill
+  catalog and changes its lifecycle to `promoted_user`.
+
+Inspect the revision first, then promote it by name, slug, or exact capability
+ID:
+
+```text
+/learn show normalize-release-notes
+/learn promote normalize-release-notes --scope user
+```
+
+`--scope user` is the only supported scope and may be omitted. Invalid scopes,
+unknown options, duplicate scope options, and extra operands fail without
+changing the catalog. Promotion writes to the configured KodaX user Skill
+directory—normally `~/.kodax/skills/<slug>/SKILL.md`—and never overwrites
+different formal Skill content.
+
+Use `/learn promote --help`, `/learn help promote`, or
+`/help learn promote` for the dedicated command reference. In the Ink Learning
+Center, open `/learn`, select an `active_learned` Skill, and choose
+**Promote to user catalog**.
 
 ---