# BALDART — private agent framework

Private framework for coordinating Claude Code, Codex and human developers.
Repository, CLI, payload, issues and bat-beacon transcripts are private.

## What Is This?

BALDART provides a portable system for:

- **Agent Coordination**: Clear protocols (AGENTS.md) defining how AI agents and humans work together
- **AI Agents**: Pre-built specialized agents (coder, code-reviewer, doc-reviewer, etc.)
- **Commands**: Batch orchestration (/new), design reviews, issue analysis
- **Templates**: Backlog cards, PRDs, specs, breaking change checklists
- **Documentation Structure**: Standard layouts for API docs, data models, UI specs

## Quick Start

### Bootstrap

Requirements: Node.js >=18, npm, GitHub CLI (`gh`) and access to
`antbald/BALDART`.

Existing users of the final public bridge:

```bash
baldart private-bootstrap
```

New machines:

```bash
gh auth login --hostname github.com
gh auth setup-git --hostname github.com
tmp_dir="$(mktemp -d)"
gh release download --repo antbald/BALDART --pattern 'baldart-cli-*.tgz' --dir "$tmp_dir"
gh release download --repo antbald/BALDART --pattern SHA256SUMS --dir "$tmp_dir"
(cd "$tmp_dir" && grep 'baldart-cli-' SHA256SUMS | shasum -a 256 -c -)
npm install -g "$tmp_dir"/baldart-cli-*.tgz
baldart auth status
```

Then in any project directory just run:

```bash
baldart
```

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.

| 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" |
| New private release available | "Install verified release" → runs `update` |
| Local framework changes ready to share | "Open private contribution PR" → runs `push` |

If several conditions hold, actions are presented in priority order (e.g. update before push).

Upgrade the CLI later:
```bash
baldart private-bootstrap
```

### Commands

```bash
baldart            # same smart entry point
baldart auth status
baldart add        # explicit subcommands
baldart update
baldart configure
baldart capabilities  # enable/disable capability clusters (interactive menu)
baldart push
baldart version
baldart status
```

### What `add` (first install) does

- Refuses a verified public consumer before writing private payload bytes
- Downloads the latest private payload release into staging and verifies SHA-256 + the per-file manifest
- Atomically installs the tracked `.framework/` directory
- Creates a symlink for the cross-tool `agents/` reference dir
- Generates the root-file primitives `AGENTS.md` (cross-tool SSOT) + `CLAUDE.md` (Claude entry) from versioned skeletons — filling project facts from `baldart.config.yml` and merging `.baldart/overlays/{AGENTS,CLAUDE}.md`
- 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 git aliases
> (`fw-version`, `fw-update`, `fw-push`) for shorter project-local commands.

## Features

### Core Protocol

