Skip to content

AgentiaPT/vela-slides / skills/vela-slides

vela-slides

Unverified

Create presentation decks using the Vela engine. Compact DSL format — never verbose JSON. Also loads, extracts, and edits existing decks.

FileKindSize
SKILL.mdskill md6.5 KB
app/vela.jsxother2.3 MB
examples/vela-demo.jsonconfig87.0 KB
references/block-schema.mdmarkdown25.6 KB
references/design-patterns.mdmarkdown20.5 KB
references/formats.mdmarkdown4.6 KB
references/themes.mdmarkdown4.5 KB
scripts/_safe_term.pyscript10.2 KB
scripts/assemble.pyscript9.3 KB
scripts/validate.pyscript16.7 KB
scripts/vela.pyscript115.0 KB

scripts/vela.py

View on GitHub
#!/usr/bin/env python3
# © 2025-present Rui Quintino. Vela Slides — licensed under ELv2. See LICENSE.
"""vela — CLI for Vela slide decks. Agent-friendly by design.

Usage:
  vela <resource> <action> [args...]
  vela --capabilities          Machine-readable command index
  vela --help                  Human-readable help

Resources:
  deck     Deck-level operations (list, validate, extract, split, dump, stats, find, extract-text, patch-text, replace-text, assemble, ship, compact, expand, turbo)
  slide    Slide-level operations (view, edit, remove, move, duplicate, insert, remove-block)

Exit codes:
  0  Success
  1  General failure
  2  Usage error (bad arguments)
  3  Resource not found (slide/block/file)
  4  Validation failure
  5  Conflict (already exists)
"""

import json, sys, os, subprocess, copy, shutil

# ── Terminal-output funnel ──────────────────────────────────────────────
# COMPLETE MEDIATION: every human-readable byte this script writes leaves
# through emit(), which applies the canonical encoder in _safe_term.py (read
# that module's header for the threat and the policy). Encoding at the SINK
# rather than at each call site is what makes the mediation total: a new print
# site cannot be added without either routing through emit() or failing the
# lint gate (tools/vela-dev/scripts/lint.py, check_terminal_sink_gate).
#
# NOT applied to file writes, and never to deck data on its way back into a
# deck — `deck extract-text` → `patch-text` is a round-trip edit that must stay
# lossless, so the encoder belongs on the display path only.
#
# This sink also covers the RELAY hop: this script re-prints the captured
# stdout of validate.py / assemble.py, so deck text can reach the terminal one
# process later than it was read. Encoding at the sink catches that hop;
# encoding where the value is read does not.
sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
from _safe_term import term_text, term_label, Untrusted  # noqa: E402

_write = print  # the only builtin-print reference; everything else uses emit()


def emit(*parts, **kwargs):
    """Write to the terminal with deck-supplied control sequences neutralized."""
    _write(*(term_text(p) if isinstance(p, str) else p for p in parts), **kwargs)

# ── Paths ──────────────────────────────────────────────────────────────
SKILL_DIR = os.path.dirname(os.path.realpath(__file__))
SCRIPTS_DIR = SKILL_DIR
SKILL_ROOT = os.path.dirname(SKILL_DIR)
VALIDATE_PY = os.path.join(SCRIPTS_DIR, "validate.py")
ASSEMBLE_PY = os.path.join(SCRIPTS_DIR, "assemble.py")
OUTPUT_DIR = os.environ.get("VELA_OUTPUT_DIR", os.getcwd())

# ── Exit codes ─────────────────────────────────────────────────────────
EXIT_OK = 0
EXIT_FAIL = 1
EXIT_USAGE = 2
EXIT_NOT_FOUND = 3
EXIT_VALIDATION = 4
EXIT_CONFLICT = 5

# ── Helpers ────────────────────────────────────────────────────────────
_json_mode = False

def _safe_resolve(file_path, label="file"):
    """Resolve a file path and reject directory traversal / symlink escapes."""
    resolved = os.path.realpath(file_path)
    cwd = os.path.realpath(os.getcwd())
    if not resolved.startswith(cwd + os.sep) and resolved != cwd:
        _err(EXIT_USAGE, f"Path traversal blocked for {label}: {file_path}")
    return resolved

def _extract_output_flag(args):
    """Extract --output <path> from args. Returns (output_path, remaining_args)."""
    output_path = None
    remaining = []
    i = 0
    while i < len(args):
        if args[i] == '--output' and i + 1 < len(args):
            output_path = args[i + 1]
            i += 2
        else:
            remaining.append(args[i])
            i += 1
    return output_path, remaining

def _is_json():
    return _json_mode or "--json" in sys.argv

def _out(data):
    """Print structured output to stdout.

    ensure_ascii=True is a security setting here, not a style choice. This is
    the machine/agent path, and `json.dumps` only escapes C0 — DEL, the C1 range
    (0x9B is the 8-bit CSI introducer), bidi overrides and zero-width
    characters all survive `ensure_ascii=False` as raw bytes. Escaping to \\uXXXX
    makes the payload inert for every downstream reader while staying a lossless
    round-trip for any JSON parser.
    """
    if isinstance(data, (dict, list)):
        emit(json.dumps(data, ensure_ascii=True, indent=2))
    else:
        emit(data)

def _err(code, message, suggestions=None, retryable=False):
    """Print error and exit with semantic code."""
    if _is_json():
        err = {"success": False, "error": {"code": code, "message": message, "retryable": retryable}}
        if suggestions:
            err["error"]["suggestions"] = suggestions
        emit(json.dumps(err, ensure_ascii=True, indent=2))  # see _out: machine path
    else:
        emit(f"❌ {message}", file=sys.stderr)
        if suggestions:
            for s in suggestions:
                emit(f"   💡 {s}", file=sys.stderr)
    sys.exit(code)

def _ok(data, message=None):
    """Print success output."""
    if _is_json():
        out = {"success": True}
        if isinstance(data, dict):
            out.update(data)
        else:
            out["data"] = data
        if message:
            out["message"] = message
        _out(out)
    else:
        if message:
            emit(f"✅ {message}", file=sys.stderr)
        if data and not isinstance(data, bool):
            _out(data)
    sys.exit(EXIT_OK)

def _load_deck(path):
    if not os.path.exists(path):
        _err(EXIT_NOT_FOUND, f"File not found: {path}",
             suggestions=["Check the file path", "Run: ls /home/claude/*.vela"])
    try:
        with open(path, encoding="utf-8") as f:
            return json.load(f)
    except json.JSONDecodeError as e:
        _err(EXIT_FAIL, f"Invalid JSON: {e}",
             suggestions=["Check JSON syntax", "Run: python3 -m json.tool " + path])

def _save_deck(deck, path):
    with open(path, 'w', encoding="utf-8") as f:
        json.dump(deck, f, ensure_ascii=False, indent=2)

def _all_slides(deck):
    """Yield (global_idx_1based, slide, item) for each slide."""
    idx = 0
    for lane in deck.get("lanes", []):
        for item in lane.get("items", []):
            for si, slide in enumerate(item.get("slides", [])):
                idx += 1
                yield idx, slide, item, si

def _get_slide(deck, num):
    """Get (slides_list, slide_index, item) for 1-indexed slide number."""
    for idx, slide, item, si in _all_slides(deck):
        if idx == num:
            return item["slides"], si, item
    return None, None, None

def _is_dark(slide):
    bg = slide.get("bg", "#0f172a")
    if not bg.startswith("#") or len(bg) < 7:
        return True
    r, g, b = int(bg[1:3], 16), int(bg[3:5], 16), int(bg[5:7], 16)
    return (r * 0.299 + g * 0.587 + b * 0.114) < 128


# ── COMPACT FORMAT ─────────────────────────────────────────────────────
# Compact JSON reduces LLM output tokens by ~61% via:
#   1. Flat slides array (no lanes/items nesting)
#   2. Short key names (_=type, x=text, s=size, etc.)
#   3. Theme presets (T.d/l/a → slides use "t":"d")
#   4. Spacer shorthand (8 instead of {"type":"spacer","h":8})
#
# Detection: compact decks have "S" key (slides array), full decks have "lanes".
# expand_deck() converts compact→full, compact_deck() converts full→compact.

# Block-level key map: short → full
_BK = {
    "_": "type", "x": "text", "s": "size", "c": "color",
    "i": "icon", "b": "bg", "ic": "iconColor", "ib": "iconBg",
    "I": "items", "B": "blocks", "nm": "name",
    "lb": "label", "v": "variant", "w": "weight",
    "g": "gap", "H": "headers", "R": "rows",
    "sl": "sublabel", "slc": "sublabelColor",
    "ac": "arrowColor", "lc": "labelColor",
    "ts": "titleSize", "xs": "textSize",
    "hb": "headerBg", "hc": "headerColor", "cc": "cellColor",
    "bc": "borderColor", "str": "striped", "lo": "loop",
    "lnc": "lineColor", "nc": "numberColor", "tc": "titleColor",
    "xc": "textColor", "dc": "dotColor",
    "cir": "circle", "dir": "direction",
    "dl": "dividerLabel", "cl": "centerLabel", "csub": "centerSub",
    "Q": "quadrants", "xL": "xLeft", "xR": "xRight",
    "yT": "yTop", "yB": "yBottom", "sL": "showLabels",
    "brd": "bordered", "cpt": "compact", "hl": "highlight",
    "dr": "drop", "hd": "hideDivider", "sI": "showIcons",
    "val": "value",
    "cp": "copy",
    "rv": "reveal"
}
_BK_REV = {v: k for k, v in _BK.items()}

# Slide-level key map: short → full
_SK = {"n": "title", "d": "duration", "B": "blocks", "p": "padding", "sN": "studyNotes"}
_SK_REV = {v: k for k, v in _SK.items()}

# Theme preset key map: short → full slide property
_TK = {"b": "bg", "c": "color", "a": "accent", "p": "padding"}
_TK_REV = {v: k for k, v in _TK.items()}

# Slide properties that come from theme (omit when compacting if they match)
_THEME_PROPS = ["bg", "color", "accent", "padding"]


def _is_compact(deck):
    """Detect compact format."""
    return ("S" in deck or "G" in deck) and "lanes" not in deck


def _expand_keys(obj, keymap):
    """Recursively expand short keys in a dict using keymap."""
    if isinstance(obj, dict):
        result = {}
        for k, v in obj.items():
            full_k = keymap.get(k, k)
            # Recurse into items/blocks arrays but NOT into style objects
            if full_k in ("items", "blocks") and isinstance(v, list):
                result[full_k] = [_expand_block(item) for item in v]
            elif isinstance(v, dict) and full_k != "style":
                result[full_k] = _expand_keys(v, keymap)
            elif isinstance(v, list) and full_k not in ("rows", "headers"):
                result[full_k] = [_expand_keys(item, keymap) if isinstance(item, dict) else item for item in v]
            else:
                result[full_k] = v
        return result
    return obj


def _expand_block(block):
    """Expand a single block from compact form."""
    # Spacer shorthand: int → {"type": "spacer", "h": N}
    if isinstance(block, (int, float)):
        return {"type": "spacer", "h": int(block)}
    if isinstance(block, dict):
        return _expand_keys(block, _BK)
    return block


def _expand_slide(slide, themes):
    """Expand a compact slide: resolve theme, expand keys, expand blocks."""
    # Expand slide-level keys
    expanded = {}
    theme_name = None
    for k, v in slide.items():
        full_k = _SK.get(k, k)
        # Handle blocks array (LLM may write "B" or "blocks")
        if full_k == "blocks" and isinstance(v, list):
            expanded["blocks"] = [_expand_block(b) for b in v]
        elif k == "blocks" and isinstance(v, list) and "blocks" not in expanded:
            expanded["blocks"] = [_expand_block(b) for b in v]
        elif k == "t":
            theme_name = v  # consumed, not passed through
        else:
            expanded[full_k] = v

    # Apply theme defaults (only for props not already in slide)
    if theme_name and theme_name in themes:
        theme = themes[theme_name]
        for tk, tv in theme.items():
            full_prop = _TK.get(tk, tk)
            if full_prop not in expanded:
                expanded[full_prop] = tv

    # Expand blocks inside L and R arrays (cols layout)
    for col_key in ("L", "R"):
        if col_key in expanded and isinstance(expanded[col_key], list):
            expanded[col_key] = [_expand_block(b) for b in expanded[col_key]]

    return expanded


def expand_deck(compact):
    """Convert compact deck format to full Vela JSON."""
    if not _is_compact(compact):
        return copy.deepcopy(compact)  # Already full format

    # Resolve color palette aliases ($A→#3B82F6, etc.)
    if "C" in compact:
        raw_palette = compact.pop("C")

        # Normalize palette: must be flat {str: str}. Skip malformed entries.
        palette = {}
        if isinstance(raw_palette, dict):
            for k, v in raw_palette.items():
                if isinstance(k, str) and isinstance(v, str) and k.startswith("$"):
                    palette[k] = v
                elif isinstance(v, dict):
                    # LLM wrote nested palette like {"palette":{"bg":"#..."}} — skip
                    pass

        if palette:
            # Walk the JSON tree and replace $aliases in string values.
            # Skip known text-content keys to avoid corrupting prose.
            _TEXT_KEYS = frozenset({"n", "x", "text", "title", "label", "lb", "sublabel",
                                    "author", "loopLabel", "gateLabel", "caption",
                                    "annotation", "date", "markup", "deckTitle",
                                    # studyNotes (offline student content) prose fields — preserve literal hex codes
                                    "diagram", "questions", "glossary", "definition"})
            # Sort longest alias first so $AB is replaced before $A
            _sorted = sorted(palette.items(), key=lambda x: -len(x[0]))

            def _resolve(obj, skip=False):
                if isinstance(obj, str) and not skip:
                    for alias, color in _sorted:
                        obj = obj.replace(alias, color)
                    return obj
                if isinstance(obj, dict):
                    return {k: _resolve(v, skip=(k in _TEXT_KEYS)) for k, v in obj.items()}
                if isinstance(obj, list):
                    return [_resolve(v, skip) for v in obj]
                return obj

            compact = _resolve(compact)

    # Resolve theme presets
    raw_themes = compact.get("T", {})
    themes = {}
    for name, preset in raw_themes.items():
        themes[name] = dict(preset)  # shallow copy

    # Build full deck with lanes structure
    title = compact.get("n", compact.get("deckTitle", "Untitled"))

    # Handle grouped format "G" or flat "S"
    groups = compact.get("G", None)
    if groups and isinstance(groups, list):
        # Grouped: G=[{"g":"Section Title","S":[slides]}, ...]
        items = []
        for group in groups:
            group_title = group.get("g", group.get("title", "Section"))
            group_slides = group.get("S", group.get("slides", []))
            expanded = [_expand_slide(s, themes) for s in group_slides]
            items.append({
                "title": group_title,
                "status": "done",
                "importance": "must",
                "slides": expanded
            })
    else:
        # Flat: S=[slides] — group into single item
        slides = compact.get("S", [])
        expanded_slides = [_expand_slide(s, themes) for s in slides]
        items = [{
            "title": title,
            "status": "done",
            "importance": "must",
            "slides": expanded_slides
        }]

    result = {
        "deckTitle": title,
        "lanes": [{"title": "Main", "items": items}]
    }

    # Fix bare hex colors missing # prefix (common LLM output issue)
    import re
    raw = json.dumps(result, ensure_ascii=False)
    # Match color fields with 6-char hex missing #
    raw = re.sub(
        r'("(?:bg|color|accent|headerBg|headerColor|cellColor|borderColor|arrowColor|lineColor|dotColor|numberColor|iconColor|iconBg|border|c|b|a|ic|ib)":\s*")([0-9A-Fa-f]{6})"',
        r'\1#\2"', raw
    )
    result = json.loads(raw)

    return result


