fimo 0.20.1-staging.1 → 0.21.0-staging.2

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/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 first successful `fimo deploy --publish`** (not the automatic first preview) → 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. 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 after 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,6 +56,52 @@ 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 it or keeps any conflict for review.
+- **Retain** when a person should review the work, the run stops or fails, the agent needs an answer, or recovery may be
+  necessary. Fimo keeps the task Branch for a follow-up run.
+- **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.
+
+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
@@ -88,9 +134,10 @@ There is no all-capabilities wildcard; keeping the list explicit makes each agen
 | `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.
+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.
 
 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.
@@ -113,7 +160,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

@@ -113,9 +113,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 after first publish
+
+After the project's first successful `fimo deploy --publish`, offer a cleaner free `*.fimo.site` URL when there is no custom domain and the current default slug still looks generated or was never explicitly chosen. This is not part of the automatic first preview. 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. Renaming the default slug changes a public URL, 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>`.
+
+The renamed URL resolves after a successful publish.
+
 ## Pricing & how money moves
 
 The CLI never charges directly. Two distinct money paths:

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-migration/SKILL.md

@@ -76,11 +76,20 @@ the selected pinned CLI. Give workers the project id, environment, exact CLI
 invocation, and verification command. Generated `.fimo` JSON without a
 successful platform read is not initialization.
 
-For an existing non-empty application, reuse the CLI's real flow: create or
-select the Fimo project with `fimo init`, then run
-`fimo link <project-id> -C <target> --env <env>` and verify the data plane.
-`fimo migrate init <url> <dir>` is only usable when the target directory is
-empty or already linked.
+Pick the setup path from the evidence:
+
+- **Source-backed, same framework** — copy or `git worktree` the source into the
+  target directory first, then run `fimo link -C <target> --env <env>`
+  (`fimo link <project-id> -C <target> --env <env>` when the owner supplied an
+  id). Link creates or selects the project, keeps the source's code, framework,
+  git history, and `origin`, initializes a repository when the copy has none,
+  and adds only the Fimo dependency, `.fimo/project.json`, the `fimo` remote,
+  and `.fimo/config.json#runtime.framework`. It never overlays a template, so
+  the target must already contain the source.
+- **Empty target, or an explicit framework conversion** — `fimo init` with the
+  chosen `--framework`, or `fimo migrate init <url> <dir>` for a URL crawl.
+  Both refuse a non-empty target and write nothing when they refuse.
+
 If authentication, organization selection, project creation, environment
 resolution, linking, or the verification read fails, stop before workers and
 report the exact failed command and setup requirement.
@@ -134,8 +143,9 @@ report the exact failed command and setup requirement.
   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. Missing access stops only that
-  data lane and becomes unresolved; never invent replacement content.
+  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.
 - 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,
@@ -162,8 +172,9 @@ report the exact failed command and setup requirement.
 - Do not report completion until the QA gate passes or every failed check is
   present in the migration report.
 - Import through the data-plane commands and verify locally before deployment.
-  Propose one preview deployment after a successful run, but deploy or publish
-  only after an explicit user request.
+  Deployment is not QA evidence. After successful local QA, follow the
+  new-project or existing-project rule in Completion and deployment. Never
+  publish without an explicit user request.
 
 ## Orient and route
 
@@ -204,14 +215,16 @@ The target is its own Fimo project directory. The client source checkout is
 read-only evidence: never run setup inside it, never modify it, and never
 hand-write a `.fimo/project.json` marker to fake a link.
 
