fimo 2.2.0-staging.1 → 2.2.0-staging.11

package/README.md

@@ -27,9 +27,10 @@ Run the CLI with `npx` — no global install, always the latest:
 
 ```bash
 npx fimo@latest login
-npx fimo@latest init my-site                 # default React Router scaffold
+# default Next.js App Router scaffold
+npx fimo@latest init my-site
+# or: npx fimo@latest init my-react-site --framework react-router
 # or: npx fimo@latest init my-astro-site --framework astro
-# or: npx fimo@latest init my-next-site --framework nextjs
 # or: npx fimo@latest init my-svelte-site --framework sveltekit
 cd my-site
 ```

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

@@ -2,5 +2,6 @@
 # See https://fimo.dev/docs/agents/bundle for the full reference.
 version: 1
 description: 'A new Fimo agent. Edit this tagline to describe what it does.'
+model: openai/gpt-5.6-luna
 triggers:
   - type: manual

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

@@ -1,5 +1,6 @@
 version: 1
 description: 'Crawl the published site and flag broken outbound links in a weekly report.'
+model: openai/gpt-5.6-luna
 
 runtime:
   cloud: true

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

@@ -1,5 +1,6 @@
 version: 1
 description: 'Translate CMS content into the project locales whenever an entry is published.'
+model: openai/gpt-5.6-luna
 data_sources:
   - main
 

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

@@ -1,5 +1,6 @@
 version: 1
 description: 'Probe routes and inspect logs after a deploy; report any issues to email recipients.'
+model: openai/gpt-5.6-luna
 data_sources:
   - prod
 

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

@@ -1,5 +1,6 @@
 version: 1
 description: "Audit the project's pages for SEO health and write a markdown report."
+model: openai/gpt-5.6-luna
 # Read from main env. Switch to prod when running the audit against the
 # live site (M13 keeps data_sources here so M16's sandbox adapter can
 # bind the right Fimo API base URL).

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

@@ -52,7 +52,7 @@ A project can have multiple **Branches** — each is a git branch _plus_ its own
 fimo login                                     # authenticate via browser
 fimo skills install                            # install the global Fimo skill for your AI tools
 fimo init my-site --org <id>                   # one-stop setup: sign in, create/link a project, install deps + skills. Use the org **id** from `fimo orgs list`, NOT the slug.
-fimo init my-site --starter fimo-site@1 --org <id> --yes --no-skills  # opt-in content-led starter for a new project
+fimo init my-react-site --framework react-router --org <id> --yes --no-skills  # canonical React Router template
 fimo init --project-id <id> my-site            # set up a project by ID: scaffold a newly created project or clone existing code
 fimo clone                                     # interactively choose an existing project to clone locally
 cd my-site                                     # then load skills on demand: fimo skills get fimo-code