def _compact_keys(obj, keymap_rev):
    """Recursively shorten keys in a dict."""
    if isinstance(obj, dict):
        result = {}
        for k, v in obj.items():
            short_k = keymap_rev.get(k, k)
            if k in ("items", "blocks") and isinstance(v, list):
                result[short_k] = [_compact_block(item) for item in v]
            elif isinstance(v, dict) and k != "style":
                result[short_k] = _compact_keys(v, keymap_rev)
            elif isinstance(v, list) and k not in ("rows", "headers"):
                result[short_k] = [_compact_keys(item, keymap_rev) if isinstance(item, dict) else item for item in v]
            else:
                result[short_k] = v
        return result
    return obj


def _compact_block(block):
    """Compact a single block."""
    if isinstance(block, dict):
        # Spacer → int
        if block.get("type") == "spacer" and set(block.keys()) <= {"type", "h"}:
            return block["h"]
        return _compact_keys(block, _BK_REV)
    return block


def compact_deck(full):
    """Convert full Vela JSON to compact format."""
    if _is_compact(full):
        return copy.deepcopy(full)  # Already compact

    # Collect all slides and detect theme groups
    slides = []
    for lane in full.get("lanes", []):
        for item in lane.get("items", []):
            for s in item.get("slides", []):
                slides.append(s)

    # Auto-detect themes by grouping slides with identical bg/color/accent/padding
    theme_groups = {}
    for s in slides:
        key = tuple(s.get(p, "") for p in _THEME_PROPS)
        if key not in theme_groups:
            theme_groups[key] = []
        theme_groups[key].append(s)

    # Assign theme names: d (dark), l (light), a (alt), b, c, ... for extras
    themes = {}
    theme_for_key = {}
    names = iter("dlabcefghijkm")
    for key in sorted(theme_groups.keys(), key=lambda k: -len(theme_groups[k])):
        bg = key[0]
        if bg and _is_dark({"bg": bg}):
            name = "d" if "d" not in themes else next(names)
        else:
            name = "l" if "l" not in themes else ("a" if "a" not in themes else next(names))
        while name in themes:
            name = next(names)
        themes[name] = {_TK_REV.get(p, p): v for p, v in zip(_THEME_PROPS, key) if v}
        theme_for_key[key] = name

    # Compact each slide
    compact_slides = []
    for s in slides:
        key = tuple(s.get(p, "") for p in _THEME_PROPS)
        theme_name = theme_for_key.get(key, "d")

        cs = {"t": theme_name}
        for k, v in s.items():
            if k in _THEME_PROPS:
                continue  # Omit — comes from theme
            if k == "blocks":
                cs[_SK_REV.get(k, k)] = [_compact_block(b) for b in v]
            elif k == "L" and isinstance(v, list):
                cs["L"] = [_compact_block(b) for b in v]
            elif k == "R" and isinstance(v, list):
                cs["R"] = [_compact_block(b) for b in v]
            elif k in _SK_REV:
                cs[_SK_REV[k]] = v
            else:
                cs[k] = v
        compact_slides.append(cs)

    result = {
        "n": full.get("deckTitle", "Untitled"),
        "T": themes,
        "S": compact_slides
    }

    # Preserve studyNotes verbatim across the palette-aliasing step.
    # The blind string-replace below would otherwise mangle literal hex codes
    # ("#3b82f6") that happen to appear inside prose, SVG diagrams, or glossary
    # definitions. Extract them now, restore after the JSON round-trip.
    _preserved_sn = []
    for _ci, _cs in enumerate(compact_slides):
        if isinstance(_cs, dict) and _cs.get("sN") is not None:
            _preserved_sn.append((_ci, _cs["sN"]))
            _cs["sN"] = None  # placeholder — will be restored verbatim below

    # Color palette: find repeated colors in the JSON, alias as $A, $B, ...
    raw = json.dumps(result, ensure_ascii=False, separators=(',', ':'))
    import re as _re
    color_counts = {}
    for m in _re.findall(r'#[a-fA-F0-9]{6,8}', raw):
        color_counts[m] = color_counts.get(m, 0) + 1
    for m in _re.findall(r'rgba\([^)]+\)', raw):
        color_counts[m] = color_counts.get(m, 0) + 1

    # Only alias colors that appear 2+ times (net savings)
    repeated = sorted(
        [(c, n) for c, n in color_counts.items() if n >= 2],
        key=lambda x: -x[1]
    )

    if repeated:
        alpha = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijkl"
        cmap = {}
        for i, (color, _count) in enumerate(repeated):
            if i >= len(alpha):
                break
            alias = "$" + alpha[i]
            raw = raw.replace(color, alias)
            cmap[alias] = color
        result = json.loads(raw)
        result["C"] = cmap

    # Restore preserved studyNotes verbatim (bypassing palette aliasing)
    if _preserved_sn and isinstance(result.get("S"), list):
        for _ci, _sn in _preserved_sn:
            if 0 <= _ci < len(result["S"]) and isinstance(result["S"][_ci], dict):
                result["S"][_ci]["sN"] = _sn

    return result


# ── TURBO FORMAT ───────────────────────────────────────────────────────
# Positional arrays + color palette. ~44% token savings.
# NOT for LLM generation — for storage, cache, and inter-LLM context.
#
# Detection: top-level is a JSON array (not object).
# Structure: [deckTitle, lanes, colorPalette]
# Blocks: [type_id, ...positional values]
#
# Type IDs: 0=badge, 1=spacer, 2=heading, 3=text, 4=grid, 5=icon,
#           6=callout, 7=icon-row, 8=code, 9=table, 10=flow,
#           11=steps, 12=tag-group, 13=divider, 14=comparison,
#           15=funnel, 16=cycle, 17=number-row, 18=matrix,
#           19=checklist, 99=passthrough

_BLOCK_TYPE_IDS = {
    "badge": 0, "spacer": 1, "heading": 2, "text": 3, "grid": 4,
    "icon": 5, "callout": 6, "icon-row": 7, "code": 8, "table": 9,
    "flow": 10, "steps": 11, "tag-group": 12, "divider": 13,
    "comparison": 14, "funnel": 15, "cycle": 16, "number-row": 17,
    "matrix": 18, "checklist": 19
}
_BLOCK_ID_TYPES = {v: k for k, v in _BLOCK_TYPE_IDS.items()}


def _is_turbo(data):
    """Detect turbo format: top-level is a list."""
    return isinstance(data, list)


def _build_palette(deck):
    """Extract all unique color values from deck into an ordered palette."""
    colors = []
    seen = set()
    raw = json.dumps(deck, ensure_ascii=False)
    # Hex colors
    for m in __import__('re').findall(r'#[a-fA-F0-9]{6,8}', raw):
        if m not in seen:
            colors.append(m)
            seen.add(m)
    # rgba colors
    for m in __import__('re').findall(r'rgba\([^)]+\)', raw):
        if m not in seen:
            colors.append(m)
            seen.add(m)
    return colors


def _ci(palette, val):
    """Color index: return palette index or -1."""
    if not val or val == "":
        return -1
    try:
        return palette.index(val)
    except ValueError:
        return -1


def _turbo_encode_block(block, palette):
    """Encode a single block to positional array."""
    t = block.get("type", "")
    tid = _BLOCK_TYPE_IDS.get(t, 99)

    if t == "spacer":
        return [1, block.get("h", 0)]
    if t == "badge":
        return [0, block.get("text", ""), block.get("icon", ""),
                _ci(palette, block.get("bg", "")), _ci(palette, block.get("color", ""))]
    if t == "heading":
        return [2, block.get("text", ""), block.get("size", ""),
                block.get("weight", 0), _ci(palette, block.get("color", "")),
                block.get("icon", ""), block.get("iconColor", ""),
                block.get("align", "")]
    if t == "text":
        return [3, block.get("text", ""), block.get("size", ""),
                _ci(palette, block.get("color", "")),
                block.get("align", "")]
    if t == "icon":
        return [5, block.get("name", ""), block.get("size", ""),
                _ci(palette, block.get("color", "")),
                1 if block.get("circle") else 0,
                _ci(palette, block.get("bg", ""))]
    if t == "code":
        return [8, block.get("text", ""), block.get("label", ""),
                block.get("size", ""), _ci(palette, block.get("bg", "")),
                _ci(palette, block.get("color", ""))]
    if t == "callout":
        return [6, block.get("text", ""), block.get("icon", ""),
                _ci(palette, block.get("bg", "")),
                _ci(palette, block.get("border", "")),
                _ci(palette, block.get("color", ""))]
    if t == "icon-row":
        items = [[i.get("icon",""), i.get("title",""), i.get("text",""),
                  _ci(palette, i.get("iconColor","")),
                  _ci(palette, i.get("iconBg",""))]
                 for i in block.get("items", [])]
        return [7, items, block.get("gap", 0),
                block.get("titleSize", ""), block.get("textSize", "")]
    if t == "table":
        return [9, block.get("headers", []), block.get("rows", []),
                1 if block.get("striped") else 0,
                _ci(palette, block.get("headerBg", "")),
                _ci(palette, block.get("headerColor", "")),
                _ci(palette, block.get("cellColor", "")),
                _ci(palette, block.get("borderColor", "")),
                block.get("size", "")]
    if t == "flow":
        items = [[i.get("icon",""), i.get("label",""), i.get("sublabel","")]
                 for i in block.get("items", [])]
        return [10, items, _ci(palette, block.get("arrowColor", "")),
                block.get("direction", ""),
                _ci(palette, block.get("labelColor", "")),
                _ci(palette, block.get("sublabelColor", ""))]
    if t == "steps":
        items = [[i.get("title",""), i.get("text","")]
                 for i in block.get("items", [])]
        return [11, items, _ci(palette, block.get("lineColor", "")),
                _ci(palette, block.get("numberColor", "")),
                _ci(palette, block.get("titleColor", "")),
                _ci(palette, block.get("textColor", ""))]
    if t == "tag-group":
        items = [[i.get("text",""), _ci(palette, i.get("color",""))]
                 for i in block.get("items", [])]
        return [12, items, block.get("variant", ""), block.get("size", "")]
    if t == "grid":
        grid_items = []
        for gi in block.get("items", []):
            sub_blocks = [_turbo_encode_block(b, palette) for b in gi.get("blocks", [])]
            grid_items.append([sub_blocks, gi.get("style", {}), gi.get("direction", "")])
        return [4, block.get("cols", 0), block.get("gap", 0), grid_items]
    if t == "divider":
        return [13, _ci(palette, block.get("color", ""))]
    if t == "comparison":
        sides = []
        for side in block.get("items", []):
            side_items = [si if isinstance(si, str) else si.get("text", "") for si in side.get("items", [])]
            sides.append([side.get("title", ""), side.get("icon", ""),
                          _ci(palette, side.get("color", "")), side_items])
        return [14, sides, block.get("dividerLabel", ""),
                block.get("titleSize", ""), block.get("size", "")]
    if t == "funnel":
        items = [[i.get("label", ""), i.get("value", ""),
                  _ci(palette, i.get("color", "")),
                  i.get("drop", ""), 1 if i.get("highlight") else 0]
                 for i in block.get("items", [])]
        return [15, items]
    if t == "cycle":
        items = [[i.get("label", ""), i.get("icon", ""),
                  _ci(palette, i.get("color", ""))]
                 for i in block.get("items", [])]
        return [16, items, block.get("centerLabel", ""),
                block.get("centerSub", "")]
    if t == "number-row":
        items = [[i.get("value", ""), i.get("label", ""),
                  i.get("icon", ""), _ci(palette, i.get("color", ""))]
                 for i in block.get("items", [])]
        return [17, items, block.get("size", ""),
                1 if block.get("compact") else 0,
                1 if block.get("bordered") else 0]
    if t == "matrix":
        quads = []
        for q in block.get("quadrants", block.get("items", [])):
            q_items = [qi if isinstance(qi, str) else qi.get("text", "") for qi in q.get("items", [])]
            quads.append([q.get("title", ""), q.get("icon", ""),
                          _ci(palette, q.get("color", "")), q_items])
        return [18, quads, block.get("xLeft", ""), block.get("xRight", ""),
                block.get("yTop", ""), block.get("yBottom", "")]
    if t == "checklist":
        # A plain-string item (valid in the app and validate.py) stays a bare
        # string, so it decodes back unchanged.
        items = [i if isinstance(i, str) else
                 [i.get("text", ""), i.get("status", "pending")]
                 + ([i["label"]] if i.get("label") else [])
                 for i in block.get("items", [])]
        return [19, items, block.get("size", ""),
                1 if block.get("showLabels", True) else 0]
    # Passthrough for unknown types
    return [99, block]


