@arnilo/prism 0.7.0 → 0.9.0

package/docs/attention-compiler.md

@@ -48,16 +48,17 @@ await session.run("cheap run", { attentionCompiler: { triggerRatio: 0.95, compac
 The agent setting is resolved with the run's model at run start, before any provider turn, so a malformed setting or a widening overlay fails the run immediately instead of on the turn that crosses the ratio:
 
 - **Allowed in the overlay:** `triggerRatio` / `compactRatio` at or above the agent setting, `keepLast` / `thinkingKeepTurns` at or below it, and extra `excludeTools` (unioned with the agent list, never removed).
-- **Rejected:** a lower gate ratio, more protected rows, and `maxInputTokens` / `reserveTokens` — cap inputs are agent-config only, because moving the cap moves the gate itself. Raising `triggerRatio` at or above the agent's `compactRatio` needs `compactRatio` raised in the same overlay.
+- **Rejected:** a lower gate ratio, more protected rows, and `maxInputTokens` / `reserveTokens` / `trigger` — cap inputs and fold axes are agent-config only, because moving either moves the gate itself. Raising `triggerRatio` at or above the agent's `compactRatio` needs `compactRatio` raised in the same overlay.
 - **Enabling from a run is rejected:** a run may disable or relax the compiler, never switch it on where the agent config left it off.
 
-The **sticky frontier is session-owned and created lazily** the first time an enabled run assembles a request: one `{ thinking, toolCallIds }` set pair per session, shared across runs, provider rounds, and branches, so a stub or strip made once stays applied even on a later under-ratio turn. It lives in memory only — a resumed process simply re-decides from the ratio it sees.
+The **sticky frontier is session-owned and created lazily** the first time an enabled run assembles a request: one `{ thinking, toolCallIds }` set pair per session, shared across runs, provider rounds, and branches, so a stub or strip made once stays applied even on a later under-ratio turn. A durable run with `persistSessionState: true` writes its bounded snapshot into the checkpoint and restores it on resume, so a resumed process keeps its stubs instead of re-deciding its first turn from the ratio.
 
 `AttentionCompilerOptions` (all optional):
 
 | Field | Type | Default | Meaning |
 | --- | --- | --- | --- |
-| `triggerRatio` | `number` | `0.75` | Fraction of `inputCap` that enables mutation; must be in `(0, 1)` (exclusive). |
+| `triggerRatio` | `number` | `0.75` | Fraction of `inputCap` that enables mutation; must be in `(0, 1)` (exclusive). The reference ratio the report carries and `compactRatio` is checked against. |
+| `trigger` | `AttentionTriggerInput` | — | Fold axes (plan 086 T2). **Replaces** the `triggerRatio` axis when set; omitted keeps it alone, so behavior is unchanged. See [Trigger axes](#trigger-axes). |
 | `compactRatio` | `number` | `0.9` | Where compaction should fire relative to the compiler; must exceed `triggerRatio`. |
 | `thinkingKeepTurns` | `number` | `1` | Newest thinking-bearing assistant turns kept intact. |
 | `keepLast` | `number` | `3` | Newest tool results kept full. |
@@ -71,8 +72,9 @@ The **sticky frontier is session-owned and created lazily** the first time an en
 | --- | --- | --- |
 | `model` | `{ limits?: ModelLimits }` | Source of `contextWindow` / `maxOutputTokens` when `maxInputTokens` is absent. |
 | `compactionTrigger` | `CompactionTrigger` | Optional: validated here so an unknown trigger `type` fails at create time, not on the first turn. An `input_ratio` trigger must exceed `triggerRatio`. |
+| `runInputBudget` | `number \| null` | Cumulative run input budget the `run_input_ratio` axis folds against — pass the resolved `RunLimits.maxInputTokens`. `null` or omitted means the run declares no budget, so that axis falls back to the input cap. Distinct from `maxInputTokens`, which caps a single request. |
 
-**Public surface.** `createAttentionCompiler(options?: AttentionCompilerOptions, context?)` is the factory; `AttentionCompilerOptions` carries the gate ratios, sticky-stage tuning (`thinkingKeepTurns`, `keepLast`), `excludeTools`, and `reserveTokens`. `resolveInputCap(options?: AttentionInputCapOptions, model?)` is the cap resolver, `compileAttention(options: AttentionCompileOptions)` is the per-turn call `assembleProviderInput` makes (`AttentionCompileOptions` also carries `fold`, `frontier`, `redactor`, `signal`, and the `turn`/`sessionId`/`runId` telemetry ids), and `createAttentionTruncationTrigger(options?: AttentionTruncationTriggerOptions)` builds the host-programmable compaction trigger.
+**Public surface.** `createAttentionCompiler(options?: AttentionCompilerOptions, context?)` is the factory; `AttentionCompilerOptions` carries the gate ratios, the optional `trigger` axes, sticky-stage tuning (`thinkingKeepTurns`, `keepLast`), `excludeTools`, and `reserveTokens`. `resolveInputCap(options?: AttentionInputCapOptions, model?)` is the cap resolver, `compileAttention(options: AttentionCompileOptions)` is the per-turn call `assembleProviderInput` makes (`AttentionCompileOptions` also carries `fold`, `frontier`, `redactor`, `signal`, `runInputTokens`, and the `turn`/`sessionId`/`runId` telemetry ids), and `createAttentionTruncationTrigger(options?: AttentionTruncationTriggerOptions)` builds the host-programmable compaction trigger. The frozen handle carries the normalized `trigger` axes, the resolved `runInputBudget`, and `durable`, so a caller can never resolve one and evaluate against another.
 
 Input cap resolution: `maxInputTokens` when set, otherwise `contextWindow - (maxOutputTokens ?? 0) - reserveTokens`. Both `resolveInputCap(options?, model?)` and the compiler fail closed with a `TypeError` when neither source is present, when a declared limit is malformed, or when the computed cap is not positive.
 
@@ -82,10 +84,56 @@ Turn options, passed to `assembleProviderInput`:
 | --- | --- | --- |
 | `attentionCompiler` | `AttentionCompilerOptions \| AttentionCompiler` | Raw options are validated for that call; a resolved handle reuses one validation. The session passes the run's resolved handle so a tuning typo fails before the first provider turn. |
 | `attentionSticky` | `AttentionStickyFrontier` | `{ thinking, toolCallIds }` sets from `createAttentionStickyFrontier()`. The session supplies its own; a direct `assembleProviderInput` caller owns it, and omitting it makes each call mutate for its turn only. |
+| `runInputTokens` | `number` | Run input tokens already charged by provider usage this run (default 0), so the cumulative `run_input_ratio` axis can project this turn onto the spend. The session passes the run limit counter. |
 | `onAttentionReport` | `(report: AttentionReport) => void` | Called once per **mutated** turn, before `input_assembly` middleware; silent under the ratio. The session uses it to emit `attention_compiled`. |
 
 `attentionCompiler` and `contextBudget` are **mutually exclusive** — a compiler-on turn that is still over throws `AttentionBudgetError` rather than evicting through the budget, so passing both fails closed with a `TypeError`.
 
+### Trigger axes
+
+`trigger` replaces `triggerRatio` as the gate (plan 086 T2). It takes one axis, one predicate function, or an array of them; an array is **any-of**, and the first axis that fires is the one attributed on the report.
+
+| Kind | Fires when | Folds to | Fails closed? |
+| --- | --- | --- | --- |
+| `{ kind: "input_ratio", ratio }` | the assembled request reaches `ratio × inputCap` — the legacy `triggerRatio` axis | `ratio × inputCap` | yes |
+| `{ kind: "run_input_ratio", ratio }` | `runInputTokens + estimatedInputTokens` reaches `ratio × runInputBudget`, so a run capped below the model window folds before the cap kills it | every eligible row (a cumulative gate has no per-request target) | **no** — the spend is already booked; folding only slows the counter, and the run limit owns the cap |
+| `{ kind: "token_floor", tokens }` | the assembled request reaches `tokens` tokens, whatever the cap | `tokens` | yes |
+| `{ kind: "predicate", shouldFold }` (or a bare function) | `shouldFold(state)` returns `true` | every eligible row | yes |
+
+```ts
+// The synapta Plan 118 shape: a 1M-window model under a 500k run input cap, where the legacy
+// 0.75 × window gate (745k) could never open before the run died at its cap.
+const compiler = createAttentionCompiler(
+  { trigger: { kind: "run_input_ratio", ratio: 0.75 }, keepLast: 3 },
+  { model, runInputBudget: 500_000 },
+);
+
+// Any-of, attributed in order: the floor is reported when both would fire.
+createAttentionCompiler({ trigger: [{ kind: "token_floor", tokens: 120_000 }, { kind: "input_ratio", ratio: 0.9 }] }, { model });
+
+// Host predicate: synchronous, evaluated at most twice per turn (once to decide, once to
+// confirm the stages settled it) with a frozen `AttentionTriggerState`.
+createAttentionCompiler(
+  { trigger: (state) => state.estimatedInputTokens > 150_000 && state.turn > 5 },
+  { model },
+);
+```
+
+`AttentionTriggerState` is frozen and carries estimates only: `estimatedInputTokens` (this turn's assembled request), `inputCapTokens`, `runInputBudgetTokens` (absent when the run declares none), `runInputTokens` (charged spend so far), and `turn`. A predicate that returns a non-boolean — including a `Promise` from an `async` function — fails closed with a `TypeError` naming the option, rather than silently never firing.
+
+Predicate axes run **host-supplied code**, under the same trust as `CompactionTrigger.custom`: the compiler passes host data in and takes a boolean out, never credentials or payloads. Keep them synchronous and side-effect free; they see token estimates and ids, never message text.
+
+Rules that hold for every axis:
+
+- **Config-time validation.** Unknown kinds, a ratio outside `(0, 1)`, a non-positive `token_floor.tokens`, an empty array, and a predicate that is not a function all throw a `TypeError` naming the option (`attentionCompiler.trigger`, or `attentionCompiler.trigger[1]` inside an array).
+- **Gate is agent-config only.** A run overlay may not set `trigger`, `maxInputTokens`, or `reserveTokens` — the gate and the cap move together, so moving either belongs in the agent config.
+- **One evaluation per turn.** The axes are evaluated at turn start against the measured request and once more after the stages. The per-row loop then compares numbers, so a predicate costs two calls a turn no matter how many rows are eligible.
+- **Sticky and monotonic as ever.** An axis only decides *whether* to fold; the stages still stop as soon as a target is reached, and mutations stay applied on later under-gate turns.
+- **`run_input_ratio` needs its budget.** With `compactAfterTokens`-style run limits declared (`RunLimits.maxInputTokens`, which defaults to `40_000` and kills the run cumulatively), pass the resolved value as `runInputBudget`. Without one the axis is the per-request `input_ratio` comparison.
+- **`triggerRatio` stays the reference.** Omitted alongside `trigger`, it takes the first `input_ratio` axis's ratio so `compactRatio` and the report still describe the real fold point; with no `input_ratio` axis it keeps the default `0.75` as the compaction reference.
+
+Runnable end to end: [`examples/attention-budget-axes.ts`](../examples/attention-budget-axes.ts) runs the scenario both axes exist for — a 1M window, a 500k run budget, 24 provider turns. The window axis would need 743k tokens and never gets near (`maxUsed` ≈ 7k, so it never fires); cumulative spend crosses 1 % of the budget on turn 6, the gate opens there, and the run finishes having spent 36k of its 500k with the newest 2 rows raw and every older body a stub. `src/__tests__/attention-compiler-budget.test.ts` asserts the same numbers, including that the first fold could only be explained by carried-over spend.
+
 ## Outputs / response / events
 
 `createAttentionCompiler` returns an `AttentionCompiler`: `inputCap`, `reserveTokens`, `triggerRatio`, `compactRatio`, `thinkingKeepTurns`, `keepLast`, and a frozen, de-duplicated `excludeTools`. It performs no I/O and calls no provider.
@@ -97,10 +145,12 @@ Turn options, passed to `assembleProviderInput`:
 | `used` | `number` | Estimated tokens measured before this turn's mutation. |
 | `usedAfter` | `number` | Estimated tokens of the same request after the mutation, so `used` → `usedAfter` is the per-turn cost curve. |
 | `inputCap` | `number` | Resolved cap the ratio was compared against. |
-| `triggerRatio` | `number` | Configured ratio. |
+| `triggerRatio` | `number` | Configured ratio — the reference axis, whether or not a `trigger` replaced the gate. |
+| `firedAxis` | `AttentionTriggerKind?` | Axis that opened the gate on this turn, in configured order; absent on an under-gate turn. Plan 087 attribution reads this. |
 | `droppedThinkingTurns` | `number` | Thinking turns absent from this request — rows re-applied from the sticky frontier count again. |
 | `stubbedToolResults` | `number` | Tool results stubbed in this request — re-applied rows count again. |
 | `stubbedBytes` | `number` | Payload bytes those stubs took out of the request (message bytes minus the stub header). |
+| `newFoldedBodies` | `number` | Folded bodies this turn added to the ledger: the `summarize` calls the cache saved, and the durable-fold checkpoint signal. `0` on a turn that only re-applied stored bodies. |
 | `truncated` | `boolean` | `true` when the gate stopped with eligible rows left, so the sticky frontier is partial. |
 | `runId` / `sessionId` | `string?` | Owning run/session when known. |
 
@@ -119,7 +169,7 @@ Tool result read_file [call_1]: omitted 41_982 bytes (sha256 3f9a1c2b4d5e6f70a1b
 
 Never stubbed: rows named in `excludeTools`, tool **errors**, results stamped as a decision/approval payload (`approval`, `approvalId`, `prismApproval`, `decision`, `decisions`, `pendingDecisions`, `elicitation` metadata), rows the host fold's own age/byte gates exclude, and any row whose stub would cost more than the payload it replaces. When `toolResultFold.summarize` is configured, that function produces the stub body for the rows the compiler picked (capped by its `maxSummaryBytes`); otherwise the deterministic digest above is used.
 
-`compileAttention({ compiler, groups, context?, skills?, tools?, fold?, frontier?, redactor?, signal?, turn?, sessionId?, runId? })` is what `assembleProviderInput` calls; it returns `{ groups, mutated, report }`. Under the ratio it returns the **same groups object** it was given; when it mutates it returns new `history` / `toolResults` arrays and never writes into the caller's arrays.
+`compileAttention({ compiler, groups, context?, skills?, tools?, fold?, frontier?, attentionFold?, redactor?, signal?, turn?, runInputTokens?, sessionId?, runId? })` is what `assembleProviderInput` calls; it returns `{ groups, mutated, report }`. Under the ratio it returns the **same groups object** it was given; when it mutates it returns new `history` / `toolResults` arrays and never writes into the caller's arrays.
 
 Errors:
 
@@ -137,6 +187,7 @@ Errors:
   "keepLast": 3,
   "excludeTools": ["submit_payment"],
   "reserveTokens": 1024,
+  "durable": false,
   "compaction": {
     "trigger": {
       "type": "custom",
@@ -244,11 +295,40 @@ See [Compaction and retry policies](compaction-and-retry.md) for the trigger uni
 - `excludeTools` is fail closed: entries are validated as non-empty bounded strings, de-duplicated, and frozen; a named tool is never stubbed even when the request stays over the ratio.
 - The compiler never orchestrates other levers: `toolResultFold.summarize` still wins for fold-eligible rows when a host supplies it, `applyContextBudget` keeps working unchanged for compiler-off agents, and compaction stays a task-boundary operation (`session.compact()` still throws while a run is in flight).
 - Sticky means sticky: a stripped thinking turn is never restored and a stubbed call id is never un-stubbed, even on a later under-ratio turn — restoring either would rewrite the cached prefix. Pass no `attentionSticky` for one-shot assemblies.
-- The frontier is bounded (256 thinking keys, 256 tool-call ids, newest kept) and lives on the session, so it survives turns and runs. A durable run with `persistSessionState: true` also writes it into the checkpoint (`sessionState.attentionSticky`) and restores it on resume, so a resumed run keeps its stubs instead of re-deciding its first turn from the ratio; a malformed or hand-edited frontier is dropped entry by entry, never fatal to a resume.
+- The frontier is bounded (256 thinking keys, 256 tool-call ids, newest kept) and lives on the session, so it survives turns and runs. A durable run with `persistSessionState: true`, or any run with `durable: true`, also writes it into the checkpoint (`sessionState.attentionSticky`) and restores it on resume, so a resumed run keeps its stubs instead of re-deciding its first turn from the ratio; a malformed or hand-edited frontier is dropped entry by entry, never fatal to a resume.
 - A compiler-on turn assembles from the default message groups (instructions, summaries, history, input, attachments, tool results) exactly like a `contextBudget` turn, so a custom `inputBuilder` is not consulted while the compiler is on.
 - Compaction timing is programmable per agent through `CompactionOptions.trigger` (`threshold_entries` | `input_ratio` | `custom`); omitting it keeps today's `thresholdEntries` gate. `assertCompactionTrigger(trigger)` validates a trigger independently of the compiler.
 - The gate is opt-in per agent/run; omit the option for current assembly bytes.
 
+### Durable folding
+
+`durable: true` puts the fold state on disk (plan 086 T3), so a run that dies mid-investigation resumes
+with the rows it had already folded instead of re-deciding them from the ratio.
+
+```ts
+const agent = createAgent({
+  // ...
+  attentionCompiler: {
+    trigger: { kind: "run_input_ratio", ratio: 0.75 },
+    keepLast: 2,
+    durable: true,
+  },
+  runState: { checkpoints, definitionRevision: "1" }, // the write target; `persistSessionState` not required
+  toolResultFold: { summarize: hostSummarize },        // optional: bodies become durable too
+});
+
+// After a crash the worker resumes where the fold left off:
+await resumeAgentRun(agent, { runId, sessionId }, { decision: "continue", expectedVersion }, { checkpoints, definitionRevision: "1" });
+```
+
+- **One write per fold, never per turn.** The checkpoint is written after the turn's request is assembled and before the provider sees it, only on turns that added folded bodies. A turn that re-applies what the ledger already holds writes nothing.
+- **The fold ledger.** Each folded body is stored once, keyed by tool call id (newest 64, 4 KiB each), and re-applied on every later turn: the host `summarize` runs once per row instead of once per turn, and a sticky row stays byte-identical for the provider cache. Bodies are already redacted and capped by the fold that produced them.
+- **Independent of `persistSessionState`.** That option governs skill and tool-activation state. `durable` is its own opt-in for the fold ledger plus its sticky frontier (`sessionState.attentionFold` / `attentionSticky`), because a resumed run needs both: the frontier decides *what* stays folded, the ledger decides *what body* it was folded to.
+- **Restore is fault-tolerant.** A malformed ledger shape starts from an empty ledger, and a malformed entry is dropped one by one — the row simply re-folds on the next over-gate turn. A hand-edited checkpoint never blocks a resume.
+- **Sizing.** Off by default. On, it costs one checkpoint write per fold turn plus `bodies × (body ≤ maxSummaryBytes)` bytes in the run state (default cap: 64 bodies), and it makes the fold the run's first crash-recovery point when `checkpointPolicy` is `"decision"`.
+- **Requires a durable run.** `durable: true` without `runState` (a checkpoint store) throws `AgentRunStateError` at run start, before the first provider turn. A run overlay may not set `durable`.
+- **Still projection-only.** Durability changes *where the projection is remembered*, not what the store holds: the session store, observational-memory ledger, and semantic stores keep every original payload for recall, branching, and audit.
+
 ## Security and performance notes
 
 - Validation is synchronous with no provider I/O, and the returned handle plus `excludeTools` are frozen.
@@ -264,9 +344,10 @@ See [Compaction and retry policies](compaction-and-retry.md) for the trigger uni
 
 - [`assembleProviderInput`](input-and-prompt-assembly.md): the compose path the compiler pre-passes when enabled.
 - [`toolResultFold`](input-and-prompt-assembly.md): host summarizer that wins over the deterministic stub for eligible rows.
-- [`CompactionOptions`](compaction-and-retry.md): `trigger` is the host compact-when seam; `thresholdEntries` remains the default gate.
+- [`CompactionOptions`](compaction-and-retry.md): `trigger` is the host compact-when seam; `thresholdEntries` remains the default gate. For fold state that outlives a crash, see [Durable folding](#durable-folding).
 - [`observational-memory`](compaction-observational-memory.md): host `shouldCompact` / trigger overrides `compactAfterTokens` for post-run compaction.
 - [`provider caching`](provider-caching.md): why mutations are monotonic and in-place.
 - [`AttentionReport` measurements](_evidence/phase74-attention-measurements.md): the hermetic fixture behind the savings, cache, resume, and truncation numbers.
+- Example: [`examples/attention-budget-axes.ts`](../examples/attention-budget-axes.ts) — budget-capped long run where only the cumulative axis can open the gate.
 - [Memory fabric](memory-fabric.md): a context source whose blocks are measured like any other (`working-memory` / `semantic-memory` tags, no layer id).
 - [`thinking and reasoning`](thinking-and-reasoning.md): the `thinking` blocks the first stage strips.

package/docs/coding-agent-tools.md

@@ -610,7 +610,7 @@ Every configurable value is a positive safe integer (context may be zero); Prism
 - [Language intelligence](language-intelligence.md): optional host-activated LSP contract (`createLanguageIntelligence`) — symbols/definitions/references/diagnostics/hover/rename.
 - [Process sessions](process-sessions.md): optional managed long-running processes (`createProcessSessions`) — start/output/input/wait/signal/kill/release.
 - [Forge integration](forge-integration.md): optional GitHub adapter (`createGitHubForge`) — issue context, authenticated push, PR create/update, review comments, checks, bounded handoff reconcile; effect-store idempotency, no duplicate PRs/comments on retry, tokens never in argv/logs/events.
-- [Tools](tools.md): the host-owned tool harness — `createToolRegistry`, `dispatchToolCall`, filtering, and the `ToolDefinition` contract these factories satisfy.
+- [Tools](tools.md): the host-owned tool harness — `createToolRegistry`, `dispatchToolCall`, filtering, `toolNarrowing` per-turn menus, and the `ToolDefinition` contract these factories satisfy.
 - [Public contracts](public-contracts.md): `ToolDefinition`, `ToolResult`, `ToolExecutionContext`, `ContentBlock`, and `JsonObject` shapes.
 - [Host security guide](host-security.md): fail-closed checklist for permission policies, tool validation, and trust boundaries that must gate these tools.
 - [Tool conformance](tool-conformance.md): assertions for the tool-dispatch blocked-reason matrix these tools participate in.

package/docs/coding-security.md

@@ -219,6 +219,7 @@ A native Windows backend (Job objects / AppContainer) is tracked, not scheduled.
 
 ## Related APIs
 
+- [Work sandbox](work-sandbox.md): work image + `createWorkComposition`; host injects `createDockerSandbox` (prism-work does not fork it)
 - [Coding agent tools](coding-agent-tools.md): durable plan/todo Markdown helpers and `state.coding` checkpoint metadata for restart/resume without a second runtime
 - [Hosted sandboxes](hosted-sandboxes.md): E2B pause/resume adapter, filesystem-only snapshots, reconnect by sandbox id
 - [Workflows](workflows.md): `runWorkflow` / `resumeWorkflow` / `startWorkflowBackground` composition for coding tasks

package/docs/coding-tools.md

@@ -24,7 +24,6 @@ npm install @dietrichgebert/ponytail
 |---|---|---|
 | `@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; optional host-selected Mistral OCR (native fetch, no SDK peer) | `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 | — |

package/docs/compaction-and-retry.md

@@ -203,7 +203,7 @@ The default strategy does not call a provider. Hosts that need model-generated s
 - [Session stores and branching](session-stores-and-branching.md): branch entries, compaction entries, and `rebuildSessionContext()` behavior.
 - [Input and prompt assembly](input-and-prompt-assembly.md): compacted summaries become default summary messages for provider input.
 - [Agent/session runtime](agent-session-runtime.md): `session.compact()`, opt-in auto-compaction, `RunOptions.retry`, and `retry_scheduled` runtime behavior.
-- [Attention compiler](attention-compiler.md): resolves the same input cap and shrinks an over-ratio request before compaction is considered.
+- [Attention compiler](attention-compiler.md): resolves the same input cap and shrinks an over-ratio request before compaction is considered; with `attention.compiler.durable` the fold ledger and frontier are checkpointed per fold, so a run that dies mid-investigation resumes already folded instead of replaying the pre-fold tail.
 - Example: [`examples/autonomous-coding-loop.ts`](../examples/autonomous-coding-loop.ts) — task-boundary compact after each iteration.
 - [Middleware hooks](middleware-hooks.md): `compaction` and `retry` middleware payload timing.
 - [Contribution registries](contribution-registries.md): compaction strategy and retry policy contributions.

package/docs/compaction-observational-memory.md

@@ -67,7 +67,7 @@ Worker limits are finite positive safe integers:
 | Recent-message window | — | 512 KiB | `renderRecentMessageWindow()` hard cap |
 | Recall page size | 20 | 100 | `retrieval.pageLimit` / recall tool `limit` |
 
-Direct `runObserver()` / `runReflector()` / `runDropper()` calls retain required `maxTurns` and accept the corresponding shorter worker fields (`maxToolCalls`, `maxResultBytes`, etc.). Named default/hard constants and `resolveMemoryWorkerLimits()` are exported.
+Direct `runObserver()` / `runReflector()` / `runDropper()` calls retain required `maxTurns` and accept the corresponding shorter worker fields (`maxToolCalls`, `maxResultBytes`, etc.). Workers are tool-only: text, thinking, and done events are ignored; a turn with no `tool_call` succeeds as a no-op and records nothing. Named default/hard constants and `resolveMemoryWorkerLimits()` are exported.
 
 ## Outputs / response / events
 
@@ -87,6 +87,7 @@ Key exports:
 | `createFoldedMemoryDetails()` | Create JSON details for compaction `data.memory`. |
 | `renderObservationalMemory()` | Render reflections and observations into a prepared memory summary. |
 | `recallObservationalMemory()` | Recover source evidence for a known observation/reflection id from supplied current-branch entries. `invalidatedIds` withholds content (`reason: "revoked"`) without injecting derived text. |
+| `listInvalidatedIds()` (`@arnilo/prism-memory`) | Read the ids one exact scope currently withholds (`corrected` stays) and pass them as `invalidatedIds`, so blocks that rest on a source revoked mid-turn go stale on the next build. Empty for stores without lineage invalidation. |
 | `recallObservationalMemoryBranchPage()` | Page eligible user/assistant/tool messages around a cursor entry id (`forward`/`backward`, optional `detail: summary|full`). |
 | `createMemoryId()` / `isMemoryId()` | Create/check 12-character ids. |
 | `resolveObservationalMemorySettings()` | Merge `observational-memory` settings with defaults and overrides. |
@@ -94,7 +95,7 @@ Key exports:
 | `createObservationalMemoryRuntime()` | Low-level explicit flush for advanced hosts or tests. |
 | `createObservationalMemoryCompactionStrategy()` | Render existing folded memory as a standard Prism compaction summary with `data.memory`. |
 | `createObservationalMemoryExtension()` | Inert extension helper that registers the strategy contribution unless disabled. |
-| `createRecallMemoryTool()` | Optional `recall` tool factory: exact id lookup or current-branch message paging via host-supplied entries. |
+| `createRecallMemoryTool()` | Optional `recall` tool factory: exact id lookup (optionally merged with granted shared scopes) or current-branch message paging via host-supplied entries. |
 | `createMemoryStatusCommand()` / `createMemoryViewCommand()` | Optional `om:status` and `om:view` command factories. |
 | `createObservationalMemoryCommands()` | Convenience factory returning status and view commands. |
 
@@ -102,14 +103,40 @@ Pure utilities create no events, workers, tools, commands, credentials, or provi
 
 ### Work-scope index (opt-in)
 
-`WorkScope` is a host-named, append-only index over one observational-memory ledger. Without `om.scope.*` entries, the map has only its implicit `session` root, context renders the existing active pool, and the dropper keeps its existing behavior.
+`WorkScope` is a host-named, append-only index over one observational-memory ledger. Without `om.scope.*` entries, the map has only its implicit `session` root, context renders the existing active pool, and the dropper keeps its existing behavior. Shared work scopes extend that index across sessions under explicit grants — see "Shared work scopes (opt-in)" below.
 
-Use `createWorkScopeController({ session, appendEntry, secrets? })` to `open`, `close`, `enter`, `leave`, `bind`, or `unbind` scopes. Scope ids are host-defined (`[A-Za-z0-9._:/-]{1,128}`, no `..`); there are caps of 256 scopes, depth/stack 8, 4,096 binds per scope, and 512 characters for labels or kinds. Invalid ids, missing/closed parents, duplicate scopes, unknown record ids, and ownership mismatch fail closed. Labels and kinds receive the same secret redaction as observational-memory text.
+Use `createWorkScopeController({ session, appendEntry, secrets? })` to `open`, `close`, `enter`, `leave`, `bind`, `unbind`, `grant`, or `revoke` scopes. Scope ids are host-defined (`[A-Za-z0-9._:/-]{1,128}`, no `..`); there are caps of 256 scopes, depth/stack 8, 4,096 binds and 1,024 principals per scope, and 512 characters for labels or kinds. Invalid ids, missing/closed parents, duplicate scopes, unknown record ids, reserved/closed grant targets, and ownership mismatch fail closed. Labels and kinds receive the same secret redaction as observational-memory text.
 
 `projectWorkMemory(ledger, map, { from, include, closed?, kinds? })` returns a filtered observation/reflection view plus outline. `include` is `self`, `self+ancestors`, `self+descendants`, or `lineage`; `closed: "hide"` is the default, except closed ancestors of `from` remain available. Default attached context uses the current leaf with `self+ancestors`, rendering Scope Outline, Reflections, then Observations. The compaction summary — the layer the next run's pack starts from — renders the same projection, so the full ledger never rides into the prefix; the folded payload keeps every observation, so entering another scope can still surface what that summary hid. `recallObservationalMemory()` still reads the complete current branch by exact id.
 
 After a flush records new observations or reflections, it binds those ids once to the current leaf scope only. A host promotes relevant memory explicitly by binding it to an ancestor; a reflection whose bind sits on a **closed** scope can also graduate into durable semantic memory through the fabric's `remember({ kind: "fact" | "procedure", reflectionId })`. While any host scope exists, the runtime skips the observation dropper; the folded-payload byte cap remains a storage safety cap, not working-set garbage collection. `withWorkScope(controller, spec, fn)` opens `spec` if needed, enters it, runs `fn`, and leaves in `finally`; it never closes a scope. This index does not provide resource-scoped observational memory or budget-based dropping as a working-set mechanism.
 
+### Shared work scopes (opt-in)
+
+A shared work scope lets several sessions contribute to and read one scope under explicit owner grants. Declare it per participant in `attach()`; see `examples/shared-work-scope.ts` for a runnable grant → contribute → recall → revoke demo:
+
+```ts
+const attached = om.attach(session, {
+  appendEntry: (entry, options) => store.append(entry, options),
+  sharedScopes: { "build-42": { ownerSessionId: "session-...", entries: (sessionId) => store.list(sessionId) } },
+  onScopeAccess: (event) => audit.info("om.scope.access", event),
+});
+```
+
+Requirements, all fail-closed:
+
+- The participant opens the scope in its own branch (`open`/`enter`) and binds its own observations/reflections to it. Only ids bound to that exact scope id are shared; memory bound to an ancestor, descendant, or other scope stays private.
+- The owner branch carries `om.scope.granted` / `om.scope.revoked` records (`controller.grant(scopeId, principalIds)` / `revoke`) and is the only grant authority; grants in any other branch are inert. A grant is symmetric read+write — use separate scopes for asymmetric visibility.
+- The host `entries(sessionId)` callback is the store/tenant boundary: the package checks grants, it cannot verify another branch's tenant. Keep the callback inside one `OwnershipScope`.
+- Absent, unknown, revoked, unreachable, or not-opened-locally scope state denies the read and reports `onScopeAccess({ granted: false, reason })`. `onScopeAccess` fires for every decision, granted or denied.
+- Revocation lands on the next read: each resolve re-reads the owner branch and re-folds the grant map. The local folded payload never contains foreign observations, so revocation also holds across local compaction.
+
+`resolveSharedScopes({ scopes, principalId, map, onAccess? })` reads the owner branch for grants, then the owner and every granted branch, folds each branch separately, and unions the id-keyed results (`mergeObservationalMemoryLedgers`). Raw entry lists are never concatenated across branches — coverage cursors and projection boundaries are positional per branch. Bound memory is merged into the context blocks, `recallObservationalMemory`, the `recall` tool (exact-id only; branch paging stays current-branch), and `om:view`; `om:status` counts stay session-local.
+
+Rendering still follows the work-scope projection: the reader needs the shared scope in its current leaf lineage (`enter`, or a host that keeps it entered) for the context block to include it. Recall by exact id does not depend on the leaf. The compaction strategy and its folded payload stay local, so a shared observation re-enters context from the provider rather than from the summary.
+
+Cost: one branch read and fold per participating branch per context resolve (and per `recall` call that resolves shared scopes) — not per observation. Cache per flush only if profiling demands it.
+
 ### Compact-when override
 
 `createObservationalMemory()` accepts a compact-when gate beside the settings: `trigger` (the same union `CompactionOptions.trigger` uses) or the `shouldCompact(context)` shorthand. When either is set it **replaces** `context.compactAfterTokens`; omitted, the token gate is unchanged.
@@ -220,7 +247,7 @@ The runtime requires host-supplied `session`, an `appendEntry` callback bound to
 
 ## Cross-session / delegation-tree recall (opt-in pattern)
 
-Default is per-session: `attach()` + `appendEntry` bind one store/branch, and `recallObservationalMemory(entries, id)` / `createRecallMemoryTool({ getEntries })` see only the entries the host passes for that session. Supervisor children therefore produce observations the parent cannot recall. That is acceptable for v1 — the parent transcript already contains `delegate()` results, so parent OM covers milestones. There is no package primitive for a shared workspace scope (a namespaced multi-tenant store key is out of scope).
+Default is per-session: `attach()` + `appendEntry` bind one store/branch, and `recallObservationalMemory(entries, id)` / `createRecallMemoryTool({ getEntries })` see only the entries the host passes for that session. Supervisor children therefore produce observations the parent cannot recall. That is acceptable for v1 — the parent transcript already contains `delegate()` results, so parent OM covers milestones. When the host can read the participating branches, use a shared work scope instead (above); the funnel below remains the option when it cannot (a namespaced multi-tenant store key is still out of scope).
 
 Hosts that need parent recall of child *source* work compose it themselves: wrap the shared `SessionStore.append` so eligible child messages (`isEligibleObservationSourceEntry`) are copied onto a workspace (or parent) session with a **new entry id** and that session's `sessionId`/`parentId`. Parent OM then observes those copies and mints **new** observation ids. Child OM, if attached, stays on the child session with its own ids.
 
@@ -254,7 +281,7 @@ Wire the wrapped store into both the parent session and each supervisor child fa
 
 Rules that keep exact-id recall unambiguous:
 
-- Recall always takes **one** branch (`session.entries()` / `getEntries(sessionId)`). Never concatenate parent + child lists into one `recallObservationalMemory()` call.
+- Recall always takes **one** branch (`session.entries()` / `getEntries(sessionId)`). Never concatenate parent + child lists into one `recallObservationalMemory()` call. Shared work scopes are the supported exception: they union per-branch folded ledgers (id-keyed), never raw entry lists.
 - Copies mint a new `entry.id`. `createMemorySessionStore` rejects duplicate ids globally; JSONL/DB adapters do too.
 - Do **not** rewrite the child's OM `appendEntry` onto the workspace session. After each memory append the runtime checks the entry is visible at the **child** leaf and fails closed on a session/store mismatch. Funnel messages; let parent OM observe them.
 - Do **not** copy `om.*` custom entries across. Their `sourceEntryIds` point at the origin session and would dangle on the workspace branch.
@@ -262,7 +289,7 @@ Rules that keep exact-id recall unambiguous:
 
 Cost: the workspace branch grows with every funneled child message; parent `compactAfterTokens` / observation-pool caps still apply but fire sooner. Keep the per-session default unless parent recall of child sources is required.
 
-Ownership: funnel only within the `OwnershipScope` already on the parent agent/store. Child factories receive that ownership from the supervisor; do not share a store across tenants or identities. Observations never leave the store the host scoped.
+Ownership: funnel only within the `OwnershipScope` already on the parent agent/store. Child factories receive that ownership from the supervisor; do not share a store across tenants or identities. Observations never leave the store the host scoped — the same rule applies to shared work-scope grants.
 
 ## Security and performance notes
 

package/docs/connected-apps.md

@@ -0,0 +1,116 @@
+# Connected apps
+
+## What it does
+
+`createConnectedAppSession()` groups host-selected MCP bridges under one verified identity. It exposes only prefixed `ToolDefinition`s selected by the host and leaves transport construction, OAuth, credentials, and remote effect classification with that host.
+
+## When to use it
+
+Use connected apps when one agent needs a small, identity-scoped set of SaaS or internal MCP servers. Use typed [work tools](work-tools.md) instead for high-trust Google Workspace or Microsoft 365 actions that require Prism's draft/approve lifecycle.
+
+## Inputs / request
+
+| Input | Required | Contract |
+| --- | --- | --- |
+| `identity` | yes | Active, verified `AgentIdentity` bound to every connection. A `bind()` identity, if supplied, must match tenant, account, user, and principal. |
+| `select` | yes | Host admission callback. `false` denies before any MCP connection. |
+| `effect` | no | Shared `McpToolEffectPolicy`. Omit it to retain MCP's `external_mutation` / `unsupported` default. |
+| `connect` | no | Test seam. Production uses `connectMcpTools`. |
+| `maxApps` | no | Maximum bindings; defaults to 8 and has a hard cap of 32. |
+| `bind({ appId, serverId, transport, allowTools, effect })` | yes | `appId` and `serverId` are unique session identifiers. `transport` is already host-built. `allowTools` is an exact remote-name allowlist; per-binding `effect` overrides the shared policy. |
+
+## Outputs / response / events
+
+`bind()` connects one admitted bridge. `tools()` returns its prefixed tools without re-listing. `refresh()` re-lists every bound bridge. `list()` returns only `appId`, `serverId`, and visible prefixed tool names. `unbind()` and `close()` close their bridges.
+
+## Host composition inspection
+
+Pass only `apps.list()` identifiers into `inspectHostComposition()`; inspection never connects, refreshes, or receives a transport. A business host with connected apps must provide a verified identity.
+
+```ts
+const bindings = apps.list();
+const report = inspectHostComposition({
+  profile: "business",
+  agent,
+  connectedApps: {
+    appIds: bindings.map(({ appId }) => appId),
+    serverIds: bindings.map(({ serverId }) => serverId),
+  },
+});
+```
+
+## Request/response example
+
+```json
+{
+  "binding": {
+    "appId": "slack",
+    "serverId": "slack",
+    "transport": { "type": "stdio", "command": "/usr/bin/slack-mcp", "args": ["mcp"] },
+    "allowTools": ["list_channels", "post_message"]
+  },
+  "list": [{ "appId": "slack", "serverId": "slack", "tools": ["mcp:slack:list_channels", "mcp:slack:post_message"] }]
+}
+```
+
+## Implementation example
+
+```ts
+import { createToolRegistry, type AgentIdentity } from "@arnilo/prism";
+import { createConnectedAppSession } from "@arnilo/prism-mcp";
+
+const identity: AgentIdentity = {
+  tenantId: "tenant-a",
+  userId: "user-a",
+  principal: { kind: "user", id: "user-a" },
+  scopes: ["tools:execute"],
+  issuedAt: new Date().toISOString(),
+  verified: true,
+};
+const apps = createConnectedAppSession({
+  identity,
+  select: ({ transport }) => transport.type === "stdio" && transport.command === "/usr/bin/slack-mcp",
+  effect: ({ remoteName }) =>
+    remoteName.startsWith("list_") ? { kind: "none", idempotency: "none" } : undefined,
+});
+await apps.bind({
+  appId: "slack",
+  serverId: "slack",
+  transport: { type: "stdio", command: "/usr/bin/slack-mcp", args: ["mcp"] },
+  allowTools: ["list_channels", "post_message"],
+});
+
+const registry = createToolRegistry({ duplicate: "error" });
+for (const tool of apps.tools()) registry.register(tool);
+```
+
+## Slack MCP wrap example
+
+[`examples/connected-slack-mcp.ts`](../examples/connected-slack-mcp.ts) is a network-free template: a mock bridge exposes read and write Slack names, an exact `allowTools` list exposes only the intended tools, and the host policy marks `list_*`, `get_*`, and `search_*` as observations. `post_*`, `update_*`, and `delete_*` remain the MCP external-mutation default.
+
+For a real Slack server, the host `select` callback must admit its exact stdio command or HTTP origin. Build credentials into stdio `env` or MCP OAuth before `bind()`; never place tokens in model context.
+
+## Open Connector sidecar (example only)
+
+[`examples/open-connector-sidecar/`](../examples/open-connector-sidecar/README.md) shows the opposite shape: Prism as the host for a sibling connector gateway over loopback MCP. The recipe pins an immutable `ghcr.io/oomol-lab/open-connector` release tag (never `main`/`tip`/`latest`), binds port `3000` on `127.0.0.1`, and keeps runtime tokens host-supplied.
+
+Admission stays with the host: `select` must admit the exact loopback origin with `allowLoopbackHttp: true`, and an exact `allowTools` list (`search_actions`, `get_action_guide`, `execute_action`) keeps the provider catalog and connection listings off the model. Reads stay observations; `execute_action` is intentionally left unclassified and therefore remains `external_mutation` / `unsupported`. MCP `execute_action` accepts no `Idempotency-Key` — use HTTP `POST /v1/actions/:actionId` for retry-safe writes, or keep writes in [work tools](work-tools.md).
+
+Identity mapping is host glue: Open Connector has no Prism identity, so the host resolves `connectionName`/`x-oo-connector-alias` from the verified `AgentIdentity` and issues one runtime token per identity. OC provider egress (including `skipDnsValidation` executors and `OOMOL_CONNECT_ALLOWED_PROXIES`) stays inside Open Connector; Prism's `pinnedFetch` policy cannot be layered over it.
+
+No workspace package depends on Open Connector, no OC source is vendored, and `examples/open-connector-sidecar.ts` proves the admission and effect behavior network-free.
+
+## Extension and configuration notes
+
+Build stdio `env` and Streamable HTTP `requestInit.headers` in host code before `bind()`. Use `createMcpOAuthTransport()` when the host chooses MCP OAuth. The session does not discover catalogs, construct commands, resolve credentials, or add a second OAuth implementation.
+
+## Security and performance notes
+
+`select` is mandatory and deny-by-default. The session never infers an effect from remote descriptions or annotations; unclassified tools stay external mutations with unsupported idempotency. `allowTools` is an allowlist. `list()` excludes transports, headers, environment, and tokens. Binding performs one MCP connect; `tools()` uses cached bridge definitions until explicit `refresh()`.
+
+## Related APIs
+
+- [MCP client bridge and server exposure](mcp-tools.md): underlying MCP transports, bridge limits, OAuth, and tool mapping.
+- [Agent identity](agent-identity.md): verified identity lifecycle and delegation boundaries.
+- [Recoverable tool effects](tool-effects.md): effect declarations and mutation recovery semantics.
+- [Work tools](work-tools.md): typed high-trust M365 and Google Workspace actions.

package/docs/context-and-skills.md

@@ -211,6 +211,19 @@ Mode slices and skill bodies are independent: the injector can add `PONYTAIL MOD
 
 Pure validation without the tool: `resolveSkillLoad({ registry, name, tools, loaded, activeSkillNames })`.
 
+### Bundled work skills (`docx`, `xlsx`, `powerpoint`, `pdf`)
+
+`@arnilo/prism-work/skills` vendors four MIT Hermes productivity skills. `loadWorkSkills()` reads the committed `SKILL.md` files (64 KiB cap) and overlays Prism `toolNames` in TypeScript — vendored markdown is never edited.
+
+```ts
+import { createSkillRegistry } from "@arnilo/prism";
+import { loadWorkSkills } from "@arnilo/prism-work/skills";
+
+const registry = createSkillRegistry(loadWorkSkills(), { duplicate: "error" });
+```
+
+Scripts run only via work-sandbox `execFile` (argv, no shell). See [Work sandbox](work-sandbox.md).
+
 ### Context budget priority and skill demotion
 
 When `assembleProviderInput` runs with `contextBudget`, `applyContextBudget` evicts droppable sections in layout order. Within `context` blocks and skills, victims sort by ascending `ContextBlock.priority` (missing = **0**), then LIFO within the same priority.

package/docs/core.md

@@ -41,7 +41,6 @@ Every peer below is optional and fails closed at first use; the [optional peer d
 | `@arnilo/prism-core/governance/observability` | OpenTelemetry instrumentation and event tracing | `@opentelemetry/api` |
 | `@arnilo/prism-core/credentials/node` | Keyring-backed encrypted credential store, scrypt envelope encryption, OAuth2 PKCE providers, and OIDC identity verification | `@napi-rs/keyring` (bundled) |
 | `@arnilo/prism-core/enterprise/postgres` | Unified multi-tenant enterprise PostgreSQL state (approvals, evaluations, model-router, policy, tool effects, work idempotency) | `pg` |
-| `@arnilo/prism-core/integrations/work` | Microsoft 365 and Google Workspace CLI tool adapters with approval gates and idempotency | — |
 | `@arnilo/prism-core/validation/json-schema` | Ajv-backed JSON Schema tool argument validation | `ajv` (bundled) |
 
 ## Usage Examples
@@ -85,3 +84,4 @@ const validator = createJsonSchemaToolArgumentValidator();
 - Subpaths never load database drivers (`pg`, `better-sqlite3`) unless the specific database subpath is imported.
 - All database and network drivers fail closed with clear actionable error messages when peers are omitted.
 - Root `@arnilo/prism` remains dependency-free contracts and CLI runner.
+- Messaging channels are `@arnilo/prism-channels` (`/telegram`, `/signal`), not a `@arnilo/prism-core` subpath.

package/docs/diagrams.md

@@ -1,8 +1,8 @@
-# Diagramming, draw.io embed client, and mxGraph XML validation (`@arnilo/prism-office/diagrams`)
+# Diagramming, draw.io embed client, and mxGraph XML validation (`@arnilo/prism-work/diagrams`)
 
 ## What it does
 
-The `@arnilo/prism-office/diagrams` package provides an origin-enforced draw.io / diagrams.net iframe embed client, XXE-safe mxGraph XML validation, and byte-stable deterministic XML canonicalization for content hashing and visual artifact workflows in Prism applications and agent runtimes.
+The `@arnilo/prism-work/diagrams` package provides an origin-enforced draw.io / diagrams.net iframe embed client, XXE-safe mxGraph XML validation, and byte-stable deterministic XML canonicalization for content hashing and visual artifact workflows in Prism applications and agent runtimes.
 
 ### Core Capabilities
 
@@ -17,7 +17,7 @@ The `@arnilo/prism-office/diagrams` package provides an origin-enforced draw.io
 
 ## When to use it
 
-Use `@arnilo/prism-office/diagrams` when applications, host workspaces, or autonomous agents need to:
+Use `@arnilo/prism-work/diagrams` when applications, host workspaces, or autonomous agents need to:
 1. Embed an interactive, self-hosted draw.io / diagrams.net editor inside a web or Electron iframe with strictly enforced cross-origin security.
 2. Coordinate diagram editing lifecycles (`init` handshake, `load`, `save`, `autosave`, `merge`, and `export`).
 3. Execute save-with-preview workflows generating SVG (`xmlsvg`) or PNG (`xmlpng`) visual snapshots from the active editor session.
@@ -148,7 +148,7 @@ Outbound host-to-editor action postMessage:
 ## Implementation example
 
 ```ts
-import { createDrawioEmbed, validateDrawioXml, canonicalizeDrawioXml } from "@arnilo/prism-office/diagrams";
+import { createDrawioEmbed, validateDrawioXml, canonicalizeDrawioXml } from "@arnilo/prism-work/diagrams";
 
 // 1. Initialize embed client with strict origin binding
 const embed = createDrawioEmbed({
@@ -240,8 +240,8 @@ const summary = validateDrawioXml(xml, {
 
 ## Related APIs
 
-- [`@arnilo/prism-office/documents`](./documents.md): Specification-compliant OpenXML document generation and preview rendering for DOCX, XLSX, and PPTX.
-- [`@arnilo/prism-office/sheets`](./sheets.md): Spreadsheet and CSV parsing engine with strict financial decimal safety guarantees.
+- [`@arnilo/prism-work/documents`](./documents.md): Specification-compliant OpenXML document generation and preview rendering for DOCX, XLSX, and PPTX.
+- [`@arnilo/prism-work/sheets`](./sheets.md): Spreadsheet and CSV parsing engine with strict financial decimal safety guarantees.
 - [`@arnilo/prism-web-tools/browser`](./browser-automation.md): Browser automation tools and quarantine lifecycle.
 - [`@arnilo/prism-ag-ui`](./ag-ui.md): Agent-User Interface projection and timeline components.
 - [`@arnilo/prism-core/governance/observability`](./observability.md): OpenTelemetry instrumentation and trace adapters.

package/docs/document-reader.md

@@ -1,14 +1,14 @@
-# Document reader (`@arnilo/prism-coding-tools/document-reader`)
+# Document reader (`@arnilo/prism-work/document-reader`)
 
 > **Optional peer install:** `pdf-parse` and/or `mammoth` — see [Optional peer dependencies](peer-dependencies.md). OCR uses **native fetch**, not an SDK peer.
 
 ## What it does
 
-Optional bounded literal-text extraction for PDF and DOCX files, consumed by the coding `read` tool (plan 018 closeout `doc-reader`, 0.1.6). `createDocumentReader()` returns a `DocumentReader` that the host wires into `createReadTool(cwd, { documentReader })`; the read tool then extracts text from supported documents instead of falling back to the raw text page. Scanned PDFs/images need a **host-selected** `createMistralOcrParser({ apiKey })` passed in `parsers` — default wiring never calls an external OCR service.
+Optional bounded literal-text extraction for PDF, DOCX, XLSX, and PPTX files, consumed by the coding `read` tool. `createDocumentReader()` returns a `DocumentReader` that the host wires into `createReadTool(cwd, { documentReader })`; the read tool then extracts text from supported documents instead of falling back to the raw text page. XLSX renders as TSV and PPTX as a slide title/bullet outline through the in-package OOXML parser. Scanned PDFs/images need a **host-selected** `createMistralOcrParser({ apiKey })` passed in `parsers` — default wiring never calls an external OCR service.
 
 ## When to use it
 
-Use when coding agents must read PDF/Office files (specs, requirements docs, reports) as literal text. Do **not** use it when embedded content execution, macro evaluation, or external resource fetching is required — this adapter never does any of those by construction, and the optional peer parsers (`pdf-parse`, `mammoth`) are the only parsing code involved. Docker-less hosts that need document reads pair this with the network-free native sandbox backend (`@arnilo/prism-coding-tools/security` `createNativeSandbox`) for the surrounding tool execution.
+Use when coding agents must read PDF/Office files (specs, requirements docs, reports) as literal text. Do **not** use it when embedded content execution, macro evaluation, or external resource fetching is required — this adapter never does any of those by construction. PDF/DOCX use optional peer parsers (`pdf-parse`, `mammoth`); XLSX/PPTX use the bounded Prism OOXML parser. Docker-less hosts that need document reads pair this with the network-free native sandbox backend (`@arnilo/prism-coding-tools/security` `createNativeSandbox`) for the surrounding tool execution.
 
 Activation is explicit: no file-extension sniffing anywhere enables parsing. Absent `documentReader` option = exactly the 0.1.5 read behavior.
 
@@ -21,10 +21,10 @@ Activation is explicit: no file-extension sniffing anywhere enables parsing. Abs
 | `maxBytes` | Hard input size cap; oversize files refuse before loading | 32 MiB | 512 MiB |
 | `maxPages` | Page cap for formats that report pages; over-page documents refuse | 1000 | 10 000 |
 | `maxTextBytes` | Extracted-literal-text cap; over-cap results truncate (`truncatedBy: "bytes"`) | 2 MiB | 64 MiB |
-| `parsers` | Host-selected `DocumentParser[]`; default wiring loads the optional peers | `[pdf, docx]` | — |
+| `parsers` | Host-selected `DocumentParser[]`; default wiring includes peer-backed PDF/DOCX plus OOXML XLSX/PPTX | `[pdf, docx, xlsx, pptx]` | — |
 | `redactor` | Optional `SecretRedactor` applied to extracted text at the adapter boundary | none | — |
 
-Format gating is magic-byte based: PDF header (`%PDF-`); DOCX zip container + `word/document.xml` part marker. Unsupported buffers return `null` and the read falls through to its text path.
+Format gating is magic-byte based: PDF header (`%PDF-`); DOCX/XLSX/PPTX zip container plus `word/document.xml`, `xl/workbook.xml`, or `ppt/presentation.xml` part marker. Unsupported buffers return `null` and the read falls through to its text path.
 
 ## Outputs / response / events
 
@@ -36,7 +36,7 @@ Errors: `DocumentReaderError` with code `ERR_PRISM_DOCUMENT_READER` for missing
 
 ```ts
 import { createReadTool } from "@arnilo/prism-coding-tools/agent";
-import { createDocumentReader } from "@arnilo/prism-coding-tools/document-reader";
+import { createDocumentReader } from "@arnilo/prism-work/document-reader";
 
 const documentReader = await createDocumentReader({
   maxBytes: 32 * 1024 * 1024,
@@ -51,7 +51,7 @@ A `read` of `spec.pdf` yields text content extracted from the PDF (up to 2 MiB o
 ## Implementation example
 
 ```ts
-import { createDocumentReader, createPdfParser, type DocumentParser } from "@arnilo/prism-coding-tools/document-reader";
+import { createDocumentReader, createPdfParser, type DocumentParser } from "@arnilo/prism-work/document-reader";
 
 // Host-selected parser wiring: swap in a different PDF backend without touching bounds.
 const myPdfParser: DocumentParser = {
@@ -64,7 +64,7 @@ const myPdfParser: DocumentParser = {
 };
 const reader = await createDocumentReader({ parsers: [myPdfParser, await createPdfParser()] });
 
-import { createMistralOcrParser } from "@arnilo/prism-coding-tools/document-reader";
+import { createMistralOcrParser } from "@arnilo/prism-work/document-reader";
 const ocr = createMistralOcrParser({
   apiKey: hostKey, // never read from process.env
   recordUsage: (u) => router.recordUsage({ /* Task 7 */ tokens: 0, costUsd: hostPrice(u) }),
@@ -74,7 +74,7 @@ const scanned = await createDocumentReader({ parsers: [ocr] }); // not in the de
 
 ## Extension and configuration notes
 
-- Default parser wiring uses the optional peer dependencies `pdf-parse` (PDF) and `mammoth` (DOCX raw text). Both are declared optional (`peerDependenciesMeta`); `createDocumentReader` fails closed with a documented error at creation when a selected format's peer is absent — never at read time. Hosts pin parser versions (their CVE surface is the host's responsibility; parser advisory is reviewed at ship time).
+- Default parser wiring uses optional peer dependencies `pdf-parse` (PDF) and `mammoth` (DOCX raw text), plus in-package XLSX/PPTX parsing. Missing selected peers fail closed at creation — never at read time. XLSX sheet count and PPTX slide count share `maxPages`; text remains capped at `maxTextBytes`.
 - `createMistralOcrParser` is **not** a default parser. It POSTs `https://api.mistral.ai/v1/ocr` (`mistral-ocr-latest`) with inline `data:` URLs (`include_image_base64: false`). No Files API upload, so no remote cleanup. Host `documentUrl` values pass `assertSsrfAllowedUrl`. Extracted markdown is untrusted. Caps: 8 MiB / 32 pages / 60 s / 1 in-flight by default (hard 50 MiB / 10 000 pages / 180 s / 4). Pass `recordUsage` to admit cost through Task 7 accounting. `baseUrl` selects residency.
 - DOCX has no page concept in raw text: `pages` is always `1` and the page cap applies to PDF only; the text cap governs DOCX output.
 - The read tool re-checks `maxTextBytes` on results (parity with its text-page bounds check) and refuses reader output beyond it.