fimo 2.7.1 → 2.8.0-staging.2

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

@@ -16,6 +16,6 @@ Adapt these defaults to the risk and scope of this agent:
 
 - Proceed without asking when the work is within scope and a safe, reversible choice exists.
 - Ask when a missing human decision changes what the correct result should be.
-- Retain when the work is complete but all changes should be reviewed before merge.
-- Request merge only when the result is complete, verified, and clearly safe for this agent's scope.
+- Keep work open and request review when a human decision or approval is needed.
+- Merge completed, verified work within scope when runtime:auto_merge is granted; otherwise request human review.
 - Discard when the run produced no useful changes or deliberately abandoned them.

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

@@ -8,3 +8,4 @@
 - fimo:history:read
 - fimo:logs:read
 - fimo:preview:read
+- runtime:auto_merge

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

@@ -1,2 +1 @@
-- net:fetch
 - fimo:analytics:read

package/assets/agent-templates/content-translator/GOAL.md

@@ -16,8 +16,7 @@ JSON files or put translated values in source code.
 For each entry:
 
 1. Read the default-locale field via `cms:read`.
-2. Translate to every missing locale (via `net:fetch` to your translation
-   provider of choice).
+2. Translate to every missing locale.
 3. Write the translation back to the matching locale entry via `cms:write`.
 4. For static UI labels, update values with the i18n/labels API rather
    than editing files.

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

@@ -1,6 +1,5 @@
-# Reads CMS and writes DB-backed localized content / labels. Net is for the translation provider.
+# Reads CMS and writes DB-backed localized content / labels.
 - cms:read
 - cms:write
 - i18n:read
 - i18n:write
-- net:fetch

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

@@ -1,2 +1 @@
-- net:fetch
 - fimo:logs:read

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

@@ -1,4 +1,3 @@
 # Read-only audit — no writes to project files or CMS.
 - cms:read
-- net:fetch
 - fimo:analytics:read

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

@@ -77,25 +77,20 @@ runtime:
 All four keys are optional; an absent `runtime` block behaves as if every key were unset. There is no platform step cap
 and no platform per-run cost ceiling — the only stops are these author-owned limits, the organization running out of
 credits (`insufficient_credits`), and the agent-hours allowance. A limit that fires records a truthful terminal reason
-(`max_steps`, `budget_exceeded`, `insufficient_credits`, or `finish_run_missing` when a run ends without calling
-`finish_run`), readable via `fimo agents report` and the Studio run page.
+(`max_steps`, `budget_exceeded`, or `insufficient_credits`), readable via `fimo agents report` and the Studio run page.
 
 ## 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.
+Runs perform compute; explicit work sessions hold project changes. Ordinary conversation and research need no session.
+Project operations name their session. Save accumulated work before a risky operation or handoff. A confirmed save
+commits and pushes without merging or publishing; Fimo also attempts a bounded save when compute ends.
 
-- **Merge** when the work is ready for the target Branch. Fimo applies the complete task environment or, if it conflicts,
-  leaves the target unchanged and keeps the work for review without choosing a side.
-- **Retain** when the completed work should be reviewed before merge, or when the run stops, fails, or may need recovery.
-  Fimo leaves the target unchanged, keeps the complete task Branch, and sends an Inbox notification asking a person to
-  review all of its changes. A later follow-up can continue from that retained work.
-- **Discard** when none of the run's work should be applied, including when it made no useful changes or deliberately
-  abandoned an approach. This permanently deletes the task Branch and every change in it without review.
+Merge ready work explicitly. Resolve clear conflicts through the existing merge tools; ask when the resolution requires
+product intent. Request review with one sessionId; request_review saves current work itself and makes that same session visible and durable. Inspecting or leaving a session open creates no review.
+Discard only unwanted work within the requested scope. Ending a run does none of these operations implicitly.
 
-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 autonomous `report` tool records a structured report without ending compute or deciding session fate. The model may
+continue working after reporting. A normal model stop ends compute. Scheduled work has no implicit publication grant.
 
 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.
