@clipboard-health/ai-rules 2.29.2 → 2.29.3

package/skills/metabase-to-hex/references/yaml_schemas.md

@@ -0,0 +1,281 @@
+# Hex YAML cell shapes — exact schemas
+
+Hex's YAML import is picky. Use the shapes below verbatim. These are the only YAML
+constructs the round-trip path supports for adding new cells programmatically.
+
+## Top-level structure
+
+```yaml
+schemaVersion: 3
+meta:
+  sourceVersionId: <do not change>
+  description: ...
+  projectId: <do not change — Hex matches imports by this>
+  title: ...
+  timezone: null
+  appTheme: SYS_PREF
+  codeLanguage: PYTHON
+  status: { name: Development }
+  # ... other meta fields preserved from export ...
+projectAssets: { dataConnections: [], envVars: [], secrets: [] }
+sharedAssets:
+  secrets: []
+  vcsPackages: []
+  dataConnections:
+    - dataConnectionId: <conn-id>
+  externalFileIntegrations: []
+cells:
+  - <cell> # SQL cells (already created by hex cell create)
+  - <cell> # INPUT cells (added during YAML round-trip)
+  - <cell> # MARKDOWN cells (added during YAML round-trip)
+appLayout:
+  visibleMetadataFields: [NAME, DESCRIPTION, AUTHOR, LAST_EDITED, LAST_RUN, CATEGORIES, STATUS, TABLE_OF_CONTENTS]
+  fullWidth: true
+  tabs:
+    - name: <tab-name>
+      rows: [...]
+sharedFilters: []
+```
+
+## SQL cell (created by `hex cell create -t sql`)
+
+```yaml
+- cellType: SQL
+  cellId: <hex-assigned-uuid7>
+  cellLabel: <human-readable label>
+  config:
+    source: |-
+      SELECT ...
+      FROM ...
+      WHERE col = {{ shift_id }}    # NO QUOTES around {{ var }}
+    dataFrameCell: false
+    dataConnectionId: 530b70b8-b300-43c9-9b3e-e4b98ded0379
+    resultVariableName: <snake_case_slug>
+    useRichDisplay: true
+    enablePreview: true
+    sqlCellOutputType: PANDAS
+    useQueryMode: false
+    castDecimals: true
+    useNativeDates: true
+    outputFilteredResult: true
+    allowDuplicateColumns: false
+    tableDisplayConfig:
+      pageSize: 50
+      # ... other display config preserved from export ...
+```
+
+You will rarely hand-write SQL cells. Create them with `hex cell create` and edit
+their `source` only if you need to re-push fixes (use `hex cell update`).
+
+## INPUT cell (added via YAML round-trip)
+
+```yaml
+- cellType: INPUT
+  cellId: <fresh uuidv7>
+  cellLabel: Shift ID # what the UI shows above the box
+  config:
+    inputType: TEXT_INPUT
+    name: shift_id # the Jinja variable name — MUST match SQL refs
+    outputType: STRING
+    options: null # required key — omitting it = malformed import
+    defaultValue: "" # or a sample value to pre-populate
+```
+
+Key constraints:
+
+- `options: null` is **required** for `TEXT_INPUT`. Omitting it triggers a
+  generic "request was rejected as malformed" error during `hex project import`.
+- Do **not** add `label:` inside `config`. Only `cellLabel` at the cell level.
+- `name` is the Jinja variable, not just a display thing. The SQL cells reference
+  it as `{{ shift_id }}` and `{% if shift_id %}`.
+
+### Dropdown backed by a SQL cell (single-select)
+
+```yaml
+- cellType: INPUT
+  cellId: <fresh uuidv7>
+  cellLabel: MSA list # what the UI shows above the dropdown
+  config:
+    inputType: DROPDOWN
+    name: msa_list # the Jinja variable name
+    outputType: DYNAMIC
+    options:
+      valueOptions:
+        dfName: msa_options # SQL cell whose first column becomes the dropdown values
+        variableName: null
+      optional: false # set true to allow no selection
+    defaultValue: null
+```
+
+Notes:
+
+- `options.valueOptions.dfName` references the **SQL cell's output dataframe
+  name**. The YAML key for that on a SQL cell is `resultVariableName` (see the
+  SQL cell shape above), which is what `hex cell create --output-dataframe <name>`
+  writes. If you grep for `outputDataframe` you'll come up empty — the YAML
+  exports use `resultVariableName`.
+- The options SQL cell must be **run at least once** for the dataframe to
+  materialize, otherwise the dropdown is empty. After a fresh import, trigger
+  `hex project run` so the kernel populates it.
+- **Multi-select is NOT settable via YAML.** Push this exact single-select shape
+  and ask the user to flip the multi-select toggle in the cell's right-sidebar
+  config. The SQL referencing the variable should use `IN ({{ var | array }})`,
+  which is a no-op for single-select scalars but required once multi-select is
+  on (see gotchas 10/16).
+
+### Date input — single date or date range (set via UI, then SQL update)
+
+Date inputs (single or range) cannot be created via YAML import. Every variant
+tried — `DATE_PICKER`, `DATE_INPUT`, `DATE`, `DATE_RANGE`, `DATE_RANGE_PICKER`,
+`DATERANGE` — is rejected as "malformed" (gotcha 17). The working flow is:
+
+1. Push a `TEXT_INPUT` placeholder with the same `name`. Use a snake_case name
+   the SQL can reference even after the type changes (e.g. `shift_start_range`).
+2. Ask the user to open the cell in the UI and change **Input type** to
+   `Date`. For a range, they then toggle **Allow date range** on the same cell.
+3. _Then_ push SQL that references the variable correctly (see access patterns
+   below).
+
+After the UI flip, the cell's YAML export looks like this (do not hand-write
+it — Hex's import API still rejects it; capture it via `hex project export`
+only for diffing / understanding):
+
+```yaml
+# Single date
+- cellType: INPUT
+  cellId: <id>
+  cellLabel: As-of date
+  config:
+    inputType: DATE
+    name: as_of_date
+    outputType: DATETIME # Hex returns a datetime.datetime
+    options:
+      enableTime: false
+      showRelativeDates: true
+      useDateRange: false
+    defaultValue:
+      - dateString: 2026-06-01
+
+# Date range — same cell, useDateRange: true, defaultValue has TWO entries
+- cellType: INPUT
+  cellId: <id>
+  cellLabel: Shift start range
+  config:
+    inputType: DATE
+    name: shift_start_range
+    outputType: DATETIME
+    options:
+      enableTime: false
+      showRelativeDates: true
+      useDateRange: true
+    defaultValue:
+      - dateString: 2025-10-17
+      - dateString: 2025-10-30
+```
+
+**Jinja access pattern for date range — two separate variables suffixed
+`_start` and `_end`.** With `options.useDateRange: true`, Hex does **not**
+bind the cell's `name` to anything; instead it injects two new variables
+`<name>_start` and `<name>_end`, both `datetime.date`. Referencing the base
+`name` (e.g. `{{ shift_start_range }}`, `.start`, `.end`, `[0]`, `[1]`) all
+fail with `Undefined variable(s): <base name>` because the base is literally
+not in scope. Use:
+
+```sql
+{% if shift_start_range_start %}AND SHIFT_START_AT >= CAST({{ shift_start_range_start }} AS TIMESTAMP_NTZ){% endif %}
+{% if shift_start_range_end %}AND SHIFT_START_AT <  DATEADD(day, 1, CAST({{ shift_start_range_end }} AS TIMESTAMP_NTZ)){% endif %}
+```
+
+The two `if` guards short-circuit when either bound is cleared in the UI. The
+`+1 day` on the upper bound makes the range inclusive of the to-date (Hex
+passes dates at midnight UTC, so `< to_date` would exclude the to-day).
+
+**How to verify the variable name for any input cell:** create a one-off Python
+diagnostic cell with `globals().get('<candidate>', '<not in globals>')` for
+each plausible name (`<name>`, `<name>_start`, `<name>_end`, `<name>_from`,
+`<name>_to`, etc.). Run the project, read the output, fix SQL, then delete the
+cell. This took ~2 minutes on the card 21241 migration and saved guessing.
+
+Confirmed shape on project `019e83b9-aed0-723b-9b96-313269b324bc` (card 21241
+migration, 2026-06-01). The `name` field in the YAML is essentially a _prefix_
+for date-range inputs, not the variable name itself.
+
+### Other input types
+
+Hex also supports `NUMERIC_INPUT`, `SLIDER`, `FILE_INPUT`, etc. — but the YAML
+import API only accepts `TEXT_INPUT` and the single-select `DROPDOWN` shape
+above. For everything else, push `TEXT_INPUT` and cast/parse in SQL or Python,
+or stop after the cells are imported and ask the user to configure the input
+type in the Hex UI. See gotcha 17 for the full accepted/rejected list.
+
+## MARKDOWN cell (added via YAML round-trip)
+
+```yaml
+- cellType: MARKDOWN
+  cellId: <fresh uuidv7>
+  config:
+    source: |
+      ## Section header
+
+      Body text in CommonMark markdown. Hex renders it inline.
+```
+
+No `cellLabel` for markdown cells. If you set one, Hex preserves it but the UI
+doesn't surface it.
+
+## appLayout — tabs / rows / columns / elements
+
+```yaml
+appLayout:
+  fullWidth: true # full-width vs centered narrow column
+  tabs:
+    - name: Main
+      rows:
+        # Row 1: three inputs side-by-side
+        - columns:
+            - start: 0
+              end: 40
+              elements:
+                - <cell-element>
+            - start: 40
+              end: 80
+              elements:
+                - <cell-element>
+            - start: 80
+              end: 120
+              elements:
+                - <cell-element>
+        # Row 2: full-width SQL output
+        - columns:
+            - start: 0
+              end: 120
+              elements:
+                - <cell-element>
+```
+
+Columns span 0–120. Common patterns:
+
+- Full width: `start: 0, end: 120`
+- Halves: `start: 0, end: 60` and `start: 60, end: 120`
+- Thirds: `start: 0/40/80, end: 40/80/120`
+- Quarters: 0/30/60/90/120
+
+Multiple `elements` per column stack vertically.
+
+## Cell element shape (inside `elements: []`)
+
+```python
+{
+    "showSource": False,        # hide the SQL source pane (True = developer view)
+    "hideOutput": False,        # show the SQL result
+    "type": "CELL",             # always CELL for this layout
+    "cellId": "<id>",           # the cell to render here
+    "sharedFilterId": None,
+    "height": None,             # auto-fit
+    "showLabel": True,          # show the cellLabel above the cell
+    "explorable": None,
+}
+```
+
+Use exactly these keys with exactly these defaults unless you have a specific UI
+need. Hex's parser is sensitive to missing keys.

