baldart 3.6.2

package/framework/docs/PROJECT-CONFIGURATION.md

@@ -0,0 +1,336 @@
+<!-- contamination-scan: skip
+     This guide deliberately shows literal `docs/design-system/INDEX.md`,
+     `src/components/ui/`, "Neo-Brutalism", etc. as examples of what
+     `baldart configure` autodetects and what consumers replace with config
+     keys. Autofixing them would destroy the guide's pedagogical value. -->
+# BALDART Project Configuration
+
+This guide explains the v3.x configuration system that lets you reuse the same BALDART skills across projects with different file layouts, design philosophies, technology stacks, and audience segments — without forking the framework.
+
+If you are migrating an existing v2.x install, jump to **§ 9 Migration Cheat Sheet**.
+
+## What changed in v3.1.0
+
+v3.0.0 introduced the configuration system (`baldart.config.yml`, overlays, `${paths.X}` indirection). v3.1.0 added on top:
+
+- **Centralized versioning** via `.baldart/state.json` — `baldart version` now reports installed version + install date + drift from remote + last-push info.
+- **Automated contribution flow** — `baldart push` now auto-bumps `VERSION`, writes the CHANGELOG entry, creates the annotated tag, and runs a contamination scan with autofix (no more "next steps required" manual workflow).
+- **`/baldart-push` skill** for conversational guidance through the contribution flow.
+
+There are no config-schema changes between v3.0 and v3.1; existing `baldart.config.yml` files keep working. `state.json` is auto-seeded on the first `add` / `update` / `push` after upgrading.
+
+## 1. Why this exists
+
+Before v3.0.0, BALDART skills hard-coded the paths and opinions of a single reference project (a multi-merchant fidelity / loyalty platform). Examples that used to live inside `ui-design/SKILL.md`:
+
+- `docs/design-system/INDEX.md` as a BLOCKING read
+- `src/components/ui/` as the primitives root
+- "Neo-Brutalism" as the design philosophy
+- "Recharts v3 + `@nivo/heatmap` only" as the charting stack
+- `merchant` and `customer` as the audience segments
+
+Drop the same framework into a SaaS admin tool with no design system, a TypeScript backend with no UI, or a marketing site with shadcn defaults — and the skills broke or produced wrong output.
+
+v3.0.0 solves this with **three layers**:
+
+1. `baldart.config.yml` — structural facts (paths, identity, stack, feature flags).
+2. Skills reference `${paths.X}` etc. instead of hard-coded paths.
+3. `.baldart/overlays/<skill>.md` — project-specific opinions that extend or override base skill rules.
+
+The protocol is documented in [`framework/agents/project-context.md`](../agents/project-context.md). This document is the practical user-facing guide.
+
+## 2. The three layers at a glance
+
+```
+your-repo/
+├── baldart.config.yml          ← Layer 1: structural facts (committed, customizable)
+├── .baldart/
+│   └── overlays/                ← Layer 3: project-specific opinions (committed)
+│       ├── ui-design.md
+│       ├── copywriting.md
+│       └── ...
+└── .framework/                  ← Layer 2: framework payload (do not edit)
+    └── .claude/skills/<name>/
+        └── SKILL.md             ← Generic, references layer 1 keys
+```
+
+| Layer | File | Updated by `baldart update`? | Authored by |
+|---|---|---|---|
+| 1 — Variables | `baldart.config.yml` | Never | You (via `baldart configure`) |
+| 2 — Skills (generic) | `.framework/.../SKILL.md` | Yes (symlinked) | Framework |
+| 3 — Overlays | `.baldart/overlays/*.md` | Never | You |
+
+## 3. First-run workflow
+
+```bash
+# 1. Install the framework
+npx baldart add
+
+# 2. Generate the config (interactive — autodetects ~80% of values)
+#    Already invoked at the end of `add` unless you skipped it.
+npx baldart configure
+
+# 3. (Optional) Author overlays for the skills that have project-specific opinions
+cp .framework/templates/overlays/ui-design.fidelity-example.md \
+   .baldart/overlays/ui-design.md
+$EDITOR .baldart/overlays/ui-design.md
+
+# 4. Commit everything
+git add baldart.config.yml .baldart/overlays/
+git commit -m "chore: BALDART v3 project configuration"
+```
+
+## 4. `baldart.config.yml` schema
+
+Source of truth: [`framework/templates/baldart.config.template.yml`](../templates/baldart.config.template.yml). The four top-level sections:
+
+### 4.1 `version`
+
+Schema version (integer). Bumped only when `paths.*` / `features.*` keys change in a backwards-incompatible way. `baldart update` warns if the framework expects a higher version than your config declares.
+
+### 4.2 `paths` — where the project's canonical docs and source roots live
+
+Empty string `""` means the concept doesn't exist in your project. Skills gated by the matching `features.*` flag will skip the related BLOCKING read when both the path is empty and the feature is `false`.
+
+| Key | Typical value | Used by |
+|---|---|---|
+| `design_system` | `docs/design-system` | ui-design, frontend-design, prd, bug, kie-ai, simplify, playwright-skill, webapp-testing, gamification-design |
+| `ui_guidelines` | `docs/references/ui-guidelines.md` | ui-design, frontend-design, copywriting, gamification-design |
+| `api_index` | `docs/references/api/index.md` | doc-writing-for-rag |
+| `api_schemas` | `docs/references/api/schemas.md` | doc-writing-for-rag |
+| `api_errors` | `docs/references/errors.md` | doc-writing-for-rag |
+| `components_primitives` | `src/components/ui` | ui-design, simplify |
+| `components_root` | `src/components` | ui-design, simplify |
+| `global_styles` | `src/app/globals.css` | ui-design |
+| `backlog_dir` | `backlog` | new, prd, context-primer |
+| `adrs_dir` | `docs/decisions` | prd, prd-add |
+| `prd_dir` | `docs/prd` | prd, prd-add, ui-design |
+| `references_dir` | `docs/references` | new, prd, context-primer, doc-writing-for-rag, simplify |
+| `wiki_dir` | `docs/wiki` | capture, context-primer |
+| `e2e_tests_dir` | `tests/e2e` | playwright-skill |
+
+### 4.3 `identity` — brand and audience facts
+
+| Key | Type | Notes |
+|---|---|---|
+| `brand_name` | string | Public product name |
+| `design_philosophy` | string | Free-form, one line. Examples: `"Neo-Brutalism"`, `"Glassmorphism"`, `"Minimalist"`, `"Material 3"`, `""` (no opinion). Drives aesthetic decisions in `ui-design`, `frontend-design`, `kie-ai`, `motion-design`. |
+| `language` | BCP-47 tag | `"en"`, `"it"`, etc. Drives copy register in `copywriting`, error-message language in `ui-design`. |
+| `audience_segments` | array of strings | Domain split, e.g. `["merchant","customer"]` or `["b2b","b2c"]`. Empty `[]` = no segmentation. Drives prompts in `copywriting`, evaluation in `ui-design`. |
+
+### 4.4 `stack` — technology choices skills must respect
+
+```yaml
+stack:
+  charting:
+    canonical: ["recharts", "@nivo/heatmap"]
+    forbidden: ["chart.js", "echarts", "victory"]
+    wrappers_root: "src/components/charts"   # optional project wrappers
+  animation:
+    canonical: ["framer-motion"]
+    forbidden: []
+  testing:
+    e2e: "playwright"                         # or "cypress", or ""
+```
+
+Skills propose only `canonical` libraries and refuse `forbidden` ones. Empty `canonical` = ask the user before proposing a library.
+
+### 4.5 `features` — explicit booleans gating BLOCKING reads
+
+Every flag MUST be present as `true` or `false` once `baldart configure` has run. **Never default to `false` from absence** — that breaks the always-ask contract. Skills prompt and persist if a flag is missing.
+
+| Flag | Meaning |
+|---|---|
+| `has_design_system` | The project has docs rooted at `paths.design_system`. When `true`, `ui-design`, `bug`, `frontend-design`, `simplify`, `playwright-skill` etc. treat the INDEX as BLOCKING. |
+| `multi_tenant_theming` | The project supports per-tenant theme overrides. Activates themed-surface text/bg pairing rules in `ui-design`, `playwright-skill`, `webapp-testing`. |
+| `has_api_docs` | Canonical API docs at `paths.api_index`. Gates `doc-writing-for-rag` schemas/errors workflow. |
+| `has_backlog` | Card-driven workflow (`paths.backlog_dir` + AGENTS.md card protocol). `new` skill refuses to run without it. |
+| `has_adrs` | ADR workflow. Architectural decisions get logged in `paths.adrs_dir`. |
+| `has_prd_workflow` | PRD workflow (`paths.prd_dir`). `/prd` and `/prd-add` skills refuse to run without it. |
+| `has_wiki_overlay` | LLM-wiki overlay (`paths.wiki_dir`). `/capture` skill refuses to run without it. |
+
+## 5. The overlay system
+
+Overlays let you keep project-specific opinions out of `baldart.config.yml` (which is for structural facts only). They live in `.baldart/overlays/<skill-name>.md`, one file per skill that needs project-specific extension.
+
+### 5.1 Frontmatter
+
+```yaml
+---
+base_skill: ui-design          # MUST match the skill directory name
+base_skill_version: 3.0.0      # framework version this overlay was authored against
+mode: extend                   # extend (default) | override
+---
+```
+
+- `mode: extend` (default) — overlay rules are **added** to the base skill.
+- `mode: override` — sections in the overlay **replace** conflicting sections in the base.
+- Inside any overlay, a section marked `## [OVERRIDE] <topic>` replaces the same `<topic>` from the base skill regardless of mode.
+
+### 5.2 Precedence
+
+When base skill, config, and overlay all have something to say:
+
+1. **Config wins on facts** (paths, feature flags, identity).
+2. **Overlay wins on opinions** (stricter thresholds, mandated styles, forbidden vocabulary). If overlay overrides a config value, the skill emits a one-line notice in its output.
+3. **Base skill provides the default** when neither config nor overlay applies.
+
+### 5.3 Version drift
+
+`baldart status` and `baldart update` check `base_skill_version` against the installed framework version. When the framework advances past an overlay's version:
+
+- The skill loads the overlay normally.
+- It emits a single-line WARNING at the start of its output: `overlay <name> targets v<X>, installed v<Y> — review for drift`.
+- `baldart status` lists drifted overlays.
+
+Non-blocking by design. Silent overrides are worse than noisy ones.
+
+### 5.4 Recommended skills to author overlays for
+
+These skills had heavy hard-coding before v3.0.0; if your project has opinions in any of these areas, an overlay is the place for them:
+
+| Skill | Common overlay content |
+|---|---|
+| `ui-design` | Design philosophy mandates, theming pairing rules, charting wrappers, browser open command, evaluation thresholds |
+| `copywriting` | Brand voice pillars, audience register matrix, forbidden vocabulary, language-only rules |
+| `frontend-design` | Aesthetic mandates, illustration-motion contract |
+| `prd` / `prd-add` | Project terminology, mandatory review gates, design-system reads for UI PRDs |
+| `kie-ai` | Illustration character library, video-prompt motion vocabulary, forbidden aesthetics |
+| `bug` | Project debug entry points (env summary helper, cache debug switch, error-code module) |
+| `playwright-skill` / `webapp-testing` | Test URLs, auth helpers, theming token-pair assertions |
+| `capture` | Wiki-log helper import path, domain vocabulary |
+| `gamification-design` | Reward economy facts, customer surface motion vocabulary |
+
+The framework ships starter examples for the heaviest ones in `framework/templates/overlays/`:
+
+- `ui-design.fidelity-example.md`
+- `copywriting.fidelity-example.md`
+
+## 6. Skill behaviour when config is missing or empty
+
+**Always-ask, never-assume**. Configured in v3.0.0 per option A.
+
+If a skill encounters:
+
+- A `paths.X` key that is `""` and is required for the current task → ask the user.
+- A `features.Y` flag that is **absent from the YAML** (not just `false`) → ask the user, persist the answer.
+- A `stack.Z.canonical` array that is empty and is required → ask the user.
+
+The skill suggests running `npx baldart configure` so the answer is durable. If the user declines, the skill proceeds with the provided value, marking it as ASSUMED in its output.
+
+Never:
+
+- Default to `false` from absence.
+- Invent a path.
+- Silently skip a BLOCKING read.
+
+## 7. Example: ground-up config for a fresh React SaaS
+
+```yaml
+version: 1
+paths:
+  design_system: ""                           # no formal DS yet
+  ui_guidelines: docs/style-guide.md
+  api_index: ""
+  api_schemas: ""
+  api_errors: ""
+  components_primitives: src/components/ui
+  components_root: src/components
+  global_styles: src/index.css
+  backlog_dir: ""                             # using Linear, not local backlog
+  adrs_dir: docs/decisions
+  prd_dir: ""
+  references_dir: docs
+  wiki_dir: ""
+  e2e_tests_dir: tests/e2e
+identity:
+  brand_name: "Acme SaaS"
+  design_philosophy: "Minimalist"
+  language: en
+  audience_segments: ["admin", "end-user"]
+stack:
+  charting:
+    canonical: ["recharts"]
+    forbidden: []
+    wrappers_root: ""
+  animation:
+    canonical: ["framer-motion"]
+    forbidden: []
+  testing:
+    e2e: "playwright"
+features:
+  has_design_system: false
+  multi_tenant_theming: false
+  has_api_docs: false
+  has_backlog: false                          # disables /new
+  has_adrs: true
+  has_prd_workflow: false                     # disables /prd
+  has_wiki_overlay: false                     # disables /capture
+```
+
+In this project, `/new`, `/prd`, `/prd-add`, `/capture` refuse to run (they require their workflow). `ui-design` operates with `paths.ui_guidelines` only as its BLOCKING read, and applies a Minimalist aesthetic with English copy targeting admin or end-user.
+
+## 8. Example: porting the legacy fidelity-app
+
+The pre-v3.0.0 BALDART skills assumed this project. To reproduce that behavior exactly:
+
+```bash
+npx baldart configure
+```
+
+Autodetection should populate most values. Then drop in the example overlays:
+
+```bash
+cp .framework/templates/overlays/ui-design.fidelity-example.md \
+   .baldart/overlays/ui-design.md
+cp .framework/templates/overlays/copywriting.fidelity-example.md \
+   .baldart/overlays/copywriting.md
+```
+
+Open both and edit. They contain the Neo-Brutalism + Recharts + merchant-theming + 4-pillar-brand-voice content that used to live in the skills. Adapt freely — these are starting points.
+
+## 9. Migration cheat sheet (v2.x → v3.x)
+
+If your project was using BALDART v2.x:
+
+1. `npx baldart update` — pulls v3.0.0, runs configure-check.
+2. `npx baldart configure` — interactive prompts, autodetection. Confirm each detected path/flag.
+3. For each opinionated skill you actually used (ui-design, copywriting, bug, etc.):
+   - If you relied on the pre-v3 hard-coded opinions (Neo-Brutalism, merchant/customer, Recharts-only): copy the matching `*.fidelity-example.md` from `.framework/templates/overlays/` into `.baldart/overlays/` and adapt.
+   - If you want the generic behavior: do nothing, skip the overlay.
+4. `npx baldart status` — verify config, overlays, and any version-drift warnings.
+5. Commit `baldart.config.yml` and `.baldart/overlays/`.
+
+The skills will fail loudly (asking the user) if anything required is missing — there is no silent degradation.
+
+### v3.0 → v3.1 upgrade
+
+No config changes needed. After `npx baldart update`:
+
+- `.baldart/state.json` is seeded automatically on the next CLI invocation (`add` / `update` / `push`).
+- `npx baldart version` will show enriched output (install date, remote drift, last-push info).
+- `npx baldart push` now auto-bumps `VERSION` and writes the CHANGELOG entry instead of leaving them as manual steps.
+- `/baldart-push` is the new slash skill that walks you through the contribution flow.
+
+## 10. FAQ
+
+**Q. Can I edit `baldart.config.yml` directly?**
+Yes. It's a regular YAML file. `baldart configure` re-runs interactively and preserves your edits.
+
+**Q. Can I author overlays without ever running `baldart configure`?**
+You'd need to hand-write `baldart.config.yml`. Use the template at `framework/templates/baldart.config.template.yml` as a starting point.
+
+**Q. How do skills know which overlay to load?**
+Convention: `.baldart/overlays/<skill-name>.md`, where `<skill-name>` matches the skill directory name (e.g. `ui-design`, not `UI Design`).
+
+**Q. Can one overlay reference another?**
+No cross-overlay references. Each overlay extends only its own base skill. If two skills share opinions (e.g. design philosophy), put the opinion in `baldart.config.yml` (`identity.design_philosophy`) — that's exactly what the config is for.
+
+**Q. What if the framework removes a config key in a future version?**
+That's a MAJOR version bump (`baldart push` will prompt for the classification). The CHANGELOG documents the removed key and a migration step. Your old config is preserved on disk; the new framework version simply ignores the unknown key.
+
+**Q. Where does `baldart update` log changes to my config?**
+It never modifies `baldart.config.yml`. It only warns when the framework's template gained new keys not yet in your config — you decide if and when to re-run `configure`.
+
+**Q. The autodetection got something wrong. How do I correct it?**
+Re-run `npx baldart configure`. Each prompt shows the autodetected default; type a different value to override.