@@ -106,18 +101,22 @@ When authoring or editing an agent, add a short **Decision policy** to its `GOAL
 acting, asking, review, and merge; do not copy Fimo's tool protocol. Use this shape and replace the examples with rules
 specific to the agent:
 
+Infer the intended autonomy from the user's request when it is clear. Otherwise ask what the agent may apply itself,
+what needs review, and whether it may publish. Record that policy in `GOAL.md`; do not impose review-first on every
+agent or treat permission to merge as permission to publish. A routine fixer and a proposal writer need different policies.
+
 ```md
 ## Decision policy
 
 - Proceed without asking when the work is within scope and a safe, reversible choice exists.
 - Ask when a missing human decision changes what the correct result should be.
-- Retain when the work is complete but all changes should be reviewed before merge.
+- Request review of the saved session when completed work needs a person's approval before merge.
 - Request merge only when the result is complete, verified, and clearly safe for this agent's scope.
 - Discard when the run produced no useful changes or deliberately abandoned them.
 ```
 
-Asking and review are different: `ask_user` is for a decision required before correct work can continue; `retain` ends
-the run with its complete proposal waiting for review and does not ask a question.
+`ask_user` requests a blocking decision and ends the current invocation. `request_review` saves and captures one selected session for approval
+without ending compute. Neither operation merges or discards sessions.
 
 Make those rules concrete enough that the agent can decide without guessing. For example:
 
@@ -126,8 +125,7 @@ Make those rules concrete enough that the agent can decide without guessing. For
   verification is blocked. Discard when the scan is clean or exploratory edits were reverted.
 - **Launch-copy agent:** draft from an approved brief without asking about routine wording. Ask before choosing pricing,
   product promises, brand direction, or deletions. Retain every completed draft for human review; never request merge.
-- **Read-only auditor:** inspect and report autonomously. Ask only when the requested scope cannot be inferred. Discard
-  the unchanged task environment after recording the report.
+- **Read-only auditor:** inspect and report autonomously. Ask only when the requested scope cannot be inferred.
 - **Missing capability:** ask once for the exact capability and explain which operation it unlocks. Do not retain partial
   work as a substitute for the blocking permission decision.
 
@@ -144,9 +142,8 @@ A review-first content agent could use this complete policy:
 ```
 
 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.
+question goes to the Fimo Inbox and the current invocation ends. It can reference zero or more sessions. An authorized
+answer starts a continuation in the same thread; the referenced work stays open and the original model process does not wait.
 
 Use `ask_user` sparingly, especially from scheduled agents:
 
@@ -156,7 +153,7 @@ Use `ask_user` sparingly, especially from scheduled agents:
 - 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.
+- Use `request_review` with one sessionId when approval is needed. No pre-save or promotion is required; other sessions stay unchanged and work can continue.
 
 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
@@ -169,7 +166,7 @@ behavior. Keep it under 4 KB, record no secrets or run log, and prune stale entr
 
 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.
+changes and records a brief report of what is waiting.
 
 ## Define reporting preferences when they matter
 
@@ -208,11 +205,11 @@ audience or emphasis. Even then, the brief remains the external handoff and the
 
 ## Capabilities
 
-Capabilities describe the opt-in Fimo and network actions an agent may take. Managed agents always receive project
-filesystem access, a shell, and the ability to commit their task-environment changes; Fimo owns branch creation and
-publication. If `capabilities.yaml` is absent or empty, the agent keeps baseline project reads such as agent run history,
-but receives no CMS, asset, or other domain-operation scope and no web-fetch tool. Once you add a capabilities file,
-list every Fimo or network permission the agent needs.
+Capabilities describe the opt-in Fimo actions an agent may take. Managed agents always receive project filesystem
+access, a shell, the ability to commit their task-environment changes, and web and data tools; Fimo owns branch creation
+and publication. If `capabilities.yaml` is absent or empty, the agent keeps baseline project reads such as agent run
+history, but receives no CMS, asset, or other domain-operation scope. Once you add a capabilities file, list every Fimo
+permission the agent needs. `net:fetch` is no longer needed and is ignored.
 Namespace selectors such as `cms:*`, `assets:*`, `i18n:*`, and `forms:*` grant every current and future declarable capability
 in that namespace. Fimo expands selectors to concrete grants when a run starts. Use exact tokens for narrower agents.
 The default template includes those four selectors plus read access to analytics, deployment logs, history, previews,
