kracked-core 1.0.0 → 1.1.0

package/README.md

@@ -53,12 +53,15 @@ The wizard asks a few questions — name your agent, is this a new or existing p
 
 ## Use
 
-Three commands. That's the whole thing.
+Five commands. Three of them are the whole daily loop.
 
 ```
 /kracked-boot    Start of session — agent loads its memory and tells you where you left off
 /kracked-sdd     Build something — idea → spec → docs → build → review
 /kracked-wrap    End of session — agent writes down what it learned
+
+/kracked-identity  Change your agent's name, tone, or how you like to work
+/kracked-explain   "What is all this?" — walks you through what got installed
 ```
 
 > **`/kracked-wrap` is not optional.** Boot without wrap is a memory system that just forgets more slowly. The wrap is where memory actually gets written.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kracked-core",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Zero-dependency memory & workflow installer for AI coding agents — global identity, project memory, and skills that survive session restarts.",
   "type": "module",
   "bin": {

package/src/detect.mjs

@@ -15,6 +15,39 @@ export function globalMemoryDir() {
   return path.join(os.homedir(), '.kracked');
 }
 
+/**
+ * Find agent setups already governing this directory, so we never silently
+ * overwrite someone's existing system. A CLAUDE.md/AGENTS.md that kracked-core
+ * didn't write is another system's loader — installing over it would replace
+ * that agent's identity, which is exactly the failure this check prevents.
+ *
+ * Returns [{ file, path, scope, ours }] — `ours` marks files kracked-core
+ * itself wrote (safe to refresh), everything else is someone else's.
+ */
+export function detectExistingAgentSetup(projectDir) {
+  const found = [];
+
+  const inspect = (filePath, label, scope) => {
+    if (!fs.existsSync(filePath)) return;
+    let body = '';
+    try {
+      body = fs.readFileSync(filePath, 'utf8');
+    } catch {
+      return; // unreadable is not our problem to solve here
+    }
+    // Our own loaders always reference kracked-core by name.
+    const ours = /kracked-core|kracked\.md|\.kracked\//.test(body);
+    found.push({ file: label, path: filePath, scope, ours });
+  };
+
+  inspect(path.join(projectDir, 'CLAUDE.md'), 'CLAUDE.md', 'project');
+  inspect(path.join(projectDir, 'AGENTS.md'), 'AGENTS.md', 'project');
+  inspect(path.join(projectDir, '.agents', 'rules', 'kracked.md'), '.agents/rules/kracked.md', 'project');
+  inspect(path.join(os.homedir(), '.claude', 'CLAUDE.md'), '~/.claude/CLAUDE.md', 'global');
+
+  return found;
+}
+
 /**
  * Is the target dir an existing codebase, empty, or new (doesn't exist yet)?
  * Returns one of: "new" (doesn't exist), "empty" (exists, no entries),

package/src/prompt.mjs

@@ -0,0 +1,235 @@
+// Keyboard-driven prompts: arrow-key single select and spacebar checkboxes.
+// Zero dependencies — raw TTY keypress handling, so the installer never fails
+// in a classroom because of a missing package.
+
+import { stdin, stdout } from 'node:process';
+
+const ESC = '';
+const KEY = {
+  up: `${ESC}[A`,
+  down: `${ESC}[B`,
+  ctrlC: '',
+  ctrlD: '',
+  enter: '\r',
+  newline: '\n',
+  space: ' ',
+};
+
+const c = {
+  dim: (s) => `${s}`,
+  cyan: (s) => `${s}`,
+  green: (s) => `${s}`,
+  bold: (s) => `${s}`,
+};
+
+/** Hide/show the cursor so the redrawing menu doesn't flicker a caret around. */
+function setCursor(visible) {
+  stdout.write(visible ? `${ESC}[?25h` : `${ESC}[?25l`);
+}
+
+/** Move up n lines and clear from there down — used to redraw the menu in place. */
+function clearLines(n) {
+  if (n > 0) stdout.write(`${ESC}[${n}A`);
+  stdout.write(`${ESC}[0J`);
+}
+
+/**
+ * Read single keypresses until `onKey` signals completion.
+ * onKey(key) returns { done: true, value } to finish, or falsy to keep listening.
+ */
+function readKeys(onKey) {
+  return new Promise((resolve, reject) => {
+    const wasRaw = stdin.isRaw;
+    stdin.setRawMode(true);
+    stdin.resume();
+    stdin.setEncoding('utf8');
+
+    const cleanup = () => {
+      stdin.setRawMode(wasRaw ?? false);
+      stdin.pause();
+      stdin.removeListener('data', handler);
+      setCursor(true);
+    };
+
+    function handler(key) {
+      // Ctrl+C / Ctrl+D must always escape, whatever the prompt is doing.
+      if (key === KEY.ctrlC || key === KEY.ctrlD) {
+        cleanup();
+        stdout.write('\n\nCancelled — nothing was written.\n');
+        process.exit(130);
+      }
+
+      let result;
+      try {
+        result = onKey(key);
+      } catch (err) {
+        cleanup();
+        reject(err);
+        return;
+      }
+
+      if (result && result.done) {
+        cleanup();
+        resolve(result.value);
+      }
+    }
+
+    stdin.on('data', handler);
+  });
+}
+
+/**
+ * Arrow-key single select. `choices` is [{ label, value, hint }].
+ * Returns the chosen `value`.
+ */
+export async function select(question, choices, defaultIndex = 0) {
+  let index = defaultIndex;
+  let drawn = 0;
+
+  const render = () => {
+    clearLines(drawn);
+    let out = `${c.bold('?')} ${question}  ${c.dim('↑↓ to move, Enter to pick')}\n`;
+    for (let i = 0; i < choices.length; i++) {
+      const active = i === index;
+      const pointer = active ? c.cyan('❯') : ' ';
+      const label = active ? c.cyan(choices[i].label) : choices[i].label;
+      const hint = choices[i].hint ? `  ${c.dim(choices[i].hint)}` : '';
+      out += `${pointer} ${label}${hint}\n`;
+    }
+    stdout.write(out);
+    drawn = choices.length + 1;
+  };
+
+  setCursor(false);
+  render();
+
+  const value = await readKeys((key) => {
+    if (key === KEY.up) {
+      index = (index - 1 + choices.length) % choices.length;
+      render();
+    } else if (key === KEY.down) {
+      index = (index + 1) % choices.length;
+      render();
+    } else if (key === KEY.enter || key === KEY.newline) {
+      return { done: true, value: choices[index].value };
+    }
+    return null;
+  });
+
+  // Collapse the menu to a single answered line.
+  clearLines(drawn);
+  const chosen = choices.find((ch) => ch.value === value);
+  stdout.write(`${c.green('✔')} ${question}  ${c.cyan(chosen.label)}\n`);
+  return value;
+}
+
+/**
+ * Spacebar checkbox multi-select. `choices` is [{ label, value, hint, checked }].
+ * Returns an array of checked `value`s. Enter with nothing checked is refused,
+ * since every multi-select in this wizard needs at least one answer.
+ */
+export async function checkbox(question, choices) {
+  let index = 0;
+  let drawn = 0;
+  const state = choices.map((ch) => Boolean(ch.checked));
+  let warning = '';
+
+  const render = () => {
+    clearLines(drawn);
+    let out = `${c.bold('?')} ${question}  ${c.dim('↑↓ move, space to toggle, Enter to confirm')}\n`;
+    for (let i = 0; i < choices.length; i++) {
+      const active = i === index;
+      const pointer = active ? c.cyan('❯') : ' ';
+      const box = state[i] ? c.green('◉') : '◯';
+      const label = active ? c.cyan(choices[i].label) : choices[i].label;
+      const hint = choices[i].hint ? `  ${c.dim(choices[i].hint)}` : '';
+      out += `${pointer} ${box} ${label}${hint}\n`;
+    }
+    if (warning) out += `${c.dim(warning)}\n`;
+    stdout.write(out);
+    drawn = choices.length + 1 + (warning ? 1 : 0);
+  };
+
+  setCursor(false);
+  render();
+
+  const values = await readKeys((key) => {
+    if (key === KEY.up) {
+      index = (index - 1 + choices.length) % choices.length;
+      warning = '';
+      render();
+    } else if (key === KEY.down) {
+      index = (index + 1) % choices.length;
+      warning = '';
+      render();
+    } else if (key === KEY.space) {
+      state[index] = !state[index];
+      warning = '';
+      render();
+    } else if (key === KEY.enter || key === KEY.newline) {
+      const picked = choices.filter((_, i) => state[i]).map((ch) => ch.value);
+      if (picked.length === 0) {
+        warning = '  Pick at least one (space to toggle).';
+        render();
+        return null;
+      }
+      return { done: true, value: picked };
+    }
+    return null;
+  });
+
+  clearLines(drawn);
+  const labels = choices.filter((_, i) => state[i]).map((ch) => ch.label).join(', ');
+  stdout.write(`${c.green('✔')} ${question}  ${c.cyan(labels)}\n`);
+  return values;
+}
+
+/**
+ * Free-text input with a default. Implemented on the same raw-mode reader as
+ * the menus: readline and raw mode cannot share stdin — if both are listening,
+ * keystrokes go to the wrong reader and the wizard hangs. One owner, always.
+ */
+export async function input(question, defaultValue = '') {
+  let buffer = '';
+  const hint = defaultValue ? c.dim(` [${defaultValue}]`) : '';
+
+  const render = () => {
+    stdout.write(`\r${ESC}[0K${c.bold('?')} ${question}${hint} ${buffer}`);
+  };
+
+  setCursor(true);
+  render();
+
+  const value = await readKeys((key) => {
+    if (key === KEY.enter || key === KEY.newline) {
+      return { done: true, value: buffer.trim() || defaultValue };
+    }
+    // Backspace (DEL or BS)
+    if (key === '' || key === '\b') {
+      buffer = buffer.slice(0, -1);
+      render();
+      return null;
+    }
+    // Ignore escape sequences (arrows etc.) and other control chars.
+    if (key.startsWith(ESC) || key < ' ') return null;
+
+    buffer += key;
+    render();
+    return null;
+  });
+
+  stdout.write(`\r${ESC}[0K${c.green('✔')} ${question}  ${c.cyan(value)}\n`);
+  return value;
+}
+
+/** Yes/no as an arrow menu, so every prompt in the wizard behaves the same way. */
+export async function confirm(question, defaultYes = true) {
+  return select(
+    question,
+    [
+      { label: 'Yes', value: true },
+      { label: 'No', value: false },
+    ],
+    defaultYes ? 0 : 1
+  );
+}

package/src/scaffold.mjs

@@ -9,7 +9,13 @@ import { fileURLToPath } from 'node:url';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const TEMPLATES_ROOT = path.join(__dirname, '..', 'templates');
 
-const SKILL_NAMES = ['kracked-boot', 'kracked-sdd', 'kracked-wrap', 'kracked-explain'];
+const SKILL_NAMES = [
+  'kracked-boot',
+  'kracked-sdd',
+  'kracked-wrap',
+  'kracked-explain',
+  'kracked-identity',
+];
 
 /** Read a template file, throwing a clear error if Track A hasn't shipped it yet. */
 function readTemplate(relPath) {
@@ -173,7 +179,7 @@ export async function writeLoaders({ projectDir, tokens, ask, report }) {
 }
 
 /**
- * Write the 4 skills to BOTH .claude/skills/<name>/SKILL.md and
+ * Write every skill to BOTH .claude/skills/<name>/SKILL.md and
  * .agents/skills/<name>/SKILL.md — but only for the harnesses selected.
  * `editors` is an array that may contain 'antigravity' and/or 'claude'.
  */

package/src/wizard.mjs

@@ -1,7 +1,6 @@
 // Interactive prompt flow for `npx kracked-core init`.
 // Follows the wizard flow in CONTRACT.md exactly — question order matters.
 
-import readline from 'node:readline/promises';
 import { stdin, stdout } from 'node:process';
 import fs from 'node:fs';
 import path from 'node:path';
@@ -13,7 +12,9 @@ import {
   classifyProjectDir,
   scanExistingProject,
   stackSummaryLine,
+  detectExistingAgentSetup,
 } from './detect.mjs';
+import { select, checkbox, confirm, input } from './prompt.mjs';
 import {
   writeGlobalMemory,
   registerProject,
@@ -68,87 +69,91 @@ export async function runInit() {
     return;
   }
 
-  const rl = readline.createInterface({ input: stdin, output: stdout });
-
-  let interrupted = false;
+  // Ctrl+C / Ctrl+D are handled inside prompt.mjs, which owns stdin in raw
+  // mode. Keep a SIGINT guard for interrupts arriving between prompts.
   const onSigint = () => {
-    interrupted = true;
     stdout.write('\n\nCancelled. Nothing after this point was written.\n');
-    rl.close();
     process.exit(130);
   };
   process.on('SIGINT', onSigint);
 
   try {
-    await wizardFlow(rl);
-  } catch (err) {
-    // Ctrl+D (EOF) mid-question surfaces as readline's AbortError. Treat it
-    // the same as Ctrl+C — a clean cancel, not a crash with a scary stack.
-    if (err.code === 'ABORT_ERR' || /ctrl\+d/i.test(err.message || '')) {
-      stdout.write('\n\nCancelled. Nothing after this point was written.\n');
-      process.exitCode = 130;
-      return;
-    }
-    throw err;
+    await wizardFlow();
   } finally {
     process.off('SIGINT', onSigint);
-    if (!interrupted) rl.close();
+    stdin.pause();
   }
 }
 
-/** Ask a question with a default; Enter alone accepts the default. */
-async function ask(rl, question, defaultValue) {
-  const suffix = defaultValue ? ` [${defaultValue}]` : '';
-  const answer = (await rl.question(`${question}${suffix} `)).trim();
-  return answer === '' ? defaultValue : answer;
+/** Prompt for how to resolve a file-already-exists conflict. */
+async function askConflict(destPath) {
+  stdout.write(`\n  Already exists: ${destPath}\n`);
+  return select(
+    '  What should we do?',
+    [
+      { label: 'Skip', value: 'skip', hint: 'keep the existing file' },
+      { label: 'Overwrite', value: 'overwrite', hint: 'replace it' },
+      { label: 'Write alongside', value: 'alongside', hint: 'save as .kracked-new' },
+    ],
+    0
+  );
 }
 
-/** Ask a yes/no question. Returns boolean. Default shown as Y/n or y/N. */
-async function askYesNo(rl, question, defaultYes) {
-  const suffix = defaultYes ? '[Y/n]' : '[y/N]';
-  const answer = (await rl.question(`${question} ${suffix} `)).trim().toLowerCase();
-  if (answer === '') return defaultYes;
-  return answer === 'y' || answer === 'yes';
+/**
+ * Warn before writing into a directory another agent system already governs.
+ * A CLAUDE.md we didn't write belongs to someone else's setup — overwriting it
+ * silently replaces that agent's identity. Ask first, every time.
+ */
+async function warnOnExistingSetup(projectDir) {
+  const found = detectExistingAgentSetup(projectDir).filter((f) => !f.ours);
+  if (found.length === 0) return true;
+
+  stdout.write('\n  Heads up — this looks like it already has an agent setup:\n');
+  for (const f of found) {
+    const where = f.scope === 'global' ? 'global' : 'this project';
+    stdout.write(`    • ${f.file}  ${c_dim(`(${where})`)}\n`);
+  }
+  stdout.write(
+    '\n  Installing here would overwrite those loaders and change who your\n' +
+    '  agent is in this directory. Existing files are never replaced without\n' +
+    '  asking, but it is easy to end up with two systems giving different\n' +
+    '  instructions.\n\n'
+  );
+
+  return confirm('Continue installing here?', false);
 }
 
-/** Prompt for how to resolve a file-already-exists conflict. */
-async function askConflict(rl, destPath) {
-  stdout.write(`\n  Already exists: ${destPath}\n`);
-  const answer = (
-    await rl.question('  skip / overwrite / write alongside as .kracked-new? [skip] ')
-  ).trim().toLowerCase();
-
-  if (answer === 'o' || answer === 'overwrite') return 'overwrite';
-  if (answer === 'a' || answer === 'alongside' || answer === 'write alongside') return 'alongside';
-  return 'skip';
+/** Minimal dim helper for wizard-level notices. */
+function c_dim(s) {
+  return `${s}`;
 }
 
-async function wizardFlow(rl) {
+async function wizardFlow() {
   const created = [];
   const reporter = (entry) => created.push(entry);
-  const conflictAsk = (destPath) => askConflict(rl, destPath);
+  const conflictAsk = (destPath) => askConflict(destPath);
 
   stdout.write('kracked-core — set up memory for your AI coding agent\n\n');
 
   // 1. Agent name
-  const agentName = (await ask(rl, 'What should we call your agent?', 'KC')) || 'KC';
+  const agentName = (await input('What should we call your agent?', 'KC')) || 'KC';
 
   // 2. User name
   const systemUser = os.userInfo().username || 'you';
-  const userName = (await ask(rl, 'Your name?', systemUser)) || systemUser;
+  const userName = (await input('Your name?', systemUser)) || systemUser;
 
-  // 3. Global memory
+  // 3. Global memory — always installed. It holds identity, preferences and
+  // cross-project lessons, and boot depends on it; making it optional only
+  // created a way to end up with a half-installed system that can't boot.
+  // Existing files are still never overwritten without asking.
   const hasGlobal = globalMemoryExists();
-  let setUpGlobal;
-  if (!hasGlobal) {
-    setUpGlobal = await askYesNo(rl, 'Set up global memory now?', true);
-  } else {
-    const reuse = await askYesNo(rl, 'Global memory found. Reuse it?', true);
-    setUpGlobal = !reuse; // if not reusing, we still (re)write it below
+  const setUpGlobal = true;
+  if (hasGlobal) {
+    stdout.write(`\n  Global memory found at ${globalMemoryDir()} — reusing it.\n`);
   }
 
   // 4. Project setup
-  const setUpProject = await askYesNo(rl, 'Set up this project?', true);
+  const setUpProject = await confirm('Set up this project?', true);
 
   let projectDir = process.cwd();
   let projectMode = null; // 'new' | 'existing'
@@ -156,24 +161,29 @@ async function wizardFlow(rl) {
   let projectSummary = null;
 
   if (setUpProject) {
-    const pathAnswer = await ask(rl, 'Project directory?', '.');
+    const pathAnswer = await input('Project directory?', '.');
     const expanded = expandTilde(pathAnswer);
     projectDir = path.resolve(expanded === '' ? '.' : expanded);
 
-    const classification = classifyProjectDir(projectDir);
-
-    if (classification === 'existing') {
-      const modeAnswer = (
-        await ask(rl, 'New project or existing codebase? (new/existing)', 'existing')
-      ).toLowerCase();
-      projectMode = modeAnswer.startsWith('n') ? 'new' : 'existing';
-    } else {
-      const modeAnswer = (
-        await ask(rl, 'New project or existing codebase? (new/existing)', 'new')
-      ).toLowerCase();
-      projectMode = modeAnswer.startsWith('e') ? 'existing' : 'new';
+    // Another agent system already here? Ask before touching its loaders.
+    if (fs.existsSync(projectDir)) {
+      const proceed = await warnOnExistingSetup(projectDir);
+      if (!proceed) {
+        stdout.write('\nStopped — nothing was written to this project.\n');
+        return;
+      }
     }
 
+    const classification = classifyProjectDir(projectDir);
+    projectMode = await select(
+      'Is this a new project or an existing codebase?',
+      [
+        { label: 'Existing codebase', value: 'existing', hint: 'scan it and draft the memory' },
+        { label: 'New project', value: 'new', hint: 'start with a blank scaffold' },
+      ],
+      classification === 'existing' ? 0 : 1
+    );
+
     if (projectMode === 'existing') {
       if (!fs.existsSync(projectDir)) {
         stdout.write(`\n  ${projectDir} doesn't exist yet — nothing to scan. Treating as new.\n`);
@@ -192,9 +202,9 @@ async function wizardFlow(rl) {
         }
         stdout.write('\n');
 
-        const confirmed = await askYesNo(rl, 'Does this look right?', true);
+        const confirmed = await confirm('Does this look right?', true);
         if (!confirmed) {
-          const manualStack = await ask(rl, 'Describe the stack yourself:', stackLine);
+          const manualStack = await input('Describe the stack yourself:', stackLine);
           stackLine = manualStack;
         }
       }
@@ -208,23 +218,25 @@ async function wizardFlow(rl) {
     }
   }
 
-  // 5. Editors
-  const editorAnswer = (
-    await ask(rl, 'Which editor(s) do you use? (antigravity/claude/both/other)', 'both')
-  ).toLowerCase();
-
-  let editors;
-  if (editorAnswer.startsWith('both')) {
-    editors = ['antigravity', 'claude'];
-  } else if (editorAnswer.startsWith('a')) {
-    editors = ['antigravity'];
-  } else if (editorAnswer.startsWith('c')) {
-    editors = ['claude'];
-  } else {
-    // "other" or anything unrecognized — still write both loader formats,
-    // since AGENTS.md/CLAUDE.md are cheap and cover most tools either way.
-    editors = ['antigravity', 'claude'];
-  }
+  // 5. Editors — a checkbox, so anyone already running another agent system in
+  // one harness can install for the other and leave that one alone.
+  const existing = setUpProject ? detectExistingAgentSetup(projectDir) : [];
+  const claudeTaken = existing.some((f) => f.file === 'CLAUDE.md' && !f.ours);
+
+  const editors = await checkbox('Which editor(s) do you use?', [
+    {
+      label: 'Antigravity',
+      value: 'antigravity',
+      checked: true,
+      hint: 'writes .agents/',
+    },
+    {
+      label: 'Claude Code',
+      value: 'claude',
+      checked: !claudeTaken,
+      hint: claudeTaken ? 'CLAUDE.md already in use here' : 'writes CLAUDE.md + .claude/',
+    },
+  ]);
 
   // 6. Write files
   const projectName = projectSummary?.name || (setUpProject ? path.basename(projectDir) : 'unnamed-project');

package/templates/loaders/AGENTS.md

@@ -50,6 +50,7 @@ the signup flow, next step is wiring the email step. Ready."
 | `/kracked-sdd` | Runs the SDD flow: idea → spec → docs → build → review |
 | `/kracked-wrap` | Writes lessons + updates session state, closes the session cleanly |
 | `/kracked-explain` | Walks {{USER_NAME}} through what kracked-core installed and why |
+| `/kracked-identity` | Change who you are, your tone, or how {{USER_NAME}} likes to work |
 
 ## Writing memory (wrap)
 

package/templates/skills/kracked-boot/SKILL.md

@@ -5,14 +5,21 @@ description: Use at the start of every session, before any other work, to load g
 
 Run this before doing anything else in the session. Do not skip steps or merge reads together.
 
-## 1. Check that memory exists
+## 1. Check what memory exists
 
-Look for `~/.kracked/identity.md`. If it is missing, global memory has not been set up. Tell the
-user:
+Look for `~/.kracked/identity.md` (global) and `.kracked/` in the current directory (project).
+At least one must exist. Boot works with either layer — never halt just because one is missing.
 
-> Global memory isn't set up yet. Run `npx kracked-core init` to create it, then re-run this.
+- **Both present** — normal boot. Continue to step 2.
+- **Project only** (no `~/.kracked/`) — boot from project memory alone. Behave as a careful,
+  direct coding agent, and say in your orientation line that global memory isn't set up, so
+  cross-project lessons and preferences aren't loaded. Mention `npx kracked-core init` once.
+  Do NOT invent preferences or lessons you haven't read.
+- **Global only** (no `.kracked/` here) — see step 3.
+- **Neither** — nothing is installed. Say so and point at `npx kracked-core init`. This is the
+  only case where there's nothing to load.
 
-Stop here if memory doesn't exist. Do not fabricate identity, preferences, or project state.
+Never fabricate identity, preferences, project state, or lessons. Missing is missing — say it.
 
 ## 2. Load global memory, in this exact order
 

package/templates/skills/kracked-identity/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: kracked-identity
+description: Use when the user wants to change their agent's name, personality, or communication style, or to record how they like to work — anything about who the agent is or what it should remember about them.
+---
+
+Help the user shape who you are and how you work with them. Two files, two purposes — keep them
+straight, because mixing them up is the most common mistake.
+
+| File | Holds | Example |
+|---|---|---|
+| `~/.kracked/identity.md` | Who the AGENT is | name, tone, how direct to be |
+| `~/.kracked/preferences.md` | How the USER works | their stack, their conventions, what to never do |
+
+If they say "be less formal" → identity. If they say "I use Tailwind, stop suggesting CSS
+modules" → preferences. When unsure, ask which one they mean rather than guessing.
+
+## 1. Work out what they actually want to change
+
+Read both files first, so you're editing from what's there rather than overwriting blind.
+
+Then figure out which of these they're asking for:
+
+- **Rename** — just the agent's name
+- **Personality / tone** — how you talk to them
+- **Preferences** — their stack, style, or a standing rule for you to follow
+- **"I don't know, it just feels off"** — go to step 2
+
+## 2. If they can't name it, ask about behaviour, not settings
+
+Don't hand them a config form. Ask what's been annoying:
+
+- "Am I too wordy, or not detailed enough?"
+- "Do I explain too much before doing the work?"
+- "Anything I keep suggesting that you never want?"
+- "Anything I keep getting wrong about your setup?"
+
+Turn each answer into a concrete line. "Be less annoying" is not actionable; "answer first, then
+explain, and don't restate my question back to me" is.
+
+## 3. Make the edit
+
+Edit the file directly — surgical changes, not a rewrite. Keep the existing structure and only
+touch the lines that need to change.
+
+- Renaming: update the name in `identity.md`. Mention that `AGENTS.md` in their projects may
+  also name the agent, and offer to update those too.
+- Tone/personality: edit the "How I work" or "Communication style" section.
+- Preferences: add to the right section of `preferences.md`. One line per rule, specific enough
+  to act on.
+
+**Never invent preferences they didn't state.** If you observed something during the session
+("you corrected me twice about using Postgres, not MySQL"), say so and ask whether to write it
+down — don't just write it.
+
+## 4. Read the change back
+
+Show them the lines you changed, exactly as written. Then say plainly:
+
+> This takes effect at your next boot. Run `/kracked-boot` in a fresh session to load it.
+
+Do not claim the change is already active in the current session — memory is read at boot.
+
+## Two things worth telling them once
+
+- **These are plain markdown files they own.** They can open `~/.kracked/identity.md` in any
+  editor and change it directly. Doing that is often faster than asking you.
+- **Global vs project.** Identity and preferences are global — they apply everywhere. Anything
+  true only for one codebase (its stack, conventions, structure) belongs in that project's
+  `.kracked/project.md` instead. Putting project detail in global memory makes you apply it to
+  every other project, which is the most common way this system goes wrong.