@caoscompanybr/merlin 3.5.0

package/.merlin-core/skills/general/apify-scrape/scripts/apify-scrape.sh

@@ -0,0 +1,68 @@
+#!/usr/bin/env bash
+# apify-scrape.sh — deterministic Apify calls for walled-garden social profiles.
+# Usage:
+#   apify-scrape.sh ig <instagram_handle>
+#   apify-scrape.sh linkedin <linkedin_profile_slug>
+#   apify-scrape.sh raw <actor> '<json_body>'
+# Options:
+#   --env <path>   explicit path to an apify.env file (key APIFY_TOKEN=...)
+#   --out <path>   where to save raw JSON (default: .merlin/apify/<key>.json)
+# Token discovery order: $APIFY_TOKEN  →  --env file  →  ./.secrets-vault/apify.env
+#   →  ../.secrets-vault/apify.env  →  ../../.secrets-vault/apify.env
+# Never echoes the token. Saves raw JSON so you can re-parse without re-calling (saves credits).
+set -euo pipefail
+
+ENV_PATH=""; OUT_PATH=""
+ARGS=()
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --env) ENV_PATH="$2"; shift 2 ;;
+    --out) OUT_PATH="$2"; shift 2 ;;
+    *) ARGS+=("$1"); shift ;;
+  esac
+done
+set -- "${ARGS[@]}"
+
+MODE="${1:-}"; [ -z "$MODE" ] && { echo "ERROR: mode required (ig|linkedin|raw)" >&2; exit 2; }
+
+find_token() {
+  if [ -n "${APIFY_TOKEN:-}" ]; then printf '%s' "$APIFY_TOKEN"; return 0; fi
+  local candidates=()
+  [ -n "$ENV_PATH" ] && candidates+=("$ENV_PATH")
+  candidates+=("./.secrets-vault/apify.env" "../.secrets-vault/apify.env" "../../.secrets-vault/apify.env" "../../../.secrets-vault/apify.env")
+  local f
+  for f in "${candidates[@]}"; do
+    if [ -f "$f" ]; then
+      local t; t="$(grep -E '^APIFY_TOKEN=' "$f" | head -1 | cut -d= -f2- | tr -d '\r\n')"
+      [ -n "$t" ] && { printf '%s' "$t"; return 0; }
+    fi
+  done
+  return 1
+}
+
+TOKEN="$(find_token || true)"
+if [ -z "$TOKEN" ]; then
+  echo "ERROR: APIFY_TOKEN not found (env, --env, or .secrets-vault/apify.env). Ask the user for it." >&2
+  exit 3
+fi
+
+case "$MODE" in
+  ig)       ACTOR="apify~instagram-profile-scraper"; KEY="${2:?handle required}"; BODY="{\"usernames\":[\"$KEY\"]}" ;;
+  linkedin) ACTOR="apimaestro~linkedin-profile-detail"; KEY="${2:?slug required}"; BODY="{\"username\":\"$KEY\"}" ;;
+  raw)      ACTOR="${2:?actor required}"; BODY="${3:?json body required}"; KEY="$(echo "$ACTOR" | tr -c 'A-Za-z0-9' '_')" ;;
+  *) echo "ERROR: unknown mode '$MODE' (use ig|linkedin|raw)" >&2; exit 2 ;;
+esac
+
+[ -z "$OUT_PATH" ] && OUT_PATH=".merlin/apify/${KEY}.json"
+mkdir -p "$(dirname "$OUT_PATH")"
+
+echo "Scraping via Apify actor '$ACTOR' (key: $KEY) ..." >&2
+HTTP=$(curl -s -w '%{http_code}' -X POST \
+  "https://api.apify.com/v2/acts/${ACTOR}/run-sync-get-dataset-items?token=${TOKEN}" \
+  -H "Content-Type: application/json" -d "$BODY" --max-time 220 -o "$OUT_PATH")
+
+if [ "$HTTP" != "200" ] && [ "$HTTP" != "201" ]; then
+  echo "ERROR: Apify returned HTTP $HTTP. Body:" >&2; cat "$OUT_PATH" >&2; exit 4
+fi
+echo "OK ($HTTP) → saved raw JSON to $OUT_PATH ($(wc -c < "$OUT_PATH") bytes)" >&2
+cat "$OUT_PATH"

