@foldspace_npm/harness 0.1.27 → 0.1.29

package/src/observe-core.mjs

@@ -44,7 +44,7 @@ export function isSameSite(url, pageUrl, hosts = []) {
 }
 
 /**
- * One product often lives on several hosts (www., analyze., admin. ...), and a
+ * One product often lives on several hosts (www., reports., admin. ...), and a
  * project only works on the hosts it names. Given addresses seen from a page,
  * say which hosts look like the same product but are NOT covered, and the one
  * pattern that would cover them. The site is an approximation (see siteOf), so
@@ -81,7 +81,7 @@ export function uncoveredSiblings(urls, pageUrl, hosts = []) {
     hint:
       `This product also lives on ${found.slice(0, 4).map((entry) => entry.host).join(", ")}` +
       `${found.length > 4 ? ` and ${found.length - 4} more` : ""}, which this project does not cover. ` +
-      `To work there, add "${pattern}" to "hosts" in foldspace.dev.json - with the human's yes - then run inject and attach again.`,
+      `To work there, add "${pattern}" to "hosts" in foldspace.dev.json - with the human's yes - then \`npx foldspace attach --stop\`, \`npm run inject\` and \`npx foldspace attach --daemon\` with the flags it ran with.`,
   };
 }
 
@@ -132,7 +132,7 @@ export function gotoDestination(input, pageUrl, hosts = []) {
     throw new Error(
       `--goto: ${target.hostname} is not one of this project's hosts (${hosts.join(", ") || "none named"}). ` +
         (coverage.pattern
-          ? `If it is part of the product, add "${coverage.pattern}" to "hosts" in foldspace.dev.json - with the human's yes - then run inject and attach again.`
+          ? `If it is part of the product, add "${coverage.pattern}" to "hosts" in foldspace.dev.json - with the human's yes - then \`npx foldspace attach --stop\`, \`npm run inject\` and \`npx foldspace attach --daemon\` with the flags it ran with. If it is not, --goto a screen on this project's hosts.`
           : "observe only opens screens of the product this project is for."),
     );
   }
@@ -398,6 +398,11 @@ export function rankCandidates(candidates, words = [], max = 8) {
 
 const WRITE_FLAGS = ["method", "data", "body", "header", "headers", "json", "post", "put", "delete"];
 
+/** True for an option that would make `observe read` write (`--method`, `--body`, ...). */
+export function isWriteFlag(option) {
+  return WRITE_FLAGS.includes(String(option || "").replace(/^--/, ""));
+}
+
 /**
  * `observe read` is GET only. There is deliberately no way to pick a method,
  * add a header or send a body: anything else belongs in an action handler the
@@ -407,7 +412,7 @@ export function refuseWriteFlags(flags = {}) {
   const asked = WRITE_FLAGS.filter((name) => name in flags);
   if (asked.length) {
     throw new Error(
-      `observe read is GET only and never sends a body (refused: ${asked
+      `observe read is GET only - it never sets a method, a header or a body (refused: ${asked
         .map((name) => `--${name}`)
         .join(", ")}).`,
     );
@@ -706,8 +711,9 @@ export function looksLoggedIn({ url, hasPasswordField = false, hosts = [] }) {
 
 /** Computed colours come back as rgb()/rgba(); anything else passes through. */
 // oklch / oklab, as modern apps write their palettes and as Chrome reports
