baldart 3.6.2

package/framework/agents/performance.md

@@ -0,0 +1,155 @@
+# Performance
+
+## Purpose
+
+Define performance targets, optimization guidelines, and monitoring strategies.
+
+## Scope
+
+**In**: Performance requirements, optimization techniques, profiling.
+**Out**: Infrastructure scaling (see deployment-protocol.md if applicable).
+
+## Do
+
+- Set measurable performance targets
+- Profile before optimizing
+- Monitor performance metrics
+- Optimize critical paths first
+
+## Do Not
+
+- Optimize prematurely
+- Sacrifice readability for micro-optimizations
+- Skip performance testing
+
+## Performance Targets
+
+Define your performance targets:
+
+| Metric | Target | Critical Threshold |
+|--------|--------|-------------------|
+| API Response Time (p95) | [e.g., < 200ms] | [e.g., < 500ms] |
+| Page Load Time | [e.g., < 2s] | [e.g., < 5s] |
+| Time to Interactive | [e.g., < 3s] | [e.g., < 7s] |
+| Database Query Time | [e.g., < 50ms] | [e.g., < 200ms] |
+| Bundle Size | [e.g., < 200KB] | [e.g., < 500KB] |
+
+## Frontend Performance
+
+### Loading Performance
+
+- Code splitting
+- Lazy loading
+- Asset optimization
+- Caching strategies
+- CDN usage
+
+### Runtime Performance
+
+- Virtual scrolling for long lists
+- Debouncing/throttling
+- Memoization
+- Efficient re-renders
+- Web Workers for heavy computation
+
+### Bundle Optimization
+
+- Tree shaking
+- Minification
+- Compression (gzip/brotli)
+- Remove unused dependencies
+- Analyze bundle composition
+
+## Backend Performance
+
+### Query Optimization
+
+- Use indexes effectively
+- Avoid N+1 queries
+- Implement query caching
+- Use connection pooling
+- Optimize complex joins
+
+### API Optimization
+
+- Response compression
+- Pagination for large datasets
+- Rate limiting
+- Request/response caching
+- Background job processing
+
+### Caching Strategy
+
+- [Cache layers - e.g., Redis, CDN, browser]
+- [Cache invalidation rules]
+- [Cache TTL policies]
+- [Cache warming strategies]
+
+## Database Performance
+
+### Indexing Strategy
+
+- Index frequently queried fields
+- Composite indexes for multi-field queries
+- Monitor index usage
+- Remove unused indexes
+
+### Query Patterns
+
+- Use database connection pooling
+- Implement read replicas if needed
+- Batch operations when possible
+- Avoid SELECT *
+- Use appropriate data types
+
+## Monitoring
+
+### Key Metrics
+
+- Response times (p50, p95, p99)
+- Error rates
+- Throughput (requests per second)
+- Resource utilization (CPU, memory, disk)
+- Database query performance
+
+### Tools
+
+- [APM tool - e.g., New Relic, Datadog]
+- [Logging - e.g., ELK, CloudWatch]
+- [Profiling tools]
+- [Load testing tools]
+
+## Profiling
+
+### When to Profile
+
+- Before major optimizations
+- After performance regressions
+- During load testing
+- For bottleneck identification
+
+### Profiling Tools
+
+- [Browser DevTools for frontend]
+- [Language-specific profilers for backend]
+- [Database query analyzers]
+
+## Load Testing
+
+- Define realistic load scenarios
+- Test at expected peak load
+- Test beyond capacity (stress testing)
+- Monitor resource usage during tests
+- Document findings and thresholds
+
+## Optimization Checklist
+
+- [ ] Performance targets defined
+- [ ] Critical paths identified
+- [ ] Monitoring implemented
+- [ ] Caching strategy in place
+- [ ] Database indexed appropriately
+- [ ] Frontend bundle optimized
+- [ ] API responses optimized
+- [ ] Load testing performed
+- [ ] Profiling results documented

package/framework/agents/project-context.md

