@foldspace_npm/harness 0.1.26 → 0.1.28

package/CLAUDE.md

@@ -4,23 +4,24 @@ You are adding an AI agent to a product that already exists. It answers
 questions and *does things* inside that product, with the user's own session.
 
 The person you are working with may not be a developer. **You run the
-commands; they sign in and talk to the agent.** Their first session ends at
-something they can **see on their own page** — not at "it builds".
+commands; they sign in, talk to the agent, and say yes or no.** Their first
+session ends at something they can **see on their own page** - not at
+"it builds".
 
 ## Every session starts the same way
 
 1. **Harness version.** Run `npx foldspace help --json` (from an older install,
    `npx --yes @foldspace_npm/harness@latest upgrade --check`). If
-   `update.outdated` is true, say the pinned and latest versions and **ask
-   before upgrading**; then `foldspace upgrade --yes` and `npm run build`. Never
-   upgrade as a side effect of build, attach or implementing an action.
-   `build` and `attach` check too: behind prints one line and carries on; a
-   version Foldspace **withdrew** refuses to run and says why. Tell the user
-   the reason and ask to upgrade. Only if they decide not to, rerun with
-   `FOLDSPACE_SKIP_UPDATE_CHECK=1` - never set it on your own. If the
-   project `CLAUDE.md` does not contain
+   `update.outdated` is true, say which version the project is on and which is
+   newest, and **ask before upgrading**; then `npx foldspace upgrade --yes` and
+   `npm run build`. Never upgrade as a side effect of build, attach or
+   implementing an action. `build` and `attach` check too: on an older version
+   they print one line and carry on; on a version Foldspace **withdrew** they
+   refuse to run and say why. Tell the human the reason and ask to upgrade.
+   Only if they decide not to, rerun with `FOLDSPACE_SKIP_UPDATE_CHECK=1` -
+   never set it on your own. If the project `CLAUDE.md` does not contain
    `@node_modules/@foldspace_npm/harness/CLAUDE.md`, ask before
-   `foldspace upgrade --refresh-instructions`.
+   `npx foldspace upgrade --refresh-instructions`.
 2. **Is Foldspace connected? Check — never assume.** `region` in
    `foldspace.dev.json` (absent means `us`) picks the server: `foldspace`, or
    `foldspace-eu` for `eu`. Use that server's tools all session. Call its
@@ -28,8 +29,8 @@ something they can **see on their own page** — not at "it builds".
 
    | Result | Do |
    |---|---|
-   | The tool does not exist | The Foldspace MCP is not installed in this editor. Give the one install step for *this* region and editor — **EU**, any editor: the MCP block on <https://foldspace.ai/eu/agents.md>, never the plugin. **US** — Claude Code: `claude plugin install foldspace-agent-builder@foldspace-plugins`; anything else: the MCP block on <https://foldspace.ai/agents.md>. Then check again |
-   | It exists but fails on auth | Installed, not signed in. Only the human can approve sign-in. Tell them exactly where — Claude Code: `/mcp` → **foldspace-eu** (**EU**) or **foldspace** (**US**) → finish in the browser — then check again |
+   | The tool does not exist | The Foldspace MCP is not installed in this editor. Install it yourself, the one way that fits *this* region and editor. **EU** - any editor: the MCP block on <https://foldspace.ai/eu/agents.md>, never the plugin. **US** - Claude Code with git on the machine (`command -v git`): `claude plugin marketplace add https://github.com/foldspace-ai/plugins` (already added, or added from another source, is fine), then `claude plugin install foldspace-agent-builder@foldspace-plugins`; without git, or any other editor: the MCP block on <https://foldspace.ai/agents.md>. Either way it needs sign-in: start it before your turn ends, as **Connect Foldspace tools** on that page says. **The plugin** loads when your turn ends: call `list_agents` again on the human's next message. **A server added from the MCP block** (`claude mcp add`) never reaches a chat that is already running - not on the next message, not through `/mcp`: once it is signed in, the human opens a new chat in this folder and repeats their request. `claude mcp get` saying Connected proves only the setting; the check is `list_agents` in the chat you are in |
+   | It exists but fails on auth | Installed, not signed in. Only the human can approve sign-in. Tell them exactly where - Claude Code: `/mcp` → **foldspace-eu** (**EU**) or **foldspace** (**US**; listed as `plugin:foldspace-agent-builder:foldspace` when the plugin installed it) → finish in the browser - then check again. If `/mcp` does not list that server, it was added after this chat started: the human opens a new chat in this folder, as above |
    | It returns agents | One agent: state its name, Agent Key and product in a line and carry on; the human objects if it is wrong. Several: ask which, as a choice |
 
 3. **Orient** — `get_agent_settings`, `list_actions`, `list_task_agents`,
@@ -38,6 +39,39 @@ something they can **see on their own page** — not at "it builds".
    seeded at sign-up are often a specification someone already wrote.
 4. **Read `docs/app-profile.md`.** It is what is already known about this app,
    with how each fact was established.
+5. **Does the agent already have code saved in Foldspace?** If your Foldspace
+   tools include `repo_read`, call it with command `status` now - before the
+   first build, because the first build is what the test window shows them.
+   - **A code project.** Call `repo_read` with command `instructions` and
+     follow what it returns. The project's `agent/` is the copy Foldspace
+     builds and publishes, and it may hold work someone else saved. Before you
+     build, replace this folder's `agent/` with it (`repo_read` commands `tree`
+     and `file`): delete what is there rather than copying over the top, or
+     their page shows the template instead of their agent. An action file here
+     that the project lacks is work a session never saved: keep it aside and
+     put it back after.
+   - **`NO_REPO`.** Nothing is saved yet. Follow the next step `status` gives:
+     it creates the code project in about a minute and changes nothing anyone
+     sees - say you are setting up their project, no need to ask. Get the agent
+     live in this folder meanwhile (L0 needs no code). Once `status` shows the
+     project, replace this folder's `agent/` with its `agent/` as above, before
+     you write the first action.
+   - **A refusal that names `foldspace-ai-access`.** This agent has saved
+     code that Foldspace has not opened to these tools; that is final. Tell
+     the human that Foldspace manages their agent's saved code, so this build
+     starts fresh.
+   - **A refusal that starts "Your Foldspace account cannot".** It is about
+     the signed-in account, so you cannot tell whether code is saved. Pass its
+     words on as they are - they are written for the human.
+   - **Anything else** - `status` says a project claims this agent but cannot
+     be used, or another error. Create none. Tell the human in your own words
+     that their agent's saved code cannot be used right now; never pass on the
+     text that came back - it can name things they cannot open.
+
+   After any of these three, build in this folder, never stop the session
+   over it, and tell the human once that the code stays on this computer.
+   - **No `repo_read` tool.** This folder is the only copy, so there is no code
+     project.
 
 Before an unfamiliar harness operation, `npx foldspace help --json` is the
 current CLI contract — risk, prerequisites, effects, next step.
