@ekanos/cli 0.1.5 → 0.1.7

package/dist/toolchain.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"toolchain.js","sourceRoot":"","sources":["../src/toolchain.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,GAAG,EAAE,aAAa;IAClB,GAAG,EAAE,aAAa;IAClB,EAAE,EAAE,YAAY;IAChB,iBAAiB,EAAE,4BAA4B;IAC/C,OAAO,EAAE,iBAAiB;CAClB,CAAC","sourcesContent":["/**\n * The five packages that make up \"the toolchain\" — the CLI plus the four\n * packages a partner's project itself installs. `ekanos upgrade` and the\n * proactive update notice both reason about this exact set, from two\n * different angles: upgrade moves a PROJECT to a coherent target, the notice\n * tells a partner the CLI itself is behind. One shared vocabulary so the two\n * features cannot drift apart on what \"the toolchain\" even means.\n */\nexport const TOOLCHAIN_PACKAGES = {\n  cli: '@ekanos/cli',\n  sdk: '@ekanos/sdk',\n  ui: '@ekanos/ui',\n  integrationSchema: '@ekanos/integration-schema',\n  harness: '@ekanos/harness',\n} as const;\n\nexport type ToolchainKey = keyof typeof TOOLCHAIN_PACKAGES;\n\nexport type ToolchainVersions = Record<ToolchainKey, string>;\n\nexport interface ToolchainNote {\n  level: 'warn' | 'info';\n  message: string;\n}\n"]}

package/dist/update-notice.d.ts

@@ -0,0 +1,32 @@
+import type { CliContext } from './context.js';
+import type { ToolchainVersions } from './toolchain.js';
+export interface ToolchainNoticeData {
+    status: 'behind' | 'unsupported';
+    current: {
+        cli: string;
+    };
+    target: ToolchainVersions;
+    upgradeCommand: 'ekanos upgrade';
+}
+export interface CheckForUpdateParams {
+    env: Record<string, string | undefined>;
+    /** An already-resolved Fusion host/session, when the caller has one handy. */
+    host?: string;
+    session?: {
+        accessToken: string;
+    } | null;
+}
+/**
+ * Resolve whether this CLI is behind, respecting the 24h cache and the hard
+ * `EKANOS_NO_UPDATE_CHECK` opt-out. Returns null whenever there is nothing to
+ * say — current, unresolvable, or any failure along the way.
+ */
+export declare function checkForUpdate(params: CheckForUpdateParams): Promise<ToolchainNoticeData | null>;
+/**
+ * Surface a notice, if any. Human mode gets one stderr line; every mode gets
+ * the `claude-code-hint` stderr line so an agent parsing stderr for that
+ * marker sees it regardless of `--json`. NEVER writes to stdout — the JSON
+ * envelope's caller is responsible for embedding `notice` under a `toolchain`
+ * key in its own `data`, per the envelope docs in `context.ts`.
+ */
+export declare function announceUpdate(ctx: CliContext, notice: ToolchainNoticeData | null): void;

package/dist/update-notice.js

@@ -0,0 +1,180 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { CredentialStore, resolveEkanosHome } from './auth/credential-store.js';
+import { cliVersion, compareVersions } from './compatibility.js';
+import { resolveToolchainTarget } from './toolchain-resolve.js';
+/**
+ * The proactive, NEVER-mutating "your CLI is behind" notice. Runs on
+ * `validate`, `dev`, `publish` and `status` — the verbs a partner (or an
+ * agent acting for one) runs constantly — so staleness is discovered on the
+ * next ordinary command instead of only when something breaks.
+ *
+ * The one rule that governs every line of this file: this check must be
+ * INVISIBLE on failure. A partner offline, a flaky registry, a host that
+ * predates this endpoint — none of that may add meaningful latency, change a
+ * verb's exit code, or so much as touch the JSON envelope's `ok` field.
+ * Every failure path below resolves to `null` ("say nothing"), never a throw.
+ */
+const CACHE_FILENAME = 'update-check.json';
+const CACHE_DIR_MODE = 0o700;
+const CACHE_FILE_MODE = 0o600;
+const TTL_MS = 24 * 60 * 60 * 1000;
+/** The hard ceiling on this check's total network time, whatever else happens. */
+const DEADLINE_MS = 1500;
+function cachePath(env) {
+    return path.join(resolveEkanosHome(env), '.ekanos', CACHE_FILENAME);
+}
+function readCache(env) {
+    try {
+        const raw = fs.readFileSync(cachePath(env), 'utf8');
+        const parsed = JSON.parse(raw);
+        return isCacheFile(parsed) ? parsed : null;
+    }
+    catch (_a) {
+        // Missing, unreadable, or corrupt — all read as "no cache", never an
+        // error. This check is a courtesy, not a source of truth.
+        return null;
+    }
+}
+function writeCache(env, file) {
+    const target = cachePath(env);
+    try {
+        fs.mkdirSync(path.dirname(target), {
+            recursive: true,
+            mode: CACHE_DIR_MODE,
+        });
+        const tmp = `${target}.${process.pid}.tmp`;
+        fs.writeFileSync(tmp, JSON.stringify(file), { mode: CACHE_FILE_MODE });
+        fs.renameSync(tmp, target);
+    }
+    catch (_a) {
+        // Best-effort. The next run simply re-checks — this is a cache, not a
+        // durable record.
+    }
+}
+function isCacheFile(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const candidate = value;
+    return (typeof candidate.checkedAt === 'number' &&
+        typeof candidate.target === 'object' &&
+        candidate.target !== null &&
+        (candidate.source === 'host' || candidate.source === 'npm'));
+}
+/**
+ * The one host/session this check will ever try, resolved WITHOUT any of the
+ * throwing machinery in `auth/session.ts` — `resolveHost` is built to demand
+ * an answer (a usage error naming the ambiguity) because a real command needs
+ * one; this check needs an answer only if one is obvious, and silence
+ * otherwise. Exactly one stored host is "obvious"; zero or several are not,
+ * and this never prompts or guesses to resolve that ambiguity — it just
+ * falls back to the npm registry, same as no session at all.
+ */
+function bestEffortHostSession(env) {
+    try {
+        const store = new CredentialStore({ home: resolveEkanosHome(env) });
+        const hosts = store.hosts();
+        if (hosts.length !== 1)
+            return null;
+        const session = store.read(hosts[0]);
+        return session ? { host: hosts[0], session } : null;
+    }
+    catch (_a) {
+        return null;
+    }
+}
+function withDeadline(promise, ms) {
+    return new Promise((resolve) => {
+        let settled = false;
+        const timer = setTimeout(() => {
+            if (!settled) {
+                settled = true;
+                resolve(null);
+            }
+        }, ms);
+        // A rejection is a failure like any other here — resolve to null rather
+        // than letting it become an unhandled rejection.
+        promise.then((value) => {
+            if (!settled) {
+                settled = true;
+                clearTimeout(timer);
+                resolve(value);
+            }
+        }, () => {
+            if (!settled) {
+                settled = true;
+                clearTimeout(timer);
+                resolve(null);
+            }
+        });
+    });
+}
+/**
+ * Resolve whether this CLI is behind, respecting the 24h cache and the hard
+ * `EKANOS_NO_UPDATE_CHECK` opt-out. Returns null whenever there is nothing to
+ * say — current, unresolvable, or any failure along the way.
+ */
+export async function checkForUpdate(params) {
+    if (params.env.EKANOS_NO_UPDATE_CHECK)
+        return null;
+    const cached = readCache(params.env);
+    const now = Date.now();
+    let target;
+    let minimum;
+    if (cached && now - cached.checkedAt < TTL_MS) {
+        target = cached.target;
+        minimum = cached.minimum;
+    }
+    else {
+        const auth = params.host && params.session
+            ? { host: params.host, session: params.session }
+            : bestEffortHostSession(params.env);
+        const resolution = await withDeadline(resolveToolchainTarget({
+            host: auth === null || auth === void 0 ? void 0 : auth.host,
+            session: auth === null || auth === void 0 ? void 0 : auth.session,
+            timeoutMs: DEADLINE_MS,
+        }), DEADLINE_MS);
+        if (!resolution || resolution.status !== 'ok')
+            return null;
+        target = resolution.target;
+        minimum = resolution.source === 'host' ? resolution.minimum : undefined;
+        writeCache(params.env, {
+            checkedAt: now,
+            target,
+            minimum,
+            source: resolution.source,
+        });
+    }
+    const current = cliVersion();
+    if (compareVersions(current, target.cli) >= 0)
+        return null;
+    const status = minimum && compareVersions(current, minimum.cli) < 0
+        ? 'unsupported'
+        : 'behind';
+    return {
+        status,
+        current: { cli: current },
+        target,
+        upgradeCommand: 'ekanos upgrade',
+    };
+}
+/**
+ * Surface a notice, if any. Human mode gets one stderr line; every mode gets
+ * the `claude-code-hint` stderr line so an agent parsing stderr for that
+ * marker sees it regardless of `--json`. NEVER writes to stdout — the JSON
+ * envelope's caller is responsible for embedding `notice` under a `toolchain`
+ * key in its own `data`, per the envelope docs in `context.ts`.
+ */
+export function announceUpdate(ctx, notice) {
+    if (!notice)
+        return;
+    if (!ctx.jsonMode) {
+        ctx.warn(notice.status === 'unsupported'
+            ? `ekanos: @ekanos/cli ${notice.current.cli} is below the version ` +
+                `this host requires (${notice.target.cli}). Run "ekanos upgrade".`
+            : `ekanos: a newer @ekanos/cli is available (${notice.current.cli} ` +
+                `→ ${notice.target.cli}). Run "ekanos upgrade".`);
+    }
+    ctx.emitClaudeCodeHint({ tool: 'ekanos', toolchain: notice });
+}
+//# sourceMappingURL=update-notice.js.map

