fimo 2.2.0-staging.8 → 2.2.0

package/assets/agent-templates/_default/config.yaml

@@ -3,5 +3,11 @@
 version: 1
 description: 'A new Fimo agent. Edit this tagline to describe what it does.'
 model: openai/gpt-5.6-luna
+
+runtime:
+  # Per-run spend limit in credits. Remove to allow up to the
+  # organization's available balance at admission.
+  max_credits: 5000
+
 triggers:
   - type: manual

package/assets/agent-templates/broken-link-sweeper/config.yaml

@@ -5,6 +5,7 @@ model: openai/gpt-5.6-luna
 runtime:
   cloud: true
   long_running: true
+  max_credits: 5000
 
 triggers:
   - type: manual

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

@@ -24,6 +24,27 @@ import type { <%= referenceImport.pascal %> } from "./<%= referenceImport.pascal
 /*  ────────────  📄  Type definitions  ────────────             */
 /*───────────────────────────────────────────────────────────────*/
 
+<% if (Object.values(model.fields || {}).some(holdsMedia)) { -%>
+/**
+ * What a media field stores: a reference to a media-library asset. Point at the
+ * asset by `id`, or by the `url` an upload returned and Fimo resolves the `id`
+ * for you. `alt` belongs to the entry, so it survives replacing the asset. The
+ * facts the asset owns are never copied in, so they cannot go stale.
+ */
+export type FimoMediaRef = ({ id: string; url?: string } | { id?: string; url: string }) & {
+  alt?: string;
+  source?: "local" | "external";
+};
+
+/**
+ * What a read returns for a media field it named in `populate`: the reference
+ * plus the facts the asset owns as of that read. `name`, `mime`, `width`, and
+ * `height` remain optional when the asset is external, missing, or incomplete.
+ * A read that did not name the field returns `FimoMedia` with those facts absent.
+ */
+export type FimoPopulatedMedia = FimoMedia & { name?: string; mime?: string };
+
+<% } -%>
 /**
  * <%= model.pascal %> entity interface
  */
