frontpage-host 0.1.5 → 0.1.7

package/AGENTS.md

@@ -108,19 +108,29 @@ 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 modules (payments/shop/ordering/instagram): after building gated markup, `frontpage modules request-setup <key> --reason "…"` once — owner finishes in the **editor status bar** (CLI cannot show it). Auto-active modules (forms/callbar/…) need markup, not request-setup.
 - 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 in markup: `/__media/uploads/<slug>/…` from `frontpage media` (not raw blob URLs).
+- Analytics: bare `frontpage analytics` = dashboard; also `summary|query|funnel|timeseries|compare|sql` for structured reads (SQL is guard + RLS site-scoped).
 
 ## Agent prompt loop
 
 ```bash
 frontpage prompt "make the hero shorter"
+frontpage prompt "Use this logo in the header" --attach ./logo.png
+frontpage prompt "Match this brand PDF" --attach ./guide.pdf --path /
+frontpage prompt "Reuse uploaded art" --attach /__media/uploads/<slug>/<file>
 frontpage runs wait          # wait for the agent run to finish
 # Review https://<subdomain>.frontpage.host — do not publish unless asked.
 ```
 
+- `--attach` accepts a local file (uploads via the same path as `frontpage media upload`), an existing `/__media/…` site path, or an `https://` Blob URL. Repeatable.
+- `--asset-url <https://…>` adds a legacy image URL. Repeatable.
+- Caps match the media proxy: images / PDF / text-code. CLI video and >4 MB binaries are not supported yet (editor attach / Phase E).
+- Prompt text is still required (API). Attachments ride on the same enqueue as the editor.
+
 Mid-task continuation is automatic. There is **no** `runs continue` in v1.
 
 ## Content / JSON-native commands
@@ -128,7 +138,7 @@ Mid-task continuation is automatic. There is **no** `runs continue` in v1.
 These already return JSON bodies (wrap further with global `--json` where supported):
 
 - `usage`, `analytics`, `seo`, `articles`, `settings`, `inbox` (default JSON)
-- Mutate: `modules enable|disable|archive|config`, `extensions …`
+- Mutate: `modules enable|disable|archive|config|request-setup`, `extensions …`
 
 Click-edit (exact single occurrence), **not** file push:
 

package/dist/commands/analytics.js

@@ -1,17 +1,175 @@
 import { resolveSlug } from "../site.js";
