fimo 2.8.0-staging.6 → 2.8.0-staging.8

package/README.md

@@ -35,11 +35,11 @@ npx fimo@latest init my-site
 cd my-site
 ```
 
-Every command runs the same way: **`npx fimo@latest <command>`**. `fimo init` sets up the project, pushes the first commit, and wires it to your Fimo account. Open it in your coding agent and start building.
+Every command runs the same way: **`npx fimo@latest <command>`**. `fimo init` sets up the site, pushes the first commit, and wires it to your Fimo account. Open it in your coding agent and start building.
 
 ## AI coding tools
 
-Fimo ships skills and rules for your AI coding tools (Claude Code, Cursor, Codex, Gemini, and more) so the agent knows how to work in a Fimo project. `fimo init` installs them for you — add or refresh them any time (`--mode=copy` is required under npx):
+Fimo ships skills and rules for your AI coding tools (Claude Code, Cursor, Codex, Gemini, and more) so the agent knows how to work in a Fimo site. `fimo init` installs them for you — add or refresh them any time (`--mode=copy` is required under npx):
 
 ```bash
 npx fimo@latest skills install --mode=copy
@@ -47,7 +47,7 @@ npx fimo@latest skills install --mode=copy
 
 ## Local development
 
-A Fimo project is a standard framework application. Run its normal package scripts:
+A Fimo site is a standard framework application. Run its normal package scripts:
 
 ```bash
 npm install

package/assets/skills/fimo/SKILL.md

@@ -1,10 +1,11 @@
 ---
 name: fimo
 description: >-
-  Working in or with a Fimo project (a content + media + forms + analytics
+  Working in or with a Fimo site (a content + media + forms + analytics
   platform for web applications). Load the current Fimo skills on demand through
   the `fimo` CLI before doing Fimo work — writing schema-driven
-  code, running CLI/deploy workflows, using the dashboard, or migrating a site.
+  code, planning, recommendations, design, copy, running CLI/deploy workflows,
+  using the dashboard, or migrating a site.
 ---
 
 # Fimo
@@ -27,10 +28,16 @@ Reference paths mentioned in streamed skill output, such as `references/media.md
 not files in the project. Load them through the CLI, for example
 `<fimo-cli> skills get fimo-cli --ref media`. Do not use a filesystem read tool for them.
 
+Before reasoning about an existing site's goals, recommendations, design, copy, content, or code,
+read its shared knowledge with `<fimo-cli> knowledge get --project <id> --json` (omit `--project` in a
+linked checkout). Load the detailed rules with `<fimo-cli> skills get fimo-cli --ref knowledge`.
+Refresh when switching sites or starting a new task. Empty knowledge does not block work; never
+save inferred guidance automatically. Write only when explicitly asked and authorized.
+
 Pick by task:
 
 - Writing code — schemas/forms, generated clients, labels, framework adapters, rendering primitives → `fimo-code`
-- Project creation, local setup, cloning, and CLI workflows — init, push, deploy, sync, labels, domains, analytics → `fimo-cli`
+- Site creation, local setup, cloning, and CLI workflows — init, push, deploy, sync, labels, domains, analytics → `fimo-cli`
 - Fimo agents — create, configure, validate, deploy, run, or inspect them → `fimo-cli` (`references/agents.md`)
 - AI agent setup — connect Claude Code, Codex, Cursor, or another agent → `fimo-cli` (`references/agent-setup.md`)
 - Remote MCP integrations — add, inspect, search, or run an MCP server → `fimo-cli` (`references/mcp.md`)
@@ -38,7 +45,7 @@ Pick by task:
 - Migrating an existing site into Fimo → `fimo-migration`
 
 For project setup, load `fimo-cli` first. Its `references/init.md` decision tree distinguishes a new or empty
-project, an existing Fimo project, and an external migration; load `fimo-migration` for the last path.
+project, an existing Fimo site, and an external migration; load `fimo-migration` for the last path.
 
 If a confirmed Fimo platform failure or missing capability materially blocks the task, finish or safely preserve the main work first, then use the built-in `supportReport` tool. Load the `fimo-cli` support instructions for the reporting criteria.
 

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

@@ -1,7 +1,7 @@
 ---
 name: fimo-cli
 description: >-
