cohorte 2.4.0 → 2.6.0

package/CHANGELOG.md

@@ -7,6 +7,72 @@ short, user-facing, most recent first. One `## <version> — <YYYY-MM-DD>` secti
 > They are history and are deliberately not rewritten — every command gained a `cohorte-` prefix
 > in 2.0.0.
 
+## 2.6.0 — 2026-08-14
+
+- **Two ways to type the same command, and one of them silently doesn't work.** The docs wrote
+  `npx cohorte install`, the Francois extension's manifest names a bare `cohorte` binary, and
+  nothing said why the two could not be the same string. They cannot: `npx` fetches a package
+  into a cache and runs it once, leaving nothing on `PATH`, and a Francois panel may only spawn
+  a **bare binary name resolved on `PATH`**. So the extension's requirement read like a
+  preference the rest of the documentation contradicted.
+
+  Every command is now written one way — `cohorte <verb>`, after `npm i -g cohorte` — across the
+  README, the docs, both shell installers, the CLI's own banners, the `/cohorte-doctor` fix
+  lines, and the `install` string `/cohorte-init-pipeline` writes into a repo's committed
+  `pipeline.json`. `npx cohorte@latest <verb>` still works and is still the right call for a
+  one-off on a machine you don't own; it is named once, as the escape hatch it is.
+
+- **The cost of pinning, removed before it could bite.** `install` and `update` lay down the core
+  carried by the CLI that runs them. `npx cohorte@latest` made that self-correcting; a global
+  install does not, so `cohorte update` on a CLI left at an old version would re-lay an old core
+  and report success — an update that updates nothing.
+
+  Both verbs now compare themselves against the registry when they finish and print exactly what
+  to run (`npm i -g cohorte@latest`) when they are behind. It is never fatal, never blocks a
+  successful install, costs a 2.5s fetch with no `npm view` fallback, and stays silent on any
+  failure — an offline install pays 2.5 seconds and says nothing. `COHORTE_NO_VERSION_CHECK=1`
+  opts out; `CI` opts out already.
+
+  Nothing in the pipeline changed: no new agent, no gate, no template — this release needs no
+  `/cohorte-update-pipeline`.
+
+## 2.5.0 — 2026-08-14
+
+- **Everything the pipeline knew about your repo, it would only say to a coding agent.**
+  `/cohorte-doctor` reads the health of an install and `specs/*.md` holds the board, but both
+  answers cost a session: you opened Claude Code, ran a command, and read prose. There was no
+  way to ask "is this repo's pipeline sound?" from a shell script, a CI job, or anything that
+  isn't an LLM.
+
+  Two read-only commands now answer without an agent in the loop:
+
+  ```sh
+  cohorte specs     # the board: id · status · branch · title, from specs/*.md frontmatter
+  cohorte doctor    # the /cohorte-doctor checks — exits 1 when any check is bad
+  ```
+
+  `doctor` **exits 1 on any bad check**, so it drops into CI as-is. Both reuse the dashboard's
+  own readers, so the board, the dashboard and the CLI can never give three answers about one
+  repo. `--porcelain` gives one record per line with `U+001F` between fields — a spec title
+  with a space in it never misaligns a column — and `--json` gives the native document.
+
+- **The pipeline, in Francois.** A third shape, `--panel` (on `specs`, `doctor` and `metrics`),
+  emits the payload a [Francois](https://github.com/antoine-gmnz/francois) extension panel
+  validates against. It exists for
+  [**francois-plugin-cohorte**](https://github.com/TheBidouilleAgency/francois-plugin-cohorte):
+  a manifest-only extension — no code, no binary — that renders the 30-day cost, the doctor
+  report and the spec board as three panels beside your sessions, on any project with a
+  `PIPELINE.md`.
+
+  ```sh
+  npm i -g cohorte                                   # a Francois extension may only spawn a
+  francois ext install TheBidouilleAgency/cohorte    # bare binary on PATH — never npx, never a shell
+  ```
+
+  This is the only Francois-aware surface in the package, and it is one flag wide. Nothing in
+  the pipeline itself changed: no new agent, no new gate, no template to re-render — this
+  release needs no `/cohorte-update-pipeline`.
+
 ## 2.4.0 — 2026-08-13
 
 - **The pipeline froze *what* to build, never *how much*.** A spec pins the contract and the

package/README.md

@@ -46,9 +46,9 @@ The doctrine is one set of source prompts. The installer renders them into whate
 actually reads, and branches the instructions on what it can actually do:
 
 ```sh
-npx cohorte install --runtime=codex,cursor     # pick explicitly
-npx cohorte install --all-runtimes             # every supported one
-npx cohorte install                            # detects what you have and asks
+cohorte install --runtime=codex,cursor     # pick explicitly
+cohorte install --all-runtimes             # every supported one
+cohorte install                            # detects what you have and asks
 ```
 
 | | Commands | Subagents | Gate | Workflows |
@@ -82,10 +82,10 @@ install is unchanged.
 
 Only one hard requirement — the rest is optional and independent:
 
-- **Node ≥ 18 + npm** — _required_, for the `npx` installer that lays down the core. Nothing else needs it.
+- **Node ≥ 18 + npm** — _required_, for the `cohorte` CLI that lays down the core. Nothing else needs it.
 - **[`uv`](https://docs.astral.sh/uv/) + the Serena CLI** — _optional_, the default code-retrieval
   provider. Install it separately (`uv tool install -p 3.13 serena-agent && uv tool update-shell`); the
-  `npx` install neither needs nor touches it, so the order between the two is irrelevant. Without Serena
+  cohorte install neither needs nor touches it, so the order between the two is irrelevant. Without Serena
   the pipeline still runs — agents just fall back to Grep/Read. Having it installed **before**
   `/cohorte-init-pipeline` lets init wire it in one pass (otherwise `/cohorte-update-pipeline` wires it later).
 - **On a new machine cloning a repo that's already pipeline-ised:** the Serena registration is committed
@@ -94,15 +94,25 @@ Only one hard requirement — the rest is optional and independent:
 
 ## Install
 
-The pipeline ships as an npm package (`cohorte`), so releases are semver-tagged and
-`npx` always fetches the latest published version — no clone needed, works on macOS/Linux/Windows.
+The pipeline ships as an npm package (`cohorte`), so releases are semver-tagged — no clone
+needed, works on macOS/Linux/Windows. **Install it once, globally**; every command below is
+written as `cohorte …`, and that single form is what the rest of this README, the docs, and the
+[Francois extension](https://github.com/TheBidouilleAgency/francois-plugin-cohorte) all assume:
+
+```sh
+npm i -g cohorte
+```
+
+`npx cohorte <verb>` runs any of them without installing anything, for a one-off on a machine
+you don't own. It is the escape hatch, not the path — see
+[why one form](https://thebidouilleagency.github.io/cohorte/reference/installers).
 
 **Global (recommended)** — install the generic core ONCE into `~/.claude`; it serves every repo on
 your machine. Nothing is copied per project; the gate hook is registered once and reads each repo's
 own `gate-config.json`:
 
 ```sh
-npx cohorte install --global
+cohorte install --global
 ```
 
 The per-project part is NOT the core — it's the **profile** `/cohorte-init-pipeline` generates and you
@@ -116,7 +126,7 @@ repo; each teammate just runs the same global one-liner once, guided by the comm
 
 ```sh
 # inside your project (or pass its path as an argument)
-npx cohorte install
+cohorte install
 ```
 
 Copies the core into `<project>/.claude`, committed with the repo. Choose this when you want
@@ -178,8 +188,9 @@ Sanity-check `PIPELINE.md`, commit it, and run `/cohorte-brainstorm`.
 ## Update
 
 ```sh
-npx cohorte@latest update --global    # the shared core in ~/.claude (recommended setup)
-npx cohorte@latest update             # a repo's bundled core in <project>/.claude
+npm i -g cohorte@latest           # refresh the CLI — the core it lays down is its own
+cohorte update --global           # the shared core in ~/.claude (recommended setup)
+cohorte update                    # a repo's bundled core in <project>/.claude
 ```
 
 (Script equivalents: `sh install.sh --update [--global]` / `.\install.ps1 -Update [-Global]`.)
@@ -200,9 +211,9 @@ maintenance command you ever run (`/cohorte-build` auto-grows surfaces as specs
 A browser view of pipeline state, for when a checklist beats scanning files:
 
 ```sh
-npx cohorte dashboard          # serves http://localhost:4317 (Ctrl-C to stop)
-npx cohorte dashboard <path>   # start focused on another project
-npx cohorte dashboard --port=4400 --open   # custom port, open the browser
+cohorte dashboard          # serves http://localhost:4317 (Ctrl-C to stop)
+cohorte dashboard <path>   # start focused on another project
+cohorte dashboard --port=4400 --open   # custom port, open the browser
 ```
 
 **Bound to `127.0.0.1` by default** — the dashboard's actions execute code (install/update/reset,
@@ -234,6 +245,40 @@ source lives in `dashboard/app/`, built to `dashboard/dist/` at publish time). T
 are reimplemented in JS, so the dashboard needs no Claude session to compute state. See
 [`dashboard/README.md`](dashboard/README.md) for the architecture.
 
+## Reading a project without an agent
+
+The two read-only halves of the pipeline, in the shell:
+
+```sh
+cohorte specs              # the board: id · status · branch · title, from specs/*.md
+cohorte doctor             # the /cohorte-doctor checks — exits 1 when any check is bad
+cohorte metrics --days=30  # cost + runtime per command, from Claude Code's transcripts
+```
+
+`doctor`'s exit code is what makes it a CI step, and the three of them are what the Francois
+extension below renders.
+
+`doctor`'s exit code makes it a CI step as-is. Add `--porcelain` for one record per line with
+`U+001F` between fields (a spec title with a space in it never misaligns a column), or `--json`
+for the native document. Both reuse the dashboard's own readers, so the board and the CLI can
+never give two answers about one repo.
+
+`--panel` — on `specs`, `doctor` and `metrics` — emits the payload shape a
+[Francois](https://github.com/antoine-gmnz/francois) extension panel expects. It is the one
+Francois-aware surface in the package, and it exists for
+[**francois-plugin-cohorte**](https://github.com/TheBidouilleAgency/francois-plugin-cohorte): a
+manifest-only extension that renders the spec board, the doctor report and the 30-day cost as
+three panels beside your sessions.
+
+A Francois extension may only spawn a **bare binary name resolved on `PATH`** — never `npx`,
+never a shell, never an absolute path. So this one needs the global install, and nothing else
+will do:
+
+```sh
+npm i -g cohorte
+francois ext install TheBidouilleAgency/cohorte
+```
+
 ## Releasing (maintainers)
 
 Versions are tracked with npm semver — the published package is the release artifact.
@@ -246,8 +291,10 @@ a version bump just run the sanity checks.
 `npm version patch --no-git-tag-version`), commit, push — CI does the rest (publish + tag +
 release). No local tagging needed.
 
-`npx cohorte@latest …` then serves the new version everywhere; installed cores record
+`npm i -g cohorte@latest` then serves the new version everywhere; installed cores record
 it in `.claude/pipeline/VERSION` and bundled repos in their committed `pipeline.json` pointer.
+`install` and `update` compare themselves against the registry and say so when they are behind,
+so a CLI pinned at an old version cannot quietly re-lay an old core.
 
 ## The commands
 
@@ -380,7 +427,7 @@ profile/
   SCHEMA.md             # field reference
   cohorte.config.template.yaml   # seeds ~/.claude/cohorte.config.yaml (kanban)
 scripts/                # worktree-isolation templates + the shipped preflight/kanban scripts
-dashboard/              # local web cockpit (npx … dashboard) — see dashboard/README.md
+dashboard/              # local web cockpit (cohorte dashboard) — see dashboard/README.md
   server/               # dependency-free node runtime (serves the built app + JSON/stream API)
   app/                  # Vite + React source (built to dashboard/dist/ at publish time)
 ```

package/bin/cli.js

@@ -2,11 +2,16 @@
 // cohorte — installer CLI for the portable multi-agent pipeline.
 // Cross-platform, dependency-free port of install.sh / install.ps1.
 //
-//   npx cohorte install              # bundle the core into <cwd>/.claude (committable)
-//   npx cohorte install [target]     # same, into another project
-//   npx cohorte install --global     # one shared core in ~/.claude
-//   npx cohorte update [--global]    # refresh the core, keep every generated file
-//   npx cohorte version
+//   npm i -g cohorte                 # once — the CLI, and the `cohorte` binary on PATH
+//   cohorte install                  # bundle the core into <cwd>/.claude (committable)
+//   cohorte install [target]         # same, into another project
+//   cohorte install --global         # one shared core in ~/.claude
+//   cohorte update [--global]        # refresh the core, keep every generated file
+//   cohorte version
+//
+// `npx cohorte <verb>` runs any of these without installing anything — it is the
+// escape hatch, not the documented path: a Francois extension panel can only spawn
+// a bare binary on PATH, and a globally installed CLI is what puts one there.
 
 'use strict';
 
@@ -37,6 +42,8 @@ Usage:
   cohorte update    [target] [--global] [--runtime=a,b | --all-runtimes]
   cohorte dashboard [target] [--port=N] [--host=ADDR] [--open]
   cohorte metrics   [target] [--days=N] [--since=ISO] [--runs] [--json]
+  cohorte specs     [target] [--porcelain | --json | --panel]
+  cohorte doctor    [target] [--porcelain | --json | --panel]
   cohorte version
 
 Commands:
@@ -56,8 +63,18 @@ Commands:
             ~/.claude/projects — nothing to enable, and it covers runs that
             already happened. Worktree-aware, so a feature adds up. --json for
             the raw rollup, --runs to include every individual invocation.
+  specs     The spec board of <target>: id, status, branch, title, read from the
+            frontmatter of specs/*.md. --porcelain for one record per line with
+            U+001F between fields, --json for the list.
+  doctor    The same checks /cohorte-doctor runs (core, pointer, profile, agents,
+            hook, gate, retrieval, design, isolation, specs), without a coding
+            agent in the loop. Exits 1 when any check is bad, 0 otherwise, so it
+            drops into CI. --porcelain / --json as above.
   version   Print the installed CLI version.
 
+  --panel on specs, doctor and metrics emits the payload a Francois extension
+  panel expects (github.com/TheBidouilleAgency/francois-plugin-cohorte).
+
 Runtimes (--runtime=): ${adapter.listRuntimes().join(', ')}
   The pipeline's doctrine is one set of source prompts; the installer renders them into
   whatever each coding agent reads (markdown + frontmatter, plain markdown, or TOML) and
@@ -86,13 +103,19 @@ const metricsFlags = [];
 const isMetricsFlag = (a) =>
   a === '--json' || a === '--runs' || a.startsWith('--days=') || a.startsWith('--since=');
 
+// How `specs`, `doctor` and `metrics` render. One variable, not one flag per command,
+// so `--porcelain` never means two different things depending on where it sits.
+let format = 'human';
+
 // Which coding agents to install for. Empty ⇒ resolved later (detect, then ask on a TTY,
 // then fall back to claude — the only behaviour that existed before 2.2.0).
 let wantRuntimes = [];
 
 for (const a of args) {
-  if (a === 'install' || a === 'update' || a === 'dashboard' || a === 'metrics') mode = a;
-  else if (isMetricsFlag(a)) metricsFlags.push(a);
+  if (a === 'install' || a === 'update' || a === 'dashboard' || a === 'metrics'
+      || a === 'specs' || a === 'doctor') mode = a;
+  else if (a === '--porcelain' || a === '--panel') format = a.slice(2);
+  else if (isMetricsFlag(a)) { if (a === '--json') format = 'json'; metricsFlags.push(a); }
   else if (a === '--all-runtimes') wantRuntimes = adapter.listRuntimes();
   else if (a === '--runtimes' || a === '--runtime') {
     console.error('error: --runtime needs a value, e.g. --runtime=codex,cursor'); process.exit(2);
@@ -136,10 +159,45 @@ if (mode === 'dashboard') {
   return;
 }
 
+// --- specs / doctor: read-only reports on <target> ---------------------------
+// Both reuse the dashboard's own readers, so the board and the CLI can never drift
+// into two answers about the same repo. Nothing here writes or spawns anything.
+if (mode === 'specs' || mode === 'doctor') {
+  const report = require('./report.js');
+  const { state, scanSpecs } = require('../dashboard/server/doctor.js');
+  const globalDir = process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), '.claude');
+
+  if (mode === 'specs') {
+    const records = report.specRecords(target, scanSpecs);
+    if (format === 'json') console.log(JSON.stringify({ project: target, specs: records }, null, 2));
+    else if (format === 'porcelain') { if (records.length) console.log(report.specsPorcelain(records)); }
+    else if (format === 'panel') console.log(report.specsPanel(records));
+    else console.log(report.specsHuman(records));
+    process.exit(0);
+  }
+
+  // `state` is async (it probes versions), so this branch owns the whole tail.
+  state({ projectRoot: target, globalDir, cliVersion: VERSION }).then((s) => {
+    const records = report.checkRecords(s);
+    if (format === 'json') console.log(JSON.stringify(s, null, 2));
+    else if (format === 'porcelain') { if (records.length) console.log(report.doctorPorcelain(records)); }
+    else if (format === 'panel') console.log(report.doctorPanel(records));
+    else console.log(report.doctorHuman(s, records));
+    // A bad check is a failure the shell can branch on; warn and skip are not.
+    process.exit(s.summary.bad > 0 && format !== 'panel' ? 1 : 0);
+  }).catch((e) => {
+    console.error(`error: ${e && e.message ? e.message : e}`);
+    process.exit(1);
+  });
+  return;
+}
+
 // --- metrics: cost + runtime per command ------------------------------------
 // The collector is ESM and this CLI is CommonJS, so it runs as a child process rather
 // than being required. stdio is inherited so --json stays pipeable.
 if (mode === 'metrics') {
+  // `--panel` is not in isMetricsFlag (it is not metrics-specific), so forward it here.
+  if (format === 'panel') metricsFlags.push('--panel');
   const script = path.join(pkgRoot, 'scripts', 'metrics', 'collect.mjs');
   if (!fs.existsSync(script)) {
     console.error(`error: metrics collector not found at ${script}`);
@@ -238,7 +296,7 @@ function copyCore() {
   resolveTemplateConditionals(pipelineDir);
   // Copy the *.template files AND the shipped executables (kanban-move.sh,
   // preflight.sh). Until 1.2.4 this loop took only `.template`, so every
-  // `npx cohorte install/update` produced a core missing both scripts — and since
+  // `cohorte install/update` produced a core missing both scripts — and since
   // every caller chains them with `|| true`, the result was silent: no kanban card
   // moves, no error. The shell installers named them explicitly
   // and this port drifted. The rule below needs no list to keep in sync: a `<x>.sh`
@@ -333,7 +391,7 @@ function renderSurfaces() {
 
   // Every agent in core/agents/ EXCEPT the *.template.md ones, which /cohorte-init-pipeline renders
   // per-surface. Until 1.2.6 this was a hardcoded ['review.md', 'release.md'] that never grew
-  // the agents the shell installers copy, so `npx cohorte install` shipped a command with no
+  // the agents the shell installers copy, so `cohorte install` shipped a command with no
   // agent to dispatch — the run reported the command as not installed.
   // Reading the directory needs no list to keep in sync with the shell installers.
   const agentDir = path.join(src, 'core', 'agents');
@@ -562,7 +620,7 @@ function registerGlobalHook() {
   const file = path.join(dest, 'hooks', 'gate.py');
   const base = path.basename(file);
   // Trailing-quote tolerant: the Windows form is `py "C:\...\gate.py"`, and a
-  // bare .endsWith() missed it — which is how repeat `npx cohorte install`
+  // bare .endsWith() missed it — which is how repeat `cohorte install`
   // runs accumulated a duplicate registration every time (gate.py then ran
   // once per copy on every Bash call).
   const isGate = entry => (entry.hooks || []).some(
@@ -604,7 +662,7 @@ function bumpPointerVersion(ptr) {
 // configured on this machine, and — on a TTY — let the human confirm, because installing
 // into a runtime they don't use litters a config dir they never asked us to touch. With no
 // TTY and no flag we install for Claude Code alone: the behaviour of every version before
-// the adapter, so a scripted `npx cohorte install` keeps doing exactly what it did.
+// the adapter, so a scripted `cohorte install` keeps doing exactly what it did.
 async function selectRuntimes() {
   if (wantRuntimes.length) return wantRuntimes;
   const found = adapter.detectRuntimes();
@@ -622,6 +680,33 @@ async function selectRuntimes() {
   return picked.length ? [...new Set(picked)] : found;
 }
 
+// --- staleness notice --------------------------------------------------------
+// `install` and `update` write a core taken from THIS package, so the core is only
+// as fresh as the CLI that ran. `npx cohorte@latest` made that self-correcting; a
+// global install does not — `cohorte update` on a pinned 2.5.0 would re-lay the
+// 2.5.0 core forever and report success, which is an update that updates nothing.
+// So the CLI checks its own version against the registry and says what to run.
+// Never fatal, never blocking a successful install: a short fetch, no `npm view`
+// fallback, and silence on any failure. COHORTE_NO_VERSION_CHECK / CI opt out.
+async function staleVersionNotice() {
+  if (process.env.COHORTE_NO_VERSION_CHECK || process.env.CI) return;
+  let latest = null;
+  try {
+    const v = require('../dashboard/server/versions.js');
+    latest = await v.latestNpm({ timeoutMs: 2500, fallback: false });
+    if (!latest || v.cmpSemver(VERSION, latest) >= 0) return;
+  } catch { return; }
+  // How you got here decides the fix: under npx the package is transient (and may
+  // have come from the cache rather than the registry), so the answer is to pin
+  // @latest; with a global install the answer is to upgrade the global.
+  const viaNpx = /[\\/]_npx[\\/]/.test(pkgRoot);
+  console.log(`
+! You ran cohorte ${VERSION}, but ${latest} is published — the core just written is ${VERSION}.
+  ${viaNpx
+    ? 'Re-run as  npx cohorte@latest <same command>  to lay down the current core.'
+    : 'Upgrade with  npm i -g cohorte@latest  and re-run the same command.'}`);
+}
+
 // --- run ---------------------------------------------------------------------
 (async () => {
 const selected = await selectRuntimes();
@@ -640,6 +725,8 @@ if (selected.length > 1) {
   console.log('  The doctrine is identical; what differs is enforcement — run /cohorte-doctor in');
   console.log('  each one to see what it can and cannot guarantee.');
 }
+// Last, so a stale CLI is the final thing on screen rather than scrolled past.
+await staleVersionNotice();
 })();
 
 async function installOne() {
@@ -685,7 +772,7 @@ if (scope === 'global') {
   copyCore();
   // Register on UPDATE too — install.sh and install.ps1 always have, and this
   // port skipping it is why a duplicated or stale-matcher registration could
-  // never be repaired by `npx cohorte update`: the only route that rewrites it
+  // never be repaired by `cohorte update`: the only route that rewrites it
   // was a full re-install, which is not what anyone runs to get a fix. Safe to
   // run every time — registration reconciles only gate.py entries and leaves
   // every other hook and settings key untouched.
@@ -705,7 +792,7 @@ Per repo:
      teammates know to install the global core (${REPO_URL}).
   3. Commit PIPELINE.md + .claude/, then  /cohorte-brainstorm  to start a feature.
 
-Update later with:  npx cohorte@latest update --global
+Update later with:  npm i -g cohorte@latest && cohorte update --global
 
 Global kanban config, user-scoped — optional:
   · One consolidated file: ${path.join(globalDir, 'cohorte.config.yaml')}
@@ -730,7 +817,7 @@ Next:
      PIPELINE.md + renders one implementer agent per surface.
   3. Commit PIPELINE.md, then  /cohorte-brainstorm  to start a feature.
 
-Update later with:  npx cohorte@latest update
+Update later with:  npm i -g cohorte@latest && cohorte update
 Prefer one shared core across all your repos?  Re-run with  --global.`);
 } else {
   console.log(`→ updating pipeline core in ${dest} (keeping your PIPELINE.md + rendered agents)`);

package/bin/report.js

@@ -0,0 +1,141 @@
+'use strict';
+// Machine-readable reports for `cohorte specs` and `cohorte doctor`.
+//
+// Both commands read what the dashboard already computes (dashboard/server/doctor.js:
+// `scanSpecs` and `state`) and render it four ways:
+//
+//   default      a human table on a terminal
+//   --porcelain  one record per line, fields separated by U+001F (the ASCII unit
+//                separator) — stable, greppable, and immune to a spec title that
+//                contains a space, a tab or a pipe
+//   --json       the native document (the full doctor state, the spec list)
+//   --panel      the payload shape a Francois extension panel validates against
+//                (`{rows:[{key,value,tone}]}` / `{rows:[{id,cells,tone}]}`). This is
+//                the ONLY Francois-aware surface in cohorte; everything else here is
+//                generic. See github.com/TheBidouilleAgency/francois-plugin-cohorte.
+//
+// Dependency-free, and it never writes anything.
+
+const US = String.fromCharCode(0x1f); // ASCII unit separator (U+001F)
+
+// A spec's status → a display tone. The tones are the ones a status column can carry
+// anywhere (terminal colour, panel row tone); `busy` marks the two statuses that mean
+// "a command is mid-flight on this spec".
+const STATUS_TONE = {
+  draft: 'neutral',
+  frozen: 'neutral',
+  'in-progress': 'busy',
+  'in-review': 'busy',
+  shipped: 'ok',
+  blocked: 'error',
+};
+
+// doctor's four check states → the same tone vocabulary. `skip` is not a failure:
+// a check that does not apply to this project (no design system, no worktrees) reads
+// neutral, never warn.
+const CHECK_TONE = { ok: 'ok', warn: 'warn', bad: 'error', skip: 'neutral' };
+
+// Collapse anything that would break the line format or a single-line cell. A spec
+// title is free text written by a human in YAML frontmatter — it can contain a newline
+// continuation, and it must never split one record into two. A stray separator inside a
+// field goes the same way, and so does the padding a doctor `fix` carries for terminal
+// alignment — in a one-line panel cell that padding reads as a hole.
+function flat(value) {
+  return String(value == null ? '' : value)
+    .replace(new RegExp(`[\\s${US}]+`, 'g'), ' ')
+    .trim();
+}
+
+function specRecords(projectRoot, scanSpecs) {
+  return scanSpecs(projectRoot).map((s) => ({
+    id: s.id,
+    title: s.title || '',
+    status: s.status || 'unknown',
+    branch: s.branch || '',
+    file: s.file,
+    tone: STATUS_TONE[s.status] || 'warn', // an unknown status IS the warning
+  }));
+}
+
+function specsPorcelain(records) {
+  return records
+    .map((r) => [r.id, r.title, r.status, r.branch, r.tone].map(flat).join(US))
+    .join('\n');
+}
+
+function specsPanel(records) {
+  return JSON.stringify({
+    rows: records.map((r) => ({
+      id: flat(r.id),
+      tone: r.tone,
+      cells: { id: flat(r.id), title: flat(r.title), status: flat(r.status), branch: flat(r.branch) },
+    })),
+  });
+}
+
+function specsHuman(records) {
+  if (!records.length) return 'no specs in ./specs — /cohorte-spec writes the first one';
+  const w = (k) => Math.max(...records.map((r) => flat(r[k]).length), k.length);
+  const [wi, ws, wb] = [w('id'), w('status'), w('branch')];
+  const head = `${'id'.padEnd(wi)}  ${'status'.padEnd(ws)}  ${'branch'.padEnd(wb)}  title`;
+  const rows = records.map(
+    (r) => `${flat(r.id).padEnd(wi)}  ${flat(r.status).padEnd(ws)}  ${flat(r.branch).padEnd(wb)}  ${flat(r.title)}`,
+  );
+  return [head, '-'.repeat(head.length), ...rows].join('\n');
+}
+
+function checkRecords(state) {
+  return state.checks.map((c) => ({
+    id: c.id,
+    label: c.label,
+    status: c.status,
+    detail: c.detail,
+    fix: c.fix || '',
+    tone: CHECK_TONE[c.status] || 'neutral',
+  }));
+}
+
+function doctorPorcelain(records) {
+  return records
+    .map((r) => [r.id, r.label, r.status, r.detail, r.fix].map(flat).join(US))
+    .join('\n');
+}
+
+// key-value, one row per check: the check's label keyed against what it found. The fix
+// rides in the value for a failing check — a panel row has nowhere else to put it, and
+// a health report that says "broken" without saying "run this" is half a report.
+function doctorPanel(records) {
+  return JSON.stringify({
+    rows: records.map((r) => ({
+      key: flat(r.label),
+      value: flat(r.fix && r.tone !== 'ok' ? `${r.detail} → ${r.fix}` : r.detail),
+      tone: r.tone,
+    })),
+  });
+}
+
+function doctorHuman(state, records) {
+  const mark = { ok: 'ok  ', warn: 'warn', bad: 'BAD ', skip: 'skip' };
+  const lines = [`cohorte doctor — ${state.project}`, ''];
+  for (const r of records) {
+    lines.push(`${mark[r.status] || '?   '}  ${r.label} — ${flat(r.detail)}`);
+    if (r.fix && r.status !== 'ok') lines.push(`        fix: ${flat(r.fix)}`);
+  }
+  const s = state.summary;
+  lines.push('', `${s.ok} ok · ${s.warn} warn · ${s.bad} bad · ${s.skip} skipped`);
+  return lines.join('\n');
+}
+
+module.exports = {
+  US,
+  STATUS_TONE,
+  CHECK_TONE,
+  specRecords,
+  specsPorcelain,
+  specsPanel,
+  specsHuman,
+  checkRecords,
+  doctorPorcelain,
+  doctorPanel,
+  doctorHuman,
+};

package/core/commands/cohorte-update-pipeline.md

@@ -35,11 +35,15 @@ the human's choices — so `/cohorte-init-pipeline` never needs re-running for a
 - Otherwise use the published npm package (preferred — installs the latest tagged release):
 
   ```sh
-  npx cohorte@latest update --global   # global core
-  npx cohorte@latest update            # bundled core of the current repo
+  npm i -g cohorte@latest              # the CLI itself, refreshed
+  cohorte update --global              # global core
+  cohorte update                       # bundled core of the current repo
   ```
 
-- If npm/npx is unavailable, fall back to piping the installer from the repo's latest `main`:
+  If `cohorte` is not on PATH, `npx cohorte@latest update [--global]` runs the same thing
+  without installing anything.
+
+- If npm is unavailable, fall back to piping the installer from the repo's latest `main`:
 
   ```sh
   curl -fsSL https://raw.githubusercontent.com/TheBidouilleAgency/cohorte/main/install.sh | sh -s -- --update --global

package/core/templates/steps/init-pipeline/04-write-render.md

@@ -83,8 +83,8 @@
 9. **Write the pointer** `<state>/pipeline.json` (committed — this is how a teammate who clones the repo
    knows which core to install):
    `{ "pipeline": "cohorte", "mode": "<bundled|global>", "core_version": "<contents of the
-   installer's pipeline/VERSION>", "install": "<per mode: bundled ⇒ \"npx cohorte install\"
-   note that the core is committed under .claude/; global ⇒ \"npx cohorte install --global\"
+   installer's pipeline/VERSION>", "install": "<per mode: bundled ⇒ \"npm i -g cohorte && cohorte install\"
+   note that the core is committed under .claude/; global ⇒ \"npm i -g cohorte && cohorte install --global\"
    (or, without npm: curl -fsSL https://raw.githubusercontent.com/TheBidouilleAgency/cohorte/main/install.sh | sh -s -- --global;
    Windows: install.ps1 -Global from the same repo)> " }`.
    In **global** mode also add, near the top of `<memory>`, a one-liner:

package/dashboard/README.md

@@ -1,6 +1,6 @@
 # Dashboard — architecture
 
-A local web cockpit for the pipeline, launched with `npx cohorte dashboard`
+A local web cockpit for the pipeline, launched with `cohorte dashboard`
 (see the [root README](../README.md#dashboard--a-local-web-cockpit) for user-facing docs).
 
 ## Two halves: shipped runtime vs dev build
@@ -12,7 +12,7 @@ dashboard/
   dist/        → app/ built output. Shipped, served by server/. Git-ignored, rebuilt at publish.
 ```
 
-- **`server/`** is plain node (`http`, `fs`, `child_process`) — no deps, so `npx … dashboard`
+- **`server/`** is plain node (`http`, `fs`, `child_process`) — no deps, so `cohorte dashboard`
   needs no install. It serves `dist/` as static files + a small JSON/stream API.
 - **`app/`** is a Vite+React app built to `dist/`. `npm run build:dashboard` (root) runs
   `npm --prefix dashboard/app ci && … run build`; CI does this before `npm pack`/`publish`

package/dashboard/server/doctor.js

@@ -58,18 +58,18 @@ function mk(id, label, status, detail, fix) {
 function checkCore(v) {
   if (v.installMode === 'none') {
     return mk('core', 'Core & pointer', 'bad', 'no pipeline core installed for this project',
-      'npx cohorte install   (or --global)');
+      'cohorte install   (or --global)');
   }
   if (v.pointer.present && v.pointer.core_version && v.installedVersion &&
       v.pointer.core_version !== v.installedVersion) {
     return mk('core', 'Core & pointer', 'warn',
       `pointer says core ${v.pointer.core_version} but installed core is ${v.installedVersion}`,
-      'npx cohorte update   (reconcile the pointer)');
+      'cohorte update   (reconcile the pointer)');
   }
   if (v.freshness === -1) {
     return mk('core', 'Core & pointer', 'warn',
       `core ${v.installedVersion} installed (${v.installMode}); npm latest is ${v.latest}`,
-      '/cohorte-update-pipeline   (or  npx cohorte update)');
+      '/cohorte-update-pipeline   (or  cohorte update)');
   }
   const tail = v.latest ? `, npm latest ${v.latest}` : ', npm unreachable';
   return mk('core', 'Core & pointer', 'ok', `core ${v.installedVersion} (${v.installMode})${tail}`);
@@ -264,7 +264,7 @@ function checkHooks(projectRoot, globalDir, installMode, all) {
         'nothing to fix; run /cohorte-doctor inside that runtime for the full picture');
     }
     return mk('hooks', 'Gate hook', 'warn', 'no runtime installed to register the gate hook against',
-      'npx cohorte install   (or --global)');
+      'cohorte install   (or --global)');
   }
 
   const problems = [];
@@ -306,7 +306,7 @@ function checkHooks(projectRoot, globalDir, installMode, all) {
     // alone reads as if the gate were off everywhere, when four of five may be fine.
     const tail = okLines.length ? ` (ok: ${okLines.join(', ')})` : '';
     return mk('hooks', 'Gate hook', 'warn', problems.join(' · ') + tail,
-      'npx cohorte@latest update   (re-registers the gate hook for every installed runtime)');
+      'npm i -g cohorte@latest && cohorte update   (re-registers the gate hook for every installed runtime)');
   }
   const tail = advisory.length ? ` · ${advisory.map(l => l.label).join(', ')}: advisory --check only` : '';
   return mk('hooks', 'Gate hook', 'ok', `registered once for ${okLines.join(', ')}${tail}`);
@@ -381,16 +381,16 @@ function checkWorkflows(projectRoot, globalDir, installMode, all) {
   if (missing.length === scripts.length) {
     return mk('workflows', 'Workflows', 'warn',
       'no workflow scripts installed — conversational commands only (the default path)',
-      'npx cohorte update   (ships core/workflows/)');
+      'cohorte update   (ships core/workflows/)');
   }
   if (missing.length) {
     return mk('workflows', 'Workflows', 'warn', `missing script(s): ${missing.join(', ')}`,
-      'npx cohorte update   (half-copied core)');
+      'cohorte update   (half-copied core)');
   }
   if (!exists(path.join(agentsDir, 'profile-reader.md'))) {
     return mk('workflows', 'Workflows', 'warn',
       'scripts present but the profile-reader agent (their phase 0) is missing',
-      'npx cohorte update   (re-copies the fixed agents)');
+      'cohorte update   (re-copies the fixed agents)');
   }
   return mk('workflows', 'Workflows', 'ok',
     'scripts + profile-reader installed — opt-in per run; needs Claude Code ≥ 2.1.154 with ' +

package/dashboard/server/versions.js

@@ -38,9 +38,9 @@ const CACHE_MS = 5 * 60 * 1000;
 // this once per tracked project, so the dashboard's 15s poll never finished.
 const FAIL_CACHE_MS = 60 * 1000;
 
-async function fetchRegistry() {
+async function fetchRegistry(timeoutMs = 5000) {
   const ctrl = new AbortController();
-  const t = setTimeout(() => ctrl.abort(), 5000);
+  const t = setTimeout(() => ctrl.abort(), timeoutMs);
   try {
     const res = await fetch('https://registry.npmjs.org/cohorte/latest', {
       signal: ctrl.signal,
@@ -75,7 +75,12 @@ function npmView() {
 }
 
 let _inflight = null;
-async function latestNpm() {
+// `opts` bounds what a CALLER is willing to pay for the answer. The CLI's staleness
+// notice runs at the tail of an install, where the default 5s fetch + 8s `npm view`
+// fallback would make an OFFLINE install appear to hang for 13 seconds after it had
+// already succeeded — so it asks for a short fetch and no fallback. The cache is
+// shared across callers either way: a cheap lookup still serves an expensive one.
+async function latestNpm({ timeoutMs = 5000, fallback = true } = {}) {
   const age = Date.now() - _cache.at;
   if (_cache.at && age < (_cache.value ? CACHE_MS : FAIL_CACHE_MS)) return _cache.value;
   // /api/fleet resolves N projects concurrently — without this, N lookups race and
@@ -83,7 +88,7 @@ async function latestNpm() {
   if (_inflight) return _inflight;
   _inflight = (async () => {
     try {
-      const v = (await fetchRegistry()) || npmView();
+      const v = (await fetchRegistry(timeoutMs)) || (fallback ? npmView() : null);
       _cache = { value: v || null, at: Date.now() };
       return v || null;
     } finally {
@@ -141,4 +146,4 @@ async function versions({ projectRoot, globalDir, cliVersion }) {
   };
 }
 
-module.exports = { versions };
+module.exports = { versions, latestNpm, cmpSemver };

package/install.ps1

@@ -122,7 +122,7 @@ cohorte needs Node >= 18 to install.
   The pipeline's commands are rendered per coding agent (Claude Code, Codex, Cursor,
   Gemini CLI, OpenCode) at install time; there is no PowerShell equivalent of that
   step, and a raw copy would install prompts this runtime cannot follow.
-  Install Node, then:  npx cohorte install$(if ($Global) { ' --global' })
+  Install Node, then:  npm i -g cohorte; cohorte install$(if ($Global) { ' --global' })
 "@
     exit 1
 
@@ -257,7 +257,7 @@ cohorte needs Node >= 18 to install.
     # pipeline capability config is USER-level (vault, Notion DB, kanban boards) — it lives in
     # the user's .claude regardless of install scope. Seed only if neither the consolidated nor
     # the legacy copy exists. Non-interactive here: seeds disabled defaults; /cohorte-init-pipeline +
-    # /cohorte-update-pipeline wire it (npx's installer offers a quick interview instead).
+    # /cohorte-update-pipeline wire it (the npm CLI's installer offers a quick interview instead).
     function Initialize-Config {
         $userClaude = if ($env:CLAUDE_CONFIG_DIR) { $env:CLAUDE_CONFIG_DIR } else { Join-Path $HOME '.claude' }
         $cfg = Join-Path $userClaude 'cohorte.config.yaml'

package/install.sh

@@ -42,8 +42,9 @@ install.sh — install the cohorte pipeline core.
   sh install.sh --update --global
 
 Honours $CLAUDE_CONFIG_DIR for the global destination and $PIPELINE_REPO for the
-source when piped through curl. The npm CLI (`npx cohorte install`) does the same
-thing and is the documented route; this script exists for Node-less environments.
+source when piped through curl. The npm CLI (`npm i -g cohorte` then `cohorte install`)
+does the same thing and is the documented route; this script exists for Node-less
+environments.
 USAGE
       exit 0 ;;
     --)       shift; break ;;
@@ -89,7 +90,7 @@ echo "error: cohorte needs Node ≥ 18 to install." >&2
 echo "  The pipeline's commands are rendered per coding agent (Claude Code, Codex, Cursor," >&2
 echo "  Gemini CLI, OpenCode) at install time; there is no shell equivalent of that step," >&2
 echo "  and a raw copy would install prompts this runtime cannot follow." >&2
-echo "  Install Node, then:  npx cohorte install${scope:+ }$([ "$scope" = global ] && echo --global)" >&2
+echo "  Install Node, then:  npm i -g cohorte && cohorte install$([ "$scope" = global ] && echo ' --global')" >&2
 exit 1
 
 # --- resolve the destination .claude dir ------------------------------------
@@ -218,7 +219,7 @@ scrub_research_questionnaire() {
 # pipeline capability config is USER-level (vault, Notion DB, kanban boards) — it lives in
 # ~/.claude regardless of install scope. Seed it only if neither the consolidated nor the
 # legacy copy exists. This piped installer is non-interactive: it seeds disabled defaults;
-# /cohorte-init-pipeline + /cohorte-update-pipeline wire it (npx's installer offers a quick interview instead).
+# /cohorte-init-pipeline + /cohorte-update-pipeline wire it (the npm CLI's installer offers a quick interview instead).
 seed_config() {
   base="${CLAUDE_CONFIG_DIR:-$HOME/.claude}"
   cfg="$base/cohorte.config.yaml"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cohorte",
-  "version": "2.4.0",
+  "version": "2.6.0",
   "description": "Portable, stack-agnostic multi-agent development pipeline for Claude Code, Codex CLI, Cursor, Gemini CLI and OpenCode — install the core, run /cohorte-init-pipeline, and it adapts to your project's stack.",
   "bin": {
     "cohorte": "bin/cli.js"

package/scripts/metrics/collect.mjs

@@ -481,6 +481,22 @@ function main(argv) {
     agents: rows.reduce((n, r) => n + r.agents.total, 0),
   };
 
+  // The headline figures as a Francois extension `stat-row` payload — four tiles, no
+  // table. Deliberately ahead of the --json branch: --panel is a shape, not a filter,
+  // and passing both should never print two documents.
+  // See github.com/TheBidouilleAgency/francois-plugin-cohorte.
+  if (flag('panel')) {
+    const window = opt('days') ? `last ${opt('days')} days` : since ? 'since ' + new Date(since).toISOString().slice(0, 10) : 'all time';
+    const top = rows[0];
+    process.stdout.write(JSON.stringify({ tiles: [
+      { label: 'Cost', value: fmtUsd(totals.cost), sublabel: window },
+      { label: 'Runs', value: String(totals.runs), sublabel: `${totals.sessions} sessions` },
+      { label: 'Subagents', value: String(totals.agents) },
+      ...(top ? [{ label: 'Priciest', value: top.command, sublabel: fmtUsd(top.cost.total) }] : []),
+    ] }) + '\n');
+    return 0;
+  }
+
   if (flag('json')) {
     const out = { generatedAt: new Date().toISOString(), projectRoot: root,
                   checkouts: [...checkouts], pricesUpdated: PRICES.updated, totals, commands: rows };

package/scripts/validate-core.mjs

@@ -177,7 +177,7 @@ for (const c of KANBAN_STAGES) {
 // Every scripts/*.sh must be copied by BOTH shell installers. Callers chain these
 // with `|| true`, so one an installer forgets is a silent no-op forever — no kanban
 // card moves, no error. CI is the only place this is loud.
-// The third installer, bin/cli.js (what `npx cohorte` runs), copies by rule rather
+// The third installer, bin/cli.js (what the `cohorte` CLI runs), copies by rule rather
 // than by name, so grepping for filenames can't see it — ci.yml dry-runs it into a
 // scratch HOME and asserts the same postconditions instead. Both are needed: this
 // check catches a forgotten name, that one catches a drifted rule.