@@ -0,0 +1,145 @@
+<!-- contamination-scan: skip
+     This file legitimately uses the literal paths `docs/design-system/`,
+     `docs/references/`, `docs/decisions/`, etc. inside autodetection probe
+     descriptions (§ 6). Those are NOT hardcoded references — they are
+     literal strings describing what to look for on disk. Autofixing them
+     would make the probe nonsensical. -->
+# Project Context Protocol
+
+**Status**: MANDATORY pre-read for any BALDART skill or agent invocation that touches project-specific paths, brand identity, or technology stack choices.
+
+This module defines how skills resolve project-specific facts (paths, identity, stack, feature toggles) instead of hard-coding them. It exists so that the same skill can run unchanged across a fidelity-app repo, an internal admin tool, or a marketing site.
+
+## 1) The three layers
+
+BALDART skills resolve project context through three layers, in this order:
+
+1. **`baldart.config.yml`** (repo root) — variables: paths, identity, stack, feature flags. Authoritative source of structural facts.
+2. **Skill base content** (`.claude/skills/<name>/`) — generic instructions written against config keys, not hard-coded paths.
+3. **`.baldart/overlays/<skill-name>.md`** (consumer-authored, optional) — project-specific extensions: brand voice, custom workflows, project-specific BLOCKING rules.
+
+Skills MUST consult all three layers in this order on every invocation.
+
+## 2) Reading `baldart.config.yml`
+
+Before executing any step that depends on project-specific facts, the skill MUST:
+
+1. Read `baldart.config.yml` from the repo root.
+2. Resolve the keys it declares in its **Project Context** header.
+3. Apply the **Missing-key protocol** below if any required key is empty / absent / unanswered.
+
+The schema is documented in [`framework/docs/PROJECT-CONFIGURATION.md`](../docs/PROJECT-CONFIGURATION.md). Top-level keys:
+
+| Key | Purpose |
+|---|---|
+| `version` | Schema version. Skills MAY refuse to run on a higher major than they understand. |
+| `paths.*` | Canonical document and source paths. Empty string = concept absent in this project. |
+| `identity.*` | Brand name, design philosophy, language, audience segments. |
+| `stack.*` | Charting / animation / testing technology choices (canonical + forbidden). |
+| `features.*` | Explicit booleans gating BLOCKING reads (e.g. `has_design_system`). |
+
+## 3) Missing-key protocol (option A — always ask)
+
+When a key the skill declares as required is missing, empty, or a `features.*` flag is absent:
+
+1. **Do not assume.** Never default to `false`. Never invent a path.
+2. **Ask the user** with a concrete question naming the missing key:
+   > "`baldart.config.yml` does not declare `paths.design_system`. Does this project have a design system, and if so where is its entry point?"
+3. **Persist the answer.** Suggest running `npx baldart configure` so the answer is written to `baldart.config.yml` and not asked again next time. If the user declines, proceed with the value but note it as ASSUMED.
+4. **Do not silently degrade.** If a BLOCKING read is gated by an unanswered `features.*` flag, the skill MUST ask before deciding whether to skip — it MUST NOT default to skipping.
+
+## 4) Skill header convention (3-5 lines)
+
+Every skill that depends on project context MUST include a **Project Context** block immediately after its frontmatter. The block is short and dense — the full protocol (this file) is loaded once, not duplicated per skill.
+
+Template ([`framework/templates/skill-project-context.snippet.md`](../templates/skill-project-context.snippet.md)):
+
+```markdown
+## Project Context
+
+**Reads from `baldart.config.yml`:** `paths.X`, `paths.Y`, `identity.Z`, `stack.W`.
+**Gated by features:** `features.has_FOO` (BLOCKING when true), `features.has_BAR` (skip step N when false).
+**Overlay:** loads `.baldart/overlays/<this-skill>.md` if present (see `framework/agents/project-context.md` § 5).
+**On missing/empty keys:** ask the user; do not assume defaults.
+```
+
+Skills MUST NOT re-explain the protocol. They MUST cite `framework/agents/project-context.md` for the rules.
+
+## 5) Overlay loading rule
+
+Path: `.baldart/overlays/<skill-name>.md` (matches the skill directory name, e.g. `.baldart/overlays/ui-design.md`).
+
+### Frontmatter (mandatory)
+
+```yaml
+---
+base_skill: ui-design
+base_skill_version: 3.0.0   # version of the framework when this overlay was authored
+mode: extend                # extend | override
+---
+```
+
+- `base_skill_version` — captures the framework version the overlay was written against. `baldart status` and `baldart update` use this to warn when the base skill has evolved (silent-conflict prevention).
+- `mode: extend` (default) — overlay rules are ADDED to base skill rules. The skill runs both.
+- `mode: override` — overlay rules REPLACE conflicting base-skill rules. Use sparingly.
+
+### Precedence rules
+
+1. **Default**: overlays *extend* base skills. If overlay and base both apply, both run.
+2. **Explicit override**: inside an overlay (regardless of `mode`), a section marked `## [OVERRIDE] <topic>` replaces the same `<topic>` from the base skill.
+3. **Stack/identity conflicts**: when an overlay's stack/identity rule contradicts `baldart.config.yml`, the overlay wins (the user wrote it deliberately) — but the skill MUST log a one-line "overlay overrides config" notice in its output.
+
+### Version drift handling
+
+If `base_skill_version` in the overlay is older than the installed framework version:
+- The skill loads the overlay normally.
+- The skill emits a single-line WARNING at the start of its output: `overlay <name> targets v<X>, installed v<Y> — review for drift`.
+- `npx baldart status` lists drifted overlays and suggests `npx baldart update --review-overlays`.
+
+This is non-blocking by design — silent overrides are worse than noisy ones.
+
+## 6) Autodetection (used by `baldart configure`)
+
+`npx baldart configure` populates `baldart.config.yml` by probing the filesystem. The complete probe table (source of truth: `src/commands/configure.js` `detect()`):
+
+| Probe | Filesystem check | Config keys set |
+|---|---|---|
+| Design system | `docs/design-system/INDEX.md` exists | `paths.design_system: docs/design-system`, `features.has_design_system: true` |
+| UI guidelines | first match of `docs/references/ui-guidelines.md`, `docs/ui-guidelines.md`, `docs/references/brand-guidelines.md` | `paths.ui_guidelines: <found>` |
+| API index | first match of `docs/references/api/index.md`, `docs/api/index.md` | `paths.api_index: <found>` |
+| API schemas | first match of `docs/references/api/schemas.md`, `docs/api/schemas.md` | `paths.api_schemas: <found>`, `features.has_api_docs: true` |
+| API errors | first match of `docs/references/errors.md`, `docs/errors.md` | `paths.api_errors: <found>` |
+| Components — primitives | first match of `src/components/ui`, `app/components/ui`, `components/ui` | `paths.components_primitives: <found>` |
+| Components — root | first match of `src/components`, `app/components`, `components` | `paths.components_root: <found>` |
+| Global styles | first match of `src/app/globals.css`, `app/globals.css`, `src/styles/globals.css`, `styles/globals.css` | `paths.global_styles: <found>` |
+| Backlog | `backlog/*.yml` count > 0 | `paths.backlog_dir: backlog`, `features.has_backlog: true` |
+| ADR | `docs/decisions/ADR-*.md` count > 0 | `paths.adrs_dir: docs/decisions`, `features.has_adrs: true` |
+| PRD | `docs/prd/` exists | `paths.prd_dir: docs/prd`, `features.has_prd_workflow: true` |
+| References dir | `docs/references/` exists | `paths.references_dir: docs/references` |
+| LLM wiki | `docs/wiki/` exists | `paths.wiki_dir: docs/wiki`, `features.has_wiki_overlay: true` |
+| E2E tests | first match of `tests/e2e`, `e2e`, `tests/playwright`, `tests/cypress` | `paths.e2e_tests_dir: <found>` |
+| Brand name | `package.json#name` | `identity.brand_name: <name>` |
+| Charting canonical | `package.json` lists any of `recharts`, `@nivo/heatmap`, `@nivo/bar`, `@nivo/line` | `stack.charting.canonical: [<found>]` |
+| Charting wrappers | first match of `src/components/charts`, `app/components/charts` | `stack.charting.wrappers_root: <found>` |
+| Animation canonical | `package.json` lists any of `framer-motion`, `lottie-react`, `gsap`, `motion` | `stack.animation.canonical: [<found>]` |
+| E2E framework | `playwright.config.{ts,js}` → `playwright`; `cypress.config.{ts,js}` → `cypress` | `stack.testing.e2e: <name>` |
+
+Autodetection PROPOSES values; the user always confirms. The point is to make first-run feel like one prompt-confirmation cycle, not 20 hand-typed YAML keys.
+
+The `multi_tenant_theming` feature is not auto-detectable (no filesystem signal). `configure` always prompts for it explicitly; non-interactive mode omits the key from the written YAML so the always-ask contract kicks in on first skill invocation.
+
+## 7) Why this design
+
+- **Symlinks survive updates.** The skill base content is symlinked from `.framework/`. Without indirection, every `npx baldart update` would overwrite consumer customizations. With indirection, customizations live in `baldart.config.yml` (copy, never overwritten) and `.baldart/overlays/` (consumer-owned).
+- **Generic + opinionated coexist.** Generic skill content is the framework's IP. The opinionated parts (Neo-Brutalism, merchant/customer split, Recharts-only) live in the consumer's overlay. The same `ui-design` skill can be reused with a different overlay in every project.
+- **Always-ask beats silent-default.** The cost of one extra question per missing key is trivial. The cost of a skill silently using `docs/design-system/INDEX.md` in a project that has no design system is silent failure, hallucinated paths, broken output.
+
+## 8) Author checklist (when adding/modifying a skill)
+
+- [ ] Skill declares its config dependencies in a **Project Context** header (3-5 lines).
+- [ ] No hard-coded paths in skill body — every path references a `baldart.config.yml` key.
+- [ ] No hard-coded identity claims — brand voice / design philosophy / language come from `identity.*`.
+- [ ] No hard-coded stack imposition — canonical/forbidden libraries come from `stack.*`.
+- [ ] BLOCKING reads are gated by `features.*` flags, not assumed-always-present.
+- [ ] Skill explicitly invokes overlay loading: "load `.baldart/overlays/<name>.md` if present".
+- [ ] If the skill ships an opinionated default that was previously hard-coded, the opinion is moved to `framework/templates/overlays/<name>.<flavour>-example.md` and the skill body stays neutral.

