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

package/assets/skills/fimo-migration/references/frameworks/nextjs.md

@@ -158,6 +158,14 @@ document, and a `public/` reference may become a media upload. The content
 planner decides the destination from the consuming route and data shape, rather
 than using a filename or extension as an automatic classification.
 
+Preserve how that content reaches the page. Local Markdown rendered during a
+Next build stays a Server Component or static-generation read after it moves to
+Fimo. Keep `generateStaticParams` when the source has known routes, list the
+required slugs once, and use the generated client's `getBySlug` for each detail
+page. Do not fetch the full post collection and filter it on every route, and do
+not introduce a Client Component solely to load Fimo content. Follow the shared
+evidence and freshness contract in `references/questions-and-improvements.md`.
+
 Create one source item per Markdown/MDX document and per independently handled
 construct inside it. Portable prose and an executable MDX component are
 different items even when they share one file. Read the custom component, its

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

@@ -85,6 +85,16 @@ items.
   and public APIs were read under their simple access rules; private sources
   used a user export or narrowly scoped server-side credential. Missing access
   is unresolved for that lane, and no content was guessed.
+- Each content family moved from local or bundled files to Fimo records its
+  build-time, request-time, or browser delivery mode before and after migration.
+  Build-time and server-rendered source content did not become a browser API
+  waterfall.
+- Detail routes use a direct generated-client lookup when available. Indexes use
+  bounded pagination and projection. Shared reads are deduplicated, independent
+  reads start together, and page-only reads do not block a shared root layout.
+- Production evidence labels cold and warm navigation separately and records
+  observable Fimo/API request counts, duplicates, order, and longest blocking
+  read. Development-only timing is never presented as production proof.
 
 For linked Next.js targets, the root `FimoProvider` resolves an explicit host
 connection first, otherwise `.fimo/project.json` plus the active git branch,
@@ -124,6 +134,8 @@ Owned by the runtime lane; verified here read-only.
 ## Behavior
 
 - Dependencies are installed in the target project.
+- The recorded CLI and companion package specifiers are reproducible outside
+  the current package-manager cache and match the selected runtime channel.
 - The project builds successfully.
 - Local dev starts without Vite loader/schema/form generation errors.
 - Primary routes render without console/runtime errors.
@@ -135,6 +147,10 @@ Owned by the runtime lane; verified here read-only.
 - Every content-code batch exercised at least one non-empty imported item
   through each Server-to-Client or plain-JSON boundary it introduced; build
   success over an empty query result does not pass this check.
+- Server-rendered source content remains in the initial server result and is not
+  fetched again after hydration. A new client waterfall, repeated full-list
+  read, avoidable sequential request chain, or stale edit fails the responsible
+  migration lane.
 - Navigation and footer links point to migrated routes or documented external URLs.
 - Missing integration secrets do not block these checks: build, dev, and route
   render run with the integration inert, and the missing key is a recorded
@@ -160,7 +176,9 @@ equivalent):
 5. Assert globally rendered label/button text (header/footer nav, CTAs, cookie
    banner) is non-empty; blank text usually means the component is mounted
    outside the label provider.
-6. Inspect the browser console and server output for runtime errors.
+6. Assert visible text and attributes contain no source-absent serialization
+   sentinels such as `undefined`, `null`, `[object Object]`, or `NaN`.
+7. Inspect the browser console and server output for runtime errors.
 
 Keep it bounded: representative pages and one interaction, not an interactive
 walk of every route or a multi-hour visual audit. The Visual section below
@@ -176,6 +194,11 @@ report; never claim a visual check that did not run.
 - Prioritize layout, typography, content hierarchy, media, and brand tokens.
 - Remove generated placeholder copy from visible UI.
 - Verify media aspect ratios and no broken images on primary routes.
+- Compare representative component bounds; whole-page height can hide a local
+  geometry regression.
+- Compare image loading before and after scroll. Record eager/lazy and preload
+  counts, response formats, and representative transfer sizes; an optimizer
+  URL alone is not delivery proof.
 
 ## Import Verification
 