@@ -64,6 +64,8 @@ fimo deploy                                    # ON-DEMAND: hosted project previ
 fimo deploy --publish                          # ON-DEMAND: publish live (only when the developer says "ship it")
 ```
 
+New projects use the Next.js App Router template by default. Fimo's canonical React Router template is selected explicitly with `--framework react-router`; use `--framework vite` for a React SPA.
+
 The working loop is local: run the app with the project's package-manager `dev` script (`pnpm dev` / `npm run dev` / `yarn dev` / `bun dev` — match the lockfile), ask the developer what they want, edit, and iterate against the live localhost server. Outside the first-time onboarding rule below, `fimo deploy` is **not** a required final step — reach for it only when the developer wants a hosted project preview or to go live, and only on their signal (see `references/deploy.md`).
 
 `fimo validate` is the single entrypoint for "prove this project is ready" — it covers schema/form codegen, route metadata checks, lint, and missing label checks for `i18n.defaultLocale` from `.fimo/config.json` (fallback: `en`). Use `fimo labels set` / `set-many` to create or update label values in the DB. The underlying phases are also available individually under the hidden `fimo scripts` namespace for advanced/debug use.
@@ -76,12 +78,12 @@ Keep `fimo validate --json` at the front of the project's `build` script, which
 
 Load the matching reference when the user's request fires its trigger. Recipes that involve writing code also need the `fimo-code` skill's package references — they're called out where relevant.
 
-- "Create a new Fimo project / scaffold a site / start a new website / add the opt-in content starter / link an existing project locally" → `references/init.md`
+- "Create a new Fimo project / scaffold a site / start a new website / link an existing project locally" → `references/init.md`
 - "Add a content type / blog / products / content schemas / CMS" → `references/content.md` (workflow) **+ run `fimo skills get fimo-code --ref content/schema` and load the detected framework reference**
 - "Declare Pages routes / configure Pages sources or route params / control what Studio shows for a route" → `references/pages.md`
 - "Add a contact / signup / feedback / newsletter form" → `references/forms.md` (workflow) **+ run `fimo skills get fimo-code --ref forms` for the JSON spec and generated client**
 - "View form submissions / who filled out the contact form / inspect what users sent / how many signups" → `references/forms.md` § Reading submissions
-- "Upload an image / hero / cover / existing media file" → `references/assets.md` (workflow: upload, browse, open, delete) **+ run `fimo skills get fimo-code --ref assets` for the `FimoMedia` shape and rendering**
+- "Upload, inspect, replace, safely remove, or permanently destroy an image / hero / cover / existing media file" → `references/assets.md` **+ run `fimo skills get fimo-code --ref assets` for the `FimoMedia` shape and rendering**
 - "Generate AI image / video / draft preview / image edit / cover from a prompt" → `references/media.md` (task commands, quality, recipes, and verification) **+ run `fimo skills get fimo-code --ref assets` for the `FimoMedia` shape if you'll plug the result into UI**
 - "Add labels / update static copy / fix missing `t()` values" → `references/labels.md` (workflow) **+ run `fimo skills get fimo-code --ref labels` and load the detected framework reference**
 - "Enable locales / configure default locale / integrate an existing locale system" → `references/locales.md` **+ run `fimo skills get fimo-code --ref locales` and load the detected framework locale reference**
@@ -140,8 +142,6 @@ These fire at specific moments in the project lifecycle. **Surface them proactiv
 - **Running `fimo deploy` just to get the current preview URL** — that's a commit + push + sandbox sync when only destination resolution is needed. Use `fimo preview url` instead. See `references/preview.md`.
 - **Using `fimo deploy --publish` casually** — `--publish` makes the site live to the public. Plain `fimo deploy` (preview) is the default. Use `--publish` only when the user says "ship it" / "go live" / "publish".
 - **Bare `fimo init` in a non-interactive shell** — will hang. Always pass `[dir]`, `--no-install` (or `--install`), `--no-skills` (or `--skills`), and `--org`/`--agents` as needed explicitly when scripted.
-- **Using a starter on an existing project** — `--starter` is create-new only. Keep `--project-id` flows blank and use explicit content/form/label commands when changing an existing project.
-- **Treating a starter as a permanent demo tenant** — starters are opt-in seed data in the new project, not a global default. Keep starter agents manual-only; do not add schedules or webhooks unless the project owner explicitly asks for automation.
 - **Hardcoding content / strings / images in code** — that's what schemas, `t()`, and the media library are for. See the `fimo-code` skill's anti-patterns.
 - **Adding another deploy tool (Vercel, Netlify, Cloudflare Pages)** — Fimo handles deploys; don't bolt another platform on.
 - **Committing secrets** — hidden values use `fimo secrets`; public browser-safe values use `fimo vars`. Local env files are ignored and must not become deploy inputs.

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

@@ -40,6 +40,7 @@ fimo agents secrets remove <name> <KEY> [-C <dir>]
 
 - **`list-templates`** — list the bundled starter templates with the first line of each template's `GOAL.md` as a summary. Ships with the CLI binary; no API call. The five bundled templates are `_default`, `seo-audit`, `content-translator`, `broken-link-sweeper`, `post-deploy-check`.
 - **`create <name>`** — scaffold `.fimo/agents/<name>/` from a template (default `_default`, a minimal valid bundle with a manual trigger). `--description <text>` writes a one-line tagline into the scaffolded `config.yaml` (surfaces in the dashboard's agents list). When run **without** `-C`, it requires the cwd to be inside a real Fimo project (walks up for `.fimo/project.json` or legacy `.fimo.settings.json`) and errors out cleanly otherwise, so it never leaks an agent bundle into a stray cwd. If the template declares capabilities, an install-consent flow runs after the copy (`--quiet` skips it; critical caps still abort).
+- Every generated `config.yaml` includes `model: openai/gpt-5.6-luna`. Change that top-level value to another supported Fimo text model when needed; bundles without `model` keep the Luna fallback. Deploy after changing it because cloud runs use the deployed bundle.
 - **`list`** — list the agents declared under `<project>/.fimo/agents/` (or legacy root `agents/`), with each one's trigger types and capability count. Local — the bundle list is the source of truth even if the project isn't linked yet.
 - **`validate [name]`** — run the full validation pipeline: parse → capability vocabulary → composition (cycle / missing sub-agents / invalid grants) → semantic + Fimo project config policy checks. Omit `name` to validate every bundle. `--json` emits a structured `ValidationReport` for CI; exit code is non-zero on any failure.
 - **`secrets add/remove/list`** — edit or inspect the agent's requested secret names in `.fimo/agents/<name>/config.yaml` (or legacy root). These commands do not create, rotate, or reveal secret values. Store values with `fimo secrets add`; run `fimo agents validate` to check that required requested secrets exist in the project. See `references/project-vars-and-secrets.md`.
@@ -241,7 +242,7 @@ Example for a content editor that can read and update entries but cannot change
 
 ```bash
 fimo agents run <name> [--branch <branch>] [--project <id>] [--skip-drift-check] [-C <dir>]