@@ -238,9 +235,8 @@ webhooks, and schedules; remove entries when an agent should have less access.
 | `fimo:preview:read`                         | Read a current preview URL                                                | Low          |
 | `fimo:history:read`                         | Read project restore points                                               | Low          |
 | `fimo:deploy`                               | Trigger a production deploy                                               | Critical     |
-| `net:fetch`                                 | Make outbound HTTP requests                                               | Medium       |
 | `agent:delegate`                            | Invoke declared sub-agents                                                | Medium       |
-| `runtime:auto_merge`                        | Auto-merge trivial proposed branches                                      | Critical     |
+| `runtime:auto_merge`                        | Merge work sessions without per-change review                             | Critical     |
 
 If a public Fimo capability is missing and the work is genuinely blocked, the agent can request it through `ask_user`.
 Fimo grants only the selected subset to the next invocation in that run thread. Unknown capabilities, internal runtime
@@ -282,7 +278,7 @@ fimo agents report <name> [--session <id>] [--branch <branch>] [--project <id>]
   A refusal that clears on its own (`agent-paused`, `run-in-progress`, `task-branch-budget`) exits **0** and prints `Dispatch was skipped: <reason>`. **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`.
 
 - **`runs <name>`** — list past run sessions for the agent in a compact table (id, started, duration, status, trigger, Branch, credits — settled credit consumption, `—` until a run settles). Default `--limit 20`; `--branch` filters to one Branch. The response uses the canonical `branch` field.
-- **`report <name>`** — print a run's structured **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 returns plain text without calling `finish_run` receives a small structured fallback document. With no `--session`, the most recent run for `<name>` is used (combine with `--branch` to scope); `--session <id>` targets a specific run. Output is projected 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 report, it says so (and shows the stop reason when there is one).
+- **`report <name>`** — print a run's structured **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 returns plain text without calling `report` receives a small structured fallback document. With no `--session`, the most recent run for `<name>` is used (combine with `--branch` to scope); `--session <id>` targets a specific run. Output is projected 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 report, it says so (and shows the stop reason when there is one).
 
 ## How triggers get wired
 

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

@@ -1,9 +1,23 @@
 # Analytics workflow
 
-Pageview aggregates for the **published** site are stored in Fimo's analytics pipeline. Preview traffic is not recorded.
+Pageview aggregates are read for the selected branch. Fimo production builds enable
+the React Router tracker; hosted preview builds disable it. Ingestion itself accepts
+resolved branches, so do not assume that every possible preview sender is excluded.
+
+For tracking setup, load `fimo-code`. Reading analytics does not install a tracker.
+If counts are zero, check the selected branch, built scripts, enabled setting,
+browser requests and stored results before diagnosing a missing implementation.
+A successful HTTP response alone does not establish that a row was stored.
+Use `fimo-code` analytics setup for the standalone `fimo-analytics` APIs.
+Confirm that the selected package release contains them before generating imports;
+older Fimo releases and existing published sites do not acquire a tracker automatically.
 
 Analytics has a **retained preview for every org** — free included. The free default is a 7-day retention window, so short ranges (`today`, `yesterday`, `this_week`, `last_week`, `last_7_days`) work for everyone. **Extended date ranges and longer retention are paid** — `last_30_days`, `last_90_days`, `this_month`, `last_month`, `last_quarter`, `last_year`, and `custom` require the `canUseExtendedDateRanges` privilege, which only paid orgs have. Asking for an extended range as a free user returns a 403 with an upgrade hint.
 
+For Studio tracking verification, load `fimo-studio` and its analytics reference.
+Its tracking status is independent of the chart range and device filter; a failed
+status check is not evidence of missing tracking.
+
 ## Select published traffic
 
 For traffic, growth, or site-performance questions, read **`prod`**, regardless of the current Git branch, `FIMO_ENV`, or the source branch published to Production. Analytics reads (`pageviews`, `top`, `annotations list`) default to this canonical published target. On older CLI versions, select it explicitly:

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

@@ -22,6 +22,18 @@ What it refuses to touch:
 - `file:` and development-tarball pins select a development build on purpose; they are reported as blockers, never replaced.
 - Ambiguous imports (template literals, `fimo/astro/config`) are reported as manual steps instead of guessed at.
 
+## Analytics when updating
+
+Existing analytics tracking remains supported. Keep the existing integration;
+do not add a second tracker. If the project declares `fimo-analytics`, the
+update keeps it aligned with the other Fimo packages.
+
+Updating a project without a tracker does not enable analytics. If analytics
+is wanted, load `fimo skills get fimo-code --ref analytics` and check for any
+existing tracker before adding one. After the developer publishes the update,
+verify new pageviews in Studio. Existing analytics history remains available.
+The update command itself does not publish the website.
+
 ## Reading the report
 
 `--json` returns one envelope whose `data` is stable for agents:

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

@@ -76,6 +76,14 @@ Each reference defines one package contract. Fetch it when the task reaches that
 - Framework detection, production routing, and hosting adapters → `references/frameworks/hosting.md`
 - Major visual work → `references/design.md`
 
+## Analytics
+
+For pageview installation, read [references/analytics.md](references/analytics.md).
+`FimoProviders` from `fimo-react-router` already tracks when `VITE_API_URL` and
+`VITE_ENABLE_ANALYTICS=true` are configured. Inspect the installed version and
+browser requests before adding a sender. Hosting or the neutral Vite plugin alone
+does not install a tracker. Older releases do not acquire new package exports.
+
 ## Non-negotiable boundaries
 
 - Do not hardcode editor-owned collections, page content, labels, or media in JSX.

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

@@ -0,0 +1,104 @@
+# Pageview tracking
+
+First inspect the installed package and the built page. React Router's
+`FimoProviders` already tracks when `VITE_API_URL` and
+`VITE_ENABLE_ANALYTICS=true` are present. Do not mount another sender beside an
+unmodified legacy tracker. The neutral Vite plugin and hosting alone do not
+install tracking.
+
+## Standalone setup
+
+Install a released version of `fimo-analytics` that exposes the adapter you need.
+Keep any version/channel selector the user already chose. An older `fimo`
+release does not imply these standalone APIs exist, and existing published
+sites need a code update to gain missing instrumentation.
+
+```sh
+pnpm add fimo-analytics
+```
+
+Obtain the tenant API base URL from the project's configured Fimo connection,
+and append `/e/p`. Pass that complete URL as `endpoint`. Never infer it from the
+site's public URL, guess a project hostname, or invent a discovery command. If
+the connection does not supply a tenant endpoint, obtain it before enabling
+tracking. A configured origin-relative proxy is also accepted.
+
+| Framework      | Import                                              | Placement                                    |
+| -------------- | --------------------------------------------------- | -------------------------------------------- |
+| React          | `{ Analytics }` from `fimo-analytics/react`         | Application root                             |
+| React Router   | `{ Analytics }` from `fimo-analytics/react-router`  | Inside root router                           |
+| Next App/Pages | `{ Analytics }` from `fimo-analytics/next`          | Root layout or `_app`                        |
+| Astro          | default `Analytics` from `fimo-analytics/astro`     | Shared layout, no `client:*`                 |
+| Svelte         | default `Analytics` from `fimo-analytics/svelte`    | Root component                               |
+| SvelteKit      | default `Analytics` from `fimo-analytics/sveltekit` | Root `+layout.svelte`                        |
+| Vue            | `{ Analytics }` from `fimo-analytics/vue`           | Root component, history routing              |
+| Nuxt           | `modules: ['fimo-analytics/nuxt']`                  | `analytics: { endpoint, enabled }` in config |
+
+Components accept `endpoint` and `enabled`. React example:
+
+```tsx
+import { Analytics } from 'fimo-analytics/next';
+<Analytics endpoint={endpoint} enabled={isProduction} />;
+```
+
+For Nuxt, also install the optional build peer with `pnpm add -D @nuxt/kit`.
+Next owns its client and Suspense boundaries. SvelteKit uses committed
+navigation; Nuxt covers reused pages and query changes. Generic React, Vue and
+Svelte observe history. For a router that changes the URL before committing,
+use the manual core. For Vue Router, initialize in `onMounted` after initial
+router readiness, send once, subscribe to `router.afterEach`, send only when
+`failure` is falsy, and remove the subscription and destroy on unmount.
+
+```ts
+import { init } from 'fimo-analytics';
+const analytics = init({ endpoint, enabled: isProduction, routing: 'manual' });
+// In the router's successful-navigation callback:
+analytics.pageview();
+// During cleanup:
+analytics.destroy();
+```
+
+Vanilla apps can omit `routing` to track the initial page and browser history.
+Hash routers can pass `{ path: resolvedVirtualPath, pageName }` to `pageview`;
+the React Router adapter already reads its router's virtual location.
+
+For plain HTML, copy the installed `dist/browser.js` into static assets:
+
+```html
+<script defer src="/fimo-analytics.js" data-endpoint="https://YOUR-TENANT-API-HOST/e/p" data-enabled="true"></script>
+```
+
+Use a classic script, not `type="module"`. Set `data-enabled="false"` in preview
+builds. No framework peer is required for core or HTML. Framework peers are
+optional and only the chosen adapter's framework is needed.
+
+## Choose the enabled guard
+
+Tracking defaults to enabled, so always pass `enabled`. Never use `NODE_ENV`:
+a Fimo hosted preview is a production build, so that guard leaves previews
+reporting. Read the build variable Fimo already sets:
+
+| Framework                 | Guard                                              |
+| ------------------------- | -------------------------------------------------- |
+| React Router and any Vite | `import.meta.env.VITE_ENABLE_ANALYTICS === 'true'` |
+| Next.js                   | `process.env.NEXT_PUBLIC_FIMO_ENV === 'prod'`      |
+| Build-time server env     | `process.env.FIMO_ENV === 'prod'`                  |
+
+Astro, SvelteKit, Svelte and Vue have no browser-visible environment name from
+Fimo. Read `FIMO_ENV` at build time and pass the boolean into the bundle through
+the framework's own public-variable mechanism. Do not invent a `PUBLIC_FIMO_ENV`
+and do not expose the whole environment name when a boolean is enough.
+
+## Verify the installed integration
+
+Standalone tracking defaults to enabled. Supply an explicit production guard;
+`bl_preview_token` also suppresses sends. SSR and disabled calls are inert.
+Do not add browser secrets, project IDs or branch claims to payloads.
+
+Verify one initial POST, navigation, query-only changes, back/forward and a
+route revisit. Check duplicate mounts and cleanup. Existing visitor/session
+storage keys are retained; blocked storage uses per-document IDs. Delivery is
+best effort and has no retries. A 202 response alone does not prove persistence;
+check recorded analytics separately. Framework peer ranges are not proof that
+every older framework release was tested. Use the installed package's version
+qualification and preserve existing supported integrations when upgrading.

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

@@ -24,7 +24,7 @@ Before coding, understand the context and commit to a BOLD aesthetic direction:
 ## Frontend aesthetics guidelines
 
 - **Typography**: Choose fonts that are beautiful, unique, and interesting. Avoid generic fonts like Arial and Inter; opt for distinctive choices. Pair a distinctive display font with a refined body font. Limit to 2 font families total.
-- **Color & Theme**: Commit to a cohesive aesthetic. Dominant colors with sharp accents outperform timid, evenly-distributed palettes. Reserve high-saturation colors for small actionable elements (icons, charts, buttons). Maintain WCAG AA contrast (4.5:1 body, 3:1 large text). Write palette values into the shadcn CSS variables in `src/index.css` — see `references/ui.md` for the Tailwind integration.
+- **Color & Theme**: Commit to a cohesive aesthetic. Dominant colors with sharp accents outperform timid, evenly-distributed palettes. Reserve high-saturation colors for small actionable elements (icons, charts, buttons). Maintain WCAG AA contrast (4.5:1 body, 3:1 large text). Put palette values in the project's existing theme tokens instead of hard-coding colors in components.
 - **Motion**: Use animations for effects and micro-interactions. Prioritize CSS-only solutions; use Motion library for React when available. Focus on high-impact moments: one well-orchestrated page load with staggered reveals creates more delight than scattered micro-interactions. Use scroll-triggering and hover states that surprise.
 - **Spatial Composition**: Unexpected layouts. Asymmetry. Overlap. Diagonal flow. Grid-breaking elements. Generous negative space OR controlled density. Dramatic whitespace contrast: tight clusters + generous breathing room.
 - **Backgrounds & Visual Details**: Create atmosphere and depth rather than defaulting to solid colors — gradient meshes, noise textures, geometric patterns, layered transparencies, dramatic shadows, decorative borders, custom cursors, grain overlays.
@@ -101,13 +101,13 @@ Example: "**Linear meets Stripe** — polished SaaS with premium editorial touch
 ### Color & Theme
 
 - **Like:** Reference site(s) for color inspiration
-- **Background:** Primary background color (hex → `--background`)
-- **Foreground:** Primary text color (hex → `--foreground`)
-- **Accent:** Primary accent color (hex → `--primary`)
+- **Background:** Primary background color (hex)
+- **Foreground:** Primary text color (hex)
+- **Accent:** Primary accent color (hex)
 - **Secondary accents:** Additional colors if needed
 - **Dark mode:** Direction for dark mode palette (if applicable)
 
-Write into `src/index.css` as shadcn CSS variables, then use `bg-background` / `text-foreground` / `bg-primary` in components.
+Write these into the project's existing theme tokens and reference the tokens from components.
 
 ### Motion & Interaction
 
@@ -130,7 +130,7 @@ If the user hasn't supplied images and one is needed, run `fimo image generate -
 
 - **Like:** Reference site(s) for icon style
 - **Style:** Line icons, filled, duotone, custom
