@vpxa/aikit 0.1.208 → 0.1.210

package/scaffold/dist/definitions/skills/aikit.mjs

@@ -12,7 +12,9 @@ metadata:
 
 # @vpxa/aikit — AI Kit
 
-Local-first AI developer toolkit for search, analysis, compression, validation, memory, flows, and coordination.
+> This skill provides DEEP GUIDANCE beyond base instructions. For tool routing rules, see your base instructions.
+
+Local-first AI developer toolkit with 60+ tools for search, analysis, compression, validation, memory, flows, and coordination.
 
 ## When to Use
 
@@ -45,40 +47,6 @@ If you are unsure which tool fits, ask AI Kit for the live catalog with \`list_t
 4. Reuse previous context before searching again.
 5. Use reference docs only when the main routing logic is not enough.
 
-## Tool Selection (Decision Tree)
-
-~~~text
-Need to understand code?
-├─ Just structure?     → file_summary (exports, imports — ~50 tokens)
-├─ Specific section?   → compact({ path, query }) — 5-20x token reduction
-├─ Multiple files?     → digest (multi-source compression)
-├─ Need relationships? → graph (find_nodes → neighbors)
-└─ Need exact lines?   → read_file (ONLY for editing)
-
-Need to find something?
-├─ Code/symbols?       → search (hybrid — default)
-├─ Symbol definition?  → symbol (definition + refs + call context)
-├─ Usage examples?     → find({ mode: 'examples', query })
-├─ Cross-file flow?    → trace (forward/backward/both)
-└─ Change impact?      → blast_radius
-
-Need to validate?
-├─ Type errors?        → check (typecheck + lint combined)
-├─ Tests pass?         → test_run (structured output)
-└─ Full audit?         → audit (structure + deps + health)
-
-Need to remember?
-├─ Store decision?     → knowledge({ action: 'remember' })
-├─ Find past decision? → search({ query, origin: 'curated' })
-├─ Session state?      → stash (ephemeral) or checkpoint (persistent)
-└─ Cross-session?      → knowledge (curated memory)
-
-Need tool discovery?
-├─ Full live catalog?  → list_tools
-├─ Know capability, not name? → search_tools
-└─ Need details first? → describe_tool or guide
-~~~
-
 **When tools return empty:**
 - \`search\` → 0 results? Broaden query terms OR fall back to \`find({ pattern })\` with regex
 - \`symbol\` → not found? Check spelling, try \`search\` with partial name
@@ -118,7 +86,6 @@ Without session discipline, agents repeat work, miss context, and make decisions
 - NEVER \`search\` then immediately \`read_file\` the result — search already returns content snippets
 - NEVER call \`compact\` on a file you just \`file_summary\`'d — pick one retrieval depth
 - NEVER stash >10 items without \`checkpoint\` — stash has no TTL, checkpoints do
-- NEVER \`read_file\` a file >50 lines to "understand" it — \`file_summary\` → \`compact\` decision tree
 - NEVER run \`reindex\` mid-implementation — wait until all edits are done
 - NEVER skip \`search\` before implementing — past decisions may exist that constrain your approach
 - NEVER echo full subagent output to user — compress with \`stash\` + brief summary
@@ -193,6 +160,38 @@ Capture reusable engineering insights via \`knowledge({ action: "lesson", subAct
 
 See the \`lesson-learned\` skill for the full extraction workflow.
 
+### Lesson Lifecycle Management
+
+| SubAction | Purpose | Default |
+|-----------|---------|---------|
+| \`prune\` | Archive stale lessons (confidence < 15, idle > 30d) | dryRun: true |
+| \`group\` | Cluster similar lessons, add group tags | dryRun: true |
+| \`promote\` | Cross-workspace promotion to global store | dryRun: true |
+| \`demote\` | Remove from global store | -- |
+| \`auto-observe\` | Pattern detection from tool outputs | automatic |
+
+**Maintenance workflow** (periodic):
+\`\`\`
+knowledge({ action: "lesson", subAction: "prune" })   // review stale
+knowledge({ action: "lesson", subAction: "group" })   // organize
+knowledge({ action: "lesson", subAction: "promote" }) // share universal
+\`\`\`
+
+### Session Prelude
+Request context-primed session start:
+\`\`\`
+status({ includePrelude: true })
+\`\`\`
+Returns: top 3 lessons (by decayed confidence), top 2 conventions (by recency), last session checkpoint.
+Use at session start for immediate situational awareness.
+
+### Confidence Decay
+Lesson confidence decays over time via Ebbinghaus curve:
+- Accessing lessons (via withdraw, list-lessons) implicitly reinforces them
+- Unaccessed lessons gradually lose confidence
+- Below threshold 15 + idle > 30 days -> eligible for pruning
+- \`knowledge({ action: "flagged" })\` surfaces decayed entries for review
+
 ### Supersession (automatic dedup)
 When you \`remember()\`, similar entries are detected automatically:
 - Jaccard > 0.7 → flagged for review
@@ -216,18 +215,6 @@ Load these only when the main skill is not enough:
 - \`references/forge-protocol.md\` — tiering, evidence, gates
 - \`references/search-patterns.md\` — search, trace, graph, compression patterns
 
-## NEVER
-
-- NEVER use \`read_file\` to "understand" a file. \`file_summary\` gives structure in ~50 tokens instead of hundreds.
-- NEVER use \`grep_search\` or \`semantic_search\` when \`search\` is available. \`search\` combines both strategies and ranks them.
-- NEVER run tsc, lint, or tests through the terminal when \`check()\` and \`test_run()\` exist. Structured output beats terminal noise.
-- NEVER skip \`status()\` at session start. If index state is unknown, every later choice is lower quality.
-- NEVER call \`knowledge({ action: 'remember' })\` for trivial facts. Memory is for decisions, conventions, lessons, and durable findings.
-- NEVER search the same thing twice without checking \`stash\` or prior results.
-- NEVER use a long flat tool catalog as your primary routing aid. Use runtime discovery when you need exact tool metadata.
-- NEVER jump to \`analyze\` for simple local questions. Start with cheaper retrieval and escalate only if needed.
-- NEVER leave structural changes unindexed. Run \`reindex\` when symbols, files, or imports change.
-
 ## Complementary Skills
 
 - Load \`typescript\` before TypeScript-heavy implementation work.
@@ -235,13 +222,6 @@ Load these only when the main skill is not enough:
 - Load \`session-handoff\` when context is filling up or a pause is imminent.
 - Load \`repo-access\` when repo auth fails.
 
-## Practical Defaults
-
-- Default search mode: \`search\` with hybrid ranking.
-- Default read path: \`file_summary\` then \`compact\`.
-- Default validation pair: \`check\` then \`test_run\`.
-- Default persistence: \`knowledge remember\` for durable findings, \`stash\` for everything temporary.
-
 ## Self-Dogfooding
 
 When developing AI Kit itself, rebuild generated output before trusting runtime behavior, and reindex after structural changes so the toolkit can see its own new shape.

package/scaffold/dist/definitions/skills/lesson-learned.mjs

@@ -272,6 +272,8 @@ knowledge({ action: "lesson", subAction: "create", context: "<what happened —
 - 80-90: Pattern confirmed across multiple PRs/sessions
 - 90+: Fundamental principle validated repeatedly -- treat as convention
 
+Confidence decays over time based on access recency (Ebbinghaus curve). Accessing a lesson via \`withdraw\` or \`list-lessons\` implicitly reinforces it.
+
 If you encounter a lesson that CONFIRMS a previously stored one:
 ~~~
 knowledge({ action: "lesson", subAction: "confirm", id: "<lesson-path>" })
@@ -285,6 +287,50 @@ knowledge({ action: "lesson", subAction: "contradict", id: "<lesson-path>", reas
 Before creating a new lesson, check existing ones: \`knowledge({ action: "lesson", subAction: "list-lessons" })\`
 Only create if no existing lesson already covers this insight.
 
+### Passive Learning (auto-observe)
+The server automatically observes tool output patterns and can detect:
+- Repeated error -> fix cycles (suggests lessons about common pitfalls)
+- Consistent code patterns across files (suggests convention lessons)
+- Recurring search queries (suggests documentation gaps)
+
+Trigger manually: \`knowledge({ action: "lesson", subAction: "auto-observe", buffer: "<tool output>" })\`
+Usually runs automatically via exec-hooks -- agents don't need to call this directly.
+
+## Phase 6: Lifecycle Maintenance (Periodic)
+
+Run these periodically (every few sessions) to maintain knowledge quality:
+
+### Prune Stale Lessons
+\`\`\`
+knowledge({ action: "lesson", subAction: "prune" })                // dry-run: shows candidates
+knowledge({ action: "lesson", subAction: "prune", dryRun: false }) // execute: archives stale lessons
+\`\`\`
+Archives lessons where: decayed confidence < 15 AND last accessed > 30 days ago.
+Safety: minimum 3 lessons always retained, dry-run by default.
+
+### Group Similar Lessons
+\`\`\`
+knowledge({ action: "lesson", subAction: "group" })                // dry-run: shows proposed groups
+knowledge({ action: "lesson", subAction: "group", dryRun: false }) // execute: adds group tags
+\`\`\`
+Clusters lessons with similar titles (Jaccard > 0.7), adds \`group:<label>\` tags.
+Non-destructive -- only adds tags, never modifies content.
+
+### Cross-Project Promotion
+\`\`\`
+knowledge({ action: "lesson", subAction: "promote" })                  // dry-run: shows candidates
+knowledge({ action: "lesson", subAction: "promote", dryRun: false })   // execute: copies to global
+knowledge({ action: "lesson", subAction: "demote", path: "<path>" }) // remove from global
+\`\`\`
+Requires user-level install. Scans all workspaces for similar lessons (Jaccard > 0.7 on insight text).
+Promotes when: found in 2+ workspaces AND average confidence >= 80.
+Global lessons available to ALL workspaces via \`workspaces: ["*"]\`.
+
+### Recommended Maintenance Cadence
+- **Every 5 sessions**: \`prune\` (dry-run review)
+- **Every 10 sessions**: \`group\` to organize
+- **Monthly**: \`promote\` to share universal lessons across projects
+
 ## What NOT to Do
 
 | Avoid | Why | Instead |

package/scaffold/general/hooks/scripts/_runtime.mjs

@@ -0,0 +1,161 @@
+import path from 'node:path';
+import process from 'node:process';
+
+const FILE_KEYS = new Set([
+  'dirPath',
+  'file',
+  'filePath',
+  'filePaths',
+  'files',
+  'from',
+  'path',
+  'paths',
+  'targetPath',
+  'to',
+  'uri',
+  'uris',
+]);
+
+const escapeRegex = (value) => value.replace(/[.+?^${}()|[\]\\]/g, '\\$&');
+
+const normalizePath = (value) => {
+  if (typeof value !== 'string') return '';
+  let next = value.trim();
+  if (next.startsWith('file://')) {
+    try {
+      next = decodeURIComponent(new URL(next).pathname);
+    } catch {
+      return '';
+    }
+  }
+  if (/^\/[a-z]:/i.test(next)) next = next.slice(1);
+  return path.normalize(next).replace(/\\/g, '/').toLowerCase();
+};
+
+/**
+ * Creates a hook entrypoint that normalizes stdin and writes a platform-neutral response.
+ * @param {(context: ReturnType<typeof normalizeContext>) => Promise<object> | object} handler
+ */
+export async function createHook(handler) {
+  try {
+    const raw = await readStdin();
+    const result = (await handler(normalizeContext(raw))) ?? { decision: 'allow' };
+    respond(result);
+  } catch (error) {
+    respond({ decision: 'deny', reason: error instanceof Error ? error.message : String(error) });
+  }
+}
+
+/**
+ * Reads and parses the full stdin payload as JSON.
+ * @returns {Promise<object>}
+ */
+export function readStdin() {
+  return new Promise((resolve, reject) => {
+    let input = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => {
+      input += chunk;
+    });
+    process.stdin.on('end', () => {
+      if (!input.trim()) return resolve({});
+      try {
+        resolve(JSON.parse(input));
+      } catch (error) {
+        reject(error);
+      }
+    });
+    process.stdin.on('error', reject);
+  });
+}
+
+/**
+ * Normalizes platform-specific hook payloads into one shared shape.
+ * @param {object} raw
+ */
+export function normalizeContext(raw = {}) {
+  const platform = raw.tool_name
+    ? 'claude'
+    : raw.toolName
+      ? 'copilot'
+      : raw.tool
+        ? 'copilot-cli'
+        : 'copilot';
+  const toolInput =
+    raw.toolInput ?? raw.tool_input ?? raw.input ?? raw.arguments ?? raw.params ?? {};
+  return {
+    raw,
+    platform,
+    event: raw.event ?? raw.hookEvent ?? raw.hook_event ?? 'SessionStart',
+    toolName: raw.toolName ?? raw.tool_name ?? raw.tool ?? '',
+    toolInput,
+    filePaths: extractFilePaths(toolInput),
+    env: raw.env ?? raw.environment ?? raw.processEnv ?? {},
+    cwd: raw.cwd ?? raw.workingDirectory ?? raw.working_directory ?? process.cwd(),
+    matchesPattern,
+    normalizePath,
+  };
+}
+
+/**
+ * Writes a normalized hook response to stdout and sets the exit code.
+ * @param {{ decision?: 'allow' | 'deny', reason?: string, additionalContext?: string, continue?: boolean }} result
+ */
+export function respond(result = { decision: 'allow' }) {
+  const decision = result.decision ?? 'allow';
+  const payload =
+    decision === 'deny'
+      ? { decision: 'deny', reason: result.reason ?? 'Hook denied request.' }
+      : {
+          ...(result.additionalContext ? { additionalContext: result.additionalContext } : {}),
+          ...(result.continue === false ? { continue: false } : {}),
+        };
+  if (Object.keys(payload).length > 0) process.stdout.write(`${JSON.stringify(payload)}\n`);
+  process.exitCode = decision === 'deny' ? 2 : 0;
+}
+
+/**
+ * Extracts file paths from common tool input field names.
+ * @param {unknown} toolInput
+ * @returns {string[]}
+ */
+export function extractFilePaths(toolInput) {
+  const found = new Set();
+  const visit = (value, key = '') => {
+    if (Array.isArray(value)) {
+      value.forEach((item) => {
+        visit(item, key);
+      });
+      return;
+    }
+    if (value && typeof value === 'object') {
+      Object.entries(value).forEach(([nextKey, nextValue]) => {
+        visit(nextValue, nextKey);
+      });
+      return;
+    }
+    if (typeof value === 'string' && FILE_KEYS.has(key)) found.add(normalizePath(value));
+  };
+  visit(toolInput);
+  return [...found].filter(Boolean);
+}
+
+/**
+ * Matches a normalized path against simple wildcard and directory-prefix patterns.
+ * @param {string} filePath
+ * @param {string[]} patterns
+ */
+export function matchesPattern(filePath, patterns) {
+  const target = normalizePath(filePath);
+  return patterns.some((pattern) => {
+    const normalizedPattern = normalizePath(pattern);
+    if (!normalizedPattern) return false;
+    if (normalizedPattern.endsWith('/')) {
+      const prefix = normalizedPattern.slice(0, -1);
+      return target === prefix || target.includes(`/${prefix}/`) || target.startsWith(`${prefix}/`);
+    }
+    return new RegExp(`(^|/)${normalizedPattern.split('*').map(escapeRegex).join('.*')}$`).test(
+      target,
+    );
+  });
+}

package/scaffold/general/hooks/scripts/post-edit-check.mjs

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import process from 'node:process';
+import { createHook } from './_runtime.mjs';
+
+const EDIT_TOOLS = new Set(['Edit', 'Write', 'create_file', 'editFiles', 'replace_string_in_file']);
+const counterPath = path.join(os.tmpdir(), `aikit-edit-count-${process.ppid}.json`);
+const readCount = () => {
+  try {
+    return JSON.parse(fs.readFileSync(counterPath, 'utf8')).count || 0;
+  } catch {
+    return 0;
+  }
+};
+const writeCount = (count) => {
+  try {
+    fs.writeFileSync(counterPath, JSON.stringify({ count }), 'utf8');
+  } catch {}
+};
+
+/** Tracks edit counts and nudges validation after repeated file changes. */
+export const postEditCheck = async (context) => {
+  if (context.event !== 'PostToolUse' || !EDIT_TOOLS.has(context.toolName))
+    return { decision: 'allow' };
+  const count = readCount() + 1;
+  writeCount(count);
+  if (count < 5 || count % 5 !== 0) return { decision: 'allow' };
+  const prefix = count >= 10 ? 'Strongly consider' : 'Consider';
+  return {
+    additionalContext: `📋 You've made ${count} file edits this session. ${prefix} running check({}) and test_run({}) to validate changes before continuing.`,
+  };
+};
+
+createHook(postEditCheck);

