convene-cli 1.1.1 → 1.3.0

package/dist/catalog/prompt.js

@@ -0,0 +1,89 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pickPracticesInteractively = pickPracticesInteractively;
+/**
+ * Interactive best-practices picker for `convene init` / `convene setup`.
+ *
+ * STRICTLY interactive: the caller MUST gate on `process.stdin.isTTY &&
+ * process.stdout.isTTY && !opts.yes` before invoking this — it is never reached in
+ * tests (which run non-TTY) or under `--yes` (agents/CI). The whole flow is wrapped
+ * so any error / EOF / Ctrl-D falls back to `[]` (adopt nothing) — a picker hiccup
+ * must NEVER crash onboarding. The readline interface is always closed in a finally.
+ */
+const promises_1 = __importDefault(require("node:readline/promises"));
+const select_1 = require("./select");
+const out = (m) => process.stdout.write(m + '\n');
+/** Count of opt-in (default-ON) practices in the named tiers — for the menu labels. */
+function presetCount(catalog, preset) {
+    return (0, select_1.presetSelections)(catalog, preset).length;
+}
+/**
+ * Run the onboarding picker and resolve a Selection[]. Returns [] on EOF / any
+ * error / explicit "None". Never throws.
+ */
+async function pickPracticesInteractively(catalog) {
+    const rl = promises_1.default.createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        out('');
+        out('Adopt Convene best practices for this repo? (lean CLAUDE.md guidance now; enforcement hooks later)');
+        out(`  [1] Essentials (${presetCount(catalog, 'essentials')})`);
+        out(`  [2] Essentials + Recommended (${presetCount(catalog, 'recommended')})  [default]`);
+        out(`  [3] Everything (${presetCount(catalog, 'all')})`);
+        out('  [4] Customize');
+        out('  [n] None');
+        const choice = (await rl.question('Choose [2]: ')).trim().toLowerCase();
+        if (choice === 'n' || choice === 'none')
+            return [];
+        if (choice === '1')
+            return (0, select_1.presetSelections)(catalog, 'essentials');
+        if (choice === '3')
+            return (0, select_1.presetSelections)(catalog, 'all');
+        if (choice === '4')
+            return await customize(catalog, rl);
+        // Empty input or "2" → the recommended default.
+        return (0, select_1.presetSelections)(catalog, 'recommended');
+    }
+    catch {
+        // EOF (Ctrl-D), a closed pipe, anything — never crash onboarding.
+        return [];
+    }
+    finally {
+        rl.close();
+    }
+}
+/**
+ * Customize from the recommended preset: for each chosen practice show
+ * `title [defaultLevel]` and accept enter=keep, 's'=skip, or a level name from
+ * availableLevels. Skimmable; unknown levels re-prompt-free (keep at default).
+ */
+async function customize(catalog, rl) {
+    const base = (0, select_1.presetSelections)(catalog, 'recommended');
+    const byId = new Map(catalog.practices.map((p) => [p.id, p]));
+    const result = [];
+    out('');
+    out('Customize — for each: [enter] keep · [s] skip · or type a level name.');
+    for (const sel of base) {
+        const p = byId.get(sel.id);
+        if (!p)
+            continue;
+        const levels = p.availableLevels.join('/');
+        const ans = (await rl.question(`  ${p.title} [${sel.level}] (${levels}): `)).trim().toLowerCase();
+        if (ans === 's' || ans === 'skip')
+            continue;
+        if (ans === '') {
+            result.push(sel);
+            continue;
+        }
+        if (p.availableLevels.includes(ans)) {
+            result.push({ id: sel.id, level: ans });
+        }
+        else {
+            out(`    (unrecognized level "${ans}" — keeping ${sel.level})`);
+            result.push(sel);
+        }
+    }
+    return result;
+}