package/framework/agents/runbook.md

@@ -0,0 +1,208 @@
+# Runbook
+
+## Purpose
+
+Document operational procedures, environment setup, and common tasks.
+
+## Scope
+
+**In**: Environment setup, deployment procedures, common operations.
+**Out**: Development workflow (see agents/workflows.md).
+
+## Do
+
+- Document all manual procedures
+- Keep runbook updated
+- Test procedures periodically
+
+## Do Not
+
+- Skip documenting new procedures
+- Assume knowledge is common
+
+## Environment Setup
+
+### Prerequisites
+
+- [Tool 1 - e.g., Node.js 18+]
+- [Tool 2 - e.g., Docker]
+- [Tool 3 - e.g., Database client]
+- [Access requirements]
+
+### Installation Steps
+
+1. Clone repository: `git clone [repo-url]`
+2. Install dependencies: `[install-command]`
+3. Copy environment file: `cp .env.example .env`
+4. Configure environment variables
+5. Run database migrations (if applicable)
+6. Start development server: `[dev-command]`
+
+### Environment Variables
+
+| Variable | Required | Description | Example |
+|----------|----------|-------------|---------|
+| `VAR_1` | Yes | [Description] | `value` |
+| `VAR_2` | No | [Description] | `value` |
+
+## Common Operations
+
+### Starting Services
+
+```bash
+# Development
+[command to start dev server]
+
+# Production
+[command to start prod server]
+```
+
+### Running Tests
+
+```bash
+# All tests
+[test command]
+
+# Specific test
+[test command for specific file/suite]
+
+# With coverage
+[coverage command]
+```
+
+### Database Operations
+
+```bash
+# Run migrations
+[migration command]
+
+# Rollback migration
+[rollback command]
+
+# Seed database
+[seed command]
+
+# Backup database
+[backup command]
+
+# Restore database
+[restore command]
+```
+
+### Build and Deploy
+
+```bash
+# Build for production
+[build command]
+
+# Run linter
+[lint command]
+
+# Run type check
+[type-check command]
+
+# Deploy
+[deploy command]
+```
+
+## Troubleshooting
+
+### Issue: [Common Issue 1]
+
+**Symptoms**: [Describe symptoms]
+
+**Cause**: [Root cause]
+
+**Solution**:
+
+```bash
+[Commands to fix]
+```
+
+### Issue: [Common Issue 2]
+
+**Symptoms**: [Describe symptoms]
+
+**Cause**: [Root cause]
+
+**Solution**:
+
+```bash
+[Commands to fix]
+```
+
+## Maintenance Tasks
+
+### Daily
+
+- [Task 1 - e.g., Check error logs]
+- [Task 2 - e.g., Monitor resource usage]
+
+### Weekly
+
+- [Task 1 - e.g., Review performance metrics]
+- [Task 2 - e.g., Update dependencies]
+
+### Monthly
+
+- [Task 1 - e.g., Database optimization]
+- [Task 2 - e.g., Security audit]
+
+## Backup Procedures
+
+### Database Backup
+
+```bash
+[Backup command with examples]
+```
+
+### File Backup
+
+```bash
+[Backup command with examples]
+```
+
+### Restore Procedures
+
+```bash
+[Restore command with examples]
+```
+
+## Monitoring
+
+- [Health check endpoint]
+- [Metrics endpoint]
+- [Logs location]
+- [Dashboard URL]
+
+## Emergency Contacts
+
+- **On-call**: [Contact info]
+- **Database Admin**: [Contact info]
+- **DevOps**: [Contact info]
+- **Security**: [Contact info]
+
+## Useful Commands
+
+```bash
+# Check service status
+[command]
+
+# View logs
+[command]
+
+# Clear cache
+[command]
+
+# Restart service
+[command]
+```
+
+## Environment Differences
+
+| Aspect | Development | Staging | Production |
+|--------|-------------|---------|------------|
+| URL | [dev-url] | [staging-url] | [prod-url] |
+| Database | [db info] | [db info] | [db info] |
+| Logging | Debug | Info | Warn/Error |
+| Cache | Disabled | Enabled | Enabled |

