@foldspace_npm/harness 0.1.13 → 0.1.14

package/CLAUDE.md

@@ -64,6 +64,12 @@ current CLI contract — risk, prerequisites, effects, next step.
    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>."*
+
 Navigation, uploads, extraction and anything that writes are a later session.
 
 ### Ask as a choice, and ask almost nothing
@@ -76,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
@@ -111,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 |
 |---|---|---|---|
@@ -269,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`),
@@ -337,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.13",
+  "version": "0.1.14",
   "description": "Build and verify portable Foldspace action artifacts against a live app.",
   "type": "module",
   "bin": {