- **AGENTS.md**: Mandatory coordination rules (MUST/SHOULD/OPTIONAL)
- **agents/**: 33 domain modules (architecture, workflows, testing, security, card-schema, i18n-protocol, return-contract-protocol, runtime-portability-protocol, component-manifest-schema, research-protocol, etc.)
- **Routing**: If you touch X, read Y - minimize context loading

### Capabilities (new in v6.0.0)

The payload (skills, agents, commands, routines, workflows, external tools,
MCP servers) is grouped into selectable **capability clusters** — `core`
(always on), `development`, `design`, `website`, `creative-media`,
`machine-learning`, `gamification`, `psychology`. Pick per project via
`capabilities.enabled` in `baldart.config.yml` (absent = ALL, full backwards
compatibility); per-item `extra_*`/`exclude` overrides; shared credentials in
the user-level `~/.baldart/secrets.yml`; MCP servers wired into `.mcp.json`
(BALDART-owned entries only). See [framework/docs/CAPABILITIES.md](framework/docs/CAPABILITIES.md).

### AI Agents (36 specialized agents)

**Core (required for every project)**
1. **codebase-architect**: MANDATORY before planning/implementation - understands codebase structure
2. **coder**: Writes production code with build/test/lint verification + Post-Approval Complexity Gate
3. **code-reviewer**: Reviews for bugs, security, quality, maintainability — confidence-based filtering + Findings Schema
4. **code-simplifier**: Dedicated reuse & simplicity reviewer — duplication, reuse-misses, dead code, wrong-altitude abstractions, missed optimizations; deterministic clone floor + `simplify-protocol.md` (quality only, partitioned from code-reviewer)
5. **security-reviewer**: Dedicated AppSec auditor for auth/secrets/multi-tenant/infra — boundary-gate → repo-scoped threat-model → modern high-miss discovery-lens → class proof-tuples → structured attack-path → adversarial-refute (`security-review-protocol.md`)
6. **doc-reviewer**: Audits and writes documentation, SSOT sync, doc debt tracking, design-system drift detection
7. **wiki-curator**: Maintains the derived LLM wiki overlay (`docs/wiki/`) — synthesis candidates, anchor + frontmatter validation
8. **doc-graph-aligner**: Aligns documentation with the Graphify code knowledge graph — coverage gaps, stale docs, drift vs the SSOT registry
9. **prd**: Creates PRDs, implementation plans, and backlog cards with autonomous tech decisions
10. **prd-card-writer**: Generates atomic backlog cards with traceability + parallel groups from approved PRDs
11. **plan-auditor**: MANDATORY after planning — 4-persona plan review + High-Risk Path triggers + Specialist Auto-Spawn
12. **senior-researcher**: Evidence-based research with AI-readable retrieval-optimized reports
13. **api-perf-cost-auditor**: API performance and cost analysis with Findings Schema emission
14. **qa-sentinel**: SDET-grade gate runner (profile-driven: scoped-by-default, full on deep) — lint, tsc, test, build, audit
15. **security-finder**: READ-ONLY AppSec finder (analysis-only twin of security-reviewer) — powers the Codex-native `/new` review fan-out
16. **doc-finder**: READ-ONLY doc drift/coverage finder (analysis-only twin of doc-reviewer)

**Design & UX**
17. **ui-expert**: UI/UX design and review
18. **visual-designer**: Visual asset generation via image APIs
19. **motion-expert**: Animation specs, transitions, micro-interactions
20. **hyper-gamification-designer**: Game mechanics, retention loops, economy balance
21. **remotion-animator-orchestrator**: Video/motion graphics with Remotion
22. **visual-fidelity-verifier** (v3.18.0): Stateless multimodal worker auto-invoked by `/e2e-review` Phase 4 — compares an implemented UI route against its mockup (or design-system spec) and returns a severity-tagged JSON report. Never reads source code (anti assertion-fitting bias), never edits, never declares done
23. **markup-fidelity-verifier** (v4.78.0): Route-INDEPENDENT structural twin of `visual-fidelity-verifier`, auto-invoked by `/e2e-review` Phase 2.7 — compares the implementation's code structure against the mockup expressed as code (`links.design` HTML or `links.design_src`) with no browser/auth/data, catching the 2-column-mockup → 1-column-build class of divergence. READS code (mockup-vs-impl, no assertion-fitting risk); same canonical taxonomy + JSON output; fixes route to `ui-expert`
24. **ui-quality-critic** (v4.61.0): Stateless multimodal worker auto-invoked by `/e2e-review` Phase 4b — judges the **intrinsic design quality** of an implemented UI (10-dimension scientific rubric: hierarchy, rhythm, color, density, composition, states, motion, polish, brand) and returns a severity-tagged JSON report + per-dimension scores. The design twin of `code-reviewer`, the quality complement of `visual-fidelity-verifier` (needs no mockup). Never reads source, never grades its own design; fixes route to `ui-expert` in the bounded self-heal loop

**Product & Marketing**
25. **onboarding-architect-lead**: User onboarding flow design and experimentation
26. **marketing-conversion-strategist**: High-converting copy and messaging
27. **seo-analytics-strategist**: SEO strategy, metadata, GA4/GTM event planning
28. **email-deliverability-architect** (v2.0.0): Transactional/informational email design + SPF/DKIM/DMARC — field-verified invariants (DMARC staged progression, reply-to on-domain, mail-tester go-live gate)
29. **email-copywriter** (v6.34.0): Profile-driven email copy (`PROFILE=<transactional|onboarding|retention|winback|announcement|digest>`) — copy only, invoked by `/email`
30. **website-orchestrator**: Multi-agent website development coordination

**Specialized**
31. **hybrid-ml-architect**: ML/DL system design (recommenders, ranking, embeddings)
32. **legal-counsel-gdpr**: GDPR compliance, privacy policies, data governance
33. **deep-human-insight**: Psychological / sociological analysis for B2C UX and adoption
34. **skill-improver**: Weekly auto-improvement of skills/agents based on review/QA findings
35. **i18n-translator** (v4.52.0): Context-aware label translation into native locale files (Sonnet, low-effort, flag-not-guess) — invoked by `/i18n` + the `i18n-align` routine
36. **merge-conflict-resolver** (v4.64.0): Resolves the final-merge **code** conflicts OFF the orchestrator context — auto-spawned by `/new` Phase 6 / `/mw` only when the deterministic `merge-worktree.sh` pauses on a code/test conflict. Adjudicates additive-vs-semantic hunks (semantic → STOP), then lets the script land. Runs in a fresh isolated context so the conflict churn never re-enters the bloated end-of-batch orchestrator

REGISTRY.md is the single source of truth for agent routing and capabilities.

### Real-time edit gate (new in v3.3.0)

A Claude Code `PreToolUse` hook (`framework-edit-gate`) is auto-registered in
every BALDART consumer. It intercepts `Edit`/`Write`/`MultiEdit` whose target
resolves (via symlink) to a path inside `.framework/` and runs the
contamination scanner on the new content. If project-specific tokens are
detected (Neo-Brutalism, merchant, recharts, secrets, …), the call is blocked
with a structured reason that tells Claude exactly what to do: reformulate
generically with `${paths.X}`/`identity.X`, move to `.baldart/overlays/`, or
declare the file opt-out via the contamination-scan marker.

In practice: when Claude tries to write project-specific content into a
framework skill, the hook stops it before the file is touched and Claude
adapts in real time. No more "I forgot, sent merchant logic upstream by
mistake".

Registered automatically by `baldart add` and `baldart update`. Detected by
`baldart doctor` and re-installed on demand. Disable by removing the entry
from `.claude/settings.json` if you ever need to.

### Centralized versioning (new in v3.1.0)

Every consumer repo gets a `.baldart/state.json` file that tracks: which
framework version is installed, when it was installed, when it was last
updated, when it was last pushed upstream, and a rolling history of the
last 20 events. You always know exactly which version you are working on.

Run `baldart version` to see installed/private-latest versions, distribution,
payload checksum, access status, local uncommitted-files count and last-push
info. Use `--offline` to skip GitHub.

State updates happen automatically — no manual bookkeeping required.

### Private CLI self-update

The CLI and tracked `.framework/` payload are separate private release assets.

Every interactive run performs a cached best-effort check against the latest
private GitHub Release. A newer release produces:

```
↑ baldart 3.13.0 available (you have 3.12.0)
  Update with: baldart private-bootstrap
  Suppress with: BALDART_NO_UPDATE_CHECK=1
```

The notifier never installs anything automatically — global installs can
require sudo and affect every other project on your machine, so the choice
stays with you. CLI drift also appears inline in `baldart doctor` (new `CLI`
row) and in `baldart version`. Auto-suppressed in CI, in non-TTY runs, with
`--offline`, with `NODE_ENV=test`, or via `BALDART_NO_UPDATE_CHECK=1`.

### Project Configuration (new in v3.0.0)

BALDART skills are **portable across projects**. Instead of hard-coding paths
(`docs/design-system/INDEX.md`), brand identity (Neo-Brutalism), audience segments
(merchant/customer), or technology stacks (Recharts-only), skills now read these from
`baldart.config.yml` at your repo root.

Three layers:

1. **`baldart.config.yml`** — structural facts (paths, identity, stack, feature flags). Populated by `baldart configure` with strong filesystem autodetection.
2. **Skills** — generic, reference `${paths.X}` and `identity.Y` instead of literals.
3. **`.baldart/overlays/<skill>.md`** — your project-specific opinions (brand voice pillars, mandatory libraries, custom workflows). Frontmatter-versioned for drift detection.

```bash
# First-run (also invoked at the end of `baldart add`)
baldart configure

# Author overlays (optional; starter examples in .framework/templates/overlays/)
cp .framework/templates/overlays/ui-design.fidelity-example.md \
   .baldart/overlays/ui-design.md
```

Skills always-ask when required keys are missing — never silently default.
`baldart update` warns when new framework versions add config keys but
never overwrites your file. Full guide:
[`framework/docs/PROJECT-CONFIGURATION.md`](framework/docs/PROJECT-CONFIGURATION.md).

### Skills (46 portable skills)

Skills live under `.claude/skills/` and are auto-discovered by Claude Code. Every
skill is **versioned** (`version:` in frontmatter) and ships a per-skill
`CHANGELOG.md` (v4.82.0 — see [skill-structure.md](framework/.claude/skills/skill-creator/references/skill-structure.md)).
Bundled skills:

- **Workflow**: `new` (Codex Model B since v6.12.0: one-shot resident executor, append-only journal, strict broker/evidence/review/delivery receipts; Claude path unchanged), `new2` (v4.16.0 — EXPERIMENTAL workflow-hosted `/new`, Claude-only, for A/B testing context economy), `prd` + `prd-add` (Codex-native Mode B since the /prd Codex-native program — the multi-turn conversation ships a native `runtimes/codex/` package: native progress/decision surfaces, shared agent-execution adapter, docs-worktree + docs-mode merge scripts, deterministic audit fan-in; the Claude path is byte-unchanged behind `{{#rt_codex}}` branches), `bug`, `simplify`, `codexreview` (framework v5.20.0 — the deep multi-agent card-review pipeline as a portable skill; the `/codexreview` slash command is now a thin Claude wrapper, and Codex-hosted runs get a native fresh-context adversarial binding), `worktree-manager`, `issue-review`, `context-primer`
- **Code quality**: `skill-creator`, `find-skills`, `webapp-testing`, `playwright-skill`, `lsp-bootstrap` (v3.10.0), `graphify-bootstrap` (v4.21.0 — code knowledge graph), `graph-align` (v4.21.0 — doc↔graph alignment), `toolchain-bootstrap` (v4.41.0 — curated dev toolchain), `e2e-review` (v3.18.0)
- **Design**: `ui-design` (v2.0.0, framework v5.2.0 — the **local design studio**: Design Read & direction lock, 12-direction menu, deterministic anti-slop craft gate `craft-check.mjs`, dual-lens evaluation with `ui-quality-critic`; the internal twin of the Claude Design handoff), `frontend-design` (retired to a router since v5.2.0 — reroutes to `ui-design` / `ui-implement` / `ui-expert`), `ui-implement` (v4.82.0 — implement an approved mockup end-to-end + self-verify fidelity; the mockup→code playbook SSOT, delegated from `/new`), `motion-design`, `gamification-design`, `design-system-init` (v3.11.0 — bulk registry bootstrap/upgrade), `ds-new` (v4.69.0 — single-element guided creation: one component or token, reuse-first → optional scaffold → document + register + govern + verify; the on-the-fly twin of `design-system-init`), `ds-edit` (v4.70.0 — deliberate edit of one existing element: resync / extend-variant / breaking / re-govern; regenerates the spec preserving agentic fields + prose, same canonical template), `ds-render` (v4.76.0 — render primitives in isolation to PNG via Storybook+Playwright), `design-sync` (v4.76.0 — mirror the registry to its Claude Design satellite), `ds-handoff` (v4.79.0 — field-level 1:1 Claude Design handoff brief: grounds every screen's fields in the real data schemas + coverage-gates before emitting; the SSOT for the Claude Design prompt, delegated from `/prd`)
- **Product**: `seo-audit`, `copywriting`, `api-design-principles`
- **Knowledge**: `doc-writing-for-rag`, `capture` (LLM wiki overlay), `research` (v5.1.0 — routed research over the reusable research library: profile + source-matrix routing, reuse pre-flight, `senior-researcher` fan-out, matrix growth loop)
- **Internationalization**: `i18n` (v4.52.0 — audit the context registry + context-aware translation into native locale files), `i18n-adopt` (v4.52.0 — one-shot migration that externalizes all hardcoded strings on an existing codebase); both gated on `features.has_i18n`
- **Integration**: `kie-ai`, `remotion-best-practices`
- **Framework**: `baldart-push` (upstream contribution), `baldart-update` (v3.21.0 — agent-driven framework update), `overlay` (v3.19.0 — guided overlay author), `bat-beacon` (v6.14.0 — il bat-segnale: raccolta deterministica del contesto di un problema del framework + invio come issue GitHub sulla repo upstream, con outbox offline; il lato consumer del loop di miglioramento autonomo), `wrap` (v6.21.0 — chiusura di sessione con retrospettiva terminale: auto-analisi della run + bat-beacon aggregato + recupero differito delle sessioni chiuse con exit secco)

### Registry-First UI Protocol (new in v3.11.0)

When `features.has_design_system: true`, every UI-touching agent/skill/command (`ui-expert`, `ui-design`, `ui-implement`, `code-reviewer`, `/design-review`) follows the same BLOCKING cascade: read `${paths.design_system}/INDEX.md` (Authority Matrix), `tokens-reference.md` (token contract), and `components/<Name>.md` for every primitive in scope — BEFORE producing or reviewing any UI. New components must reuse from the registry or ship their per-component spec in the same change. Hardcoded color/shadow/radius/spacing values are HIGH findings. The textual SSOT for the protocol lives in [`framework/agents/design-system-protocol.md`](framework/agents/design-system-protocol.md). Projects without a registry can bootstrap one with `/design-system-init`, which inventories existing primitives, extracts tokens from global styles + Tailwind config, scaffolds the registry, and flips the flag.

**Closed-Set Selection Policy (v4.68.0).** The registry has a token layer and a component layer, but until now nothing asserted the *boundary* of a category — so an agent designing from a mockup could write a third "header" when two canonical ones already cover every case, and the duplicate was only caught (reactively) at review. The closed-set policy adds the missing third layer: each component spec declares the presentational **role** it is canonical for (`canonical_for: [page-header@depth-0]`) and whether that role family is **closed** (`selection_closed`), aggregated into a generated `INDEX.md` § "Selection Policy". A closed family means *introducing a new canonical member is a governance decision, not an implementation act*. Three layers enforce it: (1) **`/prd` Component Reconciliation** — a human-in-the-loop *match-before-generate* gate that binds each mockup region to an existing component (or a governed NEW one) and asks *"this becomes the standard?"* only on genuine ambiguity, persisting the decision into the card's `component_bindings`; (2) **`baldart ds-gate`** — a deterministic, zero-false-positive build-time gate that BLOCKS (`DS_CLOSED_SET_VIOLATION`) any change adding a new canonical in a closed family (wired into `qa-sentinel` / `/new` / `code-reviewer`, the design-system analogue of the i18n gate); (3) the existing review + weekly `ds-drift` safety net. Rides on `features.has_design_system` — no new config key; `/design-system-init --upgrade` derives the closed sets from your existing `must_rules`. This closes a gap no 2026 design-to-code vendor hard-gates (Figma Code Connect, Storybook MCP, shadcn are all advisory).

### End-to-End Review BLOCKING Gate (new in v3.18.0)

When `features.has_e2e_review: true`, the `/new` orchestrator Phase 2.6 invokes the new `/e2e-review` skill on every UI card (auto-skipped on backend-only cards). The skill is a **deterministic, BLOCKING** orchestrator that combines functional E2E (Playwright spec written by `coder`, executed via `playwright-skill`) with visual fidelity diff (`visual-fidelity-verifier` multimodal agent) and aggregates findings under a strict severity gate. This replaces the legacy advisory pair (Phase 2.6 conditional E2E + Phase 2.7 non-blocking design review) that left the user manually re-verifying every screen.

The skill walks a **4-level mockup source cascade** (Figma MCP → local PNG/JPG/PDF → design-system compliance-only → skip-with-warning) — Figma is opt-in, the framework remains portable. The aggregation gate uses a **canonical severity taxonomy** (Critical: layout/responsiveness/element-order/component-missing; Major: spacing/typography/color/token-bypass/interactive-state/a11y; Minor: border-radius/shadow/micro-misalignment). The gate enforces three pillars from the 2025–2026 agentic-testing literature: (a) **implementer ≠ verifier** ([Anthropic — Effective Harnesses for Long-Running Agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)), (b) **Definition of Done machine-readable** ([Policy Cards, arXiv 2510.24383](https://arxiv.org/abs/2510.24383)), (c) **Playwright MCP + Vision** as the canonical browser+vision combo ([Playwright MCP](https://playwright.dev/mcp/introduction)).

Tuning lives under `features.e2e_review` in `baldart.config.yml`: `fidelity_tolerance` (`strict` | `balanced` | `lenient`, default `strict`), `max_self_heal_iterations` (default `2`), `pixel_diff_threshold` (default `0.02` — pre-filter to skip Vision when implementation and mockup are pixel-identical, primary cost saver), `require_override_reason` (default `true`). When self-heal exhausts iterations, the gate exposes an **override path with mandatory reason** logged in the tracker's `## Issues & Flags` for auditability. The weekly `ds-drift` routine remains as a complementary safety net for direct human edits that bypass `/new`.

### UI Excellence + Post-Intervention Coherence Gate (new in v3.12.0)

The `ui-expert` agent is upgraded from a generic baseline to a world-class UI/UX reviewer/designer — UI States Taxonomy (8 states), Performance Gates (Core Web Vitals 2026 — LCP/INP/CLS), modern CSS surface (container queries, `:has()`, View Transitions, subgrid, logical properties), AI-era patterns (streaming UI, hallucination guardrails), and 60+ categorized red flags. Numeric reference tables (type scale, contrast targets WCAG+APCA, spacing scales, density tiers, motion durations/easings) are SSOT'd in [`framework/agents/design-system-protocol.md`](framework/agents/design-system-protocol.md) so agents cite values verbatim instead of inventing them. Crucially, the registry-first discipline now has a **post-intervention coherence gate**: every UI change introduced by `ui-expert` / `ui-design` / `ui-implement` (and verified by `code-reviewer` at merge) must reconcile `INDEX.md` + `components/<Name>.md` + `tokens-reference.md` **in the same change** — drift can no longer wait for the weekly `ds-drift` routine. Three layers now enforce coherence: per-task → per-merge → weekly safety net. Existing projects align their current graphic organization with the new discipline via [`framework/docs/UPGRADE-3.12-UI-COHERENCE.md`](framework/docs/UPGRADE-3.12-UI-COHERENCE.md) (idempotent walkthrough: baseline scan → prioritized backlog → quick wins → gate verification).

### LSP Symbol Search Layer (new in v3.10.0)

When `features.has_lsp_layer: true`, `codebase-architect` and the code-exploration skills (`context-primer`, `bug`, `prd`, `new`, `simplify`) prefer LSP `find-references` / `go-to-definition` over Grep for identifier-shaped queries — the filtering happens **before** Claude reads files, so a common function name no longer dumps thousands of textual matches into context. Opt-in at `baldart configure`; BALDART installs the matching language servers (global npm install for TypeScript/Python — the binary must be on `$PATH` because Claude Code's LSP tool spawns it by name; system commands printed for Go/Rust/Ruby). Grep remains the fallback for free-text queries and degraded states. See [`framework/agents/code-search-protocol.md`](framework/agents/code-search-protocol.md).

### Code Knowledge Graph Layer (new in v4.21.0)

When `features.has_code_graph: true`, agents prefer the [Graphify](https://github.com/safishamsi/graphify) code knowledge graph (tree-sitter, local/offline, native Leiden communities) for **structural / relational** queries — "what connects X to Y", blast-radius of a change, which modules cluster — via `graphify query`/`path`/`explain`/`affected`. The same graph **re-activates the LLM-wiki auto-learning loop** (dormant since the RAG removal in v4.20.0): `wiki-curator`, `/capture`, and the nightly `doc-graph-align` routine feed synthesis candidates from Graphify's native `GRAPH_REPORT.md` (god nodes, communities, suggested questions) — entirely offline. Graphify is a single language-agnostic tool (`pipx install graphifyy`); install via `baldart configure` or `/graphify-bootstrap` (never silent in CI — `baldart doctor` backfills). Falls back silently to LSP→Grep→Git. See [`framework/agents/code-graph-protocol.md`](framework/agents/code-graph-protocol.md) and [`framework/docs/CODE-GRAPH-LAYER.md`](framework/docs/CODE-GRAPH-LAYER.md).

### Internationalization Layer (new in v4.52.0)

When `features.has_i18n: true`, BALDART makes consumers develop **multi-language by default**. Two ideas: (1) **no user-facing string is ever hardcoded** — every label goes through the stack's translation function, enforced by a deterministic anti-hardcoded gate (a BALDART-owned standalone `eslint.i18n.config.mjs` running `eslint-plugin-i18next` `no-literal-string` — works even on Biome-only projects, never touches your lint config) with `code-reviewer` as the semantic backstop; (2) a **stack-agnostic context registry** (`docs/i18n/registry.yml`) holds a *hyper-brief context* per key (what it is for / where it appears) + `domain`, so LLM translation is **context-aware instead of blind** — the 2026 "void of context" fix. Translations live in the stack's **native locale files** (i18next / next-intl / react-intl / lingui / vue-i18n); BALDART wraps the consumer's framework and best-in-class OSS rather than reimplementing i18n. The `/i18n` skill audits + translates on demand (via the `i18n-translator` agent — Sonnet, low-effort, bounded flag-not-guess); the weekly `i18n-align` routine keeps the maintained `i18n.target_languages` aligned and commits directly to the trunk. Ownership is strict: `coder` (STEP 9) externalizes + populates the registry, `doc-reviewer` curates it, `i18n-translator` translates. Opt-in at `baldart configure`; `baldart doctor` backfills the lint plugin + flags a missing registry. See [`framework/agents/i18n-protocol.md`](framework/agents/i18n-protocol.md) and [`framework/docs/I18N-LAYER.md`](framework/docs/I18N-LAYER.md).

### Curated Toolchain Layer (new in v4.41.0)

When `features.has_toolchain: true`, BALDART becomes opinionated about the *tools* you build with, not just the workflow. On a JS/TS project `baldart configure` PRESELECTS and installs a curated set as devDependencies — **Biome** (format + lint + import organizer), **Vitest**, **tsc**, **Lefthook** (pre-commit) — and records literal gate commands in `toolchain.commands.*`. The quality-gate flows (`/new`, `/new2`, `/qa`, `qa-sentinel`, `coder`) then run those commands verbatim instead of hard-coding `eslint`/`tsc`/`jest`. Opinionated **but askable** (default Y, opt-out) and **non-destructive**: existing ESLint/Prettier/Jest/husky setups are detected and a migration is only ever PROPOSED, never automatic (`.husky/` is never overwritten). Never silent in CI (`baldart doctor` backfills); each gate falls back silently to the project-standard default when its command is unset, so non-JS projects and consumers with their own toolchain are unaffected. Install via `baldart configure` or `/toolchain-bootstrap`. See [`framework/agents/toolchain-protocol.md`](framework/agents/toolchain-protocol.md) and [`framework/docs/TOOLCHAIN-LAYER.md`](framework/docs/TOOLCHAIN-LAYER.md).

### Commands

- **/new**: Batch orchestrator; Claude uses the established orchestration, Codex uses the one-shot resident Model B runtime with typed decision/terminal boundaries
- **/codexreview**: Deep multi-agent code review with mandatory false-positive validation and finding pooling across reviewers
- **/check**: Pre-development parallel quality audits using agent teams
- **/design-review**: UI/UX design review workflow
- **/issue-review**: GitHub issue analysis and context capture

