wize-dev-kit 0.26.0 → 0.27.2

package/tools/installer/install-plan.js

@@ -0,0 +1,136 @@
+// Pure decisions behind `wize-dev-kit install` / `uninstall`: where the kit
+// may be installed, what an existing project.toml means for a re-run, how the
+// project and user names are derived and when the baseline runs. wize-cli.js
+// runs main() at load time, so everything testable lives here.
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { gitContext, configUserName } = require('./git-context.js');
+const { findProjectRoot, findKitElsewhere } = require('./project-root.js');
+const { loadProjectConfig } = require('./toml.js');
+const { real, sameSet } = require('./util.js');
+
+const hasProjectToml = (dir) => fs.existsSync(path.join(dir, '.wize', 'config', 'project.toml'));
+
+// -> { status, ctx, installed, root?, toplevel?, message? }
+//   installed  cwd already holds project.toml
+//   nested     an ancestor (inside the git checkout) holds it
+//   subdir     cwd is inside a git checkout but is not its top level
+//   primary    linked worktree whose branch lacks project.toml while the
+//              default-branch (or any other non-bare) worktree has it (merge the kit, or pass --here)
+//   ok         fresh install at cwd
+// `--here` skips the nested, subdir and primary checks.
+function checkInstallRoot({ cwd, flags = {} }) {
+  const here = real(cwd);
+  const ctx = gitContext(here);
+  if (hasProjectToml(here)) return { status: 'installed', installed: true, ctx, root: here };
+  if (flags.here) return { status: 'ok', installed: false, ctx };
+
+  const found = findProjectRoot(here);
+  if (found && found !== here) {
+    return { status: 'nested', installed: false, ctx, root: found, message: `kit already installed at ${found}; run from there` };
+  }
+  const primary = findKitElsewhere(here, ctx);
+  if (primary) {
+    return {
+      status: 'primary', installed: false, ctx, root: primary,
+      message: `kit is installed on ${primary}'s branch; merge it into this branch, or pass --here to install here`
+    };
+  }
+  if (ctx.isRepo && ctx.toplevel && real(ctx.toplevel) !== here) {
+    return {
+      status: 'subdir', installed: false, ctx, toplevel: real(ctx.toplevel),
+      message: `run install from the repo root ${real(ctx.toplevel)} (or pass --here)`
+    };
+  }
+  return { status: 'ok', installed: false, ctx };
+}
+
+const csv = (v) => (typeof v === 'string' ? v.split(',').map(s => s.trim()).filter(Boolean) : []);
+
+// Flags that would change what an installed project is configured for.
+// Returns the list of conflicting flag names (empty = nothing to reject).
+function conflictingFlags({ flags = {}, root }) {
+  let cfg;
+  try { cfg = loadProjectConfig(root); } catch { cfg = {}; }
+  const install = (cfg && cfg.install) || {};
+  const out = [];
+  if (typeof flags.profiles === 'string') {
+    const want = [...csv(flags.profiles), 'core'];
+    if (!sameSet(want, [...(install.profiles || ['core']), 'core'])) out.push('--profiles');
+  }
+  if (typeof flags.targets === 'string') {
+    if (!sameSet(csv(flags.targets), install.ide_targets || [])) out.push('--targets');
+  }
+  if (typeof flags.lang === 'string') {
+    const lang = cfg && cfg.language && cfg.language.communication;
+    if (flags.lang.trim() !== lang) out.push('--lang');
+  }
+  return out;
+}
+
+function installedPin(root) {
+  try {
+    const cfg = loadProjectConfig(root);
+    return (cfg.project && cfg.project.kit_version) || 'unknown';
+  } catch { return 'unknown'; }
+}
+
+// Default project name: the primary checkout's name in a linked worktree (the
+// worktree directory is a throwaway), else the directory being installed.
+function defaultProjectName({ cwd, ctx }) {
+  const c = ctx || gitContext(cwd);
+  if (c.isRepo && c.linked && c.primary) return path.basename(c.primary);
+  return path.basename(real(cwd));
+}
+
+const clean = (v) => (typeof v === 'string' && v.trim() ? v.trim() : null);
+
+// specific flag > legacy --name > derived
+function resolveProjectName({ flags = {}, cwd, ctx }) {
+  return clean(flags['project-name']) || clean(flags.name) || defaultProjectName({ cwd, ctx });
+}
+
+// specific flag > legacy --name > git user.name > $USER > Developer. Without
+// --yes and without a flag the caller prompts, so this returns null.
+function resolveUserName({ flags = {}, cwd, env = process.env, nonInteractive = false }) {
+  const given = clean(flags['user-name']) || clean(flags.name);
+  if (given) return given;
+  if (!nonInteractive) return null;
+  return configUserName(cwd) || env.USER || env.USERNAME || 'Developer';
+}
+
+function baselineDocsExist(root) {
+  try {
+    return fs.readdirSync(path.join(root, '.wize', 'knowledge', 'document-project')).some(f => f.endsWith('.md'));
+  } catch { return false; }
+}
+
+// -> { run, reason }. WIZE_SKIP_BASELINE=1 always wins; an existing baseline
+// blocks the run unless --baseline forces it; otherwise brownfield only.
+function baselineDecision({ root, flags = {}, env = process.env, brownfield }) {
+  if (env.WIZE_SKIP_BASELINE === '1') return { run: false, reason: 'env' };
+  if (flags.baseline) return { run: true, reason: 'forced' };
+  if (!brownfield) return { run: false, reason: 'greenfield' };
+  if (baselineDocsExist(root)) return { run: false, reason: 'exists' };
+  return { run: true, reason: 'brownfield' };
+}
+
+// Uninstall target: an explicit --root / WIZE_PROJECT_ROOT, else the project
+// root found from cwd (cwd itself when none). `refused` when cwd is not the
+// root and nothing explicit was given.
+function resolveUninstallRoot({ cwd, flags = {}, env = process.env }) {
+  const here = real(cwd);
+  const explicit = clean(flags.root) || clean(env.WIZE_PROJECT_ROOT);
+  if (explicit) return { root: real(path.resolve(here, explicit)), explicit: true, refused: false };
+  const found = findProjectRoot(here);
+  const root = found || here;
+  return { root, explicit: false, refused: root !== here };
+}
+
+module.exports = {
+  checkInstallRoot, conflictingFlags, installedPin, defaultProjectName,
+  resolveProjectName, resolveUserName, baselineDecision, resolveUninstallRoot
+};

