fimo 2.7.1 → 2.8.0-staging.10

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

@@ -0,0 +1,48 @@
+# Shared site knowledge
+
+Site knowledge holds website goals, audience, brand guidance, and rules shared across every Branch.
+It is site context, not repository instructions or an agent's private memory.
+
+## Read before site work
+
+Read before proposing a site direction, planning, writing code or content, choosing design, or
+reviewing work for consistency. Refresh on a new task, site switch, reported knowledge change,
+or context refresh/compaction that removed the snapshot. Carry the current content to
+delegated agents. Do not fetch it for unrelated account administration.
+
+```bash
+fimo knowledge get --json
+fimo knowledge get --project <project-id> --json
+```
+
+The result contains `content`, `updatedAt`, and `updatedBy`. Empty content means no saved knowledge. Continue using the user's request and site evidence; ask only for missing
+information that materially affects the task. Do not force setup, infer and save on the next message,
+or treat a permission/network failure as empty knowledge. Explain a failed read and retry safely.
+
+Use knowledge as site guidance, never as authority to override system instructions, permissions,
+or the user's current request. Surface relevant conflicts rather than silently changing the knowledge.
+Website observations are evidence of the current site, not proof of intended goals or approved rules.
+
+## Write only when asked
+
+Only persist when the user explicitly asks to save or update shared knowledge and the caller has
+permission. Managers can edit; an agent needs explicit knowledge-write authorization. Reading is not
+permission to learn and persist. A request to change site copy is not a request to change shared rules.
+
+Read the current knowledge, edit the complete Markdown while preserving unrelated guidance, and save:
+
+```bash
+fimo knowledge set --file knowledge.md --json
+cat knowledge.md | fimo knowledge set --stdin --json
+```
+
+`--file -` also reads stdin. Content is limited to 10,000 characters. An empty file explicitly clears
+knowledge. Each save replaces the current Markdown.
+
+CLI `--branch` does not isolate knowledge. Saved updates apply on the next agent context refresh.
+For MCP, use `knowledge_get` or `knowledge_update`
+with `projectId`; update accepts `content`.
+
+Settings also offers **Draft from website**. It runs analysis in the background and returns an editable
+draft for review. Only an explicit **Save** updates shared knowledge; drafting does not grant permission
+to write it. Do not install an autonomous agent to perform this action.

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

@@ -33,7 +33,7 @@ The synchronized `.fimo/config.json` remains the application runtime's declarati
 - `defaultLocale` is the locale used by `fimo validate`, `fimo labels set` without `--locale`, and content commands without `--locale`. Change it with `fimo locales set-default`.
 - `locales` must include `defaultLocale`. Add and remove values with `fimo locales add` and `fimo locales remove`.
 - Locale tags should be structurally valid, for example `en`, `es`, `pt-BR`, or `zh-Hans`.
-- New projects do not need a global routing strategy. The route contract declares locale placement with `/:locale`; legacy `i18n.routing.strategy` values are read only for compatibility while migrating.
+- New sites do not need a global routing strategy. The route contract declares locale placement with `/:locale`; legacy `i18n.routing.strategy` values are read only for compatibility while migrating.
 - If multiple locales are configured, create or update labels and localized content for every configured locale. Create schemas with `i18n: { "enabled": false }` only once.
 
 Edit application-owned settings such as `routes` directly in `.fimo/config.json`. Locale membership and the default use the lifecycle commands above because they must update the selected Fimo Branch and local checkout together.

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

@@ -121,4 +121,4 @@ Remote connections support HTTPS Streamable HTTP servers with OAuth, no authenti
 private headers. Local stdio commands such as `npx`, arbitrary child processes, resources, and prompts are not supported.
 
 To connect ChatGPT, Claude, or another remote MCP client to Fimo itself, use Fimo's hosted Project MCP at
-`https://api.fimo.ai/api/mcp`. That is a separate direction from connecting a Fimo project to an external MCP server.
+`https://api.fimo.ai/api/mcp`. That is a separate direction from connecting a Fimo site to an external MCP server.

package/assets/skills/fimo-cli/references/project-vars-and-secrets.md

@@ -53,7 +53,7 @@ and the active git branch; hosted preview and production inject it directly.
 
 `fimo vars add`, `fimo vars update`, and `fimo vars pull` write public project variables to a managed block in `.env.local`.
 