### LLM Wiki Overlay (new in v2.0.0)

A derived, non-canonical knowledge layer (`docs/wiki/`) maintained on two
paths: a nightly `wiki-curator` sweep (synthesis candidates from recent
ADRs/PRDs, anchor + frontmatter validation) and on-demand `/capture` from live
conversations. See `framework/agents/llm-wiki-methodology.md` for the full
methodology and adoption checklist.

### Migrating an Existing Install (v1.x / v2.x → v3.x)

If you already have BALDART installed in an existing project:

```bash
# 1. Pull v3 framework
baldart update

# 2. (v2.0.x → v2.1.1 layout fix, if you skipped that train)
baldart migrate     # idempotent: converts legacy skills layout

# 3. v3 step — populate baldart.config.yml (paths/identity/stack/features)
baldart configure   # interactive prompts + filesystem autodetection

# 4. Confirm
baldart status      # config + overlays + drift
baldart version     # current version + last update / last push
```

Full migration guide (including the v2 → v3 cheat sheet and overlay
authoring): [`framework/docs/PROJECT-CONFIGURATION.md`](framework/docs/PROJECT-CONFIGURATION.md) § 9.

`v3.0 → v3.1` requires no config changes — `state.json` is auto-seeded on
the next CLI invocation (`add` / `update` / `push`).

