fimo 2.8.0-staging.1 → 2.8.0-staging.10

package/README.md

@@ -35,11 +35,11 @@ npx fimo@latest init my-site
 cd my-site
 ```
 
-Every command runs the same way: **`npx fimo@latest <command>`**. `fimo init` sets up the project, pushes the first commit, and wires it to your Fimo account. Open it in your coding agent and start building.
+Every command runs the same way: **`npx fimo@latest <command>`**. `fimo init` sets up the site, pushes the first commit, and wires it to your Fimo account. Open it in your coding agent and start building.
 
 ## AI coding tools
 
-Fimo ships skills and rules for your AI coding tools (Claude Code, Cursor, Codex, Gemini, and more) so the agent knows how to work in a Fimo project. `fimo init` installs them for you — add or refresh them any time (`--mode=copy` is required under npx):
+Fimo ships skills and rules for your AI coding tools (Claude Code, Cursor, Codex, Gemini, and more) so the agent knows how to work in a Fimo site. `fimo init` installs them for you — add or refresh them any time (`--mode=copy` is required under npx):
 
 ```bash
 npx fimo@latest skills install --mode=copy
@@ -47,7 +47,7 @@ npx fimo@latest skills install --mode=copy
 
 ## Local development
 
-A Fimo project is a standard framework application. Run its normal package scripts:
+A Fimo site is a standard framework application. Run its normal package scripts:
 
 ```bash
 npm install

package/assets/agent-templates/_default/GOAL.md

@@ -16,6 +16,6 @@ Adapt these defaults to the risk and scope of this agent:
 
 - Proceed without asking when the work is within scope and a safe, reversible choice exists.
 - Ask when a missing human decision changes what the correct result should be.
-- Retain when the work is complete but all changes should be reviewed before merge.
-- Request merge only when the result is complete, verified, and clearly safe for this agent's scope.
+- Keep work open and request review when a human decision or approval is needed.
+- Merge completed, verified work within scope when runtime:auto_merge is granted; otherwise request human review.
 - Discard when the run produced no useful changes or deliberately abandoned them.

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

@@ -8,3 +8,4 @@
 - fimo:history:read
 - fimo:logs:read
 - fimo:preview:read
+- runtime:auto_merge

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

@@ -1,2 +1 @@
-- net:fetch
 - fimo:analytics:read

package/assets/agent-templates/content-translator/GOAL.md

@@ -16,8 +16,7 @@ JSON files or put translated values in source code.
 For each entry:
 
 1. Read the default-locale field via `cms:read`.
-2. Translate to every missing locale (via `net:fetch` to your translation
-   provider of choice).
+2. Translate to every missing locale.
 3. Write the translation back to the matching locale entry via `cms:write`.
 4. For static UI labels, update values with the i18n/labels API rather
    than editing files.

package/assets/agent-templates/content-translator/capabilities.yaml

@@ -1,6 +1,5 @@
-# Reads CMS and writes DB-backed localized content / labels. Net is for the translation provider.
+# Reads CMS and writes DB-backed localized content / labels.
 - cms:read
 - cms:write
 - i18n:read
 - i18n:write
-- net:fetch

package/assets/agent-templates/post-deploy-check/capabilities.yaml

@@ -1,2 +1 @@
-- net:fetch
 - fimo:logs:read

package/assets/agent-templates/seo-audit/capabilities.yaml

@@ -1,4 +1,3 @@
 # Read-only audit — no writes to project files or CMS.
 - cms:read
-- net:fetch
 - fimo:analytics:read

package/assets/skills/fimo/SKILL.md

@@ -1,10 +1,11 @@
 ---
 name: fimo
 description: >-
-  Working in or with a Fimo project (a content + media + forms + analytics
+  Working in or with a Fimo site (a content + media + forms + analytics
   platform for web applications). Load the current Fimo skills on demand through
   the `fimo` CLI before doing Fimo work — writing schema-driven
-  code, running CLI/deploy workflows, using the dashboard, or migrating a site.
+  code, planning, recommendations, design, copy, running CLI/deploy workflows,
+  using the dashboard, or migrating a site.
 ---
 
 # Fimo
@@ -27,10 +28,16 @@ Reference paths mentioned in streamed skill output, such as `references/media.md
 not files in the project. Load them through the CLI, for example
 `<fimo-cli> skills get fimo-cli --ref media`. Do not use a filesystem read tool for them.
 
+Before reasoning about an existing site's goals, recommendations, design, copy, content, or code,
+read its shared knowledge with `<fimo-cli> knowledge get --project <id> --json` (omit `--project` in a
+linked checkout). Load the detailed rules with `<fimo-cli> skills get fimo-cli --ref knowledge`.
+Refresh when switching sites or starting a new task. Empty knowledge does not block work; never
+save inferred guidance automatically. Write only when explicitly asked and authorized.
+
 Pick by task:
 
 - Writing code — schemas/forms, generated clients, labels, framework adapters, rendering primitives → `fimo-code`
