fimo 0.21.0-staging.1 → 0.21.0-staging.3

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,10 +97,10 @@ Syncs the current Branch's data plane from its parent (or `--from <ancestor>`).
 
 Two different "go live" mechanisms — don't confuse them:
 
-- **`fimo publish --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
 

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/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`)                                                                                                                              |
@@ -163,6 +165,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/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/references/frameworks/next/locales.md

@@ -35,13 +35,13 @@ When labels are not needed at that boundary, use `<FimoProvider locale={locale}>
 
 ## New-project boundary
 
-Choose the primary locale from the user's request before building pages. Put the first explicitly requested locale in `.fimo/config.json#i18n.defaultLocale` and keep all requested locales in `i18n.locales`. That edit is the whole locale setup: `src/locales.ts` reads the file, so the default locale passed to `FimoProvider`, the `<html lang>` of each tree, and the set of prefixed URLs follow it. If the user gives no locale signal, keep `en` and state that choice. Never add `NEXT_PUBLIC_FIMO_DEFAULT_LOCALE` or `FIMO_DEFAULT_LOCALE`; the runtime ignores them by design.
+Choose the primary locale from the user's request before building pages. Put the first explicitly requested locale in `.fimo/config.json#i18n.defaultLocale` and keep all requested locales in `i18n.locales`. That is content and provider configuration: `src/locales.ts` reads the file, so the default locale passed to `FimoProvider` and the `<html lang>` follow it. It does not create locale URLs. If the user gives no locale signal, keep `en` and state that choice. Never add `NEXT_PUBLIC_FIMO_DEFAULT_LOCALE` or `FIMO_DEFAULT_LOCALE`; the runtime ignores them by design.
 
-The starter keeps default routes in an unprefixed `app/(default)` route group and a native `app/[locale]` tree for the other locales. Only a root layout may render `<html>`, so each tree owns its root layout and renders the shared `src/components/Document.tsx` with its locale: the unprefixed tree with `defaultLocale`, the prefixed tree with `params.locale`. The prefixed layout 404s a locale that is not in `prefixedLocales`, which is why the default locale has exactly one URL. For `/:locale/pricing`, `params.locale.optional: true` means omit the configured default locale: with `i18n.defaultLocale: "en"`, `/pricing` is English and `/fr/pricing` is French. With `optional: false`, both `/en/pricing` and `/fr/pricing` are prefixed. The default locale value chooses the fallback locale; `optional` independently controls URL prefixes. A route without `:locale` remains application-owned.
+The starter is default-only: one ordinary root layout renders `<html lang={defaultLocale}>` and `FimoProvider`, `/` is the homepage, and unknown paths get Next's native 404. Implement a locale routing strategy only when the product asks for one — prefixed `[locale]` segments, middleware, cookies, domains, or an i18n library are all Next decisions — then resolve the locale in that strategy and pass it into Fimo server reads and `FimoProvider`. Do not install a top-level `[locale]` route or an optional catch-all speculatively: it captures `/favicon.ico` and every unknown top-level path, and Fimo never requires it.
 
-Next.js has no optional single-segment route folder, so mirror localized routes in both existing groups as the site grows. Astro uses the same paired native filesystem-tree shape for this semantic. Do not replace the trees with middleware, rewrites, an optional catch-all that captures the application route tree, or a Fimo route helper. The config route catalog describes the URL shapes for Studio; Next's `app` directory remains authoritative.
+When the app implements a localized URL shape, describe it in `.fimo/config.json#routes` for Studio. For `/:locale/pricing`, `params.locale.optional: true` means omit the configured default locale: with `i18n.defaultLocale: "en"`, `/pricing` is English and `/fr/pricing` is French. With `optional: false`, both `/en/pricing` and `/fr/pricing` are prefixed. The default locale value chooses the fallback locale; `optional` independently controls URL prefixes. A route without `:locale` remains application-owned. The config route catalog describes URL shapes for Studio; Next's `app` directory remains authoritative.
 
