@paleo/workspace 0.19.1 → 0.21.0

package/README.md

@@ -26,7 +26,8 @@ The agent reads the skill, adapts the reference scripts to your stack, installs
 ## Workflow
 
 ```sh
-npm run workspace -- setup feat/42 -c   # new branch + worktree + isolated env
+npm run workspace -- setup feat/42 -c        # new branch + worktree + isolated env
+npm run workspace -- setup feat/42 -c --go   # …then drop into a shell there (exit to return)
 npm run dev                             # foreground: stream logs, CTRL+C stops; attaches if already running
 npm run dev -- up                       # start in the background (no-op if already running here)
 npm run dev -- up --restart             # stop the dev-server in this worktree if running, then start fresh
@@ -36,8 +37,12 @@ npm run dev -- status                   # report whether this worktree's dev-ser
 npm run dev -- list                     # active dev-servers across all worktrees
 npm run dev -- down                     # stop dev server (infrastructure stays up)
 npm run workspace -- remove feat/42     # full teardown
+npm run workspace -- prune              # heal workspaces whose worktree was deleted out-of-band
+npm run workspace -- --guide            # full operating guide (workspace + dev-server)
 ```
 
+`--guide` prints the complete workspace + dev-server procedures in your package-manager's syntax. Point agents at it instead of maintaining a separate doc.
+
 ## API
 
 ```ts

package/dist/cli.d.ts

@@ -7,12 +7,15 @@ export type WorkspaceCommand = {
     slot?: string;
     force: boolean;
     wait: boolean;
+    go: boolean;
 } | {
     kind: "remove";
     branch?: string;
     force: boolean;
 } | {
     kind: "list";
+} | {
+    kind: "prune";
 } | {
     kind: "status";
     slot?: string;
@@ -29,6 +32,8 @@ export type WorkspaceCommand = {
 } | {
     kind: "migrate";
     oldRegistryDir: string;
+} | {
+    kind: "guide";
 } | {
     kind: "help";
 };

package/dist/cli.js

@@ -5,6 +5,9 @@ export function parseWorkspaceArgs(argv = process.argv.slice(2)) {
     if (subcommand === "--help" || subcommand === "-h") {
         return { command: { kind: "help" }, verbose: false };
     }
+    if (subcommand === "--guide") {
+        return { command: { kind: "guide" }, verbose: false };
+    }
     if (subcommand === undefined)
         throw new ConfigError("No command given.");
     try {
@@ -24,6 +27,8 @@ function parseSubcommand(subcommand, tokens) {
             return parseRemove(tokens);
         case "list":
             return parseList(tokens);
+        case "prune":
+            return parsePrune(tokens);
         case "status":
             return parseStatus(tokens);
         case "wait":
@@ -48,6 +53,7 @@ function parseSetup(tokens) {
             slot: { type: "string", short: "s" },
             force: { type: "boolean" },
             wait: { type: "boolean" },
+            go: { type: "boolean" },
             verbose: { type: "boolean", short: "v" },
         },
         allowPositionals: true,
@@ -55,12 +61,16 @@ function parseSetup(tokens) {
     });
     const branch = takeOptionalPositional(positionals, "setup");
     const newBranch = values["new-branch"] ?? false;
+    const go = values.go ?? false;
     if (newBranch && branch === undefined) {
         throw new ConfigError("`workspace setup <branch> -c` requires a branch name.");
     }
     if (values.from !== undefined && !newBranch) {
         throw new ConfigError("`--from` requires `-c`/`--new-branch`.");
     }
+    if (go && branch === undefined) {
+        throw new ConfigError("`--go` requires a branch (the worktree to enter).");
+    }
     return {
         command: {
             kind: "setup",
@@ -71,6 +81,7 @@ function parseSetup(tokens) {
             slot: values.slot,
             force: values.force ?? false,
             wait: values.wait ?? false,
+            go,
         },
         verbose: values.verbose ?? false,
     };
@@ -101,6 +112,16 @@ function parseList(tokens) {
     rejectPositionals(positionals, "list");
     return { command: { kind: "list" }, verbose: values.verbose ?? false };
 }
+function parsePrune(tokens) {
+    const { values, positionals } = parseArgs({
+        args: tokens,
+        options: { verbose: { type: "boolean", short: "v" } },
+        allowPositionals: true,
+        strict: true,
+    });
+    rejectPositionals(positionals, "prune");
+    return { command: { kind: "prune" }, verbose: values.verbose ?? false };
+}
 function parseStatus(tokens) {
     const { values, positionals } = parseArgs({
         args: tokens,
@@ -181,17 +202,22 @@ export function printWorkspaceHelp() {
         "Manage workspaces: a git worktree plus its own dev setup (ports, config, database, dev server).",
         "",
         "Commands:",
-        "  setup [<branch>] [-c|--new-branch] [--from <ref>] [--owner <name>] [-s|--slot <port>] [--force] [--wait]",
+        "  setup [<branch>] [-c|--new-branch] [--from <ref>] [--owner <name>] [-s|--slot <port>] [--force] [--wait] [--go]",
         "      Set up the workspace. With <branch>, create a sibling worktree for it",
         "      (add -c to create the branch first). Without, set up the current worktree",
         "      (idempotent; bootstrap and retry path).",
         "      With -c, the new branch starts at the current worktree's HEAD, or at <ref> with --from.",
         "      Finalize runs in the background; add --wait to block until it reaches READY.",
+        "      With --go, drop into an interactive shell in the new worktree (exit to return);",
+        "      combine with --wait to enter only once it is READY. Requires a branch and $SHELL.",
         "  remove [<branch>] [--force]",
         "      Remove a workspace by branch, or the current one when omitted.",
         "      Refuses on uncommitted changes unless --force.",
         "  list",
         "      List all registered workspaces (slot, status, branch, path, owner, created).",
+        "  prune",
+        "      Heal orphaned workspaces (worktree deleted out-of-band): stop their dev-servers",
+        "      and drop their registry entries, then run `git worktree prune`.",
         "  status [-s|--slot <port>]",
         "      Print a workspace summary (ports, branch, readiness, dev-server).",
         "  wait [-s|--slot <port>]",
@@ -201,6 +227,7 @@ export function printWorkspaceHelp() {
         "",
         "Global options:",
         "  -v, --verbose   Show intermediate output.",
+        "      --guide     Print the full workspace + dev-server operating guide.",
         "  -h, --help      Show this help message.",
     ].join("\n"));
 }

package/dist/guide.d.ts

@@ -0,0 +1,19 @@
+interface ScriptInvocation {
+    /** Run with no forwarded args, e.g. `npm run dev`. */
+    base: string;
+    /** Prefix before forwarded args, e.g. `npm run dev --`. */
+    withArgs: string;
+}
+export interface PackageManagerCommands {
+    workspace: ScriptInvocation;
+    dev: ScriptInvocation;
+}
+export interface GuideLayout {
+    /** The per-worktree runtime dir, relative to the worktree root (config `runtimeDir`, e.g. `.local-wt`). */
+    runtimeDir: string;
+    /** The shared (symlinked-from-main) dir names (config `sharedDirs`). */
+    sharedDirs: string[];
+}
+export declare function renderGuide(pm: PackageManagerCommands, layout: GuideLayout): string;
+export declare function printGuide(layout: GuideLayout, cwd?: string): void;
+export {};

package/dist/guide.js

@@ -0,0 +1,163 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { REGISTRY_SUBDIR } from "./slots.js";
+// Pad every command to the longest one so the `#` comments line up, whatever the
+// package-manager prefix length (npm's `run … --` vs a bare `pnpm dev`).
+function renderRows(rows) {
+    const width = Math.max(...rows.map((row) => row.command.length));
+    return rows.map((row) => `${row.command.padEnd(width)}  # ${row.comment}`).join("\n");
+}
+// Like renderRows, but tolerates bare comment-only lines (rendered verbatim, never padded)
+// interleaved between commands.
+function renderSnippet(lines) {
+    const commands = lines.filter((line) => typeof line !== "string");
+    const width = Math.max(...commands.map((row) => row.command.length));
+    return lines
+        .map((line) => typeof line === "string" ? line : `${line.command.padEnd(width)}  # ${line.comment}`)
+        .join("\n");
+}
+function commandBlocks(pm) {
+    const ws = pm.workspace.withArgs;
+    const dev = pm.dev.withArgs;
+    return {
+        setup: [
+            {
+                command: `${ws} setup my-branch -c`,
+                comment: "new branch + worktree (dedup: appends -2, -3…)",
+            },
+            {
+                command: `${ws} setup my-branch -c --from origin/main`,
+                comment: "new branch based on another ref",
+            },
+            { command: `${ws} setup my-branch`, comment: "new worktree on an existing branch" },
+            {
+                command: `${ws} setup`,
+                comment: "set up the current worktree (idempotent; bootstrap + retry path)",
+            },
+            {
+                command: `${ws} wait --slot 8110`,
+                comment: "block until ready (exit 0) or failed (exit 1)",
+            },
+        ],
+        recovery: [
+            {
+                command: `${ws} setup --wait`,
+                comment: "retry the finalize step, block until READY/FAILED",
+            },
+        ],
+        inspect: [
+            {
+                command: `${ws} list`,
+                comment: "all registered workspaces (slot, status, branch, path, owner, created)",
+            },
+            {
+                command: `${ws} status`,
+                comment: "current worktree summary (ports, branch, readiness, dev-server)",
+            },
+            { command: `${ws} status --slot 8110`, comment: "same, for another worktree" },
+        ],
+        owner: [
+            { command: `${ws} setup my-branch -c --owner alice`, comment: "set on creation" },
+            { command: `${ws} set-owner bob`, comment: "update later, no rebuild" },
+        ],
+        remove: [
+            { command: `${ws} remove my-branch`, comment: "remove by branch name" },
+            { command: `${ws} remove`, comment: "remove the current worktree (run from inside it)" },
+        ],
+        prune: [
+            {
+                command: `${ws} prune`,
+                comment: "stop orphans' dev-servers, drop registry entries, run `git worktree prune`",
+            },
+        ],
+        dev: [
+            {
+                command: pm.dev.base,
+                comment: "foreground; streams logs; CTRL+C stops (attaches if already running here)",
+            },
+            { command: `${dev} up`, comment: "start in the background (this worktree)" },
+            {
+                command: `${dev} restart`,
+                comment: "stop this worktree's dev-server if running, then start in background",
+            },
+            {
+                command: `${dev} status`,
+                comment: "report whether this worktree's dev-server is UP or DOWN",
+            },
+            { command: `${dev} down`, comment: "stop the dev-server (this worktree only)" },
+            { command: `${dev} list`, comment: "list active dev-servers across all worktrees" },
+            { command: `${dev} down --all`, comment: "stop every active dev-server" },
+            {
+                command: `${dev} up --evict`,
+                comment: "if the cap is full, evict the oldest dev-server and start",
+            },
+        ],
+    };
+}
+function driveDevSnippet(pm) {
+    const dev = pm.dev.withArgs;
+    return renderSnippet([
+        { command: "git worktree list", comment: "1. find the worktree directory" },
+        { command: `cd <worktree-dir> && ${dev} up`, comment: "2. start in the background" },
+        "# 3. read the log file (path printed on start) to confirm startup and find URLs",
+        { command: `${dev} down`, comment: "4. stop when done (same directory)" },
+    ]);
+}
+function renderSharedLayout(sharedDirs) {
+    if (sharedDirs.length === 0) {
+        return "- No dirs are shared across worktrees.";
+    }
+    const names = sharedDirs.map((dir) => `\`${dir}/\``).join(", ");
+    return `- Shared across worktrees, symlinked from the main worktree: ${names}.`;
+}
+export function renderGuide(pm, layout) {
+    const template = readFileSync(new URL("../templates/guide.md", import.meta.url), "utf-8");
+    let out = template;
+    for (const [name, rows] of Object.entries(commandBlocks(pm))) {
+        out = out.replaceAll(`{{COMMANDS:${name}}}`, renderRows(rows));
+    }
+    return out
+        .replaceAll("{{SNIPPET:drive-dev}}", driveDevSnippet(pm))
+        .replaceAll("{{DEV_BASE}}", pm.dev.base)
+        .replaceAll("{{WS}}", pm.workspace.withArgs)
+        .replaceAll("{{DEV}}", pm.dev.withArgs)
+        .replaceAll("{{RUNTIME_DIR}}", layout.runtimeDir)
+        .replaceAll("{{REGISTRY_SUBDIR}}", REGISTRY_SUBDIR)
+        .replaceAll("{{LAYOUT:shared}}", renderSharedLayout(layout.sharedDirs))
+        .trimEnd();
+}
+export function printGuide(layout, cwd = process.cwd()) {
+    console.log(renderGuide(detectPackageManager(cwd), layout));
+}
+// Mirror docmap's lockfile walk. These scripts are always wired as project scripts (the package
+// is a dev dependency), so there is no global-install fallback — default to npm when unsure.
+function detectPackageManager(cwd) {
+    let dir = cwd;
+    while (true) {
+        if (existsSync(join(dir, "pnpm-lock.yaml")))
+            return same("pnpm");
+        if (existsSync(join(dir, "yarn.lock")))
+            return same("yarn run");
+        if (existsSync(join(dir, "bun.lockb")) || existsSync(join(dir, "bun.lock")))
+            return same("bun run");
+        if (existsSync(join(dir, "package-lock.json")))
+            return npm();
+        const parent = dirname(dir);
+        if (parent === dir)
+            return npm();
+        dir = parent;
+    }
+}
+// Only npm needs a `--` separator before forwarded args; every other manager passes them verbatim.
+function npm() {
+    return {
+        workspace: { base: "npm run workspace", withArgs: "npm run workspace --" },
+        dev: { base: "npm run dev", withArgs: "npm run dev --" },
+    };
+}
+function same(prefix) {
+    return {
+        workspace: { base: `${prefix} workspace`, withArgs: `${prefix} workspace` },
+        dev: { base: `${prefix} dev`, withArgs: `${prefix} dev` },
+    };
+}