-`fimo migrate init` is the migration setup gate. For a source-backed migration
-it validates the target and CLI auth, then delegates project selection and
-creation to the standard `fimo init` flow (same options, no separate creation
-path), and returns a setup receipt covering auth, the target link, the
-migration directory, and readiness. It fails with a structured error when auth
-is missing, the target is missing or invalid, or the project or organization
-is inaccessible. Both forms need a real ID supplied by the owner — without
-one, stop with an unresolved owner action instead of inventing an ID:
+`fimo migrate init` is the setup gate for an empty target; a target that
+already holds the copied source is set up with `fimo link` instead (see
+Initialized target precondition). `fimo migrate init` validates the target and
+CLI auth, then delegates project selection and creation to the standard
+`fimo init` flow (same options, no separate creation path), and returns a setup
+receipt covering auth, the target link, the migration directory, and readiness.
+It fails with a structured error when auth is missing, the target is missing or
+invalid, or the project or organization is inaccessible. Both forms need a real
+ID supplied by the owner — without one, stop with an unresolved owner action
+instead of inventing an ID:
 
 - Link an owner-supplied (empty) project:
   `fimo migrate init <target-dir> --project-id <projectId> --framework <framework>`
@@ -225,8 +238,8 @@ React Router scaffold.
 
 Setup scaffolds the target and pushes its initial commit; that is the only
 remote write it performs — it never pushes schemas, uploads assets, or imports
-entries. `fimo deploy` and `fimo publish` stay separate and are never run
-automatically (see Completion and deployment).
+entries. Setup itself never deploys or publishes; the one new-project preview
+deploy happens only after successful local QA (see Completion and deployment).
 
 ## Command surface
 
@@ -253,12 +266,16 @@ Commands that perform actual data writes, all requiring the linked target:
   `fimo singles update`, `fimo labels set|set-many`, `fimo forms push`.
 - `fimo migrate init` (source-backed form): the project link/creation and
   initial commit push described above.
+- `fimo link`: project creation or selection plus the in-place adoption of a
+  copied source target.
 - `fimo deploy` / `fimo publish` — owner-approved only.
 
 ## Migration loop
 
