@foldspace_npm/harness 0.1.11 → 0.1.13

package/CLAUDE.md

@@ -1,108 +1,184 @@
 # Foldspace Agent
 
-## Harness version
-
-At the start of a session, run `npx foldspace help --json` (or, from an older
-install, `npx --yes @foldspace_npm/harness@latest upgrade --check`).
-
-If `update.outdated` is true, tell the user the pinned and latest versions and
-**ask before upgrading**. After they agree, run `foldspace upgrade --yes`, then
-`npm run build`. Do not upgrade as a side effect of build, attach, or
-implementing an action. A harness bump is not a deploy.
-
-If the tenant `CLAUDE.md` does not contain
-`@node_modules/@foldspace_npm/harness/CLAUDE.md`, ask before
-`foldspace upgrade --refresh-instructions`. That replaces the snapshot with an
-import of this file.
-
-## Before building
-
-1. Run `npx foldspace help --json` before an unfamiliar harness operation.
-   Treat its risk, prerequisites, effects, next-step, and `update` fields as
-   the current CLI contract.
-2. Connect Product MCP and verify that `list_agents` works.
-3. Inspect the selected agent with `get_agent_settings`, `list_actions`, and
-   `list_task_agents`.
-4. Use `discover_actions` to identify candidate experiences, then let the user
-   choose what to build. Treat those ideas as candidates, not an inventory.
-
-## Build workflow
-
-An experience can require several reusable actions. Separate lookup actions
-from actions that read or mutate a selected resource.
-
-1. Agree on the candidate experience and how its actions would compose. This is
-   not a publish and not a commitment.
-2. Run `npm run inject`. Ask the user to sign in and perform the real target
-   workflow in that Chrome window.
-3. Capture at least one real HTTP 200 for the data the action needs. Use
-   chrome-devtools MCP against the inject Chrome, or a page-context `fetch`,
-   **before** `attach` owns the debug port. If there is no 200,
-   pivot; do not create Foldspace resources. Write what you establish into
-   `docs/app-profile.md` with **how you know it**. Do not promote an assumption
-   by quoting that file.
-4. Create action metadata as a draft. `generate_action_handler` works from a
-   draft schema; do not publish yet.
-5. Implement the handler using the observed request and response shapes.
-   Import helpers from `agent/utils.ts` — inspect that file before writing
-   another `fetch` or rank helper.
-6. Register the handler in `agent/actions/index.ts` and build (`foldspace build` lints first).
-7. Run `npx foldspace attach --daemon` (add `--bootstrap` or `--replace` when
-   the page requires it). An empty local registry is valid if you only want to
-   see how the agent works.
-8. Ask before publishing. Publishing is required only so the copilot can call
-   the action, and it is a live product change when the agent has real users.
-9. Complete the verification gates below.
-
-## API rules
-
-Actions execute in the user's signed-in browser session.
-
-- Import HTTP, ranking, and widget helpers from `../utils`, not a new
-  `agent/api.ts` copy of `fetch`.
-- Do not guess `API_BASE` or `AUTH_SOURCE`. Capture at least one real 200
-  (and the auth header the page actually sends) before filling them in.
-  `credentials: "include"` is correct only when you have observed the app
-  using cookies that way. Many apps use `Authorization: Bearer` from
-  `localStorage` instead; some use a custom header.
-- Never guess endpoints or schemas. Capture at least one real 200 before
-  implementing a parser. Do not implement a path that was not observed.
-- Verify that the user is signed in before observing a workflow.
-- Do not substitute a public developer API when the browser session is missing;
-  ask the user to sign in.
-- Validate parameters and return sanitized errors. Return **data only** — never
-  `directive`, `instructions`, or a paragraph telling the copilot what to say.
-  Action and agent instructions live in Agent Studio / MCP. Never return
-  `ApiResult.detail` from `execute` — it is for the console.
-- Actions that return data the user will inspect should include a `render`
-  function for in-chat UI (a chatterblock). If it makes more sense to output the data
-  in a UI component instead of text then consider using render to show a component.
-   - `render` receives **`execute`'s return value**, not the action's input params.
-     Returning anything that lacks the ids the card needs is why widgets pass in
-     isolation and fail in the real chat.
-   - `runAction` refuses render actions (`cannot be executed silently`). Driving
-     `render()` yourself never runs `execute()`, so it does not test that contract.
-   - Check https://docs.foldspace.ai/guides/in-chat-ui/ for more information
-
-## Task agents
-
-Use a Task Agent when the handler needs a one-time LLM subtask that
-deterministic code cannot do well: extraction, summarization,
-classification, normalization, enrichment, or generation.
-
-Do not use a Task Agent for API calls, CRUD, routing, or parsing a
-known response shape. Those stay in `execute`.
-
-Task agents are created in Agent Studio, not in this repo. Ask before
-creating or publishing one. Call a published task agent from the
-handler with `runTask({ taskKey, data })` (if not published the runTask won't work).
-`data` carries extracted facts only — not `prompt` / `instructions` strings.
-Prefer JSON output when the handler must consume the result.
-
-See https://docs.foldspace.ai/user-guides/task-agents/ and
-https://docs.foldspace.ai/reference/task-agent-api/
-
-## Local harness loop
+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".
+
+## 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. If the
+   project `CLAUDE.md` does not contain
+   `@node_modules/@foldspace_npm/harness/CLAUDE.md`, ask before
+   `foldspace upgrade --refresh-instructions`.
+2. **Is Foldspace connected? Check — never assume.** Call `list_agents`:
+
+   | Result | Do |
+   |---|---|
+   | The tool does not exist | The Foldspace MCP is not installed in this editor. Give the one install step for *this* editor — 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** → finish in the browser — then check again |
+   | 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`,
+   `list_navigation_routes`. Record current versions before changing anything;
+   if something breaks, this is how you prove what moved. Conversation starters
+   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.
+
+Before an unfamiliar harness operation, `npx foldspace help --json` is the
+current CLI contract — risk, prerequisites, effects, next step.
+
+## The first session has a fixed order
+
+| Level | Reached when |
+|---|---|
+| **L0 · agent live** | injected, visible on the page, `identify` fired |
+| **L1 · read settings** | the user's own account, plan or settings in a widget, 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`, the human signs in to their
+   app, then `npx foldspace attach --daemon`. An empty registry is valid. L0
+   is `registration_ok` with the agent visible on their page - tell them to
+   look at it and say hello to it. **Do not explore the app first**: no
+   reading its bundle, no watching its traffic, no browsing its screens.
+   Nothing about L0 needs any of it, and minutes of silent investigation
+   before the human has seen anything is the wrong first impression.
+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 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.
+
+Navigation, uploads, extraction and anything that writes 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:
+*"Show my plan and credits needs one thing the agent can call and one card to
+show it in. Sound right?"*
+
+## Find the call yourself
+
+Never guess `API_BASE`, `AUTH_SOURCE`, an endpoint or a schema. But guessing
+and asking are not the only options — **observing is, and it comes first**:
+
+1. **Already known** — `docs/app-profile.md`. A verified endpoint needs no
+   browsing.
+2. **You drive - once they have chosen an experience.** The agent is already
+   attached from L0, and `attach` owns the debug port: `npx foldspace attach
+   --stop` first. Then *you* go to the one screen that experience needs: read
+   the app's bundle for API paths and watch the requests it makes
+   (chrome-devtools MCP against the inject Chrome, or a page-context
+   `fetch`). Attach again when you have the call. Read the auth method off a request
+   the page already sent — bearer from `localStorage`, cookie, custom header.
+   Delegate the watching to a read-only subagent so the traffic does not flood
+   your context.
+3. **Ask the human to perform the workflow** — only for what you cannot reach:
+   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.
+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.
+
+Capture at least one real HTTP 200 for the data the action needs. If there is
+none, pivot; do not create Foldspace resources. Write what you establish into
+`docs/app-profile.md` **with how you know it**, at that moment. Do not promote
+an assumption by quoting that file later.
+
+## Build: objects first, code second
+
+Four kinds of thing. Never make the customer learn these words — describe them
+by what they do.
+
+| Thing | Answers | Lives in | You write |
+|---|---|---|---|
+| **Action** | *when* should the agent invoke this? | Agent Studio | the contract |
+| **Action handler** | what happens when it does | `agent/actions/<name>.ts` | the code |
+| **Task agent** | *how* to do one reasoning job | Agent Studio | instructions + response schema |
+| **Navigation route** | where the agent can send the user | Agent Studio | a URL template + what the page is for |
+
+Knowledge search, navigation and sharing the current tab are platform
+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.
+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
+   helper.
+3. Register it in `agent/actions/index.ts` and build (`foldspace build` lints
+   first).
+
+**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.
+<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.
+
+### 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.
+
+## Reachability: everything must be published
+
+| | Published to run? | Second gate |
+|---|---|---|
+| Action | **yes** | handler registered in `agent/actions/index.ts` |
+| 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 **no publish tool on the MCP** and
+`get_navigation_route` returns only `isActive` — publish routes in Agent Studio
+and say so. 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.
+
+## Local loop
 
 ```bash
 npm run dev
@@ -110,99 +186,147 @@ npm run inject
 npx foldspace attach --daemon
 ```
 
-`inject` launches an isolated Chrome profile and records its debug port.
-It does not generate or load an application extension. Observe the customer's
-workflow after inject and **before** attach, while chrome-devtools MCP can use
-the same Chrome. `attach` prepares the page and loads the local `dist/index.js`
-bundle through CDP. Coding agents must use `--daemon` so the invoking tool
-returns after `[lifecycle] inspect_registration:…`; foreground `npm run attach`
-is for humans watching the terminal. An empty local registry is valid. `npm run
+`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);
+to observe afterwards, `attach --stop`, use chrome-devtools MCP against the
+same Chrome, then attach again. `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.
 
-Use the default swap only when the page already has the configured product and
-agent. Use `--bootstrap` only when the page has no Foldspace SDK, and
-`--replace` when it embeds a different product or agent, or when an SDK is
-present without the configured agent.
-
-The attach log must report `inspect_registration:registration_ok` before
-treating the page as registered. Zero captured actions is success when the
-local registry is empty. On `registration_mismatch`, read
-`npx foldspace help attach --json` diagnostics and map those names onto the
-lifecycle details (`missingActionNames`, `unexpectedActionNames`,
-`diagnosticError`).
+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.
 
-While attach is running it owns the debug port. Detach (`attach --stop`, or
-Ctrl-C in the foreground) before using chrome-devtools MCP against the same
-Chrome.
+`inspect_registration:registration_ok` is the signal. On `registration_mismatch`
+read `npx foldspace help attach --json` and map `missingActionNames`,
+`unexpectedActionNames`, `diagnosticError`. While attach runs it owns the debug
+port — `attach --stop` before using chrome-devtools MCP again.
 
-Prove a named action through the visible agent. After the user talks to the
+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; do not invoke the handler directly. Those lines record
-names, statuses, durations, and parameter keys only — not results or error
-bodies.
-
-## Product defaults
-
-These are not product-specific. Lint can catch some of them 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 (MCP cannot write that field, so each new
-  action's Studio `instructions` must carry the line too).
-- **Never send the user out of the host app.** No "open in &lt;product&gt;"
-  button and no pasted URLs — navigate with a navigation route, same tab.
-- **Check row counts before choosing the experience.** On an empty account the
-  useful first action is one that creates data.
+execute/render lines. Those record names, statuses, durations and parameter keys
+only — never results or error bodies.
 
 ## Verification gates
 
 Do not report success without all six:
 
-1. TypeScript compiles with `npm run typecheck` (`tsc --noEmit -p tsconfig.json`).
-   Do not run `npx tsc` — that can install the wrong package.
-2. `foldspace lint` reports no errors (`foldspace build` runs this first).
-3. The expected handler appears in `dist/index.js`.
-4. The browser reports `inspect_registration:registration_ok`. For a named
-   action, the captured registry includes that handler.
-5. The action behaves correctly against the real target workflow. Confirm
-   `[actions] local-handler:execute` in the attach log after the user exercises
-   the visible agent. For a widget, that log must include `local-handler:render`
-   from a real chat turn — not a hand-built `render()` call.
-6. Browser evidence came from the live target, not from hand-authored examples.
+1. `npm run typecheck` compiles (`tsc --noEmit -p tsconfig.json`). Do not run
+   `npx tsc` — it can install the wrong package.
+2. `foldspace lint` reports no errors (`foldspace build` runs it first).
+3. The handler appears in `dist/index.js`.
+4. The browser reports `inspect_registration:registration_ok`, and for a named
+   action the captured registry includes it.
+5. The action behaves against the real workflow: `[actions]
+   local-handler:execute` in the attach log after 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()`.
+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.
+   Validate parameters and return sanitised errors.
+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/>
+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. **Do not send chat messages to test.** Every message is a real conversation
+   in the customer's list. `runTask` creates no conversation record — use it.
+5. **Test mode is off by default.** A new agent has no traffic to pollute, and
+   watching real conversations appear is the point of the first run. Arm it
+   only when the tenant already has real conversations — and then on **every**
+   instance via `armAllInstances`, because `foldspace.agent({apiName})` returns
+   the overlay handle, which is not the one serving an embedded chat. Nothing
+   can confirm it is on afterwards; never send probe messages to find out.
+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.
+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.
+8. **Subagents investigate; they do not build.** A read-only investigation
+   that returns a summary belongs in a subagent because it floods context.
+   Never delegate a handler or a gate — a summary of a gate is not a gate.
+
+## Product defaults
+
+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`.
+- **Never send the user out of the host app.** No "open in <product>" button,
+  no pasted URLs — navigate with a route, same tab.
+
 ## Layout
 
 - `agent/actions/` — one handler per action (`execute`, optional `render`),
-  registered in `index.ts`
+  registered in `index.ts`. The key must equal the action key in Agent Studio;
+  a mismatch does not error, the action simply never fires.
 - `agent/api/` — one HTTP helper per endpoint
 - `agent/constants.ts` — agent, product, domain, plus empty `API_BASE` /
   `AUTH_SOURCE` and `LOAD_MODE`
-- `agent/utils.ts` — configure the harness runtime and re-export it. **This is
-  the only import surface for actions.**
-- `foldspace.dev.json` — local harness target configuration
+- `agent/utils.ts` — configures the harness runtime and re-exports it. **The
+  only import surface for actions.**
+- `agent/views/` — branded cards
 - `docs/app-profile.md` — what is known about this app, and how it was established
+- `foldspace.dev.json` — local harness target configuration
 - `CLAUDE.md` — this file, imported — plus what is specific to this product
 
 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.
+
+L0 → `who-is-the-user`. L2 → `find-by-name`, and `pick-from-a-list` when the
+user has to choose. 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 — say so and build from
+`agent/actions/_example.ts`.
+
 ## What you already have
 
-Import from `../utils`. Inspect that file before implementing another
-general-purpose helper. MCP `generate_action_handler` may still emit a
-skeleton that does not import it — fix the import when you implement.
+Import from `../utils`. `generate_action_handler` may emit a skeleton that does
+not import it — fix the import when you implement.
 
 | Helper | Use when | Do not use when |
 |---|---|---|
 | `apiFetch` / `apiFetchBinary` | The app's own JSON/file API, after a real 200 | Public marketing hosts (`publicFetch`); custom auth headers |
 | `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, MasterFormat) |
