@arnilo/prism 0.3.2 → 0.5.0

package/docs/cli-rpc.md

@@ -4,13 +4,25 @@
 
 The `prism` bin is a thin adapter over `AgentSession` plus a tiny project scaffold:
 
-- `prism -p "prompt"`: print assistant text deltas.
-- `prism --mode json -p "prompt"`: write one normalized event envelope per line.
-- `prism --mode rpc`: read LF-delimited JSON requests from stdin and write correlated JSON responses/events to stdout.
+- `prism --provider <id> -p "prompt"`: print assistant text deltas. Provider ids come from the init provider catalog (`templates/init/providers.json`); `mock` is built in, real providers are dynamically imported from their `@arnilo/prism-providers/*` package (must be installed) and read their credential from the catalog's env var. Without `--provider` the CLI fails with a usage error.
+- `prism --mode json --provider <id> -p "prompt"`: write one normalized event envelope per line.
+- `prism --mode rpc --provider <id>`: read LF-delimited JSON requests from stdin and write correlated JSON responses/events to stdout.
 - `prism init <dir>`: create a minimal TypeScript project with one selected provider, `.env.example`, and one offline mock test.
+- `prism dev`: boot the loopback dev inspector over the scaffolded agent (delegates into `@arnilo/prism-coding-tools/dev` when resolvable; plan 040 Task 4).
 
 It does not add a TUI, app tools, provider globals, extension discovery, resource discovery, or credential storage. `init` uses Node standard-library filesystem APIs and checked-in templates only — no interactive prompts or template-engine dependency.
 
+## Live CLI journey (plans/064 Task 5)
+
+An env-gated e2e journey drives the packed `prism` bin end to end — `init` scaffold (generated offline test passes), `providers add` scaffold, and print/json/rpc modes over a real provider wire with a full-transcript secret scan:
+
+```bash
+PRISM_LIVE_PROVIDER_TESTS=1 OPENAI_API_KEY=sk-... \
+  node --test scripts/e2e-cli-live.test.mjs
+```
+
+The provider is the first init-catalog entry whose credential env var is present; override with `PRISM_LIVE_CLI_PROVIDER=<id>`. Wire legs skip (never fail) when the provider rejects the credential (401/403) — refresh the key and rerun. Registered in `scripts/live-matrix.json` as `cli/journey`.
+
 ## When to use it
 
 Use the CLI for terminal smoke tests, scriptable JSON event streams, simple non-Node clients that can speak newline-delimited JSON, and bootstrapping a tiny host project with `prism init`.
@@ -22,19 +34,22 @@ Use the SDK directly when an app needs custom providers, tools, resources, crede
 ### `prism init`
 
 ```bash
-prism init <dir> [--provider <name>] [--with-workflows] [--with-evals] [--force]
+prism init <dir> [--template <name>] [--list-templates] [--provider <name>] [--with-workflows] [--with-evals] [--force]
 ```
 
 | Flag / arg | Purpose |
 | --- | --- |
-| `<dir>` | Destination directory (created if missing). |
+| `<dir>` | Destination directory (created if missing). Required unless `--list-templates` is specified. |
+| `--template <name>` | Template starter name (`init` [default], `deep-research`). |
+| `--list-templates` | List available starter templates from the templates gallery. |
 | `--provider <name>` | `mock` (default), `openai`, `openrouter`, `kimi`, `zai`, `opencode-go`, or `neuralwatt`. |
-| `--with-workflows` | Add `@arnilo/prism-workflows` and `src/workflows-example.ts`. |
-| `--with-evals` | Add `@arnilo/prism-evals` and `src/evals-example.ts`. |
+| `--with-workflows` | Add `@arnilo/prism-core/runtime/workflows` and `src/workflows-example.ts`. |
+| `--with-evals` | Add `@arnilo/prism-core/governance/evals` and `src/evals-example.ts`. |
 | `--force` | Overwrite generated files when the destination already exists. |
 | `-h`, `--help` | Print init usage. |
 
-Default generation installs only `@arnilo/prism` (mock provider). Selecting a real provider adds exactly one `@arnilo/prism-provider-*` package. Storage, telemetry, memory, and server packages are never added unless a later phase introduces an explicit flag for them. Rerunning without `--force` refuses non-empty destinations and existing generated files. `.env.example` contains placeholders only; `.gitignore` excludes `.env` and local stores.
+Default generation (`init` template) installs only `@arnilo/prism` (mock provider). Selecting a real provider adds exactly one dependency: the `@arnilo/prism-providers` family package (the selected adapter imports from `@arnilo/prism-providers/<id>`). Specifying `--template deep-research` scaffolds a flagship deep research agent pipeline (`@arnilo/prism`, `@arnilo/prism-web-tools`, `@arnilo/prism-memory/rag`, `@arnilo/prism-core/runtime/workflows`) with planning, attributable citations, bounded refine loops, and HITL decision clarification. Rerunning without `--force` refuses non-empty destinations and existing generated files. `.env.example` contains placeholders only; `.gitignore` excludes `.env` and local stores.
+
 
 ### `prism providers add` (0.1.7)
 
@@ -68,6 +83,22 @@ header ownership, secret-leak redaction, and serialized-content coverage
 against the base provider. Replace the starter model metadata and the docs
 stub with docs-verified values before publishing.
 
