@lorekit/cli 1.70.0 → 1.71.1

package/README.md

@@ -210,6 +210,27 @@ itself:
 A revoked token is a **failure**, not a warning: fix it by creating a new token
 and running `lorekit install --force`, which offers to replace the stored one.
 
+### `lorekit update`
+
+Offline refresh of the bundled skills (and their hook command string) to the
+version shipped with the running CLI — the fix `doctor`'s outdated-skill
+warning and the SessionStart drift nudge (`updates.notify`) both point at.
+Fully offline: the shipped skill source travels in the same npm tarball as
+this CLI, so "installed vs shipped" is a filesystem version compare, never a
+network call.
+
+```bash
+lorekit update            # refresh every scope that already has an install
+lorekit update --check    # dry run: report drift, write nothing
+lorekit update --project  # only the project (.claude/skills) install
+lorekit update --global   # only the global (~/.claude/skills) install
+```
+
+`update` never CREATES a fresh install — that stays `install`'s job, so a
+scope with nothing installed is reported and left alone. Refreshing prunes
+any file the shipped skill no longer ships before re-copying, so a
+dropped rule file doesn't silently outlive the version that removed it.
+
 ### `lorekit list` (alias `ls`)
 
 Shows the lessons that apply to **where you are** — the scopes `deriveScope`
@@ -646,6 +667,75 @@ The server's refusal is printed verbatim with a one-line next step; the CLI make
 exactly one request and never retries, splits the sweep, or re-scopes around it.
 Use an unscoped `lk_rw_*` / `lk_wo_*` token for maintenance.
 
+### `lorekit groom` / `lorekit policy` / `lorekit protect` (aliases: `pin` / `unpin`)
+
+Retention automation — the CLI counterpart to the MCP `groom.*`/`policy.*`/
+`memory.protect` tools and the REST `/groom/*`/`/policies*`/`/protect` routes.
+**Remote only**, matching `purge`: `retention_policies` has no local-store
+equivalent.
+
+```bash
+# Preview what a rule would catch, without changing anything
+lorekit groom --scope repo::acme/app --unseen-days 90
+
+# Archive the matches (soft-archive, recoverable via `lorekit restore`)
+lorekit groom --scope repo::acme/app --unseen-days 90 --run --yes
+
+# Save it as a policy you can re-run by name, or let it sweep nightly
+lorekit policy create --scope repo::acme/app --name "stale repo lore" \
+  --unseen-days 90 --mode review
+lorekit policy list
+lorekit policy update <id> --mode auto --enabled
+lorekit policy delete <id>
+
+# Exempt one lesson from every rule and every manual sweep
+lorekit pin repo::acme/app::the-load-bearing-lesson
+lorekit unpin repo::acme/app::the-load-bearing-lesson
+```
+
+`groom [--policy-id <id> | --scope <s> [conditions…]] [--run] [--yes]` previews
+by default; `--run` archives. Exactly one of `--policy-id`/`--scope` is
+required. `policy <list|create|update|delete>` manages the SAVED rules
+`--policy-id` runs; `delete` removes the rule only, never the lessons it
+matched.
+
+Every condition ANDs together: the five age/activity fields
+(`--min-age-days`/`--unseen-days`/`--max-seen-count`/`--max-read-count`/
+`--max-opened-count`) plus the same **eight dimension filters** the Lore
+Explorer's filter bar offers —
+
+| Flag | `--<dim>-mode` values (default) |
+|------|----------------------------------|
+| `--tags <a,b>` | `any` \| `all` \| `none` (`any`) |
+| `--kind <a,b>` | `in` \| `nin` (`in`) |
+| `--host <a,b>` | `in` \| `nin` (`in`) |
+| `--trigger <a,b>` | `in` \| `nin` (`in`) |
+| `--source-agent <a,b>` | `in` \| `nin` (`in`) |
+| `--origin-repo <a,b>` | `in` \| `nin` (`in`) |
+| `--origin-branch <a,b>` | `in` \| `nin` (`in`) |
+| `--origin-pr <a,b>` | `in` \| `nin` (`in`) |
+
+— all comma-separated, same convention as `write --tags a,b,c`:
+
+```bash
+lorekit policy create --scope repo::acme/app --name "stale ci review events" \
+  --kind bus --kind-mode in --tags ci::pr-review-state --tags-mode all \
+  --min-age-days 30
+```
+
+`policy update` pairs every condition — age/count AND every dimension — with
+a `--clear-<field>` boolean (e.g. `--clear-kind`, `--clear-min-age-days`) that
+sends an explicit `null` rather than omitting the field: omitting a field on
+update leaves it unchanged, `null` clears it.
+
+```bash
+lorekit policy update <id> --clear-kind --host reviewer,aw
+```
+
+`protect <scope::key> [--off]` (or the shorter `pin`/`unpin`) marks a lesson as
+excluded from every policy and every `groom --run`, regardless of which rule
+would otherwise match it — persists until explicitly cleared.
+
 ### `lorekit hook`
 
 The **shared hook engine** behind the Claude Code / Cursor / Codex plugins.
@@ -1110,8 +1200,8 @@ also returns their headroom against the plan's memory cap.
 | Flag | Meaning |
 |------|---------|
 | `-d, --dir <path>` | Target project root (default: cwd) |
-| `--project` | Install into this repo: `.claude/skills` + `.mcp.json` (`install`; default) |
-| `--global` | Install for every project: `~/.claude/skills` + `~/.claude.json` (`install`) |
+| `--project` | Install into this repo: `.claude/skills` + `.mcp.json` (`install`; default). Narrows to the project scope (`update`) |
+| `--global` | Install for every project: `~/.claude/skills` + `~/.claude.json` (`install`). Narrows to the global scope (`update`) |
 | `-e, --endpoint <url>` | LoreKit MCP endpoint |
 | `-t, --token <token>` | LoreKit token |
 | `--mode <mode>` | Memory mode override for `doctor`: `off` / `local` / `remote` |
@@ -1125,6 +1215,7 @@ also returns their headroom against the plan's memory cap.
 | `--mcp-json` | Also write a committable project `.mcp.json` (auth via `${LOREKIT_TOKEN}`, no embedded token) for Claude Code on the web (`install`) |
 | `--force` | Overwrite existing skill files (`install`) |
 | `--deep` | Write/read/delete round-trip (`doctor`) |
+| `--check` | Dry run: report skill-install drift without writing anything (`update`) |
 | `--json` | Machine-readable output (`list` / `search` / `show` / `stats` / `scopes` / `diff` / `tree` / `lint` / `dedupe` / `obligations` / `invariants candidates` / `link` / `purge` / `purge-expired`) |
 | `--scope <scope>` | Restrict to a single scope (`list` / `search` / `stats` / `diff` / `tree` / `lint` / `dedupe` / `link`; default: all applicable). For `scopes` it is a **substring filter** over the inventory. On `show` / `write` it **names** the scope, overriding the positional |
 | `--key <key>` | Name the key outright (`show` / `write` / `link`) — the way to address a key that itself contains `::` |

package/bin/lorekit.mjs

@@ -39,6 +39,11 @@ ${c.bold('Commands')}
               other servers, hooks, and settings are left untouched. Prompts
               project vs global; --project / --global choose non-interactively.
   doctor      Verify the skill install, remote connectivity, token, and scope.
+  update      Offline refresh of the bundled skills (and their hook command
+              string) to the version shipped with the running CLI — the fix
+              for doctor's outdated-skill warning. Never creates a fresh
+              install (that's \`install\`'s job); --project / --global narrow
+              to one scope; --check reports drift without writing anything.
   list (ls)   List the memories that apply to the current directory, split into
               an Offline section (local .lorekit/ + ~/.lorekit/) and a Remote
               section (the hosted LoreKit API). Groups by scope (project/branch/repo/global).
@@ -169,6 +174,7 @@ ${c.bold('Options')}
       --force             Overwrite existing skill files (install)
       --deep              Do a write→read→delete round-trip (doctor)
       --telemetry         Verify the OTLP export credential works (doctor)
+      --check             Report drift without writing anything (update)
       --adapter <name>    Host framework for hook: claude | cursor | codex
       --event <name>      Host hook event (else read from stdin payload)
   -h, --help              Show this help
@@ -193,6 +199,7 @@ ${c.bold('Examples')}
   npx @lorekit/cli install --global    # set up memory for every project (~/.claude)
   npx @lorekit/cli uninstall --global  # tear that global setup back down
   npx @lorekit/cli doctor --deep