package/.merlin-core/skills/general/backup/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: backup
+description: Managed backup system for project-owned data — ensures zero data loss during upgrades and fleet sync
+license: Apache-2.0
+metadata:
+  author: merlin-framework
+  version: "3.0.0"
+  auto_activate: [backup, upgrade, sync, fleet, restore, preserve]
+---
+
+# Backup Skill
+
+Creates managed backups of project-owned data before destructive operations like
+framework upgrades and fleet sync. Ensures zero tolerance for thought loss.
+
+## What Gets Backed Up
+
+| Data            | Source Path                        | Purpose                                                                |
+| --------------- | ---------------------------------- | ---------------------------------------------------------------------- |
+| Thoughts        | `.merlin-core/thoughts/`           | Plans, research, handoffs, decisions, reminders, objectives, learnings |
+| Domain skills   | `.merlin-core/skills/domain/`      | Project-specific skill extensions                                      |
+| Project config  | `.merlin-core/project-config.yaml` | Project identity and settings                                          |
+| Custom commands | `.claude/commands/`                | Satellite-specific slash commands                                      |
+
+## Backup Location
+
+```
+.merlin-backups/
+└── latest/
+    ├── backup-manifest.json    ← timestamp, version, contents inventory
+    ├── thoughts/               ← full copy of thoughts/
+    ├── domain-skills/          ← full copy of skills/domain/
+    ├── project-config.yaml     ← project identity
+    └── claude-commands/        ← custom slash commands
+```
+
+Only **one** backup is retained (the most recent). Old backups are rotated out
+when a new backup is created.
+
+## CLI Usage
+
+```bash
+# Backup current project
+node .merlin-core/tools/merlin-tools.js backup
+
+# Backup a specific satellite project
+node .merlin-core/tools/merlin-tools.js backup "/path/to/project"
+
+# Dry run — show what would be backed up
+node .merlin-core/tools/merlin-tools.js backup --dry-run
+```
+
+## Automatic Backups
+
+The `upgrade` tool automatically creates a backup in `.merlin-backups/latest/`
+**before** syncing framework files. No manual intervention needed.
+
+If the upgrade fails at any point:
+
+1. The pre-upgrade backup in `.merlin-backups/latest/` is preserved
+2. The temp directory is NOT deleted (for manual recovery)
+3. The tool reports the backup location in its error output
+
+## Restoring from Backup
+
+Manual copy from `.merlin-backups/latest/`:
+
+```bash
+# Restore thoughts
+cp -r .merlin-backups/latest/thoughts/ .merlin-core/thoughts/
+
+# Restore domain skills
+cp -r .merlin-backups/latest/domain-skills/ .merlin-core/skills/domain/
+
+# Restore project config
+cp .merlin-backups/latest/project-config.yaml .merlin-core/project-config.yaml
+
+# Restore custom commands
+cp -r .merlin-backups/latest/claude-commands/ .claude/commands/
+```
+
+## Safety Principles
+
+1. **Copy-then-delete** — Never delete the original until the copy is verified
+2. **Verify counts** — Thought count is checked before and after every operation
+3. **Preserve on failure** — Temp backups are never deleted if the operation failed
+4. **Additive merge** — Custom satellite commands are never overwritten by framework sync

package/.merlin-core/skills/general/blkskrn/SKILL.md

