@boopkit/cli 0.1.0 → 0.1.2

package/dist/commands/init.js

@@ -85,11 +85,19 @@ function runInit(name, options) {
         }
     }
     // --- Pre-flight: detect script conflicts before writing anything ---
+    // When running from npm (not the monorepo), capabilities can't be resolved
+    // until after npm install. Defer conflict check to after install in that case.
     const capabilityNames = profile.defaultCapabilities;
     const preflightScripts = {};
+    let preflight = true;
     for (const capName of capabilityNames) {
         const cap = (0, capability_1.getCapability)(capName);
-        if (!cap?.scripts)
+        if (!cap) {
+            // Can't resolve capabilities yet — will install first, then check
+            preflight = false;
+            break;
+        }
+        if (!cap.scripts)
             continue;
         for (const scriptName of Object.keys(cap.scripts)) {
             if (scriptName in preflightScripts) {
@@ -102,15 +110,19 @@ function runInit(name, options) {
     }
     // --- Create directory ---
     fs.mkdirSync(targetDir, { recursive: true });
-    // --- Collect hooks from capabilities ---
-    const hookEntries = [];
-    for (const capName of capabilityNames) {
-        const cap = (0, capability_1.getCapability)(capName);
-        if (cap?.hooks) {
-            hookEntries.push({ name: capName, hooks: cap.hooks });
+    // --- Collect hooks from capabilities (deferred if not resolvable yet) ---
+    let hookVars = (0, scaffold_1.collectHooks)([]);
+    const canResolveLocally = capabilityNames.every(n => (0, capability_1.getCapability)(n) !== null);
+    if (canResolveLocally) {
+        const hookEntries = [];
+        for (const capName of capabilityNames) {
+            const cap = (0, capability_1.getCapability)(capName);
+            if (cap?.hooks) {
+                hookEntries.push({ name: capName, hooks: cap.hooks });
+            }
         }
+        hookVars = (0, scaffold_1.collectHooks)(hookEntries);
     }
-    const hookVars = (0, scaffold_1.collectHooks)(hookEntries);
     // --- Scaffold kernel ---
     const variables = {
         projectName: name,
@@ -130,6 +142,65 @@ function runInit(name, options) {
         capabilities: [],
         createdAt: new Date().toISOString(),
     });
+    // --- Add capability package deps and install before resolving ---
+    // When running from npm (not the monorepo), capability packages aren't in
+    // the CLI's node_modules. We add them to the project's package.json first,
+    // run npm install, then resolve from the project's node_modules.
+    const capDeps = {};
+    for (const capName of capabilityNames) {
+        const pkgName = `@boopkit/cap-${capName}`;
+        capDeps[pkgName] = (0, scaffold_1.getBoopkitVersion)(pkgName);
+    }
+    (0, scaffold_1.mergePackageJson)(targetDir, undefined, undefined, capDeps, { skipBackup: true });
+    // Run npm install early so capability packages are available for resolution
+    if (shouldInstall) {
+        try {
+            console.log('\nInstalling dependencies...');
+            (0, child_process_1.execSync)('npm install', { cwd: targetDir, stdio: 'inherit' });
+        }
+        catch {
+            console.error('Warning: npm install failed. You can run it manually later.');
+        }
+    }
+    // Search paths for capability resolution: project dir first, then CLI root
+    const capSearchPaths = [targetDir];
+    // If hooks couldn't be collected before kernel scaffold (remote install),
+    // collect them now and re-scaffold kernel templates that use hook variables.
+    if (!canResolveLocally) {
+        const hookEntries = [];
+        for (const capName of capabilityNames) {
+            const cap = (0, capability_1.getCapability)(capName, capSearchPaths);
+            if (cap?.hooks) {
+                hookEntries.push({ name: capName, hooks: cap.hooks });
+            }
+        }
+        hookVars = (0, scaffold_1.collectHooks)(hookEntries);
+        // Re-scaffold kernel with correct hook variables
+        variables.hookImports = hookVars.hookImports;
+        variables.hookInit = hookVars.hookInit;
+        variables.hookPreRoutes = hookVars.hookPreRoutes;
+        variables.hookPostRoutes = hookVars.hookPostRoutes;
+        (0, scaffold_1.scaffoldKernel)(targetDir, variables, true);
+    }
+    // Post-install conflict check (when preflight was deferred)
+    if (!preflight) {
+        const postScripts = {};
+        for (const capName of capabilityNames) {
+            const cap = (0, capability_1.getCapability)(capName, capSearchPaths);
+            if (!cap?.scripts)
+                continue;
+            for (const scriptName of Object.keys(cap.scripts)) {
+                if (scriptName in postScripts) {
+                    console.error(`Error: Script "${scriptName}" conflicts between capabilities "${postScripts[scriptName]}" and "${capName}".`);
+                    // Already created the directory, but the project is incomplete — warn user
+                    console.error('The project directory has been partially created and may need cleanup.');
+                    process.exitCode = 1;
+                    return;
+                }
+                postScripts[scriptName] = capName;
+            }
+        }
+    }
     // --- Resolve and install capabilities ---
     const installedCapabilities = [];
     const allScripts = {};
@@ -137,13 +208,13 @@ function runInit(name, options) {
     const capabilityFiles = [];
     const cssCapMap = {};
     for (const capName of capabilityNames) {
-        const cap = (0, capability_1.getCapability)(capName);
+        const cap = (0, capability_1.getCapability)(capName, capSearchPaths);
         if (!cap) {
             console.error(`Warning: Capability "${capName}" not found, skipping.`);
             continue;
         }
         // Copy capability files (skills, scaffolded files, etc.)
-        const copied = (0, scaffold_1.copyCapabilityFiles)(targetDir, capName);
+        const copied = (0, scaffold_1.copyCapabilityFiles)(targetDir, capName, capSearchPaths);
         capabilityFiles.push(...copied);
         // Track CSS partials for annotation
         for (const f of copied) {
@@ -194,7 +265,7 @@ function runInit(name, options) {
     const capabilityConfig = {};
     const envEntries = [];
     for (const capName of installedCapabilities) {
-        const cap = (0, capability_1.getCapability)(capName);
+        const cap = (0, capability_1.getCapability)(capName, capSearchPaths);
         if (cap?.env && cap.env.length > 0) {
             const envConfig = {};
             for (const e of cap.env) {
@@ -239,7 +310,7 @@ function runInit(name, options) {
     const typeOrder = ['application', 'development', 'operations', 'demo'];
     const grouped = new Map();
     for (const capName of installedCapabilities) {
-        const cap = (0, capability_1.getCapability)(capName);
+        const cap = (0, capability_1.getCapability)(capName, capSearchPaths);
         const key = cap?.type ?? 'other';
         if (!grouped.has(key))
             grouped.set(key, []);
@@ -253,15 +324,8 @@ function runInit(name, options) {
         const label = typeLabels[type] ?? type;
         console.log(`    ${label}: ${caps.join(', ')}`);
     }
-    // --- npm install (after summary so output is clear) ---
+    // --- Post-install setup (CSS build, Prisma generate) ---
     if (shouldInstall) {
-        try {
-            console.log('\nInstalling dependencies...');
-            (0, child_process_1.execSync)('npm install', { cwd: targetDir, stdio: 'inherit' });
-        }
-        catch {
-            console.error('Warning: npm install failed. You can run it manually later.');
-        }
         // Build CSS if tailwind:build script exists
         const pkgPath = path.join(targetDir, 'package.json');
         const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
@@ -284,6 +348,13 @@ function runInit(name, options) {
                 console.error('Warning: Prisma generate failed. Run `npm run db:generate` manually.');
             }
         }
+        // Re-run npm install to pick up any new deps added by capability scaffolding
+        try {
+            (0, child_process_1.execSync)('npm install', { cwd: targetDir, stdio: 'inherit' });
+        }
+        catch {
+            // Already warned earlier if npm install has issues
+        }
     }
     console.log(`\nNext steps:`);
     console.log(`  cd ${name}`);

package/dist/lib/capability.d.ts

@@ -1,9 +1,10 @@
 import { CapabilityMetadata } from './config';
 /**
  * Resolve the directory of an installed @boopkit/cap-{name} package.
+ * Searches in the provided paths first, then falls back to boopRoot.
  * Returns null if not found.
  */
-export declare function getPackageDir(name: string): string | null;
+export declare function getPackageDir(name: string, searchPaths?: string[]): string | null;
 /**
  * List all capabilities by scanning package directory and capabilities/ source tree (test fixtures only).
  * Package resolution takes priority. Returns metadata for each valid capability.
@@ -12,6 +13,7 @@ export declare function listCapabilities(): CapabilityMetadata[];
 /**
  * Get a single capability's metadata by name.
  * Tries package resolution first, falls back to source tree.
+ * Pass searchPaths to resolve from a project's node_modules (e.g. during init).
  * Returns null if not found in either location.
  */
-export declare function getCapability(name: string): CapabilityMetadata | null;
+export declare function getCapability(name: string, searchPaths?: string[]): CapabilityMetadata | null;

package/dist/lib/capability.js

@@ -41,29 +41,31 @@ const path = __importStar(require("path"));
 const config_1 = require("./config");
 /**
  * Resolve the directory of an installed @boopkit/cap-{name} package.
+ * Searches in the provided paths first, then falls back to boopRoot.
  * Returns null if not found.
  */
-function getPackageDir(name) {
+function getPackageDir(name, searchPaths) {
     const pkgName = `@boopkit/cap-${name}`;
+    const paths = [...(searchPaths ?? []), (0, config_1.getBoopRoot)()];
     try {
         const pkgJsonPath = require.resolve(`${pkgName}/package.json`, {
-            paths: [(0, config_1.getBoopRoot)()],
+            paths,
         });
         return path.dirname(pkgJsonPath);
     }
     catch {
         // Fall back to scanning for a package whose capability.json has this name
-        return findPackageDirByCapabilityName(name);
+        return findPackageDirByCapabilityName(name, paths);
     }
 }
 /**
  * Read capability metadata from a package's capability.json.
  * Returns null if the package is not found or has no capability.json.
  */
-function getCapabilityFromPackage(name) {
+function getCapabilityFromPackage(name, searchPaths) {
     // getPackageDir already falls back to findPackageDirByCapabilityName on
     // require.resolve failure, so no secondary scan needed here.
-    const pkgDir = getPackageDir(name);
+    const pkgDir = getPackageDir(name, searchPaths);
     if (!pkgDir)
         return null;
     const capJsonPath = path.join(pkgDir, 'capability.json');
@@ -84,25 +86,27 @@ function getCapabilityFromPackage(name) {
  * has the given capability name. Handles mismatches between capability name
  * and package name (e.g. "users-and-accounts" → @boopkit/cap-users).
  */
-function findPackageDirByCapabilityName(name) {
-    const nodeModulesBoopkit = path.join((0, config_1.getBoopRoot)(), 'node_modules', '@boopkit');
-    if (!fs.existsSync(nodeModulesBoopkit))
-        return null;
-    const entries = fs.readdirSync(nodeModulesBoopkit, { withFileTypes: true });
-    for (const entry of entries) {
-        if ((!entry.isDirectory() && !entry.isSymbolicLink()) || !entry.name.startsWith('cap-'))
-            continue;
-        const dir = path.join(nodeModulesBoopkit, entry.name);
-        const capJsonPath = path.join(dir, 'capability.json');
-        if (!fs.existsSync(capJsonPath))
-            continue;
-        try {
-            const capJson = JSON.parse(fs.readFileSync(capJsonPath, 'utf-8'));
-            if (capJson.name === name)
-                return dir;
-        }
-        catch {
+function findPackageDirByCapabilityName(name, searchPaths) {
+    for (const basePath of searchPaths) {
+        const nodeModulesBoopkit = path.join(basePath, 'node_modules', '@boopkit');
+        if (!fs.existsSync(nodeModulesBoopkit))
             continue;
+        const entries = fs.readdirSync(nodeModulesBoopkit, { withFileTypes: true });
+        for (const entry of entries) {
+            if ((!entry.isDirectory() && !entry.isSymbolicLink()) || !entry.name.startsWith('cap-'))
+                continue;
+            const dir = path.join(nodeModulesBoopkit, entry.name);
+            const capJsonPath = path.join(dir, 'capability.json');
+            if (!fs.existsSync(capJsonPath))
+                continue;
+            try {
+                const capJson = JSON.parse(fs.readFileSync(capJsonPath, 'utf-8'));
+                if (capJson.name === name)
+                    return dir;
+            }
+            catch {
+                continue;
+            }
         }
     }
     return null;
@@ -149,11 +153,12 @@ function listCapabilities() {
 /**
  * Get a single capability's metadata by name.
  * Tries package resolution first, falls back to source tree.
+ * Pass searchPaths to resolve from a project's node_modules (e.g. during init).
  * Returns null if not found in either location.
  */
-function getCapability(name) {
+function getCapability(name, searchPaths) {
     // Try package first
-    const fromPackage = getCapabilityFromPackage(name);
+    const fromPackage = getCapabilityFromPackage(name, searchPaths);
     if (fromPackage)
         return fromPackage;
     // Fall back to source tree

package/dist/lib/scaffold.d.ts

@@ -35,7 +35,7 @@ export declare function hashFile(filePath: string): 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): string[];
+export declare function copyCapabilityFiles(targetDir: string, capabilityName: string, searchPaths?: string[]): string[];
 /**
  * Merge dependencies into an existing package.json.
  * Does not overwrite existing dependency versions.
@@ -45,7 +45,9 @@ export declare function copyCapabilityFiles(targetDir: string, capabilityName: s
  */
 /**
  * Read the version from a @boopkit/ package's package.json and return ^version.
- * Falls back to '*' if the package.json cannot be read.
+ * First tries the monorepo packages/ dir, then falls back to resolving the
+ * installed package via require.resolve (for published CLI installs).
+ * Falls back to '*' if neither location works.
  */
 export declare function getBoopkitVersion(packageName: string): string;
 export declare function mergePackageJson(targetDir: string, dependencies?: string[], devDependencies?: string[], packages?: Record<string, string>, options?: {

package/dist/lib/scaffold.js

@@ -125,8 +125,8 @@ function hashFile(filePath) {
  * 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) {
-    const pkgDir = (0, capability_1.getPackageDir)(capabilityName);
+function copyCapabilityFiles(targetDir, capabilityName, searchPaths) {
+    const pkgDir = (0, capability_1.getPackageDir)(capabilityName, searchPaths);
     if (pkgDir) {
         // Read package.json for boopkit config
         const pkgJsonPath = path.join(pkgDir, 'package.json');
@@ -276,18 +276,43 @@ function scaffoldCapabilityFiles(targetDir, filesDir) {
  */
 /**
  * Read the version from a @boopkit/ package's package.json and return ^version.
- * Falls back to '*' if the package.json cannot be read.
+ * First tries the monorepo packages/ dir, then falls back to resolving the
+ * installed package via require.resolve (for published CLI installs).
+ * Falls back to '*' if neither location works.
  */
 function getBoopkitVersion(packageName) {
     const pkgName = packageName.replace(/^@boopkit\//, '');
-    const pkgJsonPath = path.join((0, config_1.getBoopRoot)(), 'packages', pkgName, 'package.json');
+    // Try monorepo packages/ directory first (development)
+    const monorepoPkgJsonPath = path.join((0, config_1.getBoopRoot)(), 'packages', pkgName, 'package.json');
     try {
-        const pkg = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf-8'));
+        const pkg = JSON.parse(fs.readFileSync(monorepoPkgJsonPath, 'utf-8'));
         return `^${pkg.version}`;
     }
     catch {
-        return '*';
+        // Not in monorepo — try require.resolve (published CLI install)
     }
+    // Try resolving the installed package
+    try {
+        const resolvedPath = require.resolve(`${packageName}/package.json`, {
+            paths: [(0, config_1.getBoopRoot)()],
+        });
+        const pkg = JSON.parse(fs.readFileSync(resolvedPath, 'utf-8'));
+        return `^${pkg.version}`;
+    }
+    catch {
+        // Not found — fall back to CLI's own version as a reasonable default
+    }
+    // Use CLI's own version as fallback (all @boopkit packages versioned in same range)
+    try {
+        const cliPkgJsonPath = path.join((0, config_1.getBoopRoot)(), 'package.json');
+        const cliPkg = JSON.parse(fs.readFileSync(cliPkgJsonPath, 'utf-8'));
+        if (cliPkg.version)
+            return `^${cliPkg.version}`;
+    }
+    catch {
+        // give up
+    }
+    return '*';
 }
 function parseDep(dep) {
     // Handle scoped packages: @scope/name@version

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boopkit/cli",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "CLI tool to scaffold new projects from boop profiles and capabilities",
   "main": "dist/cli.js",
   "workspaces": [
@@ -11,7 +11,8 @@
   },
   "files": [
     "dist/",
-    "profiles/"
+    "profiles/",
+    "src/templates/"
   ],
   "publishConfig": {
     "access": "public"

package/src/templates/kernel/.github/copilot-instructions.md

@@ -0,0 +1,3 @@
+Read the [AGENTS.md](../AGENTS.md) file and follow those instructions.
+
+Before writing any code, run `boop status` to see what capabilities are configured and what needs setup.

package/src/templates/kernel/.gitignore.hbs

@@ -0,0 +1,7 @@
+node_modules/
+dist/
+.env
+*.log
+.DS_Store
+.boop/*
+!.boop/config.json

package/src/templates/kernel/AGENTS.md.hbs

@@ -0,0 +1,28 @@
+# {{projectName}}
+
+This is a **boop**-managed project. Use boop commands — don't reinvent what boop already provides.
+
+## Getting Started
+
+1. Run `boop status` to see what needs configuration
+2. Follow the setup hints to configure your environment
+3. Run `npm run dev` to start the development server
+
+## How to work in this project
+
+1. **Check skills first.** Before coding, reviewing, testing, or designing, check [skills/index.md](skills/index.md) for a matching skill and follow its process. Do not rely on general knowledge when a project skill exists.
+2. **Use boop for capabilities.** To add features like database, auth, or other infrastructure, run `boop add <capability>` — don't install or wire things manually. Run `boop caps` to see what's available.
+3. **Check project status.** Run `boop status` to see what's configured and what needs attention.
+4. **Run `boop --help`** for the full command list.
+
+## Boop extension model
+
+Read [reference/boop-guide.ref.md](reference/boop-guide.ref.md) to understand how this project's services, controllers, and styles are structured — service tiers, factory patterns, the adoption curve (use → compose → adopt), and CSS extension.
+
+## Project layout
+- `src/` — source code
+- `skills/` — process skills for agents (read `skills/index.md`)
+- `reference/` — architecture and coding standards ("what exists now")
+- `specs/` — design docs and specifications ("future state")
+- `tests/` — `npm test` (Jest)
+- `.boop/` — project manifest (managed by boop)

package/src/templates/kernel/CLAUDE.md.hbs

@@ -0,0 +1,3 @@
+# {{projectName}}
+
+Read [AGENTS.md](AGENTS.md) and follow all instructions there.

package/src/templates/kernel/Procfile.hbs

@@ -0,0 +1 @@
+web: npm start

package/src/templates/kernel/README.md.hbs

@@ -0,0 +1,17 @@
+# {{projectName}}
+
+A project scaffolded with [boop](https://github.com/boop).
+
+## Getting Started
+
+```bash
+npm install
+npm run dev
+```
+
+## Scripts
+
+- `npm start` — Start the application
+- `npm run dev` — Start in development mode
+- `npm run build` — Build the project
+- `npm test` — Run tests

package/src/templates/kernel/package.json.hbs

@@ -0,0 +1,16 @@
+{
+  "name": "{{projectName}}",
+  "version": "0.1.0",
+  "private": true,
+  "engines": {
+    "node": "{{nodeVersion}}"
+  },
+  "scripts": {
+    "start": "{{scripts.start}}",
+    "dev": "{{scripts.dev}}",
+    "build": "{{scripts.build}}",
+    "test": "{{scripts.test}}"
+  },
+  "dependencies": {},
+  "devDependencies": {}
+}

package/src/templates/kernel/reference/boop-guide.ref.md

@@ -0,0 +1,160 @@
+# Busy Agent's Guide to Boop
+
+Quick orientation for AI agents working in a boop-generated project. Read this before modifying service code, controller logic, or styles.
+
+**Deep dive**: If this project has `reference/application-services.ref.md`, it covers service tiers, factory internals, and controller patterns in full detail.
+
+---
+
+## How Boop Projects Work
+
+Boop projects are built from **capabilities** — each one adds skills, npm packages, scaffolded files, or all three. The developer owns scaffolded files from day one. Packages (`@boopkit/*`) are managed dependencies that can be updated via npm — or adopted into the project when the developer outgrows them.
+
+Key commands:
+- `boop caps` — list available capabilities
+- `boop add <capability>` — add a capability to the project
+- `boop adopt <capability>` — copy package source into the project and take ownership
+- `boop status` — check project configuration and what needs attention
+
+---
+
+## Service Tiers
+
+Application logic is organized into four tiers. Dependency flows downward only.
+
+```
+Developer code          ← project-owned, fully custom
+  → Business services   ← multi-step orchestration (e.g. postNotice)
+    → Data services     ← typed CRUD + lifecycle events (e.g. createNoticeService)
+      → Entity primitives ← createEntityService, createPropertyService (@boopkit/cap-services)
+        → Primitives    ← middleware, DB helpers, validators
+```
+
+| Tier | In package? | npm updatable? | Typical relationship |
+|------|-------------|----------------|---------------------|
+| Primitives | Yes | Yes | Stable utilities — rarely replaced |
+| Data services | Yes | Yes | Long-lived composable building blocks |
+| Business services | Yes | Yes | Use until you outgrow, then adopt |
+| Developer code | No | N/A | Fully owned from the start |
+
+---
+
+## Factory Pattern
+
+Boop services export **factory functions** that return a bag of typed methods — not classes, not singletons.
+
+```typescript
+const noticeService = createNoticeService<MyNoticeInfo>(store);
+const { create, findById, list } = noticeService;  // destructuring is safe
+```
+
+**Generic type params** let you extend the base entity shape. Set the type once at factory creation; type safety flows to every returned method:
+
+```typescript
+interface MyNoticeInfo extends BaseNoticeInfo {
+  priority: 'low' | 'medium' | 'high';
+  tags: string[];
+}
+const noticeService = createNoticeService<MyNoticeInfo>(store);
+// All methods are now typed with MyNoticeInfo
+```
+
+**Lifecycle events** are optional callbacks passed to the factory. When provided, they fire on mutations. When omitted, they're no-ops:
+
+```typescript
+const noticeService = createNoticeService<MyNoticeInfo>(store, {
+  onCreated: async (notice) => { /* publish, log, index, etc. */ },
+});
+```
+
+---
+
+## The Adoption Curve: Use → Compose → Adopt
+
+Every boop service supports three levels of engagement. Move between them as needs evolve.
+
+### 1. Use the box
+Call the high-level method. Accept the defaults.
+```typescript
+const notice = await noticeBoardService.postNotice(input);
+```
+
+### 2. Compose the steps
+Business services expose their sub-operations as public methods. Orchestrate them yourself, inserting custom logic between steps:
+```typescript
+noticeBoardService.validateContent(input);
+const notice = await noticeBoardService.createNotice(input);
+await myCustomApprovalWorkflow(notice);          // your step
+await noticeBoardService.notifySubscribers(notice);
+```
+
+**How to find decomposed operations**: Look at the convenience method's implementation — it calls the individual steps in sequence. Each step is a public method on the same service. JSDoc on each method explains what it does.
+
+### 3. Adopt
+Copy the package source into the project and own it:
+```bash
+boop adopt noticeboard
+```
+
+This copies `@boopkit/cap-noticeboard` source into `src/adopted/cap-noticeboard/`, rewrites all imports, removes the package dependency, and updates the manifest. From here, the developer maintains the code directly.
+
+> **"Adopt" not "eject."** Adoption implies natural maturation — taking ownership of code that served you well.
+
+---
+
+## Controller Handlers
+
+Packages export **individual route handlers** as named functions, plus an optional **router factory**:
+
+**Use the box** — mount the whole router:
+```typescript
+app.use('/noticeboard', createNoticeBoardRouter({ noticeBoardService }));
+```
+
+**Compose the steps** — pick individual handlers, add custom middleware:
+```typescript
+const handlers = createNoticeBoardHandlers({ noticeBoardService });
+app.get('/noticeboard',     handlers.listNotices);
+app.post('/noticeboard',    rateLimit(5), handlers.postNotice);
+app.delete('/noticeboard/:id', requireAdmin, handlers.deleteNotice);
+```
+
+---
+
+## CSS Extension
+
+The project's `styles/styles.css` imports from packages in a layered cascade:
+
+```css
+@import "tailwindcss";                              /* 1. Framework */
+@import "@boopkit/cap-web/styles/theme.css";        /* 2. Design tokens */
+@import "@boopkit/cap-web/styles/base.css";         /* 3. Base styles */
+@import "@boopkit/cap-noticeboard/styles/...";      /* 4. Capability styles */
+
+@theme { --color-brand-600: #059669; }              /* 5. Project overrides */
+.btn-primary { @apply shadow-lg; }                  /* 6. Component overrides */
+```
+
+**Design tokens** (`@theme`) generate Tailwind utilities automatically. Override a token → everything downstream updates.
+
+**Package CSS is npm-updatable.** Boop ships new components that pick up the project's brand colors via tokens. Developers override any class by redeclaring it later in the file — CSS cascade handles precedence.
+
+**The same adoption curve applies**: use the imports → override specific classes → drop the import and own the styles.
+
+---
+
+## Project Structure at a Glance
+
+| Directory | Owned by | Purpose |
+|-----------|----------|---------|
+| `src/services/` | Developer | Service wiring files (bridge factories to ServiceMap) |
+| `src/routes/` | Developer | Route mounting (thin glue over handler sets) |
+| `src/controllers/` | Developer | Project-specific controllers |
+| `src/adopted/` | Developer | Adopted package source (created by `boop adopt`) |
+| `styles/` | Developer | Project CSS (imports from packages + overrides) |
+| `styles/adopted/` | Developer | Adopted package styles |
+| `views/` | Developer | Handlebars templates (layouts, pages, partials) |
+| `node_modules/@boopkit/*` | Package | Managed dependencies (updatable via npm) |
+| `skills/` | Scaffolded | Agent skills (process guidance) |
+| `reference/` | Scaffolded | Architecture docs |
+| `.boop/config.json` | Boop | Project manifest (capabilities, adopted packages) |

package/src/templates/kernel/specs/README.md

@@ -0,0 +1,12 @@
+# Specs
+
+Design documents and specifications for planned features and changes. Specs describe the **future state** — what we intend to build — in contrast to `reference/` which documents the **current state**.
+
+## Workflow
+
+1. Write a spec for a new feature or significant change
+2. Review and approve the spec
+3. Create implementation tasks (in beads) from the approved spec
+4. After shipping, update `reference/` docs to reflect the new reality
+
+Specs remain as a record of design intent even after implementation.

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

@@ -0,0 +1,23 @@
+// @boopkit:env
+import express from 'express';
+{{{hookImports}}}
+
+const app = express();
+const PORT = process.env.PORT || {{port}};
+app.locals.projectName = '{{projectName}}';
+
+app.use(express.json());
+app.use(express.urlencoded({ extended: true }));
+{{{hookPreRoutes}}}
+
+{{{hookPostRoutes}}}
+
+export async function boot() {
+  {{{hookInit}}}
+
+  app.listen(PORT, () => {
+    console.log(`{{projectName}} listening on port ${PORT}`);
+  });
+}
+
+export default app;

package/src/templates/kernel/src/server.ts.hbs

@@ -0,0 +1,3 @@
+import { boot } from './app';
+boot();
+

package/src/templates/kernel/tsconfig.json.hbs

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "commonjs",
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}