@sitar_fiercer4c/skills 0.1.0

package/skills/backend-code-review/scripts/verify_citations.py

@@ -0,0 +1,201 @@
+#!/usr/bin/env python3
+"""Resolve every file:LINE citation in a review against the source tree.
+
+Prints the real source slice back for each citation so the claim riding on it can be
+checked, not just the line number, and flags three failure modes:
+
+  NOT-FOUND            path does not resolve, or the line is past end of file
+  AMBIGUOUS            a bare filename matches more than one file in the tree
+  TRUNCATED-CONSTRUCT  a cited range ends mid-construct (braces unbalanced across it),
+                       so anything the finding claims is absent may sit just past it
+
+Usage:
+  python3 verify_citations.py REPORT.md [REPORT.md ...] --root <backend>
+  python3 verify_citations.py REPORT.md --root <backend> --problems   # flagged rows only
+"""
+
+import argparse
+import os
+import re
+import sys
+from collections import defaultdict
+
+CITATION = re.compile(
+    r"(?<![\w/.])"
+    r"((?:[A-Za-z0-9_.\-]+/)*[A-Za-z0-9_.\-]+\.(?:js|cjs|mjs|jsx|ts|tsx|json|env|yml|yaml))"
+    r":(\d+)(?:\s*[-–—]\s*(\d+))?"
+)
+
+SKIP_DIRS = {"node_modules", ".git", "dist", "build", "coverage", "__pycache__", ".next"}
+CODE_EXT = (".js", ".cjs", ".mjs", ".jsx", ".ts", ".tsx")
+
+# A finding that asserts something is ABSENT is only checkable over a complete construct: if
+# the cited range stops mid-function, the thing claimed missing may sit on the next line. On a
+# positive claim, citing a fragment is normal, so the same imbalance is not worth reporting.
+NEGATION = re.compile(
+    r"\b(?:no|never|lacks?|lacking|missing|absent|without|none|nothing|un(?:guarded|validated"
+    r"|checked|handled|caught)|do(?:es)?\s+not|doesn't|is\s+not|are\s+not|fails?\s+to"
+    r"|neither|nor|omits?|omitted|skips?|bypasses)\b",
+    re.I,
+)
+
+
+def index_tree(root):
+    """Map every relative path, and every path suffix, to the files it can name."""
+    by_suffix = defaultdict(set)
+    for dirpath, dirnames, filenames in os.walk(root):
+        dirnames[:] = [d for d in dirnames if d not in SKIP_DIRS]
+        for fn in filenames:
+            full = os.path.join(dirpath, fn)
+            relpath = os.path.relpath(full, root)
+            parts = relpath.split(os.sep)
+            for i in range(len(parts)):
+                by_suffix["/".join(parts[i:])].add(relpath)
+    return by_suffix
+
+
+def resolve(cited, by_suffix):
+    """Return (relpath, None) or (None, reason). Citations are usually partial paths."""
+    key = cited.lstrip("./")
+    hits = by_suffix.get(key)
+    if not hits:
+        return None, "NOT-FOUND"
+    if len(hits) > 1:
+        # An exact whole-path match beats suffix matches.
+        exact = {h for h in hits if h.replace(os.sep, "/") == key}
+        if len(exact) == 1:
+            return exact.pop(), None
+        return None, "AMBIGUOUS (" + ", ".join(sorted(hits)) + ")"
+    return next(iter(hits)), None
+
+
+def strip_noncode(text):
+    """Blank out strings, template literals and comments so brace counting means something."""
+    out = []
+    i, n = 0, len(text)
+    while i < n:
+        c = text[i]
+        if c == "/" and i + 1 < n and text[i + 1] == "/":
+            while i < n and text[i] != "\n":
+                i += 1
+        elif c == "/" and i + 1 < n and text[i + 1] == "*":
+            i += 2
+            while i + 1 < n and not (text[i] == "*" and text[i + 1] == "/"):
+                if text[i] == "\n":
+                    out.append("\n")
+                i += 1
+            i += 2
+        elif c in "\"'`":
+            quote = c
+            i += 1
+            while i < n and text[i] != quote:
+                if text[i] == "\\":
+                    i += 1
+                elif text[i] == "\n":
+                    out.append("\n")
+                i += 1
+            i += 1
+        else:
+            out.append(c)
+            i += 1
+    return "".join(out)
+
+
+def brace_delta(slice_text):
+    code = strip_noncode(slice_text)
+    return (
+        code.count("{") - code.count("}"),
+        code.count("(") - code.count(")"),
+        code.count("[") - code.count("]"),
+    )
+
+
+def check(report, root, by_suffix, problems_only):
+    with open(report, encoding="utf-8", errors="replace") as fh:
+        report_lines = fh.readlines()
+
+    seen = set()
+    rows = []
+    for lineno, text in enumerate(report_lines, 1):
+        for m in CITATION.finditer(text):
+            cited, start, end = m.group(1), int(m.group(2)), m.group(3)
+            end = int(end) if end else start
+            key = (cited, start, end)
+            if key in seen:
+                continue
+            seen.add(key)
+            rows.append((lineno, cited, start, end, bool(NEGATION.search(text))))
+
+    results = []
+    for report_line, cited, start, end, negated in rows:
+        relpath, reason = resolve(cited, by_suffix)
+        if reason:
+            results.append((report_line, cited, start, end, relpath, [], [reason]))
+            continue
+
+        with open(os.path.join(root, relpath), encoding="utf-8", errors="replace") as fh:
+            src = fh.readlines()
+
+        flags = []
+        if start < 1 or start > len(src):
+            flags.append(f"NOT-FOUND (file has {len(src)} lines)")
+            results.append((report_line, cited, start, end, relpath, [], flags))
+            continue
+        if end > len(src):
+            flags.append(f"RANGE-PAST-EOF (file has {len(src)} lines)")
+
+        body = src[start - 1:min(end, len(src))]
+        if negated and end > start and relpath.endswith(CODE_EXT):
+            unbal = [f"{n}{d:+d}" for n, d in zip(("{}", "()", "[]"), brace_delta("".join(body))) if d]
+            if unbal:
+                flags.append(
+                    "TRUNCATED-CONSTRUCT (" + ", ".join(unbal) + ") — this row claims an "
+                    "absence, so the range must span the whole construct"
+                )
+
+        results.append((report_line, cited, start, end, relpath, body, flags))
+
+    return results, seen
+
+
+def render(report, results, problems_only):
+    print(f"\n=== {os.path.basename(report)} ===")
+    bad = 0
+    for report_line, cited, start, end, relpath, body, flags in results:
+        if flags:
+            bad += 1
+        elif problems_only:
+            continue
+
+        span = f"{start}" if start == end else f"{start}-{end}"
+        target = f" -> {relpath}" if relpath else ""
+        print(f"\n[{'FLAG' if flags else 'OK'}] {cited}:{span}{target}  (report line {report_line})")
+        for f in flags:
+            print(f"    !! {f}")
+        for i, src_line in enumerate(body, start):
+            print(f"    {i:>5} | {src_line.rstrip()}")
+    return bad
+
+
+def main():
+    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("reports", nargs="+")
+    ap.add_argument("--root", required=True, help="backend root the citations are relative to")
+    ap.add_argument("--problems", action="store_true", help="print only flagged citations")
+    args = ap.parse_args()
+
+    root = os.path.abspath(args.root)
+    by_suffix = index_tree(root)
+
+    total_bad = total = 0
+    for report in args.reports:
+        results, seen = check(report, root, by_suffix, args.problems)
+        total_bad += render(report, results, args.problems)
+        total += len(seen)
+
+    print(f"\n{'=' * 60}\n{total} citations checked, {total_bad} flagged.")
+    return 1 if total_bad else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/be-brief/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: be-brief
+description: User invoked only
+---
+
+# Intent
+User is trying to understand OR problem solve something on a high level
+
+# Brief
+To make an answer brief, write it as a 30-60 word sentence. For technical things, use 10-15 word bullet points.
+
+# User tech stack
+## Good proficiency
+Python, SQL, Linux, relational database, NoSQL database, System design, data flow, ETL pipeline
+## Medium proficiency
+Spark, Java, Bash, Infrastructure as Code, AWS, Claude code, CLI
+## Bad proficiency
+Frontend, Full stack, JavaScript, Node, NPM, Vercel, Render

