fimo 0.11.0-staging.5 → 0.11.0-staging.7

package/assets/skills/fimo-cli/references/project-vars-and-secrets.md

@@ -62,7 +62,7 @@ fimo agents secrets remove seo-publisher FIRECRAWL_API_KEY
 fimo agents validate
 ```
 
-`fimo agents secrets add` edits `agents/<name>/config.yaml`. It does not create or rotate the secret value. Use `fimo secrets add` to create the value or `fimo secrets update` to rotate it.
+`fimo agents secrets add` edits `.fimo/agents/<name>/config.yaml`. It does not create or rotate the secret value. Use `fimo secrets add` to create the value or `fimo secrets update` to rotate it.
 
 `fimo agents validate` checks that required agent secrets exist in the project. A running agent keeps the environment it started with; the next run reads the deployed agent config again.
 

package/assets/skills/fimo-cli/references/projects.md

@@ -2,7 +2,7 @@
 
 > **Run via `npx fimo@latest <command>`** — always the latest CLI, no install needed.
 
-Commands for listing projects across an org, cloning a remote project locally, and managing the lifecycle of a single project (delete, publish, unpublish, rename). Most lifecycle commands operate on the **current project** (read from `.fimo.settings.json` in the cwd) by default; for `delete`, `publish`, and `unpublish` you can pass an explicit `[projectId]` to target another. (`rename` is local-only — it never targets a different project; see below.)
+Commands for listing projects across an org, cloning a remote project locally, and managing the lifecycle of a single project (delete, publish, unpublish, rename). Most lifecycle commands operate on the **current project** (read from `.fimo/project.json`, or the legacy `.fimo.settings.json`, in the cwd) by default; for `delete`, `publish`, and `unpublish` you can pass an explicit `[projectId]` to target another. (`rename` only edits the linked local project; see below.)
 
 ## The `fimo projects` namespace
 
@@ -13,15 +13,15 @@ fimo projects clone [projectId] [dir] [--env <name>] # clone an existing project
 fimo projects delete [projectId] [-C <dir>] [-y] # delete (defaults to current project)
 fimo projects publish [projectId] [-C <dir>]     # make the project live (publish from main)
 fimo projects unpublish [projectId] [-C <dir>]   # take the project offline
-fimo projects rename <name> [projectId] [-C <dir>]   # local-only: set seo.siteName in fimo-config.json
+fimo projects rename <name> [projectId] [-C <dir>]   # set seo.siteName in the linked project config
 ```
 
 - **`list`** — projects you can see in the org. Live projects are marked.
 - **`create`** — identical to `fimo init` (create-new path); see `references/init.md`.
-- **`clone`** — clone a remote Fimo project's git repo to your machine and write the local `.fimo.settings.json`/agent files. Use `fimo clone <projectId>` when scripting or when the ID is known. In an interactive terminal, bare `fimo clone` opens a project picker for the active org; JSON mode and non-TTY shells require an explicit project ID and fail fast instead of prompting. By default it clones `main`; pass `--env <name>` to clone a specific env. The target directory defaults to the project display name/name, or pass `[dir]` explicitly.
+- **`clone`** — clone a remote Fimo project's git repo to your machine and write the local `.fimo/project.json` and agent files. Use `fimo clone <projectId>` when scripting or when the ID is known. In an interactive terminal, bare `fimo clone` opens a project picker for the active org; JSON mode and non-TTY shells require an explicit project ID and fail fast instead of prompting. By default it clones `main`; pass `--env <name>` to clone a specific env. The target directory defaults to the project display name/name, or pass `[dir]` explicitly.
 - **`delete`** — destructive; prompts unless `-y`. Removes the remote project.
 - **`publish` / `unpublish`** — toggle the project's public visibility. `publish` flips the current `main` state live (the same "go live" as `fimo deploy --publish`, minus the git push). This is **not** the versioned release path — for that, see `fimo publish` in `references/branches.md`.
