frontpage-host 0.1.9 → 0.1.11

package/AGENTS.md

@@ -29,15 +29,16 @@ Frontpage has two surfaces:
 **How changes become visible on staging**
 
 - `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 visible at `https://<subdomain>.frontpage.host`.
+- 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.
 - `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).
 - **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 `https://<subdomain>.frontpage.host`, and let **them** publish (or ask you to publish after they approve).
+- 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).
 
 ## Non-interactive auth
 
@@ -112,7 +113,7 @@ Sites are Astro 6 + Tailwind v4. More detail: `frontpage help site-building` or
 - 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). Use returned `sitePath` (`/__media/uploads/<slug>/…`) in markup — never raw blob hosts. Optional `?w=` on rasters only.
+- 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).
 - Analytics: bare `frontpage analytics` = dashboard; also `summary|query|funnel|timeseries|compare|sql` for structured reads (SQL is guard + RLS site-scoped).
 
 ## Agent prompt loop
@@ -180,7 +181,7 @@ Global machine envelope (`--json`):
 { "ok": false, "command": "push", "error": { "message": "…", "code": "conflict", "httpStatus": 409, "exitCode": 3, "requestId": "…" } }
 ```
 
-Failures with `--json` print the envelope on **stdout** (still use the process exit code). Include `requestId` when filing support issues.
+Failures with `--json` print the envelope on **stdout** (still use the process exit code). Include `requestId` when the API returned one (local validation errors omit `requestId` and `httpStatus`).
 
 ## Global flags
 
@@ -191,6 +192,7 @@ Failures with `--json` print the envelope on **stdout** (still use the process e
 | `--site <slug>` | Subdomain override (most site commands) |
 | `--yes` | Confirm destructive ops (`unpublish`, `revert`) when non-TTY |
 | `--help` / `-h` | Per-command help (alias of `frontpage help <cmd>`) |
+| `--version` / `-V` | Print `frontpage-host <semver>` (also `frontpage version`) |
 
 ## Destructive ops — defaults for agents
 

package/dist/argv.d.ts

@@ -0,0 +1,12 @@
+/** Remove `--name value` (or `--name=value`) from rest; return the value. */
+export declare function takeFlag(rest: string[], name: string): string | undefined;
+/** Remove a boolean `--name` flag from rest; return whether it was present. */
+export declare function hasFlag(rest: string[], name: string): boolean;
+/** True when a token looks like a flag (not a negative number). */
+export declare function looksLikeFlag(token: string): boolean;
+/**
+ * After a command has consumed its known options, fail if any flag-like
+ * tokens remain. Positionals (non-flags) are allowed leftovers unless the
+ * caller also checks them.
+ */
+export declare function assertNoUnknownFlags(rest: string[], command: string): void;

package/dist/argv.js

@@ -0,0 +1,48 @@
+/**
+ * Shared argv helpers for command parsers (CLI Agent UX R1–R3).
+ */
+import { CliHttpError, EXIT_USAGE } from "./http/client.js";
+/** Remove `--name value` (or `--name=value`) from rest; return the value. */
+export function takeFlag(rest, name) {
+    const eq = `${name}=`;
+    for (let i = 0; i < rest.length; i++) {
+        const a = rest[i];
+        if (a === name) {
+            const v = rest[i + 1];
+            rest.splice(i, 2);
+            return v;
+        }
+        if (a.startsWith(eq)) {
+            rest.splice(i, 1);
+            return a.slice(eq.length);
+        }
+    }
+    return undefined;
+}
+/** Remove a boolean `--name` flag from rest; return whether it was present. */
+export function hasFlag(rest, name) {
+    const i = rest.indexOf(name);
+    if (i === -1)
+        return false;
+    rest.splice(i, 1);
+    return true;
+}
+/** True when a token looks like a flag (not a negative number). */
+export function looksLikeFlag(token) {
+    if (token === "-" || token === "--")
+        return true;
+    if (/^-\d/.test(token))
+        return false; // allow negative numbers as values
+    return token.startsWith("-");
+}
+/**
+ * After a command has consumed its known options, fail if any flag-like
+ * tokens remain. Positionals (non-flags) are allowed leftovers unless the
+ * caller also checks them.
+ */
+export function assertNoUnknownFlags(rest, command) {
+    const unknown = rest.find(looksLikeFlag);
+    if (!unknown)
+        return;
+    throw new CliHttpError(`Unknown flag: ${unknown}. Run: frontpage help ${command}`, EXIT_USAGE, 0, "bad_request");
+}

package/dist/bin.js

@@ -34,6 +34,7 @@ import { runTokens } from "./commands/tokens.js";
 import { runHistory } from "./commands/history.js";
 import { runRevert } from "./commands/revert.js";
 import { runCompletion } from "./commands/completion.js";
+import { runVersion } from "./commands/version.js";
 import { EXIT_USAGE, EXIT_UNEXPECTED } from "./http/client.js";
 import { parseGlobalFlags } from "./flags.js";
 import { setRuntimeFlags, isJson } from "./runtime.js";
@@ -43,6 +44,10 @@ async function main() {
     const argv = parsed.args;
     const cmd = argv[0];
     const args = argv.slice(1);
+    // Global version before help/command dispatch (R6).
+    if (parsed.wantsVersion || cmd === "version") {
+        return runVersion();
+    }
     // Global or per-command help aliases (before site resolution).
     if (!cmd || cmd === "help") {
         return runHelp(cmd === "help" ? args : []);

package/dist/commands/analytics.d.ts

@@ -1 +1,8 @@
+/**
+ * Funnel --steps: JSON array (canonical) or comma-separated site paths (R9).
+ * Example shorthand: `--steps /, /problems, /updates`
+ */
+export declare function parseFunnelSteps(raw: string): Array<{
+    path: string;
+}>;
 export declare function runAnalytics(args: string[]): Promise<number>;

package/dist/commands/analytics.js

@@ -1,24 +1,48 @@
 import { resolveSlug } from "../site.js";
-import { EXIT_OK, EXIT_USAGE, exitCodeForError, v1Get, v1Post } from "../http/client.js";
+import { CliHttpError, EXIT_OK, EXIT_USAGE, exitCodeForError, v1Get, v1Post } from "../http/client.js";
+import { assertNoUnknownFlags, takeFlag } from "../argv.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`);
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        throw new CliHttpError(`Invalid JSON for ${label}: ${detail}`, EXIT_USAGE, 0, "bad_request");
     }
 }