-fimo agents runs <name> [--limit <n>] [--branch <branch>] [--project <id>] [-C <dir>]
+fimo agents runs <name> [--limit <n>] [--cursor <cursor>] [--all-pages] [--branch <branch>] [--project <id>] [-C <dir>]
 fimo agents report <name> [--session <id>] [--branch <branch>] [--project <id>] [-C <dir>]
 fimo agents logs <name> [--session <id>] [--project <id>] [-C <dir>]
 ```

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

@@ -3,7 +3,7 @@
 > Package contract: run `fimo skills get fimo-code --ref assets` for `FimoMedia`, `--ref ui` for rendering primitives, and load the detected framework reference for framework-specific integration.
 > For **generating** new images / videos with AI, see **`references/media.md`** for the task commands and recipes.
 
-This file covers the **CLI workflow** for media that already exists: uploading files, browsing the library, opening an asset to inspect it, moving / deleting items.
+This file covers the **CLI workflow** for media that already exists: uploading files, browsing the library, inspecting reference impact, replacing references, and removing assets safely.
 
 ## Upload a file
 
@@ -96,9 +96,12 @@ fimo assets list --search "wolf"
 fimo assets list --search "hero" --image
 fimo assets list --search "logo" --type file --sort-by createdAt
 
-fimo assets list --limit 50 --offset 0                    # paging
+fimo assets list --limit 50 --cursor <next-cursor>        # next page
+fimo assets list --all-pages                              # every remaining page
 ```
 
+The response includes `nextCursor` when another page exists. Keep the same filters when continuing. `--offset` remains a compatibility alias for existing scripts.
+
 The `--search` query matches:
 
 - `name` (file name)
@@ -142,11 +145,47 @@ When the agent needs to **see** the image — e.g., Claude inspecting it to pick
 fimo assets create-folder "Blog Images"
 fimo assets create-folder "Covers" --parent-id <uuid>
 fimo assets move <asset-id> --parent-id <folder-uuid>
-fimo assets delete <asset-id>
 ```
 
 `--parent-id` is **required** on `move` and must be a folder UUID. (Moving an asset back to the library root isn't supported by this command today — the server rejects a non-UUID parent.)
 
+## Inspect, replace, and remove safely
+
+Check structured content references before removal:
+
+```bash
+fimo assets usage <asset-id> --json
+```
+
+The result reports coverage, status, and counts for the Current Branch, Main, and Live. Other Branches are not checked, so this is guidance, never a project-wide claim that an asset is unused. Code references are not scanned.
+
+Replace structured references only in the Current Branch:
+
+```bash
+fimo assets replace <source-id> --with <replacement-id>
+```
+
+This changes references, not file bytes. It leaves the original asset, Main, Live, other Branches, and code references unchanged.
+
+Remove from the selected environment and include reference guidance in the receipt:
+
+```bash
+fimo assets remove <asset-id>
+fimo assets remove <source-id> --replace-with <replacement-id>
+fimo assets remove <asset-id> --without-checking
+```
+
+Reference counts and incomplete scopes do not block environment removal. Main and Live keep their rows, and shared bytes remain available to them. Use `--replace-with` when Current Branch references should point to another asset before removal. `--without-checking` skips only the guidance scan and remains environment-scoped.
+
+Project-wide destruction is separate and requires confirmation:
+
+```bash
+fimo assets remove <asset-id> --permanent
+fimo assets remove <asset-id> --permanent --yes
+```
+
+Use `--permanent` only when the user explicitly wants the asset destroyed across the project. It cannot be combined with `--replace-with` or `--without-checking`. The legacy `fimo assets delete` spelling remains an alias for `remove`.
+
 ## End-to-end workflow
 
 1. Upload with `fimo assets upload`, use `fimo assets bulk-upload` for a batch, or generate with a task command such as `fimo image generate`.

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

@@ -69,7 +69,7 @@ Use singular commands for one entry. Bulk create and per-entry bulk update also
 ```bash
 fimo entries create <TypeName> --body '<json>'
 fimo entries create <TypeName> --locale es --document-id <documentId> --body '<json>'
-fimo entries list <TypeName> [--limit N] [--offset N] [--search Q] [--where JSON] [--sort F] [--fields FIELDS] [--populate FIELDS]
+fimo entries list <TypeName> [--limit N] [--cursor CURSOR] [--all-pages] [--search Q] [--where JSON] [--sort F] [--fields FIELDS] [--populate FIELDS]
 fimo entries list <TypeName> --locale es
 fimo entries get <TypeName> <id> [--locale es]
 fimo entries update <TypeName> <id> [--locale es] --body '<json>'
@@ -90,12 +90,12 @@ fimo entries list BlogPost --where '{"featured":true}' --sort -publishedAt
 fimo entries list BlogPost --where '{"rank":{"$gte":3}}' --sort rank
 fimo entries list BlogPost --where '{"__fimo":{"contentType":{"$eq":"BlogPost"}}}'
 fimo entries list BlogPost --search "launch"
