diff --git a/.github/scripts/generate_meta_skill.py b/.github/scripts/generate_meta_skill.py
index e6e0d2ec5..7759f1d62 100644
--- a/.github/scripts/generate_meta_skill.py
+++ b/.github/scripts/generate_meta_skill.py
@@ -1,5 +1,5 @@
 #!/usr/bin/env python3
-"""Generate cli-hub-skill/SKILL.md from registry.json and public_registry.json."""
+"""Generate cli-hub-skill/SKILL.md from registry.json, public_registry.json, and matrix_registry.json."""
 import json
 from pathlib import Path
 from collections import defaultdict
@@ -8,6 +8,7 @@ def main():
     repo_root = Path(__file__).parent.parent.parent
     registry_path = repo_root / 'registry.json'
     public_registry_path = repo_root / 'public_registry.json'
+    matrix_registry_path = repo_root / 'matrix_registry.json'
     output_path = repo_root / 'cli-hub-skill' / 'SKILL.md'
 
     with open(registry_path) as f:
@@ -19,6 +20,12 @@ def main():
             public_data = json.load(f)
         public_clis = public_data.get('clis', [])
 
+    matrices = []
+    if matrix_registry_path.exists():
+        with open(matrix_registry_path) as f:
+            matrix_data = json.load(f)
+        matrices = matrix_data.get('matrices', [])
+
     total_count = len(data['clis']) + len(public_clis)
 
     # Group harness CLIs by category
@@ -65,6 +72,24 @@ def main():
         "cli-hub launch <name> [args...]",
         "```",
         "",
+        "## CLI Matrices",
+        "",
+        f"`cli-hub` also ships {len(matrices)} curated cross-tool matrices: install one name to pull in a whole workflow kit and read its dedicated SKILL.md.",
+        "",
+        "```bash",
+        "# Browse curated matrices",
+        "cli-hub matrix list",
+        "",
+        "# Inspect one matrix",
+        "cli-hub matrix info video-creation",
+        "",
+        "# Check which providers are available locally",
+        "cli-hub matrix preflight video-creation --json",
+        "",
+        "# Install the whole matrix",
+        "cli-hub matrix install video-creation",
+        "```",
+        "",
         "## CLI-Anything Harness CLIs",
         "",
         f"Stateful, agent-native wrappers for {len(data['clis'])} GUI applications. All support `--json` output, REPL mode, and undo/redo.",
@@ -97,15 +122,36 @@ def main():
         clis = public_by_category[category]
         lines.append(f"### {category.title()}")
         lines.append("")
-        lines.append("| Name | Description | Entry Point | Install |")
-        lines.append("|------|-------------|-------------|---------|")
+        lines.append("| Name | Description | Entry Point | Install | Skill |")
+        lines.append("|------|-------------|-------------|---------|-------|")
 
         for cli in sorted(clis, key=lambda x: x['name']):
             name = cli['display_name']
             desc = cli['description']
             entry = f"`{cli['entry_point']}`"
             install = f"`cli-hub install {cli['name']}`"
-            lines.append(f"| **{name}** | {desc} | {entry} | {install} |")
+            skill = cli.get('skill_md') or '—'
+            skill_cell = f"`{skill}`" if not str(skill).startswith("http") else skill
+            lines.append(f"| **{name}** | {desc} | {entry} | {install} | {skill_cell} |")
+
+        lines.append("")
+
+    if matrices:
+        lines.extend([
+            "## Curated Matrices",
+            "",
+            "Each matrix is a curated multi-CLI workflow pulled from the CLI Matrix. Installing a matrix installs all member CLIs and points you at a matrix-specific SKILL.md.",
+            "",
+            "| Matrix | Description | CLIs | Install | Skill |",
+            "|--------|-------------|------|---------|-------|",
+        ])
+
+        for matrix in sorted(matrices, key=lambda x: x['name']):
+            skill = matrix.get('skill_md') or '—'
+            install = f"`cli-hub matrix install {matrix['name']}`"
+            lines.append(
+                f"| **{matrix['display_name']}** | {matrix['description']} | {len(matrix.get('clis', []))} | {install} | `{skill}` |"
+            )
 
         lines.append("")
 
@@ -119,6 +165,7 @@ def main():
         "- **uv CLIs**: installed via `uv tool install`",
         "- **brew/script CLIs**: installed via the tool's native installer",
         "- **bundled CLIs**: detected from PATH (pre-installed with the host app)",
+        "- **Matrices**: install a curated set of harness and public CLIs in one command",
         "",
         "## Harness CLI Usage Pattern",
         "",
@@ -152,7 +199,10 @@ def main():
 
     output_path.parent.mkdir(parents=True, exist_ok=True)
     output_path.write_text('\n'.join(lines) + '\n')
-    print(f"Generated meta-skill with {len(data['clis'])} harness CLIs + {len(public_clis)} public CLIs ({total_count} total) at {output_path}")
+    print(
+        f"Generated meta-skill with {len(data['clis'])} harness CLIs + "
+        f"{len(public_clis)} public CLIs + {len(matrices)} matrices at {output_path}"
+    )
 
 if __name__ == '__main__':
     main()
diff --git a/.github/workflows/deploy-pages.yml b/.github/workflows/deploy-pages.yml
index b57c00bc7..8e55a3edc 100644
--- a/.github/workflows/deploy-pages.yml
+++ b/.github/workflows/deploy-pages.yml
@@ -8,7 +8,9 @@ on:
       - '*/agent-harness/**'
       - 'registry.json'
       - 'public_registry.json'
+      - 'matrix_registry.json'
       - 'cli-hub/**'
+      - 'cli-hub-matrix/**'
       - 'docs/hub/**'
       - '.github/workflows/deploy-pages.yml'
       - '.github/scripts/update_registry_dates.py'
@@ -63,12 +65,25 @@ jobs:
           cp registry.json docs/hub/registry.json
           cp public_registry.json docs/hub/public_registry.json
 
+      - name: Copy matrix_registry.json to hub for cli-hub access
+        run: cp matrix_registry.json docs/hub/matrix_registry.json
+
       - name: Build with Jekyll
         uses: actions/jekyll-build-pages@v1
         with:
           source: ./docs/hub
           destination: ./docs/_site
 
+      # Copied after the Jekyll build so SKILL.md front matter is served
+      # verbatim instead of being converted to HTML. Published at
+      # https://hkuds.github.io/CLI-Anything/matrix/<name>/{SKILL.md,references/,scripts/}
+      # (consumed by cli_hub.matrix_skill's published-URL fallback).
+      - name: Copy matrix skill content into site
+        run: |
+          sudo mkdir -p docs/_site/matrix
+          sudo rsync -a --exclude='__pycache__' --exclude='*.pyc' --exclude='*.pyo' \
+            cli-hub-matrix/ docs/_site/matrix/
+
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v3
         with:
diff --git a/.gitignore b/.gitignore
index 8c199271e..bab309f16 100644
--- a/.gitignore
+++ b/.gitignore
@@ -326,18 +326,14 @@ assets/gen_typing_gif.py
 !/registry.json
 !/public_registry.json
 !/matrix_registry.json
-!/docs/
-/docs/*
-!/docs/PREVIEW_PROTOCOL.md
-!/docs/PREVIEW_PROGRESS.md
-!/docs/FREECAD_VIDEO_REFERENCE.md
-!/docs/PREVIEW_MECHANISM_PROGRESS.md
-!/docs/scripts/
-!/docs/scripts/**
-/docs/scripts/__pycache__/
-/docs/scripts/**/*.pyc
-!/docs/hub/
-/docs/hub/registry-dates.json
+# docs/* is always ignored — working documents stay local and are never committed.
+# (Previously-tracked files under docs/ remain in the index until explicitly removed.)
+/docs/
+# CLI-Matrix is unshipped/confidential — never track anything under docs/cli-matrix/.
+/docs/cli-matrix/
+
+# Build-time vendored matrix skill content (generated by cli-hub setup.py build_py/sdist)
+/cli-hub/cli_hub/_matrix_data/
 !/notebooklm/
 /notebooklm/*
 /notebooklm/.*
diff --git a/audacity/agent-harness/cli_anything/audacity/audacity_cli.py b/audacity/agent-harness/cli_anything/audacity/audacity_cli.py
index 84f4e9328..ec0bd14ae 100644
--- a/audacity/agent-harness/cli_anything/audacity/audacity_cli.py
+++ b/audacity/agent-harness/cli_anything/audacity/audacity_cli.py
@@ -40,6 +40,7 @@
 _session: Optional[Session] = None
 _json_output = False
 _repl_mode = False
+_dry_run = False
 
 
 def get_session() -> Session:
@@ -63,6 +64,15 @@ def output(data, message: str = ""):
             click.echo(str(data))
 
 
+def autosave_session_if_needed() -> None:
+    """Persist one-shot mutations immediately when working from a project file."""
+    if _repl_mode or _dry_run:
+        return
+    sess = get_session()
+    if sess.has_project() and sess._modified and sess.project_path:
+        sess.save_session()
+
+
 def _print_dict(d: dict, indent: int = 0):
     prefix = "  " * indent
     for k, v in d.items():
@@ -129,8 +139,9 @@ def cli(ctx, use_json, project_path, dry_run):
 
     Run without a subcommand to enter interactive REPL mode.
     """
-    global _json_output
+    global _json_output, _dry_run
     _json_output = use_json
+    _dry_run = dry_run
 
     if project_path:
         sess = get_session()
@@ -229,6 +240,7 @@ def project_settings(sample_rate, bit_depth, channels):
         sess.snapshot("Change settings")
         result = proj_mod.set_settings(proj, sample_rate, bit_depth, channels)
         output(result, "Settings updated:")
+        autosave_session_if_needed()
     else:
         output(proj.get("settings", {}), "Project settings:")
 
@@ -264,6 +276,7 @@ def track_add(name, track_type, volume, pan):
         volume=volume, pan=pan,
     )
     output(result, f"Added track: {result['name']}")
+    autosave_session_if_needed()
 
 
 @track.command("remove")
@@ -275,6 +288,7 @@ def track_remove(index):
     sess.snapshot(f"Remove track {index}")
     removed = track_mod.remove_track(sess.get_project(), index)
     output(removed, f"Removed track: {removed.get('name', '')}")
+    autosave_session_if_needed()
 
 
 @track.command("list")
@@ -298,6 +312,7 @@ def track_set(index, prop, value):
     result = track_mod.set_track_property(sess.get_project(), index, prop, value)
     output({"track": index, "property": prop, "value": value},
            f"Set track {index} {prop} = {value}")
+    autosave_session_if_needed()
 
 
 # -- Clip Commands ---------------------------------------------------------
@@ -336,6 +351,7 @@ def clip_add(track_index, source, name, start, end, trim_start, trim_end, volume
         trim_start=trim_start, trim_end=trim_end, volume=volume,
     )
     output(result, f"Added clip: {result['name']}")
+    autosave_session_if_needed()
 
 
 @clip.command("remove")
@@ -348,6 +364,7 @@ def clip_remove(track_index, clip_index):
     sess.snapshot(f"Remove clip {clip_index} from track {track_index}")
     removed = clip_mod.remove_clip(sess.get_project(), track_index, clip_index)
     output(removed, f"Removed clip: {removed.get('name', '')}")
+    autosave_session_if_needed()
 
 
 @clip.command("trim")
@@ -365,6 +382,7 @@ def clip_trim(track_index, clip_index, trim_start, trim_end):
         trim_start=trim_start, trim_end=trim_end,
     )
     output(result, "Clip trimmed")
+    autosave_session_if_needed()
 
 
 @clip.command("split")
@@ -380,6 +398,7 @@ def clip_split(track_index, clip_index, split_time):
         sess.get_project(), track_index, clip_index, split_time,
     )
     output(result, f"Split clip into 2 parts at {split_time}s")
+    autosave_session_if_needed()
 
 
 @clip.command("move")
@@ -395,6 +414,7 @@ def clip_move(track_index, clip_index, new_start):
         sess.get_project(), track_index, clip_index, new_start,
     )
     output(result, f"Moved clip to {new_start}s")
+    autosave_session_if_needed()
 
 
 @clip.command("list")
@@ -455,6 +475,7 @@ def effect_add(name, track_index, param):
     sess.snapshot(f"Add effect {name} to track {track_index}")
     result = fx_mod.add_effect(sess.get_project(), name, track_index, params)
     output(result, f"Added effect: {name}")
+    autosave_session_if_needed()
 
 
 @effect_group.command("remove")
@@ -467,6 +488,7 @@ def effect_remove(effect_index, track_index):
     sess.snapshot(f"Remove effect {effect_index} from track {track_index}")
     result = fx_mod.remove_effect(sess.get_project(), effect_index, track_index)
     output(result, f"Removed effect {effect_index}")
+    autosave_session_if_needed()
 
 
 @effect_group.command("set")
@@ -486,6 +508,7 @@ def effect_set(effect_index, param, value, track_index):
     fx_mod.set_effect_param(sess.get_project(), effect_index, param, value, track_index)
     output({"effect": effect_index, "param": param, "value": value},
            f"Set effect {effect_index} {param} = {value}")
+    autosave_session_if_needed()
 
 
 @effect_group.command("list")
@@ -514,6 +537,7 @@ def selection_set(start, end):
     sess = get_session()
     result = sel_mod.set_selection(sess.get_project(), start, end)
     output(result, f"Selection: {start}s - {end}s")
+    autosave_session_if_needed()
 
 
 @selection.command("all")
@@ -523,6 +547,7 @@ def selection_all():
     sess = get_session()
     result = sel_mod.select_all(sess.get_project())
     output(result, "Selected all")
+    autosave_session_if_needed()
 
 
 @selection.command("none")
@@ -532,6 +557,7 @@ def selection_none():
     sess = get_session()
     result = sel_mod.select_none(sess.get_project())
     output(result, "Selection cleared")
+    autosave_session_if_needed()
 
 
 @selection.command("info")
@@ -561,6 +587,7 @@ def label_add(start, end, text):
     sess.snapshot(f"Add label at {start}")
     result = label_mod.add_label(sess.get_project(), start, end, text)
     output(result, f"Added label: {text or f'at {start}s'}")
+    autosave_session_if_needed()
 
 
 @label.command("remove")
@@ -572,6 +599,7 @@ def label_remove(index):
     sess.snapshot(f"Remove label {index}")
     removed = label_mod.remove_label(sess.get_project(), index)
     output(removed, f"Removed label: {removed.get('text', '')}")
+    autosave_session_if_needed()
 
 
 @label.command("list")
@@ -671,6 +699,7 @@ def session_undo():
     sess = get_session()
     desc = sess.undo()
     output({"undone": desc}, f"Undone: {desc}")
+    autosave_session_if_needed()
 
 
 @session_group.command("redo")
@@ -680,6 +709,7 @@ def session_redo():
     sess = get_session()
     desc = sess.redo()
     output({"redone": desc}, f"Redone: {desc}")
+    autosave_session_if_needed()
 
 
 @session_group.command("history")
diff --git a/audacity/agent-harness/cli_anything/audacity/tests/test_full_e2e.py b/audacity/agent-harness/cli_anything/audacity/tests/test_full_e2e.py
index cafc23ade..6339f2971 100644
--- a/audacity/agent-harness/cli_anything/audacity/tests/test_full_e2e.py
+++ b/audacity/agent-harness/cli_anything/audacity/tests/test_full_e2e.py
@@ -707,6 +707,26 @@ def test_cli_export_presets(self):
         assert result.returncode == 0
         assert "wav" in result.stdout.lower()
 
+    def test_cli_project_mutations_persist_to_disk(self, tmp_dir, sine_wav):
+        project_path = os.path.join(tmp_dir, "persist.json")
+
+        result = self._run_cli(["project", "new", "--name", "Persist", "-o", project_path])
+        assert result.returncode == 0
+        assert os.path.exists(project_path)
+
+        result = self._run_cli(["--project", project_path, "track", "add", "--name", "Music"])
+        assert result.returncode == 0
+        with open(project_path, "r", encoding="utf-8") as handle:
+            payload = json.load(handle)
+        assert len(payload["tracks"]) == 1
+        assert payload["tracks"][0]["name"] == "Music"
+
+        result = self._run_cli(["--project", project_path, "clip", "add", "0", sine_wav])
+        assert result.returncode == 0
+        with open(project_path, "r", encoding="utf-8") as handle:
+            payload = json.load(handle)
+        assert len(payload["tracks"][0]["clips"]) == 1
+
 
 # ── True Backend E2E Tests (requires SoX installed) ──────────────
 
diff --git a/cli-hub-matrix/3d-cad/SKILL.md b/cli-hub-matrix/3d-cad/SKILL.md
new file mode 100644
index 000000000..04791fc43
--- /dev/null
+++ b/cli-hub-matrix/3d-cad/SKILL.md
@@ -0,0 +1,232 @@
+---
+name: cli-hub-matrix-3d-cad
+description: >-
+  Capability-based multi-tool matrix for 3D modeling, CAD, point clouds, rendering,
+  GPU debugging, and fabrication. Covers mesh/parametric/photogrammetry and the
+  path from idea to printed part or game-ready asset.
+---
+
+# 3D & CAD Matrix (S3 — v2 capability-based)
+
+Scenario **S3**. Strongest technical scenario in the matrix by depth — Blender + FreeCAD + CloudCompare + RenderDoc is rare coverage. Structural gaps: **texturing** and **fabrication slicing**.
+
+Schema: [`docs/cli-matrix/matrix_registry.schema.md`](../../docs/cli-matrix/matrix_registry.schema.md). Matrix plan: [`docs/cli-matrix/cli-matrix-plan.md`](../../docs/cli-matrix/cli-matrix-plan.md).
+
+## Install
+
+```bash
+cli-hub matrix install 3d-cad
+cli-hub matrix info    3d-cad
+cli-hub matrix preflight 3d-cad --json
+```
+
+---
+
+## Provider selection constraints
+
+1. Use preflight as an availability report, not as a provider selector.
+2. Treat provider order as documentation order only.
+3. Choose from user requirements, output quality bar, offline needs, credential state, install cost, and provider notes.
+4. Escalate to paid or metered APIs only when credentials are already present or the user explicitly consents.
+
+Offline context? Most of this matrix is offline-first; rendering and photogrammetry are the exceptions.
+
+---
+
+## Preflight
+
+Run `cli-hub matrix preflight 3d-cad --json` first. Use the manual block below for extra probes or older `cli-hub` versions.
+
+```bash
+cli-hub list --json
+python - <<'PY'
+import importlib.util
+for m in ("trimesh","pymeshlab","open3d","cadquery","build123d","solid",
+          "pygltflib","laspy","pyvista","bpy","rawpy","pycam"):
+    print(m, importlib.util.find_spec(m) is not None)
+PY
+for b in blender freecad meshroom colmap openmvg openmvs prusaslicer slic3r \
+         cura CuraEngine apitrace vulkaninfo renderdoc OpenSCAD; do
+  command -v "$b" >/dev/null && echo "$b: yes" || echo "$b: no"
+done
+for e in POLYCAM_API_KEY LUMA_API_KEY ONSHAPE_ACCESS_KEY FUSION360_TOKEN \
+         OCTANE_TOKEN; do
+  [ -n "${!e}" ] && echo "$e: set" || echo "$e: unset"
+done
+```
+
+---
+
+## Suggest-to-user template
+
+```
+To enable <capability> via <provider>, please set <ENV_VAR>.
+  Cost: <cost notes>
+  Quality: <quality tier>
+Reply 'skip' to fall back to <next provider>.
+```
+
+Example: *To enable cloud photogrammetry via Luma AI, please set `LUMA_API_KEY`. Cost: metered per-scan. Quality: sota. Reply 'skip' to fall back to local `Meshroom` (slower, free).*
+
+---
+
+## Capabilities
+
+### `model.mesh` — mesh modeling / editing
+
+| Provider | Kind | Requires | Cost | Quality | Offline |
+|---|---|---|---|---|---|
+| `cli-anything-blender` | harness-cli | Blender installed | free | sota | yes |
+| `trimesh` | python | pkg | free | high | yes |
+| `pymeshlab` | python | pkg | free | high | yes |
+| `open3d` | python | pkg | free | high | yes |
+| `pygalmesh` | python | pkg + CGAL | free | high | yes |
+
+### `model.parametric` — parametric CAD
+
+| Provider | Kind | Requires | Cost | Quality | Offline |
+|---|---|---|---|---|---|
+| `cli-anything-freecad` | harness-cli | FreeCAD installed | free | sota | yes |
+| `cadquery` | python | pkg | free | high | yes |
+| `build123d` | python | pkg | free | high | yes |
+| `OpenSCAD` | native | binary | free | high | yes |
+| `SolidPython` | python | pkg + OpenSCAD | free | good | yes |
+| Onshape API | api | `ONSHAPE_ACCESS_KEY` | paid | sota | no |
+| Fusion 360 API | api | `FUSION360_TOKEN` | paid | sota | no |
+
+### `model.sculpt` — digital sculpting
+
+| Provider | Kind | Requires | Cost | Quality | Offline |
+|---|---|---|---|---|---|
+| `cli-anything-blender` (sculpt mode, scripted) | harness-cli | Blender | free | good | yes |
+| ZBrush / Nomad | — | — | — | — | — |
+
+Known gap — agent-driven sculpting is impractical beyond Blender scripts.
+
+### `pointcloud.process` — point cloud ingest / clean / register
+
+| Provider | Kind | Requires | Cost | Quality | Offline |
+|---|---|---|---|---|---|
+| `cli-anything-cloudcompare` | harness-cli | CloudCompare | free | sota | yes |
+| `cli-anything-cloudanalyzer` | harness-cli | harness installed | free | high | yes |
+| `open3d` | python | pkg | free | high | yes |
+| `laspy` | python | pkg | free | high | yes |
+| `pdal` | native | binary | free | sota | yes |
+| `pyvista` | python | pkg | free | high | yes |
+
+### `photogrammetry.reconstruct` — images → 3D mesh
+
+| Provider | Kind | Requires | Cost | Quality | Offline |
+|---|---|---|---|---|---|
+| `Meshroom` | native | binary | free | high | yes |
+| `colmap` | native | binary | free | high | yes |
+| `OpenMVG` + `OpenMVS` | native | binaries | free | high | yes |
+| RealityCapture | native | commercial license | paid | sota | yes |
+| Polycam API | api | `POLYCAM_API_KEY` | metered | sota | no |
+| Luma AI | api | `LUMA_API_KEY` | metered | sota | no |
+
+### `material.texture` — PBR texturing
+
+| Provider | Kind | Requires | Cost | Quality | Offline |
+|---|---|---|---|---|---|
+| `cli-anything-blender` (shader nodes, scripted) | harness-cli | Blender | free | good | yes |
+| `bpy` PBR synthesis | python | pkg | free | good | yes |
+| `Pillow` procedural maps | python | pkg | free | basic | yes |
+| Substance 3D / Polycam Materials / Adobe Sampler | — | — | — | — | — |
+
+**Known gap** — no agent-native path approaches Substance quality.
+
+### `render.preview` — fast viewport renders
+
+| Provider | Kind | Requires | Cost | Quality | Offline |
+|---|---|---|---|---|---|
+| `cli-anything-blender` (Eevee) | harness-cli | Blender | free | high | yes |
+| `cli-anything-godot` (viewport screenshot) | harness-cli | Godot | free | good | yes |
+
+### `render.offline` — path-traced / final renders
+
+| Provider | Kind | Requires | Cost | Quality | Offline |
+|---|---|---|---|---|---|
+| `cli-anything-blender` (Cycles) | harness-cli | Blender + GPU | free | sota | yes |
+| `bpy` + Cycles | python | pkg + GPU | free | sota | yes |
+| Octane Cloud | api | `OCTANE_TOKEN` | paid | sota | no |
+| RenderMan on offline farm | — | license + farm | paid | sota | depends |
+
+### `gpu.debug` — capture / inspect GPU frames
+
+| Provider | Kind | Requires | Cost | Quality | Offline |
+|---|---|---|---|---|---|
+| `cli-anything-renderdoc` | harness-cli | RenderDoc installed | free | sota | yes |
+| `apitrace` | native | binary | free | high | yes |
+| `vulkan-tools` | native | binary | free | good | yes |
+
+### `fabricate.slice` — 3D print slicer (mesh → gcode)
+
+| Provider | Kind | Requires | Cost | Quality | Offline |
+|---|---|---|---|---|---|
+| `PrusaSlicer` CLI | native | binary | free | sota | yes |
+| `CuraEngine` | native | binary | free | high | yes |
+| `slic3r` | native | binary | free | good | yes |
+| Bambu Studio / OrcaSlicer (API-driven) | — | — | — | — | — |
+
+**Known gap** — no agent-native harness, though the natives are scriptable.
+
+### `fabricate.cam` — CAM / CNC toolpaths
+
+| Provider | Kind | Requires | Cost | Quality | Offline |
+|---|---|---|---|---|---|
+| `cli-anything-freecad` (Path workbench, scripted) | harness-cli | FreeCAD | free | good | yes |
+| `pycam` | python | pkg | free | good | yes |
+| `kiri:moto` | native | binary | free | good | yes |
+| Fusion 360 CAM / Onshape CAM | api | tokens | paid | sota | no |
+
+### `export.engine` — handoff to game / viz engine
+
+| Provider | Kind | Requires | Cost | Quality | Offline |
+|---|---|---|---|---|---|
+| `cli-anything-godot` | harness-cli | Godot | free | high | yes |
+| `cli-anything-blender` (glTF/FBX export) | harness-cli | Blender | free | sota | yes |
+| `pygltflib` | python | pkg | free | high | yes |
+| `trimesh` glTF writer | python | pkg | free | good | yes |
+| Unity Asset Pipeline / Unreal Datasmith | — | — | — | — | — |
+
+---
+
+## Recipes
+
+- **`printable-part`** — parametric CAD → mesh → slice → gcode.
+  Uses: `model.parametric`, `model.mesh`, `fabricate.slice`.
+
+- **`game-asset`** — model → texture → export to engine.
+  Uses: `model.mesh`, `material.texture`, `export.engine`, (optional `render.preview`).
+
+- **`reality-scan`** — photos → photogrammetry → clean mesh → export.
+  Uses: `photogrammetry.reconstruct`, `pointcloud.process`, `model.mesh`, `export.engine`.
+
+- **`cnc-part`** — parametric part → CAM toolpath → gcode.
+  Uses: `model.parametric`, `fabricate.cam`.
+
+- **`product-viz-still`** — CAD → import → scene → offline render.
+  Uses: `model.parametric`, `model.mesh`, `material.texture`, `render.offline`.
+
+- **`gpu-bug-repro`** — capture frame → analyze → patch shader.
+  Uses: `gpu.debug`, `render.preview`.
+
+---
+
+## Known gaps
+
+- **`material.texture`** — no open equivalent to Substance; Blender shader nodes are the current ceiling.
+- **`fabricate.slice`** — PrusaSlicer/Cura natives work but want a harness-level wrapper.
+- **`model.sculpt`** — impractical for agents today.
+- **Unity / Unreal export** — only Godot covered on the harness side.
+
+---
+
+## Agent guidance
+
+- **Parametric first, mesh later.** Start in `model.parametric` when the object has dimensions; `model.mesh` when it's organic.
+- **Always bake before export.** When handing off to `export.engine`, apply modifiers and bake materials — runtime engines don't read Blender shader graphs.
+- **Check manifold before slicing.** `fabricate.slice` fails silently on non-manifold meshes; use `trimesh.Trimesh.is_volume` or pymeshlab's manifold check first.
+- **Offline-capable baseline.** This matrix is highly offline-capable — API escalation is rarely needed except for photogrammetry-at-scale.
+- **Workspace discipline.** Keep `.FCStd` / `.blend` / `.ply` / `.stl` / `.gcode` in one project folder so the chain of transformations is reproducible.
diff --git a/cli-hub-matrix/game-development/SKILL.md b/cli-hub-matrix/game-development/SKILL.md
new file mode 100644
index 000000000..01fa37088
--- /dev/null
+++ b/cli-hub-matrix/game-development/SKILL.md
@@ -0,0 +1,213 @@
+---
+name: cli-hub-matrix-game-development
+description: >-
+  Capability-based multi-tool matrix for game development: engine, 3D/2D/audio assets,
+  AI-generated assets, agent playtesting, packaging, store publishing, and telemetry.
+---
+
+# Game Development Matrix (S4 — v2 capability-based)
+
+Scenario **S4**. All asset-creation capabilities covered via the S3/S5 stacks; the structural gap is **distribution** (Steam/itch/console stores) and alternative engines (Unity/Unreal).
+
+Schema: [`docs/cli-matrix/matrix_registry.schema.md`](../../docs/cli-matrix/matrix_registry.schema.md). Matrix plan: [`docs/cli-matrix/cli-matrix-plan.md`](../../docs/cli-matrix/cli-matrix-plan.md).
+
+## Install
+
+```bash
+cli-hub matrix install game-development
+cli-hub matrix info    game-development
+cli-hub matrix preflight game-development --json
+```
+
+---
+
+## Provider selection constraints
+
+1. Use preflight as an availability report, not as a provider selector.
+2. Treat provider order as documentation order only.
+3. Choose from user requirements, output quality bar, offline needs, credential state, install cost, and provider notes.
+4. Escalate to paid or metered APIs only when credentials are already present or the user explicitly consents.
+
+---
+
+## Preflight
+
+Run `cli-hub matrix preflight game-development --json` first. Use the manual block below for extra probes or older `cli-hub` versions.
+
+```bash
+cli-hub list --json
+python - <<'PY'
+import importlib.util
+for m in ("pygame","arcade","panda3d","ursina","trimesh","pygltflib","PIL",
+          "pydub","librosa","music21","mido","abjad","diffusers","replicate",
+          "posthog","gymnasium"):
+    print(m, importlib.util.find_spec(m) is not None)
+PY
+for b in godot blender aseprite butler steamcmd ffmpeg pyinstaller; do
+  command -v "$b" >/dev/null && echo "$b: yes" || echo "$b: no"
+done
+for e in STEAM_USERNAME STEAM_PASSWORD ITCH_API_KEY EPIC_DEV_TOKEN \
+         PLAY_CONSOLE_KEY APP_STORE_CONNECT_KEY \
+         REPLICATE_API_TOKEN OPENAI_API_KEY STABILITY_API_KEY IDEOGRAM_API_KEY \
+         POSTHOG_API_KEY GAMEANALYTICS_KEY PLAYFAB_TITLE_KEY SENTRY_DSN; do
+  [ -n "${!e}" ] && echo "$e: set" || echo "$e: unset"
+done
+```
+
+---
+
+## Suggest-to-user template
+
+```
+To enable <capability> via <provider>, please set <ENV_VAR>.
+  Cost: <cost notes>
+  Quality: <quality tier>
+Reply 'skip' to fall back to <next provider>.
+```
+
+Example: *To publish to Steam, please install `steamcmd` and set `STEAM_USERNAME` + `STEAM_PASSWORD` (use a dedicated build account to limit credential risk). Cost: one-time $100 Steamworks fee. Reply 'skip' to fall back to itch.io via `butler` which only needs `ITCH_API_KEY`.*
+
+---
+
+## Capabilities
+
+### `game.engine` — engine authoring / project manipulation
+
+| Provider | Kind | Requires | Cost | Quality | Offline |
+|---|---|---|---|---|---|
+| `cli-anything-godot` | harness-cli | Godot installed | free | sota | yes |
+| `pygame` | python | pkg | free | good | yes |
+| `arcade` | python | pkg | free | good | yes |
+| `panda3d` | python | pkg | free | high | yes |
+| `ursina` | python | pkg | free | good | yes |
+| Unity / Unreal | — | — | — | — | — |
+
+### `asset.3d` — 3D game assets
+
+See S3 matrix. Primary: `cli-anything-blender`, `cli-anything-freecad`, `trimesh`, `pygltflib`.
+
+### `asset.2d` — sprites, tiles, UI art
+
+| Provider | Kind | Requires | Cost | Quality | Offline |
+|---|---|---|---|---|---|
+| `cli-anything-krita` | harness-cli | Krita installed | free | sota | yes |
+| `cli-anything-inkscape` | harness-cli | Inkscape installed | free | sota | yes |
+| `Pillow` | python | pkg | free | good | yes |
+| `aseprite` | native | binary (commercial) | paid | sota | yes |
+| `pyxel` | python | pkg | free | good | yes |
+| OpenAI GPT-Image-1 | api | `OPENAI_API_KEY` | metered | sota | no |
+| Scenario GG | api | `SCENARIO_API_KEY` | paid | sota | no |
+| Leonardo AI | api | `LEONARDO_API_KEY` | paid | high | no |
+
+### `asset.audio` — sfx and gameplay audio
+
+| Provider | Kind | Requires | Cost | Quality | Offline |
+|---|---|---|---|---|---|
+| `cli-anything-audacity` | harness-cli | Audacity | free | high | yes |
+| `pydub` / `librosa` / `soundfile` | python | pkg | free | good | yes |
+| `sfxr` / `jsfxr` | native | binary | free | good | yes |
+| ElevenLabs SFX | api | `ELEVENLABS_API_KEY` | paid | sota | no |
+| Mubert | api | `MUBERT_API_KEY` | metered | high | no |
+
+### `asset.notation` — music notation / score export
+
+| Provider | Kind | Requires | Cost | Quality | Offline |
+|---|---|---|---|---|---|
+| `cli-anything-musescore` | harness-cli | MuseScore installed | free | sota | yes |
+| `music21` | python | pkg | free | high | yes |
+| `mido` | python | pkg | free | good | yes |
+| `abjad` | python | pkg | free | high | yes |
+
+### `ai.gen-asset` — AI-generated art/audio for games
+
+| Provider | Kind | Requires | Cost | Quality | Offline |
+|---|---|---|---|---|---|
+| `cli-anything-comfyui` | harness-cli | ComfyUI installed | free | high | yes |
+| `jimeng` | public-cli | bin | metered | high | no |
+| `diffusers` | python | pkg + weights | free | good | yes |
+| `replicate` | python | `REPLICATE_API_TOKEN` | metered | high | no |
+| Scenario GG | api | `SCENARIO_API_KEY` | paid | sota | no |
+| Leonardo AI | api | `LEONARDO_API_KEY` | paid | high | no |
+| OpenAI GPT-Image-1 | api | `OPENAI_API_KEY` | metered | sota | no |
+| Stability | api | `STABILITY_API_KEY` | metered | high | no |
+
+### `playtest.agent` — agent-driven play / testing
+
+| Provider | Kind | Requires | Cost | Quality | Offline |
+|---|---|---|---|---|---|
+| `cli-anything-slay-the-spire-ii` | harness-cli | StS II + bridge mod | free | sota | yes |
+| `gymnasium` envs | python | pkg | free | high | yes |
+| Headless game + scripted input (e.g. Godot `--headless` with GUT) | harness-cli | Godot | free | good | yes |
+
+Distinctive capability — very few agent stacks can drive a live GUI game loop.
+
+### `build.package` — package a game binary / bundle
+
+| Provider | Kind | Requires | Cost | Quality | Offline |
+|---|---|---|---|---|---|
+| `cli-anything-godot` (export presets) | harness-cli | Godot export templates | free | sota | yes |
+| `pyinstaller` (pygame/arcade) | python | pkg | free | good | yes |
+| `butler` (itch packager) | native | binary | free | high | yes |
+
+### `publish.store` — upload a build to a store
+
+| Provider | Kind | Requires | Cost | Quality | Offline |
+|---|---|---|---|---|---|
+| `steamcmd` | native | binary + Steam account + app ID | paid (fee) | sota | no |
+| `butler` (itch.io) | native | binary + `ITCH_API_KEY` | free | high | no |
+| Epic Games Services | api | `EPIC_DEV_TOKEN` | paid | high | no |
+| Google Play Developer | api | `PLAY_CONSOLE_KEY` + service account | paid | high | no |
+| App Store Connect | api | `APP_STORE_CONNECT_KEY` | paid | high | no |
+
+**Known gap** — no harness-level abstraction; escalate via the suggest-to-user template with platform-specific preflight.
+
+### `telemetry.ingest` — gameplay analytics / crash reports
+
+| Provider | Kind | Requires | Cost | Quality | Offline |
+|---|---|---|---|---|---|
+| `sentry` | public-cli | bin + `SENTRY_DSN` | free-paid | high | no |
+| `posthog` | python | pkg + `POSTHOG_API_KEY` | free-paid | high | no |
+| GameAnalytics | api | `GAMEANALYTICS_KEY` | free | good | no |
+| Unity Analytics | api | Unity project token | metered | high | no |
+| PlayFab | api | `PLAYFAB_TITLE_KEY` | metered | high | no |
+
+---
+
+## Recipes
+
+- **`godot-jam-game`** — minimal end-to-end for a game jam.
+  Uses: `game.engine`, `asset.2d`, `asset.audio`, `build.package`, (optional `publish.store`).
+
+- **`agent-bot`** — train / evaluate an agent against an existing game.
+  Uses: `playtest.agent`, `telemetry.ingest`.
+
+- **`ai-indie-short`** — AI-generated art + simple engine loop.
+  Uses: `ai.gen-asset`, `asset.2d`, `game.engine`, `asset.audio`, `build.package`.
+
+- **`steam-release`** — ship to Steam with crash reporting.
+  Uses: `build.package`, `publish.store`, `telemetry.ingest`.
+
+- **`music-driven-game`** — composed score integrated with gameplay.
+  Uses: `asset.notation`, `asset.audio`, `game.engine`.
+
+- **`reality-to-game`** — photogrammetry asset → import → ship.
+  Uses: (S3 `photogrammetry.reconstruct`), `asset.3d`, `game.engine`, `build.package`.
+
+---
+
+## Known gaps
+
+- **`publish.store`** — Steam/itch/console wrappers are native-only; escalate with explicit credentials.
+- **`game.engine` for Unity/Unreal** — only Godot harness exists.
+- **`telemetry.ingest`** — Sentry works; no first-party for GameAnalytics/PlayFab.
+- **`asset.notation`** — uniquely strong (MuseScore) but rarely used in practice; keep as a differentiator.
+
+---
+
+## Agent guidance
+
+- **Start in Godot** unless the user has explicitly asked for Unity/Unreal — it's the only engine we harness.
+- **Keep asset pipelines deterministic** — re-runnable seeds for `ai.gen-asset`, versioned source `.aseprite`/`.krita` files, scriptable Blender bakes.
+- **`playtest.agent` needs a bridge.** Most commercial games lack API access; agents should ask the user if modding is permitted before attempting.
+- **Version builds immediately.** `build.package` output goes into `builds/<version>/` with a manifest so `publish.store` has deterministic uploads.
+- **Don't auto-publish.** `publish.store` must always be gated behind explicit user confirmation — uploading a broken build is expensive to roll back.
diff --git a/cli-hub-matrix/image-design/SKILL.md b/cli-hub-matrix/image-design/SKILL.md
new file mode 100644
index 000000000..5e8931a72
--- /dev/null
+++ b/cli-hub-matrix/image-design/SKILL.md
@@ -0,0 +1,218 @@
+---
+name: cli-hub-matrix-image-design
+description: >-
+  Capability-based multi-tool matrix for image and graphic design: AI generation,
+  raster/vector editing, UI mockups, diagrams, upscaling, photo library, and publishing.
+---
+
+# Image & Graphic Design Matrix (S5 — v2 capability-based)
+
+Scenario **S5**. Deepest creation coverage after S2 — raster (GIMP + Krita), vector (Inkscape), AI (ComfyUI + Jimeng + 7 APIs), diagram (drawio + mermaid). **Figma** is the headline gap (also affects S7).
+
+Schema: [`docs/cli-matrix/matrix_registry.schema.md`](../../docs/cli-matrix/matrix_registry.schema.md). Matrix plan: [`docs/cli-matrix/cli-matrix-plan.md`](../../docs/cli-matrix/cli-matrix-plan.md).
+
+## Install
+
+```bash
+cli-hub matrix install image-design
+cli-hub matrix info    image-design
+cli-hub matrix preflight image-design --json
+```
+
+---
+
+## Provider selection constraints
+
+1. Use preflight as an availability report, not as a provider selector.
+2. Treat provider order as documentation order only.
+3. Choose from user requirements, output quality bar, offline needs, credential state, install cost, and provider notes.
+4. Escalate to paid or metered APIs only when credentials are already present or the user explicitly consents. AI image is paid-API-diverse, so ask which provider the user wants when several credentialed choices are available.
+
+Offline context? GIMP, Krita, Inkscape, and local `diffusers` cover almost everything offline.
+
+---
+
+## Preflight
+
+Run `cli-hub matrix preflight image-design --json` first. Use the manual block below for extra probes or older `cli-hub` versions.
+
+```bash
+cli-hub list --json
+python - <<'PY'
+import importlib.util
+for m in ("PIL","cv2","skimage","rembg","svgwrite","cairosvg","svgpathtools","vpype",
+          "diffusers","replicate","rawpy"):
+    print(m, importlib.util.find_spec(m) is not None)
+PY
+for b in inkscape gimp krita drawio magick convert exiftool upscayl darktable-cli \
+         rawtherapee-cli graphviz dot mermaid plantuml hugo mkdocs; do
+  command -v "$b" >/dev/null && echo "$b: yes" || echo "$b: no"
+done
+for e in OPENAI_API_KEY STABILITY_API_KEY IDEOGRAM_API_KEY RECRAFT_API_KEY \
+         GOOGLE_API_KEY MIDJOURNEY_TOKEN FIGMA_TOKEN CANVA_API_KEY PENPOT_TOKEN \
+         REPLICATE_API_TOKEN TOPAZ_API_KEY REMOVE_BG_API_KEY FIREFLY_TOKEN; do
+  [ -n "${!e}" ] && echo "$e: set" || echo "$e: unset"
+done
+```
+
+---
+
+## Suggest-to-user template
+
+```
+To enable <capability> via <provider>, please set <ENV_VAR>.
+  Cost: <cost notes>
+  Quality: <quality tier>
+Reply 'skip' to fall back to <next provider>.
+```
+
+Examples:
+- *To enable sota AI image generation via OpenAI GPT-Image-1, please set `OPENAI_API_KEY`. Cost: metered per-image. Quality: sota for photoreal + text rendering. Reply 'skip' to fall back to local `comfyui` (FLUX/SDXL).*
+- *To round-trip UI mockups with Figma, please set `FIGMA_TOKEN`. Cost: free tier works for most users. Quality: sota (design system aware). Reply 'skip' to fall back to `sketch` or `drawio` wireframes.*
+
+---
+
+## Capabilities
+
+### `visual.generate` — AI image generation
+
+| Provider | Kind | Requires | Cost | Quality | Offline |
+|---|---|---|---|---|---|
+| `cli-anything-comfyui` | harness-cli | ComfyUI + weights | free | high | yes |
+| `jimeng` | public-cli | `dreamina` bin | metered | high | no |
+| `diffusers` (SD/SDXL/FLUX) | python | pkg + weights + GPU | free | good-high | yes |
+| `replicate` | python | `REPLICATE_API_TOKEN` | metered | high | no |
+| OpenAI GPT-Image-1 | api | `OPENAI_API_KEY` | metered | sota | no |
+| Ideogram | api | `IDEOGRAM_API_KEY` | metered | sota | no |
+| Stability AI | api | `STABILITY_API_KEY` | metered | high | no |
+| Recraft | api | `RECRAFT_API_KEY` | paid | sota | no |
+| Google Imagen / Nano Banana | api | `GOOGLE_API_KEY` | metered | high | no |
+| Midjourney (Discord bridge) | api | `MIDJOURNEY_TOKEN` | paid | sota | no |
+| Adobe Firefly | api | `FIREFLY_TOKEN` | paid | high | no |
+
+### `visual.edit.raster` — raster editing
+
+| Provider | Kind | Requires | Cost | Quality | Offline |
+|---|---|---|---|---|---|
+| `cli-anything-gimp` | harness-cli | GIMP installed | free | sota | yes |
+| `cli-anything-krita` | harness-cli | Krita installed | free | sota | yes |
+| `Pillow` | python | pkg | free | good | yes |
+| `opencv-python` | python | pkg | free | high | yes |
+| `scikit-image` | python | pkg | free | high | yes |
+| `rembg` (background removal) | python | pkg | free | high | yes |
+| `remove.bg` | api | `REMOVE_BG_API_KEY` | metered | sota | no |
+| Adobe Firefly | api | `FIREFLY_TOKEN` | paid | sota | no |
+| Cutout.pro | api | token | metered | high | no |
+
+### `visual.edit.vector` — vector editing
+
+| Provider | Kind | Requires | Cost | Quality | Offline |
+|---|---|---|---|---|---|
+| `cli-anything-inkscape` | harness-cli | Inkscape installed | free | sota | yes |
+| `svgwrite` | python | pkg | free | good | yes |
+| `cairosvg` | python | pkg | free | good | yes |
+| `svgpathtools` | python | pkg | free | high | yes |
+| `vpype` (vector post-processing) | python | pkg | free | high | yes |
+
+### `visual.mockup` — UI / mockup / wireframe
+
+| Provider | Kind | Requires | Cost | Quality | Offline |
+|---|---|---|---|---|---|
+| `cli-anything-sketch` | harness-cli | Sketch installed (macOS) | paid app | sota | yes |
+| `cli-anything-drawio` | harness-cli | drawio installed | free | high | yes |
+| `drawio-desktop` | native | binary | free | high | yes |
+| `penpot` | native | binary / self-host | free | high | yes |
+| Figma API | api | `FIGMA_TOKEN` | free tier | sota | no |
+| Canva API | api | `CANVA_API_KEY` | paid | high | no |
+| Penpot API | api | `PENPOT_TOKEN` | free | high | no |
+
+**Known gap** — Figma is the cross-scenario gap (S5 and S7).
+
+### `visual.diagram` — diagrams / flowcharts
+
+| Provider | Kind | Requires | Cost | Quality | Offline |
+|---|---|---|---|---|---|
+| `cli-anything-drawio` | harness-cli | drawio | free | sota | yes |
+| `cli-anything-mermaid` | harness-cli | mermaid-cli | free | high | yes |
+| `graphviz` (`dot`) | native | binary | free | high | yes |
+| `plantuml` | native | binary + java | free | high | yes |
+
+### `visual.upscale` — super-resolution
+
+| Provider | Kind | Requires | Cost | Quality | Offline |
+|---|---|---|---|---|---|
+| `Real-ESRGAN` | python | pkg + weights | free | high | yes |
+| `GFPGAN` (faces) | python | pkg + weights | free | high | yes |
+| `upscayl` | native | binary | free | high | yes |
+| Topaz | api | `TOPAZ_API_KEY` | paid | sota | no |
+| Replicate upscalers | python | `REPLICATE_API_TOKEN` | metered | high | no |
+
+### `photo.library` — DAM / photo organization
+
+| Provider | Kind | Requires | Cost | Quality | Offline |
+|---|---|---|---|---|---|
+| `exiftool` + `Pillow` | native+python | binary+pkg | free | high | yes |
+| `digikam` | native | binary | free | high | yes |
+| `photoprism` | native | binary / self-host | free | high | yes |
+| Google Photos API | api | OAuth | free tier | high | no |
+
+### `photo.develop` — RAW processing
+
+| Provider | Kind | Requires | Cost | Quality | Offline |
+|---|---|---|---|---|---|
+| `rawpy` | python | pkg | free | high | yes |
+| `darktable-cli` | native | binary | free | sota | yes |
+| `rawtherapee-cli` | native | binary | free | sota | yes |
+| Adobe Lightroom API | api | Adobe creds | paid | sota | no |
+
+### `publish.cms` — publish images / articles to a CMS
+
+| Provider | Kind | Requires | Cost | Quality | Offline |
+|---|---|---|---|---|---|
+| `contentful` | public-cli | bin + token | metered | high | no |
+| `sanity` | public-cli | bin + token | metered | high | no |
+| `hugo` / `mkdocs` | native/python | binary/pkg | free | high | yes |
+| WordPress REST | api | app password | free | high | no |
+
+---
+
+## Recipes
+
+- **`social-card`** — generate + compose a social sharing image.
+  Uses: `visual.generate`, `visual.edit.raster`, `publish.cms`.
+
+- **`logo-set`** — design a logo + size variants.
+  Uses: `visual.edit.vector`, `visual.edit.raster` (rasterize), batch export.
+
+- **`ui-wireframe`** — mockup a UI flow.
+  Uses: `visual.mockup`, optional `visual.edit.vector` polish.
+
+- **`photo-batch`** — RAW ingest → develop → edit → library → publish.
+  Uses: `photo.develop`, `visual.edit.raster`, `photo.library`, `publish.cms`.
+
+- **`icon-pack`** — systematic icon production.
+  Uses: `visual.edit.vector`, batch rasterize via `cairosvg`.
+
+- **`thumbnail-set`** — thumbnails for a video/article series.
+  Uses: `visual.generate` (hero imagery), `visual.edit.raster` (layout, type), batch variant export.
+
+- **`ai-concept-art`** — generate → upscale → touch up.
+  Uses: `visual.generate`, `visual.upscale`, `visual.edit.raster`.
+
+---
+
+## Known gaps
+
+- **Figma** — cross-scenario gap (UI/UX loop for S5 and S7). API escalation works but we lack a native harness.
+- **`photo.library` / `photo.develop`** — strong native CLIs, no harness.
+- **Midjourney** — Discord bridge only; no clean API.
+
+---
+
+## Agent guidance
+
+- **Match generation provider to intent.** GPT-Image-1 for text-in-image and photoreal; Ideogram for poster/typography; FLUX for artistic; Midjourney for stylized beauty shots; Stability for control+speed.
+- **Vector-first for design systems** — logos, icons, illustrations start in `visual.edit.vector`, rasterize last.
+- **Preserve color profiles.** `exiftool` + `Pillow` handles ICC; when moving between `rawpy` and `Pillow`, convert to sRGB at the boundary.
+- **AI + edit chain.** Agents should plan: generate → background removal (`rembg`) → composite (`visual.edit.raster`) → export. Skipping cleanup is the most common visible defect.
+- **Workspace discipline.** Keep generation seeds + prompts in a manifest alongside output PNGs so variations are reproducible.
diff --git a/cli-hub-matrix/knowledge-research/SKILL.md b/cli-hub-matrix/knowledge-research/SKILL.md
new file mode 100644
index 000000000..688f997be
--- /dev/null
+++ b/cli-hub-matrix/knowledge-research/SKILL.md
@@ -0,0 +1,241 @@
+---
+name: cli-hub-matrix-knowledge-research
+description: >-
+  Capability-based multi-tool matrix for research, note-taking, document authoring,
+  and publishing. Agents compose providers (CLI-Anything harnesses, public CLIs,
+  Python libs, native binaries, cloud APIs) per capability.
+---
+
+# Knowledge / Office / Research Matrix (S2 — v2 capability-based)
+
+Scenario **S2**. Strongest coverage in the current ecosystem: search, reference management, notes, synthesis, documents, and diagrams all have first-party harnesses; Python/native fallbacks fill the rest.
+
+Schema: [`docs/cli-matrix/matrix_registry.schema.md`](../../docs/cli-matrix/matrix_registry.schema.md). Matrix plan: [`docs/cli-matrix/cli-matrix-plan.md`](../../docs/cli-matrix/cli-matrix-plan.md).
+
+## Install
+
+```bash
+cli-hub matrix install knowledge-research
+cli-hub matrix info    knowledge-research
+cli-hub matrix preflight knowledge-research --json
+```
+
+---
+
+## Provider selection constraints
+
+1. Use preflight as an availability report, not as a provider selector.
+2. Treat provider order as documentation order only.
+3. Choose from user requirements, output quality bar, offline needs, credential state, install cost, and provider notes.
+4. Escalate to paid or metered APIs only when credentials are already present or the user explicitly consents.
+
+Offline context? Filter to `offline: true` providers.
+
+---
+
+## Preflight
+
+Run `cli-hub matrix preflight knowledge-research --json` first. Use the manual block below for extra probes or older `cli-hub` versions.
+
+```bash
+cli-hub list --json
+python - <<'PY'
+import importlib.util
+for m in ("pyzotero","bibtexparser","trafilatura","readability","httpx","playwright",
+          "python_docx","openpyxl","pptx","reportlab","pypdf","pdfplumber","weasyprint",
+          "langchain","llama_index","haystack"):
+    print(m, importlib.util.find_spec(m) is not None)
+PY
+for b in pandoc qpdf pdftk exiftool latexmk tex dot mermaid plantuml hugo mkdocs jekyll; do
+  command -v "$b" >/dev/null && echo "$b: yes" || echo "$b: no"
+done
+for e in OPENAI_API_KEY ANTHROPIC_API_KEY GOOGLE_API_KEY PERPLEXITY_API_KEY TAVILY_API_KEY \
+         SERPAPI_API_KEY BRAVE_API_KEY FIRECRAWL_API_KEY \
+         NOTION_API_KEY SEMANTIC_SCHOLAR_API_KEY WORDPRESS_TOKEN GHOST_ADMIN_KEY; do
+  [ -n "${!e}" ] && echo "$e: set" || echo "$e: unset"
+done
+```
+
+---
+
+## Suggest-to-user template
+
+```
+To enable <capability> via <provider>, please set <ENV_VAR>.
+  Cost: <cost notes>
+  Quality: <quality tier>
+Reply 'skip' to fall back to <next provider>.
+```
+
+Example: *To enable live Notion sync via the Notion API, please set `NOTION_API_KEY`. Cost: free tier suffices for most users. Quality: sota (round-trips block/page IDs). Reply 'skip' to fall back to local Obsidian vault + manual paste.*
+
+---
+
+## Capabilities
+
+### `research.search` — web / literature search
+
+| Provider | Kind | Requires | Cost | Quality | Offline |
+|---|---|---|---|---|---|
+| `cli-anything-exa` | harness-cli | `EXA_API_KEY` | metered | sota | no |
+| `cli-anything-browser` / `safari` / `clibrowser` | harness-cli | browser installed | free | high | no |
+| `duckduckgo-search` | python | pkg | free | good | no |
+| `googlesearch-python` | python | pkg | free | good | no |
+| Perplexity API | api | `PERPLEXITY_API_KEY` | paid | sota | no |
+| Tavily | api | `TAVILY_API_KEY` | metered | high | no |
+| Brave Search | api | `BRAVE_API_KEY` | metered | good | no |
+| Google Custom Search | api | `GOOGLE_API_KEY` | metered | high | no |
+
+### `research.retrieve` — fetch article text / scrape pages
+
+| Provider | Kind | Requires | Cost | Quality | Offline |
+|---|---|---|---|---|---|
+| `cli-anything-browser` / `safari` / `clibrowser` | harness-cli | harness installed | free | high | no |
+| `trafilatura` | python | pkg | free | high | yes |
+| `readability-lxml` | python | pkg | free | good | yes |
+| `httpx` + manual parse | python | pkg | free | basic | yes |
+| `playwright` | python | pkg + browsers | free | sota | no |
+| Firecrawl | api | `FIRECRAWL_API_KEY` | metered | sota | no |
+| ScrapingBee | api | `SCRAPINGBEE_API_KEY` | paid | high | no |
+
+### `research.reference` — citations, BibTeX, references
+
+| Provider | Kind | Requires | Cost | Quality | Offline |
+|---|---|---|---|---|---|
+| `cli-anything-zotero` | harness-cli | Zotero installed | free | sota | yes |
+| `pyzotero` | python | pkg + Zotero key | free | high | no |
+| `habanero` (Crossref) | python | pkg | free | high | no |
+| `bibtexparser` | python | pkg | free | good | yes |
+| Crossref REST | api | none | free | high | no |
+| Semantic Scholar | api | `SEMANTIC_SCHOLAR_API_KEY` (optional) | free | high | no |
+
+### `knowledge.note` — note-taking / PKM
+
+| Provider | Kind | Requires | Cost | Quality | Offline |
+|---|---|---|---|---|---|
+| `cli-anything-obsidian` | harness-cli | Obsidian installed | free | sota | yes |
+| `cli-anything-mubu` | harness-cli | Mubu installed | free | high | no |
+| `obsidian-cli` | public-cli | bin + vault path | free | high | yes |
+| raw markdown + `git` | native | `git` | free | good | yes |
+| `mdformat` | python | pkg | free | good | yes |
+| Notion API | api | `NOTION_API_KEY` | free | sota | no |
+| Roam / Logseq sync | — | — | — | — | — |
+
+### `knowledge.outline` — outlining
+
+| Provider | Kind | Requires | Cost | Quality | Offline |
+|---|---|---|---|---|---|
+| `cli-anything-mubu` | harness-cli | Mubu installed | free | high | no |
+| OPML via `lxml` | python | pkg | free | good | yes |
+| YAML outlines + `yq` | native | binary | free | good | yes |
+
+### `knowledge.synthesize` — multi-doc synthesis / summarization
+
+| Provider | Kind | Requires | Cost | Quality | Offline |
+|---|---|---|---|---|---|
+| `cli-anything-notebooklm` | harness-cli | harness installed | metered | sota | no |
+| `cli-anything-intelwatch` | harness-cli | harness installed | free-metered | high | partial |
+| `langchain` / `llama_index` + local LLM | python | pkg + ollama | free | high | yes |
+| `haystack` | python | pkg | free | good | partial |
+| Claude / OpenAI / Gemini (long context) | api | model key | metered | sota | no |
+
+### `document.author` — write docs (DOCX, XLSX, PPTX, PDF)
+
+| Provider | Kind | Requires | Cost | Quality | Offline |
+|---|---|---|---|---|---|
+| `cli-anything-libreoffice` | harness-cli | LibreOffice installed | free | high | yes |
+| `cli-anything-anygen` | harness-cli | harness installed | free | high | yes |
+| `python-docx` / `openpyxl` / `python-pptx` / `reportlab` | python | pkg | free | good | yes |
+| Google Docs API | api | OAuth token | metered | sota | no |
+| Microsoft Graph | api | Azure app + token | metered | sota | no |
+
+### `document.format` — convert / reformat
+
+| Provider | Kind | Requires | Cost | Quality | Offline |
+|---|---|---|---|---|---|
+| `pandoc` | native | binary | free | sota | yes |
+| `cli-anything-libreoffice` (headless convert) | harness-cli | LibreOffice | free | high | yes |
+| `docx2pdf` | python | pkg + Word/LO | free | good | yes |
+| `weasyprint` | python | pkg | free | high | yes |
+| CloudConvert | api | `CLOUDCONVERT_API_KEY` | metered | sota | no |
+
+### `document.pdf` — manipulate PDFs (split, merge, OCR, extract)
+
+| Provider | Kind | Requires | Cost | Quality | Offline |
+|---|---|---|---|---|---|
+| `qpdf` / `pdftk` | native | binary | free | sota | yes |
+| `pypdf` | python | pkg | free | high | yes |
+| `pdfplumber` | python | pkg | free | high | yes |
+| `pdf2image` | python | pkg + poppler | free | good | yes |
+| `ocrmypdf` | native | binary + tesseract | free | high | yes |
+| Adobe PDF Services | api | Adobe creds | paid | sota | no |
+
+### `diagram.create` — diagrams, flowcharts, architecture
+
+| Provider | Kind | Requires | Cost | Quality | Offline |
+|---|---|---|---|---|---|
+| `cli-anything-drawio` | harness-cli | drawio installed | free | sota | yes |
+| `cli-anything-mermaid` | harness-cli | mermaid-cli | free | high | yes |
+| `graphviz` (`dot`) | native | binary | free | high | yes |
+| `plantuml` | native | binary | free | high | yes |
+
+### `publish.web` — publish articles / blog posts
+
+| Provider | Kind | Requires | Cost | Quality | Offline |
+|---|---|---|---|---|---|
+| `contentful` | public-cli | bin + space token | metered | high | no |
+| `sanity` | public-cli | bin + project token | metered | high | no |
+| `hugo` / `mkdocs` / `jekyll` / `pelican` | native/python | binary/pkg | free | high | yes |
+| WordPress REST | api | app password | free | high | no |
+| Ghost Admin | api | `GHOST_ADMIN_KEY` | free | high | no |
+| Medium (legacy) | api | token | free | good | no |
+
+### `publish.latex` — build PDFs from LaTeX
+
+| Provider | Kind | Requires | Cost | Quality | Offline |
+|---|---|---|---|---|---|
+| `latexmk` + `texlive` | native | binaries | free | sota | yes |
+| `pylatex` | python | pkg + texlive | free | high | yes |
+| Overleaf API | api | `OVERLEAF_API_KEY` | paid | sota | no |
+| Tectonic | native | binary | free | high | yes |
+
+---
+
+## Recipes
+
+- **`literature-review`** — survey a topic, extract key papers, synthesize.
+  Uses: `research.search`, `research.retrieve`, `research.reference`, `knowledge.synthesize`, `document.author`.
+
+- **`meeting-to-doc`** — turn a recorded meeting into a structured document.
+  Uses: `text.transcribe` (via S1 matrix), `knowledge.synthesize`, `document.author`, `document.format`.
+
+- **`blog-post`** — research → write → publish.
+  Uses: `research.search`, `research.retrieve`, `knowledge.synthesize`, `document.author`, `publish.web`.
+
+- **`paper-draft`** — research + citations + LaTeX.
+  Uses: `research.reference`, `knowledge.synthesize`, `document.author`, `publish.latex`.
+
+- **`competitive-brief`** — fetch competitor pages, extract positioning, produce a briefing deck.
+  Uses: `research.retrieve`, `knowledge.synthesize`, `document.author` (PPTX).
+
+- **`pdf-book-digest`** — ingest a PDF book, OCR if needed, produce chapter summaries + quote file.
+  Uses: `document.pdf`, `knowledge.synthesize`, `knowledge.note`.
+
+---
+
+## Known gaps
+
+- **Notion** — Notion API exists as an escalation, but there is no harness for local-first Notion workflows. Recurs in S11 (team comms).
+- **Google Docs / Microsoft 365 live editing** — API path only.
+- **LaTeX harness** — `latexmk` + Tectonic cover the native path, but no agent-native wrapper yet.
+- **Translation** — no first-party CLI; Python fallback and APIs only.
+
+---
+
+## Agent guidance
+
+- **Run preflight once per session.** Many capabilities have strong Python or native paths that bypass the need to install anything.
+- **Prefer local** for sensitive docs (legal, health, internal): use Obsidian + local LLM + `whisper` rather than cloud APIs.
+- **Citations are load-bearing** — for academic work always route through `research.reference` so bibliographies stay consistent.
+- **Chain `document.format` at the end**, not the middle: author in the richest source format (markdown or LaTeX) and convert last.
+- **Workspace discipline** — one directory per project; keep `refs.bib`, source markdown, figures, and output PDFs colocated.
diff --git a/cli-hub-matrix/video-creation/SKILL.md b/cli-hub-matrix/video-creation/SKILL.md
new file mode 100644
index 000000000..26f14b7a1
--- /dev/null
+++ b/cli-hub-matrix/video-creation/SKILL.md
@@ -0,0 +1,536 @@
+---
+name: cli-hub-matrix-video-creation
+description: >-
+  Capability-based multi-tool matrix for video production. Agents pick providers
+  (CLI-Anything harnesses, public CLIs, Python libs, native binaries, cloud APIs)
+  per capability rather than marching through fixed stages, including storyboard
+  planning, story/audio direction, source triage, internet video/music
+  search/download, capture/generation, analysis, sound design, high-end caption
+  design, NLE/render doctor investigation, review, and packaging.
+---
+
+# Video Creation Matrix (v3 — capability-based)
+
+This matrix describes **capabilities** the agent can compose on demand — not a fixed pipeline. A "video creation" workflow picks a *recipe* (which capabilities it needs) and, per capability, picks a *provider* from the task requirements and preflight facts below.
+
+Schema: [`docs/cli-matrix/matrix_registry.schema.md`](../../docs/cli-matrix/matrix_registry.schema.md).
+
+## Install (installable portion)
+
+```bash
+cli-hub matrix install video-creation   # installs registered matrix CLIs only
+cli-hub matrix info    video-creation   # inspect providers & recipes
+cli-hub matrix preflight video-creation # check available providers in this environment
+```
+
+Not everything in this matrix is installed by `cli-hub matrix install`. Cloud APIs, Python packages, native binaries, third-party public CLIs, and external skills are first-class providers too, but install them only after the task actually needs that provider.
+Do not hand-write `pip install ...#subdirectory=...` for CLI-Anything matrix members; install the supported harnesses through `cli-hub matrix install video-creation`, then use preflight to see what else is already available.
+
+---
+
+## Provider selection constraints (agent: evaluate per capability)
+
+1. Use preflight as an availability report, not as a provider selector.
+2. Choose providers from the user's goal, quality bar, budget, offline needs, credential state, install cost, and requested workflow.
+3. Treat registry/provider order as documentation order only; do not assume the first provider is the correct one.
+4. Install Python libs, native binaries, harness CLIs, public CLIs, or agent skills only when they fit the task constraints.
+5. Escalate to paid or metered APIs only when the user has supplied credentials or explicitly consents. Never silently call a paid API.
+6. If a task falls into a genre with a mandatory provider rule, the provider is not optional. Do not substitute a cheaper/easier fallback just because it is locally convenient.
+
+Offline context? Filter to `offline: true` providers only.
+
+---
+
+## Preflight (run once per session, cache the result)
+
+Run the built-in matrix preflight first:
+
+```bash
+cli-hub matrix preflight video-creation --json
+cli-hub matrix preflight video-creation --capability composite.assemble
+cli-hub matrix preflight video-creation --offline
+```
+
+If you need raw checks or are running without the latest `cli-hub`, use the manual block:
+
+```bash
+cli-hub list --json
+python - <<'PY'
+import importlib.util
+for m in ("moviepy","whisper","pydub","PIL","edge_tts","pysrt","pysubs2","yt_dlp","spotdl","scenedetect","paddleocr","twelvelabs"):
+    print(m, importlib.util.find_spec(m) is not None)
+PY
+for b in ffmpeg ffprobe sox convert magick screencapture yt-dlp spotdl scdl bandcamp-dl you-get lux BBDown scenedetect mediainfo ffmpeg-quality-metrics paddleocr hyperframes; do command -v "$b" >/dev/null && echo "$b: yes" || echo "$b: no"; done
+for e in RUNWAY_API_KEY KLING_API_KEY PIKA_API_KEY SEEDANCE_API_KEY \
+         ELEVENLABS_API_KEY MINIMAX_API_KEY OPENAI_API_KEY GOOGLE_CLOUD_PROJECT \
+         ASSEMBLYAI_API_KEY DEEPGRAM_API_KEY \
+         SUNO_API_KEY UDIO_API_KEY IDEOGRAM_API_KEY STABILITY_API_KEY \
+         TWELVELABS_API_KEY GOOGLE_APPLICATION_CREDENTIALS; do
+  [ -n "${!e}" ] && echo "$e: set" || echo "$e: unset"
+done
+```
+
+---
+
+## Suggest-to-user template (agent uses verbatim when escalating)
+
+```
+To enable <capability> via <provider>, please set <ENV_VAR>.
+  Cost: <cost notes>
+  Quality: <quality tier>
+Reply 'skip' to fall back to <next provider>.
+```
+
+Examples:
+
+- *To enable cinematic AI video via Runway Gen-4, please set `RUNWAY_API_KEY`. Cost: ~$0.05/sec as of 2026-04. Quality: sota. Reply 'skip' to fall back to `generate-veo-video` or `jimeng` if configured.*
+- *To enable ByteDance Seedance video generation, please set `SEEDANCE_API_KEY`. Cost: metered per-clip. Quality: sota for realistic motion. Reply 'skip' to fall back to `jimeng` (Dreamina) which shares the ByteDance model family.*
+
+---
+
+## Capabilities
+
+### `script.storyboard` — brief to creative direction, script, shot list, timing, and asset plan
+
+Use this before generation, search, capture, or assembly when the user gives a vague concept or asks for a complete video. By default, do the planning directly as agent work: produce a structured brief, global creative direction, narrative/emotional arc, audio arc, script/narration, shot list, timing map, asset requirements, and reviewable storyboard before spending time on downloads or generation.
+
+For any non-trivial video, read [`references/story-structure-audio.md`](references/story-structure-audio.md) and save `creative_direction.md` before final assembly. This is mandatory for trailers, sports/music montages, film commentary, found-footage edits, product launch videos, and any output where flat random clips or boring music would fail the brief.
+
+Hard gate: do not begin final assembly for a non-trivial video until `creative_direction.md` exists. `plan.md` is not a substitute. The file must include target duration or requested duration range, output language, a shot-role table with time, beat, source/shot role, audio event, caption/title role, and failure risk; reject plans where the ending/final act has no payoff, climax, reveal, useful recap, or deliberate unresolved hook appropriate to the genre. Language rule: if the user specifies an output language, use it for all agent-authored viewer-facing content; otherwise use the language the user is using in the conversation.
+
+| Provider | Kind | Requires | Cost | Quality | Offline |
+|---|---|---|---|---|---|
+| Agent-native planning | agent-native | none | free | high | yes |
+| `storyboard-creation` skill | agent-skill | installed skill | free | high | yes |
+| `remotion-best-practices` skill | agent-skill | installed skill | free | high for code-driven motion video | yes |
+
+Selection:
+
+- Start with agent-native planning for normal scripts, shot lists, timing maps, and asset plans.
+- Include `creative_direction.md` with the one-sentence promise, story arc, emotional curve, audio arc, cut-density curve, visual motif, source roles, and no-flatness guardrails.
+- Use `storyboard-creation` only when you need explicit storyboard-panel conventions, camera-angle grammar, continuity checks, or animatic planning.
+- Use `remotion-best-practices` only when the storyboard will be implemented as Remotion/React motion-video code.
+
+### `video.search` — discover candidate internet footage
+
+Use this before `video.download` when the user asks for found footage, B-roll, public-domain clips, stock footage, YouTube/Bilibili material, or named movie/TV/game/anime moments. Prefer free/open sources first and record source URL, license, creator, and attribution requirement before editing.
+
+For found-footage deliverables or platform-origin claims, read [`references/source-triage.md`](references/source-triage.md) and classify each candidate as direct platform source, verified platform-origin transport, or weak mirror.
+
+| Provider | Kind | Requires | Cost | Quality | Offline |
+|---|---|---|---|---|---|
+| Web search + source filters | web-search | online search access | free | good | no |
+
+Search discipline:
+
+- For reusable/commercial-safe B-roll, start with Wikimedia Commons, YouTube Creative Commons, or other browser-searchable stock/public-domain pages and keep attribution metadata beside every downloaded file.
+- For Bilibili/YouTube reference or fan-edit workflows, search specific scene names rather than generic terms. Add quality modifiers such as `1080p`, `4K`, `HD`, `BD`, `蓝光`, or `高清`.
+- For Bilibili, use targeted web search such as `site:bilibili.com "Game of Thrones" S3E09 BV`; standalone `/video/BV...` uploads are usually easier to process than geo-restricted bangumi URLs.
+- Do not treat downloadability as permission. If license or user authorization is unclear, ask before using the footage in a deliverable.
+
+### `video.download` — download/import web video into the workspace
+
+Use this after `video.search` identifies candidate URLs, or directly when the user gives URLs. Keep all raw downloads in one `sources/` directory, save `sources.json` with URL/license/creator/provenance, and normalize filenames before downstream editing.
+
+For internet footage, `sources.json` must record the platform URL, transport URL if different, command, cookie-file path if used, local file, probe summary, selected ranges, source role, license/rights notes, and quality caveats.
+
+| Provider | Kind | Requires | Cost | Quality | Offline |
+|---|---|---|---|---|---|
+| `yt-dlp` | public-cli | `yt-dlp` + `ffmpeg` | free | high | no |
+| `you-get` | public-cli | `you-get` bin | free | good | no |
+| `lux` | public-cli | `lux` + `ffmpeg` | free | good | no |
+| `BBDown` | public-cli | `BBDown` + `ffmpeg` | free | high for Bilibili | no |
+
+Operational notes:
+
+- Prefer `yt-dlp -f "bestvideo[height>=1080]+bestaudio/best" --merge-output-format mp4` for YouTube/Bilibili URLs when quality matters. Use cookies only when the user has authorized access to the content.
+- For Bilibili audio-only extraction, avoid `yt-dlp -x --audio-format mp3`; download the raw m4a and convert with `ffmpeg`, then verify volume before using it.
+- Use `BBDown` when Bilibili-specific metadata, subtitles, danmaku, playlists, or high-quality member streams are central to the task.
+
+### `music.search` — discover existing songs, BGM, or clean audio sources
+
+Use this before `music.download` when the user wants an existing song, soundtrack cue, royalty-free track, platform audio, or a specific cover/version. Keep the search about the requested music, not just any available audio. Record title, artist, platform URL, uploader, source type, version notes, rights/licensing, and attribution in `music_sources.json`.
+
+| Provider | Kind | Requires | Cost | Quality | Offline |
+|---|---|---|---|---|---|
+| Web search + source filters | web-search | online search access | free | good | no |
+| `yt-dlp` search extractors | public-cli | `yt-dlp` | free | good | no |
+| `spotdl` metadata/search | public-cli | `spotdl` | free | good for Spotify-linked songs | no |
+
+Search discipline:
+
+- For clean audio, look for the artist's official upload, label upload, official audio/MV, verified lyric video, or a standalone audio upload with no extra descriptors.
+- If the user asks for a specific version such as `女生版`, duet, piano, acoustic, live, DJ, karaoke, or instrumental, verify the title/uploader/metadata names that exact version before committing.
+- Reject candidate titles that imply the wrong source: `remix`, `cover`, `fan edit`, `AMV`, `MAD`, `mashup`, compilation, trailer mix, or unrelated soundtrack/OST unless the user explicitly asked for that variant.
+- For tie-in songs and promo tracks, assume dialogue/voiceover/SFX bleed is possible. Search alternatives with `{artist} {song} 纯音乐`, `{song} 无对白`, `{song} 歌词版`, `official audio`, or `lyric video` before asking the user to accept a risky source.
+- Do not treat downloadability as permission. If rights, license, or user authorization is unclear, ask before using the music in a deliverable.
+
+### `music.download` — download/import existing music into the workspace
+
+Use this after `music.search` identifies a candidate or directly when the user supplies a music URL/local file. Keep raw downloads in `sources/music/`, save `music_sources.json`, and create a normalized working file for editing.
+
+| Provider | Kind | Requires | Cost | Quality | Offline |
+|---|---|---|---|---|---|
+| `yt-dlp` audio download | public-cli | `yt-dlp` + `ffmpeg` | free | high | no |
+| `spotdl` | public-cli | `spotdl` + `ffmpeg` | free | good for Spotify-linked metadata | no |
+| `scdl` | public-cli | `scdl` | free | good for SoundCloud | no |
+| `bandcamp-dl` | public-cli | `bandcamp-dl` | free | good for Bandcamp | no |
+| local file import + `ffmpeg` | native | `ffmpeg` | free | high | yes |
+
+Operational notes:
+
+- Use only music the user is authorized to use or that is clearly licensed for the deliverable. Do not bypass DRM, paywalls, or access controls.
+- For general audio URLs, download source audio first, then convert explicitly:
+
+```bash
+yt-dlp -f "bestaudio[ext=m4a]/bestaudio" -o "sources/music/audio_raw.%(ext)s" "URL"
+ffmpeg -i sources/music/audio_raw.m4a -vn -c:a libmp3lame -q:a 0 sources/music/audio.mp3
+```
+
+- For Bilibili audio-only downloads, do **not** use `yt-dlp -x --audio-format mp3`; it can produce a valid-looking but nearly silent MP3. Download the raw m4a, convert with `ffmpeg`, then verify volume:
+
+```bash
+yt-dlp -f 30280 -o "sources/music/audio_raw.%(ext)s" "BILIBILI_URL"
+ffmpeg -i sources/music/audio_raw.m4a -c:a libmp3lame -q:a 0 sources/music/audio.mp3
+ffmpeg -i sources/music/audio.mp3 -af volumedetect -f null - 2>&1 | grep mean_volume
+```
+
+Reject files with mean volume below roughly `-40dB` unless silence is expected.
+
+- Sample-listen at least three points before editing, especially for promo/OST/tie-in songs:
+
+```bash
+ffplay -ss 30 -t 5 -autoexit sources/music/audio.mp3
+ffplay -ss 90 -t 5 -autoexit sources/music/audio.mp3
+ffplay -ss 150 -t 5 -autoexit sources/music/audio.mp3
+```
+
+- Normalize or loudness-match only after verifying the source is the right song/version and has no dialogue/SFX bleed.
+
+### `visual.capture` — record screen / webcam / window
+
+| Provider | Kind | Requires | Cost | Quality | Offline |
+|---|---|---|---|---|---|
+| `cli-anything-openscreen` | harness-cli | harness installed | free | high | yes |
+| `cli-anything-obs-studio` | harness-cli | OBS installed | free | high | yes |
+| `ffmpeg -f x11grab` / `avfoundation` | native | `ffmpeg` | free | high | yes |
+| `screencapture` | native | macOS | free | high | yes |
+| `mss` / `pyautogui` + `cv2` | python | pkgs | free | good | yes |
+
+### `visual.generate` — produce a video clip from prompt/reference
+
+| Provider | Kind | Requires | Cost | Quality | Offline |
+|---|---|---|---|---|---|
+| `generate-veo-video` | public-cli | `generate-veo` bin + Google creds | metered | high | no |
+| `jimeng` | public-cli | `dreamina` bin + Dreamina login | metered | high | no |
+| Runway Gen-4 | api | `RUNWAY_API_KEY` | paid | sota | no |
+| Kling | api | `KLING_API_KEY` | paid | high | no |
+| Pika | api | `PIKA_API_KEY` | paid | good | no |
+| Seedance | api | `SEEDANCE_API_KEY` | paid | sota | no |
+
+### `audio.capture` — record and clean audio tracks
+
+| Provider | Kind | Requires | Cost | Quality | Offline |
+|---|---|---|---|---|---|
+| `cli-anything-audacity` | harness-cli | Audacity installed | free | high | yes |
+| `sox` / `ffmpeg` | native | binary | free | high | yes |
+| `pydub` / `soundfile` / `librosa` / `noisereduce` | python | pkgs | free | good | yes |
+
+### `audio.synthesize` — text-to-speech / voice
+
+| Provider | Kind | Requires | Cost | Quality | Offline |
+|---|---|---|---|---|---|
+| `minimax-cli` | public-cli | bin + MiniMax key | metered | high | no |
+| `elevenlabs` | public-cli | bin + `ELEVENLABS_API_KEY` | paid | sota | no |
+| OpenAI TTS | api | `OPENAI_API_KEY` | metered | high | no |
+| Google Cloud TTS | api | `GOOGLE_CLOUD_PROJECT` | metered | high | no |
+| `edge-tts` | python | pkg | free | good | no |
+
+### `music.generate` — generated music / BGM
+
+| Provider | Kind | Requires | Cost | Quality | Offline |
+|---|---|---|---|---|---|
+| `suno` | public-cli | bin + Suno account | metered | sota | no |
+| `minimax-cli` | public-cli | bin + MiniMax key | metered | high | no |
+| Udio | api | `UDIO_API_KEY` | paid | sota | no |
+
+Use `music.search` + `music.download` instead when the user asks for an existing song, official upload, platform audio, soundtrack cue, royalty-free track, or a specific cover/version.
+
+Music and SFX must follow the story/audio arc in `creative_direction.md`. For polished 60+ second videos, choose a real main music strategy first: either AI-generated music from a music provider, downloaded relevant/authorized music via `music.search` + `music.download`, or strong source ambience when the genre is documentary/ambient. Avoid one flat loop from start to finish; plan section changes such as intro, buildup, drop, dip, final lift, source-audio reveal, or final resolve.
+
+### `sound.design` — hits, risers, score sections, mix dynamics, and final audio arc
+
+Use this when a video needs trailer hits, whooshes, risers, drones, heartbeat gaps, sub drops, crowd/source accents, or locally generated score elements. Do not hide sound design inside `music.generate`; a music bed is not a designed mix.
+
+| Provider | Kind | Requires | Cost | Quality | Offline |
+|---|---|---|---|---|---|
+| Agent-native sound plan | agent-native | `references/sound-design.md` | free | high | yes |
+| `ffmpeg` / `sox` procedural stems | native | binary | free | good | yes |
+| `pydub` / `numpy` procedural stems | python | pkgs | free | good | yes |
+| Generated music provider | public-cli/api | chosen `music.generate` provider | metered/paid | high | no |
+| Downloaded/authorized music | public-cli/skill | `music.search` + `music.download` or `music-downloader` skill | varies | high when relevant | no |
+
+Deliverables for polished edits: `sound_design.md` with stems, cue times, story function, ducking notes, and section loudness targets; separate WAV stems when generated locally; and per-section loudness checks. The ending/final act should have intentional audio shape such as escalation, silence/hold, hit/drop, source-audio reveal, or resolve when the genre calls for it. Read [`references/sound-design.md`](references/sound-design.md) for sports, commentary, trailer, and final-act patterns.
+
+Source-audio gate: before mixing downloaded/captured clip audio with new music or narration, classify every used range as `silent_or_mute`, `ambience_keep`, `dialogue_keep`, `music_only`, `mixed_music_speech`, or `needs_separation`. Keep one foreground voice and one intentional music bed at a time. If source speech/music overlaps new narration/music, mute, duck, make the source foreground, run separation, or reject the range; do not hide the conflict behind "source texture."
+
+Procedural-audio gate: locally generated audio is acceptable for short SFX, UI ticks, impacts, pulses, and risers, but it must not become the default main music bed for polished 60+ second videos. Prefer AI-generated music or downloaded relevant/authorized music for the main bed. Locally generated noise, risers, and whooshes must be filtered, enveloped, gain-staged, and sample-reviewed. Do not use raw Gaussian/full-band noise as a music bed or repeated transition effect; hiss/sizzle in the promoted final is a critical issue even if `silencedetect` looks normal.
+
+### `media.analyze` — segment, label, OCR, and search footage
+
+Use this after download/capture and before edit planning when there are many clips or when the edit depends on finding specific shots. Output should be a scene library with time ranges, keyframes, visible text, people/objects/actions where available, usability notes, and searchable tags.
+
+| Provider | Kind | Requires | Cost | Quality | Offline |
+|---|---|---|---|---|---|
+| PySceneDetect `scenedetect` | public-cli | `scenedetect` + `ffmpeg` | free | high | yes |
+| Google Cloud Video Intelligence | api | GCP creds | metered | sota | no |
+| TwelveLabs video search/index | api | `TWELVELABS_API_KEY` + `twelvelabs` pkg | metered | sota | no |
+| PaddleOCR on sampled keyframes | public-cli/python | `paddleocr` pkg or bin | free | good overall; high for visible text | yes |
+
+Default path:
+
+- Use PySceneDetect for general local cut detection and keyframe extraction.
+- Use PaddleOCR only on sampled keyframes or subtitle regions; it complements scene detection rather than replacing it.
+- Use Google Video Intelligence or TwelveLabs when you need high-quality object/person/action/text labels or semantic search over a larger footage library and the user accepts cloud processing/cost.
+
+Found-footage gate:
+
+- Build `scene_library.json` before cutting, with source file, start/end, resolution, visual description, shot role, motion level, faces/action/objects, source text/watermarks/subtitles, quality notes, and rejection reason when skipped.
+- Create contact sheets for each source and selected ranges. Scan for countdown cards, credits, hardcoded captions, watermarks, large ranking numbers, and source title cards.
+- Do not use a source just because it downloaded. Reject or crop/mask ranges that are low-resolution, static, duplicated, credit-card-heavy, subtitle-dominated, or off-theme. Use [`references/source-triage.md`](references/source-triage.md) for the rejection checklist.
+
+### `text.transcribe` — speech → text / subtitles
+
+| Provider | Kind | Requires | Cost | Quality | Offline |
+|---|---|---|---|---|---|
+| `cli-anything-videocaptioner` | harness-cli | harness installed | free | high | yes |
+| `openai-whisper` | python | pkg + model download | free | high | yes |
+| `stable-ts` / `faster-whisper` | python | pkg + model download | free | high | yes |
+| AssemblyAI | api | `ASSEMBLYAI_API_KEY` | paid | sota | no |
+| Deepgram | api | `DEEPGRAM_API_KEY` | paid | sota | no |
+| Google Speech-to-Text | api | GCP creds | metered | high | no |
+
+Local ASR notes:
+
+- Preflight package checks do not prove Whisper model weights are already cached or that runtime will fit the task.
+- Prefer small/base CPU models for quick local drafts; use larger models only when the user accepts the time/resource tradeoff or the machine is known to handle it.
+- Use paid/cloud ASR when long recordings, diarization, timestamps, or quality requirements make local model setup a poor fit.
+- Do not use Whisper `.en` models unless the user explicitly says the audio is English; `.en` models translate non-English speech into English.
+
+### `text.caption` — design, time, render, and investigate visible captions
+
+Use this after `text.transcribe` or agent-written script/narration timing, and before `composite.overlay` / `package.encode`. This is for viewer-facing subtitles, creator captions, trailer title hits, lyrics/karaoke, lower-third text, and other timed text that must look high-end. It is not just "burn SRT at the end."
+
+| Provider | Kind | Requires | Cost | Quality | Offline |
+|---|---|---|---|---|---|
+| Captions reference module | agent-native | `references/captions.md` | free | high | yes |
+| ASS + `ffmpeg subtitles` | native | `ffmpeg` + fonts | free | high | yes |
+| HyperFrames captions workflow | agent-skill | `npx skills add heygen-com/hyperframes --skill hyperframes`; Node.js + `ffmpeg` | free | high for kinetic/digital captions | yes |
+| `pysubs2` ASS authoring | python | `pysubs2` pkg + `ffmpeg` | free | high | yes |
+| MoviePy/Pillow transparent overlays | python | `moviepy` + `PIL` | free | good when custom layout is required | yes |
+
+Caption discipline:
+
+- Read [`references/captions.md`](references/captions.md) for any polished caption/subtitle/lyric/lower-third work. It defines the lifecycle, genre presets, typography, safe-zone rules, and caption doctor review.
+- Keep transcription (`text.transcribe`) separate from caption design (`text.caption`). A raw SRT is source material, not a finished caption package.
+- Keep caption roles separate: narration subtitle, story-beat label, chapter/title card, source translation, and lyric/karaoke. Do not turn every story beat into a narration subtitle.
+- Produce `captions.source.json`, `captions_style.md`, `captions.ass` or equivalent render source, caption-heavy preview frames/contact sheet, and `captions_qc.md` for non-trivial videos.
+- Prefer ASS + `ffmpeg` for deterministic subtitle burn-in on edited footage. Use the installed HyperFrames skill when captions are part of a mandatory HyperFrames workflow: digital product/site/app launch videos, UI-heavy presentations, HTML/CSS/GSAP motion compositions, karaoke, or audio-reactive typography.
+- If captions are generated after an NLE master, burn them onto the exact final master and regenerate review frames from the exact promoted final path.
+- Ban persistent debug-like widgets unless explicitly part of the design, such as `MISSION SUBTITLE`, `MISSION LOG`, or fixed label tags that appear on every caption.
+- For voice captions, sync to voice/audio timing, not shot timing. If a narration track exists, derive subtitles from the narration transcript or ASR/forced alignment; manually timed summary captions are title cards, not voice subtitles. Verify narration duration versus voice-caption coverage.
+- Honor the output-language rule across narration, subtitles, title cards, callouts, UI labels created by the agent, and CTA text. Source-language subtitles may be translated or avoided, but do not let source or instruction language leak into agent-authored viewer-facing text.
+- For ASS burn-in, set `PlayResX`/`PlayResY` to the actual final render resolution or prove the scaling keeps text readable. A 1080p ASS design burned into 720p without resizing is a failure.
+- If source footage has hardcoded captions, broadcast tickers, watermarks, or lower thirds, choose a safe zone, crop/mask, or replace the range. Do not stack authored subtitles over source subtitles.
+- Fail the render if captions are clipped, stale, off-sync, too small, low-contrast, covering faces/action/source subtitles, missing CJK glyphs, visually mismatched to the genre, or if the video only makes sense by reading labels.
+
+### `composite.assemble` — timeline, cuts, transitions, export
+
+For non-trivial videos, do not assemble a final timeline until `script.storyboard` has produced `creative_direction.md`. Timeline order should follow the story/audio arc and source roles from [`references/story-structure-audio.md`](references/story-structure-audio.md), not source-file order or arbitrary clip variety.
+
+| Provider | Kind | Requires | Cost | Quality | Offline |
+|---|---|---|---|---|---|
+| `cli-anything-kdenlive` | harness-cli | Kdenlive installed | free | high | yes |
+| `cli-anything-shotcut` | harness-cli | Shotcut installed | free | high | yes |
+| `moviepy` | python | pkg + `ffmpeg` | free | good | yes |
+| `ffmpeg-python` | python | pkg + `ffmpeg` | free | high | yes |
+| `ffmpeg concat/filter_complex` | native | `ffmpeg` | free | high | yes |
+| HyperFrames skill/CLI | agent-skill | installed `hyperframes` skill; Node.js + `ffmpeg` | free | high for digital/UI launch videos | yes |
+
+HyperFrames hard gate: for digital product launches, website/product-page videos, SaaS/app demos, UI-heavy product presentations, animated feature reels, HTML/CSS/GSAP-driven motion videos, and product videos where interface motion is the main storytelling surface, load and use the installed `hyperframes` skill as the primary `composite.assemble` authoring workflow. A "HyperFrames-style" MoviePy/Pillow/ffmpeg/browser imitation is not an acceptable substitute when this gate applies.
+
+When the HyperFrames gate applies:
+
+- Read the installed HyperFrames skill before implementation and follow its workflow.
+- Produce a real HyperFrames project/render artifact, not only a static HTML reference.
+- Prove the video topic and value proposition in the first 5-8 seconds, then follow a product arc: user problem, real UI action, feature reveal, proof, outcome, and CTA/payoff.
+- Use `ffmpeg`, MoviePy, or NLE tools only for source preparation, final muxing, caption burn-in when explicitly needed, or doctor investigation; they cannot replace HyperFrames as the main authoring surface.
+- If HyperFrames cannot run, stop and report the blocker or ask the user to change the requirement. Do not silently fall back.
+
+Use `remotion-best-practices` instead only when the user explicitly requires Remotion/React as the implementation surface.
+
+For Shotcut/Kdenlive harness workflows, use the provider-boundary pattern in [`references/nle-shotcut-kdenlive.md`](references/nle-shotcut-kdenlive.md): `ffmpeg` for stable mezzanine clips, crops, speed ramps, and text-card segments when needed; the NLE harness for project/timeline/tracks/transitions/render; then `ffmpeg` for ASS burn-in if captions are post-NLE, fps/SAR/DAR/profile/color normalization, final muxing, and doctor investigation.
+
+Assembly discipline:
+
+- Every selected shot needs a job: setup, reveal, escalation, contrast, proof, impact, or payoff.
+- For most edited pieces, introduce meaningful changes in tension, density, audio texture, title system, setting, character focus, or edit pattern often enough that the structure does not feel accidental or flat. Slow/ambient/real-time genres may justify longer holds.
+- Chapter cards and title hits must advance the story beat; they cannot be decorative separators for random clips.
+- Transitions and motion graphics need a story job. Repeated wipes, random kinetic text, and generic animations are failures when the viewer cannot tell the topic or why the transition happened.
+- Do not assume a clean mezzanine segment contains captions, chapter cards, or later overlay stages. Choose and document one caption stage before render.
+- For HyperFrames-gated genres, fail the assembly if the final render was produced by an imitation workflow instead of the installed HyperFrames skill.
+- For data, UI, charts, maps, captions, and explainers, keep the frame stable unless camera motion has a documented visual purpose. Global sinusoidal crop drift, jitter, shake, or fake handheld motion over readable data/text is a critical issue requiring revision or a documented reason.
+- After NLE render, check actual duration versus intended timeline duration, stream fps versus project fps, SAR/DAR, partial MP4 or missing moov, video coverage through the audio tail, and displayed content speed versus audio.
+- If a render is technically valid but feels like flat montage, revise `creative_direction.md` and rebuild the timeline instead of adding more filters.
+
+### `composite.overlay` — composite captions, watermark, picture-in-picture
+
+Use this to apply already-designed caption/subtitle assets, watermarks, or picture-in-picture layers. For user-visible subtitles/captions, run `text.caption` first so the overlay step receives a deliberate ASS/HTML/PNG/NLE caption package instead of an ugly default SRT.
+
+| Provider | Kind | Requires | Cost | Quality | Offline |
+|---|---|---|---|---|---|
+| `ffmpeg -vf subtitles=...` | native | `ffmpeg` | free | high | yes |
+| `moviepy` (CompositeVideoClip) | python | pkg | free | good | yes |
+
+### `package.thumbnail` — thumbnail / social card
+
+| Provider | Kind | Requires | Cost | Quality | Offline |
+|---|---|---|---|---|---|
+| `cli-anything-gimp` / `krita` / `inkscape` | harness-cli | installed | free | high | yes |
+| `Pillow` | python | pkg | free | good | yes |
+| `cairosvg` / `html2image` | python | pkg | free | good | yes |
+| OpenAI GPT-Image-1 | api | `OPENAI_API_KEY` | metered | sota | no |
+| Google Nano Banana | api | GCP creds | metered | high | no |
+| Ideogram | api | `IDEOGRAM_API_KEY` | metered | high | no |
+| Stability AI | api | `STABILITY_API_KEY` | metered | high | no |
+| `ffmpeg -ss ... -frames:v 1` | native | `ffmpeg` | free | basic | yes |
+| `convert` / `magick` | native | ImageMagick | free | good | yes |
+
+### `package.encode` — final mux, codec, container
+
+| Provider | Kind | Requires | Cost | Quality | Offline |
+|---|---|---|---|---|---|
+| `ffmpeg` | native | binary | free | sota | yes |
+
+### `quality.review` — technical and editorial investigation before delivery
+
+Run this after every render and before presenting a final file. The goal is not a binary test suite; it is an evidence-gathering pass that helps the agent inspect the exact file, understand suspicious signals, and make a contextual editorial decision.
+
+| Provider | Kind | Requires | Cost | Quality | Offline |
+|---|---|---|---|---|---|
+| `ffmpeg` / `ffprobe` investigation filters | native | `ffmpeg` + `ffprobe` | free | high | yes |
+| MediaInfo CLI | native | `mediainfo` | free | high | yes |
+| `ffmpeg-quality-metrics` / VMAF | public-cli | `ffmpeg-quality-metrics` + `ffmpeg` | free | high with reference | yes |
+| Video doctor helper | bundled-script | `scripts/video_doctor.py` + `ffmpeg`/`ffprobe` | free | high for investigation | yes |
+
+Investigation checks:
+
+- Use `scripts/video_doctor.py` to produce probe, caption, source, frame, tail, audio, and lint reports. Doctor reports are evidence and investigation signals, not pass/fail verdicts.
+- Compare final duration against the user brief and `creative_direction.md`; if it differs, inspect whether the plan or final render is wrong before promotion.
+- Verify the final viewer-facing language against the output-language rule: narration, authored captions, title cards, charts, labels, and CTAs must use the requested language, or the conversation language when no language was specified.
+- FFmpeg filters: `blackdetect`, `silencedetect`, `freezedetect`, `cropdetect`, `ebur128` / `loudnorm`.
+- Extract first/mid/last frames, 2s contact sheets, subtitle-heavy frames, and final-10s tail sheets; inspect visually or via OCR for text overflow, watermarks, black frames, wrong crops, frozen tails, wrong-speed tails, and audio-only tails.
+- For narration videos, run the caption doctor against the narration audio and media dimensions; inspect signals about caption role, voice alignment, planned language coverage, captions extending beyond narration, mismatched ASS PlayRes, small effective font size, generic styling, or source-subtitle collision risk.
+- For generated or heavily processed audio, run `scripts/video_doctor.py audio` with `--scan-path` on the task directory, listen to exported snippets, and review high-frequency/low-frequency/loudness signals. `silencedetect` and `volumedetect` passing does not mean the mix is listenable.
+- When source audio is used, also pass `--sources-manifest`, `--music-manifest`, and `--sound-design` to the audio doctor so it can flag missing audio roles and export snippets around source-audio/new-music/new-narration overlap windows.
+- For data/UI/chart sections, inspect short frame strips around animation segments for unintended global shake or drifting crops.
+- Use VMAF/SSIM/PSNR only when a reference video exists; they are not general no-reference quality checks.
+- For non-trivial videos, run the story/audio review rubric in [`references/story-structure-audio.md`](references/story-structure-audio.md): premise clarity, escalation, turning point, high point, source roles, music sections, audio events, and final payoff.
+- For polished videos, run the art-direction gates in [`references/art-direction-review.md`](references/art-direction-review.md): aesthetics, captions-muted readability, final-act payoff/hook/resolve, justified card time, sparse labels, synchronized audio hits, and intentional shot repetition.
+- For HyperFrames or other linter-based motion workflows, run `scripts/video_doctor.py lint` on lint logs and record whether warnings were fixed, accepted with reason, or left as blockers.
+- For every promoted final, follow [`references/render-doctor.md`](references/render-doctor.md): hash the candidate/default, regenerate frames from the promoted path, update reports, and scan reports for stale paths or superseded source names.
+
+The bundled helper is `scripts/video_doctor.py`. It has subcommands for `probe`, `captions`, `sources`, `frames`, `tail`, `audio`, and `lint`; agents must read the generated signals and then inspect the referenced evidence.
+
+### `publish.upload` — deliver to a platform
+
+Currently a **known gap** (see below). Agents should surface this to the user.
+
+---
+
+## Recipes
+
+Recipes declare *which capabilities a workflow needs* — not the order. Choose providers per capability from the task constraints and preflight facts.
+
+- **`ai-short`** — fully-generative social short.
+  Uses: `script.storyboard`, `visual.generate`, `audio.synthesize`, `music.generate` or `music.search` / `music.download`, `sound.design` for trailer/social impact edits, `text.caption` when captions/title hits are part of the brief, `composite.assemble`, `composite.overlay`, `package.thumbnail`, `quality.review`, `package.encode`.
+
+- **`screencast-tutorial`** — walkthrough with narration + subs.
+  Uses: `script.storyboard`, `visual.capture`, `audio.capture`, `text.transcribe`, `text.caption`, `composite.overlay`, `package.thumbnail`, `quality.review`, `package.encode`.
+
+- **`talking-head-explainer`** — webcam + b-roll + captions.
+  Uses: `script.storyboard`, `visual.capture`, `video.search` / `video.download` or `visual.generate` (b-roll), `music.search` / `music.download` or `music.generate`, `sound.design` when chapter changes or emphasis hits matter, `media.analyze`, `audio.capture`, `text.transcribe`, `text.caption`, `composite.assemble`, `composite.overlay`, `package.thumbnail`, `quality.review`, `package.encode`.
+
+- **`podcast-to-video`** — audio-first, visualize + caption.
+  Uses: `script.storyboard`, `audio.capture`, `text.transcribe`, `text.caption`, `package.thumbnail`, `composite.overlay`, `composite.assemble`, `quality.review`, `package.encode`.
+
+- **`found-footage-montage`** — source internet clips, curate, then edit.
+  Uses: `script.storyboard`, `video.search`, `video.download`, `media.analyze`, `sound.design`, `text.transcribe` (optional), `text.caption` when captions/title hits are part of the edit, `composite.assemble`, `composite.overlay`, `package.thumbnail`, `quality.review`, `package.encode`.
+
+- **`existing-song-music-video`** — build an edit around a user-specified or discovered song.
+  Uses: `music.search`, `music.download`, `script.storyboard`, `video.search`, `video.download`, `media.analyze`, `sound.design` for hits/source accents that do not fight the song, `text.caption` (optional lyrics/karaoke), `composite.assemble`, `composite.overlay`, `package.thumbnail`, `quality.review`, `package.encode`.
+
+- **`digital-product-launch`** — product/site-driven launch video with animated UI, typography, and motion graphics.
+  Uses: `script.storyboard`, `visual.capture`, `audio.synthesize` (optional), `music.generate` or `music.search` / `music.download`, `sound.design` for launches with cue hits or section shifts, `text.caption` for brand-safe kinetic captions/title hits, `composite.assemble` via mandatory installed HyperFrames skill, `composite.overlay`, `package.thumbnail`, `package.encode`, `quality.review`.
+
+---
+
+## Known gaps
+
+- **`publish.upload`** — no first-party or public CLI for YouTube/TikTok/Bilibili/Instagram yet. *Workaround:* instruct the user to upload manually via the web UI, or escalate to a custom script using each platform's v3 API with an OAuth token the user supplies.
+- **`visual.generate` — top-tier "cinematic"** — available only via paid APIs (Runway, Kling, Seedance); local GPU/weights deployment is intentionally not part of this matrix.
+- **`rights.provenance`** — no automated license/TOS/provenance verifier. *Workaround:* save `sources.json` / `music_sources.json` with URL, creator, license, intended use, attribution text, transport evidence, and quality caveats; ask the user before using unclear or restricted media. Use [`references/source-triage.md`](references/source-triage.md) for evidence levels.
+- **`agent-skill.preflight`** — external agent skills may appear in this matrix before they are installed locally. *Workaround:* use the source/install table below and load the external `SKILL.md` only when that workflow is actually needed.
+
+---
+
+## Reference modules, external skills, and tool sources
+
+Consult these only when the task needs the focused workflow; keep this matrix as the router and load the reference, external skill, or tool only if its workflow matches.
+
+| Reference/tool | Use when | Source or install |
+|---|---|---|
+| `advanced-video-downloader` | User supplies YouTube/Bilibili/TikTok/etc. URLs and needs download, playlist handling, music/audio extraction, cookies, or transcription | `npx skills add https://github.com/jst-well-dan/skill-box --skill advanced-video-downloader` |
+| `music-downloader` | Need to find/download real music, BGM, soundtrack cues, platform audio, or authorized music rather than faking a full music bed procedurally | `npx skills add https://github.com/nymbo/skills --skill music-downloader` |
+| `references/story-structure-audio.md` | Non-trivial video needs a global arc, internal logic, source roles, story ups/downs, music/audio sections, or flat-montage prevention | Local reference module: [`references/story-structure-audio.md`](references/story-structure-audio.md) |
+| `references/captions.md` | Any polished visible captions, subtitles, lyrics, karaoke, lower thirds, trailer title hits, or caption investigation | Local reference module: [`references/captions.md`](references/captions.md) |
+| `references/source-triage.md` | Found-footage source selection, platform-origin evidence, rights/provenance fields, source rejection, and contact-sheet requirements | Local reference module: [`references/source-triage.md`](references/source-triage.md) |
+| `references/nle-shotcut-kdenlive.md` | Shotcut/Kdenlive timeline work, provider boundaries, mezzanine conventions, render resilience, and known NLE failure modes | Local reference module: [`references/nle-shotcut-kdenlive.md`](references/nle-shotcut-kdenlive.md) |
+| `references/sound-design.md` | Trailer hits, risers, sports accents, commentary mix changes, final-act audio shape, and section loudness review | Local reference module: [`references/sound-design.md`](references/sound-design.md) |
+| `references/art-direction-review.md` | Genre-specific naive-output traps, contact-sheet review, captions-muted review, and art gates before promotion | Local reference module: [`references/art-direction-review.md`](references/art-direction-review.md) |
+| `references/render-doctor.md` | Final-path doctor workflow, probe/frame/tail/caption/source investigation, promotion discipline, and stale-report checks | Local reference module: [`references/render-doctor.md`](references/render-doctor.md) |
+| `scripts/video_doctor.py` | Non-binary investigation helper for media facts, review frames, tail signals, sources, captions, audio listenability signals, and procedural-audio evidence | Local script: [`scripts/video_doctor.py`](scripts/video_doctor.py) |
+| `storyboard-creation` | Need shot grammar, camera angles, storyboard panels, continuity, or animatic planning | `pnpm dlx add-skill https://github.com/inference-sh/skills/tree/HEAD/guides/video/storyboard-creation` |
+| `remotion-best-practices` | Need to implement the storyboard as Remotion code | `npx skills add https://github.com/remotion-dev/skills --skill remotion-best-practices`; SKILL.md: <https://github.com/remotion-dev/skills/blob/main/skills/remotion/SKILL.md> |
+| `hyperframes` | Mandatory for website/product-page videos, digital product launches, SaaS/app demos, UI-heavy product presentations, animated feature reels, and whole-video HTML/CSS/GSAP motion compositions | Installed local skill. If missing in a future environment, install it with `npx skills add heygen-com/hyperframes --skill hyperframes`; do not substitute another renderer when this skill is mandatory. Captions reference: <https://skills.sh/heygen-com/hyperframes/captions> |
+| `ffmpeg-quality-metrics` | Need VMAF/SSIM/PSNR against a reference video | `pipx install ffmpeg-quality-metrics`; source: <https://github.com/slhck/ffmpeg-quality-metrics> |
+
+---
+
+## Agent guidance
+
+- **Run the preflight block once**, then consult the cached result when picking providers.
+- **For non-trivial videos, start with `creative_direction.md`.** Use the story/audio reference module to define the whole arc before acquisition and assembly: premise, emotional curve, audio arc, cut-density curve, source roles, turning point, climax, and payoff.
+- **Language rule:** if the user specifies a video language, use it. Otherwise use the conversation language for all agent-authored narration, captions, titles, labels, and CTAs; source-language text must be translated, avoided, or explained when it matters.
+- **For internet footage, run `video.search` before `video.download`** unless the user already supplied URLs. Keep provenance metadata with every source file.
+- **For found-footage edits, build `scene_library.json` before cutting.** Use source triage and contact sheets to reject weak, static, card-heavy, subtitle-dominated, or off-theme footage.
+- **For existing music, run `music.search` before `music.download`** unless the user already supplied a URL/local file. Verify the song version and listen for dialogue/SFX bleed before beat analysis or editing.
+- **For polished music beds, prefer real music.** Use AI-generated music or downloaded relevant/authorized music as the main bed unless the brief calls for ambient/source-audio-led work. Procedural audio is for SFX/accent stems, not a cheap replacement for a full soundtrack.
+- **For high-energy edits, run `sound.design` as a separate pass.** A music bed alone is not a designed mix; create cue times, stems, ducking notes, and section loudness targets.
+- **For visible captions, use `text.caption` as its own design pass.** Do not hand off raw SRT to `composite.overlay` and call it done. Use the captions reference module for genre style, grouping, safe placement, font/glyph checks, hard exits, and caption-heavy preview frames.
+- **For narrated work, captions must follow the voice.** Generate or align subtitles from the final narration/audio, then run `scripts/video_doctor.py captions` against the exact final dimensions and narration file. Read the doctor signals and inspect frames/audio before deciding what to revise. Summary captions belong in a separate title/callout style.
+- **For subtitle/caption localization, translate directly as agent work** unless the user explicitly requires a specific translation service, offline translation, or human/legal review. Preserve timestamps, maintain names/terms consistently, and verify CJK glyph rendering in overlays.
+- **For non-trivial work, do `script.storyboard` before acquisition/generation**, usually as agent-native planning. Load an external storyboard skill only when its focused format is worth the extra install/context. Do not replace the global story/audio plan with a list of clips.
+- **For digital product/site/app launch videos, use HyperFrames under `composite.assemble`.** When the genre is a UI-heavy product launch, SaaS/app demo, product presentation, animated feature reel, or whole-video HTML/CSS/GSAP composition, HyperFrames is mandatory. Do not use MoviePy/Pillow/ffmpeg, a static HTML mock, or a "HyperFrames-style" imitation as the primary authoring surface.
+- **Using the right tool is not enough.** The final must still satisfy brief compliance, topic clarity, duration, story arc, caption sync, audio listenability, and stable-motion review.
+- **For final audio, listen and run the audio doctor.** Use `scripts/video_doctor.py audio <final> <qc/audio> --scan-path <task-dir>` for polished edits, then inspect the snippets. A technically valid track can still fail if it sounds like hiss, test tones, synthetic pulse wallpaper, or repeated boom hits.
+- **Use Remotion guidance only for code-driven motion graphics.** Do not install it for ordinary cuts, overlays, or NLE work.
+- **Choose Shotcut, Kdenlive, MoviePy, or raw `ffmpeg` by edit complexity and availability.** NLE harnesses fit timeline-heavy edits; MoviePy/ffmpeg fit deterministic programmatic cuts and overlays.
+- **When using Shotcut/Kdenlive, keep provider boundaries explicit.** Preprocess stable mezzanine/source clips with `ffmpeg`, author the timeline in the NLE, then use `ffmpeg` for post-NLE captions, muxing, normalization, and doctor evidence as needed.
+- **Prefer `--json`** for harness CLI output when chaining tools.
+- **Promote only verified final paths.** Probe the exact file being delivered, regenerate review frames from it, hash it, and make reports refer to that same path.
+- **Doctor helpers are not verdicts.** A clean doctor report can still hide an editorial failure, and a strong doctor signal can be acceptable with context. Read the evidence and document the judgment.
+- **Independent review must seek defects.** A review that only repeats ffprobe/black/freeze/silence checks is incomplete; it must cite visual/caption/audio/story risks from exact-final evidence before giving a verdict.
+- **Escalate explicitly.** When a paid API would materially improve quality, use the suggest-to-user template. Do not silently burn credits.
+- **Recipes ≠ order.** A recipe says what's needed; pick a sensible order for the specific task. Most videos should transcribe *after* the final cut, not before; screencasts often capture audio + video simultaneously.
+- **Workspace discipline.** Keep all intermediate assets under one directory so cross-tool references stay stable.
diff --git a/cli-hub-matrix/video-creation/references/art-direction-review.md b/cli-hub-matrix/video-creation/references/art-direction-review.md
new file mode 100644
index 000000000..068c763d9
--- /dev/null
+++ b/cli-hub-matrix/video-creation/references/art-direction-review.md
@@ -0,0 +1,92 @@
+# Art Direction Review
+
+Use this when a video can be technically valid but still feel naive, flat, over-labeled, or assembled from unrelated clips. This is mandatory for high-quality trailers, sports/music montages, film commentary, found-footage edits, and final deliverables after human critique.
+
+## Review Assets
+
+Generate review frames from the exact final path:
+
+- First 10 seconds contact sheet.
+- Every-2-seconds contact sheet.
+- Dense final-act sheet. The default final-act sample can be the last 20%, but judge it as an ending/payoff sample, not a fixed rule.
+- Caption-heavy sheet.
+- First, middle, and last single frames.
+
+Then review in three passes:
+
+1. Normal pass: does it feel intentional without reading reports?
+2. Captions-muted pass: does story and emotion still read without labels?
+3. No-text mental pass: if title cards and labels vanished, would the edit still have visual cause/effect?
+4. Brief-compliance pass: does the final duration, topic, tool choice, language, and genre match the user request and `creative_direction.md`?
+5. Aesthetic pass (`美学&审美`): do composition, typography, color, motion rhythm, and restraint feel designed for the genre rather than default, random, or template-like?
+
+## Aesthetic Bar
+
+- Composition has hierarchy: the eye knows what to read/watch first, second, and third.
+- Typography is intentional: font, size, weight, line breaks, and caption plates match the genre.
+- Motion has taste: every zoom, shake, wipe, reveal, or bounce has a story or rhythm purpose.
+- Color and contrast are controlled; avoid one-note palettes, muddy overlays, and default black-outline subtitles.
+- Repetition is either a callback/motif or removed. Similar frames across a contact sheet are a warning, not proof of stability.
+- A technically valid render that looks naive, generic, or confusing is a failed creative review.
+
+## Genre Failure Modes
+
+Sports hype:
+
+- Stock-montage feel with no athlete pressure or emotional stakes.
+- Odd color grade that makes real footage look artificial.
+- Source ranking/countdown cards, platform UI, or low-quality inserts that distract from the sports moment.
+- Final moment lacks a signature impact.
+
+Film commentary:
+
+- Generic recap instead of an argument or interpretive arc.
+- Source order dictates the video rather than the thesis.
+- Opening caption/hook is truncated or too late.
+- Cards replace narration structure instead of supporting it.
+
+Sci-fi/game/mecha trailer:
+
+- Too many title cards, chapter cards, or HUD/debug labels.
+- No continuity of protagonist, threat, or objective.
+- Reused setup/dialogue shots that feel accidental.
+- Final image is not cinematic or memorable.
+- Labels explain stakes that the edit never visualizes.
+
+Digital/product launch:
+
+- Decorative kinetic text hides the actual product.
+- UI states are too cropped, blurry, or fast to inspect.
+- Sound hits and visual changes are unsynchronized.
+- The product/topic is not clear in the first 5-8 seconds.
+- The edit is a sequence of generic animations instead of a product arc: problem, real UI action, feature reveal, proof, outcome, CTA.
+- Repeated wipes/transitions happen without story function.
+
+Data/news/science explainer:
+
+- Global shake, crop drift, fake handheld motion, or jitter moves charts, maps, labels, or subtitles.
+- Chart text is too small to read at final resolution.
+- Debug-like labels remain visible, such as renderer/composition labels that are not intended for the viewer.
+- Footage, charts, and narration do not explain each other.
+
+## Art Gates Before Promotion
+
+Fail or revise if:
+
+- The final duration is outside the requested range or materially different from the plan without approval.
+- The ending/final act is not a climax, payoff, useful recap, hook, or deliberate unresolved ending appropriate to the genre.
+- Title cards consume more than roughly 15% of runtime unless the genre explicitly needs more.
+- Labels appear so often that the output reads like a storyboard, debug overlay, or pitch deck.
+- Repeated shots are not deliberate callbacks.
+- Important action is hidden by captions, source subtitles, watermarks, or cards.
+- Voice captions do not match the spoken narration.
+- Data/UI/chart/caption sections shake or drift without a deliberate, documented reason.
+- Audio has no section changes or visible hit synchronization.
+- The last frame is black, throwaway, or unrelated to the promised premise.
+- The independent review cannot name real weaknesses or residual risks from exact-final frames, captions, audio, or story structure.
+
+## Response To Review Defects
+
+When a human or fresh-context reviewer flags a visible defect, reproduce it with screenshots or contact sheets before editing reports. Treat "technically passes but feels naive" as a real failure: revise `creative_direction.md`, scene selection, sound design, or timeline structure instead of adding more labels and effects.
+
+Independent review stance: review to find defects first. A PASS is acceptable only after listing the strongest risks checked, the evidence inspected, and why those risks are tolerable for the brief.
diff --git a/cli-hub-matrix/video-creation/references/captions.md b/cli-hub-matrix/video-creation/references/captions.md
new file mode 100644
index 000000000..5c0d439d7
--- /dev/null
+++ b/cli-hub-matrix/video-creation/references/captions.md
@@ -0,0 +1,206 @@
+# Video Captions
+
+Use this reference when captions are part of the viewer-facing video design, not just an accessibility sidecar. In the video-creation matrix, it sits after `text.transcribe` or agent-written script work and before `composite.overlay`, `package.encode`, and `quality.review`.
+
+Default subtitle output is not acceptable for polished videos. Captions must feel designed for the video genre, synchronized to the edit, readable on the target platform, and visually integrated with the footage.
+
+## Workflow
+
+1. **Define the caption job.** Record aspect ratio, delivery platform, language(s), transcript source, whether word timings are available, and caption role: accessibility subtitles, creator captions, film commentary, trailer title hits, lyrics/karaoke, tutorial labels, or product launch typography.
+2. **Build a clean timed source.** Produce `captions.source.json` with text, start, end, optional words, speaker, role, and emphasis. Use `.srt` only as an interchange format; keep JSON/ASS as the design source of truth. If a narration track exists, build narration subtitles from the narration audio/transcript or ASR/forced alignment, not from hand-timed story summaries.
+3. **Select a style preset.** Pick from the genre presets below, then adapt to the footage palette, subject position, and music/edit energy. Do not use generic white text with a black stroke unless the user explicitly asks for plain subtitles.
+4. **Design safe placement.** Extract representative frames for caption-heavy moments, mark face/action/logo/source-subtitle regions, and choose one or two safe zones. Captions must not cover faces, important action, hardcoded subtitles, UI controls, or source watermarks.
+5. **Render with the right authoring path.** Use ASS+ffmpeg for deterministic subtitles, the installed HyperFrames skill for kinetic captions inside HyperFrames-gated digital/UI videos, NLE overlay tracks for timeline-heavy edits, or transparent PNG/MoviePy overlays only when custom layout is necessary and no mandatory authoring provider applies.
+6. **Investigate before delivery.** Save `captions_doctor.json`, a caption review note, and preview frames/contact sheets. Use the doctor signals to decide what to inspect next; do not treat the helper as a binary verdict.
+
+## Transcript Rules
+
+- Never use Whisper `.en` models unless the user explicitly says the audio is English. `.en` models translate non-English audio into English instead of transcribing it.
+- Treat prompt language and deliverable language as separate fields. If the user specifies a video language, use it for all authored subtitles, title cards, callouts, and narrator captions. If no output language is specified, use the language the user is using in the conversation.
+- If the user gives a script, time captions against the final narration/audio, not against the draft text.
+- When using TTS, keep the generated audio and any word/subtitle sidecar. If the TTS provider cannot emit word timings, run ASR/forced alignment on the final narration file before treating the captions as subtitles.
+- Summary captions, chapter labels, and data callouts must use separate roles/styles from narration subtitles. They may support the edit, but they do not satisfy a "subtitles must match the voice" requirement.
+- If translating/localizing captions, do the translation as agent work unless the user requires a specific service. Preserve timestamps, names, terms, tone, and line breaks; then review glyph rendering.
+- Keep one caption group visible at a time for spoken captions. Trailer title hits and lower thirds may coexist only if they occupy distinct zones and do not compete for reading priority.
+- Break groups on sentence boundaries, semantic phrases, beat hits, or pauses longer than about 150 ms.
+
+## Design Recipe
+
+Use this before writing ASS/HTML styles; do not leave default subtitle styling in a polished final.
+
+- Pick an intentional font: `Inter`, `Aptos`, `IBM Plex Sans`, `Source Sans 3`, or a brand font for Latin; `Noto Sans CJK` / Source Han Sans for CJK. `Arial`/`DejaVu Sans` are fallback fonts, not a design choice unless documented.
+- Use two to four named styles: `Narration`, `Keyword`, `Chapter`, `SourceTranslation`, `DataLabel`. Avoid one anonymous `Caption` style for everything.
+- Spoken captions should be readable but not oversized: roughly 38-52 px at 720p, 48-76 px at 1080p, and larger for vertical social. Title hits can be larger.
+- Prefer a subtle translucent plate, soft shadow, or tuned glow over a thick default black outline. Match the plate radius/opacity to the genre: quiet documentary plates, sharp product chips, bold social bars, cinematic thin accents.
+- Group text by meaning, not by raw subtitle chunks. Aim for 3-8 words per group for kinetic/social/product captions, or one short semantic phrase per line for documentary narration.
+- Add hierarchy: one accent color for names, numbers, verbs, or product terms; keep body text neutral. Do not rainbow-highlight every word.
+- Place captions where the image has negative space. Recheck first/middle/last caption-heavy frames after burn-in; move, crop, or replace source ranges if captions fight faces, UI, source subtitles, or watermarks.
+- Motion should have a job: reveal a keyword, land on a beat, follow a cursor/action, or mark a chapter. Random bounce/typewriter effects usually make captions look cheap.
+
+ASS static-caption starter patterns:
+
+```text
+Narration: clean font, 44-58px at 1080p equivalent, BorderStyle=3 translucent back plate, Outline=0-1, Shadow=0-2, Alignment=2/8 based on safe zone.
+Keyword: same family, bold, one accent color, short duration, placed near the base caption or relevant object.
+Chapter: larger display weight, no paragraph text, appears only at real story turns.
+```
+
+## Deliverables
+
+Every captioned video should keep these files near the render:
+
+- `captions.source.json` — timed text source with role/emphasis metadata.
+- `captions_style.md` — selected preset, font, palette, placement, animation, and deviations.
+- `captions.ass` or equivalent render source; optionally `captions.srt` for accessibility/export.
+- `captions_preview_frames/` or `review_frames/` — first/middle/last and caption-dense samples.
+- `captions_doctor.json` — output from `scripts/video_doctor.py captions`.
+- `captions_review.md` — readability, sync, overflow, safe-zone, font, style review, final resolution, narration duration when relevant, source-subtitle collision notes, and how doctor signals were interpreted.
+
+## Style Presets
+
+### Sports Hype / Music Montage
+
+- **Use for:** dunk reels, football/soccer hype, workout edits, esports frag montages.
+- **Text density:** 1-3 words per hit; avoid paragraph subtitles.
+- **Typography:** heavy condensed sans, 800-900 weight; CJK needs a bold high-legibility font such as Noto Sans CJK/Source Han Sans.
+- **Look:** dark or neutral caption plate, one aggressive accent, subtle glow or shadow, no thick default outline.
+- **Motion:** beat-locked slam, scale-pop, wipe, quick flash, or kinetic word replacement. Use fast exits and hard kills.
+- **Placement:** lower third for readable captions; center or upper-center only for short title hits between action beats.
+
+### Film Commentary / Recap
+
+- **Use for:** movie explanation, anime recap, documentary narration, story analysis.
+- **Text density:** 6-14 Chinese characters per line or 28-40 Latin characters per line; max two lines.
+- **Typography:** elegant sans or restrained serif for chapter cards; normal captions should stay highly readable.
+- **Look:** cinematic neutral/warm palette, soft shadow, thin accent line or small chapter label, no loud bouncing.
+- **Motion:** gentle fade/slide for narration; stronger title cards only at chapter boundaries.
+- **Placement:** bottom safe zone unless source subtitles or important faces occupy it; use upper safe zone only when necessary.
+
+### Sci-Fi / Game / Mecha Trailer
+
+- **Use for:** CG trailers, game launch edits, anime/mecha/sci-fi hype.
+- **Text density:** short bilingual title hits, faction labels, mission-style captions, 2-4 word bursts.
+- **Typography:** square/tech sans, condensed bold, or clean mono for data-like labels; keep letter spacing at 0 for body captions.
+- **Look:** high-contrast white/near-white plus one neon accent; restrained glow, scanline, bracket, or HUD framing.
+- **Motion:** glitch, scan reveal, mask wipe, chromatic nudge, or hard cut on impact. Avoid random particles and cheap typewriter spam.
+- **Placement:** title hits can use center frame during low-action beats; subtitles stay bottom/side safe and never cover spectacle.
+
+### Product / Digital Launch
+
+- **Use for:** website-to-video, app demos, SaaS launches, Remotion/HyperFrames motion pieces.
+- **Text density:** short product claims, feature labels, metric callouts, step captions.
+- **Typography:** match `design.md` or product brand fonts. If missing, use a modern sans with consistent weights.
+- **Look:** brand palette, clean contrast, precise spacing, polished cards/chips only when the product UI style supports them.
+- **Motion:** layout-first kinetic type, marker sweeps, reveal masks, scroll/pointer sync, audio-reactive emphasis if it supports the beat.
+- **Implementation:** HyperFrames is mandatory when the video is a product/site/app launch, UI-heavy presentation, animated feature reel, or whole-video HTML/CSS/GSAP motion composition. Use the installed `hyperframes` skill and read its captions guidance before authoring kinetic synced text; do not substitute plain HTML capture, MoviePy/Pillow, ffmpeg filters, or NLE-only captions when this gate applies.
+
+### Tutorial / Explainer
+
+- **Use for:** screencasts, app walkthroughs, educational clips, code demos.
+- **Text density:** clear phrases; prefer fewer captions when screen text already carries meaning.
+- **Typography:** clean sans; mono only for code terms. Use exact UI labels and command names.
+- **Look:** quiet, high contrast, no decorative motion that distracts from the action.
+- **Motion:** quick fade/slide, pointer-aligned callouts, occasional highlight boxes.
+- **Placement:** avoid covering cursor targets, terminal prompts, menus, code, or UI labels.
+
+### Lyrics / Karaoke
+
+- **Use for:** music videos, lyric edits, singalong, rhythm shorts.
+- **Text density:** phrase or word-level timing; lyrics should follow musical phrasing, not sentence grammar.
+- **Typography:** genre-matched display font for hooks, readable sans for verses.
+- **Look:** one active-word treatment plus one base caption style. Avoid rainbow karaoke unless the user asks for it.
+- **Motion:** per-word color fill, underline sweep, scale emphasis, or mask reveal. Keep sync tighter than normal speech captions.
+- **Placement:** bottom or center-lower; make sure fast cuts do not leave stale lyrics from the previous phrase.
+
+### Vertical Social / Talking Head
+
+- **Use for:** shorts, Reels, TikTok-style hooks, selfie explainers.
+- **Text density:** 2-5 words per group; emphasize hooks, numbers, names, and claims.
+- **Typography:** bold rounded or bold grotesk, large enough for phone viewing.
+- **Look:** strong foreground/background contrast, restrained pill/plate, one accent color for keywords.
+- **Motion:** pop/slide per group, occasional keyword bounce; avoid constant elastic motion.
+- **Placement:** lower-middle or mid-lower safe zone, but never over mouth/face. Leave platform UI margins.
+
+## Typography And Layout
+
+- Size for final pixels, not editor preview. For 16:9 1080p, spoken captions usually land around 48-76 px; hype/title hits can be 80-130 px. For vertical 1080x1920, spoken groups usually need 64-104 px.
+- For 720p landscape, spoken captions below about 36 px are usually too small unless the delivery context is large-screen only and review frames prove readability.
+- Set ASS `PlayResX` and `PlayResY` to the actual final render resolution. If you author at 1920x1080 and deliver 1280x720, resize the style values or prove the effective font size remains readable.
+- Use max width: about 70-82% of landscape width, 78-88% of portrait width. Reduce width further when words scale above 1.0.
+- Set explicit line height around 1.05-1.18. Do not rely on default browser or ASS line spacing.
+- Use real safe margins: at least 5% from frame edges, more for vertical social platform UI.
+- Verify fonts render all glyphs. CJK tofu boxes, missing punctuation, broken emoji, or fallback font jumps are critical issues to revise or justify.
+- Prefer shadow, blur, backing plate, or glow tuned to the footage over a thick black outline. If using ASS outlines, keep them intentional and proportional.
+- Keep body caption letter spacing at 0. Avoid negative tracking. Display title cards may use deliberate tracking only if it improves the genre look.
+
+## Source Subtitle Collisions
+
+Found footage often contains hardcoded subtitles, tickers, logos, and broadcast lower thirds. Before burn-in, review caption-heavy frames and mark occupied zones.
+
+- Prefer upper/side safe zones when the source already uses bottom subtitles.
+- Crop, blur, or mask nonessential source subtitles only when it does not harm the footage.
+- Replace ranges where source text makes authored subtitles unreadable.
+- Do not stack authored narration subtitles over source-language subtitles and call the result complete.
+
+## Authoring Paths
+
+### ASS + FFmpeg
+
+Use when the final output is normal edited footage and captions need deterministic burn-in.
+
+```bash
+ffmpeg -i input.mp4 -vf "subtitles=captions.ass:fontsdir=fonts" -c:a copy output_captioned.mp4
+```
+
+ASS is the preferred interchange for styled subtitles because it supports font, size, outline, shadow, position, and per-event timing. Keep `captions.ass` readable and style-named (`Narration`, `Keyword`, `Chapter`, `LyricActive`) instead of generating anonymous styles.
+
+### HyperFrames / HTML Captions
+
+Use when captions are part of a digital motion composition, product launch, audio-reactive typography, karaoke, or per-word kinetic text system.
+
+- Install/load only when the workflow needs it: `npx skills add heygen-com/hyperframes --skill hyperframes`.
+- Build end-state layout first, then animate into/out of that layout.
+- Use deterministic timelines, no random/time-based logic, and no infinite repeats.
+- Use fit-to-width logic for dynamic text and a hard timeline kill at each group end so old captions cannot remain visible.
+
+### NLE Overlay Tracks
+
+Use Shotcut/Kdenlive when the whole edit already lives in an NLE timeline. For complex captions, pre-render transparent overlays or ASS-burned intermediate clips, then bring them into the NLE to avoid fragile text filter behavior.
+
+### Python / MoviePy / Pillow
+
+Use only when the project already uses a Python render path and needs custom layout that ASS cannot express. Render transparent text layers at final resolution, inspect frames, and avoid rebuilding a low-end subtitle engine from scratch.
+
+## Doctor Review
+
+Run the caption doctor to gather evidence, then inspect the relevant frames and audio. These signals usually require revision or a written justification:
+
+- Captions feel like generic subtitles pasted on top of the video.
+- Voice captions use a default-looking font/style with no genre fit, hierarchy, safe-zone reasoning, or caption-heavy frame review.
+- Any caption is clipped, outside safe margins, too small on the target platform, or unreadable against the footage.
+- Captions cover faces, important action, source subtitles, UI controls, or watermarks without a documented reason.
+- Text lingers past its end time, overlaps the next caption group unintentionally, or appears before the spoken line.
+- Voice captions are hand-timed story summaries instead of timed narration text.
+- Voice-caption coverage extends far beyond the narration audio, or leaves large narrated sections without subtitles.
+- The planned caption role is narrative coverage, but the final has a large unreviewed gap between authored narration/caption coverage and media duration.
+- ASS PlayRes does not match the final video and the effective font size is too small.
+- CJK/Latin font fallback is inconsistent, missing glyphs appear, or punctuation wraps badly.
+- Style conflicts with genre: bouncy social captions on serious film commentary, plain subtitles on a hype montage, loud karaoke on a tutorial, etc.
+- The final render was delivered without caption-heavy sample frames or a written caption review note.
+
+Minimum investigation steps:
+
+```bash
+mkdir -p caption_review_frames
+python cli-hub-matrix/video-creation/scripts/video_doctor.py captions captions.ass \
+  --media final.mp4 \
+  --narration narration.mp3 \
+  --output-language "<brief-or-conversation-language>" \
+  --json > captions_doctor.json
+python cli-hub-matrix/video-creation/scripts/video_doctor.py frames final.mp4 caption_review_frames \
+  --json > caption_review_frames/frames_doctor.json
+```
+
+Also extract exact frames around first caption, densest caption section, last caption, and any style transition. Inspect them visually before calling the video done.
+
+If the brief expects narration or intertitles to carry the full story, add `--expect-authored-coverage` so the doctor emits coverage-gap signals. Do not write "caption doctor passed." Write what signals appeared, which frames/audio were inspected, and why the final caption treatment is acceptable or what was revised.
diff --git a/cli-hub-matrix/video-creation/references/nle-shotcut-kdenlive.md b/cli-hub-matrix/video-creation/references/nle-shotcut-kdenlive.md
new file mode 100644
index 000000000..003caaa88
--- /dev/null
+++ b/cli-hub-matrix/video-creation/references/nle-shotcut-kdenlive.md
@@ -0,0 +1,82 @@
+# Shotcut And Kdenlive NLE Workflow
+
+Use this when an edit benefits from a real timeline: multiple tracks, transitions, reusable project files, source crops, long audio beds, or harness-controlled NLE rendering.
+
+## When To Choose An NLE
+
+Prefer Shotcut or Kdenlive when:
+
+- The timeline has many clips, transitions, or layered tracks.
+- The user may want a project file they can reopen.
+- Manual review or future editability matters.
+- MoviePy/ffmpeg filtergraphs are becoming brittle.
+
+Prefer MoviePy or raw `ffmpeg` when:
+
+- The edit is deterministic and simple.
+- The task is mostly concat, burn-in, resize, trim, mux, or thumbnail extraction.
+- The environment cannot run long NLE jobs reliably.
+
+## Provider Boundary Pattern
+
+Use a clear boundary between tools:
+
+1. `ffmpeg`: create stable mezzanine clips, source crops, speed-ramp snippets, and title-card video segments when NLE text filters are risky.
+2. NLE harness: create the project, import media, arrange tracks, add transitions/filters, and render a master.
+3. `ffmpeg`: burn ASS captions if the caption pass is post-NLE, normalize fps/SAR/DAR/profile/color tags, mux final audio, and run doctor investigation.
+
+Do not assume a clean mezzanine segment contains later captions, chapter cards, watermarks, or overlays. Choose one caption stage and document it before rendering.
+
+## Mezzanine Conventions
+
+Use boring, stable clip properties:
+
+- Constant frame rate matching the final project, usually 24, 25, 30, or 60 fps.
+- `yuv420p`, square pixels, known dimensions, and normalized rotation.
+- Clean crop/scale decisions made before NLE import.
+- Audio-less video snippets unless audio from that source is intentionally used.
+- Short filenames with no spaces when harnesses or MLT paths are fragile.
+
+Example:
+
+```bash
+ffmpeg -y -i source.mp4 \
+  -ss 12.3 -t 5.7 \
+  -vf "scale=1920:1080:force_original_aspect_ratio=increase,crop=1920:1080,fps=30,setsar=1" \
+  -an -c:v libx264 -crf 16 -preset medium -pix_fmt yuv420p mezz/shot_001.mp4
+```
+
+## Render Resilience
+
+For long renders:
+
+- Write progress logs from the harness or render command.
+- Keep the previous good output until the new candidate has been investigated and accepted.
+- Probe the rendered file before promotion.
+- Full-decode the candidate to catch missing `moov`, corrupt packets, and partial MP4s.
+- If the environment kills long renders, render shorter chunks and assemble with `ffmpeg`.
+- Never update reports before the exact promoted final file exists.
+
+Checks after every NLE render:
+
+- Actual duration versus intended timeline duration.
+- Video stream fps versus project fps.
+- SAR/DAR and final dimensions.
+- Video track coverage through the audio tail.
+- Whether content speed visually matches audio after any normalization.
+- Whether captions/chapter cards survived the selected caption stage.
+
+## Known Failure Modes
+
+| Symptom | Likely cause | Response |
+|---|---|---|
+| Black or frozen tail | Video track shorter than audio or render ended on empty track. | Extend/fill video track, trim audio, rerender, run `video_doctor.py tail` and inspect the tail contact sheet. |
+| Valid MP4 with bad playback | Partial render, missing `moov`, bad timestamps. | Full-decode, rerender or remux from a healthy master. |
+| Wrong speed after normalization | FPS/timebase changed after NLE render. | Compare duration/fps before and after normalization; avoid filters that rewrite timing unintentionally. |
+| Captions disappeared | Clean mezzanine was rendered before caption overlay stage. | Burn captions after NLE master or include captions inside NLE by design. |
+| Source cards or hardcoded subs dominate | Source triage skipped or ranges were selected from overview cards. | Rebuild scene library and reject/crop those ranges. |
+| PNG overlays render with black backing | Alpha/format handling issue in MLT path. | Pre-render cards as video with alpha-safe settings or use ffmpeg overlay. |
+
+## Promotion
+
+Promote only after `video_doctor.py probe`, `video_doctor.py frames`, and relevant tail/caption/source doctor reports have been read and accepted in context. Hash the candidate and final path, regenerate review assets from the final path, and update reports last. Do not write "doctor passed"; record which signals were investigated and why the final is acceptable.
diff --git a/cli-hub-matrix/video-creation/references/render-doctor.md b/cli-hub-matrix/video-creation/references/render-doctor.md
new file mode 100644
index 000000000..35b6c3e94
--- /dev/null
+++ b/cli-hub-matrix/video-creation/references/render-doctor.md
@@ -0,0 +1,116 @@
+# Render Doctor And Final Promotion
+
+Use this after every render and before presenting a final MP4. Technical validity is not enough, but a binary QC script is also not enough. The render doctor gathers evidence from the exact file being delivered so the agent can investigate issues in context.
+
+## Doctor Principle
+
+`scripts/video_doctor.py` reports facts and investigation signals. It does not decide pass/fail. A nonzero exit means the doctor could not run. A zero exit means the report was produced, not that the video is good.
+
+Agents must read the report, open the referenced frames/logs/audio where relevant, and decide whether the signal is acceptable for the brief.
+
+## Baseline Doctor Commands
+
+```bash
+mkdir -p doctor
+python cli-hub-matrix/video-creation/scripts/video_doctor.py probe final.mp4 --json > doctor/probe.json
+python cli-hub-matrix/video-creation/scripts/video_doctor.py frames final.mp4 doctor/review_frames --json > doctor/frames.json
+python cli-hub-matrix/video-creation/scripts/video_doctor.py tail final.mp4 doctor/tail --json > doctor/tail.json
+python cli-hub-matrix/video-creation/scripts/video_doctor.py audio final.mp4 doctor/audio --scan-path . --json > doctor/audio.json
+```
+
+For captioned narration:
+
+```bash
+python cli-hub-matrix/video-creation/scripts/video_doctor.py captions captions.ass \
+  --media final.mp4 \
+  --narration narration.mp3 \
+  --output-language "<brief-or-conversation-language>" \
+  --json > doctor/captions.json
+```
+
+When the brief expects narration or intertitles to carry the full story, add `--expect-authored-coverage` to surface coverage-gap signals. Omit it for spot captions, music videos, ambient edits, source-audio-led scenes, or videos where captions are intentionally partial.
+
+For source manifests:
+
+```bash
+python cli-hub-matrix/video-creation/scripts/video_doctor.py sources sources.json \
+  --root . \
+  --json > doctor/sources.json
+```
+
+For HyperFrames or other linter-backed motion projects:
+
+```bash
+python cli-hub-matrix/video-creation/scripts/video_doctor.py lint render_lint.log \
+  --disposition lint_disposition.md \
+  --json > doctor/lint.json
+```
+
+Optional low-level probes are still useful when a signal needs deeper inspection:
+
+```bash
+ffmpeg -hide_banner -i final.mp4 -vf blackdetect=d=0.15:pic_th=0.98 -an -f null - 2> doctor/blackdetect.log
+ffmpeg -hide_banner -i final.mp4 -af silencedetect=n=-45dB:d=0.5 -vn -f null - 2> doctor/silencedetect.log
+ffmpeg -hide_banner -i final.mp4 -vf freezedetect=n=0.003:d=1.0 -an -f null - 2> doctor/freezedetect.log
+ffmpeg -v error -i final.mp4 -f null - 2> doctor/decode_errors.log
+```
+
+## What To Read
+
+Read doctor reports in this order:
+
+1. `probe`: duration, dimensions, fps, audio/video streams, aspect ratio clues.
+2. `frames`: first/middle/last frames, every-2s contact sheet, and a dense final-act sheet. The default final-act sample is the last 20% only as an inspection heuristic.
+3. `tail`: black/freeze/static-tail signals and tail contact sheet.
+4. `captions`: PlayRes versus final dimensions, effective font size, generic style, caption role, voice-caption span versus narration/media, repeated/debug text signals, and optional authored-coverage checks when the brief needs them.
+5. `sources`: provenance fields, source existence, selected ranges, story roles, source-text/watermark risks, quality caveats.
+6. `audio`: loudness, high/low-band clues, exported listening snippets, and procedural-audio artifact scan.
+7. `lint`: linter warnings/errors and whether the agent fixed, accepted, or blocked on them.
+
+## Investigation Signals
+
+Strong signals deserve manual inspection, not automatic rejection:
+
+- Final duration differs from the requested range or `creative_direction.md`.
+- First review frames do not reveal the topic/product/value proposition.
+- Tail report points to black/frozen/static frames.
+- Captions appear to extend far beyond narration, are authored at a different resolution, or are too small at final size.
+- Voice/narration captions end long before the media ends when the brief expects authored narration or intertitles to carry the full story.
+- Frame doctor reports very low visual diversity, especially in the final-act sample.
+- Source ranges contain hardcoded subtitles, broadcast graphics, watermarks, or platform UI without crop/mask/safe-zone mitigation.
+- Linter warnings are present without a written disposition.
+- Source manifest lacks selected ranges, story roles, platform evidence, or rights notes.
+- Generated or processed audio has harsh high-frequency hiss/sizzle, even if silence/volume scans look normal.
+- Audio doctor finds procedural-audio artifacts where a long polished edit should have AI-generated music, downloaded relevant/authorized music, or source-audio-led ambience.
+- Low-frequency pulse or repeated impact hits dominate the mix and make the soundtrack feel like test tones instead of music.
+- Data/UI/chart/map/caption regions visibly shake or drift without a documented purpose.
+- Reports point to a path other than the promoted final.
+
+For each signal, write what you inspected and the decision: accepted with reason, revised, or escalated.
+
+## Promotion Discipline
+
+1. Keep the previous known-good output.
+2. Run doctor reports on the candidate.
+3. Inspect referenced frames/logs/audio directly.
+4. If revising, render a new candidate and rerun the relevant doctor command.
+5. After choosing a promoted final, hash it:
+
+```bash
+sha256sum final.mp4 > doctor/final_sha256.txt
+```
+
+6. Regenerate `probe`, `frames`, and any relevant caption/tail/source reports from the final path.
+7. Scan reports for stale source names, old final paths, old hashes, and superseded versions.
+
+## Reporting
+
+A final review note should say:
+
+- Which doctor commands were run.
+- Which signals appeared.
+- Which frames/logs/audio segments were inspected.
+- What was revised or accepted with context.
+- For independent reviews, the top visible risks or weaknesses with frame/timestamp evidence; a review that only repeats technical checks is incomplete.
+
+Do not write "doctor passed." Write what the doctor helped you learn.
diff --git a/cli-hub-matrix/video-creation/references/sound-design.md b/cli-hub-matrix/video-creation/references/sound-design.md
new file mode 100644
index 000000000..d89242f1f
--- /dev/null
+++ b/cli-hub-matrix/video-creation/references/sound-design.md
@@ -0,0 +1,137 @@
+# Sound Design For Video Edits
+
+Use this when a video needs more than a single music bed: trailer hits, risers, whooshes, drones, heartbeats, crowd/source accents, silence gaps, or narration-aware ducking.
+
+## Required Deliverable
+
+For polished edits, create `sound_design.md` with:
+
+- Section map: time ranges, emotion, music role, and loudness target.
+- Main music strategy: AI-generated music, downloaded relevant/authorized music, source ambience-led, or user-supplied music.
+- Cue list: exact time, stem/file, story function, and visual sync point.
+- Source Audio Policy when any downloaded/captured clip audio is used: time range, source file, `audio_role`, keep reason, overlap policy, processing, and review snippet.
+- Ducking notes for narration, dialogue, source audio, or captions that need clarity.
+- Generated-stem notes, including tools and parameters.
+- Review notes for section loudness, true peak, final-act shape, and a listening pass that explicitly checks hiss, sizzle, clipping, and narration intelligibility.
+
+Generated procedural stems should be separate WAV files named by role, for example `pulse.wav`, `riser_01.wav`, `impact_03.wav`, `drone_low.wav`, `heartbeat.wav`, or `whoosh_fast.wav`. Mark them as generated in `music_sources.json` or `sound_design.md`.
+
+## Procedural Audio Guardrails
+
+Procedural audio is useful for short UI hits, pulses, and risers, but raw noise is easy to make unlistenable.
+
+- For polished videos around 60 seconds or longer, do not make a NumPy/ffmpeg/sox procedural bed the default main soundtrack. Use AI-generated music or downloaded relevant/authorized music as the main bed unless the brief explicitly asks for procedural/generative sound or the piece is intentionally source-ambience-led.
+- Treat procedural audio as SFX/accent stems first: UI ticks, soft impacts, short risers, transition whooshes, drones, pulses, or a brief final hit.
+- Do not use unfiltered Gaussian/full-band noise as a music bed, riser, or repeated whoosh.
+- Shape noise with a short envelope, band-limit it, keep it low in the mix, and reserve it for transitional moments.
+- Prefer tonal UI clicks, soft impacts, filtered sweeps, and real ambience over constant hiss.
+- Export stems separately before mixing so a noisy stem can be muted or replaced without rebuilding the edit.
+- If the user reports sizzling/noise, treat it as a critical issue even when `silencedetect`, `volumedetect`, or decode checks look normal.
+
+Bad smell examples:
+
+- `np.sin` low drones plus `rng.normal` risers as the entire music bed.
+- Repeating sub hits every few seconds to fake pacing.
+- "Procedural score" in `music_sources.json` with no real music, AI-generated music, or source-audio-led rationale.
+- Source ambience mixed so low that it is only texture while synthetic pulses dominate the edit.
+
+## Audio Roles
+
+| Role | Purpose |
+|---|---|
+| Music bed | Continuity, tone, pacing. |
+| Pulse | Gives cuts a motor without overwhelming narration. |
+| Riser | Builds into a reveal, chapter change, or final hit. |
+| Impact/sub drop | Marks a beat, dunk, reveal, title, or scene turn. |
+| Whoosh | Motivates motion graphics, fast pans, or chapter transitions. |
+| Drone | Adds dread, scale, or unresolved tension. |
+| Heartbeat/silence | Creates a hold before a payoff. |
+| Source audio | Proves authenticity or gives a scene a human edge. |
+| Narration | Leads story logic; music should move around it. |
+
+## Source Audio Overlap Rules
+
+Classify every source-audio range before mixing it. Do not use vague labels such as "source texture" unless the range has been checked and is truly ambience.
+
+| Audio role | Use |
+|---|---|
+| `silent_or_mute` | Source audio is unused, irrelevant, noisy, copyrighted music, platform intro, or would conflict with the designed mix. |
+| `ambience_keep` | Natural room/machine/crowd/market sound with no dominant music or speech; may sit quietly under narration/music. |
+| `dialogue_keep` | Source speech is story-critical; make it foreground and subtitle/translate it instead of talking over it. |
+| `music_only` | Source music is the intended bed for that window, or mute it when adding a separate music bed. |
+| `mixed_music_speech` | Speech and music are tangled; do not stack new narration/music without separation, replacement, or a source-only decision. |
+| `needs_separation` | Use a separation step such as Demucs/Spleeter/UVR or choose a cleaner range before final mix. |
+
+Keep one foreground voice at a time: agent narration or source dialogue, not both. Keep one intentional music bed at a time: source music or added music, not both. If a source clip has music and you add a new bed, mute the source audio by default unless the written policy says source-only, ducked, or separated. If a source clip has commentary and you add narration, mute/replace the source voice or let the source voice lead with subtitles.
+
+Suggested `sound_design.md` table:
+
+| Time | Source audio | Audio role | Keep reason | Overlap policy | Processing | Review snippet |
+|---|---|---|---|---|---|---|
+| 12-18s | `sources/clip.mp4` | `ambience_keep` | real machine room tone | low under music, no speech/music detected | high-pass, low-pass, duck under narration | `qc/audio/source_overlap_01.wav` |
+
+## Patterns
+
+Trailer final act:
+
+- Quiet hold or drop-out.
+- Riser into denser cuts.
+- Several synchronized hits.
+- One impact or silence gap.
+- Unresolved sting, final image, or hard resolve.
+
+Sports hype:
+
+- Cut on downbeats and visible impacts.
+- Use crowd/source accents sparingly to increase authenticity.
+- Include one energy dip before the signature final hit.
+- Avoid score loops that ignore athletic motion.
+
+Film commentary:
+
+- Narration leads the mix.
+- Chapter score changes signal argument turns.
+- Source audio reveals should be short and meaningful.
+- Do not let effects fight dialogue or subtitles.
+
+Digital/product launch:
+
+- Small UI whooshes and tactile hits work better than oversized trailer booms.
+- Sync audio changes to product state changes, not decorative text.
+
+## Mix Review
+
+Run whole-file and section-level loudness checks:
+
+```bash
+ffmpeg -hide_banner -i final.mp4 -af ebur128 -f null -
+ffmpeg -hide_banner -i final.mp4 -af volumedetect -f null -
+```
+
+Review the opening, a dense middle section, and the ending/final act. Revise or justify the mix if the ending has no intentional shape for the genre, if narration is buried, if hits are visually unsynchronized, or if the same loop runs unchanged from start to finish without a deliberate calm/ambient reason.
+
+For hiss/sizzle checks, also isolate the high band and listen or measure:
+
+```bash
+ffmpeg -hide_banner -i final.mp4 -af highpass=f=6000,volumedetect -f null -
+```
+
+A high-band measurement is only a clue; the final decision is the listening pass.
+
+Use the bundled audio doctor to collect these clues and export listening snippets:
+
+```bash
+python cli-hub-matrix/video-creation/scripts/video_doctor.py audio final.mp4 qc/audio --scan-path .
+```
+
+When source audio is used, pass the manifests and sound design file so the doctor can export overlap snippets:
+
+```bash
+python cli-hub-matrix/video-creation/scripts/video_doctor.py audio final.mp4 qc/audio \
+  --scan-path . \
+  --sources-manifest sources.json \
+  --music-manifest music_sources.json \
+  --sound-design sound_design.md
+```
+
+Read the signals in context. Revise or justify the mix if the doctor finds procedural-audio artifacts, dominant low-frequency pulse, strong high-frequency hiss/sizzle, clipped peaks, flat loudness range, missing source-audio roles, or source audio layered under music/narration without a clear mute/duck/source-only/separation policy. For polished long edits, the normal fix is to replace the main bed with AI-generated music or downloaded relevant/authorized music, keep procedural stems only as low-volume accents, and keep source audio only where its role is explicit.
diff --git a/cli-hub-matrix/video-creation/references/source-triage.md b/cli-hub-matrix/video-creation/references/source-triage.md
new file mode 100644
index 000000000..4b92eadf0
--- /dev/null
+++ b/cli-hub-matrix/video-creation/references/source-triage.md
@@ -0,0 +1,123 @@
+# Source Triage For Found-Footage Video
+
+Use this when a video depends on internet footage, public-domain clips, platform-origin media, or named scenes. The goal is to avoid cutting with weak sources just because they downloaded.
+
+## Evidence Levels
+
+Classify every source before editing:
+
+| Level | Meaning | Use |
+|---|---|---|
+| Direct platform source | Downloaded from the original or intended platform URL. | Preferred when user supplied the URL or the platform source is authorized and reachable. |
+| Verified platform-origin transport | Downloaded through another host that preserves credible source metadata, such as a Wikimedia transcode with source information or a `ytarchive:` capture. | Accept when direct platform access fails but the transport proves origin well enough for the brief. |
+| Weak mirror | Reupload, compilation, fan edit, generic mirror, or unverifiable clip. | Use only when the user accepts the caveat and the final deliverable is appropriate for that risk. |
+
+Downloadability is not permission. Do not bypass DRM, paywalls, login restrictions, or access controls. Use cookies only when the user has authorized access to the content.
+
+## Required Manifest Fields
+
+For `sources.json`, include one object per source:
+
+```json
+{
+  "id": "source_short_name",
+  "platform_url": "https://...",
+  "transport_url": "https://...",
+  "evidence_level": "direct-platform|verified-transport|weak-mirror",
+  "download_command": "yt-dlp ...",
+  "cookie_file": "path or null",
+  "local_file": "sources/source_short_name.mp4",
+  "probe": {
+    "duration": 123.45,
+    "width": 1920,
+    "height": 1080,
+    "fps": "30000/1001",
+    "video_bitrate": 8000000,
+    "audio_bitrate": 160000
+  },
+  "selected_ranges": [
+    {
+      "start": 12.3,
+      "end": 18.8,
+      "role": "setup|reveal|impact|contrast|proof|payoff",
+      "audio_role": "silent_or_mute|ambience_keep|dialogue_keep|music_only|mixed_music_speech|needs_separation",
+      "source_music_present": "none|light|dominant|unknown",
+      "speech_needed": false,
+      "overlap_policy": "mute_source|keep_ambience_low|source_dialogue_foreground|source_music_only|duck_new_music|separate_vocals|reject_range",
+      "separation_tool": "none|demucs|spleeter|uvr|api",
+      "quality_notes": "why this range survives triage",
+      "risk": "watermark/source subtitle/soft crop/etc."
+    }
+  ],
+  "creator": "name if known",
+  "license": "license or unknown",
+  "rights_notes": "authorization/attribution/caveat",
+  "quality_caveat": "none or specific caveat"
+}
+```
+
+For music, keep equivalent details in `music_sources.json`.
+
+Audio fields are required when a selected range has an audio stream and the final uses any source sound. Classify source audio before editing:
+
+- `silent_or_mute`: irrelevant audio, platform intro, pure source BGM that would fight added music, or source commentary that would fight new narration.
+- `ambience_keep`: natural ambience with no dominant music or speech.
+- `dialogue_keep`: source speech is needed; it must become foreground with subtitles/translation, not background under new narration.
+- `music_only`: source music is the intentional bed for that window; do not add another full music bed there.
+- `mixed_music_speech` / `needs_separation`: use Demucs, Spleeter, UVR, an approved API, or reject the range before adding new music or narration.
+
+If the source audio is only used for authenticity, prove it is ambience. Do not label speech/music bleed as "texture."
+
+## Triage Workflow
+
+1. Probe every source before watching it in detail:
+
+```bash
+python cli-hub-matrix/video-creation/scripts/video_doctor.py probe sources/source.mp4
+```
+
+2. Make a source overview contact sheet:
+
+```bash
+python cli-hub-matrix/video-creation/scripts/video_doctor.py frames sources/source.mp4 review/source_name
+```
+
+3. After drafting `sources.json`, run the source doctor:
+
+```bash
+python cli-hub-matrix/video-creation/scripts/video_doctor.py sources sources.json --root .
+```
+
+4. Read the doctor signals for missing provenance, stale files, weak ranges, low-quality sources, missing audio roles, and risky source-audio overlap policies. The doctor is not a rights verifier; it is a prompt for investigation.
+5. Mark likely usable ranges with a story role. A range without a role is not selected footage.
+6. Make contact sheets for selected ranges or dense action sections.
+7. Reject bad ranges before timeline work; do not push the problem into color, crop, captions, or NLE effects.
+
+When source footage has hardcoded subtitles, broadcast graphics, watermarks, or platform UI, record the risk and mitigation in the selected range: safe-zone placement, crop, mask/blur, replacement, or a written reason it is acceptable. The source doctor will flag text-heavy risks that lack mitigation notes.
+
+## Rejection Checklist
+
+Reject or crop/mask ranges that have:
+
+- Too-low resolution for the final format, unless the low-fi look is intentional.
+- Static shots that do not support the beat.
+- Countdown cards, ranking cards, source title cards, end credits, sponsor cards, or large hardcoded numbers.
+- Hardcoded captions/subtitles that fight the final captions.
+- Watermarks or platform UI that cannot be justified or safely cropped.
+- Repeated content from another selected range unless it is a deliberate callback.
+- Off-theme action, wrong character/team/object, or generic stock feel.
+- Weak platform evidence when the brief requires real YouTube/Bilibili/source provenance.
+- Audio with dialogue/SFX bleed when the source is supposed to be clean music.
+- Source music stacked under a new music bed without a source-only, ducking, mute, or separation decision.
+- Source commentary stacked under new narration; choose one foreground voice or separate/replace the source audio.
+
+## Contact Sheets To Keep
+
+For found-footage edits, keep these under `review/` or equivalent:
+
+- One overview sheet per raw source.
+- One sheet of all selected ranges.
+- One final used-ranges sheet after assembly.
+- One dense final-act sheet for trailer/sports/music edits, using the final section size that fits the genre.
+
+Reports must name the exact final source files and ranges used. If a source is replaced after review, regenerate the sheets and update the manifest.
diff --git a/cli-hub-matrix/video-creation/references/story-structure-audio.md b/cli-hub-matrix/video-creation/references/story-structure-audio.md
new file mode 100644
index 000000000..d1cd1a0c5
--- /dev/null
+++ b/cli-hub-matrix/video-creation/references/story-structure-audio.md
@@ -0,0 +1,117 @@
+# Story Structure And Audio Direction
+
+Use this reference for non-trivial videos: trailers, sports hype edits, film commentary, found-footage montage, product launch videos, music videos, documentary shorts, and anything longer than a simple clip trim. The goal is to prevent flat montage: clips with no internal logic, no emotional rise/fall, and a dull continuous audio bed.
+
+Before editing, write `creative_direction.md`. Do not start final assembly until it has enough detail that another agent could understand the whole video without seeing your timeline.
+
+## Required Creative Direction
+
+`creative_direction.md` must include:
+
+- **One-sentence promise:** what the viewer should feel or understand by the end.
+- **Audience/platform:** who watches it, where it plays, and expected energy/density.
+- **Genre contract:** trailer, sports hype, movie recap, tutorial, launch film, lyric edit, etc.
+- **Story arc:** beginning, escalation, turning point, climax, resolution.
+- **Emotional curve:** e.g. curiosity -> tension -> threat -> release -> triumph.
+- **Audio arc:** main music strategy, music sections, narration/source-audio role, silence/breaks, hits, risers, drops, and final resolve.
+- **Cut-density curve:** where cuts are slow, where they accelerate, where the edit breathes.
+- **Visual motif:** repeated image idea, color/shape/title system, or source pattern that ties the video together.
+- **Source roles:** which clips/sources establish world, conflict, evidence, spectacle, payoff, or texture.
+- **No-flatness guardrails:** explicit choices that prevent random clip order, monotone music, repeated footage, and title cards with no narrative function.
+
+## Planning Order
+
+1. **Define the spine.** Pick a clear premise and a final payoff before selecting shots.
+2. **Choose the arc shape.** Use one of the patterns below, then adapt it.
+3. **Map audio first.** Choose whether the main bed is AI-generated music, downloaded relevant/authorized music, user-supplied music, or source ambience. Then mark music/narration sections and major beat hits. The edit should respond to audio structure, not just play under it.
+4. **Assign shot jobs.** Every selected segment needs a narrative job: setup, reveal, escalation, contrast, proof, impact, or payoff.
+5. **Only then assemble.** Build rough cut by story beats, not source order.
+
+## Arc Patterns
+
+### Trailer / Sci-Fi / Game / Mecha
+
+- **0-10% Hook:** emergency, question, impossible image, or cold-open impact.
+- **10-30% World + threat:** establish where we are and what is wrong.
+- **30-55% Escalation:** stakes rise; shots become shorter; sound design grows.
+- **55-75% Drop / reversal:** major title hit, combat drop, reveal, or turning point.
+- **75-92% Final run:** fastest density, strongest music section, clear image progression.
+- **92-100% Lockup:** final line/title/logo, short breathe-out, no abrupt ending.
+
+Audio: avoid a single flat loop. Use intro pulse, riser, drop, breakdown or half-time bridge, final lift, and final tail. Layer source audio, impacts, whooshes, short silence, and low hits where appropriate.
+
+### Sports Hype / Action Montage
+
+- **Hook:** strongest visual in first 3-5 seconds, not a slow intro.
+- **Identity:** show athlete/team/sport vocabulary.
+- **Pressure:** misses, defense, conflict, preparation, crowd, rivalry, or fatigue.
+- **Breakthrough:** first clear win/impact/drop.
+- **Run:** dense sequence of best moments with increasing cut density.
+- **Signature finish:** final highlight, title, or crowd reaction.
+
+Audio: map hard cuts to kicks/snares/downbeats. Use crowd/source hits selectively. Include at least one energy dip so the final section feels earned.
+
+### Film Commentary / Recap
+
+- **Cold hook:** what makes the film/scene worth watching.
+- **Setup:** characters, context, conflict.
+- **Complication:** why the situation worsens.
+- **Turn:** decision, reveal, or emotional pivot.
+- **Payoff:** consequence and interpretation.
+- **Closing thought:** short final thesis, not just "the end."
+
+Audio: narration leads. Music should support chapters, not fight speech. Use small score changes at chapter boundaries, emotional dips for turning points, and source audio only when it clarifies a moment.
+
+### Product / Digital Launch
+
+- **Problem:** pain or opportunity.
+- **Reveal:** product/name/visual identity.
+- **Proof:** feature demo, metric, workflow, or before/after.
+- **Momentum:** multiple capabilities or use cases, increasingly fast.
+- **Outcome:** user benefit, launch line, CTA/title lockup.
+
+Audio: match UI motion to music phrases. Use clicks, swipes, risers, and soft impacts only when they reinforce product action.
+
+### Tutorial / Explainer
+
+- **Promise:** what the viewer will learn.
+- **Map:** the steps or mental model.
+- **Action:** demonstrate steps with clear cause/effect.
+- **Check:** show result or common failure.
+- **Wrap:** concise recap.
+
+Audio: keep music low and simple. Rhythm comes from edits, cursor movement, callouts, and narration pacing, not big trailer hits.
+
+## Audio Direction Rules
+
+- Do not use one unchanging music bed from start to finish unless the genre explicitly demands calm continuity.
+- Mark at least three audio events in any polished 60+ second video: hit, riser, drop, pause, texture change, source-audio reveal, or final resolve.
+- Use silence as a design element. A 200-500 ms dip before a drop can make the next shot feel stronger than another constant hit.
+- Narration, dialogue, source audio, music, and SFX must have roles. If everything is loud all the time, nothing has impact.
+- Check loudness by section, not only whole-file mean volume. Flat mean volume can hide a boring mix.
+- For polished 60+ second videos, do not default to a procedural tone/noise bed as the main soundtrack. Prefer AI-generated music, downloaded relevant/authorized music, user-supplied music, or source-ambience-led design.
+- If generating procedural hits/risers/pulses, write the intended structure first and keep them as stems or accents. Do not generate a single tone/noise loop and hope it creates drama.
+
+## Assembly Rules
+
+- Source order is not story order. Reorder clips around the arc unless the task is explicitly chronological.
+- Repeated footage is allowed only as a deliberate callback, escalation, or motif. Accidental repetition is a failure.
+- Chapter cards must change the story beat; they cannot be decorative separators for random clips.
+- Every 10-20 seconds, something should change: setting, tension, density, audio texture, title system, character focus, or edit pattern.
+- The ending must resolve the premise, intentionally withhold resolution, or hand off to a next action. It should not stop only because the timeline reached the target duration.
+
+## Review Rubric
+
+Fail and revise if any answer is "no":
+
+- Can a viewer explain the premise after the first 10 seconds?
+- Does the middle develop or escalate instead of continuing the same pattern?
+- Is there a clear high point or turning point?
+- Does the audio have sections, not just volume?
+- Is the main music/ambience strategy credible for the genre, rather than a synthetic test-tone/noise bed?
+- Do music hits, source audio, titles, and cuts reinforce the same moments?
+- Do the chosen sources have assigned narrative roles?
+- Would removing the chapter cards still leave an understandable arc?
+- Does the ending feel like a payoff rather than a cutoff?
+
+If the video is technically valid but fails this rubric, return to `creative_direction.md`, revise the arc/audio plan, and rebuild the timeline.
diff --git a/cli-hub-matrix/video-creation/scripts/video_doctor.py b/cli-hub-matrix/video-creation/scripts/video_doctor.py
new file mode 100644
index 000000000..79b70efe2
--- /dev/null
+++ b/cli-hub-matrix/video-creation/scripts/video_doctor.py
@@ -0,0 +1,2580 @@
+#!/usr/bin/env python3
+"""Investigate video-creation artifacts and report evidence for agent review.
+
+This helper is intentionally non-binary. It reports facts and investigation
+signals; it does not decide whether a video passes. A nonzero exit means the
+doctor could not run, not that the artifact is bad.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+from typing import Any
+
+
+DEFAULT_FLAG_TERMS = [
+    "MISSION SUBTITLE",
+    "MISSION LOG",
+    "DEBUG",
+    "TODO",
+]
+
+SOURCE_TEXT_TERMS = [
+    "hardcoded subtitle",
+    "hardcoded subtitles",
+    "source subtitle",
+    "source subtitles",
+    "burned subtitle",
+    "burned subtitles",
+    "broadcast graphic",
+    "broadcast graphics",
+    "lower third",
+    "ticker",
+    "watermark",
+    "platform ui",
+    "logo bug",
+    "chinese subtitle",
+    "caption collision",
+]
+
+SOURCE_TEXT_MITIGATION_TERMS = [
+    "safe zone",
+    "safe-zone",
+    "crop",
+    "cropped",
+    "mask",
+    "masked",
+    "blur",
+    "blurred",
+    "replace",
+    "replaced",
+    "avoid",
+    "avoided",
+    "upper",
+    "side",
+    "acceptable",
+    "intentional",
+]
+
+AUDIO_ROLE_VALUES = [
+    "silent_or_mute",
+    "ambience_keep",
+    "dialogue_keep",
+    "music_only",
+    "mixed_music_speech",
+    "needs_separation",
+    "unknown",
+]
+
+AUDIO_ROLE_FIELDS = [
+    "audio_role",
+    "audio_class",
+    "source_audio_role",
+    "source_audio_class",
+]
+
+AUDIO_OVERLAP_POLICY_FIELDS = [
+    "overlap_policy",
+    "new_music_overlap_policy",
+    "source_audio_policy",
+    "narration_overlap_policy",
+    "audio_policy",
+]
+
+SOURCE_AUDIO_CONFLICT_TERMS = [
+    "under the music",
+    "under music",
+    "under the score",
+    "under score",
+    "under narration",
+    "under the narration",
+    "source texture",
+    "source-audio texture",
+    "source audio texture",
+    "retain all source audio",
+    "retained source audio",
+    "mixed audibly",
+    "audible under",
+]
+
+SOURCE_AUDIO_RESOLUTION_TERMS = [
+    "mute",
+    "muted",
+    "duck",
+    "ducked",
+    "sidechain",
+    "side-chain",
+    "separate",
+    "separated",
+    "separation",
+    "demucs",
+    "spleeter",
+    "uvr",
+    "isolate",
+    "vocal",
+    "vocals",
+    "accompaniment",
+    "instrumental",
+    "keep source only",
+    "source-only",
+    "no new music",
+]
+
+SRT_TIME = re.compile(
+    r"(?P<start>\d\d:\d\d:\d\d[,.]\d{3})\s*-->\s*(?P<end>\d\d:\d\d:\d\d[,.]\d{3})"
+)
+
+
+def as_float(value: Any) -> float | None:
+    try:
+        return float(value)
+    except (TypeError, ValueError):
+        return None
+
+
+def as_int(value: Any) -> int | None:
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return None
+
+
+def parse_rate(value: str | None) -> float | None:
+    if not value or value == "0/0":
+        return None
+    if "/" in value:
+        num, den = value.split("/", 1)
+        try:
+            den_f = float(den)
+            return float(num) / den_f if den_f else None
+        except ValueError:
+            return None
+    return as_float(value)
+
+
+def ensure_tool(name: str) -> None:
+    if shutil.which(name) is None:
+        raise RuntimeError(f"{name} not found on PATH")
+
+
+def run(cmd: list[str], *, capture: bool = True) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(cmd, text=True, capture_output=capture, check=False)
+
+
+def run_bytes(cmd: list[str]) -> subprocess.CompletedProcess[bytes]:
+    return subprocess.run(cmd, capture_output=True, check=False)
+
+
+def run_checked(cmd: list[str]) -> subprocess.CompletedProcess[str]:
+    proc = run(cmd)
+    if proc.returncode != 0:
+        detail = proc.stderr.strip() or proc.stdout.strip() or "command failed"
+        raise RuntimeError(detail)
+    return proc
+
+
+def run_ffprobe(path: Path) -> dict[str, Any]:
+    ensure_tool("ffprobe")
+    proc = run_checked(
+        [
+            "ffprobe",
+            "-v",
+            "error",
+            "-print_format",
+            "json",
+            "-show_format",
+            "-show_streams",
+            str(path),
+        ]
+    )
+    return json.loads(proc.stdout)
+
+
+def media_summary(path: Path, raw: dict[str, Any]) -> dict[str, Any]:
+    fmt = raw.get("format", {})
+    video_streams: list[dict[str, Any]] = []
+    audio_streams: list[dict[str, Any]] = []
+    for stream in raw.get("streams", []):
+        if stream.get("codec_type") == "video":
+            video_streams.append(
+                {
+                    "index": stream.get("index"),
+                    "codec": stream.get("codec_name"),
+                    "profile": stream.get("profile"),
+                    "width": stream.get("width"),
+                    "height": stream.get("height"),
+                    "pix_fmt": stream.get("pix_fmt"),
+                    "duration": as_float(stream.get("duration")),
+                    "nb_frames": stream.get("nb_frames"),
+                    "avg_frame_rate": stream.get("avg_frame_rate"),
+                    "avg_fps": parse_rate(stream.get("avg_frame_rate")),
+                    "r_frame_rate": stream.get("r_frame_rate"),
+                    "sample_aspect_ratio": stream.get("sample_aspect_ratio"),
+                    "display_aspect_ratio": stream.get("display_aspect_ratio"),
+                    "field_order": stream.get("field_order"),
+                    "color_range": stream.get("color_range"),
+                    "color_space": stream.get("color_space"),
+                    "color_transfer": stream.get("color_transfer"),
+                    "color_primaries": stream.get("color_primaries"),
+                    "bit_rate": as_float(stream.get("bit_rate")),
+                }
+            )
+        elif stream.get("codec_type") == "audio":
+            audio_streams.append(
+                {
+                    "index": stream.get("index"),
+                    "codec": stream.get("codec_name"),
+                    "profile": stream.get("profile"),
+                    "sample_rate": as_float(stream.get("sample_rate")),
+                    "channels": stream.get("channels"),
+                    "channel_layout": stream.get("channel_layout"),
+                    "duration": as_float(stream.get("duration")),
+                    "bit_rate": as_float(stream.get("bit_rate")),
+                }
+            )
+    return {
+        "file": str(path),
+        "size_bytes": path.stat().st_size,
+        "format": fmt.get("format_name"),
+        "duration": as_float(fmt.get("duration")),
+        "bit_rate": as_float(fmt.get("bit_rate")),
+        "video_streams": video_streams,
+        "audio_streams": audio_streams,
+    }
+
+
+def compact_media(path: Path | None) -> dict[str, Any] | None:
+    if path is None:
+        return None
+    raw = run_ffprobe(path)
+    summary = media_summary(path, raw)
+    video = summary["video_streams"][0] if summary["video_streams"] else {}
+    return {
+        "path": str(path),
+        "duration": summary.get("duration"),
+        "width": video.get("width"),
+        "height": video.get("height"),
+        "fps": video.get("avg_fps"),
+        "audio_streams": len(summary["audio_streams"]),
+        "video_streams": len(summary["video_streams"]),
+    }
+
+
+def signal(
+    topic: str,
+    message: str,
+    *,
+    level: str = "review",
+    evidence: dict[str, Any] | None = None,
+    investigate: str | None = None,
+) -> dict[str, Any]:
+    item: dict[str, Any] = {"level": level, "topic": topic, "message": message}
+    if evidence:
+        item["evidence"] = evidence
+    if investigate:
+        item["investigate"] = investigate
+    return item
+
+
+def language_counts(text: str) -> dict[str, int]:
+    latin = len(re.findall(r"[A-Za-z]", text))
+    cjk = len(re.findall(r"[\u3400-\u9fff\u3040-\u30ff\uac00-\ud7af]", text))
+    return {
+        "latin_letters": latin,
+        "cjk_chars": cjk,
+        "visible_chars": len([char for char in text if not char.isspace()]),
+    }
+
+
+def merge_intervals(intervals: list[tuple[float, float]], duration: float | None = None) -> list[tuple[float, float]]:
+    clipped: list[tuple[float, float]] = []
+    for start, end in intervals:
+        if duration is not None:
+            start = max(0.0, min(duration, start))
+            end = max(0.0, min(duration, end))
+        if end > start:
+            clipped.append((start, end))
+    clipped.sort()
+    merged: list[tuple[float, float]] = []
+    for start, end in clipped:
+        if not merged or start > merged[-1][1] + 0.05:
+            merged.append((start, end))
+        else:
+            merged[-1] = (merged[-1][0], max(merged[-1][1], end))
+    return merged
+
+
+def coverage_seconds(intervals: list[tuple[float, float]], duration: float | None = None) -> float:
+    return sum(end - start for start, end in merge_intervals(intervals, duration))
+
+
+def sampled_frame_hashes(
+    media: Path,
+    *,
+    start: float = 0.0,
+    length: float | None = None,
+    fps: str = "1/2",
+    width: int = 32,
+    height: int = 18,
+) -> list[str]:
+    ensure_tool("ffmpeg")
+    cmd = [
+        "ffmpeg",
+        "-hide_banner",
+        "-loglevel",
+        "error",
+        "-ss",
+        f"{start:.3f}",
+        "-i",
+        str(media),
+    ]
+    if length is not None:
+        cmd += ["-t", f"{length:.3f}"]
+    cmd += [
+        "-an",
+        "-vf",
+        f"fps={fps},scale={width}:{height}:flags=fast_bilinear,format=gray",
+        "-f",
+        "rawvideo",
+        "-",
+    ]
+    proc = run_bytes(cmd)
+    if proc.returncode != 0:
+        detail = proc.stderr.decode("utf-8", errors="replace").strip() or "ffmpeg raw frame sampling failed"
+        raise RuntimeError(detail)
+    frame_size = width * height
+    hashes: list[str] = []
+    for offset in range(0, len(proc.stdout), frame_size):
+        frame = proc.stdout[offset : offset + frame_size]
+        if len(frame) != frame_size:
+            continue
+        avg = sum(frame) / frame_size
+        value = 0
+        for pix in frame:
+            value = (value << 1) | int(pix >= avg)
+        hashes.append(f"{value:0{frame_size // 4}x}")
+    return hashes
+
+
+def hamming_distance_hex(left: str, right: str) -> int:
+    return (int(left, 16) ^ int(right, 16)).bit_count()
+
+
+def visual_diversity_summary(hashes: list[str], threshold: int = 36) -> dict[str, Any]:
+    groups: list[str] = []
+    for item in hashes:
+        if not any(hamming_distance_hex(item, existing) <= threshold for existing in groups):
+            groups.append(item)
+    samples = len(hashes)
+    unique_groups = len(groups)
+    return {
+        "samples": samples,
+        "unique_groups": unique_groups,
+        "unique_ratio": round(unique_groups / samples, 3) if samples else None,
+        "near_duplicate_threshold": threshold,
+    }
+
+
+def parse_time(value: str) -> float:
+    value = value.strip().replace(",", ".")
+    parts = value.split(":")
+    if len(parts) == 3:
+        hours, minutes, seconds = parts
+        return int(hours) * 3600 + int(minutes) * 60 + float(seconds)
+    if len(parts) == 2:
+        minutes, seconds = parts
+        return int(minutes) * 60 + float(seconds)
+    return float(value)
+
+
+def clean_text(text: str) -> str:
+    text = re.sub(r"\{\\.*?\}", "", text)
+    text = re.sub(r"<[^>]+>", "", text)
+    text = text.replace("\\N", " ").replace("\\n", " ")
+    text = re.sub(r"\s+", " ", text)
+    return text.strip()
+
+
+def parse_srt(text: str) -> list[dict[str, Any]]:
+    entries: list[dict[str, Any]] = []
+    blocks = re.split(r"\n\s*\n", text.strip(), flags=re.MULTILINE)
+    for block in blocks:
+        lines = [line.strip("\ufeff") for line in block.splitlines() if line.strip()]
+        time_index = next((i for i, line in enumerate(lines) if SRT_TIME.search(line)), None)
+        if time_index is None:
+            continue
+        match = SRT_TIME.search(lines[time_index])
+        if not match:
+            continue
+        entries.append(
+            {
+                "start": parse_time(match.group("start")),
+                "end": parse_time(match.group("end")),
+                "text": clean_text(" ".join(lines[time_index + 1 :])),
+                "style": "",
+            }
+        )
+    return entries
+
+
+def parse_ass(text: str) -> list[dict[str, Any]]:
+    entries: list[dict[str, Any]] = []
+    in_events = False
+    fields: list[str] = []
+    for raw_line in text.splitlines():
+        line = raw_line.strip()
+        if line.lower() == "[events]":
+            in_events = True
+            continue
+        if in_events and line.startswith("[") and line.endswith("]"):
+            in_events = False
+        if not in_events:
+            continue
+        if line.lower().startswith("format:"):
+            fields = [part.strip().lower() for part in line.split(":", 1)[1].split(",")]
+            continue
+        if line.lower().startswith("dialogue:"):
+            payload = line.split(":", 1)[1].lstrip()
+            if not fields:
+                continue
+            parts = payload.split(",", maxsplit=len(fields) - 1)
+            if len(parts) != len(fields):
+                continue
+            row = dict(zip(fields, parts))
+            try:
+                start = parse_time(row["start"])
+                end = parse_time(row["end"])
+            except (KeyError, ValueError):
+                continue
+            entries.append(
+                {
+                    "start": start,
+                    "end": end,
+                    "text": clean_text(row.get("text", "")),
+                    "style": row.get("style") or "",
+                }
+            )
+    return entries
+
+
+def parse_ass_metadata(text: str) -> dict[str, Any]:
+    metadata: dict[str, Any] = {"playres_x": None, "playres_y": None, "styles": {}}
+    in_styles = False
+    style_fields: list[str] = []
+    for raw_line in text.splitlines():
+        line = raw_line.strip()
+        lower = line.lower()
+        if lower.startswith("playresx:"):
+            metadata["playres_x"] = as_int(as_float(line.split(":", 1)[1].strip()))
+        elif lower.startswith("playresy:"):
+            metadata["playres_y"] = as_int(as_float(line.split(":", 1)[1].strip()))
+        if lower == "[v4+ styles]":
+            in_styles = True
+            continue
+        if in_styles and line.startswith("[") and line.endswith("]"):
+            in_styles = False
+        if not in_styles:
+            continue
+        if lower.startswith("format:"):
+            style_fields = [part.strip().lower() for part in line.split(":", 1)[1].split(",")]
+            continue
+        if lower.startswith("style:") and style_fields:
+            payload = line.split(":", 1)[1].lstrip()
+            parts = payload.split(",", maxsplit=len(style_fields) - 1)
+            if len(parts) != len(style_fields):
+                continue
+            row = dict(zip(style_fields, parts))
+            name = row.get("name")
+            if not name:
+                continue
+            metadata["styles"][name] = {
+                "fontname": row.get("fontname"),
+                "fontsize": as_float(row.get("fontsize")),
+                "bold": row.get("bold"),
+                "alignment": row.get("alignment"),
+                "borderstyle": row.get("borderstyle"),
+                "outline": as_float(row.get("outline")),
+                "shadow": as_float(row.get("shadow")),
+                "primary_colour": row.get("primarycolour"),
+                "back_colour": row.get("backcolour"),
+                "margin_l": row.get("marginl"),
+                "margin_r": row.get("marginr"),
+                "margin_v": row.get("marginv"),
+            }
+    return metadata
+
+
+def parse_captions(path: Path, text: str) -> list[dict[str, Any]]:
+    suffix = path.suffix.lower()
+    if suffix == ".srt":
+        return parse_srt(text)
+    if suffix in {".ass", ".ssa"}:
+        return parse_ass(text)
+    srt_entries = parse_srt(text)
+    return srt_entries if srt_entries else parse_ass(text)
+
+
+def caption_doctor(args: argparse.Namespace) -> dict[str, Any]:
+    text = args.captions.read_text(encoding="utf-8-sig")
+    entries = parse_captions(args.captions, text)
+    metadata = parse_ass_metadata(text)
+    media = compact_media(args.media) if args.media else None
+    narration = compact_media(args.narration) if args.narration else None
+    voice_styles = {style.lower() for style in args.voice_style}
+    output_language = (args.output_language or "").strip().lower()
+    signals: list[dict[str, Any]] = []
+
+    if not entries:
+        signals.append(
+            signal(
+                "caption_parse",
+                "No timed caption entries were parsed.",
+                level="strong_signal",
+                investigate="Check file format, encoding, and whether captions are generated elsewhere.",
+            )
+        )
+
+    all_caption_text = " ".join(str(entry.get("text") or "") for entry in entries)
+    caption_language = language_counts(all_caption_text)
+    if output_language in {"en", "eng", "english"} and caption_language["cjk_chars"] > 0:
+        signals.append(
+            signal(
+                "caption_language",
+                "Caption text includes CJK characters while English output was requested.",
+                evidence=caption_language,
+                investigate="Confirm whether these are intentional names/source translations or leaked source/instruction language.",
+            )
+        )
+
+    duration = as_float(args.duration)
+    if duration is None and media:
+        duration = as_float(media.get("duration"))
+
+    playres_x = metadata.get("playres_x")
+    playres_y = metadata.get("playres_y")
+    media_w = media.get("width") if media else None
+    media_h = media.get("height") if media else None
+    if media_w and media_h and playres_x and playres_y:
+        if playres_x != media_w or playres_y != media_h:
+            signals.append(
+                signal(
+                    "caption_resolution",
+                    "ASS PlayRes differs from the final media dimensions.",
+                    level="strong_signal",
+                    evidence={
+                        "playres": f"{playres_x}x{playres_y}",
+                        "media": f"{media_w}x{media_h}",
+                    },
+                    investigate=(
+                        "Inspect caption-heavy frames at final size; resize styles or justify "
+                        "why effective text remains readable."
+                    ),
+                )
+            )
+        for style_name, style in metadata.get("styles", {}).items():
+            font_size = as_float(style.get("fontsize"))
+            if not font_size:
+                continue
+            effective = font_size * float(media_h) / float(playres_y)
+            if style_name.lower() in voice_styles and effective < 32:
+                signals.append(
+                    signal(
+                        "caption_readability",
+                        "A voice-caption style scales to a small effective font size.",
+                        evidence={"style": style_name, "effective_px": round(effective, 1)},
+                        investigate="Review the final frame on the target display size.",
+                    )
+                )
+            font_name = str(style.get("fontname") or "").strip().lower()
+            outline = as_float(style.get("outline")) or 0.0
+            borderstyle = str(style.get("borderstyle") or "")
+            if style_name.lower() in voice_styles and font_name in {"arial", "dejavu sans", "sans-serif"}:
+                signals.append(
+                    signal(
+                        "caption_style",
+                        "A voice-caption style uses a generic fallback-looking font.",
+                        evidence={
+                            "style": style_name,
+                            "font": style.get("fontname"),
+                            "borderstyle": borderstyle,
+                            "outline": outline,
+                        },
+                        investigate=(
+                            "Inspect caption-heavy frames for genre fit; choose an intentional "
+                            "font/style or document why this fallback is acceptable."
+                        ),
+                    )
+                )
+            if style_name.lower() in voice_styles and borderstyle != "3" and outline >= 2.0:
+                signals.append(
+                    signal(
+                        "caption_style",
+                        "A voice-caption style appears to rely on a thick outline instead of a designed plate/shadow.",
+                        evidence={"style": style_name, "outline": outline, "borderstyle": borderstyle},
+                        investigate="Check whether captions look like default subtitles pasted over the video.",
+                    )
+                )
+
+    previous_end = -1.0
+    overlap_count = 0
+    end_after_media: list[int] = []
+    empty_count = 0
+    flagged_terms: list[dict[str, Any]] = []
+    normalized_counts: dict[str, int] = {}
+    voice_entries: list[dict[str, Any]] = []
+
+    for idx, entry in enumerate(entries):
+        start = float(entry["start"])
+        end = float(entry["end"])
+        text_value = str(entry.get("text") or "")
+        if end <= start:
+            signals.append(
+                signal(
+                    "caption_timing",
+                    "Caption entry has non-positive duration.",
+                    level="strong_signal",
+                    evidence={"entry": idx, "start": start, "end": end},
+                    investigate="Fix or regenerate the timed-caption source.",
+                )
+            )
+        if start < previous_end - 0.05:
+            overlap_count += 1
+        previous_end = max(previous_end, end)
+        if duration is not None and end > duration + 0.25:
+            end_after_media.append(idx)
+        if not text_value:
+            empty_count += 1
+        upper = text_value.upper()
+        for term in args.flag_term:
+            if term.upper() in upper:
+                flagged_terms.append({"entry": idx, "term": term, "text": text_value[:80]})
+        normalized = re.sub(r"[^A-Z0-9]+", " ", upper).strip()
+        if normalized:
+            normalized_counts[normalized] = normalized_counts.get(normalized, 0) + 1
+        style = str(entry.get("style") or "")
+        if not style or style.lower() in voice_styles:
+            voice_entries.append(entry)
+
+    if overlap_count:
+        signals.append(
+            signal(
+                "caption_timing",
+                "Some caption entries overlap previous entries.",
+                evidence={"overlap_count": overlap_count},
+                investigate="Decide whether overlaps are intentional title/callout layering or stale subtitles.",
+            )
+        )
+    if end_after_media:
+        signals.append(
+            signal(
+                "caption_timing",
+                "Some captions extend beyond the media duration.",
+                level="strong_signal",
+                evidence={"entries": end_after_media[:10], "count": len(end_after_media)},
+                investigate="Check whether captions were authored against a different master.",
+            )
+        )
+    if empty_count:
+        signals.append(
+            signal(
+                "caption_text",
+                "Some timed entries have no visible text after cleanup.",
+                evidence={"count": empty_count},
+                investigate="Inspect ASS overrides or blank placeholder entries.",
+            )
+        )
+    if flagged_terms:
+        signals.append(
+            signal(
+                "caption_text",
+                "Potential debug or placeholder terms appear in captions.",
+                evidence={"matches": flagged_terms[:10], "count": len(flagged_terms)},
+                investigate="Confirm whether these terms are intended viewer-facing copy.",
+            )
+        )
+    repeated = [
+        {"text": key, "count": count}
+        for key, count in normalized_counts.items()
+        if count >= 3 and count / max(len(entries), 1) >= 0.5
+    ]
+    if repeated:
+        signals.append(
+            signal(
+                "caption_text",
+                "Persistent repeated caption text may indicate a stuck label.",
+                evidence={"repeated": repeated[:10]},
+                investigate="Inspect contact sheets for stale subtitles or debug labels.",
+            )
+        )
+
+    voice_summary: dict[str, Any] | None = None
+    if voice_entries:
+        voice_first = min(float(entry["start"]) for entry in voice_entries)
+        voice_last = max(float(entry["end"]) for entry in voice_entries)
+        voice_intervals = [(float(entry["start"]), float(entry["end"])) for entry in voice_entries]
+        voice_media_coverage = None
+        post_caption_tail = None
+        if duration is not None and duration > 0:
+            covered = coverage_seconds(voice_intervals, duration)
+            voice_media_coverage = covered / duration
+            post_caption_tail = max(0.0, duration - voice_last)
+        voice_summary = {
+            "entries": len(voice_entries),
+            "first_start": voice_first,
+            "last_end": voice_last,
+            "span": voice_last - voice_first,
+            "media_coverage_ratio": round(voice_media_coverage, 3) if voice_media_coverage is not None else None,
+            "post_caption_tail_seconds": round(post_caption_tail, 3) if post_caption_tail is not None else None,
+        }
+        if args.expect_authored_coverage and duration is not None and post_caption_tail is not None:
+            tail_threshold = max(args.post_caption_tail_signal, duration * 0.12)
+            if post_caption_tail > tail_threshold:
+                signals.append(
+                    signal(
+                        "caption_media_coverage",
+                        "The planned authored-caption coverage leaves a large gap before media end.",
+                        level="strong_signal",
+                        evidence={
+                            "media_duration": round(duration, 3),
+                            "voice_last_end": round(voice_last, 3),
+                            "post_caption_tail_seconds": round(post_caption_tail, 3),
+                            "media_coverage_ratio": round(voice_media_coverage or 0.0, 3),
+                        },
+                        investigate=(
+                            "Because authored coverage was requested for this doctor run, inspect the tail; "
+                            "add authored language coverage or shorten/restructure the ending."
+                        ),
+                    )
+                )
+            if (
+                voice_media_coverage is not None
+                and duration >= 30
+                and voice_media_coverage < args.voice_media_coverage_signal
+            ):
+                signals.append(
+                    signal(
+                        "caption_media_coverage",
+                        "Voice-style caption coverage is low relative to the final media duration.",
+                        evidence={
+                            "media_duration": round(duration, 3),
+                            "media_coverage_ratio": round(voice_media_coverage, 3),
+                            "threshold": args.voice_media_coverage_signal,
+                        },
+                        investigate="Check whether the video relies on source-only content where the brief expects authored narration/intertitles.",
+                    )
+                )
+        narration_duration = as_float(narration.get("duration")) if narration else None
+        if narration_duration is not None:
+            if (
+                args.expect_authored_coverage
+                and duration is not None
+                and duration - narration_duration > args.narration_media_tail_signal
+            ):
+                signals.append(
+                    signal(
+                        "narration_media_coverage",
+                        "Narration audio coverage leaves a large gap before media end in an authored-coverage review.",
+                        evidence={
+                            "media_duration": round(duration, 3),
+                            "narration_duration": round(narration_duration, 3),
+                            "post_narration_tail_seconds": round(duration - narration_duration, 3),
+                        },
+                        investigate="Inspect whether the ending has authored intertitles, intended source-only material, or an unintended coverage gap.",
+                    )
+                )
+            if voice_last > narration_duration + args.voice_after_narration_signal:
+                signals.append(
+                    signal(
+                        "caption_voice_alignment",
+                        "Voice-style captions extend well beyond the narration audio.",
+                        level="strong_signal",
+                        evidence={
+                            "voice_last_end": round(voice_last, 3),
+                            "narration_duration": round(narration_duration, 3),
+                        },
+                        investigate=(
+                            "Check whether these are narration subtitles or hand-timed story "
+                            "summaries; align against the final voice track."
+                        ),
+                    )
+                )
+            if narration_duration > 10 and (voice_last - voice_first) < narration_duration * 0.45:
+                signals.append(
+                    signal(
+                        "caption_voice_alignment",
+                        "Voice-style caption coverage is much shorter than narration.",
+                        evidence={
+                            "voice_span": round(voice_last - voice_first, 3),
+                            "narration_duration": round(narration_duration, 3),
+                        },
+                        investigate="Check for missing subtitles or wrong voice-style names.",
+                    )
+                )
+    elif narration:
+        signals.append(
+            signal(
+                "caption_voice_alignment",
+                "Narration audio was supplied, but no voice-style caption entries were found.",
+                evidence={"voice_styles": sorted(args.voice_style)},
+                investigate="Confirm style naming or whether subtitles were authored in another layer.",
+            )
+        )
+
+    review_dir_summary = None
+    if args.review_dir:
+        images = []
+        if args.review_dir.exists():
+            images = [
+                item.name
+                for item in args.review_dir.iterdir()
+                if item.suffix.lower() in {".jpg", ".jpeg", ".png", ".webp"}
+            ]
+        review_dir_summary = {
+            "path": str(args.review_dir),
+            "exists": args.review_dir.exists(),
+            "images": len(images),
+        }
+        if not args.review_dir.exists() or not images:
+            signals.append(
+                signal(
+                    "review_assets",
+                    "Review-frame directory is missing or has no image frames.",
+                    evidence=review_dir_summary,
+                    investigate="Generate caption-heavy frames from the exact promoted final.",
+                )
+            )
+
+    return {
+        "doctor": "captions",
+        "artifact": str(args.captions),
+        "summary": {
+            "entries": len(entries),
+            "first_start": entries[0]["start"] if entries else None,
+            "last_end": entries[-1]["end"] if entries else None,
+            "ass_metadata": metadata,
+            "media": media,
+            "narration": narration,
+            "voice_styles": sorted(args.voice_style),
+            "output_language": args.output_language,
+            "caption_language_counts": caption_language,
+            "voice_caption_summary": voice_summary,
+            "review_dir": review_dir_summary,
+        },
+        "signals": signals,
+        "agent_instruction": (
+            "Use these signals to choose what to inspect next. Do not treat this "
+            "report as a pass/fail verdict. Use --expect-authored-coverage only "
+            "when the brief expects narration or intertitles to carry the story."
+        ),
+    }
+
+
+def load_manifest(path: Path) -> list[dict[str, Any]]:
+    data = json.loads(path.read_text(encoding="utf-8"))
+    if isinstance(data, list):
+        return data
+    if isinstance(data, dict):
+        for key in ("sources", "music_sources", "items"):
+            if isinstance(data.get(key), list):
+                return data[key]
+    raise ValueError("manifest must be a list or contain sources/music_sources/items")
+
+
+def get_source_path(item: dict[str, Any]) -> str | None:
+    for key in ("local_file", "file", "path", "filename"):
+        value = item.get(key)
+        if isinstance(value, str) and value:
+            return value
+    return None
+
+
+def get_ranges(item: dict[str, Any]) -> list[dict[str, Any]]:
+    for key in ("selected_ranges", "used_ranges", "ranges", "clips"):
+        value = item.get(key)
+        if isinstance(value, list):
+            return [v for v in value if isinstance(v, dict)]
+    return []
+
+
+def resolve_path(value: str, root: Path, manifest_dir: Path) -> Path:
+    path = Path(value)
+    if path.is_absolute():
+        return path
+    root_candidate = root / path
+    if root_candidate.exists():
+        return root_candidate
+    return manifest_dir / path
+
+
+def range_value(item: dict[str, Any], *names: str) -> float | None:
+    for name in names:
+        if name in item:
+            return as_float(item[name])
+    return None
+
+
+def manifest_text_blob(*items: Any) -> str:
+    parts: list[str] = []
+    for item in items:
+        if item is None:
+            continue
+        if isinstance(item, dict):
+            parts.append(manifest_text_blob(*item.values()))
+        elif isinstance(item, list):
+            parts.append(manifest_text_blob(*item))
+        else:
+            parts.append(str(item))
+    return " ".join(part for part in parts if part).lower()
+
+
+def has_any_term(text: str, terms: list[str]) -> bool:
+    return any(term in text for term in terms)
+
+
+def first_manifest_value(item: dict[str, Any], names: list[str]) -> Any:
+    for name in names:
+        value = item.get(name)
+        if value not in (None, ""):
+            return value
+    return None
+
+
+def normalize_audio_role(value: Any) -> str | None:
+    if value is None:
+        return None
+    text = str(value).strip().lower().replace("-", "_").replace(" ", "_")
+    aliases = {
+        "mute": "silent_or_mute",
+        "muted": "silent_or_mute",
+        "silent": "silent_or_mute",
+        "no_audio": "silent_or_mute",
+        "ambience": "ambience_keep",
+        "ambient": "ambience_keep",
+        "nat_sound": "ambience_keep",
+        "natural_sound": "ambience_keep",
+        "dialogue": "dialogue_keep",
+        "speech": "dialogue_keep",
+        "voice": "dialogue_keep",
+        "source_music": "music_only",
+        "music": "music_only",
+        "mixed": "mixed_music_speech",
+        "mixed_speech_music": "mixed_music_speech",
+        "speech_music": "mixed_music_speech",
+    }
+    return aliases.get(text, text)
+
+
+def source_audio_metadata(item: dict[str, Any], selected: dict[str, Any] | None = None) -> dict[str, Any]:
+    selected = selected or {}
+    role = normalize_audio_role(
+        first_manifest_value(selected, AUDIO_ROLE_FIELDS)
+        or first_manifest_value(item, AUDIO_ROLE_FIELDS)
+    )
+    policy = (
+        first_manifest_value(selected, AUDIO_OVERLAP_POLICY_FIELDS)
+        or first_manifest_value(item, AUDIO_OVERLAP_POLICY_FIELDS)
+    )
+    speech_needed = first_manifest_value(selected, ["speech_needed", "dialogue_needed", "voice_needed"])
+    source_music_present = first_manifest_value(
+        selected,
+        ["source_music_present", "music_present", "bgm_present"],
+    ) or first_manifest_value(item, ["source_music_present", "music_present", "bgm_present"])
+    separation_tool = first_manifest_value(selected, ["separation_tool", "source_separation_tool"]) or first_manifest_value(
+        item,
+        ["separation_tool", "source_separation_tool"],
+    )
+    return {
+        "audio_role": role,
+        "overlap_policy": str(policy).strip() if policy not in (None, "") else None,
+        "speech_needed": speech_needed,
+        "source_music_present": source_music_present,
+        "separation_tool": separation_tool,
+    }
+
+
+def parse_time_ranges_from_text(text: str) -> list[tuple[float, float]]:
+    ranges: list[tuple[float, float]] = []
+    for match in re.finditer(
+        r"(?<![\d.])(\d+(?:\.\d+)?)\s*(?:-|–|—|to)\s*(\d+(?:\.\d+)?)\s*s\b",
+        text,
+        flags=re.IGNORECASE,
+    ):
+        start = float(match.group(1))
+        end = float(match.group(2))
+        if end > start:
+            ranges.append((start, end))
+    return ranges
+
+
+def selected_timeline_range(selected: dict[str, Any]) -> tuple[float, float] | None:
+    start = range_value(
+        selected,
+        "timeline_start",
+        "final_start",
+        "edit_start",
+        "out_start",
+        "placement_start",
+    )
+    end = range_value(
+        selected,
+        "timeline_end",
+        "final_end",
+        "edit_end",
+        "out_end",
+        "placement_end",
+    )
+    if start is not None and end is not None and end > start:
+        return start, end
+    start = range_value(selected, "timeline_start", "final_start", "edit_start", "out_start", "placement_start")
+    duration = range_value(selected, "duration", "timeline_duration", "edit_duration")
+    if start is not None and duration is not None and duration > 0:
+        return start, start + duration
+    return None
+
+
+def sources_doctor(args: argparse.Namespace) -> dict[str, Any]:
+    items = load_manifest(args.manifest)
+    entries: list[dict[str, Any]] = []
+    signals: list[dict[str, Any]] = []
+
+    for idx, item in enumerate(items):
+        source_id = str(item.get("id") or item.get("name") or f"source_{idx}")
+        local_value = get_source_path(item)
+        entry: dict[str, Any] = {"id": source_id}
+        if not local_value:
+            signals.append(
+                signal(
+                    "source_manifest",
+                    "Source entry has no local file/path field.",
+                    level="strong_signal",
+                    evidence={"id": source_id},
+                    investigate="Record the downloaded or generated file used by the edit.",
+                )
+            )
+            entries.append(entry)
+            continue
+
+        path = resolve_path(local_value, args.root, args.manifest.parent)
+        entry["path"] = str(path)
+        if not path.exists():
+            signals.append(
+                signal(
+                    "source_manifest",
+                    "Referenced source file does not exist.",
+                    level="strong_signal",
+                    evidence={"id": source_id, "path": str(path)},
+                    investigate="Check stale paths or whether the file was generated elsewhere.",
+                )
+            )
+            entries.append(entry)
+            continue
+
+        try:
+            compact = compact_media(path)
+        except Exception as exc:  # noqa: BLE001 - diagnostic report
+            compact = {"probe_error": str(exc)}
+            signals.append(
+                signal(
+                    "source_probe",
+                    "Source media probe did not complete.",
+                    evidence={"id": source_id, "error": str(exc)},
+                    investigate="Probe manually with ffprobe and check file integrity.",
+                )
+            )
+        if compact:
+            entry.update(compact)
+            width = compact.get("width")
+            height = compact.get("height")
+            if width is not None and height is not None and (width < 1280 or height < 720):
+                signals.append(
+                    signal(
+                        "source_quality",
+                        "Source resolution is below 720p.",
+                        evidence={"id": source_id, "resolution": f"{width}x{height}"},
+                        investigate="Inspect whether this source can carry the intended shot role.",
+                    )
+                )
+
+        if not (item.get("platform_url") or item.get("url") or item.get("source_url")):
+            signals.append(
+                signal(
+                    "source_provenance",
+                    "Source entry lacks platform/source URL evidence.",
+                    evidence={"id": source_id},
+                    investigate="Record origin URL or explain why the asset is local/generated.",
+                )
+            )
+        if not item.get("evidence_level"):
+            signals.append(
+                signal(
+                    "source_provenance",
+                    "Source entry lacks evidence_level.",
+                    evidence={"id": source_id},
+                    investigate="Classify direct platform, verified transport, weak mirror, or generated/local.",
+                )
+            )
+        if not (item.get("license") or item.get("rights_notes")):
+            signals.append(
+                signal(
+                    "source_rights",
+                    "Source entry lacks license or rights notes.",
+                    evidence={"id": source_id},
+                    investigate="Add usable rights notes before promotion or ask the user.",
+                )
+            )
+
+        ranges = get_ranges(item)
+        entry["selected_ranges"] = len(ranges)
+        entry["audio_streams"] = entry.get("audio_streams", 0)
+        if not ranges:
+            signals.append(
+                signal(
+                    "source_selection",
+                    "Source entry has no selected ranges.",
+                    evidence={"id": source_id},
+                    investigate="Record which ranges are actually used and their story roles.",
+                )
+            )
+        duration = as_float(entry.get("duration"))
+        missing_risk_note_ranges: list[dict[str, Any]] = []
+        unmitigated_source_text_ranges: list[dict[str, Any]] = []
+        missing_audio_role_ranges: list[dict[str, Any]] = []
+        risky_audio_policy_ranges: list[dict[str, Any]] = []
+        for ridx, selected in enumerate(ranges):
+            start = range_value(selected, "start", "in", "start_time")
+            end = range_value(selected, "end", "out", "end_time")
+            if start is None or end is None:
+                signals.append(
+                    signal(
+                        "source_selection",
+                        "Selected range lacks numeric start/end.",
+                        evidence={"id": source_id, "range": ridx},
+                        investigate="Normalize selected range metadata.",
+                    )
+                )
+                continue
+            if end <= start:
+                signals.append(
+                    signal(
+                        "source_selection",
+                        "Selected range has end <= start.",
+                        level="strong_signal",
+                        evidence={"id": source_id, "range": ridx, "start": start, "end": end},
+                        investigate="Fix range timing before using this source.",
+                    )
+                )
+            if duration is not None and end > duration + 0.25:
+                signals.append(
+                    signal(
+                        "source_selection",
+                        "Selected range ends after source duration.",
+                        level="strong_signal",
+                        evidence={
+                            "id": source_id,
+                            "range": ridx,
+                            "end": end,
+                            "duration": duration,
+                        },
+                        investigate="Check whether the manifest references the wrong source file.",
+                    )
+                )
+            if not (selected.get("role") or selected.get("shot_role")):
+                signals.append(
+                    signal(
+                        "source_selection",
+                        "Selected range lacks a story role.",
+                        evidence={"id": source_id, "range": ridx},
+                        investigate="Explain why this shot belongs in the edit.",
+                    )
+                )
+            if not any(
+                key in selected
+                for key in (
+                    "risk",
+                    "risks",
+                    "quality_notes",
+                    "source_text",
+                    "visible_text",
+                    "watermark",
+                    "subtitles",
+                )
+            ):
+                missing_risk_note_ranges.append({"range": ridx, "start": start, "end": end})
+            risk_text = manifest_text_blob(
+                selected.get("risk"),
+                selected.get("risks"),
+                selected.get("quality_notes"),
+                selected.get("source_text"),
+                selected.get("watermark"),
+                selected.get("subtitles"),
+                selected.get("visible_text"),
+                item.get("quality_caveat"),
+                item.get("source_text"),
+                item.get("watermark"),
+                item.get("subtitles"),
+                item.get("visible_text"),
+            )
+            if has_any_term(risk_text, SOURCE_TEXT_TERMS) and not has_any_term(
+                risk_text, SOURCE_TEXT_MITIGATION_TERMS
+            ):
+                unmitigated_source_text_ranges.append({"range": ridx, "start": start, "end": end})
+            audio_meta = source_audio_metadata(item, selected)
+            audio_role = audio_meta["audio_role"]
+            policy_text = manifest_text_blob(audio_meta["overlap_policy"], selected, item)
+            if entry.get("audio_streams") and not audio_role:
+                missing_audio_role_ranges.append({"range": ridx, "start": start, "end": end})
+            elif audio_role and audio_role not in AUDIO_ROLE_VALUES:
+                signals.append(
+                    signal(
+                        "source_audio_role",
+                        "Selected range uses a non-standard audio role.",
+                        evidence={"id": source_id, "range": ridx, "audio_role": audio_role},
+                        investigate=(
+                            "Normalize to silent_or_mute, ambience_keep, dialogue_keep, music_only, "
+                            "mixed_music_speech, needs_separation, or unknown."
+                        ),
+                    )
+                )
+            if audio_role in {"dialogue_keep", "music_only", "mixed_music_speech", "needs_separation"} and not audio_meta[
+                "overlap_policy"
+            ]:
+                risky_audio_policy_ranges.append(
+                    {"range": ridx, "start": start, "end": end, "audio_role": audio_role}
+                )
+            if audio_role in {"mixed_music_speech", "needs_separation"} and not (
+                audio_meta["separation_tool"] or has_any_term(policy_text, SOURCE_AUDIO_RESOLUTION_TERMS)
+            ):
+                signals.append(
+                    signal(
+                        "source_audio_overlap",
+                        "Mixed speech/music source audio lacks a separation or replacement plan.",
+                        level="strong_signal",
+                        evidence={"id": source_id, "range": ridx, "audio_role": audio_role},
+                        investigate=(
+                            "Use source separation, keep the source speech as foreground, mute the source, "
+                            "or choose a cleaner range before adding narration or a new music bed."
+                        ),
+                    )
+                )
+            if has_any_term(policy_text, SOURCE_AUDIO_CONFLICT_TERMS) and not has_any_term(
+                policy_text, SOURCE_AUDIO_RESOLUTION_TERMS
+            ):
+                signals.append(
+                    signal(
+                        "source_audio_overlap",
+                        "Source-audio text suggests overlap with music or narration without a clear mitigation.",
+                        evidence={"id": source_id, "range": ridx},
+                        investigate=(
+                            "Decide whether source audio is muted, ducked, isolated, source-only, or truly ambience-only."
+                        ),
+                    )
+                )
+        if missing_risk_note_ranges:
+            signals.append(
+                signal(
+                    "source_range_review",
+                    "Some selected ranges lack source-text/watermark/quality risk notes.",
+                    evidence={
+                        "id": source_id,
+                        "count": len(missing_risk_note_ranges),
+                        "sample": missing_risk_note_ranges[:8],
+                    },
+                    investigate=(
+                        "Review selected-range contact sheets for hardcoded subtitles, broadcast graphics, "
+                        "watermarks, platform UI, and caption-safe-zone risks."
+                    ),
+                )
+            )
+        if unmitigated_source_text_ranges:
+            signals.append(
+                signal(
+                    "source_text_occupancy",
+                    "Some selected ranges mention source subtitles, broadcast graphics, watermark, or platform UI without mitigation notes.",
+                    evidence={
+                        "id": source_id,
+                        "count": len(unmitigated_source_text_ranges),
+                        "sample": unmitigated_source_text_ranges[:8],
+                    },
+                    investigate="Record safe zone, crop/mask/blur, replacement, or reason the source text is acceptable.",
+                )
+            )
+        if missing_audio_role_ranges:
+            signals.append(
+                signal(
+                    "source_audio_role",
+                    "Some selected ranges with audio streams lack source-audio role metadata.",
+                    evidence={
+                        "id": source_id,
+                        "count": len(missing_audio_role_ranges),
+                        "sample": missing_audio_role_ranges[:8],
+                    },
+                    investigate=(
+                        "Classify each selected range as silent_or_mute, ambience_keep, dialogue_keep, "
+                        "music_only, mixed_music_speech, or needs_separation before mixing."
+                    ),
+                )
+            )
+        if risky_audio_policy_ranges:
+            signals.append(
+                signal(
+                    "source_audio_overlap",
+                    "Some selected ranges have foreground speech/music roles but no overlap policy.",
+                    evidence={
+                        "id": source_id,
+                        "count": len(risky_audio_policy_ranges),
+                        "sample": risky_audio_policy_ranges[:8],
+                    },
+                    investigate=(
+                        "Record whether new narration/music is absent, ducked, source-only, muted, or separated in those windows."
+                    ),
+                )
+            )
+        entries.append(entry)
+
+    return {
+        "doctor": "sources",
+        "artifact": str(args.manifest),
+        "summary": {"entries": entries, "root": str(args.root)},
+        "signals": signals,
+        "agent_instruction": (
+            "Use this as a provenance and source-selection investigation, not as a license verdict."
+        ),
+    }
+
+
+def calc_time(duration: float, expr: str) -> float:
+    if expr == "first":
+        return 0.5 if duration > 1 else 0
+    if expr == "middle":
+        return duration / 2
+    if expr == "last":
+        return duration - 0.25 if duration > 0.5 else 0
+    if expr == "tail_start":
+        return max(duration - 10, 0)
+    if expr == "dense_start":
+        return duration * 0.8
+    if expr == "tail_len":
+        return 10 if duration > 10 else duration
+    if expr == "dense_len":
+        return duration * 0.2 if duration > 5 else duration
+    return 0
+
+
+def frames_doctor(args: argparse.Namespace) -> dict[str, Any]:
+    ensure_tool("ffmpeg")
+    ensure_tool("ffprobe")
+    args.out_dir.mkdir(parents=True, exist_ok=True)
+    media = compact_media(args.media)
+    duration = as_float(media.get("duration")) if media else None
+    if duration is None or duration <= 0:
+        raise RuntimeError("could not read positive media duration")
+
+    times = {
+        "first": calc_time(duration, "first"),
+        "middle": calc_time(duration, "middle"),
+        "last": calc_time(duration, "last"),
+        "tail_start": calc_time(duration, "tail_start"),
+        "tail_len": calc_time(duration, "tail_len"),
+        "dense_start": calc_time(duration, "dense_start"),
+        "dense_len": calc_time(duration, "dense_len"),
+    }
+
+    outputs: dict[str, str] = {}
+    for name in ("first", "middle", "last"):
+        out = args.out_dir / f"{name}.jpg"
+        run_checked(
+            [
+                "ffmpeg",
+                "-hide_banner",
+                "-loglevel",
+                "error",
+                "-y",
+                "-ss",
+                f"{times[name]:.3f}",
+                "-i",
+                str(args.media),
+                "-frames:v",
+                "1",
+                "-q:v",
+                "2",
+                str(out),
+            ]
+        )
+        outputs[name] = str(out)
+
+    contact = args.out_dir / f"contact_every_{args.interval}s.jpg"
+    run_checked(
+        [
+            "ffmpeg",
+            "-hide_banner",
+            "-loglevel",
+            "error",
+            "-y",
+            "-i",
+            str(args.media),
+            "-vf",
+            f"fps=1/{args.interval},scale=320:-1:flags=lanczos,tile=5x5",
+            "-frames:v",
+            "1",
+            str(contact),
+        ]
+    )
+    outputs["contact"] = str(contact)
+
+    tail = args.out_dir / "tail_10s_contact.jpg"
+    run_checked(
+        [
+            "ffmpeg",
+            "-hide_banner",
+            "-loglevel",
+            "error",
+            "-y",
+            "-ss",
+            f"{times['tail_start']:.3f}",
+            "-i",
+            str(args.media),
+            "-t",
+            f"{times['tail_len']:.3f}",
+            "-vf",
+            "fps=1,scale=320:-1:flags=lanczos,tile=5x5",
+            "-frames:v",
+            "1",
+            str(tail),
+        ]
+    )
+    outputs["tail_10s"] = str(tail)
+
+    final_act_fraction = max(0.05, min(0.5, float(args.final_act_fraction)))
+    times["dense_start"] = duration * (1.0 - final_act_fraction)
+    times["dense_len"] = duration * final_act_fraction
+
+    dense = args.out_dir / "final_act_dense.jpg"
+    run_checked(
+        [
+            "ffmpeg",
+            "-hide_banner",
+            "-loglevel",
+            "error",
+            "-y",
+            "-ss",
+            f"{times['dense_start']:.3f}",
+            "-i",
+            str(args.media),
+            "-t",
+            f"{times['dense_len']:.3f}",
+            "-vf",
+            "fps=2,scale=320:-1:flags=lanczos,tile=5x5",
+            "-frames:v",
+            "1",
+            str(dense),
+        ]
+    )
+    outputs["final_act_dense"] = str(dense)
+
+    diversity: dict[str, Any] = {}
+    signals = [
+        signal(
+            "manual_review",
+            "Review frames were generated from the exact media path.",
+            level="info",
+            investigate=(
+                "Inspect these images for topic clarity, subtitle collisions, unreadable text, "
+                "black/frozen frames, wrong crops, and final-act payoff."
+            ),
+        ),
+        signal(
+            "final_act_payoff",
+            "A dense final-act contact sheet was generated for ending/payoff review.",
+            level="info",
+            evidence={
+                "image": str(dense),
+                "start": round(times["dense_start"], 3),
+                "fraction": final_act_fraction,
+            },
+            investigate=(
+                "Decide whether the ending is a climax, payoff, useful recap, hook, or deliberate unresolved ending "
+                "appropriate to the genre; motion alone is not enough."
+            ),
+        ),
+    ]
+    try:
+        overview_hashes = sampled_frame_hashes(
+            args.media,
+            start=0.0,
+            length=duration,
+            fps=f"1/{args.interval}",
+        )
+        final_hashes = sampled_frame_hashes(
+            args.media,
+            start=times["dense_start"],
+            length=times["dense_len"],
+            fps="2",
+        )
+        overview_diversity = visual_diversity_summary(overview_hashes)
+        final_diversity = visual_diversity_summary(final_hashes)
+        diversity = {"overview": overview_diversity, "final_act": final_diversity}
+        if (
+            overview_diversity["samples"] >= 8
+            and overview_diversity["unique_ratio"] is not None
+            and overview_diversity["unique_ratio"] < 0.45
+        ):
+            signals.append(
+                signal(
+                    "visual_diversity",
+                    "Sampled frames have low perceptual diversity.",
+                    evidence=overview_diversity,
+                    investigate="Inspect the contact sheet for repeated screens/cards or accidental static structure.",
+                )
+            )
+        if (
+            final_diversity["samples"] >= 8
+            and final_diversity["unique_ratio"] is not None
+            and final_diversity["unique_ratio"] < 0.45
+        ):
+            signals.append(
+                signal(
+                    "final_act_visual_diversity",
+                    "The final-act sample has low perceptual diversity.",
+                    evidence=final_diversity,
+                    investigate="Check whether the ending is an intentional hold/payoff or accidental repetition.",
+                )
+            )
+    except Exception as exc:  # noqa: BLE001 - diagnostic signal only
+        signals.append(
+            signal(
+                "visual_diversity",
+                "Perceptual diversity sampling did not complete.",
+                evidence={"error": str(exc)},
+                investigate="Use the generated contact sheets for manual repetition review.",
+            )
+        )
+
+    return {
+        "doctor": "frames",
+        "artifact": str(args.media),
+        "summary": {
+            "media": media,
+            "out_dir": str(args.out_dir),
+            "times": {key: round(value, 3) for key, value in times.items()},
+            "outputs": outputs,
+            "visual_diversity": diversity,
+        },
+        "signals": signals,
+        "agent_instruction": "The frames are evidence for visual review; inspect them directly.",
+    }
+
+
+def tail_doctor(args: argparse.Namespace) -> dict[str, Any]:
+    ensure_tool("ffmpeg")
+    ensure_tool("ffprobe")
+    args.out_dir.mkdir(parents=True, exist_ok=True)
+    media = compact_media(args.media)
+    duration = as_float(media.get("duration")) if media else None
+    if duration is None or duration <= 0:
+        raise RuntimeError("could not read positive media duration")
+    start = max(duration - args.tail_seconds, 0)
+    length = duration - start
+
+    black_log = args.out_dir / "blackdetect.log"
+    freeze_log = args.out_dir / "freezedetect.log"
+    framemd5 = args.out_dir / "tail_framemd5.txt"
+    contact = args.out_dir / "tail_contact.jpg"
+
+    proc = run(
+        [
+            "ffmpeg",
+            "-hide_banner",
+            "-ss",
+            f"{start:.3f}",
+            "-i",
+            str(args.media),
+            "-t",
+            f"{length:.3f}",
+            "-vf",
+            "blackdetect=d=0.15:pic_th=0.98",
+            "-an",
+            "-f",
+            "null",
+            "-",
+        ]
+    )
+    black_log.write_text(proc.stdout + proc.stderr, encoding="utf-8")
+
+    proc = run(
+        [
+            "ffmpeg",
+            "-hide_banner",
+            "-ss",
+            f"{start:.3f}",
+            "-i",
+            str(args.media),
+            "-t",
+            f"{length:.3f}",
+            "-vf",
+            "freezedetect=n=0.003:d=1.0",
+            "-an",
+            "-f",
+            "null",
+            "-",
+        ]
+    )
+    freeze_log.write_text(proc.stdout + proc.stderr, encoding="utf-8")
+
+    run_checked(
+        [
+            "ffmpeg",
+            "-hide_banner",
+            "-loglevel",
+            "error",
+            "-ss",
+            f"{start:.3f}",
+            "-i",
+            str(args.media),
+            "-t",
+            f"{length:.3f}",
+            "-an",
+            "-vf",
+            "fps=1",
+            "-f",
+            "framemd5",
+            str(framemd5),
+        ]
+    )
+    run_checked(
+        [
+            "ffmpeg",
+            "-hide_banner",
+            "-loglevel",
+            "error",
+            "-y",
+            "-ss",
+            f"{start:.3f}",
+            "-i",
+            str(args.media),
+            "-t",
+            f"{length:.3f}",
+            "-vf",
+            "fps=1,scale=320:-1:flags=lanczos,tile=5x5",
+            "-frames:v",
+            "1",
+            str(contact),
+        ]
+    )
+
+    hashes = [
+        line.split(",")[-1].strip()
+        for line in framemd5.read_text(encoding="utf-8").splitlines()
+        if line and not line.startswith("#")
+    ]
+    signals: list[dict[str, Any]] = []
+    black_text = black_log.read_text(encoding="utf-8", errors="replace")
+    freeze_text = freeze_log.read_text(encoding="utf-8", errors="replace")
+    if "black_start" in black_text:
+        signals.append(
+            signal(
+                "tail_visual",
+                "Blackdetect reported black frames in the inspected tail.",
+                evidence={"log": str(black_log)},
+                investigate="Open the tail contact sheet and decide whether the black segment is intentional.",
+            )
+        )
+    if "freeze_start" in freeze_text:
+        signals.append(
+            signal(
+                "tail_visual",
+                "Freezedetect reported a frozen segment in the inspected tail.",
+                evidence={"log": str(freeze_log)},
+                investigate="Check whether the final shot is intentionally held or an accidental freeze.",
+            )
+        )
+    if len(hashes) >= 3 and len(set(hashes)) <= 1:
+        signals.append(
+            signal(
+                "tail_visual",
+                "Sampled tail frame hashes are static.",
+                evidence={"sampled_frames": len(hashes), "unique_hashes": len(set(hashes))},
+                investigate="Inspect whether the video has a frozen or audio-only ending.",
+            )
+        )
+
+    return {
+        "doctor": "tail",
+        "artifact": str(args.media),
+        "summary": {
+            "media": media,
+            "tail_start": round(start, 3),
+            "tail_length": round(length, 3),
+            "sampled_frames": len(hashes),
+            "unique_frame_hashes": len(set(hashes)),
+            "logs": {
+                "blackdetect": str(black_log),
+                "freezedetect": str(freeze_log),
+                "framemd5": str(framemd5),
+                "contact": str(contact),
+            },
+        },
+        "signals": signals,
+        "agent_instruction": "Use tail signals to guide visual/audio inspection; do not use them as verdicts.",
+    }
+
+
+def lint_doctor(args: argparse.Namespace) -> dict[str, Any]:
+    signals: list[dict[str, Any]] = []
+    logs: list[dict[str, Any]] = []
+    total_warnings = 0
+    total_errors = 0
+    warning_lines: list[str] = []
+    error_lines: list[str] = []
+
+    for path in args.logs:
+        text = path.read_text(encoding="utf-8", errors="replace")
+        lower = text.lower()
+        lines = text.splitlines()
+        warning_sample = [
+            line.strip()
+            for line in lines
+            if ("⚠" in line or "warning" in line.lower())
+            and not (
+                "⚠" not in line
+                and re.search(r"\b\d+\s+warning(?:s|\(s\))?\b", line.lower())
+            )
+        ]
+        error_sample = [
+            line.strip()
+            for line in lines
+            if ("✖" in line or "error" in line.lower())
+            and not (
+                "✖" not in line
+                and re.search(r"\b\d+\s+error(?:s|\(s\))?\b", line.lower())
+            )
+        ]
+        warnings = len(warning_sample)
+        errors = len(error_sample)
+        total_warnings += warnings
+        total_errors += errors
+        warning_lines.extend(warning_sample)
+        error_lines.extend(error_sample)
+        logs.append({"path": str(path), "warnings": warnings, "errors": errors})
+        if "continuing render despite lint issues" in lower:
+            signals.append(
+                signal(
+                    "lint_disposition",
+                    "Render continued despite lint issues.",
+                    level="strong_signal",
+                    evidence={"log": str(path)},
+                    investigate="Record why continuing was acceptable, or revise/split/fix the composition and rerun lint.",
+                )
+            )
+        for term in ("composition_file_too_large", "timeline_track_too_dense"):
+            if term in lower:
+                signals.append(
+                    signal(
+                        "lint_structure",
+                        f"Lint reported {term}.",
+                        evidence={"log": str(path), "term": term},
+                        investigate="Split dense compositions or document why the warning is acceptable for this render.",
+                    )
+                )
+
+    disposition = None
+    if args.disposition:
+        if args.disposition.exists():
+            disposition_text = args.disposition.read_text(encoding="utf-8", errors="replace").lower()
+            disposition = {"path": str(args.disposition), "exists": True}
+            if not any(term in disposition_text for term in ("fixed", "revised", "accepted", "intentional", "blocked")):
+                signals.append(
+                    signal(
+                        "lint_disposition",
+                        "Lint disposition file exists but does not clearly say fixed, revised, accepted, intentional, or blocked.",
+                        evidence=disposition,
+                        investigate="Write a concise warning-by-warning disposition before promotion.",
+                    )
+                )
+        else:
+            disposition = {"path": str(args.disposition), "exists": False}
+    if (total_warnings or total_errors) and (not disposition or not disposition.get("exists")):
+        signals.append(
+            signal(
+                "lint_disposition",
+                "Lint warnings/errors exist without a disposition file.",
+                level="strong_signal",
+                evidence={"warnings": total_warnings, "errors": total_errors},
+                investigate="Fix the lint issues or save a warning disposition before promoting the final.",
+            )
+        )
+    if total_errors:
+        signals.append(
+            signal(
+                "lint_errors",
+                "Lint reported errors.",
+                level="strong_signal",
+                evidence={"errors": total_errors, "sample": error_lines[:8]},
+                investigate="Treat lint errors as blockers unless the renderer/linter bug is documented.",
+            )
+        )
+    elif total_warnings:
+        signals.append(
+            signal(
+                "lint_warnings",
+                "Lint reported warnings.",
+                evidence={"warnings": total_warnings, "sample": warning_lines[:8]},
+                investigate="Warnings are not automatic failures, but they must be inspected and dispositioned.",
+            )
+        )
+
+    return {
+        "doctor": "lint",
+        "artifact": ", ".join(str(path) for path in args.logs),
+        "summary": {
+            "logs": logs,
+            "total_warnings": total_warnings,
+            "total_errors": total_errors,
+            "disposition": disposition,
+        },
+        "signals": signals,
+        "agent_instruction": (
+            "Use lint signals to decide whether to fix, split, accept with reason, or block; "
+            "do not silently continue from lint warnings."
+        ),
+    }
+
+
+def parse_volumedetect(text: str) -> dict[str, float | None]:
+    result: dict[str, float | None] = {"mean_volume_db": None, "max_volume_db": None}
+    mean = re.search(r"mean_volume:\s*(-?\d+(?:\.\d+)?)\s*dB", text)
+    peak = re.search(r"max_volume:\s*(-?\d+(?:\.\d+)?)\s*dB", text)
+    if mean:
+        result["mean_volume_db"] = float(mean.group(1))
+    if peak:
+        result["max_volume_db"] = float(peak.group(1))
+    return result
+
+
+def parse_ebur128(text: str) -> dict[str, float | None]:
+    result: dict[str, float | None] = {
+        "integrated_lufs": None,
+        "lra_lu": None,
+        "true_peak_dbfs": None,
+    }
+    summaries = [match.start() for match in re.finditer(r"Integrated loudness:", text)]
+    if summaries:
+        tail = text[summaries[-1] :]
+    else:
+        tail = text
+    integrated = re.search(r"I:\s*(-?\d+(?:\.\d+)?)\s*LUFS", tail)
+    lra = re.search(r"LRA:\s*(-?\d+(?:\.\d+)?)\s*LU", tail)
+    true_peak = re.search(r"Peak:\s*(-?\d+(?:\.\d+)?)\s*dBFS", tail)
+    if integrated:
+        result["integrated_lufs"] = float(integrated.group(1))
+    if lra:
+        result["lra_lu"] = float(lra.group(1))
+    if true_peak:
+        result["true_peak_dbfs"] = float(true_peak.group(1))
+    return result
+
+
+PROCEDURAL_AUDIO_PATTERNS = [
+    (r"\bnp\.sin\b|\bnumpy\b", "numpy_synthesis"),
+    (r"\brng\.normal\b|\bstandard_normal\b|\brandom\.normal\b", "random_noise"),
+    (r"\bAudioArrayClip\b", "audio_array_clip"),
+    (r"\bwave\.open\b", "wave_writer"),
+    (r"\banoisesrc\b|\baevalsrc\b", "ffmpeg_synthetic_source"),
+    (r"\bprocedural (?:score|music|audio|bed|stem)", "procedural_claim"),
+    (r"\briser\b|\bsub drop\b|\bimpact hit\b|\bui tick\b", "sfx_claim"),
+]
+
+
+def scan_audio_artifacts(paths: list[Path], *, max_bytes: int = 512_000) -> dict[str, Any]:
+    files: list[dict[str, Any]] = []
+    totals: dict[str, int] = {}
+    suffixes = {".py", ".md", ".json", ".html", ".txt", ".log", ".mlt"}
+    expanded: list[Path] = []
+    for path in paths:
+        if path.is_dir():
+            for child in path.rglob("*"):
+                if child.is_file() and child.suffix.lower() in suffixes:
+                    expanded.append(child)
+        elif path.is_file():
+            expanded.append(path)
+    for path in sorted(set(expanded)):
+        try:
+            if path.stat().st_size > max_bytes:
+                continue
+            text = path.read_text(encoding="utf-8", errors="replace")
+        except OSError:
+            continue
+        matches: dict[str, int] = {}
+        for pattern, name in PROCEDURAL_AUDIO_PATTERNS:
+            count = len(re.findall(pattern, text, flags=re.IGNORECASE))
+            if count:
+                matches[name] = count
+                totals[name] = totals.get(name, 0) + count
+        if matches:
+            files.append({"path": str(path), "matches": matches})
+    return {"files": files[:80], "total_files_with_matches": len(files), "totals": totals}
+
+
+def ffmpeg_filter_report(media: Path, audio_filter: str) -> subprocess.CompletedProcess[str]:
+    return run(
+        [
+            "ffmpeg",
+            "-hide_banner",
+            "-i",
+            str(media),
+            "-vn",
+            "-af",
+            audio_filter,
+            "-f",
+            "null",
+            "-",
+        ]
+    )
+
+
+def export_audio_snippet(media: Path, out: Path, start: float, duration: float) -> None:
+    run_checked(
+        [
+            "ffmpeg",
+            "-hide_banner",
+            "-loglevel",
+            "error",
+            "-y",
+            "-ss",
+            f"{max(0.0, start):.3f}",
+            "-i",
+            str(media),
+            "-t",
+            f"{max(0.1, duration):.3f}",
+            "-vn",
+            "-ac",
+            "2",
+            "-ar",
+            "48000",
+            "-c:a",
+            "pcm_s16le",
+            str(out),
+        ]
+    )
+
+
+def manifest_audio_overlap_review(
+    manifests: list[Path],
+    *,
+    root: Path,
+) -> tuple[list[dict[str, Any]], list[dict[str, Any]], list[tuple[float, float]]]:
+    signals: list[dict[str, Any]] = []
+    entries: list[dict[str, Any]] = []
+    snippet_ranges: list[tuple[float, float]] = []
+
+    for manifest in manifests:
+        try:
+            items = load_manifest(manifest)
+        except Exception as exc:  # noqa: BLE001 - diagnostic report
+            signals.append(
+                signal(
+                    "source_audio_manifest",
+                    "Audio overlap manifest could not be read.",
+                    evidence={"manifest": str(manifest), "error": str(exc)},
+                    investigate="Fix JSON shape or pass the intended sources/music manifest.",
+                )
+            )
+            continue
+
+        for idx, item in enumerate(items):
+            source_id = str(item.get("id") or item.get("name") or f"source_{idx}")
+            role_value = str(item.get("role") or item.get("type") or "").lower()
+            role_text = manifest_text_blob(item.get("role"), item.get("type"))
+            local_value = get_source_path(item)
+            compact: dict[str, Any] | None = None
+            if local_value:
+                path = resolve_path(local_value, root, manifest.parent)
+                if path.exists():
+                    try:
+                        compact = compact_media(path)
+                    except Exception:  # noqa: BLE001 - optional evidence only
+                        compact = None
+
+            ranges = get_ranges(item)
+            if not ranges:
+                ranges = [{}]
+            for ridx, selected in enumerate(ranges):
+                audio_meta = source_audio_metadata(item, selected)
+                text_blob = manifest_text_blob(item, selected)
+                timeline = selected_timeline_range(selected)
+                if timeline is None:
+                    parsed = parse_time_ranges_from_text(text_blob)
+                    timeline = parsed[0] if parsed else None
+
+                is_source_audio = (
+                    role_value.startswith("source")
+                    or "source_audio" in role_text
+                    or "ambience" in role_text
+                    or "dialogue" in role_text
+                    or bool(audio_meta["audio_role"])
+                )
+                has_overlap_smell = has_any_term(text_blob, SOURCE_AUDIO_CONFLICT_TERMS)
+                if is_source_audio or has_overlap_smell:
+                    entries.append(
+                        {
+                            "manifest": str(manifest),
+                            "id": source_id,
+                            "range": ridx if selected else None,
+                            "role": item.get("role"),
+                            "audio_role": audio_meta["audio_role"],
+                            "overlap_policy": audio_meta["overlap_policy"],
+                            "timeline_range": list(timeline) if timeline else None,
+                            "audio_streams": compact.get("audio_streams") if compact else None,
+                        }
+                    )
+                if timeline and (is_source_audio or has_overlap_smell):
+                    snippet_ranges.append(timeline)
+                if compact and compact.get("audio_streams") and is_source_audio and not audio_meta["audio_role"]:
+                    signals.append(
+                        signal(
+                            "source_audio_role",
+                            "Manifest source-audio entry lacks audio_role metadata.",
+                            evidence={"manifest": str(manifest), "id": source_id},
+                            investigate=(
+                                "Classify it before mixing: silent_or_mute, ambience_keep, dialogue_keep, "
+                                "music_only, mixed_music_speech, or needs_separation."
+                            ),
+                        )
+                    )
+
+                if audio_meta["audio_role"] in {"music_only", "dialogue_keep", "mixed_music_speech", "needs_separation"} and not audio_meta[
+                    "overlap_policy"
+                ]:
+                    signals.append(
+                        signal(
+                            "source_audio_overlap",
+                            "Source audio has a foreground speech/music role but no overlap policy.",
+                            evidence={
+                                "manifest": str(manifest),
+                                "id": source_id,
+                                "audio_role": audio_meta["audio_role"],
+                                "timeline_range": list(timeline) if timeline else None,
+                            },
+                            investigate=(
+                                "Decide whether source audio is source-only, muted, ducked, separated, "
+                                "or kept as foreground while new narration/music exits."
+                            ),
+                        )
+                    )
+
+                if has_overlap_smell and not has_any_term(
+                    text_blob,
+                    SOURCE_AUDIO_RESOLUTION_TERMS,
+                ):
+                    signals.append(
+                        signal(
+                            "source_audio_overlap",
+                            "Manifest text suggests source audio is mixed under music or narration without a mitigation.",
+                            evidence={
+                                "manifest": str(manifest),
+                                "id": source_id,
+                                "timeline_range": list(timeline) if timeline else None,
+                            },
+                            investigate=(
+                                "Verify this is true ambience with no music/speech, or revise to mute, duck, separate, "
+                                "or keep source audio as the only foreground audio."
+                            ),
+                        )
+                    )
+
+    return entries, signals, snippet_ranges
+
+
+def sound_design_overlap_review(paths: list[Path]) -> tuple[list[dict[str, Any]], list[tuple[float, float]]]:
+    signals: list[dict[str, Any]] = []
+    snippet_ranges: list[tuple[float, float]] = []
+    for path in paths:
+        if not path.exists():
+            signals.append(
+                signal(
+                    "sound_design",
+                    "Referenced sound design file does not exist.",
+                    evidence={"path": str(path)},
+                    investigate="Pass the current sound_design.md for audio-overlap review.",
+                )
+            )
+            continue
+        text = path.read_text(encoding="utf-8", errors="replace")
+        lower = text.lower()
+        for line in lower.splitlines():
+            if has_any_term(line, SOURCE_AUDIO_CONFLICT_TERMS) or (
+                "source audio" in line and ("music" in line or "narration" in line or "dialogue" in line)
+            ):
+                snippet_ranges.extend(parse_time_ranges_from_text(line))
+        if "source audio policy" not in lower and ("source audio" in lower or "source-audio" in lower):
+            signals.append(
+                signal(
+                    "source_audio_policy",
+                    "Sound design mentions source audio but lacks a clear Source Audio Policy section/table.",
+                    evidence={"path": str(path)},
+                    investigate=(
+                        "Add a table with time range, source file, audio_role, keep reason, overlap policy, processing, and review snippet."
+                    ),
+                )
+            )
+        if has_any_term(lower, SOURCE_AUDIO_CONFLICT_TERMS) and not has_any_term(lower, SOURCE_AUDIO_RESOLUTION_TERMS):
+            signals.append(
+                signal(
+                    "source_audio_overlap",
+                    "Sound design suggests source audio is layered under music or narration without clear mitigation.",
+                    evidence={"path": str(path)},
+                    investigate=(
+                        "Do not stack source music/speech with new music/narration. Mute, duck, isolate, or make source audio foreground."
+                    ),
+                )
+            )
+    return signals, snippet_ranges
+
+
+def audio_doctor(args: argparse.Namespace) -> dict[str, Any]:
+    ensure_tool("ffmpeg")
+    ensure_tool("ffprobe")
+    raw = run_ffprobe(args.media)
+    summary = media_summary(args.media, raw)
+    signals: list[dict[str, Any]] = []
+    logs: dict[str, str] = {}
+    snippets: dict[str, str] = {}
+    audio_streams = summary.get("audio_streams") or []
+    duration = as_float(summary.get("duration")) or 0.0
+    if not audio_streams:
+        signals.append(
+            signal(
+                "audio_stream",
+                "No audio stream found.",
+                level="strong_signal",
+                investigate="Confirm whether the brief allowed a silent video; otherwise remux or rebuild audio.",
+            )
+        )
+        return {
+            "doctor": "audio",
+            "artifact": str(args.media),
+            "summary": {"media": summary, "logs": logs, "snippets": snippets},
+            "signals": signals,
+            "agent_instruction": "No audio was available to investigate.",
+        }
+
+    out_dir = args.out_dir
+    if out_dir:
+        out_dir.mkdir(parents=True, exist_ok=True)
+
+    vol_proc = ffmpeg_filter_report(args.media, "volumedetect")
+    full_volume = parse_volumedetect(vol_proc.stderr + vol_proc.stdout)
+    if out_dir:
+        log = out_dir / "audio_volumedetect.log"
+        log.write_text(vol_proc.stdout + vol_proc.stderr, encoding="utf-8")
+        logs["volumedetect"] = str(log)
+
+    high_proc = ffmpeg_filter_report(args.media, "highpass=f=6000,volumedetect")
+    high_volume = parse_volumedetect(high_proc.stderr + high_proc.stdout)
+    if out_dir:
+        log = out_dir / "audio_highpass_6000_volumedetect.log"
+        log.write_text(high_proc.stdout + high_proc.stderr, encoding="utf-8")
+        logs["highpass_6000_volumedetect"] = str(log)
+
+    low_proc = ffmpeg_filter_report(args.media, "lowpass=f=140,volumedetect")
+    low_volume = parse_volumedetect(low_proc.stderr + low_proc.stdout)
+    if out_dir:
+        log = out_dir / "audio_lowpass_140_volumedetect.log"
+        log.write_text(low_proc.stdout + low_proc.stderr, encoding="utf-8")
+        logs["lowpass_140_volumedetect"] = str(log)
+
+    ebu_proc = ffmpeg_filter_report(args.media, "ebur128=peak=true")
+    loudness = parse_ebur128(ebu_proc.stderr + ebu_proc.stdout)
+    if out_dir:
+        log = out_dir / "audio_ebur128.log"
+        log.write_text(ebu_proc.stdout + ebu_proc.stderr, encoding="utf-8")
+        logs["ebur128"] = str(log)
+
+    high_delta = None
+    if full_volume["mean_volume_db"] is not None and high_volume["mean_volume_db"] is not None:
+        high_delta = high_volume["mean_volume_db"] - full_volume["mean_volume_db"]
+    low_delta = None
+    if full_volume["mean_volume_db"] is not None and low_volume["mean_volume_db"] is not None:
+        low_delta = low_volume["mean_volume_db"] - full_volume["mean_volume_db"]
+
+    if full_volume["max_volume_db"] is not None and full_volume["max_volume_db"] > -1.0:
+        signals.append(
+            signal(
+                "audio_headroom",
+                "Peak level is very close to clipping.",
+                evidence={"max_volume_db": full_volume["max_volume_db"]},
+                investigate="Listen around loud hits and consider lowering/limiting the mix with more headroom.",
+            )
+        )
+    if loudness["integrated_lufs"] is not None and not (-28 <= loudness["integrated_lufs"] <= -12):
+        signals.append(
+            signal(
+                "audio_loudness",
+                "Integrated loudness is outside a broad review range for edited video.",
+                evidence={"integrated_lufs": loudness["integrated_lufs"]},
+                investigate="Check whether the target platform/genre justifies this level.",
+            )
+        )
+    if loudness["lra_lu"] is not None and loudness["lra_lu"] < 3.0 and duration >= 45:
+        signals.append(
+            signal(
+                "audio_dynamics",
+                "Loudness range is very low for a medium/long polished edit.",
+                evidence={"lra_lu": loudness["lra_lu"], "duration": duration},
+                investigate="Listen for a flat bed; revise section dynamics if the genre needs a stronger arc.",
+            )
+        )
+    if high_delta is not None and high_delta > -14:
+        signals.append(
+            signal(
+                "audio_high_band",
+                "High-frequency band is relatively strong compared with the full mix.",
+                evidence={"highpass_6000_mean_minus_full_mean_db": round(high_delta, 2)},
+                investigate="Listen for hiss, sizzle, harsh UI ticks, codec artifacts, or noisy risers.",
+            )
+        )
+    if low_delta is not None and low_delta > -5 and duration >= 45:
+        signals.append(
+            signal(
+                "audio_low_band",
+                "Low-frequency band dominates the mix.",
+                evidence={"lowpass_140_mean_minus_full_mean_db": round(low_delta, 2)},
+                investigate="Listen for sub-pulse monotony or repeated boom hits replacing real music.",
+            )
+        )
+
+    scan_paths = args.scan_path or []
+    artifact_scan = scan_audio_artifacts(scan_paths) if scan_paths else {"files": [], "total_files_with_matches": 0, "totals": {}}
+    totals = artifact_scan.get("totals", {})
+    if totals:
+        level = "strong_signal" if duration >= 45 and any(key in totals for key in ("random_noise", "procedural_claim")) else "review"
+        signals.append(
+            signal(
+                "procedural_audio_artifacts",
+                "Text artifacts suggest procedural or synthetic audio was used.",
+                level=level,
+                evidence={"totals": totals, "matched_files": artifact_scan.get("total_files_with_matches")},
+                investigate=(
+                    "Confirm whether generated stems are only short SFX/accent layers or whether they became the main music bed. "
+                    "For polished long videos, prefer AI-generated music or downloaded relevant/authorized music as the main bed."
+                ),
+            )
+        )
+
+    source_audio_review_entries: list[dict[str, Any]] = []
+    source_audio_snippet_ranges: list[tuple[float, float]] = []
+    manifest_paths = list(args.sources_manifest or []) + list(args.music_manifest or [])
+    if manifest_paths:
+        root = args.root or Path.cwd()
+        entries, manifest_signals, ranges = manifest_audio_overlap_review(manifest_paths, root=root)
+        source_audio_review_entries.extend(entries)
+        source_audio_snippet_ranges.extend(ranges)
+        signals.extend(manifest_signals)
+    if args.sound_design:
+        sound_signals, ranges = sound_design_overlap_review(list(args.sound_design))
+        source_audio_snippet_ranges.extend(ranges)
+        signals.extend(sound_signals)
+
+    if out_dir and source_audio_snippet_ranges and duration > 0:
+        seen: set[tuple[int, int]] = set()
+        for index, (start, end) in enumerate(source_audio_snippet_ranges, 1):
+            start = max(0.0, min(start, max(duration - 0.1, 0.0)))
+            length = max(0.1, min(end - start, args.snippet_seconds, duration - start))
+            key = (round(start * 10), round(length * 10))
+            if key in seen:
+                continue
+            seen.add(key)
+            out = out_dir / f"source_overlap_{index:02d}_{start:.1f}s.wav"
+            export_audio_snippet(args.media, out, start, length)
+            snippets[f"source_overlap_{index:02d}_{start:.1f}s"] = str(out)
+        if seen:
+            signals.append(
+                signal(
+                    "source_audio_overlap_listening",
+                    "Audio snippets were exported around documented source-audio overlap windows.",
+                    level="info",
+                    evidence={
+                        key: value
+                        for key, value in snippets.items()
+                        if key.startswith("source_overlap_")
+                    },
+                    investigate=(
+                        "Listen for stacked music beds, source commentary under new narration, or ambience that is actually speech/music."
+                    ),
+                )
+            )
+
+    if out_dir and duration > 0:
+        points = {
+            "opening": 0.0,
+            "middle": max(0.0, duration / 2 - args.snippet_seconds / 2),
+            "ending": max(0.0, duration - args.snippet_seconds),
+        }
+        if args.snippet_at:
+            for index, start in enumerate(args.snippet_at, 1):
+                points[f"custom_{index:02d}_{start:.1f}s"] = max(0.0, start)
+        for name, start in points.items():
+            out = out_dir / f"{name}.wav"
+            export_audio_snippet(args.media, out, start, min(args.snippet_seconds, max(duration - start, 0.1)))
+            snippets[name] = str(out)
+        signals.append(
+            signal(
+                "listening_pass",
+                "Audio snippets were exported for manual listening.",
+                level="info",
+                evidence=snippets,
+                investigate="Listen to the snippets before promotion; technical metrics cannot judge taste or harshness.",
+            )
+        )
+
+    return {
+        "doctor": "audio",
+        "artifact": str(args.media),
+        "summary": {
+            "media": summary,
+            "full_volume": full_volume,
+            "highpass_6000_volume": high_volume,
+            "lowpass_140_volume": low_volume,
+            "band_deltas_db": {
+                "highpass_6000_mean_minus_full_mean": high_delta,
+                "lowpass_140_mean_minus_full_mean": low_delta,
+            },
+            "loudness": loudness,
+            "procedural_artifact_scan": artifact_scan,
+            "source_audio_overlap_review": source_audio_review_entries,
+            "logs": logs,
+            "snippets": snippets,
+        },
+        "signals": signals,
+        "agent_instruction": (
+            "Use audio signals to guide listening and mix review; do not treat this report as a pass/fail verdict. "
+            "If procedural audio is the main bed in a polished long video, consider AI-generated music or downloaded relevant/authorized music instead. "
+            "If source audio overlaps new music or narration, confirm it is intentional ambience or revise with mute/duck/source-only/separation."
+        ),
+    }
+
+
+def probe_doctor(args: argparse.Namespace) -> dict[str, Any]:
+    raw = run_ffprobe(args.media)
+    summary = media_summary(args.media, raw)
+    if args.raw:
+        summary["raw_ffprobe"] = raw
+    return {
+        "doctor": "probe",
+        "artifact": str(args.media),
+        "summary": summary,
+        "signals": [],
+        "agent_instruction": "Compare these media facts to the brief and render reports.",
+    }
+
+
+def print_human(report: dict[str, Any]) -> None:
+    print(f"doctor: {report['doctor']}")
+    print(f"artifact: {report['artifact']}")
+    print("summary:")
+    print(json.dumps(report["summary"], indent=2, sort_keys=True))
+    signals = report.get("signals") or []
+    print(f"signals: {len(signals)}")
+    for item in signals:
+        print(f"- [{item.get('level')}] {item.get('topic')}: {item.get('message')}")
+        if item.get("evidence"):
+            print(f"  evidence: {json.dumps(item['evidence'], sort_keys=True)}")
+        if item.get("investigate"):
+            print(f"  investigate: {item['investigate']}")
+    print(f"agent_instruction: {report['agent_instruction']}")
+
+
+def add_common(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--json", action="store_true", help="print JSON report")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description=__doc__)
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    probe = sub.add_parser("probe", help="summarize a media file with ffprobe")
+    probe.add_argument("media", type=Path)
+    probe.add_argument("--raw", action="store_true", help="include raw ffprobe JSON")
+    add_common(probe)
+
+    captions = sub.add_parser("captions", help="investigate SRT/ASS caption timing and metadata")
+    captions.add_argument("captions", type=Path)
+    captions.add_argument("--duration", type=float, help="media duration in seconds")
+    captions.add_argument("--media", type=Path, help="final rendered media file")
+    captions.add_argument("--narration", type=Path, help="narration audio file")
+    captions.add_argument(
+        "--output-language",
+        help="expected authored viewer-facing language, e.g. English or Chinese",
+    )
+    captions.add_argument(
+        "--voice-style",
+        action="append",
+        default=[],
+        help="ASS style name used for voice subtitles; repeatable",
+    )
+    captions.add_argument(
+        "--flag-term",
+        action="append",
+        default=[],
+        help="viewer-facing term to flag for review; repeatable",
+    )
+    captions.add_argument(
+        "--voice-after-narration-signal",
+        type=float,
+        default=2.0,
+        help="seconds after narration before the doctor emits an investigation signal",
+    )
+    captions.add_argument(
+        "--post-caption-tail-signal",
+        type=float,
+        default=10.0,
+        help="seconds of media after the last voice caption before emitting an authored-coverage signal",
+    )
+    captions.add_argument(
+        "--voice-media-coverage-signal",
+        type=float,
+        default=0.75,
+        help="voice-caption coverage ratio below which the doctor emits an authored-coverage signal",
+    )
+    captions.add_argument(
+        "--narration-media-tail-signal",
+        type=float,
+        default=12.0,
+        help="seconds of media after narration duration before emitting an authored-coverage signal",
+    )
+    captions.add_argument(
+        "--expect-authored-coverage",
+        action="store_true",
+        help=(
+            "emit media-coverage signals when the brief expects narration/intertitles "
+            "to carry the story; omit for spot captions or intentionally partial captions"
+        ),
+    )
+    captions.add_argument("--review-dir", type=Path, help="directory of final-path review frames")
+    add_common(captions)
+
+    sources = sub.add_parser("sources", help="investigate a sources/music_sources manifest")
+    sources.add_argument("manifest", type=Path)
+    sources.add_argument("--root", type=Path, default=Path.cwd())
+    add_common(sources)
+
+    frames = sub.add_parser("frames", help="generate review frames/contact sheets")
+    frames.add_argument("media", type=Path)
+    frames.add_argument("out_dir", type=Path)
+    frames.add_argument("--interval", type=int, default=2)
+    frames.add_argument(
+        "--final-act-fraction",
+        type=float,
+        default=0.2,
+        help="fraction of the ending to sample for dense final-act review; default 0.2",
+    )
+    add_common(frames)
+
+    tail = sub.add_parser("tail", help="investigate the final video tail")
+    tail.add_argument("media", type=Path)
+    tail.add_argument("out_dir", type=Path)
+    tail.add_argument("--tail-seconds", type=float, default=10.0)
+    add_common(tail)
+
+    audio = sub.add_parser("audio", help="investigate final audio quality signals")
+    audio.add_argument("media", type=Path)
+    audio.add_argument("out_dir", type=Path, nargs="?", help="optional directory for logs and listening snippets")
+    audio.add_argument(
+        "--scan-path",
+        type=Path,
+        action="append",
+        default=[],
+        help="script/manifest/project path to scan for procedural-audio evidence; repeatable",
+    )
+    audio.add_argument(
+        "--sources-manifest",
+        type=Path,
+        action="append",
+        default=[],
+        help="sources.json to inspect for source-audio roles and overlap policies; repeatable",
+    )
+    audio.add_argument(
+        "--music-manifest",
+        type=Path,
+        action="append",
+        default=[],
+        help="music_sources.json to inspect for source-audio/new-music overlap; repeatable",
+    )
+    audio.add_argument(
+        "--sound-design",
+        type=Path,
+        action="append",
+        default=[],
+        help="sound_design.md to inspect for source-audio policy and overlap language; repeatable",
+    )
+    audio.add_argument("--root", type=Path, default=Path.cwd(), help="root for resolving manifest paths")
+    audio.add_argument("--snippet-seconds", type=float, default=5.0)
+    audio.add_argument(
+        "--snippet-at",
+        type=float,
+        action="append",
+        default=[],
+        help="additional snippet start time in seconds; repeatable",
+    )
+    add_common(audio)
+
+    lint = sub.add_parser("lint", help="investigate renderer/linter logs and warning disposition")
+    lint.add_argument("logs", type=Path, nargs="+")
+    lint.add_argument("--disposition", type=Path, help="file documenting warning/error disposition")
+    add_common(lint)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    for attr in ("media", "captions", "manifest"):
+        path = getattr(args, attr, None)
+        if path is not None and not path.exists():
+            print(f"error: file not found: {path}", file=sys.stderr)
+            return 2
+    for path in getattr(args, "logs", []) or []:
+        if not path.exists():
+            print(f"error: file not found: {path}", file=sys.stderr)
+            return 2
+    if getattr(args, "voice_style", None) == []:
+        args.voice_style = ["Caption", "Narration", "Subtitle"]
+    if getattr(args, "flag_term", None) == []:
+        args.flag_term = DEFAULT_FLAG_TERMS.copy()
+
+    try:
+        if args.command == "probe":
+            report = probe_doctor(args)
+        elif args.command == "captions":
+            report = caption_doctor(args)
+        elif args.command == "sources":
+            report = sources_doctor(args)
+        elif args.command == "frames":
+            report = frames_doctor(args)
+        elif args.command == "tail":
+            report = tail_doctor(args)
+        elif args.command == "audio":
+            report = audio_doctor(args)
+        elif args.command == "lint":
+            report = lint_doctor(args)
+        else:
+            raise RuntimeError(f"unknown command: {args.command}")
+    except Exception as exc:  # noqa: BLE001 - command-line diagnostic
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+
+    if args.json:
+        print(json.dumps(report, indent=2, sort_keys=True))
+    else:
+        print_human(report)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/cli-hub-meta-skill/SKILL.md b/cli-hub-meta-skill/SKILL.md
index 0aa9fde61..5745c8a75 100644
--- a/cli-hub-meta-skill/SKILL.md
+++ b/cli-hub-meta-skill/SKILL.md
@@ -29,6 +29,34 @@ cli-hub install gimp
 cli-hub info gimp
 ```
 
+## Workflow Matrices
+
+A single CLI is one tool. A **matrix** is a whole workflow packaged as
+capabilities × providers — e.g. `video-creation` maps intents like
+`text.transcribe` or `visual.generate` to harness CLIs, public CLIs, Python
+libraries, native binaries, and cloud APIs. Reach for a matrix when a task spans
+several tools (produce a video, design an image, build a game).
+
+Standard agent sequence — **preflight before you install**:
+
+```bash
+cli-hub matrix list                                   # browse all matrices
+cli-hub can "transcribe audio"                        # find the capability across matrices
+cli-hub matrix search "video subtitle"                # search; shows the matched capability
+cli-hub matrix preflight video-creation --json        # what's usable here? (exit 3 = gaps)
+cli-hub matrix preflight video-creation -c text.transcribe --fix-hints   # one capability + install hints
+cli-hub matrix install video-creation --capability text.transcribe       # install ONLY what the task needs
+# After install, the matrix SKILL.md renders locally with provider-selection rules — read it.
+```
+
+Scope every install — do not bulk-install a 14-CLI matrix for a one-capability
+task. Use `--capability <id>`, `--recipe <id>`, or `--only a,b`, and
+`--dry-run` to preview the plan with zero side effects. `--json` is available on
+every matrix subcommand; exit codes are `0` ok · `3` partial/gaps · `1` failure ·
+`2` usage error. Retry failures with `cli-hub matrix install <name> --resume`,
+and audit an install with `cli-hub matrix doctor <name>`.
+
+
 ## Live Catalog
 
 **URL**: [`https://reeceyang.sgp1.cdn.digitaloceanspaces.com/SKILL.md`](https://reeceyang.sgp1.cdn.digitaloceanspaces.com/SKILL.md)
diff --git a/cli-hub/MANIFEST.in b/cli-hub/MANIFEST.in
new file mode 100644
index 000000000..db1860206
--- /dev/null
+++ b/cli-hub/MANIFEST.in
@@ -0,0 +1,4 @@
+# Vendored matrix skill content (generated by setup.py from ../cli-hub-matrix
+# at sdist/wheel build time; see cli_hub/matrix_skill.py lookup chain).
+recursive-include cli_hub/_matrix_data *
+global-exclude __pycache__ *.pyc *.pyo
diff --git a/cli-hub/cli_hub/cli.py b/cli-hub/cli_hub/cli.py
index 651dbbb1b..a2f3fba96 100644
--- a/cli-hub/cli_hub/cli.py
+++ b/cli-hub/cli_hub/cli.py
@@ -10,7 +10,27 @@
 
 from cli_hub import __version__
 from cli_hub.registry import fetch_all_clis, get_cli, search_clis, list_categories
-from cli_hub.installer import install_cli, uninstall_cli, get_installed, update_cli
+from cli_hub.matrix import (
+    all_recipes,
+    capability_matches,
+    fetch_all_matrices,
+    get_matrix,
+    get_recipe,
+    preflight_matrix,
+    provider_install_hint,
+    search_capabilities,
+    search_matrices,
+)
+from cli_hub.matrix_skill import get_rendered_matrix_skill_path, render_matrix_skill_file
+from cli_hub.installer import (
+    doctor_matrix,
+    get_installed,
+    install_cli,
+    install_matrix,
+    plan_matrix_install,
+    uninstall_cli,
+    update_cli,
+)
 from cli_hub.analytics import (
     detect_invocation_context,
     track_first_run,
@@ -33,6 +53,14 @@
 )
 
 
+# Exit-code contract for the matrix command family (F2.3 / F2.4):
+#   0 success · 1 failure or not-found · 2 usage error · 3 partial / gaps
+EXIT_OK = 0
+EXIT_FAIL = 1
+EXIT_USAGE = 2
+EXIT_PARTIAL = 3
+
+
 def _invocation_command(ctx, version):
     """Return a compact label for the current invocation."""
     argv = sys.argv[1:]
@@ -51,7 +79,7 @@ def _invocation_command(ctx, version):
 @click.option("--version", is_flag=True, help="Show version.")
 @click.pass_context
 def main(ctx, version):
-    """cli-hub — Download and manage CLI-Anything harnesses and public CLIs."""
+    """cli-hub — Download and manage CLI-Anything CLIs, public CLIs, and curated matrices."""
     track_first_run()
     track_visit(command=_invocation_command(ctx, version), detection=detect_invocation_context())
     if version:
@@ -70,6 +98,11 @@ def _source_tag(cli):
     return ""
 
 
+def _plural(count, singular, plural=None):
+    """Return a compact count label with basic pluralization."""
+    return f"{count} {singular if count == 1 else (plural or singular + 's')}"
+
+
 @main.command()
 @click.argument("name")
 def install(name):
@@ -230,6 +263,8 @@ def info(name):
     click.echo(f"  Version:     {cli['version']}")
     click.echo(f"  Requires:    {cli.get('requires') or 'nothing'}")
     click.echo(f"  Entry point: {cli['entry_point']}")
+    if cli.get("skill_md"):
+        click.echo(f"  Skill:       {cli['skill_md']}")
     click.echo(f"  Homepage:    {cli.get('homepage', 'N/A')}")
     contributors = cli.get("contributors", [])
     if contributors:
@@ -366,5 +401,568 @@ def preview_open(preview_ref, output_path, poll_ms, port):
         click.echo(f"Opened in {launched['browser']}: pid {launched['pid']}")
     else:
         click.echo(f"Open this file manually: {rendered}")
+
+
+@main.command("can")
+@click.argument("query")
+@click.option("--json", "as_json", is_flag=True, help="Output as JSON.")
+def can(query, as_json):
+    """Find a capability across all matrices for a task (e.g. cli-hub can "transcribe audio")."""
+    hits = search_capabilities(query)
+
+    if as_json:
+        click.echo(json_mod.dumps({"query": query, "matched_capabilities": hits}, indent=2))
+        raise SystemExit(EXIT_OK if hits else EXIT_FAIL)
+
+    if not hits:
+        click.echo(f"No capability matches '{query}'.")
+        click.echo("  Browse matrices: cli-hub matrix list")
+        raise SystemExit(EXIT_FAIL)
+
+    for hit in hits:
+        cap = click.style(hit["capability_id"], bold=True)
+        loc = click.style(f"({hit['matrix']} [{hit['matrix_id']}])", fg="cyan")
+        click.echo(f"\n  {cap}  {loc}")
+        click.echo(f"    {hit['intent'][:88]}")
+
+        chips = []
+        for provider in hit["providers"][:5]:
+            if provider.get("agent_installable"):
+                chips.append(click.style(f"○ {provider['name']} (agent)", fg="bright_black"))
+            elif provider["available"]:
+                chips.append(click.style(f"✓ {provider['name']}", fg="green"))
+            else:
+                missing = [item for values in provider["missing"].values() for item in values]
+                miss = f" (missing: {', '.join(missing)})" if missing else ""
+                chips.append(click.style(f"✗ {provider['name']}{miss}", fg="yellow"))
+        if chips:
+            click.echo("    local: " + " · ".join(chips))
+        click.echo(
+            f"    next: cli-hub matrix preflight {hit['matrix']} -c {hit['capability_id']}"
+        )
+
+
+@main.group(name="matrix", invoke_without_command=True)
+@click.pass_context
+def matrix(ctx):
+    """Browse and install curated multi-CLI workflow matrices."""
+    if ctx.invoked_subcommand is None:
+        click.echo(ctx.get_help())
+
+
+@matrix.command("list")
+@click.option("--json", "as_json", is_flag=True, help="Output as JSON.")
+def list_matrices(as_json):
+    """List all available matrices."""
+    try:
+        matrices = fetch_all_matrices()
+    except Exception as e:
+        click.secho(f"Failed to fetch matrix registry: {e}", fg="red", err=True)
+        raise SystemExit(1)
+
+    installed = get_installed()
+
+    if as_json:
+        click.echo(json_mod.dumps(matrices, indent=2))
+        return
+
+    if not matrices:
+        click.echo("No matrices found.")
+        return
+
+    click.secho("\n  MATRICES", fg="blue", bold=True)
+    for matrix_item in sorted(matrices, key=lambda s: s["name"]):
+        installed_count = sum(1 for cli_name in matrix_item.get("clis", []) if cli_name in installed)
+        total = len(matrix_item.get("clis", []))
+        marker = click.style(" ●", fg="green") if total and installed_count == total else "  "
+        name = click.style(f"{matrix_item['name']:20s}", bold=True)
+        matrix_label = click.style(f"[{matrix_item.get('matrix_id', 'matrix')}]", fg="cyan")
+        click.echo(f"  {marker} {name} {matrix_label} {matrix_item['description'][:65]}")
+        click.echo(f"     Includes: {installed_count}/{total} CLIs installed")
+
+    click.echo(f"\n  {len(matrices)} matrices available")
+
+
+@matrix.command("search")
+@click.argument("query")
+@click.option("--json", "as_json", is_flag=True, help="Output as JSON.")
+def matrix_search(query, as_json):
+    """Search matrices by name, capabilities, providers, recipes, or gaps."""
+    results = search_matrices(query)
+    query_lower = query.lower()
+
+    if as_json:
+        enriched = []
+        for matrix_item in results:
+            entry = dict(matrix_item)
+            entry["matched_capabilities"] = capability_matches(matrix_item, query_lower)
+            enriched.append(entry)
+        click.echo(json_mod.dumps(enriched, indent=2))
+        return
+
+    if not results:
+        click.echo(f"No matrices matching '{query}'.")
+        click.echo(f"  Try capability search: cli-hub can \"{query}\"")
+        return
+
+    installed = get_installed()
+    for matrix_item in results:
+        cli_names = matrix_item.get("clis", [])
+        installed_count = sum(1 for c in cli_names if c in installed)
+        total = len(cli_names)
+        name_str = click.style(matrix_item["name"], bold=True)
+        matrix_label = click.style(f"[{matrix_item.get('matrix_id', 'matrix')}]", fg="cyan")
+        click.echo(f"\n  {name_str} {matrix_label} - {matrix_item['description'][:65]}")
+        click.echo(f"    CLIs: {installed_count}/{total} installed")
+
+        matched = capability_matches(matrix_item, query_lower)
+        for hit in matched:
+            star = click.style("✦", fg="cyan")
+            click.echo(
+                f"    {star} matched capability: {click.style(hit['capability_id'], bold=True)} "
+                f"({hit['match_field']})"
+            )
+            click.echo(f"        {hit['intent'][:80]}")
+            click.echo(f"        providers: {hit['providers_summary']}")
+
+        if matched:
+            first = matched[0]["capability_id"]
+            click.echo(
+                f"    Install: cli-hub matrix install {matrix_item['name']} "
+                f"--capability {first}"
+            )
+        else:
+            click.echo(f"    Install: cli-hub matrix install {matrix_item['name']}")
+
+
+@matrix.command("info")
+@click.argument("name")
+@click.option("--json", "as_json", is_flag=True, help="Output matrix metadata as JSON.")
+def matrix_info(name, as_json):
+    """Show details for a specific matrix."""
+    matrix_item = get_matrix(name)
+    if not matrix_item:
+        click.secho(f"Matrix '{name}' not found.", fg="red", err=True)
+        raise SystemExit(1)
+
+    installed = get_installed()
+    cli_names = matrix_item.get("clis", [])
+    installed_count = sum(1 for cli_name in cli_names if cli_name in installed)
+
+    if as_json:
+        payload = dict(matrix_item)
+        payload["_installed"] = {
+            "count": installed_count,
+            "total": len(cli_names),
+            "clis": [cli_name for cli_name in cli_names if cli_name in installed],
+        }
+        click.echo(json_mod.dumps(payload, indent=2))
+        return
+
+    click.secho(f"\n  {matrix_item['display_name']}", bold=True)
+    click.echo(f"  {matrix_item['description']}")
+    click.echo(f"  Matrix:      {matrix_item.get('matrix', 'N/A')} {matrix_item.get('matrix_id', '')}".rstrip())
+    if matrix_item.get("schema_version"):
+        click.echo(f"  Schema:      v{matrix_item['schema_version']}")
+    click.echo(f"  Category:    {matrix_item.get('category', 'N/A')}")
+    click.echo(f"  CLIs:        {len(cli_names)}")
+    click.echo(f"  Installed:   {installed_count}/{len(cli_names)}")
+    if matrix_item.get("skill_md"):
+        click.echo(f"  Skill:       {matrix_item['skill_md']}")
+    rendered_skill_path = get_rendered_matrix_skill_path(matrix_item["name"])
+    if rendered_skill_path.exists():
+        click.echo(f"  Local skill: {rendered_skill_path}")
+    if matrix_item.get("homepage"):
+        click.echo(f"  Homepage:    {matrix_item['homepage']}")
+
+    click.echo("\n  Members:")
+    for cli_name in cli_names:
+        status = click.style("installed", fg="green") if cli_name in installed else "not installed"
+        click.echo(f"    - {cli_name} ({status})")
+
+    stages = matrix_item.get("stages", [])
+    if stages:
+        click.echo("\n  Stage Coverage:")
+        for stage in stages:
+            members = ", ".join(stage.get("clis", []))
+            goal = stage.get("goal", "")
+            goal_suffix = f" -- {goal}" if goal else ""
+            click.echo(f"    - {stage['name']}: {members}{goal_suffix}")
+
+    capabilities = matrix_item.get("capabilities", [])
+    if capabilities:
+        click.echo("\n  Capabilities:")
+        for capability in capabilities:
+            providers = capability.get("providers", [])
+            cli_provider_count = sum(
+                1 for provider in providers
+                if provider.get("kind") in {"harness-cli", "public-cli"}
+            )
+            offline_count = sum(1 for provider in providers if provider.get("offline"))
+            click.echo(
+                f"    - {capability['id']}: "
+                f"{_plural(len(providers), 'provider')} "
+                f"({_plural(cli_provider_count, 'CLI')}, {offline_count} offline)"
+            )
+            if capability.get("intent"):
+                click.echo(f"      {capability['intent']}")
+
+    recipes = matrix_item.get("recipes", [])
+    if recipes:
+        click.echo("\n  Recipes:")
+        for recipe in recipes:
+            capability_count = len(recipe.get("capabilities_used", []))
+            click.echo(f"    - {recipe['id']}: {capability_count} capabilities - {recipe.get('description', '')}")
+
+    known_gaps = matrix_item.get("known_gaps", [])
+    if known_gaps:
+        click.echo("\n  Known Gaps:")
+        for gap in known_gaps:
+            click.echo(f"    - {gap.get('capability', 'unknown')}: {gap.get('reason', '')}")
+
+    click.echo(f"\n  Install: cli-hub matrix install {matrix_item['name']}")
+    if capabilities:
+        click.echo(f"  Preflight: cli-hub matrix preflight {matrix_item['name']}")
+    click.echo()
+
+
+@matrix.command("preflight")
+@click.argument("name")
+@click.option("--capability", "-c", default=None, help="Only check one capability id.")
+@click.option("--recipe", default=None, help="Only check the capabilities used by one recipe.")
+@click.option("--offline", is_flag=True, help="Only consider offline-capable providers.")
+@click.option("--fix-hints", is_flag=True, help="Show an install command under each missing provider.")
+@click.option("--summary", "summary_only", is_flag=True, help="Print only the two-line summary.")
+@click.option("--json", "as_json", is_flag=True, help="Output provider availability as JSON.")
+def matrix_preflight(name, capability, recipe, offline, fix_hints, summary_only, as_json):
+    """Check which matrix providers are available in the current environment.
+
+    Exit codes: 0 all capabilities covered · 3 one or more capability gaps ·
+    1 matrix not found · 2 unknown capability/recipe.
+    """
+    matrix_item = get_matrix(name)
+    if not matrix_item:
+        click.secho(f"Matrix '{name}' not found.", fg="red", err=True)
+        raise SystemExit(EXIT_FAIL)
+
+    if capability and recipe:
+        click.secho("Use only one of --capability or --recipe.", fg="red", err=True)
+        raise SystemExit(EXIT_USAGE)
+
+    capability_ids = None
+    if recipe:
+        recipe_item = get_recipe(matrix_item, recipe)
+        if recipe_item is None:
+            valid = ", ".join(r.get("id", "") for r in matrix_item.get("recipes", []))
+            click.secho(f"Recipe '{recipe}' not found. Valid: {valid or '(none)'}", fg="red", err=True)
+            raise SystemExit(EXIT_USAGE)
+        capability_ids = recipe_item.get("capabilities_used", [])
+    if capability and capability not in {c.get("id") for c in matrix_item.get("capabilities", [])}:
+        valid = ", ".join(c.get("id", "") for c in matrix_item.get("capabilities", []))
+        click.secho(f"Capability '{capability}' not found. Valid: {valid or '(none)'}", fg="red", err=True)
+        raise SystemExit(EXIT_USAGE)
+
+    payload = preflight_matrix(
+        matrix_item, capability_id=capability, offline=offline, capability_ids=capability_ids
+    )
+
+    if as_json:
+        click.echo(json_mod.dumps(payload, indent=2))
+        raise SystemExit(EXIT_PARTIAL if payload["summary"].get("gaps", 0) else EXIT_OK)
+
+    capabilities = payload["capabilities"]
+    if not capabilities:
+        target = capability or recipe or "capabilities"
+        click.secho(f"No capability data found for {target}.", fg="yellow")
+        raise SystemExit(EXIT_FAIL)
+
+    summary = payload["summary"]
+    cli_names = matrix_item.get("clis", [])
+    click.secho(f"\n  {payload['matrix']['display_name']} Preflight", bold=True)
+    mode = "offline providers only" if offline else "all providers"
+    scope_suffix = f" · recipe {recipe}" if recipe else (f" · capability {capability}" if capability else "")
+    click.echo(
+        f"  {summary['covered']}/{summary['capabilities']} capabilities covered "
+        f"({summary['available_providers']}/{_plural(summary['providers'], 'provider')} "
+        f"available, {mode}{scope_suffix})"
+    )
+    if summary.get("gaps"):
+        click.secho(f"  {_plural(summary['gaps'], 'capability')} with no usable provider", fg="yellow")
+    agent_installable = summary.get("agent_installable_providers", 0)
+    if agent_installable:
+        verb = "is" if agent_installable == 1 else "are"
+        click.echo(
+            f"  {_plural(agent_installable, 'agent-installable skill provider')} "
+            f"{verb} not counted as installed or missing"
+        )
+
+    if not summary_only:
+        for capability_result in capabilities:
+            click.echo(f"\n  {capability_result['id']}")
+            click.echo(f"    {capability_result['intent']}")
+
+            for provider in capability_result["providers"][:4]:
+                if provider.get("agent_installable"):
+                    marker = click.style("○", fg="bright_black")
+                elif provider["available"]:
+                    marker = click.style("✓", fg="green")
+                else:
+                    marker = click.style("·", fg="yellow")
+                missing = [
+                    item
+                    for values in provider["missing"].values()
+                    for item in values
+                ]
+                if provider.get("agent_installable"):
+                    suffix = " agent-installable"
+                elif provider["available"]:
+                    suffix = ""
+                else:
+                    suffix = f" missing: {', '.join(missing) or 'requirements'}"
+                click.echo(
+                    f"    {marker} {provider['name']} "
+                    f"[{provider['kind']}; {provider['quality_tier']}; {provider['cost_tier']}]{suffix}"
+                )
+                if fix_hints and not provider["available"] and not provider.get("agent_installable"):
+                    hint = provider_install_hint(provider, cli_names)
+                    if hint:
+                        click.echo(click.style(f"      ↳ install: {hint}", fg="bright_black"))
+
+    raise SystemExit(EXIT_PARTIAL if summary.get("gaps") else EXIT_OK)
+
+
+_NOT_MANAGED_LABELS = {
+    "python": "Python libraries",
+    "native": "native binaries",
+    "api": "cloud APIs (need keys)",
+    "agent-skill": "agent skills (agent-installed)",
+    "public-unmanaged": "third-party CLIs (brew/npm/pip)",
+}
+
+
+def _render_dry_run(payload):
+    """Print a no-side-effect install plan (F2.1)."""
+    matrix_item = payload["matrix"]
+    summary = payload["summary"]
+    click.secho(f"\n  Install plan: {matrix_item['name']} ({payload['scope_label']})", bold=True)
+
+    skips = [p for p in payload["plan"] if p["action"] == "skip"]
+    installs = [p for p in payload["plan"] if p["action"] == "install"]
+    errors = [p for p in payload["plan"] if p["action"] == "error"]
+
+    if skips:
+        names = ", ".join(p["name"] for p in skips)
+        click.secho(f"  ✓ Already installed, will skip ({len(skips)}): {names}", fg="green")
+    for via in ("pip", "npm", "uv", "bundled", "command"):
+        group = [p for p in installs if p["via"] == via]
+        if group:
+            names = ", ".join(p["name"] for p in group)
+            click.echo(f"  + Will install via {via} ({len(group)}): {names}")
+    if errors:
+        names = ", ".join(p["name"] for p in errors)
+        click.secho(f"  ! Not in CLI registry ({len(errors)}): {names}", fg="yellow")
+
+    not_managed = payload.get("not_managed", {})
+    if not_managed:
+        click.echo("  ! Not installed by this command (use preflight + install hints):")
+        for category, names in not_managed.items():
+            label = _NOT_MANAGED_LABELS.get(category, category)
+            click.echo(f"      {label}: {', '.join(names)}")
+
+    if not payload["plan"]:
+        click.secho("  Nothing to install for this scope via cli-hub.", fg="yellow")
+        click.echo("  These providers are public/native/API — see: "
+                   f"cli-hub matrix preflight {matrix_item['name']} --fix-hints")
+
+    click.echo(f"\n  {summary['to_install']} to install, {summary['to_skip']} to skip"
+               + (f", {summary['unresolved']} unresolved" if summary["unresolved"] else ""))
+    click.echo(f"  Run: cli-hub matrix install {matrix_item['name']}"
+               + _scope_args(payload["scope"]))
+
+
+def _scope_args(scope):
+    """Reconstruct the scope flags for an echoed command line."""
+    scope_type = scope.get("type")
+    if scope_type == "capability":
+        return f" --capability {scope['value']}"
+    if scope_type == "recipe":
+        return f" --recipe {scope['value']}"
+    if scope_type == "only":
+        return f" --only {','.join(scope['value'])}"
+    return ""
+
+
+@matrix.command("install")
+@click.argument("name")
+@click.option("--capability", "-c", default=None, help="Install only the CLIs behind one capability.")
+@click.option("--recipe", default=None, help="Install only the CLIs used by one recipe.")
+@click.option("--only", default=None, help="Install a comma-separated subset of the matrix CLIs.")
+@click.option("--dry-run", is_flag=True, help="Show the install plan without installing anything.")
+@click.option("--resume", is_flag=True, help="Retry only the CLIs that failed in the last install.")
+@click.option(
+    "--skill-only",
+    is_flag=True,
+    help="Render the matrix skill (SKILL.md + references/ + scripts/) without installing member CLIs.",
+)
+@click.option("--json", "as_json", is_flag=True, help="Output the plan or result as JSON.")
+def matrix_install(name, capability, recipe, only, dry_run, resume, skill_only, as_json):
+    """Install the CLIs in a matrix (optionally scoped to a capability, recipe, or subset).
+
+    Exit codes: 0 success · 3 partial failure · 1 total failure or not found ·
+    2 usage error.
+    """
+    if skill_only:
+        matrix_item = get_matrix(name)
+        if not matrix_item:
+            click.secho(f"Matrix '{name}' not found.", fg="red", err=True)
+            raise SystemExit(EXIT_FAIL)
+        rendered_skill_path = render_matrix_skill_file(matrix_item, installed=get_installed())
+        click.echo(f"  Local matrix skill: {rendered_skill_path}")
+        click.echo(f"  Install CLIs: cli-hub matrix install {matrix_item['name']}")
+        return
+
+    if dry_run:
+        ok, payload = plan_matrix_install(name, capability=capability, recipe=recipe, only=only)
+        if not ok:
+            if as_json:
+                click.echo(json_mod.dumps({"error": payload["error"]}, indent=2))
+            else:
+                click.secho(f"✗ {payload['error']}", fg="red", err=True)
+            raise SystemExit(EXIT_USAGE if payload.get("arg_error") else EXIT_FAIL)
+        if as_json:
+            data = {k: payload[k] for k in ("scope", "scope_label", "plan", "not_managed", "summary")}
+            data["matrix"] = payload["matrix"]["name"]
+            click.echo(json_mod.dumps(data, indent=2))
+        else:
+            _render_dry_run(payload)
+        return
+
+    success, payload = install_matrix(
+        name, capability=capability, recipe=recipe, only=only, resume=resume
+    )
+    if payload.get("error"):
+        if as_json:
+            click.echo(json_mod.dumps({"error": payload["error"]}, indent=2))
+        else:
+            click.secho(f"✗ {payload['error']}", fg="red", err=True)
+        raise SystemExit(EXIT_USAGE if payload.get("arg_error") else EXIT_FAIL)
+
+    matrix_item = payload["matrix"]
+    summary = payload["summary"]
+
+    if as_json:
+        data = {
+            "matrix": matrix_item["name"],
+            "scope": payload.get("scope"),
+            "results": payload["results"],
+            "summary": summary,
+            "rendered_skill_path": payload.get("rendered_skill_path"),
+        }
+        click.echo(json_mod.dumps(data, indent=2))
+    else:
+        if payload.get("nothing_to_resume"):
+            click.secho(f"  Nothing to resume — last install of {name} had no failures.", fg="green")
+            return
+        scope_label = payload.get("scope_label", "full matrix")
+        click.echo(f"Installing matrix {name} ({scope_label})...")
+        if not payload["results"]:
+            click.secho("  No cli-hub-managed CLIs in this scope.", fg="yellow")
+            click.echo(f"  Check provider availability: cli-hub matrix preflight {name} --fix-hints")
+        for result in payload["results"]:
+            status = result["status"]
+            prefix = "✓" if status in {"installed", "skipped"} else "✗"
+            color = "green" if status in {"installed", "skipped"} else "red"
+            click.secho(f"  {prefix} {result['name']}: {result['message']}",
+                        fg=color, err=status == "failed")
+
+        click.echo(
+            f"\n  Summary: {summary['installed']} installed, "
+            f"{summary['skipped']} skipped, {summary['failed']} failed"
+        )
+        if summary["failed"]:
+            click.echo(f"  Retry failures: cli-hub matrix install {matrix_item['name']} --resume")
+        if matrix_item.get("skill_md"):
+            click.echo(f"  Matrix skill: {matrix_item['skill_md']}")
+        if payload.get("rendered_skill_path"):
+            click.echo(f"  Local matrix skill: {payload['rendered_skill_path']}")
+        click.echo(f"  Inspect:      cli-hub matrix info {matrix_item['name']}")
+
+    if summary["failed"]:
+        # Partial failure (some installed) vs. total failure get distinct exit codes.
+        raise SystemExit(EXIT_PARTIAL if summary["installed"] or summary["skipped"] else EXIT_FAIL)
+
+
+@matrix.command("doctor")
+@click.argument("name")
+@click.option("--json", "as_json", is_flag=True, help="Output the audit as JSON.")
+def matrix_doctor(name, as_json):
+    """Audit install completeness for a matrix's CLIs and suggest fixes (F2.3).
+
+    Exit codes: 0 healthy · 3 some CLIs missing or broken · 1 matrix not found.
+    """
+    healthy, payload = doctor_matrix(name)
+    if payload.get("error"):
+        if as_json:
+            click.echo(json_mod.dumps({"error": payload["error"]}, indent=2))
+        else:
+            click.secho(f"✗ {payload['error']}", fg="red", err=True)
+        raise SystemExit(EXIT_FAIL)
+
+    if as_json:
+        data = {k: payload[k] for k in ("last_run", "checks", "summary")}
+        data["matrix"] = payload["matrix"]["name"]
+        click.echo(json_mod.dumps(data, indent=2))
+        raise SystemExit(EXIT_OK if healthy else EXIT_PARTIAL)
+
+    matrix_item = payload["matrix"]
+    summary = payload["summary"]
+    click.secho(f"\n  {matrix_item['display_name']} Doctor", bold=True)
+    if payload.get("last_run"):
+        click.echo(f"  Last install: {payload['last_run']}")
+    for check in payload["checks"]:
+        if check["status"] == "ok":
+            marker = click.style("✓", fg="green")
+        elif check["status"] == "broken":
+            marker = click.style("!", fg="yellow")
+        else:
+            marker = click.style("·", fg="bright_black")
+        click.echo(f"  {marker} {check['name']}: {check['detail']}")
+        if check["fix"]:
+            click.echo(click.style(f"      ↳ fix: {check['fix']}", fg="bright_black"))
+
+    click.echo(f"\n  Summary: {summary['ok']} ok, {summary['broken']} broken, "
+               f"{summary['not_installed']} not installed")
+    raise SystemExit(EXIT_OK if healthy else EXIT_PARTIAL)
+
+
+@matrix.command("recipes")
+@click.option("--search", "query", default=None, help="Filter recipes by id, description, or capability.")
+@click.option("--json", "as_json", is_flag=True, help="Output as JSON.")
+def matrix_recipes(query, as_json):
+    """List task-oriented recipes across all matrices (F1.4)."""
+    recipes = all_recipes(query)
+
+    if as_json:
+        click.echo(json_mod.dumps({"query": query, "recipes": recipes}, indent=2))
+        return
+
+    if not recipes:
+        target = f" matching '{query}'" if query else ""
+        click.echo(f"No recipes found{target}.")
+        return
+
+    for recipe in recipes:
+        name_str = click.style(recipe["id"], bold=True)
+        loc = click.style(f"({recipe['matrix']})", fg="cyan")
+        click.echo(f"\n  {name_str}  {loc}")
+        if recipe["description"]:
+            click.echo(f"    {recipe['description']}")
+        caps = ", ".join(recipe["capabilities_used"])
+        click.echo(f"    capabilities: {caps}")
+        click.echo(
+            f"    Preflight: cli-hub matrix preflight {recipe['matrix']} --recipe {recipe['id']}"
+        )
+
+
 if __name__ == "__main__":
     main()
diff --git a/cli-hub/cli_hub/installer.py b/cli-hub/cli_hub/installer.py
index 0a7451c48..aef36d6fd 100644
--- a/cli-hub/cli_hub/installer.py
+++ b/cli-hub/cli_hub/installer.py
@@ -1,15 +1,19 @@
-"""Install, uninstall, and manage CLIs — dispatches to pip or npm based on source."""
+"""Install, uninstall, and manage CLIs and matrices."""
 
 import json
 import shlex
 import shutil
 import subprocess
 import sys
+from datetime import datetime
 from pathlib import Path
 
 from cli_hub.registry import get_cli
+from cli_hub.matrix import get_matrix, resolve_install_scope, unmanaged_providers
+from cli_hub.matrix_skill import render_matrix_skill_file
 
 INSTALLED_FILE = Path.home() / ".cli-hub" / "installed.json"
+MATRIX_STATE_FILE = Path.home() / ".cli-hub" / "matrix_state.json"
 
 
 def _load_installed():
@@ -26,6 +30,20 @@ def _save_installed(data):
     INSTALLED_FILE.write_text(json.dumps(data, indent=2))
 
 
+def _load_matrix_state():
+    if MATRIX_STATE_FILE.exists():
+        try:
+            return json.loads(MATRIX_STATE_FILE.read_text())
+        except json.JSONDecodeError:
+            pass
+    return {}
+
+
+def _save_matrix_state(data):
+    MATRIX_STATE_FILE.parent.mkdir(parents=True, exist_ok=True)
+    MATRIX_STATE_FILE.write_text(json.dumps(data, indent=2))
+
+
 def _find_npm():
     """Find npm executable. Returns path or None."""
     return shutil.which("npm")
@@ -371,3 +389,216 @@ def update_cli(name):
 def get_installed():
     """Return dict of installed CLIs."""
     return _load_installed()
+
+
+def _scope_label(scope, capabilities=None):
+    """Human-readable label for an install scope (used in state + output)."""
+    scope_type = scope.get("type")
+    if scope_type == "capability":
+        return f"capability {scope.get('value')}"
+    if scope_type == "recipe":
+        return f"recipe {scope.get('value')}"
+    if scope_type == "only":
+        return f"only {', '.join(scope.get('value', []))}"
+    return "full matrix"
+
+
+def plan_matrix_install(name, capability=None, recipe=None, only=None):
+    """Compute what ``matrix install`` would do — no side effects (F2.1).
+
+    Returns ``(ok, payload)``. ``ok`` is false only on lookup/usage errors;
+    ``payload['arg_error']`` distinguishes usage errors (exit 2) from not-found.
+    """
+    matrix_item = get_matrix(name)
+    if matrix_item is None:
+        return False, {"error": f"Matrix '{name}' not found. Use 'cli-hub matrix list' to see available matrices."}
+
+    scope = resolve_install_scope(matrix_item, capability=capability, recipe=recipe, only=only)
+    if scope.get("error"):
+        return False, {"error": scope["error"], "arg_error": True, "matrix": matrix_item}
+
+    installed = set(get_installed())
+    plan = []
+    for cli_name in scope["cli_names"]:
+        cli = get_cli(cli_name)
+        if cli_name in installed:
+            action, via = "skip", (_install_strategy(cli) if cli else None)
+        elif cli is None:
+            action, via = "error", None
+        else:
+            action, via = "install", _install_strategy(cli)
+        plan.append({
+            "name": cli_name,
+            "display_name": cli["display_name"] if cli else cli_name,
+            "action": action,
+            "via": via,
+            "already_installed": cli_name in installed,
+            "found": cli is not None,
+        })
+
+    scope_caps = scope.get("capabilities")
+    cap_objs = None
+    if scope_caps is not None and scope["scope"].get("type") in {"capability", "recipe"}:
+        cap_set = set(scope_caps)
+        cap_objs = [c for c in matrix_item.get("capabilities", []) if c.get("id") in cap_set]
+    not_managed = unmanaged_providers(matrix_item, cap_objs)
+
+    summary = {
+        "total": len(plan),
+        "to_install": sum(1 for p in plan if p["action"] == "install"),
+        "to_skip": sum(1 for p in plan if p["action"] == "skip"),
+        "unresolved": sum(1 for p in plan if p["action"] == "error"),
+    }
+    payload = {
+        "matrix": matrix_item,
+        "scope": scope["scope"],
+        "scope_label": _scope_label(scope["scope"]),
+        "plan": plan,
+        "not_managed": not_managed,
+        "summary": summary,
+    }
+    return True, payload
+
+
+def install_matrix(name, capability=None, recipe=None, only=None, resume=False):
+    """Install the CLIs in a named matrix, optionally scoped (F2.2) or resumed (F2.3).
+
+    Returns ``(success, payload)``. ``payload['arg_error']`` marks usage errors.
+    Records per-CLI outcomes to ``matrix_state.json`` so ``--resume`` and
+    ``matrix doctor`` can act on them.
+    """
+    matrix_item = get_matrix(name)
+    if matrix_item is None:
+        return False, {"error": f"Matrix '{name}' not found. Use 'cli-hub matrix list' to see available matrices."}
+
+    state = _load_matrix_state()
+
+    if resume:
+        if capability or recipe or only:
+            return False, {"error": "Cannot combine --resume with --capability/--recipe/--only.",
+                           "arg_error": True, "matrix": matrix_item}
+        prior = state.get(name)
+        if not prior:
+            return False, {"error": f"No previous install of '{name}' to resume. "
+                                    f"Run 'cli-hub matrix install {name}' first.",
+                           "arg_error": True, "matrix": matrix_item}
+        target_names = [r["name"] for r in prior.get("results", []) if r.get("status") == "failed"]
+        scope = prior.get("scope", {"type": "all"})
+        if not target_names:
+            return True, {"matrix": matrix_item, "results": [], "scope": scope,
+                          "scope_label": _scope_label(scope),
+                          "summary": {"total": 0, "installed": 0, "skipped": 0, "failed": 0},
+                          "resumed": True, "nothing_to_resume": True}
+    else:
+        scope_info = resolve_install_scope(matrix_item, capability=capability, recipe=recipe, only=only)
+        if scope_info.get("error"):
+            return False, {"error": scope_info["error"], "arg_error": True, "matrix": matrix_item}
+        target_names = scope_info["cli_names"]
+        scope = scope_info["scope"]
+
+    installed = set(get_installed())
+    results = []
+
+    for cli_name in target_names:
+        cli = get_cli(cli_name)
+        display_name = cli["display_name"] if cli else cli_name
+        via = _install_strategy(cli) if cli else None
+
+        if cli_name in installed:
+            results.append({"name": cli_name, "display_name": display_name,
+                            "status": "skipped", "via": via, "message": "Already installed"})
+            continue
+
+        if cli is None:
+            results.append({"name": cli_name, "display_name": display_name,
+                            "status": "failed", "via": via, "message": "CLI not found in registry"})
+            continue
+
+        success, msg = install_cli(cli_name)
+        results.append({"name": cli_name, "display_name": display_name,
+                        "status": "installed" if success else "failed", "via": via, "message": msg})
+        if success:
+            installed.add(cli_name)
+
+    summary = {
+        "total": len(results),
+        "installed": sum(1 for result in results if result["status"] == "installed"),
+        "skipped": sum(1 for result in results if result["status"] == "skipped"),
+        "failed": sum(1 for result in results if result["status"] == "failed"),
+    }
+
+    state[name] = {
+        "last_run": datetime.now().isoformat(timespec="seconds"),
+        "scope": scope,
+        "results": results,
+    }
+    _save_matrix_state(state)
+
+    installed_state = get_installed()
+    rendered_skill_path = render_matrix_skill_file(matrix_item, installed=installed_state)
+    payload = {
+        "matrix": matrix_item,
+        "results": results,
+        "scope": scope,
+        "scope_label": _scope_label(scope),
+        "summary": summary,
+        "resumed": resume,
+        "rendered_skill_path": str(rendered_skill_path),
+    }
+    return summary["failed"] == 0, payload
+
+
+def doctor_matrix(name):
+    """Audit install completeness for a matrix's CLIs against the environment (F2.3).
+
+    Unlike preflight (which reports provider availability for selection), doctor
+    checks whether the matrix's own ``clis[]`` are installed and on PATH, and
+    emits a fix command per broken/missing member.
+    """
+    matrix_item = get_matrix(name)
+    if matrix_item is None:
+        return False, {"error": f"Matrix '{name}' not found. Use 'cli-hub matrix list' to see available matrices."}
+
+    installed = get_installed()
+    state = _load_matrix_state().get(name)
+    checks = []
+    for cli_name in matrix_item.get("clis", []):
+        cli = get_cli(cli_name)
+        entry_point = cli.get("entry_point") if cli else None
+        record = installed.get(cli_name)
+
+        if record is None:
+            status = "not_installed"
+            detail = "Not installed"
+            fix = f"cli-hub install {cli_name}"
+        elif entry_point and not _command_exists(entry_point):
+            status = "broken"
+            detail = f"Recorded as installed but '{entry_point}' is not on PATH"
+            fix = f"cli-hub install {cli_name}"
+        else:
+            status = "ok"
+            detail = "Installed"
+            fix = None
+
+        checks.append({
+            "name": cli_name,
+            "entry_point": entry_point,
+            "status": status,
+            "detail": detail,
+            "fix": fix,
+        })
+
+    summary = {
+        "total": len(checks),
+        "ok": sum(1 for check in checks if check["status"] == "ok"),
+        "broken": sum(1 for check in checks if check["status"] == "broken"),
+        "not_installed": sum(1 for check in checks if check["status"] == "not_installed"),
+    }
+    payload = {
+        "matrix": matrix_item,
+        "last_run": state.get("last_run") if state else None,
+        "checks": checks,
+        "summary": summary,
+    }
+    healthy = summary["broken"] == 0 and summary["not_installed"] == 0
+    return healthy, payload
diff --git a/cli-hub/cli_hub/matrix.py b/cli-hub/cli_hub/matrix.py
new file mode 100644
index 000000000..865b5a6b8
--- /dev/null
+++ b/cli-hub/cli_hub/matrix.py
@@ -0,0 +1,537 @@
+"""Fetch, cache, and query curated CLI workflow matrices."""
+
+import importlib.metadata
+import importlib.util
+import json
+import os
+import shutil
+import time
+from pathlib import Path
+
+import requests
+
+MATRIX_REGISTRY_URL = "https://hkuds.github.io/CLI-Anything/matrix_registry.json"
+MATRIX_CACHE_FILE = Path.home() / ".cli-hub" / "matrix_registry_cache.json"
+CACHE_TTL = 3600  # 1 hour
+
+AGENT_INSTALLABLE_KINDS = {"agent-skill"}
+
+# Provider kinds whose CLIs `matrix install` can manage via cli-hub / public registries.
+INSTALLABLE_KINDS = {"harness-cli", "public-cli"}
+
+# Harness CLI providers are named `cli-anything-<cli>`; the flat `clis[]` list uses `<cli>`.
+HARNESS_PREFIX = "cli-anything-"
+
+# Short, stable labels for provider kinds used across search / can / preflight output.
+KIND_LABELS = {
+    "harness-cli": "harness",
+    "public-cli": "public",
+    "python": "python",
+    "native": "native",
+    "api": "api",
+    "agent-skill": "skill",
+    "agent-native": "native",
+    "web-search": "web",
+}
+
+
+def _ensure_cache_dir():
+    MATRIX_CACHE_FILE.parent.mkdir(parents=True, exist_ok=True)
+
+
+def _load_cached_data():
+    if not MATRIX_CACHE_FILE.exists():
+        return None
+    try:
+        cached = json.loads(MATRIX_CACHE_FILE.read_text())
+        return cached["data"]
+    except (json.JSONDecodeError, KeyError):
+        return None
+
+
+def _load_local_registry():
+    """Load matrix_registry.json from a source checkout when available."""
+    for parent in Path(__file__).resolve().parents:
+        candidate = parent / "matrix_registry.json"
+        if not candidate.exists():
+            continue
+        try:
+            return json.loads(candidate.read_text())
+        except json.JSONDecodeError:
+            return None
+    return None
+
+
+def fetch_matrix_registry(force_refresh=False):
+    """Fetch the matrix registry with local file caching."""
+    _ensure_cache_dir()
+
+    if not force_refresh and MATRIX_CACHE_FILE.exists():
+        try:
+            cached = json.loads(MATRIX_CACHE_FILE.read_text())
+            if time.time() - cached.get("_cached_at", 0) < CACHE_TTL:
+                return cached["data"]
+        except (json.JSONDecodeError, KeyError):
+            pass
+
+    try:
+        resp = requests.get(MATRIX_REGISTRY_URL, timeout=15)
+        resp.raise_for_status()
+        data = resp.json()
+    except (requests.RequestException, ValueError):
+        cached_data = _load_cached_data()
+        if cached_data is not None:
+            return cached_data
+        local_data = _load_local_registry()
+        if local_data is not None:
+            return local_data
+        raise
+
+    MATRIX_CACHE_FILE.write_text(json.dumps({"_cached_at": time.time(), "data": data}, indent=2))
+    return data
+
+
+def fetch_all_matrices(force_refresh=False):
+    """Return all matrix entries."""
+    return fetch_matrix_registry(force_refresh).get("matrices", [])
+
+
+def get_matrix(name, force_refresh=False):
+    """Look up a matrix entry by name (case-insensitive)."""
+    name_lower = name.lower()
+    for matrix_item in fetch_all_matrices(force_refresh):
+        if matrix_item["name"].lower() == name_lower:
+            return matrix_item
+    return None
+
+
+def _string_values(value):
+    """Yield lowercase strings from nested matrix registry values."""
+    if isinstance(value, str):
+        yield value.lower()
+    elif isinstance(value, dict):
+        for child in value.values():
+            yield from _string_values(child)
+    elif isinstance(value, list):
+        for child in value:
+            yield from _string_values(child)
+
+
+def search_matrices(query, force_refresh=False):
+    """Search matrices by name, capabilities, providers, recipes, or gaps."""
+    query_lower = query.lower()
+    results = []
+    for matrix_item in fetch_all_matrices(force_refresh):
+        haystack_values = {
+            "name": matrix_item.get("name", ""),
+            "display_name": matrix_item.get("display_name", ""),
+            "description": matrix_item.get("description", ""),
+            "category": matrix_item.get("category", ""),
+            "matrix_id": matrix_item.get("matrix_id", ""),
+            "capabilities": matrix_item.get("capabilities", []),
+            "recipes": matrix_item.get("recipes", []),
+            "known_gaps": matrix_item.get("known_gaps", []),
+            "clis": matrix_item.get("clis", []),
+        }
+        if any(query_lower in value for value in _string_values(haystack_values)):
+            results.append(matrix_item)
+    return results
+
+
+def _as_list(value):
+    """Normalize registry requirement fields to lists."""
+    if value is None:
+        return []
+    if isinstance(value, list):
+        return value
+    return [value]
+
+
+def _package_available(name):
+    try:
+        if importlib.util.find_spec(name) is not None:
+            return True
+    except Exception:
+        pass
+    try:
+        normalized = name.replace("-", "_")
+        if normalized != name and importlib.util.find_spec(normalized) is not None:
+            return True
+    except Exception:
+        pass
+    try:
+        importlib.metadata.version(name)
+        return True
+    except Exception:
+        pass
+    return False
+
+
+def check_provider_requirements(provider):
+    """Check whether a provider's declared requirements are available locally."""
+    kind = provider.get("kind", "")
+    if kind in AGENT_INSTALLABLE_KINDS:
+        return {
+            "name": provider.get("name", ""),
+            "kind": kind,
+            "available": False,
+            "agent_installable": True,
+            "status": "agent-installable",
+            "offline": bool(provider.get("offline")),
+            "cost_tier": provider.get("cost_tier", "unknown"),
+            "quality_tier": provider.get("quality_tier", "unknown"),
+            "requires": provider.get("requires") or {},
+            "present": {"env": [], "binary": [], "package": []},
+            "missing": {"env": [], "binary": [], "package": []},
+            "notes": provider.get("notes", ""),
+            "install_hint": provider.get("install_hint"),
+        }
+
+    requires = provider.get("requires") or {}
+    env_names = _as_list(requires.get("env"))
+    binary_names = _as_list(requires.get("binary"))
+    package_names = _as_list(requires.get("package"))
+
+    present = {
+        "env": [name for name in env_names if os.environ.get(name)],
+        "binary": [name for name in binary_names if shutil.which(name)],
+        "package": [name for name in package_names if _package_available(name)],
+    }
+    missing = {
+        "env": [name for name in env_names if name not in present["env"]],
+        "binary": [name for name in binary_names if name not in present["binary"]],
+        "package": [name for name in package_names if name not in present["package"]],
+    }
+    available = not any(missing.values())
+
+    return {
+        "name": provider.get("name", ""),
+        "kind": kind,
+        "available": available,
+        "agent_installable": False,
+        "status": "available" if available else "missing",
+        "offline": bool(provider.get("offline")),
+        "cost_tier": provider.get("cost_tier", "unknown"),
+        "quality_tier": provider.get("quality_tier", "unknown"),
+        "requires": requires,
+        "present": present,
+        "missing": missing,
+        "notes": provider.get("notes", ""),
+        "install_hint": provider.get("install_hint"),
+    }
+
+
+def preflight_matrix(matrix_item, capability_id=None, offline=False, capability_ids=None):
+    """Return provider availability for a matrix, optionally filtered.
+
+    ``capability_id`` filters to a single capability; ``capability_ids`` (a set or
+    list, used by ``--recipe``) filters to a named subset. The two compose.
+    """
+    id_filter = set(capability_ids) if capability_ids is not None else None
+    capability_results = []
+
+    for capability in matrix_item.get("capabilities", []):
+        if capability_id and capability.get("id") != capability_id:
+            continue
+        if id_filter is not None and capability.get("id") not in id_filter:
+            continue
+
+        provider_results = [
+            check_provider_requirements(provider)
+            for provider in capability.get("providers", [])
+            if not offline or provider.get("offline")
+        ]
+        capability_results.append({
+            "id": capability.get("id", ""),
+            "intent": capability.get("intent", ""),
+            "provider_count": len(provider_results),
+            "available_count": sum(1 for provider in provider_results if provider["available"]),
+            "agent_installable_count": sum(
+                1 for provider in provider_results
+                if provider.get("agent_installable")
+            ),
+            "providers": provider_results,
+        })
+
+    summary = {
+        "capabilities": len(capability_results),
+        "with_available_provider": sum(1 for cap in capability_results if cap["available_count"] > 0),
+        "with_agent_installable_provider": sum(
+            1 for cap in capability_results
+            if cap["available_count"] == 0 and cap["agent_installable_count"] > 0
+        ),
+        "providers": sum(cap["provider_count"] for cap in capability_results),
+        "available_providers": sum(cap["available_count"] for cap in capability_results),
+        "agent_installable_providers": sum(
+            cap["agent_installable_count"] for cap in capability_results
+        ),
+    }
+    # A capability is "covered" when it has at least one available provider or an
+    # agent-installable fallback; everything else is a hard gap (drives exit code 3).
+    summary["covered"] = sum(
+        1 for cap in capability_results
+        if cap["available_count"] > 0 or cap["agent_installable_count"] > 0
+    )
+    summary["gaps"] = summary["capabilities"] - summary["covered"]
+
+    return {
+        "matrix": {
+            "name": matrix_item.get("name", ""),
+            "display_name": matrix_item.get("display_name", matrix_item.get("name", "")),
+            "schema_version": matrix_item.get("schema_version", "1"),
+        },
+        "capability_filter": capability_id,
+        "offline": offline,
+        "summary": summary,
+        "capabilities": capability_results,
+    }
+
+
+# ── Provider ↔ CLI resolution and install scoping (F2.2) ──────────────────────
+
+
+def provider_cli_name(provider, cli_names):
+    """Resolve a provider to the ``clis[]`` member that ``matrix install`` manages.
+
+    Returns the registry CLI name, or ``None`` when the provider is not installable
+    through cli-hub (Python libs, native binaries, cloud APIs, agent skills, or
+    third-party public CLIs that live outside the matrix's ``clis[]`` list).
+    """
+    if provider.get("kind") not in INSTALLABLE_KINDS:
+        return None
+    cli_set = set(cli_names)
+    explicit = provider.get("cli")  # forward-compatible with schema v2.1 (F4.2)
+    if explicit and explicit in cli_set:
+        return explicit
+    name = provider.get("name", "")
+    if name in cli_set:
+        return name
+    if name.startswith(HARNESS_PREFIX):
+        stripped = name[len(HARNESS_PREFIX):]
+        if stripped in cli_set:
+            return stripped
+    return None
+
+
+def provider_install_hint(provider, cli_names):
+    """Return a human-readable install command for a provider, or ``None``.
+
+    Prefers the registry's explicit ``install_hint`` (F2.4); otherwise derives
+    ``cli-hub install <cli>`` for providers that map into the matrix's ``clis[]``.
+    """
+    hint = provider.get("install_hint")
+    if hint:
+        return hint
+    cli = provider_cli_name(provider, cli_names)
+    if cli:
+        return f"cli-hub install {cli}"
+    return None
+
+
+def get_recipe(matrix_item, recipe_id):
+    """Look up a recipe entry by id (case-insensitive)."""
+    recipe_lower = recipe_id.lower()
+    for recipe in matrix_item.get("recipes", []):
+        if recipe.get("id", "").lower() == recipe_lower:
+            return recipe
+    return None
+
+
+def _scope_clis_for_capabilities(matrix_item, capabilities):
+    """Return the ``clis[]`` members backing the given capabilities, in registry order."""
+    cli_names = matrix_item.get("clis", [])
+    wanted = set()
+    for capability in capabilities:
+        for provider in capability.get("providers", []):
+            cli = provider_cli_name(provider, cli_names)
+            if cli:
+                wanted.add(cli)
+    return [name for name in cli_names if name in wanted]
+
+
+def resolve_install_scope(matrix_item, capability=None, recipe=None, only=None):
+    """Resolve install scope flags to a concrete subset of the matrix's ``clis[]``.
+
+    Returns a dict with ``cli_names`` (ordered subset), ``scope`` (type/value),
+    ``capabilities`` (capability ids in scope, when applicable), and ``error``
+    (a usage message when the selectors are invalid or mutually exclusive).
+    """
+    cli_names = matrix_item.get("clis", [])
+    selectors = [(kind, value) for kind, value in
+                 (("capability", capability), ("recipe", recipe), ("only", only)) if value]
+
+    if len(selectors) > 1:
+        return {"error": "Use only one of --capability, --recipe, or --only.",
+                "scope": {"type": "invalid"}, "cli_names": [], "capabilities": []}
+
+    if not selectors:
+        return {"error": None, "scope": {"type": "all"}, "cli_names": list(cli_names),
+                "capabilities": [c.get("id") for c in matrix_item.get("capabilities", [])]}
+
+    sel_type, sel_value = selectors[0]
+
+    if sel_type == "only":
+        requested = [name.strip() for name in only.split(",") if name.strip()]
+        unknown = [name for name in requested if name not in set(cli_names)]
+        if unknown:
+            return {"error": (f"Not in matrix '{matrix_item.get('name')}' clis[]: "
+                              f"{', '.join(unknown)}. Valid: {', '.join(cli_names) or '(none)'}"),
+                    "scope": {"type": "only"}, "cli_names": [], "capabilities": []}
+        chosen = [name for name in cli_names if name in set(requested)]
+        return {"error": None, "scope": {"type": "only", "value": requested},
+                "cli_names": chosen, "capabilities": []}
+
+    if sel_type == "capability":
+        capability_item = next(
+            (c for c in matrix_item.get("capabilities", []) if c.get("id") == capability), None)
+        if capability_item is None:
+            valid = ", ".join(c.get("id", "") for c in matrix_item.get("capabilities", []))
+            return {"error": (f"Capability '{capability}' not found in "
+                              f"'{matrix_item.get('name')}'. Valid: {valid or '(none)'}"),
+                    "scope": {"type": "capability"}, "cli_names": [], "capabilities": []}
+        return {"error": None, "scope": {"type": "capability", "value": capability},
+                "cli_names": _scope_clis_for_capabilities(matrix_item, [capability_item]),
+                "capabilities": [capability]}
+
+    # sel_type == "recipe"
+    recipe_item = get_recipe(matrix_item, recipe)
+    if recipe_item is None:
+        valid = ", ".join(r.get("id", "") for r in matrix_item.get("recipes", []))
+        return {"error": (f"Recipe '{recipe}' not found in '{matrix_item.get('name')}'. "
+                          f"Valid: {valid or '(none)'}"),
+                "scope": {"type": "recipe"}, "cli_names": [], "capabilities": []}
+    used = recipe_item.get("capabilities_used", [])
+    used_set = set(used)
+    capabilities = [c for c in matrix_item.get("capabilities", []) if c.get("id") in used_set]
+    return {"error": None, "scope": {"type": "recipe", "value": recipe},
+            "cli_names": _scope_clis_for_capabilities(matrix_item, capabilities),
+            "capabilities": list(used)}
+
+
+def unmanaged_providers(matrix_item, capabilities=None):
+    """Group providers that ``matrix install`` does NOT install, by category.
+
+    Used by ``install --dry-run`` to show what still needs manual setup
+    (Python libs, native binaries, cloud APIs, agent skills, and third-party
+    public CLIs outside ``clis[]``).
+    """
+    cli_names = matrix_item.get("clis", [])
+    caps = capabilities if capabilities is not None else matrix_item.get("capabilities", [])
+    buckets = {"python": [], "native": [], "api": [], "agent-skill": [], "public-unmanaged": []}
+    seen = set()
+    for capability in caps:
+        for provider in capability.get("providers", []):
+            kind = provider.get("kind")
+            name = provider.get("name", "")
+            key = (kind, name)
+            if key in seen:
+                continue
+            if kind in INSTALLABLE_KINDS:
+                if kind == "public-cli" and provider_cli_name(provider, cli_names) is None:
+                    buckets["public-unmanaged"].append(name)
+                    seen.add(key)
+                continue
+            if kind in buckets:
+                buckets[kind].append(name)
+                seen.add(key)
+    return {category: names for category, names in buckets.items() if names}
+
+
+# ── Capability-level search (F1.1 / F1.4) ─────────────────────────────────────
+
+
+def providers_summary(capability, limit=4):
+    """Render a compact 'name (kind) · …' summary of a capability's providers."""
+    providers = capability.get("providers", [])
+    parts = [
+        f"{p.get('name', '')} ({KIND_LABELS.get(p.get('kind'), p.get('kind', '?'))})"
+        for p in providers[:limit]
+    ]
+    summary = " · ".join(parts)
+    extra = len(providers) - limit
+    if extra > 0:
+        summary += f" · +{extra} more"
+    return summary
+
+
+def _capability_match_field(capability, query_lower):
+    """Return which field of a capability matched the query, or ``None``."""
+    if query_lower in capability.get("id", "").lower():
+        return "id"
+    if query_lower in capability.get("intent", "").lower():
+        return "intent"
+    if any(query_lower in hint.lower() for hint in capability.get("skill_search_hints", [])):
+        return "hint"
+    for provider in capability.get("providers", []):
+        if query_lower in provider.get("name", "").lower():
+            return "provider"
+    return None
+
+
+def capability_matches(matrix_item, query_lower):
+    """Return per-capability match attribution for a single matrix (F1.1 matched_in)."""
+    matches = []
+    for capability in matrix_item.get("capabilities", []):
+        field = _capability_match_field(capability, query_lower)
+        if not field:
+            continue
+        matches.append({
+            "matrix": matrix_item.get("name", ""),
+            "matrix_id": matrix_item.get("matrix_id", ""),
+            "capability_id": capability.get("id", ""),
+            "intent": capability.get("intent", ""),
+            "match_field": field,
+            "providers_summary": providers_summary(capability),
+        })
+    return matches
+
+
+def search_capabilities(query, force_refresh=False):
+    """Search every matrix at capability granularity (powers ``cli-hub can``).
+
+    Each hit carries local provider availability so callers can show what is
+    usable on this machine right now.
+    """
+    query_lower = query.lower()
+    hits = []
+    for matrix_item in fetch_all_matrices(force_refresh):
+        for capability in matrix_item.get("capabilities", []):
+            field = _capability_match_field(capability, query_lower)
+            if not field:
+                continue
+            hits.append({
+                "matrix": matrix_item.get("name", ""),
+                "matrix_id": matrix_item.get("matrix_id", ""),
+                "capability_id": capability.get("id", ""),
+                "intent": capability.get("intent", ""),
+                "match_field": field,
+                "providers": [
+                    check_provider_requirements(provider)
+                    for provider in capability.get("providers", [])
+                ],
+            })
+    return hits
+
+
+def all_recipes(query=None, force_refresh=False):
+    """Return recipes across all matrices, optionally filtered by a query (F1.4)."""
+    query_lower = query.lower() if query else None
+    out = []
+    for matrix_item in fetch_all_matrices(force_refresh):
+        for recipe in matrix_item.get("recipes", []):
+            if query_lower:
+                haystack = " ".join([
+                    recipe.get("id", ""),
+                    recipe.get("description", ""),
+                    " ".join(recipe.get("capabilities_used", [])),
+                ]).lower()
+                if query_lower not in haystack:
+                    continue
+            out.append({
+                "matrix": matrix_item.get("name", ""),
+                "matrix_id": matrix_item.get("matrix_id", ""),
+                "id": recipe.get("id", ""),
+                "description": recipe.get("description", ""),
+                "capabilities_used": recipe.get("capabilities_used", []),
+            })
+    return out
diff --git a/cli-hub/cli_hub/matrix_skill.py b/cli-hub/cli_hub/matrix_skill.py
new file mode 100644
index 000000000..f2d9f2cf1
--- /dev/null
+++ b/cli-hub/cli_hub/matrix_skill.py
@@ -0,0 +1,397 @@
+"""Render local matrix skill files with resolved CLI skill paths.
+
+Installed layout (one directory per matrix, so the skill's relative links to
+``references/*.md`` and ``scripts/*.py`` resolve):
+
+    ~/.cli-hub/matrix/<name>/SKILL.md
+    ~/.cli-hub/matrix/<name>/references/...
+    ~/.cli-hub/matrix/<name>/scripts/...
+
+Skill content source lookup chain:
+
+1. Repo checkout: ``<repo_root>/cli-hub-matrix/<name>/`` (via ``skill_md``).
+2. Bundled package data: ``cli_hub/_matrix_data/<name>/`` (shipped in
+   wheels/sdists built from a checkout; absent in editable installs, which
+   hit the checkout in step 1 instead).
+3. Published URL: ``https://hkuds.github.io/CLI-Anything/matrix/<name>/SKILL.md``
+   (SKILL.md only; references/scripts stay remote and are linked from the
+   rendered file).
+4. Generated stub.
+"""
+
+import shutil
+import subprocess
+from importlib import metadata
+from pathlib import Path
+
+import requests
+
+from cli_hub.registry import get_cli
+
+MATRIX_SKILL_DIR = Path.home() / ".cli-hub" / "matrix"
+
+# Base URL where deploy-pages.yml publishes cli-hub-matrix/ content (main only).
+MATRIX_CONTENT_BASE_URL = "https://hkuds.github.io/CLI-Anything/matrix"
+
+# Package data dir bundled into wheels/sdists by cli-hub/setup.py.
+BUNDLED_MATRIX_DATA_DIR = Path(__file__).resolve().parent / "_matrix_data"
+
+# Asset directories co-installed beside the rendered SKILL.md.
+MATRIX_ASSET_SUBDIRS = ("references", "scripts")
+
+_COPY_IGNORE = shutil.ignore_patterns("__pycache__", "*.pyc", "*.pyo")
+
+
+def _find_repo_root():
+    """Find the repository root via git, falling back to parent traversal."""
+    try:
+        result = subprocess.run(
+            ["git", "rev-parse", "--show-toplevel"],
+            capture_output=True, text=True, timeout=5,
+        )
+        if result.returncode == 0:
+            root = Path(result.stdout.strip())
+            if root.is_dir():
+                return root
+    except (FileNotFoundError, subprocess.TimeoutExpired):
+        pass
+
+    # Fallback: walk up from this file looking for .git
+    current = Path(__file__).resolve().parent
+    for parent in [current] + list(current.parents):
+        if (parent / ".git").exists():
+            return parent
+
+    return None
+
+
+def get_rendered_matrix_skill_path(name):
+    """Return the local rendered SKILL.md path for a matrix.
+
+    Prefers the per-matrix directory layout (``<name>/SKILL.md``); falls back
+    to the legacy flat ``<name>.SKILL.md`` file when only that exists, so
+    pre-existing installs keep resolving until the next re-render.
+    """
+    current = MATRIX_SKILL_DIR / name / "SKILL.md"
+    legacy = MATRIX_SKILL_DIR / f"{name}.SKILL.md"
+    if not current.exists() and legacy.exists():
+        return legacy
+    return current
+
+
+def resolve_local_skill_path(cli):
+    """Resolve an installed harness CLI's local SKILL.md path if possible."""
+    if cli.get("_source", "harness") != "harness":
+        return None
+
+    dist_name = cli.get("dist_name") or f"cli-anything-{cli['name']}"
+    try:
+        dist = metadata.distribution(dist_name)
+    except metadata.PackageNotFoundError:
+        return _fallback_repo_skill_path(cli)
+
+    for file in dist.files or []:
+        file_str = str(file).replace("\\", "/")
+        if file_str.endswith("/skills/SKILL.md") or file_str.endswith("skills/SKILL.md"):
+            return str(dist.locate_file(file).resolve())
+
+    return _fallback_repo_skill_path(cli)
+
+
+def _fallback_repo_skill_path(cli):
+    """Use the repo-relative skill path when available in the current checkout."""
+    skill_ref = cli.get("skill_md")
+    if not skill_ref or "://" in skill_ref or skill_ref.startswith("npx "):
+        return None
+
+    repo_root = _find_repo_root()
+    if repo_root is None:
+        return None
+    candidate = repo_root / skill_ref
+    if candidate.exists():
+        return str(candidate.resolve())
+    return None
+
+
+def render_matrix_skill_file(matrix_item, installed=None):
+    """Write a local matrix SKILL.md with resolved member skill paths.
+
+    Renders into ``MATRIX_SKILL_DIR/<name>/SKILL.md`` and co-installs the
+    matrix content directory's ``references/`` and ``scripts/`` beside it so
+    the skill's relative links resolve. Re-rendering is idempotent: asset
+    directories are replaced wholesale on each render.
+    """
+    name = matrix_item["name"]
+    output_dir = MATRIX_SKILL_DIR / name
+    output_dir.mkdir(parents=True, exist_ok=True)
+    output_path = output_dir / "SKILL.md"
+
+    template_path, content_dir = _resolve_matrix_content_source(matrix_item)
+    base_content = _load_matrix_skill_template(matrix_item, template_path).rstrip()
+    copied = _copy_matrix_assets(content_dir, output_dir) if content_dir else []
+
+    extra = ""
+    if not copied:
+        extra = (
+            "\n\n## Reference Modules\n\n"
+            "No local copy of this matrix's `references/` and `scripts/` was "
+            "found; relative links above will not resolve locally. The "
+            "published copies live under "
+            f"{MATRIX_CONTENT_BASE_URL}/{name}/ (e.g. "
+            f"{MATRIX_CONTENT_BASE_URL}/{name}/SKILL.md)."
+        )
+
+    injected_section = _render_injected_section(matrix_item, installed or {})
+    output_path.write_text(
+        f"{base_content}\n\n<!-- MATRIX_SKILL_PATHS:START -->\n\n{injected_section}{extra}\n\n<!-- MATRIX_SKILL_PATHS:END -->\n",
+        encoding="utf-8",
+    )
+    return output_path
+
+
+def _resolve_matrix_content_source(matrix_item):
+    """Locate the matrix skill source as ``(template_path, content_dir)``.
+
+    Tries the repo checkout first, then bundled package data. Either element
+    may be ``None`` when nothing local is available (the template then falls
+    back to the published URL or a stub).
+    """
+    skill_ref = matrix_item.get("skill_md")
+    if skill_ref and "://" not in skill_ref and not skill_ref.startswith("npx "):
+        repo_root = _find_repo_root()
+        if repo_root is not None:
+            candidate = repo_root / skill_ref
+            if candidate.exists():
+                return candidate, candidate.parent
+
+    bundled = BUNDLED_MATRIX_DATA_DIR / matrix_item["name"] / "SKILL.md"
+    if bundled.exists():
+        return bundled, bundled.parent
+
+    return None, None
+
+
+def _copy_matrix_assets(content_dir, output_dir):
+    """Copy references/ and scripts/ beside the rendered SKILL.md.
+
+    Existing asset directories are removed first so re-installs are clean and
+    stale files do not linger. ``__pycache__`` and ``*.pyc`` are excluded.
+    Returns the list of subdirectories that were copied.
+    """
+    copied = []
+    for subdir in MATRIX_ASSET_SUBDIRS:
+        source = content_dir / subdir
+        destination = output_dir / subdir
+        if destination.exists():
+            shutil.rmtree(destination)
+        if source.is_dir():
+            shutil.copytree(source, destination, ignore=_COPY_IGNORE)
+            copied.append(subdir)
+    return copied
+
+
+def _load_matrix_skill_template(matrix_item, template_path=None):
+    """Load the matrix skill template via the lookup chain.
+
+    Order: local source file (checkout or bundled data) -> published URL ->
+    generated stub.
+    """
+    if template_path is None:
+        template_path, _ = _resolve_matrix_content_source(matrix_item)
+    if template_path is not None:
+        return template_path.read_text(encoding="utf-8")
+
+    published = _fetch_published_matrix_skill(matrix_item["name"])
+    if published is not None:
+        return published
+
+    title = matrix_item.get("display_name", matrix_item["name"])
+    description = matrix_item.get("description", "")
+    return (
+        f"# {title}\n\n"
+        f"{description}\n\n"
+        f"Install with `cli-hub matrix install {matrix_item['name']}`.\n\n"
+        f"Full skill content (when published): "
+        f"{MATRIX_CONTENT_BASE_URL}/{matrix_item['name']}/SKILL.md"
+    )
+
+
+def _fetch_published_matrix_skill(name):
+    """Fetch the published SKILL.md for a matrix, or None on any failure."""
+    url = f"{MATRIX_CONTENT_BASE_URL}/{name}/SKILL.md"
+    try:
+        resp = requests.get(url, timeout=10)
+    except requests.RequestException:
+        return None
+    if resp.status_code != 200 or not resp.text.strip():
+        return None
+    return resp.text
+
+
+def _render_injected_section(matrix_item, installed):
+    """Render the injected skill reference section."""
+    lines = [
+        "## Installed CLI Skills",
+        "",
+        "Generated by `cli-hub matrix install` from the current local environment.",
+        "",
+        "| CLI | Entry Point | Canonical Skill | Local Skill | Status |",
+        "|---|---|---|---|---|",
+    ]
+
+    for cli_name in matrix_item.get("clis", []):
+        cli = get_cli(cli_name) or {"name": cli_name, "entry_point": cli_name}
+        canonical_skill = cli.get("skill_md") or "—"
+        local_skill = resolve_local_skill_path(cli) or "—"
+        status = "installed" if cli_name in installed else "not installed"
+        lines.append(
+            f"| `{cli_name}` | `{cli.get('entry_point', '—')}` | "
+            f"{canonical_skill} | {local_skill} | {status} |"
+        )
+
+    capability_tooling = _render_capability_tooling(matrix_item, installed)
+    if capability_tooling:
+        lines.append("")
+        lines.append(capability_tooling)
+
+    stage_tooling = _render_stage_tooling(matrix_item, installed)
+    if stage_tooling:
+        lines.append("")
+        lines.append(stage_tooling)
+
+    discovery = _render_discovery_section(matrix_item)
+    if discovery:
+        lines.append("")
+        lines.append(discovery)
+
+    return "\n".join(lines)
+
+
+def _provider_installed(provider, installed):
+    """Return whether a CLI provider appears installed by cli-hub name."""
+    if provider.get("kind") not in {"harness-cli", "public-cli"}:
+        return False
+    name = provider.get("name", "")
+    aliases = {name}
+    if name.startswith("cli-anything-"):
+        aliases.add(name.removeprefix("cli-anything-"))
+    return any(alias in installed for alias in aliases)
+
+
+def _format_requires(provider):
+    requires = provider.get("requires") or {}
+    parts = []
+    for key in ("binary", "env", "package"):
+        values = requires.get(key) or []
+        if isinstance(values, str):
+            values = [values]
+        if values:
+            parts.append(f"{key}: {', '.join(values)}")
+    return "; ".join(parts) if parts else "none"
+
+
+def _render_capability_tooling(matrix_item, installed):
+    """Render v2 capability/provider guidance for local matrix skills."""
+    capabilities = matrix_item.get("capabilities", [])
+    if not capabilities:
+        return ""
+
+    lines = [
+        "## Capability Provider Overview",
+        "",
+        "Pick providers per capability from task constraints and preflight facts. CLI providers show cli-hub install status; non-CLI providers list their preflight requirements.",
+        "",
+    ]
+
+    for capability in capabilities:
+        lines.append(f"### `{capability['id']}`")
+        if capability.get("intent"):
+            lines.append(capability["intent"])
+        lines.append("")
+
+        for provider in capability.get("providers", []):
+            kind = provider.get("kind", "provider")
+            quality = provider.get("quality_tier", "unknown")
+            cost = provider.get("cost_tier", "unknown")
+            offline = "offline" if provider.get("offline") else "online"
+            status = ""
+            if kind in {"harness-cli", "public-cli"}:
+                status = "installed" if _provider_installed(provider, installed) else "not installed"
+                status = f"; {status}"
+            requires = _format_requires(provider)
+            lines.append(
+                f"- `{provider.get('name', '')}` ({kind}; {quality}; {cost}; {offline}{status})"
+            )
+            lines.append(f"  - Requires: {requires}")
+            if provider.get("notes"):
+                lines.append(f"  - Notes: {provider['notes']}")
+
+        lines.append("")
+
+    recipes = matrix_item.get("recipes", [])
+    if recipes:
+        lines.append("## Recipes")
+        lines.append("")
+        for recipe in recipes:
+            capabilities_used = ", ".join(f"`{item}`" for item in recipe.get("capabilities_used", []))
+            lines.append(f"- `{recipe['id']}`: {recipe.get('description', '')}")
+            if capabilities_used:
+                lines.append(f"  - Uses: {capabilities_used}")
+        lines.append("")
+
+    known_gaps = matrix_item.get("known_gaps", [])
+    if known_gaps:
+        lines.append("## Known Gaps")
+        lines.append("")
+        for gap in known_gaps:
+            lines.append(f"- `{gap.get('capability', 'unknown')}`: {gap.get('reason', '')}")
+            if gap.get("workaround"):
+                lines.append(f"  - Workaround: {gap['workaround']}")
+        lines.append("")
+
+    return "\n".join(lines).rstrip()
+
+
+def _render_stage_tooling(matrix_item, installed):
+    """Render per-stage tooling overview with goals and alternatives."""
+    stages = matrix_item.get("stages", [])
+    has_goals = any(s.get("goal") for s in stages)
+    if not has_goals:
+        return ""
+
+    lines = [
+        "## Stage Tooling Overview",
+        "",
+        "What is available for each stage on this system.",
+        "",
+    ]
+
+    for stage in stages:
+        goal = stage.get("goal")
+        if not goal:
+            continue
+
+        lines.append(f"### {stage['name']}")
+        lines.append(f"**Goal:** {goal}")
+        lines.append("")
+
+        for cli_name in stage.get("clis", []):
+            marker = "installed" if cli_name in installed else "not installed"
+            lines.append(f"- CLI: `{cli_name}` ({marker})")
+
+        alts = stage.get("alternatives", {})
+        if alts.get("python"):
+            lines.append(f"- Python: {', '.join(alts['python'])}")
+        if alts.get("api"):
+            lines.append(f"- APIs: {', '.join(alts['api'])}")
+        if alts.get("native"):
+            lines.append(f"- Native: {', '.join(alts['native'])}")
+
+        lines.append("")
+
+    return "\n".join(lines)
+
+
+def _render_discovery_section(matrix_item):
+    """Registry search hints are metadata; generated skills list concrete providers."""
+    return ""
diff --git a/cli-hub/setup.py b/cli-hub/setup.py
index 936899224..6274164ae 100644
--- a/cli-hub/setup.py
+++ b/cli-hub/setup.py
@@ -1,6 +1,52 @@
 """cli-hub — package manager for CLI-Anything harnesses."""
 
+import shutil
+from pathlib import Path
+
 from setuptools import setup, find_packages
+from setuptools.command.build_py import build_py as _build_py
+from setuptools.command.sdist import sdist as _sdist
+
+HERE = Path(__file__).resolve().parent
+
+# Matrix skill content lives at the repo root (outside this package dir).
+# It is vendored into cli_hub/_matrix_data/ at build time so wheels and
+# sdists ship real matrix content for users without a repo checkout.
+# Editable installs (`pip install -e`) do not need the vendored copy: the
+# runtime lookup chain in cli_hub/matrix_skill.py finds the checkout first.
+MATRIX_CONTENT_SOURCE = HERE.parent / "cli-hub-matrix"
+MATRIX_DATA_DIR = HERE / "cli_hub" / "_matrix_data"
+
+
+def _sync_matrix_data():
+    """Vendor cli-hub-matrix/ into cli_hub/_matrix_data/ (build artifact).
+
+    No-op when building from an sdist (the data is already vendored) or when
+    the repo content is unavailable (runtime falls back to the published URL
+    or a stub).
+    """
+    if not MATRIX_CONTENT_SOURCE.is_dir():
+        return
+    if MATRIX_DATA_DIR.exists():
+        shutil.rmtree(MATRIX_DATA_DIR)
+    shutil.copytree(
+        MATRIX_CONTENT_SOURCE,
+        MATRIX_DATA_DIR,
+        ignore=shutil.ignore_patterns("__pycache__", "*.pyc", "*.pyo"),
+    )
+
+
+class build_py(_build_py):
+    def run(self):
+        _sync_matrix_data()
+        super().run()
+
+
+class sdist(_sdist):
+    def run(self):
+        _sync_matrix_data()
+        super().run()
+
 
 setup(
     name="cli-anything-hub",
@@ -19,6 +65,15 @@
     },
     license="MIT",
     packages=find_packages(exclude=["tests", "tests.*"]),
+    cmdclass={"build_py": build_py, "sdist": sdist},
+    include_package_data=True,
+    package_data={
+        "cli_hub": [
+            "_matrix_data/*/SKILL.md",
+            "_matrix_data/*/references/*",
+            "_matrix_data/*/scripts/*",
+        ],
+    },
     python_requires=">=3.10",
     install_requires=[
         "click>=8.0",
diff --git a/cli-hub/tests/test_cli_hub.py b/cli-hub/tests/test_cli_hub.py
index ce2edc365..dba729ac4 100644
--- a/cli-hub/tests/test_cli_hub.py
+++ b/cli-hub/tests/test_cli_hub.py
@@ -12,6 +12,29 @@
 
 from cli_hub import __version__
 from cli_hub.registry import fetch_registry, fetch_all_clis, get_cli, search_clis, list_categories
+from cli_hub.matrix import (
+    _package_available,
+    all_recipes,
+    capability_matches,
+    check_provider_requirements,
+    fetch_matrix_registry,
+    fetch_all_matrices,
+    get_matrix,
+    preflight_matrix,
+    provider_cli_name,
+    provider_install_hint,
+    resolve_install_scope,
+    search_capabilities,
+    search_matrices,
+    unmanaged_providers,
+)
+from cli_hub.matrix_skill import (
+    resolve_local_skill_path,
+    render_matrix_skill_file,
+    _render_capability_tooling,
+    _render_stage_tooling,
+    _render_discovery_section,
+)
 from cli_hub.preview import (
     inspect_bundle,
     inspect_session,
@@ -23,6 +46,7 @@
 )
 from cli_hub.installer import (
     install_cli,
+    install_matrix,
     uninstall_cli,
     get_installed,
     _load_installed,
@@ -85,6 +109,106 @@
     ],
 }
 
+SAMPLE_MATRIX_REGISTRY = {
+    "meta": {"repo": "https://github.com/HKUDS/CLI-Anything", "description": "test matrices"},
+    "matrices": [
+        {
+            "name": "video-creation",
+            "display_name": "Video Creation & Editing",
+            "description": "Curated video workflow matrix",
+            "category": "video",
+            "matrix": "cli-matrix",
+            "matrix_id": "S1",
+            "schema_version": "2",
+            "skill_md": "cli-hub-matrix/video-creation/SKILL.md",
+            "clis": ["gimp", "blender", "audacity"],
+            "stages": [
+                {
+                    "name": "Thumbnail",
+                    "clis": ["gimp"],
+                    "goal": "Create a thumbnail image",
+                    "alternatives": {"python": ["Pillow"], "native": ["ImageMagick convert"]},
+                    "skill_search_hints": ["thumbnail", "image editing"],
+                },
+                {"name": "3D", "clis": ["blender"]},
+                {
+                    "name": "Audio",
+                    "clis": ["audacity"],
+                    "goal": "Edit and process audio",
+                    "alternatives": {"python": ["pydub"], "native": ["sox"]},
+                    "skill_search_hints": ["audio editing"],
+                },
+            ],
+            "capabilities": [
+                {
+                    "id": "package.thumbnail",
+                    "intent": "Create a thumbnail image",
+                    "inputs": ["concept:text"],
+                    "outputs": ["image:path"],
+                    "skill_search_hints": ["thumbnail", "image editing"],
+                    "providers": [
+                        {
+                            "kind": "harness-cli",
+                            "name": "cli-anything-gimp",
+                            "requires": {"binary": ["cli-anything-gimp"]},
+                            "cost_tier": "free",
+                            "quality_tier": "high",
+                            "offline": True,
+                        },
+                        {
+                            "kind": "python",
+                            "name": "Pillow",
+                            "requires": {"package": ["PIL"]},
+                            "cost_tier": "free",
+                            "quality_tier": "good",
+                            "offline": True,
+                        },
+                    ],
+                },
+                {
+                    "id": "audio.capture",
+                    "intent": "Edit and process audio",
+                    "inputs": ["source:mic|file"],
+                    "outputs": ["audio_clip:path"],
+                    "skill_search_hints": ["audio editing"],
+                    "providers": [
+                        {
+                            "kind": "harness-cli",
+                            "name": "cli-anything-audacity",
+                            "requires": {"binary": ["cli-anything-audacity"]},
+                            "cost_tier": "free",
+                            "quality_tier": "high",
+                            "offline": True,
+                        },
+                        {
+                            "kind": "native",
+                            "name": "sox",
+                            "requires": {"binary": ["sox"]},
+                            "cost_tier": "free",
+                            "quality_tier": "high",
+                            "offline": True,
+                        },
+                    ],
+                },
+            ],
+            "recipes": [
+                {
+                    "id": "social-short",
+                    "description": "Create a short with a thumbnail and cleaned audio.",
+                    "capabilities_used": ["package.thumbnail", "audio.capture"],
+                }
+            ],
+            "known_gaps": [
+                {
+                    "capability": "publish.upload",
+                    "reason": "No platform upload CLI yet.",
+                    "workaround": "Ask the user to upload manually.",
+                }
+            ],
+        }
+    ],
+}
+
 
 def _make_preview_bundle(tmp_path: Path, *, with_trajectory: bool = False) -> Path:
     bundle_dir = tmp_path / "preview-bundle"
@@ -338,6 +462,300 @@ def test_list_categories(self, mock_fetch):
         assert cats == ["3d", "audio", "image"]
 
 
+class TestMatrixRegistry:
+    """Tests for matrix.py — fetch, cache, search, and lookup."""
+
+    @patch("cli_hub.matrix.requests.get")
+    @patch("cli_hub.matrix.MATRIX_CACHE_FILE", Path(tempfile.mktemp()))
+    def test_fetch_matrix_registry_from_remote(self, mock_get):
+        mock_resp = MagicMock()
+        mock_resp.json.return_value = SAMPLE_MATRIX_REGISTRY
+        mock_resp.raise_for_status = MagicMock()
+        mock_get.return_value = mock_resp
+
+        result = fetch_matrix_registry(force_refresh=True)
+        assert result["matrices"][0]["name"] == "video-creation"
+        mock_get.assert_called_once()
+
+    @patch("cli_hub.matrix._load_local_registry", return_value=SAMPLE_MATRIX_REGISTRY)
+    @patch("cli_hub.matrix.requests.get", side_effect=requests.HTTPError("not found"))
+    def test_fetch_matrix_registry_falls_back_to_local_checkout(self, mock_get, mock_local, tmp_path):
+        with patch("cli_hub.matrix.MATRIX_CACHE_FILE", tmp_path / "matrix_cache.json"):
+            result = fetch_matrix_registry(force_refresh=True)
+        assert result["matrices"][0]["name"] == "video-creation"
+        mock_local.assert_called_once()
+
+    @patch("cli_hub.matrix.fetch_all_matrices", return_value=SAMPLE_MATRIX_REGISTRY["matrices"])
+    def test_get_matrix_found(self, mock_fetch):
+        matrix_item = get_matrix("video-creation")
+        assert matrix_item is not None
+        assert matrix_item["display_name"] == "Video Creation & Editing"
+
+    @patch("cli_hub.matrix.fetch_all_matrices", return_value=SAMPLE_MATRIX_REGISTRY["matrices"])
+    def test_search_matrices_matches_description(self, mock_fetch):
+        results = search_matrices("video")
+        assert len(results) == 1
+        assert results[0]["name"] == "video-creation"
+
+    @patch("cli_hub.matrix.fetch_all_matrices", return_value=SAMPLE_MATRIX_REGISTRY["matrices"])
+    def test_search_matrices_matches_capability_provider(self, mock_fetch):
+        results = search_matrices("Pillow")
+        assert len(results) == 1
+        assert results[0]["name"] == "video-creation"
+
+    @patch("cli_hub.matrix.importlib.util.find_spec")
+    @patch("cli_hub.matrix.shutil.which")
+    def test_check_provider_requirements(self, mock_which, mock_find_spec):
+        provider = {
+            "name": "Pillow",
+            "kind": "python",
+            "requires": {"package": ["PIL"], "binary": ["ffmpeg"], "env": ["MISSING_KEY"]},
+            "cost_tier": "free",
+            "quality_tier": "good",
+            "offline": True,
+        }
+        mock_which.return_value = "/usr/bin/ffmpeg"
+        mock_find_spec.return_value = MagicMock()
+
+        result = check_provider_requirements(provider)
+        assert result["available"] is False
+        assert result["present"]["binary"] == ["ffmpeg"]
+        assert result["present"]["package"] == ["PIL"]
+        assert result["missing"]["env"] == ["MISSING_KEY"]
+
+    @patch("cli_hub.matrix.importlib.util.find_spec")
+    @patch("cli_hub.matrix.shutil.which")
+    def test_check_provider_requirements_marks_agent_skill_installable(self, mock_which, mock_find_spec):
+        provider = {
+            "name": "video-scriptwriting skill",
+            "kind": "agent-skill",
+            "requires": {"binary": ["some-skill-cli"]},
+            "cost_tier": "free",
+            "quality_tier": "sota",
+            "offline": True,
+        }
+
+        result = check_provider_requirements(provider)
+        assert result["available"] is False
+        assert result["agent_installable"] is True
+        assert result["status"] == "agent-installable"
+        assert result["missing"] == {"env": [], "binary": [], "package": []}
+        mock_which.assert_not_called()
+        mock_find_spec.assert_not_called()
+
+    @patch("cli_hub.matrix.importlib.util.find_spec")
+    @patch("cli_hub.matrix.shutil.which")
+    def test_preflight_matrix_reports_provider_availability_without_recommendation(self, mock_which, mock_find_spec):
+        mock_which.side_effect = lambda binary: "/usr/bin/sox" if binary == "sox" else None
+        mock_find_spec.side_effect = lambda package: MagicMock() if package == "PIL" else None
+
+        payload = preflight_matrix(SAMPLE_MATRIX_REGISTRY["matrices"][0], capability_id="package.thumbnail")
+        assert payload["summary"]["capabilities"] == 1
+        assert payload["summary"]["available_providers"] == 1
+        assert "recommended" not in payload["capabilities"][0]
+        assert payload["capabilities"][0]["providers"][0]["name"] == "cli-anything-gimp"
+        assert payload["capabilities"][0]["providers"][0]["available"] is False
+        assert payload["capabilities"][0]["providers"][1]["name"] == "Pillow"
+        assert payload["capabilities"][0]["providers"][1]["available"] is True
+
+    @patch("cli_hub.matrix.shutil.which", return_value=None)
+    def test_preflight_matrix_keeps_agent_skills_out_of_available_counts(self, mock_which):
+        matrix_item = {
+            "name": "video-creation",
+            "display_name": "Video Creation & Editing",
+            "schema_version": "2",
+            "capabilities": [
+                {
+                    "id": "script.storyboard",
+                    "intent": "Plan a video",
+                    "providers": [
+                        {
+                            "kind": "agent-skill",
+                            "name": "video-scriptwriting skill",
+                            "requires": {},
+                            "cost_tier": "free",
+                            "quality_tier": "sota",
+                            "offline": True,
+                        },
+                        {
+                            "kind": "native",
+                            "name": "planner-cli",
+                            "requires": {"binary": ["planner-cli"]},
+                            "cost_tier": "free",
+                            "quality_tier": "good",
+                            "offline": True,
+                        },
+                    ],
+                }
+            ],
+        }
+
+        payload = preflight_matrix(matrix_item, capability_id="script.storyboard")
+        assert payload["summary"]["available_providers"] == 0
+        assert payload["summary"]["agent_installable_providers"] == 1
+        assert payload["summary"]["with_agent_installable_provider"] == 1
+        assert payload["capabilities"][0]["available_count"] == 0
+        assert payload["capabilities"][0]["agent_installable_count"] == 1
+        assert "recommended" not in payload["capabilities"][0]
+        assert payload["capabilities"][0]["providers"][0]["status"] == "agent-installable"
+
+
+class TestPackageAvailable:
+    """Tests for _package_available() — import name, dist name, and error handling."""
+
+    def test_stdlib_import_name_detected(self):
+        assert _package_available("json") is True
+
+    @patch("cli_hub.matrix.importlib.util.find_spec", return_value=None)
+    @patch("cli_hub.matrix.importlib.metadata.version", return_value="7.2.3")
+    def test_dist_name_with_dash_detected_via_metadata(self, mock_version, mock_find_spec):
+        assert _package_available("edge-tts") is True
+        mock_version.assert_called_with("edge-tts")
+
+    @patch("cli_hub.matrix.importlib.util.find_spec")
+    @patch("cli_hub.matrix.importlib.metadata.version", side_effect=Exception("not found"))
+    def test_dash_normalized_to_underscore_detected_via_find_spec(self, mock_version, mock_find_spec):
+        mock_find_spec.side_effect = lambda n: MagicMock() if n == "edge_tts" else None
+        assert _package_available("edge-tts") is True
+
+    @patch("cli_hub.matrix.importlib.util.find_spec", return_value=None)
+    @patch("cli_hub.matrix.importlib.metadata.version", side_effect=Exception("not found"))
+    def test_uninstalled_garbage_name_returns_false(self, mock_version, mock_find_spec):
+        assert _package_available("xyzzy-totally-fake-pkg-99999") is False
+
+    @patch("cli_hub.matrix.importlib.util.find_spec", side_effect=RuntimeError("boom"))
+    @patch("cli_hub.matrix.importlib.metadata.version", side_effect=RuntimeError("boom"))
+    def test_exceptions_are_swallowed_returns_false(self, mock_version, mock_find_spec):
+        assert _package_available("some-pkg") is False
+
+    @patch("cli_hub.matrix.importlib.util.find_spec", return_value=MagicMock())
+    def test_plain_import_name_detected_via_find_spec(self, mock_find_spec):
+        assert _package_available("PIL") is True
+        mock_find_spec.assert_called_with("PIL")
+
+
+class TestMatrixSkill:
+    """Tests for matrix_skill.py — local skill resolution and rendering."""
+
+    @patch("cli_hub.matrix_skill.metadata.distribution")
+    def test_resolve_local_skill_path_from_distribution(self, mock_distribution, tmp_path):
+        class FakeDist:
+            files = [Path("cli_anything/audacity/skills/SKILL.md")]
+
+            def locate_file(self, file):
+                return tmp_path / file
+
+        mock_distribution.return_value = FakeDist()
+        cli = {"name": "audacity", "_source": "harness"}
+        resolved = resolve_local_skill_path(cli)
+        assert resolved == str((tmp_path / "cli_anything/audacity/skills/SKILL.md").resolve())
+
+    @patch("cli_hub.matrix_skill.MATRIX_SKILL_DIR", Path(tempfile.mkdtemp()))
+    @patch("cli_hub.matrix_skill.resolve_local_skill_path")
+    @patch("cli_hub.matrix_skill.get_cli")
+    def test_render_matrix_skill_file_injects_paths(self, mock_get_cli, mock_resolve):
+        mock_get_cli.side_effect = lambda name: next((c for c in SAMPLE_REGISTRY["clis"] if c["name"] == name), None)
+        mock_resolve.side_effect = lambda cli: f"/tmp/{cli['name']}/skills/SKILL.md" if cli["name"] != "blender" else None
+
+        rendered = render_matrix_skill_file(SAMPLE_MATRIX_REGISTRY["matrices"][0], installed={"gimp": {}, "audacity": {}})
+        content = Path(rendered).read_text()
+        assert "## Installed CLI Skills" in content
+        assert "/tmp/gimp/skills/SKILL.md" in content
+        assert "skills/cli-anything-gimp/SKILL.md" in content
+        assert "## Capability Provider Overview" in content
+        assert "not installed" in content
+
+    def test_render_capability_tooling_includes_providers_and_recipes(self):
+        matrix_item = SAMPLE_MATRIX_REGISTRY["matrices"][0]
+        result = _render_capability_tooling(matrix_item, installed={"gimp": {}})
+        assert "## Capability Provider Overview" in result
+        assert "`package.thumbnail`" in result
+        assert "`cli-anything-gimp`" in result
+        assert "binary: cli-anything-gimp" in result
+        assert "## Recipes" in result
+        assert "`social-short`" in result
+        assert "## Known Gaps" in result
+
+
+class TestMultiApproachRendering:
+    """Tests for multi-approach stage rendering in matrix_skill.py."""
+
+    def test_render_stage_tooling_includes_goals(self):
+        matrix_item = SAMPLE_MATRIX_REGISTRY["matrices"][0]
+        result = _render_stage_tooling(matrix_item, installed={"gimp": {}})
+        assert "## Stage Tooling Overview" in result
+        assert "Create a thumbnail image" in result
+        assert "Edit and process audio" in result
+
+    def test_render_stage_tooling_includes_alternatives(self):
+        matrix_item = SAMPLE_MATRIX_REGISTRY["matrices"][0]
+        result = _render_stage_tooling(matrix_item, installed={})
+        assert "Pillow" in result
+        assert "pydub" in result
+        assert "sox" in result
+        assert "ImageMagick convert" in result
+
+    def test_render_stage_tooling_shows_install_status(self):
+        matrix_item = SAMPLE_MATRIX_REGISTRY["matrices"][0]
+        result = _render_stage_tooling(matrix_item, installed={"gimp": {}})
+        assert "`gimp` (installed)" in result
+        assert "`audacity` (not installed)" in result
+
+    def test_render_stage_tooling_omits_skill_search_hints(self):
+        matrix_item = SAMPLE_MATRIX_REGISTRY["matrices"][0]
+        result = _render_stage_tooling(matrix_item, installed={})
+        assert "npx skills search" not in result
+        assert "Search for skills" not in result
+
+    def test_render_stage_tooling_backward_compat_no_goal(self):
+        """Stages without 'goal' field are skipped gracefully."""
+        matrix_no_goals = {
+            "name": "test",
+            "stages": [
+                {"name": "Stage1", "clis": ["foo"]},
+            ],
+        }
+        result = _render_stage_tooling(matrix_no_goals, installed={})
+        assert result == ""
+
+    def test_render_discovery_section(self):
+        matrix_item = SAMPLE_MATRIX_REGISTRY["matrices"][0]
+        result = _render_discovery_section(matrix_item)
+        assert result == ""
+
+    def test_render_discovery_section_uses_capability_hints(self):
+        matrix_item = {
+            "name": "test",
+            "capabilities": [
+                {"id": "publish.upload", "skill_search_hints": ["youtube upload"]},
+            ],
+        }
+        result = _render_discovery_section(matrix_item)
+        assert result == ""
+
+    def test_render_discovery_section_empty_when_no_hints(self):
+        matrix_no_hints = {
+            "name": "test",
+            "stages": [{"name": "S1", "clis": ["foo"]}],
+        }
+        result = _render_discovery_section(matrix_no_hints)
+        assert result == ""
+
+    @patch("cli_hub.matrix_skill.MATRIX_SKILL_DIR", Path(tempfile.mkdtemp()))
+    @patch("cli_hub.matrix_skill.resolve_local_skill_path")
+    @patch("cli_hub.matrix_skill.get_cli")
+    def test_render_matrix_skill_file_includes_stage_tooling(self, mock_get_cli, mock_resolve):
+        mock_get_cli.side_effect = lambda name: next((c for c in SAMPLE_REGISTRY["clis"] if c["name"] == name), None)
+        mock_resolve.return_value = None
+
+        rendered = render_matrix_skill_file(SAMPLE_MATRIX_REGISTRY["matrices"][0], installed={"gimp": {}})
+        content = Path(rendered).read_text()
+        assert "## Stage Tooling Overview" in content
+        assert "## Skill Discovery Commands" not in content
+        assert "npx skills search" not in content
+        assert "Create a thumbnail image" in content
+
+
 class TestPreviewBundle:
     """Tests for preview bundle inspection and HTML rendering."""
 
@@ -1087,7 +1505,204 @@ def test_help(self, mock_detect, mock_visit, mock_first_run):
         mock_detect.return_value = self.human_detection
         result = self.runner.invoke(main, ["--help"])
         assert "cli-hub" in result.output
+        assert "matrix" in result.output
+        assert "previews" in result.output
+        assert result.exit_code == 0
+
+    @patch("cli_hub.cli.track_first_run")
+    @patch("cli_hub.cli.track_visit")
+    @patch("cli_hub.cli.detect_invocation_context")
+    @patch("cli_hub.cli.fetch_all_matrices", return_value=SAMPLE_MATRIX_REGISTRY["matrices"])
+    @patch("cli_hub.cli.get_installed", return_value={"gimp": {"version": "1.0.0"}})
+    def test_matrix_list_command(self, mock_installed, mock_fetch_matrices, mock_detect, mock_visit, mock_first_run):
+        mock_detect.return_value = self.human_detection
+        result = self.runner.invoke(main, ["matrix", "list"])
+        assert "video-creation" in result.output
+        assert "1/3" in result.output
+        assert result.exit_code == 0
+
+    @patch("cli_hub.cli.track_first_run")
+    @patch("cli_hub.cli.track_visit")
+    @patch("cli_hub.cli.detect_invocation_context")
+    @patch("cli_hub.cli.search_matrices", return_value=SAMPLE_MATRIX_REGISTRY["matrices"])
+    @patch("cli_hub.cli.get_installed", return_value={"gimp": {"version": "1.0.0"}})
+    def test_matrix_search_command(self, mock_installed, mock_search, mock_detect, mock_visit, mock_first_run):
+        mock_detect.return_value = self.human_detection
+        result = self.runner.invoke(main, ["matrix", "search", "video"])
+        assert "video-creation" in result.output
+        assert "1/3" in result.output
+        assert result.exit_code == 0
+
+    @patch("cli_hub.cli.track_first_run")
+    @patch("cli_hub.cli.track_visit")
+    @patch("cli_hub.cli.detect_invocation_context")
+    @patch("cli_hub.cli.search_matrices", return_value=[])
+    def test_matrix_search_no_results(self, mock_search, mock_detect, mock_visit, mock_first_run):
+        mock_detect.return_value = self.human_detection
+        result = self.runner.invoke(main, ["matrix", "search", "nonexistent"])
+        assert "No matrices matching" in result.output
+        assert result.exit_code == 0
+
+    @patch("cli_hub.cli.track_first_run")
+    @patch("cli_hub.cli.track_visit")
+    @patch("cli_hub.cli.detect_invocation_context")
+    @patch("cli_hub.cli.get_matrix", return_value=SAMPLE_MATRIX_REGISTRY["matrices"][0])
+    @patch("cli_hub.cli.get_installed", return_value={"gimp": {"version": "1.0.0"}})
+    @patch("cli_hub.cli.get_rendered_matrix_skill_path", return_value=Path("/tmp/video-creation.SKILL.md"))
+    @patch("pathlib.Path.exists", return_value=True)
+    def test_matrix_info_command(
+        self,
+        mock_exists,
+        mock_rendered,
+        mock_installed,
+        mock_get_matrix,
+        mock_detect,
+        mock_visit,
+        mock_first_run,
+    ):
+        mock_detect.return_value = self.human_detection
+        result = self.runner.invoke(main, ["matrix", "info", "video-creation"])
+        assert "Video Creation & Editing" in result.output
+        assert "cli-hub matrix install video-creation" in result.output
+        assert "cli-hub-matrix/video-creation/SKILL.md" in result.output
+        assert "Local skill: /tmp/video-creation.SKILL.md" in result.output
+        assert "Capabilities:" in result.output
+        assert "package.thumbnail" in result.output
+        assert "Known Gaps:" in result.output
+        assert result.exit_code == 0
+
+    @patch("cli_hub.cli.track_first_run")
+    @patch("cli_hub.cli.track_visit")
+    @patch("cli_hub.cli.detect_invocation_context")
+    @patch("cli_hub.cli.get_matrix", return_value=SAMPLE_MATRIX_REGISTRY["matrices"][0])
+    @patch("cli_hub.cli.preflight_matrix")
+    def test_matrix_preflight_command(self, mock_preflight, mock_get_matrix, mock_detect, mock_visit, mock_first_run):
+        mock_detect.return_value = self.human_detection
+        mock_preflight.return_value = {
+            "matrix": {"display_name": "Video Creation & Editing"},
+            "offline": False,
+            "summary": {
+                "capabilities": 1,
+                "with_available_provider": 1,
+                "providers": 2,
+                "available_providers": 1,
+                "covered": 1,
+                "gaps": 0,
+            },
+            "capabilities": [
+                {
+                    "id": "package.thumbnail",
+                    "intent": "Create a thumbnail image",
+                    "providers": [
+                        {
+                            "name": "Pillow",
+                            "kind": "python",
+                            "available": True,
+                            "quality_tier": "good",
+                            "cost_tier": "free",
+                            "missing": {"env": [], "binary": [], "package": []},
+                        }
+                    ],
+                }
+            ],
+        }
+        result = self.runner.invoke(main, ["matrix", "preflight", "video-creation"])
         assert result.exit_code == 0
+        assert "Video Creation & Editing Preflight" in result.output
+        assert "Recommended:" not in result.output
+        assert "Pillow [python; good; free]" in result.output
+        mock_preflight.assert_called_once_with(
+            SAMPLE_MATRIX_REGISTRY["matrices"][0],
+            capability_id=None,
+            offline=False,
+            capability_ids=None,
+        )
+
+    @patch("cli_hub.cli.track_first_run")
+    @patch("cli_hub.cli.track_visit")
+    @patch("cli_hub.cli.detect_invocation_context")
+    @patch("cli_hub.cli.get_matrix", return_value=SAMPLE_MATRIX_REGISTRY["matrices"][0])
+    @patch("cli_hub.cli.preflight_matrix")
+    def test_matrix_preflight_command_renders_agent_skills_separately(
+        self,
+        mock_preflight,
+        mock_get_matrix,
+        mock_detect,
+        mock_visit,
+        mock_first_run,
+    ):
+        mock_detect.return_value = self.human_detection
+        mock_preflight.return_value = {
+            "matrix": {"display_name": "Video Creation & Editing"},
+            "offline": False,
+            "summary": {
+                "capabilities": 1,
+                "with_available_provider": 0,
+                "with_agent_installable_provider": 1,
+                "providers": 1,
+                "available_providers": 0,
+                "agent_installable_providers": 1,
+                "covered": 1,
+                "gaps": 0,
+            },
+            "capabilities": [
+                {
+                    "id": "script.storyboard",
+                    "intent": "Plan a video",
+                    "providers": [
+                        {
+                            "name": "video-scriptwriting skill",
+                            "kind": "agent-skill",
+                            "available": False,
+                            "agent_installable": True,
+                            "quality_tier": "sota",
+                            "cost_tier": "free",
+                            "missing": {"env": [], "binary": [], "package": []},
+                        }
+                    ],
+                }
+            ],
+        }
+
+        result = self.runner.invoke(main, ["matrix", "preflight", "video-creation"])
+        assert result.exit_code == 0
+        assert "1 agent-installable skill provider is not counted as installed or missing" in result.output
+        assert "Recommended:" not in result.output
+        assert "Agent-installable:" not in result.output
+        assert "video-scriptwriting skill [agent-skill; sota; free] agent-installable" in result.output
+        assert "missing:" not in result.output
+
+    @patch("cli_hub.cli.track_first_run")
+    @patch("cli_hub.cli.track_visit")
+    @patch("cli_hub.cli.detect_invocation_context")
+    @patch("cli_hub.cli.install_matrix", return_value=(False, {
+        "matrix": SAMPLE_MATRIX_REGISTRY["matrices"][0],
+        "results": [
+            {"name": "gimp", "status": "skipped", "message": "Already installed"},
+            {"name": "blender", "status": "installed", "message": "Installed Blender"},
+            {"name": "audacity", "status": "failed", "message": "Install failed"},
+        ],
+        "summary": {"installed": 1, "skipped": 1, "failed": 1},
+        "rendered_skill_path": "/tmp/video-creation.SKILL.md",
+    }))
+    def test_matrix_install_command_partial_failure(self, mock_install_matrix, mock_detect, mock_visit, mock_first_run):
+        mock_detect.return_value = self.human_detection
+        result = self.runner.invoke(main, ["matrix", "install", "video-creation"])
+        # Partial failure (some installed, some failed) → exit code 3 per the contract.
+        assert result.exit_code == 3
+        assert "Summary: 1 installed, 1 skipped, 1 failed" in result.output
+        assert "Matrix skill: cli-hub-matrix/video-creation/SKILL.md" in result.output
+        assert "Local matrix skill: /tmp/video-creation.SKILL.md" in result.output
+
+    @patch("cli_hub.cli.track_first_run")
+    @patch("cli_hub.cli.track_visit")
+    @patch("cli_hub.cli.detect_invocation_context")
+    @patch("cli_hub.cli.install_matrix", return_value=(False, {"error": "Matrix 'missing' not found."}))
+    def test_matrix_install_command_not_found(self, mock_install_matrix, mock_detect, mock_visit, mock_first_run):
+        mock_detect.return_value = self.human_detection
+        result = self.runner.invoke(main, ["matrix", "install", "missing"])
+        assert result.exit_code == 1
+        assert "not found" in result.output
 
     @patch("cli_hub.cli.track_first_run")
     @patch("cli_hub.cli.track_visit")
@@ -1228,3 +1843,179 @@ def test_launch_unknown_cli(self, mock_get, mock_detect, mock_visit, mock_first_
         result = self.runner.invoke(main, ["launch", "nonexistent"])
         assert result.exit_code == 1
         assert "not found" in result.output
+
+
+SAMPLE_MATRIX = SAMPLE_MATRIX_REGISTRY["matrices"][0]
+
+
+class TestMatrixScopeHelpers:
+    """Pure-function tests for provider↔CLI resolution and install scoping (F2.2)."""
+
+    def test_provider_cli_name_strips_harness_prefix(self):
+        gimp = SAMPLE_MATRIX["capabilities"][0]["providers"][0]
+        assert provider_cli_name(gimp, SAMPLE_MATRIX["clis"]) == "gimp"
+
+    def test_provider_cli_name_none_for_non_installable(self):
+        pillow = SAMPLE_MATRIX["capabilities"][0]["providers"][1]  # python
+        assert provider_cli_name(pillow, SAMPLE_MATRIX["clis"]) is None
+
+    def test_provider_cli_name_explicit_field_wins(self):
+        provider = {"kind": "public-cli", "name": "Whatever", "cli": "blender"}
+        assert provider_cli_name(provider, SAMPLE_MATRIX["clis"]) == "blender"
+
+    def test_scope_all_returns_every_cli(self):
+        scope = resolve_install_scope(SAMPLE_MATRIX)
+        assert scope["error"] is None
+        assert scope["cli_names"] == ["gimp", "blender", "audacity"]
+        assert scope["scope"]["type"] == "all"
+
+    def test_scope_capability_maps_to_clis(self):
+        scope = resolve_install_scope(SAMPLE_MATRIX, capability="package.thumbnail")
+        assert scope["error"] is None
+        assert scope["cli_names"] == ["gimp"]
+
+    def test_scope_recipe_unions_capability_clis(self):
+        scope = resolve_install_scope(SAMPLE_MATRIX, recipe="social-short")
+        assert scope["error"] is None
+        # social-short uses package.thumbnail (gimp) + audio.capture (audacity), in clis[] order
+        assert scope["cli_names"] == ["gimp", "audacity"]
+
+    def test_scope_only_validates_membership(self):
+        ok = resolve_install_scope(SAMPLE_MATRIX, only="gimp,audacity")
+        assert ok["error"] is None
+        assert ok["cli_names"] == ["gimp", "audacity"]
+        bad = resolve_install_scope(SAMPLE_MATRIX, only="gimp,bogus")
+        assert bad["error"] is not None and "bogus" in bad["error"]
+
+    def test_scope_mutually_exclusive(self):
+        scope = resolve_install_scope(SAMPLE_MATRIX, capability="package.thumbnail", only="gimp")
+        assert scope["error"] is not None
+
+    def test_scope_unknown_capability_errors(self):
+        scope = resolve_install_scope(SAMPLE_MATRIX, capability="nope")
+        assert scope["error"] is not None and "nope" in scope["error"]
+
+    def test_unmanaged_providers_groups_by_kind(self):
+        groups = unmanaged_providers(SAMPLE_MATRIX)
+        assert groups.get("python") == ["Pillow"]
+        assert groups.get("native") == ["sox"]
+
+    def test_provider_install_hint_derives_cli_hub_command(self):
+        gimp = SAMPLE_MATRIX["capabilities"][0]["providers"][0]
+        assert provider_install_hint(gimp, SAMPLE_MATRIX["clis"]) == "cli-hub install gimp"
+
+    def test_provider_install_hint_prefers_explicit(self):
+        provider = {"kind": "public-cli", "name": "tool", "install_hint": "brew install tool"}
+        assert provider_install_hint(provider, SAMPLE_MATRIX["clis"]) == "brew install tool"
+
+
+class TestCapabilitySearch:
+    """Capability-level search powering matrix search matched_in and `cli-hub can` (F1.1)."""
+
+    def test_capability_matches_by_intent(self):
+        matches = capability_matches(SAMPLE_MATRIX, "thumbnail")
+        ids = {m["capability_id"] for m in matches}
+        assert "package.thumbnail" in ids
+        hit = next(m for m in matches if m["capability_id"] == "package.thumbnail")
+        assert hit["match_field"] in {"id", "intent", "hint"}
+        assert "cli-anything-gimp" in hit["providers_summary"]
+
+    @patch("cli_hub.matrix.fetch_all_matrices", return_value=SAMPLE_MATRIX_REGISTRY["matrices"])
+    def test_search_capabilities_includes_availability(self, mock_fetch):
+        with patch("cli_hub.matrix.shutil.which", return_value=None), \
+             patch("cli_hub.matrix._package_available", return_value=False):
+            hits = search_capabilities("audio")
+        assert hits
+        hit = hits[0]
+        assert "providers" in hit and "available" in hit["providers"][0]
+
+    @patch("cli_hub.matrix.fetch_all_matrices", return_value=SAMPLE_MATRIX_REGISTRY["matrices"])
+    def test_all_recipes_filters_by_query(self, mock_fetch):
+        assert {r["id"] for r in all_recipes()} == {"social-short"}
+        assert all_recipes("nonexistent-recipe-xyz") == []
+
+
+class TestMatrixF1F2Commands:
+    """CLI-level tests for the F1/F2 matrix commands."""
+
+    def setup_method(self):
+        self.runner = click.testing.CliRunner()
+        self.human_detection = {"is_agent": False, "agent": None, "source": "tty"}
+
+    @patch("cli_hub.cli.track_first_run")
+    @patch("cli_hub.cli.track_visit")
+    @patch("cli_hub.cli.detect_invocation_context")
+    @patch("cli_hub.matrix.fetch_all_matrices", return_value=SAMPLE_MATRIX_REGISTRY["matrices"])
+    def test_can_command_finds_capability(self, mock_fetch, mock_detect, mock_visit, mock_first):
+        mock_detect.return_value = self.human_detection
+        with patch("cli_hub.matrix.shutil.which", return_value=None), \
+             patch("cli_hub.matrix._package_available", return_value=False):
+            result = self.runner.invoke(main, ["can", "thumbnail"])
+        assert result.exit_code == 0
+        assert "package.thumbnail" in result.output
+        assert "cli-hub matrix preflight video-creation -c package.thumbnail" in result.output
+
+    @patch("cli_hub.cli.track_first_run")
+    @patch("cli_hub.cli.track_visit")
+    @patch("cli_hub.cli.detect_invocation_context")
+    @patch("cli_hub.matrix.fetch_all_matrices", return_value=SAMPLE_MATRIX_REGISTRY["matrices"])
+    def test_can_command_no_match_exits_1(self, mock_fetch, mock_detect, mock_visit, mock_first):
+        mock_detect.return_value = self.human_detection
+        result = self.runner.invoke(main, ["can", "zzz-no-such-capability"])
+        assert result.exit_code == 1
+
+    @patch("cli_hub.cli.track_first_run")
+    @patch("cli_hub.cli.track_visit")
+    @patch("cli_hub.cli.detect_invocation_context")
+    @patch("cli_hub.matrix.fetch_all_matrices", return_value=SAMPLE_MATRIX_REGISTRY["matrices"])
+    def test_recipes_command_lists_recipes(self, mock_fetch, mock_detect, mock_visit, mock_first):
+        mock_detect.return_value = self.human_detection
+        result = self.runner.invoke(main, ["matrix", "recipes"])
+        assert result.exit_code == 0
+        assert "social-short" in result.output
+        assert "preflight video-creation --recipe social-short" in result.output
+
+    @patch("cli_hub.cli.track_first_run")
+    @patch("cli_hub.cli.track_visit")
+    @patch("cli_hub.cli.detect_invocation_context")
+    @patch("cli_hub.cli.get_installed", return_value={})
+    @patch("cli_hub.installer.get_cli")
+    @patch("cli_hub.installer.get_matrix", return_value=SAMPLE_MATRIX)
+    def test_install_dry_run_no_side_effects(self, mock_get_matrix, mock_get_cli,
+                                             mock_installed, mock_detect, mock_visit, mock_first):
+        mock_detect.return_value = self.human_detection
+        mock_get_cli.side_effect = lambda n: {"name": n, "display_name": n.title(),
+                                              "_source": "harness", "entry_point": n}
+        with patch("cli_hub.installer.install_cli") as mock_install:
+            result = self.runner.invoke(
+                main, ["matrix", "install", "video-creation", "--capability", "package.thumbnail", "--dry-run"])
+        mock_install.assert_not_called()
+        assert result.exit_code == 0
+        assert "Install plan" in result.output
+        assert "gimp" in result.output
+
+    @patch("cli_hub.cli.track_first_run")
+    @patch("cli_hub.cli.track_visit")
+    @patch("cli_hub.cli.detect_invocation_context")
+    @patch("cli_hub.installer.get_matrix", return_value=SAMPLE_MATRIX)
+    def test_install_unknown_capability_exits_2(self, mock_get_matrix, mock_detect, mock_visit, mock_first):
+        mock_detect.return_value = self.human_detection
+        result = self.runner.invoke(
+            main, ["matrix", "install", "video-creation", "--capability", "nope", "--dry-run"])
+        assert result.exit_code == 2
+
+    @patch("cli_hub.cli.track_first_run")
+    @patch("cli_hub.cli.track_visit")
+    @patch("cli_hub.cli.detect_invocation_context")
+    @patch("cli_hub.cli.doctor_matrix", return_value=(False, {
+        "matrix": SAMPLE_MATRIX,
+        "last_run": "2026-06-14T10:00:00",
+        "checks": [{"name": "gimp", "entry_point": "gimp", "status": "not_installed",
+                    "detail": "Not installed", "fix": "cli-hub install gimp"}],
+        "summary": {"total": 1, "ok": 0, "broken": 0, "not_installed": 1},
+    }))
+    def test_doctor_command_reports_gaps_exit_3(self, mock_doctor, mock_detect, mock_visit, mock_first):
+        mock_detect.return_value = self.human_detection
+        result = self.runner.invoke(main, ["matrix", "doctor", "video-creation"])
+        assert result.exit_code == 3
+        assert "cli-hub install gimp" in result.output
diff --git a/cli-hub/tests/test_matrix_skill_dist.py b/cli-hub/tests/test_matrix_skill_dist.py
new file mode 100644
index 000000000..d60b5cb07
--- /dev/null
+++ b/cli-hub/tests/test_matrix_skill_dist.py
@@ -0,0 +1,265 @@
+"""Tests for matrix skill distribution (P1-4): co-installed assets and the
+content lookup chain in cli_hub/matrix_skill.py."""
+
+from pathlib import Path
+from unittest.mock import patch
+
+import pytest
+import requests
+import click.testing
+
+from cli_hub import matrix_skill
+from cli_hub.matrix_skill import (
+    get_rendered_matrix_skill_path,
+    render_matrix_skill_file,
+)
+from cli_hub.cli import main
+
+
+def _make_content_dir(root, name="demo", with_pycache=False):
+    """Create a fake repo checkout with cli-hub-matrix/<name>/ content."""
+    content = root / "cli-hub-matrix" / name
+    (content / "references").mkdir(parents=True)
+    (content / "scripts").mkdir(parents=True)
+    (content / "SKILL.md").write_text(
+        "# Demo Matrix\n\nRead [`references/guide.md`](references/guide.md) "
+        "and run `scripts/doctor.py`.\n",
+        encoding="utf-8",
+    )
+    (content / "references" / "guide.md").write_text("guide", encoding="utf-8")
+    (content / "scripts" / "doctor.py").write_text("print('ok')", encoding="utf-8")
+    if with_pycache:
+        pycache = content / "scripts" / "__pycache__"
+        pycache.mkdir()
+        (pycache / "doctor.cpython-310.pyc").write_bytes(b"\x00")
+        (content / "scripts" / "stray.pyc").write_bytes(b"\x00")
+    return content
+
+
+def _demo_matrix(name="demo"):
+    return {
+        "name": name,
+        "display_name": "Demo Matrix",
+        "description": "A demo matrix.",
+        "skill_md": f"cli-hub-matrix/{name}/SKILL.md",
+        "clis": [],
+    }
+
+
+class TestAssetCoInstall:
+    """references/ and scripts/ land beside the rendered SKILL.md."""
+
+    def test_references_and_scripts_copied_beside_skill(self, tmp_path, monkeypatch):
+        repo = tmp_path / "repo"
+        _make_content_dir(repo)
+        skill_dir = tmp_path / "home" / ".cli-hub" / "matrix"
+        monkeypatch.setattr(matrix_skill, "MATRIX_SKILL_DIR", skill_dir)
+        monkeypatch.setattr(matrix_skill, "_find_repo_root", lambda: repo)
+
+        rendered = render_matrix_skill_file(_demo_matrix(), installed={})
+
+        assert rendered == skill_dir / "demo" / "SKILL.md"
+        assert rendered.exists()
+        # Relative links in the skill resolve in the installed layout.
+        assert (rendered.parent / "references" / "guide.md").exists()
+        assert (rendered.parent / "scripts" / "doctor.py").exists()
+        content = rendered.read_text(encoding="utf-8")
+        assert "references/guide.md" in content
+        assert "MATRIX_SKILL_PATHS:START" in content
+        # Assets were found locally, so no remote-fallback note is injected.
+        assert "will not resolve locally" not in content
+
+    def test_pycache_and_pyc_excluded(self, tmp_path, monkeypatch):
+        repo = tmp_path / "repo"
+        _make_content_dir(repo, with_pycache=True)
+        skill_dir = tmp_path / "home" / ".cli-hub" / "matrix"
+        monkeypatch.setattr(matrix_skill, "MATRIX_SKILL_DIR", skill_dir)
+        monkeypatch.setattr(matrix_skill, "_find_repo_root", lambda: repo)
+
+        rendered = render_matrix_skill_file(_demo_matrix(), installed={})
+
+        installed_files = [p.name for p in rendered.parent.rglob("*")]
+        assert "doctor.py" in installed_files
+        assert "__pycache__" not in installed_files
+        assert not any(name.endswith(".pyc") for name in installed_files)
+
+    def test_reinstall_is_idempotent_and_removes_stale_files(self, tmp_path, monkeypatch):
+        repo = tmp_path / "repo"
+        content = _make_content_dir(repo)
+        skill_dir = tmp_path / "home" / ".cli-hub" / "matrix"
+        monkeypatch.setattr(matrix_skill, "MATRIX_SKILL_DIR", skill_dir)
+        monkeypatch.setattr(matrix_skill, "_find_repo_root", lambda: repo)
+
+        first = render_matrix_skill_file(_demo_matrix(), installed={})
+        # Simulate drift: stale file in the installed copy, updated source.
+        (first.parent / "references" / "stale.md").write_text("old", encoding="utf-8")
+        (content / "references" / "guide.md").write_text("guide v2", encoding="utf-8")
+
+        second = render_matrix_skill_file(_demo_matrix(), installed={})
+
+        assert second == first
+        assert not (second.parent / "references" / "stale.md").exists()
+        assert (second.parent / "references" / "guide.md").read_text(encoding="utf-8") == "guide v2"
+
+
+class TestLookupChain:
+    """Checkout -> bundled data -> published URL -> stub."""
+
+    def test_bundled_data_used_when_no_checkout(self, tmp_path, monkeypatch):
+        bundled_root = tmp_path / "bundled"
+        _make_content_dir(bundled_root)
+        skill_dir = tmp_path / "home" / ".cli-hub" / "matrix"
+        monkeypatch.setattr(matrix_skill, "MATRIX_SKILL_DIR", skill_dir)
+        monkeypatch.setattr(matrix_skill, "_find_repo_root", lambda: None)
+        monkeypatch.setattr(
+            matrix_skill, "BUNDLED_MATRIX_DATA_DIR", bundled_root / "cli-hub-matrix"
+        )
+
+        rendered = render_matrix_skill_file(_demo_matrix(), installed={})
+
+        content = rendered.read_text(encoding="utf-8")
+        assert "# Demo Matrix" in content
+        assert (rendered.parent / "references" / "guide.md").exists()
+        assert (rendered.parent / "scripts" / "doctor.py").exists()
+
+    def test_published_url_used_when_no_local_content(self, tmp_path, monkeypatch):
+        skill_dir = tmp_path / "home" / ".cli-hub" / "matrix"
+        monkeypatch.setattr(matrix_skill, "MATRIX_SKILL_DIR", skill_dir)
+        monkeypatch.setattr(matrix_skill, "_find_repo_root", lambda: None)
+        monkeypatch.setattr(
+            matrix_skill, "BUNDLED_MATRIX_DATA_DIR", tmp_path / "missing"
+        )
+
+        class FakeResponse:
+            status_code = 200
+            text = "# Demo Matrix (published)\n\npublished body\n"
+
+        requested = {}
+
+        def fake_get(url, timeout):
+            requested["url"] = url
+            return FakeResponse()
+
+        monkeypatch.setattr(matrix_skill.requests, "get", fake_get)
+
+        rendered = render_matrix_skill_file(_demo_matrix(), installed={})
+
+        content = rendered.read_text(encoding="utf-8")
+        assert "# Demo Matrix (published)" in content
+        assert requested["url"] == (
+            f"{matrix_skill.MATRIX_CONTENT_BASE_URL}/demo/SKILL.md"
+        )
+        # No local assets: the rendered skill points at the published copies.
+        assert not (rendered.parent / "references").exists()
+        assert "will not resolve locally" in content
+        assert f"{matrix_skill.MATRIX_CONTENT_BASE_URL}/demo/" in content
+
+    def test_stub_used_when_everything_else_fails(self, tmp_path, monkeypatch):
+        skill_dir = tmp_path / "home" / ".cli-hub" / "matrix"
+        monkeypatch.setattr(matrix_skill, "MATRIX_SKILL_DIR", skill_dir)
+        monkeypatch.setattr(matrix_skill, "_find_repo_root", lambda: None)
+        monkeypatch.setattr(
+            matrix_skill, "BUNDLED_MATRIX_DATA_DIR", tmp_path / "missing"
+        )
+
+        def fake_get(url, timeout):
+            raise requests.ConnectionError("offline")
+
+        monkeypatch.setattr(matrix_skill.requests, "get", fake_get)
+
+        rendered = render_matrix_skill_file(_demo_matrix(), installed={})
+
+        content = rendered.read_text(encoding="utf-8")
+        assert "# Demo Matrix" in content
+        assert "A demo matrix." in content
+        assert "Install with `cli-hub matrix install demo`." in content
+
+    def test_published_url_non_200_falls_back_to_stub(self, tmp_path, monkeypatch):
+        skill_dir = tmp_path / "home" / ".cli-hub" / "matrix"
+        monkeypatch.setattr(matrix_skill, "MATRIX_SKILL_DIR", skill_dir)
+        monkeypatch.setattr(matrix_skill, "_find_repo_root", lambda: None)
+        monkeypatch.setattr(
+            matrix_skill, "BUNDLED_MATRIX_DATA_DIR", tmp_path / "missing"
+        )
+
+        class FakeResponse:
+            status_code = 404
+            text = "Not Found"
+
+        monkeypatch.setattr(matrix_skill.requests, "get", lambda url, timeout: FakeResponse())
+
+        rendered = render_matrix_skill_file(_demo_matrix(), installed={})
+        assert "Install with `cli-hub matrix install demo`." in rendered.read_text(encoding="utf-8")
+
+
+class TestRenderedPathCompat:
+    """get_rendered_matrix_skill_path prefers the new layout, keeps legacy."""
+
+    def test_prefers_directory_layout(self, tmp_path, monkeypatch):
+        monkeypatch.setattr(matrix_skill, "MATRIX_SKILL_DIR", tmp_path)
+        new_path = tmp_path / "demo" / "SKILL.md"
+        new_path.parent.mkdir(parents=True)
+        new_path.write_text("new", encoding="utf-8")
+        (tmp_path / "demo.SKILL.md").write_text("legacy", encoding="utf-8")
+
+        assert get_rendered_matrix_skill_path("demo") == new_path
+
+    def test_falls_back_to_legacy_flat_file(self, tmp_path, monkeypatch):
+        monkeypatch.setattr(matrix_skill, "MATRIX_SKILL_DIR", tmp_path)
+        legacy = tmp_path / "demo.SKILL.md"
+        legacy.write_text("legacy", encoding="utf-8")
+
+        assert get_rendered_matrix_skill_path("demo") == legacy
+
+    def test_defaults_to_directory_layout_when_nothing_exists(self, tmp_path, monkeypatch):
+        monkeypatch.setattr(matrix_skill, "MATRIX_SKILL_DIR", tmp_path)
+        assert get_rendered_matrix_skill_path("demo") == tmp_path / "demo" / "SKILL.md"
+
+
+class TestSkillOnlyInstall:
+    """`cli-hub matrix install <name> --skill-only` renders without CLI installs."""
+
+    def setup_method(self):
+        self.runner = click.testing.CliRunner()
+        self.human_detection = {
+            "is_agent": False,
+            "traffic_type": "human",
+            "category": "human",
+            "reason": "human",
+            "signals": [],
+            "stdin_tty": True,
+            "is_interactive": True,
+        }
+
+    @patch("cli_hub.cli.track_first_run")
+    @patch("cli_hub.cli.track_visit")
+    @patch("cli_hub.cli.detect_invocation_context")
+    @patch("cli_hub.cli.render_matrix_skill_file")
+    @patch("cli_hub.cli.get_installed", return_value={})
+    @patch("cli_hub.cli.get_matrix")
+    @patch("cli_hub.cli.install_matrix")
+    def test_skill_only_renders_and_skips_cli_installs(
+        self, mock_install_matrix, mock_get_matrix, mock_installed,
+        mock_render, mock_detect, mock_visit, mock_first_run, tmp_path,
+    ):
+        mock_detect.return_value = self.human_detection
+        mock_get_matrix.return_value = _demo_matrix()
+        mock_render.return_value = tmp_path / "demo" / "SKILL.md"
+
+        result = self.runner.invoke(main, ["matrix", "install", "demo", "--skill-only"])
+
+        assert result.exit_code == 0
+        assert "Local matrix skill:" in result.output
+        mock_render.assert_called_once()
+        mock_install_matrix.assert_not_called()
+
+    @patch("cli_hub.cli.track_first_run")
+    @patch("cli_hub.cli.track_visit")
+    @patch("cli_hub.cli.detect_invocation_context")
+    @patch("cli_hub.cli.get_matrix", return_value=None)
+    def test_skill_only_unknown_matrix_fails(
+        self, mock_get_matrix, mock_detect, mock_visit, mock_first_run,
+    ):
+        mock_detect.return_value = self.human_detection
+        result = self.runner.invoke(main, ["matrix", "install", "missing", "--skill-only"])
+        assert result.exit_code == 1
diff --git a/docs/hub/assets/demos/arcgis-pro-live-bridge-demo.gif b/docs/hub/assets/demos/arcgis-pro-live-bridge-demo.gif
new file mode 100644
index 000000000..645a33fd2
Binary files /dev/null and b/docs/hub/assets/demos/arcgis-pro-live-bridge-demo.gif differ
diff --git a/docs/hub/assets/demos/blender-orbital-relay-drone-preview-trajectory.gif b/docs/hub/assets/demos/blender-orbital-relay-drone-preview-trajectory.gif
new file mode 100644
index 000000000..501b2eb2f
Binary files /dev/null and b/docs/hub/assets/demos/blender-orbital-relay-drone-preview-trajectory.gif differ
diff --git a/docs/hub/assets/demos/drawio-demo.gif b/docs/hub/assets/demos/drawio-demo.gif
new file mode 100644
index 000000000..6a07b989e
Binary files /dev/null and b/docs/hub/assets/demos/drawio-demo.gif differ
diff --git a/docs/hub/assets/demos/drawio-https-handshake.png b/docs/hub/assets/demos/drawio-https-handshake.png
new file mode 100644
index 000000000..83a7eb1c0
Binary files /dev/null and b/docs/hub/assets/demos/drawio-https-handshake.png differ
diff --git a/docs/hub/assets/demos/freecad-curiosity-preview-trajectory.gif b/docs/hub/assets/demos/freecad-curiosity-preview-trajectory.gif
new file mode 100644
index 000000000..65bb8eeb6
Binary files /dev/null and b/docs/hub/assets/demos/freecad-curiosity-preview-trajectory.gif differ
diff --git a/docs/hub/assets/demos/slay-the-spire-ii-gameplay.gif b/docs/hub/assets/demos/slay-the-spire-ii-gameplay.gif
new file mode 100644
index 000000000..dd87679dd
Binary files /dev/null and b/docs/hub/assets/demos/slay-the-spire-ii-gameplay.gif differ
diff --git a/docs/hub/assets/demos/videocaptioner-after.png b/docs/hub/assets/demos/videocaptioner-after.png
new file mode 100644
index 000000000..fe30d9c18
Binary files /dev/null and b/docs/hub/assets/demos/videocaptioner-after.png differ
diff --git a/docs/hub/assets/demos/videocaptioner-before.png b/docs/hub/assets/demos/videocaptioner-before.png
new file mode 100644
index 000000000..f43628847
Binary files /dev/null and b/docs/hub/assets/demos/videocaptioner-before.png differ
diff --git a/docs/hub/demos.html b/docs/hub/demos.html
new file mode 100644
index 000000000..262c4bd49
--- /dev/null
+++ b/docs/hub/demos.html
@@ -0,0 +1,593 @@
+<!DOCTYPE html>
+<html lang="en" data-theme="dark">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <meta name="robots" content="index,follow,max-snippet:-1,max-image-preview:large,max-video-preview:-1">
+  <title>Real-World Demos — CLI-Anything Hub</title>
+  <meta name="description" content="Watch AI agents drive generated CLIs to produce complete, useful artifacts — CAD models, 3D scenes, diagrams, gameplay, captioned video, and live GIS — no GUI needed.">
+  <meta name="author" content="HKUDS and Yuhao Yang">
+  <meta name="copyright" content="Copyright: HKUDS. Lead author: Yuhao Yang (yuhao.page).">
+  <link rel="canonical" href="https://clianything.cc/demos.html">
+  <meta property="og:type" content="website">
+  <meta property="og:site_name" content="CLI-Anything Hub">
+  <meta property="og:title" content="Real-World Demos — CLI-Anything Hub">
+  <meta property="og:description" content="AI agents using generated CLIs to produce complete artifacts — no GUI needed.">
+  <meta property="og:url" content="https://clianything.cc/demos.html">
+  <meta name="twitter:card" content="summary">
+  <meta name="twitter:title" content="Real-World Demos — CLI-Anything Hub">
+  <meta name="twitter:description" content="Watch AI agents drive generated CLIs to produce real artifacts.">
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <link href="https://fonts.googleapis.com/css2?family=Hanken+Grotesk:ital,wght@0,400;0,500;0,600;0,700;0,800;1,500&family=Instrument+Serif:ital@0;1&family=JetBrains+Mono:wght@400;500&family=Newsreader:ital,opsz,wght@0,6..72,300;0,6..72,400;0,6..72,500;1,6..72,300;1,6..72,400&display=swap" rel="stylesheet">
+  <style>
+    /* ===================== Tokens — shared with the Hub (Steel Sky default; set by JS per palette×theme) ===================== */
+    :root {
+      color-scheme: dark;
+      --bg: #0d1117; --surface: #151b24;
+      --ink: #e8edf4; --ink-2: #9fb0c4; --ink-3: #647488;
+      --line: rgba(255,255,255,0.08);
+      --accent: #46b2f4; --accent2: #6cc6f8; --accent-rgb: 70,178,244;
+      --surface-rgb: 21,27,36; --accent-band: 203;
+      --ok: #54d196; --radius: 22px; --radius-sm: 13px;
+      --accent-ink: var(--accent2);
+      --glass-bg: linear-gradient(158deg, rgba(255,255,255,0.075), rgba(255,255,255,0.024) 46%, rgba(255,255,255,0.010));
+      --glass-bg-fallback: rgba(var(--surface-rgb), 0.86);
+      --glass-border: var(--line);
+      --glass-edge: rgba(255,255,255,0.14);
+      --glass-shadow: 0 24px 60px -22px rgba(0,0,0,0.62), 0 2px 8px -2px rgba(0,0,0,0.48);
+      --glass-shadow-hi: 0 38px 90px -28px rgba(0,0,0,0.70), 0 4px 14px -4px rgba(0,0,0,0.52);
+      --chip-bg: rgba(255,255,255,0.055);
+      --cmd-bg: rgba(0,0,0,0.30); --cmd-line: rgba(255,255,255,0.08);
+      --tint-s: 52%; --tint-l: 62%;
+      --ease: cubic-bezier(.22,.61,.36,1);
+      --spring: cubic-bezier(.34,1.32,.5,1);
+      --palette-transition: background .45s var(--ease), color .45s var(--ease), border-color .45s var(--ease);
+    }
+    [data-theme="light"] {
+      color-scheme: light;
+      --bg: #f4f6f9; --surface: #ffffff;
+      --ink: #14181f; --ink-2: #4a5568; --ink-3: #8595a8;
+      --line: rgba(20,40,80,0.10);
+      --accent: #1c8ee0; --accent2: #1573bd; --accent-rgb: 28,142,224;
+      --surface-rgb: 255,255,255;
+      --accent-ink: var(--accent2);
+      --glass-bg: linear-gradient(158deg, rgba(255,255,255,0.92), rgba(255,255,255,0.62) 48%, rgba(255,255,255,0.42));
+      --glass-bg-fallback: rgba(var(--surface-rgb), 0.92);
+      --glass-edge: rgba(255,255,255,0.96);
+      --glass-shadow: 0 22px 50px -24px rgba(30,44,70,0.22), 0 2px 6px -2px rgba(30,44,70,0.12);
+      --glass-shadow-hi: 0 34px 80px -28px rgba(30,44,70,0.28), 0 4px 12px -4px rgba(30,44,70,0.16);
+      --chip-bg: rgba(20,40,80,0.045);
+      --cmd-bg: rgba(20,40,80,0.05); --cmd-line: rgba(20,40,80,0.08);
+      --tint-s: 46%; --tint-l: 44%;
+    }
+    body, .nav.scrolled, .ed-media .media, .seg-btn { transition: var(--palette-transition); }
+
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    html { scroll-behavior: smooth; scroll-padding-top: 84px; -webkit-text-size-adjust: 100%; }
+    body { font-family: 'Hanken Grotesk', sans-serif; background: var(--bg); color: var(--ink);
+      line-height: 1.6; font-size: 16px; letter-spacing: -0.004em;
+      -webkit-font-smoothing: antialiased; -moz-osx-font-smoothing: grayscale; min-height: 100vh; overflow-x: hidden; }
+    ::selection { background: rgba(var(--accent-rgb), 0.30); color: var(--ink); }
+    a { color: inherit; }
+    button { font-family: inherit; }
+    h1,h2,h3 { letter-spacing: -0.022em; line-height: 1.1; font-weight: 700; }
+    code, .mono { font-family: 'JetBrains Mono', monospace; }
+
+    /* ambient + grain + glass (shared) */
+    .ambient { position: fixed; inset: 0; z-index: -2; overflow: hidden; pointer-events: none; }
+    .ambient i { position: absolute; border-radius: 50%; filter: blur(100px); opacity: 0.7; }
+    .ambient .a { width: 60vw; max-width: 760px; aspect-ratio: 1; top: -18vw; right: -10vw;
+      background: radial-gradient(circle at 38% 38%, hsl(calc(var(--accent-band) + 28) var(--tint-s) 58% / 0.26), transparent 64%); }
+    .ambient .b { width: 50vw; max-width: 620px; aspect-ratio: 1; bottom: -16vw; left: -12vw;
+      background: radial-gradient(circle at 60% 42%, hsl(var(--accent-band) calc(var(--tint-s) + 12%) 56% / 0.24), transparent 62%); }
+    .grain { position: fixed; inset: 0; z-index: -1; pointer-events: none; opacity: 0.04; mix-blend-mode: overlay;
+      background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='120' height='120'%3E%3Cfilter id='n'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='0.9' numOctaves='2'/%3E%3C/filter%3E%3Crect width='100%25' height='100%25' filter='url(%23n)'/%3E%3C/svg%3E"); }
+    .glass { position: relative; background: var(--glass-bg-fallback); border: 1px solid var(--glass-border); border-radius: var(--radius); box-shadow: var(--glass-shadow); }
+    @supports ((backdrop-filter: blur(1px)) or (-webkit-backdrop-filter: blur(1px))) {
+      .glass { background: var(--glass-bg); -webkit-backdrop-filter: blur(22px) saturate(1.5); backdrop-filter: blur(22px) saturate(1.5); } }
+    .glass::before { content: ''; position: absolute; inset: 0; border-radius: inherit; pointer-events: none; box-shadow: inset 0 1px 0 var(--glass-edge), inset 0 0 0 1px rgba(255,255,255,0.02); }
+
+    /* ===================== Nav (shared with Hub) ===================== */
+    .nav { position: sticky; top: 0; z-index: 40; border-bottom: 1px solid transparent; transition: border-color .3s, background .3s, backdrop-filter .3s; }
+    .nav.scrolled { border-color: var(--line); background: color-mix(in oklab, var(--bg) 78%, transparent);
+      -webkit-backdrop-filter: blur(16px) saturate(1.4); backdrop-filter: blur(16px) saturate(1.4); }
+    .nav-in { max-width: 1180px; margin: 0 auto; padding: 0 22px; display: flex; align-items: center; justify-content: space-between; gap: 14px; height: 64px; }
+    .nav-brand { display: inline-flex; align-items: center; gap: 9px; text-decoration: none; font-weight: 800; font-size: 1.08rem; letter-spacing: -0.02em; }
+    .nav-brand-badge { width: 30px; height: 30px; display: grid; place-items: center; border-radius: 9px; flex-shrink: 0;
+      border: 1px solid var(--glass-border); background: var(--chip-bg); box-shadow: var(--glass-shadow); }
+    .nav-brand-badge svg { width: 64%; height: 64%; }
+    .nav-links { display: flex; align-items: center; gap: 4px; }
+    .nav-link { padding: 7px 11px; border-radius: 10px; text-decoration: none; color: var(--ink-2); font-size: 0.84rem; font-weight: 500;
+      transition: color .18s, background .18s; display: inline-flex; align-items: center; gap: 6px; }
+    .nav-link:hover { color: var(--ink); background: var(--chip-bg); }
+    .nav-link.active { color: var(--ink); background: var(--chip-bg); }
+    .nav-link svg { width: 15px; height: 15px; flex-shrink: 0; }
+    .nav-link-stars { font-family: 'JetBrains Mono', monospace; font-size: 0.72rem; font-weight: 600; color: var(--accent-ink);
+      background: var(--chip-bg); border: 1px solid var(--line); border-radius: 7px; padding: 1px 7px; font-variant-numeric: tabular-nums; }
+    .theme-toggle { display: inline-grid; place-items: center; width: 36px; height: 36px; border-radius: 11px;
+      border: 1px solid var(--line); background: var(--chip-bg); color: var(--ink-2); cursor: pointer; transition: color .18s, border-color .18s; }
+    .theme-toggle:hover { color: var(--ink); border-color: var(--ink-3); }
+    .theme-toggle svg { width: 17px; height: 17px; }
+    .theme-toggle .icon-moon { display: none; }
+    [data-theme="light"] .theme-toggle .icon-moon { display: block; }
+    [data-theme="light"] .theme-toggle .icon-sun { display: none; }
+
+    /* Mobile nav drawer */
+    .nav-menu { display: flex; align-items: center; gap: 4px; }
+    .nav-toggle { display: none; position: relative; z-index: 70; place-items: center; width: 38px; height: 38px;
+      border-radius: 11px; border: 1px solid var(--line); background: var(--chip-bg); color: var(--ink); cursor: pointer;
+      transition: color .18s, border-color .18s; }
+    .nav-toggle:hover { border-color: var(--ink-3); }
+    .nav-toggle svg { width: 19px; height: 19px; }
+    .nav-toggle .icon-x { display: none; }
+    .nav-toggle.open .icon-bars { display: none; }
+    .nav-toggle.open .icon-x { display: block; }
+    .nav-scrim { position: fixed; inset: 0; z-index: 55; background: rgba(2,5,10,0.5);
+      -webkit-backdrop-filter: blur(2px); backdrop-filter: blur(2px); opacity: 0; visibility: hidden;
+      transition: opacity .3s var(--ease), visibility .3s; }
+    .nav-scrim.open { opacity: 1; visibility: visible; }
+    .nav-menu.open { transform: none; }
+    @media (max-width: 860px) {
+      .nav-toggle { display: inline-grid; }
+      .nav-menu { position: fixed; top: 0; right: 0; height: 100dvh; width: min(82vw, 320px);
+        flex-direction: column; align-items: stretch; gap: 6px; padding: 80px 16px 28px;
+        background: var(--glass-bg-fallback); border-left: 1px solid var(--line);
+        box-shadow: -24px 0 64px -28px rgba(0,0,0,0.6); transform: translateX(106%);
+        transition: transform .34s var(--ease); overflow-y: auto; z-index: 60; }
+      .nav-menu .nav-link { padding: 12px 14px; font-size: 0.98rem; border-radius: 11px; color: var(--ink-2); }
+      .nav-menu .nav-link.active { color: var(--ink); background: var(--chip-bg); }
+      .nav-menu .nav-link svg { width: 19px; height: 19px; }
+      .nav-menu .nav-link-stars { margin-left: auto; }
+    }
+    @supports ((backdrop-filter: blur(1px)) or (-webkit-backdrop-filter: blur(1px))) {
+      @media (max-width: 860px) {
+        .nav-menu { background: var(--glass-bg); -webkit-backdrop-filter: blur(22px) saturate(1.4); backdrop-filter: blur(22px) saturate(1.4); }
+      }
+    }
+
+    .reveal { opacity: 0; transform: translateY(22px); transition: opacity .7s var(--ease), transform .7s var(--ease); }
+    .reveal.in { opacity: 1; transform: none; }
+    [style*="--d"] { transition-delay: var(--d); }
+
+    /* ===================== Page header ===================== */
+    .phead { max-width: 1100px; margin: 0 auto; padding: 64px 22px 8px; text-align: center; }
+    .klabel { font-size: 0.72rem; font-weight: 700; letter-spacing: 0.16em; text-transform: uppercase; color: var(--accent-ink); }
+    .phead h1 { font-family: 'Newsreader', serif; font-weight: 400; color: var(--ink);
+      font-size: clamp(2.5rem, 7vw, 4.4rem); letter-spacing: -0.018em; line-height: 1.02; margin-top: 14px; }
+    .phead h1 em { font-style: italic; font-weight: 300; color: var(--accent2); }
+    [data-theme="dark"] .phead h1 em { color: var(--accent); }
+    .phead p { max-width: 60ch; margin: 20px auto 0; color: var(--ink-2); font-size: clamp(1rem, 2.2vw, 1.18rem); text-wrap: pretty; }
+    .phead p .lead { color: var(--ink); font-weight: 600; }
+    .phead-meta { display: flex; gap: 10px; justify-content: center; flex-wrap: wrap; margin-top: 26px; }
+    .phead-meta .stat { padding: 11px 20px; border-radius: 15px; text-align: center; min-width: 110px;
+      background: var(--glass-bg-fallback); border: 1px solid var(--glass-border); box-shadow: var(--glass-shadow); position: relative; }
+    @supports ((backdrop-filter: blur(1px))) { .phead-meta .stat { background: var(--glass-bg); -webkit-backdrop-filter: blur(18px) saturate(1.4); backdrop-filter: blur(18px) saturate(1.4); } }
+    .phead-meta .stat-num { font-family: 'Newsreader', serif; font-size: 2rem; line-height: 1; color: var(--accent2); }
+    [data-theme="dark"] .phead-meta .stat-num { color: var(--accent); }
+    .phead-meta .stat-label { font-size: 0.66rem; font-weight: 700; letter-spacing: 0.1em; text-transform: uppercase; color: var(--ink-3); margin-top: 7px; }
+
+    /* ===================== Editorial gallery ===================== */
+    .editorial { max-width: 1100px; margin: 56px auto 0; padding: 0 22px; display: flex; flex-direction: column; gap: 64px; }
+    .ed-row { display: grid; grid-template-columns: 1.22fr 1fr; gap: 40px; align-items: center; }
+    .ed-row:nth-child(even) .ed-media { order: 2; }
+    @media (max-width: 840px) { .ed-row { grid-template-columns: 1fr; gap: 22px; } .ed-row:nth-child(even) .ed-media { order: 0; } }
+    .ed-num { font-family: 'Newsreader', serif; font-style: italic; font-size: 1.05rem; color: var(--ink-3); }
+    .d-cat { display: inline-flex; align-items: center; gap: 7px; font-size: 0.68rem; font-weight: 700; letter-spacing: 0.04em; text-transform: uppercase;
+      padding: 4px 10px; border-radius: 999px; color: hsl(var(--ch) var(--tint-s) 74%);
+      background: hsl(var(--ch) var(--tint-s) 52% / 0.14); border: 1px solid hsl(var(--ch) var(--tint-s) 55% / 0.3); vertical-align: middle; }
+    [data-theme="light"] .d-cat { color: hsl(var(--ch) calc(var(--tint-s) + 12%) 36%); }
+    .d-cat svg { width: 13px; height: 13px; }
+    .d-title { font-family: 'Newsreader', serif; font-weight: 400; font-size: clamp(1.7rem, 3.6vw, 2.3rem); line-height: 1.1; margin-top: 14px; letter-spacing: -0.01em; }
+    .d-title .app { font-style: italic; color: var(--accent-ink); }
+    .d-blurb { color: var(--ink-2); font-size: 1rem; margin-top: 14px; text-wrap: pretty; max-width: 46ch; }
+    .d-meta { display: flex; flex-wrap: wrap; gap: 7px; margin-top: 18px; }
+    .d-pill { display: inline-flex; align-items: center; gap: 6px; font-size: 0.72rem; padding: 5px 10px; border-radius: 8px;
+      background: var(--chip-bg); border: 1px solid var(--line); color: var(--ink-2); }
+    .d-pill b { color: var(--ink); font-weight: 600; }
+    .d-pill code { font-family: 'JetBrains Mono', monospace; font-size: 0.7rem; color: var(--accent-ink); }
+    .d-foot { display: flex; align-items: center; gap: 12px; margin-top: 20px; flex-wrap: wrap; }
+    .d-contrib { display: inline-flex; align-items: center; gap: 9px; font-size: 0.82rem; color: var(--ink-2); text-decoration: none; }
+    .d-contrib:hover { color: var(--ink); }
+    .d-av { width: 28px; height: 28px; border-radius: 8px; display: grid; place-items: center; font-size: 0.64rem; font-weight: 700; text-transform: uppercase;
+      background: hsl(var(--ch) var(--tint-s) 52% / 0.2); color: hsl(var(--ch) var(--tint-s) 74%); border: 1px solid hsl(var(--ch) var(--tint-s) 55% / 0.35); }
+    [data-theme="light"] .d-av { color: hsl(var(--ch) calc(var(--tint-s) + 12%) 36%); }
+    .d-contrib b { color: var(--ink); font-weight: 600; }
+    /* Install command — parallel, low-key info (same code styling as the Hub, kept small). */
+    .ed-install { display: flex; align-items: center; gap: 10px; margin-top: 16px; max-width: 440px; }
+    .ed-install .lbl { font-size: 0.6rem; font-weight: 700; letter-spacing: 0.1em; text-transform: uppercase; color: var(--ink-3); flex-shrink: 0; }
+    .ed-cmd { flex: 1; min-width: 0; display: flex; align-items: center; gap: 8px; background: var(--cmd-bg);
+      border: 1px solid var(--cmd-line); border-radius: 9px; padding: 7px 11px; }
+    .ed-cmd code { font-family: 'JetBrains Mono', monospace; font-size: 0.74rem; color: var(--accent-ink);
+      white-space: nowrap; overflow: hidden; text-overflow: ellipsis; flex: 1; min-width: 0; }
+    .ed-copy { border: 0; background: transparent; color: var(--ink-3); font-size: 0.62rem; font-weight: 700; letter-spacing: 0.04em;
+      text-transform: uppercase; cursor: pointer; font-family: inherit; padding: 3px 5px; border-radius: 6px; flex-shrink: 0; transition: color .15s; }
+    .ed-copy:hover { color: var(--ink); }
+
+    /* media frame + chrome */
+    .ed-media { position: relative; }
+    .media { position: relative; border-radius: 16px; overflow: hidden; border: 1px solid var(--line); background: #05070b; box-shadow: var(--glass-shadow-hi); }
+    [data-theme="light"] .media { background: #e9edf3; }
+    .media-chrome { display: flex; align-items: center; gap: 7px; padding: 9px 13px; background: var(--cmd-bg); border-bottom: 1px solid var(--cmd-line); }
+    .media-chrome .dots { display: inline-flex; gap: 5px; }
+    .media-chrome .dots i { width: 9px; height: 9px; border-radius: 50%; }
+    .media-chrome .dots i:nth-child(1) { background: hsl(8 60% 60%); }
+    .media-chrome .dots i:nth-child(2) { background: hsl(45 70% 58%); }
+    .media-chrome .dots i:nth-child(3) { background: hsl(140 45% 55%); }
+    .media-chrome .url { font-family: 'JetBrains Mono', monospace; font-size: 0.68rem; color: var(--ink-3); flex: 1; min-width: 0; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+    .media-chrome .live { display: inline-flex; align-items: center; gap: 5px; font-size: 0.6rem; font-weight: 700; letter-spacing: 0.08em; text-transform: uppercase; color: var(--accent-ink); }
+    .media-chrome .live i { width: 6px; height: 6px; border-radius: 50%; background: var(--accent); box-shadow: 0 0 8px var(--accent); animation: pulse 1.6s infinite; }
+    @keyframes pulse { 0%,100% { opacity: 1; } 50% { opacity: 0.35; } }
+    .media-stage { position: relative; cursor: zoom-in; display: block; }
+    .media-stage img { display: block; width: 100%; height: auto; }
+    .media-zoom { position: absolute; bottom: 10px; right: 10px; display: inline-grid; place-items: center; width: 32px; height: 32px; border-radius: 9px;
+      background: rgba(0,0,0,0.5); color: #fff; opacity: 0; transition: opacity .2s; -webkit-backdrop-filter: blur(6px); backdrop-filter: blur(6px); }
+    .media-stage:hover .media-zoom { opacity: 1; }
+    .media-zoom svg { width: 16px; height: 16px; }
+    .ba-pair { display: grid; grid-template-columns: 1fr 1fr; }
+    .ba-pair .media-stage:first-child { border-right: 1px solid var(--cmd-line); }
+    .ba-label { position: absolute; top: 9px; left: 9px; font-size: 0.58rem; font-weight: 700; letter-spacing: 0.06em; text-transform: uppercase; color: #fff;
+      background: rgba(0,0,0,0.55); padding: 3px 8px; border-radius: 6px; -webkit-backdrop-filter: blur(4px); backdrop-filter: blur(4px); }
+    .artifact-toggle { display: inline-flex; align-items: center; gap: 7px; font-size: 0.78rem; font-weight: 600; cursor: pointer; margin-top: 14px;
+      border: 1px solid var(--line); background: var(--chip-bg); color: var(--accent-ink); padding: 8px 13px; border-radius: 10px; font-family: inherit; transition: border-color .18s; }
+    .artifact-toggle:hover { border-color: var(--accent); }
+    .artifact-toggle svg { width: 15px; height: 15px; transition: transform .3s; }
+    .artifact-toggle[aria-expanded="true"] svg { transform: rotate(180deg); }
+    .artifact-panel { display: none; margin-top: 14px; }
+    .artifact-panel.open { display: block; animation: fade .35s var(--ease); }
+    @keyframes fade { from { opacity: 0; transform: translateY(8px); } to { opacity: 1; transform: none; } }
+
+    /* ===================== Closing CTA ===================== */
+    .demos-end { max-width: 1100px; margin: 72px auto 0; padding: 0 22px; }
+    .demos-end .inner { padding: 36px; border-radius: var(--radius); text-align: center;
+      background: var(--glass-bg-fallback); border: 1px solid var(--glass-border); box-shadow: var(--glass-shadow); position: relative; overflow: hidden; }
+    @supports ((backdrop-filter: blur(1px))) { .demos-end .inner { background: var(--glass-bg); -webkit-backdrop-filter: blur(22px) saturate(1.5); backdrop-filter: blur(22px) saturate(1.5); } }
+    .demos-end .soon { font-family: 'Newsreader', serif; font-style: italic; color: var(--ink-3); font-size: 1.1rem; }
+    .demos-end h2 { font-family: 'Newsreader', serif; font-weight: 400; font-size: clamp(1.6rem, 3.6vw, 2.2rem); margin-top: 8px; }
+    .demos-end h2 em { font-style: italic; color: var(--accent-ink); }
+    .demos-end p { color: var(--ink-2); max-width: 56ch; margin: 12px auto 0; }
+    .demos-end .actions { display: flex; gap: 12px; justify-content: center; flex-wrap: wrap; margin-top: 24px; }
+    .btn-primary, .btn-secondary { display: inline-flex; align-items: center; gap: 9px; padding: 12px 20px; border-radius: 13px; text-decoration: none; font-weight: 700; font-size: 0.9rem; transition: transform .18s var(--ease), box-shadow .18s, border-color .18s; }
+    .btn-primary { color: #fff; background: linear-gradient(120deg, var(--accent2), var(--accent)); box-shadow: 0 12px 30px -14px rgba(var(--accent-rgb), 0.7); }
+    [data-theme="light"] .btn-primary { color: #fff; }
+    .btn-primary:hover { transform: translateY(-2px); }
+    .btn-secondary { color: var(--ink); border: 1px solid var(--glass-border); background: var(--chip-bg); }
+    .btn-secondary:hover { transform: translateY(-2px); border-color: var(--ink-3); }
+    .btn-primary svg, .btn-secondary svg { width: 17px; height: 17px; }
+
+    .footer { border-top: 1px solid var(--line); margin: 72px auto 0; max-width: 1180px; padding: 32px 22px 56px;
+      font-size: 0.84rem; color: var(--ink-3); display: flex; justify-content: space-between; gap: 16px; flex-wrap: wrap; }
+    .footer a { color: var(--accent-ink); text-decoration: none; font-weight: 600; }
+    .footer a:hover { text-decoration: underline; }
+
+    /* lightbox */
+    .lightbox { position: fixed; inset: 0; z-index: 100; display: none; place-items: center; padding: 4vmin;
+      background: rgba(3,5,9,0.86); -webkit-backdrop-filter: blur(8px); backdrop-filter: blur(8px); cursor: zoom-out; }
+    .lightbox.on { display: grid; animation: fade .25s var(--ease); }
+    .lightbox img { max-width: 94vw; max-height: 90vh; border-radius: 14px; box-shadow: 0 40px 120px -30px rgba(0,0,0,0.8); border: 1px solid rgba(255,255,255,0.12); }
+    .lightbox .lb-close { position: fixed; top: 18px; right: 22px; width: 42px; height: 42px; border-radius: 12px; display: grid; place-items: center;
+      background: rgba(255,255,255,0.1); color: #fff; border: 1px solid rgba(255,255,255,0.18); cursor: pointer; }
+    .lightbox .lb-close svg { width: 20px; height: 20px; }
+
+    @media (prefers-reduced-motion: reduce) {
+      * { animation-duration: 0.001ms !important; scroll-behavior: auto !important; }
+      .reveal { opacity: 1; transform: none; transition: none; }
+      .media-chrome .live i { animation: none; }
+    }
+  </style>
+</head>
+<body>
+  <div class="ambient"><i class="a"></i><i class="b"></i></div>
+  <div class="grain"></div>
+
+  <!-- Nav (shared with the Hub) -->
+  <nav class="nav" id="nav">
+    <div class="nav-in">
+      <a class="nav-brand" href="index.html" aria-label="Back to CLI-Anything Hub home"><span class="nav-brand-badge" aria-hidden="true"><svg viewBox="0 0 48 48" fill="none"><path d="M8 16.5 18.5 24 8 31.5" stroke="currentColor" stroke-width="3.9" stroke-linecap="square" stroke-linejoin="miter" style="color: var(--accent);"/><path d="M24 29.2h16" stroke="currentColor" stroke-width="3.9" stroke-linecap="square" style="color: var(--ink);"/></svg></span>CLI-Hub</a>
+      <div class="nav-links">
+        <div class="nav-menu" id="navMenu">
+        <a class="nav-link" href="index.html">
+          <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.85" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M3 10.5 12 3l9 7.5"/><path d="M5 9.5V20a1 1 0 0 0 1 1h12a1 1 0 0 0 1-1V9.5"/><path d="M9.5 21v-6h5v6"/></svg>
+          Home
+        </a>
+        <a class="nav-link active" href="demos.html" aria-current="page">
+          <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.85" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="3" y="4" width="18" height="14" rx="2"/><path d="m10 9 4 2.5L10 14z" fill="currentColor" stroke="none"/></svg>
+          Demos
+        </a>
+        <a class="nav-link" href="index.html#matrices">
+          <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.85" stroke-linecap="round" stroke-linejoin="round"><rect x="3.5" y="3.5" width="7" height="7" rx="1.6"/><rect x="13.5" y="3.5" width="7" height="7" rx="1.6"/><rect x="3.5" y="13.5" width="7" height="7" rx="1.6"/><rect x="13.5" y="13.5" width="7" height="7" rx="1.6"/></svg>
+          Matrices
+        </a>
+        <a class="nav-link" href="docs.html">
+          <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.85" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M4 4.8A1.8 1.8 0 0 1 5.8 3H12v17H5.8A1.8 1.8 0 0 0 4 21.8z"/><path d="M20 4.8A1.8 1.8 0 0 0 18.2 3H12v17h6.2A1.8 1.8 0 0 1 20 21.8z"/></svg>
+          Docs
+        </a>
+        <a class="nav-link" href="https://reeceyang.sgp1.cdn.digitaloceanspaces.com/SKILL.md" target="_blank">
+          <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.85" stroke-linecap="round" stroke-linejoin="round"><path d="m5.5 18.5 9.8-9.8"/><path d="m13.7 6.9 3.4 3.4"/><path d="M18 4v2.4"/><path d="M16.8 5.2h2.4"/><path d="M7.5 4.8v2"/><path d="M6.5 5.8h2"/><path d="M18.2 15.8v2"/><path d="M17.2 16.8h2"/></svg>
+          SKILL
+        </a>
+        <a class="nav-link" href="https://github.com/HKUDS/CLI-Anything" target="_blank">
+          <svg viewBox="0 0 98 96" fill="currentColor" aria-hidden="true"><path fill-rule="evenodd" clip-rule="evenodd" d="M48.854 0C21.839 0 0 22 0 49.217c0 21.756 13.993 40.172 33.405 46.69 2.427.49 3.316-1.059 3.316-2.362 0-1.141-.08-5.052-.08-9.127-13.59 2.934-16.42-5.867-16.42-5.867-2.184-5.704-5.42-7.17-5.42-7.17-4.448-3.015.324-3.015.324-3.015 4.934.326 7.523 5.052 7.523 5.052 4.367 7.496 11.404 5.378 14.235 4.074.404-3.178 1.699-5.378 3.074-6.6C29.304 70.25 17.9 66.013 17.9 47.02c0-5.52 1.94-10.046 5.127-13.58-.486-1.302-2.264-6.437.486-13.34 0 0 4.206-1.302 13.59 5.216 3.963-1.14 8.17-1.628 12.34-1.628 4.17 0 8.376.568 12.34 1.628 9.384-6.518 13.59-5.216 13.59-5.216 2.75 6.903.972 12.038.486 13.34 3.268 3.534 5.127 8.06 5.127 13.58 0 19.074-11.485 23.15-22.328 24.29 1.78 1.548 3.316 4.481 3.316 9.126 0 6.6-.08 11.897-.08 13.526 0 1.304.89 2.853 3.316 2.364 19.412-6.52 33.405-24.935 33.405-46.691C97.707 22 75.788 0 48.854 0z"/></svg>
+          GitHub
+          <span class="nav-link-stars" data-github-stars aria-label="GitHub star count">--</span>
+        </a>
+        <a class="nav-link" href="https://github.com/HKUDS/CLI-Anything/blob/main/CONTRIBUTING.md" target="_blank">Contribute</a>
+        </div>
+        <button class="theme-toggle keep" onclick="toggleTheme()" aria-label="Toggle theme">
+          <svg class="icon-sun" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="5"/><line x1="12" y1="1" x2="12" y2="3"/><line x1="12" y1="21" x2="12" y2="23"/><line x1="4.22" y1="4.22" x2="5.64" y2="5.64"/><line x1="18.36" y1="18.36" x2="19.78" y2="19.78"/><line x1="1" y1="12" x2="3" y2="12"/><line x1="21" y1="12" x2="23" y2="12"/><line x1="4.22" y1="19.78" x2="5.64" y2="18.36"/><line x1="18.36" y1="5.64" x2="19.78" y2="4.22"/></svg>
+          <svg class="icon-moon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M21 12.79A9 9 0 1 1 11.21 3 7 7 0 0 0 21 12.79z"/></svg>
+        </button>
+        <button class="nav-toggle keep" id="navToggle" aria-label="Menu" aria-expanded="false" aria-controls="navMenu">
+          <svg class="icon-bars" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round"><line x1="3" y1="6" x2="21" y2="6"/><line x1="3" y1="12" x2="21" y2="12"/><line x1="3" y1="18" x2="21" y2="18"/></svg>
+          <svg class="icon-x" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M18 6 6 18M6 6l12 12"/></svg>
+        </button>
+      </div>
+    </div>
+    <div class="nav-scrim" id="navScrim"></div>
+  </nav>
+
+  <!-- Page header -->
+  <header class="phead">
+    <span class="klabel">Real-World Demos</span>
+    <h1>Agents, doing <em>real work</em></h1>
+    <p><span class="lead">AI agents using generated CLIs to produce complete, useful artifacts — no GUI needed.</span> Each run below is a real session: the agent reads state, issues commands, and ships an artifact you can open.</p>
+  </header>
+
+  <!-- Editorial gallery -->
+  <main class="editorial" id="editorial"></main>
+
+  <!-- Closing CTA -->
+  <section class="demos-end">
+    <div class="inner glass-none">
+      <div class="soon">More CLI demos coming soon.</div>
+      <h2>Built something with a CLI-Anything harness? <em>Show it off.</em></h2>
+      <p>Record a short run of your agent driving a generated CLI, and add it here. The Contributing Guide and PR Template walk you through it.</p>
+      <div class="actions">
+        <a class="btn-primary" href="https://github.com/HKUDS/CLI-Anything/blob/main/CONTRIBUTING.md" target="_blank">
+          <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M12 5v14M5 12h14"/></svg>
+          Add your demo
+        </a>
+        <a class="btn-secondary" href="index.html">
+          <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M19 12H5"/><path d="m12 5-7 7 7 7"/></svg>
+          Back to the Hub
+        </a>
+      </div>
+    </div>
+  </section>
+
+  <footer class="footer">
+    <span>CLI-Anything Hub — agent-friendly CLI registry.</span>
+    <span><a href="index.html">Home</a> · <a href="index.html#matrices">Matrices</a> · <a href="https://github.com/HKUDS/CLI-Anything" target="_blank">GitHub</a></span>
+  </footer>
+
+  <!-- Lightbox -->
+  <div class="lightbox" id="lightbox">
+    <button class="lb-close" aria-label="Close"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M18 6 6 18M6 6l12 12"/></svg></button>
+    <img id="lb-img" src="" alt="">
+  </div>
+
+  <script>
+    // ===================== Palette + theme (shared with the Hub) =====================
+    const PALETTES = {
+      steel: { label:'Steel', accentBand:209,
+        light:{ bg:'#f4f6f9', surface:'#ffffff', ink:'#14181f', ink2:'#4a5568', ink3:'#8595a8', line:'rgba(20,40,80,.10)', accent:'#2f6fb0', accent2:'#1f5793', accentRgb:'47,111,176', surfaceRgb:'255,255,255' },
+        dark:{ bg:'#0d1117', surface:'#151b24', ink:'#e8edf4', ink2:'#9fb0c4', ink3:'#647488', line:'rgba(255,255,255,.08)', accent:'#5b9bd6', accent2:'#7db4e6', accentRgb:'91,155,214', surfaceRgb:'21,27,36' } },
+      steelsky: { label:'Steel Sky', accentBand:203,
+        light:{ bg:'#f4f6f9', surface:'#ffffff', ink:'#14181f', ink2:'#4a5568', ink3:'#8595a8', line:'rgba(20,40,80,.10)', accent:'#1c8ee0', accent2:'#1573bd', accentRgb:'28,142,224', surfaceRgb:'255,255,255' },
+        dark:{ bg:'#0d1117', surface:'#151b24', ink:'#e8edf4', ink2:'#9fb0c4', ink3:'#647488', line:'rgba(255,255,255,.08)', accent:'#46b2f4', accent2:'#6cc6f8', accentRgb:'70,178,244', surfaceRgb:'21,27,36' } },
+      sky: { label:'Sky', accentBand:203,
+        light:{ bg:'#f4f9fe', surface:'#ffffff', ink:'#0f1f2d', ink2:'#465a6b', ink3:'#8299ac', line:'rgba(20,70,115,.10)', accent:'#1c8ee0', accent2:'#1573bd', accentRgb:'28,142,224', surfaceRgb:'255,255,255' },
+        dark:{ bg:'#0a1320', surface:'#121e2d', ink:'#e9f3fb', ink2:'#9bb4c9', ink3:'#5f7689', line:'rgba(255,255,255,.08)', accent:'#46b2f4', accent2:'#6cc6f8', accentRgb:'70,178,244', surfaceRgb:'18,30,45' } },
+      sage: { label:'Sage', accentBand:160,
+        light:{ bg:'#f3f8f4', surface:'#ffffff', ink:'#13211b', ink2:'#475a51', ink3:'#7f968a', line:'rgba(20,65,48,.10)', accent:'#2c9b78', accent2:'#1d8062', accentRgb:'44,155,120', surfaceRgb:'255,255,255' },
+        dark:{ bg:'#0b1410', surface:'#121d18', ink:'#e7f2eb', ink2:'#9ab4a7', ink3:'#5e7568', line:'rgba(255,255,255,.07)', accent:'#48c29c', accent2:'#67d0b1', accentRgb:'72,194,156', surfaceRgb:'18,29,24' } },
+      sand: { label:'Sand', accentBand:175,
+        light:{ bg:'#f8f5ef', surface:'#fffdf8', ink:'#221d15', ink2:'#585044', ink3:'#948979', line:'rgba(75,58,30,.12)', accent:'#1d7a71', accent2:'#145d57', accentRgb:'29,122,113', surfaceRgb:'255,253,248' },
+        dark:{ bg:'#13110b', surface:'#1b1811', ink:'#f1ece1', ink2:'#b2a797', ink3:'#796e5e', line:'rgba(255,255,255,.07)', accent:'#3eb2a4', accent2:'#5cc3b6', accentRgb:'62,178,164', surfaceRgb:'27,24,17' } },
+      blush: { label:'Blush', accentBand:3,
+        light:{ bg:'#faf6f4', surface:'#fffefd', ink:'#271d1c', ink2:'#5e504e', ink3:'#9b8a87', line:'rgba(90,50,45,.11)', accent:'#c25e5a', accent2:'#a4453f', accentRgb:'194,94,90', surfaceRgb:'255,254,253' },
+        dark:{ bg:'#140f0e', surface:'#1c1615', ink:'#f3eae8', ink2:'#b6a4a1', ink3:'#7d6b68', line:'rgba(255,255,255,.07)', accent:'#df8480', accent2:'#e89f9b', accentRgb:'223,132,128', surfaceRgb:'28,22,21' } },
+      mist: { label:'Mist', accentBand:222,
+        light:{ bg:'#f6f8fb', surface:'#ffffff', ink:'#171b22', ink2:'#4e586a', ink3:'#8893a6', line:'rgba(25,35,60,.09)', accent:'#3b6ef0', accent2:'#2f57cf', accentRgb:'59,110,240', surfaceRgb:'255,255,255' },
+        dark:{ bg:'#0a0d14', surface:'#12161f', ink:'#eef1f7', ink2:'#9aa6bd', ink3:'#606b82', line:'rgba(255,255,255,.07)', accent:'#5b8bff', accent2:'#789fff', accentRgb:'91,139,255', surfaceRgb:'18,22,31' } },
+    };
+    const DEFAULT_PALETTE = 'steelsky';
+    function getPalette() { const s = localStorage.getItem('palette'); return (s && PALETTES[s]) ? s : DEFAULT_PALETTE; }
+    function applyPalette(name) {
+      const p = PALETTES[name] || PALETTES[DEFAULT_PALETTE];
+      const theme = document.documentElement.getAttribute('data-theme') || 'dark';
+      const t = (theme === 'light') ? p.light : p.dark;
+      const r = document.documentElement.style;
+      r.setProperty('--bg', t.bg); r.setProperty('--surface', t.surface);
+      r.setProperty('--ink', t.ink); r.setProperty('--ink-2', t.ink2); r.setProperty('--ink-3', t.ink3);
+      r.setProperty('--line', t.line); r.setProperty('--accent', t.accent); r.setProperty('--accent2', t.accent2);
+      r.setProperty('--accent-rgb', t.accentRgb); r.setProperty('--surface-rgb', t.surfaceRgb);
+      r.setProperty('--accent-band', String(p.accentBand));
+      document.documentElement.setAttribute('data-palette', name);
+    }
+    function getPreferredTheme() { const s = localStorage.getItem('theme'); if (s) return s; return window.matchMedia('(prefers-color-scheme: light)').matches ? 'light' : 'dark'; }
+    function applyTheme(t) { document.documentElement.setAttribute('data-theme', t); applyPalette(getPalette()); }
+    function toggleTheme() { const cur = document.documentElement.getAttribute('data-theme') || 'dark'; const next = cur === 'dark' ? 'light' : 'dark'; applyTheme(next); localStorage.setItem('theme', next); }
+    applyTheme(getPreferredTheme());
+    window.matchMedia('(prefers-color-scheme: light)').addEventListener('change', (e) => { if (!localStorage.getItem('theme')) applyTheme(e.matches ? 'light' : 'dark'); });
+
+    // nav scrolled
+    (function () { const nav = document.getElementById('nav'); const on = () => nav.classList.toggle('scrolled', window.scrollY > 8);
+      window.addEventListener('scroll', on, { passive: true }); on(); })();
+
+    // mobile nav drawer
+    (function () {
+      const toggle = document.getElementById('navToggle');
+      const menu = document.getElementById('navMenu');
+      const scrim = document.getElementById('navScrim');
+      if (!toggle || !menu) return;
+      function setOpen(open) {
+        menu.classList.toggle('open', open);
+        toggle.classList.toggle('open', open);
+        if (scrim) scrim.classList.toggle('open', open);
+        toggle.setAttribute('aria-expanded', String(open));
+        document.body.style.overflow = open ? 'hidden' : '';
+      }
+      toggle.addEventListener('click', () => setOpen(!menu.classList.contains('open')));
+      if (scrim) scrim.addEventListener('click', () => setOpen(false));
+      menu.addEventListener('click', (e) => { if (e.target.closest('a')) setOpen(false); });
+      document.addEventListener('keydown', (e) => { if (e.key === 'Escape') setOpen(false); });
+      window.addEventListener('resize', () => { if (window.innerWidth > 860) setOpen(false); });
+    })();
+
+    // GitHub stars — shields.io badge first (CORS-friendly, no rate limit), API fallback. Matches the Hub.
+    const GITHUB_REPO_API = 'https://api.github.com/repos/HKUDS/CLI-Anything';
+    const GITHUB_STARS_BADGE_API = 'https://img.shields.io/github/stars/HKUDS/CLI-Anything.json';
+    function renderGitHubStars(label, title) {
+      document.querySelectorAll('[data-github-stars]').forEach(el => { el.textContent = label; el.setAttribute('aria-label', title); el.title = title; });
+    }
+    function formatCompactCount(value) {
+      return new Intl.NumberFormat('en', { notation: 'compact', maximumFractionDigits: value >= 10000 ? 0 : 1 }).format(value);
+    }
+    function formatBadgeCount(value) {
+      if (typeof value !== 'string') return null;
+      const label = value.trim();
+      return label ? label.toUpperCase() : null;
+    }
+    (async function loadGitHubStars() {
+      try {
+        try {
+          const badgeResp = await fetch(GITHUB_STARS_BADGE_API);
+          if (badgeResp.ok) {
+            const badge = await badgeResp.json();
+            const badgeLabel = formatBadgeCount(badge.message || badge.value);
+            if (badgeLabel) { renderGitHubStars(badgeLabel, `${badgeLabel} GitHub stars`); return; }
+          }
+        } catch (_) {}
+        const resp = await fetch(GITHUB_REPO_API, { headers: { 'Accept': 'application/vnd.github+json' } });
+        if (!resp.ok) return;
+        const repo = await resp.json();
+        const stars = repo.stargazers_count;
+        if (typeof stars !== 'number') return;
+        renderGitHubStars(formatCompactCount(stars), `${stars.toLocaleString('en-US')} GitHub stars`);
+      } catch (_) {}
+    })();
+
+    // ===================== Demo data (verbatim from README · Real-World Demos) =====================
+    const A = 'assets/demos/';
+    const DEMOS = [
+      { id:'freecad', app:'FreeCAD', cat:'3D / CAD', hue:210, glyph:'cube',
+        title:'Curiosity Rover via Preview, Live Preview, and Trajectory',
+        blurb:'An agent incrementally assembles a Curiosity-inspired rover while publishing real FreeCAD preview bundles, refreshing a live preview session, and recording command-to-preview history for later replay.',
+        meta:[['Harness','cli-anything-freecad','code'],['Preview Stack','preview · live · trajectory'],['Artifact','Curiosity-style rover']],
+        media:{type:'gif', src:'freecad-curiosity-preview-trajectory.gif', url:'cli-anything-freecad · preview live', live:true},
+        contrib:{name:'Core team', sub:'CLI-Anything'} },
+      { id:'blender', app:'Blender', cat:'3D · Hard-surface', hue:28, glyph:'cube',
+        title:'Orbital Relay Drone via Preview, Live Preview, and Trajectory',
+        blurb:'An agent grows a hard-surface orbital relay drone under a real preview loop: each stage pushes new render-backed bundles, the live session tracks the current head, and the trajectory ties every command to its visual state.',
+        meta:[['Harness','cli-anything-blender','code'],['Preview Stack','preview · live · trajectory'],['Artifact','Orbital relay drone']],
+        media:{type:'gif', src:'blender-orbital-relay-drone-preview-trajectory.gif', url:'cli-anything-blender · preview live', live:true},
+        contrib:{name:'Core team', sub:'CLI-Anything'} },
+      { id:'drawio', app:'Draw.io', cat:'Diagramming', hue:250, glyph:'diagram',
+        title:'HTTPS Handshake Diagram',
+        blurb:'An agent creates a full HTTPS connection lifecycle diagram from scratch — TCP three-way handshake, TLS negotiation, encrypted data exchange, and TCP four-way termination — entirely through CLI commands.',
+        meta:[['Harness','cli-anything-drawio','code'],['Time','~4 min'],['Artifact','.drawio + .png']],
+        media:{type:'gif', src:'drawio-demo.gif', url:'cli-anything-drawio · build', live:true},
+        artifact:{label:'Final artifact', src:'drawio-https-handshake.png', alt:'HTTPS handshake sequence diagram'},
+        contrib:{name:'@zhangxilong-43', url:'https://github.com/zhangxilong-43'} },
+      { id:'sts2', app:'Slay the Spire II', cat:'Games', hue:350, glyph:'game',
+        title:'Game Automation',
+        blurb:'An agent plays through a Slay the Spire II run using the CLI harness — reading game state, selecting cards, choosing paths, and making strategic decisions in real-time.',
+        meta:[['Harness','cli-anything-slay-the-spire-ii','code'],['Artifact','Automated gameplay session']],
+        media:{type:'gif', src:'slay-the-spire-ii-gameplay.gif', url:'cli-anything-slay-the-spire-ii', live:true},
+        contrib:{name:'@TianyuFan0504', url:'https://github.com/TianyuFan0504'} },
+      { id:'videocaptioner', app:'VideoCaptioner', cat:'Video', hue:280, glyph:'video',
+        title:'Auto-Generated Subtitles',
+        blurb:'An agent uses the VideoCaptioner CLI to automatically generate and overlay styled subtitles onto video content, with bilingual text rendering and customizable formatting.',
+        meta:[['Harness','cli-anything-videocaptioner','code'],['Artifact','Captioned video frames']],
+        media:{type:'ba', a:{src:'videocaptioner-before.png', label:'Sub A'}, b:{src:'videocaptioner-after.png', label:'Sub B'}, url:'cli-anything-videocaptioner · before / after'},
+        contrib:{name:'@WEIFENG2333', url:'https://github.com/WEIFENG2333'} },
+      { id:'arcgis', app:'ArcGIS Pro', cat:'GIS · Live bridge', hue:160, glyph:'map',
+        title:'Live Agent Cartography via the MCP Bridge',
+        blurb:'An agent drives a live, open ArcGIS Pro session through an MCP bridge — reading the project, zooming to feature layers, running geoprocessing, and exporting layouts — each step executing inside Pro as you watch.',
+        meta:[['Harness','arcgis-pro','code'],['Mode','live-Pro MCP bridge'],['Artifact','Agent-driven map navigation']],
+        media:{type:'gif', src:'arcgis-pro-live-bridge-demo.gif', url:'arcgis-pro · MCP bridge', live:true},
+        contrib:{name:'@Jasper0122', url:'https://github.com/Jasper0122'} },
+    ];
+    // Install command per demo (CLI-Hub registry names) — parallel info on each card.
+    const DEMO_INSTALL = {
+      freecad: 'cli-hub install freecad', blender: 'cli-hub install blender', drawio: 'cli-hub install drawio',
+      sts2: 'cli-hub install slay_the_spire_ii', videocaptioner: 'cli-hub install videocaptioner', arcgis: 'cli-hub install arcgis-pro',
+    };
+    function installRow(d) {
+      const cmd = DEMO_INSTALL[d.id]; if (!cmd) return '';
+      return `<div class="ed-install"><span class="lbl">Install</span><span class="ed-cmd"><code>${cmd}</code>` +
+        `<button class="ed-copy" onclick="copyEd(this, '${cmd}')" aria-label="Copy install command">Copy</button></span></div>`;
+    }
+    function copyEd(btn, cmd) {
+      if (!navigator.clipboard) return;
+      navigator.clipboard.writeText(cmd).then(() => { const o = btn.textContent; btn.textContent = 'Copied'; setTimeout(() => { btn.textContent = o; }, 1200); }).catch(() => {});
+    }
+    const GLYPHS = {
+      cube:'<path d="M12 2 3 7v10l9 5 9-5V7z"/><path d="M3 7l9 5 9-5"/><path d="M12 12v10"/>',
+      diagram:'<rect x="3" y="3" width="7" height="5" rx="1"/><rect x="14" y="16" width="7" height="5" rx="1"/><path d="M6.5 8v4a2 2 0 0 0 2 2h9"/>',
+      game:'<rect x="2" y="7" width="20" height="10" rx="5"/><path d="M7 11v2M6 12h2"/><circle cx="16" cy="11.5" r=".6" fill="currentColor"/><circle cx="18" cy="13.5" r=".6" fill="currentColor"/>',
+      video:'<rect x="3" y="5" width="18" height="14" rx="2"/><path d="m10 9 5 3-5 3z" fill="currentColor" stroke="none"/>',
+      map:'<path d="m9 4-6 2v14l6-2 6 2 6-2V4l-6 2-6-2z"/><path d="M9 4v16M15 6v16"/>',
+    };
+    const svg = (g) => `<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round">${GLYPHS[g]}</svg>`;
+    const ZOOM = '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M15 3h6v6"/><path d="M9 21H3v-6"/><path d="M21 3l-7 7"/><path d="M3 21l7-7"/></svg>';
+
+    function pills(d) { return d.meta.map(([k,v,c]) => `<span class="d-pill"><b>${k}</b> ${c?`<code>${v}</code>`:v}</span>`).join(''); }
+    function contrib(d) {
+      const c = d.contrib;
+      const initials = c.url ? c.name.replace('@','').slice(0,2) : 'CA';
+      const inner = `<span class="d-av">${initials}</span><span>${c.url ? 'Contributed by <b>'+c.name+'</b>' : '<b>Core team</b> · '+c.sub}</span>`;
+      return c.url ? `<a class="d-contrib" href="${c.url}" target="_blank" rel="noopener">${inner}</a>` : `<span class="d-contrib">${inner}</span>`;
+    }
+    function media(m, id) {
+      const chrome = `<div class="media-chrome"><span class="dots"><i></i><i></i><i></i></span><span class="url">${m.url||''}</span>${m.live?'<span class="live"><i></i>live</span>':''}</div>`;
+      if (m.type === 'ba') {
+        return `<div class="media">${chrome}<div class="ba-pair">
+          <div class="media-stage" data-full="${A+m.a.src}"><span class="ba-label">${m.a.label}</span><img loading="lazy" src="${A+m.a.src}" alt="${id} before"><span class="media-zoom">${ZOOM}</span></div>
+          <div class="media-stage" data-full="${A+m.b.src}"><span class="ba-label">${m.b.label}</span><img loading="lazy" src="${A+m.b.src}" alt="${id} after"><span class="media-zoom">${ZOOM}</span></div></div></div>`;
+      }
+      return `<div class="media">${chrome}<div class="media-stage" data-full="${A+m.src}"><img loading="lazy" src="${A+m.src}" alt="${id} demo"><span class="media-zoom">${ZOOM}</span></div></div>`;
+    }
+    function artifact(d) {
+      if (!d.artifact) return '';
+      return `<button class="artifact-toggle" aria-expanded="false" onclick="toggleArtifact(this)">${d.artifact.label}
+        <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round"><path d="m6 9 6 6 6-6"/></svg></button>
+        <div class="artifact-panel"><div class="media"><div class="media-stage" data-full="${A+d.artifact.src}"><img loading="lazy" src="${A+d.artifact.src}" alt="${d.artifact.alt}"><span class="media-zoom">${ZOOM}</span></div></div></div>`;
+    }
+    function toggleArtifact(btn) {
+      const open = btn.getAttribute('aria-expanded') === 'true';
+      btn.setAttribute('aria-expanded', String(!open));
+      btn.nextElementSibling.classList.toggle('open', !open);
+    }
+
+    document.getElementById('editorial').innerHTML = DEMOS.map((d,i) => `
+      <article class="ed-row reveal" id="${d.id}" style="--ch:${d.hue}">
+        <div class="ed-media">${media(d.media, d.id)}${artifact(d)}</div>
+        <div class="ed-text">
+          <span class="d-cat">${svg(d.glyph)}${d.cat}</span>
+          <h2 class="d-title"><span class="app">${d.app}</span> — ${d.title}</h2>
+          <p class="d-blurb">${d.blurb}</p>
+          <div class="d-meta">${pills(d)}</div>
+          ${installRow(d)}
+          <div class="d-foot">${contrib(d)}</div>
+        </div>
+      </article>`).join('');
+
+    // reveal on scroll
+    (function () {
+      const io = new IntersectionObserver((es) => es.forEach(e => { if (e.isIntersecting) { e.target.classList.add('in'); io.unobserve(e.target); } }), { rootMargin: '0px 0px -8% 0px' });
+      document.querySelectorAll('.reveal').forEach(el => io.observe(el));
+    })();
+
+    // lightbox
+    const lb = document.getElementById('lightbox'), lbImg = document.getElementById('lb-img');
+    document.addEventListener('click', (e) => {
+      const stage = e.target.closest('.media-stage');
+      if (stage && stage.dataset.full) { lbImg.src = stage.dataset.full; lb.classList.add('on'); return; }
+      if (e.target.closest('.lb-close') || e.target === lb) { lb.classList.remove('on'); lbImg.src = ''; }
+    });
+    document.addEventListener('keydown', (e) => { if (e.key === 'Escape' && lb.classList.contains('on')) { lb.classList.remove('on'); lbImg.src = ''; } });
+  </script>
+</body>
+</html>
diff --git a/docs/hub/docs.html b/docs/hub/docs.html
new file mode 100644
index 000000000..683620bd0
--- /dev/null
+++ b/docs/hub/docs.html
@@ -0,0 +1,718 @@
+<!DOCTYPE html>
+<html lang="en" data-theme="dark">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <meta name="robots" content="index,follow,max-snippet:-1,max-image-preview:large,max-video-preview:-1">
+  <title>Documentation — CLI-Anything Hub</title>
+  <meta name="description" content="How to use cli-hub: install and launch agent-native CLIs from the catalog, and drive capability-based Workflow Matrices — search, preflight, progressive install, doctor, and JSON automation.">
+  <meta name="author" content="HKUDS and Yuhao Yang">
+  <meta name="copyright" content="Copyright: HKUDS. Lead author: Yuhao Yang (yuhao.page).">
+  <link rel="canonical" href="https://clianything.cc/docs.html">
+  <meta property="og:type" content="website">
+  <meta property="og:site_name" content="CLI-Anything Hub">
+  <meta property="og:title" content="Documentation — CLI-Anything Hub">
+  <meta property="og:description" content="Use cli-hub to install agent-native CLIs and drive capability-based Workflow Matrices.">
+  <meta property="og:url" content="https://clianything.cc/docs.html">
+  <meta name="twitter:card" content="summary">
+  <meta name="twitter:title" content="Documentation — CLI-Anything Hub">
+  <meta name="twitter:description" content="Install agent-native CLIs and drive Workflow Matrices from one command.">
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <link href="https://fonts.googleapis.com/css2?family=Hanken+Grotesk:ital,wght@0,400;0,500;0,600;0,700;0,800;1,500&family=Instrument+Serif:ital@0;1&family=JetBrains+Mono:wght@400;500;600&family=Newsreader:ital,opsz,wght@0,6..72,300;0,6..72,400;0,6..72,500;1,6..72,300;1,6..72,400&display=swap" rel="stylesheet">
+  <style>
+    /* ===================== Tokens — shared with the Hub (Steel Sky default; set by JS per palette×theme) ===================== */
+    :root {
+      color-scheme: dark;
+      --bg: #0d1117; --surface: #151b24;
+      --ink: #e8edf4; --ink-2: #9fb0c4; --ink-3: #647488;
+      --line: rgba(255,255,255,0.08);
+      --accent: #46b2f4; --accent2: #6cc6f8; --accent-rgb: 70,178,244;
+      --surface-rgb: 21,27,36; --accent-band: 203;
+      --ok: #54d196; --radius: 22px; --radius-sm: 13px;
+      --accent-ink: var(--accent2);
+      --glass-bg: linear-gradient(158deg, rgba(255,255,255,0.075), rgba(255,255,255,0.024) 46%, rgba(255,255,255,0.010));
+      --glass-bg-fallback: rgba(var(--surface-rgb), 0.86);
+      --glass-border: var(--line);
+      --glass-edge: rgba(255,255,255,0.14);
+      --glass-shadow: 0 24px 60px -22px rgba(0,0,0,0.62), 0 2px 8px -2px rgba(0,0,0,0.48);
+      --glass-shadow-hi: 0 38px 90px -28px rgba(0,0,0,0.70), 0 4px 14px -4px rgba(0,0,0,0.52);
+      --chip-bg: rgba(255,255,255,0.055);
+      --cmd-bg: rgba(0,0,0,0.30); --cmd-line: rgba(255,255,255,0.08);
+      --tint-s: 52%; --tint-l: 62%;
+      --ease: cubic-bezier(.22,.61,.36,1);
+      --spring: cubic-bezier(.34,1.32,.5,1);
+      --palette-transition: background .45s var(--ease), color .45s var(--ease), border-color .45s var(--ease);
+    }
+    [data-theme="light"] {
+      color-scheme: light;
+      --bg: #f4f6f9; --surface: #ffffff;
+      --ink: #14181f; --ink-2: #4a5568; --ink-3: #8595a8;
+      --line: rgba(20,40,80,0.10);
+      --accent: #1c8ee0; --accent2: #1573bd; --accent-rgb: 28,142,224;
+      --surface-rgb: 255,255,255;
+      --accent-ink: var(--accent2);
+      --glass-bg: linear-gradient(158deg, rgba(255,255,255,0.92), rgba(255,255,255,0.62) 48%, rgba(255,255,255,0.42));
+      --glass-bg-fallback: rgba(var(--surface-rgb), 0.92);
+      --glass-edge: rgba(255,255,255,0.96);
+      --glass-shadow: 0 22px 50px -24px rgba(30,44,70,0.22), 0 2px 6px -2px rgba(30,44,70,0.12);
+      --glass-shadow-hi: 0 34px 80px -28px rgba(30,44,70,0.28), 0 4px 12px -4px rgba(30,44,70,0.16);
+      --chip-bg: rgba(20,40,80,0.045);
+      --cmd-bg: rgba(20,40,80,0.05); --cmd-line: rgba(20,40,80,0.08);
+      --tint-s: 46%; --tint-l: 44%;
+    }
+    body, .nav.scrolled { transition: var(--palette-transition); }
+
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    html { scroll-behavior: smooth; scroll-padding-top: 84px; -webkit-text-size-adjust: 100%; }
+    body { font-family: 'Hanken Grotesk', sans-serif; background: var(--bg); color: var(--ink);
+      line-height: 1.6; font-size: 16px; letter-spacing: -0.004em;
+      -webkit-font-smoothing: antialiased; -moz-osx-font-smoothing: grayscale; min-height: 100vh; overflow-x: hidden; }
+    ::selection { background: rgba(var(--accent-rgb), 0.30); color: var(--ink); }
+    a { color: inherit; }
+    button { font-family: inherit; }
+    h1,h2,h3,h4 { letter-spacing: -0.022em; line-height: 1.1; font-weight: 700; }
+    code, .mono { font-family: 'JetBrains Mono', monospace; }
+
+    /* ambient + grain + glass (shared) */
+    .ambient { position: fixed; inset: 0; z-index: -2; overflow: hidden; pointer-events: none; }
+    .ambient i { position: absolute; border-radius: 50%; filter: blur(100px); opacity: 0.7; }
+    .ambient .a { width: 60vw; max-width: 760px; aspect-ratio: 1; top: -18vw; right: -10vw;
+      background: radial-gradient(circle at 38% 38%, hsl(calc(var(--accent-band) + 28) var(--tint-s) 58% / 0.26), transparent 64%); }
+    .ambient .b { width: 50vw; max-width: 620px; aspect-ratio: 1; bottom: -16vw; left: -12vw;
+      background: radial-gradient(circle at 60% 42%, hsl(var(--accent-band) calc(var(--tint-s) + 12%) 56% / 0.24), transparent 62%); }
+    .grain { position: fixed; inset: 0; z-index: -1; pointer-events: none; opacity: 0.04; mix-blend-mode: overlay;
+      background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='120' height='120'%3E%3Cfilter id='n'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='0.9' numOctaves='2'/%3E%3C/filter%3E%3Crect width='100%25' height='100%25' filter='url(%23n)'/%3E%3C/svg%3E"); }
+
+    /* ===================== Nav (shared with Hub) ===================== */
+    .nav { position: sticky; top: 0; z-index: 40; border-bottom: 1px solid transparent; transition: border-color .3s, background .3s, backdrop-filter .3s; }
+    .nav.scrolled { border-color: var(--line); background: color-mix(in oklab, var(--bg) 78%, transparent);
+      -webkit-backdrop-filter: blur(16px) saturate(1.4); backdrop-filter: blur(16px) saturate(1.4); }
+    .nav-in { max-width: 1180px; margin: 0 auto; padding: 0 22px; display: flex; align-items: center; justify-content: space-between; gap: 14px; height: 64px; }
+    .nav-brand { display: inline-flex; align-items: center; gap: 9px; text-decoration: none; font-weight: 800; font-size: 1.08rem; letter-spacing: -0.02em; }
+    .nav-brand-badge { width: 30px; height: 30px; display: grid; place-items: center; border-radius: 9px; flex-shrink: 0;
+      border: 1px solid var(--glass-border); background: var(--chip-bg); box-shadow: var(--glass-shadow); }
+    .nav-brand-badge svg { width: 64%; height: 64%; }
+    .nav-links { display: flex; align-items: center; gap: 4px; }
+    .nav-link { padding: 7px 11px; border-radius: 10px; text-decoration: none; color: var(--ink-2); font-size: 0.84rem; font-weight: 500;
+      transition: color .18s, background .18s; display: inline-flex; align-items: center; gap: 6px; }
+    .nav-link:hover { color: var(--ink); background: var(--chip-bg); }
+    .nav-link.active { color: var(--ink); background: var(--chip-bg); }
+    .nav-link svg { width: 15px; height: 15px; flex-shrink: 0; }
+    .nav-link-stars { font-family: 'JetBrains Mono', monospace; font-size: 0.72rem; font-weight: 600; color: var(--accent-ink);
+      background: var(--chip-bg); border: 1px solid var(--line); border-radius: 7px; padding: 1px 7px; font-variant-numeric: tabular-nums; }
+    .theme-toggle { display: inline-grid; place-items: center; width: 36px; height: 36px; border-radius: 11px;
+      border: 1px solid var(--line); background: var(--chip-bg); color: var(--ink-2); cursor: pointer; transition: color .18s, border-color .18s; }
+    .theme-toggle:hover { color: var(--ink); border-color: var(--ink-3); }
+    .theme-toggle svg { width: 17px; height: 17px; }
+    .theme-toggle .icon-moon { display: none; }
+    [data-theme="light"] .theme-toggle .icon-moon { display: block; }
+    [data-theme="light"] .theme-toggle .icon-sun { display: none; }
+
+    /* Mobile nav drawer */
+    .nav-menu { display: flex; align-items: center; gap: 4px; }
+    .nav-toggle { display: none; position: relative; z-index: 70; place-items: center; width: 38px; height: 38px;
+      border-radius: 11px; border: 1px solid var(--line); background: var(--chip-bg); color: var(--ink); cursor: pointer;
+      transition: color .18s, border-color .18s; }
+    .nav-toggle:hover { border-color: var(--ink-3); }
+    .nav-toggle svg { width: 19px; height: 19px; }
+    .nav-toggle .icon-x { display: none; }
+    .nav-toggle.open .icon-bars { display: none; }
+    .nav-toggle.open .icon-x { display: block; }
+    .nav-scrim { position: fixed; inset: 0; z-index: 55; background: rgba(2,5,10,0.5);
+      -webkit-backdrop-filter: blur(2px); backdrop-filter: blur(2px); opacity: 0; visibility: hidden;
+      transition: opacity .3s var(--ease), visibility .3s; }
+    .nav-scrim.open { opacity: 1; visibility: visible; }
+    .nav-menu.open { transform: none; }
+    @media (max-width: 860px) {
+      .nav-toggle { display: inline-grid; }
+      .nav-menu { position: fixed; top: 0; right: 0; height: 100dvh; width: min(82vw, 320px);
+        flex-direction: column; align-items: stretch; gap: 6px; padding: 80px 16px 28px;
+        background: var(--glass-bg-fallback); border-left: 1px solid var(--line);
+        box-shadow: -24px 0 64px -28px rgba(0,0,0,0.6); transform: translateX(106%);
+        transition: transform .34s var(--ease); overflow-y: auto; z-index: 60; }
+      .nav-menu .nav-link { padding: 12px 14px; font-size: 0.98rem; border-radius: 11px; color: var(--ink-2); }
+      .nav-menu .nav-link.active { color: var(--ink); background: var(--chip-bg); }
+      .nav-menu .nav-link svg { width: 19px; height: 19px; }
+      .nav-menu .nav-link-stars { margin-left: auto; }
+    }
+    @supports ((backdrop-filter: blur(1px)) or (-webkit-backdrop-filter: blur(1px))) {
+      @media (max-width: 860px) {
+        .nav-menu { background: var(--glass-bg); -webkit-backdrop-filter: blur(22px) saturate(1.4); backdrop-filter: blur(22px) saturate(1.4); }
+      }
+    }
+
+    .reveal { opacity: 0; transform: translateY(20px); transition: opacity .7s var(--ease), transform .7s var(--ease); }
+    .reveal.in { opacity: 1; transform: none; }
+
+    /* ===================== Page header ===================== */
+    .phead { max-width: 1180px; margin: 0 auto; padding: 60px 22px 6px; }
+    .klabel { font-size: 0.72rem; font-weight: 700; letter-spacing: 0.16em; text-transform: uppercase; color: var(--accent-ink); }
+    .phead h1 { font-family: 'Newsreader', serif; font-weight: 400; color: var(--ink);
+      font-size: clamp(2.4rem, 6vw, 4rem); letter-spacing: -0.018em; line-height: 1.04; margin-top: 14px; }
+    .phead h1 em { font-style: italic; font-weight: 300; color: var(--accent2); }
+    [data-theme="dark"] .phead h1 em { color: var(--accent); }
+    .phead p { max-width: 64ch; margin: 20px 0 0; color: var(--ink-2); font-size: clamp(1rem, 2.2vw, 1.16rem); text-wrap: pretty; }
+    .phead p .lead { color: var(--ink); font-weight: 600; }
+
+    /* ===================== Doc layout ===================== */
+    .doc-wrap { max-width: 1180px; margin: 30px auto 0; padding: 0 22px; display: grid; grid-template-columns: 222px minmax(0,1fr); gap: 54px; align-items: start; }
+    .toc { position: sticky; top: 88px; align-self: start; }
+    .toc-label { font-size: 0.64rem; font-weight: 700; letter-spacing: 0.14em; text-transform: uppercase; color: var(--ink-3); padding: 0 12px 10px; }
+    .toc a { display: block; padding: 7px 12px; border-radius: 9px; color: var(--ink-2); text-decoration: none; font-size: 0.85rem;
+      border-left: 2px solid transparent; transition: color .15s, background .15s, border-color .15s; }
+    .toc a:hover { color: var(--ink); background: var(--chip-bg); }
+    .toc a.active { color: var(--accent-ink); border-left-color: var(--accent); background: var(--chip-bg); font-weight: 600; }
+    @media (max-width: 960px) { .doc-wrap { grid-template-columns: 1fr; gap: 0; } .toc { display: none; } }
+
+    .doc-main { min-width: 0; }
+    .doc-sec { scroll-margin-top: 84px; padding-bottom: 6px; margin-bottom: 30px; }
+    .doc-sec + .doc-sec { border-top: 1px solid var(--line); padding-top: 34px; }
+    .sec-eyebrow { font-size: 0.66rem; font-weight: 700; letter-spacing: 0.14em; text-transform: uppercase; color: var(--accent-ink); }
+    .doc-sec h2 { font-family: 'Newsreader', serif; font-weight: 400; font-size: clamp(1.7rem, 3.4vw, 2.25rem); margin-top: 8px; letter-spacing: -0.01em; }
+    .doc-sec h3 { font-size: 1.02rem; margin-top: 30px; color: var(--ink); }
+    .doc-sec > p { color: var(--ink-2); margin-top: 14px; max-width: 66ch; text-wrap: pretty; }
+    .doc-sec p code, .doc-sec li code, .inline { font-family: 'JetBrains Mono', monospace; font-size: 0.82em;
+      background: var(--chip-bg); border: 1px solid var(--line); border-radius: 6px; padding: 1px 6px; color: var(--accent-ink); }
+    .doc-list { margin: 14px 0 0; padding: 0; list-style: none; display: flex; flex-direction: column; gap: 10px; }
+    .doc-list li { color: var(--ink-2); padding-left: 22px; position: relative; max-width: 66ch; }
+    .doc-list li::before { content: ''; position: absolute; left: 5px; top: 10px; width: 5px; height: 5px; border-radius: 50%; background: var(--accent); }
+    .doc-list li b { color: var(--ink); font-weight: 600; }
+
+    /* code block */
+    .code { position: relative; margin-top: 18px; background: var(--cmd-bg); border: 1px solid var(--cmd-line); border-radius: 12px; overflow: hidden; }
+    .code pre { margin: 0; padding: 15px 16px; overflow-x: auto; }
+    .code code { font-family: 'JetBrains Mono', monospace; font-size: 0.795rem; line-height: 1.75; color: var(--ink); white-space: pre; display: block; }
+    .code .pr { color: var(--accent); } /* prompt $ */
+    .code .cm { color: var(--ink-3); }   /* comment */
+    .code .ot { color: var(--ink-3); }   /* output */
+    .code .hl { color: var(--accent-ink); }
+    .code-copy { position: absolute; top: 9px; right: 9px; border: 1px solid var(--line); background: var(--chip-bg); color: var(--ink-3);
+      font-size: 0.6rem; font-weight: 700; letter-spacing: 0.05em; text-transform: uppercase; cursor: pointer; font-family: inherit;
+      padding: 4px 8px; border-radius: 7px; transition: color .15s, border-color .15s; }
+    .code-copy:hover { color: var(--ink); border-color: var(--ink-3); }
+
+    /* command reference card */
+    .cmd { margin-top: 16px; border-radius: var(--radius-sm); border: 1px solid var(--glass-border); background: var(--glass-bg-fallback); box-shadow: var(--glass-shadow); padding: 17px 20px; }
+    @supports ((backdrop-filter: blur(1px))) { .cmd { background: var(--glass-bg); -webkit-backdrop-filter: blur(16px) saturate(1.4); backdrop-filter: blur(16px) saturate(1.4); } }
+    .cmd-name { font-family: 'JetBrains Mono', monospace; font-size: 0.9rem; font-weight: 600; color: var(--ink); word-break: break-word; }
+    .cmd-name .arg { color: var(--accent-ink); font-weight: 500; }
+    .cmd-purpose { color: var(--ink-2); font-size: 0.88rem; margin-top: 7px; max-width: 60ch; }
+    .flags { margin-top: 13px; border-top: 1px solid var(--line); }
+    .flag { display: grid; grid-template-columns: 200px 1fr; gap: 16px; padding: 9px 0; border-bottom: 1px solid var(--line); align-items: baseline; }
+    .flag:last-child { border-bottom: 0; }
+    .flag code { font-family: 'JetBrains Mono', monospace; font-size: 0.755rem; color: var(--accent-ink); }
+    .flag span { color: var(--ink-2); font-size: 0.84rem; }
+    @media (max-width: 560px) { .flag { grid-template-columns: 1fr; gap: 3px; } }
+
+    /* object model tree */
+    .concept { margin-top: 20px; border-radius: var(--radius-sm); border: 1px solid var(--glass-border); background: var(--cmd-bg); padding: 20px 22px; overflow-x: auto; }
+    .concept pre { font-family: 'JetBrains Mono', monospace; font-size: 0.78rem; line-height: 1.95; color: var(--ink-2); white-space: pre; margin: 0; }
+    .concept .n { color: var(--ink); font-weight: 600; }
+    .concept .k { color: var(--accent-ink); font-weight: 500; }
+    .concept .tree { color: var(--ink-3); }
+
+    /* provider kinds + exit codes grids */
+    .grid2 { margin-top: 18px; display: grid; grid-template-columns: repeat(auto-fit, minmax(228px,1fr)); gap: 12px; }
+    .kind { border-radius: 12px; border: 1px solid var(--line); background: var(--chip-bg); padding: 14px 16px; }
+    .kind h4 { font-family: 'JetBrains Mono', monospace; font-size: 0.8rem; color: var(--accent-ink); font-weight: 600; }
+    .kind p { font-size: 0.81rem; margin-top: 6px; color: var(--ink-2); }
+    .exit { display: flex; align-items: flex-start; gap: 13px; border-radius: 12px; border: 1px solid var(--line); background: var(--chip-bg); padding: 13px 15px; }
+    .exit .num { font-family: 'JetBrains Mono', monospace; font-weight: 700; font-size: 1.05rem; width: 30px; height: 30px; flex-shrink: 0; display: grid; place-items: center; border-radius: 8px; }
+    .exit.ok .num { color: #2faf6e; background: rgba(84,209,150,.16); }
+    .exit.fail .num { color: #db5b56; background: rgba(219,91,86,.16); }
+    .exit.warn .num { color: #d6982f; background: rgba(214,152,47,.16); }
+    .exit .x-label { font-weight: 700; color: var(--ink); font-size: 0.85rem; }
+    .exit .x-desc { color: var(--ink-2); font-size: 0.79rem; margin-top: 2px; }
+
+    /* callout */
+    .callout { margin-top: 18px; border-radius: 12px; border: 1px solid hsl(var(--accent-band) 50% 55% / .32); background: rgba(var(--accent-rgb), .06); padding: 14px 17px; display: flex; gap: 12px; }
+    .callout svg { width: 18px; height: 18px; color: var(--accent-ink); flex-shrink: 0; margin-top: 2px; }
+    .callout p { margin: 0; color: var(--ink-2); font-size: 0.85rem; max-width: 64ch; }
+    .callout b { color: var(--ink); }
+
+    /* footer (shared) */
+    .footer { border-top: 1px solid var(--line); margin: 64px auto 0; max-width: 1180px; padding: 32px 22px 56px;
+      font-size: 0.84rem; color: var(--ink-3); display: flex; justify-content: space-between; gap: 16px; flex-wrap: wrap; }
+    .footer a { color: var(--accent-ink); text-decoration: none; font-weight: 600; }
+    .footer a:hover { text-decoration: underline; }
+
+    @media (prefers-reduced-motion: reduce) {
+      * { animation-duration: 0.001ms !important; scroll-behavior: auto !important; }
+      .reveal { opacity: 1; transform: none; transition: none; }
+    }
+  </style>
+</head>
+<body>
+  <div class="ambient"><i class="a"></i><i class="b"></i></div>
+  <div class="grain"></div>
+
+  <!-- Nav (shared with the Hub) -->
+  <nav class="nav" id="nav">
+    <div class="nav-in">
+      <a class="nav-brand" href="index.html" aria-label="Back to CLI-Anything Hub home"><span class="nav-brand-badge" aria-hidden="true"><svg viewBox="0 0 48 48" fill="none"><path d="M8 16.5 18.5 24 8 31.5" stroke="currentColor" stroke-width="3.9" stroke-linecap="square" stroke-linejoin="miter" style="color: var(--accent);"/><path d="M24 29.2h16" stroke="currentColor" stroke-width="3.9" stroke-linecap="square" style="color: var(--ink);"/></svg></span>CLI-Hub</a>
+      <div class="nav-links">
+        <div class="nav-menu" id="navMenu">
+        <a class="nav-link" href="index.html">
+          <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.85" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M3 10.5 12 3l9 7.5"/><path d="M5 9.5V20a1 1 0 0 0 1 1h12a1 1 0 0 0 1-1V9.5"/><path d="M9.5 21v-6h5v6"/></svg>
+          Home
+        </a>
+        <a class="nav-link" href="index.html#matrices">
+          <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.85" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="3.5" y="3.5" width="7" height="7" rx="1.6"/><rect x="13.5" y="3.5" width="7" height="7" rx="1.6"/><rect x="3.5" y="13.5" width="7" height="7" rx="1.6"/><rect x="13.5" y="13.5" width="7" height="7" rx="1.6"/></svg>
+          Matrices
+        </a>
+        <a class="nav-link active keep" href="docs.html" aria-current="page">
+          <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.85" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M4 4.8A1.8 1.8 0 0 1 5.8 3H12v17H5.8A1.8 1.8 0 0 0 4 21.8z"/><path d="M20 4.8A1.8 1.8 0 0 0 18.2 3H12v17h6.2A1.8 1.8 0 0 1 20 21.8z"/></svg>
+          Docs
+        </a>
+        <a class="nav-link" href="https://reeceyang.sgp1.cdn.digitaloceanspaces.com/SKILL.md" target="_blank">
+          <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.85" stroke-linecap="round" stroke-linejoin="round"><path d="m5.5 18.5 9.8-9.8"/><path d="m13.7 6.9 3.4 3.4"/><path d="M18 4v2.4"/><path d="M16.8 5.2h2.4"/><path d="M7.5 4.8v2"/><path d="M6.5 5.8h2"/><path d="M18.2 15.8v2"/><path d="M17.2 16.8h2"/></svg>
+          SKILL
+        </a>
+        <a class="nav-link" href="https://github.com/HKUDS/CLI-Anything" target="_blank">
+          <svg viewBox="0 0 98 96" fill="currentColor" aria-hidden="true"><path fill-rule="evenodd" clip-rule="evenodd" d="M48.854 0C21.839 0 0 22 0 49.217c0 21.756 13.993 40.172 33.405 46.69 2.427.49 3.316-1.059 3.316-2.362 0-1.141-.08-5.052-.08-9.127-13.59 2.934-16.42-5.867-16.42-5.867-2.184-5.704-5.42-7.17-5.42-7.17-4.448-3.015.324-3.015.324-3.015 4.934.326 7.523 5.052 7.523 5.052 4.367 7.496 11.404 5.378 14.235 4.074.404-3.178 1.699-5.378 3.074-6.6C29.304 70.25 17.9 66.013 17.9 47.02c0-5.52 1.94-10.046 5.127-13.58-.486-1.302-2.264-6.437.486-13.34 0 0 4.206-1.302 13.59 5.216 3.963-1.14 8.17-1.628 12.34-1.628 4.17 0 8.376.568 12.34 1.628 9.384-6.518 13.59-5.216 13.59-5.216 2.75 6.903.972 12.038.486 13.34 3.268 3.534 5.127 8.06 5.127 13.58 0 19.074-11.485 23.15-22.328 24.29 1.78 1.548 3.316 4.481 3.316 9.126 0 6.6-.08 11.897-.08 13.526 0 1.304.89 2.853 3.316 2.364 19.412-6.52 33.405-24.935 33.405-46.691C97.707 22 75.788 0 48.854 0z"/></svg>
+          GitHub
+          <span class="nav-link-stars" data-github-stars aria-label="GitHub star count">--</span>
+        </a>
+        <a class="nav-link" href="https://github.com/HKUDS/CLI-Anything/blob/main/CONTRIBUTING.md" target="_blank">Contribute</a>
+        </div>
+        <button class="theme-toggle keep" onclick="toggleTheme()" aria-label="Toggle theme">
+          <svg class="icon-sun" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="5"/><line x1="12" y1="1" x2="12" y2="3"/><line x1="12" y1="21" x2="12" y2="23"/><line x1="4.22" y1="4.22" x2="5.64" y2="5.64"/><line x1="18.36" y1="18.36" x2="19.78" y2="19.78"/><line x1="1" y1="12" x2="3" y2="12"/><line x1="21" y1="12" x2="23" y2="12"/><line x1="4.22" y1="19.78" x2="5.64" y2="18.36"/><line x1="18.36" y1="5.64" x2="19.78" y2="4.22"/></svg>
+          <svg class="icon-moon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M21 12.79A9 9 0 1 1 11.21 3 7 7 0 0 0 21 12.79z"/></svg>
+        </button>
+        <button class="nav-toggle keep" id="navToggle" aria-label="Menu" aria-expanded="false" aria-controls="navMenu">
+          <svg class="icon-bars" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round"><line x1="3" y1="6" x2="21" y2="6"/><line x1="3" y1="12" x2="21" y2="12"/><line x1="3" y1="18" x2="21" y2="18"/></svg>
+          <svg class="icon-x" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M18 6 6 18M6 6l12 12"/></svg>
+        </button>
+      </div>
+    </div>
+    <div class="nav-scrim" id="navScrim"></div>
+  </nav>
+
+  <!-- Page header -->
+  <header class="phead">
+    <span class="klabel">Documentation</span>
+    <h1>Drive any app from the <em>command line</em></h1>
+    <p><span class="lead">CLI-Hub is a registry and installer for agent-native CLIs.</span> Install a tool by name, launch it, and — when a task spans several tools — pull in a capability-based <b>Workflow Matrix</b>. Every command is built for both humans and AI agents, with <code>--json</code> output and a documented exit-code contract.</p>
+  </header>
+
+  <div class="doc-wrap">
+    <!-- Table of contents -->
+    <aside class="toc" aria-label="On this page">
+      <div class="toc-label">On this page</div>
+      <nav id="toc-nav">
+        <a href="#install">Install</a>
+        <a href="#quickstart">Quick start</a>
+        <a href="#catalog">Catalog commands</a>
+        <a href="#matrices">Workflow matrices</a>
+        <a href="#matrix-cli">Matrix commands</a>
+        <a href="#exit">Exit codes</a>
+        <a href="#automation">JSON &amp; automation</a>
+        <a href="#config">Registries &amp; config</a>
+      </nav>
+    </aside>
+
+    <main class="doc-main">
+
+      <!-- ===================== Install ===================== -->
+      <section class="doc-sec reveal" id="install">
+        <span class="sec-eyebrow">Getting started</span>
+        <h2>Install</h2>
+        <p>CLI-Hub ships as the <code>cli-anything-hub</code> package and installs the <code>cli-hub</code> command. It needs Python 3.10 or newer.</p>
+        <div class="code"><button class="code-copy" onclick="copyCode(this)">Copy</button><pre><code><span class="pr">$</span> pip install cli-anything-hub
+<span class="pr">$</span> cli-hub --version</code></pre></div>
+        <p>That single command is the entry point for everything below — browsing the catalog, installing tools, and working with matrices. From here you can also hand an agent the <a href="https://reeceyang.sgp1.cdn.digitaloceanspaces.com/SKILL.md" target="_blank" rel="noopener">meta-skill <code>SKILL.md</code></a> so it can discover and install CLIs autonomously.</p>
+      </section>
+
+      <!-- ===================== Quick start ===================== -->
+      <section class="doc-sec reveal" id="quickstart">
+        <span class="sec-eyebrow">Two-minute tour</span>
+        <h2>Quick start</h2>
+        <p>Find a tool, install it, and run it — or scope a whole workflow to just what your task needs.</p>
+        <div class="code"><button class="code-copy" onclick="copyCode(this)">Copy</button><pre><code><span class="cm"># Browse and install a single CLI</span>
+<span class="pr">$</span> cli-hub search diagram
+<span class="pr">$</span> cli-hub install drawio
+<span class="pr">$</span> cli-hub launch drawio --help
+
+<span class="cm"># Ask what's needed for a task across every matrix</span>
+<span class="pr">$</span> cli-hub can <span class="hl">"transcribe audio"</span>
+
+<span class="cm"># Check a matrix, then install only the capability you need</span>
+<span class="pr">$</span> cli-hub matrix preflight video-creation --summary
+<span class="pr">$</span> cli-hub matrix install video-creation --capability text.transcribe</code></pre></div>
+        <div class="callout">
+          <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="9"/><path d="M12 16v-4"/><path d="M12 8h.01"/></svg>
+          <p><b>Tip.</b> Add <code>--json</code> to almost any command for machine-readable output, and chain on exit codes (see <a href="#exit">Exit codes</a>) to make scripts and agents react without parsing text.</p>
+        </div>
+      </section>
+
+      <!-- ===================== Catalog commands ===================== -->
+      <section class="doc-sec reveal" id="catalog">
+        <span class="sec-eyebrow">The catalog</span>
+        <h2>Catalog commands</h2>
+        <p>The catalog is the flat list of individual CLIs — first-party <em>harness</em> tools published by CLI-Anything and curated <em>public</em> tools. These commands discover, install, and run them.</p>
+
+        <div class="cmd">
+          <div class="cmd-name">cli-hub list</div>
+          <div class="cmd-purpose">List every available CLI, grouped by category, with an installed marker.</div>
+          <div class="flags">
+            <div class="flag"><code>-c, --category &lt;name&gt;</code><span>Filter to one category.</span></div>
+            <div class="flag"><code>-s, --source &lt;harness|public|npm|all&gt;</code><span>Filter by source (<code>npm</code> is an alias for public).</span></div>
+            <div class="flag"><code>--json</code><span>Machine-readable output.</span></div>
+          </div>
+        </div>
+
+        <div class="cmd">
+          <div class="cmd-name">cli-hub search <span class="arg">&lt;query&gt;</span></div>
+          <div class="cmd-purpose">Search CLIs by name, description, or category.</div>
+          <div class="flags">
+            <div class="flag"><code>--json</code><span>Machine-readable output.</span></div>
+          </div>
+        </div>
+
+        <div class="cmd">
+          <div class="cmd-name">cli-hub info <span class="arg">&lt;name&gt;</span></div>
+          <div class="cmd-purpose">Show full detail for one CLI — description, category, source, version, requirements, entry point, homepage, and contributors.</div>
+        </div>
+
+        <div class="cmd">
+          <div class="cmd-name">cli-hub install <span class="arg">&lt;name&gt;</span></div>
+          <div class="cmd-purpose">Install a CLI from the registry. Harness tools install via <code>pip</code>; public tools use their declared strategy (npm / uv / command).</div>
+        </div>
+
+        <div class="cmd">
+          <div class="cmd-name">cli-hub launch <span class="arg">&lt;name&gt; [args…]</span></div>
+          <div class="cmd-purpose">Launch an installed CLI, passing every argument after the name straight through to it.</div>
+        </div>
+
+        <div class="cmd">
+          <div class="cmd-name">cli-hub update <span class="arg">&lt;name&gt;</span> &nbsp;·&nbsp; cli-hub uninstall <span class="arg">&lt;name&gt;</span></div>
+          <div class="cmd-purpose">Update an installed CLI to the latest version, or remove it.</div>
+        </div>
+
+        <div class="cmd">
+          <div class="cmd-name">cli-hub previews <span class="arg">&lt;inspect|html|watch|open&gt;</span></div>
+          <div class="cmd-purpose">Inspect, render, watch, or open preview bundles and live sessions produced by harness CLIs (e.g. FreeCAD / Blender preview loops). <code>watch</code> and <code>open</code> serve a live, auto-refreshing page.</div>
+        </div>
+      </section>
+
+      <!-- ===================== Workflow matrices ===================== -->
+      <section class="doc-sec reveal" id="matrices">
+        <span class="sec-eyebrow">Concepts</span>
+        <h2>Workflow matrices</h2>
+        <p>A real task — &ldquo;make a captioned video&rdquo; — rarely maps to one tool. A <b>matrix</b> bundles a domain into <b>capabilities</b> (the verbs an agent calls) and, for each, several <b>providers</b> (concrete ways to fulfil it). You pick a path by <em>capability</em>, not by memorising which of fourteen packages to install.</p>
+
+        <div class="concept"><pre><span class="n">Matrix</span>  <span class="tree">──</span> a capability bundle for one domain (e.g. video-creation)
+<span class="tree">│</span>
+<span class="tree">├─</span> <span class="n">capabilities[]</span>   verbs an agent can call — <span class="k">visual.generate</span>, <span class="k">text.transcribe</span> …
+<span class="tree">│   └─</span> <span class="n">providers[]</span>   concrete ways to fulfil a capability, each tagged with a <span class="n">kind</span>
+<span class="tree">│</span>
+<span class="tree">├─</span> <span class="n">recipes[]</span>        named subsets of capabilities for a specific task
+<span class="tree">├─</span> <span class="n">clis[]</span>           the flat list that <span class="k">matrix install</span> actually installs
+<span class="tree">└─</span> <span class="n">SKILL.md</span>         the provider-selection handbook, rendered locally on install</pre></div>
+
+        <h3>Provider kinds</h3>
+        <p>Every provider declares a <code>kind</code> that tells you how it&rsquo;s obtained and what it costs:</p>
+        <div class="grid2">
+          <div class="kind"><h4>harness-cli</h4><p>A first-party CLI you can install with <code>cli-hub</code>; each ships its own SKILL.md.</p></div>
+          <div class="kind"><h4>public-cli</h4><p>A third-party CLI installed via brew / npm / pip.</p></div>
+          <div class="kind"><h4>python</h4><p>A Python library used directly (a free fallback).</p></div>
+          <div class="kind"><h4>native</h4><p>A native binary on the system, such as <code>ffmpeg</code>.</p></div>
+          <div class="kind"><h4>api</h4><p>A cloud API — needs a key and explicit user consent.</p></div>
+          <div class="kind"><h4>agent-skill</h4><p>An external agent skill the agent installs itself; not counted by preflight.</p></div>
+        </div>
+
+        <div class="callout">
+          <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="9"/><path d="M12 16v-4"/><path d="M12 8h.01"/></svg>
+          <p><b>Preflight reports, it doesn&rsquo;t choose.</b> Registry order is documentation order, not a ranking. <code>preflight</code> tells you what&rsquo;s available; the agent picks the provider using the rules in the matrix&rsquo;s <code>SKILL.md</code>. Paid APIs are never used without configured keys and user consent.</p>
+        </div>
+      </section>
+
+      <!-- ===================== Matrix commands ===================== -->
+      <section class="doc-sec reveal" id="matrix-cli">
+        <span class="sec-eyebrow">The matrix command family</span>
+        <h2>Matrix commands</h2>
+        <p>All matrix operations live under <code>cli-hub matrix</code>, plus the top-level <code>cli-hub can</code> shortcut for capability search. Every subcommand supports <code>--json</code>.</p>
+
+        <h3>Discover</h3>
+        <div class="cmd">
+          <div class="cmd-name">cli-hub can <span class="arg">&lt;query&gt;</span></div>
+          <div class="cmd-purpose">Search capabilities across <em>all</em> matrices for a task, with per-provider availability on this machine. Exit 0 if there are hits, 1 if none.</div>
+          <div class="flags">
+            <div class="flag"><code>--json</code><span>Emit capability matches as JSON.</span></div>
+          </div>
+        </div>
+        <div class="code"><button class="code-copy" onclick="copyCode(this)">Copy</button><pre><code><span class="pr">$</span> cli-hub can <span class="hl">"download bilibili video"</span>
+<span class="ot">  video.download  (video-creation)</span>
+<span class="ot">    available here: yt-dlp · missing: BBDown, lux</span>
+<span class="ot">    next: cli-hub matrix preflight video-creation -c video.download</span></code></pre></div>
+
+        <div class="cmd">
+          <div class="cmd-name">cli-hub matrix list</div>
+          <div class="cmd-purpose">List all matrices with their description and how many member CLIs are installed.</div>
+          <div class="flags"><div class="flag"><code>--json</code><span>Machine-readable output.</span></div></div>
+        </div>
+
+        <div class="cmd">
+          <div class="cmd-name">cli-hub matrix search <span class="arg">&lt;query&gt;</span></div>
+          <div class="cmd-purpose">Search matrices by name, capability, provider, recipe, or gap — with match attribution (which capability matched, and on which field).</div>
+          <div class="flags"><div class="flag"><code>--json</code><span>Includes <code>matched_capabilities[]</code>.</span></div></div>
+        </div>
+
+        <div class="cmd">
+          <div class="cmd-name">cli-hub matrix info <span class="arg">&lt;name&gt;</span></div>
+          <div class="cmd-purpose">Full detail for one matrix — members and status, capabilities with provider counts, recipes, and known gaps.</div>
+          <div class="flags"><div class="flag"><code>--json</code><span>Machine-readable output.</span></div></div>
+        </div>
+
+        <div class="cmd">
+          <div class="cmd-name">cli-hub matrix recipes</div>
+          <div class="cmd-purpose">List task-oriented recipes across every matrix, each with its capabilities and a ready-to-run preflight command.</div>
+          <div class="flags">
+            <div class="flag"><code>--search &lt;text&gt;</code><span>Filter by id, description, or capability.</span></div>
+            <div class="flag"><code>--json</code><span>Machine-readable output.</span></div>
+          </div>
+        </div>
+
+        <h3>Preflight</h3>
+        <p>Preflight is the pivot of the whole flow: it reports which providers are actually usable in your current environment, so you (or an agent) decide what to install before touching anything.</p>
+        <div class="cmd">
+          <div class="cmd-name">cli-hub matrix preflight <span class="arg">&lt;name&gt;</span></div>
+          <div class="cmd-purpose">Check provider availability per capability. Exits <code>0</code> when every (filtered) capability has at least one usable provider, <code>3</code> when there&rsquo;s a gap.</div>
+          <div class="flags">
+            <div class="flag"><code>-c, --capability &lt;id&gt;</code><span>Check just one capability.</span></div>
+            <div class="flag"><code>--recipe &lt;id&gt;</code><span>Check only the capabilities a recipe uses.</span></div>
+            <div class="flag"><code>--offline</code><span>Consider only offline-capable providers.</span></div>
+            <div class="flag"><code>--fix-hints</code><span>Print an install command under each missing provider.</span></div>
+            <div class="flag"><code>--summary</code><span>Print only the two-line summary.</span></div>
+            <div class="flag"><code>--json</code><span>Machine-readable output.</span></div>
+          </div>
+        </div>
+        <div class="code"><button class="code-copy" onclick="copyCode(this)">Copy</button><pre><code><span class="cm"># Gate an action on coverage — only proceed if the recipe is fully satisfiable</span>
+<span class="pr">$</span> cli-hub matrix preflight video-creation --recipe screencast-tutorial --json \
+    || echo <span class="hl">"capability gap — read the missing list before installing"</span></code></pre></div>
+
+        <h3>Install</h3>
+        <div class="cmd">
+          <div class="cmd-name">cli-hub matrix install <span class="arg">&lt;name&gt;</span></div>
+          <div class="cmd-purpose">Install a matrix&rsquo;s CLIs. With no scope flag it installs every member CLI; the scope flags below install just a subset. Installation is idempotent — already-installed tools are skipped.</div>
+          <div class="flags">
+            <div class="flag"><code>--dry-run</code><span>Show the install plan with zero side effects.</span></div>
+            <div class="flag"><code>-c, --capability &lt;id&gt;</code><span>Install only the CLIs behind one capability.</span></div>
+            <div class="flag"><code>--recipe &lt;id&gt;</code><span>Install only the CLIs a recipe uses.</span></div>
+            <div class="flag"><code>--only &lt;a,b,c&gt;</code><span>Install a named comma-separated subset of the matrix&rsquo;s CLIs.</span></div>
+            <div class="flag"><code>--resume</code><span>Retry only the CLIs that failed last time.</span></div>
+            <div class="flag"><code>--skill-only</code><span>Render the matrix skill (SKILL.md + references + scripts) without installing CLIs.</span></div>
+            <div class="flag"><code>--json</code><span>Machine-readable plan or result.</span></div>
+          </div>
+        </div>
+        <div class="code"><button class="code-copy" onclick="copyCode(this)">Copy</button><pre><code><span class="pr">$</span> cli-hub matrix install video-creation --dry-run
+<span class="ot">  Plan: video-creation</span>
+<span class="ot">  skip (already installed): audacity, gimp, kdenlive</span>
+<span class="ot">  install via pip:          inkscape, krita, obs-studio, …</span>
+<span class="ot">  not managed here:         python libs, native binaries, cloud APIs — see preflight</span></code></pre></div>
+        <p>The scope flags (<code>--capability</code>, <code>--recipe</code>, <code>--only</code>) are mutually exclusive. Per-matrix install state is recorded under <code>~/.cli-hub/matrix_state.json</code>, which is what powers <code>--resume</code>.</p>
+
+        <h3>Repair</h3>
+        <div class="cmd">
+          <div class="cmd-name">cli-hub matrix doctor <span class="arg">&lt;name&gt;</span></div>
+          <div class="cmd-purpose">Audit install completeness for a matrix&rsquo;s CLIs — flags anything recorded as installed but missing from <code>PATH</code>, and suggests a fix. (Preflight asks &ldquo;is a provider usable?&rdquo;; doctor asks &ldquo;is what I installed still healthy?&rdquo;)</div>
+          <div class="flags"><div class="flag"><code>--json</code><span>Machine-readable audit.</span></div></div>
+        </div>
+      </section>
+
+      <!-- ===================== Exit codes ===================== -->
+      <section class="doc-sec reveal" id="exit">
+        <span class="sec-eyebrow">Contract</span>
+        <h2>Exit codes</h2>
+        <p>The matrix command family follows one exit-code contract, so scripts and agents can branch without reading text. Catalog commands use the simpler <code>0</code> / <code>1</code> success-or-failure convention.</p>
+        <div class="grid2">
+          <div class="exit ok"><span class="num">0</span><div><div class="x-label">Success</div><div class="x-desc">All checks passed, or every capability gap is covered.</div></div></div>
+          <div class="exit fail"><span class="num">1</span><div><div class="x-label">Failure</div><div class="x-desc">Matrix or capability not found; nothing could be installed.</div></div></div>
+          <div class="exit warn"><span class="num">2</span><div><div class="x-label">Usage error</div><div class="x-desc">Mutually exclusive flags, or an invalid capability / recipe / <code>--only</code> name.</div></div></div>
+          <div class="exit warn"><span class="num">3</span><div><div class="x-label">Partial</div><div class="x-desc">A capability gap, or some CLIs installed while others failed or are broken.</div></div></div>
+        </div>
+      </section>
+
+      <!-- ===================== Automation ===================== -->
+      <section class="doc-sec reveal" id="automation">
+        <span class="sec-eyebrow">For agents &amp; scripts</span>
+        <h2>JSON &amp; automation</h2>
+        <p>CLI-Hub is built to be driven by AI agents as much as by people. Two design choices make that reliable:</p>
+        <ul class="doc-list">
+          <li><b>Structured output everywhere.</b> Catalog commands and the whole matrix family accept <code>--json</code> — including <code>matrix install</code>, whose JSON carries the full plan or result. No screen-scraping required.</li>
+          <li><b>Exit codes as control flow.</b> Combine the contract above with <code>&amp;&amp;</code> / <code>||</code> to gate steps — e.g. preflight a recipe, and only install when it returns <code>0</code>.</li>
+        </ul>
+        <p>After installing a matrix, its <code>SKILL.md</code> is rendered to your machine. Read it: it contains the provider-selection rules, the suggest-to-user template for paid upgrades, and references — the judgement an agent needs that the registry alone doesn&rsquo;t encode.</p>
+        <div class="callout">
+          <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M4 17v2a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2v-2"/><path d="m7 11 5 5 5-5"/><path d="M12 4v12"/></svg>
+          <p>The meta-skill <code>SKILL.md</code> includes a <b>Workflow Matrices</b> section, and the site publishes <code>llms.txt</code> plus the machine-readable registries — give an agent those entry points and it can go from cold start to &ldquo;preflight → install by capability → JSON result&rdquo; on its own.</p>
+        </div>
+      </section>
+
+      <!-- ===================== Config ===================== -->
+      <section class="doc-sec reveal" id="config">
+        <span class="sec-eyebrow">Reference</span>
+        <h2>Registries &amp; config</h2>
+        <p>CLI-Hub reads three published registries and caches them locally (one-hour TTL) under <code>~/.cli-hub/</code>:</p>
+        <ul class="doc-list">
+          <li><b>registry.json</b> — first-party harness CLIs.</li>
+          <li><b>public_registry.json</b> — curated public CLIs.</li>
+          <li><b>matrix_registry.json</b> — matrices: capabilities × providers, with preflight contracts.</li>
+        </ul>
+        <p>They&rsquo;re served from the project&rsquo;s GitHub Pages domain (for example <code>…/CLI-Anything/matrix_registry.json</code>). Local state lives alongside the cache: <code>installed.json</code> tracks installed CLIs, and <code>matrix_state.json</code> records per-matrix install outcomes for <code>--resume</code>.</p>
+        <h3>Environment</h3>
+        <ul class="doc-list">
+          <li><b><code>CLI_HUB_NO_ANALYTICS=1</code></b> — opt out of anonymous, fire-and-forget usage analytics.</li>
+          <li>CLI-Hub auto-detects when it&rsquo;s invoked by an AI agent (Claude Code, Codex, Cursor, and others) for analytics bucketing only.</li>
+          <li>Color is suppressed automatically when output is piped or not a TTY, keeping logs and parsers clean.</li>
+        </ul>
+        <div class="callout">
+          <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M12 2 4 6v6c0 5 3.5 8 8 10 4.5-2 8-5 8-10V6z"/></svg>
+          <p>Analytics never block your workflow and can be turned off entirely. Matrices are the differentiator here — start from <a href="index.html#matrices">the Matrices section</a> or run <code>cli-hub matrix list</code> to see what&rsquo;s available.</p>
+        </div>
+      </section>
+
+    </main>
+  </div>
+
+  <footer class="footer">
+    <span>CLI-Anything Hub — agent-friendly CLI registry.</span>
+    <span><a href="index.html">Home</a> · <a href="index.html#matrices">Matrices</a> · <a href="demos.html">Demos</a> · <a href="https://github.com/HKUDS/CLI-Anything" target="_blank">GitHub</a></span>
+  </footer>
+
+  <script>
+    // ===================== Palette + theme (shared with the Hub) =====================
+    const PALETTES = {
+      steel: { label:'Steel', accentBand:209,
+        light:{ bg:'#f4f6f9', surface:'#ffffff', ink:'#14181f', ink2:'#4a5568', ink3:'#8595a8', line:'rgba(20,40,80,.10)', accent:'#2f6fb0', accent2:'#1f5793', accentRgb:'47,111,176', surfaceRgb:'255,255,255' },
+        dark:{ bg:'#0d1117', surface:'#151b24', ink:'#e8edf4', ink2:'#9fb0c4', ink3:'#647488', line:'rgba(255,255,255,.08)', accent:'#5b9bd6', accent2:'#7db4e6', accentRgb:'91,155,214', surfaceRgb:'21,27,36' } },
+      steelsky: { label:'Steel Sky', accentBand:203,
+        light:{ bg:'#f4f6f9', surface:'#ffffff', ink:'#14181f', ink2:'#4a5568', ink3:'#8595a8', line:'rgba(20,40,80,.10)', accent:'#1c8ee0', accent2:'#1573bd', accentRgb:'28,142,224', surfaceRgb:'255,255,255' },
+        dark:{ bg:'#0d1117', surface:'#151b24', ink:'#e8edf4', ink2:'#9fb0c4', ink3:'#647488', line:'rgba(255,255,255,.08)', accent:'#46b2f4', accent2:'#6cc6f8', accentRgb:'70,178,244', surfaceRgb:'21,27,36' } },
+      sky: { label:'Sky', accentBand:203,
+        light:{ bg:'#f4f9fe', surface:'#ffffff', ink:'#0f1f2d', ink2:'#465a6b', ink3:'#8299ac', line:'rgba(20,70,115,.10)', accent:'#1c8ee0', accent2:'#1573bd', accentRgb:'28,142,224', surfaceRgb:'255,255,255' },
+        dark:{ bg:'#0a1320', surface:'#121e2d', ink:'#e9f3fb', ink2:'#9bb4c9', ink3:'#5f7689', line:'rgba(255,255,255,.08)', accent:'#46b2f4', accent2:'#6cc6f8', accentRgb:'70,178,244', surfaceRgb:'18,30,45' } },
+      sage: { label:'Sage', accentBand:160,
+        light:{ bg:'#f3f8f4', surface:'#ffffff', ink:'#13211b', ink2:'#475a51', ink3:'#7f968a', line:'rgba(20,65,48,.10)', accent:'#2c9b78', accent2:'#1d8062', accentRgb:'44,155,120', surfaceRgb:'255,255,255' },
+        dark:{ bg:'#0b1410', surface:'#121d18', ink:'#e7f2eb', ink2:'#9ab4a7', ink3:'#5e7568', line:'rgba(255,255,255,.07)', accent:'#48c29c', accent2:'#67d0b1', accentRgb:'72,194,156', surfaceRgb:'18,29,24' } },
+      sand: { label:'Sand', accentBand:175,
+        light:{ bg:'#f8f5ef', surface:'#fffdf8', ink:'#221d15', ink2:'#585044', ink3:'#948979', line:'rgba(75,58,30,.12)', accent:'#1d7a71', accent2:'#145d57', accentRgb:'29,122,113', surfaceRgb:'255,253,248' },
+        dark:{ bg:'#13110b', surface:'#1b1811', ink:'#f1ece1', ink2:'#b2a797', ink3:'#796e5e', line:'rgba(255,255,255,.07)', accent:'#3eb2a4', accent2:'#5cc3b6', accentRgb:'62,178,164', surfaceRgb:'27,24,17' } },
+      blush: { label:'Blush', accentBand:3,
+        light:{ bg:'#faf6f4', surface:'#fffefd', ink:'#271d1c', ink2:'#5e504e', ink3:'#9b8a87', line:'rgba(90,50,45,.11)', accent:'#c25e5a', accent2:'#a4453f', accentRgb:'194,94,90', surfaceRgb:'255,254,253' },
+        dark:{ bg:'#140f0e', surface:'#1c1615', ink:'#f3eae8', ink2:'#b6a4a1', ink3:'#7d6b68', line:'rgba(255,255,255,.07)', accent:'#df8480', accent2:'#e89f9b', accentRgb:'223,132,128', surfaceRgb:'28,22,21' } },
+      mist: { label:'Mist', accentBand:222,
+        light:{ bg:'#f6f8fb', surface:'#ffffff', ink:'#171b22', ink2:'#4e586a', ink3:'#8893a6', line:'rgba(25,35,60,.09)', accent:'#3b6ef0', accent2:'#2f57cf', accentRgb:'59,110,240', surfaceRgb:'255,255,255' },
+        dark:{ bg:'#0a0d14', surface:'#12161f', ink:'#eef1f7', ink2:'#9aa6bd', ink3:'#606b82', line:'rgba(255,255,255,.07)', accent:'#5b8bff', accent2:'#789fff', accentRgb:'91,139,255', surfaceRgb:'18,22,31' } },
+    };
+    const DEFAULT_PALETTE = 'steelsky';
+    function getPalette() { const s = localStorage.getItem('palette'); return (s && PALETTES[s]) ? s : DEFAULT_PALETTE; }
+    function applyPalette(name) {
+      const p = PALETTES[name] || PALETTES[DEFAULT_PALETTE];
+      const theme = document.documentElement.getAttribute('data-theme') || 'dark';
+      const t = (theme === 'light') ? p.light : p.dark;
+      const r = document.documentElement.style;
+      r.setProperty('--bg', t.bg); r.setProperty('--surface', t.surface);
+      r.setProperty('--ink', t.ink); r.setProperty('--ink-2', t.ink2); r.setProperty('--ink-3', t.ink3);
+      r.setProperty('--line', t.line); r.setProperty('--accent', t.accent); r.setProperty('--accent2', t.accent2);
+      r.setProperty('--accent-rgb', t.accentRgb); r.setProperty('--surface-rgb', t.surfaceRgb);
+      r.setProperty('--accent-band', String(p.accentBand));
+      document.documentElement.setAttribute('data-palette', name);
+    }
+    function getPreferredTheme() { const s = localStorage.getItem('theme'); if (s) return s; return window.matchMedia('(prefers-color-scheme: light)').matches ? 'light' : 'dark'; }
+    function applyTheme(t) { document.documentElement.setAttribute('data-theme', t); applyPalette(getPalette()); }
+    function toggleTheme() { const cur = document.documentElement.getAttribute('data-theme') || 'dark'; const next = cur === 'dark' ? 'light' : 'dark'; applyTheme(next); localStorage.setItem('theme', next); }
+    applyTheme(getPreferredTheme());
+    window.matchMedia('(prefers-color-scheme: light)').addEventListener('change', (e) => { if (!localStorage.getItem('theme')) applyTheme(e.matches ? 'light' : 'dark'); });
+
+    // nav scrolled
+    (function () { const nav = document.getElementById('nav'); const on = () => nav.classList.toggle('scrolled', window.scrollY > 8);
+      window.addEventListener('scroll', on, { passive: true }); on(); })();
+
+    // mobile nav drawer
+    (function () {
+      const toggle = document.getElementById('navToggle');
+      const menu = document.getElementById('navMenu');
+      const scrim = document.getElementById('navScrim');
+      if (!toggle || !menu) return;
+      function setOpen(open) {
+        menu.classList.toggle('open', open);
+        toggle.classList.toggle('open', open);
+        if (scrim) scrim.classList.toggle('open', open);
+        toggle.setAttribute('aria-expanded', String(open));
+        document.body.style.overflow = open ? 'hidden' : '';
+      }
+      toggle.addEventListener('click', () => setOpen(!menu.classList.contains('open')));
+      if (scrim) scrim.addEventListener('click', () => setOpen(false));
+      menu.addEventListener('click', (e) => { if (e.target.closest('a')) setOpen(false); });
+      document.addEventListener('keydown', (e) => { if (e.key === 'Escape') setOpen(false); });
+      window.addEventListener('resize', () => { if (window.innerWidth > 860) setOpen(false); });
+    })();
+
+    // GitHub stars — shields.io badge first (CORS-friendly, no rate limit), API fallback. Matches the Hub.
+    const GITHUB_REPO_API = 'https://api.github.com/repos/HKUDS/CLI-Anything';
+    const GITHUB_STARS_BADGE_API = 'https://img.shields.io/github/stars/HKUDS/CLI-Anything.json';
+    function renderGitHubStars(label, title) {
+      document.querySelectorAll('[data-github-stars]').forEach(el => { el.textContent = label; el.setAttribute('aria-label', title); el.title = title; });
+    }
+    function formatCompactCount(value) {
+      return new Intl.NumberFormat('en', { notation: 'compact', maximumFractionDigits: value >= 10000 ? 0 : 1 }).format(value);
+    }
+    function formatBadgeCount(value) {
+      if (typeof value !== 'string') return null;
+      const label = value.trim();
+      return label ? label.toUpperCase() : null;
+    }
+    (async function loadGitHubStars() {
+      try {
+        try {
+          const badgeResp = await fetch(GITHUB_STARS_BADGE_API);
+          if (badgeResp.ok) {
+            const badge = await badgeResp.json();
+            const badgeLabel = formatBadgeCount(badge.message || badge.value);
+            if (badgeLabel) { renderGitHubStars(badgeLabel, `${badgeLabel} GitHub stars`); return; }
+          }
+        } catch (_) {}
+        const resp = await fetch(GITHUB_REPO_API, { headers: { 'Accept': 'application/vnd.github+json' } });
+        if (!resp.ok) return;
+        const repo = await resp.json();
+        const stars = repo.stargazers_count;
+        if (typeof stars !== 'number') return;
+        renderGitHubStars(formatCompactCount(stars), `${stars.toLocaleString('en-US')} GitHub stars`);
+      } catch (_) {}
+    })();
+
+    // ===================== Doc behaviour =====================
+    // copy code blocks
+    function copyCode(btn) {
+      const code = btn.parentElement.querySelector('code');
+      if (!code || !navigator.clipboard) return;
+      navigator.clipboard.writeText(code.innerText).then(() => {
+        const o = btn.textContent; btn.textContent = 'Copied';
+        setTimeout(() => { btn.textContent = o; }, 1200);
+      }).catch(() => {});
+    }
+
+    // reveal on scroll
+    (function () {
+      const io = new IntersectionObserver((es) => es.forEach(e => { if (e.isIntersecting) { e.target.classList.add('in'); io.unobserve(e.target); } }), { rootMargin: '0px 0px -8% 0px' });
+      document.querySelectorAll('.reveal').forEach(el => io.observe(el));
+    })();
+
+    // scrollspy — highlight the active TOC link
+    (function () {
+      const links = Array.from(document.querySelectorAll('#toc-nav a'));
+      const map = new Map(links.map(a => [a.getAttribute('href').slice(1), a]));
+      const sections = links.map(a => document.getElementById(a.getAttribute('href').slice(1))).filter(Boolean);
+      let active = null;
+      const setActive = (id) => { if (id === active) return; active = id; links.forEach(a => a.classList.toggle('active', a === map.get(id))); };
+      const spy = new IntersectionObserver((entries) => {
+        const visible = entries.filter(e => e.isIntersecting).sort((a, b) => a.boundingClientRect.top - b.boundingClientRect.top);
+        if (visible.length) setActive(visible[0].target.id);
+      }, { rootMargin: '-72px 0px -64% 0px', threshold: 0 });
+      sections.forEach(s => spy.observe(s));
+    })();
+  </script>
+</body>
+</html>
diff --git a/docs/hub/index.html b/docs/hub/index.html
index e38ecf1de..b7e71c45f 100644
--- a/docs/hub/index.html
+++ b/docs/hub/index.html
@@ -1,21 +1,17 @@
 <!DOCTYPE html>
-<html lang="en">
+<html lang="en" data-theme="dark">
 <head>
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <meta name="robots" content="index,follow,max-snippet:-1,max-image-preview:large,max-video-preview:-1">
   <title>CLI-Anything Hub - Agent-Friendly CLI Registry</title>
   <meta name="description" content="CLI-Anything Hub is an agent-friendly registry and package manager for CLI tools that let AI agents discover, install, and operate GUI applications, developer tools, creative software, web APIs, and public SaaS platforms.">
   <meta name="author" content="HKUDS and Yuhao Yang">
   <meta name="copyright" content="Copyright: HKUDS. Lead author: Yuhao Yang (yuhao.page).">
-  <meta name="robots" content="index,follow,max-snippet:-1,max-image-preview:large,max-video-preview:-1">
   <link rel="canonical" href="https://clianything.cc/">
   <link rel="alternate" type="text/markdown" href="https://clianything.cc/index.md" title="CLI-Anything Hub Markdown">
   <link rel="alternate" type="text/plain" href="https://clianything.cc/llms.txt" title="CLI-Anything LLM Context">
   <link rel="alternate" type="text/plain" href="https://clianything.cc/llms-full.txt" title="CLI-Anything Full LLM Context">
-  <link rel="sitemap" type="application/xml" href="https://clianything.cc/sitemap.xml">
-  <link rel="service-desc" type="application/openapi+json" href="https://clianything.cc/openapi.json">
-  <link rel="agent" type="application/json" href="https://clianything.cc/.well-known/agent.json">
-  <link rel="agent-card" type="application/json" href="https://clianything.cc/.well-known/agent-card.json">
   <meta property="og:type" content="website">
   <meta property="og:site_name" content="CLI-Anything Hub">
   <meta property="og:title" content="CLI-Anything Hub - Agent-Friendly CLI Registry">
@@ -26,1881 +22,935 @@
   <meta name="twitter:description" content="Agent-friendly CLI registry and package manager for discovering, installing, and launching command-line tools.">
   <link rel="preconnect" href="https://fonts.googleapis.com">
   <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
-  <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500&display=swap" rel="stylesheet">
-  <script type="application/ld+json">
-  {
-    "@context": "https://schema.org",
-    "@graph": [
-      {
-        "@type": "Organization",
-        "@id": "https://clianything.cc/#organization",
-        "name": "HKUDS",
-        "url": "https://github.com/HKUDS",
-        "sameAs": [
-          "https://github.com/HKUDS/CLI-Anything",
-          "https://yuhao.page"
-        ]
-      },
-      {
-        "@type": "Person",
-        "@id": "https://yuhao.page/#person",
-        "name": "Yuhao Yang",
-        "url": "https://yuhao.page"
-      },
-      {
-        "@type": "SoftwareApplication",
-        "@id": "https://clianything.cc/#software",
-        "name": "CLI-Anything Hub",
-        "alternateName": [
-          "CLI-Hub",
-          "cli-hub",
-          "cli-anything-hub"
-        ],
-        "description": "Agent-friendly registry and package manager for CLI tools that let AI agents discover, install, and operate GUI applications, developer tools, creative software, web APIs, and public SaaS platforms.",
-        "url": "https://clianything.cc/",
-        "applicationCategory": "DeveloperApplication",
-        "operatingSystem": "Linux, macOS, Windows",
-        "softwareVersion": "0.3.0",
-        "programmingLanguage": "Python",
-        "downloadUrl": "https://pypi.org/project/cli-anything-hub/",
-        "codeRepository": "https://github.com/HKUDS/CLI-Anything",
-        "license": "https://github.com/HKUDS/CLI-Anything/blob/main/LICENSE",
-        "isAccessibleForFree": true,
-        "offers": {
-          "@type": "Offer",
-          "price": "0",
-          "priceCurrency": "USD",
-          "url": "https://clianything.cc/pricing.md"
-        },
-        "creator": {
-          "@id": "https://yuhao.page/#person"
-        },
-        "publisher": {
-          "@id": "https://clianything.cc/#organization"
-        },
-        "copyrightHolder": {
-          "@id": "https://clianything.cc/#organization"
-        },
-        "copyrightNotice": "Copyright: HKUDS. Lead author: Yuhao Yang (yuhao.page).",
-        "sameAs": [
-          "https://github.com/HKUDS/CLI-Anything",
-          "https://pypi.org/project/cli-anything-hub/",
-          "https://clawhub.ai/yuh-yang/cli-anything-hub",
-          "https://www.skillhub.club/web/skills/itsyuhao-cli-anything-hub",
-          "https://skillhub.cn/skills/cli-hub-meta-skill"
-        ],
-        "potentialAction": [
-          {
-            "@type": "InstallAction",
-            "target": "pip install cli-anything-hub"
-          },
-          {
-            "@type": "SearchAction",
-            "target": "cli-hub search {query}",
-            "query-input": "required name=query"
-          }
-        ]
-      },
-      {
-        "@type": "WebSite",
-        "@id": "https://clianything.cc/#website",
-        "name": "CLI-Anything Hub",
-        "url": "https://clianything.cc/",
-        "description": "Agent-friendly CLI registry and package manager.",
-        "publisher": {
-          "@id": "https://clianything.cc/#organization"
-        },
-        "potentialAction": {
-          "@type": "SearchAction",
-          "target": "https://clianything.cc/?q={search_term_string}",
-          "query-input": "required name=search_term_string"
-        }
-      }
-    ]
-  }
-  </script>
+  <link href="https://fonts.googleapis.com/css2?family=Hanken+Grotesk:ital,wght@0,400;0,500;0,600;0,700;0,800;1,500&family=Instrument+Serif:ital@0;1&family=JetBrains+Mono:wght@400;500&family=Newsreader:ital,opsz,wght@0,6..72,300;0,6..72,400;0,6..72,500;1,6..72,300;1,6..72,400&display=swap" rel="stylesheet">
   <style>
+    /* ===================== Tokens (cool/neutral/tech palette system) =====================
+       The anchor tokens (--bg, --surface, --ink/2/3, --line, --accent, --accent2) are set
+       per [data-palette][data-theme] by applyPalette() in JS from the PALETTES object.
+       Everything below derives glass / chip / shadow / accent-ink from those anchors so the
+       glass optics survive every palette × theme combination. Steel-dark values are inlined
+       as a no-JS fallback. */
     :root {
-      --bg: #09090b;
-      --surface: #18181b;
-      --surface-raised: #1e1e22;
-      --border: #27272a;
-      --border-subtle: #1f1f23;
-      --text: #fafafa;
-      --text-secondary: #a1a1aa;
-      --text-tertiary: #71717a;
-      --hero-neutral-top: #e7ecf2;
-      --hero-neutral-bottom: #b8c1cd;
-      --accent: #3b82f6;
-      --accent-muted: #2563eb;
-      --green: #22c55e;
-      --green-muted: rgba(34, 197, 94, 0.12);
-      --purple: #a78bfa;
-      --purple-muted: rgba(167, 139, 250, 0.12);
-      --radius: 8px;
-      --radius-sm: 6px;
-    }
-
-    /* ── Light theme ── */
-    [data-theme="light"] {
-      --bg: #ffffff;
-      --surface: #f4f4f5;
-      --surface-raised: #e4e4e7;
-      --border: #d4d4d8;
-      --border-subtle: #e4e4e7;
-      --text: #09090b;
-      --text-secondary: #52525b;
-      --text-tertiary: #71717a;
-      --hero-neutral-top: #7f8894;
-      --hero-neutral-bottom: #a8b1bc;
-      --accent: #2563eb;
-      --accent-muted: #1d4ed8;
-      --green: #16a34a;
-      --green-muted: rgba(22, 163, 74, 0.1);
-      --purple: #7c3aed;
-      --purple-muted: rgba(124, 58, 237, 0.1);
+      color-scheme: dark;
+      /* --- anchor tokens (Steel · dark fallback; overridden by JS) --- */
+      --bg: #0d1117;
+      --surface: #151b24;
+      --ink: #e8edf4;
+      --ink-2: #9fb0c4;
+      --ink-3: #647488;
+      --line: rgba(255,255,255,0.08);
+      --accent: #5b9bd6;
+      --accent2: #7db4e6;
+      --accent-rgb: 91,155,214;
+      --surface-rgb: 21,27,36;
+      --accent-band: 209;   /* palette accent hue; per-category tints fan around it */
+
+      --ok: #54d196;
+      --radius: 22px;
+      --radius-sm: 13px;
+
+      /* derived (dark) */
+      --accent-ink: var(--accent2);
+      --glass-bg: linear-gradient(158deg, rgba(255,255,255,0.075), rgba(255,255,255,0.024) 46%, rgba(255,255,255,0.010));
+      --glass-bg-fallback: rgba(var(--surface-rgb), 0.86);
+      --glass-border: var(--line);
+      --glass-edge: rgba(255,255,255,0.14);
+      --glass-shadow: 0 24px 60px -22px rgba(0,0,0,0.62), 0 2px 8px -2px rgba(0,0,0,0.48);
+      --glass-shadow-hi: 0 38px 90px -28px rgba(0,0,0,0.70), 0 4px 14px -4px rgba(0,0,0,0.52);
+      --chip-bg: rgba(255,255,255,0.055);
+      --cmd-bg: rgba(0,0,0,0.30);
+      --cmd-line: rgba(255,255,255,0.08);
+
+      --hue-default: 212;
+      --tint-s: 52%;
+      --tint-l: 62%;
+      --ease: cubic-bezier(.22,.61,.36,1);
+      --spring: cubic-bezier(.34,1.32,.5,1);
+      --flip-ease: cubic-bezier(.46,.9,.4,1.05);
+      --palette-transition: background .45s var(--ease), color .45s var(--ease), border-color .45s var(--ease);
     }
 
+    [data-theme="light"] {
+      color-scheme: light;
+      /* Steel · light fallback (overridden by JS) */
+      --bg: #f4f6f9;
+      --surface: #ffffff;
+      --ink: #14181f;
+      --ink-2: #4a5568;
+      --ink-3: #8595a8;
+      --line: rgba(20,40,80,0.10);
+      --accent: #2f6fb0;
+      --accent2: #1f5793;
+      --accent-rgb: 47,111,176;
+      --surface-rgb: 255,255,255;
+
+      --accent-ink: var(--accent2);
+      --glass-bg: linear-gradient(158deg, rgba(255,255,255,0.92), rgba(255,255,255,0.62) 48%, rgba(255,255,255,0.42));
+      --glass-bg-fallback: rgba(var(--surface-rgb), 0.92);
+      --glass-border: var(--line);
+      --glass-edge: rgba(255,255,255,0.96);
+      --glass-shadow: 0 22px 50px -24px rgba(30,44,70,0.22), 0 2px 6px -2px rgba(30,44,70,0.12);
+      --glass-shadow-hi: 0 34px 80px -28px rgba(30,44,70,0.28), 0 4px 12px -4px rgba(30,44,70,0.16);
+      --chip-bg: rgba(20,40,80,0.045);
+      --cmd-bg: rgba(20,40,80,0.05);
+      --cmd-line: rgba(20,40,80,0.08);
+      --tint-s: 46%;
+      --tint-l: 44%;
+    }
+    /* every surface eases between palettes (reduced-motion neutralizes below) */
+    body, .nav.scrolled, .card-face, .mcard, .stat, .empower-card,
+    .typing-shell, .deck-tab, .filter-btn, .search, .sort-select, .chip-label,
+    .scope-banner, .palette-swatch { transition: var(--palette-transition); }
+
+    /* ===================== Reset / base ===================== */
     * { margin: 0; padding: 0; box-sizing: border-box; }
-
+    html { scroll-behavior: smooth; scroll-padding-top: 84px; -webkit-text-size-adjust: 100%; }
     body {
-      font-family: 'Inter', -apple-system, BlinkMacSystemFont, sans-serif;
+      font-family: 'Hanken Grotesk', sans-serif;
       background: var(--bg);
-      color: var(--text);
+      color: var(--ink);
       line-height: 1.6;
+      font-size: 16px;
+      letter-spacing: -0.004em;
       -webkit-font-smoothing: antialiased;
       -moz-osx-font-smoothing: grayscale;
+      min-height: 100vh;
+      overflow-x: hidden;
+    }
+    ::selection { background: rgba(var(--accent-rgb), 0.30); color: var(--ink); }
+    a { color: inherit; }
+    button { font-family: inherit; }
+    h1,h2,h3 { letter-spacing: -0.022em; line-height: 1.1; font-weight: 700; }
+    code, .mono { font-family: 'JetBrains Mono', monospace; }
+
+    /* ===================== Ambient backdrop ===================== */
+    .ambient { position: fixed; inset: 0; z-index: -2; overflow: hidden; pointer-events: none; }
+    .ambient i { position: absolute; border-radius: 50%; filter: blur(100px); opacity: 0.7; will-change: transform; }
+    .ambient .a { width: 60vw; max-width: 760px; aspect-ratio: 1; top: -18vw; right: -10vw;
+      background: radial-gradient(circle at 38% 38%, hsl(calc(var(--accent-band) + 28) var(--tint-s) 58% / 0.26), transparent 64%); }
+    .ambient .b { width: 54vw; max-width: 680px; aspect-ratio: 1; bottom: -16vw; left: -12vw;
+      background: radial-gradient(circle at 60% 42%, hsl(var(--accent-band) calc(var(--tint-s) + 12%) 56% / 0.24), transparent 62%); }
+    .ambient .c { width: 46vw; max-width: 560px; aspect-ratio: 1; top: 42%; left: 50%;
+      background: radial-gradient(circle, hsl(calc(var(--accent-band) - 22) var(--tint-s) 54% / 0.14), transparent 66%); }
+    [data-theme="light"] .ambient i { opacity: 0.55; }
+    .grain { position: fixed; inset: 0; z-index: -1; pointer-events: none; opacity: 0.04; mix-blend-mode: overlay;
+      background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='120' height='120'%3E%3Cfilter id='n'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='0.9' numOctaves='2'/%3E%3C/filter%3E%3Crect width='100%25' height='100%25' filter='url(%23n)'/%3E%3C/svg%3E"); }
+
+    /* ===================== Glass primitive ===================== */
+    .glass {
+      position: relative;
+      background: var(--glass-bg-fallback);
+      border: 1px solid var(--glass-border);
+      border-radius: var(--radius);
+      box-shadow: var(--glass-shadow);
     }
-
-    /* ── Nav bar ── */
-    .nav {
-      display: flex;
-      align-items: center;
-      justify-content: space-between;
-      max-width: 1120px;
-      margin: 0 auto;
-      padding: 1rem 1.5rem;
-      border-bottom: 1px solid var(--border-subtle);
-    }
-
-    .nav-brand {
-      font-size: 0.95rem;
-      font-weight: 600;
-      color: var(--text);
-      text-decoration: none;
-      letter-spacing: -0.01em;
-    }
-
-    .nav-brand span { color: var(--text-tertiary); }
-
-    .nav-links {
-      display: flex;
-      align-items: center;
-      gap: 0.25rem;
-    }
-
-    .nav-link {
-      display: inline-flex;
-      align-items: center;
-      gap: 0.35rem;
-      padding: 0.4rem 0.7rem;
-      color: var(--text-secondary);
-      text-decoration: none;
-      font-size: 0.8rem;
-      font-weight: 500;
-      border-radius: var(--radius-sm);
-      transition: color 0.15s, background 0.15s;
+    @supports ((backdrop-filter: blur(1px)) or (-webkit-backdrop-filter: blur(1px))) {
+      .glass { background: var(--glass-bg);
+        -webkit-backdrop-filter: blur(22px) saturate(1.5); backdrop-filter: blur(22px) saturate(1.5); }
     }
+    .glass::before { content: ''; position: absolute; inset: 0; border-radius: inherit; pointer-events: none;
+      box-shadow: inset 0 1px 0 var(--glass-edge), inset 0 0 0 1px rgba(255,255,255,0.02); }
 
-    .nav-link:hover {
-      color: var(--text);
-      background: var(--surface);
-    }
+    /* ===================== Layout ===================== */
+    .wrap { max-width: 1180px; margin: 0 auto; padding: 0 22px; }
 
+    /* ===================== Nav ===================== */
+    .nav {
+      position: sticky; top: 0; z-index: 40;
+      border-bottom: 1px solid transparent;
+      transition: border-color .3s, background .3s, backdrop-filter .3s;
+    }
+    .nav.scrolled {
+      border-color: var(--line);
+      background: color-mix(in oklab, var(--bg) 78%, transparent);
+      -webkit-backdrop-filter: blur(16px) saturate(1.4); backdrop-filter: blur(16px) saturate(1.4);
+    }
+    .nav-in { max-width: 1180px; margin: 0 auto; padding: 0 22px; display: flex; align-items: center; justify-content: space-between; gap: 14px; height: 64px; }
+    .nav-brand { display: inline-flex; align-items: center; gap: 9px; text-decoration: none; font-weight: 800; font-size: 1.08rem; letter-spacing: -0.02em; }
+    .nav-brand-badge { width: 30px; height: 30px; display: grid; place-items: center; border-radius: 9px; flex-shrink: 0;
+      border: 1px solid var(--glass-border); background: var(--chip-bg); box-shadow: var(--glass-shadow); }
+    .nav-brand-badge svg { width: 64%; height: 64%; }
+    .nav-links { display: flex; align-items: center; gap: 4px; }
+    .nav-link { padding: 7px 11px; border-radius: 10px; text-decoration: none; color: var(--ink-2); font-size: 0.84rem; font-weight: 500;
+      transition: color .18s, background .18s; display: inline-flex; align-items: center; gap: 6px; }
+    .nav-link:hover { color: var(--ink); background: var(--chip-bg); }
     .nav-link svg { width: 15px; height: 15px; flex-shrink: 0; }
-
-    .nav-link-stars {
-      display: inline-flex;
-      align-items: center;
-      justify-content: center;
-      min-width: 2.8rem;
-      padding: 0.1rem 0.45rem;
-      border-radius: 999px;
-      border: 1px solid var(--border);
-      background: var(--surface);
-      color: var(--text);
-      font-size: 0.72rem;
-      font-variant-numeric: tabular-nums;
-      line-height: 1.1;
-    }
-
-    /* ── Theme toggle ── */
-    .theme-toggle {
-      display: inline-flex;
-      align-items: center;
-      justify-content: center;
-      width: 32px;
-      height: 32px;
-      background: none;
-      border: 1px solid var(--border);
-      border-radius: var(--radius-sm);
-      color: var(--text-secondary);
-      cursor: pointer;
-      transition: color 0.15s, border-color 0.15s, background 0.15s;
-      flex-shrink: 0;
-    }
-
-    .theme-toggle:hover {
-      color: var(--text);
-      border-color: var(--text-tertiary);
-      background: var(--surface);
-    }
-
-    .theme-toggle svg { width: 16px; height: 16px; }
+    .nav-link-stars { font-family: 'JetBrains Mono', monospace; font-size: 0.72rem; font-weight: 600; color: var(--accent-ink);
+      background: var(--chip-bg); border: 1px solid var(--line); border-radius: 7px; padding: 1px 7px; font-variant-numeric: tabular-nums; }
+    .theme-toggle { display: inline-grid; place-items: center; width: 36px; height: 36px; border-radius: 11px;
+      border: 1px solid var(--line); background: var(--chip-bg); color: var(--ink-2); cursor: pointer; transition: color .18s, border-color .18s; }
+    .theme-toggle:hover { color: var(--ink); border-color: var(--ink-3); }
+    .theme-toggle svg { width: 17px; height: 17px; }
     .theme-toggle .icon-moon { display: none; }
-    .theme-toggle .icon-sun { display: block; }
     [data-theme="light"] .theme-toggle .icon-moon { display: block; }
     [data-theme="light"] .theme-toggle .icon-sun { display: none; }
 
-    /* ── Hero ── */
-    .hero {
-      max-width: 1120px;
-      margin: 0 auto;
-      padding: 3.5rem 1.5rem 2.5rem;
-      text-align: center;
-    }
-
-    .hero-title {
-      display: inline-flex;
-      align-items: center;
-      justify-content: center;
-      gap: 0.95rem;
-      margin-bottom: 0.82rem;
-      position: relative;
-    }
-
-    .hero-title-badge {
-      position: relative;
-      width: 3.25rem;
-      height: 3.25rem;
-      display: inline-flex;
-      align-items: center;
-      justify-content: center;
-      border-radius: 12px;
-      border: 1px solid rgba(148, 163, 184, 0.12);
-      background:
-        linear-gradient(180deg, rgba(255, 255, 255, 0.035), rgba(255, 255, 255, 0.008)),
-        linear-gradient(135deg, rgba(59, 130, 246, 0.08), transparent 42%),
-        var(--surface);
-      box-shadow:
-        inset 0 1px 0 rgba(255, 255, 255, 0.05),
-        inset 0 -1px 0 rgba(255, 255, 255, 0.02),
-        0 14px 34px rgba(2, 6, 23, 0.2);
-      overflow: hidden;
-      backdrop-filter: blur(8px);
-      -webkit-backdrop-filter: blur(8px);
-    }
-
-    .hero-title-badge::before {
-      content: '';
-      position: absolute;
-      inset: 0;
-      border-radius: inherit;
-      background: linear-gradient(180deg, rgba(255,255,255,0.04), transparent 36%, transparent 100%);
-      pointer-events: none;
-    }
-
-    .hero-title-badge svg {
-      width: 2.26rem;
-      height: 2.26rem;
-      overflow: visible;
-    }
-
-    .hero h1 {
-      font-size: 2.8rem;
-      font-weight: 800;
-      letter-spacing: -0.02em;
-      line-height: 1.15;
-      margin: 0;
-      display: inline-flex;
-      align-items: baseline;
-      gap: 0.18em;
-      flex-wrap: wrap;
-      justify-content: center;
-    }
-
-    .hero-word {
-      display: inline-block;
-      will-change: transform, opacity;
-    }
-
-    .js .hero-word {
-      opacity: 0;
-      transform: translateY(18px);
-    }
-
-    .motion-ready .hero-word--cli {
-      animation: hero-rise-in 0.72s cubic-bezier(0.2, 0.9, 0.2, 1) 0.06s both;
-    }
-
-    .motion-ready .hero-word--anything {
-      animation: hero-rise-in 0.82s cubic-bezier(0.2, 0.9, 0.2, 1) 0.18s both;
-    }
-
-    .motion-ready .hero-word--hub {
-      animation: hero-drop-in 0.8s cubic-bezier(0.2, 0.9, 0.2, 1) 0.34s both;
-    }
-
-    .hero-accent { color: var(--accent); }
-    .hero-dim {
-      color: var(--hero-neutral-bottom);
-      background: linear-gradient(180deg, var(--hero-neutral-top) 0%, var(--hero-neutral-bottom) 100%);
-      -webkit-background-clip: text;
-      background-clip: text;
-      -webkit-text-fill-color: transparent;
-      opacity: 0.9;
-    }
-
-    .hero-shimmer {
-      position: relative;
-      isolation: isolate;
-    }
-
-    .hero-shimmer::after {
-      content: attr(data-text);
-      position: absolute;
-      inset: 0;
-      color: transparent;
-      background: linear-gradient(115deg, transparent 22%, rgba(255,255,255,0.94) 48%, transparent 72%);
-      background-size: 220% 100%;
-      background-position: 145% 50%;
-      -webkit-background-clip: text;
-      background-clip: text;
-      opacity: 0;
-      pointer-events: none;
-    }
-
-    .motion-ready .hero-shimmer::after {
-      animation: hero-shimmer-pass 1.25s ease-out 0.66s 1 both;
-    }
-
-    .hero-tagline {
-      font-size: 1.15rem;
-      color: var(--text-secondary);
-      line-height: 1.6;
-      max-width: 700px;
-      margin: 0 auto 1.5rem;
-      letter-spacing: 0;
-      text-align: center;
-      white-space: normal;
-    }
-
-    .hero-tagline-line {
-      display: inline;
-    }
-
-    .js .hero-tagline-line {
-      opacity: 0;
-      transform: translateY(10px);
-    }
-
-    .hero-tagline-line--any {
-      color: var(--text);
-      font-weight: 600;
-    }
-
-    .motion-ready .hero-tagline-line--any {
-      animation: hero-tagline-in 0.62s ease-out 0.5s both;
-    }
-
-    .motion-ready .hero-tagline-line--rest {
-      animation: hero-tagline-in 0.62s ease-out 0.64s both;
-    }
-
-    .hero-tagline strong { color: var(--text); font-weight: 600; }
-
-    .motion-ready .hero-title-badge {
-      animation: hero-badge-in 0.68s cubic-bezier(0.2, 0.9, 0.2, 1) 0.02s both;
-    }
-
-    .motion-ready .hero-title-badge svg {
-      animation: hero-badge-float 4.2s ease-in-out 1.1s infinite;
-    }
-
-    .motion-ready .hero-badge-glow {
-      animation: hero-badge-pulse 4.2s ease-in-out 1.1s infinite;
-    }
-
-    .motion-ready .hero-badge-cursor {
-      animation: hero-badge-cursor 1.1s steps(1) infinite;
-    }
-
-    @keyframes hero-rise-in {
-      from {
-        opacity: 0;
-        transform: translateY(18px);
-      }
-      to {
-        opacity: 1;
-        transform: translateY(0);
-      }
-    }
-
-    @keyframes hero-drop-in {
-      from {
-        opacity: 0;
-        transform: translateY(-16px);
-      }
-      to {
-        opacity: 1;
-        transform: translateY(0);
-      }
-    }
-
-    @keyframes hero-tagline-in {
-      from {
-        opacity: 0;
-        transform: translateY(10px);
-      }
-      to {
-        opacity: 1;
-        transform: translateY(0);
-      }
-    }
-
-    @keyframes hero-badge-in {
-      from {
-        opacity: 0;
-        transform: translateY(10px) scale(0.94);
-      }
-      to {
-        opacity: 1;
-        transform: translateY(0) scale(1);
-      }
-    }
-
-    @keyframes hero-badge-float {
-      0%, 100% { transform: translateY(0); }
-      50% { transform: translateY(-3px); }
-    }
-
-    @keyframes hero-badge-pulse {
-      0%, 100% { opacity: 0.3; }
-      50% { opacity: 0.88; }
-    }
-
-    @keyframes hero-badge-cursor {
-      0%, 48% { opacity: 1; }
-      49%, 100% { opacity: 0.18; }
-    }
-
-    @keyframes hero-shimmer-pass {
-      0% {
-        opacity: 0;
-        background-position: 145% 50%;
-      }
-      12% {
-        opacity: 0.92;
-      }
-      78% {
-        opacity: 0.92;
-      }
-      100% {
-        opacity: 0;
-        background-position: -55% 50%;
-      }
-    }
-
-    @keyframes hero-stats-in {
-      from {
-        opacity: 0;
-        transform: translateY(12px);
-      }
-      to {
-        opacity: 1;
-        transform: translateY(0);
-      }
-    }
-
-    /* ── Empower card ── */
-    .empower-row {
-      display: flex;
-      gap: 1rem;
-      max-width: 1100px;
-      margin: 0 auto 1.5rem;
-      align-items: stretch;
-    }
-
-    .empower-card {
-      flex: 1;
-      min-width: 0;
-      margin: 0;
-      background: var(--surface);
-      border: 1px solid var(--border);
-      border-radius: 12px;
-      padding: 1.5rem 1.75rem;
-      text-align: left;
-      position: relative;
-      overflow: hidden;
-    }
-
-    .empower-card::before {
-      content: '';
-      position: absolute;
-      top: 0; left: 0; right: 0;
-      height: 2px;
-      background: var(--accent);
-    }
-
-    .empower-card h3 {
-      font-size: 0.95rem;
-      font-weight: 600;
-      margin-bottom: 0.85rem;
-      color: var(--text);
-    }
-
-    .empower-card h3 span { color: var(--accent); }
-
-    .install-row {
-      display: flex;
-      align-items: center;
-      gap: 0.5rem;
-      background: var(--bg);
-      border: 1px solid var(--border);
-      border-radius: var(--radius-sm);
-      padding: 0.52rem 0.75rem;
-      margin-bottom: 0.5rem;
-    }
-
-    .install-row:hover { border-color: var(--text-tertiary); }
-
-    .install-row code {
-      font-family: 'JetBrains Mono', monospace;
-      font-size: 0.78rem;
-      color: var(--text-secondary);
-      flex: 1;
-      white-space: nowrap;
-      overflow: hidden;
-      text-overflow: ellipsis;
-    }
-
-    .install-row--wrap {
-      align-items: flex-start;
-    }
-
-    .install-row--wrap code {
-      white-space: normal;
-      overflow: visible;
-      text-overflow: clip;
-      overflow-wrap: anywhere;
-      word-break: break-word;
-      line-height: 1.45;
-      padding-top: 0.08rem;
-    }
-
-    .empower-note {
-      margin-top: 0.25rem;
-      font-size: 0.76rem;
-      color: var(--text-tertiary);
-      line-height: 1.5;
-    }
-
-    .empower-note strong {
-      color: var(--text-secondary);
-      font-weight: 600;
-    }
-
-    .empower-prompt {
-      margin-top: 0.85rem;
-      padding: 0.6rem 0.85rem;
-      background: rgba(59, 130, 246, 0.05);
-      border: 1px dashed rgba(59, 130, 246, 0.2);
-      border-radius: var(--radius);
-      font-size: 0.82rem;
-      color: var(--text-tertiary);
-      line-height: 1.5;
-    }
-
-    .empower-prompt strong { color: var(--text-secondary); font-weight: 600; }
-    .empower-prompt em { color: var(--accent); font-style: italic; }
-
-    .empower-available {
-      margin: 0.25rem 0 0.7rem;
-      font-size: 0.78rem;
-      color: var(--text-tertiary);
-    }
-    .empower-available a { color: var(--accent); text-decoration: none; }
+    /* Mobile nav drawer */
+    .nav-menu { display: flex; align-items: center; gap: 4px; }
+    .nav-toggle { display: none; position: relative; z-index: 70; place-items: center; width: 38px; height: 38px;
+      border-radius: 11px; border: 1px solid var(--line); background: var(--chip-bg); color: var(--ink); cursor: pointer;
+      transition: color .18s, border-color .18s; }
+    .nav-toggle:hover { border-color: var(--ink-3); }
+    .nav-toggle svg { width: 19px; height: 19px; }
+    .nav-toggle .icon-x { display: none; }
+    .nav-toggle.open .icon-bars { display: none; }
+    .nav-toggle.open .icon-x { display: block; }
+    .nav-scrim { position: fixed; inset: 0; z-index: 55; background: rgba(2,5,10,0.5);
+      -webkit-backdrop-filter: blur(2px); backdrop-filter: blur(2px); opacity: 0; visibility: hidden;
+      transition: opacity .3s var(--ease), visibility .3s; }
+    .nav-scrim.open { opacity: 1; visibility: visible; }
+    .nav-menu.open { transform: none; }
+    @media (max-width: 860px) {
+      .nav-toggle { display: inline-grid; }
+      .nav-menu { position: fixed; top: 0; right: 0; height: 100dvh; width: min(82vw, 320px);
+        flex-direction: column; align-items: stretch; gap: 6px; padding: 80px 16px 28px;
+        background: var(--glass-bg-fallback); border-left: 1px solid var(--line);
+        box-shadow: -24px 0 64px -28px rgba(0,0,0,0.6); transform: translateX(106%);
+        transition: transform .34s var(--ease); overflow-y: auto; z-index: 60; }
+      .nav-menu .nav-link { padding: 12px 14px; font-size: 0.98rem; border-radius: 11px; color: var(--ink-2); }
+      .nav-menu .nav-link.active { color: var(--ink); background: var(--chip-bg); }
+      .nav-menu .nav-link svg { width: 19px; height: 19px; }
+      .nav-menu .nav-link-stars { margin-left: auto; }
+    }
+    @supports ((backdrop-filter: blur(1px)) or (-webkit-backdrop-filter: blur(1px))) {
+      @media (max-width: 860px) {
+        .nav-menu { background: var(--glass-bg); -webkit-backdrop-filter: blur(22px) saturate(1.4); backdrop-filter: blur(22px) saturate(1.4); }
+      }
+    }
+
+    /* ===================== Palette switcher ===================== */
+    /* Palette switcher hidden from the header (default palette = Steel still applies). */
+    .palette-switch { display: none; align-items: center; gap: 5px; padding: 4px; border-radius: 13px;
+      border: 1px solid var(--line); background: var(--chip-bg); }
+    .palette-switch-label { font-size: 0.62rem; font-weight: 700; letter-spacing: 0.1em; text-transform: uppercase;
+      color: var(--ink-3); padding: 0 4px 0 6px; }
+    .palette-swatch { width: 24px; height: 24px; border-radius: 8px; cursor: pointer; padding: 0; position: relative;
+      border: 1px solid rgba(255,255,255,0.18); overflow: hidden;
+      background: linear-gradient(135deg, var(--sw-accent) 0 52%, var(--sw-grey) 52% 100%); }
+    [data-theme="light"] .palette-swatch { border-color: rgba(20,40,80,0.18); }
+    .palette-swatch:hover { transform: translateY(-1px); }
+    .palette-swatch:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; }
+    .palette-swatch[aria-pressed="true"] { box-shadow: 0 0 0 2px var(--bg), 0 0 0 4px var(--accent); }
+    @media (max-width: 860px) { .palette-switch-label { display: none; } }
+    @media (max-width: 520px) { .palette-switch { display: none; } }
+    /* compact popover variant for small screens */
+    .palette-popwrap { position: relative; display: none; }
+    .palette-pop-btn { display: inline-grid; place-items: center; width: 36px; height: 36px; border-radius: 11px;
+      border: 1px solid var(--line); background: var(--chip-bg); color: var(--ink-2); cursor: pointer; }
+    .palette-pop-btn:hover { color: var(--ink); border-color: var(--ink-3); }
+    .palette-pop-btn svg { width: 17px; height: 17px; }
+    .palette-pop-panel { position: absolute; right: 0; top: calc(100% + 8px); display: none; flex-direction: column; gap: 6px;
+      padding: 10px; border-radius: 13px; border: 1px solid var(--glass-border); background: var(--glass-bg-fallback);
+      box-shadow: var(--glass-shadow-hi); z-index: 50; min-width: 150px; }
+    .palette-popwrap.open .palette-pop-panel { display: flex; }
+    .palette-pop-panel .pp-row { display: flex; align-items: center; gap: 9px; padding: 6px 8px; border-radius: 9px;
+      border: 1px solid transparent; background: transparent; color: var(--ink-2); cursor: pointer; font-size: 0.84rem; font-weight: 600; font-family: inherit; }
+    .palette-pop-panel .pp-row:hover { background: var(--chip-bg); color: var(--ink); }
+    .palette-pop-panel .pp-row[aria-pressed="true"] { color: var(--ink); border-color: var(--accent); }
+    .palette-pop-panel .pp-dot { width: 18px; height: 18px; border-radius: 6px; flex-shrink: 0;
+      background: linear-gradient(135deg, var(--sw-accent) 0 52%, var(--sw-grey) 52% 100%); }
+
+    /* ===================== Reveal motion ===================== */
+    .reveal { opacity: 0; transform: translateY(22px); transition: opacity .7s var(--ease), transform .7s var(--ease); }
+    .reveal.in { opacity: 1; transform: none; }
+    [style*="--d"] { transition-delay: var(--d); }
+
+    /* ===================== Hero ===================== */
+    .hero { max-width: 1180px; margin: 0 auto; padding: 70px 22px 24px; text-align: center; }
+    .hero-title { display: flex; align-items: center; justify-content: center; gap: clamp(14px, 2.4vw, 22px); }
+    /* Badge scales with the serif title so it reads as a peer of the wordmark (≈ title
+       font-size), not a small chip. The inner glyph tracks the tile size. */
+    .hero-title-badge { width: clamp(2.6rem, 7.4vw, 5rem); height: clamp(2.6rem, 7.4vw, 5rem);
+      display: grid; place-items: center; border-radius: clamp(15px, 1.8vw, 22px); flex-shrink: 0;
+      border: 1px solid var(--glass-border); background: var(--chip-bg); box-shadow: var(--glass-shadow); }
+    .hero-title-badge svg { width: 64%; height: 64%; }
+    /* Premium Serif Display title (V1 "Accent on Anything"): Newsreader serif,
+       "Anything" in serif italic carrying the solid palette accent, while "CLI-" and
+       "Hub" stay ink. No gradient. The accent uses the palette's accent2 in light and
+       accent in dark (legibility-tuned), so the word recolors with the palette switcher. */
+    .hero h1 { font-family: 'Newsreader', serif; font-weight: 400; color: var(--ink);
+      font-size: clamp(2.7rem, 7.6vw, 5.1rem); letter-spacing: -0.018em; line-height: 1.0; }
+    .hero-word { display: inline-block; }
+    .hero-word--cli, .hero-word--hub { color: var(--ink); }
+    .hero-word--anything { font-style: italic; font-weight: 300; letter-spacing: 0; color: var(--accent2); }
+    [data-theme="dark"] .hero-word--anything { color: var(--accent); }
+    .hero-tagline { max-width: 60ch; margin: 20px auto 0; color: var(--ink-2); font-size: clamp(1rem, 2.2vw, 1.18rem); }
+    .hero-tagline-line--any { color: var(--ink); font-weight: 600; }
+
+    .stats { display: flex; justify-content: center; gap: 12px; flex-wrap: wrap; margin-top: 30px; }
+    .stat { padding: 13px 24px; border-radius: 15px; text-align: center; min-width: 130px;
+      background: var(--glass-bg-fallback); border: 1px solid var(--glass-border); box-shadow: var(--glass-shadow); position: relative; }
+    @supports ((backdrop-filter: blur(1px)) or (-webkit-backdrop-filter: blur(1px))) {
+      .stat { background: var(--glass-bg); -webkit-backdrop-filter: blur(18px) saturate(1.4); backdrop-filter: blur(18px) saturate(1.4); }
+    }
+    /* Stat figures use the SAME two-token accent rule as the italic "Anything" word in the
+       title (accent2 in light, accent in dark), so they recolor with palette + theme, and
+       are enlarged to read as large figures like the remote reference. */
+    .stat-num { font-size: clamp(2.1rem, 4.4vw, 2.7rem); font-weight: 800; letter-spacing: -0.03em;
+      font-variant-numeric: tabular-nums; line-height: 1.05; color: var(--accent2); }
+    [data-theme="dark"] .stat-num { color: var(--accent); }
+    .stat-label { font-size: 0.72rem; color: var(--ink-3); text-transform: uppercase; letter-spacing: 0.1em; font-weight: 600; margin-top: 2px; }
+
+    /* ===================== Empower cards ===================== */
+    /* align-items: stretch makes the two side-by-side cards equal height; each card is a
+       column flexbox so its inner content distributes evenly down to the matched height. */
+    .empower-row { display: grid; gap: 18px; grid-template-columns: 1fr 1fr; margin-top: 38px; text-align: left; align-items: stretch; }
+    @media (max-width: 820px) { .empower-row { grid-template-columns: 1fr; } }
+    .empower-card { padding: 24px 24px 22px; border-radius: var(--radius); border: 1px solid var(--glass-border);
+      background: var(--glass-bg-fallback); box-shadow: var(--glass-shadow); position: relative;
+      display: flex; flex-direction: column; }
+    @supports ((backdrop-filter: blur(1px)) or (-webkit-backdrop-filter: blur(1px))) {
+      .empower-card { background: var(--glass-bg); -webkit-backdrop-filter: blur(20px) saturate(1.4); backdrop-filter: blur(20px) saturate(1.4); }
+    }
+    .empower-card::before { content: ''; position: absolute; inset: 0; border-radius: inherit; pointer-events: none;
+      box-shadow: inset 0 1px 0 var(--glass-edge); }
+    .empower-card h3 { font-size: 1.16rem; font-weight: 700; }
+    .empower-card h3 span { color: var(--accent2); }
+    [data-theme="dark"] .empower-card h3 span { color: var(--accent); }
+    .empower-available { font-size: 0.84rem; color: var(--ink-3); margin-top: 8px; }
+    .empower-available a { color: var(--accent-ink); text-decoration: none; font-weight: 600; }
     .empower-available a:hover { text-decoration: underline; }
-
-    .empower-card.empower-self::before { background: var(--green); }
-    .empower-card.empower-self h3 span { color: var(--green); }
-    .typing-shell {
-      position: relative;
-      margin-bottom: 0.9rem;
-      padding: 0.8rem 0.92rem 0.88rem;
-      background:
-        linear-gradient(180deg, rgba(34, 197, 94, 0.06) 0%, rgba(34, 197, 94, 0.015) 100%),
-        radial-gradient(circle at top right, rgba(59, 130, 246, 0.14), transparent 42%),
-        var(--bg);
-      border: 1px solid rgba(63, 63, 70, 0.95);
-      border-radius: 11px;
-      overflow: hidden;
-      box-shadow: inset 0 1px 0 rgba(255, 255, 255, 0.03), 0 12px 28px rgba(0, 0, 0, 0.16);
-    }
-    .typing-shell::before {
-      content: '';
-      position: absolute;
-      inset: 0;
-      background: linear-gradient(180deg, rgba(255, 255, 255, 0.035), transparent 22%, transparent 78%, rgba(255, 255, 255, 0.025));
-      pointer-events: none;
-    }
-    .typing-shell-head {
-      display: flex;
-      align-items: center;
-      justify-content: space-between;
-      gap: 0.75rem;
-      margin-bottom: 0.56rem;
-      position: relative;
-      z-index: 1;
-    }
-    .typing-shell-label {
-      display: inline-flex;
-      align-items: center;
-      gap: 0.42rem;
-      color: var(--text-tertiary);
-      font-size: 0.68rem;
-      font-style: italic;
-      letter-spacing: 0.06em;
-      text-transform: uppercase;
-    }
-    .typing-shell-label::before {
-      content: '';
-      width: 0.42rem;
-      height: 0.42rem;
-      border-radius: 999px;
-      background: var(--green);
-      box-shadow: 0 0 14px rgba(34, 197, 94, 0.55);
-      flex-shrink: 0;
-    }
-    .typing-shell-copy {
-      position: relative;
-      z-index: 1;
-    }
-    .typing-shell-body {
-      position: relative;
-      z-index: 1;
-      display: flex;
-      align-items: center;
-      gap: 0.65rem;
-      min-height: 2.5rem;
-      padding: 0.76rem 0.82rem;
-      border-radius: 9px;
-      border: 1px solid rgba(63, 63, 70, 0.92);
-      background: linear-gradient(180deg, rgba(9, 9, 11, 0.74), rgba(9, 9, 11, 0.94));
-    }
-    .typing-shell-prompt {
-      color: var(--green);
-      font-family: 'JetBrains Mono', monospace;
-      font-size: 0.82rem;
-      font-weight: 500;
-      text-shadow: 0 0 16px rgba(34, 197, 94, 0.25);
-      flex-shrink: 0;
-    }
-    .typing-shell-code {
-      flex: 1;
-      min-width: 0;
-      display: inline-flex;
-      align-items: center;
-      font-family: 'JetBrains Mono', monospace;
-      font-size: 0.8rem;
-      color: #d4d4d8;
-      letter-spacing: -0.01em;
-      white-space: nowrap;
-      overflow: hidden;
-    }
-    .typing-shell-text {
-      display: inline-block;
-      min-height: 1em;
-    }
-    .typing-shell-cursor {
-      width: 0.62ch;
-      height: 1.1em;
-      margin-left: 0.1rem;
-      border-radius: 1px;
-      background: linear-gradient(180deg, #fafafa, #a1a1aa);
-      box-shadow: 0 0 14px rgba(255, 255, 255, 0.2);
-      animation: typing-caret 1s steps(1) infinite;
-      flex-shrink: 0;
-    }
-    .typing-shell-subtitle {
-      position: relative;
-      z-index: 1;
-      margin-top: 0.55rem;
-      color: var(--text-tertiary);
-      font-size: 0.73rem;
-      font-style: italic;
-      line-height: 1.45;
-    }
-    @keyframes typing-caret {
-      0%, 48% { opacity: 1; }
-      49%, 100% { opacity: 0.2; }
-    }
-    .empower-self .cmd-grid {
-      display: grid;
-      grid-template-columns: 1fr 1fr;
-      gap: 0.38rem;
-    }
-    .empower-self .cmd-item {
-      display: grid;
-      grid-template-rows: auto auto;
-      align-content: start;
-      gap: 0.1rem;
-      background: var(--bg);
-      border: 1px solid var(--border);
-      border-radius: var(--radius-sm);
-      padding: 0.42rem 0.64rem 0.44rem;
-      min-height: 3.12rem;
-    }
-    .empower-self .cmd-item:hover { border-color: var(--text-tertiary); }
-    .empower-self .cmd-item .cmd-name {
-      color: var(--green);
-      font-family: 'JetBrains Mono', monospace;
-      font-weight: 500;
-      font-size: 0.76rem;
-      line-height: 1.18;
-      white-space: nowrap;
-    }
-    .empower-self .cmd-item .cmd-desc {
-      color: var(--text-tertiary);
-      font-size: 0.68rem;
-      line-height: 1.22;
-      letter-spacing: -0.01em;
-    }
-
-    .hero-actions {
-      display: flex;
-      justify-content: center;
-      align-items: center;
-      gap: 0.5rem;
-      flex-wrap: wrap;
-      margin-bottom: 1rem;
-    }
-
-    .btn-primary {
-      display: inline-flex;
-      align-items: center;
-      gap: 0.4rem;
-      padding: 0.55rem 1.1rem;
-      background: var(--text);
-      color: var(--bg);
-      text-decoration: none;
-      font-size: 0.85rem;
-      font-weight: 600;
-      border-radius: var(--radius-sm);
-      transition: opacity 0.15s;
-      border: none;
-      cursor: pointer;
-    }
-
-    .btn-primary:hover { opacity: 0.85; }
-
-    .btn-secondary {
-      display: inline-flex;
-      align-items: center;
-      gap: 0.4rem;
-      padding: 0.55rem 1.1rem;
-      background: transparent;
-      color: var(--text-secondary);
-      text-decoration: none;
-      font-size: 0.85rem;
-      font-weight: 500;
-      border-radius: var(--radius-sm);
-      border: 1px solid var(--border);
-      transition: border-color 0.15s, color 0.15s;
-      cursor: pointer;
-    }
-
-    .btn-secondary:hover { border-color: var(--text-tertiary); color: var(--text); }
+    .install-row { display: flex; align-items: center; gap: 0; margin-top: 14px; border-radius: 13px; overflow: hidden;
+      border: 1px solid var(--cmd-line); background: var(--cmd-bg); }
+    .install-row--wrap { flex-wrap: wrap; }
+    .install-row .chip-label { font-family: 'JetBrains Mono', monospace; font-size: 0.68rem; font-weight: 600; text-transform: lowercase;
+      color: var(--ink-3); padding: 0 12px; align-self: stretch; display: inline-flex; align-items: center; border-right: 1px solid var(--cmd-line); white-space: nowrap; }
+    .install-row code { font-family: 'JetBrains Mono', monospace; font-size: 0.82rem; padding: 12px 14px; color: var(--ink);
+      flex: 1; min-width: 0; overflow-x: auto; white-space: nowrap; }
+    .copy-btn { border: 0; border-left: 1px solid var(--cmd-line); background: var(--chip-bg); color: var(--ink-2);
+      padding: 0 16px; align-self: stretch; cursor: pointer; font-size: 0.78rem; font-weight: 600;
+      transition: color .18s, background .18s; white-space: nowrap; }
+    .copy-btn:hover { color: var(--ink); background: color-mix(in oklab, var(--accent) 18%, transparent); }
+    .empower-note { font-size: 0.84rem; color: var(--ink-2); margin-top: 14px; }
+    .empower-note strong { color: var(--ink); }
+    .empower-prompt { font-size: 0.85rem; color: var(--ink-2); margin-top: 10px; padding: 11px 13px; border-radius: 11px;
+      border: 1px solid var(--line); background: var(--chip-bg); }
+    .empower-prompt strong { color: var(--ink); }
+    .empower-prompt em { color: var(--accent-ink); font-style: italic; }
+
+    /* Toolkit grid: compressed rows (tighter padding, smaller gaps) so the "Empower yourself"
+       card fills its share of the matched equal-height row cleanly without looking sparse. */
+    .cmd-grid { display: grid; grid-template-columns: 1fr 1fr; gap: 6px; margin-top: 14px; flex: 1 1 auto; align-content: stretch; }
+    @media (max-width: 420px) { .cmd-grid { grid-template-columns: 1fr; } }
+    .cmd-item { display: flex; flex-direction: column; justify-content: center; gap: 0; padding: 7px 11px; border-radius: 9px;
+      border: 1px solid var(--line); background: var(--chip-bg); }
+    .cmd-name { font-family: 'JetBrains Mono', monospace; font-size: 0.75rem; color: var(--accent-ink); font-weight: 500; line-height: 1.35; }
+    .cmd-desc { font-size: 0.72rem; color: var(--ink-3); line-height: 1.3; }
+
+    /* ===================== Hero actions ===================== */
+    .hero-actions { display: flex; flex-wrap: wrap; gap: 10px; justify-content: center; margin-top: 34px; }
+    .btn-primary, .btn-secondary { display: inline-flex; align-items: center; gap: 8px; padding: 12px 20px; border-radius: 13px;
+      font-weight: 600; font-size: 0.9rem; text-decoration: none; cursor: pointer; transition: transform .15s, border-color .18s, background .18s; }
+    .btn-primary { color: #fff; border: 1px solid transparent;
+      background: linear-gradient(120deg, var(--accent2), var(--accent)); box-shadow: 0 12px 30px -14px rgba(var(--accent-rgb), 0.7); }
+    .btn-primary:hover { transform: translateY(-2px); }
+    .btn-secondary { color: var(--ink); border: 1px solid var(--glass-border); background: var(--chip-bg); }
+    .btn-secondary:hover { transform: translateY(-2px); border-color: var(--ink-3); }
     .btn-secondary svg { width: 15px; height: 15px; }
 
-    .hero-hint {
-      font-size: 0.78rem;
-      color: var(--text-tertiary);
-      font-style: italic;
-      margin-bottom: 0.75rem;
-    }
-
-    .hero-hint a {
-      color: var(--text-tertiary);
-      text-decoration: underline;
-      text-decoration-style: dotted;
-    }
-
-    .hero-hint a:hover { color: var(--text-secondary); }
-
-    .hero-cta {
-      font-size: 0.95rem;
-      color: var(--text-secondary);
-      line-height: 1.65;
-      max-width: 700px;
-      margin: 0 auto;
-    }
-
-    .hero-cta em { color: var(--accent); font-style: normal; font-weight: 600; }
-    .hero-cta a { color: var(--accent); text-decoration: none; font-weight: 500; }
+    .hero-hint { margin-top: 18px; font-size: 0.86rem; color: var(--ink-3); }
+    .hero-hint a { color: var(--accent-ink); font-weight: 600; text-decoration: none; }
+    .hero-hint a:hover { text-decoration: underline; }
+    .hero-cta { max-width: 760px; margin: 26px auto 0; font-size: 0.9rem; color: var(--ink-2); text-align: center; }
+    .hero-cta .nowrap { white-space: nowrap; }
+    .hero-cta em { color: var(--accent-ink); font-style: normal; font-weight: 700; }
+    .hero-cta a { color: var(--accent-ink); font-weight: 600; text-decoration: none; }
     .hero-cta a:hover { text-decoration: underline; }
 
-    .stats {
-      display: inline-flex;
-      align-items: flex-start;
-      justify-content: center;
-      gap: 0;
-      margin: 0.45rem auto 1.45rem;
-    }
-
-    .js .stats {
-      opacity: 0;
-      transform: translateY(12px);
-    }
-
-    .motion-ready .stats {
-      animation: hero-stats-in 0.66s cubic-bezier(0.2, 0.9, 0.2, 1) 0.78s both;
-    }
-
-    .stat {
-      min-width: 8.5rem;
-      padding: 0 1.55rem;
-      position: relative;
-      text-align: center;
-    }
-
-    .stat + .stat::before {
-      content: '';
-      position: absolute;
-      left: 0;
-      top: 0.2rem;
-      bottom: 0.2rem;
-      width: 1px;
-      background: linear-gradient(180deg, transparent, rgba(148, 163, 184, 0.32), transparent);
-    }
-
-    .stat-num {
-      font-size: 2.7rem;
-      line-height: 1;
-      font-weight: 800;
-      letter-spacing: -0.045em;
-      color: var(--accent);
-      font-variant-numeric: tabular-nums;
-      text-shadow: 0 10px 28px rgba(37, 99, 235, 0.16);
-    }
-
-    .stat-label {
-      margin-top: 0.38rem;
-      font-size: 0.73rem;
-      color: var(--text-tertiary);
-      text-transform: uppercase;
-      letter-spacing: 0.09em;
-      font-weight: 600;
-    }
-
-    .chip-label {
-      font-size: 0.7rem;
-      font-weight: 600;
-      text-transform: uppercase;
-      letter-spacing: 0.04em;
-      color: var(--text-tertiary);
-      background: var(--surface-raised);
-      padding: 0.15rem 0.45rem;
-      border-radius: 4px;
-      flex-shrink: 0;
-    }
-
-    .copy-btn {
-      background: none;
-      border: 1px solid var(--border);
-      border-radius: 4px;
-      color: var(--text-tertiary);
-      cursor: pointer;
-      padding: 0.2rem 0.45rem;
-      font-size: 0.7rem;
-      font-family: 'Inter', sans-serif;
-      transition: color 0.15s, border-color 0.15s;
-      white-space: nowrap;
-    }
-
-    .copy-btn:hover { color: var(--text); border-color: var(--text-tertiary); }
-
-    /* ── Divider ── */
-    .section-divider {
-      max-width: 1120px;
-      margin: 0 auto;
-      border-top: 1px solid var(--border-subtle);
-    }
-
-    .marketplace-prelude {
-      max-width: 1200px;
-      margin: 0 auto;
-      padding: 0.9rem 1.5rem 0;
-    }
-
-    .marketplace-prelude .typing-shell {
-      margin-bottom: 0;
-    }
-
-    /* ── Deck system ── */
-    .deck-stage {
-      --deck-peek: 72px;
-      max-width: 1200px;
-      margin: 0 auto;
-      position: relative;
-    }
-
-    .deck-viewport {
-      --deck-panel-width: calc(100% - var(--deck-peek));
-      width: calc(100% + var(--deck-peek));
-      margin-right: calc(var(--deck-peek) * -1);
-      position: relative;
-      overflow: hidden;
-      isolation: isolate;
-      touch-action: pan-y pinch-zoom;
-    }
-    .deck-viewport.dragging * { user-select: none; }
-
-    .deck-track {
-      display: flex;
-      width: max-content;
-      transition: transform 0.55s cubic-bezier(0.4, 0, 0.15, 1);
-      will-change: transform;
-    }
-
+    /* ===================== Marketplace prelude / typing shell =====================
+       Wide-but-short, matching the remote design's compact proportions: the shell
+       spans the column (no narrow max-width), the caption + Copy sit on one short
+       header row, and the command line is a single slim band — re-themed to glass. */
+    .marketplace-prelude { max-width: 1180px; margin: 36px auto 0; padding: 0 22px; }
+    .typing-shell { width: 100%; max-width: 720px; margin: 0 auto; border-radius: var(--radius-sm); overflow: hidden;
+      padding: 13px 15px 14px; border: 1px solid var(--glass-border); background: var(--glass-bg-fallback);
+      box-shadow: var(--glass-shadow); position: relative; }
+    @supports ((backdrop-filter: blur(1px)) or (-webkit-backdrop-filter: blur(1px))) {
+      .typing-shell { background: var(--glass-bg); -webkit-backdrop-filter: blur(20px) saturate(1.4); backdrop-filter: blur(20px) saturate(1.4); }
+    }
+    .typing-shell-head { display: flex; align-items: center; justify-content: space-between; gap: 12px;
+      margin-bottom: 9px; }
+    .typing-shell-label { display: inline-flex; align-items: center; gap: 7px; font-size: 0.7rem; color: var(--ink-3);
+      letter-spacing: 0.05em; text-transform: uppercase; font-weight: 600; font-style: italic; }
+    .typing-shell-label::before { content: ''; width: 7px; height: 7px; border-radius: 999px; background: var(--ok);
+      box-shadow: 0 0 12px color-mix(in oklab, var(--ok) 60%, transparent); flex-shrink: 0; }
+    .typing-shell-copy { border: 1px solid var(--cmd-line); border-left: 1px solid var(--cmd-line); border-radius: 9px;
+      padding: 5px 13px; flex-shrink: 0; }
+    .typing-shell-body { display: flex; align-items: center; gap: 9px; min-height: 0; padding: 9px 12px;
+      border-radius: 9px; border: 1px solid var(--cmd-line); background: var(--cmd-bg); }
+    .typing-shell-prompt { color: var(--ok); font-family: 'JetBrains Mono', monospace; font-weight: 600; font-size: 0.84rem; flex-shrink: 0; }
+    .typing-shell-code { flex: 1; min-width: 0; font-family: 'JetBrains Mono', monospace; font-size: 0.84rem; color: var(--ink);
+      display: inline-flex; align-items: center; white-space: nowrap; overflow: hidden; }
+    .typing-shell-cursor { display: inline-block; width: 8px; height: 1.05em; background: var(--accent); margin-left: 2px; animation: blink 1.05s steps(1) infinite; }
+    @keyframes blink { 0%,50%{opacity:1} 50.01%,100%{opacity:0} }
+
+    /* ===================== Deck nav ===================== */
+    .deck-nav { max-width: 1180px; margin: 56px auto 18px; padding: 0 22px; display: flex; align-items: center; gap: 8px; flex-wrap: wrap; }
+    .deck-tab { display: inline-flex; align-items: center; gap: 9px; padding: 10px 16px; border-radius: 999px; cursor: pointer;
+      border: 1px solid var(--line); background: var(--chip-bg); color: var(--ink-2); font-size: 0.9rem; font-weight: 600;
+      transition: color .18s, border-color .18s, background .18s; }
+    .deck-tab:hover { color: var(--ink); }
+    .deck-tab.active { color: var(--bg); background: var(--ink); border-color: var(--ink); }
+    [data-theme="light"] .deck-tab.active { color: #fff; }
+    .deck-count { font-family: 'JetBrains Mono', monospace; font-size: 0.72rem; font-weight: 600; opacity: 0.7; font-variant-numeric: tabular-nums; }
+    .deck-separator { flex: 1; }
+    .deck-arrow-btn { display: inline-flex; align-items: center; gap: 7px; padding: 9px 14px; border-radius: 11px; cursor: pointer;
+      border: 1px solid var(--glass-border); background: var(--chip-bg); color: var(--ink-2); font-size: 0.84rem; font-weight: 600;
+      transition: color .18s, border-color .18s; }
+    .deck-arrow-btn:hover { color: var(--ink); border-color: var(--ink-3); }
+    .deck-arrow-btn svg { width: 16px; height: 16px; }
+    .deck-arrow-btn--back { flex-direction: row-reverse; }
+    @media (max-width: 560px) { .deck-arrow-btn { display: none; } .deck-separator { display: none; } }
+
+    /* ===================== Deck stage ===================== */
+    .deck-stage { max-width: 1180px; margin: 0 auto; padding: 0 22px; }
+    .deck-viewport { overflow: hidden; touch-action: pan-y; cursor: grab; }
+    .deck-viewport.dragging { cursor: grabbing; }
+    .deck-track { display: flex; transition: transform .5s var(--spring); will-change: transform; }
     .deck-track.is-dragging { transition: none; }
-
-    .deck-panel {
-      position: relative;
-      width: var(--deck-panel-width);
-      min-width: var(--deck-panel-width);
-      flex-shrink: 0;
-    }
-
-    .deck-panel--public {
-      box-shadow: inset 1px 0 0 rgba(161, 161, 170, 0.55);
-    }
-
-    .deck-panel::before {
-      content: '';
-      position: absolute;
-      inset: 0;
-      opacity: 0;
-      pointer-events: none;
-      transition: opacity 0.28s ease;
-      z-index: 2;
-    }
-
-    .deck-track[data-active="harness"] .deck-panel--public::before {
-      background: linear-gradient(90deg, rgba(9, 9, 11, 0.4) 0%, rgba(9, 9, 11, 0.2) 48%, rgba(9, 9, 11, 0.05) 100%);
-      opacity: 1;
-    }
-
-    .deck-track[data-active="public"] .deck-panel--harness::before {
-      background: linear-gradient(270deg, rgba(9, 9, 11, 0.4) 0%, rgba(9, 9, 11, 0.2) 48%, rgba(9, 9, 11, 0.05) 100%);
-      opacity: 1;
-    }
-
-    [data-theme="light"] .deck-track[data-active="harness"] .deck-panel--public::before {
-      background: linear-gradient(90deg, rgba(250, 250, 250, 0.56) 0%, rgba(250, 250, 250, 0.28) 48%, rgba(250, 250, 250, 0.06) 100%);
-    }
-
-    [data-theme="light"] .deck-track[data-active="public"] .deck-panel--harness::before {
-      background: linear-gradient(270deg, rgba(250, 250, 250, 0.56) 0%, rgba(250, 250, 250, 0.28) 48%, rgba(250, 250, 250, 0.06) 100%);
-    }
-
-    /* ── Deck nav strip ── */
-    .deck-nav {
-      max-width: 1200px;
-      margin: 0 auto;
-      padding: 1.25rem 1.5rem 0;
-      display: flex;
-      align-items: center;
-      gap: 0;
-    }
-
-    .deck-tab {
-      position: relative;
-      padding: 0.6rem 1.25rem;
-      background: none;
-      border: none;
-      color: var(--text-tertiary);
-      font-size: 0.85rem;
-      font-family: 'Inter', sans-serif;
-      font-weight: 500;
-      cursor: pointer;
-      transition: color 0.2s;
-      display: flex;
-      align-items: center;
-      gap: 0.5rem;
-    }
-
-    .deck-tab::after {
-      content: '';
-      position: absolute;
-      bottom: 0; left: 1.25rem; right: 1.25rem;
-      height: 2px;
-      background: transparent;
-      border-radius: 1px;
-      transition: background 0.2s;
-    }
-
-    .deck-tab:hover { color: var(--text-secondary); }
-
-    .deck-tab.active {
-      color: var(--text);
-      font-weight: 600;
-    }
-
-    .deck-tab.active::after {
-      background: var(--accent);
-    }
-
-    .deck-tab.active.deck-tab--public::after {
-      background: var(--orange);
-    }
-
-    .deck-tab .deck-count {
-      font-size: 0.7rem;
-      font-weight: 600;
-      padding: 0.1rem 0.45rem;
-      border-radius: 999px;
-      background: var(--surface-raised);
-      color: var(--text-tertiary);
-      transition: all 0.2s;
-    }
-
-    .deck-tab.active .deck-count {
-      background: rgba(59, 130, 246, 0.12);
-      color: var(--accent);
-    }
-
-    .deck-tab.active.deck-tab--public .deck-count {
-      background: rgba(234, 138, 46, 0.12);
-      color: var(--orange);
-    }
-
-    .deck-separator {
-      flex: 1;
-      height: 1px;
-      background: var(--border-subtle);
-      margin: 0 0.5rem;
-    }
-
-    .deck-arrow-btn {
-      display: inline-flex;
-      align-items: center;
-      gap: 0.35rem;
-      padding: 0.4rem 0.85rem;
-      background: none;
-      border: 1px solid var(--border);
-      border-radius: 999px;
-      color: var(--text-tertiary);
-      font-size: 0.75rem;
-      font-family: 'Inter', sans-serif;
-      font-weight: 500;
-      cursor: pointer;
-      transition: all 0.2s;
-    }
-
-    .deck-arrow-btn:hover {
-      border-color: var(--text-tertiary);
-      color: var(--text-secondary);
-      background: var(--surface);
-    }
-
-    .deck-arrow-btn svg {
-      width: 14px;
-      height: 14px;
-      transition: transform 0.2s;
-    }
-
-    .deck-arrow-btn:hover svg {
-      transform: translateX(2px);
-    }
-
-    .deck-arrow-btn--back:hover svg {
-      transform: translateX(-2px);
-    }
-
-    /* ── Public deck accent ── */
-    :root {
-      --orange: #ea8a2e;
-      --orange-muted: rgba(234, 138, 46, 0.12);
-    }
-
-    [data-theme="light"] {
-      --orange: #c2711e;
-      --orange-muted: rgba(194, 113, 30, 0.1);
-    }
-
-    /* ── Controls ── */
-    .controls {
-      margin: 0;
-      padding: 1.15rem 1.5rem 0;
-      display: flex;
-      gap: 0.7rem;
-      flex-wrap: wrap;
-      align-items: center;
-    }
-
-    .search {
-      flex: 1;
-      min-width: 200px;
-      padding: 0.72rem 0.95rem;
-      background: var(--surface);
-      border: 1px solid var(--border);
-      border-radius: var(--radius-sm);
-      color: var(--text);
-      font-size: 0.9rem;
-      font-family: 'Inter', sans-serif;
-      outline: none;
-      transition: border-color 0.15s;
-    }
-
-    .search::placeholder { color: var(--text-tertiary); }
-    .search:focus { border-color: var(--text-tertiary); }
-
-    .sort-select {
-      min-width: 168px;
-      padding: 0.78rem 2.7rem 0.78rem 1rem;
+    /* Each panel is exactly one viewport wide; the track slides by one full panel width
+       between decks. (Replaces the old over-wide "peek" carousel that mis-measured its
+       width and clipped the active panel on the right while bleeding the other on the left.) */
+    .deck-panel { flex: 0 0 100%; min-width: 0; position: relative; }
+    /* Perf — Safari especially. While the deck moves we collapse every effect that forces a
+       per-frame re-rasterization of the large card subtree, so each panel caches as a flat
+       layer the GPU can translate cheaply. All effects return the moment motion stops.
+         • per-card glass backdrop-blur (cheap on Chrome, costly on Safari)
+         • the ~150 3D flip contexts (perspective + preserve-3d + backface-visibility) — the
+           real Safari cliff: Safari cannot flatten them and re-renders each context per frame.
+           Flattening to transform-style:flat keeps the correct face visible via
+           backface-visibility, with no flip glitch on settle.
+         • the sticky-nav backdrop-blur and the blend-mode grain overlay. */
+    html.deck-sliding .card-face,
+    html.deck-sliding .nav.scrolled { -webkit-backdrop-filter: none !important; backdrop-filter: none !important; }
+    html.deck-sliding .card { perspective: none !important; }
+    html.deck-sliding .card-inner { transform-style: flat !important; }
+    html.deck-sliding .grain { visibility: hidden; }
+    /* Pager dots + swipe hint — signal the deck is a swipeable two-panel carousel. */
+    .deck-dots { display: inline-flex; align-items: center; gap: 7px; margin-left: 2px; }
+    .deck-dot { width: 8px; height: 8px; padding: 0; border: 0; border-radius: 999px; cursor: pointer;
+      background: var(--ink-3); opacity: 0.4; transition: width .25s var(--ease), opacity .2s, background .2s; }
+    .deck-dot:hover { opacity: 0.7; }
+    .deck-dot.active { width: 22px; opacity: 1; background: var(--accent); }
+    .deck-hint { display: inline-flex; align-items: center; gap: 6px; font-size: 0.74rem; color: var(--ink-3); white-space: nowrap; }
+    .deck-hint svg { width: 16px; height: 16px; opacity: 0.8; }
+    @media (max-width: 600px) { .deck-hint span { display: none; } }
+
+    /* ===================== Controls (search + sort) ===================== */
+    .controls { display: flex; gap: 12px; align-items: center; margin-bottom: 16px; flex-wrap: wrap; }
+    .search { flex: 1; min-width: 220px; padding: 13px 16px; border-radius: 13px; border: 1px solid var(--glass-border);
+      background: var(--chip-bg); color: var(--ink); font-size: 0.92rem; font-family: inherit; transition: border-color .18s, background .18s; }
+    .search::placeholder { color: var(--ink-3); }
+    .search:focus { outline: none; border-color: var(--accent); background: color-mix(in oklab, var(--accent) 8%, var(--chip-bg)); }
+    .sort-select { padding: 12px 14px; border-radius: 13px; border: 1px solid var(--glass-border); background: var(--chip-bg);
+      color: var(--ink); font-size: 0.86rem; font-family: inherit; font-weight: 500; cursor: pointer; transition: border-color .18s; }
+    .sort-select:focus { outline: none; border-color: var(--accent); }
+    .sort-select option { background: var(--bg-2); color: var(--ink); }
+
+    .public-panel-note { font-size: 0.82rem; color: var(--ink-3); margin-bottom: 14px; padding: 12px 15px; border-radius: 12px;
+      border: 1px solid var(--line); background: var(--chip-bg); max-width: 80ch; }
+
+    /* ===================== Filter chips ===================== */
+    .filter-row { display: flex; gap: 7px; flex-wrap: wrap; margin-bottom: 22px; }
+    .filter-btn { padding: 7px 14px; border-radius: 999px; border: 1px solid var(--line); background: var(--chip-bg);
+      color: var(--ink-2); font-size: 0.8rem; font-weight: 600; cursor: pointer; transition: color .15s, border-color .15s, background .15s; }
+    .filter-btn:hover { color: var(--ink); }
+    .filter-btn.active { color: var(--bg); background: var(--ink); border-color: var(--ink); }
+    [data-theme="light"] .filter-btn.active { color: #fff; }
+
+    /* ===================== Card grid + 3D flip cards ===================== */
+    /* Masonry: cards interlock into balanced columns so uneven heights fill the vertical
+       gaps — an abundant, staggered "琳琅满目" wall of CLIs rather than a ragged row grid.
+       Engine-independent JS masonry (layoutMasonry): a flex row of .grid-col wrappers,
+       each a vertical flex column; cards are distributed into the SHORTEST column as we go.
+       (CSS multicol balancing was buggy — Safari left empty tops in columns 2–3.)
+       max-width caps usable width because the deck-panel is intentionally over-wide for
+       the swipe carousel; columns land at ~3 across desktop / 2 tablet / 1 phone. */
+    /* Cap to the visible viewport (not the over-wide carousel panel) so the grid's own width
+       tracks the real screen — this lets masonryColumnCount pick 3/2/1 columns responsively. */
+    .grid { display: flex; align-items: flex-start; gap: 18px; max-width: min(1044px, calc(100vw - 108px)); padding-bottom: 24px; }
+    .grid-col { flex: 1 1 0; min-width: 0; display: flex; flex-direction: column; gap: 18px; }
+    /* the .empty / error state is a direct child of .grid (not wrapped in a column) */
+    .grid > .empty { flex: 1 1 100%; }
+
+    .card { perspective: 1600px; position: relative; }
+    .card-inner { position: absolute; inset: 0; width: 100%; height: 100%;
+      transform-style: preserve-3d; transition: transform .72s var(--flip-ease); }
+    .card.flipped .card-inner { transform: rotateY(180deg); }
+    /* subtle hover tilt hint (does not auto-flip) */
+    @media (hover: hover) {
+      .card:not(.flipped):hover .card-inner { transform: rotateY(-5deg) rotateX(2.5deg); }
+    }
+    .card-face {
+      position: absolute; inset: 0; display: flex; flex-direction: column;
+      -webkit-backface-visibility: hidden; backface-visibility: hidden;
+      border-radius: var(--radius); border: 1px solid var(--glass-border);
       background:
-        linear-gradient(180deg, rgba(255,255,255,0.02), rgba(255,255,255,0)),
-        var(--surface) url('data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 14 14"><path fill="%23a1a1aa" d="M7 10.2 2.8 6h8.4z"/></svg>') no-repeat right 0.85rem center;
-      border: 1px solid var(--border);
-      border-radius: 999px;
-      color: var(--text);
-      font-size: 0.9rem;
-      font-family: 'Inter', sans-serif;
-      font-weight: 600;
-      letter-spacing: -0.01em;
-      box-shadow: inset 0 1px 0 rgba(255,255,255,0.03);
-      outline: none;
-      cursor: pointer;
-      appearance: none;
-      -webkit-appearance: none;
-      transition: border-color 0.15s, box-shadow 0.15s, background-color 0.15s, transform 0.15s;
-    }
-
-    .sort-select:focus, .sort-select:hover {
-      border-color: var(--text-tertiary);
-      background-color: var(--surface-raised);
-      box-shadow: 0 0 0 3px rgba(59, 130, 246, 0.1);
-    }
-
-    [data-theme="light"] .sort-select {
-      background-image:
-        linear-gradient(180deg, rgba(255,255,255,0.5), rgba(255,255,255,0)),
-        url('data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 14 14"><path fill="%2352525b" d="M7 10.2 2.8 6h8.4z"/></svg>');
-    }
-
-    .filter-row {
-      display: flex;
-      gap: 0.45rem;
-      row-gap: 0.55rem;
-      flex-wrap: wrap;
-      margin: 0;
-      padding: 0.85rem 1.5rem 0;
-    }
-
-    .deck-panel--harness .filter-row {
-      margin-right: calc(var(--deck-peek) * 0.58);
-      padding-right: 1.5rem;
-    }
-
-    .filter-row::-webkit-scrollbar { display: none; }
-
-    .filter-btn {
-      padding: 0.3rem 0.7rem;
-      background: transparent;
-      border: 1px solid var(--border);
-      border-radius: 999px;
-      color: var(--text-tertiary);
-      font-size: 0.8rem;
-      font-family: 'Inter', sans-serif;
-      font-weight: 500;
-      cursor: pointer;
-      transition: all 0.15s;
-      white-space: nowrap;
-      flex-shrink: 0;
-    }
-
-    .filter-btn:hover { border-color: var(--text-tertiary); color: var(--text-secondary); }
-    .filter-btn.active {
-      background: var(--text);
-      color: var(--bg);
-      border-color: var(--text);
-      font-weight: 600;
-    }
-
-    /* ── Grid ── */
-    .grid {
-      margin: 1.25rem 0 4rem;
-      padding: 0 1.5rem;
-      display: grid;
-      grid-template-columns: repeat(3, minmax(0, 1fr));
-      gap: 0.9rem;
-    }
-
-    .card {
-      background: var(--surface);
-      border: 1px solid var(--border);
-      border-radius: var(--radius);
-      padding: 1.25rem;
-      transition: border-color 0.15s;
-    }
-
-    .card:hover { border-color: var(--text-tertiary); }
-
-    .card-head {
-      display: flex;
-      align-items: flex-start;
-      justify-content: space-between;
-      margin-bottom: 0.4rem;
-      gap: 0.5rem;
-    }
-
-    .card-title {
-      font-size: 0.95rem;
-      font-weight: 600;
-      line-height: 1.3;
-    }
-
-    .card-title a {
-      color: var(--text);
-      text-decoration: none;
-      transition: color 0.15s;
-    }
-
-    .card-title a:hover { color: var(--accent); }
-
-    .card-title a svg {
-      width: 11px;
-      height: 11px;
-      margin-left: 3px;
-      vertical-align: middle;
-      opacity: 0;
-      transition: opacity 0.15s;
-    }
-
-    .card-title a:hover svg { opacity: 0.5; }
-
-    .card-meta {
-      display: flex;
-      align-items: center;
-      gap: 0.4rem;
-      flex-shrink: 0;
-    }
-
-    .card-version {
-      font-family: 'JetBrains Mono', monospace;
-      font-size: 0.7rem;
-      font-weight: 500;
-      color: var(--green);
-      background: var(--green-muted);
-      padding: 0.12rem 0.45rem;
-      border-radius: 999px;
-    }
-
-    .category-tag {
-      font-size: 0.7rem;
-      font-weight: 500;
-      color: var(--text-tertiary);
-      background: var(--surface-raised);
-      padding: 0.12rem 0.45rem;
-      border-radius: 999px;
-      border: 1px solid var(--border);
-    }
-
-    .card-desc {
-      color: var(--text-secondary);
-      font-size: 0.85rem;
-      margin-bottom: 0.85rem;
-      line-height: 1.55;
-    }
-
-    .card-requires {
-      font-size: 0.78rem;
-      color: var(--text-tertiary);
-      margin-bottom: 0.75rem;
-    }
-
-    .card-requires strong {
-      color: var(--text-secondary);
-      font-weight: 500;
-    }
-
-    .card-install {
-      background: var(--bg);
-      border: 1px solid var(--border);
-      border-radius: var(--radius-sm);
-      padding: 0.8rem 0.9rem 0.8rem 0.9rem;
-      position: relative;
-      margin-bottom: 0.75rem;
-    }
-
-    .card-install--note {
-      justify-content: flex-start;
-    }
-
-    .card-install code {
-      font-family: 'JetBrains Mono', monospace;
-      font-size: 0.75rem;
-      color: var(--text-secondary);
-      white-space: pre-wrap;
-      overflow-wrap: break-word;
-      word-break: normal;
-      line-height: 1.45;
-      display: block;
-      padding-top: 0.1rem;
-    }
-
-    .card-install code .install-comment {
-      display: block;
-      color: var(--text-tertiary);
-      font-style: italic;
-      margin-bottom: 0.22rem;
-      padding-right: 4.8rem;
-    }
-
-    .card-install code .install-command {
-      display: block;
-    }
-
-    .card-install code .install-command + .install-comment {
-      margin-top: 0.38rem;
-    }
-
-    .card-copy-btn {
-      background: none;
-      border: 1px solid var(--border);
-      border-radius: 4px;
-      color: var(--text-tertiary);
-      cursor: pointer;
-      padding: 0.2rem 0.45rem;
-      font-size: 0.7rem;
-      font-family: 'Inter', sans-serif;
-      transition: all 0.15s;
-      white-space: nowrap;
-    }
-
-    .card-install .card-copy-btn {
-      position: absolute;
-      top: 0.78rem;
-      right: 0.72rem;
-    }
-
-    .card-copy-btn:hover { color: var(--text); border-color: var(--text-tertiary); }
-
-    .card-footer {
-      display: flex;
-      align-items: center;
-      justify-content: space-between;
-      gap: 0.5rem;
-      margin-top: 0.85rem;
-      padding-top: 0.8rem;
-      border-top: 1px solid var(--border-subtle);
-      flex-wrap: wrap;
-    }
-
-    .card-links {
-      display: flex;
-      gap: 0.6rem;
-      font-size: 0.78rem;
-      flex-wrap: wrap;
-      align-items: center;
-    }
-
-    .card-links a,
-    .card-link-btn {
-      color: var(--text-tertiary);
-      text-decoration: none;
-      font-weight: 500;
-      transition: color 0.15s;
-    }
-
-    .card-link-btn {
-      background: none;
-      border: 0;
-      cursor: pointer;
-      font: inherit;
-      padding: 0;
-    }
-
-    .card-links a:hover,
-    .card-link-btn:hover { color: var(--text-secondary); }
-
-    .skill-popover {
-      position: relative;
-      display: inline-flex;
-      align-items: center;
-    }
-
-    .skill-popover-panel {
-      position: absolute;
-      left: 0;
-      top: calc(100% + 0.45rem);
-      width: min(18rem, calc(100vw - 3rem));
-      padding: 0.7rem;
-      border-radius: 10px;
-      border: 1px solid rgba(148, 163, 184, 0.36);
-      background: rgba(248, 250, 252, 0.98);
-      color: #0f172a;
-      box-shadow: 0 16px 32px rgba(15, 23, 42, 0.24);
-      opacity: 0;
-      transform: translateY(-4px);
-      pointer-events: none;
-      transition: opacity 0.16s ease, transform 0.16s ease;
-      z-index: 10;
-    }
-
-    .skill-popover.is-open .skill-popover-panel {
-      opacity: 1;
-      transform: translateY(0);
-      pointer-events: auto;
-    }
-
-    .skill-popover-label {
-      display: block;
-      font-size: 0.64rem;
-      font-weight: 700;
-      letter-spacing: 0.08em;
-      text-transform: uppercase;
-      color: #475569;
-      margin-bottom: 0.45rem;
-    }
-
-    .skill-popover-panel code {
-      display: block;
-      font-size: 0.75rem;
-      line-height: 1.55;
-      white-space: pre-wrap;
-      overflow-wrap: anywhere;
-      word-break: break-word;
-      font-family: 'JetBrains Mono', monospace;
-      background: rgba(226, 232, 240, 0.7);
-      border: 1px solid rgba(148, 163, 184, 0.3);
-      border-radius: 8px;
-      padding: 0.55rem 0.6rem;
-    }
-
-    .skill-popover-copy {
-      margin-top: 0.55rem;
-      color: #334155;
-      border-color: rgba(100, 116, 139, 0.34);
-      background: rgba(255, 255, 255, 0.72);
-    }
-
-    .skill-popover-copy:hover {
-      color: #0f172a;
-      border-color: rgba(51, 65, 85, 0.42);
-    }
-
-    .card-contributor {
-      font-size: 0.75rem;
-      color: var(--text-tertiary);
-      display: flex;
-      align-items: center;
-      gap: 0.3rem;
-      flex-wrap: wrap;
-    }
-
-    .card-contributor a {
-      color: var(--text-secondary);
-      text-decoration: none;
-      font-weight: 500;
-    }
-
-    .card-contributor a:hover { color: var(--text); }
-
-    .community-badge {
-      font-size: 0.65rem;
-      font-weight: 600;
-      color: var(--purple);
-      background: var(--purple-muted);
-      padding: 0.08rem 0.35rem;
-      border-radius: 999px;
-    }
-
-    .card-date {
-      font-size: 0.72rem;
-      color: var(--text-tertiary);
-      margin-bottom: 0.75rem;
-    }
-
-    .public-badge {
-      font-size: 0.65rem;
-      font-weight: 600;
-      color: var(--text-tertiary);
-      background: var(--surface-raised);
-      border: 1px solid var(--border);
-      padding: 0.08rem 0.35rem;
-      border-radius: 999px;
-    }
-
-    .public-badge--npm {
-      color: #cb3837;
-      background: rgba(203, 56, 55, 0.1);
-      border-color: rgba(203, 56, 55, 0.14);
-    }
-
-    .public-badge--brew {
-      color: #8b5cf6;
-      background: rgba(139, 92, 246, 0.1);
-      border-color: rgba(139, 92, 246, 0.14);
-    }
-
-    .public-badge--bundled {
-      color: #64748b;
-      background: rgba(100, 116, 139, 0.1);
-      border-color: rgba(100, 116, 139, 0.14);
-    }
-
-    .card-public-notes {
-      display: grid;
-      gap: 0.45rem;
-      margin-top: 0.2rem;
-      margin-bottom: 0.1rem;
-      padding: 0.7rem 0.75rem;
-      background: var(--surface);
-      border: 1px solid var(--border-subtle);
-      border-radius: var(--radius-sm);
-    }
-
-    .card-npx {
-      font-size: 0.75rem;
-      color: var(--text-tertiary);
-      padding: 0.55rem 0.65rem;
-      background: var(--bg);
-      border: 1px solid var(--border);
-      border-radius: calc(var(--radius-sm) - 2px);
-      line-height: 1.55;
-    }
-
-    .card-npx--direct {
-      display: flex;
-      align-items: flex-start;
-      gap: 0.38rem;
-      background: transparent;
-      border: 0;
-      border-left: 2px solid var(--border);
-      border-radius: 0;
-      padding: 0.05rem 0 0.05rem 0.7rem;
-    }
-
-    .card-npx--direct strong {
-      color: var(--text-secondary);
-      font-weight: 500;
-      white-space: nowrap;
-    }
-
-    .card-npx--direct span {
-      color: var(--text-tertiary);
-      overflow-wrap: anywhere;
-      word-break: break-word;
-    }
-
-    .card-npx--comment {
-      background: transparent;
-      border: 0;
-      border-left: 2px solid var(--border-subtle);
-      border-radius: 0;
-      padding: 0.05rem 0 0.05rem 0.7rem;
-      color: var(--text-secondary);
-    }
-
-    .card-npx code {
-      font-family: 'JetBrains Mono', monospace;
-      color: var(--text-secondary);
-      font-size: 0.73rem;
-      display: inline-block;
-      margin-top: 0.25rem;
-      overflow-wrap: anywhere;
-      word-break: break-word;
-    }
-
-    .public-panel-note {
-      padding: 0.75rem 1.5rem 0;
-      font-size: 0.74rem;
-      color: var(--text-tertiary);
-      line-height: 1.5;
-    }
-
-    .public-panel-note code {
-      font-family: 'JetBrains Mono', monospace;
-      font-size: 0.72rem;
-      color: var(--text-secondary);
-    }
-
-    .empty {
-      grid-column: 1 / -1;
-      text-align: center;
-      padding: 3rem;
-      color: var(--text-tertiary);
-      font-size: 0.9rem;
-    }
-
-    /* ── Footer ── */
-    .footer {
-      max-width: 1120px;
-      margin: 0 auto;
-      padding: 1.05rem 1.5rem 1rem;
-      border-top: 1px solid var(--border-subtle);
-      display: flex;
-      justify-content: space-between;
-      align-items: center;
-      flex-wrap: wrap;
-      gap: 0.52rem 1rem;
-    }
-
-    .footer-left {
-      flex: 1 1 620px;
-      font-size: 0.8rem;
-      color: var(--text-tertiary);
-      line-height: 1.45;
-    }
-
-    .footer-left a {
-      color: var(--text-secondary);
-      text-decoration: none;
-      font-weight: 500;
-    }
-
-    .footer-left a:hover { color: var(--text); }
-
-    .footer-right {
-      display: flex;
-      gap: 1rem;
-      font-size: 0.8rem;
-    }
-
-    .footer-right a {
-      color: var(--text-tertiary);
-      text-decoration: none;
-      font-weight: 500;
-      transition: color 0.15s;
-    }
-
-    .footer-right a:hover { color: var(--text-secondary); }
-
-    .footer-stats {
-      width: 100%;
-      display: flex;
-      justify-content: flex-start;
-      padding-top: 0.42rem;
-      margin-top: 0.02rem;
-      border-top: 1px solid var(--border-subtle);
-    }
-
-    .analytics-report {
-      width: 100%;
-      min-height: 1.35rem;
-      padding: 0.08rem 0 0;
-      border: 0;
-      background: transparent;
-      display: flex;
-      align-items: baseline;
-      justify-content: flex-start;
-      flex-wrap: wrap;
-      gap: 0.24rem 0.72rem;
-      font-family: -apple-system, BlinkMacSystemFont, "SF Pro Text", "Helvetica Neue", Inter, sans-serif;
-    }
-
-    :root[data-theme="light"] .analytics-report {
-      background: transparent;
-    }
-
-    .analytics-kicker,
-    .analytics-row,
-    .analytics-key,
-    .analytics-pair {
-      display: inline-flex;
-      align-items: center;
-      min-width: 0;
-      white-space: nowrap;
-    }
-
-    .analytics-kicker {
-      font-size: 0.65rem;
-      font-weight: 600;
-      letter-spacing: 0.12em;
-      text-transform: uppercase;
-      color: var(--text-tertiary);
-      margin-right: 0.05rem;
-    }
-
-    .analytics-row {
-      gap: 0.38rem;
-      font-size: 0.74rem;
-      color: var(--text-tertiary);
-    }
-
-    .analytics-key {
-      font-size: 0.68rem;
-      color: var(--text-tertiary);
-      font-variant-numeric: tabular-nums;
-    }
-
-    .analytics-title {
-      color: var(--text-secondary);
-      font-weight: 600;
-    }
-
-    .analytics-total,
-    .analytics-pair strong {
-      color: var(--text);
-      font-size: 0.84rem;
-      font-weight: 650;
-      font-variant-numeric: tabular-nums;
-      letter-spacing: -0.018em;
-    }
-
-    .analytics-pair {
-      gap: 0.18rem;
-      color: var(--text-tertiary);
-    }
-
-    .analytics-pair .human-value,
-    .analytics-pair .agent-value {
-      color: var(--text);
-    }
-
-    .analytics-divider {
-      width: 1px;
-      height: 0.78rem;
-      background: var(--border-subtle);
-      flex: 0 0 auto;
-      transform: translateY(0.12rem);
-    }
-
-    /* ── Responsive ── */
-    @media (max-width: 640px) {
-      .deck-stage { --deck-peek: 46px; }
-      .hero { padding: 2rem 1.25rem 1.5rem; }
-      .hero h1 { font-size: 2rem; }
-      .hero-title {
-        gap: 0.72rem;
-        align-items: flex-start;
-      }
-      .hero-title-badge {
-        width: 2.7rem;
-        height: 2.7rem;
-        border-radius: 11px;
-      }
-      .hero-title-badge svg {
-        width: 1.84rem;
-        height: 1.84rem;
-      }
-      .stats {
-        display: flex;
-        width: 100%;
-        justify-content: center;
-        gap: 0;
-      }
-      .stat {
-        min-width: 0;
-        flex: 1;
-        padding: 0 1rem;
-      }
-      .stat + .stat::before {
-        top: 0.1rem;
-        bottom: 0.1rem;
-      }
-      .stat-num {
-        font-size: 2.2rem;
-      }
-      .hero-tagline { white-space: normal; }
-      .grid { grid-template-columns: 1fr; padding: 0 1.25rem; }
-      .controls { padding: 1rem 1.25rem 0; }
-      .filter-row {
-        gap: 0.4rem;
-        row-gap: 0.5rem;
-        padding: 0.75rem 1.25rem 0;
-      }
-      .public-panel-note { padding: 0.7rem 1.25rem 0; }
-      .deck-panel--harness .filter-row {
-        margin-right: calc(var(--deck-peek) * 0.5);
-        padding-right: 1.25rem;
-      }
-      .marketplace-prelude { padding: 0.75rem 1.25rem 0; }
-      .nav { padding: 0.75rem 1.25rem; }
-      .footer { padding: 1.1rem 1.25rem; align-items: flex-start; }
-      .footer-stats { justify-content: flex-start; }
-      .analytics-report {
-        justify-content: flex-start;
-      }
-      .empower-row { flex-direction: column; }
-      .empower-card { margin: 0 0 1rem; padding: 1.25rem; }
-      .typing-shell { padding: 0.72rem 0.78rem 0.8rem; }
-      .typing-shell-head { align-items: flex-start; }
-      .typing-shell-body { padding: 0.72rem 0.74rem; }
-      .typing-shell-code { font-size: 0.74rem; }
-      .empower-self .cmd-grid { grid-template-columns: 1fr; }
-      .deck-nav { padding: 1.25rem 1.25rem 0; }
-      .deck-arrow-btn span { display: none; }
-    }
-
-    @media (max-width: 1120px) {
-      .grid {
-        grid-template-columns: repeat(2, minmax(0, 1fr));
-      }
-    }
-
-    @media (max-width: 400px) {
-      .nav-links { gap: 0; }
-      .nav-link { padding: 0.4rem 0.4rem; font-size: 0.75rem; }
-    }
+        radial-gradient(120% 90% at 0% 0%, hsl(var(--ch, var(--hue-default)) var(--tint-s) var(--tint-l) / 0.16), transparent 56%),
+        var(--glass-bg-fallback);
+      box-shadow: var(--glass-shadow); overflow: hidden;
+    }
+    @supports ((backdrop-filter: blur(1px)) or (-webkit-backdrop-filter: blur(1px))) {
+      .card-face { background:
+        radial-gradient(120% 90% at 0% 0%, hsl(var(--ch, var(--hue-default)) var(--tint-s) var(--tint-l) / 0.18), transparent 56%),
+        var(--glass-bg);
+        -webkit-backdrop-filter: blur(18px) saturate(1.4); backdrop-filter: blur(18px) saturate(1.4); }
+    }
+    .card-face::before { content: ''; position: absolute; inset: 0; border-radius: inherit; pointer-events: none;
+      box-shadow: inset 0 1px 0 var(--glass-edge); z-index: 3; }
+    .card-front { padding: 18px 19px; }
+    .card-back { transform: rotateY(180deg); padding: 16px 17px; }
+
+    /* content-sized: .card-sizer is in normal flow and its height follows the FRONT face
+       only (the back is taken out of flow), so the card fits its compact front content
+       with no empty bottom gap. .card-inner overlays absolutely on top for the real 3D
+       flip; when flipped, the back fills that same height and scrolls internally. */
+    .card-sizer { position: relative; width: 100%; }
+    .card-sizer .card-face { position: relative; box-shadow: none; border: 1px solid transparent; background: none; visibility: hidden;
+      -webkit-backdrop-filter: none; backdrop-filter: none; }
+    .card-sizer .card-back { position: absolute; inset: 0; transform: none; }
+
+    /* FRONT face content */
+    .card-head { display: flex; align-items: flex-start; gap: 10px; }
+    .card-title { font-size: 1.04rem; font-weight: 700; flex: 1; min-width: 0; line-height: 1.25; }
+    .card-title a { text-decoration: none; color: var(--ink); display: inline-flex; align-items: center; gap: 5px; }
+    .card-title a:hover { color: var(--accent-ink); }
+    .card-title svg { width: 12px; height: 12px; flex-shrink: 0; opacity: 0.65; }
+    .card-meta { display: flex; flex-direction: column; align-items: flex-end; gap: 5px; flex-shrink: 0; }
+    .category-tag { font-size: 0.62rem; font-weight: 700; letter-spacing: 0.05em; text-transform: uppercase; padding: 3px 8px; border-radius: 7px;
+      color: hsl(var(--ch, var(--hue-default)) 80% 76%); background: hsl(var(--ch, var(--hue-default)) var(--tint-s) var(--tint-l) / 0.16);
+      border: 1px solid hsl(var(--ch, var(--hue-default)) 70% 64% / 0.32); white-space: nowrap; }
+    [data-theme="light"] .category-tag { color: hsl(var(--ch, var(--hue-default)) 72% 38%); }
+    .card-version { font-family: 'JetBrains Mono', monospace; font-size: 0.66rem; color: var(--ink-3); font-weight: 500; }
+    .public-badge { font-size: 0.6rem; font-weight: 700; letter-spacing: 0.05em; text-transform: uppercase; padding: 3px 7px; border-radius: 6px;
+      border: 1px solid var(--line); background: var(--chip-bg); color: var(--ink-2); white-space: nowrap; }
+    .public-badge--npm { color: #d98a4a; border-color: #d98a4a55; }
+    .public-badge--brew { color: #c79cff; border-color: #c79cff55; }
+    .public-badge--bundled { color: var(--ink-3); }
+    .card-desc { color: var(--ink-2); font-size: 0.86rem; margin-top: 11px;
+      display: -webkit-box; -webkit-line-clamp: 3; -webkit-box-orient: vertical; overflow: hidden; }
+    .card-date { font-size: 0.72rem; color: var(--ink-3); margin-top: 10px; }
+    .card-requires { font-size: 0.76rem; color: var(--ink-2); margin-top: 8px; }
+    .card-requires strong { color: var(--ink); font-weight: 700; }
+
+    /* install block (used on both faces where applicable) */
+    .card-install { display: flex; align-items: stretch; gap: 0; margin-top: 8px; border-radius: 11px; overflow: hidden;
+      border: 1px solid var(--cmd-line); background: var(--cmd-bg); }
+    .card-install code { font-family: 'JetBrains Mono', monospace; font-size: 0.74rem; color: var(--ink); padding: 9px 11px;
+      flex: 1; min-width: 0; overflow: hidden; display: flex; flex-direction: column; gap: 3px; }
+    /* Each command renders on exactly ONE line; long lines truncate with an ellipsis.
+       The full, untruncated text is preserved in the Copy payload (display only). */
+    .card-install .install-command { color: var(--accent-ink); display: block; min-width: 0; line-height: 1.5;
+      white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+    .card-install--note code { color: var(--ink-3); display: block; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+    /* two-step install: a short plain-language label above the clean command box */
+    .install-steps { margin-top: 14px; }
+    .install-steps-label { display: flex; align-items: center; gap: 7px; font-size: 0.7rem; font-weight: 600; color: var(--ink-3);
+      letter-spacing: 0.01em; margin-bottom: 5px; }
+    .install-steps-label .isl-num { display: inline-grid; place-items: center; width: 15px; height: 15px; border-radius: 5px; flex-shrink: 0;
+      font-family: 'JetBrains Mono', monospace; font-size: 0.6rem; font-weight: 700; color: var(--accent-ink);
+      background: hsl(var(--ch, var(--hue-default)) var(--tint-s) var(--tint-l) / 0.16); border: 1px solid hsl(var(--ch, var(--hue-default)) var(--tint-s) 60% / 0.3); }
+    .install-steps-label .isl-sep { color: var(--ink-3); opacity: 0.55; }
+    .card-copy-btn { border: 0; border-left: 1px solid var(--cmd-line); background: var(--chip-bg); color: var(--ink-2);
+      padding: 0 13px; cursor: pointer; font-size: 0.72rem; font-weight: 600; white-space: nowrap; transition: color .18s, background .18s; align-self: stretch; }
+    .card-copy-btn:hover { color: var(--ink); background: color-mix(in oklab, var(--accent) 18%, transparent); }
+
+    .card-public-notes { margin-top: 10px; display: flex; flex-direction: column; gap: 8px; }
+    .card-npx { font-size: 0.76rem; color: var(--ink-2); }
+    .card-npx--direct strong { color: var(--ink); font-weight: 700; display: block; margin-bottom: 2px; }
+    .card-npx--direct span { font-family: 'JetBrains Mono', monospace; font-size: 0.72rem; color: var(--accent-ink); word-break: break-all; }
+    .card-npx--comment { padding-left: 11px; border-left: 2px solid var(--line); color: var(--ink-3); }
+
+    .card-footer { margin-top: auto; padding-top: 14px; display: flex; align-items: center; justify-content: space-between; gap: 10px; flex-wrap: wrap; }
+    .card-links { display: flex; align-items: center; gap: 4px; font-size: 0.78rem; color: var(--ink-3); }
+    .card-links a { color: var(--accent-ink); text-decoration: none; font-weight: 600; }
+    .card-links a:hover { text-decoration: underline; }
+    .card-contributor { font-size: 0.76rem; color: var(--ink-3); display: inline-flex; align-items: center; gap: 6px; flex-wrap: wrap; }
+    .card-contributor a { color: var(--ink-2); text-decoration: none; font-weight: 500; }
+    .card-contributor a:hover { color: var(--ink); text-decoration: underline; }
+    .community-badge { font-size: 0.58rem; font-weight: 700; letter-spacing: 0.04em; text-transform: uppercase; padding: 2px 6px; border-radius: 5px;
+      color: var(--ok); border: 1px solid color-mix(in oklab, var(--ok) 45%, transparent); background: color-mix(in oklab, var(--ok) 14%, transparent); }
+
+    /* flip affordance — a clear "Details" / "Back" pill (NOT a refresh glyph) */
+    .card-front-foot { margin-top: 14px; padding-top: 13px; display: flex; align-items: center; justify-content: space-between; gap: 10px; }
+    .flip-btn { display: inline-flex; align-items: center; gap: 6px; padding: 6px 12px; border-radius: 10px; cursor: pointer;
+      border: 1px solid var(--glass-border); background: var(--chip-bg); color: var(--ink-2); font-size: 0.76rem; font-weight: 600;
+      font-family: inherit; transition: color .18s, border-color .18s, background .18s, transform .15s; flex-shrink: 0; }
+    .flip-btn:hover { color: var(--ink); border-color: hsl(var(--ch, var(--hue-default)) 70% 64% / 0.6);
+      background: hsl(var(--ch, var(--hue-default)) var(--tint-s) var(--tint-l) / 0.14); transform: translateY(-1px); }
+    .flip-btn:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; }
+    .flip-btn svg { width: 14px; height: 14px; flex-shrink: 0; }
+    .flip-btn--back svg { transform: scaleX(-1); }
+    .flip-hint { font-size: 0.7rem; color: var(--ink-3); font-weight: 600; }
+
+    /* ===================== Software icons (Simple Icons) ===================== */
+    /* Unified rounded tile; the <img> is the single-color Simple Icons SVG tinted to the
+       palette ink; the .icon-mono fallback is a tasteful single-letter monogram. */
+    .sw-icon { display: inline-grid; place-items: center; width: 26px; height: 26px; border-radius: 8px; flex-shrink: 0;
+      background: hsl(var(--ch, var(--hue-default)) var(--tint-s) var(--tint-l) / 0.14);
+      border: 1px solid hsl(var(--ch, var(--hue-default)) var(--tint-s) 60% / 0.28); overflow: hidden; }
+    .sw-icon img { width: 15px; height: 15px; object-fit: contain; display: block;
+      /* Simple Icons are single-color SVGs; flatten them to a cohesive monochrome glyph that
+         stays legible in both themes (near-white on dark, near-ink on light). */
+      filter: var(--icon-tint); }
+    /* Favicon-sourced logos (apps Simple Icons lacks) keep their real colour — no monochrome
+       flatten — and sit a touch larger since they're already a rounded glyph. */
+    .sw-icon img.raw { filter: none; width: 18px; height: 18px; border-radius: 4px; }
+    .sw-icon .icon-mono { font-family: 'Hanken Grotesk', sans-serif; font-size: 0.8rem; font-weight: 700; line-height: 1;
+      color: hsl(var(--ch, var(--hue-default)) 70% 70%); text-transform: uppercase; }
+    [data-theme="light"] .sw-icon .icon-mono { color: hsl(var(--ch, var(--hue-default)) calc(var(--tint-s) + 14%) 40%); }
+    /* dark theme: glyph → light ink; light theme: glyph → dark ink. brightness(0) flattens any
+       source color to black, then invert/opacity lifts it to the right tone for the theme. */
+    :root { --icon-tint: brightness(0) invert(1) opacity(0.86); }
+    [data-theme="light"] { --icon-tint: brightness(0) invert(0.18) opacity(0.92); }
+    /* a row of stacked member icons on matrix cards */
+    .icon-stack { display: flex; margin-top: 14px; align-items: center; }
+    .icon-stack .sw-icon { margin-left: -8px; box-shadow: 0 2px 6px rgba(0,0,0,0.25); background:
+      radial-gradient(120% 120% at 30% 25%, hsl(var(--ch, var(--hue-default)) var(--tint-s) var(--tint-l) / 0.2), var(--surface)); }
+    .icon-stack .sw-icon:first-child { margin-left: 0; }
+    .icon-stack .sw-icon.miss { opacity: 0.6; }
+    .icon-stack .more { font-size: 0.72rem; color: var(--ink-3); margin-left: 9px; }
+    /* small icon beside a card / matrix title */
+    .title-icon { width: 22px; height: 22px; border-radius: 7px; }
+    .title-icon img { width: 13px; height: 13px; }
+    .title-icon .icon-mono { font-size: 0.66rem; }
+    .card-title-row { display: inline-flex; align-items: center; gap: 8px; min-width: 0; }
+
+    /* back face */
+    .card-back-head { display: flex; align-items: center; justify-content: space-between; gap: 8px; margin-bottom: 10px; }
+    .card-back-title { font-size: 0.7rem; font-weight: 700; letter-spacing: 0.12em; text-transform: uppercase; color: var(--ink-3); }
+    .card-back-scroll { flex: 1; min-height: 0; overflow-y: auto; padding-right: 4px; }
+    .card-back-scroll::-webkit-scrollbar { width: 7px; }
+    .card-back-scroll::-webkit-scrollbar-track { background: transparent; }
+    .card-back-scroll::-webkit-scrollbar-thumb { background: var(--line); border-radius: 6px; }
+    .card-back-scroll::-webkit-scrollbar-thumb:hover { background: var(--ink-3); }
+    .card-back-scroll { scrollbar-width: thin; scrollbar-color: var(--line) transparent; }
+    .card-back-field { margin-top: 12px; }
+    .card-back-field:first-child { margin-top: 0; }
+    .card-back-label { font-size: 0.64rem; font-weight: 700; letter-spacing: 0.08em; text-transform: uppercase; color: var(--ink-3); margin-bottom: 5px; }
+
+    /* a face hidden from a11y/tab when not active */
+    .card:not(.flipped) .card-back :is(a,button,input,select,[tabindex]),
+    .card.flipped .card-front :is(a,button,input,select,[tabindex]) { /* aria-hidden handled via attr; this is style fallback */ }
+
+    .empty { grid-column: 1 / -1; text-align: center; padding: 56px 20px; color: var(--ink-3); }
+    .empty a { color: var(--accent); }
+    .skeleton { border-radius: var(--radius); min-height: 300px; background: var(--chip-bg); animation: shimmerSk 1.6s var(--ease) infinite; }
+    @keyframes shimmerSk { 0%,100%{opacity:.5} 50%{opacity:1} }
+
+    /* skill popover (public cards) */
+    .skill-popover { position: relative; display: inline-block; }
+    .card-link-btn { border: 0; background: transparent; color: var(--accent-ink); font-size: 0.78rem; font-weight: 600;
+      font-family: inherit; cursor: pointer; padding: 0; }
+    .card-link-btn:hover { text-decoration: underline; }
+    .skill-popover-panel { position: absolute; bottom: calc(100% + 8px); left: 50%; transform: translateX(-50%) translateY(6px);
+      min-width: 240px; max-width: 320px; padding: 12px; border-radius: 12px; border: 1px solid var(--glass-border);
+      background: var(--glass-bg-fallback); box-shadow: var(--glass-shadow-hi); z-index: 20;
+      opacity: 0; pointer-events: none; transition: opacity .2s, transform .2s; display: flex; flex-direction: column; gap: 8px; }
+    @supports ((backdrop-filter: blur(1px)) or (-webkit-backdrop-filter: blur(1px))) {
+      .skill-popover-panel { background: var(--glass-bg); -webkit-backdrop-filter: blur(20px) saturate(1.5); backdrop-filter: blur(20px) saturate(1.5); }
+    }
+    .skill-popover.is-open .skill-popover-panel { opacity: 1; pointer-events: auto; transform: translateX(-50%); }
+    .skill-popover-label { font-size: 0.62rem; font-weight: 700; letter-spacing: 0.1em; text-transform: uppercase; color: var(--ink-3); }
+    .skill-popover-panel code { font-family: 'JetBrains Mono', monospace; font-size: 0.7rem; color: var(--accent-ink); word-break: break-all;
+      padding: 8px 10px; border-radius: 8px; background: var(--cmd-bg); border: 1px solid var(--cmd-line); display: block; }
+    .skill-popover-copy { align-self: flex-start; border: 1px solid var(--cmd-line); border-radius: 8px; padding: 6px 12px; }
+    /* front-face Skill control: compact icon+label, sized like the flip pill (not oversized) */
+    .card-skill-front { display: inline-flex; align-items: center; gap: 6px; padding: 6px 11px; border-radius: 10px; cursor: pointer;
+      border: 1px solid var(--glass-border); background: var(--chip-bg); color: var(--accent-ink); font-size: 0.76rem; font-weight: 600;
+      font-family: inherit; text-decoration: none; transition: color .18s, border-color .18s, background .18s, transform .15s; flex-shrink: 0; }
+    .card-skill-front:hover { color: var(--ink); border-color: hsl(var(--ch, var(--hue-default)) 70% 64% / 0.6);
+      background: hsl(var(--ch, var(--hue-default)) var(--tint-s) var(--tint-l) / 0.14); transform: translateY(-1px); text-decoration: none; }
+    .card-skill-front:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; }
+    .card-skill-front svg { width: 14px; height: 14px; flex-shrink: 0; }
+
+    /* ===================== Matrices band ===================== */
+    .matrices { max-width: 1180px; margin: 0 auto; padding: 64px 22px 8px; }
+    .matrices-head { display: flex; align-items: flex-end; justify-content: space-between; gap: 16px; margin: 0 0 24px; flex-wrap: wrap; }
+    .matrices-head .klabel { font-size: 0.72rem; font-weight: 700; letter-spacing: 0.16em; text-transform: uppercase; color: var(--accent-ink); }
+    .matrices-head h2 { font-size: clamp(1.6rem, 4vw, 2.2rem); margin-top: 8px; }
+    .matrices-head p { color: var(--ink-2); max-width: 54ch; margin-top: 8px; font-size: 0.96rem; }
+    .matrices-head .mat-stat { font-family: 'JetBrains Mono', monospace; font-size: 0.78rem; color: var(--ink-3); white-space: nowrap; }
+
+    .shelf { display: grid; gap: 18px; grid-template-columns: repeat(auto-fill, minmax(330px, 1fr)); grid-auto-rows: 1fr; align-items: stretch; }
+    @media (min-width: 980px) { .shelf { grid-template-columns: repeat(3, 1fr); } }
+    @media (max-width: 760px) {
+      .shelf { display: flex; grid-auto-flow: column; overflow-x: auto; scroll-snap-type: x mandatory;
+        margin: 0 -22px; padding: 0 22px 12px; gap: 16px; }
+      .shelf > .mcard { flex: 0 0 84%; scroll-snap-align: center; }
+    }
+    /* matrix flip card — reuses .card / .card-inner / .card-face machinery, taller min-height */
+    .mcard { perspective: 1600px; min-height: 372px; position: relative; }
+    .mcard .card-inner { position: absolute; inset: 0; width: 100%; height: 100%;
+      transform-style: preserve-3d; transition: transform .72s var(--flip-ease); }
+    .mcard.flipped .card-inner { transform: rotateY(180deg); }
+    @media (hover: hover) { .mcard:not(.flipped):hover .card-inner { transform: rotateY(-4deg) rotateX(2deg); } }
+    .mcard .card-sizer { position: relative; width: 100%; min-height: inherit; }
+    .mcard .card-sizer .card-face { position: relative; box-shadow: none; border: 1px solid transparent; background: none; visibility: hidden;
+      -webkit-backdrop-filter: none; backdrop-filter: none; }
+    .mcard .card-sizer .card-back { position: absolute; inset: 0; transform: none; }
+
+    .mcard-top { display: flex; align-items: center; justify-content: space-between; gap: 10px; }
+    .mcard-glyph { width: 42px; height: 42px; border-radius: 13px; display: grid; place-items: center;
+      background: hsl(var(--ch, var(--hue-default)) var(--tint-s) var(--tint-l) / 0.18); border: 1px solid hsl(var(--ch, var(--hue-default)) var(--tint-s) 60% / 0.34); color: hsl(var(--ch, var(--hue-default)) var(--tint-s) 74%); }
+    [data-theme="light"] .mcard-glyph { color: hsl(var(--ch, var(--hue-default)) calc(var(--tint-s) + 14%) 38%); }
+    .mcard-glyph svg { width: 21px; height: 21px; }
+    .mcard h3 { font-size: 1.2rem; margin-top: 16px; }
+    .mcard .mdesc { color: var(--ink-2); font-size: 0.88rem; margin-top: 8px;
+      display: -webkit-box; -webkit-line-clamp: 3; -webkit-box-orient: vertical; overflow: hidden; }
+    .mcard .meta-row { display: flex; align-items: center; gap: 14px; margin-top: 14px; font-size: 0.8rem; color: var(--ink-3); }
+    .mcard .meta-row b { color: var(--ink); font-weight: 700; }
+    .avatars { display: flex; margin-top: 14px; align-items: center; }
+    .avatars .av { width: 30px; height: 30px; border-radius: 9px; margin-left: -7px; display: grid; place-items: center;
+      font-size: 0.6rem; font-weight: 700; background: var(--chip-bg); border: 1px solid var(--glass-border);
+      box-shadow: 0 2px 6px rgba(0,0,0,0.25); text-transform: uppercase; color: var(--ink-2); }
+    .avatars .av:first-child { margin-left: 0; }
+    .avatars .av.miss { opacity: 0.55; }
+    .avatars .more { font-size: 0.72rem; color: var(--ink-3); margin-left: 9px; }
+
+    /* matrix front: primary command + flip foot */
+    .mcard-front-foot { margin-top: auto; padding-top: 13px; display: flex; align-items: center; justify-content: space-between; gap: 10px; }
+
+    /* matrix back: scrolling detail */
+    .mback-scroll { flex: 1; min-height: 0; overflow-y: auto; padding-right: 5px; scrollbar-width: thin; scrollbar-color: var(--line) transparent; }
+    .mback-scroll::-webkit-scrollbar { width: 7px; }
+    .mback-scroll::-webkit-scrollbar-thumb { background: var(--line); border-radius: 6px; }
+    .msub { font-size: 0.62rem; font-weight: 700; letter-spacing: 0.1em; text-transform: uppercase; color: var(--ink-3); margin: 16px 0 8px; }
+    .msub:first-child { margin-top: 2px; }
+    .mcmd { display: flex; align-items: center; gap: 8px; background: var(--cmd-bg); border: 1px solid var(--cmd-line);
+      border-radius: 10px; padding: 8px 10px; margin-bottom: 7px; }
+    /* matrix commands stay on a single line; truncate with an ellipsis if they overflow
+       (Copy still copies the full command). */
+    .mcmd code { font-family: 'JetBrains Mono', monospace; font-size: 0.74rem; color: var(--ink); flex: 1; min-width: 0;
+      white-space: nowrap; overflow: hidden; text-overflow: ellipsis; line-height: 1.5; }
+    .mcmd code .pfx { color: var(--ink-3); }
+    .mcmd .card-copy-btn { border: 0; border-left: 1px solid var(--cmd-line); }
+
+    /* capability accordions */
+    .cap { border: 1px solid var(--line); border-radius: 11px; margin-bottom: 7px; overflow: hidden; background: var(--chip-bg); }
+    .cap > summary { list-style: none; cursor: pointer; padding: 10px 12px; display: flex; align-items: center; gap: 9px; }
+    .cap > summary::-webkit-details-marker { display: none; }
+    .cap > summary:focus-visible { outline: 2px solid var(--accent); outline-offset: -2px; border-radius: 10px; }
+    .cap .cap-id { font-family: 'JetBrains Mono', monospace; font-size: 0.66rem; color: hsl(var(--ch, var(--hue-default)) var(--tint-s) 74%); flex-shrink: 0;
+      background: hsl(var(--ch, var(--hue-default)) 50% 50% / 0.14); padding: 3px 6px; border-radius: 6px; }
+    [data-theme="light"] .cap .cap-id { color: hsl(var(--ch, var(--hue-default)) calc(var(--tint-s) + 14%) 38%); }
+    .cap .cap-title { font-weight: 600; font-size: 0.82rem; flex: 1; min-width: 0; }
+    .cap .chev { width: 14px; height: 14px; color: var(--ink-3); transition: transform .3s var(--ease); flex-shrink: 0; }
+    .cap[open] .chev { transform: rotate(90deg); }
+    .cap-detail { padding: 0 12px 12px; }
+    .cap-intent { color: var(--ink-2); font-size: 0.8rem; margin-bottom: 10px; }
+    .io { display: flex; flex-wrap: wrap; gap: 5px; margin-bottom: 10px; }
+    .io span { font-family: 'JetBrains Mono', monospace; font-size: 0.64rem; padding: 3px 7px; border-radius: 6px; background: var(--cmd-bg); color: var(--ink-2); border: 1px solid var(--cmd-line); }
+    .io span.out { color: hsl(var(--ch, var(--hue-default)) var(--tint-s) 70%); }
+    [data-theme="light"] .io span.out { color: hsl(var(--ch, var(--hue-default)) calc(var(--tint-s) + 12%) 40%); }
+    .prov { display: flex; gap: 9px; padding: 8px 0; border-top: 1px dashed var(--line); }
+    .prov:first-of-type { border-top: 0; }
+    .prov .pk { font-size: 0.58rem; font-weight: 700; letter-spacing: 0.04em; text-transform: uppercase; padding: 3px 6px; border-radius: 6px;
+      white-space: nowrap; height: fit-content; border: 1px solid; flex-shrink: 0; margin-top: 2px; }
+    .prov .pbody b { font-weight: 600; font-size: 0.8rem; }
+    .prov .pbody .pmeta { font-size: 0.7rem; color: var(--ink-3); margin-top: 1px; }
+    .prov .pbody .pnotes { font-size: 0.74rem; color: var(--ink-2); margin-top: 3px; }
+    /* provider-kind badges (cool/neutral) */
+    .pk-agentnative  { color: #54d196; border-color: #54d19655; background: #54d19614; }
+    .pk-publiccli    { color: var(--accent); border-color: rgba(var(--accent-rgb),.4); background: rgba(var(--accent-rgb),.10); }
+    .pk-harnesscli   { color: #9aa6ff; border-color: #9aa6ff55; background: #9aa6ff14; }
+    .pk-agentskill   { color: #5ad1d1; border-color: #5ad1d155; background: #5ad1d114; }
+    .pk-bundledscript{ color: #79c0e8; border-color: #79c0e855; background: #79c0e814; }
+    .pk-api          { color: #5ad1d1; border-color: #5ad1d155; background: #5ad1d114; }
+    .pk-native, .pk-python, .pk-websearch, .pk-fallback { color: var(--ink-2); border-color: var(--line); background: var(--chip-bg); }
+    [data-theme="light"] .pk-agentnative{color:#0f8a52} [data-theme="light"] .pk-harnesscli{color:#4350c0}
+    [data-theme="light"] .pk-agentskill{color:#127d7d} [data-theme="light"] .pk-bundledscript{color:#1f6fa0} [data-theme="light"] .pk-api{color:#127d7d}
+
+    .member { display: flex; flex-wrap: wrap; gap: 7px; }
+    .member button { display: inline-flex; align-items: center; gap: 6px; padding: 6px 10px; border-radius: 9px; cursor: pointer;
+      border: 1px solid var(--glass-border); background: var(--chip-bg); color: var(--ink); font-size: 0.78rem; font-weight: 500;
+      font-family: inherit; transition: border-color .18s, background .18s, transform .18s; }
+    .member button:hover { border-color: hsl(var(--ch, var(--hue-default)) var(--tint-s) 60% / 0.6); transform: translateY(-1px); }
+    .member button .badge-mini { font-size: 0.56rem; padding: 1px 5px; border-radius: 5px; background: var(--cmd-bg); color: var(--ink-3); text-transform: uppercase; letter-spacing: 0.04em; }
+    .member button.miss { opacity: 0.6; cursor: default; }
+    .mback-cta { display: flex; gap: 8px; flex-wrap: wrap; margin-top: 14px; }
+    .mbtn { display: inline-flex; align-items: center; gap: 7px; padding: 9px 13px; border-radius: 10px; font-weight: 600; font-size: 0.8rem;
+      text-decoration: none; cursor: pointer; border: 1px solid var(--glass-border); background: var(--chip-bg); color: var(--ink); font-family: inherit;
+      transition: border-color .18s, background .18s, transform .15s; }
+    .mbtn:hover { transform: translateY(-1px); border-color: var(--ink-3); }
+    .mbtn.primary { background: hsl(var(--ch, var(--hue-default)) var(--tint-s) var(--tint-l) / 0.2); border-color: hsl(var(--ch, var(--hue-default)) var(--tint-s) 60% / 0.5); }
+    .mbtn.primary:hover { background: hsl(var(--ch, var(--hue-default)) var(--tint-s) var(--tint-l) / 0.3); }
+    .mbtn svg { width: 14px; height: 14px; }
+
+    /* scope banner above the decks */
+    .scope-banner { display: none; align-items: center; gap: 12px; flex-wrap: wrap; padding: 12px 16px; margin: 0 22px 16px;
+      max-width: 1180px; margin-left: auto; margin-right: auto;
+      border-radius: 14px; border: 1px solid hsl(var(--ch, var(--hue-default)) var(--tint-s) 60% / 0.4); background: hsl(var(--ch, var(--hue-default)) var(--tint-s) var(--tint-l) / 0.12); }
+    .scope-banner.on { display: flex; }
+    .scope-banner .lbl { font-size: 0.86rem; }
+    .scope-banner b { font-weight: 700; }
+    .scope-banner .clear { margin-left: auto; border: 0; background: transparent; color: var(--ink-2); cursor: pointer; font-weight: 600;
+      font-size: 0.82rem; display: inline-flex; gap: 6px; align-items: center; padding: 5px 9px; border-radius: 9px; font-family: inherit; }
+    .scope-banner .clear:hover { background: var(--chip-bg); color: var(--ink); }
+
+    /* membership chip on catalog cards */
+    .in-matrix { display: inline-flex; align-items: center; gap: 5px; font-size: 0.68rem; font-weight: 600; padding: 4px 8px; border-radius: 8px;
+      border: 1px solid var(--line); background: var(--chip-bg); color: var(--ink-2); cursor: pointer; font-family: inherit; transition: color .15s, border-color .15s; }
+    .in-matrix:hover { color: var(--ink); border-color: var(--accent); }
+    .in-matrix .mid { font-family: 'JetBrains Mono', monospace; color: var(--accent-ink); }
+    .card.flash .card-face { animation: cardFlash 1.5s var(--ease); }
+    @keyframes cardFlash { 0%,12% { box-shadow: 0 0 0 2px var(--accent), var(--glass-shadow-hi); } 100% { box-shadow: var(--glass-shadow); } }
+
+    /* ===================== Footer ===================== */
+    .footer { border-top: 1px solid var(--line); margin-top: 56px; padding: 34px 22px 50px; max-width: 1180px; margin-left: auto; margin-right: auto;
+      display: flex; flex-wrap: wrap; gap: 18px 32px; align-items: center; justify-content: space-between; }
+    .footer-left, .footer-right { font-size: 0.84rem; color: var(--ink-3); }
+    .footer a { color: var(--accent-ink); text-decoration: none; font-weight: 600; }
+    .footer a:hover { text-decoration: underline; }
+    .footer-stats { width: 100%; margin-top: 6px; }
+    .analytics-report { display: inline-flex; align-items: center; gap: 14px; flex-wrap: wrap; padding: 10px 16px; border-radius: 13px;
+      border: 1px solid var(--line); background: var(--chip-bg); }
+    .analytics-kicker { font-size: 0.64rem; font-weight: 700; letter-spacing: 0.14em; text-transform: uppercase; color: var(--accent-ink); }
+    .analytics-row { display: inline-flex; align-items: baseline; gap: 8px; }
+    .analytics-title { font-size: 0.74rem; color: var(--ink-3); text-transform: uppercase; letter-spacing: 0.06em; font-weight: 600; }
+    .analytics-total { font-size: 1.02rem; font-weight: 800; font-variant-numeric: tabular-nums; }
+    .analytics-pair { font-size: 0.78rem; color: var(--ink-3); font-variant-numeric: tabular-nums; }
+    .analytics-pair .human-value { color: var(--ink-2); }
+    .analytics-pair .agent-value { color: var(--accent-ink); }
+    .analytics-divider { width: 1px; height: 18px; background: var(--line); }
 
     @media (prefers-reduced-motion: reduce) {
-      .hero-word,
-      .hero-tagline-line {
-        opacity: 1;
-        transform: none;
-      }
-
-      .hero-shimmer::after,
-      .hero-title-badge,
-      .hero-badge-glow,
-      .hero-badge-cursor,
-      .typing-shell-cursor {
-        animation: none !important;
-      }
-    }
+      * { animation-duration: 0.001ms !important; animation-iteration-count: 1 !important; scroll-behavior: auto !important; }
+      .reveal { opacity: 1; transform: none; transition: none; }
+      .card-inner { transition: opacity .2s ease !important; transform: none !important; }
+      /* Reduced-motion flip becomes an instant crossfade */
+      .card .card-front { opacity: 1; transition: opacity .2s ease; }
+      .card .card-back { opacity: 0; transition: opacity .2s ease; }
+      .card.flipped .card-front { opacity: 0; }
+      .card.flipped .card-back { opacity: 1; }
+      .card-face { -webkit-backface-visibility: visible; backface-visibility: visible; }
+      .card-back { transform: none; }
+      .card:hover .card-inner { transform: none !important; }
+      /* matrix flip cards: crossfade too */
+      .mcard .card-inner { transition: opacity .2s ease !important; transform: none !important; }
+      .mcard .card-front { opacity: 1; transition: opacity .2s ease; }
+      .mcard .card-back { opacity: 0; transition: opacity .2s ease; }
+      .mcard.flipped .card-front { opacity: 0; }
+      .mcard.flipped .card-back { opacity: 1; }
+      .mcard:hover .card-inner { transform: none !important; }
+    }
+
+    /* ===================== Real-World Demos — homepage teaser (full gallery on demos.html) ===================== */
+    .demos-teaser { max-width: 1180px; margin: 56px auto 0; padding: 0 22px; }
+    .dt-head { display: flex; align-items: flex-end; justify-content: space-between; gap: 16px; margin-bottom: 22px; flex-wrap: wrap; }
+    .dt-head .kl { font-size: 0.72rem; font-weight: 700; letter-spacing: 0.16em; text-transform: uppercase; color: var(--accent-ink); }
+    .dt-head h2 { font-size: clamp(1.6rem, 4vw, 2.2rem); margin-top: 8px; }
+    .dt-head p { color: var(--ink-2); max-width: 56ch; margin-top: 8px; font-size: 0.96rem; }
+    .dt-seeall { display: inline-flex; align-items: center; gap: 7px; font-weight: 700; font-size: 0.88rem; color: var(--accent-ink); text-decoration: none;
+      white-space: nowrap; padding: 9px 14px; border-radius: 11px; border: 1px solid var(--glass-border); background: var(--chip-bg); transition: border-color .18s, transform .18s; }
+    .dt-seeall:hover { border-color: var(--accent); transform: translateY(-1px); }
+    .dt-seeall svg { width: 16px; height: 16px; }
+    .demos-strip { display: grid; grid-template-columns: repeat(3, 1fr) auto; gap: 18px; align-items: stretch; }
+    @media (max-width: 900px) {
+      .demos-strip { grid-auto-flow: column; grid-template-columns: none; grid-auto-columns: 80%; overflow-x: auto;
+        scroll-snap-type: x mandatory; margin: 0 -22px; padding: 0 22px 12px; }
+      .demos-strip > * { scroll-snap-align: start; }
+    }
+    .dposter { display: flex; flex-direction: column; padding: 14px; border-radius: var(--radius); text-decoration: none; color: inherit;
+      background: var(--glass-bg-fallback); border: 1px solid var(--glass-border); box-shadow: var(--glass-shadow); position: relative; transition: transform .3s var(--ease), box-shadow .3s var(--ease); }
+    @supports ((backdrop-filter: blur(1px)) or (-webkit-backdrop-filter: blur(1px))) {
+      .dposter { background: var(--glass-bg); -webkit-backdrop-filter: blur(22px) saturate(1.5); backdrop-filter: blur(22px) saturate(1.5); } }
+    .dposter:hover { transform: translateY(-4px); box-shadow: var(--glass-shadow-hi); }
+    .dt-media { position: relative; border-radius: 13px; overflow: hidden; border: 1px solid var(--line); background: #05070b; }
+    [data-theme="light"] .dt-media { background: #e9edf3; }
+    .dt-chrome { display: flex; align-items: center; gap: 6px; padding: 7px 11px; background: var(--cmd-bg); border-bottom: 1px solid var(--cmd-line); }
+    .dt-chrome .dts { display: inline-flex; gap: 4px; }
+    .dt-chrome .dts i { width: 8px; height: 8px; border-radius: 50%; }
+    .dt-chrome .dts i:nth-child(1){ background: hsl(8 60% 60%); } .dt-chrome .dts i:nth-child(2){ background: hsl(45 70% 58%); } .dt-chrome .dts i:nth-child(3){ background: hsl(140 45% 55%); }
+    .dt-chrome .u { font-family: 'JetBrains Mono', monospace; font-size: 0.62rem; color: var(--ink-3); flex: 1; min-width: 0; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+    .dt-chrome .lv { display: inline-flex; align-items: center; gap: 4px; font-size: 0.56rem; font-weight: 700; letter-spacing: 0.08em; text-transform: uppercase; color: var(--accent-ink); }
+    .dt-chrome .lv i { width: 5px; height: 5px; border-radius: 50%; background: var(--accent); box-shadow: 0 0 7px var(--accent); animation: dtpulse 1.6s infinite; }
+    @keyframes dtpulse { 0%,100%{opacity:1} 50%{opacity:.35} }
+    .dt-media img { display: block; width: 100%; height: 170px; object-fit: cover; }
+    .dposter .dt-cat { display: inline-flex; align-items: center; gap: 6px; font-size: 0.64rem; font-weight: 700; letter-spacing: 0.04em; text-transform: uppercase; margin-top: 13px;
+      color: hsl(var(--ch) var(--tint-s) 74%); }
+    [data-theme="light"] .dposter .dt-cat { color: hsl(var(--ch) calc(var(--tint-s) + 12%) 36%); }
+    .dposter .dt-cat svg { width: 12px; height: 12px; }
+    .dposter h3 { font-family: 'Newsreader', serif; font-weight: 400; font-size: 1.3rem; margin-top: 6px; letter-spacing: -0.01em; }
+    .dposter h3 .ap { font-style: italic; color: var(--accent-ink); }
+    .dposter .dt-blurb { color: var(--ink-2); font-size: 0.83rem; margin-top: 7px; display: -webkit-box; -webkit-line-clamp: 2; -webkit-box-orient: vertical; overflow: hidden; }
+    .dposter .dt-by { margin-top: auto; padding-top: 12px; font-size: 0.74rem; color: var(--ink-3); display: flex; align-items: center; gap: 7px; }
+    .dposter .dt-by b { color: var(--ink-2); font-weight: 600; }
+    .dt-av { width: 22px; height: 22px; border-radius: 7px; display: grid; place-items: center; font-size: 0.55rem; font-weight: 700; text-transform: uppercase;
+      background: hsl(var(--ch) var(--tint-s) 52% / 0.2); color: hsl(var(--ch) var(--tint-s) 74%); border: 1px solid hsl(var(--ch) var(--tint-s) 55% / 0.35); }
+    [data-theme="light"] .dt-av { color: hsl(var(--ch) calc(var(--tint-s) + 12%) 36%); }
+    .dposter-end { display: grid; place-content: center; gap: 8px; text-align: center; min-width: 184px; padding: 22px; text-decoration: none; color: inherit;
+      border-radius: var(--radius); border: 1px dashed hsl(var(--accent-band) var(--tint-s) 55% / 0.5); background: hsl(var(--accent-band) var(--tint-s) 52% / 0.07); transition: background .25s, transform .25s; }
+    .dposter-end:hover { background: hsl(var(--accent-band) var(--tint-s) 52% / 0.13); transform: translateY(-2px); }
+    .dposter-end .ico { width: 52px; height: 52px; border-radius: 50%; display: grid; place-items: center; margin: 0 auto; color: var(--accent-ink);
+      border: 1px solid hsl(var(--accent-band) var(--tint-s) 55% / 0.5); background: hsl(var(--accent-band) var(--tint-s) 52% / 0.14); }
+    .dposter-end .ico svg { width: 22px; height: 22px; }
+    .dposter-end .go { font-weight: 700; color: var(--ink); font-size: 0.95rem; }
+    .dposter-end .tx { color: var(--ink-2); font-size: 0.82rem; max-width: 16ch; margin: 0 auto; }
+    @media (max-width: 900px) { .dposter-end { min-width: 70%; } }
+    @media (prefers-reduced-motion: reduce) { .dt-chrome .lv i { animation: none; } }
   </style>
   <script>document.documentElement.classList.add('js');</script>
-  <!-- Analytics provider is configured in the footer script. -->
 </head>
 <body>
+  <div class="ambient" aria-hidden="true"><i class="a"></i><i class="b"></i><i class="c"></i></div>
+  <div class="grain" aria-hidden="true"></div>
+
   <!-- Nav -->
-  <nav class="nav">
-    <a class="nav-brand" href="#">CLI-Hub</a>
-    <div class="nav-links">
-      <a class="nav-link" href="https://reeceyang.sgp1.cdn.digitaloceanspaces.com/SKILL.md" target="_blank">
-        <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.85" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="m5.5 18.5 9.8-9.8"/><path d="m13.7 6.9 3.4 3.4"/><path d="M18 4v2.4"/><path d="M16.8 5.2h2.4"/><path d="M7.5 4.8v2"/><path d="M6.5 5.8h2"/><path d="M18.2 15.8v2"/><path d="M17.2 16.8h2"/></svg>
-        SKILL
-      </a>
-      <a class="nav-link" href="https://github.com/HKUDS/CLI-Anything" target="_blank">
-        <svg viewBox="0 0 98 96" fill="currentColor"><path fill-rule="evenodd" clip-rule="evenodd" d="M48.854 0C21.839 0 0 22 0 49.217c0 21.756 13.993 40.172 33.405 46.69 2.427.49 3.316-1.059 3.316-2.362 0-1.141-.08-5.052-.08-9.127-13.59 2.934-16.42-5.867-16.42-5.867-2.184-5.704-5.42-7.17-5.42-7.17-4.448-3.015.324-3.015.324-3.015 4.934.326 7.523 5.052 7.523 5.052 4.367 7.496 11.404 5.378 14.235 4.074.404-3.178 1.699-5.378 3.074-6.6C29.304 70.25 17.9 66.013 17.9 47.02c0-5.52 1.94-10.046 5.127-13.58-.486-1.302-2.264-6.437.486-13.34 0 0 4.206-1.302 13.59 5.216 3.963-1.14 8.17-1.628 12.34-1.628 4.17 0 8.376.568 12.34 1.628 9.384-6.518 13.59-5.216 13.59-5.216 2.75 6.903.972 12.038.486 13.34 3.268 3.534 5.127 8.06 5.127 13.58 0 19.074-11.485 23.15-22.328 24.29 1.78 1.548 3.316 4.481 3.316 9.126 0 6.6-.08 11.897-.08 13.526 0 1.304.89 2.853 3.316 2.364 19.412-6.52 33.405-24.935 33.405-46.691C97.707 22 75.788 0 48.854 0z"/></svg>
-        GitHub
-        <span class="nav-link-stars" data-github-stars aria-label="GitHub star count">--</span>
-      </a>
-      <a class="nav-link" href="https://arxiv.org/abs/2606.03854" target="_blank" rel="noopener noreferrer">
-        <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.85" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M7 3.5h8.2L19 7.3v12A1.7 1.7 0 0 1 17.3 21H7a2 2 0 0 1-2-2V5.5a2 2 0 0 1 2-2z"/><path d="M15 3.5v4h4"/><path d="M8.5 11.2h7"/><path d="M8.5 14.5h7"/><path d="M8.5 17.8h4.5"/><path d="M10 3.5v5l1.7-1.1L13.4 8.5v-5"/></svg>
-        Tech Report
-      </a>
-      <a class="nav-link" href="https://github.com/HKUDS/CLI-Anything/blob/main/CONTRIBUTING.md" target="_blank">
-        Contribute
-      </a>
-      <button class="theme-toggle" onclick="toggleTheme()" aria-label="Toggle theme">
-        <svg class="icon-sun" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="5"/><line x1="12" y1="1" x2="12" y2="3"/><line x1="12" y1="21" x2="12" y2="23"/><line x1="4.22" y1="4.22" x2="5.64" y2="5.64"/><line x1="18.36" y1="18.36" x2="19.78" y2="19.78"/><line x1="1" y1="12" x2="3" y2="12"/><line x1="21" y1="12" x2="23" y2="12"/><line x1="4.22" y1="19.78" x2="5.64" y2="18.36"/><line x1="18.36" y1="5.64" x2="19.78" y2="4.22"/></svg>
-        <svg class="icon-moon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M21 12.79A9 9 0 1 1 11.21 3 7 7 0 0 0 21 12.79z"/></svg>
-      </button>
+  <nav class="nav" id="nav">
+    <div class="nav-in">
+      <a class="nav-brand" href="#"><span class="nav-brand-badge" aria-hidden="true"><svg viewBox="0 0 48 48" fill="none"><path d="M8 16.5 18.5 24 8 31.5" stroke="currentColor" stroke-width="3.9" stroke-linecap="square" stroke-linejoin="miter" style="color: var(--accent);"/><path d="M24 29.2h16" stroke="currentColor" stroke-width="3.9" stroke-linecap="square" style="color: var(--ink);"/></svg></span>CLI-Hub</a>
+      <div class="nav-links">
+        <div class="nav-menu" id="navMenu">
+        <a class="nav-link" href="#demos">
+          <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.85" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="3" y="4" width="18" height="14" rx="2"/><path d="m10 9 4 2.5L10 14z" fill="currentColor" stroke="none"/></svg>
+          Demos
+        </a>
+        <a class="nav-link" href="#matrices">
+          <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.85" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="3.5" y="3.5" width="7" height="7" rx="1.6"/><rect x="13.5" y="3.5" width="7" height="7" rx="1.6"/><rect x="3.5" y="13.5" width="7" height="7" rx="1.6"/><rect x="13.5" y="13.5" width="7" height="7" rx="1.6"/></svg>
+          Matrices
+        </a>
+        <a class="nav-link" href="docs.html">
+          <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.85" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M4 4.8A1.8 1.8 0 0 1 5.8 3H12v17H5.8A1.8 1.8 0 0 0 4 21.8z"/><path d="M20 4.8A1.8 1.8 0 0 0 18.2 3H12v17h6.2A1.8 1.8 0 0 1 20 21.8z"/></svg>
+          Docs
+        </a>
+        <a class="nav-link" href="https://reeceyang.sgp1.cdn.digitaloceanspaces.com/SKILL.md" target="_blank">
+          <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.85" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="m5.5 18.5 9.8-9.8"/><path d="m13.7 6.9 3.4 3.4"/><path d="M18 4v2.4"/><path d="M16.8 5.2h2.4"/><path d="M7.5 4.8v2"/><path d="M6.5 5.8h2"/><path d="M18.2 15.8v2"/><path d="M17.2 16.8h2"/></svg>
+          SKILL
+        </a>
+        <a class="nav-link" href="https://github.com/HKUDS/CLI-Anything" target="_blank">
+          <svg viewBox="0 0 98 96" fill="currentColor" aria-hidden="true"><path fill-rule="evenodd" clip-rule="evenodd" d="M48.854 0C21.839 0 0 22 0 49.217c0 21.756 13.993 40.172 33.405 46.69 2.427.49 3.316-1.059 3.316-2.362 0-1.141-.08-5.052-.08-9.127-13.59 2.934-16.42-5.867-16.42-5.867-2.184-5.704-5.42-7.17-5.42-7.17-4.448-3.015.324-3.015.324-3.015 4.934.326 7.523 5.052 7.523 5.052 4.367 7.496 11.404 5.378 14.235 4.074.404-3.178 1.699-5.378 3.074-6.6C29.304 70.25 17.9 66.013 17.9 47.02c0-5.52 1.94-10.046 5.127-13.58-.486-1.302-2.264-6.437.486-13.34 0 0 4.206-1.302 13.59 5.216 3.963-1.14 8.17-1.628 12.34-1.628 4.17 0 8.376.568 12.34 1.628 9.384-6.518 13.59-5.216 13.59-5.216 2.75 6.903.972 12.038.486 13.34 3.268 3.534 5.127 8.06 5.127 13.58 0 19.074-11.485 23.15-22.328 24.29 1.78 1.548 3.316 4.481 3.316 9.126 0 6.6-.08 11.897-.08 13.526 0 1.304.89 2.853 3.316 2.364 19.412-6.52 33.405-24.935 33.405-46.691C97.707 22 75.788 0 48.854 0z"/></svg>
+          GitHub
+          <span class="nav-link-stars" data-github-stars aria-label="GitHub star count">--</span>
+        </a>
+        <a class="nav-link" href="https://arxiv.org/abs/2606.03854" target="_blank" rel="noopener noreferrer">
+          <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.85" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M7 3.5h8.2L19 7.3v12A1.7 1.7 0 0 1 17.3 21H7a2 2 0 0 1-2-2V5.5a2 2 0 0 1 2-2z"/><path d="M15 3.5v4h4"/><path d="M8.5 11.2h7"/><path d="M8.5 14.5h7"/><path d="M8.5 17.8h4.5"/><path d="M10 3.5v5l1.7-1.1L13.4 8.5v-5"/></svg>
+          Tech Report
+        </a>
+        <a class="nav-link" href="https://github.com/HKUDS/CLI-Anything/blob/main/CONTRIBUTING.md" target="_blank">
+          Contribute
+        </a>
+        </div>
+        <div class="palette-switch" id="palette-switch" role="group" aria-label="Color palette">
+          <span class="palette-switch-label">Palette</span>
+        </div>
+        <div class="palette-popwrap" id="palette-popwrap">
+          <button class="palette-pop-btn" id="palette-pop-btn" aria-haspopup="true" aria-expanded="false" aria-label="Choose color palette">
+            <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.9" stroke-linecap="round" stroke-linejoin="round"><circle cx="13.5" cy="6.5" r=".5" fill="currentColor"/><circle cx="17.5" cy="10.5" r=".5" fill="currentColor"/><circle cx="8.5" cy="7.5" r=".5" fill="currentColor"/><circle cx="6.5" cy="12.5" r=".5" fill="currentColor"/><path d="M12 2C6.5 2 2 6.5 2 12s4.5 10 10 10c.926 0 1.648-.746 1.648-1.688 0-.437-.18-.835-.437-1.125-.29-.289-.438-.652-.438-1.125 0-.926.746-1.688 1.688-1.688H16c3.314 0 6-2.686 6-6 0-4.97-4.5-8.375-10-8.375Z"/></svg>
+          </button>
+          <div class="palette-pop-panel" id="palette-pop-panel" role="group" aria-label="Color palette"></div>
+        </div>
+        <button class="theme-toggle" onclick="toggleTheme()" aria-label="Toggle theme">
+          <svg class="icon-sun" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="5"/><line x1="12" y1="1" x2="12" y2="3"/><line x1="12" y1="21" x2="12" y2="23"/><line x1="4.22" y1="4.22" x2="5.64" y2="5.64"/><line x1="18.36" y1="18.36" x2="19.78" y2="19.78"/><line x1="1" y1="12" x2="3" y2="12"/><line x1="21" y1="12" x2="23" y2="12"/><line x1="4.22" y1="19.78" x2="5.64" y2="18.36"/><line x1="18.36" y1="5.64" x2="19.78" y2="4.22"/></svg>
+          <svg class="icon-moon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M21 12.79A9 9 0 1 1 11.21 3 7 7 0 0 0 21 12.79z"/></svg>
+        </button>
+        <button class="nav-toggle" id="navToggle" aria-label="Menu" aria-expanded="false" aria-controls="navMenu">
+          <svg class="icon-bars" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round"><line x1="3" y1="6" x2="21" y2="6"/><line x1="3" y1="12" x2="21" y2="12"/><line x1="3" y1="18" x2="21" y2="18"/></svg>
+          <svg class="icon-x" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M18 6 6 18M6 6l12 12"/></svg>
+        </button>
+      </div>
     </div>
+    <div class="nav-scrim" id="navScrim"></div>
   </nav>
 
   <!-- Hero -->
@@ -1909,9 +959,9 @@
       <span class="hero-title-badge" aria-hidden="true">
         <svg viewBox="0 0 48 48" fill="none">
           <path d="M8 16.5 18.5 24 8 31.5" stroke="currentColor" stroke-width="3.9" stroke-linecap="square" stroke-linejoin="miter" style="color: var(--accent);" />
-          <path d="M24 29.2h16" stroke="currentColor" stroke-width="3.9" stroke-linecap="square" class="hero-badge-cursor" style="color: rgba(248,250,252,0.98);" />
-          <path d="M26 12h14" stroke="url(#heroBadgeBeam)" stroke-width="2.6" stroke-linecap="square" class="hero-badge-glow" opacity="0.78" />
-          <path d="M7 10.5h9" stroke="currentColor" stroke-width="1.8" stroke-linecap="square" style="color: rgba(148,163,184,0.48);" />
+          <path d="M24 29.2h16" stroke="currentColor" stroke-width="3.9" stroke-linecap="square" style="color: var(--ink);" />
+          <path d="M26 12h14" stroke="url(#heroBadgeBeam)" stroke-width="2.6" stroke-linecap="square" opacity="0.78" />
+          <path d="M7 10.5h9" stroke="currentColor" stroke-width="1.8" stroke-linecap="square" style="color: var(--ink-3);" />
           <path d="M7 37.5h11" stroke="currentColor" stroke-width="1.8" stroke-linecap="square" style="color: rgba(96,165,250,0.3);" />
           <defs>
             <linearGradient id="heroBadgeBeam" x1="26" y1="12" x2="40" y2="12" gradientUnits="userSpaceOnUse">
@@ -1923,9 +973,7 @@
         </svg>
       </span>
       <h1>
-        <span class="hero-word hero-word--cli hero-accent">CLI-</span>
-        <span class="hero-word hero-word--anything hero-dim hero-shimmer" data-text="Anything">Anything</span>
-        <span class="hero-word hero-word--hub hero-accent">Hub</span>
+        <span class="hero-word hero-word--cli">CLI-</span><span class="hero-word hero-word--anything">Anything</span> <span class="hero-word hero-word--hub">Hub</span>
       </h1>
     </div>
     <p class="hero-tagline"><span class="hero-tagline-line hero-tagline-line--any">Any software. Any codebase. Any Web API.</span> <span class="hero-tagline-line hero-tagline-line--rest">Generate an agent-native CLI and let AI agents operate it &mdash; install with a single command.</span></p>
@@ -1975,8 +1023,12 @@ <h3>Empower yourself &mdash; <span>your CLI toolkit</span></h3>
 
     <div class="hero-actions">
       <a class="btn-primary" href="https://reeceyang.sgp1.cdn.digitaloceanspaces.com/SKILL.md" target="_blank">Agent SKILL (SKILL.md)</a>
+      <a class="btn-secondary" href="docs.html">
+        <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.9" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M4 4.8A1.8 1.8 0 0 1 5.8 3H12v17H5.8A1.8 1.8 0 0 0 4 21.8z"/><path d="M20 4.8A1.8 1.8 0 0 0 18.2 3H12v17h6.2A1.8 1.8 0 0 1 20 21.8z"/></svg>
+        Documentation
+      </a>
       <a class="btn-secondary" href="https://github.com/HKUDS/CLI-Anything" target="_blank">
-        <svg viewBox="0 0 98 96" fill="currentColor"><path fill-rule="evenodd" clip-rule="evenodd" d="M48.854 0C21.839 0 0 22 0 49.217c0 21.756 13.993 40.172 33.405 46.69 2.427.49 3.316-1.059 3.316-2.362 0-1.141-.08-5.052-.08-9.127-13.59 2.934-16.42-5.867-16.42-5.867-2.184-5.704-5.42-7.17-5.42-7.17-4.448-3.015.324-3.015.324-3.015 4.934.326 7.523 5.052 7.523 5.052 4.367 7.496 11.404 5.378 14.235 4.074.404-3.178 1.699-5.378 3.074-6.6C29.304 70.25 17.9 66.013 17.9 47.02c0-5.52 1.94-10.046 5.127-13.58-.486-1.302-2.264-6.437.486-13.34 0 0 4.206-1.302 13.59 5.216 3.963-1.14 8.17-1.628 12.34-1.628 4.17 0 8.376.568 12.34 1.628 9.384-6.518 13.59-5.216 13.59-5.216 2.75 6.903.972 12.038.486 13.34 3.268 3.534 5.127 8.06 5.127 13.58 0 19.074-11.485 23.15-22.328 24.29 1.78 1.548 3.316 4.481 3.316 9.126 0 6.6-.08 11.897-.08 13.526 0 1.304.89 2.853 3.316 2.364 19.412-6.52 33.405-24.935 33.405-46.691C97.707 22 75.788 0 48.854 0z"/></svg>
+        <svg viewBox="0 0 98 96" fill="currentColor" aria-hidden="true"><path fill-rule="evenodd" clip-rule="evenodd" d="M48.854 0C21.839 0 0 22 0 49.217c0 21.756 13.993 40.172 33.405 46.69 2.427.49 3.316-1.059 3.316-2.362 0-1.141-.08-5.052-.08-9.127-13.59 2.934-16.42-5.867-16.42-5.867-2.184-5.704-5.42-7.17-5.42-7.17-4.448-3.015.324-3.015.324-3.015 4.934.326 7.523 5.052 7.523 5.052 4.367 7.496 11.404 5.378 14.235 4.074.404-3.178 1.699-5.378 3.074-6.6C29.304 70.25 17.9 66.013 17.9 47.02c0-5.52 1.94-10.046 5.127-13.58-.486-1.302-2.264-6.437.486-13.34 0 0 4.206-1.302 13.59 5.216 3.963-1.14 8.17-1.628 12.34-1.628 4.17 0 8.376.568 12.34 1.628 9.384-6.518 13.59-5.216 13.59-5.216 2.75 6.903.972 12.038.486 13.34 3.268 3.534 5.127 8.06 5.127 13.58 0 19.074-11.485 23.15-22.328 24.29 1.78 1.548 3.316 4.481 3.316 9.126 0 6.6-.08 11.897-.08 13.526 0 1.304.89 2.853 3.316 2.364 19.412-6.52 33.405-24.935 33.405-46.691C97.707 22 75.788 0 48.854 0z"/></svg>
         Star on GitHub
       </a>
       <a class="btn-secondary" href="https://github.com/HKUDS/CLI-Anything/blob/main/CONTRIBUTING.md" target="_blank">
@@ -1989,10 +1041,66 @@ <h3>Empower yourself &mdash; <span>your CLI toolkit</span></h3>
 
     <p class="hero-hint">Feed <a href="https://reeceyang.sgp1.cdn.digitaloceanspaces.com/SKILL.md" target="_blank">SKILL.md</a> to your AI agent for autonomous CLI discovery &amp; installation</p>
 
-    <p class="hero-cta">We welcome contributions for <em>any</em> application &mdash; desktop apps, dev tools, cloud services, SaaS APIs, creative suites, and beyond. If it has a GUI or an API, it deserves an agent-native CLI. Read the <a href="https://github.com/HKUDS/CLI-Anything/blob/main/CONTRIBUTING.md" target="_blank">Contributing Guide</a>, use the <a href="https://github.com/HKUDS/CLI-Anything/blob/main/.github/PULL_REQUEST_TEMPLATE.md" target="_blank">PR Template</a>, and bring it to the hub!</p>
+    <p class="hero-cta">We welcome contributions for <em>any</em> application &mdash; desktop apps, dev tools, cloud services, SaaS APIs, creative suites, and beyond. If it has a GUI or an API, it deserves an agent-native CLI. Read the <a href="https://github.com/HKUDS/CLI-Anything/blob/main/CONTRIBUTING.md" target="_blank">Contributing Guide</a>, use the <a href="https://github.com/HKUDS/CLI-Anything/blob/main/.github/PULL_REQUEST_TEMPLATE.md" target="_blank">PR Template</a>, and bring it <span class="nowrap">to the hub!</span></p>
 
   </div>
 
+  <!-- Real-World Demos — homepage teaser (full Editorial gallery lives on demos.html) -->
+  <section class="demos-teaser" id="demos">
+    <div class="dt-head">
+      <div>
+        <div class="kl">See it work</div>
+        <h2>Real-world demos</h2>
+        <p>Agents driving generated CLIs to finished artifacts &mdash; CAD models, 3D scenes, diagrams, gameplay, captioned video, and live GIS. No GUI needed.</p>
+      </div>
+      <a class="dt-seeall" href="demos.html">See all demos
+        <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M5 12h14"/><path d="m12 5 7 7-7 7"/></svg>
+      </a>
+    </div>
+    <div class="demos-strip">
+
+      <a class="dposter" href="demos.html#freecad" style="--ch:210">
+        <div class="dt-media">
+          <div class="dt-chrome"><span class="dts"><i></i><i></i><i></i></span><span class="u">cli-anything-freecad · preview live</span><span class="lv"><i></i>live</span></div>
+          <img loading="lazy" src="assets/demos/freecad-curiosity-preview-trajectory.gif" alt="FreeCAD Curiosity rover demo">
+        </div>
+        <span class="dt-cat"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"><path d="M12 2 3 7v10l9 5 9-5V7z"/><path d="M3 7l9 5 9-5"/><path d="M12 12v10"/></svg>3D / CAD</span>
+        <h3><span class="ap">FreeCAD</span> — Curiosity Rover</h3>
+        <p class="dt-blurb">An agent assembles a Curiosity-inspired rover while publishing real preview bundles and recording a replayable trajectory.</p>
+        <div class="dt-by"><span class="dt-av">CA</span><span><b>Core team</b> · CLI-Anything</span></div>
+      </a>
+
+      <a class="dposter" href="demos.html#blender" style="--ch:28">
+        <div class="dt-media">
+          <div class="dt-chrome"><span class="dts"><i></i><i></i><i></i></span><span class="u">cli-anything-blender · preview live</span><span class="lv"><i></i>live</span></div>
+          <img loading="lazy" src="assets/demos/blender-orbital-relay-drone-preview-trajectory.gif" alt="Blender orbital relay drone demo">
+        </div>
+        <span class="dt-cat"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"><path d="M12 2 3 7v10l9 5 9-5V7z"/><path d="M3 7l9 5 9-5"/><path d="M12 12v10"/></svg>3D · Hard-surface</span>
+        <h3><span class="ap">Blender</span> — Orbital Relay Drone</h3>
+        <p class="dt-blurb">A hard-surface drone grows under a real preview loop, each stage pushing render-backed bundles tied to the trajectory.</p>
+        <div class="dt-by"><span class="dt-av">CA</span><span><b>Core team</b> · CLI-Anything</span></div>
+      </a>
+
+      <a class="dposter" href="demos.html#drawio" style="--ch:250">
+        <div class="dt-media">
+          <div class="dt-chrome"><span class="dts"><i></i><i></i><i></i></span><span class="u">cli-anything-drawio · build</span><span class="lv"><i></i>live</span></div>
+          <img loading="lazy" src="assets/demos/drawio-demo.gif" alt="Draw.io HTTPS handshake diagram demo">
+        </div>
+        <span class="dt-cat"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"><rect x="3" y="3" width="7" height="5" rx="1"/><rect x="14" y="16" width="7" height="5" rx="1"/><path d="M6.5 8v4a2 2 0 0 0 2 2h9"/></svg>Diagramming</span>
+        <h3><span class="ap">Draw.io</span> — HTTPS Handshake</h3>
+        <p class="dt-blurb">A full HTTPS lifecycle diagram built from scratch — TCP handshake, TLS negotiation, and termination — entirely via CLI.</p>
+        <div class="dt-by"><span class="dt-av">ZH</span><span>Contributed by <b>@zhangxilong-43</b></span></div>
+      </a>
+
+      <a class="dposter-end" href="demos.html">
+        <span class="ico" aria-hidden="true"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M5 12h14"/><path d="m12 5 7 7-7 7"/></svg></span>
+        <span class="go">See all demos</span>
+        <span class="tx">Explore the full gallery</span>
+      </a>
+
+    </div>
+  </section>
+
   <div class="marketplace-prelude">
     <div class="typing-shell" data-typing-text="pip install cli-anything-hub">
       <div class="typing-shell-head">
@@ -2006,6 +1114,30 @@ <h3>Empower yourself &mdash; <span>your CLI toolkit</span></h3>
     </div>
   </div>
 
+  <!-- Matrices -->
+  <section class="matrices" id="matrices">
+    <div class="matrices-head">
+      <div>
+        <div class="klabel">The collections</div>
+        <h2>Matrices</h2>
+        <p>Each matrix is a capability bundle &mdash; a curated set of intents mapped to provider CLIs from the catalog below. Flip a card for its capabilities, then scope the catalog to just its tools.</p>
+      </div>
+      <div class="mat-stat" id="mat-stat"></div>
+    </div>
+    <div class="shelf" id="shelf">
+      <div class="skeleton"></div><div class="skeleton"></div><div class="skeleton"></div>
+    </div>
+  </section>
+
+  <!-- Catalog scope banner (set by matrix "show only these tools") -->
+  <div class="scope-banner" id="scopeBanner" role="status">
+    <span class="lbl">Scoped to <b id="scopeName">a matrix</b> &mdash; showing <b id="scopeCount">0</b> tools.</span>
+    <button class="clear" id="scopeClear" type="button">
+      <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.2" width="14" height="14"><path d="M18 6 6 18M6 6l12 12"/></svg>
+      Show all tools
+    </button>
+  </div>
+
   <!-- Deck nav -->
   <div class="deck-nav">
     <button class="deck-tab active" data-deck="harness" onclick="switchDeck('harness')">
@@ -2016,7 +1148,15 @@ <h3>Empower yourself &mdash; <span>your CLI toolkit</span></h3>
       Public CLIs
       <span class="deck-count" id="deck-count-public">&mdash;</span>
     </button>
+    <div class="deck-dots" role="tablist" aria-label="Switch deck">
+      <button class="deck-dot active" data-deck="harness" onclick="switchDeck('harness')" aria-label="Show CLI-Anything CLIs" title="CLI-Anything CLIs"></button>
+      <button class="deck-dot" data-deck="public" onclick="switchDeck('public')" aria-label="Show Public CLIs" title="Public CLIs"></button>
+    </div>
     <span class="deck-separator"></span>
+    <span class="deck-hint" aria-hidden="true">
+      <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.9" stroke-linecap="round" stroke-linejoin="round"><path d="M8 9 4 12l4 3"/><path d="M16 9l4 3-4 3"/><path d="M4 12h16"/></svg>
+      <span>drag, scroll, or tap to switch</span>
+    </span>
     <button class="deck-arrow-btn" id="deck-toggle" onclick="toggleDeck()">
       <span>Public CLIs</span>
       <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><polyline points="9 18 15 12 9 6"/></svg>
@@ -2039,7 +1179,9 @@ <h3>Empower yourself &mdash; <span>your CLI toolkit</span></h3>
             </select>
           </div>
           <div class="filter-row" id="filters-harness"></div>
-          <div class="grid" id="grid-harness"></div>
+          <div class="grid" id="grid-harness">
+            <div class="skeleton"></div><div class="skeleton"></div><div class="skeleton"></div>
+          </div>
         </div>
 
         <!-- Public CLI deck -->
@@ -2089,34 +1231,205 @@ <h3>Empower yourself &mdash; <span>your CLI toolkit</span></h3>
   </footer>
 
   <script>
+    // Forward declaration so palette init (which runs before the matrix block) can read it.
+    var STATE = {
+      byName: new Map(),     // cli name -> catalog entry (with ._deck)
+      matrices: [],
+      membership: new Map(), // cli name -> [matrix, ...]
+      scope: null,           // matrix name the catalog is scoped to
+    };
+    var MATRIX_URLS = [
+      '../../matrix_registry.json',
+      'https://raw.githubusercontent.com/HKUDS/CLI-Anything/main/matrix_registry.json'
+    ];
+
+    // ── Palette system (tech · humanistic · aesthetic) ──
+    // Anchor tokens per palette × theme; glass/chip/shadow derive in CSS from these.
+    // accentBand = the palette's ACCENT hue; per-category tints spread ±~25° around it
+    // (catHue), so each palette keeps its own colour family (warm palettes → warm tints).
+    const PALETTES = {
+      steel: {
+        label: 'Steel', accentBand: 209,
+        sw: { accent: '#2f6fb0', grey: '#8595a8' },
+        light: { bg:'#f4f6f9', surface:'#ffffff', ink:'#14181f', ink2:'#4a5568', ink3:'#8595a8', line:'rgba(20,40,80,.10)', accent:'#2f6fb0', accent2:'#1f5793', accentRgb:'47,111,176', surfaceRgb:'255,255,255' },
+        dark:  { bg:'#0d1117', surface:'#151b24', ink:'#e8edf4', ink2:'#9fb0c4', ink3:'#647488', line:'rgba(255,255,255,.08)', accent:'#5b9bd6', accent2:'#7db4e6', accentRgb:'91,155,214', surfaceRgb:'21,27,36' },
+      },
+      steelsky: {
+        label: 'Steel Sky', accentBand: 203,
+        sw: { accent: '#1c8ee0', grey: '#8595a8' },
+        light: { bg:'#f4f6f9', surface:'#ffffff', ink:'#14181f', ink2:'#4a5568', ink3:'#8595a8', line:'rgba(20,40,80,.10)', accent:'#1c8ee0', accent2:'#1573bd', accentRgb:'28,142,224', surfaceRgb:'255,255,255' },
+        dark:  { bg:'#0d1117', surface:'#151b24', ink:'#e8edf4', ink2:'#9fb0c4', ink3:'#647488', line:'rgba(255,255,255,.08)', accent:'#46b2f4', accent2:'#6cc6f8', accentRgb:'70,178,244', surfaceRgb:'21,27,36' },
+      },
+      sky: {
+        label: 'Sky', accentBand: 203,
+        sw: { accent: '#1c8ee0', grey: '#8299ac' },
+        light: { bg:'#f4f9fe', surface:'#ffffff', ink:'#0f1f2d', ink2:'#465a6b', ink3:'#8299ac', line:'rgba(20,70,115,.10)', accent:'#1c8ee0', accent2:'#1573bd', accentRgb:'28,142,224', surfaceRgb:'255,255,255' },
+        dark:  { bg:'#0a1320', surface:'#121e2d', ink:'#e9f3fb', ink2:'#9bb4c9', ink3:'#5f7689', line:'rgba(255,255,255,.08)', accent:'#46b2f4', accent2:'#6cc6f8', accentRgb:'70,178,244', surfaceRgb:'18,30,45' },
+      },
+      sage: {
+        label: 'Sage', accentBand: 160,
+        sw: { accent: '#2c9b78', grey: '#7f968a' },
+        light: { bg:'#f3f8f4', surface:'#ffffff', ink:'#13211b', ink2:'#475a51', ink3:'#7f968a', line:'rgba(20,65,48,.10)', accent:'#2c9b78', accent2:'#1d8062', accentRgb:'44,155,120', surfaceRgb:'255,255,255' },
+        dark:  { bg:'#0b1410', surface:'#121d18', ink:'#e7f2eb', ink2:'#9ab4a7', ink3:'#5e7568', line:'rgba(255,255,255,.07)', accent:'#48c29c', accent2:'#67d0b1', accentRgb:'72,194,156', surfaceRgb:'18,29,24' },
+      },
+      sand: {
+        label: 'Sand', accentBand: 175,
+        sw: { accent: '#1d7a71', grey: '#948979' },
+        light: { bg:'#f8f5ef', surface:'#fffdf8', ink:'#221d15', ink2:'#585044', ink3:'#948979', line:'rgba(75,58,30,.12)', accent:'#1d7a71', accent2:'#145d57', accentRgb:'29,122,113', surfaceRgb:'255,253,248' },
+        dark:  { bg:'#13110b', surface:'#1b1811', ink:'#f1ece1', ink2:'#b2a797', ink3:'#796e5e', line:'rgba(255,255,255,.07)', accent:'#3eb2a4', accent2:'#5cc3b6', accentRgb:'62,178,164', surfaceRgb:'27,24,17' },
+      },
+      blush: {
+        label: 'Blush', accentBand: 3,
+        sw: { accent: '#c25e5a', grey: '#9b8a87' },
+        light: { bg:'#faf6f4', surface:'#fffefd', ink:'#271d1c', ink2:'#5e504e', ink3:'#9b8a87', line:'rgba(90,50,45,.11)', accent:'#c25e5a', accent2:'#a4453f', accentRgb:'194,94,90', surfaceRgb:'255,254,253' },
+        dark:  { bg:'#140f0e', surface:'#1c1615', ink:'#f3eae8', ink2:'#b6a4a1', ink3:'#7d6b68', line:'rgba(255,255,255,.07)', accent:'#df8480', accent2:'#e89f9b', accentRgb:'223,132,128', surfaceRgb:'28,22,21' },
+      },
+      mist: {
+        label: 'Mist', accentBand: 222,
+        sw: { accent: '#3b6ef0', grey: '#8893a6' },
+        light: { bg:'#f6f8fb', surface:'#ffffff', ink:'#171b22', ink2:'#4e586a', ink3:'#8893a6', line:'rgba(25,35,60,.09)', accent:'#3b6ef0', accent2:'#2f57cf', accentRgb:'59,110,240', surfaceRgb:'255,255,255' },
+        dark:  { bg:'#0a0d14', surface:'#12161f', ink:'#eef1f7', ink2:'#9aa6bd', ink3:'#606b82', line:'rgba(255,255,255,.07)', accent:'#5b8bff', accent2:'#789fff', accentRgb:'91,139,255', surfaceRgb:'18,22,31' },
+      },
+    };
+    const PALETTE_ORDER = ['steel', 'steelsky', 'sky', 'sage', 'sand', 'blush', 'mist'];
+    const DEFAULT_PALETTE = 'steelsky';
+
+    function getPalette() {
+      const stored = localStorage.getItem('palette');
+      return (stored && PALETTES[stored]) ? stored : DEFAULT_PALETTE;
+    }
+    function applyPalette(name) {
+      const p = PALETTES[name] || PALETTES[DEFAULT_PALETTE];
+      const theme = document.documentElement.getAttribute('data-theme') || 'dark';
+      const t = (theme === 'light') ? p.light : p.dark;
+      const root = document.documentElement.style;
+      root.setProperty('--bg', t.bg);
+      root.setProperty('--surface', t.surface);
+      root.setProperty('--ink', t.ink);
+      root.setProperty('--ink-2', t.ink2);
+      root.setProperty('--ink-3', t.ink3);
+      root.setProperty('--line', t.line);
+      root.setProperty('--accent', t.accent);
+      root.setProperty('--accent2', t.accent2);
+      root.setProperty('--accent-rgb', t.accentRgb);
+      root.setProperty('--surface-rgb', t.surfaceRgb);
+      root.setProperty('--accent-band', String(p.accentBand));
+      root.setProperty('--hue-default', String(p.accentBand));
+      document.documentElement.setAttribute('data-palette', name);
+      syncPaletteUI(name);
+      if (typeof rerenderTints === 'function') rerenderTints();
+    }
+    function setPalette(name) {
+      if (!PALETTES[name]) return;
+      applyPalette(name);
+      localStorage.setItem('palette', name);
+    }
+    function syncPaletteUI(active) {
+      document.querySelectorAll('.palette-swatch, .pp-row').forEach(b => {
+        b.setAttribute('aria-pressed', String(b.dataset.palette === active));
+      });
+    }
+    function buildPaletteSwitcher() {
+      const row = document.getElementById('palette-switch');
+      const panel = document.getElementById('palette-pop-panel');
+      if (!row || !panel) return;
+      PALETTE_ORDER.forEach(key => {
+        const p = PALETTES[key];
+        const sw = document.createElement('button');
+        sw.type = 'button';
+        sw.className = 'palette-swatch';
+        sw.dataset.palette = key;
+        sw.style.setProperty('--sw-accent', p.sw.accent);
+        sw.style.setProperty('--sw-grey', p.sw.grey);
+        sw.setAttribute('aria-label', p.label + ' palette');
+        sw.title = p.label;
+        sw.addEventListener('click', () => setPalette(key));
+        row.appendChild(sw);
+
+        const pr = document.createElement('button');
+        pr.type = 'button';
+        pr.className = 'pp-row';
+        pr.dataset.palette = key;
+        pr.setAttribute('aria-label', p.label + ' palette');
+        const dot = document.createElement('span');
+        dot.className = 'pp-dot';
+        dot.style.setProperty('--sw-accent', p.sw.accent);
+        dot.style.setProperty('--sw-grey', p.sw.grey);
+        pr.appendChild(dot);
+        pr.appendChild(document.createTextNode(p.label));
+        pr.addEventListener('click', () => { setPalette(key); closePalettePop(); });
+        panel.appendChild(pr);
+      });
+      // popover toggle (small screens)
+      const popwrap = document.getElementById('palette-popwrap');
+      const popBtn = document.getElementById('palette-pop-btn');
+      if (popBtn && popwrap) {
+        popBtn.addEventListener('click', (e) => {
+          e.stopPropagation();
+          const open = popwrap.classList.toggle('open');
+          popBtn.setAttribute('aria-expanded', String(open));
+        });
+        document.addEventListener('click', (e) => { if (!popwrap.contains(e.target)) closePalettePop(); });
+        document.addEventListener('keydown', (e) => { if (e.key === 'Escape') closePalettePop(); });
+      }
+      syncPaletteUI(getPalette());
+    }
+    function closePalettePop() {
+      const popwrap = document.getElementById('palette-popwrap');
+      const popBtn = document.getElementById('palette-pop-btn');
+      if (popwrap) popwrap.classList.remove('open');
+      if (popBtn) popBtn.setAttribute('aria-expanded', 'false');
+    }
+
     // ── Theme: system preference + localStorage override ──
     function getPreferredTheme() {
       const stored = localStorage.getItem('theme');
       if (stored) return stored;
       return window.matchMedia('(prefers-color-scheme: light)').matches ? 'light' : 'dark';
     }
-
     function applyTheme(theme) {
       document.documentElement.setAttribute('data-theme', theme);
+      applyPalette(getPalette()); // re-resolve anchor tokens for the new theme
     }
-
     function toggleTheme() {
       const current = document.documentElement.getAttribute('data-theme') || 'dark';
       const next = current === 'dark' ? 'light' : 'dark';
       applyTheme(next);
       localStorage.setItem('theme', next);
     }
-
-    // Apply immediately to avoid flash
     applyTheme(getPreferredTheme());
-
-    // Listen for system preference changes (if no manual override)
+    buildPaletteSwitcher();
     window.matchMedia('(prefers-color-scheme: light)').addEventListener('change', (e) => {
-      if (!localStorage.getItem('theme')) {
-        applyTheme(e.matches ? 'light' : 'dark');
-      }
+      if (!localStorage.getItem('theme')) applyTheme(e.matches ? 'light' : 'dark');
     });
 
+    // ── Nav scrolled state ──
+    (function () {
+      const nav = document.getElementById('nav');
+      const onScroll = () => nav.classList.toggle('scrolled', window.scrollY > 8);
+      window.addEventListener('scroll', onScroll, { passive: true }); onScroll();
+    })();
+
+    // ── Mobile nav drawer ──
+    (function () {
+      const toggle = document.getElementById('navToggle');
+      const menu = document.getElementById('navMenu');
+      const scrim = document.getElementById('navScrim');
+      if (!toggle || !menu) return;
+      function setOpen(open) {
+        menu.classList.toggle('open', open);
+        toggle.classList.toggle('open', open);
+        if (scrim) scrim.classList.toggle('open', open);
+        toggle.setAttribute('aria-expanded', String(open));
+        document.body.style.overflow = open ? 'hidden' : '';
+      }
+      toggle.addEventListener('click', () => setOpen(!menu.classList.contains('open')));
+      if (scrim) scrim.addEventListener('click', () => setOpen(false));
+      menu.addEventListener('click', (e) => { if (e.target.closest('a')) setOpen(false); });
+      document.addEventListener('keydown', (e) => { if (e.key === 'Escape') setOpen(false); });
+      window.addEventListener('resize', () => { if (window.innerWidth > 860) setOpen(false); });
+    })();
+
     const REPO = 'https://github.com/HKUDS/CLI-Anything';
     const GITHUB_REPO_API = 'https://api.github.com/repos/HKUDS/CLI-Anything';
     const GITHUB_STARS_BADGE_API = 'https://img.shields.io/github/stars/HKUDS/CLI-Anything.json';
@@ -2134,20 +1447,212 @@ <h3>Empower yourself &mdash; <span>your CLI toolkit</span></h3>
       '../../registry-dates.json'
     ];
     const EXTERNAL_LINK_SVG = '<svg viewBox="0 0 16 16" fill="currentColor"><path d="M3.75 2h3.5a.75.75 0 0 1 0 1.5H4.56l6.72 6.72a.75.75 0 1 1-1.06 1.06L3.5 4.56v2.69a.75.75 0 0 1-1.5 0v-3.5A1.75 1.75 0 0 1 3.75 2Zm7.5 0h1A1.75 1.75 0 0 1 14 3.75v8.5A1.75 1.75 0 0 1 12.25 14h-8.5A1.75 1.75 0 0 1 2 12.25v-1a.75.75 0 0 1 1.5 0v1c0 .138.112.25.25.25h8.5a.25.25 0 0 0 .25-.25v-8.5a.25.25 0 0 0-.25-.25h-1a.75.75 0 0 1 0-1.5Z"/></svg>';
+    // Skill glyph — identical to the header nav SKILL link icon, for a unified design language.
+    const SKILL_ICON_SVG = '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.85" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="m5.5 18.5 9.8-9.8"/><path d="m13.7 6.9 3.4 3.4"/><path d="M18 4v2.4"/><path d="M16.8 5.2h2.4"/><path d="M7.5 4.8v2"/><path d="M6.5 5.8h2"/><path d="M18.2 15.8v2"/><path d="M17.2 16.8h2"/></svg>';
+
+    // ── Flip affordance glyphs ──
+    // FRONT → "Details" (chevron-right circle), BACK → "Back" (arrow-left). These deliberately
+    // avoid the old circular two-arrow icon, which read as "refresh/reload" rather than "flip".
+    const DETAILS_GLYPH = '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="9"/><path d="m10.5 8.5 3.5 3.5-3.5 3.5"/></svg>';
+    const BACK_GLYPH = '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M19 12H5"/><path d="m12 5-7 7 7 7"/></svg>';
+
+    // ===================== Software icon system (Simple Icons) =====================
+    // ICON_REGISTRY maps a CLI/software *name* (lowercased) → a Simple Icons slug.
+    // HOW TO ADD AN ICON:
+    //   1. Find the slug at https://simpleicons.org (e.g. "Krita" → "krita").
+    //   2. Add a lowercased-name → slug entry below (the catalog `name`, not display_name).
+    //   3. That's it — iconFor() renders https://cdn.simpleicons.org/<slug> and tints it.
+    // Resolver order in iconFor(): (1) entry.icon field if present (future-proofing),
+    //   (2) ICON_REGISTRY[name], (3) a single-letter monogram fallback. A wrong/missing slug
+    //   that 404s also degrades to the monogram via <img onerror>.
+    const ICON_REGISTRY = {
+      gimp: 'gimp', blender: 'blender', obs: 'obsstudio', 'obs-studio': 'obsstudio', obsstudio: 'obsstudio',
+      audacity: 'audacity', krita: 'krita', inkscape: 'inkscape', shotcut: 'shotcut', ffmpeg: 'ffmpeg',
+      imagemagick: 'imagemagick', darktable: 'darktable', kdenlive: 'kdenlive', davinci: 'davinciresolve',
+      'davinci-resolve': 'davinciresolve', handbrake: 'handbrake', vlc: 'vlcmediaplayer', mpv: 'mpv',
+      godot: 'godotengine', 'godot-engine': 'godotengine', godotengine: 'godotengine', unity: 'unity',
+      unrealengine: 'unrealengine', 'unreal-engine': 'unrealengine', aseprite: 'aseprite', musescore: 'musescore',
+      lmms: 'lmms', ardour: 'ardour', reaper: 'reaper',
+      github: 'github', gitlab: 'gitlab', git: 'git', slack: 'slack', discord: 'discord', telegram: 'telegram',
+      notion: 'notion', obsidian: 'obsidian', zoom: 'zoom', calibre: 'calibre', libreoffice: 'libreoffice',
+      figma: 'figma', miro: 'miro', trello: 'trello', asana: 'asana', jira: 'jira', linear: 'linear',
+      airtable: 'airtable', todoist: 'todoist', evernote: 'evernote', spotify: 'spotify', youtube: 'youtube',
+      vimeo: 'vimeo', twitch: 'twitch', canva: 'canva', adobe: 'adobe', photoshop: 'adobephotoshop',
+      premiere: 'adobepremierepro', illustrator: 'adobeillustrator', aftereffects: 'adobeaftereffects',
+      docker: 'docker', kubernetes: 'kubernetes', postman: 'postman', insomnia: 'insomnia', vscode: 'visualstudiocode',
+      'vs-code': 'visualstudiocode', vim: 'vim', neovim: 'neovim', emacs: 'gnuemacs', sublime: 'sublimetext',
+      jupyter: 'jupyter', anaconda: 'anaconda', python: 'python', nodejs: 'nodedotjs', npm: 'npm',
+      ghostscript: 'ghostscript', pandoc: 'pandoc', latex: 'latex', tableau: 'tableau', grafana: 'grafana',
+      wordpress: 'wordpress', shopify: 'shopify', stripe: 'stripe', mailchimp: 'mailchimp', hubspot: 'hubspot',
+      salesforce: 'salesforce', googledrive: 'googledrive', dropbox: 'dropbox', onedrive: 'microsoftonedrive',
+      gmail: 'gmail', googlecalendar: 'googlecalendar', googlesheets: 'googlesheets', googledocs: 'googledocs',
+      excalidraw: 'excalidraw', drawio: 'diagramsdotnet', openai: 'openai', anthropic: 'anthropic',
+      huggingface: 'huggingface', replicate: 'replicate', elevenlabs: 'elevenlabs',
+      // Chinese / APAC brands Simple Icons carries (others resolve via the favicon chain below)
+      wechat: 'wechat', weixin: 'wechat', qq: 'tencentqq', tencentqq: 'tencentqq',
+      bilibili: 'bilibili', weibo: 'sinaweibo', sinaweibo: 'sinaweibo', zhihu: 'zhihu',
+      baidu: 'baidu', alipay: 'alipay', dingtalk: 'dingtalk', tiktok: 'tiktok', douyin: 'tiktok',
+      xiaohongshu: 'xiaohongshu', taobao: 'taobao', tmall: 'tmall', gitee: 'gitee',
+      alibabacloud: 'alibabacloud', huawei: 'huawei', xiaomi: 'xiaomi',
+    };
+
+    // Synonyms & non-English names → a canonical key (used for BOTH the Simple Icons slug and
+    // the favicon-domain lookup). Powers 近义查询 (synonyms); paired with the containment scan
+    // in resolveIconKey() for 模糊查询 (fuzzy). Add an alias to widen what a CLI name can match.
+    const ICON_ALIASES = {
+      feishu: 'lark', lark: 'lark', larksuite: 'lark', '飞书': 'lark',
+      wecom: 'wecom', wework: 'wecom', wechatwork: 'wecom', weixinwork: 'wecom', '企业微信': 'wecom',
+      minimax: 'minimax', minimaxi: 'minimax',
+      wechat: 'wechat', weixin: 'wechat', '微信': 'wechat',
+      dingtalk: 'dingtalk', dingding: 'dingtalk', '钉钉': 'dingtalk',
+      alipay: 'alipay', '支付宝': 'alipay',
+      bilibili: 'bilibili', bili: 'bilibili', '哔哩哔哩': 'bilibili',
+      weibo: 'weibo', '微博': 'weibo', sinaweibo: 'weibo',
+      zhihu: 'zhihu', '知乎': 'zhihu', baidu: 'baidu', '百度': 'baidu',
+      taobao: 'taobao', '淘宝': 'taobao', tmall: 'tmall', '天猫': 'tmall',
+      douyin: 'douyin', '抖音': 'douyin', tiktok: 'tiktok',
+      kuaishou: 'kuaishou', '快手': 'kuaishou', meituan: 'meituan', '美团': 'meituan',
+      amap: 'amap', gaode: 'amap', '高德': 'amap', netease: 'netease', '网易': 'netease',
+      neteasemusic: 'neteasemusic', qqmusic: 'qqmusic', yuque: 'yuque', '语雀': 'yuque',
+      xiaohongshu: 'xiaohongshu', rednote: 'xiaohongshu', '小红书': 'xiaohongshu',
+      qq: 'qq', tencent: 'tencent',
+    };
+
+    // Curated real-logo favicon domains (authoritative — beats a generic homepage such as a
+    // github.com repo URL). Apps Simple Icons lacks still get a real colour logo from here.
+    const ICON_DOMAINS = {
+      lark: 'larksuite.com', wecom: 'work.weixin.qq.com', minimax: 'minimaxi.com',
+      wechat: 'weixin.qq.com', dingtalk: 'dingtalk.com', alipay: 'alipay.com',
+      bilibili: 'bilibili.com', weibo: 'weibo.com', zhihu: 'zhihu.com', baidu: 'baidu.com',
+      taobao: 'taobao.com', tmall: 'tmall.com', douyin: 'douyin.com', tiktok: 'tiktok.com',
+      kuaishou: 'kuaishou.com', meituan: 'meituan.com', amap: 'amap.com', netease: '163.com',
+      neteasemusic: 'music.163.com', qqmusic: 'y.qq.com', yuque: 'yuque.com',
+      xiaohongshu: 'xiaohongshu.com', qq: 'qq.com', tencent: 'tencent.com',
+    };
+    // Generic code/registry hosts we never use as a favicon source (they'd brand every app the
+    // same). When an entry's homepage is one of these, we skip straight to the monogram.
+    const ICON_GENERIC_HOSTS = new Set(['github.com', 'gitlab.com', 'bitbucket.org', 'npmjs.com', 'pypi.org', 'gitee.com', 'sourceforge.net', 'readthedocs.io', 'readthedocs.org', 'codeberg.org']);
+
+    function iconNormName(s) {
+      return String(s || '').toLowerCase().trim()
+        .replace(/[\s_]*cli$/, '').replace(/^cli[\s_-]*/, '').replace(/[\s_\-./]+/g, '');
+    }
+    function iconDomainFromUrl(u) { try { return new URL(u).hostname.replace(/^www\./, ''); } catch (_) { return ''; } }
+    // Multi-source <img> fallback: walk data-fb (pipe-separated URLs) before degrading to a monogram.
+    window.iconFallback = function (img) {
+      const fbs = (img.getAttribute('data-fb') || '').split('|').filter(Boolean);
+      if (fbs.length) { const next = fbs.shift(); img.setAttribute('data-fb', fbs.join('|')); if (next.indexOf('simpleicons') === -1) img.classList.add('raw'); img.src = next; return; }
+      const span = document.createElement('span'); span.className = 'icon-mono';
+      span.textContent = img.getAttribute('data-letter') || '?';
+      img.replaceWith(span);
+    };
+    // Cross-reference resolver: alias (synonym) → exact key → containment (fuzzy) scan.
+    function resolveIconKey(name) {
+      const n = iconNormName(name);
+      if (!n) return '';
+      if (ICON_ALIASES[n]) return ICON_ALIASES[n];
+      if (ICON_REGISTRY[n] || ICON_DOMAINS[n]) return n;
+      const keys = Object.keys(ICON_ALIASES).concat(Object.keys(ICON_REGISTRY), Object.keys(ICON_DOMAINS));
+      for (const k of keys) { if (k.length >= 3 && (n.includes(k) || k.includes(n))) return ICON_ALIASES[k] || k; }
+      return n;
+    }
+
+    // Tasteful single-letter monogram fallback (one clean letter, palette-tinted tile).
+    function iconMono(label) {
+      const ch = (String(label || '?').trim()[0] || '?').toUpperCase();
+      return `<span class="icon-mono">${esc(ch)}</span>`;
+    }
+    // Resolve a CLI/catalog entry (or bare name string) to a tinted Simple Icons <img>, or
+    // the monogram fallback. extraClass lets callers reuse the tile at different sizes.
+    function iconFor(cli, extraClass) {
+      const obj = (cli && typeof cli === 'object') ? cli : null;
+      const label = obj ? (obj.display_name || obj.name) : String(cli || '');
+      const rawName = String(obj ? obj.name : cli || '');
+      const cls = 'sw-icon' + (extraClass ? ' ' + extraClass : '');
+      const letter = (String(label || '?').trim()[0] || '?').toUpperCase();
+      const key = resolveIconKey(rawName);
+
+      // (1) explicit slug on the entry, then (2) Simple Icons by resolved key or raw name.
+      let slug = obj && typeof obj.icon === 'string' && obj.icon.trim() ? obj.icon.trim().toLowerCase() : '';
+      if (!slug) slug = ICON_REGISTRY[key] || ICON_REGISTRY[iconNormName(rawName)] || '';
+      // (3) real-logo favicon domain: curated first, else the entry's own homepage (skip code hosts).
+      let domain = ICON_DOMAINS[key] || '';
+      if (!domain && obj) { const hp = iconDomainFromUrl(obj.homepage || obj.source_url || ''); if (hp && !ICON_GENERIC_HOSTS.has(hp)) domain = hp; }
+
+      // Ordered source chain → monogram. Simple Icons (clean monochrome) first; then live
+      // favicons widen coverage to apps it lacks (esp. Chinese: Lark, WeCom, MiniMax, DingTalk…).
+      const srcs = [];
+      if (slug) srcs.push(`https://cdn.simpleicons.org/${esc(slug)}`);
+      if (domain) {
+        srcs.push(`https://icons.duckduckgo.com/ip3/${esc(domain)}.ico`);
+        srcs.push(`https://www.google.com/s2/favicons?domain=${esc(domain)}&sz=64`);
+      }
+      if (!srcs.length) return `<span class="${cls}" title="${escAttr(label)}">${iconMono(label)}</span>`;
+      const first = srcs.shift();
+      const rawCls = first.indexOf('simpleicons') === -1 ? ' class="raw"' : '';
+      return `<span class="${cls}" title="${escAttr(label)}"><img${rawCls} loading="lazy" decoding="async" ` +
+        `src="${first}" data-fb="${escAttr(srcs.join('|'))}" data-letter="${escAttr(letter)}" ` +
+        `alt="${escAttr(label)} icon" onerror="iconFallback(this)"></span>`;
+    }
+
+    // Per-category tints follow the ACTIVE palette's accent hue (catHue centres on the
+    // palette accent band and spreads each category a small signed offset around it), so the
+    // whole page reads as one colour family that recolours with the palette: warm palettes
+    // (Sand, Blush) get warm tints, cool palettes (Steel, Sky, Mist) stay cool, Sage stays
+    // green. Saturation/lightness are fixed in CSS (legible in both themes); we only vary hue.
+    const TINT_SPREAD = 25; // categories fan ±~25° around the palette accent hue
+    // ordered offsets in [-1, 1]; scaled by TINT_SPREAD so the spread tracks the band
+    const CATEGORY_OFFSET = {
+      video: -0.30, knowledge: 0, '3d': 0.58, game: -0.74, image: 1.0,
+      ai: 0.30, audio: -0.52, dev: 0.15, design: 0.86, productivity: -0.15,
+      creative: 0.72, web: 0, data: -0.38, science: 0.44, business: 0.22, other: 0
+    };
+    // hues wrap on the 0–360 circle (Blush's ~3° accent fans into both reds and oranges)
+    function wrapHue(h) { return ((h % 360) + 360) % 360; }
+    function catHue(cat) {
+      const band = parseFloat(getComputedStyle(document.documentElement).getPropertyValue('--accent-band')) || 209;
+      const key = String(cat || 'other');
+      let norm;
+      if (Object.prototype.hasOwnProperty.call(CATEGORY_OFFSET, key)) {
+        norm = CATEGORY_OFFSET[key];
+      } else {
+        // deterministic offset in [-1, 1] for any unlisted category
+        let h = 0; for (let i = 0; i < key.length; i++) h = (h * 31 + key.charCodeAt(i)) % 101;
+        norm = (h - 50) / 50;
+      }
+      return wrapHue(Math.round(band + norm * TINT_SPREAD));
+    }
+
+    // Recompute per-category --ch in place whenever the palette (accent band) changes,
+    // so tints re-bias toward the new accent without losing card/scroll/flip state.
+    function rerenderTints() {
+      document.querySelectorAll('[data-cat]').forEach(el => {
+        el.style.setProperty('--ch', String(catHue(el.dataset.cat)));
+      });
+      // scope banner follows the scoped matrix's hue
+      const sb = document.getElementById('scopeBanner');
+      if (sb && STATE.scope) {
+        const m = STATE.matrices.find(x => x.name === STATE.scope);
+        if (m) sb.style.setProperty('--ch', String(catHue(m.category)));
+      }
+    }
 
     let harnessClis = [];
     let publicClis = [];
     let activeDeck = 'harness';
+    let deckSuspendTimer = null;
+    // Collapse heavy effects (glass blur, the 3D flip contexts, sticky-nav blur, grain) for the
+    // duration of ANY deck movement — drag or animated switch — so panels translate as flat,
+    // GPU-cached layers. This is what makes the slide smooth on Safari. Auto-clears 560ms after
+    // the last movement (covers the .5s settle transition); each move resets the timer.
+    function armDeckSuspend() {
+      document.documentElement.classList.add('deck-sliding');
+      clearTimeout(deckSuspendTimer);
+      deckSuspendTimer = setTimeout(() => document.documentElement.classList.remove('deck-sliding'), 560);
+    }
     let wheelSwitchLockUntil = 0;
 
-    const deckGesture = {
-      pointerId: null,
-      startX: 0,
-      deltaX: 0,
-      dragging: false,
-    };
-
-    // Per-deck state
+    const deckGesture = { pointerId: null, startX: 0, deltaX: 0, dragging: false };
     const deckState = {
       harness: { filter: 'all', sort: 'updated', query: '' },
       public:  { filter: 'all', sort: 'updated', query: '' },
@@ -2155,35 +1660,27 @@ <h3>Empower yourself &mdash; <span>your CLI toolkit</span></h3>
 
     async function fetchJson(urls) {
       for (const url of urls) {
-        try {
-          const resp = await fetch(url);
-          if (resp.ok) return await resp.json();
-        } catch (_) { continue; }
+        try { const resp = await fetch(url); if (resp.ok) return await resp.json(); }
+        catch (_) { continue; }
       }
       return null;
     }
 
     function formatCompactCount(value) {
       return new Intl.NumberFormat('en', {
-        notation: 'compact',
-        maximumFractionDigits: value >= 10000 ? 0 : 1,
+        notation: 'compact', maximumFractionDigits: value >= 10000 ? 0 : 1,
       }).format(value);
     }
-
     function formatBadgeCount(value) {
       if (typeof value !== 'string') return null;
       const label = value.trim();
       return label ? label.toUpperCase() : null;
     }
-
     function renderGitHubStars(label, title) {
       document.querySelectorAll('[data-github-stars]').forEach(el => {
-        el.textContent = label;
-        el.setAttribute('aria-label', title);
-        el.title = title;
+        el.textContent = label; el.setAttribute('aria-label', title); el.title = title;
       });
     }
-
     async function loadGitHubStars() {
       try {
         try {
@@ -2191,47 +1688,32 @@ <h3>Empower yourself &mdash; <span>your CLI toolkit</span></h3>
           if (badgeResp.ok) {
             const badge = await badgeResp.json();
             const badgeLabel = formatBadgeCount(badge.message || badge.value);
-            if (badgeLabel) {
-              renderGitHubStars(badgeLabel, `${badgeLabel} GitHub stars`);
-              return;
-            }
+            if (badgeLabel) { renderGitHubStars(badgeLabel, `${badgeLabel} GitHub stars`); return; }
           }
         } catch (_) {}
-
-        const resp = await fetch(GITHUB_REPO_API, {
-          headers: { 'Accept': 'application/vnd.github+json' }
-        });
+        const resp = await fetch(GITHUB_REPO_API, { headers: { 'Accept': 'application/vnd.github+json' } });
         if (!resp.ok) return;
-
         const repo = await resp.json();
         const stars = repo.stargazers_count;
         if (typeof stars !== 'number') return;
-
         renderGitHubStars(formatCompactCount(stars), `${stars.toLocaleString('en-US')} GitHub stars`);
-      } catch (_) {
-        // Keep fallback placeholder when GitHub API is unavailable.
-      }
+      } catch (_) {}
     }
 
     async function loadRegistries() {
       try {
         const [harnessData, publicData, dates] = await Promise.all([
-          fetchJson(REGISTRY_URLS),
-          fetchJson(PUBLIC_REGISTRY_URLS),
-          fetchJson(DATES_URLS),
+          fetchJson(REGISTRY_URLS), fetchJson(PUBLIC_REGISTRY_URLS), fetchJson(DATES_URLS),
         ]);
-
         if (!harnessData) throw new Error('Registry load failed');
 
         harnessClis = harnessData.clis;
         if (dates) harnessClis.forEach(c => c.last_modified = dates[c.name]);
-
         if (publicData && publicData.clis) {
           publicClis = publicData.clis;
           if (dates) publicClis.forEach(c => c.last_modified = dates[c.name]);
         }
 
-        // Update counts
         const totalClis = harnessClis.length + publicClis.length;
         const allCategories = [...new Set([...harnessClis, ...publicClis].map(c => c.category))];
         animateCount(document.getElementById('cli-count'), totalClis, 980);
@@ -2239,21 +1721,53 @@ <h3>Empower yourself &mdash; <span>your CLI toolkit</span></h3>
         document.getElementById('deck-count-harness').textContent = harnessClis.length;
         document.getElementById('deck-count-public').textContent = publicClis.length;
 
-        // Build filters for harness deck (initial)
         const harnessCats = [...new Set(harnessClis.map(c => c.category))];
         buildFilters('harness', harnessCats);
-
         const publicCats = [...new Set(publicClis.map(c => c.category))];
         buildFilters('public', publicCats);
 
+        // Build name -> entry map for the unification join (harness wins on name clash)
+        STATE.byName.clear();
+        publicClis.forEach(c => { c._deck = 'public'; STATE.byName.set(c.name, c); });
+        harnessClis.forEach(c => { c._deck = 'harness'; STATE.byName.set(c.name, c); });
+
         renderDeck('harness');
         renderDeck('public');
+
+        loadMatrices();
       } catch (e) {
         document.getElementById('grid-harness').innerHTML =
           '<div class="empty">Failed to load registry. <a href="' + REPO + '/blob/main/registry.json" style="color:var(--accent)">View source</a></div>';
       }
     }
 
+    // ── Matrices (the unification): fetch registry, build membership, render flip cards ──
+    async function loadMatrices() {
+      const data = await fetchJson(MATRIX_URLS);
+      const shelf = document.getElementById('shelf');
+      if (!data || !Array.isArray(data.matrices) || !data.matrices.length) {
+        if (shelf) shelf.innerHTML = '<div class="empty">Could not load the matrix registry right now &mdash; the catalog below is unaffected. Try refreshing, or browse on <a href="' + REPO + '" target="_blank" rel="noopener">GitHub</a>.</div>';
+        const ms = document.getElementById('mat-stat'); if (ms) ms.textContent = '';
+        return;
+      }
+      STATE.matrices = data.matrices;
+      STATE.membership.clear();
+      STATE.matrices.forEach(m => {
+        (m.clis || []).forEach(n => {
+          if (!STATE.membership.has(n)) STATE.membership.set(n, []);
+          STATE.membership.get(n).push(m);
+        });
+      });
+      const capCount = STATE.matrices.reduce((s, m) => s + ((m.capabilities && m.capabilities.length) || 0), 0);
+      const ms = document.getElementById('mat-stat');
+      if (ms) ms.textContent = STATE.matrices.length + ' matrices · ' + capCount + ' capabilities';
+      renderShelf();
+      // re-render decks so membership chips appear on catalog cards
+      renderDeck('harness');
+      renderDeck('public');
+      syncFlipA11y();
+    }
+
     const CATEGORY_LABELS = { 'ai': 'AI', '3d': '3D' };
     function catLabel(cat) {
       return CATEGORY_LABELS[cat] || cat.charAt(0).toUpperCase() + cat.slice(1);
@@ -2293,11 +1807,14 @@ <h3>Empower yourself &mdash; <span>your CLI toolkit</span></h3>
       activeDeck = deck;
       const track = document.getElementById('deck-track');
       track.dataset.active = deck;
+      armDeckSuspend();
       updateDeckPosition();
       document.querySelectorAll('.deck-tab').forEach(t => {
         t.classList.toggle('active', t.dataset.deck === deck);
       });
-      // Update toggle button
+      document.querySelectorAll('.deck-dot').forEach(d => {
+        d.classList.toggle('active', d.dataset.deck === deck);
+      });
       const toggle = document.getElementById('deck-toggle');
       if (deck === 'harness') {
         toggle.querySelector('span').textContent = 'Public CLIs';
@@ -2309,120 +1826,87 @@ <h3>Empower yourself &mdash; <span>your CLI toolkit</span></h3>
         toggle.classList.add('deck-arrow-btn--back');
       }
     }
-
-    function toggleDeck() {
-      switchDeck(activeDeck === 'harness' ? 'public' : 'harness');
-    }
+    function toggleDeck() { switchDeck(activeDeck === 'harness' ? 'public' : 'harness'); }
 
     function getDeckMetrics() {
-      const stage = document.querySelector('.deck-stage');
       const viewport = document.querySelector('.deck-viewport');
       const track = document.getElementById('deck-track');
-      if (!stage || !viewport || !track) return null;
-
-      const peek = parseFloat(getComputedStyle(stage).getPropertyValue('--deck-peek')) || 0;
-      const panelWidth = Math.max(viewport.clientWidth - peek, 0);
-      return {
-        viewport,
-        track,
-        panelWidth,
-        maxShift: Math.max(panelWidth - peek, 0),
-      };
+      if (!viewport || !track) return null;
+      // Each panel is exactly one viewport wide, so the slide distance is the viewport width.
+      const panelWidth = viewport.clientWidth;
+      return { viewport, track, panelWidth, maxShift: panelWidth };
     }
-
     function setDeckTransform(offset = 0) {
       const metrics = getDeckMetrics();
       if (!metrics) return;
-      const { viewport, track, panelWidth, maxShift } = metrics;
-      viewport.style.setProperty('--deck-panel-width', `${panelWidth}px`);
+      const { track, maxShift } = metrics;
       const baseShift = activeDeck === 'public' ? -maxShift : 0;
       const clampedShift = Math.min(0, Math.max(-maxShift, baseShift + offset));
       track.style.transform = `translateX(${clampedShift}px)`;
     }
-
-    function updateDeckPosition() {
-      setDeckTransform();
-    }
+    function updateDeckPosition() { setDeckTransform(); }
 
     function finishDeckDrag() {
       const viewport = document.querySelector('.deck-viewport');
       const track = document.getElementById('deck-track');
       if (viewport) viewport.classList.remove('dragging');
       if (track) track.classList.remove('is-dragging');
-      deckGesture.pointerId = null;
-      deckGesture.startX = 0;
-      deckGesture.deltaX = 0;
-      deckGesture.dragging = false;
+      deckGesture.pointerId = null; deckGesture.startX = 0; deckGesture.deltaX = 0; deckGesture.dragging = false;
     }
-
     function initDeckGestures() {
       const viewport = document.querySelector('.deck-viewport');
       const track = document.getElementById('deck-track');
       if (!viewport || !track) return;
-
       const isInteractiveTarget = (target) => !!target.closest('a, button, input, select, textarea, label');
 
       viewport.addEventListener('pointerdown', (e) => {
         if (e.pointerType === 'mouse' && e.button !== 0) return;
         if (isInteractiveTarget(e.target)) return;
-        deckGesture.pointerId = e.pointerId;
-        deckGesture.startX = e.clientX;
-        deckGesture.deltaX = 0;
-        deckGesture.dragging = true;
-        viewport.classList.add('dragging');
-        track.classList.add('is-dragging');
+        deckGesture.pointerId = e.pointerId; deckGesture.startX = e.clientX; deckGesture.deltaX = 0; deckGesture.dragging = true;
+        viewport.classList.add('dragging'); track.classList.add('is-dragging');
         if (viewport.setPointerCapture) viewport.setPointerCapture(e.pointerId);
       });
-
       viewport.addEventListener('pointermove', (e) => {
         if (!deckGesture.dragging || e.pointerId !== deckGesture.pointerId) return;
         deckGesture.deltaX = e.clientX - deckGesture.startX;
+        armDeckSuspend();
         setDeckTransform(deckGesture.deltaX);
       });
-
       const endDrag = (e) => {
         if (!deckGesture.dragging || e.pointerId !== deckGesture.pointerId) return;
         const deltaX = deckGesture.deltaX;
         finishDeckDrag();
-        if (activeDeck === 'harness' && deltaX < -60) {
-          switchDeck('public');
-          return;
-        }
-        if (activeDeck === 'public' && deltaX > 60) {
-          switchDeck('harness');
-          return;
-        }
+        if (activeDeck === 'harness' && deltaX < -60) { switchDeck('public'); return; }
+        if (activeDeck === 'public' && deltaX > 60) { switchDeck('harness'); return; }
         updateDeckPosition();
       };
-
       viewport.addEventListener('pointerup', endDrag);
       viewport.addEventListener('pointercancel', endDrag);
       viewport.addEventListener('lostpointercapture', () => {
         if (!deckGesture.dragging) return;
-        finishDeckDrag();
-        updateDeckPosition();
+        finishDeckDrag(); updateDeckPosition();
       });
-
       viewport.addEventListener('wheel', (e) => {
         const now = Date.now();
         if (now < wheelSwitchLockUntil) return;
         if (Math.abs(e.deltaX) < 24 || Math.abs(e.deltaX) <= Math.abs(e.deltaY)) return;
         e.preventDefault();
-        if (e.deltaX > 0 && activeDeck !== 'public') {
-          switchDeck('public');
-          wheelSwitchLockUntil = now + 450;
-        } else if (e.deltaX < 0 && activeDeck !== 'harness') {
-          switchDeck('harness');
-          wheelSwitchLockUntil = now + 450;
-        }
+        if (e.deltaX > 0 && activeDeck !== 'public') { switchDeck('public'); wheelSwitchLockUntil = now + 450; }
+        else if (e.deltaX < 0 && activeDeck !== 'harness') { switchDeck('harness'); wheelSwitchLockUntil = now + 450; }
       }, { passive: false });
     }
 
     function renderDeck(deck) {
-      const clis = deck === 'harness' ? harnessClis : publicClis;
+      let clis = deck === 'harness' ? harnessClis : publicClis;
       const state = deckState[deck];
       const query = state.query.toLowerCase();
 
+      // matrix scoping: restrict to the scoped matrix's member CLIs
+      if (STATE.scope) {
+        const m = STATE.matrices.find(x => x.name === STATE.scope);
+        if (m) { const set = new Set(m.clis || []); clis = clis.filter(c => set.has(c.name)); }
+      }
+
       const filtered = clis.filter(c => {
         const matchFilter = state.filter === 'all' || c.category === state.filter;
         const matchSearch = !query ||
@@ -2444,12 +1928,54 @@ <h3>Empower yourself &mdash; <span>your CLI toolkit</span></h3>
         grid.innerHTML = '<div class="empty">No CLIs match your search.</div>';
         return;
       }
-
-      if (deck === 'harness') {
-        grid.innerHTML = filtered.map(renderHarnessCard).join('');
-      } else {
-        grid.innerHTML = filtered.map(renderNpmCard).join('');
-      }
+      if (deck === 'harness') grid.innerHTML = filtered.map(renderHarnessCard).join('');
+      else grid.innerHTML = filtered.map(renderNpmCard).join('');
+      layoutMasonry(grid);
+    }
+
+    // ── Engine-independent JS masonry: shortest-column distribution ──
+    // Rebuilds the grid's .grid-col wrappers from the current set of .card elements and
+    // drops each next card into the currently shortest column. Idempotent / re-runnable.
+    function masonryColumnCount(grid) {
+      // Measure the grid's OWN usable width (capped by max-width), not the over-wide
+      // swipe-carousel panel it lives in. clientWidth already reflects the max-width cap.
+      const w = grid.clientWidth || grid.getBoundingClientRect().width || 0;
+      if (w >= 900) return 3;
+      if (w >= 600) return 2;
+      return 1;
+    }
+    function layoutMasonry(grid) {
+      if (!grid) return;
+      // Collect the current card set (whether loose or already inside columns).
+      const cards = Array.from(grid.querySelectorAll(':scope > .card, :scope > .grid-col > .card'));
+      if (!cards.length) return; // empty/error states render a bare .empty div — leave it
+      const cols = masonryColumnCount(grid);
+
+      // Rebuild column wrappers from scratch so the layout is fully re-runnable. The
+      // wrappers must be live in the DOM so offsetHeight reflects real laid-out height as
+      // we go, which is what makes the shortest-column placement correct.
+      grid.innerHTML = '';
+      const wrappers = [];
+      for (let i = 0; i < cols; i++) {
+        const col = document.createElement('div');
+        col.className = 'grid-col';
+        grid.appendChild(col);
+        wrappers.push(col);
+      }
+      // Place each card into the currently shortest column, preserving overall card order.
+      cards.forEach(card => {
+        let target = wrappers[0];
+        let min = wrappers[0].offsetHeight;
+        for (let i = 1; i < wrappers.length; i++) {
+          const h = wrappers[i].offsetHeight;
+          if (h < min) { min = h; target = wrappers[i]; }
+        }
+        target.appendChild(card);
+      });
+    }
+    function relayoutAllGrids() {
+      layoutMasonry(document.getElementById('grid-harness'));
+      layoutMasonry(document.getElementById('grid-public'));
     }
 
     function repoSkillId(skillPath) {
@@ -2457,42 +1983,24 @@ <h3>Empower yourself &mdash; <span>your CLI toolkit</span></h3>
       const match = skillPath.match(/^skills\/([^/]+)\/SKILL\.md$/);
       return match ? match[1] : '';
     }
-
-    function isWebUrl(value) {
-      return /^https?:\/\//i.test(value || '');
-    }
-
-    function isRepoSkillPath(value) {
-      return !/\s/.test(value || '') && /(^\.{0,2}\/|\/|\.md$|\.txt$)/i.test(value || '');
-    }
-
+    function isWebUrl(value) { return /^https?:\/\//i.test(value || ''); }
+    function isRepoSkillPath(value) { return !/\s/.test(value || '') && /(^\.{0,2}\/|\/|\.md$|\.txt$)/i.test(value || ''); }
     function normalizeNpxSkillsCmd(cmd) {
       if (!cmd) return '';
       const trimmed = cmd.trim();
       if (!trimmed.startsWith('npx skills add ')) return '';
-      return trimmed
-        .replace(/\s+-g\b/g, '')
-        .replace(/\s+-y\b/g, '')
-        .trim() + ' -g -y';
+      return trimmed.replace(/\s+-g\b/g, '').replace(/\s+-y\b/g, '').trim() + ' -g -y';
     }
-
     function harnessSkillCmd(c) {
       const skillId = repoSkillId(c.skill_md);
       return skillId ? `npx skills add ${REPO_SKILLS_SOURCE} --skill ${skillId} -g -y` : '';
     }
-
-    function publicSkillCmd(c) {
-      return normalizeNpxSkillsCmd(c.skill_md);
-    }
+    function publicSkillCmd(c) { return normalizeNpxSkillsCmd(c.skill_md); }
 
     function renderSkillAction(value) {
       if (!value) return '';
-      if (isWebUrl(value)) {
-        return `<a href="${esc(value)}" target="_blank">Skill</a>`;
-      }
-      if (isRepoSkillPath(value)) {
-        return `<a href="${REPO}/blob/main/${esc(value)}" target="_blank">Skill</a>`;
-      }
+      if (isWebUrl(value)) return `<a href="${esc(value)}" target="_blank">Skill</a>`;
+      if (isRepoSkillPath(value)) return `<a href="${REPO}/blob/main/${esc(value)}" target="_blank">Skill</a>`;
       return `
         <span class="skill-popover">
           <button class="card-link-btn skill-trigger" type="button" aria-expanded="false" data-skill-value="${escAttr(value)}">Skill</button>
@@ -2504,32 +2012,323 @@ <h3>Empower yourself &mdash; <span>your CLI toolkit</span></h3>
         </span>`;
     }
 
-    function renderInstallStack(steps) {
-      const display = steps.map((step) =>
-        `<span class="install-comment"># ${esc(step.label.toLowerCase())}</span><span class="install-command">${esc(step.cmd)}</span>`
-      ).join('');
-      const copyText = steps.map((step) =>
-        `# ${step.label.toLowerCase()}\n${step.cmd}`
-      ).join('\n');
-      return `<div class="card-install">
-        <code>${display}</code>
-        <button class="card-copy-btn" onclick='copyCmd(this, ${JSON.stringify(copyText)})'>Copy</button>
+    // FRONT-face Skill control: small icon+label consistent with the card visual language.
+    // Same three cases as renderSkillAction (web URL → link, repo skill path → link,
+    // npx popover → trigger + popover), with the header SKILL icon prepended.
+    function renderSkillFront(value) {
+      if (!value) return '';
+      if (isWebUrl(value)) return `<a class="card-skill-front" href="${esc(value)}" target="_blank">${SKILL_ICON_SVG}<span>Skill</span></a>`;
+      if (isRepoSkillPath(value)) return `<a class="card-skill-front" href="${REPO}/blob/main/${esc(value)}" target="_blank">${SKILL_ICON_SVG}<span>Skill</span></a>`;
+      return `
+        <span class="skill-popover">
+          <button class="card-skill-front skill-trigger" type="button" aria-expanded="false" data-skill-value="${escAttr(value)}">${SKILL_ICON_SVG}<span>Skill</span></button>
+          <span class="skill-popover-panel">
+            <span class="skill-popover-label">Skill install</span>
+            <code>${esc(value)}</code>
+            <button class="card-copy-btn skill-popover-copy" type="button" data-copy-value="${escAttr(value)}">Copy</button>
+          </span>
+        </span>`;
+    }
+
+    // Clean install box: just the command lines (NO inline "# step …" comments) + Copy-all.
+    // `label` is a short plain-language hint rendered ABOVE the box; `numbered` adds tiny
+    // 1·2 step markers in that label when there are two commands.
+    function renderInstallStack(steps, label, numbered) {
+      const cmds = steps.map(s => s.cmd);
+      const display = cmds.map(cmd => `<span class="install-command">${esc(cmd)}</span>`).join('');
+      const copyText = cmds.join('\n');
+      let head = '';
+      if (label) {
+        head = `<div class="install-steps-label">${esc(label)}</div>`;
+      } else if (numbered && cmds.length === 2) {
+        head = `<div class="install-steps-label"><span class="isl-num">1</span>Install the CLI<span class="isl-sep">·</span><span class="isl-num">2</span>add the skill</div>`;
+      }
+      return `<div class="install-steps">
+        ${head}
+        <div class="card-install">
+          <code>${display}</code>
+          <button class="card-copy-btn" onclick='copyCmd(this, ${JSON.stringify(copyText)})'>Copy</button>
+        </div>
       </div>`;
     }
 
+    // ── 3D flip card shell ──
+    // front = important info (title, desc, category, version, primary install copy)
+    // back  = full install command, requires, entry_point/direct cmd, source/skill links, contributors
+    function flipCardShell(c, hue, frontHTML, backHTML) {
+      const titleText = esc(c.display_name || c.name);
+      return `
+        <div class="card" id="tool-${cssId(c.name)}" style="--ch:${hue}" data-cat="${escAttr(c.category || 'other')}">
+          <div class="card-sizer" aria-hidden="true">
+            <div class="card-face card-front">${frontHTML}</div>
+            <div class="card-face card-back">${backHTML}</div>
+          </div>
+          <div class="card-inner">
+            <div class="card-face card-front">${frontHTML}</div>
+            <div class="card-face card-back" aria-hidden="true">${backHTML}</div>
+          </div>
+        </div>`;
+    }
+
+    function flipAffordance() {
+      return `<button class="flip-btn flip-toggle" type="button" aria-label="Show details, requirements and links" aria-pressed="false"><span>Details</span>${DETAILS_GLYPH}</button>`;
+    }
+    function flipBackBtn() {
+      return `<button class="flip-btn flip-btn--back flip-toggle" type="button" aria-label="Back to overview" aria-pressed="true">${BACK_GLYPH}<span>Back</span></button>`;
+    }
+
+    // ── Matrix card rendering (FLIP metaphor, lifted from Gallery D, re-themed) ──
+    const MATRIX_GLYPH = {
+      video: '<path d="m22 8-6 4 6 4V8z"/><rect x="2" y="6" width="14" height="12" rx="2"/>',
+      knowledge: '<path d="M4 19.5A2.5 2.5 0 0 1 6.5 17H20"/><path d="M6.5 2H20v20H6.5A2.5 2.5 0 0 1 4 19.5v-15A2.5 2.5 0 0 1 6.5 2z"/>',
+      '3d': '<path d="M12 2 2 7l10 5 10-5-10-5z"/><path d="m2 17 10 5 10-5M2 12l10 5 10-5"/>',
+      game: '<rect x="2" y="6" width="20" height="12" rx="4"/><path d="M6 12h4M8 10v4"/><circle cx="16" cy="11" r="1"/><circle cx="18.5" cy="13.5" r="1"/>',
+      image: '<rect x="3" y="3" width="18" height="18" rx="3"/><circle cx="9" cy="9" r="2"/><path d="m21 15-5-5L5 21"/>'
+    };
+    function matrixGlyph(cat) { return MATRIX_GLYPH[cat] || MATRIX_GLYPH.knowledge; }
+    const PK_LABEL = {
+      'agent-native': 'Agent-native', 'public-cli': 'Public CLI', 'harness-cli': 'Harness CLI',
+      'agent-skill': 'Agent skill', 'bundled-script': 'Bundled script', 'api': 'API',
+      'native': 'Native', 'python': 'Python', 'web-search': 'Web search'
+    };
+    const PK_KNOWN = { 'agentnative':1,'publiccli':1,'harnesscli':1,'agentskill':1,'bundledscript':1,'api':1,'native':1,'python':1,'websearch':1 };
+    function pkClass(k) {
+      const c = String(k || '').replace(/-/g, '');
+      return PK_KNOWN[c] ? ('pk-' + c) : 'pk-fallback';
+    }
+    function initials(s) {
+      const parts = String(s).replace(/[^A-Za-z0-9 ]/g, ' ').trim().split(/\s+/);
+      if (parts.length === 1) return parts[0].slice(0, 2);
+      return (parts[0][0] || '') + (parts[1][0] || '');
+    }
+    function firstSentence(s) {
+      if (!s) return '';
+      const i = s.indexOf('. ');
+      return (i > 0 && i < 90) ? s.slice(0, i + 1) : (s.length > 96 ? s.slice(0, 95) + '…' : s);
+    }
+    function matrixCmdRow(cmd) {
+      return `<div class="mcmd"><code><span class="pfx">$ </span>${esc(cmd)}</code>` +
+        `<button class="card-copy-btn" type="button" onclick='copyCmd(this, ${JSON.stringify(cmd)})'>Copy</button></div>`;
+    }
+
+    function renderShelf() {
+      const shelf = document.getElementById('shelf');
+      if (!shelf) return;
+      if (!STATE.matrices.length) { shelf.innerHTML = '<div class="empty">No matrices found in the registry.</div>'; return; }
+      shelf.innerHTML = STATE.matrices.map(matrixFlipCard).join('');
+    }
+
+    function matrixFlipCard(m) {
+      const hue = catHue(m.category);
+      const members = m.clis || [];
+      const caps = m.capabilities || [];
+      const install = 'cli-hub matrix install ' + m.name;
+      const preflight = 'cli-hub matrix preflight ' + m.name;
+      const glyph = `<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linejoin="round" stroke-linecap="round">${matrixGlyph(m.category)}</svg>`;
+
+      // FRONT — cover: display_name, id chip, description, counts, member software icons, primary install copy
+      const memberIcons = members.slice(0, 6).map(n => {
+        const t = STATE.byName.get(n);
+        return iconFor(t || n, t ? '' : 'miss');
+      }).join('');
+      const moreN = members.length - 6;
+      const front = `
+        <div class="mcard-top">
+          <span class="mcard-glyph">${glyph}</span>
+        </div>
+        <h3>${esc(m.display_name || m.name)}</h3>
+        <p class="mdesc">${esc(m.description || '')}</p>
+        <div class="meta-row"><span><b>${caps.length}</b> capabilities</span><span><b>${members.length}</b> CLIs</span></div>
+        <div class="icon-stack">${memberIcons}${moreN > 0 ? `<span class="more">+${moreN}</span>` : ''}</div>
+        ${matrixCmdRow(install)}
+        <div class="mcard-front-foot">
+          <span class="flip-hint">Flip: ${caps.length} capabilities, providers &amp; tools</span>
+          ${flipAffordance()}
+        </div>`;
+
+      // BACK — full capability list, both commands, member chips, scope action (internally scrolling)
+      const capsHtml = caps.map(c => {
+        const io = []
+          .concat((c.inputs || []).map(x => `<span>${esc(x)}</span>`))
+          .concat((c.outputs || []).map(x => `<span class="out">${esc(x)} →</span>`))
+          .join('');
+        const provs = (c.providers || []).map(p => {
+          const meta = [];
+          if (p.cost_tier) meta.push(esc(p.cost_tier));
+          if (p.quality_tier) meta.push(esc(p.quality_tier) + ' quality');
+          if (p.offline) meta.push('offline');
+          if (p.requires) meta.push('needs ' + esc(p.requires));
+          return `<div class="prov">` +
+            `<span class="pk ${pkClass(p.kind)}">${esc(PK_LABEL[p.kind] || p.kind || 'other')}</span>` +
+            `<div class="pbody"><b>${esc(p.name || '')}</b>` +
+            (meta.length ? `<div class="pmeta">${meta.join(' · ')}</div>` : '') +
+            (p.notes ? `<div class="pnotes">${esc(p.notes)}</div>` : '') +
+            `</div></div>`;
+        }).join('');
+        return `<details class="cap">` +
+          `<summary><span class="cap-id">${esc(c.id || '')}</span><span class="cap-title">${esc(firstSentence(c.intent))}</span>` +
+          `<svg class="chev" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.2"><path d="m9 6 6 6-6 6"/></svg></summary>` +
+          `<div class="cap-detail">` +
+            `<p class="cap-intent">${esc(c.intent || '')}</p>` +
+            (io ? `<div class="io">${io}</div>` : '') +
+            provs +
+          `</div></details>`;
+      }).join('');
+
+      const memberChips = members.map(n => {
+        const t = STATE.byName.get(n);
+        if (!t) return `<button class="miss" type="button" disabled>${esc(n)}<span class="badge-mini">unlisted</span></button>`;
+        const bk = t._deck === 'public' ? 'public' : 'harness';
+        return `<button type="button" data-goto="${escAttr(t.name)}">${esc(t.display_name || t.name)}<span class="badge-mini">${bk}</span></button>`;
+      }).join('');
+
+      const skillLink = m.skill_md
+        ? `<a class="mbtn" href="${m.skill_md.startsWith('http') ? esc(m.skill_md) : `${REPO}/blob/main/${esc(m.skill_md)}`}" target="_blank" rel="noopener"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M14 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8z"/><path d="M14 2v6h6"/></svg>SKILL.md</a>`
+        : '';
+
+      const back = `
+        <div class="card-back-head">
+          <span class="card-back-title">${esc(m.display_name || m.name)} · ${esc(m.matrix_id || '')}</span>
+          ${flipBackBtn()}
+        </div>
+        <div class="mback-scroll">
+          <div class="msub">Install &amp; preflight</div>
+          ${matrixCmdRow(install)}
+          ${matrixCmdRow(preflight)}
+          <div class="msub">${caps.length} capabilities · intent → providers</div>
+          ${capsHtml || '<p style="color:var(--ink-3);font-size:.82rem">No capabilities listed.</p>'}
+          <div class="msub">${members.length} member CLIs <span style="font-weight:400;text-transform:none;letter-spacing:0;color:var(--ink-3)">— tap to jump into the catalog</span></div>
+          <div class="member">${memberChips}</div>
+          <div class="mback-cta">
+            <button class="mbtn primary" type="button" data-scope="${escAttr(m.name)}"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M3 6h18M7 12h10M11 18h2"/></svg>Show only these ${members.length} tools</button>
+            ${skillLink}
+          </div>
+        </div>`;
+
+      return `
+        <div class="mcard" style="--ch:${hue}" data-cat="${escAttr(m.category || 'other')}" data-matrix="${escAttr(m.name)}">
+          <div class="card-sizer" aria-hidden="true">
+            <div class="card-face card-front">${front}</div>
+            <div class="card-face card-back">${back}</div>
+          </div>
+          <div class="card-inner">
+            <div class="card-face card-front">${front}</div>
+            <div class="card-face card-back" aria-hidden="true">${back}</div>
+          </div>
+        </div>`;
+    }
+
+    // open a matrix card (flip it + scroll into view) — used by catalog membership chips
+    function openMatrix(name) {
+      const card = document.querySelector('.mcard[data-matrix="' + cssEsc(name) + '"]');
+      if (!card) return;
+      document.getElementById('matrices').scrollIntoView({ behavior: 'smooth', block: 'start' });
+      requestAnimationFrame(() => setCardFlipped(card, true));
+    }
+    function cssEsc(s) { return String(s).replace(/["\\]/g, '\\$&'); }
+    function cssId(s) { return String(s).replace(/[^A-Za-z0-9_-]/g, '_'); }
+
+    // ── Catalog scoping + jump-to-tool (the bidirectional stitching) ──
+    function jumpToTool(name) {
+      // clear any scope/filter so the tool is guaranteed visible, switch to its deck
+      const t = STATE.byName.get(name);
+      clearScope(true);
+      const deck = (t && t._deck === 'public') ? 'public' : 'harness';
+      deckState.harness.filter = 'all'; deckState.public.filter = 'all';
+      deckState[deck].query = '';
+      const si = document.getElementById('search-' + deck); if (si) si.value = '';
+      setFilter(deck, 'all');
+      switchDeck(deck);
+      requestAnimationFrame(() => {
+        const el = document.getElementById('tool-' + cssId(name));
+        if (el) {
+          el.scrollIntoView({ behavior: 'smooth', block: 'center' });
+          const card = el.querySelector('.card-face') ? el : el;
+          el.classList.remove('flash'); void el.offsetWidth; el.classList.add('flash');
+        }
+      });
+    }
+
+    function applyScope(matName) {
+      const m = STATE.matrices.find(x => x.name === matName);
+      if (!m) return;
+      STATE.scope = matName;
+      // reset both decks' filters/search so every scoped member is visible
+      deckState.harness.filter = 'all'; deckState.harness.query = '';
+      deckState.public.filter = 'all'; deckState.public.query = '';
+      const sh = document.getElementById('search-harness'); if (sh) sh.value = '';
+      const sp = document.getElementById('search-public'); if (sp) sp.value = '';
+      setFilter('harness', 'all'); setFilter('public', 'all');
+      updateScopeBanner();
+      renderDeck('harness'); renderDeck('public');
+      syncFlipA11y();
+      // surface whichever deck holds more of the matrix's members
+      const set = new Set(m.clis || []);
+      const inHarness = harnessClis.filter(c => set.has(c.name)).length;
+      const inPublic = publicClis.filter(c => set.has(c.name)).length;
+      switchDeck(inPublic > inHarness ? 'public' : 'harness');
+      const nav = document.querySelector('.deck-nav');
+      if (nav) nav.scrollIntoView({ behavior: 'smooth', block: 'start' });
+    }
+    function clearScope(silent) {
+      STATE.scope = null;
+      updateScopeBanner();
+      if (!silent) { renderDeck('harness'); renderDeck('public'); syncFlipA11y(); }
+    }
+    function updateScopeBanner() {
+      const b = document.getElementById('scopeBanner');
+      if (!b) return;
+      if (STATE.scope) {
+        const m = STATE.matrices.find(x => x.name === STATE.scope);
+        if (!m) { b.classList.remove('on'); return; }
+        b.style.setProperty('--ch', String(catHue(m.category)));
+        const members = (m.clis || []).filter(n => STATE.byName.has(n)).length;
+        document.getElementById('scopeName').textContent = (m.display_name || m.name) + ' (' + (m.matrix_id || '') + ')';
+        document.getElementById('scopeCount').textContent = members;
+        b.classList.add('on');
+      } else {
+        b.classList.remove('on');
+      }
+    }
+    // delegated clicks for member chips / scope / membership chips
+    document.addEventListener('click', (e) => {
+      const goto = e.target.closest('[data-goto]');
+      if (goto && !goto.disabled) { jumpToTool(goto.getAttribute('data-goto')); return; }
+      const scopeBtn = e.target.closest('[data-scope]');
+      if (scopeBtn) { applyScope(scopeBtn.getAttribute('data-scope')); return; }
+      const inM = e.target.closest('[data-openmatrix]');
+      if (inM) { openMatrix(inM.getAttribute('data-openmatrix')); return; }
+    });
+    (function () {
+      const sc = document.getElementById('scopeClear');
+      if (sc) sc.addEventListener('click', () => clearScope(false));
+    })();
+
+    // membership chip ("In S1 · S4") — opens the matrix flip card; the core unification proof
+    function membershipChip(name) {
+      const mems = STATE.membership.get(name) || [];
+      if (!mems.length) return '';
+      const ids = mems.map(m => esc(m.matrix_id || '')).filter(Boolean).join(' · ');
+      const title = mems.length > 1
+        ? ('In ' + mems.length + ' matrices — open ' + (mems[0].display_name || mems[0].name))
+        : ('In ' + (mems[0].display_name || mems[0].name) + ' — open it');
+      return `<button class="in-matrix" type="button" data-openmatrix="${escAttr(mems[0].name)}" title="${escAttr(title)}">In <span class="mid">${ids}</span></button>`;
+    }
+
     function renderHarnessCard(c) {
+      const hue = catHue(c.category);
+      const memChip = membershipChip(c.name);
       const requiresHtml = c.requires
-        ? `<div class="card-requires"><strong>Requires</strong> ${esc(c.requires)}</div>`
-        : '';
-      const skillLink = c.skill_md
-        ? `<a href="${c.skill_md.startsWith('http') ? c.skill_md : `${REPO}/blob/main/${c.skill_md}`}" target="_blank">Skill</a>`
-        : '';
+        ? `<div class="card-requires"><strong>Requires</strong> ${esc(c.requires)}</div>` : '';
+      const skillFront = renderSkillFront(c.skill_md);
       const sourceLink = c.source_url
         ? `<a href="${esc(c.source_url)}" target="_blank">Source</a>`
         : `<a href="${REPO}/tree/main/${c.name}/agent-harness" target="_blank">Source</a>`;
       const titleHtml = c.homepage
         ? `<a href="${esc(c.homepage)}" target="_blank">${esc(c.display_name)}${EXTERNAL_LINK_SVG}</a>`
         : esc(c.display_name);
+      const titleRow = `<span class="card-title"><span class="card-title-row">${iconFor(c, 'title-icon')}<span>${titleHtml}</span></span></span>`;
+      const backTitleRow = `<span class="card-back-title">${esc(c.display_name || c.name)}</span>`;
       const contributors = c.contributors || (c.contributor ? [{name: c.contributor, url: c.contributor_url}] : []);
       const isTeam = contributors.length === 1 && contributors[0].name === 'CLI-Anything-Team';
       const contributorHtml = contributors.length
@@ -2537,34 +2336,54 @@ <h3>Empower yourself &mdash; <span>your CLI toolkit</span></h3>
             ${contributors.map(ct => `<a href="${esc(ct.url)}" target="_blank">${esc(ct.name)}</a>`).join(', ')}${isTeam ? '' : '<span class="community-badge">Community</span>'}
           </div>`
         : '';
-      const dateHtml = c.last_modified
-        ? `<div class="card-date">Updated ${esc(c.last_modified)}</div>`
-        : '';
-      const installSteps = [
-        { label: 'step 1 · install cli', cmd: `cli-hub install ${c.name}` }
-      ];
+      const versionHtml = c.version
+        ? `<div class="card-back-field"><div class="card-back-label">Version</div><div class="card-requires">${esc(c.version)}</div></div>` : '';
+      const updatedHtml = c.last_modified
+        ? `<div class="card-back-field"><div class="card-back-label">Updated</div><div class="card-requires">${esc(c.last_modified)}</div></div>` : '';
+      const runHtml = c.entry_point
+        ? `<div class="card-back-field"><div class="card-back-label">Run directly</div><div class="card-install card-install--note"><code>${esc(c.entry_point)}</code></div></div>` : '';
+
+      // Two-step install (clean box: command lines only, NO inline comments).
+      const installSteps = [{ cmd: `cli-hub install ${c.name}` }];
       const skillCmd = harnessSkillCmd(c);
-      if (skillCmd) installSteps.push({ label: 'step 2 · install skill', cmd: skillCmd });
-      const installHtml = renderInstallStack(installSteps);
+      if (skillCmd) installSteps.push({ cmd: skillCmd });
+      // FRONT: full two-line install with a short plain-language label above the box.
+      const frontInstall = installSteps.length === 2
+        ? renderInstallStack(installSteps, null, true)
+        : renderInstallStack(installSteps, 'Install the CLI');
+
+      // FRONT (page 1): title · description · install box · contributor(s) · Details
+      const front = `
+        <div class="card-head">
+          ${titleRow}
+        </div>
+        <div class="card-desc">${esc(c.description)}</div>
+        ${memChip ? `<div class="tool-foot" style="display:flex;margin-top:11px">${memChip}</div>` : ''}
+        ${frontInstall}
+        ${(contributorHtml || skillFront) ? `<div style="margin-top:12px;display:flex;align-items:center;justify-content:space-between;gap:10px;flex-wrap:wrap">${contributorHtml || '<span></span>'}${skillFront}</div>` : ''}
+        <div class="card-front-foot">
+          <span class="flip-hint">Requirements, version &amp; source</span>
+          ${flipAffordance()}
+        </div>`;
 
-      return `
-        <div class="card">
-          <div class="card-head">
-            <span class="card-title">${titleHtml}</span>
-            <div class="card-meta">
-              <span class="category-tag">${catLabel(c.category)}</span>
-              <span class="card-version">${esc(c.version)}</span>
-            </div>
-          </div>
-          <div class="card-desc">${esc(c.description)}</div>
-          ${dateHtml}
-          ${requiresHtml}
-          ${installHtml}
-          <div class="card-footer">
-            <div class="card-links">${sourceLink}${skillLink ? ' &middot; ' + skillLink : ''}</div>
-            ${contributorHtml}
+      // BACK (page 2): requirements · version · run directly · source · secondary fields
+      const back = `
+        <div class="card-back-head">
+          ${backTitleRow}
+          ${flipBackBtn()}
+        </div>
+        <div class="card-back-scroll">
+          ${requiresHtml ? `<div class="card-back-field">${requiresHtml}</div>` : ''}
+          ${versionHtml}
+          ${runHtml}
+          ${updatedHtml}
+          <div class="card-back-field">
+            <div class="card-back-label">Links</div>
+            <div class="card-links">${sourceLink}</div>
           </div>
         </div>`;
+
+      return flipCardShell(c, hue, front, back);
     }
 
     function formatPublicManager(c) {
@@ -2573,26 +2392,21 @@ <h3>Empower yourself &mdash; <span>your CLI toolkit</span></h3>
       const label = labelMap[manager] || manager;
       return `<span class="public-badge public-badge--${esc(manager)}">${esc(label)}</span>`;
     }
-
-    function publicDirectCmd(c) {
-      return c.direct_cmd || c.entry_point || c.npx_cmd || '';
-    }
+    function publicDirectCmd(c) { return c.direct_cmd || c.entry_point || c.npx_cmd || ''; }
 
     function renderNpmCard(c) {
+      const hue = catHue(c.category);
+      const memChip = membershipChip(c.name);
       const isBundled = (c.install_strategy || c.package_manager) === 'bundled';
-      const dateHtml = c.last_modified
-        ? `<div class="card-date">Updated ${esc(c.last_modified)}</div>`
-        : '';
       const requiresHtml = c.requires
-        ? `<div class="card-requires"><strong>Requires</strong> ${esc(c.requires)}</div>`
-        : '';
+        ? `<div class="card-requires"><strong>Requires</strong> ${esc(c.requires)}</div>` : '';
       const titleHtml = c.homepage
         ? `<a href="${esc(c.homepage)}" target="_blank">${esc(c.display_name)}${EXTERNAL_LINK_SVG}</a>`
         : esc(c.display_name);
-      const skillLink = renderSkillAction(c.skill_md);
-      const sourceLink = c.source_url
-        ? `<a href="${esc(c.source_url)}" target="_blank">Source</a>`
-        : '';
+      const titleRow = `<span class="card-title"><span class="card-title-row">${iconFor(c, 'title-icon')}<span>${titleHtml}</span></span></span>`;
+      const backTitleRow = `<span class="card-back-title">${esc(c.display_name || c.name)}</span>`;
+      const skillFront = renderSkillFront(c.skill_md);
+      const sourceLink = c.source_url ? `<a href="${esc(c.source_url)}" target="_blank">Source</a>` : '';
       const contributors = c.contributors || [];
       const contributorHtml = contributors.length
         ? `<div class="card-contributor">
@@ -2601,43 +2415,66 @@ <h3>Empower yourself &mdash; <span>your CLI toolkit</span></h3>
         : '';
       const directCmd = c.install_cmd || publicDirectCmd(c);
       const directCmdHtml = directCmd && !isBundled
-        ? `<div class="card-npx card-npx--direct"><strong>Or run directly:</strong><span>${esc(directCmd)}</span></div>`
-        : '';
+        ? `<div class="card-npx card-npx--direct"><strong>Or run directly:</strong><span>${esc(directCmd)}</span></div>` : '';
       const installNotesHtml = c.install_notes
-        ? `<div class="card-npx card-npx--comment">${esc(c.install_notes)}</div>`
-        : '';
+        ? `<div class="card-npx card-npx--comment">${esc(c.install_notes)}</div>` : '';
       const publicNotesHtml = (directCmdHtml || installNotesHtml)
-        ? `<div class="card-public-notes">${directCmdHtml}${installNotesHtml}</div>`
-        : '';
-      const installSteps = isBundled
-        ? []
-        : [{ label: 'step 1 · install cli', cmd: `cli-hub install ${c.name}` }];
+        ? `<div class="card-public-notes">${directCmdHtml}${installNotesHtml}</div>` : '';
+      const updatedHtml = c.last_modified
+        ? `<div class="card-back-field"><div class="card-back-label">Updated</div><div class="card-requires">${esc(c.last_modified)}</div></div>` : '';
+
+      // Clean install box — command lines only (no inline comments).
+      const installSteps = isBundled ? [] : [{ cmd: `cli-hub install ${c.name}` }];
       const skillCmd = publicSkillCmd(c);
-      if (skillCmd) installSteps.push({ label: 'step 2 · install skill', cmd: skillCmd });
-      const cliHubInstallHtml = isBundled
-        ? `<div class="card-install card-install--note"><code>Bundled with the upstream app</code></div>`
-        : renderInstallStack(installSteps);
-      const linksHtml = [sourceLink, skillLink].filter(Boolean).join(' &middot; ');
+      if (skillCmd) installSteps.push({ cmd: skillCmd });
+
+      let frontInstall;
+      if (isBundled) {
+        frontInstall = `<div class="install-steps"><div class="install-steps-label">Bundled with the upstream app — no install needed</div>` +
+          `<div class="card-install card-install--note"><code>Bundled with the upstream app</code></div></div>`;
+      } else if (installSteps.length === 2) {
+        frontInstall = renderInstallStack(installSteps, null, true);
+      } else {
+        frontInstall = renderInstallStack(installSteps, 'Install the CLI');
+      }
 
-      return `
-        <div class="card">
-          <div class="card-head">
-            <span class="card-title">${titleHtml}</span>
-            <div class="card-meta">
-              ${formatPublicManager(c)}
-              <span class="category-tag">${catLabel(c.category)}</span>
-            </div>
+      const linksHtml = [sourceLink].filter(Boolean).join(' &middot; ');
+
+      // FRONT (page 1): title (+ manager badge) · description · install box · contributor(s) · Details
+      const front = `
+        <div class="card-head">
+          ${titleRow}
+          <div class="card-meta">
+            ${formatPublicManager(c)}
+            <span class="category-tag">${catLabel(c.category)}</span>
           </div>
-          <div class="card-desc">${esc(c.description)}</div>
-          ${dateHtml}
-          ${requiresHtml}
-          ${cliHubInstallHtml}
-          ${publicNotesHtml}
-          <div class="card-footer">
+        </div>
+        <div class="card-desc">${esc(c.description)}</div>
+        ${memChip ? `<div class="tool-foot" style="display:flex;margin-top:11px">${memChip}</div>` : ''}
+        ${frontInstall}
+        ${(contributorHtml || skillFront) ? `<div style="margin-top:12px;display:flex;align-items:center;justify-content:space-between;gap:10px;flex-wrap:wrap">${contributorHtml || '<span></span>'}${skillFront}</div>` : ''}
+        <div class="card-front-foot">
+          <span class="flip-hint">Requirements, run command &amp; source</span>
+          ${flipAffordance()}
+        </div>`;
+
+      // BACK (page 2): requirements · run directly / notes · updated · source
+      const back = `
+        <div class="card-back-head">
+          ${backTitleRow}
+          ${flipBackBtn()}
+        </div>
+        <div class="card-back-scroll">
+          ${requiresHtml ? `<div class="card-back-field">${requiresHtml}</div>` : ''}
+          ${publicNotesHtml ? `<div class="card-back-field"><div class="card-back-label">Run &amp; notes</div>${publicNotesHtml}</div>` : ''}
+          ${updatedHtml}
+          <div class="card-back-field">
+            <div class="card-back-label">Links</div>
             <div class="card-links">${linksHtml}</div>
-            ${contributorHtml}
           </div>
         </div>`;
+
+      return flipCardShell(c, hue, front, back);
     }
 
     function copyCmd(btn, cmd) {
@@ -2647,38 +2484,18 @@ <h3>Empower yourself &mdash; <span>your CLI toolkit</span></h3>
       });
     }
 
-    function initHeroMotion() {
-      if (window.matchMedia('(prefers-reduced-motion: reduce)').matches) {
-        document.documentElement.classList.remove('js');
-        return;
-      }
-      window.requestAnimationFrame(() => {
-        document.documentElement.classList.add('motion-ready');
-      });
-    }
-
     function animateCount(el, target, duration = 900) {
       if (!el) return;
       const finalValue = Number(target) || 0;
-
-      if (window.matchMedia('(prefers-reduced-motion: reduce)').matches) {
-        el.textContent = finalValue;
-        return;
-      }
-
+      if (window.matchMedia('(prefers-reduced-motion: reduce)').matches) { el.textContent = finalValue; return; }
       const start = performance.now();
-
       function step(now) {
         const progress = Math.min((now - start) / duration, 1);
         const eased = 1 - Math.pow(1 - progress, 3);
         el.textContent = Math.round(finalValue * eased);
-        if (progress < 1) {
-          window.requestAnimationFrame(step);
-        } else {
-          el.textContent = finalValue;
-        }
+        if (progress < 1) window.requestAnimationFrame(step);
+        else el.textContent = finalValue;
       }
-
       window.requestAnimationFrame(step);
     }
 
@@ -2688,34 +2505,17 @@ <h3>Empower yourself &mdash; <span>your CLI toolkit</span></h3>
       const target = shell.querySelector('[data-typing-target]');
       const fullText = shell.dataset.typingText || '';
       if (!target || !fullText) return;
-
-      if (window.matchMedia('(prefers-reduced-motion: reduce)').matches) {
-        target.textContent = fullText;
-        return;
-      }
-
-      let index = 0;
-      let deleting = false;
-
+      if (window.matchMedia('(prefers-reduced-motion: reduce)').matches) { target.textContent = fullText; return; }
+      let index = 0, deleting = false;
       function tick() {
         target.textContent = fullText.slice(0, index);
-
         let delay = deleting ? 44 : 86;
-        if (!deleting && index < fullText.length) {
-          index += 1;
-        } else if (!deleting && index === fullText.length) {
-          deleting = true;
-          delay = 1650;
-        } else if (deleting && index > 0) {
-          index -= 1;
-        } else {
-          deleting = false;
-          delay = 480;
-        }
-
+        if (!deleting && index < fullText.length) { index += 1; }
+        else if (!deleting && index === fullText.length) { deleting = true; delay = 1650; }
+        else if (deleting && index > 0) { index -= 1; }
+        else { deleting = false; delay = 480; }
         window.setTimeout(tick, delay);
       }
-
       window.setTimeout(tick, 420);
     }
 
@@ -2725,16 +2525,61 @@ <h3>Empower yourself &mdash; <span>your CLI toolkit</span></h3>
       d.textContent = s;
       return d.innerHTML;
     }
-
     function escAttr(s) {
       if (!s) return '';
-      return String(s)
-        .replace(/&/g, '&amp;')
-        .replace(/"/g, '&quot;')
-        .replace(/</g, '&lt;')
-        .replace(/>/g, '&gt;');
+      return String(s).replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+    }
+
+    // ── Flip interaction (delegated) ──
+    function setCardFlipped(card, flipped) {
+      card.classList.toggle('flipped', flipped);
+      const inner = card.querySelector('.card-inner');
+      if (!inner) return;
+      const front = inner.querySelector('.card-front');
+      const back = inner.querySelector('.card-back');
+      if (front) front.toggleAttribute('aria-hidden', flipped);
+      if (back) back.toggleAttribute('aria-hidden', !flipped);
+      // toggle tabbability of the hidden face
+      const hidden = flipped ? front : back;
+      const shown = flipped ? back : front;
+      if (hidden) hidden.querySelectorAll('a,button,input,select,summary,[tabindex]').forEach(el => el.setAttribute('tabindex', '-1'));
+      if (shown) shown.querySelectorAll('a,button,input,select,summary,[tabindex]').forEach(el => el.removeAttribute('tabindex'));
+      // update flip-toggle aria-pressed on shown face
+      const tgl = (shown || inner).querySelector('.flip-toggle');
+      if (tgl) tgl.setAttribute('aria-pressed', String(flipped));
+    }
+    // initialise hidden-face tabbability after each render (CLI cards + matrix cards)
+    function syncFlipA11y(root) {
+      (root || document).querySelectorAll('.card, .mcard').forEach(card => {
+        const inner = card.querySelector('.card-inner');
+        if (!inner) return;
+        const back = inner.querySelector('.card-back');
+        if (back && !card.classList.contains('flipped')) {
+          back.setAttribute('aria-hidden', 'true');
+          back.querySelectorAll('a,button,input,select,summary,[tabindex]').forEach(el => el.setAttribute('tabindex', '-1'));
+        }
+      });
     }
 
+    document.addEventListener('click', (e) => {
+      const tgl = e.target.closest('.flip-toggle');
+      if (tgl) {
+        const card = tgl.closest('.card, .mcard');
+        if (card) { setCardFlipped(card, !card.classList.contains('flipped')); }
+        return;
+      }
+    });
+    // Enter/Space when the flip affordance is focused (native button handles this,
+    // but ensure Space doesn't scroll and both keys flip reliably)
+    document.addEventListener('keydown', (e) => {
+      if ((e.key === 'Enter' || e.key === ' ' || e.key === 'Spacebar') && document.activeElement && document.activeElement.classList && document.activeElement.classList.contains('flip-toggle')) {
+        e.preventDefault();
+        const card = document.activeElement.closest('.card, .mcard');
+        if (card) setCardFlipped(card, !card.classList.contains('flipped'));
+      }
+    });
+
+    // ── Skill popover (public cards) ──
     function toggleSkillPopover(trigger) {
       const popover = trigger.closest('.skill-popover');
       if (!popover) return;
@@ -2751,28 +2596,15 @@ <h3>Empower yourself &mdash; <span>your CLI toolkit</span></h3>
 
     document.addEventListener('click', (e) => {
       const copyBtn = e.target.closest('.skill-popover-copy');
-      if (copyBtn) {
-        e.preventDefault();
-        e.stopPropagation();
-        copyCmd(copyBtn, copyBtn.dataset.copyValue);
-        return;
-      }
-
+      if (copyBtn) { e.preventDefault(); e.stopPropagation(); copyCmd(copyBtn, copyBtn.dataset.copyValue); return; }
       const trigger = e.target.closest('.skill-trigger');
-      if (trigger) {
-        e.preventDefault();
-        e.stopPropagation();
-        toggleSkillPopover(trigger);
-        return;
-      }
-
+      if (trigger) { e.preventDefault(); e.stopPropagation(); toggleSkillPopover(trigger); return; }
       document.querySelectorAll('.skill-popover.is-open').forEach((node) => {
         node.classList.remove('is-open');
         const btn = node.querySelector('.skill-trigger');
         if (btn) btn.setAttribute('aria-expanded', 'false');
       });
     });
-
     document.addEventListener('keydown', (e) => {
       if (e.key !== 'Escape') return;
       document.querySelectorAll('.skill-popover.is-open').forEach((node) => {
@@ -2782,321 +2614,59 @@ <h3>Empower yourself &mdash; <span>your CLI toolkit</span></h3>
       });
     });
 
+    // Sync flip a11y whenever a grid is (re)rendered
+    (function () {
+      const obsTargets = ['grid-harness', 'grid-public', 'shelf'].map(id => document.getElementById(id)).filter(Boolean);
+      if ('MutationObserver' in window) {
+        const mo = new MutationObserver(() => syncFlipA11y());
+        obsTargets.forEach(t => mo.observe(t, { childList: true }));
+      }
+    })();
+
     // Wire up search and sort for each deck
     document.getElementById('search-harness').addEventListener('input', (e) => {
-      deckState.harness.query = e.target.value;
-      renderDeck('harness');
+      deckState.harness.query = e.target.value; renderDeck('harness');
     });
     document.getElementById('sort-harness').addEventListener('change', (e) => {
-      deckState.harness.sort = e.target.value;
-      renderDeck('harness');
+      deckState.harness.sort = e.target.value; renderDeck('harness');
     });
     document.getElementById('search-public').addEventListener('input', (e) => {
-      deckState.public.query = e.target.value;
-      renderDeck('public');
+      deckState.public.query = e.target.value; renderDeck('public');
     });
     document.getElementById('sort-public').addEventListener('change', (e) => {
-      deckState.public.sort = e.target.value;
-      renderDeck('public');
+      deckState.public.sort = e.target.value; renderDeck('public');
     });
 
-    window.addEventListener('resize', updateDeckPosition);
+    let masonryResizeTimer = null;
+    window.addEventListener('resize', () => {
+      updateDeckPosition();
+      // debounce the (re)layout: recompute column count + redistribute cards
+      clearTimeout(masonryResizeTimer);
+      masonryResizeTimer = setTimeout(relayoutAllGrids, 150);
+    });
 
     initDeckGestures();
-    initHeroMotion();
     initHeroTypingBar();
-    loadRegistries().then(updateDeckPosition);
-
-    // ── Visitor classification: human vs AI agent ──
-    (function() {
-      const ANALYTICS_PROVIDER = 'posthog';
-      const ANALYTICS_SITE = 'clianything.cc';
-      const COUNTED_HOSTS = new Set(['clianything.cc', 'www.clianything.cc']);
-      const ANALYTICS_TEST_RUN = new URLSearchParams(location.search).get('analytics_test_run') || '';
-      const POSTHOG_CONFIG = {
-        projectToken: 'phc_ovP8d5bmjpn8YZnTo7pb6rE3TikcAMgmNVt75o3Ywejz',
-        apiHost: 'https://us.i.posthog.com',
-        defaults: '2026-01-30',
-        personProfiles: 'identified_only',
-      };
-      const UMAMI_CONFIG = {
-        sendUrl: 'https://cloud.umami.is/api/send',
-        websiteId: 'a076c661-bed1-405c-a522-813794e688b4',
-      };
-      const OFFICIAL_AGENT_UA_RULES = [
-        { id: 'openai-oai-searchbot', category: 'official_ai_agent', regex: /\bOAI-SearchBot\b/i },
-        { id: 'openai-gptbot', category: 'official_ai_agent', regex: /\bGPTBot\b/i },
-        { id: 'openai-chatgpt-user', category: 'official_ai_agent', regex: /\bChatGPT-User\b/i },
-        { id: 'anthropic-claudebot', category: 'official_ai_agent', regex: /\bClaudeBot\b/i },
-        { id: 'anthropic-claude-user', category: 'official_ai_agent', regex: /\bClaude-User\b/i },
-        { id: 'anthropic-claude-searchbot', category: 'official_ai_agent', regex: /\bClaude-SearchBot\b/i },
-        { id: 'perplexity-bot', category: 'official_ai_agent', regex: /\bPerplexityBot\b/i },
-        { id: 'perplexity-user', category: 'official_ai_agent', regex: /\bPerplexity-User\b/i },
-        { id: 'google-vertex-bot', category: 'official_ai_agent', regex: /\bGoogle-CloudVertexBot\b/i },
-      ];
-      const AGENT_TOOL_UA_RULES = [
-        { id: 'claude-code', category: 'agent_tool', regex: /\bclaude(?:[ -]?code)\b/i },
-        { id: 'codex', category: 'agent_tool', regex: /\bcodex\b/i },
-        { id: 'cursor', category: 'agent_tool', regex: /\bcursor\b/i },
-        { id: 'cline', category: 'agent_tool', regex: /\bcline\b/i },
-        { id: 'aider', category: 'agent_tool', regex: /\baider\b/i },
-        { id: 'continue', category: 'agent_tool', regex: /\bcontinue\b/i },
-        { id: 'openhands', category: 'agent_tool', regex: /\bopenhands\b/i },
-        { id: 'openclaw', category: 'agent_tool', regex: /\bopenclaw\b/i },
-        { id: 'nanobot', category: 'agent_tool', regex: /\bnanobot\b/i },
-        { id: 'browser-use', category: 'agent_tool', regex: /\bbrowser[- ]use\b/i },
-        { id: 'stagehand', category: 'agent_tool', regex: /\bstagehand\b/i },
-      ];
-      const AUTOMATION_UA_RULES = [
-        { id: 'headless-browser', category: 'automation_runtime', regex: /\bHeadlessChrome\b|\bHeadless\b/i },
-        { id: 'playwright', category: 'automation_runtime', regex: /\bPlaywright\b/i },
-        { id: 'puppeteer', category: 'automation_runtime', regex: /\bPuppeteer\b/i },
-        { id: 'selenium', category: 'automation_runtime', regex: /\bSelenium\b/i },
-        { id: 'phantomjs', category: 'automation_runtime', regex: /\bPhantomJS\b|\bPhantom\b/i },
-      ];
-      const SCRIPTED_CLIENT_UA_RULES = [
-        { id: 'python-requests', category: 'scripted_client', regex: /\bpython-requests\b/i },
-        { id: 'python-httpx', category: 'scripted_client', regex: /\bpython-httpx\b/i },
-        { id: 'axios', category: 'scripted_client', regex: /\baxios\b/i },
-        { id: 'node-fetch', category: 'scripted_client', regex: /\bnode-fetch\b/i },
-        { id: 'undici', category: 'scripted_client', regex: /\bundici\b/i },
-        { id: 'go-http-client', category: 'scripted_client', regex: /\bGo-http-client\b/i },
-        { id: 'curl', category: 'scripted_client', regex: /\bcurl\b/i },
-        { id: 'wget', category: 'scripted_client', regex: /\bwget\b/i },
-      ];
-      const CATEGORY_PRIORITY = ['official_ai_agent', 'agent_tool', 'automation_runtime', 'scripted_client'];
-      let humanConfirmed = false;
-      let posthogReady = false;
-      const pendingPosthogEvents = [];
-
-      function isTrackedHost() {
-        return COUNTED_HOSTS.has(location.hostname);
-      }
+    loadRegistries().then(() => { updateDeckPosition(); syncFlipA11y(); });
+
+    // ── Live analytics via Cloudflare Worker proxy ──
+    (function () {
+      const ANALYTICS_PROXY_URL = 'https://analytics.clianything.cc/';
+      const ZERO_STATS = { web_unique_visitors: 0, cli_hub_total: 0, cli_hub_human: 0, cli_hub_agent: 0 };
 
       function applyVisitorStats(stats) {
         const formatK = (val) => {
           const n = Number(val) || 0;
-          if (!n) return '0K';
+          if (n < 1000) return String(n);
           return (n / 1000).toFixed(1).replace(/\.0$/, '') + 'K';
         };
-        const setText = (id, val) => {
-          const el = document.getElementById(id);
-          if (el) el.textContent = formatK(val);
-        };
+        const setText = (id, val) => { const el = document.getElementById(id); if (el) el.textContent = formatK(val); };
         setText('stat-web-unique', stats.web_unique_visitors);
         setText('stat-cli-total', stats.cli_hub_total);
         setText('stat-cli-human', stats.cli_hub_human);
         setText('stat-cli-agent', stats.cli_hub_agent);
       }
 
-      function readUaBrands() {
-        const brands = navigator.userAgentData && Array.isArray(navigator.userAgentData.brands)
-          ? navigator.userAgentData.brands
-          : [];
-        return brands.map((brand) => brand.brand).join(' ');
-      }
-
-      function collectRuleSignals(ua, rules, signals) {
-        rules.forEach((rule) => {
-          if (rule.regex.test(ua)) {
-            signals.push(rule);
-          }
-        });
-      }
-
-      function collectRuntimeSignals(brands, signals) {
-        if (navigator.webdriver === true) {
-          signals.push({ id: 'webdriver', category: 'automation_runtime' });
-        }
-        if (/HeadlessChrome/i.test(brands)) {
-          signals.push({ id: 'ua-brand-headlesschrome', category: 'automation_runtime' });
-        }
-        if ('__playwright__binding__' in window || '__pwManual' in window) {
-          signals.push({ id: 'playwright-runtime', category: 'automation_runtime' });
-        }
-        if ('Cypress' in window) {
-          signals.push({ id: 'cypress-runtime', category: 'automation_runtime' });
-        }
-        if ('_phantom' in window || 'callPhantom' in window) {
-          signals.push({ id: 'phantom-runtime', category: 'automation_runtime' });
-        }
-        if ('domAutomation' in window || 'domAutomationController' in window) {
-          signals.push({ id: 'dom-automation', category: 'automation_runtime' });
-        }
-      }
-
-      function classifyVisitor() {
-        const ua = navigator.userAgent || '';
-        const brands = readUaBrands();
-        const signals = [];
-        collectRuleSignals(ua, OFFICIAL_AGENT_UA_RULES, signals);
-        collectRuleSignals(ua, AGENT_TOOL_UA_RULES, signals);
-        collectRuleSignals(ua, AUTOMATION_UA_RULES, signals);
-        collectRuleSignals(ua, SCRIPTED_CLIENT_UA_RULES, signals);
-        collectRuntimeSignals(brands, signals);
-
-        const seen = new Set();
-        const uniqueSignals = signals.filter((signal) => {
-          if (seen.has(signal.id)) return false;
-          seen.add(signal.id);
-          return true;
-        }).sort((left, right) => CATEGORY_PRIORITY.indexOf(left.category) - CATEGORY_PRIORITY.indexOf(right.category));
-
-        const primary = uniqueSignals[0] || null;
-        const isAgent = uniqueSignals.length > 0;
-        return {
-          ua,
-          brands,
-          webdriver: navigator.webdriver === true,
-          isAgent,
-          isAutomation: !!primary && (primary.category === 'automation_runtime' || primary.category === 'scripted_client'),
-          trafficType: isAgent ? 'agent' : 'human',
-          reason: primary ? primary.id : 'human',
-          category: primary ? primary.category : 'human',
-          signals: uniqueSignals.map((signal) => signal.id),
-        };
-      }
-
-      const visitor = classifyVisitor();
-
-      function analyticsContext(eventData) {
-        const base = {
-          source: 'web',
-          site: ANALYTICS_SITE,
-          host: location.hostname,
-          visitor_type: visitor.trafficType,
-          is_agent: visitor.isAgent,
-          is_automation: visitor.isAutomation,
-          agent_category: visitor.category,
-          agent_reason: visitor.reason,
-          agent_signals: visitor.signals.slice(0, 12),
-          ua: visitor.ua.slice(0, 200),
-          ua_brands: visitor.brands.slice(0, 200),
-          webdriver: visitor.webdriver,
-        };
-        if (ANALYTICS_TEST_RUN) {
-          base.test_run = ANALYTICS_TEST_RUN;
-        }
-        return { ...base, ...eventData };
-      }
-
-      function initPosthog() {
-        if (!isTrackedHost()) return;
-        !function(t,e){var o,n,p,r;e.__SV||(window.posthog&&window.posthog.__loaded)||(window.posthog=e,e._i=[],e.init=function(i,s,a){function g(t,e){var o=e.split('.');2==o.length&&(t=t[o[0]],e=o[1]),t[e]=function(){t.push([e].concat(Array.prototype.slice.call(arguments,0)))}}(p=t.createElement('script')).type='text/javascript',p.crossOrigin='anonymous',p.async=!0,p.src=s.api_host.replace('.i.posthog.com','-assets.i.posthog.com')+'/static/array.js',(r=t.getElementsByTagName('script')[0]).parentNode.insertBefore(p,r);var u=e;for(void 0!==a?u=e[a]=[]:a='posthog',u.people=u.people||[],u.toString=function(t){var e='posthog';return'posthog'!==a&&(e+='.'+a),t||(e+=' (stub)'),e},u.people.toString=function(){return u.toString(1)+'.people (stub)'},o='init capture register register_once register_for_session unregister unregister_for_session getFeatureFlag getFeatureFlagPayload isFeatureEnabled reloadFeatureFlags updateEarlyAccessFeatureEnrollment getEarlyAccessFeatures on onFeatureFlags onSessionId getSurveys getActiveMatchingSurveys renderSurvey canRenderSurvey getNextSurveyStep identify setPersonProperties group resetGroups setPersonPropertiesForFlags resetPersonPropertiesForFlags setGroupPropertiesForFlags resetGroupPropertiesForFlags reset get_distinct_id getGroups get_session_id get_session_replay_url alias set_config startSessionRecording stopSessionRecording sessionRecordingStarted captureException loadToolbar get_property getSessionProperty createPersonProfile opt_in_capturing opt_out_capturing has_opted_in_capturing has_opted_out_capturing clear_opt_in_out_capturing debug'.split(' '),n=0;n<o.length;n++)g(u,o[n]);e._i.push([i,s,a])},e.__SV=1)}(document,window.posthog||[]);
-        window.posthog.init(POSTHOG_CONFIG.projectToken, {
-          api_host: POSTHOG_CONFIG.apiHost,
-          defaults: POSTHOG_CONFIG.defaults,
-          person_profiles: POSTHOG_CONFIG.personProfiles,
-          opt_out_useragent_filter: true,
-          loaded: function(posthog) {
-            posthogReady = true;
-            while (pendingPosthogEvents.length) {
-              const queued = pendingPosthogEvents.shift();
-              posthog.capture(queued.eventName, analyticsContext(queued.eventData));
-            }
-          },
-        });
-      }
-
-      function initUmami() {
-        if (!isTrackedHost()) return;
-        const script = document.createElement('script');
-        script.defer = true;
-        script.src = 'https://cloud.umami.is/script.js';
-        script.dataset.websiteId = UMAMI_CONFIG.websiteId;
-        document.head.appendChild(script);
-      }
-
-      function trackWithPosthog(eventName, eventData) {
-        if (!isTrackedHost() || !window.posthog) return;
-        if (!posthogReady || typeof window.posthog.capture !== 'function') {
-          pendingPosthogEvents.push({ eventName, eventData });
-          return;
-        }
-        window.posthog.capture(eventName, analyticsContext(eventData));
-      }
-
-      function trackWithUmami(eventName, eventData) {
-        if (!isTrackedHost()) return;
-        const payload = {
-          type: 'event',
-          payload: {
-            website: UMAMI_CONFIG.websiteId,
-            hostname: ANALYTICS_SITE,
-            url: location.pathname,
-            name: eventName,
-            data: analyticsContext(eventData),
-          },
-        };
-        fetch(UMAMI_CONFIG.sendUrl, {
-          method: 'POST',
-          headers: { 'Content-Type': 'application/json' },
-          body: JSON.stringify(payload),
-          keepalive: true,
-        }).catch(() => {});
-      }
-
-      function trackAnalyticsEvent(eventName, eventData) {
-        if (ANALYTICS_PROVIDER === 'umami') {
-          trackWithUmami(eventName, eventData);
-          return;
-        }
-        trackWithPosthog(eventName, eventData);
-      }
-
-      if (ANALYTICS_PROVIDER === 'umami') {
-        initUmami();
-      } else {
-        initPosthog();
-      }
-
-      if (ANALYTICS_TEST_RUN) {
-        window.__CLI_ANYTHING_ANALYTICS__ = {
-          visitor: {
-            isAgent: visitor.isAgent,
-            isAutomation: visitor.isAutomation,
-            trafficType: visitor.trafficType,
-            category: visitor.category,
-            reason: visitor.reason,
-            signals: visitor.signals.slice(),
-            webdriver: visitor.webdriver,
-            ua: visitor.ua,
-          },
-        };
-      }
-
-      if (isTrackedHost() && visitor.isAgent) {
-        trackAnalyticsEvent('visit-agent', {
-          classification_source: 'initial-load',
-        });
-      }
-
-      function onHumanInteraction(event) {
-        if (humanConfirmed || !isTrackedHost() || visitor.trafficType !== 'human') return;
-        humanConfirmed = true;
-        trackAnalyticsEvent('visit-human', {
-          classification_source: 'user-interaction',
-          interaction: event.type,
-        });
-        ['mousemove', 'touchstart', 'scroll', 'keydown', 'click'].forEach((evt) => {
-          document.removeEventListener(evt, onHumanInteraction);
-        });
-      }
-
-      ['mousemove', 'touchstart', 'scroll', 'keydown', 'click'].forEach((evt) => {
-        document.addEventListener(evt, onHumanInteraction, { once: false, passive: true });
-      });
-
-      // ── Live analytics via Cloudflare Worker proxy ──
-      // Runtime stats are fetched once per page load and rendered as compact
-      // Cloudflare unique visitor and CLI-Hub usage counters.
-      const ANALYTICS_PROXY_URL = 'https://analytics.clianything.cc/';
-      const ZERO_STATS = {
-        web_unique_visitors: 0,
-        cli_hub_total: 0,
-        cli_hub_human: 0, cli_hub_agent: 0,
-      };
-
       function normalizeStats(stats) {
         const cliHubHuman = Number(stats && stats.cli_hub_human) || 0;
         const cliHubAgent = Number(stats && stats.cli_hub_agent) || 0;
@@ -3107,37 +2677,23 @@ <h3>Empower yourself &mdash; <span>your CLI toolkit</span></h3>
           cli_hub_agent: cliHubAgent,
         };
       }
-
       async function fetchWorkerStats() {
         const response = await fetch(ANALYTICS_PROXY_URL + 'stats');
         if (!response.ok) throw new Error('analytics stats http ' + response.status);
         const data = await response.json();
         return normalizeStats(data.stats || data);
       }
-
-      async function fetchVisitorStats() {
-        return fetchWorkerStats();
-      }
-
-      function hasAnyStats(s) {
-        return Object.keys(ZERO_STATS).some((key) => (s[key] || 0) > 0);
-      }
-
+      function hasAnyStats(s) { return Object.keys(ZERO_STATS).some((key) => (s[key] || 0) > 0); }
       async function refreshVisitorStats() {
-        const stats = await fetchVisitorStats();
+        const stats = await fetchWorkerStats();
         if (!hasAnyStats(stats)) return false;
         applyVisitorStats(stats);
         return true;
       }
-
-      async function loadVisitorStats() {
-        await refreshVisitorStats().catch(() => false);
-      }
+      async function loadVisitorStats() { await refreshVisitorStats().catch(() => false); }
 
       loadVisitorStats();
-      if (typeof loadGitHubStars === 'function') {
-        loadGitHubStars();
-      }
+      if (typeof loadGitHubStars === 'function') loadGitHubStars();
     })();
   </script>
 </body>
diff --git a/docs/hub/llms.txt b/docs/hub/llms.txt
index b6421c532..87062b971 100644
--- a/docs/hub/llms.txt
+++ b/docs/hub/llms.txt
@@ -24,6 +24,17 @@ Agent skill install: `npx skills add HKUDS/CLI-Anything --skill cli-hub-meta-ski
 - Use `cli-hub install <name>` to install a selected CLI.
 - Use `cli-hub launch <name> [args...]` or the CLI entry point directly to run installed tools.
 - Prefer each harness CLI's `--json` output for reliable agent parsing.
+- For multi-tool workflows, use **matrices** (capability-based bundles): `cli-hub can "<task>"` to find a capability, `cli-hub matrix preflight <name> --json` to check availability, then `cli-hub matrix install <name> --capability <id>` to install only what the task needs.
+
+## Workflow Matrices
+
+Matrices package a whole workflow as capabilities × providers (harness CLIs, public CLIs, Python libs, native binaries, and cloud APIs). Browse them at https://clianything.cc/matrix.html.
+
+- Matrix registry (machine-readable): https://clianything.cc/matrix_registry.json — capabilities, providers, preflight `requires` contracts, recipes, and known gaps.
+- Discover a capability across all matrices: `cli-hub can "<task>"`.
+- Preflight before installing (exit 3 = capability gaps): `cli-hub matrix preflight <name> --json`.
+- Scope installs to a capability, recipe, or subset: `cli-hub matrix install <name> --capability <id>` (also `--recipe`, `--only`, `--dry-run`, `--resume`).
+- Every matrix subcommand supports `--json`. After install, each matrix renders a local SKILL.md with provider-selection rules.
 
 ## Constraints
 
@@ -39,6 +50,7 @@ Agent skill install: `npx skills add HKUDS/CLI-Anything --skill cli-hub-meta-ski
 - Pricing: https://clianything.cc/pricing.md
 - Registry: https://clianything.cc/registry.json
 - Public registry: https://clianything.cc/public_registry.json
+- Matrix registry: https://clianything.cc/matrix_registry.json
 - OpenAPI description for read-only registry resources: https://clianything.cc/openapi.json
 - Agent discovery: https://clianything.cc/.well-known/agent.json
 - A2A agent card: https://clianything.cc/.well-known/agent-card.json
diff --git a/docs/hub/sitemap.xml b/docs/hub/sitemap.xml
index 3bc84ba08..6cecedc5d 100644
--- a/docs/hub/sitemap.xml
+++ b/docs/hub/sitemap.xml
@@ -12,6 +12,12 @@
     <changefreq>weekly</changefreq>
     <priority>0.9</priority>
   </url>
+  <url>
+    <loc>https://clianything.cc/matrix.html</loc>
+    <lastmod>2026-06-11</lastmod>
+    <changefreq>weekly</changefreq>
+    <priority>0.9</priority>
+  </url>
   <url>
     <loc>https://clianything.cc/llms.txt</loc>
     <lastmod>2026-05-10</lastmod>
diff --git a/matrix_registry.json b/matrix_registry.json
new file mode 100644
index 000000000..0459a20f3
--- /dev/null
+++ b/matrix_registry.json
@@ -0,0 +1,1276 @@
+{
+  "meta": {
+    "repo": "https://github.com/HKUDS/CLI-Anything",
+    "description": "Curated CLI Matrix registry for CLI-Hub multi-CLI workflows (capability-based, v2 schema)",
+    "updated": "2026-06-11",
+    "schema_doc": "docs/cli-matrix/matrix_registry.schema.md"
+  },
+  "matrices": [
+    {
+      "name": "video-creation",
+      "display_name": "Video Creation & Editing",
+      "version": "3",
+      "schema_version": "2",
+      "description": "Capability-based matrix for end-to-end video production: storyboard planning, story/audio direction, internet video/music search/download with source triage, capture, generation, voice/music, sound design, footage analysis, transcription, high-end caption design, assembly, overlay, thumbnail, encode, and quality review with render-doctor investigation. Providers include harness CLIs, public CLIs, Python libs, native binaries, bundled scripts, agent skills, and cloud APIs.",
+      "category": "video",
+      "matrix": "cli-matrix",
+      "matrix_id": "S1",
+      "homepage": "https://github.com/HKUDS/CLI-Anything/blob/main/docs/cli-matrix/cli-matrix-plan.md",
+      "skill_md": "cli-hub-matrix/video-creation/SKILL.md",
+      "clis": [
+        "generate-veo-video",
+        "jimeng",
+        "openscreen",
+        "obs-studio",
+        "audacity",
+        "minimax-cli",
+        "elevenlabs",
+        "suno",
+        "kdenlive",
+        "shotcut",
+        "videocaptioner",
+        "gimp",
+        "krita",
+        "inkscape"
+      ],
+      "capabilities": [
+        {
+          "id": "script.storyboard",
+          "intent": "Turn a brief into global creative direction, narrative/emotional arc, audio arc, script, shot list, timing map, storyboard, and asset requirements before production. Default to agent-native planning unless a focused external skill is clearly worth installing.",
+          "inputs": ["brief:text", "duration?:seconds", "audience?:text", "style?:text"],
+          "outputs": ["creative_direction:path", "script:path", "shot_list:path", "timing_map:path", "beat_map:path", "audio_plan:path", "asset_plan:path"],
+          "skill_search_hints": ["storyboard", "creative direction", "video scriptwriting", "shot list", "beat map", "audio arc", "animatic", "remotion storyboard"],
+          "providers": [
+            {"kind": "agent-native", "name": "Agent-native planning", "requires": {}, "cost_tier": "free", "quality_tier": "high", "offline": true, "notes": "Default path for creative_direction.md, story arc, emotional curve, audio arc, beat map, scripts, shot lists, timing maps, storyboards, and asset plans; read cli-hub-matrix/video-creation/references/story-structure-audio.md for non-trivial videos."},
+            {"kind": "agent-skill", "name": "storyboard-creation skill", "requires": {}, "cost_tier": "free", "quality_tier": "high", "offline": true, "notes": "Install with `pnpm dlx add-skill https://github.com/inference-sh/skills/tree/HEAD/guides/video/storyboard-creation`. Use only for shot grammar, camera angles, continuity, storyboard panels, and animatic planning."},
+            {"kind": "agent-skill", "name": "remotion-best-practices skill", "requires": {}, "cost_tier": "free", "quality_tier": "high", "offline": true, "notes": "Install with `npx skills add https://github.com/remotion-dev/skills --skill remotion-best-practices`; SKILL.md: https://github.com/remotion-dev/skills/blob/main/skills/remotion/SKILL.md. Use when the storyboard will become Remotion/React motion-video code."}
+          ]
+        },
+        {
+          "id": "video.search",
+          "intent": "Discover candidate internet footage, stock clips, public-domain clips, or platform URLs before download.",
+          "inputs": ["query:text", "source_preference?:stock|public-domain|youtube|bilibili|web", "license_requirement?:text"],
+          "outputs": ["candidate_urls:json", "source_metadata:json"],
+          "skill_search_hints": ["video search", "stock footage", "public domain video", "bilibili search", "youtube creative commons"],
+          "providers": [
+            {"kind": "web-search", "name": "Web search + source filters", "requires": {}, "cost_tier": "free", "quality_tier": "good", "offline": false, "notes": "Use site/source filters for YouTube, Bilibili, Wikimedia Commons, stock sites, and public-source searches; record URL, creator, license, and attribution before editing. For found-footage deliverables, read cli-hub-matrix/video-creation/references/source-triage.md and classify each candidate's platform-origin evidence."}
+          ]
+        },
+        {
+          "id": "video.download",
+          "intent": "Download or import selected web video URLs into the workspace with provenance metadata.",
+          "inputs": ["urls:string[]", "quality?:resolution", "cookies?:path", "license_metadata?:json"],
+          "outputs": ["video_clips:path[]", "sources_manifest:path"],
+          "skill_search_hints": ["video downloader", "yt-dlp", "bilibili downloader", "youtube downloader", "download video skill"],
+          "providers": [
+            {"kind": "public-cli", "name": "yt-dlp", "requires": {"binary": ["yt-dlp", "ffmpeg"]}, "install_hint": "pipx install yt-dlp  # or brew install yt-dlp", "cost_tier": "free", "quality_tier": "high", "offline": false, "notes": "General downloader for YouTube, Bilibili, and many sites; supports search, playlists, cookies, and quality filters."},
+            {"kind": "public-cli", "name": "you-get", "requires": {"binary": ["you-get"]}, "install_hint": "pipx install you-get  # or brew install you-get", "cost_tier": "free", "quality_tier": "good", "offline": false, "notes": "Multi-site media downloader with Bilibili support."},
+            {"kind": "public-cli", "name": "lux", "requires": {"binary": ["lux", "ffmpeg"]}, "install_hint": "brew install lux  # or go install github.com/iawia002/lux@latest", "cost_tier": "free", "quality_tier": "good", "offline": false, "notes": "Go CLI downloader with Bilibili, YouTube, Douyin, Youku, and other site support."},
+            {"kind": "public-cli", "name": "BBDown", "requires": {"binary": ["BBDown", "ffmpeg"]}, "install_hint": "dotnet tool install --global BBDown  # or brew install bbdown", "cost_tier": "free", "quality_tier": "high", "offline": false, "notes": "Bilibili-focused CLI; useful for subtitles, danmaku, playlists, favorites, and high-quality streams."}
+          ]
+        },
+        {
+          "id": "music.search",
+          "intent": "Discover existing songs, BGM, soundtrack cues, platform audio, or specific music versions before download.",
+          "inputs": ["query:text", "version_requirement?:text", "license_requirement?:text", "platform_preference?:youtube|bilibili|soundcloud|bandcamp|spotify|web"],
+          "outputs": ["candidate_urls:json", "music_source_metadata:json"],
+          "skill_search_hints": ["music search", "existing song", "background music source", "official audio", "royalty free music"],
+          "providers": [
+            {"kind": "web-search", "name": "Web search + music source filters", "requires": {}, "cost_tier": "free", "quality_tier": "good", "offline": false, "notes": "Search for official artist/label uploads, official audio/MV, verified lyric videos, royalty-free sources, or the exact requested cover/version; record rights and attribution metadata."},
+            {"kind": "public-cli", "name": "yt-dlp search extractors", "requires": {"binary": ["yt-dlp"]}, "cost_tier": "free", "quality_tier": "good", "offline": false, "notes": "Use ytsearch/scsearch only after the query and version constraints are clear; inspect candidates before download."},
+            {"kind": "public-cli", "name": "spotdl metadata/search", "requires": {"binary": ["spotdl"]}, "cost_tier": "free", "quality_tier": "good", "offline": false, "notes": "Useful when the user names a Spotify track/playlist and metadata alignment matters; respect platform rights and user authorization."}
+          ]
+        },
+        {
+          "id": "music.download",
+          "intent": "Download or import existing music into the workspace with provenance metadata, conversion, and source-audio validation.",
+          "inputs": ["urls:string[]", "local_files?:path[]", "version_metadata?:json", "license_metadata?:json"],
+          "outputs": ["audio_clip:path", "music_sources_manifest:path"],
+          "skill_search_hints": ["music downloader", "audio extraction", "yt-dlp audio", "soundcloud downloader", "bandcamp downloader", "spotify downloader"],
+          "providers": [
+            {"kind": "public-cli", "name": "yt-dlp audio download", "requires": {"binary": ["yt-dlp", "ffmpeg"]}, "cost_tier": "free", "quality_tier": "high", "offline": false, "notes": "General audio download/extraction path for many supported sites. For Bilibili, download raw m4a and convert with ffmpeg instead of `yt-dlp -x --audio-format mp3`; verify mean volume after conversion."},
+            {"kind": "public-cli", "name": "spotdl", "requires": {"binary": ["spotdl", "ffmpeg"]}, "cost_tier": "free", "quality_tier": "good", "offline": false, "notes": "Downloads tracks/playlists with Spotify metadata and matched audio sources. Use only when the user is authorized to use the resulting music."},
+            {"kind": "public-cli", "name": "scdl", "requires": {"binary": ["scdl"]}, "cost_tier": "free", "quality_tier": "good", "offline": false, "notes": "SoundCloud-focused downloader for public/authorized SoundCloud tracks."},
+            {"kind": "public-cli", "name": "bandcamp-dl", "requires": {"binary": ["bandcamp-dl"]}, "cost_tier": "free", "quality_tier": "good", "offline": false, "notes": "Bandcamp-focused downloader for public or user-owned Bandcamp tracks/albums."},
+            {"kind": "native", "name": "local file import + ffmpeg", "requires": {"binary": ["ffmpeg"]}, "cost_tier": "free", "quality_tier": "high", "offline": true, "notes": "Use when the user supplies local music files; normalize/convert only after validating the correct version and clean audio."}
+          ]
+        },
+        {
+          "id": "visual.capture",
+          "intent": "Record screen, webcam, or application windows to a video file.",
+          "inputs": ["source:screen|window|webcam", "duration?:seconds"],
+          "outputs": ["video_clip:path"],
+          "skill_search_hints": ["screen recording", "screencast", "webcam capture"],
+          "providers": [
+            {"kind": "harness-cli", "name": "cli-anything-openscreen", "requires": {"binary": ["cli-anything-openscreen"]}, "cost_tier": "free", "quality_tier": "high", "offline": true},
+            {"kind": "harness-cli", "name": "cli-anything-obs-studio", "requires": {"binary": ["cli-anything-obs-studio"]}, "cost_tier": "free", "quality_tier": "high", "offline": true},
+            {"kind": "native", "name": "ffmpeg x11grab/avfoundation", "requires": {"binary": ["ffmpeg"]}, "cost_tier": "free", "quality_tier": "high", "offline": true},
+            {"kind": "native", "name": "screencapture (macOS)", "requires": {"binary": ["screencapture"]}, "cost_tier": "free", "quality_tier": "high", "offline": true},
+            {"kind": "python", "name": "mss + cv2", "requires": {"package": ["mss", "cv2"]}, "cost_tier": "free", "quality_tier": "good", "offline": true}
+          ]
+        },
+        {
+          "id": "visual.generate",
+          "intent": "Produce a video clip from a text prompt or reference image.",
+          "inputs": ["prompt:text", "ref_image?:path", "duration?:seconds"],
+          "outputs": ["video_clip:path"],
+          "skill_search_hints": ["text-to-video", "AI video", "video generation"],
+          "providers": [
+            {"kind": "public-cli", "name": "generate-veo-video", "requires": {"binary": ["generate-veo"], "env": ["GOOGLE_CLOUD_PROJECT"]}, "cost_tier": "metered", "quality_tier": "high", "offline": false},
+            {"kind": "public-cli", "name": "jimeng", "requires": {"binary": ["dreamina"]}, "cost_tier": "metered", "quality_tier": "high", "offline": false, "notes": "ByteDance Dreamina; shares model family with Seedance."},
+            {"kind": "api", "name": "Runway Gen-4", "requires": {"env": ["RUNWAY_API_KEY"]}, "cost_tier": "paid", "quality_tier": "sota", "offline": false, "notes": "~$0.05/sec, cinematic motion."},
+            {"kind": "api", "name": "Kling", "requires": {"env": ["KLING_API_KEY"]}, "cost_tier": "paid", "quality_tier": "high", "offline": false},
+            {"kind": "api", "name": "Pika", "requires": {"env": ["PIKA_API_KEY"]}, "cost_tier": "paid", "quality_tier": "good", "offline": false},
+            {"kind": "api", "name": "Seedance", "requires": {"env": ["SEEDANCE_API_KEY"]}, "cost_tier": "paid", "quality_tier": "sota", "offline": false, "notes": "ByteDance Seedance; realistic motion."}
+          ]
+        },
+        {
+          "id": "audio.capture",
+          "intent": "Record, clean, trim, normalize, or denoise audio tracks.",
+          "inputs": ["source:mic|file"],
+          "outputs": ["audio_clip:path"],
+          "skill_search_hints": ["audio editing", "noise reduction"],
+          "providers": [
+            {"kind": "harness-cli", "name": "cli-anything-audacity", "requires": {"binary": ["cli-anything-audacity"]}, "cost_tier": "free", "quality_tier": "high", "offline": true},
+            {"kind": "native", "name": "sox/ffmpeg", "requires": {"binary": ["ffmpeg"]}, "cost_tier": "free", "quality_tier": "high", "offline": true},
+            {"kind": "python", "name": "pydub/soundfile/librosa/noisereduce", "requires": {"package": ["pydub"]}, "cost_tier": "free", "quality_tier": "good", "offline": true}
+          ]
+        },
+        {
+          "id": "audio.synthesize",
+          "intent": "Generate speech audio from text (narration / voiceover).",
+          "inputs": ["text", "voice?:id", "lang?:code"],
+          "outputs": ["audio_clip:path"],
+          "skill_search_hints": ["text-to-speech", "TTS", "voice synthesis"],
+          "providers": [
+            {"kind": "public-cli", "name": "minimax-cli", "requires": {"binary": ["minimax-cli"], "env": ["MINIMAX_API_KEY"]}, "cost_tier": "metered", "quality_tier": "high", "offline": false},
+            {"kind": "public-cli", "name": "elevenlabs", "requires": {"binary": ["elevenlabs"], "env": ["ELEVENLABS_API_KEY"]}, "cost_tier": "paid", "quality_tier": "sota", "offline": false},
+            {"kind": "api", "name": "OpenAI TTS", "requires": {"env": ["OPENAI_API_KEY"]}, "cost_tier": "metered", "quality_tier": "high", "offline": false},
+            {"kind": "api", "name": "Google Cloud TTS", "requires": {"env": ["GOOGLE_CLOUD_PROJECT"]}, "cost_tier": "metered", "quality_tier": "high", "offline": false},
+            {"kind": "python", "name": "edge-tts", "requires": {"package": ["edge_tts"]}, "cost_tier": "free", "quality_tier": "good", "offline": false}
+          ]
+        },
+        {
+          "id": "music.generate",
+          "intent": "Generate background music or sound effects that follow the planned audio arc rather than a flat continuous bed.",
+          "inputs": ["prompt:text", "duration?:seconds", "audio_plan?:path"],
+          "outputs": ["audio_clip:path"],
+          "skill_search_hints": ["music generation", "background music"],
+          "providers": [
+            {"kind": "public-cli", "name": "suno", "requires": {"binary": ["suno"]}, "cost_tier": "metered", "quality_tier": "sota", "offline": false},
+            {"kind": "public-cli", "name": "minimax-cli", "requires": {"binary": ["minimax-cli"], "env": ["MINIMAX_API_KEY"]}, "cost_tier": "metered", "quality_tier": "high", "offline": false},
+            {"kind": "api", "name": "Udio", "requires": {"env": ["UDIO_API_KEY"]}, "cost_tier": "paid", "quality_tier": "sota", "offline": false}
+          ]
+        },
+        {
+          "id": "sound.design",
+          "intent": "Design hits, risers, score sections, mix dynamics, and the final audio arc as a separate pass; a music bed alone is not a designed mix.",
+          "inputs": ["edit_or_plan:path", "audio_plan?:path", "music_bed?:path", "source_audio?:path[]"],
+          "outputs": ["sound_design:path", "audio_stems:path[]", "mixed_audio:path"],
+          "skill_search_hints": ["sound design", "trailer hits", "risers", "sfx stems", "audio mix", "ducking", "section loudness"],
+          "providers": [
+            {"kind": "agent-native", "name": "Agent-native sound plan", "requires": {}, "cost_tier": "free", "quality_tier": "high", "offline": true, "notes": "Read cli-hub-matrix/video-creation/references/sound-design.md, then write sound_design.md with stems, cue times, story function, ducking notes, and section loudness targets; shape the ending/final act intentionally (escalation, silence/hold, hit/drop, source-audio reveal, or resolve)."},
+            {"kind": "native", "name": "ffmpeg/sox procedural stems", "requires": {"binary": ["ffmpeg"]}, "cost_tier": "free", "quality_tier": "good", "offline": true, "notes": "Short SFX, impacts, whooshes, and risers only; filter, envelope, and gain-stage every generated stem. Never use raw Gaussian/full-band noise as a music bed or repeated transition effect."},
+            {"kind": "python", "name": "pydub/numpy procedural stems", "requires": {"package": ["pydub", "numpy"]}, "cost_tier": "free", "quality_tier": "good", "offline": true, "notes": "Programmatic stem synthesis and mixing; same procedural-audio gate as the ffmpeg/sox path — accent stems only, not the main music bed for polished 60+ second videos."},
+            {"kind": "public-cli", "name": "Generated music provider", "requires": {"binary": ["suno"]}, "cost_tier": "metered", "quality_tier": "high", "offline": false, "notes": "Locally generated score sections via the provider chosen for music.generate (suno checked here; minimax-cli or Udio with UDIO_API_KEY also apply). Follow music.generate cost/consent rules."},
+            {"kind": "agent-skill", "name": "Downloaded/authorized music", "requires": {}, "cost_tier": "free", "quality_tier": "high", "offline": false, "notes": "Route through music.search + music.download, or install the music-downloader skill with `npx skills add https://github.com/nymbo/skills --skill music-downloader`. Use only relevant music the user is authorized to use; run the source-audio gate before mixing source audio with new music or narration."}
+          ]
+        },
+        {
+          "id": "media.analyze",
+          "intent": "Segment, label, OCR, and index video footage so an editor can find usable shots across many clips.",
+          "inputs": ["video_clips:path[]", "focus?:shots|text|people|objects|actions"],
+          "outputs": ["scene_index:path", "keyframes:path[]", "labels:json"],
+          "skill_search_hints": ["scene detection", "video indexing", "video OCR", "shot labels", "scene index"],
+          "providers": [
+            {"kind": "public-cli", "name": "PySceneDetect scenedetect", "requires": {"binary": ["scenedetect", "ffmpeg"]}, "cost_tier": "free", "quality_tier": "high", "offline": true, "notes": "Fast local scene cut detection; can save scene lists and start/mid/end keyframes. For found-footage edits, build scene_library.json and use cli-hub-matrix/video-creation/references/source-triage.md for the source rejection checklist and contact-sheet requirements."},
+            {"kind": "api", "name": "Google Cloud Video Intelligence", "requires": {"env": ["GOOGLE_APPLICATION_CREDENTIALS"]}, "cost_tier": "metered", "quality_tier": "sota", "offline": false, "notes": "Use for labels, people, objects, text, speech, and shot-change annotations when cloud processing is acceptable."},
+            {"kind": "api", "name": "TwelveLabs video search/index", "requires": {"env": ["TWELVELABS_API_KEY"], "package": ["twelvelabs"]}, "cost_tier": "metered", "quality_tier": "sota", "offline": false, "notes": "Use for semantic search over larger footage libraries and multimodal visual/audio indexing."},
+            {"kind": "python", "name": "PaddleOCR on sampled keyframes", "requires": {"package": ["paddleocr"]}, "cost_tier": "free", "quality_tier": "good", "offline": true, "notes": "Run after keyframe extraction to index visible text, signage, lower thirds, and hard subtitles; it complements scene detection rather than replacing it."}
+          ]
+        },
+        {
+          "id": "text.transcribe",
+          "intent": "Transcribe speech to text and produce subtitle files (SRT/ASS).",
+          "inputs": ["audio_or_video:path", "lang?:code"],
+          "outputs": ["subtitles:path", "transcript:text"],
+          "skill_search_hints": ["subtitle", "transcribe", "speech-to-text"],
+          "providers": [
+            {"kind": "harness-cli", "name": "cli-anything-videocaptioner", "requires": {"binary": ["cli-anything-videocaptioner"]}, "cost_tier": "free", "quality_tier": "high", "offline": true, "notes": "Can use cloud ASR backends if configured."},
+            {"kind": "python", "name": "openai-whisper", "requires": {"package": ["whisper"]}, "cost_tier": "free", "quality_tier": "high", "offline": true, "notes": "First use may download model weights. Prefer small/base CPU models for drafts; use larger models only when runtime/resources fit the task."},
+            {"kind": "python", "name": "faster-whisper/stable-ts", "requires": {"package": ["faster_whisper"]}, "cost_tier": "free", "quality_tier": "high", "offline": true, "notes": "Package availability does not guarantee model cache or acceptable runtime. Choose model size by quality/time constraints."},
+            {"kind": "api", "name": "AssemblyAI", "requires": {"env": ["ASSEMBLYAI_API_KEY"]}, "cost_tier": "paid", "quality_tier": "sota", "offline": false},
+            {"kind": "api", "name": "Deepgram", "requires": {"env": ["DEEPGRAM_API_KEY"]}, "cost_tier": "paid", "quality_tier": "sota", "offline": false},
+            {"kind": "api", "name": "Google Speech-to-Text", "requires": {"env": ["GOOGLE_CLOUD_PROJECT"]}, "cost_tier": "metered", "quality_tier": "high", "offline": false}
+          ]
+        },
+        {
+          "id": "text.caption",
+          "intent": "Design, time, render, and QC visible captions, subtitles, lyrics, karaoke, lower thirds, and trailer title hits so they look polished and genre-appropriate.",
+          "inputs": ["captions_source:path", "video?:path", "style?:text", "aspect_ratio?:text", "language?:code"],
+          "outputs": ["captions_ass_or_overlay:path", "captions_style:path", "caption_preview_frames:path[]", "captions_qc:path"],
+          "skill_search_hints": ["caption design", "subtitle styling", "ASS subtitles", "kinetic captions", "lyrics karaoke", "caption QC"],
+          "providers": [
+            {"kind": "agent-native", "name": "Captions reference module", "requires": {}, "cost_tier": "free", "quality_tier": "high", "offline": true, "notes": "Read cli-hub-matrix/video-creation/references/captions.md. Use for polished visible captions, subtitles, lyrics, lower thirds, genre presets, safe-zone rules, and caption QC."},
+            {"kind": "native", "name": "ASS + ffmpeg subtitles", "requires": {"binary": ["ffmpeg"]}, "cost_tier": "free", "quality_tier": "high", "offline": true, "notes": "Deterministic local path for styled subtitle burn-in on edited footage; supply fontsdir when custom fonts are used."},
+            {"kind": "agent-skill", "name": "HyperFrames captions workflow", "requires": {"binary": ["hyperframes", "ffmpeg"]}, "cost_tier": "free", "quality_tier": "high", "offline": true, "notes": "Install with `npx skills add heygen-com/hyperframes --skill hyperframes`. Use only when captions are part of an HTML/CSS/GSAP motion composition, karaoke, audio-reactive typography, or digital launch video."},
+            {"kind": "python", "name": "pysubs2 ASS authoring", "requires": {"package": ["pysubs2"], "binary": ["ffmpeg"]}, "cost_tier": "free", "quality_tier": "high", "offline": true, "notes": "Programmatically author ASS events/styles while keeping final burn-in deterministic through ffmpeg."},
+            {"kind": "python", "name": "MoviePy/Pillow transparent overlays", "requires": {"package": ["moviepy", "PIL"]}, "cost_tier": "free", "quality_tier": "good", "offline": true, "notes": "Use only when custom layout exceeds ASS and the project already uses a Python render path; inspect caption-heavy frames before delivery."}
+          ]
+        },
+        {
+          "id": "composite.assemble",
+          "intent": "Assemble clips on a timeline with transitions, following the creative direction, story arc, source roles, and audio plan.",
+          "inputs": ["clips:path[]", "edit_plan?:json", "creative_direction?:path", "audio_plan?:path"],
+          "outputs": ["video:path"],
+          "skill_search_hints": ["video editing", "timeline", "NLE", "story arc", "beat map", "audio plan", "hyperframes", "website to video", "product launch video", "digital launch video"],
+          "providers": [
+            {"kind": "harness-cli", "name": "cli-anything-kdenlive", "requires": {"binary": ["cli-anything-kdenlive"]}, "cost_tier": "free", "quality_tier": "high", "offline": true, "notes": "Use the provider-boundary pattern in cli-hub-matrix/video-creation/references/nle-shotcut-kdenlive.md: ffmpeg for mezzanine prep, the NLE harness for project/timeline/tracks/transitions/render, then ffmpeg for post-NLE captions, normalization, muxing, and doctor evidence."},
+            {"kind": "harness-cli", "name": "cli-anything-shotcut", "requires": {"binary": ["cli-anything-shotcut"]}, "cost_tier": "free", "quality_tier": "high", "offline": true, "notes": "Use the provider-boundary pattern in cli-hub-matrix/video-creation/references/nle-shotcut-kdenlive.md: ffmpeg for mezzanine prep, the NLE harness for project/timeline/tracks/transitions/render, then ffmpeg for post-NLE captions, normalization, muxing, and doctor evidence."},
+            {"kind": "python", "name": "moviepy", "requires": {"package": ["moviepy"], "binary": ["ffmpeg"]}, "cost_tier": "free", "quality_tier": "good", "offline": true},
+            {"kind": "python", "name": "ffmpeg-python", "requires": {"package": ["ffmpeg"], "binary": ["ffmpeg"]}, "cost_tier": "free", "quality_tier": "high", "offline": true},
+            {"kind": "native", "name": "ffmpeg concat/filter_complex", "requires": {"binary": ["ffmpeg"]}, "cost_tier": "free", "quality_tier": "high", "offline": true},
+            {"kind": "agent-skill", "name": "HyperFrames skill/CLI", "requires": {"binary": ["hyperframes", "ffmpeg"]}, "cost_tier": "free", "quality_tier": "good", "offline": true, "notes": "Install skill with `npx skills add heygen-com/hyperframes`; CLI can also run via `npx hyperframes preview/render`. Use only for website/product-page or digital UI-driven launch videos where HTML/CSS/GSAP composition is appropriate, not as a general NLE or Remotion/React path."}
+          ]
+        },
+        {
+          "id": "composite.overlay",
+          "intent": "Apply already-designed caption/subtitle assets, watermarks, or picture-in-picture layers onto a video.",
+          "inputs": ["video:path", "overlay:path_or_srt"],
+          "outputs": ["video:path"],
+          "skill_search_hints": ["burn subtitles", "caption overlay", "watermark", "picture in picture", "overlay"],
+          "providers": [
+            {"kind": "native", "name": "ffmpeg -vf subtitles/overlay", "requires": {"binary": ["ffmpeg"]}, "cost_tier": "free", "quality_tier": "high", "offline": true},
+            {"kind": "python", "name": "moviepy (CompositeVideoClip)", "requires": {"package": ["moviepy"]}, "cost_tier": "free", "quality_tier": "good", "offline": true}
+          ]
+        },
+        {
+          "id": "package.thumbnail",
+          "intent": "Create a thumbnail image or social card.",
+          "inputs": ["concept:text", "reference?:path"],
+          "outputs": ["image:path"],
+          "skill_search_hints": ["thumbnail", "social card", "image design"],
+          "providers": [
+            {"kind": "harness-cli", "name": "cli-anything-gimp", "requires": {"binary": ["cli-anything-gimp"]}, "cost_tier": "free", "quality_tier": "high", "offline": true},
+            {"kind": "harness-cli", "name": "cli-anything-krita", "requires": {"binary": ["cli-anything-krita"]}, "cost_tier": "free", "quality_tier": "high", "offline": true},
+            {"kind": "harness-cli", "name": "cli-anything-inkscape", "requires": {"binary": ["cli-anything-inkscape"]}, "cost_tier": "free", "quality_tier": "high", "offline": true},
+            {"kind": "python", "name": "Pillow", "requires": {"package": ["PIL"]}, "cost_tier": "free", "quality_tier": "good", "offline": true},
+            {"kind": "python", "name": "cairosvg/html2image", "requires": {"package": ["cairosvg"]}, "cost_tier": "free", "quality_tier": "good", "offline": true},
+            {"kind": "api", "name": "OpenAI GPT-Image-1", "requires": {"env": ["OPENAI_API_KEY"]}, "cost_tier": "metered", "quality_tier": "sota", "offline": false},
+            {"kind": "api", "name": "Google Nano Banana", "requires": {"env": ["GOOGLE_CLOUD_PROJECT"]}, "cost_tier": "metered", "quality_tier": "high", "offline": false},
+            {"kind": "api", "name": "Ideogram", "requires": {"env": ["IDEOGRAM_API_KEY"]}, "cost_tier": "metered", "quality_tier": "high", "offline": false},
+            {"kind": "api", "name": "Stability AI", "requires": {"env": ["STABILITY_API_KEY"]}, "cost_tier": "metered", "quality_tier": "high", "offline": false},
+            {"kind": "native", "name": "ffmpeg frame-grab", "requires": {"binary": ["ffmpeg"]}, "cost_tier": "free", "quality_tier": "basic", "offline": true},
+            {"kind": "native", "name": "ImageMagick convert/magick", "requires": {"binary": ["magick"]}, "cost_tier": "free", "quality_tier": "good", "offline": true}
+          ]
+        },
+        {
+          "id": "package.encode",
+          "intent": "Final mux / codec / container for the output video.",
+          "inputs": ["video:path", "target?:codec_or_container"],
+          "outputs": ["video:path"],
+          "skill_search_hints": ["encode", "transcode", "codec"],
+          "providers": [
+            {"kind": "native", "name": "ffmpeg", "requires": {"binary": ["ffmpeg"]}, "cost_tier": "free", "quality_tier": "sota", "offline": true}
+          ]
+        },
+        {
+          "id": "quality.review",
+          "intent": "Check rendered video for technical, editorial, story-structure, and audio defects before delivery.",
+          "inputs": ["video:path", "subtitles?:path", "reference?:path", "creative_direction?:path"],
+          "outputs": ["qc_report:path", "preview_frames:path[]"],
+          "skill_search_hints": ["video qc", "ffmpeg blackdetect", "loudness LUFS", "subtitle layout", "story review", "audio flatness", "ffprobe"],
+          "providers": [
+            {"kind": "native", "name": "ffmpeg/ffprobe QC filters", "requires": {"binary": ["ffmpeg", "ffprobe"]}, "cost_tier": "free", "quality_tier": "high", "offline": true, "notes": "Primary local QC path for metadata, black frames, silence, freezes, crop/aspect checks, and LUFS/loudness analysis. For polished videos, also run the art gates in cli-hub-matrix/video-creation/references/art-direction-review.md and the story/audio rubric in references/story-structure-audio.md."},
+            {"kind": "native", "name": "MediaInfo CLI", "requires": {"binary": ["mediainfo"]}, "cost_tier": "free", "quality_tier": "high", "offline": true, "notes": "Use for independent container/codec/bitrate/duration/aspect-ratio metadata checks."},
+            {"kind": "public-cli", "name": "ffmpeg-quality-metrics / VMAF", "requires": {"binary": ["ffmpeg-quality-metrics", "ffmpeg"]}, "cost_tier": "free", "quality_tier": "high", "offline": true, "notes": "Install with `pipx install ffmpeg-quality-metrics`; source: https://github.com/slhck/ffmpeg-quality-metrics. Use VMAF/SSIM/PSNR only when a reference video exists."},
+            {"kind": "bundled-script", "name": "Video doctor helper", "requires": {"binary": ["ffmpeg", "ffprobe"]}, "cost_tier": "free", "quality_tier": "high", "offline": true, "notes": "Run cli-hub-matrix/video-creation/scripts/video_doctor.py with the system Python; subcommands probe/captions/sources/frames/tail/audio/lint produce investigation evidence, not pass/fail verdicts. For every promoted final, follow cli-hub-matrix/video-creation/references/render-doctor.md (hash the candidate, regenerate frames from the promoted path, refresh reports)."}
+          ]
+        }
+      ],
+      "recipes": [
+        {
+          "id": "ai-short",
+          "description": "Fully-generative social short.",
+          "capabilities_used": ["script.storyboard", "visual.generate", "audio.synthesize", "text.caption", "music.generate", "music.search", "music.download", "sound.design", "composite.assemble", "composite.overlay", "package.thumbnail", "quality.review", "package.encode"]
+        },
+        {
+          "id": "screencast-tutorial",
+          "description": "Record a screen walkthrough with narration and subtitles.",
+          "capabilities_used": ["script.storyboard", "visual.capture", "audio.capture", "text.transcribe", "text.caption", "composite.overlay", "package.thumbnail", "quality.review", "package.encode"]
+        },
+        {
+          "id": "talking-head-explainer",
+          "description": "Webcam + b-roll + captions.",
+          "capabilities_used": ["script.storyboard", "visual.capture", "video.search", "video.download", "music.search", "music.download", "sound.design", "visual.generate", "media.analyze", "audio.capture", "text.transcribe", "text.caption", "composite.assemble", "composite.overlay", "package.thumbnail", "quality.review", "package.encode"]
+        },
+        {
+          "id": "podcast-to-video",
+          "description": "Audio-first, visualize and caption for video platforms.",
+          "capabilities_used": ["script.storyboard", "audio.capture", "text.transcribe", "text.caption", "package.thumbnail", "composite.overlay", "composite.assemble", "quality.review", "package.encode"]
+        },
+        {
+          "id": "found-footage-montage",
+          "description": "Find internet clips, download them with provenance, then edit a montage.",
+          "capabilities_used": ["script.storyboard", "video.search", "video.download", "media.analyze", "sound.design", "text.transcribe", "text.caption", "composite.assemble", "composite.overlay", "package.thumbnail", "quality.review", "package.encode"]
+        },
+        {
+          "id": "existing-song-music-video",
+          "description": "Build a music video around a user-specified or discovered existing song.",
+          "capabilities_used": ["music.search", "music.download", "script.storyboard", "video.search", "video.download", "media.analyze", "sound.design", "text.caption", "composite.assemble", "composite.overlay", "package.thumbnail", "quality.review", "package.encode"]
+        },
+        {
+          "id": "digital-product-launch",
+          "description": "Product/site-driven launch video with animated UI, typography, and motion graphics.",
+          "capabilities_used": ["script.storyboard", "visual.capture", "audio.synthesize", "text.caption", "music.generate", "music.search", "music.download", "sound.design", "composite.assemble", "composite.overlay", "package.thumbnail", "package.encode", "quality.review"]
+        }
+      ],
+      "known_gaps": [
+        {
+          "capability": "publish.upload",
+          "reason": "No first-party or public CLI for YouTube/TikTok/Bilibili/Instagram yet.",
+          "workaround": "Instruct the user to upload manually via the web UI, or escalate to a custom script using each platform's v3 API with an OAuth token the user supplies."
+        },
+        {
+          "capability": "visual.generate",
+          "reason": "Sota-tier cinematic output is only available via paid APIs (Runway, Kling, Seedance).",
+          "workaround": "Use generate-veo-video or jimeng for high-quality output when configured; avoid pulling complex local GPU/weights stacks into the matrix by default."
+        },
+        {
+          "capability": "rights.provenance",
+          "reason": "No automated license/TOS/provenance verifier for web-sourced video or music.",
+          "workaround": "Save sources.json/music_sources.json with source URL, creator, license, intended use, and attribution text; ask the user before using unclear or restricted media. Use cli-hub-matrix/video-creation/references/source-triage.md for platform-origin evidence levels."
+        },
+        {
+          "capability": "agent-skill.preflight",
+          "reason": "External agent skills are reported as agent-installable instead of available/missing because their local install state is not machine-checkable by the env/binary/package preflight contract.",
+          "workaround": "Use provider notes and the SKILL.md source/install table to install or inspect the external skill before relying on it."
+        }
+      ],
+      "suggest_to_user_template": "To enable <capability> via <provider>, please set <ENV_VAR>. Cost: <cost_tier>. Quality: <quality_tier>. Reply 'skip' to fall back to <next provider>."
+    },
+    {
+      "name": "knowledge-research",
+      "display_name": "Knowledge / Office / Research",
+      "version": "1",
+      "schema_version": "2",
+      "description": "Capability-based matrix for research, note-taking, document authoring, and publishing: web/literature search, article retrieval, citations/references, notes/PKM, outlining, multi-doc synthesis, office document authoring (DOCX/XLSX/PPTX/PDF), format conversion, PDF manipulation, diagrams, web publishing, and LaTeX builds. Providers include harness CLIs, public CLIs, Python libs, native binaries, and cloud APIs.",
+      "category": "knowledge",
+      "matrix": "cli-matrix",
+      "matrix_id": "S2",
+      "homepage": "https://github.com/HKUDS/CLI-Anything/blob/main/docs/cli-matrix/cli-matrix-plan.md",
+      "skill_md": "cli-hub-matrix/knowledge-research/SKILL.md",
+      "clis": [
+        "exa",
+        "browser",
+        "safari",
+        "clibrowser",
+        "zotero",
+        "obsidian",
+        "mubu",
+        "notebooklm",
+        "intelwatch",
+        "libreoffice",
+        "anygen",
+        "drawio",
+        "mermaid"
+      ],
+      "capabilities": [
+        {
+          "id": "research.search",
+          "intent": "Search the web and academic literature for candidate sources on a topic.",
+          "inputs": ["query:text", "scope?:web|academic|news", "recency?:text"],
+          "outputs": ["results:json", "source_urls:string[]"],
+          "skill_search_hints": ["web search", "literature search", "academic search", "search API"],
+          "providers": [
+            {"kind": "harness-cli", "name": "cli-anything-exa", "requires": {"binary": ["cli-anything-exa"], "env": ["EXA_API_KEY"]}, "cost_tier": "metered", "quality_tier": "sota", "offline": false},
+            {"kind": "harness-cli", "name": "cli-anything-browser / safari / clibrowser", "requires": {"binary": ["cli-anything-browser"]}, "cost_tier": "free", "quality_tier": "high", "offline": false, "notes": "Browser-driven search and navigation; cli-anything-safari (macOS) and clibrowser are equivalent harness paths."},
+            {"kind": "python", "name": "duckduckgo-search", "requires": {"package": ["duckduckgo_search"]}, "cost_tier": "free", "quality_tier": "good", "offline": false},
+            {"kind": "python", "name": "googlesearch-python", "requires": {"package": ["googlesearch"]}, "cost_tier": "free", "quality_tier": "good", "offline": false},
+            {"kind": "api", "name": "Perplexity API", "requires": {"env": ["PERPLEXITY_API_KEY"]}, "cost_tier": "paid", "quality_tier": "sota", "offline": false},
+            {"kind": "api", "name": "Tavily", "requires": {"env": ["TAVILY_API_KEY"]}, "cost_tier": "metered", "quality_tier": "high", "offline": false},
+            {"kind": "api", "name": "Brave Search", "requires": {"env": ["BRAVE_API_KEY"]}, "cost_tier": "metered", "quality_tier": "good", "offline": false},
+            {"kind": "api", "name": "Google Custom Search", "requires": {"env": ["GOOGLE_API_KEY"]}, "cost_tier": "metered", "quality_tier": "high", "offline": false}
+          ]
+        },
+        {
+          "id": "research.retrieve",
+          "intent": "Fetch pages and extract readable article text, including JS-heavy pages.",
+          "inputs": ["urls:string[]", "render_js?:bool"],
+          "outputs": ["article_text:path[]", "page_snapshots:path[]"],
+          "skill_search_hints": ["web scraping", "article extraction", "readability", "headless browser"],
+          "providers": [
+            {"kind": "harness-cli", "name": "cli-anything-browser / safari / clibrowser", "requires": {"binary": ["cli-anything-browser"]}, "cost_tier": "free", "quality_tier": "high", "offline": false},
+            {"kind": "python", "name": "trafilatura", "requires": {"package": ["trafilatura"]}, "cost_tier": "free", "quality_tier": "high", "offline": true, "notes": "Best default extractor; extraction also works offline on saved HTML."},
+            {"kind": "python", "name": "readability-lxml", "requires": {"package": ["readability"]}, "cost_tier": "free", "quality_tier": "good", "offline": true},
+            {"kind": "python", "name": "httpx + manual parse", "requires": {"package": ["httpx"]}, "cost_tier": "free", "quality_tier": "basic", "offline": true},
+            {"kind": "python", "name": "playwright", "requires": {"package": ["playwright"]}, "cost_tier": "free", "quality_tier": "sota", "offline": false, "notes": "Needs `playwright install` browser download on first use; best for JS-heavy pages."},
+            {"kind": "api", "name": "Firecrawl", "requires": {"env": ["FIRECRAWL_API_KEY"]}, "cost_tier": "metered", "quality_tier": "sota", "offline": false},
+            {"kind": "api", "name": "ScrapingBee", "requires": {"env": ["SCRAPINGBEE_API_KEY"]}, "cost_tier": "paid", "quality_tier": "high", "offline": false}
+          ]
+        },
+        {
+          "id": "research.reference",
+          "intent": "Manage citations, bibliographies, BibTeX, and reference metadata.",
+          "inputs": ["dois_or_queries:string[]", "library?:path"],
+          "outputs": ["bibtex:path", "references:json"],
+          "skill_search_hints": ["citation", "bibtex", "zotero", "crossref", "reference manager"],
+          "providers": [
+            {"kind": "harness-cli", "name": "cli-anything-zotero", "requires": {"binary": ["cli-anything-zotero"]}, "cost_tier": "free", "quality_tier": "sota", "offline": true},
+            {"kind": "python", "name": "pyzotero", "requires": {"package": ["pyzotero"]}, "cost_tier": "free", "quality_tier": "high", "offline": false, "notes": "Needs a Zotero API key and library ID."},
+            {"kind": "python", "name": "habanero (Crossref)", "requires": {"package": ["habanero"]}, "cost_tier": "free", "quality_tier": "high", "offline": false},
+            {"kind": "python", "name": "bibtexparser", "requires": {"package": ["bibtexparser"]}, "cost_tier": "free", "quality_tier": "good", "offline": true},
+            {"kind": "api", "name": "Crossref REST", "requires": {}, "cost_tier": "free", "quality_tier": "high", "offline": false, "notes": "No key required; add a mailto for the polite pool."},
+            {"kind": "api", "name": "Semantic Scholar", "requires": {}, "cost_tier": "free", "quality_tier": "high", "offline": false, "notes": "SEMANTIC_SCHOLAR_API_KEY is optional for higher rate limits."}
+          ]
+        },
+        {
+          "id": "knowledge.note",
+          "intent": "Create, search, and maintain notes in a personal knowledge management system.",
+          "inputs": ["note:text", "vault?:path"],
+          "outputs": ["note_files:path[]"],
+          "skill_search_hints": ["note taking", "PKM", "obsidian", "markdown notes", "notion"],
+          "providers": [
+            {"kind": "harness-cli", "name": "cli-anything-obsidian", "requires": {"binary": ["cli-anything-obsidian"]}, "cost_tier": "free", "quality_tier": "sota", "offline": true},
+            {"kind": "harness-cli", "name": "cli-anything-mubu", "requires": {"binary": ["cli-anything-mubu"]}, "cost_tier": "free", "quality_tier": "high", "offline": false},
+            {"kind": "public-cli", "name": "obsidian-cli", "requires": {"binary": ["obsidian"]}, "cost_tier": "free", "quality_tier": "high", "offline": true, "notes": "Official Obsidian CLI bundled with Obsidian 1.12+; install via `cli-hub install obsidian-cli` and point it at a vault."},
+            {"kind": "native", "name": "raw markdown + git", "requires": {"binary": ["git"]}, "cost_tier": "free", "quality_tier": "good", "offline": true},
+            {"kind": "python", "name": "mdformat", "requires": {"package": ["mdformat"]}, "cost_tier": "free", "quality_tier": "good", "offline": true},
+            {"kind": "api", "name": "Notion API", "requires": {"env": ["NOTION_API_KEY"]}, "cost_tier": "free", "quality_tier": "sota", "offline": false, "notes": "Free tier suffices for most users; round-trips block/page IDs."}
+          ]
+        },
+        {
+          "id": "knowledge.outline",
+          "intent": "Build and manipulate hierarchical outlines (OPML/YAML/markdown) for documents and plans.",
+          "inputs": ["topic_or_doc:text", "format?:opml|yaml|markdown"],
+          "outputs": ["outline:path"],
+          "skill_search_hints": ["outliner", "OPML", "mind map", "mubu"],
+          "providers": [
+            {"kind": "harness-cli", "name": "cli-anything-mubu", "requires": {"binary": ["cli-anything-mubu"]}, "cost_tier": "free", "quality_tier": "high", "offline": false},
+            {"kind": "python", "name": "OPML via lxml", "requires": {"package": ["lxml"]}, "cost_tier": "free", "quality_tier": "good", "offline": true},
+            {"kind": "native", "name": "YAML outlines + yq", "requires": {"binary": ["yq"]}, "cost_tier": "free", "quality_tier": "good", "offline": true}
+          ]
+        },
+        {
+          "id": "knowledge.synthesize",
+          "intent": "Summarize and synthesize across multiple documents or sources into briefs, digests, or reports.",
+          "inputs": ["sources:path[]", "question?:text", "length?:text"],
+          "outputs": ["synthesis:path"],
+          "skill_search_hints": ["summarization", "multi-document synthesis", "notebooklm", "RAG"],
+          "providers": [
+            {"kind": "harness-cli", "name": "cli-anything-notebooklm", "requires": {"binary": ["cli-anything-notebooklm"]}, "cost_tier": "metered", "quality_tier": "sota", "offline": false},
+            {"kind": "harness-cli", "name": "cli-anything-intelwatch", "requires": {"binary": ["cli-anything-intelwatch"]}, "cost_tier": "free", "quality_tier": "high", "offline": false, "notes": "Partially offline; metered when cloud backends are configured."},
+            {"kind": "python", "name": "langchain / llama_index + local LLM", "requires": {"package": ["langchain"]}, "cost_tier": "free", "quality_tier": "high", "offline": true, "notes": "Pair with a local model via ollama; llama_index is an equivalent path."},
+            {"kind": "python", "name": "haystack", "requires": {"package": ["haystack"]}, "cost_tier": "free", "quality_tier": "good", "offline": false, "notes": "Partial offline support depending on pipeline components."},
+            {"kind": "api", "name": "Claude / OpenAI / Gemini long context", "requires": {"env": ["ANTHROPIC_API_KEY"]}, "cost_tier": "metered", "quality_tier": "sota", "offline": false, "notes": "Any long-context model key works (ANTHROPIC_API_KEY checked here; OPENAI_API_KEY or GOOGLE_API_KEY also apply)."}
+          ]
+        },
+        {
+          "id": "document.author",
+          "intent": "Author office documents — DOCX, XLSX, PPTX, PDF — from structured content.",
+          "inputs": ["content:path_or_text", "format:docx|xlsx|pptx|pdf", "template?:path"],
+          "outputs": ["document:path"],
+          "skill_search_hints": ["docx", "pptx", "spreadsheet", "report generation", "office documents"],
+          "providers": [
+            {"kind": "harness-cli", "name": "cli-anything-libreoffice", "requires": {"binary": ["cli-anything-libreoffice"]}, "cost_tier": "free", "quality_tier": "high", "offline": true},
+            {"kind": "harness-cli", "name": "cli-anything-anygen", "requires": {"binary": ["cli-anything-anygen"]}, "cost_tier": "free", "quality_tier": "high", "offline": true},
+            {"kind": "python", "name": "python-docx / openpyxl / python-pptx / reportlab", "requires": {"package": ["docx"]}, "cost_tier": "free", "quality_tier": "good", "offline": true, "notes": "Install per output format; import names are docx (DOCX), openpyxl (XLSX), pptx (PPTX), reportlab (PDF)."},
+            {"kind": "api", "name": "Google Docs API", "requires": {"env": ["GOOGLE_APPLICATION_CREDENTIALS"]}, "cost_tier": "metered", "quality_tier": "sota", "offline": false, "notes": "OAuth/service-account credentials required."},
+            {"kind": "api", "name": "Microsoft Graph", "requires": {"env": ["MICROSOFT_GRAPH_TOKEN"]}, "cost_tier": "metered", "quality_tier": "sota", "offline": false, "notes": "Azure app registration + token required."}
+          ]
+        },
+        {
+          "id": "document.format",
+          "intent": "Convert documents between formats (markdown, DOCX, HTML, PDF, EPUB, ...).",
+          "inputs": ["document:path", "target:format"],
+          "outputs": ["document:path"],
+          "skill_search_hints": ["pandoc", "document conversion", "markdown to pdf", "docx to pdf"],
+          "providers": [
+            {"kind": "native", "name": "pandoc", "requires": {"binary": ["pandoc"]}, "cost_tier": "free", "quality_tier": "sota", "offline": true},
+            {"kind": "harness-cli", "name": "cli-anything-libreoffice (headless convert)", "requires": {"binary": ["cli-anything-libreoffice"]}, "cost_tier": "free", "quality_tier": "high", "offline": true},
+            {"kind": "python", "name": "docx2pdf", "requires": {"package": ["docx2pdf"]}, "cost_tier": "free", "quality_tier": "good", "offline": true, "notes": "Needs Word or LibreOffice installed."},
+            {"kind": "python", "name": "weasyprint", "requires": {"package": ["weasyprint"]}, "cost_tier": "free", "quality_tier": "high", "offline": true},
+            {"kind": "api", "name": "CloudConvert", "requires": {"env": ["CLOUDCONVERT_API_KEY"]}, "cost_tier": "metered", "quality_tier": "sota", "offline": false}
+          ]
+        },
+        {
+          "id": "document.pdf",
+          "intent": "Split, merge, OCR, and extract text/tables from PDFs.",
+          "inputs": ["pdf:path", "operation:split|merge|ocr|extract"],
+          "outputs": ["pdf_or_text:path"],
+          "skill_search_hints": ["pdf manipulation", "pdf ocr", "pdf extract", "qpdf"],
+          "providers": [
+            {"kind": "native", "name": "qpdf / pdftk", "requires": {"binary": ["qpdf"]}, "cost_tier": "free", "quality_tier": "sota", "offline": true, "notes": "pdftk is an equivalent alternative for split/merge/forms."},
+            {"kind": "python", "name": "pypdf", "requires": {"package": ["pypdf"]}, "cost_tier": "free", "quality_tier": "high", "offline": true},
+            {"kind": "python", "name": "pdfplumber", "requires": {"package": ["pdfplumber"]}, "cost_tier": "free", "quality_tier": "high", "offline": true, "notes": "Best local path for text and table extraction."},
+            {"kind": "python", "name": "pdf2image", "requires": {"package": ["pdf2image"]}, "cost_tier": "free", "quality_tier": "good", "offline": true, "notes": "Needs poppler installed."},
+            {"kind": "native", "name": "ocrmypdf", "requires": {"binary": ["ocrmypdf", "tesseract"]}, "cost_tier": "free", "quality_tier": "high", "offline": true},
+            {"kind": "api", "name": "Adobe PDF Services", "requires": {"env": ["PDF_SERVICES_CLIENT_ID"]}, "cost_tier": "paid", "quality_tier": "sota", "offline": false, "notes": "Adobe PDF Services credentials (client id + secret)."}
+          ]
+        },
+        {
+          "id": "diagram.create",
+          "intent": "Create diagrams, flowcharts, and architecture drawings.",
+          "inputs": ["spec:text_or_path", "format?:svg|png|drawio|mermaid"],
+          "outputs": ["diagram:path"],
+          "skill_search_hints": ["diagram", "flowchart", "mermaid", "graphviz", "drawio"],
+          "providers": [
+            {"kind": "harness-cli", "name": "cli-anything-drawio", "requires": {"binary": ["cli-anything-drawio"]}, "cost_tier": "free", "quality_tier": "sota", "offline": true},
+            {"kind": "harness-cli", "name": "cli-anything-mermaid", "requires": {"binary": ["cli-anything-mermaid"]}, "cost_tier": "free", "quality_tier": "high", "offline": true},
+            {"kind": "native", "name": "graphviz (dot)", "requires": {"binary": ["dot"]}, "cost_tier": "free", "quality_tier": "high", "offline": true},
+            {"kind": "native", "name": "plantuml", "requires": {"binary": ["plantuml"]}, "cost_tier": "free", "quality_tier": "high", "offline": true, "notes": "Needs Java."}
+          ]
+        },
+        {
+          "id": "publish.web",
+          "intent": "Publish articles or posts to a website, blog, or CMS.",
+          "inputs": ["content:path", "target:cms_or_site"],
+          "outputs": ["published_url:text"],
+          "skill_search_hints": ["blog publishing", "CMS", "static site", "wordpress", "ghost"],
+          "providers": [
+            {"kind": "public-cli", "name": "contentful", "requires": {"binary": ["contentful"]}, "cost_tier": "metered", "quality_tier": "high", "offline": false, "notes": "Needs a Contentful space token; install via `cli-hub install contentful`."},
+            {"kind": "public-cli", "name": "sanity", "requires": {"binary": ["sanity"]}, "cost_tier": "metered", "quality_tier": "high", "offline": false, "notes": "Needs a Sanity project token; install via `cli-hub install sanity`."},
+            {"kind": "native", "name": "hugo / mkdocs / jekyll / pelican", "requires": {"binary": ["hugo"]}, "cost_tier": "free", "quality_tier": "high", "offline": true, "notes": "Static-site path (hugo checked here); mkdocs/pelican are Python equivalents, jekyll is Ruby."},
+            {"kind": "api", "name": "WordPress REST", "requires": {"env": ["WORDPRESS_TOKEN"]}, "cost_tier": "free", "quality_tier": "high", "offline": false, "notes": "Application password/token for the target site."},
+            {"kind": "api", "name": "Ghost Admin", "requires": {"env": ["GHOST_ADMIN_KEY"]}, "cost_tier": "free", "quality_tier": "high", "offline": false},
+            {"kind": "api", "name": "Medium (legacy)", "requires": {"env": ["MEDIUM_TOKEN"]}, "cost_tier": "free", "quality_tier": "good", "offline": false, "notes": "Legacy API; availability not guaranteed."}
+          ]
+        },
+        {
+          "id": "publish.latex",
+          "intent": "Build PDFs from LaTeX sources.",
+          "inputs": ["tex:path"],
+          "outputs": ["pdf:path"],
+          "skill_search_hints": ["latex", "latexmk", "tectonic", "pdf build"],
+          "providers": [
+            {"kind": "native", "name": "latexmk + texlive", "requires": {"binary": ["latexmk"]}, "cost_tier": "free", "quality_tier": "sota", "offline": true},
+            {"kind": "python", "name": "pylatex", "requires": {"package": ["pylatex"]}, "cost_tier": "free", "quality_tier": "high", "offline": true, "notes": "Needs a TeX distribution installed."},
+            {"kind": "native", "name": "Tectonic", "requires": {"binary": ["tectonic"]}, "cost_tier": "free", "quality_tier": "high", "offline": true},
+            {"kind": "api", "name": "Overleaf API", "requires": {"env": ["OVERLEAF_API_KEY"]}, "cost_tier": "paid", "quality_tier": "sota", "offline": false}
+          ]
+        }
+      ],
+      "recipes": [
+        {
+          "id": "literature-review",
+          "description": "Survey a topic, extract key papers, synthesize.",
+          "capabilities_used": ["research.search", "research.retrieve", "research.reference", "knowledge.synthesize", "document.author"]
+        },
+        {
+          "id": "meeting-to-doc",
+          "description": "Turn a recorded meeting into a structured document.",
+          "capabilities_used": ["knowledge.synthesize", "document.author", "document.format"],
+          "notes": "Transcription comes from the video-creation (S1) matrix's text.transcribe capability; run it there first."
+        },
+        {
+          "id": "blog-post",
+          "description": "Research, write, and publish a post.",
+          "capabilities_used": ["research.search", "research.retrieve", "knowledge.synthesize", "document.author", "publish.web"]
+        },
+        {
+          "id": "paper-draft",
+          "description": "Research + citations + LaTeX build.",
+          "capabilities_used": ["research.reference", "knowledge.synthesize", "document.author", "publish.latex"]
+        },
+        {
+          "id": "competitive-brief",
+          "description": "Fetch competitor pages, extract positioning, produce a briefing deck (PPTX).",
+          "capabilities_used": ["research.retrieve", "knowledge.synthesize", "document.author"]
+        },
+        {
+          "id": "pdf-book-digest",
+          "description": "Ingest a PDF book, OCR if needed, produce chapter summaries + quote file.",
+          "capabilities_used": ["document.pdf", "knowledge.synthesize", "knowledge.note"]
+        }
+      ],
+      "known_gaps": [
+        {
+          "capability": "knowledge.note",
+          "reason": "Notion API exists as an escalation, but there is no harness for local-first Notion workflows (recurs in S11 team comms).",
+          "workaround": "Use cli-anything-obsidian or raw markdown locally, then sync to Notion via the API when NOTION_API_KEY is set."
+        },
+        {
+          "capability": "document.author",
+          "reason": "Google Docs / Microsoft 365 live editing is API-path only.",
+          "workaround": "Author locally (LibreOffice / python-docx) and upload, or escalate to Google Docs API / Microsoft Graph with user-supplied credentials."
+        },
+        {
+          "capability": "publish.latex",
+          "reason": "No agent-native LaTeX harness; latexmk + Tectonic cover the native path.",
+          "workaround": "Use the latexmk/Tectonic native binaries or pylatex."
+        },
+        {
+          "capability": "text.translate",
+          "reason": "No first-party translation CLI; Python fallbacks and APIs only.",
+          "workaround": "Translate directly as agent work, or escalate to a translation API the user supplies."
+        }
+      ],
+      "suggest_to_user_template": "To enable <capability> via <provider>, please set <ENV_VAR>. Cost: <cost_tier>. Quality: <quality_tier>. Reply 'skip' to fall back to <next provider>."
+    },
+    {
+      "name": "3d-cad",
+      "display_name": "3D & CAD",
+      "version": "1",
+      "schema_version": "2",
+      "description": "Capability-based matrix for 3D modeling, parametric CAD, sculpting, point clouds, photogrammetry, PBR texturing, preview/offline rendering, GPU frame debugging, fabrication (slicing and CAM), and game-engine export. Mostly offline-capable; providers include harness CLIs, Python libs, native binaries, and cloud APIs.",
+      "category": "3d",
+      "matrix": "cli-matrix",
+      "matrix_id": "S3",
+      "homepage": "https://github.com/HKUDS/CLI-Anything/blob/main/docs/cli-matrix/cli-matrix-plan.md",
+      "skill_md": "cli-hub-matrix/3d-cad/SKILL.md",
+      "clis": [
+        "blender",
+        "freecad",
+        "cloudcompare",
+        "cloudanalyzer",
+        "godot",
+        "renderdoc"
+      ],
+      "capabilities": [
+        {
+          "id": "model.mesh",
+          "intent": "Create, edit, and repair polygon meshes (organic or scanned geometry).",
+          "inputs": ["spec_or_mesh:text_or_path", "format?:stl|obj|ply|gltf"],
+          "outputs": ["mesh:path"],
+          "skill_search_hints": ["mesh modeling", "blender scripting", "mesh repair", "trimesh"],
+          "providers": [
+            {"kind": "harness-cli", "name": "cli-anything-blender", "requires": {"binary": ["cli-anything-blender"]}, "cost_tier": "free", "quality_tier": "sota", "offline": true},
+            {"kind": "python", "name": "trimesh", "requires": {"package": ["trimesh"]}, "cost_tier": "free", "quality_tier": "high", "offline": true},
+            {"kind": "python", "name": "pymeshlab", "requires": {"package": ["pymeshlab"]}, "cost_tier": "free", "quality_tier": "high", "offline": true},
+            {"kind": "python", "name": "open3d", "requires": {"package": ["open3d"]}, "cost_tier": "free", "quality_tier": "high", "offline": true},
+            {"kind": "python", "name": "pygalmesh", "requires": {"package": ["pygalmesh"]}, "cost_tier": "free", "quality_tier": "high", "offline": true, "notes": "Needs CGAL installed."}
+          ]
+        },
+        {
+          "id": "model.parametric",
+          "intent": "Model dimension-driven parts with parametric CAD.",
+          "inputs": ["dimensions_or_spec:text", "format?:step|fcstd|scad"],
+          "outputs": ["cad_model:path"],
+          "skill_search_hints": ["parametric CAD", "cadquery", "openscad", "freecad"],
+          "providers": [
+            {"kind": "harness-cli", "name": "cli-anything-freecad", "requires": {"binary": ["cli-anything-freecad"]}, "cost_tier": "free", "quality_tier": "sota", "offline": true},
+            {"kind": "python", "name": "cadquery", "requires": {"package": ["cadquery"]}, "cost_tier": "free", "quality_tier": "high", "offline": true},
+            {"kind": "python", "name": "build123d", "requires": {"package": ["build123d"]}, "cost_tier": "free", "quality_tier": "high", "offline": true},
+            {"kind": "native", "name": "OpenSCAD", "requires": {"binary": ["openscad"]}, "cost_tier": "free", "quality_tier": "high", "offline": true},
+            {"kind": "python", "name": "SolidPython", "requires": {"package": ["solid"]}, "cost_tier": "free", "quality_tier": "good", "offline": true, "notes": "Generates OpenSCAD code; needs the openscad binary to render."},
+            {"kind": "api", "name": "Onshape API", "requires": {"env": ["ONSHAPE_ACCESS_KEY"]}, "cost_tier": "paid", "quality_tier": "sota", "offline": false},
+            {"kind": "api", "name": "Fusion 360 API", "requires": {"env": ["FUSION360_TOKEN"]}, "cost_tier": "paid", "quality_tier": "sota", "offline": false}
+          ]
+        },
+        {
+          "id": "model.sculpt",
+          "intent": "Sculpt organic forms digitally.",
+          "inputs": ["base_mesh:path", "sculpt_plan:text"],
+          "outputs": ["mesh:path"],
+          "skill_search_hints": ["sculpting", "blender sculpt mode"],
+          "providers": [
+            {"kind": "harness-cli", "name": "cli-anything-blender (sculpt mode, scripted)", "requires": {"binary": ["cli-anything-blender"]}, "cost_tier": "free", "quality_tier": "good", "offline": true, "notes": "Agent-driven sculpting is impractical beyond Blender scripts; see known gaps (no ZBrush/Nomad path)."}
+          ]
+        },
+        {
+          "id": "pointcloud.process",
+          "intent": "Ingest, clean, register, and convert point clouds.",
+          "inputs": ["pointcloud:path[]", "operation?:clean|register|convert|analyze"],
+          "outputs": ["pointcloud_or_mesh:path"],
+          "skill_search_hints": ["point cloud", "registration", "las", "pdal", "cloudcompare"],
+          "providers": [
+            {"kind": "harness-cli", "name": "cli-anything-cloudcompare", "requires": {"binary": ["cli-anything-cloudcompare"]}, "cost_tier": "free", "quality_tier": "sota", "offline": true},
+            {"kind": "harness-cli", "name": "cli-anything-cloudanalyzer", "requires": {"binary": ["cli-anything-cloudanalyzer"]}, "cost_tier": "free", "quality_tier": "high", "offline": true},
+            {"kind": "python", "name": "open3d", "requires": {"package": ["open3d"]}, "cost_tier": "free", "quality_tier": "high", "offline": true},
+            {"kind": "python", "name": "laspy", "requires": {"package": ["laspy"]}, "cost_tier": "free", "quality_tier": "high", "offline": true},
+            {"kind": "native", "name": "pdal", "requires": {"binary": ["pdal"]}, "cost_tier": "free", "quality_tier": "sota", "offline": true},
+            {"kind": "python", "name": "pyvista", "requires": {"package": ["pyvista"]}, "cost_tier": "free", "quality_tier": "high", "offline": true}
+          ]
+        },
+        {
+          "id": "photogrammetry.reconstruct",
+          "intent": "Reconstruct 3D meshes from photo sets.",
+          "inputs": ["photos:path[]", "quality?:draft|high"],
+          "outputs": ["mesh:path", "pointcloud:path"],
+          "skill_search_hints": ["photogrammetry", "3d scan", "structure from motion", "meshroom", "colmap"],
+          "providers": [
+            {"kind": "native", "name": "Meshroom", "requires": {"binary": ["meshroom"]}, "cost_tier": "free", "quality_tier": "high", "offline": true},
+            {"kind": "native", "name": "colmap", "requires": {"binary": ["colmap"]}, "cost_tier": "free", "quality_tier": "high", "offline": true},
+            {"kind": "native", "name": "OpenMVG + OpenMVS", "requires": {"binary": ["openmvg", "openmvs"]}, "cost_tier": "free", "quality_tier": "high", "offline": true},
+            {"kind": "native", "name": "RealityCapture", "requires": {"binary": ["RealityCapture"]}, "cost_tier": "paid", "quality_tier": "sota", "offline": true, "notes": "Commercial license required."},
+            {"kind": "api", "name": "Polycam API", "requires": {"env": ["POLYCAM_API_KEY"]}, "cost_tier": "metered", "quality_tier": "sota", "offline": false},
+            {"kind": "api", "name": "Luma AI", "requires": {"env": ["LUMA_API_KEY"]}, "cost_tier": "metered", "quality_tier": "sota", "offline": false}
+          ]
+        },
+        {
+          "id": "material.texture",
+          "intent": "Create PBR textures and materials for meshes.",
+          "inputs": ["mesh:path", "material_spec:text"],
+          "outputs": ["textured_mesh:path", "texture_maps:path[]"],
+          "skill_search_hints": ["PBR texturing", "materials", "uv mapping", "shader nodes"],
+          "providers": [
+            {"kind": "harness-cli", "name": "cli-anything-blender (shader nodes, scripted)", "requires": {"binary": ["cli-anything-blender"]}, "cost_tier": "free", "quality_tier": "good", "offline": true},
+            {"kind": "python", "name": "bpy PBR synthesis", "requires": {"package": ["bpy"]}, "cost_tier": "free", "quality_tier": "good", "offline": true},
+            {"kind": "python", "name": "Pillow procedural maps", "requires": {"package": ["PIL"]}, "cost_tier": "free", "quality_tier": "basic", "offline": true}
+          ]
+        },
+        {
+          "id": "render.preview",
+          "intent": "Produce fast viewport/preview renders.",
+          "inputs": ["scene:path", "camera?:spec"],
+          "outputs": ["image:path"],
+          "skill_search_hints": ["preview render", "eevee", "viewport screenshot"],
+          "providers": [
+            {"kind": "harness-cli", "name": "cli-anything-blender (Eevee)", "requires": {"binary": ["cli-anything-blender"]}, "cost_tier": "free", "quality_tier": "high", "offline": true},
+            {"kind": "harness-cli", "name": "cli-anything-godot (viewport screenshot)", "requires": {"binary": ["cli-anything-godot"]}, "cost_tier": "free", "quality_tier": "good", "offline": true}
+          ]
+        },
+        {
+          "id": "render.offline",
+          "intent": "Produce final path-traced renders.",
+          "inputs": ["scene:path", "samples?:int", "resolution?:text"],
+          "outputs": ["image_or_animation:path"],
+          "skill_search_hints": ["path tracing", "cycles", "final render"],
+          "providers": [
+            {"kind": "harness-cli", "name": "cli-anything-blender (Cycles)", "requires": {"binary": ["cli-anything-blender"]}, "cost_tier": "free", "quality_tier": "sota", "offline": true, "notes": "GPU strongly recommended for acceptable render times."},
+            {"kind": "python", "name": "bpy + Cycles", "requires": {"package": ["bpy"]}, "cost_tier": "free", "quality_tier": "sota", "offline": true},
+            {"kind": "api", "name": "Octane Cloud", "requires": {"env": ["OCTANE_TOKEN"]}, "cost_tier": "paid", "quality_tier": "sota", "offline": false}
+          ]
+        },
+        {
+          "id": "gpu.debug",
+          "intent": "Capture and inspect GPU frames for graphics debugging.",
+          "inputs": ["application:path_or_pid"],
+          "outputs": ["frame_capture:path", "analysis:json"],
+          "skill_search_hints": ["gpu debugging", "frame capture", "renderdoc", "apitrace"],
+          "providers": [
+            {"kind": "harness-cli", "name": "cli-anything-renderdoc", "requires": {"binary": ["cli-anything-renderdoc"]}, "cost_tier": "free", "quality_tier": "sota", "offline": true},
+            {"kind": "native", "name": "apitrace", "requires": {"binary": ["apitrace"]}, "cost_tier": "free", "quality_tier": "high", "offline": true},
+            {"kind": "native", "name": "vulkan-tools", "requires": {"binary": ["vulkaninfo"]}, "cost_tier": "free", "quality_tier": "good", "offline": true}
+          ]
+        },
+        {
+          "id": "fabricate.slice",
+          "intent": "Slice meshes into 3D-printer gcode.",
+          "inputs": ["mesh:path", "printer_profile?:path"],
+          "outputs": ["gcode:path"],
+          "skill_search_hints": ["3d printing", "slicer", "gcode", "prusaslicer"],
+          "providers": [
+            {"kind": "native", "name": "PrusaSlicer CLI", "requires": {"binary": ["prusaslicer"]}, "cost_tier": "free", "quality_tier": "sota", "offline": true, "notes": "Check the mesh is manifold first (trimesh.Trimesh.is_volume or pymeshlab); slicers fail silently on non-manifold meshes."},
+            {"kind": "native", "name": "CuraEngine", "requires": {"binary": ["CuraEngine"]}, "cost_tier": "free", "quality_tier": "high", "offline": true},
+            {"kind": "native", "name": "slic3r", "requires": {"binary": ["slic3r"]}, "cost_tier": "free", "quality_tier": "good", "offline": true}
+          ]
+        },
+        {
+          "id": "fabricate.cam",
+          "intent": "Generate CNC/CAM toolpaths from CAD models.",
+          "inputs": ["cad_model:path", "machine_profile?:path"],
+          "outputs": ["gcode:path"],
+          "skill_search_hints": ["CAM", "CNC", "toolpath", "freecad path"],
+          "providers": [
+            {"kind": "harness-cli", "name": "cli-anything-freecad (Path workbench, scripted)", "requires": {"binary": ["cli-anything-freecad"]}, "cost_tier": "free", "quality_tier": "good", "offline": true},
+            {"kind": "python", "name": "pycam", "requires": {"package": ["pycam"]}, "cost_tier": "free", "quality_tier": "good", "offline": true},
+            {"kind": "native", "name": "kiri:moto", "requires": {"binary": ["kirimoto"]}, "cost_tier": "free", "quality_tier": "good", "offline": true, "notes": "Grid.Space kiri:moto; also runs as a local web app."},
+            {"kind": "api", "name": "Fusion 360 CAM / Onshape CAM", "requires": {"env": ["FUSION360_TOKEN"]}, "cost_tier": "paid", "quality_tier": "sota", "offline": false, "notes": "Onshape CAM via ONSHAPE_ACCESS_KEY is the equivalent escalation."}
+          ]
+        },
+        {
+          "id": "export.engine",
+          "intent": "Export/convert assets (glTF/FBX) and hand off to a game or viz engine.",
+          "inputs": ["asset:path", "target?:godot|gltf|fbx"],
+          "outputs": ["engine_asset:path"],
+          "skill_search_hints": ["gltf export", "game engine import", "fbx", "asset handoff"],
+          "providers": [
+            {"kind": "harness-cli", "name": "cli-anything-godot", "requires": {"binary": ["cli-anything-godot"]}, "cost_tier": "free", "quality_tier": "high", "offline": true},
+            {"kind": "harness-cli", "name": "cli-anything-blender (glTF/FBX export)", "requires": {"binary": ["cli-anything-blender"]}, "cost_tier": "free", "quality_tier": "sota", "offline": true, "notes": "Apply modifiers and bake materials before export; runtime engines don't read Blender shader graphs."},
+            {"kind": "python", "name": "pygltflib", "requires": {"package": ["pygltflib"]}, "cost_tier": "free", "quality_tier": "high", "offline": true},
+            {"kind": "python", "name": "trimesh glTF writer", "requires": {"package": ["trimesh"]}, "cost_tier": "free", "quality_tier": "good", "offline": true}
+          ]
+        }
+      ],
+      "recipes": [
+        {
+          "id": "printable-part",
+          "description": "Parametric CAD, then mesh, slice, and gcode.",
+          "capabilities_used": ["model.parametric", "model.mesh", "fabricate.slice"]
+        },
+        {
+          "id": "game-asset",
+          "description": "Model, texture, and export to an engine.",
+          "capabilities_used": ["model.mesh", "material.texture", "export.engine", "render.preview"],
+          "notes": "render.preview is optional."
+        },
+        {
+          "id": "reality-scan",
+          "description": "Photos to photogrammetry, clean mesh, then export.",
+          "capabilities_used": ["photogrammetry.reconstruct", "pointcloud.process", "model.mesh", "export.engine"]
+        },
+        {
+          "id": "cnc-part",
+          "description": "Parametric part, then CAM toolpath and gcode.",
+          "capabilities_used": ["model.parametric", "fabricate.cam"]
+        },
+        {
+          "id": "product-viz-still",
+          "description": "CAD import, scene setup, offline render.",
+          "capabilities_used": ["model.parametric", "model.mesh", "material.texture", "render.offline"]
+        },
+        {
+          "id": "gpu-bug-repro",
+          "description": "Capture a GPU frame, analyze, patch shader.",
+          "capabilities_used": ["gpu.debug", "render.preview"]
+        }
+      ],
+      "known_gaps": [
+        {
+          "capability": "material.texture",
+          "reason": "No open agent-native path approaches Substance 3D quality; Blender shader nodes are the current ceiling.",
+          "workaround": "Use scripted Blender shader nodes or bpy/Pillow procedural maps; ask the user for Substance-authored textures when quality is critical."
+        },
+        {
+          "capability": "fabricate.slice",
+          "reason": "PrusaSlicer/CuraEngine natives work but there is no harness-level wrapper (Bambu Studio / OrcaSlicer uncovered).",
+          "workaround": "Drive the native slicer CLIs directly; verify the mesh is manifold first."
+        },
+        {
+          "capability": "model.sculpt",
+          "reason": "Agent-driven sculpting is impractical beyond Blender scripts; no ZBrush/Nomad path.",
+          "workaround": "Use Blender sculpt-mode scripting for coarse forms or ask the user to sculpt manually."
+        },
+        {
+          "capability": "export.engine",
+          "reason": "Only Godot is covered on the harness side; no Unity Asset Pipeline / Unreal Datasmith path.",
+          "workaround": "Export glTF/FBX and instruct the user to import into Unity/Unreal manually."
+        }
+      ],
+      "suggest_to_user_template": "To enable <capability> via <provider>, please set <ENV_VAR>. Cost: <cost_tier>. Quality: <quality_tier>. Reply 'skip' to fall back to <next provider>."
+    },
+    {
+      "name": "game-development",
+      "display_name": "Game Development",
+      "version": "1",
+      "schema_version": "2",
+      "description": "Capability-based matrix for game development: engine authoring (Godot-first), 3D/2D/audio/notation assets, AI-generated assets, agent-driven playtesting, build packaging, store publishing, and telemetry/crash reporting. Providers include harness CLIs, public CLIs, Python libs, native binaries, and cloud APIs.",
+      "category": "game",
+      "matrix": "cli-matrix",
+      "matrix_id": "S4",
+      "homepage": "https://github.com/HKUDS/CLI-Anything/blob/main/docs/cli-matrix/cli-matrix-plan.md",
+      "skill_md": "cli-hub-matrix/game-development/SKILL.md",
+      "clis": [
+        "godot",
+        "blender",
+        "freecad",
+        "krita",
+        "inkscape",
+        "audacity",
+        "musescore",
+        "comfyui",
+        "slay_the_spire_ii"
+      ],
+      "capabilities": [
+        {
+          "id": "game.engine",
+          "intent": "Author and manipulate game projects, scenes, and scripts in an engine.",
+          "inputs": ["project:path", "change_spec:text"],
+          "outputs": ["project:path"],
+          "skill_search_hints": ["game engine", "godot", "pygame", "game scripting"],
+          "providers": [
+            {"kind": "harness-cli", "name": "cli-anything-godot", "requires": {"binary": ["cli-anything-godot"]}, "cost_tier": "free", "quality_tier": "sota", "offline": true},
+            {"kind": "python", "name": "pygame", "requires": {"package": ["pygame"]}, "cost_tier": "free", "quality_tier": "good", "offline": true},
+            {"kind": "python", "name": "arcade", "requires": {"package": ["arcade"]}, "cost_tier": "free", "quality_tier": "good", "offline": true},
+            {"kind": "python", "name": "panda3d", "requires": {"package": ["panda3d"]}, "cost_tier": "free", "quality_tier": "high", "offline": true},
+            {"kind": "python", "name": "ursina", "requires": {"package": ["ursina"]}, "cost_tier": "free", "quality_tier": "good", "offline": true}
+          ]
+        },
+        {
+          "id": "asset.3d",
+          "intent": "Produce 3D game assets (modeling, baking, engine-ready export).",
+          "inputs": ["spec:text", "format?:gltf|fbx|obj"],
+          "outputs": ["asset:path"],
+          "skill_search_hints": ["3d asset", "gltf", "blender", "game model"],
+          "providers": [
+            {"kind": "harness-cli", "name": "cli-anything-blender", "requires": {"binary": ["cli-anything-blender"]}, "cost_tier": "free", "quality_tier": "sota", "offline": true, "notes": "The full pipeline lives in the 3d-cad (S3) matrix: model.mesh, material.texture, export.engine."},
+            {"kind": "harness-cli", "name": "cli-anything-freecad", "requires": {"binary": ["cli-anything-freecad"]}, "cost_tier": "free", "quality_tier": "high", "offline": true},
+            {"kind": "python", "name": "trimesh", "requires": {"package": ["trimesh"]}, "cost_tier": "free", "quality_tier": "high", "offline": true},
+            {"kind": "python", "name": "pygltflib", "requires": {"package": ["pygltflib"]}, "cost_tier": "free", "quality_tier": "high", "offline": true}
+          ]
+        },
+        {
+          "id": "asset.2d",
+          "intent": "Create sprites, tiles, and UI art.",
+          "inputs": ["spec:text", "style?:text", "size?:px"],
+          "outputs": ["images:path[]"],
+          "skill_search_hints": ["sprites", "pixel art", "game ui art", "tileset"],
+          "providers": [
+            {"kind": "harness-cli", "name": "cli-anything-krita", "requires": {"binary": ["cli-anything-krita"]}, "cost_tier": "free", "quality_tier": "sota", "offline": true},
+            {"kind": "harness-cli", "name": "cli-anything-inkscape", "requires": {"binary": ["cli-anything-inkscape"]}, "cost_tier": "free", "quality_tier": "sota", "offline": true},
+            {"kind": "python", "name": "Pillow", "requires": {"package": ["PIL"]}, "cost_tier": "free", "quality_tier": "good", "offline": true},
+            {"kind": "native", "name": "aseprite", "requires": {"binary": ["aseprite"]}, "cost_tier": "paid", "quality_tier": "sota", "offline": true, "notes": "Commercial license required."},
+            {"kind": "python", "name": "pyxel", "requires": {"package": ["pyxel"]}, "cost_tier": "free", "quality_tier": "good", "offline": true},
+            {"kind": "api", "name": "OpenAI GPT-Image-1", "requires": {"env": ["OPENAI_API_KEY"]}, "cost_tier": "metered", "quality_tier": "sota", "offline": false},
+            {"kind": "api", "name": "Scenario GG", "requires": {"env": ["SCENARIO_API_KEY"]}, "cost_tier": "paid", "quality_tier": "sota", "offline": false},
+            {"kind": "api", "name": "Leonardo AI", "requires": {"env": ["LEONARDO_API_KEY"]}, "cost_tier": "paid", "quality_tier": "high", "offline": false}
+          ]
+        },
+        {
+          "id": "asset.audio",
+          "intent": "Create and process SFX and gameplay audio.",
+          "inputs": ["spec:text", "source_audio?:path"],
+          "outputs": ["audio:path[]"],
+          "skill_search_hints": ["game sfx", "sound effects", "audio asset"],
+          "providers": [
+            {"kind": "harness-cli", "name": "cli-anything-audacity", "requires": {"binary": ["cli-anything-audacity"]}, "cost_tier": "free", "quality_tier": "high", "offline": true},
+            {"kind": "python", "name": "pydub / librosa / soundfile", "requires": {"package": ["pydub"]}, "cost_tier": "free", "quality_tier": "good", "offline": true},
+            {"kind": "native", "name": "sfxr / jsfxr", "requires": {"binary": ["sfxr"]}, "cost_tier": "free", "quality_tier": "good", "offline": true},
+            {"kind": "api", "name": "ElevenLabs SFX", "requires": {"env": ["ELEVENLABS_API_KEY"]}, "cost_tier": "paid", "quality_tier": "sota", "offline": false},
+            {"kind": "api", "name": "Mubert", "requires": {"env": ["MUBERT_API_KEY"]}, "cost_tier": "metered", "quality_tier": "high", "offline": false}
+          ]
+        },
+        {
+          "id": "asset.notation",
+          "intent": "Compose and export music notation / scores (MIDI, MusicXML).",
+          "inputs": ["score_spec:text", "format?:midi|musicxml|pdf"],
+          "outputs": ["score:path"],
+          "skill_search_hints": ["music notation", "midi", "musescore", "score composition"],
+          "providers": [
+            {"kind": "harness-cli", "name": "cli-anything-musescore", "requires": {"binary": ["cli-anything-musescore"]}, "cost_tier": "free", "quality_tier": "sota", "offline": true},
+            {"kind": "python", "name": "music21", "requires": {"package": ["music21"]}, "cost_tier": "free", "quality_tier": "high", "offline": true},
+            {"kind": "python", "name": "mido", "requires": {"package": ["mido"]}, "cost_tier": "free", "quality_tier": "good", "offline": true},
+            {"kind": "python", "name": "abjad", "requires": {"package": ["abjad"]}, "cost_tier": "free", "quality_tier": "high", "offline": true}
+          ]
+        },
+        {
+          "id": "ai.gen-asset",
+          "intent": "Generate art/audio assets for games with AI, with reproducible seeds and prompts.",
+          "inputs": ["prompt:text", "seed?:int", "style?:text"],
+          "outputs": ["assets:path[]", "generation_manifest:json"],
+          "skill_search_hints": ["ai asset generation", "stable diffusion", "comfyui", "game art generation"],
+          "providers": [
+            {"kind": "harness-cli", "name": "cli-anything-comfyui", "requires": {"binary": ["cli-anything-comfyui"]}, "cost_tier": "free", "quality_tier": "high", "offline": true, "notes": "Needs ComfyUI plus model weights."},
+            {"kind": "public-cli", "name": "jimeng", "requires": {"binary": ["dreamina"]}, "cost_tier": "metered", "quality_tier": "high", "offline": false, "notes": "ByteDance Dreamina; install via `cli-hub install jimeng`."},
+            {"kind": "python", "name": "diffusers", "requires": {"package": ["diffusers"]}, "cost_tier": "free", "quality_tier": "good", "offline": true, "notes": "Needs model weights and ideally a GPU."},
+            {"kind": "python", "name": "replicate", "requires": {"package": ["replicate"], "env": ["REPLICATE_API_TOKEN"]}, "cost_tier": "metered", "quality_tier": "high", "offline": false},
+            {"kind": "api", "name": "Scenario GG", "requires": {"env": ["SCENARIO_API_KEY"]}, "cost_tier": "paid", "quality_tier": "sota", "offline": false},
+            {"kind": "api", "name": "Leonardo AI", "requires": {"env": ["LEONARDO_API_KEY"]}, "cost_tier": "paid", "quality_tier": "high", "offline": false},
+            {"kind": "api", "name": "OpenAI GPT-Image-1", "requires": {"env": ["OPENAI_API_KEY"]}, "cost_tier": "metered", "quality_tier": "sota", "offline": false},
+            {"kind": "api", "name": "Stability AI", "requires": {"env": ["STABILITY_API_KEY"]}, "cost_tier": "metered", "quality_tier": "high", "offline": false}
+          ]
+        },
+        {
+          "id": "playtest.agent",
+          "intent": "Drive a live game loop or test harness with an agent.",
+          "inputs": ["game:path_or_process", "test_plan?:text"],
+          "outputs": ["playtest_report:path", "telemetry:json"],
+          "skill_search_hints": ["agent playtesting", "game testing", "gymnasium", "headless game"],
+          "providers": [
+            {"kind": "harness-cli", "name": "cli-anything-slay-the-spire-ii", "requires": {"binary": ["cli-anything-sts2"]}, "cost_tier": "free", "quality_tier": "sota", "offline": true, "notes": "Requires Slay the Spire II plus the bridge mod; ask the user if modding is permitted before attempting."},
+            {"kind": "python", "name": "gymnasium envs", "requires": {"package": ["gymnasium"]}, "cost_tier": "free", "quality_tier": "high", "offline": true},
+            {"kind": "harness-cli", "name": "Godot headless + scripted input", "requires": {"binary": ["cli-anything-godot"]}, "cost_tier": "free", "quality_tier": "good", "offline": true, "notes": "Run Godot with --headless and GUT or scripted input."}
+          ]
+        },
+        {
+          "id": "build.package",
+          "intent": "Package a game build/binary for distribution.",
+          "inputs": ["project:path", "target_platform:text", "version:text"],
+          "outputs": ["build:path", "build_manifest:json"],
+          "skill_search_hints": ["game packaging", "export build", "godot export", "itch butler"],
+          "providers": [
+            {"kind": "harness-cli", "name": "cli-anything-godot (export presets)", "requires": {"binary": ["cli-anything-godot"]}, "cost_tier": "free", "quality_tier": "sota", "offline": true, "notes": "Needs Godot export templates installed. Version builds into builds/<version>/ with a manifest."},
+            {"kind": "python", "name": "pyinstaller (pygame/arcade)", "requires": {"package": ["PyInstaller"]}, "cost_tier": "free", "quality_tier": "good", "offline": true},
+            {"kind": "native", "name": "butler (itch packager)", "requires": {"binary": ["butler"]}, "cost_tier": "free", "quality_tier": "high", "offline": true}
+          ]
+        },
+        {
+          "id": "publish.store",
+          "intent": "Upload a build to a game store; always gated behind explicit user confirmation.",
+          "inputs": ["build:path", "store:steam|itch|epic|play|appstore", "credentials:env"],
+          "outputs": ["release_url:text"],
+          "skill_search_hints": ["steam upload", "itch.io publish", "store release", "steamcmd"],
+          "providers": [
+            {"kind": "native", "name": "steamcmd", "requires": {"binary": ["steamcmd"], "env": ["STEAM_USERNAME", "STEAM_PASSWORD"]}, "cost_tier": "paid", "quality_tier": "sota", "offline": false, "notes": "One-time $100 Steamworks fee and an app ID; use a dedicated build account to limit credential risk."},
+            {"kind": "native", "name": "butler (itch.io)", "requires": {"binary": ["butler"], "env": ["ITCH_API_KEY"]}, "cost_tier": "free", "quality_tier": "high", "offline": false},
+            {"kind": "api", "name": "Epic Games Services", "requires": {"env": ["EPIC_DEV_TOKEN"]}, "cost_tier": "paid", "quality_tier": "high", "offline": false},
+            {"kind": "api", "name": "Google Play Developer", "requires": {"env": ["PLAY_CONSOLE_KEY"]}, "cost_tier": "paid", "quality_tier": "high", "offline": false, "notes": "Service account required."},
+            {"kind": "api", "name": "App Store Connect", "requires": {"env": ["APP_STORE_CONNECT_KEY"]}, "cost_tier": "paid", "quality_tier": "high", "offline": false}
+          ]
+        },
+        {
+          "id": "telemetry.ingest",
+          "intent": "Collect gameplay analytics and crash reports.",
+          "inputs": ["app_or_build:path", "events?:json"],
+          "outputs": ["telemetry_dashboard:url", "crash_reports:json"],
+          "skill_search_hints": ["game analytics", "crash reporting", "sentry", "telemetry"],
+          "providers": [
+            {"kind": "public-cli", "name": "sentry", "requires": {"binary": ["sentry-cli"], "env": ["SENTRY_DSN"]}, "cost_tier": "free", "quality_tier": "high", "offline": false, "notes": "Free tier with paid scale; install via `cli-hub install sentry`."},
+            {"kind": "python", "name": "posthog", "requires": {"package": ["posthog"], "env": ["POSTHOG_API_KEY"]}, "cost_tier": "free", "quality_tier": "high", "offline": false, "notes": "Free tier with paid scale."},
+            {"kind": "api", "name": "GameAnalytics", "requires": {"env": ["GAMEANALYTICS_KEY"]}, "cost_tier": "free", "quality_tier": "good", "offline": false},
+            {"kind": "api", "name": "Unity Analytics", "requires": {"env": ["UNITY_PROJECT_TOKEN"]}, "cost_tier": "metered", "quality_tier": "high", "offline": false, "notes": "Unity project token required."},
+            {"kind": "api", "name": "PlayFab", "requires": {"env": ["PLAYFAB_TITLE_KEY"]}, "cost_tier": "metered", "quality_tier": "high", "offline": false}
+          ]
+        }
+      ],
+      "recipes": [
+        {
+          "id": "godot-jam-game",
+          "description": "Minimal end-to-end for a game jam.",
+          "capabilities_used": ["game.engine", "asset.2d", "asset.audio", "build.package", "publish.store"],
+          "notes": "publish.store is optional and always needs explicit user confirmation."
+        },
+        {
+          "id": "agent-bot",
+          "description": "Train / evaluate an agent against an existing game.",
+          "capabilities_used": ["playtest.agent", "telemetry.ingest"]
+        },
+        {
+          "id": "ai-indie-short",
+          "description": "AI-generated art plus a simple engine loop.",
+          "capabilities_used": ["ai.gen-asset", "asset.2d", "game.engine", "asset.audio", "build.package"]
+        },
+        {
+          "id": "steam-release",
+          "description": "Ship to Steam with crash reporting.",
+          "capabilities_used": ["build.package", "publish.store", "telemetry.ingest"]
+        },
+        {
+          "id": "music-driven-game",
+          "description": "Composed score integrated with gameplay.",
+          "capabilities_used": ["asset.notation", "asset.audio", "game.engine"]
+        },
+        {
+          "id": "reality-to-game",
+          "description": "Photogrammetry asset, import, ship.",
+          "capabilities_used": ["asset.3d", "game.engine", "build.package"],
+          "notes": "Photogrammetry reconstruction comes from the 3d-cad (S3) matrix's photogrammetry.reconstruct capability."
+        }
+      ],
+      "known_gaps": [
+        {
+          "capability": "publish.store",
+          "reason": "Steam/itch/console wrappers are native or API only; no harness-level abstraction.",
+          "workaround": "Escalate via the suggest-to-user template with platform-specific credentials; never auto-publish without explicit user confirmation."
+        },
+        {
+          "capability": "game.engine",
+          "reason": "Only Godot has a harness; no Unity/Unreal path.",
+          "workaround": "Start in Godot unless the user explicitly requires Unity/Unreal; for those, fall back to user-driven editor work."
+        },
+        {
+          "capability": "telemetry.ingest",
+          "reason": "Sentry works via the public CLI; no first-party path for GameAnalytics/PlayFab.",
+          "workaround": "Use the sentry public CLI, or API escalation with user-supplied keys."
+        }
+      ],
+      "suggest_to_user_template": "To enable <capability> via <provider>, please set <ENV_VAR>. Cost: <cost_tier>. Quality: <quality_tier>. Reply 'skip' to fall back to <next provider>."
+    },
+    {
+      "name": "image-design",
+      "display_name": "Image & Graphic Design",
+      "version": "1",
+      "schema_version": "2",
+      "description": "Capability-based matrix for image and graphic design: AI image generation, raster/vector editing, UI mockups/wireframes, diagrams, super-resolution upscaling, photo library management, RAW development, and CMS publishing. GIMP/Krita/Inkscape/ComfyUI cover most work offline; cloud APIs escalate quality.",
+      "category": "image",
+      "matrix": "cli-matrix",
+      "matrix_id": "S5",
+      "homepage": "https://github.com/HKUDS/CLI-Anything/blob/main/docs/cli-matrix/cli-matrix-plan.md",
+      "skill_md": "cli-hub-matrix/image-design/SKILL.md",
+      "clis": [
+        "comfyui",
+        "gimp",
+        "krita",
+        "inkscape",
+        "sketch",
+        "drawio",
+        "mermaid"
+      ],
+      "capabilities": [
+        {
+          "id": "visual.generate",
+          "intent": "Produce an image from a text prompt or reference image.",
+          "inputs": ["prompt:text", "ref_image?:path", "size?:px", "seed?:int"],
+          "outputs": ["image:path"],
+          "skill_search_hints": ["text-to-image", "AI image", "image generation", "stable diffusion"],
+          "providers": [
+            {"kind": "harness-cli", "name": "cli-anything-comfyui", "requires": {"binary": ["cli-anything-comfyui"]}, "cost_tier": "free", "quality_tier": "high", "offline": true, "notes": "Needs ComfyUI plus model weights (FLUX/SDXL)."},
+            {"kind": "public-cli", "name": "jimeng", "requires": {"binary": ["dreamina"]}, "cost_tier": "metered", "quality_tier": "high", "offline": false, "notes": "ByteDance Dreamina; install via `cli-hub install jimeng`."},
+            {"kind": "python", "name": "diffusers (SD/SDXL/FLUX)", "requires": {"package": ["diffusers"]}, "cost_tier": "free", "quality_tier": "good", "offline": true, "notes": "Needs model weights and ideally a GPU."},
+            {"kind": "python", "name": "replicate", "requires": {"package": ["replicate"], "env": ["REPLICATE_API_TOKEN"]}, "cost_tier": "metered", "quality_tier": "high", "offline": false},
+            {"kind": "api", "name": "OpenAI GPT-Image-1", "requires": {"env": ["OPENAI_API_KEY"]}, "cost_tier": "metered", "quality_tier": "sota", "offline": false, "notes": "Best for photoreal and text-in-image."},
+            {"kind": "api", "name": "Ideogram", "requires": {"env": ["IDEOGRAM_API_KEY"]}, "cost_tier": "metered", "quality_tier": "sota", "offline": false, "notes": "Strong poster/typography rendering."},
+            {"kind": "api", "name": "Stability AI", "requires": {"env": ["STABILITY_API_KEY"]}, "cost_tier": "metered", "quality_tier": "high", "offline": false},
+            {"kind": "api", "name": "Recraft", "requires": {"env": ["RECRAFT_API_KEY"]}, "cost_tier": "paid", "quality_tier": "sota", "offline": false},
+            {"kind": "api", "name": "Google Imagen / Nano Banana", "requires": {"env": ["GOOGLE_API_KEY"]}, "cost_tier": "metered", "quality_tier": "high", "offline": false},
+            {"kind": "api", "name": "Midjourney (Discord bridge)", "requires": {"env": ["MIDJOURNEY_TOKEN"]}, "cost_tier": "paid", "quality_tier": "sota", "offline": false, "notes": "Discord bridge only; no official API."},
+            {"kind": "api", "name": "Adobe Firefly", "requires": {"env": ["FIREFLY_TOKEN"]}, "cost_tier": "paid", "quality_tier": "high", "offline": false}
+          ]
+        },
+        {
+          "id": "visual.edit.raster",
+          "intent": "Edit raster images: retouch, composite, resize, background removal.",
+          "inputs": ["image:path", "edit_spec:text"],
+          "outputs": ["image:path"],
+          "skill_search_hints": ["raster editing", "photo retouch", "background removal", "compositing"],
+          "providers": [
+            {"kind": "harness-cli", "name": "cli-anything-gimp", "requires": {"binary": ["cli-anything-gimp"]}, "cost_tier": "free", "quality_tier": "sota", "offline": true},
+            {"kind": "harness-cli", "name": "cli-anything-krita", "requires": {"binary": ["cli-anything-krita"]}, "cost_tier": "free", "quality_tier": "sota", "offline": true},
+            {"kind": "python", "name": "Pillow", "requires": {"package": ["PIL"]}, "cost_tier": "free", "quality_tier": "good", "offline": true},
+            {"kind": "python", "name": "opencv-python", "requires": {"package": ["cv2"]}, "cost_tier": "free", "quality_tier": "high", "offline": true},
+            {"kind": "python", "name": "scikit-image", "requires": {"package": ["skimage"]}, "cost_tier": "free", "quality_tier": "high", "offline": true},
+            {"kind": "python", "name": "rembg (background removal)", "requires": {"package": ["rembg"]}, "cost_tier": "free", "quality_tier": "high", "offline": true},
+            {"kind": "api", "name": "remove.bg", "requires": {"env": ["REMOVE_BG_API_KEY"]}, "cost_tier": "metered", "quality_tier": "sota", "offline": false},
+            {"kind": "api", "name": "Adobe Firefly", "requires": {"env": ["FIREFLY_TOKEN"]}, "cost_tier": "paid", "quality_tier": "sota", "offline": false},
+            {"kind": "api", "name": "Cutout.pro", "requires": {"env": ["CUTOUT_PRO_API_KEY"]}, "cost_tier": "metered", "quality_tier": "high", "offline": false}
+          ]
+        },
+        {
+          "id": "visual.edit.vector",
+          "intent": "Create and edit vector graphics (SVG): logos, icons, illustrations.",
+          "inputs": ["svg_or_spec:path_or_text", "edit_spec?:text"],
+          "outputs": ["svg:path"],
+          "skill_search_hints": ["vector editing", "svg", "logo design", "inkscape"],
+          "providers": [
+            {"kind": "harness-cli", "name": "cli-anything-inkscape", "requires": {"binary": ["cli-anything-inkscape"]}, "cost_tier": "free", "quality_tier": "sota", "offline": true},
+            {"kind": "python", "name": "svgwrite", "requires": {"package": ["svgwrite"]}, "cost_tier": "free", "quality_tier": "good", "offline": true},
+            {"kind": "python", "name": "cairosvg", "requires": {"package": ["cairosvg"]}, "cost_tier": "free", "quality_tier": "good", "offline": true, "notes": "Also the batch rasterization path for icon/logo exports."},
+            {"kind": "python", "name": "svgpathtools", "requires": {"package": ["svgpathtools"]}, "cost_tier": "free", "quality_tier": "high", "offline": true},
+            {"kind": "python", "name": "vpype (vector post-processing)", "requires": {"package": ["vpype"]}, "cost_tier": "free", "quality_tier": "high", "offline": true}
+          ]
+        },
+        {
+          "id": "visual.mockup",
+          "intent": "Design UI mockups and wireframes.",
+          "inputs": ["flow_spec:text", "fidelity?:wireframe|hifi"],
+          "outputs": ["mockups:path[]"],
+          "skill_search_hints": ["UI mockup", "wireframe", "figma", "design system"],
+          "providers": [
+            {"kind": "harness-cli", "name": "cli-anything-sketch", "requires": {"binary": ["sketch-cli"]}, "cost_tier": "paid", "quality_tier": "sota", "offline": true, "notes": "Sketch is a paid macOS app."},
+            {"kind": "harness-cli", "name": "cli-anything-drawio", "requires": {"binary": ["cli-anything-drawio"]}, "cost_tier": "free", "quality_tier": "high", "offline": true},
+            {"kind": "native", "name": "drawio-desktop", "requires": {"binary": ["drawio"]}, "cost_tier": "free", "quality_tier": "high", "offline": true},
+            {"kind": "native", "name": "penpot", "requires": {"binary": ["penpot"]}, "cost_tier": "free", "quality_tier": "high", "offline": true, "notes": "Self-hostable."},
+            {"kind": "api", "name": "Figma API", "requires": {"env": ["FIGMA_TOKEN"]}, "cost_tier": "free", "quality_tier": "sota", "offline": false, "notes": "Free tier works for most users; design-system aware."},
+            {"kind": "api", "name": "Canva API", "requires": {"env": ["CANVA_API_KEY"]}, "cost_tier": "paid", "quality_tier": "high", "offline": false},
+            {"kind": "api", "name": "Penpot API", "requires": {"env": ["PENPOT_TOKEN"]}, "cost_tier": "free", "quality_tier": "high", "offline": false}
+          ]
+        },
+        {
+          "id": "visual.diagram",
+          "intent": "Create diagrams and flowcharts.",
+          "inputs": ["spec:text_or_path", "format?:svg|png|drawio|mermaid"],
+          "outputs": ["diagram:path"],
+          "skill_search_hints": ["diagram", "flowchart", "mermaid", "graphviz"],
+          "providers": [
+            {"kind": "harness-cli", "name": "cli-anything-drawio", "requires": {"binary": ["cli-anything-drawio"]}, "cost_tier": "free", "quality_tier": "sota", "offline": true},
+            {"kind": "harness-cli", "name": "cli-anything-mermaid", "requires": {"binary": ["cli-anything-mermaid"]}, "cost_tier": "free", "quality_tier": "high", "offline": true},
+            {"kind": "native", "name": "graphviz (dot)", "requires": {"binary": ["dot"]}, "cost_tier": "free", "quality_tier": "high", "offline": true},
+            {"kind": "native", "name": "plantuml", "requires": {"binary": ["plantuml"]}, "cost_tier": "free", "quality_tier": "high", "offline": true, "notes": "Needs Java."}
+          ]
+        },
+        {
+          "id": "visual.upscale",
+          "intent": "Upscale images and restore faces with super-resolution.",
+          "inputs": ["image:path", "scale?:2x|4x"],
+          "outputs": ["image:path"],
+          "skill_search_hints": ["super resolution", "upscale", "esrgan", "face restoration"],
+          "providers": [
+            {"kind": "python", "name": "Real-ESRGAN", "requires": {"package": ["realesrgan"]}, "cost_tier": "free", "quality_tier": "high", "offline": true, "notes": "Needs model weights."},
+            {"kind": "python", "name": "GFPGAN (faces)", "requires": {"package": ["gfpgan"]}, "cost_tier": "free", "quality_tier": "high", "offline": true, "notes": "Face restoration; needs model weights."},
+            {"kind": "native", "name": "upscayl", "requires": {"binary": ["upscayl"]}, "cost_tier": "free", "quality_tier": "high", "offline": true},
+            {"kind": "api", "name": "Topaz", "requires": {"env": ["TOPAZ_API_KEY"]}, "cost_tier": "paid", "quality_tier": "sota", "offline": false},
+            {"kind": "python", "name": "Replicate upscalers", "requires": {"package": ["replicate"], "env": ["REPLICATE_API_TOKEN"]}, "cost_tier": "metered", "quality_tier": "high", "offline": false}
+          ]
+        },
+        {
+          "id": "photo.library",
+          "intent": "Organize, tag, and query a photo library (DAM).",
+          "inputs": ["photos:path[]", "operation?:tag|search|organize"],
+          "outputs": ["library_index:path"],
+          "skill_search_hints": ["photo organization", "DAM", "exif", "photo library"],
+          "providers": [
+            {"kind": "native", "name": "exiftool + Pillow", "requires": {"binary": ["exiftool"], "package": ["PIL"]}, "cost_tier": "free", "quality_tier": "high", "offline": true, "notes": "Handles EXIF/ICC metadata; preserve color profiles when moving between tools."},
+            {"kind": "native", "name": "digikam", "requires": {"binary": ["digikam"]}, "cost_tier": "free", "quality_tier": "high", "offline": true},
+            {"kind": "native", "name": "photoprism", "requires": {"binary": ["photoprism"]}, "cost_tier": "free", "quality_tier": "high", "offline": true, "notes": "Self-hosted."},
+            {"kind": "api", "name": "Google Photos API", "requires": {"env": ["GOOGLE_APPLICATION_CREDENTIALS"]}, "cost_tier": "free", "quality_tier": "high", "offline": false, "notes": "OAuth credentials required; free tier."}
+          ]
+        },
+        {
+          "id": "photo.develop",
+          "intent": "Process RAW photos into developed images.",
+          "inputs": ["raw_files:path[]", "develop_profile?:path"],
+          "outputs": ["images:path[]"],
+          "skill_search_hints": ["RAW processing", "darktable", "rawtherapee", "photo develop"],
+          "providers": [
+            {"kind": "python", "name": "rawpy", "requires": {"package": ["rawpy"]}, "cost_tier": "free", "quality_tier": "high", "offline": true, "notes": "Convert to sRGB at the boundary when handing off to Pillow."},
+            {"kind": "native", "name": "darktable-cli", "requires": {"binary": ["darktable-cli"]}, "cost_tier": "free", "quality_tier": "sota", "offline": true},
+            {"kind": "native", "name": "rawtherapee-cli", "requires": {"binary": ["rawtherapee-cli"]}, "cost_tier": "free", "quality_tier": "sota", "offline": true},
+            {"kind": "api", "name": "Adobe Lightroom API", "requires": {"env": ["ADOBE_CLIENT_ID"]}, "cost_tier": "paid", "quality_tier": "sota", "offline": false, "notes": "Adobe credentials required."}
+          ]
+        },
+        {
+          "id": "publish.cms",
+          "intent": "Publish images or articles to a CMS or static site.",
+          "inputs": ["assets:path[]", "target:cms_or_site"],
+          "outputs": ["published_url:text"],
+          "skill_search_hints": ["CMS publishing", "contentful", "static site", "image hosting"],
+          "providers": [
+            {"kind": "public-cli", "name": "contentful", "requires": {"binary": ["contentful"]}, "cost_tier": "metered", "quality_tier": "high", "offline": false, "notes": "Needs a Contentful space token; install via `cli-hub install contentful`."},
+            {"kind": "public-cli", "name": "sanity", "requires": {"binary": ["sanity"]}, "cost_tier": "metered", "quality_tier": "high", "offline": false, "notes": "Needs a Sanity project token; install via `cli-hub install sanity`."},
+            {"kind": "native", "name": "hugo / mkdocs", "requires": {"binary": ["hugo"]}, "cost_tier": "free", "quality_tier": "high", "offline": true, "notes": "Static-site path (hugo checked here); mkdocs is the Python equivalent."},
+            {"kind": "api", "name": "WordPress REST", "requires": {"env": ["WORDPRESS_TOKEN"]}, "cost_tier": "free", "quality_tier": "high", "offline": false, "notes": "Application password/token for the target site."}
+          ]
+        }
+      ],
+      "recipes": [
+        {
+          "id": "social-card",
+          "description": "Generate and compose a social sharing image.",
+          "capabilities_used": ["visual.generate", "visual.edit.raster", "publish.cms"]
+        },
+        {
+          "id": "logo-set",
+          "description": "Design a logo plus size variants with batch export.",
+          "capabilities_used": ["visual.edit.vector", "visual.edit.raster"],
+          "notes": "Vector-first; rasterize last for the size variants."
+        },
+        {
+          "id": "ui-wireframe",
+          "description": "Mock up a UI flow.",
+          "capabilities_used": ["visual.mockup", "visual.edit.vector"],
+          "notes": "visual.edit.vector polish is optional."
+        },
+        {
+          "id": "photo-batch",
+          "description": "RAW ingest, develop, edit, library, publish.",
+          "capabilities_used": ["photo.develop", "visual.edit.raster", "photo.library", "publish.cms"]
+        },
+        {
+          "id": "icon-pack",
+          "description": "Systematic icon production with batch rasterization.",
+          "capabilities_used": ["visual.edit.vector"],
+          "notes": "Batch rasterize via cairosvg."
+        },
+        {
+          "id": "thumbnail-set",
+          "description": "Thumbnails for a video/article series with batch variant export.",
+          "capabilities_used": ["visual.generate", "visual.edit.raster"]
+        },
+        {
+          "id": "ai-concept-art",
+          "description": "Generate, upscale, touch up.",
+          "capabilities_used": ["visual.generate", "visual.upscale", "visual.edit.raster"]
+        }
+      ],
+      "known_gaps": [
+        {
+          "capability": "visual.mockup",
+          "reason": "Figma is the headline cross-scenario gap (S5 and S7); API escalation only, no native harness.",
+          "workaround": "Use the Figma API with FIGMA_TOKEN, or fall back to cli-anything-sketch / drawio wireframes."
+        },
+        {
+          "capability": "photo.library",
+          "reason": "Strong native CLIs (exiftool, digikam, photoprism) and equally strong photo.develop natives, but no harness.",
+          "workaround": "Drive the native CLIs directly."
+        },
+        {
+          "capability": "visual.generate",
+          "reason": "Midjourney has no clean API; Discord bridge only.",
+          "workaround": "Prefer GPT-Image-1 / Ideogram / Stability / Recraft when credentialed, or local ComfyUI / diffusers."
+        }
+      ],
+      "suggest_to_user_template": "To enable <capability> via <provider>, please set <ENV_VAR>. Cost: <cost_tier>. Quality: <quality_tier>. Reply 'skip' to fall back to <next provider>."
+    }
+  ]
+}
diff --git a/public_registry.json b/public_registry.json
index 173c37ac0..9abbc4ae5 100644
--- a/public_registry.json
+++ b/public_registry.json
@@ -2,7 +2,7 @@
   "meta": {
     "repo": "https://github.com/HKUDS/CLI-Anything",
     "description": "Public CLI Registry — Third-party and official CLIs managed by CLI-Hub across npm, bundled, brew, and other install methods",
-    "updated": "2026-06-03"
+    "updated": "2026-06-19"
   },
   "clis": [
     {
@@ -49,6 +49,25 @@
         }
       ]
     },
+    {
+      "name": "pieces",
+      "display_name": "Pieces OS CLI",
+      "version": "1.0.0",
+      "description": "Agent-native CLI for Pieces OS — persistent long-term memory for developers. Search, create, and manage memory assets, snippets, and models via Pieces OS REST API.",
+      "category": "productivity",
+      "requires": "Pieces OS running locally (http://localhost:39300)",
+      "homepage": "https://pieces.app",
+      "source_url": "https://github.com/goddardoven110907/cli-anything-pieces",
+      "install_cmd": "pip install git+https://github.com/goddardoven110907/cli-anything-pieces.git",
+      "entry_point": "cli-anything-pieces",
+      "skill_md": "https://github.com/goddardoven110907/cli-anything-pieces/blob/master/README.md",
+      "contributors": [
+        {
+          "name": "goddardoven110907",
+          "url": "https://github.com/goddardoven110907"
+        }
+      ]
+    },
     {
       "name": "wecom",
       "display_name": "WeCom CLI",
diff --git a/skills/cli-hub-meta-skill/SKILL.md b/skills/cli-hub-meta-skill/SKILL.md
index 148f9f83e..30b23a290 100644
--- a/skills/cli-hub-meta-skill/SKILL.md
+++ b/skills/cli-hub-meta-skill/SKILL.md
@@ -29,6 +29,34 @@ cli-hub install gimp
 cli-hub info gimp
 ```
 
+## Workflow Matrices
+
+A single CLI is one tool. A **matrix** is a whole workflow packaged as
+capabilities × providers — e.g. `video-creation` maps intents like
+`text.transcribe` or `visual.generate` to harness CLIs, public CLIs, Python
+libraries, native binaries, and cloud APIs. Reach for a matrix when a task spans
+several tools (produce a video, design an image, build a game).
+
+Standard agent sequence — **preflight before you install**:
+
+```bash
+cli-hub matrix list                                   # browse all matrices
+cli-hub can "transcribe audio"                        # find the capability across matrices
+cli-hub matrix search "video subtitle"                # search; shows the matched capability
+cli-hub matrix preflight video-creation --json        # what's usable here? (exit 3 = gaps)
+cli-hub matrix preflight video-creation -c text.transcribe --fix-hints   # one capability + install hints
+cli-hub matrix install video-creation --capability text.transcribe       # install ONLY what the task needs
+# After install, the matrix SKILL.md renders locally with provider-selection rules — read it.
+```
+
+Scope every install — do not bulk-install a 14-CLI matrix for a one-capability
+task. Use `--capability <id>`, `--recipe <id>`, or `--only a,b`, and
+`--dry-run` to preview the plan with zero side effects. `--json` is available on
+every matrix subcommand; exit codes are `0` ok · `3` partial/gaps · `1` failure ·
+`2` usage error. Retry failures with `cli-hub matrix install <name> --resume`,
+and audit an install with `cli-hub matrix doctor <name>`.
+
+
 ## Live Catalog
 
 **URL**: [`https://reeceyang.sgp1.cdn.digitaloceanspaces.com/SKILL.md`](https://reeceyang.sgp1.cdn.digitaloceanspaces.com/SKILL.md)