frontpage-host 0.1.16 → 0.1.17

package/AGENTS.md

@@ -26,17 +26,22 @@ Frontpage has two surfaces:
 | **Staging** | `https://<subdomain>.frontpage.host` | Working copy for edits, previews, and review |
 | **Production** | Custom domain (when connected), after **publish** | What end customers see on the live domain |
 
-**How changes become visible on staging**
+**Three clocks (do not collapse these)**
 
-- `frontpage push`, `frontpage prompt`, and `frontpage edit` update the site branch and the **staging** surface.
-- After a push or agent run finishes building, changes are on the site branch behind `https://<subdomain>.frontpage.host`.
-- There is **no separate “deploy to staging” step** agents must run. Do not treat `frontpage deploy wait` as “going live.” At most it waits for an in-flight build to finish before you open the subdomain to review.
+1. **Git tip** — `frontpage push` / `prompt` / `edit` land a new SHA. Fast.
+2. **Site compile** — Fly (or Vercel on legacy hosts) builds that SHA. This is what visitors get. Poll `GET /api/v1/sites/<slug>/deploy` until `ready` is true (`liveCommit` equals the tip).
+3. **Editor agent run** — a chat job (`queued` / `running` / `deploying`). `frontpage runs wait` watches this clock only.
+
+- After the compile is ready, staging is `https://<subdomain>.frontpage.host`.
+- There is **no separate “deploy to staging” step**. `frontpage deploy wait` waits for agent-run idle (if a run is in flight) **and** for the tip compile. It is not go-live.
+- A file-only push has **no** agent run. Do not treat a historical run that says “Your changes are live” as this push.
 - `frontpage open` opens the subdomain staging URL.
 - **Custom-domain caveat:** `<subdomain>.frontpage.host` is publicly viewable (anonymous) only when the site has **no** custom domain and subdomain sharing is public. If a custom domain is connected (e.g. `arbiter.wiki`), the subdomain is often **owner-private** — an unauthenticated browser/curl may see the app login page. That login wall is **not** a failed push. Anonymous public review is then on the **published custom domain**; editing the subdomain still needs an owner browser session (CLI API key ≠ browser cookie).
 
 **Production publish is a deliberate promote**
 
-- `frontpage publish` copies the current **staging tip** to **production** (custom domain / published site).
+- `frontpage publish` copies the last **ready staging compile** to **production** (custom domain / published site). It 409s if the tip is not compiled yet. Use `frontpage publish --wait` (or `deploy wait` then `publish`) so you do not promote the previous build.
+- After publish, compare `<meta name="frontpage:commit">` on the custom domain to the push SHA. History’s `P` marker is the stamped tip; it is only trustworthy when it matches the SHA in `productionUrl`.
 - **Never run `publish` or `unpublish` unless the user explicitly asked**, or the user’s own automation/workflow clearly requires autonomous publishing.
 - Default: finish work on staging, tell the user to review the staging subdomain when it is publicly shareable (see custom-domain caveat above), and let **them** publish (or ask you to publish after they approve).
 
@@ -90,14 +95,14 @@ Rules:
 4. Push updates **staging** (subdomain). Production is unchanged until someone runs `publish`.
 5. Pushing module markup may auto-activate modules (same as the editor agent).
 6. Binaries use base64; do not UTF-8 round-trip them.
-7. Prefer reviewing the subdomain after push; only use `deploy wait` if you need to block until a build finishes.
+7. After push, wait for the site compile (`frontpage push --wait` or `frontpage deploy wait`) before reviewing or publishing. Verify `<meta name="frontpage:commit">` when checking production.
 8. The **UI / canvas agent does not use this CLI** — it edits the live tip in-process. Only CLI checkouts need `pull`.
 
 ## Site contract (Astro)
 
 Sites are Astro 6 + Tailwind v4. More detail: `frontpage help site-building` or https://frontpage.host/developers/site-building
 
-1. **Every page** wraps content in `<BaseLayout title="…" description="…">` (import from `src/layouts/BaseLayout.astro`).
+1. **Every page** wraps content in `<BaseLayout title="…" description="…">` (import from `src/layouts/BaseLayout.astro`), or in a site layout that itself wraps `BaseLayout`. A custom wrapper MUST identity-forward `description={description}` and `ogImage={ogImage}` from a 1:1 `Astro.props` destructure (no default, no rename, no reassignment), and `title={seoTitle ?? <derived fallback>}` so the H1 can stay on `title` while Search & Social edits `seoTitle`. NEVER pass a derived local as `title={pageTitle}` with no `seoTitle` alias: the editor will lock Title and Share image on every page that uses that layout. Pages set literal `title` / `description` / optional `seoTitle` / `ogImage` on that tag.
 2. **`src/config/site.ts`** — keep `pages` (path registry) and `nav` in sync when adding/renaming/deleting page files. Tab title comes from BaseLayout, not the `pages` map label.
 3. **One file per URL** for similar page sets (services, guides, …). Do not default to `getStaticPaths()` over `src/data/*.ts`. Blog/news → `frontpage articles`, not a hand-rolled catalog.
 4. **No backends / databases / fake forms or checkout.** Real forms use `<form data-fp-form="slug">` + `frontpage modules`. Refuse or use modules for payments.
@@ -108,13 +113,14 @@ Sites are Astro 6 + Tailwind v4. More detail: `frontpage help site-building` or
 
 ## Modules & articles
 
-- Forms: `data-fp-form` markup in pages + `frontpage modules` for enable/config. No submit JS / honeypot / `action`.
-- Wizard / connect-once modules (payments/shop/ordering): `frontpage modules <key> connect` opens Frontpage (you must be logged in there), then Stripe or Square. Already-connected sites stay live — do not retry connect. payments/shop connect needs an **admin** key; ordering connect needs **editor**. `--no-open` for CI. `request-setup` remains valid when you want the **editor amber bar** instead. payments and shop share one Stripe account — payments disconnect fails if the store still uses it. Auto-active modules (forms/callbar/…) need markup, not request-setup. Typed settings: `frontpage modules callbar|forms|booking|signups get|set` (forms set needs `--instance`; do not target `default`). `frontpage modules <key>` prints that key's CLI usage (exit 2). Index: https://frontpage.host/developers/modules · payments/shop/ordering pages under /developers/modules/<key>
+- Forms: `data-fp-form` markup in pages + `frontpage modules` for enable/config. No submit JS / honeypot / `action`. Do not put a CRM webhook or token in HTML.
+- Wizard / connect-once modules (payments/shop/ordering): `frontpage modules <key> connect` opens Frontpage (you must be logged in there), then Stripe or Square. Already-connected sites stay live — do not retry connect. payments/shop connect needs an **admin** key; ordering connect needs **editor**. `--no-open` for CI. `request-setup` remains valid when you want the **editor amber bar** instead. payments and shop share one Stripe account — payments disconnect fails if the store still uses it. Auto-active modules (forms/callbar/…) need markup, not request-setup. Typed settings: `frontpage modules callbar|forms|booking|signups get|set` (forms set needs `--instance`; do not target `default`). Form destinations (HubSpot / Pipedrive / Privyr): connect once, then attach each form. `frontpage modules forms destinations|connect-destination|attach-destination|detach-destination|remove-destination --yes|request-destination-setup`. Token write is **admin**; `request-destination-setup` lights the editor amber bar (**editor** key). Do not use `request-setup forms` for a CRM (no-op). Connecting does not attach every form. Privyr: paste the Incoming Webhook URL from Automations → Lead Sources → Webhooks (`https://www.privyr.com/api/v1/incoming-leads/…`), not a token and not Outgoing Webhooks. HubSpot: Development → Keys → Service keys or Development → Legacy apps → Auth → Show token. Pipedrive: profile → Company settings → Personal preferences → API. Full docs: https://frontpage.host/developers/modules#forms-destinations. `frontpage modules <key>` prints that key's CLI usage (exit 2). Index: https://frontpage.host/developers/modules · payments/shop/ordering pages under /developers/modules/<key>
 - Google reviews: platform nodes only (`data-fp-google-reviews` / `data-fp-google-ask` + required `data-fp-requires="google_reviews"`). `data-layout` is `feed` (default), `badge`, or `link`. Never invent stars, quotes, a 1–10, or a Maps URL. Do not pick a Place ID via Autocomplete and do not write `placeId` through `modules config`. Owner-supplied Place ID / Maps URL: `frontpage modules google_reviews connect --place-id …` or `--maps-url …` (server resolves + seeds). Curation: `list-reviews`, `hide --id`, `show --id`, `set-stars`, `set-sort`, `set-weight`, `reset-weights`, `refresh`, `disconnect`. Usage: `frontpage modules google_reviews`. Docs: https://frontpage.host/developers/modules/google-reviews. Ask-widget scores: `frontpage inbox google_reviews`.
 - Articles: `frontpage articles …` for lifecycle; bodies via sync under `content/` or `articles content get|set`. Section landing is an owned `src/pages/<section>/index.astro`.
 - Migrate a folder into Articles: prefer `frontpage prompt "migrate … into articles"` — do not invent a mass delete+write migration.
 - Extensions: `frontpage extensions`; if LOCKED on plan, do not fake charts/etc.
 - Media: `frontpage media upload <file>` — images/PDF ≤25 MB, video (MP4/WebM/MOV) ≤50 MB, SVG/text ≤4 MB (sanitizing proxy). Human output prints `sitePath:` first (use that in markup — never raw blob hosts), then optional `url:`. Optional `?w=` on rasters only. **Text/CSV** uploads are inline only — **not** added to the media library and **cannot** be linked via `/__media` (`media upload --json` omits full `content`; use `inbox … --csv` for submission exports).
