fimo 2.2.0-staging.13 → 2.2.0-staging.14

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
 
@@ -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.
 
@@ -247,8 +247,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/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/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
 

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

@@ -11,7 +11,7 @@ Invite collaborators to your Fimo organization or project. After deploying a web
 Typical scenarios where inviting is appropriate:
 
 - Multi-person projects (agencies, teams)
-- Client hand-off (invite client as `view` or `comment`)
+- Client hand-off (invite client as `view`)
 - Content editors (invite as `edit` for CMS access)
 - Developers (invite as `edit` or `full`)
 
@@ -30,12 +30,14 @@ fimo invite --project <project-id> --email "john@acme.com" --role full
 
 Project roles:
 
-| Role      | Access Level                                  | Use Case                    |
-| --------- | --------------------------------------------- | --------------------------- |
-| `view`    | Read-only                                     | Clients, stakeholders       |
-| `comment` | View + leave comments                         | Reviewers, approvers        |
-| `edit`    | Edit code, content, assets, use AI chat       | Developers, content editors |
-| `full`    | Full access including settings and publishing | Project leads               |
+| Role   | Access Level                                  | Use Case                         |
+| ------ | --------------------------------------------- | -------------------------------- |
+| `view` | Read-only                                     | Clients, stakeholders, reviewers |
+| `edit` | Edit code, content, assets, use AI chat       | Developers, content editors      |
+| `full` | Full access including settings and publishing | Project leads                    |
+
+`comment` is no longer offered. Fimo has no comment system, so it granted exactly what `view` grants. It is still
+accepted by `--role` and still held by anyone already assigned it, but do not hand it out — use `view`.
 
 ## Invite to an organization
 
@@ -76,8 +78,8 @@ Next steps:
 # Give client view-only access
 fimo invite --email "client@company.com" --role view
 
-# Give client comment access for feedback
-fimo invite --email "client@company.com" --role comment
+# Reviewers get the same read-only access
+fimo invite --email "reviewer@company.com" --role view
 ```
 
 ### Adding a developer

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

@@ -27,18 +27,10 @@ There is no `fimo translations` command. Use `fimo labels`.
 
 ## Locale config
 
-`.fimo/config.json` controls label/content locales:
-
-```json
-{
-  "i18n": {
-    "defaultLocale": "en",
-    "locales": ["en"]
-  }
-}
-```
+Use `references/locales.md` to change the supported locales or default.
 
-- `defaultLocale` is what `fimo validate` and label commands use when `--locale` is omitted.
+- `fimo validate` reads `defaultLocale` from the synchronized local config so it can run without a Fimo session.
+- Label writes with no `--locale` leave the locale unset; the selected Branch API resolves its configured default.
 - `locales` is the enabled locale list and must include `defaultLocale`. Do not add non-default locales unless the user asks for multiple languages, localized routes, translations, or a specific locale.
 - If multiple locales are configured, create or update label values for every configured locale.
 - For a non-default locale, pass `--locale <locale>` explicitly.

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

@@ -13,13 +13,13 @@ fimo locales set-default es --yes --json
 fimo locales remove es --yes --json
 ```
 
-Studio chat can run `locales list`. Manage the locale lifecycle through Studio Settings or the standalone CLI.
+In a linked project, change the locale set or default only through these commands or Studio Settings. Never edit `i18n.defaultLocale` or `i18n.locales` directly. Studio chat can run `locales list`.
 
 These commands update the selected Branch through the locale lifecycle API. The API commits `.fimo/config.json` to the Fimo Branch, then the CLI synchronizes the **whole local branch** to that commit. They refuse a dirty config, a local-ahead branch, or a diverged branch before applying the remote change. `--yes` bypasses only the explanatory prompt.
 
 If a mutation exits with code `2` and `data.code` is `LOCALE_APPLIED_SYNC_REQUIRED`, the remote operation succeeded (`data.applied` is `true`) but the local fast-forward did not. **Do not retry the locale command.** Run the commands in `data.sync.recovery`, resolve the checkout, and confirm with `fimo status` or `fimo locales list`.
 
-Edit `.fimo/config.json` only for declarative locale and route metadata:
+The synchronized `.fimo/config.json` remains the application runtime's declarative locale configuration:
 
 ```jsonc
 {
@@ -36,6 +36,8 @@ Edit `.fimo/config.json` only for declarative locale and route metadata:
 - New projects do not need a global routing strategy. The route contract declares locale placement with `/:locale`; legacy `i18n.routing.strategy` values are read only for compatibility while migrating.
 - If multiple locales are configured, create or update labels and localized content for every configured locale. Create schemas with `i18n: { "enabled": false }` only once.
 
+Edit application-owned settings such as `routes` directly in `.fimo/config.json`. Locale membership and the default use the lifecycle commands above because they must update the selected Fimo Branch and local checkout together.
+
 `fimo locales remove` permanently deletes that locale's stored entries and labels.
 
 ## Validate
@@ -108,7 +110,7 @@ Neither Astro nor Next supports an optional single-segment filesystem folder. As
 
 ## Migrate An Existing Locale System
 
-Inspect the existing locale provider, route table, switcher, redirects, and public URLs before editing configuration. Preserve working URL behavior during the migration.
+Inspect the existing locale provider, route table, switcher, redirects, and public URLs before changing locale behavior. Preserve working URL behavior during the migration.
 
 Preserve the existing locale provider, router, switcher, redirects, and public URLs. Next.js projects run `fimo skills get fimo-code --ref frameworks/next/locales`; React Router projects load the React Router setup reference and its focused route-ownership migration when upgrading; Astro projects run `fimo skills get fimo-code --ref frameworks/astro` and pass the page-resolved locale into server reads and `getLabels`.
 

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

@@ -14,7 +14,7 @@ fimo preview url --all                               # print every destination a
 curl -L "$(fimo preview url)"                        # fetch the raw sandbox preview
 ```
 
