fimo 2.4.0-staging.1 → 2.4.0-staging.10

package/assets/skills/fimo-cli/SKILL.md

@@ -91,6 +91,7 @@ Load the matching reference when the user's request fires its trigger. Recipes t
 - "Deploy / publish / go live / push my changes" → `references/deploy.md`
 - "Add a redirect / security headers / CSP / HSTS / clean URLs / trailing slash" → `references/hosting.md`
 - "Get the preview URL / open the preview / what's the URL for this Branch / refresh the preview link / I just want to see the site / the preview URL stopped working" → `references/preview.md`
+- "Check the site in a browser / is my site accessible / a11y or WCAG check / measure LCP or Web Vitals / why is the page slow / inspect network requests or console errors / Lighthouse score" → `references/site-checks.md`
 - "Schedule a command / cron / nightly publish / recurring checks / `fimo schedules`" → `references/schedules.md`
 - "Set env vars / configure API keys / add project secrets / local `.env.local` / `fimo vars` / `fimo secrets`" → `references/project-vars-and-secrets.md`
 - "React to form submissions / publish changes / agent runs / analytics reports / media activity / send events to Resend, Slack, GitHub, Zapier, or an HTTP endpoint / configure or debug outbound webhooks" → `references/webhooks.md`
@@ -100,7 +101,7 @@ Load the matching reference when the user's request fires its trigger. Recipes t
 - "List history / create a restore point / recover content and code / restore a previous version / snapshot usage or retention" → `references/history.md`
 - "Create a Branch / feature Branch / switch Branches / merge Branches / diff two Branches / Branch status / what changed on this Branch / sync from parent / cut a release / tag a version / go to prod" → `references/branches.md`
 - "List my projects / clone an existing project locally / check out a project / delete this project / unpublish / rename the project / manage projects across the org" → `references/projects.md`
-- "Migrate an existing Webflow / Framer / Squarespace / Wix / Carrd site from only a published URL" → load the `fimo-migration` skill and start with `fimo migrate <url> [dir]` to prepare the agent-ready migration draft
+- "Migrate an existing Webflow / Framer / Squarespace / Wix / Carrd site from only a published URL" → load the `fimo-migration` skill, set the target up with `fimo migrate init <dir>`, and read the published site yourself with a browser — the CLI does not crawl it
 - "Migrate from an exported project, source repository, Webflow code export plus CMS CSVs, Framer CMS CSVs, Squarespace XML/CSV, Wix CSVs, Carrd/static export, or downloaded site files" → load the `fimo-migration` skill and use the source repo/export as the migration source of truth
 - "How do AI agents read my site / markdown for agents" → `references/deploy.md`
 - "Modify the URL of the website / change my project's address / connect a custom domain (e.g. blog.example.com) / rename the Fimo-provided `*.fimo.site` subdomain / buy a new domain through Fimo / set up a domain" → `references/domains.md`
@@ -145,7 +146,7 @@ These fire at specific moments in the project lifecycle. **Surface them proactiv
 - **Using `fimo deploy --publish` casually** — `--publish` makes the site live to the public. Plain `fimo deploy` (preview) is the default. Use `--publish` only when the user says "ship it" / "go live" / "publish".
 - **Bare `fimo init` in a non-interactive shell** — will hang. Always pass `[dir]`, `--no-install` (or `--install`), `--no-skills` (or `--skills`), and `--org`/`--agents` as needed explicitly when scripted.
 - **Hardcoding content / strings / images in code** — that's what schemas, `t()`, and the media library are for. See the `fimo-code` skill's anti-patterns.
-- **Adding another deploy tool (Vercel, Netlify, Cloudflare Pages)** — Fimo handles deploys; don't bolt another platform on.
+- **Adding another deploy tool**. Fimo handles deploys; don't bolt another platform on.
 - **Committing secrets** — hidden values use `fimo secrets`; public browser-safe values use `fimo vars`. Local env files are ignored and must not become deploy inputs.
 - **Hardcoding tokens in flags** — use the credentials written by `fimo login` (one file per backend at `~/.config/fimo/credentials/<host>-<hash>.json`).
 - **Treating the daily allowance as extra credits** — the allowance section appears only for legacy Premium organizations, and `fimo credits` already includes its spendable credits in "Available now"; it is accounting context, not an amount to add.

package/assets/skills/fimo-cli/references/agent-setup.md

