frontpage-host 0.1.8 → 0.1.10

package/dist/flags.js

@@ -1,6 +1,6 @@
 /**
  * Strip global flags from argv. Safe to call before command dispatch.
- * Recognizes --json, --quiet, --yes, and help aliases anywhere in the list.
+ * Recognizes --json, --quiet, --yes, --version/-V, and help aliases anywhere in the list.
  */
 export function parseGlobalFlags(argv) {
     const args = [];
@@ -8,6 +8,7 @@ export function parseGlobalFlags(argv) {
     let quiet = false;
     let yes = false;
     let wantsHelp = false;
+    let wantsVersion = false;
     for (const a of argv) {
         if (a === "--json") {
             json = true;
@@ -25,7 +26,11 @@ export function parseGlobalFlags(argv) {
             wantsHelp = true;
             continue;
         }
+        if (a === "--version" || a === "-V") {
+            wantsVersion = true;
+            continue;
+        }
         args.push(a);
     }
-    return { json, quiet, yes, wantsHelp, args };
+    return { json, quiet, yes, wantsHelp, wantsVersion, args };
 }

package/dist/http/client.d.ts

@@ -21,6 +21,8 @@ export declare class CliHttpError extends Error {
 /** Map a non-OK v1 response into CliHttpError (shared by JSON + multipart clients). */
 export declare function httpErrorFromV1(status: number, parsed: V1Envelope, fallbackMessage?: string): CliHttpError;
 export declare function apiBase(): string;
+/** Bearer header for raw fetch (e.g. Blob client-token exchange). */
+export declare function getBearerAuthHeader(): Promise<Record<string, string>>;
 export declare function v1Get<T>(path: string): Promise<T>;
 export declare function v1Post<T>(path: string, body?: unknown): Promise<T>;
 export declare function v1Put<T>(path: string, body?: unknown): Promise<T>;

package/dist/http/client.js

@@ -61,6 +61,14 @@ export function apiBase() {
         return fromEnv;
     return "https://app.frontpage.host";
 }
+/** Bearer header for raw fetch (e.g. Blob client-token exchange). */
+export async function getBearerAuthHeader() {
+    const key = await getApiKey();
+    if (!key) {
+        throw new CliHttpError("Not logged in. Run: frontpage login", EXIT_AUTH, 401);
+    }
+    return { Authorization: `Bearer ${key}` };
+}
 async function v1Request(method, path, body) {
     const key = await getApiKey();
     if (!key) {

package/dist/media/limits.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Mirror of app `src/lib/upload/limits.ts` + video ext set (CLI cannot import app code).
+ * Keep values in lockstep with the platform.
+ */
+export declare const MAX_UPLOAD_BYTES: number;
+export declare const MAX_VIDEO_UPLOAD_BYTES: number;
+export declare const MAX_PROXY_UPLOAD_BYTES: number;
+export declare const MAX_INLINE_TEXT_BYTES: number;
+export declare const VIDEO_UPLOAD_EXT: Set<string>;
+export declare const RASTER_EXT: Set<string>;
+export declare const PDF_EXT: Set<string>;
+export declare const SVG_EXT: Set<string>;
+/** Common text/code extensions (proxy/inline only via CLI — no FU.9 client path). */
+export declare const TEXT_EXT: Set<string>;
+export declare function formatBytes(n: number): string;
+export declare function extOf(filename: string): string;
+export declare function contentTypeForExt(ext: string): string | undefined;
+export declare function sitePathFromKey(key: string): string;

package/dist/media/limits.js

@@ -0,0 +1,101 @@
+/**
+ * Mirror of app `src/lib/upload/limits.ts` + video ext set (CLI cannot import app code).
+ * Keep values in lockstep with the platform.
+ */
+export const MAX_UPLOAD_BYTES = 25 * 1024 * 1024;
+export const MAX_VIDEO_UPLOAD_BYTES = 50 * 1024 * 1024;
+export const MAX_PROXY_UPLOAD_BYTES = 4 * 1024 * 1024;
+export const MAX_INLINE_TEXT_BYTES = 256 * 1024;
+export const VIDEO_UPLOAD_EXT = new Set(["mp4", "webm", "mov", "m4v"]);
+export const RASTER_EXT = new Set(["png", "jpg", "jpeg", "gif", "webp", "avif"]);
+export const PDF_EXT = new Set(["pdf"]);
+export const SVG_EXT = new Set(["svg"]);
+/** Common text/code extensions (proxy/inline only via CLI — no FU.9 client path). */
+export const TEXT_EXT = new Set([
+    "txt",
+    "md",
+    "markdown",
+    "csv",
+    "tsv",
+    "json",
+    "json5",
+    "jsonc",
+    "html",
+    "htm",
+    "css",
+    "scss",
+    "sass",
+    "less",
+    "js",
+    "mjs",
+    "cjs",
+    "jsx",
+    "ts",
+    "tsx",
+    "py",
+    "rb",
+    "php",
+    "go",
+    "rs",
+    "java",
+    "kt",
+    "swift",
+    "c",
+    "h",
+    "cpp",
+    "cc",
+    "yaml",
+    "yml",
+    "toml",
+    "ini",
+    "env",
+    "xml",
+    "sql",
+    "sh",
+    "graphql",
+    "gql",
+]);
+export function formatBytes(n) {
+    if (!Number.isFinite(n) || n < 0)
+        return "0 bytes";
+    if (n < 1024)
+        return `${Math.round(n)} bytes`;
+    if (n < 1024 * 1024)
+        return `${(n / 1024).toFixed(0)} KB`;
+    return `${(n / (1024 * 1024)).toFixed(1)} MB`;
+}
+export function extOf(filename) {
+    const base = (filename || "").split(/[/\\]/).pop() ?? "";
+    return base.includes(".") ? (base.split(".").pop() ?? "").toLowerCase() : "";
+}
+export function contentTypeForExt(ext) {
+    switch (ext) {
+        case "png":
+            return "image/png";
+        case "jpg":
+        case "jpeg":
+            return "image/jpeg";
+        case "gif":
+            return "image/gif";
+        case "webp":
+            return "image/webp";
+        case "avif":
+            return "image/avif";
+        case "pdf":
+            return "application/pdf";
+        case "mp4":
+            return "video/mp4";
+        case "webm":
+            return "video/webm";
+        case "mov":
+            return "video/quicktime";
+        case "m4v":
+            return "video/x-m4v";
+        default:
+            return undefined;
+    }
+}
+export function sitePathFromKey(key) {
+    const k = key.replace(/^\//, "");
+    return k.startsWith("__media/") ? `/${k}` : `/__media/${k}`;
+}

package/dist/media/select-transport.d.ts

@@ -0,0 +1,27 @@
+export type MediaKind = "image" | "document" | "video" | "text";
+export type TransportDecision = {
+    transport: "proxy";
+    kind: MediaKind;
+} | {
+    transport: "client";
+    kind: Exclude<MediaKind, "text">;
+    ext: string;
+    contentType: string;
+} | {
+    transport: "reject";
+    message: string;
+};
+/**
+ * Minimal video sniff for files without a recognized extension.
+ * Mirrors server `sniffType` enough to avoid classifying AVIF/HEIC as video.
+ */
+export declare function sniffVideoExt(head: Uint8Array): "mp4" | "webm" | null;
+/**
+ * Decide proxy vs direct-to-Blob vs reject for a local file.
+ * `headBytes` (optional) enables video detection when the extension is missing/wrong.
+ */
+export declare function selectMediaTransport(input: {
+    filename: string;
+    sizeBytes: number;
+    headBytes?: Uint8Array;
+}): TransportDecision;

package/dist/media/select-transport.js

@@ -0,0 +1,134 @@
+/**
+ * Phase E — pure transport matrix for `frontpage media upload`.
+ */
+import { extOf, formatBytes, MAX_PROXY_UPLOAD_BYTES, MAX_UPLOAD_BYTES, MAX_VIDEO_UPLOAD_BYTES, PDF_EXT, RASTER_EXT, SVG_EXT, TEXT_EXT, VIDEO_UPLOAD_EXT, } from "./limits.js";
+function asciiAt(bytes, offset, s) {
+    if (bytes.length < offset + s.length)
+        return false;
+    for (let i = 0; i < s.length; i++)
+        if (bytes[offset + i] !== s.charCodeAt(i))
+            return false;
+    return true;
+}
+/** Brands that share ISOBMFF/`ftyp` but are NOT video (must not route to client-as-mp4). */
+const NON_VIDEO_FTYP_BRANDS = new Set(["avif", "avis", "heic", "heif", "mif1", "msf1"]);
+function ftypBrand(head) {
+    if (!asciiAt(head, 4, "ftyp") || head.length < 12)
+        return null;
+    return String.fromCharCode(head[8], head[9], head[10], head[11]).toLowerCase();
+}
+/**
+ * Minimal video sniff for files without a recognized extension.
+ * Mirrors server `sniffType` enough to avoid classifying AVIF/HEIC as video.
+ */
+export function sniffVideoExt(head) {
+    const brand = ftypBrand(head);
+    if (brand && NON_VIDEO_FTYP_BRANDS.has(brand))
+        return null;
+    if (asciiAt(head, 4, "ftyp") ||
+        asciiAt(head, 4, "moov") ||
+        asciiAt(head, 4, "mdat") ||
+        asciiAt(head, 4, "wide") ||
+        asciiAt(head, 4, "free") ||
+        asciiAt(head, 4, "skip")) {
+        return "mp4";
+    }
+    if (head.length >= 4 && head[0] === 0x1a && head[1] === 0x45 && head[2] === 0xdf && head[3] === 0xa3) {
+        return "webm";
+    }
+    return null;
+}
+function clientDecision(kind, ext, contentType) {
+    return { transport: "client", kind, ext, contentType };
+}
+/**
+ * Decide proxy vs direct-to-Blob vs reject for a local file.
+ * `headBytes` (optional) enables video detection when the extension is missing/wrong.
+ */
+export function selectMediaTransport(input) {
+    const { filename, sizeBytes } = input;
+    if (!Number.isFinite(sizeBytes) || sizeBytes <= 0) {
+        return { transport: "reject", message: "That file is empty — nothing to upload." };
+    }
+    let ext = extOf(filename);
+    const hasKnownNonVideoExt = RASTER_EXT.has(ext) || PDF_EXT.has(ext) || SVG_EXT.has(ext) || TEXT_EXT.has(ext);
+    // Only sniff for video when the extension isn't already a known non-video kind
+    // (AVIF is ISOBMFF/`ftyp` — sniffing before the raster branch would mis-route it).
+    const sniffedVideo = !hasKnownNonVideoExt && input.headBytes ? sniffVideoExt(input.headBytes) : null;
+    const isVideo = VIDEO_UPLOAD_EXT.has(ext) || sniffedVideo !== null;
+    if (isVideo && !VIDEO_UPLOAD_EXT.has(ext) && sniffedVideo) {
+        ext = sniffedVideo;
+    }
+    if (isVideo) {
+        if (sizeBytes > MAX_VIDEO_UPLOAD_BYTES) {
+            return {
+                transport: "reject",
+                message: `This video is ${formatBytes(sizeBytes)}, over the ${MAX_VIDEO_UPLOAD_BYTES / (1024 * 1024)} MB video limit. Please compress it (a web-ready MP4 around 1080p) and try again.`,
+            };
+        }
+        const useExt = VIDEO_UPLOAD_EXT.has(ext) ? ext : sniffedVideo ?? "mp4";
+        const contentType = useExt === "webm"
+            ? "video/webm"
+            : useExt === "mov"
+                ? "video/quicktime"
+                : useExt === "m4v"
+                    ? "video/x-m4v"
+                    : "video/mp4";
+        return clientDecision("video", useExt, contentType);
+    }
+    if (SVG_EXT.has(ext)) {
+        if (sizeBytes > MAX_PROXY_UPLOAD_BYTES) {
+            return {
+                transport: "reject",
+                message: `This SVG is ${formatBytes(sizeBytes)} — SVGs must be under ${MAX_PROXY_UPLOAD_BYTES / (1024 * 1024)} MB.`,
+            };
+        }
+        return { transport: "proxy", kind: "image" };
+    }
+    if (RASTER_EXT.has(ext)) {
+        if (sizeBytes > MAX_UPLOAD_BYTES) {
+            return {
+                transport: "reject",
+                message: `This image is ${formatBytes(sizeBytes)}, over the ${MAX_UPLOAD_BYTES / (1024 * 1024)} MB upload limit. Please use a smaller or lower-resolution image.`,
+            };
+        }
+        if (sizeBytes > MAX_PROXY_UPLOAD_BYTES) {
+            const contentType = ext === "jpg" || ext === "jpeg"
+                ? "image/jpeg"
+                : ext === "png"
+                    ? "image/png"
+                    : ext === "gif"
+                        ? "image/gif"
+                        : ext === "webp"
+                            ? "image/webp"
+                            : "image/avif";
+            return clientDecision("image", ext === "jpeg" ? "jpg" : ext, contentType);
+        }
+        return { transport: "proxy", kind: "image" };
+    }
+    if (PDF_EXT.has(ext)) {
+        if (sizeBytes > MAX_UPLOAD_BYTES) {
+            return {
+                transport: "reject",
+                message: `This PDF is ${formatBytes(sizeBytes)}, over the ${MAX_UPLOAD_BYTES / (1024 * 1024)} MB upload limit. Please attach a smaller file.`,
+            };
+        }
+        if (sizeBytes > MAX_PROXY_UPLOAD_BYTES) {
+            return clientDecision("document", "pdf", "application/pdf");
+        }
+        return { transport: "proxy", kind: "document" };
+    }
+    if (TEXT_EXT.has(ext)) {
+        if (sizeBytes > MAX_PROXY_UPLOAD_BYTES) {
+            return {
+                transport: "reject",
+                message: `This text/data file is ${formatBytes(sizeBytes)}. Large text/data Blob uploads aren't supported via the CLI yet — keep files under ${MAX_PROXY_UPLOAD_BYTES / (1024 * 1024)} MB or use the editor.`,
+            };
+        }
+        return { transport: "proxy", kind: "text" };
+    }
+    return {
+        transport: "reject",
+        message: "That file type isn't supported. Use an image (PNG, JPG, GIF, WebP, AVIF, SVG), a PDF, a video (MP4, WebM, MOV), or a text/code file.",
+    };
+}

package/dist/media/upload.d.ts

@@ -0,0 +1,16 @@
+export type UploadedMedia = {
+    kind: string;
+    url?: string;
+    key?: string;
+    sitePath?: string;
+    filename?: string;
+    sizeBytes?: number;
+    contentType?: string;
+    content?: string;
+    transport?: "proxy" | "client";
+};
+/** Upload a local file using the Phase E transport matrix. */
+export declare function uploadLocalMedia(args: {
+    slug: string;
+    filePath: string;
+}): Promise<UploadedMedia>;

package/dist/media/upload.js

@@ -0,0 +1,141 @@
+/**
+ * Shared local-file upload used by `frontpage media upload` and `prompt --attach`.
+ */
+import { randomUUID } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { basename } from "node:path";
+import { put } from "@vercel/blob/client";
+import { apiBase, CliHttpError, EXIT_AUTH, EXIT_UNEXPECTED, EXIT_USAGE, getBearerAuthHeader, httpErrorFromV1, v1PostMultipart, } from "../http/client.js";
+import { contentTypeForExt, sitePathFromKey } from "./limits.js";
+import { selectMediaTransport } from "./select-transport.js";
+async function requestClientToken(args) {
+    const auth = await getBearerAuthHeader();
+    const url = `${apiBase()}/api/v1/sites/${encodeURIComponent(args.slug)}/media/client`;
+    let res;
+    try {
+        res = await fetch(url, {
+            method: "POST",
+            headers: {
+                ...auth,
+                Accept: "application/json",
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify({
+                type: "blob.generate-client-token",
+                payload: {
+                    pathname: args.pathname,
+                    clientPayload: JSON.stringify({ declaredSize: args.declaredSize }),
+                    multipart: args.multipart,
+                },
+            }),
+        });
+    }
+    catch (err) {
+        throw new CliHttpError(`Network error: ${err instanceof Error ? err.message : String(err)}`, EXIT_UNEXPECTED, 0);
+    }
+    const text = await res.text();
+    let parsed = {};
+    try {
+        parsed = text ? JSON.parse(text) : {};
+    }
+    catch {
+        parsed = {};
+    }
+    if (!res.ok) {
+        const msg = typeof parsed.error === "string"
+            ? parsed.error
+            : typeof parsed.error === "object" && parsed.error?.message
+                ? parsed.error.message
+                : `Upload authorization failed (${res.status})`;
+        // Auth / rate-limit use v1 envelopes; policy denials use { error: string }.
+        if (typeof parsed.error === "object" && parsed.error) {
+            throw httpErrorFromV1(res.status, parsed, msg);
+        }
+        if (res.status === 401 || res.status === 403) {
+            throw new CliHttpError(msg, EXIT_AUTH, res.status);
+        }
+        if (res.status === 402 || res.status === 413 || res.status === 429 || res.status === 400) {
+            throw new CliHttpError(msg, EXIT_USAGE, res.status);
+        }
+        throw new CliHttpError(msg, EXIT_UNEXPECTED, res.status);
+    }
+    if (typeof parsed.clientToken !== "string" || !parsed.clientToken) {
+        throw new CliHttpError("Upload authorization failed (no client token).", EXIT_UNEXPECTED, res.status);
+    }
+    return parsed.clientToken;
+}
+async function uploadViaClient(args) {
+    const pathname = `uploads/${args.slug}/${randomUUID()}.${args.ext}`;
+    const multipart = args.bytes.length > 8 * 1024 * 1024;
+    const clientToken = await requestClientToken({
+        slug: args.slug,
+        pathname,
+        declaredSize: args.bytes.length,
+        multipart,
+    });
+    try {
+        const blob = await put(pathname, args.bytes, {
+            access: "public",
+            token: clientToken,
+            contentType: args.contentType,
+            multipart,
+        });
+        const key = blob.pathname.replace(/^\//, "");
+        return {
+            kind: args.kind,
+            url: blob.url,
+            key,
+            sitePath: sitePathFromKey(key),
+            filename: args.filename,
+            sizeBytes: args.bytes.length,
+            contentType: args.contentType || contentTypeForExt(args.ext),
+            transport: "client",
+        };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new CliHttpError(`Upload failed: ${msg}`, EXIT_UNEXPECTED, 500);
+    }
+}
+async function uploadViaProxy(args) {
+    const form = new FormData();
+    form.append("file", new Blob([Uint8Array.from(args.bytes)]), args.filename);
+    const data = await v1PostMultipart(`/api/v1/sites/${encodeURIComponent(args.slug)}/media`, form);
+    const key = data.key?.replace(/^\//, "");
+    return {
+        kind: data.kind,
+        url: data.url,
+        key,
+        sitePath: data.sitePath ?? (key ? sitePathFromKey(key) : undefined),
+        filename: data.filename ?? args.filename,
+        sizeBytes: data.sizeBytes ?? args.bytes.length,
+        contentType: data.contentType,
+        content: data.content,
+        transport: "proxy",
+    };
+}
+/** Upload a local file using the Phase E transport matrix. */
+export async function uploadLocalMedia(args) {
+    const bytes = await readFile(args.filePath);
+    const filename = basename(args.filePath);
+    const decision = selectMediaTransport({
+        filename,
+        sizeBytes: bytes.length,
+        headBytes: bytes.subarray(0, 4096),
+    });
+    if (decision.transport === "reject") {
+        // Local validation only — omit httpStatus (status 0) and never invent requestId (R10).
+        throw new CliHttpError(decision.message, EXIT_USAGE, 0, "bad_request");
+    }
+    if (decision.transport === "client") {
+        return uploadViaClient({
+            slug: args.slug,
+            bytes,
+            filename,
+            ext: decision.ext,
+            contentType: decision.contentType,
+            kind: decision.kind,
+        });
+    }
+    return uploadViaProxy({ slug: args.slug, bytes, filename });
+}

package/dist/registry.js

@@ -26,6 +26,13 @@ export const COMMANDS = [
             "frontpage help --json",
         ],
     },
+    {
+        name: "version",
+        summary: "Print frontpage-host package version",
+        usage: "frontpage version | frontpage --version | frontpage -V",
+        examples: ["frontpage --version", "frontpage version --json"],
+        flags: ["Also available as global --version / -V"],
+    },
     {
         name: "login",
         summary: "Save an API key to the OS keychain",
@@ -133,15 +140,21 @@ export const COMMANDS = [
     {
         name: "search",
         summary: "Search remote text files",
-        usage: "frontpage search <pattern> [path] [--regex] [--case-sensitive] [--whole-word] [--files-only] [--context-lines N] [--max-results N] [--site <slug>] [--json]",
+        usage: "frontpage search <pattern> [path|--path <path>] [--regex] [--case-sensitive] [--whole-word] [--files-only] [--context-lines N] [--max-results N] [--site <slug>] [--json]",
         topics: ["sync"],
+        examples: [
+            "frontpage search Subscribe src/pages",
+            "frontpage search Subscribe --path src/pages",
+        ],
         flags: [
+            "--path <prefix> (alias for positional path filter; flag wins if both present)",
             "--regex",
             "--case-sensitive",
             "--whole-word",
             "--files-only",
             "--context-lines <n>",
             "--max-results <n>",
+            "Unknown leftover flags fail closed (exit 2)",
         ],
     },
     {
@@ -184,9 +197,13 @@ export const COMMANDS = [
     {
         name: "open",
         summary: "Open the site subdomain in a browser",
-        usage: "frontpage open [--site <slug>] [--prod]",
+        usage: "frontpage open [/path|--path /path] [--site <slug>] [--prod]",
         topics: ["sync"],
-        flags: ["--prod is a no-op stub today — always opens https://<slug>.frontpage.host/"],
+        examples: ["frontpage open", "frontpage open /updates", "frontpage open --path /pricing"],
+        flags: [
+            "Optional site-relative path appended to https://<slug>.frontpage.host",
+            "--prod is a no-op stub today — still opens the *.frontpage.host subdomain",
+        ],
     },
     {
         name: "prompt",
@@ -204,7 +221,7 @@ export const COMMANDS = [
             "--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)",
+            "Local attach uses frontpage media upload (images/PDF ≤25 MB, video ≤50 MB, SVG/text ≤4 MB proxy)",
             "stdout is bare runId (or JSON with --json)",
         ],
         seeAlso: ["runs", "deploy", "media"],
@@ -316,9 +333,21 @@ export const COMMANDS = [
     },
     {
         name: "media",
-        summary: "List or upload site media assets",
-        usage: "frontpage media list|upload <file> [--site <slug>]",
+        summary: "List or upload site media (images/PDF ≤25 MB, video ≤50 MB)",
+        usage: "frontpage media list|upload <file> [--site <slug>] [--json]",
         topics: ["content"],
+        examples: [
+            "frontpage media list",
+            "frontpage media upload ./hero.webp",
+            "frontpage media upload ./clip.mp4",
+        ],
+        flags: [
+            "Auto-selects proxy (≤4 MB) vs direct-to-Blob for large rasters/PDFs and all video",
+            "Human success: sitePath first (markup-safe), then url: (blob URL for debugging)",
+            "Use sitePath (/__media/uploads/<slug>/…) in markup — never raw blob hosts in pages",
+            "SVG stays on the sanitizing proxy path (≤4 MB)",
+        ],
+        seeAlso: ["prompt", "help content", "help site-building"],
     },
     {
         name: "inbox",
@@ -330,8 +359,14 @@ export const COMMANDS = [
     {
         name: "seo",
         summary: "Get or set page SEO",
-        usage: "frontpage seo get|set --path / [--title …] [--description …] [--site <slug>]",
+        usage: "frontpage seo get [/path|--path /path] | seo set --path / [--title …] [--description …] [--site <slug>]",
         topics: ["content"],
+        examples: [
+            "frontpage seo get /",
+            "frontpage seo get --path /updates",
+            "frontpage seo set --path / --title \"Home\"",
+        ],
+        flags: ["get accepts positional path or --path (flag wins); unknown leftover flags fail closed"],
     },
     {
         name: "articles",
@@ -436,8 +471,8 @@ export const TOPICS = {
   frontpage push [--message …] [--wait]   # uploads allowlisted files; CAS + active-run guard
   frontpage ls [prefix]
   frontpage cat <path>
-  frontpage search <pattern> [path] [--regex] [--case-sensitive] [--whole-word] [--files-only]
-  frontpage open                 # opens https://<slug>.frontpage.host/ (--prod is a no-op stub)
+  frontpage search <pattern> [path|--path <path>] [--regex] [--case-sensitive] [--whole-word] [--files-only]
+  frontpage open [/path]         # opens https://<slug>.frontpage.host[/path] (--prod is a no-op stub)
 
   Local state: .frontpage/state.json { slug, baseCommitSha }
   Pull BEFORE EDITING when tip may have moved (UI agent / another checkout) — check tipDrift.
@@ -485,7 +520,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 in markup: /__media/uploads/<slug>/… from frontpage media (not raw blob URLs).
+  - 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.
 
   Full guide: https://frontpage.host/developers/site-building
   See also: frontpage help sync | content | AGENTS.md`,
@@ -508,15 +543,15 @@ export const TOPICS = {
   frontpage modules request-setup <key> --reason "…"
   frontpage extensions
 
-  --attach uploads local files via media (images/PDF/text) or accepts /__media/… / https URLs.
-  API errors include requestId in --json error envelopes (and stderr when not --json).
+  --attach uploads via media (images/PDF/video/text) or accepts /__media/… / https URLs.
+  API errors include requestId in --json envelopes when the server returned one; local validation errors omit requestId and httpStatus.
   Mid-task continuation is automatic — there is no runs continue.
   Do not file-sync while an agent run is active (see help sync for push --wait).
   Default after work: review https://<subdomain>.frontpage.host; do not publish.`,
     content: `Content
-  frontpage media list|upload <file>
+  frontpage media list|upload <file>   # images/PDF ≤25 MB, video ≤50 MB; human prints sitePath first
   frontpage inbox [leads|subscribers|orders|…] [--mark-read] [--csv]
-  frontpage seo get|set --path /
+  frontpage seo get [/path|--path /path] | seo set --path /
   frontpage articles list|content|create-section|create-article|set-draft|…
   frontpage fonts [list|search] [--slot …] [--query …]
   frontpage tokens set --group … --key … --value …
@@ -562,7 +597,8 @@ export const TOPICS = {
     { "ok": true, "command": "…", "data": {…} }
     { "ok": false, "command": "…", "error": { "message", "code?", "httpStatus?", "exitCode", "requestId?" }, "data"? }
   Failures with --json still use the process exit code; envelope is on stdout.
-  Prefer requestId from error envelopes when filing support issues.`,
+  requestId is present only when the API returned one — local CLI validation (e.g. media size/type reject) omits requestId and httpStatus.
+  Prefer requestId from API error envelopes when filing support issues.`,
 };
 export function findCommand(name) {
     return COMMANDS.find((c) => c.name === name);

package/dist/version.d.ts

@@ -0,0 +1,7 @@
+/** Read package identity from frontpage-host package.json (works from dist/). */
+export declare function packageIdentity(): {
+    name: string;
+    version: string;
+};
+/** Human one-liner: `frontpage-host 0.1.10`. */
+export declare function versionLine(): string;

package/dist/version.js

@@ -0,0 +1,15 @@
+import { createRequire } from "node:module";
+const require = createRequire(import.meta.url);
+/** Read package identity from frontpage-host package.json (works from dist/). */
+export function packageIdentity() {
+    const pkg = require("../package.json");
+    return {
+        name: pkg.name ?? "frontpage-host",
+        version: pkg.version ?? "0.0.0",
+    };
+}
+/** Human one-liner: `frontpage-host 0.1.10`. */
+export function versionLine() {
+    const { name, version } = packageIdentity();
+    return `${name} ${version}`;
+}