@boopkit/cli 0.8.0 → 0.8.2

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

@@ -68,6 +68,8 @@ If `--prefix` is also provided, it is passed to the planning session as a naming
 | `--no-skip-perms` | off | Don't skip Claude permission prompts |
 | `--json` | off | Output summary as JSON |
 
+Every Claude session the loop spawns, planning and issue sessions alike, runs with `CLAUDE_CODE_ENTRYPOINT=boop-loop`, which marks its transcript as machine-driven, and `CLAUDE_CODE_DISABLE_AUTO_MEMORY=1`, which keeps the operator's auto-memory out of it.
+
 ## Worktree Isolation (default)
 
 By default, `boop loop` runs **inside its own git worktree** so that N loops can run concurrently without colliding. On start (with `--run`) the loop:
@@ -115,14 +117,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,20 @@ 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-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-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-docs-sweep-workflow** — When `specs/` has piled up with documents nobody has looked at in months and you need to know which are finished, which have gone stale, and which are the only surviving record of real work, follow this process: measure the set rather than read it, classify each document against what the issue tracker says (the close reason, not the status), pass the gate before archiving anything, and make the mechanical fixes while surfacing the judgement calls. The document-set sibling of issue-sweep. Not for folding one shipped feature into `reference/`.
+- **boop-product-design-reference-restructure-workflow** — When `reference/` has grown by accretion and subjects a reader would look up have no page of their own (they live as sections inside pages about something else, or in pieces across several pages), follow this process: measure the whole set rather than read it, write down the candidate subjects, then promote each one in a worktree, one commit per subject, for the operator to review as a diff. The whole-set counterpart of reference-integration, which promotes a buried subject one change at a time.
+- **boop-product-design-thought-partnership** — When the user wants to think out loud through a design — a feature, a capability, a strategic direction — or to drive a set of features forward with you interactively, through design, code, review and adjustment, be a thought partner, not an implementer: hold the conversation at user-and-value altitude, honor uncertainty with hypotheses rather than pretend-decisions, record each ruling where the next reader will find it, 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 +45,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, loudness, anatomy, scan-line, whitespace, density, voice. Pairs with ux-purpose-judgement (the question of whether each element belongs at all) and, when the project has the web capability, with boop-web-css (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-feature-dev-workflow** — When you are tasked with building a feature end-to-end, follow this beads-issue-per-step workflow: epic root → understand → plan → decompose → implement → review → punch-list → closeout → reconcile-and-finalize.
 - **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 +104,11 @@ 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-css** — When you need to write or change CSS — adding or renaming a class, writing a selector or a stylesheet rule, or editing a class attribute in a template — name classes for what their elements are for, nest each block's children and variants inside it, and never use BEM's __element or --modifier separators.
+- **boop-web-testing** — When you need to write or run tests for the Express server — services, controllers, middleware, and HTTP routes — or to confirm in a browser that a change to something a person looks at does what its issue said, since a green suite proves behaviour but not what renders.
+- **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.
+- **boop-web-design-handoff-bundle** — When the operator points at a design canvas (an artifact of artboards) and asks for it to be bundled, turned into a handoff, or made ready for the coding agent, turn it into a design handoff bundle under specs/design-handoffs/: a README, drop-in templates and CSS in the project's conventions, the decisions, and an eval checklist. The producing side of boop-web-design-handoff-workflow; the system wins over the prototype, and every departure is written down.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boopkit/cli",
-  "version": "0.8.0",
+  "version": "0.8.2",
   "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/

package/profiles/web-app/profile.md

@@ -9,6 +9,7 @@ defaultCapabilities:
   - database
   # Development
   - coding
+  - typescript
   - testing
   - project-mgmt
   - product-design
@@ -86,11 +87,12 @@ The `web-app` profile ships all of the following capabilities by default:
 - **services** — Service layer scaffolding, auto-discovery, and design skills
 - **database** — PostgreSQL with Prisma ORM, migrations, and seeding
 
-**Development capabilities** — pure skill bundles that guide agent behavior:
+**Development capabilities** — skill bundles that guide agent behavior, and the toolchain they assume:
 - **coding** — Development conventions and code style skills
-- **testing** — Jest setup, test utilities, TDD workflow skills
-- **project-mgmt** — Beads issue tracking, planning skills
-- **product-design** — Feature requirements, design thinking skills
+- **typescript** — The TypeScript toolchain: Jest with ts-jest, `tsconfig.test.json`, and the `test` and `typecheck` scripts
+- **testing** — Testing principles and the TDD-Lite workflow skills
+- **project-mgmt** — Beads issue tracking, planning, issue sweeps and stray disposition
+- **product-design** — Feature requirements, design thinking and knowledge backfill skills
 - **skills** — Skill authoring and maintenance
 
 **Demo:**

package/profiles/web-app/reference/message-queue-patterns.ref.md

@@ -26,28 +26,23 @@ await MessageQueueService.publish('batch-ready', [message1, message2]);
 - **Error recovery**: If `publish()` catches an error (e.g., channel closed), it resets connection state and returns `false` — the next call will reconnect
 - **Shutdown**: The publish connection is tracked and closed by `close()` alongside the listener connection
 
-### Publishing to a queue that does not exist
+### Publishing to a queue that does not exist yet
 
-`publish()` does not declare the queue; only `listen()` does.
-A broker confirms a message that it cannot put in any queue and then discards it,
-so a publish to a name that no consumer has ever listened on returns `true` and the message is lost.
+`publish()` declares the queue's topology (main, `.retry` and `.failed` queues and their exchanges) before its first publish to it on a connection, exactly as `listen()` does,
+so a message published before the consumer has ever run is kept until the consumer attaches.
 
-Pass `{ mandatory: true }` as the third argument when the publisher cannot be sure the queue exists:
-when the name is composed at run time (for example with `targetPrefix`),
-or when the publisher can start before the consumer ever has.
+- Each queue is declared once per publish connection; concurrent first publishes share the declaration, and a queue a consumer in the same process already declared with the same arguments is not declared again
+- The declaration runs on a short-lived channel, so a refused one (`PRECONDITION_FAILED`, when the arguments differ from the existing queue's) fails that publish alone: it is logged with the queue's name and `publish()` returns `false`
+- Pass the consumer's `queueArguments` in the third argument whenever the consumer declares any:
 
 ```typescript
-const queued = await MessageQueueService.publish('batch-ready', message, { targetPrefix, mandatory: true });
+const queued = await MessageQueueService.publish('batch-ready', message, { targetPrefix, queueArguments: BATCH_QUEUE_ARGUMENTS });
 if (!queued) {
   // Not queued anywhere: record or report it.
 }
 ```
 
-- The message is sent with the AMQP `mandatory` flag, and the broker returns it when no queue has the destination's name
-- `publish()` then logs `publish to "<queue>" was returned by the broker: no queue has that name` and returns `false`
-- The connection state is **not** reset in this case — the connection is healthy, and the next `publish()` reuses it
-- A queue that exists but has no consumer running still takes the message; the option reports a missing queue, not a missing worker
-- Without the option, `publish()` is unchanged
+- `{ mandatory: true }` still makes the broker return a message no queue took; after the declaration that means a real fault, such as a queue deleted by hand, and `publish()` returns `false` without resetting the connection
 
 ### Why persistent (not per-call)
 

package/src/templates/kernel/tests/app.test.ts.hbs

@@ -0,0 +1,17 @@
+import app from '../src/app';
+
+describe('app', () => {
+  it('exports a valid Express application', () => {
+    expect(app).toBeDefined();
+    expect(typeof app.get).toBe('function');
+    expect(typeof app.post).toBe('function');
+    expect(typeof app.use).toBe('function');
+  });
+
+  it('has JSON and URL-encoded body parsing enabled', () => {
+    const stack = (app as any).router?.stack ?? (app as any)._router?.stack ?? [];
+    const layerNames = stack.map((layer: any) => layer.name);
+    expect(layerNames).toContain('jsonParser');
+    expect(layerNames).toContain('urlencodedParser');
+  });
+});