frontpage-host 0.1.3 → 0.1.5

package/AGENTS.md

@@ -92,6 +92,27 @@ Rules:
 7. Prefer reviewing the subdomain after push; only use `deploy wait` if you need to block until a build finishes.
 8. The **UI / canvas agent does not use this CLI** — it edits the live tip in-process. Only CLI checkouts need `pull`.
 
+## Site contract (Astro)
+
+Sites are Astro 6 + Tailwind v4. More detail: `frontpage help site-building` or https://frontpage.host/developers/site-building
+
+1. **Every page** wraps content in `<BaseLayout title="…" description="…">` (import from `src/layouts/BaseLayout.astro`).
+2. **`src/config/site.ts`** — keep `pages` (path registry) and `nav` in sync when adding/renaming/deleting page files. Tab title comes from BaseLayout, not the `pages` map label.
+3. **One file per URL** for similar page sets (services, guides, …). Do not default to `getStaticPaths()` over `src/data/*.ts`. Blog/news → `frontpage articles`, not a hand-rolled catalog.
+4. **No backends / databases / fake forms or checkout.** Real forms use `<form data-fp-form="slug">` + `frontpage modules`. Refuse or use modules for payments.
+5. **Tokens** in `src/config/tokens.ts` — keep required color/font/spacing/radii keys; style via CSS variables / token Tailwind. Setting a font token is not enough — apply `font-sans` / `font-serif` / `font-display`. Browse fonts with `frontpage fonts`; set one token with `frontpage tokens set --group … --key … --value …` (CAS like push). Module how-tos: `frontpage modules docs <key>` / `frontpage extensions docs <key>`.
+6. **Shared chrome** — prefer `src/components/Header.astro` + `Footer.astro` (or `chrome: { managed: true }` in `site.ts`).
+7. **404** — customize `src/pages/404.astro` if needed; keep `frontpage:404` meta; never register `/404` in `nav`/`pages`.
+8. **Platform-owned paths** stay off-limits (BaseLayout overlay, module/extension shells, `package.json`, …). Customer layouts like `DocsLayout` / `GuideLayout` are OK.
+
+## Modules & articles
+
+- Forms: `data-fp-form` markup in pages + `frontpage modules` for enable/config. No submit JS / honeypot / `action`.
+- 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).
+
 ## Agent prompt loop
 
 ```bash
@@ -194,6 +215,7 @@ Safe default after finishing work: summarize what changed and give the staging U
 frontpage help
 frontpage help --json
 frontpage help sync
+frontpage help site-building
 frontpage help agent
 frontpage doctor --json
 ```

package/dist/bin.js

@@ -29,6 +29,8 @@ import { runSeo } from "./commands/seo.js";
 import { runArticles } from "./commands/articles.js";
 import { runSettings } from "./commands/settings.js";
 import { runEdit } from "./commands/edit.js";
+import { runFonts } from "./commands/fonts.js";
+import { runTokens } from "./commands/tokens.js";
 import { runHistory } from "./commands/history.js";
 import { runRevert } from "./commands/revert.js";
 import { runCompletion } from "./commands/completion.js";
@@ -110,6 +112,10 @@ async function main() {
             return runSettings(args);
         case "edit":
             return runEdit(args);
+        case "fonts":
+            return runFonts(args);
+        case "tokens":
+            return runTokens(args);
         case "history":
             return runHistory(args);
         case "revert":

package/dist/commands/extensions.js

@@ -23,6 +23,20 @@ export async function runExtensions(args) {
             }
             return EXIT_OK;
         }