package/scaffold/general/hooks/scripts/pre-compact-save.mjs

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+import { createHook } from './_runtime.mjs';
+
+const REMINDER = `⚠️ Context compaction imminent. Before proceeding:
+1. If you have uncommitted decisions, call: knowledge({ action: "remember", title: "Pre-compact save", content: "<key decisions and state>", category: "session" })
+2. If a flow is active, call: stash({ action: "set", key: "pre-compact-state", value: "<current progress>" })
+3. After compaction, call: search({ query: "SESSION CHECKPOINT", origin: "curated" }) to recover context.`;
+
+/** Injects a save-state reminder immediately before context compaction. */
+export const preCompactSave = async (context) =>
+  context.event === 'PreCompact' ? { additionalContext: REMINDER } : { decision: 'allow' };
+
+createHook(preCompactSave);

package/scaffold/general/hooks/scripts/privacy-guard.mjs

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+import { createHook } from './_runtime.mjs';
+
+const BLOCKED = [
+  '**/.env',
+  '**/.env.*',
+  '**/*.pem',
+  '**/*.key',
+  '**/*.p12',
+  '**/*.pfx',
+  '**/id_rsa*',
+  '**/id_ed25519*',
+  '**/.ssh/*',
+  '**/*credentials*',
+  '**/*.secret',
+  '**/.netrc',
+  '**/.pgpass',
+  '**/secret.*',
+  '**/secrets.*',
+];
+
+const READ_TOOLS = new Set(['Read', 'read_file', 'readFile']);
+
+/** Blocks reads of secret-bearing files and key material. */
+export const privacyGuard = async (context) => {
+  if (context.event !== 'PreToolUse' || !READ_TOOLS.has(context.toolName))
+    return { decision: 'allow' };
+  const blockedPath = context.filePaths.find((filePath) =>
+    context.matchesPattern(filePath, BLOCKED),
+  );
+  return blockedPath
+    ? {
+        decision: 'deny',
+        reason: `Blocked: reading sensitive file ${blockedPath}. Use environment variables or secrets manager instead.`,
+      }
+    : { decision: 'allow' };
+};
+
+createHook(privacyGuard);

