@event4u/agent-config 5.5.0 → 5.6.1

package/docs/contracts/rule-router.md

@@ -123,6 +123,45 @@ The host agent reads `dist/router.json` once per session. Per turn:
 No runtime profile resolution — the profile is fixed at session
 start, the router lookup is keyword/phrase/path/intent matching only.
 
+## Kill-switch — thin-projection rollback (lean-initial-context Phase 2.3)
+
+Phase 3 of the lean-initial-context migration makes the per-tool projector
+emit the kernel full-bodied and every non-kernel rule as a one-line
+router-resolved pointer. That is the suite's biggest behavioural change, so
+it ships behind a **single documented flip** that restores today's
+full-eager projection:
+
+```yaml
+# .agent-settings.yml
+lean_projection:
+  # thin     = kernel full-bodied + non-kernel rules as router pointers (Phase 3)
+  # eager-all = every rule body inlined into every projection (today's behaviour)
+  mode: eager-all   # DEFAULT until Phase 3.1 ships + its benchmark gate is green
+```
+
+Revert procedure (one flip, no code change): set `lean_projection.mode:
+eager-all`, run `task generate-tools` (regenerates `.claude/`, `.cursor/`,
+`.clinerules/`, `.windsurfrules`) + `task sync` (`.agent-src/`, `.augment/`).
+The thin projector (Phase 3.1) MUST honour this key; with it absent or
+`eager-all` the projector behaves exactly as today. Default stays
+`eager-all` so the migration is opt-in and reversible by one line.
+
+### Staleness guard — `src → dist`
+
+A projection or router that drifts from source silently re-introduces the
+eager bytes (or a missing pointer target). Three CI gates enforce
+`src == dist`, all already wired into `task ci`:
+
+- `task check-router` (`compile_router.py --check`) — `dist/router.json`
+  must equal a fresh compile from frontmatter `triggers:`/`routes_to:`.
+- `task check-artefact-checksums` — every artefact's committed checksum
+  must match its current source bytes.
+- `task lint-projection-fidelity` — the per-tool projections must match
+  what the projector would emit from source.
+
+The thin projector inherits all three: a thin projection whose recorded
+source hash ≠ current source fails CI before it can ship a stale pointer.
+
 ## Linter contract (Phase 3.3)
 
 `scripts/skill_linter.py` extension enforces:

package/docs/contracts/value-dashboard-spec.md

@@ -267,9 +267,13 @@ copies it verbatim into the dashboard.
   Saves output tokens — when the corpus rewards it.
 - **Ohne Paket / Mit Paket** — "without the package" /
   "with the package" — the two arms of the A/B comparison.
-- **€-per-1k-requests** — token cost at the reference scale
-  (1,000 requests of the average shape, priced at the current
-  Sonnet rates in `internal/bench/pricing.yaml`).
+- **Δ Tokens** — input-token difference per request vs. the baseline.
+  The rendered dashboard reports cost in **tokens only** — no € figure.
+  A €/USD comparison would assume per-call API pricing, which the many
+  users on subscriptions do not pay; tokens are the currency-neutral
+  metric. The `eur_delta` fields remain in the JSON for back-compat but
+  are not rendered. (Historical € figures elsewhere in this spec are
+  dated examples, kept as record.)
 
 ## Honest baseline appendix
 

package/docs/contracts/value-report-schema.md

@@ -80,10 +80,15 @@ totals:
   cumulative_pct: <signed float>         # net % of baseline
   net_verdict: net-saving | net-cost | break-even   # by sign of cumulative_pct
 notes:
