@timekast/factory 0.1.8 → 1.0.0

package/dist/commands/add.js

@@ -1,47 +1,102 @@
 /**
- * `factory add` — install the `core` brain into an existing repo (design §6.2).
+ * `factory add` — install the brain (`.claude/` + tracked scripts) into an
+ * existing repo (design §6.2).
  *
- * Flow: detect a git repo (cwd or ancestor) → refuse with an actionable message
- * if none → preflight (gh) → download the `core` profile (literal, never `full`)
- * → extract to temp + validate the embedded manifest → move the staged contents
- * into the cwd (only the manifest's files) → write `.timekast/lockfile.json`.
+ * Profile: full-brain is the DEFAULT. `add` auto-detects from the target's
+ * `package.json` — a `factoryVersion` field means the repo was born from the
+ * Factory boilerplate (sk-* + SK.md apply) → `full`; its absence (non-Node repo,
+ * or a Node repo not derived from the kit) → `core`. `--full`/`--core` override.
+ *
+ * Flow: require a git repo → GATE on a pre-existing brain (a lockfile → reject:
+ * use `update`; a `.claude/` without lockfile → redirect to `update`, where the
+ * legacy auto-register lives with its safeguards) → preflight (gh) → resolve
+ * profile → download + stage + validate the manifest → install ONLY the manifest
+ * files via `applyPlan` (so a `full` tarball never lays down `src/`; `track`
+ * excludes it) → write `.timekast/lockfile.json` → ensure `factory:update` (H5).
  *
  * Invariants:
- *   - `add` ONLY ever installs `core`. The profile is the literal `PROFILES.core`,
- *     never a flag — `full` is structurally unreachable from this command.
- *   - `add` never touches `src/`, `package.json`, `pj-*`, or any file outside the
- *     `core` manifest. The `core` tarball contains only `core` files, so moving
- *     its contents in cannot reach dev-owned paths; files in the cwd that are not
- *     in the tarball are left byte-identical.
+ *   - `add` never touches `src/`, `pj-*`, or any file outside the manifest. It
+ *     installs the manifest's files (`.claude/` + tracked scripts + CLAUDE.md),
+ *     never the raw tarball payload — so reusing the `full` tarball cannot reach
+ *     `src/`. cwd files not in the manifest stay byte-identical.
+ *   - CLAUDE.md is dev-owned (write-if-absent): if it already exists on disk it
+ *     is preserved (filtered out of writes) + a warning; only written when absent.
+ *   - `add` is for a repo WITHOUT the brain. A repo that already has `.claude/`
+ *     or a lockfile is routed to `update` (never a raw re-install).
  *   - `add` overwrites manifest files without prompting — the conflict prompt is
- *     exclusive to `update` (DIST-005). Documented in the command's `--help`.
- *   - Atomicity (§7.5): extract + validate in a temp dir before touching the cwd;
- *     a failure mid-flight never leaves a partial `.claude/`.
+ *     exclusive to `update` (DIST-005).
+ *   - Atomicity (§7.5): extract + validate in a temp dir before touching the cwd.
  *
  * Expected failures throw `CLIError`; the top-level handler prints + exits.
  */