-import { EXIT_OK, exitCodeForError, v1Get } from "../http/client.js";
+import { EXIT_OK, EXIT_USAGE, exitCodeForError, v1Get, v1Post } from "../http/client.js";
+import { emitErr, emitOk, isJson } from "../runtime.js";
+function takeFlag(rest, name) {
+    const i = rest.indexOf(name);
+    if (i === -1)
+        return undefined;
+    const v = rest[i + 1];
+    rest.splice(i, 2);
+    return v;
+}
+function parseJsonFlag(raw, label) {
+    if (raw === undefined)
+        return undefined;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`${label} must be valid JSON`);
+    }
+}
+function rangeFields(work) {
+    const days = takeFlag(work, "--days");
+    const from = takeFlag(work, "--from");
+    const to = takeFlag(work, "--to");
+    const out = {};
+    if (days)
+        out.days = Number(days);
+    if (from)
+        out.from = from;
+    if (to)
+        out.to = to;
+    return out;
+}
+function printJson(data) {
+    console.log(JSON.stringify(data, null, 2));
+}
 export async function runAnalytics(args) {
     try {
         const { slug, rest } = await resolveSlug(args);
-        let days = "7";
-        const daysIdx = rest.indexOf("--days");
-        if (daysIdx >= 0 && rest[daysIdx + 1])
-            days = rest[daysIdx + 1];
-        const data = await v1Get(`/api/v1/sites/${encodeURIComponent(slug)}/analytics?days=${encodeURIComponent(days)}`);
-        console.log(JSON.stringify(data.dashboard, null, 2));
-        return EXIT_OK;
+        const work = [...rest];
+        const sub = work[0];
+        const ops = new Set(["summary", "query", "funnel", "timeseries", "compare", "sql", "dashboard"]);
+        // Bare `analytics` or `analytics dashboard` → legacy GET dashboard (compat).
+        if (!sub || sub === "dashboard" || !ops.has(sub) && sub.startsWith("--")) {
+            if (sub === "dashboard")
+                work.shift();
+            const days = takeFlag(work, "--days") ?? "7";
+            const data = await v1Get(`/api/v1/sites/${encodeURIComponent(slug)}/analytics?days=${encodeURIComponent(days)}`);
+            if (isJson()) {
+                emitOk("analytics", data);
+                return EXIT_OK;
+            }
+            printJson(data.dashboard);
+            return EXIT_OK;
+        }
+        if (!ops.has(sub)) {
+            console.error("Usage: frontpage analytics [dashboard|summary|query|funnel|timeseries|compare|sql] …");
+            return EXIT_USAGE;
+        }
+        work.shift();
+        const base = `/api/v1/sites/${encodeURIComponent(slug)}/analytics`;
+        if (sub === "summary") {
+            const filters = parseJsonFlag(takeFlag(work, "--filters"), "--filters");
+            const body = { op: "summary", ...rangeFields(work), ...(filters ? { filters } : {}) };
+            const data = await v1Post(base, body);
+            if (isJson())
+                emitOk("analytics", data);
+            else
+                printJson(data);
+            return EXIT_OK;
+        }
+        if (sub === "query") {
+            const dimension = takeFlag(work, "--dimension") ?? work.shift();
+            if (!dimension) {
+                console.error("Usage: frontpage analytics query --dimension <path|source|…> [--measure count] [--limit N] [--filters '{…}'] [--days N]");
+                return EXIT_USAGE;
+            }
+            const measure = takeFlag(work, "--measure");
+            const limit = takeFlag(work, "--limit");
+            const filters = parseJsonFlag(takeFlag(work, "--filters"), "--filters");
+            const body = {
+                op: "query",
+                dimension,
+                ...rangeFields(work),
+                ...(measure ? { measure } : {}),
+                ...(limit ? { limit: Number(limit) } : {}),
+                ...(filters ? { filters } : {}),
+            };
+            const data = await v1Post(base, body);
+            if (isJson())
+                emitOk("analytics", data);
+            else
+                printJson(data);
+            return EXIT_OK;
+        }
+        if (sub === "funnel") {
+            const stepsRaw = takeFlag(work, "--steps");
+            if (!stepsRaw) {
+                console.error(`Usage: frontpage analytics funnel --steps '[{"path":"/"},{"path":"/pricing"}]' [--days N]`);
+                return EXIT_USAGE;
+            }
+            const steps = parseJsonFlag(stepsRaw, "--steps");
+            const body = { op: "funnel", steps, ...rangeFields(work) };
+            const data = await v1Post(base, body);
+            if (isJson())
+                emitOk("analytics", data);
+            else
+                printJson(data);
+            return EXIT_OK;
+        }
+        if (sub === "timeseries") {
+            const metric = takeFlag(work, "--metric");
+            const interval = takeFlag(work, "--interval");
+            const filters = parseJsonFlag(takeFlag(work, "--filters"), "--filters");
+            const body = {
+                op: "timeseries",
+                ...rangeFields(work),
+                ...(metric ? { metric } : {}),
+                ...(interval ? { interval } : {}),
+                ...(filters ? { filters } : {}),
+            };
+            const data = await v1Post(base, body);
+            if (isJson())
+                emitOk("analytics", data);
+            else
+                printJson(data);
+            return EXIT_OK;
+        }
+        if (sub === "compare") {
+            const aRaw = takeFlag(work, "--a");
+            const bRaw = takeFlag(work, "--b");
+            if (!aRaw || !bRaw) {
+                console.error(`Usage: frontpage analytics compare --a '{"device":"mobile"}' --b '{"device":"desktop"}' [--metric uniqueVisitors] [--days N]`);
+                return EXIT_USAGE;
+            }
+            const a = parseJsonFlag(aRaw, "--a");
+            const b = parseJsonFlag(bRaw, "--b");
+            const metric = takeFlag(work, "--metric");
+            const body = {
+                op: "compare",
+                a,
+                b,
+                ...rangeFields(work),
+                ...(metric ? { metric } : {}),
+            };
+            const data = await v1Post(base, body);
+            if (isJson())
+                emitOk("analytics", data);
+            else
+                printJson(data);
+            return EXIT_OK;
+        }
+        if (sub === "sql") {
+            const sql = takeFlag(work, "--sql") ?? work.join(" ").trim();
+            if (!sql) {
+                console.error('Usage: frontpage analytics sql --sql "SELECT path, count(*) FROM analytics_events GROUP BY 1"');
+                return EXIT_USAGE;
+            }
+            const data = await v1Post(base, { op: "sql", sql });
+            if (isJson())
+                emitOk("analytics", data);
+            else
+                printJson(data);
+            return EXIT_OK;
+        }
+        console.error("Usage: frontpage analytics [dashboard|summary|query|funnel|timeseries|compare|sql] …");
+        return EXIT_USAGE;
     }
     catch (err) {
+        if (isJson())
+            return emitErr("analytics", err);
         console.error(err instanceof Error ? err.message : String(err));
         return exitCodeForError(err);
     }

package/dist/commands/modules.js

@@ -36,6 +36,34 @@ export async function runModules(args) {
             console.log(data.docs);
             return EXIT_OK;
         }
+        if (sub === "request-setup" || sub === "request_setup") {
+            const key = rest[1];
+            if (!key) {
+                console.error("Usage: frontpage modules request-setup <key> --reason \"…\" [--prefill '{…}'] [--instance <id>] [--site <slug>]");
+                return EXIT_USAGE;
+            }
+            const work = rest.slice(2);
+            const instanceId = takeFlag(work, "--instance");
+            const reason = takeFlag(work, "--reason");
+            const prefillRaw = takeFlag(work, "--prefill");
+            if (!reason) {
+                console.error("Usage: frontpage modules request-setup <key> --reason \"…\" [--prefill '{…}']");
+                return EXIT_USAGE;
+            }
+            let prefill;
+            if (prefillRaw) {
+                try {
+                    prefill = JSON.parse(prefillRaw);
+                }
+                catch {
+                    console.error("--prefill must be valid JSON");
+                    return EXIT_USAGE;
+                }
+            }
+            const data = await v1Post(`/api/v1/sites/${encodeURIComponent(slug)}/modules/${encodeURIComponent(key)}`, { action: "request-setup", reason, prefill, instanceId });
+            console.log(JSON.stringify(data, null, 2));
+            return EXIT_OK;
+        }
         if (sub === "enable" || sub === "disable" || sub === "archive" || sub === "config") {
             const key = rest[1];
             if (!key) {
@@ -63,7 +91,7 @@ export async function runModules(args) {
             console.log(JSON.stringify(data, null, 2));
             return EXIT_OK;
         }
-        console.error("Usage: frontpage modules [list|docs|enable|disable|archive|config] …");
+        console.error("Usage: frontpage modules [list|docs|request-setup|enable|disable|archive|config] …");
         return EXIT_USAGE;
     }
     catch (err) {

package/dist/commands/prompt-attach.d.ts

@@ -0,0 +1,59 @@
+/** Mirror ATTACH_LIMITS in src/lib/agent/attachments.ts (images/docs/text only via proxy media). */
+export declare const CLI_ATTACH_LIMITS: {
+    readonly maxImages: 6;
+    readonly maxDocuments: 4;
+    readonly maxTextFiles: 6;
+};
+export type PromptAttachmentsPayload = {
+    images: Array<{
+        url: string;
+        name?: string;
+    }>;
+    documents: Array<{
+        url: string;
+        name?: string;
+    }>;
+    textFiles: Array<{
+        name: string;
+        content: string;
+    }>;
+};
+export type MediaUploadResult = {
+    kind: string;
+    url?: string;
+    key?: string;
+    filename?: string;
+    sizeBytes?: number;
+    content?: string;
+};
+export declare function emptyAttachments(): PromptAttachmentsPayload;
+export declare function isHttpsUrl(s: string): boolean;
+export declare function isMediaSitePath(s: string): boolean;
+export declare function classifyRemoteByName(nameOrUrl: string): "image" | "document";
+export declare function addHttpsRef(out: PromptAttachmentsPayload, url: string, opts?: {
+    name?: string;
+    asImageOnly?: boolean;
+}): void;
+export declare function addUploadResult(out: PromptAttachmentsPayload, data: MediaUploadResult): void;
+export declare function uploadLocalForAttach(slug: string, filePath: string): Promise<MediaUploadResult>;
+export declare function resolveSitePathUrl(slug: string, sitePath: string): Promise<{
+    url: string;
+    name: string;
+    type: string;
+}>;
+/**
+ * Resolve one --attach value (local path, /__media/…, or https URL) into the payload.
+ */
+export declare function resolveAttachRef(slug: string, ref: string, out: PromptAttachmentsPayload): Promise<void>;
+export declare function buildPromptAttachments(args: {
+    slug: string;
+    attachRefs: string[];
+    assetUrls: string[];
+}): Promise<PromptAttachmentsPayload | undefined>;
+/** Parse prompt argv: prompt words + --path / --attach / --asset-url flags. */
+export declare function parsePromptArgs(rest: string[]): {
+    prompt: string;
+    currentPath: string;
+    attachRefs: string[];
+    assetUrls: string[];
+};

package/dist/commands/prompt-attach.js

@@ -0,0 +1,207 @@
+/**
+ * §CLI Phase C — resolve --attach / --asset-url into the agent attachments payload.
+ * Local files upload via the same multipart media endpoint as `frontpage media upload`.
+ */
+import { access, readFile } from "node:fs/promises";
+import { basename } from "node:path";
+import { constants as fsConstants } from "node:fs";
+import { v1Get, v1PostMultipart, CliHttpError, EXIT_USAGE, EXIT_UNEXPECTED } from "../http/client.js";
+/** Mirror ATTACH_LIMITS in src/lib/agent/attachments.ts (images/docs/text only via proxy media). */
+export const CLI_ATTACH_LIMITS = {
+    maxImages: 6,
+    maxDocuments: 4,
+    maxTextFiles: 6,
+};
+export function emptyAttachments() {
+    return { images: [], documents: [], textFiles: [] };
+}
+export function isHttpsUrl(s) {
+    return /^https:\/\/[^\s]+$/i.test(s) && s.length <= 2048;
+}
+export function isMediaSitePath(s) {
+    return s.startsWith("/__media/");
+}
+export function classifyRemoteByName(nameOrUrl) {
+    const base = nameOrUrl.split(/[?#]/)[0] ?? nameOrUrl;
+    const ext = base.includes(".") ? (base.split(".").pop() ?? "").toLowerCase() : "";
+    if (ext === "pdf")
+        return "document";
+    return "image";
+}
+function pushUniqueUrl(list, max, url, name, label) {
+    if (list.some((x) => x.url === url))
+        return;
+    if (list.length >= max) {
+        throw new CliHttpError(`Too many ${label} attachments (max ${max}).`, EXIT_USAGE, 400, "bad_request");
+    }
+    list.push(name ? { url, name } : { url });
+}
+function pushText(list, name, content) {
+    if (list.length >= CLI_ATTACH_LIMITS.maxTextFiles) {
+        throw new CliHttpError(`Too many text attachments (max ${CLI_ATTACH_LIMITS.maxTextFiles}).`, EXIT_USAGE, 400, "bad_request");
+    }
+    list.push({ name, content });
+}
+export function addHttpsRef(out, url, opts) {
+    if (!isHttpsUrl(url)) {
+        throw new CliHttpError(`Not an https URL: ${url}`, EXIT_USAGE, 400, "bad_request");
+    }
+    const kind = opts?.asImageOnly ? "image" : classifyRemoteByName(opts?.name ?? url);
+    if (kind === "document") {
+        pushUniqueUrl(out.documents, CLI_ATTACH_LIMITS.maxDocuments, url, opts?.name, "document");
+    }
+    else {
+        pushUniqueUrl(out.images, CLI_ATTACH_LIMITS.maxImages, url, opts?.name, "image");
+    }
+}
+export function addUploadResult(out, data) {
+    const name = data.filename?.trim() || undefined;
+    if (data.kind === "text") {
+        if (typeof data.content !== "string" || !data.content) {
+            throw new CliHttpError("Text upload returned no content.", EXIT_UNEXPECTED, 500, "internal");
+        }
+        pushText(out.textFiles, name ?? "snippet.txt", data.content);
+        return;
+    }
+    if (data.kind === "image" || data.kind === "document") {
+        if (!data.url || !isHttpsUrl(data.url)) {
+            throw new CliHttpError(`Upload of ${name ?? "file"} did not return a Blob URL.`, EXIT_UNEXPECTED, 500, "internal");
+        }
+        if (data.kind === "document") {
+            pushUniqueUrl(out.documents, CLI_ATTACH_LIMITS.maxDocuments, data.url, name, "document");
+        }
+        else {
+            pushUniqueUrl(out.images, CLI_ATTACH_LIMITS.maxImages, data.url, name, "image");
+        }
+        return;
+    }
+    throw new CliHttpError(`Unsupported upload kind "${data.kind}" for prompt attach. Use images, PDFs, or text/code files (video/large files need the editor path until Phase E).`, EXIT_USAGE, 400, "bad_request");
+}
+export async function uploadLocalForAttach(slug, filePath) {
+    try {
+        await access(filePath, fsConstants.R_OK);
+    }
+    catch {
+        throw new CliHttpError(`Cannot read file for --attach: ${filePath}`, EXIT_USAGE, 400, "bad_request");
+    }
+    const bytes = await readFile(filePath);
+    if (bytes.length === 0) {
+        throw new CliHttpError(`File is empty: ${filePath}`, EXIT_USAGE, 400, "bad_request");
+    }
+    const form = new FormData();
+    form.append("file", new Blob([Uint8Array.from(bytes)]), basename(filePath));
+    return v1PostMultipart(`/api/v1/sites/${encodeURIComponent(slug)}/media`, form);
+}
+export async function resolveSitePathUrl(slug, sitePath) {
+    const data = await v1Get(`/api/v1/sites/${encodeURIComponent(slug)}/media`);
+    const norm = (p) => p.replace(/\/+/g, "/").replace(/\/$/, "") || p;
+    const want = norm(sitePath);
+    const hit = data.assets.find((a) => a.sitePath === sitePath || norm(a.sitePath) === want);
+    if (!hit?.url) {
+        throw new CliHttpError(`No media asset found for ${sitePath}. Upload with frontpage media upload, or pass a Blob https URL.`, EXIT_USAGE, 404, "not_found");
+    }
+    return { url: hit.url, name: hit.name, type: hit.type };
+}
+/**
+ * Resolve one --attach value (local path, /__media/…, or https URL) into the payload.
+ */
+export async function resolveAttachRef(slug, ref, out) {
+    const raw = ref.trim();
+    if (!raw) {
+        throw new CliHttpError("--attach requires a path or URL", EXIT_USAGE, 400, "bad_request");
+    }
+    if (/^https?:\/\//i.test(raw)) {
+        if (!isHttpsUrl(raw)) {
+            throw new CliHttpError(`--attach URLs must be https:// (got ${raw.split(":")[0]}://)`, EXIT_USAGE, 400, "bad_request");
+        }
+        addHttpsRef(out, raw);
+        return;
+    }
+    if (isMediaSitePath(raw)) {
+        const asset = await resolveSitePathUrl(slug, raw);
+        const kind = classifyRemoteByName(asset.name || asset.type || raw);
+        if (kind === "document") {
+            pushUniqueUrl(out.documents, CLI_ATTACH_LIMITS.maxDocuments, asset.url, asset.name, "document");
+        }
+        else {
+            pushUniqueUrl(out.images, CLI_ATTACH_LIMITS.maxImages, asset.url, asset.name, "image");
+        }
+        return;
+    }
+    const uploaded = await uploadLocalForAttach(slug, raw);
+    addUploadResult(out, uploaded);
+}
+export async function buildPromptAttachments(args) {
+    if (args.attachRefs.length === 0 && args.assetUrls.length === 0)
+        return undefined;
+    const out = emptyAttachments();
+    for (const url of args.assetUrls) {
+        addHttpsRef(out, url.trim(), { asImageOnly: true });
+    }
+    for (const ref of args.attachRefs) {
+        await resolveAttachRef(args.slug, ref, out);
+    }
+    if (out.images.length === 0 &&
+        out.documents.length === 0 &&
+        out.textFiles.length === 0) {
+        throw new CliHttpError("No attachments could be resolved from --attach / --asset-url.", EXIT_USAGE, 400, "bad_request");
+    }
+    return out;
+}
+/** Parse prompt argv: prompt words + --path / --attach / --asset-url flags. */
+export function parsePromptArgs(rest) {
+    let currentPath = "/";
+    const promptParts = [];
+    const attachRefs = [];
+    const assetUrls = [];
+    for (let i = 0; i < rest.length; i++) {
+        const a = rest[i];
+        if (a === "--path") {
+            currentPath = rest[++i] ?? "/";
+            continue;
+        }
+        if (a.startsWith("--path=")) {
+            currentPath = a.slice("--path=".length) || "/";
+            continue;
+        }
+        if (a === "--attach") {
+            const v = rest[++i];
+            if (!v || v.startsWith("--")) {
+                throw new CliHttpError('Usage: frontpage prompt "…" --attach <file|/__media/…|https://…>', EXIT_USAGE, 400, "bad_request");
+            }
+            attachRefs.push(v);
+            continue;
+        }
+        if (a.startsWith("--attach=")) {
+            const v = a.slice("--attach=".length);
+            if (!v) {
+                throw new CliHttpError("--attach= requires a value", EXIT_USAGE, 400, "bad_request");
+            }
+            attachRefs.push(v);
+            continue;
+        }
+        if (a === "--asset-url") {
+            const v = rest[++i];
+            if (!v || v.startsWith("--")) {
+                throw new CliHttpError("Usage: frontpage prompt \"…\" --asset-url <https://…>", EXIT_USAGE, 400, "bad_request");
+            }
+            assetUrls.push(v);
+            continue;
+        }
+        if (a.startsWith("--asset-url=")) {
+            const v = a.slice("--asset-url=".length);
+            if (!v) {
+                throw new CliHttpError("--asset-url= requires a value", EXIT_USAGE, 400, "bad_request");
+            }
+            assetUrls.push(v);
+            continue;
+        }
+        promptParts.push(a);
+    }
+    return {
+        prompt: promptParts.join(" ").trim(),
+        currentPath,
+        attachRefs,
+        assetUrls,
+    };
+}

package/dist/commands/prompt.js

@@ -1,38 +1,48 @@
 import { resolveSlug } from "../site.js";
 import { EXIT_OK, EXIT_USAGE, v1Post } from "../http/client.js";
 import { emitErr, emitOk, emitUsage, isJson } from "../runtime.js";
+import { buildPromptAttachments, parsePromptArgs } from "./prompt-attach.js";
 export async function runPrompt(args) {
     try {
         const { slug, rest } = await resolveSlug(args);
-        let currentPath = "/";
-        const promptParts = [];
-        for (let i = 0; i < rest.length; i++) {
-            const a = rest[i];
-            if (a === "--path") {
-                currentPath = rest[++i] ?? "/";
-                continue;
-            }
-            if (a.startsWith("--path=")) {
-                currentPath = a.slice("--path=".length) || "/";
-                continue;
-            }
-            promptParts.push(a);
-        }
-        const prompt = promptParts.join(" ").trim();
+        const { prompt, currentPath, attachRefs, assetUrls } = parsePromptArgs(rest);
         if (!prompt) {
-            return emitUsage("prompt", 'Usage: frontpage prompt "..." [--site <slug>] [--path /page]', EXIT_USAGE);
+            return emitUsage("prompt", 'Usage: frontpage prompt "..." [--site <slug>] [--path /page] [--attach <file|/__media/…|https://…>]… [--asset-url <https://…>]…', EXIT_USAGE);
         }
         if (!currentPath.startsWith("/")) {
             return emitUsage("prompt", "currentPath must start with /", EXIT_USAGE);
         }
-        const data = await v1Post(`/api/v1/sites/${encodeURIComponent(slug)}/agent-runs`, { prompt, currentPath });
+        const attachments = await buildPromptAttachments({ slug, attachRefs, assetUrls });
+        const body = { prompt, currentPath };
+        if (attachments) {
+            body.attachments = attachments;
+            // Legacy image list for run display / back-compat readers.
+            body.assetUrls = attachments.images.map((i) => i.url);
+        }
+        const data = await v1Post(`/api/v1/sites/${encodeURIComponent(slug)}/agent-runs`, body);
         if (isJson()) {
-            emitOk("prompt", { slug, ...data });
+            emitOk("prompt", {
+                slug,
+                ...data,
+                attached: attachments
+                    ? {
+                        images: attachments.images.length,
+                        documents: attachments.documents.length,
+                        textFiles: attachments.textFiles.length,
+                    }
+                    : undefined,
+            });
         }
         else {
             console.log(data.runId);
             if (data.coalesced)
                 console.error("(coalesced with an identical queued run)");
+            if (attachments) {
+                const n = attachments.images.length +
+                    attachments.documents.length +
+                    attachments.textFiles.length;
+                console.error(`(attached ${n} file${n === 1 ? "" : "s"})`);
+            }
         }
         return EXIT_OK;
     }

package/dist/completions/generate.js

@@ -23,8 +23,10 @@ _frontpage_completions() {
     tokens) COMPREPLY=( $(compgen -W "set" -- "\${cur}") ) ;;
     seo|settings) COMPREPLY=( $(compgen -W "get set" -- "\${cur}") ) ;;
     articles) COMPREPLY=( $(compgen -W "list content create-section create-article set-draft" -- "\${cur}") ) ;;
-    modules) COMPREPLY=( $(compgen -W "list docs enable disable archive config" -- "\${cur}") ) ;;
+    analytics) COMPREPLY=( $(compgen -W "dashboard summary query funnel timeseries compare sql" -- "\${cur}") ) ;;
+    modules) COMPREPLY=( $(compgen -W "list docs request-setup enable disable archive config" -- "\${cur}") ) ;;
     extensions) COMPREPLY=( $(compgen -W "list docs enable disable config" -- "\${cur}") ) ;;