package/scaffold/general/hooks/scripts/scout-guard.mjs

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+import { createHook } from './_runtime.mjs';
+
+const BLOCKED_DIRS = [
+  'node_modules/',
+  '.git/objects/',
+  'dist/',
+  'build/',
+  'vendor/',
+  '.next/',
+  'coverage/',
+  '__pycache__/',
+  '.tox/',
+  'target/debug/',
+  'target/release/',
+  '.gradle/',
+  'Pods/',
+];
+
+const normalize = (value) =>
+  String(value ?? '')
+    .replace(/\\/g, '/')
+    .toLowerCase();
+
+/** Blocks reads and searches inside generated or dependency-heavy directories. */
+export const scoutGuard = async (context) => {
+  if (context.event !== 'PreToolUse') return { decision: 'allow' };
+  const blockedDir = context.filePaths.reduce((match, filePath) => {
+    if (match) return match;
+    const normalizedPath = normalize(filePath);
+    return (
+      BLOCKED_DIRS.find(
+        (dir) => normalizedPath.startsWith(dir) || normalizedPath.includes(`/${dir}`),
+      ) ?? ''
+    );
+  }, '');
+  return blockedDir
+    ? {
+        decision: 'deny',
+        reason: `Blocked: accessing ${blockedDir} wastes context. Use search tools or package documentation instead.`,
+      }
+    : { decision: 'allow' };
+};
+
+createHook(scoutGuard);