+/**
+ * Funnel --steps: JSON array (canonical) or comma-separated site paths (R9).
+ * Example shorthand: `--steps /, /problems, /updates`
+ */
+export function parseFunnelSteps(raw) {
+    const trimmed = raw.trim();
+    if (!trimmed) {
+        throw new CliHttpError(`Usage: frontpage analytics funnel --steps '[{"path":"/"},{"path":"/pricing"}]' or --steps /, /pricing`, EXIT_USAGE, 0, "bad_request");
+    }
+    if (trimmed.startsWith("[")) {
+        const parsed = parseJsonFlag(trimmed, "--steps");
+        if (!Array.isArray(parsed)) {
+            throw new CliHttpError("Invalid JSON for --steps: expected an array of { path } objects", EXIT_USAGE, 0, "bad_request");
+        }
+        return parsed;
+    }
+    const paths = trimmed
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean);
+    if (paths.length === 0) {
+        throw new CliHttpError("Invalid --steps: provide a JSON array or comma-separated paths like /, /pricing", EXIT_USAGE, 0, "bad_request");
+    }
+    for (const path of paths) {
+        if (!path.startsWith("/") || path.startsWith("//")) {
+            throw new CliHttpError(`Invalid funnel step path "${path}" — each step must be a site-relative path starting with /`, EXIT_USAGE, 0, "bad_request");
+        }
+    }
+    return paths.map((path) => ({ path }));
+}
 function rangeFields(work) {
     const days = takeFlag(work, "--days");
     const from = takeFlag(work, "--from");
@@ -35,6 +59,12 @@ function rangeFields(work) {
 function printJson(data) {
     console.log(JSON.stringify(data, null, 2));
 }
+function finishWork(work) {
+    assertNoUnknownFlags(work, "analytics");
+    if (work.length > 0) {
+        throw new CliHttpError(`Unexpected argument: ${work[0]}. Run: frontpage help analytics`, EXIT_USAGE, 0, "bad_request");
+    }
+}
 export async function runAnalytics(args) {
     try {
         const { slug, rest } = await resolveSlug(args);
@@ -42,10 +72,11 @@ export async function runAnalytics(args) {
         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 || sub === "dashboard" || (!ops.has(sub) && sub.startsWith("--"))) {
             if (sub === "dashboard")
                 work.shift();
             const days = takeFlag(work, "--days") ?? "7";
+            finishWork(work);
             const data = await v1Get(`/api/v1/sites/${encodeURIComponent(slug)}/analytics?days=${encodeURIComponent(days)}`);
             if (isJson()) {
                 emitOk("analytics", data);
@@ -63,6 +94,7 @@ export async function runAnalytics(args) {
         if (sub === "summary") {
             const filters = parseJsonFlag(takeFlag(work, "--filters"), "--filters");
             const body = { op: "summary", ...rangeFields(work), ...(filters ? { filters } : {}) };
+            finishWork(work);
             const data = await v1Post(base, body);
             if (isJson())
                 emitOk("analytics", data);
@@ -87,6 +119,7 @@ export async function runAnalytics(args) {
                 ...(limit ? { limit: Number(limit) } : {}),
                 ...(filters ? { filters } : {}),
             };
+            finishWork(work);
             const data = await v1Post(base, body);
             if (isJson())
                 emitOk("analytics", data);
@@ -95,13 +128,21 @@ export async function runAnalytics(args) {
             return EXIT_OK;
         }
         if (sub === "funnel") {
-            const stepsRaw = takeFlag(work, "--steps");
+            let stepsRaw = takeFlag(work, "--steps");
             if (!stepsRaw) {
-                console.error(`Usage: frontpage analytics funnel --steps '[{"path":"/"},{"path":"/pricing"}]' [--days N]`);
+                console.error(`Usage: frontpage analytics funnel --steps '[{"path":"/"},{"path":"/pricing"}]' [--days N]\n` +
+                    `   or: frontpage analytics funnel --steps /, /pricing, /updates [--days N]`);
                 return EXIT_USAGE;
             }
-            const steps = parseJsonFlag(stepsRaw, "--steps");
+            // Shell splits `--steps /, /pricing` into multiple argv tokens; reassemble path list.
+            if (!stepsRaw.trim().startsWith("[")) {
+                while (work[0] && work[0].startsWith("/") && !work[0].startsWith("//")) {
+                    stepsRaw = `${stepsRaw},${work.shift()}`;
+                }
+            }
+            const steps = parseFunnelSteps(stepsRaw);
             const body = { op: "funnel", steps, ...rangeFields(work) };
+            finishWork(work);
             const data = await v1Post(base, body);
             if (isJson())
                 emitOk("analytics", data);
@@ -120,6 +161,7 @@ export async function runAnalytics(args) {
                 ...(interval ? { interval } : {}),
                 ...(filters ? { filters } : {}),
             };
+            finishWork(work);
             const data = await v1Post(base, body);
             if (isJson())
                 emitOk("analytics", data);
@@ -144,6 +186,7 @@ export async function runAnalytics(args) {
                 ...rangeFields(work),
                 ...(metric ? { metric } : {}),
             };
+            finishWork(work);
             const data = await v1Post(base, body);
             if (isJson())
                 emitOk("analytics", data);
@@ -152,7 +195,16 @@ export async function runAnalytics(args) {
             return EXIT_OK;
         }
         if (sub === "sql") {
-            const sql = takeFlag(work, "--sql") ?? work.join(" ").trim();
+            const sqlFlag = takeFlag(work, "--sql");
+            const sql = sqlFlag ?? work.join(" ").trim();
+            if (sqlFlag) {
+                // Consumed via flag; reject leftover flags/args.
+                finishWork(work);
+            }
+            else if (sql) {
+                // Positional SQL consumed all remaining tokens.
+                work.length = 0;
+            }
             if (!sql) {
                 console.error('Usage: frontpage analytics sql --sql "SELECT path, count(*) FROM analytics_events GROUP BY 1"');
                 return EXIT_USAGE;

package/dist/commands/help.js

@@ -70,7 +70,7 @@ export function runHelp(args) {
             console.log(`  ${c.name.padEnd(12)} ${c.summary}`);
         }
         console.log(`\nTopics: frontpage help ${TOPIC_NAMES.join(" | frontpage help ")}`);
-        console.log("Global: --json  --quiet  --yes  --site <slug>  --help");
+        console.log("Global: --json  --quiet  --yes  --site <slug>  --help  --version");
         console.log("Agents: see AGENTS.md in the npm package");
         return 0;
     }

package/dist/commands/media.d.ts

@@ -1 +1,4 @@
+import { type UploadedMedia } from "../media/upload.js";
+/** Sanitize media --json payload: omit full text body (R5); keep content for prompt --attach path. */
+export declare function mediaJsonData(slug: string, data: UploadedMedia): Record<string, unknown>;
 export declare function runMedia(args: string[]): Promise<number>;

package/dist/commands/media.js

@@ -1,13 +1,47 @@
 import { resolveSlug } from "../site.js";
-import { EXIT_OK, EXIT_USAGE, exitCodeForError } from "../http/client.js";
+import { EXIT_OK, EXIT_USAGE, exitCodeForError, v1Get } from "../http/client.js";
+import { assertNoUnknownFlags } from "../argv.js";
 import { emitErr, emitOk, isJson } from "../runtime.js";
 import { uploadLocalMedia } from "../media/upload.js";
-import { v1Get } from "../http/client.js";
+const TEXT_NOT_LIBRARY = "not added to the media library and cannot be linked via /__media. " +
+    "For form submission exports use inbox … --csv; large data files via the editor.";
+/** Sanitize media --json payload: omit full text body (R5); keep content for prompt --attach path. */
+export function mediaJsonData(slug, data) {
+    if (data.kind === "text") {
+        const content = data.content;
+        const contentBytes = data.sizeBytes ??
+            (typeof content === "string" ? Buffer.byteLength(content, "utf8") : 0);
+        const contentPreview = typeof content === "string"
+            ? content.length > 256
+                ? content.slice(0, 256)
+                : content
+            : undefined;
+        return {
+            slug,
+            kind: data.kind,
+            filename: data.filename,
+            sizeBytes: data.sizeBytes,
+            contentType: data.contentType,
+            transport: data.transport,
+            contentBytes,
+            contentPreview,
+            contentOmitted: true,
+            libraryAsset: false,
+        };
+    }
+    return { slug, ...data };
+}
 export async function runMedia(args) {
     try {
         const { slug, rest } = await resolveSlug(args);
         const sub = rest[0] ?? "list";
         if (sub === "list" || sub === "ls") {
+            const work = rest.slice(1);
+            assertNoUnknownFlags(work, "media");
+            if (work.length > 0) {
+                console.error(`Unexpected argument: ${work[0]}\nUsage: frontpage media list [--site <slug>] [--json]`);
+                return EXIT_USAGE;
+            }
             const data = await v1Get(`/api/v1/sites/${encodeURIComponent(slug)}/media`);
             if (isJson()) {
                 emitOk("media", { slug, ...data });
@@ -20,26 +54,33 @@ export async function runMedia(args) {
             return EXIT_OK;
         }
         if (sub === "upload") {
-            const filePath = rest[1];
+            const work = rest.slice(1);
+            const filePath = work.shift();
             if (!filePath) {
                 console.error("Usage: frontpage media upload <file> [--site <slug>] [--json]");
                 return EXIT_USAGE;
             }
+            assertNoUnknownFlags(work, "media");
+            if (work.length > 0) {
+                console.error(`Unexpected argument: ${work[0]}\nUsage: frontpage media upload <file> [--site <slug>] [--json]`);
+                return EXIT_USAGE;
+            }
             const data = await uploadLocalMedia({ slug, filePath });
             if (isJson()) {
-                emitOk("media", { slug, ...data });
+                emitOk("media", mediaJsonData(slug, data));
                 return EXIT_OK;
             }
             if (data.kind === "text") {
-                console.log(`Inline text (${data.filename}): ${data.sizeBytes ?? 0} bytes — not stored.`);
+                console.log(`Inline text (${data.filename}): ${data.sizeBytes ?? 0} bytes — ${TEXT_NOT_LIBRARY}`);
                 return EXIT_OK;
             }
-            if (data.url)
-                console.log(data.url);
+            // Human mode: sitePath first so first-line copy/paste is markup-safe (R4).
             if (data.sitePath)
                 console.log(`sitePath: ${data.sitePath}`);
             else if (data.key)
                 console.log(`sitePath: /__media/${data.key}`);
+            if (data.url)
+                console.log(`url: ${data.url}`);
             return EXIT_OK;
         }
         console.error("Usage: frontpage media list|upload <file> [--site <slug>] [--json]");

package/dist/commands/modules.js

@@ -1,13 +1,6 @@
 import { resolveSlug } from "../site.js";
 import { EXIT_OK, EXIT_USAGE, exitCodeForError, v1Get, v1Post } from "../http/client.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;
-}
+import { takeFlag } from "../argv.js";
 export async function runModules(args) {
     try {
         const { slug, rest } = await resolveSlug(args);
@@ -22,7 +15,12 @@ export async function runModules(args) {
         if (sub === "docs" || sub === "doc") {
             const key = rest[1];
             if (!key) {
+                const data = await v1Get(`/api/v1/sites/${encodeURIComponent(slug)}/modules`);
                 console.error("Usage: frontpage modules docs <key> [--instance <id>] [--site <slug>]");
+                console.error("Known modules (run: frontpage modules docs <key>):");
+                for (const m of data.modules) {
+                    console.error(`  ${m.key.padEnd(16)}  ${m.name}`);
+                }
                 return EXIT_USAGE;
             }
             const work = rest.slice(2);

package/dist/commands/open.d.ts

@@ -1 +1,3 @@
+/** Site-relative path for open; rejects schemes and traversal. */
+export declare function normalizeOpenPath(raw: string): string;
 export declare function runOpen(args: string[]): Promise<number>;

package/dist/commands/open.js

@@ -1,22 +1,56 @@
 import { spawn } from "node:child_process";
 import { resolveSlug } from "../site.js";
-import { EXIT_OK, EXIT_USAGE } from "../http/client.js";
+import { CliHttpError, EXIT_OK, EXIT_USAGE } from "../http/client.js";
+import { assertNoUnknownFlags, hasFlag, takeFlag } from "../argv.js";
 import { emitErr, emitOk, emitUsage, isJson, isQuiet } from "../runtime.js";
+/** Site-relative path for open; rejects schemes and traversal. */
+export function normalizeOpenPath(raw) {
+    const trimmed = raw.trim();
+    if (!trimmed.startsWith("/") || trimmed.startsWith("//")) {
+        throw new CliHttpError("Open path must be site-relative and start with / (e.g. /updates).", EXIT_USAGE, 0, "bad_request");
+    }
+    if (/^https?:/i.test(trimmed) || trimmed.includes("..") || trimmed.includes("\\")) {
+        throw new CliHttpError("Open path must be a site-relative path (no http(s) URLs or ..).", EXIT_USAGE, 0, "bad_request");
+    }
+    const collapsed = trimmed.replace(/\/+/g, "/");
+    if (collapsed.length > 1 && collapsed.endsWith("/"))
+        return collapsed.slice(0, -1);
+    return collapsed;
+}
 export async function runOpen(args) {
     try {
         const { slug, rest } = await resolveSlug(args);
-        const prod = rest.includes("--prod") || args.includes("--prod");
-        const url = `https://${slug}.frontpage.host/`;
+        const work = [...rest];
+        const prod = hasFlag(work, "--prod");
+        const pathFlag = takeFlag(work, "--path");
+        let path = "/";
+        if (pathFlag !== undefined) {
+            path = normalizeOpenPath(pathFlag);
+        }
+        else {
+            const positional = work.find((a) => a.startsWith("/") && !a.startsWith("//"));
+            if (positional) {
+                work.splice(work.indexOf(positional), 1);
+                path = normalizeOpenPath(positional);
+            }
+        }
+        assertNoUnknownFlags(work, "open");
+        if (work.length > 0) {
+            return emitUsage("open", "Usage: frontpage open [/path|--path /path] [--site <slug>] [--prod]", EXIT_USAGE);
+        }
+        const url = path === "/"
+            ? `https://${slug}.frontpage.host/`
+            : `https://${slug}.frontpage.host${path}`;
         // --prod is reserved for a future production custom-domain lookup; both
         // modes currently open the site subdomain on *.frontpage.host.
         if (prod && !isJson() && !isQuiet()) {
-            console.error("Note: --prod is a no-op stub; opening https://<slug>.frontpage.host/");
+            console.error("Note: --prod is a no-op stub; opening https://<slug>.frontpage.host/…");
         }
         const opener = process.platform === "darwin" ? "open" : process.platform === "win32" ? "cmd" : "xdg-open";
         const openerArgs = process.platform === "win32" ? ["/c", "start", "", url] : [url];
         spawn(opener, openerArgs, { detached: true, stdio: "ignore" }).unref();
         if (isJson()) {
-            emitOk("open", { slug, url, prodRequested: prod, prodNoOp: true });
+            emitOk("open", { slug, url, path, prodRequested: prod, prodNoOp: true });
         }
         else {
             console.log(url);
@@ -25,7 +59,7 @@ export async function runOpen(args) {
     }
     catch (err) {
         if (err instanceof Error && err.message.includes("Usage")) {
-            return emitUsage("open", "Usage: frontpage open [--site <slug>] [--prod]", EXIT_USAGE);
+            return emitUsage("open", "Usage: frontpage open [/path|--path /path] [--site <slug>] [--prod]", EXIT_USAGE);
         }
         return emitErr("open", err);
     }

package/dist/commands/search.js

@@ -1,21 +1,8 @@
 import { resolveSlug } from "../site.js";
 import { EXIT_OK, EXIT_USAGE, exitCodeForError, v1Get } from "../http/client.js";
+import { assertNoUnknownFlags, hasFlag, takeFlag } from "../argv.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 hasFlag(rest, name) {
-    const i = rest.indexOf(name);
-    if (i === -1)
-        return false;
-    rest.splice(i, 1);
-    return true;
-}
+const SEARCH_USAGE = "Usage: frontpage search <pattern> [path|--path <path>] [--regex] [--case-sensitive] [--whole-word] [--files-only] [--context-lines N] [--max-results N] [--site <slug>]";
 export async function runSearch(args) {
     try {
         const { slug, rest } = await resolveSlug(args);
@@ -26,12 +13,21 @@ export async function runSearch(args) {
         const filesOnly = hasFlag(work, "--files-only");
         const contextLines = takeFlag(work, "--context-lines");
         const maxResults = takeFlag(work, "--max-results");
-        const pattern = work[0];
+        const pathFlag = takeFlag(work, "--path");
+        const pattern = work.shift();
         if (!pattern) {
-            console.error("Usage: frontpage search <pattern> [path] [--regex] [--case-sensitive] [--whole-word] [--files-only] [--context-lines N] [--max-results N] [--site <slug>]");
+            console.error(SEARCH_USAGE);
+            return EXIT_USAGE;
+        }
+        let pathFilter = pathFlag;
+        if (pathFilter === undefined && work[0] && !work[0].startsWith("-")) {
+            pathFilter = work.shift();
+        }
+        assertNoUnknownFlags(work, "search");
+        if (work.length > 0) {
+            console.error(`Unexpected argument: ${work[0]}\n${SEARCH_USAGE}`);
             return EXIT_USAGE;
         }
-        const pathFilter = work[1] && !work[1].startsWith("-") ? work[1] : undefined;
         const q = new URLSearchParams({ pattern });
         if (pathFilter)
             q.set("path", pathFilter);

package/dist/commands/seo.js

@@ -1,27 +1,39 @@
 import { resolveSlug } from "../site.js";
-import { EXIT_OK, EXIT_USAGE, exitCodeForError, v1Get, v1Post } from "../http/client.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;
+import { CliHttpError, EXIT_OK, EXIT_USAGE, exitCodeForError, v1Get, v1Post } from "../http/client.js";
+import { assertNoUnknownFlags, takeFlag } from "../argv.js";
+import { emitErr, isJson } from "../runtime.js";
+function resolveSeoPath(work) {
+    const fromFlag = takeFlag(work, "--path");
+    if (fromFlag !== undefined) {
+        if (!fromFlag.startsWith("/") || fromFlag.startsWith("//")) {
+            throw new CliHttpError("SEO path must start with / (e.g. / or /about).", EXIT_USAGE, 0, "bad_request");
+        }
+        return fromFlag;
+    }
+    const positional = work.find((a) => a.startsWith("/") && !a.startsWith("//"));
+    if (positional) {
+        const i = work.indexOf(positional);
+        work.splice(i, 1);
+        return positional;
+    }
+    return "/";
 }
 export async function runSeo(args) {
     try {
         const { slug, rest } = await resolveSlug(args);
         const sub = rest[0];
-        if (!sub || sub === "get") {
-            const pathArgs = rest[0] === "get" ? rest.slice(1) : rest;
-            const path = pathArgs[0] ?? "/";
+        // `seo`, `seo get`, `seo get /path`, `seo get --path /path`, `seo --path /path`
+        if (!sub || sub === "get" || sub === "--path" || (sub.startsWith("/") && !sub.startsWith("//"))) {
+            const work = sub === "get" ? rest.slice(1) : [...rest];
+            const path = resolveSeoPath(work);
+            assertNoUnknownFlags(work, "seo");
             const data = await v1Get(`/api/v1/sites/${encodeURIComponent(slug)}/seo?path=${encodeURIComponent(path)}`);
             console.log(JSON.stringify(data, null, 2));
             return EXIT_OK;
         }
         if (sub === "set") {
             const work = rest.slice(1);
-            const path = takeFlag(work, "--path") ?? work.find((a) => a.startsWith("/")) ?? "/";
+            const path = resolveSeoPath(work);
             const body = { path };
             for (const field of [
                 "title",
@@ -39,6 +51,7 @@ export async function runSeo(args) {
             if (noindex !== undefined) {
                 body.noindex = noindex === "true" || noindex === "1";
             }
+            assertNoUnknownFlags(work, "seo");
             if (Object.keys(body).length <= 1) {
                 console.error("Usage: frontpage seo set --path / [--title …] [--description …] [--ogImage …] [--noindex true|false]");
                 return EXIT_USAGE;
@@ -47,10 +60,12 @@ export async function runSeo(args) {
             console.log(JSON.stringify(data, null, 2));
             return EXIT_OK;
         }
-        console.error("Usage: frontpage seo get|set … [--site <slug>]");
+        console.error("Usage: frontpage seo get [/path|--path /path] | seo set --path / [--title …] [--site <slug>]");
         return EXIT_USAGE;
     }
     catch (err) {
+        if (isJson())
+            return emitErr("seo", err);
         console.error(err instanceof Error ? err.message : String(err));
         return exitCodeForError(err);
     }

package/dist/commands/version.d.ts

@@ -0,0 +1 @@
+export declare function runVersion(): number;

package/dist/commands/version.js

@@ -0,0 +1,13 @@
+import { EXIT_OK } from "../http/client.js";
+import { emitOk, isJson } from "../runtime.js";
+import { packageIdentity, versionLine } from "../version.js";
+export function runVersion() {
+    const identity = packageIdentity();
+    if (isJson()) {
+        emitOk("version", identity);
+    }
+    else {
+        console.log(versionLine());
+    }
+    return EXIT_OK;
+}

package/dist/flags.d.ts

@@ -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 type GlobalFlags = {
     json: boolean;
@@ -8,6 +8,8 @@ export type GlobalFlags = {
     yes: boolean;
     /** True when argv asked for help (--help / -h), not the `help` command itself. */
     wantsHelp: boolean;
+    /** True when argv asked for version (--version / -V). */
+    wantsVersion: boolean;
     args: string[];
 };
 export declare function parseGlobalFlags(argv: string[]): GlobalFlags;

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/media/upload.js

@@ -124,7 +124,8 @@ export async function uploadLocalMedia(args) {
         headBytes: bytes.subarray(0, 4096),
     });
     if (decision.transport === "reject") {
-        throw new CliHttpError(decision.message, EXIT_USAGE, 400, "bad_request");
+        // 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({

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",
@@ -277,12 +294,16 @@ export const COMMANDS = [
             "frontpage analytics summary --days 30",
             "frontpage analytics query --dimension path --measure count --limit 10",
             `frontpage analytics funnel --steps '[{"path":"/"},{"path":"/pricing"}]'`,
+            "frontpage analytics funnel --steps /, /pricing, /updates",
             "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)",
+            "funnel --steps accepts JSON array or comma-separated paths (/, /pricing)",
+            "Invalid JSON for --steps / --a / --b prints an explicit parse error (not bare Usage)",
+            "Unknown leftover flags fail closed (exit 2)",
             "Ops use POST …/analytics with allowlisted dimensions/measures; SQL is guard-validated + RLS",
         ],
     },
@@ -299,6 +320,7 @@ export const COMMANDS = [
         topics: ["agent", "content"],
         examples: [
             "frontpage modules docs forms",
+            "frontpage modules docs signups",
             "frontpage modules list",
             'frontpage modules request-setup payments --reason "You asked for a $50 deposit button — Stripe setup makes it live"',
         ],
@@ -326,8 +348,11 @@ export const COMMANDS = [
         ],
         flags: [
             "Auto-selects proxy (≤4 MB) vs direct-to-Blob for large rasters/PDFs and all video",
-            "Prints sitePath (/__media/uploads/<slug>/…) for markup — never raw blob hosts in pages",
+            "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",
+            "Text/CSV upload is inline only — not a media-library asset (no /__media link); --json omits full content",
             "SVG stays on the sanitizing proxy path (≤4 MB)",
+            "Unknown leftover flags fail closed (exit 2)",
         ],
         seeAlso: ["prompt", "help content", "help site-building"],
     },
@@ -341,8 +366,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",
@@ -422,7 +453,9 @@ export const TOPICS = {
   5. frontpage pull
   6. Edit files under src/, public/, or content/
   7. frontpage push --message "…"
-  8. Review https://<subdomain>.frontpage.host  (staging)
+  8. 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
 
   Staging is the subdomain. There is no separate staging-deploy step for agents.
@@ -447,8 +480,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.
@@ -520,18 +553,20 @@ export const TOPICS = {
   frontpage extensions
 
   --attach uploads via media (images/PDF/video/text) or accepts /__media/… / https URLs.
-  API errors include requestId in --json error envelopes (and stderr when not --json).
+  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.`,
+  Default after work: review staging on https://<subdomain>.frontpage.host when public;
+  with a custom domain, that subdomain may require an owner browser session (login wall ≠ failed deploy).
+  Do not publish unless asked.`,
     content: `Content
-  frontpage media list|upload <file>   # images/PDF ≤25 MB, video ≤50 MB; sitePath for markup
+  frontpage media list|upload <file>   # images/PDF/video; text/CSV = inline not library; sitePath first when stored
   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 …
-  frontpage modules list|docs|request-setup|enable|disable|archive|config <key>
+  frontpage modules list|docs|request-setup|enable|disable|archive|config <key>  # mailing list key: signups
   frontpage extensions list|docs|enable|disable|config <key>
   frontpage settings get|set
   frontpage edit --path / --old "…" --new "…"
@@ -573,7 +608,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}`;
+}

package/llms.txt

@@ -10,12 +10,16 @@
 - 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)
-- Media: frontpage media upload <file> (images/PDF ≤25 MB, video ≤50 MB, SVG/text ≤4 MB); use sitePath /__media/uploads/<slug>/… in markup
+- 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)
-- Errors: --json error envelopes include requestId; runs wait failed/canceled → ok:false + run.error (exit 2); deploy wait fail-closed; push --wait
+- Version: frontpage --version | -V | version
+- 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
 - 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
+- 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
 - 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)

package/package.json

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