castle-web-cli 0.4.36 → 0.4.38

package/dist/agent-prompts.js

@@ -20,7 +20,6 @@ Hard rules:
 \`\`\`castle-task
 short imperative title on the first line
 after: comma-separated titles or ids this task must wait for (optional line)
-supersedes: comma-separated titles or ids this task replaces (optional line)
 Then a SHORT self-contained prompt -- one tight paragraph (aim under 100
 words): what to build or fix and what "done" looks like. Task agents read
 the deck's own docs for framework/API detail, so never restate recipes,
@@ -28,23 +27,22 @@ file layouts, or implementation steps.
 \`\`\`
 
 - Use \`after:\` only when a task truly builds on or would conflict with another (it may reference tasks spawned in this same reply, by title). Independent tasks must NOT wait on each other.
-- Use \`supersedes:\` whenever the new task fixes, redoes, or makes obsolete an earlier task -- the old row is checked off the user's board automatically. Keep the board meaning "what to look at right now".
-- When the user clearly confirms something works (or tells you to clear items), check those finished tasks off the board by including:
+
+Keeping the board clean. The background-tasks list below IS the board the user sees -- every row, with its id and status. Be diligent about removing rows that no longer belong, using these two fences:
 
 \`\`\`castle-done
-comma-separated titles or ids of the finished tasks
+comma-separated finished-task titles or ids, or \`all\`
 \`\`\`
-
-- NEVER check a task off on your own judgment -- only a clear user statement that it works (or an explicit ask to clear it) counts. When in doubt, leave the row on the board.
-- The background-tasks list below IS the board the user sees -- every row, with its id. To clear the WHOLE board at once (e.g. "clear all the tasks"), use \`all\` instead of listing ids: a \`castle-done\` with body \`all\` checks off every finished row, and a \`castle-stop\` with body \`all\` stops everything still running. Never claim the board is cleared without actually emitting the fence.
-- To STOP tasks (running or waiting) when the user asks or their work is clearly no longer wanted, include:
-
 \`\`\`castle-stop
-comma-separated titles or ids of the tasks to stop
+comma-separated active-task titles or ids, or \`all\`
 \`\`\`
 
-Stopped tasks show as interrupted on the board. If a new task replaces the stopped work, prefer \`supersedes:\` on the new task instead.
-- Tasks are one-and-done -- when the user gives feedback on a finished task, spawn a new fix task rather than reopening the old one.
+- \`castle-done\` removes FINISHED rows (done/failed). Use it when the user confirms a task works, or to clear a finished task that has become obsolete (replaced by newer work). \`all\` clears every finished row.
+- \`castle-stop\` stops AND removes ACTIVE rows (running/waiting) -- a running task's agent is killed. Use it when the user asks to stop something, or when you spawn a fix/replacement that makes an in-flight task obsolete. \`all\` stops everything active.
+- When you spawn a task that fixes, redoes, or replaces an earlier one, remove the earlier one in the SAME reply: \`castle-done\` if it already finished, \`castle-stop\` if it is still running or waiting. Keep the board meaning "what to look at right now".
+- Do not mark a task done to imply YOU verified its quality -- the user playtests and confirms that. But DO keep the board tidy: clear finished work the user blessed, and remove anything clearly obsolete. When genuinely unsure, leave the row.
+- Never claim the board is cleared without actually emitting the fence.
+- Tasks are one-and-done -- when the user gives feedback on a finished task, spawn a new fix task (and \`castle-done\` the old row) rather than reopening it.
 - Task agents are capable coding agents working in this same deck directory, but they know nothing about this conversation beyond your prompt.
 
 Conversation style:

package/dist/agent.js

@@ -113,8 +113,7 @@ function visibleLength(raw) {
     return raw.length;
 }
 // Pull ```castle-task fenced directives out of a finished router reply.