package/framework/agents/security.md

@@ -0,0 +1,168 @@
+# Security
+
+## Purpose
+
+Document security requirements, threats, and mitigation strategies.
+
+## Scope
+
+**In**: Authentication, authorization, data protection, common vulnerabilities.
+**Out**: Compliance requirements (create separate docs/compliance/ if needed).
+
+## Do
+
+- Validate all user inputs
+- Use parameterized queries
+- Implement rate limiting
+- Log security events
+- Keep dependencies updated
+
+## Do Not
+
+- Store secrets in code
+- Trust client-side validation alone
+- Skip authentication checks
+- Log sensitive data
+
+## Authentication
+
+- [Authentication method]
+- [Session management]
+- [Token handling]
+- [Password requirements]
+- [Multi-factor authentication if applicable]
+
+## Authorization
+
+- [Permission model]
+- [Role-based access control]
+- [Resource-level permissions]
+- [API authorization checks]
+
+## Input Validation
+
+- Validate all user inputs server-side
+- Sanitize data before database operations
+- Use allowlists over denylists
+- Validate file uploads (type, size, content)
+- Check for injection attacks (SQL, NoSQL, command, XSS)
+
+## Data Protection
+
+- [Encryption at rest]
+- [Encryption in transit]
+- [PII handling]
+- [Sensitive data masking in logs]
+- [Secrets management]
+
+## Common Vulnerabilities (OWASP Top 10)
+
+### Injection Attacks
+
+- Use parameterized queries
+- Validate and sanitize inputs
+- Implement least privilege database access
+
+### Broken Authentication
+
+- Implement secure session management
+- Use strong password policies
+- Implement account lockout
+- Protect against brute force
+
+### Sensitive Data Exposure
+
+- Encrypt sensitive data
+- Use HTTPS everywhere
+- Don't log sensitive information
+- Implement secure key management
+
+### XML External Entities (XXE)
+
+- Disable XML external entity processing
+- Use safe XML parsers
+- Validate XML inputs
+
+### Broken Access Control
+
+- Implement proper authorization
+- Validate permissions on every request
+- Use principle of least privilege
+
+### Security Misconfiguration
+
+- Harden default configurations
+- Keep software updated
+- Remove unnecessary features
+- Implement security headers
+
+### Cross-Site Scripting (XSS)
+
+- Escape output
+- Use Content Security Policy
+- Validate and sanitize inputs
+- Use framework protections
+
+### Insecure Deserialization
+
+- Validate serialized data
+- Use safe deserialization libraries
+- Implement integrity checks
+
+### Using Components with Known Vulnerabilities
+
+- Keep dependencies updated
+- Monitor security advisories
+- Use dependency scanning tools
+
+### Insufficient Logging & Monitoring
+
+- Log security events
+- Monitor for suspicious activity
+- Implement alerting
+- Protect log integrity
+
+## Rate Limiting
+
+- [API rate limits]
+- [Authentication attempt limits]
+- [Resource access limits]
+
+## Security Headers
+
+Implement these HTTP security headers:
+
+- `Content-Security-Policy`
+- `X-Content-Type-Options: nosniff`
+- `X-Frame-Options: DENY`
+- `X-XSS-Protection: 1; mode=block`
+- `Strict-Transport-Security`
+
+## Secrets Management
+
+- Never commit secrets to version control
+- Use environment variables
+- Use secrets management service if available
+- Rotate secrets regularly
+- Implement least privilege access
+
+## Incident Response
+
+1. Detect and identify incident
+2. Contain the threat
+3. Investigate root cause
+4. Remediate vulnerability
+5. Document and learn
+
+## Security Checklist
+
+- [ ] All inputs validated
+- [ ] Parameterized queries used
+- [ ] Authentication implemented
+- [ ] Authorization checked
+- [ ] Sensitive data encrypted
+- [ ] Security headers set
+- [ ] Rate limiting implemented
+- [ ] Dependencies up to date
+- [ ] Logging implemented
+- [ ] Secrets properly managed