+- Generated images: `frontpage images generate --prompt "…"` `[--count N]` — one prompt, 1–4 variations of that same picture. Prints `sitePath:` first. Counts against AI $ and storage. Flag-off environments return 404 (`Image generation is not enabled.`). Do not call xAI / Imagine yourself.
 - Analytics: bare `frontpage analytics` = dashboard; also `summary|query|funnel|timeseries|compare|sql` for structured reads (SQL is guard + RLS site-scoped).
 
 ## Agent prompt loop
@@ -134,8 +140,9 @@ frontpage runs wait          # wait for the agent run to finish (failed/canceled
 - Caps: images/PDF ≤25 MB, video ≤50 MB, SVG/text via proxy ≤4 MB (large text/data Blob upload is editor-only).
 - Prompt text is still required (API). Attachments ride on the same enqueue as the editor.
 - `runs wait` with `--json`: failures use `ok: false` and include `data.run` (with `run.error` when present).
-- `deploy wait` is fail-closed: exit 2 if the waited run (or latest, when already idle) is `failed`/`canceled`.
-- `frontpage push --wait` waits for agent-run idle after push (same busy statuses; not a separate Vercel oracle).
+- `runs wait` watches an editor agent run only.
+- `deploy wait` is fail-closed on a failed/canceled agent run it actually watched (or a latest failed/canceled when idle). It then waits until `GET /deploy` `ready` (live compile SHA equals the tip). Exit 2 on compile failure or timeout.
+- `frontpage push --wait` does the same compile wait for the SHA just pushed. A file-only push still waits for the compile.
 
 Mid-task continuation is automatic. There is **no** `runs continue` in v1.
 
@@ -217,7 +224,7 @@ Safe default after finishing work: summarize what changed and give the staging U
 6. **Active-run guard.** Push/revert refuse while an editor agent run is active (exit 3).
 7. **CAS.** Tip moved since pull → exit 3; pull and retry.
 8. **No invented v1 commands:** `domains*`, `billing*`, `members*`, `suggestions*`, `sites delete|restore`, `runs continue`, MCP, git remotes / clone URLs.
-9. **`deploy wait` ≠ publish.** Optional build wait only; staging visibility is the subdomain.
+9. **`deploy wait` ≠ publish.** It waits for the tip compile. Production still requires `publish`. Verify live HTML with `<meta name="frontpage:commit">`.
 10. **Honesty on stubs.** `open --prod` is currently a no-op stub (still opens the subdomain).
 
 ## Isolation (hard fence)

package/README.md

@@ -23,9 +23,9 @@ Requires Node.js ≥ 20.
 3. `frontpage sites` — note the **subdomain** (not a custom domain).
 4. `mkdir my-site && cd my-site && frontpage use <subdomain>`
 5. `frontpage pull` → edit files under `src/`, `public/`, or `content/`
-6. `frontpage push --message "describe the change"`
-7. Review staging at `https://<subdomain>.frontpage.host` (no separate staging-deploy step).
-8. `frontpage publish` only when you intentionally promote to production.
+6. `frontpage push --message "describe the change"` (add `--wait` to block until the site compile is live)
+7. Review staging at `https://<subdomain>.frontpage.host` after the compile is ready.
+8. `frontpage publish --wait` only when you intentionally promote the ready compile to production.
 
 ## Environment
 

package/dist/bin.js

@@ -24,6 +24,7 @@ import { runPages } from "./commands/pages.js";
 import { runModules } from "./commands/modules.js";
 import { runExtensions } from "./commands/extensions.js";
 import { runMedia } from "./commands/media.js";
+import { runImages } from "./commands/images.js";
 import { runInbox } from "./commands/inbox.js";
 import { runSeo } from "./commands/seo.js";
 import { runArticles } from "./commands/articles.js";
