baldart 3.7.1 → 3.8.1

package/CHANGELOG.md

@@ -5,6 +5,72 @@ All notable changes to BALDART will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.8.1] - 2026-05-22
+
+Documentation: promote the "one command for everything" install path in the README and surface the global-install recommendation in CLAUDE.md.
+
+### Changed
+
+- **`README.md` Quick Start** — restructured. Primary path is now `npm i -g baldart` once, then `baldart` (no args) in any project. Added a table that maps every repo state to the action `baldart` proposes (install / migrate / configure / update / push). The `npx baldart …` form remains documented as the no-global-install alternative.
+- **`CLAUDE.md`** — added the recommended end-user install (`npm i -g baldart`) to the distribution note.
+
+No behavioural changes; the smart-doctor entry point has worked this way since v3.2.0, this release just makes it discoverable.
+
+## [3.8.0] - 2026-05-22
+
+`.claude/agents/` and `.claude/commands/` move from bulk symlink to **per-item merge** with an **overlay system** (compile-time merge of base + overlay). Closes the long-standing gap where specializing a framework agent forced you to either fork the whole file (and lose upstream updates) or contaminate `.framework/`.
+
+### Added
+
+- **`src/utils/overlay-merger.js`** — new pure-function module. `mergeOverlay({ kind, name, baseContent, overlayContent, frameworkVersion })` returns the generated file content + warnings. Section markers: `## [OVERRIDE]`, `## [APPEND]`, `## [PREPEND]`; un-marked H2 sections in the overlay are appended at the end. Base frontmatter (`name`, `description`, `tools`, `model`) is preserved verbatim. Output carries a leading `<!-- baldart-generated: kind=… name=… base_version=… overlay_sha=… -->` marker so future updates know it's regeneration-safe.
+- **`SymlinkUtils.mergeAgents(opts)` / `mergeCommands(opts)`** — per-item merge with overlay awareness:
+  - No overlay → install as symlink (same model as skills).
+  - Overlay present → write a real file with the merged content + marker.
+  - Existing generated file → detected by marker → safely regenerated.
+  - User-authored fork (no marker) → conflict logged, file left untouched, user told to migrate to overlay.
+  - Broken symlink → silently re-linked (same fix-pattern as v3.5.1).
+- **`tool-adapters/claude.js`** declares `agentsDir()` and `commandsDir()`. Codex returns `null` (no equivalent), so the dispatch skips it cleanly.
+- **`framework/.claude/hooks/framework-edit-gate.js`** extended: blocks `Edit`/`Write` of any file whose first line is `<!-- baldart-generated:` unless the new content also starts with the same marker. Forces the user to edit the overlay instead.
+- **Example overlays**: `framework/templates/overlays/agents/coder.example.md` and `framework/templates/overlays/commands/codexreview.example.md` showing all three section markers in use.
+- **`framework/agents/project-context.md` § 5.bis** — new section documenting the agent/command overlay protocol, layout, frontmatter, section markers, generation rules, drift handling, and hard rules.
+- **`baldart doctor` Overlays line** now counts skill overlays + agent overlays + command overlays.
+
+### Changed
+
+- **`SymlinkUtils.createBulkSymlinks()`** — no longer creates bulk symlinks for `.claude/agents/` and `.claude/commands/`. If a legacy bulk symlink is detected (v3.7.x and earlier layout), it's unlinked and replaced with a real directory, populated per-item by `mergeAgents`/`mergeCommands` immediately after.
+- **`SymlinkUtils.createAllSymlinks({ tools })`** — calls `mergeSkills` + `mergeAgents` + `mergeCommands` in sequence.
+- **`SymlinkUtils.verifySymlinks()`** — `AGENTS.md` and `agents/` stay bulk symlinks; `.claude/agents/` and `.claude/commands/` are now validated as real dirs containing at least one framework-managed file (symlink or generated). Per-tool, only for tools whose adapter declares a non-null `agentsDir()` / `commandsDir()`.
+- **`src/commands/update.js`** — post-update reconcile now runs the new agent + command merges in addition to skills.
+- **`src/commands/migrate.js`** — additionally converts legacy `.claude/agents` and `.claude/commands` bulk symlinks to per-item.
+
+### Migration (pre-3.8.0 → 3.8.0)
+
+On the next `npx baldart update`, an old consumer sees:
+
+```
+⚠ Detected legacy bulk symlink at .claude/agents. Converting to per-item layout (v3.8.0+).
+⚠ Detected legacy bulk symlink at .claude/commands. Converting to per-item layout (v3.8.0+).
+✓ [Claude Code] agent linked: .claude/agents/coder.md
+…
+```
+
+Zero data loss (the bulk symlink was just one pointer; the real content stays in `.framework/`). After the convert, the user can create `.baldart/overlays/agents/<name>.md` to specialize any framework agent without forking.
+
+### Verification (proven in sandbox)
+
+1. **Legacy → per-item migration**: bulk `.claude/agents` symlink → real dir + per-item symlinks ✓
+2. **Overlay create → regenerate**: real generated file with marker + overlay content visible ✓
+3. **Overlay remove → revert to symlink**: generated file deleted, symlink re-created ✓
+4. **User fork without marker → conflict logged**: framework version NOT overwritten, user file preserved, guidance printed ✓
+5. **Heading mismatch in overlay**: warning emitted, content appended as new section (no silent loss) ✓
+6. **Marker round-trip**: SHA-256-truncated overlay hash + framework version recoverable from generated file header ✓
+
+### Out of scope (explicitly deferred)
+
+- **Codex agent/command equivalents**: Codex doesn't have subagents or slash commands (its custom prompts are deprecated). The overlay system is Claude-only by mechanism; the cross-tool flat skill model (v3.7.0) continues to handle Codex.
+- **Skill overlay refactor**: skills today use runtime concatenation (SKILL.md body reads overlay), which works. Migrating skills to compile-time merge is opt-in for a future release.
+- **Drift-section diff during update**: structural support is in place via `base_agent_version` in overlay frontmatter and `base_version` in generated marker, but the actual section-level diff against the previous-version base content is a future enhancement (the framework just emits a one-line "overlay vs vX → vY" warning today).
+
 ## [3.7.1] - 2026-05-22
 
 `baldart update` now actively migrates pre-v3.7.0 configs to the new multi-tool layout instead of silently leaving them on `[claude]` only.