-  - "Token→€ conversion priced at <model_tier> rates from <pricing source>."
+  - "Cost is reported in tokens only — no € figure (API pricing misleads subscription users)."
   - "<other invariants surfaced as plain prose>"
 ```
 
+> **Rendering note.** The `eur_delta` / `cumulative_eur_delta` /
+> `pricing_sourced_on` fields stay in the JSON for back-compat, but the
+> rendered dashboard (`docs/value.md`) shows **tokens only** — no € column,
+> no €-per-1k figure, no NETTO € line. See `scripts/render_value_md.py`.
+
 ## Invariants
 
 - **No silent drops.** Missing input → emit the rung with

package/docs/getting-started.md

@@ -129,7 +129,7 @@ Your agent is now:
 - **Respecting your codebase** — no conflicting patterns
 - **Following standards** — consistent code quality
 
-This is enforced automatically by 78 rules. No configuration needed.
+This is enforced automatically by 79 rules. No configuration needed.
 
 ---
 
@@ -169,7 +169,7 @@ Your agent now understands slash commands:
 | `/quality-fix` | Run and fix all quality checks |
 | `/chat-history` | Inspect the persistent chat-history log (read-only `show`) |
 
-→ [Browse all 141 active commands](../.agent-src/commands/)
+→ [Browse all 145 active commands](../.agent-src/commands/)
 
 ---
 

package/docs/value.md

@@ -4,7 +4,7 @@
 
 ## Wie diese Seite zu lesen ist
 
-**Panel A (Kostenleiter)** — von oben nach unten lesen. Jede Stufe sagt: *was sie macht*, *wie viele Input-Tokens sie pro Request hinzufügt oder spart*, *was das in € auf 1,000 Requests kostet*, und *wo wir kumulativ stehen*. Die fett gedruckte **NETTO**-Zeile am Ende ist die Antwort.
+**Panel A (Token-Leiter)** — von oben nach unten lesen. Jede Stufe sagt: *was sie macht*, *wie viele Input-Tokens sie pro Request hinzufügt oder spart*, und *wo wir kumulativ stehen*. Die fett gedruckte **NETTO**-Zeile am Ende ist die Antwort. Bewusst rein in Tokens — kein €-Vergleich, da Abo-Nutzer keine Per-Request-API-Preise zahlen.
 
 **Panel B (Verhalten)** — vier reale Vergleiche, *mit* vs. *ohne* Paket. Hier liegt der nicht-Token-Wert: passende Skill-Auswahl, Stopps bei riskanten Aktionen, weniger Rückfragen, mehr abgeschlossene Aufgaben.
 
@@ -13,25 +13,25 @@
 ## Reference scale
 
 - **1,000** Requests, durchschnittlich **8,000** Input-Tokens und **600** Output-Tokens pro Request
-- Modell-Tier: `sonnet` · Preisstand `2026-05-14` (Quelle: `internal/bench/pricing.yaml`)
+- Modell-Tier (Workload-Annahme): `sonnet`
 - Wer einen anderen Workload fährt, rechnet selbst nach — die Methodik ist offengelegt; nichts ist hardcodiert versteckt.
 
 ## Panel A — Kostenleiter (kumulativ, min → max)
 
 Liest sich von oben nach unten. Positive Δ-Werte = das Paket *kostet* Tokens (Regel-Load ist die ehrliche Up-Front-Steuer); negative Δ-Werte = das Paket *spart* Tokens.
 
-| Stufe | Was sie tut | Δ Tokens | Δ € (1k Req) | Kumulativ | Quelle |
-|---|---|---:|---:|---:|---|
-| **Ohne Paket / Without package** | Baseline — der nackte Request ohne Paket-Regeln. | +0 | +0.00 € | +0.00% | `n/a` · ✅ gemessen |
-| Mit Paket (Regeln laden) / With package (rule load) | Die immer-aktiven Regeln landen im Kontext jedes Requests. ⚠️ erst teurer | +8 895 | +24.55 € | +111.19% | `dist/router.json` · ✅ gemessen |
-| | _Fußnote:_ Kernel = 10 rules (31570 chars) + charter (4010 chars); tokens ≈ chars / 4. | | | | |
-| + condense (Regeln eindampfen) / + condense (rule shrink) | Build-Schritt schrumpft Regel-Dateien vor dem Ausliefern. | -186 | -0.51 € | +108.86% | `internal/bench/reports/telegraph-v2.json` · ✅ gemessen |
-| | _Fußnote:_ Aggregate across non-Thin-Root categories; Thin-Root files (AGENTS.md variants) net negative (~−4%) and are excluded from the rung — surfaced separately. | | | | |
-| + rtk (CLI-Output filtern) / + rtk (filter CLI output) | rtk schneidet verbose CLI-Ausgabe vor dem Modell-Input weg. | -593 | -1.64 € | +101.45% | `internal/bench/reports/rtk/latest.json` · ✅ gemessen |
-| + terse (Antworten knapper) / + terse (shorter replies) | Telegraph-Stil zielt auf knappere Modell-Antworten. | +56 | +0.77 € | +102.15% | `internal/bench/reports/telegraph-v1.json` · ✅ gemessen |
-| | _Fußnote:_ Honest: gemessener Median = -9.27% gegen 'sei knapp' — Telegraph liefert hier mehr Tokens, nicht weniger. Wir messen, wir verstecken nicht. | | | | |
+| Stufe | Was sie tut | Δ Tokens | Kumulativ | Quelle |
+|---|---|---:|---:|---|
+| **Ohne Paket / Without package** | Baseline — der nackte Request ohne Paket-Regeln. | +0 | +0.00% | `n/a` · ✅ gemessen |
+| Mit Paket (Regeln laden) / With package (rule load) | Die immer-aktiven Regeln landen im Kontext jedes Requests. ⚠️ erst teurer | +8 522 | +106.53% | `dist/router.json` · ✅ gemessen |
+| | _Fußnote:_ Kernel = 10 rules (30080 chars) + charter (4010 chars); tokens ≈ chars / 4. | | | |
+| + condense (Regeln eindampfen) / + condense (rule shrink) | Build-Schritt schrumpft Regel-Dateien vor dem Ausliefern. | -186 | +104.20% | `internal/bench/reports/telegraph-v2.json` · ✅ gemessen |
+| | _Fußnote:_ Aggregate across non-Thin-Root categories; Thin-Root files (AGENTS.md variants) net negative (~−4%) and are excluded from the rung — surfaced separately. | | | |
+| + rtk (CLI-Output filtern) / + rtk (filter CLI output) | rtk schneidet verbose CLI-Ausgabe vor dem Modell-Input weg. | -593 | +96.79% | `internal/bench/reports/rtk/latest.json` · ✅ gemessen |
+| + terse (Antworten knapper) / + terse (shorter replies) | Telegraph-Stil zielt auf knappere Modell-Antworten. | +56 | +97.49% | `internal/bench/reports/telegraph-v1.json` · ✅ gemessen |
+| | _Fußnote:_ Honest: gemessener Median = -9.27% gegen 'sei knapp' — Telegraph liefert hier mehr Tokens, nicht weniger. Wir messen, wir verstecken nicht. | | | |
 
-**NETTO: Mehrkosten** ⚠️ — **+8 172 Tokens / Request**, **+22.55 €** auf 1,000 Requests, kumulativ **+102.15%** vs. Baseline.
+**NETTO: Mehrkosten** ⚠️ — **+7 799 Tokens / Request**, kumulativ **+97.49%** vs. Baseline.
 
 ## Panel B — Verhalten (mit vs. ohne)
 
@@ -42,7 +42,7 @@ Vier reale Vergleiche aus echten Bench-Runs. Hier liegt der Wert, den Tokens all
 | Right-skill selection / Richtige Skill-Wahl | Wie oft das passende Skill aktiviert wird (top-K Treffer). | 50.0% | 0.0% | 50.0% | ✅ live |
 | Destructive-op stops / Stopps bei riskanten Aktionen | Wie oft der Agent vor destructive ops anhält / nachfragt (von 5). | — | — | — | ⚠️ dry-run |
 | Ask-vs-act ratio / Fragen vs. Handeln | Verhältnis Rückfragen zu Aktionen — niedriger = entschlossener. | 0.000 | 0.000 | 0.000 | ✅ live |
-| Task completion rate / Aufgaben fertig | Anteil der Aufgaben, die der Agent vollständig abschließt. | 84.6% | 7.7% | 76.9% | ✅ live |
+| Task completion rate / Aufgaben fertig | Anteil der Aufgaben, die der Agent vollständig abschließt. | 84.6% | 0.0% | 84.6% | ✅ live |
 
 ## Glossar
 
@@ -55,7 +55,7 @@ Plain-language Definitionen für den nicht-Entwickler-Reader.
 - **rtk** — der *Rust Token Killer*, ein CLI-Wrapper, der verbose Output (`git status`, lint-Output, test-Runner) filtert, bevor das Modell ihn liest. Spart Input-Tokens auf Tool-Calls.
 - **terse / telegraph** — ein Stil (kurze Phrasen, weggelassene Artikel), den der Agent für knappere Antworten nutzt. Spart Output-Tokens — wenn der Korpus es belohnt.
 - **Ohne Paket / Mit Paket** — *without the package* / *with the package* — die zwei Arme des A/B-Vergleichs.
-- **€-per-1k-requests** — Token-Kosten auf der Referenz-Skala (1.000 Requests durchschnittlicher Größe, gepreist mit den aktuellen Sonnet-Raten aus `internal/bench/pricing.yaml`).
+- **Δ Tokens** — Input-Token-Differenz pro Request gegenüber der Baseline. Bewusst die einzige Kosten-Einheit: ein €-Vergleich würde Per-Request-API-Preise unterstellen, die Abo-Nutzer nicht zahlen.
 
 ## Methodik & Quellen
 
@@ -77,8 +77,8 @@ Diese Seite ist eine **abgeleitete** Sicht — keine eigene Messung. Sie fasst d
 
 **Hinweise aus dem Report:**
 
-- Token→€ conversion priced at sonnet rates from internal/bench/pricing.yaml (sourced_on=2026-05-14).
+- Cost is reported in tokens only — no € figure. Per-call API pricing misleads subscription users; tokens are the currency-neutral metric.
 - Pending rungs contribute 0 to the cumulative until measured.
 - Reference scale: 1000 requests × 8000 input / 600 output tokens per request.
 
-_Last rendered: `2026-05-29T04:36:04+00:00`_
+_Last rendered: `2026-05-31T14:37:17+00:00`_

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@event4u/agent-config",
-    "version": "5.5.0",
+    "version": "5.6.1",
     "description": "Universal AI Agent OS \u2014 audited skills, governance rules, commands, and templates for AI coding tools (Claude Code, Cursor, Windsurf, Copilot).",
     "license": "MIT",
     "private": false,

package/scripts/_lib/bench_report.py

@@ -52,31 +52,32 @@ def _selection_section(selection: dict[str, Any]) -> str:
     return "\n".join(lines)
 
 
-def _cost_section(cost: dict[str, Any]) -> str:
+def _token_usage_section(cost: dict[str, Any]) -> str:
+    # Token-only — the monetary (USD) comparison is intentionally omitted:
+    # it assumes per-call API pricing, which misleads subscription users.
+    # Tokens are the currency-neutral metric that matters. JSON keeps the
+    # raw cost field for back-compat; it is simply not rendered.
     if cost.get("source") == "unavailable":
         return (
-            "## Cost capture\n\n"
+            "## Token usage\n\n"
             f"- **source:** `unavailable` ({cost.get('reason', 'unknown')})\n"
-            f"- **scanned:** `{cost.get('scanned_path', '—')}`\n"
-            f"- **pricing sourced on:** {cost.get('pricing_sourced_on') or '—'}\n\n"
+            f"- **scanned:** `{cost.get('scanned_path', '—')}`\n\n"
             "_No session jsonl available. Run `node scripts/cost/track.mjs` "
             "from a real Claude Code session to populate agents/cost-tracking/sessions.jsonl._\n"
         )
     totals = cost["totals"]
     lines = [
-        "## Cost capture",
+        "## Token usage",
         "",
         f"- **source:** `{cost['source']}` · sessions scanned: **{cost['sessions_scanned']}**",
-        f"- **pricing sourced on:** {cost.get('pricing_sourced_on') or '—'}",
-        f"- **total cost:** **${totals['total_cost_usd']:.6f}**",
         "",
-        "| tier | messages | cost (USD) |",
-        "|---|---:|---:|",
+        "| tier | messages |",
+        "|---|---:|",
     ]
     for tier, slot in cost["per_tier"].items():
         if slot["messages"] == 0 and slot["cost_usd"] == 0.0:
             continue
-        lines.append(f"| {tier} | {slot['messages']} | ${slot['cost_usd']:.6f} |")
+        lines.append(f"| {tier} | {slot['messages']} |")
     lines += [
         "",
         "| metric | value |",
@@ -125,21 +126,19 @@ def render_markdown(report: dict[str, Any]) -> str:
         f"# Benchmark Report — `{corpus['id']}` · {report['generated_at']}\n\n"
         "## Headline\n\n"
         f"- **selection** {sel['selection_accuracy']:.2%} (target {sel['target']:.2%}) → **{verdict['selection']}**\n"
-        f"- **cost** ${cost['totals']['total_cost_usd']:.6f} "
-        f"({'sessions=' + str(cost['sessions_scanned']) if cost['source'] != 'unavailable' else cost['source']})\n"
+        f"- **tokens** {'sessions=' + str(cost['sessions_scanned']) if cost['source'] != 'unavailable' else cost['source']}\n"
         f"- **quality** {qual['quality_score']:.2%} → **{verdict['quality']}**\n"
         f"- **overall** → **{verdict['overall']}**\n"
     )
     notes = (
         "## Notes\n\n"
         f"- corpus path: `{corpus['path']}` · prompts: **{corpus['prompt_count']}**\n"
-        f"- pricing: `internal/bench/pricing.yaml`\n"
         f"- baseline collector: `{report['runner']['baseline_collector']}`\n"
     )
     return "\n\n".join([
         headline,
         _selection_section(sel),
-        _cost_section(cost),
+        _token_usage_section(cost),
         _quality_section(qual),
         notes,
     ]) + "\n"

package/scripts/_lib/bench_telegraph_report.py

@@ -104,8 +104,7 @@ def render_telegraph_markdown(report: dict[str, Any]) -> str:
         f"(p10 {_fmt_pct(agg['savings_vs_terse']['p10'])} · p90 {_fmt_pct(agg['savings_vs_terse']['p90'])})",
         f"- median realised carve-out share (condensed arm): **{_fmt_pct(agg['realised_carve_out_pct']['median'])}** "
         f"(expected median {_fmt_pct(agg['expected_carve_out_pct']['median'])})",
-        f"- total cost: **${cost['totals']['total_cost_usd']:.6f}** "
-        f"(calls {cost['totals']['calls']} · errors {cost['totals']['errors']})",
+        f"- calls: **{cost['totals']['calls']}** · errors: **{cost['totals']['errors']}**",
         f"- verdict: **{report['verdict']['overall']}**",
         "",
     ]

package/scripts/_lib/token_count.py

@@ -0,0 +1,95 @@
+#!/usr/bin/env python3
+"""Real-tokenizer counting for the budget tooling (roadmap 0B.1).
+
+`char != token`. Every budget in this suite is historically in characters;
+the lean-initial-context goal is tokens. This helper adds a token count
+*alongside* chars so chars stay the cheap, stdlib-only proxy and tokens
+become the truth where a real tokenizer is available.
+
+Design — no silent installs, no mandatory network (per `missing-tool-handling`):
+
+- **GPT** — exact via `tiktoken` (`o200k_base`, the GPT-4o/4.1 encoding) when
+  the optional dependency is installed; otherwise a documented `chars / 4`
+  proxy flagged `exact=False`. Install `tiktoken` to activate exact counts.
+- **Claude** — no offline tokenizer ships in `anthropic` 0.98 (the SDK exposes
+  only the live `messages.count_tokens` endpoint, which needs an API call).
+  Offline we use a documented `chars / 3.6` proxy flagged `exact=False`; the
+  exact API count is reserved for the live-bench boundaries to avoid spend on
+  the cheap path.
+
+Both proxies are intentionally conservative ratios drawn from English-prose +
+markdown samples; they are estimates, never gates. The char budgets remain the
+enforced floor (`measure_rule_budget --kernel-budget-check`).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+# Proxy ratios (chars per token) for the no-tokenizer fallback. Tuned for
+# English markdown rule/skill prose; deliberately conservative.
+_GPT_CHARS_PER_TOKEN = 4.0
+_CLAUDE_CHARS_PER_TOKEN = 3.6
+
+_TIKTOKEN_ENCODING = "o200k_base"  # GPT-4o / GPT-4.1 family.
+
+# Resolve the optional tiktoken encoder once at import.
+try:  # pragma: no cover - exercised by env presence, not unit tests
+    import tiktoken  # type: ignore
+
+    _ENC = tiktoken.get_encoding(_TIKTOKEN_ENCODING)
+except Exception:  # ImportError, or model-data fetch failure offline
+    _ENC = None
+
+TIKTOKEN_AVAILABLE = _ENC is not None
+
+
+@dataclass(frozen=True)
+class TokenCount:
+    """A single token measurement and whether it is exact or a proxy."""
+
+    tokens: int
+    exact: bool
+
+
+def gpt_tokens(text: str) -> TokenCount:
+    """GPT token count — exact via tiktoken when present, else a char proxy."""
+    if _ENC is not None:
+        return TokenCount(len(_ENC.encode(text)), True)
+    return TokenCount(round(len(text) / _GPT_CHARS_PER_TOKEN), False)
+
+
+def claude_tokens(text: str) -> TokenCount:
+    """Claude token count — documented offline proxy (no local tokenizer)."""
+    return TokenCount(round(len(text) / _CLAUDE_CHARS_PER_TOKEN), False)
+
+
+def measure(text: str) -> dict[str, object]:
+    """Return chars + per-model token counts for one text blob.
+
+    Keys: chars, tokens_gpt, tokens_gpt_exact, tokens_claude,
+    tokens_claude_exact. The `*_exact` booleans tell a report consumer
+    whether the number is a real tokenizer count or a proxy estimate.
+    """
+    g = gpt_tokens(text)
+    c = claude_tokens(text)
+    return {
+        "chars": len(text),
+        "tokens_gpt": g.tokens,
+        "tokens_gpt_exact": g.exact,
+        "tokens_claude": c.tokens,
+        "tokens_claude_exact": c.exact,
+    }
+
+
+def method_note() -> str:
+    """One-line provenance of how token counts were produced (for reports)."""
+    if TIKTOKEN_AVAILABLE:
+        return (
+            f"tokens_gpt: exact (tiktoken {_TIKTOKEN_ENCODING}); "
+            f"tokens_claude: proxy (chars/{_CLAUDE_CHARS_PER_TOKEN})"
+        )
+    return (
+        f"tokens_gpt: proxy (chars/{_GPT_CHARS_PER_TOKEN}, tiktoken not installed); "
+        f"tokens_claude: proxy (chars/{_CLAUDE_CHARS_PER_TOKEN})"
+    )

package/scripts/_lib/value_report.py

@@ -333,9 +333,9 @@ def assemble_value_v1(
         "totals": totals,
         "notes": [
             (
-                "Token→€ conversion priced at "
-                f"{tier} rates from internal/bench/pricing.yaml "
-                f"(sourced_on={ref.get('pricing_sourced_on', '—')})."
+                "Cost is reported in tokens only — no € figure. Per-call API "
+                "pricing misleads subscription users; tokens are the "
+                "currency-neutral metric."
             ),
             "Pending rungs contribute 0 to the cumulative until measured.",
             (

package/scripts/ai-video/adapters/higgsfield.sh

@@ -51,7 +51,49 @@ aiv_higgsfield_capability() {
       "$(higgsfield_audio_for_preset "${preset}")" "${preset}"
     return 0
   fi
-  printf '{"audio":"per-model","presets":["mix","burst","dvd","cinematic","talk"]}\n'
+  printf '{"audio":"per-model","presets":["mix","burst","dvd","cinematic","talk"],"speak":true}\n'
+}
+
+# --- live helpers -----------------------------------------------------
+# Higgsfield API (authoritative contract — official higgsfield-js SDK):
+#   base   https://platform.higgsfield.ai
+#   auth   Authorization: Key <KEY_ID>:<KEY_SECRET>  (api-key + api-key-secret)
+#   upload POST /api/v1/upload_file  (multipart)        -> hosted image URL
+#   submit POST /v1/image2video/dop                     -> { request_id, status_url }
+#   poll   GET  /requests/<id>/status                   -> { status, video:{url} }
+# Fields tagged ASSUMED are documented-best-effort and verified on the
+# first live smoke (this adapter has no captured smoke trace yet).
+HF_BASE_DEFAULT="https://platform.higgsfield.ai"
+
+_hf_secret() {
+  _aiv_xpath "(/ai-video/provider[@id='${ADAPTER_ID}']|/ai-video/extra/provider[@id='${ADAPTER_ID}'])/api-key-secret"
+}
+
+# Documented base; honour AIV_ENDPOINT only when it points at the
+# platform host (the XML default api.higgsfield.ai/v1 is not the SDK base).
+_hf_base() {
+  case "${AIV_ENDPOINT:-}" in
+    *platform.higgsfield.ai*) printf '%s' "${AIV_ENDPOINT%/}" | sed -E 's#/v1/?$##' ;;
+    *) printf '%s' "${HF_BASE_DEFAULT}" ;;
+  esac
+}
+
+_hf_auth() {
+  local secret; secret="$(_hf_secret)"
+  [ -n "${secret}" ] || aiv_die 6 "${ADAPTER_ID}: api-key-secret missing in agents/.ai-video.xml"
+  command -v aiv_redact_register >/dev/null 2>&1 && aiv_redact_register "${secret}"
+  printf 'Authorization: Key %s:%s' "${AIV_KEY}" "${secret}"
+}
+
+# image2video needs a DoP video model; the XML default may carry an
+# image model (e.g. higgsfield-soul) — fall back to dop-turbo and warn.
+_hf_model() {
+  case "${AIV_MODEL:-}" in
+    *dop*|*turbo*) printf '%s' "${AIV_MODEL}" ;;
+    *) printf 'dop-turbo'
+       printf '%s: XML model "%s" is not a DoP video model; using dop-turbo for image2video\n' \
+         "${ADAPTER_ID}" "${AIV_MODEL:-unset}" >&2 ;;
+  esac
 }
 
 aiv_cmd_submit() {
@@ -60,29 +102,144 @@ aiv_cmd_submit() {
   aiv_load_provider "${ADAPTER_ID}"
   [ "$(aiv_key_status)" = "present" ] \
     || aiv_die 6 "${ADAPTER_ID}: api key missing in agents/.ai-video.xml"
-  aiv_die 9 "${ADAPTER_ID}: live submit not yet wired"
+
+  local stdin_json base auth model ref img_url prompt req resp http body rid
+  stdin_json="$(cat)"
+  base="$(_hf_base)"; auth="$(_hf_auth)"; model="$(_hf_model)"
+
+  # image2video must animate a still — require ref_images[0].
+  ref="$(printf '%s' "${stdin_json}" | jq -r '.ref_images[0] // empty')"
+  [ -n "${ref}" ] || aiv_die 7 "${ADAPTER_ID}: image2video requires ref_images[0] (the still to animate)"
+
+  case "${ref}" in
+    http://*|https://*) img_url="${ref}" ;;
+    *)
+      case "${ref}" in /*) : ;; *) ref="$(pwd)/${ref}" ;; esac
+      [ -f "${ref}" ] || aiv_die 7 "${ADAPTER_ID}: ref image not found: ${ref}"
+      # Upload local still -> hosted URL. Multipart field name ASSUMED 'file'.
+      local up up_code up_body
+      up="$(curl -sS -w '\n%{http_code}' -X POST "${base}/api/v1/upload_file" \
+        -H "${auth}" -F "file=@${ref}")" \
+        || aiv_die 8 "${ADAPTER_ID}: upload_file curl failed"
+      up_code="$(printf '%s' "${up}" | tail -n1)"; up_body="$(printf '%s' "${up}" | sed '$d')"
+      case "${up_code}" in 2*) : ;; *) aiv_die 8 "${ADAPTER_ID}: upload HTTP ${up_code}: $(printf '%s' "${up_body}" | head -c 200)" ;; esac
+      img_url="$(printf '%s' "${up_body}" | jq -r '.url // .image_url // .file_url // .data.url // empty')"
+      [ -n "${img_url}" ] || aiv_die 8 "${ADAPTER_ID}: no URL in upload response (got: $(printf '%s' "${up_body}" | head -c 200))"
+      ;;
+  esac
+
+  # DoP wants a camera-movement prompt, not the full scene prose.
+  prompt="$(printf '%s' "${stdin_json}" | jq -r '
+    [.prompt.camera, .prompt.action, .prompt.mood]
+    | map(select(. != null and . != "")) | join(". ")')"
+  [ -n "${prompt}" ] || prompt="Cinematic camera movement"
+
+  # Live API wraps the request in a "params" object (verified: a flat
+  # body returns 422 'body.params required'; params requires prompt +
+  # input_images). model lives inside params.
+  req="$(jq -n --arg m "${model}" --arg p "${prompt}" --arg u "${img_url}" \
+    '{params:{model:$m, prompt:$p, input_images:[{type:"image_url", image_url:$u}]}}')"
+
+  resp="$(curl -sS -w '\n%{http_code}' -X POST "${base}/v1/image2video/dop" \
+    -H "${auth}" -H "Content-Type: application/json" --data-binary "${req}")" \
+    || aiv_die 8 "${ADAPTER_ID}: image2video curl failed"
+  http="$(printf '%s' "${resp}" | tail -n1)"; body="$(printf '%s' "${resp}" | sed '$d')"
+  case "${http}" in 2*) : ;; *) aiv_die 8 "${ADAPTER_ID}: submit HTTP ${http}: $(printf '%s' "${body}" | jq -r '.detail // .error // .message // "unknown"' 2>/dev/null | head -c 300)" ;; esac
+
+  rid="$(printf '%s' "${body}" | jq -r '.request_id // .generation_id // .id // empty')"
+  [ -n "${rid}" ] || aiv_die 8 "${ADAPTER_ID}: no request_id in submit response (got: $(printf '%s' "${body}" | head -c 200))"
+  jq -n --arg id "${rid}" '{job_id:$id}'
+}
+
+# Reconstruct the status URL from the request id (status_url also returned by submit).
+_hf_status_json() {
+  local job_id="${1}" base auth resp http body
+  base="$(_hf_base)"; auth="$(_hf_auth)"
+  resp="$(curl -sS -w '\n%{http_code}' -X GET "${base}/requests/${job_id}/status" -H "${auth}")" \
+    || aiv_die 8 "${ADAPTER_ID}: status curl failed"
+  http="$(printf '%s' "${resp}" | tail -n1)"; body="$(printf '%s' "${resp}" | sed '$d')"
+  case "${http}" in 2*) : ;; *) aiv_die 8 "${ADAPTER_ID}: status HTTP ${http}" ;; esac
+  printf '%s' "${body}"
 }
 
 aiv_cmd_poll() {
   local job_id="${1:-}"
   [ -n "${job_id}" ] || aiv_die 2 "${ADAPTER_ID}: poll <job_id> required"
   aiv_assert_dryrun
-  aiv_die 9 "${ADAPTER_ID}: live poll not yet wired (job=${job_id})"
+  aiv_require_cmd curl jq
+  aiv_load_provider "${ADAPTER_ID}"
+  local st; st="$(_hf_status_json "${job_id}" | jq -r '.status // empty')"
+  case "${st}" in
+    completed|done|success)          printf '{"status":"done"}\n' ;;
+    queued)                          printf '{"status":"queued"}\n' ;;
+    in_progress|running|processing)  printf '{"status":"running"}\n' ;;
+    failed|nsfw|canceled|cancelled)  printf '{"status":"failed","reason":"%s"}\n' "${st}" ;;
+    *)                               printf '{"status":"running","raw":"%s"}\n' "${st:-unknown}" ;;
+  esac
 }
 
 aiv_cmd_fetch() {
   local job_id="${1:-}"
   [ -n "${job_id}" ] || aiv_die 2 "${ADAPTER_ID}: fetch <job_id> required"
   aiv_assert_dryrun
-  aiv_die 9 "${ADAPTER_ID}: live fetch not yet wired (job=${job_id})"
+  aiv_require_cmd curl jq
+  aiv_load_provider "${ADAPTER_ID}"
+  local body url out
+  body="$(_hf_status_json "${job_id}")"
+  url="$(printf '%s' "${body}" | jq -r '.video.url // .results.raw.url // .video_url // (.images[0].url) // empty')"
+  [ -n "${url}" ] || aiv_die 8 "${ADAPTER_ID}: no video url in status (status=$(printf '%s' "${body}" | jq -r '.status // "?"'))"
+  out="${AIV_OUT:-}"; [ -n "${out}" ] || out="$(mktemp -t aiv-hf-XXXXXX).mp4"
+  curl -sS -L -o "${out}" "${url}" || aiv_die 8 "${ADAPTER_ID}: download failed: ${url}"
+  case "${out}" in /*) : ;; *) out="$(pwd)/${out}" ;; esac
+  jq -n --arg p "${out}" '{video_path:$p, audio_embedded:false}'
+}
+
+# aiv_cmd_speak — audio-driven lip-sync. Stdin JSON:
+#   {input_image: <url>, input_audio: <wav url>, prompt: <string>}
+# Animates the portrait's mouth to the supplied vocal WAV via
+# POST /v1/speak/higgsfield. Returns {job_id}; poll/fetch are shared.
+# Image + audio MUST be public URLs (the platform upload endpoint is
+# WAF-gated for non-browser clients). Audio must be WAV.
+aiv_cmd_speak() {
+  aiv_assert_dryrun
+  aiv_require_cmd curl jq
+  aiv_load_provider "${ADAPTER_ID}"
+  [ "$(aiv_key_status)" = "present" ] \
+    || aiv_die 6 "${ADAPTER_ID}: api key missing in agents/.ai-video.xml"
+  local stdin_json base auth img aud prompt req resp http body rid
+  stdin_json="$(cat)"
+  base="$(_hf_base)"; auth="$(_hf_auth)"
+  img="$(printf '%s' "${stdin_json}" | jq -r '.input_image // .image_url // (.ref_images[0]?) // empty')"
+  aud="$(printf '%s' "${stdin_json}" | jq -r '.input_audio // .audio_url // empty')"
+  prompt="$(printf '%s' "${stdin_json}" | jq -r 'if (.prompt|type)=="string" then .prompt else empty end')"
+  [ -n "${prompt}" ] || prompt="sing the line with force, mouth moving precisely to the words"
+  [ -n "${img}" ] || aiv_die 7 "${ADAPTER_ID}: speak requires input_image (public URL)"
+  [ -n "${aud}" ] || aiv_die 7 "${ADAPTER_ID}: speak requires input_audio (public WAV URL)"
+  case "${img}" in http://*|https://*) : ;; *) aiv_die 7 "${ADAPTER_ID}: speak input_image must be a public URL (local upload is WAF-gated)" ;; esac
+  case "${aud}" in http://*|https://*) : ;; *) aiv_die 7 "${ADAPTER_ID}: speak input_audio must be a public WAV URL" ;; esac
+  req="$(jq -n --arg i "${img}" --arg a "${aud}" --arg p "${prompt}" \
+    '{params:{input_image:{type:"image_url",image_url:$i},input_audio:{type:"audio_url",audio_url:$a},prompt:$p}}')"
+  resp="$(curl -sS -w '\n%{http_code}' -X POST "${base}/v1/speak/higgsfield" \
+    -H "${auth}" -H "Content-Type: application/json" --data-binary "${req}")" \
+    || aiv_die 8 "${ADAPTER_ID}: speak curl failed"
+  http="$(printf '%s' "${resp}" | tail -n1)"; body="$(printf '%s' "${resp}" | sed '$d')"
+  case "${http}" in 2*) : ;; *) aiv_die 8 "${ADAPTER_ID}: speak HTTP ${http}: $(printf '%s' "${body}" | jq -r '.detail // .error // .message // "unknown"' 2>/dev/null | head -c 300)" ;; esac
+  rid="$(printf '%s' "${body}" | jq -r '.id // .request_id // empty')"
+  [ -n "${rid}" ] || aiv_die 8 "${ADAPTER_ID}: speak: no request_id (got: $(printf '%s' "${body}" | head -c 200))"
+  jq -n --arg id "${rid}" '{job_id:$id}'
 }
 
-# Custom dispatch with capability override; falls back to the common
-# router for every other subcommand.
+# Custom dispatch: capability + speak handled here; submit/poll/fetch/
+# run/dry-run fall through to the common router.
 sub="${1:-}"
 if [ "${sub}" = "capability" ]; then
   shift
   aiv_higgsfield_capability "$@"
   exit 0
 fi
+if [ "${sub}" = "speak" ]; then
+  shift
+  aiv_cmd_speak "$@"
+  exit 0
+fi
 aiv_dispatch "${ADAPTER_ID}" "per-model" "$@"