@foldspace_npm/harness 0.1.27 → 0.1.29

package/templates/agent-starter/README.md

@@ -24,63 +24,62 @@ npm run build
 agent/
   actions/     one file per action; register actions in index.ts
   api/         one file per HTTP helper
+  views/       cards; brand.ts comes from `npx foldspace observe styles --write`
   constants.ts product, agent, and domain identifiers
-  utils.ts     Foldspace agent lookup
-docs/          optional notes for coding-agent learnings (create when needed)
+  utils.ts     configures the harness runtime; the only import surface for actions
+docs/
+  app-profile.md  what is known about this app, and how each fact was established
 foldspace.dev.json
 CLAUDE.md          imports platform instructions from the installed harness
 ```
 
-## Agent learnings
+## What is known about this app
 
-Coding agents may keep durable, repository-specific lessons under `docs/` so
-later sessions do not repeat the same mistakes. Create the folder when the first
-note is useful; do not commit an empty `docs/` directory.
-
-Good notes cover verified gotchas, failed approaches, design rationale, and
-useful verification commands. Keep them concise and evidence-based. Before
-similar work, read any relevant notes in `docs/`. Do not store secrets, cookies,
-HAR files, browser storage, or other transient session data there.
+`docs/app-profile.md` holds every fact established about this app, each with
+how it was established, and every workaround. Never store secrets, cookies, HAR
+files or browser storage there.
 
 ## Commands
 
 ```bash
