@caoscompanybr/merlin 3.5.0

package/.merlin-core/skills/domain/ops-manual/SKILL.md

@@ -0,0 +1,225 @@
+---
+name: ops-manual
+description: Project-specific operations manual — routes agents to the right commit, build, deploy, CI/CD, and publish instructions based on project-config.yaml operations section.
+license: Apache-2.0
+metadata:
+  author: merlin-framework
+  version: "3.0.0"
+  auto_activate:
+    [ops, operations, project-setup, onboard-project, deploy-config, ci-config]
+---
+
+## Purpose
+
+Every project has different answers to the same questions: How do I commit? How do I deploy? What CI runs? Where does it publish?
+
+This skill is the **single source of truth** for operational procedures. Instead of each agent guessing or asking every time, they read `operations` from the project's `project-config.yaml` and follow it.
+
+## How It Works
+
+```
+project-config.yaml → operations: { git, build, deploy[], ci, publish }
+                                      ↓
+                              ops-manual skill
+                           ┌────────┼────────┐
+                           ↓        ↓        ↓
+                         Dex      Gage    /commit
+                      (git,build) (deploy,  (git config)
+                                  ci,publish)
+```
+
+### Agent Ownership
+
+| Section              | Primary Agent   | Reads When                                |
+| -------------------- | --------------- | ----------------------------------------- |
+| `operations.git`     | Dex (dev)       | Committing, branching, pre-commit hooks   |
+| `operations.git`     | /commit command | Formatting commit messages                |
+| `operations.build`   | Dex (dev)       | Running builds during /implement          |
+| `operations.deploy`  | Gage (devops)   | Any deploy, go-live, or push-to-prod      |
+| `operations.ci`      | Gage (devops)   | Setting up or troubleshooting CI/CD       |
+| `operations.publish` | Gage (devops)   | Publishing packages, extensions, releases |
+
+### External Skill Routing
+
+When the `deploy[].platform` value points to an external skill, Gage reads the corresponding skill for deep platform knowledge:
+
+| Platform   | External Skill Path                                                         |
+| ---------- | --------------------------------------------------------------------------- |
+| firebase   | `.agents/skills/firebase-hosting-basics/` or `firebase-app-hosting-basics/` |
+| cloudflare | `.agents/skills/cloudflare/` + `wrangler/`                                  |
+| docker     | `.agents/skills/docker-deployment/`                                         |
+| vps        | `.agents/skills/ssh-hardening/` + `.agents/skills/docker-deployment/`       |
+| vercel     | Built-in deploy skill                                                       |
+| netlify    | Built-in deploy skill                                                       |
+| azure      | `.merlin-core/skills/domain/azure-cloud/` (if created)                      |
+
+If a platform skill is not installed, Gage falls back to the `operations.deploy[].command` and `deploy_steps` from config — the external skill adds depth, not dependency.
+
+## Reading Operations Config
+
+At the start of any operational task, the acting agent reads the config:
+
+```
+1. Read .merlin-core/project-config.yaml → operations section
+2. If operations section exists → follow it
+3. If operations section is missing → run elicitation (see references/elicitation-questions.md)
+4. If specific field is empty → use sensible defaults or ask user
+```
+
+### Sensible Defaults (when config is missing)
+
+| Field                   | Default                                  |
+| ----------------------- | ---------------------------------------- |
+| `git.branch_strategy`   | trunk                                    |
+| `git.main_branch`       | main                                     |
+| `git.commit_convention` | conventional                             |
+| `build.command`         | `npm run build` (if package.json exists) |
+| `deploy[].approval`     | HIGH                                     |
+| `ci.provider`           | none                                     |
+| `publish.platform`      | none                                     |
+
+## Operational Checklists
+
+### Commit Checklist (Dex + /commit)
+
+```
+□ Read operations.git from project-config.yaml
+□ Use commit_convention format (conventional, jira, plain)
+□ Apply commit_prefix if set (e.g., "PROJ-123: ")
+□ Verify branch matches branch_strategy expectations
+□ Run pre_commit_hooks if defined
+□ Stage specific files — never git add -A
+□ Never --no-verify unless user explicitly requests
+□ Present message for user approval before committing
+```
+
+### Build Checklist (Dex)
+
+```
+□ Read operations.build from project-config.yaml
+□ Run pre_build commands if defined (npm install, prisma generate, etc.)
+□ Execute build.command
+□ Verify output appears in build.output_dir
+□ Check for TypeScript/lint errors in build output
+□ If build fails, diagnose before retrying
+```
+
+### Deploy Checklist (Gage)
+
+```
+□ Read operations.deploy[] from project-config.yaml
+□ Identify target by name (production, staging, vps-primary, etc.)
+□ Check approval level — if HIGH, require explicit user confirmation
+□ Load external skill for the platform (firebase, docker, vps, etc.)
+□ For VPS targets:
+  □ SSH to vps.host as vps.user on vps.port
+  □ Execute vps.deploy_steps in order
+  □ On failure, run vps.rollback
+□ For platform targets:
+  □ Verify env vars are configured at env_vars_location
+  □ Execute deploy command
+□ Post-deploy: verify URL responds
+□ On failure: report full error + rollback instructions
+```
+
+### CI/CD Checklist (Gage)
+
+```
+□ Read operations.ci from project-config.yaml
+□ If provider is "none", skip CI
+□ Check ci.config_file exists and is valid
+□ For github-actions: validate .github/workflows/ YAML
+□ Verify pipeline runs on protected_branches (from git config)
+□ Pipeline must run: lint, test, typecheck, build (Quality Layer 1)
+□ If pipeline_url exists, provide it for monitoring
+```
+
+### Publish Checklist (Gage)
+
+```
+□ Read operations.publish from project-config.yaml
+□ If platform is "none", skip
+□ Run pre_publish commands (build, test)
+□ Approval: ALWAYS HIGH for publishing
+□ Execute publish.command
+□ Verify published artifact is accessible
+```
+
+## Onboarding New Projects
+
+When a project has no `operations` section, trigger elicitation:
+
+1. Auto-detect from project files (see `references/elicitation-questions.md` auto-detection checklist)
+2. Ask user only for what can't be auto-detected
+3. Write results to `project-config.yaml` under `operations:`
+4. Use `references/operations-template.yaml` as the base structure
+
+This happens during:
+
+- `/converterparamagos` (full project onboarding)
+- First time `/commit` is run and no `operations.git` exists
+- First time `/deploy` is run and no `operations.deploy` exists
+
+## Examples
+
+### Example 1: Dex committing with Jira convention
+
+```yaml
+# project-config.yaml
+operations:
+  git:
+    commit_convention: jira
+    commit_prefix: "BACK-"
+```
+
+Dex reads this and formats commits as: `BACK-42: Add user authentication endpoint`
+
+### Example 2: Gage deploying to VPS
+
+```yaml
+# project-config.yaml
+operations:
+  deploy:
+    - name: production
+      platform: vps
+      approval: HIGH
+      vps:
+        host: "app.example.com"
+        user: "deploy"
+        deploy_path: "/opt/webapp"
+        deploy_steps:
+          - "cd /opt/webapp && git pull origin main"
+          - "npm install --production"
+          - "npm run build"
+          - "pm2 restart webapp"
+        rollback: "cd /opt/webapp && git checkout HEAD~1 && pm2 restart webapp"
+```
+
+Gage asks for user confirmation (HIGH), SSHs in, runs steps sequentially, reports success or triggers rollback.
+
+### Example 3: Firebase + GitHub Actions
+
+```yaml
+# project-config.yaml
+operations:
+  deploy:
+    - name: production
+      platform: firebase
+      command: "firebase deploy --only hosting"
+      url: "https://myapp.web.app"
+      approval: HIGH
+  ci:
+    provider: github-actions
+    config_file: ".github/workflows/deploy.yml"
+    pipeline_url: "https://github.com/org/repo/actions"
+```
+
+Gage reads the firebase platform, loads `.agents/skills/firebase-hosting-basics/` for deep docs, runs the deploy command, then checks the pipeline URL.
+
+## References
+
+| File                                     | Purpose                                       |
+| ---------------------------------------- | --------------------------------------------- |
+| `references/operations-template.yaml`    | Copy-paste template for project-config.yaml   |
+| `references/elicitation-questions.md`    | 23 questions for populating operations config |
+| `references/external-skills-registry.md` | Inventory of 18 installed external skills     |

