rsc-universal 0.1.1

package/skills/agent-eval/scripts/verify.sh

@@ -0,0 +1,161 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# verify.sh — agent-eval skill gate. Run from your PROJECT root.
+#
+# What it does (read-only, idempotent, NEVER calls an LLM or network):
+#   1. Discovers *.jsonl golden sets (skips vendor dirs); checks every line parses
+#      and carries the required keys id, input, expected. Hard fail on a bad line.
+#   2. If an eval-report.json exists, validates its shape (a "passed" boolean and a
+#      "metrics" object). Hard fail only on malformed JSON / missing shape.
+#   3. Optional lint, advisory only: ruff + mypy on example Python, markdownlint on docs.
+#
+# Exit non-zero ONLY on a malformed JSONL line, a missing required key, or a malformed
+# eval-report.json. Every optional lint and every missing tool is a yellow WARN/skip.
+# An empty or clean target exits 0. Stock macOS bash 3.2 (no mapfile / associative arrays).
+
+YELLOW=$'\033[33m'; GREEN=$'\033[32m'; RED=$'\033[31m'; NC=$'\033[0m'
+EXIT=0
+skip() { printf '%s[skip]%s %s\n' "$YELLOW" "$NC" "$*"; }
+note() { printf '%s[warn]%s %s\n' "$YELLOW" "$NC" "$*"; }
+ok()   { printf '%s[ok]%s %s\n'   "$GREEN"  "$NC" "$*"; }
+err()  { printf '%s[fail]%s %s\n' "$RED"    "$NC" "$*"; EXIT=1; }
+
+ROOT="$(pwd)"
+
+# Need a JSON-aware tool for the structural checks. Prefer python3, fall back to jq.
+JSON_TOOL=""
+if command -v python3 >/dev/null 2>&1; then JSON_TOOL="python3"
+elif command -v jq >/dev/null 2>&1; then JSON_TOOL="jq"; fi
+
+# --- 1. golden-set JSONL validation -----------------------------------------
+JSONL_FILES=()
+while IFS= read -r -d '' f; do
+  JSONL_FILES+=("$f")
+done < <(
+  find "$ROOT" \
+    \( -path '*/node_modules/*' -o -path '*/.git/*' -o -path '*/vendor/*' \
+       -o -path '*/.venv/*' -o -path '*/dist/*' \) -prune -o \
+    -type f -name '*.jsonl' -print0 2>/dev/null
+)
+
+if [ "${#JSONL_FILES[@]}" -eq 0 ]; then
+  skip "no *.jsonl golden sets found under $ROOT — nothing to validate"
+elif [ -z "$JSON_TOOL" ]; then
+  skip "neither python3 nor jq found — cannot validate JSONL, skipping"
+else
+  for f in "${JSONL_FILES[@]}"; do
+    if [ "$JSON_TOOL" = "python3" ]; then
+      msg="$(python3 - "$f" <<'PY'
+import json, sys
+path = sys.argv[1]
+req = {"id", "input", "expected"}
+bad = []
+with open(path, encoding="utf-8") as fh:
+    for n, line in enumerate(fh, 1):
+        s = line.strip()
+        if not s:
+            continue
+        try:
+            obj = json.loads(s)
+        except ValueError as e:
+            bad.append(f"line {n}: invalid JSON ({e})"); continue
+        if not isinstance(obj, dict):
+            bad.append(f"line {n}: not a JSON object"); continue
+        missing = req - obj.keys()
+        if missing:
+            bad.append(f"line {n}: missing keys {sorted(missing)}")
+print("\n".join(bad), end="")
+PY
+)" || msg="parser crashed on $f"
+      if [ -n "$msg" ]; then
+        err "$f:"; printf '  %s\n' "$msg"
+      else
+        ok "$f valid (id/input/expected present on every line)"
+      fi
+    else
+      # jq path: each line must be an object with the three keys.
+      if jq -e 'has("id") and has("input") and has("expected")' "$f" >/dev/null 2>&1; then
+        ok "$f valid (jq: required keys present)"
+      else
+        err "$f: a line is not an object or is missing id/input/expected (jq)"
+      fi
+    fi
+  done
+fi
+
+# --- 2. eval-report.json shape ------------------------------------------------
+REPORTS=()
+while IFS= read -r -d '' f; do
+  REPORTS+=("$f")
+done < <(
+  find "$ROOT" \
+    \( -path '*/node_modules/*' -o -path '*/.git/*' -o -path '*/.venv/*' \) -prune -o \
+    -type f -name 'eval-report.json' -print0 2>/dev/null
+)
+
+if [ "${#REPORTS[@]}" -eq 0 ]; then
+  skip "no eval-report.json found — gate output not validated"
+elif [ -z "$JSON_TOOL" ]; then
+  skip "no python3/jq — cannot validate eval-report.json shape"
+else
+  for f in "${REPORTS[@]}"; do
+    if [ "$JSON_TOOL" = "python3" ]; then
+      if python3 - "$f" <<'PY'
+import json, sys
+try:
+    r = json.load(open(sys.argv[1], encoding="utf-8"))
+except ValueError as e:
+    print(e); sys.exit(1)
+ok = isinstance(r, dict) and isinstance(r.get("passed"), bool) \
+     and isinstance(r.get("metrics"), dict)
+sys.exit(0 if ok else 1)
+PY
+      then ok "$f shape ok (passed: bool, metrics: object)"
+      else err "$f: malformed or missing 'passed'(bool)/'metrics'(object)"; fi
+    else
+      if jq -e 'type=="object" and (.passed|type=="boolean") and (.metrics|type=="object")' "$f" >/dev/null 2>&1; then
+        ok "$f shape ok (jq)"
+      else err "$f: malformed or missing passed/metrics (jq)"; fi
+    fi
+  done
+fi
+
+# --- 3. optional lint (advisory only) ----------------------------------------
+PY_FILES=()
+while IFS= read -r -d '' f; do
+  PY_FILES+=("$f")
+done < <(
+  find "$ROOT" \
+    \( -path '*/node_modules/*' -o -path '*/.git/*' -o -path '*/.venv/*' \) -prune -o \
+    -type f -name '*.py' -print0 2>/dev/null
+)
+
+if [ "${#PY_FILES[@]}" -gt 0 ]; then
+  if command -v ruff >/dev/null 2>&1; then
+    if ruff check "${PY_FILES[@]}" >/dev/null 2>&1; then ok "ruff clean"; else note "ruff reported lint findings (advisory)"; fi
+  else skip "ruff not installed — skipping Python lint"; fi
+  if command -v mypy >/dev/null 2>&1; then
+    mypy "${PY_FILES[@]}" >/dev/null 2>&1 && ok "mypy clean" || note "mypy reported type findings (advisory)"
+  else skip "mypy not installed — skipping type check"; fi
+else
+  skip "no *.py files — skipping ruff/mypy"
+fi
+
+MD_FILES=()
+while IFS= read -r -d '' f; do
+  MD_FILES+=("$f")
+done < <(
+  find "$ROOT" \
+    \( -path '*/node_modules/*' -o -path '*/.git/*' \) -prune -o \
+    -type f -name '*.md' -print0 2>/dev/null
+)
+if [ "${#MD_FILES[@]}" -gt 0 ] && command -v markdownlint >/dev/null 2>&1; then
+  markdownlint "${MD_FILES[@]}" >/dev/null 2>&1 && ok "markdownlint clean" || note "markdownlint findings (advisory)"
+else
+  skip "markdownlint not installed or no docs — skipping doc lint"
+fi
+
+printf '\n'
+if [ "$EXIT" -eq 0 ]; then ok "verify.sh passed"; else err "verify.sh found failures"; fi
+exit "$EXIT"

