sdocs-dev 1.15.0 → 1.18.0

package/lib/library-commands.js

@@ -30,16 +30,8 @@ function libraryDisable() {
 function libraryStatus() {
   const s = store.loadState();
   const idx = store.loadIndex();
-  const last = s.lastScanAt ? new Date(s.lastScanAt).toISOString() : 'never';
   console.log(`library: ${s.enabled === false ? 'disabled' : 'enabled'}`);
   console.log(`entries: ${idx.entries.length}`);
-  console.log(`last scan: ${last}`);
-}
-
-function libraryRebuild() {
-  console.log('library: rebuilding...');
-  const result = libIndex.rebuild();
-  console.log(`library: scanned ${result.scanned}, added ${result.added}, updated ${result.updated}`);
 }
 
 // Walk up from a directory looking for `.git/`. Falls back to the start
@@ -114,7 +106,7 @@ function libraryLs(opts) {
     const tags = libIndex.tagsUnderPrefix(scope);
     if (!tags.length) {
       console.log(`no tagged markdown files indexed under ${scope} yet`);
-      console.log(`(tip: run \`sdoc library rebuild\` if you expected results, or open a file with \`sdoc <file> +tag\` to start tagging)`);
+      console.log(`(tip: open a file with \`sdoc <file> +tag\` to add and tag it)`);
       return;
     }
     console.log(`most frequent tags for tagged markdown files under ${scope} (tag - count):`);
@@ -132,7 +124,7 @@ function libraryLs(opts) {
   const entries = entriesUnderScope(scope);
   if (!entries.length) {
     console.log(`library has no markdown indexed under ${scope} yet`);
-    console.log(`(tip: run \`sdoc library rebuild\` to scan, or open a file with \`sdoc <file>\` to index it)`);
+    console.log(`(tip: open a file with \`sdoc <file>\` to add it)`);
     return;
   }
 
@@ -209,8 +201,8 @@ async function libraryOpen() {
   const { agentUrl } = await libServer.createServer();
   const pageUrl = `${siteUrl}/library?agent=${encodeURIComponent(agentUrl)}`;
   console.log(`library: ${pageUrl}`);
-  console.log(`library: ${idx.entries.length} entries indexed` + (state.enabled === false ? ' (scanning disabled)' : ''));
-  if (!idx.entries.length) console.log('library: click "rescan" in the UI to walk your home for markdown.');
+  console.log(`library: ${idx.entries.length} entries indexed` + (state.enabled === false ? ' (indexing disabled)' : ''));
+  if (!idx.entries.length) console.log('library: open a file with `sdoc <file>` to add it.');
   ensureAutostart();
   console.log(`library: agent at ${agentUrl} (ctrl-c to stop)`);
   openBrowser(pageUrl);
@@ -263,7 +255,6 @@ async function libraryCommand(opts) {
     case 'enable':   libraryEnable();        break;
     case 'disable':  libraryDisable();       break;
     case 'status':   libraryStatus();        break;
-    case 'rebuild':  libraryRebuild();       break;
     case 'autostart': {
       const action = (opts.extra || '').toLowerCase();
       if (action === 'enable')       autostartEnable();
@@ -278,7 +269,7 @@ async function libraryCommand(opts) {
     }
     default:
       console.error(`sdoc library: unknown subcommand "${sub}"`);
-      console.error('usage: sdoc library [ls|enable|disable|status|rebuild|autostart|help]');
+      console.error('usage: sdoc library [ls|enable|disable|status|autostart|help]');
       process.exit(1);
   }
 }
@@ -300,7 +291,7 @@ function tapOpen(opts) {
 
 module.exports = {
   libraryCommand,
-  libraryEnable, libraryDisable, libraryStatus, libraryRebuild, libraryOpen,
+  libraryEnable, libraryDisable, libraryStatus, libraryOpen,
   libraryLs, libraryHelp,
   resolveProjectRoot, resolveLsScope, entriesUnderScope,
   tapOpen,

package/lib/library-scan.js

@@ -15,18 +15,13 @@ const paths     = require('./library-paths');
 const DEFAULT_MAX_SIZE = 1 * 1024 * 1024;
 
 const DIRNAME_BLOCKLIST = new Set([
-  'node_modules',
   '.git',
   '.svn',
   '.hg',
-  'dist',
-  'build',
-  'vendor',
   '.venv',
   '.next',
   '.cache',
   '__pycache__',
-  'target',
   '.gradle',
   '.idea',
   '.vscode',
@@ -46,6 +41,19 @@ const DIRNAME_BLOCKLIST = new Set([
   '.password-store',
 ]);
 
+// Directories skipped during scanning traversal for speed, but NOT blocked
+// from path-gating when opening an explicitly indexed file.
+const SCAN_SKIP_DIRNAMES = new Set([
+  'assets',
+  'graphify',
+  'node_modules',
+  'vendor',
+  'target',
+  'dist',
+  'build',
+  'venv',
+]);
+
 // File basenames that should never make it into the library, regardless
 // of which directory they live in or what extension they carry. Most of
 // these don't have a markdown extension and so the existing extension
@@ -129,8 +137,10 @@ function deniedByPattern(absPath) {
 }
 
 function shouldSkipDir(absDir, base, skipSet, exemptRoots) {
-  if (base.startsWith('.') && base !== '.' && base !== '..') return true;
+  // Exempt .sdocs so AI coding agent markdown artifacts are indexed
+  if (base.startsWith('.') && base !== '.' && base !== '..' && base !== '.sdocs') return true;
   if (DIRNAME_BLOCKLIST.has(base)) return true;
+  if (SCAN_SKIP_DIRNAMES.has(base)) return true;
   if (skipSet.has(absDir)) return true;
   // Skip ephemeral paths during descent unless we're inside a root that
   // the caller explicitly named (in which case they want it scanned).

package/lib/library-server.js

@@ -35,9 +35,8 @@ try {
 //   2. The deny-pattern list (SSH keys, .env, credentials.{json,...}
 //      and anything under .ssh/.aws/.gnupg/...).
 //   3. Library-membership: the real path must appear in the index.
-//      The index is what the user has explicitly opened with sdoc or
-//      placed under a scanned root; arbitrary paths outside that set
-//      are refused.
+//      The index contains files the user explicitly opened with sdoc;
+//      arbitrary paths outside that set are refused.
 //
 // Returns { ok: true, realPath } on pass, { ok: false, reason, status }
 // on refusal. Caller picks the HTTP status from `status`.
@@ -295,12 +294,6 @@ function createServer({ port } = {}) {
         return;
       }
 
-      if (req.method === 'POST' && route === '/api/library/rescan') {
-        const result = libIndex.scanAndIndex();
-        sendJson(res, 200, result);
-        return;
-      }
-
       // Serve the current contents of a local file. The editor page
       // uses this to refresh content after the URL-hash snapshot goes
       // stale (e.g. after the user edited tags then reloaded). Gated
@@ -319,9 +312,8 @@ function createServer({ port } = {}) {
       }
 
       // Re-index a single file. Called by the editor page after a Bridge
-      // save so the library catches up immediately (instead of waiting
-      // for the next manual scan). Pure read-then-index; never writes
-      // the file the path points at.
+      // save so the library catches up immediately. Pure read-then-index;
+      // never writes the file the path points at.
       if (req.method === 'POST' && route === '/api/library/reindex') {
         const body = await readBody(req);
         const filePath = body && body.path;

package/lib/setup.js

@@ -1,24 +1,30 @@
 // `sdoc setup`, `sdoc refresh`, `sdoc auto-update`, and the implicit
-// post-command refresh that keeps agent files in sync as new sdoc
+// post-command refresh that keeps the SmallDocs skill current as new sdoc
 // versions ship.
 //
-// runSetup: first-run interactive flow. Detects agent configs, writes
-//   the block into the ones the user agrees to. Pass dryRun:true to
-//   preview what would be written without touching any file or state.
-// runRefresh: unconditional refresh of every agent file that already
-//   has a recognised block.
+// runSetup: first-run interactive flow. Detects installed agents, installs
+//   the skill (canonical copy + symlinks), strips legacy blocks. Pass
+//   dryRun:true to preview without touching anything.
+// runRefresh: unconditional refresh of the canonical skill + symlinks.
 // runAutoUpdateSubcommand: flips state.autoInstallUpdates.
 // maybeAutoRefresh: called after every successful command. Quiet, only
-//   touches files whose existing block we already manage.
+//   rewrites the canonical skill when its version is stale.
 
-const os = require('os');
+const os   = require('os');
 const path = require('path');
+const fs   = require('fs');
 const readline = require('readline');
 
 const {
-  AGENT_BLOCK_VERSION,
-  AGENT_BLOCK_BODY,
-  formatAgentBlock,
+  SKILL_VERSION,
+  SKILL_BODY,
+  SKILL_NAME,
+  formatSkill,
+  canonicalSkillFile,
+  canonicalSkillDir,
+  legacyBlockTargets,
+  findBookendedBlock,
+  findLegacyBlock,
   compareVersions,
   readSetupState,
   writeSetupState,
@@ -28,11 +34,12 @@ const {
 const { upgradeCommand } = require('./update-check');
 
 const {
-  detectAgents,
-  fileHasBlock,
-  writeBookendedBlock,
-  refreshAllAgentFiles,
-  printRefreshSummary,
+  detectSkillAgents,
+  hasSetupEvidence,
+  syncAgentSkill,
+  syncChanged,
+  toImplicitResults,
+  printSyncSummary,
 } = require('./agent-files');
 
 const { VERSION, AGENT_CHANGES_URL } = require('./constants');
@@ -59,18 +66,56 @@ async function askAutoInstallConsent() {
 }
 
 async function askAutoRefreshConsent() {
-  console.log('\nKeep this block updated on future sdoc upgrades?');
+  console.log('\nKeep this skill updated on future sdoc upgrades?');
   console.log('');
-  console.log('When sdoc adds a feature we sometimes update this section so');
-  console.log('your agent learns about it. Each time the block changes we');
-  console.log(`print a notice with a link to ${AGENT_CHANGES_URL}`);
-  console.log('showing the exact delta - the new wording, and why it changed.');
+  console.log('When sdoc adds a feature we sometimes update the skill so your');
+  console.log('agent learns about it. Each change prints a notice with a link to');
+  console.log(`${AGENT_CHANGES_URL} showing the exact delta - the new wording, and why.`);
   console.log('');
   console.log('Re-run `sdoc setup` any time to change this.\n');
   const a = await ask('Enable? [Y/n] ');
   return !a || a === 'y' || a === 'yes';
 }
 
+// Preview what setup would do: print the skill, the symlinks it would create,
+// the agents covered by the canonical copy, and any legacy blocks it would
+// strip. Touches no file and writes no state.
+function dryRunPreview() {
+  const home = os.homedir();
+  const env = process.env;
+  const skillPath = canonicalSkillFile(home);
+  console.log(`--- ${skillPath} ---`);
+  console.log(formatSkill(SKILL_VERSION));
+
+  const detected = detectSkillAgents(home, env);
+  const linked = detected.filter(a => !a.universal);
+  const universal = detected.filter(a => a.universal);
+
+  if (universal.length) {
+    console.log('\nCovered by the canonical copy (~/.agents/skills, no symlink needed):');
+    for (const a of universal) console.log(`  ${a.displayName}`);
+  }
+  if (linked.length) {
+    console.log('\nSymlinks to create (<agent skills dir> -> canonical):');
+    for (const a of linked) console.log(`  ${path.join(a.dir, SKILL_NAME)} -> ${canonicalSkillDir(home)}`);
+  }
+  if (detected.length === 0) {
+    console.log('\nNo coding-agent configs detected. The canonical skill is still written');
+    console.log('so any agent that discovers ~/.agents/skills picks it up.');
+  }
+
+  const wouldStrip = [];
+  for (const t of legacyBlockTargets(home, env)) {
+    let content;
+    try { content = fs.readFileSync(t.file, 'utf-8'); } catch (_) { continue; }
+    if (findBookendedBlock(content) || findLegacyBlock(content)) wouldStrip.push(t.file);
+  }
+  if (wouldStrip.length) {
+    console.log('\nLegacy SmallDocs blocks to remove:');
+    for (const f of wouldStrip) console.log(`  ${f}`);
+  }
+}
+
 async function runSetup({ force = false, yes = false, dryRun = false } = {}) {
   if (!force) {
     if (!process.stdout.isTTY || !process.stdin.isTTY) return;
@@ -79,143 +124,67 @@ async function runSetup({ force = false, yes = false, dryRun = false } = {}) {
   }
 
   // ── --yes (non-interactive) path ───────────────────────────
-  // Pulled out of the detection branch so this is the SINGLE place that
-  // handles every --yes case: fresh install, old block (upgrade), legacy
-  // open-marker (migration), already-current (no-op), no agents at all.
-  // Idempotent by design - an agent or user can re-paste the install prompt
-  // any number of times and the result is a current block in every detected
-  // config, or a clean "nothing to do".
   if (yes) {
-    // ── --dry-run (preview only) path ─────────────────────────────────────
-    // Prints each file path and the block that would be written, then exits
-    // without touching any file or mutating setup state. Must return before
-    // the write steps below.
-    if (dryRun) {
-      const toWrite = detectAgents().filter(t => !fileHasBlock(t.filePath));
-      if (toWrite.length === 0) {
-        console.log('All SDocs agent blocks already at current version. Nothing to do.');
-        return;
-      }
-      for (const t of toWrite) {
-        console.log(`--- ${t.filePath} ---`);
-        console.log(formatAgentBlock(AGENT_BLOCK_VERSION, AGENT_BLOCK_BODY));
-      }
-      return;
-    }
+    if (dryRun) { dryRunPreview(); return; }
 
-    // Step 1: refresh any existing outdated / legacy blocks. This is what
-    // closes the gap where re-running setup --yes used to silently no-op
-    // on a stale install.
-    const refreshResults = refreshAllAgentFiles();
-    const refreshedFiles = refreshResults.filter(r => r.changed).map(r => r.path);
-    if (refreshResults.some(r => r.changed)) printRefreshSummary(refreshResults);
-
-    // Step 2: any agent whose config dir exists but doesn't yet have a
-    // block gets one written. Re-detect after refresh because the refresh
-    // step may have flipped some files from "needs block" to "has block".
-    const stillMissing = detectAgents().filter(t => !fileHasBlock(t.filePath));
-    const writtenTo = [];
-    for (const t of stillMissing) {
-      try { writeBookendedBlock(t.filePath); writtenTo.push(t.filePath); console.log(`✓ ${t.name}: ${t.filePath}`); }
-      catch (e) { console.error(`✗ ${t.name}: ${e.message}`); }
+    const result = syncAgentSkill({});
+    const changed = syncChanged(result);
+    const detected = detectSkillAgents(os.homedir(), process.env);
+
+    if (changed || result.errors.length) {
+      printSyncSummary(result);
     }
+    if (result.errors.length) return;
 
-    const affected = [...new Set([...writtenTo, ...refreshedFiles])];
-
-    if (affected.length === 0) {
-      const anyAgentDir = detectAgents().length > 0;
-      writeSetupState({
-        setupCompleted: new Date().toISOString(),
-        writtenTo: [], declined: !anyAgentDir,
-        autoRefreshAgentFiles: anyAgentDir,
-        autoInstallUpdates: false,
-        lastRunVersion: VERSION,
-      });
-      if (anyAgentDir) {
-        console.log('All SDocs agent blocks already at current version. Nothing to do.');
+    if (!changed) {
+      if (detected.length > 0) {
+        console.log('SmallDocs skill already at current version. Nothing to do.');
       } else {
-        console.log('No coding-agent configs detected. Nothing to write.');
-        console.log('Re-run `sdoc setup` (interactive) if you want to include opencode.');
+        console.log('No coding-agent configs detected. The canonical skill is at');
+        console.log('~/.agents/skills/smalldocs/SKILL.md; any agent that discovers');
+        console.log('~/.agents/skills will pick it up.');
       }
-      return;
     }
 
     writeSetupState({
       setupCompleted: new Date().toISOString(),
-      writtenTo: affected, declined: false,
+      writtenTo: changed ? [canonicalSkillFile(os.homedir())] : [],
+      declined: false,
       autoRefreshAgentFiles: true,
       autoInstallUpdates: false,
       lastRunVersion: VERSION,
     });
-    const n = affected.length;
-    const verb = writtenTo.length && refreshedFiles.length
-      ? 'Wrote/refreshed'
-      : (writtenTo.length ? 'Wrote' : 'Refreshed');
-    console.log(`\nDone. ${verb} SDocs block in ${n} ${n === 1 ? 'file' : 'files'}.`);
     return;
   }
 
-  const detected = detectAgents().filter(t => !fileHasBlock(t.filePath));
-
-  if (detected.length === 0) {
-    const opencodeAlreadyDone = fileHasBlock(path.join(os.homedir(), '.config', 'opencode', 'AGENTS.md'));
-    if (opencodeAlreadyDone) {
-      writeSetupState({
-        setupCompleted: new Date().toISOString(),
-        writtenTo: [], declined: false,
-        autoRefreshAgentFiles: true, autoInstallUpdates: false,
-        lastRunVersion: VERSION,
-      });
-      console.log('\nSDocs is already set up in all detected agent configs. Nothing to do.');
-      return;
-    }
-    console.log('\n✨─────── SDocs setup ───────✨');
-    console.log('First run only - wire SDocs into your CLI coding agents.\n');
-    console.log('No coding-agent configs detected.');
-    const a = await ask('Do you use opencode? [y/N] ');
-    const writtenTo = [];
-    let autoRefresh = false;
-    let autoInstall = false;
-    if (a === 'y' || a === 'yes') {
-      const target = path.join(os.homedir(), '.config', 'opencode', 'AGENTS.md');
-      try { writeBookendedBlock(target); writtenTo.push(target); console.log(`✓ Wrote SDocs section to ${target}`); }
-      catch (e) { console.error(`Failed to write ${target}: ${e.message}`); }
-      autoRefresh = await askAutoRefreshConsent();
-      autoInstall = await askAutoInstallConsent();
-      console.log('Done. Run `sdoc setup` any time to revisit.');
-    } else {
-      console.log('Skipped. Run `sdoc setup` any time to revisit.');
-    }
-    writeSetupState({
-      setupCompleted: new Date().toISOString(),
-      writtenTo, declined: writtenTo.length === 0,
-      autoRefreshAgentFiles: autoRefresh,
-      autoInstallUpdates: autoInstall,
-      lastRunVersion: VERSION,
-    });
-    return;
+  // ── interactive path ───────────────────────────────────────
+  const home = os.homedir();
+  const detected = detectSkillAgents(home, process.env);
+
+  console.log('\n\u2728─────── SmallDocs setup ───────\u2728');
+  console.log('Install the SmallDocs skill so your coding agents know `sdoc`.\n');
+
+  if (detected.length > 0) {
+    console.log('Detected: ' + detected.map(a => a.displayName).join(', '));
+    console.log('\nWill write the skill to ~/.agents/skills/smalldocs/SKILL.md.');
+    console.log('Agents using that universal location read it directly; other');
+    console.log('detected agents receive a symlink in their skills directory.');
+  } else {
+    console.log('No coding-agent configs detected. Setup still writes the canonical');
+    console.log('skill at ~/.agents/skills/smalldocs/SKILL.md, which any agent that');
+    console.log('discovers ~/.agents/skills will pick up.');
   }
-
-  console.log('\n✨─────── SDocs setup ───────✨');
-  console.log('First run only - wire SDocs into your CLI coding agents.\n');
-  console.log('Detected: ' + detected.map(t => t.name).join(', '));
-  console.log('\nWill append a short SDocs section to:');
-  for (const t of detected) console.log('  ' + t.filePath);
-  console.log('\nThese files are loaded into every conversation across all your');
-  console.log('projects, so SDocs becomes available no matter where you\'re working.');
-  console.log('');
-  console.log('You can ask your agent things like:');
+  console.log('\nYou can ask your agent things like:');
   console.log('  "write up the plan and sdoc it to me"');
   console.log('  "explain async/await to me in a sdoc"');
   console.log('  "draft the release notes as a sdoc I can share"');
-  console.log('');
-  console.log('This is the best way to work with SDocs');
-  const RULE = '═'.repeat(36);
-  console.log(`\n═══════════ Block to add ═══════════`);
-  console.log(AGENT_BLOCK_BODY.trim());
+
+  const RULE = '\u2550'.repeat(36);
+  console.log(`\n${RULE} Skill body ${RULE}`);
+  console.log(SKILL_BODY.trim());
   console.log(RULE);
 
-  const a = await ask('\nAdd to all? [Y/n/skip] ');
+  const a = await ask('\nInstall? [Y/n/skip] ');
   const skipped = a === 'skip' || (a && a !== 'y' && a !== 'yes');
   if (skipped) {
     writeSetupState({
@@ -228,18 +197,18 @@ async function runSetup({ force = false, yes = false, dryRun = false } = {}) {
     return;
   }
 
-  const writtenTo = [];
-  for (const t of detected) {
-    try { writeBookendedBlock(t.filePath); writtenTo.push(t.filePath); console.log(`✓ ${t.name}: ${t.filePath}`); }
-    catch (e) { console.error(`✗ ${t.name}: ${e.message}`); }
-  }
+  const result = syncAgentSkill({});
+  const changed = syncChanged(result);
+  if (changed || result.errors.length) printSyncSummary(result);
+  if (result.errors.length) return;
 
-  const autoRefresh = writtenTo.length > 0 ? await askAutoRefreshConsent() : false;
-  const autoInstall = writtenTo.length > 0 ? await askAutoInstallConsent() : false;
+  const autoRefresh = await askAutoRefreshConsent();
+  const autoInstall = await askAutoInstallConsent();
 
   writeSetupState({
     setupCompleted: new Date().toISOString(),
-    writtenTo, declined: false,
+    writtenTo: changed ? [canonicalSkillFile(home)] : [],
+    declined: false,
     autoRefreshAgentFiles: autoRefresh,
     autoInstallUpdates: autoInstall,
     lastRunVersion: VERSION,
@@ -247,25 +216,27 @@ async function runSetup({ force = false, yes = false, dryRun = false } = {}) {
   console.log('\nDone. Run `sdoc setup` any time to revisit.');
 }
 
-// Auto-refresh existing agent files when the binary version is newer than the
-// version that last ran. No prompt: the user already consented during setup.
-// Bails on downgrades (block version > shipped version), errors, or partial
-// failures (lastRunVersion only advances when every changed file succeeded).
+// Auto-refresh when the binary version is newer than the version that last
+// ran. No prompt: the user already consented during setup. Rewrites only the
+// canonical skill (every symlink follows); re-checks symlinks and re-strips
+// any block that reappeared. Bails on downgrades or errors.
 async function maybeAutoRefresh() {
   if (process.env.SDOCS_NO_REFRESH) return;
   let state = readSetupState();
 
-  // Implicit-consent migration for users who have a recognised SDocs block in
-  // an agent file but no `~/.sdocs/setup.json`. This is the pre-1.5.0 install
-  // path. `refreshContent` only signals `changed` for a block whose exact
-  // shape we wrote (legacy JoshInLisbon terminator, or our bookend markers);
-  // anything else is left untouched, so a user who deleted the block or
-  // hand-edited it doesn't get state silently created.
+  // Implicit-consent migration for users who have evidence of a prior setup
+  // (a skill file on disk, or a recognised always-on block in one of the
+  // historical config files) but no ~/.sdocs/setup.json. A brand-new user has
+  // no evidence and is left for the interactive first-run prompt instead, so
+  // nothing is auto-installed without consent.
   if (!state) {
-    const results = refreshAllAgentFiles();
-    const next = implicitConsentState(results, VERSION);
+    if (!hasSetupEvidence(os.homedir(), process.env)) return;
+    const result = syncAgentSkill({});
+    if (result.errors.length) { printSyncSummary(result); return; }
+    if (!syncChanged(result)) return;
+    const next = implicitConsentState(toImplicitResults(result), VERSION);
     if (!next) return;
-    printRefreshSummary(results);
+    printSyncSummary(result);
     writeSetupState(next);
     return;
   }
@@ -273,53 +244,37 @@ async function maybeAutoRefresh() {
   if (!state.autoRefreshAgentFiles) return;
   if (compareVersions(VERSION, state.lastRunVersion) <= 0) return;
 
-  const results = refreshAllAgentFiles();
-  const anyChanged = results.some(r => r.changed);
-  if (anyChanged) printRefreshSummary(results);
+  const result = syncAgentSkill({});
+  if (syncChanged(result) || result.errors.length) printSyncSummary(result);
 
-  const anyError = results.some(r => r.error);
-  if (!anyError) {
+  if (!result.errors.length) {
     writeSetupState({ ...state, lastRunVersion: VERSION });
   }
 }
 
-// `sdoc refresh` — unconditional agent-block refresh. Useful for users whose
-// setup.json was never written (pre-1.5.0 installs) or has been deleted, and
-// for agents that want to trigger the migration explicitly without going
-// through the interactive setup flow.
+// `sdoc refresh` - unconditional skill refresh. Useful when setup.json was
+// never written or has been deleted, or to force the migration explicitly.
 async function runRefresh() {
   const existing = readSetupState();
-  const results = refreshAllAgentFiles();
-  const changed = results.filter(r => r.changed);
-  const errors  = results.filter(r => r.error);
-  const current = results.filter(r => r.reason === 'current');
-  const blocksPresent = changed.length + current.length;
-
-  printRefreshSummary(results);
-
-  if (changed.length === 0 && errors.length === 0) {
-    if (blocksPresent === 0) {
-      console.log('No SDocs blocks found in any agent file. Run `sdoc setup` to add one.');
-      return;
-    }
-    console.log(`All SDocs agent blocks already at v${AGENT_BLOCK_VERSION}.`);
-  }
+  const result = syncAgentSkill({});
+  printSyncSummary(result);
 
-  if (errors.length > 0) return;
-
-  if (blocksPresent === 0 && !existing) return;
+  if (!syncChanged(result) && !result.errors.length) {
+    console.log(`SmallDocs skill already at v${SKILL_VERSION}.`);
+  }
+  if (result.errors.length) return;
 
   writeSetupState({
-    setupCompleted: existing?.setupCompleted || new Date().toISOString(),
-    writtenTo: [...changed, ...current].map(r => r.path),
+    setupCompleted: existing && existing.setupCompleted || new Date().toISOString(),
+    writtenTo: [canonicalSkillFile(os.homedir())],
     declined: false,
     autoRefreshAgentFiles: existing ? existing.autoRefreshAgentFiles !== false : true,
-    autoInstallUpdates: existing?.autoInstallUpdates ?? false,
+    autoInstallUpdates: existing && existing.autoInstallUpdates != null ? existing.autoInstallUpdates : false,
     lastRunVersion: VERSION,
   });
 }
 
-// `sdoc auto-update on|off|status` — flips state.autoInstallUpdates.
+// `sdoc auto-update on|off|status` - flips state.autoInstallUpdates.
 function runAutoUpdateSubcommand(arg) {
   let state = readSetupState();
   if (!state) {
@@ -328,12 +283,12 @@ function runAutoUpdateSubcommand(arg) {
   }
   if (arg === 'on') {
     writeSetupState({ ...state, autoInstallUpdates: true });
-    console.log('✓ Auto-install of sdoc updates: on');
+    console.log('\u2713 Auto-install of sdoc updates: on');
     return;
   }
   if (arg === 'off') {
     writeSetupState({ ...state, autoInstallUpdates: false });
-    console.log('✓ Auto-install of sdoc updates: off');
+    console.log('\u2713 Auto-install of sdoc updates: off');
     return;
   }
   console.log(`Auto-install of sdoc updates: ${state.autoInstallUpdates ? 'on' : 'off'}`);
@@ -344,6 +299,7 @@ module.exports = {
   ask,
   askAutoInstallConsent,
   askAutoRefreshConsent,
+  dryRunPreview,
   runSetup,
   runRefresh,
   runAutoUpdateSubcommand,