-  Use the `fimo` CLI to create or operate a Fimo project: content, forms,
+  Use the `fimo` CLI to create or operate a Fimo site: content, forms,
   media, labels/locales, deploys, Branches, Environments, domains, analytics,
   integrations, Fimo agents, collaboration, accounts, and credits. Also use
   for AI agent or MCP setup and confirmed Fimo platform blockers.
@@ -9,7 +9,7 @@ description: >-
 
 # Fimo CLI
 
-The `fimo` CLI is the workflow surface for Fimo. Fimo connects content, media, forms, analytics, editing, and hosting to web applications. The CLI handles project creation, content / forms / media / labels / locale workflows, deploys, collaboration, account management, Fimo agents, AI credit inspection, and AI agent setup.
+The `fimo` CLI is the workflow surface for Fimo. Fimo connects content, media, forms, analytics, editing, and hosting to web applications. The CLI handles site creation, content / forms / media / labels / locale workflows, deploys, collaboration, account management, Fimo agents, AI credit inspection, and AI agent setup.
 
 This skill describes **what the CLI does and the workflows it drives**. For the package surface used IN code (component props, generated hooks, JSON shapes, code-side rules), load the `fimo-code` skill on demand with `fimo skills get fimo-code`, using the invocation prefix below.
 
@@ -17,6 +17,13 @@ Use `fimo <command> --help` for full flag details on any command.
 
 > Verify a destination with `fimo webhooks test <id> --wait` and inspect its delivery history before depending on it in production.
 
+## 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.
+
 ## Running the CLI
 
 Use **`npx fimo@latest`** by default. If the initiating prompt supplies another Fimo CLI selector, such as `npx fimo@staging` or `npx fimo@0.14.0`, preserve that selector for every Fimo command in the same flow. Do **not** install `fimo` globally.
@@ -40,11 +47,11 @@ Pretty output may hide URLs behind clickable labels. Agents should use `--json`
 
 ## Critical: `.fimo/project.json` is the project link
 
-A Fimo project is identified by `.fimo/project.json`, written by `fimo init`. This file connects the local directory to the remote Fimo project. **Never edit it manually.** Most CLI commands find it by walking up from the cwd.
+A Fimo site is identified by `.fimo/project.json`, written by `fimo init`. This file connects the local directory to the remote Fimo site. **Never edit it manually.** Most CLI commands find it by walking up from the cwd.
 
 ## Critical: commands target the Branch matching the current git branch
 
-A project can have multiple **Branches** — each is a git branch _plus_ its own DB, sandbox, preview, and assets. Project-scoped commands (`deploy`, `status`, `entries`, `diff`, …) operate on the Branch matching the **current git branch**, and print a one-line banner saying which one. Analytics reads are the exception: they default to canonical `prod`, independent of the checkout; see `references/analytics.md`. Annotation writes keep the current or explicit Branch. New projects start on `main`. Override for a single command with the canonical `--branch <name>` flag; the removed `--env <name>` spelling is rejected. Never edit the link file to switch. The full git-shaped workflow (`branch` / `checkout` / `switch` / `pull` / `diff` / `merge` / `status` / `publish`) lives in `references/branches.md`.
+A project can have multiple **Branches** — each is a git branch _plus_ its own DB, sandbox, preview, and assets. Site-scoped commands (`deploy`, `status`, `entries`, `diff`, …) operate on the Branch matching the **current git branch**, and print a one-line banner saying which one. Analytics reads are the exception: they default to canonical `prod`, independent of the checkout; see `references/analytics.md`. Annotation writes keep the current or explicit Branch. New sites start on `main`. Override for a single command with the canonical `--branch <name>` flag; the removed `--env <name>` spelling is rejected. Never edit the link file to switch. The full git-shaped workflow (`branch` / `checkout` / `switch` / `pull` / `diff` / `merge` / `status` / `publish`) lives in `references/branches.md`.
 
 ## Quick Start
 