-fimo entries list BlogPost --limit 10 --offset 20 --sort title
+fimo entries list BlogPost --limit 10 --cursor <next-cursor> --sort title
 fimo entries list BlogPost --fields slug,title,excerpt,coverImage --sort -publishedAt --limit 12
 fimo entries list BlogPost --fields slug,title,author --populate author
 ```
 
-Use the canonical read query flags: `--search`, `--sort`, `--where`, `--limit`, `--offset`, `--fields`, and `--populate`.
+Use the canonical read query flags: `--search`, `--sort`, `--where`, `--limit`, `--cursor`, `--all-pages`, `--fields`, and `--populate`. `--offset` remains a compatibility alias for existing scripts.
 `--where` is a JSON object keyed by schema field name. Simple values mean equality and stay typed inside the JSON (`{"featured":true}`, `{"category":"react"}`, `{"rank":{"$gte":3}}`); operator objects support `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$in`, `$nin`, `$contains`, `$startsWith`, and `$null`, subject to the field type. Public Fimo-owned metadata lives under `__fimo`; currently `__fimo.contentType` is filterable.
 
 Reference filters take the target `id` string (`{"author":"750e..."}`). On a to-many field, `$eq` and `$contains` mean membership, `$in` means any listed target is present, `$ne` and `$nin` mean none are present, and `$null: true` means empty or missing. Reference fields cannot be sorted; use `--sort field` / `--sort -field` on scalar fields.

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

@@ -50,11 +50,11 @@ Public project variables managed with `fimo vars add` and `fimo vars update` are
 
 ## Diagnose a failed publication
 
-Use the publication ID returned by the failed command: run `fimo publish inspect <id> --json` for its durable status, then `fimo publish logs <id> --json` for a bounded build-log tail. Logs come from the hosting provider and may be unavailable after its deployment is reclaimed.
+Use the publication ID returned by the failed command: run `fimo publish inspect <id> --json` for its durable status, then `fimo publish logs <id> --json` for a bounded build-log tail. Use `fimo publish list --cursor <cursor>` to continue through older attempts or `--all-pages` to fetch the complete retained history. `--before` remains a compatibility alias. Logs come from the hosting provider and may be unavailable after its deployment is reclaimed.
 
 ## Diagnose a failed preview deploy
 
-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.
+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 --cursor <cursor> --json` to fetch the preceding page, or use `--all-pages` to fetch every retained page. `--before` remains a compatibility alias. 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:
 

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

@@ -29,11 +29,13 @@ Notification recipients for form submissions are configured in the Fimo web UI,
 After a form is live and users have filled it out, inspect submissions from the terminal:
 
 ```bash
-fimo forms submissions list <formIdOrName> [--limit 50] [--offset 0] [--search "<q>"] [--sort asc|desc]
+fimo forms submissions list <formIdOrName> [--limit 50] [--cursor CURSOR] [--all-pages] [--search "<q>"] [--sort asc|desc]
 fimo forms submissions get  <formIdOrName> <submissionId>
 fimo forms submissions stats <formIdOrName>
 ```
 
+The list response includes `nextCursor` when another page exists. `--offset` remains a compatibility alias for existing scripts.
+
 - `<formIdOrName>` accepts either the form's UUID or its `name` (the same name in the JSON file). Names that don't resolve to exactly one form return an error.
 - `list` returns `{ data: [...], total }`. Newest-first by default; pass `--sort asc` to reverse.
 - `search` matches against submission contents server-side.

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

@@ -28,6 +28,7 @@ there is no local `.fimo/project.json`.
 
 ```bash
 fimo history list --limit 20 --cursor <cursor>
+fimo history list --all-pages
 ```
 
 The list also reports compressed snapshot usage and the current retention period. Restore points expire after 14 days on Free and pay-as-you-go plans, or 90 days on Premium. The expiry is fixed when each point is created.

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

@@ -11,40 +11,40 @@ fimo init [dir] [options]
 `fimo init` runs the full onboarding in one shot:
 
 1. **Signs in automatically** — if there's no session it opens the browser loopback login. In `--json` / non-TTY with no session it fails with `NOT_AUTHENTICATED` (run `fimo login` first).