@@ -231,6 +254,8 @@ complete | complete-with-unresolved | draft-only
 
 ## Hosting
 
+## Content Delivery
+
 ## Timing
 
 ## Checks
@@ -248,9 +273,10 @@ locales) with `gate`,
 coverage must not average away a missing entry or an unuploaded asset. Timing is
 a separate section copied from the worker reports, so it never dilutes coverage.
 
-Cache freshness is a report check only when the source or user made freshness an
-accepted observable requirement; do not fail a migration for omitted provider
-cache mechanics alone.
+Cache freshness is a report check whenever migration changes the content
+transport or rendering mode. Do not fail a migration for omitted provider cache
+mechanics alone, but do fail stale Fimo edits caused by the target's migrated
+read path.
 
 Use `complete` only when all required checks pass. Use
 `complete-with-unresolved` when the migrated site is usable and all gaps are

package/assets/skills/fimo-migration/references/questions-and-improvements.md

@@ -0,0 +1,188 @@
+# Migration questions and content delivery
+
+## Inspect before asking
+
+Start with read-only source inspection. Find the framework, router, version,
+content sources, integrations, API routes, environment variable names, and
+obvious runtime constraints. Do not initialize or link the target, edit files,
+write Fimo data, contact private services, deploy, or publish yet.
+
+Do not ask the user to explain facts the source already proves. Ask only when
+the answer changes authorization or forces a real choice:
+
+- an integration may be removed, replaced, disconnected, or moved;
+- environment configuration or credentials may need to move into Fimo;
+- the source framework is unknown or the user requested a conversion;
+- the source defines CMS content but the deployed records are unavailable;
+- two systems could own the same content or behavior; or
+- the requested migration includes a destructive or mutually exclusive choice.
+
+Preserve the source's visible behavior by default. Do not ask the user to list
+the routes, metadata, feeds, forms, locales, analytics, or content that must
+survive. Discovering and preserving them is the migration job. Do not ask a
+generic speed, optimization, or framework-upgrade question during migration.
+
+## Ask one stacked batch
+
+Use the coding agent's native structured-question UI when it has one. The tool
+name differs between Codex, Claude Code, and other hosts.
+
+- Collect decisions from the same inspection and ask one preflight batch. Aim
+  for one to three questions.
+- Include setup blockers already visible at that point, such as a missing target
+  choice, organization or project, URL-only framework choice, or pinned CLI
+  artifact. Do not save them for separate follow-up turns.
+- Give each question a short subject and two or three concrete choices. Put the
+  recommended safe default first and state the consequence of each choice.
+- Write for the site owner, who may not know Fimo or the migration process. Do
+  not put evaluator terms such as faithful acceptance, frozen result, or probe
+  in a user-facing question. Explain Fimo terms the first time they matter.
+- Group environment keys by the integration they enable. Never ask one question
+  per key.
+- Use multi-select for independent choices when the host supports it. Otherwise
+  offer a few useful bundles.
+- Restate the accepted contract once after the answers, then start. Ask again
+  only when new evidence creates a safety or consent decision that the initial
+  inspection could not reveal.
+- When the host has no structured-question UI, send the whole batch as one
+  numbered message. Do not drip questions across turns.
+
+## Protect integrations and environment values
+
+Detect integration and environment key names without printing or reading their
+values. A request to migrate the website is not consent to move any environment
+value.
+
+- Keep third-party behavior wired when Fimo does not replace it exactly.
+- Never silently remove, replace, or partly imitate an integration.
+- Ask before changing its owner, credential store, or runtime behavior.
+- Without consent, leave current environment references unchanged. Mark live
+  verification blocked when credentials are unavailable.
+- When the user chooses Fimo storage, load the current `fimo-cli`
+  `project-vars-and-secrets` reference. Browser-safe configuration uses project
+  variables. Hidden API keys and tokens use project secrets. Never turn a
+  secret into a public variable.
+- When the owner chooses Fimo-managed secrets, ask them to add the values to
+  Fimo. Never read existing secret values from env files, logs, browser code,
+  migration artifacts, or worker transcripts.
+
+## Ask before reconstructing missing CMS content
+
+Source repositories often contain CMS schemas and rendering code without the
+deployed records. A public website can recover what visitors can see, but it
+cannot prove drafts, unlinked records, editorial metadata, hidden relations, or
+private fields. Do not silently substitute scraped pages for the missing CMS.
+
+When required CMS records are unavailable, ask one question with these choices:
+
+- **Provide CMS access or an export (Recommended).** Use a scoped read-only
+  credential or export to preserve the selected records, relations, locales,
+  SEO, and media as completely as the source allows.
+- **Rebuild from the public website.** Use credential-free public APIs when
+  available, then the rendered pages for the user-approved route slice. Treat
+  the run as hybrid, import only published evidence, and report everything the
+  public site cannot reveal.
+- **Migrate code only.** Keep the CMS integration and its records outside Fimo;
+  do not claim that editorial content moved.
+
+The question should sound like this:
+
+> The repository contains the CMS structure, but not the content currently
+> published on the site. Should I use a read-only CMS export, rebuild the
+> selected pages from the public website, or migrate only the code and leave the
+> content where it is?
+
+If the owner chooses the public website, stay inside the selected route scope.
+Public retrieval does not authorize private endpoint discovery, credential use,
+or a broader crawl. Record the URL, retrieval time, redirects, and every field
+or relation that remains unknown.
+
+## Ask what happens outside a partial migration
+
+When the request selects only part of a website and does not say what should
+happen to the remaining pages, ask in the same preflight batch:
+
+> We're moving only part of the site. What should happen when someone follows
+> a link to a page we aren't moving?
+
+Offer these choices:
+
+- **Keep opening the current site.** Preserve working absolute source URLs for
+  pages outside the selected slice.
+- **Remove those pages.** Remove their navigation links and redirect known old
+  routes to the migrated homepage instead of leaving broken relative links.
+
+Do not ask when every route is migrating or the request already settles this
+behavior. If the coordinator discovers an omitted route only after preflight,
+preserve its working absolute source URL and report it. Do not interrupt the
+migration with a late preference question.
+
+## Preserve content delivery performance
+
+Replacing local Markdown, MDX, JSON, or hardcoded content with Fimo reads must
+not add an avoidable runtime wait. This is migration correctness, so apply it
+without asking an optimization question.
+
+First record how the source delivers each content family: at build time, on the
+server per request, or in the browser. Load the current `fimo-code` framework
+and generated-client references, then keep the same rendering and freshness
+semantics unless the target framework requires a documented equivalent.
+
+- Keep build-time or server-rendered source content on the server. Do not turn
+  a local Markdown page into a client-side loading state or browser API
+  waterfall.
+- Preserve known-route generation. For a static blog, list slugs once for route
+  generation, then use `getBySlug` or another direct generated-client lookup for
+  each detail route. Do not list the whole collection and filter it again on
+  every page request.
+- Start independent reads together. Keep page-only content out of shared root
+  layouts, and deduplicate the same read when metadata, a layout, and a page
+  need it during one render.
+- Query only the fields, relations, and page of records the route consumes.
+  Populate required references explicitly. Avoid unbounded collection reads and
+  N+1 relation lookups.
+- Keep framework links and their normal prefetch behavior. Do not add broad
+  forced prefetching that turns a page list into a burst of Fimo requests.
+- Preserve edit freshness. Static generation, revalidation, or caching is valid
+  only when a normal rebuild or the source's normal refresh path shows the new
+  Fimo value. Cold-build once as a diagnostic when the normal result is stale.
+- Do not upgrade the framework, change routers, add loading placeholders, or
+  redesign the page to satisfy this rule. Those are separate changes unless the
+  user explicitly requested them.
+
+Examples:
+
+- **Static Markdown blog:** import every post into Fimo, generate the known
+  routes from a bounded slug list, read each post on the server during static
+  generation, and ship the article in the initial HTML. A browser fetch for the
+  article body is a migration regression.
+- **Large collection:** use a paginated, projected list for the index and a
+  direct slug lookup for the detail page. Fetching every full record for every
+  navigation is a migration regression even when the page eventually matches.
+- **Fresh request-time page:** keep the Fimo read in the framework's server
+  loader or Server Component. Stream only when the source already tolerated
+  partial rendering or a new wait would otherwise block the whole page.
+
+## Prove the transport did not regress
+
+Run the production build and production server. Development mode may include
+compilation and may disable prefetching, so label any development observation
+as development-only.
+
+For every content family moved from local or bundled source files to Fimo:
+
+1. Record whether the source and target reads happen at build time, request
+   time, or in the browser.
+2. Check one cold navigation and one warm navigation separately.
+3. Capture Fimo/API request count, duplicate reads, request order, and the
+   longest blocking read when observable.
+4. Verify that server-rendered source content remains in the initial server
+   result and is not fetched again after hydration.
+5. Run the normal edit, render, and revert proof. When caching or static output
+   is involved, record normal-build and cold-build freshness separately.
+
+Do not invent a universal millisecond budget. Timing starts as evidence. Fail
+the migration when it introduces an objective transport regression, such as a
+new client waterfall, repeated full-list reads, avoidable sequential requests,
+or stale edits. A broader performance review or framework upgrade is separate
+work and starts only when the user explicitly asks for it.

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

