@lorekit/cli 1.70.0 → 1.71.0

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`
@@ -1110,8 +1131,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 +1146,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)')}
 
@@ -1090,6 +1123,8 @@ const KNOWN_FLAGS = [
   'clear-max-opened-count', 'off',
   // `obligations`
   'files', 'strict', 'strict-all',
+  // `update`
+  'check',
 ];
 
 async function main() {
@@ -1102,7 +1137,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', 'check'],
     known: KNOWN_FLAGS,
   });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lorekit/cli",
-  "version": "1.70.0",
+  "version": "1.71.0",
   "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/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/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/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'),
+  );
+}