`baldart migrate` (still available) handles legacy v2.0.x cases:

- Converts the legacy `.claude/skills/` bulk symlink (v2.0.x) into a real directory.
- Re-merges framework skills as per-item symlinks alongside your personal skills.
- Restores `.claude/skills.backup/` content into `.claude/skills/`, leaving name collisions in `.backup/` for manual review.
- Logs unresolved collisions in `.baldart/skill-conflicts.json`.

Safe to re-run; if there's nothing to do, it reports so and exits.

### Scheduled Routines (new in v2.1.0)

The framework now ships **scheduled routines** that make its maintenance and
drift-detection loops actually run. Ship-bundled routines:

| Routine | Cadence | Agent | Purpose |
|---------|---------|-------|---------|
| `wiki-review` | nightly 02:00 UTC | wiki-curator | Maintains the LLM-wiki overlay (candidates, anchors, frontmatter) |
| `doc-review` | nightly 00:00 UTC | doc-reviewer | Audits doc changes, flags SSOT drift |
| `code-review` | nightly 01:00 UTC | code-reviewer | Reviews last-24h commits |
| `doc-graph-align` | nightly 04:00 UTC | doc-graph-aligner | Aligns docs with the Graphify code graph — uncovered core code, stale docs, registry drift (optional, needs `has_code_graph`) |
| `skill-improve` | weekly Sun 02:00 UTC | skill-improver | Refines skills/agents from review patterns |
| `ds-drift` | weekly Mon 03:00 UTC | doc-reviewer | Design-system drift check (optional) |
| `full-sweep` | weekly Sun 03:00 UTC | doc-reviewer | Full SSOT audit (optional) |
| `i18n-align` | weekly Mon 04:00 UTC | i18n-translator | Translates target languages, lints, commits direct to trunk (optional, needs `has_i18n`) |
| `email-align` | weekly Mon 04:30 UTC | doc-reviewer | Email-registry drift reconciliation (deterministic scan + curation; optional, needs `has_email_layer`, v6.34.0) |
| `bug-mine` | weekly Mon 04:00 UTC | skill-improver | Mines the per-project bug registry (`.baldart/bug-registry/`) into classified process proposals + explicit one-off discards (`MODE: bug-miner`, v5.19.0, optional) |
| `finding-mine` | monthly 1st 03:00 UTC | skill-improver | Deep 30-day mining of pooled findings/QA/trackers/reviewer memories into classified improvement proposals (`MODE: miner`, v5.0.0) |