+### `prism dev` (0.3.2)
+
+```bash
+prism dev [--port <n>] [--host <addr>]
+```
+
+Runs the local dev inspector over the current `prism init` scaffold's agent. Delegation, not duplication: the subcommand resolves `@arnilo/prism-coding-tools/dev` from the project's own `node_modules` (falling back to the CLI's own installation) and hands over to its `runDevCli` entry; unresolvable → install hint, exit `2`.
+
+| Flag / arg | Purpose |
+| --- | --- |
+| `--port <n>` | Bind port. Default `4311`. |
+| `--host <addr>` | Bind host. Default `127.0.0.1`; any non-loopback value is refused before binding (`ERR_PRISM_DEV_REMOTE_BIND`) unless remote authorization is wired programmatically. |
+| `-h`, `--help` | Print dev usage. |
+
+Manifests of the negotiation are simple: the agent is loaded from the scaffold contract `dist/agent.js` exporting `createAppAgent()` (missing → "build the project first", exit `2`); the inspector binds loopback, prints `prism dev → http://127.0.0.1:<port>/…`, and `SIGINT` drains and closes (exit `0`). Credentials stay in the scaffold's agent config — the CLI never reads environment secrets itself. Scaffolded projects ship a matching `"dev": "prism dev"` npm script.
+
 ### Run/RPC CLI flags
 
 | Flag | Purpose |
@@ -178,7 +209,10 @@ printf '{"id":"1","command":"prompt","params":{"input":"Hi"}}\n' | prism --provi
 prism init my-agent
 prism init my-agent --provider openai
 prism init my-agent --provider openrouter --with-workflows --with-evals
+prism init my-research --template deep-research
+prism init --list-templates
 cd my-agent && npm install && npm test
+
 ```
 
 Programmatic hosts should use the public runtime directly:
@@ -199,7 +233,7 @@ CLI/RPC are adapters over `AgentSession`. They do not scan packages, import exte
 
 RPC `command` executes only explicitly registered `CommandDefinition` values. `setModel` stores a model override for later prompt/follow-up calls. `compact`, `switchSession`, `forkSession`, `cloneSession`, and `checkout` call the existing session APIs.
 
-Optional workflow control (from `@arnilo/prism-workflows`) registers `workflow.start`, `workflow.enqueue`, `workflow.replay`, `workflow.status`, `workflow.list`, `workflow.cancel`, and `workflow.resume` via `createWorkflowCommands({ workflows, checkpoints, runOptions? })`. Supplying an ownership-scoped `schedules` service additionally registers `schedule.create`, `schedule.list`, `schedule.pause`, `schedule.resume`, `schedule.trigger`, and `schedule.delete`. Pass the returned `CommandDefinition[]` into `runRpcServer({ commands })` the same way as observational-memory commands. Cancel aborts in-process runs through the package active-run registry; orphaned durable checkpoints still marked `running` are fail-closed to `aborted`.
+Optional workflow control (from `@arnilo/prism-core/runtime/workflows`) registers `workflow.start`, `workflow.enqueue`, `workflow.replay`, `workflow.status`, `workflow.list`, `workflow.cancel`, and `workflow.resume` via `createWorkflowCommands({ workflows, checkpoints, runOptions? })`. Supplying an ownership-scoped `schedules` service additionally registers `schedule.create`, `schedule.list`, `schedule.pause`, `schedule.resume`, `schedule.trigger`, and `schedule.delete`. Pass the returned `CommandDefinition[]` into `runRpcServer({ commands })` the same way as observational-memory commands. Cancel aborts in-process runs through the package active-run registry; orphaned durable checkpoints still marked `running` are fail-closed to `aborted`.
 
 Suspended workflow resume parameters are `{ workflowId, runId, decision: "approve" | "deny", input?, expectedVersion, ownership? }`. Read `expectedVersion` from `workflow.status`/`workflow.list`; stale or duplicate decisions fail checkpoint CAS before node execution. Ordinary recovery resume for failed/aborted runs remains backward-compatible without decision fields.
 

package/docs/coding-agent-tools.md

@@ -2,7 +2,7 @@
 
 ## What it does
 
-`@arnilo/prism-coding-agent` is an optional first-party package that provides host shell/filesystem/repository tools as Prism `ToolDefinition` objects. It ships nine default coding tools — `shell`, `read`, `write`, `edit`, `repo_list`, `repo_search`, `glob`, `delete`, `move` — plus opt-in structured Git/check set (`createGitTools`), opt-in `createAskUserDecisionTool({ ask })`, and bounded coding-plan/checkpoint helpers. The tools are **inert** until a host imports them and registers them into a `ToolRegistry`. Hosts may register any subset, omit aggregators entirely, or mix first-party tools with host-owned `ToolDefinition`s. Behavior for shell/read/write/edit is a behavioral port of the pi coding agent's tools, adapted to Prism's `ToolDefinition` / `ToolResult` contracts (no `@earendil-works/*` or `typebox` dependencies; only `diff` plus the Node standard library). List/search/glob/Git are native Prism tools with no picomatch/ripgrep/Git-library dependency (hand-rolled `*`/`?`/`**` glob matcher).
+`@arnilo/prism-coding-tools/agent` is an optional first-party package that provides host shell/filesystem/repository tools as Prism `ToolDefinition` objects. It ships nine default coding tools — `shell`, `read`, `write`, `edit`, `repo_list`, `repo_search`, `glob`, `delete`, `move` — plus opt-in structured Git/check set (`createGitTools`), opt-in `createAskUserDecisionTool({ ask })`, and bounded coding-plan/checkpoint helpers. The tools are **inert** until a host imports them and registers them into a `ToolRegistry`. Hosts may register any subset, omit aggregators entirely, or mix first-party tools with host-owned `ToolDefinition`s. Behavior for shell/read/write/edit is a behavioral port of the pi coding agent's tools, adapted to Prism's `ToolDefinition` / `ToolResult` contracts (no `@earendil-works/*` or `typebox` dependencies; only `diff` plus the Node standard library). List/search/glob/Git are native Prism tools with no picomatch/ripgrep/Git-library dependency (hand-rolled `*`/`?`/`**` glob matcher).
 
 | Export | Purpose |
 | --- | --- |
@@ -44,7 +44,7 @@ Each factory returns a plain `ToolDefinition` (no auto-registration). Register w
 
 ```ts
 import { createToolRegistry } from "@arnilo/prism";
-import { createCodingTools } from "@arnilo/prism-coding-agent";
+import { createCodingTools } from "@arnilo/prism-coding-tools/agent";
 
 const tools = createToolRegistry(createCodingTools(process.cwd()));
 ```
@@ -56,7 +56,7 @@ Every tool carries an explicit `kind` (`shell`→`execute`, `read`/`repo_list`
 `createAcpFilesystemOperations` adapts any client with `readTextFile({ path, line?, limit? })` and `writeTextFile({ path, content })` methods to the `ReadOperations`, `WriteOperations`, and `EditOperations` seams. All reads and writes stay client-backed; `mkdir` is a no-op, `statFile` measures a bounded UTF-8 text read, and image MIME detection is always `null`.
 
 ```ts
-import { createAcpFilesystemOperations, createCodingTools } from "@arnilo/prism-coding-agent";
+import { createAcpFilesystemOperations, createCodingTools } from "@arnilo/prism-coding-tools/agent";
 
 const operations = createAcpFilesystemOperations(clientFilesystem);
 const tools = createCodingTools(cwd, {
@@ -72,11 +72,11 @@ This is an editor-buffer adapter, not a repository backend: `repo_list`, `repo_s
 
 Use this package when a host wants ready-made coding tools for an agent, session, or run, registered explicitly into a `ToolRegistry` and dispatched through the normal Prism tool harness. The tools perform **real** shell and filesystem operations on the host — they are not mocked or sandboxed. Use the individual factories when you need per-tool options or custom operation backends; use the aggregators when you want the default set.
 
-Do not use this package as a sandbox, permission policy, secret store, or provider loop. Prism gates tool dispatch with `PermissionPolicy` / `ToolValidator` / trust policies; pass an optional `ExecutionPolicy` (for example from `@arnilo/prism-coding-security`) for path/command approval before side effects. Do not register these tools for an untrusted provider.
+Do not use this package as a sandbox, permission policy, secret store, or provider loop. Prism gates tool dispatch with `PermissionPolicy` / `ToolValidator` / trust policies; pass an optional `ExecutionPolicy` (for example from `@arnilo/prism-coding-tools/security`) for path/command approval before side effects. Do not register these tools for an untrusted provider.
 
 ```ts
-import { createCodingTools } from "@arnilo/prism-coding-agent";
-import { createCodingApprovalPolicy } from "@arnilo/prism-coding-security";
+import { createCodingTools } from "@arnilo/prism-coding-tools/agent";
+import { createCodingApprovalPolicy } from "@arnilo/prism-coding-tools/security";
 
 const tools = createCodingTools(workspaceRoot, {
   executionPolicy: createCodingApprovalPolicy({
@@ -88,7 +88,7 @@ const tools = createCodingTools(workspaceRoot, {
 
 ### pi name mapping
 
-| Prism (`@arnilo/prism-coding-agent`) | pi coding agent |
+| Prism (`@arnilo/prism-coding-tools/agent`) | pi coding agent |
 | --- | --- |
 | `shell` | `bash` |
 | `read` | `read` |
@@ -180,7 +180,7 @@ Read a text or image file.
 | `executionPolicy` | — | Structured pre-execution policy (see [Coding security](coding-security.md)). |
 
 ```ts
-import { createReadTool, DEFAULT_MAX_IMAGE_BYTES } from "@arnilo/prism-coding-agent";
+import { createReadTool, DEFAULT_MAX_IMAGE_BYTES } from "@arnilo/prism-coding-tools/agent";
 
 const read = createReadTool(cwd, {
   maxImageBytes: DEFAULT_MAX_IMAGE_BYTES,
@@ -229,7 +229,7 @@ Default local `writeFile` uses same-directory temp + `rename` so a crash mid-wri
 Hosts may opt in to a session-scoped soft guard: share one `createReadPathSet()` across `read` / `write` / `edit` and set `requireReadBeforeWrite: true` on write/edit options. Successful `read` marks the path; unread existing-file writes/edits fail with a clear error unless `force: true`. Default is **off** (no behavior change for hosts that ignore it).
 
 ```ts
-import { createReadPathSet, createReadTool, createWriteTool, createEditTool } from "@arnilo/prism-coding-agent";
+import { createReadPathSet, createReadTool, createWriteTool, createEditTool } from "@arnilo/prism-coding-tools/agent";
 
 const readPaths = createReadPathSet();
 const read = createReadTool(cwd, { readPathSet: readPaths });
@@ -240,7 +240,7 @@ const edit = createEditTool(cwd, { requireReadBeforeWrite: true, readPathSet: re
 Since 0.1.3 (plan 015 Task 4) hosts may opt in to persisting the set across restarts via the host-owned `CheckpointStore`:
 
 ```ts
-import { createReadPathSet, createReadPathSetPersistence } from "@arnilo/prism-coding-agent";
+import { createReadPathSet, createReadPathSetPersistence } from "@arnilo/prism-coding-tools/agent";
 
 const readPaths = createReadPathSet();
 const persistence = createReadPathSetPersistence({ checkpoints, key: sessionId, ownership });
@@ -287,7 +287,7 @@ List repository entries with deterministic relative paths. Uses Node `opendir`/`
 - **Security:** `.git` internals never listed; paths re-checked against the workspace root; symlink escapes match native fail-closed behavior.
 
 ```ts
-import { createCodingTools, createGitAwareRepositoryOperations } from "@arnilo/prism-coding-agent";
+import { createCodingTools, createGitAwareRepositoryOperations } from "@arnilo/prism-coding-tools/agent";
 
 const operations = createGitAwareRepositoryOperations(cwd); // native fallback outside Git
 const tools = createCodingTools(cwd, { repository: { operations } });
@@ -392,7 +392,7 @@ Opt-in tools over a host-pinned Git executable (`gitPath`, default `/usr/bin/git
 | `coding_check` | Included when `checks` are declared: model selects only a name; executable/args/env are host-fixed. |
 
 ```ts
-import { createGitTools } from "@arnilo/prism-coding-agent";
+import { createGitTools } from "@arnilo/prism-coding-tools/agent";
 
 const gitTools = createGitTools(workspaceRoot, {
   gitPath: "/usr/bin/git",
@@ -431,7 +431,7 @@ import {
   createCodingTools,
   suspendAskUserDecision,
   createAskUserDecisionResumeValidator,
-} from "@arnilo/prism-coding-agent";
+} from "@arnilo/prism-coding-tools/agent";
 
 const tools = createToolRegistry([
   ...createCodingTools(workspaceRoot),
@@ -453,10 +453,10 @@ return suspendAskUserDecision({
 
 ### Goal → verify helper (`runCodingGoalVerify`)
 
-Thin composition over existing plan Markdown, named checks, workflow `suspend`/`resumeWorkflow`, and bounded PR handoff. **No Goal table / second runtime.** Peer `@arnilo/prism-workflows`. Example: `examples/coding-goal-verify.ts`.
+Thin composition over existing plan Markdown, named checks, workflow `suspend`/`resumeWorkflow`, and bounded PR handoff. **No Goal table / second runtime.** Peer `@arnilo/prism-core/runtime/workflows`. Example: `examples/coding-goal-verify.ts`.
 
 ```ts
-import { runCodingGoalVerify } from "@arnilo/prism-coding-agent";
+import { runCodingGoalVerify } from "@arnilo/prism-coding-tools/agent";
 
 const result = await runCodingGoalVerify({
   goal: "Fix the flake",
@@ -524,7 +524,7 @@ Minimal drop-in for any Prism app:
 
 ```ts
 import { createToolRegistry } from "@arnilo/prism";
-import { createCodingTools, createReadOnlyTools } from "@arnilo/prism-coding-agent";
+import { createCodingTools, createReadOnlyTools } from "@arnilo/prism-coding-tools/agent";
 
 // Full coding set (shell + read + write + edit + repo_list + repo_search + glob + delete + move):
 const tools = createToolRegistry(createCodingTools(process.cwd()));
@@ -536,7 +536,7 @@ const ro = createToolRegistry(createReadOnlyTools(process.cwd()));
 Customizing a single tool (force bash, cap output, delegate writes to a remote backend):
 
 ```ts
-import { createShellTool, createWriteTool } from "@arnilo/prism-coding-agent";
+import { createShellTool, createWriteTool } from "@arnilo/prism-coding-tools/agent";
 
 const shell = createShellTool("/repo", {
   shellPath: "/bin/bash",
@@ -560,11 +560,11 @@ Packed capability demo: `examples/coding-tools-capability-gaps.ts` (search modes
 
 ## Extension and configuration notes
 
-- **Long coding sessions.** Use `createCodingCompactionStrategy()` from optional `@arnilo/prism-compaction-llm` when history needs a bounded coding handoff. It is selected explicitly through normal `session.compact()` / agent compaction configuration, preserves raw session entries, and prioritizes file paths, patch intent, checks, plan/todo state, blockers, and verification steps. It does not read files, retain full diffs, or create a second coding runtime.
+- **Long coding sessions.** Use `createCodingCompactionStrategy()` from optional `@arnilo/prism-memory/compaction/llm` when history needs a bounded coding handoff. It is selected explicitly through normal `session.compact()` / agent compaction configuration, preserves raw session entries, and prioritizes file paths, patch intent, checks, plan/todo state, blockers, and verification steps. It does not read files, retain full diffs, or create a second coding runtime.
 - **Pluggable operation backends.** Every tool accepts an `operations` seam. Custom `ReadOperations` must implement bounded `readText` plus `statFile`; custom `EditOperations` must implement `statFile`; read/write methods receive caps/signals. `BashOperations` must stream through `onData` and honor `signal`/`timeout`. Custom `RepositoryOperations` must honor depth/entry/file/match/scan/time caps and abort (including `glob`). Custom `DeleteOperations` / `MoveOperations` must honor containment and abort. A hostile custom backend can still violate its host-owned contract, so isolate it separately.
 - **Per-tool options.** `ShellToolOptions` adds `timeout` and `maxTotalOutputBytes`; `ReadToolOptions` adds `maxScanBytes` and optional `readPathSet`; `WriteToolOptions` / `EditToolOptions` add input caps plus optional `requireReadBeforeWrite` / `readPathSet` / `force`; list/search/glob accept `repository` limits and shared aggregator `ToolsOptions.repository`.
 - **Aggregator options.** `ToolsOptions` (`{ executionPolicy?, shell?, read?, write?, edit?, delete?, move?, list?, search?, glob?, repository? }`) threads each sub-object to the matching tool. `createCodingTools()`, `createAllTools()`, and `createReadOnlyTools()` apply the shared policy unless that tool has an explicit per-tool override. Full membership is nine tools; read-only is `read` + `repo_list` + `repo_search` + `glob`.
-- **Sandbox composition.** Prefer `@arnilo/prism-coding-security` `createSandboxCodingComposition(cwd, { workspaceMode, sandbox, ... })` (or tools-only wrappers). `workspaceMode` is required: `"sandbox"` keeps shell/read/write/edit/list/search/glob/delete/move on one disposable tree; `"host"` runs against host cwd and never claims containment. Mixed sandbox-shell + host-FS wiring throws unless `allowMixedWorkspaceWiring: true`. Same-tree Git: `createGitTools(composition.workspaceRoot, { execFile: sandbox.execFile, commitIdentity })`.
+- **Sandbox composition.** Prefer `@arnilo/prism-coding-tools/security` `createSandboxCodingComposition(cwd, { workspaceMode, sandbox, ... })` (or tools-only wrappers). `workspaceMode` is required: `"sandbox"` keeps shell/read/write/edit/list/search/glob/delete/move on one disposable tree; `"host"` runs against host cwd and never claims containment. Mixed sandbox-shell + host-FS wiring throws unless `allowMixedWorkspaceWiring: true`. Same-tree Git: `createGitTools(composition.workspaceRoot, { execFile: sandbox.execFile, commitIdentity })`.
 - **`ToolsOptions`** and the per-tool option types are exported from the package barrel for host configuration.
 - No auto-discovery or manifest registration: import and register explicitly. This package registers no extensions and owns no globals (the mutation queue is a process-wide per-path map — see `ponytail:` note in the source).
 

package/docs/coding-review-and-diagnostics.md

@@ -19,8 +19,8 @@ Bounded patch-review manifests plus normalized LSP/check diagnostics for the cod
 A review is created per patch handoff. The manifest binds: repository identity (credential-free remote fingerprint + default branch + optional worktree path), `base`/`head`, the patch artifact reference (`kind`, `uri`, `sha256`, `bytes`), changed paths, diffstat, named-check summaries, and diagnostic summaries. The `digest` is SHA-256 over the canonical manifest JSON; the structural artifact input carries the manifest in `preview.review` and the patch SHA-256 as the artifact hash.
 
 ```ts
-import { createCodingPatchReviewManifest, assertCodingPatchAccepted } from "@arnilo/prism-coding-agent";
-import { createArtifactService } from "@arnilo/prism-server";
+import { createCodingPatchReviewManifest, assertCodingPatchAccepted } from "@arnilo/prism-coding-tools/agent";
+import { createArtifactService } from "@arnilo/prism-core/runtime/server";
 
 const { review, artifactInput } = createCodingPatchReviewManifest({
   threadId: "thread-1",

package/docs/coding-security.md

@@ -2,7 +2,7 @@
 
 ## What it does
 
-`@arnilo/prism-coding-security` is an optional package that supplies structured execution policy for `@arnilo/prism-coding-agent` tools and one disposable Docker/OCI sandbox reference. It complements name-based `PermissionPolicy` at dispatch time with path/command context checked **inside** each tool before side effects, and optionally contains untrusted coding work in a host-invoked container.
+`@arnilo/prism-coding-tools/security` is an optional package that supplies structured execution policy for `@arnilo/prism-coding-tools/agent` tools and one disposable Docker/OCI sandbox reference. It complements name-based `PermissionPolicy` at dispatch time with path/command context checked **inside** each tool before side effects, and optionally contains untrusted coding work in a host-invoked container.
 
 | Export | Purpose |
 | --- | --- |
@@ -43,7 +43,7 @@ Use `createEgressPolicy()` + `createAllowListEgressProxy()` when a coding agent
 `createEgressPolicy({ allow, presets })` builds a deny-all policy. Rules are exact `{ host, port, protocol }` triples — no wildcards, no CIDR, no regex. Presets (`npm-registry`, `github`) expand to explicit rule lists at construction. The policy exposes a stable SHA-256 `fingerprint` over the canonical rule set.
 
 ```ts
-import { createEgressPolicy, createAllowListEgressProxy } from "@arnilo/prism-coding-security";
+import { createEgressPolicy, createAllowListEgressProxy } from "@arnilo/prism-coding-tools/security";
 
 const policy = createEgressPolicy({
   allow: [{ host: "api.github.com", port: 443, protocol: "https" }],
@@ -144,8 +144,8 @@ import {
   createCodingApprovalPolicy,
   createDockerSandbox,
   createSandboxCodingComposition,
-} from "@arnilo/prism-coding-security";
-import { createGitTools } from "@arnilo/prism-coding-agent";
+} from "@arnilo/prism-coding-tools/security";
+import { createGitTools } from "@arnilo/prism-coding-tools/agent";
 
 const policy = createCodingApprovalPolicy({
   roots: [workspaceRoot],
@@ -194,7 +194,7 @@ await sandbox.close({
 
 Policies are ordinary host values: attach one globally through `createCodingTools()`/`createReadOnlyTools()`/`createSandboxCodingComposition()` or per tool. A per-tool policy overrides the shared policy. `SandboxAdapter` / `DisposableSandbox` are replaceable and host-owned; approval policy and sandboxing are separate layers. Custom remote sandboxes can implement `DisposableSandbox` without using Docker.
 
-`createSandboxCodingComposition()` requires `workspaceMode`. Sandbox mode auto-wires FS/list/search through `DisposableSandbox.execFile` (or host-supplied custom operations) so mutations stay on the disposable tree until export. Host mode runs every coding tool against the host cwd and reports no isolation capability (`containmentClaim` deprecated false). Sandbox shell + host FS throws unless `allowMixedWorkspaceWiring: true` (warnings + all capabilities false). Opt-in structured Git tools (`createGitTools(composition.workspaceRoot, { execFile: sandbox.execFile, commitIdentity })`) share the same tree/cwd; Prism still never pushes or opens PRs. Optional `@arnilo/prism-browser` can share the same disposable boundary: use `assertBrowserSandboxNetwork()` before browse-ready custom networks, and `createSharedSandboxBrowserOptions({ workspaceRoot, downloadsRoot, containedProxyAttestation })` so uploads/downloads align with `/workspace` and `/downloads`. Close the browser context before disposing the sandbox.
+`createSandboxCodingComposition()` requires `workspaceMode`. Sandbox mode auto-wires FS/list/search through `DisposableSandbox.execFile` (or host-supplied custom operations) so mutations stay on the disposable tree until export. Host mode runs every coding tool against the host cwd and reports no isolation capability (`containmentClaim` deprecated false). Sandbox shell + host FS throws unless `allowMixedWorkspaceWiring: true` (warnings + all capabilities false). Opt-in structured Git tools (`createGitTools(composition.workspaceRoot, { execFile: sandbox.execFile, commitIdentity })`) share the same tree/cwd; Prism still never pushes or opens PRs. Optional `@arnilo/prism-web-tools/browser` can share the same disposable boundary: use `assertBrowserSandboxNetwork()` before browse-ready custom networks, and `createSharedSandboxBrowserOptions({ workspaceRoot, downloadsRoot, containedProxyAttestation })` so uploads/downloads align with `/workspace` and `/downloads`. Close the browser context before disposing the sandbox.
 
 The Docker reference adapter starts by recorded container ID/label, uses argument arrays only, mounts source read-only, populates a size-bounded tmpfs `/workspace`, drops all capabilities, enables `no-new-privileges`, runs with `--init`, and never exposes the Docker socket, privileged mode, or host PID/IPC namespaces. Image pull/build/update stays outside Prism. Protected real-Docker checks are opt-in via `PRISM_TEST_DOCKER_SANDBOX=1` with host-supplied `PRISM_TEST_DOCKER_BIN` and digest-pinned `PRISM_TEST_DOCKER_IMAGE`.
 

package/docs/coding-tools.md

@@ -0,0 +1,82 @@
+# Coding Tools, Sandboxing, and Personas (@arnilo/prism-coding-tools)
+
+The `@arnilo/prism-coding-tools` family package unifies Prism's coding agent tools, security sandboxing, document reading, OpenAPI integration, Linux desktop automation, Dev inspector, and persona extensions into explicit, import-isolated subpaths.
+
+## Installation
+
+```bash
+npm install @arnilo/prism @arnilo/prism-coding-tools
+```
+
+For document reading or specialized persona integrations, install the optional peer dependencies as needed:
+
+```bash
+# PDF and DOCX document extraction
+npm install pdf-parse mammoth
+
+# Ponytail upstream integration
+npm install @dietrichgebert/ponytail
+```
+
+## Subpaths Map
+
+| Subpath | Description | Optional Peers |
+|---|---|---|
+| `@arnilo/prism-coding-tools/agent` | Core coding tools (read, write, edit, search, bash, git, diagnostics, check, ast-grep, lsp) | — |
+| `@arnilo/prism-coding-tools/security` | Sandbox execution adapters (Docker/OCI, native disposable sandbox, approval policies, egress proxy) | — |
+| `@arnilo/prism-coding-tools/document-reader` | Bounded PDF/DOCX literal-text extraction adapter with fail-closed loading | `pdf-parse`, `mammoth` |
+| `@arnilo/prism-coding-tools/openapi` | OpenAPI 3.x tool generator and executor with SSRF protection and parameter validation | — |
+| `@arnilo/prism-coding-tools/computer-use-linux` | Linux desktop observation and targeting tool bridge | — |
+| `@arnilo/prism-coding-tools/dev` | Loopback-only developer inspector, event timeline visualizer, and local replay server | — |
+| `@arnilo/prism-coding-tools/dev/cli` | Command-line entrypoint for `prism dev` | — |
+| `@arnilo/prism-coding-tools/caveman` | Caveman ultra-terse engineering persona extension | — |
+| `@arnilo/prism-coding-tools/ponytail` | Ponytail multi-agent planning and delegation persona extension | `@dietrichgebert/ponytail` |
+| `@arnilo/prism-coding-tools/impeccable` | Impeccable high-precision frontend engineering persona extension | — |
+
+## CLI
+
+```bash
+# Start the loopback dev inspector
+npx prism-dev --port 4311
+```
+
+## Usage Examples
+
+### Creating Coding Tools
+```ts
+import { createCodingTools } from "@arnilo/prism-coding-tools/agent";
+
+const tools = createCodingTools({
+  workspaceRoot: process.cwd(),
+});
+```
+
+### Sandboxed Execution
+```ts
+import { createDockerSandbox, createSandboxCodingComposition } from "@arnilo/prism-coding-tools/security";
+
+const composition = createSandboxCodingComposition({
+  workspaceMode: "sandbox",
+  sandbox: createDockerSandbox({
+    image: "node:20-alpine@sha256:...",
+    workspaceRoot: process.cwd(),
+  }),
+});
+```
+
+### Persona Extensions
+```ts
+import { createCavemanExtension } from "@arnilo/prism-coding-tools/caveman";
+import { createPonytailExtension } from "@arnilo/prism-coding-tools/ponytail";
+import { createImpeccableExtension } from "@arnilo/prism-coding-tools/impeccable";
+
+const caveman = createCavemanExtension();
+const ponytail = createPonytailExtension();
+const impeccable = createImpeccableExtension();
+```
+
+## Security & Import Isolation
+
+- Importing `@arnilo/prism-coding-tools/agent` never loads Docker sandbox adapters, desktop MCP bridges, document parser peers, or Dev inspector modules.
+- Document parser peers (`pdf-parse`, `mammoth`) and Ponytail optional peer fail closed when absent.
+- Persona extensions are pure prompt and behavior modifiers and never gain implicit host privileges.

package/docs/coding-workspaces.md

@@ -1,13 +1,13 @@
 # Coding workspaces
 
-Ownership-scoped multi-repository and worktree lifecycle (plan 026 Task 3, `@arnilo/prism-coding-agent`). A durable coding workspace correlates task/session/run identity with host repositories and linked worktrees so that resume, cleanup, artifacts, and recovery stay bounded and reconcilable.
+Ownership-scoped multi-repository and worktree lifecycle (plan 026 Task 3, `@arnilo/prism-coding-tools/agent`). A durable coding workspace correlates task/session/run identity with host repositories and linked worktrees so that resume, cleanup, artifacts, and recovery stay bounded and reconcilable.
 
 The lifecycle composes existing bounded primitives only: `CheckpointStore` CAS records in a separate versioned namespace (`prism.coding-agent.workspace.v1`), `LeaseStore` fencing, and cwd-bound `GitOperations` runners. There is no clone manager, Git library, watcher, new database schema, or second task runtime.
 
 ## Activation
 
 ```ts
-import { createCodingWorkspaceLifecycle } from "@arnilo/prism-coding-agent";
+import { createCodingWorkspaceLifecycle } from "@arnilo/prism-coding-tools/agent";
 
 const workspaces = createCodingWorkspaceLifecycle({
   checkpoints,                 // CheckpointStore (ownership-scoped)

package/docs/compaction-and-retry.md

@@ -149,11 +149,11 @@ await session.compact({ keepRecentEntries: 4 });
 
 ## Extension and configuration notes
 
-Retry policies are ordinary `RetryPolicy` implementations and can be registered as `retryPolicy` contributions. Hosts must still pass the selected policy/config to `createAgent()` or `session.run()`. Retry middleware receives `{ context, decision }` before a retry is scheduled and can reduce delay or stop retrying. First-party providers emit `ErrorInfo.code` as the numeric HTTP status so the default policy's transient-code set (`429`/`500`/`502`/`503`) classifies retryability without provider-specific core branches; `@arnilo/prism-provider-neuralwatt` additionally exports `classifyNeuralWattError()` for hosts that want structured `Retry-After`/`retry_strategy` metadata.
+Retry policies are ordinary `RetryPolicy` implementations and can be registered as `retryPolicy` contributions. Hosts must still pass the selected policy/config to `createAgent()` or `session.run()`. Retry middleware receives `{ context, decision }` before a retry is scheduled and can reduce delay or stop retrying. First-party providers emit `ErrorInfo.code` as the numeric HTTP status so the default policy's transient-code set (`429`/`500`/`502`/`503`) classifies retryability without provider-specific core branches; `@arnilo/prism-providers/neuralwatt` additionally exports `classifyNeuralWattError()` for hosts that want structured `Retry-After`/`retry_strategy` metadata.
 
 Compaction strategies are ordinary `CompactionStrategy` implementations. Extensions can register strategies through the existing compaction strategy contribution registry, but registration is inert until a host explicitly selects and passes a strategy to runtime code. Extensions can also register `compaction` middleware; the runtime calls it only when the agent/session has that middleware registry configured.
 
-The default strategy does not call a provider. Hosts that need model-generated summaries can use the optional [`@arnilo/prism-compaction-llm` package](compaction-llm.md); its `maxOutputTokens`/`maxSummaryTokens` budget is passed through `model.parameters.maxTokens` and first-party providers serialize that to provider output-token fields. Coding sessions can select that package's `createCodingCompactionStrategy()` preset for paths, patch intent, checks, plans/todos, blockers, and next verification steps; it remains an ordinary `CompactionStrategy` and does not retain complete diffs or add a coding runtime. Hosts that need prepared source-backed memory without a compaction-time model call can use [`@arnilo/prism-compaction-observational-memory`](compaction-observational-memory.md).
+The default strategy does not call a provider. Hosts that need model-generated summaries can use the optional [`@arnilo/prism-memory/compaction/llm` subpath](compaction-llm.md); its `maxOutputTokens`/`maxSummaryTokens` budget is passed through `model.parameters.maxTokens` and first-party providers serialize that to provider output-token fields. Coding sessions can select that package's `createCodingCompactionStrategy()` preset for paths, patch intent, checks, plans/todos, blockers, and next verification steps; it remains an ordinary `CompactionStrategy` and does not retain complete diffs or add a coding runtime. Hosts that need prepared source-backed memory without a compaction-time model call can use [`@arnilo/prism-memory/compaction/observational-memory`](compaction-observational-memory.md).
 
 ## Security and performance notes
 

package/docs/compaction-llm.md

@@ -1,7 +1,7 @@
 # LLM compaction package
 
 ## What it does
-`@arnilo/prism-compaction-llm` is an optional provider-backed compaction package. It prepares branch history, calls an explicit summary provider/model, and returns a standard Prism `CompactionStrategy`. The core default compaction remains local and conservative.
+`@arnilo/prism-memory/compaction/llm` is an optional provider-backed compaction subpath. It prepares branch history, calls an explicit summary provider/model, and returns a standard Prism `CompactionStrategy`. The core default compaction remains local and conservative.
 
 ## When to use it
 Use it when a host wants model-generated summaries while preserving raw append-only session history. Do not use it as a core default, provider SDK loader, hidden credential discovery layer, vector memory, or store rewrite.
@@ -59,7 +59,7 @@ Provider `error` events, empty summaries, or abort signals throw before returnin
 
 ## Implementation example
 ```ts
-import { createLlmCompactionStrategy } from "@arnilo/prism-compaction-llm";
+import { createLlmCompactionStrategy } from "@arnilo/prism-memory/compaction/llm";
 
 const strategy = createLlmCompactionStrategy({
   provider: summaryProvider,
@@ -80,7 +80,7 @@ await session.compact({ strategy, secrets: [apiKey] });
 Coding-session example:
 
 ```ts
-import { createCodingCompactionStrategy } from "@arnilo/prism-compaction-llm";
+import { createCodingCompactionStrategy } from "@arnilo/prism-memory/compaction/llm";
 
 const strategy = createCodingCompactionStrategy({
   provider: summaryProvider,
@@ -110,7 +110,7 @@ This package is inert until imported. Direct strategy use works with `session.co
 
 ```ts
 import { createAgent, createExtensionKernel } from "@arnilo/prism";
-import { createLlmCompactionExtension } from "@arnilo/prism-compaction-llm";
+import { createLlmCompactionExtension } from "@arnilo/prism-memory/compaction/llm";
 
 const kernel = createExtensionKernel();
 await kernel.load([createLlmCompactionExtension({ provider: summaryProvider, model: summaryModel })]);

package/docs/compaction-observational-memory.md

@@ -2,7 +2,7 @@
 
 ## What it does
 
-`@arnilo/prism-compaction-observational-memory` is an optional package for source-backed observational memory and fast compaction.
+`@arnilo/prism-memory/compaction/observational-memory` is an optional subpath for source-backed observational memory and fast compaction.
 
 Current status: ledger/projection/render/recall utilities, explicit worker runtime, fast compaction strategy, inert extension helper, recall tool, and status/view command factories are available.
 
@@ -107,7 +107,7 @@ import {
   createRecallMemoryTool,
   recallObservationalMemory,
   renderObservationalMemory,
-} from "@arnilo/prism-compaction-observational-memory";
+} from "@arnilo/prism-memory/compaction/observational-memory";
 
 const om = createObservationalMemory({
   observation: { provider: observerProvider, model: observerModel, messageTokens: 10_000 },
@@ -174,7 +174,7 @@ Hosts that need parent recall of child *source* work compose it themselves: wrap
 
 ```ts
 import { createId, type SessionStore } from "@arnilo/prism";
-import { isEligibleObservationSourceEntry } from "@arnilo/prism-compaction-observational-memory";
+import { isEligibleObservationSourceEntry } from "@arnilo/prism-memory/compaction/observational-memory";
 
 function funnelChildMessagesToWorkspace(store: SessionStore, workspaceSessionId: string): SessionStore {
   return {

package/docs/computer-use-linux.md

@@ -2,7 +2,7 @@
 
 ## What it does
 
-`@arnilo/prism-computer-use-linux` wraps the host-owned [`computer-use-linux`](https://github.com/agent-sh/computer-use-linux) MCP binary as Prism `ToolDefinition`s. It connects over stdio only when `createComputerUseLinuxTools()` is called, keeps upstream tool names, filters unknown tools, and composes desktop admission, execution approval, result bounds, serialization, redaction, and trust labeling over Prism's existing seams.
+`@arnilo/prism-coding-tools/computer-use-linux` wraps the host-owned [`computer-use-linux`](https://github.com/agent-sh/computer-use-linux) MCP binary as Prism `ToolDefinition`s. It connects over stdio only when `createComputerUseLinuxTools()` is called, keeps upstream tool names, filters unknown tools, and composes desktop admission, execution approval, result bounds, serialization, redaction, and trust labeling over Prism's existing seams.
 
 The package also exports `loadComputerUseLinuxSkill()`, which loads the short Prism-authored desktop procedure bundled at `skills/computer-use-linux/SKILL.md`. It does not resolve or vendor an upstream skill tree.
 
@@ -75,7 +75,7 @@ import { createToolRegistry, type Skill } from "@arnilo/prism";
 import {
   createComputerUseLinuxTools,
   loadComputerUseLinuxSkill,
-} from "@arnilo/prism-computer-use-linux";
+} from "@arnilo/prism-coding-tools/computer-use-linux";
 
 async function installDesktop(hostSkills: { register(skill: Skill): void }, hostApproved: boolean) {
   const desktop = await createComputerUseLinuxTools({
@@ -112,6 +112,17 @@ async function installDesktop(hostSkills: { register(skill: Skill): void }, host
 - Imports are inert. The default setup surface is off, the skill file is capped at 64 KiB, and no full upstream skill tree is shipped.
 - The host must keep credentials, desktop session state, binary paths, sandbox identity, and approval state outside model-controlled arguments.
 
+## Live probe (plans/064 Task 7)
+
+A live leg drives the host's real `computer-use-linux` MCP binary over stdio — real tool inventory, one bounded read-only screenshot, clean close (≤30 s):
+
+```bash
+PRISM_TEST_COMPUTER_USE=1 PRISM_COMPUTER_USE_BIN="$(command -v computer-use-linux)" \
+  node --test packages/prism-coding-tools/dist/computer-use-linux/__tests__/live.test.js
+```
+
+Skips (never fails) when the flag, binary path, or a desktop session is unavailable. The suite performs no network I/O, so screenshot bytes cannot leave the process. Registered in `scripts/live-matrix.json` as `coding-tools/computer-use-live`.
+
 ## Related APIs
 
 - [Device adapters](device-adapters.md): generic admission, shared limits, chunk bounds, and telemetry redaction contract.

package/docs/context-and-skills.md

@@ -158,6 +158,8 @@ Skill selection grants no tool access and cannot bypass permissions — a skill'
 
 ### Progressive skill disclosure
 
+Skills apply the same progressive-disclosure discipline as plan 041's [tool disclosure](tools.md) (toolsDisclosure "search") — one mechanism applied to skills (prompt text) and tools (provider tool arrays).
+
 `skillsDisclosure` on `AgentConfig` / `RunOptions` (`"progressive"` default, `"eager"` opt-in; run wins) controls how active skills render in provider input:
 
 | Mode | Provider view per active skill |
@@ -198,7 +200,7 @@ await agent.createSession().run("…", { activeSkills: ["ponytail"] });
 
 ### Third-party behavior packages (Caveman, Ponytail, Impeccable)
 
-`@arnilo/prism-caveman` and `@arnilo/prism-ponytail` register upstream skills into the extension kernel skill registry. Hosts should:
+`@arnilo/prism-coding-tools/caveman` and `@arnilo/prism-coding-tools/ponytail` register upstream skills into the extension kernel skill registry. Hosts should:
 
 1. `kernel.load([createCavemanExtension(...), createPonytailExtension(...)])` with session `appendEntry` / `getEntries` callbacks.
 2. Build `createSkillRegistry(kernel.registries.skills.list())` and pass `activeSkills` / `resolveActiveSkills` names.

package/docs/conversations.md

@@ -2,9 +2,9 @@
 
 ## What it does
 
-`@arnilo/prism-server` ships a durable, user-scoped conversation service: create/list/get/continue/branch/archive/export/delete conversation threads on top of the existing session and event-ledger seams. A thread **is** an ownership-scoped session branch plus a `prismConversation` marker in `SessionRecord.metadata`; content stays in session entries and the redacted event ledger. Reconnectable replay pages durable redacted events without ever rerunning a provider or tool.
+`@arnilo/prism-core/runtime/server` ships a durable, user-scoped conversation service: create/list/get/continue/branch/archive/export/delete conversation threads on top of the existing session and event-ledger seams. A thread **is** an ownership-scoped session branch plus a `prismConversation` marker in `SessionRecord.metadata`; content stays in session entries and the redacted event ledger. Reconnectable replay pages durable redacted events without ever rerunning a provider or tool.
 
-Core (`@arnilo/prism`) exports only conversation **types and pure helpers** (`ConversationThread`, `ConversationError`, `CONVERSATION_METADATA_KEY`, thread-bound replay cursor codec, `conversationThreadFromRecord`, `conversationMarkerMetadata`). The service and optional HTTP handler live in `@arnilo/prism-server`.
+Core (`@arnilo/prism`) exports only conversation **types and pure helpers** (`ConversationThread`, `ConversationError`, `CONVERSATION_METADATA_KEY`, thread-bound replay cursor codec, `conversationThreadFromRecord`, `conversationMarkerMetadata`). The service and optional HTTP handler live in `@arnilo/prism-core/runtime/server`.
 
 ## When to use it
 
@@ -15,8 +15,8 @@ Do not use it as a chat UI, a push/always-on daemon, or a file store. Slack/Team
 ## Inputs / request
 
 ```ts
-import { createConversationService, createConversationHandler } from "@arnilo/prism-server";
-import { createSqlitePersistence } from "@arnilo/prism-session-store-sqlite";
+import { createConversationService, createConversationHandler } from "@arnilo/prism-core/runtime/server";
+import { createSqlitePersistence } from "@arnilo/prism-core/sessions/sqlite";
 
 const persistence = createSqlitePersistence({ filename }); // implements ConversationServiceStore
 const service = createConversationService(persistence, {