-npx foldspace help # discover commands, risks, and next steps
-npm run build    # create dist/index.js
-npm run dev      # rebuild dist/index.js on changes
-npm run inject   # launch the dedicated Chrome profile
-npm run attach   # load local actions and observe the agent over CDP
-npm run attach:daemon  # same, but return after inspect_registration
+npx foldspace help                 # commands, risks, and next steps
+npm run build                      # create dist/index.js
+npm run dev                        # rebuild dist/index.js on changes
+npm run inject                     # open the test window; the human signs in there
+npx foldspace observe wait-login   # returns when they are signed in
+npx foldspace attach --daemon      # load this build into the test window
 ```
 
-Run `inject` before `attach`. Sign in to the product in the Chrome window that
-`inject` opens. To see how the product loads its data, use `npx foldspace
-observe` - it reads that same window, read-only, and works while `attach` runs.
-`inject` does not generate an application extension; `attach` loads
-`dist/index.js` directly through CDP. An empty local registry is valid,
-so you can attach before implementing handlers. Coding agents should use
-`attach --daemon` (or `npm run attach:daemon`) so the command returns after
+Run `inject` before `attach`. `npx foldspace observe` reads the test window,
+read-only, and works while `attach` runs. `attach` loads `dist/index.js` into
+the page over CDP; an empty registry is valid, so attach before any handler
+exists. Run it as `npx foldspace attach --daemon`: it returns after
 registration instead of occupying the terminal.
 
-Choose the attach mode from the state of the target page:
+The attach mode is read off the page:
 
 - Default swap: the page already has the configured product and agent.
-- `npm run attach -- --bootstrap`: the page has no Foldspace SDK.
-- `npm run attach -- --replace`: the page has a different product or agent, or
-  an SDK without the configured agent.
+- `npx foldspace attach --bootstrap --daemon`: the page has no Foldspace SDK.
+- `npx foldspace attach --replace --daemon`: the page has a different product
+  or agent, or an SDK without the configured agent.
 
 Run `npx foldspace help attach` for full requirements and safety options. Coding
 agents can read the versioned contract with `npx foldspace help --json`.
 
 ## Add an action
 
-1. Observe the real product workflow in the inject Chrome and capture a real
-   200 for the API the action will call.
-2. Create the action as a draft in Agent Studio or through Product MCP.
+1. Once the human has chosen the experience, observe what it needs in the
+   test window (`npx foldspace observe screen`, then `read`) and capture a
+   real 200 for the API the action will call.
+2. Create the action as a draft with the Foldspace tools (`create_action`).
 3. Copy `agent/actions/_example.ts` to `agent/actions/<action_key>.ts`.
 4. Implement the handler from that observed request and response.
 5. Import and register the handler in `agent/actions/index.ts`.
-6. Type-check, rebuild, `attach --daemon`, and verify it through the visible
-   agent. Publish only when the copilot must call the action.
+6. Type-check and rebuild; if attach is running, `npx foldspace attach --stop`,
+   then `npx foldspace attach --daemon` with the flags it ran with. Ask the human
+   before publishing - the agent cannot call the action until it is published.
+   On a yes, publish it and prove it with
+   `npx foldspace ask "<question>" --retry 2`; on a not yet, it stays a draft:
+   say so in one line.
 
 Action keys and parameter names must exactly match the action schema.

package/templates/agent-starter/agent/actions/_example.ts

@@ -17,9 +17,9 @@ export const example_action = {
 
     const result = await apiFetch<{ items?: Item[] }>("/__observe_me");
     if (!result.ok) {
-      // Pass `reason` through so `render` can call renderFailure — an expired
-      // session, a 404 and a throttled call are three different widget states.
-      return { ok: false, error: result.error, reason: result.reason };
+      // Pass `reason` through so `render` can call renderFailure - an expired
+      // session, a 404 and a throttled call are three different card states.
+      return { success: false, error: result.error, reason: result.reason };
     }
 
     const items = result.data.items ?? [];
@@ -30,6 +30,6 @@ export const example_action = {
 
     // Zero matches is an answer, not an error. Return the query so the empty
     // state can name what was searched for.
-    return { ok: true, query, matches };
+    return { success: true, query, matches };
   },
 };

package/templates/agent-starter/agent/actions/index.ts

@@ -2,9 +2,9 @@
 //
 // Registration here is the switch: the SDK transmits these to the server, and
 // the server excludes any active action it does not receive. Comment an entry
-// out and the copilot can no longer see it — no unpublishing required.
+// out and the agent can no longer see it - no unpublishing required.
 //
-// LOAD_MODE "injected" publishes the registry for attach to swap. "embedded"
+// LOAD_MODE "injected" puts the registry on window for attach to swap. "embedded"
 // skips that assignment because the host page already loads Foldspace.
 
 import { LOAD_MODE } from "../constants";

package/templates/agent-starter/agent/constants.ts

@@ -13,8 +13,9 @@ export const API_BASE = "";
  * `{ kind: "localStorage", name: "access_token" }` or
  * `{ kind: "cookie", name: "session" }`.
  *
- * Custom headers that are not Bearer belong in a local `apiFetch` override —
- * see CLAUDE.md. Do not guess this value.
+ * Auth that is not Bearer (a custom header, or cookies with no token) needs
+ * its own `apiFetch` - see "Custom auth" in `agent/utils.ts`. Do not guess
+ * this value.
  */
 export const AUTH_SOURCE:
   | { kind: "localStorage" | "cookie"; name: string }
@@ -22,7 +23,7 @@ export const AUTH_SOURCE:
 
 /**
  * "injected" assigns `window.__FOLDSPACE_REMOTE_ACTIONS__` so attach can swap
- * the bundle. "embedded" does not — the page already publishes handlers
+ * the bundle. "embedded" does not - the page already registers handlers
  * through its own SDK snippet.
  */
 export const LOAD_MODE: "injected" | "embedded" = "injected";

package/templates/agent-starter/agent/utils.ts

@@ -11,8 +11,8 @@
  * ## What `export *` gives you
  *
  * HTTP (customer API, from the signed-in page):
- * - `apiFetch` — JSON + `Authorization: Bearer`. Stop re-exporting this if
- *   the live app uses cookies, custom headers, or no Bearer (see below).
+ * - `apiFetch` - JSON + `Authorization: Bearer`. For any other sign-in, see
+ *   "Custom auth" below.
  * - `apiFetchBinary` — same auth, raw bytes (file download).
  * - `publicFetch` — no token; marketing / public origin only.
  * - `getAuthToken` / `parseJwt` / `redact` — session read and safe logging.
@@ -21,11 +21,11 @@
  * Foldspace SDK (thin wrappers; the SDK is the source of truth):
  * - `getAgent` — overlay handle for `searchInList` and similar.
  * - `rankBy` — substring first, then SDK fuzzy match. Not for domain ranking.
- * - `armAllInstances` — **attach/bootstrap only**, never from `execute`.
- *   Local `foldspace attach` already arms test mode. Importing this from an
- *   action can put those SDK calls in the production `dist` bundle.
+ * - `armAllInstances` - never in agent code: attach handles the page, and
+ *   test mode is `npx foldspace attach --test-mode`, only for an agent that
+ *   already has real users. Anything in `agent/` ships to production.
  *
- * Widget chrome (unstyled; replace in `agent/views/` when brand matters):
+ * Card states (unstyled; replace in `agent/views/` when brand matters):
  * - `renderLoading` / `renderEmpty` / `renderError` / `renderFatal`
  * - `renderFailure` — picks one of those from `ApiFailure.reason`, so an expired
  *   session, a 404 and a throttled call each draw the right state.
@@ -36,20 +36,17 @@
  * Leave `API_BASE` and `AUTH_SOURCE` empty in `constants.ts` until you capture
  * a real XHR. Empty config makes `apiFetch` return `{ ok: false }` instead of
  * guessing a host. Errors are returned, never thrown; show `result.error` in
- * the widget and log `result.detail` only.
+ * the card and log `result.detail` only.
  *
- * ## Override example (custom auth — do not guess Bearer)
+ * ## Custom auth (not Bearer)
  *
- * ```ts
- * import { configure, apiFetch as defaultApiFetch, ... } from "@foldspace_npm/harness/runtime";
- * // After configure(...):
- * export async function apiFetch<T>(path: string, init: RequestInit = {}) {
- *   // observe the live request first, then copy its headers here
- *   return defaultApiFetch<T>(path, { ...init, headers: { ... } });
- * }
- * export { getAgent, rankBy, renderEmpty, renderError, renderFatal, renderLoading };
- * // Do not `export *` if that would re-export the default apiFetch.
- * ```
+ * Read `node_modules/@foldspace_npm/harness/recipes/swap-the-login-method/README.md`
+ * and copy over this file the variant it names for what the app's requests
+ * carry: `agent/utils.ts` for a custom header, `variants/utils.cookies.ts` for
+ * cookies with no token. Each defines its own `apiFetch`, keeps the harness's
+ * failure `reason`s through `httpFailure` / `networkFailure`, and re-exports
+ * the other helpers by name - keep it that way: an `export *` would also bring
+ * in helpers such as `apiFetchBinary` that still use the default sign-in.
  */
 
 import { configure } from "@foldspace_npm/harness/runtime";

package/templates/agent-starter/claude-settings.json

@@ -1,5 +1,5 @@
 {
-  "$comment": "Written by foldspace init. The commands a build runs, allowed up front so the coding agent is not stopped one denial at a time mid-build. Named one by one on purpose: init, upgrade and deploy are not here and still ask. Everything else still asks.",
+  "$comment": "Written by foldspace init: the commands a build runs, allowed up front so the coding agent is not stopped one denial at a time. init and upgrade are left out on purpose, so they ask, like anything not listed. foldspace deploy is Foldspace-internal and never runs in a build.",
   "permissions": {
     "allow": [
       "Bash(npx foldspace help:*)",

package/templates/agent-starter/docs/app-profile.md

@@ -3,9 +3,10 @@
 Durable facts about `{{APP_DOMAIN}}` and its API, established by observing the
 running app on **<date>** from a logged-in session.
 
-**Everything here should be observed.** Each entry says how. Where something is
-only believed, say so in the same breath — do not promote an assumption by
-quoting this file. Re-run the probe before trusting an entry that matters.
+**Every entry says how it was established.** Where something is only
+believed, mark it **assumed** in the same breath - do not promote an
+assumption by quoting this file. Re-run the probe before trusting an entry
+that matters.
 
 Do not store secrets, cookies, HAR files, tokens, or session data here. Record
 *where* the token lives and *what a redacted value looks like*, never the value.
@@ -13,9 +14,9 @@ Do not store secrets, cookies, HAR files, tokens, or session data here. Record
 How to re-run any probe below:
 
 ```bash