Three backend adapters are bundled:

- **`claude-code-cloud`** — `.claude/routines/<name>.json` for RemoteTrigger
- **`github-actions`** — `.github/workflows/baldart-<name>.yml`
- **`cron`** — `scripts/routines/<name>.sh` + a crontab line

**Review engine (v4.18.0+)** — a review routine (e.g. `code-review`) may set `review_engine: codex`
in its `.routine.yml` to shift the finding pass onto the OpenAI Codex companion (spend a Codex
licence instead of Claude tokens). This is **cron-only** — it needs the Codex plugin + an
authenticated `~/.codex/` in the cron user's home; the `github-actions` and `claude-code-cloud`
backends fall back to the `claude` engine with a warning. On a BALDART consumer
with Multi-agent v2 enabled, the Codex cron pass selects generated specialist
roles through `spawn_agent.agent_type`; an explicit v2 opt-out degrades to the
documented holistic single-pass fallback.

During `baldart add` and `baldart update`, BALDART surfaces routines
the user has never reviewed and prompts to install them. Standalone command:

```bash
baldart routines list          # show status for every routine
baldart routines install wiki-review   # interactive install
baldart routines doctor        # verify installed routines are still healthy
baldart routines disable wiki-review   # remove the schedule
```

### Templates

- `feature-card.template.yml`: Backlog card structure
- `spec.template.md`: Technical specifications
- `breaking-change-checklist.md`: API/schema migration checklist
- `ui-guidelines.template.md`: UI/UX guidelines template
- `brand-guidelines.md`: Brand identity template