+        if (sub === "docs" || sub === "doc") {
+            const key = rest[1];
+            if (!key) {
+                console.error("Usage: frontpage extensions docs <key> [--site <slug>]");
+                return EXIT_USAGE;
+            }
+            const data = await v1Get(`/api/v1/sites/${encodeURIComponent(slug)}/extensions/${encodeURIComponent(key)}`);
+            console.log(`# ${data.key} (${data.name})  [${data.state}]`);
+            if (data.note)
+                console.log(data.note);
+            console.log("");
+            console.log(data.docs);
+            return EXIT_OK;
+        }
         if (sub === "enable" || sub === "disable" || sub === "config") {
             const key = rest[1];
             if (!key) {
@@ -50,7 +64,7 @@ export async function runExtensions(args) {
             console.log(JSON.stringify(data, null, 2));
             return EXIT_OK;
         }
-        console.error("Usage: frontpage extensions [list|enable|disable|config] …");
+        console.error("Usage: frontpage extensions [list|docs|enable|disable|config] …");
         return EXIT_USAGE;
     }
     catch (err) {

package/dist/commands/fonts.d.ts

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

package/dist/commands/fonts.js

@@ -0,0 +1,71 @@
+import { EXIT_OK, EXIT_USAGE, exitCodeForError, v1Get } 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 hasFlag(rest, name) {
+    const i = rest.indexOf(name);
+    if (i === -1)
+        return false;
+    rest.splice(i, 1);
+    return true;
+}
+export async function runFonts(args) {
+    try {
+        const work = [...args];
+        let sub = work[0];
+        if (sub === "list" || sub === "search" || sub === "ls") {
+            work.shift();
+        }
+        else {
+            sub = "list";
+        }
+        const slot = takeFlag(work, "--slot");
+        const query = takeFlag(work, "--query") ??
+            (sub === "search" ? work.shift() : undefined) ??
+            (work[0] && !work[0].startsWith("-") ? work.shift() : undefined);
+        const variableOnly = hasFlag(work, "--variable-only");
+        const limit = takeFlag(work, "--limit");
+        const offset = takeFlag(work, "--offset");
+        if (sub === "search" && !query) {
+            console.error("Usage: frontpage fonts search <query> [--slot …] [--variable-only] [--limit N]");
+            return EXIT_USAGE;
+        }
+        const q = new URLSearchParams();
+        if (slot)
+            q.set("slot", slot);
+        if (query)
+            q.set("query", query);
+        if (variableOnly)
+            q.set("variableOnly", "true");
+        if (limit)
+            q.set("limit", limit);
+        if (offset)
+            q.set("offset", offset);
+        const path = `/api/v1/fonts${q.toString() ? `?${q.toString()}` : ""}`;
+        const data = await v1Get(path);
+        if (isJson()) {
+            emitOk("fonts", data);
+            return EXIT_OK;
+        }
+        for (const f of data.fonts ?? []) {
+            const varMark = f.variable ? "var" : "   ";
+            console.log(`${f.slot.padEnd(8)} ${varMark}  ${f.family.padEnd(28)}  ${f.value}`);
+        }
+        console.log(`(${data.returned}/${data.total} fonts${data.hasMore ? "; more available" : ""})`);
+        if (data.hint)
+            console.error(data.hint);
+        return EXIT_OK;
+    }
+    catch (err) {
+        if (isJson())
+            return emitErr("fonts", err);
+        console.error(err instanceof Error ? err.message : String(err));
+        return exitCodeForError(err);
+    }
+}

package/dist/commands/modules.js

@@ -19,6 +19,23 @@ export async function runModules(args) {
             }
             return EXIT_OK;
         }
+        if (sub === "docs" || sub === "doc") {
+            const key = rest[1];
+            if (!key) {
+                console.error("Usage: frontpage modules docs <key> [--instance <id>] [--site <slug>]");
+                return EXIT_USAGE;
+            }
+            const work = rest.slice(2);
+            const instanceId = takeFlag(work, "--instance");
+            const q = instanceId ? `?instanceId=${encodeURIComponent(instanceId)}` : "";
+            const data = await v1Get(`/api/v1/sites/${encodeURIComponent(slug)}/modules/${encodeURIComponent(key)}${q}`);
+            console.log(`# ${data.key}  (${data.status})`);
+            if (data.note)
+                console.log(data.note);
+            console.log("");
+            console.log(data.docs);
+            return EXIT_OK;
+        }
         if (sub === "enable" || sub === "disable" || sub === "archive" || sub === "config") {
             const key = rest[1];
             if (!key) {
@@ -46,7 +63,7 @@ export async function runModules(args) {
             console.log(JSON.stringify(data, null, 2));
             return EXIT_OK;
         }
-        console.error("Usage: frontpage modules [list|enable|disable|archive|config] …");
+        console.error("Usage: frontpage modules [list|docs|enable|disable|archive|config] …");
         return EXIT_USAGE;
     }
     catch (err) {

package/dist/commands/search.js

@@ -1,29 +1,79 @@
 import { resolveSlug } from "../site.js";
 import { EXIT_OK, EXIT_USAGE, exitCodeForError, v1Get } 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 hasFlag(rest, name) {
+    const i = rest.indexOf(name);
+    if (i === -1)
+        return false;
+    rest.splice(i, 1);
+    return true;
+}
 export async function runSearch(args) {
     try {
         const { slug, rest } = await resolveSlug(args);
-        const pattern = rest[0];
+        const work = [...rest];
+        const regex = hasFlag(work, "--regex");
+        const caseSensitive = hasFlag(work, "--case-sensitive");
+        const wholeWord = hasFlag(work, "--whole-word");
+        const filesOnly = hasFlag(work, "--files-only");
+        const contextLines = takeFlag(work, "--context-lines");
+        const maxResults = takeFlag(work, "--max-results");
+        const pattern = work[0];
         if (!pattern) {
-            console.error("Usage: frontpage search <pattern> [--site <slug>]");
+            console.error("Usage: frontpage search <pattern> [path] [--regex] [--case-sensitive] [--whole-word] [--files-only] [--context-lines N] [--max-results N] [--site <slug>]");
             return EXIT_USAGE;
         }
+        const pathFilter = work[1] && !work[1].startsWith("-") ? work[1] : undefined;
         const q = new URLSearchParams({ pattern });
-        const pathFilter = rest[1];
         if (pathFilter)
             q.set("path", pathFilter);
+        if (regex)
+            q.set("regex", "true");
+        if (caseSensitive)
+            q.set("caseSensitive", "true");
+        if (wholeWord)
+            q.set("wholeWord", "true");
+        if (filesOnly)
+            q.set("filesOnly", "true");
+        if (contextLines)
+            q.set("contextLines", contextLines);
+        if (maxResults)
+            q.set("maxResults", maxResults);
         const data = await v1Get(`/api/v1/sites/${encodeURIComponent(slug)}/search?${q.toString()}`);
-        const matches = data.matches ?? [];
-        for (const m of matches) {
-            console.log(`${m.file}:${m.lineNumber}: ${m.line}`);
+        if (isJson()) {
+            emitOk("search", data);
+            return EXIT_OK;
+        }
+        if (filesOnly || data.filesOnly) {
+            const files = data.files ?? [];
+            for (const f of files)
+                console.log(f);
+            if (files.length === 0)
+                console.error("(no matches)");
+        }
+        else {
+            const matches = data.matches ?? [];
+            for (const m of matches) {
+                console.log(`${m.file}:${m.lineNumber}: ${m.line}`);
+            }
+            if (matches.length === 0)
+                console.error("(no matches)");
         }
-        if (matches.length === 0)
-            console.error("(no matches)");
         if (data.truncated || data.scanTruncated)
             console.error("# results truncated");
         return EXIT_OK;
     }
     catch (err) {
+        if (isJson())
+            return emitErr("search", err);
         console.error(err instanceof Error ? err.message : String(err));
         return exitCodeForError(err);
     }

package/dist/commands/tokens.d.ts

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

package/dist/commands/tokens.js

@@ -0,0 +1,64 @@
+import { resolveSlug } from "../site.js";
+import { EXIT_OK, EXIT_USAGE, exitCodeForError, v1Post } from "../http/client.js";
+import { readState, writeState } from "../state/frontpage-state.js";
+import { emitErr, emitOk, emitUsage, 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;
+}
+export async function runTokens(args) {
+    try {
+        const { slug, rest } = await resolveSlug(args);
+        const sub = rest[0];
+        if (sub !== "set") {
+            console.error("Usage: frontpage tokens set --group <colors|fonts|spacing|radii|article> --key <name> --value <…> [--site <slug>]");
+            return EXIT_USAGE;
+        }
+        const work = rest.slice(1);
+        const group = takeFlag(work, "--group");
+        const key = takeFlag(work, "--key");
+        const value = takeFlag(work, "--value");
+        if (!group || !key || value === undefined) {
+            return emitUsage("tokens", "Usage: frontpage tokens set --group <…> --key <…> --value <…> [--site <slug>]", EXIT_USAGE);
+        }
+        const cwd = process.cwd();
+        const state = await readState(cwd);
+        if (!state.baseCommitSha) {
+            return emitUsage("tokens", "No baseCommitSha in .frontpage/state.json. Run: frontpage pull", EXIT_USAGE);
+        }
+        const data = await v1Post(`/api/v1/sites/${encodeURIComponent(slug)}/tokens`, {
+            group,
+            key,
+            value,
+            baseCommitSha: state.baseCommitSha,
+            expectedHeadSha: state.baseCommitSha,
+        });
+        if (data.commitSha) {
+            await writeState({ ...state, slug, baseCommitSha: data.commitSha }, cwd);
+        }
+        if (isJson()) {
+            emitOk("tokens", { slug, ...data });
+            return EXIT_OK;
+        }
+        if (!data.changed) {
+            console.log(`No change (${group}.${key} already set).`);
+        }
+        else {
+            console.log(`Set ${group}.${key} → ${data.commitSha}`);
+            console.log("Updated .frontpage/state.json baseCommitSha");
+        }
+        if (data.warning)
+            console.error(`Warning: ${data.warning}`);
+        return EXIT_OK;
+    }
+    catch (err) {
+        if (isJson())
+            return emitErr("tokens", err);
+        console.error(err instanceof Error ? err.message : String(err));
+        return exitCodeForError(err);
+    }
+}

package/dist/completions/generate.js

@@ -14,15 +14,17 @@ _frontpage_completions() {
   fi
   local cmd="\${COMP_WORDS[1]}"
   case "\${cmd}" in
-    help) COMPREPLY=( $(compgen -W "\${cmds} quickstart auth sync agent content history isolation exit-codes" -- "\${cur}") ) ;;
+    help) COMPREPLY=( $(compgen -W "\${cmds} quickstart auth sync site-building agent content history isolation exit-codes" -- "\${cur}") ) ;;
     completion) COMPREPLY=( $(compgen -W "bash zsh fish" -- "\${cur}") ) ;;
     runs) COMPREPLY=( $(compgen -W "list current wait cancel retry get" -- "\${cur}") ) ;;
     deploy) COMPREPLY=( $(compgen -W "wait" -- "\${cur}") ) ;;
     media) COMPREPLY=( $(compgen -W "list upload" -- "\${cur}") ) ;;