-2. **Resolves the project** — with `--project-id <id>` it sets up the named Fimo project: a project with no code yet is scaffolded as a fresh site, while an existing repository is cloned. Without it, `init` creates a NEW project. An interactive TTY shows a "Create new / Link existing" picker; non-interactive shells default to create-new. New projects use React Router by default; `--framework vite`, `--framework astro`, `--framework nextjs`, and `--framework sveltekit` select minimal framework-native shells. An optional `--starter fimo-site@1` adds a content-led starter only to a newly created project without `--project-id`.
+2. **Resolves the project** — with `--project-id <id>` it sets up the named Fimo project: a project with no code yet is scaffolded as a fresh site, while an existing repository is cloned. Without it, `init` creates a NEW project. An interactive TTY shows a "Create new / Link existing" picker; non-interactive shells default to create-new. New projects use the Next.js App Router by default; `--framework react-router`, `--framework vite`, `--framework astro`, and `--framework sveltekit` select the other minimal framework-native shells.
 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`)                                                                                                                              |
-| `--project-id <id>`          | no                            | Set up the named Fimo project: scaffold and push a fresh site when it has no code yet, otherwise clone it.                                                     |
-| `--org <id>`                 | no                            | Target organization **id** when creating (use the `ID` column from `fimo orgs list`, NOT the slug). Picker shown interactively if omitted and TTY.             |
-| `--branch <name>`            | no                            | Branch to check out when linking an existing project (defaults to `main`).                                                                                     |
-| `--env <name>`               | no                            | Compatibility alias for `--branch <name>`.                                                                                                                     |
-| `--framework <framework>`    | no                            | New-project scaffold: `react-router` (default), `vite` (React SPA), `astro`, `nextjs` (App Router), or `sveltekit`. Existing repositories are preserved.       |
-| `--starter <id>`             | no                            | Opt-in project starter for create-new (currently `fimo-site@1`). It seeds CMS content, labels, a contact form, and manual-only agents. Rejects `--project-id`. |
-| `--package-manager <pm>`     | no                            | `npm` \| `pnpm` \| `yarn` \| `bun`.                                                                                                                            |
-| `--install` / `--no-install` | yes in non-TTY                | Install deps after checkout (or skip it).                                                                                                                      |
-| `--skills` / `--no-skills`   | yes in non-TTY                | Install the global Fimo skill (or skip it).                                                                                                                    |
-| `--agents <list>`            | no                            | Comma-separated agent IDs (e.g. `claude-code,cursor`). Pass `none` to skip installing the global skill.                                                        |
-| `-a, --agent <id>`           | alternative                   | Repeatable form: `-a claude-code -a cursor`.                                                                                                                   |
-| `--template-root <path>`     | no                            | Override the bundled template (development only).                                                                                                              |
-| `-y, --yes`                  | no                            | Run non-interactively using defaults (no prompts).                                                                                                             |
+| Flag                         | Required                      | Purpose                                                                                                                                                 |
+| ---------------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `[dir]` positional           | yes in non-TTY for create-new | Target directory (e.g. `my-site`)                                                                                                                       |
+| `--project-id <id>`          | no                            | Set up the named Fimo project: scaffold and push a fresh site when it has no code yet, otherwise clone it.                                              |
+| `--org <id>`                 | no                            | Target organization **id** when creating (use the `ID` column from `fimo orgs list`, NOT the slug). Picker shown interactively if omitted and TTY.      |
+| `--branch <name>`            | no                            | Branch to check out when linking an existing project (defaults to `main`).                                                                              |
+| `--env <name>`               | no                            | Compatibility alias for `--branch <name>`.                                                                                                              |
+| `--framework <framework>`    | no                            | New-project scaffold: `nextjs` (App Router, default), `react-router`, `vite` (React SPA), `astro`, or `sveltekit`. Existing repositories are preserved. |
+| `--package-manager <pm>`     | no                            | `npm` \| `pnpm` \| `yarn` \| `bun`.                                                                                                                     |
+| `--install` / `--no-install` | yes in non-TTY                | Install deps after checkout (or skip it).                                                                                                               |
+| `--skills` / `--no-skills`   | yes in non-TTY                | Install the global Fimo skill (or skip it).                                                                                                             |
+| `--agents <list>`            | no                            | Comma-separated agent IDs (e.g. `claude-code,cursor`). Pass `none` to skip installing the global skill.                                                 |
+| `-a, --agent <id>`           | alternative                   | Repeatable form: `-a claude-code -a cursor`.                                                                                                            |
+| `--template-root <path>`     | no                            | Override the bundled template (development only).                                                                                                       |
+| `-y, --yes`                  | no                            | Run non-interactively using defaults (no prompts).                                                                                                      |
 
 In a non-TTY shell the create-new path requires `[dir]`, `--install` / `--no-install`, and `--skills` / `--no-skills` (and `--org` if you have no active org and belong to multiple orgs). Without them the command exits with `Cannot prompt in a non-interactive shell.`
 
-### Non-interactive starter setup
+### Non-interactive setup
 
 Use explicit flags when a script or agent owns the flow. `--json` gives the
 caller one stable result envelope; `--yes` is useful when running in a TTY but
-is not required in a pipe or CI shell. The starter is never selected by default.
+is not required in a pipe or CI shell. The default scaffold is the Next.js App
+Router template. Select the canonical React Router template explicitly with
+`--framework react-router`.
 
 ```bash
 fimo --json init my-site \
-  --starter fimo-site@1 \
   --org <organizationId> \
   --no-install \
   --no-skills \