package/dist/update-notice.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"update-notice.js","sourceRoot":"","sources":["../src/update-notice.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAElC,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC7E,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAG9D,OAAO,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAE7D;;;;;;;;;;;GAWG;AAEH,MAAM,cAAc,GAAG,mBAAmB,CAAC;AAC3C,MAAM,cAAc,GAAG,KAAK,CAAC;AAC7B,MAAM,eAAe,GAAG,KAAK,CAAC;AAC9B,MAAM,MAAM,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AACnC,kFAAkF;AAClF,MAAM,WAAW,GAAG,IAAI,CAAC;AAgBzB,SAAS,SAAS,CAAC,GAAuC;IACxD,OAAO,IAAI,CAAC,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,EAAE,SAAS,EAAE,cAAc,CAAC,CAAC;AACtE,CAAC;AAED,SAAS,SAAS,CAAC,GAAuC;IACxD,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,EAAE,CAAC,YAAY,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,CAAC;QACpD,MAAM,MAAM,GAAY,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACxC,OAAO,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC;IAC7C,CAAC;IAAC,WAAM,CAAC;QACP,qEAAqE;QACrE,0DAA0D;QAC1D,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,SAAS,UAAU,CACjB,GAAuC,EACvC,IAAe;IAEf,MAAM,MAAM,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC;IAC9B,IAAI,CAAC;QACH,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE;YACjC,SAAS,EAAE,IAAI;YACf,IAAI,EAAE,cAAc;SACrB,CAAC,CAAC;QACH,MAAM,GAAG,GAAG,GAAG,MAAM,IAAI,OAAO,CAAC,GAAG,MAAM,CAAC;QAC3C,EAAE,CAAC,aAAa,CAAC,GAAG,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,EAAE,IAAI,EAAE,eAAe,EAAE,CAAC,CAAC;QACvE,EAAE,CAAC,UAAU,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;IAC7B,CAAC;IAAC,WAAM,CAAC;QACP,sEAAsE;QACtE,kBAAkB;IACpB,CAAC;AACH,CAAC;AAED,SAAS,WAAW,CAAC,KAAc;IACjC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAC9D,MAAM,SAAS,GAAG,KAA2B,CAAC;IAC9C,OAAO,CACL,OAAO,SAAS,CAAC,SAAS,KAAK,QAAQ;QACvC,OAAO,SAAS,CAAC,MAAM,KAAK,QAAQ;QACpC,SAAS,CAAC,MAAM,KAAK,IAAI;QACzB,CAAC,SAAS,CAAC,MAAM,KAAK,MAAM,IAAI,SAAS,CAAC,MAAM,KAAK,KAAK,CAAC,CAC5D,CAAC;AACJ,CAAC;AAED;;;;;;;;GAQG;AACH,SAAS,qBAAqB,CAC5B,GAAuC;IAEvC,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,IAAI,eAAe,CAAC,EAAE,IAAI,EAAE,iBAAiB,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACpE,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,EAAE,CAAC;QAC5B,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC;QACpC,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAE,CAAC,CAAC;QACtC,OAAO,OAAO,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC,CAAE,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;IACvD,CAAC;IAAC,WAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,SAAS,YAAY,CAAI,OAAmB,EAAE,EAAU;IACtD,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;QAC7B,IAAI,OAAO,GAAG,KAAK,CAAC;QACpB,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;YAC5B,IAAI,CAAC,OAAO,EAAE,CAAC;gBACb,OAAO,GAAG,IAAI,CAAC;gBACf,OAAO,CAAC,IAAI,CAAC,CAAC;YAChB,CAAC;QACH,CAAC,EAAE,EAAE,CAAC,CAAC;QACP,wEAAwE;QACxE,iDAAiD;QACjD,OAAO,CAAC,IAAI,CACV,CAAC,KAAK,EAAE,EAAE;YACR,IAAI,CAAC,OAAO,EAAE,CAAC;gBACb,OAAO,GAAG,IAAI,CAAC;gBACf,YAAY,CAAC,KAAK,CAAC,CAAC;gBACpB,OAAO,CAAC,KAAK,CAAC,CAAC;YACjB,CAAC;QACH,CAAC,EACD,GAAG,EAAE;YACH,IAAI,CAAC,OAAO,EAAE,CAAC;gBACb,OAAO,GAAG,IAAI,CAAC;gBACf,YAAY,CAAC,KAAK,CAAC,CAAC;gBACpB,OAAO,CAAC,IAAI,CAAC,CAAC;YAChB,CAAC;QACH,CAAC,CACF,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC;AASD;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,MAA4B;IAE5B,IAAI,MAAM,CAAC,GAAG,CAAC,sBAAsB;QAAE,OAAO,IAAI,CAAC;IAEnD,MAAM,MAAM,GAAG,SAAS,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACrC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAEvB,IAAI,MAAyB,CAAC;IAC9B,IAAI,OAAsC,CAAC;IAE3C,IAAI,MAAM,IAAI,GAAG,GAAG,MAAM,CAAC,SAAS,GAAG,MAAM,EAAE,CAAC;QAC9C,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;QACvB,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC;IAC3B,CAAC;SAAM,CAAC;QACN,MAAM,IAAI,GACR,MAAM,CAAC,IAAI,IAAI,MAAM,CAAC,OAAO;YAC3B,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE;YAChD,CAAC,CAAC,qBAAqB,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAExC,MAAM,UAAU,GAAG,MAAM,YAAY,CACnC,sBAAsB,CAAC;YACrB,IAAI,EAAE,IAAI,aAAJ,IAAI,uBAAJ,IAAI,CAAE,IAAI;YAChB,OAAO,EAAE,IAAI,aAAJ,IAAI,uBAAJ,IAAI,CAAE,OAAO;YACtB,SAAS,EAAE,WAAW;SACvB,CAAC,EACF,WAAW,CACZ,CAAC;QAEF,IAAI,CAAC,UAAU,IAAI,UAAU,CAAC,MAAM,KAAK,IAAI;YAAE,OAAO,IAAI,CAAC;QAE3D,MAAM,GAAG,UAAU,CAAC,MAAM,CAAC;QAC3B,OAAO,GAAG,UAAU,CAAC,MAAM,KAAK,MAAM,CAAC,CAAC,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC;QAExE,UAAU,CAAC,MAAM,CAAC,GAAG,EAAE;YACrB,SAAS,EAAE,GAAG;YACd,MAAM;YACN,OAAO;YACP,MAAM,EAAE,UAAU,CAAC,MAAM;SAC1B,CAAC,CAAC;IACL,CAAC;IAED,MAAM,OAAO,GAAG,UAAU,EAAE,CAAC;IAC7B,IAAI,eAAe,CAAC,OAAO,EAAE,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IAE3D,MAAM,MAAM,GACV,OAAO,IAAI,eAAe,CAAC,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC;QAClD,CAAC,CAAC,aAAa;QACf,CAAC,CAAC,QAAQ,CAAC;IAEf,OAAO;QACL,MAAM;QACN,OAAO,EAAE,EAAE,GAAG,EAAE,OAAO,EAAE;QACzB,MAAM;QACN,cAAc,EAAE,gBAAgB;KACjC,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAC5B,GAAe,EACf,MAAkC;IAElC,IAAI,CAAC,MAAM;QAAE,OAAO;IAEpB,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC;QAClB,GAAG,CAAC,IAAI,CACN,MAAM,CAAC,MAAM,KAAK,aAAa;YAC7B,CAAC,CAAC,uBAAuB,MAAM,CAAC,OAAO,CAAC,GAAG,wBAAwB;gBAC/D,uBAAuB,MAAM,CAAC,MAAM,CAAC,GAAG,0BAA0B;YACtE,CAAC,CAAC,6CAA6C,MAAM,CAAC,OAAO,CAAC,GAAG,GAAG;gBAChE,KAAK,MAAM,CAAC,MAAM,CAAC,GAAG,0BAA0B,CACvD,CAAC;IACJ,CAAC;IAED,GAAG,CAAC,kBAAkB,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,EAAE,CAAC,CAAC;AAChE,CAAC","sourcesContent":["import * as fs from 'node:fs';\nimport * as path from 'node:path';\n\nimport { CredentialStore, resolveEkanosHome } from './auth/credential-store';\nimport { cliVersion, compareVersions } from './compatibility';\nimport type { CliContext } from './context';\nimport type { ToolchainVersions } from './toolchain';\nimport { resolveToolchainTarget } from './toolchain-resolve';\n\n/**\n * The proactive, NEVER-mutating \"your CLI is behind\" notice. Runs on\n * `validate`, `dev`, `publish` and `status` — the verbs a partner (or an\n * agent acting for one) runs constantly — so staleness is discovered on the\n * next ordinary command instead of only when something breaks.\n *\n * The one rule that governs every line of this file: this check must be\n * INVISIBLE on failure. A partner offline, a flaky registry, a host that\n * predates this endpoint — none of that may add meaningful latency, change a\n * verb's exit code, or so much as touch the JSON envelope's `ok` field.\n * Every failure path below resolves to `null` (\"say nothing\"), never a throw.\n */\n\nconst CACHE_FILENAME = 'update-check.json';\nconst CACHE_DIR_MODE = 0o700;\nconst CACHE_FILE_MODE = 0o600;\nconst TTL_MS = 24 * 60 * 60 * 1000;\n/** The hard ceiling on this check's total network time, whatever else happens. */\nconst DEADLINE_MS = 1500;\n\nexport interface ToolchainNoticeData {\n  status: 'behind' | 'unsupported';\n  current: { cli: string };\n  target: ToolchainVersions;\n  upgradeCommand: 'ekanos upgrade';\n}\n\ninterface CacheFile {\n  checkedAt: number;\n  target: ToolchainVersions;\n  minimum?: ToolchainVersions;\n  source: 'host' | 'npm';\n}\n\nfunction cachePath(env: Record<string, string | undefined>): string {\n  return path.join(resolveEkanosHome(env), '.ekanos', CACHE_FILENAME);\n}\n\nfunction readCache(env: Record<string, string | undefined>): CacheFile | null {\n  try {\n    const raw = fs.readFileSync(cachePath(env), 'utf8');\n    const parsed: unknown = JSON.parse(raw);\n    return isCacheFile(parsed) ? parsed : null;\n  } catch {\n    // Missing, unreadable, or corrupt — all read as \"no cache\", never an\n    // error. This check is a courtesy, not a source of truth.\n    return null;\n  }\n}\n\nfunction writeCache(\n  env: Record<string, string | undefined>,\n  file: CacheFile,\n): void {\n  const target = cachePath(env);\n  try {\n    fs.mkdirSync(path.dirname(target), {\n      recursive: true,\n      mode: CACHE_DIR_MODE,\n    });\n    const tmp = `${target}.${process.pid}.tmp`;\n    fs.writeFileSync(tmp, JSON.stringify(file), { mode: CACHE_FILE_MODE });\n    fs.renameSync(tmp, target);\n  } catch {\n    // Best-effort. The next run simply re-checks — this is a cache, not a\n    // durable record.\n  }\n}\n\nfunction isCacheFile(value: unknown): value is CacheFile {\n  if (typeof value !== 'object' || value === null) return false;\n  const candidate = value as Partial<CacheFile>;\n  return (\n    typeof candidate.checkedAt === 'number' &&\n    typeof candidate.target === 'object' &&\n    candidate.target !== null &&\n    (candidate.source === 'host' || candidate.source === 'npm')\n  );\n}\n\n/**\n * The one host/session this check will ever try, resolved WITHOUT any of the\n * throwing machinery in `auth/session.ts` — `resolveHost` is built to demand\n * an answer (a usage error naming the ambiguity) because a real command needs\n * one; this check needs an answer only if one is obvious, and silence\n * otherwise. Exactly one stored host is \"obvious\"; zero or several are not,\n * and this never prompts or guesses to resolve that ambiguity — it just\n * falls back to the npm registry, same as no session at all.\n */\nfunction bestEffortHostSession(\n  env: Record<string, string | undefined>,\n): { host: string; session: { accessToken: string } } | null {\n  try {\n    const store = new CredentialStore({ home: resolveEkanosHome(env) });\n    const hosts = store.hosts();\n    if (hosts.length !== 1) return null;\n    const session = store.read(hosts[0]!);\n    return session ? { host: hosts[0]!, session } : null;\n  } catch {\n    return null;\n  }\n}\n\nfunction withDeadline<T>(promise: Promise<T>, ms: number): Promise<T | null> {\n  return new Promise((resolve) => {\n    let settled = false;\n    const timer = setTimeout(() => {\n      if (!settled) {\n        settled = true;\n        resolve(null);\n      }\n    }, ms);\n    // A rejection is a failure like any other here — resolve to null rather\n    // than letting it become an unhandled rejection.\n    promise.then(\n      (value) => {\n        if (!settled) {\n          settled = true;\n          clearTimeout(timer);\n          resolve(value);\n        }\n      },\n      () => {\n        if (!settled) {\n          settled = true;\n          clearTimeout(timer);\n          resolve(null);\n        }\n      },\n    );\n  });\n}\n\nexport interface CheckForUpdateParams {\n  env: Record<string, string | undefined>;\n  /** An already-resolved Fusion host/session, when the caller has one handy. */\n  host?: string;\n  session?: { accessToken: string } | null;\n}\n\n/**\n * Resolve whether this CLI is behind, respecting the 24h cache and the hard\n * `EKANOS_NO_UPDATE_CHECK` opt-out. Returns null whenever there is nothing to\n * say — current, unresolvable, or any failure along the way.\n */\nexport async function checkForUpdate(\n  params: CheckForUpdateParams,\n): Promise<ToolchainNoticeData | null> {\n  if (params.env.EKANOS_NO_UPDATE_CHECK) return null;\n\n  const cached = readCache(params.env);\n  const now = Date.now();\n\n  let target: ToolchainVersions;\n  let minimum: ToolchainVersions | undefined;\n\n  if (cached && now - cached.checkedAt < TTL_MS) {\n    target = cached.target;\n    minimum = cached.minimum;\n  } else {\n    const auth =\n      params.host && params.session\n        ? { host: params.host, session: params.session }\n        : bestEffortHostSession(params.env);\n\n    const resolution = await withDeadline(\n      resolveToolchainTarget({\n        host: auth?.host,\n        session: auth?.session,\n        timeoutMs: DEADLINE_MS,\n      }),\n      DEADLINE_MS,\n    );\n\n    if (!resolution || resolution.status !== 'ok') return null;\n\n    target = resolution.target;\n    minimum = resolution.source === 'host' ? resolution.minimum : undefined;\n\n    writeCache(params.env, {\n      checkedAt: now,\n      target,\n      minimum,\n      source: resolution.source,\n    });\n  }\n\n  const current = cliVersion();\n  if (compareVersions(current, target.cli) >= 0) return null;\n\n  const status =\n    minimum && compareVersions(current, minimum.cli) < 0\n      ? 'unsupported'\n      : 'behind';\n\n  return {\n    status,\n    current: { cli: current },\n    target,\n    upgradeCommand: 'ekanos upgrade',\n  };\n}\n\n/**\n * Surface a notice, if any. Human mode gets one stderr line; every mode gets\n * the `claude-code-hint` stderr line so an agent parsing stderr for that\n * marker sees it regardless of `--json`. NEVER writes to stdout — the JSON\n * envelope's caller is responsible for embedding `notice` under a `toolchain`\n * key in its own `data`, per the envelope docs in `context.ts`.\n */\nexport function announceUpdate(\n  ctx: CliContext,\n  notice: ToolchainNoticeData | null,\n): void {\n  if (!notice) return;\n\n  if (!ctx.jsonMode) {\n    ctx.warn(\n      notice.status === 'unsupported'\n        ? `ekanos: @ekanos/cli ${notice.current.cli} is below the version ` +\n            `this host requires (${notice.target.cli}). Run \"ekanos upgrade\".`\n        : `ekanos: a newer @ekanos/cli is available (${notice.current.cli} ` +\n            `→ ${notice.target.cli}). Run \"ekanos upgrade\".`,\n    );\n  }\n\n  ctx.emitClaudeCodeHint({ tool: 'ekanos', toolchain: notice });\n}\n"]}

