klypix-mcp 1.7.0 → 1.9.0

package/bin/klypix-a2a.mjs

@@ -32,8 +32,9 @@ import { z } from 'zod';
 import {
   resolveVault, getEmbedder, cardSchema, connSchema,
   opListCanvases, opReadCanvas, opSearchCanvases, opSearchAllBrains,
-  opBrainInsights, opBrainConnect, opCreateCanvas, opAddToCanvas,
+  opBrainInsights, opBrainConnect, opCreateCanvas, opAddToCanvas, opBrainNote,
 } from '../src/klypix-core.mjs';
+import { looksLikeSkill } from '../src/klypix-format.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 // Resolve the package version across layouts: the published package (bin/ →
@@ -87,12 +88,21 @@ function agentCard(publicUrl) {
       {
         id: 'remember',
         name: 'Remember into the canvas / brain',
-        description: 'Append a decision or cards (with optional connections) to an existing .klypix, preserving every existing item and position. The durable, cross-session memory a multi-agent run keeps writing to.',
-        tags: ['memory', 'append', 'write', 'brain'],
+        description: 'Append a decision or cards (with optional connections) to an existing .klypix, preserving every existing item and position. The durable, cross-session memory a multi-agent run keeps writing to. Pass a "marker" in args for the full lifecycle: ""=decision · "?"=open question · "!"=milestone · "+"=🛠️ skill · "✓"=resolve a match · "~"=update a match.',
+        tags: ['memory', 'append', 'write', 'brain', 'lifecycle'],
         examples: ['Remember that we chose Postgres over Mongo', 'Add a card with this finding to the roadmap canvas'],
         inputModes: ['text/plain', 'application/json'],
         outputModes: [KLYPIX_MIME, 'text/plain'],
       },
+      {
+        id: 'learn_skill',
+        name: 'Learn a reusable skill (how-to / gotcha)',
+        description: 'Record a 🛠️ SKILL — a reusable how-to, gotcha, or convention ("always dedup zKeys before REORDER") that should resurface every session and never age out, distinct from a one-time decision. Routes through the capture engine with the "+" marker. A delegating agent uses this to teach the shared brain how work is done here, so every future agent inherits it. Plain "remember" auto-promotes to a skill when the text reads as a general rule.',
+        tags: ['memory', 'skill', 'how-to', 'procedure', 'brain', 'learn'],
+        examples: ['Learn this gotcha: never set backgroundThrottling false — it breaks visibility detection', 'Remember the convention: Electron main imports must stay at top'],
+        inputModes: ['text/plain', 'application/json'],
+        outputModes: [KLYPIX_MIME, 'text/plain'],
+      },
       {
         id: 'recall',
         name: 'Recall context from the canvases',
@@ -195,7 +205,21 @@ async function runSkill(skill, args, text, via) {
       return await opCreateCanvas({ vault: VAULT, title: args.title ?? 'Untitled board', cards: parsed.data, connections: conns.data, filename: args.filename });
     }
     case 'remember':
-    case 'add_to_canvas': {
+    case 'add_to_canvas':
+    case 'learn_skill': {
+      // Route through the brain's CAPTURE ENGINE (full lifecycle + markers, incl.
+      // 🛠️ skills) when: the caller passed a marker, asked for learn_skill, or the
+      // text reads as a reusable rule (auto-skill from the flow — the same
+      // classifier the Claude-Code hook uses). Otherwise: flat multi-card append.
+      let marker = String(args.marker || '').trim();
+      if (skill === 'learn_skill') marker = '+';
+      const single = (!args.cards && text.trim()) ? stripVerb(text) : null;
+      if (!marker && single && looksLikeSkill(single)) marker = '+';   // NL "remember this gotcha: always…" → skill
+      if (marker) {
+        const noteText = single ?? (Array.isArray(args.cards) && args.cards[0]?.text) ?? '';
+        if (!String(noteText).trim()) return needInput('Nothing to capture — send text or a card to remember.');
+        return await opBrainNote({ vault: VAULT, canvas: args.canvas ?? 'brain', text: noteText, area: args.area, marker, closes: args.closes, via });
+      }
       // NL convenience: a bare "remember: X" becomes a single card on the brain.
       const cards = args.cards ?? (text.trim() ? [{ text: stripVerb(text) }] : null);
       const parsed = cardsArg.safeParse(cards);
@@ -250,6 +274,7 @@ function routeIntent(text, dataArgs) {
   const t = String(text || '').toLowerCase();
   const named = extractCanvas(text);
   if (/\b(make|build|create|draw|turn .* into).{0,30}(board|canvas|mind ?map|map|diagram)\b/.test(t)) return { skill: 'make_board', args: {} };
+  if (/\b(learn (this|a) skill|teach the brain|remember the (convention|rule|gotcha)|this is a (gotcha|pitfall|footgun))\b/.test(t) || /\bskill:/i.test(text)) return { skill: 'learn_skill', args: {} };
   if (/\b(remember|note this|capture this|log that|record that|add a card)\b/.test(t)) return { skill: 'remember', args: {} };
   // An explicit read verb OR a specific named canvas → read it. Checked BEFORE
   // list so "what's on the roadmap canvas" reads that canvas, not the vault index.

package/bin/klypix-mcp.mjs

@@ -17,6 +17,7 @@
 
 import fs from 'fs';
 import path from 'path';
+import { createRequire } from 'module';
 import { z } from 'zod';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
@@ -26,6 +27,10 @@ import {
   opBrainInsights, opBrainConnect, opBrainReconcile, opBrainGarden, opCreateCanvas, opAddToCanvas, opBrainNote,
 } from '../src/klypix-core.mjs';
 
+// Real package version for the MCP handshake (was hardcoded '1.0.0', which
+// misled every client/version diagnosis — it could never reflect the true release).
+const PKG_VERSION = (() => { try { return createRequire(import.meta.url)('../package.json').version; } catch { return '0.0.0'; } })();
+
 // IMPORTANT: stdout is the JSON-RPC channel. Never console.log — only stderr.
 const log = (...a) => console.error('[klypix-mcp]', ...a);
 
@@ -41,6 +46,7 @@ if (process.argv[2] === 'init') {
       { title: 'Goal', cards: [{ text: '❓ What is this project for, and for whom?\nAgent: survey the repo on your first session and replace this with the real goal.' }] },
       { title: 'Architecture', cards: [{ text: '❓ Key components and how they fit.\nAgent: record the actual shape from the repo — only what a new session must know.' }] },
       { title: 'Decisions', cards: [{ text: 'Decisions land here automatically: agents emit `🧠 BRAIN [Area]: …` markers; a new decision that replaces an old one archives it (superseded). Resolve finished items with `✓`, correct in place with `~`. Drag any card into 📌 Focus to make it lead every session brief.' }] },
+      { title: '🛠️ Skills', cards: [{ text: '🛠️ Reusable how-tos, gotchas & conventions land here — emit `🧠 BRAIN [Area] +: <skill>` (or just state a rule like "always X / never Y" and it auto-promotes). Skills resurface every session and never age out, unlike one-time decisions. This is "how we work here", inherited by every future agent.' }] },
       { title: 'Pending / next', cards: [{ text: 'What is in flight and what comes next. Close finished items with the ✓ marker.' }] },
       { title: 'Open questions', cards: [{ text: 'Unresolved questions (the ❓ marker) live here — the session brief surfaces them first.' }] },
       { title: '📌 Focus', cards: [{ text: 'Drag any card into this area to make it lead every session brief — steer your agent by moving cards.' }] },
@@ -63,7 +69,7 @@ const toContent = (r) => {
   return r.isError ? { content, isError: true } : { content };
 };
 
-const server = new McpServer({ name: 'klypix-canvas', version: '1.0.0' });
+const server = new McpServer({ name: 'klypix-canvas', version: PKG_VERSION });
 
 server.registerTool('list_canvases', {
   title: 'List KLYPIX canvases',
@@ -161,11 +167,11 @@ server.registerTool('add_to_canvas', {
 });
 
 server.registerTool('brain_note', {
-  title: 'Write a deliberate note to the project brain (decision / question / milestone / resolve / update)',
-  description: 'Record something in the project brain ON DEMAND — the agent-neutral twin of the Claude-Code capture hook, so any client (Cursor / Cline / Desktop) can write the brain, not just read it. Unlike add_to_canvas (a flat append), this routes through the brain\'s capture engine, so a new decision SUPERSEDES a heavily-overlapping older one, ✓ RESOLVES/archives a matching card, closes: resolves the strategy/question a milestone fulfils, and ~ UPDATES a card in place — the full decision lifecycle, with dedup. Use it to remember a decision, ask an open question, mark a milestone, resolve a finished item, or correct a card. Defaults to the project brain ("brain").',
+  title: 'Write a deliberate note to the project brain (decision / question / milestone / skill / resolve / update)',
+  description: 'Record something in the project brain ON DEMAND — the agent-neutral twin of the Claude-Code capture hook, so any client (Cursor / Cline / Desktop) can write the brain, not just read it. Unlike add_to_canvas (a flat append), this routes through the brain\'s capture engine, so a new decision SUPERSEDES a heavily-overlapping older one, ✓ RESOLVES/archives a matching card, closes: resolves the strategy/question a milestone fulfils, and ~ UPDATES a card in place — the full decision lifecycle, with dedup. Use marker "+" to record a 🛠️ SKILL — a reusable how-to/gotcha/convention ("always dedup zKeys before REORDER") that should resurface every session and never age out, distinct from a one-time decision. Use it to remember a decision, ask an open question, mark a milestone, log a skill, resolve a finished item, or correct a card. Defaults to the project brain ("brain").',
   inputSchema: {
     text: z.string().describe('The note — one concise idea; the first line becomes the card title.'),
-    marker: z.enum(['', '?', '!', '✓', '~']).optional().describe('(none)=decision · ?=open question · !=milestone · ✓=resolve+archive the best-matching card · ~=update the matching card in place. Default: decision.'),
+    marker: z.enum(['', '?', '!', '+', '✓', '~']).optional().describe('(none)=decision · ?=open question · !=milestone · +=🛠️ skill (reusable how-to/gotcha; always resurfaces, never ages out) · ✓=resolve+archive the best-matching card · ~=update the matching card in place. Default: decision.'),
     area: z.string().optional().describe('Area/topic — routes the card into that titled container and becomes a #tag (e.g. "Auth", "Release").'),
     closes: z.string().optional().describe('Title or [[wikilink]] of a strategy/question card this note fulfils — resolves+archives it and draws a "closed by" arrow.'),
     canvas: z.string().optional().describe('Brain canvas filename/path. Defaults to the project brain ("brain").'),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "klypix-mcp",
-  "version": "1.7.0",
+  "version": "1.9.0",
   "description": "An open, local-first, agent-neutral canvas file your AI reads and writes over MCP — works with Claude, Cursor, Cline, any model.",
   "type": "module",
   "license": "MIT",

package/src/klypix-core.mjs

@@ -85,6 +85,52 @@ export function resolveCanvas(vault, ref) {
   return matches[0] || null;
 }
 
+// Resolve the DEFAULT project brain for the brain-* ops, INDEPENDENT of the
+// --vault library folder. The vault answers "where does my .klypix library live"
+// (list/read/search); the BRAIN is "THIS project's ./brain.klypix". Conflating
+// them is what made the brain ops read a stray canvas out of a global vault
+// (the "SS2" bug — a foreign brain.klypix picked by a fuzzy basename walk).
+// Precedence, project-first:
+//   1. KLYPIX_BRAIN env (explicit override)
+//   2. ./brain.klypix in the launch cwd — the project brain (coding agents launch
+//      this server with cwd = the project root)
+//   3. <vault>/brain.klypix (exact) — when the vault itself is the brain's home
+//   4. a SINGLE brain.klypix found by walking the vault; if MORE THAN ONE exists
+//      we REFUSE to guess (returns { ambiguous }) instead of silently taking one.
+export function resolveDefaultBrain(vault) {
+  const ex = (p) => { try { return p && fs.existsSync(p) ? path.resolve(p) : null; } catch { return null; } };
+  let f;
+  if ((f = ex(process.env.KLYPIX_BRAIN))) return { file: f, how: 'env (KLYPIX_BRAIN)' };
+  if ((f = ex(path.join(process.cwd(), 'brain.klypix')))) return { file: f, how: 'project cwd' };
+  if ((f = ex(path.join(vault, 'brain.klypix')))) return { file: f, how: 'vault root' };
+  const matches = walkVault(vault).filter(p => /^brain\.(klypix|any)$/i.test(path.basename(p)));
+  if (matches.length === 1) return { file: matches[0], how: 'vault search' };
+  if (matches.length > 1) return { ambiguous: matches };
+  return { file: null };
+}
+
+// Resolve the brain a brain-* op should act on. An explicit `canvas` arg → exact
+// resolve against the vault; otherwise the project-aware default above. Always
+// returns one of: { file, how } · { ambiguous: [paths] } · { file: null }.
+export function brainTarget(vault, canvas) {
+  if (canvas) { const file = resolveCanvas(vault, canvas); return file ? { file, how: `canvas:"${canvas}"` } : { file: null }; }
+  return resolveDefaultBrain(vault);
+}
+
+// One-line provenance shown atop every brain-op result so a wrong brain (the
+// "SS2" class) is OBVIOUS at a glance instead of silent. Counts non-container cards.
+export function brainStamp(file, struct, how) {
+  const title = (struct && struct.title) || path.basename(file);
+  const n = struct ? struct.cards.filter(c => c.type !== 'container').length : '?';
+  return `_brain: ${path.basename(file)} · “${title}” · ${n} cards${how ? ' · via ' + how : ''}_\n\n`;
+}
+
+// Shared error for the refuse-to-guess case — names the candidates so the caller
+// can pick one (canvas:"<path>") or fix the vault / run from the project root.
+function ambiguousBrainErr(matches) {
+  return err(`Found ${matches.length} brain.klypix files in the vault and no ./brain.klypix in the current project — refusing to guess which is "the brain". Pass canvas:"<path>", run from the project root, or set KLYPIX_BRAIN. Candidates:\n${matches.map(m => '  - ' + m).join('\n')}`);
+}
+
 function safeName(vault, title) {
   const base = String(title || 'untitled').replace(/[^\w\- ]+/g, '').trim() || 'untitled';
   let name = base, n = 1;
@@ -273,7 +319,7 @@ export async function opSearchAllBrains({ vault, query, as_of, log = () => {} })
   if (pipe) { try { [qv] = await embedTexts(pipe, [q]); } catch { /* lexical only */ } }
 
   let curKey = null;
-  try { const cb = resolveCanvas(vault, 'brain') || resolveCanvas(vault, 'brain.klypix'); if (cb) curKey = path.resolve(cb).replace(/\\/g, '/').toLowerCase(); } catch { /* no current brain */ }
+  try { const cb = resolveDefaultBrain(vault).file; if (cb) curKey = path.resolve(cb).replace(/\\/g, '/').toLowerCase(); } catch { /* no current brain */ }
   const fresh = Date.now() - 30 * 86_400_000;
   const scored = [];
   for (const b of brains) {
@@ -324,12 +370,13 @@ export async function opSearchAllBrains({ vault, query, as_of, log = () => {} })
 }
 
 export async function opBrainInsights({ vault, canvas, staleDays }) {
-  const file = resolveCanvas(vault, canvas || 'brain') || resolveCanvas(vault, 'brain.klypix');
-  if (!file) return err(`No brain canvas found in ${vault}. Pass canvas: "<name>", or run \`npx klypix-mcp init\` to create one.`);
+  const t = brainTarget(vault, canvas);
+  if (t.ambiguous) return ambiguousBrainErr(t.ambiguous);
+  if (!t.file) return err(`No brain found — looked for ./brain.klypix in the project, then ${vault}. Pass canvas: "<name>", or run \`npx klypix-mcp init\` to create one.`);
   try {
-    const { struct } = await parseKlypix(fs.readFileSync(file));
+    const { struct } = await parseKlypix(fs.readFileSync(t.file));
     const ins = brainInsights(struct, staleDays ? { staleDays } : {});
-    return { blocks: [text(insightsToMarkdown(ins, struct.title))] };
+    return { blocks: [text(brainStamp(t.file, struct, t.how) + insightsToMarkdown(ins, struct.title))] };
   } catch (e) {
     return err(`Insights failed: ${e.message}`);
   }
@@ -359,20 +406,23 @@ export function collectMigrationFiles(root) {
   return out;
 }
 export async function opBrainReconcile({ vault, canvas, root }) {
-  const file = resolveCanvas(vault, canvas || 'brain') || resolveCanvas(vault, 'brain.klypix');
-  if (!file) return err(`No brain canvas found in ${vault}. Pass canvas: "<name>".`);
+  const t = brainTarget(vault, canvas);
+  if (t.ambiguous) return ambiguousBrainErr(t.ambiguous);
+  if (!t.file) return err(`No brain found — looked for ./brain.klypix in the project, then ${vault}. Pass canvas: "<name>".`);
+  const file = t.file;
   let struct;
   try { ({ struct } = await parseKlypix(fs.readFileSync(file))); } catch (e) { return err(`Read failed: ${e.message}`); }
+  const stamp = brainStamp(file, struct, t.how);
   // Migrations live in the CODE repo (usually beside brain.klypix), not in a
   // separate canvas vault — so default the root to the brain file's folder.
   const repoRoot = root ? path.resolve(root) : path.dirname(file);
   const files = collectMigrationFiles(repoRoot);
-  if (!files.length) return { blocks: [text(`No migration files under ${repoRoot} (looked in: ${MIGRATION_DIRS.join(', ')}). Nothing to reconcile.`)] };
+  if (!files.length) return { blocks: [text(stamp + `No migration files under ${repoRoot} (looked in: ${MIGRATION_DIRS.join(', ')}). Nothing to reconcile.`)] };
   const { gaps, total } = findUnrecordedMigrations(struct, files, { max: 20 });
-  if (!gaps.length) return { blocks: [text(`✓ All ${files.length} migration(s) under ${path.basename(repoRoot)} are referenced by a brain card — no unrecorded rollouts.`)] };
+  if (!gaps.length) return { blocks: [text(stamp + `✓ All ${files.length} migration(s) under ${path.basename(repoRoot)} are referenced by a brain card — no unrecorded rollouts.`)] };
   const lines = gaps.map(g => `- \`${g.path}\` — committed, but no brain card mentions it. If applied to prod, record it:\n    \`🧠 BRAIN [DB] !: migration ${g.file.replace(/\.sql$/i, '')} applied to prod ev: ${g.path}\``);
   const more = total > gaps.length ? `\n\n…and ${total - gaps.length} more.` : '';
-  return { blocks: [text(`# ⚠️ ${total} migration(s) committed but unrecorded in the brain\n_The brain can't see prod — it flags migrations that are in git but unmentioned, so you can confirm the rollout. It never asserts a migration was applied. To dismiss one without applying, record any card that names it (e.g. "committed, not applied")._\n\n${lines.join('\n')}${more}`)] };
+  return { blocks: [text(stamp + `# ⚠️ ${total} migration(s) committed but unrecorded in the brain\n_The brain can't see prod — it flags migrations that are in git but unmentioned, so you can confirm the rollout. It never asserts a migration was applied. To dismiss one without applying, record any card that names it (e.g. "committed, not applied")._\n\n${lines.join('\n')}${more}`)] };
 }
 
 // ── Brain gardener (two-phase: select → agent synthesizes → apply) ───────────
@@ -381,17 +431,20 @@ export async function opBrainReconcile({ vault, canvas, root }) {
 // prose); apply consolidates each area into a 🌿 card and archives the originals
 // with audit arrows. Mirrors brain_connect's dry-run/apply discipline.
 export async function opBrainGarden({ vault, canvas, apply = false, syntheses }) {
-  const file = resolveCanvas(vault, canvas || 'brain') || resolveCanvas(vault, 'brain.klypix');
-  if (!file) return err(`No brain canvas found in ${vault}. Pass canvas: "<name>".`);
+  const t = brainTarget(vault, canvas);
+  if (t.ambiguous) return ambiguousBrainErr(t.ambiguous);
+  if (!t.file) return err(`No brain found — looked for ./brain.klypix in the project, then ${vault}. Pass canvas: "<name>".`);
+  const file = t.file;
   let struct;
   try { ({ struct } = await parseKlypix(fs.readFileSync(file))); } catch (e) { return err(`Read failed: ${e.message}`); }
+  const stamp = brainStamp(file, struct, t.how);
   const areas = selectGardenCandidates(struct);
-  if (!areas.length) return { blocks: [text('Nothing to garden — no area has 3+ DORMANT cards (old, beyond its newest 8, AND peripheral/≤1 link). Anything still woven into the graph is protected. The brain is tidy.')] };
+  if (!areas.length) return { blocks: [text(stamp + 'Nothing to garden — no area has 3+ DORMANT cards (old, beyond its newest 8, AND peripheral/≤1 link). Anything still woven into the graph is protected. The brain is tidy.')] };
 
   if (!apply) {
     const flat = (s) => String(s || '').replace(/\s+/g, ' ').trim();
     const body = areas.map(a => `## ${a.title}  (${a.candidates.length} dormant cards)\n` + a.candidates.map(c => `- ${flat(c.text).slice(0, 240)}`).join('\n')).join('\n\n');
-    return { blocks: [text(`# 🌿 Gardener — ${areas.length} area(s) with DORMANT cards to consolidate\nThese are old, peripheral (≤1 link) cards only — hubs and still-referenced decisions were left untouched. For EACH area below, write ONE tight synthesis (3-6 sentences, plain prose, no headers) that preserves every still-relevant fact / decision / number and drops only repetition + play-by-play. Then call \`brain_garden\` again with \`apply:true\` and \`syntheses: [{ "title": "<area title EXACTLY as shown>", "synthesis": "<text>" }, …]\`. Originals are archived with audit arrows — nothing is deleted; one undo un-gardens.\n\n${body}`)] };
+    return { blocks: [text(stamp + `# 🌿 Gardener — ${areas.length} area(s) with DORMANT cards to consolidate\nThese are old, peripheral (≤1 link) cards only — hubs and still-referenced decisions were left untouched. For EACH area below, write ONE tight synthesis (3-6 sentences, plain prose, no headers) that preserves every still-relevant fact / decision / number and drops only repetition + play-by-play. Then call \`brain_garden\` again with \`apply:true\` and \`syntheses: [{ "title": "<area title EXACTLY as shown>", "synthesis": "<text>" }, …]\`. Originals are archived with audit arrows — nothing is deleted; one undo un-gardens.\n\n${body}`)] };
   }
 
   if (!Array.isArray(syntheses) || !syntheses.length) return err('apply:true needs syntheses:[{title, synthesis}, …] — run the dry run first (apply omitted) to get the areas + their cards.');
@@ -410,8 +463,10 @@ export async function opBrainGarden({ vault, canvas, apply = false, syntheses })
 }
 
 export async function opBrainConnect({ vault, canvas, apply = false, max = 24, threshold = 0.45, log = () => {} }) {
-  const file = resolveCanvas(vault, canvas || 'brain') || resolveCanvas(vault, 'brain.klypix');
-  if (!file) return err(`No brain canvas found in ${vault}.`);
+  const tgt = brainTarget(vault, canvas);
+  if (tgt.ambiguous) return ambiguousBrainErr(tgt.ambiguous);
+  if (!tgt.file) return err(`No brain found — looked for ./brain.klypix in the project, then ${vault}.`);
+  const file = tgt.file;
   let struct;
   try { ({ struct } = await parseKlypix(fs.readFileSync(file))); } catch (e) { return err(`Read failed: ${e.message}`); }
   const flat = (s) => String(s || '').replace(/\s+/g, ' ').trim().slice(0, 70);
@@ -516,10 +571,12 @@ export async function opAddToCanvas({ vault, canvas, cards, connections, via })
 // can now record a decision, ask an open question, mark a milestone, resolve a card,
 // or correct one — with the full lifecycle, not just a flat append.
 export async function opBrainNote({ vault, canvas, text: noteText, area, marker = '', closes, via }) {
-  const file = resolveCanvas(vault, canvas || 'brain') || resolveCanvas(vault, 'brain.klypix');
-  if (!file) return err(`No brain canvas found in ${vault}. Pass canvas: "<name>".`);
+  const t = brainTarget(vault, canvas);
+  if (t.ambiguous) return ambiguousBrainErr(t.ambiguous);
+  if (!t.file) return err(`No brain found — looked for ./brain.klypix in the project, then ${vault}. Pass canvas: "<name>".`);
+  const file = t.file;
   if (!noteText || !String(noteText).trim()) return err('brain_note needs a non-empty text.');
-  if (!['', '?', '!', '✓', '~'].includes(marker)) return err(`Invalid marker "${marker}" — use: (none)=decision · ?=open question · !=milestone · ✓=resolve a matching card · ~=update a matching card.`);
+  if (!['', '?', '!', '✓', '~', '+'].includes(marker)) return err(`Invalid marker "${marker}" — use: (none)=decision · ?=open question · !=milestone · +=skill (reusable how-to) · ✓=resolve a matching card · ~=update a matching card.`);
   const input = noteToCaptureInput({ text: noteText, area, marker, closes: closes || '', createdVia: via || 'mcp' });
   try {
     const res = await captureIntoBrain(fs.readFileSync(file), input);
@@ -528,7 +585,9 @@ export async function opBrainNote({ vault, canvas, text: noteText, area, marker
     const s = res.stats || {};
     const bits = [`${s.added || 0} added`];
     for (const k of ['resolved', 'updated', 'closed', 'superseded', 'linked']) if (s[k]) bits.push(`${s[k]} ${k}`);
-    return { blocks: [text(`✓ brain_note → ${path.relative(vault, file)} (${bits.join(' · ')}). Reopen the brain in KLYPIX to see it.`)] };
+    // Name the resolved brain explicitly (basename + how) so a write never lands
+    // in a surprise file silently — the write-side twin of the read-op stamp.
+    return { blocks: [text(`✓ brain_note → ${path.basename(file)} (via ${t.how}) · ${bits.join(' · ')}. Reopen the brain in KLYPIX to see it.`)] };
   } catch (e) {
     return err(`brain_note failed (brain unchanged): ${e.message}`);
   }

package/src/klypix-format.mjs

@@ -561,7 +561,7 @@ export async function tidyBrain(buffer) {
 // decisions + milestones. Everything older stays in the file, reachable via the
 // klypix-canvas MCP search or `--full`. Keeps the session-start cost flat as
 // the brain grows (the full markdown scales with history; this doesn't).
-export function structToBrief(struct, { recentDays = 14, maxRecent = 40, maxMilestones = 8, maxConnections = 30, freshness = null } = {}) {
+export function structToBrief(struct, { recentDays = 14, maxRecent = 40, maxMilestones = 8, maxConnections = 30, maxSkills = 24, freshness = null } = {}) {
     const cutoff = Date.now() - recentDays * 86_400_000;
     const texts = struct.cards.filter(c => c.type !== 'container' && (c.text || '').trim());
     const containers = struct.cards.filter(c => c.type === 'container');
@@ -576,9 +576,14 @@ export function structToBrief(struct, { recentDays = 14, maxRecent = 40, maxMile
     // 🎯 (goal/target) reads as an OPEN item alongside ❓ — a goal card is
     // still-to-do until a ✓/closes: or a covering milestone closes it (so it
     // must NOT masquerade as a plain decision that quietly ages out of view).
-    const open = rest.filter(c => /❓|🎯/.test(c.text));
-    const miles = rest.filter(c => /🏁/.test(c.text) && !/❓|🎯/.test(c.text));
-    const plain = rest.filter(c => !open.includes(c) && !miles.includes(c));
+    // 🛠️ Skills — reusable how-tos / gotchas / procedures (the '+' marker).
+    // Standing reference, NOT a point-in-time event: always shown, never
+    // recency-decayed, and excluded from open/milestones/recent so a skill never
+    // masquerades as (or ages out like) a decision.
+    const skills = rest.filter(c => /🛠/.test(c.text));
+    const open = rest.filter(c => /❓|🎯/.test(c.text) && !/🛠/.test(c.text));
+    const miles = rest.filter(c => /🏁/.test(c.text) && !/❓|🎯|🛠/.test(c.text));
+    const plain = rest.filter(c => !open.includes(c) && !miles.includes(c) && !skills.includes(c));
     const recent = plain.filter(c => c.createdAt >= cutoff).sort((a, b) => b.createdAt - a.createdAt).slice(0, maxRecent);
     const archivedCount = texts.length - live.length;
 
@@ -611,6 +616,11 @@ export function structToBrief(struct, { recentDays = 14, maxRecent = 40, maxMile
         for (const c of focus) push(`- ${fr(c)}${flat(c.text)}`);
     }
     if (open.length) { push('', '## Open questions & goals'); for (const c of open) push(`- ${fr(c)}${flat(c.text)}`); }
+    if (skills.length) {
+        push('', '## 🛠️ Skills — how we do things here (reusable; applies every session)');
+        for (const c of skills.slice(0, maxSkills)) push(`- ${fr(c)}${flat(c.text)}`);
+        if (skills.length > maxSkills) push(`- …and ${skills.length - maxSkills} more skill(s) — search the brain.`);
+    }
     // ⚠️ Conflicts — pairs flagged conflicts_with (e.g. by parallel sessions);
     // surfaced HIGH so the next session reconciles them, not buries them.
     const conflicts = (struct.connections || []).filter(c => c.relationship === 'conflicts_with');
@@ -685,6 +695,7 @@ export function scoreCardsAgainstQuery(struct, query, { topK = 6, minScore = 2,
         }
         if (score <= 0) continue;
         if ((c.createdAt || 0) >= cutoff) score += 0.5; // gentle recency tiebreak, never dominant
+        if (/🛠/.test(c.text)) score += 1; // 🛠️ skills are standing how-tos — surface them when relevant, regardless of age
         scored.push({ card: c, score });
     }
     scored.sort((a, b) => b.score - a.score || (b.card.createdAt || 0) - (a.card.createdAt || 0));
@@ -968,6 +979,25 @@ const overlapScore = (a, b) => {
 // a real `closes: v1.2.0 staged as a github draft` — only 3 long tokens — silently
 // failed to fire.)
 const coverageOf = (target, hay) => { if (!target.size) return 0; let h = 0; for (const w of target) if (hay.has(w)) h++; return h / target.size; };
+
+// ── Auto-skill classifier (skills emerge from the flow, not just the '+' marker) ─
+// A REUSABLE skill (how-to / gotcha / convention) reads as a GENERAL RULE that
+// applies next time — distinct from a one-time decision ("we shipped X"). This is
+// the high-precision signal the capture path uses to AUTO-promote a plain decision
+// or a rationale-bearing commit into a 🛠️ skill, so the brain learns "how we work
+// here" without anyone remembering to type '+'. Deliberately conservative: STRONG
+// rule cues only, and NOT pinned to a one-time event (a version/PR#/date/ship verb
+// makes it "what happened", not "how to do it"). The explicit '+' marker always
+// wins and covers everything this misses; a false miss is cheap, a false skill is
+// noisy — so this errs toward silence.
+const STRONG_SKILL_CUES = /(\balways\b|\bnever\b|\bmust\s+(?:not|always)\b|\bdon'?t\s+(?:ever|forget)\b|\bgotcha\b|\bwatch\s+out\b|\bthe\s+trick\s+is\b|\brule\s+of\s+thumb\b|\bby\s+convention\b|\bpitfall\b|\bfootgun\b|\bremember\s+to\b|\bbe\s+sure\s+to\b)/i;
+const SKILL_EVENT_PINS = /(\bv?\d+\.\d+\.\d+\b|\bPR\s*#?\d+\b|#\d{2,}\b|\b20\d{2}-\d{2}-\d{2}\b|\bshipped\b|\breleased\b|\bpublished\b|\bmerged\b|\bdeployed\b)/i;
+export function looksLikeSkill(text) {
+    const t = String(text || '');
+    if (/🛠|❓|🎯|🏁/.test(t)) return false;      // already glyphed (skill/question/goal/milestone) — don't reclassify
+    return STRONG_SKILL_CUES.test(t) && !SKILL_EVENT_PINS.test(t);
+}
+
 export async function captureIntoBrain(buffer, { cards = [], resolutions = [], updates = [] } = {}) {
     const SUPERSEDE_AT = 0.6, RESOLVE_AT = 0.3, UPDATE_AT = 0.45, CLOSE_COVER_AT = 0.6;
     let work = buffer;
@@ -1095,12 +1125,13 @@ export async function captureIntoBrain(buffer, { cards = [], resolutions = [], u
         // to the new card is drawn in pass 2 (after the new ids exist), matched
         // back by remembering which old card each new card displaced.
         for (const card of cards) {
-            if (/❓|🎯|🏁/.test(card.text)) continue; // only plain decisions supersede (not questions/goals/milestones)
+            if (/❓|🎯|🏁|🛠/.test(card.text)) continue; // only plain decisions supersede (not questions/goals/milestones/skills)
             const nTok = tokenSet(card.text);
             const area = (card.area || '').toLowerCase();
             let best = null, bestScore = 0;
             for (const c of liveTextCards()) {
                 if (area && (c.area || '').toLowerCase() !== area) continue;
+                if (/🛠/.test(c.text)) continue; // never auto-archive a 🛠️ skill via a decision's supersede — skills are standing reference (correct with ~)
                 const s = overlapScore(nTok, tokenSet(c.text));
                 if (s > bestScore) { bestScore = s; best = c; }
             }
@@ -1253,7 +1284,7 @@ export function selectGardenCandidates(struct, { keepNewest = GARDEN_KEEP_NEWEST
         const title = (ctn.title || '').trim();
         if (!title || GARDEN_PROTECTED.test(title)) continue;
         const children = struct.cards
-            .filter(c => c.type === 'text' && c.parentId === ctn.id && (c.text || '').trim() && !/⤵|↩|✅/.test(c.text))
+            .filter(c => c.type === 'text' && c.parentId === ctn.id && (c.text || '').trim() && !/⤵|↩|✅|🛠/.test(c.text))  // 🛠️ skills are standing reference — never consolidate them away
             .sort((a, b) => (a.createdAt || 0) - (b.createdAt || 0));
         const old = children
             .slice(0, Math.max(0, children.length - keepNewest))
@@ -1409,15 +1440,17 @@ export function findStaleOpenCards(struct, { coverAt = 0.6, max = 5 } = {}) {
 // write (the brain_note MCP tool, the brain-note CLI — any agent, not just the
 // Claude-Code hook) get IDENTICAL supersede / resolve / close / dedup semantics as
 // a harvested 🧠 marker. marker ∈ '' (decision) | '?' (open question) | '!'
-// (milestone) | '✓' (resolve+archive a match) | '~' (update a match in place).
+// (milestone) | '✓' (resolve+archive a match) | '~' (update a match in place) |
+// '+' (skill — a REUSABLE how-to/gotcha/procedure, standing reference that always
+// surfaces and never ages out, distinct from a point-in-time decision).
 export function noteToCaptureInput({ text = '', area = '', marker = '', closes = '', evidence = null, createdVia = 'mcp' } = {}) {
     const body = String(text).trim();
     if (!body) return { cards: [], resolutions: [], updates: [] };
     const a = String(area || '').trim();
     if (marker === '✓') return { cards: [], resolutions: [{ area: a, text: body }], updates: [] };
     if (marker === '~') return { cards: [], resolutions: [], updates: [{ area: a, text: body, createdVia, ...(evidence ? { evidence } : {}) }] };
-    const prefix = marker === '?' ? '❓ ' : marker === '!' ? '🏁 ' : '';
-    const borderColor = marker === '?' ? 'rgba(245,166,35,0.8)' : marker === '!' ? 'rgba(59,130,246,0.8)' : 'rgba(16,185,129,0.6)';
+    const prefix = marker === '?' ? '❓ ' : marker === '!' ? '🏁 ' : marker === '+' ? '🛠️ ' : '';
+    const borderColor = marker === '?' ? 'rgba(245,166,35,0.8)' : marker === '!' ? 'rgba(59,130,246,0.8)' : marker === '+' ? 'rgba(139,92,246,0.85)' : 'rgba(16,185,129,0.6)';
     const tag = a ? `\n#${a.toLowerCase().replace(/[^a-z0-9]+/g, '-')}` : '';
     const cardText = (a ? `${a}: ${prefix}${body}` : `${prefix}${body}`) + tag;
     return { cards: [{ text: cardText, area: a, color: '#e8e8ed', borderColor, createdVia, ...(closes ? { closes } : {}), ...(evidence ? { evidence } : {}) }], resolutions: [], updates: [] };