def _turbo_decode_block(arr, palette):
    """Decode a positional array back to a block dict."""
    def _cv(idx):
        """Color value from palette index."""
        if idx < 0 or idx >= len(palette):
            return ""
        return palette[idx]

    def _clean(d):
        """Remove empty-string values."""
        return {k: v for k, v in d.items() if v != "" and v != 0 and v is not None} if isinstance(d, dict) else d

    if not isinstance(arr, list) or len(arr) < 1:
        return arr
    tid = arr[0]

    if tid == 1:  # spacer
        return {"type": "spacer", "h": arr[1]}
    if tid == 0:  # badge
        r = {"type": "badge", "text": arr[1], "icon": arr[2]}
        bg = _cv(arr[3]); color = _cv(arr[4])
        if bg: r["bg"] = bg
        if color: r["color"] = color
        return r
    if tid == 2:  # heading
        r = {"type": "heading", "text": arr[1], "size": arr[2]}
        if arr[3]: r["weight"] = arr[3]
        c = _cv(arr[4])
        if c: r["color"] = c
        if len(arr) > 5 and arr[5]: r["icon"] = arr[5]
        if len(arr) > 6 and arr[6]: r["iconColor"] = arr[6]
        if len(arr) > 7 and arr[7]: r["align"] = arr[7]
        return r
    if tid == 3:  # text
        r = {"type": "text", "text": arr[1], "size": arr[2]}
        c = _cv(arr[3])
        if c: r["color"] = c
        if len(arr) > 4 and arr[4]: r["align"] = arr[4]
        return r
    if tid == 5:  # icon
        r = {"type": "icon", "name": arr[1], "size": arr[2]}
        c = _cv(arr[3])
        if c: r["color"] = c
        if arr[4]: r["circle"] = True
        bg = _cv(arr[5])
        if bg: r["bg"] = bg
        return r
    if tid == 8:  # code
        r = {"type": "code", "text": arr[1], "label": arr[2], "size": arr[3]}
        bg = _cv(arr[4])
        if bg: r["bg"] = bg
        c = _cv(arr[5])
        if c: r["color"] = c
        return r
    if tid == 6:  # callout
        r = {"type": "callout", "text": arr[1], "icon": arr[2]}
        bg = _cv(arr[3])
        if bg: r["bg"] = bg
        if arr[4] != "" and arr[4] >= 0:
            border = _cv(arr[4])
            if border: r["border"] = border
        c = _cv(arr[5])
        if c: r["color"] = c
        return r
    if tid == 7:  # icon-row
        items = [{"icon": i[0], "title": i[1], "text": i[2],
                  "iconColor": _cv(i[3]), "iconBg": _cv(i[4])}
                 for i in arr[1]]
        items = [{k:v for k,v in i.items() if v} for i in items]
        r = {"type": "icon-row", "items": items}
        if arr[2]: r["gap"] = arr[2]
        if arr[3]: r["titleSize"] = arr[3]
        if arr[4]: r["textSize"] = arr[4]
        return r
    if tid == 9:  # table
        r = {"type": "table", "headers": arr[1], "rows": arr[2]}
        if arr[3]: r["striped"] = True
        hb = _cv(arr[4])
        if hb: r["headerBg"] = hb
        hc = _cv(arr[5])
        if hc: r["headerColor"] = hc
        cc = _cv(arr[6])
        if cc: r["cellColor"] = cc
        bc = _cv(arr[7])
        if bc: r["borderColor"] = bc
        if arr[8]: r["size"] = arr[8]
        return r
    if tid == 10:  # flow
        items = [{"icon": i[0], "label": i[1], "sublabel": i[2]}
                 for i in arr[1]]
        r = {"type": "flow", "items": items}
        ac = _cv(arr[2])
        if ac: r["arrowColor"] = ac
        if arr[3]: r["direction"] = arr[3]
        lc = _cv(arr[4])
        if lc: r["labelColor"] = lc
        sc = _cv(arr[5])
        if sc: r["sublabelColor"] = sc
        return r
    if tid == 11:  # steps
        items = [{"title": i[0], "text": i[1]} for i in arr[1]]
        r = {"type": "steps", "items": items}
        lc = _cv(arr[2])
        if lc: r["lineColor"] = lc
        nc = _cv(arr[3])
        if nc: r["numberColor"] = nc
        tc = _cv(arr[4])
        if tc: r["titleColor"] = tc
        xc = _cv(arr[5])
        if xc: r["textColor"] = xc
        return r
    if tid == 12:  # tag-group
        items = [{"text": i[0], "color": _cv(i[1])} for i in arr[1]]
        items = [{k:v for k,v in i.items() if v} for i in items]
        r = {"type": "tag-group", "items": items}
        if arr[2]: r["variant"] = arr[2]
        if arr[3]: r["size"] = arr[3]
        return r
    if tid == 4:  # grid
        grid_items = []
        for gi in arr[3]:
            blocks = [_turbo_decode_block(b, palette) for b in gi[0]]
            item = {"blocks": blocks}
            if gi[1]: item["style"] = gi[1]
            if gi[2]: item["direction"] = gi[2]
            grid_items.append(item)
        r = {"type": "grid", "items": grid_items}
        if arr[1]: r["cols"] = arr[1]
        if arr[2]: r["gap"] = arr[2]
        return r
    if tid == 13:  # divider
        r = {"type": "divider"}
        c = _cv(arr[1]) if len(arr) > 1 else ""
        if c: r["color"] = c
        return r
    if tid == 14:  # comparison
        sides = []
        for s in arr[1]:
            side = {"title": s[0]}
            if s[1]: side["icon"] = s[1]
            c = _cv(s[2])
            if c: side["color"] = c
            side["items"] = s[3]
            sides.append(side)
        r = {"type": "comparison", "items": sides}
        if len(arr) > 2 and arr[2]: r["dividerLabel"] = arr[2]
        if len(arr) > 3 and arr[3]: r["titleSize"] = arr[3]
        if len(arr) > 4 and arr[4]: r["size"] = arr[4]
        return r
    if tid == 15:  # funnel
        items = []
        for i in arr[1]:
            item = {"label": i[0], "value": i[1]}
            c = _cv(i[2])
            if c: item["color"] = c
            if i[3]: item["drop"] = i[3]
            if i[4]: item["highlight"] = True
            items.append(item)
        return {"type": "funnel", "items": items}
    if tid == 16:  # cycle
        items = []
        for i in arr[1]:
            item = {"label": i[0]}
            if i[1]: item["icon"] = i[1]
            c = _cv(i[2])
            if c: item["color"] = c
            items.append(item)
        r = {"type": "cycle", "items": items}
        if len(arr) > 2 and arr[2]: r["centerLabel"] = arr[2]
        if len(arr) > 3 and arr[3]: r["centerSub"] = arr[3]
        return r
    if tid == 17:  # number-row
        items = []
        for i in arr[1]:
            item = {"value": i[0], "label": i[1]}
            if i[2]: item["icon"] = i[2]
            c = _cv(i[3])
            if c: item["color"] = c
            items.append(item)
        r = {"type": "number-row", "items": items}
        if len(arr) > 2 and arr[2]: r["size"] = arr[2]
        if len(arr) > 3 and arr[3]: r["compact"] = True
        if len(arr) > 4 and arr[4]: r["bordered"] = True
        return r
    if tid == 18:  # matrix
        quads = []
        for q in arr[1]:
            quad = {"title": q[0]}
            if q[1]: quad["icon"] = q[1]
            c = _cv(q[2])
            if c: quad["color"] = c
            quad["items"] = q[3]
            quads.append(quad)
        r = {"type": "matrix", "quadrants": quads}
        if len(arr) > 2 and arr[2]: r["xLeft"] = arr[2]
        if len(arr) > 3 and arr[3]: r["xRight"] = arr[3]
        if len(arr) > 4 and arr[4]: r["yTop"] = arr[4]
        if len(arr) > 5 and arr[5]: r["yBottom"] = arr[5]
        return r
    if tid == 19:  # checklist
        items = []
        for i in arr[1]:
            if isinstance(i, str):
                items.append(i)
                continue
            item = {"text": i[0], "status": i[1]}
            if len(i) > 2 and i[2]: item["label"] = i[2]
            items.append(item)
        r = {"type": "checklist", "items": items}
        if len(arr) > 2 and arr[2]: r["size"] = arr[2]
        if len(arr) > 3 and not arr[3]: r["showLabels"] = False
        return r
    if tid == 99:  # passthrough
        return arr[1]
    return arr


def turbo_deck(deck):
    """Convert full deck JSON to turbo format (positional arrays + color palette)."""
    # Ensure full format first
    if _is_compact(deck):
        deck = expand_deck(deck)

    palette = _build_palette(deck)

    def encode_slide(s):
        arr = [
            s.get("title", ""),
            _ci(palette, s.get("bg", "")),
            s.get("bgGradient", ""),
            _ci(palette, s.get("color", "")),
            _ci(palette, s.get("accent", "")),
            s.get("align", ""),
            s.get("verticalAlign", ""),
            s.get("padding", ""),
            s.get("duration", 0),
            [_turbo_encode_block(b, palette) for b in s.get("blocks", [])]
        ]
        # Optional trailing positions, appended only when present:
        #   10 = studyNotes (offline student content)
        #   11 = imageCols  (pinned column count for a run of adjacent images)
        # Backward compatible — old decoders reading new decks ignore extras;
        # new decoders reading old decks handle missing positions via len() guards.
        # Position 11 requires 10 to exist, so emit a null placeholder when a
        # slide has imageCols but no studyNotes.
        sn = s.get("studyNotes")
        ic = s.get("imageCols")
        #   12 = story      (true: present the slide's images one by one)
        # Positions 10 and 11 get null placeholders when story is set without them.
        st = s.get("story") is True
        if sn or ic or st:
            arr.append(sn if sn else None)
        if ic or st:
            arr.append(ic if ic else None)
        if st:
            arr.append(True)
        return arr

    def encode_item(item):
        return [
            item.get("title", ""),
            item.get("status", "done"),
            item.get("importance", "must"),
            [encode_slide(s) for s in item.get("slides", [])]
        ]

    def encode_lane(lane):
        return [
            lane.get("title", ""),
            [encode_item(i) for i in lane.get("items", [])]
        ]

    return [
        deck.get("deckTitle", "Untitled"),
        [encode_lane(l) for l in deck.get("lanes", [])],
        palette
    ]


def unturbo_deck(data):
    """Convert turbo format back to full deck JSON."""
    if not _is_turbo(data):
        return data

    deck_title = data[0]
    lanes_data = data[1]
    palette = data[2] if len(data) > 2 else []

    def decode_slide(s):
        def _cv(idx):
            if idx < 0 or idx >= len(palette): return ""
            return palette[idx]
        result = {"title": s[0]}
        bg = _cv(s[1])
        if bg: result["bg"] = bg
        if s[2]: result["bgGradient"] = s[2]
        color = _cv(s[3])
        if color: result["color"] = color
        accent = _cv(s[4])
        if accent: result["accent"] = accent
        if s[5]: result["align"] = s[5]
        if s[6]: result["verticalAlign"] = s[6]
        if s[7]: result["padding"] = s[7]
        if s[8]: result["duration"] = s[8]
        result["blocks"] = [_turbo_decode_block(b, palette) for b in s[9]]
        # Optional trailing positions (backward compatible with length-10 turbo):
        #   10 = studyNotes, 11 = imageCols, 12 = story
        if len(s) > 10 and s[10]:
            result["studyNotes"] = s[10]
        if len(s) > 11 and s[11]:
            result["imageCols"] = s[11]
        if len(s) > 12 and s[12] is True:
            result["story"] = True
        return result

    def decode_item(item):
        return {
            "title": item[0],
            "status": item[1],
            "importance": item[2],
            "slides": [decode_slide(s) for s in item[3]]
        }

    def decode_lane(lane):
        return {
            "title": lane[0],
            "items": [decode_item(i) for i in lane[1]]
        }

    return {
        "deckTitle": deck_title,
        "lanes": [decode_lane(l) for l in lanes_data]
    }


def _load_full(path):
    """Load a deck JSON and auto-expand if compact or turbo."""
    deck = _load_deck(path)
    if _is_turbo(deck):
        return unturbo_deck(deck)
    if _is_compact(deck):
        return expand_deck(deck)
    return deck


# ── CAPABILITIES ───────────────────────────────────────────────────────
CAPABILITIES = {
    "version": "2.6.0",
    "resources": {
        "deck": {
            "commands": {
                "list": "vela deck list <deck.vela> — TOC with slide#, title, blocks, duration",
                "validate": "vela deck validate <deck.vela> — check deck JSON integrity",
                "split": "vela deck split <deck.vela> --sections \"Title:N,...\" | --flat | --size N — regroup slides into sections (--flat to merge all into one)",
                "assemble": "vela deck assemble <deck.vela> [--output <path>] — inject deck into JSX artifact",
                "ship": "vela deck ship <deck.vela> [--output <path>] — validate + assemble in one call",
                "replace-text": "vela deck replace-text <deck.vela> \"old\" \"new\" — find/replace across all slides (hex colors auto-cascade to rgba)",
                "stats": "vela deck stats <deck.vela> — health audit: block distribution, missing durations, overflow, monotony issues",
                "find": "vela deck find <deck.vela> --query \"text\" | --type flow | --missing duration — search slides by content, block type, or missing props",
                "dump": "vela deck dump <deck.vela> [--full] — compact text-only view of all slides (--full for all text fields)",
                "extract-text": "vela deck extract-text <deck.vela> [output.json] — extract all translatable text as key-value map",
                "patch-text": "vela deck patch-text <deck.vela> <texts.json> — apply translated text map back into deck",
                "expand": "vela deck expand <compact.vela> <full.vela> — compact/turbo → full format",
                "compact": "vela deck compact <full.vela> <compact.vela> — full → compact format",
                "turbo": "vela deck turbo <deck.vela> <turbo.vela> — any → turbo format",
            },
            "description": "Deck-level operations (auto-detects full/compact/turbo format)"
        },
        "slide": {
            "commands": {
                "view": "vela slide view <deck.vela> <N> — show slide content summary",
                "edit": "vela slide edit <deck.vela> <N> <key> <value> — edit slide/block property (block.I.key for blocks)",
                "remove": "vela slide remove <deck.vela> <N> — remove a slide",
                "move": "vela slide move <deck.vela> <from> <to> — reorder a slide",
                "duplicate": "vela slide duplicate <deck.vela> <N> — copy a slide",
                "insert": "vela slide insert <deck.vela> <N> <slide.json> — insert slide from file",
                "remove-block": "vela slide remove-block <deck.vela> <N> <block#> — remove a block from a slide",
            },
            "description": "Slide-level operations (1-indexed slide numbers)"
        }
    },
    "global_flags": ["--json (structured output)", "--dry-run (preview without writing)", "--help"],
    "exit_codes": {"0": "success", "1": "failure", "2": "usage error", "3": "not found", "4": "validation error", "5": "conflict"}
}