package/dist/orphans.d.ts

@@ -0,0 +1,7 @@
+import type { SlotsRegistry } from "./slots.js";
+/**
+ * Returns the slot ports whose worktree directory no longer exists on disk — workspaces deleted
+ * out-of-band (a manual `rm -rf`, a bare `git worktree remove`). The main worktree is never
+ * reported: if its directory is gone the whole git context is, and we must not touch it.
+ */
+export declare function findOrphanPorts(registry: SlotsRegistry, exists?: (path: string) => boolean): string[];

package/dist/orphans.js

@@ -0,0 +1,11 @@
+import { existsSync } from "node:fs";
+/**
+ * Returns the slot ports whose worktree directory no longer exists on disk — workspaces deleted
+ * out-of-band (a manual `rm -rf`, a bare `git worktree remove`). The main worktree is never
+ * reported: if its directory is gone the whole git context is, and we must not touch it.
+ */
+export function findOrphanPorts(registry, exists = existsSync) {
+    return Object.entries(registry.slots)
+        .filter(([, entry]) => !entry.main && !exists(entry.worktree))
+        .map(([port]) => port);
+}

package/dist/workspace.js

@@ -1,12 +1,14 @@
-import { spawn, spawnSync } from "node:child_process";
+import { execFileSync, spawn, spawnSync } from "node:child_process";
 import { appendFileSync, closeSync, existsSync, lstatSync, mkdirSync, openSync, readFileSync, rmSync, symlinkSync, writeFileSync, } from "node:fs";
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { parseWorkspaceArgs, printWorkspaceHelp } from "./cli.js";
 import { findOwnEntry, liveWorktrees, mergeDevServers, readDevServers, removeDevServerEntryByWorktree, writeDevServers, } from "./dev-servers-registry.js";
 import { ConfigError } from "./errors.js";
