@boopkit/cli 0.6.12 → 0.6.14

package/dist/lib/update.js

@@ -39,9 +39,11 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.SKILL_EDITS_INSTRUCTION = exports.TRIAGE_SKILL = void 0;
 exports.compareFileHash = compareFileHash;
 exports.planCapabilityUpdate = planCapabilityUpdate;
 exports.executeUpdatePlan = executeUpdatePlan;
+exports.countSkillEdits = countSkillEdits;
 exports.formatUpdateSummary = formatUpdateSummary;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
@@ -50,6 +52,10 @@ const capability_1 = require("./capability");
 const project_1 = require("./project");
 const safe_io_1 = require("./safe-io");
 const install_layout_1 = require("./install-layout");
+/** The skill that splits a drifted SKILL.md — keep in step with the folder name boop-rm2l.8 gives it */
+exports.TRIAGE_SKILL = 'boop-skills-edit-triage';
+/** What to do about skills edited in SKILL.md, for a report that counts them */
+exports.SKILL_EDITS_INSTRUCTION = `Move each skill's edits into the PROJECT.md beside it: run \`boop migrate-skill-edits\` and follow the ${exports.TRIAGE_SKILL} skill.`;
 /**
  * Compare a file's current hash against a stored hash.
  */
@@ -96,9 +102,22 @@ function planCapabilityUpdate(targetDir, capabilityName, projectManifest) {
         const destPath = path.join(targetDir, relPath);
         const storedHash = storedHashes[relPath];
         const newHash = (0, scaffold_1.hashFile)(srcPath);
+        const fileKind = fileKindOf(relPath);
         if (!storedHash) {
             // New file — not in stored hashes
-            if (fs.existsSync(destPath)) {
+            if (fs.existsSync(destPath) && (0, scaffold_1.hashFile)(destPath) === newHash) {
+                // Untracked but already holds what boop ships, as a hand-split skill does — start tracking it
+                actions.push({
+                    relativePath: relPath,
+                    action: 'record-hash',
+                    reason: 'Locally matches package',
+                    currentHash: newHash,
+                    newHash,
+                    drift: 'already-upstream',
+                    fileKind,
+                });
+            }
+            else if (fs.existsSync(destPath)) {
                 // File exists but wasn't tracked — treat as modified (skip)
                 actions.push({
                     relativePath: relPath,
@@ -106,6 +125,8 @@ function planCapabilityUpdate(targetDir, capabilityName, projectManifest) {
                     reason: 'File exists but has no stored hash (untracked)',
                     currentHash: (0, scaffold_1.hashFile)(destPath),
                     newHash,
+                    fileKind,
+                    ...skipInstruction(targetDir, relPath, srcPath, fileKind),
                 });
             }
             else {
@@ -114,6 +135,7 @@ function planCapabilityUpdate(targetDir, capabilityName, projectManifest) {
                     action: 'add',
                     reason: 'New file from package',
                     newHash,
+                    fileKind,
                 });
             }
             continue;
@@ -134,19 +156,40 @@ function planCapabilityUpdate(targetDir, capabilityName, projectManifest) {
                     storedHash,
                     currentHash: storedHash,
                     newHash,
+                    fileKind,
+                    instruction: fileKind === 'skill' ? offeredRulesInstruction(targetDir, relPath) : undefined,
                 });
                 break;
-            case 'modified':
-                // Locally modified — skip with warning
+            case 'modified': {
+                const currentHash = (0, scaffold_1.hashFile)(destPath);
+                if (currentHash === newHash) {
+                    // Already holds what boop ships — move the base forward, or it reads as modified forever
+                    actions.push({
+                        relativePath: relPath,
+                        action: 'record-hash',
+                        reason: 'Locally matches package',
+                        storedHash,
+                        currentHash,
+                        newHash,
+                        drift: 'already-upstream',
+                        fileKind,
+                    });
+                    break;
+                }
+                const drift = newHash === storedHash ? 'project-only' : 'both-changed';
                 actions.push({
                     relativePath: relPath,
                     action: 'skip',
                     reason: 'Locally modified',
                     storedHash,
-                    currentHash: (0, scaffold_1.hashFile)(destPath),
+                    currentHash,
                     newHash,
+                    drift,
+                    fileKind,
+                    ...skipInstruction(targetDir, relPath, srcPath, fileKind, drift),
                 });
                 break;
+            }
             case 'missing':
                 // File was deleted locally — respect user's deletion, skip by default
                 actions.push({
@@ -155,6 +198,7 @@ function planCapabilityUpdate(targetDir, capabilityName, projectManifest) {
                     reason: 'Locally deleted',
                     storedHash,
                     newHash,
+                    fileKind,
                 });
                 break;
         }
@@ -185,18 +229,25 @@ function planCapabilityUpdate(targetDir, capabilityName, projectManifest) {
                 const oldFilePath = path.join(targetDir, oldRelPath);
                 const oldState = compareFileHash(oldFilePath, oldStoredHash);
                 if (oldState === 'modified') {
-                    // User modified the old file — skip new folder files, keep old file
+                    // User modified the old file — keep it, and don't install the folder that replaces it.
+                    // A folder file already installed has its own comparison, so only an install is held back.
                     for (const action of actions) {
-                        if (action.relativePath.startsWith(newPrefix) || action.relativePath === path.join('skills', newSkillName)) {
+                        if (action.action === 'add' && (action.relativePath.startsWith(newPrefix) || action.relativePath === path.join('skills', newSkillName))) {
                             action.action = 'skip';
                             action.reason = `Skipped: old skill file '${oldRelPath}' was locally modified`;
+                            action.oldPath = oldRelPath;
+                            action.instruction = `boop installs this once ${oldRelPath} is gone; see what to do about that file.`;
                         }
                     }
                     // Change deprecate to skip for the old file
                     const oldAction = actions.find(a => a.relativePath === oldRelPath);
                     if (oldAction) {
+                        const projectFile = path.join('skills', newSkillName, 'PROJECT.md');
                         oldAction.action = 'skip';
                         oldAction.reason = 'Locally modified (migration skipped)';
+                        oldAction.replacedBy = newSkillName;
+                        oldAction.instruction = `This is the old single-file form of the ${newSkillName} skill, and this project edited it. ` +
+                            `Move the rules this project needs from it into ${projectFile}, following the ${exports.TRIAGE_SKILL} skill, then delete it and run \`boop update\`.`;
                     }
                 }
                 else if (oldState === 'match') {
@@ -245,6 +296,7 @@ function executeUpdatePlan(plan, options = {}) {
         pruned: [],
         migrated: [],
         unchangedCount: plan.unchangedCount,
+        instructions: [],
     };
     const pkgJson = JSON.parse(fs.readFileSync(path.join(plan.packageDir, 'package.json'), 'utf-8'));
     const boopkit = pkgJson.boopkit;
@@ -264,9 +316,16 @@ function executeUpdatePlan(plan, options = {}) {
                     fs.copyFileSync(srcPath, destPath);
                     newHashes[action.relativePath] = (0, scaffold_1.hashFile)(destPath);
                     result.overwritten.push(action.relativePath);
+                    if (action.instruction) {
+                        result.instructions.push({ relativePath: action.relativePath, instruction: action.instruction });
+                    }
                 }
                 break;
             }
+            case 'record-hash':
+                newHashes[action.relativePath] = action.newHash;
+                result.unchangedCount++;
+                break;
             case 'skip': {
                 const isLocallyDeleted = action.reason === 'Locally deleted';
                 if (isLocallyDeleted && options.restore) {
@@ -291,6 +350,10 @@ function executeUpdatePlan(plan, options = {}) {
                         newHashes[action.relativePath] = (0, scaffold_1.hashFile)(destPath);
                         result.overwritten.push(action.relativePath);
                         result.forcedOverwrite.push(action.relativePath);
+                        const instruction = action.fileKind === 'skill' ? offeredRulesInstruction(plan.targetDir, action.relativePath) : undefined;
+                        if (instruction) {
+                            result.instructions.push({ relativePath: action.relativePath, instruction });
+                        }
                         console.warn(`\x1b[33mWARN\x1b[0m Force-overwriting modified file: ${action.relativePath} (backup saved as ${action.relativePath}.bak)`);
                     }
                 }
@@ -299,6 +362,13 @@ function executeUpdatePlan(plan, options = {}) {
                     if (isLocallyDeleted) {
                         result.skippedDeleted.push(action.relativePath);
                     }
+                    if (action.instruction) {
+                        result.instructions.push({
+                            relativePath: action.relativePath,
+                            instruction: action.instruction,
+                            upstreamPath: action.upstreamPath,
+                        });
+                    }
                     // Keep existing hash unchanged
                 }
                 break;
@@ -355,6 +425,79 @@ function executeUpdatePlan(plan, options = {}) {
     }
     return result;
 }
+/**
+ * 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.
+ *
+ * An edited SKILL.md always gets an instruction: any edit there is project
+ * content in boop's file. An edited reference page or code file is doing what
+ * those files are for, so it gets one only when boop has changed it too.
+ */
+function skipInstruction(targetDir, relPath, srcPath, fileKind, drift) {
+    const upstreamPath = displayPath(targetDir, srcPath);
+    if (!drift) {
+        const untracked = `boop has no record of installing this file, so it cannot tell this project's changes from its own. boop's current copy is at ${upstreamPath}`;
+        if (fileKind === 'skill') {
+            const projectFile = path.join(path.dirname(relPath), 'PROJECT.md');
+            return {
+                instruction: `${untracked}. Split it by hand: move this project's rules into ${projectFile}, following the ${exports.TRIAGE_SKILL} skill, then copy boop's copy into place, and the next update tracks it.`,
+                upstreamPath,
+            };
+        }
+        return { instruction: `${untracked}; compare the two by hand.`, upstreamPath };
+    }
+    if (fileKind === 'skill') {
+        const projectFile = path.join(path.dirname(relPath), 'PROJECT.md');
+        return {
+            instruction: `Move this project's edits into ${projectFile}: run \`boop migrate-skill-edits\` and follow the ${exports.TRIAGE_SKILL} skill.`,
+        };
+    }
+    if (drift !== 'both-changed')
+        return {};
+    const advice = fileKind === 'reference'
+        ? 'Blend in what applies to this project, following the boop-product-design-reference-integration skill.'
+        : 'Compare the two and take what applies.';
+    return { instruction: `boop's current copy is at ${upstreamPath}. ${advice}`, upstreamPath };
+}
+/**
+ * When an update replaces a SKILL.md whose PROJECT.md offers rules to boop,
+ * boop's new text may now cover them, and a rule left behind would duplicate it.
+ */
+function offeredRulesInstruction(targetDir, relPath) {
+    const projectFile = path.join(path.dirname(relPath), 'PROJECT.md');
+    if (!(0, scaffold_1.hasOfferedRules)(path.join(targetDir, projectFile)))
+        return undefined;
+    return `boop replaced this skill, and ${projectFile} offers rules to boop. Check whether boop's new text covers each rule under "Offered to boop", and delete any it does.`;
+}
+/** A path relative to the project when it lies inside it, as a package in node_modules does */
+function displayPath(targetDir, filePath) {
+    const relative = path.relative(targetDir, filePath);
+    return relative.startsWith('..') || path.isAbsolute(relative) ? filePath : relative;
+}
+/**
+ * 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`
+ * makes. Null when there are none, or the capability has no package to compare with.
+ */
+function countSkillEdits(targetDir, capabilityName, projectManifest) {
+    const plan = planCapabilityUpdate(targetDir, capabilityName, projectManifest);
+    const edited = (plan?.actions ?? []).filter(a => a.action === 'skip' && a.fileKind === 'skill' && (a.drift === 'project-only' || a.drift === 'both-changed'));
+    if (edited.length === 0)
+        return null;
+    return { edited: edited.length, changesWaiting: edited.filter(a => a.drift === 'both-changed').length };
+}
+/**
+ * Classify a project-relative destination path: a skill's SKILL.md, a
+ * reference page, or anything else (code, views, config).
+ */
+function fileKindOf(relativePath) {
+    const segments = relativePath.split(path.sep);
+    if (segments.length === 3 && segments[0] === 'skills' && segments[2] === 'SKILL.md')
+        return 'skill';
+    if (relativePath.endsWith('.ref.md'))
+        return 'reference';
+    return 'code';
+}
 /**
  * Resolve the source path a project-relative file was installed from — the
  * placement list read backwards, so it cannot disagree with what was copied.

package/docs/init.md

@@ -1,6 +1,8 @@
 # boop init
 
-`boop init` is the command you run when you want a real starting point quickly. It creates a new project directory, applies a boop profile, writes a `.boop.json` manifest, and, unless you opt out, installs npm dependencies. The goal is simple: get you to a local project you can run, extend, and keep clean as both humans and agents start contributing.
+`boop init` is the command you run when you want a real starting point quickly.
+It creates a new project directory, applies a boop profile, writes a `.boop/config.json` manifest, and, unless you opt out, installs npm dependencies and sets up the project's beads issue tracker.
+The goal is simple: get you to a local project you can work in, extend, and keep clean as both humans and agents start contributing.
 
 ## Synopsis
 
@@ -10,9 +12,15 @@ boop init <name> --profile <profile>
 
 If you omit `--profile`, Boop uses `web-app`.
 
+`<name>` can be a plain name or a path such as `~/work/aws-setup`.
+Either way, the project is named after its folder, `aws-setup` in that example:
+that is the name in `package.json`, `.boop/config.json` and the README heading, and the beads issue prefix.
+
 ## Before You Run It
 
-The current `web-app` profile requires Node 24 or newer. If your Node version is too old, `boop init` exits before creating the directory and prints an upgrade hint.
+The `web-app` profile requires Node 24 or newer.
+If your Node version is too old, `boop init` exits before creating the directory and prints an upgrade hint.
+The `base` profile names no runtime, so it has no version to check.
 
 ## Available Profiles
 
@@ -27,110 +35,154 @@ Current output:
 ```text
 Available profiles:
 
+  base
+    Planning, writing and issue tracking for a project that isn't an application
+    capabilities:
+      Development: project-mgmt, product-design, skills
+
+  development
+    Development skills only — for a project with no application domain (a CLI, a library, a data pipeline)
+    capabilities:
+      Development: coding, testing, project-mgmt, product-design, skills, workflows
+
   web-app
-    Full-stack web application (Express + Handlebars + Tailwind + Postgres)
-    capabilities: web, api, database
+    Full-stack web application (Express + Handlebars + Tailwind)
     runtime: node | deploy: heroku | port: 3000
+    capabilities:
+      Application: web, api, services, database
+      Development: coding, testing, project-mgmt, product-design, skills, workflows
+      Demo: hello
 ```
 
-`web-app` is the only profile `boop init` can scaffold from.
-The other built-in profile, `development`, carries development capabilities and no application domain,
-so it has no runtime, port or deploy target to scaffold with —
-`boop init --profile development` is refused with a pointer to the two ways it is meant to be used:
+`boop init` can scaffold from two of these.
+`web-app` carries a kernel, the configuration for a running application, and renders an Express server from it.
+`base` has no kernel, but it ships templates of its own,
+so it renders a project for planning, writing and tracking work instead:
+agent instructions, a README in each of `specs/`, `reference/` and `docs/`,
+and the planning and writing skills, with no application code at all.
+
+The third profile, `development`, carries development capabilities and no application domain.
+It has neither a kernel nor templates, so there is nothing for `boop init` to write,
+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.
 
 ## What It Creates
 
-Running `boop init my-saas --profile web-app --no-install` creates a project like this:
+Running `boop init my-saas --profile web-app --no-install --no-beads` creates a project like this, shown to two levels:
 
 ```text
 my-saas/
-  .boop.json
+  .boop/
+    config.json
+  .env
+  .env.example
+  .github/
+    copilot-instructions.md
   .gitignore
+  AGENTS.md
+  CLAUDE.md
   Procfile
   README.md
+  jest.config.js
   package.json
+  prisma/
+    schema/
+  public/
+    css/
+    favicon.svg
   reference/
-    architecture.ref.md
-    message-queue-patterns.ref.md
+    (architecture, database, REST API, service layer and web UI pages, among others)
   skills/
-    boop-api-rest-api-design/
-      SKILL.md
-    boop-coding-beads-flow/
-      SKILL.md
-    boop-coding-commit-changes/
-      SKILL.md
-    boop-coding-development/
-      SKILL.md
-    boop-coding-review-changes/
-      SKILL.md
-    boop-database-data-model/
-      SKILL.md
-    boop-database-prisma/
-      SKILL.md
-    boop-product-design-engineering-design/
-      SKILL.md
-    boop-product-design-feature-documentation/
-      SKILL.md
-    boop-product-design-feature-requirements/
-      SKILL.md
-    boop-product-design-reference-integration/
-      SKILL.md
-    boop-project-mgmt-beads-planning/
-      SKILL.md
-    boop-project-mgmt-engineering-planning/
-      SKILL.md
-    boop-services-controllers/
-      SKILL.md
-    boop-services-services/
-      SKILL.md
-    boop-skill-authoring/
-      SKILL.md
-    boop-testing-tdd-light/
-      SKILL.md
-    boop-testing-testing/
-      SKILL.md
-    boop-testing-testing-express-web/
-      SKILL.md
-    boop-web-web-ui-design/
-      SKILL.md
+    (40 skill folders from the installed capabilities)
+  specs/
+    README.md
   src/
+    app.ts
+    controllers/
+    db.ts
     lib/
-      .gitkeep
+    middleware/
+    routes/
+    scripts/
     server.ts
+    services/
+  styles/
+  tailwind.config.ts
+  tests/
   tsconfig.json
+  tsconfig.test.json
+  views/
 ```
 
 That scaffold breaks down into a few parts:
 
-- Kernel files: `.gitignore`, `Procfile`, `README.md`, `package.json`, `tsconfig.json`, `src/server.ts`, and `src/lib/.gitkeep`
+- Kernel files, rendered from boop's kernel templates: `.github/copilot-instructions.md`, `.gitignore`, `AGENTS.md`, `CLAUDE.md`, `Procfile`, `README.md`, `package.json`, `tsconfig.json`, `src/app.ts`, `src/server.ts`, `src/lib/.gitkeep`, `specs/README.md` and `reference/boop-guide.ref.md`
 - Profile reference docs: copied into `reference/`
-- Profile and capability skills: copied into `skills/`
-- Project manifest: `.boop.json` records the project name, profile, boop version, installed capabilities, and creation timestamp
-- Capability install effects: default capability dependencies and scripts are merged into `package.json`, and the installed capability names are recorded in `.boop.json`
+- Capability files: each capability's skills are copied into `skills/`, and its scaffold files (`src/`, `views/`, `styles/`, `prisma/`, `tests/` and so on) into the project
+- Project manifest: `.boop/config.json` records the project name, profile, boop version, installed capabilities, the hashes of the files each capability wrote, and the creation timestamp
+- Capability install effects: default capability dependencies and scripts are merged into `package.json`, and any environment variables a capability needs are written to `.env` and `.env.example`
 
 For the `web-app` profile, the default capabilities are:
 
-- `web`
-- `api`
-- `database`
-
-At the moment, those capabilities show up most clearly in `package.json`, `skills/`, and `.boop.json`. The initial source tree is still small: the kernel server entry point plus the copied reference and skill material.
+- Application: `web`, `api`, `services`, `database`
+- Development: `coding`, `testing`, `project-mgmt`, `product-design`, `skills`, `workflows`
+- Demo: `hello`
 
 Beyond the defaults, optional capabilities are available to add later with `boop add <capability>`. For example, `users-and-accounts` adds user management and authentication, and `noticeboard` provides a fuller service-layer reference demo. See the profile documentation for the complete list.
 
+The `base` profile makes a much smaller project.
+Running `boop init notes --profile base --no-install --no-beads` creates this:
+
+```text
+notes/
+  .boop/
+    config.json
+  .github/
+    copilot-instructions.md
+  .gitignore
+  AGENTS.md
+  CLAUDE.md
+  README.md
+  docs/
+    README.md
+  package.json
+  reference/
+    README.md
+  skills/
+    (16 skill folders from project-mgmt, product-design and skills)
+  specs/
+    README.md
+```
+
+There is no `src/`, no test setup and no server to start.
+The `package.json` holds only the capability packages, the `bd` dependency and two `bd:` scripts;
+it is there because it is how boop records the capabilities and refreshes their skills with `boop update`.
+Without `--no-beads`, the project also has a `.beads/` folder and a git repository with two commits, as described under `--no-beads` below.
+
 ## Options
 
 - `--profile <profile>`: choose which profile to initialize. Defaults to `web-app`.
 - `--no-install`: skip `npm install`. This is useful if you want to inspect or adjust the scaffold before installing dependencies.
+- `--no-beads`: skip the beads setup.
+  By default, when the profile installs `project-mgmt` (as `web-app` and `base` both do), Boop's last step is `bd init --non-interactive --server -p <name>`,
+  where the issue prefix is the project folder's name even when you pass a path such as `~/work/aws-setup`.
+  That creates the project's beads issue database in Dolt server mode and starts its Dolt server,
+  so `bd create` works straight away and `boop loop` can run in the project without first migrating it to server mode.
+  Pass `--no-beads` for a throwaway scaffold or a CI run; the command is printed under "Next steps" so you can run it later.
+  If `bd` is not installed, or `bd init` fails, init still succeeds and prints the same command.
+
+  Just before `bd init`, Boop creates a git repository in the new project and commits the scaffold, so the project starts with two commits (the scaffold, then beads) and a clean `git status`.
+  With `--no-beads`, Boop leaves git alone.
+  If git has no `user.name` and `user.email` configured, Boop skips its commit and tells you; it never sets an identity for you.
+  If the new project is inside another git repository, Boop skips both the commit and `bd init` and tells you why, because `bd init` would commit into that repository and redirect its git hooks.
 
 If you do not pass `--no-install`, Boop runs `npm install` after scaffolding and then prints the same next-step summary.
 
-## Example: Initialize Without Installing
+## Example: Initialize Without Installing or Setting Up Beads
 
 ```bash
-boop init my-saas --profile web-app --no-install
+boop init my-saas --profile web-app --no-install --no-beads
 ```
 
 Expected output:
@@ -138,43 +190,37 @@ Expected output:
 ```text
 Created project "my-saas" with profile "web-app"
 
-Kernel files:
-  .gitignore
-  Procfile
-  README.md
-  package.json
-  src/lib/.gitkeep
-  src/server.ts
-  tsconfig.json
-
-Capabilities: web, api, database
-
-Scripts added:
-  tailwind:build: npx @tailwindcss/cli -i src/public/css/input.css -o src/public/css/style.css --minify
-  tailwind:watch: npx @tailwindcss/cli -i src/public/css/input.css -o src/public/css/style.css --watch
-  db:migrate: prisma migrate dev --schema=prisma/schema/
-  db:deploy: prisma migrate deploy --schema=prisma/schema/
-  db:seed: prisma db seed --schema=prisma/schema/
-  db:generate: prisma generate --schema=prisma/schema/
-  db:studio: prisma studio --schema=prisma/schema/
+  13 kernel files · 11 capabilities · 68 capability files · 13 scripts
+    Application: web, api, services, database
+    Development: coding, testing, project-mgmt, product-design, skills, workflows
+    Demo: hello
 
 Next steps:
   cd my-saas
   npm install
-  npm run dev
+  bd init --non-interactive --server -p my-saas
+  boop status          ← check what needs configuration
+  npm run dev          ← start development server
 ```
 
+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.
+
 ## What To Do After Init
 
-If you used `--no-install`, run:
+Run the commands under "Next steps".
+If you used `--no-install` and `--no-beads`, that is:
 
 ```bash
 cd my-saas
 npm install
+bd init --non-interactive --server -p my-saas
+boop status
 npm run dev
 ```
 
-If you let Boop install dependencies for you, the shorter version is:
+If you let Boop install dependencies and set up beads for you, the shorter version is:
 
 ```bash
 cd my-saas

package/docs/loop.md

@@ -122,6 +122,21 @@ Session logs are written to `labs/claude-runs/` in the project directory. Each i
 - **Budget caps** — each issue is capped at `--budget` USD
 - **Resume limits** — prevents infinite retry loops (default: 3 attempts)
 - **Permission skipping** — enabled by default for unattended operation; use `--no-skip-perms` to require approval for each tool call
+- **A failed queue read is never a clean finish** — if the loop cannot read the ready queue it says so and stops with exit code 1, rather than reporting "No more ready issues" and exiting 0. See [Reading the ready queue](#reading-the-ready-queue).
+
+## Reading the ready queue
+
+The loop reads claimable work with `bd ready --json -n 0`, projected through `jq` to the only three fields its filters use: `id`, `issue_type` and `parent`.
+
+The projection matters because `bd ready --json` returns every ready issue *with its full description*. In a repo with 112 ready issues that is 274,529 bytes, roughly 70% of it description the loop never looks at; projected, the same read is 5,941 bytes. Node captures at most 1 MiB from a subprocess by default and fails past it, so an unprojected read on a mature backlog dies — and a dead read used to be indistinguishable from an empty queue, which is how a loop could stop early with work still ready.
+
+**`jq` is recommended but not required.** It ships with neither stock macOS nor stock Debian, so when it is missing the loop warns once and falls back to the unprojected read. That stays safe because every `bd` read is capped at 256 MiB rather than the 1 MiB default. Install `jq` to keep the read small:
+
+```bash
+brew install jq
+```
+
+If the ready queue cannot be read at all, the loop says which command failed and stops with exit code 1 rather than reporting a clean finish. Under `--poll` it logs the failure and retries on the next interval.
 
 ## Planning Mode
 
@@ -167,6 +182,7 @@ The prefix is included in the planning prompt as a suggestion for naming the fea
 - **Flags used separately** — `--work` without `--flow` (or vice versa) prints an error. They must be used together.
 - **Feature ID not found** — If the planning session doesn't output `FEATURE_ID=<id>` and the fallback query finds no matching recent feature, the command exits with an error and points to the session log for debugging.
 - **Planning session limit hit** — If the Claude session hits a usage limit, the command exits without proceeding to the loop phase.
+- **Ready-queue read failure** — If `bd ready` cannot be read, the loop reports the failing command and stops with exit code 1; it never reports a clean finish on a read it could not make.
 
 Planning session logs are written to `labs/claude-runs/` with the prefix `_planning_`.
 

package/docs/skills.md

@@ -38,6 +38,7 @@ Every capability ships **agent skills** — focused `SKILL.md` guides that `boop
 - **boop-get-smart** — When there is a recurring fault in your own behaviour during a chat, run the five whys to find its root cause, and agree a change with the operator that makes it less likely.
 - **boop-so-what** — When the operator asks for the so-what, or says some version of 'thanks for the essay', compress what you just produced into three sentences about what they should care about.
 - **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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boopkit/cli",
-  "version": "0.6.12",
+  "version": "0.6.14",
   "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": [
@@ -21,7 +21,8 @@
     "access": "public"
   },
   "scripts": {
-    "build": "tsc && node tools/generate-version-manifest.js",
+    "build": "npm run build:caps && tsc && node tools/generate-version-manifest.js",
+    "build:cli": "tsc && node tools/generate-version-manifest.js",
     "typecheck": "tsc -p tsconfig.test.json",
     "skills:index": "node tools/generate-skills-index.js",
     "skills:layout": "tsx tools/generate-installed-layout.ts",