@lorekit/cli 1.15.0 → 1.17.0

package/README.md

@@ -483,6 +483,16 @@ Both files share this schema — all fields optional:
                            // values: "claude" | "cursor" | "codex"
                            // repo wins over user
 
+  "hooks.instructions": {
+    "SessionStart":        "Focus on migration safety. Treat any lesson tagged 'migration' as high-priority.",
+    "PostToolUseFailure":  "When recording a failure, always include the exact command and exit code.",
+    "Stop":                null
+  },
+                           // per-event custom text appended to the hook output.
+                           // both layers merged: repo instructions first, then user.
+                           // null (or absent key) means no extra instruction for that event.
+                           // values: string | null  (keys: "SessionStart" | "PostToolUseFailure" | "Stop")
+
   // ── Telemetry ──────────────────────────────────────────────────────────────
   "telemetry.disabled": true,
                            // team-level opt-out for orgs with a no-telemetry policy

package/package.json

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

package/src/control.mjs

@@ -137,6 +137,27 @@ export function resolveControl({
     (typeof userConfig['hooks.adapter'] === 'string' && userConfig['hooks.adapter'].trim()) ||
     null;
 
+  // `hooks.instructions` — per-event custom text appended to the hook output so
+  // teams can embed project-specific guidance directly into the injected context.
+  // Both layers contribute: repo instructions come first, user instructions follow
+  // (same direction as `tags.default` — repo supplements, user personalises).
+  // null for a given event means "no custom instruction for that event".
+  const HOOK_EVENTS = ['SessionStart', 'PostToolUseFailure', 'Stop'];
+  const hooksInstructions = {};
+  {
+    const repoInstr =
+      (repoConfig['hooks.instructions'] && typeof repoConfig['hooks.instructions'] === 'object')
+        ? repoConfig['hooks.instructions'] : {};
+    const userInstr =
+      (userConfig['hooks.instructions'] && typeof userConfig['hooks.instructions'] === 'object')
+        ? userConfig['hooks.instructions'] : {};
+    for (const ev of HOOK_EVENTS) {
+      const parts = [repoInstr[ev], userInstr[ev]]
+        .filter((v) => typeof v === 'string' && v.trim().length > 0);
+      hooksInstructions[ev] = parts.length > 0 ? parts.join('\n') : null;
+    }
+  }
+
   return {
     mode: chosen.mode,
     storeTarget,
@@ -147,6 +168,7 @@ export function resolveControl({
     scopeDefaults,
     hooksDisabled,
     hooksAdapter,
+    hooksInstructions,
   };
 }
 

package/src/core/lessons.mjs

@@ -51,19 +51,56 @@ export async function fetchLessons(store, cwd) {
   return { scope, lessons: lessons.slice(0, MAX_LESSONS) };
 }
 
-// Render lessons as a compact markdown block, or null when there are none.
-export function formatLessons(lessons, scope) {
-  if (!lessons || lessons.length === 0) return null;
+// Cap on a lesson's one-line hook in the injected index. Long enough to jog
+// recognition, short enough that N lessons stay a scannable list, not a wall —
+// the full text is always one `memory.read` away.
+const HOOK_LEN = 80;
+
+// A lesson's first meaningful line, cleaned into a short recognisable hook:
+// skips leading HTML-comment metadata (`<!-- ... -->`) and markdown heading
+// marks, collapses whitespace, and truncates on a word boundary with an
+// ellipsis — so nothing is ever cut mid-word into noise like "cascades to GE".
+function lessonHook(value, max = HOOK_LEN) {
+  let first = '';
+  for (const raw of String(value || '').split('\n')) {
+    const line = raw.trim();
+    if (!line || line.startsWith('<!--')) continue; // skip blanks + meta comments
+    first = line.replace(/^#+\s*/, '');              // strip markdown heading marks
+    if (first) break;
+  }
+  first = first.replace(/\s+/g, ' ').trim();
+  if (first.length <= max) return first;
+  const clipped = first.slice(0, max);
+  const lastSpace = clipped.lastIndexOf(' ');
+  return `${(lastSpace > max * 0.6 ? clipped.slice(0, lastSpace) : clipped).trimEnd()}…`;
+}
+
+// Render the SessionStart block as a compact INDEX — one terse line per lesson
+// (scope, key, and a short hook), never the full bodies. This mirrors the
+// lorekit-memory intake rule ("report briefly") and the MEMORY.md index pattern:
+// surface WHAT is known so the agent can `memory.read` the one lesson that turns
+// out to matter, instead of paying for every body up front. Null when empty.
+// `instruction` — an optional extra line appended after the index, sourced from
+// `hooks.instructions.SessionStart` in the control config. Lets teams inject
+// project-specific guidance (e.g. "focus on migration safety") without touching
+// the hook internals. Visible even when there are no lessons.
+export function formatLessons(lessons, scope, { instruction = null } = {}) {
+  const noun = lessons && lessons.length === 1 ? 'memory' : 'memories';
+  if (!lessons || lessons.length === 0) {
+    // No lessons — only emit if there is a custom instruction to show.
+    if (!instruction) return null;
+    return (
+      `LoreKit: 0 ${noun} loaded · ${scope.repoScope || 'this workspace'} ` +
+      `— considerations, not rules; read any in full with memory.read.\n\n` +
+      `Project instruction: ${instruction}`
+    );
+  }
   const header =
-    `LoreKit — ${lessons.length} shared ${lessons.length === 1 ? 'memory' : 'memories'} for ${scope.repoScope || 'this workspace'}. ` +
-    `Treat as considerations, not rules; trust the current code if they conflict.`;
-  const body = lessons
-    .map((l) => {
-      const first = String(l.value || '').split('\n')[0].slice(0, 300);
-      return `- (${l.scope}) ${l.key}: ${first}`;
-    })
-    .join('\n');
-  return `${header}\n${body}`;
+    `LoreKit: ${lessons.length} ${noun} loaded · ${scope.repoScope || 'this workspace'} ` +
+    `— considerations, not rules; read any in full with memory.read.`;
+  const body = lessons.map((l) => `- (${l.scope}) ${l.key} — ${lessonHook(l.value)}`).join('\n');
+  const instructionBlock = instruction ? `\n\nProject instruction: ${instruction}` : '';
+  return `${header}\n${body}${instructionBlock}`;
 }
 
 // Distil a small set of significant, lowercased search TERMS from a tool
@@ -104,19 +141,16 @@ export function relevantLessons(lessons, terms, cap = MAX_RELEVANT) {
 }
 
 // Render the relevant-lessons block injected alongside the failure nudge, or
-// null when nothing matched. Framed as prior art, not a directive — same
-// "considerations, not rules" stance as `formatLessons`.
+// null when nothing matched. Same compact-index shape as `formatLessons`, with a
+// touch more hook per line (there are at most MAX_RELEVANT and they're directly
+// actionable). Framed as prior art, not a directive.
 export function formatRelevantLessons(lessons) {
   if (!lessons || lessons.length === 0) return null;
+  const noun = lessons.length === 1 ? 'memory' : 'memories';
   const header =
-    `LoreKit — you've hit something like this before. ${lessons.length} related ` +
-    `${lessons.length === 1 ? 'memory' : 'memories'} (considerations, not rules; trust the current code if they conflict):`;
-  const body = lessons
-    .map((l) => {
-      const first = String(l.value || '').split('\n')[0].slice(0, 300);
-      return `- (${l.scope}) ${l.key}: ${first}`;
-    })
-    .join('\n');
+    `LoreKit: ${lessons.length} related ${noun} — you've hit something like this before ` +
+    `(considerations, not rules; read in full with memory.read):`;
+  const body = lessons.map((l) => `- (${l.scope}) ${l.key} — ${lessonHook(l.value, 140)}`).join('\n');
   return `${header}\n${body}`;
 }
 
@@ -146,12 +180,12 @@ function tagsHint(writeScope, { tagsDefault = [], scopeDefaults = null } = {}) {
 export function retrospectiveNudge(scope, control) {
   const writeScope = scope.repoScope || 'global';
   const hint = tagsHint(writeScope, control);
+  const instruction = control && control.hooksInstructions && control.hooksInstructions.Stop
+    ? `\n\nProject instruction: ${control.hooksInstructions.Stop}` : '';
   return (
-    'LoreKit retrospective: if this session hit a stuck loop, a repeated ' +
-    'command failure, a surprising gotcha, a near-miss, or a wrong assumption ' +
-    'that cost time, record it now via the lorekit-memory skill ' +
-    `(memory.write to ${writeScope}, phrased as an observation).${hint} ` +
-    'If nothing was durable, do nothing.'
+    `LoreKit: hit any friction worth remembering — a stuck loop, a repeated ` +
+    `failure, a gotcha, a wrong assumption? If so, memory.write to ${writeScope} ` +
+    `as an observation; else skip.${hint}${instruction}`
   );
 }
 
@@ -161,11 +195,11 @@ export function retrospectiveNudge(scope, control) {
 export function failureNudge(toolName, scope, control) {
   const writeScope = scope.repoScope || 'global';
   const hint = tagsHint(writeScope, control);
-  const suffix = hint ? `${hint} So the next run avoids it.` : 'so the next run avoids it.';
+  const instruction = control && control.hooksInstructions && control.hooksInstructions.PostToolUseFailure
+    ? `\n\nProject instruction: ${control.hooksInstructions.PostToolUseFailure}` : '';
   return (
-    `LoreKit: the last ${toolName} call failed. If this is a recurring or ` +
-    'non-obvious failure, consider recording the fix as a memory via ' +
-    `lorekit-memory (memory.write to ${writeScope}) — ${suffix}`
+    `LoreKit: the last ${toolName} call failed. If it's recurring or non-obvious, ` +
+    `memory.write to ${writeScope} with the fix so the next run avoids it.${hint}${instruction}`
   );
 }
 

package/src/doctor.mjs

@@ -88,7 +88,24 @@ export async function doctor(args) {
     record('warn', 'scope', 'no git remote here — memories fall back to global');
   }
 
-  // 6. doctor.require — committed list of checks that MUST pass.
+  // 6. Hook instructions — show resolved per-event custom instructions when any are set.
+  {
+    const instr = control.hooksInstructions || {};
+    const EVENTS = ['SessionStart', 'PostToolUseFailure', 'Stop'];
+    const configured = EVENTS.filter((ev) => instr[ev]);
+    if (configured.length > 0) {
+      for (const ev of EVENTS) {
+        const text = instr[ev];
+        if (text) {
+          record('info', `hooks.instructions.${ev}`, c.dim(text.length > 80 ? text.slice(0, 77) + '…' : text));
+        } else {
+          record('info', `hooks.instructions.${ev}`, c.dim('(not set)'));
+        }
+      }
+    }
+  }
+
+  // 7. doctor.require — committed list of checks that MUST pass.
   //    Useful as a CI gate: any check in the list that did not pass causes a failure.
   const lorekitJson = readLorekitJson(root);
   const required = (Array.isArray(lorekitJson['doctor.require']) ? lorekitJson['doctor.require'] : [])

package/src/hook.mjs

@@ -93,9 +93,19 @@ async function run(args) {
   if (intent === 'read') {
     if (!firstTimeThisSession(parsed.sessionId, 'read')) return 0;
     const store = createStore(control);
-    if (!store) return 0; // unconfigured/unusable — stay silent
+    // When there is no usable store, we still want to emit a custom instruction
+    // if one is configured — so we don't bail out entirely on a missing store.
+    const sessionInstruction = control.hooksInstructions && control.hooksInstructions.SessionStart
+      ? control.hooksInstructions.SessionStart : null;
+    if (!store) {
+      // No store: emit a minimal header + instruction when present, then return.
+      if (sessionInstruction) {
+        emit(formatLessons(null, { repoScope: null }, { instruction: sessionInstruction }));
+      }
+      return 0;
+    }
     const { scope: readScope, lessons } = await fetchLessons(store, root);
-    emit(formatLessons(lessons, readScope));
+    emit(formatLessons(lessons, readScope, { instruction: sessionInstruction }));
     return 0;
   }
 

package/src/install.mjs

@@ -15,21 +15,55 @@ import {
   resolveConnection,
   tokenKind,
   homeDir,
+  mcpConfigPath,
+  readJsonIfExists,
 } from './config.mjs';
-import { buildRemoteUrl } from './mcp.mjs';
+import { buildRemoteUrl, splitEndpoint } from './mcp.mjs';
 import { deriveScope } from './scope.mjs';
-import { log, err, heading, status, select, c } from './util.mjs';
+import { log, heading, status, select, c } from './util.mjs';
+
+// The MCP server URL is fixed — there is only one hosted LoreKit endpoint.
+const LOREKIT_MCP_ENDPOINT = 'https://pqokxlhvnosogizsjztg.supabase.co/functions/v1/mcp';
 
 function ask(question) {
   const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
   return new Promise((resolve) => rl.question(question, (a) => { rl.close(); resolve(a.trim()); }));
 }
 
-const DEFAULT_ENDPOINT_HINT = 'https://pqokxlhvnosogizsjztg.supabase.co/functions/v1/mcp';
+// Detect whether lorekit is already installed for a given scope. Returns an
+// object describing what is present so the caller can give precise feedback.
+function detectInstalled(root, scope) {
+  // Check if at least one skill is present.
+  const skillsPresent = SKILLS.filter((skill) =>
+    fs.existsSync(path.join(skillInstallDir(root, scope, skill.name), 'SKILL.md')),
+  );
+
+  // Check if the MCP server entry exists and extract any configured token.
+  // Use a try/catch so a corrupt config file degrades to "not installed"
+  // instead of throwing — the user sees a clear error when they actually
+  // try to write via upsertMcpServer, which uses the throwing readJsonIfExists.
+  const mcpFile = mcpConfigPath(root, scope);
+  let mcpConfig = null;
+  try { mcpConfig = readJsonIfExists(mcpFile); } catch { /* corrupt — treat as absent */ }
+  const mcpServer = mcpConfig && mcpConfig.mcpServers && mcpConfig.mcpServers.lorekit;
+  const serverArgs = mcpServer && Array.isArray(mcpServer.args) ? mcpServer.args : [];
+  const serverUrl = serverArgs.find((a) => typeof a === 'string' && /^https?:\/\//.test(a));
+  const existingToken = serverUrl ? splitEndpoint(serverUrl).token : null;
+
+  return {
+    hasSkills: skillsPresent.length > 0,
+    skillCount: skillsPresent.length,
+    totalSkills: SKILLS.length,
+    hasMcp: Boolean(mcpServer),
+    existingToken,
+    isFullyInstalled: skillsPresent.length === SKILLS.length && Boolean(mcpServer),
+  };
+}
 
 export async function install(args) {
   const root = resolveProjectRoot(args.dir);
   const nonInteractive = Boolean(args.yes) || !process.stdin.isTTY;
+  const force = Boolean(args.force);
 
   heading('LoreKit install');
   log(`  project: ${c.dim(root)}`);
@@ -47,44 +81,105 @@ export async function install(args) {
       ]);
     }
   }
+
+  // 2. Already-installed detection — check both scopes so we can give accurate
+  //    context ("installed globally but not for this project", etc.).
+  const projectState = detectInstalled(root, 'project');
+  const globalState = detectInstalled(root, 'global');
+  const currentState = scope === 'global' ? globalState : projectState;
+
+  if (currentState.isFullyInstalled && !force) {
+    // Surface a clear, useful already-installed summary.
+    log('');
+    log(
+      `  ${c.green('LoreKit is already installed')} for ${
+        scope === 'global'
+          ? 'all projects (global)'
+          : 'this project'
+      }.`,
+    );
+
+    // Cross-scope awareness: tell the user what's installed where.
+    if (scope === 'project' && globalState.isFullyInstalled) {
+      log(`  ${c.dim('Also installed globally — skills and MCP server are active for every project.')}`);
+    } else if (scope === 'project' && globalState.hasMcp) {
+      log(`  ${c.dim('Partially installed globally (MCP server present, but skills may be missing).')}`);
+    } else if (scope === 'global' && projectState.isFullyInstalled) {
+      log(`  ${c.dim('Also installed for this project (.claude, .mcp.json).')}`);
+    } else if (scope === 'global' && projectState.hasMcp) {
+      log(`  ${c.dim('Partially installed for this project (MCP server present, but skills may be missing).')}`);
+    }
+
+    // Surface the configured token state so the user knows what access they have.
+    const kind = tokenKind(currentState.existingToken);
+    if (kind === 'read-write') {
+      log(`  ${c.dim('Token: read+write (lk_rw_*)')}`);
+    } else if (kind === 'read-only') {
+      log(`  ${c.dim('Token: read-only (lk_ro_*) — writes will fail until a read+write token is set')}`);
+    } else if (kind === 'write-only') {
+      log(`  ${c.dim('Token: write-only (lk_wo_*) — reads will fail until a read+write token is set')}`);
+    } else if (kind === 'unknown') {
+      log(`  ${c.dim('Token: unrecognized prefix — expected lk_rw_*, lk_ro_*, or lk_wo_*')}`);
+    } else {
+      log(`  ${c.yellow('Token: none configured — reads/writes will fail until a token is set')}`);
+    }
+
+    log('');
+    log(`  Run ${c.cyan('npx @lorekit/cli doctor')} to verify the connection.`);
+    log(`  Pass ${c.cyan('--force')} to reinstall and overwrite existing files.`);
+    return 0;
+  }
+
+  // Partial install — note what's already there vs what will be added.
+  if ((currentState.hasSkills || currentState.hasMcp) && !force) {
+    const partialNote =
+      currentState.hasSkills && !currentState.hasMcp
+        ? `Skills already present (${currentState.skillCount}/${currentState.totalSkills}) — wiring MCP server.`
+        : currentState.hasMcp && !currentState.hasSkills
+          ? 'MCP server already configured — installing skill files.'
+          : `Partially installed (${currentState.skillCount}/${currentState.totalSkills} skills, MCP ${currentState.hasMcp ? 'present' : 'missing'}) — completing setup.`;
+    log(`\n  ${c.dim(partialNote)}`);
+  }
+
   log(
     `  install: ${c.dim(
       scope === 'global' ? 'global — ~/.claude, applies to every project' : 'project — this repo only',
     )}`,
   );
 
-  // 2. Connection details.
-  let { endpoint, token } = resolveConnection(args);
-
-  if (!endpoint) {
-    if (nonInteractive) {
-      err(
-        `\n${c.red('Missing endpoint.')} Pass --endpoint ${DEFAULT_ENDPOINT_HINT} ` +
-          `or set LOREKIT_MCP_URL.`,
-      );
-      return 1;
-    }
-    endpoint = await ask(`  LoreKit MCP endpoint [${DEFAULT_ENDPOINT_HINT}]: `);
-    if (!endpoint) endpoint = DEFAULT_ENDPOINT_HINT;
+  // 3. Connection details.
+  //    The endpoint is always the fixed hosted LoreKit URL — no need to ask.
+  //    The token is reused from the existing config when already present; the
+  //    user only needs to supply it on a fresh install (or to replace it).
+  const fromArgs = resolveConnection(args);
+  const endpoint = fromArgs.endpoint || LOREKIT_MCP_ENDPOINT;
+
+  // Token resolution order: --token flag → env → existing config → prompt.
+  let token = fromArgs.token;
+  if (!token && currentState.existingToken) {
+    // Reuse the token that's already in the config — don't make the user repeat
+    // it just because they're running install again.
+    token = currentState.existingToken;
+    log(`  ${c.dim('Token: reusing existing token from config.')}`);
   }
   if (!token && !nonInteractive) {
     token = await ask('  LoreKit token (lk_rw_… to allow writes, blank to skip): ');
     token = token || null;
   }
 
-  // 3. Install the skill files — every skill the CLI ships.
+  // 4. Install the skill files — every skill the CLI ships.
   const skillResults = SKILLS.map((skill) => {
     const dest = skillInstallDir(root, scope, skill.name);
     const existed = fs.existsSync(path.join(dest, 'SKILL.md'));
-    const written = copyDir(skill.source, dest, { force: Boolean(args.force) });
+    const written = copyDir(skill.source, dest, { force });
     return { name: skill.name, dest, existed, written };
   });
 
-  // 4. Wire the MCP config for the chosen scope.
+  // 5. Wire the MCP config for the chosen scope.
   const remoteUrl = buildRemoteUrl(endpoint, token);
   const { file, existed } = upsertMcpServer(root, remoteUrl, scope);
 
-  // 4b. Wire the deterministic hooks (unless --no-hooks). This is the layer the
+  // 5b. Wire the deterministic hooks (unless --no-hooks). This is the layer the
   //     Claude plugin adds on top of the skill: lessons injected on every
   //     SessionStart, a nudge on tool failure, a retrospective nudge on Stop —
   //     firing the shared `lorekit hook` engine, which reads the same config.
@@ -100,14 +195,14 @@ export async function install(args) {
     scope === 'global' ? p.replace(homeDir(), '~') : path.relative(root, p) || p;
   const mcpLabel = scope === 'global' ? '~/.claude.json' : '.mcp.json';
 
-  // 5. Report.
+  // 6. Report.
   heading('Done');
   for (const s of skillResults) {
     const skillState = !s.existed
       ? 'installed'
       : s.written > 0
         ? `updated (${s.written} file(s) written)`
-        : 'unchanged — pass --force to overwrite';
+        : 'already up to date';
     status(s.existed && s.written === 0 ? 'info' : 'pass', `skill ${s.name}`, `${skillState} → ${display(s.dest)}`);
   }
   status('pass', mcpLabel, `${existed ? 'updated' : 'created'} lorekit server → ${display(file)}`);
@@ -116,10 +211,11 @@ export async function install(args) {
     status('info', 'hooks', 'skipped (--no-hooks) — the skill still works, but memories are model-invoked only');
   } else {
     const n = hooks.added + hooks.updated;
-    const hookState =
-      n === 0
-        ? 'unchanged — already wired'
-        : `${hooks.added ? `${hooks.added} added` : ''}${hooks.added && hooks.updated ? ', ' : ''}${hooks.updated ? `${hooks.updated} updated` : ''}`;
+    const hookParts = [
+      hooks.added ? `${hooks.added} added` : '',
+      hooks.updated ? `${hooks.updated} updated` : '',
+    ].filter(Boolean);
+    const hookState = n === 0 ? 'already wired' : hookParts.join(', ');
     status(n === 0 ? 'info' : 'pass', 'hooks', `${hookState} → ${display(hooks.file)} (${CLAUDE_HOOK_EVENTS.join(', ')})`);
   }
 
@@ -148,8 +244,8 @@ export async function install(args) {
     log(
       `  ${c.dim(
         scope === 'global'
-          ? 'Note: your token now lives in ~/.claude.json (used by every project) — keep that file private.'
-          : 'Note: your token now lives in .mcp.json — keep it out of version control.',
+          ? 'Note: your token is stored in ~/.claude.json (used by every project) — keep that file private.'
+          : 'Note: your token is stored in .mcp.json — keep it out of version control.',
       )}`,
     );
   }