package/dist/catalog/report.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.reportManifest = reportManifest;
+/**
+ * Phase 5 — report the adopted best-practices manifest to the server so the
+ * dashboard can show per-project adoption.
+ *
+ * This is PURELY observability and is ALWAYS best-effort / fail-OPEN: it must
+ * never fail or slow down `convene init` (onboarding) or `convene update --apply`
+ * because the report failed, was offline, or the server is down. The whole thing
+ * is fire-and-forget — every failure path returns `{ ok: false }` and is swallowed
+ * by the caller.
+ */
+const api_1 = require("../api");
+const config_1 = require("../config");
+const git_1 = require("../git");
+/** A short, fixed budget — the report is non-blocking, so never the 10s default. */
+const REPORT_TIMEOUT_MS = 5_000;
+/**
+ * Fire-and-forget the manifest report. Resolves to `{ ok }`, NEVER throws and
+ * NEVER prints. Skips silently (ok:false) when offline or with no API key — the
+ * report is optional and onboarding/update proceed regardless.
+ *
+ *   - `offline` — caller ran with --offline; skip the network entirely.
+ *   - no api key / no member — not logged in; nothing to authenticate the POST.
+ */
+async function reportManifest(top, slug, manifest, opts = {}) {
+    try {
+        if (opts.offline)
+            return { ok: false };
+        const cfg = (0, config_1.resolveConfig)();
+        if (!cfg.apiKey)
+            return { ok: false };
+        const session = cfg.member ? (0, git_1.sessionId)(cfg.member, top) : null;
+        const api = new api_1.ConveneApi(cfg.baseUrl, cfg.apiKey, session, cfg.tool);
+        const res = await api.reportBestPractices(slug, manifest, REPORT_TIMEOUT_MS);
+        return { ok: res.ok };
+    }
+    catch {
+        // Belt-and-suspenders: ConveneApi.request is already fail-soft, but the
+        // report is observability-only — any unexpected throw is swallowed so a call
+        // site can fire-and-forget without a try/catch of its own.
+        return { ok: false };
+    }
+}

package/dist/catalog/select.js

@@ -0,0 +1,86 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.selectionsForTiers = selectionsForTiers;
+exports.parseSelectionFlags = parseSelectionFlags;
+exports.presetSelections = presetSelections;
+/** All `optInDefault:'on'` practices in the given tiers, at each one's defaultLevel. */
+function selectionsForTiers(catalog, tiers) {
+    const want = new Set(tiers);
+    return catalog.practices
+        .filter((p) => want.has(p.tier) && p.optInDefault === 'on')
+        .map((p) => ({ id: p.id, level: p.defaultLevel }));
+}
+/**
+ * Resolve CLI selection flags into a Selection[] — or `null` when NO selection
+ * flag was passed (the caller then decides: prompt interactively, or skip the
+ * catalog entirely). Precedence, applied in CATALOG order at the end so the
+ * result is deterministic regardless of flag order:
+ *   --no-practices      → [] (explicitly adopt nothing)
+ *   --all-practices     → every practice at its defaultLevel
+ *   --tier a,b          → selectionsForTiers
+ *   --practice id|id=lvl → add/override that id at the level (validated)
+ * `--practice` always wins over a tier pick for the same id.
+ */
+function parseSelectionFlags(opts, catalog) {
+    const hasTier = typeof opts.tier === 'string' && opts.tier.length > 0;
+    const hasPractice = Array.isArray(opts.practice) && opts.practice.length > 0;
+    if (!opts.noPractices && !opts.allPractices && !hasTier && !hasPractice)
+        return null;
+    // --no-practices is the explicit "adopt nothing" — it short-circuits everything.
+    if (opts.noPractices)
+        return [];
+    const byId = new Map(catalog.practices.map((p) => [p.id, p]));
+    // Keep levels in a map keyed by id; emit in CATALOG order at the end.
+    const chosen = new Map();
+    if (opts.allPractices) {
+        for (const p of catalog.practices)
+            chosen.set(p.id, p.defaultLevel);
+    }
+    else if (hasTier) {
+        const tiers = opts.tier.split(',').map((t) => t.trim()).filter(Boolean);
+        for (const s of selectionsForTiers(catalog, tiers))
+            chosen.set(s.id, s.level);
+    }
+    // --practice add/override (after tier so it wins): "id" → defaultLevel, "id=level" → that level.
+    if (hasPractice) {
+        for (const raw of opts.practice) {
+            const eq = raw.indexOf('=');
+            const id = (eq >= 0 ? raw.slice(0, eq) : raw).trim();
+            const lvl = eq >= 0 ? raw.slice(eq + 1).trim() : null;
+            const p = byId.get(id);
+            if (!p)
+                throw new Error(`unknown practice "${id}" — not in the catalog (run \`convene doctor\` to see ids)`);
+            let level;
+            if (lvl === null) {
+                level = p.defaultLevel;
+            }
+            else {
+                if (!p.availableLevels.includes(lvl)) {
+                    throw new Error(`invalid level "${lvl}" for practice "${id}" — choose one of: ${p.availableLevels.join(', ')}`);
+                }
+                level = lvl;
+            }
+            chosen.set(id, level);
+        }
+    }
+    return catalog.practices.filter((p) => chosen.has(p.id)).map((p) => ({ id: p.id, level: chosen.get(p.id) }));
+}
+/**
+ * Named onboarding presets:
+ *   essentials  — essentials-tier opt-ins
+ *   recommended — essentials + recommended opt-ins
+ *   all         — every practice at its defaultLevel
+ *   none        — []
+ */
+function presetSelections(catalog, preset) {
+    switch (preset) {
+        case 'none':
+            return [];
+        case 'essentials':
+            return selectionsForTiers(catalog, ['essentials']);
+        case 'recommended':
+            return selectionsForTiers(catalog, ['essentials', 'recommended']);
+        case 'all':
+            return catalog.practices.map((p) => ({ id: p.id, level: p.defaultLevel }));
+    }
+}