## What Gets Installed

```
your-project/
├── .framework/              # Verified private release payload (tracked)
├── AGENTS.md               # Generated from skeleton + config + overlay (cross-tool SSOT)
├── CLAUDE.md               # Generated Claude Code entry (Claude-native mechanics)
├── agents/                  # Symlink → .framework/agents/
├── .claude/
│   ├── agents/             # Symlink → .framework/.claude/agents/
│   ├── commands/           # Symlink → .framework/.claude/commands/
│   ├── skills/             # Per-item merge dir (v2.1.1+): framework symlinks alongside your own skills
│   ├── workflows/          # Per-item symlinks of framework dynamic workflows (v4.14.0+, Claude-only)
│   ├── output-styles/      # Per-item symlinks of framework output styles (v4.50.0+, Claude-only; latent — activate via /config)
│   └── hooks/              # Customizable copies
├── baldart.config.yml      # Project context: paths/identity/stack/features (v3.0.0+)
├── .baldart/
│   ├── state.json          # Centralized versioning ledger (v3.1.0+, managed by CLI)
│   └── overlays/           # Your per-skill project-specific overrides (v3.0.0+)
├── docs/references/
│   ├── ui-guidelines.template.md    # Customize for your project
│   └── brand-guidelines.md          # Customize for your project
└── templates/               # Customizable backlog/spec templates
```

