baldart 3.6.2

package/framework/.claude/skills/prd/references/validation-phase.md

@@ -0,0 +1,72 @@
+# Validation & Commit Phase (Steps 6-7)
+
+## Step 6 — Quality Audit
+
+**Precondition:** Backlog cards approved.
+
+Mark task 5 as `in_progress`.
+
+1. **Field Name Audit (runs BEFORE audit agents)** — for each generated card:
+
+   a. Verify every `data_fields` entry has `ts_verified: true` OR `status: new` with `schema_ref`.
+   b. For cards with `estimated_complexity: HIGH` or `MEDIUM`:
+      - For each `status: existing` field: run `grep -n "fieldName" src/types/<domain>.ts`
+        and verify ≥1 match. 0 matches = **BLOCKER** — correct or mark as `🆕 new`.
+      - For each `status: new` field: PRD `## Schema Verification` must have complete
+        definition (type, nullable, default, indexing notes).
+   c. For cards with `estimated_complexity: LOW`:
+      - Verify only that `data_fields` has `ts_verified: true` or `status: new`. No grep needed.
+   d. If card has `firestore_indexes` but NO `data_fields`: log warning —
+      "card touches Firestore (firestore_indexes present) but missing data_fields block."
+
+   **Gate**: no field with `status: existing | modified` and `ts_verified: false` can proceed.
+
+2. Read the audit phase reference: [audit-phase.md](audit-phase.md)
+   Then execute the audit protocol described within, using the card IDs from Step 5.
+   The protocol auto-detects which agents to include (security and performance
+   are signal-triggered, no manual profile selection needed).
+3. Wait for audit report and card edits.
+
+**Gate:** all HIGH/MEDIUM findings resolved, no open `[MANUAL]` items.
+
+## Step 7 — Resolution and Commit
+
+**Precondition:** Step 6 complete.
+
+### Resolve remaining items
+
+1. If `[MANUAL]` items remain: resolve each one.
+2. If resolution required card re-edits: re-run the audit protocol (audit-phase.md) on affected cards.
+
+### Update knowledge base
+
+3. Add/update entry in `${paths.references_dir}/ssot-registry.md` pointing to the new PRD
+   as canonical source for this macro feature.
+4. Update `${paths.references_dir}/project-status.md` Active Code Context with PRD completion.
+
+### Commit
+
+5. Stage ONLY PRD session artifacts (explicit file names, never `git add .`):
+   - `${paths.prd_dir}/sessions/YYYY-MM-DD-<slug>-state.md`
+   - `docs/prd/<slug>/PRD.md`
+   - `docs/prd/<slug>/design.html` (if exists)
+   - `backlog/FEAT-XXXX-*.yml` (all cards created in Step 5)
+   - `${paths.references_dir}/ssot-registry.md` (if updated)
+   - `${paths.references_dir}/project-status.md` (if updated)
+6. Update state file: status -> `completed`, add commit hash to `## Validation`.
+7. Commit with format: `[PRD] <slug>: <brief description>`
+
+**Gate:** commit successful, state file shows `completed`.
+
+Mark task 5 as `completed`.
+
+### Final output
+
+Print final summary:
+
+- PRD path
+- Design path (if applicable)
+- Card IDs created
+- Commit hash
+
+Display completed Progress Bar.

package/framework/.claude/skills/prd-add/SKILL.md