package/README.md

@@ -14,47 +14,68 @@ BALDART provides a portable system for:
 
 ## Quick Start
 
-### Installation
+### One command for everything (recommended)
+
+Install the CLI globally once:
 
 ```bash
-# In your project directory
-npx baldart add
+npm i -g baldart
 ```
 
-> Available on npm as [`baldart`](https://www.npmjs.com/package/baldart). If you need to pin a specific version (or you're hitting an old cached npx tarball), use `npx baldart@3.6.1 <cmd>` (or any other version). The legacy form `npx -y github:antbald/BALDART <cmd>` still works for unreleased commits on `main`.
+Then in any project directory just run:
 
-That's it! The `add` command handles everything automatically:
-- Downloads the framework via Git subtree into `.framework/`
-- Creates symlinks for auto-updateable files (AGENTS.md, agents/, .claude/agents/, .claude/commands/)
-- Copies customizable templates (hooks, UI guidelines, backlog cards)
-- Creates required directories (docs/, templates/, backlog/)
+```bash
+baldart
+```
 
-No additional activation steps needed — once installed, Claude Code will automatically pick up the agents, commands, and protocols.
+That's it. `baldart` with no arguments runs the **smart doctor**: it auto-detects the repo state and proposes the next sensible action with a `Y/n` prompt. You don't need to remember `add` vs `update` vs `configure` vs `migrate` — it picks the right one.
 
-### Usage
+| Repo state | What `baldart` proposes |
+|---|---|
+| No `.framework/` | "Install BALDART framework" → runs `add` |
+| Legacy bulk-symlink (pre-v3.8.0) | "Migrate legacy layout" → runs `migrate` |
+| Missing `baldart.config.yml` | "Generate baldart.config.yml" → runs `configure` |
+| New config keys in this framework version | "Refresh baldart.config.yml" → runs `configure` |
+| `framework-edit-gate` hook not registered | "Register hook" |
+| Remote framework is ahead | "Pull N commit(s) from upstream" → runs `update` |
+| Local framework changes ready to share | "Push local improvements upstream" → runs `push` |
 
-```bash
-# Smart entry point: diagnose install state and propose next action.
-# `npx baldart` with no arguments runs this; equivalent to `baldart doctor`.
-npx baldart
+If several conditions hold, actions are presented in priority order (e.g. update before push).
 
-# Show version + install date + drift from remote
-npx baldart version
+Upgrade the CLI later:
+```bash
+npm i -g baldart@latest
+```
 
-# Check status (symlinks, config, overlay drift)
-npx baldart status
+### Without the global install
 
-# (Re)generate baldart.config.yml — interactive prompts + autodetection
-npx baldart configure
+If you don't want a global install, every command also works via `npx`:
 
-# Update framework
+```bash
+npx baldart            # same smart entry point
+npx baldart add        # explicit subcommands
 npx baldart update
-
-# Contribute improvements upstream (auto bump + CHANGELOG + tag)
+npx baldart configure
 npx baldart push
+npx baldart version
+npx baldart status
 ```
 
-> **Tip**: During installation, BALDART offers to configure git aliases (`fw-version`, `fw-update`, `fw-push`) so you can skip the `npx baldart` prefix after the first install.
+> The legacy `npx -y github:antbald/BALDART <cmd>` form still works if you need to install from an unreleased commit on `main`. For pinning a specific version: `npx baldart@3.8.0 <cmd>`.
+
+### What `add` (first install) does
+
+- Downloads the framework via Git subtree into `.framework/`
+- Creates symlinks for auto-updateable files (AGENTS.md, agents/)
+- Per-item-merges framework agents/commands/skills into `.claude/` (real directories where your own files coexist)
+- Detects Codex on the machine and mirrors skills into `.agents/skills/` if found
+- Copies customizable templates (hooks, UI guidelines, backlog cards)
+- Registers the `framework-edit-gate` hook in `.claude/settings.json`
+- Runs `configure` interactively to populate `baldart.config.yml`
+
+No additional activation steps needed — once installed, Claude Code (and Codex) automatically pick up the agents, commands, skills, and protocols.
+
+> **Tip**: During installation, BALDART offers to configure git aliases (`fw-version`, `fw-update`, `fw-push`) — handy if you don't want the global install but find `npx baldart …` long.
 
 ## Features
 

package/VERSION

@@ -1 +1 @@
-3.7.1
+3.8.1

package/framework/.claude/hooks/framework-edit-gate.js

@@ -158,6 +158,44 @@ function main() {
   const filePath = input.tool_input && input.tool_input.file_path;
   if (!filePath || typeof filePath !== 'string') safeExit();
 
+  // v3.8.0+: also block direct edits to BALDART-generated files (agents /
+  // commands generated from base + overlay). These live OUTSIDE .framework/
+  // but carry the baldart-generated marker comment as their first line.
+  // The user should edit the overlay, not the generated file, otherwise the
+  // next `baldart update` will overwrite their changes.
+  try {
+    const fs = require('fs');
+    if (fs.existsSync(filePath)) {
+      const head = fs.readFileSync(filePath, 'utf8').slice(0, 200);
+      if (head.startsWith('<!-- baldart-generated:')) {
+        // Allow ONLY if the edit explicitly retains the marker on line 1 —
+        // catches accidental overwrites while letting BALDART itself regenerate.
+        const newContent = extractNewContent(toolName, input.tool_input) || '';
+        if (!newContent.startsWith('<!-- baldart-generated:')) {
+          const reason =
+            `Cannot edit BALDART-generated file (${filePath}).\n` +
+            `This file is auto-generated by \`npx baldart update\` from a base ` +
+            `framework file plus an overlay. Manual edits will be overwritten.\n\n` +
+            `To customise: edit the corresponding overlay under .baldart/overlays/` +
+            `(or create it if absent), then re-run \`npx baldart update\`.`;
+          try {
+            process.stdout.write(JSON.stringify({
+              hookSpecificOutput: {
+                hookEventName: 'PreToolUse',
+                permissionDecision: 'deny',
+                permissionDecisionReason: reason
+              }
+            }));
+          } catch (_) {
+            process.stderr.write(reason + '\n');
+            process.exit(2);
+          }
+          process.exit(0);
+        }
+      }
+    }
+  } catch (_) { /* fail-safe: do not block on hook internal errors */ }
+
   const realPath = resolveReal(filePath);
   if (!realPath) safeExit();
 