+  npx @lorekit/cli update --check      # report outdated skills without writing
   npx @lorekit/cli migrate --from .lore                 # preview a rename
   npx @lorekit/cli migrate --from .lore --to project --yes
   npx @lorekit/cli migrate --from .lorekit --to remote --yes  # push local lore up
@@ -302,6 +309,32 @@ ${c.bold('Examples')}
   npx @lorekit/cli doctor --deep
   npx @lorekit/cli doctor --telemetry
   npx @lorekit/cli doctor --mode local
+`,
+  update: `${c.bold('lorekit update')} — offline refresh of the bundled skills to the shipped version
+
+${c.bold('Usage')}
+  npx @lorekit/cli update [options]
+
+Re-copies every bundled skill (force) into whichever scope(s) already have an
+install, and refreshes that scope's hook command string — the same skill-copy
+path and hook-command call \`install --force\` uses, so the two can never
+disagree on what "installing a skill" means. Fully offline: the shipped skill
+source travels in the same npm tarball as this running CLI, so "installed vs
+shipped" is a filesystem version compare, not a network call. Never creates a
+fresh install — that's \`install\`'s job — so a scope with nothing installed is
+reported and left alone.
+
+${c.bold('Options')}
+  -d, --dir <path>        Target project root (default: current directory)
+      --project           Only refresh this project's install (.claude/skills)
+      --global            Only refresh the global install (~/.claude/skills)
+      --check             Dry run: report drift (installed vs shipped version
+                          per skill) and write nothing
+
+${c.bold('Examples')}
+  npx @lorekit/cli update
+  npx @lorekit/cli update --check
+  npx @lorekit/cli update --global
 `,
   list: `${c.bold('lorekit list')} — list the memories that apply to the current directory ${c.dim('(alias: ls)')}
 
@@ -902,7 +935,10 @@ ${c.bold('Options')}
 ${c.bold('Usage')}
   lorekit groom --policy-id <id> [--run] [--yes] [--json]
   lorekit groom --scope <s> [--min-age-days <n>] [--unseen-days <n>] [--max-seen-count <n>]
-                            [--max-read-count <n>] [--max-opened-count <n>] [--run] [--yes] [--json]
+                            [--max-read-count <n>] [--max-opened-count <n>]
+                            [--tags a,b --tags-mode any|all|none]
+                            [--kind|--host|--trigger|--source-agent|--origin-repo|--origin-branch|--origin-pr a,b [--<dim>-mode in|nin]]
+                            [--run] [--yes] [--json]
 
 Resolves the SAME candidates a saved policy or an inline condition set would
 catch, via the retention-policy candidate query — a previewed count always
@@ -927,6 +963,12 @@ ${c.bold('Options')}
                              the hundreds — a small value matches nothing
       --max-opened-count <n> Match only lessons an agent DELIBERATELY fetched at most n
                              times. Bulk reads do NOT count, so 0 means never chosen
+      --tags <a,b>, --tags-mode <any|all|none>
+                             Match lessons carrying these labels (default: any)
+      --kind, --host, --trigger, --source-agent,
+      --origin-repo, --origin-branch, --origin-pr <a,b>
+      --<dim>-mode <in|nin>  Match lessons whose dimension is one of these
+                             values (default: in); comma-separated
       --run                  Archive the matches instead of previewing
   -y, --yes                  Confirm --run; required when non-interactive
       --json                 Machine-readable result
@@ -941,12 +983,17 @@ ${c.bold('Usage')}
   lorekit policy create --scope <s> --name <n> [--mode review|auto] [--enabled]
                          [--min-age-days <n>] [--unseen-days <n>] [--max-seen-count <n>]
                          [--max-read-count <n>] [--max-opened-count <n>]
+                         [--tags a,b --tags-mode any|all|none]
+                         [--kind|--host|--trigger|--source-agent|--origin-repo|--origin-branch|--origin-pr a,b [--<dim>-mode in|nin]]
   lorekit policy update <id> [--name <n>] [--mode review|auto] [--enabled|--disabled]
-                         [--min-age-days <n>|--clear-min-age-days] [...] [--json]
+                         [--min-age-days <n>|--clear-min-age-days] [...]
+                         [--tags a,b|--clear-tags] [--<dim> a,b|--clear-<dim>] [--<dim>-mode in|nin] [--json]
   lorekit policy delete <id> [--yes] [--json]
 
 A policy is a saved retention rule: a scope plus AND-ed conditions
-(min-age-days / unseen-days / max-seen-count / max-read-count / max-opened-count).
+(min-age-days / unseen-days / max-seen-count / max-read-count / max-opened-count,
+plus the eight dimension filters — tags/kind/host/trigger/source-agent/
+origin-repo/origin-branch/origin-pr).
 \`mode: review\` surfaces it for
 you to run by hand with ${c.cyan('lorekit groom --policy-id')}; \`mode: auto\` gets swept
 nightly, but ONLY once you also pass --enabled — auto starts disabled on
@@ -962,8 +1009,14 @@ ${c.bold('Options')}
       --min-age-days <n>, --unseen-days <n>, --max-seen-count <n>, --max-read-count <n>,
       --max-opened-count <n>
                              Conditions (create/update)
+      --tags <a,b>, --tags-mode <any|all|none>
+      --kind, --host, --trigger, --source-agent,
+      --origin-repo, --origin-branch, --origin-pr <a,b>
+      --<dim>-mode <in|nin>  Dimension conditions (create/update); comma-separated
       --clear-min-age-days, --clear-unseen-days, --clear-max-seen-count,
-      --clear-max-read-count, --clear-max-opened-count
+      --clear-max-read-count, --clear-max-opened-count,
+      --clear-tags, --clear-kind, --clear-host, --clear-trigger,
+      --clear-source-agent, --clear-origin-repo, --clear-origin-branch, --clear-origin-pr
                              Remove a condition (update only)
   -y, --yes                  Confirm delete; required when non-interactive
       --json                 Machine-readable result
@@ -1088,8 +1141,20 @@ const KNOWN_FLAGS = [
   'name', 'mode', 'enabled', 'disabled',
   'clear-min-age-days', 'clear-unseen-days', 'clear-max-seen-count', 'clear-max-read-count',
   'clear-max-opened-count', 'off',
+  // The eight retention dimension filters' `*-mode` value flags (the value
+  // flags themselves — tags/source-agent/trigger/kind/host/origin-repo/
+  // origin-branch/origin-pr — are already listed above for `write`) plus
+  // their `clear-*` booleans (policy update only). See
+  // `shared/flags.mjs`'s `parseDimensionConditions`, the one place that
+  // owns the flag-name ↔ field-name ↔ mode-enum table these mirror.
+  'tags-mode', 'source-agent-mode', 'trigger-mode', 'kind-mode', 'host-mode',
+  'origin-repo-mode', 'origin-branch-mode', 'origin-pr-mode',
+  'clear-tags', 'clear-source-agent', 'clear-trigger', 'clear-kind', 'clear-host',
+  'clear-origin-repo', 'clear-origin-branch', 'clear-origin-pr',
   // `obligations`
   'files', 'strict', 'strict-all',
+  // `update`
+  'check',
 ];
 
 async function main() {
@@ -1102,7 +1167,7 @@ async function main() {
   const argv = process.argv.slice(2);
   const args = parseArgs(argv, {
     aliases: { d: 'dir', e: 'endpoint', t: 'token', y: 'yes', h: 'help', v: 'version' },
-    booleans: ['yes', 'force', 'deep', 'apply', 'help', 'version', 'global', 'project', 'no-hooks', 'mcp-json', 'no-origin', 'json', 'remote', 'local', 'link', 'archived', 'clear-ttl', 'telemetry', 'all', 'run', 'enabled', 'disabled', 'off', 'clear-min-age-days', 'clear-unseen-days', 'clear-max-seen-count', 'clear-max-read-count', 'clear-max-opened-count', 'strict', 'strict-all'],
+    booleans: ['yes', 'force', 'deep', 'apply', 'help', 'version', 'global', 'project', 'no-hooks', 'mcp-json', 'no-origin', 'json', 'remote', 'local', 'link', 'archived', 'clear-ttl', 'telemetry', 'all', 'run', 'enabled', 'disabled', 'off', 'clear-min-age-days', 'clear-unseen-days', 'clear-max-seen-count', 'clear-max-read-count', 'clear-max-opened-count', 'strict', 'strict-all', 'clear-tags', 'clear-source-agent', 'clear-trigger', 'clear-kind', 'clear-host', 'clear-origin-repo', 'clear-origin-branch', 'clear-origin-pr', 'check'],
     known: KNOWN_FLAGS,
   });
 

package/package.json

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

package/skill/lorekit-groom/SKILL.md

@@ -18,7 +18,7 @@ argument-hint: '[scope-hint]'
 license: MIT
 metadata:
   author: mthines
-  version: '1.0.0'
+  version: '1.1.0'
   workflow_type: shared-memory-grooming-and-consolidation
   tags:
     - lorekit

package/skill/lorekit-memory/SKILL.md

@@ -17,7 +17,7 @@ argument-hint: '[read|write] [scope-hint or lesson]'
 license: MIT
 metadata:
   author: mthines
-  version: '1.0.0'
+  version: '1.1.0'
   workflow_type: shared-memory-intake-and-retrospective
   tags:
     - lorekit

package/src/commands/doctor.mjs

@@ -7,7 +7,6 @@ import { execFileSync } from 'node:child_process';
 import {
   SKILLS,
   resolveProjectRoot,
-  skillInstallDir,
   CLAUDE_HOOK_EVENTS,
   installedHookEvents,
   hookModeFromEvents,
@@ -17,6 +16,7 @@ import {
   tokenKind,
   readLorekitJson,
 } from '../shared/config.mjs';
+import { checkSkillVersions } from '../shared/skill-versions.mjs';
 import { splitEndpoint } from '../shared/mcp.mjs';
 import {
   resolveTelemetryConfig,
@@ -71,18 +71,48 @@ export async function doctor(args) {
   // 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).
+  //
+  // Beyond existence, each installed scope now reports its VERSION against the
+  // one this CLI ships (`checkSkillVersions` — an offline compare of
+  // `metadata.version` in SKILL.md's frontmatter, see `shared/skill-versions.mjs`).
+  // An `outdated` or `unknown` (legacy, unparseable) install is a `warn`, never a
+  // `fail` — the skill still works, it just has no signal to update without this
+  // line — and names the fix scope-aware, mirroring the hooks-upgrade wording
+  // above: `lorekit update` is what a stale install is missing, the same way
+  // `lorekit install --hooks <mode>` is what a stale hook wiring is missing.
+  const skillVersions = checkSkillVersions(root);
   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 {
+    const installedEntries = skillVersions.filter(
+      (r) => r.name === skill.name && r.state !== 'not-installed',
+    );
+    if (installedEntries.length === 0) {
       record('fail', `skill ${skill.name}`, 'not found — run `lorekit install`');
+      continue;
+    }
+    for (const entry of installedEntries) {
+      const rel = path.relative(root, entry.installedPath);
+      const displayPath = rel && !rel.startsWith('..') ? rel : prettyPath(entry.installedPath);
+      // Only distinguish the scope in the label when the skill is installed in
+      // more than one — the common single-scope case keeps the pre-existing
+      // `skill <name>` label so it doesn't churn every doctor transcript.
+      const label = installedEntries.length > 1 ? `skill ${skill.name} (${entry.scope})` : `skill ${skill.name}`;
+      if (entry.state === 'current') {
+        record('pass', label, `${displayPath} — v${entry.installed}`);
+      } else if (entry.state === 'outdated') {
+        record(
+          'warn',
+          label,
+          `${displayPath} — v${entry.installed}, shipped v${entry.shipped} — ` +
+            `run \`lorekit update --${entry.scope}\` to refresh`,
+        );
+      } else {
+        record(
+          'warn',
+          label,
+          `${displayPath} — version unknown (legacy install predates version stamping) — ` +
+            `run \`lorekit update --${entry.scope}\` to refresh`,
+        );
+      }
     }
   }
 