@@ -0,0 +1,222 @@
+---
+name: prd-add
+description: "Change Request skill for active PRD sessions. Use when the user says /prd-add, 'aggiungi requisito', 'serve anche', 'manca un endpoint', or describes a new requirement that impacts an existing PRD. Also auto-triggered by /prd during discovery when the user's answer reveals a new sub-feature not covered by the original scope. Runs ICIAS impact analysis (semantic scan + structural propagation + scoring) to determine which PRD phases need SKIP/PATCH/REDO, then executes only affected phases."
+---
+
+# /prd-add — Change Request per PRD attivi
+
+Add a new requirement to an existing PRD session. Uses the ICIAS protocol
+(Impact-Confidence-Artifact Stakes) to determine which phases and artifacts
+need revision, then executes only the affected ones.
+
+## Project Context
+
+**Reads from `baldart.config.yml`:** `paths.prd_dir`, `paths.design_system`.
+**Gated by features:** `features.has_prd_workflow` (REFUSES to run when `false`), `features.has_design_system` (Rule 9 BLOCKING when `true`).
+**Overlay:** loads `.baldart/overlays/prd-add.md` if present — and inherits the prd overlay's terminology + design-system reads (since prd-add operates on /prd's artifacts).
+**On missing/empty keys:** ask the user; do not assume defaults. See `framework/agents/project-context.md` § 3.
+
+---
+
+## TRIGGER MODES
+
+### 1. Manual invocation
+User types `/prd-add <description>` or `/prd-add` (then describes the change).
+
+### 2. Auto-trigger from /prd discovery
+During `/prd` Step 2 (Discovery Question Loop), if the user's answer reveals
+a new sub-feature or structural requirement NOT covered by the original feature
+description, the `/prd` skill invokes `/prd-add` automatically.
+
+Detection signal: the user's answer introduces NEW entities (endpoints, collections,
+pages, roles, flows) that were not part of the original feature scope.
+
+---
+
+## EXECUTION MODEL
+
+Sequential, single-turn analysis + selective multi-turn re-execution.
+
+| Step | Phase | Description |
+|------|-------|-------------|
+| 0 | Session Locate | Find active PRD state file |
+| 1 | Intake | Capture and classify change request |
+| 2 | Impact Analysis | ICIAS protocol (3 phases) |
+| 3 | Verdict | Present impact matrix, ask confirmation |
+| 4 | Selective Execution | Re-run only PATCH/REDO phases |
+| 5 | Delta Commit | Commit changes with `[PRD-ADD]` prefix |
+
+---
+
+## HARD RULES
+
+1. NEVER start from scratch. Always build on the existing PRD session.
+2. Read the state file and PRD before any analysis.
+3. Follow ICIAS protocol exactly — read [impact-analysis.md](references/impact-analysis.md).
+4. Present verdict BEFORE executing changes. Wait for user confirmation.
+5. When re-running phases, follow the SAME reference files as `/prd` (discovery-phase.md, etc.).
+6. Update the state file with a `## Change Requests` section tracking all CR history.
+7. Commit with format: `[PRD-ADD] <slug>: <brief CR description>`
+8. **Every message MUST end with the CR Progress Bar.**
+9. **Design System SSOT re-validation (UI-touching CRs).** When `features.has_design_system: true` AND the change request introduces, modifies, or removes any UI surface (new page, component, layout, flow, or visual state), you MUST re-validate against `${paths.design_system}/INDEX.md` (component index + authority matrix + Quick rules MUST). The ICIAS impact analysis MUST include design-system scope as a dimension: check whether affected UI maps to existing components in `${paths.design_system}/components/<Name>.md` (PATCH = reuse existing) or introduces a new pattern (REDO = propose new component doc and route through DS ownership). When `features.multi_tenant_theming: true`, themed surfaces MUST be re-checked against the project's theming pattern doc; motion changes MUST reference the project's motion pattern doc (both listed in `.baldart/overlays/prd.md`). Cite consulted DS docs in the updated PRD's Canonical Sources section.
+
+---
+
+## Step 0 — Session Locate
+
+1. List `${paths.prd_dir}/sessions/` for state files.
+2. If exactly ONE active session (status != `completed`): use it.
+3. If multiple active sessions: ask user which one.
+4. If zero sessions: inform user, suggest `/prd` instead.
+5. Read the state file AND the PRD document (if exists).
+
+---
+
+## Step 1 — Intake
+
+1. If change description provided as argument: use it.
+2. If not: ask the user to describe the change.
+
+**Classify the change type** (from CIA literature):
+- **Addition**: new entity (endpoint, collection, page, role, flow)
+- **Modification**: change to existing entity (new field, changed behavior)
+- **Deletion**: removal of planned entity
+
+Record in state file under `## Change Requests`:
+
+```markdown
+### CR-N: <title>
+- Type: Addition | Modification | Deletion
+- Description: <user's description verbatim>
+- Date: YYYY-MM-DD
+- Status: analyzing
+```
+
+**Immediately proceed to Step 2.**
+
+---
+
+## Step 2 — Impact Analysis (ICIAS Protocol)
+
+**Read [references/impact-analysis.md](references/impact-analysis.md) for the full protocol.**
+
+Quick summary — 3 phases executed in sequence:
+
+### Phase 1: Semantic Scan
+Evaluate each of the 10 dimensions against the change request.
+For each dimension, assign an initial impact assessment (0=none, 1-3=depth).
+
+### Phase 2: Structural Propagation
+Apply the coupling matrix to find transitive impacts.
+Max 2 hops, confidence degrades per hop.
+
+### Phase 3: ICIAS Scoring
+For each impacted dimension: `Score = I x C x A`
+- I = Impact depth (1=cosmetic, 2=logic, 3=structural)
+- C = Confidence (1=inferred, 2=probable, 3=certain)
+- A = Artifact Stakes (pre-assigned per dimension)
+
+Classify: **SKIP** (score <= 3), **PATCH** (4-9), **REDO** (>= 10)
+
+---
+
+## Step 3 — Verdict
+
+Present the impact matrix to the user:
+
+```
+### Impact Analysis — CR-N: <title>
+
+| # | Dimension | Direct | Cascade | I | C | A | Score | Verdict |
+|---|-----------|--------|---------|---|---|---|-------|---------|
+| D1 | Target users | - | - | 0 | - | 1 | 0 | SKIP |
+| D2 | User journey | yes | - | 2 | 3 | 2 | 12 | REDO |
+| D3 | Data model | - | D4->D3 | 1 | 2 | 3 | 6 | PATCH |
+| ... | ... | ... | ... | ... | ... | ... | ... | ... |
+
+**Fasi da rieseguire:**
+- Discovery: PATCH (D2, D4 da aggiornare)
+- UI Design: REDO (nuovo flow)
+- PRD: PATCH (sezioni 4, 6, 9)
+- Backlog Cards: PATCH (nuove cards + update esistenti)
+
+Vuoi procedere con questa analisi?
+```
+
+**STOP.** Wait for user confirmation.
+
+If user disagrees with any verdict, adjust manually and re-present.
+
+---
+
+## Step 4 — Selective Execution
+
+Execute ONLY phases with PATCH or REDO verdict, in original phase order.
+
+### For Discovery dimensions (PATCH/REDO)
+
+- **PATCH**: Run `codebase-architect` on affected dimensions only.
+  Update state file checklist entries. No user questions unless ambiguous.
+- **REDO**: Full re-discovery for that dimension (same as /prd Step 2 loop
+  but scoped to affected dimensions only). May require user questions.
+
+### For UI Design (PATCH/REDO)
+
+- **PATCH**: Describe changes needed to existing design.html. Ask user
+  if they want a full design refresh or text-only update to PRD.
+- **REDO**: Re-run full UI Design phase (Steps 3a-3d from /prd).
+
+### For PRD (PATCH/REDO)
+
+- **PATCH**: Edit specific PRD sections. Add/modify user stories, API
+  contracts, data model, acceptance criteria as needed. Preserve
+  unchanged sections verbatim.
+- **REDO**: Rewrite major PRD sections (rare — only when change
+  fundamentally alters the feature).
+
+### For Backlog Cards (PATCH/REDO)
+
+- **PATCH**: Create new cards for new work. Update `depends_on` in
+  existing cards if dependencies changed. Do NOT rewrite existing cards
+  unless acceptance criteria changed.
+- **REDO**: Regenerate affected cards via `prd-card-writer` agent.
+  Preserve cards that are unaffected.
+
+### For ISA (always re-scan if any PATCH/REDO exists)
+
+Run a delta ISA scan focused on the new requirement. Merge new
+touchpoints into existing ISA table. Assign new ISA-N IDs.
+
+---
+
+## Step 5 — Delta Commit
+
+1. Update state file:
+   - CR status: `applied`
+   - Update comprehension checklist with changes
+   - Update `## Change Requests` with summary of what was done
+2. Re-run API Performance Gate (Step 4.5) if API/data model changed.
+3. Stage ONLY modified files (explicit names).
+4. Commit: `[PRD-ADD] <slug>: <CR description>`
+
+---
+
+## CR PROGRESS BAR — MANDATORY ON EVERY MESSAGE
+
+```
+---
+🔄 **Change Request: <slug> — CR-N**
+
+| # | Fase | Verdict | Stato |
+|---|------|---------|-------|
+| 1 | Intake | - | ⬜/✅ |
+| 2 | Impact Analysis | - | ⬜/🔄/✅ |
+| 3 | Verdict & conferma | - | ⬜/🔄/✅ |
+| 4a | Discovery (delta) | SKIP/PATCH/REDO | ⬜/🔄/✅/⏭️ |
+| 4b | UI Design (delta) | SKIP/PATCH/REDO | ⬜/🔄/✅/⏭️ |
+| 4c | PRD (delta) | SKIP/PATCH/REDO | ⬜/🔄/✅/⏭️ |
+| 4d | Backlog Cards (delta) | SKIP/PATCH/REDO | ⬜/🔄/✅/⏭️ |
+| 5 | Delta Commit | - | ⬜/✅ |
+
+Prossimo passo: <what happens next>
+```