package/.merlin-core/skills/domain/ops-manual/references/elicitation-questions.md

@@ -0,0 +1,141 @@
+# Operations Elicitation Questions
+
+When onboarding a new project (via `/converterparamagos` or manually), Orion asks these questions to populate the `operations` section of `project-config.yaml`.
+
+**Auto-detect first, ask second.** Many answers can be inferred from the project's files. Only ask the user when auto-detection is ambiguous or impossible.
+
+---
+
+## Auto-Detection Checklist
+
+Before asking questions, check for these files:
+
+| File Found                                  | Infer                                  |
+| ------------------------------------------- | -------------------------------------- |
+| `firebase.json`                             | platform: firebase                     |
+| `apphosting.yaml`                           | platform: firebase (app hosting / SSR) |
+| `vercel.json`                               | platform: vercel                       |
+| `netlify.toml`                              | platform: netlify                      |
+| `wrangler.toml`                             | platform: cloudflare                   |
+| `Dockerfile` or `docker-compose.yml`        | platform: docker                       |
+| `azure.yaml` or `*.bicep`                   | platform: azure                        |
+| `.github/workflows/*.yml`                   | ci.provider: github-actions            |
+| `.gitlab-ci.yml`                            | ci.provider: gitlab-ci                 |
+| `package.json` scripts.build                | build.command                          |
+| `package.json` scripts.deploy               | deploy command                         |
+| `.husky/` or `lint-staged` in package.json  | pre_commit_hooks                       |
+| `git branch --show-current` or `git remote` | main_branch                            |
+| `.nvmrc`, `requirements.txt`, `Cargo.toml`  | stack detection                        |
+
+---
+
+## Questions by Section
+
+### Git & Commit (populates `operations.git`)
+
+1. **What's your branching strategy?**
+   - Auto-detect: If only `main` exists → trunk. If `develop` exists → gitflow.
+   - Ask if ambiguous: "I see branches `main` and `develop`. Do you use gitflow or github-flow?"
+   - Values: `gitflow` | `trunk` | `github-flow` | `custom`
+
+2. **What's the main branch name?**
+   - Auto-detect: `git symbolic-ref refs/remotes/origin/HEAD` or check `main` vs `master`
+   - Ask if no remote or multiple candidates
+
+3. **Are there protected branches?**
+   - Auto-detect: GitHub API `gh api repos/{owner}/{repo}/branches/{branch}/protection` if gh available
+   - Default: `[main]` or `[master]`
+
+4. **Do you use conventional commits?**
+   - Auto-detect: Read last 10 commit messages. If >70% match `type(scope): desc` → conventional
+   - Ask if mixed: "Your recent commits use mixed formats. Should I enforce conventional commits?"
+   - Values: `conventional` | `jira` | `plain` | `custom`
+
+5. **Is there a commit prefix? (e.g., Jira ticket ID)**
+   - Auto-detect: If commits contain patterns like `PROJ-123` → prefix = "PROJ-"
+   - Only ask if jira convention detected
+
+6. **What pre-commit hooks are configured?**
+   - Auto-detect: Check `.husky/pre-commit`, `lint-staged` in package.json, `.pre-commit-config.yaml`
+   - Values: array of `lint`, `test`, `typecheck`, `format`, etc.
+
+### Build (populates `operations.build`)
+
+7. **What's the build command?**
+   - Auto-detect: `package.json` → `scripts.build`
+   - Fallback: Check for `Makefile`, `Cargo.toml`, `setup.py`
+   - Ask if no build script found: "I couldn't detect a build command. What do you run to build?"
+
+8. **Where does the build output go?**
+   - Auto-detect from framework:
+     - Next.js → `.next/`
+     - Vite → `dist/`
+     - CRA → `build/`
+     - Cargo → `target/release/`
+   - Ask if custom framework
+
+9. **Is there a production env file?**
+   - Auto-detect: Check for `.env.production`, `.env.prod`
+   - Only mention if found: "I found `.env.production`. Should I reference it in build config?"
+
+### Deploy (populates `operations.deploy`)
+
+10. **Where does this project deploy?**
+    - Auto-detect from files (see checklist above)
+    - Ask if none detected: "I don't see a firebase.json, vercel.json, or Dockerfile. Where does this project deploy?"
+    - Values: `firebase` | `vercel` | `netlify` | `cloudflare` | `vps` | `docker` | `azure` | `aws` | `manual` | `none`
+
+11. **What's the deploy command?**
+    - Auto-detect: `package.json` → `scripts.deploy` or `scripts.deploy:prod`
+    - Platform defaults: firebase → `firebase deploy --only hosting`, vercel → `vercel --prod`
+    - Ask if custom: "What command deploys to production?"
+
+12. **What's the production URL?**
+    - Auto-detect: Firebase → check `.firebaserc` for project ID → `{id}.web.app`
+    - Ask if not detectable: "What's the production URL?"
+
+13. **Is there a staging environment?**
+    - Auto-detect: Check for `scripts.deploy:staging`, Vercel preview branches
+    - Ask: "Do you have a staging environment? If so, what's the URL?"
+
+14. **What approval level for production deploys?**
+    - Default: HIGH (always)
+    - Only ask for staging: "Should staging deploys require confirmation or auto-approve in YOLO mode?"
+
+15. **[If VPS] What's the SSH connection info?**
+    - Ask: "What's the VPS host, SSH user, and port?"
+    - Ask: "What's the deploy path on the server? (e.g., /opt/myapp)"
+
+16. **[If VPS] What are the deploy steps?**
+    - Ask: "Walk me through the deploy: after SSH, what commands run? (e.g., git pull, npm install, build, restart)"
+
+17. **[If VPS] How do you rollback?**
+    - Ask: "If a deploy fails, what's the rollback command?"
+
+18. **Where are environment variables configured?**
+    - Platform-specific defaults: Firebase → "Firebase Console", Vercel → "Vercel Dashboard", VPS → ".env on server"
+    - Ask if unclear
+
+### CI/CD (populates `operations.ci`)
+
+19. **Do you use CI/CD?**
+    - Auto-detect: `.github/workflows/`, `.gitlab-ci.yml`, `azure-pipelines.yml`
+    - Ask if none found: "Do you use CI/CD? If so, which provider?"
+
+20. **Where's the CI config?**
+    - Auto-detect: First `.yml` in `.github/workflows/`
+    - Ask if multiple: "I found multiple workflow files. Which is the primary deploy pipeline?"
+
+21. **Is there a pipeline dashboard URL?**
+    - Auto-detect: GitHub → `https://github.com/{owner}/{repo}/actions`
+    - Ask for other providers
+
+### Publish (populates `operations.publish`)
+
+22. **Is this a publishable package or extension?**
+    - Auto-detect: `package.json` → `private: false` means publishable. Chrome extension → `manifest.json` with MV3.
+    - Ask if ambiguous: "Is this published to npm / Chrome Web Store / etc.?"
+
+23. **What's the publish command and pre-publish checks?**
+    - Auto-detect: `package.json` → `scripts.prepublishOnly`, `scripts.publish`
+    - Default for npm: `npm publish` with pre-publish `["npm run build", "npm test"]`