-Keep the starter's client-only `src/components/FimoPreviewBridge.tsx` inside `Document`, so both trees mount it. It reads Next's native pathname/router, reports the settled locale to Studio, and lets Studio navigate through Next; do not move Next imports into Fimo's shared runtime.
+`FimoProvider` owns the optional Studio preview runtime, including Next navigation and script loading. Application code only passes its resolved locale to the provider. Do not add a preview bridge component, read Fimo preview environment variables, or inject Fimo scripts.
 
 With `next-i18next`, keep its routing and translation provider for the strings it owns. Pass the same resolved locale to Fimo; do not replace the library or duplicate its route structure.
 

package/assets/skills/fimo-code/references/frameworks/react-router.md

@@ -133,6 +133,7 @@ For new projects, apply `references/locales.md`, keep the starter's `:locale?` r
 ## Boundaries
 
 - Route modules and `meta` exports own routing and SEO.
-- `FimoScripts` owns preview-script loading; do not add the overlay script manually.
+- `FimoProviders` owns the optional Studio preview runtime. Do not read Fimo preview environment variables or inject its script in application code.
+- `FimoScripts` owns document-only JSON-LD and the development error overlay.
 - Use `fimo deploy` only when the developer requests a hosted preview or publication.
 - Load `references/ui.md` for rendering and `references/locales.md` for locale ownership.

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

@@ -127,11 +127,9 @@ export const actions = {
 
 ## Live preview
 
-`FimoProvider` owns the Studio browser bridge. On mount it reads
-`PUBLIC_FIMO_PREVIEW_SCRIPT_URL` from SvelteKit's dynamic public environment,
-loads that script once, delegates navigation to SvelteKit's `goto`, and
-refreshes data with `invalidateAll()`. Without that environment value it does
-nothing. Do not add a second preview component.
+`FimoProvider` owns the optional Studio preview runtime, including script
+loading, SvelteKit navigation, and content refresh. Do not add a second preview
+component, read Fimo preview environment variables, or inject Fimo scripts.
 
 ## Boundaries
 

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

@@ -13,7 +13,7 @@ The application owns locale resolution and routing. Fimo consumes the resolved l
 }
 ```
 
-For new projects, derive the primary locale from the request; when several are explicit, the first one named is the default. Update `i18n.defaultLocale`, `i18n.locales`, the framework-native route boundary and matcher, and the document language default. If the user gives no locale signal, retain the starter default and state that choice.
+For new projects, derive the primary locale from the request; when several are explicit, the first one named is the default. Update `i18n.defaultLocale`, `i18n.locales`, the document language default, and any framework-native locale route boundary or matcher the application implements. If the user gives no locale signal, retain the starter default and state that choice.
 
 Keep one locale unless the product asks for multilingual output. Keep it locale-ready without forcing `/en`, a language switcher, global path-prefix routing, or localized schemas. Locale tags should be structurally valid, such as `en`, `pt-BR`, or `zh-Hans`.
 
@@ -45,4 +45,4 @@ For an already linked project, enable each locale in Fimo before writing non-def
 
 Do not replace an existing locale system merely to add Fimo. Do not duplicate localized routes in the Studio catalog. Every framework resolves its active locale and passes it to Fimo through that framework's provider or server-read seam.
 
-Astro and Next implement an optional locale boundary with paired native filesystem route trees: one unprefixed tree for the default locale and one prefixed tree for the other locales. Neither framework has an optional single-segment filesystem folder.
+Neither Astro nor Next has an optional single-segment filesystem folder; an optional locale boundary in those frameworks is paired native filesystem route trees, one unprefixed for the default locale and one prefixed for the others. The Astro starter ships that pair; the Next starter is default-only, so a Next application adds a `[locale]` tree (or another strategy) only when the product asks for prefixed URLs.