+    fonts) COMPREPLY=( $(compgen -W "list search" -- "\${cur}") ) ;;
+    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 enable disable archive config" -- "\${cur}") ) ;;
-    extensions) COMPREPLY=( $(compgen -W "list enable disable config" -- "\${cur}") ) ;;
+    modules) COMPREPLY=( $(compgen -W "list docs enable disable archive config" -- "\${cur}") ) ;;
+    extensions) COMPREPLY=( $(compgen -W "list docs enable disable config" -- "\${cur}") ) ;;
     *) COMPREPLY=( $(compgen -W "--site --help --json --quiet --yes" -- "\${cur}") ) ;;
   esac
 }
@@ -45,8 +47,10 @@ _frontpage() {
         runs) _values 'subcommand' current wait cancel retry get ;;
         deploy) _values 'subcommand' wait ;;
         media) _values 'subcommand' list upload ;;
+        fonts) _values 'subcommand' list search ;;
+        tokens) _values 'subcommand' set ;;
         seo|settings) _values 'subcommand' get set ;;
-        modules|extensions) _values 'subcommand' list enable disable config ;;
+        modules|extensions) _values 'subcommand' list docs enable disable config ;;
       esac
       ;;
   esac
@@ -63,8 +67,10 @@ export function generateFishCompletion() {
         `complete -c frontpage -n "__fish_seen_subcommand_from runs" -a "current wait cancel retry get"`,
         `complete -c frontpage -n "__fish_seen_subcommand_from deploy" -a "wait"`,
         `complete -c frontpage -n "__fish_seen_subcommand_from media" -a "list upload"`,
+        `complete -c frontpage -n "__fish_seen_subcommand_from 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 enable disable config"`,
+        `complete -c frontpage -n "__fish_seen_subcommand_from modules extensions" -a "list docs enable disable config"`,
         `complete -c frontpage -l site -d "Site subdomain slug"`,
     ];
     return `${lines.join("\n")}\n`;