## Daily Workflow

### 1. Create Backlog Card

```bash
# Copy template
cp templates/feature-card.template.yml backlog/FEAT-001.yml

# Edit card with your requirements
```

### 2. Implement with Framework

```bash
# Framework guides agent coordination automatically
# Use /new command for batch implementation
/new FEAT-001
```

### 3. Update Framework

```bash
# Check for updates
baldart status

# Update to latest
baldart update
```

### 4. Contribute Back

```bash
# Made improvements? Share them!
baldart push
```

## Customization

### Files You SHOULD Customize

1. **`.claude/hooks/lint-before-commit.sh.template`**
   - Replace commands with your project's tools
   - Rename to `lint-before-commit.sh`
   - Make executable: `chmod +x .claude/hooks/lint-before-commit.sh`

2. **`docs/references/ui-guidelines.template.md`**
   - Define brand colors, typography, spacing
   - Document component patterns
   - Rename to `ui-guidelines.md`

3. **`docs/references/brand-guidelines.md`**
   - Add logo specifications
   - Define brand voice and tone
   - Document imagery guidelines

4. **`templates/*.yml`**
   - Adapt backlog card template
   - Add project-specific fields

5. **`baldart.config.yml`** (v3.0.0+)
   - Paths, identity, stack, feature flags for your project
   - Generated by `baldart configure` — re-run any time to refresh
   - Never overwritten by `baldart update`

6. **`.baldart/overlays/<skill>.md`** (v3.0.0+)
   - Per-skill project-specific extensions (brand voice, mandated stack, custom workflows)
   - Examples in `.framework/templates/overlays/`
   - Never overwritten by `baldart update`

### Files You SHOULD NOT Modify

Files with symlinks auto-update when framework updates:

- `AGENTS.md`
- `agents/`
- `.claude/agents/`
- `.claude/commands/`
- `.claude/workflows/` (v4.14.0+) — framework dynamic workflows, per-item symlinks (Claude-only; no Codex equivalent)
- `.claude/output-styles/` (v4.50.0+) — framework output styles, per-item symlinks (Claude-only; latent — installs without activating, toggle via `/config` → Output Style)

Files managed by the CLI:

- `.baldart/state.json` (schema v2) — distribution, installed asset/checksum,
  source repo and event ledger. It never contains credentials.

## Commands Reference

### `baldart add [repo]`

Install framework in your project.

- `repo`: Optional. Default: `antbald/BALDART`
- `--ack-private-storage`: explicit acknowledgement when remote visibility
  cannot be verified. A verified public consumer is always refused.

**Example:**
```bash
baldart add              # Install from default repo
baldart add owner/repo   # Install from custom fork
```

### `baldart update`

Update framework to latest version — **seamless** (v4.8.0+): one command, zero
iterations. The job is always the same — update and preserve overlays — so the
CLI does the whole thing in one shot:

- Resolves the latest private GitHub Release
- Downloads payload + `SHA256SUMS` into staging and verifies every manifest file
- Auto-stashes any non-framework work and re-applies it after (single blanket
  stash; handles tracked files inside `.gitignore`d dirs)
- Creates a backup tag (`git reset --hard <tag>` to roll back)
- Refuses committed or uncommitted payload drift until it is preserved through
  `baldart push` or overlays
- Atomically swaps `.framework/`, reconciles Claude/Codex artifacts and updates
  the schema-v2 ledger

It stops **once** only when an edit cannot be captured+verified faithfully (a
section deletion, a frontmatter/preamble change, a `src/` change) — never a
silent destructive action.

**For agents / CI (v3.32.0+):** `baldart update --json --yes` emits a single
machine-readable result object on stdout (`{schema:"baldart.update/1", ok,
action, installed_after, backup_tag, blockers, next_command, …}`) with all human
output on stderr — no prose to scrape. `ok:true` ⟺ the framework is now at the
remote version (`action` is `updated`, `reset`, or `already-current`). The escape
hatches `--reset --yes --i-know` and `--on-divergence pull|scaffold-overlays|abort`
still exist for power users, but the seamless default makes them unnecessary.
`--json` requires `--yes` and rejects an explicit `--reset`.

### `baldart` (no args) / `doctor` (v3.2.0+)

