@foldspace_npm/harness 0.1.26 → 0.1.28

package/src/region.mjs

@@ -7,7 +7,7 @@
 // points at that region's agent, recording and tracking hosts - the US SDK on
 // an EU page talks to a US backend that does not have the EU agents.
 //
-// `server`: the Product MCP's name in the editor, as the region's playbook
+// `server`: the Foldspace tools' server name in the editor, as the region's playbook
 // installs it. Distinct per region, so both can sit side by side.
 export const REGIONS = Object.freeze({
   us: Object.freeze({

package/src/runtime/agent.ts

@@ -6,7 +6,7 @@ let cached: any | null = null;
  * Foldspace SDK handle for this agent's **overlay** instance.
  *
  * Takes no `mode` on purpose: `foldspace.agent({ apiName })` returns the overlay
- * handle. On an app that embeds the copilot in-page that is not the instance
+ * handle. On an app that embeds the agent in-page that is not the instance
  * serving the chat, so arming only it succeeds and leaves real conversations
  * untagged. For a specific instance, enumerate `window.foldspace.agentIds()`
  * (`"<mode>-<apiName>"`) and call `foldspace.agent({ apiName, mode })`.
@@ -25,20 +25,24 @@ export function getAgent(): any | null {
 }
 
 /**
- * Arm every Foldspace instance on the page for test mode and remote actions.
+ * Turns test mode on or off (`testMode`) on every Foldspace instance on the
+ * page (`window.foldspace.agentIds()`) and turns on their remote actions: SDK
+ * `setTestMode(testMode)` and `setConfiguration({ remoteActionsSettings })`.
  *
- * Calls SDK `setTestMode` and `setConfiguration({ remoteActionsSettings })`.
- * Local `foldspace attach` already injects test-mode arming without putting it
- * in `dist/index.js`. Prefer that. Importing this helper from an action can
- * ship those calls into the production CDN bundle.
+ * It does not belong in agent code: any file in `agent/` can ship to
+ * production, where test mode would stop real users' conversations being
+ * tracked. Leave it out even with `false`, which lint refuses too: it still
+ * calls `setConfiguration` on every instance, and a partial `setConfiguration`
+ * can shrink the agent's panel to 0×0. Test mode is only for an agent that
+ * already has real users, and only through `npx foldspace attach --test-mode`,
+ * which never touches the bundle. For an agent with no real users yet, leave
+ * test mode off.
  *
- * Do not call from `execute`. Partial `setConfiguration` has collapsed the
- * widget to 0×0 in a real build.
- *
- * @param testMode - When true, mark conversations as test traffic
- * @returns Instance ids that armed vs failed
+ * @param testMode - `true` marks new conversations on this page as test
+ *   traffic; `false` (the default) turns that off.
+ * @returns The instance ids it set (`armed`) and the ones that threw (`failed`)
  */
-export function armAllInstances(testMode = true): {
+export function armAllInstances(testMode = false): {
   armed: string[];
   failed: string[];
 } {

package/src/runtime/http.ts

@@ -96,16 +96,17 @@ export interface ApiSuccess<T> {
 /**
  * Failed request. Errors are **returned**, never thrown.
  *
- * Show `error` to a person. Log `detail` to the console only — never put
- * `detail` in an action return value; Foldspace may quote that to the user.
+ * Show `error` to a person. Log `detail` to the console only - never put
+ * `detail` in an action return value; the agent may quote it to the end user.
  *
  * `unreachable` is true when the browser never got a response (DNS, CORS,
  * offline, connection refused). Timeouts set `unreachable: false` and
  * `error: "Request timed out."`. Empty `API_BASE` / `AUTH_SOURCE` also
- * return `{ ok: false }` with status 0 — they do not throw.
+ * return `{ ok: false }` with status 0 - they do not throw: `reason: "config"`,
+ * `error: "This is not set up yet."`, and which setting is missing in `detail`.
  *
  * Branch on `reason`, not on `status`: a search that finds nothing, an expired
- * session and a throttled call are three different widget states, and
+ * session and a throttled call are three different card states, and
  * `renderFailure` picks the right one for you.
  */
 export interface ApiFailure {
@@ -121,7 +122,7 @@ export interface ApiFailure {
   status: number;
   /** Safe, user-facing sentence. Pass this to `renderError`. */
   error: string;
-  /** Truncated API body for the console. Never show this in the widget. */
+  /** For the console only: the API's body (truncated), or which setting is missing. Never show this in the card. */
   detail?: string;
   /**
    * True when the network itself failed (not HTTP 4xx/5xx, not abort).
@@ -131,7 +132,7 @@ export interface ApiFailure {
 }
 
 /**
- * Why a call failed, in terms a widget can act on.
+ * Why a call failed, in terms a card can act on.
  *
  * - `signed_out` — no token on the page, or the API answered 401. The session
  *   observed at build time is not the session at run time; expect this.
@@ -155,6 +156,11 @@ export type FailureReason =
 /** Discriminated result of a customer-API call. Branch on `ok`. */
 export type ApiResult<T> = ApiSuccess<T> | ApiFailure;
 
+// What reaches the agent and the card when the build is not configured yet:
+// a state, never a developer instruction. The developer hint is in `detail`,
+// for the console only: nothing shows it unless the handler logs it.
+const NOT_SET_UP = "This is not set up yet.";
+
 function missingConfigResult(): ApiResult<never> | null {
   const config = getConfig();
   if (!config.apiBase) {
@@ -162,7 +168,8 @@ function missingConfigResult(): ApiResult<never> | null {
       ok: false,
       status: 0,
       reason: "config",
-      error: "API_BASE is not set — capture the app's XHR first.",
+      error: NOT_SET_UP,
+      detail: "API_BASE is not set - capture the app's XHR first.",
     };
   }
   if (!config.authSource) {
@@ -170,7 +177,8 @@ function missingConfigResult(): ApiResult<never> | null {
       ok: false,
       status: 0,
       reason: "config",
-      error: "AUTH_SOURCE is not set — capture the app's session first.",
+      error: NOT_SET_UP,
+      detail: "AUTH_SOURCE is not set - capture the app's session first.",
     };
   }
   return null;
@@ -196,7 +204,7 @@ function retryAfterMs(res: Response): number | undefined {
 }
 
 /**
- * One mapping from HTTP status to a failure a widget can act on.
+ * One mapping from HTTP status to a failure a card can act on.
  *
  * Exported for a tenant's own `apiFetch` — an app that authenticates with a
  * custom header or cookies replaces the transport, and should not also have to
@@ -206,7 +214,7 @@ export function httpFailure(res: Response, fallback: string, detail?: string): A
   const base = { ok: false as const, status: res.status, detail };
   switch (res.status) {
     case 401:
-      return { ...base, reason: "signed_out", error: "Your session expired. Sign in again." };
+      return { ...base, reason: "signed_out", error: "Your session has expired." };
     case 403:
       return { ...base, reason: "forbidden", error: "You do not have access to that." };
     case 404:
@@ -216,7 +224,7 @@ export function httpFailure(res: Response, fallback: string, detail?: string): A
         ...base,
         reason: "rate_limited",
         retryAfterMs: retryAfterMs(res),
-        error: "Too many requests. Try again in a moment.",
+        error: "Too many requests right now.",
       };
     default:
       return { ...base, reason: "server", error: fallback };
@@ -245,9 +253,10 @@ const SIGNED_OUT: ApiFailure = {
 /**
  * Authenticated JSON request against `apiBase` with `Authorization: Bearer`.
  *
- * Matches the common pattern (two of three early builds). If the live page
- * uses cookies, custom headers, or no Bearer, **stop re-exporting this** from
- * `agent/utils.ts` and write a local `apiFetch` instead.
+ * For an app whose own requests carry `Authorization: Bearer`. If the live
+ * page sends something else (a custom header, or cookies with no token),
+ * follow `recipes/swap-the-login-method/README.md`: it names the file to copy
+ * over `agent/utils.ts` for each case.
  *
  * Empty `API_BASE` / `AUTH_SOURCE` return `{ ok: false }` so a guessed host
  * cannot look like success. Errors never throw and never include the token.
@@ -401,7 +410,8 @@ export async function publicFetch<T = unknown>(
       ok: false,
       status: 0,
       reason: "config",
-      error: "No public origin is configured for this app.",
+      error: NOT_SET_UP,
+      detail: "No public origin is set - pass one to publicFetch, or set publicOrigin in configure().",
     };
   }
   const controller = new AbortController();

package/src/runtime/match.ts

@@ -41,7 +41,7 @@ const PLAUSIBLE = 0.45;
  * SDK method degrades the result rather than breaking the action.
  *
  * @param items - Records already loaded (e.g. from {@link apiFetch})
- * @param query - What the user typed
+ * @param query - What the end user typed
  * @param opts - Fields, identity, optional limit
  * @returns Up to `limit` items, substring matches first
  */

package/src/runtime/render.ts

@@ -1,5 +1,5 @@
 /**
- * Unstyled chatterblock states. Tenant brand belongs in `agent/views/`.
+ * Unstyled card states. Tenant brand belongs in `agent/views/`.
  *
  * An action's `render` output cannot be typechecked. Look at a frame. Never
  * use `innerHTML` with API data.
@@ -38,7 +38,7 @@ function replace(host: ViewHost, node: HTMLElement): void {
 }
 
 /**
- * In-progress chatterblock. Unstyled scaffolding — replace with branded UI
+ * In-progress card. Unstyled scaffolding - replace with branded UI
  * when the card is the experience.
  *
  * @param host - Foldspace `render` host
@@ -60,8 +60,8 @@ export function renderEmpty(host: ViewHost, message: string): void {
 }
 
 /**
- * Recoverable error: the user can retry or narrow. Pass `ApiResult.error`,
- * never `detail` — `detail` is the API's own words and is for the console.
+ * Recoverable error: the end user can retry or narrow. Pass `ApiResult.error`,
+ * never `detail` - it is for the console.
  *
  * @param host - Foldspace `render` host
  * @param message - Safe, user-facing sentence

package/src/transports/README.md

@@ -6,7 +6,7 @@ The harness does the same three jobs regardless of where the browser is:
 
 Track A (`local`) does them over CDP against a browser on this machine.
 Track B (`extension`) will do them over a websocket to a Web Store extension in
-the user's own Chrome.
+the human's own Chrome.
 
 `agent/`, `fixtures/` and the build are identical in both — only this layer
 differs. Keep it that way: "export to repo" from a hosted build is a copy only
@@ -21,4 +21,4 @@ while the two tracks share an identical `agent/` directory.
 | `navigate` | `Page.navigate` | `tabs.update` |
 
 `local` is implemented today as `bin/inject.mjs` + `bin/attach.mjs`.
-`extension` is not built; see `architecture-hosted.md`.
+`extension` is not built.

package/src/upgrade.mjs

@@ -9,7 +9,7 @@ export const HARNESS_PACKAGE = "@foldspace_npm/harness";
 export const INSTRUCTION_IMPORT = `@node_modules/${HARNESS_PACKAGE}/CLAUDE.md`;
 export const CACHE_TTL_MS = 12 * 60 * 60 * 1000;
 export const NPM_VIEW_TIMEOUT_MS = 2000;
-export const UPGRADE_NEXT = "Ask the user, then run foldspace upgrade --yes";
+export const UPGRADE_NEXT = "Ask the human, then run npx foldspace upgrade --yes";
 
 const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const instructionTemplatePath = path.join(
@@ -267,11 +267,11 @@ function nextAction(report) {
   }
   if (report.status === "outdated") {
     return report.instructionsImport === false
-      ? `${UPGRADE_NEXT}. If CLAUDE.md is still a snapshot, also pass --refresh-instructions`
+      ? "CLAUDE.md does not import the package instructions. Ask the human, then run npx foldspace upgrade --yes --refresh-instructions (the old CLAUDE.md is kept as CLAUDE.md.bak)."
       : UPGRADE_NEXT;
   }
   if (report.status === "upgraded") {
-    return "Run npm run build. Deploy only if product users should receive the rebuilt runtime.";
+    return "Run `npm run build`. If attach is running, run `npx foldspace attach --stop`, then `npx foldspace attach --daemon` with the flags it ran with, to load the rebuild.";
   }
   return null;
 }
@@ -311,8 +311,14 @@ export function checkForUpdate(projectDir, options = {}) {
     // new answer down. `foldspace upgrade` is always fresh: someone asking to
     // upgrade minutes after a release was told the previous version was the
     // latest, for up to 12 hours (seen 2026-09-28).
+    // `preferFresh` (help --json, which the manual reads first) asks the
+    // registry too, but falls back to the remembered answer when the registry
+    // cannot be reached, so an offline session still hears something.
+    const preferFresh = options.preferFresh === true;
     const cached =
-      options.cache === false || options.fresh === true ? null : readCache(projectDir, now);
+      options.cache === false || options.fresh === true || preferFresh
+        ? null
+        : readCache(projectDir, now);
     const cachedDeprecation =
       cached?.deprecation?.version === running ? cached.deprecation : null;
     if (cached?.latest && cachedDeprecation) {
@@ -329,12 +335,25 @@ export function checkForUpdate(projectDir, options = {}) {
           ? options.fetchDeprecation(running)
           : fetchDeprecationFromNpm(running, options);
       deprecated = message || null;
-      if (latest && options.cache !== false) {
-        const entry = { latest };
+      // Each of the two answers falls back on its own: the version can arrive
+      // while the withdrawn-version check times out, and that warning is the
+      // one step 1 must not lose.
+      const fetchedLatest = latest;
+      const remembered = preferFresh && options.cache !== false ? readCache(projectDir, now) : null;
+      const rememberedDeprecation =
+        remembered?.deprecation?.version === running ? remembered.deprecation : null;
+      if (!fetchedLatest && remembered?.latest) latest = remembered.latest;
+      if (typeof message !== "string" && rememberedDeprecation) {
+        deprecated = rememberedDeprecation.message || null;
+      }
+      if (fetchedLatest && options.cache !== false) {
+        const entry = { latest: fetchedLatest };
         // Only cache an answer the registry actually gave, so an offline
         // run is asked again next time instead of remembered as "fine".
         if (typeof message === "string") {
           entry.deprecation = { version: running, message };
+        } else if (rememberedDeprecation) {
+          entry.deprecation = rememberedDeprecation;
         }
         writeCache(projectDir, entry, now);
       }
@@ -367,7 +386,7 @@ export function checkForUpdate(projectDir, options = {}) {
 /**
  * What `build` and `attach` do with an update report before they run:
  * `block: true` stops the command, `message` (if any) is printed to stderr.
- * Never upgrades - that stays the user's decision (CLAUDE.md, step 1).
+ * Never upgrades - that stays the human's decision (CLAUDE.md, step 1).
  * The escape hatch is FOLDSPACE_SKIP_UPDATE_CHECK=1: the report comes back
  * check_skipped, so nothing here blocks.
  */
@@ -379,7 +398,7 @@ export function gateForCommand(report) {
       block: true,
       message:
         `${HARNESS_PACKAGE} ${report.installed || report.pinned} was withdrawn: ${report.deprecated}. ` +
-        `${UPGRADE_NEXT}. If the user declines, rerun with FOLDSPACE_SKIP_UPDATE_CHECK=1 to build on this version anyway.`,
+        `${UPGRADE_NEXT}. If the human declines, rerun with FOLDSPACE_SKIP_UPDATE_CHECK=1 to run this version anyway.`,
     };
   }
   if (report.outdated) {
@@ -487,10 +506,14 @@ export async function runUpgrade(argv, options = {}) {
     log(
       `${HARNESS_PACKAGE} ${report.pinned || report.installed} -> ${report.latest} is available`,
     );
-    const answer = await ask("Upgrade the exact pin in this project? [Y/n] ", options);
+    const answer = await ask("Upgrade the version this project uses? [Y/n] ", options);
     shouldInstall = isAffirmative(answer);
     if (!shouldInstall) {
-      return { ...report, status: "declined", next: UPGRADE_NEXT };
+      // The answer was no: asking again is not the next step.
+      const next = report.broken
+        ? "The human declined: do not ask again this session. This version is withdrawn, so build and attach refuse it; run them with FOLDSPACE_SKIP_UPDATE_CHECK=1."
+        : "The human declined: carry on with this version, and do not ask again this session.";
+      return { ...report, status: "declined", next };
     }
     if (!report.instructionsImport && !shouldRefresh) {
       const refreshAnswer = await ask(

package/templates/agent-starter/CLAUDE.md

@@ -2,15 +2,18 @@
 
 @node_modules/@foldspace_npm/harness/CLAUDE.md
 
-If that import did not resolve, read `node_modules/@foldspace_npm/harness/CLAUDE.md`
-before building. What follows is only what is true of **this** product.
+That import is the manual for this build. If it did not resolve, read
+`node_modules/@foldspace_npm/harness/CLAUDE.md` before anything else; if that
+file is missing too, run `npm install --ignore-scripts` first. What follows is
+only what is true of **this** product.
 
 ## This product
 
 | | |
 |---|---|
-| Agent | `{{AGENT_API_NAME}}` |
-| Product | `{{PRODUCT_ID}}` |
+| Agent Key | `{{AGENT_API_NAME}}` |
+| Product ID | `{{PRODUCT_ID}}` |
 | App | `{{APP_DOMAIN}}` |
 
-Observed API, auth, and account facts for this app live in `docs/app-profile.md`.
+What is known about this app, and how each fact was established, is in
+`docs/app-profile.md`.

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:*)",
@@ -10,6 +10,7 @@
       "Bash(npx foldspace observe:*)",
       "Bash(npx foldspace ask:*)",
       "Bash(npx foldspace badge:*)",
+      "Bash(npx foldspace published:*)",
       "Bash(npm install:*)",
       "Bash(npm run build:*)",
       "Bash(npm run typecheck:*)",