package/dist/validate-findings.d.ts

@@ -6,5 +6,17 @@ import type { LoadedProject } from './project.js';
  * implementation so the publish gate can never drift from what `validate`
  * checks — a project that validates clean is, by construction, a project that
  * publish will accept locally.
+ *
+ * NOTE on schema skew: an earlier version of this function rewrote the
+ * unrecognized-key hint when the project's `@ekanos/integration-schema` was
+ * newer than the CLI's (see `schema-skew.ts`). That rewrite was dead code —
+ * `assertSchemaNotSkewed` throws PRECONDITION_FAILED before either `validate`
+ * or `publish` ever calls this function in that state, so a project-newer
+ * finding can never reach here to be rewritten, and the precondition error
+ * already names both versions and points at the fix. It was removed rather
+ * than kept "just in case": if a future caller ever makes validate proceed
+ * under skew instead of failing fast, THAT is when a rewrite here becomes
+ * necessary again, and it should be reintroduced with a real caller driving
+ * it, not tests that fake their own reachability.
  */
 export declare function collectAllFindings(loaded: LoadedProject): Promise<Finding[]>;

package/dist/validate-findings.js

@@ -1,13 +1,25 @@
 import { collectCollisionFindings, collectDefinitionFindings, } from '@ekanos/integration-schema';
 import { preconditionError } from './errors.js';
 import { loadDefinition } from './load-definition.js';