package/framework/docs/references/brand-guidelines.md

@@ -0,0 +1,170 @@
+# Brand Guidelines (Template)
+
+This is a template for documenting your project's brand guidelines. Customize for your project.
+
+## Brand Overview
+
+### Mission
+
+[Your mission statement]
+
+### Vision
+
+[Your vision statement]
+
+### Values
+
+- [Value 1]
+- [Value 2]
+- [Value 3]
+
+## Visual Identity
+
+### Logo
+
+**Primary Logo**:
+- [Description]
+- Minimum size: [dimensions]
+- Clear space: [specifications]
+- File formats: SVG, PNG
+
+**Logo Variations**:
+- Full color
+- Monochrome
+- Reversed (light on dark)
+
+**Logo Usage**:
+- Do: [List correct usage]
+- Don't: [List incorrect usage - stretching, recoloring, etc.]
+
+### Color Palette
+
+See `ui-guidelines.template.md` for detailed color specifications.
+
+**Brand Colors**:
+- Primary: [color] - [meaning/usage]
+- Secondary: [color] - [meaning/usage]
+- Accent: [color] - [meaning/usage]
+
+## Typography
+
+### Brand Fonts
+
+**Primary Typeface**: [Font Name]
+- Use for: Headings, important text
+- Weights: [list available weights]
+
+**Secondary Typeface**: [Font Name]
+- Use for: Body copy, long-form content
+- Weights: [list available weights]
+
+### Typography Hierarchy
+
+See `ui-guidelines.template.md` for detailed type scale.
+
+## Voice & Tone
+
+### Brand Voice
+
+[Describe your brand personality - professional, friendly, casual, authoritative, etc.]
+
+**Characteristics**:
+- [Characteristic 1]: [Explanation]
+- [Characteristic 2]: [Explanation]
+- [Characteristic 3]: [Explanation]
+
+### Tone Variations
+
+**Formal situations**:
+- [When and how to use]
+
+**Casual situations**:
+- [When and how to use]
+
+**Error/problem situations**:
+- [How to communicate empathetically]
+
+### Writing Guidelines
+
+- Active voice preferred
+- Clear, concise language
+- Avoid jargon unless necessary
+- Use contractions appropriately
+- [Other project-specific guidelines]
+
+## Imagery
+
+### Photography Style
+
+- [Describe visual style]
+- [Color treatment]
+- [Subject matter]
+- [Composition guidelines]
+
+### Illustrations
+
+- [Style guidelines]
+- [Color usage]
+- [When to use]
+
+### Icons
+
+- [Icon style - outline, filled, etc.]
+- [Size specifications]
+- [Color usage]
+
+## Applications
+
+### Web
+
+- Responsive design requirements
+- Minimum browser support
+- Performance standards
+
+### Print
+
+- Minimum resolutions
+- Color profiles
+- Paper specifications
+
+### Social Media
+
+- Profile image specifications
+- Cover image specifications
+- Post image specifications
+
+## Brand Usage
+
+### Dos
+
+- [Correct usage examples]
+- [Approved variations]
+- [Proper contexts]
+
+### Don'ts
+
+- [Incorrect usage examples]
+- [Prohibited modifications]
+- [Inappropriate contexts]
+
+## Asset Library
+
+### Where to Find Assets
+
+- Logo files: [location]
+- Brand fonts: [location]
+- Image library: [location]
+- Templates: [location]
+
+### File Naming
+
+[Describe naming conventions for brand assets]
+
+## Contact
+
+For brand guideline questions:
+- [Contact name/role]
+- [Email]
+
+For design system updates:
+- [Repository/documentation link]