@@ -47,14 +81,15 @@ current CLI contract — risk, prerequisites, effects, next step.
 | Level | Reached when |
 |---|---|
 | **L0 · agent live** | injected, visible on the page |
-| **L1 · read settings** | the user's own account, plan or settings in a widget, showing their real values |
+| **L1 · read settings** | the user's own account, plan or settings on a card, showing their real values |
 | **L2 · look up entities** | a search from the user's own words, showing rows |
 
-1. **Get the agent live first (L0) - with no actions.** Straight after
-   orienting: `npm run build`, `npm run inject`, and one ask - *"A Chrome
-   window opened at <Product>'s login. Please log in there - I'll notice when
-   you're in."* Then `npx foldspace observe wait-login`: it returns the moment
-   they are in, so nobody has to type "I've logged in". Then
+1. **Get the agent live first (L0) - with no actions.** Straight after the
+   steps above (with a code project, once its `agent/` is in place - step 5):
+   `npm run build`, `npm run inject`, and one ask - *"A Chrome window opened at
+   <Product>'s login. Please log in there - I'll notice when you're in."* Then
+   `npx foldspace observe wait-login`: it returns the moment they are in, so
+   nobody has to type "I've logged in". Then
    `npx foldspace attach --daemon` - and if it answers that the page has no
    Foldspace code, `npx foldspace attach --bootstrap --daemon` (an app that
    never had Foldspace). An empty registry is valid. L0 is
@@ -69,33 +104,37 @@ current CLI contract — risk, prerequisites, effects, next step.
 2. **Then offer experiences - from what you already have.** With the agent on
    their screen, offer three or four read-only experiences as a choice,
    recommended first. Sources: the product's own menu (`npx foldspace observe
-   menu` takes a second and moves nothing), the conversation starters seeded at sign-up,
-   `discover_actions`, and `docs/app-profile.md`. `discover_actions` gives
-   candidates, not an inventory. Do not investigate the app to build this
+   menu` takes a second and moves nothing), the conversation starters seeded
+   at sign-up, `discover_actions`, and `docs/app-profile.md`. `discover_actions`
+   gives candidates, not an inventory. Do not investigate the app to build this
    list. Order them cheapest first: the user's own data with no parameter
    (L1) before a search with one parameter (L2).
 3. **Only then observe - and only what the chosen experience needs** (**Find
    the call yourself**). Check the row count as part of that: an experience
    on a resource the account has zero of is a demo of an empty state, so say
-   so and offer the next one. On an empty account the useful first action is
-   one that creates data - say so instead.
-
-**Say when the test window is yours, and when it is theirs - on the page and
-in chat.** You and the human share one Chrome window. `observe` and `ask`
-raise the working pill by themselves for as long as they run, and drop it
-after. For the longer stretch - from the moment you start working on their
-window until it is their turn - run `npx foldspace badge working` (the pill at
-the foot of the window says Foldspace is building here, leave it alone) and say
-so in chat: *"I'm going to work in that Chrome window for a few minutes -
-please leave it alone until I tell you it's ready."* When it is their turn,
-`npx foldspace badge ready` takes the pill away (the small corner tag comes
-back) and in chat you say what to try. No bar for their turn: they may type
-whatever, whenever; the pill only ever asks them to wait. `foldspace badge label` puts the small
-corner tag back; `off` removes it, for a screenshot they will share.
-
-**After they have tried it, offer the second wave - one choice, recommended
-first, not four questions.** Once you have handed over (`badge ready`) and the
-human has asked the agent the question:
+   so and offer the next one. When the account has nothing to read at all,
+   say so and offer a write first: a card that creates a record and writes
+   only when the user approves it (`recipes/create-a-record`).
+
+**Say when the test window is yours, and when it is theirs - on the page and in
+chat.** You and the human share one Chrome window. `ask` and `observe` (except
+`screenshot`, `pages` and `wait-login`) raise the working pill by themselves for
+as long as they run, and drop it after. For the longer stretch - from the moment
+you start working on their window until it is their turn - run
+`npx foldspace badge working` (the pill at the foot of the window says Foldspace
+is building here, leave it alone) and say so in chat: *"I'm going to work in
+that Chrome window for a few minutes - please leave it alone until I tell you
+it's ready."* When it is their turn, `npx foldspace badge ready` takes the pill
+away (the small corner tag comes back) and in chat you say what to try. Nothing
+marks their turn: they may type whatever, whenever; the pill only ever asks them
+to wait. `npx foldspace badge label` puts the small corner tag back;
+`npx foldspace badge off` removes it, for a screenshot they will share.
+
+**After they have tried it, the second wave: tell Foldspace who the user is
+(item 3 - no question, one line in chat), and offer the rest as one choice,
+recommended first.** Once you have handed over (`badge ready`), the human has
+asked the agent the question and - with a code project - you have taken the
+steps in **Done, and what you say at the end**:
 
 1. **Starters.** The sign-up starters point at actions the agent does not have
    (clicking one answers "that action isn't available"): replace them with the
@@ -106,52 +145,70 @@ human has asked the agent the question:
    project's start-up code; nothing in their source changes.
 3. **Tell Foldspace who the user is** - `recipes/who-is-the-user`: from then on
    their conversations and analytics stop being anonymous, and the agent has
-   real-time context about who it is talking to. One line in chat, no question.
-4. **A second experience** - and, once a card shows records, navigation to a
-   record's page.
+   real-time context about who it is talking to.
+4. **A second experience** - a read, or a write through
+   `recipes/create-a-record` - and, once a card shows records, navigation to
+   a record's page.
+5. **No emoji in any of the agent's replies** - one line in the agent's
+   Behavior instructions (Agent Studio → **Style & Behavior** → **Behavior &
+   Responses**). No Foldspace tool writes those, so it is theirs to add: on a
+   yes, give them the line to paste and where it goes.
 
 Not before the first experience: nothing about it needs any of these, and it
 is silent work before the human has seen anything.
 
-Uploads, extraction and anything that writes are a later session.
+Uploads and extraction are a later session.
 
 ### Ask as a choice, and ask almost nothing
 
 Every question to the human is an **enumerated choice with the recommended