-import { mkdtempSync, rmSync } from 'node:fs';
+import { existsSync, mkdtempSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import path from 'node:path';
+import { applyPlan, defaultBackupDir, validateStagedManifest } from '../lib/atomic-swap.js';
 import { CLIError } from '../lib/cli-error.js';
-import { PROFILES } from '../lib/constants.js';
-import { writeInitialLockfile } from '../lib/lockfile.js';
+import { CLAUDE_MD_FILE, PROFILES } from '../lib/constants.js';
+import { hasLockfile, writeInitialLockfile } from '../lib/lockfile.js';
+import { detectProfile, insertFactoryUpdateScript, } from '../lib/package-json.js';
 import { runPreflight } from '../lib/preflight.js';
 import { detectRepo } from '../lib/repo-detection.js';
-import { downloadProfileTarball, moveContentsInto, stageProfileTarball } from '../lib/unpack.js';
+import { downloadProfileTarball, stageProfileTarball } from '../lib/unpack.js';
+import { runUpdate } from './update.js';
 /** Message shown when `add` runs outside any git repo context. */
 const NO_REPO_MESSAGE = 'No hay repositorio git aquí. Ejecuta `git init` primero, o usa `factory new` para crear un proyecto desde cero.';
-export async function runAdd() {
+/** Parse `add`'s argv slice into flags. Unknown flags are ignored here. */
+export function parseAddFlags(argv) {
+    return { core: argv.includes('--core'), full: argv.includes('--full') };
+}
+export async function runAdd(flags = { core: false, full: false }) {
     const cwd = process.cwd();
+    if (flags.core && flags.full) {
+        throw new CLIError('No puedes combinar `--core` con `--full`.');
+    }
     // 1. Require a git repo context (cwd or any ancestor). Refuse before any
-    //    network call or write — nothing is touched when there is no repo.
-    const { hasRepo } = detectRepo(cwd);
+    //    network call or write — nothing is touched when there is no repo. The
+    //    brain lives at the REPO ROOT, so all gating + install target `root`, not
+    //    `cwd` — running `add` from a subdir must not plant a nested second brain.
+    const { hasRepo, repoRoot } = detectRepo(cwd);
     if (!hasRepo) {
         throw new CLIError(NO_REPO_MESSAGE);
     }
-    // 2. Preflight: gh installed + authed + org member. Runs before any download.
+    const root = repoRoot ?? cwd;
+    // 2. Gate on a pre-existing brain (checked at the repo root, not cwd). `add` is
+    //    for a repo WITHOUT one; anything else routes to `update` so the raw
+    //    `applyPlan` install never clobbers an old `.claude/` (leaving orphans, no
+    //    confirm) — `update` has the legacy auto-register with its safeguards.
+    if (hasLockfile(root)) {
+        throw new CLIError('Este repo ya está gestionado por el Factory (tiene `.timekast/lockfile.json`). ' +
+            'Para actualizar el cerebro usa `factory update`.');
+    }
+    if (existsSync(path.join(root, '.claude'))) {
+        // `update` opera sobre process.cwd(); si la raíz es un ancestro, no podemos
+        // redirigir limpio desde un subdir → pedir correr desde la raíz.
+        if (path.resolve(root) !== path.resolve(cwd)) {
+            throw new CLIError(`Este repo ya tiene un cerebro \`.claude/\` en su raíz (${root}). ` +
+                'Corre `factory update` desde la raíz del repo.');
+        }
+        console.log('Este repo ya tiene `.claude/` (sin lockfile). Te redirijo a `factory update`, ' +
+            'que lo registra de forma segura (preserva tus archivos propios y tu CLAUDE.md).\n');
+        await runUpdate({
+            core: flags.core,
+            full: flags.full,
+            theirsAll: false,
+            mineAll: false,
+            resume: false,
+            verify: false,
+        });
+        return;
+    }
+    // 3. Preflight: gh installed + authed + org member. Runs before any download.
     await runPreflight();
-    // 3. Download + unpack into a temp dir, validate, then move into place (§7.5).
+    // 4. Resolve profile: flag override, else auto-detect from package.json (at root).
+    const profile = flags.full
+        ? PROFILES.full
+        : flags.core
+            ? PROFILES.core
+            : detectProfile(root);
+    // 5. Download + unpack into a temp dir, validate, then install into place (§7.5).
     const tmpDir = mkdtempSync(path.join(tmpdir(), 'tk-add-'));
     const cleanup = () => {
         try {
@@ -57,22 +112,62 @@ export async function runAdd() {
     };
     process.once('SIGINT', onSignal);
     process.once('SIGTERM', onSignal);
+    let version;
     try {
-        // `add` is structurally `core`-only: the literal is passed, never a flag.
-        const tarball = await downloadProfileTarball(PROFILES.core, tmpDir);
-        // Extract + validate the embedded manifest before touching the destination.
+        const tarball = await downloadProfileTarball(profile, tmpDir);
         const { stagedDir, manifestRaw } = await stageProfileTarball(tarball, tmpDir);
-        // Move only the tarball's (core) contents into the cwd. Files outside the
-        // manifest — src/, package.json, pj-* — are never visited, so they stay
-        // byte-identical.
-        moveContentsInto(stagedDir, cwd);
+        const manifest = validateStagedManifest(stagedDir, manifestRaw);
+        // Guard: the downloaded tarball must actually be the profile we asked for. A
+        // mispublished asset (e.g. a `full` tag carrying a `core` manifest) would
+        // otherwise write a lockfile for the wrong profile. Refuse loudly.
+        if (manifest.profile !== profile) {
+            throw new CLIError(`El tarball descargado declara perfil \`${manifest.profile}\` pero se pidió \`${profile}\`. ` +
+                'El release está mal publicado; no se modificó nada.');
+        }
+        version = manifest.version;
+        // Install ONLY the manifest's files (never the raw tarball payload — so a
+        // `full` tarball cannot lay down `src/`). CLAUDE.md is dev-owned: filtered out
+        // if it already exists on disk (write-if-absent + warning).
+        const claudeMdExists = existsSync(path.join(root, CLAUDE_MD_FILE));
+        const writes = manifest.files
+            .map((f) => f.path)
+            .filter((p) => !(p === CLAUDE_MD_FILE && claudeMdExists));
+        applyPlan(root, stagedDir, { writes, deletes: [] }, defaultBackupDir(tmpDir));
         // Write the lockfile = the tarball's embedded manifest (no hash recompute).
-        writeInitialLockfile(cwd, manifestRaw);
+        writeInitialLockfile(root, manifestRaw);
+        if (claudeMdExists) {
+            console.log('Conservé tu `CLAUDE.md` (no se sobrescribió). Verifica que importe las rules del kit ' +
+                '(`@.claude/rules/*`); corre `factory doctor` para detectar rules sin importar.');
+        }
     }
     finally {
         process.removeListener('SIGINT', onSignal);
         process.removeListener('SIGTERM', onSignal);
         cleanup();
     }
-    console.log('\n✔ Cerebro `core` instalado. Lockfile escrito en `.timekast/lockfile.json`.');
+    // H5: if the repo is a Node project, add the `pnpm factory:update` convenience by
+    // surgically inserting the script into the EXISTING package.json. Non-fatal — a
+    // missing/invalid package.json just means the dev uses `npx` (the brain is already
+    // installed). We NEVER create a package.json in a non-Node repo.
+    const pkgPath = path.join(root, 'package.json');
+    let scriptAction = 'none';
+    if (existsSync(pkgPath)) {
+        try {
+            scriptAction = insertFactoryUpdateScript(pkgPath).action;
+        }
+        catch {
+            scriptAction = 'none'; // invalid package.json — skip the alias, brain still installed
+        }
+    }
+    console.log(`\n✔ Cerebro \`${profile}\` v${version} instalado. Lockfile escrito en \`.timekast/lockfile.json\`.`);
+    if (scriptAction === 'added' || scriptAction === 'already-correct') {
+        console.log('Para actualizar: `pnpm factory:update` (alias de `npx @timekast/factory update`).');
+    }
+    else {
+        if (scriptAction === 'conflict') {
+            console.warn('Aviso: `factory:update` ya existe en package.json con otro valor; no se sobrescribió.');
+        }
+        console.log('Para actualizar: `npx @timekast/factory update` desde la raíz del repo,');
+        console.log('o instala el CLI una vez (`npm i -g @timekast/factory`) y corre `factory update`.');
+    }
 }

package/dist/commands/doctor.js

@@ -18,7 +18,17 @@
  */
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import path from 'node:path';
+import { CLAUDE_MD_FILE } from '../lib/constants.js';
 import { hasLockfile, normalizeThenHash, readLockfile } from '../lib/lockfile.js';
+import { detectRepo } from '../lib/repo-detection.js';
+/** Matches a flat always-on rule file shipped by the kit (`.claude/rules/<name>.md`). */
+const RULE_PATH_RE = /^\.claude\/rules\/[^/]+\.md$/;
+/**
+ * Matches ONLY the reserved on-demand rules heading (`Rules (on-demand reference)`
+ * and close variants), not any heading that merely contains "on-demand" (e.g.
+ * `## On-demand migration notes`).
+ */
+const ON_DEMAND_HEADING_RE = /rules?\s*\(\s*on-demand/i;
 /**
  * The A1 security notice (design §1 + §11, decision A1). Literal text emitted at
  * the end of every `doctor` run so the dev always sees the `src/` responsibility
@@ -55,6 +65,55 @@ function collectClaudePaths(rootDir) {
     walk('.claude');
     return out;
 }
+/**
+ * Concatenate the body of the reserved "on-demand reference" section of CLAUDE.md
+ * — the lines under a heading matching `ON_DEMAND_HEADING_RE`, until the next
+ * heading of the SAME or HIGHER level (a deeper nested heading stays inside the
+ * section). Rules listed there are loaded by skills on demand (NOT via `@import`),
+ * so they must not be flagged as unimported. Empty string when no such section.
+ *
+ * Level-aware (a nested `###` under a `##` on-demand heading does not end it) and
+ * specific (only the reserved heading starts it, not any "on-demand" mention).
+ */
+function onDemandSectionText(claudeMd) {
+    const out = [];
+    let sectionLevel = 0; // 0 = not currently inside an on-demand section
+    for (const line of claudeMd.split('\n')) {
+        const heading = /^(#{1,6})\s+(.*)$/.exec(line);
+        if (heading) {
+            const level = heading[1].length;
+            const isOnDemand = ON_DEMAND_HEADING_RE.test(heading[2]);
+            if (sectionLevel === 0) {
+                if (isOnDemand)
+                    sectionLevel = level; // enter the section
+            }
+            else if (level <= sectionLevel) {
+                // sibling/higher heading ends the section (unless it is on-demand too)
+                sectionLevel = isOnDemand ? level : 0;
+            }
+            // a deeper heading (level > sectionLevel) stays inside → no change
+            continue;
+        }
+        if (sectionLevel > 0)
+            out.push(line);
+    }
+    return out.join('\n');
+}
+/**
+ * Collect the rule paths a CLAUDE.md actually `@import`s — a line whose trimmed
+ * text is `@<path>` (the real import directive). A prose mention or a fenced
+ * code block ("no agregues `@.claude/rules/SK.md`") is NOT a bare directive line,
+ * so it does not count as imported.
+ */
+function importedRulePaths(claudeMd) {
+    const paths = new Set();
+    for (const raw of claudeMd.split('\n')) {
+        const line = raw.trim();
+        if (line.startsWith('@'))
+            paths.add(line.slice(1).trim());
+    }
+    return paths;
+}
 /**
  * Compute the doctor diagnosis. No lockfile → `noLockfile: true` (the caller
  * renders the "run factory:update" advice). Otherwise diffs the on-disk
@@ -63,9 +122,19 @@ function collectClaudePaths(rootDir) {
  *   - conflict = tracked path whose normalized disk hash != recorded hash.
  */
 export function computeDoctor(deps = {}) {
-    const rootDir = deps.rootDir ?? process.cwd();
+    // Diagnose at the REPO ROOT (where the brain + lockfile live), not cwd — so
+    // `doctor` from a subdir of a managed repo reports the real state instead of
+    // "no lockfile" (consistency with `add`/`update`). Tests inject `rootDir`.
+    const rootDir = deps.rootDir ?? detectRepo(process.cwd()).repoRoot ?? process.cwd();
     if (!hasLockfile(rootDir)) {
-        return { orphans: [], conflicts: [], a1Warning: A1_WARNING, noLockfile: true };
+        return {
+            orphans: [],
+            conflicts: [],
+            unimportedRules: [],
+            claudeMdMissing: false,
+            a1Warning: A1_WARNING,
+            noLockfile: true,
+        };
     }
     const lock = readLockfile(rootDir);
     const manifestPaths = new Set(lock.files.map((f) => f.path));
@@ -85,7 +154,37 @@ export function computeDoctor(deps = {}) {
         }
     }
     conflicts.sort();
-    return { orphans, conflicts, a1Warning: A1_WARNING, noLockfile: false };
+    // Unimported kit rules: a kit-shipped always-on rule (`.claude/rules/*.md`)
+    // that is NOT `@import`ed by CLAUDE.md → it does NOT load at runtime. The check
+    // is strict on the `@import` directive (a prose mention does NOT count — a
+    // mentioned-but-not-imported always-on rule is dead). Exception: a rule listed
+    // under an "on-demand" heading is loaded by skills on demand, not via @import,
+    // so it is excluded. No CLAUDE.md on disk in a managed repo → can't check, and
+    // every rule is dead → flagged via `claudeMdMissing` instead.
+    const unimportedRules = [];
+    const claudeMdPath = path.join(rootDir, CLAUDE_MD_FILE);
+    const claudeMdMissing = !existsSync(claudeMdPath);
+    if (!claudeMdMissing) {
+        const claudeMd = readFileSync(claudeMdPath, 'utf8');
+        const imported = importedRulePaths(claudeMd); // bare `@<path>` directive lines
+        const onDemand = onDemandSectionText(claudeMd);
+        for (const entry of lock.files) {
+            if (!RULE_PATH_RE.test(entry.path))
+                continue;
+            const isOnDemand = onDemand.includes(entry.path);
+            if (!imported.has(entry.path) && !isOnDemand)
+                unimportedRules.push(entry.path);
+        }
+        unimportedRules.sort();
+    }
+    return {
+        orphans,
+        conflicts,
+        unimportedRules,
+        claudeMdMissing,
+        a1Warning: A1_WARNING,
+        noLockfile: false,
+    };
 }
 /** Render the doctor result to the console. The A1 notice is ALWAYS last. */
 function renderDoctor(result) {
@@ -96,10 +195,17 @@ function renderDoctor(result) {
         console.log(`\n${result.a1Warning}`);
         return;
     }
-    if (result.orphans.length === 0 && result.conflicts.length === 0) {
-        console.log('✔ Sin huérfanos ni conflictos pendientes.');
+    if (result.orphans.length === 0 &&
+        result.conflicts.length === 0 &&
+        result.unimportedRules.length === 0 &&
+        !result.claudeMdMissing) {
+        console.log('✔ Sin huérfanos, conflictos ni rules sin importar.');
     }
     else {
+        if (result.claudeMdMissing) {
+            console.log('🔴 Falta `CLAUDE.md` en la raíz: las rules del kit NO se cargan (el auto-load es por ' +
+                '`@import` desde ese archivo). Recupéralo (`git checkout -- CLAUDE.md`) o corre `factory update`.');
+        }
         if (result.conflicts.length > 0) {
             console.log('Modificados localmente respecto al lockfile (conflicto si el Factory los actualiza):');
             for (const p of result.conflicts) {
@@ -107,6 +213,12 @@ function renderDoctor(result) {
             }
             console.log('  Sugerencia: corre `factory:update --verify` para re-chequear, o `factory:update` para reconciliar.');
         }
+        if (result.unimportedRules.length > 0) {
+            console.log('\nRules del kit que tu `CLAUDE.md` no importa (no se cargan en runtime):');
+            for (const p of result.unimportedRules) {
+                console.log(`  • ${p} — agrega \`@${p}\` a tu CLAUDE.md o no se aplicará`);
+            }
+        }
         if (result.orphans.length > 0) {
             console.log('\nArchivos huérfanos (en `.claude/` fuera del manifest instalado):');
             for (const p of result.orphans) {

package/dist/commands/new.js

@@ -17,7 +17,7 @@ import { execa } from 'execa';
 import prompts from 'prompts';
 import { CLIError } from '../lib/cli-error.js';
 import { FACTORY_ORG, PROFILES } from '../lib/constants.js';
-import { writeInitialLockfile } from '../lib/lockfile.js';
+import { parseLockfile, writeInitialLockfile } from '../lib/lockfile.js';
 import { applyPackageJsonEdits } from '../lib/package-json.js';
 import { runPreflight } from '../lib/preflight.js';
 import { downloadProfileTarball, moveContentsInto, stageProfileTarball } from '../lib/unpack.js';
@@ -87,10 +87,12 @@ export async function runNew(name) {
     };
     process.once('SIGINT', onSignal);
     process.once('SIGTERM', onSignal);
+    let version = '';
     try {
         const tarball = await downloadProfileTarball(profile, tmpDir);
         // Extract + validate the embedded manifest before touching the destination.
         const { stagedDir, manifestRaw } = await stageProfileTarball(tarball, tmpDir);
+        version = parseLockfile(manifestRaw, 'manifest').version;
         // Move contents into ./<name>/ (without the Factory's git lineage).
         mkdirSync(destDir, { recursive: true });
         moveContentsInto(stagedDir, destDir);
@@ -126,6 +128,7 @@ export async function runNew(name) {
         process.removeListener('SIGTERM', onSignal);
         cleanup();
     }
-    console.log(`\n✔ Proyecto \`${validName}\` listo. Repo: ${FACTORY_ORG}/${validName}`);
+    console.log(`\n✔ Proyecto \`${validName}\` listo (perfil \`${profile}\`, cerebro v${version}). ` +
+        `Repo: ${FACTORY_ORG}/${validName}`);
     console.log(`  cd ${validName}`);
 }

package/dist/commands/update.js

@@ -4,24 +4,27 @@
  *
  * Flow:
  *   1. Preflight (gh) — reused from DIST-003, never reimplemented.
- *   2. Read the lockfile → the STICKY profile (`core` | `full`). Download the
- *      tarball of the SAME profile (never cross-grade). A `core` repo therefore
- *      never receives `sk-*` (not in the core manifest); a new `kb-*` in the
- *      core manifest does land.
+ *   2. Resolve the profile. With a lockfile it is STICKY (`core` | `full`),
+ *      EXCEPT `--full` cross-grades a `core` repo → `full` (additive: adds
+ *      sk-* + SK.md, swaps CLAUDE.md to the full one); `--core` on a `full` repo
+ *      is a rejected downgrade. With no lockfile (legacy) the profile is
+ *      auto-detected from package.json (`factoryVersion` → full, else core),
+ *      overridable with `--full`/`--core`. Download the tarball of that profile.
  *   3. Stage + validate the embedded manifest (the swap preflight rejects a
  *      corrupt/empty manifest before touching the FS).
  *   4. Diff the new manifest against the lockfile → the 4 buckets + conflicts.
  *   5. Resolve conflicts: `--theirs-all` / `--mine-all`, else prompt PER FILE
  *      with NO default option (design §7.3) — the file is not modified until the
- *      dev chooses.
+ *      dev chooses. CLAUDE.md never conflicts (dev-owned → ignoreLocal).
  *   6. Apply atomically (backup + rollback guard, design §7.5).
  *   7. Write the lockfile (= the new manifest) ONLY after a clean apply.
  *   8. Surgically ensure `factory:update` is in package.json (design §7.4).
  *
  * 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.
- * The dev is warned before proceeding.
+ * 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.
  *
  * `--verify`: compares disk vs lockfile and reports drift WITHOUT modifying
  * anything. `--resume`: re-applies a persisted mid-flight state without
@@ -36,9 +39,11 @@ import path from 'node:path';
 import prompts from 'prompts';
 import { applyPlan, clearUpdateState, defaultBackupDir, hasUpdateState, readUpdateState, validateStagedManifest, writeUpdateState, } from '../lib/atomic-swap.js';
 import { CLIError } from '../lib/cli-error.js';
+import { CLAUDE_MD_FILE, PROFILES } from '../lib/constants.js';
 import { diffLockfiles, hasLockfile, normalizeThenHash, planAutoRegister, readLockfile, writeLockfile, } from '../lib/lockfile.js';
-import { insertFactoryUpdateScript, setAgentKitVersion } from '../lib/package-json.js';
+import { detectProfile, insertFactoryUpdateScript, setAgentKitVersion, } from '../lib/package-json.js';
 import { runPreflight } from '../lib/preflight.js';
+import { detectRepo } from '../lib/repo-detection.js';
 import { downloadProfileTarball, stageProfileTarball } from '../lib/unpack.js';
 /** Parse `update`'s argv slice into flags. Unknown flags are ignored here. */
 export function parseUpdateFlags(argv) {
@@ -47,6 +52,8 @@ export function parseUpdateFlags(argv) {
         mineAll: argv.includes('--mine-all'),
         resume: argv.includes('--resume'),
         verify: argv.includes('--verify'),
+        core: argv.includes('--core'),
+        full: argv.includes('--full'),
     };
 }
 /** Default acquire: download the sticky-profile tarball, stage + validate it. */
@@ -216,11 +223,20 @@ function warnOnScriptConflict(action, _pkgPath) {
  * semver) are untouched.
  */
 function maintainDerivedPkg(pkgPath, agentKitVersion) {
-    warnOnScriptConflict(insertFactoryUpdateScript(pkgPath).action, pkgPath);
-    setAgentKitVersion(pkgPath, agentKitVersion);
+    // Tolerant (mirrors `add`): a malformed package.json must NOT throw AFTER the
+    // brain was already applied + the lockfile written — the install succeeded; the
+    // script/version mirror is best-effort. Warn and move on.
+    try {
+        warnOnScriptConflict(insertFactoryUpdateScript(pkgPath).action, pkgPath);
+        setAgentKitVersion(pkgPath, agentKitVersion);
+    }
+    catch {
+        console.warn('Aviso: no se pudo actualizar package.json (¿JSON inválido?); el cerebro se instaló igual. ' +
+            'Corrige package.json y vuelve a correr `factory update` para sincronizar agentKitVersion.');
+    }
 }
 /** Print the deletes + kept-retired (design §7.6 — visible) + a one-line summary. */
-function reportSummary(diff) {
+function reportSummary(diff, manifest) {
     if (diff.deleteSilent.length > 0) {
         console.log('\nArchivos retirados por el Factory en esta versión:');
         for (const e of diff.deleteSilent)
@@ -233,7 +249,8 @@ function reportSummary(diff) {
     }
     const unchanged = diff.unchanged.length > 0 ? ` (${diff.unchanged.length} sin cambios)` : '';
     const kept = diff.keptRetiredLocal.length > 0 ? `, ${diff.keptRetiredLocal.length} conservados` : '';
-    console.log(`\n✔ update: ${diff.add.length} agregados, ${diff.overwriteSilent.length} actualizados${unchanged}, ` +
+    console.log(`\n✔ update a v${manifest.version} (perfil ${manifest.profile}): ${diff.add.length} agregados, ` +
+        `${diff.overwriteSilent.length} actualizados${unchanged}, ` +
         `${diff.deleteSilent.length} retirados${kept}, ${diff.conflicts.length} conflictos.`);
 }
 /**
@@ -241,7 +258,19 @@ function reportSummary(diff) {
  * network seam (tests inject a local fixture).
  */
 export async function runUpdate(flags, deps = {}) {
-    const rootDir = process.cwd();
+    // Operate on the REPO ROOT (the brain + lockfile live there), not cwd — running
+    // `update` from a subdir of a managed repo must not miss the lockfile and
+    // legacy-register a second nested brain (consistency with `add`).
+    const rootDir = detectRepo(process.cwd()).repoRoot ?? process.cwd();
+    // Mutually-exclusive flag validation FIRST — before --verify/--resume
+    // short-circuit, so an invalid combination is always rejected (not silently
+    // honored by verify/resume).
+    if (flags.theirsAll && flags.mineAll) {
+        throw new CLIError('No puedes combinar `--theirs-all` con `--mine-all`.');
+    }
+    if (flags.core && flags.full) {
+        throw new CLIError('No puedes combinar `--core` con `--full`.');
+    }
     // --verify and --resume short-circuit (no download).
     if (flags.verify) {
         runVerify(rootDir);
@@ -254,28 +283,46 @@ export async function runUpdate(flags, deps = {}) {
         runResume(rootDir);
         return;
     }
-    if (flags.theirsAll && flags.mineAll) {
-        throw new CLIError('No puedes combinar `--theirs-all` con `--mine-all`.');
-    }
     // Preflight (gh) before any download — reused, not reimplemented.
     await runPreflight();
     const legacy = !hasLockfile(rootDir);
-    // Sticky profile: a lockfile pins the installed profile; a legacy repo with no
-    // lockfile defaults to `core` (the additive baseline a pre-CLI repo carries).
+    // Profile resolution:
+    //   - legacy (no lockfile): auto-detect from package.json (`factoryVersion` →
+    //     full, else core), unless a flag forces it. This is the adoption path for
+    //     pre-CLI derivatives, so full-brain is the default for Factory repos.
+    //   - lockfile'd: sticky to the recorded profile, EXCEPT `--full` cross-grades
+    //     a `core` repo → `full` (additive: adds sk-* + SK.md, swaps CLAUDE.md to the
+    //     full one). `--core` on a `full` repo is a downgrade → rejected.
     let oldLock;
     let profile;
     if (legacy) {
-        profile = 'core';
+        profile = flags.full ? PROFILES.full : flags.core ? PROFILES.core : detectProfile(rootDir);
         oldLock = { version: '0.0.0', profile, files: [] };
-        await confirmLegacy();
+        await confirmLegacy(profile);
     }
     else {
         oldLock = readLockfile(rootDir);
-        profile = oldLock.profile;
+        if (flags.full && oldLock.profile === PROFILES.core) {
+            profile = PROFILES.full; // cross-grade core → full (additive)
+        }
+        else if (flags.core && oldLock.profile === PROFILES.full) {
+            throw new CLIError('Este repo está registrado como `full`; el downgrade a `core` no está soportado ' +
+                '(implicaría borrar sk-*/SK.md). Si de verdad lo quieres, hazlo a mano.');
+        }
+        else {
+            profile = oldLock.profile; // sticky (--full on full / --core on core = refresh)
+        }
     }
     const acquire = deps.acquire ?? acquireFromRelease;
     const { stagedDir, manifest, tmpRoot } = await acquire(profile);
     try {
+        // Guard: the downloaded tarball must match the resolved profile. A mispublished
+        // asset (e.g. a `full` tag carrying a `core` manifest) would otherwise write a
+        // lockfile for the wrong profile or silently no-op a cross-grade. Refuse loudly.
+        if (manifest.profile !== profile) {
+            throw new CLIError(`El tarball descargado declara perfil \`${manifest.profile}\` pero se resolvió \`${profile}\`. ` +
+                'El release está mal publicado; no se modificó nada.');
+        }
         if (legacy) {
             await applyLegacy(rootDir, stagedDir, manifest);
             return;
@@ -314,19 +361,31 @@ export async function runUpdate(flags, deps = {}) {
         const pkgPath = path.join(rootDir, 'package.json');
         if (existsSync(pkgPath))
             maintainDerivedPkg(pkgPath, manifest.version);
-        reportSummary(diff);
+        reportSummary(diff, manifest);
     }
     finally {
-        rmSync(tmpRoot, { recursive: true, force: true });
+        // Keep the staged tarball if an update-state survives (a post-apply failure —
+        // e.g. writeLockfile threw after applyPlan): the persisted state points into
+        // tmpRoot, so deleting it would strand `--resume` with a vanished stagedDir
+        // and no recovery. A clean run clears the state first → tmpRoot is removed.
+        if (!hasUpdateState(rootDir)) {
+            rmSync(tmpRoot, { recursive: true, force: true });
+        }
     }
 }
 /** Warn the dev before a legacy auto-register sync (design §8 edge case). */
-async function confirmLegacy() {
+async function confirmLegacy(profile) {
+    const detected = profile === PROFILES.full
+        ? 'Detectado como derivado del Factory (`factoryVersion` en package.json) → perfil `full` ' +
+            '(incluye sk-* + SK.md). Usa `--core` si quieres solo el cerebro base.'
+        : 'Detectado como repo de otro stack (sin `factoryVersion`) → perfil `core` (sin sk-*). ' +
+            'Usa `--full` si es un derivado Next del Factory.';
     const { proceed } = await prompts({
         type: 'confirm',
         name: 'proceed',
-        message: 'Este repo no tiene lockfile. Se hará un auto-registro por paths. Los archivos del cerebro ' +
-            'que coincidan se sobrescribirán con la última versión. ¿Continuar?',
+        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?',
         initial: false,
     });
     if (!proceed) {
@@ -343,8 +402,15 @@ async function applyLegacy(rootDir, stagedDir, manifest) {
     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.
-    const writes = manifest.files.map((f) => f.path);
+    // 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.
+    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 backupDir = defaultBackupDir(path.dirname(stagedDir));
     applyPlan(rootDir, stagedDir, { writes, deletes: [] }, backupDir);
     // The lockfile = the manifest (its hashes are already the normalized hashes of
@@ -354,11 +420,15 @@ async function applyLegacy(rootDir, stagedDir, manifest) {
     const pkgPath = path.join(rootDir, 'package.json');
     if (existsSync(pkgPath))
         maintainDerivedPkg(pkgPath, manifest.version);
+    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.');
+    }
     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)
             console.log(`  • ambiguo — revisar manualmente: ${p}`);
     }
-    console.log(`\n✔ Auto-registro completo: ${plan.kitOwned.length} kit-owned, ${plan.toAdd.length} agregados, ` +
-        `${plan.ambiguous.length} ambiguos.`);
+    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.`);
 }

package/dist/index.js

@@ -10,7 +10,7 @@ import { readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { CLIError } from './lib/cli-error.js';
-import { runAdd } from './commands/add.js';
+import { parseAddFlags, runAdd } from './commands/add.js';
 import { runDoctor } from './commands/doctor.js';
 import { runNew } from './commands/new.js';
 import { runStatus } from './commands/status.js';
@@ -23,23 +23,27 @@ Uso:
 
 Comandos:
   new <Nombre>     Crea un proyecto derivado nuevo (repo + perfil + git init)
-  add              Instala el cerebro \`core\` (.claude/) en el repo actual
+  add              Instala el cerebro (.claude/) en el repo actual
   update           Actualiza el cerebro al día sin pisar tu trabajo local
   status           Reporta la versión instalada vs. la última disponible
-  doctor           Detecta huérfanos y conflictos pendientes + aviso de seguridad
+  doctor           Detecta huérfanos, conflictos y rules sin importar + aviso de seguridad
 
 Sobre \`add\`:
-  Requiere estar dentro de un repo git (al menos \`git init\`). Nunca toca tu
-  \`src/\`, tu \`package.json\` ni tus archivos propios (\`pj-*\`): solo escribe los
-  archivos del perfil \`core\`. Si un archivo del \`core\` ya existe, lo sobrescribe
-  sin preguntar (el manejo de conflictos es exclusivo de \`update\`).
+  Requiere estar dentro de un repo git (al menos \`git init\`). Por default instala
+  el cerebro \`full\` (incluye sk-* + SK.md) si el repo es un derivado del Factory
+  (tiene \`factoryVersion\` en package.json); si no, instala \`core\` (sin sk-*).
+  Flags: --full / --core fuerzan el perfil. Nunca toca tu \`src/\` ni tus archivos
+  propios; instala solo los archivos del manifest. Tu \`CLAUDE.md\` se conserva si
+  ya existe. Si el repo ya tiene \`.claude/\` o lockfile, te redirige a \`update\`.
 
 Sobre \`update\`:
-  Lee el perfil instalado del lockfile y baja el tarball del MISMO perfil (nunca
-  cross-grada). Compara contra el lockfile y aplica solo cambios de \`.claude/\`:
-  agrega lo nuevo, sobrescribe lo del kit sin cambios locales, retira lo que el
-  Factory borró, y pregunta (sin opción default) ante un conflicto. Nunca toca
-  \`src/\` ni tus archivos propios. Flags:
+  Con lockfile, es sticky al perfil instalado; sin lockfile (legacy), auto-detecta
+  el perfil (igual que \`add\`). Compara contra el lockfile y aplica solo cambios de
+  \`.claude/\`: agrega lo nuevo, sobrescribe lo del kit sin cambios locales, retira
+  lo que el Factory borró, y pregunta (sin opción default) ante un conflicto. Tu
+  \`CLAUDE.md\` nunca se sobrescribe en silencio. Nunca toca \`src/\`. Flags:
+    --full         Sube un repo \`core\` a \`full\` (cross-grade aditivo: + sk-*/SK.md)
+    --core         Fuerza \`core\` en un install legacy (downgrade de full→core no soportado)
     --theirs-all   Resuelve todos los conflictos con la versión del Factory
     --mine-all     Conserva tu versión en todos los conflictos
     --resume       Retoma un update interrumpido sin re-descargar
@@ -88,7 +92,7 @@ async function main(argv) {
             return;
         }
         case 'add': {
-            await runAdd();
+            await runAdd(parseAddFlags(rest));
             return;
         }
         case 'update': {

package/dist/lib/atomic-swap.js

@@ -23,8 +23,27 @@
 import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, rmdirSync, rmSync, writeFileSync, } from 'node:fs';
 import path from 'node:path';
 import { CLIError } from './cli-error.js';
-import { TIMEKAST_DIR } from './constants.js';
+import { CLAUDE_MD_FILE, TIMEKAST_DIR } from './constants.js';
 import { parseLockfile } from './lockfile.js';
+/** Roots a manifest path may live under (mirrors `profiles.json#track`). */
+const ALLOWED_ROOTS = ['.claude/', 'scripts/'];
+/**
+ * Reject a manifest path that is unsafe to write: absolute, escaping via `..`, or
+ * outside the tracked scope (`.claude/**`, `scripts/**`, `CLAUDE.md`). A correct
+ * release never produces these — this guards a mispublished/tampered tarball from
+ * writing `src/` or escaping the repo root. Separator-agnostic (Windows-safe).
+ */
+function assertSafeTrackedPath(rel) {
+    const segments = rel.split(/[\\/]/);
+    if (rel.length === 0 || path.isAbsolute(rel) || segments.includes('..')) {
+        throw new CLIError(`El manifest declara un path inseguro \`${rel}\` (absoluto o con \`..\`); no se tocó nada.`);
+    }
+    const tracked = rel === CLAUDE_MD_FILE || ALLOWED_ROOTS.some((root) => rel.startsWith(root));
+    if (!tracked) {
+        throw new CLIError(`El manifest declara \`${rel}\`, fuera del scope rastreado (\`.claude/\`, \`scripts/\`, \`CLAUDE.md\`). ` +
+            'El release está mal construido; no se tocó nada.');
+    }
+}
 /** Name of the resume-state sidecar inside `.timekast/`. */
 export const UPDATE_STATE_FILE = '.update-state.json';
 /** Absolute path to the resume-state sidecar inside a project root. */
@@ -80,6 +99,8 @@ export function clearUpdateState(rootDir) {
 export function validateStagedManifest(stagedDir, manifestRaw) {
     const manifest = parseLockfile(manifestRaw, 'manifest embebido');
     for (const entry of manifest.files) {
+        // Path safety BEFORE any existence check: never resolve an unsafe path.
+        assertSafeTrackedPath(entry.path);
         if (!existsSync(path.join(stagedDir, entry.path))) {
             throw new CLIError(`El tarball está incompleto: falta \`${entry.path}\` declarado en el manifest. ` +
                 'No se tocó ningún archivo.');

package/dist/lib/constants.js

@@ -16,6 +16,16 @@ export const PROFILES = {
 export const TIMEKAST_DIR = '.timekast';
 export const MANIFEST_FILE = 'manifest.json';
 export const LOCKFILE_FILE = 'lockfile.json';
+/**
+ * Repo-root path of the runtime entrypoint markdown. It is a tracked manifest
+ * file (via `track` + the `core` rename `CLAUDE.core.md → CLAUDE.md`), so it
+ * flows through the diff/install engine. It gets special handling because it is
+ * dev-owned after bootstrap (it carries project-specific sections + `@import`s):
+ * a derived repo's edited CLAUDE.md is never silently overwritten or prompted on
+ * `update` (lockfile path), and never clobbered by `add`/legacy if it already
+ * exists on disk (path-match path). See `diffLockfiles` + the install commands.
+ */
+export const CLAUDE_MD_FILE = 'CLAUDE.md';
 /** The script the CLI injects into a derived project's package.json. */
 export const UPDATE_SCRIPT_NAME = 'factory:update';
 // `npx` so the script resolves in a fresh derived repo where @timekast/factory

package/dist/lib/lockfile.js

@@ -32,7 +32,7 @@ import { createHash } from 'node:crypto';
 import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { CLIError } from './cli-error.js';
-import { LOCKFILE_FILE, MANIFEST_FILE, TIMEKAST_DIR } from './constants.js';
+import { CLAUDE_MD_FILE, LOCKFILE_FILE, MANIFEST_FILE, TIMEKAST_DIR, } from './constants.js';
 /**
  * Write the initial lockfile in `destDir/.timekast/lockfile.json` (used by
  * `new` / `add`). On the initial install the lockfile carries the tarball's
@@ -185,6 +185,18 @@ export function diffLockfiles(oldLock, newManifest, diskHashes) {
         ignoreLocal: [],
         conflicts: [],
     };
+    // CLAUDE.md special-case (rama A): it is dev-owned after bootstrap, so it must
+    // NEVER prompt. Any path that would classify it as a `conflict` instead routes
+    // it to `ignoreLocal` (kept as-is, silently). The clean kit-owned branches
+    // (`add` / `overwriteSilent` / `unchanged`) stay normal, so a clean CLAUDE.md
+    // still propagates — e.g. a core→full cross-grade swaps in the full CLAUDE.md
+    // that imports `@.claude/rules/SK.md`, and new always-on rules reach it.
+    const recordConflict = (entry) => {
+        if (entry.path === CLAUDE_MD_FILE)
+            diff.ignoreLocal.push(entry.path);
+        else
+            diff.conflicts.push(entry);
+    };
     // Walk the new manifest: add / overwriteSilent / conflicts.
     for (const newEntry of newManifest.files) {
         const localHash = diskHashes.get(newEntry.path);
@@ -203,7 +215,7 @@ export function diffLockfiles(oldLock, newManifest, diskHashes) {
                 diff.unchanged.push(newEntry);
             }
             else {
-                diff.conflicts.push({
+                recordConflict({
                     path: newEntry.path,
                     localHash,
                     registeredHash: localHash, // no prior record; treat current as baseline
@@ -233,8 +245,9 @@ export function diffLockfiles(oldLock, newManifest, diskHashes) {
             diff.unchanged.push(newEntry);
         }
         else {
-            // Edited locally AND changed by the Factory, diverging → conflict.
-            diff.conflicts.push({
+            // Edited locally AND changed by the Factory, diverging → conflict
+            // (CLAUDE.md routes to ignoreLocal instead — see recordConflict).
+            recordConflict({
                 path: newEntry.path,
                 localHash,
                 registeredHash,

package/dist/lib/package-json.js

@@ -5,9 +5,35 @@
  * indentation, never rewriting the whole document. The dev's deps, scripts,
  * field order and formatting are preserved.
  */
-import { readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
 import { CLIError } from './cli-error.js';
-import { UPDATE_SCRIPT_CMD, UPDATE_SCRIPT_NAME } from './constants.js';
+import { PROFILES, UPDATE_SCRIPT_CMD, UPDATE_SCRIPT_NAME } from './constants.js';
+/**
+ * Auto-detect the profile to install into an existing repo from its
+ * `package.json`: a `factoryVersion` field means the repo was born from the
+ * Factory boilerplate (the `sk-*` skills + `SK.md` rule apply) → `full`. Its
+ * absence — including a non-Node repo with no `package.json`, or an invalid one —
+ * means the repo is not a Factory derivative → `core`.
+ *
+ * Tolerant by design: any read/parse failure degrades to `core`, never throws.
+ * A `--full` / `--core` flag overrides this (the caller decides). The signal is
+ * one-time: once a lockfile records the profile, `update` is sticky to it.
+ */
+export function detectProfile(rootDir) {
+    const pkgPath = path.join(rootDir, 'package.json');
+    try {
+        if (!existsSync(pkgPath))
+            return PROFILES.core;
+        const pkg = parsePackageJson(readFileSync(pkgPath, 'utf8'));
+        return typeof pkg.factoryVersion === 'string' && pkg.factoryVersion.length > 0
+            ? PROFILES.full
+            : PROFILES.core;
+    }
+    catch {
+        return PROFILES.core;
+    }
+}
 /** Detect the indentation used by an existing JSON document (defaults to 2 spaces). */
 function detectIndent(raw) {
     const match = raw.match(/^(\s+)"/m);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timekast/factory",
-  "version": "0.1.8",
+  "version": "1.0.0",
   "description": "Public, thin CLI to bootstrap and maintain TimeKast Factory derived projects.",
   "type": "module",
   "license": "UNLICENSED",