package/skills/clarke-list-excel/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: clarke-list-excel
+description: Use and invoke
+---
+
+# Clarke List Excel Skill
+
+## Goal
+
+Extract Clarke XLSX → JSON/Markdown → map images to Part No → upload to S3 → upsert MongoDB `clarke`.
+
+## Use When
+
+Use for Clarke price-list extraction, re-import, refresh, product/image extraction, S3 upload, or MongoDB loading.
+
+## Workflow
+
+1. Read values/images with openpyxl and table/image spans with Datalab.
+2. Detect products by valid Part No; identify category/sub-category headings from formatting.
+3. Map each image to every product row covered by its Datalab `Picture` bbox.
+4. Stop spans at headings; for overlapping spans, nearest anchor above wins.
+5. Use nearest-row matching only within 3 rows when no span match exists.
+6. Upload valid images first, then upsert products into MongoDB.
+7. Validate the database write and report all important counts/issues.
+
+## Commands
+
+```bash
+python scripts/run_all.py "<xlsx>" --out-dir /home/dev/workspaces/murtaza-workspaces/clarke-products
+python scripts/clarke_extract.py "<xlsx>" --out-dir <dir>
+python scripts/load_clarke.py <dir>/clarke-products.json
+```
+
+## Rules
+
+* Datalab = image coordinates/spans; openpyxl = values and original image bytes.
+* Read columns by position, never by printed header names.
+* Store images at `products/catalog/clarke/<part-no>.<ext>` and upsert by unique `partNo`.
+* Preserve `supplier: "Clarke"` and `source`; run `--check` before writes.
+* Never use grid indexes/equal row bands, treat headings as products, or silently drop rows/issues.
+* Keep duplicates, missing prices, unmatched images, held-back rows and unsupported formats visible.
+* EMF uploads require `--upload-unrenderable`; re-runs must be idempotent.
+* Never overwrite another catalogue on collection clashes.
+
+## Validation
+
+Report product/duplicate/held-back counts, image coverage, span vs nearest matches, overridden/unmatched images, truncated spans, missing prices, unsupported formats, and Datalab/openpyxl anchor agreement.
+
+## Wrong Tool
+
+UKEN PDF → `uken-data-export`; other PDFs → `pdf-to-json`; unknown/general spreadsheets → `datalab-api`.

