@aui.io/apollo 0.1.76 → 0.1.80

package/LICENSE

@@ -0,0 +1,10 @@
+Terms of use — @aui.io/apollo
+
+Copyright (c) AUI. All rights reserved.
+
+Use of this package, and of the Apollo APIs it calls, is governed by the
+AUI API and Developer Package Terms of Service:
+
+    https://www.aui.io/api-and-developer-package-terms-of-service/
+
+By installing or using this package you agree to those terms.

package/README.md

@@ -1,22 +1,28 @@
-# @aui.io/apollo
+# Apollo CLI — `@aui.io/apollo`
 
-**Apollo operator console — CLI + interactive TUI for authoring and operating Apollo agents.**
+**Author, test, and operate Apollo agents from your terminal.**
 
-One `npm install` gives you both surfaces: a scriptable Commander CLI (`apollo <command>`)
-and a full-screen terminal UI (bare `apollo`) for the author/test loop.
-This is the only published Apollo console package — the `apollo-core`, `apollo-cli`,
-and `apollo-tui` workspaces are bundled inside it.
+The Apollo CLI is the operator console for agents built on [Apollo-1](https://www.aui.io),
+AUI's neuro-symbolic foundation model. One install gives you two surfaces:
 
-## Install
+- a scriptable command-line interface — `apollo <command>`, with a `--json` mode for
+  scripts and coding agents;
+- a full-screen terminal UI (bare `apollo`) for the author → validate → test → push loop.
 
-```bash
-npm install -g @aui.io/apollo
-apollo --version
-```
+An agent's program is a **typed YAML codebase** you keep in a local checkout, edit in your
+IDE with schema support, validate, test against the live runtime, and push back as new
+versions. The same agents are available in [the Playground](https://apollo.aui.io).
+
+📘 Full documentation: **[docs.aui.io/cli](https://docs.aui.io/cli/overview)**
+
+---
+
+## Requirements
 
 | Requirement | Needed for |
 |---|---|
-| Node.js ≥ 20 | everything |
+| An AUI account — the login you use for [the Playground](https://apollo.aui.io) | everything |
+| Node.js 20 or newer | everything |
 | [Bun](https://bun.sh) (optional) | the interactive TUI only |
 
 No npm login is required to install. The TUI is built on [OpenTUI](https://opentui.com)
@@ -24,97 +30,153 @@ and runs on Bun: when launched from Node, `apollo` transparently re-executes the
 under `bun` from your `PATH`; without Bun it prints install guidance and the CLI
 remains fully usable.
 
-Upgrade later with:
+## Install
 
 ```bash
-apollo upgrade            # install @latest from npm
-apollo upgrade --check    # show the available version only
+npm install -g @aui.io/apollo
+apollo --version
+apollo doctor          # checks Node/Bun, the install, your terminal and connectivity
 ```
 
-## CLI or TUI?
+Upgrade later with:
 
-- **Bare `apollo` on a TTY launches the TUI** (the main path). `apollo tui` / `--tui` force it.
-- Any subcommand, `--json`, `--no-input`, or a non-TTY always runs the **CLI**.
-- Escape hatches: `APOLLO_TUI=0` keeps a bare TTY on the CLI welcome; `apollo cli <cmd…>` always routes to Commander.
+```bash
+apollo upgrade            # install the latest version from npm
+apollo upgrade --check    # show the available version only
+```
 
 ## Quick start
 
 ```bash
-apollo login                          # browser flow
-apollo agent import <agent-id>        # or: apollo agent create <name>
-cd <the printed checkout directory>   # defaults to ~/apollo/<profile>/<env>/<name>-<id>
+# 1. Sign in — opens the browser flow in the Playground
+apollo login
+
+# 2. Create a new agent, or import one you already have
+apollo agent create "Returns Assistant"      # or: apollo agent import <agent-id>
+cd <the printed checkout directory>          # defaults to ~/apollo/<profile>/<env>/<name>-<id>
 
-# edit bundle/src/… (program.yaml, vocabulary.yaml, capabilities/, policies/, …)
+# 3. Edit the program under bundle/src/
+#    program.yaml · vocabulary.yaml · situations.yaml · sources.yaml ·
+#    derivations.yaml · connections.yaml · capabilities/ · policies/
 
-apollo validate                       # deterministic program validation
-apollo push -m "describe the change"  # upload as a new version revision
-apollo chat "hello" --trace           # talk to it, with the decision trace
+# 4. Validate — deterministic, with every finding located in a file
+apollo validate
+
+# 5. Talk to it against the live runtime WITHOUT deploying, and read the trace
+apollo chat "I want to return an order" --local . --trace
+
+# 6. Push the change as a new version, then publish it when it is ready
+apollo push -m "Describe the change"
+apollo version list
+apollo version publish <tag>
 ```
 
-Context is positional: the nearest `.apollorc` walking up from your current directory
-selects the agent you are working on. `apollo status` always tells you where you stand.
+`apollo status` always tells you where you stand — which profile, organization, project,
+agent and version are active, and which runtime the checkout is pinned to.
+
+## How the CLI thinks
 
-## Mental model
+Context is **positional**: the nearest `.apollorc` walking up from your current directory
+selects the agent you are working on, so `cd` into a checkout and every command applies
+to that agent.
 
 | Layer | What it is | Commands |
 |---|---|---|
-| **Profile** | Named credential slot (e.g. `default`, `work`) | `profile *` |
-| **Checkout** | Local directory holding one agent (`.apollorc` + `bundle/src/`) | `agent use / import / create` |
-| **Organization** | Identity / billing org (on the access token) | `org *` |
-| **Project** | Container for agents | `project *` |
-| **Agent** | The program you edit and test | `agent *` |
-| **Version** | Tagged remote snapshot of the program | `version *`, `pull` / `push` |
+| **Profile** | A named credential slot (`default`, `work`, …) | `profile current / list / use` |
+| **Organization** | The organization your session is scoped to | `org list / use` |
+| **Project** | A container for agents | `project list / use / create` |
+| **Agent** | The program you edit and test | `agent list / create / import / use / unlink` |
+| **Checkout** | A local directory holding one agent: `.apollorc` + `bundle/src/` | `agent create / import` |
+| **Version** | A tagged snapshot of the program: draft → published → archived (publishing an older version is the rollback) | `version list / get / use / create / publish / archive`, `pull` / `push` |
+| **Runtime** | The engine build the checkout is pinned to | `runtime list / show / use` |
 
-## Command overview
+## Commands
 
 ```text
-status     [--check]                         # active context (+ service connectivity)
-doctor     [--offline]                       # diagnose setup; exit 2 on problems
-upgrade    [version] [--check] [--force]
-login | logout
-profile    current | list | use <name>
-org        list | use <id>
-project    list | use <id> | create <name>
-agent      list | use <target> | path | create <name> [--dir] | import <id> | unlink
-schema     pull [--dir]
-validate   [directory]
-diff       [--remote]
-pull       [--tag] [--dir] [--force]
-push       -m|--message <text> [--dry-run]
-version    list | get <tag> | use <tag> | create [--from|--template|--label|--notes]
-           | publish <tag> | archive <tag>
-scenarios  generate | pull | push | scores
-chat       [text…] [--thread] [--user] [--local] [--var] [--trace]
-thread     create | list | get | messages | trace
-mockdb     provision | status | describe | export | keys | wire | delete --force
-           | collections … | seed | endpoint … | execute | session … | rotate …
-vault      set <NAME> | list | get <NAME> | rm <NAME> --force
-kb         list | status <name> | check | create <name> | add <hub> <files…>
-           | add-url <hub> <urls…> | export <hub> | export --all | delete <name> --force
+status      [--check]                          active context (+ service connectivity)
+doctor      [--offline]                        diagnose the setup; exit 2 on problems
+upgrade     [version] [--check] [--force]      upgrade from npm
+login       [--sso | --email <e> [--otp <c>] | --token <jwt>]
+logout
+profile     current | list | use <name>
+org         list | use <id>
+project     list | use <id> | create <name>
+agent       list | create <name> [--dir <path>] [--template <id>]
+            | import [agent-id] [--tag <tag>] [--dir <path>] [--skills <targets>] [--force]
+            | use <target> | path | unlink
+runtime     list | show | use [version]
+validate    [directory] [--fix]                validate the local program (exit 2 on errors)
+diff        [--remote]                         compare local files with the last baseline
+pull        [--tag] [--dir] [--force] [--skills cursor,claude,opencode] [--no-skills] [--no-schemas]
+push        -m <message> [--dry-run]           validate and push local changes as a new version
+version     list | get <tag> | use <tag> | create [--from <tag> | --template <id>] [--label] [--notes]
+            | publish <tag> | archive <tag>
+chat        [text…] [--thread <id>] [--local <dir>] [--var k=v] [--trace]
+thread      create | list | get <id> | messages <id> | trace <id>
+regress     [--scenarios <codes>] [--judge] [--follow] [--status] [--cancel] [--pull]
+evaluate    [directory] [guidelines] [--simulations <n>] [--min-turns] [--max-turns] [--seed] [--world] [--follow]
+advise      <question> [--fresh] [--model] [--max-usd]
+build       <instruction> [-m] [--version-tag] [--publish] [--model] [--max-usd]
+mockdb      provision [--wire] | status | describe | export | keys | wire | clone --from <id> | delete --force
+            | collections create | update | list · seed · endpoint create | list | get | update | delete
+            | execute --slug <s> [--session] [--body] · session get | reset · rotate mgmt | runtime
+            | identities get | set · guide
+vault       set <NAME> | list | get <NAME> | rm <NAME> --force
+kb          list | status <name> | create <name> | add <hub> <files…> | add-url <hub> <urls…>
+            | check | export [name] | delete <name> --force
+shell-init                                     print the shell hook (see below)
 ```
 
-Run `apollo <command> --help` for the live flag list on your installed version.
+Run `apollo <command> --help` for the live flag list on your installed version — the
+command surface is verified against the CLI itself, so `--help` is always the authority.
 
 ### Global flags (before the subcommand)
 
 `--json` (stable envelope for scripts) · `--quiet` · `--verbose` (extra diagnostics,
-including one live line per API request) · `--no-input` · `--yes` ·
-`--profile <name>` · `--project <id>` · `--org <id>` · `--timeout <ms>`
+including one live line per API request) · `--no-input` · `--yes` · `--profile <name>` ·
+`--project <id>` · `--org <id>` · `--runtime-version <version>` · `--timeout <ms>`
 
 JSON mode always emits `{"success":true,"data":…}` or
 `{"success":false,"error":{"code","message","suggestion"}}`.
 Exit codes: `0` success · `1` runtime/API failure · `2` validation failure ·
 `3` auth/config failure.
 
+## Authentication
+
+```bash
+apollo login                               # browser sign-in via the Playground (default)
+apollo login --email you@example.com       # email one-time code, then prompts for it
+apollo login --token "$ACCESS_TOKEN"       # store a pre-issued access token
+apollo logout
+```
+
+Credentials are stored per **profile** in `~/.apollo/credentials.json` (mode `0600`).
+Use profiles to keep several accounts side by side (`apollo profile use work`, or
+`--profile work` on a single command).
+
+**CI and automation:** set `APOLLO_TOKEN` in the environment and run with
+`--json --no-input`; nothing prompts, and every result is a machine-readable envelope.
+
+## Working with coding agents
+
+The CLI is designed to be driven by coding agents as much as by humans. `apollo agent
+import` / `apollo pull` install the authoring **skill packs** and an `AGENTS.md` into the
+checkout (`--skills cursor,claude,opencode` selects the targets; `--no-skills` skips them),
+so tools such as Cursor, Claude Code and OpenCode can author, validate, test and push an
+agent end to end. `apollo advise "<question>"` asks the server-side authoring advisor about
+your checkout, and `apollo build "<instruction>"` runs one build turn over the pushed agent.
+
 ## The TUI in one minute
 
-Two primary modes — **Author** (program cockpit: validate, diff, push, pull, versions,
+Bare `apollo` on a TTY launches the terminal UI (`apollo tui` / `--tui` force it; any
+subcommand, `--json`, `--no-input` or a non-TTY always runs the CLI; `APOLLO_TUI=0` keeps a
+bare TTY on the CLI). Two primary modes — **Author** (validate, diff, push, pull, versions,
 resources, scenarios) and **Talk** (converse with the running agent).
 
 | Input | Action |
 |---|---|
 | `Ctrl+1` / `Ctrl+2` (or `Tab`) | Author / Talk |
-| `Ctrl+K` | Action palette — every operation, with CLI equivalents |
+| `Ctrl+K` | Action palette — every operation, with its CLI equivalent |
 | `Ctrl+G` | Context switcher — profile / agent / project / org |
 | `Ctrl+J` | Activity drawer — operations, retry, output, live API-request tail |
 | `Esc` | Close overlay / cancel |
@@ -124,6 +186,26 @@ In Author, single letters run quick actions (`v` validate · `d` diff · `p` pus
 text is a copilot instruction to the author backend. In Talk, the composer sends
 everything to the agent verbatim.
 
+## Testing an agent
+
+| Lane | Command | What it proves |
+|---|---|---|
+| A conversation | `apollo chat "…" --trace` (`--local .` sends the working tree instead of the pushed version) | one turn, with the symbolic **trace** — the reasoning record behind the reply |
+| Scripted regression | `apollo regress --follow` | every scenario in `bundle/build/scenarios.yaml`, said as written, as a real conversation |
+| Simulated callers | `apollo evaluate "<guidelines>" --follow` | improvising simulated callers planned from your guidelines and graded by a judge |
+| Threads | `apollo thread list / messages <id> / trace <id>` | inspect any conversation after the fact |
+
+## Data your agent reads
+
+- **Mock database** — `apollo mockdb …` provisions a per-agent, seedable mock database
+  with declared endpoints, so you can build and test against realistic data before a real
+  backend exists. `apollo mockdb guide` writes the complete how-to into your checkout.
+- **Knowledge hubs** — `apollo kb …` creates hubs, uploads documents or scrapes URLs into
+  them, and checks the program's `hub:` references before you push.
+- **Secrets** — `apollo vault set <NAME>` stores connection credentials by name; programs
+  reference them (`token_env`, `${NAME}`) in `bundle/src/connections.yaml` and never carry
+  a value.
+
 ## Diagnostics
 
 ```bash
@@ -132,21 +214,19 @@ apollo status --check     # context + per-service reachability/auth
 apollo --verbose <cmd>    # stream each API call live to stderr
 ```
 
-`apollo doctor` checks runtimes (Node/Bun), install origin, shell
-integration, `APOLLO_*` overrides, terminal capabilities, credential
-permissions, token expiry, the current checkout, and service reachability —
-read-only, with the fix attached to every finding. Share its output when
-reporting issues.
+`apollo doctor` checks runtimes (Node/Bun), install origin, shell integration,
+`APOLLO_*` overrides, terminal capabilities, credential permissions, token expiry, the
+current checkout, and service reachability — read-only, with the fix attached to every
+finding. Share its output when reporting issues.
 
-`--verbose` streams one **redacted** line per API request (auth/token/key/secret
-values never appear) to stderr; the TUI shows the same stream live in its
-activity drawer.
+`--verbose` streams one **redacted** line per API request (auth/token/key/secret values
+never appear) to stderr; the TUI shows the same stream live in its activity drawer.
 
 ## Files and environment variables
 
 ```text
 ~/.apollo/
-  config.json          # profile, environment, default projects
+  config.json          # profile, default projects
   credentials.json     # tokens (mode 0600 — the only secret-bearing file)
   checkouts.json       # known-checkouts registry
   baselines/…          # sync hashes for diff/push
@@ -155,9 +235,17 @@ activity drawer.
 <checkout>/bundle/src/ # the editable program source
 ```
 
-`APOLLO_PROFILE`, `APOLLO_TOKEN` (CI auth), `APOLLO_ORG_ID`,
-`APOLLO_PROJECT_ID`, `APOLLO_TIMEOUT_MS`, and per-service `APOLLO_*_URL` overrides are
-honored everywhere; see the User Guide for the full table.
+| Variable | Effect |
+|---|---|
+| `APOLLO_PROFILE` | credential profile to use |
+| `APOLLO_TOKEN` | access token for CI (no stored session needed) |
+| `APOLLO_ORG_ID`, `APOLLO_PROJECT_ID` | override the active organization / project |
+| `APOLLO_RUNTIME_VERSION` | override the checkout's pinned runtime |
+| `APOLLO_TIMEOUT_MS` | request timeout |
+| `APOLLO_TUI` | `0` keeps a bare TTY on the CLI |
+
+The full table, including per-service URL overrides, is in the
+[configuration reference](https://docs.aui.io/cli/configuration).
 
 ## Shell integration
 
@@ -165,11 +253,17 @@ The postinstall step offers a small shell hook (or add it yourself with
 `eval "$(apollo shell-init)"`): it lets `apollo agent use / import / create` drop your
 shell directly into the checkout directory.
 
-## Documentation
+## Documentation and support
+
+- [CLI overview](https://docs.aui.io/cli/overview) · [Installation](https://docs.aui.io/cli/installation) · [Commands](https://docs.aui.io/cli/commands) · [Configuration](https://docs.aui.io/cli/configuration) · [Workflows](https://docs.aui.io/cli/workflows)
+- [Apollo-1 documentation](https://docs.aui.io) — the program model, the Messaging API, the Agent Builder API and the SDK
+- [The Playground](https://apollo.aui.io) — the same agents in the browser
+- Questions or issues: run `apollo doctor`, then [contact AUI](https://www.aui.io/contact-us) with its output
+
+## Terms of use
 
-Full docs live in the repository:
+Use of this package, and of the Apollo APIs it calls, is governed by the
+**[AUI API and Developer Package Terms of Service](https://www.aui.io/api-and-developer-package-terms-of-service/)**.
+By installing or using `@aui.io/apollo` you agree to those terms.
 
-- [User Guide](https://bitbucket.org/getstuff/runtime-v2/src/main/console/docs/USER_GUIDE.md) — install, mental model, every command, TUI, troubleshooting
-- [Configuration](https://bitbucket.org/getstuff/runtime-v2/src/main/console/docs/CONFIGURATION.md) — every file and variable the console reads or writes
-- [Architecture](https://bitbucket.org/getstuff/runtime-v2/src/main/console/docs/ARCHITECTURE.md) — services, auth, request handling
-- [Keybindings](https://bitbucket.org/getstuff/runtime-v2/src/main/console/docs/KEYBINDINGS.md) — TUI input reference
+© AUI. All rights reserved.

package/node_modules/@aui.io/apollo-cli/dist/src/commands/bundles.d.ts

@@ -1,3 +1,15 @@
 import type { Command } from "commander";
+import type { EvaluationView } from "@aui.io/apollo-core/api/builder-api.js";
 import type { CommandRuntime } from "./runtime.js";
+/** The report, one line per scenario, with the judge's reasons (and trial
+ *  errors) folded in; an evaluation adds its macro verdict and findings; any
+ *  annotations come last. A live run renders as a progress line instead —
+ *  polling is the progress surface. */
+export declare function renderRun(view: EvaluationView): string;
+/** The three grades per trial and per covered case (symbolic-judge-design.md
+ *  §6, §7): the trace check, the judge, and what the trial counts as. A
+ *  regression counts both; an evaluation shows the trace but counts the
+ *  judge alone, and says so in the block's title. Rows settled before the
+ *  grades existed carry none, and the block stays away. */
+export declare function renderGrades(view: EvaluationView): string[];
 export declare function registerBundles(program: Command, runtime: () => CommandRuntime): void;

package/node_modules/@aui.io/apollo-cli/dist/src/commands/bundles.js

@@ -1,14 +1,14 @@
 import { access } from "node:fs/promises";
 import { homedir } from "node:os";
 import path from "node:path";
-import { renderValidation } from "@aui.io/apollo-core/bundle/validate.js";
+import { renderBundleAudit, renderValidation } from "@aui.io/apollo-core/bundle/validate.js";
 import { defaultCheckoutDir, listCheckouts, registerCheckout, } from "@aui.io/apollo-core/checkouts/registry.js";
 import { ConfigError, ValidationError } from "@aui.io/apollo-core/errors/index.js";
 import { assertRuntimeAvailable } from "@aui.io/apollo-core/runtime-version/availability.js";
 import { adviseLocalBundle } from "@aui.io/apollo-core/services/advisor.js";
 import { buildAgent } from "@aui.io/apollo-core/services/builds.js";
 import { annotateRun, awaitRun, pullRun, receiptId, resolveRunId, startEvaluation, startRegression, } from "@aui.io/apollo-core/services/runs.js";
-import { importBundle, listVersions, localDiff, pullCheckout, pushBundle, remoteDiff, validateLocalBundle, } from "@aui.io/apollo-core/services/bundles.js";
+import { importBundle, listVersions, localDiff, pullCheckout, pushBundle, remoteDiff, applyBundleFixes, bundleSourceRoot, validateLocalBundle, } from "@aui.io/apollo-core/services/bundles.js";
 import { checkoutSchemasDir, installSchemas, } from "@aui.io/apollo-core/schemas/install.js";
 import { createClients } from "@aui.io/apollo-core/services/clients.js";
 import { agentRuntimeVersion, listAgents, useVersion, } from "@aui.io/apollo-core/services/hierarchy.js";
@@ -48,7 +48,7 @@ function censusLines(result) {
  *  errors) folded in; an evaluation adds its macro verdict and findings; any
  *  annotations come last. A live run renders as a progress line instead —
  *  polling is the progress surface. */
-function renderRun(view) {
+export function renderRun(view) {
     const kind = view.kind;
     if (view.verdict === null && view.result === null && view.macro_verdict == null) {
         const settled = view.trials.filter((trial) => trial.status !== "running" && trial.status !== "queued").length;
@@ -82,6 +82,7 @@ function renderRun(view) {
         const marker = row.verdict === "pass" ? "PASS" : "FAIL";
         lines.push(`  ${marker} ${row.code} — ${row.passed}/${row.k} trial(s)${row.verdict !== "pass" && reasons ? ` — ${reasons}` : ""}`);
     }
+    lines.push(...renderGrades(view));
     if (view.annotations?.length) {
         lines.push("annotations:");
         for (const note of view.annotations) {
@@ -94,6 +95,33 @@ function renderRun(view) {
     lines.push(`${kind} ${view.evaluation_id}`);
     return lines.join("\n");
 }
+/** The three grades per trial and per covered case (symbolic-judge-design.md
+ *  §6, §7): the trace check, the judge, and what the trial counts as. A
+ *  regression counts both; an evaluation shows the trace but counts the
+ *  judge alone, and says so in the block's title. Rows settled before the
+ *  grades existed carry none, and the block stays away. */
+export function renderGrades(view) {
+    const graded = view.trials.filter((trial) => trial.final != null);
+    if (graded.length === 0)
+        return [];
+    const trace = view.kind === "evaluation" ? "trace observed, not counted" : "trace";
+    const lines = [`grades (${trace} · judge · final)`];
+    const perCode = new Map();
+    for (const trial of graded) {
+        perCode.set(trial.scenario_code, (perCode.get(trial.scenario_code) ?? 0) + 1);
+    }
+    for (const trial of graded) {
+        const label = (perCode.get(trial.scenario_code) ?? 0) > 1
+            ? `${trial.scenario_code}#${trial.iteration}`
+            : trial.scenario_code;
+        lines.push(`  ${label}: ${trial.symbolic ?? "not_validated"} · ${trial.neural ?? "not_validated"} · ${trial.final ?? "not_validated"}`);
+        for (const [caseId, grades] of Object.entries(trial.cases ?? {})) {
+            const reasons = (grades.reasons ?? []).join("; ");
+            lines.push(`    ${caseId}: ${grades.symbolic} · ${grades.neural} · ${grades.final}${reasons ? ` — ${reasons}` : ""}`);
+        }
+    }
+    return lines;
+}
 /** The read/act half both lanes share: `--status`, `--cancel`, `--pull` and
  *  `--annotate` name the checkout's last run of that lane (or `--id`) and
  *  never start one. Returns false when nothing was asked. */
@@ -229,20 +257,53 @@ export function registerBundles(program, runtime) {
         .command("validate")
         .description("Validate the local agent program via builder-api — the verdict plus the orphan and era censuses")
         .argument("[directory]")
-        .action(async (directory) => {
+        .option("--fix", "apply the build-bundle audit's mechanical repairs (files moved home, retired keys respelled, case prose lifted onto its need), then report what remains")
+        .action(async (directory, options) => {
         const run = runtime();
         const clients = createClients(run.context);
         await assertRuntimeAvailable(run.context, clients);
-        const result = await validateLocalBundle(run.context, clients.builder, directory
+        const root = directory
             ? path.join(path.resolve(directory), "bundle", "src")
-            : undefined);
+            : bundleSourceRoot(run.context);
+        let result = await validateLocalBundle(run.context, clients.builder, root, {
+            fix: options.fix === true,
+        });
+        // With --fix the repairs are written HERE — builder-api planned them
+        // over a copy — and the tree is validated again, so the verdict below
+        // is the one the checkout now has. The applied list rides the result.
+        const applied = options.fix ? (result.fixes ?? []) : [];
+        if (applied.length > 0) {
+            await applyBundleFixes(applied, root);
+            result = await validateLocalBundle(run.context, clients.builder, root);
+        }
+        const appliedLines = options.fix
+            ? applied.length > 0
+                ? [
+                    `Applied ${String(applied.length)} repair(s):`,
+                    ...applied.map((f) => `  ${f.op} ${f.path} — ${f.why}`),
+                    "",
+                ]
+                : ["Nothing mechanical to fix.", ""]
+            : [];
+        result = { ...result, ...(options.fix ? { applied } : {}) };
         // Errors AND warnings, both paths. The success path used to print only
         // "Program is valid." — every advisory finding silently dropped, which
         // is the exact blindness a post-change validate exists to remove.
         if (!result.valid) {
-            throw new ValidationError(renderValidation(result));
+            throw new ValidationError([...appliedLines, renderValidation(result), ...renderBundleAudit(result.bundle)].join("\n"));
         }
-        run.output.result(result, () => [renderValidation(result), ...censusLines(result)].join("\n"));
+        // Valid is not pushable: the audit's existence errors (no brief, no
+        // needs, no cases) let a validate through and refuse a push — say so
+        // here, where the author looks before pushing.
+        run.output.result(result, () => [
+            ...appliedLines,
+            renderValidation(result),
+            ...renderBundleAudit(result.bundle),
+            ...(result.pushable
+                ? []
+                : [`Not pushable — ${String(result.bundle.errors.length)} build-bundle error(s) refuse a push.`]),
+            ...censusLines(result),
+        ].join("\n"));
     });
     withRunFlags(program
         .command("regress")
@@ -496,6 +557,9 @@ export function registerBundles(program, runtime) {
                 result.build
                     ? `Build bundle v${result.build.version}: ${result.build.written.length} file(s) into bundle/build.`
                     : "",
+                result.certificate
+                    ? `Certificate: ${result.certificate.revision ?? result.certificate.version} (${result.certificate.run}), ${result.certificate.cases.length} case(s) — bundle/build/certification.yaml.`
+                    : "",
                 result.schemas ? `Schemas: ${result.schemas.length}.` : "",
                 result.skills ? `Skills: ${result.skills.length}.` : "",
                 result.removedSkills
@@ -556,6 +620,9 @@ export function registerBundles(program, runtime) {
                         "Validated via builder-api — the runtime validate lane was unreachable.",
                     ]
                     : []),
+                // The audit's warnings and advisories ride the push report; its
+                // errors already refused above.
+                ...renderBundleAudit(result.bundle),
                 renderDiff(combined),
             ].join("\n");
         });