@@ -66,15 +66,20 @@ data workers start:
    REST endpoints. Ask for an owner-provided export or narrowly scoped
    server-side token only when website-required records are not public. Never
    recover, log, persist, or copy secret values. If required access is missing
-   or unreachable, stop before planning schemas or payloads.
+   or unreachable, stop before planning schemas or payloads until the owner
+   chooses scoped access, public-site reconstruction, or a code-only migration.
 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;
+4. When the owner chose public-site reconstruction, retrieve only the approved
+   published routes. Use credential-free public APIs when available and rendered
+   HTML otherwise. Mark drafts, unlinked records, hidden relations, and private
+   fields unknown instead of inventing them.
+5. 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
+6. Design Fimo schemas from both the retrieved values and the code that uses
    them. Keep uncertain fields optional unless authoritative evidence requires
    them; sampled enum-like values are strings, and private or absent fields
    remain unknown. Never invent replacement content when access is unavailable.

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

@@ -1,7 +1,16 @@
 # Migration validator
 
-The validator is an independent read-only worker. It did not author the
-migration and starts only after all writers return.
+Validation is one independent read-only wave after all writers return. The
+coordinator gives every validator the accepted migration scope and deliberate
+user-approved differences, but no producer findings, repair reasoning,
+transcript, or expected verdict. A validator checks the finished target against
+the source within that contract. It does not report an explicitly excluded
+route, integration, or control as migration drift.
+
+When subagents are available, launch separate workers for build and runtime,
+Fimo data and content, and rendered browser behavior. Run them concurrently
+after their prerequisites pass. They may inspect overlapping files because none
+of them writes.
 
 Compare the source, content plan, actual `git diff`, real Fimo state, and local
 application behavior. A worker report is a claim, not evidence.
