@vendoai/vendo 0.4.0

package/dist/cli/sync.js

@@ -0,0 +1,202 @@
+import { join, resolve } from "node:path";
+import { vendoSync } from "@vendoai/actions";
+import { pushSyncReport } from "./cloud/services.js";
+import { syncSemantics } from "./semantics.js";
+import { consoleOutput, withCommandRun } from "./shared.js";
+function impactResponse(value) {
+    if (typeof value !== "object" || value === null || !Array.isArray(value.impact)) {
+        throw new Error("invalid sync impact response");
+    }
+    const impact = value.impact;
+    for (const entry of impact) {
+        if (typeof entry !== "object" || entry === null)
+            throw new Error("invalid sync impact response");
+        const candidate = entry;
+        if (typeof candidate.tool !== "string" || !Array.isArray(candidate.apps)
+            || !Array.isArray(candidate.automations) || typeof candidate.grants !== "number") {
+            throw new Error("invalid sync impact response");
+        }
+    }
+    return impact;
+}
+function printImpact(output, impact) {
+    for (const entry of impact) {
+        const categories = [
+            [entry.automations.length, "automation"],
+            [entry.apps.length, "app"],
+            [entry.grants, "grant"],
+        ];
+        const references = categories
+            .filter(([count]) => count > 0)
+            .map(([count, label]) => `${count} ${label}${count === 1 ? "" : "s"}`);
+        output.log(references.length === 0
+            ? `impact: ${entry.tool} no saved references`
+            : `impact: ${entry.tool} breaks ${references.join(", ")}`);
+    }
+}
+function nonzero(entry) {
+    return entry.apps.length > 0 || entry.automations.length > 0 || entry.grants > 0;
+}
+/** 04-actions §1 / 09-vendo §5 — fail-soft extraction, strict CI gate. */
+export async function runSync(options) {
+    return withCommandRun({
+        command: "sync",
+        root: options.targetDir,
+        ...(options.telemetry === undefined ? {} : { telemetry: options.telemetry }),
+    }, () => sync(options));
+}
+async function sync(options) {
+    const output = options.output ?? consoleOutput;
+    const json = options.json === true;
+    // In --json mode, human lines that duplicate report fields are dropped and
+    // CLI-level events collect into `notes`; stdout carries exactly one object.
+    const notes = [];
+    const note = (message) => { if (json)
+        notes.push(message);
+    else
+        output.log(message); };
+    const noteError = (message) => { if (json)
+        notes.push(message);
+    else
+        output.error(message); };
+    try {
+        const root = resolve(options.targetDir);
+        const report = await (options.sync ?? vendoSync)({
+            root,
+            out: join(root, ".vendo"),
+            // The CLI needs the report to compute exit 2 vs 3; it applies strictness below.
+            strict: false,
+        });
+        if (!json) {
+            for (const warning of report.warnings)
+                output.error(`warning: ${warning}`);
+            output.log(`tools: +${report.tools.added.length} -${report.tools.removed.length} ~${report.tools.changed.length}`);
+            output.log(`pins: ${report.pins.captured.length} captured, ${report.pins.drifted.length} drifted`);
+            output.log(`catalog.json: ${report.catalog.discovered} discovered, ${report.catalog.registered} registered`);
+            if (report.pins.drifted.length > 0) {
+                // 06-apps §8 — drift never auto-rebases: the fork's owner decides.
+                output.log(`drifted: ${report.pins.drifted.join(", ")} — existing forks stay on the old capture until each owner rebases (POST /apps/:id/rebase-pin or the vendo_apps_rebase_pin agent tool)`);
+            }
+        }
+        // Unresolved slots fail the run regardless of --strict (silent remix skips
+        // are eliminated), but impact analysis, the report push, and the breaking
+        // gate below still execute so the most severe exit code wins. In --json
+        // mode the human lines are dropped: the pins ride in report.unresolvedPins.
+        let unresolvedExit = 0;
+        if (report.unresolvedPins.length > 0) {
+            if (!json) {
+                output.error("unresolved remixable slots:");
+                for (const pin of report.unresolvedPins) {
+                    output.error(`  ${pin.slot} [${pin.reason}]: ${pin.hint}`);
+                }
+            }
+            unresolvedExit = 2;
+        }
+        const wireUrl = (options.url ?? process.env.VENDO_URL ?? "http://localhost:3000/api/vendo").replace(/\/+$/, "");
+        // W3 — field semantics + domain manifest into .vendo/semantics.json
+        // (one-time inference via the dev server; host edits preserved).
+        // Fail-soft like everything else in sync.
+        try {
+            await syncSemantics({
+                vendoDir: join(root, ".vendo"),
+                url: wireUrl,
+                ...(options.fetchImpl === undefined ? {} : { fetchImpl: options.fetchImpl }),
+                note,
+            });
+        }
+        catch (error) {
+            note(`semantics sync failed soft: ${error instanceof Error ? error.message : "unknown error"}`);
+        }
+        const tools = [...new Set([
+                ...report.breaking.map((breaking) => breaking.tool),
+                ...report.tools.changed,
+            ])];
+        let impact;
+        if (tools.length > 0) {
+            const impactUrl = wireUrl;
+            try {
+                const response = await (options.fetchImpl ?? fetch)(`${impactUrl}/sync/impact`, {
+                    method: "POST",
+                    headers: { accept: "application/json", "content-type": "application/json" },
+                    body: JSON.stringify({ tools }),
+                });
+                if (!response.ok)
+                    throw new Error(`sync impact returned ${response.status}`);
+                impact = impactResponse(await response.json());
+                if (!json)
+                    printImpact(output, impact);
+            }
+            catch {
+                note(`impact unknown — dev server not reachable at ${impactUrl}`);
+            }
+        }
+        if (options.report === true) {
+            const apiKey = options.apiKey ?? process.env.VENDO_API_KEY;
+            if (!apiKey) {
+                noteError("--report requires VENDO_API_KEY or --key");
+            }
+            else {
+                const payload = {
+                    report,
+                    ...(impact === undefined ? {} : { impact }),
+                    at: new Date().toISOString(),
+                };
+                try {
+                    if (options.push !== undefined)
+                        await options.push(payload);
+                    else
+                        await pushSyncReport(payload, {
+                            apiKey,
+                            ...(options.apiUrl === undefined ? {} : { apiUrl: options.apiUrl }),
+                            ...(options.fetchImpl === undefined ? {} : { fetchImpl: options.fetchImpl }),
+                        });
+                }
+                catch (error) {
+                    noteError(`warning: failed to push sync report: ${error instanceof Error ? error.message : "unknown error"}`);
+                }
+            }
+        }
+        // Unresolved slots set the floor; the strict breaking gate overrides with
+        // its own (equal-or-worse) code, so the most severe exit wins.
+        let exitCode = unresolvedExit;
+        if (options.strict === true && report.breaking.length > 0) {
+            if (!json)
+                for (const breaking of report.breaking)
+                    output.error(`breaking: ${breaking.tool} ${breaking.change}`);
+            const breakingTools = new Set(report.breaking.map((breaking) => breaking.tool));
+            exitCode = impact?.some((entry) => breakingTools.has(entry.tool) && nonzero(entry)) === true ? 3 : 2;
+        }
+        if (json) {
+            const result = {
+                ok: exitCode === 0,
+                exitCode,
+                report,
+                // Nothing changed → nothing could be impacted; changes without a
+                // reachable dev server → unknown, surfaced as null plus a note.
+                impact: impact ?? (tools.length === 0 ? [] : null),
+                notes,
+            };
+            output.log(JSON.stringify(result, null, 2));
+        }
+        return exitCode;
+    }
+    catch (error) {
+        const message = `sync failed soft: ${error instanceof Error ? error.message : "unknown error"}`;
+        const exitCode = options.strict === true ? 2 : 0;
+        if (json) {
+            const result = {
+                ok: exitCode === 0,
+                exitCode,
+                report: { tools: { added: [], removed: [], changed: [] }, breaking: [], pins: { captured: [], drifted: [] }, unresolvedPins: [], catalog: { discovered: 0, registered: 0 }, warnings: [] },
+                impact: null,
+                notes,
+                error: message,
+            };
+            output.log(JSON.stringify(result, null, 2));
+        }
+        else {
+            output.error(`warning: ${message}`);
+        }
+        return exitCode;
+    }
+}