package/src/commands/groom.mjs

@@ -11,7 +11,7 @@ import { resolveProjectRoot } from '../shared/config.mjs';
 import { loadControl, resolveDenies } from '../shared/control.mjs';
 import { resolveStores, remoteUnavailableReason } from '../shared/stores.mjs';
 import { log, err, c, select } from '../shared/util.mjs';
-import { parseIntFlag } from '../shared/flags.mjs';
+import { parseIntFlag, parseDimensionConditions } from '../shared/flags.mjs';
 
 /** Resolve the groom.preview/groom.run request from CLI args. */
 export function parseGroomRequest(args) {
@@ -33,6 +33,8 @@ export function parseGroomRequest(args) {
   if (maxRead.error) return { error: maxRead.error };
   const maxOpened = parseIntFlag(args['max-opened-count'], 'max-opened-count');
   if (maxOpened.error) return { error: maxOpened.error };
+  const dims = parseDimensionConditions(args, { clearable: false });
+  if (dims.error) return { error: dims.error };
 
   return {
     request: {
@@ -42,6 +44,7 @@ export function parseGroomRequest(args) {
       max_seen_count: maxSeen.value,
       max_read_count: maxRead.value,
       max_opened_count: maxOpened.value,
+      ...dims.conditions,
     },
   };
 }

package/src/commands/hook.mjs

@@ -30,6 +30,7 @@ import {
   recordShownLessons,
 } from '../core/state.mjs';
 import { recordFixture } from '../core/record.mjs';
+import { resolveUpdateNudge } from '../core/update-notify.mjs';
 import { claude } from '../adapters/claude.mjs';
 import { cursor } from '../adapters/cursor.mjs';
 import { codex } from '../adapters/codex.mjs';
@@ -62,6 +63,20 @@ function hookMeterAttrs(meter) {
   return attrs;
 }
 
+// Append the offline skill-update nudge to the SessionStart block, when the
+// throttle allows it. Best-effort by design — a broken drift check or a
+// throttle-file write failure must never cost the reader their lessons block,
+// so any error here silently falls back to `text` unmodified.
+function appendUpdateNudge(text, root, control) {
+  try {
+    const nudge = resolveUpdateNudge(root, { notify: control.updatesNotify });
+    if (!nudge) return text;
+    return text ? `${text}\n\n${nudge}` : nudge;
+  } catch {
+    return text;
+  }
+}
+
 function readStdin() {
   return new Promise((resolve) => {
     let data = '';
@@ -164,9 +179,10 @@ async function run(args, meter) {
       // No store: emit a minimal header + instruction when present, then return.
       // A SessionStart that cannot read lore is the highest-value failure to see.
       meter.outcome = HOOK_OUTCOME.STORE_UNAVAILABLE;
-      if (sessionInstruction) {
-        emit(formatLessons(null, { repoScope: null }, { instruction: sessionInstruction }));
-      }
+      const base = sessionInstruction
+        ? formatLessons(null, { repoScope: null }, { instruction: sessionInstruction })
+        : null;
+      emit(appendUpdateNudge(base, root, control));
       return 0;
     }
     const { scope: readScope, lessons, scopeCounts, applicable } = await fetchLessons(store, root, {
@@ -174,7 +190,7 @@ async function run(args, meter) {
       branchHint: control.hooksSessionStartBranchHint !== 'off',
       maxLessons: control.hooksSessionStartMaxLessons,
     });
-    emit(formatLessons(lessons, readScope, {
+    const lessonsBlock = formatLessons(lessons, readScope, {
       instruction: sessionInstruction,
       mode: control.hooksSessionStart,
       maxChars: control.hooksSessionStartMaxChars,
@@ -192,7 +208,8 @@ async function run(args, meter) {
       // `recordShownLessons` never throws, and a failure costs at most one
       // repeated lesson later in the session.
       onShown: (rendered) => recordShownLessons(parsed.sessionId, rendered.map(lessonId)),
-    }));
+    });
+    emit(appendUpdateNudge(lessonsBlock, root, control));
     return 0;
   }
 

package/src/commands/policy.mjs

@@ -15,7 +15,19 @@ import { resolveProjectRoot } from '../shared/config.mjs';
 import { loadControl, resolveDenies } from '../shared/control.mjs';
 import { resolveStores, remoteUnavailableReason } from '../shared/stores.mjs';
 import { log, err, c, select } from '../shared/util.mjs';
-import { parseIntFlag } from '../shared/flags.mjs';
+import { parseIntFlag, parseDimensionConditions } from '../shared/flags.mjs';
+
+/** `field` → display label for `formatPolicy`'s dimension summary. */
+const DIMENSION_DISPLAY = [
+  ['tags', 'tags_mode', 'tags'],
+  ['source_agent', 'source_agent_mode', 'source_agent'],
+  ['trigger', 'trigger_mode', 'trigger'],
+  ['kind', 'kind_mode', 'kind'],
+  ['host', 'host_mode', 'host'],
+  ['origin_repo', 'origin_repo_mode', 'origin_repo'],
+  ['origin_branch', 'origin_branch_mode', 'origin_branch'],
+  ['origin_pr', 'origin_pr_mode', 'origin_pr'],
+];
 
 function pickRemote({ root, env, args }) {
   const { remoteDenied } = resolveDenies(root, { env });
@@ -32,6 +44,12 @@ function formatPolicy(p) {
   if (p.max_seen_count != null) conditions.push(`max_seen_count=${p.max_seen_count}`);
   if (p.max_read_count != null) conditions.push(`max_read_count=${p.max_read_count}`);
   if (p.max_opened_count != null) conditions.push(`max_opened_count=${p.max_opened_count}`);
+  for (const [field, modeField, label] of DIMENSION_DISPLAY) {
+    const values = p[field];
+    if (!Array.isArray(values) || values.length === 0) continue;
+    const mode = p[modeField];
+    conditions.push(`${label}${mode ? `:${mode}` : ''}=[${values.join(',')}]`);
+  }
   const mode = p.mode === 'auto' ? (p.enabled ? c.green('auto (enabled)') : c.dim('auto (disabled)')) : c.dim('review');
   return `${c.cyan(p.id)}  ${c.bold(p.name)}  ${c.dim(p.scope)}  ${mode}${conditions.length ? `  ${c.dim(conditions.join(', '))}` : ''}`;
 }
@@ -52,7 +70,7 @@ async function list(args, store) {
 
 async function create(args, store) {
   if (!args.scope || !args.name) {
-    err(`${c.red('Usage:')} lorekit policy create --scope <scope> --name <name> [--mode review|auto] [--enabled] [--min-age-days N] [--unseen-days N] [--max-seen-count N] [--max-read-count N] [--max-opened-count N]`);
+    err(`${c.red('Usage:')} lorekit policy create --scope <scope> --name <name> [--mode review|auto] [--enabled] [--min-age-days N] [--unseen-days N] [--max-seen-count N] [--max-read-count N] [--max-opened-count N] [--tags a,b --tags-mode any|all|none] [--kind|--host|--trigger|--source-agent|--origin-repo|--origin-branch|--origin-pr a,b [--<dim>-mode in|nin]]`);
     return 1;
   }
   const minAge = parseIntFlag(args['min-age-days'], 'min-age-days');
@@ -69,6 +87,8 @@ async function create(args, store) {
     err(`${c.red('Error:')} --mode must be "review" or "auto"`);
     return 1;
   }
+  const dims = parseDimensionConditions(args, { clearable: false });
+  if (dims.error) { err(`${c.red('Error:')} ${dims.error}`); return 1; }
 
   const res = await store.policyCreate({
     scope: args.scope,
@@ -80,6 +100,7 @@ async function create(args, store) {
     max_seen_count: maxSeen.value,
     max_read_count: maxRead.value,
     max_opened_count: maxOpened.value,
+    ...dims.conditions,
   });
   if (!res.ok) {
     const msg = res.error?.message ?? res.error ?? res.networkError ?? 'the server rejected the request';
@@ -95,7 +116,7 @@ async function create(args, store) {
 async function update(args, store) {
   const id = args._[2];
   if (!id) {
-    err(`${c.red('Usage:')} lorekit policy update <id> [--name N] [--mode review|auto] [--enabled|--disabled] [--min-age-days N] [--unseen-days N] [--max-seen-count N] [--max-read-count N] [--max-opened-count N]`);
+    err(`${c.red('Usage:')} lorekit policy update <id> [--name N] [--mode review|auto] [--enabled|--disabled] [--min-age-days N|--clear-min-age-days] [...] [--tags a,b|--clear-tags] [--kind|--host|--trigger|--source-agent|--origin-repo|--origin-branch|--origin-pr a,b|--clear-<dim>] [--<dim>-mode ...]`);
     return 1;
   }
   if (args.mode !== undefined && args.mode !== 'review' && args.mode !== 'auto') {
@@ -121,6 +142,9 @@ async function update(args, store) {
     if (parsed.error) { err(`${c.red('Error:')} ${parsed.error}`); return 1; }
     patch[field] = parsed.value;
   }
+  const dims = parseDimensionConditions(args, { clearable: true });
+  if (dims.error) { err(`${c.red('Error:')} ${dims.error}`); return 1; }
+  Object.assign(patch, dims.conditions);
   if (Object.keys(patch).length === 0) {
     err(`${c.red('Error:')} at least one field to update is required`);
     return 1;

package/src/commands/update.mjs

@@ -0,0 +1,190 @@
+// `lorekit update` — refresh the bundled skills (and their hook wiring) to the
+// versions shipped with the running CLI.
+//
+// Fully offline: the shipped skill source travels in the SAME npm tarball as
+// this running CLI (`SKILLS[].source` in `shared/config.mjs`), so "installed
+// vs shipped" is a filesystem compare with zero network calls — see
+// `shared/skill-versions.mjs`, the same module `doctor` and the SessionStart
+// drift nudge (`core/update-notify.mjs`) read through, so all three surfaces
+// agree on what counts as outdated.
+//
+// `--check` is a dry run: report drift, write nothing. Without it, `update`
+// first PRUNES any file present in the install that the shipped skill no
+// longer ships (`pruneRemoved` — `copyDir` only ever writes, so without this
+// a rule file a newer version dropped would survive every future refresh
+// forever), then re-copies (force) every skill into whichever scope(s)
+// already have an install — reusing `copyDir`, the exact same skill-copy path
+// `install` uses, so the two can never drift on what "installing a skill"
+// means — and refreshes that scope's hook command string via `upsertClaudeHooks`, the
+// same call `install --force` makes. That refresh is deliberately in scope:
+// a stale `npx -y @lorekit/cli@1.2.3 hook …` pin or an old runner path is the
+// same class of drift this command exists to fix, the call is idempotent
+// (it only rewrites the command string, never the wired event set), and
+// skipping it would leave `update` unable to repair the one other thing an
+// install can go stale on. `--project` / `--global` narrow to one scope;
+// with neither, every scope that currently has an existing skill install is
+// refreshed — `update` never CREATES a fresh install, that stays `install`'s
+// job.
+import fs from 'node:fs';
+import path from 'node:path';
+import {
+  SKILLS,
+  resolveProjectRoot,
+  skillInstallDir,
+  copyDir,
+  installedHookEvents,
+  upsertClaudeHooks,
+  resolveHookRunner,
+} from '../shared/config.mjs';
+import { checkSkillVersions, SKILL_SCOPES } from '../shared/skill-versions.mjs';
+import { log, heading, status, c } from '../shared/util.mjs';
+
+// Which scopes `update` should touch. Explicit `--project`/`--global` narrow
+// to exactly one — but only when that scope actually has something installed;
+// naming a scope with nothing in it must still fall through to the "nothing
+// to update" report below, never silently report health on an empty scope.
+// `--global` is checked first, matching `install`/`uninstall`'s own
+// scope-flag precedence, so `--project --global` never picks the opposite
+// scope from its sibling commands.
+// With neither flag, every scope holding at least one installed skill (any
+// state other than `not-installed`) is refreshed.
+function targetScopes(args, results) {
+  const hasInstall = (scope) => results.some((r) => r.scope === scope && r.state !== 'not-installed');
+  if (args.global) return hasInstall('global') ? ['global'] : [];
+  if (args.project) return hasInstall('project') ? ['project'] : [];
+  return SKILL_SCOPES.filter(hasInstall);
+}
+
+// Remove any file under `dest` that no longer exists in `src` before the
+// refresh copy. `copyDir` only ever WRITES — it has no delete path — so a
+// rule/reference file a newer skill version dropped would otherwise survive
+// every future `update` forever, still sitting on disk and still read by the
+// agent alongside the content that superseded it, while `update` reports a
+// clean "already up to date" or a green "refreshed". Safe to prune
+// unconditionally: `update` never touches a scope the caller didn't already
+// have installed, and the refresh that follows overwrites everything that
+// DOES still exist in `src` anyway (`--force`), so nothing reachable from the
+// shipped skill is ever at risk — only content the shipped skill no longer
+// ships is removed.
+// `dryRun: true` counts what WOULD be removed without touching disk — the
+// preview `--check` shows for the one destructive step `update` takes, so a
+// dry run never has to say "outdated" and stay silent about a file the real
+// run is about to delete.
+function pruneRemoved(src, dest, { dryRun = false } = {}) {
+  if (!fs.existsSync(dest)) return 0;
+  let removed = 0;
+  for (const entry of fs.readdirSync(dest, { withFileTypes: true })) {
+    const destPath = path.join(dest, entry.name);
+    const srcPath = path.join(src, entry.name);
+    if (entry.isDirectory()) {
+      if (fs.existsSync(srcPath) && fs.statSync(srcPath).isDirectory()) {
+        removed += pruneRemoved(srcPath, destPath, { dryRun });
+      } else {
+        if (!dryRun) fs.rmSync(destPath, { recursive: true, force: true });
+        removed++;
+      }
+    } else if (!fs.existsSync(srcPath)) {
+      if (!dryRun) fs.rmSync(destPath, { force: true });
+      removed++;
+    }
+  }
+  return removed;
+}
+
+const versionLabel = (v) => (v ? `v${v}` : 'unknown');
+
+export async function update(args) {
+  const root = resolveProjectRoot(args.dir);
+  const dryRun = Boolean(args.check);
+
+  heading(dryRun ? 'LoreKit update (--check)' : 'LoreKit update');
+  log(`  project: ${c.dim(root)}`);
+
+  const results = checkSkillVersions(root);
+  const scopes = targetScopes(args, results);
+
+  if (scopes.length === 0) {
+    log('');
+    log(`  ${c.dim('no existing skill install found — nothing to update.')}`);
+    log(`  Run ${c.cyan('lorekit install')} for a fresh install.`);
+    return { exitCode: 0, 'lorekit.cli.update.scopes': 0, 'lorekit.cli.update.outdated': 0, 'lorekit.cli.update.check': dryRun };
+  }
+
+  heading('Skills');
+  let outdatedCount = 0;
+  let filesWritten = 0;
+  let filesRemoved = 0;
+  for (const scope of scopes) {
+    for (const skill of SKILLS) {
+      const entry = results.find((r) => r.scope === scope && r.name === skill.name);
+      if (!entry || entry.state === 'not-installed') continue;
+      const label = scopes.length > 1 ? `skill ${skill.name} (${scope})` : `skill ${skill.name}`;
+
+      if (entry.state === 'current') {
+        status('pass', label, `${versionLabel(entry.installed)} — already up to date`);
+        continue;
+      }
+
+      outdatedCount++;
+      const before = versionLabel(entry.installed);
+      const after = versionLabel(entry.shipped);
+      const dest = skillInstallDir(root, scope, skill.name);
+      if (dryRun) {
+        const wouldRemove = pruneRemoved(skill.source, dest, { dryRun: true });
+        const removedNote = wouldRemove > 0 ? `, ${wouldRemove} to remove` : '';
+        status('warn', label, `${before} → ${after} available${removedNote} — run \`lorekit update\` to refresh`);
+        continue;
+      }
+
+      const removed = pruneRemoved(skill.source, dest);
+      const written = copyDir(skill.source, dest, { force: true });
+      filesWritten += written;
+      filesRemoved += removed;
+      const removedNote = removed > 0 ? `, ${removed} removed` : '';
+      status('pass', label, `${before} → ${after} (${written} file(s) written${removedNote})`);
+    }
+  }
+
+  // Hook command strings — refreshed for real, never on a dry run. Only a
+  // scope that already has hooks wired has anything to refresh; a scope with
+  // none stays untouched (matching `install`'s own "nothing to wire" no-op).
+  // `upsertClaudeHooks` rewrites `.claude/settings.json` unconditionally
+  // (formatting included) even when every entry was already `unchanged` —
+  // tallying its returned counts is what lets the no-skills-outdated report
+  // below say so instead of silently rewriting the file underneath the user.
+  let hooksChanged = 0;
+  if (!dryRun) {
+    for (const scope of scopes) {
+      const wired = installedHookEvents(root, scope);
+      if (wired.length === 0) continue;
+      const stats = upsertClaudeHooks(root, scope, resolveHookRunner(), wired);
+      hooksChanged += stats.added + stats.updated + stats.removed + stats.deduped;
+    }
+  }
+
+  log('');
+  if (outdatedCount === 0) {
+    const hooksNote = hooksChanged > 0 ? ` (hook wiring refreshed: ${hooksChanged} change${hooksChanged === 1 ? '' : 's'})` : '';
+    log(`  ${c.green('✓')} every installed skill is already at the shipped version${hooksNote}.`);
+  } else if (dryRun) {
+    const plural = outdatedCount === 1 ? '' : 's';
+    log(`  ${c.yellow('!')} ${outdatedCount} skill install${plural} outdated — run \`lorekit update\` to apply.`);
+  } else {
+    const plural = outdatedCount === 1 ? '' : 's';
+    const removedNote = filesRemoved > 0 ? `, ${filesRemoved} removed` : '';
+    log(`  ${c.green('✓')} refreshed ${outdatedCount} skill install${plural} (${filesWritten} file(s) written${removedNote}).`);
+  }
+  log('');
+
+  return {
+    // Non-zero only for a `--check` run that found drift — a real run always
+    // finishes at 0 (it just fixed whatever it found), matching `doctor`'s own
+    // deliberate warn-never-fail posture. This is what lets `--check` gate a
+    // CI step or pre-commit hook on "everything is current" instead of only
+    // ever reporting drift for a human to notice.
+    exitCode: dryRun && outdatedCount > 0 ? 1 : 0,
+    'lorekit.cli.update.scopes': scopes.length,
+    'lorekit.cli.update.outdated': outdatedCount,
+    'lorekit.cli.update.check': dryRun,
+  };
+}

package/src/commands.mjs

@@ -36,6 +36,7 @@
 import { install } from './commands/install.mjs';
 import { uninstall } from './commands/uninstall.mjs';
 import { doctor } from './commands/doctor.mjs';
+import { update } from './commands/update.mjs';
 import { list } from './commands/list.mjs';
 import { search } from './commands/search.mjs';
 import { show } from './commands/show.mjs';
@@ -74,6 +75,7 @@ export const COMMANDS = [
   { name: 'install', run: install, traced: true, strictFlags: true, native: 'scaffolds skills, hooks and MCP config on disk' },
   { name: 'uninstall', run: uninstall, traced: true, strictFlags: true, native: 'removes what install wrote' },
   { name: 'doctor', run: doctor, traced: true, strictFlags: true, native: 'connectivity / token / scope health check' },
+  { name: 'update', run: update, traced: true, strictFlags: true, native: 'offline refresh of the bundled skills + hook wiring' },
   { name: 'list', run: list, traced: true, strictFlags: true, tool: 'memory.list', aliases: ['ls'] },
   { name: 'search', run: search, traced: true, strictFlags: true, tool: 'memory.search', aliases: ['grep'] },
   { name: 'show', run: show, traced: true, strictFlags: true, tool: 'memory.read' },

package/src/core/update-notify.mjs

@@ -0,0 +1,154 @@
+// SessionStart skill-update drift nudge: a terse, throttled line telling the
+// agent "your skills are stale, run `lorekit update`" — computed entirely
+// offline (see ../shared/skill-versions.mjs) and gated by `updates.notify`
+// (../shared/control.mjs).
+//
+// Throttle state lives at `$LOREKIT_HOME/update-state.json`, following the
+// exact precedent `telemetry/telemetry-identity.mjs` sets for a small,
+// user-owned JSON file under the home tier: TOTAL reads (a missing/corrupt
+// file degrades to `{}`, never throws), atomic writes via
+// `shared/config.mjs`'s `writeFileAtomic`, and the file is written ONLY when
+// there is something to record — never merely because this ran.
+//
+// The nudge fires at most once per NEW shipped-version signature, plus a
+// 7-day cooldown on repeating that same signature. `updates.notify: off`
+// short-circuits before any filesystem check runs, so an opted-out user's
+// disk is never touched by this module at all.
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import { homeRoot } from '../shared/control.mjs';
+import { writeFileAtomic } from '../shared/config.mjs';
+import { checkSkillVersions, skillsNeedingUpdate } from '../shared/skill-versions.mjs';
+
+const STATE_FILE = 'update-state.json';
+const COOLDOWN_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
+
+/** `$LOREKIT_HOME/update-state.json`, default `~/.lorekit/update-state.json`. */
+export function updateStatePath(env = process.env) {
+  return path.join(homeRoot(env), STATE_FILE);
+}
+
+/**
+ * Read the stored throttle state, or `{}`. TOTAL — a missing file, an
+ * unreadable one, a corrupt body, or a body that parses but isn't the right
+ * shape all yield `{}`, exactly like `telemetry-identity.mjs`'s `readIdentity`.
+ */
+export function readUpdateState(file = updateStatePath()) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return {};
+    const out = {};
+    if (typeof parsed.lastNotifiedVersion === 'string' && parsed.lastNotifiedVersion) {
+      out.lastNotifiedVersion = parsed.lastNotifiedVersion;
+    }
+    if (typeof parsed.lastNotifiedAt === 'number' && Number.isFinite(parsed.lastNotifiedAt)) {
+      out.lastNotifiedAt = parsed.lastNotifiedAt;
+    }
+    return out;
+  } catch {
+    return {};
+  }
+}
+
+// Persist the throttle state, creating the home directory if needed. Returns
+// true on success, false on any failure (unwritable home, full disk) — a
+// write failure must not surface as an error, since a hook this fires from
+// must never break the host on a filesystem hiccup.
+function writeUpdateState(state, file = updateStatePath()) {
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    writeFileAtomic(file, `${JSON.stringify(state, null, 2)}\n`);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * A stable signature naming exactly which skills need an update and at which
+ * shipped version, e.g. `"lorekit-memory@1.2.0,lorekit-setup@1.1.0"`. Sorted
+ * by skill name so the signature is deterministic regardless of scan order.
+ *
+ * This — not a bare boolean — is what the throttle compares against: a NEW
+ * release (a shipped version bump) or a previously-current skill drifting
+ * produces a DIFFERENT signature, which re-qualifies for a nudge even inside
+ * the 7-day cooldown on the old one. `""` means nothing needs an update.
+ */
+export function driftSignature(results) {
+  const bySkill = new Map();
+  for (const r of skillsNeedingUpdate(results)) {
+    if (!r.shipped || bySkill.has(r.name)) continue;
+    bySkill.set(r.name, r.shipped);
+  }
+  return [...bySkill.entries()]
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([name, shipped]) => `${name}@${shipped}`)
+    .join(',');
+}
+
+/**
+ * Render the one-line nudge, or `null` when nothing needs an update. De-duped
+ * by skill name (the same `name -> shipped` Map `driftSignature` builds) —
+ * `skillsNeedingUpdate` returns one row per (skill, scope), and without the
+ * dedupe a skill outdated in BOTH the project and global install would count
+ * itself twice in the "(+N more)" tail. An `unknown` row (no readable
+ * installed version — the drift signature counts it too, see
+ * `driftSignature`) still gets named, just without a "vX →" on its left side,
+ * so the nudge is never silently dropped for the one state that most needs a
+ * "go look" — a legacy install with no parseable version at all.
+ */
+export function formatUpdateNudge(results) {
+  const bySkill = new Map();
+  for (const r of skillsNeedingUpdate(results)) {
+    if (!r.shipped || bySkill.has(r.name)) continue;
+    bySkill.set(r.name, r);
+  }
+  const needing = [...bySkill.values()];
+  if (needing.length === 0) return null;
+  const [first, ...rest] = needing;
+  const extra = rest.length > 0 ? ` (+${rest.length} more)` : '';
+  const headline = first.installed
+    ? `${first.name} v${first.installed} → v${first.shipped}`
+    : `${first.name} → v${first.shipped}`;
+  return (
+    `LoreKit skills are outdated (${headline}${extra}). ` +
+    'Run `lorekit update` to refresh.'
+  );
+}
+
+/**
+ * The full resolve: should a SessionStart nudge fire right now, and if so,
+ * record the throttle state and return the text? `null` means stay silent —
+ * `notify: off`, nothing outdated, or the same signature is still inside its
+ * 7-day cooldown.
+ *
+ * TOTAL and side-effect-light: nothing is read or written when `notify` is
+ * `off`, and the state file is written ONLY on the turn that actually emits a
+ * nudge — never merely because this ran. Any unexpected error (a throwing
+ * filesystem call the individual helpers didn't already swallow) is caught
+ * here too, so a caller never needs its own try/catch to stay safe.
+ */
+export function resolveUpdateNudge(root, { notify = 'auto', now = Date.now(), env = process.env } = {}) {
+  if (notify === 'off') return null;
+  try {
+    const results = checkSkillVersions(root);
+    const signature = driftSignature(results);
+    if (!signature) return null;
+
+    const file = updateStatePath(env);
+    const state = readUpdateState(file);
+    const sameSignature = state.lastNotifiedVersion === signature;
+    const withinCooldown =
+      typeof state.lastNotifiedAt === 'number' && now - state.lastNotifiedAt < COOLDOWN_MS;
+    if (sameSignature && withinCooldown) return null;
+
+    const text = formatUpdateNudge(results);
+    if (!text) return null;
+
+    writeUpdateState({ lastNotifiedVersion: signature, lastNotifiedAt: now }, file);
+    return text;
+  } catch {
+    return null;
+  }
+}

package/src/shared/completions.mjs

@@ -43,6 +43,7 @@ const FLAG = {
   force: { desc: 'Overwrite / hard-delete' },
   deep: { desc: 'Do a write→read→delete round-trip' },
   telemetry: { desc: 'Verify the OTLP export credential works' },
+  check: { desc: 'Report drift without writing anything' },
   json: { desc: 'Machine-readable output' },
   scope: { desc: 'Restrict to / name a scope', arg: 'scope', complete: 'scope' },
   key: { desc: 'Name the key explicitly', arg: 'key' },
@@ -107,6 +108,8 @@ const COMMANDS = [
     flags: ['dir', 'project', 'global', 'yes'] },
   { name: 'doctor', summary: 'Verify the install, connectivity, token, scope',
     flags: ['dir', 'mode', 'endpoint', 'token', 'store', 'deep', 'telemetry'] },
+  { name: 'update', summary: 'Offline refresh of the bundled skills to the shipped version',
+    flags: ['dir', 'project', 'global', 'check'] },
   { name: 'list', summary: 'List memories for the current directory', aliases: ['ls'],
     flags: ['dir', 'scope', 'json', 'endpoint', 'token', 'store', 'link', 'base'] },
   { name: 'search', summary: 'Full-text search the applicable memories', aliases: ['grep'],

package/src/shared/control.mjs

@@ -61,6 +61,21 @@ export function normalizeStopMode(v) {
   return null;
 }
 
+// `updates.notify` — whether the SessionStart hook may append a terse
+// skill-update nudge when an installed skill has drifted behind the version
+// this CLI ships. `auto` (default) | `off`. Same forgiving-vocabulary /
+// repo-wins model as `hooks.stop`: a plain boolean, `false`/`none`/`disabled`
+// all mean `off`, so a hand-edited JSON file reads naturally either way.
+export const UPDATE_NOTIFY_MODES = ['auto', 'off'];
+export function normalizeUpdateNotifyMode(v) {
+  if (typeof v === 'boolean') return v ? 'auto' : 'off';
+  if (typeof v !== 'string') return null;
+  const s = v.trim().toLowerCase();
+  if (['off', 'none', 'false', 'disabled', 'never', 'no'].includes(s)) return 'off';
+  if (['auto', 'on', 'true', 'enabled', 'always', 'yes'].includes(s)) return 'auto';
+  return null;
+}
+
 // `hooks.userPrompt` — the per-turn relevance pull, on or off.
 //
 // A BOOLEAN, not a mode, and that is a deliberate limit on the surface. The
@@ -454,6 +469,12 @@ export function resolveControl({
     normalizeUserPromptMode(userConfig['hooks.sessionStart.branchHint']) ||
     'on';
 
+  // `updates.notify` — repo layer wins over user layer, default `auto`.
+  const updatesNotify =
+    normalizeUpdateNotifyMode(repoConfig['updates.notify']) ||
+    normalizeUpdateNotifyMode(userConfig['updates.notify']) ||
+    'auto';
+
   // `hooks.adapter` — repo layer wins over user layer (explicit project override).
   const hooksAdapter =
     (typeof repoConfig['hooks.adapter'] === 'string' && repoConfig['hooks.adapter'].trim()) ||
@@ -499,6 +520,7 @@ export function resolveControl({
     hooksSessionStartBranchHint,
     hooksAdapter,
     hooksInstructions,
+    updatesNotify,
   };
 }
 

package/src/shared/flags.mjs

@@ -14,3 +14,76 @@ export function parseIntFlag(raw, name) {
   }
   return { value: Number(String(raw).trim()) };
 }
+
+/**
+ * The eight dimension filters a retention policy / inline groom call can
+ * carry (migration 00093) — the CLI's flag-name ↔ field-name ↔ valid-mode
+ * table. Mirrors `groomDimensionFilterProperties` in
+ * `packages/schemas/src/shared/tool-catalog.ts` and `GROOM_DIMENSION_FIELDS`
+ * in `supabase/functions/mcp/tools.ts`; kept as ONE list here (not three) so
+ * `policy create`/`policy update`/`groom` cannot describe the dimensions
+ * differently.
+ */
+const DIMENSIONS = [
+  { flag: 'tags', field: 'tags', modes: ['any', 'all', 'none'] },
+  { flag: 'source-agent', field: 'source_agent', modes: ['in', 'nin'] },
+  { flag: 'trigger', field: 'trigger', modes: ['in', 'nin'] },
+  { flag: 'kind', field: 'kind', modes: ['in', 'nin'] },
+  { flag: 'host', field: 'host', modes: ['in', 'nin'] },
+  { flag: 'origin-repo', field: 'origin_repo', modes: ['in', 'nin'] },
+  { flag: 'origin-branch', field: 'origin_branch', modes: ['in', 'nin'] },
+  { flag: 'origin-pr', field: 'origin_pr', modes: ['in', 'nin'] },
+];
+
+/**
+ * Parse the eight retention dimension filters (`--tags`/`--kind`/`--host`/
+ * `--trigger`/`--source-agent`/`--origin-repo`/`--origin-branch`/`--origin-pr`,
+ * each with a `--<dim>-mode`) out of a parsed-args object.
+ *
+ * Comma-separated values — matching the existing `write --tags a,b,c`
+ * convention. The minimal flag parser (`bin/lorekit.mjs`'s `parseArgs`) is
+ * last-wins on a repeated flag, so comma-splitting is the established
+ * multi-value shape in this CLI, not a new one invented here.
+ *
+ * `--<dim>-mode` is validated against that DIMENSION's own enum (`tags-mode`
+ * accepts any/all/none; every other dimension accepts in/nin) — an invalid
+ * value is rejected rather than silently forwarded to the RPC as a raw
+ * Postgres enum error.
+ *
+ * With `clearable: true` (policy update), `--clear-<dim>` sends an explicit
+ * `null` for the VALUE field only, and skips both the value and mode flags for
+ * that dimension entirely — matching how `policy update --clear-min-age-days`
+ * already ignores `--min-age-days` when both are passed. The MODE field is
+ * left untouched by a clear: it is meaningless once the value is null, and
+ * silently dropping it if the caller separately set it would be a second
+ * surprise on top of the clear.
+ *
+ * Returns `{ conditions }` containing only the fields the caller actually
+ * named — never a full 16-key object of undefineds, so a caller can spread it
+ * straight into a request body without a second `stripUndefined` pass losing
+ * an intentional `null` — or `{ error }` naming the offending flag.
+ */
+export function parseDimensionConditions(args, { clearable = false } = {}) {
+  const conditions = {};
+  for (const { flag, field, modes } of DIMENSIONS) {
+    if (clearable && args[`clear-${flag}`]) {
+      conditions[field] = null;
+      continue;
+    }
+    const raw = args[flag];
+    if (raw !== undefined) {
+      conditions[field] = String(raw)
+        .split(',')
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+    }
+    const modeRaw = args[`${flag}-mode`];
+    if (modeRaw !== undefined) {
+      if (!modes.includes(modeRaw)) {
+        return { error: `--${flag}-mode must be one of ${modes.join('|')}, got ${JSON.stringify(String(modeRaw))}` };
+      }
+      conditions[`${field}_mode`] = modeRaw;
+    }
+  }
+  return { conditions };
+}

package/src/shared/skill-versions.mjs

@@ -0,0 +1,148 @@
+// Offline "installed vs shipped" skill version check.
+//
+// `lorekit install` copies each skill's SKILL.md verbatim and stamps no version
+// anywhere else, so a skill installed at an old version has reported a healthy
+// `doctor` PASS forever with no signal to update. The version data already
+// exists: every skill's `SKILL.md` frontmatter carries `metadata.version`
+// (e.g. `'1.0.0'`), and the shipped skill source travels in the SAME npm
+// tarball as the running CLI (`SKILLS[].source` in `./config.mjs`) — so
+// comparing "what's on disk" against "what this CLI ships" needs zero network
+// calls and no server round-trip. `doctor` (per-scope reporting) and
+// `lorekit update` (the refresh command) and the SessionStart drift nudge
+// (`../core/update-notify.mjs`) all read through this one module so the three
+// surfaces can't disagree about what counts as outdated.
+//
+// Dependency-free `.mjs`, like the other `shared/*.mjs` pure modules — no npm
+// imports beyond node builtins.
+import fs from 'node:fs';
+import path from 'node:path';
+import { SKILLS, skillInstallDir } from './config.mjs';
+
+/**
+ * Pull the YAML frontmatter block out of a SKILL.md body — the text between
+ * the first `---` line and the next one. `null` when there is no such block
+ * (not a SKILL.md-shaped file, or a corrupt/truncated one).
+ */
+export function extractFrontmatter(markdown) {
+  const m = /^---\r?\n([\s\S]*?)\r?\n---/.exec(typeof markdown === 'string' ? markdown : '');
+  return m ? m[1] : null;
+}
+
+/**
+ * Parse `metadata.version` out of a SKILL.md's frontmatter.
+ *
+ * Deliberately minimal: every SKILL.md this CLI ships has exactly one
+ * `version:` line (nested under `metadata:`), so a plain line match — robust
+ * to single/double quotes and a trailing comment — is enough without pulling
+ * in a YAML parser this zero-dep package does not otherwise need. Returns
+ * `null` when the frontmatter is absent or carries no `version:` line at all
+ * (a legacy skill file predating the version stamp).
+ */
+export function parseSkillVersion(markdown) {
+  const frontmatter = extractFrontmatter(markdown);
+  if (!frontmatter) return null;
+  const m = /^[ \t]*version:[ \t]*(['"]?)([^'"\n#]+?)\1[ \t]*(?:#.*)?$/m.exec(frontmatter);
+  if (!m) return null;
+  const version = m[2].trim();
+  return version || null;
+}
+
+// Read + parse a SKILL.md's version, or `null` for anything that isn't a
+// readable, parseable file — an absent path, a permissions error, and a file
+// with no `version:` line all collapse to the same "unknown" signal.
+function readVersion(skillMdPath) {
+  try {
+    return parseSkillVersion(fs.readFileSync(skillMdPath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Dependency-free semver-ish compare of two dotted-numeric version strings.
+ *
+ * Returns `-1` / `0` / `1` the usual way, or `null` when either input is not a
+ * usable version string (missing, empty, or containing a non-numeric segment —
+ * pre-release/build metadata like `1.0.0-beta` is intentionally out of scope,
+ * since every shipped SKILL.md version is a plain `x.y.z`). `null` reads as
+ * "cannot compare", which callers treat as `unknown` rather than guessing a
+ * direction.
+ */
+export function compareVersions(a, b) {
+  if (typeof a !== 'string' || typeof b !== 'string' || !a.trim() || !b.trim()) return null;
+  const toParts = (v) => v.trim().split('.').map((seg) => Number(seg));
+  const pa = toParts(a);
+  const pb = toParts(b);
+  if (pa.some((n) => !Number.isFinite(n)) || pb.some((n) => !Number.isFinite(n))) return null;
+  const len = Math.max(pa.length, pb.length);
+  for (let i = 0; i < len; i++) {
+    const x = pa[i] ?? 0;
+    const y = pb[i] ?? 0;
+    if (x < y) return -1;
+    if (x > y) return 1;
+  }
+  return 0;
+}
+
+/** The scopes a skill can be installed in — matches `skillInstallDir`'s. */
+export const SKILL_SCOPES = ['project', 'global'];
+
+/**
+ * Classify one (skill, scope) pair against the version this CLI ships.
+ *
+ * `state`:
+ *   - `not-installed` — no SKILL.md at that scope.
+ *   - `current`       — installed version >= shipped version.
+ *   - `outdated`       — installed version < shipped version.
+ *   - `unknown`       — a SKILL.md exists but a version could not be
+ *                        resolved on one side (an unparseable/legacy
+ *                        installed file, or — in practice never — an
+ *                        unparseable shipped one), so no direction can be
+ *                        asserted.
+ */
+function classify(installedPath, shipped) {
+  const installedExists = fs.existsSync(installedPath);
+  if (!installedExists) {
+    return { installed: null, state: 'not-installed' };
+  }
+  const installed = readVersion(installedPath);
+  if (installed == null || shipped == null) {
+    return { installed, state: 'unknown' };
+  }
+  const cmp = compareVersions(installed, shipped);
+  if (cmp === null) return { installed, state: 'unknown' };
+  return { installed, state: cmp < 0 ? 'outdated' : 'current' };
+}
+
+/**
+ * Check every skill in `skills` (default: the CLI's own `SKILLS` list) at
+ * every scope, comparing the INSTALLED `SKILL.md`'s `metadata.version`
+ * against the SHIPPED source's. Pure filesystem reads — no network, no store.
+ *
+ * Returns one row per (skill, scope):
+ *   `{ name, scope, installedPath, installed, shipped, state }`
+ */
+export function checkSkillVersions(root, { skills = SKILLS } = {}) {
+  const results = [];
+  for (const skill of skills) {
+    const shipped = readVersion(path.join(skill.source, 'SKILL.md'));
+    for (const scope of SKILL_SCOPES) {
+      const installedPath = path.join(skillInstallDir(root, scope, skill.name), 'SKILL.md');
+      const { installed, state } = classify(installedPath, shipped);
+      results.push({ name: skill.name, scope, installedPath, installed, shipped, state });
+    }
+  }
+  return results;
+}
+
+/**
+ * The subset of `checkSkillVersions` results that need an update — `outdated`
+ * or `unknown` (a legacy install with no readable version is exactly the case
+ * `lorekit update` exists to repair, since re-copying stamps a fresh one).
+ * `not-installed` and `current` are excluded — neither one is drift to act on.
+ */
+export function skillsNeedingUpdate(results) {
+  return (Array.isArray(results) ? results : []).filter(
+    (r) => r && (r.state === 'outdated' || r.state === 'unknown'),
+  );
+}

package/src/store/remote.mjs

@@ -42,6 +42,20 @@ function stripUndefined(obj) {
   return out;
 }
 
+// Drop only `undefined` — keeps an explicit `null`. Bare `stripUndefined`
+// above is right for a CREATE body, where an omitted dimension and an
+// explicit `null` mean the same "not filtered". It is wrong for a PATCH,
+// where `null` is the caller's explicit instruction to CLEAR a
+// previously-set condition (`policy update --clear-kind`) — dropping it
+// there means the field silently stays whatever it already was, which is
+// the opposite of what was asked. Named for what it keeps, not what it
+// drops, since "strip" alone reads as "strip everything falsy-ish".
+function stripUndefinedKeepNull(obj) {
+  const out = {};
+  for (const [k, v] of Object.entries(obj || {})) if (v !== undefined) out[k] = v;
+  return out;
+}
+
 /**
  * A read that could not be answered — a transport failure or a non-2xx status,
  * as opposed to "the lesson is not there".
@@ -768,9 +782,20 @@ class RemoteStore {
     return { ok: true, entries: Array.isArray(res.data?.entries) ? res.data.entries : [] };
   }
 
-  // POST /policies → the created policy object.
-  async policyCreate({ scope, name, mode, enabled, min_age_days, unseen_days, max_seen_count, max_read_count, max_opened_count } = {}) {
-    const body = stripUndefined({ scope, name, mode, enabled, min_age_days, unseen_days, max_seen_count, max_read_count, max_opened_count });
+  // POST /policies → the created policy object. `...dims` carries whichever
+  // of the eight dimension filters (+ their `_mode` companions) the caller
+  // named — see `parseDimensionConditions` in `shared/flags.mjs`, the shared
+  // parser policy create/update and groom all go through.
+  async policyCreate({
+    scope, name, mode, enabled, min_age_days, unseen_days, max_seen_count, max_read_count, max_opened_count,
+    tags, tags_mode, source_agent, source_agent_mode, trigger, trigger_mode, kind, kind_mode, host, host_mode,
+    origin_repo, origin_repo_mode, origin_branch, origin_branch_mode, origin_pr, origin_pr_mode,
+  } = {}) {
+    const body = stripUndefined({
+      scope, name, mode, enabled, min_age_days, unseen_days, max_seen_count, max_read_count, max_opened_count,
+      tags, tags_mode, source_agent, source_agent_mode, trigger, trigger_mode, kind, kind_mode, host, host_mode,
+      origin_repo, origin_repo_mode, origin_branch, origin_branch_mode, origin_pr, origin_pr_mode,
+    });
     const res = await this._rest('/memories/policies', { method: 'POST', body });
     if (!res.ok) return { ok: false, error: res.error, httpStatus: res.httpStatus, networkError: res.networkError };
     return { ok: true, policy: res.data };
@@ -778,10 +803,11 @@ class RemoteStore {
 
   // PATCH /policies/:id → the updated policy object. An omitted field is left
   // unchanged; pass an explicit `null` in the patch to clear a condition —
-  // this method does not strip nulls, only `undefined` (stripUndefined keeps
-  // that distinction, which is the whole point of the RPC's JSONB-patch design).
+  // this method does not strip nulls, only `undefined` (stripUndefinedKeepNull
+  // keeps that distinction, which is the whole point of the RPC's JSONB-patch
+  // design and of `policy update --clear-*`).
   async policyUpdate(id, patch = {}) {
-    const body = stripUndefined(patch);
+    const body = stripUndefinedKeepNull(patch);
     const res = await this._rest(`/memories/policies/${encodeURIComponent(id)}`, { method: 'PATCH', body });
     if (!res.ok) return { ok: false, error: res.error, httpStatus: res.httpStatus, networkError: res.networkError };
     return { ok: true, policy: res.data };
@@ -796,9 +822,18 @@ class RemoteStore {
 
   // POST /groom/preview → { count, keys: [{ scope, key }] } — the SAME
   // candidates a groom() run would archive. Pass either `policy_id` or
-  // `scope` (+ optional conditions), never both.
-  async groomPreview({ policy_id, scope, min_age_days, unseen_days, max_seen_count, max_read_count, max_opened_count } = {}) {
-    const body = stripUndefined({ policy_id, scope, min_age_days, unseen_days, max_seen_count, max_read_count, max_opened_count });
+  // `scope` (+ optional conditions, including the eight dimension filters —
+  // see policyCreate's comment), never both.
+  async groomPreview({
+    policy_id, scope, min_age_days, unseen_days, max_seen_count, max_read_count, max_opened_count,
+    tags, tags_mode, source_agent, source_agent_mode, trigger, trigger_mode, kind, kind_mode, host, host_mode,
+    origin_repo, origin_repo_mode, origin_branch, origin_branch_mode, origin_pr, origin_pr_mode,
+  } = {}) {
+    const body = stripUndefined({
+      policy_id, scope, min_age_days, unseen_days, max_seen_count, max_read_count, max_opened_count,
+      tags, tags_mode, source_agent, source_agent_mode, trigger, trigger_mode, kind, kind_mode, host, host_mode,
+      origin_repo, origin_repo_mode, origin_branch, origin_branch_mode, origin_pr, origin_pr_mode,
+    });
     const res = await this._rest('/memories/groom/preview', { method: 'POST', body });
     if (!res.ok) return { ok: false, error: res.error, httpStatus: res.httpStatus, networkError: res.networkError };
     return { ok: true, count: res.data?.count ?? 0, keys: Array.isArray(res.data?.keys) ? res.data.keys : [] };
@@ -806,8 +841,16 @@ class RemoteStore {
 
   // POST /groom/run → archives every previewed candidate, in one transaction.
   // Soft-archive only (recoverable via restore); never hard-deletes.
-  async groomRun({ policy_id, scope, min_age_days, unseen_days, max_seen_count, max_read_count, max_opened_count } = {}) {
-    const body = stripUndefined({ policy_id, scope, min_age_days, unseen_days, max_seen_count, max_read_count, max_opened_count });
+  async groomRun({
+    policy_id, scope, min_age_days, unseen_days, max_seen_count, max_read_count, max_opened_count,
+    tags, tags_mode, source_agent, source_agent_mode, trigger, trigger_mode, kind, kind_mode, host, host_mode,
+    origin_repo, origin_repo_mode, origin_branch, origin_branch_mode, origin_pr, origin_pr_mode,
+  } = {}) {
+    const body = stripUndefined({
+      policy_id, scope, min_age_days, unseen_days, max_seen_count, max_read_count, max_opened_count,
+      tags, tags_mode, source_agent, source_agent_mode, trigger, trigger_mode, kind, kind_mode, host, host_mode,
+      origin_repo, origin_repo_mode, origin_branch, origin_branch_mode, origin_pr, origin_pr_mode,
+    });
     const res = await this._rest('/memories/groom/run', { method: 'POST', body });
     if (!res.ok) return { ok: false, error: res.error, httpStatus: res.httpStatus, networkError: res.networkError };
     return { ok: true, archived: res.data?.archived ?? 0, keys: Array.isArray(res.data?.keys) ? res.data.keys : [] };