cohorte 2.5.0 → 2.6.0

package/CHANGELOG.md

@@ -7,6 +7,35 @@ 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.**

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,
@@ -239,11 +250,14 @@ are reimplemented in JS, so the dashboard needs no Claude session to compute sta
 The two read-only halves of the pipeline, in the shell:
 
 ```sh
-npx cohorte specs              # the board: id · status · branch · title, from specs/*.md
-npx cohorte doctor             # the /cohorte-doctor checks — exits 1 when any check is bad
-npx cohorte metrics --days=30  # cost + runtime per command, from Claude Code's transcripts
+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
@@ -256,9 +270,13 @@ Francois-aware surface in the package, and it exists for
 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                              # a Francois extension may only spawn a bare
-francois ext install TheBidouilleAgency/cohorte   # binary on PATH — never npx, never a shell
+npm i -g cohorte
+francois ext install TheBidouilleAgency/cohorte
 ```
 
 ## Releasing (maintainers)
@@ -273,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
 
@@ -407,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';
 
@@ -291,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`
@@ -386,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');
@@ -615,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(
@@ -657,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();
@@ -675,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();
@@ -693,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() {
@@ -738,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.
@@ -758,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')}
@@ -783,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/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.5.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/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.