-Local env files are ignored by git in Fimo projects. They are for local development only; deployment reads project variables from Fimo and injects them into the remote build.
+Local env files are ignored by git in Fimo sites. They are for local development only; deployment reads project variables from Fimo and injects them into the remote build.
 
 ## Agent Secrets
 

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

@@ -1,6 +1,6 @@
 # Managing projects
 
-Commands for listing projects across an org, cloning a remote project locally, and managing the lifecycle of a single project (delete, publish, unpublish, rename). Most lifecycle commands operate on the **current project** (read from `.fimo/project.json`, or the legacy `.fimo.settings.json`, in the cwd) by default; for `delete`, `publish`, and `unpublish` you can pass an explicit `[projectId]` to target another. (`rename` only edits the linked local project; see below.)
+Commands for listing projects across an org, cloning a remote site locally, and managing the lifecycle of a single project (delete, publish, unpublish, rename). Most lifecycle commands operate on the **current project** (read from `.fimo/project.json`, or the legacy `.fimo.settings.json`, in the cwd) by default; for `delete`, `publish`, and `unpublish` you can pass an explicit `[projectId]` to target another. (`rename` only edits the linked local project; see below.)
 
 ## The `fimo projects` namespace
 
@@ -16,8 +16,8 @@ fimo projects rename <name> [projectId] [-C <dir>]   # set seo.siteName in the l
 
 - **`list`** — projects you can see in the org. Live projects are marked.
 - **`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 removed `--env <name>` spelling is rejected as a Branch selector. The target directory defaults to the project display name/name, or pass `[dir]` explicitly.
-- **`delete`** — destructive; prompts unless `-y`. Removes the remote project.
+- **`clone`** — clone a remote Fimo site'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 site ID and fail fast instead of prompting. By default it clones `main`; pass `--branch <name>` to clone a specific Branch. The removed `--env <name>` spelling is rejected as a Branch selector. The target directory defaults to the project display name/name, or pass `[dir]` explicitly.
+- **`delete`** — destructive; prompts unless `-y`. Removes the remote site.
 - **`publish` / `unpublish`** — toggle the project's public visibility. `publish` flips the configured Production source state live (the same "go live" as `fimo deploy --publish`, minus the git push).
 - **`rename`** — edits only the linked local project's `seo.siteName`. It does not commit or deploy. 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). Later remote config commands may require reconciliation while the local config is dirty. Finish your local edits, then explicitly run `fimo deploy --no-wait` when ready for a quick sync.
 

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

@@ -33,7 +33,7 @@ fimo schedules delete <schedule>
 
 Scheduled commands run in the project's Branch runtime, not on the user's machine. Fimo prepares the Branch and executes the stored command from the project root.
 
-`--do` can be any command that works with schedule runtime permissions, such as `fimo validate`, `pnpm test`, or a project script. The runtime can edit project content and publish or unpublish the project, but it cannot manage project access, secrets, schedules, or other project-level settings.
+`--do` can be any command that works with schedule runtime permissions, such as `fimo validate`, `pnpm test`, or a project script. The runtime can edit project content and publish or unpublish the project, but it cannot manage site access, secrets, schedules, or other project-level settings.
 
 Runs use at-least-once delivery. If Fimo loses a completion response, the same run may execute again. Side-effecting commands should use `FIMO_SCHEDULE_RUN_ID` as their idempotency key.
 

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

@@ -1,6 +1,6 @@
 # Reporting a problem to Fimo
 
-`fimo support report` sends a project-scoped problem to Fimo support. It automatically includes the project, current Branch, and CLI version so support can start investigating without asking the user to repeat that context.
+`fimo support report` sends a site-scoped problem to Fimo support. It automatically includes the project, current Branch, and CLI version so support can start investigating without asking the user to repeat that context.
 
 ## When to prepare it
 

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

@@ -22,6 +22,15 @@ 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
+
+If the project declares `fimo-analytics`, the update keeps it aligned with the
+other Fimo packages. The update never adds a tracker: React Router projects that
+tracked through `FimoProviders` before 2.8.0 need `<Analytics />`, and other
+projects without `fimo-analytics` should add it to match new projects. For setup and
+verification, load `fimo skills get fimo-code --ref analytics`. 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

@@ -20,6 +20,13 @@ plain-JSON consumer such as Markdown, RSS, or JSON-LD, use the generated
 serializer and hydrate them in the client when the generated client requires
 it. Load the framework reference for the exact boundary.
 
+## Shared site knowledge
+
+Before site planning, recommendations, design, copy, content, or code work, read the site's
+knowledge: `fimo knowledge get --project <id> --json` (omit `--project` in a linked checkout).
+Use the selected CLI invocation. Load `fimo skills get fimo-cli --ref knowledge` for refresh,
+empty-state, and explicit-write rules. This prerequisite also applies when entering this skill directly.
+
 ## Orient before writing
 
 1. Run the project-installed `fimo describe --json` in a linked project and read `data.framework.slug`, schemas, locales, and tree. If the project is not linked yet, inspect `package.json` and the app directory instead.
@@ -76,6 +83,10 @@ 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 or debugging, read [references/analytics.md](references/analytics.md).
+
 ## 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,70 @@
+# Pageview tracking
+
+## Before adding tracking
+
+Inspect the installed packages and the built page first; never mount a second
+sender beside one the app already renders. Projects created from current
+templates already declare `fimo-analytics` and mount `<Analytics />` in the root. `fimo-react-router` before 2.8.0
+tracked from `FimoProviders`; from 2.8.0 it does not.
+
+Install `fimo-analytics`, preserving the project's chosen version or channel.
+Publish the code change before verifying live traffic.
+
+```sh
+pnpm add fimo-analytics
+```
+
+## Install and mount
+
+Mount the matching component once, with no props:
+
+| Framework    | Import                                              | Placement                                                                                                                |
+| ------------ | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| React Router | `{ Analytics }` from `fimo-analytics/react-router`  | Root route component beside `<Outlet />`, or inside the existing `<BrowserRouter>` / `<HashRouter>`                      |
+| Next.js      | `{ Analytics }` from `fimo-analytics/next`          | App Router: inside `<body>` in `app/layout.tsx`. Pages Router: beside `<Component {...pageProps} />` in `pages/_app.tsx` |
+| Astro        | default `Analytics` from `fimo-analytics/astro`     | Shared layout, no `client:*` directive                                                                                   |
+| SvelteKit    | default `Analytics` from `fimo-analytics/sveltekit` | Root `src/routes/+layout.svelte`                                                                                         |
+| React (Vite) | `{ Analytics }` from `fimo-analytics/react`         | Application root                                                                                                         |
+| Svelte       | default `Analytics` from `fimo-analytics/svelte`    | Root component                                                                                                           |
+| Vue          | `{ Analytics }` from `fimo-analytics/vue`           | Root component                                                                                                           |
+
+```tsx
+import { Analytics } from 'fimo-analytics/next';
+<Analytics />;
+```
+
+For Nuxt, mount nothing: add `'fimo-analytics/nuxt'` to `modules` in
+`nuxt.config.ts` and run `pnpm add -D @nuxt/kit`.
+
+The generic React, Svelte and Vue components observe browser history and do not
+resolve hash-router paths; use a framework adapter when one exists.
+
+For a plain HTML Vite site, copy `node_modules/fimo-analytics/dist/browser.js`
+to `public/fimo-analytics.js` and add this classic script to `index.html`:
+
+```html
+<script
+  defer
+  src="/fimo-analytics.js"
+  data-endpoint="%VITE_API_URL%/e/p"
+  data-enabled="%VITE_ENABLE_ANALYTICS%"
+></script>
+```
+
+## Hosting controls tracking
+
+Fimo hosting provides the destination and the switch while the site builds:
+on for published sites, off for previews. Without it, as in local development,
+tracking is off; `[fimo-analytics]` in the browser console, or in build logs for
+Astro and Nuxt, says why. Do not add an `endpoint`, an `enabled` guard, or a
+`NODE_ENV` check.
+
+## Verify and diagnose
+
+On the published site, check Network for one POST to `/e/p` on the initial load
+and on each pathname or query change, including back/forward and revisits.
+Hash-only changes do not send. Previews send nothing. If requests are missing,
+check that the deployed app mounts the component and read the `[fimo-analytics]`
+diagnostics. If requests arrive but counts stay at zero, use the `fimo-cli`
+analytics reference to check the branch, date range and device filter; headless
+browsers count as bots. A 202 response does not prove a stored row.

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-code/references/frameworks/vite-react.md

@@ -27,7 +27,7 @@ Import it from `fimo-react-router/vite` whenever the application renders through
 
 ## Application root
 
-`FimoProviders` needs a React Router context for Studio navigation and pageview tracking. Keep the application's existing router type:
+`FimoProviders` needs a React Router context for Studio navigation. Keep the application's existing router type. For pageview tracking, read `references/analytics.md`.
 
 ```tsx
 import { QueryClient, QueryClientProvider } from '@tanstack/react-query';

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

