ctxr-cli 0.8.0 → 0.10.0

package/dist/core/version-check.d.ts

@@ -0,0 +1,63 @@
+import type { RunEnv } from './env.js';
+import type { Finding } from './envelope.js';
+import type { Store } from './store.js';
+/**
+ * The release comparison behind `ctxr version --check` and the session-start /
+ * update advisory (cli-contract: an explicit release check reports its answer
+ * through the exit code).
+ *
+ * Hand-rolled over the plain three-part shape rather than taking a semver
+ * dependency (design.md D7): every published release is X.Y.Z with no
+ * prerelease or build metadata, and a comparison that handles exactly that and
+ * REFUSES anything else fails in the right direction. An unrecognized version
+ * is reported as undeterminable and named — the fail-loud contract applied to
+ * parsing — never compared by guesswork, and never quietly treated as "current".
+ */
+export type ReleaseComparison = {
+    readonly kind: 'current';
+} | {
+    readonly kind: 'newer-available';
+    readonly installed: string;
+    readonly latest: string;
+} | {
+    readonly kind: 'undetermined';
+    readonly reason: string;
+};
+/** Parses a plain X.Y.Z version. Returns undefined for anything else — including
+ *  a prerelease, build metadata, a `v` prefix, or a leading/trailing space. */
+export declare function parseVersion(version: string): [number, number, number] | undefined;
+/**
+ * An installed version AHEAD of the published one is 'current', not an error:
+ * that is exactly what a maintainer running an unreleased build sees, and it
+ * is not a condition to nag them about.
+ */
+export declare function compareRelease(installed: string, latest: string): ReleaseComparison;
+/**
+ * Store-local, under the derived-cache subpath that is already gitignored and
+ * already declared in `derived.paths` — so it needs no new plumbing and never
+ * rides review. Deliberately NOT ~/.cache: that would be the first thing this
+ * codebase writes outside a store root, and under the integration tests'
+ * hermetic HOME it would write to a nonexistent path and silently do nothing
+ * (design.md D6).
+ */
+export declare function updateCheckCachePath(store: Store): string;
+/** The environment variable that suppresses the check for one invocation. */
+export declare const UPDATE_CHECK_ENV_VAR = "CONTEXTURE_UPDATE_CHECK";
+export interface UpdateAdvisory {
+    findings: Finding[];
+    /** The stderr line, when there is one to print. */
+    notice?: string;
+}
+/**
+ * cli-contract: an advisory about a newer release never changes the outcome of
+ * the command carrying it.
+ *
+ * This function has NO throwing path, and that is a requirement rather than an
+ * intention (design.md D5). Session start creates a git worktree BEFORE this
+ * runs, and runCommand maps any escaping error to the internal-error code — so
+ * an unhandled rejection here would report a failed session that had in fact
+ * succeeded, leaving an orphan worktree behind. Every failure below becomes a
+ * finding.
+ */
+export declare function updateAdvisory(env: RunEnv, store: Store): Promise<UpdateAdvisory>;
+//# sourceMappingURL=version-check.d.ts.map

package/dist/core/version-check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version-check.d.ts","sourceRoot":"","sources":["../../src/core/version-check.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AACvC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAG7C,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAGxC;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,iBAAiB,GACzB;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;CAAE,GAC5B;IAAE,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACzF;IAAE,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAI/D;+EAC+E;AAC/E,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAQlF;AAWD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,iBAAiB,CAanF;AAQD;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,CAEzD;AAED,6EAA6E;AAC7E,eAAO,MAAM,oBAAoB,4BAA4B,CAAC;AA0D9D,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,mDAAmD;IACnD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAiBD;;;;;;;;;;GAUG;AACH,wBAAsB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,cAAc,CAAC,CAoCvF"}

package/dist/core/version-check.js