package/skills/clarke-list-excel/references/output-schema.md

@@ -0,0 +1,125 @@
+# What the files hold
+
+Read this when you need a specific field — what it means, when it is null, and
+which numbers are safe to quote. Figures are from the 2023 Clarke list.
+
+## `clarke-products.json`
+
+```
+source     where it came from
+summary    counts, and everything that did not come through
+products   one entry per product row, in sheet order
+rowsHeldBack  rows that looked like products and were not
+```
+
+### `source`
+
+| field | example | note |
+|---|---|---|
+| `file` | `CLARKE PRICE LIST-2023.xlsx` | |
+| `path` | absolute path | what was actually read |
+| `sheet` | `Sheet1` | first worksheet unless `--sheet` said otherwise |
+| `headerRow` | `8` | the row printing `PART NO`; rows above are a title block |
+| `tableRange` | `A5:G2035` | Datalab's view of the table's extent, null with `--no-datalab` |
+| `rows`, `columns` | `2035`, `8` | the sheet's extent, not the table's |
+
+### `summary`
+
+| field | 2023 file | what it tells you |
+|---|---|---|
+| `products` | 1558 | rows that parsed as products. **Not** the document count — see `duplicate_part_numbers` |
+| `categories` | 26 | merged 14pt headings |
+| `subCategories` | 193 | unmerged 10pt headings |
+| `image_placements` | 249 | photos in the sheet, including the logo |
+| `products_with_image` | 986 | every product a photo's span covers, not just the first |
+| `products_without_image` | 572 | the document, not a failure |
+| `distinct_images` | 204 | far fewer than 986: one photo illustrates a whole group |
+| `media_files_in_workbook` | 216 | everything in `xl/media`, used or not |
+| `images_matched_by_span` | 986 | confident: the photo's own extent covered the row |
+| `images_matched_by_nearest` | 0 | inferred: it covered no product row. Any rise is a warning |
+| `images_spanning_multiple_products` | 177 | placements attached to more than one product |
+| `products_sharing_a_spanned_image` | 926 | products carrying a group photo rather than their own |
+| `spans_truncated_at_heading` | 32 | spans cut at a sub-category row instead of running into the next group |
+| `images_overridden` | 11 | placements every row of which a nearer-anchored photo won |
+| `images_unmatched` | 1 | attached to nothing. One is expected — the row-1 logo |
+| `unsupported_image_formats` | `["emf"]` | present in the workbook; not uploaded by default |
+| `products_without_price` | 1 | kept with a null price |
+| `rows_held_back` | 2 | see `rowsHeldBack` |
+| `duplicate_part_numbers` | `{HS20C: [420, 1150], HS24C: [421, 1153]}` | part number → the rows printing it. These collapse on upsert |
+| `cross_check` | see below | the completeness check |
+
+### `summary.cross_check`
+
+Datalab and openpyxl each report where every photo is anchored, by different
+code paths. This is where they are compared.
+
+| field | 2023 file | |
+|---|---|---|
+| `ran` | `true` | false under `--no-datalab`, and then nothing below exists |
+| `datalab_pictures` | 249 | |
+| `openpyxl_placements` | 249 | |
+| `anchor_rows_agree` | `true` | **the number to quote.** False means photos may be on the wrong products |
+| `rows_only_in_datalab` | `[]` | photos openpyxl could not read — likely a format it drops |
+| `rows_only_in_openpyxl` | `[]` | photos Datalab did not report |
+| `table_range`, `table_blocks` | `A5:G2035`, 1 | more than one table block means the sheet segmented unexpectedly |
+
+### `products[]`
+
+| field | example | null when |
+|---|---|---|
+| `partNo` | `CP6CL` | never — it is the key |
+| `partNoRaw` | `CP6CL` | never; differs from `partNo` only where the sheet printed odd spacing |
+| `description` | `COMBINATION PLIERS 6"` | never — a row without one is held back |
+| `category` | `PLIERS` | products appearing before any heading |
+| `subCategory` | `COMBINATION PLIER` | the category has no sub-headings |
+| `pktQty`, `ctnQty` | `6`, `60` | the cell is blank or not numeric |
+| `price` | `8.0` | the sheet printed no price (1 row) |
+| `priceLabel` | `TRADER Price` | never — the tier name, kept so the number is not bare |
+| `currency` | `AED` | never |
+| `supplier` | `Clarke` | never — this is what separates the two catalogues sharing the collection |
+| `sheetRow` | `14` | never — the row in the *sheet*, not in Datalab's grid |
+| `imageSha256` | `760cd2a2…` | the product has no photo (572 of them) |
+| `imageFormat` | `jpeg` | as above |
+| `imageMatch` | `span` \| `nearest` | as above. `nearest` is inference — see SKILL.md |
+| `imageAnchorRow` | `14` | as above. The top of the photo, which may be many rows above `sheetRow` |
+| `imageSpanRows` | `[166, 185]` | as above. The rows the photo covers; every product in them carries it |
+| `imageShared` | `true` | absent unless the photo covers more than one product — a group photo |
+
+### `rowsHeldBack[]`
+
+`{row, reason, partNo, description}`. Two reasons occur: `missing part number
+or description`, and `part number is not code-like` — prose in column A, which
+is a heading that lost its formatting. These are listed rather than dropped
+because the count of what did not load is the number worth seeing.
+
+## `images/`
+
+One file per distinct photo, named `<sha256>.<format>`, written beside the
+JSON. These are the **original bytes out of the xlsx zip**, not Datalab's
+re-encodings, so they are reproducible across runs. `load_clarke.py` reads this
+directory; stage one rewrites it, so re-run the two together.
+
+## `clarke-products.md`
+
+The same data rendered to read: a heading per category breadcrumb, then a table
+of part number, description, pkt, ctn, price and the first 8 characters of the
+photo hash. For eyeballing whether the grouping and the photo mapping came out
+right — the JSON is what anything downstream should read.
+
+## The MongoDB document
+
+`clarke`, upserted on `partNo` (unique index). Same fields as
+`products[]` minus the image internals, plus:
+
+| field | example | |
+|---|---|---|
+| `source` | `CLARKE PRICE LIST-2023.xlsx` | which file this came from |
+| `imageKey` | `products/catalog/clarke/CP6CL.jpeg` | S3 key, no leading slash; null when the product has no photo |
+
+| `imageShared` | `true` | the photo covers several products; this is the group's picture, not this part's alone |
+
+`imageSha256`, `imageFormat`, `imageAnchorRow` and `imageSpanRows` stay in the
+JSON — they are extraction diagnostics, not product data. `imageMatch` and
+`imageShared` are carried through, because a downstream reader should be able
+to tell an inferred photo from a confident one, and a group photo from a
+product's own.