package/framework/.claude/skills/prd-add/references/impact-analysis.md

@@ -0,0 +1,233 @@
+# ICIAS Impact Analysis Protocol
+
+Full protocol for Change Impact Analysis on PRD sessions.
+Based on ProReFiCIA (Etezadi et al. 2025), CodePlan (Bairi et al. 2023),
+and FMEA-adapted scoring.
+
+---
+
+## Phase 1 — Semantic Scan
+
+Evaluate each dimension against the change request description.
+
+### Procedure
+
+For each of the 10 dimensions, determine:
+- **Is there a direct impact?** (yes/no)
+- **Impact depth** (I):
+  - 0 = no impact
+  - 1 = cosmetic (labels, copy, minor display)
+  - 2 = logic (new conditions, validation, flow branches)
+  - 3 = structural (new entities, schemas, endpoints, pages)
+
+### Refinement pass (mandatory)
+
+After initial scan, re-read the change request and check dimensions 4-7
+again (the "middle" of the list — LLMs tend to under-evaluate items in
+the middle of lists, per "lost-in-the-middle" research). Adjust any
+dimension that was initially scored 0 but deserves >= 1 on second look.
+
+---
+
+## Phase 2 — Structural Propagation (Coupling Matrix)
+
+Apply the coupling matrix to find transitive (cascade) impacts.
+
+### Rules
+
+1. Start from all dimensions with direct impact (I > 0 from Phase 1).
+2. For each directly impacted dimension, check outgoing edges in the matrix.
+3. If edge strength >= 2 AND target dimension has I = 0: mark as cascade impact.
+   - Cascade I = max(1, source_I - 1) (degrades by hop)
+   - Cascade C = source_C - 1 (min 1) (confidence degrades)
+4. Max hop depth = 2. Do NOT propagate beyond 2 hops.
+5. If a dimension is reached by both direct and cascade: use direct (higher confidence).
+
+### Coupling Matrix (10x10)
+
+Rows = source dimension, Columns = target dimension.
+Values: 0 = independent, 1 = weak, 2 = moderate, 3 = strong (almost always co-impacted).
+
+```
+        D1   D2   D3   D4   D5   D6   D7   D8   D9   D10
+D1  U   -    1    0    0    1    1    0    0    0    0
+D2  J   0    -    1    1    3    0    2    0    1    1
+D3  DM  0    0    -    3    0    0    1    3    1    2
+D4  API 0    1    3    -    1    1    1    0    3    3
+D5  UI  0    2    0    0    -    0    1    0    1    2
+D6  P   0    0    0    1    1    -    1    0    1    3
+D7  EC  0    0    0    0    0    0    -    0    0    1
+D8  RM  0    0    1    0    0    0    1    -    0    1
+D9  IS  0    0    0    1    0    0    0    0    -    1
+D10 TS  0    0    0    0    0    0    0    0    0    -
+```
+
+**Key:**
+- D1=Users, D2=Journey, D3=Data Model, D4=API, D5=UI
+- D6=Permissions, D7=Edge Cases, D8=Rollout/Migration
+- D9=Integration Surface, D10=Test Strategy
+
+### High-coupling pairs (strength=3, rationale)
+
+| Source → Target | Why |
+|-----------------|-----|
+| D2 Journey → D5 UI | New flow = new interface almost always |
+| D3 Data → D4 API | Schema change = API contract change |
+| D3 Data → D8 Rollout | Schema change = migration needed |
+| D4 API → D3 Data | New endpoint often needs new/modified schema |
+| D4 API → D9 Integration | New endpoint = new touchpoints in existing code |
+| D4 API → D10 Tests | New endpoint = new test scenarios |
+| D6 Perms → D10 Tests | Permission change = critical test update |
+
+---
+
+## Phase 3 — ICIAS Scoring
+
+For each dimension with I > 0 (direct or cascade):
+
+### Score = I x C x A
+
+**I = Impact Depth** (from Phase 1/2):
+| Value | Meaning | Examples |
+|-------|---------|----------|
+| 1 | Cosmetic | Label, copy, minor display change |
+| 2 | Logic | New condition, validation, flow branch, field |
+| 3 | Structural | New entity, endpoint, page, collection, role |
+
+**C = Confidence** (how certain the impact is):
+| Value | Meaning | When to use |
+|-------|---------|-------------|
+| 1 | Inferred | Cascade-only, no direct evidence |
+| 2 | Probable | Logical deduction, codebase pattern suggests it |
+| 3 | Certain | Explicitly stated in CR, or direct code dependency |
+
+**A = Artifact Stakes** (pre-assigned, fixed per dimension):
+| A=3 (High stakes) | A=2 (Medium stakes) | A=1 (Low stakes) |
+|-------------------|---------------------|-------------------|
+| D3 Data Model | D2 User Journey | D1 Target Users |
+| D4 API | D5 UI | D7 Edge Cases |
+| D9 Integration Surface | D6 Permissions | D8 Rollout/Migration |
+| | D10 Test Strategy | |
+
+### Verdict thresholds
+
+| Score Range | Verdict | Meaning |
+|-------------|---------|---------|
+| 0 | SKIP | No impact detected |
+| 1–3 | SKIP | Negligible impact, no revision needed |
+| 4–9 | PATCH | Moderate impact, surgical update to affected sections |
+| 10–27 | REDO | Major impact, phase must be substantially re-executed |
+
+### Bias rule
+
+**False negatives are worse than false positives.** When uncertain:
+- Round C up, not down
+- Prefer PATCH over SKIP when on the boundary (score = 3)
+- Prefer REDO over PATCH only when I = 3 (structural)
+
+---
+
+## Phase Mapping
+
+After scoring all dimensions, map to PRD phases:
+
+### Discovery phase impact
+- ANY dimension with PATCH/REDO → Discovery needs delta update
+- PATCH: update state file checklist, run codebase-architect on affected dims
+- REDO: re-run discovery question loop for affected dims
+
+### UI Design phase impact
+- D2 Journey REDO OR D5 UI REDO → UI Design REDO
+- D5 UI PATCH → UI Design PATCH (update existing design)
+- Otherwise → UI Design SKIP
+
+### PRD document impact
+- ANY dimension with PATCH/REDO → PRD needs update
+- Map dimensions to PRD sections:
+
+| Dimension | PRD Sections Affected |
+|-----------|----------------------|
+| D1 Users | 3 (Personas) |
+| D2 Journey | 4 (User Stories), 7 (UI Specs) |
+| D3 Data | 5 (Data Model), 12 (Dependencies) |
+| D4 API | 6 (API Contract), 14 (Pipeline) |
+| D5 UI | 7 (UI Specs), 8 (i18n) |
+| D6 Perms | 9 (Acceptance Criteria) |
+| D7 Edge Cases | 10 (Edge Cases) |
+| D8 Rollout | 12 (Dependencies) |
+| D9 Integration | 15 (ISA) |
+| D10 Tests | 13 (Test Plan) |
+
+### Backlog Cards impact
+- New structural entities (I=3) → new cards needed
+- Changed acceptance criteria → update existing cards
+- Changed dependencies → update `depends_on` fields
+
+---
+
+## Worked Example
+
+**CR: "Add POST /api/v1/merchant/reservations/bulk-confirm for batch confirmation"**
+
+Change type: Addition (new endpoint)
+
+### Phase 1 — Semantic Scan
+
+| Dim | Direct? | I | Rationale |
+|-----|---------|---|-----------|
+| D1 Users | no | 0 | Same users (merchant staff) |
+| D2 Journey | yes | 2 | New batch flow alongside single confirm |
+| D3 Data | no | 0 | Same reservation schema |
+| D4 API | yes | 3 | New endpoint, new payload, new validation |
+| D5 UI | yes | 2 | Need selection mode + bulk button |
+| D6 Perms | no | 0 | Same permission (manage_reservations) |
+| D7 Edge | yes | 2 | Partial failure in batch, max batch size |
+| D8 Rollout | no | 0 | No migration needed |
+| D9 Integration | no | 0 | (check in Phase 2) |
+| D10 Tests | no | 0 | (check in Phase 2) |
+
+### Phase 2 — Structural Propagation
+
+From D4 (API, I=3):
+- D4→D3 (strength=3): cascade. D3 I=max(1, 3-1)=2, C=2 → but wait,
+  CR says "same schema" → override to I=0. No cascade (semantic override).
+- D4→D9 (strength=3): cascade. D9 I=2, C=2
+- D4→D10 (strength=3): cascade. D10 I=2, C=2
+
+### Phase 3 — ICIAS Score
+
+| Dim | I | C | A | Score | Verdict |
+|-----|---|---|---|-------|---------|
+| D1 | 0 | - | 1 | 0 | SKIP |
+| D2 | 2 | 3 | 2 | 12 | REDO |
+| D3 | 0 | - | 3 | 0 | SKIP |
+| D4 | 3 | 3 | 3 | 27 | REDO |
+| D5 | 2 | 3 | 2 | 12 | REDO |
+| D6 | 0 | - | 2 | 0 | SKIP |
+| D7 | 2 | 3 | 1 | 6 | PATCH |
+| D8 | 0 | - | 1 | 0 | SKIP |
+| D9 | 2 | 2 | 3 | 12 | REDO |
+| D10 | 2 | 2 | 2 | 8 | PATCH |
+
+### Phase mapping result
+
+| Phase | Verdict | Scope |
+|-------|---------|-------|
+| Discovery | PATCH | Update D2, D4, D5, D7, D9, D10 in checklist |
+| UI Design | REDO | New batch selection flow |
+| PRD | REDO | Sections 4, 6, 7, 10, 13, 15 |
+| Backlog Cards | PATCH | New cards for bulk endpoint + UI; update deps |
+
+---
+
+## Calibration Notes
+
+These thresholds are FMEA-adapted heuristics, not empirically validated
+for PRD CIA. After 10-15 real change requests, review:
+
+1. Were any SKIPs that should have been PATCHes? → Lower threshold.
+2. Were any REDOs that could have been PATCHes? → Raise threshold.
+3. Did the coupling matrix miss any real cascades? → Add/strengthen edges.
+4. Did the coupling matrix produce false cascades? → Weaken/remove edges.
+
+Track calibration data in state file `## Change Requests` section.