@@ -107,6 +108,8 @@ async function main() {
             return runExtensions(args);
         case "media":
             return runMedia(args);
+        case "images":
+            return runImages(args);
         case "inbox":
             return runInbox(args);
         case "seo":

package/dist/commands/deploy.d.ts

@@ -1,2 +1,2 @@
-/** `frontpage deploy wait` — wait until no run is in deploying/queued/running. */
+/** `frontpage deploy wait` — agent-run idle, then the tip's site compile. */
 export declare function runDeploy(args: string[]): Promise<number>;

package/dist/commands/deploy.js

@@ -1,8 +1,8 @@
 import { resolveSlug } from "../site.js";
 import { EXIT_USAGE } from "../http/client.js";
 import { emitErr, emitUsage } from "../runtime.js";
-import { emitWaitOutcome, waitForAgentIdle } from "./wait-agent-idle.js";
-/** `frontpage deploy wait` — wait until no run is in deploying/queued/running. */
+import { waitForAgentThenCompile } from "./wait-site-compile.js";
+/** `frontpage deploy wait` — agent-run idle, then the tip's site compile. */
 export async function runDeploy(args) {
     try {
         const sub = args[0];
@@ -10,12 +10,11 @@ export async function runDeploy(args) {
             return emitUsage("deploy", "Usage: frontpage deploy wait [--site <slug>]", EXIT_USAGE);
         }
         const { slug } = await resolveSlug(args.slice(1));
-        const result = await waitForAgentIdle({
+        return waitForAgentThenCompile({
+            command: "deploy",
             slug,
-            // Fail-closed: idle with latest failed/canceled is not success.
             failClosedOnIdleTerminalFailure: true,
         });
-        return emitWaitOutcome({ command: "deploy", slug, result });
     }
     catch (err) {
         return emitErr("deploy", err);

package/dist/commands/images.d.ts

@@ -0,0 +1 @@
+export declare function runImages(args: string[]): Promise<number>;

package/dist/commands/images.js

@@ -0,0 +1,57 @@
+import { resolveSlug } from "../site.js";
+import { EXIT_OK, EXIT_USAGE, exitCodeForError, v1Post } from "../http/client.js";
+import { assertNoUnknownFlags, takeFlag } from "../argv.js";
+import { emitErr, emitOk, isJson } from "../runtime.js";
+const USAGE = 'Usage: frontpage images generate --prompt "…" [--count N] [--site <slug>] [--json]';
+const GENERATE_TIMEOUT_MS = 180_000;
+export async function runImages(args) {
+    try {
+        const { slug, rest } = await resolveSlug(args);
+        const sub = rest[0];
+        if (sub !== "generate") {
+            console.error(USAGE);
+            return EXIT_USAGE;
+        }
+        const work = rest.slice(1);
+        const prompt = takeFlag(work, "--prompt");
+        const countRaw = takeFlag(work, "--count");
+        assertNoUnknownFlags(work, "images");
+        if (work.length > 0) {
+            console.error(`Unexpected argument: ${work[0]}\n${USAGE}`);
+            return EXIT_USAGE;
+        }
+        if (!prompt) {
+            console.error(USAGE);
+            return EXIT_USAGE;
+        }
+        let count;
+        if (countRaw !== undefined) {
+            const n = Number(countRaw);
+            if (!Number.isInteger(n) || n < 1 || n > 4) {
+                console.error("Ask for 1 to 4 variations.");
+                return EXIT_USAGE;
+            }
+            count = n;
+        }
+        const body = { prompt };
+        if (count !== undefined)
+            body.count = count;
+        const data = await v1Post(`/api/v1/sites/${encodeURIComponent(slug)}/images`, body, { timeoutMs: GENERATE_TIMEOUT_MS });
+        if (isJson()) {
+            emitOk("images", { slug, images: data.images });
+            return EXIT_OK;
+        }
+        for (const img of data.images ?? []) {
+            console.log(`sitePath: ${img.sitePath}`);
+            if (img.filename)
+                console.log(`filename: ${img.filename}`);
+        }
+        return EXIT_OK;
+    }
+    catch (err) {
+        if (isJson())
+            return emitErr("images", err);
+        console.error(err instanceof Error ? err.message : String(err));
+        return exitCodeForError(err);
+    }
+}

package/dist/commands/modules.js

@@ -5,6 +5,7 @@ import { emitUsage } from "../runtime.js";
 import { formatModuleUsage, formatModulesIndex, isCliModuleAction, isDocumentedModuleKey, isGenericModuleVerb, } from "../modules/commands.js";
 import { runGoogleReviews } from "../modules/google_reviews.js";
 import { isTypedConfigCliKey, runTypedConfig } from "../modules/typed_config.js";
+import { isFormsDestinationCliAction, runFormsDestinations } from "../modules/forms_destinations.js";
 import { isOauthCliKey, runOauthHandoff } from "../modules/oauth.js";
 /** Drop --site so we can print local usage without resolving a checkout. */
 function positionalArgs(args) {
@@ -44,6 +45,9 @@ export async function runModules(args) {
                 if (peekedKey === "google_reviews") {
                     return await runGoogleReviews(slug, peekedAction, extraFlags);
                 }
+                if (peekedKey === "forms" && isFormsDestinationCliAction(peekedAction)) {
+                    return await runFormsDestinations(slug, peekedAction, extraFlags);
+                }
                 if (isTypedConfigCliKey(peekedKey)) {
                     return await runTypedConfig(peekedKey, slug, peekedAction, extraFlags);
                 }

package/dist/commands/publish.js

@@ -1,19 +1,77 @@
 import { resolveSlug } from "../site.js";
-import { EXIT_OK, EXIT_USAGE, v1Delete, v1Post } from "../http/client.js";
-import { emitErr, emitOk, emitUsage, isJson, requireYesOrTty } from "../runtime.js";
+import { EXIT_OK, EXIT_USAGE, v1Post, v1Delete } from "../http/client.js";
+import { emitErr, emitFail, emitOk, emitUsage, isJson, progress, requireYesOrTty } from "../runtime.js";
+import { describePublishResult, waitForCompileReady } from "../compile.js";
+function takeWaitFlag(rest) {
+    const i = rest.indexOf("--wait");
+    if (i === -1)
+        return false;
+    rest.splice(i, 1);
+    return true;
+}
+function emitPublished(slug, data) {
+    const described = describePublishResult({
+        productionCommit: data.productionCommit ?? null,
+        productionUrl: data.productionUrl ?? null,
+    });
+    if (isJson()) {
+        emitOk("publish", {
+            slug,
+            productionUrl: data.productionUrl ?? null,
+            productionCommit: data.productionCommit ?? null,
+            servingCommit: described.servingCommit,
+            matchesTip: described.matchesTip,
+        });
+    }
+    else {
+        console.log(`Published ${slug}`);
+        for (const line of described.lines)
+            console.log(line);
+        if (data.productionUrl)
+            console.log(data.productionUrl);
+        if (!described.matchesTip) {
+            console.error("Publish promoted a build that is not the current tip. Wait for the site compile, then publish again.");
+        }
+    }
+    return EXIT_OK;
+}
 export async function runPublish(args) {
     try {
-        const { slug } = await resolveSlug(args);
-        const data = await v1Post(`/api/v1/sites/${encodeURIComponent(slug)}/publish`);
-        if (isJson()) {
-            emitOk("publish", { slug, productionUrl: data.productionUrl ?? null });
+        const { slug, rest } = await resolveSlug(args);
+        const work = [...rest];
+        const wait = takeWaitFlag(work);
+        if (work.length > 0) {
+            return emitUsage("publish", "Usage: frontpage publish [--site <slug>] [--wait] [--json]", EXIT_USAGE);
         }
-        else {
-            console.log(`Published ${slug}`);
-            if (data.productionUrl)
-                console.log(data.productionUrl);
+        if (wait) {
+            if (!isJson())
+                progress("Waiting for the site compile…\n");
+            const compile = await waitForCompileReady({ slug });
+            if (compile.exitCode !== EXIT_OK) {
+                const message = compile.failed
+                    ? "Site compile failed. Refusing to publish a previous build."
+                    : compile.timedOut
+                        ? "Timed out waiting for the site compile. Refusing to publish a previous build."
+                        : "Site compile is not ready. Refusing to publish a previous build.";
+                return emitFail("publish", {
+                    message,
+                    exitCode: compile.exitCode,
+                    data: {
+                        slug,
+                        compile: compile.status,
+                        tip: compile.status?.stagingCommit ?? null,
+                        live: compile.status?.liveCommit ?? null,
+                        status: compile.failed
+                            ? "compile_failed"
+                            : compile.timedOut
+                                ? "compile_timeout"
+                                : "compile_not_ready",
+                    },
+                });
+            }
         }
-        return EXIT_OK;
+        const data = await v1Post(`/api/v1/sites/${encodeURIComponent(slug)}/publish`);
+        return emitPublished(slug, data);
     }
     catch (err) {
         return emitErr("publish", err);

package/dist/commands/push.js

@@ -4,7 +4,7 @@ import { resolveSlug } from "../site.js";
 import { EXIT_OK, EXIT_USAGE, v1Put } from "../http/client.js";
 import { readState, writeState } from "../state/frontpage-state.js";
 import { emitErr, emitOk, emitUsage, isJson } from "../runtime.js";
-import { emitWaitOutcome, waitForAgentIdle } from "./wait-agent-idle.js";
+import { waitForAgentThenCompile } from "./wait-site-compile.js";
 const TEXT_EXTS = new Set([
     ".astro",
     ".ts",
@@ -136,8 +136,7 @@ export async function runPush(args) {
                 console.error(`Warning: ${w}`);
             return EXIT_OK;
         }
-        // --wait: after push, wait for agent-run busy to clear (same statuses as deploy wait).
-        // Does not invent a Vercel deploy oracle; file-only pushes with no active run return promptly.
+        // --wait: agent-run idle (if any), then the new commit's site compile.
         if (!isJson()) {
             if (!data.changed) {
                 console.log("Nothing to commit (remote already matches).");
@@ -148,17 +147,12 @@ export async function runPush(args) {
             }
             for (const w of data.warnings ?? [])
                 console.error(`Warning: ${w}`);
-            console.error("Waiting for agent run / deploy idle…");
         }
-        const result = await waitForAgentIdle({
-            slug,
-            // Do not fail on an ancient canceled run when this push never saw busy work.
-            failClosedOnIdleTerminalFailure: false,
-        });
-        return emitWaitOutcome({
+        return waitForAgentThenCompile({
             command: "push",
             slug,
-            result,
+            expectCommit: data.commitSha ?? null,
+            failClosedOnIdleTerminalFailure: false,
             extra: { ...pushPayload, waited: true },
         });
     }

package/dist/commands/wait-agent-idle.d.ts

@@ -16,6 +16,18 @@ export type WaitIdleResult = {
 };
 export declare function isBusyStatus(status: string): boolean;
 export declare function isFailTerminal(status: string): boolean;
+/**
+ * A historical succeeded run is unrelated when this wait never saw busy work.
+ * Keep failed/canceled latest so deploy wait stays fail-closed (Phase D).
+ */
+export declare function sanitizeUnrelatedIdleRun(args: {
+    observedBusy: boolean;
+    run: WaitRunSnapshot | null;
+    status: string;
+}): {
+    run: WaitRunSnapshot | null;
+    status: string;
+};
 /**
  * Decide exit after idle. Pure — unit-tested.
  * - If we watched a busy run end: succeeded → 0; failed/canceled → 2.

package/dist/commands/wait-agent-idle.js

@@ -1,6 +1,7 @@
 /**
- * §CLI Phase D — shared wait for agent-run busy states (queued/running/deploying).
- * Used by `deploy wait` and `push --wait`. Not a Vercel deploy oracle.
+ * Shared wait for editor agent-run busy states (queued/running/deploying).
+ * This is the agent-run clock, not the site compile. File-only pushes have
+ * no agent run — success here does not mean the latest commit is built.
  */
 import { EXIT_OK, EXIT_USAGE, v1Get } from "../http/client.js";
 import { emitFail, emitOk, isJson, progress } from "../runtime.js";
@@ -12,6 +13,18 @@ export function isBusyStatus(status) {
 export function isFailTerminal(status) {
     return FAIL_TERMINAL.has(status);
 }
+/**
+ * A historical succeeded run is unrelated when this wait never saw busy work.
+ * Keep failed/canceled latest so deploy wait stays fail-closed (Phase D).
+ */
+export function sanitizeUnrelatedIdleRun(args) {
+    if (args.observedBusy)
+        return { run: args.run, status: args.status };
+    if (args.run && isFailTerminal(args.run.status)) {
+        return { run: args.run, status: args.status };
+    }
+    return { run: null, status: "idle" };
+}
 /**
  * Decide exit after idle. Pure — unit-tested.
  * - If we watched a busy run end: succeeded → 0; failed/canceled → 2.
@@ -111,11 +124,16 @@ export async function waitForAgentIdle(args) {
             observedBusy,
             failClosedOnIdleTerminalFailure: args.failClosedOnIdleTerminalFailure,
         });
+        const sanitized = sanitizeUnrelatedIdleRun({
+            observedBusy,
+            run: decided.run,
+            status: decided.status,
+        });
         return {
             exitCode: decided.exitCode,
-            run: decided.run,
+            run: sanitized.run,
             observedBusy,
-            status: decided.status,
+            status: sanitized.status,
         };
     }
     progress("\n");
@@ -175,7 +193,7 @@ export function emitWaitOutcome(args) {
         console.log(`${result.run.id}  ${result.run.status}${result.run.statusMessage ? `  ${result.run.statusMessage}` : ""}`);
     }
     else {
-        console.log("No active deploy.");
+        console.log("No agent run was in flight. This does not mean the latest commit is compiled.");
     }
     return EXIT_OK;
 }

package/dist/commands/wait-site-compile.d.ts

@@ -0,0 +1,21 @@
+import { type DeployStatus } from "../compile.js";
+import { type WaitIdleResult } from "./wait-agent-idle.js";
+export declare function waitForAgentThenCompile(args: {
+    command: "deploy" | "push";
+    slug: string;
+    expectCommit?: string | null;
+    failClosedOnIdleTerminalFailure: boolean;
+    extra?: Record<string, unknown>;
+}): Promise<number>;
+export declare function emitCompileWaitOutcome(args: {
+    command: "deploy" | "push";
+    slug: string;
+    agent: WaitIdleResult;
+    compile: {
+        exitCode: number;
+        timedOut: boolean;
+        failed?: boolean;
+        status: DeployStatus | null;
+    };
+    extra?: Record<string, unknown>;
+}): number;

package/dist/commands/wait-site-compile.js

@@ -0,0 +1,94 @@
+/**
+ * After the agent-run clock is idle, wait for the site compile of the tip.
+ */
+import { EXIT_OK } from "../http/client.js";
+import { emitFail, emitOk, isJson, progress } from "../runtime.js";
+import { waitForCompileReady } from "../compile.js";
+import { emitWaitOutcome, waitForAgentIdle, } from "./wait-agent-idle.js";
+export async function waitForAgentThenCompile(args) {
+    const agent = await waitForAgentIdle({
+        slug: args.slug,
+        failClosedOnIdleTerminalFailure: args.failClosedOnIdleTerminalFailure,
+    });
+    if (agent.exitCode !== EXIT_OK) {
+        return emitWaitOutcome({
+            command: args.command,
+            slug: args.slug,
+            result: agent,
+            extra: args.extra,
+        });
+    }
+    if (!isJson()) {
+        if (agent.observedBusy && agent.run) {
+            console.log(`${agent.run.id}  ${agent.run.status}${agent.run.statusMessage ? `  ${agent.run.statusMessage}` : ""}`);
+        }
+        else {
+            console.log("No agent run was in flight.");
+        }
+        progress("Waiting for the site compile…\n");
+    }
+    const compile = await waitForCompileReady({
+        slug: args.slug,
+        expectCommit: args.expectCommit,
+    });
+    return emitCompileWaitOutcome({
+        command: args.command,
+        slug: args.slug,
+        agent,
+        compile,
+        extra: args.extra,
+    });
+}
+export function emitCompileWaitOutcome(args) {
+    const compileData = {
+        compile: args.compile.status,
+        compileReady: Boolean(args.compile.status?.ready) && !args.compile.timedOut,
+    };
+    if (args.compile.exitCode !== EXIT_OK) {
+        const message = args.compile.failed
+            ? "Site compile failed. The git tip is not live."
+            : args.compile.timedOut
+                ? "Timed out waiting for the site compile. The git tip is not live yet."
+                : "Site compile is not ready.";
+        if (isJson()) {
+            return emitFail(args.command, {
+                message,
+                exitCode: args.compile.exitCode,
+                data: {
+                    slug: args.slug,
+                    waited: true,
+                    observedBusy: args.agent.observedBusy,
+                    status: args.compile.failed
+                        ? "compile_failed"
+                        : args.compile.timedOut
+                            ? "compile_timeout"
+                            : "compile_not_ready",
+                    run: args.agent.run,
+                    ...compileData,
+                    ...args.extra,
+                },
+            });
+        }
+        console.error(message);
+        if (args.compile.status) {
+            console.error(`tip ${args.compile.status.stagingCommit ?? "(none)"}  live ${args.compile.status.liveCommit ?? "(none)"}`);
+        }
+        return args.compile.exitCode;
+    }
+    if (isJson()) {
+        emitOk(args.command, {
+            slug: args.slug,
+            waited: true,
+            observedBusy: args.agent.observedBusy,
+            status: "ready",
+            run: args.agent.run,
+            ...compileData,
+            ...args.extra,
+        });
+    }
+    else {
+        const live = args.compile.status?.liveCommit ?? args.compile.status?.stagingCommit;
+        console.log(`Site compile ready  ${live ?? ""}`.trim());
+    }
+    return EXIT_OK;
+}

package/dist/compile.d.ts

@@ -0,0 +1,41 @@
+export type DeployStatus = {
+    slug?: string;
+    stagingCommit: string | null;
+    servingCommit: string | null;
+    liveCommit: string | null;
+    ready: boolean;
+    splitBrain: boolean;
+    compileState?: "ready" | "building" | "failed" | "canceled" | "unknown";
+    stagingUrl: string | null;
+    productionCommit: string | null;
+    productionServingCommit: string | null;
+    productionUrl: string | null;
+};
+export declare function normalizeSha(raw: string | null | undefined): string | null;
+export declare function shortSha(raw: string | null | undefined): string;
+/** SHA encoded in a Blob artifact prefix URL. */
+export declare function commitFromArtifactUrl(url: string | null | undefined): string | null;
+export declare function compileIsReady(status: Pick<DeployStatus, "ready" | "liveCommit">, expectCommit?: string | null): boolean;
+export type CompileWaitResult = {
+    exitCode: number;
+    timedOut: boolean;
+    failed: boolean;
+    status: DeployStatus | null;
+};
+export declare function fetchDeployStatus(slug: string): Promise<DeployStatus>;
+export declare function waitForCompileReady(args: {
+    slug: string;
+    expectCommit?: string | null;
+    maxMs?: number;
+    pollMs?: number;
+    fetchStatus?: (slug: string) => Promise<DeployStatus>;
+}): Promise<CompileWaitResult>;
+export declare function describePublishResult(args: {
+    productionCommit: string | null;
+    productionUrl: string | null;
+}): {
+    tipCommit: string | null;
+    servingCommit: string | null;
+    matchesTip: boolean;
+    lines: string[];
+};

package/dist/compile.js

@@ -0,0 +1,71 @@
+/**
+ * Site compile clock (not the editor agent run).
+ *
+ * GET /api/v1/sites/{slug}/deploy → ready when the live compile SHA equals the tip.
+ */
+import { EXIT_OK, EXIT_USAGE, v1Get } from "./http/client.js";
+import { progress } from "./runtime.js";
+const SHA_RE = /^[0-9a-f]{40}$/i;
+export function normalizeSha(raw) {
+    const sha = (raw ?? "").trim().toLowerCase();
+    return SHA_RE.test(sha) ? sha : null;
+}
+export function shortSha(raw) {
+    const sha = normalizeSha(raw);
+    return sha ? sha.slice(0, 7) : "(none)";
+}
+/** SHA encoded in a Blob artifact prefix URL. */
+export function commitFromArtifactUrl(url) {
+    if (!url)
+        return null;
+    const m = String(url).match(/\/artifacts\/[^/]+\/([0-9a-f]{40})(?:\/|$)/i);
+    return m ? m[1].toLowerCase() : null;
+}
+export function compileIsReady(status, expectCommit) {
+    if (!status.ready)
+        return false;
+    const live = normalizeSha(status.liveCommit);
+    if (!live)
+        return false;
+    const expect = normalizeSha(expectCommit ?? null);
+    if (!expect)
+        return true;
+    return live === expect;
+}
+export async function fetchDeployStatus(slug) {
+    return v1Get(`/api/v1/sites/${encodeURIComponent(slug)}/deploy`);
+}
+export async function waitForCompileReady(args) {
+    const maxMs = args.maxMs ?? 30 * 60 * 1000;
+    const pollMs = args.pollMs ?? 2000;
+    const fetchStatus = args.fetchStatus ?? fetchDeployStatus;
+    const started = Date.now();
+    let last = null;
+    while (Date.now() - started < maxMs) {
+        last = await fetchStatus(args.slug);
+        if (last.compileState === "failed" || last.compileState === "canceled") {
+            progress("\n");
+            return { exitCode: EXIT_USAGE, timedOut: false, failed: true, status: last };
+        }
+        if (compileIsReady(last, args.expectCommit)) {
+            progress("\n");
+            return { exitCode: EXIT_OK, timedOut: false, failed: false, status: last };
+        }
+        const tip = shortSha(args.expectCommit ?? last.stagingCommit);
+        const live = shortSha(last.liveCommit ?? last.servingCommit);
+        progress(`\rwaiting for site compile  tip ${tip}  live ${live}   `);
+        await new Promise((r) => setTimeout(r, pollMs));
+    }
+    progress("\n");
+    return { exitCode: EXIT_USAGE, timedOut: true, failed: false, status: last };
+}
+export function describePublishResult(args) {
+    const tipCommit = normalizeSha(args.productionCommit);
+    const servingCommit = commitFromArtifactUrl(args.productionUrl) ?? tipCommit;
+    const matchesTip = Boolean(tipCommit && servingCommit && tipCommit === servingCommit);
+    const lines = [
+        `tip      ${tipCommit ?? "(none)"}`,
+        `serving  ${servingCommit ?? "(none)"}${matchesTip ? "" : "  ← not the tip; this is the previous build"}`,
+    ];
+    return { tipCommit, servingCommit, matchesTip, lines };
+}

package/dist/completions/generate.js

@@ -19,6 +19,7 @@ _frontpage_completions() {
     runs) COMPREPLY=( $(compgen -W "list current wait cancel retry get" -- "\${cur}") ) ;;
     deploy) COMPREPLY=( $(compgen -W "wait" -- "\${cur}") ) ;;
     media) COMPREPLY=( $(compgen -W "list upload" -- "\${cur}") ) ;;
+    images) COMPREPLY=( $(compgen -W "generate" -- "\${cur}") ) ;;
     fonts) COMPREPLY=( $(compgen -W "list search" -- "\${cur}") ) ;;
     tokens) COMPREPLY=( $(compgen -W "set" -- "\${cur}") ) ;;
     seo|settings) COMPREPLY=( $(compgen -W "get set" -- "\${cur}") ) ;;
@@ -27,7 +28,9 @@ _frontpage_completions() {
     modules)
       if [[ \${COMP_CWORD} -ge 3 && \${COMP_WORDS[2]} == google_reviews ]]; then
         COMPREPLY=( $(compgen -W "docs request-setup enable disable archive config connect resolve status list-reviews hide show set-stars set-sort set-weight reset-weights write-review-url refresh disconnect" -- "\${cur}") )
-      elif [[ \${COMP_CWORD} -ge 3 && (\${COMP_WORDS[2]} == callbar || \${COMP_WORDS[2]} == forms || \${COMP_WORDS[2]} == booking || \${COMP_WORDS[2]} == signups) ]]; then
+      elif [[ \${COMP_CWORD} -ge 3 && \${COMP_WORDS[2]} == forms ]]; then
+        COMPREPLY=( $(compgen -W "docs request-setup enable disable archive config get set destinations connect-destination remove-destination disconnect-destination attach-destination detach-destination request-destination-setup" -- "\${cur}") )
+      elif [[ \${COMP_CWORD} -ge 3 && (\${COMP_WORDS[2]} == callbar || \${COMP_WORDS[2]} == booking || \${COMP_WORDS[2]} == signups) ]]; then
         COMPREPLY=( $(compgen -W "docs request-setup enable disable archive config get set" -- "\${cur}") )
       elif [[ \${COMP_CWORD} -ge 3 && (\${COMP_WORDS[2]} == payments || \${COMP_WORDS[2]} == shop) ]]; then
         COMPREPLY=( $(compgen -W "docs request-setup enable disable archive config status connect disconnect" -- "\${cur}") )
@@ -61,6 +64,7 @@ _frontpage() {
         runs) _values 'subcommand' current wait cancel retry get ;;
         deploy) _values 'subcommand' wait ;;
         media) _values 'subcommand' list upload ;;
+        images) _values 'subcommand' generate ;;
         fonts) _values 'subcommand' list search ;;
         tokens) _values 'subcommand' set ;;
         seo|settings) _values 'subcommand' get set ;;
@@ -68,7 +72,9 @@ _frontpage() {
         modules)
           if [[ $words[2] == google_reviews ]]; then
             _values 'subcommand' docs request-setup enable disable archive config connect resolve status list-reviews hide show set-stars set-sort set-weight reset-weights write-review-url refresh disconnect
-          elif [[ $words[2] == callbar || $words[2] == forms || $words[2] == booking || $words[2] == signups ]]; then
+          elif [[ $words[2] == forms ]]; then
+            _values 'subcommand' docs request-setup enable disable archive config get set destinations connect-destination remove-destination disconnect-destination attach-destination detach-destination request-destination-setup
+          elif [[ $words[2] == callbar || $words[2] == booking || $words[2] == signups ]]; then
             _values 'subcommand' docs request-setup enable disable archive config get set
           elif [[ $words[2] == payments || $words[2] == shop ]]; then
             _values 'subcommand' docs request-setup enable disable archive config status connect disconnect
@@ -95,13 +101,15 @@ export function generateFishCompletion() {
         `complete -c frontpage -n "__fish_seen_subcommand_from runs" -a "current wait cancel retry get"`,
         `complete -c frontpage -n "__fish_seen_subcommand_from deploy" -a "wait"`,
         `complete -c frontpage -n "__fish_seen_subcommand_from media" -a "list upload"`,
+        `complete -c frontpage -n "__fish_seen_subcommand_from images" -a "generate"`,
         `complete -c frontpage -n "__fish_seen_subcommand_from fonts" -a "list search"`,
         `complete -c frontpage -n "__fish_seen_subcommand_from tokens" -a "set"`,
         `complete -c frontpage -n "__fish_seen_subcommand_from seo settings" -a "get set"`,
         `complete -c frontpage -n "__fish_seen_subcommand_from analytics" -a "dashboard summary query funnel timeseries compare sql"`,
         `complete -c frontpage -n "__fish_seen_subcommand_from modules" -a "list docs request-setup enable disable archive config callbar forms booking signups payments shop ordering articles google_reviews"`,
         `complete -c frontpage -n "__fish_seen_subcommand_from modules; and __fish_seen_subcommand_from google_reviews" -a "connect resolve status list-reviews hide show set-stars set-sort set-weight reset-weights write-review-url refresh disconnect"`,
-        `complete -c frontpage -n "__fish_seen_subcommand_from modules; and __fish_seen_subcommand_from callbar forms booking signups" -a "get set"`,
+        `complete -c frontpage -n "__fish_seen_subcommand_from modules; and __fish_seen_subcommand_from forms" -a "get set destinations connect-destination remove-destination disconnect-destination attach-destination detach-destination request-destination-setup"`,
+        `complete -c frontpage -n "__fish_seen_subcommand_from modules; and __fish_seen_subcommand_from callbar booking signups" -a "get set"`,
         `complete -c frontpage -n "__fish_seen_subcommand_from modules; and __fish_seen_subcommand_from payments shop" -a "status connect disconnect"`,
         `complete -c frontpage -n "__fish_seen_subcommand_from modules; and __fish_seen_subcommand_from ordering" -a "status connect disconnect sync"`,
         `complete -c frontpage -n "__fish_seen_subcommand_from extensions" -a "list docs enable disable config"`,

package/dist/modules/commands.js

@@ -63,6 +63,13 @@ export const MODULE_COMMANDS = [
         extraActions: [
             "get [--instance <slug>]",
             "set --instance <slug> [--notify-email] [--confirm yes|no]",
+            "destinations [--instance <slug>]",
+            "connect-destination <privyr|hubspot|pipedrive> --token \"…\" [--lead-source \"…\"]",
+            "attach-destination --instance <slug> --provider <id>",
+            "detach-destination --instance <slug> --provider <id>",
+            "remove-destination <id> --yes",
+            "disconnect-destination <id> --yes",
+            "request-destination-setup <id> --reason \"…\"",
         ],
         notYet: [],
         examples: [
@@ -70,12 +77,16 @@ export const MODULE_COMMANDS = [
             "frontpage modules forms get",
             "frontpage modules forms get --instance lead-gen",
             "frontpage modules forms set --instance lead-gen --notify-email hi@example.com",
+            "frontpage modules forms destinations",
+            "frontpage modules forms connect-destination privyr --token \"…\"",
+            "frontpage modules forms attach-destination --instance lead-gen --provider privyr",
             "frontpage modules forms docs",
             `frontpage modules config forms --instance lead-gen --config '{"notifyEmail":"hi@example.com"}'`,
         ],
         notes: [
             "Without --instance, get lists each form (id, status, notifyEmail). Do not target `default`.",
             "Confirmation emails require a paid plan (same as Modules).",
+            "Destinations copy leads to HubSpot, Pipedrive, or Privyr. Connect once, then attach each form. Token write is admin (Privyr: paste the Incoming Webhook URL, not a token). request-destination-setup lights the editor amber bar (editor key). remove-destination requires --yes. Locations: https://frontpage.host/developers/modules#forms-destinations",
         ],
     },
     {
@@ -275,7 +286,19 @@ export function isCliModuleAction(key, action) {
     if (key === "google_reviews") {
         return GOOGLE_REVIEWS_CLI_ACTIONS.includes(action);
     }
-    if (key === "callbar" || key === "forms" || key === "booking" || key === "signups") {
+    if (key === "forms") {
+        return (TYPED_CONFIG_CLI_ACTIONS.includes(action) ||
+            [
+                "destinations",
+                "connect-destination",
+                "remove-destination",
+                "disconnect-destination",
+                "attach-destination",
+                "detach-destination",
+                "request-destination-setup",
+            ].includes(action));
+    }
+    if (key === "callbar" || key === "booking" || key === "signups") {
         return TYPED_CONFIG_CLI_ACTIONS.includes(action);
     }
     if (key === "payments" || key === "shop") {

package/dist/modules/forms_destinations.d.ts

@@ -0,0 +1,3 @@
+export declare const FORMS_DESTINATION_CLI_ACTIONS: readonly ["destinations", "connect-destination", "remove-destination", "disconnect-destination", "attach-destination", "detach-destination", "request-destination-setup"];
+export declare function isFormsDestinationCliAction(action: string): boolean;
+export declare function runFormsDestinations(slug: string, action: string, flags: string[]): Promise<number>;

package/dist/modules/forms_destinations.js

@@ -0,0 +1,147 @@
+/**
+ * §FD.CLI — form destination verbs.
+ */
+import { assertNoUnknownFlags, hasFlag, takeFlag } from "../argv.js";
+import { EXIT_OK, EXIT_USAGE, v1Get, v1Post } from "../http/client.js";
+import { emitOk, emitUsage, isJson } from "../runtime.js";
+import { formatModuleUsage } from "./commands.js";
+const USAGE = formatModuleUsage("forms");
+const REMOVE_CONFIRM = "This deletes the destination from Frontpage and stops every form from sending a copy. Your leads stay in Frontpage and still email you.";
+function pathFor(slug) {
+    return `/api/v1/sites/${encodeURIComponent(slug)}/modules/forms`;
+}
+export const FORMS_DESTINATION_CLI_ACTIONS = [
+    "destinations",
+    "connect-destination",
+    "remove-destination",
+    "disconnect-destination",
+    "attach-destination",
+    "detach-destination",
+    "request-destination-setup",
+];
+export function isFormsDestinationCliAction(action) {
+    return FORMS_DESTINATION_CLI_ACTIONS.includes(action);
+}
+function printDestinations(data, instanceFilter) {
+    const providers = data.destinations?.providers ?? [];
+    const connected = providers.filter((p) => p.connected);
+    if (!connected.length) {
+        console.log("(no destinations)");
+        return;
+    }
+    const by = data.destinations?.byInstance ?? {};
+    for (const p of connected) {
+        console.log(`${p.id.padEnd(10)}  connected  ${p.last4 ? `••••${p.last4}` : ""}`.trimEnd());
+        const slugs = instanceFilter ? [instanceFilter] : Object.keys(by);
+        for (const slug of slugs) {
+            const row = (by[slug] ?? []).find((r) => r.provider === p.id);
+            const sending = row?.enabled ? "sending" : "—";
+            const err = row?.lastError ? `  error  ${row.lastError}` : "";
+            if (instanceFilter && !row) {
+                console.log(`          ${slug.padEnd(16)}  —`);
+                continue;
+            }
+            if (!instanceFilter && !row)
+                continue;
+            console.log(`          ${slug.padEnd(16)}  ${sending}${err}`);
+        }
+    }
+}
+export async function runFormsDestinations(slug, action, flags) {
+    const work = [...flags];
+    if (action === "destinations") {
+        const instanceId = takeFlag(work, "--instance");
+        assertNoUnknownFlags(work, "modules");
+        const data = await v1Get(pathFor(slug));
+        if (isJson()) {
+            emitOk("modules", data.destinations ?? { providers: [], byInstance: {} });
+            return EXIT_OK;
+        }
+        printDestinations(data, instanceId);
+        return EXIT_OK;
+    }
+    if (action === "connect-destination") {
+        const provider = work.shift();
+        const token = takeFlag(work, "--token");
+        const leadSource = takeFlag(work, "--lead-source");
+        assertNoUnknownFlags(work, "modules");
+        if (!provider || !token) {
+            return emitUsage("modules", `Usage: frontpage modules forms connect-destination <privyr|hubspot|pipedrive> --token "…"\n\n${USAGE}`);
+        }
+        const data = await v1Post(pathFor(slug), {
+            action: "destination_connect",
+            provider,
+            token,
+            ...(leadSource ? { leadSource } : {}),
+        });
+        if (isJson()) {
+            emitOk("modules", data);
+            return EXIT_OK;
+        }
+        const last4 = typeof data.last4 === "string" ? data.last4 : "";
+        console.log(`Connected ${provider}${last4 ? `  ••••${last4}` : ""}.`);
+        return EXIT_OK;
+    }
+    if (action === "remove-destination" || action === "disconnect-destination") {
+        const provider = work.shift();
+        const yes = hasFlag(work, "--yes");
+        assertNoUnknownFlags(work, "modules");
+        if (!provider) {
+            return emitUsage("modules", `Usage: frontpage modules forms ${action} <privyr|hubspot|pipedrive> --yes\n\n${USAGE}`);
+        }
+        if (!yes) {
+            return emitUsage("modules", REMOVE_CONFIRM, EXIT_USAGE);
+        }
+        const data = await v1Post(pathFor(slug), {
+            action: "destination_remove",
+            provider,
+        });
+        if (isJson()) {
+            emitOk("modules", data);
+            return EXIT_OK;
+        }
+        console.log(`Removed ${provider}. Leads still land in Frontpage.`);
+        return EXIT_OK;
+    }
+    if (action === "attach-destination" || action === "detach-destination") {
+        const instanceId = takeFlag(work, "--instance");
+        const provider = takeFlag(work, "--provider") ?? work.shift();
+        assertNoUnknownFlags(work, "modules");
+        if (!instanceId || !provider) {
+            return emitUsage("modules", `Usage: frontpage modules forms ${action} --instance <slug> --provider <privyr|hubspot|pipedrive>\n\n${USAGE}`);
+        }
+        const data = await v1Post(pathFor(slug), {
+            action: action === "attach-destination" ? "destination_attach" : "destination_detach",
+            provider,
+            instanceId,
+        });
+        if (isJson()) {
+            emitOk("modules", data);
+            return EXIT_OK;
+        }
+        console.log(action === "attach-destination"
+            ? `${instanceId} will also send a copy to ${provider}.`
+            : `Stopped sending ${instanceId} to ${provider}.`);
+        return EXIT_OK;
+    }
+    if (action === "request-destination-setup") {
+        const provider = work.shift();
+        const reason = takeFlag(work, "--reason") ?? "";
+        assertNoUnknownFlags(work, "modules");
+        if (!provider || !reason) {
+            return emitUsage("modules", `Usage: frontpage modules forms request-destination-setup <privyr|hubspot|pipedrive> --reason "…"\n\n${USAGE}`);
+        }
+        const data = await v1Post(pathFor(slug), {
+            action: "destination_request_setup",
+            provider,
+            reason,
+        });
+        if (isJson()) {
+            emitOk("modules", data);
+            return EXIT_OK;
+        }
+        console.log(`Setup requested for ${provider}. The owner sees an amber prompt in the Frontpage editor.`);
+        return EXIT_OK;
+    }
+    return emitUsage("modules", `${USAGE}\n\nUnknown action "${action}".`);
+}

package/dist/modules/typed_config.js

@@ -46,17 +46,29 @@ function printConfirmable(config, confirmations) {
     else
         printLine("confirm", yesNo(on));
 }
-function printFormsList(instances) {
+function printFormsList(instances, destinations) {
     if (!instances.length) {
         console.log("(no forms)");
-        return;
     }
-    for (const i of instances) {
-        const id = i.instance ?? "";
-        const label = i.label && i.label !== id ? i.label : "";
-        const status = String(i.status ?? "—");
-        const email = typeof i.config?.notifyEmail === "string" ? i.config.notifyEmail : "(account email)";
-        console.log(`${id.padEnd(20)}  ${status.padEnd(12)}  ${label ? `${label}  ` : ""}${email}`);
+    else {
+        for (const i of instances) {
+            const id = i.instance ?? "";
+            const label = i.label && i.label !== id ? i.label : "";
+            const status = String(i.status ?? "—");
+            const email = typeof i.config?.notifyEmail === "string" ? i.config.notifyEmail : "(account email)";
+            const attached = (destinations?.byInstance?.[id] ?? [])
+                .filter((r) => r.enabled)
+                .map((r) => r.provider)
+                .join(",");
+            console.log(`${id.padEnd(20)}  ${status.padEnd(12)}  ${label ? `${label}  ` : ""}${email.padEnd(22)}  ${attached || "—"}`);
+        }
+    }
+    const connected = (destinations?.providers ?? []).filter((p) => p.connected);
+    if (connected.length) {
+        console.log("");
+        for (const p of connected) {
+            console.log(`${p.id} connected${p.last4 ? ` ••••${p.last4}` : ""}`);
+        }
     }
 }
 function parseYesNoFlag(raw, flag) {
@@ -81,7 +93,7 @@ export async function runTypedConfig(key, slug, action, flags) {
             return EXIT_OK;
         }
         if (key === "forms" && !instanceId) {
-            printFormsList(data.instances ?? []);
+            printFormsList(data.instances ?? [], data.destinations);
             return EXIT_OK;
         }
         if (key === "callbar")

package/dist/registry.js

@@ -104,7 +104,7 @@ export const COMMANDS = [
         flags: [
             "--site <slug>",
             "--message <text>",
-            "--wait: after push, wait until no agent run is queued/running/deploying (same as deploy wait; not a Vercel oracle)",
+            "--wait: after push, wait until the new commit's site compile is live (agent-run idle first, then GET /deploy ready)",
         ],
         dangers: [
             "Requires prior pull (baseCommitSha)",
@@ -249,10 +249,16 @@ export const COMMANDS = [
     {
         name: "publish",
         summary: "Promote staging to production",
-        usage: "frontpage publish [--site <slug>] [--json]",
+        usage: "frontpage publish [--site <slug>] [--wait] [--json]",
         topics: ["agent"],
+        examples: ["frontpage publish", "frontpage publish --wait"],
+        flags: [
+            "--wait: wait until the staging tip's site compile is live, then publish (refuses a previous build)",
+            "Prints tip SHA and serving SHA; warns if they differ",
+        ],
         dangers: [
-            "Promotes the current staging tip to PRODUCTION (custom domain)",
+            "Promotes the last ready staging compile to PRODUCTION (custom domain)",
+            "409 if the tip is not compiled yet — wait, then publish",
             "Agents: never run unless the user explicitly asked to publish",
         ],
         seeAlso: ["unpublish", "deploy"],
@@ -270,13 +276,14 @@ export const COMMANDS = [
     },
     {
         name: "deploy",
-        summary: "Wait for an in-flight build to finish (not publish)",
+        summary: "Wait for the current tip's site compile (not publish)",
         usage: "frontpage deploy wait [--site <slug>] [--json]",
         topics: ["agent"],
         flags: [
-            "Optional build wait only — staging is https://<subdomain>.frontpage.host",
+            "Waits for editor-agent idle (if a run is in flight), then until GET /deploy ready",
+            "ready = the live compile SHA equals the git tip — not a historical agent run",
             "Does NOT promote to production; use publish only when the user asks",
-            "Fail-closed: exit 2 when the waited run (or latest, if already idle) is failed/canceled",
+            "Fail-closed: exit 2 when the waited agent run is failed/canceled, or the compile fails or times out",
         ],
     },
     {
@@ -361,6 +368,24 @@ export const COMMANDS = [
         topics: ["agent", "content"],
         examples: ["frontpage extensions docs charts"],
     },
+    {
+        name: "images",
+        summary: "Generate 1–4 AI image variations of one prompt (counts against AI $ and storage)",
+        usage: 'frontpage images generate --prompt "…" [--count N] [--site <slug>] [--json]',
+        topics: ["content"],
+        examples: [
+            'frontpage images generate --prompt "flat illustration of a red stand mixer on marble"',
+            'frontpage images generate --prompt "watercolor cafe storefront at dusk" --count 4',
+        ],
+        flags: [
+            "One prompt; --count 1–4 is variations of that same picture (default 1)",
+            "Human success: sitePath first (markup-safe), then filename",
+            "Counts against the site AI $ budget and storage; 402 when the cycle is spent",
+            "--count outside 1–4 fails locally (exit 2) with no request",
+            "Unknown leftover flags fail closed (exit 2)",
+        ],
+        seeAlso: ["media", "prompt", "help content", "help site-building"],
+    },
     {
         name: "media",
         summary: "List or upload site media (images/PDF ≤25 MB, video ≤50 MB)",
@@ -478,12 +503,13 @@ export const TOPICS = {
   5. frontpage pull
   6. Edit files under src/, public/, or content/
   7. frontpage push --message "…"
-  8. Review staging: https://<subdomain>.frontpage.host when that subdomain is publicly shareable.
+  8. frontpage deploy wait         # tip compile ready (optional; push --wait does this)
+     Review staging: https://<subdomain>.frontpage.host when that subdomain is publicly shareable.
      With a custom domain connected, the subdomain is often owner-private (login wall ≠ failed push);
      anonymous review is on the published custom domain after publish.
-  9. frontpage publish             # ONLY if the user asked — promotes to production
+  9. frontpage publish [--wait]    # ONLY if the user asked — promotes the ready compile
 
-  Staging is the subdomain. There is no separate staging-deploy step for agents.
+  Push updates the git tip. The site compile is a second clock. deploy wait is not go-live.
   Never publish/unpublish unless the user explicitly asks.
   Agents: read AGENTS.md + frontpage help site-building; use --json for structured I/O.
   More: frontpage help auth | sync | site-building | agent | content | history | isolation | exit-codes`,
@@ -511,7 +537,7 @@ export const TOPICS = {
   Local state: .frontpage/state.json { slug, baseCommitSha }
   Pull BEFORE EDITING when tip may have moved (UI agent / another checkout) — check tipDrift.
   Pull before push so CAS has baseCommitSha. Do not push while the editor agent is building.
-  --wait after push blocks until no agent run is queued/running/deploying (same as deploy wait).
+  --wait after push blocks until the new commit's site compile is live (agent idle, then GET /deploy ready).
   The UI/canvas agent does not use this CLI; only CLI checkouts need pull.
   Pushing module markup may auto-activate modules (same as the agent).
   tokens.ts may be auto-repaired at commit if it would break the build.
@@ -520,12 +546,15 @@ export const TOPICS = {
   Do not store secrets in the site tree (.env, *.pem, secrets/, credentials.json) — rejected by the API.
 
   Staging vs production:
-  - Push/prompt/edit update STAGING: https://<subdomain>.frontpage.host
-  - No separate "deploy to staging" step for agents — review the subdomain after the build.
-  - frontpage deploy wait only waits for an in-flight build; it is NOT go-live.
-  - frontpage publish promotes staging → production (custom domain). Never publish unless asked.`,
+  - Push/prompt/edit update the git tip. The site compile is a second clock.
+  - Review STAGING at https://<subdomain>.frontpage.host after GET /deploy is ready.
+  - frontpage deploy wait = agent-run idle (if any) + tip compile ready. It is NOT go-live.
+  - A file-only push has no agent run. deploy wait / push --wait must still wait for the compile.
+  - frontpage publish promotes the last ready staging compile. 409 if the tip is not built yet.
+  - frontpage publish --wait waits for that compile, then publishes. Never publish unless asked.`,
     "site-building": `Site building (Astro contract)
-  Stack: Astro 6 + Tailwind v4. Pages in src/pages/. Every page wraps <BaseLayout title description>.
+  Stack: Astro 6 + Tailwind v4. Pages in src/pages/. Every page wraps <BaseLayout title description>,
+  or a site layout that itself wraps BaseLayout.
   Control files: src/config/tokens.ts (design tokens), src/config/site.ts (title, nav, pages map, seo).
 
   Pages map:
@@ -538,7 +567,10 @@ export const TOPICS = {
   - No API routes, serverless backends, or databases.
   - No fake lead forms / checkout / card fields — use data-fp-* modules + frontpage modules, or refuse.
   - Platform-owned paths are not syncable (BaseLayout overlay, module/extension shells, package.json…).
-  - Customer layouts (DocsLayout, GuideLayout, …) are fine when site-owned.
+  - Customer layouts (DocsLayout, GuideLayout, …) are fine when site-owned. A wrapper MUST render
+    <BaseLayout> and forward SEO: description={description}, ogImage={ogImage}, and
+    title={seoTitle ?? derivedFallback} from a 1:1 Astro.props destructure. NEVER title={pageTitle}
+    with no seoTitle alias (locks Title/Share image in Search & Social for every page on that layout).
 
   Tokens & fonts:
   - Keep required colors/fonts/spacing/radii keys; style via CSS variables / token Tailwind.
@@ -556,7 +588,7 @@ export const TOPICS = {
   Modules & articles (short):
   - Forms: <form data-fp-form="slug"> with named inputs; no action/onsubmit/honeypot.
   - Articles: frontpage articles …; migrate folders via frontpage prompt (don't invent mass delete+write).
-  - Media: frontpage media upload (images/PDF ≤25 MB, video ≤50 MB). Use sitePath /__media/uploads/<slug>/… in markup (not raw blob URLs). Optional ?w= on rasters only.
+  - Media: frontpage media upload (images/PDF ≤25 MB, video ≤50 MB). frontpage images generate --prompt "…" [--count N] for 1–4 AI variations of one invented picture (AI $ + storage). Use sitePath /__media/uploads/<slug>/… in markup (not raw blob URLs). Optional ?w= on rasters only.
 
   Full guide: https://frontpage.host/developers/site-building
   See also: frontpage help sync | content | AGENTS.md`,
@@ -568,8 +600,8 @@ export const TOPICS = {
   frontpage runs wait [runId]    # failed/canceled → exit 2; JSON ok:false + run.error
   frontpage runs cancel <runId>
   frontpage runs retry <runId>
-  frontpage deploy wait          # optional build wait; fail-closed on failed/canceled; NOT publish
-  frontpage publish              # ONLY if the user asked — production promote
+  frontpage deploy wait          # agent idle + tip compile ready; fail-closed; NOT publish
+  frontpage publish [--wait]     # ONLY if the user asked — promotes the ready compile
   frontpage unpublish --yes      # admin only; never unless asked; --yes when non-TTY
   frontpage usage
   frontpage analytics [--days 7]
@@ -589,6 +621,7 @@ export const TOPICS = {
   Do not publish unless asked.`,
     content: `Content
   frontpage media list|upload <file>   # images/PDF/video; text/CSV = inline not library; sitePath first when stored
+  frontpage images generate --prompt "…" [--count N]  # 1–4 AI variations of one prompt; sitePath first; AI $ + storage
   frontpage inbox [leads|subscribers|orders|google_reviews|…] [--mark-read] [--csv]
   frontpage seo get [/path|--path /path] | seo set --path /
   frontpage articles list|content|create-section|create-article|set-draft|…

package/llms.txt

@@ -8,7 +8,7 @@
 - Fonts: frontpage fonts [--slot] [--query] → exact value → tokens set fonts.<role> → APPLY font-sans|serif|mono|display. Build bundles catalog faces from tokens.ts and/or CSS font-family contexts (not prose). Inline-only without tokens works for catalog faces after rebuild; prefer tokens+utilities for brand roles.
 - Module/extension docs: frontpage modules docs <key> | frontpage extensions docs <key>
 - Search flags: --regex --case-sensitive --whole-word --files-only --context-lines --max-results
-- Modules setup: wizard modules (payments/shop/ordering): frontpage modules <key> connect [--no-open] opens Frontpage (logged-in browser) then Stripe/Square; already-connected stays live. payments/shop connect = admin key; ordering = editor. payments disconnect 409s if shop still uses the shared Stripe account. request-setup remains valid for the editor amber bar. frontpage modules <key> prints that key's CLI usage. Index: https://frontpage.host/developers/modules. Typed config: frontpage modules callbar|forms|booking|signups get|set (forms set needs --instance; confirm emails paid-plan only). google_reviews: frontpage modules google_reviews connect --place-id | --maps-url (server resolve + seed; no Autocomplete; do not write placeId via config). Also status, list-reviews, hide/show, set-stars, set-sort, set-weight, reset-weights, refresh, disconnect. Docs: https://frontpage.host/developers/modules/google-reviews. Markup: data-fp-google-reviews / data-fp-google-ask + required data-fp-requires="google_reviews". Ask scores: frontpage inbox google_reviews.
+- Modules setup: wizard modules (payments/shop/ordering): frontpage modules <key> connect [--no-open] opens Frontpage (logged-in browser) then Stripe/Square; already-connected stays live. payments/shop connect = admin key; ordering = editor. payments disconnect 409s if shop still uses the shared Stripe account. request-setup remains valid for the editor amber bar. frontpage modules <key> prints that key's CLI usage. Index: https://frontpage.host/developers/modules. Typed config: frontpage modules callbar|forms|booking|signups get|set (forms set needs --instance; confirm emails paid-plan only). Form destinations: frontpage modules forms destinations|connect-destination|attach-destination|detach-destination|remove-destination --yes|request-destination-setup (token = admin; request-destination-setup lights the editor bar; request-setup forms is a no-op; connect does not attach every form). Privyr: paste Incoming Webhook URL (https://www.privyr.com/api/v1/incoming-leads/…), not a token. HubSpot: Development → Keys → Service keys or Legacy apps → Auth → Show token. Pipedrive: profile → Company settings → Personal preferences → API. Docs: https://frontpage.host/developers/modules#forms-destinations. google_reviews: frontpage modules google_reviews connect --place-id | --maps-url (server resolve + seed; no Autocomplete; do not write placeId via config). Also status, list-reviews, hide/show, set-stars, set-sort, set-weight, reset-weights, refresh, disconnect. Docs: https://frontpage.host/developers/modules/google-reviews. Markup: data-fp-google-reviews / data-fp-google-ask + required data-fp-requires="google_reviews". Ask scores: frontpage inbox google_reviews.
 - Analytics ops: frontpage analytics summary|query|funnel|timeseries|compare|sql (bare analytics = dashboard)
 - Media: frontpage media upload <file> (images/PDF ≤25 MB, video ≤50 MB, SVG/text ≤4 MB); human prints sitePath first — use /__media/uploads/<slug>/… in markup. Text/CSV is inline only (not media library; --json omits full content).
 - Prompt attachments: frontpage prompt "…" --attach <file|/__media/…|https://…> [--asset-url https://…] (same media caps as media upload)
@@ -16,12 +16,12 @@
 - SEO get: frontpage seo get [/path|--path /path]; search path filter: [path|--path <path>]; open [/path|--path /path]
 - Analytics funnel: --steps JSON array or comma paths (/, /pricing); bad JSON → Invalid JSON for --steps
 - Modules: unknown key errors list Known: …; mailing list module key is signups (not subscribe)
-- Errors: --json API envelopes include requestId when the server returned one; local validation omits requestId/httpStatus; runs wait failed/canceled → ok:false + run.error (exit 2); deploy wait fail-closed; push --wait
+- Errors: --json API envelopes include requestId when the server returned one; local validation omits requestId/httpStatus; runs wait failed/canceled → ok:false + run.error (exit 2); deploy wait = agent idle + tip compile ready (fail-closed / compile timeout → exit 2); push --wait and publish --wait wait for GET /deploy ready
 - Auth: mint fp_live_ key in Frontpage UI (Developers); frontpage login KEY or FRONTPAGE_API_KEY
 - Site id: subdomain only (frontpage use <subdomain>). Not custom domains.
-- Staging: https://<subdomain>.frontpage.host — push/prompt/edit update staging; no separate staging deploy step. With a custom domain, subdomain may be owner-private (login wall ≠ failed push); public review is published custom domain.
-- Production: custom domain after frontpage publish — NEVER publish/unpublish unless the user explicitly asks
+- Three clocks: git tip (push/prompt/edit) ≠ site compile (GET /deploy ready) ≠ editor agent run (runs wait). File-only push has no agent run.
+- Production: frontpage publish promotes the last ready compile (409 if tip not built). frontpage publish --wait waits then publishes. NEVER publish/unpublish unless the user explicitly asks. Verify live <meta name="frontpage:commit">.
 - Sync: allowlist src/ public/ content/; platform overlay + secret-like paths rejected; pull before edit if tip may have moved (status/diff tipDrift); pull → edit → diff (blobSha) → push [--wait] (CAS); no push during active agent run; UI agent does not use CLI pull; review on subdomain
 - Machine: global --json / --quiet; exit 0/2/3/4/5 (see help exit-codes)
-- deploy wait = optional build wait only (fail-closed on failed/canceled); it is NOT go-live / publish
+- deploy wait = agent-run idle (if any) + tip compile ready; it is NOT go-live / publish
 - No runs continue, domains, billing, members, MCP, or git remotes in v1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "frontpage-host",
-  "version": "0.1.16",
+  "version": "0.1.17",
   "description": "Frontpage CLI — manage your site from the terminal",
   "type": "module",
   "bin": {