-// Block format: title line, then optional "after:" / "supersedes:" lines (in
-// either order), then the task prompt.
+// Block format: title line, then an optional "after:" line, then the prompt.
 function extractDirectives(full) {
     const directives = [];
     const checkoffs = [];
@@ -135,9 +134,9 @@ function extractDirectives(full) {
     const cleaned = withoutDone.replace(fenceRe, (_match, body) => {
         const lines = String(body).replace(/\r/g, '').split('\n');
         const title = (lines.shift() ?? '').trim();
-        const headers = { after: [], supersedes: [] };
+        const headers = { after: [] };
         while (lines.length > 0) {
-            const headerMatch = /^(after|supersedes):\s*(.*)$/i.exec((lines[0] ?? '').trim());
+            const headerMatch = /^(after):\s*(.*)$/i.exec((lines[0] ?? '').trim());
             if (!headerMatch)
                 break;
             lines.shift();
@@ -148,7 +147,7 @@ function extractDirectives(full) {
         }
         const prompt = lines.join('\n').trim();
         if (title) {
-            directives.push({ title, after: headers.after, supersedes: headers.supersedes, prompt });
+            directives.push({ title, after: headers.after, prompt });
         }
         return '';
     });
@@ -528,6 +527,9 @@ function createTaskStore(opts) {
             refreshTaskFiles(tasksDir, task);
             const wasStopped = stopRequested.delete(task.id);
             task.status = wasStopped ? 'interrupted' : result.ok ? 'done' : 'failed';
+            // A stopped task is cleared off the board (castle-stop = halt + remove).
+            if (wasStopped)
+                task.acknowledged = true;
             if (result.ok && !wasStopped)
                 task.progress = 100;
             task.finishedAt = nowIso();
@@ -543,19 +545,6 @@ function createTaskStore(opts) {
         });
     }
     function spawnFromDirective(directive, originMessageId) {
-        // A fix/redo task sweeps the rows it obsoletes off the user's board. Halt
-        // first -- a superseded task that is still running must have its process
-        // killed (not just hidden, which left an invisible zombie the rest of the
-        // board could depend on), and a waiting one must not start later.
-        for (const id of resolveDeps(tasks, directive.supersedes)) {
-            const old = tasks.get(id);
-            if (old && !old.acknowledged) {
-                haltTask(old);
-                old.acknowledged = true;
-                touch(old);
-                opts.onSuperseded(old);
-            }
-        }
         const task = {
             id: nanoid(8),
             title: directive.title,
@@ -621,12 +610,14 @@ function createTaskStore(opts) {
     // stop everything still active. Waiting tasks are cancelled outright;
     // running ones get their agent process killed and finalize as interrupted
     // via the stopRequested path.
-    // Halt an active task: a waiting one is cancelled (-> interrupted); a
-    // running one gets its agent process killed and finalizes as interrupted
-    // via the stopRequested path. No-op on terminal tasks.
+    // Halt + remove an active task (castle-stop): a waiting one is cancelled and
+    // cleared off the board immediately; a running one gets its agent process
+    // killed and is cleared when it finalizes (the stopRequested path acks it).
+    // No-op on terminal tasks.
     function haltTask(task) {
         if (task.status === 'waiting') {
             task.status = 'interrupted';
+            task.acknowledged = true;
             touch(task);
         }
         else if (task.status === 'running') {
@@ -992,7 +983,6 @@ export function createAgentServer(opts) {
         onStarted: () => undefined,
         onRetry: (task, attempt) => addLog(`agent died, retrying (${attempt}/${MAX_TASK_ATTEMPTS}): ${task.title}`),
         onFinished: (task) => taskFeeds.map.delete(task.id),
-        onSuperseded: () => undefined,
         onFeed: (task, entry) => taskFeeds.push(task, entry),
     });
     // A new user message interrupts the in-flight router reply: its partial

package/dist/buildArchive.d.ts

@@ -0,0 +1 @@
+export declare function buildKitArchives(kits?: string[]): void;

package/dist/buildArchive.js

@@ -0,0 +1,108 @@
+import { execFileSync } from 'child_process';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { ARCHIVE_NAME, PUBLISHED_SDK_VERSION, copyKitSource, getKitArchivePath, rewriteKitPackageJson, } from './init.js';
+import { getKitsDir, getSdkPackagePath, toPosixPath } from './localPaths.js';
+// Refs forced to "published" so the archived deck looks like one scaffolded
+// from a globally-installed castle-web (registry sdk + `castle-web` binary),
+// regardless of the workspace checkout we generate it from.
+const PUBLISHED_REFS = {
+    workspaceMode: false,
+    sdkRef: `^${PUBLISHED_SDK_VERSION}`,
+    cliCommand: 'castle-web',
+    cliDistAbs: null,
+    sdkPathPosix: null,
+};
+// Build the local sdk and `npm pack` it into a temp dir, returning the tarball
+// path. Installing a tarball (not a `file:` dir) gives the archive a real copy
+// of the sdk in node_modules instead of a symlink to the local checkout.
+function packSdk() {
+    const sdkDir = getSdkPackagePath();
+    if (!fs.existsSync(sdkDir)) {
+        throw new Error(`sdk/ not found at ${sdkDir}; build-archives must run from a workspace checkout.`);
+    }
+    console.log('Building sdk...');
+    execFileSync('npm', ['run', 'build'], { cwd: sdkDir, stdio: 'inherit' });
+    const dest = fs.mkdtempSync(path.join(os.tmpdir(), 'castle-sdk-pack-'));
+    console.log('Packing sdk...');
+    const out = execFileSync('npm', ['pack', '--pack-destination', dest], {
+        cwd: sdkDir,
+        encoding: 'utf8',
+    }).trim();
+    // npm pack prints the created tarball filename on its last line.
+    const file = out.split('\n').pop().trim();
+    return path.join(dest, file);
+}
+// Find every real kit under kits/ (a subdir with a package.json).
+function discoverKits(kitsDir) {
+    return fs.readdirSync(kitsDir).filter((name) => {
+        const dir = path.join(kitsDir, name);
+        return fs.statSync(dir).isDirectory() && fs.existsSync(path.join(dir, 'package.json'));
+    });
+}
+// Generate one ready-to-serve archive for `kit`: kit source (minus build junk)
+// + installed node_modules + a published-mode package.json, gzipped into the
+// bundled kit dir (cli/kits/<kit>/published-deck.tgz).
+function buildKitArchive(kit, sdkTarball) {
+    const kitDir = path.join(getKitsDir(), kit);
+    if (!fs.existsSync(path.join(kitDir, 'package.json'))) {
+        throw new Error(`Kit "${kit}" has no package.json at ${kitDir}.`);
+    }
+    const stagingRoot = fs.mkdtempSync(path.join(os.tmpdir(), `castle-archive-${kit}-`));
+    const deck = path.join(stagingRoot, 'deck');
+    try {
+        // Same filter the live scaffold uses, plus drop any prior archive.
+        copyKitSource(kitDir, deck, new Set([ARCHIVE_NAME]));
+        // A stale workspace lock would pin file:../../sdk; drop it before install.
+        fs.rmSync(path.join(deck, 'package-lock.json'), { force: true });
+        // Published-mode package.json, but point the sdk at the local tarball so
+        // the install copies our freshly-built sdk into node_modules.
+        const pkgPath = path.join(deck, 'package.json');
+        const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+        rewriteKitPackageJson(pkg, kit, PUBLISHED_REFS);
+        pkg.dependencies['castle-web-sdk'] = `file:${toPosixPath(sdkTarball)}`;
+        fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n');
+        // Deck deps are pure JS (no native binaries), so this mac-built
+        // node_modules runs as-is on linux/e2b.
+        console.log(`Installing deps for ${kit}...`);
+        execFileSync('npm', ['install', '--no-audit', '--no-fund', '--loglevel=error'], {
+            cwd: deck,
+            stdio: 'inherit',
+        });
+        // Restore the published sdk range (node_modules already holds the real
+        // sdk) and drop the lock pinning the local tarball path.
+        pkg.dependencies['castle-web-sdk'] = `^${PUBLISHED_SDK_VERSION}`;
+        fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n');
+        fs.rmSync(path.join(deck, 'package-lock.json'), { force: true });
+        const archivePath = getKitArchivePath(kit);
+        fs.mkdirSync(path.dirname(archivePath), { recursive: true });
+        fs.rmSync(archivePath, { force: true });
+        console.log(`Archiving ${kit} -> ${archivePath}`);
+        execFileSync('tar', ['-czf', archivePath, '-C', deck, '.'], { stdio: 'inherit' });
+        const sizeMb = (fs.statSync(archivePath).size / 1e6).toFixed(1);
+        console.log(`  ${kit} archive: ${sizeMb} MB`);
+    }
+    finally {
+        fs.rmSync(stagingRoot, { recursive: true, force: true });
+    }
+}
+// Generate archives for the given kits (default: every kit under kits/). Builds
+// + packs the sdk once, then archives each kit against that same tarball.
+export function buildKitArchives(kits) {
+    const kitsDir = getKitsDir();
+    const targets = kits ?? discoverKits(kitsDir);
+    if (targets.length === 0) {
+        console.error(`No kits found under ${kitsDir}.`);
+        process.exit(1);
+    }
+    const sdkTarball = packSdk();
+    try {
+        for (const kit of targets)
+            buildKitArchive(kit, sdkTarball);
+    }
+    finally {
+        fs.rmSync(path.dirname(sdkTarball), { recursive: true, force: true });
+    }
+    console.log(`Done. Archived: ${targets.join(', ')}`);
+}

package/dist/index.js

@@ -135,6 +135,14 @@ async function main() {
         case 'login':
             await login();
             break;
+        case 'build-archives': {
+            // Dev/publish tool: generate the prebuilt per-kit deck archives that
+            // `init` extracts in published mode. Run after `npm run build -w cli`.
+            const { buildKitArchives } = await import('./buildArchive.js');
+            const only = getFlagValue('--kit');
+            buildKitArchives(only ? [only] : undefined);
+            break;
+        }
         default:
             usage();
     }

package/dist/init.d.ts

@@ -1,4 +1,22 @@
+export declare const PUBLISHED_SDK_VERSION = "0.4.4";
+export declare const KIT_COPY_EXCLUDE: Set<string>;
+export declare const ARCHIVE_NAME = "published-deck.tgz";
+export declare function getKitArchivePath(kit: string): string;
+export declare function copyKitSource(kitDir: string, dest: string, extraExclude?: Set<string>): void;
+export declare function rewriteKitPackageJson(pkg: {
+    name?: string;
+    dependencies?: Record<string, string>;
+    scripts?: Record<string, string>;
+}, name: string, refs: ReturnType<typeof resolveScaffoldRefs>): void;
+declare function resolveScaffoldRefs(): {
+    workspaceMode: boolean;
+    sdkRef: string;
+    cliCommand: string;
+    cliDistAbs: string | null;
+    sdkPathPosix: string | null;
+};
 export declare function init(dir: string, opts?: {
     kit?: string;
     serve?: boolean;
 }): Promise<void>;
+export {};

package/dist/init.js

@@ -1,4 +1,4 @@
-import { execSync } from 'child_process';
+import { execFileSync, execSync } from 'child_process';
 import * as fs from 'fs';
 import * as path from 'path';
 import { COMMON_INSTRUCTIONS } from './commonInstructions.js';
@@ -35,10 +35,62 @@ const DEFAULT_KIT = 'basic-2d';
 // Registry version of castle-web-sdk to inject when scaffolding from a
 // globally-installed castle-web (not from inside the workspace). Bumped
 // alongside cli/sdk version bumps.
-const PUBLISHED_SDK_VERSION = '0.4.4';
+export const PUBLISHED_SDK_VERSION = '0.4.4';
 // Never copied into a fresh deck: build/dependency junk, and castle.json (a
 // fresh deck has no deckId until its first save-deck).
-const KIT_COPY_EXCLUDE = new Set(['node_modules', '.castle', 'dist', '.git', 'castle.json']);
+export const KIT_COPY_EXCLUDE = new Set(['node_modules', '.castle', 'dist', '.git', 'castle.json']);
+// A globally-installed castle-web ships one prebuilt, ready-to-serve archive
+// per kit (kit source + installed node_modules + published-mode package.json),
+// gzipped. `init` in published mode extracts it instead of cp + `npm install`.
+// Lives inside each bundled kit dir (cli/kits/<kit>/), generated by
+// `build-archives` (see buildArchive.ts). Workspace mode never uses it.
+export const ARCHIVE_NAME = 'published-deck.tgz';
+export function getKitArchivePath(kit) {
+    return path.join(getKitsDir(), kit, ARCHIVE_NAME);
+}
+// Copy a framework kit into `dest`, dropping build/dependency junk + castle.json
+// (and any caller-supplied extra names, e.g. a stale archive). Shared by the
+// live scaffold and archive generation so the two stay in sync.
+export function copyKitSource(kitDir, dest, extraExclude) {
+    fs.cpSync(kitDir, dest, {
+        recursive: true,
+        // Keep symlinks verbatim so the kit's AGENTS.md -> CLAUDE.md stays a link.
+        verbatimSymlinks: true,
+        filter: (src) => src === kitDir ||
+            (!KIT_COPY_EXCLUDE.has(path.basename(src)) && !extraExclude?.has(path.basename(src))),
+    });
+}
+// Rewrite a kit's package.json (in place) so the scaffolded deck references the
+// sdk + cli per the resolved mode. Workspace mode points at the local checkout
+// (file: sdk + node <abs cli dist>); published mode points at the registry sdk
+// + the `castle-web` binary. Shared by the live scaffold and archive generation.
+export function rewriteKitPackageJson(pkg, name, refs) {
+    pkg.name = name;
+    const { workspaceMode, sdkRef, cliDistAbs, sdkPathPosix } = refs;
+    if (pkg.dependencies &&
+        typeof pkg.dependencies['castle-web-sdk'] === 'string' &&
+        pkg.dependencies['castle-web-sdk'].startsWith('file:')) {
+        pkg.dependencies['castle-web-sdk'] = sdkRef;
+    }
+    if (!pkg.scripts)
+        return;
+    for (const k of Object.keys(pkg.scripts)) {
+        if (typeof pkg.scripts[k] !== 'string')
+            continue;
+        if (workspaceMode) {
+            pkg.scripts[k] = pkg.scripts[k]
+                .replace(/\.\.\/\.\.\/cli\/dist/g, cliDistAbs)
+                .replace(/\.\.\/\.\.\/sdk/g, sdkPathPosix);
+        }
+        else {
+            // Globally-installed: route through the `castle-web` binary on PATH.
+            pkg.scripts[k] = pkg.scripts[k]
+                .replace(/node\s+\.\.\/\.\.\/cli\/dist\/index\.js/g, 'castle-web')
+                .replace(/await import\((['"])\.\.\/\.\.\/cli\/dist\/bundle\.js\1\)/g, "await import('castle-web-cli/dist/bundle.js')")
+                .replace(/\.\.\/\.\.\/sdk/g, '');
+        }
+    }
+}
 // Resolve how a scaffolded deck should reference the sdk + cli. Both the bare
 // and kit scaffold paths go through here so they stay in sync.
 //   workspace mode (sdk/ sits next to cli/, i.e. running from a checkout):
@@ -127,8 +179,42 @@ function scaffoldBare(projectDir) {
     ensureAgentsSymlink(projectDir);
     fs.writeFileSync(path.join(projectDir, 'package.json'), JSON.stringify(makePackageJson(projectDir), null, 2) + '\n');
 }
+// Finalize a deck whose files are already on disk (mirroring scaffoldFromKit's
+// tail): ensure a CLAUDE.md, append the cli-owned common guidance, and create
+// the AGENTS.md symlink. Used by both the cp path and the archive-extract path.
+function finalizeDeckDocs(projectDir) {
+    // Every deck needs a CLAUDE.md so coding agents know how castle-web works.
+    // Keep the kit's own if it ships one; otherwise generate from the upstream.
+    const claudePath = path.join(projectDir, 'CLAUDE.md');
+    if (!fs.existsSync(claudePath)) {
+        fs.writeFileSync(claudePath, makeClaudeMd());
+    }
+    appendCommonInstructions(projectDir);
+    ensureAgentsSymlink(projectDir);
+}
+// Published fast path: extract the prebuilt, ready-to-serve archive into the
+// deck dir (no cp, no `npm install`). The archive carries the kit source +
+// installed node_modules + a published-mode package.json with a generic name;
+// rename it to the deck dir, then run the shared doc finalization.
+function extractKitArchive(archivePath, projectDir) {
+    fs.mkdirSync(projectDir, { recursive: true });
+    execFileSync('tar', ['-xzf', archivePath, '-C', projectDir], { stdio: 'inherit' });
+    const pkgPath = path.join(projectDir, 'package.json');
+    if (fs.existsSync(pkgPath)) {
+        try {
+            const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+            pkg.name = path.basename(projectDir);
+            fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n');
+        }
+        catch {
+            // archived an unparseable package.json — leave it for the user to fix
+        }
+    }
+    finalizeDeckDocs(projectDir);
+}
 // Copy a framework kit from kits/<kit>/ into the new deck dir, dropping
-// build/dependency junk and castle.json.
+// build/dependency junk and castle.json. Returns whether deps are already
+// installed (true only on the published archive-extract fast path).
 function scaffoldFromKit(kit, projectDir) {
     const kitDir = path.join(getKitsDir(), kit);
     if (!fs.existsSync(kitDir) || !fs.statSync(kitDir).isDirectory()) {
@@ -150,12 +236,17 @@ function scaffoldFromKit(kit, projectDir) {
         console.error('Or use `--kit none` for a bare code-only deck.');
         process.exit(1);
     }
-    fs.cpSync(kitDir, projectDir, {
-        recursive: true,
-        // Keep symlinks verbatim so the kit's AGENTS.md -> CLAUDE.md stays a link.
-        verbatimSymlinks: true,
-        filter: (src) => src === kitDir || !KIT_COPY_EXCLUDE.has(path.basename(src)),
-    });
+    // Published mode (globally-installed castle-web, no sibling sdk/) extracts a
+    // prebuilt archive when one ships for this kit -- skipping cp + `npm install`.
+    // Workspace mode always does the live cp so local sdk edits stay live.
+    const refs = resolveScaffoldRefs();
+    const archivePath = getKitArchivePath(kit);
+    if (!refs.workspaceMode && fs.existsSync(archivePath)) {
+        console.log('Extracting prebuilt deck (deps included)...');
+        extractKitArchive(archivePath, projectDir);
+        return { depsInstalled: true };
+    }
+    copyKitSource(kitDir, projectDir);
     // The kit's package.json carries the kit's name; rename it to the deck dir.
     // Kit-relative refs to `../../sdk` and `../../cli/dist` only resolve when the
     // deck lives at castle-experimental-web/decks/<name>/. Rewrite both to
@@ -165,50 +256,15 @@ function scaffoldFromKit(kit, projectDir) {
     if (fs.existsSync(pkgPath)) {
         try {
             const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
-            pkg.name = path.basename(projectDir);
-            // Local-dev paths (`file:../../sdk` / `node ../../cli/dist/index.js`) only
-            // work when the deck lives inside the castle-experimental-web workspace.
-            // For a deck scaffolded from a globally-installed castle-web, rewrite to
-            // the published packages instead. Same workspace-vs-published resolution
-            // the bare scaffold path uses.
-            const { workspaceMode, sdkRef, cliDistAbs, sdkPathPosix } = resolveScaffoldRefs();
-            if (pkg.dependencies &&
-                typeof pkg.dependencies['castle-web-sdk'] === 'string' &&
-                pkg.dependencies['castle-web-sdk'].startsWith('file:')) {
-                pkg.dependencies['castle-web-sdk'] = sdkRef;
-            }
-            if (pkg.scripts) {
-                for (const k of Object.keys(pkg.scripts)) {
-                    if (typeof pkg.scripts[k] !== 'string')
-                        continue;
-                    if (workspaceMode) {
-                        pkg.scripts[k] = pkg.scripts[k]
-                            .replace(/\.\.\/\.\.\/cli\/dist/g, cliDistAbs)
-                            .replace(/\.\.\/\.\.\/sdk/g, sdkPathPosix);
-                    }
-                    else {
-                        // Globally-installed: route through the `castle-web` binary on PATH.
-                        pkg.scripts[k] = pkg.scripts[k]
-                            .replace(/node\s+\.\.\/\.\.\/cli\/dist\/index\.js/g, 'castle-web')
-                            .replace(/await import\((['"])\.\.\/\.\.\/cli\/dist\/bundle\.js\1\)/g, "await import('castle-web-cli/dist/bundle.js')")
-                            .replace(/\.\.\/\.\.\/sdk/g, '');
-                    }
-                }
-            }
+            rewriteKitPackageJson(pkg, path.basename(projectDir), refs);
             fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n');
         }
         catch {
             // kit shipped an unparseable package.json — leave it for the user to fix
         }
     }
-    // Every deck needs a CLAUDE.md so coding agents know how castle-web works.
-    // Keep the kit's own if it ships one; otherwise generate from the upstream.
-    const claudePath = path.join(projectDir, 'CLAUDE.md');
-    if (!fs.existsSync(claudePath)) {
-        fs.writeFileSync(claudePath, makeClaudeMd());
-    }
-    appendCommonInstructions(projectDir);
-    ensureAgentsSymlink(projectDir);
+    finalizeDeckDocs(projectDir);
+    return { depsInstalled: false };
 }
 export async function init(dir, opts = {}) {
     const projectDir = path.resolve(dir);
@@ -218,11 +274,14 @@ export async function init(dir, opts = {}) {
     }
     const kit = opts.kit ?? DEFAULT_KIT;
     const bare = kit === 'none' || kit === 'bare';
+    // depsInstalled is true only when the published archive fast-path ran, which
+    // already ships node_modules -- so we can skip `npm install` below.
+    let depsInstalled = false;
     if (bare) {
         scaffoldBare(projectDir);
     }
     else {
-        scaffoldFromKit(kit, projectDir);
+        ({ depsInstalled } = scaffoldFromKit(kit, projectDir));
     }
     console.log(`Created project in ${projectDir}/${bare ? '' : ` (from kit "${kit}")`}`);
     // Auto-run npm install + serve so the page is up the moment the
@@ -230,16 +289,21 @@ export async function init(dir, opts = {}) {
     const autoServe = opts.serve !== false;
     if (autoServe) {
         console.log('');
-        console.log('Installing deps + serving (pass --no-serve to skip)...');
-        try {
-            execSync('npm install --no-audit --no-fund --loglevel=error', {
-                cwd: projectDir,
-                stdio: 'inherit',
-            });
+        if (!depsInstalled) {
+            console.log('Installing deps + serving (pass --no-serve to skip)...');
+            try {
+                execSync('npm install --no-audit --no-fund --loglevel=error', {
+                    cwd: projectDir,
+                    stdio: 'inherit',
+                });
+            }
+            catch {
+                console.error('npm install failed; skipping serve. Re-run yourself with `npm install && castle-web serve .` (& in your shell to background it).');
+                return;
+            }
         }
-        catch {
-            console.error('npm install failed; skipping serve. Re-run yourself with `npm install && castle-web serve .` (& in your shell to background it).');
-            return;
+        else {
+            console.log('Serving (deps prebuilt)...');
         }
         // Call serve() with detach so init returns once the server is up. serve()
         // handles the background spawn internally; init doesn't shell out.
@@ -256,6 +320,7 @@ export async function init(dir, opts = {}) {
     console.log('');
     console.log('Next steps:');
     console.log(`  cd ${dir}`);
-    console.log('  npm install');
+    if (!depsInstalled)
+        console.log('  npm install');
     console.log('  castle-web serve .   # & in your shell to background it');
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "castle-web-cli",
-  "version": "0.4.36",
+  "version": "0.4.38",
   "type": "module",
   "bin": {
     "castle-web": "./dist/index.js"