@foldspace_npm/harness 0.1.37 → 0.1.39

package/CLAUDE.md

@@ -516,6 +516,14 @@ save or publish:**
 <committed_paths, comma-separated>`, so your own save is not taken for
 someone else's.
 
+**None of this is said to the human.** No develop, lines of work, pulling,
+merging, conflicts, commits or branches - not in a status line, not when
+something goes wrong. When nobody else saved, say nothing. When someone did,
+one line: *"I brought in changes a teammate saved."* When a file had changes
+both here and in theirs, name the experience in their words: *"A teammate
+also changed the patient table; I kept theirs and put my change on top."*
+Updating the harness is *"updating the Foldspace tools"*, never pulling it.
+
 ## Done, and what you say at the end
 
 A first session is done when the customer has seen one experience answer from
@@ -551,15 +559,27 @@ you offer the second wave:
    again. If it works, invite them to try it in that window (a reload takes
    it off dev), and run `npx foldspace attach --daemon` before you build
    anything else. If `published` says this window cannot show dev, say so in
-   one sentence, attach again, and stop at step 1.
+   one sentence, attach again, and do not offer production yourself - but
+   publish it when the human asks (below).
 3. Once the dev check passed, ask before publishing for their users:
    *"Shall I publish it for your users?"* On a yes, publish to production. On a not yet, it stays on dev:
    say so in one line and carry on.
 
-Steps 2 and 3 need a site that loads this agent by itself. If you attached
-with `--bootstrap` or `--replace`, it does not yet: do step 1, keep attach
-running, and give the answer below for the rest - their site loading the agent
-is the step the Foldspace team does with them.
+**Publishing for their users is the human's call, not a step they earn.**
+When they ask for it - at any point, whether or not the dev check ran or
+could run - that is the yes: publish to production the way `repo_read`
+command `instructions` says, in that turn. Do not ask them to confirm again,
+and do not explain the process. When dev was not checked, one line as you
+publish: *"I couldn't check it on dev here, so it goes out as you tried it
+in the test window."* Only a refusal from the Foldspace tools stops it (below).
+
+Step 2 needs a site that loads this agent by itself. If you attached with
+`--bootstrap` or `--replace`, it does not yet: do step 1, keep attach
+running, and do not offer production yourself - their site loading the agent
+is the step the Foldspace team does with them. When the human asks for
+production anyway, publish it (above), and add one line: *"Your users will
+see it once your site loads the agent - that's the step the Foldspace team
+does with you."*
 
 A save refused because someone saved after you read is not final: pull again
 (**Several builders, one agent**), put your change on top and save. Any other refusal from the Foldspace tools
@@ -759,7 +779,8 @@ Each of these cost a real build.
   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. Foldspace's docs call these **read-only** and **input**
+  cards; they mean the same thing.
 - **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
@@ -798,6 +819,14 @@ Each of these cost a real build.
   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.
+- **Never report a view card through `callback`.** Calling `callback(data)`
+  right after drawing (the old way to get a card's data to the agent) tells
+  the agent the user submitted that data, and it replies as if they had.
+  A view card takes `render(data, host, header)`, or calls
+  `readyState(value)` to send less than `execute` returned.
+- **The agent only knows what the card reports, not what it draws.** A
+  figure or date on the card that is not in that data is unknown to the
+  agent, so put every fact a follow-up question could need in it.
 - **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 -
@@ -814,11 +843,8 @@ Each of these cost a real build.
   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.
+  quote money and counts exactly as given and never to add them up itself (a
+  model that adds up line items will eventually add them up wrong).
 - **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

package/package.json

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

package/recipes/README.md

@@ -43,9 +43,10 @@ SDK's: `execute(params)` and
 `render(data, host, header, callback, cancel, readyState)`
 (<https://docs.foldspace.ai/guides/in-chat-ui/>), `foldspace.identify(context)`
 (<https://docs.foldspace.ai/start/user-context/>), and the harness runtime.
-Where the in-chat UI page says to set `awaitUserInput`, do not - the SDK waits
-when `render` uses `callback` or `cancel` (see the card bullet below). That
-page does not list `readyState`; CLAUDE.md describes it, and no recipe uses it.
+Never set `awaitUserInput` - the SDK waits when `render` uses `callback`,
+`cancel` or `readyState` (see the card bullet below). What the agent receives
+for each is in CLAUDE.md (**Agentic UI components**); no recipe uses
+`readyState` yet.
 
 Error handling is **not** taken from those builds. They predate `reason`: one
 turns every failure into "unexpected error", another reports a missing session

package/recipes/account-overview/README.md

@@ -8,7 +8,7 @@ This card is the base layout. Copy it, then replace the `/__observe_me` routes w
 
 A view card: `render` takes no `callback` and the action sets no `awaitUserInput`. As soon as the card is drawn, the agent gets "Shown to the user. The user has not acted on it." plus exactly what `execute` returned - the account, the totals and every row behind the tabs, or the failure (`success: false`, `error` and `reason`) - and it answers questions about the account from that. So `execute` returns the overview the card draws and nothing else. One tab is on screen at a time; an empty tab says so. A signed-out or failed call is drawn with `renderFailure`, never as zeros. A 200 is signed out unless the account has both an id and a name.
 
-In Agent Studio: an action with key `show_account_overview` and one string parameter `accountId`, described as "The account's id. Never taken from the user's words: get it from `<lookup action key>`." Replace `<lookup action key>` with the key of this agent's action that returns account ids; if the agent has none, build that action first - `find-by-name` has the shape. Its `instructions`: "Answer follow-up questions about this account from the data you receive: quote money and counts exactly as given, and never add them up yourself. Right after the card, one short sentence at most - do not repeat what it shows. On a failure, the card already says why: say so in one short sentence and stop. No emoji."
+In Agent Studio: an action with key `show_account_overview` and one string parameter `accountId`, described as "The account's id. Never taken from the user's words: get it from `<lookup action key>`." Replace `<lookup action key>` with the key of this agent's action that returns account ids; if the agent has none, build that action first - `find-by-name` has the shape. Its `instructions`: "Quote money and counts exactly as given, and never add them up yourself. No emoji."
 
 ## Adapt it
 

package/recipes/lookup-then-view/studio/show_account_overview.json

@@ -11,5 +11,5 @@
     }
   ],
   "confirmation_required": false,
-  "instructions": "The result is the data the card was drawn from - every open deal, person and open case, not only the ones it lists - or a failure: success false, with the reason. Answer follow-up questions about this account from the data you receive: quote money and counts exactly as given, and never add them up yourself. Right after the card, one short sentence at most - do not repeat what it shows. On a failure, the card already says why: say so in one short sentence and stop. No emoji."
+  "instructions": "The result is the data the card was drawn from - every open deal, person and open case, not only the ones it lists - or a failure: success false, with the reason. Quote money and counts exactly as given, and never add them up yourself. No emoji."
 }

package/recipes/opportunities-at-risk/README.md

@@ -8,7 +8,7 @@ The app decides what "at risk" means, on the server. In that build it was: stall
 
 A view card: `render` takes no `callback` and the action sets no `awaitUserInput`. As soon as the card is drawn, the agent gets "Shown to the user. The user has not acted on it." plus exactly what `execute` returned - the count, the total, the average and the rows (no rows when the card says "No opportunities are at risk."), or the failure (`success: false`, `error` and `reason`). So `execute` returns what the card draws, with each row's id, and nothing else. The count, the total and the average are computed in code from the rows.
 
-In Agent Studio: an action with key `show_opportunities_at_risk` and no parameters. Its `instructions`: "Answer follow-up questions about these opportunities from the data you receive: quote money and counts exactly as given, and never add them up yourself. Right after the card, one short sentence at most - do not repeat what it shows. On a failure, the card already says why: say so in one short sentence and stop. No emoji."
+In Agent Studio: an action with key `show_opportunities_at_risk` and no parameters. Its `instructions`: "Quote money and counts exactly as given, and never add them up yourself. No emoji."
 
 ## Adapt it
 

package/recipes/records-list/README.md

@@ -8,7 +8,7 @@ A view card: `render` takes no `callback` and the action sets no `awaitUserInput
 
 `brand.ts` here is a placeholder: keep the `agent/views/brand.ts` that `npx foldspace observe styles --write` wrote - it has every key the recipe cards read. If the project has none yet, run that command first; do not copy this one.
 