-- Project creation, local setup, cloning, and CLI workflows — init, push, deploy, sync, labels, domains, analytics → `fimo-cli`
+- Site creation, local setup, cloning, and CLI workflows — init, push, deploy, sync, labels, domains, analytics → `fimo-cli`
 - Fimo agents — create, configure, validate, deploy, run, or inspect them → `fimo-cli` (`references/agents.md`)
 - AI agent setup — connect Claude Code, Codex, Cursor, or another agent → `fimo-cli` (`references/agent-setup.md`)
 - Remote MCP integrations — add, inspect, search, or run an MCP server → `fimo-cli` (`references/mcp.md`)
@@ -38,7 +45,7 @@ Pick by task:
 - Migrating an existing site into Fimo → `fimo-migration`
 
 For project setup, load `fimo-cli` first. Its `references/init.md` decision tree distinguishes a new or empty
-project, an existing Fimo project, and an external migration; load `fimo-migration` for the last path.
+project, an existing Fimo site, and an external migration; load `fimo-migration` for the last path.
 
 If a confirmed Fimo platform failure or missing capability materially blocks the task, finish or safely preserve the main work first, then use the built-in `supportReport` tool. Load the `fimo-cli` support instructions for the reporting criteria.
 

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

@@ -1,7 +1,7 @@
 ---
 name: fimo-cli
 description: >-
-  Use the `fimo` CLI to create or operate a Fimo project: content, forms,
+  Use the `fimo` CLI to create or operate a Fimo site: content, forms,
   media, labels/locales, deploys, Branches, Environments, domains, analytics,
   integrations, Fimo agents, collaboration, accounts, and credits. Also use
   for AI agent or MCP setup and confirmed Fimo platform blockers.
@@ -9,7 +9,7 @@ description: >-
 
 # Fimo CLI
 
-The `fimo` CLI is the workflow surface for Fimo. Fimo connects content, media, forms, analytics, editing, and hosting to web applications. The CLI handles project creation, content / forms / media / labels / locale workflows, deploys, collaboration, account management, Fimo agents, AI credit inspection, and AI agent setup.
+The `fimo` CLI is the workflow surface for Fimo. Fimo connects content, media, forms, analytics, editing, and hosting to web applications. The CLI handles site creation, content / forms / media / labels / locale workflows, deploys, collaboration, account management, Fimo agents, AI credit inspection, and AI agent setup.
 
 This skill describes **what the CLI does and the workflows it drives**. For the package surface used IN code (component props, generated hooks, JSON shapes, code-side rules), load the `fimo-code` skill on demand with `fimo skills get fimo-code`, using the invocation prefix below.
 
@@ -17,6 +17,13 @@ Use `fimo <command> --help` for full flag details on any command.
 
 > Verify a destination with `fimo webhooks test <id> --wait` and inspect its delivery history before depending on it in production.
 
+## Shared site knowledge
+
+Before site planning, recommendations, design, copy, content, or code work, read the site's
+knowledge: `fimo knowledge get --project <id> --json` (omit `--project` in a linked checkout).
+Use the selected CLI invocation. Load `fimo skills get fimo-cli --ref knowledge` for refresh,
+empty-state, and explicit-write rules. This prerequisite also applies when entering this skill directly.
+
 ## Running the CLI
 
 Use **`npx fimo@latest`** by default. If the initiating prompt supplies another Fimo CLI selector, such as `npx fimo@staging` or `npx fimo@0.14.0`, preserve that selector for every Fimo command in the same flow. Do **not** install `fimo` globally.
@@ -40,11 +47,11 @@ Pretty output may hide URLs behind clickable labels. Agents should use `--json`
 
 ## Critical: `.fimo/project.json` is the project link
 
-A Fimo project is identified by `.fimo/project.json`, written by `fimo init`. This file connects the local directory to the remote Fimo project. **Never edit it manually.** Most CLI commands find it by walking up from the cwd.
+A Fimo site is identified by `.fimo/project.json`, written by `fimo init`. This file connects the local directory to the remote Fimo site. **Never edit it manually.** Most CLI commands find it by walking up from the cwd.
 
 ## 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. Analytics reads are the exception: they default to canonical `prod`, independent of the checkout; see `references/analytics.md`. Annotation writes keep the current or explicit Branch. 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`.
+A project can have multiple **Branches** — each is a git branch _plus_ its own DB, sandbox, preview, and assets. Site-scoped commands (`deploy`, `status`, `entries`, `diff`, …) operate on the Branch matching the **current git branch**, and print a one-line banner saying which one. Analytics reads are the exception: they default to canonical `prod`, independent of the checkout; see `references/analytics.md`. Annotation writes keep the current or explicit Branch. New sites 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
 