@@ -48,6 +48,13 @@ lookups, avoid duplicate or sequential reads, and prove edit freshness. Do not
 ask a generic optimization question or bundle a framework upgrade into the
 migration.
 
+## Shared site knowledge
+
+Before site planning, recommendations, design, copy, content, or code work, read the site's
+knowledge: `fimo knowledge get --project <id> --json` (omit `--project` in a linked checkout).
+Use the selected CLI invocation. Load `fimo skills get fimo-cli --ref knowledge` for refresh,
+empty-state, and explicit-write rules. This prerequisite also applies when entering this skill directly.
+
 ## Execution environment
 
 Run this skill from a coding-agent process that has direct access to the

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, agents, schedules and run history, outbound webhooks,
+  dashboard SEO/domain settings, site 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
@@ -15,56 +15,73 @@ description: >-
 
 # Fimo Studio
 
-Fimo Studio is the Fimo web app — the place where content editors and project owners manage their site without writing code. This skill guides users through Studio features with step-by-step walkthroughs.
+Fimo Studio is the Fimo web app — the place where content editors and site owners manage their site without writing code. This skill guides users through Studio features with step-by-step walkthroughs.
 
 For developer-side conventions (the `fimo` CLI, schemas, forms, code-side rules), see the `fimo` skill instead.
 
