arkaos 5.17.0 → 5.17.1

package/README.md

@@ -4,7 +4,7 @@
 
 **The Operating System for AI Agent Teams.**
 
-89 agents. 17 departments. 340 skills. Enterprise frameworks. Multi-runtime. One install.
+89 agents. 17 departments. 341 skills. Enterprise frameworks. Multi-runtime. One install.
 
 ```bash
 npx arkaos install
@@ -97,7 +97,7 @@ npx arkaos doctor    # Health check
 
 ### Skill packs, à la carte
 
-The default install ships a curated core so your context window stays lean. Everything else lives in the ArkaOS plugin marketplace: 16 department packs with 266 skills, generated straight from the same sources the core uses. Inside Claude Code:
+The default install ships a curated core so your context window stays lean. Everything else lives in the ArkaOS plugin marketplace: 16 department packs with 267 skills, generated straight from the same sources the core uses. Inside Claude Code:
 
 ```
 /plugin marketplace add andreagroferreira/arka-os

package/THE-ARKAOS-GUIDE.md

@@ -1,6 +1,6 @@
 # The ArkaOS Guide
 
-> v5.16.1 — 89 agents, 17 departments, 340 skills, 306 commands, 20 ADRs.
+> v5.17.1 — 89 agents, 17 departments, 341 skills, 307 commands, 20 ADRs.
 > One file, everything you need to start. Generated by `scripts/guide_gen.py` — never hand-edited.
 
 ## What it is
@@ -40,7 +40,7 @@ answers as a generic assistant.
 | `/arka` | 22 |
 | `/brand` | 14 |
 | `/community` | 15 |
-| `/content` | 20 |
+| `/content` | 21 |
 | `/dev` | 42 |
 | `/do` | 1 |
 | `/ecom` | 18 |

package/VERSION

@@ -1 +1 @@
-5.17.0
+5.17.1

package/arka/SKILL.md

@@ -63,7 +63,7 @@ complementary, not alternatives.
 # ArkaOS — Main Orchestrator
 
 > **The Operating System for AI Agent Teams**
-> 89 agents. 17 departments. 340 skills. Multi-runtime. Dashboard. Knowledge RAG.
+> 89 agents. 17 departments. 341 skills. Multi-runtime. Dashboard. Knowledge RAG.
 
 ## ⛔ Evidence flow — 4 gates (NON-NEGOTIABLE)
 

package/bin/arka-doctor

@@ -370,17 +370,23 @@ run_check "plugins" "warn" "$PLUGINS_DESC" "$PLUGINS_OK" "Run: bash install.sh"
 
 # ─── Check 17: Hyperframes Skills (video production) ──────────────────────
 # Parity with installer/doctor.js `hyperframes-skills` (PR-C2): same name,
-# same sentinel, warn-only — video production is opt-in.
+# same sentinels, same two roots (~/.claude/skills and ~/.agents/skills),
+# warn-only — video production is opt-in.
 HF_OK=false
 HF_DESC="Hyperframes skills AUSENTE (video-as-code editing for /content video)"
-for hf_name in hyperframes hyperframes-core; do
-  if [ -f "$HOME/.claude/skills/$hf_name/SKILL.md" ]; then
-    HF_OK=true
-    HF_DESC="Hyperframes skills installed ($hf_name)"
-    break
-  fi
+for hf_root in "$HOME/.claude/skills" "$HOME/.agents/skills"; do
+  for hf_name in hyperframes hyperframes-core; do
+    if [ -f "$hf_root/$hf_name/SKILL.md" ]; then
+      HF_OK=true
+      # Static, matching installer/doctor.js `description` exactly: run_check
+      # splices $desc unescaped into the --json payload, so no path or
+      # name interpolation may reach it.
+      HF_DESC="Hyperframes skills installed (video-as-code editing for /content video)"
+      break 2
+    fi
+  done
 done
-run_check "hyperframes-skills" "warn" "$HF_DESC" "$HF_OK" "Run /content video-setup in Claude Code"
+run_check "hyperframes-skills" "warn" "$HF_DESC" "$HF_OK" "Run /content video-setup in Claude Code, or: npx hyperframes skills update (core set; npx hyperframes skills check reports staleness)"
 
 # ─── Check 18: SQLite corrupt-store backups (self-heal F1-D1) ──────────────
 # Parity with installer/doctor.js `sqlite-corrupt-backups`: same name,

