baldart 3.8.0 → 3.8.2

package/CHANGELOG.md

@@ -5,6 +5,27 @@ 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.2] - 2026-05-22
+
+`baldart` (smart doctor) no longer double-confirms safe actions. Previously, running `baldart` with a remote-ahead state would ask *"Run: Pull N commit(s)?"* and then the `update` command would ask *"Proceed with update?"* immediately after — two prompts for the same intent.
+
+### Fixed
+
+- **`src/commands/doctor.js` action runner** — every action now carries an `autoOk` flag. Safe & idempotent actions (`update`, `configure*`, `migrate`, `register-edit-gate`) run without the outer doctor confirmation (their own internal prompts take over). Actions that change external state or need explicit version classification (`add`, `push`) keep the outer confirmation so the user signals intent explicitly.
+
+Result: `baldart` in a repo with "remote ahead" now goes straight into the update flow (with its own pre-flight stash + diff preview + proceed prompt), instead of double-asking.
+
+## [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/`.

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.8.0
+3.8.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "baldart",
-  "version": "3.8.0",
+  "version": "3.8.2",
   "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

@@ -228,11 +228,19 @@ function planActions(state) {
     return actions;
   }
 
+  // `autoOk` policy:
+  //   - true  → safe & idempotent action that has its own internal prompts
+  //             (update, configure, migrate, hook register). The outer doctor
+  //             prompt would be a redundant double-confirmation, so we skip it.
+  //   - false → state-changing action that warrants explicit intent at the
+  //             doctor level (add = first install, push = writes to remote
+  //             and triggers a version-classification dialog).
   if (!state.frameworkPresent) {
     actions.push({
       key: 'add',
       label: 'Install BALDART framework',
       why: 'No .framework/ directory found in this repo.',
+      autoOk: false,
       run: async () => {
         const add = require('./add');
         await add(REPO_DEFAULT, { branch: 'main' });
@@ -246,6 +254,7 @@ function planActions(state) {
       key: 'migrate',
       label: 'Migrate legacy v2.0.x layout',
       why: '.claude/skills/ is a bulk symlink — v2.0.x layout. v2.1.1+ uses per-item merge.',
+      autoOk: true,
       run: () => require('./migrate')(),
     });
     return actions;
@@ -256,6 +265,7 @@ function planActions(state) {
       key: 'configure-malformed',
       label: 'Rewrite baldart.config.yml (current file is malformed)',
       why: 'Existing baldart.config.yml is not valid YAML — re-running configure will rebuild it.',
+      autoOk: true,
       run: () => require('./configure')(),
     });
     return actions;
@@ -266,6 +276,7 @@ function planActions(state) {
       key: 'configure',
       label: 'Generate baldart.config.yml',
       why: 'Skills require a config to resolve project-specific paths/identity/stack. Without it they will prompt on every invocation.',
+      autoOk: true,
       run: () => require('./configure')(),
     });
     return actions;
@@ -276,6 +287,7 @@ function planActions(state) {
       key: 'configure-drift',
       label: `Refresh baldart.config.yml (${state.configSchemaMissing.length} new key(s) from framework template)`,
       why: 'Framework added config keys this consumer doesn\'t yet declare: ' + state.configSchemaMissing.join(', '),
+      autoOk: true,
       run: () => require('./configure')(),
     });
     // Drift is non-blocking — keep checking for other actions after.
@@ -286,6 +298,7 @@ function planActions(state) {
       key: 'register-edit-gate',
       label: 'Register framework-edit-gate hook (.claude/settings.json)',
       why: 'Prevents project-specific tokens (Neo-Brutalism, merchant, …) from being written to .framework/ accidentally. Standard in v3.3.0+; missing on installs predating that version.',
+      autoOk: true,
       run: async () => {
         const res = require('../utils/hooks').register();
         UI.success(`Hook registered: ${res.status} (${res.path})`);
@@ -301,6 +314,7 @@ function planActions(state) {
       key: 'update',
       label: `Pull ${state.remote.behind} commit(s) from upstream`,
       why: 'Remote framework is ahead of your local copy. Updating first keeps your contributions on a fresh base.',
+      autoOk: true, // update has its own internal "Proceed?" prompt + pre-flight stash
       run: () => require('./update')(),
     });
   }
@@ -312,6 +326,7 @@ function planActions(state) {
       why: state.workingTreeDirty
         ? `${state.workingTreeDirty} uncommitted file(s) in .framework/ — commit them through \`baldart push\`.`
         : `${state.commitsAhead} commit(s) on .framework/ not yet pushed.`,
+      autoOk: false, // push writes to remote and asks for version classification — keep explicit intent
       run: () => require('./push')(),
     });
   }
@@ -472,7 +487,16 @@ async function doctor(opts = {}) {
   for (const action of actions) {
     let proceed = auto;
     if (!auto) {
-      proceed = await UI.confirm(`Run: ${action.label}?`, true);
+      // Safe & idempotent actions (`autoOk: true`) run without an outer
+      // confirmation — they have their own internal prompts. Actions that
+      // change external state or require explicit version classification
+      // (add, push) still ask here so the user signals intent.
+      if (action.autoOk) {
+        UI.info(`→ Running: ${action.label}`);
+        proceed = true;
+      } else {
+        proceed = await UI.confirm(`Run: ${action.label}?`, true);
+      }
     }
     if (!proceed) {
       UI.info(`Skipped: ${action.label}`);