@fingerskier/augment 0.5.0 → 0.5.1

package/docs/verify-memory-flow.md

@@ -1,132 +1,132 @@
-# Verifying the auto-memory flow
-
-Augment now *enforces* the memory loop through host lifecycle hooks rather than
-relying on the agent to remember to call the MCP tools:
-
-| Event              | Hook command                       | Effect |
-| ------------------ | ---------------------------------- | ------ |
-| `SessionStart`     | `augment hook session-start`       | Warms the daemon and registers the project. |
-| `UserPromptSubmit` | `augment hook user-prompt-submit`  | Recalls relevant memory and injects it as `additionalContext` **before** the model sees the prompt. |
-| `PreToolUse`       | `augment hook pre-tool-use`        | Recalls **additional** memory keyed to the matched tool action (the edited file / the Bash command) and injects it as `additionalContext`. Matcher-scoped to `Edit\|Write\|Bash` to bound the hot path; injection-only (never blocks, gates, or rewrites a tool call). Uses a raised relevance floor (`min_score` 0.45 — above the 0.4 search default, calibrated on the real model because tool queries are command/path-shaped, not prose) and injects each distinct query at most once per session. |
-| `Stop`             | `augment hook stop`                | Blocks the turn **once** with a directive to upsert a memory, then allows the stop (loop-guarded per turn). |
-
-`PreToolUse` fires before **every matched** tool call, so it is the only hook with a tool-name
-`matcher` (the others fire once per prompt/turn). Two host nuances: on Claude the injected text
-rides alongside the *tool result* on the next model request (it supplements, rather than precedes,
-the action); on Codex builds older than ~0.124.0 `PreToolUse` `additionalContext` is rejected and
-silently dropped (the tool still runs). It is purely additive — `UserPromptSubmit` remains the
-guaranteed memory path on both hosts.
-
-The same `hooks/hooks.json` ships in both the Claude Code and Codex plugins
-(Codex copied Claude's event names + stdin/stdout contract), so one set of
-handlers serves both hosts.
-
-This doc is the test process. Run the layers top-to-bottom; each is cheaper and
-more isolated than the one below it.
-
-## 1. Automated (no network, no host) — `npm test`
-
-```sh
-npm test
-```
-
-Covers:
-- `test/hooks.test.ts` — the stdin→stdout contract of every hook event
-  (UserPromptSubmit envelope, PreToolUse tool-query derivation + injection-only
-  envelope + 0.45 floor + per-session dedupe, Stop block-once loop guard,
-  fail-open paths).
-- `test/recall.test.ts` — recall degrades to `""` on any failure (a hook must
-  never break the agent).
-- `test/cli.test.ts` — the `recall` and `hook` CLI commands.
-- `test/install.test.ts` — the installer writes `hooks/hooks.json` for both hosts.
-- `test/integration/memory-flow.test.ts` — a planted memory flows
-  upsert → index → `recall()` → UserPromptSubmit **and** PreToolUse envelopes, against a **real**
-  `AugmentService` (real store + sqlite index), using the deterministic hash
-  embedder. Proves the wiring end-to-end without a model download.
-
-## 2. CLI smoke (real daemon + real embeddings, one machine)
-
-Build first, then drive the real daemon by hand. Use a throwaway memory root so
-you don't pollute your real memories:
-
-```sh
-npm run build
-export AUGMENT_MEMORY_ROOT="$(mktemp -d)"      # PowerShell: $env:AUGMENT_MEMORY_ROOT = (New-Item -ItemType Directory -Path $env:TEMP\augver -Force).FullName
-
-# Plant a memory (project_id 1 after the first init), then recall it.
-node ./dist/bin/augment.js recall "the deploy pipeline"      # prints recalled text (empty until something is stored)
-
-# Exercise the hook handlers exactly as a host would (JSON on stdin):
-echo '{"user_input":"fix the deploy pipeline","cwd":"."}' | node ./dist/bin/augment.js hook user-prompt-submit
-#   -> {"hookSpecificOutput":{"hookEventName":"UserPromptSubmit","additionalContext":"## Augment memory ..."}}  (or nothing if no match)
-
-# PreToolUse keys the query off the tool action (Bash -> command, Edit/Write -> file_path):
-echo '{"tool_name":"Bash","tool_input":{"command":"deploy the pipeline"},"cwd":"."}' | node ./dist/bin/augment.js hook pre-tool-use
-#   -> {"hookSpecificOutput":{"hookEventName":"PreToolUse","additionalContext":"## Augment memory ..."}}  (or nothing if no match)
-echo '{"tool_name":"Read","tool_input":{"file_path":"x"}}' | node ./dist/bin/augment.js hook pre-tool-use
-#   -> (empty)  Read isn't in the installed matcher; even if invoked it derives a query but stays injection-only
-
-echo '{"session_id":"s","prompt_id":"p"}' | node ./dist/bin/augment.js hook stop
-#   -> {"decision":"block","reason":"Before ending this turn, record durable memory ..."}
-echo '{"session_id":"s","prompt_id":"p"}' | node ./dist/bin/augment.js hook stop
-#   -> (empty)  second stop for the same turn is allowed — proves the loop guard
-```
-
-The first `recall`/`hook user-prompt-submit` call auto-starts the daemon and, on
-a cold machine, downloads the bge-small model — so the very first run is slow.
-This is real-model retrieval; ranking quality (not just wiring) is what you're
-eyeballing here.
-
-Two footnotes on the examples: they omit `session_id`, which deliberately skips
-the PreToolUse once-per-session dedupe — include one to demo it. And the Stop
-loop-guard marker persists in the OS tmpdir, so re-running the stop example
-later with the same `session_id`/`prompt_id` yields empty on the *first* call
-too — use fresh ids per run.
-
-For a binding version of the ranking-quality check, `npm run test:model` runs
-the pinned real-bge abstention/recall tripwires
-(`test/real-model-abstention.model.ts`) — what this layer can otherwise only
-eyeball.
-
-## 3. Real project (host-level hook firing)
-
-1. Install into a repo (or user scope):
-   ```sh
-   npm exec --yes --package @fingerskier/augment -- augment install all --scope repo --memory-root "<your shared memory root>"
-   ```
-2. Confirm the plugin is actually installed/enabled — hooks only fire when the
-   plugin is active:
-   - **Claude Code:** `/plugin` → `augment` listed and enabled. The installer
-     best-effort-registers it via the `claude` CLI; if that was skipped, run the
-     printed `/plugin marketplace add … && /plugin install …` commands.
-   - **Codex:** plugin-shipped hooks need a **one-time trust** — run `/hooks` and
-     approve the augment hooks. (Managed/enterprise distribution can pre-trust;
-     a plain plugin install cannot.)
-3. Observe the loop on a real task:
-   - **Inject:** start a session and give a task that matches something in your
-     memory. The recalled block ("## Augment memory (recalled for this task)")
-     should appear in the model's context — confirm it influenced the answer.
-   - **Capture:** finish the task. The Stop hook should prompt the agent to
-     `upsert` a WORK/ARCH/ISSUE/TODO/SPEC memory; confirm a new file appears under
-     your memory root and that `augment recall` surfaces it next time.
-
-## Known caveats (logged, not blockers)
-
-- **Hook startup cost (resolved).** Hooks now invoke the install-time-provisioned
-  runtime directly (`node <prefix>/node_modules/@fingerskier/augment/dist/bin/augment.js
-  hook <event>`, tens of milliseconds) — the old `npm exec --yes` form paid a
-  multi-second npm bootstrap per event. Residual caveat: provisioning is
-  best-effort. If npm was missing at install time the installer prints a manual
-  `npm install --prefix <prefix> @fingerskier/augment` command and hooks fail
-  open (silent no-ops) until it is run. The MCP server itself still launches via
-  `npm exec`; only the hook hot path changed.
-- **Claude hook activation depends on plugin install.** The MCP server is also
-  direct-registered (so the tools always exist), but the hooks live in the plugin;
-  if the plugin isn't installed, the loop degrades to the CLAUDE.md prose guidance.
-- **Retrieval floor calibration (resolved).** The `(cos+1)/2` mis-normalization
-  is fixed by an empirically-anchored cosine rescale (`SEMANTIC_COSINE_BASELINE`
-  0.33), and abstention is now proven on the real model by `npm run test:model`.
-  Remaining retrieval-quality follow-ups (ordinary-upsert credential warnings
-  and HF revision pinning) are tracked in
-  `.council/memory/retrieval-quality-roadmap.md` and
-  [ROADMAP.md](../ROADMAP.md).
+# Verifying the auto-memory flow
+
+Augment now *enforces* the memory loop through host lifecycle hooks rather than
+relying on the agent to remember to call the MCP tools:
+
+| Event              | Hook command                       | Effect |
+| ------------------ | ---------------------------------- | ------ |
+| `SessionStart`     | `augment hook session-start`       | Warms the daemon and registers the project. |
+| `UserPromptSubmit` | `augment hook user-prompt-submit`  | Recalls relevant memory and injects it as `additionalContext` **before** the model sees the prompt. |
+| `PreToolUse`       | `augment hook pre-tool-use`        | Recalls **additional** memory keyed to the matched tool action (the edited file / the Bash command) and injects it as `additionalContext`. Matcher-scoped to `Edit\|Write\|Bash` to bound the hot path; injection-only (never blocks, gates, or rewrites a tool call). Uses a raised relevance floor (`min_score` 0.45 — above the 0.4 search default, calibrated on the real model because tool queries are command/path-shaped, not prose) and injects each distinct query at most once per session. |
+| `Stop`             | `augment hook stop`                | Blocks the turn **once** with a directive to upsert a memory, then allows the stop (loop-guarded per turn). |
+
+`PreToolUse` fires before **every matched** tool call, so it is the only hook with a tool-name
+`matcher` (the others fire once per prompt/turn). Two host nuances: on Claude the injected text
+rides alongside the *tool result* on the next model request (it supplements, rather than precedes,
+the action); on Codex builds older than ~0.124.0 `PreToolUse` `additionalContext` is rejected and
+silently dropped (the tool still runs). It is purely additive — `UserPromptSubmit` remains the
+guaranteed memory path on both hosts.
+
+The same `hooks/hooks.json` ships in both the Claude Code and Codex plugins
+(Codex copied Claude's event names + stdin/stdout contract), so one set of
+handlers serves both hosts.
+
+This doc is the test process. Run the layers top-to-bottom; each is cheaper and
+more isolated than the one below it.
+
+## 1. Automated (no network, no host) — `npm test`
+
+```sh
+npm test
+```
+
+Covers:
+- `test/hooks.test.ts` — the stdin→stdout contract of every hook event
+  (UserPromptSubmit envelope, PreToolUse tool-query derivation + injection-only
+  envelope + 0.45 floor + per-session dedupe, Stop block-once loop guard,
+  fail-open paths).
+- `test/recall.test.ts` — recall degrades to `""` on any failure (a hook must
+  never break the agent).
+- `test/cli.test.ts` — the `recall` and `hook` CLI commands.
+- `test/install.test.ts` — the installer writes `hooks/hooks.json` for both hosts.
+- `test/integration/memory-flow.test.ts` — a planted memory flows
+  upsert → index → `recall()` → UserPromptSubmit **and** PreToolUse envelopes, against a **real**
+  `AugmentService` (real store + sqlite index), using the deterministic hash
+  embedder. Proves the wiring end-to-end without a model download.
+
+## 2. CLI smoke (real daemon + real embeddings, one machine)
+
+Build first, then drive the real daemon by hand. Use a throwaway memory root so
+you don't pollute your real memories:
+
+```sh
+npm run build
+export AUGMENT_MEMORY_ROOT="$(mktemp -d)"      # PowerShell: $env:AUGMENT_MEMORY_ROOT = (New-Item -ItemType Directory -Path $env:TEMP\augver -Force).FullName
+
+# Plant a memory (project_id 1 after the first init), then recall it.
+node ./dist/bin/augment.js recall "the deploy pipeline"      # prints recalled text (empty until something is stored)
+
+# Exercise the hook handlers exactly as a host would (JSON on stdin):
+echo '{"user_input":"fix the deploy pipeline","cwd":"."}' | node ./dist/bin/augment.js hook user-prompt-submit
+#   -> {"hookSpecificOutput":{"hookEventName":"UserPromptSubmit","additionalContext":"## Augment memory ..."}}  (or nothing if no match)
+
+# PreToolUse keys the query off the tool action (Bash -> command, Edit/Write -> file_path):
+echo '{"tool_name":"Bash","tool_input":{"command":"deploy the pipeline"},"cwd":"."}' | node ./dist/bin/augment.js hook pre-tool-use
+#   -> {"hookSpecificOutput":{"hookEventName":"PreToolUse","additionalContext":"## Augment memory ..."}}  (or nothing if no match)
+echo '{"tool_name":"Read","tool_input":{"file_path":"x"}}' | node ./dist/bin/augment.js hook pre-tool-use
+#   -> (empty)  Read isn't in the installed matcher; even if invoked it derives a query but stays injection-only
+
+echo '{"session_id":"s","prompt_id":"p"}' | node ./dist/bin/augment.js hook stop
+#   -> {"decision":"block","reason":"Before ending this turn, record durable memory ..."}
+echo '{"session_id":"s","prompt_id":"p"}' | node ./dist/bin/augment.js hook stop
+#   -> (empty)  second stop for the same turn is allowed — proves the loop guard
+```
+
+The first `recall`/`hook user-prompt-submit` call auto-starts the daemon and, on
+a cold machine, downloads the bge-small model — so the very first run is slow.
+This is real-model retrieval; ranking quality (not just wiring) is what you're
+eyeballing here.
+
+Two footnotes on the examples: they omit `session_id`, which deliberately skips
+the PreToolUse once-per-session dedupe — include one to demo it. And the Stop
+loop-guard marker persists in the OS tmpdir, so re-running the stop example
+later with the same `session_id`/`prompt_id` yields empty on the *first* call
+too — use fresh ids per run.
+
+For a binding version of the ranking-quality check, `npm run test:model` runs
+the pinned real-bge abstention/recall tripwires
+(`test/real-model-abstention.model.ts`) — what this layer can otherwise only
+eyeball.
+
+## 3. Real project (host-level hook firing)
+
+1. Install into a repo (or user scope):
+   ```sh
+   npm exec --yes --package @fingerskier/augment -- augment install all --scope repo --memory-root "<your shared memory root>"
+   ```
+2. Confirm the plugin is actually installed/enabled — hooks only fire when the
+   plugin is active:
+   - **Claude Code:** `/plugin` → `augment` listed and enabled. The installer
+     best-effort-registers it via the `claude` CLI; if that was skipped, run the
+     printed `/plugin marketplace add … && /plugin install …` commands.
+   - **Codex:** plugin-shipped hooks need a **one-time trust** — run `/hooks` and
+     approve the augment hooks. (Managed/enterprise distribution can pre-trust;
+     a plain plugin install cannot.)
+3. Observe the loop on a real task:
+   - **Inject:** start a session and give a task that matches something in your
+     memory. The recalled block ("## Augment memory (recalled for this task)")
+     should appear in the model's context — confirm it influenced the answer.
+   - **Capture:** finish the task. The Stop hook should prompt the agent to
+     `upsert` a WORK/ARCH/ISSUE/TODO/SPEC memory; confirm a new file appears under
+     your memory root and that `augment recall` surfaces it next time.
+
+## Known caveats (logged, not blockers)
+
+- **Hook startup cost (resolved).** Hooks now invoke the install-time-provisioned
+  runtime directly (`node <prefix>/node_modules/@fingerskier/augment/dist/bin/augment.js
+  hook <event>`, tens of milliseconds) — the old `npm exec --yes` form paid a
+  multi-second npm bootstrap per event. Residual caveat: provisioning is
+  best-effort. If npm was missing at install time the installer prints a manual
+  `npm install --prefix <prefix> @fingerskier/augment` command and hooks fail
+  open (silent no-ops) until it is run. The MCP server itself still launches via
+  `npm exec`; only the hook hot path changed.
+- **Claude hook activation depends on plugin install.** The MCP server is also
+  direct-registered (so the tools always exist), but the hooks live in the plugin;
+  if the plugin isn't installed, the loop degrades to the CLAUDE.md prose guidance.
+- **Retrieval floor calibration (resolved).** The `(cos+1)/2` mis-normalization
+  is fixed by an empirically-anchored cosine rescale (`SEMANTIC_COSINE_BASELINE`
+  0.33), and abstention is now proven on the real model by `npm run test:model`.
+  Remaining retrieval-quality follow-ups (ordinary-upsert credential warnings
+  and HF revision pinning) are tracked in
+  `.council/memory/retrieval-quality-roadmap.md` and
+  [ROADMAP.md](../ROADMAP.md).

package/integrations/claude/skills/augment-context/SKILL.md

@@ -1,74 +1,74 @@
----
-name: augment-context
-description: Use Augment MCP memories to gather and persist project context during coding sessions.
----
-
-# Augment Context
-
-Use this skill when working in a repository with the Augment MCP server available.
-
-## Session Start
-
-1. Call `init_project`.
-2. Call `search` with the user's task summary.
-3. Read exact memories when search results identify likely governing context.
-
-## Memory Insights
-
-When the user asks for memory insights, stats, health, or an overview of what
-Augment knows, call `memory_insights` (and `memory_graph` when they want to see
-how memories connect). In hosts that support MCP Apps these render interactive
-dashboard snippets; elsewhere they return a text summary — either way, relay the
-findings rather than re-deriving them from raw memories.
-
-## Before Code Changes
-
-1. Search for the file, component, command, error, or behavior being touched.
-2. If the work depends on a prior decision, read and follow the relevant `SPEC`
-   or `ARCH` memory.
-3. If no relevant memory exists but the task creates a durable requirement or
-   decision, create one before implementation.
-
-## Memory Triggers
-
-Call `upsert` whenever one of these durable events happens:
-
-- A requirement, API contract, data model, or tool contract is clarified:
-  use `SPEC`.
-- An implementation approach, tradeoff, transport choice, persistence model, or
-  architecture decision is made: use `ARCH`.
-- A bug, risk, failing behavior, or blocker is discovered: use `ISSUE`.
-- Follow-up work is intentionally deferred: use `TODO`.
-- A meaningful implementation milestone is completed: use `WORK`.
-- A test scenario, regression case, or verification rule is learned: use `SPEC`
-  or `WORK`, whichever is more durable.
-
-## Links
-
-After creating or updating a memory:
-
-1. Use `link` when a memory implements, depends on, blocks, parents, or relates
-   to another memory.
-2. Prefer linking new `WORK` notes to the `SPEC`, `ARCH`, `ISSUE`, or `TODO`
-   they address.
-
-## Session Finish
-
-For almost every session that did real work (skip only pure Q&A, read-only
-inspection, or trivial mechanical ops like 'commit & push'):
-
-1. Upsert a concise `WORK` memory with what changed, key files, and verification.
-2. Upsert or update `TODO` memories for known remaining work.
-3. Link the final `WORK` memory to the relevant planning/decision memories.
-
-## Guardrails
-
-- Do not store secrets, credentials, tokens, or private keys.
-- Do not store huge logs, dependency dumps, generated files, or full source files.
-- Keep each memory focused; split large notes before calling `upsert`.
-- Treat numeric memory IDs as local handles. Relative paths are the durable identity.
-- Use returned search text directly as context; do not ask Augment to summarize.
-- Default to upserting when a turn did real work; only skip pure Q&A, read-only
-  inspection, or trivial mechanical ops. When unsure, upsert.
-- Do not create memories for facts already obvious from the current diff, or that
-  duplicate an existing memory (update that one instead).
+---
+name: augment-context
+description: Use Augment MCP memories to gather and persist project context during coding sessions.
+---
+
+# Augment Context
+
+Use this skill when working in a repository with the Augment MCP server available.
+
+## Session Start
+
+1. Call `init_project`.
+2. Call `search` with the user's task summary.
+3. Read exact memories when search results identify likely governing context.
+
+## Memory Insights
+
+When the user asks for memory insights, stats, health, or an overview of what
+Augment knows, call `memory_insights` (and `memory_graph` when they want to see
+how memories connect). In hosts that support MCP Apps these render interactive
+dashboard snippets; elsewhere they return a text summary — either way, relay the
+findings rather than re-deriving them from raw memories.
+
+## Before Code Changes
+
+1. Search for the file, component, command, error, or behavior being touched.
+2. If the work depends on a prior decision, read and follow the relevant `SPEC`
+   or `ARCH` memory.
+3. If no relevant memory exists but the task creates a durable requirement or
+   decision, create one before implementation.
+
+## Memory Triggers
+
+Call `upsert` whenever one of these durable events happens:
+
+- A requirement, API contract, data model, or tool contract is clarified:
+  use `SPEC`.
+- An implementation approach, tradeoff, transport choice, persistence model, or
+  architecture decision is made: use `ARCH`.
+- A bug, risk, failing behavior, or blocker is discovered: use `ISSUE`.
+- Follow-up work is intentionally deferred: use `TODO`.
+- A meaningful implementation milestone is completed: use `WORK`.
+- A test scenario, regression case, or verification rule is learned: use `SPEC`
+  or `WORK`, whichever is more durable.
+
+## Links
+
+After creating or updating a memory:
+
+1. Use `link` when a memory implements, depends on, blocks, parents, or relates
+   to another memory.
+2. Prefer linking new `WORK` notes to the `SPEC`, `ARCH`, `ISSUE`, or `TODO`
+   they address.
+
+## Session Finish
+
+For almost every session that did real work (skip only pure Q&A, read-only
+inspection, or trivial mechanical ops like 'commit & push'):
+
+1. Upsert a concise `WORK` memory with what changed, key files, and verification.
+2. Upsert or update `TODO` memories for known remaining work.
+3. Link the final `WORK` memory to the relevant planning/decision memories.
+
+## Guardrails
+
+- Do not store secrets, credentials, tokens, or private keys.
+- Do not store huge logs, dependency dumps, generated files, or full source files.
+- Keep each memory focused; split large notes before calling `upsert`.
+- Treat numeric memory IDs as local handles. Relative paths are the durable identity.
+- Use returned search text directly as context; do not ask Augment to summarize.
+- Default to upserting when a turn did real work; only skip pure Q&A, read-only
+  inspection, or trivial mechanical ops. When unsure, upsert.
+- Do not create memories for facts already obvious from the current diff, or that
+  duplicate an existing memory (update that one instead).

package/integrations/claude/skills/augment-decoction/SKILL.md

@@ -1,36 +1,36 @@
----
-name: augment-decoction
-description: Distill recurring cross-project memory into generic SPEC/ARCH records and optionally remove fully subsumed originals. Use when the user asks to "decoct", "glean", generalize, or clean up repeated memories across projects.
----
-
-# Augment Decoction
-
-Decoction extracts durable, project-independent knowledge from recurring
-memories. It is separate from sleep: sleep consolidates settled work within one
-project, while decoction finds patterns across projects and writes them under
-`.generic/`.
-
-1. Call `decoction_glean` with `action: "discover"`. If no cluster spans at
-   least four distinct projects, report that and stop.
-2. Pick a cluster and `read` every source. Synthesize one generic record:
-   - use SPEC for a reusable contract or rule;
-   - use ARCH for a reusable decision or tradeoff;
-   - retain only claims supported across the projects;
-   - put every source used in `derived_from`.
-3. Suggest source removal only when the generic preserves the original's entire
-   durable content. Do not suggest a source that also contains project-specific
-   facts, history, caveats, or unresolved work.
-4. Call `decoction_glean` with `action: "write"`, the complete draft, and the
-   reasoned `suggested_removals`. For an existing generic, read it fresh and
-   pass both of its expected hashes.
-5. Report the generic path and any warnings. Warnings are advisory and do not
-   block the write.
-6. Show each suggested cleanup path and reason verbatim. Ask for explicit user
-   approval of the exact paths; never infer approval from approval of the
-   generic itself.
-7. Only after approval, call `decoction_cleanup` with the generic path and the
-   approved source paths. Report every deletion and any failure.
-
-Cleanup hard-deletes the selected originals after retargeting inbound links to
-the generic. It has no journal or rollback. The user may approve a subset or
-decline cleanup entirely.
+---
+name: augment-decoction
+description: Distill recurring cross-project memory into generic SPEC/ARCH records and optionally remove fully subsumed originals. Use when the user asks to "decoct", "glean", generalize, or clean up repeated memories across projects.
+---
+
+# Augment Decoction
+
+Decoction extracts durable, project-independent knowledge from recurring
+memories. It is separate from sleep: sleep consolidates settled work within one
+project, while decoction finds patterns across projects and writes them under
+`.generic/`.
+
+1. Call `decoction_glean` with `action: "discover"`. If no cluster spans at
+   least four distinct projects, report that and stop.
+2. Pick a cluster and `read` every source. Synthesize one generic record:
+   - use SPEC for a reusable contract or rule;
+   - use ARCH for a reusable decision or tradeoff;
+   - retain only claims supported across the projects;
+   - put every source used in `derived_from`.
+3. Suggest source removal only when the generic preserves the original's entire
+   durable content. Do not suggest a source that also contains project-specific
+   facts, history, caveats, or unresolved work.
+4. Call `decoction_glean` with `action: "write"`, the complete draft, and the
+   reasoned `suggested_removals`. For an existing generic, read it fresh and
+   pass both of its expected hashes.
+5. Report the generic path and any warnings. Warnings are advisory and do not
+   block the write.
+6. Show each suggested cleanup path and reason verbatim. Ask for explicit user
+   approval of the exact paths; never infer approval from approval of the
+   generic itself.
+7. Only after approval, call `decoction_cleanup` with the generic path and the
+   approved source paths. Report every deletion and any failure.
+
+Cleanup hard-deletes the selected originals after retargeting inbound links to
+the generic. It has no journal or rollback. The user may approve a subset or
+decline cleanup entirely.

package/integrations/claude/skills/augment-dream/SKILL.md

@@ -1,34 +1,34 @@
----
-name: augment-dream
-description: Explore globally recalled Augment memories and propose speculative memories or links for explicit user approval. Use when the user asks to "dream" over memory, imagine hypotheses, or surface hidden connections across the current, generic, or foreign projects.
----
-
-# Augment Dream
-
-Dreams are hypotheses, not established facts. Discover and draft freely, but
-never mutate the corpus before the user explicitly approves a named proposal.
-Use a real project as the active project; `.generic` is inspiration or a link
-target only.
-
-1. Call `search` separately for each exploratory query, always passing the
-   active `project_name` and the singular `query` argument. Use normal global
-   results as ranked: the current project receives its normal priority, while
-   generic and foreign memories remain eligible.
-   Do not reserve a generic quota or add a generic fallback.
-2. Call `read` with each useful result's numeric memory id, and retain its
-   returned relative path for provenance. Imagine 1-5 coherent candidates:
-   - dream memory: a new record in the active project, with `derived_from`
-     equal to the exact inspiration paths;
-   - dream link: a link from an active-project memory to any current, generic,
-     or foreign memory.
-   Generic-only and foreign-only inspiration are valid.
-3. Call `dream_propose` for each worthwhile candidate. State the speculation
-   plainly in the content and rationale; do not present it as settled truth.
-4. Show each proposal to the user. Only after explicit approval call
-   `dream_apply` with its filename. Call `dream_reject` when the user rejects
-   it. If approval is unclear, leave the proposal pending.
-5. Report the applied speculative memory or link and its `dream:` commit.
-
-Keep evidence and conjecture distinguishable. Do not invent supporting source
-paths, and do not rewrite a foreign memory: foreign projects are inspiration
-and link targets only.
+---
+name: augment-dream
+description: Explore globally recalled Augment memories and propose speculative memories or links for explicit user approval. Use when the user asks to "dream" over memory, imagine hypotheses, or surface hidden connections across the current, generic, or foreign projects.
+---
+
+# Augment Dream
+
+Dreams are hypotheses, not established facts. Discover and draft freely, but
+never mutate the corpus before the user explicitly approves a named proposal.
+Use a real project as the active project; `.generic` is inspiration or a link
+target only.
+
+1. Call `search` separately for each exploratory query, always passing the
+   active `project_name` and the singular `query` argument. Use normal global
+   results as ranked: the current project receives its normal priority, while
+   generic and foreign memories remain eligible.
+   Do not reserve a generic quota or add a generic fallback.
+2. Call `read` with each useful result's numeric memory id, and retain its
+   returned relative path for provenance. Imagine 1-5 coherent candidates:
+   - dream memory: a new record in the active project, with `derived_from`
+     equal to the exact inspiration paths;
+   - dream link: a link from an active-project memory to any current, generic,
+     or foreign memory.
+   Generic-only and foreign-only inspiration are valid.
+3. Call `dream_propose` for each worthwhile candidate. State the speculation
+   plainly in the content and rationale; do not present it as settled truth.
+4. Show each proposal to the user. Only after explicit approval call
+   `dream_apply` with its filename. Call `dream_reject` when the user rejects
+   it. If approval is unclear, leave the proposal pending.
+5. Report the applied speculative memory or link and its `dream:` commit.
+
+Keep evidence and conjecture distinguishable. Do not invent supporting source
+paths, and do not rewrite a foreign memory: foreign projects are inspiration
+and link targets only.

package/integrations/claude/skills/augment-dream/agents/openai.yaml

@@ -1,4 +1,4 @@
-interface:
-  display_name: "Augment Dream"
-  short_description: "Propose speculative memory connections"
-  default_prompt: "Use $augment-dream to explore memory and propose speculative memories or links for my approval."
+interface:
+  display_name: "Augment Dream"
+  short_description: "Propose speculative memory connections"
+  default_prompt: "Use $augment-dream to explore memory and propose speculative memories or links for my approval."

package/integrations/claude/skills/augment-sleep/SKILL.md

@@ -1,26 +1,26 @@
----
-name: augment-sleep
-description: Consolidate settled WORK memories into durable SPEC/ARCH records via user-approved sleep proposals. Use when the user asks to "sleep", consolidate, or distill project memory.
----
-
-# Augment Sleep
-
-Sleep folds related, settled WORK memories into one durable SPEC or ARCH
-record. You draft; the user approves; `sleep_apply` writes. Never skip the
-approval step.
-
-1. Call `sleep_candidates` (current project unless the user names one).
-   If no clusters, report that and stop.
-2. For each cluster (or the one the user picks): `read` every member, then
-   draft ONE consolidated record — SPEC if a stable contract emerged, ARCH if
-   a decision stuck. The draft must state every fact worth keeping from the
-   sources; sources will be archived (down-weighted, never deleted).
-3. Call `sleep_propose` with the draft (kind, name, content,
-   derived_from = the cluster's relative paths). Tell the user where the
-   proposal file lives — they may edit it directly before approving.
-4. Show the user the draft and ask for approval. On an explicit yes, call
-   `sleep_apply` with the proposal filename. On no, call `sleep_reject`.
-5. Report what was consolidated, what was archived, and the git commit.
-
-Constraints: one project per pass; never invent facts not present in the
-sources; if a cluster mixes unrelated work, propose only the coherent subset.
+---
+name: augment-sleep
+description: Consolidate settled WORK memories into durable SPEC/ARCH records via user-approved sleep proposals. Use when the user asks to "sleep", consolidate, or distill project memory.
+---
+
+# Augment Sleep
+
+Sleep folds related, settled WORK memories into one durable SPEC or ARCH
+record. You draft; the user approves; `sleep_apply` writes. Never skip the
+approval step.
+
+1. Call `sleep_candidates` (current project unless the user names one).
+   If no clusters, report that and stop.
+2. For each cluster (or the one the user picks): `read` every member, then
+   draft ONE consolidated record — SPEC if a stable contract emerged, ARCH if
+   a decision stuck. The draft must state every fact worth keeping from the
+   sources; sources will be archived (down-weighted, never deleted).
+3. Call `sleep_propose` with the draft (kind, name, content,
+   derived_from = the cluster's relative paths). Tell the user where the
+   proposal file lives — they may edit it directly before approving.
+4. Show the user the draft and ask for approval. On an explicit yes, call
+   `sleep_apply` with the proposal filename. On no, call `sleep_reject`.
+5. Report what was consolidated, what was archived, and the git commit.
+
+Constraints: one project per pass; never invent facts not present in the
+sources; if a cluster mixes unrelated work, propose only the coherent subset.