@foldspace_npm/harness 0.1.30 → 0.1.31

package/CLAUDE.md

@@ -29,8 +29,8 @@ session ends at something they can **see on their own page** - not at
 
    | Result | Do |
    |---|---|
-   | The tool does not exist | The Foldspace MCP is not installed in this editor. Install it yourself, the one way that fits *this* region and editor. **EU** - any editor: the MCP block on <https://foldspace.ai/eu/agents.md>, never the plugin. **US** - Claude Code with git on the machine (`command -v git`): `claude plugin marketplace add https://github.com/foldspace-ai/plugins` (already added, or added from another source, is fine), then `claude plugin install foldspace-agent-builder@foldspace-plugins`; without git, or any other editor: the MCP block on <https://foldspace.ai/agents.md>. Either way it needs sign-in: start it before your turn ends, as **Connect Foldspace tools** on that page says. **The plugin** loads when your turn ends: call `list_agents` again on the human's next message. **A server added from the MCP block** (`claude mcp add`) never reaches a chat that is already running - not on the next message, not through `/mcp`: once it is signed in, the human opens a new chat in this folder and repeats their request. `claude mcp get` saying Connected proves only the setting; the check is `list_agents` in the chat you are in |
-   | 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-eu** (**EU**) or **foldspace** (**US**; listed as `plugin:foldspace-agent-builder:foldspace` when the plugin installed it) → finish in the browser - then check again. If `/mcp` does not list that server, it was added after this chat started: the human opens a new chat in this folder, as above |
+   | The tool does not exist | The Foldspace MCP is not installed in this editor. Install it yourself, the one way that fits *this* region and editor. **EU** - any editor: the MCP block on <https://foldspace.ai/eu/agents.md>, never the plugin. **US** - Claude Code with git on the machine (`command -v git`): `claude plugin marketplace add https://github.com/foldspace-ai/plugins` (already added, or added from another source, is fine), then `claude plugin install foldspace-agent-builder@foldspace-plugins`; without git, or any other editor: the MCP block on <https://foldspace.ai/agents.md>. Either way it needs sign-in: start it before your turn ends, as **Connect Foldspace tools** on that page says. **The plugin** loads when your turn ends: call `list_agents` again on the human's next message. **A server added from the MCP block** (`claude mcp add`) never reaches a chat that is already running - not on the next message, not through `/mcp`: once it is signed in, the human opens a new chat in this folder and repeats their request. `claude mcp get` saying Connected proves only the setting; the check is `list_agents` in the chat you are in. **Codex**: `codex mcp add foldspace --url https://api.foldspace.ai/mcp` (**EU**: `foldspace-eu` and `https://api.eu.foldspace.ai/mcp`) adds it and starts sign-in in one step; a server added during a thread never reaches that thread, so once it is signed in the work continues in a new thread in this folder: start it yourself if Codex gives you a tool for it - the human's request word for word, plus the one paragraph the playbook's Codex block gives - and say so in one line; otherwise the human starts it and repeats their request. **Cursor**: merge the server into `~/.cursor/mcp.json` yourself, keeping every other server; it reaches this chat on the human's next message, needing sign-in. **Any editor**: never read a saved sign-in or credentials file, and never reach the Foldspace MCP any other way (curl, a script, a client you write). If its tools are not in this chat, the fix is a new chat |
+   | 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-eu** (**EU**) or **foldspace** (**US**; listed as `plugin:foldspace-agent-builder:foldspace` when the plugin installed it) → finish in the browser - then check again. If `/mcp` does not list that server, it was added after this chat started: the human opens a new chat in this folder, as above. Codex: run `codex mcp login foldspace` (`foldspace-eu` for **EU**) - if the browser does not open, give the human the link it prints - then a new thread. Cursor: call the server's own sign-in tool, `mcp_auth`, yourself - the human finishes in the browser - then `list_agents` in this same chat |
    | 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`,
@@ -162,7 +162,7 @@ Uploads and extraction 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 asks only
+option first** (in Claude Code, `AskUserQuestion`; elsewhere, the editor's own question tool), asked once - not repeated in your message. A first session asks only
 this: which agent (only if several), the app's hostname, which experience
 first - and a yes wherever this manual asks for one, such as agreeing the
 experience (below), upgrading, publishing an action, task agent or
@@ -794,6 +794,18 @@ import is right.
   `Bash(npx foldspace observe:*)` - and meanwhile hand that step to them: for
   a chat turn, that is them typing the question into the panel. `init`,
   `upgrade` and `deploy` ask on purpose: never give an allow rule for them.
+- **A sandbox error is not a refusal.** Some editors (Codex) run your commands
+  in a sandbox: no network, and no writes outside this folder, unless the
+  human approves that one command. There `npm`, `npx foldspace`, `inject` and
+  anything that reaches the test window fail with errors that look like
+  something else - a host that cannot be resolved, `EPERM` in npm's cache,
+  `listen EPERM`, Chrome quitting, or *the test window is closed*. Ask to run
+  that same command outside the sandbox through the editor's own approval,
+  with one plain line on why; that approval is not a retry. Never move npm's
+  cache, change file ownership, or have the human run the command instead.
+  An approval can expire when the human sends a new message, so after one,
+  the same errors mean ask again - not that the window closed. If the human
+  declines, that is a refusal: the rule above applies.
 - **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

package/package.json

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

package/templates/agent-starter/AGENTS.md

@@ -0,0 +1,24 @@
+# Foldspace actions for {{APP_DOMAIN}}
+
+This folder builds a Foldspace agent for {{APP_DOMAIN}}. Its manual is
+`node_modules/@foldspace_npm/harness/CLAUDE.md` - written for every coding
+agent, whatever the file name says.
+
+**Read that manual in full before anything else**, and follow it from **Every
+session starts the same way**. It is long: read it in parts of about 250 lines
+until you reach its last line, because a tool that cuts long output short has
+not shown you all of it. If the file is missing, run
+`npm install --ignore-scripts` first. Run every command from this folder, even
+when your chat started somewhere else. What follows is only what is true of
+**this** product.
+
+## This product
+
+| | |
+|---|---|
+| Agent Key | `{{AGENT_API_NAME}}` |
+| Product ID | `{{PRODUCT_ID}}` |
+| App | `{{APP_DOMAIN}}` |
+
+What is known about this app, and how each fact was established, is in
+`docs/app-profile.md`.