-- **Library:** Lucide (already in the template), Heroicons, custom, or none
+- **Library:** the icon set the project already uses, a custom set, or none
 - **Usage:** Sparse and meaningful vs. decorative
 
 ### Quality Bar

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

@@ -29,42 +29,42 @@ Use plain, friendly language. Describe what users see, where they click, and wha
 
 Read the relevant reference file when the user's question matches a topic.
 
-| Topic                    | Reference                               | When to read                                          |
-| ------------------------ | --------------------------------------- | ----------------------------------------------------- |
-| Command Palette          | references/command-palette.md           | "What can I open with Cmd+K?", "Quick actions"        |
-| Publish & Deploy         | references/publish-and-deploy.md        | "How do I publish?", "How do I make my site live?"    |
-| Custom Domains           | references/custom-domains.md            | "How do I use my own domain?", "DNS setup"            |
-| Content Management (CMS) | references/cms.md                       | "How does the CMS work?", "How do I add blog posts?"  |
-| Media Library            | references/media-library.md             | "How do I upload images?", "Where are my files?"      |
-| 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"              |
-| Preview & Responsive     | references/preview-and-responsive.md    | "How does it look on mobile?", "How do I test sizes?" |
-| Visual Editing           | references/visual-editing.md            | "Can I edit visually?", "How do I change colors?"     |
-| Version History          | references/version-history.md           | "How do I undo?", "How do I go back?"                 |
-| Sharing & Collaboration  | references/sharing-and-collaboration.md | "How do I share?", "How do I invite someone?"         |
-| Project Creation         | references/project-creation.md          | "How do I start a new project?"                       |
-| Billing & Credits        | references/billing-and-credits.md       | "What are credits?", "How do I upgrade?"              |
-| Drawing & Wireframing    | references/drawing-and-wireframing.md   | "How do I sketch my idea?"                            |
+| Topic                    | Reference                               | When to read                                                       |
+| ------------------------ | --------------------------------------- | ------------------------------------------------------------------ |
+| Command Palette          | references/command-palette.md           | "What can I open with Cmd+K?", "Quick actions"                     |
+| Publish & Deploy         | references/publish-and-deploy.md        | "How do I publish?", "How do I make my site live?"                 |
+| Analytics                | references/analytics.md                 | "Is tracking working?", "Why are analytics empty?"                 |
+| Custom Domains           | references/custom-domains.md            | "How do I use my own domain?", "DNS setup"                         |
+| Content Management (CMS) | references/cms.md                       | "How does the CMS work?", "How do I add blog posts?"               |
+| Media Library            | references/media-library.md             | "How do I upload images?", "Where are my files?"                   |
+| AI Chat                  | references/ai-chat.md                   | "What can the AI do?", "How do I give context?"                    |
+| 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"                           |
+| Preview & Responsive     | references/preview-and-responsive.md    | "How does it look on mobile?", "How do I test sizes?"              |
+| Visual Editing           | references/visual-editing.md            | "Can I edit visually?", "How do I change colors?"                  |
+| Version History          | references/version-history.md           | "How do I undo?", "How do I go back?"                              |
+| Sharing & Collaboration  | references/sharing-and-collaboration.md | "How do I share?", "How do I invite someone?"                      |
+| Project Creation         | references/project-creation.md          | "How do I start a new project?"                                    |
+| Billing & Credits        | references/billing-and-credits.md       | "What are credits?", "How do I upgrade?", "How do referrals work?" |
+| Drawing & Wireframing    | references/drawing-and-wireframing.md   | "How do I sketch my idea?"                                         |
 
 ## Cross-feature references
 