package/skills/agent-safety/SKILL.md

@@ -0,0 +1,176 @@
+---
+name: agent-safety
+description: "Use when putting guardrails on an LLM agent that already runs — limiting its task scope, gating its tools to least privilege, defending against prompt injection from untrusted content (web pages, emails, RAG docs), requiring human approval on irreversible actions, capping runtime, or after an agent did something it should not have. Triggers: 'lock down the MCP tools', 'the agent deleted prod', 'an email told it to wire money and it did', 'our support agent can run any shell command', 'the agent keeps repeating a wrong instruction across sessions', 'review what this autonomous agent is allowed to do before we ship', 'posa límits a l'agent', 'l'agent ha fet una cosa que no tocava'. NOT building the agent loop, tools, or RAG (that is building-agents)."
+tags: [agent-security, guardrails, prompt-injection, least-privilege, owasp-agentic]
+recommends: [building-agents, secure-coding, agent-eval]
+origin: risco
+---
+
+# Agent safety
+
+You are the security review for an agent's **agency**, not for its code. The loop works,
+tools are wired, memory persists — your job is to make that autonomy *bounded*. If you
+want to review ordinary endpoints, auth, or secrets handling, that is
+`../secure-coding/SKILL.md`. If the loop or tools do not exist yet, that is
+`../building-agents/SKILL.md`. You arrive *after* both.
+
+## The ownership split
+
+Agent security splits into four layers — **Model · Harness · Tools · Environment**. The
+model provider owns only the Model layer (alignment, refusals). Everything else is yours:
+the Harness (loop, memory, context assembly), the Tools (what the agent can *do*), and the
+Environment (creds, network, blast radius). Do not outsource a layer you own to "the model
+is aligned."
+
+Three excesses cause almost every agentic incident. Cut all three:
+
+- **Excessive functionality** — tools the task never needs.
+- **Excessive permissions** — broader scopes/creds than the tool needs.
+- **Excessive autonomy** — acting without checking back when it should.
+
+The operating principle is **least agency**: autonomy is earned per task, not defaulted.
+
+## Scope limits
+
+- **Declare the allowed task domain as a hard boundary in the system prompt.** Why: an
+  undeclared scope is an infinite scope; "you are a refund assistant; you do not touch
+  payroll" is a constraint a reviewer can check.
+- **Deny by default — the agent starts with zero tools.** Each tool earns its place by a
+  task justification. Why: an opt-out tool list grows; an opt-in list stays minimal.
+- **Segregate the instruction channel from the data channel.** System/developer prompt =
+  trusted instructions. Everything the agent reads at runtime = data, never instructions.
+  Why: this single boundary is what stops indirect injection (LLM01).
+
+## Tool gating / least agency
+
+Give every tool a profile: **read / write / exec / send**, the exact resources it may
+touch, and an **allowlist** (never a wildcard). Block destructive flags and secret paths
+at the tool boundary, not in the prompt — the prompt is advisory, the boundary is enforced.
+
+```python
+# Bad: one wildcard tool = unbounded blast radius, runs anything the loop emits
+def run_shell(cmd: str) -> str:
+    return subprocess.run(cmd, shell=True, capture_output=True, text=True).stdout
+```
+
+```python
+# Good: narrow tool, allowlisted root, denied patterns, no shell
+ALLOWED_ROOT = pathlib.Path("/srv/agent/workspace").resolve()
+DENY = ("*.key", "*.pem", "*secret*", "*.env", "id_rsa*")
+
+def read_file(path: str) -> str:
+    p = (ALLOWED_ROOT / path).resolve()
+    if not p.is_relative_to(ALLOWED_ROOT):           # no traversal out of scope
+        raise PermissionError("path outside workspace")
+    if any(p.match(g) for g in DENY):                # never read secrets
+        raise PermissionError("denied pattern")
+    return p.read_text()
+```
+
+- **Issue task-scoped, short-lived tokens — not the session's broad creds.** A credential
+  should be valid only for the specific tool and the duration of one task. Why: a hijacked
+  loop cannot reuse a session-wide token it never held.
+- **Prefer read-only by default; writes/sends/exec are separate, gated tools.** Why: most
+  steps only need to read, so most steps should be unable to mutate anything.
+
+## Injection defense
+
+Treat **all** external data as untrusted: user messages, retrieved documents, API
+responses, emails, web pages, other agents' output. Sanitize and delimit before it enters
+context, and **never let external text reach a privileged tool unmediated.**
+
+| Source                         | Trust level | Required mediation before it can act        |
+| ------------------------------ | ----------- | ------------------------------------------- |
+| System / developer prompt      | Trusted     | none (this is the only instruction channel) |
+| End-user chat message          | Untrusted   | delimit; treat as data, not commands        |
+| Retrieved RAG / KB document    | Untrusted   | delimit; strip instruction-like spans       |
+| Fetched web page / API JSON    | Untrusted   | parse to schema; no raw text → tool args    |
+| Inbound email / ticket body    | Untrusted   | delimit; HITL on any action it requests     |
+| Another agent's message        | Untrusted   | same as external user input                 |
+
+```python
+# Bad: retrieved chunk flows straight into a privileged action
+chunk = retriever.search(q)[0].text          # attacker-controlled doc
+agent.call_tool("send_email", to=extract_to(chunk), body=chunk)
+```
+
+```python
+# Good: external content is quarantined data; the action is schema-validated + gated
+chunk = retriever.search(q)[0].text
+ctx = f"<retrieved untrusted>\n{chunk}\n</retrieved untrusted>"   # delimited, labeled
+proposal = agent.draft("send_email", context=ctx)                # model proposes
+args = SendEmail.model_validate(proposal.args)                   # schema or reject
+if args.to_domain not in ALLOWED_DOMAINS:                        # exfil guard
+    raise PermissionError("recipient outside allowlist")
+require_human_approval("send_email", args)                       # irreversible → HITL
+```
+
+- **Validate every tool-call argument against a strict schema before execution.** Why: a
+  schema rejects the surprise field, encoded payload, or off-allowlist recipient injection
+  produces.
+- **Watch for exfiltration shapes** — unexpected outbound URLs, base64 blobs, recipients
+  outside the allowlist. Why: data theft is the common payload of a successful injection.
+
+## Human-in-the-loop by risk class
+
+Do **not** approve every action — reported ~93% of permission prompts get approved without
+being read, so blanket prompting trains a rubber stamp. Gate by **risk class**, keyed on
+reversibility × blast radius. Bind each approval to the **exact parameters** with a
+short-lived token so the approved action cannot be swapped after the click.
+
+| Action type (examples)                          | Reversible? | Blast radius | Control            |
+| ----------------------------------------------- | ----------- | ------------ | ------------------ |
+| Read file, search KB, fetch page                | n/a         | none         | **auto**           |
+| Write to scratch workspace, internal draft      | yes         | local        | **log-only**       |
+| Mutate prod DB, deploy, change config            | hard        | system       | **approve (HITL)** |
+| Send email/payment to external party, post live | no          | external     | **approve (HITL)** |
+| Delete backups, rotate prod creds, mass-delete  | no          | catastrophic | **block** (or step-up auth) |
+
+- **Step up for the top row** — high-value irreversible actions deserve fresh auth, not the
+  ambient session. Why: a hijacked session should not also hold the keys to the worst action.
+
+## Memory hygiene
+
+- **Validate and sanitize content before it is stored.** Why: memory poisoning persists
+  across sessions (OWASP Agentic T1) — unlike session-scoped injection, a poisoned memory
+  re-attacks every future run until purged.
+- **Isolate memory per user and per session; do not let one user's writes color another's
+  reads.** Why: shared memory is a cross-tenant injection channel.
+- **Expire entries and cap memory size; redact PII (SSN, cards, API keys) before persist.**
+  Why: stale instructions and leaked secrets both age into liabilities.
+
+## Runtime kill-switches
+
+A looping or hijacked agent must hit a wall on its own. Set hard caps, fail closed:
+
+- **Tool-call rate cap** (e.g. ~30 calls/min) — runaway loops trip it before they do damage.
+- **Cost cap per session** (e.g. ~$10) — a wallet attack stops at a known ceiling.
+- **Loop / step cap** — a fixed max iterations kills the infinite plan.
+- **Wall-clock timeout** — a stuck agent is terminated, not left running.
+
+Log every tool call (arguments redacted) and alert on repeated approval-bypass attempts.
+
+## Anti-patterns
+
+| Anti-pattern                                   | Why it bites                                                   | Do instead                                          |
+| ---------------------------------------------- | ------------------------------------------------------------- | --------------------------------------------------- |
+| Approve every action                           | ~93% rubber-stamped; the real risky one slips through         | Gate by risk class; HITL only on irreversible/external |
+| One broad session token shared by all tools    | Hijacked loop reuses it everywhere                            | Task-scoped, short-lived per-tool tokens            |
+| Trust RAG / fetched / email content            | Indirect injection (LLM01) becomes direct tool execution      | Delimit as untrusted data; mediate before any tool  |
+| Wildcard `run_shell(cmd)` tool                 | Unbounded blast radius                                        | Narrow tools, allowlisted resources, denied patterns |
+| Raw external text piped into tool args         | Attacker controls the action's parameters                     | Schema-validate args; allowlist recipients/domains  |
+| Scope/limits stated only in the prompt         | Prompt is advisory; the model can be talked out of it         | Enforce at the tool/harness boundary                |
+| No loop / cost / rate cap                       | A hijacked or looping agent runs until it runs out of money   | Hard fail-closed kill-switches                      |
+| Redact PII only in the UI                       | The secret was already written to memory/logs                 | Redact before persistence, at the source            |
+
+## References
+
+- `references/threat-model.md` — OWASP Agentic Top 10 2026 risks mapped to the controls
+  above, a pre-ship guardrail checklist, and an incident-triage flow for "the agent did X".
+
+## Related
+
+- `../building-agents/SKILL.md` — builds the loop, tools, RAG, MCP server. Hand off here once
+  it exists; it recommends secure-coding, agent-safety is the deeper guardrail layer.
+- `../secure-coding/SKILL.md` — STRIDE/OWASP for ordinary code and web endpoints. agent-safety
+  is the *Agentic* Top 10: risks that exist only because a model has tools and autonomy.