-option first** (in Claude Code, `AskUserQuestion`). A first session has four
-decision points: which agent (only if several), the app's hostname, which
-experience first, and whether to publish. The hostname is the only free-text
-question. Everything else — attach mode, folder, name, level — you **state and
-move on**.
-
-Then agree the experience in the customer's words, before creating anything:
+option first** (in Claude Code, `AskUserQuestion`). A first session asks only
+this: which agent (only if several), the app's hostname, which experience
+first - and a yes wherever this manual asks for one, such as agreeing the
+experience (below), upgrading, publishing an action, task agent or
+navigation, publishing their code for their users, replacing their starters or
+adding hosts. The hostname is the only free-text question. Everything else -
+attach mode, folder, name, level - you **state and move on**.
+
+Then agree the experience in the human's words, before creating anything:
 *"Show my plan and credits needs one new action on your agent and one card to
 show it in. Sound right?"*
 
 ## One product, several hosts
 
-Many products live on more than one host - `www.`, `analyze.`, `admin.` under
-one domain. `init` covers only the host it was given, so on the others the
-agent does not appear and every command refuses the window.
+Many products live on more than one host - `www.`, `app.`, `reports.`,
+`admin.` under one domain. `init` covers the host it was given and that
+host's subdomains, so on sibling hosts the agent does not appear and every
+command refuses the window.
 
 - **Find out at the start.** Straight after the agent is live, `npx foldspace
   observe menu` lists the hosts the page links to that belong to the same
   product and that this project does not cover (`otherHosts`). `observe pages`
   and the attach log say the same when the window lands on one.
 - **Widening is the human's yes.** Name the hosts you found and ask once:
-  *"Your product also lives on analyze.… and communicate.…. Add them so the
-  agent works there too?"* Then add the one pattern (`"*.example.com"`) to
-  `hosts` in `foldspace.dev.json`, `npm run inject`, and attach again.
+  *"Your product also lives on reports.… and admin.…. Add them so the agent
+  works there too?"* Then add the one pattern (`"*.example.com"`) to
+  `hosts` in `foldspace.dev.json`, then `npx foldspace attach --stop`,
+  `npm run inject`, and attach again with the same flags (**Local loop**).
 - **Then go there yourself.** `npx foldspace observe screen --goto
-  https://analyze.example.com/reports` opens a screen on any host the project
+  https://reports.example.com/` opens a screen on any host the project
   names. Do not ask the human to click a tile you can open.
-- **An action reads only the host it runs on** - that is the browser. Build
-  each experience on the host its data lives on, and use
+- **An action reads only what the page it runs on may read** - that is the
+  browser: another host's signed-in data is refused unless that host allows
+  this one. Build each experience on the host its data lives on, and use
   `recipes/several-hosts`: an action asked from the wrong host answers
   `wrong_page` instead of failing.
-- **The user and their conversations carry across hosts; the agent carrying
-  on after it navigated does not** (PLG-5962). `recipes/several-hosts` has the
-  workaround. It is a workaround: register it (**Rules**, 9).
+- **The user, their conversations and the agent's turn all carry across
+  hosts.** The SDK keeps its resume note for 60 seconds in a cookie on the
+  domain the hosts share (`example.com`), so an agent that moved the user to
+  another host in the same tab carries on there. Only the navigation's own
+  result goes with it: another action that ran in the same turn reaches the
+  agent as "not available". Build nothing for the hand-over:
+  `recipes/several-hosts` is only for the wrong-host answer above. If the
+  project already has `installResumeAcrossHosts` (a row under
+  **Workarounds** in `docs/app-profile.md`), remove it as that recipe says:
+  with both, the user sees an extra message and the agent takes a second
+  turn.
 
 ## Find the call yourself
 
@@ -176,16 +233,16 @@ and asking are not the only options — **observing is, and it comes first**:
    npx foldspace observe screen --click "<a label from menu>" --match "<three to five words for the data>"
    npx foldspace observe read "<the GET path screen returned>"   # GET only: status, field names and types, row count
    npx foldspace observe auth                      # only if a read came back 401 or 403