Smart diagnostic that detects the install state and proposes the next sensible
action (install, migrate legacy layout, configure, refresh config schema,
update, push, repair symlinks, reap orphaned Codex MCP servers, or "nothing to
do"). Prints a status table then runs the proposed actions with confirmation per
step.

Since v4.37.0 it also surfaces **orphaned MCP-server processes left by Codex
calls** — every BALDART Codex finder call (`/new`, `new2`, `/codexreview`, the
cron review engine) drives `codex app-server`, whose detached broker spawns the
MCP servers from `~/.codex/config.toml` (Playwright, …) and leaks them to init
(ppid 1) when it dies, where they keep burning CPU. The doctor reaps the
orphaned MCP servers (and their browser children) directly via syscall; the live
`codex app-server` broker is never touched.

For projects with Codex enabled, install/update/migrate also opts the repository into
Codex's stable native Multi-agent v2 backend through `.codex/config.toml`.
Existing Codex project settings are merged additively; an explicit
`multi_agent_v2 = false` remains authoritative. `doctor` compares file state
with the effective CLI state, reports missing/disabled/untrusted-session drift,
and can add a missing opt-in safely.
Generated roles are selected with `spawn_agent.agent_type`; each work item uses
a separate snake-case `task_name`. Portable orchestrator skills use the native
v2 lifecycle directly. `/prd` is host-v2 first; `/new` keeps its resident Model
B subprocess engine because v2 workers cannot yet join its atomic receipt,
usage, worktree, cancellation, and cleanup transaction.

Since v4.38.0 it also checks **external-tool version currency** — BALDART pins
none of the tools it installs (`graphifyy` via pipx, language servers via npm),
and pipx/npm never auto-upgrade, so an old install silently misses upstream
security/correctness fixes. The doctor probes the managed tools against their
registries (PyPI / npm) and surfaces a non-blocking one-command upgrade for any
confirmed behind upstream (e.g. `Upgrade Graphify 0.8.36 → 0.8.39`). Network-gated
— skipped under `--offline`, silent when everything is current.

```bash
baldart            # diagnostic + interactive prompts
baldart --auto     # CI-friendly: skip y/n; error out on ambiguity
baldart --offline  # skip the upstream fetch
baldart doctor     # explicit alias (same behaviour)
```

### `baldart version`

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

### `baldart push` / `/baldart-push` (v3.1.0+)

Contribute local framework improvements through a private pull request:

- Downloads the pristine asset matching `installed_version` and computes the
  payload diff.
- Runs contamination autofix/review and blocks credentials.
- Clones private BALDART into a temporary directory, maps
  `.framework/framework/*` to `framework/*`, creates `codex/...`, pushes it and
  opens a private PR.
- Deletes the temporary clone. Consumer files never enter the PR.

Either invoke via the slash command (conversational orchestration in Claude
Code) or directly via CLI:

```bash
baldart push
```

### `baldart configure`

Generate / update `baldart.config.yml` (project paths, identity, stack, feature flags).
Interactive prompts with filesystem autodetection. Idempotent — re-running merges into
the existing file without clobbering user values.

- `--non-interactive`: write autodetected values without prompts (for CI).

Full guide: [`framework/docs/PROJECT-CONFIGURATION.md`](framework/docs/PROJECT-CONFIGURATION.md).

### `baldart status`

Check installation status:
- Framework version
- Symlink validity
- Customizable files presence
- Update availability

## Architecture

### Private release strategy

- **Distribution:** GitHub Release assets only; npm is a final bootstrap bridge.
- **Consumer storage:** `.framework/` remains tracked so private clones work
  without hydration. Public consumers are refused.
- **Authentication:** `BALDART_GH_TOKEN` → `GH_TOKEN` → `gh` credential store;
  credentials are never persisted by BALDART.
- **Updates:** verified staging + atomic swap.
- **Contributions:** private patch branch and PR; no subtree operation.
- **Bat-beacon:** private issue plus gzip/base64 transcript comments; Issues
  write only.

## Versioning

BALDART follows [Semantic Versioning](https://semver.org/):

- **MAJOR** (X.0.0): Breaking changes (incompatible updates)
- **MINOR** (0.X.0): New features (backwards compatible)
- **PATCH** (0.0.X): Bug fixes (backwards compatible)

Check version:
```bash
baldart version
```

## Troubleshooting

### "Framework not installed" error

```bash
# Install framework first
baldart add
```

### Symlinks broken after update

```bash
# Reinstall to recreate symlinks
baldart add
```

### Conflicts during update

```bash
# Check conflicting files
git status

# Choose resolution
git checkout --ours <file>    # Keep your version
git checkout --theirs <file>  # Use framework version

# Complete merge
git add <resolved-files>
git commit -m "Resolved framework update conflicts"
```

### Rollback after bad update

```bash
# Find backup tag (created by update)
git tag | grep backup/

# Rollback
git checkout backup/YYYY-MM-DD-HH-MM-SS
git checkout -b recovery-branch
```

## Requirements

- **Node.js**: >= 18.0.0
- **Git**: >= 2.0.0
- **npm**: >= 8.0.0
- **GitHub CLI**: authenticated with access to private `antbald/BALDART`

Full access, CI, migration and recovery guide:
[`framework/docs/PRIVATE-DISTRIBUTION.md`](framework/docs/PRIVATE-DISTRIBUTION.md).

## License

MIT

## Contributing

Contributions from authorized collaborators use private PRs. See
**[MAINTAINING.md](MAINTAINING.md)**.

**Quick process:**

1. Make improvements in your project
2. Test thoroughly
3. Run `baldart push` and review the private PR
4. Maintainer classifies MAJOR/MINOR/PATCH and updates changelog/version
5. Maintainer tags; the private release workflow publishes verified assets

**For agents:** Follow the complete checklist in [MAINTAINING.md](MAINTAINING.md) to ensure proper versioning, documentation, and release process.

## Repository

- **GitHub**: https://github.com/antbald/BALDART
- **Install**: `baldart add`
- **Issues**: https://github.com/antbald/BALDART/issues

## Credits

Created for coordinating AI agents and humans in software development.

## Support

- **Current Version**: `cat VERSION`
- **Changelog**: See [CHANGELOG.md](CHANGELOG.md)
- **Maintenance Protocol**: See [MAINTAINING.md](MAINTAINING.md)
- **Check Status**: `baldart status`
- **Check Version**: `baldart version`
- **Issues**: https://github.com/antbald/BALDART/issues