@vendoai/vendo 0.4.0

package/dist/cli/cloud/pending-claim.js

@@ -0,0 +1,38 @@
+import { chmod, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+function pendingClaimPath(options = {}) {
+    return join(options.home ?? homedir(), ".vendo", "pending-claim.json");
+}
+function isPendingClaim(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const claim = value;
+    return typeof claim.claim_token === "string"
+        && typeof claim.user_code === "string"
+        && typeof claim.verification_uri_complete === "string"
+        && typeof claim.expires_at === "number"
+        && typeof claim.interval === "number"
+        && typeof claim.api_url === "string"
+        && typeof claim.cwd === "string";
+}
+/** An unreadable or malformed file reads as "no pending claim" — the caller
+    discards it by opening (and persisting) a fresh ceremony. */
+export async function readPendingClaim(options = {}) {
+    try {
+        const value = JSON.parse(await readFile(pendingClaimPath(options), "utf8"));
+        return isPendingClaim(value) ? value : null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function writePendingClaim(claim, options = {}) {
+    const path = pendingClaimPath(options);
+    await mkdir(join(path, ".."), { recursive: true, mode: 0o700 });
+    await writeFile(path, `${JSON.stringify(claim, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+    await chmod(path, 0o600);
+}
+export async function deletePendingClaim(options = {}) {
+    await rm(pendingClaimPath(options), { force: true });
+}

package/dist/cli/cloud/read.d.ts

@@ -0,0 +1,3 @@
+import { type CloudCommandOptions } from "./command.js";
+export declare function runOrgs(args: string[], options?: CloudCommandOptions): Promise<number>;
+export declare function runUsage(args: string[], options?: CloudCommandOptions): Promise<number>;

package/dist/cli/cloud/read.js

@@ -0,0 +1,12 @@
+import { option } from "./args.js";
+import { resolveProjectId, runCommand, userOptions, } from "./command.js";
+export function runOrgs(args, options = {}) {
+    return runCommand(options, (context) => context.fetcher("/api/v1/orgs", userOptions(args, context)));
+}
+export function runUsage(args, options = {}) {
+    const days = option(args, "--days") ?? "30";
+    return runCommand(options, async (context) => {
+        const projectId = await resolveProjectId(args, context);
+        return context.fetcher(`/api/v1/projects/${encodeURIComponent(projectId)}/usage?days=${encodeURIComponent(days)}`, userOptions(args, context));
+    });
+}

package/dist/cli/cloud/services.d.ts

@@ -0,0 +1,2 @@
+import { type CloudFetchOptions } from "./client.js";
+export declare function pushSyncReport(payload: unknown, options?: Pick<CloudFetchOptions, "apiKey" | "apiUrl" | "env" | "fetchImpl">): Promise<unknown>;

package/dist/cli/cloud/services.js

@@ -0,0 +1,9 @@
+import { cloudFetch } from "./client.js";
+export function pushSyncReport(payload, options = {}) {
+    return cloudFetch("/api/v1/sync/report", {
+        ...options,
+        auth: "key",
+        method: "POST",
+        body: payload,
+    });
+}

package/dist/cli/cloud/session.d.ts

@@ -0,0 +1,13 @@
+export interface CloudSession {
+    access_token: string;
+    refresh_token?: string;
+    /** Supabase-compatible Unix timestamp in seconds. */
+    expires_at?: number;
+}
+export interface SessionOptions {
+    home?: string;
+}
+export declare function readCloudSession(options?: SessionOptions): Promise<CloudSession | null>;
+export declare function writeCloudSession(session: CloudSession, options?: SessionOptions): Promise<void>;
+export declare function deleteCloudSession(options?: SessionOptions): Promise<void>;
+export declare function isSessionExpired(session: CloudSession, now?: number): boolean;

package/dist/cli/cloud/session.js

@@ -0,0 +1,41 @@
+import { chmod, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+function cloudSessionPath(options = {}) {
+    return join(options.home ?? homedir(), ".vendo", "cloud-session.json");
+}
+function isCloudSession(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const session = value;
+    return typeof session.access_token === "string"
+        && (session.refresh_token === undefined || typeof session.refresh_token === "string")
+        && (session.expires_at === undefined || typeof session.expires_at === "number");
+}
+export async function readCloudSession(options = {}) {
+    try {
+        const value = JSON.parse(await readFile(cloudSessionPath(options), "utf8"));
+        if (!isCloudSession(value))
+            throw new Error("Invalid Vendo Cloud session file");
+        return value;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+}
+export async function writeCloudSession(session, options = {}) {
+    const path = cloudSessionPath(options);
+    await mkdir(join(path, ".."), { recursive: true, mode: 0o700 });
+    await writeFile(path, `${JSON.stringify(session, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+    await chmod(path, 0o600);
+}
+export async function deleteCloudSession(options = {}) {
+    await rm(cloudSessionPath(options), { force: true });
+}
+export function isSessionExpired(session, now = Date.now()) {
+    if (session.expires_at === undefined)
+        return false;
+    return session.expires_at * 1_000 <= now + 30_000;
+}

package/dist/cli/cloud-init.d.ts

@@ -0,0 +1,60 @@
+import type { DevCredential } from "../dev-creds/resolve.js";
+import { type CloudDoctorResult } from "./doctor-live.js";
+import { type Output, type TelemetryOptions } from "./shared.js";
+/**
+ * ENG-339 (install-dx design §6) — cloud in init. Detect VENDO_API_KEY when
+ * present and check its shape locally (key problems surface on the first real
+ * service call), one calm line when absent, and — when a starter model key
+ * would actually help the ladder — offer `vendo login` inline: the auth.md
+ * user-claimed ceremony approves a code in the browser and lands the minted
+ * VENDO_API_KEY in .env.local, so the dev never pastes a key.
+ */
+/** Upsert one NAME=value line in .env.local without clobbering other lines.
+    Exported for init's --cloud-key flag, which lands a supplied key exactly
+    where the mint below would. */
+export declare function upsertEnvLocal(root: string, name: string, value: string): Promise<void>;
+/** The auth.md protocol file on Vendo Cloud (Agent Install DX, Layer 2). */
+export declare const AUTH_MD_URL = "https://vendo.run/auth.md";
+/** The agent-path key pointer: when an agent-driven init needs a Cloud key
+    and none exists, this block is the whole story — discovery URL, the CLI
+    command that runs the user-claimed ceremony, and both fallbacks (paste a
+    key with --cloud-key; stay keyless with --byo). Deterministic lines an
+    agent parses; exported so init's tail and the tests share one source. */
+export declare function agentKeyPointerLines(): string[];
+export interface CloudStepOptions {
+    root: string;
+    output: Output;
+    yes: boolean;
+    /** --byo: the explicit "no Cloud" answer — skip the offer AND the agent
+        pointer (bring-your-own stays first-class, no nudging past it). */
+    byo?: boolean;
+    /** TTY seam for the decline path (tests pin both sides). */
+    isTty?: boolean;
+    /** What the model ladder resolved — decides whether a starter key helps. */
+    credential: DevCredential;
+    env?: Record<string, string | undefined>;
+    apiUrl?: string;
+    /** Fetch seam for the default ceremony (tests script the console with it). */
+    fetchImpl?: typeof fetch;
+    /** Seams (tests). */
+    confirm?: (question: string, defaultYes?: boolean) => Promise<boolean>;
+    cloudProbe?: (options: {
+        env?: Record<string, string | undefined>;
+    }) => Promise<CloudDoctorResult>;
+    /** The whole ceremony in one seam (default: runDeviceLogin). */
+    deviceLogin?: () => Promise<number>;
+    sleep?: (ms: number) => Promise<void>;
+    /** Injectable telemetry deps (matches init/doctor). */
+    telemetry?: TelemetryOptions;
+}
+export interface CloudStepResult {
+    keyPresent: boolean;
+    keyValid: boolean;
+    wroteEnvLocal: boolean;
+}
+/** init's cloud step (design §6). Never changes init's exit code. Tracked as
+    `command_run` command "cloud-init" (TELEMETRY.md): ok is "the step ended
+    in a non-error outcome" — a valid key, a clean skip/decline, or a minted
+    starter key; failures name their step. Telemetry never changes the step's
+    behavior: the tracker is fully guarded and a thrown error still rethrows. */
+export declare function runCloudStep(options: CloudStepOptions): Promise<CloudStepResult>;

package/dist/cli/cloud-init.js

@@ -0,0 +1,149 @@
+import { stdin, stdout } from "node:process";
+import { join } from "node:path";
+import { runDeviceLogin } from "./cloud/device-login.js";
+import { cloudDoctor } from "./doctor-live.js";
+import { askYesNo, cloudProjectProps, errorClass, readOptional, toolingTelemetry, writeText, } from "./shared.js";
+/**
+ * ENG-339 (install-dx design §6) — cloud in init. Detect VENDO_API_KEY when
+ * present and check its shape locally (key problems surface on the first real
+ * service call), one calm line when absent, and — when a starter model key
+ * would actually help the ladder — offer `vendo login` inline: the auth.md
+ * user-claimed ceremony approves a code in the browser and lands the minted
+ * VENDO_API_KEY in .env.local, so the dev never pastes a key.
+ */
+/** Upsert one NAME=value line in .env.local without clobbering other lines.
+    Exported for init's --cloud-key flag, which lands a supplied key exactly
+    where the mint below would. */
+export async function upsertEnvLocal(root, name, value) {
+    const path = join(root, ".env.local");
+    const current = await readOptional(path);
+    const line = `${name}=${value}`;
+    if (current === null || current.length === 0) {
+        await writeText(path, `${line}\n`);
+        return;
+    }
+    const pattern = new RegExp(`^\\s*${name}\\s*=.*$`, "m");
+    if (pattern.test(current)) {
+        await writeText(path, current.replace(pattern, line));
+        return;
+    }
+    const separator = current.endsWith("\n") ? "" : "\n";
+    await writeText(path, `${current}${separator}${line}\n`);
+}
+/** The auth.md protocol file on Vendo Cloud (Agent Install DX, Layer 2). */
+export const AUTH_MD_URL = "https://vendo.run/auth.md";
+/** The agent-path key pointer: when an agent-driven init needs a Cloud key
+    and none exists, this block is the whole story — discovery URL, the CLI
+    command that runs the user-claimed ceremony, and both fallbacks (paste a
+    key with --cloud-key; stay keyless with --byo). Deterministic lines an
+    agent parses; exported so init's tail and the tests share one source. */
+export function agentKeyPointerLines() {
+    return [
+        `Vendo Cloud key (agent path): fetch ${AUTH_MD_URL} and follow the user-claimed flow —`,
+        "  1. run `vendo login` — it prints a code your human approves in the browser",
+        "  2. the minted VENDO_API_KEY lands in .env.local automatically (never printed)",
+        "  3. re-run `vendo init` (it picks the key up from .env.local) or pass --cloud-key <key>",
+        "No Cloud account wanted? Re-run with --byo and set a provider key (ANTHROPIC_API_KEY / OPENAI_API_KEY / GOOGLE_GENERATIVE_AI_API_KEY).",
+    ];
+}
+/** init's cloud step (design §6). Never changes init's exit code. Tracked as
+    `command_run` command "cloud-init" (TELEMETRY.md): ok is "the step ended
+    in a non-error outcome" — a valid key, a clean skip/decline, or a minted
+    starter key; failures name their step. Telemetry never changes the step's
+    behavior: the tracker is fully guarded and a thrown error still rethrows. */
+export async function runCloudStep(options) {
+    const started = Date.now();
+    // The step's target root is the client's cwd: projectIdHash and the
+    // .env.local cloud-key read attribute to the project init runs against.
+    const telemetry = toolingTelemetry({ cwd: options.root, ...(options.telemetry ?? {}) });
+    const failure = {};
+    const track = async (thrown) => {
+        try {
+            await telemetry.track("command_run", {
+                command: "cloud-init",
+                ok: thrown === undefined && failure.failedStep === undefined,
+                durationMs: Date.now() - started,
+                ...(failure.failedStep === undefined ? {} : { failedStep: failure.failedStep }),
+                ...(thrown === undefined ? {} : { errorClass: errorClass(thrown.error) }),
+                ...(await cloudProjectProps(options.root)),
+            });
+        }
+        catch {
+            // Telemetry must never break init. Intentional silent failure.
+        }
+    };
+    try {
+        const result = await cloudStep(options, failure);
+        await track();
+        return result;
+    }
+    catch (error) {
+        await track({ error });
+        throw error;
+    }
+}
+async function cloudStep(options, failure) {
+    const { root, output, credential } = options;
+    const env = options.env ?? process.env;
+    const cloud = await (options.cloudProbe ?? cloudDoctor)({ env });
+    if (cloud.present && cloud.ok) {
+        output.log("\nVendo Cloud: VENDO_API_KEY present and well-formed.");
+        return { keyPresent: true, keyValid: true, wroteEnvLocal: false };
+    }
+    if (cloud.present) {
+        failure.failedStep = "key-invalid";
+        output.error(`\nVendo Cloud: VENDO_API_KEY is set but not usable (${cloud.error ?? "malformed"}). Fix or remove it; \`vendo login\` can issue a fresh one.`);
+        return { keyPresent: true, keyValid: false, wroteEnvLocal: false };
+    }
+    // Absent — one calm line stating what Cloud unlocks.
+    output.log(`\nVendo Cloud (optional): not configured. A key unlocks ${cloud.unlocks.join("; ")}.`);
+    // A starter model key only helps when the local ladder has nothing better.
+    const laddersWantKey = credential.rung === "none" || credential.rung === "vendo-cloud";
+    if (options.yes || options.byo === true || !laddersWantKey) {
+        if (laddersWantKey) {
+            if (options.byo === true) {
+                output.log("Run `vendo login` to claim a free dev-mode key; it lands in .env.local.");
+            }
+            else {
+                // --yes / agent-driven runs get the full auth.md pointer: the agent
+                // can complete the whole key story in-band from these lines.
+                for (const line of agentKeyPointerLines())
+                    output.log(line);
+            }
+        }
+        return { keyPresent: false, keyValid: false, wroteEnvLocal: false };
+    }
+    const tty = options.isTty ?? (stdin.isTTY === true && stdout.isTTY === true);
+    const confirm = options.confirm ?? askYesNo;
+    if (!(await confirm("Log in to Vendo Cloud now for a free dev-mode model key?", false))) {
+        if (tty) {
+            output.log("Skipped — run `vendo login` any time; the key lands in .env.local.");
+        }
+        else {
+            // Nobody saw that prompt (non-TTY): this is an agent-driven run that
+            // reached here without --yes — point it at the auth.md flow instead.
+            for (const line of agentKeyPointerLines())
+                output.log(line);
+        }
+        return { keyPresent: false, keyValid: false, wroteEnvLocal: false };
+    }
+    // The `vendo login` ceremony end to end: approve a code in the browser
+    // (TTY opens it), and the minted key lands in .env.local — init picks it
+    // up in this same run, so the standalone re-run hint is suppressed.
+    const deviceLogin = options.deviceLogin ?? (() => runDeviceLogin(options.apiUrl === undefined ? [] : ["--api-url", options.apiUrl], {
+        output,
+        env,
+        root,
+        isTty: tty,
+        rerunHint: false,
+        ...(options.fetchImpl === undefined ? {} : { fetchImpl: options.fetchImpl }),
+        ...(options.sleep === undefined ? {} : { sleep: options.sleep }),
+    }));
+    if ((await deviceLogin()) !== 0) {
+        failure.failedStep = "login";
+        output.error("Vendo Cloud login did not complete; run `vendo login` and re-run `vendo init`.");
+        return { keyPresent: false, keyValid: false, wroteEnvLocal: false };
+    }
+    output.log("Production always needs a real server-side key.");
+    return { keyPresent: true, keyValid: true, wroteEnvLocal: true };
+}

package/dist/cli/dep-versions.d.ts

@@ -0,0 +1,26 @@
+import type { HostFramework } from "./framework.js";
+/**
+ * Bare dependency versions for telemetry (posthog-analytics design §3):
+ * version strings are non-identifying, in line with what Astro/Nx collect
+ * anonymously. Missing dependencies are omitted, never sent as placeholders.
+ */
+export interface DepVersions {
+    frameworkVersion?: string;
+    reactVersion?: string;
+    zodVersion?: string;
+    typescriptVersion?: string;
+}
+/**
+ * The HOST's installed `ai` version (#478 short-term): @vendoai/vendo speaks
+ * AI SDK v6 to the host's `ai` package (peer `ai >=6 <7`), but npm installs
+ * the peer conflict anyway — so the version must be read from the TARGET
+ * dir's node_modules, never the CLI's own dependency tree. Non-throwing:
+ * an absent install or malformed metadata returns null (the missing-
+ * dependency story belongs to the wiring checks, not this reader).
+ */
+export declare function installedAiVersion(root: string): Promise<string | null>;
+/**
+ * Read the host project's dependency versions (deps + devDeps) for telemetry.
+ * Non-throwing: a missing or malformed package.json returns {}.
+ */
+export declare function detectDepVersions(root: string, framework: HostFramework): Promise<DepVersions>;

package/dist/cli/dep-versions.js

@@ -0,0 +1,77 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+/** The npm package that IS each detected framework (detectFramework's own
+    evidence source, framework.ts). */
+const FRAMEWORK_PACKAGE = {
+    next: "next",
+    express: "express",
+};
+/**
+ * Normalize a semver range to its bare version: "^15.3.1" → "15.3.1",
+ * "~4.2" → "4.2", ">=3.0.0-beta.1" → "3.0.0-beta.1", "workspace:^0.3.0" →
+ * "0.3.0", "npm:foo@^2.1.0" → "2.1.0". The version must start the specifier
+ * (after a workspace:/catalog:/npm-alias prefix and range operator) — a digit
+ * run elsewhere is not a version, so named catalogs ("catalog:react19"),
+ * file:/link:/git:/URL specifiers (paths and ports carry digits), and
+ * versionless ranges ("*", "latest") all → undefined and the field is omitted.
+ */
+function bareVersion(range) {
+    if (typeof range !== "string")
+        return undefined;
+    let s = range.trim();
+    if (s.startsWith("npm:")) {
+        // npm alias: the range follows the LAST "@" ("npm:@scope/name@^2.1.0").
+        const at = s.lastIndexOf("@");
+        s = at > 4 ? s.slice(at + 1) : "";
+    }
+    else {
+        s = s.replace(/^(?:workspace|catalog):/, "");
+    }
+    s = s.replace(/^(?:>=|<=|>|<|\^|~|=)?\s*/, "").replace(/^v(?=\d)/, "");
+    return /^\d+(?:\.\d+)*(?:[-+][0-9A-Za-z.-]+)?/.exec(s)?.[0];
+}
+/**
+ * The HOST's installed `ai` version (#478 short-term): @vendoai/vendo speaks
+ * AI SDK v6 to the host's `ai` package (peer `ai >=6 <7`), but npm installs
+ * the peer conflict anyway — so the version must be read from the TARGET
+ * dir's node_modules, never the CLI's own dependency tree. Non-throwing:
+ * an absent install or malformed metadata returns null (the missing-
+ * dependency story belongs to the wiring checks, not this reader).
+ */
+export async function installedAiVersion(root) {
+    try {
+        const manifest = JSON.parse(await readFile(join(root, "node_modules", "ai", "package.json"), "utf8"));
+        return typeof manifest.version === "string" ? manifest.version : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Read the host project's dependency versions (deps + devDeps) for telemetry.
+ * Non-throwing: a missing or malformed package.json returns {}.
+ */
+export async function detectDepVersions(root, framework) {
+    try {
+        const manifest = JSON.parse(await readFile(join(root, "package.json"), "utf8"));
+        const dependencies = { ...manifest.devDependencies, ...manifest.dependencies };
+        const out = {};
+        const frameworkPackage = framework === "unknown" ? undefined : FRAMEWORK_PACKAGE[framework];
+        const frameworkVersion = frameworkPackage === undefined ? undefined : bareVersion(dependencies[frameworkPackage]);
+        if (frameworkVersion !== undefined)
+            out.frameworkVersion = frameworkVersion;
+        const reactVersion = bareVersion(dependencies["react"]);
+        if (reactVersion !== undefined)
+            out.reactVersion = reactVersion;
+        const zodVersion = bareVersion(dependencies["zod"]);
+        if (zodVersion !== undefined)
+            out.zodVersion = zodVersion;
+        const typescriptVersion = bareVersion(dependencies["typescript"]);
+        if (typescriptVersion !== undefined)
+            out.typescriptVersion = typescriptVersion;
+        return out;
+    }
+    catch {
+        return {};
+    }
+}

package/dist/cli/doctor-codes.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Agent-install DX (design 2026-07-19 §CLI-3) — the doctor error-code
+ * registry. Every failure mode doctor can report (static and live) has one
+ * stable, grep-able code here: E-<AREA>-<NNN>, where the area groups related
+ * checks (WIRE wiring, CFG config files, DEP host dependency versions, UI
+ * eject drift, DEV probe server, LIVE composition/status, AUTH credentials,
+ * MCP door, TURN model turn, CLOUD key). Codes are append-only: never renumber or reuse one — the
+ * verify page anchors (`fix_ref`) and agents' remediation notes depend on
+ * them staying put.
+ *
+ * This is the ONE module a CI check enumerates to assert every code has a
+ * matching verify-page anchor (no registry rot).
+ */
+export declare const DOCTOR_ERROR_CODES: {
+    readonly "E-WIRE-001": "Express server is not wired with createVendo from @vendoai/vendo/server";
+    readonly "E-WIRE-002": "Express client is not wrapped in <VendoRoot>";
+    readonly "E-WIRE-003": "the Next.js catch-all handler app/api/vendo/[...vendo]/route.ts is missing";
+    readonly "E-WIRE-004": "the Next.js root layout is not wrapped in <VendoRoot>";
+    readonly "E-WIRE-005": "the @vendoai/vendo (or vendoai alias) dependency is not declared";
+    readonly "E-CFG-001": "a required .vendo/ config file is missing";
+    readonly "E-CFG-002": ".vendo/data/.gitignore is missing";
+    readonly "E-DEP-001": "the installed ai package is a major version @vendoai/vendo does not support";
+    readonly "E-UI-001": "an ejected surface predates the installed @vendoai/ui";
+    readonly "E-DEV-001": "the dev server could not be started for the probe";
+    readonly "E-LIVE-001": "/status returned an invalid composition response";
+    readonly "E-LIVE-002": "/status is unreachable";
+    readonly "E-LIVE-003": "/status returned an invalid execution venue";
+    readonly "E-LIVE-004": "no execution venue is configured";
+    readonly "E-LIVE-005": "the host /status does not report an execution venue (version skew)";
+    readonly "E-AUTH-001": "present credentials did not reach the host API";
+    readonly "E-AUTH-002": "the present credential probe is unreachable";
+    readonly "E-AUTH-003": "the present credential probe cannot run while the dev server is down";
+    readonly "E-AUTH-004": "actAs mint + host verification failed";
+    readonly "E-AUTH-005": "the actAs probe is unreachable";
+    readonly "E-AUTH-006": "the actAs probe cannot run while the dev server is down";
+    readonly "E-AUTH-007": "actAs is not configured";
+    readonly "E-MCP-001": "MCP protected-resource metadata did not resolve";
+    readonly "E-MCP-002": "MCP authorization-server metadata did not resolve";
+    readonly "E-MCP-003": "the MCP server card did not parse";
+    readonly "E-MCP-004": "server.json does not meet MCP registry discovery requirements";
+    readonly "E-MCP-005": "the server.json remote does not match the live MCP door";
+    readonly "E-MCP-006": "server.json is invalid JSON";
+    readonly "E-MCP-007": "the local MCP registry auth challenge is malformed";
+    readonly "E-MCP-008": "the live MCP registry auth challenge is malformed";
+    readonly "E-SCHED-001": "apps declare vendo.json schedules but no schedule caller is configured";
+    readonly "E-TURN-001": "the live model turn did not answer";
+    readonly "E-TURN-002": "the live model turn cannot run while the dev server is down";
+    readonly "E-CLOUD-001": "VENDO_API_KEY is set but not usable";
+};
+export type DoctorErrorCode = keyof typeof DOCTOR_ERROR_CODES;
+/** Complete list of every code doctor can emit, for CI enumeration. */
+export declare const doctorErrorCodes: readonly DoctorErrorCode[];
+/** The verify playbook page the fix_ref URLs anchor into. */
+export declare const VERIFY_URL = "https://vendo.run/agents/verify";
+/** Full fix URL for a code: the installed vendoai version rides as a query
+ *  param BEFORE the fragment so the URL stays valid and the verify page can
+ *  version-match its guidance. */
+export declare function doctorFixRef(code: DoctorErrorCode, version?: string): string;

package/dist/cli/doctor-codes.js

@@ -0,0 +1,60 @@
+import { CLI_VERSION } from "./shared.js";
+/**
+ * Agent-install DX (design 2026-07-19 §CLI-3) — the doctor error-code
+ * registry. Every failure mode doctor can report (static and live) has one
+ * stable, grep-able code here: E-<AREA>-<NNN>, where the area groups related
+ * checks (WIRE wiring, CFG config files, DEP host dependency versions, UI
+ * eject drift, DEV probe server, LIVE composition/status, AUTH credentials,
+ * MCP door, TURN model turn, CLOUD key). Codes are append-only: never renumber or reuse one — the
+ * verify page anchors (`fix_ref`) and agents' remediation notes depend on
+ * them staying put.
+ *
+ * This is the ONE module a CI check enumerates to assert every code has a
+ * matching verify-page anchor (no registry rot).
+ */
+export const DOCTOR_ERROR_CODES = {
+    "E-WIRE-001": "Express server is not wired with createVendo from @vendoai/vendo/server",
+    "E-WIRE-002": "Express client is not wrapped in <VendoRoot>",
+    "E-WIRE-003": "the Next.js catch-all handler app/api/vendo/[...vendo]/route.ts is missing",
+    "E-WIRE-004": "the Next.js root layout is not wrapped in <VendoRoot>",
+    "E-WIRE-005": "the @vendoai/vendo (or vendoai alias) dependency is not declared",
+    "E-CFG-001": "a required .vendo/ config file is missing",
+    "E-CFG-002": ".vendo/data/.gitignore is missing",
+    "E-DEP-001": "the installed ai package is a major version @vendoai/vendo does not support",
+    "E-UI-001": "an ejected surface predates the installed @vendoai/ui",
+    "E-DEV-001": "the dev server could not be started for the probe",
+    "E-LIVE-001": "/status returned an invalid composition response",
+    "E-LIVE-002": "/status is unreachable",
+    "E-LIVE-003": "/status returned an invalid execution venue",
+    "E-LIVE-004": "no execution venue is configured",
+    "E-LIVE-005": "the host /status does not report an execution venue (version skew)",
+    "E-AUTH-001": "present credentials did not reach the host API",
+    "E-AUTH-002": "the present credential probe is unreachable",
+    "E-AUTH-003": "the present credential probe cannot run while the dev server is down",
+    "E-AUTH-004": "actAs mint + host verification failed",
+    "E-AUTH-005": "the actAs probe is unreachable",
+    "E-AUTH-006": "the actAs probe cannot run while the dev server is down",
+    "E-AUTH-007": "actAs is not configured",
+    "E-MCP-001": "MCP protected-resource metadata did not resolve",
+    "E-MCP-002": "MCP authorization-server metadata did not resolve",
+    "E-MCP-003": "the MCP server card did not parse",
+    "E-MCP-004": "server.json does not meet MCP registry discovery requirements",
+    "E-MCP-005": "the server.json remote does not match the live MCP door",
+    "E-MCP-006": "server.json is invalid JSON",
+    "E-MCP-007": "the local MCP registry auth challenge is malformed",
+    "E-MCP-008": "the live MCP registry auth challenge is malformed",
+    "E-SCHED-001": "apps declare vendo.json schedules but no schedule caller is configured",
+    "E-TURN-001": "the live model turn did not answer",
+    "E-TURN-002": "the live model turn cannot run while the dev server is down",
+    "E-CLOUD-001": "VENDO_API_KEY is set but not usable",
+};
+/** Complete list of every code doctor can emit, for CI enumeration. */
+export const doctorErrorCodes = Object.keys(DOCTOR_ERROR_CODES);
+/** The verify playbook page the fix_ref URLs anchor into. */
+export const VERIFY_URL = "https://vendo.run/agents/verify";
+/** Full fix URL for a code: the installed vendoai version rides as a query
+ *  param BEFORE the fragment so the URL stays valid and the verify page can
+ *  version-match its guidance. */
+export function doctorFixRef(code, version = CLI_VERSION) {
+    return `${VERIFY_URL}?v=${encodeURIComponent(version)}#${code}`;
+}

package/dist/cli/doctor-live.d.ts

@@ -0,0 +1,67 @@
+import { type ChildProcess } from "node:child_process";
+import { type DevCredential, type ResolveDevCredentialOptions } from "../dev-creds/resolve.js";
+/**
+ * ENG-339 (install-dx design §5-6) — doctor's live surface: one real model
+ * turn through the wired HTTP route, a local VENDO_API_KEY shape check with
+ * what Cloud unlocks, and a consent-gated dev-server starter for the probe.
+ * All seam-driven so doctor stays testable without live keys or a running
+ * server.
+ */
+export interface LiveTurnResult {
+    attempted: boolean;
+    ok: boolean;
+    /** Which ladder rung the runtime resolved (doctor and runtime read the same
+     *  resolver, so this is what the answering turn used). */
+    rung: DevCredential["rung"];
+    credential: string;
+    reply?: string;
+    error?: string;
+    elapsedMs: number;
+}
+export interface LiveTurnOptions {
+    /** Wire base, e.g. http://localhost:3000/api/vendo. */
+    base: string;
+    fetchImpl?: typeof fetch;
+    env?: Record<string, string | undefined>;
+    /** Stream the reply to the terminal as it arrives. */
+    onDelta?: (delta: string) => void;
+    timeoutMs?: number;
+    /** Test seam: skip the real resolver probe. */
+    resolveCredential?: (options: ResolveDevCredentialOptions) => Promise<DevCredential>;
+}
+/** POST one seeded turn to the live wire and stream the reply — mirrors the
+ *  init finale's route (`POST {base}/threads`, UI-message SSE frames). Exit 0
+ *  means a user would have gotten an answer: a non-empty text reply arrived. */
+export declare function liveModelTurn(options: LiveTurnOptions): Promise<LiveTurnResult>;
+/** Human-facing list of what a Cloud key unlocks over OSS single-player. Shown
+ *  whether or not a key is present, so a keyless dev sees the offer. */
+export declare const CLOUD_UNLOCKS: readonly string[];
+export interface CloudDoctorResult {
+    present: boolean;
+    ok: boolean;
+    unlocks: readonly string[];
+    error?: string;
+}
+export interface CloudDoctorOptions {
+    env?: Record<string, string | undefined>;
+}
+/** Check VENDO_API_KEY presence and shape locally; always surface what Cloud
+ *  unlocks. Key problems surface on the first real service call — there is no
+ *  validate endpoint. */
+export declare function cloudDoctor(options?: CloudDoctorOptions): Promise<CloudDoctorResult>;
+export interface StartedDevServer {
+    ok: boolean;
+    stop: () => void;
+    log: string[];
+}
+export interface StartDevServerOptions {
+    root: string;
+    /** Wire base whose /status decides "up". */
+    statusUrl: string;
+    env?: Record<string, string | undefined>;
+    fetchImpl?: typeof fetch;
+    timeoutMs?: number;
+    spawnDev?: (packageManager: string, root: string) => ChildProcess;
+}
+/** Spawn `run dev` and wait for the wire to answer. Caller stop()s it. */
+export declare function startDevServerForProbe(options: StartDevServerOptions): Promise<StartedDevServer>;