+## Shared site knowledge
+
+Before site planning, recommendations, design, copy, content, or code work, read the site's
+knowledge: `fimo knowledge get --project <id> --json` (omit `--project` in a linked checkout).
+Use the selected CLI invocation. Load `fimo skills get fimo-cli --ref knowledge` for refresh,
+empty-state, and explicit-write rules. This prerequisite also applies when entering this skill directly.
+
 ## Voice
 
 Use plain, friendly language. Describe what users see, where they click, and what happens next. Adapt depth to the user's level.
 
 **Always read the relevant reference file before describing any UI feature, button, or panel.** Do not rely on your own knowledge of the interface — it changes frequently. If you are about to mention where something is located or how to access a feature, read the reference first.
 
+## Studio layout
+
+- **Header (desktop):** the site menu (site name; History is here) and the Branch switcher, then the workspaces: Chats, Getting started, Preview, Content, Assets, Agents, Analytics, Settings. Only workspaces the user can access appear. Workspaces that do not fit move into **More**. On the right: Earn free credits, Invite, Clone, Publish, and Merge on a Branch.
+- **Phone:** bottom tabs for Chat, Preview, Agents and Settings. Invite, Earn free credits and Clone ("Work on this site locally") move into the site menu.
+- **Settings:** General, Domains, Knowledge, SEO and Languages are listed directly. Models, Environments, Secrets, Schedules, Webhooks and Connections are under **Advanced settings**.
+- **Shortcuts:** Alt+1 Preview, Alt+2 Content, Alt+3 Assets, Alt+5 Settings, Alt+E edit mode, Cmd/Ctrl+K command palette.
+
+When a reference says "open X", X can be inside **More** on a narrow window.
+
 ## Topic index
 
 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?"                        |
+| Site Knowledge           | references/knowledge.md                 | "Set brand guidance", "Website goals", "Draft knowledge from the site" |
+| 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?"                          |
+| Site Creation            | references/project-creation.md          | "How do I start a new site?"                                           |
+| 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                | Site secrets, Forms, Publishing, Agents                              |
+| Connections             | AI Chat, Agents, Site secrets                                        |
+| Agents                  | Connections, Site secrets, Branches                                  |
+| Schedules               | Site 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 site         | Preview & Responsive, Publish & Deploy                               |
+| Running out of credits  | Billing                                                              |

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

@@ -1,10 +1,10 @@
 # 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, resume, and delete them.
+Site agents are versioned bundles from the site's repository. Studio lets site members inspect their configuration and run history, while site managers can start, stop, resume, and delete them.
 
 ## Open an agent
 
-1. Open the project and choose **Agents**.
+1. Open the site and choose **Agents**.
 2. Select **Agents** again to see the available bundles.
 3. Choose an agent to open its **Runs** and **Settings** tabs.
 