@@ -33,6 +33,7 @@ fimo login                             # connect your account when ready
 ```bash
 fimo skills install                            # interactive: pick agents, install the global bootstrap
 fimo skills install --agents=claude-code,cursor   # explicit list
+fimo skills install --agents=hermes               # Hermes default profile, or the active HERMES_HOME
 fimo skills install -a claude-code -a cursor      # repeatable form
 fimo skills sync                               # re-ensure the bootstrap + clean up stale old skills
 fimo skills uninstall                          # remove the global bootstrap
@@ -80,7 +81,7 @@ Every command that takes agents accepts the same selection inputs:
 - `-a claude-code -a cursor` — repeatable short form
 - No flag → interactive multi-select. The picker has two sections:
   - **Universal** — agents that read `AGENTS.md` natively (Codex, OpenCode, Aider, …). Always covered, not toggleable.
-  - **Additional** — agents that get the global bootstrap skill installed. The 6 popular ones (`claude-code`, `cursor`, `codex`, `opencode`, `windsurf`, `gemini-cli`) appear at the top of an 8-item scrollable viewport; the full list of 50+ supported agents is below the fold. Agents already set up on the machine are pre-checked.
+  - **Additional** — agents that get the global bootstrap skill installed. The popular ones (`claude-code`, `cursor`, `codex`, `opencode`, `windsurf`, `gemini-cli`, `hermes`) appear at the top of the picker; the full list of supported agents remains available below them. Agents already set up on the machine are pre-checked.
 - `--agents=none` (only `fimo init`) — skip the global skill entirely.
 
 In headless contexts (CI, agent-spawned commands), pass the flag explicitly. Env-var detection (only Claude Code's `CLAUDECODE` / `CLAUDE_CODE_ENTRYPOINT`) silently targets `claude-code` if the flag is omitted; every other agent must be named explicitly with `--agents` in a headless shell, or the command exits with "No agents detected and no --agents flag passed."

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

@@ -271,7 +271,19 @@ fimo agents runs <name> [--limit <n>] [--cursor <cursor>] [--all-pages] [--branc
 fimo agents report <name> [--session <id>] [--branch <branch>] [--project <id>] [-C <dir>]
 ```
 
-- **`run <name>`** — fire the agent's `manual` trigger on the server; prints a `sessionId` on success. Skips with `no-manual-trigger` when `config.yaml` declares none, or `trigger-not-wired` when the push-to-main sync recorded the trigger but refused to wire it (see the wiring note below). **Pre-flight drift check**: if `.fimo/agents/<name>/` (or the legacy root bundle) has uncommitted git changes, the command refuses — the server would dispatch the _deployed_ version, so deploy first. Pass `--skip-drift-check` to dispatch the deployed bundle anyway. Defaults `--branch` to `main`.
+- **`run <name>`** — fire the agent's `manual` trigger on the server; prints a `sessionId` on success. A refusal you must act on exits **1** with a stable code (`--json` puts it in `error.code`, and the raw server reason in `error.details.skipped`):
+
+  | Code                        | Means                                                                           | Fix                                               |
+  | --------------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------- |
+  | `AGENT_NOT_DEPLOYED`        | no bundle for this agent on `main`                                              | `fimo deploy`                                     |
+  | `AGENT_CONFIG_INVALID`      | the deployed bundle does not parse, so the sync registered none of its triggers | `fimo agents validate <name>`, fix, `fimo deploy` |
+  | `NO_MANUAL_TRIGGER`         | the deployed `config.yaml` really declares no `manual` trigger                  | add `- type: manual`, `fimo deploy`               |
+  | `MANUAL_TRIGGER_NOT_SYNCED` | `main` declares it, the background sync has not registered it yet               | wait a few seconds, retry                         |
+  | `TRIGGER_NOT_WIRED`         | registered but not live (see the wiring note below)                             | `fimo agents list` for the reason                 |
+  | `INSUFFICIENT_CREDITS`      | the org is under the credit floor a run needs                                   | `fimo credits`                                    |
+
+  A refusal that clears on its own (`agent-paused`, `run-in-progress`, `task-branch-budget`) exits **0** and prints `Dispatch was skipped: <reason>`. **Pre-flight drift check**: if `.fimo/agents/<name>/` (or the legacy root bundle) has uncommitted git changes, the command refuses — the server would dispatch the _deployed_ version, so deploy first. Pass `--skip-drift-check` to dispatch the deployed bundle anyway. Defaults `--branch` to `main`.
+
 - **`runs <name>`** — list past run sessions for the agent in a compact table (id, started, duration, status, trigger, Branch, credits — settled credit consumption, `—` until a run settles). Default `--limit 20`; `--branch` filters to one Branch. The response uses the canonical `branch` field.
 - **`report <name>`** — print a run's structured **report**: its durable outcome summary (for a read-only agent like `seo-audit` this _is_ the audit; for a write agent it's a "what I changed" summary). A run that returns plain text without calling `finish_run` receives a small structured fallback document. With no `--session`, the most recent run for `<name>` is used (combine with `--branch` to scope); `--session <id>` targets a specific run. Output is projected Markdown, so it stays readable in the terminal and pipes cleanly (e.g. `fimo agents report seo-audit | glow`). If the run hasn't finished, or produced no report, it says so (and shows the stop reason when there is one).
 

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

@@ -36,7 +36,7 @@ fimo --branch <name> <command>  # peek at another Branch for one command (does n
 | `fimo diff [from] [to]` | `git diff`          | Two-Branch diff across all surfaces. Defaults `from` = current Branch, `to` = `main`. `--surface <name>` limits to one; `--json`; `--no-color`.                              |
 | `fimo status`           | `git status`        | Multi-surface status for the current Branch vs its parent. See below.                                                                                                        |
 | `fimo merge <from>`     | `git merge`         | Merge another Branch into the current one (multi-surface, atomic, interactive conflict resolver). See below.                                                                 |