-`--env <name>` remains a deprecated alias for `--branch <name>`; the two disagreeing is an error, not a precedence rule. The JSON envelope carries `branch` and keeps `env` as a duplicate of it. Studio deep links still use the `/env/` path, which redirects to `/branch/`.
+`--env <name>` is rejected as a Branch selector; use `--branch <name>`. The JSON envelope carries the canonical `branch` field and may include a deprecated `env` compatibility duplicate. Studio deep links still use the `/env/` path, which redirects to `/branch/`.
 
 ## Human and machine behavior
 
@@ -32,7 +32,6 @@ curl -L "$(fimo preview url)"                        # fetch the raw sandbox pre
     "project_id": "prj_abc",
     "branch": "main",
     "env": "main",
-    "env": "main",
     "preview_url": "https://fimo.ai/preview/prj_abc/main",
     "sandbox_url": "https://preview.provider.example/session",
     "sandbox_expires_at": "2026-08-20T18:42:00.000Z",

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

@@ -9,16 +9,16 @@ fimo projects list [--org <id>]                 # list projects in an org (defau
 fimo projects create [dir] [--org <id>] [--framework react-router|astro|nextjs|sveltekit] [--install|--no-install]
 fimo projects clone [projectId] [dir] [--branch <name>] # clone an existing project locally
 fimo projects delete [projectId] [-C <dir>] [-y] # delete (defaults to current project)