-   npx foldspace observe styles                    # their font and colours, for the card
+   npx foldspace observe styles --write            # agent/views/brand.ts for the cards, before the first card
    ```
 
    `screen` reaches a screen the way a person does and returns at most eight
-   requests, ranked by your words - field names, value types and row counts,
-   **never values**. `read` confirms the one you picked. `auth` reports *where*
-   each header value comes from, never the value: do not go hunting through
-   storage, cookies or bundles yourself. One experience needs one screen; two
-   `screen` calls is normal, five means the experience is wrong for this
-   product - offer the next one.
+   requests, ranked by your words - field names and row counts, **never
+   values**. `read` confirms the one you picked, with value types. `auth`
+   reports *where* each header value comes from, never the value: do not go
+   hunting through storage, cookies or bundles yourself. One experience needs
+   one screen; two `screen` calls is normal, five means the experience is wrong
+   for this product - offer the next one.
 
    **`observe` refuses what is not provably looking**, and a refusal is an
    answer (**Safety**): it follows links, tabs and menu openers only - a plain
@@ -197,7 +254,8 @@ and asking are not the only options — **observing is, and it comes first**:
    an MFA step, a paywall, a screen that needs a record the account does not
    have, or anything that would write.
 
-Signing in is the human's step, because `inject` launches a fresh profile.
+Signing in is the human's step, because `inject` launches its own Chrome
+profile (empty the first time; it keeps the sign-in after that).
 Navigating is yours. **While you drive a signed-in account you are read-only:**
 GET only, never submit a form, never click anything that creates, sends or
 deletes.
@@ -209,11 +267,11 @@ an assumption by quoting that file later.
 
 ## Build: objects first, code second
 
-Four kinds of thing. With the customer, use **Foldspace's own words** for what
+Four kinds of thing. With the human, use **Foldspace's own words** for what
 they will see in Agent Studio - **action**, **task agent**, **navigation**,
 **publish** - and say what each does the first time you use it. Never invent a
 substitute: no "skill", "ability", "capability" or "tool", and no "switch on"
-for publish. "Skill" already means something else in Claude, and the customer
+for publish. "Skill" already means something else in Claude, and the human
 has seen "Actions" at sign-up and in Agent Studio - a new word breaks the link
 to what they know. The action handler is yours: call it "the code behind it".
 
@@ -229,7 +287,15 @@ built-ins — no code, and a first experience can lean on them.
 
 1. `create_action` as a **draft**. `generate_action_handler` works from a draft
    schema; do not publish yet. Generating the handler from the schema is what
-   keeps the two from drifting.
+   keeps the two from drifting. **Declare every parameter fully**: type,
+   `required`, and a description that says where the value comes from. That
+   schema is what the agent reads to wire actions together by itself - a
+   required `accountId` described as "get it from `find_account`" makes it
+   call `find_account` first. Showing the one match without asking, and a
+   searchable list when there are several or none, come from `find_account`'s
+   instructions and code (`recipes/lookup-then-view`). An id marked optional,
+   or described only as "the id", leaves the agent guessing, or asking the end
+   user for an id they do not have.
 2. Implement the handler from the observed request and response shapes. A
    handler is `fetch` plus `runTask` and nothing more. Import helpers from
    `agent/utils.ts` — inspect that file before writing another `fetch` or rank
@@ -239,29 +305,35 @@ built-ins — no code, and a first experience can lean on them.
 
 **Task agents** are for the one LLM subtask deterministic code cannot do —
 extraction, summarisation, classification, normalisation. Not for API calls,
-CRUD, routing or parsing a known shape. Created in Agent Studio, called with
-`runTask({ taskKey, data })` — published, or it does not resolve. `data` carries
-facts, never `prompt` or `instructions`. One owner per concern: extraction
-reads, normalisation converts, nothing does both.
+CRUD, routing or parsing a known shape. Create one with `create_task_agent` and
+publish it with `publish_task_agent` (with the human's yes - it changes their
+account); call it with `getAgent().runTask({ taskKey, data })` - published, or
+it does not resolve. `data` carries facts, never `prompt` or `instructions`. One
+owner per concern: extraction reads, normalisation converts, nothing does both.
 <https://docs.foldspace.ai/user-guides/task-agents/>
 
-**Changing something already live is a production deploy** — immediate, no
-review, no rollback. Never edit it to test. Stand up a `_gen2` beside it, point
-the code at that, and roll back by pointing back. `_gen2`, never `_v2` —
-Foldspace owns the `v` counter. The suffix is permanent.
+**Publishing an edit to something already live changes the live agent at
+once** - unreviewed, and publishing the earlier version again puts back its
+schema but not the code you changed to match the new one. Never edit it to
+test. Stand up a `_gen2` beside it, point the code at that, and roll back by
+pointing back. `_gen2`, never `_v2` - Foldspace owns the `v` counter. The
+suffix is permanent.
 
 ### The moment a handler exists, prove it
 
 Do not batch verification to the end. As soon as a handler is registered:
-build, confirm it reached `dist/index.js`, attach, confirm
-`registration_ok`, execute it against the live endpoint, and check the result
-is **not empty**. An empty widget that renders cleanly is not a working
-experience.
-
-Say what that proved and what it did not: executing a handler proves the
-handler; only a real chat turn proves the experience (gate 5). Then record the
-endpoint, auth source, response shape and row count in `docs/app-profile.md`,
-with how you established each.
+build, confirm it reached `dist/index.js`, `attach --stop` and attach again
+with the same flags (**Local loop**), confirm `registration_ok`, and
+`npx foldspace observe read` the endpoint it calls. Once the action is
+published (**Ask before publishing**),
+`npx foldspace ask "<the question>" --retry 2` and check that the reply - and
+the card, when the action draws one - shows real data: an empty answer only
+proves the call ran.
+
+Say what that proved and what it did not: `observe read` proves the endpoint
+answers for this account; only the chat turn proves the experience (gate 5).
+Then record the endpoint, auth source, response shape and row count in
+`docs/app-profile.md`, with how you established each.
 
 ## Reachability: everything must be published
 
@@ -271,52 +343,71 @@ with how you established each.
 | Task agent | **yes** | a `taskKey` in code names it |
 | Navigation route | **yes** | `isActive: true` |
 
-Publishing a **new** object is inert; publishing an **edit to a live one** is
-the deploy above. **Navigation has two switches, and both must be on.** Each
-route has its own `isActive`, set when you create it (`create_navigation_route`
-/ `bulk_create_navigation_routes`, `isActive: true`). The agent has one
-agent-level switch, **off by default on a new subscription**: `publish_navigation`
-turns it on, `unpublish_navigation` off, and neither touches the routes' own
-`isActive`. `list_navigation_routes` shows both. There is no MCP tool to flip a
-single route's `isActive` after creation (it was disabled until Agent Studio
-can reverse it) - create it right, or `update_navigation_route`, which replaces
-the whole route. Route descriptions are a retrieval surface: write what the
-page is *for*, in the user's words, and pair every parameterised route with the
-lookup action that produces its parameter — or ship neither.
-
-**Ask before publishing.** It is required only so the copilot can call the
-action, and it is a live product change when the agent has real users.
+**The agent offers only what the browser has.** The SDK tells Foldspace the
+key of every handler loaded on the page, and the agent offers only the
+published actions among those keys - none, on a page that loads no handlers.
+So a published action reaches someone only when its code is in what their
+browser loads: the test window has it while attach runs; their users get it
+once the code is in the bundle their site loads (**Done, and what you say at
+the end**). A handler whose key does not match the action's key is never
+offered.
+
+A **new** action or task agent therefore changes nothing for their users until
+its code reaches them. A navigation route needs no code: once both switches
+below are on, it is live for them. An **edit to anything live** changes the
+live agent at once - an action or task agent when you publish the edit
+(above), a navigation route as soon as `update_navigation_route` replaces it.
+**Navigation has two switches, and both must be on.** Each route has its own
+`isActive`, set when you create it
+(`create_navigation_route` with `is_active: true`, or `isActive: true` per route
+in `bulk_create_navigation_routes`). The agent has one agent-level switch, **off
+by default on a new subscription**: `publish_navigation` turns it on,
+`unpublish_navigation` off, and neither touches the routes' own `isActive`.
+`list_navigation_routes` shows both. To change one route's switch later,
+`update_navigation_route` - it replaces the whole route, so read it first
+(`get_navigation_route`) and send every field back. Route descriptions are a
+retrieval surface: write what the page is *for*, in the user's words, and pair
+every parameterised route with the lookup action that produces its parameter -
+or ship neither.
+
+**Ask before publishing.** It changes their Foldspace account, and an edit to
+something live - or a new navigation route - reaches their users at once.
 
 ## Local loop
 
 ```bash