package/dist/catalog/types.js

@@ -0,0 +1,14 @@
+"use strict";
+/**
+ * Canonical type contract for the Convene best-practices catalog — the data model
+ * shared by the server (source of truth, seeds the DB + serves GET /api/v1/catalog)
+ * and the CLI (a generated mirror it materializes into repos). Kept deliberately
+ * small and stable; the CLI carries a byte-mirror of this file (see brand.ts for the
+ * same dual-copy convention) so the two packages never import across the workspace.
+ *
+ * Versioning: every Practice carries its own SemVer (so a single practice can be
+ * tightened without rev'ing the whole catalog), and the Catalog itself carries a
+ * release SemVer. A repo's manifest pins the (practice, version, level) triple it
+ * adopted — see PracticeManifestEntry — so updates are diffable and never silent.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/commands/auth.js

@@ -13,6 +13,8 @@ const node_child_process_1 = require("node:child_process");
 const brand_1 = require("../brand");
 const api_1 = require("../api");
 const config_1 = require("../config");
+const catalog_1 = require("../catalog");
+const manifest_1 = require("../catalog/manifest");
 const git_1 = require("../git");
 const hook_1 = require("../hook");
 const cache_1 = require("../cache");
@@ -310,6 +312,48 @@ async function doctor(opts) {
     for (const c of checks) {
         process.stdout.write(`${c.ok ? '✓' : '✗'} ${c.name.padEnd(8)} ${c.detail}\n`);
     }
+    // Best practices (local-only, advisory): adopted-practice inventory + whether
+    // the repo trails the catalog. Fail-soft — never throws and never alters the
+    // doctor exit code.
+    reportBestPractices(top, proj?.slug ?? null);
     if (!checks.every((c) => c.ok))
         process.exitCode = 1;
 }
+/**
+ * Print doctor's "Best practices" section. Local-only this phase: reads the repo
+ * manifest and diffs it against the bundled catalog. Purely informational — it
+ * never throws (a malformed manifest is swallowed) and never sets the exit code.
+ *   - manifest present → catalog freshness line + each adopted practice + unknowns.
+ *   - on the bus but no manifest → a single nudge to adopt some.
+ *   - not on the bus → nothing.
+ */
+function reportBestPractices(top, slug) {
+    try {
+        const manifest = (0, config_1.loadManifest)(top);
+        if (!manifest) {
+            if (slug) {
+                process.stdout.write('· no best practices adopted — run `convene init` to choose some\n');
+            }
+            return;
+        }
+        const cmp = (0, manifest_1.compareToCatalog)(manifest, catalog_1.CATALOG);
+        process.stdout.write(cmp.behind
+            ? `· catalog v${cmp.catalogVersion} available (repo on v${cmp.repoVersion}) — run \`convene update\`\n`
+            : `· best practices up to date at v${cmp.repoVersion}\n`);
+        for (const p of cmp.adopted) {
+            const flag = p.outdated ? ` (outdated → v${p.catalogVersion})` : '';
+            process.stdout.write(`    ${p.id} @ ${p.manifestVersion} [${p.level}]${flag}\n`);
+        }
+        if (cmp.unknownIds.length) {
+            process.stdout.write(`    unknown (not in catalog): ${cmp.unknownIds.join(', ')}\n`);
+        }
+        // Adoption is reported to the server on init/update — point the human at the
+        // dashboard view. Local-only hint; no network call (slug present ⇒ on the bus).
+        if (slug) {
+            process.stdout.write(`    adoption is visible on the dashboard: ${(0, config_1.resolveConfig)().baseUrl}/p/${slug}\n`);
+        }
+    }
+    catch {
+        /* fail-soft: best-practices reporting must never break doctor */
+    }
+}

