baldart 3.31.0 → 3.32.0

package/CHANGELOG.md

@@ -5,6 +5,25 @@ 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.32.0] - 2026-05-30
+
+Makes the CLI **agent-native at the output layer**: `npx baldart version --json` and `npx baldart update --json --yes` now emit a single **machine-readable JSON object** on stdout (schemas `baldart.version/1` / `baldart.update/1`), with every human line routed to stderr. This closes the last fragile seam in the autonomous-update path — the `/baldart-update` skill previously had to **regex-scrape human-readable prose** (the v3.26.0 wording change had already forced a dual-format tolerant parser in Step 0). An agent now reads a field instead of matching a sentence. Borrowed from the [CLI-Anything](https://github.com/HKUDS/CLI-Anything) philosophy (`--json` on every command) — but BALDART is already a headless CLI, so this is a thin, hand-rolled output layer, not a generated wrapper. **No new `baldart.config.yml` keys** — `--json` is a CLI flag, not a config key, so the schema-propagation rule does not apply.
+
+### Added — `--json` structured output
+
+- **[src/commands/version.js](src/commands/version.js)**: `--json` emits `{schema:"baldart.version/1", installed, installed_version, remote_version, aligned, offline, fetched, uncommitted_files, commits_ahead/behind, cli_version, cli_latest, cli_update_available, repository, last_update_date, last_pushed_version, last_push_date}` — exactly the facts the human box shows. Framework-not-installed and error paths emit `{installed:false|null, error, …}` so the agent always gets parseable stdout.
+- **[src/commands/update.js](src/commands/update.js)**: `--json` emits a single `{schema:"baldart.update/1", ok, action, …}` result at **every** terminal point through one `emitUpdateJson` chokepoint (all-or-nothing: a missed exit would leave stdout empty). `ok:true` ⟺ the framework is now at the remote version (`action` `updated` / `already-current`); every refusal/failure is `ok:false` with `action` (`divergence-refused`, `divergence-scaffolded`, `aborted`, `failed`, `framework-missing`, `usage-error`), `reason`, and a `next_command` the human can re-run. `--json` **requires `--yes`** (so no prompt can block) and **rejects `--reset`** (the nuclear path stays an interactive human escape hatch).
+- **[src/utils/ui.js](src/utils/ui.js)**: new `UI.setJsonMode(on)` redirects every `console.log` the UI helpers emit to **stderr** (reversible), keeping stdout clean for the JSON. `ora` spinners already write to stderr, so they need no change. The JSON itself is written with `process.stdout.write`, never `console.log`, so it survives the redirect.
+
+### Changed — autonomous `/baldart-update` reads JSON, not prose
+
+- **[framework/.claude/skills/baldart-update/SKILL.md](framework/.claude/skills/baldart-update/SKILL.md)**: Step 0 now **prefers** `version --json` (field reads) and **falls back** to the dual-format text parser when the global CLI predates v3.32.0 (`--json` unknown / non-JSON stdout) — the same "new skill + old global CLI" transition window the text parser already guards. Autonomous mode runs `update --json --yes`, parses the single result object (`ok` / `action` / `installed_after` / `backup_tag` / `next_command`), and keeps the **exit code as the safety backstop**. The post-flight assert cross-checks `installed_after` against on-disk `.framework/VERSION` and the Step 0 `remote_version`. `last_verified` v3.31.0 → v3.32.0; added a **JSON-OUTPUT NOTE** recording that `--json` is a flag, not a config key.
+
+### Fixed — self-relaunch flag forwarding
+
+- **[src/commands/update.js](src/commands/update.js)** `maybeRelaunchUnderLatest`: the stale-CLI self-relaunch now forwards `--json` **and** `--on-divergence <strategy>` to the `npx baldart@latest` child. The latter was a pre-existing latent drop (an agent's non-interactive divergence strategy would silently vanish on relaunch); both are fixed together.
+- **[bin/baldart.js](bin/baldart.js)**: the CLI self-update notifier's stdout `announce` is suppressed under `--json` so it cannot pollute the single JSON object.
+
 ## [3.31.0] - 2026-05-30
 
 Gives `/baldart-update` an **autonomous mode** so agents and scheduled routines can bring the framework up-to-date with **zero human interaction** — closing the gap that the skill, as shipped, was *purely* human-in-the-loop (it replicated every CLI decision point as a chat confirmation, which an unattended agent cannot answer). The new mode is **auto-detected** from a positive automation signal and keeps every one of the CLI's safety gates: it drives `npx baldart update --yes` and **stops hard** (never forces a merge or reset) the moment the CLI refuses on custom divergence or a conflict — exactly the calls a human should own. **No new `baldart.config.yml` keys** — `BALDART_AUTONOMOUS` is a runtime env var, not a config flag, so the schema-propagation rule does not apply.

package/README.md

@@ -456,6 +456,14 @@ Update framework to latest version.
 - Updates via Git subtree
 - Verifies symlinks
 
+**For agents / CI (v3.32.0+):** `npx baldart update --json --yes` emits a single
+machine-readable result object on stdout (`{schema:"baldart.update/1", ok,
+action, installed_after, backup_tag, next_command, …}`) with all human output on
+stderr — no prose to scrape. `ok:true` ⟺ the framework is now at the remote
+version. `--json` requires `--yes` and rejects `--reset`. Pair with
+`--on-divergence pull|scaffold-overlays|abort` for non-interactive divergence
+resolution.
+
 ### `npx baldart` (no args) / `doctor` (v3.2.0+)
 
 Smart diagnostic that detects the install state and proposes the next sensible
@@ -474,7 +482,10 @@ npx baldart doctor     # explicit alias (same behaviour)
 
 Show installed framework version, install date, drift from remote (commits
 ahead/behind), uncommitted-files count in `.framework/`, and last-push info.
-Use `--offline` to skip the upstream fetch when offline.
+Use `--offline` to skip the upstream fetch when offline. Use `--json`
+(v3.32.0+) for a machine-readable object (`schema:"baldart.version/1"`) on
+stdout — agents read `installed_version` / `remote_version` / `aligned`
+instead of scraping the human box.
 
 ### `npx baldart push` / `/baldart-push` (v3.1.0+)
 

package/VERSION

@@ -1 +1 @@
-3.31.0
+3.32.0

package/bin/baldart.js

@@ -43,10 +43,16 @@ const CLI_VERSION = resolveVersion();
 // command on a network call.
 const rawArgsForNotifier = process.argv.slice(2);
 const offlineForNotifier = rawArgsForNotifier.includes('--offline');
-updateNotifier.announceAndRefresh({
-  currentVersion: CLI_VERSION,
-  offline: offlineForNotifier,
-});
+// In --json mode STDOUT must carry exactly one JSON object — the notifier hint
+// would pollute it. Suppress the announce entirely (the refresh is harmless but
+// the announce prints to stdout). (v3.32.0+)
+const jsonForNotifier = rawArgsForNotifier.includes('--json');
+if (!jsonForNotifier) {
+  updateNotifier.announceAndRefresh({
+    currentVersion: CLI_VERSION,
+    offline: offlineForNotifier,
+  });
+}
 
 const program = new Command();
 
@@ -73,6 +79,7 @@ program
   .option('--reset', 'Nuclear option: rm -rf .framework/ + fresh install, preserving baldart.config.yml + .baldart/ + custom .claude/{agents,skills,commands}/. Requires clean working tree.')
   .option('--i-know', 'Acknowledges --reset will wipe untracked/ignored files inside .framework/ (required to use --reset --yes).')
   .option('--on-divergence <strategy>', 'Non-interactive resolution when the consumer has local commits on .framework/ (for agents / CI): "scaffold-overlays" (auto-create overlay skeletons, then stop), "pull" (keep commits + merge — non-destructive), or "abort".')
+  .option('--json', 'Machine-readable output (agents / CI): emit a single JSON result object on stdout, route all human output to stderr. Requires --yes (non-interactive); rejects --reset.')
   .action(async (options) => {
     const updateCommand = require('../src/commands/update');
     await updateCommand(options);
@@ -90,9 +97,10 @@ program
   .command('version')
   .description('Show installed framework version + drift from remote + last-push info')
   .option('--offline', 'Skip the upstream fetch (no remote drift report)')
+  .option('--json', 'Machine-readable output: emit a single JSON object on stdout, route human output to stderr (for agents / CI).')
   .action(async (options) => {
     const versionCommand = require('../src/commands/version');
-    await versionCommand({ offline: !!options.offline });
+    await versionCommand({ offline: !!options.offline, json: !!options.json });
   });
 
 program

package/framework/.claude/skills/baldart-update/SKILL.md

@@ -15,7 +15,17 @@ this skill needs an update is left to a human reviewer.
 update_js_prompts: 6
 hook_registry_entries: 4
 config_template_top_level_keys: features,git,identity,lsp,paths,stack,tools,version
-last_verified: v3.31.0
+last_verified: v3.32.0
+-->
+
+<!--
+JSON-OUTPUT NOTE (v3.32.0)
+`npx baldart version --json` and `npx baldart update --json --yes` emit a single
+machine-readable object on stdout (schemas `baldart.version/1` /
+`baldart.update/1`), with all human output on stderr. The skill PREFERS these
+over regex-scraping prose, but keeps the text parser as a fallback for the
+"new skill + old global CLI" transition window. `--json` is a CLI FLAG, not a
+baldart.config.yml key — the schema-change propagation rule does NOT apply.
 -->
 
 <!--
@@ -116,27 +126,46 @@ touches the user's custom content.**
    global CLI crossing the v3.27.0 payload boundary → STOP and report; do not
    launch).
    - Aligned / already up-to-date → report "already current", exit success.
-2. **Launch directly — no preview/stash confirmation:**
+2. **Launch directly — no preview/stash confirmation. Prefer `--json`
+   (v3.32.0+) so the result is a parseable object, not prose:**
    ```bash
-   npx baldart update --yes
+   npx baldart update --json --yes
    ```
    Use the Bash tool with `timeout: 600000`. `--yes` implies `--auto-stash`,
-   so a dirty tree is handled (stashed + re-applied) without asking.
+   so a dirty tree is handled (stashed + re-applied) without asking. `--json`
+   requires `--yes` (it refuses interactively) and routes all human output to
+   stderr — **stdout carries exactly one JSON object**.
    **Do NOT add `--on-divergence pull` or `--reset`.** Bare `--yes` is the
    safe ceiling: the CLI auto-resolves only mechanical noise and *refuses*
    (exits non-zero) on real custom divergence.
-3. **Interpret the exit code (the whole point of staying safe):**
-   - **Exit 0** → update applied (or already aligned). Go to post-flight.
-   - **Exit non-zero** → the CLI hit a wall it will not cross unattended:
-     custom-overlay-able / real-custom divergence, a subtree-pull conflict, or
-     a stale-CLI halt. **STOP. Do NOT retry with `--on-divergence` or
-     `--reset`.** Report loudly (see below) so the human who reads the routine
-     log knows exactly what needs a hands-on decision. Forcing a merge or a
-     reset unattended is precisely the silent destruction this mode forbids.
+
+   **Fallback:** if the CLI predates v3.32.0 it rejects `--json` (unknown
+   option, non-zero exit, empty/garbled stdout). Re-run without it
+   (`npx baldart update --yes`) and fall back to exit-code + stdout-grep
+   interpretation. Never let a missing `--json` block the update.
+3. **Interpret the result — JSON first, exit code as the safety backstop:**
+   - With `--json`, parse the single stdout object. `ok === true` (action
+     `updated` or `already-current`) → success, go to post-flight using
+     `installed_after` / `backup_tag`. `ok === false` → the CLI refused or
+     failed; read `action` (`divergence-refused`, `divergence-scaffolded`,
+     `failed`, `framework-missing`, `usage-error`), `reason`, and
+     `next_command`. Report them verbatim.
+   - The **exit code is still the contract** regardless of `--json`:
+     - **Exit 0** → update applied (or already aligned). Go to post-flight.
+     - **Exit non-zero** → the CLI hit a wall it will not cross unattended:
+       custom-overlay-able / real-custom divergence, a subtree-pull conflict, or
+       a stale-CLI halt. **STOP. Do NOT retry with `--on-divergence` or
+       `--reset`.** Surface the JSON `reason` + `next_command` (or, in fallback
+       mode, the verbatim stderr) so the human who reads the routine log knows
+       exactly what needs a hands-on decision. Forcing a merge or a reset
+       unattended is precisely the silent destruction this mode forbids.
 4. **Post-flight assert (MANDATORY)** — identical to interactive Step 4:
    `cat .framework/VERSION`, compare to the pre-update version. If the CLI
    exited 0 but VERSION did not change (and stdout is not "Already up to
-   date"), **FAIL LOUD** — do not report success.
+   date"), **FAIL LOUD** — do not report success. With `--json` this is a
+   direct check: the result's `installed_after` MUST equal both
+   `.framework/VERSION` and the Step 0 `remote_version`; any mismatch (e.g.
+   `ok:true` but `installed_after` ≠ on-disk VERSION) is the same FAIL LOUD.
 5. **Report** — emit a structured, log-friendly summary (no questions):
    version delta, backup tag + rollback command, any agent-layout migration
    (v3.27.0+), and — on a non-zero exit — the verbatim CLI stderr plus the
@@ -260,7 +289,36 @@ post-flight assert:
 npx baldart version
 ```
 
-**Parser tollerante** — the output format changed in v3.26.0 (version-compare
+#### Preferred: structured `--json` (v3.32.0+) — NO regex
+
+As of v3.32.0 the CLI emits a machine-readable object — read fields instead
+of scraping prose:
+
+```bash
+npx baldart version --json 2>/dev/null
+# → {"schema":"baldart.version/1","installed":true,"installed_version":"3.32.0",
+#    "remote_version":"3.33.0","aligned":false,"offline":false,"fetched":true,
+#    "uncommitted_files":0,"cli_version":"3.32.0","cli_latest":null,
+#    "cli_update_available":false,"repository":"https://github.com/antbald/BALDART",...}
+```
+
+Decision logic on the JSON:
+- `installed === false` → framework not installed → STOP, instruct `npx baldart add`.
+- `aligned === true` → already up-to-date (`installed_version`). STOP.
+- `aligned === false` AND `remote_version !== "unknown"` → continue (save
+  `installed_version` for the post-flight assert, `remote_version` as target).
+- `offline === true` / `fetched === false` → ask the user how to proceed.
+- Still apply the **CLI version drift gate** below using `cli_version` /
+  `cli_latest` (same semver logic).
+
+**Fallback (BLOCKING for the transition window):** if `version --json` errors
+(non-zero exit, unknown-option message, or stdout that is NOT valid JSON), the
+global CLI predates v3.32.0. Do **not** abort — fall back to the **Parser
+tollerante** below, which scrapes the human-readable output. This is the same
+"new skill + old global CLI" case the dual-format text parser already exists
+for. Never remove the text parser.
+
+**Parser tollerante (fallback)** — the output format changed in v3.26.0 (version-compare
 authority instead of subtree-merge commit count). The skill must accept BOTH
 the new and legacy formats so it works during the transition window where
 the consumer has the new skill but an older global CLI.

package/package.json

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

package/src/commands/update.js

@@ -28,6 +28,20 @@ function readEnabledTools(cwd = process.cwd()) {
 // agent-overlay feedback that prompted this).
 const DIVERGENCE_STRATEGIES = ['abort', 'pull', 'scaffold-overlays'];
 
+// Machine-readable result channel (v3.32.0+). When --json is active, STDOUT
+// must carry exactly ONE JSON object and nothing else — UI.setJsonMode() has
+// already redirected every human line to STDERR. Every terminal point in the
+// standard flow routes through `emitUpdateJson` so the contract holds: one
+// object, then exit. `ok: true` means "framework is now at the remote version"
+// (action `updated` or `already-current`); everything else is `ok: false`.
+let JSON_MODE = false;
+function emitUpdateJson(obj, exitCode) {
+  if (JSON_MODE) {
+    process.stdout.write(JSON.stringify({ schema: 'baldart.update/1', ...obj }) + '\n');
+  }
+  process.exit(exitCode);
+}
+
 // Map a touched framework path to an `overlay scaffold` target string.
 //   .framework/framework/.claude/agents/coder.md     → 'agents/coder'
 //   .framework/framework/.claude/commands/check.md    → 'commands/check'
@@ -394,6 +408,10 @@ async function maybeRelaunchUnderLatest(options) {
   if (options.commit === false) flags.push('--no-commit');
   if (options.reset === true) flags.push('--reset');
   if (options.iKnow === true) flags.push('--i-know');
+  // Forward the non-interactive resolution + machine-readable flags too, else
+  // a stale-CLI self-relaunch would silently drop them (v3.32.0+).
+  if (options.onDivergence) flags.push('--on-divergence', options.onDivergence);
+  if (options.json === true) flags.push('--json');
 
   const spawn = require('child_process').spawnSync;
   UI.info(`Auto-relaunching via npx baldart@${info.latest}…`);
@@ -421,10 +439,31 @@ async function update(options = {}) {
   const autoStash = autoYes || options.autoStash === true;
   const confirm = async (msg, def = true) => (autoYes ? def : UI.confirm(msg, def));
 
+  // Machine-readable mode (v3.32.0+). Must be fully non-interactive: --json
+  // requires --yes (so no UI.select/confirm can block) and rejects --reset
+  // (the nuclear path is a deliberate destructive human escape hatch, not an
+  // agent flow — see the autonomous /baldart-update skill, which never resets).
+  JSON_MODE = options.json === true;
+  if (JSON_MODE) {
+    UI.setJsonMode(true);
+    if (options.reset === true) {
+      emitUpdateJson({ ok: false, action: 'usage-error',
+        reason: '--json does not support --reset. Reset is an interactive destructive escape hatch; run it manually.' }, 2);
+    }
+    if (!autoYes) {
+      emitUpdateJson({ ok: false, action: 'usage-error',
+        reason: '--json requires --yes (non-interactive). Re-run: npx baldart update --json --yes [--on-divergence pull|scaffold-overlays]' }, 2);
+    }
+  }
+
   // Non-interactive divergence strategy (since v3.29.0). Validated up-front so
   // a typo fails fast instead of mid-flow after the network fetch.
   const divStrategy = options.onDivergence;
   if (divStrategy !== undefined && !DIVERGENCE_STRATEGIES.includes(divStrategy)) {
+    if (JSON_MODE) {
+      emitUpdateJson({ ok: false, action: 'usage-error',
+        reason: `Invalid --on-divergence "${divStrategy}". Use one of: ${DIVERGENCE_STRATEGIES.join(', ')}.` }, 1);
+    }
     UI.error(`Invalid --on-divergence "${divStrategy}". Use one of: ${DIVERGENCE_STRATEGIES.join(', ')}.`);
     process.exit(1);
   }
@@ -443,7 +482,9 @@ async function update(options = {}) {
         'Solution:',
         '  Install first: npx baldart add'
       ]);
-      process.exit(1);
+      emitUpdateJson({ ok: false, action: 'framework-missing',
+        reason: 'Framework directory .framework/ not found.',
+        next_command: 'npx baldart add' }, 1);
     }
 
     // v3.26.0+ NUCLEAR OPTION: --reset rips out .framework/ and reinstalls
@@ -480,7 +521,8 @@ async function update(options = {}) {
           UI.error('.framework/ is STILL ignored after auto-heal — likely a parent-dir .gitignore outside this repo.');
           UI.info(`Source: ${heal.recheck.source}:${heal.recheck.line} (${heal.recheck.pattern})`);
           UI.info('Resolve by removing that rule, then re-run `baldart update`.');
-          process.exit(1);
+          emitUpdateJson({ ok: false, action: 'failed',
+            reason: `.framework/ is still ignored after auto-heal (${heal.recheck.source}:${heal.recheck.line}). Remove that .gitignore rule and re-run.` }, 1);
         }
       }
     } catch (err) {
@@ -512,19 +554,24 @@ async function update(options = {}) {
         '  • Check internet connection',
         '  • Try again later'
       ]);
-      process.exit(1);
+      emitUpdateJson({ ok: false, action: 'connect-failed',
+        reason: 'Cannot connect to repository (network / access).' }, 1);
     }
 
     if (!status.fetched || !status.hasFetchHead) {
       UI.error('Could not fetch upstream — try again with network access.');
-      process.exit(1);
+      emitUpdateJson({ ok: false, action: 'fetch-failed',
+        reason: 'Could not fetch upstream — try again with network access.' }, 1);
     }
 
     // VERSION-compare authority. Subtree-merge commit count is noise; never
     // use behind > 0 as the up-to-date signal (root cause of v3.24.x bug).
     if (status.isAligned) {
       UI.success(`Already up to date! (v${status.installedVersion})`);
-      process.exit(0);
+      emitUpdateJson({ ok: true, action: 'already-current',
+        installed_before: status.installedVersion,
+        installed_after: status.installedVersion,
+        remote_version: status.remoteVersion }, 0);
     }
 
     UI.warning(`Update available: v${status.installedVersion} → v${status.remoteVersion}`);
@@ -556,9 +603,18 @@ async function update(options = {}) {
             'Then complete the update with `npx baldart update --reset --yes --i-know` — this discards the now-redundant `.framework/` edits and reinstalls clean; your `.baldart/overlays/` are preserved and re-applied.',
             'Alternatively, push the edits upstream with `/baldart-push` if they are generic improvements.',
           ], 'cyan');
-          process.exit(0);
+          emitUpdateJson({ ok: false, action: 'divergence-scaffolded',
+            divergence_class: status.divergenceClass,
+            installed_before: status.installedVersion, remote_version: status.remoteVersion,
+            reason: 'Scaffolded overlay skeleton(s); fill them in, then re-run.',
+            next_command: 'npx baldart update --reset --yes --i-know' }, 0);
+        }
+        if (divStrategy === 'abort') {
+          UI.info('Update cancelled (--on-divergence abort).');
+          emitUpdateJson({ ok: false, action: 'aborted',
+            divergence_class: status.divergenceClass,
+            reason: 'Update cancelled (--on-divergence abort).' }, 0);
         }
-        if (divStrategy === 'abort') { UI.info('Update cancelled (--on-divergence abort).'); process.exit(0); }
         if (divStrategy === 'pull') {
           UI.info('Keeping the custom commits (--on-divergence pull). The subtree pull will attempt a merge.');
           // fall through
@@ -572,7 +628,11 @@ async function update(options = {}) {
             '--on-divergence pull               → keep the commits and merge the update (non-destructive)',
             '--reset --yes --i-know             → discard .framework/ edits and reinstall clean (destructive)',
           ], 'cyan');
-          process.exit(1);
+          emitUpdateJson({ ok: false, action: 'divergence-refused',
+            divergence_class: status.divergenceClass,
+            installed_before: status.installedVersion, remote_version: status.remoteVersion,
+            reason: 'Custom edits present — refusing to resolve them unattended under --yes.',
+            next_command: 'npx baldart update --json --yes --on-divergence scaffold-overlays' }, 1);
         } else {
           const choice = await UI.select('How would you like to proceed?', [
             { name: 'Scaffold overlay skeleton(s) now (recommended — then fill them in & re-run)', value: 'overlay' },
@@ -605,16 +665,29 @@ async function update(options = {}) {
           if (overlayCommits.length === 0) {
             UI.error('No overlay-able commits to scaffold — every custom commit touches non-overlayable paths (src/, CHANGELOG, …).');
             UI.info('Use `/baldart-push` to contribute them upstream, or `--on-divergence pull` to merge.');
-            process.exit(1);
+            emitUpdateJson({ ok: false, action: 'divergence-refused',
+              divergence_class: status.divergenceClass,
+              installed_before: status.installedVersion, remote_version: status.remoteVersion,
+              reason: 'No overlay-able commits to scaffold — every custom commit touches non-overlayable paths.',
+              next_command: 'npx baldart update --json --yes --on-divergence pull' }, 1);
           }
           UI.newline();
           scaffoldOverlaysForCommits(overlayCommits);
           UI.newline();
           UI.warning('Scaffolded overlays for the overlay-able commits, but custom-other commit(s) remain — NOT pulling (would be destructive to those edits).');
           UI.info('Resolve the remaining commits (push upstream with `/baldart-push`, or revert), then re-run `npx baldart update`.');
-          process.exit(0);
+          emitUpdateJson({ ok: false, action: 'divergence-scaffolded',
+            divergence_class: status.divergenceClass,
+            installed_before: status.installedVersion, remote_version: status.remoteVersion,
+            reason: 'Scaffolded overlay-able subset; custom-other commit(s) still need handling before pulling.',
+            next_command: 'npx baldart update --json --yes' }, 0);
+        }
+        if (divStrategy === 'abort') {
+          UI.info('Update cancelled (--on-divergence abort).');
+          emitUpdateJson({ ok: false, action: 'aborted',
+            divergence_class: status.divergenceClass,
+            reason: 'Update cancelled (--on-divergence abort).' }, 0);
         }
-        if (divStrategy === 'abort') { UI.info('Update cancelled (--on-divergence abort).'); process.exit(0); }
         if (divStrategy === 'pull') {
           UI.info('Pulling over the custom commits (--on-divergence pull). A merge commit will be created — resolve any conflicts that surface.');
           // fall through
@@ -627,7 +700,11 @@ async function update(options = {}) {
             '--on-divergence abort              → do nothing',
           ], 'cyan');
           UI.info('Best practice: contribute generic improvements upstream first with `/baldart-push`.');
-          process.exit(1);
+          emitUpdateJson({ ok: false, action: 'divergence-refused',
+            divergence_class: status.divergenceClass,
+            installed_before: status.installedVersion, remote_version: status.remoteVersion,
+            reason: 'Custom commits present — refusing to pull over them unattended under --yes.',
+            next_command: 'npx baldart update --json --yes --on-divergence pull' }, 1);
         } else {
           const choice = await UI.select('How would you like to proceed?', [
             { name: 'Push these commits upstream first (recommended — `/baldart-push`)', value: 'push' },
@@ -669,6 +746,7 @@ async function update(options = {}) {
     // "fatal: working tree has modifications. Cannot add." Offer to stash
     // and re-apply after the update, so the user doesn't have to abort mid-flow.
     let stashRef = null;
+    let stashConflict = false; // surfaced in the --json result (v3.32.0+)
     const isClean = await git.hasCleanWorkingTree();
     if (!isClean) {
       UI.newline();
@@ -703,7 +781,8 @@ async function update(options = {}) {
         UI.success(`Stashed working tree as "${stashRef}".`);
       } catch (err) {
         UI.error(`Could not stash: ${err.message}`);
-        process.exit(1);
+        emitUpdateJson({ ok: false, action: 'failed',
+          reason: `Could not stash working tree before update: ${err.message}` }, 1);
       }
     }
 
@@ -756,6 +835,7 @@ async function update(options = {}) {
           await git.git.stash(['pop']);
           UI.success(`Re-applied pre-update stash "${stashRef}".`);
         } catch (err) {
+          stashConflict = true;
           UI.newline();
           UI.warning(`Could not auto-re-apply stash "${stashRef}" — conflicts with the framework update.`);
           UI.box('STASH CONFLICT', [
@@ -1006,7 +1086,15 @@ async function update(options = {}) {
     UI.newline();
     UI.success('Framework updated successfully!');
 
+    emitUpdateJson({ ok: true, action: 'updated',
+      installed_before: currentVersion, installed_after: newVersion,
+      remote_version: status.remoteVersion, backup_tag: backupTag,
+      stash_conflict: stashConflict }, 0);
+
   } catch (error) {
+    if (JSON_MODE) {
+      emitUpdateJson({ ok: false, action: 'failed', reason: error.message }, 1);
+    }
     UI.error(`Update failed: ${error.message}`);
     process.exit(1);
   }

package/src/commands/version.js

@@ -30,12 +30,25 @@ async function describeDrift(git, status) {
   };
 }
 
+// Emit a structured JSON object on stdout (v3.32.0+). Used by agents / CI to
+// avoid scraping the human-readable box with fragile regex. Schema is
+// versioned (`baldart.version/1`) so consumers can detect breaking changes.
+function emitVersionJson(obj) {
+  process.stdout.write(JSON.stringify({ schema: 'baldart.version/1', ...obj }) + '\n');
+}
+
 async function version(opts = {}) {
   const git = new GitUtils();
+  const jsonMode = opts.json === true;
+  if (jsonMode) UI.setJsonMode(true);
 
   try {
     const exists = await git.frameworkExists();
     if (!exists) {
+      if (jsonMode) {
+        emitVersionJson({ installed: false, error: 'framework_not_installed' });
+        process.exit(0);
+      }
       UI.warning('Framework not installed');
       UI.info('Install with: npx baldart add');
       process.exit(0);
@@ -63,6 +76,31 @@ async function version(opts = {}) {
     }
     const drift = await describeDrift(git, status);
 
+    // Machine-readable path (v3.32.0+) — emit the structured object and stop.
+    // Mirrors exactly the facts the human box shows below, so the autonomous
+    // /baldart-update skill can read fields instead of regex-scraping prose.
+    if (jsonMode) {
+      emitVersionJson({
+        installed: true,
+        installed_version: frameworkVersion,
+        remote_version: drift.remoteVersion, // string version, or 'unknown'
+        aligned: drift.isAligned,
+        offline: opts.offline === true || !drift.hasFetchHead,
+        fetched: drift.hasFetchHead,
+        uncommitted_files: drift.uncommittedFiles,
+        commits_ahead: drift.ahead,
+        commits_behind: drift.behind,
+        cli_version: cliVersion,
+        cli_latest: cliUpdate ? cliUpdate.latest : null,
+        cli_update_available: !!cliUpdate,
+        repository: `https://github.com/${repo}`,
+        last_update_date: state.last_update_date || null,
+        last_pushed_version: state.last_pushed_version || null,
+        last_push_date: state.last_push_date || null,
+      });
+      return;
+    }
+
     // Messaging based on `isAligned` (not commit count, which is subtree noise).
     let remoteLine;
     if (!drift.hasFetchHead) {
@@ -103,6 +141,10 @@ async function version(opts = {}) {
     UI.box('BALDART VERSION', lines.filter((l) => l !== ''));
     UI.newline();
   } catch (error) {
+    if (jsonMode) {
+      emitVersionJson({ installed: null, error: 'version_failed', reason: error.message });
+      process.exit(1);
+    }
     UI.error(`Failed to get version: ${error.message}`);
     process.exit(1);
   }

package/src/utils/ui.js

@@ -3,6 +3,22 @@ const ora = require('ora');
 const inquirer = require('inquirer');
 
 class UI {
+  // Machine-readable mode (v3.32.0+). When on, every human-facing line that
+  // these helpers emit via `console.log` is redirected to STDERR, leaving
+  // STDOUT free for a single JSON object the caller (agent / CI) can parse.
+  // The JSON itself MUST be written with `process.stdout.write` directly —
+  // never through `console.log` — so it survives this redirect. Reversible;
+  // `ora` spinners already write to stderr, so they need no special handling.
+  static setJsonMode(on) {
+    if (on && !UI._origLog) {
+      UI._origLog = console.log;
+      console.log = (...args) => process.stderr.write(args.join(' ') + '\n');
+    } else if (!on && UI._origLog) {
+      console.log = UI._origLog;
+      UI._origLog = null;
+    }
+  }
+
   static header(text) {
     console.log('');
     console.log(chalk.cyan('━'.repeat(60)));