fimo 0.20.0 → 0.21.0-experimental.1

package/README.md

@@ -74,7 +74,7 @@ fimo deploy -m "your message"
 Go live to production:
 
 ```bash
-fimo publish --version 1.0.0
+fimo publish --label "Homepage launch"
 ```
 
 Environments work like git branches:

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

@@ -9,3 +9,13 @@ Some good things to include:
 - Inputs the agent should expect (CLI args, files, API responses)
 - Anything the agent should **not** do
 - The format of the report / output the agent should produce
+
+## Decision policy
+
+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.
+- Discard when the run produced no useful changes or deliberately abandoned them.

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

@@ -0,0 +1,10 @@
+- cms:*
+- assets:*
+- i18n:*
+- forms:*
+- webhooks:read
+- schedules:read
+- fimo:analytics:read
+- fimo:history:read
+- fimo:logs:read
+- fimo:preview:read

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

@@ -9,7 +9,7 @@
  */
 %>
 // AUTO-GENERATED ⚠️ – do not edit by hand
-import { type Fields, type FimoBoolean, type FimoMedia, type FimoPolymorphicReference, type FimoReference, type FimoRichText, type FimoRichTextContent, type FimoString, type Populate, type PopulatedResult, type ProjectedWithPopulate, type Query, type Sort, type Where, type WithReferences } from "<%= runtimeImport %>";
+import { <%= model.runtimeTypeImports.map((typeImport) => `type ${typeImport}`).join(', ') %> } from "<%= runtimeImport %>";
 <%
 if (model.referenceImports && model.referenceImports.length > 0) {
   model.referenceImports.forEach((referenceImport) => {

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

@@ -128,7 +128,8 @@ These fire at specific moments in the project lifecycle. **Surface them proactiv
 - **When the user wants to try something risky / explore a redesign without touching the live site** → suggest a feature Branch: `fimo checkout -b <name>` gives an isolated Branch + DB + preview. Deploy previews there, then `fimo merge` it back and `fimo publish`. See `references/branches.md`.
 - **After completing or safely preserving the user's main work, when a confirmed Fimo platform failure still materially blocks the task after one safe recovery attempt, or a confirmed missing capability blocks completion or forces a fragile or heavily manual workaround** → use the built-in `supportReport` tool. Do not wait for the user to ask and do not stop after only describing the gap. See `references/support.md`.
 - **After the first successful `fimo deploy`** → suggest `fimo invite` if the project involves multiple people. Typical roles: `edit` for developers/content editors, `view` or `comment` for clients/stakeholders, `full` for project leads. See `references/invite.md`.
-- **When the user wants to modify the URL of their website** → walk through `references/domains.md`. The CLI surface covers renaming the Fimo-provided subdomain (`fimo domains rename-default`, free), attaching a domain they already own (`fimo domains add`, Premium), and buying a new domain through Fimo (`fimo domains buy`, Premium). The auto-generated default URL on every project is a fallback, not a final choice — proactively offer this after `fimo deploy --publish` if the user mentioned a real brand or domain.
+- **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
 

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

@@ -22,7 +22,7 @@ fimo validate                 # project build and codegen checks
 fimo deploy                   # push to main — this also wires the declared triggers
 fimo agents run <name>        # trigger a manual run → sessionId
 fimo agents runs <name>       # see past sessions
-fimo agents report <name>     # print a run's report (the agent's final message)
+fimo agents report <name>     # print a run's outcome summary
 fimo agents logs <name>       # stream a session's log
 ```
 
@@ -56,44 +56,144 @@ integrations:
 An explicit map is restrictive: only entries set to `true` are available. An omitted or disabled integration cannot be
 used. See `references/integrations.md` for project setup, auth, and provider-specific commands.
 
+## 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.
+
+- **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.
+
+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 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.
+
+## Define the agent's decision policy
+
+When authoring or editing an agent, add a short **Decision policy** to its `GOAL.md`. Describe the domain conditions for
+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:
+
+```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 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.
+
+Make those rules concrete enough that the agent can decide without guessing. For example:
+
+- **Broken-link sweeper:** fix and request merge for up to ten internal links when each replacement is unambiguous and
+  the link check passes. Ask when two plausible destinations change the page's meaning. Retain useful fixes if complete
+  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.
+- **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.
+
+A review-first content agent could use this complete policy:
+
+```md
+## Decision policy
+
+- Draft all requested copy without asking when the brief and approved source material answer the content decisions.
+- Ask before inventing a price, product promise, legal claim, brand direction, or deleting existing content.
+- Group every blocking decision and missing capability into one question.
+- Retain every completed draft so a person reviews all changes before merge. Never request merge directly.
+- 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.
+
+Use `ask_user` sparingly, especially from scheduled agents:
+
+- Ask only for a genuinely blocking human decision. Prefer a safe reversible default when one exists.
+- Group every known blocker into one form with 1–4 related steps. Give it a 1–3 sentence description that says where
+  the work stands and why the decision matters or what it unlocks; keep implementation detail in the run.
+- 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.
+
+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
+answer; unselected tokens are denied, selecting none is valid, and the blocked invocation never gains new authority.
+Internal runtime abilities, integration setup, and OAuth are not capability requests.
+
+At the start of a run, `run_history` provides bounded summaries of earlier outcomes and work still awaiting a person. An agent
+may also maintain `.fimo/agents/<name>/MEMORY.md` as an ordinary reviewed file for durable facts that change future
+behavior. Keep it under 4 KB, record no secrets or run log, and prune stale entries before adding new ones.
+
+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.
+
 ## 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 has those project-worker tools but no Fimo API
-permissions or web-fetch tool. Once you add a capabilities file, list every Fimo or network permission the agent needs.
-There is no all-capabilities wildcard; keeping the list explicit makes each agent's power reviewable.
-
-| Capability                   | Allows the agent to                         | Risk         |
-| ---------------------------- | ------------------------------------------- | ------------ |
-| `cms:read`                   | Read CMS content                            | Low          |
-| `cms:write`                  | Create, update, or delete CMS entries       | Medium       |
-| `cms:schema:read`            | Read CMS schemas                            | Low          |
-| `cms:schema:write`           | Modify CMS schemas                          | High         |
-| `assets:read`                | Read uploaded media                         | Low          |
-| `assets:write`               | Upload, replace, or delete media            | Medium       |
-| `i18n:read` / `i18n:write`   | Read / modify translation catalogs          | Low / Medium |
-| `forms:read` / `forms:write` | Read / modify form schemas and submissions  | Low / Medium |
-| `webhooks:read`              | Read webhook configs and deliveries         | Low          |
-| `webhooks:write`             | Create, modify, delete, or trigger webhooks | High         |
-| `schedules:read`             | Read schedule configs and run history       | Low          |
-| `schedules:write`            | Create, change, or trigger scheduled runs   | Critical     |
-| `fimo:logs:read`             | Read project deployment logs                | Low          |
-| `fimo:analytics:read`        | Read analytics data                         | Low          |
-| `fimo:preview:read`          | Read a current preview URL                  | Low          |
-| `fimo:history:read`          | Read project restore points                 | Low          |
-| `fimo:deploy`                | Trigger a production deploy                 | Critical     |
-| `net:fetch`                  | Make outbound HTTP requests                 | Medium       |
-| `agent:delegate`             | Invoke declared sub-agents                  | Medium       |
-| `runtime:long_running`       | Run beyond the default time limit           | High         |
-| `runtime:auto_merge`         | Auto-merge trivial proposed branches        | Critical     |
-
-If a capability is missing, the related command is denied and the agent should choose another path or report the
-blocker. Add the capability to `capabilities.yaml`, run `fimo agents validate <name>`, deploy the bundle, and start a
-new run. A denied capability does not grant access to anything else.
-
-Studio chat and project-bound Slack turns receive `fimo:logs:read`. Autonomous agents receive it only when their
-`capabilities.yaml` declares it; use `fimo logs` with the deploy guidance when diagnosing a failed preview.
+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.
+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,
+webhooks, and schedules; remove entries when an agent should have less access.
+
+| Capability                                  | Allows the agent to                                                       | Risk         |
+| ------------------------------------------- | ------------------------------------------------------------------------- | ------------ |
+| `cms:read`                                  | Read CMS content                                                          | Low          |
+| `cms:write`                                 | Create, update, or delete CMS entries                                     | Medium       |
+| `cms:schema:read`                           | Read CMS schemas                                                          | Low          |
+| `cms:schema:write`                          | Modify CMS schemas                                                        | High         |
+| `assets:read`                               | Read uploaded media                                                       | Low          |
+| `assets:write`                              | Upload, replace, or delete media                                          | Medium       |
+| `i18n:read` / `i18n:write`                  | Read / modify translation catalogs                                        | Low / Medium |
+| `cms:*` / `assets:*` / `i18n:*` / `forms:*` | Every declarable capability in that namespace, including future additions | Mixed        |
+| `forms:read` / `forms:write`                | Read / modify form schemas and submissions                                | Low / Medium |
+| `webhooks:read`                             | Read webhook configs and deliveries                                       | Low          |
+| `webhooks:write`                            | Create, modify, delete, or trigger webhooks                               | High         |
+| `schedules:read`                            | Read schedule configs and run history                                     | Low          |
+| `schedules:write`                           | Create, change, or trigger scheduled runs                                 | Critical     |
+| `fimo:logs:read`                            | Read project deployment logs                                              | Low          |
+| `fimo:analytics:read`                       | Read analytics data                                                       | Low          |
+| `fimo:preview:read`                         | Read a current preview URL                                                | Low          |
+| `fimo:history:read`                         | Read project restore points                                               | Low          |
+| `fimo:deploy`                               | Trigger a production deploy                                               | Critical     |
+| `net:fetch`                                 | Make outbound HTTP requests                                               | Medium       |
+| `agent:delegate`                            | Invoke declared sub-agents                                                | Medium       |
+| `runtime:long_running`                      | Run beyond the default time limit                                         | High         |
+| `runtime:auto_merge`                        | Auto-merge trivial proposed branches                                      | 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
+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
+it too; custom templates still need to declare it before using `fimo logs` to diagnose a failed preview.
 
 Example for a content editor that can read and update entries but cannot change schemas:
 
@@ -113,7 +213,7 @@ 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.
-- **`report <name>`** — print a run's **report**: the agent's final message, captured when the run finishes (for a read-only agent like `seo-audit` this _is_ the audit; for a write agent it's a "what I changed" summary). With no `--session`, the most recent run for `<name>` is used (combine with `--branch` to scope); `--session <id>` targets a specific run. Output is raw markdown, so it stays readable in the terminal and pipes cleanly (e.g. `fimo agents report seo-audit | glow`). If the run hasn't finished, or produced no message, it says so (and shows the stop reason when there is one). This is the command to read what a run actually produced — see the `logs` note below.
+- **`report <name>`** — print a run's **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 never finalised falls back to its last message. With no `--session`, the most recent run for `<name>` is used (combine with `--branch` to scope); `--session <id>` targets a specific run. Output is raw markdown, so it stays readable in the terminal and pipes cleanly (e.g. `fimo agents report seo-audit | glow`). If the run hasn't finished, or produced no message, it says so (and shows the stop reason when there is one). This is the command to read what a run actually produced — see the `logs` note below.
 - **`logs <name>`** — stream a run's log (defaults to the latest session; `--session <id>` targets one). **Note:** the log-streaming endpoint is still a server-side stub at time of writing — the command prints a placeholder rather than real log lines. To read a finished run's output today, use `report`.
 
 ## How triggers get wired

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

@@ -35,7 +35,7 @@ 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`          | —                   | Tag `main@HEAD` as `release/<version>` and trigger the prod swap. See "Publishing" below.                                                                                    |
+| `fimo publish`          | —                   | Publish the already-synced `main` 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.
 
@@ -59,7 +59,7 @@ fimo preview url                 # canonical URL to open / screenshot the feat/s
 fimo status                      # see what changed vs main, surface by surface
 fimo checkout main               # back to main
 fimo merge feat/seo              # merge the Branch back into main (resolve conflicts)
-fimo publish --version 1.4.0     # tag a release + prod swap
+fimo publish --label "Homepage launch" --notes "Initial production publish"
 fimo branch -d feat/seo          # tear down the feature Branch
 ```
 
@@ -97,15 +97,18 @@ Syncs the current Branch's data plane from its parent (or `--from <ancestor>`).
 
 Two different "go live" mechanisms — don't confuse them:
 
-- **`fimo publish --version <ver> [--notes <md>]`** — the release path. Runs from `main` only, validates, tags `main@HEAD` as `release/<ver>`, and triggers the prod swap. `--skip-validate` is an operator override. This is the versioned, prod-facing publish.
+- **`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`.
 
-Use `fimo publish` for versioned prod releases; use `fimo deploy --publish` for the simple "ship what's on main now" flow. Both only run from `main`.
+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`.
 
 ## Anti-patterns
 
 - **Using `git checkout -b` instead of `fimo checkout -b`** — raw git creates the branch but **not** the Branch's DB / sandbox / preview. Always use `fimo` for Branch operations so resources are provisioned atomically. (Running `fimo branch <name>` after the fact provisions them.) The running app itself follows the git branch either way.
-- **Hardcoding the tenant API URL** — the app derives it from the git branch and `.fimo/project.json`. Set `VITE_API_URL` / `NEXT_PUBLIC_FIMO_API_URL` yourself only as a deliberate override (e.g. a local API); it then wins over derivation on every branch.
+- **Hardcoding the tenant API URL** — the framework runtime derives it from the
+  git branch and `.fimo/project.json`. Use an explicit host variable only as a
+  deliberate override, such as a local API; it then wins over derivation on
+  every branch.
 - **Trying to push to or delete `prod` / `release/*`** — these are read-only/protected. Publish to update prod; never push.
 - **`fimo merge` straight onto `main` as a habit** — it's gated for a reason. Merge on a branch, then publish.
 - **Confusing `fimo switch` (Branch) with `fimo orgs switch` (org).**

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

@@ -56,6 +56,15 @@ Use the publication ID returned by the failed command: run `fimo publish inspect
 
 If the sandbox fails to install dependencies or start the app, run `fimo logs --json` before retrying. Read the newest install and dev-server events first; when the response is truncated, use its `previousCursor` as `fimo logs --before <cursor> --json` to fetch the preceding page. Do not recreate or replace the sandbox before collecting logs, because that can discard the failure evidence.
 
+When Preview reports blocked dependency build scripts, treat that as a project security-policy repair, not a transient sandbox failure. Review every named package before approving it, then use the package manager's narrow project-owned mechanism:
+
+- **pnpm:** add each approved package to `allowBuilds` in `pnpm-workspace.yaml`.
+- **Yarn:** set `dependenciesMeta.<package>.built` in `package.json` for each approved package.
+- **Bun:** add approved packages to `trustedDependencies` in `package.json`, or run the exact `bun pm trust <packages>` command Preview reports.
+- **npm:** npm has no equivalent per-package approval error. Diagnose the failing lifecycle script itself; do not turn a generic npm script failure into a trust-policy change.
+
+Run the same plain install locally and commit the policy plus lockfile before retrying Preview. Never bypass the error with `dangerouslyAllowAllBuilds`, `enableScripts`, or another global allow-all switch: Preview and publishing intentionally consume the committed project policy.
+
 ## Framework hosting
 
 Fimo preview resolves `runtime.commands` override → package script → detected
@@ -113,9 +122,9 @@ 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 --version <ver> [--notes <md>]`** — the **versioned release** path. From `main`, it validates, tags `main@HEAD` as `release/<ver>`, and triggers the prod swap. Use this when the user wants a real, tagged production release (e.g. "cut v1.4.0", "publish a new version"). See `references/branches.md`.
+- **`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`.
 
-When unsure, `fimo deploy --publish` is the lighter-weight default; reach for `fimo publish` only when versioning/release semantics are wanted.
+When unsure, use `fimo deploy --publish` so the local revision is pushed before it goes live. Use `fimo publish` when `main` is already synced.
 
 ## Markdown for AI agents
 

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

@@ -56,6 +56,18 @@ When a user says "I want to change my website's URL," ask which case fits:
 
 If they aren't sure, run `fimo domains suggest-default` first — it's free, takes one step, and a good fallback if they don't want to commit to a domain purchase.
 
+## Offer a cleaner default URL before first publish
+
+After the automatic first-preview deploy on a newly created project, offer a cleaner free `*.fimo.site` URL before the first public publish when there is no custom domain and the current default slug still looks generated or was never explicitly chosen. Choosing it now lets the first public launch use the clean URL. Skip the offer if the user already chose the default slug, attached a custom domain, or declined.
+
+The default URL is free and needs no DNS. A custom domain is the separate Premium workflow above. A default slug can be reserved before publication, but it returns "Project Not Found" until the site is published. Renaming changes the address that will become public, so never silently claim a suggestion:
+
+1. Run `fimo domains suggest-default --base "<brand>" --json` to get candidates.
+2. Show the candidates and ask the user to choose one explicitly.
+3. After confirmation, run `fimo domains rename-default <slug>` or `fimo domains suggest-default --pick <slug>`.
+
+Choosing the slug does not publish the site. The first successful `fimo deploy --publish` makes the renamed URL resolve.
+
 ## Pricing & how money moves
 
 The CLI never charges directly. Two distinct money paths:

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

@@ -54,7 +54,7 @@ Use this when the user asks "who filled out the contact form?", "how many signup
 
 ## When to run sync manually
 
-The `fimo/vite` plugin regenerates legacy Vite `src/forms/*.ts` after form JSON changes during development. Framework-aware generation runs during validation. Before a production build, regenerate explicitly with:
+The `fimo-vite` plugin regenerates legacy Vite `src/forms/*.ts` after form JSON changes during development. Framework-aware generation runs during validation. Before a production build, regenerate explicitly with:
 
 ```bash
 fimo validate                  # runs all phases: codegen, lint, route validation, label checks

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

@@ -15,6 +15,8 @@ fimo init [dir] [options]
 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`.
 
+Generated pnpm projects pin `pnpm@10.26.0` and carry project-owned `pnpm-workspace.yaml#strictDepBuilds: true` and `#allowBuilds` settings. Generated Bun projects trust the same required packages through `package.json#trustedDependencies`. Keep the selected package manager's policy committed. When adding a dependency with an install script, review it before extending that policy; never replace it with a blanket allow-all install.
+
 | Flag                         | Required                      | Purpose                                                                                                                                                        |
 | ---------------------------- | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `[dir]` positional           | yes in non-TTY for create-new | Target directory (e.g. `my-site`)                                                                                                                              |
@@ -102,7 +104,6 @@ Pass `--project-id <id>` to set up a known Fimo project. If the project has no c
 - `.fimo/project.json` — links this directory to the remote project (read-only after creation)
 - `.fimo/config.json` — project, optional Studio Pages route metadata, locale, SEO, and agent policy
 - `.fimo/agents/` — versioned agent bundles
-- `.env` — framework-specific tenant content API URLs for local development
 - `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.
 - A git repository with `fimo` as the remote, and — after dependencies install — an initial commit (including the lockfile) plus an initial push
 
@@ -118,7 +119,11 @@ Nothing is written into per-agent skill dirs: the rich skills are fetched on dem
 
 Codex, OpenCode, Aider, and similar AGENTS.md-native tools work directly off AGENTS.md.
 
-`.env` is only the bootstrap app env so local `pnpm dev` works immediately. Fimo writes the tenant API aliases used by its supported frameworks; users should not discover or set those URLs manually. User-managed public variables are stored with `fimo vars add` and synced into a managed `.env.local` block; hidden values use `fimo secrets add`. See `references/project-vars-and-secrets.md`.
+Supported framework runtimes derive the Fimo connection from
+`.fimo/project.json` and the active git branch, so local development needs no
+Fimo env file. User-managed public variables are stored with `fimo vars add`
+and synced into a managed `.env.local` block; hidden values use
+`fimo secrets add`. See `references/project-vars-and-secrets.md`.
 
 ## Right after scaffolding
 
@@ -163,6 +168,8 @@ fimo deploy -m "chore: first preview" --json
 
 This first deploy creates a preview only — never add `--publish`, and treat every later deploy as offer-then-confirm. The rule does not apply when `init` cloned a project with existing code or when the work is a migration; those paths keep their normal deployment approval rules.
 
+After the preview succeeds, follow `references/domains.md` § Offer a cleaner default URL before first publish. Reserve a slug only after the user chooses it; the URL will not resolve until the site is published.
+
 ## Adding another AI tool to an existing project later
 
 If a teammate joins on a different AI tool (e.g. Cursor) after the project was scaffolded for claude-code only:

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

@@ -104,7 +104,7 @@ These canonical entries are also the optional metadata used by Studio Pages. See
 
 For every framework, the application owns its URL scheme, resolves the locale, and passes it into Fimo. Studio stores the locale the app reports for the current location — including when only the locale changed — and reads content in it. Route metadata is optional unless the project wants Fimo Studio route selection/navigation.
 
-Astro and Next express the same optional-locale semantic with paired native filesystem route trees: an unprefixed default-locale tree and a prefixed non-default tree. Neither framework supports an optional single-segment filesystem folder.
+Neither Astro nor Next supports an optional single-segment filesystem folder. Astro's starter expresses an optional-locale semantic with paired native filesystem route trees. The Next starter is default-only; a Next application adds a `[locale]` tree or another application-owned strategy only when the product requires locale URLs.
 
 ## Migrate An Existing Locale System
 

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

@@ -60,7 +60,7 @@ The Project MCP catalog covers:
 - **Identity and navigation** — current user, projects, and Branches.
 - **Content** — schemas, collection entries, search, create/update/delete, bounded bulk operations, and Singles.
 - **Labels** — list, read, set, batch-set, and delete localized labels.
-- **Media** — list and inspect assets, generate images or videos, create folders, move, and delete assets. Binary
+- **Media** — list and inspect assets, read canonical pages or ask one targeted question with `assets_read`, generate images or videos, create folders, move, and delete assets. Binary
   upload remains `fimo assets upload`.
 - **Forms** — create, read, update, and delete forms; inspect submissions and statistics.
 - **Files** — read, glob, grep, write, edit, and delete project files within the scoped Branch. Sensitive files

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

@@ -159,11 +159,28 @@ Do not generate when:
 
 Upload real files with `fimo assets upload`. Browse reusable media with `fimo assets list` before spending credits.
 
+## Inspect an existing asset
+
+Open the original when visual or binary inspection is required. Read canonical text when exact portable understanding
+is required:
+
+```bash
+fimo assets open <asset-id> --download
+fimo assets read <asset-id>
+fimo assets read <asset-id> --cursor <next-cursor>
+fimo assets read <asset-id> --query "<one targeted question>"
+```
+
+For a complete exact read, keep following `nextCursor` until `complete` is `true`. Never combine `--cursor` and
+`--query`. Complete readable interpretation is lazy and cached, separately from compact Media Library alt/caption
+metadata. A 3D read includes four reusable rendered views. Download ZIP archives and inspect them in the sandbox; do
+not expect server-side extraction.
+
 ## Verification
 
 After generation:
 
 1. Confirm the command exited successfully and returned an asset ID.
-2. Open or download the asset with `fimo assets open <id>`.
+2. Open the original with `fimo assets open <id>`, or read its canonical understanding with `fimo assets read <id>`.
 3. Verify it matches the request before inserting it into content or UI.
 4. Use the whole media value with Fimo's `<Image>` or `<Video>` components rather than raw HTML elements.

package/assets/skills/fimo-cli/references/project-vars-and-secrets.md

@@ -47,7 +47,9 @@ variables.
 
 ## Local Env Files
 
-`fimo init` and `fimo clone` write `.env` with the framework-specific tenant content API URLs needed for local development. These are Fimo-managed connection values, not project variables; users should not discover or set them manually.
+`fimo init`, `fimo clone`, and `fimo link` do not write the Fimo connection to
+an env file. Supported framework runtimes derive it from `.fimo/project.json`
+and the active git branch; hosted preview and production inject it directly.
 
 `fimo vars add`, `fimo vars update`, and `fimo vars pull` write public project variables to a managed block in `.env.local`.
 

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

@@ -18,7 +18,7 @@ fimo projects rename <name> [projectId] [-C <dir>]   # set seo.siteName in the l
 - **`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.
 - **`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). This is **not** the versioned release path — for that, see `fimo publish` in `references/branches.md`.
+- **`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).
 - **`rename`** — edits only the linked local project immediately. 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). It writes `seo.siteName` into the current or legacy project config; commit and run `fimo deploy` to reconcile the remote `displayName` and deploy the new site name.
 
 ## Top-level clone shortcut
@@ -41,12 +41,12 @@ fimo rename "<Site Name>"        # local edit: set seo.siteName in the project c
 
 `fimo rename` sets the **site name** (`seo.siteName`) in the local project config — it is a local edit, not an immediate remote update, so it requires a follow-up commit + `fimo deploy` to take effect. Deploy reconciles the project's remote `displayName` with the committed site name while pushing the config. See `references/init.md` and `references/deploy.md`.
 
-## Three "publish" verbs — don't confuse them
+## 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 --version <v>` | Tag `release/<v>` + trigger the prod swap (versioned release). |
+| 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. |
 
 See `references/deploy.md` and `references/branches.md` for the full picture.

package/assets/skills/fimo-code/assets/react-router-locales/navigation.tsx

@@ -1,4 +1,4 @@
-import { FimoLink } from 'fimo/react-router';
+import { FimoLink } from 'fimo-react-router';
 
 export function Navigation() {
   return (

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

@@ -24,7 +24,7 @@ Generated content reads wrap this stored value in `FimoMedia`, which exposes `ur
 
 ## Rendering in application code
 
-Import the primitives from the active framework adapter: `fimo/next` on the Next server, `fimo/next/client` in Next Client Components, `fimo/ui` in React Router/Vite, or `fimo/astro/components` in Astro pages.
+Import the primitives from the active framework adapter: `fimo-next` on the Next server, `fimo-next/client` in Next Client Components, `fimo-react` in React Router/Vite, or `fimo/astro/components` in Astro pages.
 
 | Asset source                                        | Component             | Pass via                  |
 | --------------------------------------------------- | --------------------- | ------------------------- |
@@ -32,7 +32,7 @@ Import the primitives from the active framework adapter: `fimo/next` on the Next
 | Hard-coded URL or generated asset referenced inline | `<StaticImage>`       | `src="https://..."`       |
 
 ```tsx
-import { Image, StaticImage, Video } from 'fimo/next';
+import { Image, StaticImage, Video } from 'fimo-next';
 
 // from a schema entry:
 <Image value={post.coverImage} width={1200} height={630} fit="cover" />

package/assets/skills/fimo-code/references/best-practices/next.md

@@ -13,7 +13,7 @@ Load `references/frameworks/next.md` and the matching router reference first. In
 
 ```ts
 import type { NextConfig } from 'next';
-import { withFimo } from 'fimo/next/config';
+import { withFimo } from 'fimo-next/config';
 
 const nextConfig: NextConfig = {
   cacheComponents: true,

package/assets/skills/fimo-code/references/content/schema.md

@@ -23,6 +23,29 @@ Write one schema per `src/schemas/<Uid>.json`. The PascalCase filename must matc
 
 Required root keys: `uid`, `name`, and `fields`.
 
+## Group fields in Studio
+
+Use optional top-level `groups` when an entry has meaningful editing areas, such as Overview, Tickets, SEO, or Scheduling. They work best for longer forms where editors regularly work on one area at a time. Usually skip groups for short forms, one-field groups, or vague buckets such as General and Other. Prefer two to five groups organized around editor tasks. This is guidance, not a schema limit.
+
+Assign each top-level field with `group`; one field may appear in more than one group. This changes only the Studio layout, not stored content, generated types, validation, permissions, or what agents can edit.
+
+```json
+{
+  "uid": "Event",
+  "name": "Events",
+  "groups": [
+    { "id": "overview", "label": "Overview", "default": true },
+    { "id": "tickets", "label": "Tickets" }
+  ],
+  "fields": {
+    "title": { "type": "string", "group": "overview" },
+    "price": { "type": "number", "group": ["overview", "tickets"] }
+  }
+}
+```
+
+Group IDs must be unique, at most one group may be the default, and memberships must reference a declared group. Only top-level fields can be grouped; fields inside blocks cannot declare `group`.
+
 Use `"isSingleton": true` whenever the site has exactly one logical document: a homepage, site settings, an About page, or one campaign landing page. Do not turn it into a one-entry collection just to seed content; keep the Single and load `fimo-cli/references/content.md` for the `fimo singles update` workflow.
 
 ```json

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

@@ -106,7 +106,7 @@ export function ContactForm() {
 
 ## Framework bindings
 
-- **Vite/React:** `submitX(data)` keeps using the existing `fimo/ui` runtime and preserves the current generated API.
+- **Vite/React:** `submitX(data)` keeps using the existing `fimo-react` runtime and preserves the current generated API.
 - **Next.js:** server modules import `@/forms/name`; client components import `@/forms/name.client`. Both expose the same `submitX(data)` shape.
 - **Astro:** import the generated server module and call `submitX(data)` in an Astro action or endpoint. Astro keeps the HTML form and redirect.
 - **SvelteKit:** use `createFimoFormClient({ event })` in a server action and pass it as the second argument: `submitX(data, client)`.