-import { collectProjectFindings } from './project-checks.js';
+import { collectDocsFindings, collectProjectFindings } from './project-checks.js';
 /**
  * The full findings pass shared by `validate` (which reports them) and
  * `publish` (which refuses to submit on any error-severity finding). One
  * implementation so the publish gate can never drift from what `validate`
  * checks — a project that validates clean is, by construction, a project that
  * publish will accept locally.
+ *
+ * NOTE on schema skew: an earlier version of this function rewrote the
+ * unrecognized-key hint when the project's `@ekanos/integration-schema` was
+ * newer than the CLI's (see `schema-skew.ts`). That rewrite was dead code —
+ * `assertSchemaNotSkewed` throws PRECONDITION_FAILED before either `validate`
+ * or `publish` ever calls this function in that state, so a project-newer
+ * finding can never reach here to be rewritten, and the precondition error
+ * already names both versions and points at the fix. It was removed rather
+ * than kept "just in case": if a future caller ever makes validate proceed
+ * under skew instead of failing fast, THAT is when a rewrite here becomes
+ * necessary again, and it should be reintroduced with a real caller driving
+ * it, not tests that fake their own reachability.
  */
 export async function collectAllFindings(loaded) {
     const findings = [];
@@ -43,6 +55,7 @@ export async function collectAllFindings(loaded) {
     // Cross-checks only mean something with more than one definition in hand.
     findings.push(...collectCollisionFindings(definitions));
     findings.push(...collectProjectFindings(loaded.projectDir));
+    findings.push(...collectDocsFindings(loaded.project, loaded.projectDir));
     return findings;
 }
 /**

package/dist/validate-findings.js.map

@@ -1 +1 @@
-{"version":3,"file":"validate-findings.js","sourceRoot":"","sources":["../src/validate-findings.ts"],"names":[],"mappings":"AAIA,OAAO,EACL,wBAAwB,EACxB,yBAAyB,GAC1B,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAC7C,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAEnD,OAAO,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAE1D;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,MAAqB;IAErB,MAAM,QAAQ,GAAc,EAAE,CAAC;IAC/B,MAAM,WAAW,GAA+B,EAAE,CAAC;IAEnD,KAAK,MAAM,WAAW,IAAI,MAAM,CAAC,YAAY,EAAE,CAAC;QAC9C,MAAM,MAAM,GAAG,MAAM,cAAc,CACjC,WAAW,CAAC,SAAS,EACrB,MAAM,CAAC,UAAU,CAClB,CAAC;QAEF,IAAI,MAAM,CAAC,EAAE,EAAE,CAAC;YACd,QAAQ,CAAC,IAAI,CACX,GAAG,yBAAyB,CAAC,MAAM,CAAC,UAAU,EAAE;gBAC9C,IAAI,EAAE,WAAW,CAAC,SAAS;aAC5B,CAAC,CACH,CAAC;YACF,QAAQ,CAAC,IAAI,CACX,GAAG,4BAA4B,CAC7B,WAAW,EACX,MAAM,CAAC,UAAgC,CACxC,CACF,CAAC;YACF,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,UAAsC,CAAC,CAAC;YAChE,SAAS;QACX,CAAC;QAED,IAAI,MAAM,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;YAC/B,yEAAyE;YACzE,iEAAiE;YACjE,QAAQ,CAAC,IAAI,CAAC;gBACZ,KAAK,EAAE,iBAAiB;gBACxB,QAAQ,EAAE,OAAO;gBACjB,IAAI,EAAE,WAAW,CAAC,SAAS;gBAC3B,OAAO,EAAE,MAAM,CAAC,OAAO;gBACvB,IAAI,EACF,oEAAoE;oBACpE,uBAAuB;aAC1B,CAAC,CAAC;YACH,SAAS;QACX,CAAC;QAED,kEAAkE;QAClE,MAAM,iBAAiB,CACrB,kDAAkD,WAAW,CAAC,IAAI,KAAK;YACrE,MAAM,CAAC,OAAO,EAChB,oEAAoE;YAClE,6BAA6B,CAChC,CAAC;IACJ,CAAC;IAED,0EAA0E;IAC1E,QAAQ,CAAC,IAAI,CAAC,GAAG,wBAAwB,CAAC,WAAW,CAAC,CAAC,CAAC;IACxD,QAAQ,CAAC,IAAI,CAAC,GAAG,sBAAsB,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC;IAE5D,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;;;;;;GAUG;AACH,SAAS,4BAA4B,CACnC,WAA+D,EAC/D,UAA8B;IAE9B,MAAM,QAAQ,GAAG,UAAU,CAAC,IAAI,CAAC;IACjC,IAAI,OAAO,QAAQ,KAAK,QAAQ,IAAI,QAAQ,KAAK,WAAW,CAAC,IAAI;QAAE,OAAO,EAAE,CAAC;IAE7E,OAAO;QACL;YACE,KAAK,EAAE,wBAAwB;YAC/B,QAAQ,EAAE,OAAO;YACjB,IAAI,EAAE,WAAW,CAAC,SAAS;YAC3B,OAAO,EACL,8BAA8B,WAAW,CAAC,IAAI,wBAAwB;gBACtE,wBAAwB,QAAQ,4BAA4B;gBAC5D,sEAAsE;gBACtE,qCAAqC;YACvC,IAAI,EACF,sDAAsD,QAAQ,OAAO;gBACrE,+BAA+B,WAAW,CAAC,IAAI,OAAO;gBACtD,sBAAsB;SACzB;KACF,CAAC;AACJ,CAAC","sourcesContent":["import type {\n  DefinitionCollisionInput,\n  Finding,\n} from '@ekanos/integration-schema';\nimport {\n  collectCollisionFindings,\n  collectDefinitionFindings,\n} from '@ekanos/integration-schema';\n\nimport { preconditionError } from './errors';\nimport { loadDefinition } from './load-definition';\nimport type { LoadedProject } from './project';\nimport { collectProjectFindings } from './project-checks';\n\n/**\n * The full findings pass shared by `validate` (which reports them) and\n * `publish` (which refuses to submit on any error-severity finding). One\n * implementation so the publish gate can never drift from what `validate`\n * checks — a project that validates clean is, by construction, a project that\n * publish will accept locally.\n */\nexport async function collectAllFindings(\n  loaded: LoadedProject,\n): Promise<Finding[]> {\n  const findings: Finding[] = [];\n  const definitions: DefinitionCollisionInput[] = [];\n\n  for (const integration of loaded.integrations) {\n    const result = await loadDefinition(\n      integration.entryPath,\n      loaded.projectDir,\n    );\n\n    if (result.ok) {\n      findings.push(\n        ...collectDefinitionFindings(result.definition, {\n          file: integration.entryPath,\n        }),\n      );\n      findings.push(\n        ...collectSlugAgreementFindings(\n          integration,\n          result.definition as { slug?: unknown },\n        ),\n      );\n      definitions.push(result.definition as DefinitionCollisionInput);\n      continue;\n    }\n\n    if (result.kind === 'rejected') {\n      // The module loaded but the SDK/schema rejected the definition at import\n      // time — surface it as a validation finding rather than a crash.\n      findings.push({\n        check: 'definition.load',\n        severity: 'error',\n        file: integration.entryPath,\n        message: result.message,\n        hint:\n          'Fix the integration definition so defineIntegration() accepts it, ' +\n          'then re-run validate.',\n      });\n      continue;\n    }\n\n    // A genuine module-load failure is a precondition, not a finding.\n    throw preconditionError(\n      `Could not load the integration definition for \"${integration.slug}\": ` +\n        result.message,\n      'Ensure the entry module and its installed dependencies load under ' +\n        'Node, then re-run validate.',\n    );\n  }\n\n  // Cross-checks only mean something with more than one definition in hand.\n  findings.push(...collectCollisionFindings(definitions));\n  findings.push(...collectProjectFindings(loaded.projectDir));\n\n  return findings;\n}\n\n/**\n * `ekanos.json` and the definition each carry a slug, and nothing compared\n * them: a project could declare `something-else` while the definition said\n * `repo-activity` and validate would report `{ ok: true, findings: [] }`.\n *\n * That is the identifier every surface addresses the integration by — the\n * harness route, the product slug, the widget id prefix, the MCP server — so\n * two sources of truth disagreeing is not a style question. It is an error,\n * not a warning, for the same reason a silent default is worse than a loud\n * one: the failure it causes shows up somewhere else entirely.\n */\nfunction collectSlugAgreementFindings(\n  integration: { slug: string; entry: string; entryPath: string },\n  definition: { slug?: unknown },\n): Finding[] {\n  const declared = definition.slug;\n  if (typeof declared !== 'string' || declared === integration.slug) return [];\n\n  return [\n    {\n      check: 'project.slug-agreement',\n      severity: 'error',\n      file: integration.entryPath,\n      message:\n        `ekanos.json declares slug \"${integration.slug}\" for this entry, but ` +\n        `the definition says \"${declared}\". The slug addresses the ` +\n        'integration everywhere — its harness route, its product record, its ' +\n        'widget ids — so the two must agree.',\n      hint:\n        `Change one to match the other: either set \"slug\": \"${declared}\" in ` +\n        `ekanos.json, or pass slug: '${integration.slug}' to ` +\n        'defineIntegration().',\n    },\n  ];\n}\n"]}
+{"version":3,"file":"validate-findings.js","sourceRoot":"","sources":["../src/validate-findings.ts"],"names":[],"mappings":"AAIA,OAAO,EACL,wBAAwB,EACxB,yBAAyB,GAC1B,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAC7C,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAEnD,OAAO,EAAE,mBAAmB,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAE/E;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,MAAqB;IAErB,MAAM,QAAQ,GAAc,EAAE,CAAC;IAC/B,MAAM,WAAW,GAA+B,EAAE,CAAC;IAEnD,KAAK,MAAM,WAAW,IAAI,MAAM,CAAC,YAAY,EAAE,CAAC;QAC9C,MAAM,MAAM,GAAG,MAAM,cAAc,CACjC,WAAW,CAAC,SAAS,EACrB,MAAM,CAAC,UAAU,CAClB,CAAC;QAEF,IAAI,MAAM,CAAC,EAAE,EAAE,CAAC;YACd,QAAQ,CAAC,IAAI,CACX,GAAG,yBAAyB,CAAC,MAAM,CAAC,UAAU,EAAE;gBAC9C,IAAI,EAAE,WAAW,CAAC,SAAS;aAC5B,CAAC,CACH,CAAC;YACF,QAAQ,CAAC,IAAI,CACX,GAAG,4BAA4B,CAC7B,WAAW,EACX,MAAM,CAAC,UAAgC,CACxC,CACF,CAAC;YACF,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,UAAsC,CAAC,CAAC;YAChE,SAAS;QACX,CAAC;QAED,IAAI,MAAM,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;YAC/B,yEAAyE;YACzE,iEAAiE;YACjE,QAAQ,CAAC,IAAI,CAAC;gBACZ,KAAK,EAAE,iBAAiB;gBACxB,QAAQ,EAAE,OAAO;gBACjB,IAAI,EAAE,WAAW,CAAC,SAAS;gBAC3B,OAAO,EAAE,MAAM,CAAC,OAAO;gBACvB,IAAI,EACF,oEAAoE;oBACpE,uBAAuB;aAC1B,CAAC,CAAC;YACH,SAAS;QACX,CAAC;QAED,kEAAkE;QAClE,MAAM,iBAAiB,CACrB,kDAAkD,WAAW,CAAC,IAAI,KAAK;YACrE,MAAM,CAAC,OAAO,EAChB,oEAAoE;YAClE,6BAA6B,CAChC,CAAC;IACJ,CAAC;IAED,0EAA0E;IAC1E,QAAQ,CAAC,IAAI,CAAC,GAAG,wBAAwB,CAAC,WAAW,CAAC,CAAC,CAAC;IACxD,QAAQ,CAAC,IAAI,CAAC,GAAG,sBAAsB,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC;IAC5D,QAAQ,CAAC,IAAI,CAAC,GAAG,mBAAmB,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC;IAEzE,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;;;;;;GAUG;AACH,SAAS,4BAA4B,CACnC,WAA+D,EAC/D,UAA8B;IAE9B,MAAM,QAAQ,GAAG,UAAU,CAAC,IAAI,CAAC;IACjC,IAAI,OAAO,QAAQ,KAAK,QAAQ,IAAI,QAAQ,KAAK,WAAW,CAAC,IAAI;QAAE,OAAO,EAAE,CAAC;IAE7E,OAAO;QACL;YACE,KAAK,EAAE,wBAAwB;YAC/B,QAAQ,EAAE,OAAO;YACjB,IAAI,EAAE,WAAW,CAAC,SAAS;YAC3B,OAAO,EACL,8BAA8B,WAAW,CAAC,IAAI,wBAAwB;gBACtE,wBAAwB,QAAQ,4BAA4B;gBAC5D,sEAAsE;gBACtE,qCAAqC;YACvC,IAAI,EACF,sDAAsD,QAAQ,OAAO;gBACrE,+BAA+B,WAAW,CAAC,IAAI,OAAO;gBACtD,sBAAsB;SACzB;KACF,CAAC;AACJ,CAAC","sourcesContent":["import type {\n  DefinitionCollisionInput,\n  Finding,\n} from '@ekanos/integration-schema';\nimport {\n  collectCollisionFindings,\n  collectDefinitionFindings,\n} from '@ekanos/integration-schema';\n\nimport { preconditionError } from './errors';\nimport { loadDefinition } from './load-definition';\nimport type { LoadedProject } from './project';\nimport { collectDocsFindings, collectProjectFindings } from './project-checks';\n\n/**\n * The full findings pass shared by `validate` (which reports them) and\n * `publish` (which refuses to submit on any error-severity finding). One\n * implementation so the publish gate can never drift from what `validate`\n * checks — a project that validates clean is, by construction, a project that\n * publish will accept locally.\n *\n * NOTE on schema skew: an earlier version of this function rewrote the\n * unrecognized-key hint when the project's `@ekanos/integration-schema` was\n * newer than the CLI's (see `schema-skew.ts`). That rewrite was dead code —\n * `assertSchemaNotSkewed` throws PRECONDITION_FAILED before either `validate`\n * or `publish` ever calls this function in that state, so a project-newer\n * finding can never reach here to be rewritten, and the precondition error\n * already names both versions and points at the fix. It was removed rather\n * than kept \"just in case\": if a future caller ever makes validate proceed\n * under skew instead of failing fast, THAT is when a rewrite here becomes\n * necessary again, and it should be reintroduced with a real caller driving\n * it, not tests that fake their own reachability.\n */\nexport async function collectAllFindings(\n  loaded: LoadedProject,\n): Promise<Finding[]> {\n  const findings: Finding[] = [];\n  const definitions: DefinitionCollisionInput[] = [];\n\n  for (const integration of loaded.integrations) {\n    const result = await loadDefinition(\n      integration.entryPath,\n      loaded.projectDir,\n    );\n\n    if (result.ok) {\n      findings.push(\n        ...collectDefinitionFindings(result.definition, {\n          file: integration.entryPath,\n        }),\n      );\n      findings.push(\n        ...collectSlugAgreementFindings(\n          integration,\n          result.definition as { slug?: unknown },\n        ),\n      );\n      definitions.push(result.definition as DefinitionCollisionInput);\n      continue;\n    }\n\n    if (result.kind === 'rejected') {\n      // The module loaded but the SDK/schema rejected the definition at import\n      // time — surface it as a validation finding rather than a crash.\n      findings.push({\n        check: 'definition.load',\n        severity: 'error',\n        file: integration.entryPath,\n        message: result.message,\n        hint:\n          'Fix the integration definition so defineIntegration() accepts it, ' +\n          'then re-run validate.',\n      });\n      continue;\n    }\n\n    // A genuine module-load failure is a precondition, not a finding.\n    throw preconditionError(\n      `Could not load the integration definition for \"${integration.slug}\": ` +\n        result.message,\n      'Ensure the entry module and its installed dependencies load under ' +\n        'Node, then re-run validate.',\n    );\n  }\n\n  // Cross-checks only mean something with more than one definition in hand.\n  findings.push(...collectCollisionFindings(definitions));\n  findings.push(...collectProjectFindings(loaded.projectDir));\n  findings.push(...collectDocsFindings(loaded.project, loaded.projectDir));\n\n  return findings;\n}\n\n/**\n * `ekanos.json` and the definition each carry a slug, and nothing compared\n * them: a project could declare `something-else` while the definition said\n * `repo-activity` and validate would report `{ ok: true, findings: [] }`.\n *\n * That is the identifier every surface addresses the integration by — the\n * harness route, the product slug, the widget id prefix, the MCP server — so\n * two sources of truth disagreeing is not a style question. It is an error,\n * not a warning, for the same reason a silent default is worse than a loud\n * one: the failure it causes shows up somewhere else entirely.\n */\nfunction collectSlugAgreementFindings(\n  integration: { slug: string; entry: string; entryPath: string },\n  definition: { slug?: unknown },\n): Finding[] {\n  const declared = definition.slug;\n  if (typeof declared !== 'string' || declared === integration.slug) return [];\n\n  return [\n    {\n      check: 'project.slug-agreement',\n      severity: 'error',\n      file: integration.entryPath,\n      message:\n        `ekanos.json declares slug \"${integration.slug}\" for this entry, but ` +\n        `the definition says \"${declared}\". The slug addresses the ` +\n        'integration everywhere — its harness route, its product record, its ' +\n        'widget ids — so the two must agree.',\n      hint:\n        `Change one to match the other: either set \"slug\": \"${declared}\" in ` +\n        `ekanos.json, or pass slug: '${integration.slug}' to ` +\n        'defineIntegration().',\n    },\n  ];\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ekanos/cli",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "type": "module",
   "description": "The Ekanos partner toolchain CLI: scaffold, validate, and test a Fusion integration against the published @ekanos packages. Agent-native — every verb speaks JSON with a stable exit-code taxonomy.",
   "license": "MIT",

package/templates/AGENTS.md.tmpl

@@ -43,6 +43,29 @@ structurally un-settable — the closest you get is the `proposes` block.
 `ekanos.json` at the project root maps the slug to the entry module. The slug
 lives in both files; `ekanos validate` reports a finding if they disagree.
 
+## API documentation — ground every claim about the target API
+
+`ekanos.json` may declare a `docs` array: http(s) URLs and project-relative
+paths pointing at the target API's documentation (an OpenAPI spec, the
+official docs site, a vendored export). `docs/api-notes.md` is this project's
+own structured snapshot of that API — auth model, base URL, key endpoints,
+pagination, rate limits, error shapes, webhooks — written and updated during
+research and kept under version control so a reviewer can see what the
+integration believes. `ekanos validate` warns (`docs/missing-file`, never
+blocking) when a listed local file does not exist.
+
+Resolve documentation in this order, and announce which rung you are on: a
+local file from `docs` → an OpenAPI spec URL → the official docs URL → the
+Context7 MCP server (configured in `.mcp.json`) → a web search, announced as
+such.
+
+**Never invent an API surface from memory.** If none of those rungs resolves
+to real documentation, stop and ask the developer for a file or URL rather
+than guessing at endpoints, parameters, or error shapes.
+
+Codex users (and other agents without `.mcp.json` support) can add Context7 to
+their own MCP configuration to get the same fallback.
+
 ## The capability context (`ctx`) — the ONLY platform surface
 
 Every server-side handler (tool `run`, webhook `handler`, schedule `handler`,
@@ -212,6 +235,40 @@ Free set (`pnpm --filter @ekanos/ui check:fa-free-names`, or
 https://fontawesome.com/search?o=r&s=solid,regular,brands) before relying on
 it looking like anything in particular.
 
+## Live mode — real API calls, locally
+
+The harness (`npx ekanos dev`) mocks FUSION, not your vendor. **You do not
+need mock data to develop against the real API**, and never claim otherwise:
+the dev toolbar has a fixtures ⇄ live switch per integration, and in live
+mode your widgets' real query functions run and their requests reach the
+real vendor API. The only gate is the `egress` allowlist from
+`defineIntegration()` — enforced locally by the same matcher production
+uses, so an origin you forgot to declare fails on this machine with
+`EgressDeniedError` instead of in review.
+
+Live mode is opt-in per integration. Add a `live` block to the entry in
+`harness.config.ts`:
+
+```ts
+live: {
+  // Fusion-side state widgets read before calling anything — what your
+  // host route would have returned. Everything NOT seeded runs its real
+  // query function against the real network.
+  seeds: [{ queryKey: settingsKey, data: MY_SETTINGS }],
+},
+```
+
+Egress is read off the definition automatically — do not repeat it here.
+
+What stays mocked either way (the Fusion bits): storage, secrets/vault,
+auth, host `/api/` routes — that is what `seeds` and fixtures are for.
+Boundaries to know: live-mode widget requests come from the BROWSER, so a
+vendor that blocks browser origins (CORS) or needs a server-held secret
+must be exercised through handlers instead; and the Triggers surface runs
+webhook/schedule/onActivate handlers against the mock context (its
+`ctx.fetch` never touches the network) — cover handler network behavior
+with fixtures in tests, then for real on the dev host after publishing.
+
 ## Testing
 
 `@ekanos/sdk/testing` builds the same context production uses, in memory —
@@ -242,6 +299,14 @@ with transport semantics (payload validated first, signature skip logged) and
 derive the context from the definition. Reuse one context across invocations
 via `options.context` to accumulate state.
 
+A global install (`npm i -g @ekanos/cli`) is fine and convenient: inside a
+project, `validate`/`dev`/`publish`/`test` automatically delegate to THIS
+project's own pinned `@ekanos/cli` devDependency whenever it differs from the
+invoked binary (the same pattern as the Gradle wrapper or `npx`) — one global
+binary on PATH, but the version that actually reads your definition is always
+the one this project pins. That is also why the scaffold's local
+`@ekanos/cli` devDependency stays mandatory even with a global install.
+
 ## The iteration loop (`npx ekanos <verb>`)
 
 Every verb speaks a JSON envelope on stdout with `--json` (auto-on when piped):
@@ -259,6 +324,22 @@ carries an imperative `hint`; treat hints as remediation instructions.
 | `ekanos sources` | List every Fusion source you hold a developer/admin seat on, marking this project's current target |
 | `ekanos use <source-slug>` | Set this project's publish target — refuses (`forbidden`) a slug you hold no seat on |
 | `ekanos publish` | Validate, pack (whitelist: ekanos.json, package.json, README.md, src/), verify the target, and submit. Refuses on any error-severity finding |
+| `ekanos upgrade` | Move this project's toolchain to a coherent target version, with verify-and-rollback |
+
+### Keeping the toolchain current
+
+`validate`/`dev`/`publish` all bundle an EXACT `@ekanos/integration-schema`
+version, and a project can end up NEWER than that (a `pnpm up` on
+`@ekanos/sdk` alone is enough). In that state `validate`'s findings are
+unreliable — a field the newer schema added parses here as an unrecognized
+key, and it is easy to "fix" that by deleting perfectly correct code. If a
+finding smells like that (an unrecognized key on a field you are confident is
+right), run `ekanos upgrade --check` first: it is READ-ONLY and always safe —
+it only reports current vs. target versions and never touches the project. A
+bare `ekanos upgrade` (no flags) MUTATES the project: it installs the target
+versions, verifies with `ekanos validate` and this project's own test script,
+and rolls everything back automatically if either fails. Never run a bare
+`ekanos upgrade` as a way to "try and see" — use `--check` for that.
 
 Host resolution for `logout`/`whoami`/`status`/`sources`/`use`/`publish`:
 `--host` flag → `EKANOS_HOST` → the `host` field in ekanos.json → the sole

package/templates/CLAUDE.md.tmpl

@@ -3,4 +3,5 @@
 This project is an Ekanos integration for the Fusion platform — read
 [AGENTS.md](./AGENTS.md) for the full authoring contract before changing code.
 The toolchain is `npx ekanos <verb>` (init, validate, dev, test, login,
-status, publish); every verb supports `--json` and a stable exit-code taxonomy.
+status, publish, upgrade); every verb supports `--json` and a stable
+exit-code taxonomy.

package/templates/claude-skill.md.tmpl

@@ -10,6 +10,13 @@ rules, widget and testing patterns — lives in **AGENTS.md** at the project
 root. Read it before writing integration code. The definition is one
 `defineIntegration()` in `src/integration.ts`, exported as `integration`.
 
+For the full authoring workflow — interview, API research, widgets, wiring,
+publish — use the `build-integration` skill. For a styling review of widgets
+that already exist (plain/flat widgets, overflow, a bare marketplace tile),
+use the `polish-widgets` skill. The target API's contract lives
+in `docs/api-notes.md`: write API client code from that file, and update it
+in the same commit when the live API disagrees.
+
 ## The loop
 
 1. `npx ekanos dev` — local harness (only when you need to see UI).
@@ -27,6 +34,16 @@ root. Read it before writing integration code. The definition is one
    while any error-severity finding remains, and refuses `forbidden` if you
    hold no seat on that source).
 
+## Keeping the toolchain current
+
+If a `validate` finding smells like version skew (an unrecognized-key error on
+a field you're confident is correct), run `npx ekanos upgrade --check` —
+read-only, always safe, reports current vs. target versions and changes
+nothing. A bare `npx ekanos upgrade` MUTATES the project (installs the target
+toolchain, verifies with validate + the test script, rolls back automatically
+on any failure). Never run the bare form just to "see what happens" — use
+`--check` for that.
+
 ## Reading CLI output
 
 Every verb emits ONE JSON envelope on stdout when piped (or with `--json`):
@@ -42,8 +59,9 @@ Exit codes to branch on: `0` ok · `2` usage · `3` validation (also: ambiguous
 publish target — pass `--source` or `--yes`, never guess) · `4` run
 `ekanos login` · `5` forbidden (also: no seat on the target source — run
 `ekanos sources`) · `7` version already submitted (bump `package.json#version`) ·
-`8` network (retry — do NOT re-login) · `9` precondition · `10` fix findings,
-publish again.
+`8` network (retry — do NOT re-login) · `9` precondition (also: the project's
+`@ekanos/integration-schema` is newer than this CLI bundles — run
+`ekanos upgrade`) · `10` fix findings, publish again.
 
 ## Hosts and sessions
 

package/templates/docs/api-notes.md.tmpl

@@ -0,0 +1,21 @@
+# __DISPLAY_NAME__ — API notes
+
+This file is the structured snapshot of the target API: what this integration
+currently believes about the upstream service. It is written and updated by
+the build-integration skill's Research phase, and it is versioned so a
+reviewer can see exactly what the integration assumes.
+
+As the authoring agent, fill in and maintain the sections below from real
+documentation (the `docs` entries in `ekanos.json`, an OpenAPI spec, the
+official docs site) — never from memory. Record:
+
+- **Auth model** — scheme, token lifetime, where the credential comes from.
+- **Base URL(s)** — per environment, and what `egress` must allowlist.
+- **Key endpoints** — method, path, purpose, request/response shape.
+- **Pagination** — parameter names, page-size limits, cursor semantics.
+- **Rate limits** — the numeric limits and the backoff the API expects.
+- **Error shapes** — status codes, error body structure, retryable or not.
+- **Webhooks** — events, payloads, signature scheme, retry behaviour.
+
+Update this file in the same change as the code that depends on the new
+knowledge. If the API contradicts these notes, the notes are wrong — fix them.

package/templates/mcp.json.tmpl

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "context7": {
+      "command": "npx",
+      "args": ["-y", "@upstash/context7-mcp"]
+    }
+  }
+}