@@ -131,10 +152,8 @@ function getInputTypeForField(field) {
       return 'string';
     case 'json':
       return 'Record<string, unknown>';
-    case 'media': {
-      const media = 'Pick<FimoMedia, "url" | "alt" | "name" | "mime" | "width" | "height">';
-      return field.multiple ? `${media}[]` : media;
-    }
+    case 'media':
+      return field.multiple ? 'FimoMediaRef[]' : 'FimoMediaRef';
     case 'reference': {
       const raw = Array.isArray(field.targets) && field.targets.length > 0 ? 'FimoPolymorphicReference' : 'FimoReference';
       return field.many ? `${raw}[]` : `${raw} | null`;
@@ -176,6 +195,32 @@ function getBlocksType(field, input) {
   return `${item}[]`;
 }
 
+/** A media field, or a blocks field with a media value in some variant. */
+function holdsMedia(field) {
+  if (field.type === 'media') {
+    return true;
+  }
+  if (field.type !== 'blocks') {
+    return false;
+  }
+  const schema = field.schema || {};
+  const variants = Array.isArray(schema.oneOf) ? schema.oneOf : [schema];
+  return variants.some((variant) => Object.values(variant.fields || {}).some(holdsMedia));
+}
+
+/**
+ * What the field becomes when `populate` names it. A media field gains the
+ * asset facts; a blocks field keeps its declared item types — the media inside
+ * it is populated at runtime, but naming which variant carries which value is
+ * beyond what this flat contract can say, so the type stays conservative.
+ */
+function getPopulatedTypeForField(field) {
+  if (field.type === 'media') {
+    return field.multiple ? 'FimoPopulatedMedia[]' : 'FimoPopulatedMedia';
+  }
+  return getBlocksType(field, false);
+}
+
 function getStringLiteralUnion(field) {
   if (!Array.isArray(field.options) || field.options.length === 0) {
     return null;
@@ -202,17 +247,26 @@ function isConditionalField(field) {
   return field.showIf !== undefined || field.showIfAny !== undefined;
 }
 
-const populatedReferenceFields = Object.entries(model.fields || {}).filter(([, field]) => {
+const modelFields = Object.entries(model.fields || {});
+const populatedReferenceFields = modelFields.filter(([, field]) => {
   if (field.type !== 'reference') {
     return false;
   }
   return (Array.isArray(field.targetRefs) && field.targetRefs.length > 0) || typeof field.targetPascal === 'string';
 });
+const populatedMediaFields = modelFields.filter(([, field]) => holdsMedia(field));
+const populatableFields = [...populatedReferenceFields, ...populatedMediaFields];
 -%>
 
-<% if (populatedReferenceFields.length === 0) { -%>
+<% if (populatableFields.length === 0) { -%>
 export type <%= model.pascal %>References = Record<never, never>;
 <% } else { -%>
+/**
+ * What each populatable field returns when a read names it in `populate`: a
+ * reference field resolves to its target entry, a media field to the asset's
+ * current facts, a blocks field to the same items with every media value
+ * inside them filled. Fields absent here are returned as stored.
+ */
 export interface <%= model.pascal %>References {
 <%
 populatedReferenceFields.forEach(([key, field]) => {
@@ -235,6 +289,11 @@ populatedReferenceFields.forEach(([key, field]) => {
   <%= key %>: <%= type %>;
 <%
 });
+populatedMediaFields.forEach(([key, field]) => {
+-%>
+  <%= key %>: <%= getPopulatedTypeForField(field) %>;
+<%
+});
 -%>
 }
 <% } -%>

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

@@ -44,7 +44,7 @@ A Fimo project is identified by `.fimo/project.json`, written by `fimo init`. Th
 
 ## Critical: commands target the Branch matching the current git branch
 
-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 still works, but passing both with different values fails (`BRANCH_OPTION_CONFLICT`) instead of picking one. 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 removed `--env <name>` spelling is rejected. 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
 
@@ -83,7 +83,7 @@ Load the matching reference when the user's request fires its trigger. Recipes t
 - "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**
+- "Upload, inspect, replace, safely remove, or permanently destroy an image / hero / cover / existing media file" → `references/assets.md` **+ run `fimo skills get fimo-code --ref assets` for the `FimoMedia` shape and rendering**
 - "Generate AI image / video / draft preview / image edit / cover from a prompt" → `references/media.md` (task commands, quality, recipes, and verification) **+ run `fimo skills get fimo-code --ref assets` for the `FimoMedia` shape if you'll plug the result into UI**
 - "Add labels / update static copy / fix missing `t()` values" → `references/labels.md` (workflow) **+ run `fimo skills get fimo-code --ref labels` and load the detected framework reference**
 - "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**
@@ -106,6 +106,7 @@ Load the matching reference when the user's request fires its trigger. Recipes t
 - "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` changes the active **Fimo Branch** (see `references/branches.md`)
+- "Check the Inbox / what are my agents waiting on / answer a blocked agent / an agent asked me a question / approve or deny what an agent asked for (`fimo inbox *`)" → `references/inbox.md`. Never answer on the person's behalf.
 - "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`
 - "Add, inspect, search, or run a remote MCP server / use `fimo mcp`" → `references/mcp.md`
@@ -130,6 +131,7 @@ These fire at specific moments in the project lifecycle. **Surface them proactiv
 - **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 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`.
+- **When a project agent has stopped and is waiting on a person** → `fimo inbox list --topic agent_question --unread` surfaces it. Show the stored form to the person, collect their explicit answer, and submit it with `fimo inbox answer`. See `references/inbox.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`.
 - **After the automatic first-preview deploy on the create-new path, before the project has been published** → if there is no custom domain and the free default `*.fimo.site` slug still looks generated or was never explicitly chosen, offer to find a cleaner free subdomain. It needs no DNS. Never claim one without explicit user confirmation: suggest candidates, let the user choose, then rename it. Choosing the slug does not publish the site; the URL starts resolving only after the first successful `fimo deploy --publish`. Skip this nudge if the user already chose the default slug, attached a custom domain, or declined. See `references/domains.md` § Offer a cleaner default URL before first publish.
 - **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).
@@ -146,6 +148,6 @@ These fire at specific moments in the project lifecycle. **Surface them proactiv
 - **Adding another deploy tool (Vercel, Netlify, Cloudflare Pages)** — 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** — `fimo credits` already includes spendable daily free credits in "Available now"; the allowance section is accounting context, not an amount to add.
+- **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.
 - **Trying to refill credits from the CLI** — `fimo credits` is read-only. Buying/refilling credits belongs in the billing UI for now.
 - **`fimo agents run` to push bundle changes** — it doesn't. The bundle reaches the server through `fimo deploy` (it lives in git, not the DB), and that push to `main` is also what wires the declared triggers. `run` dispatches the _deployed_ version. Deploy first. There is no `activate` command. See `references/agents.md`.

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`. 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`.
+- **Cloud ops** — `run`, `runs`, `report`, `logs`. Branch-aware, talk to the server. Default `--branch` is `main`; `--env` is rejected as a Branch selector. `--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.
 
@@ -57,6 +57,31 @@ integrations:
 An explicit map is restrictive: only entries set to `true` are available. An omitted or disabled integration cannot be
 used. See `references/integrations.md` for project setup, auth, and provider-specific commands.
 
+Declare a `runtime` block in `config.yaml` to gate where a bundle runs and bound what one run costs:
+
+```yaml
+runtime:
+  cloud: true
+  dev: false
+  long_running: false
+  max_credits: 5000
+  max_steps: 40
+```
+
+- `cloud` / `dev` — declared boolean environment flags for where the bundle may run.
+- `long_running` — same capability as the `runtime:long_running` token: lets the run exceed the default time limit.
+- `max_credits` — the run's own credit ceiling (integer, credits ≥ 1). The default scaffold template ships
+  `max_credits: 5000` as a visible starter limit. Unset: the run may spend up to the organization's available
+  credits at admission.
+- `max_steps` — cap on model-loop steps for one run (integer ≥ 1). Unset: no step cap; only `max_credits` (or the
+  organization's balance) and the plan's agent-hours bound the run.
+
+All five keys are optional; an absent `runtime` block behaves as if every key were unset. There is no platform step cap
+and no legacy per-session cost ceiling — the only stops are these author-owned limits, the organization running out of
+credits (`insufficient_credits`), and the agent-hours allowance. A limit that fires records a truthful terminal reason
+(`max_steps`, `budget_exceeded`, `insufficient_credits`, or `finish_run_missing` when a run ends without calling
+`finish_run`), readable via `fimo agents report` and the Studio run page.
+
 ## How a cloud run ends
 
 Fimo creates one task Branch and environment for a cloud run, tells the agent their names, and manages their lifecycle.
@@ -242,13 +267,13 @@ Example for a content editor that can read and update entries but cannot change
 
 ```bash
 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 runs <name> [--limit <n>] [--cursor <cursor>] [--all-pages] [--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 `--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.
+- **`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`.
+- **`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 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). 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`.
 

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

@@ -3,7 +3,7 @@
 > Package contract: run `fimo skills get fimo-code --ref assets` for `FimoMedia`, `--ref ui` for rendering primitives, and load the detected framework reference for framework-specific integration.
 > For **generating** new images / videos with AI, see **`references/media.md`** for the task commands and recipes.
 
-This file covers the **CLI workflow** for media that already exists: uploading files, browsing the library, opening an asset to inspect it, moving / deleting items.
+This file covers the **CLI workflow** for media that already exists: uploading files, browsing the library, inspecting reference impact, replacing references, and removing assets safely.
 
 ## Upload a file
 
@@ -96,9 +96,12 @@ fimo assets list --search "wolf"
 fimo assets list --search "hero" --image
 fimo assets list --search "logo" --type file --sort-by createdAt
 
-fimo assets list --limit 50 --offset 0                    # paging
+fimo assets list --limit 50 --cursor <next-cursor>        # next page
+fimo assets list --all-pages                              # every remaining page
 ```
 
+The response includes `nextCursor` when another page exists. Keep the same filters when continuing. `--offset` remains a compatibility alias for existing scripts.
+
 The `--search` query matches:
 
 - `name` (file name)
@@ -142,11 +145,47 @@ When the agent needs to **see** the image — e.g., Claude inspecting it to pick
 fimo assets create-folder "Blog Images"
 fimo assets create-folder "Covers" --parent-id <uuid>
 fimo assets move <asset-id> --parent-id <folder-uuid>
-fimo assets delete <asset-id>
 ```
 
 `--parent-id` is **required** on `move` and must be a folder UUID. (Moving an asset back to the library root isn't supported by this command today — the server rejects a non-UUID parent.)
 
+## Inspect, replace, and remove safely
+
+Check structured content references before removal:
+
+```bash
+fimo assets usage <asset-id> --json
+```
+
+The result reports coverage, status, and counts for the Current Branch, Main, and Live. Other Branches are not checked, so this is guidance, never a project-wide claim that an asset is unused. Code references are not scanned.
+
+Replace structured references only in the Current Branch:
+
+```bash
+fimo assets replace <source-id> --with <replacement-id>
+```
+
+This changes references, not file bytes. It leaves the original asset, Main, Live, other Branches, and code references unchanged.
+
+Remove from the selected environment and include reference guidance in the receipt:
+
+```bash
+fimo assets remove <asset-id>
+fimo assets remove <source-id> --replace-with <replacement-id>
+fimo assets remove <asset-id> --without-checking
+```
+
+Reference counts and incomplete scopes do not block environment removal. Main and Live keep their rows, and shared bytes remain available to them. Use `--replace-with` when Current Branch references should point to another asset before removal. `--without-checking` skips only the guidance scan and remains environment-scoped.
+
+Project-wide destruction is separate and requires confirmation:
+
+```bash
+fimo assets remove <asset-id> --permanent
+fimo assets remove <asset-id> --permanent --yes
+```
+
+Use `--permanent` only when the user explicitly wants the asset destroyed across the project. It cannot be combined with `--replace-with` or `--without-checking`. The legacy `fimo assets delete` spelling remains an alias for `remove`.
+
 ## End-to-end workflow
 
 1. Upload with `fimo assets upload`, use `fimo assets bulk-upload` for a batch, or generate with a task command such as `fimo image generate`.

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

@@ -4,7 +4,7 @@
 
 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 Branch: `main`. You create more for feature work, deploy previews per Branch, then merge back and publish.
+New standalone projects start with one Branch: `main`. Linking an unversioned folder, cloning, and scaffolding read the project's default Branch from Fimo when they set up Git. You create more for feature work, deploy previews per Branch, then merge back and publish.
 
 ## The Branch model — how every command picks its target
 
@@ -15,10 +15,11 @@ fimo --branch <name> <command>  # peek at another Branch for one command (does n
 ```
 
 - **`--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 deprecated alias for `--branch`. Passing both with **different** values fails with `BRANCH_OPTION_CONFLICT` rather than picking a winner; passing both with the same value is fine.
+- **`--env <name>`** is not a Branch selector. It is rejected; use `--branch <name>`.
 - Git-changing commands use the current branch; cross-branch status only reports the mismatch.
+- If Git cannot name a Branch, the CLI stops instead of guessing. Check out a Branch or pass `--branch <name>`. Sandboxes receive their Branch through `FIMO_ENV`.
 - 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.
+- The project's default Branch cannot be deleted. Existing standalone projects use **`main`**.
 - **`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.
 
@@ -35,9 +36,9 @@ 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 already-synced `main` revision with a stable Fimo publication ID. See "Publishing" below.                                                                        |
+| `fimo publish`          | —                   | Publish the synced Production source revision with a stable Fimo publication ID. See "Publishing" below.                                                                     |
 
-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.
+All of these accept the global `--branch` override. `diff`, `status`, `merge`, and `publish` additionally accept `-C, --cwd <dir>` to point at a project directory.
 
 > **`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`.
 
@@ -97,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 already-synced `main` 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 `main` code and flips the project live in one shot. See `references/deploy.md`.
+- **`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`.
 
-Use `fimo publish` when `main` is already synced; use `fimo deploy --publish` when the local revision still needs to be pushed first. Both only run from `main`.
+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`.
 
 ## Anti-patterns
 

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

@@ -69,7 +69,7 @@ Use singular commands for one entry. Bulk create and per-entry bulk update also
 ```bash
 fimo entries create <TypeName> --body '<json>'
 fimo entries create <TypeName> --locale es --document-id <documentId> --body '<json>'
-fimo entries list <TypeName> [--limit N] [--offset N] [--search Q] [--where JSON] [--sort F] [--fields FIELDS] [--populate FIELDS]
+fimo entries list <TypeName> [--limit N] [--cursor CURSOR] [--all-pages] [--search Q] [--where JSON] [--sort F] [--fields FIELDS] [--populate FIELDS]
 fimo entries list <TypeName> --locale es
 fimo entries get <TypeName> <id> [--locale es]
 fimo entries update <TypeName> <id> [--locale es] --body '<json>'
@@ -90,12 +90,12 @@ fimo entries list BlogPost --where '{"featured":true}' --sort -publishedAt
 fimo entries list BlogPost --where '{"rank":{"$gte":3}}' --sort rank
 fimo entries list BlogPost --where '{"__fimo":{"contentType":{"$eq":"BlogPost"}}}'
 fimo entries list BlogPost --search "launch"
-fimo entries list BlogPost --limit 10 --offset 20 --sort title
+fimo entries list BlogPost --limit 10 --cursor <next-cursor> --sort title
 fimo entries list BlogPost --fields slug,title,excerpt,coverImage --sort -publishedAt --limit 12
 fimo entries list BlogPost --fields slug,title,author --populate author
 ```
 
-Use the canonical read query flags: `--search`, `--sort`, `--where`, `--limit`, `--offset`, `--fields`, and `--populate`.
+Use the canonical read query flags: `--search`, `--sort`, `--where`, `--limit`, `--cursor`, `--all-pages`, `--fields`, and `--populate`. `--offset` remains a compatibility alias for existing scripts.
 `--where` is a JSON object keyed by schema field name. Simple values mean equality and stay typed inside the JSON (`{"featured":true}`, `{"category":"react"}`, `{"rank":{"$gte":3}}`); operator objects support `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$in`, `$nin`, `$contains`, `$startsWith`, and `$null`, subject to the field type. Public Fimo-owned metadata lives under `__fimo`; currently `__fimo.contentType` is filterable.
 
 Reference filters take the target `id` string (`{"author":"750e..."}`). On a to-many field, `$eq` and `$contains` mean membership, `$in` means any listed target is present, `$ne` and `$nin` mean none are present, and `$null: true` means empty or missing. Reference fields cannot be sorted; use `--sort field` / `--sort -field` on scalar fields.
@@ -103,7 +103,7 @@ Reference filters take the target `id` string (`{"author":"750e..."}`). On a to-
 
 `--populate` is a comma-separated list of reference fields to embed. Without it, reference fields return reference objects like `{ "id": "..." }`; with `--populate author,contributors`, those fields return the target entry objects for the requested locale. Only reference fields can be populated (scalar fields 400), and populate never selects which target fields come back. A populated target missing in the requested locale resolves to null unless you pass `localeFallbacks=true`, which falls back to the best available locale variant, marked by its `locale` field. Limits: 200 references per to-many write, 500 distinct populated documents per field per request (400 past either).
 
-Polymorphic references declare `targets: ["Post", "Product"]` instead of `target` (never both) and their values carry both parts: `{ "contentType": "Post", "id": "..." }`. Populate returns mixed full entries, and generated hooks expose `$type` on each populated value to branch on. `--where` on polymorphic fields is not supported yet and fails with a clear error.
+Polymorphic references declare `targets: ["Post", "Product"]` instead of `target` (never both) and their values carry both parts: `{ "contentType": "Post", "id": "..." }`. Populate returns mixed full entries, and generated hooks expose `$type` on each populated value to branch on. `--where` on polymorphic fields is not supported yet and fails with a clear error. Fixed and polymorphic references also work inside blocks with these same write shapes (`id`, `documentId`, or `slug` selectors), but nested fields cannot be populated or filtered.
 
 In generated application code, the equivalent is `populate: ['author', 'contributors'] as const` in query params. Let the generated client infer the result when possible; if a named TypeScript shape is needed, use `BlogPostResult<TFields, TPopulate>` as documented by `fimo skills get fimo-code --ref content/clients`. Writes use `BlogPostInput`.
 

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

@@ -13,31 +13,29 @@ This command is **project-scoped but not Branch-scoped**. It does not depend on
 
 ## Pretty Output
 
-The human output has three sections:
+The human output has two sections:
 
 - **Available now** - total spendable credits across all usable buckets, plus a status of `OK`, `Low`, or `Unavailable`.
-- **Breakdown (included in available now)** - daily free, monthly, purchased, and awarded buckets. These are components of the total, not extra credits to add again.
-- **Daily allowance (not additional balance)** - period cap, period usage, remaining period allowance, and the maximum daily grant. This explains plan/accounting limits and can be absent.
+- **Breakdown (included in available now)** - daily free, monthly, purchased, and awarded buckets. These are components of the total, not extra credits to add again. Daily free is 0 except for organizations on the legacy Premium plan, the only plan with daily credits.
 
 Example:
 
 ```txt
 Available now
-12,430 credits
+11,830 credits
 Status: OK
 
 Breakdown (included in available now)
-  Daily free             600  expires today
+  Daily free               0
   Monthly              8,000
   Purchased            3,000
   Awarded                830
-
-Daily allowance (not additional balance)
-  Used this period: 4,400 / 5,000
-  Remaining period: 600
-  Daily grant:      up to 1,000 / day
 ```
 
+Organizations on the legacy Premium plan also show a "Daily allowance (not
+additional balance)" section. It is accounting context already included in
+"Available now", never extra credits to add.
+
 ## JSON Output
 
 Use `--json` when another tool or agent needs to parse the balance:
@@ -51,29 +49,24 @@ Use `--json` when another tool or agent needs to parse the balance:
     "projectId": "project_123",
     "organizationId": "org_123",
     "balance": {
-      "totalAvailable": 12430,
+      "totalAvailable": 11830,
       "nearLimit": false,
       "canUseAi": true,
       "buckets": {
-        "dailyFreeAvailable": 600,
+        "dailyFreeAvailable": 0,
         "monthlyAvailable": 8000,
         "purchasedAvailable": 3000,
         "awardedAvailable": 830
       }
     },
     "allowances": {
-      "dailyCredits": {
-        "periodCap": 5000,
-        "dailyGrant": 1000,
-        "usedThisPeriod": 4400,
-        "remainingThisPeriod": 600
-      }
+      "dailyCredits": null
     }
   }
 }
 ```
 
-`allowances.dailyCredits` can be `null` when the project owner's plan/account does not expose a daily allowance. Do not derive spendability from the allowance alone; use `balance.canUseAi`, `balance.nearLimit`, and `balance.totalAvailable`.
+`allowances.dailyCredits` is `null` except for organizations on the legacy Premium plan, the only plan with a daily allowance. Do not derive spendability from the allowance alone; use `balance.canUseAi`, `balance.nearLimit`, and `balance.totalAvailable`.
 
 ## When To Run It
 

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

@@ -4,7 +4,7 @@
 
 > **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-Branch workflow.
+`fimo deploy` uses the current Branch. New projects start on `main`; `release/*` is read-only, and `--publish` only runs from the project's configured Production source Branch. 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.
 
@@ -20,7 +20,7 @@ fimo deploy -m "<commit message>" --publish  # also publish a new live version
 ```
 
 - **`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.)
+- **`fimo deploy --publish`** — same as above, then triggers a live publish and prints the live URL. Runs from the configured Production source Branch 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.
 
@@ -50,11 +50,11 @@ Public project variables managed with `fimo vars add` and `fimo vars update` are
 
 ## 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.
+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. Use `fimo publish list --cursor <cursor>` to continue through older attempts or `--all-pages` to fetch the complete retained history. `--before` remains a compatibility alias. 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.
+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 --cursor <cursor> --json` to fetch the preceding page, or use `--all-pages` to fetch every retained page. `--before` remains a compatibility alias. Do not recreate or replace the sandbox before collecting logs, because that can discard the failure evidence.
 
 When Preview reports blocked dependency build scripts, treat that as a project security-policy repair, not a transient sandbox failure. Review every named package before approving it, then use the package manager's narrow project-owned mechanism:
 
@@ -121,10 +121,10 @@ There's nothing special about this — it's the same `fimo deploy` you'd run lat
 
 Two different "go live" mechanisms — pick deliberately:
 
-- **`fimo deploy --publish`** — push what's on `main` now and flip the project live in one shot. The simple "ship it" path. Runs from `main` only.
-- **`fimo publish [--label <text>] [--notes <md>]`** — publish the already-synced `main` revision without pushing. Fimo assigns the immutable publication ID; a label and notes are optional human annotations. See `references/branches.md`.
+- **`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 `main` is already synced.
+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.
 
 ## Markdown for AI agents
 
@@ -157,7 +157,7 @@ fimo deploy
 
 - Source of truth is this git repo.
 - **Never** edit `.fimo/project.json`; it is generated by `fimo init`.
-- Each Branch deploys to its own 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 the configured Production source Branch only. See `references/branches.md`.
 
 ## After the first successful deploy
 

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

@@ -29,11 +29,13 @@ Notification recipients for form submissions are configured in the Fimo web UI,
 After a form is live and users have filled it out, inspect submissions from the terminal:
 
 ```bash
-fimo forms submissions list <formIdOrName> [--limit 50] [--offset 0] [--search "<q>"] [--sort asc|desc]
+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>
 ```
 
+The list response includes `nextCursor` when another page exists. `--offset` remains a compatibility alias for existing scripts.
+
 - `<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.

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

@@ -18,8 +18,8 @@ fimo history restore <version-id>
 
 Studio chat can run `history list` and `history show`. Create and restore remain available through the standalone CLI and Studio's History page.
 
-Use the global `--branch <name>` option to target a different Branch. The legacy
-`--env <name>` spelling remains a compatibility alias. Use `--project <id>` when
+Use the global `--branch <name>` option to target a different Branch. The removed
+`--env <name>` spelling is rejected as a Branch selector. Use `--project <id>` when
 there is no local `.fimo/project.json`.
 
 ## Pagination and usage
@@ -28,6 +28,7 @@ there is no local `.fimo/project.json`.
 
 ```bash
 fimo history list --limit 20 --cursor <cursor>
+fimo history list --all-pages
 ```
 
 The list also reports compressed snapshot usage and the current retention period. Restore points expire after 14 days on Free and pay-as-you-go plans, or 90 days on Premium. The expiry is fixed when each point is created.