package/core/hooks/session_start.py

@@ -318,31 +318,6 @@ def _trigger_reorganizer(repo: str, config: dict) -> None:
     _spawn_detached([sys.executable, "-m", "core.cognition.reorganizer_cli"], repo)
 
 
-def _trigger_auto_doc_drain(repo: str, config: dict) -> None:
-    """Queue-aware AND config-gated: ``cognition.auto_doc_drain_on_session``
-    (default True). The Stop hook enqueues auto-doc jobs; sessions drain
-    them — the consumer follows the producer's cadence, so a machine with
-    no sessions never wakes a worker for nothing (knowledge-flow PR1)."""
-    cognition = config.get("cognition") or {}
-    if not cognition.get("auto_doc_drain_on_session", True):
-        return
-    if not repo:
-        return
-    try:
-        from core.jobs.auto_doc_worker import _queue_root
-        if not any((_queue_root() / "pending").glob("*.json")):
-            return
-    except Exception:
-        return
-    max_age = cognition.get("auto_doc_max_age_days", 14)
-    _spawn_detached(
-        [sys.executable, "-m", "core.jobs.auto_doc_worker", "--once",
-         "--max-jobs", "10", "--max-age-days", str(max_age)],
-        repo,
-        log_path=Path.home() / ".arkaos" / "logs" / "auto-doc-drain.log",
-    )
-
-
 def _ensure_dashboard(repo: str, config: dict) -> None:
     dashboard = config.get("dashboard") or {}
     if not dashboard.get("ensure_on_session", True):
@@ -409,7 +384,6 @@ def build_visible(cwd: str) -> str:
     msg += _forge_line()
     msg += _drift(version)
     _trigger_reorganizer(repo, config)
-    _trigger_auto_doc_drain(repo, config)
     _ensure_dashboard(repo, config)
     return msg
 

package/core/jobs/auto_doc_worker.py

@@ -6,8 +6,6 @@ Queue layout under `~/.arkaos/jobs/auto-doc/`:
     processing/  — jobs currently being handled
     completed/   — jobs finished successfully
     failed/      — jobs that exhausted retries or could not be parsed
-    expired/     — jobs older than --max-age-days, moved aside unprocessed
-                   (never deleted: the operator can audit or re-queue them)
 
 Each job is a JSON file:
 
@@ -28,31 +26,22 @@ second worker that tries to claim the same job will raise and skip it.
 from __future__ import annotations
 
 import argparse
-import contextlib
 import json
 import os
 import sys
 import time
 import uuid
-from datetime import UTC, datetime
+from datetime import datetime, timezone
 from pathlib import Path
+from typing import Optional
 
-from core.knowledge.vault import resolve_vault_path
 from core.shared import safe_session_id as _safe_session_id_module
 
+
 MAX_ATTEMPTS = 3
 # Re-export for backward compatibility with any external importers.
 SAFE_SESSION_ID_RE = _safe_session_id_module.SAFE_SESSION_ID_RE
-_QUEUE_SUBDIRS = ("pending", "processing", "completed", "failed", "expired")
-
-_VAULT_REMEDIATION = (
-    "No vault configured. Set `knowledge.vaultPath` in ~/.arkaos/config.json "
-    "(or export ARKAOS_VAULT). Jobs were left untouched in pending/."
-)
-
-
-class VaultNotConfiguredError(RuntimeError):
-    """No vault answered; pending jobs must not be claimed or retried."""
+_QUEUE_SUBDIRS = ("pending", "processing", "completed", "failed")
 
 
 def _queue_root() -> Path:
@@ -62,17 +51,11 @@ def _queue_root() -> Path:
     return Path.home() / ".arkaos" / "jobs" / "auto-doc"
 
 
-def _vault_path() -> Path | None:
-    """The operator's vault via the canonical resolver, or ``None``.
-
-    Resolution order is the canonical one from ``core.knowledge.vault``:
-    ``knowledge.vaultPath`` in ``~/.arkaos/config.json`` first, then the
-    ``ARKAOS_VAULT`` env var, both required to exist on disk. This
-    replaces a hardcoded ``~/Documents/Personal`` fallback that silently
-    sent every note to one developer's personal layout (the exact defect
-    ``core.knowledge.vault`` was written to end — the worker predates it).
-    """
-    return resolve_vault_path()
+def _vault_path() -> Path:
+    override = os.environ.get("ARKAOS_VAULT", "").strip()
+    if override:
+        return Path(override)
+    return Path.home() / "Documents" / "Personal"
 
 
 def _ensure_queue(root: Path) -> None:
