@lorekit/cli 1.11.0 → 1.13.0

package/README.md

@@ -51,9 +51,11 @@ without needing a marketplace:
 2. **MCP server** (`lorekit`) — the connection to your lessons, merged into the
    MCP config (preserving any other servers).
 3. **Hooks** — the *deterministic* layer: lessons injected on every
-   `SessionStart`, a nudge on tool failure (`PostToolUseFailure`), and a
-   retrospective nudge on `Stop`. These fire the shared `lorekit hook` engine
-   and are merged into `settings.json` (existing hooks preserved).
+   `SessionStart`, and on a tool failure (`PostToolUseFailure`) any lessons that
+   look **relevant to that failure** ("you've hit this before") plus a nudge to
+   record the fix, and a retrospective nudge on `Stop`. These fire the shared
+   `lorekit hook` engine and are merged into `settings.json` (existing hooks
+   preserved).
 
 It first asks **where** to install:
 
@@ -212,10 +214,10 @@ rather than crashing. `--endpoint` / `--token` / `--store` behave as in `list`.
 
 ### `lorekit tree` (alias `resolve`)
 
-Show the scopes the hooks actually **inject** — branch → repo → global, in
-precedence order (most-specific first) — as a resolution hierarchy, and mark for
-any key present at more than one scope which scope's lesson **wins** and which are
-**shadowed**:
+Show the scopes the hooks actually **inject** — project → branch → repo →
+global, in precedence order (most-specific first) — as a resolution hierarchy,
+and mark for any key present at more than one scope which scope's lesson **wins**
+and which are **shadowed**:
 
 ```bash
 lorekit tree                  # the injected hierarchy with ✓ winning / ↳ shadowed marks
@@ -224,12 +226,12 @@ lorekit tree --json           # per-entry { winning, shadowedBy } + a winners[]
 ```
 
 This mirrors the SessionStart hook's resolution **exactly**: it reads the scopes
-in `readOrder` (branch → repo → global) and keeps the first value seen per key, so
-a more-specific scope overrides a broader scope's same-key lesson. It answers
-"which lesson actually applies here, and what is being overridden?". Note that
-`project::` scope is **not** part of the injected set (the hooks never inject
-project lessons), so `tree` doesn't show it — browse those with `lorekit list`.
-Each store is resolved independently, in the same Offline / Remote split.
+in `readOrder` (project → branch → repo → global) and keeps the first value seen
+per key, so a more-specific scope overrides a broader scope's same-key lesson. It
+answers "which lesson actually applies here, and what is being overridden?". The
+`project::` scope **is** part of the injected set (project is the most-specific
+scope), so `tree`, the hooks, and every read command's `scopeList` now share one
+ordering. Each store is resolved independently, in the same Offline / Remote split.
 
 ### `lorekit lint`
 
@@ -273,8 +275,9 @@ range. Cross-**store** divergence is `diff`'s job; `dedupe` looks within a store
 The **shared hook engine** behind the Claude Code / Cursor / Codex plugins.
 It is not run by hand — the plugins wire it into their hook config. It reads
 the host framework's JSON on stdin and prints that host's injection format on
