@arnilo/prism 0.9.0 → 0.11.0

package/docs/caveman.md

@@ -1,130 +0,0 @@
-# Caveman behavior integration
-
-## What it does
-
-`@arnilo/prism-coding-tools/caveman` is an optional package that wires [juliusbrussee/caveman](https://github.com/juliusbrussee/caveman) into Prism contribution contracts.
-
-It registers upstream skills and commands, injects active level prompt slices via `InstructionInjector`, and persists level as session custom `caveman-level` entries. Import and extension `setup` without a resolvable upstream path fail closed with a bounded redacted error and register zero contributions.
-
-Upstream prompt fragments, skill bodies, and rules load from the host-supplied upstream checkout — Prism does not reimplement or vendor Caveman content.
-
-## When to use it
-
-Use it when a host wants terse token-efficient communication modes (`lite`, `full`, `ultra`, wenyan variants, `micro`) with upstream Caveman skills (`caveman-commit`, `caveman-review`, `caveman-stats`, `caveman-compress`, `caveman-help`, `cavecrew`) in a Prism extension kernel.
-
-Skip it when you do not have a local Caveman checkout (Caveman is not published on npm) or when you only need progressive skill catalog without mode injection.
-
-Pair with Phase 3 progressive disclosure: register `createLoadSkillTool` and keep `skillsDisclosure: "progressive"` so full `SKILL.md` bodies stay catalog-only; mode slices come from the `caveman-mode` injector, not eager skill bodies.
-
-## Inputs / request
-
-`createCavemanExtension(options)`:
-
-| Field | Type | Required | Purpose |
-| --- | --- | --- | --- |
-| `upstreamPath` | `string` | yes | Absolute path to a Caveman checkout containing `skills/`. |
-| `defaultLevel` | `CavemanLevel` | no | Initial level when no session entry exists (default upstream: `full`). |
-| `showStatus` | `boolean` | no | Emit `caveman:status` extension events on level changes. |
-| `appendEntry` | `(entry, opts?) => Promise<void>` | yes | Host session append (OM `attach` pattern). |
-| `getEntries` | `() => readonly SessionEntry[] \| Promise<...>` | yes | Current branch entries for level restore. |
-| `configPath` | `string` | no | Bounded local config file for `defaultLevel` / `showStatus`. |
-
-`CavemanLevel`: `off` \| `lite` \| `full` \| `ultra` \| `wenyan-lite` \| `wenyan` \| `wenyan-ultra` \| `micro`.
-
-Session custom entry shape:
-
-```json
-{ "kind": "custom", "data": { "type": "caveman-level", "level": "full" } }
-```
-
-Required skills (fail closed if missing): `caveman`, `caveman-commit`, `caveman-review`, `caveman-stats`, `caveman-compress`, `caveman-help`, `cavecrew`. Extra `skills/*/SKILL.md` (v2.1 extras like `caveman-explore`) register as optional skills and `load_skill` commands. Dirs without `SKILL.md` (`*.mjs`, `registry.json`, `generated/`) are skipped.
-
-Registered commands: `caveman` (level), `caveman-init`, plus one `load_skill` dispatch per registered skill except `caveman`.
-
-## Outputs / response / events
-
-| Export | Purpose |
-| --- | --- |
-| `createCavemanExtension(options)` | Returns an inert `Extension` until `kernel.load([...])`. |
-| `caveman-mode` injector | `InstructionInjector` — upstream filtered `skills/caveman/SKILL.md` slice when level ≠ `off`. |
-| `caveman` command | Set level (`/caveman lite\|full\|ultra\|wenyan\|micro\|off`) or toggle `off`↔`full`. |
-| Alias commands | Dispatch `{ skill, dispatch: "load_skill" }` metadata for companion skills. |
-| `caveman:status` event | Optional metadata when `showStatus: true`. |
-
-Deactivation phrases `stop caveman` and `normal mode` clear active injection without erasing session history.
-
-## Request/response example
-
-```json
-{ "command": "caveman", "args": { "level": "ultra" }, "sessionId": "s1" }
-```
-
-```json
-{ "kind": "custom", "data": { "type": "caveman-level", "level": "ultra" } }
-```
-
-## Implementation example
-
-```ts
-import { createCavemanExtension } from "@arnilo/prism-coding-tools/caveman";
-import {
-  createExtensionKernel,
-  createLoadSkillTool,
-  createLoadedSkillSet,
-  createMemorySessionStore,
-  createSkillRegistry,
-  createSessionEntry,
-} from "@arnilo/prism";
-
-const store = createMemorySessionStore();
-const callbacks = {
-  appendEntry: async (entry, options) => store.append(entry, options),
-  getEntries: async () => store.list("s1"),
-};
-
-const kernel = createExtensionKernel({ errorPolicy: "throw" });
-await kernel.load([
-  createCavemanExtension({
-    upstreamPath: "/path/to/juliusbrussee-caveman",
-    defaultLevel: "full",
-    ...callbacks,
-  }),
-]);
-
-const registry = createSkillRegistry(kernel.registries.skills.list());
-const loaded = createLoadedSkillSet();
-const loadSkill = createLoadSkillTool({ registry, loaded });
-
-await kernel.registries.commands.get("caveman")!.execute({ level: "lite" }, { sessionId: "s1" });
-// Select instructionInjectors: ["caveman-mode"] on runs that should receive level slices.
-```
-
-See `examples/caveman-ponytail.ts` for progressive catalog + `load_skill` wiring with fixture upstream trees (network-free).
-
-## Extension and configuration notes
-
-- Import alone registers nothing and starts no timers, watchers, or network I/O (`sideEffects: false`).
-- `kernel.load` calls `setup`, which resolves upstream first; failure throws before any `register*`.
-- Level restore scans `getEntries()` for the latest `data.type === "caveman-level"` — same OM attach pattern; core does not auto-emit `session_start`.
-- Host must register `createLoadSkillTool` and pass `skillsDisclosure: "progressive"` for catalog-only skill bodies.
-- `caveman-stats` dispatches skill metadata only; full stats need host session-log integration.
-- `caveman-init` returns upstream guidance text; it does not write files in the host repo.
-- No TUI status bar; optional `caveman:status` events for host UI.
-- Caveman 2 compression proxy/engine is **not** a Prism runtime. Only `SKILL.md` files under `skills/` load.
-
-## Security and performance notes
-
-- Upstream `SKILL.md` and injected text are untrusted host-supplied content; reads are size-bounded (`MAX_SKILL_FILE_BYTES` 256 KiB, `MAX_INJECTED_INSTRUCTION_BYTES` 32 KiB).
-- Config read/write is bounded (`MAX_CONFIG_FILE_BYTES` 16 KiB) at host-owned `configPath` only.
-- Errors redact home directories and absolute paths.
-- Setup is O(skills) directory scan; mode read/write is O(1) per change; injection is O(1) upstream lookup per turn.
-- Session custom entries respect host session ownership and redaction policies.
-
-## Related APIs
-
-- [Ponytail behavior integration](ponytail.md): complementary lazy-minimalism mode package.
-- [Extension kernel and event bus](extensions.md): `kernel.load` and contribution registration.
-- [Context and skills](context-and-skills.md): progressive disclosure + `createLoadSkillTool`.
-- [Instruction injection](instruction-injection.md): `caveman-mode` injector selection.
-- [Observational memory compaction package](compaction-observational-memory.md): `appendEntry` / `getEntries` attach precedent.
-- [Migration guide](migration.md): `0.0.21 → 0.0.22` install and opt-in notes.

package/docs/graft.md

@@ -1,149 +0,0 @@
-# Graft context-graph integration
-
-> **Optional peer install:** `@nanonets/graft` — see [Optional peer dependencies](peer-dependencies.md).
-
-## What it does
-
-`@arnilo/prism-memory/graft` is an optional subpath that wires [nanonets/graft](https://github.com/nanonets/graft) — a repository context-graph CLI (`graft/` directory, INDEX.md orientation, symbol-level wiring graph) — into Prism contribution contracts.
-
-It registers six pull tools backed by the graft CLI (`--json`, argv-safe), a push-mode retrieval-pack context provider plus first-turn orientation injector carried on the `graft` skill, commands (`graft`, `graft-build`, `graft-build-deep`, `graft-check`, `graft-viz`, `graft-init`), and an edit-watch middleware that computes blast radius after mutating tool calls. Import is inert; a missing graft CLI fails closed at `setup` with a bounded redacted error.
-
-## When to use it
-
-Use it when a host wants agents to locate code by architecture, callers, and coupling before grep-spelunking. Three modes:
-
-- `"pull"` (default) — register the tools; the agent decides when to query.
-- `"push"` — per-turn retrieval pack (pointers only) + first-turn orientation, injected automatically.
-- `"both"` — everything.
-
-Install optional peer `@nanonets/graft@^0.16.0 || ^0.18.0` **or** pass `packageRoot`/`cliPath` explicitly. Both floors are smoke-tested by the offline peer-contract suite (`resolveGraftCli` bin discovery + packaged manifest); the range lists exactly the two released lines Prism validates, and `0.17` is absent because upstream never published one. Pair with progressive disclosure: the `graft` skill body stays small; tool schemas carry the details. Graft complements indexed code search (`repository_search`): graph/semantic locators vs literal search — neither replaces the other.
-
-Zero-code alternative (L0): hosts can skip this package entirely and let agents call `graft <command> --json` through their shell tool, optionally seeding context with graft's own generated instruction files. This package exists for native-tool ergonomics, budgeted subprocesses, session persistence, and push mode.
-
-## Inputs / request
-
-`createGraftExtension(options)`:
-
-| Field | Type | Required | Purpose |
-| --- | --- | --- | --- |
-| `cliPath` / `packageRoot` | `string` | no | Explicit stub/binary or checkout root with a manifest-declared bin; default resolves optional peer `@nanonets/graft`. Relative paths rejected; explicit paths existence-checked at resolve time. |
-| `mode` | `"pull" \| "push" \| "both"` | no | Surface selection. Default `pull`. |
-| `projectDir` | `string` | no | Directory graft operates on. Default `process.cwd()` at setup. |
-| `retrievalBudgetMs` | `number` | no | Wall-clock budget per CLI child call (default 8000). |
-| `maxResultBytes` | `number` | no | Stdout cap before parsing (default 512 KiB). |
-| `maxPromptChars` | `number` | no | Prompts longer than this never become ask argv (default 4096). |
-| `allowUpstreamTelemetry` | `boolean` | no | Default false → children run with `DO_NOT_TRACK=1`. |
-| `providerEnv` | `Record<string, string>` | no | Explicit graft provider settings (`GRAFT_API_KEY`, …). Never inherited from host env; only `GRAFT_*` keys reach the child. |
-| `deepModel` | `{ provider: "openai" \| "anthropic" \| "litellm" \| "orcarouter", model: string, apiKey: string, baseUrl?: string }` | no | Model for `graft build --deep` (Graft's own LLM client — **Prism's `Provider` is not Graft's LLM**; they have different protocols). Merged over `providerEnv` as `GRAFT_PROVIDER`/`GRAFT_MODEL`/`GRAFT_API_KEY`/`GRAFT_BASE_URL`; wins on conflict. |
-| `initAgents` / `initYes` / `initWireMcp` | `readonly string[]` / `boolean` / `boolean` | no | `graft init` configuration: agent ids for `--agents`, `--yes`, and whether to wire graft MCP servers (default off — Prism provides its own graft surfaces). `graft-init` refuses to spawn without `initAgents` or `initYes` (the child has no TTY). |
-| `buildBudgetMs` / `deepBuildBudgetMs` / `buildMaxResultBytes` | `number` | no | Budgets for graph builds: structural `build`/`init` default 120000 ms, `--deep` default 600000 ms (the LLM pass over the graph), stdout cap 2 MiB. Ask/grep stay on `retrievalBudgetMs`. |
-| `editToolNames` | `readonly string[]` | no | Tools triggering blast-radius lookup. Default `write`, `edit`, `move`. |
-| `quietStartup`, `hideStatus` | `boolean` | no | Suppress startup status events / status reporting. |
-| `appendEntry` | `(entry, opts?) => Promise<void>` | yes | Host session append (OM attach pattern). |
-| `getEntries` | `() => readonly SessionEntry[] \| Promise<...>` | yes | Current branch entries for state restore. |
-
-Pull tools (mode includes `pull`): `graft_ask`, `graft_grep`, `graft_callers`, `graft_skeleton`, `graft_map`, `graft_blast`.
-
-Push surfaces (mode includes `push`): skill `graft` carrying context provider `graft-context` (per-turn pointers-only pack, gated: ≥12-char prompt, dedup by seen node ids, 32 KiB block ceiling) and instruction injector `graft-orient` (`first_turn`, byte-capped INDEX.md cut + staleness banner).
-
-Registered commands: `graft` (`status` \| `build` [deep:true] \| `check` \| `viz` \| `init` dispatch), plus `graft-build`, `graft-build-deep`, `graft-check`, `graft-viz`, `graft-init` aliases.
-
-### Graph builds and init
-
-- `/graft-build` — structural rebuild via `graft build` (tree-sitter pass, no API key, plain-text progress — no `JSON.parse` on this surface).
-- `/graft-build-deep` — `graft build --deep --provider <> --model <> [--base-url <>]` using the host's `deepModel`. Without a configured model it errors before spawning. `GRAFT_API_KEY` rides in the child env, never on argv.
-- `/graft-init` — `graft init --no-global` (never writes user-level state), default `--no-mcp --no-hooks --no-statusline` (opt in via `initWireMcp`), plus `--agents <id>` per `initAgents` and `--yes` when `initYes`. Requires one of the two; non-interactive by design.
-
-```bash
-# structural, no key
-/graft-build
-# deep — host-configured model
-e.g. /graft-build-deep
-```
-
-## Outputs / response / events
-
-| Export | Purpose |
-| --- | --- |
-| `createGraftExtension(options)` | Returns an inert `Extension` until `kernel.load([...])`; emits `graft:loaded` on setup. |
-| `resolveGraftCli(options)` | Fail-closed CLI resolution (`explicit` → command+argv, `peer-bin` → node + manifest bin). |
-| `runGraftJson(cli, argv, options)` / `runGraftExit(cli, argv, options)` / `childEnv(options)` / `childTimeoutMs` / `DEFAULT_MAX_RESULT_BYTES` | Budgeted runners for hosts building custom surfaces — JSON surfaces (`check`/`ask`) vs exit-code surfaces (`build`/`init`). |
-| `deepProviderEnv(deepModel, providerEnv)` | `deepModel` merged over `providerEnv`, filtered to `GRAFT_*`. |
-| `readBoundedFile` / `redactPaths` / `GraftResolveError` | Bounded-read and redaction helpers. |
-
-Events: `graft:status` (check/build outcomes), `graft:dirty` (post-edit, repo-relative path + optional `staleCountEstimate`), `graft:loaded` (mode + cliKind metadata).
-
-Session custom entry shape (`data.type === "graft-state"`, CAS via `expectedParentId`):
-
-```json
-{ "kind": "custom", "data": { "type": "graft-state", "freshness": { "checkedAt": "...", "fresh": true }, "seen": ["node-a"], "savedTokensApprox": 120 } }
-```
-
-The graph never rebuilds itself mid-session (no auto-rebuild): after edits, ask/grep results may lag one turn; graft self-refreshes on the next indexed query, or run `/graft build` for an immediate refresh. The skill text states this contract to the agent.
-
-## Request/response example
-
-Tool call (pull):
-
-```json
-{ "name": "graft_ask", "arguments": { "query": "where is auth handled?", "count": 3 } }
-→ { "nodes": [{ "id": "auth-guard", "title": "requireAuth", "path": "src/auth.ts", "line": 41 }] }
-```
-
-Status event:
-
-```json
-{ "type": "graft:status", "extension": "@arnilo/prism-memory/graft", "metadata": { "fresh": true, "missing": 0, "stale": 2 } }
-```
-
-## Implementation example
-
-See [`examples/graft-extension.ts`](../examples/graft-extension.ts) — network-free demo against the package fixture stub: one pull-tool call, one push turn with pack injection + dedup, one simulated edit producing blast radius, and the `DO_NOT_TRACK` child-env guard.
-
-```ts
-import { createExtensionKernel, createMemorySessionStore } from "@arnilo/prism";
-import { createGraftExtension } from "@arnilo/prism-memory/graft";
-
-const store = createMemorySessionStore();
-const kernel = createExtensionKernel({ errorPolicy: "throw" });
-await kernel.load([
-  createGraftExtension({
-    packageRoot: "./vendor/graft-checkout",
-    mode: "both",
-    quietStartup: true,
-    deepModel: { provider: "anthropic", model: "claude-sonnet-4-5", apiKey: process.env.ANTHROPIC_API_KEY! },
-    initAgents: ["codex"],
-    appendEntry: async (entry, options) => store.append(entry, options),
-    getEntries: async () => store.list("s1"),
-  }),
-]);
-// Pull: dispatch graft_ask/… tools. Push: runs assemble the skill-carried
-// provider + graft-orient injector. Edits: middleware emits graft:dirty.
-// /graft-build-deep runs graft's own LLM pass; /graft-init wires codex, --no-global.
-```
-
-## Extension and configuration notes
-
-- Import alone registers nothing (`sideEffects: false`); no timers, watchers, or network. The only child processes are budgeted graft CLI calls.
-- Retrieval happens in-process via Prism primitives (context provider, injector, tool_result middleware) — no external hook shims.
-- Ask result shape is parsed tolerantly (`nodes|results|matches|hits`) because graft is pre-1.0; formatters emit pointers (`title` + `file:line` + `[[wikilink]]`), never source bodies.
-- Deliberate opt-out from family/umbrella packaging (like Caveman/Ponytail) — opt-in install only.
-- Multi-repo layouts work as upstream graft defines them (workspaces, submodules with `--follow-submodules`, sibling repos); point `projectDir` at the graft root that owns the target repo.
-
-## Security and performance notes
-
-- Telemetry default-off: children always get `DO_NOT_TRACK=1` unless `allowUpstreamTelemetry` is true; child env is fixed-base — host env vars are never inherited, and only explicit `GRAFT_*` keys from `providerEnv`/`deepModel` pass through. Route secrets like `GRAFT_API_KEY` through the host's credential resolution when populating `deepModel`/`providerEnv`. `deepModel`'s API key reaches the child via env only — never on argv (no `--api-key` flag exists in the surface), so it cannot leak through `ps` or logs.
-- Build/init commands are budgeted separately from retrieval (`buildBudgetMs`, `deepBuildBudgetMs`, `buildMaxResultBytes`); deep builds fail closed without a configured model instead of spawning unconfigured.
-- `graft-init` always passes `--no-global` — it never writes user-level agent state; MCP/hook/statusline wiring stays off unless the host opts in via `initWireMcp`.
-- Upstream output is untrusted: stdout capped (`maxResultBytes`), prompts capped (`maxPromptChars`), injected packs bounded (32 KiB), orientation cut byte-capped (8 KiB); error paths are logged redacted (absolute paths/home dirs).
-- Every CLI call is wall-clock-budgeted (`retrievalBudgetMs`, minus fixed overhead for the timeout math) and every failure degrades silently: pull tools return structured errors, the push pack contributes nothing, edit-watch passes the tool result through untouched.
-- No background workers; state persists through two CAS appends per turn at most (freshness patch, seen-set/saved-tokens update).
-
-## Related APIs
-
-- [Ponytail behavior integration](ponytail.md): same adapter pattern (optional peer/upstream path, fail-closed setup, session custom entries).
-- [Caveman behavior integration](caveman.md): complementary terse-communication mode package.
-- [Indexed code search](indexed-code-search.md): literal `repository_search` seam — complement, not overlap.
-- [Context and skills](context-and-skills.md): progressive catalog + `load_skill`; skill-carried context providers.
-- [Instruction injection](instruction-injection.md): injector seams (`graft-orient` rides `first_turn`).
-- [Extension kernel and event bus](extensions.md): explicit `kernel.load`, extension events.

package/docs/ponytail.md

@@ -1,129 +0,0 @@
-# Ponytail behavior integration
-
-> **Optional peer install:** `@dietrichgebert/ponytail` — see [Optional peer dependencies](peer-dependencies.md).
-
-## What it does
-
-`@arnilo/prism-coding-tools/ponytail` is an optional package that wires [DietrichGebert/ponytail](https://github.com/DietrichGebert/ponytail) into Prism contribution contracts.
-
-It registers upstream skills and commands, injects active mode instructions via upstream `getPonytailInstructions` / `filterSkillBodyForMode`, and persists mode as session custom `ponytail-mode` entries. Import is inert; missing upstream fails closed at `setup` with a bounded redacted error.
-
-## When to use it
-
-Use it when a host wants lazy-minimalism coding behavior (`lite`, `full`, `ultra`) with upstream Ponytail skills (`ponytail-audit`, `ponytail-debt`, `ponytail-gain`, `ponytail-help`, `ponytail-review`) in a Prism extension kernel.
-
-Install optional peer `@dietrichgebert/ponytail@^4.9.0` **or** pass `upstreamPath` to a checkout with `skills/` and `hooks/`.
-
-Pair with progressive disclosure: mode slices on the `ponytail-mode` injector; full skill bodies via `load_skill` only.
-
-## Inputs / request
-
-`createPonytailExtension(options)`:
-
-| Field | Type | Required | Purpose |
-| --- | --- | --- | --- |
-| `upstreamPath` | `string` | no | Override path to Ponytail root; default resolves optional peer package. |
-| `defaultMode` | `PonytailMode` | no | Initial mode when no session entry exists (default `full`). |
-| `quietStartup` | `boolean` | no | Suppress startup status events. |
-| `appendEntry` | `(entry, opts?) => Promise<void>` | yes | Host session append (OM `attach` pattern). |
-| `getEntries` | `() => readonly SessionEntry[] \| Promise<...>` | yes | Current branch entries for mode restore. |
-| `configPath` | `string` | no | Bounded local config for `defaultMode` / `quietStartup` / `hideStatus`. |
-
-`PonytailMode`: `off` \| `lite` \| `full` \| `ultra`.
-
-Session custom entry shape:
-
-```json
-{ "kind": "custom", "data": { "type": "ponytail-mode", "mode": "full" } }
-```
-
-Registered skills: `ponytail`, `ponytail-audit`, `ponytail-debt`, `ponytail-gain`, `ponytail-help`, `ponytail-review`.
-
-Registered commands: `ponytail`, `ponytail-review`, `ponytail-audit`, `ponytail-gain`, `ponytail-debt`, `ponytail-help`.
-
-`ponytail` command actions: empty args or `status` report current+default mode (4.9.0; does not change mode); `lite|full|ultra|off` set mode; `default <mode>` persists default.
-
-## Outputs / response / events
-
-| Export | Purpose |
-| --- | --- |
-| `createPonytailExtension(options)` | Returns an inert `Extension` until `kernel.load([...])`. |
-| `ponytail-mode` injector | `InstructionInjector` calling upstream `getPonytailInstructions(mode)`. |
-| `ponytail` command | Set mode, report status, or persist default mode to config file. |
-| Alias commands | Dispatch `{ skill, dispatch: "load_skill" }` for companion skills. |
-| `ponytail:status` / `ponytail:loaded` events | Optional host metadata (no statusline shell scripts). |
-
-Deactivation: exact phrases `stop ponytail` and `normal mode`.
-
-## Request/response example
-
-```json
-{ "command": "ponytail", "args": { "mode": "lite" }, "sessionId": "s1" }
-```
-
-```json
-{ "kind": "custom", "data": { "type": "ponytail-mode", "mode": "lite" } }
-```
-
-## Implementation example
-
-```ts
-import { createPonytailExtension } from "@arnilo/prism-coding-tools/ponytail";
-import {
-  createExtensionKernel,
-  createLoadSkillTool,
-  createLoadedSkillSet,
-  createMemorySessionStore,
-  createSkillRegistry,
-} from "@arnilo/prism";
-
-const store = createMemorySessionStore();
-const callbacks = {
-  appendEntry: async (entry, options) => store.append(entry, options),
-  getEntries: async () => store.list("s1"),
-};
-
-const kernel = createExtensionKernel({ errorPolicy: "throw" });
-await kernel.load([
-  createPonytailExtension({
-    upstreamPath: undefined, // optional peer @dietrichgebert/ponytail
-    defaultMode: "full",
-    quietStartup: true,
-    ...callbacks,
-  }),
-]);
-
-const registry = createSkillRegistry(kernel.registries.skills.list());
-const loaded = createLoadedSkillSet();
-const loadSkill = createLoadSkillTool({ registry, loaded });
-
-await kernel.registries.commands.get("ponytail")!.execute({ mode: "lite" }, { sessionId: "s1" });
-// Select instructionInjectors: ["ponytail-mode"] on runs that should receive mode slices.
-```
-
-See `examples/caveman-ponytail.ts` for combined Caveman + Ponytail progressive disclosure demo (network-free fixtures).
-
-## Extension and configuration notes
-
-- Import alone registers nothing (`sideEffects: false`); no timers, watchers, network, or shell scripts.
-- Upstream hook modules load via `createRequire` from resolved root — instruction strings are not forked in Prism.
-- Mode restore scans `getEntries()` for latest `data.type === "ponytail-mode"` (OM attach pattern).
-- `ponytail-subagent` hook is not wired; nested-agent behavior is host responsibility. When hosts wire the upstream hook, `PONYTAIL_SUBAGENT_MATCHER` accepts only the documented safe subset — `"explore|general"` (any literal substring) or `"^general$"` (exact), case-insensitive, max 256 chars. No `RegExp` is compiled from the environment, so arbitrary regex (including catastrophic nested quantifiers) is never evaluated; unset/invalid patterns inject into every subagent.
-- No TUI statusline scripts; use `ponytail status` command or extension events.
-- Not included in `@arnilo/prism-coding-tools` or `@arnilo/prism-core` profiles — opt-in install only.
-
-## Security and performance notes
-
-- Upstream text is untrusted; reads bounded (`MAX_SKILL_FILE_BYTES` 256 KiB, `MAX_INJECTED_INSTRUCTION_BYTES` 32 KiB).
-- Config writes only to host `configPath` with size cap (`MAX_CONFIG_FILE_BYTES` 16 KiB).
-- Errors redact absolute paths and home directories.
-- O(skills) setup scan; O(1) mode tracking per turn; no background workers.
-
-## Related APIs
-
-- [Caveman behavior integration](caveman.md): complementary terse-communication mode package.
-- [Extension kernel and event bus](extensions.md): explicit `kernel.load`.
-- [Context and skills](context-and-skills.md): progressive catalog + `load_skill`.
-- [Instruction injection](instruction-injection.md): `ponytail-mode` injector.
-- [Observational memory compaction package](compaction-observational-memory.md): session callback attach pattern.
-- [Migration guide](migration.md): `0.0.21 → 0.0.22` notes.