-npm run dev
+npm run build
 npm run inject
 npx foldspace attach --daemon
 ```
 
 `inject` launches an isolated Chrome profile and records its debug port; it
 loads nothing. In a first session `attach` comes straight after sign-in (L0),
-and `foldspace observe` reads the same window while it runs. `attach` prepares the page and loads the local
-`dist/index.js` over CDP. Coding agents use `--daemon` so the tool returns after
-`[lifecycle] inspect_registration:…`. An empty local registry is valid; `npm run
-build` is still required so `dist/index.js` exists.
+and `foldspace observe` reads the same window while it runs. `attach` prepares
+the page and loads the local `dist/index.js` over CDP. Use `--daemon` so the
+command returns after `[lifecycle] inspect_registration:…`. An empty local
+registry is valid; `npm run build` is still required so `dist/index.js` exists.
 
 Attach mode is read off the page, never asked: default swap when the page
 already has the configured product and agent; `--bootstrap` when it has no
 Foldspace SDK; `--replace` when it embeds a different product or agent, or an
 SDK without the configured agent.
 
-`inspect_registration:registration_ok` is the signal. On `registration_mismatch`
-read `npx foldspace help attach --json` and map `missingActionNames`,
-`unexpectedActionNames`, `diagnosticError`. A running attach keeps the actions
-it loaded: after a rebuild, `attach --stop` and attach again to load the new
-ones. That is the only reason to stop it.
-
-Prove a named action through the visible agent: after the human talks to the
-copilot, read the daemon log for `[actions]` SDK callback and local
-execute/render lines. Those record names, statuses, durations and parameter keys
-only — never results or error bodies.
+`inspect_registration:registration_ok` is the signal. On
+`registration_mismatch`, the attach log says what differs - another agent or
+product on the page, or action names that do not match - and the next step:
+take it. A running attach keeps what it started with - the actions, the hosts
+and the flags - so after a rebuild, `attach --stop` and attach again with the
+same flags; after a change to `hosts`, `npm run inject` between the two
+(**One product, several hosts**). Those, a mismatch's next step, and checking
+published code on dev (**Done, and what you say at the end**) are the only
+reasons to stop it.
+
+Prove a named action through the visible agent. For your own chat turn,
+`npx foldspace ask` reports whether `execute` and `render` ran; after a turn
+of the human's, read the attach log for the `[actions]` SDK callback and local
+execute/render lines. Those record names, statuses, durations and parameter
+keys only - never results or error bodies.
 
 ## Done, and what you say at the end
 
@@ -324,7 +415,44 @@ A first session is done when the customer has seen one experience answer from
 their own data, in the test window, and been invited to try it. Not when the
 gates pass, and not when there is nothing left to improve.
 
-If they ask *"how do I put this in front of my users?"*, the honest answer is:
+**With a code project** (step 5 found or created one), putting it in front of
+their users is yours to do. Once they have tried it in the test window, before
+you offer the second wave:
+
+1. Say *"I'm saving your changes and publishing them to dev"* - no need to
+   ask - then save with `repo_write` and publish with the `deploy` tool, the
+   way `repo_read` command `instructions` says. One exception: a dev preview
+   that comes back with no warnings means this agent loads dev for its users -
+   then ask first, as for production. In chat it is "saving your changes",
+   "publishing to dev" and "publishing for your users" - never GitHub,
+   branches, commits or tool names.
+2. Check dev yourself. Say in chat that you are checking it in that window
+   and to leave it alone until you say it is ready: with attach stopped the
+   page draws no pill. Then `npx foldspace attach --stop` (while attach runs,
+   the page serves your local build), `npx foldspace published dev`, and
+   `npx foldspace ask "<the question>" --retry 2`. Without attach, `ask`
+   cannot see `execute` and `render`: the reply, the card text and the
+   screenshot are the proof - look at the screenshot. If it fails, go no
+   further: attach again, fix it here, then save, publish to dev and check
+   again. If it works, invite them to try it in that window (a reload takes
+   it off dev), and run `npx foldspace attach --daemon` before you build
+   anything else. If `published` says this window cannot show dev, say so in
+   one sentence, attach again, and stop at step 1.
+3. Once the dev check passed, ask before publishing for their users:
+   *"Shall I publish it for your users?"* On a yes, publish to production. On a not yet, it stays on dev:
+   say so in one line and carry on.
+
+Steps 2 and 3 need a site that loads this agent by itself. If you attached
+with `--bootstrap` or `--replace`, it does not yet: do step 1, keep attach
+running, and give the answer below for the rest - their site loading the agent
+is the step the Foldspace team does with them.
+
+A save refused because someone saved after you read is not final: the
+instructions say how to redo it. Any other refusal from the Foldspace tools
+here is final: then the answer below.
+
+**Without a code project**, the answer to *"how do I put this in front of my
+users?"* is:
 
 > What you've seen runs in a test window on your machine. Putting it in front
 > of your users is a separate step, and the Foldspace team does it with you.
@@ -332,8 +460,9 @@ If they ask *"how do I put this in front of my users?"*, the honest answer is:
 > <support@foldspace.ai>. Everything built today carries over: the actions are
 > already in your Foldspace account, and the code is in this folder.
 
-Never run `foldspace deploy`, never install cloud tooling, never ask them for
-cloud credentials: `deploy` is Foldspace-internal and no customer can run it.
+Never run `npx foldspace deploy` - that command is for Foldspace staff only,
+and it is not the `deploy` tool you publish a code project with. Never install
+cloud tooling, and never ask them for cloud credentials.
 
 ## Verification gates
 
@@ -347,17 +476,26 @@ Do not report success without all six:
    action the captured registry includes it.
 5. The action behaves against the real workflow: `[actions]
    local-handler:execute` in the attach log after `foldspace ask` (or the
-   human) exercises the visible agent. A widget also needs `local-handler:render` from a real chat
-   turn — not a hand-built `render()` call. `runAction` refuses render actions
-   and driving `render()` yourself never runs `execute()`.
+   human) exercises the visible agent. A card also needs
+   `local-handler:render` from a real chat turn - not a hand-built `render()`
+   call. A view card leaves the chat free: in `ask`'s screenshot the panel's
+   message box does not read "Provide input, or cancel" beside a Cancel
+   button. If it does, `render` uses `callback` or `cancel` somewhere, or the
+   handler sets `awaitUserInput` - take them out. Then ask a follow-up
+   question about the card (`foldspace ask` again): the reply quotes its
+   numbers exactly as the card shows them. If it does not, make `execute`
+   return them as the card shows them (rule 2). An input card holds the chat
+   until the user answers or closes it, unless it calls `readyState`
+   (**Agentic UI components**).
 6. Browser evidence came from the live target, not hand-authored examples.
-   Neighbour fixtures still pass when they exist.
 
 ## Rules that are not negotiable
 
 1. **Handlers return data only.** Never `directive`, `instructions`, or a
-   paragraph telling the copilot what to say — those live in Agent Studio.
-   Never return `ApiResult.detail` from `execute`; it is for the console.
+   paragraph telling the agent what to say - those live in Agent Studio.
+   Never return from `execute` a token, a cookie, any other secret or
+   `ApiResult.detail` (it is for the console): the agent reads what
+   `execute` returns for an action with no card or a view card (rule 2).
    Validate parameters and return sanitised errors.
    **What goes back to the agent states what happened - it never says what to
    do next.** A status is state: it succeeded, it failed and why (`reason`),
@@ -369,37 +507,47 @@ Do not report success without all six:
    `success: true`, the query, zero matches - *"No <records> match
    '<query>'."* - and it stops there.
 2. **`render` receives `execute`'s return value**, not the input params. A
-   widget that lacks the ids the card needs passes in isolation and fails in the
-   real chat. <https://docs.foldspace.ai/guides/in-chat-ui/>
+   card built from the params passes in isolation and fails in the real chat:
+   return from `execute` every id the card needs. For a view card the agent
+   gets that same value as soon as `render` returns and answers questions
+   about the card from it, so return the facts the card shows, as it shows
+   them, and those ids - never the raw API response. To change what the
+   agent gets, change `execute`, not the card (**Agentic UI components**).
+   <https://docs.foldspace.ai/guides/in-chat-ui/>
 3. **Say what you verified and what you assumed.** "The docs say X" and "I
    think X" are different claims — mark which. Search `docs.foldspace.ai` over
    MCP (`search_docs`, `fetch_page`) before asserting how the platform behaves;
    cite the page, or say plainly that the docs do not cover it and write down
    what you learned.
 4. **Test through the agent, then let them.** In a first session, prove an
-   experience yourself before the customer sees it: once the action is
-   published and registered, `npx foldspace ask "<the question>" --retry 2`
-   types it into the agent's panel in the test window the way a person would,
-   and reports the reply, the card's text, whether `execute` and `render` ran
-   (from the attach log) and a screenshot. A reply with no action fired is
-   publish lag or a wrong key - `--retry` covers the lag. Look at the
-   screenshot. Only then the ready pill and the invitation to try it; never
-   hand the first test to the customer. **Ask only what reads.** A question
-   that makes the agent create, send, change or delete something is you
-   writing in their product: ask it only in an environment the human has
-   named as a test one, or let them type it. Those conversations appear in their
-   Foldspace dashboard, and that is wanted: seeing their own conversations
-   recorded is part of what they came to see. Never pass `--test-mode` in a
-   first session.
+   experience yourself before the human sees it: once the action is published
+   and registered, `npx foldspace ask "<the question>" --retry 2` types it into
+   the agent's panel in the test window the way a person would, and reports the
+   reply, the card's text, whether `execute` and `render` ran (from the attach
+   log) and a screenshot. A reply with no action fired is publish lag or a wrong
+   key - `--retry` covers the lag. Look at the screenshot. Only then
+   `npx foldspace badge ready` and the invitation to try it; never hand the
+   first test to the human. **Ask only what reads.** A question that makes the
+   agent create, send, change or delete something is you writing in their
+   product: ask it only in an environment the human has named as a test one, or
+   let them type it. A card that writes only when the user approves it
+   (`recipes/create-a-record`) is the exception: the question draws the card,
+   `ask` presses nothing on it, and nothing is written - check what it shows,
+   and leave its buttons to the human. The conversations you start appear in
+   their Foldspace dashboard, and that is wanted: seeing their own
+   conversations recorded is part of what they came to see. Never pass
+   `--test-mode` in a first session.
 5. **Test mode is for an agent that already has real users.** Then `attach
    --test-mode` keeps your conversations out of their data. It is not a safety
    net: publishing still changes the live agent. Working on an agent in
    production - test mode, pinned action versions, what may be published - is
-   a separate playbook, not this one.
+   a separate playbook, not this one. Publishing its code with the `deploy`
+   tool is the exception: it takes the same dev-then-production path as a new
+   agent (**Done, and what you say at the end**).
 6. **The human is not necessarily a developer.** Never hand over a terminal
-   line, a stack trace, or a choice between flags. Name experiences by outcome
-   — *"show my plan and credits"*, not `get_account_status`. Their two jobs:
-   sign in, and talk to the agent.
+   line, a stack trace, or a choice between flags. Name experiences by
+   outcome - *"show my plan and credits"*, not `get_account_status`. Their
+   jobs: sign in, talk to the agent, and say yes or no.
 7. **Be short.** No recap of what was established, no restating the plan before
    each step. Progress is one line: what you are doing, the level reached, and
    the question if there is one.
@@ -413,7 +561,7 @@ Do not report success without all six:
      and the recipes first: it may be supported in a way you have not found.
      Say "I did not find it", never "Foldspace does not support it".
    - **Build the narrowest workaround that gives them a working experience.**
-     A prospect is never left stuck on a Foldspace limitation.
+     The human is never left stuck on a Foldspace limitation.
    - **Register it, in two places.** A comment in the code where it lives -
      what it works around, how you established that, and that it goes when the
      fix ships - and a row under **Workarounds** in `docs/app-profile.md`:
@@ -426,8 +574,10 @@ Do not report success without all six:
 
 Lint catches some of these in handler code; Agent Studio copy is on you.
 
-- **No emoji** in copilot replies, cards or handler strings. Put that in the
-  agent's Behavior instructions, and in each new action's Studio `instructions`.
+- **No emoji** in agent replies, cards or handler strings. Put that rule in
+  each new action's Studio `instructions` yourself. It reaches the agent's
+  other replies only if the human adds it to the Behavior instructions: offer
+  that in the second wave (item 5).
 - **Never send the user out of the host app.** No "open in <product>" button,
   no pasted URLs — navigate with a route, same tab.
 
@@ -452,26 +602,56 @@ wins**. <https://docs.foldspace.ai/customize/configuration/>
   mount code is the other place it can live, their engineers' call. Offer it in
   the second wave.
 - **An action's `execute` never calls `setConfiguration`**: a partial call from
-  one once collapsed the agent's panel to nothing.
+  one can collapse the agent's panel to nothing.
 
 ## Agentic UI components: what bites
 
 An Agentic UI component is the card an action draws in the chat (`render`).
 Each of these cost a real build.
 
-- **A component that asks sets `awaitUserInput: true` - and then calling
-  `callback` is mandatory, on every path.** The agent is paused until it is
-  called: submitting, choosing "none of these" and closing the component all
-  end in `callback` (or `cancel()` when they abort), or the conversation hangs.
-  A component that only shows never sets the flag - it would hold the
-  conversation until the user clicked an acknowledgement nobody needed.
-- **What a component sends back is the tool response: the data and the user's
-  choice, as fields**, with the state - chosen, declined, failed - and nothing
-  about what to do next (**Rules**, 1).
-- **A view-only component's data does not reach the model.** For an action
-  that only shows something, the model is told just that *the information was
-  displayed to the end-user* - nothing `execute` returned, nothing the component
-  drew. So the component carries every fact, including the bad ones.
+- **A card is a view card or an input card.** `render(data, host, header,
+  callback, cancel, readyState)` decides which: a `render` that uses
+  `callback`, `cancel` or `readyState` is an input card, and the agent waits
+  until the card reports through one of them; one that uses none of them is
+  a view card.
+- **A view card shows something** - an account, a list, deals at risk -
+  with `render(data, host, header)`: no `callback`, no `cancel`. As soon as
+  `render` returns, the agent gets "Shown to the user. The user has not
+  acted on it." plus exactly what `execute` returned, and answers questions
+  about the card from that. So `execute` returns the facts the card shows,
+  as fields, and nothing else - or the failure the card draws with
+  `renderFailure`: `{ success: false, error, reason }`. To change what the
+  agent gets, change `execute`, not the card. Nothing disables a view card:
+  its tabs and links keep working.
+- **An input card asks the user** - pick one, upload, create, approve. It
+  calls `callback` or `cancel` on every path: choosing, "none of these",
+  closing the card, failing. The agent waits until one of them runs; a path
+  that never calls back leaves it waiting until the user presses stop.
+  `callback(value)` reaches the agent as the user's answer and disables the
+  card; `callback(value, false)` keeps it usable. `cancel()` reaches the
+  agent as cancelled, with no data - when the agent needs to know how the
+  card was closed, call `callback` with that state instead, as
+  `pick-from-a-list` does (`cancelled: true`). ⚠️ The docs say the SDK also
+  draws a default "Cancel" control on a card; not yet checked in the live
+  product.
+- **When the conversation should go on while the user decides,** an input
+  card calls `readyState(value)` (`render`'s 6th argument) once it is
+  drawn: the agent gets `value` as what is shown and carries on. ⚠️ The
+  user's answer then arrives as a follow-up turn - seen in the SDK's
+  headless mode (`mode: "HEADLESS"`, the customer's own chat UI), not yet
+  checked in the chat panel. No recipe uses it yet.
+- **Never set `awaitUserInput`** on either kind: `render` decides whether
+  the agent waits. An input card does not need it. The chat panel ignores
+  it; in headless mode `awaitUserInput: true` on a view card leaves the
+  agent waiting for a callback that never comes, until the user presses
+  stop. Lint stops the build on `awaitUserInput: true` on a view card, and
+  warns on any other `awaitUserInput` and on a `render` that declares
+  `callback`, `cancel` or `readyState` but uses none of them (the SDK then
+  treats it as a view card).
+- **What reaches the agent is the tool response: the data and the user's
+  choice, as fields**, with the state (chosen, declined, cancelled, failed)
+  and nothing about what to do next (**Rules**, 1). A view card needs no
+  state of its own: the SDK tells the agent it was shown.
 - **A failed or signed-out call is never drawn as zeros.** A signed-out response
   often looks like a valid empty one: a 200 with zeros, nulls or an empty list.
   Before you draw numbers, check that the response belongs to a signed-in user -
@@ -484,11 +664,15 @@ Each of these cost a real build.
   stays clean, and the action is recorded as succeeded. Only looking at it shows
   the problem. Draw the empty or the failed state (`renderEmpty`,
   `renderFailure`) - never nothing.
-- **Totals and money are never computed by the model.** Compute them in the
-  action's code or in the component, from the API's own numbers, and show them
-  in the component. The action's instructions tell the model not to restate or
-  recompute them: a model that adds up line items will eventually add them up
-  wrong.
+- **Totals and money are never computed by the agent.** Compute them in
+  code, from the API's own numbers - in `execute` for a view card, since its
+  result is what the agent gets - show them on the card, and hand the agent
+  the same figures. In the action's Studio `instructions`, tell the agent to
+  answer follow-up questions from the data it receives, to quote money and
+  counts exactly as given, never to add them up itself (a model that adds up
+  line items will eventually add them up wrong), and, right after a view
+  card, to say one short sentence at most - never repeat what the card
+  shows.
 - **A card matches the panel, not the page.** The card sits in the agent's
   panel - white by default (the agent's theme: `backgroundColor #FFFFFF`,
   `primaryColor` for accents; a `darkTheme` when the panel is dark, and the
