@zyaiting/keelson 0.4.0

package/src/platforms/integration.js

@@ -0,0 +1,384 @@
+import fs from 'node:fs';
+import crypto from 'node:crypto';
+import path from 'node:path';
+import { exists, read, readJson, readOr, rmrf, write, writeJson } from '../lib/fs.js';
+import { installTargets, PLATFORMS } from './registry.js';
+import { managedSkillShimMatches, residentBlock } from './runtime.js';
+
+export const MANAGED_STATE = path.join('.keelson', 'manifest.json');
+export const LEGACY_MANAGED_STATE = path.join('.keelson', '.managed.json');
+
+// v0.3 copied these package scripts into the project. Retire only exact known
+// copies, including the older installed snapshot committed in f6ce125 itself.
+// A user amendment or symbolic link is their file, not ours.
+const LEGACY_COPIED_HOOK_HASHES = new Map([
+  ['session-start.mjs', new Set([
+    '2c425e68f52b1b9c8febeb410916b14b302893bf0b241ea1b9ba4275452ee217',
+    '2b2f3523abaf14671764a0f1967ad649881013cc8cc3cb70b51e91b4b5d9dee7',
+  ])],
+  ['prompt-state.mjs', new Set([
+    'cd7301e7efa00368a437d8a3e084844df1cd611969ae2465c82d8ac8f6707131',
+    '10cf6cb9781c58330160602d85dcd2d417bc11c1e99223a7e55477a2529448a7',
+  ])],
+  ['codebuddy-session.mjs', new Set(['cbdcbac42ab752387721c3b53f9fae50a22e04d2e04dbb612dba45d90efc25a8'])],
+]);
+
+export const LEGACY_MANAGED_PATHS = [
+  '.cursor/skills/keelson',
+  '.cursor/rules/keelson.mdc',
+  '.github/skills/keelson',
+  '.kilocode/skills/keelson',
+  '.kilocode/rules/keelson.md',
+  '.kiro/steering/keelson.md',
+  '.qoder/skills/keelson',
+  '.qoder/rules/keelson.md',
+  '.codebuddy/rules/keelson.md',
+  '.pi/skills/keelson',
+  '.agent/skills/keelson',
+  '.agent/rules/keelson.md',
+  '.devin/skills/keelson',
+  '.factory/skills/keelson',
+  '.reasonix/skills/keelson',
+  '.zcode/skills/keelson',
+  '.trae/skills/keelson',
+  '.trae/rules/keelson.md',
+  '.grok/skills/keelson',
+  '.kimi/skills/keelson',
+  '.snow/skills/keelson',
+];
+
+const managedTarget = (t) => ({
+  id: t.id ?? null,
+  label: t.label ?? t.id ?? 'managed surface',
+  instructions: t.instructions,
+  skillsDir: t.skillsDir,
+  instructionsFormat: t.instructionsFormat ?? null,
+  rulesFile: t.rulesFile ?? null,
+  rulesFormat: t.rulesFormat ?? null,
+  hooks: Boolean(t.hooks),
+  sessionAdapter: t.sessionAdapter ?? null,
+});
+const sessionAdapterPaths = () => [];
+const targetKey = (t) => [t.instructions, t.skillsDir, t.instructionsFormat ?? '', t.rulesFile ?? '', t.rulesFormat ?? '', Boolean(t.hooks), t.sessionAdapter ?? ''].join('|');
+const managedSurfacePaths = (t) => [path.join(t.skillsDir, 'keelson'), t.instructions, t.rulesFile, ...sessionAdapterPaths(t)].filter(Boolean);
+
+export function readManagedState(root) {
+  return readJson(path.join(root, MANAGED_STATE), null) ?? readJson(path.join(root, LEGACY_MANAGED_STATE), null);
+}
+
+export function managedTargets(root) {
+  const state = readManagedState(root);
+  return Array.isArray(state?.targets) ? state.targets : [];
+}
+
+export function removeLegacyCopiedHooks(root) {
+  const hooksDir = path.join(root, '.keelson', 'hooks');
+  const removed = [];
+  const preserved = [];
+  for (const [name, expectedHashes] of LEGACY_COPIED_HOOK_HASHES) {
+    const target = path.join(hooksDir, name);
+    const rel = path.join('.keelson', 'hooks', name);
+    const stat = fs.lstatSync(target, { throwIfNoEntry: false });
+    if (stat?.isSymbolicLink()) { preserved.push(rel); continue; }
+    if (!stat?.isFile()) continue;
+    const actualHash = crypto.createHash('sha256').update(read(target).replace(/\r\n?/g, '\n')).digest('hex');
+    if (expectedHashes.has(actualHash)) {
+      rmrf(target);
+      removed.push(rel);
+    } else preserved.push(rel);
+  }
+  if (exists(hooksDir) && fs.readdirSync(hooksDir).length === 0) rmrf(hooksDir);
+  return { removed, preserved };
+}
+
+export function managedStateMatches(root, targets) {
+  const state = readManagedState(root);
+  if (!state || Number(state.schema ?? state.version) !== 1) return false;
+  const a = JSON.stringify((state.targets ?? []).map(managedTarget).sort((x, y) => targetKey(x).localeCompare(targetKey(y))));
+  const b = JSON.stringify(targets.map(managedTarget).sort((x, y) => targetKey(x).localeCompare(targetKey(y))));
+  return a === b;
+}
+
+export function writeManagedState(root, targets, packageVersion, { vendor = false } = {}) {
+  writeJson(path.join(root, MANAGED_STATE), { schema: 1, packageVersion, vendor: Boolean(vendor), targets: targets.map(managedTarget) });
+  if (exists(path.join(root, LEGACY_MANAGED_STATE))) rmrf(path.join(root, LEGACY_MANAGED_STATE));
+  return MANAGED_STATE;
+}
+
+export function staleManagedTargets(root, targets) {
+  const current = new Set(targets.map(targetKey));
+  return managedTargets(root).filter((t) => !current.has(targetKey(t)));
+}
+
+export function legacyManagedRemovals(root, targets) {
+  // Older releases did not record byte-level ownership for these retired paths.
+  // A title or frontmatter is not sufficient proof that a directory is ours.
+  // Keep unknown legacy content for the owner to review instead of deleting it.
+  return [];
+}
+
+export function plannedManagedRemovals(root, targets) {
+  const keep = new Set(targets.flatMap(managedSurfacePaths));
+  return [...new Set([
+    ...staleManagedTargets(root, targets).flatMap(managedSurfacePaths).filter((rel) => !keep.has(rel)),
+    ...legacyManagedRemovals(root, targets),
+  ])].filter((rel) => exists(path.join(root, rel)));
+}
+
+const START = '<!-- keelson:start -->';
+const END = '<!-- keelson:end -->';
+
+export function upsertBlock(existing, block) {
+  const body = block.trim();
+  if (existing.includes(START) && existing.includes(END)) {
+    return existing.replace(new RegExp(`${START}[\\s\\S]*?${END}`), body);
+  }
+  const sep = existing.trim() ? (existing.endsWith('\n') ? '\n' : '\n\n') : '';
+  return existing + sep + body + '\n';
+}
+
+export function removeBlock(existing) {
+  const stripped = existing.replace(new RegExp(`\\n*${START}[\\s\\S]*?${END}\\n?`), '');
+  if (!stripped.trim()) return '';
+  return stripped.replace(/\n{3,}/g, '\n\n').replace(/\n*$/, '\n');
+}
+
+const stripMarkers = (block) => block.replace(START, '').replace(END, '').trim();
+
+export function installInstructions(root, target, { lang }) {
+  const p = typeof target === 'string' ? PLATFORMS[target] : target;
+  const block = residentBlock(lang);
+  const touched = [];
+  const file = path.join(root, p.instructions);
+  if (p.instructionsFormat === 'kiro') {
+    const existing = readOr(file, '');
+    const front = existing.match(/^(---\n[\s\S]*?\n---\n?)/)?.[1];
+    if (front) write(file, front.replace(/\n*$/, '\n\n') + upsertBlock(existing.slice(front.length), block));
+    else if (existing) write(file, upsertBlock(existing, block));
+    else write(file, `---\ninclusion: always\n---\n\n${block.trim()}\n`);
+  } else {
+    write(file, upsertBlock(readOr(file, ''), block));
+  }
+  touched.push(path.relative(root, file));
+  if (p.rulesFile) {
+    const rf = path.join(root, p.rulesFile);
+    const body = stripMarkers(block);
+    write(rf, p.rulesFormat === 'mdc' ? `---\ndescription: Keelson project workflow\nalwaysApply: true\n---\n\n${body}\n` : `${body}\n`);
+    touched.push(path.relative(root, rf));
+  }
+  return touched;
+}
+
+const LEGACY_CLAUDE_HOOK_COMMANDS = new Set([
+  'node "$CLAUDE_PROJECT_DIR/.keelson/hooks/session-start.mjs"',
+  'node "$CLAUDE_PROJECT_DIR/.keelson/hooks/prompt-state.mjs"',
+]);
+const CLAUDE_HOOK_COMMANDS = new Set(['keelson hook session-start', 'keelson hook prompt-state', ...LEGACY_CLAUDE_HOOK_COMMANDS]);
+const isClaudeHook = (hook) => hook?.type === 'command' && CLAUDE_HOOK_COMMANDS.has(String(hook.command));
+
+export function installHooks(root) {
+  removeHooks(root, { legacyOnly: true });
+  const settingsPath = path.join(root, '.claude', 'settings.json');
+  const settings = readJson(settingsPath, {}) ?? {};
+  settings.hooks ??= {};
+  const ensure = (event, matcher, script) => {
+    settings.hooks[event] ??= [];
+    const command = `keelson hook ${script.replace(/\.mjs$/, '')}`;
+    const already = settings.hooks[event].some((g) => (g.hooks ?? []).some((h) => h?.type === 'command' && h.command === command));
+    if (already) return;
+    const group = { hooks: [{ type: 'command', command, timeout: 10 }] };
+    if (matcher) group.matcher = matcher;
+    settings.hooks[event].push(group);
+  };
+  ensure('SessionStart', 'startup|resume|clear|compact', 'session-start.mjs');
+  ensure('UserPromptSubmit', null, 'prompt-state.mjs');
+  writeJson(settingsPath, settings);
+  return ['.claude/settings.json'];
+}
+
+export function removeHooks(root, { legacyOnly = false } = {}) {
+  const settingsPath = path.join(root, '.claude', 'settings.json');
+  const settings = readJson(settingsPath, null);
+  if (!settings?.hooks) return;
+  let changed = false;
+  for (const ev of Object.keys(settings.hooks)) {
+    const groups = settings.hooks[ev].map((g) => {
+      const hooks = (g.hooks ?? []).filter((h) => !isClaudeHook(h) || (legacyOnly && !LEGACY_CLAUDE_HOOK_COMMANDS.has(h.command)));
+      if (hooks.length === (g.hooks ?? []).length) return g;
+      changed = true;
+      return hooks.length ? { ...g, hooks } : null;
+    }).filter(Boolean);
+    settings.hooks[ev] = groups;
+    if (!settings.hooks[ev].length) delete settings.hooks[ev];
+  }
+  if (!changed) return;
+  if (!Object.keys(settings.hooks).length) delete settings.hooks;
+  writeJson(settingsPath, settings);
+}
+
+const CODEBUDDY_SESSION_COMMAND = 'keelson hook codebuddy-session';
+const LEGACY_CODEBUDDY_SESSION_COMMAND = 'node "$CODEBUDDY_PROJECT_DIR/.keelson/hooks/codebuddy-session.mjs"';
+const isCodeBuddyHook = (hook) => hook?.type === 'command' && hook.command === CODEBUDDY_SESSION_COMMAND;
+
+function ensureCodeBuddyHook(settings, event, matcher = null) {
+  settings.hooks ??= {};
+  settings.hooks[event] ??= [];
+  const found = settings.hooks[event].find((g) =>
+    (g.hooks ?? []).some(isCodeBuddyHook),
+  );
+  if (found) {
+    if (matcher && found.matcher !== matcher) found.matcher = matcher;
+    else if (!matcher && 'matcher' in found) delete found.matcher;
+    return;
+  }
+  const group = {
+    hooks: [{
+      type: 'command',
+      command: CODEBUDDY_SESSION_COMMAND,
+      timeout: 10,
+    }],
+  };
+  if (matcher) group.matcher = matcher;
+  settings.hooks[event].push(group);
+}
+
+export function installSessionAdapter(root, target) {
+  const p = typeof target === 'string' ? PLATFORMS[target] : target;
+  if (!p?.sessionAdapter || p.sessionAdapter === 'pi-env' || p.sessionAdapter === 'claude-hooks') return [];
+
+  if (p.sessionAdapter === 'codebuddy-hooks') {
+    removeCodeBuddyHooks(root, { legacyOnly: true });
+    const settingsPath = path.join(root, '.codebuddy', 'settings.json');
+    const settings = readJson(settingsPath, {}) ?? {};
+    ensureCodeBuddyHook(settings, 'SessionStart');
+    ensureCodeBuddyHook(settings, 'UserPromptSubmit');
+    ensureCodeBuddyHook(settings, 'PreToolUse', 'Bash|PowerShell');
+    writeJson(settingsPath, settings);
+    return [path.relative(root, settingsPath)];
+  }
+
+  return [];
+}
+
+export function plannedSessionAdapterFiles(root, target) {
+  const p = typeof target === 'string' ? PLATFORMS[target] : target;
+  const rows = [];
+  if (!p?.sessionAdapter || p.sessionAdapter === 'pi-env' || p.sessionAdapter === 'claude-hooks') return rows;
+
+  if (p.sessionAdapter === 'codebuddy-hooks') {
+    const settings = readJson(path.join(root, '.codebuddy', 'settings.json'), {}) ?? {};
+    const has = (event, matcher = null) => (settings.hooks?.[event] ?? []).some((g) =>
+      (matcher === null || g.matcher === matcher) &&
+      (g.hooks ?? []).some(isCodeBuddyHook),
+    );
+    const ready = has('SessionStart') && has('UserPromptSubmit') && has('PreToolUse', 'Bash|PowerShell');
+    rows.push({ path: '.codebuddy/settings.json (Keelson session hooks)', status: ready ? 'unchanged' : exists(path.join(root, '.codebuddy', 'settings.json')) ? 'update' : 'create' });
+  }
+
+  return rows;
+}
+
+function removeCodeBuddyHooks(root, { legacyOnly = false } = {}) {
+  const settingsPath = path.join(root, '.codebuddy', 'settings.json');
+  const settings = readJson(settingsPath, null);
+  if (!settings?.hooks) return false;
+  let changed = false;
+  for (const event of Object.keys(settings.hooks)) {
+    settings.hooks[event] = settings.hooks[event].map((g) => {
+      const hooks = (g.hooks ?? []).filter((h) =>
+        !(h?.type === 'command' && h.command === LEGACY_CODEBUDDY_SESSION_COMMAND) && (legacyOnly || !isCodeBuddyHook(h)),
+      );
+      if (hooks.length === (g.hooks ?? []).length) return g;
+      changed = true;
+      return hooks.length ? { ...g, hooks } : null;
+    }).filter(Boolean);
+    if (!settings.hooks[event].length) delete settings.hooks[event];
+  }
+  if (!changed) return false;
+  if (!Object.keys(settings.hooks).length) delete settings.hooks;
+  if (!Object.keys(settings).length) rmrf(settingsPath);
+  else writeJson(settingsPath, settings);
+  return true;
+}
+
+export function removeSessionAdapter(root, target, keep = new Set()) {
+  const p = typeof target === 'string' ? PLATFORMS[target] : target;
+  const removed = [];
+  if (p?.sessionAdapter === 'codebuddy-hooks') {
+    if (removeCodeBuddyHooks(root)) removed.push('.codebuddy/settings.json (Keelson hooks)');
+  }
+  return removed;
+}
+
+export function sessionAdapterProblems(root, target) {
+  const p = typeof target === 'string' ? PLATFORMS[target] : target;
+  const problems = [];
+  if (!p?.sessionAdapter || p.sessionAdapter === 'pi-env' || p.sessionAdapter === 'claude-hooks') return problems;
+
+  if (p.sessionAdapter === 'codebuddy-hooks') {
+    const settings = readJson(path.join(root, '.codebuddy', 'settings.json'), {}) ?? {};
+    const has = (event, matcher = null) => (settings.hooks?.[event] ?? []).some((g) =>
+      (matcher === null || g.matcher === matcher) &&
+      (g.hooks ?? []).some(isCodeBuddyHook),
+    );
+    if (!has('SessionStart')) problems.push(`${p.label}: SessionStart session hook not registered`);
+    if (!has('UserPromptSubmit')) problems.push(`${p.label}: UserPromptSubmit session hook not registered`);
+    if (!has('PreToolUse', 'Bash|PowerShell')) problems.push(`${p.label}: Bash|PowerShell PreToolUse session hook not registered`);
+  }
+
+  return problems;
+}
+
+function removeTargetSurfaces(root, p, keep = new Set()) {
+  const removed = [];
+  const skillRel = path.join(p.skillsDir, 'keelson');
+  const skill = path.join(root, skillRel);
+  const managed = readManagedState(root);
+  if (!keep.has(skillRel) && exists(skill) && managedSkillShimMatches(root, p, managed?.packageVersion)) {
+    rmrf(skill);
+    removed.push(path.relative(root, skill));
+  }
+  const insRel = p.instructions;
+  const ins = path.join(root, insRel);
+  if (!keep.has(insRel) && exists(ins)) {
+    write(ins, removeBlock(read(ins)));
+    removed.push(path.relative(root, ins));
+  }
+  if (p.rulesFile && !keep.has(p.rulesFile) && exists(path.join(root, p.rulesFile))) {
+    rmrf(path.join(root, p.rulesFile));
+    removed.push(p.rulesFile);
+  }
+  if (p.hooks && !keep.has('.claude/settings.json')) removeHooks(root);
+  removed.push(...removeSessionAdapter(root, p, keep));
+  return removed;
+}
+
+export function reconcileManagedTargets(root, targets) {
+  const removed = [];
+  const stale = staleManagedTargets(root, targets);
+  const keep = new Set(targets.flatMap(managedSurfacePaths));
+  if (targets.some((p) => p.hooks)) keep.add('.claude/settings.json');
+  for (const p of stale) removed.push(...removeTargetSurfaces(root, p, keep));
+  for (const rel of legacyManagedRemovals(root, targets)) {
+    rmrf(path.join(root, rel));
+    removed.push(rel);
+  }
+  if (stale.some((p) => p.hooks) && !targets.some((p) => p.hooks)) {
+    removeHooks(root);
+  }
+  return [...new Set(removed)];
+}
+
+export function removeSurfaces(root, tools, cfg = null) {
+  const stateTargets = managedTargets(root);
+  const targets = stateTargets.length ? stateTargets : installTargets(tools.filter((t) => PLATFORMS[t]), cfg);
+  const removed = [];
+  for (const p of targets) removed.push(...removeTargetSurfaces(root, p));
+  removeHooks(root);
+  for (const rel of [MANAGED_STATE, LEGACY_MANAGED_STATE]) {
+    if (!exists(path.join(root, rel))) continue;
+    rmrf(path.join(root, rel));
+    removed.push(rel);
+  }
+  return [...new Set(removed)];
+}