-| When user asks about... | Also mention...                                                                |
-| ----------------------- | ------------------------------------------------------------------------------ |
-| Publishing              | SEO settings, Custom domains                                                   |
-| Custom domains          | Publishing (must publish first), Billing (premium required)                    |
-| Adding images           | Media Library, AI Chat, Edit Mode                                              |
-| 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                                                       |
-| Working with others     | Sharing, Collaboration                                                         |
-| Starting a project      | Preview & Responsive, Publish & Deploy                                         |
-| Running out of credits  | Billing                                                                        |
+| When user asks about... | Also mention...                                                      |
+| ----------------------- | -------------------------------------------------------------------- |
+| Publishing              | SEO settings, Custom domains                                         |
+| Custom domains          | Publishing (must publish first), Billing (premium required)          |
+| Adding images           | Media Library, AI Chat, Edit Mode                                    |
+| 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 (CMS content), AI Chat (layout, styling, and code changes) |
+| Something went wrong    | Version History, AI Chat                                             |
+| Working with others     | Sharing, Collaboration                                               |
+| Starting a project      | Preview & Responsive, Publish & Deploy                               |
+| Running out of credits  | Billing                                                              |

package/assets/skills/fimo-studio/references/ai-chat.md

@@ -13,7 +13,7 @@ On desktop, the AI chat opens docked on the left by default. You can make it flo
 
 The AI can place choices, cards, tables, images, and contextual actions directly in its reply. Optional suggestions do not interrupt the conversation.
 