-| `fimo publish`          | —                   | Publish the synced Production source revision with a stable Fimo publication ID. See "Publishing" below.                                                                     |
+| `fimo publish`          | —                   | Publish the revision already on the Fimo remote (no push) with a stable Fimo publication ID. See "Publishing" below.                                                         |
 
 All of these accept the global `--branch` override. `diff`, `status`, `merge`, and `publish` additionally accept `-C, --cwd <dir>` to point at a project directory.
 
@@ -98,10 +98,10 @@ Syncs the current Branch's data plane from its parent (or `--from <ancestor>`).
 
 Two different "go live" mechanisms — don't confuse them:
 
-- **`fimo publish [--label <text>] [--notes <md>]`** — publishes the synced Production source revision. Fimo assigns the immutable publication ID; the label and notes are optional annotations. `--skip-validate` is an operator override.
-- **`fimo deploy --publish`** — the project-publish path. Pushes the current Production source code and flips the project live in one shot. See `references/deploy.md`.
+- **`fimo publish [--label <text>] [--notes <md>]`** — publishes the revision already on the Fimo remote without pushing. Fimo assigns the immutable publication ID; labels and notes are optional annotations. `--skip-validate` is an operator override.
+- **`fimo deploy --publish`** — pushes the current Production source Branch and flips the project live. See `references/deploy.md`.
 
-Use `fimo publish` when the Production source Branch is already synced; use `fimo deploy --publish` when the local revision still needs to be pushed first. Both only run from the configured Production source Branch. Existing projects use `main`.
+Choose `fimo deploy --publish` when local changes need to go live; choose `fimo publish` when the remote revision is the intended release. Both only run from the configured Production source Branch. Existing projects use `main`.
 
 ## Anti-patterns
 

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

@@ -54,7 +54,7 @@ Use the publication ID returned by the failed command: run `fimo publish inspect
 A failed `fimo deploy --json` names the cause in `error.details.failure_code` and the phase in `error.details.phase`: `pull` (Git synchronization into the sandbox), `install` (dependency install), `restart` (dev-server start), or `readiness` (the final preview check); `acquire` and `sync-env` are the sandbox and environment steps before them. When the failed process produced output, the same error carries `error.details.exit_code` and a bounded, redacted `error.details.log_tail` (newest line last). Read that tail first: it is the failed process's own output, and a replacement sandbox that failed is discarded, so `fimo logs` shows the preview that is still serving rather than the attempt that failed. The top-level codes remain compatible:
 
 - `SANDBOX_SYNC_FAILED` — the revision never became ready. Fix what the tail reports (a manifest or lockfile for `install`, the Git state for `pull`), then deploy again. When `error.details.failure_code` is `install_policy_blocked`, follow the typed repair in `error.details.repair`.
-- `PREVIEW_NOT_READY` — the revision landed and the dev server never served the page. Fix what the tail reports; when there is no tail, read `fimo logs --json`.
+- `PREVIEW_NOT_READY` — the revision landed and the preview never proved ready. `error.message` names what the readiness probe last saw: a dev server that died, or the optimized dependency the public preview route was still delivering and what the dev server said about it over loopback. Fix what the tail reports; when there is no tail, act on the message before reading `fimo logs --json`, which shows a dev server that may be healthy.
 
 `--no-wait` skips only the final readiness check. Pull, install, and dev-server failures are still reported with the same fields.
 
@@ -123,12 +123,9 @@ There's nothing special about this — it's the same `fimo deploy` you'd run lat
 
 ## Publishing: `fimo deploy --publish` vs `fimo publish`
 
-Two different "go live" mechanisms — pick deliberately:
+Use `fimo deploy --publish` to push and publish local changes. Use `fimo publish` to publish the revision already on the Fimo remote without pushing. Both target the configured Production source Branch.
 
-- **`fimo deploy --publish`** — push what's on the Production source Branch now and flip the project live in one shot. The simple "ship it" path. Runs from that Branch only.
-- **`fimo publish [--label <text>] [--notes <md>]`** — publish the synced Production source revision without pushing. Fimo assigns the immutable publication ID; a label and notes are optional human annotations. See `references/branches.md`.
-
-When unsure, use `fimo deploy --publish` so the local revision is pushed before it goes live. Use `fimo publish` when the Production source Branch is already synced.
+Check the reported source commit and warnings before reporting completion. If local work is excluded or the built commit cannot be confirmed, follow the CLI's hint.
 
 ## Markdown for AI agents
 

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

@@ -51,8 +51,8 @@ Global flags: `--project <id>` / `-C, --cwd <dir>` for project resolution, `--or
 When a user says "I want to change my website's URL," ask which case fits:
 
 - **"It's fine as-is, just nicer"** → `rename-default` or `suggest-default`. Free, instant, no DNS.