package/tools/installer/marker.js

@@ -0,0 +1,67 @@
+// Hydration marker: .wize/.local/hydrated.json records which kit version
+// last rendered this checkout. .wize/.local/ is git-ignored, so each worktree
+// owns its own marker. Reads never throw.
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const SCHEMA = 1;
+
+function markerPath(root) {
+  return path.join(root, '.wize', '.local', 'hydrated.json');
+}
+
+function readMarker(root) {
+  try {
+    const data = JSON.parse(fs.readFileSync(markerPath(root), 'utf-8'));
+    return data && typeof data === 'object' && !Array.isArray(data) ? data : null;
+  } catch {
+    return null;
+  }
+}
+
+// The pin a render targeted. Fallback renders record it next to the binary that
+// did the work, so a pin the binary cannot match does not read as stale. Older
+// markers carry only kit_version.
+const markerPin = (marker) => (typeof marker.pin === 'string' ? marker.pin : marker.kit_version);
+
+// A fallback render stands in for the pinned kit while it cannot be run (offline,
+// unpublished). It counts as current for FALLBACK_TTL_MS, then the next
+// hydrate tries the exact pin again.
+const FALLBACK_TTL_MS = 60 * 60 * 1000;
+
+function fallbackExpired(marker, now = Date.now()) {
+  if (!marker || marker.fallback !== true) return false;
+  const at = Date.parse(marker.rendered_at);
+  return !Number.isFinite(at) || now - at > FALLBACK_TTL_MS;
+}
+
+function writeMarker(root, { kit_version, pin, targets, profiles, counts, delegated, rendered_with, fallback } = {}) {
+  const file = markerPath(root);
+  const payload = {
+    schema: SCHEMA,
+    kit_version: kit_version ?? null,
+    pin: pin ?? null,
+    targets: targets || [],
+    profiles: profiles || [],
+    counts: counts || {},
+    delegated: !!delegated,
+    rendered_with: rendered_with ?? null,
+    ...(fallback ? { fallback: true } : {}),
+    rendered_at: new Date().toISOString()
+  };
+  const tmp = path.join(path.dirname(file), `.hydrated.json.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`);
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(tmp, JSON.stringify(payload, null, 2) + '\n', 'utf-8');
+    fs.renameSync(tmp, file);
+    return payload;
+  } catch {
+    try { fs.rmSync(tmp, { force: true }); } catch { /* ignore */ }
+    return null;
+  }
+}
+
+module.exports = { markerPath, readMarker, writeMarker, markerPin, fallbackExpired, FALLBACK_TTL_MS };