# ── DECK COMMANDS ──────────────────────────────────────────────────────

def deck_list(args):
    """List slides as compact TOC. Usage: vela deck list <deck.vela>"""
    if not args:
        _err(EXIT_USAGE, "Missing deck path", suggestions=["vela deck list /home/claude/deck.vela"])
    deck = _load_full(args[0])
    slides = []
    for idx, slide, item, si in _all_slides(deck):
        blocks = slide.get("blocks", [])
        types = {}
        for b in blocks:
            t = b.get("type", "?")
            if t != "spacer":
                types[t] = types.get(t, 0) + 1
        theme = "dark" if _is_dark(slide) else "light"
        slides.append({
            "num": idx,
            "title": slide.get("title", "—"),
            "section": item.get("title", "?"),
            "blocks": len(blocks),
            "theme": theme,
            "duration": slide.get("duration", 0),
            "block_types": types
        })

    if _is_json():
        _ok({"deck_title": deck.get("deckTitle", "Untitled"), "slide_count": len(slides), "slides": slides})
    else:
        title = deck.get("deckTitle", "Untitled")
        emit(f"📊 {title}")
        emit(f"{'#':>3}  {'Title':<40} {'Blk':>4} {'Theme':>6} {'Dur':>5}  Types")
        emit("─" * 95)
        for s in slides:
            types_str = ", ".join(f"{t}:{c}" for t, c in s["block_types"].items())
            # IDENTITY sink: this row is how the operator tells one slide from
            # another, so it gets the label policy (NFKC fold + whitespace
            # collapse + width cap) rather than only the funnel's content
            # encoder. Capping inside term_label also keeps the column aligned:
            # slicing the RAW title to 38 and escaping afterwards would let an
            # escaped control byte push the row wider than its column.
            emit(f"{s['num']:>3}  {term_label(s['title'], '—', 38):<40} {s['blocks']:>4} {s['theme']:>6} {s['duration']:>4}s  {types_str}")
        emit(f"\n   Total: {len(slides)} slides")
        sys.exit(EXIT_OK)

def deck_validate(args):
    """Validate deck JSON. Usage: vela deck validate <deck.vela>"""
    if not args:
        _err(EXIT_USAGE, "Missing deck path", suggestions=["vela deck validate /home/claude/deck.vela"])
    # Auto-expand to a temp file for validation — preserve original format on disk
    path = args[0]
    deck = _load_deck(path)
    validate_path = path
    if _is_turbo(deck) or _is_compact(deck):
        import tempfile
        expanded = unturbo_deck(deck) if _is_turbo(deck) else expand_deck(deck)
        tmp_fd, validate_path = tempfile.mkstemp(suffix=".json")
        os.close(tmp_fd)
        _save_deck(expanded, validate_path)
    result = subprocess.run([sys.executable, VALIDATE_PY, validate_path], capture_output=True, text=True)
    if validate_path != path:
        os.unlink(validate_path)
    if result.returncode != 0:
        if _is_json():
            _err(EXIT_VALIDATION, result.stdout.strip() or result.stderr.strip(), retryable=True,
                 suggestions=["Fix the reported errors and re-run: vela deck validate <deck.vela>",
                              "Use --json for structured error details"])
        else:
            emit(result.stdout, end="")
            emit(result.stderr, end="", file=sys.stderr)
            sys.exit(EXIT_VALIDATION)
    else:
        if _is_json():
            _ok({"valid": True, "output": result.stdout.strip()}, "Deck is valid")
        else:
            emit(result.stdout, end="")
            sys.exit(EXIT_OK)

def deck_assemble(args):
    """Assemble deck JSON into JSX artifact.
    Usage: vela deck assemble <deck.vela> [--output <path>]"""
    # Parse --output flag
    output_path, filtered = _extract_output_flag(args)
    if not filtered:
        _err(EXIT_USAGE, "Missing deck path", suggestions=["vela deck assemble deck.vela", "vela deck assemble deck.vela --output out.jsx"])
    # Auto-expand to temp file for assembly — preserve original format on disk
    path = filtered[0]
    assemble_path = path
    deck = _load_deck(path)
    if _is_turbo(deck) or _is_compact(deck):
        import tempfile
        expanded = unturbo_deck(deck) if _is_turbo(deck) else expand_deck(deck)
        tmp_fd, assemble_path = tempfile.mkstemp(suffix=".json")
        os.close(tmp_fd)
        _save_deck(expanded, assemble_path)
    cmd = [sys.executable, ASSEMBLE_PY, assemble_path]
    if output_path:
        cmd += ["--output", output_path]
    result = subprocess.run(cmd, capture_output=True, text=True)
    if assemble_path != path:
        os.unlink(assemble_path)
    if result.returncode != 0:
        detail = result.stderr.strip() or result.stdout.strip() or "Unknown error"
        _err(EXIT_FAIL, f"Assembly failed: {detail}", retryable=True)
    else:
        if _is_json():
            _ok({"assembled": True, "output": result.stdout.strip()})
        else:
            emit(result.stdout, end="")
            sys.exit(EXIT_OK)

def deck_extract(args):
    """Extract STARTUP_PATCH deck JSON from a .jsx artifact.
    Usage: vela deck extract <source.jsx> [output.json]"""
    import re as _re
    if not args:
        _err(EXIT_USAGE, "Missing source .jsx path",
             suggestions=["vela deck extract artifact.jsx",
                          "vela deck extract artifact.jsx deck.vela"])
    source = args[0]
    output = args[1] if len(args) > 1 else source.replace('.jsx', '-deck.vela')

    if not os.path.isfile(source):
        _err(EXIT_NOT_FOUND, f"File not found: {source}")

    with open(source, 'r', encoding="utf-8") as f:
        content = f.read()

    match = _re.search(r'const STARTUP_PATCH = ({.*?});\s*\n', content, _re.DOTALL)
    if not match:
        _err(EXIT_NOT_FOUND, "No STARTUP_PATCH found in file",
             suggestions=["Is this a Vela .jsx artifact?",
                          "The file must contain 'const STARTUP_PATCH = {...};'"])

    try:
        deck = json.loads(match.group(1))
    except json.JSONDecodeError as e:
        _err(EXIT_FAIL, f"STARTUP_PATCH JSON is invalid: {e}")

    with open(output, 'w', encoding="utf-8") as f:
        json.dump(deck, f, ensure_ascii=False)

    lanes = len(deck.get('lanes', []))
    slides = sum(len(item.get('slides', []))
                 for lane in deck.get('lanes', [])
                 for item in lane.get('items', []))

    if _is_json():
        _ok({"extracted": True, "output": output, "deckTitle": deck.get("deckTitle", ""),
             "lanes": lanes, "slides": slides})
    else:
        emit(f"✅ Extracted: {output}")
        emit(f"   {deck.get('deckTitle', '?')} — {lanes} lane(s), {slides} slide(s)")
        sys.exit(EXIT_OK)

def deck_ship(args):
    """Validate + assemble + copy JSON to outputs. One-shot pipeline.
    Auto-expands compact format before processing.
    Usage: vela deck ship <deck.vela> [--output <path>]"""
    output_path, filtered = _extract_output_flag(args)

    # Handle --sample flag
    if "--sample" in filtered:
        filtered = [a for a in filtered if a != "--sample"]
        sample_path = os.path.join(SKILL_ROOT, "..", "..", "examples", "vela-demo.vela")
        sample_path = os.path.normpath(sample_path)
        if not os.path.isfile(sample_path):
            _err(EXIT_NOT_FOUND, "Sample deck not found",
                 suggestions=[f"Expected at: {sample_path}"])
        # Copy sample to a working location
        work_path = os.path.join(OUTPUT_DIR, "sample-deck.vela")
        os.makedirs(os.path.dirname(work_path) or '.', exist_ok=True)
        shutil.copy2(sample_path, work_path)
        filtered = [work_path]

    # Handle --demo flag (bundled demo deck showcasing all block types)
    elif "--demo" in filtered:
        filtered = [a for a in filtered if a != "--demo"]
        demo_path = os.path.join(SKILL_ROOT, "examples", "vela-demo.json")
        if not os.path.isfile(demo_path):
            _err(EXIT_NOT_FOUND, "Demo deck not found",
                 suggestions=[f"Expected at: {demo_path}"])
        work_path = os.path.join(OUTPUT_DIR, "vela-demo.json")
        os.makedirs(os.path.dirname(work_path) or '.', exist_ok=True)
        shutil.copy2(demo_path, work_path)
        filtered = [work_path]

    if not filtered:
        _err(EXIT_USAGE, "Missing deck path", suggestions=["vela deck ship deck.vela", "vela deck ship deck.vela --output out.jsx"])
    path = filtered[0]
    steps = []
    was_compact = False

    # Step 0: Auto-expand compact or turbo to a temp file for validate+assemble.
    # Preserve original format on disk so the source deck stays compact.
    deck = _load_deck(path)
    ship_path = path  # path used for validate+assemble (may be temp)
    if _is_turbo(deck) or _is_compact(deck):
        import tempfile
        was_compact = True
        expanded = unturbo_deck(deck) if _is_turbo(deck) else expand_deck(deck)
        tmp_fd, ship_path = tempfile.mkstemp(suffix=".json")
        os.close(tmp_fd)
        _save_deck(expanded, ship_path)
        slides_n = sum(1 for _ in _all_slides(expanded))
        fmt_name = "turbo" if _is_turbo(deck) else "compact"
        steps.append({"step": "expand", "success": True,
                       "output": f"Expanded {fmt_name} format ({slides_n} slides)"})

    # Step 1: Validate
    result = subprocess.run([sys.executable, VALIDATE_PY, ship_path], capture_output=True, text=True)
    steps.append({"step": "validate", "success": result.returncode == 0, "output": result.stdout.strip()})
    if result.returncode != 0:
        if ship_path != path:
            os.unlink(ship_path)
        if _is_json():
            _err(EXIT_VALIDATION, "Validation failed", suggestions=["Fix issues and retry"])
        else:
            emit(result.stdout, end="")
            emit("❌ Validation failed — aborting ship", file=sys.stderr)
            sys.exit(EXIT_VALIDATION)

    # Step 2: Assemble
    assemble_cmd = [sys.executable, ASSEMBLE_PY, ship_path, "--minify"]
    if output_path:
        assemble_cmd += ["--output", output_path]
    result = subprocess.run(assemble_cmd, capture_output=True, text=True)
    steps.append({"step": "assemble", "success": result.returncode == 0, "output": result.stdout.strip()})
    if result.returncode != 0:
        detail = result.stderr.strip() or result.stdout.strip() or "Unknown error"
        if _is_json():
            _err(EXIT_FAIL, f"Assembly failed: {detail}")
        else:
            emit(result.stdout, end="")
            emit(f"❌ Assembly failed: {detail}", file=sys.stderr)
            sys.exit(EXIT_FAIL)

    # Clean up temp expanded file
    if ship_path != path:
        os.unlink(ship_path)

    # Step 3: Copy JSON to outputs (skip if already in output dir)
    basename = os.path.splitext(os.path.basename(path))[0]
    out_dir = os.path.dirname(os.path.abspath(output_path)) if output_path else OUTPUT_DIR
    json_out = os.path.join(out_dir, basename + ".vela")
    if os.path.abspath(path) != os.path.abspath(json_out):
        os.makedirs(out_dir, exist_ok=True)
        shutil.copy2(path, json_out)
        steps.append({"step": "copy_json", "success": True, "output_path": json_out})
    else:
        steps.append({"step": "copy_json", "success": True, "output_path": path, "skipped": "already in output dir"})

    # Find the JSX output
    jsx_path = None
    for line in steps[-2]["output"].split("\n"):
        if "Assembled:" in line:
            parts = line.split("Assembled:")
            if len(parts) > 1:
                jsx_path = parts[1].strip().split()[0] if parts[1].strip() else None

    files_to_present = []
    if jsx_path and os.path.exists(jsx_path):
        files_to_present.append(jsx_path)
    files_to_present.append(json_out)

    if _is_json():
        _ok({
            "shipped": True,
            "was_compact": was_compact,
            "steps": steps,
            "present_files": files_to_present
        }, "Deck shipped successfully")
    else:
        for s in steps:
            if s.get("output"):
                emit(s["output"])
        if was_compact:
            emit(f"✅ Auto-expanded from compact format", file=sys.stderr)
        emit(f"✅ JSON copied to {json_out}", file=sys.stderr)
        emit(f"\n📦 Ready to present:", file=sys.stderr)
        for f in files_to_present:
            emit(f"   {f}", file=sys.stderr)
        sys.exit(EXIT_OK)

def _is_hex_color(s):
    """Check if a string looks like a hex color (#rrggbb)."""
    import re as _re
    return bool(_re.match(r'^#[0-9a-fA-F]{6}$', s))