@@ -64,7 +71,7 @@ fimo deploy                                    # ON-DEMAND: hosted project previ
 fimo deploy --publish                          # ON-DEMAND: publish live (only when the developer says "ship it")
 ```
 
-New projects use the Next.js App Router template by default. Fimo's canonical React Router template is selected explicitly with `--framework react-router`; use `--framework vite` for a React SPA.
+New sites use the Next.js App Router template by default. Fimo's canonical React Router template is selected explicitly with `--framework react-router`; use `--framework vite` for a React SPA.
 
 The working loop is local: run the app with the project's package-manager `dev` script (`pnpm dev` / `npm run dev` / `yarn dev` / `bun dev` — match the lockfile), ask the developer what they want, edit, and iterate against the live localhost server. Outside the first-time onboarding rule below, `fimo deploy` is **not** a required final step — reach for it only when the developer wants a hosted project preview or to go live, and only on their signal (see `references/deploy.md`).
 
@@ -78,7 +85,7 @@ Keep `fimo validate --json` at the front of the project's `build` script, which
 
 Load the matching reference when the user's request fires its trigger. Recipes that involve writing code also need the `fimo-code` skill's package references — they're called out where relevant.
 
-- "Create a new Fimo project / scaffold a site / start a new website / link an existing project locally" → `references/init.md`
+- "Create a new Fimo site / scaffold a site / start a new website / link an existing project locally" → `references/init.md`
 - "Add a content type / blog / products / content schemas / CMS" → `references/content.md` (workflow) **+ run `fimo skills get fimo-code --ref content/schema` and load the detected framework reference**
 - "Declare Pages routes / configure Pages sources or route params / control what Studio shows for a route" → `references/pages.md`
 - "Add a contact / signup / feedback / newsletter form" → `references/forms.md` (workflow) **+ run `fimo skills get fimo-code --ref forms` for the JSON spec and generated client**
@@ -107,7 +114,6 @@ 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`
@@ -123,7 +129,7 @@ Load the matching reference when the user's request fires its trigger. Recipes t
 These fire at specific moments in the project lifecycle. **Surface them proactively** rather than waiting for the user to ask:
 
 - **Right after `fimo init`** → `cd` into the new directory, read the project's `AGENTS.md` (or `CLAUDE.md` for Claude Code), run `fimo describe --json`, then load `fimo-code` and only the task/framework references it routes to. The rules file came into existence mid-session and may not be auto-loaded by the harness. See `references/init.md` § Load the project context.
-- **When `fimo init` created or scaffolded a new project (create-new path, including a Studio-supplied `--project-id`)** → after init and context loading succeed, run the single first-preview deploy and return the preview and dashboard links — see `references/init.md` § Create the first hosted preview. That deploy is also the sandbox warm-up; never run a separate warm-up deploy. Skip it only if the user explicitly said not to deploy. Linking a project with existing code and migrations keep their own approval rules.
+- **When `fimo init` created or scaffolded a new site (create-new path, including a Studio-supplied `--project-id`)** → after init and context loading succeed, run the single first-preview deploy and return the preview and dashboard links — see `references/init.md` § Create the first hosted preview. That deploy is also the sandbox warm-up; never run a separate warm-up deploy. Skip it only if the user explicitly said not to deploy. Linking a project with existing code and migrations keep their own approval rules.
 - **Right after `fimo init`** → suggest `fimo rename "<Display Name>"` to set a human-readable name (the default post-init name is an auto-generated slug). Infer the name from what the user is building (e.g. "Acme Coffee" for a café, "Jane Doe Portfolio" for a personal site). See `references/init.md`.
 - **Right after `fimo init`** → start the app locally with the project's package-manager `dev` script (`pnpm dev` / `npm run dev` / `yarn dev` / `bun dev`) in the background. This localhost server with live reload is your iteration loop — edit, show, repeat. No deploy is needed to see local changes. If the initiating request did not say what to build, ask the developer — after the first preview on the create-new path, never as a blocker before initializing.
 - **When a user-visible unit of work looks done outside first-time onboarding** → **offer** to deploy (`fimo deploy` for a hosted project preview, `fimo deploy --publish` to go live) and run it only after the developer confirms — or immediately if they ask. Never deploy ordinary edits on your own. See `references/deploy.md`.
@@ -132,14 +138,14 @@ 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`.
+- **When a project agent has stopped and is waiting on a person** → a project member answers its question in Studio, on the run's page; the question email links there. The CLI cannot answer it. Never answer on the person's behalf.
 - **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).
 
 ## Anti-Patterns
 
-- **Editing `.fimo/project.json`** — read-only; it's the link between local and remote project. Treat as a generated file.
+- **Editing `.fimo/project.json`** — read-only; it's the link between local and remote site. Treat as a generated file.
 - **Treating `fimo deploy` as the working loop or a required final step** — the loop is local (`pnpm dev` etc.). Deploy commits + pushes + round-trips the sandbox; it's for hosted previews / going live, on-demand. Iterate locally and deploy at logical breakpoints. See `references/deploy.md`.
 - **Deploying without the developer asking or confirming** — new-project onboarding authorizes exactly one automatic first preview deploy (unless the user said not to deploy); every other deploy is offer-then-confirm. Don't auto-deploy after finishing an ordinary edit.
 - **Running `fimo deploy` just to get the current preview URL** — that's a commit + push + sandbox sync when only destination resolution is needed. Use `fimo preview url` instead. See `references/preview.md`.

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

@@ -38,10 +38,10 @@ fimo agents secrets remove <name> <KEY> [-C <dir>]
 ```
 
 - **`list-templates`** — list the bundled starter templates with the first line of each template's `GOAL.md` as a summary. Ships with the CLI binary; no API call. The five bundled templates are `_default`, `seo-audit`, `content-translator`, `broken-link-sweeper`, `post-deploy-check`.
