convene-cli 1.12.0 → 1.13.1

package/dist/commands/explain.js

@@ -11,6 +11,7 @@ exports.explain = explain;
  * offline agent still gets the essentials. The endpoint is unauthenticated, so
  * this works even before `convene login`.
  */
+const node_child_process_1 = require("node:child_process");
 const config_1 = require("../config");
 const api_1 = require("../api");
 const brand_1 = require("../brand");
@@ -45,6 +46,20 @@ async function explain(question) {
             return;
         }
         if (res.ok && res.json && res.json.matched === false) {
+            // The agent asked how something works and Convene had no curated answer —
+            // the cleanest in-session friction signal. Capture it fire-and-forget
+            // (detached + unref'd, exactly as `convene fetch` spawns `convene announce`)
+            // so the product learns from confusion automatically instead of relying on a
+            // voluntary `convene suggest`. Gated on creds: no key/member → no spawn.
+            if (q && cfg.apiKey && cfg.member) {
+                try {
+                    const child = (0, node_child_process_1.spawn)(process.execPath, [process.argv[1], 'friction', '--kind', 'unmatched-explain', '--q', q], { detached: true, stdio: 'ignore' });
+                    child.unref();
+                }
+                catch {
+                    /* fail-open: friction capture must never break `explain` */
+                }
+            }
             // Unmatched query — point at the index + bundled essentials (still exit 0).
             process.stdout.write(`No specific match for "${q}". ${brand_1.BRAND.product} basics:\n\n${bundledSummary(cfg.baseUrl)}\n`);
             return;

package/dist/commands/fetch.js

@@ -105,7 +105,10 @@ function catalogBehindNudge(top) {
             return null;
         if (!(0, manifest_1.semverLt)(manifest.catalogVersion, live))
             return null;
-        return `convene: best-practices catalog v${live} available (repo on v${manifest.catalogVersion}) — run \`convene update\``;
+        // Shared phrasing with `convene doctor` — `live` is the SERVER version (the
+        // cache is populated from api.getCatalog), so the "server catalog vX" wording
+        // is accurate here and means the SAME thing in both surfaces.
+        return `convene: ${(0, manifest_1.catalogBehindLine)(live, manifest.catalogVersion)}`;
     }
     catch {
         return null;

package/dist/commands/friction.js

@@ -0,0 +1,104 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.friction = friction;
+/**
+ * `convene friction` — automatic in-session CONFUSION capture. Files ONE
+ * low-severity feature_feedback row (category 'friction') when an agent hits a
+ * product rough edge the platform should learn from — today: an unmatched
+ * `convene explain` query (the agent literally asked how something works and
+ * Convene had no curated answer — the cleanest possible friction signal). It is
+ * spawned fire-and-forget by the surface that detects the friction (exactly as
+ * `convene fetch` spawns `convene announce`), so it NEVER blocks that surface.
+ *
+ * Mirrors `convene announce`'s posture:
+ *  - FAIL-OPEN: any error / missing config / non-bus repo exits 0 silently; a 5s
+ *    watchdog backstops a hang. It can never break the command that spawned it.
+ *  - IDEMPOTENT: a deterministic server idempotency-key
+ *    (`friction:<slug>:<instance>:<sigHash>`) is the authoritative dedupe; a local
+ *    (instance, sigHash) sentinel spares the redundant post when the SAME signal
+ *    recurs in a session.
+ *  - PRIVACY: the captured text is the agent's own words about Convene-the-product
+ *    — the same class of text `convene suggest` already mirrors to maintainers. It
+ *    is CLIPPED and posted only behind a valid key + project membership (the
+ *    authenticated-session gate). It never carries prompt text or work content
+ *    beyond the question the agent typed.
+ */
+const node_crypto_1 = require("node:crypto");
+const git_1 = require("../git");
+const config_1 = require("../config");
+const cache_1 = require("../cache");
+const api_1 = require("../api");
+const exit_1 = require("../exit");
+const SIGNAL_MAX = 240;
+function clip(s, max) {
+    const t = s.trim();
+    return t.length <= max ? t : t.slice(0, max - 1) + '…';
+}
+/** Stable short hash of the normalized signal — keys both the idempotency key and the local sentinel. */
+function signalHash(kind, signal) {
+    const norm = `${kind}\n${signal.toLowerCase().replace(/\s+/g, ' ').trim()}`;
+    return (0, node_crypto_1.createHash)('sha256').update(norm).digest('hex').slice(0, 16);
+}
+/** Human-readable feedback body for a friction kind. */
+function bodyFor(kind, signal) {
+    const q = clip(signal, SIGNAL_MAX);
+    switch (kind) {
+        case 'unmatched-explain':
+            return `Unmatched \`convene explain\` query (no curated answer): "${q}"`;
+        default:
+            return `[${kind}] ${q}`;
+    }
+}
+async function run(opts) {
+    const kind = (opts.kind ?? '').trim();
+    const signal = (opts.q ?? '').trim();
+    if (!kind || !signal)
+        return; // no signal → nothing to capture
+    const top = (0, git_1.gitToplevel)();
+    if (!top)
+        return; // not a git repo → silent no-op
+    const slug = opts.project || (0, config_1.loadProjectConfig)(top)?.slug || null;
+    if (!slug)
+        return; // repo not on the bus → silent no-op
+    const instance = (0, cache_1.ensureSessionInstance)(slug);
+    const sig = signalHash(kind, signal);
+    const body = bodyFor(kind, signal);
+    if (opts.dryRun) {
+        process.stdout.write(body + '\n');
+        return;
+    }
+    // Already captured this exact signal this session — spare the redundant post.
+    if ((0, cache_1.frictionAlreadyPosted)(slug, instance, sig))
+        return;
+    // The authenticated-session gate: only post with a real key + member.
+    const cfg = (0, config_1.resolveConfig)();
+    if (!cfg.apiKey || !cfg.member)
+        return;
+    const session = (0, git_1.sessionId)(cfg.member, top);
+    const api = new api_1.ConveneApi(cfg.baseUrl, cfg.apiKey, session, cfg.tool, instance);
+    const idem = `friction:${slug}:${instance}:${sig}`;
+    const res = await api.post(slug, { type: 'feature_feedback', body, category: 'friction', severity: 'low', tags: [kind] }, idem, 4000);
+    if (res.ok) {
+        // Only mark on success so a transient failure retries on the next occurrence.
+        (0, cache_1.markFrictionPosted)(slug, instance, sig);
+        if (res.json?.message?.short_id) {
+            process.stdout.write(`convene: captured [FRICTION] ${res.json.message.short_id} (${kind})\n`);
+        }
+    }
+}
+async function friction(opts = {}) {
+    // Backstop: force-exit on every path so a keep-alive socket can't linger.
+    const watchdog = setTimeout(() => (0, exit_1.exitClean)(0), 5000);
+    watchdog.unref();
+    const done = () => {
+        clearTimeout(watchdog);
+        (0, exit_1.exitClean)(0);
+    };
+    try {
+        await run(opts);
+    }
+    catch {
+        /* fail-open: a friction capture must never break the surface that spawned it */
+    }
+    done();
+}

package/dist/commands/init.js

@@ -223,72 +223,9 @@ function registerHook(noHook) {
         log(hookSnippet());
     }
 }
-/**
- * The WP13 coordination hooks, in INSTALL ORDER. Order matters for the two Bash
- * PreToolUse entries: `gate-push --stdin` is wired before `guard`, so `guard` lands
- * LAST among Bash PreToolUse hooks (awareness/ux #10) — the deploy gate runs, then
- * the cheap halt/lane backstop. Each entry names the VERB its binary must support;
- * a stale `convene` missing the verb is skipped (so it can't error on every boot).
- *
- * `convene watch` is NOT a Bash hook — it's a long-running detached daemon that
- * `convene session-start` spawns from the SessionStart path (§4.4). Wiring it as a
- * blocking Bash/PreToolUse entry would stall; launching from session-start keeps it
- * off the discretionary tool path.
- */
-const COORD_HOOKS = [
-    {
-        event: 'SessionStart',
-        matcher: 'startup|resume|clear',
-        command: 'convene session-start',
-        verb: 'session-start',
-        note: 'auto catch-up digest + mints the session-instance + launches `convene watch`',
-    },
-    {
-        event: 'PreToolUse',
-        matcher: 'Bash',
-        command: 'convene gate-push --stdin',
-        verb: 'gate-push',
-        note: 'deploy gate before a push (fail-open-loud)',
-    },
-    // guard is appended AFTER gate-push so it is LAST among Bash PreToolUse hooks.
-    {
-        event: 'PreToolUse',
-        matcher: 'Bash',
-        command: 'convene guard',
-        verb: 'guard',
-        note: 'halt + lane backstop for Bash (fail-open-loud)',
-    },
-    {
-        event: 'PreToolUse',
-        matcher: '.*',
-        command: 'convene guard --halt-only',
-        verb: 'guard',
-        note: 'cheap directed-halt backstop on every tool call',
-    },
-    {
-        event: 'PostToolUse',
-        matcher: 'Bash',
-        command: 'convene gate-push --post',
-        verb: 'gate-push',
-        note: 'release the deploy lane after a push (idempotent)',
-    },
-    {
-        event: 'PostToolUse',
-        matcher: 'Edit|Write|MultiEdit',
-        command: 'convene beat --stdin',
-        verb: 'beat',
-        note: 'debounced session activity-beat so a heads-down session still pulses on the bus',
-    },
-    // Stop fires at every turn-end (no tool matcher); `convene wrap` is idempotent +
-    // debounced via the last-broadcast-sha cursor, so it posts at most one wrap per
-    // stretch of new committed work and stays silent on idle turns. Never blocks.
-    {
-        event: 'Stop',
-        command: 'convene wrap',
-        verb: 'wrap',
-        note: 'session-end wrap status when new committed work landed (idempotent, fail-open)',
-    },
-];
+// COORD_HOOKS (the canonical coordination-hook set, in install order) + the
+// missingCoordHooks drift-check now live in ../hook as the SINGLE source of truth,
+// so the writer here and the `convene doctor` drift-check can never disagree.
 /**
  * Wire the WP13 coordination hooks into a settings file (global or committed
  * project), idempotent + merge-safe via ensureHook (deep-clone, never clobber,
@@ -297,7 +234,7 @@ const COORD_HOOKS = [
  */
 function registerCoordinationHooks(settingsPath, label) {
     let unparseable = false;
-    for (const h of COORD_HOOKS) {
+    for (const h of hook_1.COORD_HOOKS) {
         if (!(0, hook_1.binarySupportsVerb)(h.verb)) {
             log(`· ${label}: skipped \`${h.command}\` — installed \`convene\` lacks \`${h.verb}\` (upgrade the CLI to enable).`);
             continue;

package/dist/commands/update.js

@@ -4,6 +4,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.update = update;
+exports.assessBindingCommitSafety = assessBindingCommitSafety;
 exports.runUpdate = runUpdate;
 /**
  * `convene update` — Phase 4: check for + apply best-practices catalog updates.
@@ -147,6 +148,88 @@ function warnStaleCarriers(top, host) {
             `(without --no-mcp) to fix: ${stale.join(', ')}`);
     }
 }
+/**
+ * The managed files a binding re-stamp REWRITES (a curated subset of CONVENE_PATHS) —
+ * the only ones a divergent origin edit can actually CONFLICT on. Deliberately excludes
+ * the append/merge-only members: `.gitignore` (idempotent append-only guard),
+ * `.claude/settings.json` (additive JSON hook-merge), `.githooks/pre-push` (regenerated,
+ * no user content), and `CONVENE_PROTOCOL.md` (write-if-absent — never rewritten). An
+ * unrelated origin edit to one of those auto-merges, so refusing on it is a false alarm.
+ */
+const BINDING_REWRITE_PATHS = [
+    'CLAUDE.md',
+    'AGENTS.md',
+    '.convene/project.json',
+    '.cursor/rules/convene.mdc',
+    '.clinerules/convene.md',
+    '.aider.conf.yml',
+    '.cursor/mcp.json',
+    '.vscode/mcp.json',
+    '.gemini/settings.json',
+    '.codex/config.toml',
+];
+/**
+ * Decide whether committing the convene-managed files on the LOCAL HEAD would collide
+ * with origin. The incident: `convene update --host … --commit` on a checkout whose
+ * origin had ALREADY re-pointed (and committed the same CLAUDE.md/AGENTS.md/.convene
+ * files) produced a commit guaranteed to conflict on coordination-critical files —
+ * manual git-archaeology in front of contributors.
+ *
+ * Fails OPEN on any unverifiable git state (no origin, detached HEAD, fetch failed,
+ * branch absent on origin) — exactly like the deploy compat gate (gate-push.ts), we
+ * never block a commit we cannot PROVE is unsafe. Only a CONFIRMED collision refuses.
+ */
+function assessBindingCommitSafety(top, host) {
+    if (!(0, git_1.originRemote)(top))
+        return { kind: 'ok', reason: 'no origin remote' };
+    const branch = (0, git_1.currentBranch)(top);
+    if (!branch)
+        return { kind: 'ok', reason: 'detached HEAD' };
+    if (!(0, git_1.gitFetch)(branch, 'origin', top))
+        return { kind: 'ok', reason: 'fetch failed (unverifiable)' };
+    const remote = (0, git_1.revParse)(`origin/${branch}`, top);
+    const head = (0, git_1.revParse)('HEAD', top);
+    if (!remote || !head)
+        return { kind: 'ok', reason: 'branch not on origin' };
+    // Origin tip is an ancestor of HEAD → local is up to date or ahead → a commit then
+    // push fast-forwards, no conflict possible.
+    if ((0, git_1.isAncestor)(remote, head, top))
+        return { kind: 'ok', reason: 'up to date / ahead of origin' };
+    // Behind or diverged. Does origin ALREADY carry this exact host binding? (A redundant
+    // re-commit here is the most common foot-gun — surface the friendlier pull message.)
+    const originProj = (0, git_1.gitShow)(`origin/${branch}`, '.convene/project.json', top);
+    if (originProj) {
+        try {
+            const b = JSON.parse(originProj)?.binding;
+            if (b?.host && (0, binding_1.normalizeHost)(b.host) === host)
+                return { kind: 'already-on-origin', branch };
+        }
+        catch {
+            /* unparseable origin project.json → fall through to the managed-file diff */
+        }
+    }
+    // Otherwise refuse ONLY if origin already changed a managed file the re-stamp
+    // REWRITES (BINDING_REWRITE_PATHS) — then a commit on top conflicts on it. A plain
+    // divergence that touched only append/merge-only managed files (or no managed file)
+    // is a routine rebase, not a convene-specific refusal.
+    const files = (0, git_1.changedPaths)('HEAD', `origin/${branch}`, BINDING_REWRITE_PATHS, top);
+    if (files.length)
+        return { kind: 'would-conflict', branch, files };
+    return { kind: 'ok', reason: 'diverged but origin did not touch managed files' };
+}
+/** The refusal/guidance message for a non-ok CommitSafety verdict. */
+function bindingCommitMessage(s, host) {
+    if (s.kind === 'already-on-origin') {
+        return (`origin/${s.branch} already re-points to ${host} — pull (\`git pull --rebase\`), do not re-commit. ` +
+            `Re-stamping with --commit here would create a redundant commit that conflicts on .convene/project.json. (Override: --force.)`);
+    }
+    if (s.kind === 'would-conflict') {
+        return (`refusing to --commit: your branch is behind/diverged from origin/${s.branch}, which already changed ` +
+            `convene-managed files (${s.files.join(', ')}). Committing the re-stamp now will conflict on coordination-critical ` +
+            `files. Run \`git pull --rebase\` first, then re-run. (Override: --force.)`);
+    }
+    return '';
+}
 async function runBindingRefresh(top, opts) {
     const existing = (0, config_1.loadProjectConfig)(top);
     if (!existing?.slug) {
@@ -209,6 +292,13 @@ async function runBindingRefresh(top, opts) {
     }
     const skipAgentRules = opts.noAgentRules === true || opts.agentRules === false;
     const skipMcp = opts.noMcp === true || opts.mcp === false;
+    // Divergence guard: a `--commit` that lands the re-stamped managed files on a local
+    // HEAD behind/diverged from an origin which ALSO changed those files conflicts on
+    // coordination-critical files (the VAcontractorCo incident). Assessed BEFORE any
+    // mutation so a refusal leaves the working tree clean. Only relevant under --commit.
+    const commitSafety = opts.commit
+        ? assessBindingCommitSafety(top, host)
+        : { kind: 'ok', reason: 'no --commit' };
     if (opts.check) {
         log(`Dry run — \`convene update ${opts.host ? `--host ${host}` : '--refresh'}\` would:`);
         log(`  • re-render CLAUDE.md + AGENTS.md coordination blocks at ${host}`);
@@ -221,10 +311,24 @@ async function runBindingRefresh(top, opts) {
             log(`  • update ~/.convene/config.json baseUrl → ${host}`);
         log(`  • write the .convene/project.json binding stamp (schema 3${serverVerified ? ', server-confirmed' : ''})`);
         log(opts.commit ? '  • commit exactly the convene files as one isolated commit' : '  • leave changes in the working tree (no commit without --commit)');
+        if (opts.commit && commitSafety.kind !== 'ok') {
+            log('');
+            log(opts.force
+                ? `  ⚠ origin divergence detected (${commitSafety.kind}); --force is set, so --commit would proceed ANYWAY.`
+                : `  ✗ --commit would be REFUSED — ${bindingCommitMessage(commitSafety, host)}`);
+        }
         log('');
-        log('Nothing written (--check). Re-run without --check to apply.');
+        log(opts.commit
+            ? 'Nothing written — origin was fetched only to assess the --commit divergence guard (no commit, no file changes). Re-run without --check to apply.'
+            : 'Nothing written (--check). Re-run without --check to apply.');
         return;
     }
+    // ENFORCE the divergence guard before mutating anything (clean tree on refusal).
+    if (opts.commit && commitSafety.kind !== 'ok') {
+        if (!opts.force)
+            (0, ctx_1.die)(bindingCommitMessage(commitSafety, host));
+        log(`⚠ --force: committing despite origin divergence (${commitSafety.kind}) — you will need to reconcile with origin afterward.`);
+    }
     log(`${opts.host ? 'Re-pointing' : 'Refreshing'} Convene binding for "${slug}" at ${host}…`);
     (0, init_1.writeCoordinationBlocks)(top, slug, member, host);
     if (!skipAgentRules)
@@ -279,11 +383,18 @@ async function runBindingRefresh(top, opts) {
 async function runUpdate(top, manifest, catalog, source, opts) {
     const rows = classify(manifest, catalog, top);
     const cmp = (0, manifest_1.compareToCatalog)(manifest, catalog);
+    // Newly-available catalog practices this repo has NOT adopted — the delta `update`
+    // is otherwise blind to (it only bumps the already-adopted set). Surfaced in the dry
+    // run + as an apply pointer so the "update available → nothing to apply" dead-end
+    // becomes "the delta is N new practices; run `convene adopt <id>`". update NEVER
+    // auto-adopts — adoption stays a deliberate act (see `convene adopt`).
+    const adoptedIds = new Set(manifest.practices.map((e) => e.id));
+    const available = catalog.practices.filter((p) => !adoptedIds.has(p.id));
     if (!opts.apply) {
-        printDryRun(rows, cmp.repoVersion, catalog.version, source, opts);
+        printDryRun(rows, cmp.repoVersion, catalog.version, source, opts, available);
         return;
     }
-    await applyUpdate(top, manifest, catalog, rows, opts);
+    await applyUpdate(top, manifest, catalog, rows, opts, available);
 }
 /** Build the per-practice rows: status vs. the live catalog + drift flags. */
 function classify(manifest, catalog, top) {
@@ -313,11 +424,20 @@ function classify(manifest, catalog, top) {
         };
     });
 }
-function printDryRun(rows, repoVersion, catalogVersion, source, opts) {
+function printDryRun(rows, repoVersion, catalogVersion, source, opts, available) {
     const behind = repoVersion !== catalogVersion;
-    log(behind
-        ? `Catalog update available: repo on v${repoVersion} → catalog v${catalogVersion}${source === 'bundled' ? ' (bundled — offline)' : ''}`
-        : `Best practices up to date at catalog v${repoVersion}${source === 'bundled' ? ' (bundled — offline)' : ''}`);
+    const hasAdoptedBump = rows.some((r) => hasBump(r));
+    const bundledNote = source === 'bundled' ? ' (bundled — offline)' : '';
+    // The catalog watermark moving does NOT mean an adopted practice has an update: it
+    // also moves when the catalog merely ADDS practices. If nothing adopted has a real
+    // bump, don't imply adopted updates exist — that recreates the dead-end this
+    // surfacing was built to kill. The available-not-adopted block below carries the
+    // actual delta + the `convene adopt` pointer.
+    log(behind && !hasAdoptedBump
+        ? `Adopted practices up to date at catalog v${repoVersion}; catalog is at v${catalogVersion}${bundledNote}`
+        : behind
+            ? `Catalog update available: repo on v${repoVersion} → catalog v${catalogVersion}${bundledNote}`
+            : `Best practices up to date at catalog v${repoVersion}${bundledNote}`);
     log('');
     const idW = Math.max(8, ...rows.map((r) => r.id.length));
     log(`  ${pad('practice', idW)}  ${pad('level', 9)}  ${pad('version', 18)}  change`);
@@ -343,18 +463,54 @@ function printDryRun(rows, repoVersion, catalogVersion, source, opts) {
     const skippedMajor = rows.filter((r) => skipForMajor(r, opts));
     const skippedDrift = rows.filter((r) => skipForDrift(r, opts));
     const skippedPatchGate = rows.filter((r) => skipForPatchGate(r, opts));
-    if (applicable.length === 0 && skippedMajor.length === 0 && skippedDrift.length === 0 && skippedPatchGate.length === 0) {
+    const nothingToApply = applicable.length === 0 && skippedMajor.length === 0 && skippedDrift.length === 0 && skippedPatchGate.length === 0;
+    // The load-bearing fix: when there is nothing to apply to the ADOPTED set, do NOT
+    // dead-end on a bare "Nothing to apply." while newly-available practices go unseen —
+    // fall through to the available block below.
+    if (nothingToApply && available.length === 0) {
         log('Nothing to apply.');
         return;
     }
-    if (applicable.length) {
-        log(`${applicable.length} practice(s) would update on \`convene update --apply\`.`);
+    if (nothingToApply) {
+        log('No updates to apply to your adopted practices.');
     }
-    reportSkips(skippedMajor, skippedDrift, skippedPatchGate);
+    else {
+        if (applicable.length) {
+            log(`${applicable.length} practice(s) would update on \`convene update --apply\`.`);
+        }
+        reportSkips(skippedMajor, skippedDrift, skippedPatchGate);
+    }
+    printAvailable(available, catalogVersion);
+    if (!nothingToApply) {
+        log('');
+        log('Next: `convene update --apply` (review with `git diff` and commit yourself — Convene never commits).');
+    }
+}
+/**
+ * List catalog practices the repo has NOT adopted and point at `convene adopt`. The
+ * delta `convene update` cannot take (it only bumps the already-adopted set) — without
+ * this an agent that saw "Catalog update available: repo on vX → vY" runs `--apply`,
+ * gets "Nothing to apply", and never learns the new practices exist. No-op when empty.
+ */
+function printAvailable(available, catalogVersion) {
+    if (available.length === 0)
+        return;
     log('');
-    log('Next: `convene update --apply` (review with `git diff` and commit yourself — Convene never commits).');
+    log(`${available.length} new practice(s) available in catalog v${catalogVersion} but NOT adopted here:`);
+    const aw = Math.max(8, ...available.map((p) => p.id.length));
+    for (const p of available)
+        log(`  ${pad(p.id, aw)}  ${pad(p.tier, 12)}  ${p.title}`);
+    log('');
+    log('`convene update` only refreshes practices you already adopted — it never adopts new ones for you.');
+    log(`To add one: \`convene adopt <id>\` (e.g. \`convene adopt ${available[0].id}\`). See the why first: \`convene practices <id>\`.`);
+}
+/** One-line apply-path pointer to `convene adopt` for newly-available practices. */
+function availablePointer(available) {
+    if (available.length === 0)
+        return;
+    log(`  ${available.length} new practice(s) available but NOT adopted — \`convene update --apply\` never adopts new ones. Use \`convene adopt <id>\`.`);
 }
-async function applyUpdate(top, manifest, catalog, rows, opts) {
+async function applyUpdate(top, manifest, catalog, rows, opts, available) {
     const byId = new Map(catalog.practices.map((p) => [p.id, p]));
     const toUpdate = rows.filter((r) => isApplicable(r, opts));
     const skippedMajor = rows.filter((r) => skipForMajor(r, opts));
@@ -365,6 +521,7 @@ async function applyUpdate(top, manifest, catalog, rows, opts) {
         log('Nothing applied — no practice was eligible.');
         reportSkips(skippedMajor, skippedDrift, skippedPatchGate);
         reportRemoved(rows);
+        availablePointer(available); // never auto-adopts; just points at `convene adopt`
         return;
     }
     // PRESERVE skipped (drifted / major / patch-gated) sections byte-for-byte: snapshot
@@ -415,6 +572,7 @@ async function applyUpdate(top, manifest, catalog, rows, opts) {
     }
     reportSkips(skippedMajor, skippedDrift, skippedPatchGate);
     reportRemoved(rows);
+    availablePointer(available); // never auto-adopts; just points at `convene adopt`
     log('');
     log('Changes are in your working tree only. Review with `git diff` and commit yourself — Convene never commits.');
 }

package/dist/git.js

@@ -20,6 +20,8 @@ exports.revListCount = revListCount;
 exports.revParse = revParse;
 exports.isAncestor = isAncestor;
 exports.gitFetch = gitFetch;
+exports.gitShow = gitShow;
+exports.changedPaths = changedPaths;
 exports.gitHooksDir = gitHooksDir;
 exports.gitConfigSetLocal = gitConfigSetLocal;
 exports.gitConfigUnsetLocal = gitConfigUnsetLocal;
@@ -240,6 +242,22 @@ function gitFetch(ref, remote = 'origin', cwd = process.cwd()) {
         return false;
     }
 }
+/**
+ * Contents of `ref:relPath` (e.g. `origin/main:.convene/project.json`), or null when
+ * the ref or path does not exist there. Read-only, bounded, never throws — used to
+ * peek at what a remote tip carries without checking it out.
+ */
+function gitShow(ref, relPath, cwd = process.cwd()) {
+    return git(['show', `${ref}:${relPath}`], cwd);
+}
+/**
+ * File paths that DIFFER between two refs, restricted to `paths` (files or dirs):
+ * `git diff --name-only refA refB -- <paths>`. Empty array when identical or on error.
+ */
+function changedPaths(refA, refB, paths, cwd = process.cwd()) {
+    const out = git(['diff', '--name-only', refA, refB, '--', ...paths], cwd);
+    return out ? out.split('\n').map((l) => l.trim()).filter(Boolean) : [];
+}
 /** Absolute path to this repo's hooks directory (resolves worktrees/submodules). */
 function gitHooksDir(cwd = process.cwd()) {
     const p = git(['rev-parse', '--git-path', 'hooks'], cwd);

package/dist/hook.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.HOOK_COMMAND = exports.SETTINGS_PATH = void 0;
+exports.COORD_HOOKS = exports.HOOK_COMMAND = exports.SETTINGS_PATH = void 0;
 exports.binarySupportsVerb = binarySupportsVerb;
 exports.readSettingsRaw = readSettingsRaw;
 exports.parseSettings = parseSettings;
@@ -13,6 +13,7 @@ exports.serializeSettings = serializeSettings;
 exports.genericHookIsRegistered = genericHookIsRegistered;
 exports.withGenericHook = withGenericHook;
 exports.ensureHook = ensureHook;
+exports.missingCoordHooks = missingCoordHooks;
 exports.ensureHookRegistered = ensureHookRegistered;
 exports.isConveneHookCommand = isConveneHookCommand;
 exports.conveneHookFingerprint = conveneHookFingerprint;
@@ -174,6 +175,69 @@ function ensureHook(eventName, command, matcher, settingsPath = exports.SETTINGS
         return 'manual';
     }
 }
+exports.COORD_HOOKS = [
+    {
+        event: 'SessionStart',
+        matcher: 'startup|resume|clear',
+        command: 'convene session-start',
+        verb: 'session-start',
+        note: 'auto catch-up digest + mints the session-instance + launches `convene watch`',
+    },
+    {
+        event: 'PreToolUse',
+        matcher: 'Bash',
+        command: 'convene gate-push --stdin',
+        verb: 'gate-push',
+        note: 'deploy gate before a push (fail-open-loud)',
+    },
+    // guard is appended AFTER gate-push so it is LAST among Bash PreToolUse hooks.
+    {
+        event: 'PreToolUse',
+        matcher: 'Bash',
+        command: 'convene guard',
+        verb: 'guard',
+        note: 'halt + lane backstop for Bash (fail-open-loud)',
+    },
+    {
+        event: 'PreToolUse',
+        matcher: '.*',
+        command: 'convene guard --halt-only',
+        verb: 'guard',
+        note: 'cheap directed-halt backstop on every tool call',
+    },
+    {
+        event: 'PostToolUse',
+        matcher: 'Bash',
+        command: 'convene gate-push --post',
+        verb: 'gate-push',
+        note: 'release the deploy lane after a push (idempotent)',
+    },
+    {
+        event: 'PostToolUse',
+        matcher: 'Edit|Write|MultiEdit',
+        command: 'convene beat --stdin',
+        verb: 'beat',
+        note: 'debounced session activity-beat so a heads-down session still pulses on the bus',
+    },
+    // Stop fires at every turn-end (no tool matcher); `convene wrap` is idempotent +
+    // debounced via the last-broadcast-sha cursor, so it posts at most one wrap per
+    // stretch of new committed work and stays silent on idle turns. Never blocks.
+    {
+        event: 'Stop',
+        command: 'convene wrap',
+        verb: 'wrap',
+        note: 'session-end wrap status when new committed work landed (idempotent, fail-open)',
+    },
+];
+/**
+ * COORD_HOOKS entries whose verb THIS binary supports but which are NOT present in
+ * `settings` — i.e. coordination wiring that has drifted from the canonical set.
+ * Verbs the binary lacks are skipped (mirroring registerCoordinationHooks), so an
+ * older CLI is never told to wire something it can't run.
+ */
+function missingCoordHooks(settings) {
+    return exports.COORD_HOOKS.filter((h) => binarySupportsVerb(h.verb) && !genericHookIsRegistered(settings, h.event, h.command, h.matcher));
+}
 /** Ensure the UserPromptSubmit hook is registered (idempotent, backs up). */
 function ensureHookRegistered() {
     const raw = readSettingsRaw();

package/dist/index.js

@@ -44,6 +44,7 @@ const fetch_1 = require("./commands/fetch");
 const notify_1 = require("./commands/notify");
 const announce_1 = require("./commands/announce");
 const wrap_1 = require("./commands/wrap");
+const friction_1 = require("./commands/friction");
 const post = __importStar(require("./commands/post"));
 const inbox_1 = require("./commands/inbox");
 const feedback_1 = require("./commands/feedback");
@@ -71,6 +72,7 @@ const watch_reap_1 = require("./commands/watch-reap");
 const explain_1 = require("./commands/explain");
 const practices_1 = require("./commands/practices");
 const update_1 = require("./commands/update");
+const adopt_1 = require("./commands/adopt");
 const program = new commander_1.Command();
 exports.program = program;
 // Read the version from package.json so `convene --version` always tracks the
@@ -220,6 +222,14 @@ program
     .option('--project <slug>')
     .option('--dry-run', 'print the status it would post; do not post')
     .action((opts) => (0, wrap_1.wrap)(opts));
+program
+    .command('friction')
+    .description('auto-capture in-session confusion as a low-severity [FRICTION] feature_feedback (idempotent, fail-silent)')
+    .option('--kind <kind>', 'friction kind (e.g. unmatched-explain)')
+    .option('--q <text>', "the signal text — the agent's own words about Convene")
+    .option('--project <slug>')
+    .option('--dry-run', 'print what it would capture; do not post')
+    .action((opts) => (0, friction_1.friction)(opts));
 const postCmd = program.command('post').description('post outbound coordination messages');
 postCmd
     .command('status <body>')
@@ -396,6 +406,14 @@ program
     .option('--no-agent-rules', 'skip the cross-agent rule files during --refresh/--host')
     .option('--no-mcp', 'skip the MCP carriers during --refresh/--host')
     .action((opts) => (0, update_1.update)(opts));
+program
+    .command('adopt <targets...>')
+    .description('adopt one or more catalog best practices into this repo (merges into the existing set, drift-safe; review in your working tree, never auto-commits)')
+    .option('--force', 're-level a locally-edited (drifted) practice anyway (overwrites your edits)')
+    .option('--no-hook', 'do not wire settingsHook guards (settingsJson deny + gitignore still apply)')
+    .option('--offline', 'skip the dashboard adoption report')
+    .option('--project <slug>', 'project slug (defaults to .convene/project.json)')
+    .action((targets, opts) => (0, adopt_1.adopt)(targets, opts));
 program.command('doctor').description('diagnose setup').option('--fix', 'attempt safe fixes').action((opts) => (0, auth_1.doctor)(opts));
 if (require.main === module) {
     program.parseAsync(process.argv).catch((err) => {