package/dist/commands/fetch.js

@@ -21,6 +21,7 @@ const node_fs_1 = __importDefault(require("node:fs"));
 const git_1 = require("../git");
 const config_1 = require("../config");
 const cache_1 = require("../cache");
+const manifest_1 = require("../catalog/manifest");
 const api_1 = require("../api");
 const render_1 = require("../render");
 const catchup_1 = require("./catchup");
@@ -28,6 +29,30 @@ const exit_1 = require("../exit");
 const CACHE_TTL_SEC = 3;
 const FETCH_TIMEOUT_MS = 4000;
 const WATCHDOG_MS = 6000;
+/** Catalog-version cache TTL for the behind-nudge — long enough to stay off the hot path. */
+const CATALOG_VERSION_TTL_SEC = 3600;
+/**
+ * A single fail-soft nudge line iff the repo's adopted-practices manifest trails a
+ * CACHED live catalog version. Reads only local state (the manifest + the catalog-
+ * version cache) — NEVER hits the network, so it can't slow the hot path. On a cache
+ * miss, no manifest, or any error → null (no line; never spam when up to date).
+ */
+function catalogBehindNudge(top) {
+    try {
+        const manifest = (0, config_1.loadManifest)(top);
+        if (!manifest)
+            return null;
+        const live = (0, cache_1.readCatalogVersion)(CATALOG_VERSION_TTL_SEC);
+        if (!live)
+            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\``;
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Write a rendered block. In `codexHook` mode, wrap it in Codex's UserPromptSubmit
  * hook envelope so its `additionalContext` lands in the model's per-turn context;
@@ -128,10 +153,21 @@ async function runFetch(opts = {}) {
             // DEGRADED/failure under --since-last emits nothing (structural suppression).
             return done(0);
         }
+        // A fail-soft, network-free nudge line emitted alongside a healthy block when
+        // the repo trails the CACHED live catalog version (suppressed under --json /
+        // codex-hook to keep those envelopes clean).
+        const emitNudge = () => {
+            if (opts.json || opts.codexHook)
+                return;
+            const nudge = catalogBehindNudge(top);
+            if (nudge)
+                process.stdout.write(nudge + '\n');
+        };
         // Cache short-circuit for rapid successive prompts.
         const cache = (0, cache_1.readCache)(slug);
         if (cache && (0, cache_1.ageSeconds)(cache) < CACHE_TTL_SEC) {
             renderData(cache.data, { slug, member, session, lookback, syncedAgoSec: (0, cache_1.ageSeconds)(cache), json: opts.json });
+            emitNudge();
             return done(0);
         }
         // Slow path: bounded network fetch.
@@ -140,6 +176,20 @@ async function runFetch(opts = {}) {
         if (res.ok && res.json) {
             (0, cache_1.writeCache)(slug, res.json);
             renderData(res.json, { slug, member, session, lookback, syncedAgoSec: 0, json: opts.json });
+            // Opportunistically refresh the catalog-version cache off the slow path (never
+            // its own round-trip on the hot path): only when the cached version is stale,
+            // and only if a manifest exists (a non-best-practices repo never needs it).
+            if ((0, config_1.loadManifest)(top) && !(0, cache_1.readCatalogVersion)(CATALOG_VERSION_TTL_SEC)) {
+                try {
+                    const cat = await api.getCatalog(FETCH_TIMEOUT_MS);
+                    if (cat.ok && cat.json?.version)
+                        (0, cache_1.writeCatalogVersion)(cat.json.version);
+                }
+                catch {
+                    /* fail-soft: the nudge just stays suppressed until next refresh */
+                }
+            }
+            emitNudge();
             return done(0);
         }
         // Fetch failed/timed out → DEGRADED from stale cache (or absent).

package/dist/commands/inbox.js

@@ -3,7 +3,22 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.inbox = inbox;
 /** `convene inbox` — open questions/proposals addressed to me. */
 const ctx_1 = require("../ctx");
+const git_1 = require("../git");
+const config_1 = require("../config");
 async function inbox(opts) {
+    // `--all-projects` is a DELIBERATELY cross-project view (every project you belong to).
+    // Per-project scoping is otherwise airtight; this one flag opts out of it on purpose.
+    // Running it from a repo that isn't on the bus pulls other projects' items into an
+    // unrelated session — almost never intended. Make it a deliberate act: require the
+    // cwd repo to be on Convene, or an explicit `--force`.
+    if (opts.allProjects && !opts.force) {
+        const proj = (0, config_1.loadProjectConfig)((0, git_1.gitToplevel)());
+        if (!proj?.slug) {
+            (0, ctx_1.die)('refusing `--all-projects` from a repo that is NOT on Convene — this flag is a deliberate ' +
+                'cross-project view; running it from an unrelated checkout pulls other projects’ items into ' +
+                'this session. cd into a Convene repo, or pass `--force` if you really mean to.');
+        }
+    }
     const ctx = (0, ctx_1.getContext)({ project: opts.project });
     const slug = opts.allProjects ? null : ctx.slug; // null => /inbox across all my projects
     const res = await ctx.api.inbox(slug, 10_000);

package/dist/commands/init.js

@@ -3,7 +3,11 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.AIDER_CONF = exports.CONVENE_PATHS = void 0;
 exports.upsertMarkerBlock = upsertMarkerBlock;
+exports.removeMarkerBlock = removeMarkerBlock;
+exports.removeGitignoreGuard = removeGitignoreGuard;
+exports.removeTomlBlock = removeTomlBlock;
 exports.init = init;
 /**
  * `convene init` — one-command repo onboarding. IDEMPOTENT + merge-safe
@@ -20,7 +24,33 @@ const api_1 = require("../api");
 const protocol_1 = require("../protocol");
 const hook_1 = require("../hook");
 const githook_1 = require("../githook");
+const catalog_1 = require("../catalog");
+const materialize_1 = require("../catalog/materialize");
+const select_1 = require("../catalog/select");
+const prompt_1 = require("../catalog/prompt");
+const report_1 = require("../catalog/report");
 const ctx_1 = require("../ctx");
+/**
+ * The repo-relative paths convene init writes (the onboarding footprint). Shared by
+ * init's `--commit` and `convene off-board` so the two stay in lockstep — staging
+ * exactly these, never a blanket `git add -A`.
+ */
+exports.CONVENE_PATHS = [
+    '.convene',
+    'CLAUDE.md',
+    'AGENTS.md',
+    'CONVENE_PROTOCOL.md',
+    '.gitignore',
+    '.claude/settings.json',
+    '.githooks/pre-push',
+    '.cursor/rules/convene.mdc',
+    '.cursor/mcp.json',
+    '.clinerules/convene.md',
+    '.gemini/settings.json',
+    '.aider.conf.yml',
+    '.vscode/mcp.json',
+    '.codex/config.toml',
+];
 const log = (m) => process.stdout.write(m + '\n');
 /** Replace content between the convene markers, or append the block if absent. */
 function upsertMarkerBlock(content, block) {
@@ -34,6 +64,29 @@ function upsertMarkerBlock(content, block) {
     const sep = content.length === 0 ? '' : content.endsWith('\n') ? '\n' : '\n\n';
     return content + sep + block + '\n';
 }
+/**
+ * Inverse of upsertMarkerBlock (off-board). Removes the convene block (markers
+ * inclusive), collapsing the blank separator upsert added before it and the
+ * trailing newline after — so a file that ONLY ever held the block returns to ''
+ * (caller deletes it), and a file with pre-existing content returns BYTE-IDENTICAL
+ * to its pre-onboard form. `removed` is false when no block is present.
+ */
+function removeMarkerBlock(content) {
+    return stripBetween(content, brand_1.BRAND.blockBegin, brand_1.BRAND.blockEnd);
+}
+/** Shared block-removal for both the HTML (CLAUDE/AGENTS) and TOML (Codex) markers. */
+function stripBetween(content, begin, end) {
+    const start = content.indexOf(begin);
+    const endIdx = content.indexOf(end);
+    if (start < 0 || endIdx <= start)
+        return { content, removed: false };
+    const head = content.slice(0, start).replace(/\n+$/, '');
+    const tail = content.slice(endIdx + end.length).replace(/^\n+/, '');
+    let joined = head && tail ? head + '\n\n' + tail : head + tail;
+    if (joined.length > 0 && !joined.endsWith('\n'))
+        joined += '\n';
+    return { content: joined, removed: true };
+}
 // Every file this writes lives inside the git repo, so git history IS the backup —
 // dropping a sibling `.bak` just litters the working tree (and shows up as untracked
 // noise / risks being committed). The only `.bak` we keep is for the user's GLOBAL
@@ -97,6 +150,39 @@ function ensureGitignoreGuard(top) {
         log('  then `git add -f .convene/project.json`.');
     }
 }
+/**
+ * Inverse of ensureGitignoreGuard (off-board). Drops the three granular guard lines
+ * AND restores any blanket `.convene/` rule we had commented out — so the file
+ * round-trips to its pre-onboard form. If the file ends up empty (it was created
+ * solely for the guard), it is deleted. Returns true iff anything changed.
+ */
+function removeGitignoreGuard(top) {
+    const file = node_path_1.default.join(top, '.gitignore');
+    if (!node_fs_1.default.existsSync(file))
+        return false;
+    const old = node_fs_1.default.readFileSync(file, 'utf8');
+    const guardComment = '# convene (keep local cache out of git; .convene/project.json IS committed)';
+    const next = old
+        .split('\n')
+        .filter((line) => {
+        const t = line.trim();
+        return t !== guardComment && t !== '.convene/cache/' && t !== '.convene/*.local.json';
+    })
+        .map((line) => {
+        // Re-enable a blanket rule we disabled (e.g. "# .convene/   (disabled by convene init: …)").
+        const m = line.match(/^#\s(.+?)\s+\(disabled by convene init/);
+        return m ? m[1] : line;
+    })
+        .join('\n');
+    if (next === old)
+        return false;
+    if (next.trim().length === 0) {
+        node_fs_1.default.rmSync(file, { force: true });
+        return true;
+    }
+    node_fs_1.default.writeFileSync(file, next);
+    return true;
+}
 function hookSnippet() {
     return JSON.stringify({ hooks: { UserPromptSubmit: [{ hooks: [{ type: 'command', command: hook_1.HOOK_COMMAND }] }] } }, null, 2);
 }
@@ -294,6 +380,9 @@ function writeGeminiSettings(top) {
     const r = writeIfChanged(file, JSON.stringify(obj, null, 2) + '\n');
     log(`${r === 'unchanged' ? '·' : '✓'} .gemini/settings.json (${r}) — Gemini CLI reads AGENTS.md each prompt`);
 }
+/** The exact `.aider.conf.yml` init writes when none exists — so off-board can tell
+ *  "ours" (delete) from a user's own config (leave). */
+exports.AIDER_CONF = 'read:\n  - AGENTS.md\n  - CONVENE_PROTOCOL.md\n';
 function writeAiderConf(top) {
     // No YAML parser bundled, so write-if-absent (don't risk clobbering an existing config).
     const file = node_path_1.default.join(top, '.aider.conf.yml');
@@ -301,7 +390,7 @@ function writeAiderConf(top) {
         log('· .aider.conf.yml (exists) — add `read: [AGENTS.md, CONVENE_PROTOCOL.md]` so Aider loads Convene');
         return;
     }
-    node_fs_1.default.writeFileSync(file, 'read:\n  - AGENTS.md\n  - CONVENE_PROTOCOL.md\n');
+    node_fs_1.default.writeFileSync(file, exports.AIDER_CONF);
     log('✓ .aider.conf.yml (created) — Aider loads the Convene instructions at startup');
 }
 function writeAgentRules(top, slug, member, baseUrl) {
@@ -335,6 +424,10 @@ function upsertTomlBlock(content, block) {
     const sep = content.length === 0 ? '' : content.endsWith('\n') ? '\n' : '\n\n';
     return content + sep + block + '\n';
 }
+/** Inverse of upsertTomlBlock (off-board) — removes the convene block from a Codex config.toml. */
+function removeTomlBlock(content) {
+    return stripBetween(content, TOML_BEGIN, TOML_END);
+}
 /**
  * Ensure the `convene` server in a JSON MCP config under `topKey` (`mcpServers` for
  * Cursor/Gemini, `servers` for VS Code). `stdioType` adds `"type":"stdio"` (VS Code
@@ -389,10 +482,59 @@ function writeMcpConfigs(top, baseUrl) {
     writeCodexConfig(top, baseUrl);
     log('· Cline & Windsurf register MCP only in a user-global file — add `convene` (`npx -y convene-mcp`) there manually; see CONVENE_PROTOCOL.md.');
 }
+/**
+ * Resolve + materialize the adopted best practices for this repo (Phase 2). Flags
+ * win when present; otherwise a real interactive TTY (and NOT --yes) gets the
+ * picker; otherwise we skip silently. An EMPTY selection writes NOTHING (no
+ * manifest, no doc, no ref region) — that invariant keeps a plain init byte-identical.
+ */
+async function adoptBestPractices(top, slug, opts) {
+    let selections;
+    const flags = (0, select_1.parseSelectionFlags)(opts, catalog_1.CATALOG);
+    if (flags !== null) {
+        selections = flags;
+    }
+    else if (process.stdin.isTTY && process.stdout.isTTY && !opts.yes) {
+        selections = await (0, prompt_1.pickPracticesInteractively)(catalog_1.CATALOG);
+    }
+    else {
+        // Non-interactive with no --tier/--practice flags: adopt nothing, silently — a plain
+        // headless onboarding stays byte-identical. `convene doctor` is where a human is
+        // nudged that best practices are available to adopt.
+        return;
+    }
+    // Respect --no-hook: when init declines to write the committed project settings,
+    // the materialized settingsHook guards are skipped too (settingsJson/gitignore
+    // still apply — they are not Claude-Code hooks).
+    const wireHooks = !(opts.noHook === true || opts.hook === false);
+    const entries = (0, materialize_1.materializePractices)(top, slug, selections, catalog_1.CATALOG, { wireHooks });
+    if (entries.length) {
+        const manifest = { catalogVersion: catalog_1.CATALOG.version, channel: 'minor', practices: entries };
+        (0, config_1.writeManifest)(top, manifest);
+        log(`✓ adopted ${entries.length} best practices (.convene/best-practices.md) — see them with \`convene doctor\``);
+        // Phase 5: report adoption to the server so the dashboard can show it.
+        // Best-effort, fail-OPEN, fire-and-forget — onboarding NEVER fails/slows
+        // because the report failed; skipped silently when --offline or no api key.
+        const { ok } = await (0, report_1.reportManifest)(top, slug, manifest, { offline: opts.offline });
+        if (ok)
+            log('· reported adoption to the dashboard');
+    }
+}
 async function init(opts) {
     const top = (0, git_1.gitToplevel)();
     if (!top)
         (0, ctx_1.die)('not a git repository — run `convene init` inside a repo');
+    // Consent gate: onboarding writes a footprint and registers per-prompt hooks — it
+    // must be a DELIBERATE choice, never an accidental side-effect. A human at a
+    // terminal (TTY) confirms simply by running it; an agent / CI (no TTY) must pass
+    // `--yes` so a repo can never be onboarded as a stray side-effect (the VAcontractorCo
+    // failure). This is about intent, not confidentiality — private repos are first-class
+    // (init commits the join token into them by design), and each repo is its own
+    // project, scoped to the members you add.
+    if (!opts.yes && !process.stdout.isTTY) {
+        (0, ctx_1.die)('refusing to onboard non-interactively without confirmation — connecting THIS repo to Convene ' +
+            'is a deliberate choice, not a side-effect. If you intend it, re-run with `--yes`.');
+    }
     const cfg = (0, config_1.resolveConfig)();
     const baseUrl = cfg.baseUrl;
     let member = cfg.member;
@@ -481,6 +623,23 @@ async function init(opts) {
                     joinToken = jt.json.join_token;
             }
         }
+        // Membership verification — the fix for "half-onboarded silently". Every path
+        // above should leave us a MEMBER of `slug`, but `createProject` returns 409 for a
+        // project that already exists WITHOUT making us a member (the VAcontractorCo case),
+        // and that was being swallowed — so init wrote the full footprint and every later
+        // `convene fetch` 403'd into a DEGRADED block. Probe membership NOW, before any
+        // local file is written: getProject returns 403 specifically for exists-but-not-a-
+        // member. Fail loudly with nothing left behind. (status 0 = offline/timeout → fail
+        // open and proceed, matching init's fail-open ethos elsewhere.)
+        const verify = await api.getProject(slug, 8000);
+        if (verify.status === 403) {
+            (0, ctx_1.die)(`onboarding aborted: project "${slug}" exists but the server did not confirm your membership ` +
+                `(GET returned 403). No local files were written. Ask an owner to add you — or \`convene join\` ` +
+                `with a token — then re-run \`convene init\`.`);
+        }
+        if (verify.status !== 200 && verify.status !== 0) {
+            log(`⚠ could not confirm project membership (status ${verify.status}); proceeding with local setup.`);
+        }
     }
     else if (!slug) {
         (0, ctx_1.die)('--offline requires --slug (or an existing .convene/project.json)');
@@ -582,6 +741,28 @@ async function init(opts) {
     }
     // 8. memory seed (best-effort, outside the repo)
     seedMemory(top, slug, baseUrl);
+    // 8-bis. best-practices (Phase 2). Resolve selections from flags; else prompt
+    //   interactively at a real TTY; else (non-TTY / no flags) skip. CRITICAL
+    //   INVARIANT: when `selections` is empty NOTHING is written — no manifest, no
+    //   .convene/best-practices.md, no ref region — so a plain non-interactive init
+    //   stays byte-identical to its pre-catalog output (init.test.ts passes unchanged).
+    await adoptBestPractices(top, slug, opts);
+    // 8a. optional isolated commit — stage ONLY the convene files (never `git add -A`),
+    //     so onboarding can never be bundled into unrelated work (the VAcontractorCo
+    //     entangled-commit failure). Off by default; `--commit` opts in.
+    if (opts.commit) {
+        const paths = exports.CONVENE_PATHS.filter((p) => node_fs_1.default.existsSync(node_path_1.default.join(top, p)));
+        if (paths.length && (0, git_1.gitAddPaths)(paths, top)) {
+            const res = (0, git_1.gitCommit)('Onboard onto Convene coordination bus', paths, top);
+            if (res.ok)
+                log(`✓ committed onboarding as one isolated commit${res.sha ? ` (${res.sha})` : ''} — only the convene files were staged.`);
+            else
+                log('· nothing committed (no staged changes).');
+        }
+        else if (paths.length) {
+            log('⚠ could not stage the convene files — commit them manually.');
+        }
+    }
     // 9. teammate one-liner
     log('');
     log(`Done. Project "${slug}" — dashboard: ${baseUrl}/p/${slug}`);