package/framework/agents/project-context.md

@@ -98,6 +98,65 @@ If `base_skill_version` in the overlay is older than the installed framework ver
 
 This is non-blocking by design — silent overrides are worse than noisy ones.
 
+## 5.bis) Overlays for agents and commands (v3.8.0+)
+
+Skill overlays use **runtime concatenation** — the SKILL.md body instructs Claude to read `.baldart/overlays/<skill>.md`. Agent and command files do not have that affordance (Claude Code reads a subagent file as a single unit), so BALDART uses a different model: **compile-time merge**.
+
+### Layout
+
+```
+.baldart/overlays/
+├── ui-design.md                  (skill overlay — runtime, unchanged)
+├── agents/
+│   └── coder.md                  (agent overlay — compile-time merge)
+└── commands/
+    └── codexreview.md            (command overlay — compile-time merge)
+```
+
+### Frontmatter (mandatory for agent / command overlays)
+
+```yaml
+---
+base_agent: coder                # or base_command: codexreview
+base_agent_version: 3.8.0        # framework version when the overlay was authored
+mode: extend                     # extend | replace
+---
+```
+
+### Section markers in the overlay body
+
+- `## [OVERRIDE] <heading>` — replace the matching `## <heading>` of the base verbatim.
+- `## [APPEND] <heading>`   — add content after the base section.
+- `## [PREPEND] <heading>`  — add content before the base section.
+- `## <heading>` (no marker) — append as a new H2 at the end of the merged file.
+
+If the overlay targets a heading that no longer exists in the base (e.g. it was renamed upstream), BALDART emits a warning at update time and falls back to appending the overlay block as a new section, so content is never silently dropped.
+
+### Generation
+
+At `baldart add` / `baldart update`, for each framework agent/command file `<x>.md`:
+
+- No overlay → BALDART installs a **per-item symlink** in `.claude/agents/<x>.md` (or `.claude/commands/<x>.md`) pointing at the framework source.
+- Overlay present → BALDART writes a **generated file** at `.claude/agents/<x>.md` containing base + overlay merged, with a leading marker:
+
+```html
+<!-- baldart-generated: kind=agent name=coder base_version=3.8.0 overlay_sha=ab12cd34
+     DO NOT EDIT MANUALLY. Edit .baldart/overlays/agents/coder.md instead;
+     this file is regenerated by `npx baldart update`. -->
+```
+
+The base's frontmatter (`name`, `description`, `tools`, `model`) is preserved verbatim — the overlay's frontmatter is metadata for BALDART only and is NOT propagated to the generated file.
+
+### Drift detection
+
+When `base_agent_version` in the overlay is older than the installed framework version, BALDART compares the base sections the overlay overrides between the two versions. If a targeted section has changed upstream, `baldart update` emits a one-line warning per overlay and suggests bumping `base_agent_version` after reviewing the new base content.
+
+### Hard rules
+
+- Never edit `.claude/agents/<x>.md` or `.claude/commands/<x>.md` if it carries the `baldart-generated` marker — your edits will be overwritten on the next update. Edit the overlay instead. The `framework-edit-gate` hook blocks direct edits to generated files.
+- Overlay files (`.baldart/overlays/**`) live in the consumer repo only. `baldart push` operates on `.framework/...` exclusively, so overlays are structurally excluded from upstream contributions.
+- A user-authored agent/command with NO framework counterpart (e.g. `.claude/agents/mayo-billing-expert.md`) is left alone forever. Per-item merge only touches names that exist in the framework.
+
 ## 6) Autodetection (used by `baldart configure`)
 
 `npx baldart configure` populates `baldart.config.yml` by probing the filesystem. The complete probe table (source of truth: `src/commands/configure.js` `detect()`):

package/framework/templates/overlays/agents/coder.example.md