@@ -29,7 +38,12 @@ representative page responds. After an approved deploy, browser QA must:
 
 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
-or loop indefinitely.
+Each lane continues through independent assertions and returns status,
+duration, checks run, counts, failing source items, blocked descendants, and
+suggested repair ownership. Stop only when a failed prerequisite makes a check
+meaningless.
+
+The coordinator fans every lane into one finding set before editing. It assigns
+disjoint repair owners, waits for the whole repair wave, then reruns one central
+validation wave. It does not restart every worker, repair findings one at a
+time, or loop indefinitely.

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

@@ -22,7 +22,7 @@ Plan a lane only when the source proves that surface exists:
 | 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        |
+| validation wave | read-only build, data, and rendered checks      | after all writers        |
 
 This is preserve mode, the default. When the user explicitly chose a framework
 conversion, one framework worker replaces runtime and routes and owns all
@@ -55,7 +55,7 @@ read-back.
   visitor-visible labels.
 - **framework conversion** is used only after explicit user choice. Read
   `references/workers/framework.md`.
-- **validator** authors nothing. Read `references/workers/validator.md`.
+- **validation wave** authors nothing. Read `references/workers/validator.md`.
 
 If two lanes need one file, name one owner in the text plan and sequence the
 other after it. Do not add a metadata format for a small overlap.