-When the AI needs an answer before it can continue, it pins a form directly above the message box and waits for your response. The form stays there while you scroll the conversation; the message that asked shows **Waiting for your answer...** in its place in the history. Select **Minimize** to fold the form to one line without losing your answers, then select that line to reopen it. **Submit** sends only the completed form and leaves anything typed in the message box unsent. Sending from the message box includes any selections already made in the form with your message; with no selections, it is an ordinary reply. A form with many steps scrolls inside its own area, and its **Next** / **Submit** buttons stay in view.
+When the AI needs an answer before it can continue, it pins a form directly above the message box and waits for your response. While the question is the last message, the form stays there as you scroll the conversation; the message that asked shows **Waiting for your answer...** in its place in the history. If you send a message that does not answer it, the question moves back to its place in the history, folded to one line with an orange **?**. Select it to open it there and answer it at any time, with an optional note from **Add a note**; the answer is sent as a new message at the end of the chat. An answered question shows a gray check next to its title. Select **Minimize** to fold the form to one line without losing your answers, then select that line to reopen it. **Submit** sends only the completed form and leaves anything typed in the message box unsent. Sending from the message box includes any selections already made in the form with your message; with no selections, it is an ordinary reply and the question stays open. A form with many steps scrolls inside its own area, and its **Next** / **Submit** buttons stay in view.
 
 ## Attaching Context
 