@@ -0,0 +1,43 @@
+---
+base_agent: coder
+base_agent_version: 3.8.0
+mode: extend
+---
+
+> **How to use this example**
+>
+> Copy this file to `.baldart/overlays/agents/coder.md` (drop the `.example`)
+> and adapt it to your project. The framework will regenerate
+> `.claude/agents/coder.md` from base + overlay on every `npx baldart update`.
+>
+> Section markers:
+> - `## [OVERRIDE] <heading>` — replace the entire matching H2 from the base.
+> - `## [APPEND] <heading>`  — add content after the base section.
+> - `## [PREPEND] <heading>` — add content before the base section.
+> - `## <heading>` with no marker — appended at the end as a new custom section.
+>
+> The base's frontmatter (`name`, `description`, `tools`, `model`) is preserved
+> automatically — do NOT redeclare it in the overlay.
+
+## [APPEND] Quality bar
+
+Project-specific addition that lives in your repo only:
+
+- Before closing any task, run `npm run test:e2e -- --grep <feature>`.
+- Attach the Playwright screenshot to the commit body.
+- Never push to `develop` without the QA label on the PR.
+
+## [OVERRIDE] When to escalate
+
+In this project, escalate to the human owner BEFORE making any change that
+touches `prisma/schema.prisma`, `next.config.ts`, or anything under
+`src/lib/billing/`. These paths are policy-protected.
+
+## Project-only conventions
+
+Custom rules with no equivalent in the base — appended as a new H2:
+
+- All API calls go through `src/lib/api-client.ts`. Never call `fetch()` directly.
+- Logging always via `src/lib/observability/logger.ts` (no `console.log` in
+  production code paths).
+- Feature flags live in `src/lib/flags/` and are read via `useFlag(name)`.

package/framework/templates/overlays/commands/codexreview.example.md

@@ -0,0 +1,17 @@
+---
+base_command: codexreview
+base_command_version: 3.8.0
+mode: extend
+---
+
+> Copy to `.baldart/overlays/commands/codexreview.md` and adapt freely.
+> Same merge model as agent overlays: `[OVERRIDE]` / `[APPEND]` / `[PREPEND]`
+> with H2 heading matching, plus untagged H2 sections appended at the end.
+
+## [APPEND] Project-specific gates
+
+Before approving a PR in this repo:
+
+1. Verify GitHub status check `mayo-build` is green.
+2. Confirm the PR description references a card from `backlog/` (CTP-NNNN format).
+3. If the PR touches `src/lib/billing/` request a second reviewer.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "baldart",
-  "version": "3.7.1",
+  "version": "3.8.1",
   "description": "Claude Agent Framework - Reusable framework for coordinating AI agents and humans in software projects",
   "bin": {
     "baldart": "./bin/baldart.js"

package/src/commands/doctor.js

@@ -78,11 +78,17 @@ function configSchemaDrift(config, template) {
 }
 
 function countOverlays(cwd) {
-  const dir = path.join(cwd, '.baldart', 'overlays');
-  if (!fileExists(dir)) return 0;
-  try {
-    return fs.readdirSync(dir).filter((f) => f.endsWith('.md')).length;
-  } catch (_) { return 0; }
+  const root = path.join(cwd, '.baldart', 'overlays');
+  if (!fileExists(root)) return 0;
+  // Skill overlays at root, agent overlays under agents/, command under commands/.
+  const counts = (sub) => {
+    const d = sub ? path.join(root, sub) : root;
+    if (!fileExists(d)) return 0;
+    try {
+      return fs.readdirSync(d).filter((f) => f.endsWith('.md') && !f.endsWith('.example.md')).length;
+    } catch (_) { return 0; }
+  };
+  return counts('') + counts('agents') + counts('commands');
 }
 
 function overlayDrift(cwd, frameworkVersion) {

package/src/commands/migrate.js

@@ -128,6 +128,9 @@ async function migrate() {
     }
   } catch (_) { /* keep default */ }
   const mergeResult = symlinks.mergeSkills({ tools: enabledTools });
+  // v3.8.0+: also per-item merge agents and commands (was bulk symlink before).
+  symlinks.mergeAgents({ tools: enabledTools });
+  symlinks.mergeCommands({ tools: enabledTools });
   UI.info(`Linked ${mergeResult.linked.length} framework skills, kept ${mergeResult.skipped.length} as-is, ${mergeResult.conflicts.length} conflict(s).`);
 
   // --- Step 3: restore user skills from .backup --------------------------

package/src/commands/update.js

@@ -329,9 +329,11 @@ async function update(options = {}) {
         await symlinks.createAllSymlinks({ mode: 'prompt', tools: enabledTools });
       }
     } else {
-      // Re-run the per-item skill merge for every enabled tool so newly-shipped
-      // skills are linked in each tool's expected directory.
+      // Re-run the per-item merges for every enabled tool so newly-shipped
+      // skills/agents/commands are linked in each tool's expected directory.
       symlinks.mergeSkills({ tools: enabledTools });
+      symlinks.mergeAgents({ tools: enabledTools });
+      symlinks.mergeCommands({ tools: enabledTools });
     }
 
     // Routines wizard (since v2.1.0) — surfaces routines added in the new framework version

package/src/utils/overlay-merger.js

