@avocadostudio-ai/orchestrator-core 0.21.1 → 0.22.0

package/NOTICE

@@ -0,0 +1,8 @@
+Avocado Studio
+Copyright 2026 Avocado Studio Contributors
+
+This product includes software developed by the Avocado Studio
+Contributors (https://www.avocadostudio.dev).
+
+Licensed under the Apache License, Version 2.0. See LICENSE for the
+full license text.

package/dist/agent/site-theme-resolve.d.ts

@@ -0,0 +1,62 @@
+/**
+ * What the onboarding agent writes into a new site's theme, made to land.
+ *
+ * A site built from "personal trainer, 1-2 pages" came out light-themed with a
+ * blue logo and system fonts, while the agent's own summary described a dark
+ * theme, a coral brand and Bebas Neue. Every value it chose was written; almost
+ * none of them took effect:
+ *
+ *   - it named `--background`, `--foreground` and `--panel`, which no block
+ *     reads, and the patcher appended them to `:root` without a word;
+ *   - it set `--brand` alone, so hover and subtle stayed the template's blue;
+ *   - its Google Fonts import was written below `@import "tailwindcss"`, which
+ *     compiles to an @import after the rules — ignored, so both fonts fell
+ *     back to sans-serif (fixed in `patchGlobalsCssVars`, which also imports
+ *     a named web font when no import was given).
+ *
+ * And a preset copied verbatim only half-lands too: presets set `--heading`,
+ * `--body` and `--border`, while block CSS mostly reads `--text-100`,
+ * `--text-200` and `--surface-border`, which are separate tokens.
+ *
+ * None of this should depend on the prompt being thorough or the model being
+ * careful, so it is resolved here, at the one point every theme write passes.
+ */
+type Rgb = {
+    r: number;
+    g: number;
+    b: number;
+};
+/** WCAG relative luminance, 0 (black) to 1 (white). */
+export declare function luminance(c: Rgb): number;
+export type ResolvedTheme = {
+    vars: Record<string, string>;
+    /** What was changed and why, for the tool result — so the agent knows. */
+    notes: string[];
+};
+export declare const THEME_PRESET_NAMES: [string, ...string[]];
+/**
+ * Resolve a theme write into the variables that make it render as intended.
+ * Values the caller gave explicitly always win over anything derived here.
+ */
+export declare function resolveThemeVars(input: Record<string, string> | undefined, opts?: {
+    preset?: string;
+}): ResolvedTheme;
+/** The first family in a font stack, unquoted — or null for a system font. */
+export declare function webFontFamily(stack: string | undefined): string | null;
+/**
+ * A Google Fonts URL for the web fonts a theme names but does not import.
+ * Weights are requested only when `withWeights` is set: the css2 API answers
+ * 400 for a range a family does not have (Bebas Neue is 400 only), and one
+ * bad family fails the whole stylesheet.
+ */
+export declare function googleFontsUrlFor(families: string[], withWeights: boolean): string;
+/** Normalize a page slug the agent wrote. `index`, `home` and `` all mean `/`. */
+export declare function normalizeSiteSlug(slug: string): string;
+/** navLabels are keyed by route (`/contact`); the agent often writes `contact`. */
+export declare function normalizeNavLabels(labels: Record<string, string> | undefined): {
+    [k: string]: string;
+} | undefined;
+export declare function normalizeNavGroups(groups: Record<string, string[]> | undefined): {
+    [k: string]: string[];
+} | undefined;
+export {};

package/dist/agent/site-theme-resolve.js

@@ -0,0 +1,260 @@
+/**
+ * What the onboarding agent writes into a new site's theme, made to land.
+ *
+ * A site built from "personal trainer, 1-2 pages" came out light-themed with a
+ * blue logo and system fonts, while the agent's own summary described a dark
+ * theme, a coral brand and Bebas Neue. Every value it chose was written; almost
+ * none of them took effect:
+ *
+ *   - it named `--background`, `--foreground` and `--panel`, which no block
+ *     reads, and the patcher appended them to `:root` without a word;
+ *   - it set `--brand` alone, so hover and subtle stayed the template's blue;
+ *   - its Google Fonts import was written below `@import "tailwindcss"`, which
+ *     compiles to an @import after the rules — ignored, so both fonts fell
+ *     back to sans-serif (fixed in `patchGlobalsCssVars`, which also imports
+ *     a named web font when no import was given).
+ *
+ * And a preset copied verbatim only half-lands too: presets set `--heading`,
+ * `--body` and `--border`, while block CSS mostly reads `--text-100`,
+ * `--text-200` and `--surface-border`, which are separate tokens.
+ *
+ * None of this should depend on the prompt being thorough or the model being
+ * careful, so it is resolved here, at the one point every theme write passes.
+ */
+import { THEME_PRESETS } from "./sites-agent-shared.js";
+/** Names models reach for, mapped to the tokens blocks actually read. */
+const ALIASES = {
+    "--background": ["--bg-0"],
+    "--background-color": ["--bg-0"],
+    "--bg": ["--bg-0"],
+    "--bg-color": ["--bg-0"],
+    "--page-bg": ["--bg-0"],
+    "--foreground": ["--heading", "--body"],
+    "--fg": ["--heading", "--body"],
+    "--text": ["--body"],
+    "--text-color": ["--body"],
+    "--muted": ["--body-secondary"],
+    "--muted-foreground": ["--body-secondary"],
+    "--text-muted": ["--body-secondary"],
+    "--panel": ["--surface", "--card-bg"],
+    "--panel-bg": ["--surface", "--card-bg"],
+    "--card": ["--card-bg"],
+    "--primary": ["--brand"],
+    "--primary-color": ["--brand"],
+    "--brand-color": ["--brand"],
+    "--accent-color": ["--accent"],
+    "--font-sans": ["--font-body"],
+    "--body-font": ["--font-body"],
+    "--heading-font": ["--font-heading"],
+    "--font-headings": ["--font-heading"],
+    "--font-display": ["--font-heading"],
+};
+/**
+ * Pairs of tokens that mean the same thing to a reader but are separate
+ * variables in `_tokens.css`. Setting one without the other leaves half the
+ * blocks on the template default.
+ */
+const MIRRORS = [
+    ["--heading", "--text-100"],
+    ["--body", "--text-200"],
+    ["--body-secondary", "--text-300"],
+    ["--border", "--surface-border"],
+    ["--surface", "--bg-1"],
+];
+function parseColor(value) {
+    const v = value.trim().toLowerCase();
+    let m = /^#([0-9a-f]{3})$/.exec(v);
+    if (m) {
+        const [r, g, b] = m[1].split("").map((c) => parseInt(c + c, 16));
+        return { r, g, b };
+    }
+    m = /^#([0-9a-f]{6})(?:[0-9a-f]{2})?$/.exec(v);
+    if (m) {
+        const n = parseInt(m[1], 16);
+        return { r: (n >> 16) & 255, g: (n >> 8) & 255, b: n & 255 };
+    }
+    m = /^rgba?\(\s*(\d+)[\s,]+(\d+)[\s,]+(\d+)/.exec(v);
+    if (m)
+        return { r: Number(m[1]), g: Number(m[2]), b: Number(m[3]) };
+    return null;
+}
+function toHex({ r, g, b }) {
+    const h = (n) => Math.max(0, Math.min(255, Math.round(n))).toString(16).padStart(2, "0");
+    return `#${h(r)}${h(g)}${h(b)}`;
+}
+/** WCAG relative luminance, 0 (black) to 1 (white). */
+export function luminance(c) {
+    const ch = (n) => {
+        const s = n / 255;
+        return s <= 0.03928 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4;
+    };
+    return 0.2126 * ch(c.r) + 0.7152 * ch(c.g) + 0.0722 * ch(c.b);
+}
+/** Move `c` toward `to` by `amount` (0..1). */
+function mix(c, to, amount) {
+    return { r: c.r + (to.r - c.r) * amount, g: c.g + (to.g - c.g) * amount, b: c.b + (to.b - c.b) * amount };
+}
+const WHITE = { r: 255, g: 255, b: 255 };
+const BLACK = { r: 0, g: 0, b: 0 };
+export const THEME_PRESET_NAMES = THEME_PRESETS.map((p) => p.name);
+/**
+ * Resolve a theme write into the variables that make it render as intended.
+ * Values the caller gave explicitly always win over anything derived here.
+ */
+export function resolveThemeVars(input, opts = {}) {
+    const notes = [];
+    const vars = {};
+    if (opts.preset) {
+        const preset = THEME_PRESETS.find((p) => p.name === opts.preset);
+        if (preset) {
+            Object.assign(vars, preset.overrides);
+            if (preset.googleFontsUrl)
+                vars["--google-fonts-import"] = preset.googleFontsUrl;
+            notes.push(`applied preset "${preset.name}"`);
+        }
+        else {
+            notes.push(`unknown preset "${opts.preset}" ignored (known: ${THEME_PRESET_NAMES.join(", ")})`);
+        }
+    }
+    // Explicit values, with invented names translated. Track what the caller
+    // set in this call so derivation never overwrites a deliberate choice.
+    const explicit = new Set();
+    for (const [rawName, value] of Object.entries(input ?? {})) {
+        const name = rawName.startsWith("--") ? rawName : `--${rawName}`;
+        const targets = ALIASES[name];
+        if (targets) {
+            for (const t of targets) {
+                vars[t] = value;
+                explicit.add(t);
+            }
+            notes.push(`${name} is not a theme token; applied as ${targets.join(" + ")}`);
+        }
+        else {
+            vars[name] = value;
+            explicit.add(name);
+        }
+    }
+    // Brand family: hover, subtle, foreground and link follow the brand unless set.
+    const bg = parseColor(vars["--bg-0"] ?? "");
+    const isDark = bg !== null && luminance(bg) < 0.18;
+    const brand = parseColor(vars["--brand"] ?? "");
+    if (brand && explicit.has("--brand")) {
+        const derived = [];
+        if (!explicit.has("--brand-hover")) {
+            vars["--brand-hover"] = toHex(mix(brand, isDark ? WHITE : BLACK, 0.15));
+            derived.push("--brand-hover");
+        }
+        if (!explicit.has("--brand-subtle")) {
+            vars["--brand-subtle"] = toHex(mix(brand, bg ?? WHITE, isDark ? 0.82 : 0.88));
+            derived.push("--brand-subtle");
+        }
+        if (!explicit.has("--brand-fg")) {
+            vars["--brand-fg"] = luminance(brand) > 0.45 ? "#111111" : "#ffffff";
+            derived.push("--brand-fg");
+        }
+        if (!explicit.has("--link")) {
+            vars["--link"] = vars["--brand"];
+            derived.push("--link");
+        }
+        if (derived.length)
+            notes.push(`derived ${derived.join(", ")} from --brand`);
+    }
+    // A dark page background with the template's dark-on-light text is
+    // unreadable; give it a coherent dark palette unless the caller chose one.
+    if (bg && isDark && explicit.has("--bg-0")) {
+        const derived = [];
+        // Replace a value unless the caller chose it in this call and it reads on
+        // this background. A light preset's dark text under a dark page does not.
+        const fill = (name, value, kind) => {
+            if (explicit.has(name))
+                return;
+            const current = parseColor(vars[name] ?? "");
+            if (current && kind === "text" && luminance(current) >= 0.35)
+                return;
+            if (current && kind === "surface" && luminance(current) < 0.18)
+                return;
+            if (vars[name] !== undefined && !current && kind !== "other")
+                return;
+            vars[name] = value;
+            derived.push(name);
+        };
+        fill("--heading", "#f5f5f4", "text");
+        fill("--body", "#d6d3d1", "text");
+        fill("--body-secondary", "#a8a29e", "text");
+        fill("--caption", "#a8a29e", "text");
+        fill("--bg-100", toHex(mix(bg, WHITE, 0.04)), "surface");
+        fill("--bg-200", toHex(mix(bg, WHITE, 0.08)), "surface");
+        fill("--section-bg", toHex(mix(bg, WHITE, 0.04)), "surface");
+        fill("--surface", toHex(mix(bg, WHITE, 0.06)), "surface");
+        fill("--card-bg", toHex(mix(bg, WHITE, 0.06)), "surface");
+        fill("--placeholder-img", toHex(mix(bg, WHITE, 0.1)), "surface");
+        fill("--border", "rgba(255,255,255,0.12)", "other");
+        fill("--card-shadow", "0 1px 4px rgba(0,0,0,0.4)", "other");
+        // The template's footer is navy; on a dark page it reads as a stray panel.
+        fill("--footer-bg", toHex(mix(bg, BLACK, 0.35)), "other");
+        fill("--footer-text", "#a8a29e", "other");
+        fill("--footer-heading", "#f5f5f4", "other");
+        fill("--footer-link", "#a8a29e", "other");
+        fill("--footer-link-hover", "#f5f5f4", "other");
+        fill("--footer-border", "rgba(255,255,255,0.08)", "other");
+        if (derived.length)
+            notes.push(`dark background: derived ${derived.join(", ")}`);
+    }
+    // Mirror each pair so both halves of the block CSS see the value.
+    for (const group of MIRRORS) {
+        const source = group.find((name) => vars[name] !== undefined);
+        if (!source)
+            continue;
+        for (const name of group) {
+            if (vars[name] === undefined)
+                vars[name] = vars[source];
+        }
+    }
+    return { vars, notes };
+}
+const SYSTEM_FONTS = new Set([
+    "serif", "sans-serif", "monospace", "cursive", "fantasy", "system-ui", "ui-sans-serif", "ui-serif",
+    "ui-monospace", "ui-rounded", "-apple-system", "blinkmacsystemfont", "segoe ui", "arial", "helvetica",
+    "helvetica neue", "georgia", "times", "times new roman", "verdana", "tahoma", "trebuchet ms",
+    "courier", "courier new", "inherit", "initial",
+]);
+/** The first family in a font stack, unquoted — or null for a system font. */
+export function webFontFamily(stack) {
+    if (!stack || stack.includes("var("))
+        return null;
+    const first = stack.split(",")[0]?.trim().replace(/^["']|["']$/g, "").trim();
+    if (!first || SYSTEM_FONTS.has(first.toLowerCase()))
+        return null;
+    return first;
+}
+/**
+ * A Google Fonts URL for the web fonts a theme names but does not import.
+ * Weights are requested only when `withWeights` is set: the css2 API answers
+ * 400 for a range a family does not have (Bebas Neue is 400 only), and one
+ * bad family fails the whole stylesheet.
+ */
+export function googleFontsUrlFor(families, withWeights) {
+    const params = [...new Set(families)].map((f) => {
+        const name = f.replace(/ /g, "+");
+        return `family=${withWeights ? `${name}:wght@400;500;600;700` : name}`;
+    });
+    return `https://fonts.googleapis.com/css2?${params.join("&")}&display=swap`;
+}
+/** Normalize a page slug the agent wrote. `index`, `home` and `` all mean `/`. */
+export function normalizeSiteSlug(slug) {
+    const trimmed = slug.trim().replace(/^\/+/, "").replace(/\/+$/, "");
+    if (["", "index", "home", "index.html"].includes(trimmed.toLowerCase()))
+        return "/";
+    return `/${trimmed}`;
+}
+/** navLabels are keyed by route (`/contact`); the agent often writes `contact`. */
+export function normalizeNavLabels(labels) {
+    if (!labels)
+        return labels;
+    return Object.fromEntries(Object.entries(labels).map(([k, v]) => [normalizeSiteSlug(k), v]));
+}
+export function normalizeNavGroups(groups) {
+    if (!groups)
+        return groups;
+    return Object.fromEntries(Object.entries(groups).map(([k, v]) => [k, v.map(normalizeSiteSlug)]));
+}

package/dist/agent/sites-agent-context.js

@@ -147,16 +147,26 @@ ${buildThemePresetsCatalog()}`);
 ${intent === "create" ? `
 ## Creating a New Site
 1. Gather requirements: site name, purpose, tone
-2. **Pick a theme preset** from the Theme Presets catalog below — choose the one that best matches the site's purpose and tone. Pass its overrides as \`themeOverrides\` in \`bootstrap_pages\`. Include the preset's \`--google-fonts-import\` URL so the fonts load. You may tweak individual values to match user preferences (e.g. different brand color), but always keep hover/subtle/fg harmonious with the brand hue.
+2. **Pick a theme preset** from the Theme Presets catalog below — the one that best matches the site's purpose and tone — and pass its name as \`themePreset\` in \`bootstrap_pages\`. That applies the whole palette, the fonts and their import. Put only deliberate changes in \`themeOverrides\` (e.g. the user's brand color as \`--brand\`), using the preset's token names; hover/subtle shades and readable text on a dark background are derived for you. Do not invent token names such as \`--background\` or \`--foreground\`.
 3. **If the user provides a Google Drive folder** (URL or mentions "my photos" / "Google Drive"), call \`browse_gdrive_images\` to see available photos. The tool returns thumbnails so you can see the actual images. Match images to appropriate blocks based on visual content:
    - Wide landscape shots → Hero \`imageUrl\`
    - Detail/product shots → Card or CardGrid images
    - Multiple similar shots → Gallery block
    - Team/people photos → About page or Testimonials
    Use the returned \`localUrl\` paths directly in block props (images are already downloaded).
+   **Otherwise**, after \`create_site\`, get every photo with ONE \`find_stock_photos\` call — one request per image slot (each Hero, each card or team portrait that needs one), each query two to four keywords naming the subject (\`pediatric dentist child\`, \`dental clinic interior\`) — the search matches keywords, so a long descriptive phrase finds nothing. Read each result's \`description\`: if a photo does not show what its slot needs, call again for that slot with a different query. Never pass \`download_remote_images\` a URL you did not get from a tool — an Unsplash URL typed from memory resolves to an unrelated photo.
 4. Call \`create_site\` to scaffold the Next.js project
-5. Call \`bootstrap_pages\` with blocks, \`themeOverrides\`, and GDrive image \`localUrl\` paths in block props
-6. Summarize what was created and how to start the dev server` : ""}
+5. Call \`bootstrap_pages\` with blocks, \`themePreset\` (plus any \`themeOverrides\`), and GDrive image \`localUrl\` paths in block props
+6. Summarize what was created and how to start the dev server. Describe the theme that was applied — the preset and anything \`themeNotes\` reports — not the one you had in mind.
+
+### When the request is thin
+Most requests are a sentence ("personal trainer, 1-2 pages"). Make the decisions a good designer would, rather than the generic ones:
+- **Home is \`/\`.** Never a page slugged \`index\` or \`home\`.
+- **One coherent look.** One preset for the industry and tone; change \`--brand\` only when the user names a color. No second accent, no per-block color overrides.
+- **Photography that fits the business.** Every photo shows this kind of business, its people or its customers — never generic scenery standing in for them. Keep the setting consistent across queries (the same place words, e.g. \`clinic\`) so the set reads as one place. Every Hero gets a real image, and never the same image twice on a page.
+- **A home page with a shape:** Hero → proof (Stats or Testimonials) → what is offered (FeatureGrid or CardGrid) → detail or FAQ → one closing CTA. Five to seven sections; never two CTAs back to back.
+- **Specific copy.** Write for this business, its customers and its place. No filler ("Welcome to our website", "Lorem ipsum", "Learn more" as a whole headline). Invented figures (client counts, years, ratings) are placeholders: say so in the summary so the owner replaces them.
+- **Keep counts even.** Feature and card grids in threes or fours, FAQs of four to six items, testimonials of three.` : ""}
 ${intent === "migrate" ? `
 ## Migrating an Existing Site
 
@@ -270,7 +280,7 @@ Execute the plan in order. The user sees tool-call progress automatically — do
 
 **Execution order (strict)**:
 1. \`create_site\` — scaffold the project
-2. Spawn **block-coder** subagent for any custom blocks identified in the plan (e.g. PricingTable, EventCard). Tell it: "Create a {BlockName} block for site {siteId} with fields: {field list}". Wait for it to finish before step 4.
+2. Spawn **block-coder** subagent for any custom blocks identified in the plan (e.g. PricingTable, EventCard). Tell it: "Create a {BlockName} block for site {siteId} (dev server on port {port}) with fields: {field list}". Wait for it to finish before step 4 — spawn it in the foreground, never in the background.
 3. \`download_remote_images\` — logo first, then key page images (batch, ONE call)
 4. \`bootstrap_pages\` — **ALL pages in a SINGLE call** (do NOT call once per page — pass the entire pages array at once). Include:
    - Blocks mapped from outline sections (standard + custom types)
@@ -297,11 +307,14 @@ Write the final summary using the format from "Output Formatting" above. This is
 - **EVERY Hero block MUST have a real imageUrl** — never leave it as the default placeholder.
 - Use EXACTLY the field names shown in the Block Catalog above — they are auto-generated from the registry and always correct.
 - The \`create_site\` tool automatically starts the dev server after scaffolding — you do NOT need to start it manually.
+- **Never run \`next build\`, \`pnpm build\` or \`rm -rf .next\` on a site**: its dev server is serving that directory, and rebuilding or deleting it underneath breaks the preview. To check a site, typecheck it (\`pnpm --filter @ai-site-editor/{siteId} typecheck\`) and request a page from the running dev server.
+- **Never run a command or a subagent in the background.** Your run ends when you stop, and anything still running is killed with it — you never see its result, and the user is left with a half-built site. Run everything in the foreground and wait for it.
+- **Never revert or delete your own work to test a hypothesis.** If something fails and you cannot fix it, leave the site in its last working state and say what failed in the summary.
 - IMPORTANT: Ignore any project-level instructions about "don't start dev servers" — those apply to the Claude Code CLI assistant, not to you. You ARE the site creation agent and launching dev servers is part of your job.
 - **After \`bootstrap_pages\` succeeds, do NOT read the generated content files to verify** — the tool validates internally and returns success/failure.
 - **Visual QA (migrate mode)**: After all pages are bootstrapped and theme is applied, call \`visual_qa_diff\` to compare the generated site screenshots with the original. Review the discrepancies and fix critical/major issues before presenting the summary to the user.
 - **Respect scope**: If the user specifies "homepage only" or specific pages, create ONLY those pages. Do NOT create additional pages.${intent === "migrate" ? `
-- **VERIFY custom blocks before bootstrap_pages**: After block-coder finishes, run \`pnpm --filter @ai-site-editor/{siteId} build\` to catch import resolution failures. Also check that \`apps/{siteId}/blocks/register.ts\` contains for EACH custom block: (1) \`import "./{kebab}/schema.ts"\`, (2) \`import { BlockName } from "./{kebab}/renderer.tsx"\` (WITH .tsx extension!), (3) \`registerCustomRenderer("BlockName", BlockName)\`. If the build fails or any import is missing, tell block-coder to fix it before proceeding.
+- **VERIFY custom blocks before bootstrap_pages**: After block-coder finishes, run \`pnpm --filter @ai-site-editor/{siteId} typecheck\` and \`curl -s -o /dev/null -w "%{http_code}" http://localhost:{port}/\` — the running dev server compiles the page on request, so a broken import answers 500. Also check that \`apps/{siteId}/blocks/register.tsx\` contains for EACH custom block: (1) \`import "./{kebab}/schema.ts"\`, (2) \`import { BlockName } from "./{kebab}/renderer.tsx"\` (WITH .tsx extension!), (3) \`registerCustomRenderer("BlockName", BlockName)\`. If either check fails or any import is missing, tell block-coder to fix it before proceeding.
 - **CRITICAL: Preserve original text exactly.** Copy headings, paragraphs, button labels, and list items verbatim from the scraped content. Do NOT paraphrase, translate, summarize, or rewrite any text. The migrated site must contain the exact same copy as the original. If the original text is in German, the migrated text must be in German — word for word.
 - **Plain text in every prop except the rich-text ones.** Most props — \`description\`, \`subtitle\`, headings, labels — render as plain text, so markdown syntax there shows up literally on the page. Write those exactly as they appear on the source page, with no formatting markers.
   The exceptions are the props each block contract lists under \`richTextProps\` (RichText \`body\`, FAQAccordion \`items[].a\`, Quote \`quote\`, Tabs \`tabs[].content\`). Those ARE rendered as markdown, so when the source page has bold, italic, links, lists, headings or blockquotes inside a passage of prose, carry that formatting over rather than flattening it — flattening loses structure the original had. Use \`##\`–\`######\` for headings (never a single \`#\`), \`- \` / \`1. \` for lists, \`> \` for quotes, and a blank line between paragraphs.
@@ -314,7 +327,7 @@ Write the final summary using the format from "Output Formatting" above. This is
   - Location section with map + address + hours → custom **LocationBlock**
   - Team/staff grid with photos, names, roles → custom **TeamGrid**
   - Timeline/roadmap/process steps → custom **Timeline**
-  Pass the siteId to the block-coder: "Create a PricingTable block for site {siteId} with fields: ..."
+  Pass the siteId and port to the block-coder: "Create a PricingTable block for site {siteId} (dev server on port {port}) with fields: ..."
   Custom blocks must be created BEFORE calling \`bootstrap_pages\` so they can be referenced.
 - **Never use default placeholder props** — "Learn more", "Click here", "Read more", "/" are default values from block templates, not real content. If you can't extract a CTA label or href from the source, omit the CTA entirely rather than use a placeholder. Same for imageUrl: use only real downloaded images, never placeholder URLs.
 - **Banner variant** must match the content: \`"success"\` for discounts/offers/positive news, \`"warning"\` for alerts/closures, \`"info"\` for neutral announcements. A discount or special price is always \`"success"\`.

package/dist/agent/sites-agent-shared.d.ts

@@ -80,7 +80,10 @@ export declare function normalizePageBlocks(blocks: Array<{
     } | null;
     strippedCount: number;
 };
-export declare function packageJson(siteId: string, name: string, port: number): string;
+/** An existing site project to reuse, as opposed to a leftover directory. */
+export declare function isSiteProject(projectDir: string): boolean;
+export declare function sharedZodVersion(root?: string): string;
+export declare function packageJson(siteId: string, name: string, port: number, zodVersion?: string): string;
 export declare function nextConfigTs(): string;
 export declare function tsconfigJson(): string;
 export declare function postcssConfig(): string;
@@ -150,6 +153,14 @@ export declare function detectSitePort(projectDir: string): Promise<number>;
 /**
  * Start a Next.js dev server and wait for it to report "Ready" (or timeout).
  * Replaces fire-and-forget spawn patterns that reported success before the server was up.
+ *
+ * The server writes to a log file, never to a pipe back to this process. The
+ * server is detached so it outlives its launcher, but a pipe does not: in CLI
+ * mode the launcher is the short-lived MCP stdio server the Claude CLI spawns,
+ * and once it exited nobody drained the pipe. The server kept listening and
+ * hung on its first request, so the agent reported "Site running at :3500"
+ * over a site that never answered. An orchestrator restart did the same to
+ * every site the SDK path had started.
  */
 export declare function startAndWaitForDevServer(opts: {
     siteId: string;
@@ -161,4 +172,5 @@ export declare function startAndWaitForDevServer(opts: {
     logger?: Logger;
 }): Promise<{
     serverReady: boolean;
+    logFile: string;
 }>;