[docs] Document DGX Spark (GB10) local perf benchmarking + baseline follow-up

Adds a GB10 section to performance_benchmarks.md: the single-benchmark run
command, the local stability-check workflow, reference figures, and the
baseline-seeding follow-up (scheduled-main GB10 runner or a scoped,
maintainer-approved manual calibration that preserves the existing safeguards).

Addresses review feedback on #1679.

.agents/lessons/2026-05-07_conversion-cast-bf16-suffix-allowlist.md

@@ -52,8 +52,8 @@ in one commit.
    script that supports a global dtype downcast flag MUST own an explicit
    allowlist of fp32-keep tensors, documented at the top of the file.
 
-2. **Check two things** for any converter that ships a `--cast-bf16`-style
-   flag:
+2. **The `add-model-conversion` skill** should enforce two checks for any
+   converter that ships a `--cast-bf16`-style flag:
    - Run the parity test for **every** variant of the model (base, distill,
      SR, etc.), not just the headline variant. Different variants exercise
      different code paths.

.agents/lessons/2026-05-07_dit-dtype-boundary-with-flash-attn.md

@@ -62,10 +62,10 @@ parity rationale:
 2. **Use layer-by-layer activation hooks** when DiT parity is close-but-not-
    bit-exact and the gap grows with depth. The
    `fastvideo/hooks/activation_trace.py` infra exists exactly for this case
-   (see `docs/contributing/activation_trace.md`). In MagiHuman's case it would have localized the
+   (`add-model-trace` skill). In MagiHuman's case it would have localized the
    first divergence point in one pass.
 
-3. **DiT ports must account for:**
+3. **The `add-model-port-dit` skill** should explicitly call out:
    - SDPA input dtype must match the upstream kernel's internal cast.
    - Post-attention upcast happens **before** any per-head gate, not after.
    - Residual stream dtype across block boundaries is a parity invariant.

.agents/lessons/2026-05-07_silent-channel-major-packing-bugs.md

@@ -64,5 +64,6 @@ because both sides of the parity check are now correct.
    `(pT pH pW C)`) at the call site and assert the layout matches the
    downstream consumer's expectation.
 
-4. DiT parity for any model that does video token packing should include an
-   E2E hash check, not just latent bit-exactness.
+4. The `add-model-port-dit` skill's parity gate should require an E2E hash
+   check for any DiT that does video token packing, not just latent
+   bit-exactness.

.agents/lessons/2026-09-29_streaming-ipc-semaphore-enoent.md

@@ -1,66 +0,0 @@
----
-date: 2026-09-29
-experiment: Wan-VACE multi-GPU inference on shared Slurm nodes
-category: infrastructure
-severity: important
----
-
-# Spawn workers fail with ENOENT in `SemLock._rebuild`
-
-## What Happened
-
-On Slurm nodes, standard `VideoGenerator` runs with the `mp` executor sometimes
-failed during worker startup. A spawn child raised `FileNotFoundError` from
-`multiprocessing.synchronize.SemLock._rebuild` while unpickling its arguments,
-even though the parent still held its Queue objects. Failures showed up on
-several nodes and looked intermittent.
-
-## Root Cause
-
-The cluster's Slurm epilog `80-epilog-cleanup-shm-tmp.sh` runs
-`find /dev/shm -maxdepth 2 -user "$SLURM_JOB_USER" -delete` at the end of
-**every** job. When one of a user's jobs ends, the epilog deletes that user's
-`/dev/shm` files on the node, including those that the user's *other* running
-jobs are still using. Python's POSIX named semaphores (`/dev/shm/sem.mp-*`) are
-among them. If the deletion lands between queue creation and a spawn child
-unpickling it, the child fails with ENOENT.
-
-Evidence:
-
-- **Timing.** Every recorded deletion burst during a probe job matched, to the
-  second, the end of another job by the same user on the same node
-  (`sacct -u $USER -N <node>` end times).
-- **Controlled reproduction.**
-  - Job A held a spawn `Lock` semaphore and a marker file in `/dev/shm`.
-  - Job B, on the same node, started and then ended.
-  - Job B's start deleted nothing.
-  - Within 1 s of job B's end, both of job A's objects were gone, and job A's
-    finalizer then hit the same ENOENT.
-- **Still unexplained.** One historical failure has no same-user job
-  end in its window, so another deleter cannot be ruled out for it. logind
-  `RemoveIPC` was the earlier hypothesis; it is not needed to explain the other
-  cases.
-
-## Fix / Workaround
-
-- **FastVideo hardening.** Standard inference no longer creates the two
-  streaming queues it never uses. `FastVideoArgs.enable_streaming_ipc_queues`
-  defaults to `False`, and `StreamingVideoGenerator` sets it to `True`. This
-  removes the exposure for standard inference only.
-- **Still exposed.** Streaming queues, NCCL shared-memory segments, and
-  DataLoader shared memory on the same node can still be deleted by the epilog.
-- **Cluster fix (administrators).** Clean `/dev/shm` only when the user has no
-  other job on the node, or give each job a private `/dev/shm` with
-  `JobContainerType=job_container/tmpfs`.
-- **User workaround.** Don't co-locate your own jobs on one node
-  (`--exclusive=user`), or avoid ending short jobs next to long-running ones.
-
-## Prevention
-
-- Before blaming an application for `/dev/shm` ENOENT on Slurm, read the
-  node-local prolog/epilog hooks (`/cm/local/apps/slurm/var/{prologs,epilogs}`).
-  Then correlate the failure window with `sacct -u $USER -N <node>` job end
-  times.
-- Do not pass IPC primitives to spawn workers unless the worker needs them.
-- `fastvideo/tests/worker/test_multiproc_executor.py` checks that standard
-  workers survive semaphore removal during spawn.

.agents/skills/add-model-01-prep/SKILL.md

@@ -0,0 +1,173 @@
+---
+name: add-model-01-prep
+description: Use at the start of a FastVideo model port to gather required inputs, inspect/download HF weights, clone and install the official reference repo in the current environment, create a local_tests README skeleton, and produce a handoff before conversion or implementation.
+---
+
+# Add Model Prep
+
+## Goal
+
+Prepare external assets and the shared parity-test environment for a FastVideo
+model port. Stop before writing conversion scripts, model components, pipeline
+code, registry entries, or executable parity tests.
+
+## Ask First
+
+Ask once, then proceed if the HF token is already exported:
+
+```text
+Before prep: (1) official reference repo or Diffusers pipeline URL, (2) HF repo
+id or local weights path and whether it has a root model_index.json, (3) target
+model_family, (4) workload types, (5) which token env var is exported:
+HF_TOKEN, HUGGINGFACE_HUB_TOKEN, or HF_API_KEY, (6) may I stage clone and
+weights under the FastVideo repo root, and (7) may I install official reference
+dependencies into the current FastVideo conda/env for parity tests?
+```
+
+Useful optional inputs: `pipeline_class`, `reference_dir`, `hf_revision`,
+`official_revision`, `reuse_hints`, `download_scope`.
+
+## Rules
+
+- Follow `../add-model/shared/common_rules.md` for token/auth safety, state files,
+  escape hatches, and skip/pass semantics.
+- Run from the FastVideo repo root.
+- Use repo-relative defaults: `<ReferenceDir>/`,
+  `official_weights/<model_family>/`, `converted_weights/<model_family>/`.
+- Install official reference deps into the current FastVideo environment, not a
+  new venv/conda env, so parity tests run both implementations with one shared
+  numeric stack.
+- If the reference is a Diffusers class/package instead of a cloneable repo,
+  record import path and version instead of cloning.
+- Prep may create only the local-test README and `PORT_STATUS.md` skeletons;
+  executable `.py` parity tests belong to `../add-model-02-parity/SKILL.md`.
+
+## Escape Hatches
+
+Follow `../add-model/shared/common_rules.md`. Prep-specific ask cases include
+overwriting an existing clone or weight directory, installing untrusted/private
+deps, choosing between incompatible official references, large downloads outside
+the agreed scope, or missing gated-repo auth setup by env var name.
+
+## Workflow
+
+1. Verify the repo:
+
+```bash
+git rev-parse --show-toplevel
+```
+
+Expected markers: `fastvideo/`, `scripts/checkpoint_conversion/`,
+`scripts/huggingface/download_hf.py`, `fastvideo/registry.py`.
+
+2. Inspect HF or local weight layout:
+
+```bash
+python ".agents/skills/add-model-01-prep/scripts/inspect_hf_layout.py" \
+    "Org/Model" \
+    --revision "<revision>" \
+    --json
+```
+
+For a local path, replace `Org/Model` with `/path/to/weights`. Record
+`source_layout`, `needs_conversion`, `model_index_class`, and
+`components_seen`.
+
+3. Download HF weights if needed:
+
+```bash
+python ".agents/skills/add-model-01-prep/scripts/download_hf_weights.py" \
+    "Org/Model" \
+    "official_weights/<model_family>" \
+    --revision "<revision>"
+```
+
+For selected files, repeat `--file-name`. For partial snapshots, repeat
+`--allow-pattern` or `--ignore-pattern`. If the user provided a local path,
+record it instead of copying large weights by default.
+
+4. Clone the official reference repo if applicable:
+
+```bash
+python ".agents/skills/add-model-01-prep/scripts/clone_reference_repo.py" \
+    "<official_repo_url>" \
+    "<ReferenceDir>" \
+    --branch "<tag-or-branch>" \
+    --commit "<commit-sha>" \
+    --update-gitignore
+```
+
+Omit `--branch`, `--commit`, or `--update-gitignore` when not needed. The
+helper refuses to overwrite existing paths and prints remote/HEAD instead.
+
+5. Keep prep assets ignored. Ensure `.gitignore` includes relevant entries:
+
+```gitignore
+/<ReferenceDir>/
+/official_weights/
+/converted_weights/
+```
+
+6. Follow the official repo's setup instructions in the current environment.
+Inspect dependency files and README install docs before installing anything:
+
+- `README*`, install docs, or model-card instructions.
+- `requirements*.txt`, `pyproject.toml`, `setup.py`, `environment.yml`.
+
+Use the current FastVideo conda/env. Do not create a new env even if upstream
+docs recommend one; translate the needed install commands into the active env.
+Prefer editable/no-deps first so the official source is importable without
+changing shared pins:
+
+```bash
+uv pip install --no-deps -e ./<ReferenceDir>
+```
+
+Then install only missing official deps needed for parity imports. Stop before
+installing requirements that would change FastVideo's core stack. If upstream
+requires private/non-PyPI deps, record that parity needs a local stub helper
+rather than pretending setup is complete.
+
+7. Create the model-family local test skeleton and top-level port state file:
+
+```bash
+mkdir -p tests/local_tests/<model_family>
+cp ".agents/skills/add-model-01-prep/templates/local_tests_readme.md" \
+    tests/local_tests/<model_family>/README.md
+cp ".agents/skills/add-model-01-prep/templates/port_status.md" \
+    tests/local_tests/<model_family>/PORT_STATUS.md
+```
+
+Edit every placeholder in the README and `PORT_STATUS.md`. The README gives
+later review agents enough information to reproduce the shared environment and
+run/review parity work:
+
+- official code URL or import path, local clone path, and commit/version;
+- HF URL or local weight path, revision, access notes, and token env var name
+  only;
+- commands already run and any blocked official dependency installs;
+- shared-env install commands to re-run without changing core pins;
+- expected local parity test paths and pytest commands;
+- private-dependency stubs or known setup gaps;
+- PR/review notes explaining which parity tests are required before handoff.
+
+Do not include raw tokens, absolute cache paths that are not repo-reproducible,
+or large generated outputs. If prep is blocked before imports work, still create
+the README with `official_env_status=blocked` and the exact blocker.
+
+`PORT_STATUS.md` must follow `../add-model/contracts/port_state.md`. Record open
+questions and prep issues immediately, using stable IDs such as `Q001` and
+`I001`. Keep resolved questions/issues in the table with a resolution instead of
+deleting them.
+
+## Handoff
+
+End with the canonical prep handoff contract from
+`../add-model/contracts/prep_handoff.md` and update the shared state files before
+handoff.
+
+## Helper Scripts
+
+- `scripts/inspect_hf_layout.py`: classify HF/local layout.
+- `scripts/download_hf_weights.py`: download HF snapshot or selected files.
+- `scripts/clone_reference_repo.py`: clone reference repo safely.

.agents/skills/add-model-01-prep/scripts/clone_reference_repo.py

@@ -0,0 +1,119 @@
+#!/usr/bin/env python3
+"""Clone an official reference repo without overwriting existing paths."""
+
+from __future__ import annotations
+
+import argparse
+import subprocess
+import sys
+from pathlib import Path
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Clone a reference repo for FastVideo parity tests.")
+    parser.add_argument("repo_url", help="Official reference repository URL")
+    parser.add_argument("target_dir", help="Directory to clone into")
+    parser.add_argument("--branch", help="Branch or tag to clone")
+    parser.add_argument("--commit", help="Commit SHA to check out after clone")
+    parser.add_argument(
+        "--update-gitignore",
+        action="store_true",
+        help="Add the target directory to .gitignore if missing",
+    )
+    parser.add_argument(
+        "--gitignore",
+        default=".gitignore",
+        help="Path to gitignore file when --update-gitignore is used",
+    )
+    return parser.parse_args()
+
+
+def run(command: list[str], check: bool = True) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        command,
+        check=check,
+        text=True,
+        capture_output=True,
+    )
+
+
+def print_existing_repo_info(target: Path) -> int:
+    print(f"target_exists: {target}")
+    if not (target / ".git").exists():
+        print("error: target exists but is not a git repo", file=sys.stderr)
+        return 1
+
+    remote = run(["git", "-C", str(target), "remote", "-v"], check=False)
+    head = run(["git", "-C", str(target), "rev-parse", "HEAD"], check=False)
+    if remote.stdout:
+        print("remote_v:")
+        print(remote.stdout.rstrip())
+    if head.stdout:
+        print(f"head: {head.stdout.strip()}")
+    print("not_overwritten: true")
+    return 0
+
+
+def gitignore_entry_for(target: Path) -> str:
+    root = Path.cwd().resolve()
+    resolved = target.resolve()
+    try:
+        relative = resolved.relative_to(root)
+    except ValueError as exc:
+        raise ValueError("--update-gitignore requires target_dir to be under the current directory") from exc
+
+    text = relative.as_posix().rstrip("/")
+    return "/" + text + "/"
+
+
+def update_gitignore(path: Path, target: Path) -> bool:
+    entry = gitignore_entry_for(target)
+    existing = path.read_text().splitlines() if path.exists() else []
+    if entry in existing:
+        return False
+
+    new_text = "\n".join(existing).rstrip("\n")
+    if new_text:
+        new_text += "\n"
+    new_text += entry + "\n"
+    path.write_text(new_text)
+    return True
+
+
+def main() -> int:
+    args = parse_args()
+    target = Path(args.target_dir)
+
+    if target.exists():
+        return print_existing_repo_info(target)
+
+    command = ["git", "clone", "--depth", "1"]
+    if args.branch:
+        command.extend(["--branch", args.branch])
+    command.extend([args.repo_url, str(target)])
+
+    try:
+        run(command)
+        if args.commit:
+            run(["git", "-C", str(target), "fetch", "--depth", "1", "origin", args.commit])
+            run(["git", "-C", str(target), "checkout", args.commit])
+    except subprocess.CalledProcessError as exc:
+        if exc.stdout:
+            print(exc.stdout, end="")
+        if exc.stderr:
+            print(exc.stderr, end="", file=sys.stderr)
+        return exc.returncode
+
+    head = run(["git", "-C", str(target), "rev-parse", "HEAD"])
+    print(f"cloned: {target}")
+    print(f"head: {head.stdout.strip()}")
+
+    if args.update_gitignore:
+        changed = update_gitignore(Path(args.gitignore), target)
+        print(f"gitignore_updated: {str(changed).lower()}")
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

.agents/skills/add-model-01-prep/scripts/download_hf_weights.py

@@ -0,0 +1,103 @@
+#!/usr/bin/env python3
+"""Download HF weights using the standard FastVideo token env vars."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from pathlib import Path
+
+HF_TOKEN_ENV_KEYS = ("HF_TOKEN", "HUGGINGFACE_HUB_TOKEN", "HF_API_KEY")
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Download a HF model snapshot or selected files into a local directory.")
+    parser.add_argument("repo_id", help="HF repo id, for example Org/Model")
+    parser.add_argument("local_dir", help="Destination directory")
+    parser.add_argument("--repo-type", default="model", help="HF repo type (default: model)")
+    parser.add_argument("--revision", help="HF branch, tag, or commit")
+    parser.add_argument(
+        "--file-name",
+        action="append",
+        default=[],
+        help="Download one file; may be repeated. If omitted, download full snapshot.",
+    )
+    parser.add_argument(
+        "--allow-pattern",
+        action="append",
+        default=[],
+        help="Snapshot allow pattern; may be repeated. Ignored when --file-name is used.",
+    )
+    parser.add_argument(
+        "--ignore-pattern",
+        action="append",
+        default=[],
+        help="Snapshot ignore pattern; may be repeated. Ignored when --file-name is used.",
+    )
+    return parser.parse_args()
+
+
+def resolve_token() -> tuple[str | None, str | None]:
+    for key in HF_TOKEN_ENV_KEYS:
+        value = os.environ.get(key)
+        if value:
+            return key, value
+    return None, None
+
+
+def main() -> int:
+    args = parse_args()
+    token_env, token = resolve_token()
+    local_dir = Path(args.local_dir).expanduser()
+
+    if token_env:
+        print(f"token_env: {token_env}")
+    else:
+        print("token_env: none", file=sys.stderr)
+
+    try:
+        if local_dir.exists() and not local_dir.is_dir():
+            print(
+                f"error: destination exists and is not a directory: {local_dir}",
+                file=sys.stderr,
+            )
+            return 1
+        local_dir.mkdir(parents=True, exist_ok=True)
+        if args.file_name:
+            from huggingface_hub import hf_hub_download
+
+            for file_name in args.file_name:
+                path = hf_hub_download(
+                    repo_id=args.repo_id,
+                    filename=file_name,
+                    repo_type=args.repo_type,
+                    revision=args.revision,
+                    local_dir=str(local_dir),
+                    token=token,
+                )
+                print(f"downloaded_file: {path}")
+        else:
+            from huggingface_hub import snapshot_download
+
+            path = snapshot_download(
+                repo_id=args.repo_id,
+                repo_type=args.repo_type,
+                revision=args.revision,
+                local_dir=str(local_dir),
+                token=token,
+                allow_patterns=args.allow_pattern or None,
+                ignore_patterns=args.ignore_pattern or None,
+            )
+            print(f"downloaded_snapshot: {path}")
+    except Exception as exc:  # noqa: BLE001 - CLI should print concise failures.
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+
+    print(f"local_dir: {local_dir.resolve()}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

.agents/skills/add-model-01-prep/scripts/inspect_hf_layout.py

@@ -0,0 +1,260 @@
+#!/usr/bin/env python3
+"""Inspect a Hugging Face repo or local weight directory layout."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+from typing import Any
+
+HF_TOKEN_ENV_KEYS = ("HF_TOKEN", "HUGGINGFACE_HUB_TOKEN", "HF_API_KEY")
+RAW_WEIGHT_SUFFIXES = (".safetensors", ".pt", ".pth", ".ckpt", ".bin")
+KNOWN_COMPONENTS = {
+    "audio_vae",
+    "conditioner",
+    "feature_extractor",
+    "image_encoder",
+    "scheduler",
+    "text_encoder",
+    "text_encoder_2",
+    "tokenizer",
+    "tokenizer_2",
+    "transformer",
+    "transformer_2",
+    "unet",
+    "upsampler",
+    "vae",
+    "vocoder",
+}
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Classify a HF repo or local directory as Diffusers, raw, custom, or unknown.")
+    parser.add_argument("source", help="HF repo id or local weights directory")
+    parser.add_argument("--repo-type", default="model", help="HF repo type (default: model)")
+    parser.add_argument("--revision", help="HF revision to inspect")
+    parser.add_argument(
+        "--max-local-files",
+        type=int,
+        default=20000,
+        help="Maximum local files to scan recursively (default: 20000)",
+    )
+    parser.add_argument(
+        "--sample-limit",
+        type=int,
+        default=80,
+        help="Number of file paths to print in human output (default: 80)",
+    )
+    parser.add_argument("--json", action="store_true", help="Emit JSON only")
+    return parser.parse_args()
+
+
+def resolve_token() -> tuple[str | None, str | None]:
+    for key in HF_TOKEN_ENV_KEYS:
+        value = os.environ.get(key)
+        if value:
+            return key, value
+    return None, None
+
+
+def load_local_files(root: Path, max_files: int) -> tuple[list[str], bool]:
+    files: list[str] = []
+    truncated = False
+    for path in root.rglob("*"):
+        if not path.is_file():
+            continue
+        files.append(path.relative_to(root).as_posix())
+        if len(files) >= max_files:
+            truncated = True
+            break
+    return sorted(files), truncated
+
+
+def load_local_model_index(root: Path) -> tuple[dict[str, Any] | None, str | None]:
+    index_path = root / "model_index.json"
+    if not index_path.is_file():
+        return None, None
+    try:
+        return json.loads(index_path.read_text()), None
+    except Exception as exc:  # noqa: BLE001 - surface malformed JSON clearly.
+        return None, f"failed to parse local model_index.json: {exc}"
+
+
+def load_remote_files(
+    repo_id: str,
+    repo_type: str,
+    revision: str | None,
+    token: str | None,
+) -> list[str]:
+    from huggingface_hub import list_repo_files
+
+    return sorted(list_repo_files(
+        repo_id,
+        repo_type=repo_type,
+        revision=revision,
+        token=token,
+    ))
+
+
+def load_remote_model_index(
+    repo_id: str,
+    repo_type: str,
+    revision: str | None,
+    token: str | None,
+) -> tuple[dict[str, Any] | None, str | None]:
+    from huggingface_hub import hf_hub_download
+
+    try:
+        path = hf_hub_download(
+            repo_id=repo_id,
+            filename="model_index.json",
+            repo_type=repo_type,
+            revision=revision,
+            token=token,
+        )
+    except Exception as exc:  # noqa: BLE001 - missing/inaccessible file is data.
+        return None, f"failed to download model_index.json: {exc}"
+
+    try:
+        return json.loads(Path(path).read_text()), None
+    except Exception as exc:  # noqa: BLE001 - surface malformed JSON clearly.
+        return None, f"failed to parse remote model_index.json: {exc}"
+
+
+def root_file_names(files: list[str]) -> set[str]:
+    return {name for name in files if "/" not in name}
+
+
+def component_names(files: list[str], model_index: dict[str, Any] | None) -> list[str]:
+    components: set[str] = set()
+    for name in files:
+        parts = name.split("/", 1)
+        if len(parts) != 2:
+            continue
+        top, rest = parts
+        if top in KNOWN_COMPONENTS or rest == "config.json":
+            components.add(top)
+
+    if model_index:
+        for key, value in model_index.items():
+            if key.startswith("_"):
+                continue
+            if isinstance(value, list) and len(value) == 2:
+                components.add(key)
+
+    return sorted(components)
+
+
+def classify_layout(
+    files: list[str],
+    model_index: dict[str, Any] | None,
+    components: list[str],
+) -> tuple[str, str]:
+    roots = root_file_names(files)
+    raw_weight_files = [name for name in roots if name.endswith(RAW_WEIGHT_SUFFIXES)]
+    has_model_index = "model_index.json" in roots or model_index is not None
+
+    if has_model_index and components:
+        return "diffusers", "no"
+    if has_model_index:
+        return "custom", "unknown"
+    if raw_weight_files:
+        return "raw_official", "yes"
+    if any(name.endswith(RAW_WEIGHT_SUFFIXES) for name in files):
+        return "custom", "yes"
+    return "unknown", "unknown"
+
+
+def build_result(args: argparse.Namespace) -> dict[str, Any]:
+    token_env, token = resolve_token()
+    source_path = Path(args.source).expanduser()
+    is_local = source_path.exists()
+
+    if is_local:
+        root = source_path.resolve()
+        if not root.is_dir():
+            raise ValueError(f"local source is not a directory: {root}")
+        files, truncated = load_local_files(root, args.max_local_files)
+        model_index, model_index_error = load_local_model_index(root)
+        source_kind = "local"
+        source = str(root)
+    else:
+        files = load_remote_files(args.source, args.repo_type, args.revision, token)
+        truncated = False
+        model_index, model_index_error = load_remote_model_index(
+            args.source,
+            args.repo_type,
+            args.revision,
+            token,
+        )
+        source_kind = "hf"
+        source = args.source
+
+    components = component_names(files, model_index)
+    source_layout, needs_conversion = classify_layout(files, model_index, components)
+
+    return {
+        "source": source,
+        "source_kind": source_kind,
+        "repo_type": None if is_local else args.repo_type,
+        "revision": args.revision,
+        "token_env": token_env,
+        "source_layout": source_layout,
+        "needs_conversion": needs_conversion,
+        "model_index_class": (model_index or {}).get("_class_name"),
+        "model_index_diffusers_version": (model_index or {}).get("_diffusers_version"),
+        "model_index_error": model_index_error,
+        "components_seen": components,
+        "file_count": len(files),
+        "file_scan_truncated": truncated,
+        "files_sample": files[:args.sample_limit],
+    }
+
+
+def print_human(result: dict[str, Any]) -> None:
+    for key in (
+            "source",
+            "source_kind",
+            "repo_type",
+            "revision",
+            "token_env",
+            "source_layout",
+            "needs_conversion",
+            "model_index_class",
+            "model_index_diffusers_version",
+            "model_index_error",
+            "file_count",
+            "file_scan_truncated",
+    ):
+        value = result.get(key)
+        if value is not None:
+            print(f"{key}: {value}")
+
+    components = result["components_seen"]
+    print("components_seen: " + (", ".join(components) if components else "none"))
+    print("files_sample:")
+    for name in result["files_sample"]:
+        print(f"  {name}")
+
+
+def main() -> int:
+    args = parse_args()
+    try:
+        result = build_result(args)
+    except Exception as exc:  # noqa: BLE001 - CLI should print concise failures.
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+
+    if args.json:
+        print(json.dumps(result, indent=2, sort_keys=True))
+    else:
+        print_human(result)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

.agents/skills/add-model-01-prep/templates/local_tests_readme.md

@@ -0,0 +1,122 @@
+# <Model Family> Local Tests
+
+Local-only parity and smoke tests for the `<model_family>` FastVideo port. These
+tests compare FastVideo against the official reference implementation and are
+not expected to run in CI unless explicitly promoted later.
+
+Port progress, open questions, issues, and handoff notes live in
+`tests/local_tests/<model_family>/PORT_STATUS.md`.
+
+## Reference Assets
+
+| Field | Value |
+|---|---|
+| Model family | `<model_family>` |
+| Workload types | `<T2V/I2V/V2V/T2I/or compatibility shim with rationale>` |
+| Official reference | `<url or import path>` |
+| Local reference dir | `<ReferenceDir or none>` |
+| Official commit/version | `<sha, tag, package version, or unknown>` |
+| HF weights | `<HF repo id/url or local path>` |
+| HF revision | `<revision or default>` |
+| Local weights dir | `<official_weights/model_family or local path>` |
+| Source layout | `<diffusers/raw_official/monolithic/separate_components/mixed/custom/unknown>` |
+| Needs conversion | `<yes/no/unknown>` |
+
+Do not write token values in this file. Use only the token env var name:
+`<HF_TOKEN or HUGGINGFACE_HUB_TOKEN or HF_API_KEY>`.
+
+## Shared Environment Setup
+
+Run from the FastVideo repo root in the same conda/env used for FastVideo.
+Do not create a separate upstream environment for parity tests.
+
+```bash
+# Official reference source, if cloneable.
+python ".agents/skills/add-model-01-prep/scripts/clone_reference_repo.py" \
+    "<official_repo_url>" \
+    "<ReferenceDir>" \
+    --commit "<commit-sha>" \
+    --update-gitignore
+
+# Editable install without changing shared core pins.
+uv pip install --no-deps -e ./<ReferenceDir>
+
+# Additional official deps installed or required for imports:
+# <package list or none>
+```
+
+Do not change core dependency versions (`torch`, `diffusers`, `transformers`,
+`flash-attn`, `triton`, CUDA packages) without explicit approval.
+
+## Official Environment Status
+
+```text
+dependency_changes: <none | installed no-deps editable | installed official deps in current env | blocked on user>
+official_env_status: <imports_ok | private_deps_need_stubs | blocked>
+private_dep_stubs: <none or tests/local_tests/helpers/<model_family>_upstream.py>
+blocked_on: <none or exact blocker>
+```
+
+## Weight Setup
+
+```bash
+python ".agents/skills/add-model-01-prep/scripts/download_hf_weights.py" \
+    "<Org/Model>" \
+    "official_weights/<model_family>" \
+    --revision "<revision>"
+```
+
+If weights are local-only, record the local path and do not copy large files into
+the repository.
+
+## Prototype And Conversion Artifacts
+
+State-dict key/shape dumps are generated after FastVideo native prototypes exist
+and are used to build the conversion mapping.
+
+```text
+official_key_dumps:
+  <component>: converted_weights/<model_family>/_mapping/<component>_official_keys.json
+fastvideo_key_dumps:
+  <component>: converted_weights/<model_family>/_mapping/<component>_fastvideo_keys.json
+conversion_script: scripts/checkpoint_conversion/<model_family>_to_diffusers.py
+conversion_source_layout: <diffusers | separate_components | monolithic | mixed | custom>
+converted_weights_dir: converted_weights/<model_family>
+strict_load_status: <not_run | pass | pass_with_documented_exclusions | blocked>
+```
+
+For monolithic official checkpoints, record the component prefix split here. For
+example, a single checkpoint may contain transformer, VAE/pretransform,
+conditioner, and scheduler/vocoder keys that the conversion script writes into
+separate FastVideo component subfolders.
+
+## Expected Parity Tests
+
+Planned local tests for this family:
+
+| Component | Official files / args | Test | Concerns | Status |
+|---|---|---|---|---|
+| `<component>` | `<definition path; instantiation path + args>` | `tests/local_tests/<bucket>/test_<model_family>_<component>_parity.py` | `<prototype or setup concerns>` | `<planned/scaffold_skip/debug_red/non_skip_pass/blocked>` |
+| `pipeline` | `<official pipeline call>` | `tests/local_tests/pipelines/test_<model_family>_pipeline_parity.py` | `<pipeline concerns>` | `<planned/scaffold_skip/debug_red/non_skip_pass/blocked>` |
+
+Include reused components in this table. Reuse is accepted only after the
+FastVideo component definition and official instantiation arguments have both
+been checked and the component parity test passes non-skip.
+
+Run the relevant tests with:
+
+```bash
+pytest tests/local_tests/<bucket>/test_<model_family>_<component>_parity.py -v -s
+pytest tests/local_tests/pipelines/test_<model_family>_pipeline_parity.py -v -s
+```
+
+## Review Notes
+
+- Required before handoff: non-skip PASS for each required component parity
+  test, including reused components that own weights or numerical behavior.
+- Pipeline parity may start as a scaffold, but final handoff requires non-skip
+  PASS or an explicit blocker accepted through the escape-hatch process.
+- User decisions and pause points are tracked as `E###` rows in
+  `PORT_STATUS.md`; do not rely on chat history for escape-hatch context.
+- Review agents should verify this README's setup commands still match the PR,
+  then run the listed parity tests or report the exact blocker.

.agents/skills/add-model-01-prep/templates/port_status.md

@@ -0,0 +1,69 @@
+# <Model Family> Port Status
+
+## Summary
+
+- model_family: `<model_family>`
+- workload_types: `<T2V/I2V/V2V/T2I/or compatibility shim with rationale>`
+- official_ref: `<url or import path>`
+- official_ref_dir: `<ReferenceDir or none>`
+- hf_weights_path: `<HF repo id/url or local path>`
+- local_weights_dir: `<official_weights/model_family or local path>`
+- source_layout: `<diffusers/raw_official/monolithic/separate_components/mixed/custom/unknown>`
+- local_tests_readme: `tests/local_tests/<model_family>/README.md`
+
+## Current Phase
+
+- phase: `prep`
+- status: `in_progress`
+- owner: `prep`
+- last_updated: `<YYYY-MM-DD>`
+
+## Component Matrix
+
+| Component | Type | Reuse/Port | Official Definition | Official Instantiation | FastVideo Target | Prototype | Conversion | Parity | Open Issues |
+|---|---|---|---|---|---|---|---|---|---|
+| `<component>` | `<dit/vae/encoder/generic>` | `<unknown/reuse/port>` | `<path + symbols>` | `<path + args>` | `<target files>` | `<not_started/in_progress/pass/blocked>` | `<not_started/pass/blocked>` | `<not_started/scaffold_skip/debug_red/non_skip_pass/blocked>` | `<none or IDs>` |
+
+## Conversion State
+
+- conversion_script: `scripts/checkpoint_conversion/<model_family>_to_diffusers.py`
+- converted_weights_dir: `converted_weights/<model_family>`
+- source_layout: `<diffusers/separate_components/monolithic/mixed/custom/unknown>`
+- strict_load_status: `not_run`
+- passthrough_components: `<none or list>`
+- retry_history: `<none>`
+
+## Parity Commands
+
+| Scope | Command | Last Result | Notes |
+|---|---|---|---|
+| component | `pytest tests/local_tests/<bucket>/test_<model_family>_<component>_parity.py -v -s` | `not_run` | `<notes>` |
+| pipeline | `pytest tests/local_tests/pipelines/test_<model_family>_pipeline_parity.py -v -s` | `not_run` | `<notes>` |
+
+## Open Questions
+
+| ID | Question | Owner | Needed By Phase | Status | Resolution |
+|---|---|---|---|---|---|
+| Q001 | `<question>` | `<owner>` | `<phase>` | `<open/resolved>` | `<resolution or blank>` |
+
+## Issues And Blockers
+
+| ID | Phase | Component | Severity | Issue | Evidence | Owner | Status | Resolution |
+|---|---|---|---|---|---|---|---|---|
+| I001 | `<phase>` | `<component or all>` | `<low/medium/high/blocker>` | `<issue>` | `<logs/paths/commands>` | `<owner>` | `<open/resolved>` | `<resolution or blank>` |
+
+## Escape Hatches
+
+| ID | Phase | Decision Type | Question | Recommended Option | Status | Resolution |
+|---|---|---|---|---|---|---|
+| E001 | `<phase>` | `<scope/dependency/auth/cost/destructive/ambiguity/blocker>` | `<one precise question>` | `<safe recommended option>` | `<open/resolved>` | `<resolution or blank>` |
+
+## Decisions
+
+| Date | Decision | Rationale | Impact |
+|---|---|---|---|
+| `<YYYY-MM-DD>` | `<decision>` | `<why>` | `<affected components/phases>` |
+
+## Handoff Notes
+
+- `<short notes for the next agent>`

.agents/skills/add-model-02-parity/SKILL.md

@@ -0,0 +1,234 @@
+---
+name: add-model-02-parity
+description: Use during /add-model after reference/architecture study to scaffold and later activate local FastVideo component parity tests. Emphasizes early test creation, official-reference loading, standardized FastVideo loading, and non-skip handoff gates.
+---
+
+# Add Model Parity
+
+## Goal
+
+Create parity tests as early as possible in a FastVideo port. The first pass can
+land before conversion or component implementation as an executable scaffold;
+handoff is blocked until the same tests become non-skip PASS with real weights.
+
+## When To Run
+
+Follow `../add-model/shared/common_rules.md` for token/auth safety, state files,
+escape hatches, and skip/pass semantics.
+
+Run immediately after `/add-model` Phase 1 has identified:
+
+- official component classes and call signatures;
+- FastVideo target component buckets/classes/configs;
+- local reference clone or import path from `add-model-01-prep`;
+- local raw or Diffusers weight path;
+- `official_env_status=imports_ok`, or private deps that will be stubbed
+  locally in tests;
+- `local_tests_readme` documenting setup and planned review/test commands;
+- expected component inputs and output tensors.
+
+Do not wait for all FastVideo components to be implemented. Write the tests
+first, then let component-porting subagents make them pass.
+
+## Outputs
+
+- One component parity test per required component, including reused components:
+  `tests/local_tests/<bucket>/test_<family>_<component>_parity.py`.
+- Optional helper for upstream private deps:
+  `tests/local_tests/helpers/<family>_upstream.py`.
+- Pipeline parity is owned later by `../add-model-09-pipeline/SKILL.md` after all
+  component parity tests pass non-skip.
+- A parity status block for the `/add-model` parity verification phase.
+
+## Early Scaffold Rules
+
+- A scaffold may skip while the FastVideo class, converted weights, or official
+  import is missing.
+- A scaffold must already encode the real official load path, FastVideo load
+  path, deterministic inputs, expected output extraction, and tolerance target.
+- Each parity test must declare its coverage scope in the file docstring or a
+  module constant: `production_loader`, `implementation_subcomponent`, or `both`.
+  Implementation/subcomponent parity may bypass production loaders deliberately,
+  but final handoff still needs production-loader coverage somewhere before the
+  pipeline depends on that component.
+- Official reference imports must run in the current FastVideo environment; do
+  not create or assume a separate upstream venv/conda env.
+- A scaffold is not evidence of correctness. It becomes evidence only after a
+  local non-skip PASS.
+- Prefer env-var path overrides with repo-relative defaults.
+- Keep tests local-only under `tests/local_tests/`; package/CI quality tests are
+  added later.
+- Update shared state files as described in
+  `../add-model/shared/common_rules.md` whenever adding or activating parity
+  tests.
+
+## Component Template
+
+Copy `templates/component_parity_test.py` and fill every `TODO` marker. The
+template is distilled from:
+
+- `tests/local_tests/transformers/test_ltx2.py`
+- `tests/local_tests/transformers/test_gamecraft_parity.py`
+- `tests/local_tests/encoders/test_ltx2_gemma_parity.py`
+- `tests/local_tests/vaes/test_oobleck_vae_parity.py`
+- `tests/local_tests/sd35/test_sd35_component_parity.py`
+
+The template supports three states:
+
+| State | Meaning |
+|---|---|
+| Scaffold skip | Test is committed early, but official import, FastVideo class, or weights are not available yet. |
+| Debug red | Both sides load and the test fails numerically. This is useful: porting can chase the first drift. |
+| Non-skip pass | Required before `/add-model` handoff. |
+
+## Subagent Dispatch Pattern
+
+After Phase 1, dispatch one parity subagent per component before or alongside
+component implementation:
+
+```text
+Create a local parity test scaffold for <family> <component>.
+
+Use the prep handoff:
+- official_ref_dir/import: <...>
+- local_weights_dir: <...>
+- source_layout: <...>
+- needs_conversion: <yes/no>
+- official_env_status: <imports_ok | private_deps_need_stubs>
+- local_tests_readme: tests/local_tests/<model_family>/README.md
+- port_state_file: tests/local_tests/<model_family>/PORT_STATUS.md
+- official_definition_files: <paths + classes/functions>
+- official_instantiation_files: <paths + factory/pipeline/config call sites + args>
+- concerns_or_unknowns: <known ambiguous inputs, outputs, deps, or args>
+
+The complete per-component packet must match
+`../add-model/contracts/component_context.md`.
+
+Read the official component call path and the planned FastVideo component API.
+Add tests/local_tests/<bucket>/test_<family>_<component>_parity.py based on
+add-model-02-parity/templates/component_parity_test.py.
+
+The scaffold must load the official model with real weights when available,
+load the FastVideo model through the standardized config/class/loader path when
+available, create deterministic inputs, compare concrete outputs, and skip only
+when a dependency is genuinely missing. Do not make an unconditional skip or a
+shape-only test.
+```
+
+## FastVideo Load Patterns
+
+Pick the narrowest load path that matches the component:
+
+| Component | Preferred FastVideo load path |
+|---|---|
+| DiT / transformer | Bucket config + model class, or `TransformerLoader` when testing converted Diffusers component dirs. |
+| VAE | VAE class `from_pretrained(...)` when implemented, or bucket config + class for local converted dirs. |
+| Text/image encoder | Bucket config + model class; pass HF subpaths from `local_weights_dir` or converted component dirs. |
+| Scheduler/conditioner | Native class/config plus exact official kwargs. |
+
+For early scaffolds, an import of the planned FastVideo class may be inside a
+helper that calls `pytest.skip` if the class does not exist yet. Replace that
+skip with a real import once the component PR adds the class.
+
+Direct class/config construction is allowed for implementation or subcomponent
+parity, such as connector-only encoder checks or official monolithic-checkpoint
+mapping tests. Label that scope explicitly and add separate production-loader
+coverage when converted component dirs are available.
+
+## Official Load Patterns
+
+- Clone/reference repo path: add its source dir to `sys.path` before imports.
+- HF/Diffusers reference: import only inside the test, not production code.
+- Private deps: add a helper under `tests/local_tests/helpers/` to install
+  stubs before importing upstream modules; do not rely on an external upstream
+  environment.
+- Gated HF repos: resolve `HF_TOKEN`, `HUGGINGFACE_HUB_TOKEN`, or `HF_API_KEY`
+  under the token rules in `../add-model/shared/common_rules.md`.
+
+## Non-Skip Activation Checklist
+
+Before `/add-model` handoff, each scaffolded test must be activated:
+
+```text
+[ ] Official side imports and loads real weights.
+[ ] FastVideo side imports and loads the converted or original weights.
+[ ] Test executes at least one real forward call on both sides.
+[ ] Test compares output tensors, not only shapes or state-dict keys.
+[ ] Local pytest output contains PASSED, not SKIPPED or XFAIL.
+[ ] Tolerance is justified for the component scope and kernel alignment.
+```
+
+## Component Parity Details
+
+Reference imports:
+
+- Import from `official_ref_dir` or the recorded package/import path.
+- If upstream has private deps, add a helper under
+  `tests/local_tests/helpers/<family>_upstream.py` that installs minimal stubs
+  before importing upstream modules.
+- Common stubs: identity compile/op-registration decorators, CP world size set to
+  1, identity scatter/gather, and test-friendly custom-op kernels.
+- Stub decorators that register `torch.ops.<ns>.<op>` must preserve the
+  `torch.library` registration side-effect. Identity decorators alone are not
+  enough.
+- Delete stub helpers and every `install_stubs()` call as soon as the real deps
+  become required installs. No-op shims are dead code.
+
+Kernel and wrapper pitfalls:
+
+- If parity routes flash-attn GQA through SDPA, expand KV heads manually on the
+  SDPA side with `repeat_interleave` along the head axis.
+- If upstream VAE `decode()` denormalizes internally but FastVideo/Diffusers
+  expects pre-denormalized latents, apply `z = z * std + mean` only on the
+  FastVideo side in the parity test.
+- Per-channel VAE `latents_mean` / `latents_std` must be reshaped explicitly,
+  e.g. `.view(1, z_dim, 1, 1, 1)` for 5D video latents.
+
+Tolerance guide:
+
+| Scope | Start `atol` / `rtol` | Notes |
+|---|---|---|
+| Single block, same kernel | `1e-4` / `1e-4` | Tight default. |
+| Full DiT, aligned kernels | `1e-2` / `1e-2` | Cross-layer accumulation. |
+| Full DiT, cross-kernel bf16 | `0.1` / `0.1` | Also require abs-mean drift below 5% and per-modality diagnostics. |
+| VAE decode fp32 | `5e-2` / `5e-2` | After normalization alignment. |
+| Encoder wrapper around same HF class | `1e-3` / `1e-3` | Should be near-zero. |
+
+Element-wise `assert_close` alone is not enough for deep full-DiT parity. Also
+log global abs-mean drift and per-modality summaries.
+
+When a non-skip component parity run is numerically red after weight/input
+checks, invoke `../add-model-08-trace/SKILL.md` before adding bespoke forward
+hooks. Use `docs/contributing/activation_trace.md` to keep
+`FASTVIDEO_TRACE_LAYERS`, `FASTVIDEO_TRACE_STATS`, and `FASTVIDEO_TRACE_STEPS`
+identical across FastVideo and upstream traces.
+
+Useful local commands:
+
+```bash
+pytest tests/local_tests/<bucket>/test_<family>_*parity*.py -v -s
+pytest tests/local_tests -k "<family> and parity" -v -s
+```
+
+## Escape Hatches
+
+Follow `../add-model/shared/common_rules.md`. Parity-specific ask cases include
+private dependency approval, choosing between incompatible official references,
+accepting a shape-only substitute, or loosening required tolerances.
+
+## Pipeline Parity
+
+Pipeline parity is later than component parity because it needs stages, presets,
+registry wiring, converted weights, and green component parity. Record official
+pipeline call notes in `local_tests_readme`, but do not treat pipeline parity as
+owned by this skill.
+
+Use `../add-model-09-pipeline/SKILL.md` and its
+`templates/pipeline_parity_test.py` for pipeline parity scaffolding and
+debugging. Compare denoised latents or decoded media, not just successful
+generation.
+
+## Handoff Status Block
+
+Return `../add-model/contracts/parity_status.md` to `/add-model` and update the
+shared state files before handoff.

.agents/skills/add-model-02-parity/templates/component_parity_test.py

@@ -0,0 +1,188 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Component parity scaffold for <FAMILY> <COMPONENT>.
+
+This file is intended to be created early in a port. It may skip until the
+official reference, FastVideo class, and real weights are available, but it must
+never become an unconditional skip or shape-only test.
+
+Fill every TODO before considering this test active.
+"""
+from __future__ import annotations
+
+import importlib
+import os
+from pathlib import Path
+import sys
+
+import pytest
+import torch
+from torch.testing import assert_close
+
+os.environ.setdefault("MASTER_ADDR", "localhost")
+os.environ.setdefault("MASTER_PORT", "29519")
+os.environ.setdefault("DISABLE_SP", "1")
+os.environ.setdefault("FASTVIDEO_ATTENTION_BACKEND", "TORCH_SDPA")
+
+REPO_ROOT = Path(__file__).resolve().parents[3]
+FAMILY = "<family>"  # TODO: snake_case family name.
+COMPONENT = "<component>"  # TODO: transformer | vae | encoder | conditioner | ...
+PARITY_SCOPE = "implementation_subcomponent"  # TODO: production_loader | implementation_subcomponent | both
+OFFICIAL_MODULE = "<official.module>"  # TODO: e.g. "ltx_core.model.transformer".
+OFFICIAL_CLASS = "<OfficialClass>"  # TODO: official class/factory name.
+FASTVIDEO_CONFIG_MODULE = "fastvideo.configs.models.<bucket>"  # TODO.
+FASTVIDEO_CONFIG_CLASS = "<FastVideoConfig>"  # TODO.
+FASTVIDEO_MODEL_MODULE = "fastvideo.models.<bucket>.<module>"  # TODO.
+FASTVIDEO_MODEL_CLASS = "<FastVideoModel>"  # TODO.
+
+OFFICIAL_REF_DIR = Path(os.getenv("<FAMILY_UPPER>_OFFICIAL_REF_DIR", REPO_ROOT / "<ReferenceDir>"))
+LOCAL_WEIGHTS_DIR = Path(os.getenv("<FAMILY_UPPER>_LOCAL_WEIGHTS_DIR", REPO_ROOT / "official_weights" / FAMILY))
+CONVERTED_WEIGHTS_DIR = Path(os.getenv("<FAMILY_UPPER>_CONVERTED_WEIGHTS_DIR",
+                                       REPO_ROOT / "converted_weights" / FAMILY))
+
+
+def _resolve_hf_token() -> str | None:
+    for key in ("HF_TOKEN", "HUGGINGFACE_HUB_TOKEN", "HF_API_KEY"):
+        value = os.environ.get(key)
+        if value:
+            return value
+    return None
+
+
+def _add_official_to_path() -> None:
+    """Add the official source path before importing upstream modules."""
+    # TODO: adjust for the official repo layout. Common examples:
+    # OFFICIAL_REF_DIR / "src"
+    # OFFICIAL_REF_DIR / "packages" / "<pkg>" / "src"
+    # OFFICIAL_REF_DIR
+    official_src = OFFICIAL_REF_DIR / "src"
+    if not official_src.exists():
+        official_src = OFFICIAL_REF_DIR
+    if official_src.exists() and str(official_src) not in sys.path:
+        sys.path.insert(0, str(official_src))
+
+
+def _import_or_skip(module_name: str, attr_name: str | None = None):
+    if "<" in module_name or (attr_name is not None and "<" in attr_name):
+        pytest.skip(f"Template import placeholder not filled: {module_name}.{attr_name}")
+    try:
+        module = importlib.import_module(module_name)
+    except Exception as exc:  # noqa: BLE001 - local parity should skip missing refs.
+        pytest.skip(f"Cannot import {module_name}: {exc}")
+    if attr_name is None:
+        return module
+    try:
+        return getattr(module, attr_name)
+    except AttributeError:
+        pytest.skip(f"{module_name} has no attribute {attr_name}")
+
+
+def _load_official_model(device: torch.device, dtype: torch.dtype) -> torch.nn.Module:
+    """Load the official component with real weights."""
+    _add_official_to_path()
+    if not OFFICIAL_REF_DIR.exists():
+        pytest.skip(f"Official reference missing: {OFFICIAL_REF_DIR}")
+    if not LOCAL_WEIGHTS_DIR.exists():
+        pytest.skip(f"Local weights missing: {LOCAL_WEIGHTS_DIR}")
+
+    # TODO: import official class/factory and load real weights strictly.
+    # Examples in-tree:
+    # - LTX2: SingleGPUModelBuilder(...).build(device=device, dtype=dtype)
+    # - GameCraft: torch.load(...)["module"] -> official_model.load_state_dict(...)
+    # - Oobleck: create_model_from_config(config) + ckpt state_dict
+    OfficialClass = _import_or_skip(OFFICIAL_MODULE, OFFICIAL_CLASS)
+    model = OfficialClass()  # TODO: pass official config kwargs.
+    state_dict = {}  # TODO: load official state dict from LOCAL_WEIGHTS_DIR.
+    missing, unexpected = model.load_state_dict(state_dict, strict=True)
+    assert not missing and not unexpected, (f"official load mismatch missing={missing[:5]} unexpected={unexpected[:5]}")
+    return model.to(device=device, dtype=dtype).eval()
+
+
+def _load_fastvideo_model(device: torch.device, dtype: torch.dtype) -> torch.nn.Module:
+    """Load the FastVideo component with the same tensor content."""
+    if not CONVERTED_WEIGHTS_DIR.exists() and not LOCAL_WEIGHTS_DIR.exists():
+        pytest.skip(f"No FastVideo loadable weights: {CONVERTED_WEIGHTS_DIR} or {LOCAL_WEIGHTS_DIR}")
+
+    # TODO: replace with the bucket-specific FastVideo config/class/loader.
+    # DiT examples:
+    #   from fastvideo.configs.models.dits import <Config>
+    #   from fastvideo.models.dits.<module> import <Model>
+    # VAE examples:
+    #   from fastvideo.models.vaes.<module> import <VAE>
+    #   model = <VAE>.from_pretrained(...)
+    FastVideoConfig = _import_or_skip(FASTVIDEO_CONFIG_MODULE, FASTVIDEO_CONFIG_CLASS)
+    FastVideoModel = _import_or_skip(FASTVIDEO_MODEL_MODULE, FASTVIDEO_MODEL_CLASS)
+
+    config = FastVideoConfig()
+    model = FastVideoModel(config=config)
+    state_dict = {}  # TODO: load converted or directly mapped state dict.
+    missing, unexpected = model.load_state_dict(state_dict, strict=True)
+    assert not missing and not unexpected, (
+        f"FastVideo load mismatch missing={missing[:5]} unexpected={unexpected[:5]}")
+    return model.to(device=device, dtype=dtype).eval()
+
+
+def _make_inputs(device: torch.device, dtype: torch.dtype) -> dict[str, torch.Tensor]:
+    """Create deterministic inputs matching the official component call."""
+    torch.manual_seed(0)
+    # TODO: replace with component-specific tensors and metadata.
+    return {
+        "hidden_states": torch.randn(1, 4, 16, device=device, dtype=dtype),
+        "timestep": torch.tensor([10], device=device),
+    }
+
+
+def _run_official(model: torch.nn.Module, inputs: dict[str, torch.Tensor]) -> torch.Tensor:
+    """Run official component and return the tensor to compare."""
+    with torch.inference_mode():
+        output = model(**inputs)  # TODO: adapt official call signature.
+    if isinstance(output, dict):
+        sample = output.get("sample")
+        output = sample if sample is not None else output.get("x")
+    elif hasattr(output, "sample"):
+        output = output.sample
+    elif isinstance(output, tuple):
+        output = output[0]
+    assert torch.is_tensor(output), f"official output is not tensor: {type(output)}"
+    return output.detach().float().cpu()
+
+
+def _run_fastvideo(model: torch.nn.Module, inputs: dict[str, torch.Tensor]) -> torch.Tensor:
+    """Run FastVideo component and return the tensor to compare."""
+    with torch.inference_mode():
+        output = model(**inputs)  # TODO: adapt FastVideo call signature.
+    if isinstance(output, dict):
+        sample = output.get("sample")
+        output = sample if sample is not None else output.get("x")
+    elif hasattr(output, "sample"):
+        output = output.sample
+    elif isinstance(output, tuple):
+        output = output[0]
+    assert torch.is_tensor(output), f"FastVideo output is not tensor: {type(output)}"
+    return output.detach().float().cpu()
+
+
+@pytest.mark.skipif(not torch.cuda.is_available(), reason="CUDA required for this parity test.")
+def test_component_parity():
+    """Compare official and FastVideo outputs on identical inputs."""
+    device = torch.device("cuda:0")
+    dtype = torch.bfloat16
+
+    official = _load_official_model(device, dtype)
+    fastvideo = _load_fastvideo_model(device, dtype)
+    inputs = _make_inputs(device, dtype)
+
+    official_out = _run_official(official, inputs)
+    fastvideo_out = _run_fastvideo(fastvideo, inputs)
+
+    assert official_out.shape == fastvideo_out.shape
+    diff = (official_out - fastvideo_out).abs()
+    print(f"official abs_mean={official_out.abs().mean().item():.6f} "
+          f"fastvideo abs_mean={fastvideo_out.abs().mean().item():.6f} "
+          f"diff_max={diff.max().item():.6f} diff_mean={diff.mean().item():.6f}")
+
+    # TODO: pick tolerance by scope:
+    # - single block / same kernel: 1e-4
+    # - full DiT aligned kernels: 1e-2
+    # - full DiT cross-kernel bf16: 1e-1 + abs_mean drift check
+    # - VAE decode fp32: 5e-2 after normalization alignment
+    assert_close(fastvideo_out, official_out, atol=1e-4, rtol=1e-4)

.agents/skills/add-model-03-port-dit/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: add-model-03-port-dit
+description: Use during /add-model Phase 4 or Phase 6 to prototype or parity-debug one FastVideo-native DiT/transformer component.
+---
+
+# Add Model Port DiT
+
+## Goal
+
+Prototype or parity-debug one diffusion transformer in FastVideo-native code.
+This skill is for one component only; do not work on the VAE, encoders,
+pipeline, or unrelated conversion code unless the current component cannot load
+without a minimal fix there.
+
+## Inputs
+
+Follow `../add-model/shared/component_skill_common.md` and require the complete
+packet from `../add-model/contracts/component_context.md`.
+
+DiT-specific packet fields:
+
+- `component`: transformer or DiT name.
+- `parity_test`: `tests/local_tests/<bucket>/test_<family>_<component>_parity.py`.
+- `weights`: converted transformer dir or local official path.
+- `target_files`: `fastvideo/models/dits/<family>.py` and
+  `fastvideo/configs/models/dits/<family>.py`.
+
+## Modes
+
+Use the common prototype and parity-debug modes from
+`../add-model/shared/component_skill_common.md`.
+
+DiT-specific prototype concerns include ambiguous official flags, shape
+mismatches, missing FastVideo layer equivalents, and dedicated output heads.
+
+## Reuse Proof
+
+Apply the shared reuse proof. DiT-specific comparison must include attention
+algorithm, positional embeddings, RoPE/patching, timestep/guidance embeddings,
+scaling constants, dtype casts, state-dict names, and every output head.
+
+## Existing FastVideo Patterns
+
+- Base class: `fastvideo/models/dits/base.py::BaseDiT`.
+- Config bases: `DiTConfig` and `DiTArchConfig` in
+  `fastvideo/configs/models/dits/base.py`.
+- Use the matching DiT config bucket. Wrong bucket inheritance can typecheck but
+  fail during pipeline wiring.
+- Config export: add the config to
+  `fastvideo/configs/models/dits/__init__.py`.
+- Registry discovery: set `EntryClass = <ClassName>` in the model file.
+- Loader path: `TransformerLoader` reads `transformer/config.json`, calls
+  `dit_config.update_model_arch(config)`, resolves `_class_name` through
+  `ModelRegistry`, and constructs the class with `config` and `hf_config`.
+- Reference examples: `stable_audio.py`, `wanvideo.py`, `sd3.py`, `longcat.py`,
+  and `ltx2.py`.
+- Layer guidance: `fastvideo/layers/AGENTS.md`.
+
+## Implementation Rules
+
+- Use FastVideo-native layers by default: `ReplicatedLinear` for DiT hot-path
+  linears, `DistributedAttention` for standard full-sequence attention, and
+  `LocalAttention` for local/window attention or simple single-GPU parity paths.
+- Raw SDPA is acceptable for cross-modality flat streams when no FastVideo
+  distributed equivalent exists; document the SP gap in the module docstring.
+- Mirror official tensor contracts exactly: latent packing, patch ordering,
+  timestep embedding scale, RoPE/positional embedding, guidance embedding,
+  cross-attention context order, output head order, and dtype casts.
+- Preserve all output heads that the official DiT emits. Do not silently drop
+  audio, depth, pose, mask, or auxiliary heads.
+- Put architecture fields on `DiTArchConfig`; keep inference steps, CFG scales,
+  FPS, flow shift, and sampling defaults out of the arch config.
+- Define `_fsdp_shard_conditions`, `_compile_conditions`,
+  `param_names_mapping`, and `reverse_param_names_mapping` where needed.
+- Follow the production import boundary in
+  `../add-model/shared/common_rules.md`.
+
+## Prototype Checks
+
+Follow the shared prototype success criteria. A useful one-off check is:
+
+```bash
+python - <<'PY'
+# Import the target config/class, instantiate with random weights, and print
+# state_dict names/shapes for the conversion mapping.
+PY
+```
+
+## Parity-Debug Loop
+
+Run the shared parity-debug loop. The component test command is:
+
+```bash
+pytest <parity_test> -v -s
+```
+
+For numerical drift, use `../add-model-08-trace/SKILL.md` before writing bespoke
+hooks. Start with FastVideo's activation trace (`fastvideo/hooks/activation_trace.py`;
+`docs/contributing/activation_trace.md`) and a block-level regex such as
+`FASTVIDEO_TRACE_LAYERS="^block\.layers\.[0-9]+$"`. Only fall back to custom
+per-block hooks if the needed boundary or statistic is not exposed by
+`FASTVIDEO_TRACE_STATS`.
+
+## Escape Hatches
+
+Follow `../add-model/shared/common_rules.md` and the component-specific guidance
+in `../add-model/shared/component_skill_common.md`. DiT-specific ask cases include
+dropping an output head/modality, accepting an unsupported kernel/private op, or
+choosing between incompatible official transformer definitions.
+
+## Handoff
+
+Return `../add-model/contracts/component_skill_handoff.md` following the common
+handoff rules in `../add-model/shared/component_skill_common.md`.

.agents/skills/add-model-04-port-vae/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: add-model-04-port-vae
+description: Use during /add-model Phase 4 or Phase 6 to prototype or parity-debug one FastVideo-native VAE component.
+---
+
+# Add Model Port VAE
+
+## Goal
+
+Prototype or parity-debug one VAE or autoencoder in FastVideo-native code. This
+skill covers video, image, and audio VAEs.
+
+## Inputs
+
+Follow `../add-model/shared/component_skill_common.md` and require the complete
+packet from `../add-model/contracts/component_context.md`.
+
+VAE-specific packet fields:
+
+- `component`: VAE or autoencoder name.
+- `parity_test`: `tests/local_tests/vaes/test_<family>_<component>_parity.py`.
+- `weights`: converted VAE dir, HF subfolder, or local official path.
+- `target_files`: `fastvideo/models/vaes/<arch_or_family>.py` and
+  `fastvideo/configs/models/vaes/<arch_or_family>.py`.
+
+## Modes
+
+Use the common prototype and parity-debug modes from
+`../add-model/shared/component_skill_common.md`.
+
+VAE-specific prototype concerns include latent normalization, stochastic
+posterior behavior, tiling incompatibility, temporal/spatial/audio layout, and
+decode output containers.
+
+## Reuse Proof
+
+Apply the shared reuse proof. VAE-specific comparison must include latent layout,
+temporal/spatial/audio compression, scaling factor, mean/std normalization,
+posterior behavior, encode/decode output objects, tiling flags, and cropping.
+
+## Existing FastVideo Patterns
+
+- Shared tiling wrapper: `fastvideo/models/vaes/common.py::ParallelTiledVAE`.
+- Config bases: `VAEConfig` and `VAEArchConfig` in
+  `fastvideo/configs/models/vaes/base.py`.
+- Use the matching VAE config bucket. Wrong bucket inheritance can typecheck but
+  fail during pipeline wiring.
+- Config export: add the config to
+  `fastvideo/configs/models/vaes/__init__.py`.
+- Registry discovery: set `EntryClass = <ClassName>` in the model file.
+- Loader path: VAE loaders resolve `_class_name` through `ModelRegistry` and
+  load converted component weights from the VAE subdir.
+- Reference examples: `oobleck.py`, `autoencoder_kl.py`, `wanvae.py`,
+  `ltx2vae.py`, and `gamecraftvae.py`.
+- Layer guidance: `fastvideo/layers/AGENTS.md`.
+
+## Implementation Rules
+
+- Name reusable VAE architectures by architecture (`oobleck.py`,
+  `autoencoder_kl.py`); name family-specific VAEs by family.
+- Match official encode/decode contracts exactly: input layout, latent layout,
+  temporal/spatial/audio compression, scaling factor, mean/std normalization,
+  posterior sampling behavior, decode output object, and frame/sample cropping.
+- Compare deterministic outputs in parity: decode outputs, encode mean/mode, or
+  round-trip tensors. Do not compare stochastic samples unless the RNG path is
+  explicitly controlled.
+- Use FastVideo tiling only when it preserves official numerics for the tested
+  shape; disable it in config for audio or unsupported dimensions.
+- Put architecture constants on `VAEArchConfig`; put `load_encoder`,
+  `load_decoder`, tiling, dtype, and pretrained path fields on `VAEConfig`.
+- Follow the production import boundary in
+  `../add-model/shared/common_rules.md`.
+
+## Prototype Checks
+
+Follow the shared prototype success criteria.
+
+## Parity-Debug Loop
+
+Run the shared parity-debug loop. The component test command is:
+
+```bash
+pytest <parity_test> -v -s
+```
+
+For numerical drift, check normalization, latent scaling, posterior mode vs
+sample, channel order, and temporal/spatial/audio cropping before changing
+layers.
+
+## Escape Hatches
+
+Follow `../add-model/shared/common_rules.md` and the component-specific guidance
+in `../add-model/shared/component_skill_common.md`. VAE-specific ask cases include
+dropping an encode/decode path, accepting an unsupported private op, or choosing
+between incompatible official VAE definitions.
+
+## Handoff
+
+Return `../add-model/contracts/component_skill_handoff.md` following the common
+handoff rules in `../add-model/shared/component_skill_common.md`.

.agents/skills/add-model-05-port-encoder/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: add-model-05-port-encoder
+description: Use during /add-model Phase 4 or Phase 6 to prototype or parity-debug one FastVideo-native text, image, audio, or compound encoder component.
+---
+
+# Add Model Port Encoder
+
+## Goal
+
+Prototype or parity-debug one encoder or encoder-like conditioner in
+FastVideo-native code. Use this for text encoders, image encoders, audio
+encoders, and compound conditioners that fit the encoder config/loader bucket.
+
+## Inputs
+
+Follow `../add-model/shared/component_skill_common.md` and require the complete
+packet from `../add-model/contracts/component_context.md`.
+
+Encoder-specific packet fields:
+
+- `component`: encoder or encoder-like conditioner name.
+- `parity_test`: `tests/local_tests/encoders/test_<family>_<component>_parity.py`.
+- `weights`: converted encoder dir, HF subfolder, or external HF id.
+- `target_files`: `fastvideo/models/encoders/<arch_or_family>.py` and
+  `fastvideo/configs/models/encoders/<arch_or_family>.py`.
+
+## Modes
+
+Use the common prototype and parity-debug modes from
+`../add-model/shared/component_skill_common.md`.
+
+Encoder-specific prototype concerns include tokenizer kwargs, hidden-state
+extraction, output packing, connector order, and external/passthrough weight
+needs.
+
+## Reuse Proof
+
+Apply the shared reuse proof. Encoder-specific comparison must include tokenizer
+contracts, hidden-state extraction, masks, positional IDs, output packing,
+connector/projection ordering, passthrough paths, and returned dataclass shape.
+
+## Existing FastVideo Patterns
+
+- Base classes: `TextEncoder` and `ImageEncoder` in
+  `fastvideo/models/encoders/base.py`.
+- Output type: `BaseEncoderOutput`.
+- Config bases: `TextEncoderConfig`, `ImageEncoderConfig`,
+  `TextEncoderArchConfig`, and `ImageEncoderArchConfig` in
+  `fastvideo/configs/models/encoders/base.py`.
+- Use the matching encoder config bucket. Wrong bucket inheritance can typecheck
+  but fail during pipeline wiring.
+- Config export: add the config to
+  `fastvideo/configs/models/encoders/__init__.py`.
+- Registry discovery: set `EntryClass = <ClassName>` or a list of class names in
+  the model file.
+- Reference examples: native `t5.py`, `clip.py`, `siglip.py`, `llama.py`,
+  `qwen2_5.py`, `gemma.py`, and compound `stable_audio_conditioner.py`.
+- Layer guidance: `fastvideo/layers/AGENTS.md`.
+
+## Implementation Rules
+
+- Reuse tokenizers and pure data utilities when needed, but do not add runtime
+  third-party model-class imports as a placeholder for a component that owns
+  weights or numerical behavior.
+- For LLM-style encoders, follow existing tensor-parallel patterns such as
+  `QKVParallelLinear`, `MergedColumnParallelLinear`, `RowParallelLinear`,
+  `VocabParallelEmbedding`, and `RMSNorm` when matching native examples.
+- Match official hidden-state extraction exactly: layer index, pooled output,
+  attention mask dtype, padding side, truncation, special tokens, final norm,
+  output_hidden_states, and returned tuple/dataclass shape.
+- For connector or conditioner modules, preserve sub-conditioner order and the
+  exact packing of cross-attention tokens, masks, and global conditioning.
+- Put tokenizer kwargs and architecture constants on the arch config when they
+  affect numerical behavior.
+- If an external HF encoder is explicitly accepted as a lazy wrapper, keep it
+  isolated, document why it is not a native port, and still require parity for
+  the wrapper's output contract.
+
+Hybrid external-HF encoder checklist:
+
+- Put external model folders in passthrough subfolders such as
+  `text_encoder/<external_name>/`, or record a root `model_index.json` path field
+  that the loader resolves to a local directory.
+- Keep external model parameters out of the FastVideo-owned state-dict surface
+  when the external model is loaded lazily from its own HF files.
+- Convert and strict-check only the FastVideo-owned connector/projection weights;
+  document external model weights as passthrough.
+- Add parity for the wrapper's final output contract and, when useful, a narrower
+  connector-only parity test that labels its scope as
+  `implementation_subcomponent`.
+- Verify the production loader resolves the same external path used by the
+  pipeline, not just the direct class used in the parity test.
+
+## Prototype Checks
+
+Follow the shared prototype success criteria.
+
+## Parity-Debug Loop
+
+Run the shared parity-debug loop. The component test command is:
+
+```bash
+pytest <parity_test> -v -s
+```
+
+For numerical drift, check tokenization, masks, hidden-state selection,
+positional IDs, dtype/autocast, and output packing before changing layers.
+
+## Escape Hatches
+
+Follow `../add-model/shared/common_rules.md` and the component-specific guidance
+in `../add-model/shared/component_skill_common.md`. Encoder-specific ask cases
+include accepting private model-code execution, choosing between incompatible
+tokenizer/encoder references, or dropping a required conditioning stream.
+
+## Handoff
+
+Return `../add-model/contracts/component_skill_handoff.md` following the common
+handoff rules in `../add-model/shared/component_skill_common.md`.

.agents/skills/add-model-06-port-generic/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: add-model-06-port-generic
+description: Use during /add-model Phase 4 or Phase 6 to prototype or parity-debug one non-DiT, non-VAE, non-encoder FastVideo component.
+---
+
+# Add Model Port Generic
+
+## Goal
+
+Prototype or parity-debug one scheduler, conditioner, upsampler, vocoder,
+adapter, preprocessor, or unknown component in FastVideo-native code.
+
+## Inputs
+
+Follow `../add-model/shared/component_skill_common.md` and require the complete
+packet from `../add-model/contracts/component_context.md`.
+
+Generic-component packet fields:
+
+- `component`: component name.
+- `component_type`: scheduler, conditioner, upsampler, vocoder, adapter,
+  preprocessor, or unknown.
+- `parity_test`: `tests/local_tests/<bucket>/test_<family>_<component>_parity.py`.
+- `weights`: converted component dir, HF subfolder, or none.
+- `target_files`: matching `fastvideo/models/` and `fastvideo/configs/models/`
+  bucket files when applicable.
+
+## Modes
+
+Use the common prototype and parity-debug modes from
+`../add-model/shared/component_skill_common.md`.
+
+Generic-component prototype concerns include stateless/stateful ambiguity,
+missing loader buckets, source prefixes, mutable scheduler state, and output
+container shape.
+
+## Reuse Proof
+
+Apply the shared reuse proof. Generic-component comparison must include mutable
+state, scaling constants, scheduler/conditioner semantics, output containers, and
+whether the component owns state or is stateless.
+
+## Existing FastVideo Patterns
+
+- Schedulers live under `fastvideo/models/schedulers/` and expose `EntryClass`.
+- Upsamplers use `fastvideo/models/upsamplers/` plus configs under
+  `fastvideo/configs/models/upsamplers/`; see `hunyuan15.py`.
+- Vocoders and audio-specific modules can live under `fastvideo/models/audio/`
+  with configs under `fastvideo/configs/models/audio/`; see `ltx2_audio_vae.py`.
+- Compound conditioners may fit the encoder bucket when the pipeline loader uses
+  `ConditionerLoader`; see `stable_audio_conditioner.py`.
+- Registry discovery uses `EntryClass`; config bucket exports are required when
+  pipeline configs import them by bucket.
+- Use the narrowest matching config bucket. Wrong bucket inheritance can typecheck
+  but fail during pipeline wiring.
+- Layer guidance: `fastvideo/layers/AGENTS.md`.
+
+## Bucket Decision
+
+- If the component is a transformer/DiT, stop and use `add-model-03-port-dit`.
+- If the component is a VAE/autoencoder, stop and use `add-model-04-port-vae`.
+- If the component is a text/image/audio encoder or encoder-like conditioner,
+  stop and use `add-model-05-port-encoder` unless the loader requires a different
+  bucket.
+- Otherwise choose the narrowest existing bucket. Add a new bucket only when no
+  existing loader/config shape can represent the component without misleading
+  names or unsafe runtime behavior.
+
+## Implementation Rules
+
+- Match official behavior, not just shapes: constructor args, default values,
+  runtime flags, RNG use, dtype/autocast, scaling constants, masks, and output
+  containers all matter.
+- Keep the implementation minimal and native. Do not keep a runtime import of
+  the official implementation as the production component.
+- For schedulers, compare timesteps, sigmas/noise levels, step outputs, shift
+  handling, prediction type, and any mutable internal state.
+- For upsamplers, compare resize mode, align_corners, residual branches,
+  causal padding, normalization, and exact target-shape behavior.
+- For vocoders/audio components, compare waveform shape, sample-rate contract,
+  channel order, hop length, normalization, and dtype.
+- If private upstream deps are required only for tests, keep stubs under
+  `tests/local_tests/helpers/` and do not import them from production code.
+
+## Prototype Checks
+
+Follow the shared prototype success criteria.
+
+## Parity-Debug Loop
+
+Run the shared parity-debug loop. The component test command is:
+
+```bash
+pytest <parity_test> -v -s
+```
+
+For numerical drift, add targeted intermediate comparisons in the test to
+identify the first divergent operation.
+
+## Escape Hatches
+
+Follow `../add-model/shared/common_rules.md` and the component-specific guidance
+in `../add-model/shared/component_skill_common.md`. Generic-component ask cases
+include creating a new loader bucket, accepting an unsupported private op,
+choosing between incompatible official definitions, or dropping a required
+component.
+
+## Handoff
+
+Return `../add-model/contracts/component_skill_handoff.md` following the common
+handoff rules in `../add-model/shared/component_skill_common.md`.

.agents/skills/add-model-07-conversion/SKILL.md

@@ -0,0 +1,186 @@
+---
+name: add-model-07-conversion
+description: Use during /add-model Phase 5 to write and verify a FastVideo checkpoint conversion script after native component prototypes expose FastVideo state-dict keys/shapes.
+---
+
+# Add Model Conversion
+
+## Goal
+
+Convert official weights into a FastVideo-loadable component layout after Phase 4
+native prototypes exist. The conversion script owns parameter mapping, component
+splitting, passthrough assets, config emission, and strict-load verification.
+
+## Inputs
+
+Follow `../add-model/shared/common_rules.md` for token/auth safety, state files,
+escape hatches, production boundaries, and skip/pass semantics.
+
+Require the initial request from
+`../add-model/contracts/conversion_request.md`.
+
+If the FastVideo key/shape dump is missing, return to `/add-model` Phase 4. Do
+not write a final mapping against an unimplemented component.
+
+For Phase 6 retry requests from component skills, also require the retry shape
+from `../add-model/contracts/conversion_request.md`.
+
+## Output
+
+- `scripts/checkpoint_conversion/<family>_to_diffusers.py`.
+- `converted_weights/<family>/` with `model_index.json` and per-component
+  subfolders.
+- Updated `tests/local_tests/<model_family>/README.md` with conversion command,
+  source layout, output path, and strict-load status.
+- Updated `tests/local_tests/<model_family>/PORT_STATUS.md` with conversion
+  state, retry history, open questions, and issues/blockers.
+
+## Reference Scripts
+
+- `scripts/checkpoint_conversion/convert_ltx2_weights.py`: component prefix
+  splitting, metadata config extraction, passthrough Gemma/tokenizer assets, and
+  optional component-only output.
+- `scripts/checkpoint_conversion/stable_audio_to_diffusers.py`: monolithic
+  `model.safetensors` split into transformer/VAE/conditioner, plus copied
+  passthrough subfolders. Use this shape for single-checkpoint official repos.
+- `scripts/checkpoint_conversion/convert_gamecraft_full.py`: separate official
+  sources for transformer, VAE, text encoders, tokenizers, scheduler, and root
+  `model_index.json`.
+- `scripts/checkpoint_conversion/longcat_to_fastvideo.py`: fused QKV/KV split,
+  renamed native transformer weights, and copied existing Diffusers components.
+- `scripts/checkpoint_conversion/pt_to_safetensors.py`: simple `.pt` extraction
+  helper for nested checkpoint dictionaries.
+
+## Source Layout Decision
+
+Choose exactly one primary layout:
+
+| Layout | Conversion behavior |
+|---|---|
+| `diffusers` | Usually no tensor remap; verify configs/classes and copy or update `_class_name` only when needed. |
+| `raw_official` | Convert a raw official checkpoint file or directory. Choose explicit component ownership before writing output. |
+| `separate_components` | Convert/copy each component from its own file or directory. |
+| `monolithic` | Load one model checkpoint and split state dict by authoritative prefixes into component buckets. |
+| `mixed` | Convert some components and copy passthrough components such as tokenizers, text encoders, schedulers, or already-Diffusers VAE dirs. |
+| `custom` | Document why none of the above fits before writing conversion code. |
+
+Monolithic checkpoints need explicit prefix ownership. For example, Stable Audio
+uses one `model.safetensors` with DiT, pretransform/VAE, and conditioner keys;
+the converter splits those keys into FastVideo component subfolders and writes
+per-component configs.
+
+## Script Shape
+
+Start from `templates/family_to_diffusers.py` or the closest reference script.
+Keep the script explicit and reviewable:
+
+- `COMPONENT_SPECS` or `COMPONENT_PREFIXES` declares component ownership.
+- `PARAM_NAME_MAP` declares key renames.
+- `SKIP_PATTERNS` declares intentionally dropped training-only keys.
+- tensor split/fuse helpers are named by operation, e.g. `split_qkv`.
+- `build_component_configs(...)` writes loader-compatible config files. Most
+  model components use `config.json`; schedulers use `scheduler_config.json`.
+- `build_model_index(...)` writes a root `model_index.json` matching the target
+  FastVideo pipeline and component classes.
+- verification reports missing, unexpected, skipped, unchanged, renamed, and
+  shape-mismatched keys.
+
+`model_index.json` library tokens must match FastVideo loaders:
+
+- standard native DiT/VAE/audio/vocoder/upsampler components loaded by existing
+  Diffusers-style loaders usually use `"diffusers"` with a FastVideo
+  `_class_name` in the component `config.json`;
+- text encoders, tokenizers, image encoders, processors, and feature extractors
+  usually use `"transformers"`;
+- `conditioner` currently expects `"fastvideo"`;
+- use fully qualified `"fastvideo.<module>"` only when intentionally relying on
+  the custom fastvideo-library escape path;
+- do not write bare `"fastvideo"` for transformer, VAE, or other loaders that
+  expect `"diffusers"` unless the loader explicitly expects it.
+
+## Mapping Rules
+
+- Use Phase 4 key/shape dumps to derive mappings. Do not guess from official key
+  names alone.
+- Preserve each component's official file paths, parity test path, and prototype
+  concerns in comments or structured constants near the mapping that uses them.
+- Every official inference parameter should be mapped, copied through, or listed
+  as intentionally skipped with a reason.
+- Every FastVideo prototype parameter should receive a tensor or be listed as an
+  intentional external/passthrough parameter.
+- Shape matches are necessary but not sufficient; check semantic pairing for
+  Q/K/V, gate/up/down, norm scale/bias, LoRA/base, and modality-specific heads.
+- If official and FastVideo fuse or split tensors differently, convert tensors in
+  the script rather than changing production code to match checkpoint quirks.
+
+## Verification
+
+Run conversion locally, then verify before returning to Phase 6. For retry
+requests, update the mapping, rerun conversion, and refresh only the implicated
+converted component when safe; otherwise rerun the full conversion.
+
+```bash
+python scripts/checkpoint_conversion/<family>_to_diffusers.py \
+    --src <official_weights> \
+    --revision <hf_revision> \
+    --dst converted_weights/<model_family>
+```
+
+Omit `--revision` for local sources or when prep recorded `default` / `none`.
+
+Minimum output layout:
+
+```text
+converted_weights/<family>/
+  model_index.json
+  transformer/config.json
+  transformer/*.safetensors
+  vae/config.json
+  vae/*.safetensors
+  scheduler/scheduler_config.json as needed
+  text_encoder/... as needed
+```
+
+Required checks:
+
+- `model_index.json` exists and lists every required component.
+- Each converted component has the config filename its loader expects and
+  safetensors weights when it owns weights. Scheduler dirs require
+  `scheduler_config.json`; most other native model dirs use `config.json`.
+- Weight filenames may vary by loader: transformer and VAE loaders glob all
+  `*.safetensors`; text encoders may load `*.safetensors`, `*.bin`, and
+  sometimes `*.pt`; `conditioner` currently expects
+  `diffusion_pytorch_model.safetensors`. Use the loader's actual accepted layout
+  rather than assuming one global filename.
+- Passthrough components are copied or referenced deliberately.
+- Each emitted component config validates through the same path production
+  loaders use. Instantiate the relevant config and call `update_model_arch(...)`
+  or `update_model_config(...)` with the emitted JSON so unknown keys fail during
+  conversion, not at pipeline load time.
+- Record production loader strictness for every stateful component. If the loader
+  intentionally uses non-strict loading, add explicit missing/unexpected-key
+  assertions in the parity test and document exactly which keys are allowed.
+- Each new FastVideo component strict-loads converted weights where its production
+  loader is strict. If strict loading is impossible, record the exact allowed
+  missing/unexpected keys and why they are not inference weights.
+- Retry fixes include the original component parity evidence and the new
+  strict-load result in `local_tests_readme` so the component subagent can resume
+  without rediscovering context.
+- `local_tests_readme` records the command, output directory, and strict-load
+  result.
+
+Do not chase numerical parity in this skill except to identify a conversion
+mapping bug. Long parity-debug loops belong to `/add-model` Phase 6.
+
+## Escape Hatches
+
+Follow `../add-model/shared/common_rules.md`. Conversion-specific ask cases
+include selecting between incompatible official checkpoints, publishing/uploading
+weights, overwriting an existing converted repo not created by this run,
+accepting non-strict missing inference weights, or dropping a component/output
+from scope.
+
+## Handoff
+
+Return `../add-model/contracts/conversion_handoff.md` and update the shared state
+files before handoff.

.agents/skills/add-model-07-conversion/templates/family_to_diffusers.py

@@ -0,0 +1,293 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: Apache-2.0
+"""Convert <model_family> official weights to a FastVideo Diffusers-style tree.
+
+This template supports both separate component sources and a monolithic pipeline
+checkpoint that must be split by component prefix. Replace every TODO before
+using it for a real port.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import shutil
+from collections import OrderedDict
+from pathlib import Path
+from typing import Any
+
+import torch
+from safetensors import safe_open
+from safetensors.torch import load_file, save_file
+
+try:
+    from huggingface_hub import snapshot_download
+except ImportError:  # pragma: no cover - optional local conversion dependency
+    snapshot_download = None
+
+# TODO: fill with authoritative component prefixes for monolithic checkpoints.
+# Example: {"model.model.": "transformer", "pretransform.model.": "vae"}
+COMPONENT_PREFIXES: dict[str, str] = {}
+
+# TODO: fill with component-specific source paths for separate-component repos.
+# Example: {"transformer": "transformer/model.safetensors", "vae": "vae/"}
+SEPARATE_COMPONENT_PATHS: dict[str, str] = {}
+
+# TODO: copy passthrough dirs that are already loadable by FastVideo/Diffusers.
+PASSTHROUGH_SUBFOLDERS: tuple[str, ...] = ("tokenizer", "scheduler")
+
+# TODO: add regex renames derived from Phase 4 key/shape dumps.
+PARAM_NAME_MAP: dict[str, str] = {}
+
+# TODO: include training-only or dynamically-computed keys that must not load.
+SKIP_PATTERNS: tuple[str, ...] = ()
+
+
+def _hf_token() -> str | None:
+    return (os.environ.get("HF_TOKEN") or os.environ.get("HUGGINGFACE_HUB_TOKEN") or os.environ.get("HF_API_KEY"))
+
+
+def resolve_src(src: str, revision: str | None) -> Path:
+    if os.path.exists(src):
+        return Path(src)
+    if snapshot_download is None:
+        raise RuntimeError("huggingface_hub is required when --src is a repo id")
+    return Path(snapshot_download(repo_id=src, revision=revision, token=_hf_token()))
+
+
+def load_checkpoint(path: Path) -> dict[str, torch.Tensor]:
+    if path.is_dir():
+        weights: dict[str, torch.Tensor] = {}
+        for shard in sorted(path.glob("*.safetensors")):
+            weights.update(load_file(str(shard)))
+        if weights:
+            return weights
+        raise FileNotFoundError(f"No safetensors found in {path}")
+
+    if path.suffix == ".safetensors":
+        return load_file(str(path))
+
+    checkpoint = torch.load(path, map_location="cpu", weights_only=True)
+    if isinstance(checkpoint, dict):
+        for key in ("state_dict", "model_state_dict", "model", "module", "ema"):
+            if key in checkpoint and isinstance(checkpoint[key], dict):
+                return checkpoint[key]
+        return checkpoint
+    raise TypeError(f"Unsupported checkpoint type: {type(checkpoint)!r}")
+
+
+def should_skip_key(key: str) -> bool:
+    return any(re.search(pattern, key) for pattern in SKIP_PATTERNS)
+
+
+def apply_mapping(key: str) -> str | None:
+    if should_skip_key(key):
+        return None
+    for pattern, replacement in PARAM_NAME_MAP.items():
+        if re.match(pattern, key):
+            return re.sub(pattern, replacement, key)
+    return key
+
+
+def split_monolithic(state: dict[str, torch.Tensor], ) -> dict[str, OrderedDict[str, torch.Tensor]]:
+    components: dict[str, OrderedDict[str, torch.Tensor]] = {
+        name: OrderedDict()
+        for name in set(COMPONENT_PREFIXES.values())
+    }
+    intentionally_skipped: list[str] = []
+    unowned: list[str] = []
+    for key, value in state.items():
+        if should_skip_key(key):
+            intentionally_skipped.append(key)
+            continue
+        for prefix, component in COMPONENT_PREFIXES.items():
+            if key.startswith(prefix):
+                mapped = apply_mapping(key[len(prefix):])
+                if mapped is not None:
+                    components[component][mapped] = value
+                break
+        else:
+            unowned.append(key)
+    if unowned:
+        sample = ", ".join(unowned[:10])
+        raise ValueError(f"Unowned monolithic keys: {len(unowned)}. "
+                         f"Add COMPONENT_PREFIXES or SKIP_PATTERNS entries. Sample: {sample}")
+    if intentionally_skipped:
+        print(f"Intentionally skipped {len(intentionally_skipped)} keys")
+    return {name: weights for name, weights in components.items() if weights}
+
+
+def load_separate_components(src_dir: Path) -> dict[str, OrderedDict[str, torch.Tensor]]:
+    components: dict[str, OrderedDict[str, torch.Tensor]] = {}
+    for component, rel_path in SEPARATE_COMPONENT_PATHS.items():
+        state = load_checkpoint(src_dir / rel_path)
+        converted: OrderedDict[str, torch.Tensor] = OrderedDict()
+        for key, value in state.items():
+            mapped = apply_mapping(key)
+            if mapped is not None:
+                converted[mapped] = value
+        components[component] = converted
+    return components
+
+
+def build_component_configs(_src_dir: Path) -> dict[str, dict[str, Any]]:
+    # TODO: emit config content accepted by FastVideo loaders. Most components use
+    # config.json; schedulers use scheduler_config.json.
+    return {
+        "transformer": {
+            "_class_name": "<FastVideoTransformerClass>"
+        },
+        "vae": {
+            "_class_name": "<FastVideoVAEClass>"
+        },
+    }
+
+
+def config_filename(component: str) -> str:
+    if component == "scheduler":
+        return "scheduler_config.json"
+    return "config.json"
+
+
+def source_label(src: str) -> str:
+    if os.path.exists(src):
+        return Path(src).name
+    return src
+
+
+def build_model_index(
+    src: str,
+    revision: str | None,
+    available_components: set[str],
+) -> dict[str, Any]:
+    # TODO: match the target pipeline and every required component.
+    index: dict[str, Any] = {
+        "_class_name": "<FastVideoPipelineClass>",
+        "_diffusers_version": "0.30.0",
+        "_fastvideo_converted_from": source_label(src),
+        # Existing transformer/VAE loaders expect "diffusers" even when
+        # _class_name names a FastVideo-native class registered in FastVideo.
+        "transformer": ["diffusers", "<FastVideoTransformerClass>"],
+        "vae": ["diffusers", "<FastVideoVAEClass>"],
+    }
+    if revision:
+        index["_fastvideo_converted_revision"] = revision
+    return {key: value for key, value in index.items() if key.startswith("_") or key in available_components}
+
+
+def validate_component_configs(configs: dict[str, dict[str, Any]]) -> None:
+    # TODO: instantiate each FastVideo config and call update_model_arch(...) or
+    # update_model_config(...) with this JSON so unknown emitted keys fail here.
+    placeholder_configs = [name for name, config in configs.items() if "<" in json.dumps(config)]
+    if placeholder_configs:
+        raise ValueError(f"Replace config placeholders for: {placeholder_configs}")
+
+
+def verify_conversion(
+    dst_dir: Path,
+    components: dict[str, OrderedDict[str, torch.Tensor]],
+) -> None:
+    del dst_dir, components
+    # TODO: load each emitted stateful component through its production loader and
+    # assert strict load, or document exact allowed missing/unexpected keys.
+    raise NotImplementedError("Implement production config validation and strict-load checks")
+
+
+def write_component(
+    dst_dir: Path,
+    name: str,
+    state: dict[str, torch.Tensor],
+    config: dict[str, Any] | None,
+) -> None:
+    component_dir = dst_dir / name
+    if component_dir.exists() and any(component_dir.iterdir()):
+        shutil.rmtree(component_dir)
+    component_dir.mkdir(parents=True, exist_ok=True)
+    save_file(dict(state), str(component_dir / "diffusion_pytorch_model.safetensors"))
+    if config is not None:
+        config_path = component_dir / config_filename(name)
+        with config_path.open("w", encoding="utf-8") as f:
+            json.dump(config, f, indent=2)
+            f.write("\n")
+    print(f"Wrote {name}: {len(state)} tensors")
+
+
+def copy_passthrough(src_dir: Path, dst_dir: Path) -> list[str]:
+    copied: list[str] = []
+    for subfolder in PASSTHROUGH_SUBFOLDERS:
+        src = src_dir / subfolder
+        if not src.is_dir():
+            continue
+        dst = dst_dir / subfolder
+        if dst.exists():
+            shutil.rmtree(dst)
+        shutil.copytree(src, dst)
+        copied.append(subfolder)
+        print(f"Copied {subfolder}/")
+    return copied
+
+
+def default_monolithic_checkpoint(src_path: Path) -> Path:
+    if src_path.is_file():
+        return src_path
+    return src_path / "model.safetensors"
+
+
+def convert(
+    src: str,
+    dst: str,
+    layout: str,
+    revision: str | None,
+) -> None:
+    src_path = resolve_src(src, revision)
+    dst_dir = Path(dst)
+    dst_dir.mkdir(parents=True, exist_ok=True)
+    model_index_path = dst_dir / "model_index.json"
+
+    if layout in {"monolithic", "raw_official"}:
+        # TODO: replace model.safetensors with the official monolithic file name.
+        components = split_monolithic(load_checkpoint(default_monolithic_checkpoint(src_path)))
+    elif layout in {"separate_components", "mixed"}:
+        if not src_path.is_dir():
+            raise ValueError(f"{layout} layout requires a source directory: {src_path}")
+        components = load_separate_components(src_path)
+    else:
+        raise ValueError(f"Unsupported template layout: {layout}")
+
+    copied = (copy_passthrough(src_path, dst_dir) if src_path.is_dir() else [])
+    configs = build_component_configs(src_path if src_path.is_dir() else src_path.parent)
+    validate_component_configs(configs)
+    for name, state in components.items():
+        write_component(dst_dir, name, state, configs.get(name))
+
+    available = set(components) | set(copied)
+    with model_index_path.open("w", encoding="utf-8") as f:
+        json.dump(build_model_index(src, revision, available), f, indent=2)
+        f.write("\n")
+    print(f"Wrote {dst_dir / 'model_index.json'}")
+    verify_conversion(dst_dir, components)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--src", required=True, help="HF repo id, local dir, or checkpoint path")
+    parser.add_argument("--revision", help="HF branch, tag, or commit for repo sources")
+    parser.add_argument(
+        "--dst",
+        required=True,
+        help="Output converted_weights/<model_family> directory",
+    )
+    parser.add_argument(
+        "--layout",
+        choices=("raw_official", "monolithic", "separate_components", "mixed"),
+        required=True,
+        help="Official source layout",
+    )
+    args = parser.parse_args()
+    convert(args.src, args.dst, args.layout, args.revision)
+
+
+if __name__ == "__main__":
+    main()

.agents/skills/add-model-08-trace/SKILL.md

@@ -0,0 +1,214 @@
+---
+name: add-model-08-trace
+description: Use during /add-model Phase 6 when component parity has failed and root cause requires layer-by-layer divergence analysis. Uses FastVideo activation trace first, falling back to custom hooks only for boundaries or stats the utility cannot observe.
+---
+
+# Add-Model Trace
+
+## Manual Invocation
+
+Load this skill when `/add-model` Phase 6 component parity has failed and the
+root cause requires layer-by-layer divergence analysis. This skill is not
+auto-fired. The calling subagent (DiT, VAE, encoder, or generic port skill)
+loads it when its standard parity-debug loop hits a wall and cannot isolate
+the divergence from end-to-end tensor comparisons alone.
+
+Do not load this skill for first-pass parity failures. Try weight-diff and
+end-to-end tensor comparison first. Load this skill only when those do not
+isolate the cause.
+
+## Goal
+
+Find the first numerical divergence point between FastVideo's port and the
+official reference, layer by layer, by instrumenting both sides at matching
+tensor boundaries. The investigation must leave zero source residue in
+production code when it closes.
+
+## When To Run
+
+After a component parity test FAILS at a bf16-noise-realistic tolerance AND
+the calling subagent's first-pass debug (weight-diff, end-to-end tensor
+compare) does not isolate the cause.
+
+Required inputs before starting:
+
+- A working FastVideo loader for the component under investigation.
+- A working official loader, typically via
+  `tests/local_tests/helpers/<family>_upstream.py::load_upstream_<component>`.
+- Shared deterministic test inputs (same tensors on both sides).
+- The component parity test file path and its current failure output.
+
+## Primary Path: FastVideo Activation Trace
+
+Use FastVideo's first-class activation trace before writing custom hooks:
+`fastvideo/hooks/activation_trace.py`, documented in
+`docs/contributing/activation_trace.md`.
+
+Pipeline runs attach trace to the transformer during pipeline initialization.
+Component-only parity harnesses may call `attach_activation_trace(model)` from
+local test/debug code; do not add trace calls to production model code.
+
+Prefix the failing parity command with a tight layer regex:
+
+```bash
+FASTVIDEO_TRACE_ACTIVATIONS=1 \
+FASTVIDEO_TRACE_LAYERS="^block\.layers\.[0-9]+$" \
+FASTVIDEO_TRACE_STATS="abs_mean,sum,max,shape" \
+FASTVIDEO_TRACE_STEPS="0" \
+FASTVIDEO_TRACE_OUTPUT="/tmp/opencode/fv_trace.jsonl" \
+pytest tests/local_tests -k "parity" -v -s
+```
+
+Match the layer regex to the actual `model.named_modules()` names. Empty or
+broad regexes are expensive; prefer block-level names first, then narrow to
+submodules after the first divergent block is known.
+
+## Trace Compare Contract
+
+One JSONL file per side. FastVideo output should use `FASTVIDEO_TRACE_OUTPUT`;
+the upstream harness should emit the same JSONL shape:
+
+```json
+{"module":"block.layers.0","tensor":"out","step":0,"abs_mean":0.0123,"sum":1.0,"max":0.5,"shape":[1,16,32]}
+```
+
+Compare rows by `(module, step, tensor)`. The first row whose `shape`,
+`abs_mean`, or `max` diverges beyond the component tolerance is the first broken
+boundary. Keep `FASTVIDEO_TRACE_LAYERS`, `FASTVIDEO_TRACE_STATS`, and
+`FASTVIDEO_TRACE_STEPS` identical between sides; if row order differs, sort or
+normalize before diffing.
+
+## Drill-Down Loop
+
+**Initial run:** trace every top-level block (`^block\.layers\.[0-9]+$` or the
+family's equivalent). Identify the first block index where `abs_mean` or `max`
+drifts beyond tolerance while earlier blocks match.
+
+**Drill run:** tighten `FASTVIDEO_TRACE_LAYERS` to submodules inside the first
+divergent block: attention output, MLP projections, norm outputs, modality
+adapters, or other named boundaries exposed by `named_modules()`.
+
+**Iterate:** if the first divergent operation is a free function or tensor op not
+visible as an `nn.Module`, use the fallback instrumentation hierarchy below.
+
+The loop ends when the first divergent submodule or operation is identified with
+a file:line citation in the official source.
+
+## Fallback Instrumentation Hierarchy
+
+Use these only when activation trace cannot observe the needed boundary or
+statistic.
+
+### (1) Custom forward hooks
+
+`module.register_forward_hook(...)` and `register_forward_pre_hook(...)`.
+Always within `try/finally` with `handle.remove()`. Zero source residue.
+
+### (2) Runtime monkey-patch
+
+`module.attr = wrapped_func` or `cls.method = wrapped_method`, restored via
+`try/finally` (save original first). Use for free functions and non-Module sites
+such as activation functions (`swiglu`, `apply_rotary_emb`).
+
+### (3) Source edits in FastVideo's own code
+
+Only when (1) and (2) are insufficient. Track all edits within a single named
+`git stash` boundary OR a temporary branch. Run `git diff` before closing the
+investigation to confirm cleanup.
+
+### (4) Source edits in official repo source
+
+Allowed only when hook and monkey-patch approaches cannot capture the site.
+For git-tracked or editable official clones, use `git diff` in the clone path to
+verify cleanup. For non-editable site-packages, back up the target file before
+editing and restore it before handoff.
+
+## Hypothesis Toggles
+
+Use env-var-gated monkey-patches to A/B test suspect implementations without
+source edits. Pattern: `<FAMILY>_DEBUG_PATCH_<HYPOTHESIS>=1`.
+
+Example from the magi-human investigation:
+
+```
+MAGI_DEBUG_PATCH_LINEAR=1
+```
+
+This patched `PackedExpertLinear.forward` to mirror upstream's
+`_BF16ComputeLinear` explicit-cast pattern, isolating a dtype-cast difference
+as the root cause.
+
+Document all toggles in the script docstring. Each toggle must:
+
+- save the original before patching;
+- restore the original in a `try/finally` block;
+- print a `[debug] Patched <ClassName>.<method>` line to stdout when active.
+
+## Cleanup Gate
+
+The calling agent MUST report `[cleanup-gate] PASS` on all five items before
+handoff. Do not hand off with any item unresolved.
+
+1. `git diff` in the FastVideo repo: empty. No stray prints, hooks, or
+   monkey-patches in production code.
+2. `git diff` in the official-repo clone (if used): empty. For non-editable
+   site-packages installs: `diff original.py original.py.trace-backup` is
+   empty OR `pip install --force-reinstall <pkg>` succeeded and the installed
+   file matches the original.
+3. `git stash list`: only the named investigation stash (or empty). No
+   unnamed stashes left from this session.
+4. No new untracked files outside `/tmp/opencode/` (logs) and the existing
+   debug script directory (`tests/local_tests/transformers/` or equivalent).
+5. `mypy` clean on any production files touched during the investigation.
+
+## Escape Hatches
+
+Escalate to the calling bucket skill when:
+
+- A forward hook on an official module raises because of a custom `forward`
+  signature or varlen handler args that the hook closure cannot satisfy. The
+  bucket skill has component-specific knowledge to work around this.
+- The first divergent layer is `block[0]`, meaning the divergence is in the
+  adapter, modality dispatcher, coordinate embedding, or packing step before
+  any block runs. Check those sites first; the bug is not in attention or MLP.
+- Per-block drift is never zero anywhere across all blocks. This usually means
+  the inputs are not bit-identical between sides. Verify with a state-dict
+  compare (weight-diff script) AND confirm the input tensors are the same
+  object or have identical values before the forward call.
+
+## Handoff
+
+Return to the calling subagent with:
+
+- FastVideo trace JSONL path and upstream trace JSONL path.
+- Trace settings used: `FASTVIDEO_TRACE_LAYERS`, `FASTVIDEO_TRACE_STATS`, and
+  `FASTVIDEO_TRACE_STEPS`.
+- The first divergent `(module, step, tensor)` row and observed drift.
+- The upstream file:line citation where the divergence originates.
+- Fallback hook/patch verdict if activation trace could not observe the boundary.
+- Hypothesis verdict if an A/B toggle was used, for example `PATCH_LINEAR=1`.
+- Cleanup-gate status: `[cleanup-gate] PASS` or a list of unresolved items.
+
+The calling agent uses this to scope the production fix in the FastVideo
+component file.
+
+## References
+
+- `docs/contributing/activation_trace.md` for canonical activation-trace env vars,
+  JSONL output, cost model, and troubleshooting.
+- `fastvideo/hooks/activation_trace.py` for the implementation and
+  `attach_activation_trace(model)` entry point.
+- `templates/block_trace_debug.py` in this skill directory: fallback custom-hook
+  template when activation trace cannot observe the needed boundary or stat.
+- `tests/local_tests/transformers/_debug_magi_human_block_parity.py` in the
+  FastVideo3 repo: historical worked example for custom hook/patch debugging.
+- `add-model/SKILL.md` Phase 6: the calling context for this skill.
+- `add-model-03-port-dit/SKILL.md`, `add-model-04-port-vae/SKILL.md`,
+  `add-model-05-port-encoder/SKILL.md`, `add-model-06-port-generic/SKILL.md`:
+  bucket-specific debug language and component-specific escape-hatch knowledge.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-05-01 | Initial skill extracted from `_debug_magi_human_block_parity.py` pattern. |

.agents/skills/add-model-08-trace/templates/block_trace_debug.py

@@ -0,0 +1,334 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Per-block divergence debugger template for FastVideo model ports.
+
+Run directly (not a pytest test):
+    python tests/local_tests/transformers/_debug_<family>_<component>_parity.py
+
+Generalizes: tests/local_tests/transformers/_debug_magi_human_block_parity.py
+
+Fill FAMILY, COMPONENT, and the two loader functions. Run once for the initial
+drift table, then set <FAMILY>_DEBUG_DRILL_LAYER=NN to drill into submodules.
+Add <FAMILY>_DEBUG_PATCH_<HYPOTHESIS>=1 to A/B test a suspect implementation.
+
+CLEANUP: all hooks removed in try/finally; monkey-patches restored in
+try/finally; source edits tracked in a named git stash. Zero source residue.
+See add-model-08-trace/SKILL.md for the full cleanup gate checklist.
+"""
+from __future__ import annotations
+
+import gc
+import os
+import sys
+from pathlib import Path
+from typing import Any
+
+import torch
+
+FAMILY: str = "<family>"  # e.g. "magi_human", "ltx2", "wan"
+COMPONENT: str = "<component>"  # e.g. "dit", "vae", "encoder"
+DRILL_LAYER_ENV: str = "<FAMILY>_DEBUG_DRILL_LAYER"
+HYPOTHESIS_ENV: str = "<FAMILY>_DEBUG_PATCH_<HYPOTHESIS>"
+REL_THRESHOLD: float = 0.005  # 0.5% abs_mean drift flags a block as divergent
+LOG_DIR: Path = Path("/tmp/opencode")
+
+REPO_ROOT = Path(__file__).resolve().parents[3]
+sys.path.insert(0, str(REPO_ROOT))
+
+
+def load_official(device: torch.device) -> torch.nn.Module:
+    """Load the official upstream model. TODO: implement for your family.
+
+    Example (magi-human):
+        from tests.local_tests.helpers.magi_human_upstream import install_stubs, load_upstream_dit
+        install_stubs()
+        return load_upstream_dit(base_shard_dir, device=device, dtype=None)
+    """
+    raise NotImplementedError(f"Fill load_official() for {FAMILY}/{COMPONENT}.")
+
+
+def load_fastvideo(device: torch.device) -> torch.nn.Module:
+    """Load the FastVideo-native model. TODO: implement for your family.
+
+    Example (magi-human):
+        from fastvideo.configs.models.dits.magi_human import MagiHumanVideoConfig
+        from fastvideo.models.dits.magi_human import MagiHumanDiT
+        from safetensors.torch import load_file; import glob
+        fv = MagiHumanDiT(MagiHumanVideoConfig())
+        state = {}
+        for shard in sorted(glob.glob(str(transformer_dir / "*.safetensors"))): state.update(load_file(shard))
+        fv.load_state_dict(state, strict=False); return fv.to(device).eval()
+    """
+    raise NotImplementedError(f"Fill load_fastvideo() for {FAMILY}/{COMPONENT}.")
+
+
+def build_inputs(device: torch.device) -> dict[str, Any]:
+    """Return deterministic inputs shared by both sides. TODO: replace.
+
+    Both sides must receive the SAME tensors (clone before each forward call).
+    Non-identical inputs cause non-zero drift everywhere.
+    """
+    torch.manual_seed(0)
+    return {"x": torch.randn(64, 1024, dtype=torch.bfloat16, device=device)}
+
+
+def _stat(name: str, t: torch.Tensor) -> dict:
+    f = t.detach().float()
+    return {
+        "name": name,
+        "shape": tuple(t.shape),
+        "abs_mean": f.abs().mean().item(),
+        "sum": f.sum().item(),
+        "min": f.min().item(),
+        "max": f.max().item(),
+    }
+
+
+def _attach_block_hooks(
+    model: torch.nn.Module,
+    label: str,
+    log: list[dict],
+    tensors: dict[str, torch.Tensor] | None = None,
+    drill_layer: int | None = None,
+) -> list[Any]:
+    """Return hook handles. Caller MUST remove them in try/finally."""
+    handles: list[Any] = []
+
+    def _hook(name: str):
+
+        def fn(_module, _inputs, outputs):
+            t = outputs[0] if isinstance(outputs, tuple) else outputs
+            if not torch.is_tensor(t):
+                return
+            log.append({"side": label, **_stat(name, t)})
+            if tensors is not None:
+                tensors[name] = t.detach().float().cpu()
+
+        return fn
+
+    def _pre_hook(name: str):
+        # Pre-hooks observe a free function's output by intercepting the next
+        # module's input (useful when the activation is not an nn.Module).
+        def fn(_module, inputs):
+            t = inputs[0] if isinstance(inputs, tuple) else inputs
+            if not torch.is_tensor(t):
+                return
+            key = f"{name}<in>"
+            log.append({"side": label, **_stat(key, t)})
+            if tensors is not None:
+                tensors[key] = t.detach().float().cpu()
+
+        return fn
+
+    # TODO: adapt attribute paths to your model. Remove adapter block if absent.
+    if hasattr(model, "adapter"):
+        handles.append(model.adapter.register_forward_hook(_hook("adapter")))
+
+    # TODO: adapt model.block.layers to your block container.
+    # Alternatives: model.transformer.layers, model.blocks, model.layers
+    block_layers = model.block.layers  # type: ignore[attr-defined]
+    for i, layer in enumerate(block_layers):
+        handles.append(layer.register_forward_hook(_hook(f"block[{i:02d}]")))
+        if drill_layer is not None and i == drill_layer:
+            tag = f"L{i:02d}"
+            # TODO: adapt submodule names to your layer's attributes.
+            # magi-human uses: attention, mlp.pre_norm, mlp.up_gate_proj,
+            # mlp.down_proj (pre+post), mlp, attn_post_norm, mlp_post_norm.
+            if hasattr(layer, "attention"):
+                handles.append(layer.attention.register_forward_hook(_hook(f"{tag}.attention")))
+            if hasattr(layer, "mlp"):
+                mlp = layer.mlp
+                if hasattr(mlp, "pre_norm"):
+                    handles.append(mlp.pre_norm.register_forward_hook(_hook(f"{tag}.mlp.pre_norm")))
+                if hasattr(mlp, "up_gate_proj"):
+                    handles.append(mlp.up_gate_proj.register_forward_hook(_hook(f"{tag}.mlp.up_gate_proj")))
+                if hasattr(mlp, "down_proj"):
+                    handles.append(mlp.down_proj.register_forward_pre_hook(_pre_hook(f"{tag}.mlp.down_proj")))
+                    handles.append(mlp.down_proj.register_forward_hook(_hook(f"{tag}.mlp.down_proj")))
+                handles.append(mlp.register_forward_hook(_hook(f"{tag}.mlp")))
+            if hasattr(layer, "attn_post_norm"):
+                handles.append(layer.attn_post_norm.register_forward_hook(_hook(f"{tag}.attn_post_norm")))
+            if hasattr(layer, "mlp_post_norm"):
+                handles.append(layer.mlp_post_norm.register_forward_hook(_hook(f"{tag}.mlp_post_norm")))
+    return handles
+
+
+def _apply_hypothesis_patch() -> bool:
+    """Apply an optional monkey-patch gated by HYPOTHESIS_ENV. TODO: implement.
+
+    Pattern: save original on the class, patch, restore in _restore_hypothesis_patch().
+    """
+    if os.getenv(HYPOTHESIS_ENV) != "1":
+        return False
+    # TODO: import FastVideo class, save original, apply patch.
+    print(f"[debug] Hypothesis patch {HYPOTHESIS_ENV}=1 applied.")
+    return True
+
+
+def _restore_hypothesis_patch() -> None:
+    if os.getenv(HYPOTHESIS_ENV) != "1":
+        return
+    # TODO: restore original, e.g.: _mod.TargetClass.method = _mod._ORIGINAL_METHOD
+
+
+def _write_log(entries: list[dict], path: Path) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with open(path, "w") as f:
+        for e in entries:
+            f.write(f"{e['name']} {e['shape']} "
+                    f"{e['abs_mean']:.8f} {e['sum']:.4f} "
+                    f"{e['min']:.6f} {e['max']:.6f}\n")
+
+
+def _sort_key(name: str, drill_layer: int) -> tuple:
+    if name == "adapter":
+        return (0, "")
+    if name.startswith(f"L{drill_layer:02d}."):
+        sub_order = {
+            "attention": 0,
+            "attn_post_norm": 1,
+            "mlp.pre_norm": 2,
+            "mlp.up_gate_proj": 3,
+            "mlp.down_proj<in>": 4,
+            "mlp.down_proj": 5,
+            "mlp": 6,
+            "mlp_post_norm": 7,
+        }.get(name.split(".", 1)[1], 9)
+        return (1, f"block[{drill_layer:02d}]", sub_order)
+    if name.startswith("block["):
+        return (1, name, 99)
+    return (2, name, 0)
+
+
+def _print_table(by_name: dict[str, dict], drill_layer: int) -> int | None:
+    hdr = (f"{'name':<18} {'up_shape':<22} {'up_absmean':>12} {'fv_absmean':>12} "
+           f"{'absmean_diff':>14} {'rel%':>8} {'up_sum':>14} {'fv_sum':>14} {'sum_diff':>12}")
+    print(f"\n{hdr}\n{'-' * len(hdr)}")
+    first_div: int | None = None
+    for name in sorted(by_name.keys(), key=lambda n: _sort_key(n, drill_layer)):
+        d = by_name[name]
+        up, fv = d.get("up"), d.get("fv")
+        if up is None or fv is None:
+            continue
+        am_diff = abs(up["abs_mean"] - fv["abs_mean"])
+        am_rel = am_diff / max(up["abs_mean"], 1e-9)
+        sum_diff = abs(up["sum"] - fv["sum"])
+        flag = ""
+        if name.startswith("block[") and am_rel > REL_THRESHOLD:
+            flag = " <<< DIVERGE"
+            if first_div is None:
+                first_div = int(name[len("block["):-1])
+        print(f"{name:<18} {str(up['shape']):<22} {up['abs_mean']:>12.6f} "
+              f"{fv['abs_mean']:>12.6f} {am_diff:>14.6f} {am_rel * 100:>7.3f}% "
+              f"{up['sum']:>14.4f} {fv['sum']:>14.4f} {sum_diff:>12.4f}{flag}")
+    return first_div
+
+
+def _print_elementwise(up_t: dict[str, torch.Tensor], fv_t: dict[str, torch.Tensor], drill_layer: int) -> None:
+    common = set(up_t.keys()) & set(fv_t.keys())
+    if not common:
+        return
+    hdr = f"{'name':<30} {'shape':<22} {'diff_max':>12} {'diff_mean':>12} {'diff_rel%':>10}"
+    print(f"\nElement-wise diffs for drilled L{drill_layer:02d} submodules:\n{hdr}\n{'-' * len(hdr)}")
+    for name in sorted(common):
+        a, b = up_t[name], fv_t[name]
+        if a.shape != b.shape:
+            continue
+        diff = (a - b).abs()
+        rel = (diff.mean().item() / max(a.abs().mean().item(), 1e-9)) * 100
+        print(f"{name:<30} {str(tuple(a.shape)):<22} "
+              f"{diff.max().item():>12.6f} {diff.mean().item():>12.6f} {rel:>9.4f}%")
+
+
+def main() -> None:
+    if not torch.cuda.is_available():
+        print("Need CUDA. Skipping.")
+        return
+
+    # TODO: add precondition checks (official clone present, weights available).
+
+    drill_layer = int(os.getenv(DRILL_LAYER_ENV, "0"))
+    device = torch.device("cuda:0")
+    patched = _apply_hypothesis_patch()
+    try:
+        inputs = build_inputs(device)
+
+        print("Loading official model...")
+        official = load_official(device)
+        up_log: list[dict] = []
+        up_t: dict[str, torch.Tensor] = {}
+        up_handles = _attach_block_hooks(official, "up", up_log, up_t, drill_layer)
+        print("Running official forward (with hooks)...")
+        try:
+            with torch.inference_mode():
+                # TODO: adapt forward call signature to your component.
+                ref_out = official(**{k: v.clone() for k, v in inputs.items()})
+            if isinstance(ref_out, dict):
+                sample = ref_out.get("sample")
+                ref_out = sample if sample is not None else ref_out.get("x")
+            elif hasattr(ref_out, "sample"):
+                ref_out = ref_out.sample
+            elif isinstance(ref_out, tuple):
+                ref_out = ref_out[0]
+            assert torch.is_tensor(ref_out), f"official output is not tensor: {type(ref_out)}"
+            ref_out = ref_out.detach().float().cpu()
+        finally:
+            for h in up_handles:
+                h.remove()
+        del official
+        gc.collect()
+        torch.cuda.empty_cache()
+
+        print("Loading FastVideo model...")
+        fv = load_fastvideo(device)
+        fv_log: list[dict] = []
+        fv_t: dict[str, torch.Tensor] = {}
+        fv_handles = _attach_block_hooks(fv, "fv", fv_log, fv_t, drill_layer)
+        print("Running FastVideo forward (with hooks)...")
+        try:
+            with torch.inference_mode():
+                # TODO: adapt forward call signature to your component.
+                fv_out = fv(**{k: v.clone() for k, v in inputs.items()})
+            if isinstance(fv_out, dict):
+                sample = fv_out.get("sample")
+                fv_out = sample if sample is not None else fv_out.get("x")
+            elif hasattr(fv_out, "sample"):
+                fv_out = fv_out.sample
+            elif isinstance(fv_out, tuple):
+                fv_out = fv_out[0]
+            assert torch.is_tensor(fv_out), f"FastVideo output is not tensor: {type(fv_out)}"
+            fv_out = fv_out.detach().float().cpu()
+        finally:
+            for h in fv_handles:
+                h.remove()
+    finally:
+        _restore_hypothesis_patch()
+
+    LOG_DIR.mkdir(parents=True, exist_ok=True)
+    up_path = LOG_DIR / f"{FAMILY}_{COMPONENT}_up_layers.log"
+    fv_path = LOG_DIR / f"{FAMILY}_{COMPONENT}_fv_layers.log"
+    _write_log(up_log, up_path)
+    _write_log(fv_log, fv_path)
+    print(f"\nLogs: {up_path}  {fv_path}\nDiff: diff {up_path} {fv_path}")
+
+    by_name: dict[str, dict] = {}
+    for entry in up_log + fv_log:
+        by_name.setdefault(entry["name"], {})[entry["side"]] = entry
+    first_div = _print_table(by_name, drill_layer)
+
+    print()
+    if first_div is not None:
+        print(f"First block exceeding {REL_THRESHOLD * 100:.2f}% drift: block[{first_div:02d}]")
+        print(f"Re-run with {DRILL_LAYER_ENV}={first_div} to drill submodules.")
+    else:
+        print(f"No block exceeded {REL_THRESHOLD * 100:.2f}% -- divergence is amortized or pre-block.")
+
+    diff = (ref_out - fv_out).abs()
+    print(f"\nFinal  ref_abs={ref_out.abs().mean():.6f}  fv_abs={fv_out.abs().mean():.6f}  "
+          f"diff_max={diff.max():.6f}  diff_mean={diff.mean():.6f}")
+    _print_elementwise(up_t, fv_t, drill_layer)
+    if patched:
+        print(f"\n[debug] Hypothesis {HYPOTHESIS_ENV}=1 was active this run.")
+
+
+if __name__ == "__main__":
+    main()

.agents/skills/add-model-09-pipeline/SKILL.md

@@ -0,0 +1,255 @@
+---
+name: add-model-09-pipeline
+description: Use during /add-model Phase 7 after all required component parity tests pass to define FastVideo pipeline wiring, configs, presets, registry entries, examples, smoke tests, and pipeline parity tests.
+---
+
+# Add Model Pipeline
+
+## Goal
+
+Implement and verify the end-to-end FastVideo pipeline after the native
+components and converted weights have passed non-skip component parity. This
+skill owns pipeline class/stage wiring, pipeline configs, presets, registry
+entries, examples, smoke tests, and pipeline parity-debug.
+
+FastVideo has one pipeline architecture: stage-based composition through
+`ComposedPipelineBase`. Add or specialize stages only when existing stages cannot
+represent the official behavior safely.
+
+## Hard Gate
+
+Do not start pipeline work until every required component, including reused
+components, has a non-skip local parity PASS.
+
+If any component row is missing, skipped, red, or blocked, return to `/add-model`
+Phase 6. Pipeline parity cannot distinguish stage wiring mistakes from broken
+component numerics when component parity is still unresolved.
+
+## Inputs
+
+Follow `../add-model/shared/common_rules.md` for token/auth safety, state files,
+escape hatches, production boundaries, and skip/pass semantics.
+
+Require a complete packet matching
+`../add-model/contracts/pipeline_context.md`.
+
+The packet must include:
+
+- official pipeline files and official call/default sources;
+- workload types, input/output modalities, and output contract;
+- converted or source `model_index.json` path;
+- component parity rows, all `non_skip_pass`;
+- target FastVideo pipeline/config/preset/registry/example/test paths;
+- `local_tests_readme` and `port_state_file` paths.
+
+## Outputs
+
+- Pipeline package under `fastvideo/pipelines/basic/<family>/`.
+- Pipeline config under `fastvideo/configs/pipelines/<family>.py` or a documented
+  family-local config file when that matches existing project style.
+- Presets under `fastvideo/pipelines/basic/<family>/presets.py`.
+- Registry updates in `fastvideo/registry.py`.
+- Basic example under `examples/inference/basic/basic_<family>*.py`.
+- Local smoke and parity tests under `tests/local_tests/pipelines/`.
+- Updated `tests/local_tests/<model_family>/README.md`.
+- Updated `tests/local_tests/<model_family>/PORT_STATUS.md`.
+- Handoff matching `../add-model/contracts/pipeline_handoff.md`.
+
+## Mode: Pipeline Definition
+
+Use this mode first.
+
+1. Read the official pipeline call path before editing FastVideo code.
+2. Compare official defaults against the planned FastVideo config and presets:
+   steps, CFG scales, secondary CFG, flow shift, schedulers, sigmas, seed/RNG,
+   resolution, frames, FPS, duration, VAE scaling, decode slicing, negative
+   prompt defaults, and output heads.
+3. Create or update the pipeline class with `_required_config_modules` matching
+   the emitted `model_index.json` and `ComposedPipelineBase.load_modules`.
+   Runtime pipeline resolution is exact: `model_index.json["_class_name"]` must
+   match a registered `EntryClass.__name__`, or a wrapper/alias class in
+   `EntryClass`. Registry detectors do not select the executable pipeline class.
+4. Add new public generation kwargs to `fastvideo/api/sampling_param.py` before
+   examples or presets use them. `SamplingParam.update()` ignores unknown keys
+   except for logging, and preset defaults apply only to declared fields. Add CLI
+   args when the option should be available from command-line entrypoints.
+5. Put loader-time changes in `load_modules()` or earlier, not
+   `initialize_pipeline()`. `ComposedPipelineBase.__init__` loads modules before
+   `post_init()` calls `initialize_pipeline()`, so process-global flags, loader
+   path rewrites, dtype overrides, and tokenizer path changes needed for loading
+   cannot be introduced there.
+6. Use `self.get_module("transformer_2", None)` and similar optional accessors
+   for truly optional modules. Do not hard-require optional modules by accident.
+7. Avoid mutating class-level `_required_config_modules` in custom code. If a
+   pipeline needs dynamic modules, copy the list to an instance-owned value or
+   pass `required_config_modules` explicitly so one pipeline instance cannot leak
+   module requirements into another.
+8. Create the stage chain in official execution order. Prefer existing shared
+   stages for standard text encoding, timestep preparation, latent preparation,
+   denoising, and decoding.
+9. Add model-specific stages only for family-specific behavior that does not fit
+   the shared stage contracts.
+10. Add pipeline config classes for wiring and runtime defaults. Do not duplicate
+   component architecture fields unless a loader requires them in the subconfig.
+    Family-local config files such as
+    `fastvideo/pipelines/basic/<family>/pipeline_configs.py` are valid only when
+    `fastvideo/registry.py` imports and registers the classes explicitly.
+11. Add `InferencePreset` objects with `model_family`, `name`, `version`,
+    `defaults`, optional validation-only `stage_schemas`, and an `ALL_PRESETS`
+    tuple. `stage_schemas` validates user-facing `stage_overrides` names; it does
+    not drive `create_pipeline_stages()` execution.
+12. Register config classes and presets in `fastvideo/registry.py`: add
+    `register_configs(...)`, import the family's `ALL_PRESETS`, and append it to
+    `_register_presets()`. Detectors should cover HF paths and `_class_name`
+    strings for config/preset lookup, but not as a replacement for exact pipeline
+    class-name resolution.
+13. Add a basic example with a user-story docstring and normal file-path inputs
+    for image, audio, or video references. Keep orchestration glue in the
+    pipeline or a helper, not in the example.
+14. Add a separate smoke test
+    `tests/local_tests/pipelines/test_<family>_pipeline_smoke.py` that proves
+    imports, `EntryClass`, registry, presets, config defaults, and at least one
+    real load/generate path when weights are local. Older local tests sometimes
+    colocate smoke checks in parity files; new ports should use the separate file
+    convention.
+15. Add or update pipeline parity test scaffolding with
+    `templates/pipeline_parity_test.py`.
+16. Update `local_tests_readme` and `port_state_file` with commands, statuses,
+    default sources, decisions, and blockers.
+
+Production import boundaries are defined in
+`../add-model/shared/common_rules.md`.
+
+## Mode: Pipeline Parity Debug
+
+Run after pipeline definition and after smoke can execute far enough to load the
+pipeline. Loop until pipeline parity is a non-skip PASS or a precise blocker is
+returned.
+
+Mandatory order:
+
+```bash
+pytest tests/local_tests/pipelines/test_<family>_pipeline_smoke.py -v -s
+DISABLE_SP=1 pytest tests/local_tests/pipelines/test_<family>_pipeline_parity.py -v -s
+python examples/inference/basic/basic_<family>.py
+```
+
+Pipeline parity must compare real outputs, not only successful generation:
+
+- denoised latents when decode parity is expensive or nondeterministic;
+- decoded videos/images when visual output should be deterministic enough;
+- decoded waveform or audio features for audio pipelines;
+- separate video and audio targets for joint AV pipelines unless a validated
+  joint metric exists.
+
+Debug pipeline drift in this order:
+
+1. Confirm both sides use the same component weights and component parity PASS
+   results are still valid.
+2. Align official and FastVideo call arguments, presets, and default values.
+3. Align scheduler timesteps, sigmas/noise levels, prediction type, flow shift,
+   guidance math, and secondary-guidance branches.
+4. Align RNG: initial latents/noise, generator device, seed, per-step noise, VAE
+   sampling, and any official `+1 frame` or crop/slice behavior.
+5. Align conditioning: prompt templates, negative prompts, masks, image/audio
+   preprocessing, modality packing, text truncation, and dtype/autocast.
+6. Align decode: latent scaling, per-channel mean/std, tiling flags, output
+   channel order, sample rate, FPS, and final slicing.
+7. Add targeted stage-level diagnostics to identify the first divergent stage.
+
+If stage diagnostics show the first bad stage is transformer/denoising or a
+mid-DiT block, enable activation trace before adding ad hoc pipeline prints; see
+`docs/contributing/activation_trace.md` and `../add-model-08-trace/SKILL.md`.
+Keep `FASTVIDEO_TRACE_LAYERS`, `FASTVIDEO_TRACE_STATS`, and
+`FASTVIDEO_TRACE_STEPS` identical across reruns so pipeline parity traces diff
+one-to-one.
+
+If the first divergence belongs to component implementation, strict loading, or
+conversion mapping, stop pipeline edits and return `next_step=return_to_phase_6`
+with the exact failing evidence. Do not patch conversion from this skill.
+
+## Stage And Variant Rules
+
+- Canonical video T2V order: `InputValidationStage`, `TextEncodingStage`,
+  `ConditioningStage`, `TimestepPreparationStage`, `LatentPreparationStage`,
+  `DenoisingStage`, `DecodingStage`.
+- Canonical video I2V delta adds image loading/encoding and image VAE encoding in
+  the official order, commonly: `TextEncodingStage`, `ImageEncodingStage`,
+  `ConditioningStage`, `TimestepPreparationStage`, `LatentPreparationStage`,
+  `ImageVAEEncodingStage`, `DenoisingStage`, `DecodingStage`.
+- Treat `ConditioningStage` as default-present for Wan-style pipelines, but still
+  follow the reference if another family truly skips or replaces it.
+- T2V video pipelines usually use validation, text encoding, conditioning,
+  timestep preparation, latent preparation, denoising, and decoding.
+- I2V adds image loading/encoding and image-latent preparation according to the
+  official pipeline, not by assuming CLIP or Wan-specific branches.
+- Pick image, audio, and video encoders from the reference. Do not assume CLIP or
+  any other common encoder unless the reference uses it.
+- Cross-attention class names are not prescribed; match the family style and
+  preserve the official tensor contract.
+- `WorkloadType` currently has no `T2A`, `A2A`, or `AV` values. Until that enum
+  is extended, audio-only pipelines may register with `WorkloadType.T2V` and
+  preset `workload_type="t2v"` as a compatibility shim, but must document the
+  rationale in code and `PORT_STATUS.md`.
+- Audio-only pipelines should not force real video semantics into presets. Use
+  minimal video-shaped placeholders such as small `height`/`width` and
+  `num_frames=1` only when shared `VideoGenerator`/validation paths require them,
+  and document that the real output is audio.
+- Record modality-specific shape knobs and output contract in the pipeline
+  handoff: video uses `height`, `width`, `num_frames`, and `fps`; audio uses
+  `audio_seconds` and `sampling_rate`; joint AV records both plus whether output
+  is muxed or paired files.
+- Use sibling pipeline classes/configs when required modules, HF repo layout,
+  stage chains, or inputs differ materially.
+- Use one kwargs-driven pipeline class only when variants share weights,
+  modules, stage chain, and safe call semantics.
+- Split later if components diverge, workload tags require separate discovery,
+  signatures become unsafe, or stage branches become substantial.
+- If the DiT branches on `added_kv_proj_dim`, document the T2V/I2V split.
+- If the reference uses `transformer_2`, `boundary_ratio`, `guidance_scale_2`, or
+  DMD step lists, keep those on config, presets, or stages deliberately.
+- Support every official output head in scope. If a head is out of scope, record
+  explicit user approval in `PORT_STATUS.md`.
+
+Pipeline verification order:
+
+```bash
+pytest tests/local_tests/pipelines/test_<family>_pipeline_smoke.py -v -s
+DISABLE_SP=1 pytest -v -s tests/local_tests/pipelines/test_<family>_pipeline_parity.py
+python examples/inference/basic/basic_<family>.py
+```
+
+Smoke tests prove loadability only. They are not a substitute for numerical
+component or pipeline parity.
+
+## Escape Hatches
+
+Follow `../add-model/shared/common_rules.md`. Pipeline-specific ask cases include
+dropping a public mode, modality, or output head; adding a new workload enum;
+changing official defaults for user-facing behavior; accepting a known pipeline
+parity blocker; running GPU-heavy quality work outside the agreed scope; or
+publishing/uploading generated references or converted weights.
+
+## Handoff
+
+Return `../add-model/contracts/pipeline_handoff.md` and update the shared state
+files before handoff.
+
+Do not hand back a green pipeline if smoke or parity skipped locally. A skip is a
+setup gap, not a pass.
+
+## References
+
+- `fastvideo/pipelines/composed_pipeline_base.py` for module loading and stage
+  execution.
+- `fastvideo/pipelines/basic/wan/` for standard video T2V/I2V/DMD variants.
+- `fastvideo/pipelines/basic/stable_audio/` for audio-specific stage composition.
+- `fastvideo/configs/pipelines/stable_audio.py` and
+  `fastvideo/pipelines/basic/stable_audio/presets.py` for config/preset shape.
+- `fastvideo/registry.py` for `register_configs(...)` and preset registration.
+- `tests/local_tests/pipelines/test_gamecraft_pipeline_parity.py` for latent
+  parity structure.
+- `tests/local_tests/pipelines/test_stable_audio_pipeline_parity.py` for audio
+  parity structure.
+- `tests/local_tests/pipelines/test_stable_audio_pipeline_smoke.py` for no-GPU
+  import/registry/preset preflight shape.

.agents/skills/add-model-09-pipeline/templates/pipeline_parity_test.py

@@ -0,0 +1,147 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Pipeline parity scaffold for TODO_MODEL_FAMILY.
+
+Copy this file to
+`tests/local_tests/pipelines/test_<family>_pipeline_parity.py` and replace every
+TODO before treating it as an executable scaffold.
+
+The filled test should compare denoised latents, decoded media, audio waveform,
+or another concrete output from the official pipeline against FastVideo. A
+successful generation without tensor/media comparison is not parity.
+"""
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+from typing import Any
+
+import pytest
+import torch
+from torch.testing import assert_close
+
+_REPO_ROOT = Path(__file__).resolve().parents[3]
+_MODEL_FAMILY = "TODO_MODEL_FAMILY"
+_OFFICIAL_REF_ENV = "TODO_OFFICIAL_REF_PATH"
+_OFFICIAL_REF_DEFAULT = _REPO_ROOT / "TODO_OFFICIAL_REF_DIR"
+_FASTVIDEO_MODEL_ENV = "TODO_FASTVIDEO_MODEL_PATH"
+_FASTVIDEO_MODEL_DEFAULT = _REPO_ROOT / "converted_weights" / _MODEL_FAMILY
+
+
+def _path_from_env(env_name: str, default: Path) -> Path:
+    return Path(os.getenv(env_name, str(default))).expanduser()
+
+
+def _add_official_to_path() -> Path:
+    official_path = _path_from_env(_OFFICIAL_REF_ENV, _OFFICIAL_REF_DEFAULT)
+    if not official_path.exists():
+        pytest.skip(f"Official reference not found at {official_path}")
+    if str(official_path) not in sys.path:
+        sys.path.insert(0, str(official_path))
+    return official_path
+
+
+def _log_tensor_stats(label: str, tensor: torch.Tensor) -> None:
+    value = tensor.detach().float()
+    print(f"[{_MODEL_FAMILY} PIPELINE] {label}: shape={tuple(tensor.shape)} "
+          f"dtype={tensor.dtype} device={tensor.device} "
+          f"min={value.min().item():.6f} max={value.max().item():.6f} "
+          f"mean={value.mean().item():.6f} std={value.std().item():.6f}")
+
+
+def _extract_tensor(output: Any, key: str) -> torch.Tensor:
+    if isinstance(output, dict):
+        value = output.get(key)
+    else:
+        value = getattr(output, key, None)
+    if value is None:
+        raise AssertionError(f"Pipeline output did not contain {key!r}")
+    if not torch.is_tensor(value):
+        try:
+            import numpy as np
+            value = torch.from_numpy(np.asarray(value))
+        except Exception as exc:  # pragma: no cover - scaffold guard
+            raise AssertionError(f"Could not convert {key!r} to tensor") from exc
+    return value.detach().float().cpu()
+
+
+def _run_official_pipeline(
+    official_path: Path,
+    params: dict[str, Any],
+    device: torch.device,
+) -> Any:
+    del official_path, params, device
+    pytest.skip("TODO: import the official pipeline/factory, load official weights, "
+                "run with params, and return the comparison target.")
+
+
+def _run_fastvideo_pipeline(model_path: Path, params: dict[str, Any]) -> Any:
+    from fastvideo import VideoGenerator
+
+    generator = VideoGenerator.from_pretrained(
+        str(model_path),
+        num_gpus=1,
+        use_fsdp_inference=False,
+        dit_cpu_offload=False,
+        vae_cpu_offload=False,
+        text_encoder_cpu_offload=False,
+    )
+    try:
+        return generator.generate_video(
+            prompt=params["prompt"],
+            negative_prompt=params.get("negative_prompt"),
+            output_path=f"outputs_{_MODEL_FAMILY}/pipeline_parity",
+            save_video=False,
+            height=params.get("height"),
+            width=params.get("width"),
+            num_frames=params.get("num_frames"),
+            fps=params.get("fps"),
+            num_inference_steps=params["num_inference_steps"],
+            guidance_scale=params.get("guidance_scale"),
+            seed=params["seed"],
+        )
+    finally:
+        generator.shutdown()
+
+
+@pytest.mark.skipif(
+    not torch.cuda.is_available(),
+    reason="TODO_MODEL_FAMILY pipeline parity requires CUDA.",
+)
+def test_todo_model_family_pipeline_official_parity() -> None:
+    official_path = _add_official_to_path()
+    fastvideo_model_path = _path_from_env(
+        _FASTVIDEO_MODEL_ENV,
+        _FASTVIDEO_MODEL_DEFAULT,
+    )
+    if not fastvideo_model_path.exists():
+        pytest.skip(f"FastVideo model path not found at {fastvideo_model_path}")
+
+    device = torch.device("cuda:0")
+    params = {
+        "prompt": "TODO: stable parity prompt",
+        "negative_prompt": "",
+        "height": 64,
+        "width": 64,
+        "num_frames": 9,
+        "fps": 8,
+        "num_inference_steps": 4,
+        "guidance_scale": 1.0,
+        "seed": 0,
+    }
+
+    official_output = _run_official_pipeline(official_path, params, device)
+    fastvideo_output = _run_fastvideo_pipeline(fastvideo_model_path, params)
+
+    comparison_key = "TODO_COMPARISON_KEY"
+    official_tensor = _extract_tensor(official_output, comparison_key)
+    fastvideo_tensor = _extract_tensor(fastvideo_output, comparison_key)
+
+    _log_tensor_stats("official", official_tensor)
+    _log_tensor_stats("fastvideo", fastvideo_tensor)
+    assert official_tensor.shape == fastvideo_tensor.shape
+
+    diff = (official_tensor - fastvideo_tensor).abs()
+    print(f"diff max={diff.max().item():.6f} "
+          f"mean={diff.mean().item():.6f} median={diff.median().item():.6f}")
+    assert_close(fastvideo_tensor, official_tensor, atol=1e-2, rtol=1e-2)

.agents/skills/add-model-10-pr-review/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: add-model-10-pr-review
+description: Review rubric for FastVideo PRs that add or modify model families, variants, first-class components, checkpoint conversion, pipelines, parity coverage, or generated-media quality baselines. Use when reviewing a PR whose diff touches fastvideo/models/, fastvideo/pipelines/basic/, fastvideo/registry.py, scripts/checkpoint_conversion/, fastvideo/tests/ssim/, or related model-port surfaces. Pairs with review-pr-link as a project-scoped review pass; produces findings, not fixes.
+---
+
+# Add-Model PR Review
+
+Use this skill when a reviewed PR appears to add, port, or substantially modify
+a FastVideo model family, model variant, first-class model component,
+checkpoint conversion, model pipeline, or local parity coverage.
+
+This is a review skill, not an implementation workflow. Do not run `/add-model`
+or start writing missing port code during review. Use the add-model skill stack
+as a rubric for findings.
+
+## Trigger Paths
+
+Trigger this skill if `git diff --name-only <base>...HEAD` includes any of:
+
+- `fastvideo/models/dits/`, `fastvideo/configs/models/dits/`
+- `fastvideo/models/vaes/`, `fastvideo/configs/models/vaes/`
+- `fastvideo/models/encoders/`, `fastvideo/configs/models/encoders/`
+- `fastvideo/models/schedulers/`, `fastvideo/configs/models/schedulers/`
+- `fastvideo/models/upsamplers/`, `fastvideo/configs/models/upsamplers/`
+- `fastvideo/models/audio/`, `fastvideo/configs/models/audio/`
+- `fastvideo/pipelines/basic/`, `fastvideo/configs/pipelines/`
+- `fastvideo/registry.py`, `fastvideo/api/sampling_param.py`
+- `scripts/checkpoint_conversion/`
+- `examples/inference/basic/`
+- `tests/local_tests/`, especially component or pipeline parity tests
+- `fastvideo/tests/ssim/` or other quality-regression tests for generated media
+
+Also trigger when the PR title/body claims a new model, model variant, VAE,
+encoder, scheduler, conditioner, pipeline, conversion script, or generated-media
+quality baseline even if the path list is incomplete.
+
+## Review Inputs
+
+Read these add-model references as review checklists:
+
+- `../add-model/SKILL.md`: phase gates and final handoff requirements.
+- `../add-model/shared/common_rules.md`: token/auth safety, production import
+  boundaries, state files, and skip/pass semantics.
+- `../add-model/contracts/final_handoff.md`: final evidence expected from a
+  complete port.
+- `../add-model/contracts/component_context.md` and
+  `../add-model/contracts/component_skill_handoff.md`: component evidence and
+  parity-debug expectations.
+- `../add-model/contracts/conversion_request.md` and
+  `../add-model/contracts/conversion_handoff.md`: conversion evidence,
+  strict-load status, config validation, and retry context.
+- `../add-model/contracts/pipeline_context.md` and
+  `../add-model/contracts/pipeline_handoff.md`: pipeline class/stage/config/
+  preset/registry/example evidence.
+
+Then read only the satellite skill(s) that match touched areas:
+
+- DiT/transformer changes: `../add-model-03-port-dit/SKILL.md`.
+- VAE changes: `../add-model-04-port-vae/SKILL.md`.
+- Encoder/conditioner changes: `../add-model-05-port-encoder/SKILL.md`.
+- Scheduler/upsampler/vocoder/other components:
+  `../add-model-06-port-generic/SKILL.md`.
+- Component parity tests: `../add-model-02-parity/SKILL.md`.
+- Checkpoint conversion: `../add-model-07-conversion/SKILL.md`.
+- Pipeline/config/presets/registry/examples:
+  `../add-model-09-pipeline/SKILL.md`.
+- Prep/state docs: `../add-model-01-prep/SKILL.md`.
+
+## Required Review Lanes
+
+For a full model-family or model-variant PR, cover all lanes. For a
+component-only PR, cover the component, conversion/parity as applicable, and the
+documented downstream consumer.
+
+1. Scope and source-of-truth lane:
+   Verify the PR clearly identifies the official reference, weights/revision,
+   supported variants, modalities, output heads, and any approved scope cuts.
+
+2. Component lane:
+   Verify each required component is FastVideo-native or has a documented and
+   accepted lazy-wrapper exception. Check bucket/config inheritance, `EntryClass`,
+   state-dict surface, reused-component evidence, and output heads.
+
+3. Conversion lane:
+   Verify mappings are derived from prototype key/shape dumps, source layout is
+   supported, skipped keys are intentional, emitted configs validate through
+   production paths, component strict-load status is recorded, `model_index.json`
+   library tokens match loaders, and revisions are pinned when converting from
+   HF.
+
+4. Component parity lane:
+   Verify local parity tests exist for every required component, including reused
+   components. Scaffolds may skip in CI, but the PR must provide local non-skip
+   PASS evidence or an explicit accepted blocker.
+
+5. Pipeline lane:
+   Verify stage order, required modules, `_class_name` / `EntryClass.__name__`
+   resolution, config defaults, presets, `SamplingParam` fields, registry
+   registration, examples, smoke tests, and pipeline parity.
+
+6. Quality and evidence lane:
+   Verify media quality regression is added or explicitly deferred, examples run,
+   generated outputs are non-corrupt, `tests/local_tests/<family>/README.md` and
+   `PORT_STATUS.md` are current, and final blockers are surfaced in the review.
+
+## Findings To Prioritize
+
+Prioritize review findings in this order:
+
+- Missing or skipped required component parity without accepted blocker.
+- Pipeline parity/smoke/example missing or skipped for a pipeline PR.
+- Conversion emits unloadable or unvalidated configs/weights.
+- Wrong `model_index.json` `_class_name`, component library token, or registry
+  class resolution.
+- Runtime diffusers/transformers model-class imports for components that own
+  weights or numerical behavior.
+- Dropped modalities, output heads, variants, or conditioning streams without
+  explicit approval.
+- Reused FastVideo component lacks exact definition/instantiation proof or
+  non-skip parity.
+- Public generation kwargs/preset defaults missing from `SamplingParam`.
+- Tests only check shapes, importability, or successful generation without
+  numerical/media comparison.
+- Tokens, credentials, reference clones, staged weights, or generated bulk assets
+  committed to the PR.
+
+## Output Format
+
+Write normal code-review findings first, ordered by severity. Include file and
+line references from the PR diff when possible.
+
+Use this phrasing for missing add-model evidence:
+
+```text
+This PR does not satisfy the add-model <component|conversion|pipeline|final>
+gate because <specific required evidence> is missing. The risk is <runtime load,
+numerical parity, dropped output, registry resolution, etc.>.
+```
+
+Keep the summary short. Mention which lanes were reviewed and which could not be
+verified because assets, GPU time, or external credentials were unavailable.

.agents/skills/add-model/SKILL.md

@@ -0,0 +1,438 @@
+---
+name: add-model
+description: Manual /add-model workflow for implementing a FastVideo model or first-class component port after add-model-01-prep has staged reference code and weights. Organizes the port into numbered phases with conversion rules, component policies, parity gates, and handoff checks.
+---
+
+# Add Model
+
+## Manual Invocation
+
+This skill is for explicit `/add-model` use only. Do not auto-start it from a
+casual model-port mention. The setup-only workflow is
+`../add-model-01-prep/SKILL.md`.
+
+## Goal
+
+Port a new FastVideo model family, model variant, or first-class reusable
+component so it can be loaded through FastVideo's native model, config, stage,
+registry, preset, and test infrastructure.
+
+FastVideo has one pipeline architecture: stage-based composition via
+`ComposedPipelineBase`. Vary the stages and modules, not the architecture.
+
+## Scope Shapes
+
+Use this skill for either shape:
+
+| Shape | Required output |
+|---|---|
+| Full model family or variant | Native components, conversion if needed, pipeline config/class, presets, registry, smoke test, local parity tests, example, quality regression. |
+| First-class component contribution | Native component class/config, bucket export, component parity test, and a documented downstream pipeline that will consume it. Skip pipeline/preset/registry rows only when the contribution is intentionally component-only. |
+
+If upstream ships many variants, lock scope before coding. "Base model" means
+checkpoint variant, not a modality subset. If the base checkpoint produces
+audio, pose, depth, masks, or other output heads, either support those outputs
+or get explicit user agreement to drop them.
+
+## Required Input
+
+Start from an `add-model-01-prep` handoff, or equivalent fields matching
+`contracts/prep_handoff.md`.
+
+Before Phase 0, read the shared rules and all relevant schemas:
+
+- `shared/common_rules.md`
+- `contracts/prep_handoff.md`
+- `contracts/port_state.md`
+- `contracts/escape_hatch.md`
+- `contracts/component_context.md`
+- `contracts/parity_status.md`
+- `contracts/conversion_request.md`
+- `contracts/conversion_handoff.md`
+- `contracts/component_skill_handoff.md`
+- `contracts/pipeline_context.md`
+- `contracts/pipeline_handoff.md`
+- `contracts/final_handoff.md`
+
+## Hard Rules
+
+- Follow `shared/common_rules.md` for token/auth safety, state files, escape
+  hatches, production import boundaries, and skip/pass semantics.
+- If the prep handoff is missing or ambiguous, stop and run
+  `../add-model-01-prep/SKILL.md`.
+- If a needed component is not ported, do not ship the pipeline that needs it.
+- Wan is grandfathered for missing local parity; do not copy its missing-test
+  precedent for new work.
+
+## Escape Hatches
+
+Follow `shared/common_rules.md` and `contracts/escape_hatch.md`. The main
+orchestrator should ask only when no phase skill can safely continue under the
+shared rules.
+
+## Files Map
+
+| Area | Paths |
+|---|---|
+| DiT | `fastvideo/models/dits/<family>.py`, `fastvideo/configs/models/dits/<family>.py`, bucket `__init__.py`. |
+| VAE | `fastvideo/models/vaes/<arch_or_family>.py`, `fastvideo/configs/models/vaes/<arch_or_family>.py`, bucket `__init__.py`. Name by shared arch when reusable (`oobleck.py`, `autoencoder_kl.py`), otherwise by family (`wanvae.py`). |
+| Encoder / conditioner / scheduler / upsampler | Native class/config in the matching `fastvideo/models/<bucket>/` and `fastvideo/configs/models/<bucket>/` bucket. |
+| Lazy loader wrapper | Optional `fastvideo/models/<bucket>/<family>_loader.py` or similar thin `nn.Module` wrapper when a component is fetched from an external HF repo and should be hidden from host-pipeline state-dict matching. |
+| Conversion | `scripts/checkpoint_conversion/<family>_to_diffusers.py` only when `needs_conversion=yes`. |
+| Pipeline | `fastvideo/pipelines/basic/<family>/<family>_pipeline.py` plus sibling files for variants whose components or required modules differ. |
+| Pipeline config | `fastvideo/configs/pipelines/<family>.py` or `fastvideo/pipelines/basic/<family>/pipeline_configs.py`. |
+| Stages | `fastvideo/pipelines/basic/<family>/stages/` only for model-specific stage subclasses. |
+| Presets / registry | `fastvideo/pipelines/basic/<family>/presets.py`, `fastvideo/registry.py`. |
+| Tests | Component parity under `tests/local_tests/<bucket>/`; pipeline smoke/parity under `tests/local_tests/pipelines/`; CI-backed quality tests under `fastvideo/tests/`. |
+| Example | `examples/inference/basic/basic_<family>*.py`, one per public mode/variant. |
+
+## Phase 0: Scope And Handoff Gate
+
+1. Validate every required handoff field.
+2. Resolve `needs_conversion=unknown` before component work:
+
+```bash
+python ".agents/skills/add-model-01-prep/scripts/inspect_hf_layout.py" \
+    "<hf-or-local-path>" \
+    --json
+```
+
+3. List first-PR scope across both axes:
+   - Variant axis: base, distill, SR/refine, causal, DMD, I2V, V2V, etc.
+   - Modality axis: video, image, audio, pose, depth, masks, text, etc.
+4. For component-only work, explicitly name the downstream full-pipeline PR or
+   planned consumer.
+5. Confirm `official_env_status` is `imports_ok` or
+   `private_deps_need_stubs`. If it is `blocked`, return to
+   `../add-model-01-prep/SKILL.md` before parity scaffolding.
+6. Confirm `local_tests_readme` exists and records official setup, HF weights,
+   dependency changes, and planned parity commands for reviewers.
+7. Confirm `port_state_file` exists, follows `contracts/port_state.md`, and has
+   rows for open questions/issues found during prep.
+8. If there are multiple official implementations, choose the one whose
+   architecture matches the published weights. A blessed library port can be a
+   better parity reference than a highly configurable research repo; document
+   the choice in tests.
+
+## Phase 1: Reference And Architecture Study
+
+Read the official pipeline call path before writing code.
+
+Record:
+
+- Required modules from `model_index.json` or equivalent: transformer, VAE,
+  text encoders, tokenizers, scheduler, image encoders, audio VAE, vocoder,
+  conditioners, upsamplers.
+- Input/output modalities and every dedicated DiT output head.
+- Text/image/audio encoding flow, latent shape, dtype, scaling, packing,
+  scheduler/timestep math, guidance math, VAE normalization, and decode flow.
+- Whether the official code relies on private deps, custom ops, or special
+  kernels that parity tests must stub.
+
+Arch config rule:
+
+- `ArchConfig` fields must match the emitted per-component config, especially
+  `transformer/config.json`, one-to-one.
+- Pipeline knobs do not belong on the DiT arch config: inference steps, CFG
+  scales, flow shift, FPS, VAE stride, text target length, data-proxy knobs,
+  eval defaults, and sampling defaults go on `PipelineConfig`, presets, or
+  stages.
+- If the HF repo is raw or has empty configs, synthesize
+  `transformer/config.json` from the official Python model-config class, not
+  from data/eval config classes.
+
+## Phase 2: Early Parity Scaffolding
+
+Create component parity tests before or alongside implementation. Use
+`../add-model-02-parity/SKILL.md` and its `templates/component_parity_test.py`.
+The official reference must import in the current FastVideo environment, or the
+prep handoff must identify private deps that will be stubbed locally for tests.
+Use `local_tests_readme` as the reviewer-facing source for setup commands and
+update its planned test table as parity scaffolds are added.
+
+This phase is early by design:
+
+- Official loading can be implemented from the reference study.
+- FastVideo loading can target planned standardized class/config/loader paths.
+- Tests may initially skip because the FastVideo class or converted weights do
+  not exist yet.
+- The scaffold must still contain real official loading, deterministic inputs,
+  output extraction, and concrete tensor comparisons. No unconditional skips,
+  no shape-only tests.
+
+Use subagents here: dispatch one parity-test subagent per required component,
+including components that may be reused. Their output becomes the red/skip
+target that porting or reuse-verification subagents make pass later.
+
+## Phase 3: Reuse Gate And Component Dispatch
+
+Build a component inventory before implementation:
+
+| Field | Meaning |
+|---|---|
+| Component | transformer, VAE, text encoder, image encoder, scheduler, conditioner, upsampler, vocoder, etc. |
+| Official definition | Repo-relative source file, class/function name, and relevant line/range if known. |
+| Official instantiation | Repo-relative pipeline/config/factory call site plus constructor args and runtime flags. |
+| FastVideo target | Existing class to reuse or new bucket/file/config to add. |
+| Parity test | Required local test path, including reused components. |
+| Status | `reuse_pending`, `reuse_proven`, `port_pending`, `non_skip_pass`, or `blocked`. |
+
+Reuse is allowed only from the checked-out FastVideo tree. Do not wait for or
+depend on an open PR adding a native class; add the native port directly in this
+PR if the current tree cannot be reused.
+
+Reuse decision:
+
+1. Record exact official definition and instantiation evidence for every
+   component.
+2. If an existing FastVideo class and config match both definition and
+   instantiation, pass that reused target to the bucket-specific skill in
+   `mode=prototype` and require reuse evidence plus key/shape dumps.
+3. If either definition or instantiation differs, port the component directly as
+   FastVideo-native code through the bucket-specific skill.
+4. Reused components still require non-skip component parity against the exact
+   official instantiation used by the target pipeline.
+
+Porting subagent dispatch:
+
+- Dispatch one subagent per component after Phase 2 parity scaffolds exist.
+- Use `../add-model-03-port-dit/SKILL.md` for DiTs/transformers.
+- Use `../add-model-04-port-vae/SKILL.md` for VAEs.
+- Use `../add-model-05-port-encoder/SKILL.md` for text, image, audio, or compound
+  encoders/conditioners that fit the encoder config bucket.
+- Use `../add-model-06-port-generic/SKILL.md` for schedulers, upsamplers,
+  vocoders, adapters, preprocessors, or unknown components.
+- Each subagent owns one component only and must loop on that component's local
+  parity test until it produces a non-skip PASS or returns a precise blocker.
+
+Every component subagent must receive a complete packet matching
+`contracts/component_context.md`. If any required path is unknown, pass `unknown`
+plus the exact search already performed. Do not silently omit ambiguous official
+files or prototype concerns.
+
+Bucket, layer, and attention rules live in the bucket-specific skills and
+`fastvideo/layers/AGENTS.md`.
+
+## Phase 4: Native Component Prototype
+
+Conversion needs a FastVideo state-dict surface. Use the Phase 3
+bucket-specific skill in `mode=prototype` for every required component, including
+reused components.
+
+Prototype success criteria:
+
+- the FastVideo-native or reused class/config can import and instantiate with the
+  exact official architecture args;
+- official and FastVideo key/shape dumps exist for every stateful component;
+- `local_tests_readme` and `port_state_file` record prototype status and concerns;
+- the returned handoff matches `contracts/component_skill_handoff.md`.
+
+Do not chase numerical parity in Phase 4. Prototype mode ends when conversion has
+the key/shape surface it needs, or when the component skill returns a precise
+blocker or escape hatch.
+
+## Phase 5: Param Mapping And Weight Conversion
+
+Use `../add-model-07-conversion/SKILL.md` after Phase 4 prototypes exist.
+Send a request matching `contracts/conversion_request.md`; consume the returned
+`contracts/conversion_handoff.md` update before Phase 6.
+
+Use the prep handoff's `needs_conversion` value:
+
+- `no`: verify the source already has the component layout FastVideo loaders can
+  consume, then record any passthrough components.
+- `yes`: write `scripts/checkpoint_conversion/<family>_to_diffusers.py` and
+  output `converted_weights/<family>/`.
+- `unknown`: return to Phase 0.
+
+The conversion skill owns source-layout handling, mapping derivation, config and
+`model_index.json` emission, passthrough assets, strict-load verification, and
+Phase 6 retry requests. Component skills must not patch conversion scripts or
+converted weights ad hoc.
+
+## Phase 6: Component Parity Debug
+
+This is the expected expensive loop. Dispatch one subagent per required
+component, including reused components, using the bucket-specific skill in
+`mode=parity-debug`.
+
+Each subagent gets:
+
+- the complete component context packet from Phase 3/4;
+- updated conversion mapping notes and strict-load result from Phase 5;
+- any prototype concerns or unknowns that were not resolved before conversion.
+
+The bucket-specific skills own parity-debug tactics. If a failure belongs to
+conversion, route it through `../add-model-07-conversion/SKILL.md` with a retry
+request matching `contracts/conversion_request.md`, then resume the component
+skill with the updated conversion handoff.
+
+When a component failure narrows to layer-by-layer numerical drift, load
+`../add-model-08-trace/SKILL.md` before writing custom hooks. It uses
+`fastvideo/hooks/activation_trace.py`; canonical env vars and JSONL format are
+documented in `docs/contributing/activation_trace.md`.
+
+Phase 6 ends only when every required component handoff reports
+`parity_status=non_skip_pass`, or when a precise blocker or escape hatch is
+recorded in `port_state_file`.
+
+## Phase 7: Pipeline, Stages, And Variants
+
+Do not start Phase 7 until every required component, reused or ported, has a
+non-skip local parity PASS from Phase 6. If any component parity test is still
+`scaffold_skip`, `debug_red`, `blocked`, or missing, resume Phase 6 first.
+
+Use `../add-model-09-pipeline/SKILL.md` for pipeline definition and parity-debug.
+Send a complete packet matching `contracts/pipeline_context.md`; consume the
+returned `contracts/pipeline_handoff.md` before moving to quality regression or
+final handoff.
+
+The pipeline skill owns:
+
+- pipeline class, stage chain, and optional model-specific stages;
+- pipeline config, presets, registry updates, and examples;
+- official args/defaults/presets comparison before setting FastVideo defaults;
+- pipeline smoke and parity tests;
+- continuous pipeline parity-debug until non-skip PASS or precise blocker;
+- updates to `local_tests_readme` and `port_state_file`.
+
+The pipeline handoff must explicitly cover stage order, variants, modality and
+output-head handling, config/preset/registry/example status, smoke/parity tests,
+and any return-to-Phase-6 evidence.
+
+## Phase 8: PipelineConfig, Presets, Registry, Examples
+
+This phase is implemented through `../add-model-09-pipeline/SKILL.md` after the
+Phase 7 component-parity gate passes. Accept the pipeline handoff only if it
+covers configs, presets, registry detection/exact class resolution, examples,
+new `SamplingParam` fields for public kwargs/defaults, and local smoke/parity
+status. Detailed rules live in `../add-model-09-pipeline/SKILL.md`.
+
+## Phase 9: Parity Activation And Local Verification
+
+Local parity is author-run, not CI-enforced. CI may only run package-level
+quality tests later. Before handoff, Phase 2 scaffolds must be activated into
+non-skip PASS results.
+
+Order is mandatory:
+
+1. Run conversion if needed.
+2. Run component parity for every required component, including reused ones.
+3. Run pipeline smoke.
+4. Run pipeline parity.
+5. Run the basic example.
+
+If pipeline smoke or parity points back to component implementation,
+strict-load, or conversion mapping, return to Phase 6 or Phase 5 rather than
+patching around the issue in the pipeline.
+
+Skip policy:
+
+- Follow `shared/common_rules.md`: a committed local test may skip for absent
+  clones/weights, but a local skip is not a verified pass.
+
+Use the commands and tolerance guidance from `../add-model-02-parity/SKILL.md` for
+component checks and from `../add-model-09-pipeline/SKILL.md` for pipeline smoke,
+pipeline parity, and examples. Record exact commands, status, and blockers in
+`local_tests_readme` and `port_state_file`.
+
+## Phase 10: Quality Regression
+
+Video outputs:
+
+- Add `fastvideo/tests/ssim/test_<family>_similarity.py` when output video
+  quality must be preserved.
+- Seed references through `seed-ssim-references` after the test exists.
+
+Audio outputs:
+
+- SSIM does not apply. Use an audio-specific regression metric such as
+  mel-spectrogram L1, multi-resolution STFT, CLAP cosine, or a project-approved
+  learned metric.
+- Document the metric and hardware/runtime assumptions in the test.
+
+Joint AV outputs:
+
+- Keep video and audio regression checks separate unless there is a validated
+  joint metric.
+
+## Phase 11: Post-Parity Review And Handoff
+
+After parity is green, run a hot-path review before handoff:
+
+- Hoist constant tensor allocations out of sampler/denoising loops.
+- Replace per-step `randn_like` churn with preallocated buffers plus
+  `.normal_()` when safe.
+- Move `torch.backends.*` flag changes to one-shot setup/load paths.
+- Delete `batch.extra` writes that nothing reads.
+- Derive magic constants from configs when possible.
+
+Pre-handoff checklist:
+
+```text
+[ ] Prep handoff is complete and committed nowhere with token values.
+[ ] Conversion was run if needed and output loads with real weights.
+[ ] Every required component, reused or newly ported, has a non-skip local parity PASS.
+[ ] `local_tests_readme` lists every component parity test, command, status, and blocker if any.
+[ ] `port_state_file` has every open question/issue either resolved or listed as an explicit blocker.
+[ ] Any `next_step=ask_user` has a matching `escape_hatch` block and `E###` row.
+[ ] Pipeline smoke has a non-skip local PASS.
+[ ] Pipeline parity has a non-skip local PASS against the official reference.
+[ ] Basic example runs and writes a non-corrupt output.
+[ ] Video SSIM or audio-specific quality regression is added or explicitly deferred.
+[ ] Runtime production code has no diffusers/transformers model-class imports.
+[ ] Production comments are WHY-focused; examples have user-story docstrings.
+[ ] Post-parity hot-path pass is complete.
+```
+
+Ask before deleting any reference clone or staged weights created by
+`add-model-01-prep`. Leave `.gitignore` entries so future parity assets stay
+untracked. Never commit the clone, weights, `.env`, credentials, or anything
+matching `*secret*`.
+
+## References
+
+- `../add-model-01-prep/SKILL.md` for user-input collection, HF inspection,
+  weight staging, reference cloning, and setup handoff.
+- `contracts/` for canonical handoff schemas used by prep, parity, conversion,
+  component porting, escape hatches, and final handoff.
+- `../add-model-02-parity/SKILL.md` for early component parity scaffolds and
+  activation templates.
+- `../add-model-07-conversion/SKILL.md` for Phase 5 mapping, conversion scripts,
+  monolithic checkpoint splitting, and strict-load checks.
+- `../add-model-03-port-dit/SKILL.md`, `../add-model-04-port-vae/SKILL.md`,
+  `../add-model-05-port-encoder/SKILL.md`, and
+  `../add-model-06-port-generic/SKILL.md` for component subagent implementation
+  and parity-debug loops.
+- `../add-model-09-pipeline/SKILL.md` for pipeline definition, config/preset/
+  registry/example wiring, smoke tests, and pipeline parity-debug.
+- `fastvideo/layers/AGENTS.md` for native layer selection and state-dict surface
+  guidance.
+- `docs/contributing/coding_agents.md` for narrative context.
+- `docs/design/overview.md` for pipeline/config/registry architecture.
+- `fastvideo/pipelines/basic/wan/` for standard T2V/I2V/DMD/Causal variants.
+- `fastvideo/pipelines/basic/ltx2/` for non-standard stages and audio/video
+  patterns.
+- `tests/local_tests/pipelines/test_gamecraft_pipeline_parity.py` for pipeline
+  parity shape.
+- `tests/local_tests/transformers/test_ltx2.py`,
+  `tests/local_tests/vaes/test_ltx2_vae.py`, and
+  `tests/local_tests/encoders/test_ltx2_gemma_parity.py` for component parity.
+- `scripts/checkpoint_conversion/convert_ltx2_weights.py` for modern conversion
+  script shape.
+- `scripts/checkpoint_conversion/wan_to_diffusers.py` for legacy regex mapping
+  reference only.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-04-24 | Initial FastVideo add-model workflow. |
+| 2026-04-30 | Split external setup into `add-model-01-prep`. |
+| 2026-04-30 | Rewrote as manual `/add-model` phase workflow and incorporated prior review decisions. |
+| 2026-04-30 | Extracted early parity scaffolding into `add-model-02-parity` and moved it before conversion/component implementation. |
+| 2026-04-30 | Added component reuse proof gate, bucket-specific porting skills, and parity PASS requirement for reused components. |
+| 2026-04-30 | Split prototype, conversion, and parity-debug phases; added conversion skill for monolithic and separate checkpoint layouts. |
+| 2026-04-30 | Extracted handoff schemas into `contracts/` for shared use across skills. |
+| 2026-04-30 | Added pipeline skill contract and Phase 7 component-parity gate. |
+| 2026-04-30 | Added escape-hatch contract for user decisions and `ask_user` handoffs. |

.agents/skills/add-model/contracts/README.md

@@ -0,0 +1,29 @@
+# Add Model Contracts
+
+Canonical handoff schemas for the `/add-model` workflow. When a skill needs to
+send or receive structured context, use these files instead of inventing a local
+schema.
+
+| Contract | Use |
+|---|---|
+| `prep_handoff.md` | `add-model-01-prep` output and `/add-model` Phase 0 input. |
+| `port_state.md` | Per-port `PORT_STATUS.md` file tracking progress, open questions, and issues. |
+| `escape_hatch.md` | Shared pause-and-ask schema for user decisions the workflow cannot safely choose. |
+| `component_context.md` | Per-component packet passed to parity, prototype, conversion, and parity-debug subagents. |
+| `parity_status.md` | `add-model-02-parity` scaffold/activation status returned to `/add-model`. |
+| `conversion_request.md` | Phase 5 conversion input and Phase 6 conversion retry request. |
+| `conversion_handoff.md` | `add-model-07-conversion` output back to `/add-model` and component subagents. |
+| `component_skill_handoff.md` | Component porting skill output in prototype or parity-debug mode. |
+| `pipeline_context.md` | Phase 7 packet passed to `add-model-09-pipeline` after component parity is green. |
+| `pipeline_handoff.md` | `add-model-09-pipeline` output back to `/add-model` after pipeline definition or parity-debug. |
+| `final_handoff.md` | Final `/add-model` pre-handoff checklist summary. |
+
+Rules:
+
+- Do not omit required fields. Use `unknown` plus the search already performed
+  when the value is not known yet.
+- Do not include raw token values. Use env var names only.
+- Keep model-specific mapping details in conversion scripts and the local tests
+  README/status notes, not in generic skill docs.
+- Use `next_step=ask_user` only with an `escape_hatch` block matching
+  `escape_hatch.md`.

.agents/skills/add-model/contracts/component_context.md

@@ -0,0 +1,55 @@
+# Component Context Contract
+
+Canonical per-component packet passed from `/add-model` to parity, prototype,
+conversion, and parity-debug subagents.
+
+```text
+component_context:
+  model_family: <snake_case>
+  component: <name>
+  component_type: <dit|vae|encoder|scheduler|conditioner|upsampler|vocoder|generic>
+  mode: parity-scaffold | prototype | parity-debug
+  official_ref_dir: <path or import path>
+  official_definition_files:
+    - path: <repo-relative or absolute path in official repo>
+      symbols: <class/function names>
+      notes: <layer graph, output contract, state-dict owner>
+  official_instantiation_files:
+    - path: <repo-relative or absolute path in official repo>
+      symbols: <factory/pipeline/config names>
+      args: <constructor args, config values, runtime flags>
+  official_weight_source: <checkpoint file, subfolder, prefix, or passthrough source>
+  fastvideo_target_files:
+    - fastvideo/models/<bucket>/<file>.py
+    - fastvideo/configs/models/<bucket>/<file>.py
+  local_tests_readme: tests/local_tests/<model_family>/README.md
+  port_state_file: tests/local_tests/<model_family>/PORT_STATUS.md
+  parity_test: tests/local_tests/<bucket>/test_<family>_<component>_parity.py
+  prototype_key_dumps:
+    official: converted_weights/<family>/_mapping/<component>_official_keys.json | planned | unknown
+    fastvideo: converted_weights/<family>/_mapping/<component>_fastvideo_keys.json | planned | unknown
+  conversion:
+    script: scripts/checkpoint_conversion/<family>_to_diffusers.py | not_created | not_needed | unknown
+    converted_component_dir: converted_weights/<family>/<component> | not_created | not_needed | unknown
+    model_index_library: <diffusers|transformers|fastvideo|fastvideo.*|unknown|none>
+    config_file: <config.json|scheduler_config.json|none|unknown>
+    mapping_notes: <key prefixes, split/fuse concerns, skipped keys, not_created, not_needed, or unknown>
+    production_loader_strictness: <strict|non_strict_with_allowed_keys|stateless|unknown>
+    strict_load: <not_run | pass | pass_with_documented_exclusions | blocked>
+  concerns_or_unknowns:
+    - <prototype mismatch, ambiguous arg, missing op, dtype concern, output head, etc.>
+```
+
+Rules:
+
+- If any required path is unknown, pass `unknown` plus the exact search already
+  performed.
+- Do not silently omit ambiguous official files, instantiation args, or prototype
+  concerns.
+- For reused components, still fill every field and set `fastvideo_target_files`
+  to the reused class/config.
+- In `mode=parity-scaffold`, prototype and conversion fields may be `planned`,
+  `not_created`, `not_needed`, or `unknown`; do not invent paths or statuses that
+  do not exist yet.
+- Update `port_state_file` when concerns, issues, conversion status, or parity
+  status change.

.agents/skills/add-model/contracts/component_skill_handoff.md

@@ -0,0 +1,41 @@
+# Component Skill Handoff Contract
+
+Returned by `add-model-03-port-dit`, `add-model-04-port-vae`,
+`add-model-05-port-encoder`, and `add-model-06-port-generic`.
+
+```text
+component: <name>
+mode: prototype | parity-debug
+files_changed: <model/config/export/test/readme paths>
+official_files_used: <definition files, instantiation files>
+prototype_key_dumps: <official path, fastvideo path, or none>
+port_state_file: tests/local_tests/<model_family>/PORT_STATUS.md
+concerns_or_unknowns: <remaining or newly discovered concerns>
+parity_test: <path>
+parity_status: scaffold_skip | debug_red | non_skip_pass | blocked
+production_loader_strictness: strict | non_strict_with_allowed_keys | stateless
+strict_load: pass | pass_with_documented_exclusions | blocked | not_run
+pytest_output: <command + short result>
+blocker: <none or exact missing dependency/weights/numeric mismatch>
+conversion_retry_request: <none or failing keys/shapes/prefixes/evidence for add-model-07-conversion>
+readme_updated: yes | no
+next_step: phase_5_conversion | phase_5_conversion_retry | phase_6_continue | ask_user | blocked
+escape_hatch: <none or block matching contracts/escape_hatch.md>
+```
+
+Rules:
+
+- In `mode=prototype`, parity may be `scaffold_skip` or `blocked`; key dumps are
+  the required artifact. Successful prototype handoff should use
+  `next_step=phase_5_conversion`.
+- In `mode=parity-debug`, final success requires `parity_status=non_skip_pass`.
+- If conversion is implicated, return `conversion_retry_request` and do not edit
+  conversion scripts or converted weights directly.
+- If production loading is non-strict, list allowed missing/unexpected keys in
+  the parity test or handoff and mark `strict_load=pass_with_documented_exclusions`.
+- Update `port_state_file` before returning: component row, open questions,
+  issues/blockers, decisions, and handoff notes.
+- Return an `escape_hatch` only for user decisions, not for normal component
+  implementation or parity-debug failures.
+- Use `next_step=ask_user` only with an `escape_hatch` block and a matching
+  `PORT_STATUS.md` row.

.agents/skills/add-model/contracts/conversion_handoff.md

@@ -0,0 +1,41 @@
+# Conversion Handoff Contract
+
+Returned by `../add-model-07-conversion/SKILL.md` to `/add-model` and component
+parity-debug subagents.
+
+```text
+conversion_script: scripts/checkpoint_conversion/<family>_to_diffusers.py
+source_layout: <diffusers|raw_official|separate_components|monolithic|mixed|custom>
+converted_weights_dir: converted_weights/<model_family>
+port_state_file: tests/local_tests/<model_family>/PORT_STATUS.md
+components_written: <list>
+passthrough_components: <list>
+strict_load: pass | pass_with_documented_exclusions | blocked
+component_context_updates:
+  - component: <name>
+    converted_component_dir: <path>
+    model_index_library: <diffusers|transformers|fastvideo|fastvideo.*>
+    config_file: <path or none>
+    config_validation: pass | blocked | not_applicable
+    mapping_notes: <prefixes, split/fuse ops, skipped keys>
+    production_loader_strictness: strict | non_strict_with_allowed_keys | stateless
+    strict_load: pass | pass_with_documented_exclusions | blocked | not_run
+    retry_resolved: <yes | no | not_a_retry>
+    concerns_or_unknowns: <remaining list>
+blocked_on: <none or exact blocker>
+next_step: phase_6_component_parity_debug | ask_user
+escape_hatch: <none or block matching contracts/escape_hatch.md>
+```
+
+Rules:
+
+- Include strict-load evidence for every stateful converted component.
+- If a component intentionally loads non-strictly, list the exact missing or
+  unexpected keys and why they are safe.
+- Include the actual `model_index.json` library token, config filename, and config
+  validation result for every emitted component.
+- Preserve retry evidence so the requesting component subagent can resume with
+  updated context.
+- Keep `port_state_file` synchronized with `component_context_updates`.
+- Use `next_step=ask_user` only with an `escape_hatch` block and a matching
+  `PORT_STATUS.md` row.

.agents/skills/add-model/contracts/conversion_request.md

@@ -0,0 +1,54 @@
+# Conversion Request Contract
+
+Consumed by `../add-model-07-conversion/SKILL.md` in Phase 5 and during Phase 6
+conversion retries.
+
+Initial conversion request:
+
+```text
+model_family: <snake_case>
+source_layout: diffusers | raw_official | monolithic | separate_components | mixed | custom
+official_weights: <HF repo, local dir, or checkpoint file>
+hf_revision: <revision | default | none>
+converted_weights_dir: converted_weights/<model_family>
+local_tests_readme: tests/local_tests/<model_family>/README.md
+port_state_file: tests/local_tests/<model_family>/PORT_STATUS.md
+components:
+  - name: <transformer|vae|text_encoder|conditioner|scheduler|...>
+    component_type: <dit|vae|encoder|scheduler|conditioner|upsampler|vocoder|generic>
+    official_definition_files: <paths + symbols>
+    official_instantiation_files: <paths + call sites + args>
+    official_weight_source: <checkpoint file, prefix, subfolder, or passthrough source>
+    official_keys: <path to official key/shape dump>
+    fastvideo_keys: <path to FastVideo prototype key/shape dump>
+    fastvideo_class: <class name>
+    model_index_library: <diffusers|transformers|fastvideo|fastvideo.*>
+    config_filename: <config.json|scheduler_config.json|none>
+    production_loader_strictness: <strict|non_strict_with_allowed_keys|stateless>
+    source_prefix_or_path: <prefix or path>
+    parity_test: <component parity test path>
+    prototype_concerns_or_unknowns: <short list>
+```
+
+Retry request from a component skill:
+
+```text
+conversion_retry_request:
+  component: <name>
+  parity_test: <path>
+  failing_keys: <official and FastVideo keys, if known>
+  expected_actual_shapes: <expected vs actual shapes, if known>
+  source_prefix_or_path: <prefix/path implicated by the failure>
+  evidence: <strict-load error, first divergent tensor, parity log excerpt>
+  suspected_fix: <rename | split | fuse | skip | component bucket | config | unknown>
+```
+
+Rules:
+
+- Phase 5 conversion requires Phase 4 official/FastVideo key dumps.
+- Component skills must use the retry request instead of editing conversion
+  scripts or converted weights directly.
+- Conversion must update `port_state_file` with conversion status, retry history,
+  strict-load status, new issues, and resolved issues.
+- Conversion must validate emitted config keys through the production config
+  update path and record the config filename expected by each loader.

.agents/skills/add-model/contracts/escape_hatch.md

@@ -0,0 +1,51 @@
+# Escape Hatch Contract
+
+Canonical pause-and-ask schema for `/add-model` skills. Use this when the next
+action requires user input instead of autonomous debugging.
+
+```text
+escape_hatch:
+  needs_user_input: yes | no
+  decision_type: scope | dependency | auth | cost | destructive | ambiguity | blocker
+  question: <one precise question>
+  recommended_option: <safe recommended choice>
+  options:
+    - <option + consequence>
+  safe_default: <what the agent will do after approval, or none>
+  blocked_until_answered: yes | no
+  state_snapshot:
+    phase: <phase or skill mode>
+    files_changed:
+      - <paths>
+    command_or_test: <last relevant command, or not_run>
+    evidence: <short logs, paths, error text, or blocker ID>
+```
+
+Use `needs_user_input=no` when the handoff is green or the next step is already
+specified by the workflow.
+
+Ask the user only for decisions the workflow cannot safely choose:
+
+- product or PR scope changes, including dropping a modality, output head, or
+  variant;
+- core dependency changes, version pin changes, or installing untrusted/private
+  dependencies;
+- auth setup for gated repos, using env var names only and never token values;
+- large downloads, publishing weights, SSIM/reference uploads, or GPU-heavy work
+  where cost/runtime approval is needed;
+- destructive file/git operations, overwriting existing clones/weights, or
+  deleting staged assets;
+- ambiguous official sources of truth with incompatible behavior;
+- accepting a known blocker, loosening parity/quality tolerances, or shipping
+  without required non-skip parity.
+
+Do not ask for normal recoverable failures:
+
+- missing imports, missing local paths, skipped tests, failing parity, conversion
+  mapping errors, strict-load failures, format/lint failures, or implementation
+  bugs covered by the skill workflow.
+
+Before returning `next_step=ask_user`, update
+`tests/local_tests/<model_family>/PORT_STATUS.md` with the blocker/question ID,
+include the exact evidence, and provide one recommended option plus at most three
+alternatives.

.agents/skills/add-model/contracts/final_handoff.md

@@ -0,0 +1,38 @@
+# Final Handoff Contract
+
+Completed by `/add-model` before handing work back to the user or opening a PR.
+
+```text
+final_handoff:
+  prep_handoff_complete: yes | no
+  conversion_status: not_needed | pass | blocked
+  components:
+    - name: <component>
+      reuse_or_port: reused | ported
+      parity_test: <path>
+      parity_status: non_skip_pass | blocked
+      concerns_or_unknowns: <none or list>
+  pipeline_smoke: pass | blocked | not_run
+  pipeline_parity: pass | blocked | not_run
+  example_status: pass | blocked | not_run
+  quality_regression: added | deferred_with_reason | not_applicable
+  local_tests_readme: tests/local_tests/<model_family>/README.md
+  port_state_file: tests/local_tests/<model_family>/PORT_STATUS.md
+  token_values_committed: no
+  runtime_third_party_model_imports: none | listed_with_rationale
+  blockers: <none or list>
+  escape_hatch: <none or block matching contracts/escape_hatch.md>
+```
+
+Required before handoff:
+
+- Every required component, reused or ported, has non-skip local parity PASS.
+- Pipeline smoke and pipeline parity are non-skip PASS, or a blocker is explicit.
+- Basic example runs and writes a non-corrupt output.
+- `local_tests_readme` lists every component parity command/status/blocker.
+- `port_state_file` has no unresolved blocker that is omitted from the final
+  response or PR notes.
+- No raw HF token values, credentials, `.env`, reference clone, or staged weight
+  blobs are committed.
+- If final handoff is blocked on user input, include an `escape_hatch` block and
+  matching `PORT_STATUS.md` row.

.agents/skills/add-model/contracts/parity_status.md

@@ -0,0 +1,44 @@
+# Parity Status Contract
+
+Returned by `../add-model-02-parity/SKILL.md` to `/add-model` and later updated by
+component parity-debug subagents.
+
+```text
+component_parity:
+  - component: <name>
+    test: tests/local_tests/<bucket>/test_<family>_<component>_parity.py
+    status: scaffold_skip | debug_red | non_skip_pass | blocked
+    missing: <none | fastvideo_class | converted_weights | official_import | ...>
+    coverage_scope: production_loader | implementation_subcomponent | both
+    official_definition_files: <paths>
+    official_instantiation_files: <paths>
+    concerns_or_unknowns: <short list>
+pipeline_parity:
+  test: <path or not-created>
+  status: not_started | scaffold_skip | debug_red | non_skip_pass | blocked
+local_tests_readme: tests/local_tests/<model_family>/README.md
+port_state_file: tests/local_tests/<model_family>/PORT_STATUS.md
+notes: <short list>
+escape_hatch: <none or block matching contracts/escape_hatch.md>
+```
+
+Status meanings:
+
+- `scaffold_skip`: test is present but skips for a specific missing dependency,
+  FastVideo class, or weights.
+- `debug_red`: both sides load and the test fails numerically.
+- `non_skip_pass`: required before final handoff for every required component,
+  including reused components.
+- `blocked`: a precise missing dependency, weight, official call path, or
+  component/conversion regression prevents local activation.
+
+Coverage meanings:
+
+- `production_loader`: FastVideo side loads through the same loader/path used by
+  a pipeline.
+- `implementation_subcomponent`: FastVideo side constructs classes or remaps
+  tensors directly to isolate implementation behavior.
+- `both`: the test covers both production loading and implementation behavior.
+
+Use `escape_hatch` only when blocked status requires a user decision. Normal
+skips or red parity should be debugged by the workflow without asking.

.agents/skills/add-model/contracts/pipeline_context.md

@@ -0,0 +1,82 @@
+# Pipeline Context Contract
+
+Canonical packet passed from `/add-model` to `add-model-09-pipeline` for pipeline
+definition and pipeline parity-debug work.
+
+```text
+pipeline_context:
+  model_family: <snake_case>
+  mode: pipeline-definition | pipeline-parity-debug
+  workload_types:
+    - <T2V|I2V|V2V|T2I|compatibility-shim-with-rationale>
+  modalities:
+    inputs: <text/image/video/audio/pose/depth/mask/etc.>
+    outputs: <video/image/audio/joint-av/latents/etc.>
+  official_ref_dir: <path or import path>
+  official_pipeline_files:
+    - path: <repo-relative or absolute path in official repo>
+      symbols: <pipeline/factory/sample functions>
+      notes: <stage order, mutable state, output contract>
+  official_call:
+    command_or_api: <official CLI, Python call, or package entrypoint>
+    args_and_defaults: <height, width, frames, fps, duration, steps, CFG, scheduler, seeds, etc.>
+    preset_source: <model card, config file, official script, or unknown>
+    scheduler_and_rng: <timestep/sigma/noise/generator behavior>
+    output_contract: <decoded media, denoised latents, waveform, dict keys, etc.>
+  model_index:
+    class_name: <FastVideo pipeline class name to emit in model_index.json>
+    entry_class_names: <registered EntryClass.__name__ values that must include class_name>
+    required_modules: <text_encoder, tokenizer, vae, transformer, scheduler, etc.>
+    passthrough_modules: <tokenizer, scheduler, processor, external HF dirs, or none>
+  sampling_param:
+    new_fields: <none or list of public kwargs/preset defaults to add to SamplingParam>
+    cli_fields: <none or list of fields that need CLI args>
+    placeholder_fields: <none or video-shaped compatibility placeholders with rationale>
+  components:
+    - name: <component>
+      component_type: <dit|vae|encoder|scheduler|conditioner|upsampler|vocoder|generic>
+      parity_test: tests/local_tests/<bucket>/test_<family>_<component>_parity.py
+      parity_status: non_skip_pass
+      fastvideo_target_files: <model/config/export files>
+      converted_component_dir: converted_weights/<family>/<component>
+  conversion:
+    converted_weights_dir: converted_weights/<family>
+    source_layout: <diffusers|raw_official|monolithic|separate_components|mixed|custom>
+    model_index_path: converted_weights/<family>/model_index.json
+  fastvideo_targets:
+    pipeline_files:
+      - fastvideo/pipelines/basic/<family>/<family>_pipeline.py
+    stage_files:
+      - fastvideo/pipelines/basic/<family>/stages/<stage>.py
+    pipeline_config_files:
+      - fastvideo/configs/pipelines/<family>.py
+    preset_file: fastvideo/pipelines/basic/<family>/presets.py
+    registry_file: fastvideo/registry.py
+    example_files:
+      - examples/inference/basic/basic_<family>.py
+    smoke_test: tests/local_tests/pipelines/test_<family>_pipeline_smoke.py
+    parity_test: tests/local_tests/pipelines/test_<family>_pipeline_parity.py
+  local_tests_readme: tests/local_tests/<model_family>/README.md
+  port_state_file: tests/local_tests/<model_family>/PORT_STATUS.md
+  concerns_or_unknowns:
+    - <pipeline branch, unsupported workload, output head, preset ambiguity, etc.>
+```
+
+Rules:
+
+- Start only after every required component, reused or ported, has
+  `parity_status=non_skip_pass`. If any row is missing or skipped, return to
+  `/add-model` Phase 6.
+- Record official call arguments and default sources before writing FastVideo
+  presets. Do not invent inference defaults from memory.
+- `model_index.class_name` must match a registered pipeline `EntryClass.__name__`;
+  registry detectors are not sufficient for executable pipeline resolution.
+- Every public generation kwarg or preset default must be represented in
+  `SamplingParam`, or documented as an intentional internal-only field.
+- `T2A`, `A2A`, and `AV` may be used only after `WorkloadType` supports them;
+  otherwise record the compatibility shim and rationale explicitly.
+- Keep token values out of the packet. Use only token environment variable names.
+- If a target path is unknown, use `unknown` plus the exact search already
+  performed.
+- Update `local_tests_readme` and `port_state_file` whenever pipeline smoke,
+  parity, presets, registry, examples, or blockers change.

.agents/skills/add-model/contracts/pipeline_handoff.md

@@ -0,0 +1,71 @@
+# Pipeline Handoff Contract
+
+Returned by `add-model-09-pipeline` to `/add-model` after pipeline definition or
+pipeline parity-debug work.
+
+```text
+pipeline_handoff:
+  model_family: <snake_case>
+  mode: pipeline-definition | pipeline-parity-debug
+  files_changed:
+    - <pipeline/config/preset/registry/stage/example/test/readme/status paths>
+  official_files_used:
+    - <definition/call/default source paths>
+  required_config_modules:
+    emitted: <list from pipeline class>
+    model_index: <list from converted or source model_index.json>
+    status: match | mismatch | blocked
+  pipeline_class_resolution:
+    model_index_class_name: <_class_name>
+    entry_class_names: <registered EntryClass.__name__ values>
+    status: exact_match | alias_added | blocked
+  sampling_param:
+    fields_added: <none or list>
+    cli_fields_added: <none or list>
+    unknown_kwargs_checked: yes | no | blocked
+  stage_chain:
+    - <stage names in execution order>
+  pipeline_config:
+    file: <path>
+    classes: <class names>
+    official_defaults_checked: yes | no | blocked
+  presets:
+    file: <path>
+    names: <preset names>
+    status: pass | blocked | not_run
+  registry:
+    status: pass | blocked | not_run
+    detectors: <HF paths and model_index _class_name strings covered>
+  smoke_test:
+    path: tests/local_tests/pipelines/test_<family>_pipeline_smoke.py
+    status: non_skip_pass | blocked | not_run
+    pytest_output: <command + short result>
+  pipeline_parity:
+    path: tests/local_tests/pipelines/test_<family>_pipeline_parity.py
+    status: scaffold_skip | debug_red | non_skip_pass | blocked
+    pytest_output: <command + short result>
+    comparison_target: <latents|decoded video|audio|joint outputs>
+  example:
+    path: examples/inference/basic/basic_<family>.py
+    status: pass | blocked | not_run
+    output: <path or none>
+  readme_updated: yes | no
+  port_state_updated: yes | no
+  blockers: <none or exact blocker list>
+  next_step: phase_10_quality_regression | return_to_phase_6 | ask_user
+  escape_hatch: <none or block matching contracts/escape_hatch.md>
+```
+
+Rules:
+
+- `pipeline-definition` may return with parity still `scaffold_skip` only if the
+  exact missing dependency, weight, or call-path blocker is recorded.
+- Final `/add-model` handoff requires `smoke_test.status=non_skip_pass` and
+  `pipeline_parity.status=non_skip_pass`, unless the user explicitly accepts a
+  documented blocker.
+- If parity failure traces to a component, conversion, or strict-load issue,
+  return `next_step=return_to_phase_6` and include the exact failing evidence.
+- Keep `local_tests_readme` and `port_state_file` synchronized with this
+  handoff before returning.
+- Use `next_step=ask_user` only with an `escape_hatch` block and a matching
+  `PORT_STATUS.md` row.

.agents/skills/add-model/contracts/port_state.md

@@ -0,0 +1,89 @@
+# Port State Contract
+
+Canonical per-port state file created during prep and updated by every
+`/add-model` phase.
+
+Path:
+
+```text
+tests/local_tests/<model_family>/PORT_STATUS.md
+```
+
+Purpose:
+
+- Single source of truth for resumable port progress.
+- Tracks component status, conversion status, parity status, open questions,
+  blockers, escape hatches, and issue history.
+- Lets review agents run the same setup/tests without reconstructing handoffs
+  from conversation history.
+
+Required sections:
+
+```text
+# <Model Family> Port Status
+
+## Summary
+- model_family:
+- workload_types:
+- official_ref:
+- official_ref_dir:
+- hf_weights_path:
+- local_weights_dir:
+- source_layout:
+- local_tests_readme:
+
+## Current Phase
+- phase:
+- status: not_started | in_progress | blocked | complete
+- owner: orchestrator | prep | parity | conversion | component:<name> | pipeline
+- last_updated:
+
+## Component Matrix
+| Component | Type | Reuse/Port | Official Definition | Official Instantiation | FastVideo Target | Prototype | Conversion | Parity | Open Issues |
+|---|---|---|---|---|---|---|---|---|---|
+
+## Conversion State
+- conversion_script:
+- converted_weights_dir:
+- source_layout:
+- strict_load_status:
+- passthrough_components:
+- retry_history:
+
+## Parity Commands
+| Scope | Command | Last Result | Notes |
+|---|---|---|---|
+
+## Open Questions
+| ID | Question | Owner | Needed By Phase | Status | Resolution |
+|---|---|---|---|---|---|
+
+## Issues And Blockers
+| ID | Phase | Component | Severity | Issue | Evidence | Owner | Status | Resolution |
+|---|---|---|---|---|---|---|---|---|
+
+## Escape Hatches
+| ID | Phase | Decision Type | Question | Recommended Option | Status | Resolution |
+|---|---|---|---|---|---|---|
+
+## Decisions
+| Date | Decision | Rationale | Impact |
+|---|---|---|---|
+
+## Handoff Notes
+- <short notes for the next agent>
+```
+
+Rules:
+
+- Update this file whenever a phase starts, blocks, resolves an issue, or hands
+  off to another skill.
+- Record open questions and issues immediately. Do not leave blockers only in
+  chat history or subagent responses.
+- Use stable IDs: `Q001`, `Q002`, `I001`, `I002`, etc.
+- Use stable escape-hatch IDs: `E001`, `E002`, etc. Link them from handoff
+  `escape_hatch.state_snapshot.evidence` when returning `next_step=ask_user`.
+- Do not include raw token values, machine-local cache internals, or large output
+  dumps. Use repo-relative paths when possible.
+- If a question or issue is resolved, keep the row and fill `Resolution` instead
+  of deleting it.

.agents/skills/add-model/contracts/prep_handoff.md

@@ -0,0 +1,42 @@
+# Prep Handoff Contract
+
+Produced by `../add-model-01-prep/SKILL.md` and consumed by `/add-model` Phase 0.
+
+```text
+model_family: <snake_case>
+workload_types: <T2V/I2V/V2V/T2I/or compatibility shim with rationale>
+official_ref: <url or import path>
+official_ref_dir: <ReferenceDir or none>
+official_ref_commit: <sha or unknown>
+hf_weights_path: <HF id or local path>
+hf_revision: <revision or default>
+local_weights_dir: official_weights/<model_family> or <local path>
+source_layout: diffusers | raw_official | monolithic | separate_components | mixed | custom | unknown
+model_index_class: <_class_name or none>
+components_seen: <components>
+needs_conversion: yes | no | unknown
+hf_token_env: <env var name only>
+dependency_changes: none | installed no-deps editable | installed official deps in current env | blocked on user
+official_env_status: imports_ok | private_deps_need_stubs | blocked
+local_tests_readme: tests/local_tests/<model_family>/README.md
+port_state_file: tests/local_tests/<model_family>/PORT_STATUS.md
+gitignore_entries_added: <list>
+next_step: add-model | ask_user
+open_questions: <short list>
+escape_hatch: <none or block matching contracts/escape_hatch.md>
+```
+
+Validation:
+
+- `official_env_status` must be `imports_ok` or `private_deps_need_stubs` before
+  component parity scaffolding.
+- `local_tests_readme` must exist and describe official setup, HF weights,
+  dependency changes, planned parity commands, and review notes.
+- `port_state_file` must exist and follow `contracts/port_state.md`.
+- Prep does not go directly to conversion; `/add-model` must run component
+  prototype/key-dump Phase 4 before Phase 5 conversion.
+- `T2A`, `A2A`, and `AV` may be used only after `WorkloadType` supports them;
+  otherwise record the compatibility shim and rationale explicitly.
+- Never include HF token values.
+- Use `next_step=ask_user` only with an `escape_hatch` block and a matching
+  `PORT_STATUS.md` row.

.agents/skills/add-model/shared/common_rules.md

@@ -0,0 +1,96 @@
+# Shared Add-Model Rules
+
+These rules apply to every `add-model` related skill: prep, parity, conversion,
+component porting, pipeline, and the main `/add-model` orchestrator.
+
+## Token And Auth Safety
+
+- Never accept, print, echo, log, hard-code, or commit raw HF token values.
+- Refer only to token environment variable names: `HF_TOKEN`,
+  `HUGGINGFACE_HUB_TOKEN`, or `HF_API_KEY`.
+- Scripts may read those environment variables but must not print their values.
+- Ask for auth setup only by env var name. Do not ask the user to paste a token.
+- Read scope is needed for gated repos during conversion/load. Write scope is
+  needed for publishing converted weights or seeding generated references.
+
+## Shared State Files
+
+- `tests/local_tests/<model_family>/README.md` is the reviewer-facing setup and
+  verification log. Keep it current with setup commands, dependency blockers,
+  parity commands, conversion commands, and pass/blocker status.
+- `tests/local_tests/<model_family>/PORT_STATUS.md` is the per-port state file.
+  It must follow `../contracts/port_state.md` and keep stable `Q###`, `I###`, and
+  `E###` IDs.
+- Keep resolved questions/issues in `PORT_STATUS.md` with the resolution instead
+  of deleting them.
+- Before returning a handoff, update both state files when the skill changed
+  setup, tests, conversion, parity status, blockers, or decisions.
+- Do not include raw tokens, non-reproducible absolute cache paths, large
+  generated outputs, `.env`, credentials, or anything matching `*secret*`.
+
+## Escape Hatches
+
+Continue autonomously for recoverable setup, implementation, conversion,
+strict-load, smoke, parity-debug, lint, or test failures. Stop and ask the user
+only when the next action requires a product, cost, safety, auth, dependency, or
+scope decision the workflow cannot safely choose.
+
+Use `../contracts/escape_hatch.md` whenever returning `next_step=ask_user`.
+
+Ask for user input only for:
+
+- scope changes, such as dropping a modality, output head, variant, component, or
+  public mode;
+- core dependency changes, untrusted/private dependency installs, or version pin
+  changes;
+- auth setup for gated repos, using env var names only;
+- large downloads, publishing weights, SSIM/reference uploads, or GPU-heavy work
+  where cost/runtime approval is needed;
+- destructive file/git operations, overwriting existing clones/weights, or
+  deleting staged assets;
+- incompatible official sources of truth where no reference can be chosen from
+  published weights and docs;
+- accepting a blocker, loosening tolerances, using shape-only substitutes, or
+  shipping without required non-skip parity.
+
+Do not ask for normal recoverable failures: missing imports, missing local paths,
+skipped tests, failing parity, conversion mapping bugs, strict-load errors,
+format/lint failures, smoke failures, registry import issues, example failures,
+or implementation bugs covered by the phase workflow.
+
+Before asking:
+
+- update `PORT_STATUS.md` with an `E###` escape-hatch row plus any linked `Q###`
+  or `I###` row;
+- include exact evidence: command, path, short error text, parity or strict-load
+  excerpt, or blocker ID;
+- provide one recommended option and at most three alternatives;
+- set the relevant handoff `next_step=ask_user` and include the `escape_hatch`
+  block.
+
+Skill-specific escape-hatch sections may add extra examples, but they must not
+weaken these shared rules.
+
+## Production Boundary
+
+- No runtime `from diffusers import <model class>` or
+  `from transformers import <model class>` in `fastvideo/` production code.
+- Components that own weights or numerical behavior must be FastVideo-native
+  unless the user explicitly accepts a documented lazy-wrapper exception.
+- Allowed third-party runtime exceptions are tokenizers and pure data utilities
+  when they match existing project patterns.
+- Tests may import diffusers/transformers as parity references.
+- Production comments explain why, not what or provenance. Avoid narrative
+  comments like `vendored from`, `matches upstream`, `REVIEW`, or session-history
+  commentary.
+
+## Verification Semantics
+
+- A committed local test may skip when clones, weights, or private deps are absent
+  so CI and other contributors are not blocked.
+- On the porter's machine, a skip is not a pass. Fix the missing import, weights,
+  or path before claiming verification.
+- New ports require local non-skip parity for required components and pipeline
+  parity when a pipeline is in scope.
+- Smoke tests prove loadability only. They are not a substitute for numerical
+  component or pipeline parity.

.agents/skills/add-model/shared/component_skill_common.md

@@ -0,0 +1,117 @@
+# Component Skill Common Instructions
+
+These instructions apply to `add-model-03-port-dit`, `add-model-04-port-vae`,
+`add-model-05-port-encoder`, and `add-model-06-port-generic`. Bucket-specific skills
+add target paths, implementation patterns, drift checks, and scope questions.
+
+## Required Context
+
+Require the complete packet from `../contracts/component_context.md`.
+
+Do not start if the official definition files, official instantiation files, or
+parity test path are missing. Ask the `/add-model` orchestrator for the complete
+component context packet instead of rediscovering broad scope silently.
+
+If the parity scaffold is missing, create it first with
+`../../add-model-02-parity/templates/component_parity_test.py`.
+
+## Prototype Mode
+
+Prototype mode runs before conversion:
+
+- implement or prove reuse for the minimal native component, config, export, and
+  `EntryClass` surface needed by the relevant loader;
+- instantiate with random weights using the exact official architecture args, or
+  instantiate/document stateless components with no weights;
+- dump official and FastVideo `state_dict()` names/shapes for every stateful
+  component so conversion can derive mappings from real surfaces;
+- return concerns discovered during prototype work, such as ambiguous official
+  flags, shape mismatches, private ops, missing loader buckets, passthrough
+  weights, or output heads;
+- update `local_tests_readme` with prototype status and key-dump paths;
+- update `port_state_file` with prototype status, open questions, issues, and
+  handoff notes;
+- do not chase numerical parity and do not block on converted weights.
+
+Prototype mode succeeds when the component imports, instantiates with official
+args, and required key/shape dumps exist. Converted weights and parity PASS are
+not required yet.
+
+## Parity-Debug Mode
+
+Parity-debug mode runs after conversion:
+
+- strict-load converted weights through the same path the pipeline will use, or
+  document that the component is stateless or an approved passthrough;
+- use `conversion_context` and `concerns_or_unknowns` to decide whether a failure
+  belongs to mapping, loading, implementation, tokenization, normalization,
+  scheduler semantics, or the parity test;
+- run only the component parity test first with `pytest <parity_test> -v -s`;
+- if it skips, fix the missing official import, FastVideo class, tokenizer,
+  converted weights, or path;
+- if it fails numerically, add targeted intermediate comparisons to identify the
+  first divergent operation or tensor;
+- update component implementation only when the failure is a component
+  layer/config/forward/contract bug;
+- update `local_tests_readme` with the command, result, and blocker or PASS;
+- update `port_state_file` with parity status, resolved/new issues, open
+  questions, and handoff notes;
+- keep iterating until the test is a non-skip PASS or return a precise blocker.
+
+## Conversion Boundary
+
+Component skills must not patch conversion scripts or converted weights ad hoc.
+If the first drift or strict-load failure points to wrong keys, missing tensors,
+shape mismatches, component prefixes, split/fuse logic, skipped-key policy, or
+config emission, return a conversion retry request for
+`../../add-model-07-conversion/SKILL.md` matching
+`../contracts/conversion_request.md`.
+Resume parity-debug only after conversion returns an updated handoff.
+
+## Reuse Proof
+
+When `fastvideo_target_files` point to existing FastVideo code instead of a new
+port:
+
+- compare the official definition against the FastVideo target: graph/operation
+  structure, parameter or state shapes, normalization, activation, positional or
+  temporal behavior, scaling constants, dtype behavior, state-dict names, output
+  containers, and output tensors;
+- compare the official instantiation against the FastVideo config and loader
+  args: constructor args, config values, defaults, variant flags, optional
+  submodules, checkpoint metadata, tokenizer/media paths, and loader path;
+- treat a matching class instantiated with different args as not reusable;
+- record reuse evidence in `local_tests_readme` and keep the reused component in
+  `prototype_key_dumps` when it owns state so conversion and parity-debug use the
+  same surface;
+- still run parity-debug to a non-skip PASS. If mismatch is found, return the
+  concern so `/add-model` can switch the component to a native port.
+
+## Handoff
+
+Return `../contracts/component_skill_handoff.md`.
+
+Mode-specific expectations:
+
+- In `mode=prototype`, `parity_status` may be `scaffold_skip` or `blocked`; key
+  dumps are the required artifact and successful prototype handoff should use
+  `next_step=phase_5_conversion`.
+- In `mode=parity-debug`, final success requires
+  `parity_status=non_skip_pass`.
+- If conversion is implicated, return `conversion_retry_request` and leave
+  conversion edits to `add-model-07-conversion`.
+- If production loading is non-strict, list allowed missing/unexpected keys in
+  the parity test or handoff and mark
+  `strict_load=pass_with_documented_exclusions`.
+
+## Escape Hatches
+
+Follow `common_rules.md`. Do not ask for normal prototype or parity-debug
+failures such as missing imports, tokenizer/path issues, red parity,
+strict-load failures, key mismatches, shape mismatches, or implementation bugs.
+Return conversion retry requests or precise blockers as directed by the workflow.
+
+Ask only when component work requires a scope or safety decision, such as
+dropping a required stream/output/path, changing core dependencies, accepting
+private model code or unsupported private ops, choosing between incompatible
+official definitions, creating a new loader bucket, or loosening required parity.

.agents/skills/ci-runner/SKILL.md

@@ -1,99 +0,0 @@
----
-name: ci-runner
-description: Work on FastVideo's Slurm-only, change-aware GPU CI lanes, static Buildkite graph, trusted ci-runner policy, lane scripts, and GB200 validation.
----
-
-# Slinky Slurm CI lanes
-
-FastVideo's `ci-runner` Buildkite queue is the control plane for all active
-GPU CI. A private host-owned dispatcher leases GPUs from the Slinky Slurm tray
-and runs the immutable PR SHA inside an isolated Enroot container. Buildkite
-pipeline upload and Slurm submission occur on the login plane; every test
-payload executes on Slurm compute.
-
-The files under `fastvideo/tests/modal/` and `.buildkite/scripts/pr_test.sh`
-are dormant rollback code. Never add an active Buildkite or slash-command
-route to them. `pr_test.sh` must continue to reject Buildkite invocations.
-
-The private operator bundle is deliberately outside this repository because
-it contains site paths and credentials. See
-`docs/contributing/ci_architecture.md`; this skill covers the repository half
-and the coordination contract with that bundle.
-
-## Invariants
-
-- `.buildkite/pipeline.yml` contains exactly one static step for every active
-  GPU lane. Each step pins a unique key and label, a 90-minute timeout, the
-  trusted `/opt/fastvideo-ci-runner/run-ci` command (`run-unit` is the one
-  compatibility wrapper), step-level internal `TEST_TYPE`, and
-  `queue: "ci-runner"`.
-- Active CI contains no `pr_test.sh` command, Modal invocation, default queue,
-  Buildkite plugin, `soft_fail`, or job-controlled artifact glob.
-- The six Fastcheck lanes use `:microscope:` labels. Full-Suite-only lanes use
-  `:test_tube:` or `:bar_chart:` so direct reruns update the right aggregate.
-- SSIM and vanilla training request all four GPUs. Keep both in the
-  `fastvideo/slinky/whole-tray` Buildkite concurrency group with a limit of one
-  so the second job does not consume an agent or command timeout while waiting
-  for the same tray.
-- `/test full` schedules all twenty lanes. `/merge`, `ready`, and new pushes to
-  ready PRs use the trusted base-branch planner in
-  `.github/scripts/plan_merge_ci.py`: automatic Fastcheck remains the universal
-  six-lane baseline, and the merge build adds only path-relevant integration
-  lanes. Unknown source/build paths fail closed to all fourteen additive lanes.
-  The trusted uploader still normalizes and validates the complete static graph
-  before Buildkite evaluates its plan conditions.
-- Focused merge builds may pass allowlisted golden-gate and SSIM test basenames.
-  The private host validates the lane plan and basenames before staging them,
-  and the in-container scripts validate them again. Direct `/test ssim`,
-  explicit `/test full`, and the weekly main-branch schedule run the complete
-  SSIM matrix.
-- The trusted uploader serves exactly three entry pipelines:
-  `pr-fastcheck` for automatic PR builds, `ci` for slash-command/ready-label
-  API builds, and `fastvideo-performance-lane` for the weekly schedule. Keep
-  incoming GitHub webhook processing disabled on `ci` so it cannot duplicate
-  `pr-fastcheck` on every PR update.
-- Test payloads live in `.buildkite/scripts/unit_test.sh` or executable
-  `.buildkite/scripts/lanes/<lane>.sh`. Backend policy (GPU count, extras,
-  secrets, kernel build, artifacts) stays in the agent-owned lane table.
-- Tests must preserve an inherited `MASTER_PORT`. Packed containers share the
-  tray network namespace, so the private runner assigns a distinct port range
-  per GPU lease and the SSIM scheduler assigns task offsets within its range.
-- The ARM64 runner image includes the pinned FA4 CuTe overlay validated on
-  GB200. Keep SSIM at `FASTVIDEO_FA4=1` because its references were seeded with
-  FA4; keep lanes with FA2 baselines at `FASTVIDEO_FA4=0`. A runner image change
-  must revalidate both the FA4 import and an actual GB200 forward kernel.
-- `fastvideo/tests/ssim/ci_runner.py` is the active four-GPU SSIM scheduler.
-  New SSIM files are discovered through `REQUIRED_GPUS` and
-  `*_MODEL_TO_PARAMS`; do not wire them through the dormant Modal scheduler.
-- The host policy fail-closes unknown tuples. A repository-side lane change is
-  inert until the operator updates the private lane table and uploader policy
-  in the same rollout.
-
-## Adding or changing a lane
-
-1. Read the closest `AGENTS.md` and the domain-specific testing guide.
-2. Add or update the executable lane payload under `.buildkite/scripts/`.
-   Keep it deterministic and free of host-specific paths or credential fetches.
-3. Add the static pipeline step and canonical `/test <name>` mapping. Keep the
-   `<name>-ci` alias only when compatibility requires it.
-4. Add its source/test path ownership to `.github/scripts/plan_merge_ci.py`.
-   Prefer the narrowest correctness-preserving lane set; leave unknown paths
-   fail-closed. Extend `fastvideo/tests/contract/test_ci_test_collection.py`,
-   `test_merge_ci_plan.py`, and focused CPU-only scheduler/policy tests.
-5. Coordinate the private lane row: GPU count (1-4), wall time, script, scope
-   pairs, step key, command, HF cache/token, tracking mode, extras, attention
-   backend policy, kernel policy, and artifact relay. Active training lanes
-   keep W&B offline and do not stage a W&B credential.
-6. Update the trusted pipeline-uploader schema. A mismatch must reject the
-   pipeline rather than silently skip a lane.
-7. Run `pre-commit run --files <changed paths>`, the planner's representative
-   diff matrix, contract tests, private driver tests, and a real GB200 canary.
-   Multi-GPU, hardware-reference, training, performance, and SSIM changes need
-   their own target-hardware evidence.
-
-## Rollback
-
-Rollback the Slurm routing/configuration change or pause the `ci-runner` queue.
-Do not silently reactivate Modal. A manual Modal experiment requires the
-explicit local opt-in documented in `ci_architecture.md`; returning it to
-production CI needs a separate reviewed decision.

.agents/skills/decompose-pipeline-pr/SKILL.md

@@ -0,0 +1,338 @@
+---
+name: decompose-pipeline-pr
+description: Decompose an oversized FastVideo pipeline PR into a stack of independently-reviewable PRs. Tiers the diff by blast radius (invisible / dead code / cross-cutting infra / activation), produces a branch graph and worktree bootstrap, drafts the AGENTS.md manifest, flags missing tests on cross-cutting infra changes, and extracts lessons from the PR body.
+---
+
+# Decompose Pipeline PR
+
+## Purpose
+
+When a PR adds a new pipeline (or first-class component port) and crosses
+~3,000 LOC, single-shot review converges to rubber-stamping. This skill
+decomposes such a PR into a stack of independently-reviewable PRs without
+disturbing `main`.
+
+It is the inverse of `add-model`: where `add-model` walks adding a new
+pipeline as a fresh PR, this skill walks decomposing an existing oversized
+pipeline PR.
+
+**Worked example:** PR #1280 (daVinci-MagiHuman, 9,812 LOC, 56 files) →
+2 prerequisite PRs off main + 8-PR stack:
+- #1293 `will/activation-trace` (prerequisite)
+- #1294 `will/loader-infra` (prerequisite)
+- #1295 (1/8) housekeeping
+- #1296 (2/8) t5gemma encoder
+- #1297 (3/8) DiT
+- #1298 (4/8) pipeline stages
+- #1299 (5/8) pipeline orchestrator
+- #1300 (6/8) provenance (AGENTS.md, JOURNAL.md, lessons)
+- #1301 (7/8) conversion scripts
+- #1302 (8/8) registry activation
+
+## Prerequisites
+
+- Open PR number on `hao-ai-lab/FastVideo` (or any FastVideo fork)
+- `gh` CLI authenticated against the target remote
+- Local git worktree support (`git worktree`)
+- Git config `user.name` / `user.email` set
+- Pre-commit installed (`pre-commit install --hook-type pre-commit --hook-type commit-msg`)
+- The target PR's branch fetched locally as `origin/<feature-branch>`
+
+## Inputs
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| PR number or URL | Yes | E.g. `1280` or `https://github.com/hao-ai-lab/FastVideo/pull/1280` |
+| Max desired PR size | No | Defaults to ~2,500 LOC of code per stack PR (excluding generated/journal files) |
+| Output directory | No | Defaults to `.agents/tmp/decompose-<pr-number>/` (gitignored) |
+
+## Steps
+
+### 1. Verify ground truth (do not trust `gh pr diff --name-only`)
+
+`gh pr diff <N> --name-only` has been observed to emit phantom file entries.
+Always cross-check against the authoritative `git diff`:
+
+```bash
+mkdir -p .agents/tmp/decompose-<N>
+git fetch origin pull/<N>/head:<feature-branch>
+git diff origin/main..origin/<feature-branch> --name-status \
+  > .agents/tmp/decompose-<N>/files.txt
+git diff origin/main..origin/<feature-branch> --stat
+```
+
+Use the `--name-status` output as the authoritative file list. If it
+disagrees with `gh pr diff --name-only`, trust the git diff.
+
+### 2. Tier the diff by blast radius
+
+Classify every changed file into one of four tiers:
+
+| Tier | Description | Examples |
+|---|---|---|
+| **Tier 0 — Invisible** | Lint/style/CI configs that don't affect runtime | `.gitignore`, `pyproject.toml` (codespell only), agent documentation |
+| **Tier 1 — Dead code** | New files in their own dirs; aggregator one-liners | `fastvideo/models/dits/<new>/`, `fastvideo/pipelines/basic/<new>/`, `examples/inference/basic/basic_<new>*.py`, `tests/local_tests/<new>/`, `__init__.py` exports |
+| **Tier 2 — Cross-cutting infra** | Modifications to files used by every pipeline | See protected-paths list below |
+| **Tier 3 — Activation switch** | `register_configs(...)` calls + the example scripts that demo them | `fastvideo/registry.py` |
+
+**FastVideo Tier 2 protected paths:**
+```
+fastvideo/utils.py
+fastvideo/pipelines/composed_pipeline_base.py
+fastvideo/models/loader/component_loader.py
+fastvideo/configs/models/dits/__init__.py
+fastvideo/configs/models/encoders/__init__.py
+fastvideo/configs/models/vaes/__init__.py
+fastvideo/envs.py
+fastvideo/fastvideo_args.py
+fastvideo/distributed/**
+fastvideo/layers/**
+fastvideo/attention/**
+fastvideo/registry.py    # treat as Tier 3 if change is the activation
+```
+
+Tier 3 detection (mechanical):
+```bash
+git diff origin/main..origin/<feature-branch> -- fastvideo/registry.py | \
+  grep -E "^\+.*register_configs\("
+```
+
+If `registry.py` only contains `register_configs` additions, treat it as
+Tier 3. If it modifies existing behavior, treat it as Tier 2 (rare).
+
+### 3. Identify reusable Tier-1 components
+
+Within Tier 1, look for sub-trees that are **not** model-specific and could
+land separately:
+
+- Encoders matching a known multi-model base (T5/T5-Gemma/Llama/Gemma/CLIP variants)
+- New stage classes that subclass shared bases without referencing the new model
+- Hook/profiler/debug infra under `fastvideo/hooks/`
+- New helpers that have no model-specific dependencies
+
+These get split into their own PRs (e.g. PR 4 `t5gemma-encoder` in the
+MagiHuman example).
+
+### 4. Hunt for missing test coverage on Tier 2 changes
+
+For every Tier-2 file modified, check whether the original PR added unit
+tests for the new behavior:
+
+```bash
+for f in <list-of-tier-2-files>; do
+  echo "=== Tests for $f ==="
+  git diff origin/main..origin/<feature-branch> -- \
+    "$(echo $f | sed 's|fastvideo/|fastvideo/tests/|; s|\.py|*|')"
+done
+```
+
+If a Tier-2 PR has no accompanying tests, **emit a "must-add tests" list**
+with a sketch of the case grid. Tier-2 PRs do not ship without those tests.
+
+The MagiHuman example required this for PR-B (`utils.py`): the original PR
+shipped no `test_utils_loader.py`, so the decomposition added 9 unit-test
+cases covering the umbrella-detector boundary, the optional-component-dirs
+relaxation, and regression coverage on every existing 2-segment HF id.
+
+### 5. Build the dependency DAG and topo-sort
+
+Edges:
+- Tier 2 infra → Tier 1 code that imports it
+- Reusable Tier 1 components → model-specific Tier 1 code that uses them
+  (encoder before DiT before pipeline)
+- Tier 1 → Tier 3 (activation always last)
+- Tier 0 has no dependents (lands first as a freebie)
+
+Topo-sort produces the stack ordering. Pull Tier-2 PRs **out of the stack**
+when they have no model-specific dependency — they should land off main
+with their own focused review, not buried in a model port.
+
+Render as a tree (markdown):
+
+```
+main
+ ├─ <prereq-A>
+ │   └─ <prereq-B>
+ │       ├─ <stack-01-housekeeping>
+ │       │   └─ <stack-02-encoder>
+ │       │       └─ <stack-03-dit>
+ │       │           └─ ...
+ │       │               └─ <stack-N-activate>
+ │       └─ (parallel) <skill-pr> off main
+```
+
+### 6. Detect mis-shelved docs and debug scratch
+
+Two categories to flag:
+
+- **Mis-shelved docs**: Markdown files under `tests/local_tests/` are
+  journals, not tests. Flag for relocation to the package dir as
+  `JOURNAL.md`.
+- **Debug scratch**: files starting with `_debug_`, `_scratch_`, or
+  `_explore_`. Flag for drop (do not carry into any output PR).
+
+For MagiHuman: `tests/local_tests/magi-human.md` → relocate. Two
+`_debug_magi_human_*.py` files → drop.
+
+### 7. Author the AGENTS.md manifest skeleton
+
+For the new pipeline package, generate a 6-section `AGENTS.md` scaffold
+with the file table pre-populated from the diff:
+
+1. **Manifest** — file table by role
+2. **Parity invariants** — load-bearing rules with one-paragraph each + lesson refs
+3. **Cross-refs** — "If you change X, re-run Y" matrix
+4. **Run book** — single pytest command + prereqs (HF tokens, GPU, wall-time)
+5. **Open questions** — known issues (e.g. tolerance carve-outs)
+6. **Provenance** — PR table with branch names and source SHA
+
+The provenance section is filled incrementally during stack execution and
+finalized in the activation PR.
+
+### 8. Extract lessons from the PR body
+
+Scan the PR body for sections titled "Key implementation work", "Bug hunt",
+"Lessons", or sentences with patterns like "took N waves to localize",
+"silent regression", "investigation revealed". Each becomes a candidate
+`.agents/lessons/<YYYY-MM-DD>_<slug>.md` draft.
+
+Lessons MUST follow the existing template in
+`.agents/lessons/README.md`:
+- YAML frontmatter: `date`, `experiment`, `category`, `severity`
+- Sections: What Happened, Root Cause, Fix / Workaround, Prevention
+- Filename: `<YYYY-MM-DD>_<short-slug>.md`
+
+Lessons co-locate with the code they concern: a conversion-script lesson
+lands in the same PR as the conversion script, not in the docs PR.
+
+### 9. Emit the commit-footer convention
+
+Every commit in the stack ends with:
+
+```
+<Feature>-Stack: N/M
+```
+
+E.g. `Magi-Stack: 5/8`. Use the package directory name as the feature key.
+After all PRs squash-merge, `git log --grep='^<Feature>-Stack:'` reconstructs
+the lineage even if PR numbers later get renumbered.
+
+### 10. Produce the worktree bootstrap
+
+Generate a runnable bash script:
+
+```bash
+#!/bin/bash
+set -euo pipefail
+
+REPO=/home/<user>/FastVideo
+WORKTREE=/home/<user>/FastVideoMagi   # NB: directory name must be a valid
+                                       # Python identifier (no hyphens) so
+                                       # mypy doesn't choke
+SOURCE_PR=<N>
+SOURCE_BRANCH=will/<feature>
+SOURCE_SHA=$(git -C "$REPO" rev-parse "origin/$SOURCE_BRANCH")
+
+git -C "$REPO" fetch origin main:main
+git -C "$REPO" fetch "origin/$SOURCE_BRANCH"
+git -C "$REPO" worktree add "$WORKTREE" origin/main
+
+# Capture baseline for provenance. Everything under .agents/tmp is transient
+# and ignored by git.
+OUTPUT_DIR="$REPO/.agents/tmp/decompose-$SOURCE_PR"
+mkdir -p "$OUTPUT_DIR"
+cat > "$OUTPUT_DIR/<feature>-baseline-${SOURCE_SHA:0:8}.txt" <<EOF
+Source PR: <repo>#$SOURCE_PR
+Source SHA: $SOURCE_SHA
+Authoritative file count: $(git -C "$REPO" diff origin/main..origin/$SOURCE_BRANCH --name-only | wc -l)
+Date captured: $(date -u +%Y-%m-%dT%H:%M:%SZ)
+EOF
+```
+
+### 11. Author preserve via `git checkout`, not `cherry-pick`
+
+For each stack PR:
+
+```bash
+git -C "$WORKTREE" switch -c <new-branch> <base-branch>
+git -C "$WORKTREE" checkout origin/<source-branch> -- <file1> <file2> ...
+git -C "$WORKTREE" commit -m "[<scope>]: <subject>
+
+<body>
+
+<Feature>-Stack: N/M"
+git -C "$WORKTREE" push -u origin <new-branch>
+gh pr create --base <base-branch> --head <new-branch> --title "..." --body "$(cat <<EOF ... EOF)"
+```
+
+Notes:
+- `git checkout origin/<source> -- <files>` extracts only the named files,
+  preserving the diff. The original PR's author is **not** preserved on the
+  new commit (it's authored by whoever runs the script). Reference the
+  original PR + source SHA in every commit body and PR description for
+  authorship attribution.
+- **Never use `git cherry-pick`** for this workflow — cherry-pick applies
+  whole commits, which mixes concerns across PR boundaries.
+
+## Outputs
+
+The skill produces all transient planning artifacts under
+`.agents/tmp/decompose-<pr>/`:
+
+1. A markdown decomposition plan (`plan.md`)
+2. A proposed branch graph
+3. A worktree-bootstrap script (`bootstrap.sh`)
+4. Per-PR file allocation lists (under `stack/`)
+5. AGENTS.md scaffolds for any new pipeline packages
+6. Draft lesson files (placed alongside the PR that owns the code they concern)
+7. A finalized provenance table for the package AGENTS.md
+
+## Anti-Patterns
+
+The skill should warn against:
+
+- **"Just rebase the megaPR into smaller commits."** Doesn't help review;
+  reviewer still sees one PR.
+- **Co-locating tests under the new package.** FastVideo's convention is
+  by-kind under `fastvideo/tests/` and `tests/local_tests/<family>/`. Don't
+  invent a new layout per pipeline.
+- **Splitting Tier 2 changes into "one file per PR."** Tier 2 PRs are
+  about semantic units (e.g., "loader umbrella + optional component dirs"
+  together because they jointly define the new diffusers-format contract),
+  not file-count.
+- **Landing the activation switch first** ("just register, the code can
+  be empty"). The skill enforces activation-last so every intermediate
+  state is dead code, not broken code.
+- **Trusting `gh pr diff --name-only`.** Cross-check against
+  `git diff origin/main..origin/<feature-branch> --name-status` —
+  `gh`'s output has been observed to include phantom entries.
+- **Worktree dir names with hyphens.** mypy interprets them as invalid
+  Python package names and refuses to run. Use CamelCase or underscores.
+- **Skipping the lesson-extraction step.** PR bodies contain the most
+  expensive learnings of the original implementation. Losing them to a
+  squash-merge is the silent decay of institutional knowledge.
+
+## Example Usage
+
+```
+User: split PR 1280
+Agent: [invokes decompose-pipeline-pr]
+       → produces .agents/tmp/decompose-1280/plan.md with:
+         - tiered file table (56 files: 3 tier-0, 35 tier-1, 9 tier-2,
+           9 tier-3)
+         - branch graph (PR-A + PR-B + 8-PR stack)
+         - worktree bootstrap script
+         - per-PR file lists
+         - AGENTS.md scaffold for fastvideo/pipelines/basic/magi_human/
+         - 3 draft lessons extracted from the PR body
+       → asks user to confirm before opening branches
+```
+
+## References
+
+- The MagiHuman decomposition (worked example):
+  `fastvideo/pipelines/basic/magi_human/AGENTS.md` (after PR #1302 merges)
+- Existing skill: `.agents/skills/add-model/SKILL.md` (the inverse — adding
+  a new pipeline as a fresh PR)
+- Lesson template: `.agents/lessons/README.md`
+- Skill template: `.agents/skills/SKILL_TEMPLATE.md`

.agents/skills/env-var-conventions/SKILL.md

@@ -1,79 +0,0 @@
----
-name: env-var-conventions
-description: Add, read, rename, or remove an environment variable in FastVideo, or change the environment-variable policy. Use before touching fastvideo/envs.py, os.environ, os.getenv, or monkeypatch.setenv in fastvideo/, and when fastvideo/tests/contract/test_env_policy.py fails.
----
-
-# Environment Variable Conventions
-
-## Purpose
-
-FastVideo registers its environment variables as typed fields in
-`fastvideo/envs.py`. The policy that governs them is
-`docs/contributing/env_vars.md`, and the contract test
-`fastvideo/tests/contract/test_env_policy.py` enforces the policy in the unit
-CI lane. This skill routes an environment-variable change through that policy.
-The policy doc is the single source of the rules; read it instead of relying
-on a summary here.
-
-## Prerequisites
-
-- Read `docs/contributing/env_vars.md` in full.
-- Decide whether the setting belongs in an environment variable or an argument
-  (rule 5 in the policy doc). Settings that users change per deployment are
-  arguments; add them through `fastvideo/fastvideo_args.py` instead.
-
-## Inputs
-
-| Parameter  | Required | Description                                                    |
-| ---------- | -------- | -------------------------------------------------------------- |
-| `change`   | Yes      | Add, read, rename, or remove a variable, or change the policy. |
-| `variable` | Yes      | The variable name, with the `FASTVIDEO_` prefix.               |
-
-## Steps
-
-1. **Declare or edit the variable in `fastvideo/envs.py`.**
-   - Pick the field type and category that the policy doc lists.
-   - Write a description that states what the variable does and its units.
-   - To rename, keep the old name in `deprecated_names`. To remove, add the
-     name to `DEPRECATED_VARIABLES`. Update the uses in `examples/`,
-     `scripts/`, `docs/`, `apps/`, and the tests.
-2. **Read the variable with `envs.NAME.get()` inside a function.**
-   - In tests, change the value with `envs.NAME.override(value)`, and a variable
-     outside the registry with `envs.override_external(name, value)`; the
-     `env_overrides` fixture keeps either until the end of the test.
-   - Name a variable that only tests read `FASTVIDEO_TEST_*`.
-   - Do not call `os.environ`, `os.getenv`, or `monkeypatch.setenv` for a
-     FastVideo variable.
-   - To set a variable that another tool reads, call `envs.set_external`,
-     `envs.setdefault_external`, or `envs.unset_external`.
-3. **Regenerate the table in the policy doc.**
-   - Run `python fastvideo/tests/contract/test_env_policy.py`.
-4. **Run the contract test.**
-   - Run `pytest fastvideo/tests/contract/test_env_policy.py`.
-   - When the test reports a fixed known violation, delete or lower its entry
-     in `KNOWN_VIOLATIONS`. Never add an entry to `KNOWN_VIOLATIONS`.
-5. **When the policy itself changes, update the policy doc and the contract
-   test in the same pull request.**
-   - The rules in `docs/contributing/env_vars.md`, the checks and allowlist in
-     `fastvideo/tests/contract/test_env_policy.py`, and this skill must agree.
-
-## Outputs
-
-- A registry entry in `fastvideo/envs.py` and call sites that use
-  `envs.NAME.get()`.
-- A regenerated table in `docs/contributing/env_vars.md`.
-- A passing `fastvideo/tests/contract/test_env_policy.py`.
-
-## Example Usage
-
-```
-Add a FASTVIDEO_DEBUG_MY_STAGE switch that logs MyStage inputs.
-```
-
-## References
-
-- `docs/contributing/env_vars.md`: the policy, the field types, and the
-  violation kinds that the contract test reports.
-- `fastvideo/envs.py`: the registry.
-- `fastvideo/tests/contract/test_env_policy.py`: the contract test,
-  `EXTERNAL_ALLOWLIST`, and `KNOWN_VIOLATIONS`.

.agents/skills/reseed-ssim-references/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: reseed-ssim-references
-description: Re-seed HF reference videos for a single existing SSIM test on Modal L40S. Always backs up current refs locally first, regenerates on Modal, pauses for the user to eyeball before-vs-after quality, then overwrites the targeted model subtree on `FastVideo/ssim-reference-videos` with `--force`. Use when an intentional code change (model port fix, attention backend swap, kernel upgrade, hyperparameter change) has invalidated existing refs and they need to be regenerated. Pairs with `seed-ssim-references`, which is for first-time seeding only.
+description: Re-seed HF reference videos for a single existing SSIM test on Modal L40S. Always backs up current refs locally first, regenerates on Modal, pauses for the user to eyeball before-vs-after quality, then overwrites the targeted `<model_id>` subtree on `FastVideo/ssim-reference-videos` with `--force`. Use when an intentional code change (model port fix, attention backend swap, kernel upgrade, hyperparameter change) has invalidated existing refs and they need to be regenerated. Pairs with `seed-ssim-references`, which is for first-time seeding only.
 ---
 
 # Re-seed SSIM Reference Videos
@@ -13,7 +13,7 @@ on HF — the old refs are overwritten — so the skill always:
 
 1. Confirms intent with a one-liner the user has to type.
 2. Downloads the existing refs as a local, timestamped backup.
-3. Regenerates through the manual legacy Modal L40S maintenance path.
+3. Regenerates on Modal L40S (same code path that CI uses).
 4. Pauses for a side-by-side eyeball of backup vs new mp4s.
 5. Uploads with `--force`, scoped to the single `--model-id`.
 6. Reminds the user to keep the backup until the PR lands.
@@ -51,13 +51,12 @@ harder to recover from than failing closed.
 
 Hardcoded:
 
-- Modal GPU: **L40S**. This is a manual reference-maintenance target, not the
-  active Slurm CI compute path; changing the SKU also changes the historical
-  `L40S_reference_videos` contract.
+- Modal GPU: **L40S** (matches CI; re-seeding from another SKU produces refs
+  that L40S CI cannot match).
 - Quality tier: **`default`**. `full_quality` is a separate, deliberate
   operation.
 - HF repo: `FastVideo/ssim-reference-videos` (override via
-  `FASTVIDEO_TEST_SSIM_REFERENCE_HF_REPO`).
+  `FASTVIDEO_SSIM_REFERENCE_HF_REPO`).
 - Device folder: `L40S_reference_videos`.
 
 ## Prerequisites

.agents/skills/seed-ssim-references/SKILL.md

@@ -35,8 +35,7 @@ The skill is run **manually**, once per new test. Before invoking it, the user
 has already sanity-tested the new test locally — it launches `VideoGenerator`
 and writes an artefact without crashing (the missing-reference assertion at
 the end is expected). The skill does not re-test locally; it goes straight
-to the manual legacy Modal L40S reference-maintenance target. Active CI runs
-on the Slinky Slurm cluster and only consumes the resulting references.
+to Modal L40S (which is what CI uses).
 
 ## When to use
 
@@ -62,8 +61,7 @@ Prompt the user for it if they didn't supply it.
 
 Everything else is fixed:
 
-- Modal maintenance GPU: **L40S** (hardcoded in
-  `fastvideo/tests/modal/ssim_test.py`; this is not the active CI compute path).
+- Modal runner GPU: **L40S** (hardcoded in `fastvideo/tests/modal/ssim_test.py`).
 - Device folder: `L40S_reference_videos`.
 - Quality tier: `default` (the tier CI runs). The `full_quality` tier is not
   seeded by this skill.
@@ -105,8 +103,8 @@ Detect artefact type by inspecting the file's imports / helper call:
 - **pixel** (`.mp4`) — file imports
   `run_text_to_video_similarity_test` / `run_image_to_video_similarity_test`
   from `fastvideo.tests.ssim.inference_similarity_utils`, OR uses the
-  legacy custom-inline helper pattern (see `test_gen3c`). Default to pixel
-  when both heuristics fail.
+  legacy custom-inline helper pattern (see `test_gamecraft`,
+  `test_longcat`, etc.). Default to pixel when both heuristics fail.
 
 Record `ARTEFACT_TYPE ∈ {pixel, latent}` for use in step 4. Steps 2, 3, 5,
 and 6 are artefact-type-agnostic — `_iter_reference_files`,

.buildkite/scripts/lanes/api_server.sh

@@ -1,5 +0,0 @@
-#!/usr/bin/env bash
-# Canonical Slurm CI selection for the OpenAI-compatible API lane.
-set -euo pipefail
-
-exec pytest ./fastvideo/tests/entrypoints/test_openai_api_integration.py -vs

.buildkite/scripts/lanes/distillation_dmd.sh

@@ -1,5 +0,0 @@
-#!/usr/bin/env bash
-# Canonical Slurm CI selection for the distillation-DMD lane.
-set -euo pipefail
-
-exec pytest ./fastvideo/tests/training/distill/test_distill_dmd.py -vs

.buildkite/scripts/lanes/dreamverse.sh

@@ -1,87 +0,0 @@
-#!/usr/bin/env bash
-# DreamVerse needs a GPU for import-time device resolution, but it does not
-# build or exercise fastvideo-kernel. A checksummed Node archive is installed
-# in the disposable Slurm container because the shared CI image is
-# Python/CUDA focused.
-set -euo pipefail
-
-node_version=v22.23.2
-case $(uname -m) in
-  aarch64 | arm64)
-    node_arch=arm64
-    node_archive_sha256=013b59cfd2819703a6f4a14ab891fc46fc2a4e3f5bcd92de3fb4929b43e35b30
-    ;;
-  x86_64 | amd64)
-    node_arch=x64
-    node_archive_sha256=b294a556e639d64338823920e5866c21c02741742d2e1529ee1a225c1ec9252a
-    ;;
-  *)
-    echo "Unsupported architecture for DreamVerse Node runtime: $(uname -m)" >&2
-    exit 2
-    ;;
-esac
-node_archive="node-${node_version}-linux-${node_arch}.tar.gz"
-node_runtime_root=$(mktemp -d -t fastvideo-node.XXXXXX)
-node_archive_path="${node_runtime_root}/${node_archive}"
-node_install_dir="${node_runtime_root}/${node_archive%.tar.gz}"
-curl --proto '=https' --tlsv1.2 --retry 5 --retry-all-errors \
-  --location --fail --silent --show-error \
-  "https://nodejs.org/dist/${node_version}/${node_archive}" \
-  --output "$node_archive_path"
-printf '%s  %s\n' "$node_archive_sha256" "$node_archive_path" | sha256sum --check --status
-tar -xzf "$node_archive_path" -C "$node_runtime_root"
-export PATH="${node_install_dir}/bin:${PATH}"
-node --version
-npm --version
-
-export PYTHONPATH="$(pwd)/apps/dreamverse${PYTHONPATH:+:$PYTHONPATH}"
-pytest apps/dreamverse/dreamverse/tests -q
-
-cd apps/dreamverse/web
-npm ci
-npm run typecheck
-npm test
-machine_arch=$(uname -m)
-if [[ $machine_arch =~ ^(aarch64|arm64)$ ]]; then
-  npx playwright install --with-deps chromium firefox
-else
-  npx playwright install --with-deps chromium webkit firefox
-fi
-
-master_port=${MASTER_PORT:-7959}
-BACKEND_PORT=${BACKEND_PORT:-$((master_port + 50))}
-python -m uvicorn dreamverse.mock_server:app --host 127.0.0.1 --port "$BACKEND_PORT" &
-mock_server_pid=$!
-cleanup() {
-  kill "$mock_server_pid" 2>/dev/null || true
-  wait "$mock_server_pid" 2>/dev/null || true
-}
-trap cleanup EXIT INT TERM
-
-for _ in {1..30}; do
-  curl -fsS "http://127.0.0.1:$BACKEND_PORT/healthz" && break
-  sleep 1
-done
-curl -fsS "http://127.0.0.1:$BACKEND_PORT/healthz"
-
-if [[ $machine_arch =~ ^(aarch64|arm64)$ ]]; then
-  # Playwright WebKit traps before opening a page on Linux ARM64, and its
-  # bundled Chromium lacks the H.264/AAC codecs used by the fMP4 assertions.
-  # Firefox covers every flow, including streaming. Chromium and its mobile
-  # profile still cover all codec-independent UI behavior on GB200.
-  BACKEND_HOST=127.0.0.1 BACKEND_PORT="$BACKEND_PORT" CI=1 \
-    npm run e2e -- --project=firefox
-  BACKEND_HOST=127.0.0.1 BACKEND_PORT="$BACKEND_PORT" CI=1 \
-    npm run e2e -- \
-      --project=chromium \
-      --project=mobile-chromium \
-      --grep-invert='streams, plays, and surfaces a downloadable clip|starts a new project and switches back to the prior session|saved projects persist across a page reload'
-else
-  BACKEND_HOST=127.0.0.1 BACKEND_PORT="$BACKEND_PORT" CI=1 \
-    npm run e2e -- \
-      --project=chromium \
-      --project=webkit \
-      --project=firefox \
-      --project=mobile-safari \
-      --project=mobile-chromium
-fi

.buildkite/scripts/lanes/encoder.sh

@@ -1,5 +0,0 @@
-#!/usr/bin/env bash
-# Canonical Slurm CI selection for the encoder lane.
-set -euo pipefail
-
-exec pytest ./fastvideo/tests/encoders -vs

.buildkite/scripts/lanes/eval.sh

@@ -1,5 +0,0 @@
-#!/usr/bin/env bash
-# Canonical Slurm CI selection for the evaluation lane.
-set -euo pipefail
-
-exec pytest ./fastvideo/tests/eval -vs

.buildkite/scripts/lanes/golden_gate.sh

@@ -1,35 +0,0 @@
-#!/usr/bin/env bash
-# Canonical Slurm CI selection for the golden-gate lane. Environment (HF_HOME
-# and authentication) is the runner's responsibility.
-set -euo pipefail
-
-golden_root=./fastvideo/tests/golden_gate
-selected=${FASTVIDEO_GOLDEN_TEST_FILES-}
-if [ -z "$selected" ]; then
-  if [ "${TEST_SCOPE:-}" = merge ]; then
-    echo "Missing FASTVIDEO_GOLDEN_TEST_FILES for merge scope" >&2
-    exit 2
-  fi
-  selected=all
-fi
-if [ "$selected" = all ]; then
-  exec pytest "$golden_root" -xvs
-fi
-
-[[ $selected =~ ^test_[a-z0-9_]+\.py(,test_[a-z0-9_]+\.py)*$ ]] || {
-  echo "Invalid FASTVIDEO_GOLDEN_TEST_FILES selection" >&2
-  exit 2
-}
-
-IFS=, read -r -a golden_files <<< "$selected"
-golden_paths=()
-for golden_file in "${golden_files[@]}"; do
-  golden_path="$golden_root/$golden_file"
-  [ -f "$golden_path" ] || {
-    echo "Selected golden test does not exist: $golden_file" >&2
-    exit 2
-  }
-  golden_paths+=("$golden_path")
-done
-
-exec pytest "${golden_paths[@]}" -xvs

.buildkite/scripts/lanes/inference_lora.sh

@@ -1,5 +0,0 @@
-#!/usr/bin/env bash
-# Canonical Slurm CI selection for the LoRA-inference lane.
-set -euo pipefail
-
-exec pytest ./fastvideo/tests/inference/lora/test_lora_inference_similarity.py -vs

.buildkite/scripts/lanes/inference_vmoba.sh

@@ -1,5 +0,0 @@
-#!/usr/bin/env bash
-# Canonical Slurm CI selection for the VMoBA-inference lane.
-set -euo pipefail
-
-exec python fastvideo/tests/inference/vmoba/test_vmoba_inference.py

.buildkite/scripts/lanes/kernel_tests.sh

@@ -1,5 +0,0 @@
-#!/usr/bin/env bash
-# Canonical Slurm CI selection for the custom-kernel lane.
-set -euo pipefail
-
-exec pytest fastvideo-kernel/tests/ -vs

.buildkite/scripts/lanes/lora_extraction.sh

@@ -1,5 +0,0 @@
-#!/usr/bin/env bash
-# Canonical Slurm CI selection for the LoRA-extraction lane.
-set -euo pipefail
-
-exec pytest ./fastvideo/tests/lora_extraction/ -vs

.buildkite/scripts/lanes/performance.sh

@@ -1,64 +0,0 @@
-#!/usr/bin/env bash
-# Canonical Slurm performance lane. Reports are written outside the checkout
-# so the trusted host driver can upload them after untrusted code exits.
-set -uo pipefail
-
-export PERFORMANCE_TRACKING_ROOT=/tmp/perf-tracking
-export PERF_REPORTS_DIR=/workspace/artifacts/performance
-mkdir -p "$PERF_REPORTS_DIR"
-
-if [[ ${BUILDKITE_PULL_REQUEST:-false} =~ ^[1-9][0-9]*$ ]]; then
-  export PERF_RUN_SOURCE=pr
-  export PERF_UPLOAD_POLICY=pass
-elif [ "${BUILDKITE_BRANCH:-}" = main ] \
-  && { [ "${BUILDKITE_SOURCE:-}" = schedule ] || [ "${TEST_SCOPE:-}" = full ]; }; then
-  export PERF_RUN_SOURCE=scheduled_main
-  export PERF_UPLOAD_POLICY=always
-elif [ "${TEST_SCOPE:-}" = direct ]; then
-  export PERF_RUN_SOURCE=unknown
-  export PERF_UPLOAD_POLICY=pass
-else
-  export PERF_RUN_SOURCE=unknown
-  export PERF_UPLOAD_POLICY=never
-fi
-
-nvidia-smi \
-  --query-gpu=index,timestamp,clocks.sm,clocks.max.sm,power.draw,power.limit,temperature.gpu \
-  --format=csv -l 10 > "$PERF_REPORTS_DIR/gpu_telemetry.csv" 2>/dev/null &
-telemetry_pid=$!
-cleanup() {
-  kill "$telemetry_pid" 2>/dev/null || true
-  wait "$telemetry_pid" 2>/dev/null || true
-}
-trap cleanup EXIT INT TERM
-
-pytest ./fastvideo/tests/performance/test_inference_performance.py -vs
-pytest_rc=$?
-compare_rc=0
-if [ "$pytest_rc" -eq 0 ] || [ "$PERF_UPLOAD_POLICY" = always ]; then
-  PERF_PYTEST_RC=$pytest_rc python ./fastvideo/tests/performance/compare_baseline.py
-  compare_rc=$?
-fi
-python ./fastvideo/tests/performance/dashboard.py || true
-cp -f fastvideo/tests/performance/results/*.json "$PERF_REPORTS_DIR/" 2>/dev/null || true
-# The trusted host relays only .md/.html/.json/.csv from PERF_REPORTS_DIR, so
-# mirror each captured worker log with an allowlisted extension.
-for worker_log in fastvideo/tests/performance/results/worker_logs/*.log; do
-  [ -f "$worker_log" ] || continue
-  base=$(basename "${worker_log%.log}")
-  # WorkerLogCapture keeps a .log.1 backup after rollover, and read_log_tail
-  # includes it; mirror that retained history too so the artifact is complete.
-  if [ -f "$worker_log.1" ]; then
-    cp -f "$worker_log.1" "$PERF_REPORTS_DIR/${base}.1.md" 2>/dev/null || true
-  fi
-  cp -f "$worker_log" "$PERF_REPORTS_DIR/${base}.md" 2>/dev/null || true
-done
-
-echo "--- GPU telemetry (clocks.sm vs clocks.max.sm reveals capped hosts) ---"
-cat "$PERF_REPORTS_DIR/gpu_telemetry.csv" || true
-
-final_rc=$pytest_rc
-if [ "$final_rc" -eq 0 ]; then
-  final_rc=$compare_rc
-fi
-exit "$final_rc"

.buildkite/scripts/lanes/self_forcing.sh

@@ -1,6 +0,0 @@
-#!/usr/bin/env bash
-# Canonical Slurm CI selection for the self-forcing lane.
-set -euo pipefail
-
-export WANDB_MODE=offline
-exec pytest ./fastvideo/tests/training/self-forcing/test_self_forcing.py -vs

.buildkite/scripts/lanes/ssim.sh

@@ -1,40 +0,0 @@
-#!/usr/bin/env bash
-# Canonical four-GPU SSIM lane for the Slinky Slurm worker.
-set -euo pipefail
-
-args=()
-if [ "${FASTVIDEO_SSIM_BOOTSTRAP_MODE:-0}" = 1 ]; then
-  args+=(--bootstrap-mode)
-fi
-selected=${FASTVIDEO_SSIM_TEST_FILES-}
-if [ -z "$selected" ]; then
-  if [ "${TEST_SCOPE:-}" = merge ]; then
-    echo "Missing FASTVIDEO_SSIM_TEST_FILES for merge scope" >&2
-    exit 2
-  fi
-  selected=all
-fi
-if [ "$selected" != all ]; then
-  [[ $selected =~ ^test_[a-z0-9_]+\.py(,test_[a-z0-9_]+\.py)*$ ]] || {
-    echo "Invalid FASTVIDEO_SSIM_TEST_FILES selection" >&2
-    exit 2
-  }
-  IFS=, read -r -a ssim_files <<< "$selected"
-  for ssim_file in "${ssim_files[@]}"; do
-    args+=(--test-file "$ssim_file")
-  done
-fi
-
-# MoGe's utils3d dependency builds glcontext from source on ARM64. The current
-# runner image predates the baked-in X11 headers below, so keep this guarded
-# bootstrap until every deployed image digest contains libx11-dev.
-if [ ! -f /usr/include/X11/Xlib.h ]; then
-  apt-get -o Acquire::Retries=5 update
-  apt-get -o Acquire::Retries=5 install -y --no-install-recommends libx11-dev
-  rm -rf /var/lib/apt/lists/*
-fi
-
-uv pip install git+https://github.com/microsoft/MoGe.git
-uv pip install k_diffusion einops_exts alias_free_torch torchsde
-
-exec python fastvideo/tests/ssim/ci_runner.py "${args[@]}"

.buildkite/scripts/lanes/train_framework.sh

@@ -1,5 +0,0 @@
-#!/usr/bin/env bash
-# Canonical Slurm CI selection for the modular training-framework lane.
-set -euo pipefail
-
-exec pytest ./fastvideo/tests/train/models ./fastvideo/tests/train/methods -vs

.buildkite/scripts/lanes/training.sh

@@ -1,6 +0,0 @@
-#!/usr/bin/env bash
-# Canonical Slurm CI selection for the legacy vanilla-training lane.
-set -euo pipefail
-
-export WANDB_MODE=offline
-exec pytest ./fastvideo/tests/training/Vanilla -srP

.buildkite/scripts/lanes/training_lora.sh

@@ -1,6 +0,0 @@
-#!/usr/bin/env bash
-# Canonical Slurm CI selection for the legacy LoRA-training lane.
-set -euo pipefail
-
-export WANDB_MODE=offline
-exec pytest ./fastvideo/tests/training/lora/test_lora_training.py -srP

.buildkite/scripts/lanes/training_vsa.sh

@@ -1,6 +0,0 @@
-#!/usr/bin/env bash
-# Canonical Slurm CI selection for the legacy VSA-training lane.
-set -euo pipefail
-
-export WANDB_MODE=offline
-exec pytest ./fastvideo/tests/training/VSA -srP

.buildkite/scripts/lanes/transformer.sh

@@ -1,9 +0,0 @@
-#!/usr/bin/env bash
-# Canonical Slurm CI selection for the transformer lane.
-set -euo pipefail
-
-# The existing block reference records an absent FASTVIDEO_FA4 (FA2). Keep
-# that reference identity; the component lane also selects FA2 explicitly.
-env -u FASTVIDEO_FA4 pytest ./fastvideo/tests/golden_gate/test_wan_t2v.py -xvs
-pytest ./fastvideo/tests/golden_gate/test_wan_causal.py -xvs
-exec pytest ./fastvideo/tests/transformers -vs

.buildkite/scripts/lanes/vae.sh

@@ -1,6 +0,0 @@
-#!/usr/bin/env bash
-# Canonical Slurm CI selection for the VAE lane.
-set -euo pipefail
-
-pytest ./fastvideo/tests/golden_gate/test_wan_vae.py -xvs
-exec pytest ./fastvideo/tests/vaes -vs

.buildkite/scripts/pr_test.sh

@@ -1,19 +1,6 @@
 #!/bin/bash
 set -uo pipefail
 
-# DORMANT ROLLBACK ONLY. Active CI is Slurm-only and pipeline.yml never calls
-# this launcher. Refuse every Buildkite invocation even if a stale step or
-# operator typo reaches this file; local rollback experiments require an
-# explicit opt-in.
-if [ -n "${BUILDKITE:-}" ]; then
-  echo "Legacy Modal CI is disabled; use the Slinky Slurm runner." >&2
-  exit 2
-fi
-if [ "${FASTVIDEO_ENABLE_LEGACY_MODAL_CI:-0}" != 1 ]; then
-  echo "Legacy Modal CI is dormant. Set FASTVIDEO_ENABLE_LEGACY_MODAL_CI=1 only for a manual rollback test." >&2
-  exit 2
-fi
-
 log() {
   echo "[$(date '+%Y-%m-%d %H:%M:%S')] $1"
 }

.buildkite/scripts/unit_test.sh

@@ -1,42 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-
-# Collect the whole attention directory so new files cannot land uncovered.
-# Its FA2/FA3 regression files skip when FA4 is selected (the Modal image
-# enables FA4 by default), so pin FA4 off for the directory to be real
-# coverage on every runner rather than a nominal collection.
-export FASTVIDEO_FA4=0
-
-# The livestream app's tests are CPU-only; its single gpu-marked module is
-# deselected, and DreamVerse's GPU tests have their own lane.
-exec pytest \
-  ./apps/infinite_livestream/infinite_livestream/tests \
-  ./fastvideo/tests/api/ \
-  ./fastvideo/tests/contract/ \
-  ./fastvideo/tests/dataset/ \
-  ./fastvideo/tests/workflow/ \
-  ./fastvideo/tests/entrypoints/ \
-  ./fastvideo/tests/loader/ \
-  ./fastvideo/tests/pipelines/ \
-  ./fastvideo/tests/platforms/ \
-  ./fastvideo/tests/schedulers/ \
-  ./fastvideo/tests/train/ \
-  ./fastvideo/tests/stages/ \
-  ./fastvideo/tests/ops/ \
-  ./fastvideo/tests/worker/ \
-  ./fastvideo/tests/training/test_runner.py \
-  ./fastvideo/tests/training/test_trackers.py \
-  ./fastvideo/tests/training/test_ltx2_rope_fps.py \
-  ./fastvideo/tests/inference/test_basic_fasth3_omniref_pdd.py \
-  ./fastvideo/tests/inference/test_inference_regional_compile.py \
-  ./fastvideo/tests/attention/ \
-  ./fastvideo/tests/layers/test_pdd_linear.py \
-  ./fastvideo/tests/layers/test_triton_fused_norm.py \
-  ./fastvideo/tests/modal/test_kernel_build_cache.py \
-  ./fastvideo/tests/modal/test_pr_test.py \
-  ./fastvideo/tests/modal/test_ssim_test.py \
-  --ignore=./fastvideo/tests/entrypoints/test_openai_api_integration.py \
-  --ignore=./fastvideo/tests/train/models \
-  --ignore=./fastvideo/tests/train/methods \
-  -m "not gpu" \
-  -vs

.github/PULL_REQUEST_TEMPLATE.md

@@ -8,10 +8,10 @@ PR TITLE: Must start with a type tag, e.g.:
 MERGE WORKFLOW:
   1. Ensure pre-commit passes and you have at least 1 approval
   2. Comment /merge (or add the "ready" label) to enter the Merge Queue
-  3. A path-aware merge gate runs only relevant integration tests → auto-merge on success
+  3. Full Test Suite runs automatically on a staging branch → auto-merge on success
 
 ON-DEMAND TESTING (write access required):
-  /test full       — Explicit all-lane run  /test ssim        — Full SSIM regression
+  /test full       — Full Test Suite        /test ssim        — SSIM regression
   /test training   — Training pipeline      /test encoder     — Encoder tests
   /test transformer — Transformer tests     /test vae         — VAE tests
   /test kernel     — CUDA kernel tests      /test unit        — Unit tests
@@ -61,10 +61,3 @@ Fixes #
 **For model/pipeline changes, also check:**
 - [ ] I verified SSIM regression tests pass
 - [ ] I updated the support matrix if adding a new model
-
-**For new models or serving runtimes:**
-
-- [ ] I added or updated the native serving YAML and [cookbook deployment](https://github.com/hao-ai-lab/FastVideo/blob/main/docs/contributing/cookbook_configuration.md),
-      or explained why this is not applicable.
-- [ ] I documented the GPU type/count and minimum VRAM for the serving setup with supporting measurements,
-      or marked the minimum as unknown and any VRAM estimate as an estimate.

.github/mergify.yml

@@ -205,6 +205,40 @@ pull_request_rules:
       label:
         add: ["scope: model"]
 
+  # ============================================================
+  # Pre-commit failure help comment
+  # ============================================================
+
+  - name: comment on pre-commit failure
+    conditions:
+      - check-failure~=pre-commit
+      - -closed
+    actions:
+      comment:
+        message: |
+          ## Pre-commit checks failed
+
+          Hi @{{author}}, the pre-commit checks have failed. To fix them locally:
+
+          ```bash
+          # Install pre-commit if you haven't already
+          uv pip install pre-commit
+          pre-commit install
+
+          # Run all checks and auto-fix what's possible
+          pre-commit run --all-files
+          ```
+
+          Common fixes:
+          - **yapf**: `yapf -i <file>` (formatting)
+          - **ruff**: `ruff check --fix <file>` (linting)
+          - **codespell**: `codespell --write-changes <file>` (spelling)
+
+          After fixing, commit and push the changes. The checks will re-run automatically.
+
+          For future commits, `pre-commit` will run automatically on changed files before each commit.
+
+
   # ============================================================
   # Merge conflict detection
   # ============================================================
@@ -217,6 +251,16 @@ pull_request_rules:
     actions:
       label:
         add: [needs-rebase]
+      comment:
+        message: |
+          This PR has merge conflicts with the base branch. Please rebase:
+
+          ```bash
+          git fetch origin main
+          git rebase origin/main
+          # Resolve any conflicts, then:
+          git push --force-with-lease
+          ```
 
   - name: remove conflict label when resolved
     conditions:
@@ -246,5 +290,35 @@ pull_request_rules:
       merge:
         method: squash
 
+  # ============================================================
+  # PR title format help
+  # ============================================================
+
+  - name: comment on invalid PR title format
+    conditions:
+      - -closed
+      - -draft
+      - "-title~=(?i)^\\[(feat|feature|bugfix|fix|refactor|perf|ci|doc|docs|misc|chore|kernel|new.?model|skill|skills|infra)\\]"
+    actions:
+      comment:
+        message: |
+          ## ⚠️ PR title format required
+
+          Your PR title must start with a type tag in brackets. Examples:
+          - `[feat] Add new model support`
+          - `[bugfix] Fix VAE tiling corruption`
+          - `[refactor] Restructure training pipeline`
+          - `[perf] Optimize attention kernel`
+          - `[ci] Update test infrastructure`
+          - `[infra] Add activation trace hooks`
+          - `[docs] Add inference guide`
+          - `[misc] Clean up configs`
+          - `[new-model] Port Flux2 to FastVideo`
+          - `[skill] Add add-model agent skill`
+
+          Valid tags: `feat`, `feature`, `bugfix`, `fix`, `refactor`, `perf`, `ci`, `infra`, `doc`, `docs`, `misc`, `chore`, `kernel`, `new-model`, `skill`, `skills`
+
+          Please update your PR title and the merge protection check will pass automatically.
+
 merge_protections_settings:
   reporting_method: check-runs

.github/scripts/gate_full_suite.sh

@@ -1,14 +1,14 @@
 #!/usr/bin/env bash
-# Gate the path-aware Buildkite merge plan on the cheap GitHub checks.
+# Gate the expensive Buildkite full suite on the cheap GitHub checks.
 #
 # Polls the workflow runs for the PR head commit and only exits 0 once the
 # watched cheap workflows (pre-commit, docs build) have succeeded, so the
-# 'ready' label cannot burn path-selected GPU lanes on a head that a cheap
-# check has already doomed.
+# 'ready' label cannot burn ~20 GPU lanes on a head that a cheap check has
+# already doomed.
 #
 # Semantics:
 #   - watched run completed with a bad conclusion  -> exit 1 (fail CLOSED:
-#     no merge gate; the next push re-arms via the 'synchronize' trigger)
+#     no full suite; the next push re-arms via the 'synchronize' trigger)
 #   - watched run cancelled                         -> still pending: the docs
 #     workflow's repo-global 'pages' concurrency group cancels runs superseded
 #     by unrelated pushes, so 'cancelled' is not a verdict on this PR
@@ -29,7 +29,7 @@ set -euo pipefail
 : "${PR_NUMBER:?PR_NUMBER (pull request number) is required}"
 : "${GITHUB_REPOSITORY:?GITHUB_REPOSITORY is required}"
 
-# Workflow-level `name:` values that must be green before the merge gate
+# Workflow-level `name:` values that must be green before the full suite
 # may start. "Deploy Documentation" is path-filtered on PRs, so its run may
 # legitimately never exist; pre-commit always runs, so it must appear.
 WATCHED_NAMES='["pre-commit", "Deploy Documentation"]'
@@ -56,7 +56,7 @@ recheck_ready_label() {
   if pr_json=$(gh_api "repos/${GITHUB_REPOSITORY}/pulls/${PR_NUMBER}" 2>/dev/null); then
     if ! jq -e '[.labels[]?.name] | index("ready")' <<<"$pr_json" >/dev/null 2>&1; then
       echo "::error::PR #${PR_NUMBER} no longer has the 'ready' label —" \
-        "NOT triggering the Buildkite merge gate. Re-add the label to re-arm."
+        "NOT triggering the Buildkite full suite. Re-add the label to re-arm."
       exit 1
     fi
   else
@@ -84,7 +84,7 @@ while true; do
         | map(.name) | join(", ")' <<<"$state")
     if [ -n "$failed" ]; then
       echo "::error::Cheap check(s) failed on ${PR_SHA}: ${failed}." \
-        "NOT triggering the Buildkite merge gate. Push a fix (the 'ready'" \
+        "NOT triggering the Buildkite full suite. Push a fix (the 'ready'" \
         "label re-arms on every push), or re-run the failed check and then" \
         "re-run this workflow."
       exit 1
@@ -97,7 +97,7 @@ while true; do
     if [ "$pending" -eq 0 ]; then
       if [ -z "$missing" ]; then
         recheck_ready_label
-        echo "All watched cheap checks are green — merge gate may proceed."
+        echo "All watched cheap checks are green — full suite may proceed."
         exit 0
       fi
       case "$missing" in
@@ -119,14 +119,14 @@ while true; do
     echo "::warning::GitHub API error querying workflow runs for ${PR_SHA} (attempt ${api_fails}/3)."
     if [ "$api_fails" -ge 3 ]; then
       recheck_ready_label
-      echo "::warning::FAILING OPEN: cannot query GitHub check status — triggering the merge gate WITHOUT the cheap-check gate."
+      echo "::warning::FAILING OPEN: cannot query GitHub check status — triggering the full suite WITHOUT the cheap-check gate."
       exit 0
     fi
   fi
 
   if [ "$elapsed" -ge "$MAX_WAIT_SECS" ]; then
     recheck_ready_label
-    echo "::warning::FAILING OPEN: watched checks still pending after $(( MAX_WAIT_SECS / 60 )) min${missing:+ (never appeared: ${missing})} — triggering the merge gate anyway."
+    echo "::warning::FAILING OPEN: watched checks still pending after $(( MAX_WAIT_SECS / 60 )) min${missing:+ (never appeared: ${missing})} — triggering the full suite anyway."
     exit 0
   fi
   sleep "$POLL_SECS"

.github/scripts/plan_merge_ci.py

@@ -1,578 +0,0 @@
-#!/usr/bin/env python3
-"""Select the additive GPU integration lanes needed by a PR diff.
-
-Fastcheck is the universal six-lane baseline and is intentionally not repeated
-here.  This planner selects only the more expensive merge-gate lanes.  Unknown
-source/build paths fail closed to the complete integration set, while explicit
-documentation and repository-metadata paths require no additional GPU work.
-"""
-
-from __future__ import annotations
-
-import argparse
-import fnmatch
-import re
-from collections.abc import Iterable
-from dataclasses import dataclass, field
-from pathlib import Path
-from typing import TextIO
-
-MERGE_LANES = (
-    "golden-gate",
-    "ssim",
-    "lora-inference",
-    "lora-extraction",
-    "training",
-    "distillation",
-    "self-forcing",
-    "lora-training",
-    "training-vsa",
-    "inference-vmoba",
-    "performance",
-    "api-server",
-    "train-framework",
-    "eval",
-)
-
-LANE_SCRIPT_TO_KEY = {
-    "api_server.sh": "api-server",
-    "distillation_dmd.sh": "distillation",
-    "eval.sh": "eval",
-    "golden_gate.sh": "golden-gate",
-    "inference_lora.sh": "lora-inference",
-    "inference_vmoba.sh": "inference-vmoba",
-    "lora_extraction.sh": "lora-extraction",
-    "performance.sh": "performance",
-    "self_forcing.sh": "self-forcing",
-    "ssim.sh": "ssim",
-    "train_framework.sh": "train-framework",
-    "training.sh": "training",
-    "training_lora.sh": "lora-training",
-    "training_vsa.sh": "training-vsa",
-}
-
-FASTCHECK_LANE_SCRIPTS = {
-    "dreamverse.sh",
-    "encoder.sh",
-    "kernel_tests.sh",
-    "transformer.sh",
-    "vae.sh",
-}
-
-LEGACY_TRAINING_LANES = (
-    "training",
-    "distillation",
-    "self-forcing",
-    "lora-training",
-    "training-vsa",
-)
-
-ALL_TRAINING_LANES = (*LEGACY_TRAINING_LANES, "train-framework")
-
-SSIM_SMOKE_TESTS = (
-    "test_flux_t2i_similarity.py",
-    "test_wan_t2v_similarity.py",
-)
-
-SAFE_PATTERNS = (
-    "*.md",
-    "*.rst",
-    ".agents/**",
-    ".claude/**",
-    ".codex/**",
-    ".github/ISSUE_TEMPLATE/**",
-    ".github/PULL_REQUEST_TEMPLATE.md",
-    ".github/dependabot.yml",
-    ".github/mergify.yml",
-    ".github/scripts/**",
-    ".github/workflows/**",
-    ".buildkite/scripts/pre_commit.sh",
-    ".git-blame-ignore-revs",
-    ".gitattributes",
-    ".gitignore",
-    ".pre-commit-config.yaml",
-    "AGENTS.md",
-    "CITATION.cff",
-    "CODE_OF_CONDUCT.md",
-    "CONTRIBUTING.md",
-    "LICENSE",
-    "NOTICE",
-    "__init__.py",
-    "collect_env.py",
-    "SECURITY.md",
-    "assets/**",
-    "comfyui/**",
-    "docs/**",
-    "examples/**",
-    "mkdocs.yml",
-    "requirements-mkdocs.in",
-    "requirements-mkdocs.txt",
-    "scripts/**",
-    "tests/__init__.py",
-    "tests/local_tests/**",
-)
-
-ALL_IMPACT_PATTERNS = (
-    ".buildkite/pipeline.yml",
-    "docker/**",
-    "pyproject.toml",
-    "requirements*.txt",
-    "setup.cfg",
-    "setup.py",
-    "uv.lock",
-)
-
-
-@dataclass(frozen=True)
-class FamilyCoverage:
-    pattern: re.Pattern[str]
-    golden_tests: tuple[str, ...]
-    ssim_tests: tuple[str, ...]
-
-
-FAMILY_COVERAGE = (
-    FamilyCoverage(
-        re.compile(r"(^|[/_.-])flux[_-]?2([/_.-]|$)"),
-        ("test_flux2_klein.py", ),
-        ("test_flux2_similarity.py", ),
-    ),
-    FamilyCoverage(
-        re.compile(r"(^|[/_.-])flux(?![_-]?2)([/_.-]|$)"),
-        ("test_flux.py", ),
-        ("test_flux_t2i_similarity.py", ),
-    ),
-    FamilyCoverage(
-        re.compile(r"(^|[/_.-])gen3c([/_.-]|$)"),
-        ("test_gen3c.py", ),
-        ("test_gen3c_similarity.py", ),
-    ),
-    FamilyCoverage(
-        re.compile(r"(^|[/_.-])hunyuan(video)?15([a-z0-9_-]*)([/_.-]|$)"),
-        (),
-        ("test_hunyuan15_i2v_similarity.py", ),
-    ),
-    FamilyCoverage(
-        re.compile(r"(^|[/_.-])kandinsky[_-]?5([/_.-]|$)"),
-        ("test_kandinsky5.py", ),
-        ("test_kandinsky5_similarity.py", ),
-    ),
-    FamilyCoverage(
-        re.compile(r"(^|[/_.-])lingbot([a-z0-9_-]*)([/_.-]|$)"),
-        ("test_lingbot.py", ),
-        ("test_lingbot_similarity.py", ),
-    ),
-    FamilyCoverage(
-        re.compile(r"(^|[/_.-])ltx[_-]?2([/_.-]|$)"),
-        ("test_ltx2.py", ),
-        ("test_ltx2_similarity.py", ),
-    ),
-    FamilyCoverage(
-        re.compile(r"(^|[/_.-])matrixgame[_-]?2([/_.-]|$)"),
-        ("test_matrixgame.py", ),
-        ("test_matrixgame2_similarity.py", ),
-    ),
-    FamilyCoverage(
-        re.compile(r"(^|[/_.-])matrixgame[_-]?3([/_.-]|$)"),
-        ("test_matrixgame.py", ),
-        ("test_matrixgame3_similarity.py", ),
-    ),
-    FamilyCoverage(
-        re.compile(r"(^|[/_.-])minimax[_-]?h3([/_.-]|$)"),
-        ("test_minimax_h3_t2v.py", ),
-        ("test_minimax_h3_similarity.py", ),
-    ),
-    FamilyCoverage(
-        re.compile(r"(^|[/_.-])sd[_-]?3([._-]?5)?([/_.-]|$)"),
-        ("test_sd35.py", ),
-        ("test_sd35_similarity.py", ),
-    ),
-    FamilyCoverage(
-        re.compile(r"(^|[/_.-])stable[_-]?audio([/_.-]|$)"),
-        ("test_stable_audio.py", ),
-        ("test_stable_audio_similarity.py", ),
-    ),
-    FamilyCoverage(
-        re.compile(r"(^|[/_.-])wan(video|vae)?([/_.-]|$)"),
-        ("test_wan_t2v.py", "test_wan_vae.py", "test_wan_causal.py", "test_wan_denoising.py"),
-        (
-            "test_causal_similarity.py",
-            "test_wan_i2v_similarity.py",
-            "test_wan_t2v_similarity.py",
-            "test_wan_ti2v_similarity.py",
-        ),
-    ),
-)
-
-
-@dataclass
-class MergePlan:
-    lanes: set[str] = field(default_factory=set)
-    golden_tests: set[str] = field(default_factory=set)
-    ssim_tests: set[str] = field(default_factory=set)
-    golden_all: bool = False
-    ssim_all: bool = False
-    reasons: list[str] = field(default_factory=list)
-
-    def add_lanes(self, *lanes: str, reason: str) -> None:
-        unknown = set(lanes) - set(MERGE_LANES)
-        if unknown:
-            raise ValueError(f"Unknown merge lanes: {sorted(unknown)}")
-        self.lanes.update(lanes)
-        self.reasons.append(reason)
-
-    def add_golden(self, tests: tuple[str, ...], reason: str) -> None:
-        self.add_lanes("golden-gate", reason=reason)
-        self.golden_tests.update(tests)
-
-    def add_ssim(self, tests: tuple[str, ...], reason: str) -> None:
-        self.add_lanes("ssim", reason=reason)
-        self.ssim_tests.update(tests)
-
-    def require_all(self, reason: str) -> None:
-        self.lanes.update(MERGE_LANES)
-        self.golden_all = True
-        self.ssim_all = True
-        self.reasons.append(reason)
-
-    def ordered_lanes(self) -> tuple[str, ...]:
-        return tuple(lane for lane in MERGE_LANES if lane in self.lanes)
-
-    def encoded_lanes(self) -> str:
-        lanes = self.ordered_lanes()
-        return "," + ",".join(lanes or ("none", )) + ","
-
-    def encoded_golden_tests(self) -> str:
-        if "golden-gate" not in self.lanes:
-            return "none"
-        if self.golden_all or not self.golden_tests:
-            return "all"
-        return ",".join(sorted(self.golden_tests))
-
-    def encoded_ssim_tests(self) -> str:
-        if "ssim" not in self.lanes:
-            return "none"
-        if self.ssim_all or not self.ssim_tests:
-            return "all"
-        return ",".join(sorted(self.ssim_tests))
-
-
-def _matches_any(path: str, patterns: tuple[str, ...]) -> bool:
-    return any(fnmatch.fnmatchcase(path, pattern) for pattern in patterns)
-
-
-def _family_coverage(path: str) -> tuple[set[str], set[str]]:
-    normalized = path.lower()
-    golden: set[str] = set()
-    ssim: set[str] = set()
-    for family in FAMILY_COVERAGE:
-        if family.pattern.search(normalized):
-            golden.update(family.golden_tests)
-            ssim.update(family.ssim_tests)
-    # Select the component actually touched, including compatibility paths.
-    # Family configs/pipeline wiring can affect all four Wan gates.
-    if re.search(r"(^|[/_.-])wan(video|vae)?([/_.-]|$)", normalized):
-        if (normalized.endswith(("/wan/vae.py", "/wan/vae_config.py", "/vaes/wanvae.py"))
-                or normalized.endswith("/wan/stages/conditioning.py")):
-            golden = {"test_wan_vae.py"}
-        elif normalized.endswith(("/wan/causal_transformer.py", "/dits/causal_wanvideo.py",
-                                  "/wan/stages/causal_denoising.py")):
-            golden = {"test_wan_causal.py"}
-        elif (normalized == "fastvideo/models/dits/wanvideo.py"
-              or normalized.endswith(("/wan/transformer.py", "/wan/stages/denoising.py", "/wan/stages/dmd.py"))):
-            golden = {"test_wan_t2v.py", "test_wan_denoising.py"}
-    return golden, ssim
-
-
-def _select_output_coverage(plan: MergePlan, path: str) -> None:
-    golden, ssim = _family_coverage(path)
-    if golden:
-        plan.add_golden(tuple(sorted(golden)), reason=f"model-family golden coverage: {path}")
-    else:
-        plan.golden_all = True
-        plan.add_lanes("golden-gate", reason=f"shared output golden coverage: {path}")
-    if ssim:
-        plan.add_ssim(tuple(sorted(ssim)), reason=f"model-family SSIM coverage: {path}")
-    else:
-        plan.add_ssim(SSIM_SMOKE_TESTS, reason=f"shared output SSIM smoke coverage: {path}")
-
-
-def _normalize_path(raw_path: str) -> str:
-    path = raw_path.strip()
-    while path.startswith("./"):
-        path = path[2:]
-    return path
-
-
-def classify_paths(paths: list[str], removed_paths: Iterable[str] = ()) -> MergePlan:
-    """Plan merge lanes for ``paths``.
-
-    ``removed_paths`` lists changed paths that no longer exist at the PR head
-    (deleted files and rename sources); removed golden/SSIM tests are not run.
-    """
-    plan = MergePlan()
-    normalized_paths = sorted({path for path in map(_normalize_path, paths) if path})
-    removed = {path for path in map(_normalize_path, removed_paths) if path}
-    if not normalized_paths:
-        plan.require_all("changed-file list was empty; failing closed")
-        return plan
-
-    for path in normalized_paths:
-        if path == "__FASTVIDEO_CI_PLAN_ALL__":
-            plan.require_all("changed-file API failed; failing closed")
-            continue
-
-        if path in {"requirements-mkdocs.in", "requirements-mkdocs.txt"}:
-            plan.reasons.append(f"documentation dependencies need no GPU integration: {path}")
-            continue
-
-        if _matches_any(path, ALL_IMPACT_PATTERNS):
-            plan.require_all(f"cross-cutting build/runtime surface: {path}")
-            continue
-
-        lane_script_prefix = ".buildkite/scripts/lanes/"
-        if path.startswith(lane_script_prefix):
-            script_name = Path(path).name
-            lane = LANE_SCRIPT_TO_KEY.get(script_name)
-            if lane is None:
-                if script_name in FASTCHECK_LANE_SCRIPTS:
-                    plan.reasons.append(f"covered by automatic Fastcheck lane: {path}")
-                else:
-                    plan.require_all(f"unknown lane script: {path}")
-            elif lane == "golden-gate":
-                plan.golden_all = True
-                plan.add_lanes(lane, reason=f"golden lane implementation: {path}")
-            elif lane == "ssim":
-                plan.ssim_all = True
-                plan.add_lanes(lane, reason=f"SSIM lane implementation: {path}")
-            else:
-                plan.add_lanes(lane, reason=f"lane implementation: {path}")
-            continue
-
-        if path.startswith("fastvideo/tests/golden_gate/"):
-            name = Path(path).name
-            if name.startswith("test_") and name.endswith(".py"):
-                if path in removed:
-                    plan.reasons.append(f"removed golden test has nothing to run: {path}")
-                else:
-                    plan.add_golden((name, ), reason=f"changed golden test: {path}")
-            elif name in {"AGENTS.md", "README.md"}:
-                plan.reasons.append(f"golden documentation only: {path}")
-            else:
-                plan.golden_all = True
-                plan.add_lanes("golden-gate", reason=f"shared golden harness/reference: {path}")
-            continue
-
-        if path.startswith("fastvideo/tests/ssim/"):
-            name = Path(path).name
-            if name.startswith("test_") and name.endswith(".py"):
-                if path in removed:
-                    plan.reasons.append(f"removed SSIM test has nothing to run: {path}")
-                else:
-                    plan.add_ssim((name, ), reason=f"changed SSIM test: {path}")
-            elif path.endswith((".py", ".json", ".pt", ".png", ".mp4")):
-                plan.ssim_all = True
-                plan.add_lanes("ssim", reason=f"shared SSIM harness/reference: {path}")
-            continue
-
-        if path.startswith("fastvideo/tests/performance/") or path.startswith(".buildkite/performance-benchmarks/"):
-            plan.add_lanes("performance", reason=f"performance coverage: {path}")
-            continue
-        if path.startswith(("fastvideo/performance/", "fastvideo/performance_dashboard/",
-                            "apps/performance_dashboard/")):
-            plan.add_lanes("performance", reason=f"performance implementation: {path}")
-            continue
-        if path.startswith("fastvideo/benchmarks/"):
-            if "/mlx_" in path or Path(path).name.startswith("mlx_"):
-                plan.reasons.append(f"covered by the path-filtered macOS MLX workflow: {path}")
-            else:
-                plan.add_lanes("performance", reason=f"benchmark implementation: {path}")
-            continue
-        if path.startswith("fastvideo/tests/eval/") or path.startswith("fastvideo/eval/"):
-            plan.add_lanes("eval", reason=f"evaluation coverage: {path}")
-            continue
-        if path.startswith("fastvideo/third_party/eval/"):
-            plan.add_lanes("eval", reason=f"vendored evaluation implementation: {path}")
-            continue
-        if path.startswith("fastvideo/tests/lora_extraction/") or path.startswith("scripts/lora_extraction/"):
-            plan.add_lanes("lora-extraction", reason=f"LoRA extraction coverage: {path}")
-            continue
-        if path.startswith("fastvideo/tests/inference/lora/"):
-            plan.add_lanes("lora-inference", reason=f"LoRA inference coverage: {path}")
-            continue
-        if path.startswith("fastvideo/tests/inference/vmoba/"):
-            plan.add_lanes("inference-vmoba", reason=f"VMoBA inference coverage: {path}")
-            continue
-        if path.startswith(("fastvideo/dataset/", "fastvideo/workflow/", "fastvideo/pipelines/preprocess/",
-                            "fastvideo/pipelines/training/")):
-            plan.add_lanes(*ALL_TRAINING_LANES, reason=f"shared data/training input surface: {path}")
-            continue
-        if path.startswith("fastvideo/tests/train/") or path.startswith("fastvideo/train/"):
-            plan.add_lanes("train-framework", reason=f"modular training coverage: {path}")
-            continue
-
-        if path.startswith("fastvideo/tests/training/"):
-            lowered = path.lower()
-            if "/vanilla/" in lowered:
-                plan.add_lanes("training", reason=f"vanilla training coverage: {path}")
-            elif "/distill/" in lowered:
-                plan.add_lanes("distillation", reason=f"distillation coverage: {path}")
-            elif "/self-forcing/" in lowered:
-                plan.add_lanes("self-forcing", reason=f"self-forcing coverage: {path}")
-            elif "/lora/" in lowered:
-                plan.add_lanes("lora-training", reason=f"LoRA training coverage: {path}")
-            elif "/vsa/" in lowered:
-                plan.add_lanes("training-vsa", reason=f"VSA training coverage: {path}")
-            else:
-                plan.add_lanes(*LEGACY_TRAINING_LANES, reason=f"shared legacy training coverage: {path}")
-            continue
-
-        if path.startswith("fastvideo/training/"):
-            lowered = path.lower()
-            if "self_forcing" in lowered:
-                plan.add_lanes("self-forcing", reason=f"self-forcing implementation: {path}")
-            elif "distill" in lowered:
-                plan.add_lanes("distillation", reason=f"distillation implementation: {path}")
-            elif "lora" in lowered:
-                plan.add_lanes("lora-training", reason=f"LoRA training implementation: {path}")
-            else:
-                plan.add_lanes(*LEGACY_TRAINING_LANES, reason=f"shared legacy training implementation: {path}")
-            continue
-
-        lowered = path.lower()
-        if "vmoba" in lowered and path.startswith(("fastvideo/", ".buildkite/")):
-            plan.add_lanes("inference-vmoba", reason=f"VMoBA implementation: {path}")
-            plan.add_golden(("test_wan_t2v.py", ), reason=f"VMoBA end-to-end coverage: {path}")
-            continue
-        if "lora" in lowered and path.startswith("fastvideo/"):
-            plan.add_lanes(
-                "lora-inference",
-                "lora-extraction",
-                "lora-training",
-                reason=f"shared LoRA implementation: {path}",
-            )
-            _select_output_coverage(plan, path)
-            continue
-
-        if path.startswith("fastvideo/entrypoints/") or path.startswith("fastvideo/api/"):
-            plan.add_lanes("api-server", reason=f"API/entrypoint integration: {path}")
-            if "openai" not in lowered and "/cli/" not in lowered:
-                _select_output_coverage(plan, path)
-            continue
-        if path.startswith("fastvideo/worker/"):
-            plan.add_lanes("api-server", reason=f"worker/API integration: {path}")
-            _select_output_coverage(plan, path)
-            continue
-        if path.startswith("fastvideo/distributed/"):
-            plan.add_lanes(
-                "training",
-                "train-framework",
-                reason=f"distributed runtime integration: {path}",
-            )
-            _select_output_coverage(plan, path)
-            continue
-        if path.startswith(("fastvideo/hooks/", "fastvideo/platforms/", "fastvideo/third_party/")):
-            _select_output_coverage(plan, path)
-            continue
-        if path.startswith(("fastvideo/models/", "fastvideo/pipelines/", "fastvideo/configs/",
-                            "fastvideo/layers/", "fastvideo/attention/")):
-            _select_output_coverage(plan, path)
-            continue
-        if path in {
-                "fastvideo/fastvideo_args.py",
-                "fastvideo/forward_context.py",
-                "fastvideo/image_processor.py",
-                "fastvideo/registry.py",
-                "fastvideo/utils.py",
-        }:
-            _select_output_coverage(plan, path)
-            continue
-        if path.startswith("fastvideo/mlx_runtime/"):
-            plan.reasons.append(f"covered by the path-filtered macOS MLX workflow: {path}")
-            continue
-        if path.startswith("fastvideo/logging_utils/") or path in {
-                "fastvideo/__init__.py",
-                "fastvideo/envs.py",
-                "fastvideo/logger.py",
-                "fastvideo/profiler.py",
-                "fastvideo/version.py",
-        }:
-            plan.reasons.append(f"covered by automatic Fastcheck: {path}")
-            continue
-        if path.startswith(("fastvideo-kernel/", "csrc/")):
-            plan.add_golden(("test_wan_t2v.py", ), reason=f"kernel integration smoke: {path}")
-            plan.add_ssim(("test_wan_t2v_similarity.py", ), reason=f"kernel numerical smoke: {path}")
-            continue
-
-        if path.startswith("apps/dreamverse/"):
-            # DreamVerse is already one of the six automatic Fastcheck lanes.
-            plan.reasons.append(f"covered by automatic DreamVerse Fastcheck: {path}")
-            continue
-        if path.startswith("apps/infinite_livestream/"):
-            # The app's CPU-only tests run in the automatic unit Fastcheck lane.
-            plan.reasons.append(f"covered by automatic unit Fastcheck: {path}")
-            continue
-        if path.startswith("fastvideo/tests/"):
-            # The automatic unit/component Fastcheck lanes own the remaining
-            # package tests. Domain-specific expensive test roots were handled
-            # above.
-            plan.reasons.append(f"covered by automatic Fastcheck: {path}")
-            continue
-        if path in {".buildkite/scripts/unit_test.sh", ".buildkite/scripts/pr_test.sh"}:
-            plan.reasons.append(f"covered by automatic unit Fastcheck: {path}")
-            continue
-        if _matches_any(path, SAFE_PATTERNS):
-            plan.reasons.append(f"no additional GPU integration needed: {path}")
-            continue
-
-        plan.require_all(f"unclassified path; failing closed: {path}")
-
-    return plan
-
-
-def _write_github_output(output: TextIO, plan: MergePlan) -> None:
-    output.write(f"merge_test_plan={plan.encoded_lanes()}\n")
-    output.write(f"merge_golden_tests={plan.encoded_golden_tests()}\n")
-    output.write(f"merge_ssim_tests={plan.encoded_ssim_tests()}\n")
-    output.write(f"merge_plan_label={','.join(plan.ordered_lanes()) or 'none'}\n")
-
-
-def _write_summary(output: TextIO, plan: MergePlan) -> None:
-    output.write("## Change-aware merge test plan\n\n")
-    output.write("| Selection | Value |\n|---|---|\n")
-    output.write(f"| Additional Slurm lanes | `{','.join(plan.ordered_lanes()) or 'none'}` |\n")
-    output.write(f"| Golden tests | `{plan.encoded_golden_tests()}` |\n")
-    output.write(f"| SSIM tests | `{plan.encoded_ssim_tests()}` |\n\n")
-    output.write("Fastcheck remains the universal six-lane baseline.\n")
-
-
-def parse_args() -> argparse.Namespace:
-    parser = argparse.ArgumentParser(description=__doc__)
-    parser.add_argument("--paths-file", type=Path, required=True)
-    parser.add_argument("--removed-paths-file", type=Path)
-    parser.add_argument("--github-output", type=Path)
-    parser.add_argument("--summary-file", type=Path)
-    return parser.parse_args()
-
-
-def main() -> int:
-    args = parse_args()
-    paths = args.paths_file.read_text(encoding="utf-8").splitlines()
-    removed_paths = (args.removed_paths_file.read_text(encoding="utf-8").splitlines()
-                     if args.removed_paths_file else [])
-    plan = classify_paths(paths, removed_paths)
-    print(f"MERGE_TEST_PLAN={plan.encoded_lanes()}")
-    print(f"MERGE_GOLDEN_TESTS={plan.encoded_golden_tests()}")
-    print(f"MERGE_SSIM_TESTS={plan.encoded_ssim_tests()}")
-    for reason in plan.reasons:
-        print(f"- {reason}")
-    if args.github_output:
-        with args.github_output.open("a", encoding="utf-8") as output:
-            _write_github_output(output, plan)
-    if args.summary_file:
-        with args.summary_file.open("a", encoding="utf-8") as output:
-            _write_summary(output, plan)
-    return 0
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())

.github/scripts/test_gate_full_suite.sh

@@ -53,7 +53,7 @@ PC_PENDING='{"name": "pre-commit", "id": 1, "status": "in_progress", "conclusion
 DOCS_OK='{"name": "Deploy Documentation", "id": 2, "status": "completed", "conclusion": "success"}'
 DOCS_BAD='{"name": "Deploy Documentation", "id": 2, "status": "completed", "conclusion": "failure"}'
 DOCS_CANCELLED='{"name": "Deploy Documentation", "id": 2, "status": "completed", "conclusion": "cancelled"}'
-OTHER='{"name": "Trigger Merge Gate", "id": 3, "status": "in_progress", "conclusion": null}'
+OTHER='{"name": "Trigger Full Suite", "id": 3, "status": "in_progress", "conclusion": null}'
 NULL_NAME='{"name": null, "id": 4, "status": "completed", "conclusion": "failure"}'
 PC_OK_RERUN='{"name": "pre-commit", "id": 5, "status": "completed", "conclusion": "success"}'
 

.github/workflows/_template-build-image.yml

@@ -190,7 +190,6 @@ jobs:
         if: ${{ !inputs.push_by_digest }}
         run: |
           echo "✅ Python ${{ inputs.python_version }} image successfully built and pushed to ${{ steps.image.outputs.name }}:${{ inputs.tag_suffix }}-sha-${GITHUB_SHA::7}"
-          echo "Digest: ${{ steps.build-push.outputs.digest }}"
           echo "To run tests with this image, manually trigger the 'Run Tests' workflow."
 
       - name: Digest success message

.github/workflows/ci-aggregate-status.yml

@@ -26,54 +26,29 @@ jobs:
               per_page: 100,
             });
 
-            // Buildkite derives the GitHub context prefix from the label emoji.
-            // Keep hard Full Suite lanes in test-tube/bar-chart namespaces and
-            // Fastcheck lanes in microscope so targeted reruns cannot clear the
-            // wrong aggregate status. Automatic PR jobs use pr-fastcheck while
-            // slash-command and Full Suite jobs use ci; normalize the suffix
-            // and keep the newest status for each logical lane.
-            const FASTCHECK_PREFIXES = [
-              'buildkite/pr-fastcheck/microscope-',
-              'buildkite/ci/microscope-',
-            ];
+            const bkStatuses = data.statuses.filter(
+              s => s.context.startsWith('buildkite/ci/')
+            );
+
+            const FASTCHECK_PREFIX = 'buildkite/ci/microscope-';
             const FULL_SUITE_PREFIXES = [
               'buildkite/ci/test-tube-',
               'buildkite/ci/bar-chart-',
             ];
 
-            function newestByLane(prefixes) {
-              const statuses = new Map();
-              for (const status of data.statuses) {
-                const prefix = prefixes.find(p => status.context.startsWith(p));
-                if (!prefix) continue;
-                const lane = status.context.slice(prefix.length);
-                const previous = statuses.get(lane);
-                if (!previous || Date.parse(status.updated_at) > Date.parse(previous.updated_at)) {
-                  statuses.set(lane, status);
-                }
-              }
-              return statuses;
-            }
-
-            const fastcheck = newestByLane(FASTCHECK_PREFIXES);
-            const fullSuiteOnly = newestByLane(FULL_SUITE_PREFIXES);
-            const fastcheckPassed =
-              fastcheck.size === 6
-              && [...fastcheck.values()].every(s => s.state === 'success');
-            const fullSuitePassed =
-              fastcheckPassed
-              && fullSuiteOnly.size === 14
-              && [...fullSuiteOnly.values()].every(s => s.state === 'success');
-
-            // Direct reruns may repair a failed suite, never create a gate for
-            // a suite that did not run.
-            const failedAggregate = context => data.statuses.some(
-              s => s.context === context && s.state === 'failure'
+            const fastcheck = bkStatuses.filter(
+              s => s.context.startsWith(FASTCHECK_PREFIX)
+            );
+            const fullSuite = bkStatuses.filter(
+              s => FULL_SUITE_PREFIXES.some(p => s.context.startsWith(p))
             );
 
-            if (failedAggregate('fastcheck-passed') && fastcheckPassed) {
+            if (
+              fastcheck.length > 0
+              && fastcheck.every(s => s.state === 'success')
+            ) {
               core.info(
-                `All ${fastcheck.size} fastcheck tests passed — updating fastcheck-passed`
+                `All ${fastcheck.length} fastcheck tests passed — updating fastcheck-passed`
               );
               await github.rest.repos.createCommitStatus({
                 owner: context.repo.owner,
@@ -81,13 +56,17 @@ jobs:
                 sha,
                 state: 'success',
                 context: 'fastcheck-passed',
-                description: `All ${fastcheck.size} fastcheck tests passed`,
+                description:
+                  `All ${fastcheck.length} fastcheck tests passed`,
               });
             }
 
-            if (failedAggregate('full-suite-passed') && fullSuitePassed) {
+            if (
+              fullSuite.length > 0
+              && fullSuite.every(s => s.state === 'success')
+            ) {
               core.info(
-                'All 20 full suite tests passed — updating full-suite-passed'
+                `All ${fullSuite.length} full suite tests passed — updating full-suite-passed`
               );
               await github.rest.repos.createCommitStatus({
                 owner: context.repo.owner,
@@ -95,6 +74,7 @@ jobs:
                 sha,
                 state: 'success',
                 context: 'full-suite-passed',
-                description: 'All 20 full suite tests passed',
+                description:
+                  `All ${fullSuite.length} full suite tests passed`,
               });
             }

.github/workflows/ci-macos-mlx.yml

@@ -1,170 +0,0 @@
-name: macOS MLX Smoke
-
-on:
-  pull_request:
-    branches: [main]
-    paths:
-      - ".github/workflows/ci-macos-mlx.yml"
-      - "fastvideo/mlx_runtime/**"
-      - "fastvideo/tests/mlx/**"
-      - "fastvideo/tests/platforms/test_mps_vsa_error.py"
-      - "fastvideo/tests/platforms/test_cpu_sdpa.py"
-      - "fastvideo/platforms/cpu.py"
-      - "fastvideo/platforms/mps.py"
-      - "fastvideo/platforms/__init__.py"
-      - "fastvideo/__init__.py"
-      - "examples/inference/basic/mlx_*.py"
-      - "fastvideo/benchmarks/mlx_*.py"
-      - "pyproject.toml"
-  workflow_dispatch:
-
-permissions:
-  contents: read
-
-concurrency:
-  group: macos-mlx-${{ github.ref }}
-  cancel-in-progress: true
-
-jobs:
-  mlx-smoke:
-    if: github.event_name == 'workflow_dispatch' || github.event.pull_request.draft != true
-    runs-on: macos-15
-    timeout-minutes: 25
-    env:
-      FASTVIDEO_ATTENTION_BACKEND: TORCH_SDPA
-      TOKENIZERS_PARALLELISM: "false"
-      MASTER_ADDR: "127.0.0.1"
-      MASTER_PORT: "29513"
-      GLOO_SOCKET_IFNAME: lo0
-    steps:
-      - uses: actions/checkout@v4
-
-      - uses: actions/setup-python@v5
-        with:
-          python-version: "3.12"
-
-      - uses: astral-sh/setup-uv@v3
-
-      - name: Install lightweight MLX smoke dependencies
-        run: |
-          uv pip install --system \
-            --index-url https://download.pytorch.org/whl/cpu \
-            torch==2.12.0 torchvision torchaudio
-          uv pip install --system \
-            pytest pytest-timeout numpy scipy pillow imageio einops cloudpickle filelock \
-            PyYAML diffusers huggingface_hub remote-pdb safetensors loguru mlx \
-            "ftfy>=6.3.1" "opencv-python>=4.10.0.84" psutil "transformers>=5.0.0"
-
-      - name: Show Apple runtime
-        run: |
-          python - <<'PY'
-          import platform
-          import mlx.core as mx
-          import torch
-
-          print("machine:", platform.machine())
-          print("processor:", platform.processor())
-          print("mlx default device:", mx.default_device())
-          device_info = mx.metal.device_info() if mx.metal.is_available() else "metal unavailable"
-          print("mlx device_info:", device_info)
-          print("torch:", torch.__version__)
-          print("torch mps available:", torch.backends.mps.is_available())
-          PY
-
-      - name: Run MLX smoke tests
-        run: |
-          python -m pytest \
-            fastvideo/mlx_runtime/tests/ \
-            fastvideo/tests/mlx/test_dmd_sampling.py \
-            fastvideo/tests/mlx/test_memory_limits.py \
-            fastvideo/tests/mlx/test_quant_capability.py \
-            fastvideo/tests/mlx/test_mlx_dit_parity.py \
-            fastvideo/tests/mlx/test_mlx_compile_parity.py \
-            fastvideo/tests/mlx/test_mlx_checkpoint.py \
-            fastvideo/tests/mlx/test_mlx_checkpoint_compat.py \
-            fastvideo/tests/mlx/test_mlx_affine_dq_gemm.py \
-            fastvideo/tests/mlx/test_mlx_minimax_h3_parity.py \
-            fastvideo/tests/mlx/test_mlx_minimax_h3_vsa.py \
-            fastvideo/tests/mlx/test_mlx_minimax_h3_vsa_regressions.py \
-            fastvideo/tests/mlx/test_mlx_minimax_h3_fast_mode.py \
-            fastvideo/tests/mlx/test_mlx_minimax_h3_fast_spatial.py \
-            fastvideo/tests/mlx/test_mlx_fastwan_benchmark.py \
-            fastvideo/tests/mlx/test_taehv_decode.py \
-            fastvideo/tests/mlx/test_frame_upsample.py \
-            fastvideo/tests/mlx/test_mlx_fast_spatial.py \
-            fastvideo/tests/mlx/test_mlx_refine.py \
-            fastvideo/tests/mlx/test_mlx_prompt_enhance.py \
-            fastvideo/tests/mlx/test_mlx_prompt_to_video_decode.py \
-            fastvideo/tests/mlx/test_mlx_wan22_prompt_cache_fingerprint.py \
-            fastvideo/tests/mlx/test_wan22_sample.py \
-            fastvideo/tests/mlx/test_windowed_attention.py \
-            fastvideo/tests/mlx/test_mlx_rife_interpolation.py::test_rife_download_unavailable_has_specific_error \
-            fastvideo/tests/mlx/test_mlx_rife_interpolation.py::test_rife_backend_regression_is_not_skip_eligible \
-            fastvideo/tests/platforms/test_mps_vsa_error.py \
-            fastvideo/tests/platforms/test_cpu_sdpa.py \
-            -v -s --timeout=120 -o faulthandler_timeout=120
-
-  # Same tests on MLX's CPU backend. Hosted macOS runners are scarce and
-  # slower to schedule; this Linux job gives fast PR signal on the identical
-  # graph (the parity tests were designed to be backend-agnostic), while the
-  # macOS job above stays the source of truth for Metal behavior.
-  mlx-smoke-linux-cpu:
-    if: github.event_name == 'workflow_dispatch' || github.event.pull_request.draft != true
-    runs-on: ubuntu-latest
-    timeout-minutes: 20
-    env:
-      FASTVIDEO_ATTENTION_BACKEND: TORCH_SDPA
-      TOKENIZERS_PARALLELISM: "false"
-      MASTER_ADDR: localhost
-      MASTER_PORT: "29513"
-    steps:
-      - uses: actions/checkout@v4
-
-      - uses: actions/setup-python@v5
-        with:
-          python-version: "3.12"
-
-      - uses: astral-sh/setup-uv@v3
-
-      - name: Install lightweight MLX smoke dependencies (CPU backend)
-        run: |
-          uv pip install --system \
-            --index-url https://download.pytorch.org/whl/cpu \
-            torch==2.12.0 torchvision torchaudio
-          uv pip install --system \
-            pytest pytest-timeout numpy scipy pillow imageio einops cloudpickle filelock \
-            PyYAML diffusers huggingface_hub remote-pdb safetensors loguru "mlx[cpu]" \
-            "ftfy>=6.3.1" "opencv-python>=4.10.0.84" psutil "transformers>=5.0.0"
-
-      - name: Run MLX smoke tests (CPU backend)
-        run: |
-          python -m pytest \
-            fastvideo/mlx_runtime/tests/ \
-            fastvideo/tests/mlx/test_dmd_sampling.py \
-            fastvideo/tests/mlx/test_memory_limits.py \
-            fastvideo/tests/mlx/test_quant_capability.py \
-            fastvideo/tests/mlx/test_mlx_dit_parity.py \
-            fastvideo/tests/mlx/test_mlx_compile_parity.py \
-            fastvideo/tests/mlx/test_mlx_checkpoint.py \
-            fastvideo/tests/mlx/test_mlx_checkpoint_compat.py \
-            fastvideo/tests/mlx/test_mlx_affine_dq_gemm.py \
-            fastvideo/tests/mlx/test_mlx_minimax_h3_parity.py \
-            fastvideo/tests/mlx/test_mlx_minimax_h3_vsa.py \
-            fastvideo/tests/mlx/test_mlx_minimax_h3_vsa_regressions.py \
-            fastvideo/tests/mlx/test_mlx_minimax_h3_fast_mode.py \
-            fastvideo/tests/mlx/test_mlx_minimax_h3_fast_spatial.py \
-            fastvideo/tests/mlx/test_mlx_fastwan_benchmark.py \
-            fastvideo/tests/mlx/test_taehv_decode.py \
-            fastvideo/tests/mlx/test_frame_upsample.py \
-            fastvideo/tests/mlx/test_mlx_fast_spatial.py \
-            fastvideo/tests/mlx/test_mlx_refine.py \
-            fastvideo/tests/mlx/test_mlx_prompt_enhance.py \
-            fastvideo/tests/mlx/test_mlx_prompt_to_video_decode.py \
-            fastvideo/tests/mlx/test_mlx_wan22_prompt_cache_fingerprint.py \
-            fastvideo/tests/mlx/test_wan22_sample.py \
-            fastvideo/tests/mlx/test_windowed_attention.py \
-            fastvideo/tests/mlx/test_mlx_rife_interpolation.py::test_rife_download_unavailable_has_specific_error \
-            fastvideo/tests/mlx/test_mlx_rife_interpolation.py::test_rife_backend_regression_is_not_skip_eligible \
-            fastvideo/tests/platforms/test_mps_vsa_error.py \
-            fastvideo/tests/platforms/test_cpu_sdpa.py \
-            -v -s --timeout=120 -o faulthandler_timeout=120

.github/workflows/ci-scheduled-ssim.yml

@@ -1,44 +0,0 @@
-name: Scheduled Full SSIM
-
-on:
-  schedule:
-    - cron: "0 5 * * 0"
-  workflow_dispatch:
-
-permissions:
-  contents: read
-
-jobs:
-  trigger:
-    if: github.repository == 'hao-ai-lab/FastVideo'
-    runs-on: ubuntu-latest
-    steps:
-      - name: Trigger weekly full SSIM on Slinky Slurm
-        env:
-          BUILDKITE_API_TOKEN: ${{ secrets.BUILDKITE_API_TOKEN }}
-          SOURCE_SHA: ${{ github.sha }}
-          SOURCE_BRANCH: ${{ github.event.repository.default_branch }}
-          BK_ORG: ${{ vars.BUILDKITE_ORG_SLUG }}
-          BK_PIPELINE: ${{ vars.BUILDKITE_PIPELINE_SLUG }}
-        run: |
-          set -euo pipefail
-          curl -sS --fail-with-body -X POST \
-            "https://api.buildkite.com/v2/organizations/${BK_ORG}/pipelines/${BK_PIPELINE}/builds" \
-            -H "Authorization: Bearer $BUILDKITE_API_TOKEN" \
-            -H "Content-Type: application/json" \
-            --data-raw "$(jq -n \
-              --arg commit "$SOURCE_SHA" \
-              --arg branch "$SOURCE_BRANCH" \
-              '{
-                commit: $commit,
-                branch: $branch,
-                message: "Weekly full SSIM on Slinky Slurm",
-                ignore_pipeline_branch_filters: true,
-                env: {
-                  TEST_SCOPE: "scheduled",
-                  FULL_SUITE: "false",
-                  TEST_TYPE: "ssim",
-                  PR_NUMBER: "false",
-                  PR_TITLE: "Scheduled full SSIM"
-                }
-              }')"

.github/workflows/ci-slash-commands.yml

@@ -32,7 +32,8 @@ jobs:
             }
             core.setOutput('has_write', String(hasWrite));
 
-      - name: Add ready label
+      - name: Add ready label and react
+        id: label
         if: steps.perm.outputs.has_write == 'true'
         uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7.0.1
         with:
@@ -40,33 +41,54 @@ jobs:
             const owner = context.repo.owner;
             const repo = context.repo.repo;
             const prNumber = context.payload.issue.number;
+            try { await github.rest.issues.removeLabel({ owner, repo, issue_number: prNumber, name: 'ready' }); } catch {}
             await github.rest.issues.addLabels({ owner, repo, issue_number: prNumber, labels: ['ready'] });
-
-      - name: React to comment
-        if: steps.perm.outputs.has_write == 'true'
-        continue-on-error: true
-        uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7.0.1
-        with:
-          script: |
             await github.rest.reactions.createForIssueComment({
-              owner: context.repo.owner,
-              repo: context.repo.repo,
+              owner, repo,
               comment_id: context.payload.comment.id,
               content: 'rocket',
             });
+            const { data: pr } = await github.rest.pulls.get({ owner, repo, pull_number: prNumber });
+            core.setOutput('pr_sha', pr.head.sha);
+            core.setOutput('pr_branch', pr.head.ref);
+            core.setOutput('pr_number', String(prNumber));
+            core.setOutput('pr_title', pr.title);
 
-  trigger-merge-gate:
-    needs: handle-merge
-    if: needs.handle-merge.result == 'success'
-    permissions:
-      actions: read
-      contents: read
-      pull-requests: read
-    uses: ./.github/workflows/ci-trigger-full-suite.yml
-    with:
-      pr_number: ${{ github.event.issue.number }}
-    secrets:
-      BUILDKITE_API_TOKEN: ${{ secrets.BUILDKITE_API_TOKEN }}
+      - name: Trigger Full Suite
+        if: steps.perm.outputs.has_write == 'true'
+        env:
+          BUILDKITE_API_TOKEN: ${{ secrets.BUILDKITE_API_TOKEN }}
+          PR_SHA: ${{ steps.label.outputs.pr_sha }}
+          PR_BRANCH: ${{ steps.label.outputs.pr_branch }}
+          PR_NUMBER: ${{ steps.label.outputs.pr_number }}
+          PR_TITLE: ${{ steps.label.outputs.pr_title }}
+          BK_ORG: ${{ vars.BUILDKITE_ORG_SLUG }}
+          BK_PIPELINE: ${{ vars.BUILDKITE_PIPELINE_SLUG }}
+        run: |
+          curl -sS --fail-with-body -X POST \
+            "https://api.buildkite.com/v2/organizations/${BK_ORG}/pipelines/${BK_PIPELINE}/builds" \
+            -H "Authorization: Bearer $BUILDKITE_API_TOKEN" \
+            -H "Content-Type: application/json" \
+            --data-raw "$(jq -n \
+              --arg commit "$PR_SHA" \
+              --arg branch "$PR_BRANCH" \
+              --arg message "Full Suite for PR #${PR_NUMBER} (via /merge)" \
+              --arg pr_title "$PR_TITLE" \
+              --argjson pr_id "$PR_NUMBER" \
+              '{
+                commit: $commit,
+                branch: $branch,
+                message: $message,
+                ignore_pipeline_branch_filters: true,
+                pull_request_id: $pr_id,
+                pull_request_base_branch: "main",
+                env: {
+                    TEST_SCOPE: "full",
+                    FULL_SUITE: "true",
+                    PR_NUMBER: ($pr_id | tostring),
+                    PR_TITLE: $pr_title
+                  }
+                }')"
 
   parse-command:
     if: >-
@@ -107,7 +129,7 @@ jobs:
           set -euo pipefail
           TEST_NAME=$(echo "$COMMENT" | grep -oP '(?<=/test\s)\S+' | head -1 || true)
 
-          VALID="encoder vae transformer kernel unit dreamverse ssim golden-gate training lora-inference lora-training lora-extraction distillation self-forcing vsa vmoba performance api train-framework eval unit-ci kernel-ci dreamverse-ci ssim-ci golden-gate-ci encoder-ci vae-ci transformer-ci lora-inference-ci lora-training-ci lora-extraction-ci training-ci distillation-ci self-forcing-ci vsa-ci vmoba-ci performance-ci api-ci train-framework-ci eval-ci full fastcheck pre-commit"
+          VALID="encoder vae transformer kernel unit dreamverse ssim golden-gate training lora-inference lora-training lora-extraction distillation self-forcing vsa vmoba performance api train-framework eval full fastcheck pre-commit"
           if [ -z "$TEST_NAME" ] || ! echo "$VALID" | grep -qw "$TEST_NAME"; then
             echo "Unknown test: '$TEST_NAME'. Valid: $VALID"
             exit 1
@@ -115,17 +137,7 @@ jobs:
 
           declare -A MAP=(
             [encoder]=encoder [vae]=vae [transformer]=transformer
-            [kernel]=kernel_tests [unit]=unit_test [unit-ci]=unit_test_ci
-            [kernel-ci]=kernel_tests_ci [dreamverse-ci]=dreamverse_app_ci
-            [ssim-ci]=ssim_ci [vmoba-ci]=inference_vmoba_ci
-            [golden-gate-ci]=golden_gate_ci [training-ci]=training_ci
-            [encoder-ci]=encoder_ci [vae-ci]=vae_ci [transformer-ci]=transformer_ci
-            [lora-inference-ci]=inference_lora_ci [lora-training-ci]=training_lora_ci
-            [lora-extraction-ci]=lora_extraction_ci [distillation-ci]=distillation_dmd_ci
-            [self-forcing-ci]=self_forcing_ci [vsa-ci]=training_vsa_ci
-            [performance-ci]=performance_ci [api-ci]=api_server_ci
-            [train-framework-ci]=train_framework_ci [eval-ci]=eval_ci
-            [dreamverse]=dreamverse_app
+            [kernel]=kernel_tests [unit]=unit_test [dreamverse]=dreamverse_app
             [ssim]=ssim [golden-gate]=golden_gate [training]=training
             [lora-inference]=inference_lora [lora-training]=training_lora
             [lora-extraction]=lora_extraction

.github/workflows/ci-trigger-full-suite.yml

@@ -1,239 +1,81 @@
-name: Trigger Merge Gate
+name: Trigger Full Suite
 
 on:
   pull_request_target:
     types: [labeled, synchronize]
-  workflow_call:
-    inputs:
-      pr_number:
-        description: Pull request number to enter into the merge gate
-        required: true
-        type: number
-    secrets:
-      BUILDKITE_API_TOKEN:
-        required: true
 
 permissions:
   contents: read
   pull-requests: read
   actions: read
 
+concurrency:
+  group: full-suite-${{ github.event.pull_request.number }}
+  cancel-in-progress: false
+
 jobs:
   trigger:
     if: >-
-      inputs.pr_number > 0
-      || (github.event.action == 'labeled' && github.event.label.name == 'ready')
+      (github.event.action == 'labeled' && github.event.label.name == 'ready')
       || github.event.action == 'synchronize'
     runs-on: ubuntu-latest
-    # Job-level concurrency: only this guarded job acquires the group, so an
-    # unrelated `labeled` event (which skips the job) cannot cancel an in-flight
-    # gate and then skip its replacement. The newest real trigger (`ready`,
-    # push, or `/merge`) supersedes the in-flight run, whose Buildkite build the
-    # cancel step below replaces.
-    concurrency:
-      group: merge-gate-${{ inputs.pr_number || github.event.pull_request.number }}
-      cancel-in-progress: true
     # Gate below may wait for cheap checks (up to MAX_WAIT_SECS = 25 min).
     timeout-minutes: 35
     steps:
       - name: Check ready label
         id: check
         uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7.0.1
-        env:
-          CALLED_PR_NUMBER: ${{ inputs.pr_number }}
         with:
           script: |
-            const eventPrNumber = context.payload.pull_request?.number;
-            const calledPrNumber = Number(process.env.CALLED_PR_NUMBER);
-            const prNumber = eventPrNumber ?? calledPrNumber;
-            if (!Number.isSafeInteger(prNumber) || prNumber <= 0) {
-              core.setFailed(`Invalid pull request number: ${process.env.CALLED_PR_NUMBER}`);
-              return;
-            }
             const { data: pr } = await github.rest.pulls.get({
               owner: context.repo.owner,
               repo: context.repo.repo,
-              pull_number: prNumber,
+              pull_number: context.payload.pull_request.number,
             });
-            if (pr.state !== 'open') {
-              core.setFailed(`PR #${prNumber} is not open.`);
-              return;
-            }
-            if (pr.base.repo.full_name !== context.payload.repository.full_name
-                || pr.base.ref !== context.payload.repository.default_branch) {
-              core.setFailed(`PR #${prNumber} does not target this repository's default branch.`);
-              return;
-            }
             const hasReady = pr.labels.some(l => l.name === 'ready');
             core.setOutput('has_ready', String(hasReady));
-            core.setOutput('changed_files', String(pr.changed_files));
-            core.setOutput('pr_number', String(pr.number));
-            core.setOutput('head_sha', pr.head.sha);
-            core.setOutput('head_ref', pr.head.ref);
-            core.setOutput('base_sha', pr.base.sha);
-            core.setOutput('title', pr.title);
-            if (!hasReady) core.info('No ready label — skipping merge-gate trigger.');
+            if (!hasReady) core.info('No ready label — skipping Full Suite trigger.');
 
       - name: Cancel previous Buildkite builds
-        # Cancelling stale builds only saves agent time. If it cannot run, the
-        # merge gate must still be triggered by the steps below, so a failure
-        # here is reported and stepped over rather than ending the job.
-        continue-on-error: true
-        timeout-minutes: 3
         if: steps.check.outputs.has_ready == 'true'
         env:
-          BK_ORG: ${{ vars.BUILDKITE_ORG_SLUG }}
-          BK_PIPELINE: ${{ vars.BUILDKITE_PIPELINE_SLUG }}
           BUILDKITE_API_TOKEN: ${{ secrets.BUILDKITE_API_TOKEN }}
-          PR_BRANCH: ${{ steps.check.outputs.head_ref }}
-          PR_NUMBER: ${{ steps.check.outputs.pr_number }}
+          PR_BRANCH: ${{ github.event.pull_request.head.ref }}
         run: |
-          set -euo pipefail
-          response_file=$(mktemp)
-          builds_file=$(mktemp)
-          trap 'rm -f "$response_file" "$builds_file"' EXIT
-
-          if [[ ! "$PR_NUMBER" =~ ^[1-9][0-9]*$ ]]; then
-            echo "::warning::Invalid pull request number; stale Buildkite builds may continue."
-            exit 1
-          fi
-
-          if ! curl -sS --fail-with-body --connect-timeout 5 --max-time 20 --get \
-            -H "Authorization: Bearer $BUILDKITE_API_TOKEN" \
-            --data-urlencode "branch=$PR_BRANCH" \
-            --data-urlencode "state[]=running" \
-            --data-urlencode "state[]=scheduled" \
-            --data-urlencode "state[]=failing" \
-            --data-urlencode "exclude_jobs=true" \
-            --data-urlencode "exclude_pipeline=true" \
-            --output "$response_file" \
-            "https://api.buildkite.com/v2/organizations/${BK_ORG}/pipelines/${BK_PIPELINE}/builds"; then
-            echo "::warning::Could not list Buildkite builds; stale merge-gate builds may continue."
-            exit 1
-          fi
-
-          if ! jq -e '
-            if type != "array" then false
-            else all(.[];
-              if type != "object" then false
-              else
-                (.number | if type == "number" then . > 0 and floor == . else false end)
-                and (
-                  (.env? | if . == null then {} else . end) as $env
-                  | if ($env | type) != "object" then false
-                    else
-                      ($env.TEST_SCOPE? | . == null or type == "string")
-                      and ($env.PR_NUMBER? | . == null or type == "string")
-                    end
-                )
-              end
-            )
-            end
-          ' "$response_file" >/dev/null 2>&1; then
-            # Do not print the response body: it is remote data and may contain
-            # multiline values that would be interpreted as workflow commands.
-            echo "::warning::Buildkite returned an invalid build list; stale merge-gate builds may continue."
-            exit 1
-          fi
-
-          # Match both branch and PR number: forks can reuse the same branch name.
-          if ! jq -r --arg pr_number "$PR_NUMBER" '
-            .[]
-            | select((.env.TEST_SCOPE? == "merge") and (.env.PR_NUMBER? == $pr_number))
-            | .number
-          ' "$response_file" > "$builds_file"; then
-            echo "::warning::Could not select stale Buildkite builds; stale merge-gate builds may continue."
-            exit 1
-          fi
-
-          cancellation_failed=0
-          while IFS= read -r build_num; do
+          # Find running builds for this branch with TEST_SCOPE=full and cancel them
+          builds=$(curl -sS -H "Authorization: Bearer $BUILDKITE_API_TOKEN" \
+            "https://api.buildkite.com/v2/organizations/${{ vars.BUILDKITE_ORG_SLUG }}/pipelines/${{ vars.BUILDKITE_PIPELINE_SLUG }}/builds?branch=${PR_BRANCH}&state=running,scheduled" \
+            | jq -r '.[] | select(try (.env.TEST_SCOPE == "full") catch false) | .number')
+          for build_num in $builds; do
             echo "Cancelling Buildkite build #$build_num"
-            if ! curl -sS --fail-with-body --connect-timeout 5 --max-time 20 -o /dev/null -X PUT \
-              -H "Authorization: Bearer $BUILDKITE_API_TOKEN" \
-              "https://api.buildkite.com/v2/organizations/${BK_ORG}/pipelines/${BK_PIPELINE}/builds/${build_num}/cancel"; then
-              echo "::warning::Could not cancel Buildkite build #$build_num; trying remaining builds."
-              cancellation_failed=1
-            fi
-          done < "$builds_file"
+            curl -sS -X PUT -H "Authorization: Bearer $BUILDKITE_API_TOKEN" \
+              "https://api.buildkite.com/v2/organizations/${{ vars.BUILDKITE_ORG_SLUG }}/pipelines/${{ vars.BUILDKITE_PIPELINE_SLUG }}/builds/${build_num}/cancel"
+          done
 
-          if (( cancellation_failed != 0 )); then
-            exit 1
-          fi
-
-      # Check out the immutable BASE SHA: neither pull_request_target nor the
-      # privileged slash-command call may run code from the untrusted PR head.
-      - name: Checkout trusted merge planner
+      # Checks out the BASE branch (default for pull_request_target), so PR
+      # authors cannot tamper with the gate script.
+      - name: Checkout gate script
         if: steps.check.outputs.has_ready == 'true'
         uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
-        with:
-          ref: ${{ steps.check.outputs.base_sha }}
-          persist-credentials: false
-
-      - name: Collect changed paths
-        if: steps.check.outputs.has_ready == 'true'
-        env:
-          GH_TOKEN: ${{ github.token }}
-          PR_NUMBER: ${{ steps.check.outputs.pr_number }}
-          EXPECTED_CHANGED_FILES: ${{ steps.check.outputs.changed_files }}
-        run: |
-          set -euo pipefail
-          changed_json="$RUNNER_TEMP/merge-changed-files.json"
-          changed_paths="$RUNNER_TEMP/merge-changed-paths.txt"
-          removed_paths="$RUNNER_TEMP/merge-removed-paths.txt"
-          : > "$removed_paths"
-          if gh api --paginate --slurp \
-              "repos/${GITHUB_REPOSITORY}/pulls/${PR_NUMBER}/files?per_page=100" \
-              > "$changed_json"; then
-            observed=$(jq '[.[][] | .filename] | unique | length' "$changed_json")
-            if [ "$observed" = "$EXPECTED_CHANGED_FILES" ]; then
-              jq -r '.[][] | .filename, (.previous_filename // empty)' "$changed_json" \
-                | sort -u > "$changed_paths"
-              # Paths absent from the PR head, so the planner never selects a deleted test.
-              jq -r '.[][] | if .status == "removed" then .filename
-                  elif .status == "renamed" then (.previous_filename // empty) else empty end' \
-                "$changed_json" | sort -u > "$removed_paths"
-            else
-              echo "::warning::Changed-file API returned $observed of $EXPECTED_CHANGED_FILES paths; selecting all merge lanes."
-              echo '__FASTVIDEO_CI_PLAN_ALL__' > "$changed_paths"
-            fi
-          else
-            echo "::warning::Changed-file API failed; selecting all merge lanes."
-            echo '__FASTVIDEO_CI_PLAN_ALL__' > "$changed_paths"
-          fi
-
-      - name: Select minimal merge tests
-        id: plan
-        if: steps.check.outputs.has_ready == 'true'
-        run: |
-          python3 .github/scripts/plan_merge_ci.py \
-            --paths-file "$RUNNER_TEMP/merge-changed-paths.txt" \
-            --removed-paths-file "$RUNNER_TEMP/merge-removed-paths.txt" \
-            --github-output "$GITHUB_OUTPUT" \
-            --summary-file "$GITHUB_STEP_SUMMARY"
 
       - name: Wait for pre-commit and docs build
         if: steps.check.outputs.has_ready == 'true'
         env:
           GH_TOKEN: ${{ github.token }}
-          PR_SHA: ${{ steps.check.outputs.head_sha }}
-          PR_NUMBER: ${{ steps.check.outputs.pr_number }}
+          PR_SHA: ${{ github.event.pull_request.head.sha }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
         run: bash .github/scripts/gate_full_suite.sh
 
-      - name: Trigger Buildkite merge gate
+      - name: Trigger Buildkite Full Suite
         if: steps.check.outputs.has_ready == 'true'
         env:
           BUILDKITE_API_TOKEN: ${{ secrets.BUILDKITE_API_TOKEN }}
-          PR_SHA: ${{ steps.check.outputs.head_sha }}
-          PR_BRANCH: ${{ steps.check.outputs.head_ref }}
-          PR_NUMBER: ${{ steps.check.outputs.pr_number }}
-          PR_TITLE: ${{ steps.check.outputs.title }}
+          PR_SHA: ${{ github.event.pull_request.head.sha }}
+          PR_BRANCH: ${{ github.event.pull_request.head.ref }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          PR_TITLE: ${{ github.event.pull_request.title }}
           BK_ORG: ${{ vars.BUILDKITE_ORG_SLUG }}
           BK_PIPELINE: ${{ vars.BUILDKITE_PIPELINE_SLUG }}
-          MERGE_TEST_PLAN: ${{ steps.plan.outputs.merge_test_plan }}
-          MERGE_GOLDEN_TESTS: ${{ steps.plan.outputs.merge_golden_tests }}
-          MERGE_SSIM_TESTS: ${{ steps.plan.outputs.merge_ssim_tests }}
-          MERGE_PLAN_LABEL: ${{ steps.plan.outputs.merge_plan_label }}
         run: |
           curl -sS --fail-with-body -X POST \
             "https://api.buildkite.com/v2/organizations/${BK_ORG}/pipelines/${BK_PIPELINE}/builds" \
@@ -242,11 +84,8 @@ jobs:
             --data-raw "$(jq -n \
               --arg commit "$PR_SHA" \
               --arg branch "$PR_BRANCH" \
-              --arg message "Merge gate [${MERGE_PLAN_LABEL}] for PR #${PR_NUMBER}" \
+              --arg message "Full Suite for PR #${PR_NUMBER}" \
               --arg pr_title "$PR_TITLE" \
-              --arg merge_test_plan "$MERGE_TEST_PLAN" \
-              --arg merge_golden_tests "$MERGE_GOLDEN_TESTS" \
-              --arg merge_ssim_tests "$MERGE_SSIM_TESTS" \
               --argjson pr_id "$PR_NUMBER" \
               '{
                 commit: $commit,
@@ -256,11 +95,8 @@ jobs:
                 pull_request_id: $pr_id,
                 pull_request_base_branch: "main",
                 env: {
-                  TEST_SCOPE: "merge",
+                  TEST_SCOPE: "full",
                   FULL_SUITE: "true",
-                  MERGE_TEST_PLAN: $merge_test_plan,
-                  MERGE_GOLDEN_TESTS: $merge_golden_tests,
-                  MERGE_SSIM_TESTS: $merge_ssim_tests,
                   PR_NUMBER: ($pr_id | tostring),
                   PR_TITLE: $pr_title
                 }

.github/workflows/community-stale.yml

@@ -0,0 +1,51 @@
+name: Close Stale Issues and PRs
+
+on:
+  schedule:
+    # Daily at 1:30 AM UTC
+    - cron: '30 1 * * *'
+
+jobs:
+  stale:
+    if: github.repository == 'hao-ai-lab/FastVideo'
+    permissions:
+      issues: write
+      pull-requests: write
+      actions: write
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/stale@997185467fa4f803885201cee163a9f38240193d # v10.1.1
+        with:
+          operations-per-run: 500
+
+          exempt-draft-pr: true
+          exempt-issue-labels: 'keep-open,pinned,security,Bug,RFC'
+          exempt-pr-labels: 'keep-open,pinned'
+
+          labels-to-add-when-unstale: 'unstale'
+          labels-to-remove-when-stale: 'unstale'
+
+          days-before-issue-stale: 90
+          days-before-issue-close: 30
+          stale-issue-label: 'stale'
+          stale-issue-message: >
+            This issue has been automatically marked as stale because it has not
+            had any activity within 90 days. It will be automatically closed if
+            no further activity occurs within 30 days. Leave a comment if you
+            feel this issue should remain open. Thank you!
+          close-issue-message: >
+            This issue has been automatically closed due to inactivity. Please
+            feel free to reopen if you feel it is still relevant. Thank you!
+
+          days-before-pr-stale: 60
+          days-before-pr-close: 14
+          stale-pr-label: 'stale'
+          stale-pr-message: >
+            This pull request has been automatically marked as stale because it
+            has not had any activity within 60 days. It will be automatically
+            closed if no further activity occurs within 14 days. Leave a comment
+            if you feel this pull request should remain open. Thank you!
+          close-pr-message: >
+            This pull request has been automatically closed due to inactivity.
+            Please feel free to reopen if you intend to continue working on it.
+            Thank you!

.github/workflows/community-welcome.yml

@@ -0,0 +1,56 @@
+name: Welcome First-Time Contributors
+
+on:
+  issues:
+    types: [opened]
+  pull_request_target:
+    types: [opened]
+
+permissions:
+  issues: write
+  pull-requests: write
+
+jobs:
+  welcome:
+    if: github.repository == 'hao-ai-lab/FastVideo'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/first-interaction@34f15e814fe48ac9312ccf29db4e74fa767cbab7 # v1.3.0
+        with:
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+          issue-message: |
+            Welcome to FastVideo! Thanks for opening your first issue.
+
+            To help us investigate, please include:
+            - **FastVideo version**: `pip show fastvideo`
+            - **GPU**: `nvidia-smi` output (GPU model, driver, CUDA version)
+            - **Python version**: `python --version`
+            - **OS**: e.g., Ubuntu 22.04
+
+            If this is a bug, a minimal reproduction script helps us fix it faster.
+
+            Useful links:
+            - [Documentation](https://hao-ai-lab.github.io/FastVideo)
+            - [Contributing Guide](https://hao-ai-lab.github.io/FastVideo/contributing/overview/)
+            - [Slack](https://join.slack.com/t/fastvideo/shared_invite/zt-3f4lao1uq-u~Ipx6Lt4J27AlD2y~IdLQ)
+          pr-message: |
+            Welcome to FastVideo! Thanks for your first pull request.
+
+            **How our CI works:**
+
+            PRs run a two-tier CI system:
+            1. **Pre-commit** — formatting (yapf), linting (ruff), type checking (mypy). Runs immediately on every PR.
+            2. **Fastcheck** — core GPU tests (encoders, VAEs, transformers, kernels, unit tests). Runs automatically via Buildkite on relevant file changes (~10-15 min).
+            3. **Full Suite** — integration tests, training pipelines, SSIM regression. Runs only when a reviewer adds the `ready` label.
+
+            **Before your PR is reviewed:**
+            - [ ] `pre-commit run --all-files` passes locally
+            - [ ] You've added or updated tests for your changes
+            - [ ] The PR description explains what and why
+
+            If pre-commit fails, a bot comment will explain how to fix it. Fastcheck and Full Suite results appear in the Checks section below.
+
+            **Useful links:**
+            - [Contributing Guide](https://hao-ai-lab.github.io/FastVideo/contributing/overview/)
+            - [Development Roadmap](https://github.com/hao-ai-lab/FastVideo/issues/899)
+            - [Slack](https://join.slack.com/t/fastvideo/shared_invite/zt-3f4lao1uq-u~Ipx6Lt4J27AlD2y~IdLQ)

.github/workflows/infra-build-image.yml

@@ -13,11 +13,6 @@ on:
         required: false
         default: false
         type: boolean
-      build_ci_runner_image:
-        description: 'Build the ARM64 CUDA 13 CI runner image (sm_100)'
-        required: false
-        default: false
-        type: boolean
   # Auto-rebuild the CUDA images when a repository-controlled image input
   # changes on main. This includes the trusted SM89 kernel artifact's source,
   # metadata/key helper, ABI dependency metadata, and build orchestration.
@@ -203,28 +198,6 @@ jobs:
           docker buildx imagetools create "${TAG_ARGS[@]}" "${IMAGE_REFS[@]}"
           docker buildx imagetools inspect "${TAGS[0]}"
 
-  # The CI runner is ARM64 like DGX Spark, but targets sm_100 rather than sm_121.
-  # Publish a single-architecture variant so the self-hosted CI runner can reuse
-  # the exact prebuilt kernel instead of compiling it in every job.
-  build-ci-runner-image:
-    if: ${{ (github.event_name == 'push' && github.repository == 'hao-ai-lab/FastVideo') || github.event.inputs.build_ci_runner_image == 'true' }}
-    uses: ./.github/workflows/_template-build-image.yml
-    with:
-      python_version: '3.12'
-      dockerfile_path: docker/Dockerfile
-      tag_suffix: py3.12-cuda13.0.0-sm100
-      runner: ubuntu-24.04-arm
-      architecture: arm64
-      build_args: |
-        PYTHON_VERSION=3.12
-        CUDA_VERSION=13.0.0
-        UV_TORCH_BACKEND=cu130
-        TORCH_CUDA_ARCH_LIST=10.0
-        CMAKE_BUILD_PARALLEL_LEVEL=1
-        FLASH_ATTN_WHEEL_TAG=cu130torch2.12
-        FLASH_ATTN_WHEEL_RELEASE_ARM64=https://github.com/mjun0812/flash-attention-prebuild-wheels/releases/download/v0.9.22
-    secrets: inherit
-
   # Dreamverse matrix: {backend, UI} x {12.6.3, 13.0.0}, Python 3.12. Torch backend
   # matches the base CUDA (cu126 / cu130). Keep these images amd64-only until the
   # required FA4 dependency stack is available and validated on arm64.

.github/workflows/infra-docs.yml

@@ -6,7 +6,6 @@ on:
     paths:
       - 'docs/**'
       - 'examples/**'
-      - 'scripts/inference/**'
       - 'mkdocs.yml'
       - 'requirements-mkdocs.in'
       - 'requirements-mkdocs.txt'
@@ -17,7 +16,6 @@ on:
     paths:
       - 'docs/**'
       - 'examples/**'
-      - 'scripts/inference/**'
       - 'mkdocs.yml'
       - 'requirements-mkdocs.in'
       - 'requirements-mkdocs.txt'
@@ -56,21 +54,6 @@ jobs:
       - name: Setup Pages
         uses: actions/configure-pages@v4
 
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: '22'
-
-      - name: Install cookbook dependencies
-        run: npm ci --prefix docs
-
-      - name: Validate and generate cookbook catalogs
-        run: |
-          npm run check:cookbook --prefix docs
-          npm run test:cookbook --prefix docs
-          python docs/tests/test_cookbook_assets.py
-          npm run build:catalog --prefix docs
-
       - name: Build documentation
         run: mkdocs build
 

.github/workflows/publish-kernel.yml

@@ -62,13 +62,12 @@ jobs:
               cuda-version: '13.0.0'
               torch-cuda-short: 'cu130'
           platform:
-            # x86_64 builds the full cu126 + cu130 set. cu130 ships the
-            # data-center Blackwell sm_100a/sm_103a VSA and consumer sm_120a FP4
-            # kernels.
+            # x86_64 builds the full cu126 + cu130 set (cu130 ships the consumer
+            # Blackwell sm_120a FP4 kernels).
             - os: ubuntu-22.04
               arch: x86_64
               wheel-plat: manylinux_2_35_x86_64
-          # aarch64 is Blackwell (GB200 sm_100a/sm_103a + sm_120a + DGX Spark sm_121a), not
+          # aarch64 is Blackwell (GB200 sm_100a + DGX Spark / consumer sm_120a), not
           # Hopper, and Blackwell needs CUDA >= 12.8 — so only the cu130 leg applies.
           # Added via include so x86 keeps cu126 + cu130 while aarch64 stays cu130-only.
           include:
@@ -125,7 +124,7 @@ jobs:
       - name: Install dependencies (GCC, Clang, CUDA Paths, Git)
         run: |
           sudo apt update
-          sudo apt install -y git gcc-11 g++-11 clang-11
+          sudo apt install -y git patchelf gcc-11 g++-11 clang-11
           sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-11 100 --slave /usr/bin/g++ g++ /usr/bin/g++-11
 
           # Allow Git to Access Safe Directory
@@ -164,24 +163,22 @@ jobs:
           cd fastvideo-kernel
           git submodule update --init --recursive  # Ensure ThunderKittens submodule is initialized
           # Release builds run on GPU-less runners, so set kernels + arch explicitly:
-          #   * aarch64 = Blackwell (GB200 sm_100a/sm_103a + sm_120a + DGX Spark sm_121a), NOT
-          #     Hopper, so TK (sm_90a wgmma) is OFF. The C++ FP4 (attn_qat_infer)
-          #     covers sm_120a+sm_121a; turbodiffusion covers every listed arch. The
-          #     sm_100 FP4 forward is the FA4 CuTe DSL path in the fastvideo package (PR #1221),
+          #   * aarch64 = Blackwell (GB200 sm_100a + DGX Spark/consumer sm_120a), NOT
+          #     Hopper, so TK (sm_90a wgmma) is OFF. The C++ FP4 (attn_qat_infer, SM120)
+          #     covers sm_120a; turbodiffusion covers sm_100a+sm_120a. The sm_100 FP4
+          #     forward is the FA4 CuTe DSL path in the fastvideo package (PR #1221),
           #     JIT-compiled at runtime — not built into this wheel.
-          #   * x86_64 cu130 = Hopper TK + data-center Blackwell sm_100a/sm_103a VSA
-          #     + consumer Blackwell sm_120a FP4.
+          #   * x86_64 cu130 = Hopper TK + consumer Blackwell sm_120a FP4.
           #   * x86_64 cu126 = Hopper TK only (older drivers; CUDA < 12.8 has no FP4).
-          # The per-arch split in CMakeLists pins the FP4 targets to requested
-          # sm_120a/sm_121a and builds the main extension for the full arch list.
-          # CMAKE_BUILD_PARALLEL_LEVEL caps
+          # The per-arch split in CMakeLists pins the FP4 targets to sm_120a and builds
+          # the main extension for the full arch list. CMAKE_BUILD_PARALLEL_LEVEL caps
           # Ninja so heavy CUTLASS/TK template TUs don't OOM the 16 GB runner (exit 143).
           if [ "${{ matrix.platform.arch }}" = "aarch64" ]; then
-            export TORCH_CUDA_ARCH_LIST="10.0a;10.3a;12.0a;12.1a"
+            export TORCH_CUDA_ARCH_LIST="10.0a;12.0a"
             export CMAKE_ARGS="${CMAKE_ARGS:-} -DFASTVIDEO_KERNEL_BUILD_TK=OFF -DFASTVIDEO_KERNEL_BUILD_ATTN_QAT_INFER=ON"
             export CMAKE_BUILD_PARALLEL_LEVEL=1
           elif [ "${{ matrix.torch-cuda.torch-cuda-short }}" = "cu130" ]; then
-            export TORCH_CUDA_ARCH_LIST="9.0a;10.0a;10.3a;12.0a"
+            export TORCH_CUDA_ARCH_LIST="9.0a;12.0a"
             export CMAKE_ARGS="${CMAKE_ARGS:-} -DFASTVIDEO_KERNEL_BUILD_TK=ON -DFASTVIDEO_KERNEL_BUILD_ATTN_QAT_INFER=ON -DCMAKE_CUDA_ARCHITECTURES=90a"
             # A single FP4 TU (attn_qat_infer) can use ~8-12 GB on its own, so serialize.
             export CMAKE_BUILD_PARALLEL_LEVEL=1
@@ -197,11 +194,7 @@ jobs:
           python -m build --wheel --outdir dist
 
           # Fix the wheel to be manylinux compliant
-          # Ubuntu 22.04 ships patchelf 0.14.3, while current auditwheel
-          # requires at least 0.14.5. Use the stable PyPI binary on both
-          # x86_64 and aarch64 release runners.
-          uv pip install --system auditwheel patchelf==0.17.2.4
-          patchelf --version
+          uv pip install --system auditwheel
           # Point auditwheel at torch libs, but do not vendor them into the wheel.
           TORCH_LIB_DIR=$(python - <<'PY'
           import os
@@ -218,8 +211,7 @@ jobs:
             --exclude libtorch.so \
             --exclude libc10.so \
             --exclude libc10_cuda.so \
-            --exclude libtorch_python.so \
-            --exclude libnccl.so.2
+            --exclude libtorch_python.so
           # Move fixed wheels back to dist for upload consistency
           rm dist/*.whl
           mv fixed_dist/*.whl dist/
@@ -251,8 +243,7 @@ jobs:
       - name: Download PyPI wheels
         # Publish the cu130 (CUDA 13) wheels to PyPI for both architectures:
         #   x86_64  — Hopper sm_90a TK + consumer Blackwell sm_120a FP4
-        #   aarch64 — Blackwell: turbodiffusion (sm_100a/sm_103a/sm_120a/sm_121a)
-        #             + C++ FP4 (sm_120a/sm_121a);
+        #   aarch64 — Blackwell: turbodiffusion (sm_100a/sm_120a) + C++ FP4 (sm_120a);
         #             no TK (Hopper). sm_100 FP4 forward is the FA4 CuTe DSL path in the
         #             fastvideo package (#1221), shipped/JIT separately.
         # The x86_64 cu126 wheel stays available as a build artifact / GitHub-release asset.

.gitignore

@@ -23,7 +23,6 @@ Miniconda3-latest-Linux-x86_64.sh
 *validation/
 data/
 outputs/
-outputs_audio/
 outputs_video
 checkpoints/
 sbatch.sh
@@ -36,6 +35,7 @@ env
 *.log
 weights/
 logs/
+/Z-Image/
 official_weights/
 converted_weights/
 
@@ -54,10 +54,6 @@ eggs/
 
 # MkDocs documentation
 site/
-docs/assets/cookbook-serving.json
-docs/assets/cookbook-config/
-examples/serving/clients/node_modules/
-docs/node_modules/
 docs/getting_started/examples/
 docs/examples/
 docs/inference/examples/
@@ -135,16 +131,8 @@ openspec/
 fastvideo/tests/ssim/reference_videos/**
 !fastvideo/tests/ssim/reference_videos/**/*.mp4
 !fastvideo/tests/ssim/reference_videos/**/*.png
-fastvideo/tests/ssim/.reference_videos_download.lock
-
-# Local H3 MLX kernel / exactness benches (JSON, logs, frames, videos)
-.kernel_bench/
 
 # Editor logs and local Python version pins (accidentally committed)
 *.nvimlog
 .nvimlog
 .python-version
-/LTX-2-Reference/
-/DFDReference/
-scripts/benchmarks/minimax_h3_pro6000/headline_results/
-fastvideo/tests/ssim/.reference_videos_download.lock

.gitmodules

@@ -7,6 +7,3 @@
 [submodule "fastvideo/third_party/eval/vbench"]
 	path = fastvideo/third_party/eval/vbench
 	url = https://github.com/Vchitect/VBench.git
-[submodule "fastvideo/third_party/eval/vqeval"]
-	path = fastvideo/third_party/eval/vqeval
-	url = https://github.com/JiusiServe/LongVideoSparseAttention.git

.pre-commit-config.yaml

@@ -6,10 +6,10 @@ exclude: |
     fastvideo/third_party/.*|
     fastvideo-kernel/.*|
     assets/.*|
-    (?<!docs/)tests/.*|
+    tests/.*|
     scripts/.*|
     fastvideo/dataset/.*|
-    fastvideo/models/(?!wan/(config|vae_config|pipeline_config|definition|__init__)\.py$).*|
+    fastvideo/models/.*|
     ^apps/dreamverse/web/.*|
     examples/.*|
     \.agents/.*|
@@ -65,14 +65,6 @@ repos:
     language: system
     always_run: true
     pass_filenames: false
-  - id: cookbook-javascript
-    name: Cookbook JavaScript lint and format
-    entry: npm run check:cookbook --prefix docs
-    language: system
-    # CI's trusted manual stage must not execute PR-authored npm scripts.
-    stages: [pre-commit]
-    files: ^docs/(js/(build-)?cookbook-.*\.mjs|tests/.*\.test\.mjs|eslint\.config\.mjs|prettier\.config\.mjs|package(-lock)?\.json)$
-    pass_filenames: false
   # Keep `suggestion` last
   - id: suggestion
     name: Suggestion

AGENTS.md

@@ -66,18 +66,14 @@ Local guidance lives next to the code. Read the in-scope file before editing:
 | `fastvideo/AGENTS.md` | Core package map, public API, registry-driven model dispatch |
 | `fastvideo/configs/AGENTS.md` | Arch + pipeline config dataclasses, `param_names_mapping` |
 | `fastvideo/models/AGENTS.md` | DiT / VAE / encoder / scheduler / loader layout (pre-commit excluded) |
-| `fastvideo/models/wan/AGENTS.md` | Wan family-local transformers, VAE, configs, and the SP sharding invariant |
 | `fastvideo/layers/AGENTS.md` | Tensor-parallel linear/attention layer rules for ports |
 | `fastvideo/attention/AGENTS.md` | Backend registry + env-var override |
 | `fastvideo/pipelines/AGENTS.md` | Stage ABC, `basic/<model>/`, `preprocess/`, presets |
-| `fastvideo/pipelines/basic/wan/AGENTS.md` | Wan sampling stages, first-frame conditioning, DMD/causal boundaries |
-| `fastvideo/pipelines/basic/magi_human/AGENTS.md` | MagiHuman umbrella repo, lazy-loaded components, packing invariants |
 | `fastvideo/training/AGENTS.md` | Legacy monolithic pipelines (frozen for existing models) |
 | `fastvideo/train/AGENTS.md` | New modular trainer (methods × models × callbacks, YAML) |
 | `fastvideo/tests/AGENTS.md` | Test taxonomy, conftest, pre-commit-excluded path |
 | `fastvideo/tests/ssim/AGENTS.md` | GPU SSIM regression authoring + reference video sync |
 | `scripts/checkpoint_conversion/AGENTS.md` | Adding a converter for a new HF/official checkpoint |
-| `apps/dreamverse/AGENTS.md` | DreamVerse app structure and conventions |
 
 ## Critical: Two Training Stacks Coexist
 

README.md

@@ -3,18 +3,12 @@
 </div>
 
 <p align="center">
-     | <a href="https://hao-ai-lab.github.io/FastVideo"><b>Documentation</b></a> | <a href="https://haoailab.com/FastVideo/cookbook/"><b>Cookbook</b></a> | <a href="https://hao-ai-lab.github.io/FastVideo/inference/inference_quick_start/"><b> Quick Start</b></a> | <a href="https://github.com/hao-ai-lab/FastVideo/discussions/982"  target="_blank"><b>Weekly Dev Meeting</b></a>  | 🟣💬 <a href="https://join.slack.com/t/fastvideo/shared_invite/zt-3f4lao1uq-u~Ipx6Lt4J27AlD2y~IdLQ" target="_blank"> <b>Slack</b> </a> |  🟣💬 <a href="https://github.com/hao-ai-lab/FastVideo/discussions/1097" target="_blank"> <b> WeChat </b> </a> |
+     | <a href="https://hao-ai-lab.github.io/FastVideo"><b>Documentation</b></a> | <a href="https://hao-ai-lab.github.io/FastVideo/inference/inference_quick_start/"><b> Quick Start</b></a> | <a href="https://github.com/hao-ai-lab/FastVideo/discussions/982"  target="_blank"><b>Weekly Dev Meeting</b></a>  | 🟣💬 <a href="https://join.slack.com/t/fastvideo/shared_invite/zt-3f4lao1uq-u~Ipx6Lt4J27AlD2y~IdLQ" target="_blank"> <b>Slack</b> </a> |  🟣💬 <a href="https://github.com/hao-ai-lab/FastVideo/discussions/1097" target="_blank"> <b> WeChat </b> </a> |
 </p>
 
 **FastVideo is a unified post-training and real-time inference framework for accelerated video generation.**
 
 ## NEWS
-- `2026/10/06`: FastH3 V2 now runs on a single consumer machine: NVIDIA RTX 5090, RTX 4090 and RTX PRO 6000 GPUs, DGX Spark and Apple Silicon. We also release [FastH3 Trim](https://huggingface.co/FastVideo/FastVideo-FastH3-Trim-8-Step-NVFP4), an experimental pruned model that is 4.2× smaller than base H3 and runs in as little as 8 GB of GPU memory. Get the [models](https://huggingface.co/collections/FastVideo/fastvideo-fasth3) and read the [Blog](https://haoailab.com/blogs/fasth3-rtx/).
-- `2026/10/06`: FastVideo now supports [Kandinsky 6](https://x.com/kandinskylab_ai/status/2107374635218055345) from Kandinsky Lab: text- and image-to-video with synchronized audio (base and 10-step distilled pi-Flow checkpoints) plus video super-resolution up to 4x. See the [Kandinsky 6 recipes](https://haoailab.com/FastVideo/cookbook/kandinsky6/).
-- `2026/09/15`: Release [FastH3 8-Step V2](https://huggingface.co/FastVideo/FastVideo-FastH3-8-Step-V2), an eight-forward data-free DMD2 checkpoint distilled from MiniMax-H3 with 80% Video Sparse Attention. Run it with `examples/inference/basic/basic_fasth3_8step.py` or the [FastH3 8-Step V2 recipe](https://haoailab.com/FastVideo/cookbook/minimax-h3/).
-- `2026/09/01`: FastH3 now runs locally on Apple Silicon through MLX and on NVIDIA DGX Spark through CUDA 13, including two-Spark inference. Follow the [FastH3 recipes](https://haoailab.com/FastVideo/cookbook/minimax-h3/) and read the [Blog](https://haoailab.com/blogs/fasth3-local/).
-- `2026/08/27`: [FastH3 Preview v1](https://haoailab.com/blogs/fasth3-preview/) is an open-weight 4-step sparse-distilled MiniMax-H3 model for synchronized video-and-audio generation, developed in collaboration with [Nuva Lab](https://nuvalab.ai/) and the [NVIDIA FastGen team](https://github.com/NVlabs/FastGen). Download the recommended [VSA / Data-Free weights](https://huggingface.co/FastVideo/FastVideo-FastH3-4-step-Preview-v1-VSA-DataFree), or see the [full FastH3 collection](https://huggingface.co/collections/FastVideo/fastvideo-fasth3).
-- `2026/08/19`: FastVideo now supports MLX on Apple Silicon with [FastMetal-QAD](https://huggingface.co/collections/FastVideo/fastmetal), a family of 1.3B, 5B, and 14B models optimized for Mac. Follow the [MLX install guide](https://hao-ai-lab.github.io/FastVideo/getting_started/installation/mlx/) and read the [Blog](https://haoailab.com/blogs/fastmetal/).
 - `2026/06/23`: Release FastWan-QAD: 5s of Video generated in 1.8s E2E. See the [FastWan-QAD models](https://huggingface.co/FastVideo/FastWan-QAD-FP8-1.3B), [Attn-QAT training guide](https://haoailab.com/FastVideo/training/attn_qat/), and [blog](https://haoailab.com/blogs/fastwan-qad/).
 - `2026/03/17`: Release demo: Into the Dreamverse: Vibe Directing in FastVideo, check out the [Blog](https://haoailab.com/blogs/dreamverse/).
 - `2026/03/13`: Release demo: Create a 5s 1080p Video in 4.5s with FastVideo on a Single GPU, check out the [Blog](https://haoailab.com/blogs/fastvideo_realtime_1080p/).
@@ -66,12 +60,7 @@ UV_TORCH_BACKEND=cu126 uv pip install fastvideo
 ```
 
 Use `UV_TORCH_BACKEND=cu130` on CUDA 13. Apple silicon users should follow the
-[MLX install guide](https://hao-ai-lab.github.io/FastVideo/getting_started/installation/mlx/).
-
-> **On an Apple Silicon Mac?** Install with `uv pip install -e '.[mlx]'` from
-> a clone, then pick a recipe in the
-> [cookbook](https://haoailab.com/FastVideo/cookbook/). See the
-> [MLX install guide](https://hao-ai-lab.github.io/FastVideo/getting_started/installation/mlx/).
+[MPS installation guide](https://hao-ai-lab.github.io/FastVideo/getting_started/installation/mps/).
 
 Please see our [docs](https://hao-ai-lab.github.io/FastVideo/getting_started/installation/) for more detailed installation instructions.
 
@@ -89,7 +78,7 @@ Install FastVideo (https://github.com/hao-ai-lab/FastVideo) into a fresh uv virt
    https://hao-ai-lab.github.io/FastVideo/getting_started/installation/):
      - NVIDIA GPU, x86_64                         -> docs/getting_started/installation/gpu.md
      - NVIDIA DGX Spark / GB10, aarch64, CUDA 13  -> docs/getting_started/installation/spark.md
-     - Apple Silicon, macOS                       -> docs/getting_started/installation/mlx.md
+     - Apple Silicon, macOS                       -> docs/getting_started/installation/mps.md
 3. Use uv for every step. If a command fails, debug it and tell me what you changed.
 4. Verify the result:
      python -c "import fastvideo, torch; print('cuda', torch.cuda.is_available())"
@@ -154,8 +143,6 @@ if __name__ == '__main__':
     main()
 ```
 
-`num_gpus=1` runs the worker in-process (weights load once, no extra Python process). On Colab/Kaggle-style machines with ~16GB host RAM, keep `num_gpus=1`; free-tier system memory does not grow with extra T4s, so `num_gpus>1` is likely to OOM.
-
 Run the script with:
 
 ```bash

apps/dreamverse/README.md

@@ -97,33 +97,13 @@ dreamverse-server --port 8009
 dreamverse-mock-server --port 8009
 ```
 
-### Run Dreamverse with FastH3
-
-Select the VSA data-free FastH3 Preview profile when you start the backend:
-
-```bash
-DREAMVERSE_MODEL_ID=fast-h3 dreamverse-server --port 8009
-```
-
-The `fast-h3` profile uses four visible GPUs by default. It loads the `MiniMaxAI/MiniMax-H3` base checkpoint and the
-`vsa-datafree/adapter_model.safetensors` adapter from
-`FastVideo/FastVideo-FastH3-4-step-Preview-v1-LoRA`. Each request generates a 124-frame, 768×1344 video with
-synchronized audio and five sigma-grid points. Dreamverse uses the last frame of each segment as first-frame
-conditioning for the following segment.
-
-Set `CUDA_VISIBLE_DEVICES` when you need to choose the four physical GPUs:
-
-```bash
-CUDA_VISIBLE_DEVICES=0,1,2,3 DREAMVERSE_MODEL_ID=fast-h3 dreamverse-server --port 8009
-```
-
 > **Expect a slow first boot.** With `torch.compile` and startup warmup enabled
 > (the default), the backend compiles the segment 1 and segment 2 inference
 > paths before it reports ready — this can take **tens of minutes on a cold
 > cache**, regardless of how you deploy (local, server, Docker, or Modal).
 > `/healthz` responds as soon as the process is up; `/readyz` stays `503` until
-> warmup finishes. To defer compilation until the first generated request while
-> testing, set `FASTVIDEO_ENABLE_STARTUP_WARMUP=0` before starting the backend.
+> warmup finishes. For a faster, uncompiled startup while testing, set
+> `FASTVIDEO_ENABLE_STARTUP_WARMUP=0` before starting the backend.
 
 ## Frontend Setup
 
@@ -158,40 +138,6 @@ dreamverse-server --host 0.0.0.0 --port 8009
 The Dreamverse backend defaults to `0.0.0.0:8009` and starts one GPU worker on
 the first visible GPU by default.
 
-### Cosmos Predict2.5 DFD continuation (experimental)
-
-Dreamverse can combine two converted Cosmos Predict2.5 2B packages: the
-distilled Text2World student creates an unconditioned first segment, then the
-Data-Forcing Distillation (DFD) Video2World student conditions each later
-segment on the prior terminal frame. Point the runtime at both local converted
-packages:
-
-```bash
-export DREAMVERSE_MODEL_ID=cosmos25-dfd
-export DREAMVERSE_MODEL_PATH=/path/to/Cosmos-Predict2.5-2B-Distilled-TrigFlow-FastVideo
-export DREAMVERSE_COSMOS25_DFD_MODEL_PATH=/path/to/Cosmos-Predict2.5-2B-DFD-FastVideo
-export ENABLE_TORCH_COMPILE=0
-dreamverse-server --host 0.0.0.0 --port 8009
-```
-
-The backend loads and warms both model roles before reporting ready. Both use
-BF16, Torch SDPA, 704x1280 output, 24 FPS, and four steps. Bootstrap segments
-contain 77 frames. DFD segments contain 81 decoded frames, but Dreamverse drops
-the repeated conditioning frame before streaming, leaving 80 new frames. An
-initial user image selects DFD immediately without treating that first frame as
-a cross-segment overlap.
-
-The profile uses a 30-minute session lease because sequential generation on
-GB10-class hardware can exceed Dreamverse's five-minute default while the GPU
-is still making progress. Deployments can override the lease with
-`FASTVIDEO_SESSION_TIMEOUT_SECONDS`.
-
-Cosmos does not produce audio, so the backend supplies duration-matched silent
-24 kHz audio for the existing browser streaming contract and trims 1,000 audio
-samples with each repeated DFD boundary frame. Runtime LoRA changes are not
-supported. Full segments take roughly 145 seconds on GB10, so this profile is a
-continuation-quality integration rather than a real-time configuration.
-
 ### Check Readiness
 
 In another shell, verify that the backend process is alive:
@@ -273,7 +219,6 @@ selection, and mock-server behavior:
 pytest apps/dreamverse/dreamverse/tests/test_config.py \
   apps/dreamverse/dreamverse/tests/test_entrypoints.py \
   apps/dreamverse/dreamverse/tests/test_gpu_pool.py \
-  apps/dreamverse/dreamverse/tests/test_minimax_h3_generation.py \
   apps/dreamverse/dreamverse/tests/test_mock_server.py -q
 ```
 

apps/dreamverse/arch.md

@@ -139,18 +139,7 @@ session.
 - startup warmup
 - user join/leave commands
 - `USER_STEP` execution for each segment
-- generation-command routing and stream-result delivery
-
-Model generation has a separate ownership boundary inside each GPU process:
-
-- `apps/dreamverse/dreamverse/generation_worker.py` selects the backend that the active model profile declares and owns
-  the backend lifecycle.
-- `apps/dreamverse/dreamverse/ltx2_generation.py` owns LTX-2 generator configuration, video and audio continuation, and
-  runtime LoRA application.
-- `apps/dreamverse/dreamverse/minimax_h3_generation.py` owns the VSA data-free FastH3 adapter, FastH3 generator and
-  request configuration, and last-frame continuation through MiniMax H3 first-frame conditioning.
-- `apps/dreamverse/dreamverse/generation_contracts.py` defines the decoded media and stream-trimming result that both
-  model backends return to `apps/dreamverse/dreamverse/gpu_pool.py`.
+- continuation state between segments
 
 `apps/dreamverse/dreamverse/prompt_enhancer.py` manages:
 

apps/dreamverse/dreamverse/assets.py

@@ -1,184 +0,0 @@
-"""Bounded, runtime-local media library shared by the HTTP and generation APIs."""
-
-from __future__ import annotations
-
-import json
-import math
-import os
-import re
-import shutil
-import subprocess
-import tempfile
-import threading
-import uuid
-from dataclasses import dataclass
-from pathlib import Path
-
-from PIL import Image, UnidentifiedImageError
-
-IMAGE_LIMIT = 15 * 1024 * 1024
-MEDIA_LIMIT = 100 * 1024 * 1024
-STORE_LIMIT = 2 * 1024 * 1024 * 1024
-ASSET_LIMIT = 100
-MAX_MEDIA_SECONDS = 30
-MIME_TYPES = {
-    "image/png": ("image", ".png"),
-    "image/jpeg": ("image", ".jpg"),
-    "image/webp": ("image", ".webp"),
-    "video/mp4": ("video", ".mp4"),
-    "video/quicktime": ("video", ".mov"),
-    "video/webm": ("video", ".webm"),
-    "audio/mpeg": ("audio", ".mp3"),
-    "audio/mp4": ("audio", ".m4a"),
-    "audio/x-m4a": ("audio", ".m4a"),
-    "audio/wav": ("audio", ".wav"),
-    "audio/x-wav": ("audio", ".wav"),
-    "audio/flac": ("audio", ".flac"),
-    "audio/x-flac": ("audio", ".flac"),
-    "audio/ogg": ("audio", ".ogg"),
-    "audio/webm": ("audio", ".webm"),
-}
-
-
-@dataclass(frozen=True)
-class StoredAsset:
-    asset_id: str
-    kind: str
-    path: str
-    name: str
-    mime_type: str
-    size: int
-
-    def public(self) -> dict:
-        return {
-            "asset_id": self.asset_id,
-            "kind": self.kind,
-            "name": self.name,
-            "mime_type": self.mime_type,
-            "size": self.size,
-            "url": f"/assets/{self.asset_id}",
-        }
-
-
-def validate_media(path: Path, mime_type: str) -> None:
-    """Inspect content, not filenames; refuse playlists and non-media uploads."""
-    kind = MIME_TYPES[mime_type][0]
-    if kind == "image":
-        try:
-            with Image.open(path) as img:
-                expected = {"image/png": "PNG", "image/jpeg": "JPEG", "image/webp": "WEBP"}[mime_type]
-                if img.format != expected:
-                    raise ValueError("The image content does not match its file type.")
-                if img.width * img.height > 16_777_216:
-                    raise ValueError("Images must contain at most 16 megapixels.")
-                if getattr(img, "is_animated", False):
-                    raise ValueError("Use a still image or upload the animation as a video.")
-                img.verify()
-        except (UnidentifiedImageError, OSError, Image.DecompressionBombError) as exc:
-            raise ValueError("The image could not be decoded. Use PNG, JPEG, or WebP.") from exc
-        return
-
-    probe = shutil.which(os.getenv("FASTVIDEO_FFPROBE_BIN", "ffprobe"))
-    if not probe:
-        raise ValueError("This runtime needs ffprobe installed to accept video and audio assets.")
-    try:
-        result = subprocess.run(
-            [
-                probe, "-v", "error", "-protocol_whitelist", "file,pipe", "-format_whitelist",
-                "mov,matroska,webm,mp3,wav,flac,ogg", "-show_format", "-show_streams", "-of", "json",
-                str(path)
-            ],
-            check=True,
-            capture_output=True,
-            timeout=15,
-        )
-        info = json.loads(result.stdout)
-        formats = set(info.get("format", {}).get("format_name", "").split(","))
-        if not formats.intersection({"mov", "mp4", "matroska", "webm", "mp3", "wav", "flac", "ogg"}):
-            raise ValueError("Upload a media file, not a playlist or external reference.")
-        streams = [stream for stream in info.get("streams", []) if stream.get("codec_type") == kind]
-        if not streams:
-            raise ValueError(f"The file contains no {kind} stream.")
-        for stream in info.get("streams", []):
-            if stream.get("codec_type") == "audio" and int(stream.get("channels", 0)) not in (1, 2):
-                raise ValueError("H3 references require mono or stereo audio, including video soundtracks.")
-        duration = float(info.get("format", {}).get("duration", "nan"))
-        if not math.isfinite(duration) or not 0 < duration <= MAX_MEDIA_SECONDS:
-            raise ValueError(f"Reference video and audio must be between 0 and {MAX_MEDIA_SECONDS} seconds long.")
-        for stream in streams:
-            if kind == "video" and int(stream.get("width", 0)) * int(stream.get("height", 0)) > 8_294_400:
-                raise ValueError("Reference videos must be 4K or smaller.")
-    except (subprocess.SubprocessError, json.JSONDecodeError, OSError) as exc:
-        raise ValueError("The media file could not be decoded. Check its format and try again.") from exc
-
-
-class AssetStore:
-    """Assets live until deletion or runtime exit; pinned generation inputs cannot be deleted."""
-
-    def __init__(self) -> None:
-        self._directory: tempfile.TemporaryDirectory | None = None
-        self._assets: dict[str, StoredAsset] = {}
-        self._pins: dict[str, int] = {}
-        self._lock = threading.RLock()
-
-    def staging_path(self, mime_type: str) -> Path:
-        with self._lock:
-            if mime_type not in MIME_TYPES:
-                raise ValueError("Unsupported media type. Use PNG/JPEG/WebP, MP4/WebM/MOV, or WAV/MP3/M4A/FLAC/OGG.")
-            if len(self._assets) >= ASSET_LIMIT or sum(item.size for item in self._assets.values()) >= STORE_LIMIT:
-                raise ValueError("The runtime asset library is full. Remove unused assets before uploading more.")
-            if self._directory is None:
-                self._directory = tempfile.TemporaryDirectory(prefix="dreamverse-assets-")
-            return Path(self._directory.name) / f"{uuid.uuid4().hex}{MIME_TYPES[mime_type][1]}"
-
-    def add(self, path: Path, name: str, mime_type: str) -> StoredAsset:
-        validate_media(path, mime_type)
-        size = path.stat().st_size
-        if size == 0 or size > (IMAGE_LIMIT if MIME_TYPES[mime_type][0] == "image" else MEDIA_LIMIT):
-            raise ValueError("The asset is empty or exceeds its upload size limit.")
-        with self._lock:
-            if len(self._assets) >= ASSET_LIMIT or size + sum(item.size
-                                                              for item in self._assets.values()) > STORE_LIMIT:
-                raise ValueError("The runtime asset library is full. Remove unused assets before uploading more.")
-            if self._directory is None or path.parent != Path(self._directory.name):
-                raise ValueError("The asset must be uploaded to this runtime.")
-            display_name = re.sub(r"[\x00-\x1f\x7f/\\]", "_", name).strip()[:200] or "Untitled asset"
-            asset = StoredAsset(path.stem, MIME_TYPES[mime_type][0], str(path), display_name, mime_type, size)
-            self._assets[asset.asset_id] = asset
-            return asset
-
-    def get(self, asset_id: str) -> StoredAsset:
-        with self._lock:
-            if not isinstance(asset_id, str) or not re.fullmatch(r"[a-f0-9]{32}", asset_id):
-                raise ValueError("Invalid asset ID. Upload or select an asset from the library.")
-            asset = self._assets.get(asset_id)
-            if asset is None or not Path(asset.path).is_file():
-                raise ValueError("An asset is no longer available. Upload it again and reselect it.")
-            return asset
-
-    def pin(self, asset_ids: list[str]) -> None:
-        with self._lock:
-            for asset_id in asset_ids:
-                self.get(asset_id)
-            for asset_id in asset_ids:
-                self._pins[asset_id] = self._pins.get(asset_id, 0) + 1
-
-    def release(self, asset_ids: list[str]) -> None:
-        with self._lock:
-            for asset_id in asset_ids:
-                count = self._pins.get(asset_id, 0)
-                if count > 1:
-                    self._pins[asset_id] = count - 1
-                else:
-                    self._pins.pop(asset_id, None)
-
-    def delete(self, asset_id: str) -> None:
-        with self._lock:
-            asset = self.get(asset_id)
-            if self._pins.get(asset_id, 0):
-                raise ValueError("This asset is in use by a generation session. End the session before deleting it.")
-            Path(asset.path).unlink(missing_ok=True)
-            del self._assets[asset_id]
-
-
-asset_store = AssetStore()

apps/dreamverse/dreamverse/benchmarks/benchmark_pipeline.py

@@ -1,6 +1,6 @@
 """Benchmark the LTX-2 generation pipeline driven by the dreamverse Python SDK path.
 
-Mirrors how ``apps/dreamverse/dreamverse/ltx2_generation.py`` constructs
+Mirrors how ``apps/dreamverse/dreamverse/video_generation.py`` constructs
 ``GeneratorConfig`` and calls ``VideoGenerator.generate()``, then
 captures per-stage timings via the ``FASTVIDEO_STAGE_LOGGING=1`` log
 hooks (same mechanism as ``FastVideo-internal/examples/inference/basic/
@@ -111,13 +111,7 @@ def _build_generator_config(model_path: str, enable_compile: bool, num_gpus: int
                                   mode="max-autotune-no-cudagraphs",
                                   dynamic=False),
             use_fsdp_inference=False,
-            # The bundled LTX2 model enables a refinement LoRA during the
-            # first request. NVFP4 otherwise purges the dense weights that
-            # FastVideo's LoRA merge path requires.
-            quantization=QuantizationConfig(
-                transformer_quant="NVFP4",
-                transformer_retain_original_weights=True,
-            ),
+            quantization=QuantizationConfig(transformer_quant="NVFP4"),
         ),
         pipeline=PipelineSelection(
             components=components,

apps/dreamverse/dreamverse/config.py

@@ -1,6 +1,5 @@
 import os
 from pathlib import Path
-from typing import cast
 
 _REPO_ROOT = Path(__file__).resolve().parents[1]
 _SERVER_ROOT = Path(__file__).resolve().parent
@@ -56,65 +55,16 @@ FRONTEND_STATIC_DIR_CANDIDATES = _resolve_frontend_static_dir_candidates()
 MODEL_REGISTRY = {
     "fast-ltx2": {
         "name": "FastLTX2",
-        "generation_backend": "ltx2",
-        "default_sp_size": 1,
         "model_path": "FastVideo/LTX2-Distilled-Diffusers",
         "config_model_path": "FastVideo/LTX2-Distilled-Diffusers",
         "lora_repo": "FastVideo/LTX2-OmniNFT-LoRA",
     },
     "fast-ltx23": {
         "name": "FastLTX23",
-        "generation_backend": "ltx2",
-        "default_sp_size": 1,
         "model_path": "FastVideo/LTX-2.3-Distilled-Diffusers",
         "config_model_path": "FastVideo/LTX-2.3-Distilled-Diffusers",
         "lora_repo": "FastVideo/LTX-2.3-OmniNFT-LoRA",
     },
-    "fast-h3": {
-        "name": "FastH3",
-        "generation_backend": "minimax_h3",
-        "default_sp_size": 4,
-        "model_path": "MiniMaxAI/MiniMax-H3",
-        "adapter_repo": "FastVideo/FastVideo-FastH3-4-step-Preview-v1-LoRA",
-        "adapter_filename": "vsa-datafree/adapter_model.safetensors",
-        "attention_backend": "VIDEO_SPARSE_ATTN_H3",
-        "height": 768,
-        "width": 1344,
-        "num_frames": 124,
-        "num_inference_steps": 5,
-        "seed": 1000,
-    },
-    "full-h3": {
-        "name": "MiniMax H3 (Full)",
-        "generation_backend": "minimax_h3",
-        "default_sp_size": 4,
-        "model_path": "MiniMaxAI/MiniMax-H3",
-        "attention_backend": "FLASH_ATTN",
-        "height": 768,
-        "width": 1344,
-        "num_frames": 124,
-        "num_inference_steps": 50,
-        "seed": 1000,
-        "full_checkpoint": True,
-    },
-    "cosmos25-dfd": {
-        "name": "Cosmos Predict2.5 DFD",
-        "generation_backend": "cosmos25_dfd",
-        "default_sp_size": 1,
-        "model_path": "FastVideo/Cosmos-Predict2.5-2B-Distilled-TrigFlow",
-        "continuation_model_path": "FastVideo/Cosmos-Predict2.5-2B-DFD",
-        "attention_backend": "TORCH_SDPA",
-        "height": 704,
-        "width": 1280,
-        "bootstrap_num_frames": 77,
-        "continuation_num_frames": 81,
-        "fps": 24,
-        "num_inference_steps": 4,
-        "seed": 42,
-        # Six sequential GB10 segments can exceed the legacy five-minute
-        # DreamVerse lease even though the GPU is making progress.
-        "session_timeout_seconds": 1800,
-    },
 }
 
 DEFAULT_MODEL_ID = "fast-ltx2"
@@ -126,6 +76,22 @@ if ACTIVE_MODEL_ID not in MODEL_REGISTRY:
 # Active model configuration
 MODEL_CONFIG = MODEL_REGISTRY[ACTIVE_MODEL_ID]
 
+# Generation limits
+SESSION_TIMEOUT_SECONDS = 300
+
+# Frame settings
+NUM_FRAMES = 121
+FRAME_HEIGHT = 1088
+FRAME_WIDTH = 1920
+NUM_INFERENCE_STEPS = 5
+JPEG_QUALITY = 100
+BATCH_SIZE = 3
+
+# Streaming mode:
+# - legacy_jpeg: send frame_batch JSON payloads with base64 JPEGs
+# - av_fmp4: send muxed fMP4 binary chunks over WebSocket
+STREAM_MODE = os.getenv("STREAM_MODE", "av_fmp4").strip().lower()
+
 
 def _env_int(name: str, default: int) -> int:
     value = os.getenv(name)
@@ -202,41 +168,10 @@ def _optional_env(*names: str) -> str | None:
     return None
 
 
-# Generation limits
-# Slower backends may own a longer default lease. A profile can set
-# ``session_timeout_seconds``; Full H3 loads and generates substantially longer
-# than the Preview adapter, which also covers a base/ref pipeline reload inside a
-# retained session. An explicit environment override remains available for
-# deployment policy: DREAMVERSE_SESSION_TIMEOUT_SECONDS, with
-# FASTVIDEO_SESSION_TIMEOUT_SECONDS accepted as an alias.
-# Values below 60 seconds are floored so a single segment cannot outlast the session.
-_DEFAULT_SESSION_TIMEOUT_SECONDS = cast(
-    int, MODEL_CONFIG.get("session_timeout_seconds", 7200 if ACTIVE_MODEL_ID == "full-h3" else 300))
-SESSION_TIMEOUT_SECONDS = max(
-    60,
-    _env_int(
-        "DREAMVERSE_SESSION_TIMEOUT_SECONDS",
-        _env_int("FASTVIDEO_SESSION_TIMEOUT_SECONDS", _DEFAULT_SESSION_TIMEOUT_SECONDS),
-    ),
-)
-
-# Frame settings
-NUM_FRAMES = 121
-FRAME_HEIGHT = 1088
-FRAME_WIDTH = 1920
-NUM_INFERENCE_STEPS = 5
-JPEG_QUALITY = 100
-BATCH_SIZE = 3
-
-# Streaming mode:
-# - legacy_jpeg: send frame_batch JSON payloads with base64 JPEGs
-# - av_fmp4: send muxed fMP4 binary chunks over WebSocket
-STREAM_MODE = os.getenv("STREAM_MODE", "av_fmp4").strip().lower()
-
 DEVTOOLS_ENABLED = _env_bool("FASTVIDEO_ENABLE_DEVTOOLS", False)
 PROMPT_SAFETY_ENABLED = _env_bool("FASTVIDEO_ENABLE_PROMPT_SAFETY", False)
 DREAMVERSE_MAX_AUTOTUNE = _env_bool("DREAMVERSE_MAX_AUTOTUNE", True)
-DREAMVERSE_SP_SIZE = max(1, _env_int("DREAMVERSE_SP_SIZE", cast(int, MODEL_CONFIG["default_sp_size"])))
+DREAMVERSE_SP_SIZE = max(1, _env_int("DREAMVERSE_SP_SIZE", 1))
 
 DREAMVERSE_MODEL_PATH = (os.getenv("DREAMVERSE_MODEL_PATH", "").strip() or None)
 if DREAMVERSE_MODEL_PATH:
@@ -246,13 +181,6 @@ if DREAMVERSE_MODEL_PATH:
         "config_model_path": DREAMVERSE_MODEL_PATH,
     }
 
-DREAMVERSE_COSMOS25_DFD_MODEL_PATH = (os.getenv("DREAMVERSE_COSMOS25_DFD_MODEL_PATH", "").strip() or None)
-if DREAMVERSE_COSMOS25_DFD_MODEL_PATH and MODEL_CONFIG.get("generation_backend") == "cosmos25_dfd":
-    MODEL_CONFIG = {
-        **MODEL_CONFIG,
-        "continuation_model_path": DREAMVERSE_COSMOS25_DFD_MODEL_PATH,
-    }
-
 AVAILABLE_LORAS = {
     "pixar": {
         "repo": "vrgamedevgirl84/LTX_2.3_Pixar_Toon_Style_LoRa",
@@ -285,7 +213,7 @@ def _resolve_lora_spec(spec: str) -> str | None:
     if not spec:
         return None
     if spec.lower() == "omninft":
-        return cast(str | None, MODEL_CONFIG.get("lora_repo"))
+        return MODEL_CONFIG.get("lora_repo")
     if spec.lower() in AVAILABLE_LORAS:
         return AVAILABLE_LORAS[spec.lower()]["repo"]
     return spec

apps/dreamverse/dreamverse/cosmos25_dfd_generation.py

@@ -1,252 +0,0 @@
-"""Cosmos Predict2.5 distilled bootstrap and DFD continuation for DreamVerse."""
-
-from __future__ import annotations
-
-import gc
-import os
-import time
-from typing import TYPE_CHECKING, Any
-
-import numpy as np
-import torch
-
-from dreamverse.generation_contracts import StepResult
-from dreamverse.generation_inputs import GenerationInputs
-
-if TYPE_CHECKING:
-    from PIL.Image import Image
-
-_SILENT_AUDIO_SAMPLE_RATE = 24_000
-
-
-def _required_config_str(model_config: dict, field_name: str) -> str:
-    value = model_config.get(field_name)
-    if not isinstance(value, str) or not value.strip():
-        raise ValueError(f"Cosmos Predict2.5 DFD model configuration requires `{field_name}`.")
-    return value.strip()
-
-
-class Cosmos25DFDGenerationBackend:
-    """Own complementary Cosmos T2W and one-frame-conditioned DFD generators."""
-
-    def __init__(self, gpu_id: int):
-        self.gpu_id = gpu_id
-        self.bootstrap_generator: Any | None = None
-        self.continuation_generator: Any | None = None
-        self.model_config: dict = {}
-        self.continuation_image: Image | None = None
-
-    def _gpu_mem(self) -> str:
-        allocated_gib = torch.cuda.memory_allocated() / 1024**3
-        reserved_gib = torch.cuda.memory_reserved() / 1024**3
-        return f"alloc={allocated_gib:.2f}GiB, reserved={reserved_gib:.2f}GiB"
-
-    @staticmethod
-    def _configure_environment(attention_backend: str) -> None:
-        os.environ["FASTVIDEO_ATTENTION_BACKEND"] = attention_backend
-        os.environ.pop("FASTVIDEO_INFERENCE_TORCH_COMPILE", None)
-
-    @staticmethod
-    def _load_generator(model_path: str):
-        from fastvideo import VideoGenerator
-
-        return VideoGenerator.from_pretrained(
-            model_path,
-            num_gpus=1,
-            use_fsdp_inference=False,
-            dit_cpu_offload=False,
-            vae_cpu_offload=False,
-            text_encoder_cpu_offload=True,
-            pin_cpu_memory=True,
-            enable_torch_compile=False,
-        )
-
-    def initialize(self, model_config: dict | None = None) -> None:
-        """Load both package roles so bootstrap and continuation are ready."""
-        if model_config is not None:
-            self.model_config = dict(model_config)
-        if not self.model_config:
-            raise ValueError("Cosmos Predict2.5 DFD initialization requires a model configuration.")
-
-        self.shutdown()
-        bootstrap_path = _required_config_str(self.model_config, "model_path")
-        continuation_path = _required_config_str(self.model_config, "continuation_model_path")
-        attention_backend = _required_config_str(self.model_config, "attention_backend")
-        self._configure_environment(attention_backend)
-
-        print(f"[GPU {self.gpu_id}] Loading Cosmos T2W bootstrap: {bootstrap_path}")
-        print(f"[GPU {self.gpu_id}] Before bootstrap load: {self._gpu_mem()}")
-        self.bootstrap_generator = self._load_generator(bootstrap_path)
-        print(f"[GPU {self.gpu_id}] Loading Cosmos DFD continuation: {continuation_path}")
-        self.continuation_generator = self._load_generator(continuation_path)
-        print(f"[GPU {self.gpu_id}] Cosmos T2W + DFD loaded: {self._gpu_mem()} (warmup pending)")
-
-    def shutdown(self) -> None:
-        """Release both FastVideo generators and the retained terminal frame."""
-        self.clear_conditioning()
-        for attr_name in ("bootstrap_generator", "continuation_generator"):
-            generator = getattr(self, attr_name)
-            if generator is not None:
-                try:
-                    generator.shutdown()
-                except Exception as exc:
-                    print(f"[GPU {self.gpu_id}] Cosmos generator shutdown warning: {exc}")
-                setattr(self, attr_name, None)
-        gc.collect()
-        if torch.cuda.is_available():
-            torch.cuda.empty_cache()
-
-    def clear_conditioning(self) -> None:
-        if self.continuation_image is not None:
-            self.continuation_image.close()
-            self.continuation_image = None
-
-    @staticmethod
-    def _load_rgb_image(image_path: str) -> Image:
-        from PIL import Image
-
-        with Image.open(image_path) as image:
-            return image.convert("RGB").copy()
-
-    def _select_conditioning_image(
-        self,
-        segment_idx: int,
-        image_path: str | None,
-        reset_conditioning: bool,
-    ) -> tuple[Image | None, bool]:
-        if reset_conditioning:
-            self.clear_conditioning()
-        if segment_idx > 1 and self.continuation_image is not None:
-            return self.continuation_image.copy(), True
-        if segment_idx > 1 and not reset_conditioning:
-            raise RuntimeError(f"Cosmos DFD segment {segment_idx} requires a retained continuation frame.")
-        if segment_idx == 1 and image_path:
-            return self._load_rgb_image(image_path), False
-        return None, False
-
-    def _sampling_param(self, *, conditioned: bool):
-        # ``num_cond_frames`` is not yet exposed by the typed SamplingConfig,
-        # so this backend uses the compatibility request until that field lands.
-        from fastvideo.api.sampling_param import SamplingParam
-
-        num_frames_key = "continuation_num_frames" if conditioned else "bootstrap_num_frames"
-        return SamplingParam(
-            negative_prompt="",
-            save_video=False,
-            return_frames=True,
-            height=int(self.model_config["height"]),
-            width=int(self.model_config["width"]),
-            num_frames=int(self.model_config[num_frames_key]),
-            fps=int(self.model_config["fps"]),
-            num_inference_steps=int(self.model_config["num_inference_steps"]),
-            guidance_scale=1.0,
-            seed=int(self.model_config["seed"]),
-            num_cond_frames=1 if conditioned else 0,
-        )
-
-    def _save_continuation_frame(self, frame: object) -> None:
-        from PIL import Image
-
-        self.clear_conditioning()
-        if isinstance(frame, Image.Image):
-            self.continuation_image = frame.convert("RGB").copy()
-            return
-        pixels = np.asarray(frame)
-        self.continuation_image = Image.fromarray(np.ascontiguousarray(pixels)).convert("RGB")
-
-    @staticmethod
-    def _silent_audio(frame_count: int, fps: int) -> torch.Tensor:
-        sample_count = max(1, int(round((frame_count / float(fps)) * _SILENT_AUDIO_SAMPLE_RATE)))
-        return torch.zeros(sample_count, dtype=torch.float32)
-
-    def generate_step(
-        self,
-        prompt: str,
-        segment_idx: int,
-        image_path: str | None,
-        reset_conditioning: bool,
-        generation_inputs: GenerationInputs | None = None,
-    ) -> StepResult:
-        """Generate a T2W start or DFD continuation and retain its last frame."""
-        if generation_inputs is not None and (generation_inputs.mode not in (None, "t2va") or generation_inputs.assets):
-            raise ValueError("Cosmos supports text generation only through the generation mode API.")
-        if self.bootstrap_generator is None or self.continuation_generator is None:
-            raise RuntimeError("Cosmos T2W + DFD generators are not initialized.")
-
-        conditioning_image, uses_continuation = self._select_conditioning_image(
-            segment_idx,
-            image_path,
-            reset_conditioning,
-        )
-        conditioned = conditioning_image is not None
-        generator = self.continuation_generator if conditioned else self.bootstrap_generator
-        sampling_param = self._sampling_param(conditioned=conditioned)
-        started = time.perf_counter()
-        try:
-            if conditioned:
-                sampling_param.pil_image = conditioning_image
-            result = generator.generate_video(prompt, sampling_param=sampling_param)
-        finally:
-            if conditioning_image is not None:
-                conditioning_image.close()
-        torch.cuda.synchronize()
-        generation_ms = (time.perf_counter() - started) * 1000.0
-
-        if not isinstance(result, dict):
-            raise RuntimeError("Cosmos generation did not return one result dictionary.")
-        frames = result.get("frames")
-        expected_frames = int(sampling_param.num_frames)
-        if not isinstance(frames, list) or len(frames) != expected_frames:
-            actual_frames = len(frames) if isinstance(frames, list) else None
-            raise RuntimeError(f"Cosmos generation returned {actual_frames} frames; expected {expected_frames}.")
-
-        save_started = time.perf_counter()
-        self._save_continuation_frame(frames[-1])
-        save_conditioning_ms = (time.perf_counter() - save_started) * 1000.0
-        fps = int(sampling_param.fps)
-        timings = {
-            "generation_ms": generation_ms,
-            "generation_time_ms": float(result.get("generation_time") or 0.0) * 1000.0,
-            "save_conditioning_ms": save_conditioning_ms,
-            "e2e_latency_ms": (time.perf_counter() - started) * 1000.0,
-        }
-        trim_frames = 1 if uses_continuation else 0
-        mode = "DFD continuation" if conditioned else "T2W bootstrap"
-        print(f"[GPU {self.gpu_id}] Cosmos {mode} segment {segment_idx}: "
-              f"{len(frames)} frames, gen={generation_ms:.0f}ms, "
-              f"save_conditioning={save_conditioning_ms:.0f}ms, "
-              f"e2e={timings['e2e_latency_ms']:.0f}ms")
-        return StepResult(
-            frames=frames,
-            audio=self._silent_audio(len(frames), fps),
-            audio_sample_rate=_SILENT_AUDIO_SAMPLE_RATE,
-            timings=timings,
-            head_trim_frames=trim_frames,
-            head_trim_audio_frames=trim_frames,
-        )
-
-    def warmup(self, prompt: str) -> dict[str, float]:
-        """Exercise both T2W bootstrap and retained-frame DFD request shapes."""
-        warmup_prompt = (prompt or "").strip()
-        if not warmup_prompt:
-            raise RuntimeError("Startup warmup prompt must be non-empty.")
-        print(f"[GPU {self.gpu_id}] Cosmos startup warmup starting "
-              "(synthetic segments: T2W bootstrap, DFD continuation)")
-        started = time.perf_counter()
-        bootstrap_result = self.generate_step(warmup_prompt, 1, None, True)
-        continuation_result = self.generate_step(warmup_prompt, 2, None, False)
-        total_ms = (time.perf_counter() - started) * 1000.0
-        self.clear_conditioning()
-        bootstrap_ms = float(bootstrap_result.timings.get("e2e_latency_ms", 0.0))
-        continuation_ms = float(continuation_result.timings.get("e2e_latency_ms", 0.0))
-        print(f"[GPU {self.gpu_id}] Cosmos startup warmup complete: "
-              f"bootstrap={bootstrap_ms:.0f}ms, continuation={continuation_ms:.0f}ms, total={total_ms:.0f}ms")
-        return {
-            "warmup_bootstrap_ms": bootstrap_ms,
-            "warmup_continuation_ms": continuation_ms,
-            "warmup_total_ms": total_ms,
-        }
-
-    def apply_lora_stack(self, stack: list[tuple[str, float]]) -> tuple[str | None, str | None]:
-        del stack
-        raise RuntimeError("Cosmos Predict2.5 DFD does not support DreamVerse runtime LoRA changes.")

apps/dreamverse/dreamverse/generation_contracts.py

@@ -1,49 +0,0 @@
-"""Shared contract between DreamVerse generation backends and GPU workers."""
-
-from __future__ import annotations
-
-from dataclasses import dataclass
-from typing import Any, Protocol
-
-from dreamverse.generation_inputs import GenerationInputs
-
-
-@dataclass
-class StepResult:
-    """Decoded media and stream-trimming metadata for one DreamVerse segment."""
-
-    frames: list
-    audio: Any
-    audio_sample_rate: int | None
-    timings: dict[str, float]
-    head_trim_frames: int
-    head_trim_audio_frames: int
-
-
-class GenerationBackend(Protocol):
-    """Model-owned generation operations used by one GPU worker process."""
-
-    def initialize(self, model_config: dict | None = None) -> None:
-        ...
-
-    def shutdown(self) -> None:
-        ...
-
-    def clear_conditioning(self) -> None:
-        ...
-
-    def generate_step(
-        self,
-        prompt: str,
-        segment_idx: int,
-        image_path: str | None,
-        reset_conditioning: bool,
-        generation_inputs: GenerationInputs | None = None,
-    ) -> StepResult:
-        ...
-
-    def warmup(self, prompt: str) -> dict[str, float]:
-        ...
-
-    def apply_lora_stack(self, stack: list[tuple[str, float]]) -> tuple[str | None, str | None]:
-        ...

apps/dreamverse/dreamverse/generation_inputs.py

@@ -1,102 +0,0 @@
-"""GPU-independent validation for generation modes and ordered asset handles."""
-
-from __future__ import annotations
-
-from dataclasses import dataclass
-
-from PIL import Image, UnidentifiedImageError
-
-from dreamverse.assets import asset_store
-
-GENERATION_MODES = ("t2va", "fl2va", "ref2va")
-
-
-@dataclass(frozen=True)
-class GenerationAsset:
-    asset_id: str
-    kind: str
-    path: str
-    role: str
-
-
-@dataclass(frozen=True)
-class GenerationInputs:
-    mode: str | None = None
-    assets: tuple[GenerationAsset, ...] = ()
-
-    @property
-    def first_frame_path(self) -> str | None:
-        return next((asset.path for asset in self.assets if asset.role == "first_frame"), None)
-
-    @property
-    def last_frame_path(self) -> str | None:
-        return next((asset.path for asset in self.assets if asset.role == "last_frame"), None)
-
-    @property
-    def references(self) -> tuple[GenerationAsset, ...]:
-        return tuple(asset for asset in self.assets if asset.role == "reference")
-
-
-def supported_generation_modes(model_id: str) -> tuple[str, ...]:
-    return GENERATION_MODES if model_id in ("full-h3", "mock") else ("t2va", )
-
-
-def resolve_generation_inputs(payload: dict, model_id: str) -> GenerationInputs:
-    mode = payload.get("generation_mode")
-    raw_assets = payload.get("conditioning_assets", [])
-    if mode is None and "generation_mode" not in payload:
-        if raw_assets:
-            raise ValueError("Select a generation mode before attaching conditioning assets.")
-        return GenerationInputs()
-    if not isinstance(mode, str) or mode not in GENERATION_MODES:
-        raise ValueError("Unknown generation mode. Choose T2VA, FL2VA, or Ref2VA.")
-    if mode not in supported_generation_modes(model_id):
-        raise ValueError(f"{mode.upper()} requires the Full H3 runtime. This runtime is running {model_id}.")
-    if payload.get("initial_image") is not None:
-        raise ValueError("Use asset IDs for generation modes; do not combine them with the legacy initial_image field.")
-    if not isinstance(raw_assets, list) or len(raw_assets) > 12:
-        raise ValueError("conditioning_assets must be an ordered list with at most 12 assets.")
-    if mode == "t2va" and raw_assets:
-        raise ValueError("T2VA accepts text only. Remove conditioning assets or choose another mode.")
-    assets: list[GenerationAsset] = []
-    for item in raw_assets:
-        if not isinstance(item, dict) or set(item) != {"asset_id", "role"}:
-            raise ValueError("Each conditioning asset must contain only asset_id and role.")
-        role = item["role"]
-        if role not in ("first_frame", "last_frame", "reference"):
-            raise ValueError("Asset role must be first_frame, last_frame, or reference.")
-        stored = asset_store.get(item["asset_id"])
-        assets.append(GenerationAsset(stored.asset_id, stored.kind, stored.path, role))
-    if mode == "fl2va":
-        if any(asset.kind != "image" or asset.role == "reference" for asset in assets):
-            raise ValueError("FL2VA accepts only first-frame and last-frame images.")
-        if sum(asset.role == "first_frame" for asset in assets) != 1:
-            raise ValueError("FL2VA requires exactly one first-frame image.")
-        if sum(asset.role == "last_frame" for asset in assets) > 1:
-            raise ValueError("FL2VA accepts at most one last-frame image.")
-    elif mode == "ref2va":
-        if not assets or any(asset.role != "reference" for asset in assets):
-            raise ValueError("Ref2VA requires an ordered list of reference assets, without keyframe roles.")
-        if not any(asset.kind in ("image", "video") for asset in assets):
-            raise ValueError("Ref2VA requires at least one image or video; audio alone is not supported.")
-        for kind, limit in (("image", 9), ("video", 3), ("audio", 3)):
-            if sum(asset.kind == kind for asset in assets) > limit:
-                raise ValueError(f"Ref2VA accepts at most {limit} {kind} references.")
-        for asset in assets:
-            if asset.kind == "image":
-                try:
-                    with Image.open(asset.path) as image:
-                        if image.width > 4 * image.height or image.height > 4 * image.width:
-                            raise ValueError(
-                                "Ref2VA image aspect ratios must be between 1:4 and 4:1. Crop this image first.")
-                except (UnidentifiedImageError, OSError, Image.DecompressionBombError) as exc:
-                    raise ValueError("A selected reference image could not be decoded. Upload it again.") from exc
-    return GenerationInputs(mode, tuple(assets))
-
-
-def pin_generation_inputs(inputs: GenerationInputs) -> None:
-    asset_store.pin([asset.asset_id for asset in inputs.assets])
-
-
-def release_generation_inputs(inputs: GenerationInputs) -> None:
-    asset_store.release([asset.asset_id for asset in inputs.assets])

apps/dreamverse/dreamverse/generation_worker.py

@@ -1,103 +0,0 @@
-"""Select and own one model-specific generation backend per GPU process."""
-
-from __future__ import annotations
-
-from dreamverse.config import MODEL_CONFIG
-from dreamverse.generation_contracts import GenerationBackend, StepResult
-from dreamverse.generation_inputs import GenerationInputs
-
-
-def _create_generation_backend(backend_name: str, gpu_id: int) -> GenerationBackend:
-    """Construct the backend that owns the selected model family's behavior."""
-    if backend_name == "ltx2":
-        from dreamverse.ltx2_generation import LTX2GenerationBackend
-
-        return LTX2GenerationBackend(gpu_id)
-    if backend_name == "minimax_h3":
-        from dreamverse.minimax_h3_generation import MiniMaxH3GenerationBackend
-
-        return MiniMaxH3GenerationBackend(gpu_id)
-    if backend_name == "cosmos25_dfd":
-        from dreamverse.cosmos25_dfd_generation import Cosmos25DFDGenerationBackend
-
-        return Cosmos25DFDGenerationBackend(gpu_id)
-    raise ValueError(f"Unsupported DreamVerse generation backend: {backend_name!r}")
-
-
-class VideoGenerationWorker:
-    """Delegate GPU lifecycle and generation calls to the active model backend."""
-
-    def __init__(self, gpu_id: int):
-        self.gpu_id = gpu_id
-        self.model_config: dict = dict(MODEL_CONFIG)
-        self.backend_name: str | None = None
-        self.backend: GenerationBackend | None = None
-
-    def initialize(self, model_config: dict | None = None) -> None:
-        """Load the requested model through its generation backend.
-
-        Model selection belongs here so the GPU process and streaming layers
-        use one stable media contract without importing model-specific code.
-        """
-        requested_model_config = dict(model_config) if model_config is not None else dict(self.model_config)
-        backend_name = requested_model_config.get("generation_backend")
-        if not isinstance(backend_name, str) or not backend_name:
-            raise ValueError("DreamVerse model configuration requires `generation_backend`.")
-
-        candidate_backend = self.backend
-        if candidate_backend is None or self.backend_name != backend_name:
-            if candidate_backend is not None:
-                candidate_backend.shutdown()
-            candidate_backend = _create_generation_backend(backend_name, self.gpu_id)
-
-        try:
-            candidate_backend.initialize(requested_model_config)
-        except Exception:
-            try:
-                candidate_backend.shutdown()
-            except Exception as shutdown_error:
-                print(f"[GPU {self.gpu_id}] Backend cleanup after initialization failure: {shutdown_error}")
-            self.backend = None
-            self.backend_name = None
-            raise
-
-        self.model_config = requested_model_config
-        self.backend = candidate_backend
-        self.backend_name = backend_name
-
-    def _require_backend(self) -> GenerationBackend:
-        """Return the initialized backend or fail before processing a command."""
-        if self.backend is None:
-            raise RuntimeError("Generation backend is not initialized.")
-        return self.backend
-
-    def shutdown(self) -> None:
-        """Release model resources owned by the selected backend."""
-        if self.backend is not None:
-            self.backend.shutdown()
-
-    def clear_conditioning(self) -> None:
-        self._require_backend().clear_conditioning()
-
-    def generate_step(
-        self,
-        prompt: str,
-        segment_idx: int,
-        image_path: str | None,
-        reset_conditioning: bool,
-        generation_inputs: GenerationInputs | None = None,
-    ) -> StepResult:
-        """Generate one segment through the selected model backend."""
-        return self._require_backend().generate_step(
-            prompt,
-            segment_idx,
-            image_path,
-            reset_conditioning,
-            generation_inputs=generation_inputs,
-        )
-
-    def warmup(self, prompt: str) -> dict[str, float]:
-        return self._require_backend().warmup(prompt)
-
-    def apply_lora_stack(self, stack: list[tuple[str, float]]) -> tuple[str | None, str | None]:
-        return self._require_backend().apply_lora_stack(stack)

apps/dreamverse/dreamverse/gpu_pool.py

@@ -12,7 +12,7 @@ from enum import Enum
 from multiprocessing import Process, Queue
 
 from dreamverse.config import (
-    ACTIVE_MODEL_ID,
+    DEFAULT_MODEL_ID,
     DREAMVERSE_SP_SIZE,
     MODEL_REGISTRY,
     STARTUP_WARMUP_ENABLED,
@@ -29,7 +29,6 @@ from dreamverse.av_streaming import (
     generate_stream_id,
     stream_fmp4,
 )
-from dreamverse.generation_inputs import GenerationInputs, pin_generation_inputs, release_generation_inputs
 from dreamverse.worker_ipc import (
     CommandPayload,
     InitAck,
@@ -55,7 +54,7 @@ from dreamverse.worker_ipc import (
 def _parse_requested_gpu_limit() -> int | None:
     raw_value = os.getenv("FASTVIDEO_GPU_COUNT", "").strip().lower()
     if not raw_value:
-        return DREAMVERSE_SP_SIZE
+        return 1
     if raw_value == "all":
         return None
     try:
@@ -165,12 +164,12 @@ def gpu_worker_process(
     os.environ["CUDA_VISIBLE_DEVICES"] = cuda_device
     os.environ["FASTVIDEO_ATTENTION_BACKEND"] = "FLASH_ATTN"
 
-    from dreamverse.generation_worker import VideoGenerationWorker
+    from dreamverse.video_generation import VideoGenerationWorker
 
     worker = VideoGenerationWorker(gpu_id)
 
     def event_loop(first_cmd: Command = None):
-        """Block on generation commands after the model is initialized."""
+        """Blocking event loop for LTX2; dispatches user commands."""
         print(f"[GPU {gpu_id}] Entering event loop")
 
         def handle_command(cmd: Command):
@@ -190,7 +189,6 @@ def gpu_worker_process(
                         segment_idx,
                         image_path=payload.image_path,
                         reset_conditioning=payload.reset_conditioning,
-                        generation_inputs=payload.generation_inputs,
                     )
                     head_trim_frames = step_result.head_trim_frames
                     head_trim_audio_frames = step_result.head_trim_audio_frames
@@ -434,11 +432,10 @@ class GPUSlot:
         self.connected_users: set[str] = set()
         self._pending_futures: dict[str, asyncio.Future] = {}
         self._stream_queues: dict[str, asyncio.Queue] = {}
-        self._step_asset_inputs: dict[str, GenerationInputs] = {}
         self._response_reader_task: asyncio.Task | None = None
         self._active: bool = False
         self._reader_lock: asyncio.Lock | None = None
-        self.current_model_id: str | None = ACTIVE_MODEL_ID
+        self.current_model_id: str = DEFAULT_MODEL_ID
         self.shared_stream_buffer = None
         self.shared_stream_buffer_size = SHARED_STREAM_BUFFER_BYTES
 
@@ -666,9 +663,6 @@ class GPUSlot:
                 if isinstance(event, (StepComplete, WarmupComplete)):
                     event.timings["ipc_get_done_ns"] = time.time_ns()
 
-                if isinstance(event, (StepComplete, WorkerError)) and event.user_id is not None:
-                    self._release_step_assets(event.user_id)
-
                 user_id = event.user_id
                 if user_id and user_id in self._pending_futures:
                     future = self._pending_futures.pop(user_id)
@@ -696,7 +690,7 @@ class GPUSlot:
     async def join_user(self, user_id: str, model_id: str = None) -> JoinAck:
         """Add a user to this GPU."""
         if model_id is None:
-            model_id = ACTIVE_MODEL_ID
+            model_id = DEFAULT_MODEL_ID
 
         # Reload model if a different one is requested
         if model_id != self.current_model_id and model_id in MODEL_REGISTRY:
@@ -711,23 +705,16 @@ class GPUSlot:
             self.connected_users.clear()
 
             model_config = MODEL_REGISTRY[model_id]
-            try:
-                reload_response = await self._send_command(Command(
-                    CommandType.RELOAD_MODEL,
-                    payload=ReloadModelPayload(model_config=model_config),
-                    user_id="__reload__"),
-                                                           timeout=600.0)
-            except Exception:
-                self.current_model_id = None
-                raise
+            reload_response = await self._send_command(Command(CommandType.RELOAD_MODEL,
+                                                               payload=ReloadModelPayload(model_config=model_config),
+                                                               user_id="__reload__"),
+                                                       timeout=600.0)
             match reload_response:
                 case ReloadAck():
                     pass
                 case WorkerError(message=msg):
-                    self.current_model_id = None
                     raise RuntimeError(f"Model reload failed: {msg}")
                 case _:
-                    self.current_model_id = None
                     raise RuntimeError(f"Unexpected reload response: "
                                        f"{type(reload_response).__name__}")
 
@@ -759,7 +746,6 @@ class GPUSlot:
         segment_idx: int = 1,
         image_path: str | None = None,
         reset_conditioning: bool = False,
-        generation_inputs: GenerationInputs | None = None,
     ) -> dict[str, float]:
         """Execute a generation step for a specific user.
 
@@ -773,19 +759,9 @@ class GPUSlot:
             segment_idx=segment_idx,
             image_path=image_path,
             reset_conditioning=bool(reset_conditioning),
-            generation_inputs=generation_inputs,
         )
-        if generation_inputs is not None:
-            if user_id in self._step_asset_inputs:
-                raise RuntimeError("The previous generation is still using this project's assets.")
-            pin_generation_inputs(generation_inputs)
-            self._step_asset_inputs[user_id] = generation_inputs
-        # Pins intentionally survive a waiter timeout/cancellation: the GPU
-        # command keeps running. The response reader releases them when the
-        # worker actually completes (even if that response is now unmatched).
         response = await self._send_command_tagged(Command(CommandType.USER_STEP, payload=payload, user_id=user_id),
                                                    timeout=1800.0)
-        self._release_step_assets(user_id)
         match response:
             case StepComplete(timings=timings):
                 return timings
@@ -795,11 +771,6 @@ class GPUSlot:
                 raise RuntimeError(f"Unexpected step response for {user_id[:8]}: "
                                    f"{type(response).__name__}")
 
-    def _release_step_assets(self, user_id: str) -> None:
-        inputs = self._step_asset_inputs.pop(user_id, None)
-        if inputs is not None:
-            release_generation_inputs(inputs)
-
     async def apply_lora_stack(
         self,
         stack: list[tuple[str, float]],
@@ -822,9 +793,7 @@ class GPUSlot:
     async def leave_user(self, user_id: str) -> None:
         """Remove a user from this GPU."""
         try:
-            response = await self._send_command_tagged(Command(CommandType.USER_LEAVE, user_id=user_id), timeout=30.0)
-            if isinstance(response, LeaveAck):
-                self._release_step_assets(user_id)
+            await self._send_command_tagged(Command(CommandType.USER_LEAVE, user_id=user_id), timeout=30.0)
         except Exception as e:
             print(f"[GPU {self.gpu_id}] Leave user error: {e}")
         finally:
@@ -861,10 +830,6 @@ class GPUSlot:
                 except Exception:
                     pass
 
-        if self.process is None or not self.process.is_alive():
-            for user_id in list(self._step_asset_inputs):
-                self._release_step_assets(user_id)
-
         for q in (self.command_queue, self.response_queue):
             if q is not None:
                 try:

apps/dreamverse/dreamverse/main.py

@@ -15,7 +15,6 @@ from dreamverse.gpu_pool import GPUPool, get_available_gpus
 from dreamverse.session_logger import SessionEventLogger
 
 from dreamverse.config import (
-    ACTIVE_MODEL_ID,
     AVAILABLE_LORAS,
     DEVTOOLS_ENABLED,
     FRONTEND_STATIC_DIR_CANDIDATES,
@@ -35,8 +34,6 @@ from dreamverse.routes.presets import (
     curated_presets_router,
 )
 from dreamverse.session.controller import SessionController
-from dreamverse.generation_inputs import supported_generation_modes
-from dreamverse.routes.assets import router as asset_router
 
 
 class _HeartbeatAccessLogFilter(logging.Filter):
@@ -95,16 +92,10 @@ app.add_middleware(
 app.include_router(build_health_router(lambda: runtime.gpu_pool))
 app.include_router(internal_monitor_router)
 app.include_router(prompt_config_router)
-app.include_router(asset_router)
 if DEVTOOLS_ENABLED:
     app.include_router(curated_presets_router)
 
 
-@app.get("/generation-capabilities")
-async def generation_capabilities() -> dict:
-    return {"model_id": ACTIVE_MODEL_ID, "modes": supported_generation_modes(ACTIVE_MODEL_ID), "mock": False}
-
-
 @app.websocket("/ws")
 async def websocket_endpoint(websocket: WebSocket):
     controller = SessionController(

apps/dreamverse/dreamverse/minimax_h3_generation.py

@@ -1,363 +0,0 @@
-"""Full/Preview H3 lifecycle, conditioning and per-project pipeline selection."""
-
-from __future__ import annotations
-
-import gc
-import os
-import time
-from typing import TYPE_CHECKING, Any
-
-import numpy as np
-import torch
-
-from dreamverse.config import DREAMVERSE_SP_SIZE
-from dreamverse.generation_contracts import StepResult
-from dreamverse.generation_inputs import GenerationInputs
-
-if TYPE_CHECKING:
-    from PIL.Image import Image
-
-
-def _required_config_str(model_config: dict, field_name: str) -> str:
-    """Read one required non-empty string from a DreamVerse model profile."""
-    value = model_config.get(field_name)
-    if not isinstance(value, str) or not value.strip():
-        raise ValueError(f"FastH3 model configuration requires `{field_name}`.")
-    return value.strip()
-
-
-class MiniMaxH3GenerationBackend:
-    """Own one H3 pipeline at a time and retain base-pipeline continuation."""
-
-    def __init__(self, gpu_id: int):
-        self.gpu_id = gpu_id
-        self.generator: Any | None = None
-        self.model_config: dict = {}
-        self.continuation_image: Image | None = None
-        self.pipeline_mode = "base"
-
-    def _gpu_mem(self) -> str:
-        allocated_gib = torch.cuda.memory_allocated() / 1024**3
-        reserved_gib = torch.cuda.memory_reserved() / 1024**3
-        return f"alloc={allocated_gib:.2f}GiB, reserved={reserved_gib:.2f}GiB"
-
-    @staticmethod
-    def _configure_environment(attention_backend: str) -> None:
-        """Apply the fixed boot-time switches from the FastH3 reference recipe."""
-        os.environ.update({
-            "FASTVIDEO_ATTENTION_BACKEND": attention_backend,
-            "FASTVIDEO_FA4": "1",
-            "FASTVIDEO_MINIMAX_H3_FUSIONS": "all",
-            "FASTVIDEO_VSA_SM100A": "0",
-        })
-        os.environ.pop("FASTVIDEO_INFERENCE_TORCH_COMPILE", None)
-
-    def initialize(self, model_config: dict | None = None) -> None:
-        """Load the profile's base pipeline; Ref2VA is loaded on first use."""
-        if model_config is not None:
-            self.model_config = dict(model_config)
-        if not self.model_config:
-            raise ValueError("FastH3 initialization requires a model configuration.")
-        self._load_pipeline("base")
-
-    def _load_pipeline(self, pipeline_mode: str) -> None:
-        """Unload the old executor before loading a base or reference transformer.
-
-        GPU worker commands are serialized, so a project boundary never swaps
-        weights while another request is using them. Keeping one executor also
-        avoids simultaneously retaining two large H3 transformers in VRAM. A
-        failed load leaves no executor behind so the next step retries it.
-        """
-        full_checkpoint = bool(self.model_config.get("full_checkpoint", False))
-        if pipeline_mode == "ref2va" and not full_checkpoint:
-            raise ValueError("Ref2VA requires the full-h3 model profile.")
-        if self.generator is not None:
-            previous_generator = self.generator
-            self.generator = None
-            previous_generator.shutdown()
-            del previous_generator
-            gc.collect()
-            torch.cuda.empty_cache()
-
-        self.clear_conditioning()
-        model_path = _required_config_str(self.model_config, "model_path")
-        attention_backend = _required_config_str(self.model_config, "attention_backend")
-        self._configure_environment(attention_backend)
-
-        from fastvideo import VideoGenerator
-        from fastvideo.api import (
-            CompileConfig,
-            ComponentConfig,
-            EngineConfig,
-            GeneratorConfig,
-            OffloadConfig,
-            ParallelismConfig,
-            PipelineSelection,
-        )
-
-        components = ComponentConfig()
-        if not full_checkpoint:
-            from huggingface_hub import hf_hub_download
-
-            adapter_repo = _required_config_str(self.model_config, "adapter_repo")
-            adapter_filename = _required_config_str(self.model_config, "adapter_filename")
-            components.lora_path = hf_hub_download(repo_id=adapter_repo, filename=adapter_filename)
-            components.lora_strength = 1.0
-            print(f"[GPU {self.gpu_id}] FastH3 adapter: {adapter_repo}/{adapter_filename}")
-        if pipeline_mode == "ref2va":
-            components.override_pipeline_cls_name = "MiniMaxH3Ref2VAModularPipeline"
-        experimental = {
-            "attention_backend": attention_backend,
-            "inference_torch_compile": not full_checkpoint and attention_backend == "FLASH_ATTN",
-            "vae_parallel_decode": True,
-            "vae_parallel_decode_strategy": "gather",
-        }
-        if attention_backend == "VIDEO_SPARSE_ATTN_H3":
-            experimental.update({
-                "VSA_sparsity": 0.9,
-                "VSA_tile_size": 64,
-            })
-        generator_config = GeneratorConfig(
-            model_path=model_path,
-            pipeline=PipelineSelection(
-                workload_type="i2v" if pipeline_mode == "ref2va" else None,
-                components=components,
-                experimental=experimental,
-            ),
-            engine=EngineConfig(
-                num_gpus=DREAMVERSE_SP_SIZE,
-                parallelism=ParallelismConfig(tp_size=1, sp_size=DREAMVERSE_SP_SIZE),
-                offload=OffloadConfig(
-                    dit=False,
-                    dit_layerwise=False,
-                    text_encoder=True,
-                    image_encoder=True,
-                    vae=True,
-                    pin_cpu_memory=not full_checkpoint,
-                ),
-                compile=CompileConfig(enabled=False, vae_enabled=True),
-                use_fsdp_inference=full_checkpoint and DREAMVERSE_SP_SIZE > 1,
-            ),
-        )
-
-        print(f"[GPU {self.gpu_id}] Loading H3 model: {model_path} ({pipeline_mode})")
-        print(f"[GPU {self.gpu_id}] Before model load: {self._gpu_mem()}")
-        try:
-            self.generator = VideoGenerator.from_config(generator_config)
-        except Exception:
-            # The old executor is already gone; leaving no executor behind lets
-            # the next step retry this load instead of stranding the GPU slot.
-            self.generator = None
-            raise
-        self.pipeline_mode = pipeline_mode
-        print(f"[GPU {self.gpu_id}] FastH3 loaded: {self._gpu_mem()} (warmup pending)")
-
-    def shutdown(self) -> None:
-        """Release the FastVideo generator and cached continuation image."""
-        self.clear_conditioning()
-        if self.generator is not None:
-            self.generator.shutdown()
-            self.generator = None
-
-    def clear_conditioning(self) -> None:
-        """Release the first-frame image retained for the next segment."""
-        if self.continuation_image is not None:
-            self.continuation_image.close()
-            self.continuation_image = None
-
-    @staticmethod
-    def _load_rgb_image(image_path: str) -> Image:
-        """Load an image into an independent RGB buffer with no open file handle."""
-        from PIL import Image
-
-        with Image.open(image_path) as image:
-            return image.convert("RGB").copy()
-
-    def _select_conditioning_image(
-        self,
-        segment_idx: int,
-        image_path: str | None,
-        reset_conditioning: bool,
-    ) -> tuple[Image | None, bool]:
-        """Select the initial upload or retained last frame for one segment."""
-        if reset_conditioning:
-            self.clear_conditioning()
-        if segment_idx > 1 and self.continuation_image is not None:
-            return self.continuation_image.copy(), True
-        if segment_idx > 1 and not reset_conditioning:
-            raise RuntimeError(f"FastH3 segment {segment_idx} requires a retained continuation frame.")
-        if segment_idx == 1 and image_path:
-            return self._load_rgb_image(image_path), False
-        return None, False
-
-    def _build_request(
-        self,
-        prompt: str,
-        conditioning_image: Image | None,
-        last_image: Image | None = None,
-        generation_inputs: GenerationInputs | None = None,
-    ):
-        """Build the typed FastVideo request owned by the FastH3 profile."""
-        from fastvideo.api import GenerationRequest, InputConfig, OutputConfig, SamplingConfig
-
-        references = None
-        if generation_inputs is not None and generation_inputs.mode == "ref2va":
-            from fastvideo.api import MiniMaxH3Reference
-
-            references = [
-                MiniMaxH3Reference(source=str(asset.path), media_type=asset.kind)
-                for asset in generation_inputs.references
-            ]
-        return GenerationRequest(
-            prompt=prompt,
-            negative_prompt="",
-            inputs=InputConfig(pil_image=conditioning_image, last_image=last_image, references=references),
-            sampling=SamplingConfig(
-                height=int(self.model_config["height"]),
-                width=int(self.model_config["width"]),
-                num_frames=int(self.model_config["num_frames"]),
-                fps=24,
-                num_inference_steps=int(self.model_config["num_inference_steps"]),
-                guidance_scale=1.0,
-                batch_cfg=False,
-                seed=int(self.model_config["seed"]),
-            ),
-            output=OutputConfig(save_video=False, return_frames=True),
-        )
-
-    def _save_continuation_frame(self, frames: list) -> None:
-        """Retain the last decoded frame as first-frame conditioning."""
-        from PIL import Image
-
-        self.clear_conditioning()
-        self.continuation_image = Image.fromarray(np.ascontiguousarray(frames[-1])).convert("RGB")
-
-    def generate_step(
-        self,
-        prompt: str,
-        segment_idx: int,
-        image_path: str | None,
-        reset_conditioning: bool,
-        generation_inputs: GenerationInputs | None = None,
-    ) -> StepResult:
-        """Generate one synchronized FastH3 segment and retain its last frame.
-
-        Later segments use MiniMax H3's first-frame-to-video path. The first
-        conditioned frame and its matching audio duration are trimmed before
-        streaming so adjacent segments do not duplicate media.
-        """
-        mode = generation_inputs.mode if generation_inputs is not None else None
-        if mode not in (None, "t2va", "fl2va", "ref2va"):
-            raise ValueError(f"Unsupported H3 generation mode: {mode!r}.")
-        if mode in ("fl2va", "ref2va") and not self.model_config.get("full_checkpoint", False):
-            raise ValueError(f"{mode.upper()} requires the full-h3 model profile.")
-        pipeline_mode = "ref2va" if mode == "ref2va" else "base"
-        if self.generator is None or self.pipeline_mode != pipeline_mode:
-            # A failed switch leaves no executor behind; reload here so the
-            # slot recovers on the next step instead of staying broken.
-            if segment_idx > 1 and not reset_conditioning:
-                raise ValueError("Generation mode cannot change in the middle of a project.")
-            self._load_pipeline(pipeline_mode)
-
-        conditioning_image = None
-        last_image = None
-        uses_continuation = False
-        if mode == "ref2va":
-            # The reference pipeline rejects first/last-frame inputs. Preserve
-            # all original references for every clip and do not trim overlap.
-            self.clear_conditioning()
-        else:
-            if mode == "fl2va" and generation_inputs is not None:
-                image_path = generation_inputs.first_frame_path
-            conditioning_image, uses_continuation = self._select_conditioning_image(
-                segment_idx,
-                image_path,
-                reset_conditioning,
-            )
-        started = time.perf_counter()
-        try:
-            if (mode == "fl2va" and segment_idx == 1 and generation_inputs is not None
-                    and generation_inputs.last_frame_path):
-                last_image = self._load_rgb_image(generation_inputs.last_frame_path)
-            request = self._build_request(prompt, conditioning_image, last_image, generation_inputs)
-            result = self.generator.generate(request)
-        finally:
-            if conditioning_image is not None:
-                conditioning_image.close()
-            if last_image is not None:
-                last_image.close()
-        torch.cuda.synchronize()
-        generation_ms = (time.perf_counter() - started) * 1000.0
-
-        if isinstance(result, list):
-            raise RuntimeError("FastH3 returned multiple results for one DreamVerse segment.")
-        frames = result.frames
-        if not isinstance(frames, list) or not frames:
-            raise RuntimeError("FastH3 generation did not return decoded frames.")
-        audio = result.audio
-        audio_sample_rate = result.audio_sample_rate
-        if audio is not None and audio_sample_rate is None:
-            raise RuntimeError("FastH3 returned audio without an audio sample rate.")
-
-        save_started = time.perf_counter()
-        if mode != "ref2va":
-            self._save_continuation_frame(frames)
-        save_conditioning_ms = (time.perf_counter() - save_started) * 1000.0
-        timings = {
-            "generation_ms": generation_ms,
-            "generation_time_ms": float(result.generation_time or 0.0) * 1000.0,
-            "save_conditioning_ms": save_conditioning_ms,
-            "e2e_latency_ms": (time.perf_counter() - started) * 1000.0,
-        }
-        trim_frames = 1 if uses_continuation else 0
-        print(f"[GPU {self.gpu_id}] FastH3 segment {segment_idx}: "
-              f"{len(frames)} frames, gen={generation_ms:.0f}ms, "
-              f"save_conditioning={save_conditioning_ms:.0f}ms, "
-              f"e2e={timings['e2e_latency_ms']:.0f}ms")
-        return StepResult(
-            frames=frames,
-            audio=audio,
-            audio_sample_rate=audio_sample_rate,
-            timings=timings,
-            head_trim_frames=trim_frames,
-            head_trim_audio_frames=trim_frames,
-        )
-
-    def warmup(self, prompt: str) -> dict[str, float]:
-        """Compile the FastH3 text and first-frame paths before readiness."""
-        warmup_prompt = (prompt or "").strip()
-        if not warmup_prompt:
-            raise RuntimeError("Startup warmup prompt must be non-empty.")
-        print(f"[GPU {self.gpu_id}] FastH3 startup warmup starting "
-              "(synthetic segments: text-to-video, first-frame-to-video)")
-        started = time.perf_counter()
-        text_result = self.generate_step(
-            warmup_prompt,
-            segment_idx=1,
-            image_path=None,
-            reset_conditioning=True,
-        )
-        first_frame_result = self.generate_step(
-            warmup_prompt,
-            segment_idx=2,
-            image_path=None,
-            reset_conditioning=False,
-        )
-        total_ms = (time.perf_counter() - started) * 1000.0
-        self.clear_conditioning()
-        text_ms = float(text_result.timings.get("e2e_latency_ms", 0.0))
-        first_frame_ms = float(first_frame_result.timings.get("e2e_latency_ms", 0.0))
-        print(f"[GPU {self.gpu_id}] FastH3 startup warmup complete: "
-              f"text_to_video={text_ms:.0f}ms, "
-              f"first_frame_to_video={first_frame_ms:.0f}ms, "
-              f"total={total_ms:.0f}ms")
-        return {
-            "warmup_text_to_video_ms": text_ms,
-            "warmup_first_frame_to_video_ms": first_frame_ms,
-            "warmup_total_ms": total_ms,
-        }
-
-    def apply_lora_stack(self, stack: list[tuple[str, float]]) -> tuple[str | None, str | None]:
-        """Reject runtime LoRA mutation because FastH3 uses one startup adapter."""
-        del stack
-        raise RuntimeError("FastH3 uses its fixed startup adapter and does not support runtime LoRA changes.")

apps/dreamverse/dreamverse/mock_server.py

@@ -32,14 +32,6 @@ from fastapi.staticfiles import StaticFiles
 from dreamverse._deps import require_dreamverse_runtime_deps
 from dreamverse.config import FRONTEND_STATIC_DIR_CANDIDATES, GENERATION_SEGMENT_CAP
 from dreamverse.session_init_image import cleanup_session_init_image, persist_session_init_image
-from dreamverse.generation_inputs import (
-    GenerationInputs,
-    pin_generation_inputs,
-    release_generation_inputs,
-    resolve_generation_inputs,
-    supported_generation_modes,
-)
-from dreamverse.routes.assets import router as asset_router
 
 LATENCY_MS = 200
 SESSION_TIMEOUT_SECONDS = 300
@@ -178,12 +170,6 @@ app.add_middleware(
     allow_methods=["*"],
     allow_headers=["*"],
 )
-app.include_router(asset_router)
-
-
-@app.get("/generation-capabilities")
-async def generation_capabilities():
-    return {"model_id": "mock", "modes": supported_generation_modes("mock"), "mock": True}
 
 
 @app.get("/healthz")
@@ -304,7 +290,6 @@ async def websocket_endpoint(websocket: WebSocket):
     send_lock = asyncio.Lock()
     stop_event = asyncio.Event()
     session_init_image = None
-    generation_inputs = GenerationInputs()
 
     async def ws_send_json(payload: dict) -> None:
         async with send_lock:
@@ -362,13 +347,10 @@ async def websocket_endpoint(websocket: WebSocket):
         generation_paused = bool(initial_rollout_prompt and not single_clip_mode and len(curated_prompts) == 0)
 
         try:
-            generation_inputs = resolve_generation_inputs(init_data, "mock")
-            pin_generation_inputs(generation_inputs)
             session_init_image = persist_session_init_image(init_data.get("initial_image"))
         except ValueError as exc:
             await ws_send_json({
                 "type": "error",
-                "error_code": "invalid_generation_input",
                 "message": str(exc),
             })
             await websocket.close(code=1003, reason="Invalid initial image")
@@ -380,8 +362,6 @@ async def websocket_endpoint(websocket: WebSocket):
             "type": "gpu_assigned",
             "gpu_id": 0,
             "session_timeout": SESSION_TIMEOUT_SECONDS,
-            "generation_mode": generation_inputs.mode,
-            "mock": True,
         })
 
         raw_prompt_queue: asyncio.Queue[PromptSubmission] = asyncio.Queue()
@@ -506,7 +486,6 @@ async def websocket_endpoint(websocket: WebSocket):
                 })
 
         async def apply_project_init_payload(payload: dict[str, object], ) -> bool:
-            nonlocal generation_inputs
             nonlocal preset_id
             nonlocal preset_label
             nonlocal initial_rollout_prompt
@@ -540,19 +519,10 @@ async def websocket_endpoint(websocket: WebSocket):
             ]
 
             try:
-                next_inputs = resolve_generation_inputs(payload, "mock")
-                pin_generation_inputs(next_inputs)
-                try:
-                    replace_session_image(payload.get("initial_image"))
-                except ValueError:
-                    release_generation_inputs(next_inputs)
-                    raise
-                release_generation_inputs(generation_inputs)
-                generation_inputs = next_inputs
+                replace_session_image(payload.get("initial_image"))
             except ValueError as exc:
                 await ws_send_json({
                     "type": "error",
-                    "error_code": "invalid_generation_input",
                     "message": str(exc),
                 })
                 return False
@@ -598,7 +568,6 @@ async def websocket_endpoint(websocket: WebSocket):
             return drained
 
         async def enter_project_idle() -> None:
-            nonlocal generation_inputs
             nonlocal seed_prompt_memory
             nonlocal curated_prompts
             nonlocal curated_idx
@@ -618,8 +587,6 @@ async def websocket_endpoint(websocket: WebSocket):
 
             dropped_raw = drain_queue_nowait(raw_prompt_queue)
             dropped_ready = drain_queue_nowait(ready_prompt_queue)
-            release_generation_inputs(generation_inputs)
-            generation_inputs = GenerationInputs()
             seed_prompt_memory = []
             curated_prompts = []
             curated_idx = 0
@@ -800,16 +767,10 @@ async def websocket_endpoint(websocket: WebSocket):
                         continue
 
                     try:
-                        if generation_inputs.mode is not None and data.get("initial_image") is not None:
-                            raise ValueError("Choose conditioning assets when starting a project; legacy initial_image "
-                                             "cannot replace generation mode inputs.")
-                        if "generation_mode" in data or "conditioning_assets" in data:
-                            raise ValueError("simple_generate cannot change the mode; use project_init_v1.")
                         replace_session_image(data.get("initial_image"))
                     except ValueError as exc:
                         await ws_send_json({
                             "type": "error",
-                            "error_code": "invalid_generation_input",
                             "message": str(exc),
                         })
                         continue
@@ -1221,7 +1182,6 @@ async def websocket_endpoint(websocket: WebSocket):
     finally:
         stop_event.set()
         cleanup_session_init_image(session_init_image)
-        release_generation_inputs(generation_inputs)
 
 
 for static_dir in FRONTEND_STATIC_DIR_CANDIDATES:

apps/dreamverse/dreamverse/routes/assets.py

@@ -1,72 +0,0 @@
-"""Raw, bounded media uploads keep large binary data out of websocket messages."""
-
-from __future__ import annotations
-
-import asyncio
-from urllib.parse import unquote
-
-from fastapi import APIRouter, HTTPException, Request, Response
-from fastapi.responses import FileResponse
-from starlette.concurrency import run_in_threadpool
-
-from dreamverse.assets import IMAGE_LIMIT, MEDIA_LIMIT, MIME_TYPES, asset_store
-
-router = APIRouter()
-_upload_lock = asyncio.Lock()
-
-
-@router.post("/assets", status_code=201)
-async def upload_asset(request: Request) -> dict:
-    mime_type = request.headers.get("content-type", "").split(";", 1)[0].lower()
-    if mime_type not in MIME_TYPES:
-        raise HTTPException(415, "Unsupported asset type. Select a supported image, video, or audio file.")
-    limit = IMAGE_LIMIT if MIME_TYPES[mime_type][0] == "image" else MEDIA_LIMIT
-    try:
-        if int(request.headers.get("content-length", "0")) > limit:
-            raise HTTPException(413, f"Asset exceeds the {limit // (1024 * 1024)} MB upload limit.")
-    except ValueError as exc:
-        raise HTTPException(400, "Invalid Content-Length.") from exc
-    async with _upload_lock:
-        try:
-            path = asset_store.staging_path(mime_type)
-        except ValueError as exc:
-            raise HTTPException(400, str(exc)) from exc
-        try:
-            size = 0
-            with path.open("xb") as handle:
-                async for chunk in request.stream():
-                    size += len(chunk)
-                    if size > limit:
-                        raise HTTPException(413, f"Asset exceeds the {limit // (1024 * 1024)} MB upload limit.")
-                    await run_in_threadpool(handle.write, chunk)
-            asset = await run_in_threadpool(asset_store.add, path,
-                                            unquote(request.headers.get("x-asset-name", "Untitled asset")), mime_type)
-            return asset.public()
-        except ValueError as exc:
-            path.unlink(missing_ok=True)
-            raise HTTPException(400, str(exc)) from exc
-        except BaseException:
-            path.unlink(missing_ok=True)
-            raise
-
-
-@router.api_route("/assets/{asset_id}", methods=["GET", "HEAD"])
-async def get_asset(asset_id: str) -> FileResponse:
-    try:
-        asset = asset_store.get(asset_id)
-    except ValueError as exc:
-        raise HTTPException(404, str(exc)) from exc
-    return FileResponse(asset.path, media_type=asset.mime_type, headers={"X-Content-Type-Options": "nosniff"})
-
-
-@router.delete("/assets/{asset_id}", status_code=204)
-async def delete_asset(asset_id: str) -> Response:
-    try:
-        asset_store.get(asset_id)
-    except ValueError as exc:
-        raise HTTPException(404, str(exc)) from exc
-    try:
-        asset_store.delete(asset_id)
-    except ValueError as exc:
-        raise HTTPException(409, str(exc)) from exc
-    return Response(status_code=204)