@@ -64,7 +71,7 @@ fimo deploy                                    # ON-DEMAND: hosted project previ
 fimo deploy --publish                          # ON-DEMAND: publish live (only when the developer says "ship it")
 ```
 
-New projects use the Next.js App Router template by default. Fimo's canonical React Router template is selected explicitly with `--framework react-router`; use `--framework vite` for a React SPA.
+New sites use the Next.js App Router template by default. Fimo's canonical React Router template is selected explicitly with `--framework react-router`; use `--framework vite` for a React SPA.
 
 The working loop is local: run the app with the project's package-manager `dev` script (`pnpm dev` / `npm run dev` / `yarn dev` / `bun dev` — match the lockfile), ask the developer what they want, edit, and iterate against the live localhost server. Outside the first-time onboarding rule below, `fimo deploy` is **not** a required final step — reach for it only when the developer wants a hosted project preview or to go live, and only on their signal (see `references/deploy.md`).
 
@@ -78,7 +85,7 @@ Keep `fimo validate --json` at the front of the project's `build` script, which
 
 Load the matching reference when the user's request fires its trigger. Recipes that involve writing code also need the `fimo-code` skill's package references — they're called out where relevant.
 
-- "Create a new Fimo project / scaffold a site / start a new website / link an existing project locally" → `references/init.md`
+- "Create a new Fimo site / scaffold a site / start a new website / link an existing project locally" → `references/init.md`
 - "Add a content type / blog / products / content schemas / CMS" → `references/content.md` (workflow) **+ run `fimo skills get fimo-code --ref content/schema` and load the detected framework reference**
 - "Declare Pages routes / configure Pages sources or route params / control what Studio shows for a route" → `references/pages.md`
 - "Add a contact / signup / feedback / newsletter form" → `references/forms.md` (workflow) **+ run `fimo skills get fimo-code --ref forms` for the JSON spec and generated client**
@@ -122,7 +129,7 @@ Load the matching reference when the user's request fires its trigger. Recipes t
 These fire at specific moments in the project lifecycle. **Surface them proactively** rather than waiting for the user to ask:
 
 - **Right after `fimo init`** → `cd` into the new directory, read the project's `AGENTS.md` (or `CLAUDE.md` for Claude Code), run `fimo describe --json`, then load `fimo-code` and only the task/framework references it routes to. The rules file came into existence mid-session and may not be auto-loaded by the harness. See `references/init.md` § Load the project context.
-- **When `fimo init` created or scaffolded a new project (create-new path, including a Studio-supplied `--project-id`)** → after init and context loading succeed, run the single first-preview deploy and return the preview and dashboard links — see `references/init.md` § Create the first hosted preview. That deploy is also the sandbox warm-up; never run a separate warm-up deploy. Skip it only if the user explicitly said not to deploy. Linking a project with existing code and migrations keep their own approval rules.
+- **When `fimo init` created or scaffolded a new site (create-new path, including a Studio-supplied `--project-id`)** → after init and context loading succeed, run the single first-preview deploy and return the preview and dashboard links — see `references/init.md` § Create the first hosted preview. That deploy is also the sandbox warm-up; never run a separate warm-up deploy. Skip it only if the user explicitly said not to deploy. Linking a project with existing code and migrations keep their own approval rules.
 - **Right after `fimo init`** → suggest `fimo rename "<Display Name>"` to set a human-readable name (the default post-init name is an auto-generated slug). Infer the name from what the user is building (e.g. "Acme Coffee" for a café, "Jane Doe Portfolio" for a personal site). See `references/init.md`.
 - **Right after `fimo init`** → start the app locally with the project's package-manager `dev` script (`pnpm dev` / `npm run dev` / `yarn dev` / `bun dev`) in the background. This localhost server with live reload is your iteration loop — edit, show, repeat. No deploy is needed to see local changes. If the initiating request did not say what to build, ask the developer — after the first preview on the create-new path, never as a blocker before initializing.
 - **When a user-visible unit of work looks done outside first-time onboarding** → **offer** to deploy (`fimo deploy` for a hosted project preview, `fimo deploy --publish` to go live) and run it only after the developer confirms — or immediately if they ask. Never deploy ordinary edits on your own. See `references/deploy.md`.
@@ -138,7 +145,7 @@ These fire at specific moments in the project lifecycle. **Surface them proactiv
 
 ## Anti-Patterns
 
-- **Editing `.fimo/project.json`** — read-only; it's the link between local and remote project. Treat as a generated file.
+- **Editing `.fimo/project.json`** — read-only; it's the link between local and remote site. Treat as a generated file.
 - **Treating `fimo deploy` as the working loop or a required final step** — the loop is local (`pnpm dev` etc.). Deploy commits + pushes + round-trips the sandbox; it's for hosted previews / going live, on-demand. Iterate locally and deploy at logical breakpoints. See `references/deploy.md`.
 - **Deploying without the developer asking or confirming** — new-project onboarding authorizes exactly one automatic first preview deploy (unless the user said not to deploy); every other deploy is offer-then-confirm. Don't auto-deploy after finishing an ordinary edit.
 - **Running `fimo deploy` just to get the current preview URL** — that's a commit + push + sandbox sync when only destination resolution is needed. Use `fimo preview url` instead. See `references/preview.md`.

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

@@ -38,10 +38,10 @@ fimo agents secrets remove <name> <KEY> [-C <dir>]
 ```
 
 - **`list-templates`** — list the bundled starter templates with the first line of each template's `GOAL.md` as a summary. Ships with the CLI binary; no API call. The five bundled templates are `_default`, `seo-audit`, `content-translator`, `broken-link-sweeper`, `post-deploy-check`.