-1. Run `fimo migrate init` and inspect the initialized target before any worker
-   edits it. Choose the target framework through the same canonical option as
+1. 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
    `fimo init`: pass the detected source framework for a source-backed
    migration, the framework the user explicitly chose for a conversion, and —
    for a URL-only or rebuild migration — the framework the user selected (ask
@@ -276,15 +293,19 @@ 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, writes
-   and pushes complete schemas, and writes the content import payloads required
-   by the Fimo CLI. It records source items, consumers, batches, and unresolved
-   behavior in the text plan; it does not create a second orchestration format.
-4. Once the content plan is ready, upload every planned asset and patch its
-   target payload references. After the asset gate passes (and, in conversion
-   mode, the framework gate), run data workers per schema/locale. Start content
-   code workers only after their imported records read back successfully, so
-   they can prove real values render through the native Fimo APIs.
+3. 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
+   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
    `git diff`, their Fimo writes with read-back CLI queries, and their source
    coverage with the content plan. Every source item must be migrated,

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

@@ -94,12 +94,16 @@ If a media asset cannot be downloaded or uploaded:
 - include a suggested action such as re-exporting the asset folder or providing
   credentials
 
-## Planner obligations
-
-The content planner enumerates every media obligation before fan-out: route and
-SEO media, every schema media field, and every image node nested in richtext or
-Tiptap JSON. Record its source location, consuming route/entry, and intended
-target field or node. Give each obligation a stable identity that includes its
-field or rich-text node path; a shared label or source URL is not unique. The
-asset worker cannot report complete until every obligation has an uploaded or
+## Media obligations
+
+Each discovery lane reports active media in its own surface: runtime/framework
+files, routes and SEO, or content and API data. After every discovery receipt is
+terminal, the coordinator combines and deduplicates those findings into the
+complete media-obligation list. This consolidated list is the media worker's
+only input; do not make the content planner rescan the whole application.
+
+Record each obligation's source location, consuming route/entry, and intended
+target field or node. Give it a stable identity that includes its field or
+rich-text node path; a shared label or source URL is not unique. The media
+worker cannot report complete until every obligation has an uploaded or
 duplicate Fimo mapping, or an explicit unresolved/unsupported disposition.

package/assets/skills/fimo-migration/references/qa.md

@@ -44,9 +44,10 @@ items.
 - Every media item referenced by routes, CMS entries, SEO, or forms is uploaded to
   the Fimo media library (Fimo asset id/URL) or has an unresolved item. A local
   `public/` copy is not an upload mapping.
-- Every planner media obligation, including schema media fields and nested
-  richtext/Tiptap image nodes, has a mapping or explicit disposition; the asset
-  worker's completion claim alone is not evidence.
+- Every obligation in the coordinator's consolidated media list, including
+  schema media fields and nested richtext/Tiptap image nodes, has a mapping or
+  explicit disposition; the media worker's completion claim alone is not
+  evidence. Reconcile the list against every discovery lane's media findings.
 - Every visible form has a Fimo replacement, a preserved third-party
   integration, or an unsupported note. A form became Fimo-native only when the
   Fimo form matches the source behavior 1:1.

package/assets/skills/fimo-migration/references/workers/content-planner.md

@@ -5,9 +5,8 @@ handoff. Do not import entries or rewrite application consumers.
 
 1. Inspect every content-bearing source and consumer: Markdown/MDX bodies and
    frontmatter, JSX/TSX modules, hardcoded arrays and objects, imports, data
-   clients, and call sites. Read local exports and public APIs directly. A
-   private API requires a user-provided export or narrowly scoped server-side
-   credential; never recover or copy secret values.
+   clients, and call sites. Identify whether each active source is a file,
+   inline value, API, CMS, or a mix before designing schemas.
 2. Classify each value as collection content, single content, an
    editor-visible label, or application-owned code. Repetition is evidence,
    not an automatic collection rule. Assistive text, identifiers, and values
@@ -54,11 +53,41 @@ A construct is unresolved only when it genuinely cannot be migrated. Include
 its exact source, user-visible impact, reason, and owner action; "custom" is not
 a reason.
 
+## API-backed content
+
+Retrieve API content during this planning pass, before schemas are pushed or
+data workers start:
+
+1. Trace the application's active client, base-URL environment key, endpoints,
+   queries, pagination, locales, publication states, relations, media, and
+   consuming call sites. Server rendering may hide requests from the browser,
+   so browser traffic is fallback evidence rather than the source of truth.
+2. Prove access with one read-only request. Read public APIs directly. Private
+   APIs require an owner-provided export or narrowly scoped server-side
+   credential; never recover, log, persist, or copy secret values. If the base
+   URL or required access is missing or unreachable, stop and ask the user for
+   it before planning schemas or payloads.
+3. Fetch every required page, locale, and referenced record. For a few bounded
+   endpoints, direct requests are enough. For repeated or paginated reads,
+   write a temporary source-specific read-only script under
+   `.fimo/migration/tmp/`, then spot-check counts and references.
+4. Preserve the retrieved responses as source evidence and payload inputs;
+   normalize transport details only. Do not create a provider registry or a
+   universal CMS model.
+5. Design Fimo schemas from both the retrieved values and the code that uses
+   them. Never invent replacement content when source access is unavailable.
+
+Once retrieval and consumer tracing are complete, push schemas, prepare
+payloads, and let the coordinator fan out assets and one data batch per
+schema/locale. Runtime, routes, locales, and other independent workers continue
+in parallel while retrieval runs.
+
 ## Optional extraction helpers
 
 Start with `rg` and targeted reads. A bounded read-only helper under
 `.fimo/migration/tmp/` may parse repeated frontmatter, JSON/YAML exports, or
-literal structures while preserving source locations. Spot-check its output.
+literal structures, or retrieve repeated API pages while preserving source
+identities. Spot-check its output.
 The agent still owns classification, schema design, and consumer tracing. Do
 not build a generic codemod system or let the helper write Fimo data or app
 code.

package/assets/skills/fimo-migration/references/workers/validator.md

@@ -19,6 +19,16 @@ Verify:
 - build and representative browser interactions pass; and
 - every unsupported item names its impact and owner action.
 
+`fimo deploy` readiness proves only that the server stays up and a
+representative page responds. After an approved deploy, browser QA must:
+
+- open one representative route per route family and exercise one key interaction;
+- fail on route `5xx`, blank or reloading pages, or required module, API, or runtime failures;
+- inspect browser evidence and `fimo logs --json` before editing; and
+- run at most one focused repair and redeploy, then report remaining failures unresolved.
+
+Optional development-tool failures do not fail a rendered, stable application.
+
 Return a plain-text report with status, duration, checks run, counts, failing
 source items, and suggested bounded repair surface. The coordinator may run one
 repair for that surface and rerun validation. It does not restart every worker

package/assets/skills/fimo-migration/references/workers.md

@@ -19,7 +19,7 @@ Plan a lane only when the source proves that surface exists:
 | routes          | route modules, redirects, SEO and host behavior | immediately              |
 | content planner | schemas, content payloads, and content handoff  | immediately              |
 | locales         | locale setup and translated UI copy             | immediately              |
-| assets/forms    | media uploads and form behavior                 | after content planner    |
+| assets/forms    | media uploads and form behavior                 | after discovery fan-in   |
 | content data    | one schema/locale import                        | after assets             |
 | content code    | listed consuming files                          | after its data read-back |
 | validator       | read-only final checks                          | after all writers        |
@@ -35,15 +35,19 @@ read-back.
 - **runtime** preserves the detected framework, router, runtime, dependencies,
   provider setup, environment wiring, and provider-specific configuration. An
   unclear or unsupported setup produces a question, not a silent conversion.
+  It reports active media found in its surface.
 - **routes** preserves every route, redirect, 404, SEO/OG/social output,
   sitemap, robots, feeds, headers, and other observable host behavior. A file
-  that consumes migrated content belongs to its later content-code worker.
+  that consumes migrated content belongs to its later content-code worker. It
+  reports active route and SEO media.
 - **content planner** discovers and models all editable content, labels,
-  consumers, schemas, payloads, media obligations, and execution batches. It
-  never imports entries or rewrites consumers. Read
+  consumers, schemas, payloads, media in its content/API surface, and execution
+  batches. It first retrieves any API-backed source through the application's
+  real client contract; it never imports entries or rewrites consumers. Read
   `references/workers/content-planner.md`.
-- **assets/forms** uploads every planner media obligation and patches payload
-  references. It replaces a form or integration only when Fimo preserves its
+- **assets/forms** receives only the coordinator's consolidated, deduplicated
+  media-obligation list, uploads it, and returns mappings for code and payload
+  consumers. It replaces a form or integration only when Fimo preserves its
   behavior end to end; otherwise it preserves or reports it.
 - **content data and code** execute the planner handoff without rediscovering
   or redesigning it. Read `references/workers/content-execution.md`.
@@ -62,12 +66,17 @@ other after it. Do not add a metadata format for a small overlap.
    write.
 2. Start runtime/routes/content-planner/locales together, or the framework
    worker plus content planner/locales in conversion mode.
-3. After the content plan, upload every planned asset and patch payloads.
-4. Start data workers only after the asset gate and, in conversion mode, the
+3. Wait for every discovery receipt to become terminal, then perform one fan-in
+   of runtime/framework, routes/SEO, and content media findings. Combine and
+   deduplicate them into the complete media-obligation list; do not run another
+   discovery pass.
+4. Give only that consolidated list to assets/forms. Wait for its mappings
+   before code or payload consumers replace source references.
+5. Start data workers only after the asset gate and, in conversion mode, the
    framework gate.
-5. Start each code worker only after its own imported records read back as
+6. Start each code worker only after its own imported records read back as
    non-empty. A build over empty data proves nothing.
-6. Start the independent validator only after every writer has returned.
+7. Start the independent validator only after every writer has returned.
 
 Each prompt names the worker's source paths, exact target ownership, applicable
 reference above, and dependencies. Each report states status, duration, source

package/assets/skills/fimo-migration/references/workflow.md

@@ -45,8 +45,16 @@ Classify the available evidence:
 
 For private APIs or CMSs, ask for a user-provided export or a narrowly scoped
 server-side credential. Never recover credentials from browser bundles or copy
-them into migration artifacts. Missing access blocks only that lane and becomes
-an unresolved item; never invent replacement content.
+them into migration artifacts. If the source API URL or access is missing or
+unreachable, stop and ask the user for it; do not guess or continue with
+replacement content.
+
+For API-backed content, trace the active client and call sites in source code,
+prove one read, then retrieve all required pages, locales, relations, and media
+during content planning. Use direct requests for bounded endpoints or a
+temporary read-only script for repeated and paginated reads. Do not wait for
+schema or code workers, and do not rely on browser traffic when SSR or build
+time fetches may hide the requests.
 
 For URL-only migrations, run `fimo migrate <url> [dir]` and inspect the
 generated `.fimo/migrations/current/` files as source evidence. Do not copy
@@ -58,16 +66,18 @@ The coordinator launches only the workers supported by the source:
 
 - **runtime**: preserve the detected framework, router, runtime, dependencies,
   provider configuration, and environment wiring. A framework conversion needs
-  an explicit user choice.
+  an explicit user choice. Report active media found in this surface.
 - **routes/SEO**: preserve one target route per source route, redirects, 404,
   metadata, OG/social output, sitemap, robots, and other observable behavior.
+  Report active media found in this surface.
 - **content planner**: discover content, labels, data sources, consumers, and
   schemas; push schemas and prepare content payloads. It does not rewrite page
-  code or import every entry itself.
+  code or import every entry itself. Report active media found in content and
+  API data; do not rescan unrelated runtime or route surfaces.
 - **locales**: configure locales and migrate translated UI-visible copy when
   the source has it.
-- **assets/forms**: after content planning, upload every referenced media item
-  and preserve, replace, or report forms and integrations.
+- **assets/forms**: after the discovery fan-in, upload the consolidated media
+  obligations and preserve, replace, or report forms and integrations.
 
 When the user explicitly chose a framework conversion, one framework
 conversion worker replaces the runtime and routes lanes and owns all
@@ -82,17 +92,22 @@ Workers may write the application inside their ownership. They do not need a
 JSON plan or receipt. If two workers need the same file, name one owner and run
 the other after it.
 
-## Phase 3: Content planning
+## Phase 3: Discovery fan-in and content planning
 
 The planner follows `references/workers/content-planner.md`, plus
 `references/content.md`, `references/decision.md`, and
 `references/import-contract.md`. Its text plan and payloads must be complete
-before Phase 4; data workers must not rediscover unrelated source files.
+before Phase 4; this includes retrieving API-backed source data and tracing its
+consumers. Data workers must not rediscover unrelated source files.
+
+After the runtime/framework, routes/SEO, and content discovery receipts are all
+terminal, the coordinator combines and deduplicates their media findings into
+the complete media-obligation list. This is the media worker's only input.
 
 ## Phase 4: Media, forms, and integrations
 
-1. Account for every planner media obligation, including schema media fields
-   and richtext/Tiptap image nodes, plus route, SEO, and form media.
+1. Account for every consolidated media obligation, including schema media
+   fields and richtext/Tiptap image nodes, plus route, SEO, and form media.
 2. Upload media through Fimo and replace references only after the upload is
    confirmed. A local `public/` copy or source URL is not an imported asset.
 3. Preserve third-party integrations unless Fimo reproduces their exact
@@ -139,4 +154,7 @@ Use `complete` only when required checks pass, `complete-with-unresolved` when
 the app works and every gap is explicit, and `draft-only` when import or
 verification is incomplete.
 
-All checks are local. Do not deploy or publish to verify a migration.
+All checks are local. Deployment is not QA evidence. After successful local QA,
+run one plain `fimo deploy` for a newly created project unless the user opted out
+or `FIMO_MIGRATION_NO_DEPLOY=1`; for an existing linked project, offer deploy and
+wait for approval. Never publish automatically.