@@ -76,7 +76,9 @@ other after it. Do not add a metadata format for a small overlap.
    framework gate.
 6. Start each code worker only after its own imported records read back as
    non-empty. A build over empty data proves nothing.
-7. Start the independent validator only after every writer has returned.
+7. After every writer returns, start one read-only validation wave. When
+   subagents are available, run build and runtime, Fimo data and content, and
+   rendered browser checks concurrently after their prerequisites pass.
 
 Each prompt names the worker's source paths, exact target ownership, applicable
 reference above, and dependencies. Each report states status, duration, source
@@ -84,8 +86,17 @@ evidence, files changed, Fimo writes, source items handled, unresolved work,
 and the next action. The coordinator verifies those claims against `git diff`,
 CLI read-back, and rendered routes.
 
+Validation prompts also carry the accepted migration scope and user-approved
+differences, including selected routes, behavior for routes outside a partial
+migration, excluded integrations, and the deploy boundary. This is task context,
+not an expected verdict. Do not give validators producer findings, repair
+reasoning, transcripts, or instructions to accept a difference.
+
 A source item is covered only when its target value exists and the application
 consumes it at the original behavior path, or when an explicit unresolved item
-names the impact and owner action. If validation fails, create one bounded
-repair task for that surface and rerun the validator; do not restart every
-worker.
+names the impact and owner action. Collect the complete finding set before
+repair. Fan it into one repair graph, run disjoint repair owners together, wait
+for all of them, then rerun one central validation wave. A failed prerequisite
+blocks only dependent checks; it does not stop unrelated diagnostics. Do not
+restart every worker or alternate one finding with one repair when the next
+validation pass could have exposed the full set.

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

@@ -4,6 +4,15 @@ Use this as the phase contract for a complete migration. The coordinator and
 workers communicate in plain text. JSON is used only for Fimo schemas and the
 content payloads that the data-plane commands import.
 
+## Preflight: inspect and ask
+
+Before target initialization or any other write, inspect the source read-only
+and follow `references/questions-and-improvements.md`. Use the coding agent's
+native structured-question UI to ask one stacked batch for integration,
+environment, framework, and ownership decisions that the source cannot settle.
+Never move environment values or credentials without explicit consent. Do not
+ask a generic optimization question.
+
 ## Phase 0: Initialize the target
 
 1. Confirm the target path. The target is a separate directory; the source
@@ -20,9 +29,15 @@ content payloads that the data-plane commands import.
 3. Inspect the target's real `package.json`, `.fimo/config.json`, framework config, and route
    directories. They are the authority for paths. Do not infer an app root
    from a skill example and do not create a second `app/` or `src/app/` tree.
-4. If the target is non-empty and not a Fimo project, stop and ask for a target
+4. Verify dependency provenance before workers start. A project created by a
+   published CLI pins that exact CLI release and matching companion packages.
+   A local source-checkout project uses the checkout-local CLI. Stop when the
+   target records an absolute package-manager cache path, an unapproved
+   `latest`, or a CLI and API from different runtime channels; do not let the
+   producer repair release setup inside the migration.
+5. If the target is non-empty and not a Fimo project, stop and ask for a target
    path; do not overlay a template on top of it.