-- **`create <name>`** — scaffold `.fimo/agents/<name>/` from a template (default `_default`, a minimal valid bundle with a manual trigger). `--description <text>` writes a one-line tagline into the scaffolded `config.yaml` (surfaces in the dashboard's agents list). When run **without** `-C`, it requires the cwd to be inside a real Fimo project (walks up for `.fimo/project.json` or legacy `.fimo.settings.json`) and errors out cleanly otherwise, so it never leaks an agent bundle into a stray cwd. If the template declares capabilities, an install-consent flow runs after the copy (`--quiet` skips it; critical caps still abort). Keep the scaffolded `runtime` block as is unless the author asks for a different credit limit; see the `runtime` reference below before adding any limit key.
+- **`create <name>`** — scaffold `.fimo/agents/<name>/` from a template (default `_default`, a minimal valid bundle with a manual trigger). `--description <text>` writes a one-line tagline into the scaffolded `config.yaml` (surfaces in the dashboard's agents list). When run **without** `-C`, it requires the cwd to be inside a real Fimo site (walks up for `.fimo/project.json` or legacy `.fimo.settings.json`) and errors out cleanly otherwise, so it never leaks an agent bundle into a stray cwd. If the template declares capabilities, an install-consent flow runs after the copy (`--quiet` skips it; critical caps still abort). Keep the scaffolded `runtime` block as is unless the author asks for a different credit limit; see the `runtime` reference below before adding any limit key.
 - Every generated `config.yaml` includes `model: openai/gpt-5.6-luna`. Change that top-level value to another supported Fimo text model when needed; bundles without `model` keep the Luna fallback. Deploy after changing it because cloud runs use the deployed bundle.
 - **`list`** — list the agents declared under `<project>/.fimo/agents/` (or legacy root `agents/`), with each one's trigger types and capability count. Local — the bundle list is the source of truth even if the project isn't linked yet.
-- **`validate [name]`** — run the full validation pipeline: parse → capability vocabulary → composition (cycle / missing sub-agents / invalid grants) → semantic + Fimo project config policy checks. Omit `name` to validate every bundle. `--json` emits a structured `ValidationReport` for CI; exit code is non-zero on any failure.
+- **`validate [name]`** — run the full validation pipeline: parse → capability vocabulary → composition (cycle / missing sub-agents / invalid grants) → semantic + Fimo site config policy checks. Omit `name` to validate every bundle. `--json` emits a structured `ValidationReport` for CI; exit code is non-zero on any failure.
 - **`secrets add/remove/list`** — edit or inspect the agent's requested secret names in `.fimo/agents/<name>/config.yaml` (or legacy root). These commands do not create, rotate, or reveal secret values. Store values with `fimo secrets add`; run `fimo agents validate` to check that required requested secrets exist in the project. See `references/project-vars-and-secrets.md`.
 - **`integrations <name>`** — preview the agent's `integrations` allowlist from `.fimo/agents/<name>/config.yaml` (or legacy root) and, when linked, overlay project integration status. See `references/integrations.md`.
 
@@ -77,25 +77,20 @@ runtime:
 All four keys are optional; an absent `runtime` block behaves as if every key were unset. There is no platform step cap
 and no platform per-run 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.
+(`max_steps`, `budget_exceeded`, or `insufficient_credits`), 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.
-The agent works only in that checkout. Extra branches, worktrees, and `git push` are unsupported and cannot be cleaned up
-or handed off correctly.
+Runs perform compute; explicit work sessions hold project changes. Ordinary conversation and research need no session.
+Project operations name their session. Save accumulated work before a risky operation or handoff. A confirmed save
+commits and pushes without merging or publishing; Fimo also attempts a bounded save when compute ends.
 
-- **Merge** when the work is ready for the target Branch. Fimo applies the complete task environment or, if it conflicts,
-  leaves the target unchanged and keeps the work for review without choosing a side.
-- **Retain** when the completed work should be reviewed before merge, or when the run stops, fails, or may need recovery.
-  Fimo leaves the target unchanged, keeps the complete task Branch, and sends an Inbox notification asking a person to
-  review all of its changes. A later follow-up can continue from that retained work.
-- **Discard** when none of the run's work should be applied, including when it made no useful changes or deliberately
-  abandoned an approach. This permanently deletes the task Branch and every change in it without review.
+Merge ready work explicitly. Resolve clear conflicts through the existing merge tools; ask when the resolution requires
+product intent. Request review with one sessionId; request_review saves current work itself and makes that same session visible and durable. Inspecting or leaving a session open creates no review.
+Discard only unwanted work within the requested scope. Ending a run does none of these operations implicitly.
 
-If the agent exits without a decision, Fimo retains the task Branch. `fimo deploy` inside a run may build a preview of
-that Branch for inspection or screenshots; it does not finish or hand off the run.
+The autonomous `report` tool records a structured report without ending compute or deciding session fate. The model may
+continue working after reporting. A normal model stop ends compute. Scheduled work has no implicit publication grant.
 
 The run report is a concise outcome summary: what changed, what was verified, and what is still blocked. It is not a
 chronological account, and it should not use decorative emoji.
@@ -106,18 +101,22 @@ When authoring or editing an agent, add a short **Decision policy** to its `GOAL
 acting, asking, review, and merge; do not copy Fimo's tool protocol. Use this shape and replace the examples with rules
 specific to the agent:
 
+Infer the intended autonomy from the user's request when it is clear. Otherwise ask what the agent may apply itself,
+what needs review, and whether it may publish. Record that policy in `GOAL.md`; do not impose review-first on every
+agent or treat permission to merge as permission to publish. A routine fixer and a proposal writer need different policies.
+
 ```md
 ## Decision policy
 
 - Proceed without asking when the work is within scope and a safe, reversible choice exists.
 - Ask when a missing human decision changes what the correct result should be.
-- Retain when the work is complete but all changes should be reviewed before merge.
+- Request review of the saved session when completed work needs a person's approval before merge.
 - Request merge only when the result is complete, verified, and clearly safe for this agent's scope.
 - Discard when the run produced no useful changes or deliberately abandoned them.
 ```
 
-Asking and review are different: `ask_user` is for a decision required before correct work can continue; `retain` ends
-the run with its complete proposal waiting for review and does not ask a question.
+`ask_user` requests a blocking decision and ends the current invocation. `request_review` saves and captures one selected session for approval
+without ending compute. Neither operation merges or discards sessions.
 
 Make those rules concrete enough that the agent can decide without guessing. For example:
 
@@ -126,8 +125,7 @@ Make those rules concrete enough that the agent can decide without guessing. For
   verification is blocked. Discard when the scan is clean or exploratory edits were reverted.
 - **Launch-copy agent:** draft from an approved brief without asking about routine wording. Ask before choosing pricing,
   product promises, brand direction, or deletions. Retain every completed draft for human review; never request merge.
-- **Read-only auditor:** inspect and report autonomously. Ask only when the requested scope cannot be inferred. Discard
-  the unchanged task environment after recording the report.
+- **Read-only auditor:** inspect and report autonomously. Ask only when the requested scope cannot be inferred.
 - **Missing capability:** ask once for the exact capability and explain which operation it unlocks. Do not retain partial
   work as a substitute for the blocking permission decision.
 
@@ -143,10 +141,10 @@ A review-first content agent could use this complete policy:
 - Discard only when no useful draft was produced or the attempted approach was fully abandoned.
 ```
 
-When a run cannot continue correctly without a decision from a project member, it may call `ask_user` instead. The
-question goes to the Fimo Inbox, the current invocation ends, and Fimo keeps the same task Branch and environment until
-an authorized member answers. The answer starts one ordinary continuation in the same run thread; the original model
-process does not wait.
+When a run cannot continue correctly without a decision from a project member, it may call `ask_user` instead. Fimo
+emails project members a link to answer it in Studio, and the current invocation ends. It can reference zero or more
+sessions. An authorized answer starts a continuation in the same thread; the referenced work stays open and the original
+model process does not wait.
 
 Use `ask_user` sparingly, especially from scheduled agents:
 
@@ -156,7 +154,7 @@ Use `ask_user` sparingly, especially from scheduled agents:
 - Use choices for compact text options. Use cards only when an option benefits from an image or a richer title and
   subtitle. Use assets when the image itself is the answer, and tables when options need the same structured comparison.
 - Do not repeat a question or request already waiting in prior run history.
-- Use `finish_run` with `retain` when the work is ready for review but no answer is required.
+- Use `request_review` with one sessionId when approval is needed. No pre-save or promotion is required; other sessions stay unchanged and work can continue.
 
 An agent may include one multi-select `capabilities` step in that same form to request public Fimo capabilities it does
 not currently hold. Group related tokens in one request. Selected tokens apply only to the continuation started by that
@@ -169,12 +167,12 @@ behavior. Keep it under 4 KB, record no secrets or run log, and prune stale entr
 
 When three or more earlier runs still await a question answer, review, conflict resolution, or recovery, the agent
 normally starts no new independent work. Unless the current trigger explicitly asks it to proceed anyway, it makes no
-changes and finishes with `discard` and a brief report of what is waiting.
+changes and records a brief report of what is waiting.
 
 ## Define reporting preferences when they matter
 
-Fimo's default report needs no setup: a short, scannable brief appears in email and the Inbox, while the full report in
-Fimo carries the organized evidence and depth. Do not add a reporting section merely to restate that default.
+Fimo's default report needs no setup: a short, scannable brief appears in email, while the full report in Fimo carries
+the organized evidence and depth. Do not add a reporting section merely to restate that default.
 
 When the user names an audience, depth, recurring comparison, required section, or useful visual, preserve the request
 in a short **Reporting** section of `GOAL.md`. Describe the communication outcome in ordinary language. Do not prescribe
@@ -208,11 +206,11 @@ audience or emphasis. Even then, the brief remains the external handoff and the
 
 ## Capabilities
 
-Capabilities describe the opt-in Fimo and network actions an agent may take. Managed agents always receive project
-filesystem access, a shell, and the ability to commit their task-environment changes; Fimo owns branch creation and
-publication. If `capabilities.yaml` is absent or empty, the agent keeps baseline project reads such as agent run history,
-but receives no CMS, asset, or other domain-operation scope and no web-fetch tool. Once you add a capabilities file,
-list every Fimo or network permission the agent needs.
+Capabilities describe the opt-in Fimo actions an agent may take. Managed agents always receive project filesystem
+access, a shell, the ability to commit their task-environment changes, and web and data tools; Fimo owns branch creation
+and publication. If `capabilities.yaml` is absent or empty, the agent keeps baseline project reads such as agent run
+history, but receives no CMS, asset, or other domain-operation scope. Once you add a capabilities file, list every Fimo
+permission the agent needs. `net:fetch` is no longer needed and is ignored.
 Namespace selectors such as `cms:*`, `assets:*`, `i18n:*`, and `forms:*` grant every current and future declarable capability
 in that namespace. Fimo expands selectors to concrete grants when a run starts. Use exact tokens for narrower agents.
 The default template includes those four selectors plus read access to analytics, deployment logs, history, previews,
@@ -238,16 +236,15 @@ webhooks, and schedules; remove entries when an agent should have less access.
 | `fimo:preview:read`                         | Read a current preview URL                                                | Low          |
 | `fimo:history:read`                         | Read project restore points                                               | Low          |
 | `fimo:deploy`                               | Trigger a production deploy                                               | Critical     |
-| `net:fetch`                                 | Make outbound HTTP requests                                               | Medium       |
 | `agent:delegate`                            | Invoke declared sub-agents                                                | Medium       |
-| `runtime:auto_merge`                        | Auto-merge trivial proposed branches                                      | Critical     |
+| `runtime:auto_merge`                        | Merge work sessions without per-change review                             | Critical     |
 
 If a public Fimo capability is missing and the work is genuinely blocked, the agent can request it through `ask_user`.
 Fimo grants only the selected subset to the next invocation in that run thread. Unknown capabilities, internal runtime
 abilities, and capabilities the run already holds are refused before the question is stored. For durable access on
 ordinary future runs, add the capability to `capabilities.yaml`, validate, and deploy the bundle.
 
-Managed agents can list project agents and read their run history through baseline project access. This does not
+Managed agents can list project agents and read their run history through baseline site access. This does not
 require `fimo:agents:run`; that capability is only required to dispatch another agent.
 
 Studio chat and project-bound Slack turns receive `fimo:logs:read`. The default autonomous-agent template now declares
@@ -282,7 +279,7 @@ fimo agents report <name> [--session <id>] [--branch <branch>] [--project <id>]
   A refusal that clears on its own (`agent-paused`, `run-in-progress`, `task-branch-budget`) exits **0** and prints `Dispatch was skipped: <reason>`. **Pre-flight drift check**: if `.fimo/agents/<name>/` (or the legacy root bundle) has uncommitted git changes, the command refuses — the server would dispatch the _deployed_ version, so deploy first. Pass `--skip-drift-check` to dispatch the deployed bundle anyway. Defaults `--branch` to `main`.
 
 - **`runs <name>`** — list past run sessions for the agent in a compact table (id, started, duration, status, trigger, Branch, credits — settled credit consumption, `—` until a run settles). Default `--limit 20`; `--branch` filters to one Branch. The response uses the canonical `branch` field.
-- **`report <name>`** — print a run's structured **report**: its durable outcome summary (for a read-only agent like `seo-audit` this _is_ the audit; for a write agent it's a "what I changed" summary). A run that returns plain text without calling `finish_run` receives a small structured fallback document. With no `--session`, the most recent run for `<name>` is used (combine with `--branch` to scope); `--session <id>` targets a specific run. Output is projected Markdown, so it stays readable in the terminal and pipes cleanly (e.g. `fimo agents report seo-audit | glow`). If the run hasn't finished, or produced no report, it says so (and shows the stop reason when there is one).
+- **`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 `report` 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).
 
 ## How triggers get wired
 

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

@@ -1,9 +1,17 @@
 # Analytics workflow
 
-Pageview aggregates for the **published** site are stored in Fimo's analytics pipeline. Preview traffic is not recorded.
+Pageview aggregates are read for the selected branch. Reading analytics does not
+install tracking. For installation or missing pageview requests, load
+`fimo skills get fimo-code --ref analytics`. For zero counts, first check the
+branch, date range and device filter using the guidance below. A successful HTTP
+response alone does not establish that a row was stored.
 
 Analytics has a **retained preview for every org** — free included. The free default is a 7-day retention window, so short ranges (`today`, `yesterday`, `this_week`, `last_week`, `last_7_days`) work for everyone. **Extended date ranges and longer retention are paid** — `last_30_days`, `last_90_days`, `this_month`, `last_month`, `last_quarter`, `last_year`, and `custom` require the `canUseExtendedDateRanges` privilege, which only paid orgs have. Asking for an extended range as a free user returns a 403 with an upgrade hint.
 
+For Studio tracking verification, load `fimo-studio` and its analytics reference.
+Its tracking status is independent of the chart range and device filter; a failed
+status check is not evidence of missing tracking.
+
 ## Select published traffic
 
 For traffic, growth, or site-performance questions, read **`prod`**, regardless of the current Git branch, `FIMO_ENV`, or the source branch published to Production. Analytics reads (`pageviews`, `top`, `annotations list`) default to this canonical published target. On older CLI versions, select it explicitly:

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

@@ -8,7 +8,7 @@ New standalone projects start with one Branch: `main`. Linking an unversioned fo
 
 ## The Branch model — how every command picks its target
 
-**This is the single most important concept: project-scoped commands target the Branch matching the _current git branch_.** When you're on git branch `feat/seo`, `fimo deploy`, `fimo status`, `fimo entries list`, etc. all operate on the `feat/seo` Branch's DB / sandbox / preview. The CLI prints a one-line stderr banner telling you which Branch it resolved.
+**This is the single most important concept: site-scoped commands target the Branch matching the _current git branch_.** When you're on git branch `feat/seo`, `fimo deploy`, `fimo status`, `fimo entries list`, etc. all operate on the `feat/seo` Branch's DB / sandbox / preview. The CLI prints a one-line stderr banner telling you which Branch it resolved.
 
 ```bash
 fimo --branch <name> <command>  # peek at another Branch for one command (does not switch)

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

@@ -1,6 +1,6 @@
 # Credits
 
-`fimo credits` is a read-only command for checking the AI credit balance of the organization that owns a Fimo project. It resolves the project from `.fimo/project.json` unless `--project <project-id>` is provided.
+`fimo credits` is a read-only command for checking the AI credit balance of the organization that owns a Fimo site. It resolves the project from `.fimo/project.json` unless `--project <project-id>` is provided.
 
 ```bash
 fimo credits
@@ -9,7 +9,7 @@ fimo credits --project <project-id>
 fimo credits -C ./path/to/project
 ```
 
-This command is **project-scoped but not Branch-scoped**. It does not depend on the current git branch or `--branch`, because credits belong to the project's organization, not to a Branch.
+This command is **site-scoped but not Branch-scoped**. It does not depend on the current git branch or `--branch`, because credits belong to the project's organization, not to a Branch.
 
 ## Pretty Output
 

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

@@ -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 the project's configured Production source Branch. See `references/branches.md` for the multi-Branch workflow.
+`fimo deploy` uses the current Branch. New sites 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.
 

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

@@ -1,6 +1,6 @@
 # Describe — read-only snapshot of the current project
 
-`fimo describe` prints a structured snapshot of the Fimo project in the current working directory: project name + config version, detected framework, fimo package version, package manager, route / schema / locale counts, and a file tree.
+`fimo describe` prints a structured snapshot of the Fimo site in the current working directory: project name + config version, detected framework, fimo package version, package manager, route / schema / locale counts, and a file tree.
 
 It is **read-only**. Never writes, never hits the network. Safe to run any time.
 
@@ -76,4 +76,4 @@ The scoped view still emits the project-level metadata header (name, framework,
 
 - The JSON shape is stable; parse it rather than scraping the human output when you need a specific field.
 - `framework` is normally auto-detected. If it is `null`, inspect the project before choosing framework-specific guidance.
-- The command runs in any directory that contains `.fimo/project.json` or one of its ancestors. If you're not in a Fimo project, `describe` will run against whatever directory you point it at (it doesn't require Fimo credentials).
+- The command runs in any directory that contains `.fimo/project.json` or one of its ancestors. If you're not in a Fimo site, `describe` will run against whatever directory you point it at (it doesn't require Fimo credentials).

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