+    prompt) COMPREPLY=( $(compgen -W "--path --attach --asset-url --site --json --help" -- "\${cur}") ) ;;
     *) COMPREPLY=( $(compgen -W "--site --help --json --quiet --yes" -- "\${cur}") ) ;;
   esac
 }
@@ -50,7 +52,9 @@ _frontpage() {
         fonts) _values 'subcommand' list search ;;
         tokens) _values 'subcommand' set ;;
         seo|settings) _values 'subcommand' get set ;;
-        modules|extensions) _values 'subcommand' list docs enable disable config ;;
+        analytics) _values 'subcommand' dashboard summary query funnel timeseries compare sql ;;
+        modules) _values 'subcommand' list docs request-setup enable disable archive config ;;
+        extensions) _values 'subcommand' list docs enable disable config ;;
       esac
       ;;
   esac
@@ -70,7 +74,9 @@ export function generateFishCompletion() {
         `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 modules extensions" -a "list docs enable disable config"`,
+        `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"`,
+        `complete -c frontpage -n "__fish_seen_subcommand_from extensions" -a "list docs enable disable config"`,
         `complete -c frontpage -l site -d "Site subdomain slug"`,
     ];
     return `${lines.join("\n")}\n`;

package/dist/registry.js

@@ -184,11 +184,23 @@ export const COMMANDS = [
     {
         name: "prompt",
         summary: "Enqueue an agent build",
-        usage: 'frontpage prompt "..." [--site <slug>] [--path /] [--json]',
+        usage: 'frontpage prompt "..." [--site <slug>] [--path /] [--attach <file|/__media/…|https://…>]… [--asset-url <https://…>]… [--json]',
         topics: ["agent"],
-        examples: ['frontpage prompt "make the hero shorter"'],
-        flags: ["--path must start with /", "stdout is bare runId (or JSON with --json)"],
-        seeAlso: ["runs", "deploy"],
+        examples: [
+            'frontpage prompt "make the hero shorter"',
+            'frontpage prompt "Use this logo in the header" --attach ./logo.png',
+            'frontpage prompt "Match this PDF brand guide" --attach ./guide.pdf --path /',
+            'frontpage prompt "Reuse uploaded art" --attach /__media/uploads/acme/uuid.png',
+            'frontpage prompt "Use this image" --asset-url "https://….blob.vercel-storage.com/uploads/…"',
+        ],
+        flags: [
+            "--path must start with /",
+            "--attach: local file (uploads via media), /__media/… site path, or https Blob URL; repeatable",
+            "--asset-url: https image URL (legacy); repeatable",
+            "Local attach uses the same caps as frontpage media upload (images/PDF/text; no CLI video yet)",
+            "stdout is bare runId (or JSON with --json)",
+        ],
+        seeAlso: ["runs", "deploy", "media"],
     },
     {
         name: "runs",
@@ -246,9 +258,22 @@ export const COMMANDS = [
     },
     {
         name: "analytics",
-        summary: "Show analytics dashboard JSON",
-        usage: "frontpage analytics [--days 7] [--site <slug>]",
+        summary: "Analytics dashboard or structured query ops",
+        usage: "frontpage analytics [dashboard|summary|query|funnel|timeseries|compare|sql] … [--site <slug>] [--json]",
         topics: ["agent"],
+        examples: [
+            "frontpage analytics --days 7",
+            "frontpage analytics summary --days 30",
+            "frontpage analytics query --dimension path --measure count --limit 10",
+            `frontpage analytics funnel --steps '[{"path":"/"},{"path":"/pricing"}]'`,
+            "frontpage analytics timeseries --metric pageviews --interval day --days 14",
+            `frontpage analytics compare --a '{"device":"mobile"}' --b '{"device":"desktop"}'`,
+            'frontpage analytics sql --sql "SELECT path, count(*)::int AS n FROM analytics_events GROUP BY 1 ORDER BY n DESC LIMIT 10"',
+        ],
+        flags: [
+            "Bare analytics / dashboard = legacy GET dashboard (compat)",
+            "Ops use POST …/analytics with allowlisted dimensions/measures; SQL is guard-validated + RLS",
+        ],
     },
     {
         name: "pages",
@@ -259,10 +284,17 @@ export const COMMANDS = [
     {
         name: "modules",
         summary: "List, read docs, or mutate modules (secret masks only)",
-        usage: "frontpage modules [list|docs|enable|disable|archive|config] <key> [--instance <id>] [--config '{…}'] [--site <slug>]",
+        usage: "frontpage modules [list|docs|request-setup|enable|disable|archive|config] <key> [--instance <id>] [--config '{…}'] [--site <slug>]",
         topics: ["agent", "content"],
-        examples: ["frontpage modules docs forms", "frontpage modules list"],
-        dangers: ["Secret values are never returned — masks only"],
+        examples: [
+            "frontpage modules docs forms",
+            "frontpage modules list",
+            'frontpage modules request-setup payments --reason "You asked for a $50 deposit button — Stripe setup makes it live"',
+        ],
+        dangers: [
+            "Secret values are never returned — masks only",
+            "request-setup surfaces an owner prompt in the editor status bar (CLI cannot show it)",
+        ],
     },
     {
         name: "extensions",
@@ -447,6 +479,8 @@ export const TOPICS = {
   See also: frontpage help sync | content | AGENTS.md`,
     agent: `Agent + publish
   frontpage prompt "make the hero shorter"
+  frontpage prompt "Use this logo" --attach ./logo.png
+  frontpage prompt "…" --attach /__media/uploads/<slug>/… --asset-url https://…
   frontpage runs                 # latest + active
   frontpage runs wait [runId]
   frontpage runs cancel <runId>
@@ -456,10 +490,13 @@ export const TOPICS = {
   frontpage unpublish --yes      # admin only; never unless asked; --yes when non-TTY
   frontpage usage
   frontpage analytics [--days 7]
+  frontpage analytics summary|query|funnel|timeseries|compare|sql …
   frontpage pages
   frontpage modules
+  frontpage modules request-setup <key> --reason "…"
   frontpage extensions
 
+  --attach uploads local files via media (images/PDF/text) or accepts /__media/… / https URLs.
   Mid-task continuation is automatic — there is no runs continue.
   Do not push while an agent run is active.
   Default after work: review https://<subdomain>.frontpage.host; do not publish.`,
@@ -470,7 +507,7 @@ export const TOPICS = {
   frontpage articles list|content|create-section|create-article|set-draft|…
   frontpage fonts [list|search] [--slot …] [--query …]
   frontpage tokens set --group … --key … --value …
-  frontpage modules list|docs|enable|disable|archive|config <key>
+  frontpage modules list|docs|request-setup|enable|disable|archive|config <key>
   frontpage extensions list|docs|enable|disable|config <key>
   frontpage settings get|set
   frontpage edit --path / --old "…" --new "…"

package/llms.txt

@@ -8,6 +8,9 @@
 - Fonts: frontpage fonts [--slot] [--query] — use exact value; tokens: frontpage tokens set --group --key --value (CAS)
 - 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: frontpage modules request-setup <key> --reason "…" (owner status bar; CLI cannot show it)
+- Analytics ops: frontpage analytics summary|query|funnel|timeseries|compare|sql (bare analytics = dashboard)
+- Prompt attachments: frontpage prompt "…" --attach <file|/__media/…|https://…> [--asset-url https://…] (media upload for locals; images/PDF/text)
 - 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 for agents

package/package.json

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