@foldspace_npm/harness 0.1.12 → 0.1.14

package/CLAUDE.md

@@ -35,7 +35,7 @@ something they can **see on their own page** — not at "it builds".
 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
+## The first session has a fixed order
 
 | Level | Reached when |
 |---|---|
@@ -43,15 +43,34 @@ current CLI contract — risk, prerequisites, effects, next step.
 | **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.
+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.
+
+**Say when the test window is yours, and when it is theirs.** You and the
+human share one Chrome window. Before you start looking at the app or testing
+in it: *"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: *"It's
+ready. Try asking: <the question this experience answers>."*
 
-**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.
+Navigation, uploads, extraction and anything that writes are a later session.
 
 ### Ask as a choice, and ask almost nothing
 
@@ -63,7 +82,7 @@ question. Everything else — attach mode, folder, name, level — you **state a
 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 my plan and credits needs one new action on your agent and one card to
 show it in. Sound right?"*
 
 ## Find the call yourself
@@ -73,10 +92,12 @@ 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
+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.
@@ -96,8 +117,13 @@ 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.
+Four kinds of thing. With the customer, 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
+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".
 
 | Thing | Answers | Lives in | You write |
 |---|---|---|---|
@@ -172,8 +198,9 @@ 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
+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.
@@ -253,6 +280,22 @@ Lint catches some of these in handler code; Agent Studio copy is on you.
 - **Never send the user out of the host app.** No "open in <product>" button,
   no pasted URLs — navigate with a route, same tab.
 
+## 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.
+
+- **Every path through `render` draws something.** An action that returns
+  without drawing leaves the slot spinning forever: nothing throws, the console
+  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.
+
 ## Layout
 
 - `agent/actions/` — one handler per action (`execute`, optional `render`),
@@ -321,6 +364,14 @@ export { apiFetch } from "./api";
 
 ## Safety
 
+- **A refusal is an answer.** When a command or tool call is declined - by the
+  human or by the session's own safety checks - stop. Say in one plain sentence
+  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.
+- **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
+  a permission, say so and ask; do not try others.
 - Do not commit secrets, cookies, HAR files, browser storage, or
   `.foldspace-dev/`. Nothing transient goes in `docs/`.
 - Local handler changes are not cloud publication.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foldspace_npm/harness",
-  "version": "0.1.12",
+  "version": "0.1.14",
   "description": "Build and verify portable Foldspace action artifacts against a live app.",
   "type": "module",
   "bin": {