-stdout (lessons at session start; a nudge on failure or at end of turn),
-always exiting 0 so it can never block the host agent.
+stdout (lessons at session start; relevant lessons plus a write-nudge on a tool
+failure; a retrospective nudge at end of turn), always exiting 0 so it can never
+block the host agent.
 
 ```bash
 lorekit hook --adapter <claude|cursor|codex> --event <SessionStart|Stop|…>
@@ -474,9 +477,11 @@ active deny constraints.
 | `LOREKIT_TELEMETRY_TOKEN` | bearer token for telemetry export (overrides the baked-in default) |
 | `OTEL_EXPORTER_OTLP_ENDPOINT` / `OTEL_EXPORTER_OTLP_HEADERS` | override the telemetry OTLP endpoint / headers |
 
-## What the skill does
+## What the skills do
 
-The installed `lorekit-memory` skill teaches an agent to:
+`install` scaffolds two skills:
+
+The **`lorekit-memory`** skill teaches an agent to:
 
 - **Read** scoped lessons at the start of a task, on first navigation into
   unfamiliar code, and before risky operations (narrow-to-broad scope merge).
@@ -488,11 +493,16 @@ This mirrors the read-on-start / write-on-failure loop of the `aw`
 autonomous-workflow agent. See the skill's own `SKILL.md` for the full
 protocol.
 
-The **skill** is model-invoked (the agent chooses to use it). For a
+The **`lorekit-setup`** skill is the authoring counterpart: it teaches an agent
+to wire a self-improvement loop into one of *your own* skills or workflows — the
+two-tier model, the lesson bucket convention, and the entrenchment guards. See
+its `SKILL.md` and `rules/self-improvement-loops.md`.
+
+The **skills** are model-invoked (the agent chooses to use them). For a
 **deterministic** guarantee — lessons injected on every session start, a nudge
 on every tool failure — use the framework plugins in [`plugins/`](../../plugins/),
-which fire the `lorekit hook` engine on host lifecycle events. The skill and
-the hooks compose: hooks guarantee the *timing*, the skill supplies the
+which fire the `lorekit hook` engine on host lifecycle events. The skills and
+the hooks compose: hooks guarantee the *timing*, the skills supply the
 *authoring judgment*.
 
 ## Testing & validating across frameworks

package/bin/lorekit.mjs

@@ -32,14 +32,14 @@ ${c.bold('Usage')}
   npx @lorekit/cli <command> [options]
 
 ${c.bold('Commands')}
-  install     Scaffold the lorekit-memory skill, wire the LoreKit MCP server,
-              and install the deterministic hooks (lessons on SessionStart, a
-              nudge on tool failure + at Stop). Prompts to install for this
-              project (.claude) or globally for every project (~/.claude);
-              --project / --global choose non-interactively, --no-hooks skips
-              the hooks (skill stays model-invoked only).
-  uninstall   Reverse install: remove the lorekit-memory skill, the MCP server
-              entry, and the lifecycle hooks for the chosen scope. Surgical —
+  install     Scaffold the lorekit-memory + lorekit-setup skills, wire the
+              LoreKit MCP server, and install the deterministic hooks (lessons
+              on SessionStart, a nudge on tool failure + at Stop). Prompts to
+              install for this project (.claude) or globally for every project
+              (~/.claude); --project / --global choose non-interactively,
+              --no-hooks skips the hooks (skills stay model-invoked only).
+  uninstall   Reverse install: remove the lorekit-memory + lorekit-setup skills,
+              the MCP server entry, and the lifecycle hooks for the chosen scope. Surgical —
               other servers, hooks, and settings are left untouched. Prompts
               project vs global; --project / --global choose non-interactively.
   doctor      Verify the skill install, MCP connectivity, token, and scope.
@@ -131,13 +131,14 @@ Run ${c.cyan('lorekit <command> --help')} for command-specific options.
 // focused entry instead of the full top-level HELP, so a user only sees the
 // flags that actually apply to what they're running.
 const COMMAND_HELP = {
-  install: `${c.bold('lorekit install')} — scaffold the skill, wire the MCP server, install the hooks
+  install: `${c.bold('lorekit install')} — scaffold the skills, wire the MCP server, install the hooks
 
 ${c.bold('Usage')}
   npx @lorekit/cli install [options]
 
-Scaffolds the lorekit-memory skill, adds the LoreKit MCP server, and wires the
-deterministic hooks (lessons on SessionStart, a nudge on tool failure + at Stop).
+Scaffolds the lorekit-memory (runtime read/write) and lorekit-setup (loop
+authoring) skills, adds the LoreKit MCP server, and wires the deterministic
+hooks (lessons on SessionStart, a nudge on tool failure + at Stop).
 
 ${c.bold('Options')}
   -d, --dir <path>        Target project root (default: current directory)
@@ -159,8 +160,8 @@ ${c.bold('Examples')}
 ${c.bold('Usage')}
   npx @lorekit/cli uninstall [options]
 
-Removes the lorekit-memory skill, the MCP server entry, and the lifecycle hooks.
-Surgical — other servers, hooks, and settings are left untouched.
+Removes the lorekit-memory and lorekit-setup skills, the MCP server entry, and
+the lifecycle hooks. Surgical — other servers, hooks, and settings are left untouched.
 
 ${c.bold('Options')}
   -d, --dir <path>        Target project root (default: current directory)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lorekit/cli",
-  "version": "1.11.0",
+  "version": "1.13.0",
   "description": "Install the LoreKit shared-memory skill and run health checks for the LoreKit MCP server.",
   "license": "MIT",
   "repository": {

package/skill/lorekit-memory/SKILL.md

@@ -46,6 +46,12 @@ Both jobs run through LoreKit's `memory.*` MCP tools.
 If those tools are not connected, this skill is a no-op — say so once and
 continue the task; never block work because memory is unavailable.
 
+> **Wiring a loop into your own skill?** This skill does the runtime read/write.
+> To set up a *self-improvement loop* for a skill, workflow, or agent — so it
+> reads its own lessons on every run and promotes proven ones into permanent
+> rules — use the **`lorekit-setup`** skill, the authoring counterpart to this
+> one.
+
 > **Modes.** Memory has a controllable backend (`lorekit doctor` shows the
 > resolved one): `remote` (the hosted LoreKit server — the default), `local`
 > (markdown files in two tiers — a per-user **home** tier at `~/.lorekit/` and

package/skill/lorekit-setup/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: lorekit-setup
+description: >
+  Sets up a self-improvement loop for a skill, workflow, or agent using LoreKit,
+  so a host gets better across runs by reading its own accumulated lessons at
+  the start of every run and hardening the proven ones into permanent rules.
+  Designs the two tiers (a fast episodic tier of LoreKit lessons, advisory-only;
+  a slow procedural tier that promotes a recurring lesson into a host rule),
+  chooses the lesson bucket (tag + key namespace) and scopes, and installs the
+  entrenchment guards that stop a learning loop from reinforcing its own
+  mistakes. Runtime reading and writing of lessons is the lorekit-memory skill;
+  this is the authoring counterpart. Use when giving a host durable cross-run
+  memory or wiring a lessons loop. Triggers on "set up memory for my skill",
+  "add a self-improvement loop", "give my workflow memory", "make this learn
+  from its mistakes", "self-improving memory", "/lorekit-setup".
+user-invocable: true
+argument-hint: '[host-name]'
+license: MIT
+metadata:
+  author: mthines
+  version: '1.0.0'
+  workflow_type: memory-loop-authoring
+  tags:
+    - lorekit
+    - self-improvement
+    - memory
+    - lessons
+    - loop
+    - authoring
+    - setup
+---
+
+# LoreKit Setup
+
+Give a skill, workflow, or agent a **self-improvement loop**: it reads its own
+accumulated lessons at the start of every run and hardens the proven ones into
+permanent rules — so it gets better the more it runs.
+
+This is the **authoring** counterpart to `lorekit-memory`. `lorekit-memory` does
+the runtime read/write of individual lessons; `lorekit-setup` wires the durable
+loop that calls those primitives on a host's behalf. Both run on the same
+LoreKit `memory.*` MCP tools.
+
+## The two tiers (in one screen)
+
+| Tier | Mechanism | Changes behavior? |
+| ---- | --------- | ----------------- |
+| **Fast (episodic)** | LoreKit lessons in a per-host bucket, read at the start of a run, written on failure | **No** — advisory input only |
+| **Slow (procedural)** | A human-reviewed edit that hardens a recurring lesson into a host rule | **Yes** |
+
+A recurrence gate connects them: a lesson that recurs (`seen_count >= 3`) or is
+marked `status=structural` becomes promotion-eligible. Entrenchment guards keep
+the fast tier from reinforcing its own wrong conclusions.
+
+## Set up a loop
+
+Follow [rules/self-improvement-loops.md](./rules/self-improvement-loops.md).
+It covers: when to add a loop (and when not to), the bucket convention (tag
+`loop::<host>-lessons` + key namespace), scope selection, the lesson schema, the
+read/write steps, the promotion gate, the entrenchment guards, a wiring
+checklist, and an interactive setup flow.
+
+If invoked with a `host-name`, set up the loop for that host; otherwise ask
+which skill / workflow / agent the loop is for, then walk the interactive setup.
+
+The loop's runtime tier needs LoreKit's `memory.*` tools connected; if they are
+not, the host's loop is a silent no-op (the slow tier — a normal source edit —
+still works). Designing the loop needs no connection.

package/skill/lorekit-setup/rules/self-improvement-loops.md

@@ -0,0 +1,257 @@
+# Setting up a self-improvement loop
+
+Use this when someone wants a skill, workflow, or agent to **get better across
+runs** — "give my skill memory", "add a self-improvement loop", "make this
+learn from its mistakes", "set up lessons for this workflow".
+
+Reading and writing individual lessons at runtime is the **`lorekit-memory`**
+skill (its `intake` / `retrospective` rules). This skill is one level up: how to
+wire a **durable loop** into a host so it reads its own accumulated lessons at
+the start of every run and records new ones on failure — safely, without the
+loop entrenching its own mistakes. The loop runs on the same `memory.*` MCP
+tools `lorekit-memory` uses.
+
+The design has two tiers connected by a recurrence gate. Both run on LoreKit.
+
+## Contents
+
+- [When to add a loop (and when not to)](#when-to-add-a-loop-and-when-not-to)
+- [The two tiers](#the-two-tiers)
+- [Conventions](#conventions)
+- [Read step (start of every run)](#read-step-start-of-every-run)
+- [Write step (on failure / at the end of a run)](#write-step-on-failure--at-the-end-of-a-run)
+- [Promotion (fast → slow)](#promotion-fast--slow)
+- [Entrenchment guards (do not skip these)](#entrenchment-guards-do-not-skip-these)
+- [Wiring checklist](#wiring-checklist)
+- [Interactive setup](#interactive-setup)
+
+---
+
+## When to add a loop (and when not to)
+
+Add a loop when **all** of these hold:
+
+- The host is an **orchestrator or multi-step pipeline** that can fail in
+  recurring, classifiable ways (wrong triage, a missed step, a false-green gate).
+- Its failures are about the **host's own process**, not just the user's product.
+- There is somewhere a proven lesson could eventually **harden into a rule** (the
+  slow tier below).
+
+Do **not** add a loop to:
+
+- **One-shot utilities** with no durable cross-run subject — the bookkeeping
+  costs more than it returns.
+- **Adversarial / audit steps** (a red-team pass, a fresh-eyes reviewer) — they
+  must not be biased by prior runs; that is the whole point of a fresh pass.
+- **Steps that handle secrets or credentials** — routing them through lesson
+  extraction is a leak risk.
+
+When unsure, default to **no**. A loop can be added later; unwinding an
+entrenched-bias loop is harder.
+
+---
+
+## The two tiers
+
+| Tier | Mechanism | Storage | Changes behavior? | Gate |
+| ---- | --------- | ------- | ----------------- | ---- |
+| **Fast (episodic)** | LoreKit lessons (`memory.*`), read at the start of a run, written on failure / at the end | LoreKit | **No** — advisory input only | none (privacy pre-flight only) |
+| **Slow (procedural)** | A permanent edit to the host's own source / rules | the host skill | **Yes** — a rule / gate / trigger | human review + approval |
+
+The fast tier captures a lesson immediately and cheaply. A lesson earns a
+**permanent** change to the host (the slow tier) only once it has **recurred
+across runs** — recurrence is the cheap external signal that the lesson is real,
+not a one-off. This is the episodic → procedural promotion path, with a human
+gate on the slow tier so a single bad run can never rewrite the host.
+
+The fast tier is optional: if LoreKit's `memory.*` tools are not connected, the
+loop is a silent no-op (log one line, continue). The slow tier is just editing
+the host and is unaffected.
+
+---
+
+## Conventions
+
+Give the loop its own **bucket** so its lessons stay separate from every other
+loop's on the same scopes. A bucket is a tag plus a key namespace:
+
+- **Tag:** `loop::<host>-lessons` (e.g. `loop::deploy-lessons`). Reads filter by
+  it; writes always carry it.
+- **Key:** `<host>-lessons::<kebab-slug>` (e.g. `deploy-lessons::migration-order`).
+  Same `scope` + `key` overwrites in place — the mechanism behind recurrence
+  counting.
+
+Pick the **scope** per lesson from the standard LoreKit model (`::` is the only
+separator; the `lorekit-memory` skill's scope-resolution reference has the full
+derivation):
+
+- **`global`** — universal lessons that should follow the user across every repo.
+- **`repo::{owner}/{repo}`** — lessons specific to this repository.
+
+Reserve `branch::` for throwaway notes; a loop normally writes `global` or
+`repo::`.
+
+### The lesson record
+
+A loop lesson is **procedural** ("how to do better next time"), not a fact about
+the user. Keep the machine-read metadata in a `meta:` comment at the top of the
+`value` so the prose stays readable:
+
+```markdown
+<!-- meta: seen_count=1 status=active expires=<ISO 8601, ~90 days out> trigger-context="<concrete signal — file glob, task type, tool, error shape>" -->
+
+# <one-line lesson title>
+
+**What failed:** <concrete observable from the run>
+**Why:** <root cause, if known; "unknown" is allowed>
+**What to do next time:** <prescriptive, actionable, testable instruction>
+**Promotion target:** <the host rule/step this would harden if promoted, or "none">
+```
+
+`trigger-context` must be **concrete** (globs, task types, tool names, error
+shapes) — never "when it feels relevant" — so the read step can match it
+mechanically. `seen_count`, `status`, and `expires` drive recurrence, promotion,
+and decay.
+
+---
+
+## Read step (start of every run)
+
+Read narrow-to-broad, filtered by the bucket tag, and merge:
+
+```text
+memory.list { scope: "repo::{owner}/{repo}", tags: ["loop::<host>-lessons"], limit: 50 }   # skips silently if memory.* not connected
+memory.list { scope: "global",               tags: ["loop::<host>-lessons"], limit: 50 }
+# when the run names a subsystem / error, add a search:
+memory.search { q: "<keywords>", scopes: ["repo::{owner}/*", "global"], limit: 10 }
+```
+
+Then:
+
+1. Match each lesson's `trigger-context` against the current run. Consider only
+   matches. **Skip any lesson whose `expires` is in the past** — treat it as
+   stale.
+2. Apply each matching *"What to do next time"* as a **consideration**, not a
+   command — it biases the run unless it conflicts with the user's stated intent
+   or a task-specific constraint. On conflict, the user's intent wins; surface it.
+3. On a `repo::` vs `global` collision, the `repo::` lesson wins (closer scope).
+
+No consolidation pass is needed — LoreKit owns storage and deduplicates on write.
+
+---
+
+## Write step (on failure / at the end of a run)
+
+Trigger on friction: a stuck loop, a repeated failure, a gate that should have
+caught something, a near-miss, a guess that paid off. Not on smooth successes.
+
+1. **Classify the scope.** Trigger references a concrete repo path / repo-specific
+   package or term → `repo::{owner}/{repo}`. A glob, framework, tool, or task
+   type with no repo binding → `global`. When ambiguous, default to `global`.
+2. **Deduplicate**, so a recurrence updates in place instead of piling up:
+
+   ```text
+   memory.search { q: "<key words of the lesson>", scopes: ["repo::{owner}/{repo}", "global"], limit: 10 }
+   ```
+
+3. **Write** to the classified scope:
+
+   ```text
+   memory.write {
+     scope: "<global | repo::{owner}/{repo}>",
+     key:   "<host>-lessons::<slug>",
+     value: "<the lesson body above>",
+     tags:  ["loop::<host>-lessons", "source::<trigger>"],
+     trigger: "<stuck-loop | command-failure | gotcha | near-miss | assumption-wrong | paid-off | manual>"
+   }
+   ```
+
+Same `scope` + `key` overwrites in place. **A recurrence resolves to an UPDATE
+that increments `seen_count` by 1 and refreshes `expires`** — that is what makes
+recurrence countable and drives promotion. If a lesson you applied at the start
+of the run worked (the failure did not recur), still write the UPDATE:
+successful application is recurrence evidence.
+
+The privacy pre-flight is never skipped, autonomous or not: a candidate lesson
+containing a secret, token, credential, or PII is **dropped, not written**. The
+bar is stricter for `repo::` writes — a repo scope is team-visible.
+
+---
+
+## Promotion (fast → slow)
+
+After a read or write, a lesson is **promotion-eligible** when either:
+
+- `seen_count >= 3` — the same failure recurred across at least three runs, or
+- it is tagged `status=structural` because it reflects a design gap, not a
+  one-off.
+
+For an eligible lesson, **surface a one-line suggestion — never act silently**:
+
+> Lesson "<title>" recurred N times. Promote it to a permanent guard in
+> `<host>`? (edit the host's source / rules behind your normal review.)
+
+The promotion target follows the lesson's scope: a `global` lesson hardens the
+**host's own source** (every user of the host benefits); a `repo::` lesson
+hardens the **repo's own rules / docs** (every teammate in that repo benefits).
+Promotion is a normal, human-reviewed edit — LoreKit does not apply it. After a
+successful promotion, write an UPDATE setting `status=promoted` so the lesson
+stops re-suggesting and stands as an audit trail of why the rule exists.
+
+---
+
+## Entrenchment guards (do not skip these)
+
+The dominant risk of any reflective-memory loop is **self-reinforcing error**:
+the host wrongly concludes "approach X always fails", stores it, avoids X
+forever, and never gathers the evidence to overturn the false belief. These
+guards are what make the loop safe:
+
+1. **Lessons are advisory, never auto-applied to behavior.** A lesson biases a
+   run; it can never silently disable a gate, skip a step, or change a limit. The
+   only path from a lesson to changed behavior is the human-reviewed slow tier.
+2. **Recurrence gates promotion, not a single run** (`seen_count >= 3`, or an
+   explicit `status=structural` marker in the lesson's `meta:` comment).
+3. **Every lesson expires** (default ~90 days from last sighting; the read step
+   ignores expired lessons, so stale beliefs decay instead of entrenching).
+4. **Contradiction is surfaced, not silently overwritten** — the dedup search
+   finds the prior lesson; a genuine reversal is a reviewed decision.
+5. **The privacy pre-flight is never bypassed** — secrets / PII are dropped, not
+   stored.
+
+---
+
+## Wiring checklist
+
+To add a loop to a host called `<host>`:
+
+- [ ] Pick the bucket: tag `loop::<host>-lessons`, key `<host>-lessons::<slug>`.
+- [ ] Add the **read step** at the start of the host's run (narrow-to-broad
+      `memory.list` filtered by the tag; apply matches as considerations; skip
+      expired).
+- [ ] Add the **write step** at the host's existing failure / end-of-run points
+      (classify scope, `memory.search` to dedup, `memory.write`). No new
+      reflection stage — hook the points the host already detects.
+- [ ] Add the **promotion suggestion** when a read/written lesson hits
+      `seen_count >= 3` or `status=structural`.
+- [ ] State the **entrenchment guards** so a future maintainer does not "optimize
+      them away".
+- [ ] Confirm the loop **degrades silently** when `memory.*` is not connected.
+
+---
+
+## Interactive setup
+
+When a user asks to set up self-improving memory for a specific host, walk them
+through it rather than dumping the whole recipe:
+
+1. **Confirm it should have a loop** — run the "when to add a loop" test above.
+   If the host is a one-shot utility, an adversarial pass, or a secret-handler,
+   say so and stop.
+2. **Name the bucket** — `loop::<host>-lessons` from the host's name.
+3. **Locate the read and write points** — the start of a run, and the failure /
+   end-of-run points the host already has. Show the two `memory.*` snippets with
+   the bucket filled in.
+4. **Write the guards down** in the host's own docs, so they survive future edits.
+5. **Do a dry run** — trigger a failure, confirm a lesson is written to the right
+   scope with the right tag, then confirm the next run reads it back.

package/src/config.mjs

@@ -6,8 +6,17 @@ import { fileURLToPath } from 'node:url';
 
 // packages/cli/ — the installable package root (this file lives in src/).
 export const PKG_ROOT = fileURLToPath(new URL('../', import.meta.url));
-export const SKILL_SOURCE = path.join(PKG_ROOT, 'skill', 'lorekit-memory');
 export const SKILL_NAME = 'lorekit-memory';
+export const SKILL_SOURCE = path.join(PKG_ROOT, 'skill', SKILL_NAME);
+
+// Every skill the CLI ships. `lorekit-memory` is the operational read/write
+// loop (kept first as the primary — `SKILL_NAME`/`SKILL_SOURCE` above alias it
+// for back-compat); `lorekit-setup` is the authoring skill that wires a
+// self-improvement loop into a host. install/uninstall/doctor iterate this list.
+export const SKILLS = ['lorekit-memory', 'lorekit-setup'].map((name) => ({
+  name,
+  source: path.join(PKG_ROOT, 'skill', name),
+}));
 
 export function resolveProjectRoot(dir) {
   return path.resolve(dir || process.cwd());
@@ -62,9 +71,9 @@ export function mcpConfigPath(root, scope = 'project') {
 // Where the skill is scaffolded for a given scope:
 //   project → <root>/.claude/skills/…   (this repo only)
 //   global  → ~/.claude/skills/…        (personal skills, all projects)
-export function skillInstallDir(root, scope = 'project') {
+export function skillInstallDir(root, scope = 'project', name = SKILL_NAME) {
   const base = scope === 'global' ? homeDir() : root;
-  return path.join(base, '.claude', 'skills', SKILL_NAME);
+  return path.join(base, '.claude', 'skills', name);
 }
 
 // Claude Code settings file that holds the hooks for a given scope:
@@ -231,10 +240,10 @@ export function readLorekitServer(root) {
 // server / hook / setting intact, so uninstalling never damages a shared
 // ~/.claude.json or settings.json.
 
-// Delete the scaffolded skill directory. We own the whole
-// .claude/skills/lorekit-memory tree, so a recursive remove is safe.
-export function removeSkill(root, scope = 'project') {
-  const dest = skillInstallDir(root, scope);
+// Delete a scaffolded skill directory. We own the whole
+// .claude/skills/<name> tree for each skill we ship, so a recursive remove is safe.
+export function removeSkill(root, scope = 'project', name = SKILL_NAME) {
+  const dest = skillInstallDir(root, scope, name);
   const removed = fs.existsSync(dest);
   if (removed) fs.rmSync(dest, { recursive: true, force: true });
   return { dest, removed };

package/src/core/lessons.mjs

@@ -3,23 +3,52 @@
 // Storage is reached through the resolved store (local | remote), never a
 // backend directly, so the same read path serves every mode.
 import { deriveScope } from '../scope.mjs';
+// The precedence merge and the literal substring matcher come from the
+// dependency-free `lessons-pure.mjs` — the SAME primitives `tree` and `search`
+// use, so the hook can't drift from them, and the hot path never pulls in the
+// `lessons-view.mjs` render/`util` stack.
+import { resolvePrecedence, matchesQuery } from '../lessons-pure.mjs';
 
 const MAX_LESSONS = 15;
+// Cap on lessons injected on a failure — a small, focused "you've seen this
+// before" set, never the whole applicable corpus.
+const MAX_RELEVANT = 3;
+// Cap on the terms distilled from a failure — bounds the relevance scan so a
+// huge error blob can never turn into an unbounded match loop.
+const MAX_TERMS = 12;
+// Terms shorter than this are dropped: too generic to make a match meaningful.
+const MIN_TERM_LEN = 4;
+// Cap on how much failure text is scanned for terms. A tool can dump a
+// multi-megabyte stderr/stdout; the salient error words are always near the
+// front, so we bound the input BEFORE lowercasing/splitting it — otherwise a
+// giant blob would materialise a giant token array (a CPU/memory spike) even
+// though the term COUNT is capped. Generous enough to never clip a real error.
+const MAX_SCAN_CHARS = 4096;
 
-// Read lessons narrow-to-broad through the store and merge; more specific
-// scope wins on key. Any per-scope failure is skipped (memory is best-effort).
+// Read lessons narrow-to-broad through the store and resolve cross-scope
+// precedence via the shared pure `resolvePrecedence` (the SAME first-seen /
+// more-specific-wins merge `tree` renders) — so the hook and `tree` provably
+// can't drift. Any per-scope failure is skipped (memory is best-effort).
 export async function fetchLessons(store, cwd) {
   const scope = deriveScope(cwd);
-  const byKey = new Map();
+  const groups = [];
   for (const s of scope.readOrder) {
     const res = await store.list({ scope: s, limit: 25 });
-    if (!res || !res.ok) continue;
-    const entries = Array.isArray(res.entries) ? res.entries : [];
-    for (const e of entries) {
-      if (e && e.key && !byKey.has(e.key)) byKey.set(e.key, { ...e, scope: s });
-    }
+    if (!res || !res.ok) continue; // best-effort: a failed scope contributes nothing
+    const entries = (Array.isArray(res.entries) ? res.entries : [])
+      .filter((e) => e && e.key)
+      .map((e) => ({ ...e, scope: s }));
+    groups.push({ scope: s, error: null, entries });
   }
-  return { scope, lessons: [...byKey.values()].slice(0, MAX_LESSONS) };
+  // First value per key wins (most-specific scope, since `readOrder` is
+  // narrow→broad) — exactly what the old inline `byKey` merge did, now via the
+  // one shared resolver. The winners, in group order, are the injected set.
+  const { groups: resolved } = resolvePrecedence({ groups });
+  const lessons = [];
+  for (const g of resolved) {
+    for (const e of g.entries) if (e.winning) lessons.push(e);
+  }
+  return { scope, lessons: lessons.slice(0, MAX_LESSONS) };
 }
 
 // Render lessons as a compact markdown block, or null when there are none.
@@ -37,6 +66,60 @@ export function formatLessons(lessons, scope) {
   return `${header}\n${body}`;
 }
 
+// Distil a small set of significant, lowercased search TERMS from a tool
+// failure — the tool name plus the salient words of its error text — used to
+// look up lessons that might already cover this failure. Pure and total: any
+// shape of `toolResponse` (object, string, null, malformed) is handled without
+// throwing. Terms are de-duplicated, stopword- and length-filtered so a match
+// stays meaningful, and the count is capped (`MAX_TERMS`) so a huge error blob
+// can't blow up the downstream scan.
+export function failureQuery(toolName, toolResponse) {
+  const text = `${toolName ? String(toolName) : ''} ${errorText(toolResponse)}`.slice(0, MAX_SCAN_CHARS);
+  const seen = new Set();
+  const terms = [];
+  for (const raw of text.toLowerCase().split(/[^a-z0-9]+/)) {
+    if (raw.length < MIN_TERM_LEN || STOPWORDS.has(raw) || seen.has(raw)) continue;
+    seen.add(raw);
+    terms.push(raw);
+    if (terms.length >= MAX_TERMS) break;
+  }
+  return terms;
+}
+
+// Lessons whose key OR value literally contains ANY of the failure `terms`
+// (case-insensitive, via the shared `matchesQuery` — never a regex), capped at
+// `cap`. Pure and best-effort: no terms or no lessons → empty (the caller then
+// falls back to the write-nudge alone). Preserves `lessons` order, so the
+// most-specific scope's relevant lesson surfaces first.
+export function relevantLessons(lessons, terms, cap = MAX_RELEVANT) {
+  if (!Array.isArray(lessons) || !lessons.length || !Array.isArray(terms) || !terms.length) {
+    return [];
+  }
+  const out = [];
+  for (const l of lessons) {
+    if (terms.some((t) => matchesQuery(l, t))) out.push(l);
+    if (out.length >= cap) break;
+  }
+  return out;
+}
+
+// Render the relevant-lessons block injected alongside the failure nudge, or
+// null when nothing matched. Framed as prior art, not a directive — same
+// "considerations, not rules" stance as `formatLessons`.
+export function formatRelevantLessons(lessons) {
+  if (!lessons || lessons.length === 0) return null;
+  const header =
+    `LoreKit — you've hit something like this before. ${lessons.length} related ` +
+    'lesson(s) (considerations, not rules; trust the current code if they conflict):';
+  const body = lessons
+    .map((l) => {
+      const first = String(l.value || '').split('\n')[0].slice(0, 300);
+      return `- (${l.scope}) ${l.key}: ${first}`;
+    })
+    .join('\n');
+  return `${header}\n${body}`;
+}
+
 // The retrospective nudge emitted at end-of-turn (one-shot per session).
 export function retrospectiveNudge(scope) {
   const writeScope = scope.repoScope || 'global';
@@ -58,3 +141,64 @@ export function failureNudge(toolName, scope) {
     `lorekit-memory (memory.write to ${writeScope}), so the next run avoids it.`
   );
 }
