@caddis/cli 0.4.72 → 0.4.74

package/bundles/antigravity-plugin/skills/flow-chart-from-counts/scripts/edges_to_mermaid.py

@@ -0,0 +1,418 @@
+#!/usr/bin/env python3
+"""Turn a from,to,count edge list into a first-draft Mermaid flowchart.
+
+The draft applies the count and layout rules of the flow-chart-from-counts skill:
+
+- counts go in quoted brackets on arrows: |"(1,234)"|
+- paths under --min are not drawn; the note names how many and how big they were
+- the chart is drawn as a TREE: each box keeps one parent edge (the biggest path into it); every other
+  path into it becomes a small dashed stub under its own source, "to X (n)". Shared targets are what
+  make the layout cross lines. --no-tree keeps shared targets as real edges.
+- each source that ends gets its own end box, so no long lines cross the chart to one shared box
+- a loop back to an earlier step becomes a "back to X (n)" stub, not an edge
+- edges and nodes are written largest first: the layout takes that as its first guess for left to right
+- duplicate from,to rows are added together into one path
+- node types become classDefs named t_<type> (they never clash with the built-in classes endn, stub and
+  startn); --in-scope types get a thick border, --optional types a dashed one
+
+It is a draft. Read the rendered chart and fix the layout by hand (SKILL.md, "Layout fixes").
+
+Usage:
+    python edges_to_mermaid.py edges.csv [--nodes nodes.csv] [--min 25] [--in-scope T1,T2]
+                               [--optional T3] [--direction TD] [--end-label "Ends"] [--no-tree]
+                               [--out chart.mmd] [--strict]
+
+edges.csv columns: from,to,count, where count is DISTINCT cases per pair (also accepted: from_step,
+to_step,case_count). Do not feed it path occurrences (COUNT(*)): see references/edge-list-sql.md.
+nodes.csv columns: name,type[,count]; count is the distinct cases in that box.
+The Mermaid source goes to --out FILE (written as UTF-8) or, without --out, to stdout (also UTF-8).
+The note on hidden paths and any warning go to stderr. With --strict, any self-check warning gives exit 1
+(the chart is still written). Exit codes: 0 ok, 1 strict warning, 2 bad input.
+Standard library only.
+"""
+
+from __future__ import annotations
+
+import argparse
+import csv
+import hashlib
+import re
+import sys
+from collections import defaultdict
+from dataclasses import dataclass, field
+from pathlib import Path
+
+START = "START"
+END = "END"
+
+# Light fills with dark text: they keep contrast on a light canvas in both page themes.
+PALETTE = [
+    ("#dbe4ee", "#475569"),
+    ("#bbf7d0", "#15803d"),
+    ("#f6e7d6", "#b45309"),
+    ("#e9d5ff", "#7e22ce"),
+    ("#fde68a", "#a16207"),
+    ("#cffafe", "#0e7490"),
+    ("#fecdd3", "#be123c"),
+]
+TEXT = "#1c1917"
+
+
+@dataclass(frozen=True)
+class Edge:
+    src: str
+    dst: str
+    count: int
+
+
+@dataclass
+class Result:
+    mermaid: str
+    hidden_paths: int
+    hidden_total: int
+    note: str
+    warnings: list[str] = field(default_factory=list)
+
+
+def node_id(name: str) -> str:
+    """A stable Mermaid id: a readable slug plus a 6-character hash.
+
+    A collision is very unlikely but not impossible. convert() checks for one and raises ValueError.
+    """
+    if name == START:
+        return "start"
+    slug = re.sub(r"[^A-Za-z0-9]+", "_", name).strip("_").lower()[:24] or "node"
+    digest = hashlib.sha1(name.encode("utf-8")).hexdigest()[:6]
+    return f"n_{slug}_{digest}"
+
+
+def _label(text: str) -> str:
+    """Escape a name for a quoted Mermaid label. '#' goes first: it starts every entity code."""
+    text = " ".join(text.splitlines())
+    for raw, code in (("#", "#35;"), ('"', "#quot;"), ("<", "#lt;"), (">", "#gt;"), ("[", "#91;"), ("]", "#93;"), ("&", "#amp;")):
+        text = text.replace(raw, code)
+    return text
+
+
+def merge_edges(edges: list[Edge]) -> list[Edge]:
+    """Add the counts of duplicate (from, to) pairs. First-seen order is kept."""
+    total: dict[tuple[str, str], int] = {}
+    for e in edges:
+        total[(e.src, e.dst)] = total.get((e.src, e.dst), 0) + e.count
+    return [Edge(a, b, n) for (a, b), n in total.items()]
+
+
+def _n(count: int) -> str:
+    return f"{count:,}"
+
+
+def _order_sources(edges: list[Edge]) -> list[str]:
+    """Sources in breadth-first order from START, then any left over, so the text reads top-down."""
+    out: dict[str, list[Edge]] = defaultdict(list)
+    for e in edges:
+        out[e.src].append(e)
+    roots = [START] if START in out else sorted({e.src for e in edges} - {e.dst for e in edges})
+    seen: list[str] = []
+    queue = list(roots)
+    while queue:
+        cur = queue.pop(0)
+        if cur in seen or cur == END:
+            continue
+        seen.append(cur)
+        queue.extend(e.dst for e in sorted(out.get(cur, []), key=lambda x: -x.count))
+    seen += sorted(s for s in out if s not in seen)
+    return [s for s in seen if s in out]
+
+
+def _back_edges(edges: list[Edge], roots: list[str]) -> set[Edge]:
+    """Edges that point to a step still open on the depth-first path: the loop-backs."""
+    out: dict[str, list[Edge]] = defaultdict(list)
+    for e in edges:
+        out[e.src].append(e)
+    back: set[Edge] = set()
+    state: dict[str, int] = {}  # 1 = on the path, 2 = done
+
+    def visit(node: str) -> None:
+        state[node] = 1
+        for e in sorted(out.get(node, []), key=lambda x: -x.count):
+            if e.dst == END:
+                continue
+            if state.get(e.dst) == 1:
+                back.add(e)
+            elif e.dst not in state:
+                visit(e.dst)
+        state[node] = 2
+
+    for r in roots:
+        if r not in state:
+            visit(r)
+    for s in list(out):
+        if s not in state:
+            visit(s)
+    return back
+
+
+def _reachable(edges: list[Edge], roots: list[str]) -> set[str]:
+    out: dict[str, list[str]] = defaultdict(list)
+    for e in edges:
+        out[e.src].append(e.dst)
+    seen: set[str] = set()
+    stack = list(roots)
+    while stack:
+        cur = stack.pop()
+        if cur in seen:
+            continue
+        seen.add(cur)
+        stack.extend(out.get(cur, []))
+    return seen
+
+
+def convert(
+    edges: list[Edge],
+    min_count: int = 1,
+    box_counts: dict[str, int] | None = None,
+    node_types: dict[str, str] | None = None,
+    in_scope: set[str] | frozenset[str] = frozenset(),
+    optional: set[str] | frozenset[str] = frozenset(),
+    direction: str = "TD",
+    end_label: str = "Ends",
+    tree: bool = True,
+) -> Result:
+    box_counts = box_counts or {}
+    node_types = node_types or {}
+    edges = merge_edges(edges)
+    seen_ids: dict[str, str] = {}
+    for name in {n for e in edges for n in (e.src, e.dst) if n != END}:
+        other = seen_ids.setdefault(node_id(name), name)
+        if other != name:
+            raise ValueError(f"{other!r} and {name!r} would get the same id; rename one of them")
+
+    small = [e for e in edges if e.count < min_count]
+    kept = [e for e in edges if e.count >= min_count]
+    has_start = any(e.src == START for e in edges)
+    roots = [START] if has_start else sorted({e.src for e in edges} - {e.dst for e in edges})
+    live = _reachable(kept, roots)
+    orphaned = [e for e in kept if e.src not in live]
+    kept = [e for e in kept if e.src in live]
+
+    back = _back_edges(kept, roots)
+    # Tree mode: the biggest forward path into a box is its one parent edge; the rest become stubs.
+    stubbed: set[Edge] = set()
+    if tree:
+        into: dict[str, list[Edge]] = defaultdict(list)
+        for e in kept:
+            if e.dst != END and e not in back:
+                into[e.dst].append(e)
+        for incoming in into.values():
+            incoming.sort(key=lambda x: (-x.count, x.src))
+            stubbed.update(incoming[1:])
+    layout = [e for e in kept if e not in back and e not in stubbed]
+    lines = [f"flowchart {direction}"]
+
+    # Declare nodes in the same largest-first order as the edges: Mermaid places the first-declared
+    # child of a rank on the left, so declaration order is part of the layout.
+    names: list[str] = []
+    ordered = sorted(layout, key=lambda x: -x.count)
+    for src in _order_sources(layout):
+        for n in [src] + [e.dst for e in ordered if e.src == src]:
+            if n != END and n not in names:
+                names.append(n)
+    for e in kept:
+        for n in (e.src, e.dst):
+            if n != END and n not in names:
+                names.append(n)
+    start_total = sum(e.count for e in kept if e.src == START) + sum(e.count for e in small if e.src == START)
+    for name in names:
+        if name == START:
+            lines.append(f'  start(["Start<br/>({_n(start_total)})"])')
+            continue
+        text = _label(name)
+        if name in box_counts:
+            text += f"<br/>({_n(box_counts[name])})"
+        lines.append(f'  {node_id(name)}["{text}"]')
+
+    by_src: dict[str, list[Edge]] = defaultdict(list)
+    for e in kept:
+        by_src[e.src].append(e)
+    end_ids: list[str] = []
+    stub_ids: list[str] = []
+    sources = _order_sources(layout)
+    sources += [s for s in _order_sources(kept) if s not in sources]
+    for src in sources:
+        sid = node_id(src)
+        for e in sorted(by_src[src], key=lambda x: -x.count):
+            arrow = f'{sid} -->|"({_n(e.count)})"|'
+            if e.dst == END:
+                eid = f"end_{sid}"
+                end_ids.append(eid)
+                lines.append(f'  {arrow} {eid}(["{_label(end_label)}"])')
+            elif e in back or e in stubbed:
+                word = "back to" if e in back else "to"
+                bid = f"{word.split()[0]}_{sid}_{node_id(e.dst)}"
+                stub_ids.append(bid)
+                lines.append(f'  {sid} --> {bid}(["{word} {_label(e.dst)} ({_n(e.count)})"])')
+            else:
+                lines.append(f"  {arrow} {node_id(e.dst)}")
+
+    types = []
+    for name in names:
+        t = node_types.get(name)
+        if t and t not in types:
+            types.append(t)
+    for i, t in enumerate(types):
+        fill, stroke = PALETTE[i % len(PALETTE)]
+        extra = ""
+        if t in in_scope:
+            extra = ",stroke-width:3px"
+        elif t in optional:
+            extra = ",stroke-width:2px,stroke-dasharray:6 4"
+        lines.append(f"  classDef t_{t} fill:{fill},stroke:{stroke},color:{TEXT}{extra};")
+    if end_ids:
+        lines.append(f"  classDef endn fill:#eceae6,stroke:#78716c,color:{TEXT};")
+    if stub_ids:
+        lines.append("  classDef stub fill:#ffffff,stroke:#a8a29e,stroke-dasharray:3 3,color:#57534e;")
+    if has_start and START in names:
+        lines.append(f"  classDef startn fill:#ffffff,stroke:#57534e,stroke-width:2px,color:{TEXT};")
+    for t in types:
+        ids = [node_id(n) for n in names if node_types.get(n) == t]
+        lines.append(f"  class {','.join(ids)} t_{t};")
+    if end_ids:
+        lines.append(f"  class {','.join(end_ids)} endn;")
+    if stub_ids:
+        lines.append(f"  class {','.join(stub_ids)} stub;")
+    if has_start and START in names:
+        lines.append("  class start startn;")
+
+    hidden_total = sum(e.count for e in small)
+    note_parts = []
+    if small:
+        note_parts.append(
+            f"Not drawn: {len(small)} paths with fewer than {_n(min_count)} each "
+            f"({_n(hidden_total)} in total): "
+            + "; ".join(f"{e.src} to {e.dst} ({_n(e.count)})" for e in sorted(small, key=lambda x: -x.count))
+            + "."
+        )
+    if orphaned:
+        note_parts.append(f"Also not drawn: {len(orphaned)} paths that start from a step that is not drawn.")
+    note = " ".join(note_parts)
+    if note:
+        lines.append(f"  %% {note}")
+    # Self-check: an arrow counts distinct cases, so it can never be larger than the box at either end.
+    # When it is, the edge list counts path occurrences (COUNT(*)), not cases.
+    warnings = []
+    for e in kept:
+        for end in (e.src, e.dst):
+            if end in box_counts and e.count > box_counts[end]:
+                warnings.append(
+                    f"{e.src} to {e.dst} ({_n(e.count)}) is larger than the box {end} ({_n(box_counts[end])}): "
+                    "the edge list counts path occurrences, not distinct cases"
+                )
+    return Result("\n".join(lines) + "\n", len(small), hidden_total, note, warnings)
+
+
+def build(edges: list[Edge], **kwargs) -> str:
+    return convert(edges, **kwargs).mermaid
+
+
+def _col(row: dict[str, str], *names: str, where: str = "csv") -> str:
+    lower = {k.strip().lower(): v for k, v in row.items() if k}
+    for n in names:
+        if n in lower:
+            if lower[n] is None:
+                raise ValueError(f"{where}: the row has no value for {n!r} (the row is shorter than the header)")
+            return lower[n].strip()
+    raise ValueError(f"{where}: missing column, expected one of {names}; got {sorted(lower)}")
+
+
+def read_edges(path: Path) -> list[Edge]:
+    edges = []
+    with path.open(encoding="utf-8-sig", newline="") as fh:
+        for line_no, row in enumerate(csv.DictReader(fh), start=2):
+            where = f"{path}:{line_no}"
+            raw = _col(row, "count", "case_count", "n", where=where)
+            try:
+                count = int(raw.replace(",", ""))
+            except ValueError as exc:
+                raise ValueError(f"{path}:{line_no}: count is not a whole number: {raw!r}") from exc
+            edges.append(
+                Edge(_col(row, "from", "from_step", "src", where=where), _col(row, "to", "to_step", "dst", where=where), count)
+            )
+    return merge_edges(edges)
+
+
+def read_nodes(path: Path) -> tuple[dict[str, str], dict[str, int]]:
+    types: dict[str, str] = {}
+    counts: dict[str, int] = {}
+    with path.open(encoding="utf-8-sig", newline="") as fh:
+        for line_no, row in enumerate(csv.DictReader(fh), start=2):
+            where = f"{path}:{line_no}"
+            name = _col(row, "name", "step", "node", where=where)
+            t = _col(row, "type", "kind", where=where)
+            if t:
+                types[name] = re.sub(r"[^A-Za-z0-9_]", "_", t)
+            lower = {k.strip().lower(): v for k, v in row.items() if k}
+            raw = (lower.get("count") or lower.get("case_count") or "").strip()
+            if raw:
+                try:
+                    counts[name] = int(raw.replace(",", ""))
+                except ValueError as exc:
+                    raise ValueError(f"{where}: count is not a whole number: {raw!r}") from exc
+    return types, counts
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(description=__doc__.split("\n\n")[0])
+    ap.add_argument("edges", type=Path)
+    ap.add_argument("--nodes", type=Path)
+    ap.add_argument("--min", type=int, default=1, dest="min_count")
+    ap.add_argument("--in-scope", default="")
+    ap.add_argument("--optional", default="")
+    ap.add_argument("--direction", default="TD", choices=["TD", "LR"])
+    ap.add_argument("--end-label", default="Ends")
+    ap.add_argument("--no-tree", action="store_true", help="keep shared targets as real edges, no stubs")
+    ap.add_argument("--out", type=Path, help="write the Mermaid source to this file as UTF-8 (default: stdout)")
+    ap.add_argument("--strict", action="store_true", help="exit 1 when the self-check finds an arrow larger than a box")
+    args = ap.parse_args(argv)
+    if hasattr(sys.stdout, "reconfigure"):
+        sys.stdout.reconfigure(encoding="utf-8")
+    if hasattr(sys.stderr, "reconfigure"):
+        sys.stderr.reconfigure(encoding="utf-8", errors="replace")
+
+    try:
+        edges = read_edges(args.edges)
+        types, counts = read_nodes(args.nodes) if args.nodes else ({}, {})
+    except (OSError, ValueError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+    split = lambda s: {x.strip() for x in s.split(",") if x.strip()}
+    try:
+        result = convert(
+            edges,
+            min_count=args.min_count,
+            box_counts=counts,
+            node_types=types,
+            in_scope=split(args.in_scope),
+            optional=split(args.optional),
+            direction=args.direction,
+            end_label=args.end_label,
+            tree=not args.no_tree,
+        )
+        if args.out:
+            args.out.write_text(result.mermaid, encoding="utf-8", newline="\n")
+        else:
+            sys.stdout.write(result.mermaid)
+    except (OSError, ValueError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+    if result.note:
+        print(result.note, file=sys.stderr)
+    for w in result.warnings:
+        print(f"warning: {w}", file=sys.stderr)
+    if args.strict and result.warnings:
+        print(f"error: --strict: {len(result.warnings)} self-check warning(s)", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/bundles/antigravity-plugin/skills/handoff/SKILL.md

@@ -146,7 +146,9 @@ history, and the relay has a 4,000-character budget (`caddis_budget.py`).
 > Your session id is printed at session start as `[caddis] this session's id: <id>`; use it for
 > `session_id` and `--session-id`. Never guess one: a wrong id disables session matching.
 >
-> 1. **Name the workstream** (active plan's `feature`, else the branch; the script prints nothing
+> 1. **Name the workstream.** First run the coordinator check of Step 9. When it says this session is the
+>    repo's coordinator, `<name>` is the config's `relay`: do not run `resolve` and do not ask. Else name it
+>    from the active plan's `feature`, else the branch (the script prints nothing
 >    on the default branch with no plan — run `caddis_workstreams.py list` (`python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_workstreams.py" list`) to show existing workstreams, then ask the user which one to use or for a short name):
 >    `python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_workstreams.py" resolve --plan <feature> --branch <branch> --default-branch <main>`
 > 2. **Legacy repo:** if `.caddis/relay.md` exists and does not start with
@@ -398,7 +400,40 @@ Then, in a shared checkout, `Docs PR needed:` with the `PR:` line and the file l
 Step 9 prints after this report. It is the last output of the handoff.
 
 ## Step 9 — print the resume prompt (always the last output)
-The owner should never have to ask for the resume prompt. After the checklist report, run:
+The owner should never have to ask for the resume prompt. After the checklist report, check for a
+coordinator first.
+
+**Coordinator check.** Step 3, point 1 also uses this check. When the repo has `.caddis/coordinator.md`,
+find out if this session is the repo's coordinator:
+1. Read the config. It must have `relay`:
+   ```
+   python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_coordinate.py" config show --path . --json
+   ```
+   Exit 1, or no `relay`: this session is not treated as the coordinator here. Use the normal block.
+2. Find the repo id `<R>` (`<account>` is the repo's GitHub account, from the repo's `AGENTS.md`):
+   ```
+   GH_TOKEN=$(gh auth token -u <account>) python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_coordinate.py" repo-id --json
+   ```
+   Keep `repo` as `<R>`.
+3. Find this session's pid. Keep `pid`:
+   ```
+   python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_coordinate.py" session --session-id <session-id> --json
+   ```
+4. Read the lock holder. It never takes or changes the lock:
+   ```
+   python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_coordinate.py" lock holder --repo <R> --json
+   ```
+5. This session is the coordinator when the holder's `sessionId` is this session's id, OR the holder's `pid`
+   is this session's `pid` (the same coordinator process, for example after a `/clear` that never ran start).
+
+When this session is the coordinator, `<name>` is the config's `relay`, and you add `--coordinator` to the
+`resume-block` call below. The block then prints only `/clear`, `/rename coordinator` and
+`/caddis:coordinate start`, and no resume prompt: `/caddis:coordinate start` reads the relay and its tasks
+itself. `resume-block --coordinator` refuses (exit 1) a `--name` that is not the config's `relay`. In all
+other cases (no `.caddis/coordinator.md`, no `relay`, `{"holder": null}`, another holder, an exit 1), run
+`resume-block` as written.
+
+Then run:
 ```
 python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_fleet.py" resume-block --name <name> --session-id <session-id> --root .
 ```

package/bundles/codex/.codex/skills/media/flow-chart-from-counts/SKILL.md

@@ -0,0 +1,193 @@
+---
+name: flow-chart-from-counts
+description: Turn a from-to-count edge list into a zoomable Mermaid flow chart page with counts, a legend and a render check.
+---
+
+# flow-chart-from-counts
+
+Turns counted paths (N cases went from step A to step B) into a flow chart page that a
+reader can trust: counts on every arrow, a legend for the box types, a title with the date and
+time zone, a note that names what is not drawn, and a viewer with zoom, pan and full screen.
+
+Paths below are relative to the folder that holds this file.
+
+## When to use it
+
+- "Draw how cases move through the process", "show the journey with counts", "flow chart of
+  calls / orders / tickets / sessions from this table".
+- You have, or can query, rows of `from, to, count`, or an event table with one row per step.
+- A Sankey or a funnel was asked for, but the paths branch and rejoin: a flow chart shows that
+  better.
+
+Use something else for:
+
+- An interactive page from a JSON model with lanes, playback and an inspector: `flow-studio`.
+- Mermaid syntax for other diagram kinds (sequence, ERD, class): `mermaid-diagrams`.
+- A diagram of a SQL object's structure: `db-diagram`.
+
+## What is in the folder
+
+| file | use |
+|---|---|
+| `scripts/edges_to_mermaid.py` | CSV edge list to first-draft Mermaid source (standard library only) |
+| `assets/viewer-template.html` | page with the zoom/pan/full-screen viewer, theme tokens and one example chart |
+| `scripts/check-render.mjs` | headless render check: fails on no SVG, error text, too few nodes, page errors; saves screenshots |
+| `references/edge-list-sql.md` | SQL pattern: event table to edge list and box counts, and the checks to run on it |
+
+## Process
+
+1. **Get the edge list.** From an event table, use `references/edge-list-sql.md`. Run its checks
+   (START rows add up to the cases; path occurrences in equal path occurrences out per step).
+   Count arrows as distinct cases per pair. Get the box counts (distinct cases per step) at the
+   same time.
+2. **Name the node types** with the reader, or from the process owner's own glossary: for
+   example automatic step, in-scope step, optional step, hand-off, end. Write a `nodes.csv`
+   (`name,type,count`).
+3. **Make the first draft:**
+   ```
+   python scripts/edges_to_mermaid.py edges.csv --nodes nodes.csv --min 25 \
+          --in-scope scope --optional choice --out chart.mmd --strict
+   ```
+   `--out` writes UTF-8 (do not use `>` in Windows PowerShell 5.1: it can write UTF-16). The note
+   on hidden paths goes to stderr. Keep it: it goes under the chart. `--strict` exits 1 on a
+   `warning:` line, which means an arrow is larger than its box: fix the query before you draw.
+   Duplicate `from,to` rows are added together. Node types become classes named `t_<type>`.
+4. **Put it in the page.** Copy `assets/viewer-template.html`. Paste the source into the
+   `<script type="text/plain">` block. Set `data-title` (what, which day) and `data-sub` (the UTC
+   window, the unit of the counts, the minimum path size). Replace the legend and the note.
+   For more charts, add one `.fv` block and one source script per chart.
+5. **Render and check:**
+   ```
+   node <skill folder>/scripts/check-render.mjs page.html --out shots [--channel msedge]
+   ```
+   Run it from a folder whose `node_modules` has `playwright`. It exits 1 when a check fails.
+6. **Look at the screenshots** (`chart-N.png` is the chart at Fit, `chart-1-full.png` is full
+   screen) and run the tidy checklist below. If a rule fails, change the layout with the layout
+   fixes, and go back to step 5.
+7. **Show** the page and the screenshots only when every checklist rule passes. Say which labels
+   are your reading (see Wording). If a rule cannot be met, say which rule and why.
+
+## Tidy checklist (the chart must pass it before you show it)
+
+A clean, tidy chart is an acceptance rule, not a nice-to-have. A reader who has to trace a
+line across the page stops trusting the numbers on it.
+
+1. **No crossing lines.** No line passes through a box or a label. Use the tree rule with
+   dashed stubs, and split shared targets (layout fixes 1 and 2).
+2. **No overlaps.** No label or box sits on another. Edge labels are short: `(1,234)` and at
+   most a few words. Long text goes in the note under the chart, not on the chart.
+3. **Rows and side flows.** Boxes of the same kind line up in one row where the flow allows
+   (layout fix 5). A side flow sits in its own dashed box at the bottom, pushed down with an
+   invisible link (layout fix 4).
+4. **One look per type.** One box shape per type, a small fixed palette (5 to 7 classes), a
+   legend that matches the chart exactly (stubs included), and the title with the date and the
+   time zone on the chart.
+5. **Readable at Fit and at full screen** on a 1280 x 900 screen. Nothing is clipped.
+6. **Checked by eye.** You opened both screenshots and checked rules 1 to 5 on them. The render
+   check's warnings (box overlaps, labels on boxes) help, but they cannot see a crossing line.
+
+## Count rules
+
+- **Arrows and boxes both count distinct cases.** An arrow says how many distinct cases took
+  that path (`COUNT(DISTINCT case_id)` per from-to pair). A box says how many distinct cases
+  reached it. Do not draw path occurrences (`COUNT(*)`): a case that loops counts twice, and a
+  reader who sees a box of 8,538 followed by an arrow of 8,541 stops trusting the chart. Label
+  every number as cases.
+- **Self-check: no arrow into or out of a box exceeds that box's count.** If one does, the
+  query counts occurrences. The converter warns on stderr when this happens.
+- **Say in the note that arrows into a box can sum to a little more than the box**, because a
+  case can reach it by two paths.
+- **Put counts in brackets, with thousands separators:** `(1,234)`. In Mermaid an edge label that
+  holds brackets must be quoted: `A -->|"(1,234)"| B`. Unquoted, `(` starts a node shape and the
+  chart fails to parse.
+- **Hide small paths with a stated minimum.** Choose a minimum (for example 25), drop the paths
+  under it, and write a note that names them and their total: "Not drawn because fewer than 25
+  cases took them: X to Y (12), ... (41 in total)." A chart that drops paths without a note looks
+  complete and is not.
+- **Merge small boxes into one named box, and say so.** When you merge, the count is a sum of
+  rounded or filtered parts: write `(about 600)`, and say in the note what the box holds.
+- **Put the date and the time zone on the chart.** Write the title as HTML inside the zoomable
+  stage (the template does this from `data-title` and `data-sub`), so it stays with the chart in
+  full screen and in screenshots. Do not use a frontmatter `title:` as well: it would show a second title. Give the
+  local day and the UTC window: `Mon 5 Oct 2026 (4 Oct 23:00 to 5 Oct 23:00 UTC)`.
+- **Name the unit.** "Counts in brackets are calls / orders / cases." A count with no unit gets
+  read as the wrong one.
+
+## Node types and the legend
+
+- One `classDef` per node type, and one `class id1,id2 type;` line per type. The converter writes
+  these from `nodes.csv`.
+- **In-scope boxes get a thick border** (`stroke-width:3px`), so the reader finds the subject of
+  the chart first.
+- **Optional or owner-choice boxes get a dashed border** (`stroke-dasharray:6 4`): a step that is
+  a decision still open, or one that runs only for some cases.
+- End boxes share one quiet grey class. Stubs share one class: white fill, thin dashed grey
+  border (`stroke-dasharray:3 3`), so they read as pointers, not steps.
+- Put a legend above the chart with one swatch per type, with the same fill, border width and
+  dash as the chart. Use light fills with dark text. Keep the chart canvas light in dark mode
+  too (the template's `--canvas` token does this), or the dark text loses contrast.
+
+## Layout fixes that work
+
+Mermaid's layout (dagre) puts each node on a rank and orders each rank to cut crossings. It does
+not know what the reader looks for. These fixes move it.
+
+1. **Draw the chart as a tree.** Give every box exactly one parent edge: the biggest path into
+   it. For every other path into that box, add a small dashed stub under its own source,
+   labelled with the target and the count: `B --> toB_C(["to C (412)"])`. Shared targets and
+   back-edges are what make the layout cross lines; a tree with stubs has none. Add a legend
+   entry for stubs ("dashed: the path continues at the box named"). The converter does this by
+   default (`--no-tree` turns it off).
+2. **Give each source its own end box.** One shared "Ends" box pulls a long line from every step
+   across the chart. Write `A --> endA(["Ends"])` and `B --> endB(["Ends"])` instead. The
+   converter does this. Apply the same fix to any shared target that sits far from its sources:
+   a copy of the box next to each source is easier to read than one box with crossing lines.
+3. **Do not draw a loop-back as an edge.** A line back up the chart crosses everything. End the
+   path in a stub: `A --> backA(["back to Triage (190)"])`. The converter does this for every
+   edge that points back to a step on the path.
+4. **Put a side flow in its own subgraph and push it down.** For example the steps after a
+   hand-off. Draw them in `subgraph AFTER[...] direction LR ... end` and add an invisible link
+   from a low node of the main flow: `X2 ~~~ AFTER`. The subgraph then sits under the main
+   flow, not beside it.
+5. **Put same-kind boxes in one row.** Group them in a subgraph, and lengthen the edges into it
+   (`---->`, one dash per extra rank) so they land on the same rank.
+6. **Replace a long jump with a short stub or a dotted link.** When an edge must reach a box
+   far away, end it in a small stub node near the source, or draw it dotted (`-.->`) with a
+   label such as `"few"`, so the eye can tell it is secondary.
+7. **Order the edges from a node in the order you want the boxes, left to right**, and declare
+   the nodes in the same order. Dagre takes this as its first guess. It can still swap them to
+   cut crossings: check the screenshot.
+8. **Quote every label that holds brackets, quotes or `<br/>`:** `["Text<br/>(12)"]`,
+   `|"(12)"|`. Write a quote inside a label as `#quot;`.
+
+Change one thing at a time and re-render. Two fixes at once hide which one helped.
+
+## Wording
+
+- **Use the process owner's words for box labels** when a glossary or a list of step names
+  exists. A reader checks the chart against those names.
+- **Write neutral endings.** "Case ends" or "Call ends" means the data shows no further step.
+  Do not write a guess such as "hangs up" or "gives up": the data does not say who ended it.
+  Say what "ends" means in the note.
+- **Mark your own reading.** When a label or a grouping is your interpretation, not a name from
+  the source, say so in the note ("'Team queues' is our grouping of four queues").
+
+## Verify
+
+`scripts/check-render.mjs` fails (exit 1) when a chart has no SVG, shows an error message, has
+fewer nodes than `--min-nodes`, or the page throws. Make it fail once on purpose (break one
+line of the source) to see that it can. It also counts box overlaps and arrow labels on boxes
+as warnings. Those are hints: open the screenshots and run the tidy checklist by eye, because
+the check cannot see a crossing line.
+
+Also check the numbers, not only the drawing: the START count equals the cases in the window,
+and no arrow into or out of a box is larger than the box (the converter warns when one is).
+
+## Publishing
+
+- As an Artifact: follow the artifact-design rules. Mermaid loads from
+  `https://cdnjs.cloudflare.com/ajax/libs/mermaid/10.9.1/mermaid.min.js` (an exact version on the
+  allowed CDN). The template already has theme tokens for light and dark, an explicit body
+  background, and a 16px side gutter for phone width.
+- In an app: render with the app's own Mermaid package and keep the same source, title and note.
+  Keep the count rules; they are what makes the chart trustworthy.