def deck_replace_text(args):
    """Find/replace text across entire deck. Idempotent.
    When replacing hex colors, also cascades into rgba() values automatically.
    Usage: vela deck replace-text <deck.vela> <old> <new>"""
    if len(args) < 3:
        _err(EXIT_USAGE, "Need: <deck.vela> <old> <new>",
             suggestions=["vela deck replace-text deck.vela \"old text\" \"new text\"",
                          "vela deck replace-text deck.vela \"#3b82f6\" \"#2563eb\"  (also remaps rgba)"])
    path, old, new = args[0], args[1], args[2]
    deck = _load_deck(path)
    raw = json.dumps(deck, ensure_ascii=False)
    count = raw.count(old)
    if count == 0:
        if _is_json():
            _ok({"replaced": 0, "old": old, "new": new}, "Text not found — no changes")
        else:
            emit(f"⚠️  \"{old}\" not found in deck — no changes", file=sys.stderr)
            sys.exit(EXIT_OK)
    raw = raw.replace(old, new)

    # Cascade: if replacing a hex color, also remap matching rgba() values
    rgba_count = 0
    if _is_hex_color(old) and _is_hex_color(new):
        old_h = old.lstrip("#")
        new_h = new.lstrip("#")
        old_r, old_g, old_b = int(old_h[0:2], 16), int(old_h[2:4], 16), int(old_h[4:6], 16)
        new_r, new_g, new_b = int(new_h[0:2], 16), int(new_h[2:4], 16), int(new_h[4:6], 16)
        for old_pat, new_pat in [
            (f"rgba({old_r},{old_g},{old_b},", f"rgba({new_r},{new_g},{new_b},"),
            (f"rgba({old_r}, {old_g}, {old_b},", f"rgba({new_r},{new_g},{new_b},"),
        ]:
            c = raw.count(old_pat)
            if c > 0:
                raw = raw.replace(old_pat, new_pat)
                rgba_count += c

    deck = json.loads(raw)
    _save_deck(deck, path)
    total = count + rgba_count
    if _is_json():
        result = {"replaced": count, "old": old, "new": new}
        if rgba_count > 0:
            result["rgba_cascaded"] = rgba_count
        _ok(result)
    else:
        msg = f"✅ Replaced {count} occurrence(s): \"{old}\" → \"{new}\""
        if rgba_count > 0:
            msg += f" (+{rgba_count} rgba cascaded)"
        emit(msg, file=sys.stderr)
        sys.exit(EXIT_OK)

def deck_expand(args):
    """Expand compact or turbo deck to full Vela JSON.
    Usage: vela deck expand <deck.vela> [output.json]"""
    if not args:
        _err(EXIT_USAGE, "Missing deck path",
             suggestions=["vela deck expand compact.vela full.vela"])
    path = args[0]
    output = args[1] if len(args) > 1 else None
    deck = _load_deck(path)
    if _is_turbo(deck):
        expanded = unturbo_deck(deck)
        fmt_name = "turbo"
    elif _is_compact(deck):
        expanded = expand_deck(deck)
        fmt_name = "compact"
    else:
        if _is_json():
            _ok({"already_full": True}, "Deck is already in full format")
        else:
            emit("⚠️  Deck is already in full format — no expansion needed", file=sys.stderr)
            sys.exit(EXIT_OK)
        return
    out_path = output or path
    _save_deck(expanded, out_path)
    slide_count = sum(1 for _ in _all_slides(expanded))
    if _is_json():
        _ok({"expanded": True, "from": fmt_name, "slides": slide_count, "output": out_path})
    else:
        emit(f"✅ Expanded {fmt_name} → {slide_count} slides → {out_path}", file=sys.stderr)
        sys.exit(EXIT_OK)

def deck_compact(args):
    """Compact a full deck to compact format (~61% fewer tokens).
    Usage: vela deck compact <full.vela> [output.json]"""
    if not args:
        _err(EXIT_USAGE, "Missing deck path",
             suggestions=["vela deck compact full.vela compact.vela"])
    path = args[0]
    output = args[1] if len(args) > 1 else None
    deck = _load_deck(path)
    if _is_compact(deck):
        if _is_json():
            _ok({"already_compact": True}, "Deck is already compact")
        else:
            emit("⚠️  Deck is already compact — no compaction needed", file=sys.stderr)
            sys.exit(EXIT_OK)
    compacted = compact_deck(deck)
    out_path = output or path

    # Calculate savings
    full_mini = json.dumps(deck, ensure_ascii=False, separators=(',',':'))
    compact_mini = json.dumps(compacted, ensure_ascii=False, separators=(',',':'))
    full_bytes = len(full_mini.encode())
    compact_bytes = len(compact_mini.encode())
    savings = (1 - compact_bytes / full_bytes) * 100 if full_bytes > 0 else 0

    with open(out_path, 'w', encoding="utf-8") as f:
        json.dump(compacted, f, ensure_ascii=False, separators=(',',':'))

    slide_count = len(compacted.get("S", []))
    themes = len(compacted.get("T", {}))
    if _is_json():
        _ok({"compacted": True, "slides": slide_count, "themes": themes,
             "full_bytes": full_bytes, "compact_bytes": compact_bytes,
             "savings_pct": round(savings, 1), "output": out_path})
    else:
        emit(f"✅ Compacted {slide_count} slides, {themes} themes → {out_path}", file=sys.stderr)
        emit(f"   {full_bytes:,}B → {compact_bytes:,}B ({savings:.0f}% smaller)", file=sys.stderr)
        sys.exit(EXIT_OK)

def deck_turbo(args):
    """Convert deck to turbo format (positional arrays + color palette).
    ~44% token savings. For storage/cache, not LLM generation.
    Usage: vela deck turbo <deck.vela> [output.json]"""
    if not args:
        _err(EXIT_USAGE, "Missing deck path",
             suggestions=["vela deck turbo deck.vela turbo.vela"])
    path = args[0]
    output = args[1] if len(args) > 1 else None
    deck = _load_deck(path)

    # Accept any format as input
    if _is_turbo(deck):
        if _is_json():
            _ok({"already_turbo": True}, "Deck is already in turbo format")
        else:
            emit("⚠️  Deck is already in turbo format", file=sys.stderr)
            sys.exit(EXIT_OK)
    if _is_compact(deck):
        deck = expand_deck(deck)

    turbo = turbo_deck(deck)
    out_path = output or path

    # Calculate savings
    full_mini = json.dumps(deck, ensure_ascii=False, separators=(',',':'))
    turbo_mini = json.dumps(turbo, ensure_ascii=False, separators=(',',':'))
    full_bytes = len(full_mini.encode())
    turbo_bytes = len(turbo_mini.encode())
    savings = (1 - turbo_bytes / full_bytes) * 100 if full_bytes > 0 else 0

    with open(out_path, 'w', encoding="utf-8") as f:
        json.dump(turbo, f, ensure_ascii=False, separators=(',',':'))

    slide_count = sum(1 for _ in _all_slides(deck))
    palette_size = len(turbo[2]) if len(turbo) > 2 else 0

    if _is_json():
        _ok({"turbo": True, "slides": slide_count, "palette_colors": palette_size,
             "full_bytes": full_bytes, "turbo_bytes": turbo_bytes,
             "savings_pct": round(savings, 1), "output": out_path})
    else:
        emit(f"✅ Turbo: {slide_count} slides, {palette_size} colors → {out_path}", file=sys.stderr)
        emit(f"   {full_bytes:,}B → {turbo_bytes:,}B ({savings:.0f}% smaller)", file=sys.stderr)
        sys.exit(EXIT_OK)


# ── SLIDE COMMANDS ─────────────────────────────────────────────────────

def _block_summary(block):
    """Compact one-line summary of a block."""
    t = block.get("type", "?")
    if t == "spacer": return f"[spacer h={block.get('h', '?')}]"
    if t == "heading":
        icon = f" 🔹{block.get('icon','')}" if block.get("icon") else ""
        return f"[heading/{block.get('size','?')}] \"{block.get('text', '')}\"{icon}"
    if t == "text":
        txt = block.get("text", "")[:80]
        if len(block.get("text", "")) > 80: txt += "..."
        return f"[text/{block.get('size','?')}] \"{txt}\""
    if t == "badge": return f"[badge] \"{block.get('text', '')}\" bg={block.get('bg', '?')}"
    if t == "bullets":
        n = len(block.get("items", []))
        return f"[bullets ×{n}]"
    if t == "icon-row":
        titles = [i.get("title", "?") for i in block.get("items", [])[:3]]
        return f"[icon-row ×{len(block.get('items',[]))}] {' · '.join(titles)}"
    if t == "grid":
        return f"[grid cols={block.get('cols','?')} cells={len(block.get('items',[]))}]"
    if t == "flow":
        labels = [i.get("label", "?") for i in block.get("items", [])]
        loop = " 🔁" if block.get("loop") else ""
        return f"[flow] {' → '.join(labels)}{loop}"
    if t == "table":
        return f"[table {len(block.get('headers',[]))}cols × {len(block.get('rows',[]))}rows]"
    if t == "metric": return f"[metric] {block.get('value','?')} — {block.get('label','')}"
    if t == "callout":
        txt = block.get("text", "")[:65]
        return f"[callout] \"{txt}...\""
    if t == "timeline":
        items = block.get("items", [])
        return f"[timeline ×{len(items)}]" if items else "[timeline]"
    if t == "svg":
        return f"[svg {len(block.get('markup',''))}ch] align={block.get('align','?')}"
    if t == "divider": return f"[divider] color={block.get('color','?')}"
    if t == "steps": return f"[steps ×{len(block.get('items',[]))}]"
    if t == "progress": return f"[progress ×{len(block.get('items',[]))}]"
    if t == "quote": return f"[quote] \"{block.get('text','')[:50]}...\""
    if t == "image": return f"[image]"
    if t == "code": return f"[code] {block.get('label','?')}"
    if t == "icon": return f"[icon] {block.get('name','?')}"
    if t == "tag-group": return f"[tag-group ×{len(block.get('items',[]))}]"
    return f"[{t}]"

def slide_view(args):
    """View a single slide. Usage: vela slide view <deck.vela> <num> [--json|--raw]"""
    if len(args) < 2:
        _err(EXIT_USAGE, "Need: <deck.vela> <slide_num>",
             suggestions=["vela slide view deck.vela 3", "vela slide view deck.vela 3 --raw"])
    path, num = args[0], int(args[1])
    raw_mode = "--raw" in args
    deck = _load_full(path)

    slides, si, item = _get_slide(deck, num)
    if slides is None:
        _err(EXIT_NOT_FOUND, f"Slide {num} not found",
             suggestions=["Run: vela deck list " + path])

    slide = slides[si]
    if raw_mode or _is_json():
        _ok(slide if raw_mode else {
            "num": num,
            "section": item.get("title", "?"),
            "slide": slide
        })
    else:
        emit(f"━━━ Slide {num}: {slide.get('title', '—')} ━━━")
        emit(f"  Section: {item.get('title', '?')}")
        emit(f"  bg: {slide.get('bg','?')}  accent: {slide.get('accent','?')}  align: {slide.get('align','left')}  vAlign: {slide.get('verticalAlign','top')}")
        if slide.get("bgGradient"):
            g = slide["bgGradient"]
            emit(f"  gradient: {g[:60]}{'...' if len(g)>60 else ''}")
        emit(f"  padding: {slide.get('padding','?')}  duration: {slide.get('duration','?')}s")
        emit(f"  blocks ({len(slide.get('blocks', []))}):")
        for i, block in enumerate(slide.get("blocks", [])):
            # _block_summary returns deck text mixed with our own chrome, across
            # a function boundary — the shape where "is this value untrusted?"
            # stops being obvious at the call site. Untrusted makes the encoded
            # form the DEFAULT rendering of this value in any f-string, so the
            # interpolation is safe on its own rather than only because emit()
            # cleans up afterwards. Layer under the funnel, not instead of it.
            emit(f"    [{i}] {Untrusted(_block_summary(block))}")
        sn = slide.get("studyNotes")
        if sn and isinstance(sn, dict):
            emit(f"  studyNotes: {len(sn.get('text', ''))} chars, "
                  f"{len(sn.get('questions', []) or [])} questions, "
                  f"{len(sn.get('glossary', {}) or {})} glossary terms, "
                  f"diagram={'yes' if sn.get('diagram') else 'no'}")
        sys.exit(EXIT_OK)

def slide_edit(args):
    """Edit a slide property. Usage: vela slide edit <deck.vela> <num> <key> <value>"""
    if len(args) < 4:
        _err(EXIT_USAGE, "Need: <deck.vela> <slide_num> <key> <value>",
             suggestions=["vela slide edit deck.vela 3 duration 90",
                          "vela slide edit deck.vela 3 bg \"#ffffff\""])
    path, num, key, value = args[0], int(args[1]), args[2], args[3]

    # Check for block edit: "block.N.key"
    if key.startswith("block."):
        parts = key.split(".")
        if len(parts) != 3:
            _err(EXIT_USAGE, "Block edit format: block.<index>.<property>",
                 suggestions=["vela slide edit deck.vela 3 block.2.text \"New heading\""])
        bnum, bkey = int(parts[1]), parts[2]
        deck = _load_full(path)
        slides, si, _ = _get_slide(deck, num)
        if slides is None:
            _err(EXIT_NOT_FOUND, f"Slide {num} not found")
        blocks = slides[si].get("blocks", [])
        if bnum >= len(blocks):
            _err(EXIT_NOT_FOUND, f"Block {bnum} not found in slide {num} (has {len(blocks)} blocks)")
        # Type coercion
        try: value = int(value)
        except ValueError:
            try: value = float(value)
            except ValueError: pass
        if value == "true": value = True
        elif value == "false": value = False
        old = blocks[bnum].get(bkey, "<unset>")

        if "--dry-run" in args:
            _ok({"would_execute": "set_block", "slide": num, "block": bnum, "key": bkey, "old": str(old), "new": str(value), "reversible": True})
            return

        blocks[bnum][bkey] = value
        _save_deck(deck, path)
        _ok({"slide": num, "block": bnum, "key": bkey, "old": str(old), "new": str(value)},
            f"Slide {num} block [{bnum}].{bkey}: {old} → {value}")
        return

    # Slide-level edit
    deck = _load_full(path)
    slides, si, _ = _get_slide(deck, num)
    if slides is None:
        _err(EXIT_NOT_FOUND, f"Slide {num} not found")

    try: value = int(value)
    except ValueError:
        try: value = float(value)
        except ValueError: pass
    if value == "true": value = True
    elif value == "false": value = False

    old = slides[si].get(key, "<unset>")

    if "--dry-run" in args:
        _ok({"would_execute": "set", "slide": num, "key": key, "old": str(old), "new": str(value), "reversible": True})
        return

    slides[si][key] = value
    _save_deck(deck, path)
    _ok({"slide": num, "key": key, "old": str(old), "new": str(value)},
        f"Slide {num}.{key}: {old} → {value}")