package/.merlin-core/skills/domain/ops-manual/references/external-skills-registry.md

@@ -0,0 +1,63 @@
+# External Skills Registry
+
+Tracks all skills installed in `.agents/skills/` with source, trust tier, audit status, and token footprint.
+
+**Last full audit:** 2026-03-19
+**Update command:** `npx skills update`
+**Re-audit after update:** Run frontmatter parser + read SKILL.md for each updated skill.
+
+---
+
+## Tier 1 — Official (from the companies themselves)
+
+| Skill                             | Source Repo             | Audit Date | Status | Tokens |
+| --------------------------------- | ----------------------- | ---------- | ------ | ------ |
+| firebase-hosting-basics           | `firebase/agent-skills` | 2026-03-19 | SAFE   | ~543   |
+| firebase-app-hosting-basics       | `firebase/agent-skills` | 2026-03-19 | SAFE   | ~604   |
+| cloudflare                        | `cloudflare/skills`     | 2026-03-19 | SAFE   | ~2034  |
+| workers-best-practices            | `cloudflare/skills`     | 2026-03-19 | SAFE   | ~1793  |
+| wrangler                          | `cloudflare/skills`     | 2026-03-19 | SAFE   | ~4459  |
+| durable-objects                   | `cloudflare/skills`     | 2026-03-19 | SAFE   | ~1513  |
+| agents-sdk                        | `cloudflare/skills`     | 2026-03-19 | SAFE   | ~1434  |
+| sandbox-sdk                       | `cloudflare/skills`     | 2026-03-19 | SAFE   | ~1487  |
+| web-perf                          | `cloudflare/skills`     | 2026-03-19 | SAFE   | ~2090  |
+| building-ai-agent-on-cloudflare   | `cloudflare/skills`     | 2026-03-19 | SAFE   | ~2547  |
+| building-mcp-server-on-cloudflare | `cloudflare/skills`     | 2026-03-19 | SAFE   | ~1716  |
+| supabase-postgres-best-practices  | `supabase/agent-skills` | 2026-03-19 | SAFE   | ~660   |
+
+## Tier 2 — Community (audited, no prompt injection found)
+
+| Skill                   | Source Repo                         | Audit Date | Status | Tokens |
+| ----------------------- | ----------------------------------- | ---------- | ------ | ------ |
+| docker-deployment       | `aaaaqwq/claude-code-skills`        | 2026-03-19 | SAFE   | ~498   |
+| ssh-hardening           | `mikr13/secure-server-setup-skills` | 2026-03-19 | SAFE   | ~2107  |
+| agno                    | `delorenj/skills`                   | 2026-03-19 | SAFE   | ~3528  |
+| github-actions-workflow | `aj-geddes/useful-ai-prompts`       | 2026-03-19 | SAFE   | ~632   |
+| devops-cicd             | `miles990/claude-software-skills`   | 2026-03-19 | SAFE   | ~3062  |
+| git-commit-workflow     | `laurigates/claude-plugins`         | 2026-03-19 | SAFE   | ~1639  |
+
+---
+
+## Auto-Activate Status
+
+**All 18 external skills return `auto_activate=[]`** through Merlin's frontmatter parser. They use non-Merlin frontmatter formats (`triggers:`, `tags:`, or no activation keywords). L6 will never auto-inject them. Agents must explicitly `Read` their files when needed, routed by the ops-manual domain skill.
+
+---
+
+## Coverage Map
+
+| Domain                 | Skills Available                                                   | Use For                                      |
+| ---------------------- | ------------------------------------------------------------------ | -------------------------------------------- |
+| Firebase (static/SPA)  | firebase-hosting-basics                                            | CDN deploy, preview channels, rewrites       |
+| Firebase (SSR/Next.js) | firebase-app-hosting-basics                                        | App Hosting, apphosting.yaml, secrets        |
+| Cloudflare (platform)  | cloudflare, wrangler, workers-best-practices                       | Workers, Pages, KV, D1, R2, AI               |
+| Cloudflare (advanced)  | durable-objects, agents-sdk, sandbox-sdk                           | Stateful coordination, AI agents, sandboxing |
+| Cloudflare (perf)      | web-perf                                                           | Core Web Vitals, optimization                |
+| Cloudflare (guides)    | building-ai-agent-on-cloudflare, building-mcp-server-on-cloudflare | Tutorials                                    |
+| Docker + Nginx         | docker-deployment                                                  | Containers, HTTPS, Cloudflare Tunnel         |
+| VPS/SSH                | ssh-hardening                                                      | Ed25519 keys, sshd_config, hardening scripts |
+| CI/CD (GitHub Actions) | github-actions-workflow                                            | Workflows, matrix builds, releases           |
+| CI/CD (patterns)       | devops-cicd                                                        | Blue-green, canary, K8s, Terraform, GitOps   |
+| Git workflow           | git-commit-workflow                                                | Conventional commits, staging, issue linking |
+| AI agents              | agno                                                               | Agno framework, teams, workflows, AgentOS    |
+| Database               | supabase-postgres-best-practices                                   | Query perf, RLS, schema design, connections  |