@@ -20,11 +20,11 @@ Choose **Stop** to pause every future trigger and stop planned or running work.
 
 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.
+Only site managers see Run, Stop, and Resume. Other site members can still see schedule timing, status, settings, and run history.
 
 ## Delete an agent
 
-Project managers can open **Agent actions** beside Run/Stop, choose **Delete agent**, and confirm. Deletion stops planned or running work and commits removal of the agent bundle from `main`. Recorded runs remain in history. Remove the bundle from a local checkout before deploying again, or that deployment recreates the agent.
+Site managers can open **Agent actions** beside Run/Stop, choose **Delete agent**, and confirm. Deletion stops planned or running work and commits removal of the agent bundle from `main`. Recorded runs remain in history. Remove the bundle from a local checkout before deploying again, or that deployment recreates the agent.
 
 If a run cannot be stopped or `main` changes before deletion commits, the definition stays intact and the agent may remain paused. Reload and retry, or resume it if you want to keep it.
 

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

@@ -1,6 +1,18 @@
 ## Where to Find It
 
-On desktop, the AI chat opens docked on the left by default. You can make it floating or dock it on either side from the project menu's **Chat position** submenu (Floating / Left / Right). Toggle the chat open or closed by clicking the **chat (speech-bubble) icon** in the header, or press **Cmd+Shift+H** (Mac) / **Ctrl+Shift+H** (Windows/Linux).
+Open the **Chats** tab in the site header. On a phone, the Chat tab at the bottom opens the chat list first; select a chat to open it.
+
+## Working in Several Chats
+
+Chat has its own **Chats** tab in the site header; the tab shows how many chats have unread activity. A site can have several chats, shared by everyone on the site. The left list shows them most recently active first with a status (**Working** with a spinner while replying, **Done** once the reply finished) and their last words; a dot marks unread activity. Select **+** for a new chat (it joins the list when its first message is sent, and its name comes from that message; an empty chat offers starter requests), the search icon to find a chat, the filter icon to show only Working or Done chats, and the list settings for ordering and showing read, unread, or archived chats. The buttons above an open chat (or a right-click on a row) mark it unread, pin, archive, or mute it, for you only; the settings icon opens the chat's settings, which change its portrait (shape, eyes, mouth, color) and rename it for everyone, hold the same pin, mute and archive switches, and delete it, stopping a running reply first. Each chat has its own messages and context; when you refer to an earlier discussion, Chat searches the site's chats and answers with the messages it found. The open chat is in the page address (`/chats?chat=<id>`), so a link or reload opens the same chat.
+
+## Agents
+
+An agent is a chat with a job: a name and a description that Fimo reads at the start of every reply in that chat. Agents are shared like any chat and are listed as soon as they are created, with an **Agent** tag after the name. The **+** above the chat list is a menu: **New chat** (blank), **New agent** (a name and a description, then the empty agent opens), and under **Agents** Fimo's default agents (**SEO**, **Site health**, **Writer**, **Translator**); a new site starts with all four listed, their routines off until someone turns them on, and on an older site selecting a default creates the site's chat for it the first time, the same chat every time after. In an agent, the description shows next to its name in the header, the empty state introduces the agent by name and job, and the message box reads **Message <name>**. The agent's settings page has a **Description** field, shared with everyone; empty means none. The filter icon's **Kind** option shows only chats or only agents; search finds an agent by its name.
+
+### Routines
+
+A routine is saved instructions an agent runs in a thread of its own, by hand or on a schedule, so each run sees its earlier runs and the agent's chat never fills with its work. The agent's settings list its **Routines** as cards (name, cadence such as **Every Monday at 08:00** or **By hand**, next run, an **Active** switch) with a **New routine** button; the default agents come with theirs. A routine's page holds **Name**, **Instructions** (the task, run on every trigger), **Triggers** (**By hand** with **Run now**, which starts a run right away, or sends the routine a message as its next run; **Schedule**: none, every day, every week on a weekday, or every month on a day, at a time, in the timezone shown (a default agent's routines take the opener's browser timezone), at most every 15 minutes), the **Runs** list (newest first, two lines each: how it ended (**Quiet**, **Sent to agent**, **Asked for a decision**, or **Failed** and **Stopped** in red), when and what started it (**On schedule**, or **By hand** with the person's name or **agent** when their message started it), then the first sentence of what it told the agent; select one to open the routine's thread, read-only, at that run), the **Active** switch in the header (pauses the schedule only) and **Delete routine** (removes its thread too). Routines report to the agent, never to a person: a run that has something the agent should know writes it to the agent's chat as a message only the agent reads, and the agent takes a turn on it (reports waiting together are read in one turn); a run with nothing to say reports nothing. The agent decides what the team sees: nothing (the chat stays as it was, the row stays read), one short message (several reports folded into one), or a form when a person must decide, and the chat's row reads **Needs you** while that form is open. A person answers the form in the chat; the agent sends the decision to the routine with its `send_message` tool and the routine runs again with it. Only the agent answers a routine: its page has no answer box. Quiet runs leave no message: they fold into one line placed where the last run happened among the messages (**N runs since <date>**), counted from the last report the agent answered visibly, and the chat's row reads **Ran <date>** with that count while the newest thing in the chat is a run, the ordinary status and the last words when a message is newer, and **First check <day> <time>** or **No checks scheduled** before the first run. A routine whose runs keep failing or are refused for credits is reported to the agent once per streak, as a message from Fimo.
 
 ## Sending a Message
 