package/scaffold/general/hooks/scripts/session-init.mjs

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import { createHook } from './_runtime.mjs';
+
+const exists = (cwd, name) => {
+  try {
+    return fs.existsSync(path.join(cwd, name));
+  } catch {
+    return false;
+  }
+};
+const list = (cwd) => {
+  try {
+    return fs.readdirSync(cwd);
+  } catch {
+    return [];
+  }
+};
+const readJson = (cwd, name) => {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(cwd, name), 'utf8'));
+  } catch {
+    return null;
+  }
+};
+const detectPackageManager = (cwd, pkg) =>
+  pkg?.packageManager?.split('@')[0] ||
+  (exists(cwd, 'pnpm-lock.yaml') && 'pnpm') ||
+  (exists(cwd, 'yarn.lock') && 'yarn') ||
+  ((exists(cwd, 'bun.lockb') || exists(cwd, 'bun.lock')) && 'bun') ||
+  (exists(cwd, 'package-lock.json') && 'npm') ||
+  'unknown';
+
+/** Detects workspace metadata and injects stack context at session start. */
+export const sessionInit = async (context) => {
+  if (context.event !== 'SessionStart') return { decision: 'allow' };
+  const pkg = readJson(context.cwd, 'package.json');
+  const deps = { ...pkg?.dependencies, ...pkg?.devDependencies };
+  const entries = list(context.cwd);
+  const framework = deps.react
+    ? 'React'
+    : deps.vue
+      ? 'Vue'
+      : deps.angular
+        ? 'Angular'
+        : deps.next
+          ? 'Next.js'
+          : deps.express
+            ? 'Express'
+            : deps.fastify
+              ? 'Fastify'
+              : '';
+  const stack = pkg
+    ? `Node.js${framework ? `, ${framework}` : ''}`
+    : exists(context.cwd, 'go.mod')
+      ? 'Go'
+      : exists(context.cwd, 'Cargo.toml')
+        ? 'Rust'
+        : exists(context.cwd, 'requirements.txt') || exists(context.cwd, 'pyproject.toml')
+          ? 'Python'
+          : entries.some((name) => /\.(sln|csproj)$/i.test(name))
+            ? '.NET'
+            : exists(context.cwd, 'pom.xml') || exists(context.cwd, 'build.gradle')
+              ? 'Java/Kotlin'
+              : 'Unknown';
+  const monorepo = exists(context.cwd, 'pnpm-workspace.yaml')
+    ? 'yes (pnpm-workspace)'
+    : exists(context.cwd, 'lerna.json')
+      ? 'yes (lerna)'
+      : exists(context.cwd, 'packages')
+        ? 'yes (packages/)'
+        : 'no';
+  const metadata = [
+    `Workspace: ${path.basename(context.cwd)}`,
+    `Stack: ${stack}`,
+    `Monorepo: ${monorepo}`,
+    `Package manager: ${detectPackageManager(context.cwd, pkg)}`,
+    ...(pkg ? [`Node: ${process.version}`] : []),
+  ].join('\n');
+  return { additionalContext: metadata };
+};
+
+createHook(sessionInit);