+
+// Pull the human-readable error text out of a tool_response of any shape. Total:
+// null/primitive/string/object all yield a (possibly empty) string, never a
+// throw — the relevance lookup is best-effort and must not break the host.
+function errorText(response) {
+  if (response == null) return '';
+  if (typeof response === 'string') return response;
+  if (typeof response !== 'object') return String(response);
+  const parts = [];
+  for (const f of TEXT_FIELDS) {
+    const v = response[f];
+    if (typeof v === 'string') parts.push(v);
+    else if (v && typeof v === 'object') parts.push(safeStringify(v));
+  }
+  return parts.length ? parts.join(' ') : safeStringify(response);
+}
+
+function safeStringify(v) {
+  try {
+    return JSON.stringify(v) || '';
+  } catch {
+    return '';
+  }
+}
+
+// The tool_response fields that commonly carry error text, across frameworks.
+const TEXT_FIELDS = [
+  'stderr',
+  'error',
+  'message',
+  'stdout',
+  'output',
+  'content',
+  'reason',
+  'detail',
+  'details',
+];
+
+// Generic words dropped from a failure query: too common to make a lesson match
+// meaningful (they'd match almost anything). Kept small and hand-picked.
+const STOPWORDS = new Set([
+  'error',
+  'errors',
+  'failed',
+  'failure',
+  'tool',
+  'call',
+  'code',
+  'exit',
+  'with',
+  'this',
+  'that',
+  'from',
+  'null',
+  'true',
+  'false',
+  'undefined',
+  'command',
+  'response',
+  'status',
+]);