@@ -13,7 +25,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
 
@@ -37,13 +49,21 @@ To halt the AI mid-generation, use the **Stop button** in the input bar — whil
 
 ## Understanding Tool Badges
 
-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.
+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 site, 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 site 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.
 
-If the project changed in the same place while the AI was working, the response shows a **Review changes** card and an attention banner above the chat input. The banner remains visible when floating chat history is collapsed.
+If the site changed in the same place while the AI was working, the response shows a **Review changes** card and an attention banner above the chat input.
 
 Choose **Auto fix** or keep chatting to let Fimo continue in the retained proposal, resolve the conflict, and retry the merge. Choose **Review manually** to inspect and resolve the proposal yourself. Discarding leaves the current environment unchanged and permanently removes the proposal.
 

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

@@ -0,0 +1,28 @@
+# Analytics
+
+Open **Analytics** in the site'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

@@ -15,7 +15,17 @@ Look for the **coin icon with a number** near the chat send button. That number
 - Click it to open a detailed breakdown showing how many credits you have in each category.
 - When your balance is low, opening that breakdown shows an alert-triangle warning ("No credits left" or "_N_ credits left") at the bottom.
 
-From a linked project directory, `fimo credits` shows the same organization balance in the CLI. Its "Available now" total already includes the visible buckets.
+From a linked site 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 site header (or the site 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 site, not the number of sites 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
 
@@ -29,7 +39,7 @@ Buying credits is available while a paid plan is effective, including after sche
 
 ## Refilling Credits Automatically
 
-Organization billing admins on a paid plan can configure auto-refill from **Settings > Billing**:
+Organization billing admins on a paid plan can configure auto-refill from the organization's **Billing & usage** page:
 
 1. Choose the balance threshold that should trigger a refill.
 2. Choose the dollar amount to purchase when the balance crosses that threshold.
@@ -42,7 +52,7 @@ Turn auto-refill off from the same control. Leaving a paid plan locks automatic-
 You can upgrade from two places:
 
 - Click **Upgrade** in the credit dropdown.
-- Or go to your organization settings, then the **Billing** tab.
+- Or open **Billing & usage** in your organization.
 
 From there:
 

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

@@ -13,7 +13,7 @@ Pages is still a pre-release Studio surface. It is visible in development and st
 
 ## Browsing Your Content
 
-1. Click the **Content tab** (the database icon) in the top navigation bar.
+1. Open **Content** (the database icon).
 2. Choose **Pages**, **Collections**, or **Singles** in the left sidebar. **Forms** and **Labels & Text** follow them in the same list.
 3. Hover over or focus the info icon beside any item for a short explanation.
 4. Pages shows the site's route tree. Collections and Singles show cards for the schemas in that group.
@@ -55,7 +55,7 @@ When you open a Collection, the entry list provides several tools:
 
 ## Completing Missing Translations
 
-Localized Collections show only entries for the locale selected beside the Collection name. When that locale is missing translations that exist in the project's default locale:
+Localized Collections show only entries for the locale selected beside the Collection name. When that locale is missing translations that exist in the site's default locale:
 
 1. Click the amber **N missing** warning beside the locale selector.
 2. Review the source and target languages in the popover.