@sylad/cadence 1.6.0 → 1.7.0

package/docs/deliver.md

@@ -0,0 +1,204 @@
+[← cadence](../README.md)
+
+# deliver
+
+A delivery is done when its checks pass, not when a tool says "success".
+
+```yaml
+# cadence.yaml, at the repository root
+deliver:
+  ci: github              # github | none | { command: "…" }   (default: none)
+  ciTimeout: 1800         # seconds
+  deploy:                 # sh commands, in order, at the repo root
+    - ./scripts/deploy.sh "$CADENCE_SHORT"
+  verify:                 # at least one; retried every 10 s until verifyTimeout
+    - url: https://app.example.com/api/health
+      status: 200         # default 200
+    - url: https://app.example.com/version.txt
+      contains: "${SHORT}"
+    - command: kubectl rollout status deploy/app --timeout=60s
+  verifyTimeout: 300
+  deployTimeout: 1800     # seconds, per deploy command
+```
+
+A public title (`public:`) longer than the site's Plan page accepts fails its build. Declare the limit
+in `cadence.yaml` and it is caught before the push:
+
+```yaml
+news:
+  publicTitleMax: 80      # characters; without the key, `raf check` warns at 80 in a project that has a news directory
+```
+
+`raf check` also warns (`⚠`, not an error: exit code 0 if nothing else is wrong) about every visible lot, dropped ones excepted, that has no public title: the site would show its technical title (a done lot cited by a News entry is spared: the site reuses that entry's title). Fix it with `raf public <id> "…"`. On a plan kept by another tool (read-only), the warning only applies if `plan.fields` maps a `public` field, or if some lot already carries a literal `public:` key (a field left out is read under its own name): without either there is no public title to set, so it would come back at every session.
+
+With the key, `raf public`, `raf add --public`, `raf done` (on a lot whose public title is too long) and
+`cadence news new` (its title) refuse above it; without it, only `raf check` warns.
+
+```sh
+cadence deliver --dry-run    # preconditions, then the resolved steps; nothing runs
+cadence deliver              # 0 delivered and verified · 1 a step failed · 2 refused before acting
+```
+
+- **Preconditions**: no modified tracked file; `HEAD` is on a remote branch (the
+  CI can only build what was pushed); no other delivery running (a lock whose
+  process died is removed with a warning); with `ci: github`, `gh` installed and
+  logged in.
+- Every command is killed when it exceeds its budget (CI, `deployTimeout`, what is
+  left of `verifyTimeout`) and reported as "délai dépassé". Killed means the
+  whole tree, followed while the command runs: every 200 ms cadence lists the
+  command's descendants and remembers each process it has seen with its start
+  time, so a process whose parent exits (re-parented to init — a background
+  child of a script, `sh`'s fork for each command) stays known. To kill, cadence
+  takes every remembered process still alive with the same start time (never a
+  recycled pid) plus all its current descendants, stops each one first
+  (`SIGSTOP`, the tree is re-read until nothing new appears), then kills them
+  (`SIGKILL`). This happens on a delay overrun, and at once when cadence
+  receives `SIGTERM`. On Ctrl-C or a hangup the tree has already received the
+  signal from the terminal: cadence gives the whole followed set, not just the
+  command, up to 2 seconds to finish (a script's `trap`, git removing its
+  `index.lock`), carries on the moment none of it is alive, and kills what is
+  left after the 2 seconds, a background child that ignores Ctrl-C included. If
+  the command was never listed (process list unreadable from the start), the
+  grace lasts as long as the command itself is alive, and what remains after
+  2 seconds is killed through the same fallback (the command itself only). The
+  same fallback applies when the process list fails while the command runs and
+  is still failing when the kill comes (the last listing is not trusted after
+  1 second): only the command is killed, its descendants survive, and cadence
+  says so once on stderr.
+  A delay overrun and `SIGTERM` give no grace: a script's own `trap` does not
+  get to finish there. The lock is held until the followed set is empty: when
+  cadence dies of the signal it dies after the tree, and its stale lock, which
+  the next delivery removes, leaves nothing of the first delivery running.
+  What can still outlive cadence and run concurrently with the next delivery:
+  a process that leaves the tree before cadence first sees it (a daemon's
+  double fork, `setsid`, `nohup … &` from a shell that exits, all within less
+  than 200 ms), a process of another user that cadence may not signal (`sudo`),
+  a background process still running when the command returns normally (it is
+  neither waited for nor killed), and everything if cadence itself is killed
+  with `SIGKILL` (`kill -9`, the OOM killer).
+  Where the process list cannot be read (no `/proc` and `ps` failing), cadence
+  can only kill the root command (`sh`): it leads no group of its own, since it
+  is deliberately kept in cadence's group, so its descendants are not killed and
+  survive it. A list that fails for more than a second is no longer
+  trusted (a followed pid may have been recycled): nothing is signalled from it.
+  cadence says so once on stderr when the list is unavailable.
+- Commands run in cadence's own process group and session, attached to the
+  terminal: `ssh`, `sudo` or `pinentry` can prompt on `/dev/tty`, and Ctrl-C or
+  closing the terminal stops the running command together with cadence (within
+  the limits above).
+- **CI** `github`: polls `gh run list --commit <sha>` every 15 s; no run after
+  5 minutes is a failure (you probably pushed another commit than the one you
+  deliver); every run must end `success`, `skipped` or `neutral`. `gh` errors
+  are retried, and reported with their cause after 5 minutes.
+- Commands get `CADENCE_SHA`, `CADENCE_SHORT` (7 characters) and `CADENCE_BRANCH`;
+  `${SHA}` and `${SHORT}` are replaced in `url` and `contains`.
+- On success the lots cited by the commits since the previous delivery are
+  listed, so you can `raf done` those whose effect you have seen. With a
+  read-only plan, only the lots that were in progress when the delivery started
+  are listed: an id quoted in a message for context (a finished lot, a
+  reservation number that looks like one) is not a delivered lot. Plan upkeep
+  commits (see "Plan upkeep needs no lot") are skipped in that list: they cite
+  lots without delivering anything.
+- With [`docs.articles`](news.md#an-article-elsewhere-that-follows-the-delivery), a green delivery of lots with a
+  public title also opens the lot `Article <project> à rafraîchir` in the plan.
+
+## A project with its own delivery script
+
+A project that already delivers with its own script (CI wait, deploy, business
+checks) plugs it in instead of rewriting it as `ci` / `deploy` / `verify`:
+
+```yaml
+deliver:
+  script: ./scripts/ship.sh "$CADENCE_SHORT"   # replaces ci and deploy
+  allowDirty: true                             # optional: a modified tree is reported, not refused
+  deployTimeout: 3600                          # seconds, for the whole script
+  verify: []                                   # optional here: the script's own checks count
+```
+
+```sh
+cadence deliver -- api frontend --news docs/changelog/x.md -- map    # everything after the first « -- » goes to the script
+cadence deliver --dry-run -- api                                      # shows the full command, runs nothing
+cadence deliver --sha 6b0d9aa -- api                                  # an earlier pushed commit instead of HEAD
+```
+
+`--sha` (any mode) delivers a pushed commit other than `HEAD` — for a CI that
+builds each service only on the commit that touched it. `allowDirty` suits a
+working tree shared by several sessions when the delivery starts from a pushed
+sha and never from local files; without it a modified tree is refused.
+
+cadence keeps what the script usually lacks: the preconditions (clean tree, pushed
+`HEAD`), the lock (never two deliveries at once), the delivery log and the lots
+delivered. Arguments are quoted for `sh`, so spaces and quotes reach the script
+intact. If the script commits and pushes during the delivery (stamping a
+changelog entry, say), the new `HEAD` is the sha recorded as delivered. Exit code
+0 of the script means delivered; `verify` checks, if any, run after it.
+
+## verify: replay the effect checks, outside a delivery
+
+A green delivery says the effect was right *then*. `cadence verify` replays the
+`deliver.verify` checks of `cadence.yaml` at any time — no CI, no deploy, no lock,
+no journal entry, nothing written.
+
+```sh
+cadence verify                # one pass, one line per check, then a one-line summary
+cadence verify --retry 60     # retry each failing check for up to 60 s (deliver's 300 s is not applied)
+cadence verify --sha 6b0d9aa  # the sha that replaces ${SHA} / ${SHORT} (default: see below)
+```
+
+```
+✓ GET https://ol.example/api/health → 200
+✗ GET https://ol.example/api/lineup → 200, contient « "starters" » — « "starters" » absent de la réponse
+verify : 1 effet rouge sur 2 vérifications
+```
+
+Exit code: **0** every check green · **1** at least one red effect · **2** nothing
+to verify or invalid configuration.
+
+**Which sha is expected.** By default `${SHA}` / `${SHORT}` is the last recorded
+delivery (else `HEAD`). One case differs: a project with `ci: none` (the default) and
+**neither** deploy commands (`deliver.deploy`) nor a delivery script — a host that
+builds every push, like Cloudflare Pages — delivers by pushing, and every push counts,
+plan-maintenance commits included. The expected sha is then the head of the tracked
+upstream branch (`origin/<branch>`, as last fetched — `verify` does no network git),
+**provided that upstream is the remote's production branch**: read without network from
+`refs/remotes/origin/HEAD` (set by `git clone` or `git remote set-head origin <branch>`);
+when that reference does not exist locally (repository created with `git init` + push),
+`main` then `master` are taken as the production branch. A work branch pushed with `-u`
+is not published by such a host, so it keeps the default rule. A project with `ci: github`
+or a `ci.command` and no deploy also keeps the last delivery. When local `HEAD` is ahead
+of the upstream, the report says so first — `2 commit(s) non poussé(s) — l'effet vérifié
+est celui de origin/main` — so a red there reads "waiting for a push", not "broken
+effect". `session start` uses the same rule; `--sha` always wins.
+
+Time limits differ from deliver's. `verify` runs all the checks **in parallel**,
+each try with the whole 120 s limit (a `url` request gives up after 20 s; a slow
+check is killed at its limit, "délai dépassé", and takes nothing from the others); results are printed in the order
+of `cadence.yaml`. Retries repeat every 10 s (deliver's interval) up to `--retry`
+seconds for each check on its own, so a run lasts at most `--retry` + 120 s.
+deliver, by contrast, runs its checks one after the other, retries each until
+`verifyTimeout` (300 s by default) is spent, and stops at the first check that
+never turns green. The check code is deliver's own (`url` / `status` /
+`contains` / `command`, same messages). A project with
+a delivery script (`deliver.script`) and no `verify` declares no effect checks —
+`verify` says so and exits 2 (its script's own checks stay its business); add
+`deliver.verify` to replay some.
+
+Each `command` check of `verify` (and of `session start`) runs in a process group
+of its own, detached from the terminal (no `/dev/tty`: a check must not prompt).
+At its time limit the whole group is killed, so no child survives it; Ctrl-C,
+`SIGTERM` or a closed terminal is passed on to the running checks before cadence
+exits. As the checks run together, the output of their commands may interleave;
+the result lines come after it, in order.
+
+Make `verify` count: a health endpoint stays green while the data is wrong (a
+lineup served empty for 38 h behind a green `/api/health`). Add a check on the
+content that matters, e.g. `url: …/api/lineup` with `contains: '"starters"'`.
+
+`cadence session start` runs the same checks in parallel (one try each, command
+output muted), each with a 10 s limit, so the whole step takes about 10 s at worst;
+it is not deliver's `verifyTimeout`, and there is no retry. It adds an
+**"Effets en production"** section to the morning report: a single `✓` line when
+everything is green, the red effects and the summary otherwise. It is a fact like
+the others: it never changes the exit code, and an unreachable network shows up
+as red lines ("erreur réseau") without blocking the session. No section for a
+project without `deliver.verify`.

package/docs/fonctionnement-lead-dark.svg

@@ -0,0 +1,101 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1290 372" width="1290" height="372" role="img" font-family="-apple-system,BlinkMacSystemFont,'Segoe UI',Helvetica,Arial,sans-serif" font-size="13" fill="#e6edf3">
+<title>The lead drives the waves</title>
+<desc>Three lanes: the human chooses and decides, the lead starts, relays, re-verifies and delivers, the orchestrate program runs the lots and chains the next wave while the context stays under 60 percent.</desc>
+<defs><marker id="arr3" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path d="M0,0 L10,5 L0,10 z" fill="#8b949e"/></marker></defs>
+<rect width="1290" height="372" fill="#0d1117"/>
+<rect x="0" y="30" width="1290" height="90" fill="#161b22"/>
+<rect x="0" y="230" width="1290" height="90" fill="#161b22"/>
+<text x="12" y="71" text-anchor="start" font-weight="600" font-size="13.5" fill="#e6edf3">Human</text>
+<text x="12" y="88" text-anchor="start" font-size="11.5" fill="#8b949e">chooses, decides</text>
+<text x="12" y="171" text-anchor="start" font-weight="600" font-size="13.5" fill="#e6edf3">Lead</text>
+<text x="12" y="188" text-anchor="start" font-size="11.5" fill="#8b949e">short session</text>
+<text x="12" y="271" text-anchor="start" font-weight="600" font-size="13.5" fill="#e6edf3">orchestrate</text>
+<text x="12" y="288" text-anchor="start" font-size="11.5" fill="#8b949e">fresh sessions</text>
+<text x="200" y="20" text-anchor="middle" font-weight="600" font-size="12" letter-spacing="0.7" fill="#8b949e">1 TOUR</text>
+<text x="344" y="20" text-anchor="middle" font-weight="600" font-size="12" letter-spacing="0.7" fill="#8b949e">2 WAVE</text>
+<text x="488" y="20" text-anchor="middle" font-weight="600" font-size="12" letter-spacing="0.7" fill="#8b949e">3 RELAY</text>
+<text x="632" y="20" text-anchor="middle" font-weight="600" font-size="12" letter-spacing="0.7" fill="#8b949e">4 TABLE</text>
+<text x="776" y="20" text-anchor="middle" font-weight="600" font-size="12" letter-spacing="0.7" fill="#8b949e">5 RE-CHECK</text>
+<text x="920" y="20" text-anchor="middle" font-weight="600" font-size="12" letter-spacing="0.7" fill="#8b949e">6 DELIVERY</text>
+<text x="1064" y="20" text-anchor="middle" font-weight="600" font-size="12" letter-spacing="0.7" fill="#8b949e">7 THRESHOLD</text>
+<text x="1208" y="20" text-anchor="middle" font-weight="600" font-size="12" letter-spacing="0.7" fill="#8b949e">8 CLOSE</text>
+<rect x="136" y="46" width="128" height="58" rx="6" fill="#0d1117" stroke="#8b949e" stroke-width="1.5"/>
+<text x="200" y="71.5" text-anchor="middle" font-weight="600" font-size="13.5" fill="#e6edf3">Chooses</text>
+<text x="200" y="86.5" text-anchor="middle" font-size="11.5" fill="#8b949e">lots + order</text>
+<rect x="424" y="46" width="128" height="58" rx="6" fill="#0d1117" stroke="#8b949e" stroke-width="1.5" stroke-dasharray="6 4"/>
+<text x="488" y="71.5" text-anchor="middle" font-weight="600" font-size="13.5" fill="#e6edf3">Answers</text>
+<text x="488" y="86.5" text-anchor="middle" font-size="11.5" fill="#8b949e">on a question</text>
+<rect x="712" y="46" width="128" height="58" rx="6" fill="#0d1117" stroke="#8b949e" stroke-width="1.5" stroke-dasharray="6 4"/>
+<text x="776" y="71.5" text-anchor="middle" font-weight="600" font-size="13.5" fill="#e6edf3">UX verdict</text>
+<text x="776" y="86.5" text-anchor="middle" font-size="11.5" fill="#8b949e">or lead (lead.ux)</text>
+<rect x="1144" y="46" width="128" height="58" rx="6" fill="#0d1117" stroke="#8b949e" stroke-width="1.5"/>
+<text x="1208" y="71.5" text-anchor="middle" font-weight="600" font-size="13.5" fill="#e6edf3">Report</text>
+<text x="1208" y="86.5" text-anchor="middle" font-size="11.5" fill="#8b949e">1 line / project</text>
+<rect x="136" y="146" width="128" height="58" rx="6" fill="#0d1117" stroke="#8b949e" stroke-width="1.5"/>
+<text x="200" y="171.5" text-anchor="middle" font-weight="600" font-size="13.5" fill="#e6edf3">lead tour</text>
+<text x="200" y="186.5" text-anchor="middle" font-size="11.5" fill="#8b949e">3 proposals</text>
+<rect x="280" y="146" width="128" height="58" rx="6" fill="#0d1117" stroke="#8b949e" stroke-width="1.5"/>
+<text x="344" y="171.5" text-anchor="middle" font-weight="600" font-size="13.5" fill="#e6edf3">Starts</text>
+<text x="344" y="186.5" text-anchor="middle" font-size="11.5" font-family="ui-monospace,SFMono-Regular,Menlo,monospace" fill="#8b949e">--wave</text>
+<rect x="424" y="146" width="128" height="58" rx="6" fill="#0d1117" stroke="#8b949e" stroke-width="1.5"/>
+<text x="488" y="171.5" text-anchor="middle" font-weight="600" font-size="13.5" fill="#e6edf3">Relays</text>
+<text x="488" y="186.5" text-anchor="middle" font-size="11.5" fill="#8b949e">1 sentence / line</text>
+<rect x="568" y="146" width="128" height="58" rx="6" fill="#0d1117" stroke="#8b949e" stroke-width="1.5"/>
+<text x="632" y="171.5" text-anchor="middle" font-weight="600" font-size="13.5" fill="#e6edf3">Triages</text>
+<text x="632" y="186.5" text-anchor="middle" font-size="11.5" fill="#8b949e">observable bug → lot</text>
+<rect x="712" y="146" width="128" height="58" rx="6" fill="#0c2d6b" stroke="#58a6ff" stroke-width="2"/>
+<text x="776" y="171.5" text-anchor="middle" font-weight="600" font-size="13.5" fill="#e6edf3">Re-verifies</text>
+<text x="776" y="186.5" text-anchor="middle" font-size="11.5" fill="#8b949e">tests · build · check</text>
+<rect x="856" y="146" width="128" height="58" rx="6" fill="#0d1117" stroke="#8b949e" stroke-width="1.5"/>
+<text x="920" y="171.5" text-anchor="middle" font-weight="600" font-size="13.5" fill="#e6edf3">Delivers</text>
+<text x="920" y="186.5" text-anchor="middle" font-size="11.5" fill="#8b949e">push + deliver</text>
+<rect x="1000" y="146" width="128" height="58" rx="6" fill="#0d1117" stroke="#8b949e" stroke-width="1.5"/>
+<text x="1064" y="171.5" text-anchor="middle" font-weight="600" font-size="13.5" fill="#e6edf3">&lt; 60 % ?</text>
+<text x="1064" y="186.5" text-anchor="middle" font-size="11.5" font-family="ui-monospace,SFMono-Regular,Menlo,monospace" fill="#8b949e">session context</text>
+<rect x="1144" y="146" width="128" height="58" rx="6" fill="#0d1117" stroke="#8b949e" stroke-width="1.5"/>
+<text x="1208" y="171.5" text-anchor="middle" font-weight="600" font-size="13.5" fill="#e6edf3">Close</text>
+<text x="1208" y="186.5" text-anchor="middle" font-size="11.5" fill="#8b949e">if ≥ 60 %</text>
+<rect x="280" y="246" width="128" height="58" rx="6" fill="#0d1117" stroke="#8b949e" stroke-width="1.5"/>
+<text x="344" y="271.5" text-anchor="middle" font-weight="600" font-size="13.5" fill="#e6edf3">Lots</text>
+<text x="344" y="286.5" text-anchor="middle" font-size="11.5" fill="#8b949e">figure 2, per lot</text>
+<rect x="424" y="246" width="128" height="58" rx="6" fill="#0d1117" stroke="#8b949e" stroke-width="1.5"/>
+<text x="488" y="271.5" text-anchor="middle" font-weight="600" font-size="13.5" fill="#e6edf3">journal.log</text>
+<text x="488" y="286.5" text-anchor="middle" font-size="11.5" fill="#8b949e">1 line / transition</text>
+<rect x="568" y="246" width="128" height="58" rx="6" fill="#0d1117" stroke="#8b949e" stroke-width="1.5"/>
+<text x="632" y="271.5" text-anchor="middle" font-weight="600" font-size="13.5" fill="#e6edf3">Final table</text>
+<text x="632" y="286.5" text-anchor="middle" font-size="11.5" fill="#8b949e">ready · handed back</text>
+<rect x="856" y="246" width="128" height="58" rx="6" fill="#0d1117" stroke="#8b949e" stroke-width="1.5"/>
+<text x="920" y="271.5" text-anchor="middle" font-weight="600" font-size="13.5" fill="#e6edf3">qa-reviewer</text>
+<text x="920" y="286.5" text-anchor="middle" font-size="11.5" fill="#8b949e">read only</text>
+<rect x="1000" y="246" width="128" height="58" rx="6" fill="#0d1117" stroke="#8b949e" stroke-width="1.5"/>
+<text x="1064" y="271.5" text-anchor="middle" font-weight="600" font-size="13.5" fill="#e6edf3">--continue</text>
+<text x="1064" y="286.5" text-anchor="middle" font-size="11.5" fill="#8b949e">next ready lot</text>
+<polyline points="180,146 180,106" fill="none" stroke="#8b949e" stroke-width="1.5" marker-end="url(#arr3)"/>
+<polyline points="264,75 344,75 344,144" fill="none" stroke="#8b949e" stroke-width="1.5" marker-end="url(#arr3)"/>
+<text x="300" y="68" text-anchor="middle" font-size="11.5" fill="#8b949e">priority</text>
+<polyline points="408,175 422,175" fill="none" stroke="#8b949e" stroke-width="1.5" marker-end="url(#arr3)"/>
+<polyline points="552,175 566,175" fill="none" stroke="#8b949e" stroke-width="1.5" marker-end="url(#arr3)"/>
+<polyline points="696,175 710,175" fill="none" stroke="#8b949e" stroke-width="1.5" marker-end="url(#arr3)"/>
+<polyline points="840,175 854,175" fill="none" stroke="#8b949e" stroke-width="1.5" marker-end="url(#arr3)"/>
+<polyline points="984,175 998,175" fill="none" stroke="#8b949e" stroke-width="1.5" marker-end="url(#arr3)"/>
+<polyline points="1128,175 1142,175" fill="none" stroke="#8b949e" stroke-width="1.5" marker-end="url(#arr3)"/>
+<polyline points="344,204 344,244" fill="none" stroke="#8b949e" stroke-width="1.5" marker-end="url(#arr3)"/>
+<text x="350" y="228" text-anchor="start" font-size="11.5" fill="#8b949e">starts</text>
+<polyline points="408,275 422,275" fill="none" stroke="#8b949e" stroke-width="1.5" marker-end="url(#arr3)"/>
+<polyline points="552,275 566,275" fill="none" stroke="#8b949e" stroke-width="1.5" marker-end="url(#arr3)"/>
+<polyline points="488,246 488,206" fill="none" stroke="#8b949e" stroke-width="1.5" marker-end="url(#arr3)"/>
+<text x="494" y="230" text-anchor="start" font-size="11.5" fill="#8b949e">journal</text>
+<polyline points="488,146 488,106" fill="none" stroke="#8b949e" stroke-width="1.5" stroke-dasharray="5 4" marker-end="url(#arr3)"/>
+<text x="494" y="130" text-anchor="start" font-size="11.5" fill="#8b949e">question</text>
+<polyline points="632,246 632,206" fill="none" stroke="#8b949e" stroke-width="1.5" marker-end="url(#arr3)"/>
+<text x="638" y="230" text-anchor="start" font-size="11.5" fill="#8b949e">wave ends</text>
+<polyline points="776,146 776,106" fill="none" stroke="#8b949e" stroke-width="1.5" stroke-dasharray="5 4" marker-end="url(#arr3)"/>
+<text x="782" y="130" text-anchor="start" font-size="11.5" fill="#8b949e">captures</text>
+<polyline points="920,204 920,244" fill="none" stroke="#8b949e" stroke-width="1.5" marker-end="url(#arr3)"/>
+<text x="926" y="228" text-anchor="start" font-size="11.5" fill="#8b949e">if a page changes</text>
+<polyline points="1064,204 1064,244" fill="none" stroke="#8b949e" stroke-width="1.5" marker-end="url(#arr3)"/>
+<text x="1070" y="228" text-anchor="start" font-size="11.5" fill="#8b949e">yes</text>
+<polyline points="1208,146 1208,106" fill="none" stroke="#8b949e" stroke-width="1.5" marker-end="url(#arr3)"/>
+<polyline points="1064,304 1064,346 344,346 344,306" fill="none" stroke="#8b949e" stroke-width="1.5" marker-end="url(#arr3)"/>
+<text x="704" y="340" text-anchor="middle" font-size="11.5" fill="#8b949e">next wave, without asking the human again</text>
+</svg>

package/docs/fonctionnement-lead-light.svg

@@ -0,0 +1,101 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1290 372" width="1290" height="372" role="img" font-family="-apple-system,BlinkMacSystemFont,'Segoe UI',Helvetica,Arial,sans-serif" font-size="13" fill="#1f2328">
+<title>The lead drives the waves</title>
+<desc>Three lanes: the human chooses and decides, the lead starts, relays, re-verifies and delivers, the orchestrate program runs the lots and chains the next wave while the context stays under 60 percent.</desc>
+<defs><marker id="arr3" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path d="M0,0 L10,5 L0,10 z" fill="#57606a"/></marker></defs>
+<rect width="1290" height="372" fill="#ffffff"/>
+<rect x="0" y="30" width="1290" height="90" fill="#f6f8fa"/>
+<rect x="0" y="230" width="1290" height="90" fill="#f6f8fa"/>
+<text x="12" y="71" text-anchor="start" font-weight="600" font-size="13.5" fill="#1f2328">Human</text>
+<text x="12" y="88" text-anchor="start" font-size="11.5" fill="#57606a">chooses, decides</text>
+<text x="12" y="171" text-anchor="start" font-weight="600" font-size="13.5" fill="#1f2328">Lead</text>
+<text x="12" y="188" text-anchor="start" font-size="11.5" fill="#57606a">short session</text>
+<text x="12" y="271" text-anchor="start" font-weight="600" font-size="13.5" fill="#1f2328">orchestrate</text>
+<text x="12" y="288" text-anchor="start" font-size="11.5" fill="#57606a">fresh sessions</text>
+<text x="200" y="20" text-anchor="middle" font-weight="600" font-size="12" letter-spacing="0.7" fill="#57606a">1 TOUR</text>
+<text x="344" y="20" text-anchor="middle" font-weight="600" font-size="12" letter-spacing="0.7" fill="#57606a">2 WAVE</text>
+<text x="488" y="20" text-anchor="middle" font-weight="600" font-size="12" letter-spacing="0.7" fill="#57606a">3 RELAY</text>
+<text x="632" y="20" text-anchor="middle" font-weight="600" font-size="12" letter-spacing="0.7" fill="#57606a">4 TABLE</text>
+<text x="776" y="20" text-anchor="middle" font-weight="600" font-size="12" letter-spacing="0.7" fill="#57606a">5 RE-CHECK</text>
+<text x="920" y="20" text-anchor="middle" font-weight="600" font-size="12" letter-spacing="0.7" fill="#57606a">6 DELIVERY</text>
+<text x="1064" y="20" text-anchor="middle" font-weight="600" font-size="12" letter-spacing="0.7" fill="#57606a">7 THRESHOLD</text>
+<text x="1208" y="20" text-anchor="middle" font-weight="600" font-size="12" letter-spacing="0.7" fill="#57606a">8 CLOSE</text>
+<rect x="136" y="46" width="128" height="58" rx="6" fill="#ffffff" stroke="#57606a" stroke-width="1.5"/>
+<text x="200" y="71.5" text-anchor="middle" font-weight="600" font-size="13.5" fill="#1f2328">Chooses</text>
+<text x="200" y="86.5" text-anchor="middle" font-size="11.5" fill="#57606a">lots + order</text>
+<rect x="424" y="46" width="128" height="58" rx="6" fill="#ffffff" stroke="#57606a" stroke-width="1.5" stroke-dasharray="6 4"/>
+<text x="488" y="71.5" text-anchor="middle" font-weight="600" font-size="13.5" fill="#1f2328">Answers</text>
+<text x="488" y="86.5" text-anchor="middle" font-size="11.5" fill="#57606a">on a question</text>
+<rect x="712" y="46" width="128" height="58" rx="6" fill="#ffffff" stroke="#57606a" stroke-width="1.5" stroke-dasharray="6 4"/>
+<text x="776" y="71.5" text-anchor="middle" font-weight="600" font-size="13.5" fill="#1f2328">UX verdict</text>
+<text x="776" y="86.5" text-anchor="middle" font-size="11.5" fill="#57606a">or lead (lead.ux)</text>
+<rect x="1144" y="46" width="128" height="58" rx="6" fill="#ffffff" stroke="#57606a" stroke-width="1.5"/>
+<text x="1208" y="71.5" text-anchor="middle" font-weight="600" font-size="13.5" fill="#1f2328">Report</text>
+<text x="1208" y="86.5" text-anchor="middle" font-size="11.5" fill="#57606a">1 line / project</text>
+<rect x="136" y="146" width="128" height="58" rx="6" fill="#ffffff" stroke="#57606a" stroke-width="1.5"/>
+<text x="200" y="171.5" text-anchor="middle" font-weight="600" font-size="13.5" fill="#1f2328">lead tour</text>
+<text x="200" y="186.5" text-anchor="middle" font-size="11.5" fill="#57606a">3 proposals</text>
+<rect x="280" y="146" width="128" height="58" rx="6" fill="#ffffff" stroke="#57606a" stroke-width="1.5"/>
+<text x="344" y="171.5" text-anchor="middle" font-weight="600" font-size="13.5" fill="#1f2328">Starts</text>
+<text x="344" y="186.5" text-anchor="middle" font-size="11.5" font-family="ui-monospace,SFMono-Regular,Menlo,monospace" fill="#57606a">--wave</text>
+<rect x="424" y="146" width="128" height="58" rx="6" fill="#ffffff" stroke="#57606a" stroke-width="1.5"/>
+<text x="488" y="171.5" text-anchor="middle" font-weight="600" font-size="13.5" fill="#1f2328">Relays</text>
+<text x="488" y="186.5" text-anchor="middle" font-size="11.5" fill="#57606a">1 sentence / line</text>
+<rect x="568" y="146" width="128" height="58" rx="6" fill="#ffffff" stroke="#57606a" stroke-width="1.5"/>
+<text x="632" y="171.5" text-anchor="middle" font-weight="600" font-size="13.5" fill="#1f2328">Triages</text>
+<text x="632" y="186.5" text-anchor="middle" font-size="11.5" fill="#57606a">observable bug → lot</text>
+<rect x="712" y="146" width="128" height="58" rx="6" fill="#ddf4ff" stroke="#0969da" stroke-width="2"/>
+<text x="776" y="171.5" text-anchor="middle" font-weight="600" font-size="13.5" fill="#1f2328">Re-verifies</text>
+<text x="776" y="186.5" text-anchor="middle" font-size="11.5" fill="#57606a">tests · build · check</text>
+<rect x="856" y="146" width="128" height="58" rx="6" fill="#ffffff" stroke="#57606a" stroke-width="1.5"/>
+<text x="920" y="171.5" text-anchor="middle" font-weight="600" font-size="13.5" fill="#1f2328">Delivers</text>
+<text x="920" y="186.5" text-anchor="middle" font-size="11.5" fill="#57606a">push + deliver</text>
+<rect x="1000" y="146" width="128" height="58" rx="6" fill="#ffffff" stroke="#57606a" stroke-width="1.5"/>
+<text x="1064" y="171.5" text-anchor="middle" font-weight="600" font-size="13.5" fill="#1f2328">&lt; 60 % ?</text>
+<text x="1064" y="186.5" text-anchor="middle" font-size="11.5" font-family="ui-monospace,SFMono-Regular,Menlo,monospace" fill="#57606a">session context</text>
+<rect x="1144" y="146" width="128" height="58" rx="6" fill="#ffffff" stroke="#57606a" stroke-width="1.5"/>
+<text x="1208" y="171.5" text-anchor="middle" font-weight="600" font-size="13.5" fill="#1f2328">Close</text>
+<text x="1208" y="186.5" text-anchor="middle" font-size="11.5" fill="#57606a">if ≥ 60 %</text>
+<rect x="280" y="246" width="128" height="58" rx="6" fill="#ffffff" stroke="#57606a" stroke-width="1.5"/>
+<text x="344" y="271.5" text-anchor="middle" font-weight="600" font-size="13.5" fill="#1f2328">Lots</text>
+<text x="344" y="286.5" text-anchor="middle" font-size="11.5" fill="#57606a">figure 2, per lot</text>
+<rect x="424" y="246" width="128" height="58" rx="6" fill="#ffffff" stroke="#57606a" stroke-width="1.5"/>
+<text x="488" y="271.5" text-anchor="middle" font-weight="600" font-size="13.5" fill="#1f2328">journal.log</text>
+<text x="488" y="286.5" text-anchor="middle" font-size="11.5" fill="#57606a">1 line / transition</text>
+<rect x="568" y="246" width="128" height="58" rx="6" fill="#ffffff" stroke="#57606a" stroke-width="1.5"/>
+<text x="632" y="271.5" text-anchor="middle" font-weight="600" font-size="13.5" fill="#1f2328">Final table</text>
+<text x="632" y="286.5" text-anchor="middle" font-size="11.5" fill="#57606a">ready · handed back</text>
+<rect x="856" y="246" width="128" height="58" rx="6" fill="#ffffff" stroke="#57606a" stroke-width="1.5"/>
+<text x="920" y="271.5" text-anchor="middle" font-weight="600" font-size="13.5" fill="#1f2328">qa-reviewer</text>
+<text x="920" y="286.5" text-anchor="middle" font-size="11.5" fill="#57606a">read only</text>
+<rect x="1000" y="246" width="128" height="58" rx="6" fill="#ffffff" stroke="#57606a" stroke-width="1.5"/>
+<text x="1064" y="271.5" text-anchor="middle" font-weight="600" font-size="13.5" fill="#1f2328">--continue</text>
+<text x="1064" y="286.5" text-anchor="middle" font-size="11.5" fill="#57606a">next ready lot</text>
+<polyline points="180,146 180,106" fill="none" stroke="#57606a" stroke-width="1.5" marker-end="url(#arr3)"/>
+<polyline points="264,75 344,75 344,144" fill="none" stroke="#57606a" stroke-width="1.5" marker-end="url(#arr3)"/>
+<text x="300" y="68" text-anchor="middle" font-size="11.5" fill="#57606a">priority</text>
+<polyline points="408,175 422,175" fill="none" stroke="#57606a" stroke-width="1.5" marker-end="url(#arr3)"/>
+<polyline points="552,175 566,175" fill="none" stroke="#57606a" stroke-width="1.5" marker-end="url(#arr3)"/>
+<polyline points="696,175 710,175" fill="none" stroke="#57606a" stroke-width="1.5" marker-end="url(#arr3)"/>
+<polyline points="840,175 854,175" fill="none" stroke="#57606a" stroke-width="1.5" marker-end="url(#arr3)"/>
+<polyline points="984,175 998,175" fill="none" stroke="#57606a" stroke-width="1.5" marker-end="url(#arr3)"/>
+<polyline points="1128,175 1142,175" fill="none" stroke="#57606a" stroke-width="1.5" marker-end="url(#arr3)"/>
+<polyline points="344,204 344,244" fill="none" stroke="#57606a" stroke-width="1.5" marker-end="url(#arr3)"/>
+<text x="350" y="228" text-anchor="start" font-size="11.5" fill="#57606a">starts</text>
+<polyline points="408,275 422,275" fill="none" stroke="#57606a" stroke-width="1.5" marker-end="url(#arr3)"/>
+<polyline points="552,275 566,275" fill="none" stroke="#57606a" stroke-width="1.5" marker-end="url(#arr3)"/>
+<polyline points="488,246 488,206" fill="none" stroke="#57606a" stroke-width="1.5" marker-end="url(#arr3)"/>
+<text x="494" y="230" text-anchor="start" font-size="11.5" fill="#57606a">journal</text>
+<polyline points="488,146 488,106" fill="none" stroke="#57606a" stroke-width="1.5" stroke-dasharray="5 4" marker-end="url(#arr3)"/>
+<text x="494" y="130" text-anchor="start" font-size="11.5" fill="#57606a">question</text>
+<polyline points="632,246 632,206" fill="none" stroke="#57606a" stroke-width="1.5" marker-end="url(#arr3)"/>
+<text x="638" y="230" text-anchor="start" font-size="11.5" fill="#57606a">wave ends</text>
+<polyline points="776,146 776,106" fill="none" stroke="#57606a" stroke-width="1.5" stroke-dasharray="5 4" marker-end="url(#arr3)"/>
+<text x="782" y="130" text-anchor="start" font-size="11.5" fill="#57606a">captures</text>
+<polyline points="920,204 920,244" fill="none" stroke="#57606a" stroke-width="1.5" marker-end="url(#arr3)"/>
+<text x="926" y="228" text-anchor="start" font-size="11.5" fill="#57606a">if a page changes</text>
+<polyline points="1064,204 1064,244" fill="none" stroke="#57606a" stroke-width="1.5" marker-end="url(#arr3)"/>
+<text x="1070" y="228" text-anchor="start" font-size="11.5" fill="#57606a">yes</text>
+<polyline points="1208,146 1208,106" fill="none" stroke="#57606a" stroke-width="1.5" marker-end="url(#arr3)"/>
+<polyline points="1064,304 1064,346 344,346 344,306" fill="none" stroke="#57606a" stroke-width="1.5" marker-end="url(#arr3)"/>
+<text x="704" y="340" text-anchor="middle" font-size="11.5" fill="#57606a">next wave, without asking the human again</text>
+</svg>

package/docs/fonctionnement-lot-dark.svg

@@ -0,0 +1,38 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1100 190" width="1100" height="190" role="img" font-family="-apple-system,BlinkMacSystemFont,'Segoe UI',Helvetica,Arial,sans-serif" font-size="13" fill="#e6edf3">
+<title>Life of a lot in the plan</title>
+<desc>A lot goes from todo to doing, receives commits that cite it, gets its review and UX verdicts, becomes done, then is delivered by cadence deliver.</desc>
+<defs><marker id="arr1" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path d="M0,0 L10,5 L0,10 z" fill="#8b949e"/></marker></defs>
+<rect width="1100" height="190" fill="#0d1117"/>
+<rect x="20" y="40" width="110" height="56" rx="6" fill="#0d1117" stroke="#8b949e" stroke-width="1.5"/>
+<text x="75" y="64.5" text-anchor="middle" font-weight="600" font-size="13.5" fill="#e6edf3">todo</text>
+<text x="75" y="79.5" text-anchor="middle" font-size="11.5" font-family="ui-monospace,SFMono-Regular,Menlo,monospace" fill="#8b949e">raf add</text>
+<rect x="230" y="40" width="130" height="56" rx="6" fill="#0d1117" stroke="#8b949e" stroke-width="1.5"/>
+<text x="295" y="64.5" text-anchor="middle" font-weight="600" font-size="13.5" fill="#e6edf3">doing</text>
+<text x="295" y="79.5" text-anchor="middle" font-size="11.5" fill="#8b949e">commits « Lx »</text>
+<rect x="470" y="40" width="170" height="56" rx="6" fill="#0d1117" stroke="#8b949e" stroke-width="1.5"/>
+<text x="555" y="64.5" text-anchor="middle" font-weight="600" font-size="13.5" fill="#e6edf3">Verdicts recorded</text>
+<text x="555" y="79.5" text-anchor="middle" font-size="11.5" font-family="ui-monospace,SFMono-Regular,Menlo,monospace" fill="#8b949e">raf review · raf ux</text>
+<rect x="740" y="40" width="110" height="56" rx="6" fill="#0d1117" stroke="#8b949e" stroke-width="1.5"/>
+<text x="795" y="64.5" text-anchor="middle" font-weight="600" font-size="13.5" fill="#e6edf3">done</text>
+<text x="795" y="79.5" text-anchor="middle" font-size="11.5" font-family="ui-monospace,SFMono-Regular,Menlo,monospace" fill="#8b949e">raf done</text>
+<rect x="950" y="40" width="130" height="56" rx="6" fill="#0c2d6b" stroke="#58a6ff" stroke-width="2"/>
+<text x="1015" y="64.5" text-anchor="middle" font-weight="600" font-size="13.5" fill="#e6edf3">Delivered</text>
+<text x="1015" y="79.5" text-anchor="middle" font-size="11.5" font-family="ui-monospace,SFMono-Regular,Menlo,monospace" fill="#8b949e">cadence deliver</text>
+<polyline points="130,68 228,68" fill="none" stroke="#8b949e" stroke-width="1.5" marker-end="url(#arr1)"/>
+<text x="180" y="60" text-anchor="middle" font-size="11.5" fill="#8b949e">raf start</text>
+<polyline points="360,68 468,68" fill="none" stroke="#8b949e" stroke-width="1.5" marker-end="url(#arr1)"/>
+<text x="415" y="60" text-anchor="middle" font-size="11.5" fill="#8b949e">reviews</text>
+<polyline points="640,68 738,68" fill="none" stroke="#8b949e" stroke-width="1.5" marker-end="url(#arr1)"/>
+<text x="690" y="60" text-anchor="middle" font-size="11.5" fill="#8b949e">gates passed</text>
+<polyline points="850,68 948,68" fill="none" stroke="#8b949e" stroke-width="1.5" marker-end="url(#arr1)"/>
+<text x="900" y="60" text-anchor="middle" font-size="11.5" fill="#8b949e">push</text>
+<text x="75" y="124" text-anchor="middle" font-size="11.5" fill="#8b949e">raf drop → dropped</text>
+<text x="295" y="124" text-anchor="middle" font-size="11.5" fill="#8b949e">pre-commit: hook.autostart</text>
+<text x="295" y="140" text-anchor="middle" font-size="11.5" fill="#8b949e">warn · refuse · start</text>
+<text x="555" y="124" text-anchor="middle" font-size="11.5" fill="#8b949e">review: any lot with commits</text>
+<text x="555" y="140" text-anchor="middle" font-size="11.5" fill="#8b949e">ux: visible lot</text>
+<text x="795" y="124" text-anchor="middle" font-size="11.5" fill="#8b949e">refused with an open sub-task</text>
+<text x="1015" y="124" text-anchor="middle" font-size="11.5" fill="#8b949e">CI of the sha → deploy</text>
+<text x="1015" y="140" text-anchor="middle" font-size="11.5" fill="#8b949e">→ effect checks</text>
+<text x="1015" y="164" text-anchor="middle" font-size="11.5" fill="#8b949e">visible lot: news entry + capture</text>
+</svg>

package/docs/fonctionnement-lot-light.svg

@@ -0,0 +1,38 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1100 190" width="1100" height="190" role="img" font-family="-apple-system,BlinkMacSystemFont,'Segoe UI',Helvetica,Arial,sans-serif" font-size="13" fill="#1f2328">
+<title>Life of a lot in the plan</title>
+<desc>A lot goes from todo to doing, receives commits that cite it, gets its review and UX verdicts, becomes done, then is delivered by cadence deliver.</desc>
+<defs><marker id="arr1" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path d="M0,0 L10,5 L0,10 z" fill="#57606a"/></marker></defs>
+<rect width="1100" height="190" fill="#ffffff"/>
+<rect x="20" y="40" width="110" height="56" rx="6" fill="#ffffff" stroke="#57606a" stroke-width="1.5"/>
+<text x="75" y="64.5" text-anchor="middle" font-weight="600" font-size="13.5" fill="#1f2328">todo</text>
+<text x="75" y="79.5" text-anchor="middle" font-size="11.5" font-family="ui-monospace,SFMono-Regular,Menlo,monospace" fill="#57606a">raf add</text>
+<rect x="230" y="40" width="130" height="56" rx="6" fill="#ffffff" stroke="#57606a" stroke-width="1.5"/>
+<text x="295" y="64.5" text-anchor="middle" font-weight="600" font-size="13.5" fill="#1f2328">doing</text>
+<text x="295" y="79.5" text-anchor="middle" font-size="11.5" fill="#57606a">commits « Lx »</text>
+<rect x="470" y="40" width="170" height="56" rx="6" fill="#ffffff" stroke="#57606a" stroke-width="1.5"/>
+<text x="555" y="64.5" text-anchor="middle" font-weight="600" font-size="13.5" fill="#1f2328">Verdicts recorded</text>
+<text x="555" y="79.5" text-anchor="middle" font-size="11.5" font-family="ui-monospace,SFMono-Regular,Menlo,monospace" fill="#57606a">raf review · raf ux</text>
+<rect x="740" y="40" width="110" height="56" rx="6" fill="#ffffff" stroke="#57606a" stroke-width="1.5"/>
+<text x="795" y="64.5" text-anchor="middle" font-weight="600" font-size="13.5" fill="#1f2328">done</text>
+<text x="795" y="79.5" text-anchor="middle" font-size="11.5" font-family="ui-monospace,SFMono-Regular,Menlo,monospace" fill="#57606a">raf done</text>
+<rect x="950" y="40" width="130" height="56" rx="6" fill="#ddf4ff" stroke="#0969da" stroke-width="2"/>
+<text x="1015" y="64.5" text-anchor="middle" font-weight="600" font-size="13.5" fill="#1f2328">Delivered</text>
+<text x="1015" y="79.5" text-anchor="middle" font-size="11.5" font-family="ui-monospace,SFMono-Regular,Menlo,monospace" fill="#57606a">cadence deliver</text>
+<polyline points="130,68 228,68" fill="none" stroke="#57606a" stroke-width="1.5" marker-end="url(#arr1)"/>
+<text x="180" y="60" text-anchor="middle" font-size="11.5" fill="#57606a">raf start</text>
+<polyline points="360,68 468,68" fill="none" stroke="#57606a" stroke-width="1.5" marker-end="url(#arr1)"/>
+<text x="415" y="60" text-anchor="middle" font-size="11.5" fill="#57606a">reviews</text>
+<polyline points="640,68 738,68" fill="none" stroke="#57606a" stroke-width="1.5" marker-end="url(#arr1)"/>
+<text x="690" y="60" text-anchor="middle" font-size="11.5" fill="#57606a">gates passed</text>
+<polyline points="850,68 948,68" fill="none" stroke="#57606a" stroke-width="1.5" marker-end="url(#arr1)"/>
+<text x="900" y="60" text-anchor="middle" font-size="11.5" fill="#57606a">push</text>
+<text x="75" y="124" text-anchor="middle" font-size="11.5" fill="#57606a">raf drop → dropped</text>
+<text x="295" y="124" text-anchor="middle" font-size="11.5" fill="#57606a">pre-commit: hook.autostart</text>
+<text x="295" y="140" text-anchor="middle" font-size="11.5" fill="#57606a">warn · refuse · start</text>
+<text x="555" y="124" text-anchor="middle" font-size="11.5" fill="#57606a">review: any lot with commits</text>
+<text x="555" y="140" text-anchor="middle" font-size="11.5" fill="#57606a">ux: visible lot</text>
+<text x="795" y="124" text-anchor="middle" font-size="11.5" fill="#57606a">refused with an open sub-task</text>
+<text x="1015" y="124" text-anchor="middle" font-size="11.5" fill="#57606a">CI of the sha → deploy</text>
+<text x="1015" y="140" text-anchor="middle" font-size="11.5" fill="#57606a">→ effect checks</text>
+<text x="1015" y="164" text-anchor="middle" font-size="11.5" fill="#57606a">visible lot: news entry + capture</text>
+</svg>

package/docs/fonctionnement-service-dark.svg

@@ -0,0 +1,23 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1010 140" width="1010" height="140" role="img" font-family="-apple-system,BlinkMacSystemFont,'Segoe UI',Helvetica,Arial,sans-serif" font-size="13" fill="#e6edf3">
+<title>Putting cadence itself in service</title>
+<desc>The cadence code on the PATH is a separate worktree, updated only by npm run service on a reviewed sha; a wave cannot put unreviewed code in service.</desc>
+<defs><marker id="arr4" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path d="M0,0 L10,5 L0,10 z" fill="#8b949e"/></marker></defs>
+<rect width="1010" height="140" fill="#0d1117"/>
+<rect x="20" y="38" width="220" height="62" rx="6" fill="#0d1117" stroke="#8b949e" stroke-width="1.5"/>
+<text x="130" y="65.5" text-anchor="middle" font-weight="600" font-size="13.5" fill="#e6edf3">Working repository</text>
+<text x="130" y="80.5" text-anchor="middle" font-size="11.5" fill="#8b949e">waves, build = typecheck only</text>
+<rect x="320" y="38" width="260" height="62" rx="6" fill="#0c2d6b" stroke="#58a6ff" stroke-width="2"/>
+<text x="450" y="65.5" text-anchor="middle" font-size="11.5" font-family="ui-monospace,SFMono-Regular,Menlo,monospace" fill="#8b949e">npm run service -- &lt;sha&gt;</text>
+<text x="450" y="80.5" text-anchor="middle" font-size="11.5" fill="#8b949e">ancestor of HEAD · cited lots done</text>
+<rect x="660" y="38" width="220" height="62" rx="6" fill="#0d1117" stroke="#8b949e" stroke-width="1.5"/>
+<text x="770" y="65.5" text-anchor="middle" font-weight="600" font-size="13.5" fill="#e6edf3">Service worktree</text>
+<text x="770" y="80.5" text-anchor="middle" font-size="11.5" font-family="ui-monospace,SFMono-Regular,Menlo,monospace" fill="#8b949e">~/.local/share/cadence</text>
+<text x="945" y="74" text-anchor="middle" font-weight="600" font-size="13.5" fill="#e6edf3">PATH</text>
+<polyline points="240,69 318,69" fill="none" stroke="#8b949e" stroke-width="1.5" marker-end="url(#arr4)"/>
+<text x="279" y="60" text-anchor="middle" font-size="11.5" fill="#8b949e">the lead,</text>
+<text x="279" y="92" text-anchor="middle" font-size="11.5" fill="#8b949e">after review</text>
+<polyline points="580,69 658,69" fill="none" stroke="#8b949e" stroke-width="1.5" marker-end="url(#arr4)"/>
+<text x="619" y="60" text-anchor="middle" font-size="11.5" fill="#8b949e">build</text>
+<polyline points="880,69 918,69" fill="none" stroke="#8b949e" stroke-width="1.5" marker-end="url(#arr4)"/>
+<text x="450" y="126" text-anchor="middle" font-size="11.5" fill="#8b949e">a dropped lot whose every commit is undone by a revert no longer blocks</text>
+</svg>

package/docs/fonctionnement-service-light.svg

@@ -0,0 +1,23 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1010 140" width="1010" height="140" role="img" font-family="-apple-system,BlinkMacSystemFont,'Segoe UI',Helvetica,Arial,sans-serif" font-size="13" fill="#1f2328">
+<title>Putting cadence itself in service</title>
+<desc>The cadence code on the PATH is a separate worktree, updated only by npm run service on a reviewed sha; a wave cannot put unreviewed code in service.</desc>
+<defs><marker id="arr4" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path d="M0,0 L10,5 L0,10 z" fill="#57606a"/></marker></defs>
+<rect width="1010" height="140" fill="#ffffff"/>
+<rect x="20" y="38" width="220" height="62" rx="6" fill="#ffffff" stroke="#57606a" stroke-width="1.5"/>
+<text x="130" y="65.5" text-anchor="middle" font-weight="600" font-size="13.5" fill="#1f2328">Working repository</text>
+<text x="130" y="80.5" text-anchor="middle" font-size="11.5" fill="#57606a">waves, build = typecheck only</text>
+<rect x="320" y="38" width="260" height="62" rx="6" fill="#ddf4ff" stroke="#0969da" stroke-width="2"/>
+<text x="450" y="65.5" text-anchor="middle" font-size="11.5" font-family="ui-monospace,SFMono-Regular,Menlo,monospace" fill="#57606a">npm run service -- &lt;sha&gt;</text>
+<text x="450" y="80.5" text-anchor="middle" font-size="11.5" fill="#57606a">ancestor of HEAD · cited lots done</text>
+<rect x="660" y="38" width="220" height="62" rx="6" fill="#ffffff" stroke="#57606a" stroke-width="1.5"/>
+<text x="770" y="65.5" text-anchor="middle" font-weight="600" font-size="13.5" fill="#1f2328">Service worktree</text>
+<text x="770" y="80.5" text-anchor="middle" font-size="11.5" font-family="ui-monospace,SFMono-Regular,Menlo,monospace" fill="#57606a">~/.local/share/cadence</text>
+<text x="945" y="74" text-anchor="middle" font-weight="600" font-size="13.5" fill="#1f2328">PATH</text>
+<polyline points="240,69 318,69" fill="none" stroke="#57606a" stroke-width="1.5" marker-end="url(#arr4)"/>
+<text x="279" y="60" text-anchor="middle" font-size="11.5" fill="#57606a">the lead,</text>
+<text x="279" y="92" text-anchor="middle" font-size="11.5" fill="#57606a">after review</text>
+<polyline points="580,69 658,69" fill="none" stroke="#57606a" stroke-width="1.5" marker-end="url(#arr4)"/>
+<text x="619" y="60" text-anchor="middle" font-size="11.5" fill="#57606a">build</text>
+<polyline points="880,69 918,69" fill="none" stroke="#57606a" stroke-width="1.5" marker-end="url(#arr4)"/>
+<text x="450" y="126" text-anchor="middle" font-size="11.5" fill="#57606a">a dropped lot whose every commit is undone by a revert no longer blocks</text>
+</svg>