@@ -499,13 +683,8 @@ Each of these cost a real build.
   imports it, and the recipes' `brand.ts` files are placeholders for it. A
   dark app keeps its accent and font; its light-on-dark text would vanish on
   white, so that falls back to greys and the file says so. Record where the
-  values came from in the profile's Brand section. Never copy colours by eye
-  (seen 2026-09-22: a dark card in a white panel).
-- **Plain hex or rgba only.** The panel saves every card to the conversation
-  history as an image drawn with html2canvas, which cannot read `oklch()`,
-  `lab()` or `color-mix()`: one such value and the saved card is blank
-  (`data:,` where the card was). Lint flags them. Do not read the app's CSS
-  variables either - on modern apps they resolve to oklch.
+  values came from in the profile's Brand section. Never copy colours by eye:
+  that is how a dark card ends up in a white panel.
 
 ## Layout
 
@@ -527,20 +706,26 @@ Do not introduce another bundler or bundle format.
 ## Working examples to copy from
 
 Before writing a handler or a card, read
-`node_modules/@foldspace_npm/harness/recipes/INDEX.md` — the whole table, it is
-short — and open the recipe closest to the outcome. Each is a finished
-piece of a build, generalised from production builds with the customer taken
-out: the API helper, the handler or card, and a recorded response per state. Copy its `agent/` files across, then replace the
-placeholder path and fields with what you observed. They match the harness
-version you have installed, and every one is built and run on each release.
+`node_modules/@foldspace_npm/harness/recipes/INDEX.md` - the whole table, it is
+short - and open the recipe closest to the outcome. Each is a finished piece of
+a build, generalised from production builds with the customer taken out: its
+code and its fixtures (for most card recipes, a recorded response per state).
+Copy its `agent/` files across, then replace the placeholder path and fields
+with what you observed. They match the harness version you have installed, and
+every one is built and run on each release.
 
 After the first experience → `who-is-the-user`. L2 → `find-by-name`, and
 `pick-from-a-list` when the user has to choose. The user's records on one
 card → `records-list`. The product lives on several hosts → `several-hosts`.
