@foldspace_npm/harness 0.1.27 → 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`,
@@ -80,7 +81,7 @@ 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 the
@@ -103,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
@@ -140,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
 
@@ -210,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
@@ -231,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.
@@ -243,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".
 
@@ -263,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
@@ -273,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
 
@@ -305,53 +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, 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: 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
 
@@ -420,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`),
@@ -442,28 +507,36 @@ 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
@@ -472,9 +545,9 @@ Do not report success without all six:
    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.
@@ -488,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`:
@@ -501,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.
 
@@ -527,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 -
@@ -559,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
@@ -574,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
 
@@ -602,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 —
@@ -632,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`,
@@ -668,10 +778,13 @@ the package import is right.
   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