Site building

Frontpage sites are Astro projects. Coding agents editing via pull/push should follow the same product contract as the in-editor agent — without inventing backends or editing platform-owned files. Deep command examples live under Content & settings and File sync. In the CLI package: frontpage help site-building and AGENTS.md.

Stack

• Astro 6 + TypeScript + Tailwind CSS v4
• Pages under src/pages/ (home is src/pages/index.astro)
• Every page wraps content in <BaseLayout title="…" description="…">
• Design tokens: src/config/tokens.ts
• Site registry (title, nav, pages map, optional seo): src/config/site.ts
• Components under src/components/; static assets under public/

Page registry (site.ts)

The pages map is the path registry — which URL paths exist — not the authority for the browser tab title. Real title/description come from each page’s <BaseLayout> props.

• Add a page: create src/pages/… and add a matching pages entry (and nav if it should appear in navigation) in the same change set before push.
• Delete / rename: update or remove the file, pages entry, and any nav item together.
• Path mapping: index.astro → /, about.astro → /about, blog/index.astro → /blog.

One file per URL

For sets of similar pages (services, locations, guides, case studies), prefer one discrete .astro file per URL plus a shared layout component. Do not default to getStaticPaths() over a local src/data/*.ts array — those pages are hard to edit individually in the product. Exception: a genuinely large uniform catalog. Blog/news/essay content belongs in the Articles module (frontpage articles), not a hand-rolled data-driven template.

Hard product fences

• No backends — no API routes, serverless functions, or databases.
• No fake forms or checkout — use real modules (data-fp-* markup + frontpage modules) or say you cannot do it.
• Astro only — do not migrate the site to another framework.

Platform-owned vs customer files

Sync only src/, public/, content/. Platform overlay / scaffold paths are rejected (examples: BaseLayout.astro, module/extension shells, package.json, astro.config.mjs). Customer layouts such as DocsLayout.astro or GuideLayout.astro are fine when they are site-owned.

Shared chrome

Prefer src/components/Header.astro and src/components/Footer.astro imported on every page (including article landings). Alternatively set chrome: { managed: true } in site.ts for config-driven chrome from nav. Opt out per page with <BaseLayout chrome={false}>.

Design tokens

tokens.ts is a typed contract. Keep required groups/keys: colors (primary, secondary, background, text, muted, border), fonts (sans, serif, mono; optional display), spacing (xs–xl), radii (base, full). Optional article group for article-only overrides. Prefer surgical edits over rewriting the whole file; do not rename keys or redefine the type. Style pages with CSS variables / token-backed Tailwind (e.g. text-[color:var(--color-muted)]), not hardcoded brand colors.

Fonts: browse the installed catalog with frontpage fonts [--slot serif] [--query elegant] and copy the exact value string. Set one token surgically with frontpage tokens set --group fonts --key sans --value "…" (same CAS / active-run rules as push). Setting a family in tokens.fonts is not enough — also apply font-sans / font-serif / font-mono / font-display on elements.

SEO, favicon, 404

• Site-wide defaults live in the seo block of site.ts (favicon, ogImage, siteName, canonicalBase when on a custom domain). Per-page overrides use <BaseLayout> props.
• Prefer frontpage seo get|set for metadata tweaks without a full file rewrite — see Content.
• Customize src/pages/404.astro if needed; keep <meta name="frontpage:404" content="true" />. Never add /404 to nav or pages.
• robots.txt / sitemap.xml are platform-managed. Do not invent a Sitemap line. Use noindex on BaseLayout / seo set to keep pages out of search.

Modules & articles (summary)

Real lead forms use <form data-fp-form="slug"> with named inputs — no custom submit JS, honeypot, or action. Do not fake card fields or checkout. Manage lifecycle with frontpage modules / frontpage articles. To migrate a folder of pages into Articles, prefer frontpage prompt "migrate … into the articles module" rather than a fragile mass delete/write. Full markup examples: Content & settings.

Craft defaults

• Common sections (hero, features grid, pricing, testimonials, FAQ with <details>, CTA band, footer) are good defaults — always styled from the site’s tokens, not a stock template look.
• When asked for real copy, do not leave lorem/TODO placeholders. For large pages: push a complete skeleton first, then grow section by section across edits/pushes.
• Media: frontpage media upload for images/PDFs (≤25 MB), video MP4/WebM/MOV (≤50 MB), and SVG/text (≤4 MB proxy). Reference the returned sitePath (/__media/uploads/<slug>/…) in markup — never raw *.blob.vercel-storage.com URLs. Optional raster sizing: append ?w=320|640|960|1280 on /__media/… image paths only (not video).

Workflow reminder

frontpage pull                 # or when tipDrift
# edit allowlisted files following this contract
frontpage diff --json
frontpage push --message "…"
# review https://<subdomain>.frontpage.host — do not publish unless asked