fimo 2.2.0-staging.9 → 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.
@@ -247,8 +272,8 @@ fimo agents report <name> [--session <id>] [--branch <branch>] [--project <id>]
 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
 
@@ -145,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

@@ -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.
 
@@ -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/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

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

@@ -0,0 +1,86 @@
+# Inbox
+
+The Inbox is what a project's agents tell the people on it: a run finished, a
+run left work for review, a merge conflicted, or a run stopped and is waiting
+for a decision. Only the last one can be acted on from the CLI.
+
+```bash
+fimo inbox list                              # unread first, then read
+fimo inbox list --topic agent_question --unread
+fimo inbox get <notification-id>             # the notification, plus the stored form when it is a question
+fimo inbox answer <notification-id> --body '<compact answer json>'
+```
+
+A notification id is the only id you ever hold. The question, its thread, the
+run it continues, and the Branch that run kept alive are resolved for you.
+
+Use `--project <id>` when there is no local `.fimo/project.json`. `--limit`,
+`--cursor`, and `--all-pages` page the list. `--archived` reads archived items;
+`--unread` stays in the unread stream instead of continuing into read items.
+
+## Answering is the person's decision, not yours
+
+**Never answer a question on someone's behalf.** A question exists because a run
+needed a human decision it could not make correctly. Answer only what the person
+in front of you explicitly chose.
+
+1. `fimo inbox list --topic agent_question --unread --json` to find waiting
+   questions, then `fimo inbox get <notification-id> --json` for the one to
+   answer. `data.question.form` is the stored form, verbatim.
+2. **Reproduce that form in the interface you are in** — the native form or
+   choice UI your harness offers, or a plain enumerated prompt when it offers
+   none. Keep the title, the description, the step order, the wording of every
+   question, every option label, the recommended option where one is marked,
+   image labels and URLs, and each capability's reason. The person is deciding
+   on what the agent actually asked, not on your summary of it.
+3. Collect only explicit answers. Do not default a step, infer one from earlier
+   conversation, or fill a step the person skipped. If the person already gave a
+   complete explicit answer, do not ask again — use what they said.
+4. **Never infer capability approval.** Selecting nothing on a capabilities step
+   is a deliberate deny-all, and omitting the step entirely is refused by the
+   CLI rather than read as a denial.
+5. Pass their notes through verbatim. The note is the one part of the answer
+   only they could write.
+6. Call `fimo inbox answer` once.
+
+## The compact answer
+
+Keyed by the step ids `inbox get` returned, in any order, one entry per step:
+
+```json
+{
+  "answers": [
+    { "stepId": "direction", "selected": ["Editorial studio"], "note": "Keep it calm." },
+    { "stepId": "access", "selected": [] },
+    { "stepId": "notes", "note": "Ship on Friday." }
+  ]
+}
+```
+
+- `selected` holds option **labels**, exactly as the form shows them.
+- `note` is free text. A step that offers options may be answered with a note
+  alone, with a selection alone, or with both.
+- A written step (`"type": "text"`) is answered with `note` only.
+- A capabilities step needs `selected`, empty or not. `[]` approves none.
+- Every step needs its own entry. Nothing is answered by omission.
+
+`--file <path>` and `--stdin` read the same JSON from a file or a pipe.
+
+## What the CLI refuses
+
+| Code                    | Why                                                                                                                                                                     |
+| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `INBOX_ANSWER_INVALID`  | Unknown or missing step, unoffered option, too many selections on a single-select, a written step answered by picking, or a capabilities step with no explicit decision |
+| `INBOX_NOT_A_QUESTION`  | The notification is a run outcome, a review, or a conflict — there is nothing to answer                                                                                 |
+| `INBOX_QUESTION_CLOSED` | Already answered, expired, cancelled, or superseded                                                                                                                     |
+| `INBOX_UNKNOWN_TOPIC`   | `--topic` is not one of the four Inbox topics                                                                                                                           |
+| `INBOX_INVALID_CURSOR`  | `--cursor` was not the `nextCursor` from a previous page                                                                                                                |
+| `INBOX_NOT_FOUND`       | No notification with that id is addressed to you in this project                                                                                                        |
+
+A question is answered once. Answering it starts exactly one continuation run,
+and re-sending the same answer never starts a second one.
+
+## What the CLI does not do
+
+Marking read, archiving, restoring, reviewing retained work, and resolving merge
+conflicts happen in the Fimo Inbox UI. `fimo inbox` reads and answers.

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