package/.merlin-core/skills/domain/ops-manual/references/operations-template.yaml

@@ -0,0 +1,132 @@
+# ============================================
+# Operations Manual Template
+# ============================================
+# Copy this section into your project's .merlin-core/project-config.yaml
+# under the `operations:` key. Fill in values for your project.
+#
+# Agent ownership:
+#   - Dex (dev) reads: git, build
+#   - Gage (devops) reads: deploy, ci, publish
+#   - Orion (master) populates this during onboarding
+#   - Quinn (QA) validates completeness
+# ============================================
+
+operations:
+
+  # --- Git & Commit Conventions ---
+  # Read by Dex and /commit command
+  git:
+    # Branching model: gitflow | trunk | github-flow | custom
+    branch_strategy: trunk
+
+    # Primary branch name
+    main_branch: main
+
+    # Branches that require PR review before merge
+    protected_branches:
+      - main
+
+    # Commit message format: conventional | jira | plain | custom
+    # conventional = type(scope): description
+    # jira = PROJ-123: description
+    # plain = free text
+    commit_convention: conventional
+
+    # Prefix for commit messages (e.g., "PROJ-" for Jira)
+    # Leave empty for no prefix
+    commit_prefix: ""
+
+    # What runs on pre-commit hooks
+    # Common: lint, test, typecheck, format
+    pre_commit_hooks: []
+
+  # --- Build Configuration ---
+  # Read by Dex during implementation
+  build:
+    # Build command
+    command: "npm run build"
+
+    # Where build artifacts go
+    output_dir: "dist/"
+
+    # Environment file for production builds (optional)
+    # env_file: ".env.production"
+
+    # Commands to run before build (optional)
+    # pre_build:
+    #   - "npm install"
+    #   - "prisma generate"
+
+  # --- Deploy Targets ---
+  # Read by Gage. Array — project can have multiple targets.
+  # Each target maps to a platform with specific external skill docs.
+  #
+  # Platform → External skill for deep docs:
+  #   firebase  → .agents/skills/firebase-hosting-basics/ or firebase-app-hosting-basics/
+  #   vercel    → built-in deploy skill
+  #   netlify   → built-in deploy skill
+  #   cloudflare → .agents/skills/cloudflare/ + wrangler/
+  #   vps       → .agents/skills/ssh-hardening/ + docker-deployment/
+  #   docker    → .agents/skills/docker-deployment/
+  #   azure     → .merlin-core/skills/domain/azure-cloud/
+  #   aws       → (no skill installed yet)
+  #   manual    → follow command instructions
+  #   none      → no deployment
+  deploy:
+    - name: production
+      platform: firebase           # Change to your platform
+      command: "firebase deploy --only hosting"
+      url: "https://myapp.web.app"
+      approval: HIGH               # HIGH = explicit human approval required
+      env_vars_location: "Firebase Console > Project Settings > Service accounts"
+
+    # Uncomment for staging:
+    # - name: staging
+    #   platform: vercel
+    #   command: "vercel --env preview"
+    #   url: "https://staging.myapp.vercel.app"
+    #   approval: MEDIUM
+
+    # Uncomment for VPS:
+    # - name: vps
+    #   platform: vps
+    #   command: ""  # VPS uses deploy_steps instead
+    #   url: "https://myapp.example.com"
+    #   approval: HIGH
+    #   vps:
+    #     host: "192.168.1.100"
+    #     user: "deploy"
+    #     port: 22
+    #     deploy_path: "/opt/myapp"
+    #     deploy_steps:
+    #       - "cd /opt/myapp && git pull origin main"
+    #       - "npm install --production"
+    #       - "npm run build"
+    #       - "pm2 restart myapp"
+    #     rollback: "pm2 restart myapp --update-env"
+
+  # --- CI/CD Pipeline ---
+  # Read by Gage
+  ci:
+    # Provider: github-actions | gitlab-ci | azure-pipelines | circleci | none
+    provider: none
+
+    # Path to CI config file
+    # config_file: ".github/workflows/deploy.yml"
+
+    # URL to pipeline dashboard
+    # pipeline_url: "https://github.com/org/repo/actions"
+
+  # --- Publish Configuration ---
+  # Read by Gage. For libraries, extensions, packages.
+  publish:
+    # Platform: npm | pypi | cargo | chrome-web-store | play-store | app-store | none
+    platform: none
+
+    # Publish command
+    # command: "npm publish"
+
+    # Pre-publish checks
+    # pre_publish:
+    #   - "npm run build"
+    #   - "npm test"