package/framework/.claude/skills/remotion-best-practices/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: remotion-best-practices
+description: Best practices for Remotion - Video creation in React
+metadata:
+  tags: remotion, video, react, animation, composition
+---
+
+## When to use
+
+Use this skills whenever you are dealing with Remotion code to obtain the domain-specific knowledge.
+
+## Captions
+
+When dealing with captions or subtitles, load the [./rules/subtitles.md](./rules/subtitles.md) file for more information.
+
+## How to use
+
+Read individual rule files for detailed explanations and code examples:
+
+- [rules/3d.md](rules/3d.md) - 3D content in Remotion using Three.js and React Three Fiber
+- [rules/animations.md](rules/animations.md) - Fundamental animation skills for Remotion
+- [rules/assets.md](rules/assets.md) - Importing images, videos, audio, and fonts into Remotion
+- [rules/audio.md](rules/audio.md) - Using audio and sound in Remotion - importing, trimming, volume, speed, pitch
+- [rules/calculate-metadata.md](rules/calculate-metadata.md) - Dynamically set composition duration, dimensions, and props
+- [rules/can-decode.md](rules/can-decode.md) - Check if a video can be decoded by the browser using Mediabunny
+- [rules/charts.md](rules/charts.md) - Chart and data visualization patterns for Remotion
+- [rules/compositions.md](rules/compositions.md) - Defining compositions, stills, folders, default props and dynamic metadata
+- [rules/extract-frames.md](rules/extract-frames.md) - Extract frames from videos at specific timestamps using Mediabunny
+- [rules/fonts.md](rules/fonts.md) - Loading Google Fonts and local fonts in Remotion
+- [rules/get-audio-duration.md](rules/get-audio-duration.md) - Getting the duration of an audio file in seconds with Mediabunny
+- [rules/get-video-dimensions.md](rules/get-video-dimensions.md) - Getting the width and height of a video file with Mediabunny
+- [rules/get-video-duration.md](rules/get-video-duration.md) - Getting the duration of a video file in seconds with Mediabunny
+- [rules/gifs.md](rules/gifs.md) - Displaying GIFs synchronized with Remotion's timeline
+- [rules/images.md](rules/images.md) - Embedding images in Remotion using the Img component
+- [rules/light-leaks.md](rules/light-leaks.md) - Light leak overlay effects using @remotion/light-leaks
+- [rules/lottie.md](rules/lottie.md) - Embedding Lottie animations in Remotion
+- [rules/measuring-dom-nodes.md](rules/measuring-dom-nodes.md) - Measuring DOM element dimensions in Remotion
+- [rules/measuring-text.md](rules/measuring-text.md) - Measuring text dimensions, fitting text to containers, and checking overflow
+- [rules/sequencing.md](rules/sequencing.md) - Sequencing patterns for Remotion - delay, trim, limit duration of items
+- [rules/tailwind.md](rules/tailwind.md) - Using TailwindCSS in Remotion
+- [rules/text-animations.md](rules/text-animations.md) - Typography and text animation patterns for Remotion
+- [rules/timing.md](rules/timing.md) - Interpolation curves in Remotion - linear, easing, spring animations
+- [rules/transitions.md](rules/transitions.md) - Scene transition patterns for Remotion
+- [rules/transparent-videos.md](rules/transparent-videos.md) - Rendering out a video with transparency
+- [rules/trimming.md](rules/trimming.md) - Trimming patterns for Remotion - cut the beginning or end of animations
+- [rules/videos.md](rules/videos.md) - Embedding videos in Remotion - trimming, volume, speed, looping, pitch
+- [rules/parameters.md](rules/parameters.md) - Make a video parametrizable by adding a Zod schema
+- [rules/maps.md](rules/maps.md) - Add a map using Mapbox and animate it