package/framework/docs/references/ui-guidelines.template.md

@@ -0,0 +1,182 @@
+# UI Guidelines (Template)
+
+This is a template for documenting your project's UI/UX guidelines. Customize this file for your project.
+
+## Brand Identity
+
+### Colors
+
+**Primary Palette**:
+- Primary: `#[color]` - [When to use]
+- Secondary: `#[color]` - [When to use]
+- Accent: `#[color]` - [When to use]
+
+**Neutral Palette**:
+- Black: `#000000`
+- White: `#FFFFFF`
+- Gray scale: [Define your grays]
+
+**Semantic Colors**:
+- Success: `#[color]`
+- Warning: `#[color]`
+- Error: `#[color]`
+- Info: `#[color]`
+
+### Typography
+
+**Font Families**:
+- Headings: `[Font name]`
+- Body: `[Font name]`
+- Monospace: `[Font name]`
+
+**Type Scale**:
+- H1: `[size]` / `[line-height]` / `[weight]`
+- H2: `[size]` / `[line-height]` / `[weight]`
+- H3: `[size]` / `[line-height]` / `[weight]`
+- H4: `[size]` / `[line-height]` / `[weight]`
+- Body: `[size]` / `[line-height]` / `[weight]`
+- Small: `[size]` / `[line-height]` / `[weight]`
+
+### Spacing
+
+**Spacing Scale**:
+- xs: `[value]`
+- sm: `[value]`
+- md: `[value]`
+- lg: `[value]`
+- xl: `[value]`
+- 2xl: `[value]`
+
+## Component Patterns
+
+### Buttons
+
+**Primary Button**:
+- Background: [color]
+- Text: [color]
+- Hover: [behavior]
+- Disabled: [state]
+
+**Secondary Button**:
+- Background: [color]
+- Text: [color]
+- Hover: [behavior]
+- Disabled: [state]
+
+### Forms
+
+**Input Fields**:
+- Border: [style]
+- Focus: [state]
+- Error: [state]
+- Disabled: [state]
+
+**Labels**:
+- Position: [above/inline/floating]
+- Required indicator: [style]
+
+### Cards
+
+**Card Structure**:
+- Border: [style]
+- Shadow: [value]
+- Padding: [value]
+- Border radius: [value]
+
+## Layout
+
+### Grid System
+
+- Columns: [number]
+- Gutter: [value]
+- Container max-width: [value]
+
+### Breakpoints
+
+- Mobile: `< [value]`
+- Tablet: `[value] - [value]`
+- Desktop: `> [value]`
+
+### Responsive Design
+
+- Mobile-first approach
+- Touch target minimum: 44x44px
+- Readable line length: 50-75 characters
+
+## Accessibility
+
+### Color Contrast
+
+- Text on background: minimum 4.5:1
+- Large text: minimum 3:1
+- UI components: minimum 3:1
+
+### Keyboard Navigation
+
+- All interactive elements keyboard accessible
+- Visible focus indicators
+- Logical tab order
+
+### Screen Readers
+
+- Semantic HTML
+- ARIA labels where needed
+- Alt text for images
+- Form labels proper
+
+## Animation
+
+### Motion Principles
+
+- Duration: [fast/medium/slow values]
+- Easing: [easing functions]
+- Purpose: [enhance UX, don't distract]
+
+### Common Animations
+
+- Page transitions: [description]
+- Hover states: [description]
+- Loading states: [description]
+- Error states: [description]
+
+## Design Tokens
+
+Document your design tokens (if using):
+
+```json
+{
+  "color": {
+    "primary": "[value]",
+    "secondary": "[value]"
+  },
+  "spacing": {
+    "sm": "[value]",
+    "md": "[value]"
+  }
+}
+```
+
+## Component Library
+
+Link to your component library or design system:
+
+- [Figma/Sketch file]
+- [Storybook URL]
+- [Component documentation]
+
+## Examples
+
+### Good Examples
+
+[Screenshots or code examples of well-implemented UI]
+
+### Anti-Patterns
+
+[Examples of what to avoid]
+
+## Resources
+
+- [Design system documentation]
+- [Brand guidelines]
+- [Component library]
+- [Accessibility guidelines]