@@ -1,6 +1,6 @@
 # `fimo init`
 
-One-stop project setup: sign in, create a new Fimo project (or link an existing one), install dependencies, and optionally set up Fimo skills for your AI tools.
+One-stop project setup: sign in, create a new Fimo site (or link an existing one), install dependencies, and optionally set up Fimo skills for your AI tools.
 
 ## Command
 
@@ -11,7 +11,7 @@ fimo init [dir] [options]
 `fimo init` runs the full onboarding in one shot:
 
 1. **Signs in automatically** — if there's no session it opens the browser loopback login. In `--json` / non-TTY with no session it fails with `NOT_AUTHENTICATED` (run `fimo login` first).
-2. **Resolves the project** — with `--project-id <id>` it sets up the named Fimo project: a project with no code yet is scaffolded as a fresh site, while an existing repository is cloned. Without it, `init` creates a NEW project. An interactive TTY shows a "Create new / Link existing" picker; non-interactive shells default to create-new. New projects use the Next.js App Router by default; `--framework react-router`, `--framework vite`, `--framework astro`, and `--framework sveltekit` select the other minimal framework-native shells.
+2. **Resolves the project** — with `--project-id <id>` it sets up the named Fimo site: a project with no code yet is scaffolded as a fresh site, while an existing repository is cloned. Without it, `init` creates a NEW project. An interactive TTY shows a "Create new / Link existing" picker; non-interactive shells default to create-new. New sites use the Next.js App Router by default; `--framework react-router`, `--framework vite`, `--framework astro`, and `--framework sveltekit` select the other minimal framework-native shells.
 3. **Installs dependencies** — prompts for the package manager, or honor `--package-manager <pm>` / `--no-install`.
 4. **Optionally sets up Fimo skills** — confirm prompt, or `--skills` / `--no-skills`.
 