-5. Keep source material in `.fimo/migration/source` or another explicit source
+6. Keep source material in `.fimo/migration/source` or another explicit source
    location. Do not copy source files over the initialized target root.
 
 Write a short `.fimo/migration/migration-plan.md` containing the source
@@ -46,8 +61,10 @@ 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. 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.
+unreachable, stop and ask whether to use scoped access, reconstruct only the
+selected published routes from the public site, or migrate code without the CMS
+records. Continue with public reconstruction only after that explicit choice,
+and record everything the rendered site cannot reveal.
 
 For API-backed content, trace active clients, endpoints, frontend types, and
 consumers first. Prefer backend source schemas; otherwise use public OpenAPI,
@@ -143,12 +160,22 @@ one generic static shell. Apply the matching framework reference before
 disposing of provider-specific rules; redirects, headers, feeds, metadata,
 forms, and freshness behavior are observable contracts.
 
+When local or bundled content becomes Fimo-backed, follow the content-delivery
+contract in `references/questions-and-improvements.md`. Preserve build-time or
+server rendering, direct lookups, bounded reads, request parallelism, and edit
+freshness. A new browser waterfall, repeated full-list read, avoidable
+sequential request chain, or stale edit is a migration regression.
+
 ## Phase 6: Fan in, validate, and report
 
 Workers return the plain-text receipt defined in `references/workers.md`.
 The coordinator checks those claims against the diff, source, CLI read-back,
-build, and rendered routes. Then an independent worker follows
-`references/workers/validator.md`; a worker saying "done" is not evidence.
+build, and rendered routes. Then it runs the read-only validation wave from
+`references/workers/validator.md`, passing the accepted scope and deliberate
+user-approved differences as task context; a worker saying "done" is not
+evidence.
+Collect the complete finding set before assigning repairs. Run disjoint repair
+owners together, wait for all repairs, and rerun one central validation wave.
 
 Write `.fimo/migration/migration-report.md` with route/content/media/form/SEO
 coverage, import counts, worker timings, unresolved items, and next actions.

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

@@ -6,7 +6,7 @@ description: >-
   Triggers: "in Fimo Studio", "in the dashboard", "in the web app",
   "how do I X in the UI", or screenshots of the dashboard. Topics
   covered: dashboard content and CMS, publishing from the dashboard,
-  dashboard SEO/domain settings, project connections, schedules and run history, outbound webhooks,
+  dashboard SEO/domain settings, project connections, agents, schedules and run history, outbound webhooks,
   visual editing, version history UI, dashboard sharing/billing, dashboard chat,
   and the command palette. Never describe
   UI locations, buttons, or panels from memory — always read the relevant
@@ -39,6 +39,7 @@ Read the relevant reference file when the user's question matches a topic.
 | AI Chat                  | references/ai-chat.md                   | "What can the AI do?", "How do I give context?"       |
 | Code Editor              | references/code-editor.md               | "How do I edit code?", "Where are my files?"          |
 | SEO Settings             | references/seo-settings.md              | "How do I set up SEO?", "Favicon, title, share image" |
+| Agents                   | references/agents.md                    | "Run an agent", "Pause an agent", "Next agent run"    |
 | Schedules                | references/schedules.md                 | "Recurring commands", "Run history", "Run now"        |
 | Webhooks                 | references/webhooks.md                  | "React to forms", "Send events to another service"    |
 | Connections              | references/connections.md               | "Connect a service", "Add an MCP server"              |
@@ -60,6 +61,7 @@ Read the relevant reference file when the user's question matches a topic.
 | Content/CMS             | AI Chat, Media Library                                                         |
 | Webhooks                | Project secrets, Forms, Publishing, Agents                                     |
 | Connections             | AI Chat, Agents, Project secrets                                               |
+| Agents                  | Connections, Project secrets, Branches                                         |
 | Schedules               | Project secrets, Environments, Agents                                          |
 | Visual changes          | Edit Mode (quick tweaks), AI Chat (bigger changes), Code Editor (full control) |
 | Something went wrong    | Version History, AI Chat                                                       |

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