-fimo projects publish [projectId] [-C <dir>]     # make the project live (publish from main)
+fimo projects publish [projectId] [-C <dir>]     # make the project live from its Production source Branch
 fimo projects unpublish [projectId] [-C <dir>]   # take the project offline
 fimo projects rename <name> [projectId] [-C <dir>]   # set seo.siteName in the linked project config
 ```
 
 - **`list`** — projects you can see in the org. Live projects are marked.
 - **`create`** — identical to `fimo init` (create-new path); see `references/init.md`.
-- **`clone`** — clone a remote Fimo project's git repo to your machine and write the local `.fimo/project.json` and agent files. Use `fimo clone <projectId>` when scripting or when the ID is known. In an interactive terminal, bare `fimo clone` opens a project picker for the active org; JSON mode and non-TTY shells require an explicit project ID and fail fast instead of prompting. By default it clones `main`; pass `--branch <name>` to clone a specific Branch. The legacy `--env <name>` spelling remains a compatibility alias. The target directory defaults to the project display name/name, or pass `[dir]` explicitly.
+- **`clone`** — clone a remote Fimo project's git repo to your machine and write the local `.fimo/project.json` and agent files. Use `fimo clone <projectId>` when scripting or when the ID is known. In an interactive terminal, bare `fimo clone` opens a project picker for the active org; JSON mode and non-TTY shells require an explicit project ID and fail fast instead of prompting. By default it clones `main`; pass `--branch <name>` to clone a specific Branch. The removed `--env <name>` spelling is rejected as a Branch selector. The target directory defaults to the project display name/name, or pass `[dir]` explicitly.
 - **`delete`** — destructive; prompts unless `-y`. Removes the remote project.
-- **`publish` / `unpublish`** — toggle the project's public visibility. `publish` flips the current `main` state live (the same "go live" as `fimo deploy --publish`, minus the git push).
+- **`publish` / `unpublish`** — toggle the project's public visibility. `publish` flips the configured Production source state live (the same "go live" as `fimo deploy --publish`, minus the git push).
 - **`rename`** — edits only the linked local project's `seo.siteName`. It does not commit or deploy. It requires a project marker in the cwd, and if you pass a `[projectId]` that doesn't match the linked project it errors and exits 1 (so you can't rename a different project). Later remote config commands may require reconciliation while the local config is dirty. Finish your local edits, then explicitly run `fimo deploy --no-wait` when ready for a quick sync.
 
 ## Top-level clone shortcut
@@ -43,10 +43,10 @@ fimo rename "<Site Name>"        # local edit: set seo.siteName in the project c
 
 ## Publish commands
 
-| Command                 | Effect                                                                  |
-| ----------------------- | ----------------------------------------------------------------------- |
-| `fimo deploy --publish` | Push current `main` + flip the project live in one shot.                |
-| `fimo projects publish` | Flip the project live (no git push).                                    |
-| `fimo publish`          | Flip the already-synced `main` revision live; optional label and notes. |
+| Command                 | Effect                                                                     |
+| ----------------------- | -------------------------------------------------------------------------- |
+| `fimo deploy --publish` | Push the current Production source + flip the project live in one shot.    |
+| `fimo projects publish` | Flip the project live (no git push).                                       |
+| `fimo publish`          | Flip the synced Production source revision live; optional label and notes. |
 
 See `references/deploy.md` and `references/branches.md` for the full picture.

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

@@ -2,7 +2,7 @@
 
 `fimo schedules` manages recurring commands for one project Branch. It uses the
 current checkout Branch by default, or the Branch passed with `--branch <name>`.
-The legacy `--env <name>` spelling remains a compatibility alias.
+The removed `--env <name>` spelling is rejected as a Branch selector.
 
 The command starts in that Branch's sandbox. Commands can still target another
 Branch explicitly, for example with `fimo schemas list --branch preview`.
@@ -72,6 +72,6 @@ All schedule commands support the CLI's global `--json` mode. List, detail, and
 
 ## Notes
 
-- Every operation is scoped to the active Branch unless `--branch` (or the legacy `--env` alias) is passed.
+- Every operation is scoped to the active Branch unless `--branch` is passed.
 - Pausing stops future cron runs. It does not delete history.
 - A failed or skipped manual run exits non-zero with its run ID and an exact `runs show` command for inspecting detail.

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

@@ -28,12 +28,13 @@ Run this before writing a custom payload. The list shows supported event types,
 - Publish: `publish.started`, `publish.succeeded`, `publish.failed`, `publish.unpublished`
 - Agents: run started/completed/failed/cancelled and review requested/resolved
 - Analytics: `analytics.report_ready`
-- Media: uploaded/updated/deleted/generated/processing_failed
+- Media: uploaded/updated/deleted
 - Entries: `entry.changed`
 - Domains: `domain.created`, `domain.deleted`
 - Labels: `label.changed`
 - Locales: `locale.created`, `locale.default_changed`, `locale.deleted`
-- Environment events (legacy wire names): `environment.created`, `environment.deleted`, `environment.merged`, `environment.restored`
+- Branch restore: `branch.restored`
+- Existing lifecycle wire names: `environment.created`, `environment.deleted`, `environment.merged`
 
 Do not guess variable paths. The common envelope is:
 
@@ -110,9 +111,8 @@ Available filters are event-specific:
 - `--agent <name>` for agent events
 - `--media-type <image|video|audio|document|other>` for media events
 - `--action <created|updated|deleted>`, `--content-type <name>`, and `--locale <locale>` for `entry.changed`
-- `--debounce-changes <immediate|5s|30s|1m>` for direct `entry.changed` delivery grouping
 
-`entry.changed` represents content accepted in the selected Environment. New entry webhooks wait 5 seconds after the last direct edit by default, then send one delivery with the combined `data.changes`. Exact repeated autosave changes appear once. Use `--debounce-changes immediate` to disable grouping. Accepted agent edits and environment merges already carry compact batches and send immediately. Operations above the delivery batch size share an `operationId` and include `{ index, total }` batch metadata. Every event includes scalar `environment` and `branch` context and keeps the legacy Branch value at `event.env.name`. Publish events always report Production on `main`.
+`entry.changed` represents content committed in the selected Environment. Each committed write sends one delivery whose `data.changes` lists every affected entry; environment merges arrive the same way with `reason: "environment_merge"`. Operations above the delivery batch size share an `operationId` and include `{ index, total }` batch metadata. Retries resend the same delivery (same event `id`), never a new one. Every event includes scalar `environment` and `branch` context and keeps the legacy Branch value at `event.env.name`. Publish events always report Production on `main`.
 
 ## Inspect before depending on it
 

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

@@ -115,7 +115,7 @@ export async function getStaticPaths() {
 
 Configure Astro i18n from `.fimo/config.json#i18n` and use `Astro.currentLocale` for content reads, `getLabels({ locale })`, and `<html lang>`. The standard starter keeps the configured default locale unprefixed and prefixes the others. Existing applications may instead resolve locale through middleware, domains, cookies, or another application-owned strategy. Astro needs no Fimo locale provider. Ownership rules: `references/locales.md`.
 
-The new-project shell pairs unprefixed default-locale pages with a parallel `[locale]` tree because Astro has no optional single-segment page filename. Add locales in `.fimo/config.json`; Astro's native i18n router validates the prefixed tree. Route metadata uses `/:locale` with `params.locale.optional: true`; Astro page files remain authoritative.
+The new-project shell pairs unprefixed default-locale pages with a parallel `[locale]` tree because Astro has no optional single-segment page filename. Add locales through the `fimo-cli` locale workflow; Astro's native i18n router reads the synchronized config and validates the prefixed tree. Route metadata uses `/:locale` with `params.locale.optional: true`; Astro page files remain authoritative.
 
 ## Studio route catalog