package/src/doctor.mjs

@@ -5,7 +5,7 @@ import path from 'node:path';
 import process from 'node:process';
 import { execFileSync } from 'node:child_process';
 import {
-  SKILL_NAME,
+  SKILLS,
   resolveProjectRoot,
   skillInstallDir,
   readLorekitServer,
@@ -42,18 +42,24 @@ export async function doctor(args) {
     `v${process.versions.node}${major < 18 ? ' — need v18+ for fetch' : ''}`,
   );
 
-  // 2. Skill installed — check BOTH the project and the global (~/.claude)
-  // locations. `lorekit install --global` writes the skill under home, not the
-  // repo, so a project-only check reports a healthy global install as "not
-  // found" (exactly the false FAIL a --global setup would hit).
-  const skillMd = [skillInstallDir(root, 'project'), skillInstallDir(root, 'global')]
-    .map((dir) => path.join(dir, 'SKILL.md'))
-    .find((p) => fs.existsSync(p));
-  if (skillMd) {
-    const rel = path.relative(root, skillMd);
-    record('pass', `skill ${SKILL_NAME}`, rel && !rel.startsWith('..') ? rel : prettyPath(skillMd));
-  } else {
-    record('fail', `skill ${SKILL_NAME}`, 'not found — run `lorekit install`');
+  // 2. Skills installed — check every skill the CLI ships, in BOTH the project
+  // and the global (~/.claude) locations. `lorekit install --global` writes the
+  // skill under home, not the repo, so a project-only check reports a healthy
+  // global install as "not found" (exactly the false FAIL a --global setup would
+  // hit).
+  for (const skill of SKILLS) {
+    const skillMd = [
+      skillInstallDir(root, 'project', skill.name),
+      skillInstallDir(root, 'global', skill.name),
+    ]
+      .map((dir) => path.join(dir, 'SKILL.md'))
+      .find((p) => fs.existsSync(p));
+    if (skillMd) {
+      const rel = path.relative(root, skillMd);
+      record('pass', `skill ${skill.name}`, rel && !rel.startsWith('..') ? rel : prettyPath(skillMd));
+    } else {
+      record('fail', `skill ${skill.name}`, 'not found — run `lorekit install`');
+    }
   }
 
   // 3. Resolved control model — which mode, and who decided it.

package/src/hook.mjs

@@ -7,7 +7,15 @@ import { resolveProjectRoot } from './config.mjs';
 import { deriveScope } from './scope.mjs';
 import { loadControl } from './control.mjs';
 import { createStore } from './store/index.mjs';
-import { fetchLessons, formatLessons, retrospectiveNudge, failureNudge } from './core/lessons.mjs';
+import {
+  fetchLessons,
+  formatLessons,
+  retrospectiveNudge,
+  failureNudge,
+  failureQuery,
+  relevantLessons,
+  formatRelevantLessons,
+} from './core/lessons.mjs';
 import { isFailure } from './core/failure.mjs';
 import { firstTimeThisSession } from './core/state.mjs';
 import { recordFixture } from './core/record.mjs';
@@ -92,7 +100,22 @@ async function run(args) {
     const known = adapter.guaranteedFailure ? adapter.guaranteedFailure(event) : false;
     if (!known && !isFailure(parsed.toolName, parsed.toolResponse)) return 0;
     if (!firstTimeThisSession(parsed.sessionId, 'failure')) return 0;
-    emit(failureNudge(parsed.toolName, scope));
+    // Best-effort: surface any existing lessons that look relevant to THIS
+    // failure ("you've hit this before"), then the write-nudge. A missing /
+    // unusable store, or no match, silently falls back to the nudge alone.
+    let relevant = null;
+    try {
+      const store = createStore(control);
+      if (store) {
+        const { lessons } = await fetchLessons(store, root);
+        const terms = failureQuery(parsed.toolName, parsed.toolResponse);
+        relevant = formatRelevantLessons(relevantLessons(lessons, terms));
+      }
+    } catch {
+      relevant = null; // never let a lesson lookup break the failure nudge
+    }
+    const nudge = failureNudge(parsed.toolName, scope);
+    emit(relevant ? `${relevant}\n\n${nudge}` : nudge);
     return 0;
   }
 

package/src/install.mjs

@@ -1,11 +1,10 @@
-// `lorekit install` — scaffold the skill and wire the MCP server.
+// `lorekit install` — scaffold the skills and wire the MCP server.
 import fs from 'node:fs';
 import path from 'node:path';
 import readline from 'node:readline';
 import process from 'node:process';
 import {
-  SKILL_SOURCE,
-  SKILL_NAME,
+  SKILLS,
   resolveProjectRoot,
   skillInstallDir,
   copyDir,
@@ -73,10 +72,13 @@ export async function install(args) {
     token = token || null;
   }
 
-  // 3. Install the skill files.
-  const dest = skillInstallDir(root, scope);
-  const skillExisted = fs.existsSync(path.join(dest, 'SKILL.md'));
-  const written = copyDir(SKILL_SOURCE, dest, { force: Boolean(args.force) });
+  // 3. Install the skill files — every skill the CLI ships.
+  const skillResults = SKILLS.map((skill) => {
+    const dest = skillInstallDir(root, scope, skill.name);
+    const existed = fs.existsSync(path.join(dest, 'SKILL.md'));
+    const written = copyDir(skill.source, dest, { force: Boolean(args.force) });
+    return { name: skill.name, dest, existed, written };
+  });
 
   // 4. Wire the MCP config for the chosen scope.
   const remoteUrl = buildRemoteUrl(endpoint, token);
@@ -100,12 +102,14 @@ export async function install(args) {
 
   // 5. Report.
   heading('Done');
-  const skillState = !skillExisted
-    ? 'installed'
-    : written > 0
-      ? `updated (${written} file(s) written)`
-      : 'unchanged — pass --force to overwrite';
-  status(skillExisted && written === 0 ? 'info' : 'pass', `skill ${SKILL_NAME}`, `${skillState} → ${display(dest)}`);
+  for (const s of skillResults) {
+    const skillState = !s.existed
+      ? 'installed'
+      : s.written > 0
+        ? `updated (${s.written} file(s) written)`
+        : 'unchanged — pass --force to overwrite';
+    status(s.existed && s.written === 0 ? 'info' : 'pass', `skill ${s.name}`, `${skillState} → ${display(s.dest)}`);
+  }
   status('pass', mcpLabel, `${existed ? 'updated' : 'created'} lorekit server → ${display(file)}`);
 
   if (!wireHooks) {

package/src/lessons-pure.mjs

@@ -0,0 +1,65 @@
+// Pure, DEPENDENCY-FREE lesson primitives shared by the hook engine
+// (`core/lessons.mjs`, the hot path) and the read-command view layer
+// (`lessons-view.mjs`, which re-exports these). Kept in its own module so the
+// hook can import the exact precedence + match logic the read commands use —
+// one source of truth, no drift — WITHOUT dragging in the rendering/`util`
+// stack (`heading`/`log`/`c`, plus the lint/dedupe/diff cores) that the rest of
+// `lessons-view.mjs` carries. Zero imports on purpose.
+
+// ── cross-scope precedence resolution (the `tree` + hook merge core) ──────────
+
+// Given per-scope groups in RESOLUTION ORDER — most-specific first, exactly the
+// order `deriveScope().readOrder` produces — compute which scope's lesson WINS
+// each key and which are shadowed. This is the hook engine's merge: it iterates
+// the scopes narrow-to-broad and keeps the FIRST value seen per key (`if
+// (!winnerScopeByKey.has(key)) set`), so a more-specific scope shadows a broader
+// scope's same-key lesson. Returns the same groups with every entry tagged
+// `{ winning, shadowedBy }` (`shadowedBy` = the scope that won the key, or null
+// for a winner), plus the resolved `winners` list (`{ scope, key }`, one per
+// key) and winning/shadowed counts. A per-scope read error is passed through
+// untouched (empty entries), so one unreadable scope never derails resolution.
+// Pure — consumed by both `tree` (display) and `fetchLessons` (injection).
+export function resolvePrecedence({ groups = [] } = {}) {
+  const winnerScopeByKey = new Map(); // key → the scope that first claimed it
+  const outGroups = [];
+  let winningTotal = 0;
+  let shadowedTotal = 0;
+  for (const g of groups) {
+    if (g.error) {
+      outGroups.push({ scope: g.scope, error: g.error, entries: [] });
+      continue;
+    }
+    const entries = [];
+    for (const e of g.entries || []) {
+      const prior = winnerScopeByKey.get(e.key);
+      if (prior === undefined) {
+        winnerScopeByKey.set(e.key, g.scope);
+        entries.push({ ...e, winning: true, shadowedBy: null });
+        winningTotal += 1;
+      } else {
+        entries.push({ ...e, winning: false, shadowedBy: prior });
+        shadowedTotal += 1;
+      }
+    }
+    outGroups.push({ scope: g.scope, error: null, entries });
+  }
+  const winners = [...winnerScopeByKey.entries()].map(([key, scope]) => ({ scope, key }));
+  return { groups: outGroups, winners, winningTotal, shadowedTotal };
+}
+
+// ── literal, case-insensitive substring matching (the `search` + hook core) ───
+
+// Case-insensitive, LITERAL substring match of `query` against a normalized
+// entry's key OR value — the `search` command's matcher, and the hook's
+// failure-relevance matcher. Deliberately a plain `String.includes` (never
+// `new RegExp(query)`) so a query full of regex metacharacters like `a.*(b)`
+// matches those characters verbatim, never as a pattern. An empty query matches
+// everything (the command guards emptiness as a usage error before ever calling
+// this). Pure — trivially unit-testable.
+export function matchesQuery(entry, query) {
+  const needle = String(query == null ? '' : query).toLowerCase();
+  if (!needle) return true;
+  const key = String(entry?.key ?? '').toLowerCase();
+  const value = String(entry?.value ?? '').toLowerCase();
+  return key.includes(needle) || value.includes(needle);
+}

package/src/scope.mjs

@@ -44,7 +44,11 @@ export function deriveScope(cwd = process.cwd()) {
       : null;
   const projectScope = `project::${projectName}`;
 
-  const readOrder = [branchScope, repoScope, 'global'].filter(Boolean);
+  // Injection / resolution order, most-specific → broadest. Matches the read
+  // commands' `scopeList` exactly (`lessons-view.mjs`) — project is FIRST, so a
+  // project-scoped lesson wins and IS injected. De-duplicated (a project whose
+  // basename collides with a scope, or a repo with no branch, never repeats).
+  const readOrder = [...new Set([projectScope, branchScope, repoScope, 'global'].filter(Boolean))];
 
   return {
     ownerRepo,

package/src/store/local.mjs

@@ -316,7 +316,7 @@ class TwoTierStore {
     const projRes = this.projectActive()
       ? await this.project.search({ q, scopes, tags })
       : { entries: [] };
-    const merged = mergeByKey(projRes.entries, homeRes.entries, (e) => `${e.scope}${e.key}`);
+    const merged = mergeByKey(projRes.entries, homeRes.entries, (e) => `${e.scope}\x00${e.key}`);
     return { ok: true, entries: merged };
   }
 

package/src/tree.mjs

@@ -5,17 +5,18 @@
 //
 // Precedence is not an assumption — it mirrors the hook engine exactly. The
 // SessionStart hook (`core/lessons.mjs → fetchLessons`) reads the scopes in
-// `deriveScope().readOrder` (branch → repo → global, most-specific first) and
-// keeps the FIRST value seen per key, so a more-specific scope shadows a broader
-// scope's same-key lesson. `tree` resolves over that same `readOrder` set via
-// the pure `resolvePrecedence`, so it shows the same resolution order the agent
-// is injected with (the hook additionally caps the injected set at MAX_LESSONS;
-// `tree` is uncapped, so a large workspace may list more winners than the hook
-// injects).
+// `deriveScope().readOrder` (project → branch → repo → global, most-specific
+// first) and keeps the FIRST value seen per key, so a more-specific scope
+// shadows a broader scope's same-key lesson. `tree` resolves over that same
+// `readOrder` set via the pure `resolvePrecedence`, so it shows the same
+// resolution order the agent is injected with (the hook additionally caps the
+// injected set at MAX_LESSONS; `tree` is uncapped, so a large workspace may list
+// more winners than the hook injects).
 //
-// NOTE on scope coverage: `readOrder` is the injected set, and it deliberately
-// excludes `project::` — the hooks never inject project-scope lessons, so `tree`
-// doesn't either (browse those with `lorekit list`). Both stores are resolved
+// NOTE on scope coverage: `readOrder` is the injected set. As of the smart-hooks
+// PR it INCLUDES `project::` (project is the most-specific scope and now wins /
+// is injected), so `tree` shows it too — the ordering is now unified across the
+// hook, `tree`, and every read command's `scopeList`. Both stores are resolved
 // independently (precedence is per-store — the hook reads one resolved store),
 // in the same Offline / Remote split as `list`. Graceful, read-only, wrapped in
 // `traceCommand` by the bin.
@@ -24,7 +25,8 @@ import { resolveProjectRoot } from './config.mjs';
 import { deriveScope } from './scope.mjs';
 import { resolveDenies } from './control.mjs';
 import { resolveStores, remoteUnavailableReason } from './stores.mjs';
-import { gather, resolvePrecedence, preview, shortDate } from './lessons-view.mjs';
+import { resolvePrecedence } from './lessons-pure.mjs';
+import { gather, preview, shortDate } from './lessons-view.mjs';
 import { log, heading, status, c } from './util.mjs';
 
 export async function tree(args) {

package/src/uninstall.mjs

@@ -5,7 +5,7 @@ import path from 'node:path';
 import readline from 'node:readline';
 import process from 'node:process';
 import {
-  SKILL_NAME,
+  SKILLS,
   resolveProjectRoot,
   removeSkill,
   removeMcpServer,
@@ -51,7 +51,10 @@ export async function uninstall(args) {
   // install — never clobber what we can't understand), so we catch and report it
   // cleanly, leaving that file byte-for-byte untouched. Atomic writes
   // (writeFileAtomic) guarantee a config can't be half-written even on a crash.
-  const skill = attempt(() => removeSkill(root, scope));
+  const skillSteps = SKILLS.map((skill) => ({
+    name: skill.name,
+    step: attempt(() => removeSkill(root, scope, skill.name)),
+  }));
   const mcp = attempt(() => removeMcpServer(root, scope));
   const hooks = attempt(() => removeClaudeHooks(root, scope));
 
@@ -61,10 +64,12 @@ export async function uninstall(args) {
   const mcpLabel = scope === 'global' ? '~/.claude.json' : '.mcp.json';
 
   heading('Done');
-  report(skill, `skill ${SKILL_NAME}`, {
-    done: (r) => `removed → ${display(r.dest)}`,
-    noop: 'not installed — nothing to remove',
-  });
+  for (const { name, step } of skillSteps) {
+    report(step, `skill ${name}`, {
+      done: (r) => `removed → ${display(r.dest)}`,
+      noop: 'not installed — nothing to remove',
+    });
+  }
   report(mcp, mcpLabel, {
     done: (r) => `lorekit server removed → ${display(r.file)}`,
     noop: 'no lorekit server entry — nothing to remove',
@@ -74,8 +79,10 @@ export async function uninstall(args) {
     noop: 'no lorekit hooks — nothing to remove',
   });
 
-  const failed = [skill, mcp, hooks].some((s) => !s.ok);
-  const any = (skill.result?.removed || mcp.result?.removed || hooks.result?.removed) && true;
+  const skillStepList = skillSteps.map((s) => s.step);
+  const failed = [...skillStepList, mcp, hooks].some((s) => !s.ok);
+  const any =
+    (skillStepList.some((s) => s.result?.removed) || mcp.result?.removed || hooks.result?.removed) && true;
 
   if (failed) {
     log(`\n  ${c.dim('Some items could not be removed and were left untouched — see above.')}`);