package/scaffold/general/hooks/scripts/session-learn.mjs

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+/**
+ * session-learn — Stop event hook for autonomous learning.
+ *
+ * Fires at session end. Nudges agent to process buffered observations
+ * before context is lost. Cleans up buffer if too small for analysis.
+ *
+ * @tier efficiency
+ * @event Stop
+ * @scope user
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import process from 'node:process';
+import { createHook } from './_runtime.mjs';
+
+const bufferPath = path.join(os.tmpdir(), `aikit-obs-${process.ppid}.jsonl`);
+const MIN_OBSERVATIONS = 10;
+
+const getLineCount = (filePath) => {
+  try {
+    return fs.readFileSync(filePath, 'utf8').split('\n').filter(Boolean).length;
+  } catch {
+    return 0;
+  }
+};
+
+const cleanup = () => {
+  try {
+    fs.unlinkSync(bufferPath);
+  } catch {}
+};
+
+/** Nudges end-of-session lesson extraction and cleans up small buffers. */
+export const sessionLearn = async (context) => {
+  if (context.event !== 'Stop') return { decision: 'allow' };
+
+  const count = getLineCount(bufferPath);
+  if (count < MIN_OBSERVATIONS) {
+    cleanup();
+    return { decision: 'allow' };
+  }
+
+  return {
+    additionalContext: [
+      `[Observer] Session ending with ${count} observations buffered.`,
+      'Run knowledge({ action: "lesson", subAction: "auto-observe" }) to extract learning patterns.',
+    ].join(' '),
+  };
+};
+
+createHook(sessionLearn);