@foldspace_npm/harness 0.1.10 → 0.1.12

package/CLAUDE.md

@@ -0,0 +1,328 @@
+# Foldspace Agent
+
+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.
+
+## Aim at a level, then choose the cheapest experience that reaches it
+
+| 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 |
+
+Navigation, uploads, extraction and anything that writes are a later session.
+Say the target out loud, then offer three or four read-only experiences that
+reach it, **cheapest first**: an endpoint the profile already verifies → the
+user's own data with no parameter (L1) → a search with one parameter (L2).
+`discover_actions` gives candidates, not an inventory.
+
+**Check row counts before recommending.** An experience on a resource the
+account has zero of is a demo of an empty state. On an empty account the useful
+first action is one that creates data — say so instead.
+
+### 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.** `npm run inject`, the human signs in, and *you* go to the
+   screen: 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`,
+   **before** `attach` owns the debug port). 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
+npm run inject
+npx foldspace attach --daemon
+```
+
+`inject` launches an isolated Chrome profile and records its debug port; it
+loads nothing. Observe 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` 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.
+
+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`. 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 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.
+
+## Verification gates
+
+Do not report success without all six:
+
+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`. 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` — 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`. `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, 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` |
+| `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:
+
+```ts
+export { getAgent, rankBy, renderEmpty } from "@foldspace_npm/harness/runtime";
+export { apiFetch } from "./api";
+```
+
+## Safety
+
+- 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.
+- Action keys and parameter names must match the published schema.

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>`
@@ -97,7 +97,7 @@ Non-interactive / CI form:
 npx --yes @foldspace_npm/harness init foldspace-agent \
   --product-id FR8JUQZAQRZB \
   --agent-key my-agent \
-  --domain app.example.com \
+  --app-domain app.example.com \
   --name "My Agent"
 ```
 
@@ -107,14 +107,15 @@ When running directly from a harness checkout during development:
 node bin/cli.mjs init ../foldspace-agent \
   --product-id FR8JUQZAQRZB \
   --agent-key my-agent \
