@timekast/factory 2.3.1 → 2.5.0

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
@@ -42,13 +44,18 @@ import { applyPlan, clearUpdateState, defaultBackupDir, hasUpdateState, readUpda
 import { applyClaudeMdRetrofit, assessClaudeMd, reportClaudeMd, } from '../lib/claude-md.js';
 import { collectClaudePaths } from '../lib/claude-paths.js';
 import { CLIError } from '../lib/cli-error.js';
-import { CLAUDE_MD_FILE, GITATTRIBUTES_FILE, LOCKFILE_FILE, PRETTIERIGNORE_FILE, PROFILES, TIMEKAST_DIR, } from '../lib/constants.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 { hasProvisionState } from '../lib/provision-state.js';
 import { loginCommand } from '../lib/rail.js';
@@ -98,16 +105,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;
 /**
@@ -299,7 +342,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) {
@@ -332,15 +375,20 @@ function runVerify(rootDir) {
  * → prompt y/n · headless → commit by default (a headless run needs it). Stages ONLY
  * what the update touched (the applied manifest paths + lockfile + package.json +
  * .gitattributes) — never `git add -A`. Best-effort: no identity / no repo → warn + skip.
+ * In a pruned repo (`prune` given) it also untracks what the tier restricts, leaves the
+ * restricted applied paths out, and stages `.gitignore`, the switch and the shared kit paths
+ * that are not tracked yet.
  */
-async function maybeCommitBrain(rootDir, version, appliedPaths, flags) {
+async function maybeCommitBrain(rootDir, version, appliedPaths, flags, prune = null) {
     const decision = decideCommit({
         commit: flags.commit,
         noCommit: flags.noCommit,
         isTTY: Boolean(process.stdout.isTTY),
     });
-    if (decision === 'skip')
+    if (decision === 'skip') {
+        reportPendingPrune(prune);
         return;
+    }
     let doCommit = decision === 'commit';
     if (decision === 'prompt') {
         const { yes } = await prompts({
@@ -351,17 +399,31 @@ async function maybeCommitBrain(rootDir, version, appliedPaths, flags) {
         });
         doCommit = yes === true;
     }
-    if (!doCommit)
+    if (!doCommit) {
+        reportPendingPrune(prune);
         return;
+    }
     const candidates = [
-        ...appliedPaths,
+        // A pruned repo never stages what its tier keeps local (it is ignored, and the guard would
+        // refuse it); it DOES stage the shared kit paths not yet tracked (`prune-update.ts`).
+        ...(prune ? appliedPaths.filter((p) => !isRestricted(prune.tier, p)) : appliedPaths),
+        ...(prune ? [...prune.publish, GITIGNORE_FILE, PRUNE_MARKER_PATH] : []),
         `${TIMEKAST_DIR}/${LOCKFILE_FILE}`,
         ...(existsSync(path.join(rootDir, 'package.json')) ? ['package.json'] : []),
         ...(existsSync(path.join(rootDir, GITATTRIBUTES_FILE)) ? [GITATTRIBUTES_FILE] : []),
         ...(existsSync(path.join(rootDir, PRETTIERIGNORE_FILE)) ? [PRETTIERIGNORE_FILE] : []),
     ];
     try {
-        await execa('git', ['add', '--', ...candidates], { cwd: rootDir, reject: false });
+        const stageable = await filterStageable(rootDir, candidates);
+        if (prune && prune.untrack.length > 0) {
+            await execa('git', ['rm', '--cached', '-q', '--ignore-unmatch', '--', ...prune.untrack], {
+                cwd: rootDir,
+                reject: false,
+            });
+        }
+        if (stageable.length > 0) {
+            await execa('git', ['add', '--', ...stageable], { cwd: rootDir, reject: false });
+        }
         // Nothing staged (e.g. a no-op update) → no empty commit.
         const staged = await execa('git', ['diff', '--cached', '--quiet'], {
             cwd: rootDir,
@@ -382,6 +444,34 @@ async function maybeCommitBrain(rootDir, version, appliedPaths, flags) {
         console.warn('Aviso: no se pudo commitear; el cerebro se instaló igual.');
     }
 }
+/**
+ * The brain commit was skipped in a pruned repo: whatever the tier asks the index to change
+ * (untrack a restricted path, publish a newly shared one) is still pending. `prune prepare`
+ * does exactly that and is idempotent, so it is the one instruction to give.
+ */
+function reportPendingPrune(prune) {
+    if (!prune || (prune.untrack.length === 0 && prune.publish.length === 0))
+        return;
+    console.log(`ℹ️  Repo compartido (tier \`${prune.tierName}\`): quedan ${prune.untrack.length} ruta(s) por ` +
+        `dejar de trackear y ${prune.publish.length} por publicar. Corre \`factory prune prepare\` ` +
+        'para commitearlo.');
+}
+/**
+ * Keep only the paths `git add` can take: on disk, or in the index (a deletion to stage).
+ *
+ * ONE path that is in neither — a retired file the dev never committed, which the update just
+ * removed from disk — makes `git add -- a b c` exit 128 having staged NOTHING, so the brain
+ * commit was lost in silence (the warning below only fires when `git commit` fails, and a
+ * clean index commits nothing). Exported for the CLI suite.
+ */
+export async function filterStageable(rootDir, candidates) {
+    const listed = await execa('git', ['ls-files', '-z', '--cached', '--', ...candidates], {
+        cwd: rootDir,
+        reject: false,
+    });
+    const inIndex = new Set(listed.exitCode === 0 ? listed.stdout.split('\0').filter(Boolean) : []);
+    return [...new Set(candidates)].filter((rel) => inIndex.has(rel) || existsSync(path.join(rootDir, rel)));
+}
 /**
  * `--resume`: re-apply a persisted mid-flight state without re-downloading
  * (design §7.5). Reads the staged dir + plan from `.timekast/.update-state.json`.
@@ -416,19 +506,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);
-    await maybeCommitBrain(rootDir, newLock.version, [...state.plan.writes, ...state.plan.deletes, ...(claudeMdInserted ? [CLAUDE_MD_FILE] : [])], flags);
+    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,
+        ...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
@@ -472,10 +575,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). */
@@ -524,63 +626,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
@@ -878,10 +923,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;
@@ -892,13 +938,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;
         }
@@ -928,7 +978,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
@@ -939,13 +991,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);
-        await maybeCommitBrain(rootDir, manifest.version, [...plan.writes, ...plan.deletes, ...(claudeMdInserted ? [CLAUDE_MD_FILE] : [])], flags);
+        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,
+            ...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
@@ -1023,7 +1085,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) {
@@ -1036,31 +1099,39 @@ 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)));
     reportPkgMutations(pkgMutations);
     if (claudeMdExists) {
         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)
@@ -1068,4 +1139,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 });
 }