@@ -0,0 +1,25 @@
+# Agents
+
+Project agents are versioned bundles from the project's repository. Studio lets project members inspect their configuration and run history, while project managers can start, stop, and resume them.
+
+## Open an agent
+
+1. Open the project and choose **Agents**.
+2. Select **Agents** again to see the available bundles.
+3. Choose an agent to open its **Runs** and **Settings** tabs.
+
+When the agent has a live schedule, its next run appears first in **Runs**, marked **Scheduled**. The row uses **Next** for its projected ID, a relative date such as **Tomorrow at 11:00 AM**, and **—** for changes and duration until it starts. **Settings** shows the bundle's declared capabilities and trigger wiring; it is read-only because the repository remains the source of truth.
+
+## Run, stop, or resume
+
+Choose **Run** to start an agent whose manual trigger is live.
+
+Choose **Stop** to pause every future trigger and stop planned or running work. Studio asks for confirmation and explains that the bundle, trigger configuration, model, capabilities, and other settings are preserved.
+
+A stopped agent shows **Paused** in the header. **Resume** makes the same triggers live again with their previous settings.
+
+Only project managers see Run, Stop, and Resume. Other project members can still see schedule timing, status, settings, and run history.
+
+## Inspect runs
+
+Open **Runs** on an agent to see only that bundle's history. Select a run to read its status, report, captured changes, and any question or review state that needs attention.

package/assets/skills/fimo-studio/references/preview-and-responsive.md

@@ -2,7 +2,7 @@
 
 Click the **Preview** tab (the cursor/pointer icon) to see a live version of your site right inside the editor. You can also press **Alt+1** to jump to the preview tab.
 
-- Use the **route selector** dropdown at the top to navigate between different pages.
+- For Fimo-integrated sites, use the **route selector** dropdown at the top to navigate between different pages.
 - Click the **refresh** button to reload the preview.
 - Click the **external link** icon to open your site in a new browser tab for a full-screen view.
 
@@ -34,6 +34,9 @@ To go back to a full-width preview, toggle the responsive mode off.
 You may see different overlays depending on what is happening:
 
 - **"Working"** -- A loading overlay (heading "Working", subtext "Getting your preview in motion...") while the preview is being prepared.
+- **"Connecting to Fimo…"** -- The site is already visible while Studio waits for visual editing and route controls to connect. You can dismiss this status without interrupting the preview.
+- **"Recovering preview…"** -- The visible preview is reloading after a refresh or a recoverable development-server failure.
+- **"Editing unavailable"** -- The site remains visible, but its Fimo integration did not connect in time. Visual editing and the route selector stay unavailable; preview and refresh still work.
 - **Error overlay** -- Something went wrong. The overlay shows details about the issue, and the AI can often auto-fix it for you.
 - **"Some installed packages need approval"** -- Choose **Fix with Fimo** to send the complete repair context to the coding agent, or **Copy details** to handle it elsewhere. Review every named package, commit only trusted package-specific approvals, and retry Preview. Never replace the project policy with a blanket allow-all setting.
 - **First generation progress** -- When your project is being built for the first time, a progress overlay shows the current status.

package/assets/skills/fimo-studio/references/visual-editing.md

@@ -8,7 +8,15 @@ Once in edit mode, click on any element in the preview -- text, buttons, images,
 
 ### Editing Content
 
-For text elements, the side panel shows editable fields where you can change the text directly. This covers CMS-managed content, hardcoded text, and hardcoded images. Changes save automatically, and the preview updates as you type.
+For text elements, the side panel opens the selected field immediately with its current value. This covers CMS-managed content, hardcoded text, and hardcoded images. Changes save automatically, and the preview updates as you type.
+
+For CMS content, choose **All fields** to open the complete entry form. Studio keeps the content type's field order, scrolls to the field you selected, and focuses it in place. Loading appears only while Studio fetches this additional entry data or moves to another entry.
+
+### References and Components
+
+Selecting a field rendered from a referenced entry edits that entry. For example, selecting an author's name opens the Author entry, not the Post relation that links to it. The header shows the relation path. Select the owning entry in that path to return to its complete form with the relation field focused; use that relation field to open, replace, or clear the linked entry.
+
+Selecting a field inside a component focuses that nested field. Choose **All fields** to see it in the complete entry form without moving it out of schema order. The shared CMS form provides the existing add, duplicate, remove, and reorder controls for repeatable components and blocks.
 
 ### Editing Styles
 

