fimo 0.15.0 → 0.16.0-experimental.1

package/assets/astro/components/DateTime.astro

@@ -0,0 +1,22 @@
+---
+import { getFimoSource } from 'fimo/astro';
+
+interface Props {
+  value: globalThis.Date | String | string | number | null | undefined;
+  locale?: string;
+  options?: Intl.DateTimeFormatOptions;
+  [key: string]: unknown;
+}
+
+const { value, locale, options, ...props } = Astro.props;
+const rawValue = value instanceof String ? value.toString() : value;
+const date = rawValue == null ? null : new globalThis.Date(rawValue as string | number | globalThis.Date);
+const validDate = date && !Number.isNaN(date.getTime()) ? date : null;
+// The whole instant, not just the day: a `datetime` field exists to name a
+// moment, and truncating it here would throw the time away on every page.
+const dateTime = validDate?.toISOString();
+const content = validDate?.toLocaleString(locale, options ?? { dateStyle: 'medium', timeStyle: 'short' });
+const source = getFimoSource(value);
+---
+
+{validDate && <time {...props} datetime={dateTime} data-fimo-source={source}>{content}</time>}

package/assets/astro/components/index.d.ts

@@ -1,5 +1,6 @@
 export { default as Boolean } from './Boolean.astro';
 export { default as Date } from './Date.astro';
+export { default as DateTime } from './DateTime.astro';
 export { default as Image } from './Image.astro';
 export { default as Json } from './Json.astro';
 export { default as RichText } from './RichText.astro';

package/assets/astro/components/index.js

@@ -1,5 +1,6 @@
 export { default as Boolean } from './Boolean.astro';
 export { default as Date } from './Date.astro';
+export { default as DateTime } from './DateTime.astro';
 export { default as Image } from './Image.astro';
 export { default as Json } from './Json.astro';
 export { default as RichText } from './RichText.astro';

package/assets/content-templates/forms/react.eta

@@ -78,7 +78,7 @@ const fileFieldKeys = Object.entries(form.fields)
 
 import { z } from "zod";
 