-- **`rename`** — **local-only**, unlike the others. It does not touch the remote project record. It requires `.fimo.settings.json` in the cwd, and if you pass a `[projectId]` that doesn't match the linked project it errors and exits 1 (so you can't rename a different project). It writes `seo.siteName` into the local `fimo-config.json`; you must commit and run `fimo deploy` to apply the change.
+- **`rename`** — edits only the linked local project immediately. It requires a project marker in the cwd, and if you pass a `[projectId]` that doesn't match the linked project it errors and exits 1 (so you can't rename a different project). It writes `seo.siteName` into the current or legacy project config; commit and run `fimo deploy` to reconcile the remote `displayName` and deploy the new site name.
 
 ## Top-level clone shortcut
 
@@ -33,15 +33,15 @@ Use the top-level shortcut for the common "get this project onto my machine" wor
 
 ## Top-level shortcuts (current project)
 
-These target the project linked in the cwd's `.fimo.settings.json` — handy from inside a project directory:
+These target the project linked in the cwd's `.fimo/project.json` (or legacy `.fimo.settings.json`) — handy from inside a project directory:
 
 ```bash
 fimo delete [-C <dir>] [-y]      # delete the current project
 fimo unpublish [-C <dir>]        # unpublish the current project
-fimo rename "<Site Name>"        # local edit: set seo.siteName in fimo-config.json
+fimo rename "<Site Name>"        # local edit: set seo.siteName in the project config
 ```
 
-`fimo rename` sets the **site name** (`seo.siteName`) in the local `fimo-config.json` — it is a local edit, not a remote update, so it requires a follow-up commit + `fimo deploy` to take effect. It does **not** change the project's remote display name (the `displayName` shown by `projects list`), which is set once at creation time from the project directory name. See `references/init.md` and `references/deploy.md`.
+`fimo rename` sets the **site name** (`seo.siteName`) in the local project config — it is a local edit, not an immediate remote update, so it requires a follow-up commit + `fimo deploy` to take effect. Deploy reconciles the project's remote `displayName` with the committed site name while pushing the config. See `references/init.md` and `references/deploy.md`.
 
 ## Three "publish" verbs — don't confuse them
 

package/assets/skills/fimo-code/references/labels.md

@@ -21,11 +21,11 @@ In development, the generated app reloads when DB label values change. In produc
 
 ## Locale behavior
 
-The default label locale is `i18n.defaultLocale` in `fimo-config.json`, falling back to `en` when it is not set. `fimo validate`, the generated app runtime, and `fimo labels set` without `--locale` all use that default locale.
+The default label locale is `i18n.defaultLocale` in `.fimo/config.json`, falling back to `en` when it is not set. `fimo validate`, the generated app runtime, and `fimo labels set` without `--locale` all use that default locale.
 
 For non-default locales, create explicit DB values with `fimo labels set --locale <locale>` or `fimo labels set-many --locale <locale>`. Keep the code shape the same for every locale: `t('hero.title')` declares the key, and the DB decides which locale value is shown.
 