@@ -39,6 +39,14 @@ To halt the AI mid-generation, use the **Stop button** in the input bar — whil
 
 While the AI works, you see small badges in the chat showing what it is doing. Each badge displays a tool name and its current status. Examples include reading files, writing code, searching your project, or generating images. These badges help you follow along without needing to understand the technical details.
 
+## Reviewing Proposals
+
+Ask the AI to keep alternatives as named proposals. Open the Branch picker and choose one from **Proposals** to preview its work. Each proposal has its own changes. The picker follows visibility: internal work stays hidden even when saved, durable, or given more time. Extending retention does not show the work.
+
+A review request saves the selected session's current work and makes that same session visible and durable. Follow its review card to the proposal, or its Preview and Changes links from chat, Slack, or an agent report. These links open the current Branch in Studio and require project access. A review request refers to saved work: if that work changes, request a new review before merging. Exploring or merging proposal B keeps A, C, and D available unless you ask to discard them. Merging does not publish the site.
+
+Delete a proposal from the Branch picker when you no longer need it. Pull is unavailable for proposals; ask the AI to update the proposal instead. New Branch defaults to the proposal's upstream. Merge the proposal first if you want to create a Branch from its changes.
+
 ## Reviewing Changes That Could Not Merge
 
 Chat changes are prepared separately and then applied to the environment you are viewing. Most changes merge automatically.

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