-- **"I own example.com already"** → `add example.com`. Premium. They configure CNAME at their registrar.
-- **"I want to buy a domain"** → `search` → `pricing` → `buy`. Premium + the registered-domains feature flag has to be on (it's not enabled in every environment).
+- **"I own example.com already"** → `add example.com`. Pay as you go or higher. They configure CNAME at their registrar.
+- **"I want to buy a domain"** → `search` → `pricing` → `buy`. The registered-domains feature flag and an eligible plan must be on (the flag is not enabled in every environment).
 
 If they aren't sure, run `fimo domains suggest-default` first — it's free, takes one step, and a good fallback if they don't want to commit to a domain purchase.
 
@@ -60,7 +60,7 @@ If they aren't sure, run `fimo domains suggest-default` first — it's free, tak
 
 After the automatic first-preview deploy on a newly created project, offer a cleaner free `*.fimo.site` URL before the first public publish when there is no custom domain and the current default slug still looks generated or was never explicitly chosen. Choosing it now lets the first public launch use the clean URL. Skip the offer if the user already chose the default slug, attached a custom domain, or declined.
 
-The default URL is free and needs no DNS. A custom domain is the separate Premium workflow above. A default slug can be reserved before publication, but it returns "Project Not Found" until the site is published. Renaming changes the address that will become public, so never silently claim a suggestion:
+The default URL is free and needs no DNS. A custom domain uses the Pay as you go (or higher) workflow above. A default slug can be reserved before publication, but it returns "Project Not Found" until the site is published. Renaming changes the address that will become public, so never silently claim a suggestion:
 
 1. Run `fimo domains suggest-default --base "<brand>" --json` to get candidates.
 2. Show the candidates and ask the user to choose one explicitly.
@@ -72,7 +72,7 @@ Choosing the slug does not publish the site. The first successful `fimo deploy -
 
 The CLI never charges directly. Two distinct money paths:
 
-1. **Premium subscription** — gates `add`, `buy`, `owned`, `refresh`, `remove` for custom domains. The user upgrades through the Fimo web app (Hyperline-hosted checkout). When a free user runs a gated command they get a 403 with the upgrade URL — surface it as-is to the user.
+1. **Pay as you go or higher** — gates custom-domain operations. A valid card activates Pay as you go through the Fimo web app (Hyperline-hosted checkout). When a Free user runs a gated command they get a 403 with the billing URL; surface it as-is to the user.
 2. **Domain registration** — `fimo domains buy` creates a Hyperline invoice with `payment_method_strategy: 'external'` and returns a `checkoutUrl`. The user opens that URL in a browser to pay. **No money moves until they pay the invoice.** That's why `--yes` on `buy` is safe: it queues an invoice; the human still has to consent at checkout.
 
 Domain prices come from name.com via the registrar reseller. They vary by TLD and can change. Pricing is in USD (cents in the API, formatted as dollars in CLI output).
@@ -121,7 +121,7 @@ Propagation: typically 15–30 minutes, up to 48 hours rarely.
 ## Common errors
 
 - **"Project Not Found" on a new URL or custom domain.** The route exists but the site was never published — run `fimo deploy --publish`.
-- **"Custom domains require a Premium plan."** — the operation is paid; the message includes the org billing URL. Free users can still run `list`, `rename-default`, `suggest-default`, `search`, and `pricing`.
+- **"Custom domains require Pay as you go or higher."** — add a card at `/app/billing`, then retry. Free users can still run `list`, `rename-default`, `suggest-default`, `search`, and `pricing`.
 - **"Domain purchase is not enabled on this account."** — the registered-domains feature flag is off on this API instance. Contact support.
 - **"This URL is not available."** — slug or hostname collides with another project or is reserved.
 - **"That's a Fimo-owned domain."** — user tried `add <something>.fimo.site`. Use `rename-default` instead.

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

@@ -24,7 +24,7 @@ fimo forms delete <id>            # delete a form
 
 Notification recipients for form submissions are configured in the Fimo web UI, not via CLI.
 
-## Reading submissions
+## Reading and deleting submissions
 
 After a form is live and users have filled it out, inspect submissions from the terminal:
 
@@ -32,6 +32,7 @@ After a form is live and users have filled it out, inspect submissions from the
 fimo forms submissions list <formIdOrName> [--limit 50] [--cursor CURSOR] [--all-pages] [--search "<q>"] [--sort asc|desc]
 fimo forms submissions get  <formIdOrName> <submissionId>
 fimo forms submissions stats <formIdOrName>
+fimo forms submissions delete <formIdOrName> <submissionId>
 ```
 
 The list response includes `nextCursor` when another page exists. `--offset` remains a compatibility alias for existing scripts.
@@ -39,7 +40,8 @@ The list response includes `nextCursor` when another page exists. `--offset` rem
 - `<formIdOrName>` accepts either the form's UUID or its `name` (the same name in the JSON file). Names that don't resolve to exactly one form return an error.
 - `list` returns `{ data: [...], total }`. Newest-first by default; pass `--sort asc` to reverse.
 - `search` matches against submission contents server-side.
-- All three are read-only — there's no CLI command to create or delete a submission. Submissions are created by the form intake endpoint when a user submits the published site's form.
+- `delete` removes one submission permanently and prints the deleted record. There is no undo, no bulk delete, and no confirmation prompt — confirm with the user before running it. An unknown or already-deleted id fails with `Submission not found`.
+- There's no CLI command to create a submission. Submissions are created by the form intake endpoint when a user submits the published site's form.
 
 Use this when the user asks "who filled out the contact form?", "how many signups did we get this week?", or "show me the latest submission". For older submissions or bulk export, point them at the dashboard — there's no batch export endpoint yet.
 

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

@@ -57,9 +57,9 @@ them are present.
 {
   "redirects": [
     {
-      "source": "/(.*)",
-      "has": [{ "type": "header", "key": "x-vercel-ip-country", "value": "GB" }],
-      "destination": "/uk/:path*"
+      "source": "/offers",
+      "has": [{ "type": "header", "key": "x-promo", "value": "summer" }],
+      "destination": "/summer-sale"
     }
   ],
   "rewrites": [
@@ -74,12 +74,13 @@ them are present.
 
 | `type`   | Matches on                                           |
 | -------- | ---------------------------------------------------- |
-| `header` | a request header, including CDN-injected geo headers |
+| `header` | a request header                                     |
 | `cookie` | a cookie                                             |
 | `query`  | a query parameter                                    |
 | `host`   | the hostname the request arrived on — takes no `key` |
 
 Omit `value` to match on presence alone, as the `consent` cookie above does.
+The redirect example requires the request to include `x-promo: summer`.
 
 **Prefer doing this in the application when it can.** Middleware, a loader, or a
 server component can be run and tested locally; a condition here only takes

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

@@ -24,7 +24,7 @@ JSON output contains only the Branch identity and hosted URL:
     "project_id": "prj_abc",
     "branch": "main",
     "env": "main",
-    "preview_url": "https://fimo-preview-example.vercel.app"
+    "preview_url": "https://preview.example.com"
   }
 }
 ```

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

@@ -43,10 +43,10 @@ fimo rename "<Site Name>"        # local edit: set seo.siteName in the project c
 
 ## Publish commands
 
-| Command                 | Effect                                                                     |
-| ----------------------- | -------------------------------------------------------------------------- |
-| `fimo deploy --publish` | Push the current Production source + flip the project live in one shot.    |
-| `fimo projects publish` | Flip the project live (no git push).                                       |
-| `fimo publish`          | Flip the synced Production source revision live; optional label and notes. |
+| Command                 | Effect                                                                  |
+| ----------------------- | ----------------------------------------------------------------------- |
+| `fimo deploy --publish` | Push the current Production source + flip the project live in one shot. |
+| `fimo projects publish` | Flip the project live (no git push).                                    |
+| `fimo publish`          | Flip the revision already on the Fimo remote live (no git push).        |
 
 See `references/deploy.md` and `references/branches.md` for the full picture.

package/assets/skills/fimo-cli/references/site-checks.md

@@ -0,0 +1,73 @@
+# Site checks
+
+Start from a URL the agent can actually reach, then use the inspection tools
+available in its runtime. This reference owns Fimo target selection and the
+meaning of the evidence. Browser and audit tools own their commands.
+
+## 1. Pick a target and name it
+
+- An already-running local development server.
+- An existing hosted Fimo preview: run `fimo preview url --json` and use
+  `data.sandbox_url` (see `references/preview.md`).
+- A URL the user supplied, including an existing published site.
+
+Never run `fimo deploy` just to retrieve a preview URL. Do not run `fimo
+publish` or `fimo deploy --publish` merely to create a measurement target.
+For any other deployment or publishing decision, follow the current run's
+authority rules and `references/deploy.md`.
+
+A local server or preview can prove how that target renders and behaves. Its
+timings describe that environment, not the published site. A supplied public
+URL can describe the live version, but one synthetic run is not field data.
+
+## 2. Use the tools that exist
+
+Inspect the available tools and skills before choosing a method.
+
+- If `agent-browser` is available, load its skill and version-matched `core`
+  guidance before using it.
+- Otherwise use equivalent browser automation, accessibility, HTTP, network,
+  profiling, or performance tools exposed by the current runtime.
+- HTTP-only tools can prove fetchability, status, headers, and raw content.
+  They cannot prove visual layout, interactions, or accessibility.
+- Fimo CLI does not produce Lighthouse reports, and `agent-browser` Web Vitals
+  are not Lighthouse scores. If the environment provides Lighthouse, use its
+  own guidance and name the target. If it does not, report that limitation and
+  use only measurements that can actually run.
+
+## 3. Pick the lens the question needs
+
+| The user asks                                                   | Evidence to obtain                            |
+| --------------------------------------------------------------- | --------------------------------------------- |
+| Does the page render, is the copy right, is an image broken     | browser snapshot and screenshot               |
+| Does this flow work, does the form submit, is the console clean | browser interaction and console output        |
+| Is it accessible, WCAG, contrast, labels, alt text              | accessibility audit                           |
+| Why does it feel slow, LCP, CLS, INP, TTFB, hydration           | Web Vitals and, when needed, a profiler trace |
+| Wrong data, a failing request, a slow API, response headers     | network log, HAR, or HTTP response            |
+| Does the page expose its own tools to agents                    | WebMCP page tools, when supported             |
+| What is its Lighthouse score                                    | an actual Lighthouse run                      |
+
+Run only the lenses the question needs. Two lenses with clear evidence beat a
+sweep of all seven.
+
+## 4. Report honestly
+
+- State the target URL and its kind (hosted preview, dev server, supplied URL),
+  the viewport, and when the checks ran.
+- Give the observed values with their units and how many runs produced them.
+  One run is one run; say so.
+- Keep what you observed separate from what you inferred, and list the lenses
+  you did not run.
+- Never claim a check that did not run. If the environment blocked it (no
+  browser, an expired sandbox, a target that would not load), report what
+  blocked it.
+
+For visitor behavior on the published site (pageviews, top pages, sources),
+use `references/analytics.md`. It reports real traffic rather than one browser
+run.
+
+## See also
+
+- `references/preview.md` for preview destinations and sandbox URL expiry.
+- `references/deploy.md` for preview deployment and publishing authorization.
+- `references/analytics.md` for published-site traffic.

package/assets/skills/fimo-code/SKILL.md

@@ -72,6 +72,7 @@ Each reference defines one package contract. Fetch it when the task reaches that
 - Locale ownership and framework handoff → `references/locales.md`
 - Upgrading a React Router app that imports `fimo/react-router/routes` → `references/migrations/react-router-route-ownership.md`
 - Astro connector and output/adapter contract → `references/frameworks/astro.md`
+- Astro/SvelteKit SEO or a new content route → the framework reference, then `references/frameworks/seo-head.md` for value ownership and edit-and-render acceptance
 - Framework detection, production routing, and hosting adapters → `references/frameworks/hosting.md`
 - Major visual work → `references/design.md`
 

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

@@ -6,7 +6,9 @@ This file covers media fields and the Fimo image components.
 
 ## Media field values
 
-A media field stores a reference to an asset, not a copy of the asset metadata. Write the value returned by upload or generation:
+For single-image and gallery schemas, see `references/content/schema.md`.
+
+Each media object stores a reference to an asset, not a copy of the asset metadata. Use the value returned by upload or generation:
 
 ```json
 {
@@ -31,7 +33,7 @@ const withAsset = await Post.getBySlug('hello', { populate: ['cover'] });
 
 `populate` takes top-level field names. A blocks field populates every media value inside it. One lookup covers all selected media in the response. Media inside a populated reference target stays a reference. Use `fimo assets open <id> --download` to inspect the source file.
 
-Generated reads wrap media in `FimoMedia`. Its `id`, `alt`, `name`, `mime`, `width`, and `height` can be absent. A populated value has the current facts when the asset resolves; missing or external assets stay unchanged. `source` is internal. Pass the whole value to `<Image>` or `<Video>`.
+Generated reads wrap each media object in `FimoMedia`. Its `id`, `alt`, `name`, `mime`, `width`, and `height` can be absent. A populated value has the current facts when the asset resolves; missing or external assets stay unchanged. `source` is internal. Pass one `FimoMedia` value, not the array, to `<Image>` or `<Video>`.
 
 ## Rendering in application code
 

package/assets/skills/fimo-code/references/best-practices/next.md

@@ -38,5 +38,3 @@ Use `instant = true` to find blocking code, then verify with `next build` and `n
 - Avoid duplicate content reads between `generateMetadata` and the page.
 
 Verify valid and missing slugs, canonical and initial HTML, shipped JavaScript, duplicate reads, image sizing, instant shell rendering, streaming, freshness, and bounded prefetching.
-
-Sources: [Instant Navigations](https://nextjs.org/blog/next-16-3-instant-navigations), [`partialPrefetching`](https://github.com/vercel/next.js/blob/canary/docs/01-app/03-api-reference/05-config/01-next-config-js/partialPrefetching.mdx), and [`instant`](https://github.com/vercel/next.js/blob/canary/docs/01-app/03-api-reference/03-file-conventions/02-route-segment-config/instant.mdx).

package/assets/skills/fimo-code/references/content/schema.md

@@ -14,6 +14,7 @@ Write one schema per `src/schemas/<Uid>.json`. The PascalCase filename must matc
     "publishedAt": { "type": "date" },
     "featured": { "type": "boolean" },
     "cover": { "type": "media" },
+    "gallery": { "type": "media", "multiple": true },
     "metadata": { "type": "json" },
     "author": { "type": "reference", "target": "Author" },
     "contributors": { "type": "reference", "target": "Author", "many": true }
@@ -80,11 +81,13 @@ Never declare `id`, `entryId`, `documentId`, `slug`, `locale`, `createdAt`, `upd
 | `boolean`   | boolean                    | flags                                    |
 | `date`      | ISO date string            | calendar days; loose about the form      |
 | `datetime`  | ISO instant with offset    | exact moments (`2026-08-13T09:30:00Z`)   |
-| `media`     | media object or array      | images, video, files                     |
+| `media`     | media object by default    | images, video, files                     |
 | `json`      | JSON                       | structured metadata                      |
 | `reference` | `{ "id": "..." }` or array | links to another schema                  |
 | `blocks`    | ordered object array       | nested/repeatable sections               |
 
+Set `multiple: true` on a media field for an array, even with one image. See `references/assets.md` for the object shape.
+
 A `datetime` value must carry `Z` or `±HH:MM`; a bare day or a naive local time is rejected. Render it with `<DateTime>`, which keeps the whole instant in the `<time datetime>` attribute, and a `date` with `<Date>`. `unique` is not supported on `datetime`.
 
 An enum string uses `options`; its optional `default` must be one of them:

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

@@ -44,10 +44,10 @@ Reference sites to anchor the aesthetic direction. Pull any well-known site, bra
 | Category                 | Example Anchors                                                                                           | Quality Bar                                                                |
 | ------------------------ | --------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
 | **Creative / Agency**    | Awwwards, FWA, CSS Design Awards, Pentagram, Sagmeister & Walsh, Active Theory, Fantasy Interactive, Resn | Would it win Awwwards SOTD? Would Pentagram put this in their portfolio?   |
-| **SaaS / Product**       | Linear, Vercel, Stripe, Notion, Figma, Raycast, Arc Browser, Supabase, Mercury, Clerk, Loom, Pitch        | Is it Linear-polished? Would a developer tweet "their site is so clean"?   |
+| **SaaS / Product**       | Linear, Stripe, Notion, Figma, Raycast, Arc Browser, Supabase, Mercury, Clerk, Loom, Pitch                | Is it Linear-polished? Would a developer tweet "their site is so clean"?   |
 | **Editorial / Blog**     | Medium, Substack, The Verge, NYT, The Atlantic, Monocle, It's Nice That, Eye on Design, Wired             | Would The Verge's design team respect this? Is it magazine-worthy?         |
 | **E-commerce**           | Apple Store, Shopify Dawn, Gumroad, Everlane, Glossier, SSENSE, Mr Porter, Mejuri, Allbirds               | Does it feel Apple Store premium? Would you trust buying from this?        |
-| **Documentation**        | Stripe Docs, Tailwind Docs, Vercel Docs, Supabase Docs, Prisma Docs, Algolia Docs, Clerk Docs             | Is it Stripe Docs clear? Can a developer find what they need in 3 seconds? |
+| **Documentation**        | Stripe Docs, Tailwind Docs, Supabase Docs, Prisma Docs, Algolia Docs, Clerk Docs                          | Is it Stripe Docs clear? Can a developer find what they need in 3 seconds? |
 | **Personal / Portfolio** | Read.cv, Paco Coursey, Josh Comeau, Rauno Freiberg, Brian Lovin, Lee Robinson, Linus Rogge                | Would Read.cv feature this? Is it memorable and distinctly personal?       |
 | **Corporate**            | Apple, Stripe, Airbnb, Slack, Square, Intercom, Dropbox, Zendesk                                          | Does it feel Airbnb-trustworthy? Premium but not flashy?                   |
 | **Dashboard**            | Linear, Figma, Raycast, Retool, Rows, Height, Airtable, Coda                                              | Is it Linear-efficient? Dense but never cluttered?                         |

package/assets/skills/fimo-code/references/frameworks/astro.md

@@ -1,6 +1,6 @@
 # Astro integration
 
-Use this reference for an existing Astro application. The application keeps its route files, output mode, adapter, locale system, links, `<html lang/dir>`, and SEO. Fimo connects content, labels, native rendering, preview, and hosting.
+Use this reference for an existing Astro application. The application keeps its route files, output mode, adapter, locale system, links, `<html lang/dir>`, and per-page SEO. Fimo connects content, labels, native rendering, preview, hosting, and the site-wide SEO defaults from Studio's Settings → SEO.
 
 ## Setup
 
@@ -90,6 +90,42 @@ browser values before submitting. Do not import the server form module into a
 client island; add a project endpoint if the form is intentionally browser-
 submitted.
 
+## SEO defaults
+
+Resolve the current route, apply page values, then convert to native attributes.
+New projects have this in `src/layouts/Base.astro`. Existing apps should extend
+their current head component, preserving unrelated metadata.
+
+```astro
+---
+import { resolveSeoForPath, toSeoHead } from 'fimo/seo';
+import config from '../../.fimo/config.json';
+
+const { seo = resolveSeoForPath(Astro.url.pathname, config) } = Astro.props;
+const canonicalUrl = seo?.url ? new URL(Astro.url.pathname, seo.url).href : undefined;
+const head = toSeoHead(seo, { canonicalUrl });
+---
+<head>
+  <title>{head.title ?? 'My site'}</title>
+  {head.meta.map((attributes) => <meta {...attributes} />)}
+  {head.links.map((attributes) => <link {...attributes} />)}
+</head>
+```
+
+For a content page, resolve after loading the entry and pass the final values
+to the layout: `const seo = resolveSeoForPath(Astro.url.pathname, config, { article })`,
+then `<Base lang={locale} seo={seo}>`. Route templates can read
+`{{article.title}}`. Apply app-owned overrides before conversion so the title,
+Open Graph and Twitter tags agree.
+
+The example canonical policy fits a root-hosted site. Preserve the app's own
+production domain, base path and trailing-slash policy. Omitting the converter's
+`canonicalUrl` omits canonical and `og:url`; `seo.url` alone is only a site base.
+Imported config changes need sync and rebuild/redeploy. Content freshness
+follows the route's rendering and caching policy.
+
+Full field and composition contract: read `references/frameworks/seo-head.md` when changing SEO.
+
 ## Static and on-demand rendering
 
 Keep the application's per-route rendering choice:

package/assets/skills/fimo-code/references/frameworks/compatibility.md

@@ -23,11 +23,11 @@ Vite plugin from `fimo-react-router/vite`, which builds on the installed
 SvelteKit installs `fimo` and `fimo-sveltekit`. Move a project to a new release
 with `fimo update <exact-version>`, which keeps the whole set on one version.
 
-React projects pinned before framework companions shipped keep their legacy
-runtime imports. The current CLI generates content clients through `fimo/ui`
-for those projects and does not require `fimo-react`. Run `fimo update
-<exact-version>` only when the developer chooses to move the project to a split
-runtime release.
+React and Next.js projects pinned before framework companions shipped keep
+their legacy runtime imports. The current CLI generates content clients through
+`fimo/ui` or `fimo/next` for those projects and does not require `fimo-react`
+or `fimo-next`. Run `fimo update <exact-version>` only when the developer
+chooses to move the project to a split runtime release.
 
 `runtime.framework` must match a dependency in `package.json`; a profile the
 code does not use fails the production build. Shape and rules: `hosting.md`

package/assets/skills/fimo-code/references/frameworks/hosting.md

@@ -64,6 +64,28 @@ local environment alias by hand.
 projects. Do not add it to new code, env files, setup instructions, or migration
 plans.
 
+## `hosting`: how the deployed site is served
+
+Declare hosting rules only in `.fimo/config.json#hosting`, not provider
+deployment files. Run `fimo validate` to catch unsupported keys and malformed rules.
+
+| Key             | Shape                                                            |
+| --------------- | ---------------------------------------------------------------- |
+| `rewrites`      | `{ source, destination }`, URL unchanged                         |
+| `redirects`     | `{ source, destination, permanent?, statusCode? }`               |
+| `headers`       | `{ source, headers: [{ key, value }] }`, response headers        |
+| `cleanUrls`     | Serve `/about` for `/about.html` and redirect the extension away |
+| `trailingSlash` | `true` requires a trailing slash, `false` forbids one            |
+
+Rewrites, redirects, and header rules accept `has` / `missing` conditions:
+`header`, `cookie`, and `query` require `key`; `host` requires only `value`.
+
+Redirects default to temporary. Use `permanent: true` only for lasting moves;
+browsers cache it. `statusCode`, one of 301, 302, 307, 308, overrides `permanent`.
+
+Verify rules on a hosted Preview or published site, not a local dev server.
+Legacy static hosting ignores them; contact support if deployed rules have no effect.
+
 ## React Router framework mode
 
 For the supported client-rendered setup, keep `ssr: false` and add Fimo's
@@ -111,5 +133,4 @@ Astro has a dedicated connector — load `references/frameworks/astro.md` before
 editing an Astro config.
 
 `.fimo/config.json#routes` is the Studio page catalog, not deployment routing.
-Never generate hosting rewrites from it. If a project already has a
-provider-specific deployment file, preserve it; that file remains authoritative.
+Never generate hosting rewrites from it.

package/assets/skills/fimo-code/references/frameworks/next/app-router.md

@@ -109,24 +109,10 @@ Do not add `'use client'` to a page solely because Fimo is present. Keep promise
 
 ## Metadata
 
-Fimo owns the site-wide defaults; the application owns per-page overrides. Keep (or add) the starter wiring in the root layout — it maps `.fimo/config.json#seo` (Studio's Settings → SEO: title, description, favicon, share image, robots, theme color, canonical) onto Next `Metadata`/`Viewport`:
-
-```ts
-import { buildFimoMetadata, buildFimoViewport } from 'fimo-next';
-
-export const generateMetadata = () => buildFimoMetadata();
-export const generateViewport = () => buildFimoViewport();
-```
-
-If the root layout lacks this wiring, add it (updating the fimo packages if `fimo-next` does not export the helpers); without it, Settings → SEO never reaches the rendered head.
-
-Per-page `metadata`/`generateMetadata` exports override the defaults field by field. Resolve labels/content on the server and convert tracked strings only where Next expects primitives:
-
-```ts
-export async function generateMetadata() {
-  const labels = await getLabels();
-  return { title: String(labels.t('seo.home.title')) };
-}
-```
-
-Do not expect `FimoProvider` to inject SEO, routes, language, or direction.
+When creating a site, adding a route, or integrating SEO, load
+`references/frameworks/next/seo.md` (`--ref frameworks/next/seo`). Keep root
+global defaults separate from explicit Home and route SEO. Reuse the app's
+established route integration for new pages; a dynamic route module covers all
+its instances. Next replaces nested metadata objects, not their individual
+fields. Preserve app-owned policies and image routes. `FimoProvider` does not
+inject SEO.