@@ -20,7 +20,7 @@ Generated pnpm projects pin `pnpm@10.26.0` and carry project-owned `pnpm-workspa
 | Flag                         | Required                      | Purpose                                                                                                                                                 |
 | ---------------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `[dir]` positional           | yes in non-TTY for create-new | Target directory (e.g. `my-site`)                                                                                                                       |
-| `--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.                                              |
+| `--project-id <id>`          | no                            | Set up the named Fimo site: 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                            | Rejected as a Branch selector; use `--branch <name>`.                                                                                                   |
@@ -95,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`). Without `--project-id`, `fimo init` creates a new project.
+Pass `--project-id <id>` to set up a known Fimo site. 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 site.
 
 ## Linking an existing local application
 
@@ -110,7 +110,7 @@ fimo link <projectId> --relink
 `fimo init` (create-new path) scaffolds:
 
 - The selected project shell: Next.js App Router by default, React Router with `--framework react-router`, a native React SPA with `--framework vite`, Astro with `--framework astro`, or SvelteKit with `--framework sveltekit`
-- `.fimo/project.json` — links this directory to the remote project (read-only after creation)
+- `.fimo/project.json` — links this directory to the remote site (read-only after creation)
 - `.fimo/config.json` — project, optional Studio Pages route metadata, locale, SEO, and agent policy
 - `.fimo/agents/` — versioned agent bundles
 - `AGENTS.md` + `CLAUDE.md` — project rules (from the template) read by AGENTS.md-compatible tools and Claude Code. Both point the agent at `fimo skills get` to load the real skills on demand.
@@ -149,7 +149,7 @@ After `fimo init` completes, the project root has `AGENTS.md` (universal) and `C
 
 **These files came into existence mid-session, so they may not be auto-loaded by the harness.** Explicitly:
 
