shuttlecheck 0.4.0__tar.gz → 0.4.2__tar.gz

{shuttlecheck-0.4.0 → shuttlecheck-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: shuttlecheck
-Version: 0.4.0
+Version: 0.4.2
 Summary: Check media filenames, folder structure and deliverables against a written convention. Read-only.
 Author-email: MVRK Systems <hello@mvrk.systems>
 License: Proprietary — free to use, no redistribution

{shuttlecheck-0.4.0 → shuttlecheck-0.4.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "shuttlecheck"
-version = "0.4.0"
+version = "0.4.2"
 description = "Check media filenames, folder structure and deliverables against a written convention. Read-only."
 readme = { file = "PYPI.md", content-type = "text/markdown" }
 requires-python = ">=3.11"
@@ -71,4 +71,4 @@ packages = ["shuttlecheck"]
 # it is sent, so a build that cannot read it sends nothing at all. Both travel
 # inside the wheel.
 shuttlecheck = ["schema.json", "telemetry-v1.schema.json", "ui_assets/*",
-                "ui_assets/fonts/*"]
+                "ui_assets/fonts/*", "demo_convention.yaml"]

shuttlecheck-0.4.2/shuttlecheck/certificate.py

@@ -0,0 +1,110 @@
+"""The certificate a sealed drive carries.
+
+`_SPEC/README.txt` is for somebody who has never heard of any of this and
+opens a text file. `_SPEC/SEALED.html` is the same facts for everybody else:
+the page a post house double-clicks first. It opens in any browser, offline,
+with nothing fetched, and says what was sealed, against which rule, in what
+state, and how to prove it arrived intact without installing anything of ours.
+
+It is also the only thing this product puts in front of somebody who is not
+yet a customer, on a drive their own client sent them. So it is plain, exact
+and quietly made, and it does not sell.
+"""
+
+from __future__ import annotations
+
+import html
+
+
+def _esc(value) -> str:
+    return html.escape(str(value if value is not None else ""), quote=True)
+
+
+def render(*, folder: str, project: str, convention: str, sealed: str,
+           mhl_name: str, generation: int, algorithm: str, files: int,
+           size: str, errors, warnings, custody: str = "",
+           tool_version: str = "") -> str:
+    # `None` for both is a preview drawn before sealing: the conformance is
+    # measured when the drive is sealed, and is never shown as clean before.
+    preview = errors is None or warnings is None
+    clean = not preview and not errors and not warnings
+    state = ("Measured when the drive is sealed" if preview else
+             "On the rule" if clean else
+             f"{errors} error{'s' if errors != 1 else ''}, "
+             f"{warnings} warning{'s' if warnings != 1 else ''} when sealed")
+    ring = (f"ASC MHL · {algorithm.upper()} · {files} FILES · GENERATION "
+            f"{generation} · ")
+    rows = [
+        ("Drive", folder), ("Project", project), ("Convention", convention),
+        ("Sealed", sealed), ("Hash list", f"ascmhl/{mhl_name}"),
+        ("Generation", generation), ("Checksum", algorithm),
+        ("Files", files), ("Size", size), ("Conformance", state),
+    ]
+    if custody:
+        rows.append(("Custody", custody))
+    table = "\n".join(
+        f"<tr><th>{_esc(k)}</th><td>{_esc(v)}</td></tr>" for k, v in rows)
+    return f"""<!DOCTYPE html>
+<html lang="en"><head><meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>{'Not sealed yet' if preview else 'Sealed'}: {_esc(folder)}</title>
+<style>
+:root {{ --bg:#07142A; --panel:#0C1D38; --line:rgba(130,175,225,.2); --fg:#EAF2FB;
+  --fg2:#A9BCD3; --cyan:#34E7E3; --ok:#2FBF71; --warn:#FF9A5C; color-scheme: dark; }}
+* {{ box-sizing: border-box; -webkit-print-color-adjust: exact; print-color-adjust: exact; }}
+html {{ background: var(--bg); }}
+body {{ margin:0; background:var(--bg); color:var(--fg);
+  font:15px/1.55 system-ui,-apple-system,"Segoe UI",Roboto,sans-serif; }}
+main {{ max-width:880px; margin:0 auto; padding:48px 20px 64px; display:grid; gap:28px; }}
+.top {{ display:grid; grid-template-columns:220px 1fr; gap:28px; align-items:center; }}
+h1 {{ margin:0; font-size:40px; line-height:1.05; letter-spacing:-.5px; }}
+.sub {{ color:var(--fg2); margin:8px 0 0; }}
+.state {{ display:inline-block; margin-top:14px; padding:4px 12px; border-radius:999px;
+  border:1px solid currentColor; font-weight:600; font-size:13px;
+  color:{'var(--fg2)' if preview else 'var(--ok)' if clean else 'var(--warn)'}; }}
+table {{ width:100%; border-collapse:collapse; background:var(--panel);
+  border:1px solid var(--line); border-radius:12px; overflow:hidden; }}
+th, td {{ text-align:left; padding:10px 16px; border-top:1px solid var(--line); vertical-align:top; }}
+tr:first-child th, tr:first-child td {{ border-top:0; }}
+th {{ width:160px; color:var(--fg2); font-weight:500; }}
+td {{ font-family:ui-monospace,Menlo,Consolas,monospace; font-size:13.5px; word-break:break-all; }}
+h2 {{ font-size:18px; margin:0 0 8px; }}
+p {{ margin:0 0 10px; color:var(--fg2); max-width:68ch; }}
+code {{ font-family:ui-monospace,Menlo,Consolas,monospace; color:var(--fg); }}
+.ribbon {{ display:inline-block; margin:0 0 12px; padding:3px 10px; border-radius:6px;
+  background:var(--warn); color:#07142A; font-weight:700; font-size:12px; letter-spacing:.04em; text-transform:uppercase; }}
+footer {{ color:var(--fg2); font-size:13px; border-top:1px solid var(--line); padding-top:16px; }}
+@media (max-width:640px) {{ .top {{ grid-template-columns:1fr; }} }}
+/* Dark on paper too: the certificate is the brand a client's post house
+   sees, and a browser printing it drops backgrounds unless told not to. */
+@page {{ margin: 0; background: #07142A; }}
+@media print {{ html, body {{ background: var(--bg) !important; }} main {{ padding: 28px 32px; }}
+  table, section {{ break-inside: avoid; }} }}
+</style></head>
+<body><main>
+<div class="top">
+<svg viewBox="0 0 220 220" width="200" height="200" role="img" aria-label="Seal, generation {generation}">
+<defs><path id="r" d="M110 110 m -76 0 a 76 76 0 1 1 152 0 a 76 76 0 1 1 -152 0"/>
+<linearGradient id="g" x1="0" y1="1" x2="1" y2="0"><stop offset="0" stop-color="#0B7AC1"/>
+<stop offset=".6" stop-color="#19A3C8"/><stop offset="1" stop-color="#34E7E3"/></linearGradient></defs>
+<circle cx="110" cy="110" r="96" fill="none" stroke="url(#g)" stroke-width="9"/>
+<circle cx="110" cy="110" r="60" fill="none" stroke="var(--line)"/>
+<text font-size="9.5" fill="var(--fg2)" font-family="ui-monospace,Menlo,monospace"><textPath href="#r" textLength="470" lengthAdjust="spacing">{_esc(ring)}</textPath></text>
+<text x="110" y="102" text-anchor="middle" font-size="11" fill="var(--fg2)">generation</text>
+<text x="110" y="140" text-anchor="middle" font-size="40" font-weight="700" fill="var(--fg)">{_esc(generation)}</text>
+</svg>
+<div>{'<p class="ribbon">Preview. Nothing is sealed yet.</p>' if preview else ''}<h1>{'Ready to seal' if preview else 'Sealed'}: {_esc(folder)}</h1>
+<p class="sub">{'When this drive is sealed, every file on it is hashed into an ASC Media Hash List, and the naming convention it is held to travels with it.' if preview else 'Every file on this drive was hashed into an ASC Media Hash List when it was sealed, and the naming convention it was held to travels with it.'}</p>
+<span class="state">{_esc(state)}</span></div>
+</div>
+<table>{table}</table>
+<section><h2>Prove it arrived intact</h2>
+<p>Use whatever already reads ASC MHL: Pomfort MediaVerify, or the ASC's own <code>ascmhl</code> tool. The hash list in <code>ascmhl/</code> is plain XML and opens in any text editor.</p>
+<p>Or, with ShuttleCheck, free and with no account: <code>pip install shuttlecheck</code>, then <code>shuttlecheck verify .</code> from the folder holding <code>_SPEC</code>. It only reads; nothing is renamed, moved or deleted.</p>
+</section>
+<section><h2>What else is here</h2>
+<p><code>_SPEC/convention.yaml</code> is the naming convention this job follows, <code>_SPEC/report.txt</code> the conformance report as it stood when the drive left, and <code>_SPEC/README.txt</code> the same as this page in plain text.</p>
+</section>
+<footer>Sealed with ShuttleCheck{(' ' + _esc(tool_version)) if tool_version else ''} by MVRK Systems, mvrk.systems. Nothing on this page was fetched from anywhere.</footer>
+</main></body></html>
+"""

{shuttlecheck-0.4.0 → shuttlecheck-0.4.2}/shuttlecheck/checks.py

@@ -169,7 +169,7 @@ def check_structure(spec, dirs: list[str], files_by_dir: dict[str, list[str]],
                     rule="loose-file",
                     severity=spec.severity("loose-file", "warning"),
                     path=d or ".",
-                    message=(f"{count(len(names), 'file')} sit directly in a folder that should "
+                    message=(f"{count(len(names), 'file')} {'sits' if len(names) == 1 else 'sit'} directly in a folder that should "
                              f"contain only subfolders: {', '.join(sorted(names)[:4])}"
                              + (" ..." if len(names) > 4 else "")),
                     detail={"files": sorted(names)},

{shuttlecheck-0.4.0 → shuttlecheck-0.4.2}/shuttlecheck/cli.py

@@ -69,11 +69,17 @@ def build_parser() -> argparse.ArgumentParser:
     b.add_argument("--yes", action="store_true",
                    help="write it without printing the contents first")
 
-    u = sub.add_parser("ui", help="open the local app in a browser")
+    u = sub.add_parser("ui", help="open the local app in a browser, or in its own window")
     u.add_argument("root", nargs="?", help="folder to open on (optional)")
     u.add_argument("--port", type=int, default=8765)
     u.add_argument("--no-browser", action="store_true",
                    help="print the URL instead of opening it")
+    # What the packaged app does, available from a checkout. Without it a
+    # checkout can only ever show the tool as a tab, and the window is the one
+    # part of the product nobody sees until a build ships.
+    u.add_argument("--window", action="store_true",
+                   help="open in its own window (needs the [app] extra); "
+                        "falls back to a browser where there is no webview")
 
     i = sub.add_parser("init", help="read a tree and write the spec it already follows")
     i.add_argument("root")
@@ -187,7 +193,8 @@ def _ui(args) -> int:
     if root and not root.is_dir():
         print(f"error: not a folder: {root}", file=sys.stderr)
         return 2
-    serve(root, port=args.port, open_browser=not args.no_browser)
+    serve(root, port=args.port, open_browser=not args.no_browser,
+          shell=args.window and not args.no_browser)
     return 0
 
 

{shuttlecheck-0.4.0 → shuttlecheck-0.4.2}/shuttlecheck/completeness.py

@@ -110,10 +110,15 @@ class Ledger:
     weighed: dict = field(default_factory=dict)
     missing: list = field(default_factory=list)        # Declared, nothing arrived
     undeclared: list = field(default_factory=list)     # arrived, nothing declared
+    # Declared, and here under a name the rule could not read. Not missing:
+    # telling a camera crew they never delivered a session that is sitting
+    # on the drive with a typo in it is the one mistake this screen must not
+    # make. key -> the files that name it.
+    misnamed: dict = field(default_factory=dict)
 
     @property
     def complete(self) -> bool:
-        return not self.missing
+        return not self.missing and not self.misnamed
 
     @property
     def arrived(self) -> int:
@@ -317,6 +322,7 @@ class Ledger:
             # job, only its holes.
             "roster": [{"label": d.label, "fields": d.fields, "row": d.row,
                         "files": self.delivered.get(d.key, 0),
+                        "misnamed": len(self.misnamed.get(d.key, ())),
                         "who": self.whose(d),
                         # Whether the job has got this far. A row nothing
                         # arrived for reads as a hole or as work still to
@@ -338,6 +344,10 @@ class Ledger:
                          "where": where_it_belongs(d, self.folders,
                                                    self.tokens, self.settled)}
                         for d in self.missing],
+            "misnamed": [{"label": d.label, "fields": d.fields, "row": d.row,
+                          "who": self.whose(d),
+                          "paths": self.misnamed[d.key][:5]}
+                         for d in self.declared if d.key in self.misnamed],
             "undeclared": [{"label": " ".join(f"{k}={v}" for k, v in dict(
                 zip(self.key_tokens, key)).items()), "files": self.delivered[key]}
                 for key in self.undeclared],
@@ -660,16 +670,44 @@ def reconcile(declared: list[Declared], records, key_tokens: list,
             seen["rows"].add(key)
 
     declared_keys = {d.key for d in declared}
+    unread = [r for r in records
+              if not all(t in r.tokens for t in key_tokens)]
     for entry in declared:
         if not ledger.delivered.get(entry.key):
             ledger.delivered.setdefault(entry.key, 0)
-            ledger.missing.append(entry)
+            named = _named_anyway(entry, unread, key_tokens)
+            if named:
+                ledger.misnamed[entry.key] = named
+            else:
+                ledger.missing.append(entry)
 
     ledger.undeclared = sorted(k for k, n in ledger.delivered.items()
                                if n and k not in declared_keys)
     return ledger
 
 
+def _named_anyway(entry: "Declared", records, key_tokens: list) -> list[str]:
+    """Files the rule could not read that still name this declared row.
+
+    Conservative on purpose: every key value must appear in the path as a
+    whole word (`S003`, `D01`, `EXC26`), or have been read from it already.
+    `MAINSTAGE_S003` counts for S003; `S0031` does not, and a title alone
+    never does, because a near miss here would hide a real hole.
+    """
+    import re as _re
+
+    wanted = [str(entry.fields.get(t, "")).lower() for t in key_tokens]
+    if not all(wanted):
+        return []
+    out = []
+    for record in records:
+        words = set(w.lower() for w in _re.split(r"[^A-Za-z0-9]+", str(record.rel or "")) if w)
+        have = {str(v).lower() for v in (record.tokens or {}).values()}
+        if all(v in words or v in have for v in wanted):
+            out.append(str(record.rel))
+    return out
+
+
 def findings(ledger: Ledger, severities) -> list[Finding]:
     """A missing reel is an error in the report, not a note on a side screen.
 
@@ -693,7 +731,8 @@ def findings(ledger: Ledger, severities) -> list[Finding]:
             rule="declared-never-delivered",
             severity=severities("declared-never-delivered", "error"),
             path=entry.label or "(unnamed)", context=ledger.source,
-            message=(f"{entry.label} is listed in {ledger.source or 'the manifest'} "
+            message=(f"{' '.join(str(v) for v in entry.fields.values()) or entry.label} "
+                     f"is on {'the running order' if ledger.source == 'schedule' else (ledger.source or 'the manifest')} "
                      f"(row {entry.row}) and nothing was ever delivered for it"),
             detail={"source": ledger.source, "row": entry.row,
                     "fields": dict(entry.fields)},
@@ -704,8 +743,8 @@ def findings(ledger: Ledger, severities) -> list[Finding]:
             rule="delivered-never-declared",
             severity=severities("delivered-never-declared", "warning"),
             path=described, context=ledger.source,
-            message=(f"{described} was delivered but is not listed in "
-                     f"{ledger.source or 'the manifest'}"),
+            message=(f"{' '.join(str(v) for v in key)} was delivered but is not on "
+                     f"{'the running order' if ledger.source == 'schedule' else (ledger.source or 'the manifest')}"),
             detail={"source": ledger.source, "files": ledger.delivered[key]},
         ))
     return out

{shuttlecheck-0.4.0 → shuttlecheck-0.4.2}/shuttlecheck/conventions.py

@@ -32,6 +32,7 @@ from __future__ import annotations
 from .say import count
 
 import copy
+import json
 import re
 import uuid
 from datetime import datetime, timezone
@@ -512,6 +513,25 @@ def summaries() -> list[dict]:
     } for r in all_of_them()]
 
 
+def identical(name: str, doc: dict) -> dict | None:
+    """A convention already kept under this name with the same rules, if any.
+
+    Compared without the revision and the date, which are what saving
+    changes, so the same document kept twice is recognised as the same.
+    """
+    def bare(d):
+        d = dict(d or {})
+        d.pop("revision", None)
+        d.pop("updated", None)
+        return json.dumps(d, sort_keys=True, default=str)
+
+    wanted = (str(name or "").strip()[:MAX_NAME] or "Untitled convention", bare(doc))
+    for row in all_of_them():
+        if (row.get("name"), bare(row.get("doc"))) == wanted:
+            return row
+    return None
+
+
 def get(cid: str) -> dict | None:
     return store._read_json(_file(cid), None)
 

{shuttlecheck-0.4.0 → shuttlecheck-0.4.2}/shuttlecheck/delivery.py

@@ -605,7 +605,10 @@ def check_packages(packages: dict, records: list[FileRecord],
                     rule="incomplete-package",
                     severity=_shortfall_severity(requirement, severities),
                     path=described or name, context=name,
-                    message=_shortfall(label, described, context, count, rule),
+                    # Said the way a person says it: "Session package EXC26
+                    # D01 S005", not "project=EXC26 day=D01 session=S005".
+                    message=_shortfall(label, " ".join(str(v) for v in key),
+                                       context, count, rule),
                     detail={"package": name, "key": described,
                             "context": context, "found": count,
                             "wanted": _describe(rule)},

shuttlecheck-0.4.2/shuttlecheck/demo.py

@@ -0,0 +1,160 @@
+"""A sample drive, for somebody who has not got one to hand.
+
+A conference: two days, four rooms, a keyed running order, nine suppliers
+on six roads, some of the job delivered, some of it late, and a handful of
+names off the rule. Every tool has something true to show on it. The files
+are zeros, not media, and the drive says so in its own name.
+
+Built into the app's own folder, never anywhere somebody chose, so trying
+the product writes nothing near anybody's work.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+from datetime import datetime
+from pathlib import Path
+from zoneinfo import ZoneInfo
+
+import yaml
+
+EXAMPLE = Path(__file__).resolve().parent / "demo_convention.yaml"
+TZ = ZoneInfo("Europe/Malta")
+
+AGENDA = """\
+Session ID,Session Title,Room,Day,Start,End,Speakers,Sponsor
+S001,Opening Keynote,Main Stage,1,09:00,10:00,Jane Doe;Ravi Patel,
+S002,Scaling Payments,Tech Stage,1,10:30,11:15,Marta Kowalski,Acme Corp
+S003,Regulation Panel,Main Stage,1,11:30,12:30,Jane Doe,
+S004,AI in Compliance,Tech Stage,1,13:00,13:45,Sam Okoro,
+S005,Colour Pipelines,Workshop Room,1,10:00,11:00,Elena Nowak,
+S006,Founder Interviews,Interview Studio,1,12:00,13:00,Leo Marsh,Northwind
+S007,Closing Remarks,Main Stage,1,16:00,16:30,Jane Doe,
+S011,Day Two Keynote,Main Stage,2,09:00,10:00,Ravi Patel,Northwind
+S012,Payments at the Edge,Tech Stage,2,10:30,11:15,Marta Kowalski,Acme Corp
+S013,Audio for Streams,Workshop Room,2,10:00,11:00,Felix Silva,
+S014,Investor Panel,Main Stage,2,11:30,12:30,Dana Okafor,
+S015,Creator Interviews,Interview Studio,2,12:00,13:00,Leo Marsh,
+S016,Security Deep Dive,Tech Stage,2,13:30,14:15,Sam Okoro,
+S017,Awards,Main Stage,2,17:00,18:00,Jane Doe,Acme Corp
+"""
+
+VENDORS = {
+    "crew_main": {"label": "Hall 1 camera crew", "contact": "hall1@lisbonbroadcast.example",
+                  "owns": ["iso_record"], "where": {"stage": "MAIN"},
+                  "via": "dailiesdrop", "unit": "DD-PRO-0117"},
+    "crew_tech": {"label": "Hall 2 camera crew", "contact": "hall2@lisbonbroadcast.example",
+                  "owns": ["iso_record"], "where": {"stage": "TECH"},
+                  "via": "dailiesdrop", "unit": "DD-PRO-0117"},
+    "crew_wksp": {"label": "Workshop crew", "contact": "wksp@lisbonbroadcast.example",
+                  "owns": ["iso_record"], "where": {"stage": "WKSP"},
+                  "via": "dailiesdrop", "unit": "DD-PRO-0122"},
+    "crew_stdo": {"label": "Studio crew", "contact": "studio@lisbonbroadcast.example",
+                  "owns": ["iso_record"], "where": {"stage": "STDO"},
+                  "via": "shuttle"},
+    "master_edit": {"label": "Tejo Post", "contact": "deliveries@tejopost.example",
+                    "due": "2026-11-13", "owns": ["session_master"], "via": "dailiesdrop",
+                    "unit": "DD-PRO-0122"},
+    "social_edit": {"label": "Northlight Edit", "contact": "deliveries@northlight.example",
+                    "due": "2026-11-14", "owns": ["social_cutdown"], "via": "frameio"},
+    "sponsor_agency": {"label": "Meridian Sponsorship", "contact": "post@meridian.example",
+                       "due": "2026-11-18", "owns": ["sponsor_deliverable"],
+                       "via": "wetransfer"},
+    "captions": {"label": "Verbatim Captioning", "contact": "ops@verbatim.example",
+                 "due": "2026-11-16", "owns": ["speaker_deliverable"], "via": "gdrive"},
+    "proxy_house": {"label": "Lisbon Proxy", "contact": "ops@lisbonproxy.example",
+                    "owns": ["proxy"], "via": "aspera"},
+}
+
+M = "EXC26/D0{d}/{st}/MASTERS/EXC26_D0{d}_{st}_{s}_{t}_v01.mov"
+
+FILES = [
+    # Day one masters, mostly right
+    (M.format(d=1, st="MAIN", s="S001", t="opening-keynote"), 1, "09:05"),
+    (M.format(d=1, st="TECH", s="S002", t="scaling-payments"), 1, "10:35"),
+    (M.format(d=1, st="WKSP", s="S005", t="colour-pipelines"), 1, "10:05"),
+    (M.format(d=1, st="STDO", s="S006", t="founder-interviews"), 1, "12:05"),
+    (M.format(d=1, st="MAIN", s="S007", t="closing-remarks"), 1, "16:05"),
+    # Off the rule
+    ("EXC26/D01/MAIN/MASTERS/EXC26_D01_MAINSTAGE_S003_regulation-panel_v01.mov", 1, "11:35"),
+    ("EXC26/D01/TECH/MASTERS/EXC26_D01_TECH_S004_ai-in-compliance.mov", 1, "13:05"),
+    ("EXC26/D01/MAIN/MASTERS/exc26 d01 main s007 closing remarks FINAL.mov", 1, "16:10"),
+    ("EXC26/D01/MAIN/MASTERS/EXC26_D01_MAIN_S009_overnight-test_v01.mov", 1, "03:00"),
+    ("EXC26/D01/handover-notes.txt", None, None),
+    # Day two, half in
+    (M.format(d=2, st="MAIN", s="S011", t="day-two-keynote"), 2, "09:05"),
+    (M.format(d=2, st="TECH", s="S012", t="payments-at-the-edge"), 2, "10:35"),
+    (M.format(d=2, st="WKSP", s="S013", t="audio-for-streams"), 2, "10:05"),
+    ("EXC26/D02/MAIN/MASTERS/Investor Panel MASTER.mov", 2, "11:35"),
+    # Recorder originals, never renamed
+    ("EXC26/D01/MAIN/ISO/CAM01/A001C001_261110_ABCD.mov", 1, "09:05"),
+    ("EXC26/D01/MAIN/ISO/CAM02/A002C001_261110_ABCD.mov", 1, "09:05"),
+    ("EXC26/D01/TECH/ISO/CAM01/B001C004_261110_EF01.mov", 1, "10:35"),
+    ("EXC26/D01/WKSP/ISO/CAM01/C001C002_261110_7A21.mov", 1, "10:05"),
+    ("EXC26/D02/MAIN/ISO/CAM01/A001C031_261111_ABCD.mov", 2, "09:05"),
+    ("EXC26/D02/TECH/ISO/CAM01/B001C022_261111_EF01.mov", 2, "10:35"),
+    # Proxies
+    ("EXC26/PROXY/D01/MAIN/EXC26_D01_MAIN_S001_CAM01_proxy.mp4", None, None),
+    ("EXC26/PROXY/D01/TECH/EXC26_D01_TECH_S002_CAM01_proxy.mp4", None, None),
+    ("EXC26/PROXY/D01/MAIN/S003 cam1 proxy.mp4", None, None),
+    # Deliverables
+    ("EXC26/DELIVERABLES/SPEAKERS/D01/EXC26_D01_S001_doe-jane_opening-keynote_v01.mp4", None, None),
+    ("EXC26/DELIVERABLES/SPEAKERS/D01/EXC26_D01_S002_kowalski-marta_scaling-payments_v01.mp4", None, None),
+    ("EXC26/DELIVERABLES/SPONSORS/acme-corp/EXC26_acme-corp_D01_S002_scaling-payments_16x9_v01.mp4", None, None),
+    ("EXC26/DELIVERABLES/SPONSORS/northwind/northwind cut v2.mp4", None, None),
+    ("EXC26/SOCIAL/D01/EXC26_S001_opening-keynote_9x16_v01.mp4", None, None),
+    ("EXC26/SOCIAL/D01/EXC26_S002_scaling-payments_1x1_v01.mp4", None, None),
+]
+
+
+def build(root: Path) -> Path:
+    """Lay the sample out under `root`; returns the convention it carries."""
+    root = Path(root)
+    spec_dir = root / "EXC26" / "_SPEC"
+    spec_dir.mkdir(parents=True, exist_ok=True)
+
+    doc = yaml.safe_load(EXAMPLE.read_text(encoding="utf-8"))
+    # The files are zeros, not media: delivery rules would only report that.
+    doc.pop("deliverables", None)
+    for ctx in doc["contexts"]:
+        ctx.pop("deliverable", None)
+    doc["sources"]["schedule"]["align"]["clock"] = "file_mtime"
+    doc["id"] = "showcase-conference"
+    doc["name"] = "Example Conference 2026 - Live Video"
+    doc["vendors"] = VENDORS
+    (spec_dir / "spec.yaml").write_text(
+        yaml.safe_dump(doc, sort_keys=False, allow_unicode=True), encoding="utf-8"
+    )
+    (spec_dir / "agenda.csv").write_text(AGENDA, encoding="utf-8")
+
+    for rel, day, hhmm in FILES:
+        path = root / rel
+        path.parent.mkdir(parents=True, exist_ok=True)
+        size = 4096 if rel.endswith((".mov", ".mxf")) else 1024
+        path.write_bytes(b"\0" * size)
+        if hhmm:
+            h, m = (int(x) for x in hhmm.split(":"))
+            when = datetime(2026, 11, 9 + day, h, m, tzinfo=TZ).timestamp()
+            os.utime(path, (when, when))
+    return spec_dir / "spec.yaml"
+
+
+
+
+def make(home: Path, *, fresh: bool = False) -> Path:
+    """The sample drive in the app's folder, built once and kept.
+
+    `fresh` throws the old one away first, so somebody who renamed half of
+    it can start again. Only ever the folder this module made.
+    """
+    target = Path(home) / "sample-drive"
+    if fresh and target.is_dir() and (target / ".shuttlecheck-sample").is_file():
+        shutil.rmtree(target)
+    if not (target / ".shuttlecheck-sample").is_file():
+        target.mkdir(parents=True, exist_ok=True)
+        build(target)
+        (target / ".shuttlecheck-sample").write_text(
+            "A sample drive made by ShuttleCheck. Safe to delete.\n",
+            encoding="utf-8")
+    return target / "EXC26"