package/skills/clarke-list-excel/scripts/clarke_common.py

@@ -0,0 +1,251 @@
+#!/usr/bin/env python3
+"""Shared plumbing for the Clarke export: credentials, the Datalab call, the workbook.
+
+Two readers, deliberately. Datalab segments the sheet and reports where the
+pictures are anchored; openpyxl reads the cells. Neither is redundant:
+
+Datalab's table HTML drops empty rows, so its grid is 1,783 rows against the
+sheet's 2,031. Grid index is therefore *not* sheet row, and anything that maps
+pictures onto products through the grid drifts by hundreds of rows by the
+bottom of the file. openpyxl addresses cells by their real coordinates, so it
+is what the parser reads values from.
+
+What Datalab gives that openpyxl cannot is an independent opinion. Its Picture
+bboxes are cell coordinates on spreadsheets, and `floor(y0)` is the anchoring
+row — the same number openpyxl reports from the drawing anchor, arrived at
+through an entirely different code path. Agreement between the two is the
+completeness check this skill quotes, and it is worth more than either reader's
+own confidence.
+
+The credential search is a fixed default rather than a walk up from the input
+file, for the same reason as the sibling uken-data-export skill: the price list
+sits in the workspace root and the .env is in Backend/ of a different repo, so
+walking up finds nothing. Guessing a path and half-working is worse than saying
+plainly which file was read.
+"""
+
+import hashlib
+import json
+import os
+import time
+import zipfile
+from pathlib import Path
+
+DEFAULT_BASE_URL = "https://www.datalab.to/api/v1"
+POLL_SECONDS = 2
+POLL_ATTEMPTS = 300  # 10 minutes; a one-sheet workbook lands in well under one
+
+DEFAULT_ENV = Path(
+    "/home/dev/workspaces/murtaza-workspaces/murtaza-hotel-project/Backend/.env")
+
+XLSX_MIME = "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
+MIMES = {
+    ".xlsx": XLSX_MIME,
+    ".xlsm": "application/vnd.ms-excel.sheet.macroEnabled.12",
+    ".xls": "application/vnd.ms-excel",
+    ".ods": "application/vnd.oasis.opendocument.spreadsheet",
+    ".csv": "text/csv",
+}
+
+
+# ------------------------------------------------------------ credentials
+
+def load_env(explicit: str | None = None) -> tuple[dict, Path | None]:
+    """Return (values, path_read). Real environment variables always win.
+
+    Returning the path matters: every stage prints which .env it used, because
+    "1,558 products loaded" is not a useful sentence until you know which
+    cluster it wrote them to.
+    """
+    candidates = []
+    if explicit:
+        candidates.append(Path(explicit).expanduser())
+    elif os.environ.get("CLARKE_ENV_FILE"):
+        candidates.append(Path(os.environ["CLARKE_ENV_FILE"]).expanduser())
+    else:
+        candidates.append(DEFAULT_ENV)
+
+    values, used = {}, None
+    for path in candidates:
+        if not path.is_file():
+            continue
+        used = path
+        for line in path.read_text(errors="replace").splitlines():
+            line = line.strip()
+            if not line or line.startswith("#") or "=" not in line:
+                continue
+            key, value = line.split("=", 1)
+            values[key.strip()] = value.strip().strip('"').strip("'")
+        break
+
+    if explicit and used is None:
+        raise SystemExit(f"--env {explicit} does not exist")
+    return values, used
+
+
+def credential(values: dict, *keys: str) -> str | None:
+    """First of `keys` set in the real environment, else in the .env."""
+    for key in keys:
+        if os.environ.get(key):
+            return os.environ[key]
+    for key in keys:
+        if values.get(key):
+            return values[key]
+    return None
+
+
+def require(values: dict, *keys: str) -> str:
+    got = credential(values, *keys)
+    if not got:
+        raise SystemExit(
+            f"{keys[0]} not found. Set it in the environment or in the .env "
+            f"(default {DEFAULT_ENV}); point elsewhere with --env.")
+    return got
+
+
+# --------------------------------------------------------------- datalab
+
+def strip_images(node):
+    """Drop base64 payloads before caching.
+
+    On this workbook they are ~98% of the response and none of them are used:
+    the pictures uploaded to S3 are the original media out of the xlsx zip, not
+    Datalab's re-encodings. The `Picture` blocks themselves are kept, because
+    their bboxes are the cross-check.
+    """
+    if isinstance(node, dict):
+        node.pop("images", None)
+        for value in node.values():
+            strip_images(value)
+    elif isinstance(node, list):
+        for value in node:
+            strip_images(value)
+
+
+def convert(path: Path, key: str, cache_dir: Path, mode: str = "fast",
+            refresh: bool = False, base: str = DEFAULT_BASE_URL) -> dict:
+    """Submit the workbook to Datalab and poll until it finishes.
+
+    `mode` is `fast` because on spreadsheets it changes nothing — fast,
+    balanced and accurate return identical block trees at identical cost. The
+    sibling datalab-api skill documents that experiment.
+
+    Cached on the resolved path plus the options that change the request, so
+    re-running the parser is free. The conversion is the slow, paid and
+    non-deterministic part; the parse is none of those.
+    """
+    import requests
+
+    cache_dir.mkdir(parents=True, exist_ok=True)
+    digest = hashlib.sha256(
+        f"{path.resolve()}|{path.stat().st_size}|{mode}".encode()).hexdigest()[:10]
+    cached = cache_dir / f"{path.stem}.{mode}.{digest}.json"
+    if cached.is_file() and not refresh:
+        return json.loads(cached.read_text())
+
+    mime = MIMES.get(path.suffix.lower(), XLSX_MIME)
+    with path.open("rb") as fh:
+        response = requests.post(
+            f"{base}/convert",
+            headers={"X-API-Key": key},
+            files={"file": (path.name, fh, mime)},
+            data={"output_format": "json", "mode": mode},
+            timeout=300)
+    if response.status_code != 200:
+        raise SystemExit(f"Datalab rejected the upload: "
+                         f"{response.status_code} {response.text[:400]}")
+    check_url = response.json().get("request_check_url")
+    if not check_url:
+        raise SystemExit(f"no request_check_url in response: {response.text[:400]}")
+
+    for _ in range(POLL_ATTEMPTS):
+        time.sleep(POLL_SECONDS)
+        poll = requests.get(check_url, headers={"X-API-Key": key}, timeout=120).json()
+        if poll.get("status") == "complete":
+            if not poll.get("success", True):
+                raise SystemExit(f"Datalab failed: {poll.get('error')}")
+            strip_images(poll)
+            cached.write_text(json.dumps(poll))
+            return poll
+    raise SystemExit("Datalab did not finish within the polling window")
+
+
+def walk(node, out=None):
+    """Every block in the response, in reading order."""
+    out = [] if out is None else out
+    if isinstance(node, dict):
+        if "block_type" in node:
+            out.append(node)
+        for child in node.get("children") or []:
+            walk(child, out)
+    elif isinstance(node, list):
+        for child in node:
+            walk(child, out)
+    return out
+
+
+def picture_rows(response: dict) -> list[dict]:
+    """Datalab's opinion of where each picture sits, as 1-indexed sheet rows.
+
+    On spreadsheets a Picture bbox is [col0, row0, col1, row1] in *cell*
+    coordinates, where the integer part is the 1-indexed cell and the fraction
+    is the offset within it. `[1.74, 14.48, 2.69, 16.17]` is a photo anchored
+    in B14 hanging down into row 16.
+
+    Carrying the PDF convention here instead — pixels — puts every coordinate
+    out by three orders of magnitude, and the failure is quiet because the
+    numbers still look like plausible row indices.
+    """
+    out = []
+    for block in walk(response.get("json") or response):
+        if block.get("block_type") != "Picture":
+            continue
+        bbox = block.get("bbox") or []
+        if len(bbox) < 4:
+            continue
+        html = block.get("html") or ""
+        src = None
+        if 'src="' in html:
+            src = html.split('src="', 1)[1].split('"', 1)[0]
+        out.append({
+            "row_from": int(bbox[1]),
+            "row_to": int(bbox[3]),
+            "col": int(bbox[0]),
+            "src": src,
+        })
+    return out
+
+
+def table_blocks(response: dict) -> list[dict]:
+    """Table blocks with their cell range. Datalab sometimes types a plain
+    lead-in table as TableOfContents, so match that too."""
+    return [b for b in walk(response.get("json") or response)
+            if b.get("block_type") in ("Table", "TableOfContents")]
+
+
+def excel_range(bbox) -> str:
+    """[1, 5, 7, 2035] -> 'A5:G2035'. 1-indexed and inclusive."""
+    def column(index: int) -> str:
+        name = ""
+        while index > 0:
+            index, remainder = divmod(index - 1, 26)
+            name = chr(65 + remainder) + name
+        return name or "A"
+    c0, r0, c1, r1 = (int(v) for v in bbox[:4])
+    return f"{column(c0)}{r0}:{column(c1)}{r1}"
+
+
+# ----------------------------------------------------------- the workbook
+
+def media_index(path: Path) -> dict:
+    """Every file under xl/media, archive name -> bytes.
+
+    Read from the zip rather than through openpyxl because openpyxl silently
+    drops formats it cannot decode — this workbook holds one EMF, and openpyxl
+    warns and moves on. A picture missing from the upload because a library
+    could not parse it should be reported, not lost.
+    """
+    with zipfile.ZipFile(path) as archive:
+        return {name: archive.read(name)
+                for name in archive.namelist()
+                if name.startswith("xl/media/")}