@@ -0,0 +1,392 @@
+---
+name: blkskrn
+description: "BLKSKRN — Create self-contained visual canvases — presentations, boards, diagrams — as local HTML artifacts that open in any browser, zero dependencies"
+license: Apache-2.0
+metadata:
+  author: merlin-framework
+  version: "3.0.0"
+  auto_activate: [blkskrn, presentation, slides, canvas, diagram, pitch-deck]
+  file_triggers: [*.canvas.html, *.slides.html]
+  tool_reminders: [Canvas artifacts are LOCAL HTML files — no external servers or apps needed, Keep individual slides under 50KB for performance, Always use the Merlin design system CSS classes from references/design-system.md]
+---
+
+# BLKSKRN — Local Visual Artifacts
+
+Create professional, animated visual artifacts — presentations, boards, diagrams —
+as self-contained HTML files that open in any browser. Every project with merlin-core
+gets BLKSKRN capabilities out of the box. No external apps, no servers, no dependencies.
+
+> **BLKSKRN vs a cloud whiteboard**: BLKSKRN is the local presentation engine built into
+> merlin-core. A separate cloud-based whiteboard app is a distinct tool — they may
+> share design tokens but are completely independent.
+
+---
+
+## When to Use
+
+- User asks to **showcase**, **present**, or **visualize** a project
+- During `/plan` when visual architecture diagrams would help
+- For stakeholder demos, pitch decks, or feature reviews
+- When onboarding new team members with a project walkthrough
+- When the user says "show me" or "I want to see" the project
+- Creating visual boards (strategy, SWOT, timeline, roadmap)
+
+## Architecture
+
+```
+Agent writes HTML slides
+  → canvas-manager.js registers them in canvas.json
+    → build command assembles presenter.html
+      → User opens in browser (offline, zero dependencies)
+```
+
+All artifacts are **self-contained HTML** with inlined CSS and JS.
+No build tools, no servers, no network — just open the file.
+
+### Storage Layout
+
+```
+{project-root}/
+└── .merlin/
+    └── canvas/                          # Runtime directory (gitignored)
+        ├── registry.json                # All canvases in this project
+        └── boards/
+            └── {canvas-id}/
+                ├── canvas.json          # Metadata + slide manifest
+                ├── index.html           # Built presenter (keyboard nav, fullscreen)
+                └── slides/
+                    ├── 01-title.html
+                    ├── 02-features.html
+                    └── ...
+```
+
+## Workflow
+
+Follow these steps to create a canvas artifact:
+
+### Step 1: Create the Canvas
+
+```bash
+node .merlin-core/skills/general/blkskrn/scripts/canvas-manager.js create "Sprint 12 Showcase"
+# Output: Created canvas abc12345 at .merlin/canvas/boards/abc12345/
+```
+
+### Step 2: Write Slide HTML Files
+
+Write each slide as a standalone HTML file. Use the design system CSS from
+`references/design-system.md`. Each slide is a complete HTML document:
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=1440, height=810" />
+    <style>
+      /* Paste design system CSS here — see references/design-system.md */
+      /* Then add slide-specific styles */
+    </style>
+  </head>
+  <body>
+    <div class="slide">
+      <div class="brand-line"></div>
+      <div class="slide-pad">
+        <!-- Slide content here -->
+      </div>
+      <span class="slide-num">01 / 08</span>
+    </div>
+  </body>
+</html>
+```
+
+Save slides as temporary files (e.g., `/tmp/slide-01.html` or any path).
+
+### Step 3: Add Slides to Canvas
+
+```bash
+node .merlin-core/skills/general/blkskrn/scripts/canvas-manager.js add-slide abc12345 /tmp/slide-01.html --title "Title Slide"
+node .merlin-core/skills/general/blkskrn/scripts/canvas-manager.js add-slide abc12345 /tmp/slide-02.html --title "Architecture"
+```
+
+### Step 4: Build the Presenter
+
+```bash
+node .merlin-core/skills/general/blkskrn/scripts/canvas-manager.js build abc12345
+# Output: Built presenter at .merlin/canvas/boards/abc12345/index.html
+```
+
+### Step 5: Open for Review
+
+```bash
+node .merlin-core/skills/general/blkskrn/scripts/canvas-manager.js open abc12345
+# Opens index.html in the default browser
+```
+
+### Other Commands
+
+```bash
+# List all canvases in this project
+node .merlin-core/skills/general/blkskrn/scripts/canvas-manager.js list
+
+# Delete a canvas
+node .merlin-core/skills/general/blkskrn/scripts/canvas-manager.js delete abc12345
+```
+
+## Presentation Design System
+
+Use the Merlin brand CSS foundation for all slides. See `references/design-system.md`
+for the complete system. Key tokens:
+
+| Token                 | Value     | Usage               |
+| --------------------- | --------- | ------------------- |
+| `--mc-bg-base`        | `#06080f` | Slide background    |
+| `--mc-bg-surface`     | `#0c1018` | Content areas       |
+| `--mc-bg-card`        | `#111622` | Cards, panels       |
+| `--mc-accent`         | `#7dd3fc` | Crystal blue accent |
+| `--mc-info`           | `#a78bfa` | Violet secondary    |
+| `--mc-text-primary`   | `#f0f4f8` | Headings            |
+| `--mc-text-secondary` | `#94a3b8` | Body text           |
+| `--mc-border`         | `#1e293b` | Subtle borders      |
+
+### CSS Classes Available
+
+| Class                                                 | Purpose                              |
+| ----------------------------------------------------- | ------------------------------------ |
+| `.slide`                                              | Root slide container (100vw x 100vh) |
+| `.slide-pad`                                          | Padded content area (56px/64px)      |
+| `.brand-line`                                         | 3px gradient bar at top              |
+| `.section-label`                                      | Uppercase small header               |
+| `.slide-title`                                        | 32px bold heading                    |
+| `.slide-subtitle`                                     | 14px muted subheading                |
+| `.hero-title`                                         | 52px hero text                       |
+| `.text-gradient`                                      | Gradient text effect                 |
+| `.feat-card`                                          | Feature card                         |
+| `.stat-card`                                          | Stat card (big number + label)       |
+| `.badge-crystal` / `.badge-violet` / `.badge-emerald` | Colored badges                       |
+| `.grid-2` / `.grid-3` / `.grid-4`                     | Grid layouts                         |
+| `.split`                                              | Two-column layout                    |
+| `.row` / `.row-tight` / `.row-wide`                   | Flex rows                            |
+
+## Slide Types
+
+See `references/slide-types.md` for complete examples. Standard types:
+
+1. **Title** — Logo, hero title with gradient, version badges, ambient background
+2. **Feature Grid** — 2x2 or 3x2 cards with icons, staggered entrance
+3. **Architecture** — Split layout: diagram left, details right
+4. **Stats/Numbers** — Grid of metric cards with counter animations
+5. **Timeline** — Horizontal phases with connections
+6. **Dashboard Recreation** — Miniaturized faithful UI recreation
+7. **Closing** — Summary pillars, call to action, credits
+
+## Production Quality Rules (MANDATORY)
+
+Every slide you produce MUST meet these standards. No exceptions.
+
+### 1. Ambient Background — EVERY slide
+
+Never leave a slide with just a flat `--mc-bg-base` background. Every slide
+MUST have at least one ambient layer:
+
+```html
+<!-- Option A: Grid + Orbs (content slides) -->
+<div class="grid-bg"></div>
+<div class="orb orb-crystal" style="top:-80px;right:-60px;"></div>
+<div
+  class="orb orb-violet"
+  style="bottom:-40px;left:-30px;animation-delay:0.5s;"
+></div>
+
+<!-- Option B: Title background (title/closing slides) -->
+<div class="title-bg"></div>
+
+<!-- Option C: Both for maximum depth -->
+<div class="grid-bg"></div>
+<div class="title-bg"></div>
+<div class="orb orb-emerald" style="top:50%;left:60%;"></div>
+```
+
+### 2. Animated Entrances — EVERY content element
+
+Nothing should appear statically. Use staggered animations:
+
+```html
+<!-- Cards in a grid: use slide-up-stagger on the parent -->
+<div class="grid-3 slide-up-stagger" style="flex:1;">
+  <div class="feat-card">...</div>
+  <!-- auto-delay 0.6s -->
+  <div class="feat-card">...</div>
+  <!-- auto-delay 0.65s -->
+  <div class="feat-card">...</div>
+  <!-- auto-delay 0.7s -->
+</div>
+
+<!-- Headings: explicit slide-up with delay -->
+<span class="section-label slide-up" style="animation-delay:0.3s;"
+  >SECTION</span
+>
+<h2 class="slide-title slide-up" style="animation-delay:0.4s;">Title</h2>
+<p class="slide-subtitle slide-up" style="animation-delay:0.5s;">Subtitle</p>
+
+<!-- Badges: use scale-pop -->
+<span class="badge badge-crystal scale-pop" style="animation-delay:1.2s;"
+  >v2.13</span
+>
+
+<!-- Logos: use logoSpin keyframe -->
+<div
+  class="logo-mark"
+  style="opacity:0;animation:logoSpin 0.8s var(--ease-bounce) 0.8s forwards;"
+>
+  M
+</div>
+```
+
+### 3. Fill the Screen — use ALL available space
+
+Content MUST expand to fill the 1440x810 viewport. Never leave large empty
+areas. Use these utilities:
+
+```html
+<!-- Make a grid fill available height -->
+<div class="grid-3 slide-up-stagger" style="flex:1;align-content:center;">
+  <!-- Make content area fill and center vertically -->
+  <div class="slide-pad fill-center">
+    <!-- Explicit flex:1 on content wrappers -->
+    <div
+      style="flex:1;display:flex;flex-direction:column;justify-content:center;"
+    ></div>
+  </div>
+</div>
+```
+
+### 4. Stat Numbers — ALWAYS animate with counters
+
+Never show static numbers. Use the `animateCounter` helper:
+
+```html
+<div class="stat-value" id="s1">0</div>
+<script>
+  animateCounter("s1", 42, 1000);
+</script>
+```
+
+### 5. Brand Line — ALWAYS animated
+
+The brand-line already animates via `sweep-in` in the base template. If you
+override it, keep the animation:
+
+```css
+.brand-line {
+  animation: sweepIn 1.2s var(--ease-enter) 0.2s forwards;
+}
+```
+
+### 6. Animation Timing Cascade
+
+Follow this timing pattern for a cinematic feel:
+
+| Delay    | Element                       |
+| -------- | ----------------------------- |
+| 0.0-0.2s | Brand line sweeps in          |
+| 0.3s     | Section label appears         |
+| 0.4s     | Slide title rises             |
+| 0.5s     | Subtitle fades in             |
+| 0.6-1.2s | Cards stagger in (50ms apart) |
+| 1.0-1.5s | Stats count up                |
+| 1.2-1.6s | Badges pop in                 |
+| 2.0s     | Orbs finish appearing         |
+
+## Animation Patterns
+
+See `references/animation-patterns.md` for 13 ready-to-use CSS animations.
+
+| Class                | Effect                | When to use               |
+| -------------------- | --------------------- | ------------------------- |
+| `.slide-up`          | Rise + fade           | Headings, paragraphs      |
+| `.slide-up-stagger`  | Auto-stagger children | Grid/list parents         |
+| `.card-enter`        | Rise + subtle scale   | Feature cards             |
+| `.scale-pop`         | Bounce overshoot      | Badges, icons, logos      |
+| `.sweep-in`          | Horizontal reveal     | Brand line, progress bars |
+| `.fade-in`           | Opacity only          | Backgrounds, orbs         |
+| `.from-left`         | Slide from left       | Left-side panels          |
+| `.from-right`        | Slide from right      | Right-side panels         |
+| `.grow-bar`          | Width expansion       | Progress bars, meters     |
+| `.glow-pulse::after` | Breathing glow border | Highlighted cards         |
+
+### Performance Rules
+
+1. Only animate `transform` and `opacity` (GPU composited)
+2. Never animate layout properties (`width`, `height`, `margin`)
+3. Max 50ms stagger between sequential items
+4. Duration: 200-300ms interactions, up to 1000ms illustrative
+
+### Accessibility
+
+Always include reduced-motion support (already in slide-base.html template):
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  *,
+  *::before,
+  *::after {
+    animation-duration: 0.01ms !important;
+    transition-duration: 0.01ms !important;
+  }
+}
+```
+
+## Presenter Controls
+
+The built presenter (`index.html`) supports:
+
+| Key                 | Action            |
+| ------------------- | ----------------- |
+| `→` / `↓` / `Space` | Next slide        |
+| `←` / `↑`           | Previous slide    |
+| `F`                 | Toggle fullscreen |
+| `Escape`            | Exit fullscreen   |
+| `Home`              | First slide       |
+| `End`               | Last slide        |
+
+Navigation dots at the bottom allow click-to-jump.
+
+## How to Build a Project Presentation
+
+### Research First
+
+Before building slides, thoroughly research the project:
+
+1. Read the project's CLAUDE.md / README
+2. Scan the directory structure (key directories, tech stack)
+3. Read core configuration files
+4. Check thoughts/shared/ for plans, decisions, objectives
+5. Read main UI components (if frontend exists)
+6. Identify the project's color theme / design tokens
+
+### Typical Slide Structure (12-16 slides)
+
+| #     | Slide                    | Content Source                   |
+| ----- | ------------------------ | -------------------------------- |
+| 01    | Title                    | Project name, version, tagline   |
+| 02    | Vision / Architecture    | README, CLAUDE.md                |
+| 03    | Core Features            | Directory structure, key modules |
+| 04-06 | Feature Deep Dives       | Specific subsystems              |
+| 07-09 | UI/Dashboard Recreations | Actual frontend code             |
+| 10-12 | Workflows / Processes    | Workflow configs, commands       |
+| 13-14 | Quality / Infrastructure | CI/CD, testing, deploy           |
+| 15    | By The Numbers           | Stats from codebase              |
+| 16    | Closing                  | Summary, next steps              |
+
+## Best Practices
+
+1. **Research before building** — Read actual project code, don't guess
+2. **Match the project's real theme** — Extract actual CSS tokens
+3. **Keep slides focused** — One concept per slide, max 6 content items
+4. **Use consistent spacing** — 56px top / 64px sides padding standard
+5. **SVG for icons** — Use inline SVG, not icon fonts
+6. **No external resources** — Everything must be inlined
+7. **Add slide numbers** — Bottom-right, `"01 / {total}"` format
+8. **Replay buttons on animated slides** — `onclick="location.reload()"`
+9. **Standard size** — 1440x810px (16:9 aspect ratio)
+10. **Write slides individually** — Then add to canvas with canvas-manager