ronin-skillforce 0.1.0 → 0.2.0-beta.0

package/bin/commands/trail.js

@@ -16,6 +16,7 @@ import { style } from '../registry-helpers.js';
 
 export const MAX_ROUNDS = 5;
 const TRAIL_RE = /^##\s+.*reasoning trail/i;
+const ENTRIES_RE = /^##\s+.*section entries/i;
 const ROUND_RE = /^Round\s+\d+\b/;
 
 /** Pick the course by slug; with no slug only a single course is accepted — never guess. */
@@ -24,10 +25,10 @@ export function resolveCourse(cwd, slug) {
   if (slug) {
     const hit = courses.find((c) => c.slug === slug);
     if (hit) return hit;
-    throw new Error(`No course "${slug}" under learning/ or courses/. Found: ${courses.map((c) => c.slug).join(', ') || 'none'}.`);
+    throw new Error(`No course "${slug}" under learning/. Found: ${courses.map((c) => c.slug).join(', ') || 'none'}.`);
   }
   if (courses.length === 1) return courses[0];
-  if (!courses.length) throw new Error('No course found under learning/ or courses/. Run professor:new-topic first.');
+  if (!courses.length) throw new Error('No course found under learning/. Run professor:new-topic first.');
   throw new Error(`Several courses found — pass the slug: ${courses.map((c) => c.slug).join(', ')}.`);
 }
 