-Show one account on a card → `account-overview`. Upload a
+The data arrives inside the HTML, with no JSON call → `server-rendered-forms`.
+Show one account the user names → `lookup-then-view` (start here). The app
+already hands over the id → `account-overview`. Upload a
 CSV of contacts → `upload-contacts`. Save a note on a meeting →
-`update-meeting-notes`. Prepare for a meeting → `prepare-for-a-meeting`. The records that need
-attention, with reasons → `opportunities-at-risk`.
+`update-meeting-notes`. Create one record from what the user said, edited on a
+card before it is written → `create-a-record` (all at once, or one question per
+card then a review - its README says which). Prepare for a meeting →
+`prepare-for-a-meeting`. The records that need attention, with reasons →
+`opportunities-at-risk`.
 App does not use a bearer token → `swap-the-login-method`.
 Each says how many production builds carry the pattern and what they learned.
 If nothing fits — there is no L1 card recipe yet, and no navigation recipe —
@@ -557,11 +742,11 @@ not import it — fix the import when you implement.
 | `publicFetch` | Unauthenticated / marketing origin | Signed-in product APIs |
 | `getAuthToken` / `parseJwt` | `AUTH_SOURCE` is `localStorage` or `cookie` | Custom header schemes — override `apiFetch` in `utils.ts` |
 | `rankBy` | User typed a name; API search is exact or ignored | Domain ranking (invoices, coverage, industry classification codes) |
