@timekast/factory 2.4.0 → 2.6.0

package/dist/commands/prune.js

@@ -18,12 +18,15 @@ import { GITIGNORE_FILE } from '../lib/constants.js';
 import { readValueFlag } from '../lib/flags.js';
 import { commitWithPrivateIndex, trackedFiles } from '../lib/prune-git.js';
 import { checkPr, REJECTED_PACKAGE_FIELDS } from '../lib/prune-pr-check.js';
+import { BRANCH_DEPLOY_RULE, VERCEL_JSON, ensureBranchDeployRule, hasBranchDeployRule, pruneVercelRelink, resolveVercelProject, } from '../lib/prune-vercel.js';
+import { readVercelToken } from '../lib/provision-preflight.js';
 import { applyTierFiles, defaultPruneDeps, originRepo, pruneAudit, pruneCutover, pruneFinish, pruneInvite, } from '../lib/prune-remote.js';
 import { DEFAULT_PRUNE_TIER, PRUNE_MARKER_PATH, getTier, isRestricted, readPruneMarker, readPruneTiers, } from '../lib/prune-tiers.js';
 import { detectRepo } from '../lib/repo-detection.js';
 const PRUNE_USAGE = 'Uso: `factory prune prepare [--tier=collab] [--skip-verify]` · ' +
     '`factory prune cutover [--confirm] [--discard-develop] [--resume] [--repo=owner/nombre]` · ' +