package/dist/cli/theme/color.d.ts

@@ -0,0 +1,15 @@
+import type { CssVarDecl } from "./css-vars.js";
+/** Any supported CSS color form to lowercase 6-digit hex; null when not one.
+ *  A trailing `!important` is declaration noise, not color — stripped. */
+export declare function normalizeColor(value: string): string | null;
+/**
+ * Resolve `var(--x)` / `var(--x, fallback)` references against the collected
+ * declarations (bounded depth). Returns null when a reference cannot be
+ * resolved — theme.json carries fully-resolved primitives only (frozen theme
+ * contract), so an unresolved reference means the slot is not exactly readable.
+ */
+export declare function resolveCssVarRefs(value: string, vars: CssVarDecl[], depth?: number): string | null;
+/** px/rem length to canonical px; null for any other unit or expression. */
+export declare function normalizeLength(value: string): string | null;
+/** Pick black or white by the larger WCAG contrast ratio against the accent. */
+export declare function contrastingText(accent: string): "#000000" | "#ffffff";

package/dist/cli/theme/color.js

@@ -0,0 +1,188 @@
+/**
+ * Deterministic CSS color/length normalization for exact token reads. Every
+ * conversion here is published spec math (CSS Color 4), not inference: a
+ * conventional token's declared value is turned into the concrete hex/px the
+ * frozen VendoTheme contract carries. Values with real transparency are
+ * rejected (theme slots are opaque paints), as is anything unparseable —
+ * an unreadable value is treated as absent, never guessed at.
+ */
+const HEX = /^#([0-9a-fA-F]{3,4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/;
+function normalizeHex(value) {
+    const trimmed = value.trim();
+    if (!HEX.test(trimmed))
+        return null;
+    let h = trimmed.slice(1);
+    if (h.length === 3 || h.length === 4)
+        h = [...h].map((c) => c + c).join("");
+    if (h.length === 8) {
+        const alpha = parseInt(h.slice(6, 8), 16);
+        if (alpha !== 255)
+            return null;
+        h = h.slice(0, 6);
+    }
+    return `#${h.slice(0, 6).toLowerCase()}`;
+}
+function clamp01(value) {
+    return Math.min(1, Math.max(0, value));
+}
+function byteToHex(value) {
+    return Math.round(clamp01(value) * 255).toString(16).padStart(2, "0");
+}
+function rgbToHex(r, g, b) {
+    return `#${byteToHex(r)}${byteToHex(g)}${byteToHex(b)}`;
+}
+function parseAlpha(value) {
+    if (!value)
+        return 1;
+    const trimmed = value.trim();
+    if (trimmed.endsWith("%"))
+        return Number(trimmed.slice(0, -1)) / 100;
+    return Number(trimmed);
+}
+function hslToHex(hue, saturation, lightness) {
+    const h = (((hue % 360) + 360) % 360) / 360;
+    const s = clamp01(saturation / 100);
+    const l = clamp01(lightness / 100);
+    if (s === 0)
+        return rgbToHex(l, l, l);
+    const q = l < 0.5 ? l * (1 + s) : l + s - l * s;
+    const p = 2 * l - q;
+    const channel = (offset) => {
+        let t = h + offset;
+        if (t < 0)
+            t += 1;
+        if (t > 1)
+            t -= 1;
+        if (t < 1 / 6)
+            return p + (q - p) * 6 * t;
+        if (t < 1 / 2)
+            return q;
+        if (t < 2 / 3)
+            return p + (q - p) * (2 / 3 - t) * 6;
+        return p;
+    };
+    return rgbToHex(channel(1 / 3), channel(0), channel(-1 / 3));
+}
+/** `hsl()`/`hsla()` plus the bare shadcn triplet form (`222.2 47.4% 11.2%`). */
+function parseHsl(value) {
+    const trimmed = value.trim();
+    const fn = trimmed.match(/^hsla?\(([\s\S]+)\)$/i);
+    const body = fn?.[1]?.trim() ?? trimmed;
+    const slashParts = body.split("/");
+    if (slashParts.length > 2)
+        return null;
+    const rawParts = slashParts[0].includes(",")
+        ? slashParts[0].split(",").map((part) => part.trim())
+        : slashParts[0].trim().split(/\s+/);
+    const alpha = parseAlpha(slashParts[1] ?? (rawParts.length === 4 ? rawParts[3] : undefined));
+    if (!Number.isFinite(alpha) || alpha < 0.999)
+        return null;
+    const parts = rawParts.slice(0, 3);
+    if (parts.length !== 3 || !parts[1]?.endsWith("%") || !parts[2]?.endsWith("%"))
+        return null;
+    const hue = Number(parts[0]);
+    const saturation = Number(parts[1].slice(0, -1));
+    const lightness = Number(parts[2].slice(0, -1));
+    if (![hue, saturation, lightness].every(Number.isFinite))
+        return null;
+    return hslToHex(hue, saturation, lightness);
+}
+/** Bare space-separated `R G B` byte triplet (Tailwind `rgb(var(--x)) `style). */
+function parseRgbTriplet(value) {
+    const body = value.trim().replace(/^rgba?\(([\s\S]+)\)$/i, "$1");
+    const slashParts = body.split("/");
+    if (slashParts.length > 2)
+        return null;
+    const alpha = parseAlpha(slashParts[1]);
+    if (!Number.isFinite(alpha) || alpha < 0.999)
+        return null;
+    const parts = slashParts[0].trim().split(/[\s,]+/);
+    if (parts.length !== 3 || parts.some((part) => part.endsWith("%")))
+        return null;
+    const channels = parts.map((part) => Number(part));
+    if (channels.some((channel) => !Number.isFinite(channel) || channel < 0 || channel > 255))
+        return null;
+    return `#${channels.map((channel) => Math.round(channel).toString(16).padStart(2, "0")).join("")}`;
+}
+function linearToSrgb(value) {
+    const v = clamp01(value);
+    return v <= 0.0031308 ? 12.92 * v : 1.055 * Math.pow(v, 1 / 2.4) - 0.055;
+}
+/** CSS Color 4 §"OKLCH" — the spec's published OKLab→sRGB constants. */
+function parseOklch(value) {
+    const trimmed = value.trim();
+    const match = trimmed.match(/^oklch\(\s*([+-]?(?:\d+|\d*\.\d+)%?)\s+([+-]?(?:\d+|\d*\.\d+))\s+([+-]?(?:\d+|\d*\.\d+)(?:deg)?)\s*(?:\/\s*([^)]+))?\)$/i);
+    if (!match)
+        return null;
+    const alpha = parseAlpha(match[4]);
+    if (!Number.isFinite(alpha) || alpha < 0.999)
+        return null;
+    const lRaw = match[1];
+    const lightness = lRaw.endsWith("%") ? Number(lRaw.slice(0, -1)) / 100 : Number(lRaw);
+    const chroma = Number(match[2]);
+    const hue = Number(match[3].replace(/deg$/i, ""));
+    if (![lightness, chroma, hue].every(Number.isFinite))
+        return null;
+    const a = chroma * Math.cos((hue * Math.PI) / 180);
+    const b = chroma * Math.sin((hue * Math.PI) / 180);
+    const lPrime = lightness + 0.3963377774 * a + 0.2158037573 * b;
+    const mPrime = lightness - 0.1055613458 * a - 0.0638541728 * b;
+    const sPrime = lightness - 0.0894841775 * a - 1.291485548 * b;
+    const l = lPrime ** 3;
+    const m = mPrime ** 3;
+    const s = sPrime ** 3;
+    return rgbToHex(linearToSrgb(4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s), linearToSrgb(-1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s), linearToSrgb(-0.0041960863 * l - 0.7034186147 * m + 1.707614701 * s));
+}
+/** Any supported CSS color form to lowercase 6-digit hex; null when not one.
+ *  A trailing `!important` is declaration noise, not color — stripped. */
+export function normalizeColor(value) {
+    const bare = value.replace(/\s*!important\s*$/i, "");
+    return normalizeHex(bare) ?? parseRgbTriplet(bare) ?? parseHsl(bare) ?? parseOklch(bare);
+}
+/**
+ * Resolve `var(--x)` / `var(--x, fallback)` references against the collected
+ * declarations (bounded depth). Returns null when a reference cannot be
+ * resolved — theme.json carries fully-resolved primitives only (frozen theme
+ * contract), so an unresolved reference means the slot is not exactly readable.
+ */
+export function resolveCssVarRefs(value, vars, depth = 6) {
+    if (!value.includes("var("))
+        return value;
+    if (depth <= 0)
+        return null;
+    const byName = new Map(vars.filter((v) => !v.darkScope).map((v) => [v.name, v.value]));
+    const substituted = value.replace(/var\(\s*(--[\w-]+)\s*(?:,\s*([^()]+))?\)/g, (_m, name, fallback) => {
+        return byName.get(name) ?? fallback?.trim() ?? "var()";
+    });
+    if (substituted.includes("var()"))
+        return null; // unresolvable reference
+    return resolveCssVarRefs(substituted, vars, depth - 1);
+}
+/** px/rem length to canonical px; null for any other unit or expression. */
+export function normalizeLength(value) {
+    const trimmed = value.replace(/\s*!important\s*$/i, "").trim();
+    const px = trimmed.match(/^((?:\d+|\d*\.\d+))px$/);
+    if (px)
+        return `${Number(px[1])}px`;
+    const rem = trimmed.match(/^((?:\d+|\d*\.\d+))rem$/);
+    if (rem)
+        return `${Number(rem[1]) * 16}px`;
+    return null;
+}
+function relativeLuminance(hex) {
+    const normalized = normalizeHex(hex);
+    if (!normalized)
+        return 0;
+    const channels = [1, 3, 5].map((index) => parseInt(normalized.slice(index, index + 2), 16) / 255);
+    const [r, g, b] = channels.map((channel) => channel <= 0.04045
+        ? channel / 12.92
+        : ((channel + 0.055) / 1.055) ** 2.4);
+    return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
+/** Pick black or white by the larger WCAG contrast ratio against the accent. */
+export function contrastingText(accent) {
+    const luminance = relativeLuminance(accent);
+    const blackContrast = (luminance + 0.05) / 0.05;
+    const whiteContrast = 1.05 / (luminance + 0.05);
+    return blackContrast >= whiteContrast ? "#000000" : "#ffffff";
+}

package/dist/cli/theme/css-vars.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Minimal CSS custom-property declaration scanner. Not a full CSS parser —
+ * tracks brace depth and whether the enclosing block/at-rule looks dark-scoped
+ * (`.dark`, `[data-theme="dark"]`, `@media (prefers-color-scheme: dark)`).
+ * Good enough for design-token sheets; anything it misses is hand-editable output.
+ */
+export interface CssVarDecl {
+    name: string;
+    value: string;
+    file: string;
+    darkScope: boolean;
+}
+export declare function parseCssVars(css: string, file: string): CssVarDecl[];

package/dist/cli/theme/css-vars.js

@@ -0,0 +1,40 @@
+const DARK_SELECTOR = /(\.dark\b|\[data-theme=["']?dark["']?\]|prefers-color-scheme:\s*dark)/;
+export function parseCssVars(css, file) {
+    const out = [];
+    // Strip comments first.
+    const src = css.replace(/\/\*[\s\S]*?\*\//g, "");
+    // Stack of "is this block dark-scoped" flags.
+    const darkStack = [];
+    let selectorBuf = "";
+    // A declaration ends at `;`, at the closing `}` of its block (trailing
+    // semicolons are optional in CSS and absent in minified sheets), or at
+    // end-of-input.
+    const flushDecl = () => {
+        const decl = selectorBuf.trim();
+        const m = decl.match(/^(--[\w-]+)\s*:\s*(.+)$/s);
+        if (m && m[1] && m[2]) {
+            out.push({ name: m[1], value: m[2].trim(), file, darkScope: darkStack.some(Boolean) });
+        }
+        selectorBuf = "";
+    };
+    for (let i = 0; i < src.length; i++) {
+        const ch = src[i];
+        if (ch === "{") {
+            const parentDark = darkStack.some(Boolean);
+            darkStack.push(parentDark || DARK_SELECTOR.test(selectorBuf));
+            selectorBuf = "";
+        }
+        else if (ch === "}") {
+            flushDecl();
+            darkStack.pop();
+        }
+        else if (ch === ";") {
+            flushDecl();
+        }
+        else {
+            selectorBuf += ch;
+        }
+    }
+    flushDecl();
+    return out;
+}

package/dist/cli/theme/entry-candidates.d.ts

@@ -0,0 +1,5 @@
+/** Conventional Next.js entry-file paths (app-router layouts + pages-router
+ *  `_app`), relative to a target repo's root. extract-theme.ts reads the
+ *  first hit as the root layout: the anchor for the CSS import graph and part
+ *  of the LLM pass's evidence (next/font imports live here). */
+export declare const ENTRY_FILE_CANDIDATES: string[];

package/dist/cli/theme/entry-candidates.js

@@ -0,0 +1,22 @@
+/** Conventional Next.js entry-file paths (app-router layouts + pages-router
+ *  `_app`), relative to a target repo's root. extract-theme.ts reads the
+ *  first hit as the root layout: the anchor for the CSS import graph and part
+ *  of the LLM pass's evidence (next/font imports live here). */
+export const ENTRY_FILE_CANDIDATES = [
+    "app/layout.tsx",
+    "app/layout.jsx",
+    "app/layout.ts",
+    "app/layout.js",
+    "src/app/layout.tsx",
+    "src/app/layout.jsx",
+    "src/app/layout.ts",
+    "src/app/layout.js",
+    "pages/_app.tsx",
+    "pages/_app.jsx",
+    "pages/_app.ts",
+    "pages/_app.js",
+    "src/pages/_app.tsx",
+    "src/pages/_app.jsx",
+    "src/pages/_app.ts",
+    "src/pages/_app.js",
+];

package/dist/cli/theme/extract-theme.d.ts

@@ -0,0 +1,184 @@
+import { z } from "zod";
+/**
+ * Theme extraction, exact-then-staged (kill-list §B2, re-derived Task 2/4):
+ *
+ * 1. Allowlist fast-path — conventional shadcn/Tailwind tokens are read
+ *    EXACTLY (`--primary`, `--background`, `--font-sans`, ... and their
+ *    Tailwind-v4 `--color-*` spellings). No name scoring, no inference. This
+ *    file does ONLY this: `extractTheme` is fully deterministic — no model
+ *    call, no network, no credential.
+ * 2. Whatever the allowlist leaves unfilled rides init's consent-gated AI
+ *    pass (`runAiExtraction` → `runStagedExtraction`'s theme stage, in
+ *    `../extract/stages.ts`) — the SAME harness seam as the tool-description
+ *    polish, over Read/Glob/Grep instead of a fixed evidence-file set.
+ *    `applyThemeDraft` below merges that stage's parsed artifact back onto
+ *    this file's exact-only summary.
+ * 3. Anything neither path fills falls back to neutral defaults and is
+ *    reported as defaulted — a miss is visible, never a silent wrong brand.
+ *
+ * theme.json stays the editable source of truth; init shows the palette for
+ * a one-glance confirm and asks only about model-flagged uncertainty.
+ */
+export interface ThemeSlotValues {
+    accent: string;
+    accentText: string;
+    background: string;
+    border: string;
+    danger: string;
+    surface: string;
+    text: string;
+    mutedText: string;
+    radius: string;
+    fontFamily: string;
+    headingFamily: string;
+    baseSize: string;
+    density: "compact" | "comfortable";
+    motion: "full" | "reduced";
+}
+export interface ThemeUncertainty {
+    slot: keyof ThemeSlotValues;
+    note: string;
+}
+export interface ThemeSummary {
+    /** Fully resolved values used to assemble the frozen VendoTheme contract. */
+    slots: ThemeSlotValues;
+    /** slot -> provenance: the exact token name, "(model)", or a derivation. */
+    matched: Record<string, string>;
+    /** Slots that fell back to neutral defaults (reported, never silent). */
+    defaulted: string[];
+    /** Model-flagged genuine uncertainty — init's only theme question trigger. */
+    uncertain: ThemeUncertainty[];
+    usedModel: boolean;
+    errors: string[];
+    hasDarkVariant: boolean;
+    /** Slots the exact allowlist pass did not read exactly — the staged theme
+     *  pass's `needed` input, and the only slots `applyThemeDraft` may fill. */
+    needed: SlotKey[];
+    /** The CSS/layout/tailwind-config paths the context gatherer collected,
+     *  repo-relative — seeded as evidence-path hints for the staged pass. */
+    evidencePaths: string[];
+}
+type SlotKey = keyof ThemeSlotValues;
+/** Brand-defining slots: any of these missing after the exact pass triggers
+ *  the staged theme pass, and only doubt about these becomes an init
+ *  question. The remaining slots (accentText, headingFamily, baseSize,
+ *  density, motion) derive or default safely — accentText derives from the
+ *  accent by WCAG contrast, headingFamily inherits fontFamily, and the rest
+ *  have safe brand-neutral defaults — so they never trigger a call or a
+ *  question on their own. */
+export declare const BRAND_SLOTS: readonly SlotKey[];
+export declare const modelThemeSchema: z.ZodObject<{
+    slots: z.ZodObject<{
+        accent: z.ZodOptional<z.ZodString>;
+        accentText: z.ZodOptional<z.ZodString>;
+        background: z.ZodOptional<z.ZodString>;
+        border: z.ZodOptional<z.ZodString>;
+        danger: z.ZodOptional<z.ZodString>;
+        surface: z.ZodOptional<z.ZodString>;
+        text: z.ZodOptional<z.ZodString>;
+        mutedText: z.ZodOptional<z.ZodString>;
+        radius: z.ZodOptional<z.ZodString>;
+        fontFamily: z.ZodOptional<z.ZodString>;
+        headingFamily: z.ZodOptional<z.ZodString>;
+        baseSize: z.ZodOptional<z.ZodString>;
+        density: z.ZodOptional<z.ZodEnum<["compact", "comfortable"]>>;
+        motion: z.ZodOptional<z.ZodEnum<["full", "reduced"]>>;
+    }, "strip", z.ZodTypeAny, {
+        text?: string | undefined;
+        radius?: string | undefined;
+        density?: "compact" | "comfortable" | undefined;
+        motion?: "full" | "reduced" | undefined;
+        background?: string | undefined;
+        surface?: string | undefined;
+        accent?: string | undefined;
+        accentText?: string | undefined;
+        danger?: string | undefined;
+        border?: string | undefined;
+        fontFamily?: string | undefined;
+        headingFamily?: string | undefined;
+        baseSize?: string | undefined;
+        mutedText?: string | undefined;
+    }, {
+        text?: string | undefined;
+        radius?: string | undefined;
+        density?: "compact" | "comfortable" | undefined;
+        motion?: "full" | "reduced" | undefined;
+        background?: string | undefined;
+        surface?: string | undefined;
+        accent?: string | undefined;
+        accentText?: string | undefined;
+        danger?: string | undefined;
+        border?: string | undefined;
+        fontFamily?: string | undefined;
+        headingFamily?: string | undefined;
+        baseSize?: string | undefined;
+        mutedText?: string | undefined;
+    }>;
+    uncertain: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        slot: z.ZodString;
+        note: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        slot: string;
+        note: string;
+    }, {
+        slot: string;
+        note: string;
+    }>, "many">>;
+}, "strip", z.ZodTypeAny, {
+    slots: {
+        text?: string | undefined;
+        radius?: string | undefined;
+        density?: "compact" | "comfortable" | undefined;
+        motion?: "full" | "reduced" | undefined;
+        background?: string | undefined;
+        surface?: string | undefined;
+        accent?: string | undefined;
+        accentText?: string | undefined;
+        danger?: string | undefined;
+        border?: string | undefined;
+        fontFamily?: string | undefined;
+        headingFamily?: string | undefined;
+        baseSize?: string | undefined;
+        mutedText?: string | undefined;
+    };
+    uncertain?: {
+        slot: string;
+        note: string;
+    }[] | undefined;
+}, {
+    slots: {
+        text?: string | undefined;
+        radius?: string | undefined;
+        density?: "compact" | "comfortable" | undefined;
+        motion?: "full" | "reduced" | undefined;
+        background?: string | undefined;
+        surface?: string | undefined;
+        accent?: string | undefined;
+        accentText?: string | undefined;
+        danger?: string | undefined;
+        border?: string | undefined;
+        fontFamily?: string | undefined;
+        headingFamily?: string | undefined;
+        baseSize?: string | undefined;
+        mutedText?: string | undefined;
+    };
+    uncertain?: {
+        slot: string;
+        note: string;
+    }[] | undefined;
+}>;
+/** Deterministic validation of a proposed slot value (model or human). */
+export declare function validateSlotValue(slot: SlotKey, raw: string): string | null;
+export declare function extractTheme(targetDir: string): Promise<ThemeSummary>;
+/**
+ * Merges a parsed theme-stage artifact (`modelThemeSchema`) onto an
+ * exact-only `ThemeSummary` — the precedence law (kill-list §B2, Task 2):
+ * exact reads are never overwritten; only `needed` slots may be filled; every
+ * proposed value passes through `validateSlotValue` (invalid values are
+ * ignored, the slot stays defaulted/derived); a model-provided accentText
+ * stands; accentText re-derives by contrast only when the model filled
+ * accent but not accentText and accentText itself wasn't an exact read;
+ * headingFamily inherits fontFamily under the mirror condition.
+ */
+export declare function applyThemeDraft(summary: ThemeSummary, draft: z.infer<typeof modelThemeSchema>): ThemeSummary;
+export {};