-npm run inject
-# Sign in, then read the running app with foldspace observe. It reads the
-# window you signed in to, and works while foldspace attach runs.
+npm run inject   # only if the test window is closed; the human signs in there
+npx foldspace observe wait-login
+# observe reads the test window, and works while attach runs.
 npx foldspace observe screen --click "<a label from observe menu>" --match "<words for the data>"
 npx foldspace observe read "<the GET path screen returned>"
 ```
@@ -27,9 +28,9 @@ Start URL: `{{START_URL}}`
 ## Auth
 
 - Where the token lives (cookie name, `localStorage` key, custom header), and
-  how you know — wrapping XHR/`fetch` on the live page beats guessing.
-- Its lifetime, measured. (One app's expired in ~52 minutes and killed three
-  probing sessions.)
+  how you know: `npx foldspace observe auth` reports where each header value
+  comes from, never the value.
+- Its lifetime, measured: a short one ends probing sessions halfway.
 - What an expired or refused response looks like, verbatim. A CORS-less refusal
   often surfaces as `TypeError: Failed to fetch` with no status — that is not
   "host down".
@@ -43,8 +44,11 @@ Start URL: `{{START_URL}}`
 
 ## Account contents
 
-Row counts from the signed-in account **before** choosing the experience. On an
-empty account the only useful first action is one that creates data.
+Row counts for the experience being built, checked when you observe it. Zero
+rows makes a demo of an empty state: say so and offer the next experience. On
+an account with nothing to read at all, say so and offer first a card that
+creates a record when the end user approves
+(`node_modules/@foldspace_npm/harness/recipes/create-a-record`).
 
 | Resource | Count | How established |
 |---|---|---|
@@ -93,9 +97,10 @@ Mark which you verified and which came from reading the app bundle.
 
 ## Brand (sampled, not guessed)
 
-Colour, typeface, greys, base size and radii from the running app's computed
-styles — not from a screenshot. Re-sample per tenant; do not carry values
-across.
+`npx foldspace observe styles --write` samples the app's accent, text, border,
+font and radius and writes `agent/views/brand.ts`. Record here the page and
+date it sampled, and anything it fell back on. Re-sample per product; never
+copy values across.
 
 ## Endpoints seen in the bundle but NOT called
 

package/templates/agent-starter/foldspace.dev.json

@@ -1,5 +1,5 @@
 {
-  "$comment": "Generated by foldspace init. Use the bare product ID, not the EU-… SDK key.",
+  "$comment": "Generated by foldspace init. Use the bare product ID, not the SDK key (the one that starts with EU-, in every region).",
   "defaultTarget": "app",
   "region": {{REGION_JSON}},
   "sdkUrl": {{SDK_URL_JSON}},

package/recipes/several-hosts/fixtures/nav-record.json

@@ -1,5 +0,0 @@
-{
-  "payload": { "conversationId": "conv_123", "actionName": "navigate" },
-  "normalizedUrl": "https://communicate.example-campus.net/applications/acme/test",
-  "expiry": 9999999999999
-}