-    '`factory prune invite <usuario-github> [--repo=owner/nombre]` · ' +
+    '`factory prune vercel [--confirm] [--repo=owner/nombre] [--project=prj_…] [--team=team_…]` · ' +
+    '`factory prune invite <usuario-github> [--read] [--repo=owner/nombre]` · ' +
     '`factory prune finish [--repo=owner/nombre]` · `factory prune audit [--repo=owner/nombre]` · ' +
     '`factory prune check-pr <número> [--repo=owner/nombre] [--json]`.';
 export function parsePrunePrepareFlags(argv) {
@@ -48,25 +51,29 @@ export async function prunePrepare(rootDir, flags) {
     const tier = getTier(readPruneTiers(rootDir), flags.tier);
     // The two files this command owns must not carry someone's uncommitted work: the commit
     // below takes them whole.
-    const dirty = await execa('git', ['status', '--porcelain', '--', GITIGNORE_FILE, PRUNE_MARKER_PATH], { cwd: rootDir, reject: false });
+    const dirty = await execa('git', ['status', '--porcelain', '--', GITIGNORE_FILE, PRUNE_MARKER_PATH, VERCEL_JSON], { cwd: rootDir, reject: false });
     if (dirty.stdout.trim() !== '') {
-        throw new CLIError(`\`${GITIGNORE_FILE}\` o \`${PRUNE_MARKER_PATH}\` tienen cambios sin commitear. ` +
+        throw new CLIError(`\`${GITIGNORE_FILE}\`, \`${PRUNE_MARKER_PATH}\` o \`${VERCEL_JSON}\` tienen cambios sin commitear. ` +
             'Commitéalos o descártalos y vuelve a correr `factory prune prepare`.');
     }
     // 1. The block and the switch — `at` survives a re-run with the same tier, so a re-run
     // changes nothing.
     const prior = readPruneMarker(rootDir);
     const legacyBlockRemoved = applyTierFiles(rootDir, flags.tier, tier, prior?.tier === flags.tier ? prior.at : new Date().toISOString());
-    // 2. Untrack what the tier restricts, and commit it with the block and the switch.
+    // 2. On Vercel, only `main` and `develop` deploy on push: a collaborator's branch would
+    //    start a deployment Vercel blocks (author without a seat).
+    const branchDeployRuleAdded = ensureBranchDeployRule(rootDir) === 'added';
+    // 3. Untrack what the tier restricts, and commit it with the block, the switch and the rule.
     const untracked = (await trackedFiles(rootDir)).filter((p) => isRestricted(tier, p));
     const commit = await commitWithPrivateIndex(rootDir, {
         remove: untracked,
-        add: [GITIGNORE_FILE, PRUNE_MARKER_PATH],
+        add: [GITIGNORE_FILE, PRUNE_MARKER_PATH, ...(branchDeployRuleAdded ? [VERCEL_JSON] : [])],
         message: `chore(prune): keep the methodology local (tier ${flags.tier})`,
     });
     return {
         tier: flags.tier,
         untracked,
+        branchDeployRuleAdded,
         legacyBlockRemoved,
         ...(commit.committed ? { commit: commit.sha } : {}),
     };
@@ -94,6 +101,10 @@ async function runPrunePrepare(flags) {
             `Dejé de trackear ${result.untracked.length} archivo(s); siguen en tu disco:`);
         for (const line of summarizePaths(result.untracked))
             console.log(line);
+        if (result.branchDeployRuleAdded) {
+            console.log(`✔ \`${VERCEL_JSON}\`: sólo \`main\` y \`develop\` despliegan con cada push — las ramas de ` +
+                'los colaboradores no intentan un deploy que Vercel bloquearía.');
+        }
     }
     if (flags.skipVerify)
         return;
@@ -155,7 +166,7 @@ async function runPruneCutover(flags, deps) {
         for (const line of result.notMigrated)
             console.log(`  • ${line}`);
     }
-    console.log('\nSiguiente: reconecta el proyecto de Vercel al repo nuevo en el dashboard (Settings → Git), ' +
+    console.log('\nSiguiente: reconecta el proyecto de Vercel al repo nuevo (`factory prune vercel`), ' +
         'pide a los socios volver a clonar, y corre `factory prune finish` cuando Production despliegue.');
 }
 function printAudit(repo, audit) {
@@ -188,7 +199,7 @@ async function repoFrom(argv) {
     return readValueFlag(argv, 'repo') ?? (await originRepo(requireRepoRoot()));
 }
 /** `factory prune <sub> [...]` — dispatch lives here so every branch is testable. */
-export async function runPruneCommand(args, deps = defaultPruneDeps) {
+export async function runPruneCommand(args, deps = defaultPruneDeps, vercel = {}) {
     const sub = args[0];
     const rest = args.slice(1);
     switch (sub) {
@@ -203,9 +214,48 @@ export async function runPruneCommand(args, deps = defaultPruneDeps) {
             if (!user)
                 throw new CLIError(`Falta el usuario de GitHub del colaborador. ${PRUNE_USAGE}`);
             const repo = await repoFrom(rest);
-            await pruneInvite(repo, user, deps);
-            console.log(`✔ Invité a \`${user}\` a \`${repo}\` con lectura. Tiene que aceptar la invitación; ` +
-                'después forkea y abre PRs a la rama de trabajo.');
+            const read = rest.includes('--read');
+            await pruneInvite(repo, user, deps, read ? 'pull' : 'push');
+            console.log(read
+                ? `✔ Invité a \`${user}\` a \`${repo}\` con lectura. Tiene que aceptar la invitación; ` +
+                    'después forkea y abre PRs a la rama de trabajo.'
+                : `✔ Invité a \`${user}\` a \`${repo}\` con escritura. Tiene que aceptar la invitación; ` +
+                    'después trabaja en ramas del repo y abre PRs a la rama de trabajo. El hook `pre-push` ' +
+                    'del repo le rechaza el push a `main` y `develop` (no cubre la web de GitHub).');
+            return;
+        }
+        case 'vercel': {
+            const repo = await repoFrom(rest);
+            const { projectId, teamId } = resolveVercelProject(requireRepoRoot(), {
+                project: readValueFlag(rest, 'project'),
+                team: readValueFlag(rest, 'team'),
+            });
+            const token = await (vercel.token ?? (() => readVercelToken()))();
+            const result = await pruneVercelRelink({ repo, projectId, teamId, token, confirm: rest.includes('--confirm') }, { gh: deps.gh, ...(vercel.fetchImpl ? { fetchImpl: vercel.fetchImpl } : {}) });
+            if (hasBranchDeployRule(requireRepoRoot()) === false) {
+                console.warn(`⚠ \`${VERCEL_JSON}\` no limita los deploys por push: cada rama de un colaborador intentará ` +
+                    'un deploy que Vercel bloquea (autor sin asiento). Agrega y commitea:\n' +
+                    `    "git": { "deploymentEnabled": ${JSON.stringify(BRANCH_DEPLOY_RULE)} }`);
+            }
+            if (result.status === 'already-linked') {
+                console.log(`✔ El proyecto de Vercel ya despliega desde \`${result.link.repo}\`. Nada que hacer.`);
+            }
+            else if (result.status === 'plan') {
+                console.log([
+                    `Plan: el proyecto de Vercel (\`${projectId}\`) despliega desde ` +
+                        `${result.from ? `\`${result.from.repo}\`` : 'ningún repo'}.`,
+                    `  1. Desconectarlo${result.from ? ` de \`${result.from.repo}\`` : ''} (variables, dominios y deploys se quedan).`,
+                    `  2. Conectarlo a \`${result.to}\` y releer el vínculo para confirmarlo.`,
+                    '  No dispara ningún deploy.',
+                    '',
+                    'Para ejecutarlo: `factory prune vercel --confirm`.',
+                ].join('\n'));
+            }
+            else {
+                console.log(`✔ El proyecto de Vercel ahora despliega desde \`${result.to.repo}\`` +
+                    `${result.from ? ` (antes: \`${result.from.repo}\`)` : ''}. ` +
+                    'El primer deploy sale con el siguiente push a `main` (p. ej. un commit vacío).');
+            }
             return;
         }
         case 'finish': {

package/dist/commands/update.js

@@ -23,8 +23,10 @@
  * Auto-register (no lockfile, pre-CLI repo, design §6.3): path-match — repo
  * paths matching the manifest are kit-owned (overwrite); `.claude/` paths absent
  * from the manifest are logged "ambiguous" and NOT deleted on the first sync;
- * an existing `CLAUDE.md` is preserved (write-if-absent). The dev is warned + sees
- * the auto-detected profile before proceeding.
+ * an existing `CLAUDE.md` is preserved (write-if-absent), and so is any other kit
+ * file outside the brain the repo already has with its own content (the kit's copy
+ * goes to `<path>.kit-example`). The dev is warned + sees the auto-detected profile
+ * before proceeding.
  *
  * `--verify`: compares disk vs lockfile and reports drift WITHOUT modifying
  * anything. `--resume`: re-applies a persisted mid-flight state without
@@ -44,14 +46,18 @@ import { collectClaudePaths } from '../lib/claude-paths.js';
 import { CLIError } from '../lib/cli-error.js';
 import { CLAUDE_MD_FILE, GITATTRIBUTES_FILE, GITIGNORE_FILE, LOCKFILE_FILE, PRETTIERIGNORE_FILE, PROFILES, TIMEKAST_DIR, } from '../lib/constants.js';
 import { decideCommit } from '../lib/commit-decision.js';
-import { extractManagedBlock, syncManagedBlock } from '../lib/gitattributes.js';
+import { syncDerivedDotfiles } from '../lib/derived-dotfiles.js';
+import { partitionInitialWrites, refreshKitExamples, reportKeptRepoFiles, writeKitExamples, } from '../lib/initial-writes.js';
+import { offerKitDeps, readKitDeps } from '../lib/kit-deps.js';
 import { diffLockfiles, hasLockfile, normalizeThenHash, planAutoRegister, readLockfile, writeLockfile, } from '../lib/lockfile.js';
+import { effectiveSettingsHash, KIT_SETTINGS_PATH, LEGACY_KIT_SETTINGS_KEYS, mergeProjectSettingsKeys, } from '../lib/claude-settings.js';
 import { detectProfile, maintainKitScripts, setAgentKitVersion } from '../lib/package-json.js';
 import { runPreflight } from '../lib/preflight.js';
 import { printProvisionPointer } from '../lib/provision-pointer.js';
 import { planPruneMaintenance } from '../lib/prune-update.js';
 import { isRestricted, PRUNE_MARKER_PATH } from '../lib/prune-tiers.js';
 import { printRetrofitReminder } from '../lib/retrofit-reminder.js';
+import { printWhatsNew } from '../lib/whats-new.js';
 import { hasProvisionState } from '../lib/provision-state.js';
 import { loginCommand } from '../lib/rail.js';
 import { resolveBrainRoot } from '../lib/repo-detection.js';
@@ -100,16 +106,52 @@ async function acquireFromBeta(profile) {
  * Hash the disk content (normalized) of every path in `paths` that exists.
  * A missing file is simply absent from the returned map.
  */
-function hashDiskPaths(rootDir, paths) {
+function hashDiskPaths(rootDir, paths, settingsEntries = []) {
     const map = new Map();
     for (const rel of paths) {
         const abs = path.join(rootDir, rel);
         if (existsSync(abs) && statSync(abs).isFile()) {
-            map.set(rel, normalizeThenHash(readFileSync(abs, 'utf8')));
+            const raw = readFileSync(abs, 'utf8');
+            // settings.json: only the kit's keys count, by content (the project's are its own).
+            map.set(rel, rel === KIT_SETTINGS_PATH
+                ? effectiveSettingsHash(raw, settingsEntries)
+                : normalizeThenHash(raw));
         }
     }
     return map;
 }
+/** The `settings.json` the project had before this apply: the run's backup, else the disk. */
+function readPreviousSettings(rootDir, backupDir) {
+    for (const abs of [
+        path.join(backupDir, KIT_SETTINGS_PATH),
+        path.join(rootDir, KIT_SETTINGS_PATH),
+    ]) {
+        if (existsSync(abs) && statSync(abs).isFile())
+            return readFileSync(abs, 'utf8');
+    }
+    return null;
+}
+/**
+ * After the kit's `settings.json` was written, put the project's own keys back (every top-level
+ * key the kit does not declare) and say so. No-op when the kit's file was not written.
+ */
+function restoreProjectSettingsKeys(rootDir, written, previous, previousKitKeys) {
+    if (previous === null || !written.includes(KIT_SETTINGS_PATH))
+        return;
+    const abs = path.join(rootDir, KIT_SETTINGS_PATH);
+    const merged = mergeProjectSettingsKeys(readFileSync(abs, 'utf8'), previous, previousKitKeys);
+    if (merged.content !== null) {
+        writeFileSync(abs, merged.content, 'utf8');
+        console.log(`  ✔ ${KIT_SETTINGS_PATH}: conservé tus llaves (${merged.kept.join(', ')})`);
+    }
+    for (const key of merged.replaced) {
+        console.warn(`  ⚠ ${KIT_SETTINGS_PATH}: \`${key}\` ahora la declara el kit — tu valor se reemplazó por el suyo.`);
+    }
+}
+/** The kit's keys recorded for `settings.json` in a lockfile (the legacy set when absent). */
+function kitSettingsKeysOf(lock) {
+    return lock?.files.find((f) => f.path === KIT_SETTINGS_PATH)?.keys ?? LEGACY_KIT_SETTINGS_KEYS;
+}
 /** Unchanged lines kept around each change in the `[3] Ver diff` view. */
 const DIFF_CONTEXT_LINES = 3;
 /**
@@ -301,7 +343,7 @@ function runVerify(rootDir) {
         throw new CLIError('No hay lockfile que verificar. Corre `factory update` primero.');
     }
     const lock = readLockfile(rootDir);
-    const disk = hashDiskPaths(rootDir, lock.files.map((f) => f.path));
+    const disk = hashDiskPaths(rootDir, lock.files.map((f) => f.path), [lock.files.find((f) => f.path === KIT_SETTINGS_PATH)]);
     const missing = [];
     const drifted = [];
     for (const entry of lock.files) {
@@ -465,20 +507,32 @@ async function runResume(rootDir, flags) {
     const claudeMd = priorLock
         ? assessClaudeMd(rootDir, priorLock)
         : undefined;
+    const previousSettings = readPreviousSettings(rootDir, state.backupDir);
     applyPlan(rootDir, state.stagedDir, state.plan, state.backupDir);
+    restoreProjectSettingsKeys(rootDir, state.plan.writes, previousSettings, kitSettingsKeysOf(priorLock));
     writeLockfile(rootDir, newLock);
     clearUpdateState(rootDir);
     const claudeMdInserted = claudeMd ? applyClaudeMdRetrofit(rootDir, claudeMd) : false;
+    const kitExamples = refreshKitExamples(rootDir, state.stagedDir, newLock.files.map((f) => f.path));
     // Maintain dotfiles BEFORE removing the staged dir (the .gitattributes source).
-    const pkgMutations = maintainDerivedDotfiles(rootDir, state.stagedDir, newLock.version);
+    const pkgMutations = maintainDerivedDotfiles(rootDir, state.stagedDir, newLock);
     const prune = await planPruneMaintenance(rootDir, state.stagedDir, newLock.files.map((f) => f.path));
-    await maybeCommitBrain(rootDir, newLock.version, [...state.plan.writes, ...state.plan.deletes, ...(claudeMdInserted ? [CLAUDE_MD_FILE] : [])], flags, prune);
+    await maybeCommitBrain(rootDir, newLock.version, [
+        ...state.plan.writes,
+        ...state.plan.deletes,
+        ...kitExamples,
+        ...(claudeMdInserted ? [CLAUDE_MD_FILE] : []),
+    ], flags, prune);
+    const kitDeps = readKitDeps(state.stagedDir);
     rmSync(state.stagedDir, { recursive: true, force: true });
     // A resumed update maintains package.json exactly like a normal one, so it owes the dev the
     // same account of what it moved there (`BND-004`).
     reportPkgMutations(pkgMutations);
     if (claudeMd)
         reportClaudeMd(claudeMd, 'applied', claudeMdInserted);
+    // AFTER the brain commit: an install changes package.json and the package lockfile, which
+    // stay out of that commit (Factory#78).
+    await offerKitDeps(rootDir, kitDeps, { assumeYes: flags.yes });
     console.log('✔ `update` retomado y completado.');
     // A resumed update that succeeds completed the setup → show the end-pointer
     // (PVSKILL-002 §8 edge: `--resume` SÍ lo muestra). Suppressed only in headless
@@ -522,10 +576,9 @@ function warnOnScriptConflict(action, _pkgPath) {
  * the managed blocks. Runs BEFORE any brain commit, so the blocks land before a
  * pre-commit hook could reformat the freshly-installed kit files.
  */
-function maintainDerivedDotfiles(rootDir, stagedDir, agentKitVersion) {
-    const pkgMutations = maintainDerivedPkg(rootDir, agentKitVersion);
-    syncDerivedGitattributes(rootDir, stagedDir);
-    syncDerivedPrettierignore(rootDir, stagedDir);
+function maintainDerivedDotfiles(rootDir, stagedDir, manifest) {
+    const pkgMutations = maintainDerivedPkg(rootDir, manifest.version);
+    syncDerivedDotfiles(rootDir, stagedDir, manifest);
     return pkgMutations;
 }
 /** A run that mutated nothing (no package.json, or the maintenance failed and warned). */
@@ -574,63 +627,6 @@ function maintainDerivedPkg(rootDir, agentKitVersion) {
         return emptyPkgMutations();
     }
 }
-/**
- * Sync the Factory's managed `.gitattributes` block (the EOL/binary rules that
- * keep the kit's committed binaries from being corrupted by CRLF→LF normalization)
- * into the derived repo, preserving the dev's own rules. The canonical block is
- * READ from the staged tarball (single SSOT), so the rules are never duplicated in
- * the CLI. Runs even without package.json (a non-Node derivative needs the rules
- * too). Best-effort like the package.json mirror: a tarball that predates the
- * managed block (no markers → no block) is a silent no-op, and a write failure
- * never fails an already-applied update.
- */
-function syncDerivedGitattributes(rootDir, stagedDir) {
-    try {
-        const srcPath = path.join(stagedDir, GITATTRIBUTES_FILE);
-        if (!existsSync(srcPath))
-            return;
-        const block = extractManagedBlock(readFileSync(srcPath, 'utf8'));
-        if (!block)
-            return;
-        const { action } = syncManagedBlock(rootDir, block);
-        if (action === 'unchanged')
-            return;
-        console.log(action === 'created'
-            ? '✔ `.gitattributes` creado con las reglas de normalización del kit.'
-            : '✔ `.gitattributes`: bloque de reglas del kit sincronizado.');
-    }
-    catch {
-        console.warn('Aviso: no se pudo sincronizar `.gitattributes`; el cerebro se instaló igual.');
-    }
-}
-/**
- * Sync the Factory's managed `.prettierignore` block (keeps the derived repo's
- * formatter away from `.claude/**` — a pre-commit `prettier --write` over the kit
- * files drifts disk from the lockfile hashes and turns every later update into
- * false conflicts) into the derived repo, preserving the dev's own ignore rules.
- * Same contract as `syncDerivedGitattributes`: canonical block READ from the
- * staged tarball (single SSOT), best-effort, tarball without the file (pre-block
- * releases) → silent no-op, a write failure never fails an applied update.
- */
-function syncDerivedPrettierignore(rootDir, stagedDir) {
-    try {
-        const srcPath = path.join(stagedDir, PRETTIERIGNORE_FILE);
-        if (!existsSync(srcPath))
-            return;
-        const block = extractManagedBlock(readFileSync(srcPath, 'utf8'));
-        if (!block)
-            return;
-        const { action } = syncManagedBlock(rootDir, block, PRETTIERIGNORE_FILE);
-        if (action === 'unchanged')
-            return;
-        console.log(action === 'created'
-            ? '✔ `.prettierignore` creado con el ignore del cerebro (`.claude/`) — evita falsos conflictos por formato en futuros updates.'
-            : '✔ `.prettierignore`: bloque del kit sincronizado (`.claude/` fuera del formatter).');
-    }
-    catch {
-        console.warn('Aviso: no se pudo sincronizar `.prettierignore`; el cerebro se instaló igual.');
-    }
-}
 /**
  * The kit's own test folder. It stopped shipping to derivatives (`BND-003`): those tests
  * validate KIT tooling, and inside a derivative they ran against a `src/` that may have
@@ -928,10 +924,11 @@ export async function runUpdate(flags, deps = {}) {
             if (flags.dryRun) {
                 console.log('\n🔍 Vista previa: este repo aún no tiene lockfile. El primer `factory update` ' +
                     'registra el cerebro; en el primer sync no hay conflictos posibles.');
+                await offerKitDeps(rootDir, readKitDeps(stagedDir), { dryRun: true });
                 process.exitCode = 0;
                 return;
             }
-            await applyLegacy(rootDir, stagedDir, manifest);
+            await applyLegacy(rootDir, stagedDir, manifest, flags.yes);
             // Legacy auto-register succeeded → end-pointer (PVSKILL-002).
             printProvisionPointer({ assumeYes: flags.yes });
             return;
@@ -942,13 +939,17 @@ export async function runUpdate(flags, deps = {}) {
             ...oldLock.files.map((f) => f.path),
             ...manifest.files.map((f) => f.path),
         ]);
-        const disk = hashDiskPaths(rootDir, trackedPaths);
+        const disk = hashDiskPaths(rootDir, trackedPaths, [
+            oldLock.files.find((f) => f.path === KIT_SETTINGS_PATH),
+            manifest.files.find((f) => f.path === KIT_SETTINGS_PATH),
+        ]);
         const diff = diffLockfiles(oldLock, manifest, disk);
         // --dry-run: preview + STOP. No prompts, no apply, no lockfile, no commit.
         // Exit 2 when conflicts exist so the GUI branches on it (0 otherwise). `return`
         // runs the finally → tmpRoot is cleaned (no update-state was written).
         if (flags.dryRun) {
             reportDryRun(diff, manifest);
+            await offerKitDeps(rootDir, readKitDeps(stagedDir), { dryRun: true });
             process.exitCode = diff.conflicts.length > 0 ? DRY_RUN_CONFLICTS_EXIT : 0;
             return;
         }
@@ -978,7 +979,9 @@ export async function runUpdate(flags, deps = {}) {
         // (first entry from a stable lockfile, where `priorLock.beta` is absent).
         const stateManifest = flags.beta ? { ...manifest, beta: true } : manifest;
         writeUpdateState(rootDir, { stagedDir, backupDir, plan, newManifest: stateManifest });
+        const previousSettings = readPreviousSettings(rootDir, backupDir);
         applyPlan(rootDir, stagedDir, plan, backupDir);
+        restoreProjectSettingsKeys(rootDir, plan.writes, previousSettings, kitSettingsKeysOf(oldLock));
         // Lockfile written ONLY after a clean apply. The birth stamp is preserved
         // (agentKitVersion advances; factoryVersion stays frozen). With `--beta`,
         // `stampBeta` composes `stampBirth` and adds `beta:true`; a stable/plain
@@ -989,14 +992,23 @@ export async function runUpdate(flags, deps = {}) {
         // same commit as the rest of the update (and `CLAUDE.md` joins the staged paths —
         // in case B it is in `ignoreLocal`, so the plan never names it).
         const claudeMdInserted = applyClaudeMdRetrofit(rootDir, claudeMd);
-        const pkgMutations = maintainDerivedDotfiles(rootDir, stagedDir, manifest.version);
+        const kitExamples = refreshKitExamples(rootDir, stagedDir, manifest.files.map((f) => f.path));
+        const pkgMutations = maintainDerivedDotfiles(rootDir, stagedDir, manifest);
         const prune = await planPruneMaintenance(rootDir, stagedDir, manifest.files.map((f) => f.path));
-        await maybeCommitBrain(rootDir, manifest.version, [...plan.writes, ...plan.deletes, ...(claudeMdInserted ? [CLAUDE_MD_FILE] : [])], flags, prune);
+        await maybeCommitBrain(rootDir, manifest.version, [
+            ...plan.writes,
+            ...plan.deletes,
+            ...kitExamples,
+            ...(claudeMdInserted ? [CLAUDE_MD_FILE] : []),
+        ], flags, prune);
         // `theirsConflicts` IS the overwritten-local list: same source whether the dev answered
         // the prompt, passed `--theirs-all`, or ran headless — there is no second path. The
         // package.json mutations ride the SAME closing summary, not three loose notices.
         reportSummary(diff, manifest, theirsConflicts, pkgMutations);
         reportClaudeMd(claudeMd, 'applied', claudeMdInserted);
+        // AFTER the brain commit: an install changes package.json and the package lockfile, which
+        // stay out of that commit (Factory#78).
+        await offerKitDeps(rootDir, readKitDeps(stagedDir), { assumeYes: flags.yes });
         // 🔴 The retrofit reminder, on EVERY applied update and regardless of how conflicts
         // were resolved — `--theirs-all`, `--mine-all`, per-file answers or none at all. A
         // retrofit is not a conflict: it is work this command never attempted, living outside
@@ -1006,6 +1018,10 @@ export async function runUpdate(flags, deps = {}) {
         // `oldLock.version` is the version BEFORE this update, which is what separates the guides
         // that just arrived from the ones that were already sitting there. A legacy repo carries
         // `0.0.0`, so every guide reads as new — correct: it has seen none of them.
+        // What changed first, then what still needs hands: the headlines of every kit release
+        // this update crossed, from the changelog that just arrived. Same reasons as the reminder
+        // for printing on every outcome and headless.
+        printWhatsNew({ rootDir, fromVersion: oldLock.version });
         printRetrofitReminder({ rootDir, fromVersion: oldLock.version, guiSignal: flags.launcher });
         await maybeOfferEmptyE2EBranch(rootDir, flags);
         // End-pointer to the next step (PVSKILL-002). Reached only after a clean apply;
@@ -1074,7 +1090,8 @@ async function confirmLegacy(profile, assumeYes) {
         name: 'proceed',
         message: `Este repo no tiene lockfile. Se hará un auto-registro por paths (perfil \`${profile}\`).\n` +
             `${detected}\nLos archivos del cerebro que coincidan se sobrescribirán con la última ` +
-            'versión; tu `CLAUDE.md` se conserva si ya existe. ¿Continuar?',
+            'versión; tu `CLAUDE.md` se conserva si ya existe, y también tus archivos fuera de ' +
+            '`.claude/` y `scripts/tools/` (la versión del kit queda al lado como `.kit-example`). ¿Continuar?',
         initial: false,
     });
     if (!proceed) {
@@ -1087,26 +1104,30 @@ async function confirmLegacy(profile, assumeYes) {
  * NOT deleted on the first sync (design §6.3). Builds the lockfile from the
  * normalized hashes of the installed files.
  */
-async function applyLegacy(rootDir, stagedDir, manifest) {
+async function applyLegacy(rootDir, stagedDir, manifest, assumeYes) {
     const repoPaths = new Set(collectClaudePaths(rootDir));
     const plan = planAutoRegister(manifest, repoPaths);
-    // Everything in the manifest is written (kit-owned overwrite + adds). No
-    // deletes on the first sync. CLAUDE.md is dev-owned (rama B / write-if-absent):
-    // if it already exists on disk it is preserved (filtered out of writes); only
-    // written when absent. The lockfile still records the manifest's CLAUDE.md hash,
-    // so a preserved dev CLAUDE.md reads as "locally edited" on future updates →
-    // always ignoreLocal (rama A), never silently clobbered.
+    // The brain is written whole (kit-owned overwrite + adds). No deletes on the
+    // first sync. CLAUDE.md is dev-owned (rama B / write-if-absent): if it already
+    // exists on disk it is preserved (filtered out of writes); only written when
+    // absent. The lockfile still records the manifest's CLAUDE.md hash, so a
+    // preserved dev CLAUDE.md reads as "locally edited" on future updates → always
+    // ignoreLocal (rama A), never silently clobbered. The other kit files outside
+    // the brain get the same treatment as in `add` (#76): one the repo already has
+    // with its own content is kept, the kit's copy goes to `<path>.kit-example`, and
+    // the lockfile records the kit hash (ignoreLocal until the kit changes it).
     const claudeMdExists = existsSync(path.join(rootDir, CLAUDE_MD_FILE));
-    const writes = manifest.files
-        .map((f) => f.path)
-        .filter((p) => !(p === CLAUDE_MD_FILE && claudeMdExists));
+    const { writes, kept } = partitionInitialWrites(rootDir, manifest);
     const backupDir = defaultBackupDir(path.dirname(stagedDir));
+    const previousSettings = readPreviousSettings(rootDir, backupDir);
     applyPlan(rootDir, stagedDir, { writes, deletes: [] }, backupDir);
+    restoreProjectSettingsKeys(rootDir, writes, previousSettings, LEGACY_KIT_SETTINGS_KEYS);
+    writeKitExamples(rootDir, stagedDir, kept);
     // The lockfile = the manifest (its hashes are already the normalized hashes of
     // the just-installed files) PLUS the birth stamp. A legacy auto-register is the
     // first sync this repo records, so the birth seal = the manifest's version.
     writeLockfile(rootDir, { ...manifest, factoryVersion: manifest.version });
-    const pkgMutations = maintainDerivedDotfiles(rootDir, stagedDir, manifest.version);
+    const pkgMutations = maintainDerivedDotfiles(rootDir, stagedDir, manifest);
     // No brain commit on this path; the block is still kept in step (the index is left to
     // `prune prepare`, which the pending notice names).
     reportPendingPrune(await planPruneMaintenance(rootDir, stagedDir, manifest.files.map((f) => f.path)));
@@ -1115,6 +1136,7 @@ async function applyLegacy(rootDir, stagedDir, manifest) {
         console.log('\nConservé tu `CLAUDE.md` (no se sobrescribió). Verifica que importe las rules del kit ' +
             '(`@.claude/rules/*`); corre `factory doctor` para detectar rules sin importar.');
     }
+    reportKeptRepoFiles(kept);
     if (plan.ambiguous.length > 0) {
         console.log('\nArchivos en `.claude/` que no están en el manifest (revisar manualmente):');
         for (const p of plan.ambiguous)
@@ -1122,4 +1144,6 @@ async function applyLegacy(rootDir, stagedDir, manifest) {
     }
     console.log(`\n✔ Auto-registro completo (v${manifest.version}, perfil ${manifest.profile}): ` +
         `${plan.kitOwned.length} kit-owned, ${plan.toAdd.length} agregados, ${plan.ambiguous.length} ambiguos.`);
+    // No brain commit on this path, so nothing to keep the install out of (Factory#78).
+    await offerKitDeps(rootDir, readKitDeps(stagedDir), { assumeYes });
 }