package/dist/build/astro/config.js

@@ -1,6 +1,7 @@
 import { fileURLToPath } from 'node:url';
 import { getConfigPreviewRoutes } from '../../runtime/preview/routes.js';
 import { getConfigServer } from '../../runtime/shared/fimo-config.server.js';
+import previewHealthPlugin from '../vite/plugins/preview-health.js';
 import runtimeEnvPlugin from '../vite/plugins/runtime-env.js';
 function serializeForModule(value) {
     return (JSON.stringify(value) ?? 'undefined')
@@ -32,7 +33,7 @@ export function fimo(options = {}) {
                 // `as never` sidesteps a TS "excessive stack depth" on Astro's
                 // DeepPartial<AstroConfig> vs Vite's Plugin type; the shape is the
                 // documented `updateConfig({ vite: { plugins } })`.
-                updateConfig({ vite: { plugins: [runtimeEnvPlugin()] } });
+                updateConfig({ vite: { plugins: [runtimeEnvPlugin(), previewHealthPlugin()] } });
                 const fimoConfig = getConfigServer(fileURLToPath(config.root));
                 const routes = getConfigPreviewRoutes(fimoConfig);
                 injectScript('page', [

package/dist/build/vite/plugins/preview-health.d.ts

@@ -0,0 +1,4 @@
+import type { Plugin } from 'vite';
+export declare const PREVIEW_HEALTH_PATH = "/__fimo/preview-health";
+export default function previewHealthPlugin(): Plugin;
+//# sourceMappingURL=preview-health.d.ts.map

package/dist/build/vite/plugins/preview-health.js

@@ -0,0 +1,40 @@
+export const PREVIEW_HEALTH_PATH = '/__fimo/preview-health';
+const OPTIMIZED_DEP_PATH = '/node_modules/.vite/deps/';
+export default function previewHealthPlugin() {
+    let failure = null;
+    return {
+        name: 'fimo:preview-health',
+        apply: 'serve',
+        configureServer(server) {
+            // FIMO-1589: the sandbox watcher needs a durable signal because Vite's
+            // one-shot HMR reload can fire before the hosted preview socket connects.
+            if (!process.env.FIMO_PREVIEW_ALLOWED_ORIGINS) {
+                return;
+            }
+            server.middlewares.use((req, res, next) => {
+                const url = new URL(req.url ?? '/', 'http://127.0.0.1');
+                if (url.pathname === PREVIEW_HEALTH_PATH) {
+                    res.statusCode = 200;
+                    res.setHeader('content-type', 'application/json');
+                    res.end(JSON.stringify({
+                        failureGeneration: failure?.generation ?? 0,
+                        lastFailure: failure,
+                    }));
+                    return;
+                }
+                if (url.pathname.includes(OPTIMIZED_DEP_PATH) && url.searchParams.has('v')) {
+                    res.once('finish', () => {
+                        if (res.statusCode >= 500) {
+                            failure = {
+                                generation: (failure?.generation ?? 0) + 1,
+                                status: res.statusCode,
+                                at: Date.now(),
+                            };
+                        }
+                    });
+                }
+                next();
+            });
+        },
+    };
+}

package/dist/cli/bundle.json

@@ -1,7 +1,7 @@
 {
   "bundled": true,
   "bundler": "esbuild",
-  "bundledAt": "2026-08-26T13:08:32.124Z",
+  "bundledAt": "2026-08-28T13:10:10.719Z",
   "cliVersion": "2.1.0",
   "external": [
     "oxc-parser",