package/tools/installer/project-root.js

@@ -0,0 +1,68 @@
+// Project-root discovery. A command run from a subdirectory or from a linked
+// worktree must land on the directory that owns `.wize/config/project.toml`,
+// without ever climbing out of the enclosing git checkout.
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { real } = require('./util.js');
+const { worktreeList, defaultBranch } = require('./git-context.js');
+
+const PROJECT_TOML = path.join('.wize', 'config', 'project.toml');
+
+function exists(p) {
+  try { fs.statSync(p); return true; } catch { return false; }
+}
+
+// Walks up from `start` and returns the first directory holding
+// .wize/config/project.toml. The walk ends at the first directory that
+// contains `.git` (file or dir); with no `.git` anywhere above, only `start`
+// is checked, so the walk never reaches $HOME.
+function findProjectRoot(start) {
+  const first = real(start);
+  const chain = [];
+  let boundary = null;
+  for (let dir = first; ; dir = path.dirname(dir)) {
+    chain.push(dir);
+    if (exists(path.join(dir, '.git'))) { boundary = dir; break; }
+    if (path.dirname(dir) === dir) break;
+  }
+  const candidates = boundary ? chain : [first];
+  for (const dir of candidates) {
+    if (exists(path.join(dir, PROJECT_TOML))) return dir;
+  }
+  return null;
+}
+
+// In a linked worktree whose branch lacks the kit, the other checkout that has
+// it: the default-branch worktree first, else any non-bare worktree (a bare
+// repository + worktrees layout has no primary checkout). `ctx` is the
+// gitContext of `here`. Null when this is not a linked worktree or none has it.
+function findKitElsewhere(here, ctx) {
+  if (!ctx || !ctx.isRepo || !ctx.linked) return null;
+  const self = real(ctx.toplevel || here);
+  const list = worktreeList(here) || [];
+  const def = defaultBranch(here);
+  const others = list.filter(w => !w.bare && real(w.path) !== self && real(w.path) !== real(here));
+  others.sort((a, b) => Number(b.branch === def) - Number(a.branch === def));
+  for (const w of others) {
+    if (exists(path.join(real(w.path), PROJECT_TOML))) return real(w.path);
+  }
+  if (!list.length && ctx.primary && real(ctx.primary) !== self && exists(path.join(real(ctx.primary), PROJECT_TOML))) return real(ctx.primary);
+  return null;
+}
+
+// Precedence: --root > WIZE_PROJECT_ROOT > findProjectRoot(cwd) > (hydrate
+// only) ORCA_WORKTREE_PATH > cwd. A project found from cwd beats an inherited
+// ORCA_WORKTREE_PATH, so a shell in worktree B never renders worktree A.
+function resolveRoot({ flags = {}, env = process.env, cwd = process.cwd(), forCommand = null } = {}) {
+  const pick = (v) => (typeof v === 'string' && v.trim() ? real(path.resolve(cwd, v.trim())) : null);
+  return pick(flags.root)
+    || pick(env.WIZE_PROJECT_ROOT)
+    || findProjectRoot(cwd)
+    || (forCommand === 'hydrate' ? pick(env.ORCA_WORKTREE_PATH) : null)
+    || real(cwd);
+}
+
+module.exports = { findProjectRoot, findKitElsewhere, resolveRoot };