package/skills/metabase-to-hex/scripts/audit_vars.sh

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+# Audit every Jinja variable referenced in the SQL cells of a migration.
+# Use this to cross-check against the project's defined Input cells before importing.
+# A variable referenced in SQL but missing from inputs → "Undefined variable(s)" at run time.
+#
+# Usage:
+#   audit_vars.sh <cells_dir>
+set -euo pipefail
+
+DIR="${1:-./hex_cells}"
+
+echo "=== Jinja variables per cell in $DIR ==="
+for f in "$DIR"/*.sql; do
+  vars=$(grep -oE '\{[%{][- ]*(if +[a-z_]+|[a-z_]+) [- ]*[%}]\}' "$f" 2>/dev/null \
+         | grep -oE '[a-z_]+' \
+         | grep -v -E '^(if|else|elif|endif|endfor|for|in)$' \
+         | sort -u | tr '\n' ',' | sed 's/,$//')
+  echo "$(basename "$f")  →  ${vars:-(none)}"
+done
+
+echo
+echo "=== Union of all referenced vars (this must be a subset of the project's Input names) ==="
+grep -rohE '\{[%{][- ]*(if +[a-z_]+|[a-z_]+) [- ]*[%}]\}' "$DIR"/*.sql 2>/dev/null \
+  | grep -oE '[a-z_]+' \
+  | grep -v -E '^(if|else|elif|endif|endfor|for|in)$' \
+  | sort -u

package/skills/metabase-to-hex/scripts/build_layout.py

@@ -0,0 +1,227 @@
+#!/usr/bin/env python3
+"""
+YAML round-trip helper for a Hex project: adds Input cells, Markdown cells,
+and an appLayout with per-tab input bars matching the Metabase parameter mappings.
+
+This is a TEMPLATE — copy and customize the constants at the top for each migration.
+
+Workflow:
+  hex project export <project_id> -o exported.yaml
+  python3 build_layout.py            # writes import_ready.yaml
+  hex project import import_ready.yaml
+
+Inputs:
+  exported.yaml                      — fresh Hex export with SQL cells already created
+  dashboard_<id>.json                — Metabase dashboard JSON (for layout order + text cards)
+"""
+import json
+import os
+import sys
+import time
+import uuid
+from pathlib import Path
+
+import yaml
+
+# ---------- CONFIGURE PER MIGRATION ----------
+
+WORKDIR = Path("/home/alex/pii-migrations/dashboard_<ID>")
+INPUT_YAML = WORKDIR / "artifacts/exported.yaml"
+OUTPUT_YAML = WORKDIR / "artifacts/import_ready.yaml"
+DASHBOARD_JSON = WORKDIR / "dashboard_<ID>.json"
+
+# One entry per Metabase tab — order here is the order in the Hex App view
+TABS = [
+    # {"mb_tab_id": 91,  "name": "Main"},
+    # ...
+]
+
+# For each tab, the input slugs that tab's cards use (mirrors Metabase
+# parameter_mappings). Tab inputs render side-by-side in the first row of that tab.
+TAB_INPUTS = {
+    # 91: ["shift_id", "hcp_id", "facility_id"],
+    # ...
+}
+
+# card_id -> exact cellLabel as already created via `hex cell create -l <label>`
+CARD_LABEL = {
+    # 22130: "App Shiftlogs Stg",
+    # ...
+}
+
+# Inputs to create. The `name` is the Jinja variable; `label` is the UI label.
+INPUTS = [
+    # {"name": "shift_id",    "label": "Shift ID",    "default": ""},
+    # ...
+]
+
+# ---------- END CONFIGURE ----------
+
+
+def uuidv7() -> str:
+    """Generate a UUID v7 — timestamp-prefixed, matches what Hex's export uses."""
+    ts_ms = int(time.time() * 1000)
+    rand = os.urandom(10)
+    b = bytearray(16)
+    b[0] = (ts_ms >> 40) & 0xFF
+    b[1] = (ts_ms >> 32) & 0xFF
+    b[2] = (ts_ms >> 24) & 0xFF
+    b[3] = (ts_ms >> 16) & 0xFF
+    b[4] = (ts_ms >> 8) & 0xFF
+    b[5] = ts_ms & 0xFF
+    b[6] = (0x70 | (rand[0] & 0x0F)) & 0xFF  # version 7
+    b[7] = rand[1]
+    b[8] = (0x80 | (rand[2] & 0x3F)) & 0xFF  # RFC variant
+    b[9:16] = rand[3:10]
+    return str(uuid.UUID(bytes=bytes(b)))
+
+
+def make_input_cell(input_def):
+    cell_id = uuidv7()
+    return cell_id, {
+        "cellType": "INPUT",
+        "cellId": cell_id,
+        "cellLabel": input_def["label"],
+        "config": {
+            "inputType": "TEXT_INPUT",
+            "name": input_def["name"],
+            "outputType": "STRING",
+            "options": None,            # REQUIRED — omitting it = "malformed" import
+            "defaultValue": input_def.get("default", ""),
+        },
+    }
+
+
+def make_markdown_cell(text):
+    cell_id = uuidv7()
+    return cell_id, {
+        "cellType": "MARKDOWN",
+        "cellId": cell_id,
+        "config": {"source": text},
+    }
+
+
+def cell_element(cell_id, show_source=False, show_label=True):
+    """Element shape for appLayout. Use exactly this — Hex's parser is picky."""
+    return {
+        "showSource": show_source,
+        "hideOutput": False,
+        "type": "CELL",
+        "cellId": cell_id,
+        "sharedFilterId": None,
+        "height": None,
+        "showLabel": show_label,
+        "explorable": None,
+    }
+
+
+def main():
+    with open(INPUT_YAML) as f:
+        doc = yaml.safe_load(f)
+    with open(DASHBOARD_JSON) as f:
+        dashboard = json.load(f)
+
+    # Existing SQL cells: build cellLabel -> cellId map
+    label_to_id = {c["cellLabel"]: c["cellId"] for c in doc.get("cells", []) if c.get("cellLabel")}
+    card_to_cell = {cid: label_to_id[lbl] for cid, lbl in CARD_LABEL.items() if lbl in label_to_id}
+    missing = [cid for cid in CARD_LABEL if cid not in card_to_cell]
+    if missing:
+        print(f"WARN: no Hex cell found for cards: {missing}", file=sys.stderr)
+
+    # Build dashcards by tab (with row/col positions) for ordering markdown vs SQL
+    pid2slug = {p["id"]: p.get("slug") for p in dashboard.get("parameters", [])}
+    dashcards_by_tab = {t["mb_tab_id"]: [] for t in TABS}
+    for dc in dashboard.get("dashcards", []):
+        tab_id = dc.get("dashboard_tab_id")
+        if tab_id not in dashcards_by_tab:
+            continue
+        card = dc.get("card") or {}
+        cid = card.get("id")
+        dashcards_by_tab[tab_id].append({
+            "kind": "query" if cid else "text",
+            "card_id": cid,
+            "row": dc.get("row") or 0,
+            "col": dc.get("col") or 0,
+            "text": (dc.get("visualization_settings") or {}).get("text", "") if not cid else None,
+        })
+    for tab_id in dashcards_by_tab:
+        dashcards_by_tab[tab_id].sort(key=lambda d: (d["row"], d["col"]))
+
+    # Create INPUT cells (one per slug in INPUTS)
+    new_cells = []
+    input_name_to_cellid = {}
+    for inp in INPUTS:
+        cid, cell = make_input_cell(inp)
+        new_cells.append(cell)
+        input_name_to_cellid[inp["name"]] = cid
+
+    # Create MARKDOWN cells (one per text card)
+    md_cells_by_tab = {t["mb_tab_id"]: [] for t in TABS}
+    for tab_id, cards in dashcards_by_tab.items():
+        for c in cards:
+            if c["kind"] == "text":
+                cid, cell = make_markdown_cell(c["text"])
+                new_cells.append(cell)
+                md_cells_by_tab[tab_id].append({"row": c["row"], "cell_id": cid})
+
+    doc["cells"].extend(new_cells)
+
+    # Build appLayout.tabs
+    layout_tabs = []
+    for tab_meta in TABS:
+        mb_id = tab_meta["mb_tab_id"]
+        rows = []
+
+        # Top row: this tab's input cells side-by-side
+        input_slugs = TAB_INPUTS.get(mb_id, [])
+        if input_slugs:
+            n = len(input_slugs)
+            span = 120 // n
+            cols = []
+            for i, slug in enumerate(input_slugs):
+                start = i * span
+                end = start + span if i < n - 1 else 120
+                cols.append({
+                    "start": start, "end": end,
+                    "elements": [cell_element(input_name_to_cellid[slug])],
+                })
+            rows.append({"columns": cols})
+
+        # Body: markdown + SQL outputs in dashcard order, full-width
+        body_items = []
+        for c in dashcards_by_tab[mb_id]:
+            if c["kind"] == "query" and c["card_id"] in card_to_cell:
+                body_items.append((c["row"], card_to_cell[c["card_id"]]))
+            elif c["kind"] == "text":
+                md = next((m for m in md_cells_by_tab[mb_id] if m["row"] == c["row"]), None)
+                if md:
+                    body_items.append((c["row"], md["cell_id"]))
+        body_items.sort(key=lambda x: x[0])
+        for _, cid in body_items:
+            rows.append({"columns": [{"start": 0, "end": 120,
+                                      "elements": [cell_element(cid)]}]})
+
+        layout_tabs.append({"name": tab_meta["name"], "rows": rows})
+
+    app_layout = doc.setdefault("appLayout", {})
+    app_layout["tabs"] = layout_tabs
+    app_layout["fullWidth"] = True
+
+    # CRITICAL: sort cells so INPUT comes before MARKDOWN before SQL.
+    # Otherwise SQL cells produce "Undefined variable(s)" at run time.
+    priority = {"INPUT": 0, "MARKDOWN": 1, "SQL": 2}
+    doc["cells"].sort(key=lambda c: priority.get(c.get("cellType"), 3))
+
+    with open(OUTPUT_YAML, "w") as f:
+        # allow_unicode preserves em-dashes; width=4096 prevents line wrapping.
+        # Hex's YAML parser breaks on both if these aren't set.
+        yaml.safe_dump(doc, f, allow_unicode=True, width=4096, sort_keys=False)
+
+    print(f"Wrote {OUTPUT_YAML}")
+    print(f"  cells total: {len(doc['cells'])}")
+    print(f"  layout tabs: {len(doc['appLayout']['tabs'])}")
+    print(f"  cards mapped: {len(card_to_cell)}/{len(CARD_LABEL)}")
+
+
+if __name__ == "__main__":
+    main()

package/skills/metabase-to-hex/scripts/create_cells.sh.tmpl

@@ -0,0 +1,41 @@
+#!/usr/bin/env bash
+# Template — copy and edit per migration.
+# Creates SQL cells in a Hex project, one per .sql file in CELLS_DIR.
+# Logs each create response to LOG.
+set -euo pipefail
+
+PROJECT_ID="<paste-from-hex-project-create>"
+CONN_ID="530b70b8-b300-43c9-9b3e-e4b98ded0379"  # snowflake analytics
+
+CELLS_DIR="/home/alex/pii-migrations/dashboard_<ID>/hex_cells"
+LOG="/home/alex/pii-migrations/dashboard_<ID>/artifacts/cell_create_log.jsonl"
+> "$LOG"
+
+# filename → (label, output_dataframe_slug)
+# Label must match what the build_layout.py CARD_LABEL map expects.
+declare -A LABELS=(
+  # ["22130_App Shiftlogs Stg.sql"]="App Shiftlogs Stg"
+  # ...
+)
+declare -A DFS=(
+  # ["22130_App Shiftlogs Stg.sql"]="shift_logs"
+  # ...
+)
+
+for f in "$CELLS_DIR"/*.sql; do
+  base=$(basename "$f")
+  label="${LABELS[$base]:-$base}"
+  df="${DFS[$base]:-result}"
+  echo "→ Creating: $label  (df=$df)"
+  src=$(cat "$f")
+  result=$(hex cell create "$PROJECT_ID" \
+    -t sql \
+    -s "$src" \
+    -l "$label" \
+    --data-connection-id "$CONN_ID" \
+    --output-dataframe "$df" \
+    --json 2>&1)
+  echo "$base|$label|$df|$result" >> "$LOG"
+done
+
+echo "Done. Log: $LOG"

package/skills/metabase-to-hex/scripts/inventory.py

@@ -0,0 +1,120 @@
+#!/usr/bin/env python3
+"""
+Parse a saved Metabase dashboard JSON into a structured inventory.
+
+Usage:
+  python3 inventory.py <path/to/dashboard_<id>.json>
+
+Prints:
+  - Tab list (id, name, position)
+  - Dashboard parameters (slug, name, type, default)
+  - Per-card metadata (id, name, tab, viz type, query type, source table, parameter slugs)
+  - Text/instruction cards with content preview
+
+Also writes:
+  - query_cards.json  — list of dicts, one per query card
+  - text_cards.json   — list of dicts, one per text card
+"""
+import json
+import sys
+from pathlib import Path
+
+
+def main(path_str):
+    path = Path(path_str)
+    with open(path) as f:
+        d = json.load(f)
+
+    out_dir = path.parent
+
+    tabs = {t["id"]: t for t in d.get("tabs", [])}
+    print("=== TABS ===")
+    if tabs:
+        for tid, t in sorted(tabs.items(), key=lambda x: x[1].get("position", 0)):
+            print(f"  tab {tid}: {t['name']} (pos={t.get('position')})")
+    else:
+        print("  (single page — no tabs)")
+
+    print("\n=== DASHBOARD PARAMETERS ===")
+    pid2slug = {}
+    for p in d.get("parameters", []):
+        slug = p.get("slug")
+        pid2slug[p["id"]] = slug
+        print(f"  {slug}: name='{p.get('name')}' type={p.get('type')} default={p.get('default')}")
+
+    print("\n=== CARDS ===")
+    query_cards = []
+    text_cards = []
+    for dc in d.get("dashcards", []):
+        card = dc.get("card") or {}
+        cid = card.get("id")
+        tab_id = dc.get("dashboard_tab_id")
+        tab_name = tabs.get(tab_id, {}).get("name", "(no tabs)")
+        param_slugs = [pid2slug.get(m.get("parameter_id"), m.get("parameter_id"))
+                       for m in (dc.get("parameter_mappings") or [])]
+        row, col = dc.get("row") or 0, dc.get("col") or 0
+        size_x, size_y = dc.get("size_x"), dc.get("size_y")
+
+        if not cid:
+            text = (dc.get("visualization_settings") or {}).get("text", "")
+            text_cards.append({
+                "tab_id": tab_id, "tab_name": tab_name,
+                "row": row, "col": col, "size_x": size_x, "size_y": size_y,
+                "text": text,
+            })
+            continue
+
+        dq = card.get("dataset_query", {}) or {}
+        qtype = dq.get("type")
+        native_sql = dq.get("native", {}).get("query") if qtype == "native" else None
+        source_table = dq.get("query", {}).get("source-table") if qtype == "query" else None
+
+        query_cards.append({
+            "cid": cid,
+            "name": card.get("name"),
+            "tab_id": tab_id,
+            "tab_name": tab_name,
+            "display": card.get("display"),
+            "qtype": qtype,
+            "native_sql_len": len(native_sql) if native_sql else 0,
+            "source_table_id": source_table,
+            "param_slugs": param_slugs,
+            "row": row, "col": col, "size_x": size_x, "size_y": size_y,
+        })
+
+    # Sort by tab then row/col
+    tab_pos = {t["id"]: t.get("position", 0) for t in d.get("tabs", [])}
+    query_cards.sort(key=lambda c: (tab_pos.get(c["tab_id"], 0), c["row"], c["col"]))
+    text_cards.sort(key=lambda c: (tab_pos.get(c["tab_id"], 0), c["row"], c["col"]))
+
+    for c in query_cards:
+        kind = f"native(len={c['native_sql_len']})" if c["qtype"] == "native" else f"mbql(src_table={c['source_table_id']})"
+        display = c["display"] or ""
+        print(f"  {c['cid']:>6}  tab={c['tab_name']:40s}  {display:8s}  {kind:30s}  params={c['param_slugs']}  -- {c['name']}")
+    for c in text_cards:
+        snippet = c["text"].replace("\n", " ")[:80]
+        print(f"  [TEXT]  tab={c['tab_name']:40s}  r={c['row']} c={c['col']}  -- {snippet}")
+
+    # Summary
+    print("\n=== SUMMARY ===")
+    print(f"  {len(query_cards)} query cards, {len(text_cards)} text cards across {len(tabs) or 1} tab(s)")
+    per_tab = {}
+    for c in query_cards + text_cards:
+        per_tab.setdefault(c["tab_name"], []).append(c)
+    for name, cards in per_tab.items():
+        q = sum(1 for c in cards if "cid" in c)
+        t = len(cards) - q
+        print(f"    {name:40s}  {q} query + {t} text")
+
+    with open(out_dir / "query_cards.json", "w") as f:
+        json.dump(query_cards, f, indent=2)
+    with open(out_dir / "text_cards.json", "w") as f:
+        json.dump(text_cards, f, indent=2)
+    print(f"\nWrote {out_dir/'query_cards.json'} and {out_dir/'text_cards.json'}")
+
+
+if __name__ == "__main__":
+    if len(sys.argv) < 2:
+        print(__doc__)
+        sys.exit(1)
+    main(sys.argv[1])