@@ -81,7 +64,7 @@ def _ensure_queue(root: Path) -> None:
 
 
 def _now_iso() -> str:
-    return datetime.now(UTC).isoformat()
+    return datetime.now(timezone.utc).isoformat()
 
 
 # ─── Enqueue ───────────────────────────────────────────────────────────
@@ -91,7 +74,7 @@ def enqueue_job(
     session_id: str,
     transcript_path: str,
     qg_verdict: str,
-    queue_root: Path | None = None,
+    queue_root: Optional[Path] = None,
 ) -> str:
     """Write a pending job file. Returns the job id."""
     root = queue_root or _queue_root()
@@ -118,71 +101,22 @@ def enqueue_job(
 
 def process_pending_jobs(
     max_jobs: int = 10,
-    queue_root: Path | None = None,
-    max_age_days: float | None = None,
+    queue_root: Optional[Path] = None,
 ) -> list[dict]:
-    """Process up to `max_jobs` pending jobs. Returns per-job result dicts.
-
-    Raises :class:`VaultNotConfiguredError` BEFORE claiming anything when
-    no vault is configured — a missing vault is an environment failure
-    and must never consume job attempts or move files out of pending/.
-    """
+    """Process up to `max_jobs` pending jobs. Returns per-job result dicts."""
     root = queue_root or _queue_root()
     _ensure_queue(root)
-    vault = _vault_path()
-    if vault is None:
-        raise VaultNotConfiguredError(_VAULT_REMEDIATION)
-    pending = sorted((root / "pending").glob("*.json"))
     results: list[dict] = []
-    if max_age_days is not None:
-        pending, expired = _partition_expired(pending, root, max_age_days)
-        results.extend(expired)
+    pending = sorted((root / "pending").glob("*.json"))
     for job_file in pending[:max_jobs]:
         claimed = _claim(job_file, root)
         if claimed is None:
             continue
-        results.append(run_single_job(claimed, root, vault=vault))
+        results.append(run_single_job(claimed, root))
     return results
 
 
-def _job_timestamp(job_file: Path) -> float | None:
-    prefix = job_file.name.split("-", 1)[0]
-    try:
-        return float(prefix)
-    except ValueError:
-        return None
-
-
-def _partition_expired(
-    pending: list[Path], root: Path, max_age_days: float
-) -> tuple[list[Path], list[dict]]:
-    """Split by job age, read from the unix prefix of the job filename.
-
-    A name without a parsable prefix is kept for processing — unknown
-    age must never silently shelve a job.
-    """
-    cutoff = time.time() - max_age_days * 86400.0
-    keep: list[Path] = []
-    expired: list[dict] = []
-    for job_file in pending:
-        stamp = _job_timestamp(job_file)
-        if stamp is not None and stamp < cutoff:
-            expired.append(_move_to_expired(job_file, root))
-        else:
-            keep.append(job_file)
-    return keep, expired
-
-
-def _move_to_expired(job_file: Path, root: Path) -> dict:
-    target = root / "expired" / job_file.name
-    try:
-        os.replace(job_file, target)
-    except OSError:
-        return {"job_id": job_file.stem, "status": "expire-failed"}
-    return {"job_id": job_file.stem, "status": "expired"}
-
-
-def _claim(job_file: Path, root: Path) -> Path | None:
+def _claim(job_file: Path, root: Path) -> Optional[Path]:
     target = root / "processing" / job_file.name
     try:
         os.replace(job_file, target)
@@ -193,17 +127,10 @@ def _claim(job_file: Path, root: Path) -> Path | None:
         return None
 
 
-def run_single_job(
-    job_path: Path,
-    queue_root: Path | None = None,
-    vault: Path | None = None,
-) -> dict:
+def run_single_job(job_path: Path, queue_root: Optional[Path] = None) -> dict:
     """Process one job end-to-end. Moves to completed/ or failed/."""
     root = queue_root or _queue_root()
     _ensure_queue(root)
-    vault = vault or _vault_path()
-    if vault is None:
-        return _release_claim(job_path, root)
     try:
         payload = json.loads(job_path.read_text(encoding="utf-8"))
         if not isinstance(payload, dict):
@@ -213,26 +140,18 @@ def run_single_job(
     payload["attempts"] = int(payload.get("attempts") or 0) + 1
     job_path.write_text(json.dumps(payload), encoding="utf-8")
     try:
-        written = _execute(payload, vault)
+        written = _execute(payload)
     except Exception as exc:
         return _handle_retry(job_path, payload, root, str(exc))
     return _move_to_completed(job_path, root, payload, written)
 
 
-def _release_claim(job_path: Path, root: Path) -> dict:
-    """Vault vanished between pre-flight and execution: put the job back
-    WITHOUT touching attempts — environment failure, not job failure."""
-    target = root / "pending" / job_path.name
-    with contextlib.suppress(OSError):
-        os.replace(job_path, target)
-    return {"job_id": job_path.stem, "status": "vault-unconfigured"}
-
-
-def _execute(payload: dict, vault: Path) -> list[str]:
+def _execute(payload: dict) -> list[str]:
     from core.cognition.auto_documentor import document_session
     transcript = Path(payload.get("transcript_path") or "")
     session_id = str(payload.get("session_id") or "")
     verdict = str(payload.get("qg_verdict") or "")
+    vault = _vault_path()
     paths = document_session(transcript, session_id, vault, verdict)
     return [str(p) for p in paths]
 
@@ -264,8 +183,10 @@ def _move_to_completed(
     payload["status"] = "completed"
     target = root / "completed" / job_path.name
     job_path.write_text(json.dumps(payload), encoding="utf-8")
-    with contextlib.suppress(OSError):
+    try:
         os.replace(job_path, target)
+    except OSError:
+        pass
     return {
         "job_id": payload.get("job_id"),
         "status": "completed",
@@ -279,13 +200,17 @@ def _move_to_failed(job_path: Path, root: Path, error: str) -> dict:
     info["status"] = "failed"
     info["error"] = error
     info["failed_at"] = _now_iso()
-    with contextlib.suppress(OSError):
+    try:
         job_path.write_text(json.dumps(info), encoding="utf-8")
+    except OSError:
+        pass
     try:
         os.replace(job_path, target)
     except OSError:
-        with contextlib.suppress(OSError):
+        try:
             job_path.unlink()
+        except OSError:
+            pass
     return {
         "job_id": info.get("job_id"),
         "status": "failed",
@@ -314,38 +239,20 @@ def _build_parser() -> argparse.ArgumentParser:
                         help="Cap on jobs per pass.")
     parser.add_argument("--interval", type=float, default=5.0,
                         help="Seconds to sleep between passes when daemonised.")
-    parser.add_argument("--max-age-days", type=float, default=None,
-                        help="Move pending jobs older than this to expired/ "
-                             "instead of processing them.")
     return parser
 
 
-def _run_pass(max_jobs: int, max_age_days: float | None) -> int | None:
-    """One drain pass; prints results. Returns an exit code on fatal error."""
-    try:
-        results = process_pending_jobs(
-            max_jobs=max_jobs, max_age_days=max_age_days
-        )
-    except VaultNotConfiguredError as exc:
-        print(str(exc), file=sys.stderr)
-        return 2
+def main(argv: Optional[list[str]] = None) -> int:
+    args = _build_parser().parse_args(argv)
+    results = process_pending_jobs(max_jobs=args.max_jobs)
     for r in results:
         print(json.dumps(r), flush=True)
-    return None
-
-
-def main(argv: list[str] | None = None) -> int:
-    args = _build_parser().parse_args(argv)
-    rc = _run_pass(args.max_jobs, args.max_age_days)
-    if rc is not None:
-        return rc
     if args.once:
         return 0
     while True:
         time.sleep(max(0.1, float(args.interval)))
-        rc = _run_pass(args.max_jobs, args.max_age_days)
-        if rc is not None:
-            return rc
+        for r in process_pending_jobs(max_jobs=args.max_jobs):
+            print(json.dumps(r), flush=True)
 
 
 if __name__ == "__main__":

package/core/synapse/layers.py

@@ -21,6 +21,7 @@ layers_kb.py. Both are re-exported here so existing
 `core.synapse.layers` imports keep working.
 """
 
+import os
 import re
 import time
 from typing import Any
@@ -412,6 +413,24 @@ def _hub_skill(department: str) -> str:
     return _DEPT_HUB_EXCEPTIONS.get(department, f"arka-{department}")
 
 
+# Project-shape signals: a cwd carrying ANY of these file groups (every
+# file in a group present) forces the command's hint regardless of the
+# prompt text — "working inside a Hyperframes project" is a route.
+PROJECT_SIGNALS: dict[str, tuple[tuple[str, ...], ...]] = {
+    "content-hyperframes": (
+        ("hyperframes.json",),
+        ("BRIEF.md", "STORYBOARD.md"),
+    ),
+}
+
+# The score slot exists only so signal entries share the
+# (score, command, department) tuple shape of _score_commands. Nothing
+# sorts on it in the merge path: _hint_tag and compute discard the score,
+# and precedence comes from _merge_hints concatenating signal entries
+# before the keyword ones.
+_SIGNAL_SCORE = 10_000
+
+
 def _hint_department(cmd: dict) -> str:
     """Department for the hint's hub skill.
 
@@ -426,8 +445,63 @@ def _hint_department(cmd: dict) -> str:
     return prefix.split("-")[0]
 
 
+def _group_present(cwd: str, group: tuple[str, ...]) -> bool:
+    """True when EVERY file of the group sits directly in ``cwd``."""
+    return all(os.path.isfile(os.path.join(cwd, name)) for name in group)
+
+
+def _project_signal_ids(cwd: str) -> list[str]:
+    """Registry command ids whose project shape matches the hook cwd.
+
+    Looks at ``cwd`` itself only — no parent walk — and never raises:
+    ``PromptContext.cwd`` is typed ``str``, and for str input the
+    ``os.path`` predicates (``isdir``/``isfile``) are exception-free —
+    they swallow OSError and ValueError internally — so an empty cwd, a
+    directory that does not exist, or an unreadable path yields no signal
+    and L5 degrades to plain keyword scoring. No try/except is needed.
+    """
+    if not cwd or not os.path.isdir(cwd):
+        return []
+    return [
+        cmd_id
+        for cmd_id, groups in PROJECT_SIGNALS.items()
+        if any(_group_present(cwd, group) for group in groups)
+    ]
+
+
+def _signal_commands(
+    commands: list[dict[str, Any]], ids: list[str]
+) -> list[tuple[int, str, str]]:
+    """Scored tuples for the signalled ids, shaped like _score_commands.
+
+    An id the registry does not carry is skipped in silence: a signal
+    may only surface a command that actually exists, never invent one.
+    """
+    wanted = set(ids)
+    return [
+        (_SIGNAL_SCORE, cmd.get("command", ""), _hint_department(cmd))
+        for cmd in commands
+        if cmd.get("id") in wanted
+    ]
+
+
+def _merge_hints(
+    signal: list[tuple[int, str, str]],
+    keyword: list[tuple[int, str, str]],
+) -> list[tuple[int, str, str]]:
+    """Signal hints first, keyword hints after, de-duped by command text."""
+    seen: set[str] = set()
+    merged: list[tuple[int, str, str]] = []
+    for entry in [*signal, *keyword]:
+        if entry[1] in seen:
+            continue
+        seen.add(entry[1])
+        merged.append(entry)
+    return merged
+
+
 def _score_commands(
-    commands: list[dict], text: str
+    commands: list[dict[str, Any]], text: str
 ) -> list[tuple[int, str, str]]:
     """Keyword-score the registry commands against the prompt text,
     best score first; zero-score commands never qualify."""
@@ -468,6 +542,17 @@ class CommandHintsLayer(Layer):
     the route. The old `[hint:/cmd]` form was declarative and routinely
     ignored: the model announced the squad in prose and the skill's
     content never entered context.
+
+    Beyond the prompt words, the layer routes by PROJECT SHAPE: when the
+    hook cwd carries the files that identify a project kind
+    (``PROJECT_SIGNALS`` — e.g. a Hyperframes video-as-code project ships
+    ``hyperframes.json``, or ``BRIEF.md`` + ``STORYBOARD.md``), that
+    command is hinted even when the prompt matches no keyword. An
+    operator standing inside such a project asks "render the intro" or
+    "muda o segundo plano" — vocabulary the registry cannot enumerate —
+    and keyword-only scoring left the specialist route silent while the
+    generic assistant answered. Signal hints lead the merged list and the
+    top-2 cap still holds, so a signal costs at most one keyword slot.
     """
 
     def __init__(self, commands: list[dict] | None = None) -> None:
@@ -510,7 +595,12 @@ class CommandHintsLayer(Layer):
                 cached=False,
             )
 
-        top = _score_commands(self._commands, text)[:2]
+        signal = _signal_commands(
+            self._commands, _project_signal_ids(ctx.cwd)
+        )
+        top = _merge_hints(
+            signal, _score_commands(self._commands, text)
+        )[:2]
         hints = [command for _, command, _ in top]
 
         tags = _hint_tag(top)

package/departments/content/SKILL.md

@@ -38,6 +38,7 @@ allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent, WebFetch, WebSearch]
 | `/content calendar <period>` | Content calendar with themes and batching | Focused |
 | `/content thumbnail <video>` | Thumbnail + title packaging (A/B variants) | Specialist |
 | `/content video <topic>` | End-to-end video production (research → script → assets → render) | Enterprise |
+| `/content hyperframes <task>` | Direct Hyperframes work: compose, animate, caption, port, render and review a video-as-code project | Specialist |
 | `/content trends <niche>` | Demand-first trend and niche analysis with STEPPS scoring | Specialist |
 | `/content research <topic>` | Sourced research compiled into a production brief | Focused |
 | `/content video-setup` | Video production environment bootstrap (Hyperframes, Agent-Reach, Higgsfield) | Specialist |

package/departments/content/skills/hyperframes/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: content/hyperframes
+description: >
+  Direct Hyperframes work — video-as-code in HTML/CSS/JS + GSAP rendered to a
+  deterministic MP4 — on a new or existing project: compose, animate, keyframe,
+  caption, mix audio, port from Remotion, import from Figma, render, preview,
+  publish, batch-render. Loads the /hyperframes router FIRST and wraps it in the
+  ArkaOS doctrine (Simão owns it, [arka:design] marker on compositions,
+  dev/watch review of the render, Quality Gate). TRIGGER: "/content
+  hyperframes", "renderiza o vídeo", "render this composition", "ajusta os
+  keyframes", "adiciona legendas embutidas", "motion graphic", "title card",
+  "lower third", "converte este projeto Remotion", "importa do Figma para
+  vídeo", "slideshow", "faceless explainer", "explainer sem rosto", any cwd
+  holding hyperframes.json or BRIEF.md + STORYBOARD.md (Synapse L5 project
+  signal — inside a running /content video pipeline the pipeline keeps
+  ownership and calls this skill at its edit/render phase). SKIP: brief-to-MP4
+  production with research, script and asset generation -> content/video-produce
+  (its edit/render phase loads this skill); one-off environment install
+  -> content/video-setup; watching or analysing a video -> dev/watch;
+  scroll-driven website from a video -> dev/animated-website.
+allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent, Skill, WebFetch]
+metadata:
+  origin: arkaos
+---
+
+<!-- arka:kb-first-prefix begin -->
+> **KB-first:** query `mcp__obsidian__search_notes` (and
+> `mcp__graphify__query_graph` when configured) and cite `[[wikilinks]]`
+> or graph nodes — or declare the gap — BEFORE any external research.
+> Full doctrine: `arka/SKILL.md` (KB-First Research).
+<!-- arka:kb-first-prefix end -->
+
+# Hyperframes — `/content hyperframes <task>`
+
+> **Agent:** Simão (Video Producer) | **Engine:** Hyperframes by HeyGen (Apache-2.0) — core skills under `~/.claude/skills/`, creation workflows installed on demand by the router
+> **Rule:** the `/hyperframes` router owns the workflow; this skill owns the ArkaOS ceremony around it. Never reconstruct Hyperframes from memory.
+
+## Phase 0 — Preflight (one command, always)
+
+```
+npx hyperframes skills check
+```
+
+| Result | Action |
+|---|---|
+| `N current`, nothing outdated | proceed |
+| `↑ outdated` listed | `npx hyperframes skills update` refreshes the core set and every skill already installed; it never installs a workflow that is absent. The router installs that one when it picks it, with `npx hyperframes skills update <workflow>` |
+| `~/.claude/skills/hyperframes/SKILL.md` missing | STOP with exactly "Hyperframes não instalado — corre /content video-setup". Never improvise the format. |
+| `node --version` below 22, or no `ffmpeg` | STOP and print the platform install line — `content/video-setup` owns installs, this skill never mutates system packages |
+
+## Phase 1 — Load the router, then follow it
+
+Invoke `Skill(hyperframes)` FIRST. It resumes project state (`BRIEF.md`, `hyperframes.json`, `STORYBOARD.md`), runs the intent interview for fresh creation, picks the owning workflow from its route table and installs it. Two ArkaOS constraints on top:
+
+- A specific operation on an existing project (inspect, diagnose, validate, preview, render, publish, batch-render): the router loads `/hyperframes-cli` — do that operation and nothing else.
+- Fresh creation: the interview ends by writing `BRIEF.md`. Read the marketing context first (KB-first: `WizardingCode/Marketing/product-marketing.md` in Obsidian, else the project-local `.agents/product-marketing.md`) so the brief carries the real positioning, never an invented one.
+
+## Phase 2 — Compose under the design doctrine
+
+A Hyperframes composition is `.html`, so the frontend excellence gate applies exactly as it does to UI (constitution `excellence-mandate`, `core/workflow/frontend_gate.py`). Before the first Write/Edit of a composition emit the structured marker on a line of its own:
+
+```
+[arka:design] benchmark=<named reference: Linear launch films, Vercel Ship keynote, Stripe Sessions…> skills=hyperframes,hyperframes-core,hyperframes-animation,<hyperframes-creative|hyperframes-keyframes|hyperframes-audio as loaded> tokens=<brand tokens path|none>
+```
+
+- ArkaOS-branded output follows The Assembly v1.1 (`docs/design/brand-assembly/`, skill `arkaos-design`): zinc + rose, Signal used sparingly, Space Grotesk / IBM Plex — `tokens=` points there.
+- Client work: `tokens=` points at the project's design-system document (`project-design-system-prerequisite`): no document, no composition — extract it first with `/brand design-system`.
+- Anti-default: no template title cards, no stock easing on every element, no "AI video" look. GSAP timelines with labels and position parameters (Simão's framework): load `dev/gsap` for GSAP itself (`references/timeline.md` for timelines, labels and position parameters; `references/core.md` for tweens and easing; `references/plugins.md` for kinetic type and SplitText; `references/performance.md` before the render) — upstream `hyperframes-animation` covers the Hyperframes-specific timing; it does not replace it. Word-level captions through `/embedded-captions` whenever there is speech.
+- Assets: `/media-use` resolves BGM, SFX, images and logos from licensed sources before anything is downloaded. Generated assets come from Higgsfield (`content/image-create`, `generate_video`); credits are metered — never regenerate in a loop without explicit approval.
+
+## Phase 3 — Render and review with evidence
+
+1. Render through the router / `/hyperframes-cli` (`npx hyperframes render …`). Keep the command and exit code on record (G3 of the evidence flow).
+2. Review the render with `dev/watch` on the output MP4: complete frames + timestamped transcript. Judge the hook (first 3 s), pacing, caption accuracy, audio sync, aspect ratio, brand fidelity. Screenshots are not evidence; frames are.
+3. Loop on defects. A reshoot the review demands is never blocked by time or token cost; the CostGovernor budget is the only ceiling.
+
+## Phase 4 — Quality Gate and delivery
+
+Marta orchestrates Eduardo (on-screen copy, captions, description) and Francisca (render spec, determinism, composition code quality). Binary verdict. Deliver the master MP4, the per-platform reframes the brief asked for, the SRT when captions exist, and the `[arka:design]` line plus review notes in the delivery summary. Output goes to Obsidian `WizardingCode/Content/Video/<date>-<slug>/` (or the client project's vault path).
+
+## Never
+
+- Never load `/hyperframes` when the preflight fails, and never guess what Hyperframes is.
+- Never bypass the router's route table with a hand-picked workflow "because it looks right" — the router reads `references/routes/<workflow>.md` and decides.
+- Never ship a render nobody watched.
+- Never install Hyperframes skills from a marketplace other than `heygen-com/hyperframes`; third-party "video" skills that wrap paid engines or hook every `*video*` skill are rejected by decision (spec `hyperframes-routing`).
+
+## Examples
+
+```
+/content hyperframes "renderiza o projeto em ./launch-film e revê o resultado"
+/content hyperframes "adiciona legendas embutidas word-level ao talking head em ./ep03"
+/content hyperframes "converte a composição Remotion em ./remotion-intro para Hyperframes"
+/content hyperframes "motion graphic de 8 s com o número 30K a subir, brand ArkaOS"
+```