@@ -0,0 +1,28 @@
+# Analytics
+
+Open **Analytics** in the project's workspace navigation. It may be inside
+**More** at narrower desktop widths. This workspace reports the published site,
+regardless of the editing branch currently selected.
+
+Publishing alone does not confirm pageview tracking. Before publication, the
+page offers setup guidance without an **Open site** link.
+
+For a published site:
+
+- **Waiting for the first pageview** means no pageviews are stored for it.
+  **Open site** lets the user visit the published address. **Set up tracking**
+  opens the installation guide. A visit must run a configured tracker to count.
+- **Pageviews received** shows the last pageview timestamp across available
+  history. Changing the chart's date range or device filter does not reset it.
+  Earlier traffic proves tracking worked then, not that a later deployment
+  still sends events.
+- **Tracking status unavailable** means the status could not be checked.
+  **Check again** retries it. Do not interpret this as an uninstalled tracker.
+  Charts that loaded successfully remain visible.
+
+Studio checks every 15 seconds while waiting in a visible tab. The first
+pageview refreshes the charts automatically. Processing may take longer than
+one check. Do not diagnose a missing tracker from zero chart counts alone.
+
+Users need analytics viewing permission. Date ranges and grouping apply to the
+charts; available history depends on the organization's analytics access.

package/assets/skills/fimo-studio/references/billing-and-credits.md

@@ -17,6 +17,16 @@ Look for the **coin icon with a number** near the chat send button. That number
 
 From a linked project directory, `fimo credits` shows the same organization balance in the CLI. Its "Available now" total already includes the visible buckets.
 
+## Referral progress
+
+Open **Earn free credits** from the project header (or the project menu on mobile), then use **Copy** inside the link field.
+
+- **Signed up** counts people who registered through your link, including those who later published. Link visits do not count.
+- **Published** counts people who published their first project, not the number of projects they publish.
+- **AI credits earned** shows inviter rewards already credited to you. It excludes your own bonus for joining through someone else's link; a publication can appear before its reward is credited.
+
+Each signup uses one of the five referral slots. Publishing unlocks the reward but does not reopen a slot. The dialog shows signups used and how many people have not published yet. **Terms and Conditions** opens the program terms; **Close** dismisses the dialog.
+
 ## Buying More Credits
 
 Buying credits is available while a paid plan is effective, including after scheduling its cancellation. Cancellation stops automatic spending immediately but keeps the current plan until renewal. A deliberate credit purchase still charges the payment method on file.

package/assets/skills/fimo-studio/references/command-palette.md

@@ -12,7 +12,7 @@ The palette includes the destinations you are allowed to use:
 - Individual page templates and forms
 - Agent runs, definitions, and individual agents
 - Project settings sections, individual schedules and webhooks, connections, and MCP servers
-- Asset folders and code files
+- Asset folders
 
 You can also open documentation, feedback, account actions, project history, invitations, and the Publish review flow. Use **Escape** to return from a searchable subpage to the main command list, then press it again to close the palette.
 
@@ -23,7 +23,6 @@ Studio adds commands that are relevant to the page you are viewing. Depending on
 - Refreshing Preview or opening it in a new tab
 - Creating a CMS entry or changing the content locale
 - Uploading an asset, creating a folder, or generating an image
-- Opening a code file or toggling the code sidebar
 - Running an agent, opening its Preview result, or resolving proposed changes
 - Editing or opening the current CMS page in Preview
 - Marking the current Inbox item read or unread, and archiving or restoring it

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

@@ -48,7 +48,6 @@ The preview is one of several workspaces, and only one is shown at a time. Switc
 - **Alt+1** -- Preview
 - **Alt+2** -- Content (CMS)
 - **Alt+3** -- Assets
-- **Alt+4** -- Code
 - **Alt+5** -- Settings
 
 When the Preview workspace is open, the visual editor can appear alongside it as a preview side panel.