-In Agent Studio: an action with key `list_accounts` and no parameters. Its `instructions`: "Answer follow-up questions about these accounts from the data you receive: quote money and counts exactly as given, and never add them up yourself. Right after the card, one short sentence at most - do not repeat what it shows. On a failure, the card already says why: say so in one short sentence and stop. No emoji."
+In Agent Studio: an action with key `list_accounts` and no parameters. Its `instructions`: "Quote money and counts exactly as given, and never add them up yourself. No emoji."
 
 ## Adapt it
 

package/src/lint/rules.mjs

@@ -586,7 +586,7 @@ export function ruleCardContract(sourceFile, relative, findings) {
               node: flag.name,
               file: relative,
               message:
-                "A view card (render uses neither callback nor cancel) sets awaitUserInput: true. The chat panel ignores it, but in headless mode the agent then waits for a callback that never comes.",
+                "A view card (render uses none of callback, cancel or readyState) sets awaitUserInput: true. The chat panel ignores it, but in headless mode the agent then waits for a callback that never comes.",
               fix: "Remove awaitUserInput. A view card is reported to the agent as shown, with what execute returned.",
             }),
           );
@@ -600,7 +600,7 @@ export function ruleCardContract(sourceFile, relative, findings) {
               node: flag.name,
               file: relative,
               message:
-                "A view card does not need awaitUserInput: render uses neither callback nor cancel, so the agent is told the card was shown, with what execute returned.",
+                "A view card does not need awaitUserInput: render uses none of callback, cancel or readyState, so the agent is told the card was shown, with what execute returned.",
               fix: "Remove awaitUserInput.",
             }),
           );