package/.merlin-core/skills/domain/remotion-best-practices/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: remotion-best-practices
+description: Domain knowledge for Remotion — programmatic video creation with React. Covers compositions, animations, timing, audio, captions, transitions, media handling, 3D, charts, maps, and rendering. Activates when working on any Remotion-based project (programmatic-video or music-video-rendering pipelines).
+license: MIT
+metadata:
+  author: remotion-dev
+  version: "4.0.411"
+  source: "skills.sh/remotion-dev/skills/remotion-best-practices"
+  auto_activate: [ remotion, video-composition, programmatic-video, remotion-render, music-video-pipeline, ]
+  file_triggers: [remotion.config.*, *.composition.tsx, **/compositions/**, **/remotion/**]
+  tool_reminders: [Remotion renders are CPU/GPU intensive — confirm render backend before batch operations, NEVER run `npx remotion upgrade` — it breaks Zod v3 schemas. Pin versions via npm overrides, NEVER put directory junctions/symlinks in public/ — webpack hangs indefinitely on Windows, Use <Video> in Studio mode, <OffthreadVideo> in render mode for reliable playback, Remotion bundles its own FFmpeg — do not install a separate FFmpeg for rendering]
+---
+
+## Remotion Best Practices — Domain Skill
+
+Expert knowledge for building programmatic videos with Remotion 4.x and React.
+
+### When This Activates
+
+This skill activates on any Remotion-based project. Merlin provides the **knowledge layer**; the actual rendering runtime lives in your project repositories.
+
+### Architecture Context
+
+```
+Merlin Core (this skill = KNOWLEDGE)
+    ↓ teaches agents how to write Remotion code
+<project>/renderer/ (RUNTIME)
+    ↓ actually renders videos
+    ├── React components
+    ├── video templates
+    ├── video manifests
+    └── Remotion 4.0.411 + FFmpeg
+```
+
+### Rule Files (31 topics)
+
+Read individual rules for detailed explanations and code examples:
+
+**Media Handling:**
+
+- [rules/audio.md](rules/audio.md) — Audio import, trimming, volume, speed, pitch
+- [rules/videos.md](rules/videos.md) — Video embedding, trimming, volume, looping
+- [rules/images.md](rules/images.md) — Image embedding with the Img component
+- [rules/gifs.md](rules/gifs.md) — GIF/APNG synchronized with timeline
+- [rules/fonts.md](rules/fonts.md) — Google Fonts and local font loading
+- [rules/assets.md](rules/assets.md) — Importing images, videos, audio, fonts
+- [rules/lottie.md](rules/lottie.md) — Lottie animation embedding
+
+**Animation & Timing:**
+
+- [rules/animations.md](rules/animations.md) — Fundamental animation patterns
+- [rules/timing.md](rules/timing.md) — Interpolation, easing, spring physics
+- [rules/transitions.md](rules/transitions.md) — Scene transitions (fade, slide, wipe)
+- [rules/text-animations.md](rules/text-animations.md) — Typography animation patterns
+- [rules/sequencing.md](rules/sequencing.md) — Sequence, Series, delay, trim
+- [rules/trimming.md](rules/trimming.md) — Trim beginning/end of animations
+
+**Composition & Layout:**
+
+- [rules/compositions.md](rules/compositions.md) — Compositions, stills, folders, default props
+- [rules/parameters.md](rules/parameters.md) — Zod schema parametrization
+- [rules/measuring-text.md](rules/measuring-text.md) — Text measurement, fitting, overflow
+- [rules/measuring-dom-nodes.md](rules/measuring-dom-nodes.md) — DOM element dimensions
+- [rules/tailwind.md](rules/tailwind.md) — TailwindCSS in Remotion
+
+**Captions & Speech:**
+
+- [rules/display-captions.md](rules/display-captions.md) — TikTok-style captions with word highlighting
+- [rules/import-srt-captions.md](rules/import-srt-captions.md) — .srt subtitle import
+- [rules/transcribe-captions.md](rules/transcribe-captions.md) — Audio-to-caption transcription
+
+**Media Analysis:**
+
+- [rules/calculate-metadata.md](rules/calculate-metadata.md) — Dynamic duration, dimensions, props
+- [rules/can-decode.md](rules/can-decode.md) — Video decode capability check
+- [rules/get-audio-duration.md](rules/get-audio-duration.md) — Audio duration via Mediabunny
+- [rules/get-video-duration.md](rules/get-video-duration.md) — Video duration via Mediabunny
+- [rules/get-video-dimensions.md](rules/get-video-dimensions.md) — Video dimensions via Mediabunny
+- [rules/extract-frames.md](rules/extract-frames.md) — Frame extraction at timestamps
+
+**Advanced:**
+
+- [rules/3d.md](rules/3d.md) — Three.js and React Three Fiber integration
+- [rules/charts.md](rules/charts.md) — Data visualization (bars, pies, SVG)
+- [rules/maps.md](rules/maps.md) — Mapbox map animations with turf.js
+- [rules/transparent-videos.md](rules/transparent-videos.md) — VP9/ProRes transparency rendering
+
+### Code Assets
+
+- [rules/assets/charts-bar-chart.tsx](rules/assets/charts-bar-chart.tsx) — Animated bar chart component
+- [rules/assets/text-animations-typewriter.tsx](rules/assets/text-animations-typewriter.tsx) — Typewriter text effect
+- [rules/assets/text-animations-word-highlight.tsx](rules/assets/text-animations-word-highlight.tsx) — Word highlight animation
+
+### Critical Rules (from production experience)
+
+1. **Version pinning** — All `@remotion/*` packages must be the same version. Use npm `overrides` to force alignment.
+2. **Studio vs Render** — Use `<Video>` in Studio, `<OffthreadVideo>` in render. OffthreadVideo hangs in Studio with missing files.
+3. **Windows gotchas** — No NTFS junctions in `public/`, no NVENC GPU encoding (use CPU H.264), kill lingering node processes before Studio restart.
+4. **Asset management** — Copy specific files to `public/` per manifest. Never symlink entire media directories.