+import { printGuide } from "./guide.js";
 import { copyAndPatchFile, formatDuration, setupLogPath, } from "./helpers.js";
-import { isProcessAlive } from "./process-control.js";
+import { findOrphanPorts } from "./orphans.js";
 import { defaultComputePorts, isValidPort, resolvePortScheme } from "./ports.js";
+import { isProcessAlive, stopProcessGroup } from "./process-control.js";
 import { handleSetOwner, markSlotFailed, markSlotReady, mergeSlots, readSlots, REGISTRY_SUBDIR, registryDirFor, resolveAndRegisterSlot, resolveCurrentSlot, validateSlotAvailability, warnLegacyRegistryDir, writeSlots, } from "./slots.js";
 import { createBranch, detectWorktree, getWorktreeBranch, isWorktreeDirty, removeWorktree, useExistingBranch, } from "./worktree.js";
 export async function runWorkspace(config) {
@@ -27,6 +29,10 @@ export async function runWorkspace(config) {
         printWorkspaceHelp();
         return;
     }
+    if (command.kind === "guide") {
+        printGuide({ runtimeDir: config.runtimeDir, sharedDirs: config.sharedDirs });
+        return;
+    }
     warnLegacyRegistryDir(config);
     const registryDir = registryDirFor(config.runtimeDir);
     if (command.kind === "migrate") {
@@ -51,6 +57,9 @@ export async function runWorkspace(config) {
         case "list":
             runList(registryDir);
             return;
+        case "prune":
+            await runPrune(registryDir);
+            return;
     }
     const ctx = detectWorktree();
     const run = { verbose };
@@ -62,13 +71,29 @@ export async function runWorkspace(config) {
             handleSetOwnerMode(command, ctx, registryDir);
             return;
         case "setup": {
-            const { slot } = await runSetup(command, ctx, run, config, registryDir);
+            const { slot, worktree } = await runSetup(command, ctx, run, config, registryDir);
             if (command.wait)
                 await waitForSlot(slot, config, registryDir, { printSummary: false });
+            if (command.go)
+                enterWorktree(worktree);
             return;
         }
     }
 }
+/**
+ * `--go`: open an interactive shell in the freshly set-up worktree (exit to return). Falls back to
+ * printing a `cd` hint when there is no `$SHELL` or stdin is not a tty (scripts, pipes) — dropping
+ * into an interactive shell there would hang.
+ */
+function enterWorktree(worktree) {
+    const shell = process.env.SHELL;
+    if (shell === undefined || !process.stdin.isTTY) {
+        console.log(`Now run: cd ${worktree}`);
+        return;
+    }
+    console.error(`Entering ${worktree} (exit to return).`);
+    spawnSync(shell, [], { cwd: worktree, stdio: "inherit" });
+}
 async function runSetup(command, ctx, run, config, registryDir) {
     const scheme = resolvePortScheme(config);
     const portsFn = resolvePortsFn(config);
@@ -149,7 +174,7 @@ async function runSetup(command, ctx, run, config, registryDir) {
     });
     child.unref();
     closeSync(logFd);
-    return { slot };
+    return { slot, worktree: setupCtx.currentWorktree };
 }
 function refuseIfFinalizePending(ctx, registryDir, force) {
     if (force)
@@ -297,9 +322,11 @@ function runStatus(command, config, registryDir) {
 }
 function runList(registryDir) {
     const ctx = detectWorktree();
+    const liveOrphans = autoPruneSafeOrphans(ctx.mainWorktree, registryDir);
     const entries = Object.entries(readSlots(ctx.mainWorktree, registryDir).slots).sort(([a], [b]) => Number(a) - Number(b));
     if (entries.length === 0) {
         console.log("No workspaces registered.");
+        hintLiveOrphans(liveOrphans);
         return;
     }
     const liveSet = liveWorktrees(readDevServers(ctx.mainWorktree, registryDir));
@@ -336,6 +363,95 @@ function runList(registryDir) {
     console.log(fmt(headers));
     for (const r of rows)
         console.log(fmt(r));
+    hintLiveOrphans(liveOrphans);
+}
+/**
+ * Silently drop registry entries for worktrees deleted out-of-band that have no live dev-server —
+ * harmless bookkeeping, consistent with the existing dead-PID pruning. Orphans whose dev-server is
+ * still running are left untouched (stopping a live process is the explicit `workspace prune`'s job)
+ * and returned so the caller can hint about them.
+ */
+function autoPruneSafeOrphans(mainWorktree, registryDir) {
+    const registry = readSlots(mainWorktree, registryDir);
+    const orphanPorts = findOrphanPorts(registry);
+    if (orphanPorts.length === 0)
+        return [];
+    const live = liveWorktrees(readDevServers(mainWorktree, registryDir));
+    const liveOrphans = [];
+    let changed = false;
+    for (const port of orphanPorts) {
+        const entry = registry.slots[port];
+        if (live.has(resolve(entry.worktree))) {
+            liveOrphans.push(port);
+            continue;
+        }
+        delete registry.slots[port];
+        removeDevServerEntryByWorktree(mainWorktree, registryDir, entry.worktree);
+        changed = true;
+    }
+    if (changed)
+        writeSlots(mainWorktree, registryDir, registry);
+    return liveOrphans;
+}
+function hintLiveOrphans(liveOrphans) {
+    if (liveOrphans.length === 0)
+        return;
+    console.log(`\nNote: ${liveOrphans.length} workspace(s) have a deleted worktree but a still-running ` +
+        "dev-server. Run `workspace prune` to stop them and clean up.");
+}
+async function runPrune(registryDir) {
+    const ctx = detectWorktree();
+    const registry = readSlots(ctx.mainWorktree, registryDir);
+    const orphanPorts = findOrphanPorts(registry);
+    let stoppedProcesses = 0;
+    for (const port of orphanPorts) {
+        const entry = registry.slots[port];
+        stoppedProcesses += await stopOrphanedDevServer(ctx.mainWorktree, registryDir, entry.worktree);
+        delete registry.slots[port];
+        const ownerSuffix = entry.owner ? `, owner ${entry.owner}` : "";
+        console.log(`Pruned slot ${port} (${entry.worktree}${ownerSuffix}).`);
+    }
+    if (orphanPorts.length > 0)
+        writeSlots(ctx.mainWorktree, registryDir, registry);
+    pruneGitWorktrees(ctx.mainWorktree);
+    if (orphanPorts.length === 0) {
+        console.log("No orphaned workspaces to prune.");
+        return;
+    }
+    console.log(`Pruned ${orphanPorts.length} orphaned workspace(s).`);
+    if (stoppedProcesses > 0) {
+        console.log(`Stopped ${stoppedProcesses} orphaned process(es). Note: infrastructure managed by callback ` +
+            "servers (e.g. `docker compose`) is not torn down automatically — check for leftover containers.");
+    }
+}
+/**
+ * Stop a gone worktree's dev-server the only way left: its dir (and `dev-server.mjs`) is deleted, so
+ * we can't shell out to `dev down` to run callback stop() — we kill the recorded spawn PIDs directly
+ * and drop the dev-server entry. Returns the count of live PIDs stopped. Callback-managed infra is
+ * not torn down (see `runPrune`'s caveat).
+ */
+async function stopOrphanedDevServer(mainWorktree, registryDir, worktree) {
+    const devEntry = findOwnEntry(mainWorktree, registryDir, worktree);
+    if (!devEntry)
+        return 0;
+    let stopped = 0;
+    for (const pid of Object.values(devEntry.pids)) {
+        if (isProcessAlive(pid)) {
+            await stopProcessGroup(pid);
+            ++stopped;
+        }
+    }
+    removeDevServerEntryByWorktree(mainWorktree, registryDir, worktree);
+    return stopped;
+}
+/** Best-effort: clear git's stale `.git/worktrees/<name>` admin files for deleted worktrees. */
+function pruneGitWorktrees(mainWorktree) {
+    try {
+        execFileSync("git", ["worktree", "prune"], { cwd: mainWorktree, stdio: "ignore" });
+    }
+    catch {
+        // Best-effort; nothing actionable if git is unavailable.
+    }
 }
 async function runWait(command, config, registryDir) {
     // standalone `workspace wait` (no prior setup in this invocation) → print the full summary on success.
@@ -392,8 +508,10 @@ async function handleRemove(command, ctx, run, config, registryDir) {
     const ownerSuffix = target.owner ? `, owner ${target.owner}` : "";
     if (!existsSync(target.worktreePath)) {
         console.warn(`Warning: Worktree directory ${target.worktreePath} not found. Cleaning up registry only.`);
+        await stopOrphanedDevServer(ctx.mainWorktree, registryDir, target.worktreePath);
         delete registry.slots[target.slotPort];
         writeSlots(ctx.mainWorktree, registryDir, registry);
+        pruneGitWorktrees(ctx.mainWorktree);
         console.log(`Removed registry entry for branch "${target.branch}" (slot ${target.slotPort}${ownerSuffix}).`);
         return;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paleo/workspace",
-  "version": "0.19.1",
+  "version": "0.21.0",
   "description": "Run multiple git-worktree dev environments side by side.",
   "keywords": [
     "workspace",
@@ -30,7 +30,8 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "templates"
   ],
   "publishConfig": {
     "access": "public"

package/templates/guide.md

@@ -0,0 +1,91 @@
+# Workspace & Dev Server — Guide
+
+A **workspace** is a git worktree (with its branch) plus its own dev setup: dedicated ports, config files, a database, and a dev server you can bring up or down. Workspaces are isolated, so you can run several branches in parallel.
+
+## Setting up a workspace
+
+```sh
+{{COMMANDS:setup}}
+```
+
+With `-c`, the new branch starts at the current worktree's HEAD (like `git switch -c`); `--from <ref>` accepts any commit-ish as the base.
+
+The foreground command creates the worktree, assigns a port slot, sets up symlinks, and generates config files. The remaining steps (dependency install, build, database provisioning) run **detached in the background** and stream to the setup log, ending with a `READY:` or `FAILED:` banner. Add `--wait` to block until that banner.
+
+**Main worktree:** from a fresh clone, run `setup` once on the main worktree before creating linked worktrees.
+
+### Recovery from a failed setup
+
+If the background finalize fails (check the setup log), do **not** delete the worktree. From inside it, `setup` is idempotent — repeat until the log ends with `READY:`:
+
+```sh
+{{COMMANDS:recovery}}
+```
+
+**Edge case** — if setup errors with `ERR_MODULE_NOT_FOUND: Cannot find package '@paleo/workspace'`, the worktree never got `node_modules/` (finalize failed before the install). Fall back to the main worktree's wrapper directly:
+
+```sh
+cd <failed-worktree>
+node <main-worktree>/<path-to>/workspace.mjs setup
+```
+
+## Inspecting workspaces
+
+```sh
+{{COMMANDS:inspect}}
+```
+
+### Slot owner
+
+Each slot records an optional owner (free-form label). An AI bot passes its username; on a personal laptop, omit it.
+
+```sh
+{{COMMANDS:owner}}
+```
+
+## Removing a workspace
+
+```sh
+{{COMMANDS:remove}}
+```
+
+Stops the dev server (if running), tears down infrastructure, frees the slot, and removes the worktree. The local branch is always kept. Removal refuses on uncommitted changes — pass `--force` to discard them. When removing the current worktree, the script prints the main worktree path; `cd` there afterward.
+
+**NEVER** delete a branch unless the user explicitly requests it.
+
+### Healing orphaned workspaces
+
+A workspace is **orphaned** when its worktree dir was deleted out-of-band (manual `rm -rf`, bare `git worktree remove`). `list` auto-drops the safe ones (no live dev-server). For the rest:
+
+```sh
+{{COMMANDS:prune}}
+```
+
+### A worktree without setup
+
+When you only want a worktree (no ports, no build, no config), use the `git worktree` CLI directly.
+
+## Dev server
+
+`{{DEV_BASE}}` starts the dev server in the **foreground**: it holds the terminal, tails logs, and stops cleanly on CTRL+C. For agents, `up` starts it in the **background** and returns once ready.
+
+```sh
+{{COMMANDS:dev}}
+```
+
+**Concurrent cap.** `dev` / `dev up` cap simultaneously running dev-servers. At the cap, the start errors with a table of active servers and exits non-zero. Free a slot via `down` in another worktree, `down --all`, or `up --evict` (stops the oldest live one and starts).
+
+**Two-tier shutdown.** `down` (and a foreground CTRL+C) only kill dev-server processes — they leave infrastructure (Docker containers, databases) running so restarts stay fast. Full infrastructure cleanup happens via `workspace remove` when tearing the worktree down entirely.
+
+### Driving the dev server in another worktree
+
+```sh
+{{SNIPPET:drive-dev}}
+```
+
+## Directory layout
+
+- `{{RUNTIME_DIR}}/` — per-worktree runtime data (not shared). Names below are fixed by the package:
+  - `logs/` — dev-server + setup logs.
+  - `{{REGISTRY_SUBDIR}}/` — the registry. Symlinked to the main worktree in linked worktrees.
+{{LAYOUT:shared}}