-// them back, converted to sRGB. Cards must be plain hex: the panel saves them
-// to history as an image drawn by a library that cannot read these.
+// them back, converted to sRGB hex like rgb() and rgba(): brandFile checks
+// contrast and works out its other keys from hex. lab(), lch() and color()
+// pass through; brandFile writes a default in their place.
 function okToHex(text) {
   const match = /^(oklch|oklab)\(\s*([\d.]+%?)\s+(-?[\d.]+%?)\s+(-?[\d.]+)(?:deg)?\s*(?:\/\s*([\d.]+%?))?\s*\)$/i.exec(text);
   if (!match) return null;
@@ -770,57 +776,180 @@ function luminance(hex) {
 
 const isHex = (value) => /^#[0-9a-f]{6}([0-9a-f]{2})?$/i.test(String(value || ""));
 
+/** `share` of the way from one #RRGGBB to another, channel by channel. */
+function mixHex(from, to, share) {
+  const channels = (hex) => [1, 3, 5].map((start) => parseInt(hex.slice(start, start + 2), 16));
+  const target = channels(to);
+  return `#${channels(from)
+    .map((value, i) => Math.round(value + (target[i] - value) * share).toString(16).padStart(2, "0"))
+    .join("")
+    .toUpperCase()}`;
+}
+
 /**
  * `agent/views/brand.ts` from what `observe styles` sampled: the app's own
- * accent, text, border, font and radius, on the panel's white surface. A dark
- * app keeps its accent, font and radius; its light-on-dark text and borders
+ * accent, text, muted text, border, font, radius and text size, on white (the
+ * panel's default background), plus every other key a recipe card reads - a
+ * fixed colour (surface2 and the status colours), one worked out from the
+ * sampled ones, or another name for one of them. A see-through text, muted or
+ * border colour is flattened onto the white; a see-through accent keeps its
+ * colour at full strength, so a tinted button still gives the app's own accent.
+ * A text, muted, border or accent colour still too light to read on white falls
+ * back to its default and says so. A dark app keeps its font, radius, text size
+ * and (unless it is too light) its accent; its light-on-dark text and borders
  * would vanish on white, so those fall back to neutral greys and say so.
  */
-export function brandFile(styles, { url, date, agentPrimary } = {}) {
+export function brandFile(styles, { url, date } = {}) {
   const notes = [];
   const pick = (value, fallback, name) => {
     const hex = value ? toHex(value) : null; // rgb / oklch / oklab -> hex; anything else stays as it was
     if (isHex(hex)) return hex.slice(0, 7).toUpperCase();
-    if (value) notes.push(`${name}: sampled "${value}" is not a plain colour - using ${fallback}`);
+    if (value) notes.push(`${name}: sampled "${value}" could not be converted to hex - using ${fallback}`);
     return fallback;
   };
+  // A see-through colour (rgba, or hex with alpha) is drawn on the panel's
+  // white, so flatten it onto white: dropping the alpha would turn an
+  // rgba(0, 0, 0, 0.12) border, and every key worked out from it, black.
+  const onPanel = (value, fallback, name) => {
+    const hex = value ? toHex(value) : null;
+    const alpha = isHex(hex) && hex.length === 9 ? parseInt(hex.slice(7), 16) / 255 : 1;
+    return mixHex("#FFFFFF", pick(value, fallback, name), alpha);
+  };
   const background = pick(styles.background, "#FFFFFF", "background");
   const darkApp = (luminance(background) ?? 1) < 0.4;
-  if (darkApp) notes.push(`the app is dark (${background}); cards sit in the white panel, so text, muted and border are neutral greys`);
-  const text = darkApp ? "#111827" : pick(styles.text, "#111827", "text");
-  const muted = darkApp ? "#6B7280" : pick(styles.textMuted, "#6B7280", "textMuted");
-  const border = darkApp ? "#E5E7EB" : pick(styles.border, "#E5E7EB", "border");
+  if (darkApp) notes.push(`the app is dark (${background}); cards sit in the panel, white by default, so text, muted and border are neutral greys`);
+  // A colour too light to read on white - white nav text on a light app, a
+  // white button on a dark one - falls back to its default, and says so.
+  const readable = (resolve, value, fallback, name, limit) => {
+    const hex = resolve(value, fallback, name);
+    if ((luminance(hex) ?? 0) <= limit) return hex;
+    notes.push(`${name}: sampled "${value}" would not read on white - using ${fallback}`);
+    return fallback;
+  };
+  const text = darkApp ? "#111827" : readable(onPanel, styles.text, "#111827", "text", 0.6);
+  const muted = darkApp ? "#6B7280" : readable(onPanel, styles.textMuted, "#6B7280", "textMuted", 0.75);
+  const border = darkApp ? "#E5E7EB" : readable(onPanel, styles.border, "#E5E7EB", "border", 0.97);
   const buttonBackground = styles.primaryButton?.background;
-  const accent = isHex(agentPrimary)
-    ? agentPrimary.slice(0, 7).toUpperCase()
-    : pick(buttonBackground || styles.link, "#3248F2", "accent");
-  const accentSource = isHex(agentPrimary) ? "the agent's own primary colour" : buttonBackground ? "the app's primary button" : styles.link ? "the app's links" : "Foldspace blue (nothing sampled)";
-  const accentText = pick(styles.primaryButton?.color, (luminance(accent) ?? 0) > 0.6 ? "#111827" : "#FFFFFF", "accentText");
+  const accentSample = buttonBackground || styles.link;
+  // The accent keeps its colour at full strength: a tinted button such as
+  // rgba(50, 72, 242, 0.08) still gives the app's own blue, which the cards
+  // draw white text on.
+  const accent = readable(pick, accentSample, "#3248F2", "accent", 0.85);
+  // The accent is the app's only when the sample could be converted to hex
+  // and reads on white; otherwise a NOTE says why it is the default.
+  const accentFromApp = Boolean(accentSample) && !notes.some((note) => note.startsWith("accent:"));
+  const accentSource = !accentSample
+    ? "a default blue (nothing sampled)"
+    : !accentFromApp
+      ? "a default blue (see the NOTE on accent)"
+      : buttonBackground
+        ? "the app's primary button"
+        : "the app's links";
+  // Only a solid button's text is kept, and only when the accent is that
+  // button's: a see-through button's text was chosen for its tint.
+  const buttonHex = toHex(buttonBackground);
+  const buttonText = accentFromApp && isHex(buttonHex) && buttonHex.length === 7 ? styles.primaryButton?.color : null;
+  const accentText = pick(buttonText, (luminance(accent) ?? 0) > 0.6 ? "#111827" : "#FFFFFF", "accentText");
   const font = String(styles.fontFamily || "").replace(/["'\\]/g, "").trim() || "Roboto, sans-serif";
   const radius = /^\d+(\.\d+)?px$/.test(String(styles.boxRadius || "")) ? styles.boxRadius : "8px";
+  // The app's most used text size, kept to 12-16px so a card fits the panel.
+  const sampledSize = /^(\d+(?:\.\d+)?)px$/.exec(String(styles.fontSize || ""));
+  const base = sampledSize ? Math.min(16, Math.max(12, Math.round(Number(sampledSize[1])))) : 14;
+  const white = "#FFFFFF";
+  const black = "#000000";
+  const good = "#047857";
+  const warn = "#B45309";
+  const derived = {
+    textStrong: mixHex(text, black, 0.5),
+    faint: mixHex(muted, white, 0.35),
+    row: mixHex(border, white, 0.75),
+    tableHead: mixHex(border, white, 0.5),
+    accentDeep: mixHex(accent, black, 0.15),
+    accentSoft: mixHex(accent, white, 0.9),
+    headerStart: mixHex(accent, white, 0.92),
+  };
+  // One shape for every card: each recipe's brand.ts is a placeholder with
+  // these keys, in this order.
+  const values = {
+    surface: white,
+    surface2: "#F5F6FA",
+    text,
+    muted,
+    border,
+    accent,
+    accentText,
+    font,
+    radius,
+    size: { base: `${base}px`, small: `${base - 2}px` },
+    ...derived,
+    good,
+    warn,
+    warnInk: "#FEF3C7",
+    bad: "#B91C1C",
+    primary: accent,
+    tint: derived.tableHead,
+    disabled: derived.faint,
+    money: good,
+    ok: good,
+    deals: accent,
+    contacts: derived.accentDeep,
+    cases: warn,
+  };
+  const groups = {
+    textStrong: "Worked out from the values above.",
+    good: "Status colours: fixed, so green, amber and red mean the same in every app.",
+    primary: "Other names some cards use for the colours above; a new card uses the original key.",
+  };
+  const comments = {
+    surface2: "a second background: a fixed light grey",
+    accentText: isHex(toHex(buttonText))
+      ? "text on accent: the app's button text"
+      : "text on accent: white, or near-black when accent is light",
+    size: sampledSize
+      ? "base: the app's most used text size, kept to 12-16px; small: 2px less"
+      : "base: 14px (no text size was sampled); small: 2px less",
+    textStrong: "names and headings: text, halfway to black",
+    faint: "hints and empty states: muted, 35% toward white",
+    row: "row backgrounds and alternate rows: border, 75% toward white",
+    tableHead: "table heads and summary boxes: border, halfway to white",
+    accentDeep: "gradients and hover: accent, 15% toward black",
+    accentSoft: "chips, selected rows and focus rings: accent, 90% toward white",
+    headerStart: "card headers and stage tags: accent, 92% toward white",
+    good: "done, valid, amounts",
+    warn: "late, at risk, needs a look",
+    warnInk: "the light amber behind a warning tag",
+    bad: "failed, not valid, critical",
+    primary: "same as accent",
+    tint: "pick-from-a-list's head and selected row: same as tableHead",
+    disabled: "a button that cannot be pressed: same as faint",
+    money: "amounts: same as good",
+    ok: "same as good",
+    deals: "the open-deals count: same as accent",
+    contacts: "the contacts count: same as accentDeep",
+    cases: "the open-cases count: same as warn",
+  };
+  const literal = (key, value) =>
+    key === "size" ? `{ base: "${value.base}", small: "${value.small}" }` : key === "font" ? `'${value}'` : `"${value}"`;
   const stamp = `${url || "the app"}${date ? ` on ${date}` : ""}`;
   const lines = [
     `// Brand reference for this product's cards. Sampled from ${stamp} with`,
-    "// `foldspace observe styles --write`. Cards live in the agent's panel, which is",
-    "// white, so the surface is the panel's; accent, text, border, font and radius",
-    "// are the app's own. Re-run the command to re-sample; do not edit by eye.",
-    "// Plain hex only: the panel saves cards to history as an image drawn by a",
-    "// library that cannot read oklch()/lab().",
+    "// `npx foldspace observe styles --write`. Cards live in the agent's panel,",
+    "// which is white by default, so surface is white. text, muted, border, accent,",
+    "// font, radius and size are the app's own, or a default where they were not",
+    "// sampled or would not read on white; every other key's comment, or the",
+    "// heading above it, says where it comes from. Keep every key, so any recipe",
+    "// card can use this file.",
+    "// Re-run the command to re-sample; do not edit by eye.",
     `// accent: ${accentSource}.`,
     ...notes.map((note) => `// NOTE ${note}.`),
     "",
     "export const brand = {",
-    `  surface: "#FFFFFF",`,
-    `  surface2: "#F5F6FA",`,
-    `  text: "${text}",`,
-    `  muted: "${muted}",`,
-    `  border: "${border}",`,
-    `  accent: "${accent}",`,
-    `  accentText: "${accentText}",`,
-    `  font: '${font}',`,
-    `  radius: "${radius}",`,
+    ...Object.entries(values).flatMap(([key, value]) => [
+      ...(groups[key] ? [`  // ${groups[key]}`] : []),
+      `  ${key}: ${literal(key, value)},${comments[key] ? ` // ${comments[key]}` : ""}`,
+    ]),
     "} as const;",
     "",
   ];
-  return { content: lines.join("\n"), notes, values: { text, muted, border, accent, accentText, font, radius } };
+  return { content: lines.join("\n"), notes, values };
 }

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`.