package/tools/installer/project-status.js

@@ -0,0 +1,171 @@
+// Local project status for `version-check` and the CLI hints: what this
+// checkout is pinned to, whether it is hydrated, how that compares with the
+// running kit and the registry, and the one action to take next. Reads files
+// and git only; the registry answer comes in as `latest`.
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { loadProjectConfig } = require('./toml.js');
+const { compareVersions, parse, isSafePin } = require('./semver.js');
+const { findProjectRoot, findKitElsewhere } = require('./project-root.js');
+const { real } = require('./util.js');
+const { gitContext, defaultBranch } = require('./git-context.js');
+const { missingTargets } = require('./render-targets.js');
+const { readMarker, markerPin, fallbackExpired } = require('./marker.js');
+
+// First kit version that ships `hydrate`; older pins only know `sync`.
+const HYDRATE_MIN = '0.27.0';
+
+const ACTION_EXIT_CODES = { none: 0, hydrate: 10, update: 11, 'use-pin': 12, install: 13 };
+
+function kitVersionOf(kitRoot) {
+  try { return require(path.join(kitRoot, 'package.json')).version; }
+  catch { return null; }
+}
+
+function supportsHydrate(pin) {
+  return isSafePin(pin) && !!parse(pin) && compareVersions(pin, HYDRATE_MIN) >= 0;
+}
+
+function hydrateCommand(pin) {
+  if (!isSafePin(pin)) return 'npx --yes wize-dev-kit hydrate';
+  return supportsHydrate(pin)
+    ? `npx --yes wize-dev-kit@${pin} hydrate`
+    : `npx --yes wize-dev-kit@${pin} sync`;
+}
+
+function gitFacts(root) {
+  const ctx = gitContext(root);
+  return {
+    repo: ctx.isRepo,
+    linked: ctx.linked,
+    primary: ctx.primary,
+    branch: ctx.branch,
+    detached: ctx.isRepo ? ctx.detached : false,
+    default_branch: ctx.isRepo ? defaultBranch(root) : null
+  };
+}
+
+// `latestSource` says where `latest` came from. Only a registry answer fetched
+// just now (`'network'`) can prove a pin is unpublished: a cached answer may be
+// an hour old, or older offline, and a newer release would read as a downgrade.
+// `published` is the packument's list of every published version; a pin above
+// `latest` is unpublished only when that list is known and lacks it (a
+// prerelease published under another dist-tag is ahead of `latest` too).
+function getProjectStatus({ kitRoot, cwd = process.cwd(), latest = null, latestSource = null, published = null, env = process.env } = {}) {
+  const installed = kitVersionOf(kitRoot);
+  const root = findProjectRoot(cwd);
+  const commands = {
+    hydrate: hydrateCommand(null),
+    update: 'npx --yes wize-dev-kit@latest update',
+    pr: 'npx --yes wize-dev-kit@latest update --pr',
+    install: 'npx --yes wize-dev-kit@latest install'
+  };
+  const base = {
+    root,
+    pin: null,
+    installed,
+    latest: latest || null,
+    pin_status: 'missing',
+    hydrated: 'ok',
+    missing_targets: [],
+    marker_version: null,
+    user_toml: 'missing',
+    git: gitFacts(root || cwd),
+    skew: 'none',
+    action: 'none',
+    reason: '',
+    commands
+  };
+
+  if (!root) {
+    // A linked worktree whose branch predates the kit install: installing would
+    // fork the pin, so the answer is to merge, not to install.
+    const kitAt = findKitElsewhere(real(cwd), gitContext(real(cwd)));
+    if (kitAt) return { ...base, action: 'none', reason: 'kit-not-on-branch', kit_at: kitAt, commands: { ...commands, install: `${commands.install} --here` } };
+    return { ...base, action: 'install', reason: 'no-project', pin_status: 'missing', user_toml: 'missing' };
+  }
+
+  const cfg = loadProjectConfig(root);
+  const pin = (cfg.project && typeof cfg.project.kit_version === 'string' && cfg.project.kit_version) || null;
+  const targets = (cfg.install && cfg.install.ide_targets) || ['claude-code', 'generic'];
+  const marker = readMarker(root);
+  const missing = missingTargets(root, targets);
+  const userToml = fs.existsSync(path.join(root, '.wize', 'config', 'user.toml')) ? 'present' : 'missing';
+  const known = !!latest;
+
+  let pinStatus = 'ok';
+  if (!pin) pinStatus = 'missing';
+  else if (!isSafePin(pin)) pinStatus = 'invalid';
+  else if (installed && compareVersions(pin, installed) > 0) {
+    const proven = known && latestSource === 'network' && compareVersions(pin, latest) > 0
+      && Array.isArray(published) && !published.includes(pin);
+    pinStatus = proven ? 'unpublished' : 'ahead-of-binary';
+  }
+
+  let hydrated = 'ok';
+  if (missing.length) hydrated = 'missing';
+  else if (supportsHydrate(pin) && marker && (markerPin(marker) !== pin || fallbackExpired(marker))) hydrated = 'stale';
+
+  let skew = 'none';
+  if (pin && installed) {
+    const cmp = compareVersions(pin, installed);
+    if (cmp < 0) skew = 'project-behind';
+    else if (cmp > 0) skew = 'project-ahead';
+    else if (known && compareVersions(latest, pin) > 0) skew = 'registry-ahead';
+  }
+
+  commands.hydrate = hydrateCommand(pin);
+
+  let action = 'none';
+  let reason = 'up-to-date';
+  if (hydrated !== 'ok') {
+    action = 'hydrate';
+    reason = hydrated === 'missing' ? 'unhydrated' : 'stale-marker';
+  } else if (userToml === 'missing' && supportsHydrate(pin)) {
+    action = 'hydrate';
+    reason = 'user-toml-missing';
+  } else if (pinStatus === 'unpublished') {
+    action = 'update';
+    reason = 'pin-unpublished';
+    commands.update = 'npx --yes wize-dev-kit@latest update --allow-downgrade';
+  } else if (pinStatus === 'ahead-of-binary') {
+    action = 'use-pin';
+    reason = 'pin-ahead-of-binary';
+  } else if (pinStatus === 'missing' || pinStatus === 'invalid') {
+    action = 'update';
+    reason = pinStatus === 'missing' ? 'pin-missing' : 'pin-invalid';
+  } else if (skew === 'project-behind') {
+    action = 'update';
+    reason = 'project-behind';
+  } else if (skew === 'registry-ahead') {
+    action = 'update';
+    reason = 'registry-ahead';
+  }
+
+  // WIZE_DISABLE_UPDATE_CHECK=1 is the opt-out of auto-update: the skew stays
+  // visible, the update action does not.
+  if (env.WIZE_DISABLE_UPDATE_CHECK === '1' && action === 'update') {
+    action = 'none';
+    reason = 'update-disabled';
+  }
+
+  return {
+    ...base,
+    root,
+    pin,
+    pin_status: pinStatus,
+    hydrated,
+    missing_targets: missing,
+    marker_version: marker ? marker.kit_version ?? null : null,
+    user_toml: userToml,
+    skew,
+    action,
+    reason,
+    commands
+  };
+}
+
+module.exports = { getProjectStatus, kitVersionOf, hydrateCommand, supportsHydrate, ACTION_EXIT_CODES, HYDRATE_MIN };

