baldart 3.8.0 → 3.8.1

package/CHANGELOG.md

@@ -5,6 +5,17 @@ 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/`.

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.1

package/package.json

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