@sylad/cadence 1.15.0 → 1.16.1

package/.claude-plugin/marketplace.json

@@ -8,7 +8,7 @@
     {
       "name": "cadence",
       "description": "Session start and close rituals driven by a versioned plan (raf), and deliveries proven by their effect. Needs the cadence CLI (npm i -g @sylad/cadence).",
-      "version": "1.15.0",
+      "version": "1.16.1",
       "source": "./",
       "author": {
         "name": "Sylvain Ladoire"

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "cadence",
   "description": "A repo-native working method: session start and close rituals driven by a versioned plan (raf), deliveries proven by their effect, and three reviewer agents (UX, code, QA).",
-  "version": "1.15.0",
+  "version": "1.16.1",
   "author": { "name": "Sylvain Ladoire" },
   "homepage": "https://github.com/Sylad/cadence",
   "repository": "https://github.com/Sylad/cadence",

package/README.md

@@ -7,7 +7,7 @@ cadence keeps both in plain files next to the code, and [Claude Code](https://cl
 
 ## Start
 
-Needs Node 22.18 or later (see [docs/stabilite.md](docs/stabilite.md)).
+Needs Node 22.18 or later (see [docs/stabilite.md](docs/stabilite.md)); waves also need Claude Code installed and logged in.
 
 ```sh
 npm install -g @sylad/cadence
@@ -16,12 +16,25 @@ raf add "My first lot" --estimate 1
 ```
 
 Then `raf start L1`, commit with `feat(L1): …`, `raf now` to see where you are, `raf done L1` when it is finished.
+`raf -v` prints the installed version. Every command is in [docs/raf.md](docs/raf.md).
+
+## Lead several projects in 10 minutes
+
+A parent folder, a plan in each project, a `/cadence:lead` session that picks the lots, a wave that does the work.
+[docs/quickstart.md](docs/quickstart.md) goes from install to the first wave, and lists the usual stops.
+Something broken or missing? [Open an issue](https://github.com/Sylad/cadence/issues/new/choose).
 
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="docs/cycle-vague-dark.svg">
   <img alt="A lot goes through spec, mockup, accept, implement, review, ux and deliver; the lead picks the lots, answers the questions, re-verifies and delivers" src="docs/cycle-vague-light.svg">
 </picture>
 
+## With the tools you already have
+
+Linear, a `HANDOFF.md`, ADRs, Conventional Commits? Keep them: cadence replaces none, and each part is optional.
+It can read a plan your tracker keeps (read-only) and write its plan commits in your format.
+[docs/with-your-tools.md](docs/with-your-tools.md): what stays, what is optional, what plugs in.
+
 ## Install as a Claude Code plugin
 
 ```

package/bin/cadence.js

@@ -1,5 +1,4 @@
 #!/usr/bin/env node
-import { readFileSync } from 'node:fs';
 import { run } from '../dist/cli.js';
 
 const [tool, ...args] = process.argv.slice(2);
@@ -16,8 +15,7 @@ if (tool === 'raf') {
 } else if (['news', 'session', 'deliver', 'verify', 'skills', 'orchestrate', 'lead', 'corrections', 'perf', 'spec', 'ref', 'config', 'release'].includes(tool)) {
   process.exitCode = await run([tool, ...args], io);
 } else if (tool === '--version' || tool === '-v') {
-  const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
-  console.log(pkg.version);
+  process.exitCode = await run([tool], io);
 } else {
   console.log(`cadence — une méthode de travail qui vit dans le dépôt
 

package/dist/audit.js

@@ -2,7 +2,7 @@ import { existsSync } from 'node:fs';
 import { dirname, join, relative } from 'node:path';
 import { check } from './check.js';
 import { parse } from 'yaml';
-import { changedFiles, fileAt, readCommits } from './git.js';
+import { changedFiles, fileAt, preloadChangedFiles, readCommits } from './git.js';
 import { citedRefs, linkCommits, scopeOf } from './link.js';
 import { PLAN_DEFAULT, PLAN_LEGACY, readDocsConfig, readNewsConfig, readOrchestrateConfig } from './config.js';
 import { ficheHypotheses } from './spec.js';
@@ -25,6 +25,7 @@ export function ownFiles(plan, root) {
     if (relative(root, plan.path) === PLAN_DEFAULT) {
         own.add(PLAN_LEGACY);
         own.add(join(dirname(PLAN_LEGACY), 'gantt.html'));
+        own.add(join(dirname(PLAN_DEFAULT), 'notes/.gitkeep')); // ce que `raf init` pose avec le plan (L377)
     }
     return own;
 }
@@ -45,6 +46,29 @@ function onlyPlanKeyChanged(root, sha, file) {
     const after = withoutPlanKey(fileAt(root, sha, file));
     return before !== null && before === after;
 }
+/** Les lignes que `raf init` ajoute à .gitignore (L377) ; le fichier est un fichier du plan quand un commit n'y ajoute que celles-là. */
+const INIT_GITIGNORE = ['.playwright-mcp/'];
+function gitignoreLines(text) {
+    return (text ?? '').split('\n').map((l) => l.trim()).filter(Boolean);
+}
+/** Le commit ne change de .gitignore que les lignes de `raf init` ? Rien n'est retiré, aucune autre ligne n'est ajoutée. */
+function onlyInitGitignore(root, sha, file) {
+    const before = gitignoreLines(fileAt(root, `${sha}^`, file));
+    const added = gitignoreLines(fileAt(root, sha, file));
+    const kept = added.filter((l) => !INIT_GITIGNORE.includes(l) || before.includes(l));
+    return before.every((l) => added.includes(l)) && kept.length === before.length;
+}
+/** Les clés d'un cadence.yaml qui naît dans le commit d'init : le plan et la porte de tests de la vague ; deliver:, session:… sont du travail. */
+const INIT_CONFIG_KEYS = ['plan', 'orchestrate'];
+function onlyInitKeys(text) {
+    try {
+        const doc = parse(text ?? '');
+        return doc !== null && typeof doc === 'object' && !Array.isArray(doc) && Object.keys(doc).every((k) => INIT_CONFIG_KEYS.includes(k));
+    }
+    catch {
+        return false;
+    }
+}
 /** Commits du dépôt sans les commits automatiques (motifs `ignore`) : ni audités ni comptés pour un lot. */
 export function planCommits(plan, root, opts = {}) {
     const { patterns } = plan.ignore;
@@ -54,14 +78,17 @@ export function planCommits(plan, root, opts = {}) {
 /**
  * Commit d'entretien du plan : TOUS ses fichiers sont des fichiers du plan (le plan, sa page Gantt,
  * plan.files — son plan publié par exemple —, les attendus QA et la configuration lue, mais celle-ci seulement quand la
- * clé `plan:` est la seule à changer : deliver/session/… sont du travail). Les fichiers décident,
+ * clé `plan:` est la seule à changer, ou qu'elle naît dans le commit avec les seules clés `plan:` et `orchestrate:` : deliver/session/… modifiés sont du travail ; et, de ce que `raf init` écrit, .cadence/notes/.gitkeep
+ * et les lignes qu'il ajoute à .gitignore, pour que le commit qui suit `raf init` n'ouvre pas d'écart, L377). Les fichiers décident,
  * jamais le sujet : « chore(plan): … » qui touche un fichier source est un commit comme un autre.
  */
 export function isPlanOnly(sha, plan, root) {
     const own = ownFiles(plan, root);
     const config = configRel(plan, root);
     const files = changedFiles(root, sha);
-    return files.length > 0 && files.every((f) => own.has(f) && (f !== config || onlyPlanKeyChanged(root, sha, f)));
+    const created = (f) => fileAt(root, `${sha}^`, f) === null && onlyInitKeys(fileAt(root, sha, f)); // cadence.yaml naît avec le plan : `raf init` puis la porte de tests, un seul commit (L377)
+    const initScaffold = (f) => f === '.gitignore' && onlyInitGitignore(root, sha, f);
+    return files.length > 0 && files.every((f) => initScaffold(f) || (own.has(f) && (f !== config || created(f) || onlyPlanKeyChanged(root, sha, f))));
 }
 /** Fichiers d'une version : manifestes JSON (dont seul le champ `version` bouge) et CHANGELOG. */
 const VERSION_JSON = /(^|\/)(package\.json|package-lock\.json|\.claude-plugin\/(plugin|marketplace)\.json)$/;
@@ -213,6 +240,16 @@ function workCommits(plan, root, commits) {
 export function lotCommits(plan, root, lotId) {
     return linkCommits(plan.lots(), planCommits(plan, root), plan.refs).byLot.get(lotId) ?? [];
 }
+/**
+ * Commits de travail des lots d'un rapprochement déjà fait (cf. lotWork) : le compte que montrent `raf now`, le tour et `session start`.
+ * `ids` : les seuls lots dont l'écran affiche un compte — chaque commit filtré coûte des `git diff-tree`, inutiles pour les autres.
+ */
+export function workByLot(plan, root, linked, ids) {
+    const wanted = ids ? new Set(ids) : null;
+    const shown = [...linked.byLot].filter(([id]) => !wanted || wanted.has(id));
+    preloadChangedFiles(root, shown.flatMap(([, commits]) => commits.map((c) => c.sha)));
+    return new Map(shown.map(([id, commits]) => [id, workCommits(plan, root, commits)]));
+}
 /** Commits à relire d'un lot, du plus récent au plus ancien — ce que compte la porte de revue de code et que liste `raf commits`. */
 export function lotWork(plan, root, lotId) {
     return workCommits(plan, root, lotCommits(plan, root, lotId));

package/dist/cli.js

@@ -4,7 +4,7 @@ import { basename, dirname, join, posix, relative, resolve } from 'node:path';
 import { parseArgs } from 'node:util';
 import { defaultPlan, PLAN_DEFAULT, PLAN_LEGACY, readDocsConfig, readHookConfig, readNewsConfig, readOrchestrateConfig, readPerfConfig, readPlanConfig, readSessionConfig } from './config.js';
 import { repoSections, repoShas, resolveLotRepos } from './repos.js';
-import { audit, exemptPlanOnly, gateProgress, gateText, gateWaiting, hypothesesOf, ownFiles, isPlanOnly, lotWork, nextUp, planCommits, unreviewedWork } from './audit.js';
+import { audit, exemptPlanOnly, gateProgress, gateText, gateWaiting, hypothesesOf, ownFiles, isPlanOnly, lotWork, nextUp, planCommits, unreviewedWork, workByLot } from './audit.js';
 import { short } from './check.js';
 import { isDay, toDay } from './dates.js';
 import { deliver, parseDeliverConfig, realDeps, shellQuote } from './deliver.js';
@@ -117,9 +117,18 @@ function legacyPlanLine(root, legacy) {
         return `raf: ${PLAN_LEGACY} est ignoré : ${PLAN_DEFAULT} existe aussi et fait foi (supprimer ou fusionner l'ancien)`;
     return `raf: ${PLAN_LEGACY} est l'ancien emplacement du plan ; le déplacer : cd ${shellQuote(root)} && mkdir -p ${dirname(PLAN_DEFAULT)} && ${gitRoot(root) && isTracked(root, PLAN_LEGACY) ? 'git mv' : 'mv'} ${PLAN_LEGACY} ${PLAN_DEFAULT}`;
 }
+/** La version du paquet (`package.json` est à côté de `src/` comme de `dist/`). */
+function packageVersion() {
+    return JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
+}
 export function run(argv, io) {
     setPlanNotice(io.err);
     try {
+        // Comme `cadence --version` (L376) : en premier argument seulement, ailleurs c'est une option comme une autre.
+        if (argv[0] === '--version' || argv[0] === '-v') {
+            io.out(packageVersion());
+            return 0;
+        }
         // orchestrate a ses propres options (--status et --resume prennent une valeur facultative, --answer en prend deux).
         if (argv[0] === 'orchestrate') {
             return orchestrate(argv.slice(1), io, realOrchestrateDeps(io.env)).catch((e) => failure(e, io));
@@ -663,7 +672,7 @@ function dispatch(argv, io) {
             const lots = plan.lots();
             const linked = linkCommits(lots, planCommits(plan, root), plan.refs);
             const stamp = io.now();
-            const html = renderGantt(ganttData(plan.project, schedule(lots, linked.byLot, today), today, `${toDay(stamp)} ${stamp.toTimeString().slice(0, 5)}`));
+            const html = renderGantt(ganttData(plan.project, schedule(lots, workByLot(plan, root, linked), today), today, `${toDay(stamp)} ${stamp.toTimeString().slice(0, 5)}`));
             const out = resolve(io.cwd, values.output ?? join(dirname(planPath), 'gantt.html'));
             mkdirSync(dirname(out), { recursive: true });
             writeFileSync(out, html);
@@ -841,8 +850,9 @@ function describe(l, commits) {
 function now(plan, root, newsDir, today, io) {
     const lots = plan.lots();
     const linked = linkCommits(lots, planCommits(plan, root), plan.refs);
-    const count = (id) => linked.byLot.get(id)?.length ?? 0;
     const { doing, ready, blocked } = nextUp(lots);
+    const work = workByLot(plan, root, linked, [...doing, ...ready.slice(0, 5)].map((l) => l.id));
+    const count = (id) => work.get(id)?.length ?? 0;
     io.out(`${plan.project} — ${today}`);
     io.out('\nEn cours');
     if (doing.length === 0)

package/dist/git.js

@@ -99,9 +99,37 @@ export function syncIndexWithHead(cwd, file) {
  * le commit supprime (`--diff-filter=d`) : un fichier supprimé n'est plus du code à tester.
  */
 export function changedFiles(cwd, sha, opts = {}) {
+    const known = opts.withoutDeleted ? undefined : filesCache.get(`${cwd}\0${sha}`);
+    if (known)
+        return known;
     // -z : noms séparés par NUL, jamais échappés ; quotepath=off en plus pour les sorties qui citeraient quand même.
     return git(cwd, ['-c', 'core.quotepath=off', 'diff-tree', '--root', '--no-commit-id', '--name-only', '-r', '-z', ...(opts.withoutDeleted ? ['--diff-filter=d'] : []), sha]).split('\0').filter(Boolean);
 }
+/** Fichiers modifiés par commit (hors suppressions écartées), par dépôt : un sha ne change jamais de contenu. */
+const filesCache = new Map();
+/**
+ * Lit d'un seul appel git les fichiers modifiés de ces commits, pour que `changedFiles` ne lance pas un `git diff-tree` par commit
+ * (L381 : filtrer les milliers de commits liés du gantt coûtait ~20 s). Même résultat que `changedFiles` ; un commit de fusion n'a
+ * aucun fichier, comme avec `diff-tree`. Sans effet sur un dépôt illisible : `changedFiles` retombe sur `git diff-tree`.
+ */
+export function preloadChangedFiles(cwd, shas) {
+    const missing = shas.filter((sha) => !filesCache.has(`${cwd}\0${sha}`));
+    if (missing.length < 2)
+        return;
+    let out;
+    try {
+        out = execFileSync('git', ['-c', 'core.quotepath=off', 'log', '--no-walk=unsorted', '--stdin', '--root', '--format=%x01%H', '--name-only', '-z'], {
+            cwd, encoding: 'utf8', input: missing.join('\n') + '\n', stdio: ['pipe', 'pipe', 'pipe'], maxBuffer: 1024 * 1024 * 1024,
+        });
+    }
+    catch {
+        return;
+    }
+    for (const block of out.split('\x01').slice(1)) {
+        const [sha, ...files] = block.split('\0');
+        filesCache.set(`${cwd}\0${sha}`, files.map((f) => f.replace(/^\n/, '')).filter(Boolean));
+    }
+}
 /** Contenu d'un fichier à un commit (`<sha>^` pour l'état d'avant) ; null s'il n'existe pas à ce commit. */
 export function fileAt(cwd, rev, file) {
     try {

package/dist/lead.js

@@ -1,6 +1,6 @@
 import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
 import { basename, join, relative, sep } from 'node:path';
-import { audit, gateWaiting, nextUp, planCommits } from './audit.js';
+import { audit, gateWaiting, nextUp, planCommits, workByLot } from './audit.js';
 import { PLAN_DEFAULT, PLAN_LEGACY, planLoader, readPlanConfig } from './config.js';
 import { diffDays } from './dates.js';
 import { gitRoot, repoStatus } from './git.js';
@@ -114,13 +114,14 @@ export function tourRow(dir, today, idle = TOUR_IDLE, name = basename(dir)) {
         const lots = plan.lots();
         const all = linkCommits(lots, planCommits(plan, root), plan.refs);
         const { doing, ready, blocked } = nextUp(lots);
+        const work = workByLot(plan, root, all, doing.map((l) => l.id));
         row.doing = doing.map((l) => {
-            const commits = all.byLot.get(l.id) ?? [];
-            const last = lastActivity(l, commits);
+            const count = work.get(l.id)?.length ?? 0;
+            const last = lastActivity(l, all.byLot.get(l.id) ?? []);
             if (!last)
-                return { id: l.id, commits: commits.length, noActivity: true };
+                return { id: l.id, commits: count, noActivity: true };
             const days = diffDays(last, today);
-            return days > idle ? { id: l.id, commits: commits.length, silentDays: days } : { id: l.id, commits: commits.length };
+            return days > idle ? { id: l.id, commits: count, silentDays: days } : { id: l.id, commits: count };
         });
         row.drift = audit(plan, root, join(root, 'docs/nouveautes'), today).map((i) => `${i.warning ? '⚠' : '✗'} ${i.message}`);
         row.notes = readNext(stateDir(root))?.lines ?? [];

package/dist/orchestrate/changelog-merge.js

@@ -12,8 +12,13 @@ function split(text) {
         end = lines.length;
     return { head: lines.slice(0, at + 1).join('\n'), block: lines.slice(at + 1, end), tail: lines.slice(end).join('\n') };
 }
-/** Sections du bloc `[Unreleased]` : une entrée est une ligne `- ` et ses lignes de suite. Deux titres identiques sont fondus. Du texte hors entrée : null. */
-function sections(block) {
+/** Clé des entrées nues (avant tout `### `) quand `sections` les accepte ; aucun titre réel n'est vide. */
+const BARE = '';
+/**
+ * Sections du bloc `[Unreleased]` : une entrée est une ligne `- ` et ses lignes de suite. Deux titres identiques sont fondus. Du texte hors entrée : null.
+ * Une entrée avant tout titre est refusée (null), sauf avec `allowBare` : elle est alors rangée sous la clé `BARE`.
+ */
+function sections(block, allowBare = false) {
     const out = new Map();
     let current = null;
     for (const line of block) {
@@ -24,6 +29,11 @@ function sections(block) {
             current = out.get(title) ?? [];
             out.set(title, current);
         }
+        else if (!current && allowBare && line.startsWith('- ')) {
+            current = out.get(BARE) ?? [];
+            out.set(BARE, current);
+            current.push(line);
+        }
         else if (!current) {
             return null;
         }
@@ -39,6 +49,27 @@ function sections(block) {
     }
     return out;
 }
+/**
+ * Range les entrées nues des trois côtés sous une rubrique (L383) : celle que les côtés ont ajoutée à la base si elle est seule, sinon la seule rubrique qu'ils
+ * portent. Aucune rubrique, ou plusieurs candidates : le choix serait le nôtre, on rend false et le conflit reste à la main.
+ */
+function fileBare(base, ours, theirs) {
+    if (![base, ours, theirs].some((s) => s.has(BARE)))
+        return true;
+    const titles = [...new Set([...ours.keys(), ...theirs.keys()])].filter((t) => t !== BARE);
+    const added = titles.filter((t) => !base.has(t));
+    const target = added.length === 1 ? added[0] : titles.length === 1 ? titles[0] : null;
+    if (target === null)
+        return false;
+    for (const side of [base, ours, theirs]) {
+        const bare = side.get(BARE);
+        if (!bare)
+            continue;
+        side.delete(BARE);
+        side.set(target, [...(side.get(target) ?? []), ...bare]);
+    }
+    return true;
+}
 /** `base` est une sous-suite de `side` : rien n'a été retiré ni modifié, seul de l'ajout s'y est glissé. */
 function onlyAdds(base, side) {
     let i = 0;
@@ -63,7 +94,8 @@ function pick(base, ours, theirs) {
  * Fusion à trois du CHANGELOG quand deux lots y ont chacun ajouté une entrée sous `[Unreleased]` (L314) : union par section, un seul titre par section,
  * sections dans l'ordre de Keep a Changelog, les entrées de `ours` puis celles de `theirs` qui n'y sont pas déjà. Le reste du fichier suit le côté qui l'a
  * changé. Rend null quand ce n'est pas de l'ajout pur — une entrée de base retirée ou modifiée, du texte libre sous `[Unreleased]`, le reste du fichier
- * changé des deux côtés, pas de section `[Unreleased]` — : le conflit reste alors à la main.
+ * changé des deux côtés, pas de section `[Unreleased]` — : le conflit reste alors à la main. Une entrée nue (sans rubrique) d'un côté est rangée sous la
+ * rubrique que l'autre a ajoutée (L383) ; sans rubrique unique où la ranger, le conflit reste à la main.
  *
  * `start` est le CHANGELOG du point de départ de la branche rejouée (L323). Une entrée de `base` qui n'y était pas a été ajoutée par un commit précédent du
  * lot lui-même : `theirs` peut la modifier ou la retirer, sa version gagne (l'ancienne est écartée de `ours`). Sans `start`, aucune entrée n'est au lot.
@@ -74,11 +106,11 @@ export function mergeUnreleased(base, ours, theirs, start) {
         return null;
     const head = pick(b.head, o.head, t.head);
     const tail = pick(b.tail, o.tail, t.tail);
-    const [bs, os, ts] = [sections(b.block), sections(o.block), sections(t.block)];
-    if (head === null || tail === null || !bs || !os || !ts)
+    const [bs, os, ts] = [sections(b.block, true), sections(o.block, true), sections(t.block, true)];
+    if (head === null || tail === null || !bs || !os || !ts || !fileBare(bs, os, ts))
         return null;
     const st = start === undefined ? null : split(start);
-    const startEntries = new Set([...(st ? (sections(st.block)?.values() ?? []) : [])].flat());
+    const startEntries = new Set([...(st ? (sections(st.block, true)?.values() ?? []) : [])].flat());
     const own = new Set(start === undefined || !st ? [] : [...bs.values()].flat().filter((e) => !startEntries.has(e)));
     // Une entrée de base que ours range sous une version publiée (la branche a été publiée pendant la vie du lot) n'a pas été retirée : elle a changé de place.
     // Seule une entrée de base compte, entière : une entrée nouvelle de theirs qui est un bout d'une entrée publiée n'est pas la même, elle reste au lot.

package/dist/orchestrate/command.js

@@ -239,7 +239,7 @@ function resolveTargets(args, io, refusals) {
         }
         seen.add(key);
         if (!existsSync(projectDir) || !statSync(projectDir).isDirectory()) {
-            refusals.push(`${key} : ${l.project ? `dossier ${projectDir} introuvable` : 'dossier courant illisible'}`);
+            refusals.push(`${key} : ${l.project ? `dossier ${projectDir} introuvable (le projet est un sous-dossier du dossier courant ; dans un dépôt, \`.:${l.lot}\`)` : 'dossier courant illisible'}`);
             continue;
         }
         if (!isProject(projectDir)) {
@@ -266,6 +266,10 @@ function olderThanEffort(version) {
     const [a, b, c] = [Number(m[1]), Number(m[2]), Number(m[3])];
     return a < 2 || (a === 2 && (b < 1 || (b === 1 && c < 284)));
 }
+/** L378 : claude installé mais non connecté échoue à la première session, après le démarrage du lot dans le plan. Null si connecté ou état illisible. */
+function notLoggedIn(deps) {
+    return deps.claudeAuth?.()?.loggedIn === false ? "claude n'est pas connecté : lancer `claude` puis /login (état : `claude auth status`)" : null;
+}
 /** Préconditions : tout ce qui peut être refusé l'est ici, avant d'agir, sans verrou ni écriture. */
 async function preflight(args, targets, io, deps, launch, opts = {}) {
     const refusals = [];
@@ -276,6 +280,9 @@ async function preflight(args, targets, io, deps, launch, opts = {}) {
         refusals.push('claude introuvable (CADENCE_CLAUDE_BIN, ou claude dans le PATH)');
     else if (!info.jsonSchema)
         refusals.push(`claude ${info.version} n'a pas --json-schema : mettre claude à jour`);
+    const login = info && !args.dryRun ? notLoggedIn(deps) : null; // la simulation n'ouvre pas de session : elle le signale (dryRun) sans refuser
+    if (login)
+        refusals.push(login);
     const lots = [];
     const repoChecked = new Set();
     const byProject = new Map();
@@ -459,6 +466,9 @@ function dryRun(lots, io, deps, budget, id) {
     const tmp = mkdtempSync(join(tmpdir(), 'cadence-orchestrate-'));
     const agents = agentsOf(deps);
     io.out(`vague ${id} — simulation, rien n'est lancé (budget ${budget} tokens comptés)`);
+    const login = notLoggedIn(deps);
+    if (login)
+        io.out(`⚠ ${login} — sans cela le vrai lancement est refusé`);
     const repos = [...new Set(lots.map((l) => l.repo))];
     const noTestSaid = new Set();
     const redSaid = new Set();
@@ -674,8 +684,17 @@ function removeWorktree(args, io) {
     io.out(`orchestrate : ${key} : worktree retiré (${gone.abandoned} commit(s) abandonné(s))`);
     return 0;
 }
+/** L382 : `claude auth status` peut durer jusqu'à 20 s ; en --continue, preflight() le relancerait pour chaque lot candidat de chaque tour. Une seule lecture par lancement (une vague). */
+function onceAuth(deps) {
+    const read = deps.claudeAuth;
+    if (!read)
+        return deps;
+    let cached;
+    return { ...deps, claudeAuth: () => (cached ??= { value: read() }).value };
+}
 /** Point d'entrée de `cadence orchestrate`. 0 prêts · 1 rendus au lead · 2 refus avant d'agir · 3 suspendue (budget, quota). */
 export async function orchestrate(argv, io, deps) {
+    deps = onceAuth(deps);
     const args = parseOrchestrateArgs(argv);
     const launch = io.cwd;
     const today = io.env.RAF_TODAY && isDay(io.env.RAF_TODAY) ? io.env.RAF_TODAY : toDay(io.now());
@@ -1612,6 +1631,16 @@ async function resume(args, argv, io, deps, launch, today) {
     }
     return continueRounds(await execute(wave, live, store, io, deps, today, maxSessions(args, io), lots), wave, lots, store, io, deps, today, args, launch);
 }
+/** `loggedIn` de la sortie JSON de `claude auth status` ; null si elle n'est pas lisible (versions sans cette commande : pas de refus). */
+export function parseAuthStatus(text) {
+    try {
+        const v = JSON.parse(text);
+        return typeof v.loggedIn === 'boolean' ? { loggedIn: v.loggedIn } : null;
+    }
+    catch {
+        return null;
+    }
+}
 /** Dépendances réelles : `claude` (ou CADENCE_CLAUDE_BIN), agents et gabarits du paquet, journaux de ~/.claude. */
 export function realOrchestrateDeps(env) {
     const bin = env.CADENCE_CLAUDE_BIN || 'claude';
@@ -1630,6 +1659,16 @@ export function realOrchestrateDeps(env) {
                 return null;
             }
         },
+        claudeAuth: () => {
+            try {
+                // `auth status` sort en 1 quand claude n'est pas connecté, et imprime quand même le JSON.
+                const text = execFileSync(bin, ['auth', 'status'], { env, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 20_000 });
+                return parseAuthStatus(text);
+            }
+            catch (e) {
+                return parseAuthStatus(String(e.stdout ?? ''));
+            }
+        },
         agentsDir: AGENTS_DIR,
         snapshot: child ? undefined : { packageRoot: PACKAGE_ROOT, reexec: spawnReexec },
         claudeHome: env.CLAUDE_CONFIG_DIR || join(homedir(), '.claude'),

package/dist/release.js

@@ -199,6 +199,7 @@ function steps(p, files, branch) {
     const tag = `v${p.version}`;
     const out = [
         `git add ${files.join(' ')} && git commit -m "release: ${p.version}"`,
+        'cadence verify --gate --sha HEAD    (la suite et le build rejoués sur le commit de version, où le CHANGELOG n\'a plus de [Unreleased] plein ; rouge = pas d\'éval ni de tag)',
         ...(p.hasEvalScript ? ['npm run eval:plugin -- --trust-plugin    (facturé ; un cas sous le seuil arrête la release)'] : []),
         `git tag ${tag}`,
         `git push origin ${branch} ${tag}    (le tag lance le workflow de publication)`,

package/dist/session.js

@@ -1,7 +1,7 @@
 import { spawnSync } from 'node:child_process';
 import { CLEAN_DAYS, scanStale } from './clean.js';
 import { dueLine, isRecurring, recurringByDue } from './recurring.js';
-import { audit, exemptPlanOnly, gateWaiting, nextUp, planCommits } from './audit.js';
+import { audit, exemptPlanOnly, gateWaiting, nextUp, planCommits, workByLot } from './audit.js';
 import { diffDays, maxDay } from './dates.js';
 import { repoStatus } from './git.js';
 import { linkCommits } from './link.js';
@@ -32,10 +32,12 @@ function projectFacts(ctx, since) {
     return lines;
 }
 const short = (c) => `${c.sha.slice(0, 7)} ${c.subject}`;
-/** Commits de la fenêtre reliés aux lots, sans compter comme « sans lot » ceux qui ne touchent que le plan. */
+/** Commits de la fenêtre reliés aux lots : ceux qui ne touchent que le plan ne comptent ni « sans lot » ni comme travail d'un lot (comme `raf commits`). */
 function period(ctx, since) {
     const commits = planCommits(ctx.plan, ctx.root, { since });
-    const linked = exemptPlanOnly(linkCommits(ctx.plan.lots(), commits, ctx.plan.refs), ctx.plan, ctx.root);
+    const exempt = exemptPlanOnly(linkCommits(ctx.plan.lots(), commits, ctx.plan.refs), ctx.plan, ctx.root);
+    const byLot = new Map([...workByLot(ctx.plan, ctx.root, exempt)].filter(([, cs]) => cs.length > 0));
+    const linked = { ...exempt, byLot };
     // Comme raf check : un commit antérieur à l'adoption du plan n'avait pas à citer de lot.
     const adopted = ctx.plan.since;
     return adopted ? { ...linked, orphans: linked.orphans.filter((c) => c.day >= adopted) } : linked;
@@ -113,6 +115,7 @@ export function sessionStart(ctx, opts) {
     if (lock)
         out(`\n${lock.line}`);
     const { doing, ready, blocked } = nextUp(lots);
+    const work = workByLot(plan, ctx.root, all, doing.map((l) => l.id));
     out('\nEn cours');
     if (doing.length === 0)
         out('  (rien)');
@@ -121,7 +124,7 @@ export function sessionStart(ctx, opts) {
         const last = lastActivity(l, commits);
         const idle = last ? diffDays(last, today) : 0;
         const state = last ? `dernière activité ${last}${idle > opts.idle ? `, silencieux depuis ${idle} j` : ''}` : 'aucune activité';
-        out(`  ${l.id}  ${l.title}  (${commitCount(commits.length)}, ${state})`);
+        out(`  ${l.id}  ${l.title}  (${commitCount(work.get(l.id)?.length ?? 0)}, ${state})`);
     }
     section(out, 'En attente', gateWaiting(lots, blocked).map(({ lot, text }) => `${lot.id}  ${lot.title}  (${text})`));
     const recent = period(ctx, opts.since);

package/docs/lead.md

@@ -156,6 +156,8 @@ alpha · en cours L1 (1 commit, silencieux 4j) · dérive 1 (✗ L2 a 1 commit(s
 beta · en cours rien · dérive aucune · notes : aucune · prochain T2 Second · dépôt propre
 ```
 
+The commit count of a lot in progress is the one of `raf commits`: plan commits (`plan: L1 démarré` and the like, which touch only plan files) are left out, so a lot just started reads `L1 (0 commit)` (L379).
+
 | Column | Content |
 |---|---|
 | `en cours` | ids of the lots in progress, each with its number of commits (`0 commit` included: a close note on a lot without commit is not « done, `raf done` forgotten »); then `aucune activité` when it has no activity at all, `silencieux Nj` when the lot's last activity (commit, note or start) is more than `--idle` days old (default 3) |

package/docs/orchestrate.md

@@ -11,6 +11,7 @@ exception is a **formatting retry** (below).
 ```sh
 cadence orchestrate finance-tracker:L41 ol-companion:L22 cadence:L18@haiku
 cadence orchestrate L18                      # from inside a project
+cadence orchestrate .:L18                    # the same, with the project named « . » (inside a repository)
 cadence orchestrate maritime-atlas:Q4/accueil-4-ux12@haiku   # a lot id may contain "/" (sub-tasks of read-only plans)
 cadence orchestrate maritime:B28.4 --goal "…"   # the goal replaces the stale title as the objective of the briefs (below)
 cadence orchestrate … --budget 1.5M          # 1500000, 1.5M, 800k; default 2M
@@ -35,6 +36,10 @@ cadence orchestrate --drop ccc:L29 [--wave <wave>]   # from another terminal: ta
 cadence orchestrate --stop-after-current [--wave <wave>]   # from another terminal: let the running sessions finish, start nothing else
 ```
 
+**Claude Code must be installed and logged in** (L378). Before starting a lot, `cadence orchestrate` runs `claude auth status` (no model, no cost); when it says `loggedIn: false` the command is refused (exit 2) before anything is written: no `raf start`, no plan commit, the lot stays `todo`. The message says what to do: « claude n'est pas connecté : lancer `claude` puis /login (état : `claude auth status`) ». `--dry-run` starts no session, so it is not refused: it prints the same message after its first line, as a `⚠`. `claude auth status` is read once per launch, so with `--continue` the rounds of a wave do not run it again for every candidate lot. An unreadable answer (a `claude` without `auth status`) is not a refusal.
+
+A `<project>` is a sub-folder of the current folder. Launched from inside `alpha`, `alpha:L1` looks for `alpha/alpha` and is refused: `alpha:L1 : dossier …/alpha/alpha introuvable (le projet est un sous-dossier du dossier courant ; dans un dépôt, `.:L1`)` (L376). Inside a repository, `.:L1` or `L1` names the lot of the repository itself.
+
 **`--drop` and `--stop-after-current` — steering a running wave (L79)**: both are run from the folder the wave was launched
 from (`--wave <id>` when several waves run from it), and write a request in the wave's state folder
 (`.cadence/runs/<wave>/control.log`, append-only), which the wave reads before each session — no signal, no edit of
@@ -586,7 +591,7 @@ nothing below applies and the wave behaves as before; any other value is refused
      stacked). After the rebase the program lists the entries the lot's commits wrote under `[Unreleased]` that are neither at the starting point nor at
      the lot's tip (nor under a version the tip itself carries: an entry the lot published itself is final), drops them from the result (under `[Unreleased]` and under a version), and puts back an entry of the tip that is missing, in a commit of
      its own (`docs: CHANGELOG — une entrée finale par lot …`); an entry the repository's branch also carries is left alone. The union of an earlier replayed commit files the lot's entry at the end of its section; where the lot first put it (top of the section included) does not matter for the next replayed commit. The journal says
-     `<project>:<lot> CHANGELOG.md : une entrée finale par lot, les versions intermédiaires du lot écartées`. Anything else — an entry that
+     `<project>:<lot> CHANGELOG.md : une entrée finale par lot, les versions intermédiaires du lot écartées`. **A bare entry** (L383): an entry written under `## [Unreleased]` without a section on one side, against a section (`### Fixed`) the other side added, is not a free text: it is filed under that section (the entries of the repository's branch first), so the result has one title and one entry per lot. The section is the only one the two sides added to the base, or the only one they carry; with none, or several candidates, the conflict is left by hand. Anything else — an entry that
      was already there removed or reworded, free text under `[Unreleased]`, the rest of the
      file changed on both sides, another file in conflict with it — aborts the rebase and hands the lot back as above. The rebased commits differ, so
      steps 3 and 4 apply: tests replayed, and a short review since the patch-id changed;

package/docs/overview.md

@@ -61,6 +61,8 @@ The two plugins are independent. `cadence@cadence` carries the rituals, which ca
 
 | Page | What it covers |
 |---|---|
+| [docs/quickstart.md](quickstart.md) | getting started as a lead of several projects, in 10 minutes: install, the parent folder, `raf init`, the tour, the first wave |
+| [docs/with-your-tools.md](with-your-tools.md) | cadence next to a tracker, `HANDOFF.md`, ADRs and a commit convention: what it does not replace, what is optional, what plugs in (`plan:` read-only, `plan.commit`, `docs.sync`), what it adds |
 | [docs/raf.md](raf.md) | the plan: commands, plan file, foreign plan formats, Gantt |
 | [docs/orchestrate.md](orchestrate.md) | waves of sessions: budgets, spec, accept and review steps, neighbouring repositories, one worktree per lot (`orchestrate.worktrees: true`, on in cadence's own `cadence.yaml`, off by default elsewhere; `--integrate`, `--replay`, `--remove-worktree`; recovery of a handed-back lot's branch and the `CHANGELOG.md` union at the integration are described there) |
 | [docs/deliver.md](deliver.md) | delivery: wait for CI, deploy, verify the effect |

package/docs/quickstart-dark.svg

@@ -0,0 +1,33 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1010 190" width="1010" height="190" role="img" font-family="-apple-system,BlinkMacSystemFont,'Segoe UI',Helvetica,Arial,sans-serif" font-size="13" fill="#e6edf3">
+<title>One lead, several projects, one wave</title>
+<desc>A parent folder holds the projects alpha and beta, each with its own plan. The lead session reads their tour and you choose the lots. A wave of fresh sessions does the work, then you review and deliver.</desc>
+<defs><marker id="arq" 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="190" fill="#0d1117"/>
+<text x="20" y="22" font-weight="600" font-size="13.5" fill="#e6edf3">1. Parent folder</text>
+<rect x="20" y="32" width="220" height="140" rx="6" fill="#0d1117" stroke="#8b949e" stroke-width="1.5" stroke-dasharray="5 4"/>
+<text x="130" y="52" text-anchor="middle" font-size="11.5" fill="#8b949e">atelier/ (not a repository)</text>
+<rect x="40" y="64" width="180" height="42" rx="6" fill="#0d1117" stroke="#8b949e" stroke-width="1.5"/>
+<text x="130" y="83" text-anchor="middle" font-weight="600" font-size="13.5" fill="#e6edf3">alpha</text>
+<text x="130" y="98" text-anchor="middle" font-size="11" font-family="ui-monospace,SFMono-Regular,Menlo,monospace" fill="#8b949e">raf init · plan</text>
+<rect x="40" y="116" width="180" height="42" rx="6" fill="#0d1117" stroke="#8b949e" stroke-width="1.5"/>
+<text x="130" y="135" text-anchor="middle" font-weight="600" font-size="13.5" fill="#e6edf3">beta</text>
+<text x="130" y="150" text-anchor="middle" font-size="11" font-family="ui-monospace,SFMono-Regular,Menlo,monospace" fill="#8b949e">raf init · plan</text>
+<text x="300" y="22" font-weight="600" font-size="13.5" fill="#e6edf3">2. The lead</text>
+<rect x="300" y="64" width="210" height="94" rx="6" fill="#0c2d6b" stroke="#58a6ff" stroke-width="2"/>
+<text x="405.0" y="96" text-anchor="middle" font-weight="600" font-size="13.5" fill="#e6edf3">Lead session</text>
+<text x="405.0" y="114" text-anchor="middle" font-size="11.5" fill="#c9d1d9">reads the tour, asks you</text>
+<text x="405.0" y="132" text-anchor="middle" font-size="11" font-family="ui-monospace,SFMono-Regular,Menlo,monospace" fill="#c9d1d9">/cadence:lead</text>
+<text x="570" y="22" font-weight="600" font-size="13.5" fill="#e6edf3">3. The wave</text>
+<rect x="570" y="64" width="200" height="94" rx="6" fill="#0d1117" stroke="#8b949e" stroke-width="1.5"/>
+<text x="670.0" y="96" text-anchor="middle" font-weight="600" font-size="13.5" fill="#e6edf3">Fresh sessions</text>
+<text x="670.0" y="114" text-anchor="middle" font-size="11.5" fill="#8b949e">implement, then review</text>
+<text x="670.0" y="132" text-anchor="middle" font-size="11" font-family="ui-monospace,SFMono-Regular,Menlo,monospace" fill="#8b949e">cadence orchestrate</text>
+<text x="830" y="22" font-weight="600" font-size="13.5" fill="#e6edf3">4. You</text>
+<rect x="830" y="64" width="160" height="94" rx="6" fill="#0d1117" stroke="#8b949e" stroke-width="1.5"/>
+<text x="910.0" y="96" text-anchor="middle" font-weight="600" font-size="13.5" fill="#e6edf3">Review, deliver</text>
+<text x="910.0" y="114" text-anchor="middle" font-size="11.5" fill="#8b949e">one project at a time</text>
+<text x="910.0" y="132" text-anchor="middle" font-size="11" font-family="ui-monospace,SFMono-Regular,Menlo,monospace" fill="#8b949e">/cadence:deliver</text>
+<polyline points="240,111 298,111" fill="none" stroke="#8b949e" stroke-width="1.5" marker-end="url(#arq)"/>
+<polyline points="510,111 568,111" fill="none" stroke="#8b949e" stroke-width="1.5" marker-end="url(#arq)"/>
+<polyline points="770,111 828,111" fill="none" stroke="#8b949e" stroke-width="1.5" marker-end="url(#arq)"/>
+</svg>

package/docs/quickstart-light.svg

@@ -0,0 +1,33 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1010 190" width="1010" height="190" role="img" font-family="-apple-system,BlinkMacSystemFont,'Segoe UI',Helvetica,Arial,sans-serif" font-size="13" fill="#1f2328">
+<title>One lead, several projects, one wave</title>
+<desc>A parent folder holds the projects alpha and beta, each with its own plan. The lead session reads their tour and you choose the lots. A wave of fresh sessions does the work, then you review and deliver.</desc>
+<defs><marker id="arq" 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="190" fill="#ffffff"/>
+<text x="20" y="22" font-weight="600" font-size="13.5" fill="#1f2328">1. Parent folder</text>
+<rect x="20" y="32" width="220" height="140" rx="6" fill="#ffffff" stroke="#57606a" stroke-width="1.5" stroke-dasharray="5 4"/>
+<text x="130" y="52" text-anchor="middle" font-size="11.5" fill="#57606a">atelier/ (not a repository)</text>
+<rect x="40" y="64" width="180" height="42" rx="6" fill="#ffffff" stroke="#57606a" stroke-width="1.5"/>
+<text x="130" y="83" text-anchor="middle" font-weight="600" font-size="13.5" fill="#1f2328">alpha</text>
+<text x="130" y="98" text-anchor="middle" font-size="11" font-family="ui-monospace,SFMono-Regular,Menlo,monospace" fill="#57606a">raf init · plan</text>
+<rect x="40" y="116" width="180" height="42" rx="6" fill="#ffffff" stroke="#57606a" stroke-width="1.5"/>
+<text x="130" y="135" text-anchor="middle" font-weight="600" font-size="13.5" fill="#1f2328">beta</text>
+<text x="130" y="150" text-anchor="middle" font-size="11" font-family="ui-monospace,SFMono-Regular,Menlo,monospace" fill="#57606a">raf init · plan</text>
+<text x="300" y="22" font-weight="600" font-size="13.5" fill="#1f2328">2. The lead</text>
+<rect x="300" y="64" width="210" height="94" rx="6" fill="#ddf4ff" stroke="#0969da" stroke-width="2"/>
+<text x="405.0" y="96" text-anchor="middle" font-weight="600" font-size="13.5" fill="#1f2328">Lead session</text>
+<text x="405.0" y="114" text-anchor="middle" font-size="11.5" fill="#57606a">reads the tour, asks you</text>
+<text x="405.0" y="132" text-anchor="middle" font-size="11" font-family="ui-monospace,SFMono-Regular,Menlo,monospace" fill="#57606a">/cadence:lead</text>
+<text x="570" y="22" font-weight="600" font-size="13.5" fill="#1f2328">3. The wave</text>
+<rect x="570" y="64" width="200" height="94" rx="6" fill="#ffffff" stroke="#57606a" stroke-width="1.5"/>
+<text x="670.0" y="96" text-anchor="middle" font-weight="600" font-size="13.5" fill="#1f2328">Fresh sessions</text>
+<text x="670.0" y="114" text-anchor="middle" font-size="11.5" fill="#57606a">implement, then review</text>
+<text x="670.0" y="132" text-anchor="middle" font-size="11" font-family="ui-monospace,SFMono-Regular,Menlo,monospace" fill="#57606a">cadence orchestrate</text>
+<text x="830" y="22" font-weight="600" font-size="13.5" fill="#1f2328">4. You</text>
+<rect x="830" y="64" width="160" height="94" rx="6" fill="#ffffff" stroke="#57606a" stroke-width="1.5"/>
+<text x="910.0" y="96" text-anchor="middle" font-weight="600" font-size="13.5" fill="#1f2328">Review, deliver</text>
+<text x="910.0" y="114" text-anchor="middle" font-size="11.5" fill="#57606a">one project at a time</text>
+<text x="910.0" y="132" text-anchor="middle" font-size="11" font-family="ui-monospace,SFMono-Regular,Menlo,monospace" fill="#57606a">/cadence:deliver</text>
+<polyline points="240,111 298,111" fill="none" stroke="#57606a" stroke-width="1.5" marker-end="url(#arq)"/>
+<polyline points="510,111 568,111" fill="none" stroke="#57606a" stroke-width="1.5" marker-end="url(#arq)"/>
+<polyline points="770,111 828,111" fill="none" stroke="#57606a" stroke-width="1.5" marker-end="url(#arq)"/>
+</svg>

package/docs/quickstart.md

@@ -0,0 +1,138 @@
+[← cadence](../README.md)
+
+# Start in 10 minutes: one lead, several projects
+
+You keep a folder with a few small projects. A **lead** session looks at all of them, you choose what to
+do, and a program runs each lot in fresh sessions. This page takes you from nothing to the first wave.
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="quickstart-dark.svg">
+  <img alt="A parent folder holds the projects alpha and beta; the lead session reads their tour and you choose; a wave of fresh sessions works; you review and deliver" src="quickstart-light.svg">
+</picture>
+
+The commands below were played on a clean Windows 11 machine with WSL (Ubuntu 24.04, L357): about 40 seconds of commands,
+29 of them for Node and Claude Code. The rest of the ten minutes is reading and typing.
+
+## Before you start
+
+You need four things; the page says how to check each.
+
+- **Node 22.18 or later** (`node --version`). If you have none: [nvm](https://github.com/nvm-sh/nvm), or the NodeSource
+  package of your distribution (`setup_22.x`). Node 20 is not enough.
+- **git, with an identity.** Without one, the first `git commit` stops with `empty ident name`:
+
+  ```sh
+  git config --global user.name "Your Name"
+  git config --global user.email "you@example.com"
+  ```
+
+- **Claude Code, installed and logged in.** `claude auth status` must print `"loggedIn": true`. A wave opens
+  `claude -p` sessions; `cadence orchestrate` checks `claude auth status` first and, when Claude Code is not logged in,
+  is refused before it writes anything in the plan (« claude n'est pas connecté : lancer `claude` puis /login »).
+  Install it from [claude.com/claude-code](https://claude.com/claude-code), then run `claude` once and log in.
+- **A test command** for each project (`npm test`, `pytest`, `go test ./...`). The wave runs it after every change.
+
+## Install
+
+```sh
+npm install -g @sylad/cadence
+cadence --version
+```
+
+If npm answers `EACCES: permission denied, mkdir '/usr/lib/node_modules/@sylad'`, your Node belongs to the system.
+Give npm a folder of your own, then install again:
+
+```sh
+npm config set prefix ~/.npm-global
+export PATH="$HOME/.npm-global/bin:$PATH"     # add this line to ~/.bashrc or ~/.zshrc too
+npm install -g @sylad/cadence
+```
+
+The skills and agents come as a Claude Code plugin:
+
+```sh
+claude plugin marketplace add Sylad/cadence
+claude plugin install cadence@cadence
+```
+
+## The parent folder
+
+The lead works from a folder that holds the projects as sub-folders. The folder itself is not a repository.
+Each project is one: give it a plan with `raf init`, a first lot, and the test command, in one commit.
+Run the block once per project (here `alpha`, then `beta`):
+
+```sh
+mkdir alpha && cd alpha
+git init -b main
+raf init
+raf add "Create hello.txt containing hello" --estimate 0.25
+cat > cadence.yaml <<'EOF'
+orchestrate:
+  test: test -f hello.txt        # passes once the first lot has created hello.txt
+EOF
+git add -A && git commit -m "chore: init raf"
+cd ..
+```
+
+What it does: `raf init` writes the plan (`.cadence/raf.yaml`), a commit hook and a `.gitignore` line. The commit
+that adds them cites no lot and is no gap: like any commit that touches only the plan files, it is left out of `raf check`
+and of the tour's drift column (what `raf init` writes counts as plan files, `cadence.yaml` created in the same commit
+with its `orchestrate.test` line included; a code file in it would make it a `commit sans lot` again). `cadence.yaml` is the project's settings file; its single
+`orchestrate.test` line is the minimum the wave needs, and without it the tour warns `porte de tests absente`.
+The folder is empty, so the gate here is `test -f hello.txt`, which the toy lot satisfies. On a project that already exists,
+put its own test command there (`npm test`, `pytest`, `go test ./...`): `npm test` in a folder without `package.json` fails.
+The reference for every other key is [orchestrate](orchestrate.md) and [deliver](deliver.md).
+
+Then, from the parent folder:
+
+```sh
+cadence lead tour
+```
+
+It prints one line per project: lots in progress, drift, next lot, repository state. Expect `alpha · en cours rien ·
+dérive aucune · … · prochain L1 Create hello.txt containing hello · dépôt propre`, and the same for `beta`. This is the table the lead reads.
+
+## Start the lead
+
+Open Claude Code in the parent folder and call the skill:
+
+```sh
+claude
+```
+
+then type `/cadence:lead` (or say « pilot all projects »). The lead runs the tour, reports in a table, proposes three
+lots and **waits for your priority**: nothing starts before you answer. [The lead workflow](lead.md) draws every step.
+
+## The first wave
+
+When you pick `alpha:L1`, the lead launches a wave. You can do it yourself, from the parent folder:
+
+```sh
+cadence orchestrate alpha:L1 --dry-run
+cadence orchestrate alpha:L1 --wave first
+```
+
+The first line only prints what would run: each step, its model and its budget. The second runs the lot in fresh
+sessions: implement, then review, and hands the lot back to you. From inside a project, write `.:L1` instead of
+`alpha:L1` (the project is a sub-folder of the current folder, so `alpha:L1` from inside `alpha` finds nothing).
+
+The sessions of a wave never push and never deliver. You read the table, answer the questions it brings back, then
+`/cadence:deliver` ships one project at a time ([deliver](deliver.md)). How waves, budgets and reviews work: [orchestrate](orchestrate.md).
+
+## If it stops
+
+| You see | Cause | Do |
+|---|---|---|
+| `npm: command not found` | no Node | install Node 22.18+ (above) |
+| `EACCES: permission denied, mkdir '/usr/lib/node_modules/@sylad'` | system-owned Node | `npm config set prefix ~/.npm-global` (above) |
+| `fatal: empty ident name … not allowed` | no git identity | the two `git config --global` lines (above) |
+| « claude n'est pas connecté : lancer `claude` puis /login » | Claude Code not logged in | `claude`, log in, then `claude auth status` |
+| `porte de tests absente` | no `orchestrate.test` | the `cadence.yaml` line of the project block |
+| `alpha:L1 … introuvable` | launched from inside `alpha` | use `.:L1` |
+
+A problem that is not here: [open an issue](https://github.com/Sylad/cadence/issues/new/choose) with `cadence --version` and the command you ran.
+
+## Not played
+
+The lead skill and a wave played to the end (review, `raf done`, delivery) were not played on that machine, which was not logged
+in to Claude Code; the tour, the dry run and the dry delivery were. Other systems (macOS, native Linux, PowerShell without WSL) were not played either.

package/docs/raf.md

@@ -21,7 +21,10 @@
   the plan, a journal), or the QA expectations file (`docs/qa/expectations.md`,
   or the file named by `qa.expectations`; the lead commits the `qa-reviewer`'s draft of it). Such a commit is never a "commit without a lot", and it
   does not count as work on the lots it cites: it is absent from `raf commits`,
-  does not start a `todo` lot, does not make a code review stale, and
+  does not start a `todo` lot, does not make a code review stale, is not in the commit
+  count that `raf now`, `cadence lead tour` and `cadence session start` show for a lot in
+  progress (the same count as `raf commits` and `raf show`: after `plan: L1 démarré` alone,
+  `raf now` prints no commit and the tour `L1 (0 commit)`, L379; the commit column and the tooltip of `raf gantt` read the same count, L381), and
   `cadence deliver` does not announce the lots it cites as delivered. The files
   decide, never the subject: a `chore(plan): …` commit that touches a source
   file is a commit like any other.
@@ -47,6 +50,7 @@ raf gantt                         # .cadence/gantt.html (next to the plan)
 
 | Command | Effect |
 |---|---|
+| `raf --version` · `raf -v` | print the version of the package, as `cadence --version` does (L376); only as the first argument, `raf show --version` stays an unknown option |
 | `raf init [--project name] [--prefix L] [--no-hook]` | create the plan, install the hook, add `.playwright-mcp/` to `.gitignore` |
 | `raf add "title" [--estimate d] [--quickwin] [--visible [--screen page\|component\|journey]] [--spec] [--public "title"] [--after L2,L4] [--uses banc,passerelle] [--parent L3]` | add a lot or a sub-task, print its id (`--public`: the lot's title in the public's words, written as `public:` right after `title:`; `--screen`: the screen a visible lot creates or changes — a new `page`, a new `component` or a modified `journey` — written as `screen:` right after `visible:`, shown by `raf show`; it requires `--visible`, and `raf check` reports a `screen:` without `visible:` or with another value as an error. Only `page` triggers the spec step of `orchestrate` (L209), never inferred from the title; `--spec`: the lot changes a behaviour (something a user, an API client or another service can observe), written as `spec: true` right after `screen:`, `visible:`, `quickwin:` or `estimate:` (whichever comes last), shown by `raf show`, refused on a sub-task. Also set by the lead at planning time, never inferred from the title); `--uses`: the shared resources the lot occupies, written as `uses: [banc, passerelle]` after `after:` and before `created:` ([shared resources](#shared-resources-uses-and-resources), L251), refused on a sub-task) |
 | `raf add "title" --every <days>` · `raf did <id> ["text"]` | recurring lot: `every` (days) and `last` (last time done) fields; the lot stays `todo`, `raf now` and `session start` list it under « Récurrent » with « dû depuis N j » / « prochain dans N j »; `raf did` resets the count (spec: `docs/superpowers/specs/2026-10-04-L11-tache-recurrente.md`) |
@@ -129,6 +133,10 @@ then the legacy `docs/plan/raf.yaml`.
 - `raf init` creates `.cadence/raf.yaml` and `.cadence/notes/` (with a `.gitkeep`, so git tracks the empty folder). It refuses
   when a plan already exists where it would create one, a legacy `docs/plan/raf.yaml` included: it never creates a second plan
   beside it. With `plan: path` in `cadence.yaml`, or `--file`, the plan and nothing else is created there.
+  The commit that follows `raf init` opens no « commit sans lot » gap (L377): the plan, `.cadence/notes/.gitkeep`, the
+  `.playwright-mcp/` line of `.gitignore` and a `cadence.yaml` created in the same commit with only `plan:` and `orchestrate:` keys are plan files, so such a commit is
+  a plan-only commit for `raf check`, the hook and the tour. Any other file in it, another `.gitignore` line, a `deliver:` or `session:` key
+  in a new `cadence.yaml` or a later edit of it keeps it a commit like any other.
 - A project that still has `docs/plan/raf.yaml` (and no `.cadence/raf.yaml`) keeps working, read and written as before. Every command
   that loads the plan prints one line on **stderr** (standard output, `--json` included, is unchanged) with the move to do —
   `cd <repository root> && mkdir -p .cadence && git mv docs/plan/raf.yaml .cadence/raf.yaml` (`mv` outside a git repository or when git does not track the file, where `git mv` would fail; the root is spelled out, quoted if

package/docs/releasing.md

@@ -3,7 +3,7 @@
 # Releasing
 
 A version exists in three places and is published in two; a release does all of it, in this order.
-`cadence release patch|minor|major [--dry-run]` (L341) prepares step 1 and prints steps 2 to 5 in order; it publishes nothing.
+`cadence release patch|minor|major [--dry-run]` (L341) prepares step 1 and prints steps 2 to 6 in order; it publishes nothing.
 
 1. Bump `version` in `package.json` (then `npm install` to refresh `package-lock.json`),
    `.claude-plugin/plugin.json` and `.claude-plugin/marketplace.json`, and write the version's section of
@@ -16,15 +16,22 @@ A version exists in three places and is published in two; a release does all of
    in that commit, not before the review. A commit that touches any other file
    — or another field of a manifest, or a dependency in `package-lock.json` — is work like any other and has
    to be reviewed.
-2. Run the plugin evaluation, `npm run eval:plugin` (billed, see [Evaluating the plugin](#evaluating-the-plugin-before-a-release)),
+2. Replay the project's gate on that commit: `cadence verify --gate --sha HEAD` (L380). The version commit empties
+   `## [Unreleased]` of `CHANGELOG.md`, and a test that read only that section would pass before it and fail after — the red
+   publish run of 1.14.0 (L368) and the stopped 1.15.2 (L380) — so the suite is run on the commit that will be tagged, before the
+   billed evaluation and before the tag. Red: fix it in a commit of its own and redo the version commit. A test that looks
+   for the entry of a lot in the CHANGELOG reads the section that carries it (`[Unreleased]` or the published version) through
+   `changelogSectionOf` (`test/changelog-section.ts`); `test/changelog-garde.test.ts` refuses a test that selects `## [Unreleased]`
+   of the repository's CHANGELOG itself.
+3. Run the plugin evaluation, `npm run eval:plugin` (billed, see [Evaluating the plugin](#evaluating-the-plugin-before-a-release)),
    on that version commit; a case below the threshold stops the release until you have read it in the report.
-3. `git tag v<version> && git push origin main v<version>` — the tag starts `.github/workflows/publish.yml`,
+4. `git tag v<version> && git push origin main v<version>` — the tag starts `.github/workflows/publish.yml`,
    which publishes to npm through Trusted Publishing (OIDC, no token stored anywhere): it checks the tag
    matches `package.json`, `.claude-plugin/plugin.json` and `.claude-plugin/marketplace.json` and that `CHANGELOG.md` has a `## [x.y.z]` section for it (no section, no publication), then `npm publish --provenance`, where `prepublishOnly` runs the type-check and the
    tests and `prepare` builds `dist/`; a red suite stops the publication; then it creates the GitHub release with that CHANGELOG section as its text. The trusted publisher is declared
    once on npmjs.com (package settings → Trusted Publisher → GitHub Actions, `Sylad/cadence`, `publish.yml`).
-4. Watch the run: `gh run watch` (or `gh run list --workflow publish.yml`).
-5. Check the effect: `npm view @sylad/cadence version` answers the new version.
+5. Watch the run: `gh run watch` (or `gh run list --workflow publish.yml`).
+6. Check the effect: `npm view @sylad/cadence version` answers the new version.
    A run is safe to re-run, and two runs for one tag queue instead of racing (`concurrency` per ref, never cancelling the one that publishes):
    a version already on npm skips `npm publish`, and a GitHub release that is missing is created (`--verify-tag`)
    while an existing one is left alone. If the package is on npm but the release is still missing, re-run the job;
@@ -32,10 +39,12 @@ A version exists in three places and is published in two; a release does all of
 
 `.github/workflows/tests.yml` runs the type-check and the test suite on the same runner image and `npm ci` as the publish job, in a matrix of Node 22 and 24 (the minimum `engines.node` allows, and the Node the publish job uses), and never publishes: start it with `gh workflow run tests.yml --ref <branch>` or by pushing a `diag/**` branch, to see on the runner what a red publish run saw.
 
+The suite runs the same way on your machine as on that runner, **without `raf` or `cadence` installed** (L384): `test/global-setup.ts` replaces, in the `PATH` of the tests, every folder outside the repository that carries a `raf` or a `cadence` (`~/.local/bin`, the global npm folder, the plugin's `bin/`) by a mirror of that folder without those two names — the other tools stay, `node` included. A test that relies on the installed tool turns red on the lead's machine and in the gate, not only in the publish run: the 1.16.0 publication failed because the post-commit hook of `test/raf-init-commit.test.ts` (R2) found `raf` in the developer's `PATH` and not on the runner. A test that needs `raf` (a hook, a script) builds its own from the sources (`CADENCE_TEST_PACKAGE`).
+
 The Claude Code plugin is read from the repository, so pushing `main` is what updates it; npm is what
 `npx @sylad/cadence` and a global install read, and only the tag publishes there. A missing tag, or a red
 publish run, leaves npm behind without any other error — 0.3.0 and 0.4.0 were never published — hence
-step 5.
+step 6.
 
 ## `cadence release`
 
@@ -70,6 +79,7 @@ introduction (the newest version first, as the file is read). Exit code 1 when a
 version files are written, the commit is not ready. `--dry-run` reads the forms the same way (nothing is written) and exits 1 on the same findings, so the forms can be checked before the real run.
 
 It prints the lead's steps, in order, and runs none: the `git add` of exactly the files of the version commit and the commit,
+`cadence verify --gate --sha HEAD` (always printed, before the evaluation and the tag),
 `npm run eval:plugin -- --trust-plugin` (only when `package.json` has that script), `git tag v<x.y.z>`, `git push origin <branch> v<x.y.z>`,
 `gh run watch`, `npm view <package> version` (not for a private package) and, only with a `.claude-plugin/plugin.json`,
 the plugin update: `claude plugin marketplace update <marketplace>` first (without it the installed plugin stays at the old

package/docs/session.md

@@ -3,7 +3,7 @@
 # session
 
 ```sh
-cadence session start              # notes from the last close, lots in progress (commit count, `0 commit` included, and last activity; silent ones flagged),
+cadence session start              # notes from the last close, lots in progress (work commit count, `0 commit` included — plan commits are not counted, as in `raf commits` — and last activity; silent ones flagged),
                                    # work done since yesterday by lot, drift, repo state, 3 proposals
 cadence session start --since "3 days ago" --idle 2
 cadence session close              # commits by lot since the last `session start`,
@@ -26,7 +26,7 @@ cadence session context            # `ctx 42 % (84000/200000)`: the context of Y
 `session close` takes it as its window and names it in the section title: `Commits de la période (depuis
 l'ouverture de 09:12)` (with the date when it is not today). A close never moves the boundary, refused
 or not: run again without a `session start` in between (the `session-close` skill does, after fixing a
-point), it still reports since that opening instead of an empty period. With no recorded opening, or an
+point), it still reports since that opening instead of an empty period. The period journal (`Fait depuis`, `Commits de la période`) lists work commits only: plan commits (`plan: L1 démarré`) are left out, as in `raf commits`. With no recorded opening, or an
 unreadable file, the window is the current day, said as such (`depuis 2026-09-28 00:00`); `--since` is
 quoted as given. (A `session.json` written by 0.18.0 after a close, `depuis la clôture de …`, is still read.)
 

package/docs/whats-new.md

@@ -4,6 +4,9 @@
 
 ## In two lines
 
+- **1.16.1**: publishes 1.16.0 (tagged, never published), plus `raf gantt` counting commits without plan commits, one login check per `orchestrate --continue` launch, and a wider `CHANGELOG.md` conflict settled by worktree integration.
+- **1.16.0**: easier arrival for a team already equipped and for a new user: a `docs/with-your-tools.md` page, `raf --version`, no gap after `raf init`, Claude Code login checked before any write, commit counts without plan commits.
+- **1.15.1**: a getting-started page (`docs/quickstart.md`) takes a lead of several projects from install to the first wave and lists the usual stops; GitHub issue templates for bugs and requests; a contrast fix in the dark figure.
 - **1.15.0**: worktree integration settles the `CHANGELOG.md` conflict by itself; `--integrate` accepts a lot corrected and reviewed outside the wave; `raf ignore` clears a plan commit citing lots; `raf done` gives the plan commit.
 - **1.14.1**: publishes 1.14.0 (tagged, never published): Node 22.18 or later is required; `plan.commit`, `plan.onWrite`, `orchestrate.testReplay`, `spec green`, `ref coverage` and `verify --gate --sha`.
 - **1.14.0**: Node 22.18 or later is now required (Node 20 dropped). `plan.commit`, `plan.onWrite` and `orchestrate.testReplay` fit a wave to your hooks, files and load; `spec green`, `ref coverage` and `verify --gate --sha` are new.
@@ -36,6 +39,12 @@ Each is a paragraph in [docs/whats-new.md](whats-new.md) and a full section in [
 
 The long form of « In two lines » above (the README no longer carries a « What's new » section since L326: it links here). The full history, with the date of each version, is in [CHANGELOG.md](../CHANGELOG.md).
 
+**1.16.1**: 1.16.0 was tagged but never published: a test added with it (R2 of L377) supposed `raf` installed in the `PATH`, found it on the developer's machine and not on the runner, and the publish run went red, a fault of the test and not of the tool (L384); 1.16.1 publishes it as it stands, so everything listed under 1.16.0 below arrives with it. The test suite no longer depends on a `raf` or a `cadence` installed on the machine (L384, `docs/releasing.md`): the test now has its hook run `raf` from the sources, and the suite removes every installed `raf` and `cadence` from the `PATH` of the tests (the other tools stay), so such a test is red on the lead's machine and in the gate, not only at publication. `raf gantt` counts the commits of a lot as `raf commits` does (L381, `docs/raf.md`): plan commits no longer inflate the commit column nor the tooltip of a bar, a lot whose only commit is `plan: L1 démarré` reads 0, and the filter reads the files of the commits in one `git log` call instead of one `git diff-tree` per commit (about 20 s down to 2 s on 2,700 commits for the Gantt page); a test now holds the same count for `cadence session start` and `close`, and the test that held `raf now` to the lots it shows can now fail. With `--continue`, `cadence orchestrate` reads `claude auth status` once per launch instead of again, up to 20 s each, for every candidate lot of every round (L382, `docs/orchestrate.md`), and the message quoted in `docs/quickstart.md` and `docs/orchestrate.md` no longer nests backticks inside backticks, which broke the Markdown rendering. The worktree integration of `cadence orchestrate` also settles a `CHANGELOG.md` conflict where one lot adds a section under `[Unreleased]` (`### Fixed`) with its entry and the other a bare entry (L383, `docs/orchestrate.md`): the bare entry is filed under the section the other side added, one section title and one entry per lot, instead of handing the lot back; with no single section to file it under, the conflict stays by hand.
+
+**1.16.0**: easier arrival, for a team that already has its tools and for someone who has never used cadence. A new page, `docs/with-your-tools.md` (L363, a short section of the README), is written for teams that already have a tracker, a `HANDOFF.md`, ADRs and a commit convention: what cadence does not replace, what is optional (`raf`, `session start|close`, the hook), what plugs into what you have (a plan kept by another tool, read-only, with your own ticket ids; `plan.commit` for the subject of the plan commits, which by default still read `plan: L12 démarré (orchestrate …)`, GitHub issue #15, L375; `docs.sync` for your docs) and what it adds (waves with an automatic review, a deliver that verifies the effect), with a figure. The other changes come from the walkthrough of a new user. `raf --version` and `raf -v` print the version, as `cadence --version` does, instead of `Unknown option '--version'` (L376, only as the first argument: `raf show --version` stays an unknown option), and `cadence orchestrate alpha:L1` launched from inside `alpha` says why the folder is not found (the project is a sub-folder of the current folder; inside a repository `.:L1` works). The commit that follows `raf init` no longer opens a « commit sans lot » gap (L377, `docs/raf.md`, `docs/quickstart.md`): what `raf init` writes and a `cadence.yaml` created in the same commit with only `plan:` and `orchestrate:` keys count as plan files, while a code file, another `.gitignore` line, a `deliver:` key or a later edit of `cadence.yaml` keeps it a gap, and the getting-started page drops its `raf ignore` workaround. `cadence orchestrate` checks that Claude Code is logged in (`claude auth status`) before starting a lot (L378, `docs/orchestrate.md`): when it is not, the command is refused before any write to the plan (no `raf start`, no commit, the lot stays `todo`) and the message says to run `claude` then `/login`, `--dry-run` reports it with a `⚠`; before, the lot was started and failed at the first session with `Not logged in`, left `doing`. `raf now`, `cadence lead tour` and `cadence session start` count the commits of a lot as `raf commits` does (L379, `docs/raf.md`, `docs/lead.md`, `docs/session.md`): plan commits, which touch only plan files, are left out, so a lot just started reads `0 commit` instead of `1 commit(s)` while `raf commits` lists nothing, and the period journals of `session start` and `session close` leave them out too. `cadence release` prints `cadence verify --gate --sha HEAD` right after the version commit, before the plugin evaluation and the tag, so the suite runs on the commit that will be published (L380, `docs/releasing.md`), and the tests that look for the entry of a lot in `CHANGELOG.md` read the section that carries it, not `[Unreleased]` alone, which the version commit empties, a fault that had stopped the release of 1.14.0 and again the next one (a guard test refuses the pattern).
+
+**1.15.1**: a way in for a lead who has never used cadence. A new getting-started page, `docs/quickstart.md` (L358, a section of the README), goes from install to the first wave: the parent folder, `raf init` in each project with the minimal `cadence.yaml`, the tour, `/cadence:lead`, the first wave, and a table of the usual stops (no Node, `EACCES`, no git identity, Claude Code not logged in). It comes from a walkthrough measured on a clean machine. Two GitHub issue templates, bug and request, are forms (L358, `.github/ISSUE_TEMPLATE/`); a `config.yml` turns off blank issues and points to the getting-started page, and the bug form asks for `cadence --version`, the steps and what was printed. The dark getting-started figure (`docs/quickstart-dark.svg`) draws the grey texts of « Lead session » in a lighter grey, 4.26:1 on the blue before and now above the 4.5:1 of WCAG 2.2 AA, and `docs/overview.md` lists `docs/quickstart.md` in its map of the pages (L374).
+
 **1.15.0**: fewer lots handed back, and fewer manual detours, on the lead's side. The integration of `cadence orchestrate` in worktree mode no longer hands a lot back for a `CHANGELOG.md` conflict when the branch was released while the lot lived (L369, `docs/orchestrate.md`): an entry that the release moved under the published version is no longer read as a removal, and the entries a lot's commits wrote then reworded are dropped in favour of the version at the tip of the lot's branch, so one final entry per lot is left. `cadence orchestrate --resume --integrate <project:lot>` now accepts a lot handed back for its budget or a non-compliant review that the lead corrected and reviewed outside the wave (L370, `docs/orchestrate.md`, `docs/lead.md`): fix in the worktree, `raf review` there with the plan committed there, then `--integrate`; the lot restarts at the integration step with that verdict instead of the refusal « le lot n'est pas rendu à l'étape d'intégration ». A review older than a commit of the lot, or none, keeps the refusal. If the lead also wrote on that lot in the repository's plan meanwhile, the plan conflict of the rebase is settled by the program, provided that plan commit adds nothing but lot reviews. `raf ignore` also acknowledges a commit that cites known lots (L372): a plan commit that creates lots or cites a setting in parentheses was counted as work on those lots and could not be cleared; an acknowledged commit now counts for no lot, `raf commits` no longer lists it, and `raf check --ignored` does. `raf done <lot>` says that it did not commit the plan (L371): it never has, `raf` only writes the plan file, so when the plan or a file `plan.onWrite` produces has changes, the message prints the `git add` and `git commit` that take them, the subject following the project's `plan.commit` template.
 
 **1.14.1**: 1.14.0 was tagged but never published (a test of the Node minimum read only `[Unreleased]`, which the version commit empties, a fault of the test and not of the tool, L368); 1.14.1 publishes it as it stands, so everything listed under 1.14.0 below arrives with it, Node 22.18 or later first.

package/docs/with-your-tools-dark.svg

@@ -0,0 +1,41 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1010 290" width="1010" height="290" role="img" font-family="-apple-system,BlinkMacSystemFont,'Segoe UI',Helvetica,Arial,sans-serif" font-size="13" fill="#e6edf3">
+<title>cadence next to the tools you already have</title>
+<desc>Your tools stay as they are: the tracker, HANDOFF.md, the ADRs and your commit convention. The plan can be read from your tracker's file, the plan commits follow your format and your docs are kept in step. On top, cadence adds orchestrated waves with an automatic review, and a deliver that verifies the effect.</desc>
+<defs><marker id="arw" 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="290" fill="#0d1117"/>
+<text x="20" y="22" font-weight="600" font-size="13.5" fill="#e6edf3">1. Your tools (kept)</text>
+<rect x="20" y="36" width="290" height="52" rx="6" fill="#0d1117" stroke="#8b949e" stroke-width="1.5"/>
+<text x="165" y="57" text-anchor="middle" font-weight="600" font-size="13.5" fill="#e6edf3">Linear, Jira</text>
+<text x="165" y="74" text-anchor="middle" font-size="11.5" fill="#8b949e">tickets, board, assignment</text>
+<rect x="20" y="98" width="290" height="52" rx="6" fill="#0d1117" stroke="#8b949e" stroke-width="1.5"/>
+<text x="165" y="119" text-anchor="middle" font-weight="600" font-size="13.5" fill="#e6edf3">HANDOFF.md</text>
+<text x="165" y="136" text-anchor="middle" font-size="11.5" fill="#8b949e">your hand-over notes</text>
+<rect x="20" y="160" width="290" height="52" rx="6" fill="#0d1117" stroke="#8b949e" stroke-width="1.5"/>
+<text x="165" y="181" text-anchor="middle" font-weight="600" font-size="13.5" fill="#e6edf3">ADRs</text>
+<text x="165" y="198" text-anchor="middle" font-size="11.5" fill="#8b949e">your decisions</text>
+<rect x="20" y="222" width="290" height="52" rx="6" fill="#0d1117" stroke="#8b949e" stroke-width="1.5"/>
+<text x="165" y="243" text-anchor="middle" font-weight="600" font-size="13.5" fill="#e6edf3">Conventional Commits</text>
+<text x="165" y="260" text-anchor="middle" font-size="11.5" fill="#8b949e">your commits</text>
+<text x="360" y="22" font-weight="600" font-size="13.5" fill="#e6edf3">2. What plugs in</text>
+<rect x="360" y="36" width="290" height="52" rx="6" fill="#0d1117" stroke="#8b949e" stroke-width="1.5"/>
+<text x="505" y="57" text-anchor="middle" font-weight="600" font-size="13.5" fill="#e6edf3">plan: read-only</text>
+<text x="505" y="74" text-anchor="middle" font-size="11.5" fill="#8b949e">your tracker export is the plan</text>
+<rect x="360" y="98" width="290" height="52" rx="6" fill="#0d1117" stroke="#8b949e" stroke-width="1.5"/>
+<text x="505" y="119" text-anchor="middle" font-weight="600" font-size="13.5" fill="#e6edf3">plan.commit</text>
+<text x="505" y="136" text-anchor="middle" font-size="11.5" fill="#8b949e">plan commits in your format</text>
+<rect x="360" y="160" width="290" height="52" rx="6" fill="#0d1117" stroke="#8b949e" stroke-width="1.5"/>
+<text x="505" y="181" text-anchor="middle" font-weight="600" font-size="13.5" fill="#e6edf3">docs.sync</text>
+<text x="505" y="198" text-anchor="middle" font-size="11.5" fill="#8b949e">your docs kept in step</text>
+<rect x="360" y="222" width="290" height="52" rx="6" fill="#0d1117" stroke="#8b949e" stroke-width="1.5"/>
+<text x="505" y="243" text-anchor="middle" font-weight="600" font-size="13.5" fill="#e6edf3">commit-msg hook</text>
+<text x="505" y="260" text-anchor="middle" font-size="11.5" fill="#8b949e">checked before a wave runs</text>
+<text x="700" y="22" font-weight="600" font-size="13.5" fill="#e6edf3">3. What cadence adds</text>
+<rect x="700" y="36" width="290" height="100" rx="6" fill="#0c2d6b" stroke="#58a6ff" stroke-width="2"/>
+<text x="845" y="76" text-anchor="middle" font-weight="600" font-size="13.5" fill="#e6edf3">Orchestrated wave</text>
+<text x="845" y="96" text-anchor="middle" font-size="11.5" fill="#c9d1d9">fresh sessions, review in the loop</text>
+<rect x="700" y="148" width="290" height="100" rx="6" fill="#0c2d6b" stroke="#58a6ff" stroke-width="2"/>
+<text x="845" y="188" text-anchor="middle" font-weight="600" font-size="13.5" fill="#e6edf3">Deliver</text>
+<text x="845" y="208" text-anchor="middle" font-size="11.5" fill="#c9d1d9">waits for CI, verifies the effect</text>
+<polyline points="310,145 358,145" fill="none" stroke="#8b949e" stroke-width="1.5" marker-end="url(#arw)"/>
+<polyline points="650,145 698,145" fill="none" stroke="#8b949e" stroke-width="1.5" marker-end="url(#arw)"/>
+</svg>

package/docs/with-your-tools-light.svg

@@ -0,0 +1,41 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1010 290" width="1010" height="290" role="img" font-family="-apple-system,BlinkMacSystemFont,'Segoe UI',Helvetica,Arial,sans-serif" font-size="13" fill="#1f2328">
+<title>cadence next to the tools you already have</title>
+<desc>Your tools stay as they are: the tracker, HANDOFF.md, the ADRs and your commit convention. The plan can be read from your tracker's file, the plan commits follow your format and your docs are kept in step. On top, cadence adds orchestrated waves with an automatic review, and a deliver that verifies the effect.</desc>
+<defs><marker id="arw" 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="290" fill="#ffffff"/>
+<text x="20" y="22" font-weight="600" font-size="13.5" fill="#1f2328">1. Your tools (kept)</text>
+<rect x="20" y="36" width="290" height="52" rx="6" fill="#ffffff" stroke="#57606a" stroke-width="1.5"/>
+<text x="165" y="57" text-anchor="middle" font-weight="600" font-size="13.5" fill="#1f2328">Linear, Jira</text>
+<text x="165" y="74" text-anchor="middle" font-size="11.5" fill="#57606a">tickets, board, assignment</text>
+<rect x="20" y="98" width="290" height="52" rx="6" fill="#ffffff" stroke="#57606a" stroke-width="1.5"/>
+<text x="165" y="119" text-anchor="middle" font-weight="600" font-size="13.5" fill="#1f2328">HANDOFF.md</text>
+<text x="165" y="136" text-anchor="middle" font-size="11.5" fill="#57606a">your hand-over notes</text>
+<rect x="20" y="160" width="290" height="52" rx="6" fill="#ffffff" stroke="#57606a" stroke-width="1.5"/>
+<text x="165" y="181" text-anchor="middle" font-weight="600" font-size="13.5" fill="#1f2328">ADRs</text>
+<text x="165" y="198" text-anchor="middle" font-size="11.5" fill="#57606a">your decisions</text>
+<rect x="20" y="222" width="290" height="52" rx="6" fill="#ffffff" stroke="#57606a" stroke-width="1.5"/>
+<text x="165" y="243" text-anchor="middle" font-weight="600" font-size="13.5" fill="#1f2328">Conventional Commits</text>
+<text x="165" y="260" text-anchor="middle" font-size="11.5" fill="#57606a">your commits</text>
+<text x="360" y="22" font-weight="600" font-size="13.5" fill="#1f2328">2. What plugs in</text>
+<rect x="360" y="36" width="290" height="52" rx="6" fill="#ffffff" stroke="#57606a" stroke-width="1.5"/>
+<text x="505" y="57" text-anchor="middle" font-weight="600" font-size="13.5" fill="#1f2328">plan: read-only</text>
+<text x="505" y="74" text-anchor="middle" font-size="11.5" fill="#57606a">your tracker export is the plan</text>
+<rect x="360" y="98" width="290" height="52" rx="6" fill="#ffffff" stroke="#57606a" stroke-width="1.5"/>
+<text x="505" y="119" text-anchor="middle" font-weight="600" font-size="13.5" fill="#1f2328">plan.commit</text>
+<text x="505" y="136" text-anchor="middle" font-size="11.5" fill="#57606a">plan commits in your format</text>
+<rect x="360" y="160" width="290" height="52" rx="6" fill="#ffffff" stroke="#57606a" stroke-width="1.5"/>
+<text x="505" y="181" text-anchor="middle" font-weight="600" font-size="13.5" fill="#1f2328">docs.sync</text>
+<text x="505" y="198" text-anchor="middle" font-size="11.5" fill="#57606a">your docs kept in step</text>
+<rect x="360" y="222" width="290" height="52" rx="6" fill="#ffffff" stroke="#57606a" stroke-width="1.5"/>
+<text x="505" y="243" text-anchor="middle" font-weight="600" font-size="13.5" fill="#1f2328">commit-msg hook</text>
+<text x="505" y="260" text-anchor="middle" font-size="11.5" fill="#57606a">checked before a wave runs</text>
+<text x="700" y="22" font-weight="600" font-size="13.5" fill="#1f2328">3. What cadence adds</text>
+<rect x="700" y="36" width="290" height="100" rx="6" fill="#ddf4ff" stroke="#0969da" stroke-width="2"/>
+<text x="845" y="76" text-anchor="middle" font-weight="600" font-size="13.5" fill="#1f2328">Orchestrated wave</text>
+<text x="845" y="96" text-anchor="middle" font-size="11.5" fill="#57606a">fresh sessions, review in the loop</text>
+<rect x="700" y="148" width="290" height="100" rx="6" fill="#ddf4ff" stroke="#0969da" stroke-width="2"/>
+<text x="845" y="188" text-anchor="middle" font-weight="600" font-size="13.5" fill="#1f2328">Deliver</text>
+<text x="845" y="208" text-anchor="middle" font-size="11.5" fill="#57606a">waits for CI, verifies the effect</text>
+<polyline points="310,145 358,145" fill="none" stroke="#57606a" stroke-width="1.5" marker-end="url(#arw)"/>
+<polyline points="650,145 698,145" fill="none" stroke="#57606a" stroke-width="1.5" marker-end="url(#arw)"/>
+</svg>

package/docs/with-your-tools.md

@@ -0,0 +1,95 @@
+[← cadence](../README.md)
+
+# cadence with your tools
+
+A team that already has a tracker (Linear, Jira), a `HANDOFF.md`, ADRs and a commit convention does not have to choose.
+cadence is a few plain files next to the code and a set of commands; each part is optional, and the parts that touch your habits bend to them.
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="with-your-tools-dark.svg">
+  <img alt="Your tools stay: tracker, HANDOFF.md, ADRs, commit convention. The plan read from your tracker's file, the plan commits in your format and your docs kept in step plug in. cadence adds orchestrated waves with an automatic review, and a deliver that verifies the effect" src="with-your-tools-light.svg">
+</picture>
+
+## What cadence does not replace
+
+| You have | cadence does not | What it keeps out of |
+|---|---|---|
+| A tracker (Linear, Jira, GitHub issues) | no board, no assignment, no sprint, no comments, no notifications: its plan is a list of *lots* in a file | the tracker stays where the team agrees what to do and who does it |
+| `HANDOFF.md` | writes no hand-over document: `cadence session next "…"` keeps a one-line memo for the next `session start`, nothing more | keep your `HANDOFF.md`; cadence never reads or edits it |
+| ADRs | records no decision: a lot's notes are working notes (what was tried, what is left) | decisions that must last stay in your ADRs |
+| Conventional Commits (commitlint, husky) | does not impose a commit format: a commit belongs to a lot when it **cites the lot's id**, in the scope (`feat(ENG-12): …`) or anywhere in the message | your `commit-msg` hook keeps judging every commit, including the ones cadence writes (below) |
+
+## What is optional
+
+Nothing here needs the rest. Take one piece, leave the others:
+
+- **`raf`, the plan** (`raf init`, `raf add`, `raf start`, `raf done`): only if you want the plan in the repository. A plan kept by another tool is read as it is, never written (next section).
+- **`cadence session start` and `cadence session close`**: a morning and an evening report (lots in progress, commits without a lot, what is uncommitted or unpushed). Skip them if your stand-up or `HANDOFF.md` does that; they change nothing in the repository.
+- **`raf hook install`**: warns when a commit cites a lot that is not started. It never blocks a commit unless you set `hook.autostart` to say so.
+- **`cadence orchestrate` and `cadence deliver`**: a wave needs a plan it can read, a `raf` plan or a read-only one, and nothing else of the above; it works on a plan cadence never writes. `cadence deliver` is set by its own `deliver:` block and runs without a wave.
+
+## What plugs into what you have
+
+**A plan kept by another tool, read-only.** Point cadence at the file your tracker (or its export script) writes and map its keys. `raf list`, `raf now`, `raf commits`, `raf check`, `cadence session` and `cadence orchestrate` read it; `raf add|start|done|note` refuse and leave the write to your tool. The lot ids are yours (`ENG-12`), so your commits keep citing the ticket:
+
+```yaml
+# tracker/tickets.yaml
+tickets:
+  - key: ENG-12
+    summary: Export CSV
+    state: In Progress
+    points: 2
+    opened: 2026-10-20
+  - key: ENG-13
+    summary: Fix login redirect
+    state: Todo
+    points: 1
+    opened: 2026-10-21
+```
+
+```yaml
+# cadence.yaml, at the repository root
+plan:
+  path: tracker/tickets.yaml
+  lots: tickets                 # the root key holding the list
+  fields:                       # cadence's field: the key in your file
+    id: key
+    title: summary
+    status: state
+    estimate: points
+    created: opened
+  statuses:
+    todo: [Todo]
+    doing: [In Progress]
+    done: [Done]
+```
+
+All the keys (`add`, `files`, `ignore`, sub-tasks, `repos`…) are in [docs/raf.md](raf.md#a-plan-elsewhere-or-in-another-format).
+
+**The subject of the plan commits.** A wave commits the plan itself (the lot started, the review recorded). By default they still read `plan: L12 démarré (orchestrate …)`, which a commitlint `config-conventional` hook refuses: `plan` is not one of its types (GitHub issue #15). Set `plan.commit` in `cadence.yaml` to change the subject of all of them, and `cadence orchestrate --dry-run` runs each one through your real `commit-msg` hook before the wave starts:
+
+```yaml
+plan:
+  path: tracker/tickets.yaml
+  commit: 'chore({lot}): {action} (orchestrate {vague})'
+```
+
+`{lot}` is required, `{action}` and `{vague}` are optional; the full rules are in [docs/raf.md](raf.md#the-subject-of-the-plan-commits-plancommit-l343). The commits of the work itself are `type(<lot>): …` (`feat(ENG-12): …`), which is Conventional Commits already; a convention that wants something else is stated in the project's `CLAUDE.md`, which every session reads.
+
+**Your existing docs.** `docs.sync` tells cadence which of your documents must change when some code changes, and `raf check` reports a lot that left them behind. It adds no document of its own: the README, the `docs/` pages and the CHANGELOG you already have are the ones it watches.
+
+```yaml
+docs:
+  sync:
+    - paths: [src/**, '!**/*.test.ts']
+      docs: [README.md, docs/usage.md]
+```
+
+See [Documentation that follows the code](news.md#documentation-that-follows-the-code).
+
+## What it adds
+
+- **Orchestrated waves with an automatic review.** A lead picks the lots; each one goes to a fresh session that writes the tests first, commits and stops. A second, fresh session then reviews the commits against the lot and its notes before the lot can be closed. A red test suite or a missing document is sent back for correction, not found in the pull request. [docs/orchestrate.md](orchestrate.md), [docs/quickstart.md](quickstart.md).
+- **A deliver that verifies the effect.** `cadence deliver` waits for the CI of the pushed commit, runs your deploy commands, then replays the checks you declared (a URL that answers, a version that matches, a command that succeeds). A delivery is done when those checks pass, not when the pipeline says "success". [docs/deliver.md](deliver.md).
+
+Start small: a read-only plan and `plan.commit` are enough to see a wave run in a repository that keeps its tracker, its `HANDOFF.md`, its ADRs and its commit convention.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sylad/cadence",
-  "version": "1.15.0",
+  "version": "1.16.1",
   "description": "A small, repo-native working method: a versioned plan linked to your commits, a changelog with screenshots, session rituals and deliveries proven by their effect.",
   "license": "MIT",
   "author": "Sylvain Ladoire",
@@ -44,6 +44,12 @@
     "docs/fonctionnement-lead-dark.svg",
     "docs/lead-workflow-light.svg",
     "docs/lead-workflow-dark.svg",
+    "docs/quickstart.md",
+    "docs/quickstart-light.svg",
+    "docs/quickstart-dark.svg",
+    "docs/with-your-tools.md",
+    "docs/with-your-tools-light.svg",
+    "docs/with-your-tools-dark.svg",
     "docs/cycle-vague-light.svg",
     "docs/cycle-vague-dark.svg",
     "LICENSE"