package/tools/installer/render-shared.js

@@ -105,10 +105,100 @@ function clipOneLine(str, max = 240) {
   return flat.slice(0, max - 1).trimEnd() + '…';
 }
 
+// Where `dir` would be created: the nearest existing ancestor resolved through
+// symlinks, plus the part that does not exist yet.
+function landingDir(dir) {
+  const rest = [];
+  let cur = path.resolve(dir);
+  for (;;) {
+    try { return path.join(fs.realpathSync(cur), ...rest.reverse()); } catch { /* not there yet */ }
+    const parent = path.dirname(cur);
+    if (parent === cur) return path.resolve(dir);
+    rest.push(path.basename(cur));
+    cur = parent;
+  }
+}
+
+// With a write guard set, a directory the guard vetoes is not created, so a
+// symlinked directory cannot be filled with empty folders behind the guard.
 function ensureDir(dir) {
+  if (probeOnly) return;
+  if (writeGuard && (writeGuard(path.resolve(dir)) || writeGuard(landingDir(dir)))) return;
   fs.mkdirSync(dir, { recursive: true });
 }
 
+// ---- Write safety -------------------------------------------------------
+// Every file a renderer emits goes through writeFileIfChanged /
+// copyFileIfChanged: identical bytes are left alone (mtime untouched), writes
+// are atomic (tmp + rename, safe for concurrent hydrates of one tree), and an
+// optional guard can veto a path (hydrate uses it to never touch tracked files).
+let writeGuard = null;
+// Probe mode: every write still goes through the guard (so vetoes are
+// recorded) but nothing touches the disk.
+let probeOnly = false;
+const writeStats = { written: 0, unchanged: 0, skippedTracked: [] };
+
+function setWriteGuard(fn) { writeGuard = typeof fn === 'function' ? fn : null; }
+function clearWriteGuard() { writeGuard = null; }
+function setProbeMode(on) { probeOnly = !!on; }
+function getWriteStats() {
+  return { written: writeStats.written, unchanged: writeStats.unchanged, skippedTracked: writeStats.skippedTracked.slice() };
+}
+function resetWriteStats() {
+  writeStats.written = 0;
+  writeStats.unchanged = 0;
+  writeStats.skippedTracked = [];
+}
+
+function atomicWrite(abs, buf, mode) {
+  const tmp = path.join(path.dirname(abs), `.${path.basename(abs)}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`);
+  try {
+    fs.writeFileSync(tmp, buf);
+    if (mode !== undefined) fs.chmodSync(tmp, mode);
+    fs.renameSync(tmp, abs);
+  } catch (err) {
+    try { fs.rmSync(tmp, { force: true }); } catch { /* ignore */ }
+    throw err;
+  }
+}
+
+// The path a write really lands on: the parent directory is resolved through
+// symlinks, so a tracked `.claude/skills -> ../skills` link cannot hide the
+// tracked file behind it from the guard.
+function landingPath(abs) {
+  return path.join(landingDir(path.dirname(abs)), path.basename(abs));
+}
+
+function emit(file, buf, mode) {
+  const abs = path.resolve(file);
+  if (writeGuard && (writeGuard(abs) || writeGuard(landingPath(abs)))) {
+    writeStats.skippedTracked.push(abs);
+    return 'skipped-tracked';
+  }
+  if (probeOnly) {
+    writeStats.unchanged++;
+    return 'unchanged';
+  }
+  let existing = null;
+  try { existing = fs.readFileSync(abs); } catch { /* absent */ }
+  if (existing && existing.equals(buf)) {
+    writeStats.unchanged++;
+    return 'unchanged';
+  }
+  atomicWrite(abs, buf, mode);
+  writeStats.written++;
+  return 'written';
+}
+
+// -> 'written' | 'unchanged' | 'skipped-tracked'
+function writeFileIfChanged(file, content) {
+  return emit(file, Buffer.isBuffer(content) ? content : Buffer.from(String(content), 'utf-8'));
+}
+
+function copyFileIfChanged(src, dst) {
+  return emit(dst, fs.readFileSync(src), fs.statSync(src).mode & 0o777);
+}
+
 // Companion files (steps/, templates/, data/, *.csv, *-template.md,
 // customize.toml, research.template.md, etc.) that micro-file workflows
 // reference from their body. We must copy these alongside the SKILL.md so