package/framework/.claude/skills/remotion-best-practices/rules/3d.md

@@ -0,0 +1,86 @@
+---
+name: 3d
+description: 3D content in Remotion using Three.js and React Three Fiber.
+metadata:
+  tags: 3d, three, threejs
+---
+
+# Using Three.js and React Three Fiber in Remotion
+
+Follow React Three Fiber and Three.js best practices.  
+Only the following Remotion-specific rules need to be followed:
+
+## Prerequisites
+
+First, the `@remotion/three` package needs to be installed.  
+If it is not, use the following command:
+
+```bash
+npx remotion add @remotion/three # If project uses npm
+bunx remotion add @remotion/three # If project uses bun
+yarn remotion add @remotion/three # If project uses yarn
+pnpm exec remotion add @remotion/three # If project uses pnpm
+```
+
+## Using ThreeCanvas
+
+You MUST wrap 3D content in `<ThreeCanvas>` and include proper lighting.  
+`<ThreeCanvas>` MUST have a `width` and `height` prop.
+
+```tsx
+import { ThreeCanvas } from "@remotion/three";
+import { useVideoConfig } from "remotion";
+
+const { width, height } = useVideoConfig();
+
+<ThreeCanvas width={width} height={height}>
+  <ambientLight intensity={0.4} />
+  <directionalLight position={[5, 5, 5]} intensity={0.8} />
+  <mesh>
+    <sphereGeometry args={[1, 32, 32]} />
+    <meshStandardMaterial color="red" />
+  </mesh>
+</ThreeCanvas>
+```
+
+## No animations not driven by `useCurrentFrame()`
+
+Shaders, models etc MUST NOT animate by themselves.  
+No animations are allowed unless they are driven by `useCurrentFrame()`.  
+Otherwise, it will cause flickering during rendering.  
+
+Using `useFrame()` from `@react-three/fiber` is forbidden.
+
+## Animate using `useCurrentFrame()`
+
+Use `useCurrentFrame()` to perform animations.
+
+```tsx
+const frame = useCurrentFrame();
+const rotationY = frame * 0.02;
+
+<mesh rotation={[0, rotationY, 0]}>
+  <boxGeometry args={[2, 2, 2]} />
+  <meshStandardMaterial color="#4a9eff" />
+</mesh>
+```
+
+## Using `<Sequence>` inside `<ThreeCanvas>`
+
+The `layout` prop of any `<Sequence>` inside a `<ThreeCanvas>` must be set to `none`.
+
+```tsx
+import { Sequence } from "remotion";
+import { ThreeCanvas } from "@remotion/three";
+
+const { width, height } = useVideoConfig();
+
+<ThreeCanvas width={width} height={height}>
+  <Sequence layout="none">
+    <mesh>
+      <boxGeometry args={[2, 2, 2]} />
+      <meshStandardMaterial color="#4a9eff" />
+    </mesh>
+  </Sequence>
+</ThreeCanvas>
+```

package/framework/.claude/skills/remotion-best-practices/rules/animations.md

@@ -0,0 +1,29 @@
+---
+name: animations
+description: Fundamental animation skills for Remotion
+metadata:
+  tags: animations, transitions, frames, useCurrentFrame
+---
+
+All animations MUST be driven by the `useCurrentFrame()` hook.  
+Write animations in seconds and multiply them by the `fps` value from `useVideoConfig()`.
+
+```tsx
+import { useCurrentFrame } from "remotion";
+
+export const FadeIn = () => {
+  const frame = useCurrentFrame();
+  const { fps } = useVideoConfig();
+
+  const opacity = interpolate(frame, [0, 2 * fps], [0, 1], {
+    extrapolateRight: 'clamp',
+  });
+ 
+  return (
+    <div style={{ opacity }}>Hello World!</div>
+  );
+};
+```
+
+CSS transitions or animations are FORBIDDEN - they will not render correctly.  
+Tailwind animation class names are FORBIDDEN - they will not render correctly.