package/skills/agent-safety/evals/README.md

@@ -0,0 +1,12 @@
+# Evals: agent-safety
+
+These cases are the trigger contract and capability rubric for the `agent-safety` skill.
+`should_trigger` and `should_not_trigger` assert that the description routes correctly —
+each negative names the real sibling it should route to instead (building-agents,
+secure-coding, agent-eval, prompt-engineering, cost-tracking). Run them through the repo's
+eval harness if one is wired up, or read them directly as the routing spec when reviewing
+the description. The `capability` block is not a pass/fail script: it is a rubric a human or
+an LLM-as-judge scores a sample guardrail design against — the design must cover every
+`must_include` item (deny-by-default tools, untrusted-content mediation, HITL on
+irreversible actions, memory hygiene, runtime caps) and map them to the OWASP Agentic Top
+10. This is a process/review skill, so there is no `verify.sh`; rigor lives in this eval.

package/skills/agent-safety/evals/cases.yaml

@@ -0,0 +1,46 @@
+skill: agent-safety
+
+should_trigger:
+  - prompt: "Our support agent can call any shell command — lock it down."
+    why: Wildcard exec tool with unbounded blast radius; core tool-gating / least-agency case.
+  - prompt: "An email in the inbox told the agent to forward all invoices to an external address and it did."
+    why: Indirect prompt injection (LLM01). Non-obvious — reads like a bug report, but the cause is untrusted email content reaching a privileged send tool.
+  - prompt: "Before we ship this autonomous agent to prod, review what it's allowed to do."
+    why: Pre-ship review of scope, permissions, and HITL — exactly the bounded-autonomy review this skill is.
+  - prompt: "Posa límits a l'agent perquè no pugui esborrar res sense aprovació."
+    why: Catalan. HITL-by-risk-class on an irreversible delete plus scope limiting.
+  - prompt: "The agent's memory keeps repeating a wrong instruction across sessions."
+    why: Memory poisoning (OWASP Agentic T1). Non-obvious — sounds like a quality bug, is actually contaminated persistent memory.
+  - prompt: "Review our MCP server's tool registry — the scopes look way too broad."
+    why: Over-broad tool scopes / excessive permissions; deny-by-default and per-tool allowlists.
+
+should_not_trigger:
+  - prompt: "Help me build the agent's tool-calling loop."
+    route_to: building-agents
+    why: Construction of the agent (loop/tools), not constraining one that already runs.
+  - prompt: "Is this Express auth endpoint vulnerable to broken access control?"
+    route_to: secure-coding
+    why: Plain web/app OWASP on an endpoint; no model, tools, or autonomy involved.
+  - prompt: "Measure whether my agent answers correctly with a golden set."
+    route_to: agent-eval
+    why: Quality / correctness scoring, not safety constraint.
+  - prompt: "Write a sharper system prompt so the agent is more helpful."
+    route_to: prompt-engineering
+    why: Capability tuning, not a safety boundary.
+  - prompt: "Show me how much each model call costs this month."
+    route_to: cost-tracking
+    why: Reporting spend; agent-safety sets the cost *cap*, it does not report the analytics.
+
+capability:
+  - scenario: >
+      A research agent has web-fetch, send-email, and file-write tools plus persistent
+      memory shared across sessions. Design the guardrails that make its autonomy bounded.
+    must_include:
+      - Deny-by-default tools with a per-tool profile (read web vs send email vs write file); no wildcard tool.
+      - Treats web-fetched content as untrusted; delimits it as data; never pipes external text straight into send-email args.
+      - HITL approval for send-email bound to exact parameters (irreversible, external blast radius); recipient/domain allowlist as exfil guard.
+      - File-write scoped to an allowlisted workspace root; blocks secret patterns (*.key/*.env/*secret*) and path traversal.
+      - Memory validated before store, isolated per session, expiring, PII-redacted before persist.
+      - Runtime kill-switches: tool-call rate cap, per-session cost cap, loop/step cap, wall-clock timeout, all failing closed.
+      - Task-scoped short-lived tokens rather than one broad session credential.
+      - Maps each control to OWASP Agentic Top 10 (indirect injection / tool misuse / memory poisoning / excessive agency).

package/skills/agent-safety/references/threat-model.md

@@ -0,0 +1,51 @@
+# Threat model: OWASP Agentic Top 10 (2026) → controls
+
+Mapping of the named agentic risks to the control in `../SKILL.md` that mitigates each.
+Sources: OWASP Gen AI Security Project, "OWASP Top 10 for Agentic Applications for 2026"
+(genai.owasp.org); OWASP Top 10 for LLM Applications v2025; OWASP AI Agent Security Cheat
+Sheet (cheatsheetseries.owasp.org). All accessed 2026-06-02.
+
+| Agentic risk                       | What it is                                                              | Control in this skill                                   |
+| ---------------------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------- |
+| Memory poisoning (T1)              | Contamination persists across sessions, re-attacking every future run   | Memory hygiene: validate before store, isolate, expire  |
+| Tool misuse & exploitation         | Abuse via unsafe composition / recursion / excessive calls *with* valid perms | Tool gating + runtime kill-switches (rate/loop caps)    |
+| Privilege compromise               | Broad or stolen creds let the loop act beyond its task                  | Task-scoped short-lived tokens; least agency            |
+| Indirect prompt injection (LLM01)  | Untrusted content carries instructions the model executes               | Trust-boundary table; segregate data from instructions  |
+| Excessive agency                   | Acting without check-back on irreversible/external actions              | HITL by risk class; deny-by-default scope               |
+| Data exfiltration                  | Stolen data leaves via tool output / outbound calls                     | Output schema validation; exfil-shape detection         |
+
+The OWASP framing of root causes — excessive **functionality**, **permissions**,
+**autonomy** — maps one-to-one onto the three excesses in the SKILL body. Cutting all three
+is the deny-by-default + least-agency posture.
+
+## Pre-ship guardrail checklist
+
+Before an autonomous loop reaches production, confirm:
+
+- [ ] Allowed task domain is declared in the system prompt as a hard boundary.
+- [ ] Tools are deny-by-default; each enabled tool has a written task justification.
+- [ ] Every tool has a profile (read / write / exec / send) and an allowlist, not a wildcard.
+- [ ] No tool can read `*.key` / `*.pem` / `*secret*` / `*.env` or run with destructive flags.
+- [ ] Creds are task-scoped and short-lived, not one broad session token.
+- [ ] All external content (web, email, RAG, API, other agents) is delimited as untrusted.
+- [ ] Tool-call args are schema-validated; recipients/domains are allowlisted (exfil guard).
+- [ ] HITL is gated by risk class; irreversible/external actions require approval bound to exact params.
+- [ ] Memory is validated before store, isolated per user/session, expiring, PII-redacted.
+- [ ] Runtime caps exist and fail closed: rate, cost, loop/step, wall-clock timeout.
+- [ ] Every tool call is logged (redacted); repeated approval-bypass alerts.
+
+## Incident triage: "the agent did X"
+
+When an agent has already done something it should not have, work the loop in order:
+
+1. **Contain.** Revoke the task tokens / creds the loop is holding; trip the kill-switch
+   (pause the loop). Stop the bleeding before diagnosing.
+2. **Find the trust boundary it crossed.** Which untrusted source reached a privileged
+   tool? Trace the action's parameters back to their origin — usually an email body, RAG
+   chunk, fetched page, or a poisoned memory entry.
+3. **Purge poisoned memory.** If the bad behavior repeats across sessions, the cause is
+   stored, not in-context. Delete the contaminated entries; do not just restart the session.
+4. **Add the missing gate.** Reclassify that action's risk, move it behind HITL or block,
+   tighten the tool allowlist, or add the schema/exfil check that would have caught it.
+5. **Confirm with a replay.** Re-run the triggering input against the new guardrail and
+   verify the action is now refused or escalated.

package/skills/ai-media/SKILL.md

@@ -0,0 +1,196 @@
+---
+name: ai-media
+description: "Use when turning a creative goal into a finished media file by orchestrating multiple generative-media models and gluing the pieces with ffmpeg — narrated explainer, product teaser, faceless short, AI voiceover, image-to-video clip, background score, or muxing/ducking/normalizing/stitching existing assets. Triggers: 'make a narrated video with AI voice and B-roll', 'generate a voiceover and mix it over the footage', 'duck the music under the voiceover', 'stitch the scene clips into one MP4 and normalize loudness', 'turn this still into a 9:16 clip with a music bed', 'genérame una voz en off y un vídeo para este guion con música de fondo', 'posa música de fons i abaixa-la quan parla la veu'. NOT still-image generation/editing (that is replicate-images)."
+tags: [ai-media, text-to-speech, image-to-video, voiceover, music-generation, ffmpeg, media-pipeline, elevenlabs]
+recommends: [replicate-images, fal, replicate, remotion-video, video-shorts]
+origin: risco
+---
+
+# ai-media
+
+You are the cross-modal director. You decide **which** generative-media model to call per modality, in **what order**, with **what params**, then **assemble** the pieces with ffmpeg into one finished file. You do not own a single provider's API surface and you do not prompt still images — you orchestrate and glue.
+
+## The one rule
+
+**Plan the whole pipeline before you generate a single asset.** Media generation is slow and metered: a re-roll of a 10 s Veo clip or a 90 s music track costs real money and minutes. Lock the scene list, the aspect ratio, the target loudness, and the model per modality *first*, then generate once. A draft pass at low res/short duration is cheaper than discovering at mux time that your clips are 9:16 and your VO is the wrong sample rate.
+
+## Pipeline shape — decide what the goal needs
+
+Map the goal to modalities and an ordered step list. The "delegate to" column is where the actual call mechanics live — you pick the model and params, those skills run the call.
+
+| Goal | Needs | Ordered steps | Delegate calls to |
+|------|-------|---------------|-------------------|
+| Narrated explainer | stills + img→video + VO + music | script → per-scene stills → clip per scene → VO → music → conform → concat → mix+duck → loudnorm → MP4 | `replicate-images`, `fal`/`replicate` |
+| Product teaser (1 hero) | 1 still + img→video + music | still → clip → music → mix → loudnorm → MP4 | `replicate-images`, `fal`/`replicate` |
+| Faceless short | stills + img→video + VO + music + captions | (explainer pipeline) + burn captions | `replicate-images`, `video-shorts` for the script |
+| Just a voiceover | VO only | script → TTS → loudnorm | — |
+| Just a clip from a still | img→video only | still (input) → clip | `fal`/`replicate` |
+| Code-rendered explainer | none of the above | render from React/TS | **stop — route to `remotion-video`** |
+
+If the video is *rendered from data/code* (charts, timelines, JSON-driven scenes), this is not your job → `../remotion-video/SKILL.md`. You handle *model-generated + ffmpeg-glued*.
+
+## Modality 1 — Voice (TTS)
+
+ElevenLabs Python SDK. The call is `convert(text, voice_id, model_id, output_format)`; auth via `ELEVENLABS_API_KEY`.
+
+```python
+from elevenlabs.client import ElevenLabs
+
+client = ElevenLabs()  # reads ELEVENLABS_API_KEY
+audio = client.text_to_speech.convert(
+    text="Your narration script here.",
+    voice_id="JBFqnCBsd6RMkjVDRZzb",
+    model_id="eleven_multilingual_v2",     # final-quality VO
+    output_format="mp3_44100_128",          # codec_samplerate_bitrate
+)
+with open("vo.mp3", "wb") as f:
+    for chunk in audio:
+        f.write(chunk)
+```
+
+Pick the model tier by what the job needs:
+
+| Model | When | Latency | Cost lever |
+|-------|------|---------|-----------|
+| `eleven_v3` | most expressive, hero final VO — **verify availability first (see caveat)** | higher | most credits/char |
+| `eleven_multilingual_v2` | high-quality multilingual VO (default for finals) | medium | medium |
+| `eleven_flash_v2_5` | real-time / batch / scale / drafts | ~75 ms | cheapest |
+
+**Do not hardcode `eleven_v3` blind.** It shipped to the API in *alpha* (Aug 2025) and the docs model list now carries it, but the `text_to_speech.convert` API reference still documents the default as `eleven_multilingual_v2` and does not enumerate `eleven_v3` as a guaranteed value. Before you build a final pass on it, confirm it returns from `GET /v1/models` for your key (or just call once and check) — otherwise default to `eleven_multilingual_v2`, which is the safe, always-available hero tier.
+
+`output_format` is `codec_samplerate_bitrate` — e.g. `mp3_44100_128`, `mp3_22050_32`. **Match the VO sample rate to your assembly target**, do not master the VO loud and hope.
+
+Bad → Good:
+- **Bad:** generate VO at `mp3_22050_32`, then mux onto a 48 kHz video — ffmpeg silently resamples, you get artifacts and a level mismatch.
+- **Good:** generate VO at the rate you will master at (e.g. `mp3_44100_128`), and set final loudness with `loudnorm` in assembly, not by cranking the TTS.
+
+TTS is billed per character/token (~0.5–1 credit/char on the Flash/Turbo lines). ElevenLabs cut *TTS* API pricing up to 55% on 2026-05-07 (e.g. Flash on Creator $0.11→$0.05 / 1k tokens) — that figure is TTS-specific, not the Music cut. **Pricing staling fast: these are point-in-time numbers from elevenlabs.io/pricing/api as of 2026-06-02 — re-check the page before quoting a budget.** Shorter scripts and Flash on drafts are the cost levers.
+
+## Modality 2 — Image-to-video
+
+**The still is an input, not your output.** Generate or edit the source image in `../replicate-images/SKILL.md`, then animate it here. Reality check: every serious 2026 model does 1080p or native 4K — **resolution is no longer the differentiating axis**. The hard limit is **per-generation duration (~5–15 s, model-dependent)**. Long pieces are **one clip per scene, then concat** — never one long take.
+
+Durations below are from each vendor's own pages (as of 2026-06; see `references/models-and-params.md` for the citations) — they move with releases, so verify on the catalog before a final run:
+
+| Model | Duration | Aspect / max res | Control surface | Native audio | Open-source |
+|-------|----------|------------------|-----------------|--------------|-------------|
+| Google **Veo 3.1** | **8 s** / generation | 16:9 / 9:16, up to 4K | high | **yes** — synced 48 kHz dialogue/SFX | no |
+| **Kling 3.0** | **up to 15 s** | flexible, 4K | strong identity/temporal, lip-sync | no | no |
+| **Runway Gen-4.5** | **2–10 s** | flexible | **best** — motion brushes, camera control, reference image | no | no |
+| **MiniMax Hailuo 02** | **6 s or 10 s** (1080p caps at 6 s) | up to 1080p | medium | no | no |
+| **Wan 2.6** | **up to 15 s** | up to 1080p | first/last-frame control, A/V sync | no (sync) | **yes** (Apache) |
+
+Choose by the binding constraint: need synced dialogue → Veo 3.1; need precise camera/motion control → Runway Gen-4.5; need identity consistency across scenes or the longest single take → Kling 3.0 / Wan 2.6; need open-source/self-host → Wan 2.6; cost-sensitive 1080p → Hailuo 02. Endpoint ids and per-call mechanics live in `../fal/SKILL.md` / `../replicate/SKILL.md` (both rails carry these models). See `references/models-and-params.md` for endpoint ids and current limits.
+
+## Modality 3 — Music / score
+
+Costs are per-minute and plan-dependent — treat them as approximate and **verify on the vendor pricing page** (figures as of 2026-06; sources in `references/models-and-params.md`):
+
+| Model | Cost (approx, verify) | Licensing story | Control |
+|-------|-----------------------|-----------------|---------|
+| **ElevenLabs Music v2** | per-minute, ~$0.15–0.50/min depending on plan (Music API pricing cut up to 50% at v2 launch — separate from the 55% *TTS* cut) | **cleanest** — vendor states trained *only on licensed data, cleared for commercial use* (Believe collaboration named at launch) | genre-switch mid-track |
+| **Suno v5** | plan-based | usage rights on paid plans post Nov-2025 label settlements (rights, not ownership) | vendor blind-test benchmark ELO ~1293 |
+| **Udio** | $30/mo Pro plan (commercial rights); **no official public API** — third-party gateways only | UMG-licensed platform announced for 2026 | — |
+
+**Confirm commercial rights before you ship.** Licensing differs per model and per plan; "I generated it" is not "I may sell the ad with it." For a clean commercial story with an official API, ElevenLabs Music v2 is the safe default — Udio has no first-party API, so do not plan a programmatic pipeline around it. The rest is the same fal/replicate call mechanics.
+
+## Assembly with ffmpeg
+
+Four operations. Each is a copy-paste recipe; full filter graphs and pitfalls are in `references/ffmpeg-assembly.md`.
+
+**(a) Mux VO onto video** — map both streams, copy video, take the shorter duration:
+
+```bash
+ffmpeg -i scene.mp4 -i vo.mp3 \
+  -map 0:v -map 1:a -c:v copy -shortest out.mp4
+```
+
+**(b) Duck music under the VO** — `sidechaincompress` keys the music off the voice so it drops when narration plays (pro DAW ducking, no manual keyframes):
+
+```bash
+ffmpeg -i vo.mp3 -i music.mp3 -filter_complex \
+  "[1:a][0:a]sidechaincompress=threshold=0.03:ratio=8:attack=20:release=300[duck]; \
+   [0:a][duck]amix=inputs=2:duration=longest[aout]" \
+  -map "[aout]" -c:a aac mix.m4a
+```
+
+Cheaper static fallback when sidechain is overkill — fix the music low under a full VO:
+
+```bash
+ffmpeg -i vo.mp3 -i music.mp3 -filter_complex \
+  "[1:a]volume=0.3[m];[0:a][m]amix=inputs=2:duration=longest[aout]" \
+  -map "[aout]" mix.m4a
+```
+
+**(c) Loudnorm to a target LUFS (two-pass)** — measure, then apply. Target -14 LUFS for social/streaming, -16 for podcast-style VO. Normalize per track *before* mixing.
+
+```bash
+# pass 1: measure (read the JSON it prints)
+ffmpeg -i mix.m4a -af loudnorm=I=-14:TP=-1.5:LRA=11:print_format=json -f null -
+# pass 2: apply with the measured values
+ffmpeg -i mix.m4a -af \
+  loudnorm=I=-14:TP=-1.5:LRA=11:measured_I=-20.1:measured_TP=-4.2:measured_LRA=6.0:measured_thresh=-30.8:offset=0.5:linear=true \
+  master.m4a
+```
+
+**(d) Concat scenes — conform first.** Same-codec/res/fps clips → fast demuxer with `-c copy`. Mismatched clips → re-encode and scale first, then concat. **Never `-c copy`-concat mismatched clips** — you get desync or a corrupt stream.
+
+```bash
+# all clips identical codec/res/fps:
+printf "file '%s'\n" scene1.mp4 scene2.mp4 scene3.mp4 > list.txt
+ffmpeg -f concat -safe 0 -i list.txt -c copy joined.mp4
+
+# mismatched: conform each, then concat filter
+ffmpeg -i s1.mp4 -i s2.mp4 -filter_complex \
+  "[0:v]scale=1920:1080,fps=30,setsar=1[v0];[1:v]scale=1920:1080,fps=30,setsar=1[v1]; \
+   [v0][1:a?][v1][1:a?]concat=n=2:v=1:a=0[v]" -map "[v]" joined.mp4
+```
+
+## End-to-end worked pipeline (narrated explainer)
+
+Ordered command list — generate once, assemble deterministically:
+
+1. **Lock the plan** — scene list, aspect (e.g. 16:9 1080p 30fps), target -14 LUFS, models chosen.
+2. **Stills per scene** → `../replicate-images/SKILL.md` (one prompt per scene).
+3. **Clip per scene** (img→video, ~5–15 s each, model cap) via your chosen model on `fal`/`replicate`.
+4. **VO** → ElevenLabs `convert(...)` at the master sample rate.
+5. **Music** → ElevenLabs Music v2, length = total runtime, confirm rights.
+6. **Conform** every clip to 1920x1080/30fps/SAR 1.
+7. **Concat** the conformed clips → `body.mp4`.
+8. **Loudnorm** VO and music tracks (two-pass) to consistent levels.
+9. **Mix + duck** music under VO → `mix.m4a`.
+10. **Final loudnorm** the mix to -14 LUFS → `master.m4a`.
+11. **Mux** `master.m4a` onto `body.mp4` with `-shortest` → `final.mp4`.
+
+Emit this as a runnable script. `scripts/verify.sh` lints it (loudnorm present, conform-before-concat, final MP4 target).
+
+## Cost & regen discipline
+
+- **Draft small, then final.** Generate clips short/low-res and VO on Flash to lock timing and the cut; only the final pass spends on hero quality. Re-rolling locked scenes is the biggest waste.
+- **Per-modality levers:** shorter scripts (TTS per-char), fewer scene re-rolls (img→video), fewer music minutes (music is billed per minute — verify the current rate on the vendor pricing page).
+- Spend tracking *as a discipline* → `../fal/SKILL.md` / `../replicate/SKILL.md` for per-call cost; treat budget as a constraint you set before generating.
+
+## Anti-patterns
+
+| Anti-pattern | Why it bites | Do instead |
+|--------------|--------------|------------|
+| Generating assets before locking the pipeline | aspect/sample-rate/duration mismatches surface at mux time, forcing paid re-rolls | lock scene list, aspect, LUFS, models first |
+| One long video-gen call for the whole piece | models cap at ~5–15 s; you fight the limit and waste rolls | one clip per scene, then concat |
+| Mixing tracks without per-track `loudnorm` | VO buried or blasting over music; inconsistent levels | two-pass loudnorm each track before mix |
+| `-c copy`-concat of mismatched clips | desync, corrupt stream, wrong frame timing | conform res/fps/SAR, then concat |
+| Music low set by ear / static only when VO needs space | narration gets masked under the bed | `sidechaincompress` keyed off the VO |
+| Shipping generated music without checking rights | "generated" ≠ "licensed to sell" — legal exposure | confirm commercial rights per model/plan |
+| Prompting/editing the still inside this skill | duplicates `replicate-images`' job, worse prompts | delegate the still, consume it here |
+| Mastering loudness by cranking the TTS | clipping, no true-peak control | set level with `loudnorm`, not the generator |
+
+## Hand-offs
+
+- Still-image generation/editing (the source frames) → `../replicate-images/SKILL.md`
+- The per-provider call mechanics (queue, webhook, FileOutput, cost) → `../fal/SKILL.md`, `../replicate/SKILL.md`
+- Code-rendered, frame-exact compositing in React/TS → `../remotion-video/SKILL.md`
+- Writing the short's script + cut direction → `../video-shorts/SKILL.md`
+
+## References
+
+- `references/models-and-params.md` — current per-modality model map (TTS tiers + output_format codes + per-char cost; img→video duration/aspect/fps/control/native-audio/open-source + fal & replicate endpoint ids; music cost/licensing/duration).
+- `references/ffmpeg-assembly.md` — full ffmpeg cookbook: mux, two-pass loudnorm, sidechaincompress with worked filter graphs, amix fallback, concat demuxer vs filter, conforming res/fps/SAR, burning captions, pitfalls.