def slide_remove(args):
    """Remove a slide. Usage: vela slide remove <deck.vela> <num> [--dry-run]"""
    if len(args) < 2:
        _err(EXIT_USAGE, "Need: <deck.vela> <slide_num>")
    path, num = args[0], int(args[1])
    deck = _load_full(path)
    slides, si, item = _get_slide(deck, num)
    if slides is None:
        _err(EXIT_NOT_FOUND, f"Slide {num} not found")

    title = slides[si].get("title", "?")
    if "--dry-run" in args:
        _ok({"would_execute": "remove_slide", "slide": num, "title": title, "reversible": False})
        return

    slides.pop(si)
    if len(slides) == 0:
        for lane in deck.get("lanes", []):
            if item in lane.get("items", []):
                lane["items"].remove(item)
                break
    _save_deck(deck, path)
    _ok({"removed": num, "title": title}, f"Removed slide {num}: \"{title}\"")

def slide_move(args):
    """Move a slide. Usage: vela slide move <deck.vela> <from_num> <to_num>"""
    if len(args) < 3:
        _err(EXIT_USAGE, "Need: <deck.vela> <from> <to>")
    path, from_num, to_num = args[0], int(args[1]), int(args[2])
    deck = _load_full(path)

    from_slides, from_si, from_item = _get_slide(deck, from_num)
    if from_slides is None:
        _err(EXIT_NOT_FOUND, f"Slide {from_num} not found")

    slide = from_slides.pop(from_si)
    if len(from_slides) == 0:
        for lane in deck.get("lanes", []):
            if from_item in lane.get("items", []):
                lane["items"].remove(from_item)
                break

    target = to_num if to_num <= from_num else to_num - 1
    to_slides, to_si, _ = _get_slide(deck, target)
    if to_slides is None:
        _err(EXIT_NOT_FOUND, f"Target position {to_num} not found")
    to_slides.insert(to_si + 1, slide)
    _save_deck(deck, path)
    _ok({"from": from_num, "to": to_num}, f"Moved slide {from_num} → position {to_num}")

def slide_duplicate(args):
    """Duplicate a slide. Usage: vela slide duplicate <deck.vela> <num>"""
    if len(args) < 2:
        _err(EXIT_USAGE, "Need: <deck.vela> <slide_num>")
    path, num = args[0], int(args[1])
    deck = _load_full(path)
    slides, si, _ = _get_slide(deck, num)
    if slides is None:
        _err(EXIT_NOT_FOUND, f"Slide {num} not found")
    dup = copy.deepcopy(slides[si])
    dup["title"] = dup.get("title", "") + " (copy)"
    slides.insert(si + 1, dup)
    _save_deck(deck, path)
    _ok({"duplicated": num, "new_position": num + 1}, f"Duplicated slide {num} → {num + 1}")

def slide_insert(args):
    """Insert a slide from JSON file. Usage: vela slide insert <deck.vela> <after_num> <slide.json>"""
    if len(args) < 3:
        _err(EXIT_USAGE, "Need: <deck.vela> <after_num> <slide_file.json>")
    path, after_num, slide_file = args[0], int(args[1]), args[2]
    slide_file = _safe_resolve(slide_file, "slide file")
    if not os.path.exists(slide_file):
        _err(EXIT_NOT_FOUND, f"Slide file not found: {slide_file}")
    with open(slide_file, encoding="utf-8") as f:
        new_slide = json.load(f)
    deck = _load_full(path)
    slides, si, _ = _get_slide(deck, after_num)
    if slides is None:
        _err(EXIT_NOT_FOUND, f"Slide {after_num} not found")
    slides.insert(si + 1, new_slide)
    _save_deck(deck, path)
    _ok({"inserted_after": after_num}, f"Inserted slide after {after_num}")

def slide_remove_block(args):
    """Remove a block from a slide. Usage: vela slide remove-block <deck.vela> <slide_num> <block_num>"""
    if len(args) < 3:
        _err(EXIT_USAGE, "Need: <deck.vela> <slide_num> <block_num>")
    path, snum, bnum = args[0], int(args[1]), int(args[2])
    deck = _load_full(path)
    slides, si, _ = _get_slide(deck, snum)
    if slides is None:
        _err(EXIT_NOT_FOUND, f"Slide {snum} not found")
    blocks = slides[si].get("blocks", [])
    if bnum >= len(blocks):
        _err(EXIT_NOT_FOUND, f"Block {bnum} not found in slide {snum}")

    removed = blocks[bnum]
    if "--dry-run" in args:
        _ok({"would_execute": "remove_block", "slide": snum, "block": bnum,
             "type": removed.get("type", "?"), "reversible": False})
        return

    blocks.pop(bnum)
    _save_deck(deck, path)
    _ok({"slide": snum, "block": bnum, "type": removed.get("type", "?")},
        f"Removed block [{bnum}] (type={removed.get('type','?')}) from slide {snum}")


# ── DECK STATS ─────────────────────────────────────────────────────────

def deck_stats(args):
    """Audit deck health: block distribution, quality issues, missing properties.
    Usage: vela deck stats <deck.vela>
    Mirrors Vera's deck_stats tool — finds missing durations, overflow, monotony."""
    if not args:
        _err(EXIT_USAGE, "Missing deck path", suggestions=["vela deck stats deck.vela"])
    path = args[0]
    deck = _load_full(path)

    total_slides = 0
    total_time = 0
    missing_duration = 0
    missing_bg = 0
    empty_modules = 0
    block_counts = {}
    issues = []

    for lane in deck.get("lanes", []):
        for item in lane.get("items", []):
            if len(item.get("slides", [])) == 0:
                empty_modules += 1
                issues.append(f'"{item.get("title", "?")}" has 0 slides')
            for si, slide in enumerate(item.get("slides", [])):
                total_slides += 1
                total_time += slide.get("duration", 0)
                if not slide.get("duration"):
                    missing_duration += 1
                    issues.append(f'Slide {total_slides}: missing duration')
                if not slide.get("bg") and not slide.get("bgGradient"):
                    missing_bg += 1
                    issues.append(f'Slide {total_slides}: missing bg/bgGradient')
                blocks = slide.get("blocks", [])
                block_count = len(blocks)
                block_count += len(slide.get("L", []))
                block_count += len(slide.get("R", []))
                if block_count > 7:
                    issues.append(f'Slide {total_slides}: {block_count} blocks (overflow risk)')
                for b in blocks:
                    bt = b.get("type", "unknown")
                    block_counts[bt] = block_counts.get(bt, 0) + 1
                    # Count nested blocks inside grid cells by their actual type
                    if bt == "grid":
                        for cell in b.get("items", []):
                            for cb in cell.get("blocks", []):
                                cbt = cb.get("type", "unknown")
                                block_counts[cbt] = block_counts.get(cbt, 0) + 1
                # Count blocks in L/R (cols layout)
                for col_key in ("L", "R"):
                    for b in slide.get(col_key, []):
                        bt = b.get("type", "unknown")
                        block_counts[bt] = block_counts.get(bt, 0) + 1
                        if bt == "grid":
                            for cell in b.get("items", []):
                                for cb in cell.get("blocks", []):
                                    cbt = cb.get("type", "unknown")
                                    block_counts[cbt] = block_counts.get(cbt, 0) + 1
                # Check heading+bullets monotony
                types = [b.get("type", "") for b in blocks]
                rich_types = {"flow", "grid", "table", "metric", "timeline", "steps",
                              "icon-row", "progress", "code", "svg", "image", "tag-group"}
                has_rich = any(t in rich_types for t in types)
                has_heading = "heading" in types
                has_bullets = "bullets" in types
                if has_heading and has_bullets and not has_rich and block_count >= 2:
                    issues.append(f'Slide {total_slides}: only heading+bullets — consider icon-row, grid, or flow')

    modules = sum(len(l.get("items", [])) for l in deck.get("lanes", []))
    m, s = divmod(total_time, 60)
    h, m = divmod(m, 60)
    time_str = f"{h}h {m}m" if h > 0 else f"{m}m {s}s" if m > 0 else f"{s}s"
    block_dist = sorted(block_counts.items(), key=lambda x: -x[1])

    if _is_json():
        _ok({
            "lanes": len(deck.get("lanes", [])),
            "modules": modules,
            "slides": total_slides,
            "duration": total_time,
            "duration_str": time_str,
            "blocks": dict(block_dist),
            "missing_duration": missing_duration,
            "missing_bg": missing_bg,
            "empty_modules": empty_modules,
            "issues": issues,
        })
    else:
        emit(f"📊 {deck.get('deckTitle', 'Deck')}")
        emit(f"   {len(deck.get('lanes', []))} lanes · {modules} modules · {total_slides} slides · {time_str}")
        emit(f"   Blocks: {', '.join(f'{k}:{v}' for k, v in block_dist)}")
        if missing_duration:
            emit(f"   ⚠ {missing_duration} slides missing duration")
        if missing_bg:
            emit(f"   ⚠ {missing_bg} slides missing bg")
        if empty_modules:
            emit(f"   ⚠ {empty_modules} empty modules")
        if issues:
            emit(f"\n   🔍 Issues ({len(issues)}):")
            for issue in issues[:15]:
                emit(f"   • {issue}")
            if len(issues) > 15:
                emit(f"   ...and {len(issues) - 15} more")
        else:
            emit(f"\n   ✅ No issues found")
        sys.exit(EXIT_OK)


# ── DECK FIND ──────────────────────────────────────────────────────────

def deck_find(args):
    """Search slides by text, block type, or missing properties.
    Usage: vela deck find <deck.vela> [--query "text"] [--type flow] [--missing duration]
    Mirrors Vera's find_slides tool — fuzzy text search + block type + property filters."""
    if not args:
        _err(EXIT_USAGE, "Missing deck path",
             suggestions=["vela deck find deck.vela --query 'ReAct'",
                          "vela deck find deck.vela --type flow",
                          "vela deck find deck.vela --missing duration"])
    path = args[0]
    deck = _load_full(path)

    # Parse flags
    query = ""
    block_type = ""
    prop_missing = ""
    i = 1
    while i < len(args):
        if args[i] == "--query" and i + 1 < len(args):
            query = args[i + 1].lower(); i += 2
        elif args[i] == "--type" and i + 1 < len(args):
            block_type = args[i + 1].lower(); i += 2
        elif args[i] == "--missing" and i + 1 < len(args):
            prop_missing = args[i + 1]; i += 2
        else:
            # Treat bare args as query
            if not query and not args[i].startswith("-"):
                query = args[i].lower()
            i += 1

    if not query and not block_type and not prop_missing:
        _err(EXIT_USAGE, "Need at least one of: --query, --type, --missing",
             suggestions=["vela deck find deck.vela --query 'agent'",
                          "vela deck find deck.vela --type table",
                          "vela deck find deck.vela --missing duration"])

    def walk_text(blocks):
        parts = []
        for b in (blocks or []):
            for key in ("text", "title", "label", "value", "author", "caption"):
                if key in b and isinstance(b[key], str):
                    parts.append(b[key])
            for it in b.get("items", []):
                if isinstance(it, str):
                    parts.append(it)
                elif isinstance(it, dict):
                    for key in ("text", "label", "title", "sublabel"):
                        if key in it:
                            parts.append(it[key])
            if b.get("type") == "grid":
                for cell in b.get("items", []):
                    parts.extend(walk_text(cell.get("blocks", [])))
            for row in b.get("rows", []):
                if isinstance(row, list):
                    parts.extend(str(c) for c in row)
            for h in b.get("headers", []):
                if isinstance(h, str):
                    parts.append(h)
        return parts

    results = []
    slide_num = 0
    for lane in deck.get("lanes", []):
        for item in lane.get("items", []):
            for si, slide in enumerate(item.get("slides", [])):
                slide_num += 1
                match = True

                # Text search
                if query:
                    all_text = " ".join([
                        item.get("title", ""),
                        slide.get("title", ""),
                        *walk_text(slide.get("blocks", []))
                    ]).lower()
                    if query not in all_text:
                        match = False

                # Block type filter
                if block_type and match:
                    types = [b.get("type", "") for b in slide.get("blocks", [])]
                    # Also check grid cell blocks
                    for b in slide.get("blocks", []):
                        if b.get("type") == "grid":
                            for cell in b.get("items", []):
                                types.extend(cb.get("type", "") for cb in cell.get("blocks", []))
                    if block_type not in types:
                        match = False

                # Missing property
                if prop_missing and match:
                    if slide.get(prop_missing) is not None and slide.get(prop_missing) != 0:
                        match = False

                if match:
                    heading = ""
                    for b in slide.get("blocks", []):
                        if b.get("type") == "heading":
                            heading = b.get("text", "")
                            break
                    results.append({
                        "slide": slide_num,
                        "title": heading or slide.get("title", f"Slide {slide_num}"),
                        "module": item.get("title", ""),
                    })

    if _is_json():
        _ok({"found": len(results), "query": query or None, "type": block_type or None,
             "missing": prop_missing or None, "results": results})
    else:
        if not results:
            emit(f"No matches found", file=sys.stderr)
            sys.exit(EXIT_OK)
        emit(f"🔍 Found {len(results)} match{'es' if len(results) != 1 else ''}:")
        for r in results[:20]:
            emit(f"   #{r['slide']:2d} {r['title']}")
        if len(results) > 20:
            emit(f"   ...and {len(results) - 20} more")
        sys.exit(EXIT_OK)


# ── DECK DUMP ──────────────────────────────────────────────────────────

