@boopkit/cli 0.8.0 → 0.8.1

package/dist/lib/scaffold.d.ts

@@ -31,6 +31,12 @@ export declare function renderTemplate(templateContent: string, variables: Templ
  */
 export declare function getTemplatesDir(profileName: string): string;
 export declare function profileHasTemplates(profileName: string): boolean;
+/**
+ * The minimal package.json the `base` profile ships, rendered for a project.
+ * boop records every capability as an npm package there, so a project without
+ * one (a native iOS app, say) gets this one before its first capability.
+ */
+export declare function renderBasePackageJson(projectName: string): string;
 /**
  * Copy and render every file in a templates directory (the kernel templates
  * by default) into a target directory. Creates directories as needed. Does
@@ -51,7 +57,7 @@ export declare function hashContent(content: Buffer): string;
  * Tries package resolution first (scaffold/ and skills/ dirs), falls back to source tree.
  * Returns list of copied file paths relative to targetDir, and file hashes.
  */
-export declare function copyCapabilityFiles(targetDir: string, capabilityName: string, searchPaths?: string[]): string[];
+export declare function copyCapabilityFiles(targetDir: string, capabilityName: string, searchPaths?: string[], excludePaths?: string[]): string[];
 /**
  * Symlink each skill folder under `<targetDir>/skills/` into
  * `<targetDir>/.claude/skills/` so Claude Code's built-in Skill tool
@@ -66,6 +72,11 @@ export declare function copyCapabilityFiles(targetDir: string, capabilityName: s
  * `boop init` link all of it; the boop repository mirrors the whole library
  * there and needs to offer only the part its manifest selects.
  *
+ * A link left pointing into `skills/` at a folder that no longer stands there
+ * (the project deleted the skill, or a capability stopped shipping it) is
+ * removed, so the links follow the folders. Only symlinks into `skills/` are
+ * pruned; a link the project made to anywhere else is never touched.
+ *
  * Idempotent. Returns the relative paths of symlinks created or already present.
  */
 export declare function linkSkillsToClaude(targetDir: string, only?: Iterable<string>): string[];

package/dist/lib/scaffold.js

@@ -39,6 +39,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.renderTemplate = renderTemplate;
 exports.getTemplatesDir = getTemplatesDir;
 exports.profileHasTemplates = profileHasTemplates;
+exports.renderBasePackageJson = renderBasePackageJson;
 exports.scaffoldKernel = scaffoldKernel;
 exports.hashFile = hashFile;
 exports.hashContent = hashContent;
@@ -97,6 +98,15 @@ function profileHasTemplates(profileName) {
 function getProfileTemplatesDir(profileName) {
     return path.join((0, config_1.getBoopRoot)(), 'profiles', profileName, 'templates');
 }
+/**
+ * The minimal package.json the `base` profile ships, rendered for a project.
+ * boop records every capability as an npm package there, so a project without
+ * one (a native iOS app, say) gets this one before its first capability.
+ */
+function renderBasePackageJson(projectName) {
+    const template = fs.readFileSync(path.join(getProfileTemplatesDir('base'), 'package.json.hbs'), 'utf-8');
+    return renderTemplate(template, { projectName });
+}
 /**
  * Copy and render every file in a templates directory (the kernel templates
  * by default) into a target directory. Creates directories as needed. Does
@@ -156,7 +166,7 @@ function hashContent(content) {
  * Tries package resolution first (scaffold/ and skills/ dirs), falls back to source tree.
  * Returns list of copied file paths relative to targetDir, and file hashes.
  */
-function copyCapabilityFiles(targetDir, capabilityName, searchPaths) {
+function copyCapabilityFiles(targetDir, capabilityName, searchPaths, excludePaths = []) {
     // Default to the project itself, so this resolves the capability to the same
     // package `planAdd` did. Without it a capability that lives only under the
     // project resolved here to nothing, and `boop add` reported every file copied
@@ -168,7 +178,7 @@ function copyCapabilityFiles(targetDir, capabilityName, searchPaths) {
         const pkgJson = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf-8'));
         const boopkit = pkgJson.boopkit;
         if (boopkit?.capability) {
-            return copyFromPackage(targetDir, capabilityName, pkgDir);
+            return copyFromPackage(targetDir, capabilityName, pkgDir, excludePaths);
         }
     }
     // Fallback to source tree
@@ -200,8 +210,9 @@ function copyPlacements(targetDir, placements) {
 /**
  * Copy capability files from a package directory.
  */
-function copyFromPackage(targetDir, capabilityName, pkgDir) {
-    const { copied, fileHashes } = copyPlacements(targetDir, (0, install_layout_1.capabilityPlacementsFromDir)(pkgDir));
+function copyFromPackage(targetDir, capabilityName, pkgDir, excludePaths) {
+    const placements = (0, install_layout_1.capabilityPlacementsFromDir)(pkgDir).filter(p => !(0, install_layout_1.isUnderAny)(p.dest, excludePaths));
+    const { copied, fileHashes } = copyPlacements(targetDir, placements);
     // Store file hashes and version in .boop/config.json
     if (Object.keys(fileHashes).length > 0) {
         const pkgJson = JSON.parse(fs.readFileSync(path.join(pkgDir, 'package.json'), 'utf-8'));
@@ -223,10 +234,16 @@ function copyFromPackage(targetDir, capabilityName, pkgDir) {
  * `boop init` link all of it; the boop repository mirrors the whole library
  * there and needs to offer only the part its manifest selects.
  *
+ * A link left pointing into `skills/` at a folder that no longer stands there
+ * (the project deleted the skill, or a capability stopped shipping it) is
+ * removed, so the links follow the folders. Only symlinks into `skills/` are
+ * pruned; a link the project made to anywhere else is never touched.
+ *
  * Idempotent. Returns the relative paths of symlinks created or already present.
  */
 function linkSkillsToClaude(targetDir, only) {
     const skillsDir = path.join(targetDir, 'skills');
+    pruneDanglingSkillLinks(targetDir);
     if (!fs.existsSync(skillsDir))
         return [];
     const selected = only === undefined ? null : new Set(only);
@@ -255,6 +272,28 @@ function linkSkillsToClaude(targetDir, only) {
     }
     return linked;
 }
+/**
+ * Remove each symlink in `<targetDir>/.claude/skills/` that points into
+ * `<targetDir>/skills/` at an entry that no longer exists.
+ */
+function pruneDanglingSkillLinks(targetDir) {
+    const skillsDir = path.join(targetDir, 'skills');
+    const claudeSkillsDir = path.join(targetDir, '.claude', 'skills');
+    if (!fs.existsSync(claudeSkillsDir))
+        return;
+    for (const entry of fs.readdirSync(claudeSkillsDir, { withFileTypes: true })) {
+        if (!entry.isSymbolicLink())
+            continue;
+        const linkPath = path.join(claudeSkillsDir, entry.name);
+        const resolved = path.resolve(claudeSkillsDir, fs.readlinkSync(linkPath));
+        if (!resolved.startsWith(skillsDir + path.sep))
+            continue;
+        // lstat, so a skills/ entry that is itself a symlink counts as present.
+        if (fs.lstatSync(resolved, { throwIfNoEntry: false }))
+            continue;
+        fs.unlinkSync(linkPath);
+    }
+}
 /**
  * The names of the skill folders under `<targetDir>/skills/` that boop installed.
  *

package/dist/lib/update.d.ts

@@ -17,7 +17,7 @@ export interface FileUpdateAction {
     /** Relative path from project root */
     relativePath: string;
     /** What will happen to this file */
-    action: 'overwrite' | 'skip' | 'add' | 'deprecate' | 'migrate' | 'record-hash';
+    action: 'overwrite' | 'skip' | 'add' | 'deprecate' | 'migrate' | 'record-hash' | 'move' | 'remove';
     /** Why this action was chosen */
     reason: string;
     /** Stored hash from config */
@@ -38,6 +38,12 @@ export interface FileUpdateAction {
     instruction?: string;
     /** boop's current copy of the file, when the instruction points at it */
     upstreamPath?: string;
+    /** For a path another capability ships now: where it ships */
+    movedTo?: string;
+    /** For a path another capability ships now: that capability */
+    toCapability?: string;
+    /** For the move of a skill folder: whether its PROJECT.md held more than the template */
+    projectFileCarried?: boolean;
 }
 export interface FileInstruction {
     relativePath: string;
@@ -82,6 +88,16 @@ export interface UpdateResult {
     unchangedCount: number;
     /** What to do about the files this update skipped or replaced, where the report says anything */
     instructions: FileInstruction[];
+    /** Paths moved to another capability, by the move pass */
+    moved: {
+        from: string;
+        to: string;
+        toCapability: string;
+    }[];
+    /** Skill folders deleted because another capability ships them now and this project does not install it */
+    removed: string[];
+    /** Moved paths left where they are until the instruction for them is followed */
+    movesWaiting: string[];
 }
 /** The skill that splits a drifted SKILL.md — keep in step with the folder name boop-rm2l.8 gives it */
 export declare const TRIAGE_SKILL = "boop-skills-edit-triage";
@@ -91,11 +107,21 @@ export declare const SKILL_EDITS_INSTRUCTION = "Move each skill's edits into the
  * Compare a file's current hash against a stored hash.
  */
 export declare function compareFileHash(filePath: string, storedHash: string): FileState;
+export interface PlanOptions {
+    /**
+     * The move pass's actions for paths leaving this capability. Each replaces
+     * whatever this planner would plan for the paths it covers; a skip whose
+     * `relativePath` is a folder covers every stored path inside it.
+     */
+    moves?: FileUpdateAction[];
+    /** Paths arriving in this capability by a move not yet carried out, which the move lists instead */
+    arriving?: string[];
+}
 /**
  * Plan an update for a single capability. Returns null if the capability
  * is not installed or has no package.
  */
-export declare function planCapabilityUpdate(targetDir: string, capabilityName: string, projectManifest: BoopManifest): UpdatePlan | null;
+export declare function planCapabilityUpdate(targetDir: string, capabilityName: string, projectManifest: BoopManifest, options?: PlanOptions): UpdatePlan | null;
 /**
  * Execute an update plan, writing files and updating config.
  * If force is true, overwrites even locally modified files (with backup).
@@ -105,6 +131,14 @@ export declare function executeUpdatePlan(plan: UpdatePlan, options?: {
     restore?: boolean;
     prune?: boolean;
 }): UpdateResult;
+/**
+ * Rewrite each capability's stored env record (capabilityConfig[cap].env) from
+ * the env its installed package declares. A variable the package still declares
+ * keeps its `set` flag; one it no longer declares is dropped, and a capability
+ * that declares none loses its record. `boop status` prefers this record over
+ * the package, so a stale one would list a moved variable under both capabilities.
+ */
+export declare function refreshCapabilityEnv(targetDir: string, capabilities: string[]): void;
 /**
  * Count the skills a capability's project copy has edited in SKILL.md, and how
  * many of those boop has changed since — from the same comparison `boop update`

package/dist/lib/update.js

@@ -43,6 +43,7 @@ exports.SKILL_EDITS_INSTRUCTION = exports.TRIAGE_SKILL = void 0;
 exports.compareFileHash = compareFileHash;
 exports.planCapabilityUpdate = planCapabilityUpdate;
 exports.executeUpdatePlan = executeUpdatePlan;
+exports.refreshCapabilityEnv = refreshCapabilityEnv;
 exports.countSkillEdits = countSkillEdits;
 exports.formatUpdateSummary = formatUpdateSummary;
 const fs = __importStar(require("fs"));
@@ -71,7 +72,7 @@ function compareFileHash(filePath, storedHash) {
  * Plan an update for a single capability. Returns null if the capability
  * is not installed or has no package.
  */
-function planCapabilityUpdate(targetDir, capabilityName, projectManifest) {
+function planCapabilityUpdate(targetDir, capabilityName, projectManifest, options = {}) {
     // Capability must be installed
     if (!projectManifest.capabilities.includes(capabilityName)) {
         return null;
@@ -102,8 +103,14 @@ function planCapabilityUpdate(targetDir, capabilityName, projectManifest) {
     for (const placement of (0, install_layout_1.capabilityPlacementsFromDir)(pkgDir)) {
         packageFiles.set(placement.dest, placement.source);
     }
+    const arriving = options.arriving ?? [];
+    const moves = options.moves ?? [];
+    // A held move is one action for a whole folder, named without its trailing slash
+    const coveredByMove = (relPath) => moves.some(m => (0, install_layout_1.isUnderAny)(relPath, [m.relativePath, m.relativePath + '/']));
     // For each file in the package, determine action
     for (const [relPath, srcPath] of packageFiles) {
+        if ((0, install_layout_1.isUnderAny)(relPath, arriving))
+            continue;
         const destPath = path.join(targetDir, relPath);
         const storedHash = storedHashes[relPath];
         const newHash = (0, scaffold_1.hashFile)(srcPath);
@@ -210,7 +217,7 @@ function planCapabilityUpdate(targetDir, capabilityName, projectManifest) {
     }
     // Check for files removed from package (in stored hashes but not in package)
     for (const relPath of Object.keys(storedHashes)) {
-        if (!packageFiles.has(relPath)) {
+        if (!packageFiles.has(relPath) && !coveredByMove(relPath)) {
             actions.push({
                 relativePath: relPath,
                 action: 'deprecate',
@@ -269,6 +276,7 @@ function planCapabilityUpdate(targetDir, capabilityName, projectManifest) {
             // oldState === 'missing': old file already gone, add new files normally
         }
     }
+    actions.push(...moves);
     // A capability that ships a new command ships it as a file and a script; an
     // update that delivered only the file left nothing able to run it (boop-ldou).
     const scriptActions = (0, script_merge_1.planScriptUpdates)(capJson.scripts, (0, script_merge_1.readProjectScripts)(targetDir));
@@ -304,6 +312,9 @@ function executeUpdatePlan(plan, options = {}) {
         scriptsKept: [],
         unchangedCount: plan.unchangedCount,
         instructions: [],
+        moved: [],
+        removed: [],
+        movesWaiting: [],
     };
     const pkgJson = JSON.parse(fs.readFileSync(path.join(plan.packageDir, 'package.json'), 'utf-8'));
     const boopkit = pkgJson.boopkit;
@@ -335,7 +346,13 @@ function executeUpdatePlan(plan, options = {}) {
                 break;
             case 'skip': {
                 const isLocallyDeleted = action.reason === 'Locally deleted';
-                if (isLocallyDeleted && options.restore) {
+                if (action.movedTo) {
+                    // A move waiting on something only a person or another command can settle; --force and --restore do not apply
+                    result.skipped.push(action.relativePath);
+                    result.movesWaiting.push(action.relativePath);
+                    result.instructions.push({ relativePath: action.relativePath, instruction: action.instruction });
+                }
+                else if (isLocallyDeleted && options.restore) {
                     // Restore mode: re-add locally deleted files
                     const srcPath = resolveSourcePath(plan.packageDir, action.relativePath);
                     if (srcPath) {
@@ -428,15 +445,27 @@ function executeUpdatePlan(plan, options = {}) {
         if (!manifest.capabilityMeta) {
             manifest.capabilityMeta = {};
         }
+        const previous = manifest.capabilityMeta[plan.capability];
         manifest.capabilityMeta[plan.capability] = {
             installedAt: new Date().toISOString(),
             version: plan.newVersion,
             fileHashes: newHashes,
+            ...movedFromStill(previous, newHashes),
         };
         (0, project_1.writeProjectManifest)(plan.targetDir, manifest);
     }
     return result;
 }
+/**
+ * The `movedFrom` entries still worth keeping: once this capability writes a
+ * file's hash itself, the base is a file it shipped, and the old path no longer
+ * leads to the original text.
+ */
+function movedFromStill(previous, newHashes) {
+    const kept = Object.entries(previous?.movedFrom ?? {})
+        .filter(([p]) => newHashes[p] !== undefined && newHashes[p] === previous.fileHashes[p]);
+    return kept.length > 0 ? { movedFrom: Object.fromEntries(kept) } : {};
+}
 /**
  * What to tell whoever ran the update about a file it skipped, or nothing.
  * `drift` is absent for a file boop has no stored hash for.
@@ -486,6 +515,40 @@ function displayPath(targetDir, filePath) {
     const relative = path.relative(targetDir, filePath);
     return relative.startsWith('..') || path.isAbsolute(relative) ? filePath : relative;
 }
+/**
+ * Rewrite each capability's stored env record (capabilityConfig[cap].env) from
+ * the env its installed package declares. A variable the package still declares
+ * keeps its `set` flag; one it no longer declares is dropped, and a capability
+ * that declares none loses its record. `boop status` prefers this record over
+ * the package, so a stale one would list a moved variable under both capabilities.
+ */
+function refreshCapabilityEnv(targetDir, capabilities) {
+    const manifest = (0, project_1.readProjectManifest)(targetDir);
+    if (!manifest)
+        return;
+    const config = manifest.capabilityConfig ?? {};
+    for (const cap of capabilities) {
+        const meta = (0, capability_1.getCapability)(cap, [targetDir]);
+        if (!meta)
+            continue;
+        const stored = config[cap]?.env ?? {};
+        if (meta.env && meta.env.length > 0) {
+            const env = {};
+            for (const e of meta.env) {
+                env[e.name] = { required: e.required, set: stored[e.name]?.set ?? false };
+            }
+            config[cap] = { env };
+        }
+        else {
+            delete config[cap];
+        }
+    }
+    if (Object.keys(config).length > 0)
+        manifest.capabilityConfig = config;
+    else
+        delete manifest.capabilityConfig;
+    (0, project_1.writeProjectManifest)(targetDir, manifest);
+}
 /**
  * Count the skills a capability's project copy has edited in SKILL.md, and how
  * many of those boop has changed since — from the same comparison `boop update`
@@ -523,6 +586,17 @@ function resolveSourcePath(pkgDir, relativePath) {
  */
 function formatUpdateSummary(result) {
     const parts = [];
+    const movedTo = new Map();
+    for (const m of result.moved ?? [])
+        movedTo.set(m.toCapability, [...(movedTo.get(m.toCapability) ?? []), m]);
+    for (const [capability, moves] of movedTo) {
+        const noun = moves.every(m => m.from.endsWith('/')) ? 'skill' : 'file';
+        parts.push(`moved ${moves.length} ${noun}${moves.length === 1 ? '' : 's'} to ${capability}`);
+    }
+    const removed = result.removed?.length || 0;
+    if (removed > 0) {
+        parts.push(`removed ${removed} skill${removed === 1 ? '' : 's'}`);
+    }
     if (result.migrated && result.migrated.length > 0) {
         parts.push(`migrated ${result.migrated.length} skill${result.migrated.length === 1 ? '' : 's'}`);
     }
@@ -533,7 +607,11 @@ function formatUpdateSummary(result) {
     if (result.forcedOverwrite.length > 0) {
         parts.push(`force-overwrote ${result.forcedOverwrite.length} modified file${result.forcedOverwrite.length === 1 ? '' : 's'}`);
     }
-    const skippedModified = result.skipped.length - (result.skippedDeleted?.length || 0);
+    const waiting = result.movesWaiting?.length || 0;
+    if (waiting > 0) {
+        parts.push(`${waiting} move${waiting === 1 ? '' : 's'} waiting`);
+    }
+    const skippedModified = result.skipped.length - (result.skippedDeleted?.length || 0) - waiting;
     if (skippedModified > 0) {
         parts.push(`skipped ${skippedModified} (locally modified)`);
     }

package/docs/init.md

@@ -66,6 +66,7 @@ It has neither a kernel nor templates, so there is nothing for `boop init` to wr
 and `boop init --profile development` is refused with a pointer to the two ways it is meant to be used:
 naming it as the `profile` in an existing project's `.boop/config.json`,
 or `boop add` for the capabilities you want.
+The second is the usual one; see [Bringing Boop Into an Existing Project](#bringing-boop-into-an-existing-project).
 
 ## What It Creates
 
@@ -207,6 +208,27 @@ The counts change as capabilities grow.
 A `base` project's summary counts template files rather than kernel files,
 and its next steps stop at `boop status`, because there is no development server to start.
 
+## Bringing Boop Into an Existing Project
+
+`boop init` only creates new projects: it refuses a folder that is not empty.
+To bring boop's development capabilities into a project something else made —
+an app from `create-expo-app` or Xcode, a CLI, a library —
+run `boop add` in that project for each capability you want:
+
+```bash
+cd my-expo-app
+boop add project-mgmt
+boop add coding
+boop status
+```
+
+The first `boop add` creates the `.boop/config.json` the project lacks and says so in its output.
+The project is named after the `name` in its `package.json`, or after its folder when there is none,
+and its profile is recorded as `development`.
+A project with no `package.json` at all, such as a native iOS or Android app, also gets a minimal one,
+the same one the `base` profile writes, because boop delivers every capability as an npm package recorded there.
+If an add is refused — a capability that needs another one added first, for example — it creates neither file.
+
 ## What To Do After Init
 
 Run the commands under "Next steps".

package/docs/loop.md

@@ -115,14 +115,22 @@ For each ready branch (one at a time, with `main` as the integration branch):
 
 1. **Readiness** — a branch is ready when every beads issue in its scope is closed (scope is read from the worktree's `.boop-worktree.json`). `bd ready` is insufficient here — it only lists *unblocked* issues — so `--merge` lists by status and filters by scope. An explicit `boop loop --merge work/<scope>` skips this check.
 2. **Rebase onto main** inside the worktree. Only **`package.json` dependency conflicts** are auto-resolved (union of dependencies; same-key version conflicts take the higher semver). Any other conflict aborts the rebase, files a beads bug, and skips to the next branch.
-3. **Run `npm test`** in the worktree. On failure the branch is reset to its pre-rebase commit, a beads bug is filed, and the branch is skipped.
+   A rebase that does not complete for any other reason is handled the same way, before any test runs: the branch is skipped, its worktree and `main` are left as they were, and the filed bug says why.
+   The common case is a worktree with uncommitted changes to tracked files (the loop's `npm install` can rewrite `package-lock.json`); the bug then names those files, and you commit or discard them in the worktree before running `--merge` again.
+   When git refuses the rebase for another reason, such as an untracked file that `main` would overwrite, the bug carries git's own message.
+3. **Run `npm test`** in the worktree. On failure the branch is reset to its pre-rebase commit, a beads bug is filed, and the branch is skipped. The bug names the branch and the restored commit, and carries the first failures and the Jest summary, each capped in length; the full test output is saved to `labs/claude-runs/_merge_<branch>_<timestamp>.log` and the bug gives its path.
 4. **Fast-forward merge** into `main`, then remove the worktree and delete the merged branch.
 
-**Safety contract:** `main` is never left dirty. The integration tree must be on a clean `main` before merging; a rebase conflict aborts cleanly, and a post-rebase test failure resets the feature branch. Every merge runs the test suite before completing, so no merge lands untested.
+**Safety contract:** `main` is never left dirty. The integration tree must be on a clean `main` before merging; a rebase conflict aborts cleanly, a rebase that does not complete is never tested or merged, and a post-rebase test failure resets the feature branch. Every merge runs the test suite before completing, so no merge lands untested.
+
+**Beads export files do not block a merge.** `bd` rewrites `.beads/interactions.jsonl` in the main checkout whenever it runs, including every `bd` command a loop session runs from inside its own worktree, so after any loop `main` shows that file modified.
+`--merge` treats an uncommitted change to `.beads/interactions.jsonl` or `.beads/issues.jsonl` as beads bookkeeping rather than work in progress: it merges past it and leaves the change in place for you to commit when you choose.
+Any other uncommitted change still stops the merge, and the message names the files.
+One exception keeps the fast-forward from running over your change: if a branch itself changes an export file that is uncommitted in `main`, that branch is skipped with a message saying so, and the other ready branches still merge. Commit the file in `main` and run `--merge` again.
 
 ## Logs
 
-Session logs are written to `labs/claude-runs/` in the project directory. Each issue produces a log file named `<issue-id>_<timestamp>.log` containing the full Claude stream-json output.
+Session logs are written to `labs/claude-runs/` in the project directory. Each issue produces a log file named `<issue-id>_<timestamp>.log` containing the full Claude stream-json output. A `--merge` test failure saves the full test output as `_merge_<branch>_<timestamp>.log`.
 
 ## Safety
 

package/docs/skills.md

@@ -20,15 +20,18 @@ Every capability ships **agent skills** — focused `SKILL.md` guides that `boop
 - **boop-product-design-feature-documentation** — When you need to document a complex feature, function, or system — including when you frame the task as 'write the docs', 'write a README', 'write up how X works', or 'explain this for the next reader who picks it up cold'.
 - **boop-product-design-feature-requirements** — When you need to write a feature spec, draft a spec document, or turn a brief or vague directive into requirements — i.e. define what a feature should accomplish before designing how to build it. This fires even when you frame the task to yourself as just 'writing a spec' or 'matching the house spec format': reading an existing spec to imitate its shape is not a substitute for the method, and the more competent you feel at the raw task the more this applies. Start with the user's jobs to be done, in frequency order; take and defend a stance; then derive goals, non-goals, and success metrics.
 - **boop-product-design-reference-integration** — When you need to integrate new knowledge into the project's `reference/` directory after completing a feature, fixing a bug that changes behavior, or adding a capability.
+- **boop-product-design-knowledge-backfill** — When you need to integrate new knowledge from a set of specs or completed work that was not documented in reference at the time it shipped. This often happens when a feature is developed under a tight deadline and the team prioritizes shipping over documentation, or when work was done before the reference system was fully established.
 - **boop-product-design-thought-partnership** — When the user wants to think out loud through a design — a feature, a capability, a strategic direction — be a thought partner, not an implementer: hold the conversation at user-and-value altitude, honor uncertainty with hypotheses rather than pretend-decisions, and keep software-shaped concerns downstream of the user's lived problems.
 - **boop-writing-technical-prose** — When writing chat responses, summaries, bd issue bodies, specifications, specs, or any artifact a fresh reader will pick up cold, write grammatical conversational English. Avoid the agent-shorthand patterns that compress meaning at the cost of legibility.
 - **boop-writing-documents** — When you need to write a document someone will read cold and act on — a proposal, strategy memo, analysis, recommendation, or status write-up — and want the discipline of the Amazon six-pager: narrative prose, a declared length budget, claims that carry their evidence, and the hard questions answered inside the document.
 - **boop-writing-semantic-line-breaks** — When you need to write or edit prose in a markdown file under version control — a spec, a reference page, a README, a skill — break lines at semantic boundaries rather than at a fixed column, so that edits produce readable diffs.
 
-### `project-mgmt` — Project management with beads
+### `project-mgmt` — Project management with beads: planning, issue sweeps and stray disposition
 
 - **boop-project-mgmt-beads-planning** — When you need to write and organize beads issues so that any fresh agent can pick up work.
 - **boop-project-mgmt-engineering-planning** — When you need to decompose a design into an executable plan of work — including when you frame the task as 'make a plan', 'break this into tasks or steps', 'figure out the order of work', or planning a build before you start writing issues. Order the work by uncertainty reduction, not just demonstrable value.
+- **boop-project-mgmt-issue-sweep-workflow** — When the bd queue has accumulated a noisy backlog of lingering P1/P2 items — paper-cuts, small refactors, dead code, cosmetic bugs, taxonomy drift — and you want to clear them autonomously in a sequence that supports the week's goals, follow this process: inventory → cluster by theme → pick a cluster with the operator → run autonomously in one sweep worktree → hand off for a single UAT pass → log. The work lands in a worktree for one operator review rather than on main; it arrives with no decisions left in it.
+- **boop-project-mgmt-stray-disposition** — When an autonomous run (a loop, a sweep, a sub-agent session) has finished and filed follow-up issues along the way, settle each one before you write the closing summary. Every stray gets a recorded disposition — re-parented and reachable from the roadmap, folded into a spec and closed, or triaged away. Use this whenever a run ends with issues in the queue that nobody has decided to do.
 
 ### `skills` — Skill authoring
 
@@ -40,31 +43,29 @@ Every capability ships **agent skills** — focused `SKILL.md` guides that `boop
 - **boop-skills-hyperlinking** — When you need to add, review, or repair a `## Related` section that points one skill at another, follow these rules for what earns a link, how to phrase it, which way it points, how many are too many, and how to write a path that survives `boop add`.
 - **boop-skills-edit-triage** — When you need to move a project's edits out of a boop skill's SKILL.md — because `boop update` or `boop status` reports the skill as edited here, or `boop migrate-skill-edits` wrote a plan for it — decide whether each edit is kept in this project, offered to boop, or dropped, and rewrite each kept edit as a standalone rule for the PROJECT.md beside it. Not for reference pages, which are blended rather than split.
 
-### `testing` — Jest testing setup
+### `testing` — Testing method: the testing principles and the TDD-Lite workflow
 
 - **boop-testing-tdd-light** — When you need to build features, implement changes, or fix bugs, follow the Light TDD Flow. This includes bug fixes found during UAT — write the failing test *before* applying the fix.
-- **boop-testing-testing-express-web** — When you need to write or run tests for the Express server — services, controllers, middleware, and HTTP routes.
 - **boop-testing-testing** — When you need to write, run, or reason about tests in this project.
 
+### `typescript` — TypeScript toolchain: Jest with ts-jest, and the whole-program type check
+
+- **boop-typescript-testing** — When you need to run, configure, or debug tests in a TypeScript project — how `npm test` and `npm run typecheck` behave under Jest, ts-jest and `tsc`.
+
 ### `ux` — UX design judgement and the discovery/delivery workflows that operate it
 
-- **boop-ux-purpose-judgement** — When you are evaluating a rendered page and need to judge whether each thing on it belongs there, in the right shape, for the right job. Asks the structural question that the visual lens does not — is this affordance the right idea, not just rendered well. Pairs with ux-visual-judgement (the question of how things look and scan).
-- **boop-ux-visual-judgement** — When you are evaluating a rendered page and need to form a principled judgement about how it looks and scans. Visual lens only — eye-path, register, anatomy, scan-line, gestalt, density, voice. Pairs with ux-purpose-judgement (the question of whether each element belongs at all) and with the CSS skill (the grammar of how things are rendered).
-- **boop-ux-eval-and-refine-workflow** — When you are tasked with iteratively evaluating and improving an existing rendered page (discovery, not delivery), follow this workflow. Inner loop: capture → eval → recommend → implement → re-capture. Outer: knowledge integration.
-- **boop-ux-app-ui-dev-workflow** — When you are tasked with improving an existing app-side page (app UX, not marketing) end-to-end and the input is a target page rather than a written spec, follow this beads-issue-per-step workflow. Sibling to feature-dev-workflow but stripped of backend phases. The judgement lenses are the planning input.
+- **boop-ux-purpose-judgement** — When you are evaluating a rendered screen or page and need to judge whether each thing on it belongs there, in the right shape, for the right job. Asks the structural question that the visual lens does not — is this affordance the right idea, not just rendered well. Pairs with ux-visual-judgement (the question of how things look and scan).
+- **boop-ux-visual-judgement** — When you are evaluating a rendered screen or page and need to form a principled judgement about how it looks and scans. Visual lens only — eye-path, register, anatomy, scan-line, gestalt, density, voice. Pairs with ux-purpose-judgement (the question of whether each element belongs at all) and with the CSS skill (the grammar of how things are rendered).
+- **boop-ux-eval-and-refine-workflow** — When you are tasked with iteratively evaluating and improving an existing rendered screen or page (discovery, not delivery), follow this workflow. Inner loop: capture → eval → recommend → implement → re-capture. Outer: knowledge integration.
+- **boop-ux-app-ui-dev-workflow** — When you are tasked with improving an existing app-side screen or page (app UX, not marketing) end-to-end and the input is a target screen or page rather than a written spec, follow this beads-issue-per-step workflow. Sibling to feature-dev-workflow but stripped of backend phases. The judgement lenses are the planning input.
 
-### `workflows` — Reusable end-to-end development and writing workflows
+### `workflows` — Reusable end-to-end development and audit workflows for code
 
 - **boop-feature-dev-workflow** — When you are tasked with building a feature end-to-end, follow this guidance.
 - **boop-light-dev-workflow** — When you are extending an existing system (front-end, back-end, or full-stack) toward a goal — wiring something new from data and patterns that already exist, not building greenfield — follow this grounded flow: goal → investigate the real system → design → critique → decompose into one scoped epic + child issues → run them → close out. Loop-drivable via boop loop --work --flow; lighter than feature-dev-workflow.
 - **boop-refactor-dev-workflow** — When you need to change a contract, cardinality, or shape that existing code already depends on — usually to make a feature buildable — follow this workflow instead of the feature workflow.
 - **boop-test-audit-workflow** — Use when a set of tests is not testing the purpose of the code: mocks that verify data the test itself fed in, tests that exercise the platform rather than our code, or a stubbed seam where the integration is the actual risk. Also use when tests are so coupled to the shape of the implementation that they check a label, an exact string, or a call sequence rather than a behaviour. This workflow removes tests that cannot go red for a real reason, rewrites the ones that check a real goal at the wrong level, merges duplicates, and does not lose coverage. It explicitly does not target good tests merely because a coming change will make them need updating. The sibling of light-dev-workflow for reworking tests rather than building features.
 - **boop-architecture-audit-workflow** — When you need to judge whether an area of shipped code is structurally healthy and decide what is worth fixing — undesired coupling, concerns bleeding across layers or domain boundaries, interfaces that are not composable because they are use-case specific or unparameterized — follow this process: scope one area and name the properties it should uphold → check the tests can catch you → measure before reading → grade every property and classify every finding against a named change → critique → operator gate → decompose → execute via refactor-dev-workflow. The sibling of test-audit-workflow for production code rather than tests. Not for finding bugs, and not for executing a structural change you have already decided on.
-- **boop-issue-sweep-workflow** — When the bd queue has accumulated a noisy backlog of lingering P1/P2 items — paper-cuts, small refactors, dead code, cosmetic bugs, taxonomy drift — and you want to clear them autonomously in a sequence that supports the week's goals, follow this process: inventory → cluster by theme → pick a cluster with the operator → run autonomously in one sweep worktree → hand off for a single UAT pass → log. The work lands in a worktree for one operator review rather than on main; it arrives with no decisions left in it.
-- **boop-website-dev-workflow** — When you are tasked with implementing website changes end-to-end (new pages, page rewrites, IA changes, content/CTA updates), follow this guidance.
-- **boop-design-handoff-workflow** — When the operator hands off a design package (a README plus a drop-in view template and CSS) for a redesigned surface, follow this process: read the README, VERIFY its claims against the real code, surface any buried decision to the operator, file an issue, run it as a sub-agent (branch for UAT or merge-on-clean-visual-check), then close out with knowledge integration and archival. The README is confident; confidence is not correctness — verify before you run.
-- **boop-knowledge-backfill** — When you need to integrate new knowledge from a set of specs or completed work that was not documented in reference at the time it shipped. This often happens when a feature is developed under a tight deadline and the team prioritizes shipping over documentation, or when work was done before the reference system was fully established.
-- **boop-stray-disposition** — When an autonomous run (a loop, a sweep, a sub-agent session) has finished and filed follow-up issues along the way, settle each one before you write the closing summary. Every stray gets a recorded disposition — re-parented and reachable from the roadmap, folded into a spec and closed, or triaged away. Use this whenever a run ends with issues in the queue that nobody has decided to do.
 
 ## Application capabilities
 
@@ -101,6 +102,9 @@ Every capability ships **agent skills** — focused `SKILL.md` guides that `boop
 ### `web` — Web UI with Handlebars + Tailwind
 
 - **boop-web-web-ui-design** — When you need to design and implement user interfaces — including when you frame the task as 'build a page', 'add a component', 'style this surface', or 'wire up the UI' — following established patterns and philosophy.
+- **boop-web-testing** — When you need to write or run tests for the Express server — services, controllers, middleware, and HTTP routes.
+- **boop-web-website-dev-workflow** — When you are tasked with implementing website changes end-to-end (new pages, page rewrites, IA changes, content/CTA updates), follow this guidance.
+- **boop-web-design-handoff-workflow** — When the operator hands off a design package (a README plus a drop-in view template and CSS) for a redesigned surface, follow this process: read the README, VERIFY its claims against the real code, surface any buried decision to the operator, file an issue, run it as a sub-agent (branch for UAT or merge-on-clean-visual-check), then close out with knowledge integration and archival. The README is confident; confidence is not correctness — verify before you run.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boopkit/cli",
-  "version": "0.8.0",
+  "version": "0.8.1",
   "description": "boop: the opinionated bootstrap for founder friendly, AI-first web apps - code plus agent skills, composable from day one.",
   "main": "dist/cli.js",
   "workspaces": [

package/profiles/base/profile.md

@@ -31,8 +31,8 @@ and if a file only makes sense for an application, it does not belong here.
 Three capabilities, all of them `type: development`,
 whose skills apply to work that isn't code without any edits:
 
-- **project-mgmt** — beads issue tracking and planning skills
-- **product-design** — requirements, design, documentation and writing skills
+- **project-mgmt** — beads issue tracking, planning, issue sweeps and stray disposition
+- **product-design** — requirements, design, documentation, knowledge backfill and writing skills
 - **skills** — skill authoring, discovery and maintenance
 
 The profile also ships its own `templates/` folder,
@@ -53,25 +53,28 @@ and `boop update` would have nothing to update.
 ## Three Deliberate Omissions
 
 The development capabilities that every other profile carries —
-`coding`, `testing` and `workflows` —
+`coding`, `testing` and `workflows`, and the `typescript` toolchain beside them —
 are left out on purpose.
 An agent takes the skills and files in a project as a hint about what kind of work happens there,
 so every code-shaped thing in the scaffold is an invitation to do code-shaped work.
 
 ### No testing
 
-`testing` installs Jest, `ts-jest`, a `tsconfig.test.json` and a `tests/` folder.
-A project with nothing to test would carry a test runner nobody runs,
-and an agent that finds one will reasonably suggest writing tests for it.
+`testing` installs the testing skills, and `typescript`, which comes with it in the other profiles,
+installs Jest, `ts-jest`, a `tsconfig.test.json` and a `tests/` folder.
+A project with nothing to test would carry testing guidance and a test runner nobody uses,
+and an agent that finds them will reasonably suggest writing tests.
 
 ### No workflows
 
-Seven of the ten `workflows` skills are for code:
-feature development, refactoring, test audits, website work and so on.
+Every `workflows` skill is for code:
+feature development, refactoring, test audits and architecture audits.
 An agent asked to "set up the network" could reasonably pick one of them up
 and start a feature branch for something that has no code in it.
-The three that suit any project — issue sweeps, knowledge backfill and stray disposition —
-can join this profile once `workflows` is split (tracked in `boop-4n87`).
+The workflows that suit any project that tracks its work in beads —
+issue sweeps, stray disposition and knowledge backfill —
+ship in `project-mgmt` and `product-design` instead,
+so this profile receives them without `workflows`.
 
 ### No coding
 

package/profiles/development/profile.md

@@ -4,6 +4,7 @@ description: Development skills only — for a project with no application domai
 defaultCapabilities:
   # Development
   - coding
+  - typescript
   - testing
   - project-mgmt
   - product-design
@@ -31,16 +32,17 @@ but they are all developed the same way.
 
 ## What You Get
 
-Six capabilities, all of them `type: development` —
-pure skill bundles that guide agent behaviour,
-plus the handful of dev dependencies those skills assume:
+Seven capabilities, all of them `type: development` —
+skill bundles that guide agent behaviour,
+plus the TypeScript toolchain those skills assume:
 
 - **coding** — development conventions, code style, commit and debugging skills
-- **testing** — Jest setup, test utilities, the TDD-Lite workflow
-- **project-mgmt** — beads issue tracking and planning skills
-- **product-design** — feature requirements, engineering design, documentation skills
+- **typescript** — the TypeScript toolchain: Jest with ts-jest, `tsconfig.test.json`, and the `test` and `typecheck` scripts
+- **testing** — the testing principles and the TDD-Lite workflow
+- **project-mgmt** — beads issue tracking, planning, issue sweeps and stray disposition
+- **product-design** — feature requirements, engineering design, documentation and knowledge backfill skills
 - **skills** — skill authoring, discovery and maintenance
-- **workflows** — the end-to-end development and writing workflows
+- **workflows** — the end-to-end code development and audit workflows
 
 No web layer, no API layer, no service layer, no database.
 Add any of those with `boop add` if the project grows an application domain.
@@ -72,7 +74,7 @@ and the consequence is deliberate: `boop init --profile development` is refused
 with a message pointing at the two ways this profile is actually meant to be used —
 name it in an existing project's `.boop/config.json`,
 or `boop add` these capabilities one at a time.
-The capabilities carry their own dependencies (`jest`, `ts-jest`, `beads`),
+The capabilities carry their own dependencies (`typescript` brings `jest` and `ts-jest`, and `project-mgmt` brings `beads`),
 so nothing is lost by having no kernel to merge them from.
 
 ### No reference/