arkaos 5.17.0 → 5.17.2

package/core/runtime/pricing.py

@@ -6,7 +6,8 @@ their public per-token pricing. It is used to compute an optional
 any model-selection logic — that is explicitly forbidden by the
 LLM-agnostic contract.
 
-Snapshot 2026-09-03 (Runtime Sync PR-2): values sourced from the public
+Snapshot 2026-09-03 (Runtime Sync PR-2), Opus 5.5 rows added 2026-09-22:
+values sourced from the public
 Anthropic pricing page (https://platform.claude.com/docs/en/about-claude/pricing) and
 OpenAI (https://openai.com/api/pricing). Refresh when model families
 change. Unknown models return `None` from `estimate_cost_usd` and are
@@ -61,11 +62,32 @@ PRICING: dict[str, dict[str, float]] = {
         "cache_read": 1.00,
         "cache_write": 12.50,
     },
-    # Snapshot 2026-08-09 (Gate Economy PR-8): drop-in at Opus 4.8's
-    # rates per the official model catalog — 1M context is the default
-    # with NO long-context premium, so the [1m] alias prices the same.
-    # This row was missing while claude-opus-5 carried 28% of weekly
+    # Snapshot 2026-09-22 (Opus 5.5 sweep): $4 / $20 per MTok and cache
+    # reads at $0.20 (0.05x input) per the public pricing page; the Claude
+    # Code 2.1.280 alias `opus` resolves here, so this is the lane every
+    # `model: opus` agent runs on. cache_write is NOT published yet: 5.00
+    # is the standard 1.25x five-minute multiplier — the same assumption
+    # the Fable 5.1 row shipped with — replace it when the page lists it.
+    # 1M context is native; the [1m] alias prices the same.
+    "claude-opus-5-5": {
+        "input": 4.00,
+        "output": 20.00,
+        "cache_read": 0.20,
+        "cache_write": 5.00,
+    },
+    "claude-opus-5-5[1m]": {
+        "input": 4.00,
+        "output": 20.00,
+        "cache_read": 0.20,
+        "cache_write": 5.00,
+    },
+    # History — snapshot 2026-08-09 (Gate Economy PR-8): drop-in at Opus
+    # 4.8's rates per the official model catalog — 1M context is the
+    # default with NO long-context premium, so the [1m] alias prices the
+    # same. The row was missing while claude-opus-5 carried 28% of weekly
     # input tokens, pricing them at $0.00 and blinding the CostGovernor.
+    # Retained so 2026-08/09 sessions stay priced; the live lane is
+    # claude-opus-5-5 above.
     "claude-opus-5": {
         "input": 5.00,
         "output": 25.00,

package/core/runtime/runtime_models.py

@@ -3,14 +3,16 @@
 The Model Fabric ``runtime`` provider shells out to the active CLI. This
 module lists the concrete models that CLI accepts, with human labels and
 tier, so the dashboard dropdown and ``/arka-fusion`` can offer real
-choices (Fable 5.1, Opus 5, Sonnet 5) instead of only the abstract
+choices (Fable 5.1, Opus 5.5, Sonnet 5) instead of only the abstract
 best/default/fast aliases. Haiku is deliberately absent: the weakest
 lane ArkaOS routes to is Sonnet 5 (operator decision, Runtime Sync 2026-09-03).
 
-Model IDs verified against the Claude Code changelog 2.1.257 (2026-09-01)
-and the model-config reference (2026-09). This is the single place they
-are hand-listed — update HERE when the runtime
-ships new models; the dashboard and CLI read from this module. Codex /
+Model IDs verified against the Claude Code 2.1.280 alias table (2026-09-22:
+`opus` → claude-opus-5-5) and the model-config reference (2026-09). This is the single place
+the picker catalogue is hand-listed — update HERE when the runtime ships new
+models; the dashboard and CLI read from this module. The ids also live in
+pricing.py, model_router.py, claude_code.py, gateway/litellm_config.py and
+installer/fallback-model.js (one sweep touches all six). Codex /
 Gemini / Cursor models are left empty on purpose: we do not hardcode
 another vendor's catalogue, and the UI falls back to a free-text field
 so the user types the exact id their runtime accepts.
@@ -24,8 +26,8 @@ from __future__ import annotations
 CLAUDE_CODE_MODELS: list[dict[str, str]] = [
     {"value": "claude-fable-5-1", "label": "Fable 5.1", "tier": "frontier",
      "note": "most capable — 1M context, cache reads $0.25/MTok"},
-    {"value": "opus", "label": "Opus 5", "tier": "frontier",
-     "note": "frontier"},
+    {"value": "opus", "label": "Opus 5.5", "tier": "frontier",
+     "note": "frontier — $4/$20 per MTok, cache reads $0.20"},
     {"value": "sonnet", "label": "Sonnet 5", "tier": "balanced",
      "note": "balanced speed/quality — also the mechanical lane"},
 ]

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/dashboard/app/pages/models.vue

@@ -128,7 +128,7 @@ const targetOptions = computed(() => {
   const o = overview.value
   if (!o) return []
   const options: { label: string, value: string }[] = []
-  // Concrete runtime models first (Fable 5.1, Opus 5, Sonnet 5) so the
+  // Concrete runtime models first (Fable 5.1, Opus 5.5, Sonnet 5) so the
   // operator picks a real model, not just an abstract alias.
   for (const m of o.runtime?.models ?? []) {
     options.push({ label: `runtime / ${m.label} · ${m.note}`, value: `runtime/${m.value}` })

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"
+```

package/departments/content/skills/video-produce/SKILL.md

@@ -11,7 +11,9 @@ description: >
   videos -> /content shorts (content-shorts-produce workflow); short-form
   scripting only -> /content short (content/short-form); one-off
   environment setup ->
-  content/video-setup; YouTube channel strategy -> content/youtube-strategy.
+  content/video-setup; direct work on an existing Hyperframes project
+  (render, keyframes, captions, port) -> content/hyperframes; YouTube channel
+  strategy -> content/youtube-strategy.
 allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent, WebFetch, WebSearch]
 metadata:
   origin: community
@@ -45,7 +47,7 @@ tier PER CAPABILITY. Print the matrix, state the tiers chosen, proceed
 | Capability | Full | Degraded | Manual |
 |---|---|---|---|
 | Asset generation | Higgsfield MCP (`generate_image/video/audio`, `create_voice`, `motion_control`, `upscale`) | `arka-comfyui` local | asset brief: engine-ready prompts per shot |
-| Edit / render | Hyperframes skills (Node 22 + FFmpeg; load `/hyperframes` router) | Higgsfield `explainer_video` / `shorts_studio` server-side | edit-ready package: script + assets + shot list/EDL + SRT captions |
+| Edit / render | Hyperframes skills (Node 22 + FFmpeg; via `content/hyperframes`) | Higgsfield `explainer_video` / `shorts_studio` server-side | edit-ready package: script + assets + shot list/EDL + SRT captions |
 | Research | agent-reach | firecrawl + WebSearch | KB-only |
 
 ## Pipeline (gates match the content-video workflow)
@@ -70,22 +72,29 @@ tier PER CAPABILITY. Print the matrix, state the tiers chosen, proceed
    `upscale`/`reframe`. → **user approval on generated assets —
    Higgsfield credits are metered; NEVER regenerate in a loop without
    explicit approval.**
-6. **Edit / render** — PREFLIGHT (one line, mandatory before the Full
-   tier): if `ls ~/.claude/skills | grep -qi hyperframes` fails, STOP
-   with the exact message "Hyperframes não instalado — corre
-   /content video-setup" — NEVER load `/hyperframes` blind or improvise
-   what Hyperframes might be. (Tier degradation is a Phase 0 decision;
-   reaching this step on the Full tier with the skills missing means
-   setup drift: the honest move is the stop + fix command, or an
+6. **Edit / render** — PREFLIGHT (one command, mandatory before the Full
+   tier): `npx hyperframes skills check`. It must report 0 outdated.
+   Outdated listed: run `npx hyperframes skills update` and re-check;
+   still outdated: treat it as setup drift (below). Skills missing
+   (`~/.claude/skills/hyperframes/SKILL.md` absent): STOP with the exact
+   message "Hyperframes não instalado — corre /content video-setup" —
+   NEVER load `/hyperframes` blind or improvise what Hyperframes might
+   be. (Tier degradation is a Phase 0 decision;
+   reaching this step on the Full tier with the skills missing or stale
+   means setup drift: the honest move is the stop + fix command, or an
    explicitly re-stated downgrade to the Degraded/Manual tier.)
-   Full tier: load the `/hyperframes` router skill, pick the
-   workflow (`/talking-head-recut`, `/faceless-explainer`,
-   `/product-launch-video`…), compose in HTML+GSAP (load `dev/gsap` —
-   `references/core.md` + `references/timeline.md` for motion graphics; `references/plugins.md` for kinetic
-   type/SplitText), add word-level captions (`/embedded-captions`),
-   render MP4. Degraded tier: hand assets+script to Higgsfield
-   `explainer_video`/`shorts_studio`. Manual tier: assemble the
-   edit-ready package and say exactly what a human editor gets.
+   Full tier: run `content/hyperframes` — it loads the `/hyperframes`
+   router, which picks the workflow (`/talking-head-recut`,
+   `/faceless-explainer`, `/product-launch-video`…), and it owns the
+   ArkaOS ceremony around the composition: the structured `[arka:design]`
+   marker before any `.html` is written, GSAP timelines with labels and
+   position params for motion graphics, word-level captions via
+   `/embedded-captions`, and the `dev/watch` review of the render. The
+   pipeline keeps ownership of the project directory; the skill is its
+   edit/render phase, not a second pipeline. Degraded tier: hand
+   assets+script to Higgsfield `explainer_video`/`shorts_studio`. Manual
+   tier: assemble the edit-ready package and say exactly what a human
+   editor gets.
 7. **Virality QA** — STEPPS audit pre-publish (Filipe) +
    `virality_predictor`/`video_analysis` when Higgsfield is live
    (hook strength, retention risk) + technical QC (sync, caption
@@ -321,6 +330,7 @@ requests — so no manual editing step is required.
 - **`content/short-form`** — short-form scripting and batches
 - **`content/youtube-strategy`** — YouTube channel strategy
 - **`content/video-setup`** — one-off environment setup
+- **`content/hyperframes`** — direct work on a Hyperframes project (the Full-tier edit/render phase runs it)
 - **`mkt/social-strategy`** — video content strategy and what to post
 - **`mkt/paid-campaign`** — paid video ad creative and iteration
 - **`landing/copy-framework`** — video scripts and messaging

package/departments/content/skills/video-setup/SKILL.md

@@ -8,7 +8,8 @@ description: >
   "prepara o ambiente de vídeo", "instala o hyperframes", "configura a
   produção de vídeo", "video production setup". SKIP: actually producing
   a video -> content/video-produce (it preflights non-interactively and
-  degrades); general MCP setup -> /arka keys or apply-mcps.
+  degrades); direct work on an existing Hyperframes project ->
+  content/hyperframes; general MCP setup -> /arka keys or apply-mcps.
 allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent, WebFetch, WebSearch]
 ---
 
@@ -29,25 +30,37 @@ allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent, WebFetch, WebSearch]
 |---|---|---|
 | Node.js 22+ | `node --version` | Hyperframes rendering |
 | FFmpeg | `ffmpeg -version` | encode/cut + transcription |
-| Hyperframes skills | `ls ~/.claude/skills/ \| grep -i hyperframes` | video-as-code editing |
+| Hyperframes skills (installed AND fresh) | `npx hyperframes skills check` — 0 outdated required; when `npx hyperframes` cannot run (offline), the sentinel `ls ~/.claude/skills/hyperframes/SKILL.md` proves installed, not fresh | video-as-code editing |
 | Agent-Reach | `agent-reach doctor` | trend/research platform pulls |
 | Higgsfield key | `HIGGSFIELD_API_KEY` in env or `~/.arkaos/keys.json` | generation engine (MCP) |
 
-`npx arkaos doctor` runs the same five checks (warn-only) from the
-installer side — this skill is the interactive fix path.
+`npx arkaos doctor` runs the same five checks (warn-only; its Hyperframes
+row is the installed sentinel only — freshness is this skill's job) from the
+installer side; this skill is the interactive fix path.
 
 ## Install steps — EACH gated on explicit user confirmation, never silent
 
-1. **Hyperframes skills** (free, Apache-2.0, HeyGen):
+1. **Hyperframes skills** (free, Apache-2.0, HeyGen). Interactive install —
+   select **Core Skills**; the `/hyperframes` router lazy-installs the
+   creation workflow a request needs (`/product-launch-video`,
+   `/faceless-explainer`, `/talking-head-recut`, `/motion-graphics`,
+   `/embedded-captions`, `/media-use`…):
    ```
-   npx skills add heygen-com/hyperframes --full-depth --yes
+   npx skills add heygen-com/hyperframes
    ```
-   `--full-depth` is MANDATORY — without it the skills registry serves a
-   stale snapshot that lags the upstream main branch. Installs ~20
-   skills including the `/hyperframes` router, `/talking-head-recut`,
-   `/faceless-explainer`, `/product-launch-video`, `/motion-graphics`,
-   `/embedded-captions`, `/media-use`. Keep fresh later with
-   `npx hyperframes skills update <workflow>`.
+   Non-interactive install or refresh (agent, CI) of the core set plus every
+   Hyperframes skill already present on the machine:
+   ```
+   npx hyperframes skills update
+   ```
+   Freshness is a first-class check: `npx hyperframes skills check` lists
+   outdated skills, and the preflight row must read 0 outdated, not merely
+   "installed". Skills land in `~/.claude/skills/` and `~/.agents/skills/`
+   (the CLI links them into every detected agent). To install every
+   published workflow up front — only for a machine that must work offline
+   across every workflow — run `npx hyperframes skills`: it installs the
+   complete published set, not just the core. Upstream doc:
+   hyperframes.heygen.com.
 2. **Agent-Reach CLI** (MIT, beta — THIRD-PARTY GitHub code, NOT on
    PyPI): the package `agent-reach` does NOT exist in any registry —
    `pipx install agent-reach` / `uv tool install agent-reach` fail with
@@ -100,4 +113,4 @@ hardcoded to a single external backend).
 
 Setup report: preflight table, what was installed (with user consent
 noted per step), the capability matrix, and the exact next command to
-try (`/content video <topic>`).
+try (`/content video <topic>` for a brief-to-MP4 run, `/content hyperframes <task>` for direct work on a Hyperframes project).

package/harness/codex/AGENTS.md

@@ -1,6 +1,6 @@
 # ArkaOS — The Operating System for AI Agent Teams
 
-> v5.16.1 — 89 agents, 17 departments, 340 skills. Generated by `scripts/harness_gen.py`; do not edit.
+> v5.17.1 — 89 agents, 17 departments, 341 skills. Generated by `scripts/harness_gen.py`; do not edit.
 
 You are operating within ArkaOS. Every request routes through the
 appropriate department squad — never respond as a generic assistant.
@@ -33,7 +33,7 @@ appropriate department squad — never respond as a generic assistant.
 | `/pm` | Carolina | 12 |
 | `/saas` | Tiago | 15 |
 | `/landing` | Ines | 17 |
-| `/content` | Rafael | 20 |
+| `/content` | Rafael | 21 |
 | `/community` | Beatriz | 15 |
 | `/sales` | Miguel | 13 |
 | `/lead` | Rodrigo | 10 |

package/harness/copilot/copilot-instructions.md

@@ -1,6 +1,6 @@
 # ArkaOS — The Operating System for AI Agent Teams
 
-> v5.16.1 — 89 agents, 17 departments, 340 skills. Generated by `scripts/harness_gen.py`; do not edit.
+> v5.17.1 — 89 agents, 17 departments, 341 skills. Generated by `scripts/harness_gen.py`; do not edit.
 
 You are operating within ArkaOS. Every request routes through the
 appropriate department squad — never respond as a generic assistant.
@@ -33,7 +33,7 @@ appropriate department squad — never respond as a generic assistant.
 | `/pm` | Carolina | 12 |
 | `/saas` | Tiago | 15 |
 | `/landing` | Ines | 17 |
-| `/content` | Rafael | 20 |
+| `/content` | Rafael | 21 |
 | `/community` | Beatriz | 15 |
 | `/sales` | Miguel | 13 |
 | `/lead` | Rodrigo | 10 |

package/harness/cursor/rules/arkaos.mdc

@@ -1,11 +1,11 @@
 ---
-description: ArkaOS v5.16.1 agent-team contract
+description: ArkaOS v5.17.1 agent-team contract
 alwaysApply: true
 ---
 
 # ArkaOS — The Operating System for AI Agent Teams
 
-> v5.16.1 — 89 agents, 17 departments, 340 skills. Generated by `scripts/harness_gen.py`; do not edit.
+> v5.17.1 — 89 agents, 17 departments, 341 skills. Generated by `scripts/harness_gen.py`; do not edit.
 
 You are operating within ArkaOS. Every request routes through the
 appropriate department squad — never respond as a generic assistant.
@@ -38,7 +38,7 @@ appropriate department squad — never respond as a generic assistant.
 | `/pm` | Carolina | 12 |
 | `/saas` | Tiago | 15 |
 | `/landing` | Ines | 17 |
-| `/content` | Rafael | 20 |
+| `/content` | Rafael | 21 |
 | `/community` | Beatriz | 15 |
 | `/sales` | Miguel | 13 |
 | `/lead` | Rodrigo | 10 |

package/harness/gemini/GEMINI.md

@@ -1,6 +1,6 @@
 # ArkaOS — The Operating System for AI Agent Teams
 
-> v5.16.1 — 89 agents, 17 departments, 340 skills. Generated by `scripts/harness_gen.py`; do not edit.
+> v5.17.1 — 89 agents, 17 departments, 341 skills. Generated by `scripts/harness_gen.py`; do not edit.
 
 You are operating within ArkaOS. Every request routes through the
 appropriate department squad — never respond as a generic assistant.
@@ -33,7 +33,7 @@ appropriate department squad — never respond as a generic assistant.
 | `/pm` | Carolina | 12 |
 | `/saas` | Tiago | 15 |
 | `/landing` | Ines | 17 |
-| `/content` | Rafael | 20 |
+| `/content` | Rafael | 21 |
 | `/community` | Beatriz | 15 |
 | `/sales` | Miguel | 13 |
 | `/lead` | Rodrigo | 10 |

package/harness/opencode/AGENTS.md

@@ -1,6 +1,6 @@
 # ArkaOS — The Operating System for AI Agent Teams
 
-> v5.16.1 — 89 agents, 17 departments, 340 skills. Generated by `scripts/harness_gen.py`; do not edit.
+> v5.17.1 — 89 agents, 17 departments, 341 skills. Generated by `scripts/harness_gen.py`; do not edit.
 
 You are operating within ArkaOS. Every request routes through the
 appropriate department squad — never respond as a generic assistant.
@@ -33,7 +33,7 @@ appropriate department squad — never respond as a generic assistant.
 | `/pm` | Carolina | 12 |
 | `/saas` | Tiago | 15 |
 | `/landing` | Ines | 17 |
-| `/content` | Rafael | 20 |
+| `/content` | Rafael | 21 |
 | `/community` | Beatriz | 15 |
 | `/sales` | Miguel | 13 |
 | `/lead` | Rodrigo | 10 |

package/harness/opencode/agents/arka-architect-gabriel.md

@@ -3,7 +3,7 @@ description: "Software Architect — ArkaOS /dev department"
 mode: subagent
 ---
 
-You are Gabriel, Software Architect of the ArkaOS /dev department (v5.16.1; generated by scripts/harness_gen.py — do not edit).
+You are Gabriel, Software Architect of the ArkaOS /dev department (v5.17.1; generated by scripts/harness_gen.py — do not edit).
 
 Expertise: system design, system visualization via dev/diagram (architecture + dataflow diagrams delivered as browser artifacts), domain modeling (event storming, bounded contexts), design patterns (GoF, PoEAA), business / domain analysis, API design, data architecture, integration patterns.
 

package/harness/opencode/agents/arka-brand-director-valentina.md

@@ -3,7 +3,7 @@ description: "Creative Director — ArkaOS /brand department"
 mode: subagent
 ---
 
-You are Valentina, Creative Director of the ArkaOS /brand department (v5.16.1; generated by scripts/harness_gen.py — do not edit).
+You are Valentina, Creative Director of the ArkaOS /brand department (v5.17.1; generated by scripts/harness_gen.py — do not edit).
 
 Expertise: brand identity creation, reference-video visual analysis via dev/watch (complete frames + transcript — motion and art direction judged on evidence, never on screenshots), visual design direction, UX/UI strategy, design systems, brand voice & tone, design DNA extraction and replicate-vs-differentiate calls via brand/design-dna (refusal layer, SSRF rules, attestation), creative direction.
 

package/harness/opencode/agents/arka-cfo-helena.md

@@ -3,7 +3,7 @@ description: "Chief Financial Officer — ArkaOS /fin department"
 mode: subagent
 ---
 
-You are Helena, Chief Financial Officer of the ArkaOS /fin department (v5.16.1; generated by scripts/harness_gen.py — do not edit).
+You are Helena, Chief Financial Officer of the ArkaOS /fin department (v5.17.1; generated by scripts/harness_gen.py — do not edit).
 
 Expertise: financial planning & analysis, valuation & investment, unit economics & SaaS metrics, risk management & ERM, fundraising & cap tables, cash flow management.
 

package/harness/opencode/agents/arka-chief-of-staff-afonso.md

@@ -3,7 +3,7 @@ description: "Chief of Staff & Governance Lead — ArkaOS /org department"
 mode: subagent
 ---
 
-You are Afonso, Chief of Staff & Governance Lead of the ArkaOS /org department (v5.16.1; generated by scripts/harness_gen.py — do not edit).
+You are Afonso, Chief of Staff & Governance Lead of the ArkaOS /org department (v5.17.1; generated by scripts/harness_gen.py — do not edit).
 
 Expertise: meeting cadence (daily/weekly/quarterly/annual), OKR & CFR orchestration cross-department, decision records & RACI, premortem / blameless postmortem rituals, governance, board & founder-CEO succession, strategic alignment & single-threaded leadership.
 

package/harness/opencode/agents/arka-community-strategist-beatriz.md

@@ -3,7 +3,7 @@ description: "Community Strategist — ArkaOS /community department"
 mode: subagent
 ---
 
-You are Beatriz, Community Strategist of the ArkaOS /community department (v5.16.1; generated by scripts/harness_gen.py — do not edit).
+You are Beatriz, Community Strategist of the ArkaOS /community department (v5.17.1; generated by scripts/harness_gen.py — do not edit).
 
 Expertise: community strategy & design, platform selection (Discord, Telegram, Skool, Circle), member onboarding & retention, monetization (membership, courses, coaching), gamification & engagement, niche communities (betting, AI, vertical), community-led growth.
 

package/harness/opencode/agents/arka-content-strategist-rafael.md

@@ -3,7 +3,7 @@ description: "Content Strategist — ArkaOS /content department"
 mode: subagent
 ---
 
-You are Rafael, Content Strategist of the ArkaOS /content department (v5.16.1; generated by scripts/harness_gen.py — do not edit).
+You are Rafael, Content Strategist of the ArkaOS /content department (v5.17.1; generated by scripts/harness_gen.py — do not edit).
 
 Expertise: viral content design, reference-video analysis via dev/watch (frames + timestamped transcript before judging any video), hook writing & packaging, script structure, content operating systems, platform-specific optimization, repurposing (1→30+ pieces), AI-augmented content creation.