-  --domain app.example.com
+  --app-domain app.example.com
 ```
 
 The Agent Key is the value shown in Agent Studio, such as `my-agent`. It is
 not the sidecar directory name. `--agent-api-name` remains a deprecated alias
-for `--agent-key`. `--name` is optional and defaults to the target directory
+for `--agent-key`. `--domain` remains a deprecated alias for `--app-domain`.
+`--name` is optional and defaults to the target directory
 name (`foldspace-agent` unless you pass a directory). The product ID must be
-the bare ID, not the `EU-…-1-1` SDK loader key. The domain may be a hostname
+the bare ID, not the `EU-…-1-1` SDK loader key. The app domain may be a hostname
 or an HTTP(S) URL without a port or path.
 
 For safety, `init` requires a target path that does not exist. It does not
@@ -132,6 +133,24 @@ npm run attach
 The generated npm scripts intentionally remain the normal project interface;
 `foldspace init` is the one-time project creation command.
 
+Generated `CLAUDE.md` imports platform instructions from
+`@foldspace_npm/harness` instead of copying them. Existing projects can switch
+to that import with `foldspace upgrade --refresh-instructions`.
+
+### Keep the harness current
+
+Tenant projects pin an exact `@foldspace_npm/harness` version. Publishing a
+newer package does not move them. Check, ask the user, then bump:
+
+```bash
+npx --yes @foldspace_npm/harness@latest upgrade --check
+foldspace upgrade --yes   # only after the user agrees
+```
+
+`--check` (and a non-interactive `upgrade` with no `--yes`) never installs.
+`--yes` rewrites the exact pin and runs `npm install --ignore-scripts`. Rebuild
+afterward; that is still not a deploy.
+
 ### Lint handlers before they ship
 
 `foldspace build` runs `foldspace lint` first. Errors skip bundling; warnings

package/bin/cli.mjs

@@ -5,6 +5,12 @@ import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { runInit } from "../src/init.mjs";
+import {
+  checkForUpdate,
+  nagIfOutdated,
+  resolveProjectDir,
+  runUpgrade,
+} from "../src/upgrade.mjs";
 import {
   classifyAttachControl,
   runAttachControl,
@@ -56,10 +62,13 @@ function printHelp(topic, json) {
     );
     return;
   }
+  const update = checkForUpdate(resolveProjectDir());
   if (json) {
-    console.log(JSON.stringify(document, null, 2));
+    const payload = topic ? document : { ...document, update };
+    console.log(JSON.stringify(payload, null, 2));
     return;
   }
+  nagIfOutdated(update);
   console.log(
     topic ? renderCommandHelp(registry, topic) : renderGeneralHelp(registry),
   );
@@ -118,6 +127,7 @@ const [command, ...args] = process.argv.slice(2);
 if (!command || command === "--help" || command === "-h") {
   printHelp(null, args.includes("--json"));
 } else if (command === "--version" || command === "-v") {
+  nagIfOutdated(checkForUpdate(resolveProjectDir()));
   console.log(
     `${registry.package.name} ${registry.package.version} ` +
       `(protocol ${registry.protocolVersion}, CLI schema ${registry.schemaVersion})`,
@@ -149,6 +159,24 @@ if (!command || command === "--help" || command === "-h") {
       fail(error instanceof Error ? error.message : String(error));
     }
   }
+} else if (command === "upgrade") {
+  if (args.includes("--help") || args.includes("-h")) {
+    printHelp("upgrade", args.includes("--json"));
+  } else {
+    try {
+      const normalized = normalizeCommandArgs(commandByName("upgrade"), args);
+      Promise.resolve()
+        .then(() => runUpgrade(normalized))
+        .then((report) => {
+          console.log(JSON.stringify(report, null, 2));
+        })
+        .catch((error) => {
+          fail(error instanceof Error ? error.message : String(error));
+        });
+    } catch (error) {
+      fail(error instanceof Error ? error.message : String(error));
+    }
+  }
 } else if (commandByName(command)) {
   if (args.includes("--help") || args.includes("-h")) {
     printHelp(command, args.includes("--json"));

package/package.json

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

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.

package/recipes/find-by-name/README.md

@@ -0,0 +1,47 @@
+# Find by name — L2
+
+**The user says** "add it to the Maple Street project". **The agent needs** an id.
+
+**Proven by 3 production builds**, all the same shape: a name from the user's
+words → the app's own list → a ranked answer **back to the agent as data**. None
+of them draws a card. A resolver answers questions; it never asks one. When the
+user genuinely has to choose, that is a different action —
+[`pick-from-a-list`](../pick-from-a-list/).
+
+In Agent Studio: an action with key `find_project_id` and one optional string
+parameter `name` — *the name, or part of the name, the user said*.
+
+## What it returns
+
+| The user's words | The agent gets |
+|---|---|
+| no name ("how many projects do I have?") | the account's **count**, plus a small sample — never the whole account |
+| one clear match | that project, its match strength, and up to three alternatives |
+| several equally good matches | **all of them**, marked `ambiguous` — never a silent pick |
+| nothing matches | `success: false`, plus near-misses for a typo |
+| the account is empty | a count of zero — not an error |
+| signed out, no access, throttled, unreachable | `success: false` with the `reason` |
+
+## Adapt it
+
+| File | Change |
+|---|---|
+| `agent/api/projects.ts` | Path, parameter names, envelope — from a captured response |
+| `agent/projects.ts` | What a summary carries, and which keys a user might name out loud |
+| `agent/actions/find_project_id.ts` | The entity. The logic rarely needs touching |
+
+## What those builds learned the hard way
+
+- **Hand back every tie.** Picking one of two equally good matches is how a
+  later action changes the wrong project.
+- **Count on the server.** Fetching every row to count them is the slowest thing
+  an agent can do, and it puts the whole account into the model's context.
+- **Return summaries, not rows.** Two of the three builds send ten raw fields
+  per row to the agent; the third sends three and is the one that scales.
+- **A missing session is not "no projects".** One build reports a missing token
+  as an empty list, and the agent cheerfully tells a signed-out user they have
+  none.
+- **Server search is usually a plain substring**, so a typo finds nothing. Try
+  the near-miss pass before saying no.
+- **Probe with a name a real record has.** A search that returns zero proves
+  nothing unless a matching record exists.