package/dist/registry.d.ts

@@ -14,6 +14,6 @@ export type CommandDef = {
     seeAlso?: string[];
 };
 export declare const COMMANDS: readonly CommandDef[];
-export declare const TOPIC_NAMES: readonly ["quickstart", "auth", "sync", "agent", "content", "history", "isolation", "exit-codes"];
+export declare const TOPIC_NAMES: readonly ["quickstart", "auth", "sync", "site-building", "agent", "content", "history", "isolation", "exit-codes"];
 export declare const TOPICS: Record<string, string>;
 export declare function findCommand(name: string): CommandDef | undefined;

package/dist/registry.js

@@ -7,8 +7,24 @@ export const COMMANDS = [
         name: "help",
         summary: "Show available commands",
         usage: "frontpage help [command|topic] [--json]",
-        topics: ["auth", "sync", "agent", "content", "history", "isolation", "exit-codes", "quickstart"],
-        examples: ["frontpage help", "frontpage help sync", "frontpage help push", "frontpage help --json"],
+        topics: [
+            "auth",
+            "sync",
+            "site-building",
+            "agent",
+            "content",
+            "history",
+            "isolation",
+            "exit-codes",
+            "quickstart",
+        ],
+        examples: [
+            "frontpage help",
+            "frontpage help sync",
+            "frontpage help site-building",
+            "frontpage help push",
+            "frontpage help --json",
+        ],
     },
     {
         name: "login",
@@ -110,8 +126,47 @@ export const COMMANDS = [
     {
         name: "search",
         summary: "Search remote text files",
-        usage: "frontpage search <pattern> [path] [--site <slug>]",
+        usage: "frontpage search <pattern> [path] [--regex] [--case-sensitive] [--whole-word] [--files-only] [--context-lines N] [--max-results N] [--site <slug>] [--json]",
         topics: ["sync"],
+        flags: [
+            "--regex",
+            "--case-sensitive",
+            "--whole-word",
+            "--files-only",
+            "--context-lines <n>",
+            "--max-results <n>",
+        ],
+    },
+    {
+        name: "fonts",
+        summary: "Browse or search the self-hosted font catalog",
+        usage: "frontpage fonts [list|search] [--slot sans|serif|mono|display] [--query …] [--variable-only] [--limit N] [--offset N] [--json]",
+        topics: ["site-building", "content"],
+        examples: [
+            "frontpage fonts --slot serif",
+            'frontpage fonts search "elegant script"',
+            "frontpage fonts --query Cinzel --json",
+        ],
+        flags: [
+            "Use the exact `value` string in tokens.fonts.* (via frontpage tokens set or push)",
+            "No --site required — catalog is account/platform scoped",
+        ],
+    },
+    {
+        name: "tokens",
+        summary: "Set a single design token surgically (CAS + active-run)",
+        usage: "frontpage tokens set --group <colors|fonts|spacing|radii|article> --key <name> --value <…> [--site <slug>] [--json]",
+        topics: ["site-building", "content"],
+        examples: [
+            'frontpage tokens set --group fonts --key sans --value "\\"Inter Variable\\", system-ui, sans-serif"',
+        ],
+        dangers: [
+            "Requires prior pull (baseCommitSha)",
+            "Refused while an agent run is active (exit 3)",
+            "CAS fail if remote tip moved (exit 3) — pull and retry",
+            "Off-catalog font values warn but do not block",
+        ],
+        seeAlso: ["fonts", "pull", "push"],
     },
     {
         name: "status",
@@ -203,16 +258,18 @@ export const COMMANDS = [
     },
     {
         name: "modules",
-        summary: "List or mutate modules (secret masks only)",
-        usage: "frontpage modules [list|enable|disable|archive|config] <key> [--instance <id>] [--config '{…}'] [--site <slug>]",
+        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>]",
         topics: ["agent", "content"],
+        examples: ["frontpage modules docs forms", "frontpage modules list"],
         dangers: ["Secret values are never returned — masks only"],
     },
     {
         name: "extensions",
-        summary: "List or mutate extensions (no secret values)",
-        usage: "frontpage extensions [list|enable|disable|config] <key> [--config '{…}'] [--site <slug>]",
+        summary: "List, read docs, or mutate extensions (no secret values)",
+        usage: "frontpage extensions [list|docs|enable|disable|config] <key> [--config '{…}'] [--site <slug>]",
         topics: ["agent", "content"],
+        examples: ["frontpage extensions docs charts"],
     },
     {
         name: "media",
@@ -291,6 +348,7 @@ export const TOPIC_NAMES = [
     "quickstart",
     "auth",
     "sync",
+    "site-building",
     "agent",
     "content",
     "history",
@@ -315,8 +373,8 @@ export const TOPICS = {
 
   Staging is the subdomain. There is no separate staging-deploy step for agents.
   Never publish/unpublish unless the user explicitly asks.
-  Agents: read AGENTS.md in the npm package; use --json for structured I/O.
-  More: frontpage help auth | sync | agent | content | history | isolation | exit-codes`,
+  Agents: read AGENTS.md + frontpage help site-building; use --json for structured I/O.
+  More: frontpage help auth | sync | site-building | agent | content | history | isolation | exit-codes`,
     auth: `Authentication
   1. Create a key in the Frontpage editor: profile menu → Developers
   2. frontpage login
@@ -335,7 +393,7 @@ export const TOPICS = {
   frontpage push [--message …]   # uploads allowlisted files; CAS + active-run guard
   frontpage ls [prefix]
   frontpage cat <path>
-  frontpage search <pattern>
+  frontpage search <pattern> [path] [--regex] [--case-sensitive] [--whole-word] [--files-only]
   frontpage open                 # opens https://<slug>.frontpage.host/ (--prod is a no-op stub)
 
   Local state: .frontpage/state.json { slug, baseCommitSha }
@@ -353,6 +411,40 @@ export const TOPICS = {
   - No separate "deploy to staging" step for agents — review the subdomain after the build.
   - frontpage deploy wait only waits for an in-flight build; it is NOT go-live.
   - frontpage publish promotes staging → production (custom domain). Never publish unless asked.`,
+    "site-building": `Site building (Astro contract)
+  Stack: Astro 6 + Tailwind v4. Pages in src/pages/. Every page wraps <BaseLayout title description>.
+  Control files: src/config/tokens.ts (design tokens), src/config/site.ts (title, nav, pages map, seo).
+
+  Pages map:
+  - Add/rename/delete a page file ⇒ update pages (+ nav if needed) in the SAME change set.
+  - Real title/description live on <BaseLayout>, not as authority in the pages map.
+  - One discrete .astro file per URL for similar sets (services, guides…). Do NOT default to
+    getStaticPaths() over src/data/*.ts. Blog/news → frontpage articles.
+
+  Hard fences:
+  - No API routes, serverless backends, or databases.
+  - No fake lead forms / checkout / card fields — use data-fp-* modules + frontpage modules, or refuse.
+  - Platform-owned paths are not syncable (BaseLayout overlay, module/extension shells, package.json…).
+  - Customer layouts (DocsLayout, GuideLayout, …) are fine when site-owned.
+
+  Tokens & fonts:
+  - Keep required colors/fonts/spacing/radii keys; style via CSS variables / token Tailwind.
+  - Setting fonts.sans is not enough — apply font-sans / font-serif / font-display on elements.
+  - Browse fonts: frontpage fonts [--slot serif] [--query elegant] — use the exact value string.
+  - Surgical token edit: frontpage tokens set --group fonts --key sans --value "…" (CAS like push).
+
+  Chrome / SEO / 404:
+  - Prefer src/components/Header.astro + Footer.astro (or chrome: { managed: true } in site.ts).
+  - seo block in site.ts + frontpage seo get|set; customize 404.astro but keep frontpage:404 meta;
+    never put /404 in nav or pages. robots/sitemap are platform-managed.
+
+  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).
+
+  Full guide: https://frontpage.host/developers/site-building
+  See also: frontpage help sync | content | AGENTS.md`,
     agent: `Agent + publish
   frontpage prompt "make the hero shorter"
   frontpage runs                 # latest + active
@@ -376,13 +468,19 @@ export const TOPICS = {
   frontpage inbox [leads|subscribers|orders|…] [--mark-read] [--csv]
   frontpage seo get|set --path /
   frontpage articles list|content|create-section|create-article|set-draft|…
-  frontpage modules enable|disable|archive|config <key>
-  frontpage extensions enable|disable|config <key>
+  frontpage fonts [list|search] [--slot …] [--query …]
+  frontpage tokens set --group … --key … --value …
+  frontpage modules list|docs|enable|disable|archive|config <key>
+  frontpage extensions list|docs|enable|disable|config <key>
   frontpage settings get|set
   frontpage edit --path / --old "…" --new "…"
 
+  Real forms (file sync): <form data-fp-form="slug"> + named inputs — no action/onsubmit/honeypot.
+  Do not fake payments/checkout. LOCKED extensions → do not fake; say plan required.
+  Migrate pages → articles: prefer frontpage prompt "migrate …" over mass delete+write.
   edit uses click-edit (exact single occurrence), not push / gated-write.
   Module OAuth and secret values are not exposed via the CLI.
+  Site contract: frontpage help site-building · https://frontpage.host/developers/site-building
   Domains, billing, members, and site delete are out of v1.`,
     history: `History
   frontpage history [--limit 20] [--page 1]

package/llms.txt

@@ -3,7 +3,11 @@
 - Package: frontpage-host (npm). Binary: frontpage. Do NOT install npm package "frontpage".
 - Docs in this package: README.md, AGENTS.md (agent operating manual).
 - Introspect: frontpage help | frontpage help --json | frontpage help <topic|command>
-- Topics: quickstart, auth, sync, agent, content, history, isolation, exit-codes
+- Topics: quickstart, auth, sync, site-building, agent, content, history, isolation, exit-codes
+- Site building: frontpage help site-building — Astro pages map, BaseLayout, tokens, no backends/fake forms
+- 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
 - 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.3",
+  "version": "0.1.5",
   "description": "Frontpage CLI — manage your site from the terminal",
   "type": "module",
   "bin": {