package/src/platforms/registry.js

@@ -0,0 +1,46 @@
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const REGISTRY = require('../../registry/platforms.json');
+
+/** Host discovery registry. Runtime guidance itself always lives under .keelson/. */
+export const PLATFORMS = Object.fromEntries(Object.entries(REGISTRY.platforms).map(([id, p]) => [id, { id, ...p }]));
+export const PLATFORM_IDS = Object.keys(PLATFORMS);
+export const RETIRED_PLATFORM_IDS = ['cursor', 'copilot', 'kilo', 'antigravity', 'devin', 'qoder', 'droid', 'ohmypi', 'reasonix', 'zcode', 'trae', 'grok', 'kimi', 'snow'];
+
+export const CROSS_TOOL = {
+  id: 'agents',
+  label: 'cross-tool layer',
+  instructions: 'AGENTS.md',
+  skillsDir: '.agents/skills',
+  hooks: false,
+};
+
+/** Merge per-project discovery overrides on top of the first-class registry. */
+export function platformFor(id, cfg = null) {
+  const base = PLATFORMS[id];
+  if (!base) return null;
+  const over = cfg?.platforms?.[id];
+  return over && typeof over === 'object' ? { ...base, ...over } : base;
+}
+
+/** Expand only explicitly selected hosts into unique concrete discovery targets. */
+export function installTargets(tools, cfg = null) {
+  const targets = [];
+  const seen = new Set();
+  const push = (t) => {
+    // Host identity is part of the target contract now: two hosts may reuse the
+    // same discovery files but still require different session adapters.
+    const key = t.id ?? `${t.instructions}|${t.skillsDir}|${t.rulesFile ?? ''}`;
+    if (seen.has(key)) return;
+    seen.add(key);
+    targets.push(t);
+  };
+  for (const id of tools) {
+    const p = platformFor(id, cfg);
+    if (!p) throw new Error(`unknown tool "${id}". Known: ${PLATFORM_IDS.join(', ')}`);
+    const sessionAdapter = p.sessionAdapter === 'pi-env' ? 'pi-env' : cfg?.hooks === false ? null : p.sessionAdapter ?? null;
+    push({ ...p, hooks: Boolean(p.hooks && cfg?.hooks !== false), sessionAdapter });
+  }
+  return targets;
+}