@@ -0,0 +1,181 @@
+import { mkdir, readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { SHIPPED_DEFAULTS } from '../config/defaults.js';
+import { writeFileAtomic } from './fs/atomic.js';
+import { ownPackageName } from './registry.js';
+import { CLI_VERSION } from '../version.js';
+const THREE_PART = /^(\d+)\.(\d+)\.(\d+)$/;
+/** Parses a plain X.Y.Z version. Returns undefined for anything else — including
+ *  a prerelease, build metadata, a `v` prefix, or a leading/trailing space. */
+export function parseVersion(version) {
+    const match = THREE_PART.exec(version);
+    if (!match)
+        return undefined;
+    const parts = [match[1], match[2], match[3]].map((part) => Number(part));
+    // Number() on a digits-only string cannot be NaN, but it can exceed the safe
+    // integer range on absurd input; refuse rather than compare imprecisely.
+    if (parts.some((part) => !Number.isSafeInteger(part)))
+        return undefined;
+    return [parts[0], parts[1], parts[2]];
+}
+/** Numeric, component-wise. Returns a negative number when `a` precedes `b`. */
+function compareParsed(a, b) {
+    for (let i = 0; i < 3; i += 1) {
+        const diff = a[i] - b[i];
+        if (diff !== 0)
+            return diff;
+    }
+    return 0;
+}
+/**
+ * An installed version AHEAD of the published one is 'current', not an error:
+ * that is exactly what a maintainer running an unreleased build sees, and it
+ * is not a condition to nag them about.
+ */
+export function compareRelease(installed, latest) {
+    const installedParts = parseVersion(installed);
+    if (!installedParts) {
+        return { kind: 'undetermined', reason: `the installed version "${installed}" is not a X.Y.Z version` };
+    }
+    const latestParts = parseVersion(latest);
+    if (!latestParts) {
+        return { kind: 'undetermined', reason: `the published version "${latest}" is not a X.Y.Z version` };
+    }
+    if (compareParsed(installedParts, latestParts) < 0) {
+        return { kind: 'newer-available', installed, latest };
+    }
+    return { kind: 'current' };
+}
+// ---------------------------------------------------------------------------
+// The advisory: the cached, never-throwing path used by session start and
+// update. `ctxr version --check` deliberately does NOT come through here — an
+// operator asking explicitly is asking about now, not about the last answer.
+// ---------------------------------------------------------------------------
+/**
+ * Store-local, under the derived-cache subpath that is already gitignored and
+ * already declared in `derived.paths` — so it needs no new plumbing and never
+ * rides review. Deliberately NOT ~/.cache: that would be the first thing this
+ * codebase writes outside a store root, and under the integration tests'
+ * hermetic HOME it would write to a nonexistent path and silently do nothing
+ * (design.md D6).
+ */
+export function updateCheckCachePath(store) {
+    return path.join(store.root, '.contexture', 'cache', 'update-check.json');
+}
+/** The environment variable that suppresses the check for one invocation. */
+export const UPDATE_CHECK_ENV_VAR = 'CONTEXTURE_UPDATE_CHECK';
+function isFresh(entry, now, ttlHours) {
+    const checkedAt = Date.parse(entry.checked_at);
+    if (!Number.isFinite(checkedAt))
+        return false;
+    const ageMs = now.getTime() - checkedAt;
+    // A cache stamped in the future is not fresh — a clock that moved backwards
+    // must not pin the answer forever.
+    return ageMs >= 0 && ageMs < ttlHours * 60 * 60 * 1000;
+}
+async function readCache(store, now, ttlHours) {
+    try {
+        const raw = await readFile(updateCheckCachePath(store), 'utf8');
+        const entry = JSON.parse(raw);
+        if (typeof entry.latest !== 'string' || typeof entry.checked_at !== 'string')
+            return undefined;
+        return isFresh(entry, now, ttlHours) ? entry.latest : undefined;
+    }
+    catch {
+        // Missing, unreadable, or corrupt are all a miss — never an error. The
+        // cache is an optimization; failing on it would let a stray byte on disk
+        // fail a session.
+        return undefined;
+    }
+}
+async function writeCache(store, now, latest) {
+    try {
+        const filePath = updateCheckCachePath(store);
+        await mkdir(path.dirname(filePath), { recursive: true });
+        const entry = { checked_at: now.toISOString(), latest };
+        await writeFileAtomic(filePath, `${JSON.stringify(entry, null, 2)}\n`);
+    }
+    catch {
+        // An unwritable cache costs one extra request next time. It is not a
+        // reason to fail the command that was carrying the advisory.
+    }
+}
+/** Reads the effective settings, falling back to the shipped defaults for a config that predates the block. */
+function updateCheckSettings(store) {
+    const configured = store.config.update_check;
+    return {
+        enabled: configured?.enabled ?? SHIPPED_DEFAULTS.update_check.enabled,
+        ttlHours: configured?.ttl_hours ?? SHIPPED_DEFAULTS.update_check.ttl_hours,
+    };
+}
+/** Any explicit falsey spelling turns the check off for this invocation. */
+function suppressedByEnv(env) {
+    const raw = env.env[UPDATE_CHECK_ENV_VAR];
+    if (raw === undefined)
+        return false;
+    return ['0', 'false', 'no', 'off', ''].includes(raw.trim().toLowerCase());
+}
+const NO_ADVISORY = { findings: [] };
+function checkFailed(reason) {
+    return {
+        findings: [
+            {
+                code: 'cli.update_check_failed',
+                severity: 'info',
+                message: `the release check could not be completed: ${reason}`,
+                subject: ownPackageName(),
+            },
+        ],
+    };
+}
+/**
+ * cli-contract: an advisory about a newer release never changes the outcome of
+ * the command carrying it.
+ *
+ * This function has NO throwing path, and that is a requirement rather than an
+ * intention (design.md D5). Session start creates a git worktree BEFORE this
+ * runs, and runCommand maps any escaping error to the internal-error code — so
+ * an unhandled rejection here would report a failed session that had in fact
+ * succeeded, leaving an orphan worktree behind. Every failure below becomes a
+ * finding.
+ */
+export async function updateAdvisory(env, store) {
+    try {
+        const { enabled, ttlHours } = updateCheckSettings(store);
+        if (!enabled || suppressedByEnv(env))
+            return NO_ADVISORY;
+        const now = env.now();
+        let latest = await readCache(store, now, ttlHours);
+        if (latest === undefined) {
+            const lookup = await env.registry.latestVersion(ownPackageName());
+            if (lookup.kind === 'undetermined')
+                return checkFailed(lookup.reason);
+            latest = lookup.version;
+            await writeCache(store, now, latest);
+        }
+        const comparison = compareRelease(CLI_VERSION, latest);
+        if (comparison.kind === 'undetermined')
+            return checkFailed(comparison.reason);
+        if (comparison.kind === 'current')
+            return NO_ADVISORY;
+        const message = `ctxr ${comparison.installed} is installed; ${comparison.latest} is available.`;
+        return {
+            findings: [
+                {
+                    code: 'cli.update_available',
+                    severity: 'info',
+                    message,
+                    subject: ownPackageName(),
+                    details: { installed: comparison.installed, latest: comparison.latest },
+                },
+            ],
+            notice: `${message} Run the ctxr-upgrade skill to upgrade.`,
+        };
+    }
+    catch (err) {
+        // The backstop for anything the branches above did not anticipate. Reaching
+        // it is a bug, but reaching it must still not fail the caller's command.
+        return checkFailed(err instanceof Error ? err.message : String(err));
+    }
+}
+//# sourceMappingURL=version-check.js.map

package/dist/core/version-check.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version-check.js","sourceRoot":"","sources":["../../src/core/version-check.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAGzD,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAE/C,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAmB5C,MAAM,UAAU,GAAG,uBAAuB,CAAC;AAE3C;+EAC+E;AAC/E,MAAM,UAAU,YAAY,CAAC,OAAe;IAC1C,MAAM,KAAK,GAAG,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACvC,IAAI,CAAC,KAAK;QAAE,OAAO,SAAS,CAAC;IAC7B,MAAM,KAAK,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;IACzE,6EAA6E;IAC7E,yEAAyE;IACzE,IAAI,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC;QAAE,OAAO,SAAS,CAAC;IACxE,OAAO,CAAC,KAAK,CAAC,CAAC,CAAW,EAAE,KAAK,CAAC,CAAC,CAAW,EAAE,KAAK,CAAC,CAAC,CAAW,CAAC,CAAC;AACtE,CAAC;AAED,gFAAgF;AAChF,SAAS,aAAa,CAAC,CAAoC,EAAE,CAAoC;IAC/F,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;QAC9B,MAAM,IAAI,GAAI,CAAC,CAAC,CAAC,CAAY,GAAI,CAAC,CAAC,CAAC,CAAY,CAAC;QACjD,IAAI,IAAI,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC;IAC9B,CAAC;IACD,OAAO,CAAC,CAAC;AACX,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,SAAiB,EAAE,MAAc;IAC9D,MAAM,cAAc,GAAG,YAAY,CAAC,SAAS,CAAC,CAAC;IAC/C,IAAI,CAAC,cAAc,EAAE,CAAC;QACpB,OAAO,EAAE,IAAI,EAAE,cAAc,EAAE,MAAM,EAAE,0BAA0B,SAAS,0BAA0B,EAAE,CAAC;IACzG,CAAC;IACD,MAAM,WAAW,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC;IACzC,IAAI,CAAC,WAAW,EAAE,CAAC;QACjB,OAAO,EAAE,IAAI,EAAE,cAAc,EAAE,MAAM,EAAE,0BAA0B,MAAM,0BAA0B,EAAE,CAAC;IACtG,CAAC;IACD,IAAI,aAAa,CAAC,cAAc,EAAE,WAAW,CAAC,GAAG,CAAC,EAAE,CAAC;QACnD,OAAO,EAAE,IAAI,EAAE,iBAAiB,EAAE,SAAS,EAAE,MAAM,EAAE,CAAC;IACxD,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;AAC7B,CAAC;AAED,8EAA8E;AAC9E,0EAA0E;AAC1E,8EAA8E;AAC9E,6EAA6E;AAC7E,8EAA8E;AAE9E;;;;;;;GAOG;AACH,MAAM,UAAU,oBAAoB,CAAC,KAAY;IAC/C,OAAO,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,aAAa,EAAE,OAAO,EAAE,mBAAmB,CAAC,CAAC;AAC5E,CAAC;AAED,6EAA6E;AAC7E,MAAM,CAAC,MAAM,oBAAoB,GAAG,yBAAyB,CAAC;AAO9D,SAAS,OAAO,CAAC,KAAiB,EAAE,GAAS,EAAE,QAAgB;IAC7D,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;IAC/C,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC;QAAE,OAAO,KAAK,CAAC;IAC9C,MAAM,KAAK,GAAG,GAAG,CAAC,OAAO,EAAE,GAAG,SAAS,CAAC;IACxC,4EAA4E;IAC5E,mCAAmC;IACnC,OAAO,KAAK,IAAI,CAAC,IAAI,KAAK,GAAG,QAAQ,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AACzD,CAAC;AAED,KAAK,UAAU,SAAS,CAAC,KAAY,EAAE,GAAS,EAAE,QAAgB;IAChE,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAC,oBAAoB,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC,CAAC;QAChE,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAwB,CAAC;QACrD,IAAI,OAAO,KAAK,CAAC,MAAM,KAAK,QAAQ,IAAI,OAAO,KAAK,CAAC,UAAU,KAAK,QAAQ;YAAE,OAAO,SAAS,CAAC;QAC/F,OAAO,OAAO,CAAC,KAAmB,EAAE,GAAG,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC;IAChF,CAAC;IAAC,MAAM,CAAC;QACP,uEAAuE;QACvE,yEAAyE;QACzE,kBAAkB;QAClB,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED,KAAK,UAAU,UAAU,CAAC,KAAY,EAAE,GAAS,EAAE,MAAc;IAC/D,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,oBAAoB,CAAC,KAAK,CAAC,CAAC;QAC7C,MAAM,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QACzD,MAAM,KAAK,GAAe,EAAE,UAAU,EAAE,GAAG,CAAC,WAAW,EAAE,EAAE,MAAM,EAAE,CAAC;QACpE,MAAM,eAAe,CAAC,QAAQ,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;IACzE,CAAC;IAAC,MAAM,CAAC;QACP,qEAAqE;QACrE,6DAA6D;IAC/D,CAAC;AACH,CAAC;AAED,+GAA+G;AAC/G,SAAS,mBAAmB,CAAC,KAAY;IACvC,MAAM,UAAU,GAAI,KAAK,CAAC,MAAuE,CAAC,YAAY,CAAC;IAC/G,OAAO;QACL,OAAO,EAAE,UAAU,EAAE,OAAO,IAAI,gBAAgB,CAAC,YAAY,CAAC,OAAO;QACrE,QAAQ,EAAE,UAAU,EAAE,SAAS,IAAI,gBAAgB,CAAC,YAAY,CAAC,SAAS;KAC3E,CAAC;AACJ,CAAC;AAED,4EAA4E;AAC5E,SAAS,eAAe,CAAC,GAAW;IAClC,MAAM,GAAG,GAAG,GAAG,CAAC,GAAG,CAAC,oBAAoB,CAAC,CAAC;IAC1C,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IACpC,OAAO,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,CAAC;AAC5E,CAAC;AAQD,MAAM,WAAW,GAAmB,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC;AAErD,SAAS,WAAW,CAAC,MAAc;IACjC,OAAO;QACL,QAAQ,EAAE;YACR;gBACE,IAAI,EAAE,yBAAyB;gBAC/B,QAAQ,EAAE,MAAM;gBAChB,OAAO,EAAE,6CAA6C,MAAM,EAAE;gBAC9D,OAAO,EAAE,cAAc,EAAE;aAC1B;SACF;KACF,CAAC;AACJ,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,GAAW,EAAE,KAAY;IAC5D,IAAI,CAAC;QACH,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,GAAG,mBAAmB,CAAC,KAAK,CAAC,CAAC;QACzD,IAAI,CAAC,OAAO,IAAI,eAAe,CAAC,GAAG,CAAC;YAAE,OAAO,WAAW,CAAC;QAEzD,MAAM,GAAG,GAAG,GAAG,CAAC,GAAG,EAAE,CAAC;QACtB,IAAI,MAAM,GAAG,MAAM,SAAS,CAAC,KAAK,EAAE,GAAG,EAAE,QAAQ,CAAC,CAAC;QACnD,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YACzB,MAAM,MAAM,GAAG,MAAM,GAAG,CAAC,QAAQ,CAAC,aAAa,CAAC,cAAc,EAAE,CAAC,CAAC;YAClE,IAAI,MAAM,CAAC,IAAI,KAAK,cAAc;gBAAE,OAAO,WAAW,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;YACtE,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC;YACxB,MAAM,UAAU,CAAC,KAAK,EAAE,GAAG,EAAE,MAAM,CAAC,CAAC;QACvC,CAAC;QAED,MAAM,UAAU,GAAG,cAAc,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC;QACvD,IAAI,UAAU,CAAC,IAAI,KAAK,cAAc;YAAE,OAAO,WAAW,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;QAC9E,IAAI,UAAU,CAAC,IAAI,KAAK,SAAS;YAAE,OAAO,WAAW,CAAC;QAEtD,MAAM,OAAO,GAAG,QAAQ,UAAU,CAAC,SAAS,kBAAkB,UAAU,CAAC,MAAM,gBAAgB,CAAC;QAChG,OAAO;YACL,QAAQ,EAAE;gBACR;oBACE,IAAI,EAAE,sBAAsB;oBAC5B,QAAQ,EAAE,MAAM;oBAChB,OAAO;oBACP,OAAO,EAAE,cAAc,EAAE;oBACzB,OAAO,EAAE,EAAE,SAAS,EAAE,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,CAAC,MAAM,EAAE;iBACxE;aACF;YACD,MAAM,EAAE,GAAG,OAAO,yCAAyC;SAC5D,CAAC;IACJ,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,4EAA4E;QAC5E,yEAAyE;QACzE,OAAO,WAAW,CAAC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;IACvE,CAAC;AACH,CAAC"}

package/dist/core/write-lifecycle/path-gate.d.ts

@@ -13,8 +13,8 @@ export interface PathGateResult {
  * directory's symlinks are followed. The sanctioned-location rule is
  * opt-in — with `write_lifecycle.writable_paths` empty (the default),
  * every in-store path is accepted; once any path is declared, only a
- * configured taxonomy layer, the inbox, a declared writable path, or a
- * contexture-owned location passes.
+ * configured taxonomy layer, the capture tier, a declared writable path, or
+ * a contexture-owned location passes.
  */
 export declare function sanctionedPath(config: StoreConfig, root: string, relativePath: string): Promise<PathGateResult>;
 export interface WriteScopeResult {

package/dist/core/write-lifecycle/path-gate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"path-gate.d.ts","sourceRoot":"","sources":["../../../src/core/write-lifecycle/path-gate.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAG1D,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAsFD;;;;;;;;;;;;GAYG;AACH,wBAAsB,cAAc,CAAC,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAqBrH;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,cAAc,CAAC,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAqBvH"}
+{"version":3,"file":"path-gate.d.ts","sourceRoot":"","sources":["../../../src/core/write-lifecycle/path-gate.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAI1D,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAmFD;;;;;;;;;;;;GAYG;AACH,wBAAsB,cAAc,CAAC,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAsBrH;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,cAAc,CAAC,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAqBvH"}

package/dist/core/write-lifecycle/path-gate.js

@@ -2,6 +2,7 @@ import { existsSync } from 'node:fs';
 import { realpath } from 'node:fs/promises';
 import path from 'node:path';
 import { configuredAdapters } from '../../adapters/registry.js';
+import { isUnderAnyPrefix } from '../fs/prefix.js';
 import { isLinkedWorktreeRoot } from '../git/repo.js';
 function normalizePrefix(prefix) {
     return prefix.replace(/\/+$/, '');
@@ -33,12 +34,6 @@ async function resolveStorePath(root, relativePath) {
     }
     return { kind: 'inside', rel };
 }
-function isUnderAnyPrefix(relativePath, prefixes) {
-    return prefixes.some((prefix) => {
-        const trimmed = normalizePrefix(prefix);
-        return relativePath === trimmed || relativePath.startsWith(`${trimmed}/`);
-    });
-}
 /**
  * session-capture-command spec (D5): locations contexture itself owns are
  * always sanctioned, regardless of writable_paths.
@@ -67,7 +62,11 @@ function contextureOwnedPrefixes(config) {
 function sanctionedPrefixesFor(config) {
     return [
         ...config.taxonomy.layers.map((layer) => layer.path),
-        config.ingest.inbox_path,
+        // retain-captures-as-provenance: the capture ROOT, not the inbox inside
+        // it — ingest's own write moves a capture out of the inbox and into the
+        // tier's dated directory, which a store declaring writable_paths would
+        // otherwise refuse.
+        config.ingest.capture_root,
         ...config.write_lifecycle.writable_paths,
         ...contextureOwnedPrefixes(config),
     ];
@@ -82,8 +81,8 @@ function sanctionedPrefixesFor(config) {
  * directory's symlinks are followed. The sanctioned-location rule is
  * opt-in — with `write_lifecycle.writable_paths` empty (the default),
  * every in-store path is accepted; once any path is declared, only a
- * configured taxonomy layer, the inbox, a declared writable path, or a
- * contexture-owned location passes.
+ * configured taxonomy layer, the capture tier, a declared writable path, or
+ * a contexture-owned location passes.
  */
 export async function sanctionedPath(config, root, relativePath) {
     const resolution = await resolveStorePath(root, relativePath);
@@ -100,7 +99,7 @@ export async function sanctionedPath(config, root, relativePath) {
     if (!isUnderAnyPrefix(rel, sanctionedPrefixesFor(config))) {
         return {
             ok: false,
-            reason: 'is not under a configured taxonomy layer, the inbox, a declared writable path, or a contexture-owned location',
+            reason: 'is not under a configured taxonomy layer, the capture tier, a declared writable path, or a contexture-owned location',
         };
     }
     return { ok: true };

package/dist/core/write-lifecycle/path-gate.js.map

@@ -1 +1 @@
-{"version":3,"file":"path-gate.js","sourceRoot":"","sources":["../../../src/core/write-lifecycle/path-gate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAEhE,OAAO,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAOtD,SAAS,eAAe,CAAC,MAAc;IACrC,OAAO,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;AACpC,CAAC;AAaD,KAAK,UAAU,gBAAgB,CAAC,IAAY,EAAE,YAAoB;IAChE,MAAM,cAAc,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1C,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC;IAChD,MAAM,GAAG,GAAG,IAAI,CAAC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC5E,IAAI,GAAG,KAAK,EAAE,IAAI,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QAC/D,OAAO,EAAE,IAAI,EAAE,eAAe,EAAE,CAAC;IACnC,CAAC;IAED,+FAA+F;IAC/F,gGAAgG;IAChG,iEAAiE;IACjE,IAAI,QAAQ,GAAG,MAAM,CAAC;IACtB,OAAO,QAAQ,KAAK,cAAc,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC5D,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QACtC,IAAI,MAAM,KAAK,QAAQ;YAAE,MAAM;QAC/B,QAAQ,GAAG,MAAM,CAAC;IACpB,CAAC;IACD,IAAI,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;QACzB,MAAM,QAAQ,GAAG,MAAM,QAAQ,CAAC,cAAc,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,cAAc,CAAC,CAAC;QAC5E,MAAM,YAAY,GAAG,MAAM,QAAQ,CAAC,QAAQ,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,CAAC;QACpE,MAAM,UAAU,GAAG,YAAY,KAAK,QAAQ,IAAI,YAAY,CAAC,UAAU,CAAC,GAAG,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;QAClG,IAAI,CAAC,UAAU,EAAE,CAAC;YAChB,OAAO,EAAE,IAAI,EAAE,gBAAgB,EAAE,CAAC;QACpC,CAAC;IACH,CAAC;IAED,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,EAAE,CAAC;AACjC,CAAC;AAED,SAAS,gBAAgB,CAAC,YAAoB,EAAE,QAA2B;IACzE,OAAO,QAAQ,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE;QAC9B,MAAM,OAAO,GAAG,eAAe,CAAC,MAAM,CAAC,CAAC;QACxC,OAAO,YAAY,KAAK,OAAO,IAAI,YAAY,CAAC,UAAU,CAAC,GAAG,OAAO,GAAG,CAAC,CAAC;IAC5E,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;;;GAWG;AACH,SAAS,uBAAuB,CAAC,MAAmB;IAClD,MAAM,QAAQ,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,OAAO,CAAC,WAAW,EAAE,MAAM,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC;IACjG,IAAI,CAAC;QACH,KAAK,MAAM,OAAO,IAAI,kBAAkB,CAAC,MAAM,EAAE,oBAAoB,CAAC,EAAE,CAAC;YACvE,IAAI,OAAO,CAAC,aAAa,KAAK,SAAS;gBAAE,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC;QAChF,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,qGAAqG;IACvG,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,SAAS,qBAAqB,CAAC,MAAmB;IAChD,OAAO;QACL,GAAG,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC;QACpD,MAAM,CAAC,MAAM,CAAC,UAAU;QACxB,GAAG,MAAM,CAAC,eAAe,CAAC,cAAc;QACxC,GAAG,uBAAuB,CAAC,MAAM,CAAC;KACnC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,MAAmB,EAAE,IAAY,EAAE,YAAoB;IAC1F,MAAM,UAAU,GAAG,MAAM,gBAAgB,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC;IAC9D,IAAI,UAAU,CAAC,IAAI,KAAK,eAAe,EAAE,CAAC;QACxC,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,4BAA4B,EAAE,CAAC;IAC7D,CAAC;IACD,IAAI,UAAU,CAAC,IAAI,KAAK,gBAAgB,EAAE,CAAC;QACzC,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,2CAA2C,EAAE,CAAC;IAC5E,CAAC;IACD,MAAM,EAAE,GAAG,EAAE,GAAG,UAAU,CAAC;IAE3B,IAAI,MAAM,CAAC,eAAe,CAAC,cAAc,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;IACtB,CAAC;IAED,IAAI,CAAC,gBAAgB,CAAC,GAAG,EAAE,qBAAqB,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC;QAC1D,OAAO;YACL,EAAE,EAAE,KAAK;YACT,MAAM,EAAE,+GAA+G;SACxH,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;AACtB,CAAC;AAOD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,MAAmB,EAAE,IAAY,EAAE,YAAoB;IAC1F,MAAM,UAAU,GAAG,MAAM,gBAAgB,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC;IAC9D,IAAI,UAAU,CAAC,IAAI,KAAK,eAAe,EAAE,CAAC;QACxC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IAC3B,CAAC;IACD,IAAI,UAAU,CAAC,IAAI,KAAK,gBAAgB,EAAE,CAAC;QACzC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,2CAA2C,EAAE,CAAC;IACjF,CAAC;IAED,MAAM,eAAe,GAAG,eAAe,CAAC,MAAM,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC;IACvE,MAAM,EAAE,GAAG,EAAE,GAAG,UAAU,CAAC;IAC3B,IAAI,GAAG,KAAK,eAAe,IAAI,GAAG,CAAC,UAAU,CAAC,GAAG,eAAe,GAAG,CAAC,EAAE,CAAC;QACrE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IAC3B,CAAC;IACD,IAAI,oBAAoB,CAAC,IAAI,CAAC,EAAE,CAAC;QAC/B,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IAC3B,CAAC;IACD,OAAO;QACL,OAAO,EAAE,KAAK;QACd,MAAM,EAAE,4BAA4B,GAAG,4CAA4C,MAAM,CAAC,OAAO,CAAC,cAAc,IAAI;KACrH,CAAC;AACJ,CAAC"}
+{"version":3,"file":"path-gate.js","sourceRoot":"","sources":["../../../src/core/write-lifecycle/path-gate.ts"],"names":[],"mappings":"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"}

package/dist/run.d.ts

@@ -6,11 +6,6 @@ import { ExitCode } from './core/exit-codes.js';
  * automatically gets json-envelope-conformance coverage the moment it's
  * added here.
  */
-export declare const COMMAND_NAMES: readonly ['init', 'doctor'];
-/**
- * The one testable seam for the whole CLI: given argv and an injected
- * RunEnv, returns the exit code it would have produced — no process-global
- * mutation, no real subprocess required for a unit test.
- */
+export declare const COMMAND_NAMES: readonly ['init', 'doctor', 'version'];
 export declare function run(argv: readonly string[], env: RunEnv): Promise<ExitCode>;
 //# sourceMappingURL=run.d.ts.map

package/dist/run.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../src/run.ts"],"names":[],"mappings":"AAgCA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAE5C,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAOhD;;;;;GAKG;AACH,eAAO,MAAM,aAAa,YAAI,MAAM,EAAE,QAAQ,CAAU,CAAC;AAiFzD;;;;GAIG;AACH,wBAAsB,GAAG,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,CA2ejF"}
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../src/run.ts"],"names":[],"mappings":"AAgCA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAE5C,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAQhD;;;;;GAKG;AACH,eAAO,MAAM,aAAa,YAAI,MAAM,EAAE,QAAQ,EAAE,SAAS,CAAU,CAAC;AA+GpE,wBAAsB,GAAG,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,CAghBjF"}

package/dist/run.js

@@ -8,7 +8,7 @@ import * as archiveCommand from './commands/archive.js';
 import * as doctorCommand from './commands/doctor.js';
 import * as ingestCommand from './commands/ingest.js';
 import * as lintCommand from './commands/lint.js';
-import * as migrateCommand from './commands/migrate.js';
+import * as contextGatherCommand from './commands/context-gather.js';
 import * as graphBuildCommand from './commands/graph-build.js';
 import * as entryAppendCommand from './commands/entry-append.js';
 import * as graphQueryCommand from './commands/graph-query.js';
@@ -34,6 +34,7 @@ import { createReporter } from './core/reporter.js';
 import { openStore } from './core/store.js';
 import * as updateCommand from './commands/update.js';
 import * as verifyCommand from './commands/verify.js';
+import * as versionCommand from './commands/version.js';
 import { CLI_VERSION } from './version.js';
 /**
  * Every registered top-level command name (excluding subcommand groups like
@@ -41,7 +42,7 @@ import { CLI_VERSION } from './version.js';
  * automatically gets json-envelope-conformance coverage the moment it's
  * added here.
  */
-export const COMMAND_NAMES = ['init', 'doctor'];
+export const COMMAND_NAMES = ['init', 'doctor', 'version'];
 function isCommanderError(err) {
     return typeof err === 'object' && err !== null && 'code' in err && typeof err.code === 'string';
 }
@@ -72,6 +73,8 @@ async function runCommand(commandName, env, jsonMode, body) {
             data: outcome.data,
             exitCode: outcome.exitCode,
         });
+        for (const notice of outcome.notices ?? [])
+            reporter.warn(notice);
         reporter.emitResult(envelope, outcome.humanSummary);
         return outcome.exitCode;
     }
@@ -109,7 +112,34 @@ async function runCommand(commandName, env, jsonMode, body) {
  * RunEnv, returns the exit code it would have produced — no process-global
  * mutation, no real subprocess required for a unit test.
  */
+/**
+ * commander's own `.version()` writes through configureOutput's writeOut, which
+ * this program routes to stderr so parser chatter can never contaminate --json
+ * stdout. That is the one place a version query must NOT go, so the flag is
+ * recognized ahead of parsing and dispatched to the same command path as the
+ * subcommand (design.md D8) — one envelope, on stdout, and the two cannot drift.
+ *
+ * Only a bare global query is intercepted: a version flag alongside anything
+ * other than the global output flags falls through to commander, which reports
+ * it as the usage error it is.
+ */
+const VERSION_FLAGS = new Set(['--version', '-V']);
+const GLOBAL_PASSTHROUGH_FLAGS = new Set(['--json', '--no-input']);
+function isGlobalVersionRequest(argv) {
+    if (!argv.some((arg) => VERSION_FLAGS.has(arg)))
+        return false;
+    return argv.every((arg) => VERSION_FLAGS.has(arg) || GLOBAL_PASSTHROUGH_FLAGS.has(arg));
+}
+/** Accumulates a repeatable option's values — commander keeps only the last without it. */
+function collect(value, previous) {
+    return [...previous, value];
+}
 export async function run(argv, env) {
+    if (isGlobalVersionRequest(argv)) {
+        const jsonMode = argv.includes('--json');
+        const runEnv = { ...env, noInput: env.noInput || argv.includes('--no-input') || jsonMode };
+        return runCommand('version', runEnv, jsonMode, () => versionCommand.execute(runEnv));
+    }
     const program = new Command();
     program
         .name('ctxr')
@@ -118,7 +148,7 @@ export async function run(argv, env) {
         writeOut: (str) => env.io.stderr.write(str),
         writeErr: (str) => env.io.stderr.write(str),
     })
-        .option('--root <path>', 'store root (overrides CONTEXTURE_ROOT)')
+        .option('--root <path>', 'store root (overrides CONTEXTURE_STORE_ROOT)')
         .option('--json', 'emit machine-readable output')
         .option('--no-input', 'never prompt; fail loud instead of blocking');
     let result = ExitCode.Ok;
@@ -189,6 +219,34 @@ export async function run(argv, env) {
             return catalogShowCommand.execute(store, { section: cmdOpts.section });
         });
     });
+    const contextCommand = program.command('context').description('the retrieval pass over the store');
+    contextCommand
+        .command('gather')
+        .description('expand entry selectors through the built graph into a gloss-annotated, ordered candidate set — no query, no ranking')
+        .option('--seed <path>', 'a note already in hand (repeatable)', collect, [])
+        .option('--section <id>', 'every note a catalog section lists (repeatable)', collect, [])
+        .option('--under <prefix>', 'every retrievable note under this path prefix (repeatable)', collect, [])
+        .option('--entity <name>', 'every note linking to this entity (same enumeration as rollup gather; repeatable)', collect, [])
+        .option('--hops <n>', 'how many graph hops to expand from the entry set', (v) => Number.parseInt(v, 10), 1)
+        .option('--direction <dir>', 'expand along in, out, or both edge directions', 'both')
+        .option('--type <name>', 'expand only along edges of one configured relation')
+        .option('--max-notes <n>', 'cap the returned set; truncation is reported, never silent', (v) => Number.parseInt(v, 10))
+        .action(async (cmdOpts, cmd) => {
+        const { runEnv, jsonMode, root } = deriveRunEnv(env, cmd);
+        result = await runCommand('context.gather', runEnv, jsonMode, async () => {
+            const store = await openStore(runEnv, { root });
+            return contextGatherCommand.execute(store, {
+                seed: cmdOpts.seed,
+                section: cmdOpts.section,
+                under: cmdOpts.under,
+                entity: cmdOpts.entity,
+                hops: cmdOpts.hops,
+                direction: cmdOpts.direction,
+                type: cmdOpts.type,
+                maxNotes: cmdOpts.maxNotes,
+            });
+        });
+    });
     const graphCommand = program.command('graph').description('the wikilink graph derived from the store');
     graphCommand
         .command('build')
@@ -284,15 +342,17 @@ export async function run(argv, env) {
     });
     program
         .command('ingest <path>')
-        .description('stamp source-identity fields onto an inbox file, turning it into a note')
+        .description('retain a capture with its source identity, and cite it from the note it informed')
+        .requiredOption('--into <note>', 'the note this material informed — new or existing; ingest never creates it')
         .requiredOption('--source-type <type>', 'the kind of source this material came from')
         .requiredOption('--source-id <id>', 'a stable identifier for this specific source')
-        .action(async (notePath, cmdOpts, cmd) => {
+        .action(async (capturePath, cmdOpts, cmd) => {
         const { runEnv, jsonMode, root } = deriveRunEnv(env, cmd);
         result = await runCommand('ingest', runEnv, jsonMode, async () => {
             const store = await openStore(runEnv, { root });
             return ingestCommand.execute(runEnv, store, {
-                path: notePath,
+                path: capturePath,
+                into: cmdOpts.into,
                 sourceType: cmdOpts.sourceType,
                 sourceId: cmdOpts.sourceId,
             });
@@ -467,6 +527,14 @@ export async function run(argv, env) {
             return serveCommand.execute(runEnv, store, { port: cmdOpts.port, host: cmdOpts.host });
         });
     });
+    program
+        .command('version')
+        .description("report the installed ctxr version, where it is installed from, and (with --check) whether a newer release is published")
+        .option('--check', 'resolve the latest published release and compare it against the installed one')
+        .action(async (cmdOpts, cmd) => {
+        const { runEnv, jsonMode } = deriveRunEnv(env, cmd);
+        result = await runCommand('version', runEnv, jsonMode, () => versionCommand.execute(runEnv, { check: cmdOpts.check }));
+    });
     program
         .command('update')
         .description('bring every contexture-owned file in the store up to the installed version (docs, skills, hooks, adapter outputs)')
@@ -480,23 +548,12 @@ export async function run(argv, env) {
     program
         .command('verify')
         .description('exercise core store operations end to end, from an environment with no harness-specific state')
-        .option('--portable', 'the portability test: a retrieval query, a derived-artifact build, and following one skill')
+        .option('--portable', "verify the store's recorded commit in a disposable checkout, in a child process with no harness state reachable")
         .action(async (cmdOpts, cmd) => {
         const { runEnv, jsonMode, root } = deriveRunEnv(env, cmd);
         result = await runCommand('verify', runEnv, jsonMode, async () => {
             const store = await openStore(runEnv, { root });
-            return verifyCommand.execute(store, { portable: cmdOpts.portable });
-        });
-    });
-    program
-        .command('migrate')
-        .description('apply every pending schema migration, bringing the store up to the current schema_version')
-        .option('--dry-run', 'report the exact changes each pending migration would make, without applying them')
-        .action(async (cmdOpts, cmd) => {
-        const { runEnv, jsonMode, root } = deriveRunEnv(env, cmd);
-        result = await runCommand('migrate', runEnv, jsonMode, async () => {
-            const store = await openStore(runEnv, { root });
-            return migrateCommand.execute(store, { dryRun: cmdOpts.dryRun });
+            return verifyCommand.execute(runEnv, store, { portable: cmdOpts.portable });
         });
     });
     const sessionCommand = program.command('session').description('manage session worktrees');