@@ -139,7 +229,7 @@ function copyCompanionFiles(srcDir, destDir, written, relPrefix = '') {
       copyCompanionFiles(s, d, written, rel);
     } else if (entry.isFile()) {
       ensureDir(path.dirname(d));
-      fs.copyFileSync(s, d);
+      copyFileIfChanged(s, d);
       written.push(rel);
     }
   }
@@ -244,7 +334,7 @@ function renderAnthropicSkills(kitRoot, targetDir, opts = {}) {
     } else {
       const skillDir = path.join(targetDir, a.code);
       ensureDir(skillDir);
-      fs.writeFileSync(path.join(skillDir, 'SKILL.md'), content, 'utf-8');
+      writeFileIfChanged(path.join(skillDir, 'SKILL.md'), content);
       written.push(`${a.code}/SKILL.md`);
       // Copy companion files (steps/, templates/, data/, *.csv, customize.toml,
       // *-template.md, research.template.md, etc.) so micro-file workflows can
@@ -272,7 +362,69 @@ const AGENT_ORDER = [
   'wize-sec-red-teamer'
 ];
 
+// ---- managed bootstrap block ---------------------------------------------------
+//
+// AGENTS.md is the one tracked file that Codex, Cursor, Windsurf, Antigravity
+// and others read at session start. The block below tells the agent to run
+// `version-check --json` and follow its `action`. The text names no version,
+// so `update` only rewrites it when the wording itself changes.
+
+const AGENTS_TITLE = '# Agents — Wize Development Kit';
+const BOOTSTRAP_BEGIN = '<!-- wize:bootstrap:begin (managed by wize-dev-kit; edits inside are replaced by update) -->';
+const BOOTSTRAP_END = '<!-- wize:bootstrap:end -->';
+const BOOTSTRAP_BEGIN_RE = /<!-- wize:bootstrap:begin[^\n]*?-->/;
+
+const BOOTSTRAP_LINES = [
+  BOOTSTRAP_BEGIN,
+  '## Kit bootstrap',
+  '',
+  'Once per session, if you can run shell commands, run `npx --yes --fetch-retries=0 wize-dev-kit version-check --json`',
+  '(prefix it with `timeout 20` where that exists) and follow its `action` field (if npx fails or times out,',
+  'for example offline, skip this):',
+  '',
+  '- `hydrate`: run `commands.hydrate` now. It writes only git-ignored files. If the `/wize-*`',
+  '  commands are still missing afterwards, tell the user to restart the harness.',
+  '- `update`: run `commands.update`. It prepares a `chore/wize-kit-<version>` branch in a temporary',
+  '  worktree and never touches this checkout. Then ask once before running `commands.pr`, which',
+  '  pushes the branch and opens a PR. Exception: when `reason` is `pin-unpublished`, `commands.update`',
+  '  lowers the project pin; ask the user first and run it only on a yes.',
+  '- `use-pin`: tell the user to run kit commands as `npx wize-dev-kit@<pin>`, with `<pin>` taken from',
+  '  `project.pin` in the JSON.',
+  '- `none` with `reason` `kit-not-on-branch`: tell the user to merge the kit into this branch, or install here with `install --here`.',
+  '- `install`, other `none`: do nothing.',
+  '',
+  'If the `/wize-*` commands are missing, run `npx --yes wize-dev-kit hydrate`.',
+  'Never commit a kit update on the default branch.',
+  BOOTSTRAP_END
+];
+const BOOTSTRAP_BLOCK = BOOTSTRAP_LINES.join('\n');
+
+// True only for an AGENTS.md this kit generated. A foreign file is never edited.
+function isKitAgentsMd(content) {
+  if (typeof content !== 'string') return false;
+  return content.replace(/^/, '').split(/\r?\n/, 1)[0] === AGENTS_TITLE;
+}
+
+// Pure: returns `content` with exactly one managed bootstrap block. An existing
+// block is replaced in place; otherwise the block goes before the first `## `
+// heading, or at the end when there is none. A half-written block (one marker
+// without the other) is left alone rather than guessed at.
+function upsertBootstrapBlock(content) {
+  const begin = BOOTSTRAP_BEGIN_RE.exec(content);
+  const endIdx = content.indexOf(BOOTSTRAP_END);
+  if (begin || endIdx !== -1) {
+    if (!begin || endIdx === -1 || endIdx < begin.index) return content;
+    return content.slice(0, begin.index) + BOOTSTRAP_BLOCK + content.slice(endIdx + BOOTSTRAP_END.length);
+  }
+  const heading = /^## /m.exec(content);
+  if (heading) {
+    return content.slice(0, heading.index) + BOOTSTRAP_BLOCK + '\n\n' + content.slice(heading.index);
+  }
+  return content.replace(/\s*$/, '') + '\n\n' + BOOTSTRAP_BLOCK + '\n';
+}
+
 function renderAgentsMd(kitRoot, projectRoot, opts = {}) {
+  if (opts.skipAgentsMd) return { written: [], skipped: ['AGENTS.md (skipAgentsMd)'] };
   const assets = collectAssets(kitRoot, opts);
   const rank = (code) => {
     const i = AGENT_ORDER.indexOf(code);
@@ -286,12 +438,14 @@ function renderAgentsMd(kitRoot, projectRoot, opts = {}) {
     return { written: [], skipped: ['AGENTS.md (already present; not overwritten)'] };
   }
   const lines = [
-    '# Agents — Wize Development Kit',
+    AGENTS_TITLE,
     '',
     'This repo is wired with the [`wize-dev-kit`](https://www.npmjs.com/package/wize-dev-kit).',
     'Detailed artifacts live under `.wize/`. The agents below are activated through your AI IDE',
     'using slash commands (Claude Code, Codex, Cursor, Windsurf, Antigravity, Hermes all read this file).',
     '',
+    ...BOOTSTRAP_LINES,
+    '',
     '## Operating context',
     '',
     'Treat `.wize/`, this `AGENTS.md`, and the installed `wize-*` skills as your operating',
@@ -351,7 +505,7 @@ function renderAgentsMd(kitRoot, projectRoot, opts = {}) {
   lines.push('', '## Where to start', '', 'Activate the orchestrator: `/wize` (or `/wize-help`). Wizer will guide you.', '');
 
   if (opts.dryRun) return { written: ['[dry-run] AGENTS.md'], skipped: [] };
-  fs.writeFileSync(file, lines.join('\n'), 'utf-8');
+  writeFileIfChanged(file, lines.join('\n'));
   return { written: ['AGENTS.md'], skipped: [] };
 }
 
@@ -359,7 +513,19 @@ module.exports = {
   collectAssets,
   renderAnthropicSkills,
   renderAgentsMd,
+  upsertBootstrapBlock,
+  isKitAgentsMd,
+  BOOTSTRAP_BEGIN,
+  BOOTSTRAP_END,
+  BOOTSTRAP_BLOCK,
   copyCompanionFiles,
+  writeFileIfChanged,
+  copyFileIfChanged,
+  setWriteGuard,
+  clearWriteGuard,
+  setProbeMode,
+  getWriteStats,
+  resetWriteStats,
   // Re-exports for adapter authors who need to roll their own format:
   readFrontmatter,
   bodyAfterFrontmatter,