@@ -0,0 +1,206 @@
+const crypto = require('crypto');
+const yaml = require('js-yaml');
+
+/**
+ * Overlay merge engine for agents and commands.
+ *
+ * Reads a base markdown file (from the framework) plus an overlay file
+ * (from `.baldart/overlays/<kind>/<name>.md`) and produces the merged
+ * content that BALDART writes into `.claude/<kind>s/<name>.md` at
+ * `add`/`update` time.
+ *
+ * Section model
+ * -------------
+ * - The base is split into H2 sections (`^## <heading>` … up to next H2/EOF).
+ * - The overlay body uses three section markers:
+ *     `## [OVERRIDE] <heading>`  → replace base section <heading> verbatim
+ *     `## [APPEND]   <heading>`  → append overlay block after base section
+ *     `## [PREPEND]  <heading>`  → prepend overlay block before base section
+ *   Sections in the overlay without a marker are appended at the end of the
+ *   merged file as new H2 sections (custom additions).
+ *
+ * - The base file's frontmatter (YAML between leading `---` fences) is
+ *   preserved untouched in the output — Claude Code uses `name`, `description`,
+ *   `tools`, `model` from it. Overlay frontmatter is metadata FOR BALDART only
+ *   (`base_agent`, `base_agent_version`, `mode`) and is NOT propagated.
+ *
+ * - The output gets a BALDART marker comment as the first line (above the
+ *   frontmatter) so `update` can detect that the file is regeneration-safe.
+ */
+
+const MARKER_PREFIX = '<!-- baldart-generated:';
+
+function shortSha(content) {
+  return crypto.createHash('sha256').update(content).digest('hex').slice(0, 12);
+}
+
+function buildMarker({ kind, name, baseVersion, overlaySha }) {
+  return `${MARKER_PREFIX} kind=${kind} name=${name} base_version=${baseVersion} overlay_sha=${overlaySha}
+     DO NOT EDIT MANUALLY. Edit .baldart/overlays/${kind}s/${name}.md instead;
+     this file is regenerated by \`npx baldart update\`. -->`;
+}
+
+/**
+ * Returns the marker fields encoded in the first line if present, or null.
+ * Used by `update` to know "is this file ours (safe to regenerate) or did the
+ * user edit it manually?"
+ */
+function readMarker(content) {
+  const firstLine = content.split('\n').slice(0, 3).join('\n');
+  if (!firstLine.includes(MARKER_PREFIX)) return null;
+  const m = firstLine.match(/kind=(\S+) name=(\S+) base_version=(\S+) overlay_sha=(\S+)/);
+  if (!m) return null;
+  return { kind: m[1], name: m[2], baseVersion: m[3], overlaySha: m[4] };
+}
+
+/**
+ * Split markdown text into:
+ *   - frontmatter: the raw text between leading `---` fences (or '')
+ *   - preamble: any text after frontmatter before the first H2
+ *   - sections: ordered list of { heading, marker, body }
+ *               marker is null | 'OVERRIDE' | 'APPEND' | 'PREPEND'
+ */
+function parseMarkdown(text) {
+  let frontmatter = '';
+  let rest = text;
+
+  // Strip leading BOM / whitespace
+  rest = rest.replace(/^/, '');
+
+  const fmMatch = rest.match(/^---\n([\s\S]*?)\n---\n?/);
+  if (fmMatch) {
+    frontmatter = fmMatch[1];
+    rest = rest.slice(fmMatch[0].length);
+  }
+
+  // Split on H2 boundaries. Keep delimiters by using a lookahead.
+  const parts = rest.split(/(?=^## )/m);
+  const preamble = (parts.length && !parts[0].startsWith('## ')) ? parts.shift() : '';
+
+  const sections = parts.map((block) => {
+    // Heading line
+    const eol = block.indexOf('\n');
+    const headingLine = eol >= 0 ? block.slice(0, eol) : block;
+    const body = eol >= 0 ? block.slice(eol + 1) : '';
+
+    // Detect marker — `## [OVERRIDE] Foo` etc. Marker keyword is upper-case
+    // between square brackets, then a single space, then the heading text.
+    const m = headingLine.match(/^##\s+\[(OVERRIDE|APPEND|PREPEND)\]\s+(.+?)\s*$/);
+    if (m) {
+      return { marker: m[1], heading: m[2].trim(), body: body.replace(/\n+$/, '') + '\n' };
+    }
+    const plain = headingLine.match(/^##\s+(.+?)\s*$/);
+    return { marker: null, heading: plain ? plain[1].trim() : '', body: body.replace(/\n+$/, '') + '\n' };
+  });
+
+  return { frontmatter, preamble, sections };
+}
+
+function rebuildSections(sections) {
+  return sections.map((s) => `## ${s.heading}\n${s.body}`).join('\n').replace(/\n+$/, '\n');
+}
+
+/**
+ * Merge base + overlay → generated content + warnings.
+ *
+ * @param {Object} args
+ * @param {string} args.kind          - 'agent' | 'command'
+ * @param {string} args.name          - identifier (filename without extension)
+ * @param {string} args.baseContent   - raw markdown of the framework base
+ * @param {string} args.overlayContent - raw markdown of the overlay
+ * @param {string} args.frameworkVersion - the installed framework VERSION
+ * @returns {{ generated: string, warnings: string[], baseVersionTargeted: string, overlayMode: string }}
+ */
+function mergeOverlay({ kind, name, baseContent, overlayContent, frameworkVersion }) {
+  const warnings = [];
+
+  // Parse overlay frontmatter for metadata.
+  const overlayParsed = parseMarkdown(overlayContent);
+  let overlayMeta = {};
+  if (overlayParsed.frontmatter) {
+    try { overlayMeta = yaml.load(overlayParsed.frontmatter) || {}; }
+    catch (err) {
+      warnings.push(`overlay frontmatter parse error (${err.message}) — treating overlay as plain markdown without metadata`);
+    }
+  }
+  const baseVersionTargeted = String(overlayMeta[`base_${kind}_version`] || '').trim() || 'unknown';
+  const overlayMode = (overlayMeta.mode || 'extend').trim();
+
+  // Parse the base. Keep its frontmatter verbatim — that's what Claude reads.
+  const baseParsed = parseMarkdown(baseContent);
+
+  // Build a heading → section map for the base. If headings repeat we keep
+  // the first occurrence (Claude Code does the same for repeated `name:`).
+  const baseSectionByHeading = new Map();
+  baseParsed.sections.forEach((s, idx) => {
+    if (s.heading && !baseSectionByHeading.has(s.heading)) {
+      baseSectionByHeading.set(s.heading, { ...s, _idx: idx });
+    }
+  });
+
+  // Apply overlay sections.
+  const newSections = baseParsed.sections.map((s) => ({ ...s }));
+  const trailing = []; // overlay sections without marker → custom adds at the end
+
+  for (const ov of overlayParsed.sections) {
+    if (!ov.marker) {
+      trailing.push(ov);
+      continue;
+    }
+    const base = baseSectionByHeading.get(ov.heading);
+    if (!base) {
+      warnings.push(`overlay section "${ov.marker} ${ov.heading}" has no matching H2 in base ${kind} "${name}" — appending as new section instead`);
+      trailing.push({ marker: null, heading: ov.heading, body: ov.body });
+      continue;
+    }
+    const target = newSections[base._idx];
+    if (ov.marker === 'OVERRIDE') {
+      target.body = ov.body;
+    } else if (ov.marker === 'APPEND') {
+      target.body = `${target.body.replace(/\n+$/, '')}\n\n${ov.body}`;
+    } else if (ov.marker === 'PREPEND') {
+      target.body = `${ov.body.replace(/\n+$/, '')}\n\n${target.body}`;
+    }
+  }
+
+  // Compose the merged body.
+  const sectionsOut = rebuildSections(newSections);
+  const trailingOut = trailing.length
+    ? '\n' + trailing.map((s) => `## ${s.heading}\n${s.body}`).join('\n').replace(/\n+$/, '\n')
+    : '';
+
+  const overlaySha = shortSha(overlayContent);
+  const marker = buildMarker({
+    kind,
+    name,
+    baseVersion: frameworkVersion || baseVersionTargeted,
+    overlaySha
+  });
+
+  const fmBlock = baseParsed.frontmatter
+    ? `---\n${baseParsed.frontmatter}\n---\n`
+    : '';
+
+  const generated =
+    `${marker}\n` +
+    fmBlock +
+    (baseParsed.preamble || '') +
+    sectionsOut +
+    trailingOut;
+
+  return {
+    generated,
+    warnings,
+    baseVersionTargeted,
+    overlayMode,
+    overlaySha
+  };
+}
+
+module.exports = {
+  mergeOverlay,
+  readMarker,
+  parseMarkdown,
+  shortSha,
+  MARKER_PREFIX
+};

package/src/utils/symlinks.js

@@ -126,6 +126,9 @@ class SymlinkUtils {
   async createBulkSymlinks(opts = {}) {
     const mode = opts.mode || 'prompt';
 
+    // AGENTS.md and the cross-tool `agents/` reference dir remain BULK
+    // symlinks — they're single canonical artifacts of the framework that
+    // do not need per-item user-overlay behaviour.
     await this.createSymlink(
       path.join(FRAMEWORK_PAYLOAD, 'AGENTS.md'),
       'AGENTS.md',
@@ -140,19 +143,29 @@ class SymlinkUtils {
 
     this.ensureDirectory('.claude');
 
-    // target is relative to cwd; createSymlink converts it to a path relative
-    // to the link's parent directory when `relative: true`.
-    await this.createSymlink(
-      path.join(FRAMEWORK_PAYLOAD, '.claude', 'agents'),
-      path.join('.claude', 'agents'),
-      { relative: true, mode }
-    );
+    // NB: `.claude/agents/` and `.claude/commands/` are NO LONGER bulk
+    // symlinks since v3.8.0 — they're real directories with per-item
+    // symlinks (or overlay-generated real files). Populated by
+    // mergeAgents() and mergeCommands() which createAllSymlinks() invokes
+    // right after this method.
+    this._convertLegacyBulkSymlinkToDir(path.join('.claude', 'agents'));
+    this._convertLegacyBulkSymlinkToDir(path.join('.claude', 'commands'));
+  }
 
-    await this.createSymlink(
-      path.join(FRAMEWORK_PAYLOAD, '.claude', 'commands'),
-      path.join('.claude', 'commands'),
-      { relative: true, mode }
-    );
+  /**
+   * If `rel` exists and is a symlink (the v3.7.x and earlier bulk-symlink
+   * layout for .claude/agents and .claude/commands), unlink it so that the
+   * per-item merge can populate a real directory in its place. Legacy migration.
+   */
+  _convertLegacyBulkSymlinkToDir(rel) {
+    const full = path.join(this.cwd, rel);
+    let lstat = null;
+    try { lstat = fs.lstatSync(full); } catch (_) { /* absent */ }
+    if (lstat && lstat.isSymbolicLink()) {
+      UI.warning(`Detected legacy bulk symlink at ${rel}. Converting to per-item layout (v3.8.0+).`);
+      fs.unlinkSync(full);
+    }
+    this.ensureDirectory(rel);
   }
 
   // -----------------------------------------------------------------------
@@ -305,14 +318,198 @@ class SymlinkUtils {
     this.mergeSkills({ tools: opts.tools });
 
     UI.newline();
+    UI.section('Merging Framework Agents');
+    this.mergeAgents({ tools: opts.tools });
+
+    UI.newline();
+    UI.section('Merging Framework Commands');
+    this.mergeCommands({ tools: opts.tools });
+
+    UI.newline();
+  }
+
+  // -----------------------------------------------------------------------
+  // Per-item merge for agents and commands (v3.8.0+)
+  //
+  // Same model as skills (per-item, user files coexist, broken-symlink-safe)
+  // PLUS overlay support: if `.baldart/overlays/<kind>s/<name>.md` exists,
+  // BALDART generates a real file `.claude/<kind>s/<name>.md` = base + overlay
+  // merged, with a marker header so future updates know it's regeneration-safe.
+  // -----------------------------------------------------------------------
+
+  mergeAgents(opts = {}) { return this._mergeBulkDir('agent', opts); }
+  mergeCommands(opts = {}) { return this._mergeBulkDir('command', opts); }
+
+  /**
+   * Generic per-item merge for kinds whose framework source is a directory
+   * of single .md files (agents, commands). For each enabled tool whose
+   * adapter declares a target directory (claude.agentsDir(), etc.), this
+   * either symlinks each base file or — when an overlay exists — writes a
+   * generated real file with the overlay applied.
+   */
+  _mergeBulkDir(kind, opts = {}) {
+    const tools = (opts.tools && opts.tools.length) ? opts.tools : ['claude'];
+    const aggregate = { linked: [], generated: [], skipped: [], conflicts: [], warnings: [] };
+    const { getAdapter } = require('./tool-adapters');
+
+    const fwSourceDir = path.join(this.cwd, FRAMEWORK_PAYLOAD, '.claude', `${kind}s`);
+    if (!fs.existsSync(fwSourceDir)) {
+      UI.warning(`No framework ${kind}s found at ${path.relative(this.cwd, fwSourceDir)}. Skipping ${kind} merge.`);
+      return aggregate;
+    }
+
+    const fwItems = fs.readdirSync(fwSourceDir)
+      .filter((n) => n.endsWith('.md') && !n.startsWith('.') && n !== 'REGISTRY.md');
+
+    const frameworkVersion = this._readFrameworkVersion();
+
+    for (const tool of tools) {
+      const adapter = getAdapter(tool, this.cwd);
+      const dirGetter = kind === 'agent' ? adapter.agentsDir : adapter.commandsDir;
+      const targetRel = dirGetter ? dirGetter.call(adapter) : null;
+      if (!targetRel) continue; // tool doesn't support this kind (e.g. Codex)
+
+      this.ensureDirectory(targetRel);
+
+      for (const filename of fwItems) {
+        const baseName = filename.replace(/\.md$/, '');
+        const linkPath = path.join(this.cwd, targetRel, filename);
+        const fwAbsolute = path.join(fwSourceDir, filename);
+
+        // Compute the relative-from-link path used by the symlink so it's
+        // portable if the project gets moved.
+        const linkDepth = targetRel.split(path.sep).filter(Boolean).length;
+        const upPath = path.join(...Array(linkDepth).fill('..'));
+        const target = path.join(upPath, FRAMEWORK_PAYLOAD, '.claude', `${kind}s`, filename);
+
+        const overlayRel = path.join('.baldart', 'overlays', `${kind}s`, filename);
+        const overlayAbs = path.join(this.cwd, overlayRel);
+        const hasOverlay = fs.existsSync(overlayAbs);
+
+        // Inspect what currently lives at the link path (if anything).
+        let lstat = null;
+        try { lstat = fs.lstatSync(linkPath); } catch (_) { /* absent */ }
+
+        if (hasOverlay) {
+          // Generate a real file from base + overlay.
+          this._generateOverlayedFile({
+            kind, name: baseName, fwAbsolute, overlayAbs, linkPath, lstat,
+            frameworkVersion, aggregate, adapter, targetRel
+          });
+        } else {
+          // Plain symlink, with broken-symlink recovery (same fix-pattern as v3.5.1).
+          this._installPerItemSymlink({
+            linkPath, target, fwAbsolute, lstat, baseName, filename,
+            aggregate, adapter, targetRel, kind
+          });
+        }
+      }
+    }
+
+    return aggregate;
+  }
+
+  _installPerItemSymlink({ linkPath, target, fwAbsolute, lstat, baseName, filename, aggregate, adapter, targetRel, kind }) {
+    if (!lstat) {
+      fs.symlinkSync(target, linkPath);
+      UI.success(`[${adapter.label}] ${kind} linked: ${path.join(targetRel, filename)}`);
+      aggregate.linked.push({ tool: adapter.name, kind, name: baseName });
+      return;
+    }
+    if (lstat.isSymbolicLink()) {
+      const current = fs.readlinkSync(linkPath);
+      const resolved = path.resolve(path.dirname(linkPath), current);
+      if (current === target || resolved === fwAbsolute) {
+        aggregate.skipped.push({ tool: adapter.name, kind, name: baseName, reason: 'already-linked' });
+        return;
+      }
+      // Broken or pointing elsewhere — replace if broken, else respect user override
+      if (!fs.existsSync(linkPath)) {
+        fs.unlinkSync(linkPath);
+        fs.symlinkSync(target, linkPath);
+        UI.success(`[${adapter.label}] ${kind} re-linked (was broken): ${path.join(targetRel, filename)}`);
+        aggregate.linked.push({ tool: adapter.name, kind, name: baseName });
+        return;
+      }
+      UI.info(`[${adapter.label}] ${kind} kept (user override symlink): ${path.join(targetRel, filename)} → ${current}`);
+      aggregate.skipped.push({ tool: adapter.name, kind, name: baseName, reason: 'user-symlink-override' });
+      return;
+    }
+    // Real file. Could be:
+    //  (a) A baldart-generated file from a previous run where overlay USED to
+    //      exist but now doesn't — safe to replace with symlink.
+    //  (b) A user-authored fork — leave alone.
+    const { readMarker } = require('./overlay-merger');
+    const content = fs.readFileSync(linkPath, 'utf8');
+    const marker = readMarker(content);
+    if (marker && marker.kind === kind && marker.name === baseName) {
+      // Overlay was removed → revert to symlink.
+      UI.info(`[${adapter.label}] ${kind} overlay removed — replacing generated file with symlink: ${path.join(targetRel, filename)}`);
+      fs.unlinkSync(linkPath);
+      fs.symlinkSync(target, linkPath);
+      aggregate.linked.push({ tool: adapter.name, kind, name: baseName });
+      return;
+    }
+    UI.warning(`[${adapter.label}] ${kind} name conflict (user file at ${path.join(targetRel, filename)}). Framework version NOT installed. Move user content to .baldart/overlays/${kind}s/${filename} to specialize without losing upstream updates.`);
+    aggregate.conflicts.push({
+      tool: adapter.name, kind, name: baseName,
+      local_path: path.join(targetRel, filename),
+      framework_path: path.relative(this.cwd, fwAbsolute),
+      detected_at: new Date().toISOString()
+    });
+  }
+
+  _generateOverlayedFile({ kind, name, fwAbsolute, overlayAbs, linkPath, lstat, frameworkVersion, aggregate, adapter, targetRel }) {
+    const { mergeOverlay, readMarker } = require('./overlay-merger');
+    const baseContent = fs.readFileSync(fwAbsolute, 'utf8');
+    const overlayContent = fs.readFileSync(overlayAbs, 'utf8');
+    const merged = mergeOverlay({ kind, name, baseContent, overlayContent, frameworkVersion });
+
+    if (merged.warnings && merged.warnings.length) {
+      merged.warnings.forEach((w) => {
+        UI.warning(`[${adapter.label}] ${kind} ${name}: ${w}`);
+        aggregate.warnings.push({ tool: adapter.name, kind, name, warning: w });
+      });
+    }
+
+    // If a previously generated file is on disk, check ownership via marker
+    // before overwriting. If it lacks the marker (= user edited manually after
+    // a previous generation, or a pre-3.8 fork), refuse to overwrite.
+    if (lstat && !lstat.isSymbolicLink()) {
+      const existing = fs.readFileSync(linkPath, 'utf8');
+      const m = readMarker(existing);
+      if (!m) {
+        UI.warning(`[${adapter.label}] ${kind} ${name}: existing file at ${path.join(targetRel, name)}.md has no baldart-generated marker — NOT overwriting (user fork?). Move it aside (or merge it into the overlay) and re-run update.`);
+        aggregate.conflicts.push({
+          tool: adapter.name, kind, name,
+          local_path: path.join(targetRel, `${name}.md`),
+          reason: 'manual-edit-no-marker',
+          detected_at: new Date().toISOString()
+        });
+        return;
+      }
+    }
+
+    // Replace any existing symlink/file with the freshly generated content.
+    if (lstat) {
+      try { fs.unlinkSync(linkPath); }
+      catch (_) { try { fs.rmSync(linkPath, { recursive: true, force: true }); } catch (_) { /* noop */ } }
+    }
+    fs.writeFileSync(linkPath, merged.generated);
+    UI.success(`[${adapter.label}] ${kind} generated (overlay applied): ${path.join(targetRel, name)}.md`);
+    aggregate.generated.push({ tool: adapter.name, kind, name, overlaySha: merged.overlaySha });
+  }
+
+  _readFrameworkVersion() {
+    const vPath = path.join(this.cwd, FRAMEWORK_DIR, 'VERSION');
+    try { return fs.readFileSync(vPath, 'utf8').trim(); }
+    catch { return 'unknown'; }
   }
 
   verifySymlinks() {
     const bulkSymlinks = [
       'AGENTS.md',
-      'agents',
-      '.claude/agents',
-      '.claude/commands'
+      'agents'
     ];
 
     let allValid = true;
@@ -385,6 +582,39 @@ class SymlinkUtils {
         UI.warning(`[${adapter.label}] Missing: ${skillsRel}/ (the framework would merge skills here)`);
         allValid = false;
       }
+
+      // v3.8.0+: agents and commands also use per-item merge with overlay support.
+      for (const [kindGetter, kindLabel] of [['agentsDir', 'agents'], ['commandsDir', 'commands']]) {
+        if (typeof adapter[kindGetter] !== 'function') continue;
+        const rel = adapter[kindGetter]();
+        if (!rel) continue;
+        const full = path.join(this.cwd, rel);
+        let s = null;
+        try { s = fs.lstatSync(full); } catch (_) { /* absent */ }
+        if (!s) {
+          UI.warning(`[${adapter.label}] Missing: ${rel}/ (framework ${kindLabel} would be merged here)`);
+          allValid = false;
+        } else if (s.isSymbolicLink()) {
+          UI.warning(`[${adapter.label}] Legacy bulk symlink at ${rel}. Run \`npx baldart update\` to convert to per-item layout.`);
+          allValid = false;
+        } else {
+          const entries = fs.readdirSync(full);
+          const frameworkOwned = entries.filter((n) => {
+            const p = path.join(full, n);
+            try {
+              if (fs.lstatSync(p).isSymbolicLink()) return true;
+              const content = fs.readFileSync(p, 'utf8');
+              return content.startsWith('<!-- baldart-generated:');
+            } catch { return false; }
+          });
+          if (frameworkOwned.length === 0) {
+            UI.warning(`[${adapter.label}] ${rel}/ has no framework-managed ${kindLabel}. Run \`npx baldart update\`.`);
+            allValid = false;
+          } else {
+            UI.success(`[${adapter.label}] Valid: ${rel}/ (${frameworkOwned.length} framework-managed ${kindLabel})`);
+          }
+        }
+      }
     }
 
     // Project configuration (v3.0.0+)

package/src/utils/tool-adapters/claude.js

@@ -21,6 +21,12 @@ class ClaudeAdapter {
   /** Where this tool reads skill bundles from. */
   skillsDir() { return '.claude/skills'; }
 
+  /** Where this tool reads subagent definitions from (null if unsupported). */
+  agentsDir() { return '.claude/agents'; }
+
+  /** Where this tool reads slash commands from (null if unsupported). */
+  commandsDir() { return '.claude/commands'; }
+
   /** Whether this tool consumes subagent definitions (`.claude/agents/`). */
   supportsSubagents() { return true; }
 

package/src/utils/tool-adapters/codex.js

@@ -33,6 +33,13 @@ class CodexAdapter {
 
   skillsDir() { return '.agents/skills'; }
 
+  // Codex has no equivalent of Claude subagents or slash commands (custom
+  // prompts are deprecated in favor of skills). Returning null disables the
+  // per-item merge for those kinds — adapters that DO support them return
+  // the target directory string.
+  agentsDir() { return null; }
+  commandsDir() { return null; }
+
   supportsSubagents() { return false; }
   supportsSlashCommands() { return false; }
   supportsHooks() { return false; }