-1. `cd <project-dir>` — switch into the new project.
+1. `cd <project-dir>` — switch into the new site.
 2. `Read` the project rules file: `AGENTS.md` (or `CLAUDE.md` if you're Claude Code).
 3. Run `fimo describe --json` with the current invocation prefix and read the detected framework, schemas, locales, and tree.
 4. Load the code skill on demand with the same prefix: `fimo skills get fimo-code`.
@@ -159,7 +159,7 @@ Do not batch-load every reference. Progressive disclosure keeps unrelated framew
 
 ### Create the first hosted preview (create-new path)
 
-Whenever `fimo init` created or scaffolded a new project — including a Studio-supplied `--project-id`, since Studio creates the project before any code exists — finish onboarding with exactly one plain preview deploy after init and context loading succeed, unless the user explicitly said not to deploy:
+Whenever `fimo init` created or scaffolded a new site — including a Studio-supplied `--project-id`, since Studio creates the project before any code exists — finish onboarding with exactly one plain preview deploy after init and context loading succeed, unless the user explicitly said not to deploy:
 
 ```bash
 fimo deploy -m "chore: first preview" --json

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

@@ -1,8 +1,8 @@
 # Integrations
 
-Use integrations to enable external services for a Fimo project. Firecrawl and Fal are built into Fimo: Fimo owns the provider account and bills the project in Fimo credits, so they take no API key at all. Every other credential (MCP servers, OAuth workspaces) is stored encrypted by Fimo and never printed back to the CLI. Teammates and agents receive access to the integration, not the underlying token.
+Use integrations to enable external services for a Fimo site. Firecrawl and Fal are built into Fimo: Fimo owns the provider account and bills the project in Fimo credits, so they take no API key at all. Every other credential (MCP servers, OAuth workspaces) is stored encrypted by Fimo and never printed back to the CLI. Teammates and agents receive access to the integration, not the underlying token.
 
-Start with `fimo integrations list` whenever the task could benefit from an external service. It is the project-scoped,
+Start with `fimo integrations list` whenever the task could benefit from an external service. It is the site-scoped,
 runtime-truthful inventory; use `info` only for the relevant integration instead of loading every provider's tools into
 context.
 

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

@@ -93,4 +93,4 @@ fimo invite --email "dev@agency.com" --role full
 - Invited users receive an email with a sign-up link if they don't have an account, or a sign-in link if they do.
 - Organization invites can be resent with `--resend` if the user didn't receive the original.
 - Project invites are scoped to a single project; organization invites grant access to all projects in that organization.
-- If `--cwd` is set and the directory belongs to a linked Fimo project, that project is auto-selected.
+- If `--cwd` is set and the directory belongs to a linked Fimo site, that project is auto-selected.