-| `renderLoading` / `Empty` / `Error` / `Fatal` | Chatterblock states | Branded cards — those stay in `agent/views/` |
+| `renderLoading` / `Empty` / `Error` / `Fatal` | Plain states inside a card (loading, empty, error) | Branded cards - those stay in `agent/views/` |
 | `renderFailure` | Any `{ ok: false }` from `apiFetch` — it picks the state from `reason` | You need bespoke copy for one reason; then branch on `reason` yourself |
 | `httpFailure` / `networkFailure` | Your own `apiFetch` (custom header, cookies) — keeps the same `reason`s | The default `apiFetch` fits; then you never call these |
-| `getAgent` | Talking to Foldspace | You need a specific instance — then `agentIds()` |
-| `armAllInstances` | Attach/bootstrap setup | Inside `execute` |
+| `getAgent` | Talking to Foldspace (the overlay instance) | You need a specific instance - then `window.foldspace.agent({ apiName, mode })`, with `apiName` the Agent Key and `mode` in capitals (`"EMBEDDED"`). `window.foldspace.agentIds()` lists the instances in lower case (`"embedded-<apiName>"`): ask only for one it lists - `agent()` creates an instance that does not exist |
+| `armAllInstances` | Never in agent code - `attach` handles the page, and test mode is `attach --test-mode`, only for an agent that already has real users | Anywhere in `agent/`: it ships to production |
 | `redact` / `mapWithConcurrency` | Logging tokens; batching fetches | — |
 
 Every failed call carries a `reason` — `signed_out`, `forbidden`, `not_found`,
@@ -571,13 +756,20 @@ building is not the session at run time: **expect `signed_out`** and let
 `renderFailure` show it. `not_found` and zero rows are both `renderEmpty` with
 the query named — never an error, never a blank card.
 
-If the observed auth is not Bearer + `localStorage`/`cookie`, stop re-exporting
-that one function and keep the rest:
-
-```ts
-export { getAgent, rankBy, renderEmpty } from "@foldspace_npm/harness/runtime";
-export { apiFetch } from "./api";
-```
+If the observed auth is not Bearer + `localStorage`/`cookie`, copy
+`node_modules/@foldspace_npm/harness/recipes/swap-the-login-method/agent/utils.ts`
+over `agent/utils.ts` - or, when the browser's own cookies carry the sign-in and
+there is no token, that recipe's `variants/utils.cookies.ts` - and set what its
+README's **Adapt it** table lists to what you observed.
+
+**If `agent/` came from a code project** (step 5), nothing in it may import a
+package: Foldspace builds the published bundle with no `node_modules`, so a
+package import passes every gate in this manual and then fails on publish.
+Import the helpers the way the project's own `agent/utils.ts` does - from
+`./runtime` - in a recipe file you copy too. A project with an `agent/utils/`
+folder has its own helpers instead: change the sign-in there, and never add an
+`agent/utils.ts` beside it, which would win the import. Without a code project,
+the package import is right.
 
 ## Safety
 
@@ -586,10 +778,13 @@ export { apiFetch } from "./api";
   what you wanted it for, or take a narrower read-only route. Never retry it,
   and never try a different command hoping it gets through - not re-quoted, not
   in pieces, not through a helper script or a subagent: a denial covers the
-  outcome, not the string. If a `foldspace` command itself was denied, name it,
-  give the one-line allow rule (`Bash(npx foldspace:*)` in
-  `.claude/settings.local.json`), and hand that step to the human - for a chat
-  turn, that is them typing the question into the panel.
+  outcome, not the string. If the session's own checks - not the human -
+  denied a `foldspace` command other than `init`, `upgrade` or `deploy`, name
+  it and give the human the allow rule for that one command only, to add to
+  `.claude/settings.local.json` - for `observe`,
+  `Bash(npx foldspace observe:*)` - and meanwhile hand that step to them: for
+  a chat turn, that is them typing the question into the panel. `init`,
+  `upgrade` and `deploy` ask on purpose: never give an allow rule for them.
 - **Never create an account or a key** - not in Foldspace, not in the
   customer's product, not anywhere. If one is missing, say which and where it
   goes. **Never widen your own access**: if something is refused for a site or
@@ -597,5 +792,8 @@ export { apiFetch } from "./api";
 - Do not commit secrets, cookies, HAR files, browser storage, or
   `.foldspace-dev/`. Nothing transient goes in `docs/`.
 - Local handler changes are not cloud publication.
-- Creating or publishing Foldspace resources requires explicit approval.
+- Creating or publishing Foldspace resources needs the human's yes - except
+  the agent's code: creating its code project, saving to it and publishing it
+  to dev, unless the dev preview comes back with no warnings (this agent then
+  loads dev for its users). Say you are doing it, then do it.
 - Action keys and parameter names must match the published schema.