-| `renderLoading` / `Empty` / `Error` / `Fatal` | Chatterblock empty/error paths | Branded cards — those stay in `agent/views/` |
+| `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/` |
+| `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` (can ship into `dist`; attach already arms test mode) |
+| `armAllInstances` | Attach/bootstrap setup | Inside `execute` |
 | `redact` / `mapWithConcurrency` | Logging tokens; batching fetches | — |
 
+Every failed call carries a `reason` — `signed_out`, `forbidden`, `not_found`,
+`rate_limited`, `timeout`, `unreachable`, `config`, `server`. Branch on that,
+not on `status`, and do not re-detect it. The session you observed while
+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:
 
@@ -211,25 +335,10 @@ export { getAgent, rankBy, renderEmpty } from "@foldspace_npm/harness/runtime";
 export { apiFetch } from "./api";
 ```
 
-## Agent learnings
-
-`docs/app-profile.md` is the durable record of this app. Fill it as you probe,
-not afterwards. Other notes in `docs/` are fine for session-specific lessons.
-
-- Before similar work, read `docs/app-profile.md` and any other notes in `docs/`.
-- After non-obvious discoveries, add them to the profile (or a short extra
-  note) covering verified gotchas, failed approaches, and how they were
-  established.
-- Keep notes concise and evidence-based.
-- Do not store secrets, cookies, HAR files, browser storage, or other transient
-  session data in `docs/`.
-
 ## Safety
 
 - Do not commit secrets, cookies, HAR files, browser storage, or
-  `.foldspace-dev/`.
+  `.foldspace-dev/`. Nothing transient goes in `docs/`.
 - Local handler changes are not cloud publication.
 - Creating or publishing Foldspace resources requires explicit approval.
 - Action keys and parameter names must match the published schema.
-- Search Foldspace documentation before asserting unfamiliar platform
-  behaviour.

package/README.md

@@ -26,7 +26,7 @@ constraint this package exists to protect.
 ### What is genuinely shared
 
 - `agent/actions/*` and `agent/api/*` — a handler is `fetch` plus `runTask`,
-  nothing more. The actions built for Figma run unmodified in either track.
+  nothing more. Actions built in one track run unmodified in the other.
 - `agent/utils.ts` — configures and re-exports `@foldspace_npm/harness/runtime`
 - `foldspace build` — esbuild → `dist/index.js`
 - `foldspace deploy` — publish to `agent/actions/<env>/<productId>/<agentApiName>`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foldspace_npm/harness",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "description": "Build and verify portable Foldspace action artifacts against a live app.",
   "type": "module",
   "bin": {
@@ -21,6 +21,7 @@
     "bin",
     "src",
     "templates",
+    "recipes",
     "README.md",
     "CLAUDE.md"
   ],

package/recipes/INDEX.md

@@ -0,0 +1,15 @@
+# Recipe index
+
+Read this whole table, then open the recipe closest to the outcome.
+
+| Recipe | Level | What it gives | Kind | Proven by |
+|---|---|---|---|---|
+| [`who-is-the-user`](who-is-the-user/) | **L0** | Foldspace knows who is signed in — id, email, name, role, subscription — so conversations and analytics are not anonymous | Runs once at start-up. No action, no card | 4 production builds |
+| [`find-by-name`](find-by-name/) | **L2** | The agent turns a name the user said into the id the next action needs; a count when no name is given; every tie when the name is ambiguous; near-misses when nothing matches | A data action. **No card** | 3 production builds |
+| [`pick-from-a-list`](pick-from-a-list/) | **L2** | A clickable list, shown **only** when the user has to choose — with "none of these" and cancel | An action with a card that waits for the user | 1 production build |
+| [`swap-the-login-method`](swap-the-login-method/) | any | `apiFetch` for an app that authenticates with a custom header, or with cookies, instead of a bearer token | A replacement `agent/utils.ts` | 2 production builds (3 builds, 3 different schemes) |
+
+**Not here yet — no production build proves it:** the user's own plan or
+settings drawn as a card (L1). In production that data is sent to `identify`
+(`who-is-the-user`), not rendered. Navigation (L3), writes (L4), uploads and
+task agents are also still to come.

package/recipes/README.md

@@ -0,0 +1,46 @@
+# Recipes
+
+Finished pieces of a build to **read and adapt** — each one generalised from a
+pattern that is live in production builds, with the customer taken out.
+`_example.ts` is an empty skeleton; these are complete.
+
+They ship inside the harness on purpose: a recipe always matches the runtime it
+imports, and every one is installed into a freshly scaffolded project, built,
+typechecked and run against its fixtures on every harness change
+(`test/recipes.test.mjs`). A recipe that stops working fails the release instead
+of a customer session.
+
+## Use one
+
+1. Read `INDEX.md` and pick the closest outcome.
+2. Copy its `agent/` files into your project's `agent/` — the layout is the
+   same, so the imports already resolve.
+3. Replace every `__observe_me` placeholder — paths, storage keys, claim names —
+   with what you **observed** in the live app, and record how you know in
+   `docs/app-profile.md`. The placeholders are deliberate: none can succeed.
+4. Register actions in `agent/actions/index.ts` under the **same key** as in
+   Agent Studio, then run the six gates.
+
+If nothing here fits, say so and build from `_example.ts`.
+
+## Where they come from
+
+Each recipe's README says how many production builds carry the pattern and what
+those builds learned the hard way. **What is taken is the shape** — the order of
+calls, what is returned to the agent, where the traps are. **What is not taken**
+is any customer's name, endpoint, identifier, styling or code. Contracts are the
+documented ones: `execute(params)` and
+`render(data, host, header, callback, cancel)`
+(<https://docs.foldspace.ai/guides/in-chat-ui/>), `foldspace.identify(context)`
+(<https://docs.foldspace.ai/start/user-context/>), and the harness runtime.
+
+Error handling is **not** taken from those builds. They predate `reason`: one
+turns every failure into "unexpected error", another reports a missing session
+as "no projects found". Recipes use the runtime's failure reasons instead.
+
+## What every recipe demonstrates
+
+- `execute` returns **data and facts** — never `detail`, never instructions.
+- A missing or expired session is `signed_out`, not an empty result.
+- DOM is built with `textContent`, never `innerHTML` with API data, and styles
+  go in `header` — `host` lives inside the component's frame.