@@ -52,22 +52,18 @@ fimo --json init my-site \
   --yes
 ```
 
-The command creates the project, copies the starter overlay, seeds its `HomePage`
-singleton, `contact` form, and labels in `main`, writes the form id into
-`src/forms/contact.json`, and commits the starter agents as manual-only bundles.
-`--starter` is create-new only; an existing-project command such as
-`fimo init --project-id <id> --starter fimo-site@1` fails before cloning or
-writing anything. If dependencies were skipped, install them and run
-`fimo validate` before starting the app so generated clients are present.
+If dependencies were skipped, install them and run `fimo validate` before
+starting the app so generated clients are present.
 
 > **Zero-install:** the selected `fimo init` invocation needs no global install. `fimo projects create` is also an alias of `fimo init` (create-new path).
 
 ### Choose the application framework
 
-Omit `--framework` for the existing React Router scaffold, or select a
-minimal framework-native shell explicitly:
+Omit `--framework` for the default Next.js App Router shell, or select a
+different framework explicitly:
 
 ```bash
+fimo init my-react-site --framework react-router --org <organizationId>
 fimo init my-vite-site --framework vite --org <organizationId>
 fimo init my-astro-site --framework astro --org <organizationId>
 fimo init my-next-site --framework nextjs --org <organizationId>
@@ -80,6 +76,10 @@ boundary that keeps the default locale unprefixed. The Astro shell also includes
 content-backed example with static, on-demand, and dynamic routes; the other shells intentionally
 contain no schema, labels, or designed website.
 
+The React Router shell is the canonical Fimo React template for framework mode;
+select it with `--framework react-router` when a project should use React Router
+instead of the default Next.js App Router shell.
+
 Set the primary locale from the request: when several are explicitly named, use the first as default;
 if none is requested, keep `en` and tell the user. Update `.fimo/config.json#i18n`, the framework-native
 locale boundary, matcher, and HTML language default. Do not keep `en` solely because the shell starts
@@ -89,7 +89,6 @@ After init, load the project rules and `fimo-code` to build the requested site.
 If you replace a shell's code with a site that uses another framework or none,
 fix `runtime.framework` in the same change
 (`fimo-code` → `references/frameworks/hosting.md`).
-The current `fimo-site@1` content starter supports React Router only.
 
 For `--agents`, pass the AI tool you're running in: `--agents=claude-code` for Claude Code, `--agents=cursor` for Cursor, `--agents=codex` for Codex, etc. When the flag is omitted, env-var detection of the invoking harness (e.g. `CLAUDECODE` / `CLAUDE_CODE_ENTRYPOINT` → claude-code) auto-targets that agent; other agents must be selected explicitly via `--agents`/`-a` or the interactive picker.
 
@@ -109,21 +108,13 @@ fimo link <projectId> --relink
 
 `fimo init` (create-new path) scaffolds:
 
-- The selected project shell: React Router by default, a native React SPA with `--framework vite`, Astro with `--framework astro`, Next.js App Router with `--framework nextjs`, or SvelteKit with `--framework sveltekit`
+- The selected project shell: Next.js App Router by default, React Router with `--framework react-router`, a native React SPA with `--framework vite`, Astro with `--framework astro`, or SvelteKit with `--framework sveltekit`
 - `.fimo/project.json` — links this directory to the remote project (read-only after creation)
 - `.fimo/config.json` — project, optional Studio Pages route metadata, locale, SEO, and agent policy
 - `.fimo/agents/` — versioned agent bundles
 - `AGENTS.md` + `CLAUDE.md` — project rules (from the template) read by AGENTS.md-compatible tools and Claude Code. Both point the agent at `fimo skills get` to load the real skills on demand.
 - A git repository with `fimo` as the remote, and — after dependencies install — an initial commit (including the lockfile) plus an initial push
 
-When `--starter fimo-site@1` is supplied, the overlay also includes a
-content-backed homepage, `src/schemas/HomePage.json`, a `contact` form spec,
-nine English labels, and two read-only agent bundles (`site-review` and
-`content-guide`). The seed is opt-in and scoped to the new project; the default
-blank template and all existing-project flows remain unchanged. Starter agents
-declare only a manual trigger so copying them does not create schedules or
-webhooks.
-
 Nothing is written into per-agent skill dirs: the rich skills are fetched on demand via `fimo skills get <name>`, never copied into the project. `fimo init` separately installs the small global `fimo` bootstrap skill for the agents you select (machine-wide, not in the project) unless you pass `--no-skills`. For other agents' rule-file variants (`.cursor/rules/fimo.mdc`, `.windsurfrules`, `GEMINI.md`), run `fimo rules sync`. See `references/agent-setup.md`.
 
 Codex, OpenCode, Aider, and similar AGENTS.md-native tools work directly off AGENTS.md.

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

@@ -22,7 +22,7 @@ fimo schedules resume <schedule>
 fimo schedules run <schedule>
 fimo schedules run <schedule> --no-wait
 fimo schedules runs <schedule> --limit 25 --status failed