def deck_dump(args):
    """Compact text-only view of entire deck for content review.
    Usage: vela deck dump <deck.vela> [--full]

    Default: one line per slide (heading + badge + first body text)
    --full: all text fields per slide (for detailed review/improvement)"""
    if not args:
        _err(EXIT_USAGE, "Missing deck path", suggestions=["vela deck dump deck.vela", "vela deck dump deck.vela --full"])
    path = args[0]
    full_mode = "--full" in args
    deck = _load_full(path)

    if full_mode:
        texts = _extract_texts(deck)
        if _is_json():
            _ok({"fields": len(texts), "texts": texts})
        else:
            cur_slide = ""
            for k, v in texts.items():
                # Group by slide
                slide_key = k.split(".")[0] if k.startswith("s") else k
                if slide_key != cur_slide and k.startswith("s"):
                    cur_slide = slide_key
                    emit(f"\n━━━ Slide {slide_key[1:]} ━━━")
                emit(f"  {k}: {v}")
            sys.exit(EXIT_OK)
    else:
        slide_num = 0
        lines = []
        for lane in deck.get("lanes", []):
            for item in lane.get("items", []):
                for si, slide in enumerate(item.get("slides", [])):
                    slide_num += 1
                    heading = ""
                    badge = ""
                    body = ""
                    for block in slide.get("blocks", []):
                        bt = block.get("type", "")
                        if bt == "heading" and not heading:
                            heading = block.get("text", "")
                        elif bt == "badge" and not badge:
                            badge = block.get("text", "")
                        elif bt in ("text", "callout") and not body and block.get("text"):
                            body = block["text"][:80]
                    line = f"  {slide_num:2d}. {heading}"
                    parts = []
                    if badge:
                        parts.append(f"[{badge}]")
                    if body:
                        parts.append(body)
                    if parts:
                        line += " — " + " | ".join(parts)
                    lines.append(line)

        if _is_json():
            _ok({"slides": slide_num, "dump": lines})
        else:
            emit(f"📋 {deck.get('deckTitle', 'Deck')} ({slide_num} slides)\n")
            for line in lines:
                emit(line)
            sys.exit(EXIT_OK)


# ── DECK EXTRACT-TEXT / PATCH-TEXT ─────────────────────────────────────

def _extract_texts(deck):
    """Walk deck JSON and extract all translatable text fields into a flat dict."""
    texts = {}
    # Deck title
    if deck.get("deckTitle"):
        texts["deckTitle"] = deck["deckTitle"]
    # Lane and item titles
    for li, lane in enumerate(deck.get("lanes", [])):
        if lane.get("title"):
            texts[f"l{li}.title"] = lane["title"]
        for ii, item in enumerate(lane.get("items", [])):
            if item.get("title"):
                texts[f"l{li}.m{ii}.title"] = item["title"]
    slide_num = 0
    for lane in deck.get("lanes", []):
        for item in lane.get("items", []):
            for si, slide in enumerate(item.get("slides", [])):
                slide_num += 1
                prefix = f"s{slide_num}"
                if slide.get("title"):
                    texts[f"{prefix}.title"] = slide["title"]
                for bi, block in enumerate(slide.get("blocks", [])):
                    bt = block.get("type", "")
                    bp = f"{prefix}.b{bi}"
                    # Skip code text (keep code as-is), but include code label
                    if bt == "code":
                        if "label" in block:
                            texts[f"{bp}.label"] = block["label"]
                        continue
                    if bt == "spacer":
                        continue
                    # Block-level text props
                    for key in ("text", "label", "title", "value", "author", "caption"):
                        if key in block and isinstance(block[key], str):
                            texts[f"{bp}.{key}"] = block[key]
                    # Nested items (flow, steps, icon-row, bullets, tag-group)
                    for ii, it in enumerate(block.get("items", [])):
                        if isinstance(it, str):
                            texts[f"{bp}.i{ii}"] = it
                        elif isinstance(it, dict):
                            for key in ("text", "x", "label", "lb", "sublabel", "sl", "title"):
                                if key in it and isinstance(it[key], str):
                                    texts[f"{bp}.i{ii}.{key}"] = it[key]
                    # Table headers and rows
                    for hi, h in enumerate(block.get("headers", [])):
                        if isinstance(h, str):
                            texts[f"{bp}.h{hi}"] = h
                    for ri, row in enumerate(block.get("rows", [])):
                        if isinstance(row, list):
                            for ci, cell in enumerate(row):
                                if isinstance(cell, str):
                                    texts[f"{bp}.r{ri}.c{ci}"] = cell
                    # Grid cell blocks
                    if bt == "grid":
                        for gi, gcell in enumerate(block.get("items", [])):
                            for gbi, gblock in enumerate(gcell.get("blocks", [])):
                                gbt = gblock.get("type", "")
                                gp = f"{bp}.g{gi}.b{gbi}"
                                if gbt in ("spacer", "icon"):
                                    continue
                                for key in ("text", "label", "title", "value"):
                                    if key in gblock and isinstance(gblock[key], str):
                                        texts[f"{gp}.{key}"] = gblock[key]
                                for gii, git in enumerate(gblock.get("items", [])):
                                    if isinstance(git, str):
                                        texts[f"{gp}.i{gii}"] = git
                                    elif isinstance(git, dict):
                                        for key in ("text", "x", "label", "title"):
                                            if key in git and isinstance(git[key], str):
                                                texts[f"{gp}.i{gii}.{key}"] = git[key]
                # L/R blocks (cols layout)
                for col_key in ("L", "R"):
                    for bi, block in enumerate(slide.get(col_key, [])):
                        bt = block.get("type", "")
                        bp = f"{prefix}.{col_key}{bi}"
                        if bt == "code":
                            if "label" in block:
                                texts[f"{bp}.label"] = block["label"]
                            continue
                        if bt == "spacer":
                            continue
                        for key in ("text", "label", "title", "value", "author", "caption"):
                            if key in block and isinstance(block[key], str):
                                texts[f"{bp}.{key}"] = block[key]
                        for ii, it in enumerate(block.get("items", [])):
                            if isinstance(it, str):
                                texts[f"{bp}.i{ii}"] = it
                            elif isinstance(it, dict):
                                for key in ("text", "x", "label", "lb", "sublabel", "sl", "title"):
                                    if key in it and isinstance(it[key], str):
                                        texts[f"{bp}.i{ii}.{key}"] = it[key]
                        for hi, h in enumerate(block.get("headers", [])):
                            if isinstance(h, str):
                                texts[f"{bp}.h{hi}"] = h
                        for ri, row in enumerate(block.get("rows", [])):
                            if isinstance(row, list):
                                for ci, cell in enumerate(row):
                                    if isinstance(cell, str):
                                        texts[f"{bp}.r{ri}.c{ci}"] = cell
                        if bt == "grid":
                            for gi, gcell in enumerate(block.get("items", [])):
                                for gbi, gblock in enumerate(gcell.get("blocks", [])):
                                    gbt = gblock.get("type", "")
                                    gp = f"{bp}.g{gi}.b{gbi}"
                                    if gbt in ("spacer", "icon"):
                                        continue
                                    for key in ("text", "label", "title", "value"):
                                        if key in gblock and isinstance(gblock[key], str):
                                            texts[f"{gp}.{key}"] = gblock[key]
                                    for gii, git in enumerate(gblock.get("items", [])):
                                        if isinstance(git, str):
                                            texts[f"{gp}.i{gii}"] = git
                                        elif isinstance(git, dict):
                                            for key in ("text", "x", "label", "title"):
                                                if key in git and isinstance(git[key], str):
                                                    texts[f"{gp}.i{gii}.{key}"] = git[key]
    return texts


def _patch_texts(deck, texts):
    """Apply a text map back into the deck JSON. Returns count of patches applied."""
    import re as _re
    patched = 0
    # Deck title
    if "deckTitle" in texts:
        deck["deckTitle"] = texts["deckTitle"]; patched += 1
    # Lane and item titles
    for li, lane in enumerate(deck.get("lanes", [])):
        key = f"l{li}.title"
        if key in texts:
            lane["title"] = texts[key]; patched += 1
        for ii, item in enumerate(lane.get("items", [])):
            key = f"l{li}.m{ii}.title"
            if key in texts:
                item["title"] = texts[key]; patched += 1
    slide_num = 0
    for lane in deck.get("lanes", []):
        for item in lane.get("items", []):
            for si, slide in enumerate(item.get("slides", [])):
                slide_num += 1
                prefix = f"s{slide_num}"
                key = f"{prefix}.title"
                if key in texts:
                    slide["title"] = texts[key]; patched += 1
                for bi, block in enumerate(slide.get("blocks", [])):
                    bt = block.get("type", "")
                    bp = f"{prefix}.b{bi}"
                    if bt == "code":
                        key = f"{bp}.label"
                        if key in texts:
                            block["label"] = texts[key]; patched += 1
                        continue
                    if bt == "spacer":
                        continue
                    for prop in ("text", "label", "title", "value", "author", "caption"):
                        key = f"{bp}.{prop}"
                        if key in texts:
                            block[prop] = texts[key]; patched += 1
                    for ii, it in enumerate(block.get("items", [])):
                        if isinstance(it, str):
                            key = f"{bp}.i{ii}"
                            if key in texts:
                                block["items"][ii] = texts[key]; patched += 1
                        elif isinstance(it, dict):
                            for prop in ("text", "x", "label", "lb", "sublabel", "sl", "title"):
                                key = f"{bp}.i{ii}.{prop}"
                                if key in texts:
                                    it[prop] = texts[key]; patched += 1
                    for hi, h in enumerate(block.get("headers", [])):
                        key = f"{bp}.h{hi}"
                        if key in texts:
                            block["headers"][hi] = texts[key]; patched += 1
                    for ri, row in enumerate(block.get("rows", [])):
                        if isinstance(row, list):
                            for ci, cell in enumerate(row):
                                key = f"{bp}.r{ri}.c{ci}"
                                if key in texts:
                                    row[ci] = texts[key]; patched += 1
                    if bt == "grid":
                        for gi, gcell in enumerate(block.get("items", [])):
                            for gbi, gblock in enumerate(gcell.get("blocks", [])):
                                gp = f"{bp}.g{gi}.b{gbi}"
                                for prop in ("text", "label", "title", "value"):
                                    key = f"{gp}.{prop}"
                                    if key in texts:
                                        gblock[prop] = texts[key]; patched += 1
                                for gii, git in enumerate(gblock.get("items", [])):
                                    if isinstance(git, str):
                                        key = f"{gp}.i{gii}"
                                        if key in texts:
                                            gblock["items"][gii] = texts[key]; patched += 1
                                    elif isinstance(git, dict):
                                        for prop in ("text", "x", "label", "title"):
                                            key = f"{gp}.i{gii}.{prop}"
                                            if key in texts:
                                                git[prop] = texts[key]; patched += 1
                # L/R blocks (cols layout)
                for col_key in ("L", "R"):
                    for bi, block in enumerate(slide.get(col_key, [])):
                        bt = block.get("type", "")
                        bp = f"{prefix}.{col_key}{bi}"
                        if bt == "code":
                            key = f"{bp}.label"
                            if key in texts:
                                block["label"] = texts[key]; patched += 1
                            continue
                        if bt == "spacer":
                            continue
                        for prop in ("text", "label", "title", "value", "author", "caption"):
                            key = f"{bp}.{prop}"
                            if key in texts:
                                block[prop] = texts[key]; patched += 1
                        for ii, it in enumerate(block.get("items", [])):
                            if isinstance(it, str):
                                key = f"{bp}.i{ii}"
                                if key in texts:
                                    block["items"][ii] = texts[key]; patched += 1
                            elif isinstance(it, dict):
                                for prop in ("text", "x", "label", "lb", "sublabel", "sl", "title"):
                                    key = f"{bp}.i{ii}.{prop}"
                                    if key in texts:
                                        it[prop] = texts[key]; patched += 1
                        for hi, h in enumerate(block.get("headers", [])):
                            key = f"{bp}.h{hi}"
                            if key in texts:
                                block["headers"][hi] = texts[key]; patched += 1
                        for ri, row in enumerate(block.get("rows", [])):
                            if isinstance(row, list):
                                for ci, cell in enumerate(row):
                                    key = f"{bp}.r{ri}.c{ci}"
                                    if key in texts:
                                        row[ci] = texts[key]; patched += 1
                        if bt == "grid":
                            for gi, gcell in enumerate(block.get("items", [])):
                                for gbi, gblock in enumerate(gcell.get("blocks", [])):
                                    gp = f"{bp}.g{gi}.b{gbi}"
                                    for prop in ("text", "label", "title", "value"):
                                        key = f"{gp}.{prop}"
                                        if key in texts:
                                            gblock[prop] = texts[key]; patched += 1
                                    for gii, git in enumerate(gblock.get("items", [])):
                                        if isinstance(git, str):
                                            key = f"{gp}.i{gii}"
                                            if key in texts:
                                                gblock["items"][gii] = texts[key]; patched += 1
                                        elif isinstance(git, dict):
                                            for prop in ("text", "x", "label", "title"):
                                                key = f"{gp}.i{gii}.{prop}"
                                                if key in texts:
                                                    git[prop] = texts[key]; patched += 1
    return patched


def deck_extract_text(args):
    """Extract all translatable text from a deck into a flat key-value JSON map.
    Usage: vela deck extract-text <deck.vela> [output.json]
    Keys use dot-path format: s1.b0.text, s3.b4.i0.label, s9.b4.r0.c1
    Excludes code block content (but includes code labels)."""
    if not args:
        _err(EXIT_USAGE, "Missing deck path",
             suggestions=["vela deck extract-text deck.vela texts.json"])
    path = args[0]
    output = args[1] if len(args) > 1 else None
    deck = _load_full(path)
    texts = _extract_texts(deck)

    result = json.dumps(texts, ensure_ascii=False, indent=2)
    if output:
        with open(output, "w", encoding="utf-8") as f:
            f.write(result)
        if _is_json():
            _ok({"extracted": len(texts), "output": output})
        else:
            emit(f"✅ Extracted {len(texts)} text fields → {output}", file=sys.stderr)
            sys.exit(EXIT_OK)
    else:
        # stdout is a round-trip path (`extract-text > t.json` then `patch-text`),
        # so it must stay lossless — the funnel's encoder would drop format
        # characters that belong to the author's text. ensure_ascii=True keeps
        # every codepoint recoverable AND leaves nothing for a terminal to
        # interpret, so the encoder is a no-op here instead of a corruption.
        # The file branch above stays unescaped: translators edit that by hand.
        emit(json.dumps(texts, ensure_ascii=True, indent=2))
        sys.exit(EXIT_OK)


