cohorte 1.0.0

package/README.md

@@ -0,0 +1,269 @@
+<div align="center">
+
+<img src="https://raw.githubusercontent.com/TheBidouilleAgency/cohorte/main/assets/cohorte-banner.png" alt="Cohorte — portable multi-agent pipeline for Claude Code" width="720">
+
+[![npm version](https://img.shields.io/npm/v/cohorte?logo=npm&color=cb3837)](https://www.npmjs.com/package/cohorte)
+[![npm downloads](https://img.shields.io/npm/dm/cohorte?logo=npm)](https://www.npmjs.com/package/cohorte)
+[![Publish to npm](https://github.com/TheBidouilleAgency/cohorte/actions/workflows/publish.yml/badge.svg)](https://github.com/TheBidouilleAgency/cohorte/actions/workflows/publish.yml)
+[![node >=18](https://img.shields.io/node/v/cohorte?logo=node.js&logoColor=white)](https://nodejs.org)
+[![license: AGPL-3.0](https://img.shields.io/badge/license-AGPL--3.0-blue)](LICENSE)
+
+</div>
+
+A **portable, stack-agnostic multi-agent pipeline** for Claude Code. Install it once globally,
+then one command per project (`/init-pipeline`) adapts it to that project's stack.
+
+- **The dev pipeline** — a human **lead** drives feature work through gated commands, dispatching
+  **stateless agents** that only communicate through a frozen contract:
+
+  ```
+  /brainstorm → /spec → (design) → /build <id> → /smoke → /review → (/fix) → /ship
+  ```
+
+## How it works — three layers
+
+| Layer | What it holds | Lives in | Scope |
+| --- | --- | --- | --- |
+| **Generic core** | the workflow doctrine: commands, fixed agents, templates, hooks — zero project facts | `~/.claude` (global) — or vendored in a repo's `.claude/` (bundled) | identical everywhere, installed once |
+| **Project profile** | stack, surfaces, commands, conventions, gates | `PIPELINE.md` + rendered surface agents + `gate-config.json`, **committed in each repo** | generated per project by `/init-pipeline` |
+| **User config** | kanban board links + shared Obsidian vault path | `~/.claude/cohorte.config.yaml` | personal, project-independent |
+
+The core never hardcodes stack facts. Two mechanisms keep it generic:
+
+1. **Runtime indirection** — commands/agents read project facts from `PIPELINE.md` (dev pipeline) or
+   `~/.claude/cohorte.config.yaml` (kanban board links + shared vault) at run time — an agent's
+   _first action_ is to read its config.
+2. **Render-at-init** — things that must be in agent frontmatter (name, `tools:`, surface ownership)
+   are rendered per **surface** by `/init-pipeline` from `implementer.template.md`.
+
+## Prerequisites
+
+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.
+- **[`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
+  the pipeline still runs — agents just fall back to Grep/Read. Having it installed **before**
+  `/init-pipeline` lets init wire it in one pass (otherwise `/update-pipeline` wires it later).
+- **On a new machine cloning a repo that's already pipeline-ised:** the Serena registration is committed
+  in the repo's `.mcp.json` (project scope, portable) — you don't re-wire. Just install the Serena CLI,
+  restart the session, and run `/doctor` to confirm it connects.
+
+## 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.
+
+**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
+```
+
+The per-project part is NOT the core — it's the **profile** `/init-pipeline` generates and you
+commit: `PIPELINE.md`, the rendered surface agents, `gate-config.json`, `settings.json`, `specs/`.
+**That's what makes team work possible in global mode**: everything project-specific travels with the
+repo; each teammate just runs the same global one-liner once, guided by the committed
+`.claude/pipeline.json` pointer (core version + install command) that `/init-pipeline` writes.
+
+<details>
+<summary><strong>Alternative: per-project (bundled)</strong> — vendor the core into the repo itself.</summary>
+
+```sh
+# inside your project (or pass its path as an argument)
+npx cohorte install
+```
+
+Copies the core into `<project>/.claude`, committed with the repo. Choose this when you want
+**zero-setup onboarding** (teammates get the core with `git clone`, no install step at all) and a
+core version **pinned per repo** (no drift between projects or teammates). Cost: the core is
+duplicated in every repo and each repo updates separately.
+
+</details>
+
+<details>
+<summary><strong>No Node/npm?</strong> The original script installers still work.</summary>
+
+```sh
+# global (recommended)                    # per-project (bundled)
+sh install.sh --global                    sh install.sh
+# or piped:
+curl -fsSL https://raw.githubusercontent.com/TheBidouilleAgency/cohorte/main/install.sh | sh -s -- --global
+```
+
+```powershell
+# Windows (PowerShell 5.1+)
+.\install.ps1 -Global         # or without -Global for per-project
+# or:  & ([scriptblock]::Create((irm https://raw.githubusercontent.com/TheBidouilleAgency/cohorte/main/install.ps1))) -Global
+```
+
+Script installs from a git checkout stamp the version as `<semver> (<sha>)`; the npm CLI stamps the
+published semver. Both land in `.claude/pipeline/VERSION` and the `pipeline.json` pointer.
+
+</details>
+
+> **After installing (or updating): restart Claude Code / start a new session.** Slash commands and
+> agents are scanned at session start — in an already-open session the new `/init-pipeline`,
+> `/build`, etc. won't appear until you reload. This is the #1 "the install didn't work" trap.
+
+Then, in Claude Code (from any repo, once the core is installed either way):
+
+```
+/init-pipeline
+```
+
+It **detects** your stack (package manager, workspaces, frameworks, test runners, linters, git remote,
+design system), **interviews** you for the gaps, and **generates**:
+
+- `PIPELINE.md` — the project profile (a machine-readable `pipeline-profile` YAML block + prose conventions)
+- one implementer agent per **surface** (e.g. `backend.md`, `frontend.md`) with strict tree ownership
+  and a per-surface `model:` tier (Haiku for mechanical surfaces, bigger models where design decisions live)
+- `.claude/gate-config.json` + `.claude/settings.json` — the destructive-command gate, plus an
+  `allow` list of the project's read-only commands so agents don't stall on permission prompts
+- a **code-retrieval provider** wired as a committed project-scope MCP server —
+  [Serena](https://github.com/oraios/serena) by default (live LSP symbol navigation: agents query
+  symbols instead of grep-and-reading whole files; `graphify` or `none` also available via the
+  profile's `retrieval.provider`)
+- `scripts/new-feature.sh` + `remove-feature.sh` — parallel worktree isolation (if you enable it)
+- `specs/_template.md`
+
+Sanity-check `PIPELINE.md`, commit it, and run `/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
+```
+
+(Script equivalents: `sh install.sh --update [--global]` / `.\install.ps1 -Update [-Global]`.)
+
+The installer refreshes the generic core (commands, hook, templates) **without** touching your
+`PIPELINE.md`, rendered agents, `gate-config.json`, `settings.json`, or your filled
+`~/.claude/cohorte.config.yaml`.
+
+From inside Claude Code, prefer **`/update-pipeline`**: it runs the right update invocation for your
+install scope, reports `old → new` — and then **reconciles the repo's generated files to the new
+core**: new profile fields are added at their defaults (you're only asked for genuinely new
+decisions), surface agents are re-rendered, settings are patched additively, new capabilities get
+wired. **`/init-pipeline` is one-time per project** — after init, `/update-pipeline` is the only
+maintenance command you ever run (`/build` auto-grows surfaces as specs need them).
+
+## Dashboard — a local web cockpit
+
+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
+```
+
+**Bound to `127.0.0.1` by default** — the dashboard's actions execute code (install/update/reset,
+and `/init-pipeline`·`/update-pipeline` via headless Claude), so it must stay on loopback. Each user
+runs their own agent and drives only their own machine. `--host=0.0.0.0` exposes it to the network
+(it prints a security warning) — only on a trusted network, since anyone who reaches the port can run
+those actions.
+
+- **Fleet overview** — the global core version vs npm latest, plus every tracked project's freshness
+  and health at a glance. Add a project by absolute path or with the **folder picker** (Browse…); the
+  set is remembered in `~/.claude/cohorte-dashboard.json`.
+- **Per-project drill-down** — Freshness (installed core vs npm), `/doctor` rendered as a live
+  ✅/⚠️/❌ checklist (each failure with its fix), the **Surfaces ↔ agents** map from `PIPELINE.md`,
+  and one board: a **Kanban** if the project has a linked Obsidian board (columns + cards from the
+  vault, with clickable PR links + live open/merged/closed status and a ship-date-sorted Shipped
+  column, via `gh`), otherwise a **Specs board** from `specs/*.md` (by `draft · frozen · in-review ·
+  shipped`). The Kanban supersedes the Specs board when both would apply.
+- **Actions** (stream their output live) — **Update / Install core** (the shared global core, or a
+  repo's bundled core); **Init-pipeline / Update-pipeline**, which run those Claude Code commands
+  **headless** (`claude -p`, autonomous — Init skips the interactive interview, so review the result);
+  and **Reset pipeline**, which backs up then wipes a project's pipeline footprint and reinstalls a
+  fresh core. Buttons render only when they apply (e.g. Init only when there's no profile).
+
+Runtime is **dependency-free** — node's built-in `http` server serves a prebuilt React app (the app
+source lives in `dashboard/app/`, built to `dashboard/dist/` at publish time). The `/doctor` checks
+are reimplemented in JS, so the dashboard needs no Claude session to compute state. See
+[`dashboard/README.md`](dashboard/README.md) for the architecture.
+
+## Releasing (maintainers)
+
+Versions are tracked with npm semver — the published package is the release artifact.
+Publishing is fully automated: [`publish.yml`](.github/workflows/publish.yml) runs on every push
+to `main`; when `package.json`'s version isn't on the registry yet it publishes to npm (trusted
+publishing / provenance), pushes the `vX.Y.Z` tag, and creates the GitHub release. Pushes without
+a version bump just run the sanity checks.
+
+**Releasing = editing one line.** Bump `"version"` in `package.json` (by hand, or
+`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
+it in `.claude/pipeline/VERSION` and bundled repos in their committed `pipeline.json` pointer.
+
+## The commands
+
+| Command              | Role                                                                                  |
+| -------------------- | ------------------------------------------------------------------------------------- |
+| `/init-pipeline`     | Detect stack → interview → generate the profile + agents. Run once per project.       |
+| `/brainstorm`        | Interactive persona panel that pressure-tests a feature idea.                         |
+| `/spec`              | Freeze the feature spec + contract into `specs/<id>.md` (UI features also get a standalone design brief at `specs/design/<id>.md`). Also applies review returns. |
+| `/build <id>`        | Lead authors the contract, then dispatches one implementer per surface in parallel.   |
+| `/smoke <id>`        | Run the feature for real: infra up, contract endpoints, UI flows, design conformance. |
+| `/review <id>`       | Read-only review agents (one per touched surface, parallel) audit the diff vs the spec. |
+| `/fix <id>`          | Apply a review/smoke report: remediation into the spec, re-dispatch only the surfaces with findings. |
+| `/ship <id>`         | Release agent commits, pushes, opens the PR; watches CI; proposes worktree teardown.  |
+| `/audit [path]`      | Prioritized refactor backlog for existing code.                                       |
+| `/refactor <domain>` | Apply the backlog for one surface, TDD-first.                                         |
+| `/align-ds`          | Align the code UI kit to the design system (no-op if none configured).                |
+| `/update-pipeline`   | Refresh the installed core (global or bundled) to the latest published version.       |
+| `/doctor`            | Diagnose the installation (core, agents↔surfaces, hooks, gate, retrieval, worktrees). |
+
+### Run the loop cheaply — `/clear` between stages
+
+Every command reloads all the state it needs **from disk** — the frozen spec, the contract, the diff, the
+Remediation checkboxes, the freshness stamp, and the last `/review`·`/smoke` report (staged to a gitignored
+`specs/reports/<id>.md`). Nothing essential lives in the conversation. So the loop is **`/clear`-safe at
+every boundary**:
+
+```
+/spec → /clear → /build → /clear → /smoke → /clear → /review → /clear → /fix → /clear → /review → /ship
+```
+
+`/clear`-ing between stages sheds the accumulated main-thread context, which is the single biggest token
+lever: long sessions (>150k) are expensive even when cached. Each command tells you when its handoff is
+safe to clear. If you'd rather stay in one session, `/compact` mid-task does the lighter version. (Claude
+can't fire `/clear` itself — it's a client-side command; the pipeline just makes it always safe to type.)
+
+## License
+
+[AGPL-3.0](LICENSE). Free to use, including commercially — but if you modify it and distribute it
+or offer it as a network service, you must publish your modifications under the same license.
+
+## Profile reference
+
+See `profile/SCHEMA.md` for every field in `PIPELINE.md` and how the pipeline uses it.
+
+## Layout of this repo
+
+```
+package.json            # npm package (cohorte) — semver source of truth
+bin/cli.js              # the npm CLI: install / update / dashboard / version (cross-platform, no deps)
+install.sh              # script installer (fresh + --update) for no-Node environments
+install.ps1             # same installer for Windows PowerShell (fresh + -Update)
+core/                   # copied verbatim into ~/.claude (global) or <project>/.claude (bundled)
+  agents/               # implementer.template.md (rendered per surface) + review.md + release.md
+  commands/             # init-pipeline + the workflow commands + /update-pipeline
+  hooks/                # gate.py (destructive-command gate; branch-aware — git/docker free off the default branch)
+  templates/            # handoff / brainstorm-return / design-brief / review-feedback / pr-body / spec
+profile/
+  PIPELINE.template.md  # the profile skeleton /init-pipeline fills
+  SCHEMA.md             # field reference
+  cohorte.config.template.yaml   # seeds ~/.claude/cohorte.config.yaml (kanban)
+scripts/                # new-feature / remove-feature worktree-isolation templates
+dashboard/              # local web cockpit (npx … 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

@@ -0,0 +1,339 @@
+#!/usr/bin/env node
+// 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
+
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const pkgRoot = path.resolve(__dirname, '..');
+const pkg = JSON.parse(fs.readFileSync(path.join(pkgRoot, 'package.json'), 'utf8'));
+const VERSION = pkg.version;
+
+const REPO_URL = 'https://github.com/TheBidouilleAgency/cohorte';
+
+function usage(code) {
+  console.log(`cohorte v${VERSION}
+
+Usage:
+  cohorte install   [target] [--global]
+  cohorte update    [target] [--global]
+  cohorte dashboard [target] [--port=N] [--host=ADDR] [--open]
+  cohorte version
+
+Commands:
+  install   Fresh install. Default: bundle the core into <target>/.claude
+            (committed with the repo). --global: one shared core in ~/.claude,
+            available to every project on this machine.
+  update    Refresh the stack-agnostic core only. PIPELINE.md, rendered surface
+            agents, gate-config.json, settings.json and your filled
+            ~/.claude/cohorte.config.yaml are never touched.
+  dashboard Serve a local web cockpit for the pipeline (freshness, /doctor
+            health, specs board, install/update actions). Binds 127.0.0.1:4317
+            by default (loopback only — its actions execute code). --host=ADDR
+            to expose (e.g. --host=0.0.0.0, prints a security warning). --open
+            to launch the browser.
+  version   Print the installed CLI version.`);
+  process.exit(code);
+}
+
+// --- arg parsing -------------------------------------------------------------
+const args = process.argv.slice(2);
+let mode = null;
+let scope = 'project';
+let target = process.cwd();
+let port = parseInt(process.env.COHORTE_DASHBOARD_PORT, 10) || 4317;
+// Bind to loopback by default — the dashboard's action endpoints execute code (install/update/
+// reset/claude), so it must NOT be reachable from the network unless the user explicitly opts in.
+let host = process.env.COHORTE_DASHBOARD_HOST || '127.0.0.1';
+let openBrowser = false;
+
+for (const a of args) {
+  if (a === 'install' || a === 'update' || a === 'dashboard') mode = a;
+  else if (a === 'version' || a === '--version' || a === '-v') { console.log(VERSION); process.exit(0); }
+  else if (a === '--global' || a === '-g') scope = 'global';
+  else if (a.startsWith('--port=')) { port = parseInt(a.slice(7), 10); }
+  else if (a.startsWith('--host=')) { host = a.slice(7); }
+  else if (a === '--open') { openBrowser = true; }
+  else if (a === 'help' || a === '--help' || a === '-h') usage(0);
+  else if (a.startsWith('-')) { console.error(`error: unknown flag: ${a}`); usage(2); }
+  else target = path.resolve(a);
+}
+if (!mode) usage(args.length ? 2 : 0);
+
+// --- dashboard: local web cockpit -------------------------------------------
+// Short-circuits before the install/update machinery (CommonJS wraps the module,
+// so a top-level return is valid here). Runtime is dependency-free node `http`.
+if (mode === 'dashboard') {
+  const globalDir = process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), '.claude');
+  require('../dashboard/server')({ projectRoot: target, globalDir, port, host, openBrowser, pkgRoot, version: VERSION });
+  return;
+}
+
+// --- paths -------------------------------------------------------------------
+const globalDir = process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), '.claude');
+const dest = scope === 'global' ? globalDir : path.join(target, '.claude');
+const src = pkgRoot;
+
+if (!fs.existsSync(path.join(src, 'core'))) {
+  console.error(`error: pipeline source not found (no core/ in ${src})`);
+  process.exit(1);
+}
+fs.mkdirSync(dest, { recursive: true });
+
+// --- helpers (mirror install.sh) --------------------------------------------
+function copyCore() {
+  for (const d of ['commands', 'hooks', 'templates']) {
+    fs.cpSync(path.join(src, 'core', d), path.join(dest, d), { recursive: true, force: true });
+  }
+  // 0.1.19 renamed questionnaire-domain-brief.md → research-brief.md; drop the stale copy.
+  fs.rmSync(path.join(dest, 'templates', 'questionnaire-domain-brief.md'), { force: true });
+  const pipelineDir = path.join(dest, 'pipeline');
+  fs.mkdirSync(path.join(pipelineDir, 'scripts'), { recursive: true });
+  for (const f of ['PIPELINE.template.md', 'SCHEMA.md', 'cohorte.config.template.yaml']) {
+    fs.copyFileSync(path.join(src, 'profile', f), path.join(pipelineDir, f));
+  }
+  for (const f of fs.readdirSync(path.join(src, 'scripts'))) {
+    if (f.endsWith('.template')) {
+      fs.copyFileSync(path.join(src, 'scripts', f), path.join(pipelineDir, 'scripts', f));
+    }
+  }
+  fs.copyFileSync(path.join(src, 'core', 'agents', 'implementer.template.md'),
+                  path.join(pipelineDir, 'implementer.template.md'));
+  fs.writeFileSync(path.join(pipelineDir, 'VERSION'), VERSION + '\n');
+  if (process.platform !== 'win32') {
+    try { fs.chmodSync(path.join(dest, 'hooks', 'gate.py'), 0o755); } catch { /* optional */ }
+  }
+  scrubTddGate();
+}
+
+// The TDD gate was removed in 0.1.6. Older installs have hooks/tdd_gate.py on disk and
+// registered in settings.json — copy-over never deletes, and a registered hook whose file
+// is gone errors on every Write/Edit, so scrub both.
+function scrubTddGate() {
+  fs.rmSync(path.join(dest, 'hooks', 'tdd_gate.py'), { force: true });
+  const settingsPath = path.join(dest, 'settings.json');
+  let data;
+  try { data = JSON.parse(fs.readFileSync(settingsPath, 'utf8')); } catch { return; }
+  const pre = data && data.hooks && Array.isArray(data.hooks.PreToolUse) ? data.hooks.PreToolUse : null;
+  if (!pre) return;
+  const kept = pre.filter(entry => !(entry.hooks || []).some(
+    h => typeof h.command === 'string' && h.command.trim().endsWith('tdd_gate.py')));
+  if (kept.length !== pre.length) {
+    data.hooks.PreToolUse = kept;
+    fs.writeFileSync(settingsPath, JSON.stringify(data, null, 2) + '\n');
+    console.log('  · removed the retired tdd_gate.py hook (file + settings registration)');
+  }
+}
+
+// the fixed (non-rendered) agents: the dev review/release pipeline agents
+function copyFixedAgents() {
+  fs.mkdirSync(path.join(dest, 'agents'), { recursive: true });
+  for (const f of ['review.md', 'release.md']) {
+    fs.copyFileSync(path.join(src, 'core', 'agents', f), path.join(dest, 'agents', f));
+  }
+  // 0.1.19 split the bi-mode questionnaire-researcher into research-agent + questionnaire-architect;
+  // copy-over never deletes, so scrub the retired agent lest a dead subagent_type linger.
+  fs.rmSync(path.join(dest, 'agents', 'questionnaire-researcher.md'), { force: true });
+  scrubResearchQuestionnaire();
+}
+
+// The research + questionnaire capability was removed. Older installs have its agents, commands,
+// templates and template-step dirs on disk; copy-over never deletes, so scrub every orphan.
+function scrubResearchQuestionnaire() {
+  for (const f of ['research-agent.md', 'questionnaire-architect.md',
+                   'questionnaire-writer.md', 'questionnaire-validator.md']) {
+    fs.rmSync(path.join(dest, 'agents', f), { force: true });
+  }
+  for (const f of ['research.md', 'questionnaire.md']) {
+    fs.rmSync(path.join(dest, 'commands', f), { force: true });
+  }
+  for (const f of ['research-brief.md', 'questionnaire-blueprint.md',
+                   'questionnaire-declaration.md', 'questionnaire-verdict.md']) {
+    fs.rmSync(path.join(dest, 'templates', f), { force: true });
+  }
+  for (const d of ['research', 'questionnaire']) {
+    fs.rmSync(path.join(dest, 'templates', 'steps', d), { recursive: true, force: true });
+  }
+}
+
+// --- interactive config helpers ---------------------------------------------
+// Ask one question on the TTY. Resolves to the trimmed answer (or '' on EOF).
+function ask(question) {
+  const rl = require('readline').createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise(res => rl.question(question, a => { rl.close(); res((a || '').trim()); }));
+}
+function yes(a) { return /^(y|yes|o|oui)$/i.test(a); }
+
+// Set the value on the line carrying `# cfg:<cfgKey>`, preserving the yaml key + the comment.
+// The config template anchors every interactive field this way, so we never parse YAML.
+// Line-scoped on purpose (a multiline regex would let \s span newlines and mangle keys).
+function setCfg(text, cfgKey, value) {
+  const marker = `# cfg:${cfgKey}`;
+  return text.split('\n').map(line => {
+    const idx = line.indexOf(marker);
+    if (idx === -1) return line;
+    const m = line.slice(0, idx).match(/^(\s*[\w.]+:\s*)/);   // "  key: "
+    return m ? `${m[1]}${value}  ${line.slice(idx)}` : line;
+  }).join('\n');
+}
+
+// Fill the seeded config from a short TTY interview (shared Obsidian vault for the kanban mirror).
+// Kanban is per-project, so it is wired later by /init-pipeline — not asked here.
+async function promptConfig(text) {
+  console.log('\n  Quick setup (Enter to skip — you can also wire this later via');
+  console.log('  /init-pipeline or /update-pipeline):');
+  const vault = await ask('    · absolute path to your shared Obsidian vault (for the kanban mirror): ');
+  if (vault) text = setCfg(text, 'vault_path', `"${vault}"`);
+  return text;
+}
+
+// The pipeline capability config is USER-level (vault, Notion DB, kanban boards) — it lives in
+// ~/.claude regardless of install scope. Seed it only if the user has no copy (consolidated OR
+// legacy). On a TTY, offer a quick interview to fill it; otherwise seed disabled defaults.
+async function seedConfig() {
+  const cfg = path.join(globalDir, 'cohorte.config.yaml');
+  // Pre-rename names, newest first — read as a fallback so upgrades don't lose the config.
+  const legacy = ['thebidouille.config.yaml']
+    .map((n) => path.join(globalDir, n)).find(fs.existsSync);
+  if (fs.existsSync(cfg)) { console.log(`  · kept your existing ${cfg}`); return; }
+  if (legacy) {
+    console.log(`  · found legacy ${legacy} — kept as-is (still read as a fallback).`);
+    console.log('    Run /update-pipeline to migrate it into cohorte.config.yaml + wire the kanban.');
+    return;
+  }
+  fs.mkdirSync(path.dirname(cfg), { recursive: true });
+  let text = fs.readFileSync(path.join(src, 'profile', 'cohorte.config.template.yaml'), 'utf8');
+  if (process.stdin.isTTY && process.stdout.isTTY) {
+    text = await promptConfig(text);
+    fs.writeFileSync(cfg, text);
+    console.log(`  · seeded ${cfg} from your answers`);
+  } else {
+    fs.writeFileSync(cfg, text);
+    console.log(`  · seeded ${cfg} (disabled defaults — enable via /init-pipeline or /update-pipeline)`);
+  }
+}
+
+function findPython() {
+  const candidates = process.platform === 'win32' ? ['py', 'python', 'python3'] : ['python3', 'python'];
+  for (const c of candidates) {
+    const r = spawnSync(c, ['--version'], { stdio: 'ignore', shell: false });
+    if (r.status === 0) return c;
+  }
+  return null;
+}
+
+// Register the profile-driven gate hook in the GLOBAL settings.json. Idempotent: the
+// hook reads each repo's own .claude/gate-config.json (and no-ops where absent),
+// so one registration serves every project.
+function registerGlobalHook() {
+  const python = findPython();
+  if (!python) return 'skipped (no python found — register the gate hook manually)';
+  const settingsPath = path.join(dest, 'settings.json');
+  let data = {};
+  try {
+    const parsed = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) data = parsed;
+  } catch { /* absent or invalid → start fresh */ }
+  if (!data.hooks || typeof data.hooks !== 'object') data.hooks = {};
+  if (!Array.isArray(data.hooks.PreToolUse)) data.hooks.PreToolUse = [];
+  const pre = data.hooks.PreToolUse;
+  const hooks = [
+    { file: path.join(dest, 'hooks', 'gate.py'), matcher: 'Bash' },
+  ];
+  for (const { file, matcher } of hooks) {
+    const base = path.basename(file);
+    const already = pre.some(entry => (entry.hooks || []).some(
+      h => typeof h.command === 'string' && h.command.trim().endsWith(base)));
+    if (!already) {
+      const cmd = process.platform === 'win32' ? `${python} "${file}"` : `${python} ${file}`;
+      pre.push({ matcher, hooks: [{ type: 'command', command: cmd }] });
+    }
+  }
+  fs.writeFileSync(settingsPath, JSON.stringify(data, null, 2) + '\n');
+  return 'ok';
+}
+
+// Bump only the core_version in a repo's committed .claude/pipeline.json (bundled mode).
+// Leaves every other field intact; no-ops if the pointer is absent or has no core_version.
+function bumpPointerVersion(ptr) {
+  if (!fs.existsSync(ptr)) return;
+  let data;
+  try { data = JSON.parse(fs.readFileSync(ptr, 'utf8')); } catch { return; }
+  if (data && typeof data === 'object' && 'core_version' in data) {
+    data.core_version = VERSION;
+    fs.writeFileSync(ptr, JSON.stringify(data, null, 2) + '\n');
+  }
+}
+
+// --- run ---------------------------------------------------------------------
+(async () => {
+if (scope === 'global') {
+  console.log(mode === 'install'
+    ? `→ installing pipeline core GLOBALLY into ${dest}`
+    : `→ updating pipeline core GLOBALLY in ${dest} (keeping global settings.json)`);
+  copyFixedAgents();
+  copyCore();
+  const hookState = mode === 'install' ? registerGlobalHook() : 'unchanged';
+  await seedConfig();
+  console.log(`
+✓ pipeline core installed globally into ${dest}  (version ${VERSION})
+  gate hook: ${hookState}  (reads each repo's .claude/gate-config.json; silent where absent)
+
+The commands (/init-pipeline, /brainstorm, /build …) and the review/release agents are now
+available in EVERY project on this machine — nothing is copied per repo.
+
+Per repo:
+  1. Open the project in Claude Code.
+  2. Run  /init-pipeline  — it generates PIPELINE.md, renders the surface agents, writes
+     .claude/gate-config.json, and drops a committed .claude/pipeline.json pointer so
+     teammates know to install the global core (${REPO_URL}).
+  3. Commit PIPELINE.md + .claude/, then  /brainstorm  to start a feature.
+
+Update later with:  npx cohorte@latest update --global
+
+Global kanban config, user-scoped — optional:
+  · One consolidated file: ${path.join(globalDir, 'cohorte.config.yaml')}
+  · Don't hand-edit it — /init-pipeline (new project) and /update-pipeline (existing) wire it
+    for you: creating + syncing an Obsidian kanban board of the pipeline in your shared vault.`);
+} else if (mode === 'install') {
+  console.log(`→ installing pipeline core into ${dest}`);
+  copyFixedAgents();
+  copyCore();
+  await seedConfig();
+  fs.mkdirSync(path.join(target, 'specs'), { recursive: true });
+  const specTemplate = path.join(target, 'specs', '_template.md');
+  if (!fs.existsSync(specTemplate)) {
+    fs.copyFileSync(path.join(src, 'core', 'templates', 'spec.template.md'), specTemplate);
+  }
+  console.log(`
+✓ pipeline core installed into ${dest}  (version ${VERSION})
+
+Next:
+  1. Open the project in Claude Code.
+  2. Run  /init-pipeline   — it detects your stack, asks the gaps, and generates
+     PIPELINE.md + renders one implementer agent per surface.
+  3. Commit PIPELINE.md, then  /brainstorm  to start a feature.
+
+Update later with:  npx cohorte@latest 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)`);
+  copyCore();
+  try { copyFixedAgents(); } catch { /* best-effort, as in install.sh */ }
+  await seedConfig();
+  bumpPointerVersion(path.join(dest, 'pipeline.json'));
+  console.log(`
+✓ core refreshed to ${VERSION}. Your PIPELINE.md, rendered surface agents, gate-config.json and
+  settings.json were left as-is. Re-run /init-pipeline if your stack changed.`);
+}
+})();