@@ -161,12 +162,148 @@ export function recordRound({ cwd, slug, section, learner, asked, concept, evide
   return { recorded: true, path, section: target, rounds, saved };
 }
 
+// ─── Section Entries (done gate verdict) ─────────────────────────────────────
+
+/** Accepts `solid` or `watch-this: <concept>` (leading ⚠️ tolerated). */
+export function normalizeVerdict(raw) {
+  const value = oneLine(raw);
+  if (/^solid$/i.test(value)) return { verdict: 'solid', watch: null };
+  const m = value.match(/^(?:⚠️\s*)?watch-this\s*:\s*(.+)$/i);
+  if (m && oneLine(m[1])) return { verdict: `⚠️ watch-this: ${oneLine(m[1])}`, watch: oneLine(m[1]) };
+  throw new Error('Invalid verdict — use "solid" or "watch-this: <concept>". Nothing was recorded.');
+}
+
+/** Index of the first `##` heading after `start`, or lines.length. */
+function regionEnd(lines, start) {
+  let i = start + 1;
+  while (i < lines.length && !/^##\s/.test(lines[i])) i++;
+  return i;
+}
+
+/** Find or create `## 📝 Section Entries`; returns its line index. */
+function ensureEntriesHeading(lines) {
+  let e = lines.findIndex((l) => ENTRIES_RE.test(l));
+  if (e !== -1) return e;
+  const attempt = lines.findIndex((l) => /^##\s+.*attempt log/i.test(l));
+  let at = attempt === -1 ? lines.length : regionEnd(lines, attempt);
+  while (at > 0 && !lines[at - 1].trim()) at--;
+  lines.splice(at, 0, '', '## 📝 Section Entries', '');
+  return lines.findIndex((l) => ENTRIES_RE.test(l));
+}
+
+function verdictEntryLines(entry) {
+  const out = [`### Section ${entry.section}`, '', `- Date: ${entry.date}`];
+  if (entry.hardest) out.push(`- Hardest: ${oneLine(entry.hardest)}`);
+  if (entry.duration) out.push(`- Duration: ${oneLine(entry.duration)}`);
+  for (const { q, a } of entry.answers) out.push(`- Q: "${oneLine(q)}" → A: "${oneLine(a)}"`);
+  out.push(`- Verdict: ${entry.verdict}`);
+  if (entry.lecture) out.push(`- Archived lecture: ${oneLine(entry.lecture)}`);
+  return out;
+}
+
+/** Put the watch-this flag under the section's reasoning trail, replacing an older one. */
+function addTrailWatch(lines, section, watch) {
+  let t = lines.findIndex((l) => TRAIL_RE.test(l));
+  if (t === -1) {
+    const e = lines.findIndex((l) => ENTRIES_RE.test(l));
+    let at = e === -1 ? lines.length : e;
+    while (at > 0 && !lines[at - 1].trim()) at--;
+    lines.splice(at, 0, '', '## 🗣️ Reasoning Trail', '');
+    t = at + 1;
+  }
+  let end = regionEnd(lines, t);
+  const key = sectionKey(section);
+  let h = -1;
+  for (let i = t + 1; i < end; i++) if (sectionHeadRe(key).test(lines[i])) { h = i; break; }
+  const flag = `⚠️ watch-this: ${oneLine(watch)}`;
+  if (h === -1) {
+    while (end > t + 1 && !lines[end - 1].trim()) end--;
+    lines.splice(end, 0, '', `### Section ${section}`, '', flag, '');
+    return;
+  }
+  let blockEnd = h + 1;
+  while (blockEnd < lines.length && !/^#{2,3}\s/.test(lines[blockEnd])) blockEnd++;
+  const block = lines.slice(h + 1, blockEnd);
+  const { preface, rounds } = splitRounds(block);
+  const keep = preface.filter((l) => !/watch-this/i.test(l));
+  keep.push(flag);
+  const rebuilt = [
+    '', ...keep, '',
+    ...rounds.flatMap((r) => [...r, '']).slice(0, -1),
+    '',
+  ];
+  lines.splice(h + 1, block.length, ...rebuilt);
+}
+
+/** Pure: return LEARNING-LOG.md text with the section entry for `entry`. */
+export function appendVerdict(text, entry) {
+  let src = text && text.trim()
+    ? text
+    : `---\ncourse: ${entry.slug}\nupdated: ${entry.date}\n---\n\n# Learning Log\n`;
+  src = src.replace(/^(---\n[\s\S]*?^updated:\s*).*$/m, `$1${entry.date}`);
+  const lines = src.replace(/\n+$/, '').split('\n');
+
+  const e = ensureEntriesHeading(lines);
+  const headRe = sectionHeadRe(sectionKey(entry.section));
+  let h = -1;
+  for (let i = e + 1; i < lines.length && !/^##\s/.test(lines[i]); i++) {
+    if (headRe.test(lines[i])) { h = i; break; }
+  }
+  const body = verdictEntryLines(entry);
+  if (h === -1) {
+    let at = regionEnd(lines, e);
+    while (at > e + 1 && !lines[at - 1].trim()) at--;
+    lines.splice(at, 0, '', ...body, '');
+  } else {
+    let end = h + 1;
+    while (end < lines.length && !/^#{2,3}\s/.test(lines[end])) end++;
+    while (end > h + 1 && !lines[end - 1].trim()) end--;
+    lines.splice(h, end - h, ...body, '');
+  }
+
+  if (entry.watch || /watch-this/i.test(entry.verdict)) {
+    const watch = entry.watch || normalizeVerdict(entry.verdict).watch;
+    if (watch) addTrailWatch(lines, entry.section, watch);
+  }
+
+  while (lines.length && !lines[lines.length - 1].trim()) lines.pop();
+  return { text: `${lines.join('\n').replace(/\n{3,}/g, '\n\n')}\n` };
+}
+
+/** Record the done-gate verdict; Professor is the only writer of LEARNING-LOG.md. */
+export function recordVerdict({
+  cwd, slug, section, hardest, answers, verdict, duration, lecture, date = todayISO(),
+}) {
+  if (!slug) throw new Error('Pass the course slug — verdict never guesses which course to write.');
+  const normalized = normalizeVerdict(verdict);
+  if (!oneLine(hardest)) throw new Error('Missing hardest — nothing was recorded.');
+  const cleaned = (Array.isArray(answers) ? answers : [])
+    .map((a) => (typeof a === 'string' ? { q: 'What was the hardest concept?', a } : a || {}))
+    .map((a) => ({ q: oneLine(a.q), a: oneLine(a.a) }))
+    .filter((a) => a.q && a.a);
+  if (!cleaned.length) throw new Error('Missing answers — nothing was recorded.');
+  const ctx = buildContext({ cwd, slug });
+  const target = section || ctx.section;
+  if (!target) throw new Error('No current section in COURSE.md — pass --section "N — Title".');
+  const path = ctx.learningLog;
+  const before = existsSync(path) ? readFileSync(path, 'utf-8') : '';
+  const { text } = appendVerdict(before, {
+    slug, section: target, date, duration, hardest, answers: cleaned,
+    verdict: normalized.verdict, watch: normalized.watch, lecture,
+  });
+  writeFileSync(path, text);
+  return { recorded: true, path, section: target, verdict: normalized.verdict, watch: normalized.watch };
+}
+
 function flagValue(args, name) {
   const i = args.indexOf(name);
   return i !== -1 && args[i + 1] !== undefined && !args[i + 1].startsWith('--') ? args[i + 1] : null;
 }
 
-const VALUE_FLAGS = ['--section', '--learner', '--asked', '--concept', '--evidence', '--watch', '--date'];
+const VALUE_FLAGS = [
+  '--section', '--learner', '--asked', '--concept', '--evidence', '--watch', '--date',
+  '--hardest', '--answers', '--verdict', '--duration', '--lecture',
+];
 
 function positionals(args) {
   const out = [];
@@ -197,6 +334,19 @@ export async function run({ args = [], cwd = process.cwd(), command = 'context'
       }
       return;
     }
+    if (command === 'verdict') {
+      // Same stdin-only rule as trail: the learner's words never appear inside a shell flag.
+      const fromStdin = args.includes('--stdin') ? JSON.parse(readFileSync(0, 'utf-8')) : {};
+      const f = (n) => fromStdin[n.slice(2)] ?? flagValue(args, n);
+      const r = recordVerdict({
+        cwd, slug, section: f('--section'), hardest: f('--hardest'), answers: f('--answers'),
+        verdict: f('--verdict'), duration: f('--duration'), lecture: f('--lecture'),
+        date: f('--date') || undefined,
+      });
+      if (json) console.log(JSON.stringify(r));
+      else console.log(style('success', `Recorded verdict "${r.verdict}" for Section ${r.section} in ${relative(cwd, r.path)}`));
+      return;
+    }
     const ctx = buildContext({ cwd, slug });
     if (json) { console.log(JSON.stringify(ctx, null, 2)); return; }
     console.log(`${ctx.title} (${ctx.slug}, ${ctx.kind}) — ${ctx.dir}`);

package/bin/commands/web.js

@@ -5,13 +5,13 @@
  * Legacy mode is the explicit opt-in (`--legacy` or `PROFESSOR_LEGACY=1`) and keeps the old
  * Anthropic/OpenAI fallback prompt. The server itself owns legacy-dev Vite startup (D-08).
  */
-import { existsSync, readFileSync, writeFileSync, readdirSync } from 'fs';
+import { existsSync, readFileSync, writeFileSync } from 'fs';
 import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
 import { createRequire } from 'module';
 import inquirer from 'inquirer';
 import ora from 'ora';
-import { buildPairingUrl } from './studio.js';
+import { buildPairingUrl, loopbackUrl, toLoopbackUrl } from './studio.js';
 import * as security from '../../web/security.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -297,13 +297,7 @@ export async function run({ args = [], style, startServerImpl } = {}) {
 
   process.env.PORT = positionalPort;
 
-  let defaultCourses = './courses';
-  if (existsSync('./courses')) {
-    if (readdirSync('./courses').length === 0) defaultCourses = './learning';
-  } else if (existsSync('./learning')) {
-    defaultCourses = './learning';
-  }
-  process.env.COURSES_DIR = process.env.COURSES_DIR || defaultCourses;
+  process.env.COURSES_DIR = process.env.COURSES_DIR || './learning';
 
   const token =
     rotatedToken ||
@@ -330,7 +324,11 @@ export async function run({ args = [], style, startServerImpl } = {}) {
     host: process.env.HOST,
     logBanner: false,
   });
-  const uiUrl = started?.uiUrl || `http://localhost:${expectedUiPort}`;
+  // Printed links use the IPv4 literal: `localhost` can resolve to `::1`, where another dev server
+  // may answer instead of this one (the server itself binds 127.0.0.1). Legacy dev is left alone
+  // because Vite owns that port.
+  const uiBase = started?.uiUrl || loopbackUrl(expectedUiPort);
+  const uiUrl = legacy && !isProduction ? uiBase : toLoopbackUrl(uiBase);
   const uiPort = (() => {
     try {
       return new URL(uiUrl).port || expectedUiPort;

package/bin/course-reader.js

@@ -1,7 +1,7 @@
 /**
  * Course reader — pure parsers for course files on disk.
  *
- * Reads `learning/{slug}/` (primary) and `courses/{slug}/` (legacy). Every
+ * Reads `learning/{slug}/`, the single course location. Every
  * function here is side-effect free apart from reading files, so Phase 31
  * (`studio`, `review`, `import`) can reuse the same shapes without going
  * through the CLI.
@@ -252,7 +252,7 @@ export function parseSections(content) {
   return parseListSections(region);
 }
 
-function parseCapstoneStatus(content, rowStatus) {
+export function parseCapstoneStatus(content, rowStatus) {
   const raw = metaValue(content, 'Capstone status');
   if (raw) {
     const lower = raw.toLowerCase();
@@ -488,10 +488,10 @@ export function resolveExercise(course, { lecture = null } = {}) {
 
 /**
  * Find every course directory on disk.
- * Scans `learning/*​/` first, then legacy `courses/*​/` (dedup by slug).
+ * Scans `learning/*​/` only — it is the single course location.
  * @param {string} cwd
- * @param {{ dir?: string }} [opts] `dir` overrides the roots (single course or parent)
- * @returns {{ slug: string, dir: string, location: 'learning'|'courses'|'custom' }[]}
+ * @param {{ dir?: string }} [opts] `dir` overrides the root (single course or parent)
+ * @returns {{ slug: string, dir: string, location: 'learning'|'custom' }[]}
  */
 export function findCourses(cwd, { dir } = {}) {
   if (dir) {
@@ -501,16 +501,7 @@ export function findCourses(cwd, { dir } = {}) {
     }
     return scanRoot(abs, 'custom');
   }
-  const results = [];
-  const seen = new Set();
-  for (const [name, location] of [['learning', 'learning'], ['courses', 'courses']]) {
-    for (const course of scanRoot(join(cwd, name), location)) {
-      if (seen.has(course.slug)) continue;
-      seen.add(course.slug);
-      results.push(course);
-    }
-  }
-  return results;
+  return scanRoot(join(cwd, 'learning'), 'learning');
 }
 
 function scanRoot(root, location) {

package/bin/platforms/_shared.js

@@ -1,9 +1,139 @@
-import { readFileSync, writeFileSync, mkdirSync, readdirSync, statSync, existsSync } from 'fs';
+import {
+  readFileSync,
+  writeFileSync,
+  mkdirSync,
+  readdirSync,
+  statSync,
+  existsSync,
+  copyFileSync,
+} from 'fs';
 import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
+/** Markers that delimit a plugin-managed region inside a learner-editable file. */
+export const BLOCK_START = '<!-- professor:start -->';
+export const BLOCK_END = '<!-- professor:end -->';
+
+/**
+ * Counter for one setup run: what was created or updated, what was already current, and how
+ * many files were backed up.
+ * @returns {{ updated: number, unchanged: number, backedUp: number, backedUpPaths: Set<string> }}
+ */
+export function createInstallRun() {
+  return { updated: 0, unchanged: 0, backedUp: 0, backedUpPaths: new Set() };
+}
+
+/**
+ * Save the content a write is about to replace, at most once per run per file.
+ * @param {string} dest
+ * @param {{ backedUp: number, backedUpPaths: Set<string> }} run
+ */
+function _backupOnce(dest, run) {
+  if (run.backedUpPaths.has(dest)) return;
+  copyFileSync(dest, `${dest}.bak`);
+  run.backedUpPaths.add(dest);
+  run.backedUp++;
+}
+
+/**
+ * Write a file the plugin owns: create it, leave it alone when it matches, otherwise back it up and
+ * replace it. This is what makes re-running setup refresh an upgrade.
+ * @param {string} dest
+ * @param {string} content
+ * @param {ReturnType<typeof createInstallRun>} run
+ * @param {string} [label] path shown in the log
+ * @returns {'created'|'updated'|'unchanged'}
+ */
+export function writeManagedFile(dest, content, run, label = dest) {
+  mkdirSync(dirname(dest), { recursive: true });
+
+  if (!existsSync(dest)) {
+    writeFileSync(dest, content);
+    run.updated++;
+    console.log(`  + ${label}`);
+    return 'created';
+  }
+
+  if (readFileSync(dest, 'utf-8') === content) {
+    run.unchanged++;
+    console.log(`  = ${label} (unchanged)`);
+    return 'unchanged';
+  }
+
+  _backupOnce(dest, run);
+  writeFileSync(dest, content);
+  run.updated++;
+  console.log(`  ~ ${label} (updated, backup saved)`);
+  return 'updated';
+}
+
+/**
+ * Refresh the marker-delimited Professor block inside a file the learner may also edit.
+ * Text outside the markers is preserved; a file without markers gets the block appended.
+ * @param {string} dest
+ * @param {string} blockContent
+ * @param {ReturnType<typeof createInstallRun>} run
+ * @param {string} [label]
+ * @returns {'created'|'updated'|'unchanged'}
+ */
+export function writeManagedBlock(dest, blockContent, run, label = dest) {
+  const block = `${BLOCK_START}\n${blockContent}\n${BLOCK_END}`;
+  mkdirSync(dirname(dest), { recursive: true });
+
+  if (!existsSync(dest)) {
+    writeFileSync(dest, `${block}\n`);
+    run.updated++;
+    console.log(`  + ${label}`);
+    return 'created';
+  }
+
+  const current = readFileSync(dest, 'utf-8');
+  const start = current.indexOf(BLOCK_START);
+  const end = start === -1 ? -1 : current.indexOf(BLOCK_END, start);
+  let next;
+  if (start !== -1 && end !== -1) {
+    next = current.slice(0, start) + block + current.slice(end + BLOCK_END.length);
+  } else {
+    next = `${current}${current.endsWith('\n') ? '\n' : '\n\n'}${block}\n`;
+  }
+
+  if (next === current) {
+    run.unchanged++;
+    console.log(`  = ${label} (unchanged)`);
+    return 'unchanged';
+  }
+
+  _backupOnce(dest, run);
+  writeFileSync(dest, next);
+  run.updated++;
+  console.log(`  ~ ${label} (updated, backup saved)`);
+  return 'updated';
+}
+
+/**
+ * True when the content is the skill document an older release wrote wholesale into a file.
+ * @param {string} content
+ * @returns {boolean}
+ */
+export function isLegacySkillDocument(content) {
+  const frontmatter = content.match(/^---\n([\s\S]*?)\n---/);
+  return !!frontmatter && /^name:\s*professor\s*$/m.test(frontmatter[1]);
+}
+
+/**
+ * One summary line per platform run.
+ * @param {string} platform
+ * @param {ReturnType<typeof createInstallRun>} run
+ */
+export function printInstallSummary(platform, run) {
+  console.log(
+    `✎ Setup summary (${platform}): ${run.updated} updated, ` +
+      `${run.unchanged} unchanged, ${run.backedUp} backed up.`
+  );
+}
+
 // Maps platform name → tool substitutions.
 // null means: strip the AskUserQuestion call and replace with plain inline text.
 export const TOOL_SUBSTITUTIONS = {
@@ -46,7 +176,9 @@ export function substituteTokens(content, platform) {
  */
 export function copySharedFiles(targetDir, platform) {
   const sharedDir = join(__dirname, '..', '..', 'shared');
-  _copyRecursive(sharedDir, targetDir, platform, true);
+  const run = createInstallRun();
+  _copyRecursive(sharedDir, targetDir, platform, true, run);
+  return run;
 }
 
 /**
@@ -54,23 +186,24 @@ export function copySharedFiles(targetDir, platform) {
  * By default, applies token substitution to .md/.js files.
  */
 export function copyDirectoryFiles(sourceDir, targetDir, platform, { substitute = true } = {}) {
-  _copyRecursive(sourceDir, targetDir, platform, substitute);
+  const run = createInstallRun();
+  _copyRecursive(sourceDir, targetDir, platform, substitute, run);
+  return run;
 }
 
-function _copyRecursive(src, dest, platform, substitute) {
+function _copyRecursive(src, dest, platform, substitute, run) {
   if (!existsSync(src)) return;
   const stat = statSync(src);
   if (stat.isDirectory()) {
-    if (!existsSync(dest)) mkdirSync(dest, { recursive: true });
     for (const file of readdirSync(src)) {
-      _copyRecursive(join(src, file), join(dest, file), platform, substitute);
+      _copyRecursive(join(src, file), join(dest, file), platform, substitute, run);
     }
-  } else if (!existsSync(dest)) {
+  } else {
     let content = readFileSync(src, 'utf-8');
     if (substitute && (src.endsWith('.md') || src.endsWith('.js'))) {
       content = substituteTokens(content, platform);
     }
-    writeFileSync(dest, content);
+    writeManagedFile(dest, content, run);
   }
 }
 
@@ -167,16 +300,18 @@ function _parseFrontmatter(content) {
 
 /**
  * Read every .md file from shared/commands/professor/, apply substituteTokens(),
- * then write per-platform command files into targetDir. Does NOT overwrite existing files.
+ * then write per-platform command files into targetDir.
  *
- * platform = 'gemini'   → writes targetDir/<slug>.toml
+ * platform = 'gemini'   → writes targetDir/<slug>.toml (arguments become {{args}})
  * platform = 'opencode' → writes targetDir/professor-<slug>.md
+ *
+ * @param {string} targetDir
+ * @param {'gemini'|'opencode'} platform
+ * @param {ReturnType<typeof createInstallRun>} [run]
  */
-export function generateCommandFiles(targetDir, platform) {
+export function generateCommandFiles(targetDir, platform, run = createInstallRun()) {
   const sharedDir = join(__dirname, '..', '..', 'shared', 'commands', 'professor');
-  if (!existsSync(sharedDir)) return;
-
-  mkdirSync(targetDir, { recursive: true });
+  if (!existsSync(sharedDir)) return run;
 
   for (const file of readdirSync(sharedDir)) {
     if (!file.endsWith('.md')) continue;
@@ -184,28 +319,19 @@ export function generateCommandFiles(targetDir, platform) {
 
     let raw = readFileSync(join(sharedDir, file), 'utf-8');
     raw = substituteTokens(raw, platform);
+    if (platform === 'gemini') raw = raw.replaceAll('$ARGUMENTS', '{{args}}');
     const { description, body } = _parseFrontmatter(raw);
 
     if (platform === 'gemini') {
       const filename = `${stem}.toml`;
-      const destPath = join(targetDir, filename);
-      if (existsSync(destPath)) {
-        console.log(`  ↔ ${filename} (already exists)`);
-        continue;
-      }
       const output = `description = "${description}"\n\nprompt = """\n${body}"""\n`;
-      writeFileSync(destPath, output);
-      console.log(`  + ${filename}`);
+      writeManagedFile(join(targetDir, filename), output, run, filename);
     } else if (platform === 'opencode') {
       const filename = `professor-${stem}.md`;
-      const destPath = join(targetDir, filename);
-      if (existsSync(destPath)) {
-        console.log(`  ↔ ${filename} (already exists)`);
-        continue;
-      }
       const output = `---\ndescription: ${description}\nsubtask: true\n---\n\n${body}`;
-      writeFileSync(destPath, output);
-      console.log(`  + ${filename}`);
+      writeManagedFile(join(targetDir, filename), output, run, filename);
     }
   }
+
+  return run;
 }

package/bin/platforms/claude.js

@@ -1,7 +1,12 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync } from 'fs';
+import { existsSync, mkdirSync, readFileSync, readdirSync } from 'fs';
 import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
-import { substituteTokens } from './_shared.js';
+import {
+  substituteTokens,
+  createInstallRun,
+  writeManagedFile,
+  printInstallSummary,
+} from './_shared.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const PLUGIN_DIR = join(__dirname, '..', '..');
@@ -25,6 +30,7 @@ export async function install(scope = 'local') {
     : join(process.cwd(), '.claude');
 
   const label = scope === 'global' ? '~/.claude/' : '.claude/';
+  const run = createInstallRun();
 
   if (!existsSync(base)) {
     mkdirSync(base, { recursive: true });
@@ -32,67 +38,42 @@ export async function install(scope = 'local') {
   }
 
   // 1. agents/ — one .md file per agent
-  const agentsDestDir = join(base, 'agents');
-  mkdirSync(agentsDestDir, { recursive: true });
-  const agentsSrcDir = join(PLUGIN_DIR, 'shared', 'agents');
   console.log('✓ Installing agents...');
+  const agentsSrcDir = join(PLUGIN_DIR, 'shared', 'agents');
+  const agentsDestDir = join(base, 'agents');
   for (const file of readdirSync(agentsSrcDir)) {
     if (!file.endsWith('.md')) continue;
-    const dest = join(agentsDestDir, file);
-    if (existsSync(dest)) {
-      console.log(`  ↔ agents/${file} (already exists)`);
-    } else {
-      const content = substituteTokens(readFileSync(join(agentsSrcDir, file), 'utf-8'), 'claude');
-      writeFileSync(dest, content);
-      console.log(`  + agents/${file}`);
-    }
+    const content = substituteTokens(readFileSync(join(agentsSrcDir, file), 'utf-8'), 'claude');
+    writeManagedFile(join(agentsDestDir, file), content, run, `agents/${file}`);
   }
 
   // 2. commands/professor/ — one .md file per command
-  const commandsDestDir = join(base, 'commands', 'professor');
-  mkdirSync(commandsDestDir, { recursive: true });
-  const commandsSrcDir = join(PLUGIN_DIR, 'shared', 'commands', 'professor');
   console.log('✓ Installing commands...');
+  const commandsSrcDir = join(PLUGIN_DIR, 'shared', 'commands', 'professor');
+  const commandsDestDir = join(base, 'commands', 'professor');
   for (const file of readdirSync(commandsSrcDir)) {
     if (!file.endsWith('.md')) continue;
-    const dest = join(commandsDestDir, file);
-    if (existsSync(dest)) {
-      console.log(`  ↔ commands/professor/${file} (already exists)`);
-    } else {
-      const content = substituteTokens(readFileSync(join(commandsSrcDir, file), 'utf-8'), 'claude');
-      writeFileSync(dest, content);
-      console.log(`  + commands/professor/${file}`);
-    }
+    const content = substituteTokens(readFileSync(join(commandsSrcDir, file), 'utf-8'), 'claude');
+    writeManagedFile(join(commandsDestDir, file), content, run, `commands/professor/${file}`);
   }
 
   // 3. hooks/ — pre-compact.js
-  const hooksDestDir = join(base, 'hooks');
-  mkdirSync(hooksDestDir, { recursive: true });
   const hooksSrcDir = join(PLUGIN_DIR, 'shared', 'hooks');
   if (existsSync(hooksSrcDir)) {
     console.log('✓ Installing hooks...');
+    const hooksDestDir = join(base, 'hooks');
     for (const file of readdirSync(hooksSrcDir)) {
-      const dest = join(hooksDestDir, file);
-      if (existsSync(dest)) {
-        console.log(`  ↔ hooks/${file} (already exists)`);
-      } else {
-        writeFileSync(dest, readFileSync(join(hooksSrcDir, file), 'utf-8'));
-        console.log(`  + hooks/${file}`);
-      }
+      const content = readFileSync(join(hooksSrcDir, file), 'utf-8');
+      writeManagedFile(join(hooksDestDir, file), content, run, `hooks/${file}`);
     }
   }
 
   // 4. skills/professor/ — SKILL.md
-  const skillsDestDir = join(base, 'skills', 'professor');
-  mkdirSync(skillsDestDir, { recursive: true });
   const skillSrc = join(PLUGIN_DIR, 'shared', 'SKILL.md');
-  const skillDest = join(skillsDestDir, 'SKILL.md');
-  if (existsSync(skillDest)) {
-    console.log('  ↔ skills/professor/SKILL.md (already exists)');
-  } else {
-    writeFileSync(skillDest, readFileSync(skillSrc, 'utf-8'));
-    console.log('  + skills/professor/SKILL.md');
-  }
+  const skillDest = join(base, 'skills', 'professor', 'SKILL.md');
+  writeManagedFile(skillDest, readFileSync(skillSrc, 'utf-8'), run, 'skills/professor/SKILL.md');
+
+  printInstallSummary('Claude Code', run);
 
   console.log(`
 ✅ Setup complete for Claude Code!