-`fimo-config.json` owns the locale list:
+`.fimo/config.json` owns the locale list:
 
 ```json
 {

package/assets/skills/fimo-code/references/locales.md

@@ -4,7 +4,7 @@ Fimo provides locale utilities that follow the Fimo standard, but they are helpe
 
 ## Configuration
 
-`fimo-config.json` owns the locale list and routing strategy. Keep one locale unless the user asks for multilingual or localized output.
+`.fimo/config.json` owns the locale list and routing strategy. Keep one locale unless the user asks for multilingual or localized output.
 
 ```jsonc
 {
@@ -28,7 +28,7 @@ Locale tags should be structurally valid, for example `en`, `es`, `pt-BR`, or `z
 
 ## Canonical Routes
 
-Keep `fimo-config.json#routes` canonical and unlocalized:
+Keep `.fimo/config.json#routes` canonical and unlocalized:
 
 ```json
 {
@@ -71,7 +71,7 @@ Copyable examples live in `assets/react-router-locales/routes.ts` and `assets/re
 
 Before changing a multilingual app, inspect its locale provider, route table, language switcher, redirects, and current public URLs. Preserve that behavior while migrating.
 
-For React Router projects, prefer converging on one locale contract owned by `fimo-config.json`, `fimoRoutes()`, and `FimoLink`. Move existing providers and language-switcher UI into the framework root instead of replacing them or adding a second locale context. Keep route metadata canonical and reuse page modules across locales.
+For React Router projects, prefer converging on one locale contract owned by `.fimo/config.json`, `fimoRoutes()`, and `FimoLink`. Move existing providers and language-switcher UI into the framework root instead of replacing them or adding a second locale context. Keep route metadata canonical and reuse page modules across locales.
 
 If adopting the standard helper would change established public URLs, do not silently rewrite them. Keep the custom router temporarily, pass its resolved locale to `<FimoProviders locale={locale}>`, and ask the user to choose the canonical URLs and redirects before normalizing the route table.
 
@@ -86,7 +86,7 @@ import { FimoLink } from 'fimo/react-router';
 <FimoLink to="/pricing" locale="es">Spanish pricing</FimoLink>
 ```
 
-`FimoLink` localizes absolute internal paths according to `fimo-config.json#i18n.routing`. It leaves relative, hash, query-only, and external URLs alone. Use React Router's raw `Link` only when you intentionally want to bypass Fimo's locale behavior.
+`FimoLink` localizes absolute internal paths according to `.fimo/config.json#i18n.routing`. It leaves relative, hash, query-only, and external URLs alone. Use React Router's raw `Link` only when you intentionally want to bypass Fimo's locale behavior.
 
 Read the active locale with `useLocale()` when component logic needs it:
 
@@ -125,5 +125,5 @@ When using custom routing, also provide localized internal-link helpers in that
 ## What Not To Do
 
 - Do not create `src/pages/__localized/*` copies just for locales.
-- Do not duplicate every route in `fimo-config.json` per locale.
+- Do not duplicate every route in `.fimo/config.json` per locale.
 - Do not use `/es` as a normal canonical route when `es` is an enabled locale.

package/assets/skills/fimo-code/references/setup-plain-vite.md

@@ -85,7 +85,7 @@ Notes:
 ```
 
 The `seo` plugin rewrites `<title>`, og, twitter, canonical tags from
-`fimo-config.json#seo` at build time. You can leave a placeholder title in
+`.fimo/config.json#seo` at build time. You can leave a placeholder title in
 `index.html`; it'll be replaced.
 
 ## File: `src/main.tsx`
@@ -140,7 +140,7 @@ export function App() {
 }
 ```
 
-## File: `fimo-config.json`
+## File: `.fimo/config.json`
 
 ```json
 {
@@ -165,7 +165,7 @@ this version field. It also never injects the React Router plugin: in a
 framework-mode project that `reactRouter()` plugin is added by your own
 `vite.config.ts`, not by `fimo/vite`.
 
-## File: `.fimo.settings.json`
+## File: `.fimo/project.json`
 
 ```json
 {
@@ -222,6 +222,6 @@ shows the **deployed** app, not the localhost dev server.
 ## What to do next
 
 - Add a sitemap: pass `fimo({ seo: true, sitemap: true })` and set
-  `fimo-config.json#seo.url` to your production base URL.
+  `.fimo/config.json#seo.url` to your production base URL.
 - Look up exports: see `references/ui.md`.
 - Use schema content: see `references/content.md`.

package/assets/skills/fimo-code/references/setup-react-router.md

@@ -166,7 +166,7 @@ export default fimoRoutes(routes) satisfies RouteConfig;
 Page filenames are your choice; the scaffold uses PascalCase (e.g. `Index.tsx`,
 `Privacy.tsx`).
 
-`fimoRoutes()` is Fimo's React Router helper for path-prefix locales. It is a no-op for single-locale projects and expands concrete locale aliases when `fimo-config.json#i18n.locales` contains more locales. Custom routers can ignore this helper and pass their own locale to `<FimoProviders locale={locale}>`; see `references/locales.md`.
+`fimoRoutes()` is Fimo's React Router helper for path-prefix locales. It is a no-op for single-locale projects and expands concrete locale aliases when `.fimo/config.json#i18n.locales` contains more locales. Custom routers can ignore this helper and pass their own locale to `<FimoProviders locale={locale}>`; see `references/locales.md`.
 
 ## File: `src/pages/Index.tsx`
 
@@ -182,7 +182,7 @@ export default function HomePage() {
 }
 ```
 
-## File: `fimo-config.json`
+## File: `.fimo/config.json`
 
 ```json
 {
@@ -200,7 +200,7 @@ export default function HomePage() {
 }
 ```
 
-## File: `.fimo.settings.json`
+## File: `.fimo/project.json`
 
 ```json
 {
@@ -268,9 +268,9 @@ changes after a `fimo deploy` (the local dev server is localhost-only).
 ## What to do next
 
 - Add more routes: extend `src/routes.ts`, create matching `src/pages/*.tsx`,
-  add route entries in `fimo-config.json#routes`.
+  add route entries in `.fimo/config.json#routes`.
 - Add a sitemap: pass `fimo({ sitemap: true })` (opt-in, off by default; the
   canonical template enables it). To customize the base URL, set
-  `fimo-config.json#seo.url`.
+  `.fimo/config.json#seo.url`.
 - Override SEO per route: see `references/seo-overrides.md`.
 - Look up an export: see `references/api.md`.

package/assets/skills/fimo-code/references/ui.md

@@ -27,7 +27,7 @@ Use these to render content-type field values consistently. They carry source me
 1. **Schema text → `<Text>`**, never `<h1>{post.title}</h1>`.
 2. **Schema media → `<Image>` / `<Video>`**, never `<img src={post.coverImage.url} />`. Provide `width` / `height` when known so Fimo can optimize and reserve layout space.
 3. **Non-schema images** (decorative, hard-coded URLs, generated assets referenced directly) → `<StaticImage>`. Never hand-construct a `FimoMedia` to feed `<Image>`.
-4. **Label text → `<Text value={t('key')} />`**, not `<h1>{t(...)}</h1>`. Label values live in the DB for `i18n.defaultLocale` from `fimo-config.json` unless a non-default locale is explicitly targeted. See `references/labels.md`.
+4. **Label text → `<Text value={t('key')} />`**, not `<h1>{t(...)}</h1>`. Label values live in the DB for `i18n.defaultLocale` from `.fimo/config.json` unless a non-default locale is explicitly targeted. See `references/labels.md`.
 5. **Mixed schema + translated text** → the `` fimo`...` `` template literal inside `<Text>`.
 6. **Never hand-roll richtext rendering** — always `<RichText>`. To restyle a node, pass `components={{ heading: ..., link: ..., ... }}`.
 7. **Schema `json` → `<Json>`**, not a hand-rolled `<pre data-fimo-source={getFimoSource(post.metadata)}>{JSON.stringify(post.metadata)}</pre>`. Default renders as a `<span>`; pass `as="pre"` (with a `whitespace-pre-wrap` class) for a formatted block, or a children render function for custom display of specific keys.

package/assets/skills/fimo-migration/references/workflow.md

@@ -6,7 +6,7 @@ Use this as the phase contract for complete migrations.
 
 1. Confirm the target path.
 2. If the target path is missing, create exactly one Fimo project there.
-3. If it has `.fimo.settings.json`, reuse it.
+3. If it has `.fimo/project.json` or the legacy `.fimo.settings.json`, reuse it.
 4. If it is non-empty and not a Fimo project, stop and ask for a target path.
 5. Never overwrite user work outside generated migration folders without reading
    the existing files first.

package/assets/skills/fimo-migration/scripts/build-canonical-manifest.mjs

@@ -110,7 +110,7 @@ function buildCanonicalManifest({ projectRoot, urlLedger, urlLedgerPath, sourceL
     forms,
     redirects: normalizeItems(sourceLedger?.redirects, 'redirect'),
     locales: normalizeItems(sourceLedger?.locales, 'locale'),
-    seo: normalizeSeo(urlLedger),
+    seo: normalizeSeo(urlLedger, projectRoot),
     unsupported: normalizeItems(sourceLedger?.unsupported, 'unsupported'),
     unresolved: mergeItems([
       ...normalizeUnresolved(sourceLedger?.unresolved),
@@ -326,14 +326,15 @@ function normalizeUrlForms(forms) {
   }));
 }
 
-function normalizeSeo(urlLedger) {
+function normalizeSeo(urlLedger, projectRoot) {
+  const configPath = resolveProjectConfigPath(projectRoot);
   return asArray(urlLedger?.pages).map((page) => ({
     id: `seo:${page.route}`,
     status: 'discovered',
     route: page.route,
     sourceUrls: compact([page.url]),
     sourceFiles: compact([page.artifacts?.html]),
-    targetFiles: ['fimo-config.json'],
+    targetFiles: [configPath],
     confidence: numberOr(page.confidence, 0.7),
     title: page.seo?.title ?? page.title ?? null,
     description: page.seo?.description ?? null,
@@ -341,6 +342,34 @@ function normalizeSeo(urlLedger) {
   }));
 }
 
+function resolveProjectConfigPath(projectRoot) {
+  if (fs.existsSync(path.join(projectRoot, '.fimo/project.json'))) {
+    return '.fimo/config.json';
+  }
+  if (fs.existsSync(path.join(projectRoot, '.fimo.settings.json'))) {
+    if (fs.existsSync(path.join(projectRoot, 'fimo-config.json'))) {
+      return 'fimo-config.json';
+    }
+    if (fs.existsSync(path.join(projectRoot, 'fimo.config.json'))) {
+      return 'fimo.config.json';
+    }
+    return 'fimo-config.json';
+  }
+  if (
+    fs.existsSync(path.join(projectRoot, '.fimo/config.json')) ||
+    fs.existsSync(path.join(projectRoot, '.fimo/agents'))
+  ) {
+    return '.fimo/config.json';
+  }
+  if (fs.existsSync(path.join(projectRoot, 'fimo-config.json'))) {
+    return 'fimo-config.json';
+  }
+  if (fs.existsSync(path.join(projectRoot, 'fimo.config.json'))) {
+    return 'fimo.config.json';
+  }
+  return '.fimo/config.json';
+}
+
 function normalizeUnresolved(items) {
   return asArray(items).map((item, index) => {
     if (typeof item === 'string') {

package/assets/starters/fimo-site/manifest.json

@@ -0,0 +1,64 @@
+{
+  "name": "fimo-site",
+  "version": 1,
+  "description": "A content-led site with a homepage, contact form, labels, and manual review agents.",
+  "singletons": [
+    {
+      "type": "HomePage",
+      "data": {
+        "eyebrow": "Field notes",
+        "title": "Your website, ready to edit.",
+        "intro": {
+          "type": "doc",
+          "content": [
+            {
+              "type": "paragraph",
+              "content": [
+                {
+                  "type": "text",
+                  "text": "This starter is real website content. Edit the copy in Studio, change the code with your favorite agent, and keep both surfaces in sync."
+                }
+              ]
+            }
+          ]
+        },
+        "primaryCtaLabel": "Read the field notes",
+        "primaryCtaHref": "#stories",
+        "featured": [
+          {
+            "label": "Start here",
+            "title": "A calmer content workflow",
+            "summary": "Keep content, code, previews, and the team in one editable project.",
+            "href": "#stories"
+          },
+          {
+            "label": "For agents",
+            "title": "Build once, keep iterating",
+            "summary": "Give your coding agent a real CMS surface to work with after the first deploy.",
+            "href": "#stories"
+          },
+          {
+            "label": "For teams",
+            "title": "Make every edit reviewable",
+            "summary": "Let teammates shape the site without asking them to open a code editor.",
+            "href": "#stories"
+          }
+        ],
+        "contactHeading": "Make something useful",
+        "contactIntro": "Tell us what you are building and we will help you find the shortest path from first draft to a site your team can own."
+      }
+    }
+  ],
+  "labels": [
+    { "key": "nav.stories", "value": "Field notes", "locale": "en" },
+    { "key": "nav.contact", "value": "Start a conversation", "locale": "en" },
+    { "key": "hero.scroll", "value": "Explore the starter", "locale": "en" },
+    { "key": "contact.name", "value": "Your name", "locale": "en" },
+    { "key": "contact.email", "value": "Email address", "locale": "en" },
+    { "key": "contact.message", "value": "What are you building?", "locale": "en" },
+    { "key": "contact.submit", "value": "Send a note", "locale": "en" },
+    { "key": "contact.sent", "value": "Thanks. Your note is on its way.", "locale": "en" },
+    { "key": "contact.failed", "value": "That did not send. Please try again.", "locale": "en" }
+  ],
+  "forms": ["contact"]
+}

package/assets/starters/fimo-site/template/.fimo/agents/content-guide/GOAL.md

@@ -0,0 +1,8 @@
+# Content guide
+
+Inspect the site's content model and homepage copy. Suggest a small editorial
+backlog that makes the site more useful to its intended audience.
+
+Return three suggestions, each with the content type or field it touches and
+why it matters. Use the existing content as evidence. Do not write files,
+change entries, or create labels.

package/assets/starters/fimo-site/template/.fimo/agents/content-guide/capabilities.yaml

@@ -0,0 +1,2 @@
+- files:read
+- cms:read

package/assets/starters/fimo-site/template/.fimo/agents/content-guide/config.yaml

@@ -0,0 +1,9 @@
+# Keep starter agents manual-only. Adding a schedule or webhook and pushing to
+# main registers an automation for the project.
+version: 1
+description: 'Suggest useful editorial improvements from the existing CMS content.'
+data_sources:
+  - main
+
+triggers:
+  - type: manual

package/assets/starters/fimo-site/template/.fimo/agents/site-review/GOAL.md

@@ -0,0 +1,14 @@
+# Site review
+
+Review the starter project as a teammate would before the first publish.
+
+Read the declared routes, the CMS content, the labels, and the public site.
+Return a short report with:
+
+- one thing that already feels clear;
+- the three highest-value improvements;
+- any missing content or broken route you can prove;
+- one next action that a human or coding agent can review.
+
+This is a read-only review. Do not edit files, change CMS content, create
+branches, or publish anything.

package/assets/starters/fimo-site/template/.fimo/agents/site-review/capabilities.yaml

@@ -0,0 +1,4 @@
+- files:read
+- cms:read
+- i18n:read
+- net:fetch

package/assets/starters/fimo-site/template/.fimo/agents/site-review/config.yaml

@@ -0,0 +1,9 @@
+# Keep starter agents manual-only. Adding a schedule or webhook and pushing to
+# main registers an automation for the project.
+version: 1
+description: 'Review the starter site and return a concise, read-only launch report.'
+data_sources:
+  - main
+
+triggers:
+  - type: manual

package/assets/starters/fimo-site/template/src/forms/contact.json

@@ -0,0 +1,14 @@
+{
+  "name": "contact",
+  "label": "Start a conversation",
+  "fields": {
+    "name": { "type": "text", "label": "Your name", "required": true },
+    "email": { "type": "email", "label": "Email address", "required": true },
+    "message": {
+      "type": "textarea",
+      "label": "What are you building?",
+      "required": true,
+      "validation": { "minLength": 10, "maxLength": 2000 }
+    }
+  }
+}

package/assets/starters/fimo-site/template/src/forms/contact.ts

@@ -0,0 +1,46 @@
+// AUTO-GENERATED ⚠️ — do not edit by hand
+// Source: src/forms/contact.json
+// The CLI replaces the placeholder form id while seeding the starter. `fimo
+// validate` regenerates this file from the JSON spec on later edits.
+
+import { z } from 'zod';
+
+export const FORM_ID = '__FIMO_FORM_ID__';
+
+export const ContactSchema = z.object({
+  name: z.string().min(1, 'Your name is required'),
+  email: z.string().min(1, 'Email address is required').email('Invalid email address'),
+  message: z.string().min(1, 'What are you building? is required').min(10).max(2000),
+});
+
+export type ContactData = z.infer<typeof ContactSchema>;
+
+// @ts-ignore - meta.env is a vite feature
+const base = import.meta.env.VITE_API_URL;
+
+export async function submitContact(data: ContactData): Promise<{
+  success: boolean;
+  errors?: Record<string, string>;
+}> {
+  let response: Response;
+  try {
+    response = await fetch(`${base}/forms/${FORM_ID}/submit`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(data),
+    });
+  } catch {
+    return { success: false };
+  }
+
+  if (response.ok) {
+    return { success: true };
+  }
+
+  if (response.status === 422) {
+    const json = (await response.json()) as { errors?: Record<string, string> };
+    return { success: false, errors: json.errors };
+  }
+
+  return { success: false };
+}

package/assets/starters/fimo-site/template/src/pages/Contact.tsx

@@ -0,0 +1,193 @@
+import { type FimoString, Text, useLabels } from 'fimo/ui';
+import { ArrowUpRight, Check } from 'lucide-react';
+import { type FormEvent, type ReactNode, useState } from 'react';
+
+import { Button } from '@/components/ui/button';
+import { Input } from '@/components/ui/input';
+import { Label } from '@/components/ui/label';
+import { Spinner } from '@/components/ui/spinner';
+import { Textarea } from '@/components/ui/textarea';
+import { ContactSchema, submitContact } from '@/forms/contact';
+import { cn } from '@/lib/utils';
+import type { HomePage } from '@/schemas/HomePage';
+
+import { Bar } from './SiteContent';
+
+export function Contact({ page, loading }: { page?: HomePage; loading: boolean }) {
+  return (
+    <section id="contact" className="dark bg-background text-foreground scroll-mt-16">
+      <div className="mx-auto grid w-full max-w-6xl gap-12 px-6 py-20 lg:grid-cols-12 lg:gap-16 lg:px-10 lg:py-28">
+        <div className="lg:col-span-5">
+          {page ? (
+            <>
+              <Text
+                value={page.contactHeading}
+                as="h2"
+                className="text-4xl font-semibold tracking-[-0.03em] text-balance lg:text-5xl"
+              />
+              <Text value={page.contactIntro} as="p" className="text-muted-foreground mt-6 max-w-md leading-relaxed" />
+            </>
+          ) : (
+            <div aria-hidden>
+              <div className="grid gap-3">
+                <Bar loading={loading} className="h-10 w-4/5" />
+                <Bar loading={loading} className="h-10 w-2/5" />
+              </div>
+              <div className="mt-8 grid gap-2">
+                <Bar loading={loading} className="h-4 w-full max-w-md" />
+                <Bar loading={loading} className="h-4 w-11/12 max-w-md" />
+                <Bar loading={loading} className="h-4 w-2/3 max-w-md" />
+              </div>
+            </div>
+          )}
+        </div>
+
+        <div className="lg:col-span-7">
+          <ContactForm />
+        </div>
+      </div>
+    </section>
+  );
+}
+
+type SubmitState = 'idle' | 'submitting' | 'sent' | 'invalid' | 'failed';
+
+function ContactForm() {
+  const { t } = useLabels();
+  const [state, setState] = useState<SubmitState>('idle');
+  const [errors, setErrors] = useState<Record<string, string>>({});
+
+  const handleSubmit = async (event: FormEvent<HTMLFormElement>) => {
+    event.preventDefault();
+    // `currentTarget` is cleared once the handler yields, so keep the node.
+    const form = event.currentTarget;
+    setErrors({});
+
+    const parsed = ContactSchema.safeParse(Object.fromEntries(new FormData(form)));
+    if (!parsed.success) {
+      const fieldErrors: Record<string, string> = {};
+      for (const issue of parsed.error.issues) {
+        fieldErrors[issue.path[0] as string] = issue.message;
+      }
+      setErrors(fieldErrors);
+      setState('invalid');
+      return;
+    }
+
+    setState('submitting');
+    const result = await submitContact(parsed.data);
+    if (result.success) {
+      form.reset();
+      setState('sent');
+      return;
+    }
+
+    // A rejected submission comes back with per-field messages; a network or
+    // server failure has nothing to attach to a field, so it needs its own.
+    const fieldErrors = result.errors ?? {};
+    setErrors(fieldErrors);
+    setState(Object.keys(fieldErrors).length > 0 ? 'invalid' : 'failed');
+  };
+
+  const busy = state === 'submitting';
+  const sent = state === 'sent';
+
+  return (
+    <form
+      onSubmit={handleSubmit}
+      noValidate
+      aria-busy={busy}
+      className="border-border bg-card rounded-xl border p-6 sm:p-8"
+    >
+      <div className="grid gap-6 sm:grid-cols-2">
+        <FormField id="contact-name" label={t('contact.name')} error={errors.name}>
+          <Input
+            id="contact-name"
+            name="name"
+            type="text"
+            autoComplete="name"
+            disabled={busy || sent}
+            aria-invalid={Boolean(errors.name)}
+            aria-describedby={errors.name ? 'contact-name-error' : undefined}
+          />
+        </FormField>
+
+        <FormField id="contact-email" label={t('contact.email')} error={errors.email}>
+          <Input
+            id="contact-email"
+            name="email"
+            type="email"
+            autoComplete="email"
+            disabled={busy || sent}
+            aria-invalid={Boolean(errors.email)}
+            aria-describedby={errors.email ? 'contact-email-error' : undefined}
+          />
+        </FormField>
+
+        <div className="sm:col-span-2">
+          <FormField id="contact-message" label={t('contact.message')} error={errors.message}>
+            <Textarea
+              id="contact-message"
+              name="message"
+              rows={5}
+              disabled={busy || sent}
+              aria-invalid={Boolean(errors.message)}
+              aria-describedby={errors.message ? 'contact-message-error' : undefined}
+            />
+          </FormField>
+        </div>
+      </div>
+
+      <div className="mt-8 flex flex-wrap items-center gap-x-4 gap-y-3">
+        <Button
+          type="submit"
+          size="lg"
+          disabled={busy || sent}
+          className={cn('group', state === 'invalid' && 'ring-destructive/40 ring-[3px]')}
+        >
+          {busy ? <Spinner /> : null}
+          {sent ? <Check /> : null}
+          <Text value={t('contact.submit')} />
+          {!busy && !sent ? (
+            <ArrowUpRight className="transition-transform group-hover:translate-x-0.5 group-hover:-translate-y-0.5" />
+          ) : null}
+        </Button>
+
+        {/* Both regions stay mounted and empty: a live region inserted at the same
+            moment as its text is announced unreliably. */}
+        <p role="status" className="text-muted-foreground text-sm">
+          {sent ? <Text value={t('contact.sent')} /> : null}
+        </p>
+        <p role="alert" className="text-destructive text-sm">
+          {state === 'failed' ? <Text value={t('contact.failed')} /> : null}
+        </p>
+      </div>
+    </form>
+  );
+}
+
+function FormField({
+  id,
+  label,
+  error,
+  children,
+}: {
+  id: string;
+  label: FimoString;
+  error?: string;
+  children: ReactNode;
+}) {
+  return (
+    <div className="grid gap-2">
+      <Label htmlFor={id} className="text-muted-foreground text-[11px] font-medium tracking-[0.16em] uppercase">
+        <Text value={label} />
+      </Label>
+      {children}
+      {error ? (
+        <p id={`${id}-error`} role="alert" className="text-destructive text-xs">
+          {error}
+        </p>
+      ) : null}
+    </div>
+  );
+}