def deck_patch_text(args):
    """Apply a translated text map back into a deck.
    Usage: vela deck patch-text <deck.vela> <texts.json>
    The texts.json must use the same key format as extract-text output."""
    if len(args) < 2:
        _err(EXIT_USAGE, "Need: <deck.vela> <texts.json>",
             suggestions=["vela deck patch-text deck.vela translated.json"])
    path, texts_path = args[0], args[1]
    deck = _load_full(path)
    with open(texts_path, "r", encoding="utf-8") as f:
        texts = json.load(f)
    patched = _patch_texts(deck, texts)
    _save_deck(deck, path)
    if _is_json():
        _ok({"patched": patched, "total_keys": len(texts)})
    else:
        emit(f"✅ Patched {patched}/{len(texts)} text fields", file=sys.stderr)
        sys.exit(EXIT_OK)


# ── DECK SPLIT ─────────────────────────────────────────────────────────

def deck_split(args):
    """Split a flat deck into sections (modules) by slide count or auto-grouping.
    Usage: vela deck split <deck.vela> [--flat] [--size N] [--sections "Title1:3,Title2:4,..."]

    --flat           Flatten all modules into a single module
    --size N         Split every N slides into a section (auto-titled)
    --sections       Named sections with slide counts: "Intro:3,Core:5,Close:2"

    Works on multi-module decks — flattens internally before regrouping.
    Without flags: auto-groups by scanning for badge/section-break slides."""
    if not args:
        _err(EXIT_USAGE, "Missing deck path",
             suggestions=["vela deck split deck.vela --size 5",
                          'vela deck split deck.vela --sections "Intro:3,Core:5,Close:2"'])
    path = args[0]
    deck = _load_full(path)

    all_slides = [slide for _, slide, _, _ in _all_slides(deck)]
    if not all_slides:
        _err(EXIT_FAIL, "Deck has no slides")

    # Parse flags
    size = None
    sections_spec = None
    flat = "--flat" in args
    i = 1
    while i < len(args):
        if args[i] == "--size" and i + 1 < len(args):
            try:
                size = int(args[i + 1])
            except ValueError:
                _err(EXIT_USAGE, f"Invalid size: {args[i+1]}")
            i += 2
        elif args[i] == "--sections" and i + 1 < len(args):
            sections_spec = args[i + 1]
            i += 2
        else:
            i += 1

    new_items = []

    if flat:
        # Flatten all into one module
        title = deck.get("deckTitle", "All Slides")
        new_items.append({"title": title, "status": "done",
                          "importance": "must", "slides": all_slides})

    elif sections_spec:
        # Named sections: "Intro:3,Core:5,Close:2"
        offset = 0
        for part in sections_spec.split(","):
            part = part.strip()
            if ":" not in part:
                _err(EXIT_USAGE, f"Invalid section spec: '{part}' (use 'Title:N')",
                     suggestions=['vela deck split deck.vela --sections "Intro:3,Core:5"'])
            title, count_str = part.rsplit(":", 1)
            try:
                count = int(count_str)
            except ValueError:
                _err(EXIT_USAGE, f"Invalid count in '{part}'")
            slides = all_slides[offset:offset + count]
            if slides:
                new_items.append({"title": title.strip(), "status": "done",
                                  "importance": "must", "slides": slides})
            offset += count
        # Remaining slides
        if offset < len(all_slides):
            new_items.append({"title": "Remaining", "status": "done",
                              "importance": "should", "slides": all_slides[offset:]})

    elif size:
        # Split every N slides
        for idx in range(0, len(all_slides), size):
            chunk = all_slides[idx:idx + size]
            first_title = chunk[0].get("title", "")
            # Try to get a meaningful title from the first slide's heading
            for block in chunk[0].get("blocks", []):
                if block.get("type") == "heading":
                    first_title = block.get("text", first_title)
                    break
                elif block.get("type") == "badge":
                    first_title = block.get("text", first_title)
            section_num = idx // size + 1
            title = first_title or f"Section {section_num}"
            new_items.append({"title": title, "status": "done",
                              "importance": "must", "slides": chunk})

    else:
        # Auto-group: scan for badge blocks that look like section markers
        current_slides = []
        current_title = "Introduction"
        for slide in all_slides:
            # Check if this slide starts a new section (has a badge block)
            badge_text = None
            for block in slide.get("blocks", []):
                if block.get("type") == "badge":
                    badge_text = block.get("text", "")
                    break
            # If the slide has a badge and we already have slides, start a new section
            if badge_text and current_slides:
                new_items.append({"title": current_title, "status": "done",
                                  "importance": "must", "slides": current_slides})
                current_slides = []
                # Get heading from this slide for the section title
                for block in slide.get("blocks", []):
                    if block.get("type") == "heading":
                        current_title = block.get("text", badge_text)
                        break
                else:
                    current_title = badge_text
            current_slides.append(slide)
        if current_slides:
            new_items.append({"title": current_title, "status": "done",
                              "importance": "must", "slides": current_slides})

    if "--dry-run" in args:
        summary = [{"title": it["title"], "slides": len(it["slides"])} for it in new_items]
        _ok({"would_execute": "split", "sections": summary, "total_slides": len(all_slides)})
        return

    deck["lanes"] = [{"title": "Main", "items": new_items}]
    _save_deck(deck, path)

    if _is_json():
        _ok({"sections": len(new_items), "slides": len(all_slides),
             "items": [{"title": it["title"], "slides": len(it["slides"])} for it in new_items]})
    else:
        emit(f"✅ Split {len(all_slides)} slides into {len(new_items)} sections:")
        for it in new_items:
            emit(f"   {it['title']} ({len(it['slides'])} slides)")
        sys.exit(EXIT_OK)


# ── DECK INIT / SLIDE APPEND (incremental deck building) ──────────────

def deck_init(args):
    """Create a deck skeleton. Usage: vela deck init <output.vela> --title "T" --palette '{"A":"#hex"}' --themes '{"d":{...}}' --sections "S1,S2,S3" [--force]
    Creates a valid compact deck with empty sections, ready for slide append.
    Refuses to overwrite an existing file (exit 5) unless --force is given."""
    if not args:
        _err(EXIT_USAGE, "Need: <output.vela> --title \"T\" --sections \"S1,S2\"")

    path = args[0]
    rest = args[1:]

    title = "Untitled"
    palette = {}
    themes = {}
    sections = ["Main"]
    force = False

    i = 0
    while i < len(rest):
        if rest[i] == "--title" and i + 1 < len(rest):
            title = rest[i + 1]; i += 2
        elif rest[i] == "--palette" and i + 1 < len(rest):
            palette = json.loads(rest[i + 1]); i += 2
        elif rest[i] == "--themes" and i + 1 < len(rest):
            themes = json.loads(rest[i + 1]); i += 2
        elif rest[i] == "--sections" and i + 1 < len(rest):
            sections = [s.strip() for s in rest[i + 1].split(",")]; i += 2
        elif rest[i] == "--force":
            force = True; i += 1
        else:
            i += 1

    # Refuse to clobber an existing deck unless --force — a fresh `init` over a
    # real deck would silently destroy it. This is the one genuine conflict
    # (EXIT_CONFLICT) the CLI can hit.
    if os.path.exists(path) and not force:
        _err(EXIT_CONFLICT, f"File already exists: {path}",
             suggestions=["Pass --force to overwrite", "Choose a different output path"])

    deck = {"n": title}
    if palette:
        deck["C"] = palette
    if themes:
        deck["T"] = themes
    deck["G"] = [{"g": s, "S": []} for s in sections]

    with open(path, 'w', encoding="utf-8") as f:
        json.dump(deck, f, ensure_ascii=False)
    section_count = len(sections)
    _ok({"path": path, "sections": section_count},
        f"Deck initialized: {title} ({section_count} sections)")


def slide_append(args):
    """Append a slide to a deck section. Usage: vela slide append <deck.vela> <section_index> '<slide_json>'
    Section index is 0-based. Slide JSON is compact format (inline string or @file)."""
    if len(args) < 3:
        _err(EXIT_USAGE, "Need: <deck.vela> <section_index> '<slide_json>'")

    path = args[0]
    section_idx = int(args[1])
    slide_arg = args[2]

    # Accept @file or inline JSON
    if slide_arg.startswith("@"):
        safe = _safe_resolve(slide_arg[1:], "slide @file")
        with open(safe, encoding="utf-8") as f:
            slide = json.load(f)
    else:
        slide = json.loads(slide_arg)

    deck = _load_deck(path)

    # Support both G (grouped) and S (flat) formats
    if "G" in deck:
        groups = deck["G"]
        if section_idx < 0 or section_idx >= len(groups):
            _err(EXIT_NOT_FOUND, f"Section {section_idx} not found (have {len(groups)} sections)")
        groups[section_idx]["S"].append(slide)
        total = sum(len(g["S"]) for g in groups)
        section_name = groups[section_idx].get("g", f"Section {section_idx}")
    elif "S" in deck:
        deck["S"].append(slide)
        total = len(deck["S"])
        section_name = "flat"
    else:
        _err(EXIT_FAIL, "Deck has no G or S key — run deck init first")

    with open(path, 'w', encoding="utf-8") as f:
        json.dump(deck, f, ensure_ascii=False)

    slide_name = slide.get("n", "untitled")
    _ok({"total_slides": total, "section": section_name, "slide": slide_name},
        f"Slide appended: \"{slide_name}\" → {section_name} ({total} total)")


# ── ROUTING ────────────────────────────────────────────────────────────
COMMANDS = {
    "deck": {
        "list": deck_list,
        "validate": deck_validate,
        "extract": deck_extract,
        "assemble": deck_assemble,
        "ship": deck_ship,
        "replace-text": deck_replace_text,
        "expand": deck_expand,
        "compact": deck_compact,
        "turbo": deck_turbo,
        "stats": deck_stats,
        "find": deck_find,
        "dump": deck_dump,
        "extract-text": deck_extract_text,
        "patch-text": deck_patch_text,
        "split": deck_split,
        "init": deck_init,
    },
    "slide": {
        "view": slide_view,
        "edit": slide_edit,
        "remove": slide_remove,
        "move": slide_move,
        "duplicate": slide_duplicate,
        "insert": slide_insert,
        "remove-block": slide_remove_block,
        "append": slide_append,
    },
}

def main():
    global _json_mode
    _json_mode = "--json" in sys.argv
    # Strip global flags from argv for cleaner parsing
    clean_args = [a for a in sys.argv[1:] if a not in ("--json", "--dry-run")]

    if "--capabilities" in sys.argv:
        _out(CAPABILITIES)
        sys.exit(EXIT_OK)

    if not clean_args or clean_args[0] in ("--help", "-h", "help"):
        emit(__doc__)
        sys.exit(EXIT_OK)

    resource = clean_args[0]
    if resource not in COMMANDS:
        _err(EXIT_USAGE, f"Unknown resource: {resource}",
             suggestions=[f"Available: {', '.join(COMMANDS.keys())}",
                          "Run: vela --capabilities"])

    if len(clean_args) < 2 or clean_args[1] in ("--help", "-h", "help"):
        cmds = ", ".join(COMMANDS[resource].keys())
        _err(EXIT_USAGE, f"Need an action for '{resource}'",
             suggestions=[f"Available: {cmds}", f"Example: vela {resource} {list(COMMANDS[resource].keys())[0]} --help"])

    action = clean_args[1]
    if action not in COMMANDS[resource]:
        _err(EXIT_USAGE, f"Unknown action: {resource} {action}",
             suggestions=[f"Available: {', '.join(COMMANDS[resource].keys())}"])

    # Pass remaining args (after resource + action) + any --dry-run
    remaining = clean_args[2:]
    if "--dry-run" in sys.argv:
        remaining.append("--dry-run")

    COMMANDS[resource][action](remaining)

if __name__ == "__main__":
    main()
canvas-designanthropics/skillsCreate beautiful visual art in .png and .pdf documents using design philosophy. You should use this skill when the user asks to create a poster, piece of art, design, or other static piece. Create original visual designs, never copying existing artists' work to avoid copyright violations.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
docxanthropics/skillsUse this skill whenever the user wants to create, read, edit, or manipulate Word documents (.docx files) or Word templates (.dotx files). Triggers include: any mention of 'Word doc', 'word document', '.docx', '.dotx', or requests to produce professional documents with formatting like tables of contents, headings, page numbers, or letterheads. Also use when extracting or reorganizing content from .docx or .dotx files, inserting or replacing images in documents, performing find-and-replace in Word files, working with tracked changes or comments, or converting content into a polished Word document. If the user asks for a 'report', 'memo', 'letter', 'template', or similar deliverable as a Word or .docx file, use this skill. Do NOT use for PDFs, spreadsheets, Google Docs, or general coding tasks unrelated to document generation.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
pdfanthropics/skillsUse this skill whenever the user wants to do anything with PDF files. This includes reading or extracting text/tables from PDFs, combining or merging multiple PDFs into one, splitting PDFs apart, rotating pages, adding watermarks, creating new PDFs, filling PDF forms, encrypting/decrypting PDFs, extracting images, and OCR on scanned PDFs to make them searchable. If the user mentions a .pdf file or asks to produce one, use this skill.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
pptxanthropics/skillsUse this skill any time a .pptx or .potx file is involved in any way — as input, output, or both. This includes: creating slide decks, pitch decks, or presentations; reading, parsing, or extracting text from any .pptx or .potx file (even if the extracted content will be used elsewhere, like in an email or summary); editing, modifying, or updating existing presentations; combining or splitting slide files; working with templates (.potx), layouts, speaker notes, or comments. Trigger whenever the user mentions "deck," "slides," "presentation," or references a .pptx or .potx filename, regardless of what they plan to do with the content afterward. If a .pptx or .potx file needs to be opened, created, or touched, use this skill.Stars: 198kUpdated Claude CodeCodexVerifiedInstall