@@ -23,7 +23,7 @@ Generated pnpm projects pin `pnpm@10.26.0` and carry project-owned `pnpm-workspa
 | `--project-id <id>`          | no                            | Set up the named Fimo project: scaffold and push a fresh site when it has no code yet, otherwise clone it.                                              |
 | `--org <id>`                 | no                            | Target organization **id** when creating (use the `ID` column from `fimo orgs list`, NOT the slug). Picker shown interactively if omitted and TTY.      |
 | `--branch <name>`            | no                            | Branch to check out when linking an existing project (defaults to `main`).                                                                              |
-| `--env <name>`               | no                            | Compatibility alias for `--branch <name>`.                                                                                                              |
+| `--env <name>`               | no                            | Rejected as a Branch selector; use `--branch <name>`.                                                                                                   |
 | `--framework <framework>`    | no                            | New-project scaffold: `nextjs` (App Router, default), `react-router`, `vite` (React SPA), `astro`, or `sveltekit`. Existing repositories are preserved. |
 | `--package-manager <pm>`     | no                            | `npm` \| `pnpm` \| `yarn` \| `bun`.                                                                                                                     |
 | `--install` / `--no-install` | yes in non-TTY                | Install deps after checkout (or skip it).                                                                                                               |
@@ -81,10 +81,11 @@ select it with `--framework react-router` when a project should use React Router
 instead of the default Next.js App Router shell.
 
 Set the primary locale from the request: when several are explicitly named, use the first as default;
-if none is requested, keep `en` and tell the user. Update `.fimo/config.json#i18n`, the framework-native
-locale boundary, matcher, and HTML language default. Do not keep `en` solely because the shell starts
-there. Do not add `/en`, a language picker, global path-prefix configuration, or localized schemas unless
-the site needs them.
+if none is requested, keep `en` and tell the user. After init, load `references/locales.md` and use its
+typed lifecycle commands to configure the locale set and default. Then update the framework-native locale
+boundary, matcher, and HTML language default. Do not keep `en` solely because the shell starts there.
+Do not add `/en`, a language picker, global path-prefix configuration, or localized schemas unless the
+site needs them.
 After init, load the project rules and `fimo-code` to build the requested site.
 If you replace a shell's code with a site that uses another framework or none,
 fix `runtime.framework` in the same change
@@ -94,7 +95,7 @@ For `--agents`, pass the AI tool you're running in: `--agents=claude-code` for C
 
 ## Setting up a project by ID
 
-Pass `--project-id <id>` to set up a known Fimo project. If the project has no code yet — for example, one just created in Fimo Studio — `init` scaffolds a fresh site into it and pushes the initial commit: the same create-new path, linked to the existing ID. If the project already has code, `init` clones it into `[dir]`, like `fimo clone`. Use `--branch <name>` to check out a specific Branch (defaults to `main`); `--env <name>` remains a compatibility alias. Without `--project-id`, `fimo init` creates a new project.
+Pass `--project-id <id>` to set up a known Fimo project. If the project has no code yet — for example, one just created in Fimo Studio — `init` scaffolds a fresh site into it and pushes the initial commit: the same create-new path, linked to the existing ID. If the project already has code, `init` clones it into `[dir]`, like `fimo clone`. Use `--branch <name>` to check out a specific Branch (defaults to `main`). Without `--project-id`, `fimo init` creates a new project.
 
 ## Linking an existing local application