-- **`create <name>`** — scaffold `.fimo/agents/<name>/` from a template (default `_default`, a minimal valid bundle with a manual trigger). `--description <text>` writes a one-line tagline into the scaffolded `config.yaml` (surfaces in the dashboard's agents list). When run **without** `-C`, it requires the cwd to be inside a real Fimo project (walks up for `.fimo/project.json` or legacy `.fimo.settings.json`) and errors out cleanly otherwise, so it never leaks an agent bundle into a stray cwd. If the template declares capabilities, an install-consent flow runs after the copy (`--quiet` skips it; critical caps still abort). Keep the scaffolded `runtime` block as is unless the author asks for a different credit limit; see the `runtime` reference below before adding any limit key.
+- **`create <name>`** — scaffold `.fimo/agents/<name>/` from a template (default `_default`, a minimal valid bundle with a manual trigger). `--description <text>` writes a one-line tagline into the scaffolded `config.yaml` (surfaces in the dashboard's agents list). When run **without** `-C`, it requires the cwd to be inside a real Fimo site (walks up for `.fimo/project.json` or legacy `.fimo.settings.json`) and errors out cleanly otherwise, so it never leaks an agent bundle into a stray cwd. If the template declares capabilities, an install-consent flow runs after the copy (`--quiet` skips it; critical caps still abort). Keep the scaffolded `runtime` block as is unless the author asks for a different credit limit; see the `runtime` reference below before adding any limit key.
 - Every generated `config.yaml` includes `model: openai/gpt-5.6-luna`. Change that top-level value to another supported Fimo text model when needed; bundles without `model` keep the Luna fallback. Deploy after changing it because cloud runs use the deployed bundle.
 - **`list`** — list the agents declared under `<project>/.fimo/agents/` (or legacy root `agents/`), with each one's trigger types and capability count. Local — the bundle list is the source of truth even if the project isn't linked yet.
-- **`validate [name]`** — run the full validation pipeline: parse → capability vocabulary → composition (cycle / missing sub-agents / invalid grants) → semantic + Fimo project config policy checks. Omit `name` to validate every bundle. `--json` emits a structured `ValidationReport` for CI; exit code is non-zero on any failure.
+- **`validate [name]`** — run the full validation pipeline: parse → capability vocabulary → composition (cycle / missing sub-agents / invalid grants) → semantic + Fimo site config policy checks. Omit `name` to validate every bundle. `--json` emits a structured `ValidationReport` for CI; exit code is non-zero on any failure.
 - **`secrets add/remove/list`** — edit or inspect the agent's requested secret names in `.fimo/agents/<name>/config.yaml` (or legacy root). These commands do not create, rotate, or reveal secret values. Store values with `fimo secrets add`; run `fimo agents validate` to check that required requested secrets exist in the project. See `references/project-vars-and-secrets.md`.
 - **`integrations <name>`** — preview the agent's `integrations` allowlist from `.fimo/agents/<name>/config.yaml` (or legacy root) and, when linked, overlay project integration status. See `references/integrations.md`.
 
@@ -244,7 +244,7 @@ Fimo grants only the selected subset to the next invocation in that run thread.
 abilities, and capabilities the run already holds are refused before the question is stored. For durable access on
 ordinary future runs, add the capability to `capabilities.yaml`, validate, and deploy the bundle.
 
-Managed agents can list project agents and read their run history through baseline project access. This does not
+Managed agents can list project agents and read their run history through baseline site access. This does not
 require `fimo:agents:run`; that capability is only required to dispatch another agent.
 
 Studio chat and project-bound Slack turns receive `fimo:logs:read`. The default autonomous-agent template now declares

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

@@ -8,7 +8,7 @@ New standalone projects start with one Branch: `main`. Linking an unversioned fo
 
 ## The Branch model — how every command picks its target
 
-**This is the single most important concept: project-scoped commands target the Branch matching the _current git branch_.** When you're on git branch `feat/seo`, `fimo deploy`, `fimo status`, `fimo entries list`, etc. all operate on the `feat/seo` Branch's DB / sandbox / preview. The CLI prints a one-line stderr banner telling you which Branch it resolved.
+**This is the single most important concept: site-scoped commands target the Branch matching the _current git branch_.** When you're on git branch `feat/seo`, `fimo deploy`, `fimo status`, `fimo entries list`, etc. all operate on the `feat/seo` Branch's DB / sandbox / preview. The CLI prints a one-line stderr banner telling you which Branch it resolved.
 
 ```bash
 fimo --branch <name> <command>  # peek at another Branch for one command (does not switch)

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

@@ -1,6 +1,6 @@
 # Credits
 
-`fimo credits` is a read-only command for checking the AI credit balance of the organization that owns a Fimo project. It resolves the project from `.fimo/project.json` unless `--project <project-id>` is provided.
+`fimo credits` is a read-only command for checking the AI credit balance of the organization that owns a Fimo site. It resolves the project from `.fimo/project.json` unless `--project <project-id>` is provided.
 
 ```bash
 fimo credits
@@ -9,7 +9,7 @@ fimo credits --project <project-id>
 fimo credits -C ./path/to/project
 ```
 
-This command is **project-scoped but not Branch-scoped**. It does not depend on the current git branch or `--branch`, because credits belong to the project's organization, not to a Branch.
+This command is **site-scoped but not Branch-scoped**. It does not depend on the current git branch or `--branch`, because credits belong to the project's organization, not to a Branch.
 
 ## Pretty Output
 

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

@@ -4,7 +4,7 @@
 
 > **Local vs hosted.** The local dev server is localhost only. The Fimo **dashboard preview** and the authenticated **project-member preview URL** are served by the deployed sandbox — so if the developer wants to see the site in the dashboard or send another project member a link, that requires a `fimo deploy`.
 
-`fimo deploy` uses the current Branch. New projects start on `main`; `release/*` is read-only, and `--publish` only runs from the project's configured Production source Branch. See `references/branches.md` for the multi-Branch workflow.
+`fimo deploy` uses the current Branch. New sites start on `main`; `release/*` is read-only, and `--publish` only runs from the project's configured Production source Branch. See `references/branches.md` for the multi-Branch workflow.
 
 Before deploying, Fimo fast-forwards a clean checkout that is behind and stops on dirty-behind or diverged branches. This syncs the whole branch, including config commits from Studio or locale commands.
 

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

@@ -1,6 +1,6 @@
 # Describe — read-only snapshot of the current project
 
-`fimo describe` prints a structured snapshot of the Fimo project in the current working directory: project name + config version, detected framework, fimo package version, package manager, route / schema / locale counts, and a file tree.
+`fimo describe` prints a structured snapshot of the Fimo site in the current working directory: project name + config version, detected framework, fimo package version, package manager, route / schema / locale counts, and a file tree.
 
 It is **read-only**. Never writes, never hits the network. Safe to run any time.
 
@@ -76,4 +76,4 @@ The scoped view still emits the project-level metadata header (name, framework,
 
 - The JSON shape is stable; parse it rather than scraping the human output when you need a specific field.
 - `framework` is normally auto-detected. If it is `null`, inspect the project before choosing framework-specific guidance.
-- The command runs in any directory that contains `.fimo/project.json` or one of its ancestors. If you're not in a Fimo project, `describe` will run against whatever directory you point it at (it doesn't require Fimo credentials).
+- The command runs in any directory that contains `.fimo/project.json` or one of its ancestors. If you're not in a Fimo site, `describe` will run against whatever directory you point it at (it doesn't require Fimo credentials).

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

@@ -1,6 +1,6 @@
 # `fimo init`
 
-One-stop project setup: sign in, create a new Fimo project (or link an existing one), install dependencies, and optionally set up Fimo skills for your AI tools.
+One-stop project setup: sign in, create a new Fimo site (or link an existing one), install dependencies, and optionally set up Fimo skills for your AI tools.
 
 ## Command
 
@@ -11,7 +11,7 @@ fimo init [dir] [options]
 `fimo init` runs the full onboarding in one shot:
 
 1. **Signs in automatically** — if there's no session it opens the browser loopback login. In `--json` / non-TTY with no session it fails with `NOT_AUTHENTICATED` (run `fimo login` first).
-2. **Resolves the project** — with `--project-id <id>` it sets up the named Fimo project: a project with no code yet is scaffolded as a fresh site, while an existing repository is cloned. Without it, `init` creates a NEW project. An interactive TTY shows a "Create new / Link existing" picker; non-interactive shells default to create-new. New projects use the Next.js App Router by default; `--framework react-router`, `--framework vite`, `--framework astro`, and `--framework sveltekit` select the other minimal framework-native shells.
+2. **Resolves the project** — with `--project-id <id>` it sets up the named Fimo site: a project with no code yet is scaffolded as a fresh site, while an existing repository is cloned. Without it, `init` creates a NEW project. An interactive TTY shows a "Create new / Link existing" picker; non-interactive shells default to create-new. New sites use the Next.js App Router by default; `--framework react-router`, `--framework vite`, `--framework astro`, and `--framework sveltekit` select the other minimal framework-native shells.
 3. **Installs dependencies** — prompts for the package manager, or honor `--package-manager <pm>` / `--no-install`.
 4. **Optionally sets up Fimo skills** — confirm prompt, or `--skills` / `--no-skills`.
 
@@ -20,7 +20,7 @@ Generated pnpm projects pin `pnpm@10.26.0` and carry project-owned `pnpm-workspa
 | Flag                         | Required                      | Purpose                                                                                                                                                 |
 | ---------------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `[dir]` positional           | yes in non-TTY for create-new | Target directory (e.g. `my-site`)                                                                                                                       |
-| `--project-id <id>`          | no                            | Set up the named Fimo project: scaffold and push a fresh site when it has no code yet, otherwise clone it.                                              |
+| `--project-id <id>`          | no                            | Set up the named Fimo site: scaffold and push a fresh site when it has no code yet, otherwise clone it.                                                 |
 | `--org <id>`                 | no                            | Target organization **id** when creating (use the `ID` column from `fimo orgs list`, NOT the slug). Picker shown interactively if omitted and TTY.      |
 | `--branch <name>`            | no                            | Branch to check out when linking an existing project (defaults to `main`).                                                                              |
 | `--env <name>`               | no                            | Rejected as a Branch selector; use `--branch <name>`.                                                                                                   |
@@ -95,7 +95,7 @@ For `--agents`, pass the AI tool you're running in: `--agents=claude-code` for C
 
 ## Setting up a project by ID
 
-Pass `--project-id <id>` to set up a known Fimo project. If the project has no code yet — for example, one just created in Fimo Studio — `init` scaffolds a fresh site into it and pushes the initial commit: the same create-new path, linked to the existing ID. If the project already has code, `init` clones it into `[dir]`, like `fimo clone`. Use `--branch <name>` to check out a specific Branch (defaults to `main`). Without `--project-id`, `fimo init` creates a new project.
+Pass `--project-id <id>` to set up a known Fimo site. If the project has no code yet — for example, one just created in Fimo Studio — `init` scaffolds a fresh site into it and pushes the initial commit: the same create-new path, linked to the existing ID. If the project already has code, `init` clones it into `[dir]`, like `fimo clone`. Use `--branch <name>` to check out a specific Branch (defaults to `main`). Without `--project-id`, `fimo init` creates a new site.
 
 ## Linking an existing local application
 
@@ -110,7 +110,7 @@ fimo link <projectId> --relink
 `fimo init` (create-new path) scaffolds:
 
 - The selected project shell: Next.js App Router by default, React Router with `--framework react-router`, a native React SPA with `--framework vite`, Astro with `--framework astro`, or SvelteKit with `--framework sveltekit`
-- `.fimo/project.json` — links this directory to the remote project (read-only after creation)
+- `.fimo/project.json` — links this directory to the remote site (read-only after creation)
 - `.fimo/config.json` — project, optional Studio Pages route metadata, locale, SEO, and agent policy
 - `.fimo/agents/` — versioned agent bundles
 - `AGENTS.md` + `CLAUDE.md` — project rules (from the template) read by AGENTS.md-compatible tools and Claude Code. Both point the agent at `fimo skills get` to load the real skills on demand.
@@ -149,7 +149,7 @@ After `fimo init` completes, the project root has `AGENTS.md` (universal) and `C
 
 **These files came into existence mid-session, so they may not be auto-loaded by the harness.** Explicitly:
 
-1. `cd <project-dir>` — switch into the new project.
+1. `cd <project-dir>` — switch into the new site.
 2. `Read` the project rules file: `AGENTS.md` (or `CLAUDE.md` if you're Claude Code).
 3. Run `fimo describe --json` with the current invocation prefix and read the detected framework, schemas, locales, and tree.
 4. Load the code skill on demand with the same prefix: `fimo skills get fimo-code`.
@@ -159,7 +159,7 @@ Do not batch-load every reference. Progressive disclosure keeps unrelated framew
 
 ### Create the first hosted preview (create-new path)
 
-Whenever `fimo init` created or scaffolded a new project — including a Studio-supplied `--project-id`, since Studio creates the project before any code exists — finish onboarding with exactly one plain preview deploy after init and context loading succeed, unless the user explicitly said not to deploy:
+Whenever `fimo init` created or scaffolded a new site — including a Studio-supplied `--project-id`, since Studio creates the project before any code exists — finish onboarding with exactly one plain preview deploy after init and context loading succeed, unless the user explicitly said not to deploy:
 
 ```bash
 fimo deploy -m "chore: first preview" --json

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

@@ -1,8 +1,8 @@
 # Integrations
 
-Use integrations to enable external services for a Fimo project. Firecrawl and Fal are built into Fimo: Fimo owns the provider account and bills the project in Fimo credits, so they take no API key at all. Every other credential (MCP servers, OAuth workspaces) is stored encrypted by Fimo and never printed back to the CLI. Teammates and agents receive access to the integration, not the underlying token.
+Use integrations to enable external services for a Fimo site. Firecrawl and Fal are built into Fimo: Fimo owns the provider account and bills the project in Fimo credits, so they take no API key at all. Every other credential (MCP servers, OAuth workspaces) is stored encrypted by Fimo and never printed back to the CLI. Teammates and agents receive access to the integration, not the underlying token.
 
-Start with `fimo integrations list` whenever the task could benefit from an external service. It is the project-scoped,
+Start with `fimo integrations list` whenever the task could benefit from an external service. It is the site-scoped,
 runtime-truthful inventory; use `info` only for the relevant integration instead of loading every provider's tools into
 context.
 

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

@@ -93,4 +93,4 @@ fimo invite --email "dev@agency.com" --role full
 - Invited users receive an email with a sign-up link if they don't have an account, or a sign-in link if they do.
 - Organization invites can be resent with `--resend` if the user didn't receive the original.
 - Project invites are scoped to a single project; organization invites grant access to all projects in that organization.
-- If `--cwd` is set and the directory belongs to a linked Fimo project, that project is auto-selected.
+- If `--cwd` is set and the directory belongs to a linked Fimo site, that project is auto-selected.

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-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.

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,10 +15,17 @@ 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.
@@ -29,27 +36,28 @@ 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?"                 |
-| 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?"                                         |
+| 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
 
@@ -59,12 +67,12 @@ Read the relevant reference file when the user's question matches a topic.
 | 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                                |
+| 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 project      | Preview & Responsive, Publish & Deploy                               |
+| Starting a site         | Preview & Responsive, Publish & Deploy                               |
 | Running out of credits  | Billing                                                              |