# BALDART Skill Overlay Examples

This directory contains **reference overlays** distilled from a real project
(the multi-merchant "fidelity-app" Loyalty/CRM platform) that used to live
hard-coded inside BALDART skills before v3.0.0.

## How to use

1. Run `npx baldart configure` in your consumer repo — this generates
   `baldart.config.yml`.
2. Copy any overlay example you want to adopt into
   `.baldart/overlays/<skill-name>.md` (e.g.
   `cp .framework/templates/overlays/ui-design.fidelity-example.md
    .baldart/overlays/ui-design.md`).
3. Edit freely. The framework never touches `.baldart/overlays/` on update.

## Conventions

Every overlay file has YAML frontmatter:

```yaml
---
base_skill: <skill-name>          # MUST match the skill directory name
base_skill_version: <semver>      # framework version when authored
base_file_sha: "<12-char-sha>"    # optional (v3.19.0+) — base file content sha for accurate drift detection
mode: extend | override           # default: extend
---
```

For agent overlays use `base_agent` / `base_agent_version`, and for command
overlays `base_command` / `base_command_version`.

The optional `base_file_sha` (v3.19.0+) records the sha256 prefix (12 chars)
of the base file at the moment the overlay was scaffolded. When present,
`npx baldart overlay drift` uses it to detect base-file changes precisely
instead of falling back to a version-string compare. The value MUST be
quoted because an all-digit hex like `000000000000` would otherwise be
parsed as a number by YAML. The `npx baldart overlay scaffold` CLI writes
this field automatically; hand-written overlays may omit it (drift detection
silently degrades to the version-only fallback — no error).

Sections marked `## [OVERRIDE] <topic>` replace the same `<topic>` from the
base skill. Everything else extends the base.

Full protocol: [`framework/agents/project-context.md`](../../agents/project-context.md) § 5.

## Available examples

| File | Replaces hard-coded content from |
|------|------|
| `ui-design.fidelity-example.md` | Neo-Brutalism, Recharts/nivo charting stack, merchant theming pairing, Safari open command, evaluation thresholds |
| `copywriting.fidelity-example.md` | 4-pillar brand voice, Italian-only rule, segment register matrix (customer/merchant/staff/admin), forbidden vocabulary |
| `new.migration-example.md` | Migration-Gate apply modalities (`/new` Phase 0 step 1b · `new2` Step 3.5) — how this project front-loads a declared DB migration (db:push / local apply / Prisma deploy) before the batch |

Other overlay examples may be added over time. Skills that did not have
heavy hard-coded opinions (e.g. `find-skills`, `simplify`) don't need
example overlays — write your own only when your project has
opinions to enforce.