-fimo schedules runs <schedule> --all
+fimo schedules runs <schedule> --all-pages
 fimo schedules runs show <run-id>
 fimo schedules delete <schedule>
 ```
@@ -59,9 +59,11 @@ Run history is cursor-paginated:
 fimo schedules runs nightly --limit 50
 fimo schedules runs nightly --cursor <cursor>
 fimo schedules runs nightly --status succeeded
-fimo schedules runs nightly --all
+fimo schedules runs nightly --all-pages
 ```
 
+`--all` remains a compatibility alias for existing scripts.
+
 Run detail includes status, timing, trigger, exit/error information, retained output, output retention metadata, and secret snapshot metadata. Output is capped and redacted before it is returned.
 
 ## JSON

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

@@ -121,6 +121,8 @@ fimo webhooks list
 fimo webhooks get <webhook-id>
 fimo webhooks test <webhook-id> --wait
 fimo webhooks deliveries <webhook-id> --limit 20
+fimo webhooks deliveries <webhook-id> --cursor <next-cursor>
+fimo webhooks deliveries <webhook-id> --all-pages
 fimo webhooks delivery <webhook-id> <delivery-id>
 ```
 

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

@@ -47,7 +47,10 @@ own tenant URL.
 ## Hosted preview config
 
 Wrap the existing Next config once so `next dev` accepts Fimo's hosted preview
-origins without exposing the active preview provider to the application:
+origins without exposing the active preview provider to the application. If
+the application does not set Next's `devIndicators`, the wrapper hides it in
+hosted Preview while local `next dev` keeps Next's default. Any explicit
+`devIndicators` setting is preserved:
 
 ```ts
 import type { NextConfig } from 'next';

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

@@ -1,8 +1,9 @@
 # React Router framework mode
 
-This is the canonical Fimo + React Router framework-mode setup used by
-`fimo init`. You can also apply it to an existing React Router project: preserve
-its routes, rendering choices, providers, and SEO.
+This is the canonical Fimo React Router template and framework-mode setup used
+by `fimo init --framework react-router`. You can also apply it to an existing
+React Router project: preserve its routes, rendering choices, providers, and
+SEO.
 
 ## Install and build
 

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

@@ -34,6 +34,20 @@ end-to-end. Preserve the original code path and record required environment
 variable names only; never read or copy secret values. A missing secret is a
 follow-up for the owner, not permission to silently remove the integration.
 
+Before any source, target, Fimo, or remote write, inspect the available source
+read-only and follow [questions-and-improvements.md](references/questions-and-improvements.md).
+Use the coding agent's native structured-question UI when available. Ask one
+stacked batch of the decisions the source cannot answer instead of interrupting
+the migration for each question. A migration request never authorizes moving
+environment values or credentials.
+
+When migration replaces local or bundled content with Fimo reads, preserving
+content-delivery performance is part of fidelity. Keep build-time and
+server-rendered content off the browser request path, use direct generated-client
+lookups, avoid duplicate or sequential reads, and prove edit freshness. Do not
+ask a generic optimization question or bundle a framework upgrade into the
+migration.
+
 ## Execution environment
 
 Run this skill from a coding-agent process that has direct access to the
@@ -139,13 +153,18 @@ report the exact failed command and setup requirement.
   unwired.
 - Prefer source code and exports over inferred crawl data. Use a public URL as
   visual, SEO, route, and behavior evidence when better source material exists.
+  When the source defines an active CMS but its deployed records are unavailable,
+  rebuild published content from the public site only after the user explicitly
+  chooses that lower-confidence path.
 - Read local files and exports directly and public APIs without credentials.
   Private APIs and CMSs require a user-provided export or a narrowly scoped
   server-side credential. Never read credentials from browser code or copy
   them into browser code, migration artifacts, or reports. Target-project
   authentication does not grant source access. If the source API URL or access
-  is missing or unreachable, stop and ask the user for it; do not guess, replace
-  the content, or mark the lane complete.
+  is missing or unreachable, stop and ask whether the owner wants to provide a
+  scoped export or read-only access, reconstruct the selected published routes
+  from public pages, or migrate code only and leave those records external. Never
+  infer permission to scrape, discover secrets, or contact private endpoints.
 - Model content before page code. Generated JSON is not imported content.
 - Model editorial content Fimo-natively: blocks for structured or repeatable
   sections, richtext for rich bodies, references for categories, authors,
@@ -190,9 +209,11 @@ report the exact failed command and setup requirement.
      create the draft evidence pack.
    - **hybrid**: source material plus a public URL. Treat source material as
      truth and the URL as comparison evidence.
-4. Read `references/workflow.md` before implementation and create or update the
+4. Read `references/questions-and-improvements.md`, finish its read-only
+   preflight, and collect the user's decisions before setup or implementation.
+5. Read `references/workflow.md` before implementation and create or update the
    plain-text migration plan.