-export const FORM_ID = <%= quote(form.id ?? 'undefined') %>;
+export const FORM_ID = <%= form.id ? quote(form.id) : 'undefined' %>;
 
 export const <%= form.pascal %>Schema = z.object({
 <% Object.entries(form.fields).forEach(([key, field]) => { -%>
@@ -154,8 +154,8 @@ export async function submit<%= form.pascal %>(data: <%= form.pascal %>Data): Pr
   status: number;
   errors?: Record<string, string>;
 }> {
-  if (!FORM_ID || FORM_ID === "undefined") {
-    throw new Error(`Form "${FORM_ID || "unknown"}" has not been pushed. Run fimo forms push first.`);
+  if (!FORM_ID) {
+    throw new Error(<%= quote(`Form "${form.name}" has not been pushed. Run fimo forms push first.`) %>);
   }
 
 <% if (hasFileFields) { -%>

package/assets/content-templates/shared/types.eta

@@ -97,6 +97,7 @@ function getTypeForField(field) {
     case 'boolean':
       return 'FimoBoolean';
     case 'date':
+    case 'datetime':
       return 'string';
     case 'json':
       return 'Record<string, any>';
@@ -126,6 +127,7 @@ function getInputTypeForField(field) {
     case 'boolean':
       return 'boolean';
     case 'date':
+    case 'datetime':
       return 'string';
     case 'json':
       return 'Record<string, unknown>';

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

@@ -2,7 +2,7 @@
 name: fimo-cli
 description: >-
   Use the `fimo` CLI to create or operate a Fimo project: content, forms,
-  media, labels/locales, deploys, environments, domains, analytics,
+  media, labels/locales, deploys, Branches, Environments, domains, analytics,
   integrations, Fimo agents, collaboration, accounts, and credits. Also use
   for AI agent or MCP setup and confirmed Fimo platform blockers.
 ---
@@ -15,7 +15,7 @@ This skill describes **what the CLI does and the workflows it drives**. For the
 
 Use `fimo <command> --help` for full flag details on any command.
 
-> **Webhooks are beta.** Verify a destination with `fimo webhooks test <id> --wait` and inspect its delivery history before depending on it in production.
+> Verify a destination with `fimo webhooks test <id> --wait` and inspect its delivery history before depending on it in production.
 
 ## Running the CLI
 
@@ -42,9 +42,9 @@ Pretty output may hide URLs behind clickable labels. Agents should use `--json`
 
 A Fimo project is identified by `.fimo/project.json`, written by `fimo init`. This file connects the local directory to the remote Fimo project. **Never edit it manually.** Most CLI commands find it by walking up from the cwd.
 
-## Critical: commands target the env of the current git branch
+## Critical: commands target the Branch matching the current git branch
 
-A project can have multiple **envs** — each is a git branch _plus_ its own DB, sandbox, preview, and assets. Project-scoped commands (`deploy`, `status`, `entries`, `diff`, …) operate on the env of the **current git branch**, and print a one-line banner saying which one. New projects start on `main`. Override for a single command with the global `--env <name>` flag; never edit the link file to switch. The full git-shaped workflow (`branch` / `checkout` / `switch` / `pull` / `diff` / `merge` / `status` / `publish`) lives in `references/branches.md`.
+A project can have multiple **Branches** — each is a git branch _plus_ its own DB, sandbox, preview, and assets. Project-scoped commands (`deploy`, `status`, `entries`, `diff`, …) operate on the Branch matching the **current git branch**, and print a one-line banner saying which one. New projects start on `main`. Override for a single command with the canonical `--branch <name>` flag; the legacy `--env <name>` spelling remains a compatibility alias. Never edit the link file to switch. The full git-shaped workflow (`branch` / `checkout` / `switch` / `pull` / `diff` / `merge` / `status` / `publish`) lives in `references/branches.md`.
 
 ## Quick Start
 
@@ -58,22 +58,27 @@ fimo clone                                     # interactively choose an existin
 cd my-site                                     # then load skills on demand: fimo skills get fimo-code
 pnpm dev                                       # run the app locally (use the project's PM: pnpm/npm run/yarn/bun) — your iteration loop
 fimo credits                                   # inspect the owning org's AI credit balance (read-only)
-fimo history list                              # inspect this environment's restore points
+fimo history list                              # inspect this Branch's restore points
 fimo validate                                  # run all checks + codegen; fails on missing DB labels
-fimo deploy                                    # ON-DEMAND: hosted preview / shareable link (runs validate internally)
+fimo deploy                                    # ON-DEMAND: hosted project preview (runs validate internally)
 fimo deploy --publish                          # ON-DEMAND: publish live (only when the developer says "ship it")
 ```
 
-The working loop is local: run the app with the project's package-manager `dev` script (`pnpm dev` / `npm run dev` / `yarn dev` / `bun dev` — match the lockfile), ask the developer what they want, edit, and iterate against the live localhost server. Outside the first-time onboarding rule below, `fimo deploy` is **not** a required final step — reach for it only when the developer wants a hosted preview, a shareable link, or to go live, and only on their signal (see `references/deploy.md`).
+The working loop is local: run the app with the project's package-manager `dev` script (`pnpm dev` / `npm run dev` / `yarn dev` / `bun dev` — match the lockfile), ask the developer what they want, edit, and iterate against the live localhost server. Outside the first-time onboarding rule below, `fimo deploy` is **not** a required final step — reach for it only when the developer wants a hosted project preview or to go live, and only on their signal (see `references/deploy.md`).
 
 `fimo validate` is the single entrypoint for "prove this project is ready" — it covers schema/form codegen, route metadata checks, lint, and missing label checks for `i18n.defaultLocale` from `.fimo/config.json` (fallback: `en`). Use `fimo labels set` / `set-many` to create or update label values in the DB. The underlying phases are also available individually under the hidden `fimo scripts` namespace for advanced/debug use.
 
+Keep `fimo validate --json` at the front of the project's `build` script, which is where the bundled templates put it. The hosted build runs that script, so validation runs on the exact code being published and a rejected build reports the failing rule instead of a generic build error. Removing it is the developer's call, but do not drop it while editing `package.json` for other reasons.
+
+**`fimo validate` does not type check.** Run the project's own `typecheck` or `check` script after changing code.
+
 ## Decision Tree
 
 Load the matching reference when the user's request fires its trigger. Recipes that involve writing code also need the `fimo-code` skill's package references — they're called out where relevant.
 
 - "Create a new Fimo project / scaffold a site / start a new website / add the opt-in content starter / link an existing project locally" → `references/init.md`
-- "Add a content type / blog / products / pages / CMS" → `references/content.md` (workflow) **+ run `fimo skills get fimo-code --ref content/schema` and load the detected framework reference**
+- "Add a content type / blog / products / content schemas / CMS" → `references/content.md` (workflow) **+ run `fimo skills get fimo-code --ref content/schema` and load the detected framework reference**
+- "Declare Pages routes / configure Pages sources or route params / control what Studio shows for a route" → `references/pages.md`
 - "Add a contact / signup / feedback / newsletter form" → `references/forms.md` (workflow) **+ run `fimo skills get fimo-code --ref forms` for the JSON spec and generated client**
 - "View form submissions / who filled out the contact form / inspect what users sent / how many signups" → `references/forms.md` § Reading submissions
 - "Upload an image / hero / cover / existing media file" → `references/assets.md` (workflow: upload, browse, open, delete) **+ run `fimo skills get fimo-code --ref assets` for the `FimoMedia` shape and rendering**
@@ -82,7 +87,8 @@ Load the matching reference when the user's request fires its trigger. Recipes t
 - "Enable locales / configure default locale / integrate an existing locale system" → `references/locales.md` **+ run `fimo skills get fimo-code --ref locales` and load the detected framework locale reference**
 - "What's in this project / show the project structure / describe the project / what schemas does it have / how many routes / project tree / show me what's here" → `references/describe.md`
 - "Deploy / publish / go live / push my changes" → `references/deploy.md`
-- "Get the preview URL / open the preview / what's the URL for this env / refresh the preview link / I just want to see the site / the preview URL stopped working" → `references/preview.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`
 - "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`
@@ -90,14 +96,14 @@ Load the matching reference when the user's request fires its trigger. Recipes t
 - "Firecrawl / scrape a public website / competitor research / agent web research" → `references/integrations.md` **+ load `references/integrations/firecrawl.md`**
 - "Check credits / credit balance / can I keep using AI / billing credits / running low / how many credits are left" → `references/credits.md`
 - "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 environment / new env / switch envs / merge envs / diff two envs / env status / what changed on this branch / sync from parent / cut a release / tag a version / go to prod" → `references/branches.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 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`
 - "Invite a collaborator / add Marc / share with client" → `references/invite.md`
-- "Login / log out / who am I / switch organization" → `references/account.md` — note: switching **org** is `fimo orgs switch`; bare `fimo switch` switches **env** (see `references/branches.md`)
+- "Login / log out / who am I / switch organization" → `references/account.md` — note: switching **org** is `fimo orgs switch`; bare `fimo switch` changes the active **Fimo Branch** (see `references/branches.md`)
 - "Create / scaffold / run / validate an agent / agent bundle / wire or enable its triggers / list agent templates / view agent runs, reports, or logs (`fimo agents *`)" → `references/agents.md`
 - "Install Fimo for my agent / fimo skills install / set up Claude Code, Codex, or Cursor for Fimo" → `references/agent-setup.md`
 - "Connect an agent to a Fimo project through MCP / configure `fimo mcp` / expose Fimo tools to a local MCP client" → `references/mcp.md`
@@ -115,11 +121,11 @@ These fire at specific moments in the project lifecycle. **Surface them proactiv
 - **When `fimo init` created or scaffolded a new project (create-new path, including a Studio-supplied `--project-id`)** → after init and context loading succeed, run the single first-preview deploy and return the preview and dashboard links — see `references/init.md` § Create the first hosted preview. That deploy is also the sandbox warm-up; never run a separate warm-up deploy. Skip it only if the user explicitly said not to deploy. Linking a project with existing code and migrations keep their own approval rules.
 - **Right after `fimo init`** → suggest `fimo rename "<Display Name>"` to set a human-readable name (the default post-init name is an auto-generated slug). Infer the name from what the user is building (e.g. "Acme Coffee" for a café, "Jane Doe Portfolio" for a personal site). See `references/init.md`.
 - **Right after `fimo init`** → start the app locally with the project's package-manager `dev` script (`pnpm dev` / `npm run dev` / `yarn dev` / `bun dev`) in the background. This localhost server with live reload is your iteration loop — edit, show, repeat. No deploy is needed to see local changes. If the initiating request did not say what to build, ask the developer — after the first preview on the create-new path, never as a blocker before initializing.
-- **When a user-visible unit of work looks done outside first-time onboarding** → **offer** to deploy (`fimo deploy` for a hosted preview / shareable link, `fimo deploy --publish` to go live) and run it only after the developer confirms — or immediately if they ask. Never deploy ordinary edits on your own. See `references/deploy.md`.
+- **When a user-visible unit of work looks done outside first-time onboarding** → **offer** to deploy (`fimo deploy` for a hosted project preview, `fimo deploy --publish` to go live) and run it only after the developer confirms — or immediately if they ask. Never deploy ordinary edits on your own. See `references/deploy.md`.
 - **Optional, outside new-project onboarding (its first preview already warms the sandbox), if you already know a deploy is coming** → warm the sandbox early with `fimo deploy -m "chore: init" &` in the background so the one-time ~15-30s provision + dep install happens while you work and the real deploy lands warm (~4-10s). This is a perf optimization, not a requirement. See `references/deploy.md` § Warm the sandbox early in a session.
 - **Iterative code-only deploys** → once you are deploying, `fimo deploy --no-restart` skips the sandbox dev-server restart on HMR-safe edits. See `references/deploy.md` § Skipping the dev-server restart for when it's safe.
 - **You need the current preview URL but haven't changed code** (opening it, screenshotting it, handing it to another tool, the previous URL expired) → `fimo preview url`, never a no-op `fimo deploy`. See `references/preview.md`.
-- **When the user wants to try something risky / explore a redesign without touching the live site** → suggest a feature env: `fimo checkout -b <name>` gives an isolated branch + DB + preview. Deploy previews there, then `fimo merge` it back and `fimo publish`. See `references/branches.md`.
+- **When the user wants to try something risky / explore a redesign without touching the live site** → suggest a feature Branch: `fimo checkout -b <name>` gives an isolated Branch + DB + preview. Deploy previews there, then `fimo merge` it back and `fimo publish`. See `references/branches.md`.
 - **After completing or safely preserving the user's main work, when a confirmed Fimo platform failure still materially blocks the task after one safe recovery attempt, or a confirmed missing capability blocks completion or forces a fragile or heavily manual workaround** → use the built-in `supportReport` tool. Do not wait for the user to ask and do not stop after only describing the gap. See `references/support.md`.
 - **After the first successful `fimo deploy`** → suggest `fimo invite` if the project involves multiple people. Typical roles: `edit` for developers/content editors, `view` or `comment` for clients/stakeholders, `full` for project leads. See `references/invite.md`.
 - **When the user wants to modify the URL of their website** → walk through `references/domains.md`. The CLI surface covers renaming the Fimo-provided subdomain (`fimo domains rename-default`, free), attaching a domain they already own (`fimo domains add`, Premium), and buying a new domain through Fimo (`fimo domains buy`, Premium). The auto-generated default URL on every project is a fallback, not a final choice — proactively offer this after `fimo deploy --publish` if the user mentioned a real brand or domain.
@@ -129,7 +135,7 @@ These fire at specific moments in the project lifecycle. **Surface them proactiv
 - **Editing `.fimo/project.json`** — read-only; it's the link between local and remote project. Treat as a generated file.
 - **Treating `fimo deploy` as the working loop or a required final step** — the loop is local (`pnpm dev` etc.). Deploy commits + pushes + round-trips the sandbox; it's for hosted previews / going live, on-demand. Iterate locally and deploy at logical breakpoints. See `references/deploy.md`.
 - **Deploying without the developer asking or confirming** — new-project onboarding authorizes exactly one automatic first preview deploy (unless the user said not to deploy); every other deploy is offer-then-confirm. Don't auto-deploy after finishing an ordinary edit.
-- **Running `fimo deploy` just to get a fresh preview URL** — that's a commit + push + sandbox sync for what should be a sub-second read. Use `fimo preview url` instead. See `references/preview.md`.
+- **Running `fimo deploy` just to get the current preview URL** — that's a commit + push + sandbox sync when only destination resolution is needed. Use `fimo preview url` instead. See `references/preview.md`.
 - **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.
 - **Using a starter on an existing project** — `--starter` is create-new only. Keep `--project-id` flows blank and use explicit content/form/label commands when changing an existing project.

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

@@ -26,7 +26,7 @@ fimo orgs switch                     # interactive picker to change the active o
 fimo orgs switch --org <id-or-slug>  # explicit switch (required in non-TTY)
 ```
 
-> **`fimo switch` is NOT the org switcher.** Bare `fimo switch <name>` is an alias for `fimo checkout` — it switches the active **env** (git branch). Org switching is `fimo orgs switch`. See `references/branches.md`.
+> **`fimo switch` is NOT the org switcher.** Bare `fimo switch <name>` is an alias for `fimo checkout` — it changes the active **Fimo Branch**. A Fimo Branch keeps its code, database, sandbox, content, and preview together. Org switching is `fimo orgs switch`. See `references/branches.md`.
 
 ## Inviting collaborators
 

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

@@ -7,7 +7,7 @@ The `fimo agents` namespace authors and operates **agent bundles** — multi-fil
 The namespace splits cleanly in two:
 
 - **Bundle authoring** — `create`, `list-templates`, `list`, `validate`, `secrets add/remove/list`. Local config editing, no API call except the project-level validation path. Operates on the files under `.fimo/agents/<name>/` (or root `agents/<name>/` for legacy projects).
-- **Cloud ops** — `run`, `runs`, `report`, `logs`. Env-aware, talk to the server. Default `--env` is `main`; `--project` defaults to the linked project in `.fimo/project.json` or legacy `.fimo.settings.json`.
+- **Cloud ops** — `run`, `runs`, `report`, `logs`. Branch-aware, talk to the server. Default `--branch` is `main`; the legacy `--env` spelling remains an alias. `--project` defaults to the linked project in `.fimo/project.json` or legacy `.fimo.settings.json`.
 
 The bundle lives in **git** (`.fimo/agents/<name>/`, or legacy root `agents/<name>/`), not the database. The DB only mirrors what `config.yaml` declares on `main` (which triggers are wired) plus **run sessions**. So the bundle reaches the server through `fimo deploy` — and that push to `main` is also what wires its triggers. There is no activate command: deploying IS the enablement act, and removing a trigger from `config.yaml` tears it down on the next deploy.
 
@@ -78,7 +78,7 @@ There is no all-capabilities wildcard; keeping the list explicit makes each agen
 | `webhooks:write`             | Create, modify, delete, or trigger webhooks | High         |
 | `schedules:read`             | Read schedule configs and run history       | Low          |
 | `schedules:write`            | Create, change, or trigger scheduled runs   | Critical     |
-| `fimo:logs:read`             | Read production logs                        | Low          |
+| `fimo:logs:read`             | Read project deployment logs                | Low          |
 | `fimo:analytics:read`        | Read analytics data                         | Low          |
 | `fimo:preview:read`          | Read a current preview URL                  | Low          |
 | `fimo:history:read`          | Read project restore points                 | Low          |
@@ -92,6 +92,9 @@ If a capability is missing, the related command is denied and the agent should c
 blocker. Add the capability to `capabilities.yaml`, run `fimo agents validate <name>`, deploy the bundle, and start a
 new run. A denied capability does not grant access to anything else.
 
+Studio chat and project-bound Slack turns receive `fimo:logs:read`. Autonomous agents receive it only when their
+`capabilities.yaml` declares it; use `fimo logs` with the deploy guidance when diagnosing a failed preview.
+
 Example for a content editor that can read and update entries but cannot change schemas:
 
 ```yaml
@@ -99,23 +102,23 @@ Example for a content editor that can read and update entries but cannot change
 - cms:write
 ```
 
-## Cloud ops (env-aware)
+## Cloud ops (Branch-aware)
 
 ```bash
-fimo agents run <name> [--env <env>] [--project <id>] [--skip-drift-check] [-C <dir>]
-fimo agents runs <name> [--limit <n>] [--env <env>] [--project <id>] [-C <dir>]
-fimo agents report <name> [--session <id>] [--env <env>] [--project <id>] [-C <dir>]
+fimo agents run <name> [--branch <branch>] [--project <id>] [--skip-drift-check] [-C <dir>]
+fimo agents runs <name> [--limit <n>] [--branch <branch>] [--project <id>] [-C <dir>]
+fimo agents report <name> [--session <id>] [--branch <branch>] [--project <id>] [-C <dir>]
 fimo agents logs <name> [--session <id>] [--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 `--env` to `main`.
-- **`runs <name>`** — list past run sessions for the agent in a compact table (id, started, duration, status, trigger, env, cost). Default `--limit 20`; `--env` filters to one env.
-- **`report <name>`** — print a run's **report**: the agent's final message, captured when the run finishes (for a read-only agent like `seo-audit` this _is_ the audit; for a write agent it's a "what I changed" summary). With no `--session`, the most recent run for `<name>` is used (combine with `--env` to scope); `--session <id>` targets a specific run. Output is raw 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 message, it says so (and shows the stop reason when there is one). This is the command to read what a run actually produced — see the `logs` note below.
+- **`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`; legacy `--env` remains an alias.
+- **`runs <name>`** — list past run sessions for the agent in a compact table (id, started, duration, status, trigger, Branch, cost). Default `--limit 20`; `--branch` filters to one Branch. The response's legacy `env` field is still present for API compatibility.
+- **`report <name>`** — print a run's **report**: the agent's final message, captured when the run finishes (for a read-only agent like `seo-audit` this _is_ the audit; for a write agent it's a "what I changed" summary). With no `--session`, the most recent run for `<name>` is used (combine with `--branch` to scope); `--session <id>` targets a specific run. Output is raw 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 message, it says so (and shows the stop reason when there is one). This is the command to read what a run actually produced — see the `logs` note below.
 - **`logs <name>`** — stream a run's log (defaults to the latest session; `--session <id>` targets one). **Note:** the log-streaming endpoint is still a server-side stub at time of writing — the command prints a placeholder rather than real log lines. To read a finished run's output today, use `report`.
 
 ## How triggers get wired
 
-Agents are not env-scoped: they belong to the project, are read from `main`, and their triggers are global. A branch env has no agents of its own — Studio's agents view shows main's agents whichever env you are on, and a bundle sitting only on a feature branch appears nowhere until it reaches main.
+Agents are not Branch-scoped: they belong to the project, are read from `main`, and their triggers are global. A Branch has no agents of its own — Studio's agents view shows main's agents whichever Branch you are on, and a bundle sitting only on a feature Branch appears nowhere until it reaches main.
 
 Pushing `.fimo/agents/<name>/config.yaml` (or a legacy root bundle) to `main` is the whole enablement act — `fimo deploy` does it. The server reconciles the file into its trigger rows on every push: a `schedule` trigger gets a cron, a `webhook` trigger gets its path, and `manual` becomes runnable. Removing a trigger from the file deletes it (cron torn down, path released) on the next deploy; deleting the agent's directory removes the whole deployment.
 

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

@@ -1,48 +1,49 @@
-# Envs & branches (git-shaped workflow)
+# Branches (git-shaped workflow)
 
-> **Beta:** Branch environments are still in beta. The CLI surface is available for early workflows, but not every command or cross-surface merge path is guaranteed to work reliably yet.
+> **Beta:** Branches are still in beta. The CLI surface is available for early workflows, but not every command or cross-surface merge path is guaranteed to work reliably yet.
 
-A Fimo **env** is a multi-surface clone of the project: a git branch **plus** its own Neon DB branch, sandbox, preview URL, and R2 asset prefix. The CLI mirrors `git` command shapes so the workflow transfers directly — same verbs, multi-surface semantics.
+A Fimo **Branch** is a multi-surface clone of the project: a git branch **plus** its own Neon DB branch, sandbox, preview URL, and R2 asset prefix. The CLI mirrors `git` command shapes so the workflow transfers directly — same verbs, multi-surface semantics. In Project Settings, an **Environment** is a grouping policy such as Production or Preview; it is not this Branch-backed clone.
 
-Every project starts with one env: `main`. You create more for feature work, deploy previews per-env, then merge back and publish.
+Every project starts with one Branch: `main`. You create more for feature work, deploy previews per Branch, then merge back and publish.
 
-## The env model — how every command picks its target
+## The Branch model — how every command picks its target
 
-**This is the single most important concept: project-scoped commands target the env of the _current git branch_.** When you're on git branch `feat/seo`, `fimo deploy`, `fimo status`, `fimo entries list`, etc. all operate on the `feat/seo` env's DB / sandbox / preview. The CLI prints a one-line stderr banner telling you which env it resolved.
+**This is the single most important concept: project-scoped commands target the Branch matching the _current git branch_.** When you're on git branch `feat/seo`, `fimo deploy`, `fimo status`, `fimo entries list`, etc. all operate on the `feat/seo` Branch's DB / sandbox / preview. The CLI prints a one-line stderr banner telling you which Branch it resolved.
 
 ```bash
-fimo --env <name> <command>     # peek at another env for one command (does not switch)
+fimo --branch <name> <command>  # peek at another Branch for one command (does not switch)
 ```
 
-- **`--env <name>`** is a global override. `fimo --env main status` inspects `main` while you stay checked out on your feature branch.
+- **`--branch <name>`** is the canonical global override. `fimo --branch main status` inspects `main` while you stay checked out on your feature Branch.
+- **`--env <name>`** remains a compatibility alias for `--branch`; it still carries the legacy `env` wire name.
 - Git-changing commands use the current branch; cross-branch status only reports the mismatch.
-- If the branch maps to no env, the CLI errors with a hint (`fimo branch` to list, `fimo branch <name>` to create) rather than guessing.
-- **`main`** is the default env and cannot be deleted.
-- **`release/*`** envs are **read-only** — they're tags produced by `fimo publish`, not branches you push to. `fimo deploy` refuses them.
+- If the git branch maps to no Fimo Branch, the CLI errors with a hint (`fimo branch` to list, `fimo branch <name>` to create) rather than guessing.
+- **`main`** is the default Branch and cannot be deleted.
+- **`release/*`** Branches are **read-only** — they're tags produced by `fimo publish`, not branches you push to. `fimo deploy` refuses them.
 - **`prod`** is protected: it cannot be created, forked from, checked out, or deleted. It's updated by publishing, never by pushing.
 
 ## Commands
 
-| Command                 | git analogue        | What it does                                                                                                                                                                     |
-| ----------------------- | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `fimo branch`           | `git branch`        | List envs (current marked `*`). `-v` adds preview URLs + deleted envs.                                                                                                           |
-| `fimo branch <name>`    | `git branch <name>` | Create an env off the current one. `--from <env>` forks from a different parent. Provisions DB + sandbox + preview + R2 prefix.                                                  |
-| `fimo branch -d <name>` | `git branch -d`     | Delete an env — tears down its sandbox, Neon branch, and R2 prefix. Refuses `main` and `prod`.                                                                                   |
-| `fimo checkout <name>`  | `git checkout`      | Switch to an env (checks out the matching git branch; the app derives its env from that branch at startup). `-b` creates + switches; `--from <env>` sets the parent (with `-b`). |
-| `fimo switch <name>`    | `git switch`        | Switch to an existing env. Takes only `<name>` (no `-b`/`--from`) — use `fimo checkout -b` to create + switch.                                                                   |
-| `fimo pull`             | `git pull`          | Sync the current env's data plane (DB/assets) down from its parent. `--from <env>` syncs from an explicit ancestor.                                                              |
-| `fimo diff [from] [to]` | `git diff`          | Two-env diff across all surfaces. Defaults `from` = current env, `to` = `main`. `--surface <name>` limits to one; `--json`; `--no-color`.                                        |
-| `fimo status`           | `git status`        | Multi-surface status for the current env vs its parent. See below.                                                                                                               |
-| `fimo merge <from>`     | `git merge`         | Merge another env into the current one (multi-surface, atomic, interactive conflict resolver). See below.                                                                        |
-| `fimo publish`          | —                   | Tag `main@HEAD` as `release/<version>` and trigger the prod swap. See "Publishing" below.                                                                                        |
+| Command                 | git analogue        | What it does                                                                                                                                                                 |
+| ----------------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `fimo branch`           | `git branch`        | List Branches (current marked `*`). `-v` includes deleted Branches.                                                                                                          |
+| `fimo branch <name>`    | `git branch <name>` | Create a Branch off the current one. `--from <branch>` forks from a different parent. Provisions DB + sandbox + preview + R2 prefix.                                         |
+| `fimo branch -d <name>` | `git branch -d`     | Delete a Branch — tears down its sandbox, Neon branch, and R2 prefix. Refuses `main` and `prod`.                                                                             |
+| `fimo checkout <name>`  | `git checkout`      | Switch to a Branch (checks out the matching git branch; the app derives its Branch from that branch at startup). `-b` creates + switches; `--from <branch>` sets the parent. |
+| `fimo switch <name>`    | `git switch`        | Switch to an existing Branch. Takes only `<name>` (no `-b`/`--from`) — use `fimo checkout -b` to create + switch.                                                            |
+| `fimo pull`             | `git pull`          | Sync the current Branch's data plane (DB/assets) down from its parent. `--from <branch>` syncs from an explicit ancestor.                                                    |
+| `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`          | —                   | Tag `main@HEAD` as `release/<version>` and trigger the prod swap. See "Publishing" below.                                                                                    |
 
-All of these accept the global `--env` override. `diff`, `status`, `merge`, and `publish` additionally accept `-C, --cwd <dir>` to point at a project directory.
+All of these accept the global `--branch` override; legacy `--env` remains an alias. `diff`, `status`, `merge`, and `publish` additionally accept `-C, --cwd <dir>` to point at a project directory.
 
-> **`fimo switch` is the ENV switcher, not the org switcher.** To change your active organization, use `fimo orgs switch` — see `references/account.md`.
+> **`fimo switch` changes the active Fimo Branch, not the org.** A Fimo Branch keeps its code, database, sandbox, content, and preview together. To change your active organization, use `fimo orgs switch` — see `references/account.md`.
 
 ## The 6 surfaces
 
-`status`, `diff`, and `merge` all reason over the same per-env surfaces, in this order:
+`status`, `diff`, and `merge` all reason over the same per-Branch surfaces, in this order:
 
 `code` · `schemas` · `content` · `translations` · `assets` · `forms`
 
@@ -51,25 +52,25 @@ All of these accept the global `--env` override. `diff`, `status`, `merge`, and
 ## Typical PR-style flow
 
 ```bash
-fimo checkout -b feat/seo        # branch off main: git branch + env provisioned
+fimo checkout -b feat/seo        # branch off main: git branch + Branch provisioned
 # …generate / edit code, schemas, content, translations…
-fimo deploy -m "feat: seo pass"  # deploy a preview of the feat/seo env
-fimo preview url                 # fresh URL to open / screenshot the feat/seo preview
+fimo deploy -m "feat: seo pass"  # deploy a preview of the feat/seo Branch
+fimo preview url                 # canonical URL to open / screenshot the feat/seo preview
 fimo status                      # see what changed vs main, surface by surface
 fimo checkout main               # back to main
-fimo merge feat/seo              # merge the env back into main (resolve conflicts)
+fimo merge feat/seo              # merge the Branch back into main (resolve conflicts)
 fimo publish --version 1.4.0     # tag a release + prod swap
-fimo branch -d feat/seo          # tear down the feature env
+fimo branch -d feat/seo          # tear down the feature Branch
 ```
 
 ## `fimo status`
 
-The showcase command — a unified, color-coded report of what's changed on the current env, grouped by surface, with per-surface counts.
+The showcase command — a unified, color-coded report of what's changed on the current Branch, grouped by surface, with per-surface counts.
 
 ```bash
-fimo status                  # full report, current env vs parent (or main)
+fimo status                  # full report, current Branch vs parent (or main)
 fimo status --short          # one line per surface
-fimo status --vs main        # compare against an explicit env
+fimo status --vs main        # compare against an explicit Branch
 fimo status --content        # only the content surface (combine flags freely)
 fimo status --json           # machine-readable
 ```
@@ -80,7 +81,7 @@ fimo status --json           # machine-readable
 ## `fimo merge`
 
 ```bash
-fimo merge feat/seo                   # merge feat/seo into the current env
+fimo merge feat/seo                   # merge feat/seo into the current Branch
 fimo merge feat/seo -y                # non-interactive: parent-wins on every conflict
 fimo merge feat/seo --allow-direct-merge   # override the "don't merge straight onto main" gate
 ```
@@ -90,7 +91,7 @@ fimo merge feat/seo --allow-direct-merge   # override the "don't merge straight
 
 ## `fimo pull`
 
-Syncs the current env's data plane from its parent (or `--from <ancestor>`). Conflicts currently resolve **parent-wins** automatically (a future release adds per-row picks). Use it to refresh a stale feature env with the latest `main` content/schema state.
+Syncs the current Branch's data plane from its parent (or `--from <ancestor>`). Conflicts currently resolve **parent-wins** automatically (a future release adds per-row picks). Use it to refresh a stale feature Branch with the latest `main` content/schema state.
 
 ## Publishing — `fimo publish` vs `fimo deploy --publish`
 
@@ -103,8 +104,8 @@ Use `fimo publish` for versioned prod releases; use `fimo deploy --publish` for
 
 ## Anti-patterns
 
-- **Using `git checkout -b` instead of `fimo checkout -b`** — raw git creates the branch but **not** the env's DB / sandbox / preview. Always use `fimo` for branch operations so resources are provisioned atomically. (Running `fimo branch <name>` after the fact provisions them.) The running app itself follows the git branch either way.
+- **Using `git checkout -b` instead of `fimo checkout -b`** — raw git creates the branch but **not** the Branch's DB / sandbox / preview. Always use `fimo` for Branch operations so resources are provisioned atomically. (Running `fimo branch <name>` after the fact provisions them.) The running app itself follows the git branch either way.
 - **Hardcoding the tenant API URL** — the app derives it from the git branch and `.fimo/project.json`. Set `VITE_API_URL` / `NEXT_PUBLIC_FIMO_API_URL` yourself only as a deliberate override (e.g. a local API); it then wins over derivation on every branch.
 - **Trying to push to or delete `prod` / `release/*`** — these are read-only/protected. Publish to update prod; never push.
 - **`fimo merge` straight onto `main` as a habit** — it's gated for a reason. Merge on a branch, then publish.
-- **Confusing `fimo switch` (env) with `fimo orgs switch` (org).**
+- **Confusing `fimo switch` (Branch) with `fimo orgs switch` (org).**

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

@@ -2,12 +2,12 @@
 
 > Package contract: load the version-locked `fimo-code` skill with `fimo skills get fimo-code`, then fetch its nested content and detected-framework references for schema JSON, entry values, generated clients, and imports.
 
-This file covers the **CLI workflow** for content. Use it when the user wants to add a content type (blog, products, pages) or manage Singles and entries.
+This file covers the **CLI workflow** for content schemas, Singles, and entries. Use it when the user wants to add a content type (blog, products, reusable content) or manage content records. For route metadata shown in Studio Pages, load `references/pages.md`.
 
 ## Choose the write path first
 
 - Exactly one homepage, settings document, About page, or campaign page → declare `"isSingleton": true` and write it with `fimo singles update <TypeName>`.
-- Repeated posts, products, team members, or reusable pages → keep a collection and create rows with `fimo entries create <TypeName>`.
+- Repeated posts, products, team members, or other reusable records → keep a collection and create rows with `fimo entries create <TypeName>`.
 
 Never remove `isSingleton: true` merely because `fimo entries create` rejects the type. `entries` and `singles` are separate command namespaces; inspect `fimo singles --help` when the content is one-off.
 

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

@@ -9,7 +9,7 @@ fimo credits --project <project-id>
 fimo credits -C ./path/to/project
 ```
 
-This command is **project-scoped but not env-scoped**. It does not depend on the current git branch or `--env`, because credits belong to the project's organization, not to a branch/env.
+This command is **project-scoped but not Branch-scoped**. It does not depend on the current git branch or `--branch`, because credits belong to the project's organization, not to a Branch.
 
 ## Pretty Output
 

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

@@ -1,14 +1,14 @@
 # Deploy pipeline
 
-**`fimo deploy` is on-demand, not the working loop and not a required final step.** The loop is local: run the app with the project's package-manager `dev` script (`pnpm dev` / `npm run dev` / `yarn dev` / `bun dev` — match the lockfile), iterate with the developer, and let live reload show changes. Reach for `fimo deploy` only when the developer wants a **hosted preview**, a **shareable link**, or to **go live** — and only on their signal. New-project onboarding counts as the signal for its single automatic first preview deploy (see `references/init.md` § Create the first hosted preview). It commits everything, pushes to the current env's branch, and round-trips that env's sandbox (install + restart); it's a milestone command, not a save step. Batch related edits into one deploy; never deploy after every change.
+**`fimo deploy` is on-demand, not the working loop and not a required final step.** The loop is local: run the app with the project's package-manager `dev` script (`pnpm dev` / `npm run dev` / `yarn dev` / `bun dev` — match the lockfile), iterate with the developer, and let live reload show changes. Reach for `fimo deploy` only when the developer wants a **hosted preview**, a **project-member preview link**, or to **go live** — and only on their signal. New-project onboarding counts as the signal for its single automatic first preview deploy (see `references/init.md` § Create the first hosted preview). It commits everything, pushes to the current Branch, and round-trips that Branch's sandbox (install + restart); it's a milestone command, not a save step. Batch related edits into one deploy; never deploy after every change.
 
-> **Local vs hosted.** The local dev server is localhost only. The Fimo **dashboard preview** and the **shareable preview URL** are served by the deployed sandbox — so if the developer wants to see the site in the dashboard or send someone a link, that requires a `fimo deploy`.
+> **Local vs hosted.** The local dev server is localhost only. The Fimo **dashboard preview** and the authenticated **project-member preview URL** are served by the deployed sandbox — so if the developer wants to see the site in the dashboard or send another project member a link, that requires a `fimo deploy`.
 
-`fimo deploy` uses the current branch. New projects start on `main`; `release/*` is read-only, and `--publish` only runs from `main`. See `references/branches.md` for the multi-env workflow.
+`fimo deploy` uses the current Branch. New projects start on `main`; `release/*` is read-only, and `--publish` only runs from `main`. See `references/branches.md` for the multi-Branch workflow.
 
 Before deploying, Fimo fast-forwards a clean checkout that is behind and stops on dirty-behind or diverged branches. This syncs the whole branch, including config commits from Studio or locale commands.
 
-> **Just need the current preview URL?** That's `fimo preview url` — sub-second, no commit, no push. See `references/preview.md`. `fimo deploy` is only for pushing code changes.
+> **Just need the current preview URL?** That's `fimo preview url` — no commit or push. A cold sandbox can still take time to resolve. See `references/preview.md`. `fimo deploy` is only for pushing code changes.
 
 ## Commands
 
@@ -19,7 +19,7 @@ fimo deploy --no-restart                     # skip dev-server restart (HMR-safe
 fimo deploy -m "<commit message>" --publish  # also publish a new live version
 ```
 
-- **`fimo deploy`** — commits pending changes, pushes to the current env's branch, syncs that env's preview sandbox, and links to the Preview and Fimo dashboard.
+- **`fimo deploy`** — commits pending changes, pushes to the current Branch, syncs that Branch's preview sandbox, and links to the Preview and Fimo dashboard.
 - **`fimo deploy --publish`** — same as above, then triggers a live publish and prints the live URL. Runs from `main` only. **Only use `--publish` when the user signals "ship it"** — first-time site completion, or an explicit "publish" / "go live" request. Otherwise stick to plain `fimo deploy`. (For a _versioned_ prod release, use `fimo publish` instead — see below.)
 - **`-m`** is the commit message used when there are uncommitted local changes; required in non-interactive shells. Omit if the working tree is already clean.
 - **`--no-restart`** — tells the sandbox to skip the dev-server restart and let Vite HMR pick up the change. Shaves ~3s per deploy. See "Skipping the dev-server restart" below for when it's safe.
@@ -35,15 +35,26 @@ fimo deploy -m "<commit message>" --publish --json
 
 Read these fields from `data`:
 
-| Field           | Destination                                                 |
-| --------------- | ----------------------------------------------------------- |
-| `preview_url`   | Shareable preview. Its token expires, so do not persist it. |
-| `dashboard_url` | Stable, authenticated Fimo project and environment page.    |
-| `app_url`       | Public live site, returned after a successful `--publish`.  |
+| Field                | Destination                                                      |
+| -------------------- | ---------------------------------------------------------------- |
+| `preview_url`        | Stable, authenticated full-screen viewer for project members.    |
+| `sandbox_url`        | Short-lived raw site URL for agents, curl, and screenshot tools. |
+| `sandbox_expires_at` | Expiry of the raw sandbox URL.                                   |
+| `studio_url`         | Stable, authenticated Fimo Studio project and Branch page.       |
+| `dashboard_url`      | Deprecated compatibility alias for `studio_url`.                 |
+| `app_url`            | Public live site, returned after a successful `--publish`.       |
 
-When reporting the result, present the raw values as named Markdown links. If no code changed and you only need fresh destinations, use `fimo preview url --json` instead of deploying again.
+When reporting the result, open `preview_url` for a person and use `sandbox_url` for machine reads. If no code changed and you only need fresh destinations, use `fimo preview url --json` instead of deploying again.
 
-Public project variables managed with `fimo vars add` and `fimo vars update` are injected into preview/build/deploy environments. Project secrets are not injected into app builds; agents request secrets separately through their own config. See `references/project-vars-and-secrets.md`.
+Public project variables managed with `fimo vars add` and `fimo vars update` are injected into preview/build/deploy runtimes. Project secrets are not injected into app builds; agents request secrets separately through their own config. See `references/project-vars-and-secrets.md`.
+
+## Diagnose a failed publication
+
+Use the publication ID returned by the failed command: run `fimo publish inspect <id> --json` for its durable status, then `fimo publish logs <id> --json` for a bounded build-log tail. Logs come from the hosting provider and may be unavailable after its deployment is reclaimed.
+
+## Diagnose a failed preview deploy
+
+If the sandbox fails to install dependencies or start the app, run `fimo logs --json` before retrying. Read the newest install and dev-server events first; when the response is truncated, use its `previousCursor` as `fimo logs --before <cursor> --json` to fetch the preceding page. Do not recreate or replace the sandbox before collecting logs, because that can discard the failure evidence.
 
 ## Framework hosting
 
@@ -57,6 +68,9 @@ needed, load the `fimo-code` skill's framework reference:
 connector and the explicit catch-all used only by plain Vite `BrowserRouter`
 SPAs; Astro's `fimo()` integration lives in `references/frameworks/astro.md`.
 
+Redirects, response headers, and URL shape belong in
+`.fimo/config.json#hosting` — see `references/hosting.md`.
+
 ## Warm the sandbox early in a session (optional)
 
 This is a **performance optimization, only worth doing when you already know a deploy is coming** (the developer asked to publish, or you're confident they'll want a hosted preview soon). If you're just iterating locally, skip it — don't deploy pre-emptively. New-project onboarding never needs it: its automatic first preview deploy is the warm-up.
@@ -118,12 +132,14 @@ curl -H 'Accept: text/markdown' https://your-site/  # content negotiation
 curl https://your-site/?format=md                # query param
 ```
 
+This is a hosting capability: Fimo generates the `.md`, content-negotiation, and `?format=md` responses for supported built pages. Application code must not reimplement any of them — in particular, never add a route that fetches the app's own public URL to convert it to Markdown. For a dynamic page, render Markdown from the same server-side data the page itself uses when the framework supports that; otherwise report the capability as unresolved instead of building a self-fetching route.
+
 ## Recovering from Git drift
 
 Most stale states are caught before deploy changes or commits files. Follow the emitted hint: clean a dirty checkout, or reconcile a diverged branch. A push can still lose a race if the remote advances after preflight:
 
 ```bash
-git pull --rebase fimo <env>   # <env> = the branch you're deploying (e.g. main)
+git pull --rebase fimo <branch>   # <branch> = the Branch you're deploying (e.g. main)
 # fix any conflicts
 fimo deploy
 ```
@@ -132,7 +148,7 @@ fimo deploy
 
 - Source of truth is this git repo.
 - **Never** edit `.fimo/project.json`; it is generated by `fimo init`.
-- Each env deploys to its own branch + preview sandbox; `--publish` and `fimo publish` run from `main` only. See `references/branches.md`.
+- Each Branch deploys to its own preview sandbox; `--publish` and `fimo publish` run from `main` only. See `references/branches.md`.
 
 ## After the first successful deploy