One launcher, one page — the dashboard integration format

Every tool here ends up as a script plus a page, and until now each one invented its own way of saying “this passed.” This is the house format: follow it and a new .py plus its .html drop into the master dashboard as a live tile — green at a glance, one click to run, one click to open — with no glue code on either side. It is deliberately small: five marker lines on stdout, one self-contained page, one JSON entry.

1 · The shape

One master launcher owns the browser tab. Everything else is a normal standalone program that happens to describe its own result in a way the master can read.

• One master .py serves one master .html — the only page you keep open. It runs the sub-tools, tracks their status, and links their pages.
• Each sub-tool is its own .py, still runnable by hand from a terminal with no dashboard anywhere in sight.
• Each sub-tool writes its own .html — a full sub-dashboard for the detail that will not fit on a tile. The master opens it in its own tab.

2 · The contract — five marker lines

A task reports its result by printing. That is the whole protocol: no imports, no sockets, no exit-code guessing games. Any line matching DASH_<KEY>: <value> is consumed by the master; every other line stays in the live log.

Flush as you go (print(…, flush=True)) so the log streams live instead of arriving all at once at the end.

3 · The status vocabulary

Four words, so that a wall of tiles means the same thing to everyone reading it.

4 · Scripts that predate this format still work

With no DASH_STATUS line the master falls back, in order:

1. a line matching verdict: PASS|FAIL|WARN|SKIP (also CORRECT / INCORRECT, so Calibre-style output scores itself);
2. failing that, the exit code — 0 is PASS, anything else FAIL.

So an existing checker usually needs no changes at all to become a tile. Add the markers when you want the summary line and the metrics, not to make it work.

5 · Rules for the task .py

1. One file, standard library only. It has to run on a laptop and on a workstation over SSH with nothing installed. No numpy, no requests, no framework.
2. Runnable by hand. python3 tasks/thing.py --help must work and be useful with no dashboard running.
3. Every input is a flag with a working default — --rep, --gds, --data. Point the default at a committed sample so the tile demonstrates itself on a fresh clone.
4. Missing input is SKIP, not a crash and not a pass.
5. Accept -V / --version. The install convention ends on it, so the paste proves itself — and the dashboard has something to show when a tile will not start.
6. Report progress on stderr every 5 seconds, per the site-wide rule: phase and real percentage, rate and ETA, overall ETA, and the output file's size as it grows. stdout stays the pasteable summary and the DASH_ markers, so the two never collide. Offer --no-progress and -q. The log pane is live; a silent 90-second run looks hung either way.
7. Never write outside the dashboard directory unless a flag says so. Reports go to reports/.
8. Be re-runnable. The run button gets pressed repeatedly; a second run must overwrite cleanly, not append or fail.

6 · Rules for the sub-dashboard .html

1. Self-contained. One file, inline CSS, no CDN and no network calls — it has to open from file:// on a machine with no internet.
2. Light and dark. Define the light palette on :root and override it under @media (prefers-color-scheme: dark).
3. Lead with the numbers. A KPI strip across the top, then the tables. The reader arrived from a red tile and wants to know what is red.
4. Worst first. Sort so failures are at the top of every table; nobody scrolls to find the problem.
5. Say when it was generated, and from which input file, in the subtitle. A report with no timestamp gets trusted long after it went stale.
6. Every figure carries a number and a title — Figure 1 · … — per the site-wide chart rule.
7. If it is published here, it carries its page number in the footer, and a row in the Page Registry. Local-only reports do not get numbers.

7 · Registering the tile

One object in the launcher's config. id is what other tiles and the state file refer to, so keep it short and never reuse one.

{
  "id":      "drc",
  "name":    "DRC",
  "group":   "Physical Verification",
  "icon":    "▦",
  "cmd":     "python3 tasks/drc_check.py",
  "doc":     "Calibre DRC summary — open vs waived violations, grouped by design area.",
  "timeout": 900
}

8 · Rollup tiles read the other tiles

The master writes every finished run to state/results.json, keyed by tile id: status, summary, metrics, and the timestamp. A tile marked "rollup": true is scheduled last, so it can read that file and turn the whole board into one verdict — a tapeout gate, a nightly digest, a release checklist.

Two rules make a rollup honest, and both are easy to skip:

• Never-run is not a pass. A dependency with no entry is a hole in the gate.
• Age matters. A PASS from three days ago against a layout edited this morning is not a PASS. Compare the timestamp and downgrade to WARN.

9 · Copy-paste template

A complete, valid task in 30 lines. Start here.

#!/usr/bin/env python3
"""One line saying what this checks and what it decides."""
import argparse, os, sys

def emit(k, v): print("DASH_%s: %s" % (k, v), flush=True)

def main():
    ap = argparse.ArgumentParser()
    ap.add_argument("-V", "--version", action="version", version="thing 1.0")
    ap.add_argument("--no-progress", action="store_true")   # per the 5-second rule
    ap.add_argument("-q", "--quiet", action="store_true")
    ap.add_argument("--rep", default="samples/thing.rep")   # a committed sample
    a = ap.parse_args()

    if not os.path.exists(a.rep):          # missing input is SKIP, never PASS
        emit("STATUS", "SKIP")
        emit("SUMMARY", "no input at %s" % a.rep)
        return 0

    print("reading %s" % a.rep)            # plain prints become the live log
    bad, waived = check(a.rep)             # ... your actual work ...

    path = write_report(bad)               # a self-contained page, per section 6
    emit("HTML", os.path.abspath(path))
    emit("METRIC", "violations=%d" % len(bad))
    emit("METRIC", "waived=%d" % waived)

    st = "FAIL" if bad else ("WARN" if waived else "PASS")
    emit("SUMMARY", "%d open · %d waived" % (len(bad), waived))
    emit("STATUS", st)                     # status last
    return 1 if st == "FAIL" else 0        # exit code for cron / CI

if __name__ == "__main__":
    sys.exit(main())

10 · Checklist before you call it done

1. python3 tasks/thing.py runs standalone and prints a DASH_STATUS.
2. python3 tasks/thing.py -V prints a version, so the install paste is self-testing.
3. A run longer than 5 s prints a heartbeat on stderr, and -q silences it without touching stdout.
4. It exits 1 on FAIL and 0 otherwise.
5. Deleting its input yields SKIP, not a traceback.
6. Running it twice in a row gives the same answer.
7. Its page opens from file:// with no network.
8. Its page renders in both light and dark, and every figure has a number and title.
9. The tile entry is in the launcher config, with a doc line.
10. The sample input is committed, so a fresh clone demonstrates itself.