-5. Load the references that apply:
+6. Load the references that apply:
    - Coordinator ownership and dependency gates -> `references/workers.md`.
    - Framework conversion worker -> `references/workers/framework.md`.
    - Content planner -> `references/workers/content-planner.md`.
@@ -272,7 +293,10 @@ Commands that perform actual data writes, all requiring the linked target:
 
 ## Migration loop
 
-1. Run the setup path from "Initialized target precondition" and inspect the
+1. Inspect the source read-only, then ask the one preflight question batch from
+   `references/questions-and-improvements.md`. Do not initialize, link, import,
+   edit, or move environment values until the user answers every consent gate.
+2. Run the setup path from "Initialized target precondition" and inspect the
    initialized target before any worker edits it. A `fimo link` adoption keeps
    the source framework; the `fimo init` / `fimo migrate init` paths choose the
    target framework through the same canonical option as
@@ -284,7 +308,7 @@ Commands that perform actual data writes, all requiring the linked target:
    copying an arbitrary template path. The target's real files and directories
    are the authority for framework paths; do not invent a second `app/` or
    `src/app/` tree from an example.
-2. Write a short `.fimo/migration/migration-plan.md` containing the chosen
+3. Write a short `.fimo/migration/migration-plan.md` containing the chosen
    framework, source/target paths, worker owners, important dependencies, and
    known questions. Start the independent workers in `references/workers.md`:
    runtime/config, routes/SEO, content planning, and locales when those surfaces
@@ -293,25 +317,25 @@ Commands that perform actual data writes, all requiring the linked target:
    all structural target code, and must pass the framework gate in
    `references/workers/framework.md` before content data and code workers
    start. Worker prompts and worker reports are plain text.
-3. The content planner reads every content-bearing source and consumer. When
+4. The content planner reads every content-bearing source and consumer. When
    content comes from an API, it traces the active application client and
    retrieves the complete accessible dataset before pushing schemas. It then
    writes complete schemas and import payloads, recording source items,
    consumers, batches, and unresolved behavior in the text plan rather than a
    second orchestration format.
-4. Each discovery lane reports active media in its own surface. After the
+5. Each discovery lane reports active media in its own surface. After the
    runtime/framework, routes/SEO, and content discovery receipts are terminal,
    the coordinator performs one fan-in: combine and deduplicate them into the
    complete media-obligation list. Give only that list to the media worker; do
    not require a content-planner rescan. Once it returns every mapping, patch
    code and payload consumers. Start data after the asset gate and content code
    only after its imported records read back successfully.
-5. Fan in the workers' plain-text reports. Compare their claimed files with
+6. Fan in the workers' plain-text reports. Compare their claimed files with
    `git diff`, their Fimo writes with read-back CLI queries, and their source
    coverage with the content plan. Every source item must be migrated,
    deliberately preserved, or listed as unresolved with an owner action. A
    report that merely says “done” is not evidence.
-6. Validate against the real target with a validator that did not author the
+7. Validate against the real target with a validator that did not author the
    changes and starts only after every other worker report is terminal: read
    back schemas, entries, singles, labels, and assets through the CLI, build
    the project, render the migrated routes, and verify hosting compatibility
@@ -319,13 +343,15 @@ Commands that perform actual data writes, all requiring the linked target:
    when a browser is available; otherwise use deterministic
    HTTP/header/process/log checks and mark visual proof unavailable. Then run
    the QA gate in `references/qa.md`.
-7. Write `.fimo/migration/migration-report.md` with coverage, counts, mappings,
+8. Write `.fimo/migration/migration-report.md` with coverage, counts, mappings,
    unresolved items, timings from worker reports, and next actions.
 
 ## References
 
 - `references/workflow.md` - phase order, source intake, URL artifacts, and
   implementation loop.
+- `references/questions-and-improvements.md` - structured preflight questions,
+  integration consent, and content-delivery performance preservation.
 - `references/decision.md` - plain-text decision and schema guidance; no
   decision JSON is required.
 - `references/content.md` - CMS, entries, references, and source value rules.
@@ -359,10 +385,15 @@ Use one final status:
 - **draft-only**: imports or verification are incomplete, or the user asked for
   a draft.
 
-Never call a migration complete when CMS entries, media mappings, forms, or
-route coverage are unknown. Local QA remains the acceptance gate. If
+Never call a migration complete when CMS entries, media mappings, forms, route
+coverage, or migration-induced content-delivery regressions are unknown. Local
+QA remains the acceptance gate. If
 `fimo migrate init` created a new Fimo project, run one `fimo deploy` after QA
 and return its preview and dashboard links; skip it when the user said not to
 deploy or `FIMO_MIGRATION_NO_DEPLOY=1` is set. For an existing linked project,
 offer the deployment and wait for approval. Never run `fimo publish` without an
 explicit request.
+
+Broader performance work and framework modernization are separate tasks. Start
+them only when the user explicitly asks, and never use them to hide a migration
+regression.