package/src/platforms/runtime.js

@@ -0,0 +1,249 @@
+import fs from 'node:fs';
+import crypto from 'node:crypto';
+import path from 'node:path';
+import { PKG_ROOT } from '../lib/paths.js';
+import { exists, read, walk, write, rmrf, replaceDirSafe, withLock } from '../lib/fs.js';
+import { PLATFORMS } from './registry.js';
+
+export const CANONICAL_SKILL_DIR = path.join('.keelson', 'skill');
+export const CANONICAL_WORKFLOW = path.join('.keelson', 'workflow.md');
+
+export function skillSource(lang) {
+  const dir = lang === 'zh' ? path.join(PKG_ROOT, 'skills', 'zh', 'keelson') : path.join(PKG_ROOT, 'skills', 'keelson');
+  return exists(dir) ? dir : path.join(PKG_ROOT, 'skills', 'keelson');
+}
+
+/** Strip guided-only blocks from the lean profile. */
+export function applyProfile(text, profile) {
+  if (profile === 'guided') return text.replace(/<!-- \/?guided -->\n?/g, '');
+  return text.replace(/<!-- guided -->[\s\S]*?<!-- \/guided -->\n?/g, '');
+}
+
+/** Stamp package version into SKILL.md frontmatter and normalize package-owned Markdown to LF. */
+export function stampVersion(text, version) {
+  text = text.replace(/\r\n?/g, '\n');
+  if (!version) return text;
+  if (/^version:\s*/m.test(text.split('\n---')[0] ?? '')) return text.replace(/^version:.*$/m, `version: ${version}`);
+  return text.replace(/^---\n([\s\S]*?)\n---/, (_, fm) => `---\n${fm}\nversion: ${version}\n---`);
+}
+
+export function renderSkillFiles(lang, profile, version) {
+  const src = skillSource(lang);
+  const out = [];
+  const visit = (d, rel) => {
+    for (const e of fs.readdirSync(d, { withFileTypes: true })) {
+      if (e.name === 'templates') continue;
+      const r = rel ? `${rel}/${e.name}` : e.name;
+      if (e.isDirectory()) visit(path.join(d, e.name), r);
+      else {
+        let content = fs.readFileSync(path.join(d, e.name), 'utf8');
+        if (r.endsWith('.md')) content = applyProfile(content.replace(/\r\n?/g, '\n'), profile);
+        if (r === 'SKILL.md') content = stampVersion(content, version);
+        out.push({ rel: r, content });
+      }
+    }
+  };
+  visit(src, '');
+  return out;
+}
+
+export function renderSkillShim(lang, version) {
+  const full = stampVersion(read(path.join(skillSource(lang), 'SKILL.md')).replace(/\r\n?/g, '\n'), version);
+  const front = full.match(/^---\n[\s\S]*?\n---/)?.[0] ?? '---\nname: keelson\ndescription: Keelson project skill\n---';
+  const body = lang === 'zh'
+    ? '# Keelson\n\n这是发现入口，不是技能真源。请立即运行 `keelson guide` 并按其执行；需要更深指导时运行 `keelson guide <reference>`。只有项目需要提交审计副本时才使用 `keelson init --vendor`。\n'
+    : '# Keelson\n\nThis is a discovery shim, not the source of truth. Run `keelson guide` now and follow it; for a routed topic run `keelson guide <reference>`. Use `keelson init --vendor` only when this project needs a checked-in copy of the guidance.\n';
+  return `${front}\n\n${body}`;
+}
+
+export function plannedCanonicalSkillFiles(root, { lang, profile, version }) {
+  const dest = path.join(root, CANONICAL_SKILL_DIR);
+  return renderSkillFiles(lang, profile, version).map((f) => {
+    const target = path.join(dest, f.rel);
+    const status = !exists(target) ? 'create' : fs.readFileSync(target, 'utf8') === f.content ? 'unchanged' : 'update';
+    return { path: path.relative(root, target), status };
+  });
+}
+
+export function plannedSkillFiles(root, target, { lang, version }) {
+  const p = typeof target === 'string' ? PLATFORMS[target] : target;
+  const targetPath = path.join(root, p.skillsDir, 'keelson', 'SKILL.md');
+  const content = renderSkillShim(lang, version);
+  const status = !exists(targetPath) ? 'create' : fs.readFileSync(targetPath, 'utf8') === content ? 'unchanged' : 'update';
+  return [{ path: path.relative(root, targetPath), status }];
+}
+
+function normalize(text) {
+  return String(text).replace(/\r\n?/g, '\n');
+}
+
+// Captured by running f6ce125's v0.3 CLI for every supported language/profile
+// combination. A tree hash commits to both paths and normalized file bytes, so
+// adding a neighbor or editing one byte makes this fail closed.
+const LEGACY_V03_SKILL_TREE_HASHES = new Map([
+  ['en/lean', '07ac8e2cb1010956fb172b72661a29ec3c6552ce19433fc4b1a31d012d65272b'],
+  ['en/guided', 'a3a6572d22d88f872eaf0326b0af3c674064cd027abba449715bf64e45201652'],
+  ['zh/lean', '08dd2c503b58372ef85c460867c6e5ef116919b1f69a00449f1ef750cd7603a0'],
+  ['zh/guided', 'd00636b7408c34cabf097d22d347d1e551f629f126f7c9e156760cb73d7d9506'],
+]);
+const LEGACY_V03_SKILL_SHIM_HASHES = new Set([
+  '68a1924866f8ee5af87d0cd75884d3d1ba5bb3138c4daa2d6bd0f6a7d53cd2ef',
+  '4157f6ca8898e6e94a351d1fa63da580c54574049cc4af549834ee4fcb4a237b',
+]);
+const LEGACY_V03_WORKFLOW_HASHES = new Set([
+  '8f8b682ce18a8b9fe6acf16fb528a2a752a4c874db7fc23b3029b7d83ba20dd1',
+  'eab1d92c97ca695b34ae2290d6533858da7ab89f912ce31acbb89e979b75945b',
+  'd8c89ed738bf8c82e643aea41d1cf30cd48b218035234a60b09a2ba6183ae7a4',
+  'a3495a7de442c25aa8e41a3d680cf396c6207d2bdc8566d6d1644aa28bd7f5ba',
+]);
+
+function fileHash(text) {
+  return crypto.createHash('sha256').update(normalize(text)).digest('hex');
+}
+
+function ownedWalk(dir) {
+  return walk(dir, { ignore: [] });
+}
+
+function hasSymbolicLink(dir) {
+  const visit = (current) => {
+    for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+      if (entry.isSymbolicLink()) return true;
+      if (entry.isDirectory() && visit(path.join(current, entry.name))) return true;
+    }
+    return false;
+  };
+  try { return fs.lstatSync(dir).isSymbolicLink() || visit(dir); } catch { return true; }
+}
+
+function treeHash(dir) {
+  if (hasSymbolicLink(dir)) return null;
+  try {
+    return crypto.createHash('sha256').update(ownedWalk(dir)
+      .map((rel) => `${rel}\0${fileHash(read(path.join(dir, rel)))}\n`).join('')).digest('hex');
+  } catch { return null; }
+}
+
+function canonicalSkillMatches(root, { lang, profile, version }) {
+  const dest = path.join(root, CANONICAL_SKILL_DIR);
+  const files = renderSkillFiles(lang, profile, version);
+  if (!hasSymbolicLink(dest) && JSON.stringify(ownedWalk(dest)) === JSON.stringify(files.map((file) => file.rel).sort()) &&
+    files.every((file) => exists(path.join(dest, file.rel)) && normalize(read(path.join(dest, file.rel))) === file.content)) return true;
+  return version === '0.3.0' && treeHash(dest) === LEGACY_V03_SKILL_TREE_HASHES.get(`${lang}/${profile}`);
+}
+
+export function installCanonicalSkill(root, { lang, profile, version, force = false }) {
+  const dest = path.join(root, CANONICAL_SKILL_DIR);
+  const files = renderSkillFiles(lang, profile, version);
+  if (fs.lstatSync(dest, { throwIfNoEntry: false }) && !canonicalSkillMatches(root, { lang, profile, version }) && !force) {
+    throw new Error('vendored skill differs from this CLI output; Keelson left it unchanged. Review it, then pass --force only if replacing the whole directory is intended.');
+  }
+  withLock(dest, () => {
+    replaceDirSafe(dest, (tmp) => {
+      for (const f of files) write(path.join(tmp, f.rel), f.content);
+    });
+  });
+  return path.relative(root, dest);
+}
+
+function legacyV03SkillShimMatches(dest, legacyVersion) {
+  const skill = path.join(dest, 'SKILL.md');
+  return legacyVersion === '0.3.0' && exists(skill) && !hasSymbolicLink(dest) && ownedWalk(dest).length === 1 && LEGACY_V03_SKILL_SHIM_HASHES.has(fileHash(read(skill)));
+}
+
+function skillShimMatches(dest, content, legacyVersion) {
+  const skill = path.join(dest, 'SKILL.md');
+  return exists(skill) && !hasSymbolicLink(dest) && ownedWalk(dest).length === 1 &&
+    (normalize(read(skill)) === content || legacyV03SkillShimMatches(dest, legacyVersion));
+}
+
+function assertSkillInstallable(root, target, { lang, version, legacyVersion, previousVersion, force }) {
+  const p = typeof target === 'string' ? PLATFORMS[target] : target;
+  const dest = path.join(root, p.skillsDir, 'keelson');
+  const priorOutput = previousVersion && managedSkillShimMatches(root, p, previousVersion);
+  if (fs.lstatSync(dest, { throwIfNoEntry: false }) && !skillShimMatches(dest, renderSkillShim(lang, version), legacyVersion) && !priorOutput && !force) {
+    throw new Error('discovery shim differs from this CLI output; Keelson left it unchanged. Review it, then pass --force only if replacing the whole directory is intended.');
+  }
+}
+
+/** Validate discovery replacements before init changes config or legacy runtime. */
+export function assertSkillsInstallable(root, targets, options) {
+  const seen = new Set();
+  for (const target of targets) {
+    const p = typeof target === 'string' ? PLATFORMS[target] : target;
+    if (seen.has(p.skillsDir)) continue;
+    seen.add(p.skillsDir);
+    assertSkillInstallable(root, p, options);
+  }
+}
+
+/** True only for a complete current shim or the byte-exact v0.3 shim. */
+export function managedSkillShimMatches(root, target, version) {
+  const p = typeof target === 'string' ? PLATFORMS[target] : target;
+  const dest = path.join(root, p.skillsDir, 'keelson');
+  return ['en', 'zh'].some((lang) => skillShimMatches(dest, renderSkillShim(lang, version), version));
+}
+
+export function installSkill(root, target, { lang, version, legacyVersion = null, previousVersion = null, force = false }) {
+  const p = typeof target === 'string' ? PLATFORMS[target] : target;
+  const dest = path.join(root, p.skillsDir, 'keelson');
+  const content = renderSkillShim(lang, version);
+  assertSkillInstallable(root, p, { lang, version, legacyVersion, previousVersion, force });
+  withLock(dest, () => replaceDirSafe(dest, (tmp) => write(path.join(tmp, 'SKILL.md'), content)));
+  return path.relative(root, dest);
+}
+
+export function workflowContent(lang, guide = false) {
+  const file = path.join(skillSource(lang), 'templates', 'workflow.md');
+  let text = read(file).replace(/\r\n?/g, '\n');
+  if (!guide) return text;
+  const line = lang === 'zh'
+    ? '> 引导模式：项目所有者希望边做边学。基础提问仍保持场景化；额外解释已采用的工程概念、约束理由，并在 spec 变更收尾时附一段简短教学说明。'
+    : '> Guided mode: the owner wants to learn while building. Keep the same accessible questions; additionally name the engineering ideas behind decisions, explain constraint rationale, and close spec changes with a short teaching note.';
+  return text.replace(/^# ([^\n]+)\n/, (m) => `${m}\n${line}\n`);
+}
+
+export function plannedWorkflowFile(root, { lang, guide = false }) {
+  const target = path.join(root, CANONICAL_WORKFLOW);
+  const content = workflowContent(lang, guide);
+  const status = !exists(target) ? 'create' : fs.readFileSync(target, 'utf8') === content ? 'unchanged' : 'update';
+  return { path: path.relative(root, target), status };
+}
+
+export function installWorkflow(root, { lang, guide = false, force = false }) {
+  const target = path.join(root, CANONICAL_WORKFLOW);
+  const content = workflowContent(lang, guide);
+  const stat = fs.lstatSync(target, { throwIfNoEntry: false });
+  if (stat && (stat.isSymbolicLink() || normalize(read(target)) !== content) && !force) {
+    throw new Error('vendored workflow differs from this CLI output; Keelson left it unchanged. Review it, then pass --force only if replacing it is intended.');
+  }
+  write(target, content);
+  return path.relative(root, target);
+}
+
+export function residentBlock(lang) {
+  return read(path.join(skillSource(lang), 'templates', 'resident-block.md'));
+}
+
+export function removeCanonicalRuntime(root, { lang, profile, version, guide = false } = {}) {
+  const removed = [];
+  const preserved = [];
+  const skill = path.join(root, CANONICAL_SKILL_DIR);
+  if (exists(skill)) {
+    if (canonicalSkillMatches(root, { lang, profile, version })) {
+      rmrf(skill);
+      removed.push(CANONICAL_SKILL_DIR);
+    } else preserved.push(CANONICAL_SKILL_DIR);
+  }
+  const workflow = path.join(root, CANONICAL_WORKFLOW);
+  if (fs.lstatSync(workflow, { throwIfNoEntry: false })?.isSymbolicLink()) {
+    preserved.push(CANONICAL_WORKFLOW);
+  } else if (exists(workflow)) {
+    const legacyWorkflow = version === '0.3.0' && LEGACY_V03_WORKFLOW_HASHES.has(fileHash(read(workflow)));
+    if (normalize(read(workflow)) === workflowContent(lang, guide) || legacyWorkflow) {
+      rmrf(workflow);
+      removed.push(CANONICAL_WORKFLOW);
+    } else preserved.push(CANONICAL_WORKFLOW);
+  }
+  return { removed, preserved };
+}