@foldspace_npm/harness 0.1.10 → 0.1.11

package/CLAUDE.md

@@ -0,0 +1,235 @@
+# Foldspace Agent
+
+## Harness version
+
+At the start of a session, run `npx foldspace help --json` (or, from an older
+install, `npx --yes @foldspace_npm/harness@latest upgrade --check`).
+
+If `update.outdated` is true, tell the user the pinned and latest versions and
+**ask before upgrading**. After they agree, run `foldspace upgrade --yes`, then
+`npm run build`. Do not upgrade as a side effect of build, attach, or
+implementing an action. A harness bump is not a deploy.
+
+If the tenant `CLAUDE.md` does not contain
+`@node_modules/@foldspace_npm/harness/CLAUDE.md`, ask before
+`foldspace upgrade --refresh-instructions`. That replaces the snapshot with an
+import of this file.
+
+## Before building
+
+1. Run `npx foldspace help --json` before an unfamiliar harness operation.
+   Treat its risk, prerequisites, effects, next-step, and `update` fields as
+   the current CLI contract.
+2. Connect Product MCP and verify that `list_agents` works.
+3. Inspect the selected agent with `get_agent_settings`, `list_actions`, and
+   `list_task_agents`.
+4. Use `discover_actions` to identify candidate experiences, then let the user
+   choose what to build. Treat those ideas as candidates, not an inventory.
+
+## Build workflow
+
+An experience can require several reusable actions. Separate lookup actions
+from actions that read or mutate a selected resource.
+
+1. Agree on the candidate experience and how its actions would compose. This is
+   not a publish and not a commitment.
+2. Run `npm run inject`. Ask the user to sign in and perform the real target
+   workflow in that Chrome window.
+3. Capture at least one real HTTP 200 for the data the action needs. Use
+   chrome-devtools MCP against the inject Chrome, or a page-context `fetch`,
+   **before** `attach` owns the debug port. If there is no 200,
+   pivot; do not create Foldspace resources. Write what you establish into
+   `docs/app-profile.md` with **how you know it**. Do not promote an assumption
+   by quoting that file.
+4. Create action metadata as a draft. `generate_action_handler` works from a
+   draft schema; do not publish yet.
+5. Implement the handler using the observed request and response shapes.
+   Import helpers from `agent/utils.ts` — inspect that file before writing
+   another `fetch` or rank helper.
+6. Register the handler in `agent/actions/index.ts` and build (`foldspace build` lints first).
+7. Run `npx foldspace attach --daemon` (add `--bootstrap` or `--replace` when
+   the page requires it). An empty local registry is valid if you only want to
+   see how the agent works.
+8. Ask before publishing. Publishing is required only so the copilot can call
+   the action, and it is a live product change when the agent has real users.
+9. Complete the verification gates below.
+
+## API rules
+
+Actions execute in the user's signed-in browser session.
+
+- Import HTTP, ranking, and widget helpers from `../utils`, not a new
+  `agent/api.ts` copy of `fetch`.
+- Do not guess `API_BASE` or `AUTH_SOURCE`. Capture at least one real 200
+  (and the auth header the page actually sends) before filling them in.
+  `credentials: "include"` is correct only when you have observed the app
+  using cookies that way. Many apps use `Authorization: Bearer` from
+  `localStorage` instead; some use a custom header.
+- Never guess endpoints or schemas. Capture at least one real 200 before
+  implementing a parser. Do not implement a path that was not observed.
+- Verify that the user is signed in before observing a workflow.
+- Do not substitute a public developer API when the browser session is missing;
+  ask the user to sign in.
+- Validate parameters and return sanitized errors. Return **data only** — never
+  `directive`, `instructions`, or a paragraph telling the copilot what to say.
+  Action and agent instructions live in Agent Studio / MCP. Never return
+  `ApiResult.detail` from `execute` — it is for the console.
+- Actions that return data the user will inspect should include a `render`
+  function for in-chat UI (a chatterblock). If it makes more sense to output the data
+  in a UI component instead of text then consider using render to show a component.
+   - `render` receives **`execute`'s return value**, not the action's input params.
+     Returning anything that lacks the ids the card needs is why widgets pass in
+     isolation and fail in the real chat.
+   - `runAction` refuses render actions (`cannot be executed silently`). Driving
+     `render()` yourself never runs `execute()`, so it does not test that contract.
+   - Check https://docs.foldspace.ai/guides/in-chat-ui/ for more information
+
+## Task agents
+
+Use a Task Agent when the handler needs a one-time LLM subtask that
+deterministic code cannot do well: extraction, summarization,
+classification, normalization, enrichment, or generation.
+
+Do not use a Task Agent for API calls, CRUD, routing, or parsing a
+known response shape. Those stay in `execute`.
+
+Task agents are created in Agent Studio, not in this repo. Ask before
+creating or publishing one. Call a published task agent from the
+handler with `runTask({ taskKey, data })` (if not published the runTask won't work).
+`data` carries extracted facts only — not `prompt` / `instructions` strings.
+Prefer JSON output when the handler must consume the result.
+
+See https://docs.foldspace.ai/user-guides/task-agents/ and
+https://docs.foldspace.ai/reference/task-agent-api/
+
+## Local harness loop
+
+```bash
+npm run dev
+npm run inject
+npx foldspace attach --daemon
+```
+
+`inject` launches an isolated Chrome profile and records its debug port.
+It does not generate or load an application extension. Observe the customer's
+workflow after inject and **before** attach, while chrome-devtools MCP can use
+the same Chrome. `attach` prepares the page and loads the local `dist/index.js`
+bundle through CDP. Coding agents must use `--daemon` so the invoking tool
+returns after `[lifecycle] inspect_registration:…`; foreground `npm run attach`
+is for humans watching the terminal. An empty local registry is valid. `npm run
+build` is still required so `dist/index.js` exists.
+
+Use the default swap only when the page already has the configured product and
+agent. Use `--bootstrap` only when the page has no Foldspace SDK, and
+`--replace` when it embeds a different product or agent, or when an SDK is
+present without the configured agent.
+
+The attach log must report `inspect_registration:registration_ok` before
+treating the page as registered. Zero captured actions is success when the
+local registry is empty. On `registration_mismatch`, read
+`npx foldspace help attach --json` diagnostics and map those names onto the
+lifecycle details (`missingActionNames`, `unexpectedActionNames`,
+`diagnosticError`).
+
+While attach is running it owns the debug port. Detach (`attach --stop`, or
+Ctrl-C in the foreground) before using chrome-devtools MCP against the same
+Chrome.
+
+Prove a named action through the visible agent. After the user talks to the
+copilot, read the daemon log for `[actions]` SDK callback and local
+execute/render lines; do not invoke the handler directly. Those lines record
+names, statuses, durations, and parameter keys only — not results or error
+bodies.
+
+## Product defaults
+
+These are not product-specific. Lint can catch some of them in handler code;
+Agent Studio copy is on you.
+
+- **No emoji** in copilot replies, cards, or handler strings. Put that in the
+  agent's Behavior instructions (MCP cannot write that field, so each new
+  action's Studio `instructions` must carry the line too).
+- **Never send the user out of the host app.** No "open in <product>"
+  button and no pasted URLs — navigate with a navigation route, same tab.
+- **Check row counts before choosing the experience.** On an empty account the
+  useful first action is one that creates data.
+
+## Verification gates
+
+Do not report success without all six:
+
+1. TypeScript compiles with `npm run typecheck` (`tsc --noEmit -p tsconfig.json`).
+   Do not run `npx tsc` — that can install the wrong package.
+2. `foldspace lint` reports no errors (`foldspace build` runs this first).
+3. The expected handler appears in `dist/index.js`.
+4. The browser reports `inspect_registration:registration_ok`. For a named
+   action, the captured registry includes that handler.
+5. The action behaves correctly against the real target workflow. Confirm
+   `[actions] local-handler:execute` in the attach log after the user exercises
+   the visible agent. For a widget, that log must include `local-handler:render`
+   from a real chat turn — not a hand-built `render()` call.
+6. Browser evidence came from the live target, not from hand-authored examples.
+   Neighbour fixtures still pass when they exist.
+
+## Layout
+
+- `agent/actions/` — one handler per action (`execute`, optional `render`),
+  registered in `index.ts`
+- `agent/api/` — one HTTP helper per endpoint
+- `agent/constants.ts` — agent, product, domain, plus empty `API_BASE` /
+  `AUTH_SOURCE` and `LOAD_MODE`
+- `agent/utils.ts` — configure the harness runtime and re-export it. **This is
+  the only import surface for actions.**
+- `foldspace.dev.json` — local harness target configuration
+- `docs/app-profile.md` — what is known about this app, and how it was established
+- `CLAUDE.md` — this file, imported — plus what is specific to this product
+
+Do not introduce another bundler or bundle format.
+
+## What you already have
+
+Import from `../utils`. Inspect that file before implementing another
+general-purpose helper. MCP `generate_action_handler` may still emit a
+skeleton that does not import it — fix the import when you implement.
+
+| Helper | Use when | Do not use when |
+|---|---|---|
+| `apiFetch` / `apiFetchBinary` | The app's own JSON/file API, after a real 200 | Public marketing hosts (`publicFetch`); custom auth headers |
+| `publicFetch` | Unauthenticated / marketing origin | Signed-in product APIs |
+| `getAuthToken` / `parseJwt` | `AUTH_SOURCE` is `localStorage` or `cookie` | Custom header schemes — override `apiFetch` in `utils.ts` |
+| `rankBy` | User typed a name; API search is exact or ignored | Domain ranking (invoices, coverage, MasterFormat) |
+| `renderLoading` / `Empty` / `Error` / `Fatal` | Chatterblock empty/error paths | Branded cards — those stay in `agent/views/` |
+| `getAgent` | Talking to Foldspace | You need a specific instance — then `agentIds()` |
+| `armAllInstances` | Attach/bootstrap setup | Inside `execute` (can ship into `dist`; attach already arms test mode) |
+| `redact` / `mapWithConcurrency` | Logging tokens; batching fetches | — |
+
+If the observed auth is not Bearer + `localStorage`/`cookie`, stop re-exporting
+that one function and keep the rest:
+
+```ts
+export { getAgent, rankBy, renderEmpty } from "@foldspace_npm/harness/runtime";
+export { apiFetch } from "./api";
+```
+
+## Agent learnings
+
+`docs/app-profile.md` is the durable record of this app. Fill it as you probe,
+not afterwards. Other notes in `docs/` are fine for session-specific lessons.
+
+- Before similar work, read `docs/app-profile.md` and any other notes in `docs/`.
+- After non-obvious discoveries, add them to the profile (or a short extra
+  note) covering verified gotchas, failed approaches, and how they were
+  established.
+- Keep notes concise and evidence-based.
+- Do not store secrets, cookies, HAR files, browser storage, or other transient
+  session data in `docs/`.
+
+## Safety
+
+- Do not commit secrets, cookies, HAR files, browser storage, or
+  `.foldspace-dev/`.
+- Local handler changes are not cloud publication.
+- Creating or publishing Foldspace resources requires explicit approval.
+- Action keys and parameter names must match the published schema.
+- Search Foldspace documentation before asserting unfamiliar platform
+  behaviour.

package/README.md

@@ -97,7 +97,7 @@ Non-interactive / CI form:
 npx --yes @foldspace_npm/harness init foldspace-agent \
   --product-id FR8JUQZAQRZB \
   --agent-key my-agent \
-  --domain app.example.com \
+  --app-domain app.example.com \
   --name "My Agent"
 ```
 
@@ -107,14 +107,15 @@ When running directly from a harness checkout during development:
 node bin/cli.mjs init ../foldspace-agent \
   --product-id FR8JUQZAQRZB \
   --agent-key my-agent \
-  --domain app.example.com
+  --app-domain app.example.com
 ```
 
 The Agent Key is the value shown in Agent Studio, such as `my-agent`. It is
 not the sidecar directory name. `--agent-api-name` remains a deprecated alias
-for `--agent-key`. `--name` is optional and defaults to the target directory
+for `--agent-key`. `--domain` remains a deprecated alias for `--app-domain`.
+`--name` is optional and defaults to the target directory
 name (`foldspace-agent` unless you pass a directory). The product ID must be
-the bare ID, not the `EU-…-1-1` SDK loader key. The domain may be a hostname
+the bare ID, not the `EU-…-1-1` SDK loader key. The app domain may be a hostname
 or an HTTP(S) URL without a port or path.
 
 For safety, `init` requires a target path that does not exist. It does not
@@ -132,6 +133,24 @@ npm run attach
 The generated npm scripts intentionally remain the normal project interface;
 `foldspace init` is the one-time project creation command.
 
+Generated `CLAUDE.md` imports platform instructions from
+`@foldspace_npm/harness` instead of copying them. Existing projects can switch
+to that import with `foldspace upgrade --refresh-instructions`.
+
+### Keep the harness current
+
+Tenant projects pin an exact `@foldspace_npm/harness` version. Publishing a
+newer package does not move them. Check, ask the user, then bump:
+
+```bash
+npx --yes @foldspace_npm/harness@latest upgrade --check
+foldspace upgrade --yes   # only after the user agrees
+```
+
+`--check` (and a non-interactive `upgrade` with no `--yes`) never installs.
+`--yes` rewrites the exact pin and runs `npm install --ignore-scripts`. Rebuild
+afterward; that is still not a deploy.
+
 ### Lint handlers before they ship
 
 `foldspace build` runs `foldspace lint` first. Errors skip bundling; warnings

package/bin/cli.mjs

@@ -5,6 +5,12 @@ import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { runInit } from "../src/init.mjs";
+import {
+  checkForUpdate,
+  nagIfOutdated,
+  resolveProjectDir,
+  runUpgrade,
+} from "../src/upgrade.mjs";
 import {
   classifyAttachControl,
   runAttachControl,
@@ -56,10 +62,13 @@ function printHelp(topic, json) {
     );
     return;
   }
+  const update = checkForUpdate(resolveProjectDir());
   if (json) {
-    console.log(JSON.stringify(document, null, 2));
+    const payload = topic ? document : { ...document, update };
+    console.log(JSON.stringify(payload, null, 2));
     return;
   }
+  nagIfOutdated(update);
   console.log(
     topic ? renderCommandHelp(registry, topic) : renderGeneralHelp(registry),
   );
@@ -118,6 +127,7 @@ const [command, ...args] = process.argv.slice(2);
 if (!command || command === "--help" || command === "-h") {
   printHelp(null, args.includes("--json"));
 } else if (command === "--version" || command === "-v") {
+  nagIfOutdated(checkForUpdate(resolveProjectDir()));
   console.log(
     `${registry.package.name} ${registry.package.version} ` +
       `(protocol ${registry.protocolVersion}, CLI schema ${registry.schemaVersion})`,
@@ -149,6 +159,24 @@ if (!command || command === "--help" || command === "-h") {
       fail(error instanceof Error ? error.message : String(error));
     }
   }
+} else if (command === "upgrade") {
+  if (args.includes("--help") || args.includes("-h")) {
+    printHelp("upgrade", args.includes("--json"));
+  } else {
+    try {
+      const normalized = normalizeCommandArgs(commandByName("upgrade"), args);
+      Promise.resolve()
+        .then(() => runUpgrade(normalized))
+        .then((report) => {
+          console.log(JSON.stringify(report, null, 2));
+        })
+        .catch((error) => {
+          fail(error instanceof Error ? error.message : String(error));
+        });
+    } catch (error) {
+      fail(error instanceof Error ? error.message : String(error));
+    }
+  }
 } else if (commandByName(command)) {
   if (args.includes("--help") || args.includes("-h")) {
     printHelp(command, args.includes("--json"));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foldspace_npm/harness",
-  "version": "0.1.10",
+  "version": "0.1.11",
   "description": "Build and verify portable Foldspace action artifacts against a live app.",
   "type": "module",
   "bin": {
@@ -21,7 +21,8 @@
     "bin",
     "src",
     "templates",
-    "README.md"
+    "README.md",
+    "CLAUDE.md"
   ],
   "dependencies": {
     "esbuild": "^0.20.0",

package/src/cli-help.mjs

@@ -46,6 +46,7 @@ export function renderGeneralHelp(registry) {
     "  foldspace help --json            Print the machine-readable CLI contract",
     "  foldspace help <command> --json  Print one command contract",
     "  foldspace --version              Show package and protocol versions",
+    "  foldspace upgrade --check        Compare the installed pin to npm latest",
     "",
     "attach loads local actions and observes the normal agent experience.",
     "deploy is a separate remote publication step.",

package/src/cli-registry.mjs

@@ -21,7 +21,7 @@ export const CLI_COMMANDS = Object.freeze([
     group: "start",
     summary: "Create a configured Foldspace actions project",
     usage:
-      "foldspace init [<directory>] [--product-id <id>] [--agent-key <key>] [--domain <host>] [--name <display-name>]",
+      "foldspace init [<directory>] [--product-id <id>] [--agent-key <key>] [--app-domain <host>] [--name <display-name>]",
     risk: "local-write",
     environment: "node",
     environmentVariables: [],
@@ -41,8 +41,9 @@ export const CLI_COMMANDS = Object.freeze([
         required: "non-interactive",
         deprecatedAliases: ["--agent-api-name"],
       }),
-      value("--domain", "host", "Target hostname or HTTP(S) URL", {
+      value("--app-domain", "host", "Live app hostname or HTTP(S) URL", {
         required: "non-interactive",
+        deprecatedAliases: ["--domain"],
       }),
       value("--name", "display-name", "Display name", {
         default: "directory name",
@@ -51,7 +52,7 @@ export const CLI_COMMANDS = Object.freeze([
     prerequisites: [
       "Node 20 or newer",
       "A target directory that does not already exist",
-      "Non-interactive use requires directory, product ID, Agent Key, and domain",
+      "Non-interactive use requires directory, product ID, Agent Key, and app domain",
     ],
     effects: ["Creates a new local project; never initializes Git"],
     next: [
@@ -61,6 +62,48 @@ export const CLI_COMMANDS = Object.freeze([
       "Run foldspace attach",
     ],
   }),
+  Object.freeze({
+    name: "upgrade",
+    entry: null,
+    group: "start",
+    summary: "Check for a newer harness and update the exact pin after asking",
+    usage:
+      "foldspace upgrade [--check | --yes] [--refresh-instructions]",
+    risk: "local-write",
+    environment: "node",
+    environmentVariables: [
+      "FOLDSPACE_PROJECT_DIR",
+      "FOLDSPACE_SKIP_UPDATE_CHECK",
+    ],
+    capabilities: ["project.upgrade"],
+    positionals: [],
+    options: [
+      flag("--check", "Compare versions and print JSON; never install"),
+      flag(
+        "--yes",
+        "Install the latest exact pin after the user has already agreed",
+      ),
+      flag(
+        "--refresh-instructions",
+        "Replace CLAUDE.md with an import of the package instructions",
+      ),
+    ],
+    prerequisites: [
+      "A consumer project with package.json",
+      "An exact @foldspace_npm/harness dependency unless only refreshing instructions",
+    ],
+    effects: [
+      "Without --yes, writes nothing except an optional update cache",
+      "With --yes, rewrites the exact harness pin and runs npm install --ignore-scripts",
+      "Does not rebuild dist/index.js or deploy",
+      "--refresh-instructions copies CLAUDE.md to CLAUDE.md.bak then writes the stub",
+    ],
+    next: [
+      "If outdated, ask the user, then run foldspace upgrade --yes",
+      "Run npm run build after a pin bump",
+      "Deploy only if product users should receive the rebuilt runtime",
+    ],
+  }),
   Object.freeze({
     name: "build",
     entry: "build-cli.mjs",
@@ -272,6 +315,7 @@ export const CLI_COMMANDS = Object.freeze([
 
 export const CAPABILITY_CATALOGUE = Object.freeze([
   ["project.scaffold", "Create a new configured project on local disk"],
+  ["project.upgrade", "Update the consuming project's exact harness pin"],
   ["artifact.build", "Build the portable dist/index.js action artifact"],
   ["browser.launch", "Launch an isolated local Chrome profile"],
   ["browser.cdp", "Connect to local Chrome through CDP"],
@@ -342,6 +386,7 @@ export function createCliRegistry({ packageName, packageVersion }) {
       "The harness bin alias is equivalent to foldspace.",
       "attach diagnostics are attach-internal; interpret them from the lifecycle log, not as CLI commands.",
       "Coding agents should run attach --daemon; foreground attach is for humans watching the terminal.",
+      "If update.outdated is true, ask the user before foldspace upgrade --yes.",
     ],
   };
 }

package/src/init.mjs

@@ -13,6 +13,7 @@ const allowedFlags = new Set([
   "product-id",
   "agent-key",
   "agent-api-name",
+  "app-domain",
   "domain",
 ]);
 const tokenPattern = /\{\{([A-Z0-9_]+)\}\}/g;
@@ -86,13 +87,18 @@ export function parseInitArgs(argv) {
       "Use --agent-key only; --agent-api-name is its deprecated alias.",
     );
   }
+  if (flags["app-domain"] && flags.domain) {
+    throw new Error(
+      "Use --app-domain only; --domain is its deprecated alias.",
+    );
+  }
 
   return {
     directory: positional[0] || null,
     displayName: flags.name || null,
     productId: flags["product-id"] || null,
     agentApiName: flags["agent-key"] || flags["agent-api-name"] || null,
-    domain: flags.domain || null,
+    domain: flags["app-domain"] || flags.domain || null,
   };
 }
 
@@ -101,7 +107,7 @@ function missingInitFields(parsed) {
   if (!parsed.directory) missing.push("directory");
   if (!parsed.productId) missing.push("product-id");
   if (!parsed.agentApiName) missing.push("agent-key");
-  if (!parsed.domain) missing.push("domain");
+  if (!parsed.domain) missing.push("app-domain");
   return missing;
 }
 
@@ -134,14 +140,14 @@ function validateProductId(value) {
 function normalizeTarget(value) {
   const raw = value.trim();
   if (!raw || raw.includes("*")) {
-    throw new Error("Domain must be a concrete hostname without a wildcard.");
+    throw new Error("App domain must be a concrete hostname without a wildcard.");
   }
 
   let url;
   try {
     url = new URL(raw.includes("://") ? raw : `https://${raw}`);
   } catch {
-    throw new Error(`Invalid domain: ${value}`);
+    throw new Error(`Invalid app domain: ${value}`);
   }
 
   if (
@@ -153,12 +159,12 @@ function normalizeTarget(value) {
     url.search ||
     url.hash
   ) {
-    throw new Error("Domain must contain only an HTTP(S) hostname, without credentials, a port, path, query, or fragment.");
+    throw new Error("App domain must contain only an HTTP(S) hostname, without credentials, a port, path, query, or fragment.");
   }
 
   const domain = url.hostname.toLowerCase().replace(/\.$/, "");
   if (!domain || domain.includes("..")) {
-    throw new Error(`Invalid domain: ${value}`);
+    throw new Error(`Invalid app domain: ${value}`);
   }
 
   return {
@@ -227,7 +233,7 @@ async function promptForMissingFields(parsed, options = {}) {
 
   if (!next.domain) {
     next.domain = await askUntilValid(
-      "Domain",
+      "App domain",
       (value) => {
         normalizeTarget(value);
         return value.trim();
@@ -255,7 +261,7 @@ function finalizeInitConfig(parsed) {
   for (const [key, label] of [
     ["productId", "product-id"],
     ["agentApiName", "agent-key"],
-    ["domain", "domain"],
+    ["domain", "app-domain"],
   ]) {
     if (!parsed[key]) {
       throw new Error(`Missing required option: --${label}\nUsage: ${initUsage}`);
@@ -304,7 +310,9 @@ function createTemplateValues(config, harnessVersion) {
     DISPLAY_NAME: displayName,
     PACKAGE_NAME: packageName,
     PACKAGE_DESCRIPTION_JSON: JSON.stringify(`Foldspace browser actions for ${displayName}.`),
+    PRODUCT_ID: productId,
     PRODUCT_ID_JSON: JSON.stringify(productId),
+    AGENT_API_NAME: agentApiName,
     AGENT_API_NAME_JSON: JSON.stringify(agentApiName),
     APP_DOMAIN: target.domain,
     APP_DOMAIN_JSON: JSON.stringify(target.domain),

package/src/upgrade.mjs

@@ -0,0 +1,469 @@
+import { execFileSync, spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import readline from "node:readline/promises";
+import { stdin as input } from "node:process";
+import { fileURLToPath } from "node:url";
+
+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";
+
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const instructionTemplatePath = path.join(
+  packageRoot,
+  "templates",
+  "agent-starter",
+  "CLAUDE.md",
+);
+const tokenPattern = /\{\{([A-Z0-9_]+)\}\}/g;
+
+export function resolveProjectDir(env = process.env, cwd = process.cwd()) {
+  return env.FOLDSPACE_PROJECT_DIR || cwd;
+}
+
+export function parseUpgradeArgs(argv) {
+  const flags = new Set();
+  for (const token of argv) {
+    if (token === "--check" || token === "--yes" || token === "--refresh-instructions") {
+      if (flags.has(token)) {
+        throw new Error(`option '${token}' was provided twice`);
+      }
+      flags.add(token);
+      continue;
+    }
+    throw new Error(`unknown option '${token}'`);
+  }
+  if (flags.has("--check") && flags.has("--yes")) {
+    throw new Error("options '--check' and '--yes' cannot be used together");
+  }
+  if (flags.has("--check") && flags.has("--refresh-instructions")) {
+    throw new Error(
+      "options '--check' and '--refresh-instructions' cannot be used together",
+    );
+  }
+  return {
+    checkOnly: flags.has("--check"),
+    yes: flags.has("--yes"),
+    refreshInstructions: flags.has("--refresh-instructions"),
+  };
+}
+
+export function normalizeVersion(spec) {
+  if (typeof spec !== "string" || !spec.trim()) return null;
+  const trimmed = spec.trim();
+  if (trimmed.startsWith("file:") || trimmed.startsWith("link:") || trimmed.startsWith("github:")) {
+    return null;
+  }
+  const match = trimmed.match(/^[~^]?(\d+\.\d+\.\d+)/);
+  return match ? match[1] : null;
+}
+
+export function compareVersions(left, right) {
+  const a = parseSemver(left);
+  const b = parseSemver(right);
+  if (!a || !b) return 0;
+  for (let index = 0; index < 3; index += 1) {
+    if (a[index] > b[index]) return 1;
+    if (a[index] < b[index]) return -1;
+  }
+  return 0;
+}
+
+function parseSemver(value) {
+  const version = normalizeVersion(value);
+  if (!version) return null;
+  return version.split(".").map((part) => Number(part));
+}
+
+export function isBehind(current, latest) {
+  if (!current || !latest) return false;
+  return compareVersions(current, latest) < 0;
+}
+
+function readJson(filePath) {
+  return JSON.parse(fs.readFileSync(filePath, "utf8"));
+}
+
+function writeJson(filePath, value) {
+  fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`);
+}
+
+export function readPackageManifest(projectDir) {
+  const manifestPath = path.join(projectDir, "package.json");
+  if (!fs.existsSync(manifestPath)) return null;
+  try {
+    return readJson(manifestPath);
+  } catch {
+    return null;
+  }
+}
+
+export function isHarnessSourceTree(projectDir) {
+  const manifest = readPackageManifest(projectDir);
+  return Boolean(
+    manifest?.name === HARNESS_PACKAGE &&
+      fs.existsSync(path.join(projectDir, "templates", "agent-starter")),
+  );
+}
+
+export function readPinnedVersion(manifest) {
+  if (!manifest || typeof manifest !== "object") return null;
+  const spec =
+    manifest.devDependencies?.[HARNESS_PACKAGE] ||
+    manifest.dependencies?.[HARNESS_PACKAGE] ||
+    null;
+  return normalizeVersion(spec);
+}
+
+export function readInstalledVersion(projectDir) {
+  const installedPath = path.join(
+    projectDir,
+    "node_modules",
+    HARNESS_PACKAGE,
+    "package.json",
+  );
+  if (!fs.existsSync(installedPath)) return null;
+  try {
+    return normalizeVersion(readJson(installedPath).version);
+  } catch {
+    return null;
+  }
+}
+
+export function hasLiveInstructionImport(content) {
+  return typeof content === "string" && content.includes(INSTRUCTION_IMPORT);
+}
+
+export function instructionValuesFromProject(projectDir) {
+  const configPath = path.join(projectDir, "foldspace.dev.json");
+  if (!fs.existsSync(configPath)) {
+    throw new Error("foldspace.dev.json is required to refresh CLAUDE.md");
+  }
+  const config = readJson(configPath);
+  const targetName = config.defaultTarget;
+  const target = config.targets?.[targetName];
+  if (!target?.productId || !target?.agentApiName) {
+    throw new Error(
+      `foldspace.dev.json target '${targetName || "default"}' is missing productId or agentApiName`,
+    );
+  }
+  let domain = null;
+  if (typeof target.startUrl === "string") {
+    try {
+      domain = new URL(target.startUrl).hostname;
+    } catch {
+      domain = null;
+    }
+  }
+  if (!domain && Array.isArray(target.hosts) && target.hosts[0]) {
+    domain = String(target.hosts[0]).replace(/^\*\./, "");
+  }
+  if (!domain) {
+    throw new Error("Could not resolve the app domain from foldspace.dev.json");
+  }
+  const manifest = readPackageManifest(projectDir);
+  return {
+    DISPLAY_NAME: manifest?.name || path.basename(projectDir),
+    PRODUCT_ID: String(target.productId),
+    AGENT_API_NAME: String(target.agentApiName),
+    APP_DOMAIN: domain,
+  };
+}
+
+export function renderInstructionStub(values, template = fs.readFileSync(instructionTemplatePath, "utf8")) {
+  const rendered = template.replace(tokenPattern, (_match, key) => {
+    if (!(key in values)) {
+      throw new Error(`Missing value for {{${key}}} in CLAUDE.md stub`);
+    }
+    return values[key];
+  });
+  const unresolved = rendered.match(tokenPattern);
+  if (unresolved) {
+    throw new Error(`Unresolved template token ${unresolved[0]} in CLAUDE.md stub`);
+  }
+  return rendered;
+}
+
+export function refreshInstructionStub(projectDir, options = {}) {
+  const claudePath = path.join(projectDir, "CLAUDE.md");
+  const previous = fs.existsSync(claudePath)
+    ? fs.readFileSync(claudePath, "utf8")
+    : null;
+  const next = renderInstructionStub(
+    options.values || instructionValuesFromProject(projectDir),
+    options.template,
+  );
+  if (previous === next) {
+    return { written: false, backedUp: false, importPresent: true };
+  }
+  let backedUp = false;
+  if (previous !== null) {
+    fs.writeFileSync(path.join(projectDir, "CLAUDE.md.bak"), previous);
+    backedUp = true;
+  }
+  fs.writeFileSync(claudePath, next);
+  return { written: true, backedUp, importPresent: true };
+}
+
+function cachePath(projectDir) {
+  return path.join(projectDir, ".foldspace-dev", "harness-update.json");
+}
+
+function readCache(projectDir, now) {
+  const filePath = cachePath(projectDir);
+  if (!fs.existsSync(filePath)) return null;
+  try {
+    const cached = readJson(filePath);
+    if (typeof cached.checkedAt !== "number" || typeof cached.latest !== "string") {
+      return null;
+    }
+    if (now - cached.checkedAt > CACHE_TTL_MS) return null;
+    return cached;
+  } catch {
+    return null;
+  }
+}
+
+function writeCache(projectDir, latest, now) {
+  const dir = path.dirname(cachePath(projectDir));
+  fs.mkdirSync(dir, { recursive: true });
+  writeJson(cachePath(projectDir), { checkedAt: now, latest });
+}
+
+export function fetchLatestFromNpm(options = {}) {
+  const spawn = options.spawnSyncFn || spawnSync;
+  const result = spawn("npm", ["view", HARNESS_PACKAGE, "version"], {
+    encoding: "utf8",
+    timeout: options.timeoutMs ?? NPM_VIEW_TIMEOUT_MS,
+    env: options.env || process.env,
+  });
+  if (result.error || result.status !== 0) return null;
+  return normalizeVersion(result.stdout);
+}
+
+function nextAction(report) {
+  if (report.status === "outdated") {
+    return report.instructionsImport === false
+      ? `${UPGRADE_NEXT}. If CLAUDE.md is still a snapshot, also pass --refresh-instructions`
+      : UPGRADE_NEXT;
+  }
+  if (report.status === "upgraded") {
+    return "Run npm run build. Deploy only if product users should receive the rebuilt runtime.";
+  }
+  return null;
+}
+
+export function checkForUpdate(projectDir, options = {}) {
+  const env = options.env || process.env;
+  const now = options.now ?? Date.now();
+  const manifest = readPackageManifest(projectDir);
+  const harnessSource = isHarnessSourceTree(projectDir);
+  const pinned = harnessSource ? null : readPinnedVersion(manifest);
+  const installed = harnessSource
+    ? normalizeVersion(manifest?.version)
+    : readInstalledVersion(projectDir);
+  const claudePath = path.join(projectDir, "CLAUDE.md");
+  const instructionsImport = fs.existsSync(claudePath)
+    ? hasLiveInstructionImport(fs.readFileSync(claudePath, "utf8"))
+    : false;
+
+  const skipped =
+    options.skipCheck === true ||
+    (options.skipCheck !== false && env.FOLDSPACE_SKIP_UPDATE_CHECK === "1");
+  const consumer = !harnessSource && Boolean(pinned || installed);
+
+  let latest = null;
+  let status = "current";
+
+  if (!consumer) {
+    status = "not_a_consumer";
+  } else if (skipped) {
+    status = "check_skipped";
+  } else {
+    const cached = options.cache === false ? null : readCache(projectDir, now);
+    if (cached?.latest) {
+      latest = cached.latest;
+    } else {
+      const fetched =
+        typeof options.fetchLatest === "function"
+          ? options.fetchLatest()
+          : fetchLatestFromNpm(options);
+      latest = normalizeVersion(fetched);
+      if (latest && options.cache !== false) {
+        writeCache(projectDir, latest, now);
+      }
+    }
+    if (!latest) {
+      status = "check_skipped";
+    } else {
+      const outdated = isBehind(pinned, latest) || isBehind(installed, latest);
+      status = outdated ? "outdated" : "current";
+    }
+  }
+
+  const report = {
+    kind: "foldspace.cli.update",
+    package: HARNESS_PACKAGE,
+    pinned,
+    installed,
+    latest,
+    outdated: status === "outdated",
+    status,
+    instructionsImport,
+    next: null,
+  };
+  report.next = nextAction(report);
+  return report;
+}
+
+export function writeExactPin(projectDir, version) {
+  const manifestPath = path.join(projectDir, "package.json");
+  const manifest = readPackageManifest(projectDir);
+  if (!manifest) {
+    throw new Error(`package.json not found in ${projectDir}`);
+  }
+  if (manifest.dependencies?.[HARNESS_PACKAGE] !== undefined) {
+    manifest.dependencies[HARNESS_PACKAGE] = version;
+  } else {
+    manifest.devDependencies = manifest.devDependencies || {};
+    manifest.devDependencies[HARNESS_PACKAGE] = version;
+  }
+  writeJson(manifestPath, manifest);
+}
+
+function defaultInstall(projectDir) {
+  execFileSync("npm", ["install", "--ignore-scripts"], {
+    cwd: projectDir,
+    stdio: "inherit",
+    env: process.env,
+  });
+}
+
+function isInteractive(options = {}) {
+  if (typeof options.interactive === "boolean") return options.interactive;
+  return Boolean(options.stdin?.isTTY ?? input.isTTY);
+}
+
+function isAffirmative(value) {
+  const normalized = value.trim().toLowerCase();
+  return normalized === "" || normalized === "y" || normalized === "yes";
+}
+
+async function ask(question, options = {}) {
+  if (typeof options.ask === "function") return options.ask(question);
+  const rl = readline.createInterface({
+    input: options.stdin || input,
+    output: options.stderr || process.stderr,
+  });
+  try {
+    return await rl.question(question);
+  } finally {
+    rl.close();
+  }
+}
+
+export async function runUpgrade(argv, options = {}) {
+  const parsed = parseUpgradeArgs(argv);
+  const projectDir = options.projectDir || resolveProjectDir(options.env);
+  const log = options.log || ((message) => {
+    console.error(message);
+  });
+
+  if (isHarnessSourceTree(projectDir) && (parsed.yes || parsed.refreshInstructions)) {
+    throw new Error(
+      "this directory is the harness source, not a consumer project",
+    );
+  }
+
+  const report = checkForUpdate(projectDir, options);
+
+  if (parsed.checkOnly || (!parsed.yes && !isInteractive(options) && !parsed.refreshInstructions)) {
+    return report;
+  }
+
+  if (parsed.refreshInstructions && !parsed.yes && report.status !== "outdated") {
+    const refreshed = refreshInstructionStub(projectDir, options);
+    return {
+      ...report,
+      status: refreshed.written ? "instructions_refreshed" : "current",
+      instructionsImport: true,
+      refreshed: refreshed.written,
+      backedUp: refreshed.backedUp,
+      next: refreshed.written
+        ? "Imported platform instructions from the installed harness."
+        : report.next,
+    };
+  }
+
+  if (report.status === "not_a_consumer") {
+    throw new Error(
+      `no ${HARNESS_PACKAGE} dependency found in ${projectDir}`,
+    );
+  }
+
+  if (parsed.yes && report.status === "check_skipped") {
+    throw new Error("cannot upgrade without a registry version");
+  }
+
+  let shouldInstall = parsed.yes && report.status === "outdated";
+  let shouldRefresh = parsed.refreshInstructions;
+
+  if (!parsed.yes && !parsed.checkOnly && isInteractive(options) && report.status === "outdated") {
+    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);
+    shouldInstall = isAffirmative(answer);
+    if (!shouldInstall) {
+      return { ...report, status: "declined", next: UPGRADE_NEXT };
+    }
+    if (!report.instructionsImport && !shouldRefresh) {
+      const refreshAnswer = await ask(
+        "Replace CLAUDE.md with an import of the package instructions? [Y/n] ",
+        options,
+      );
+      shouldRefresh = isAffirmative(refreshAnswer);
+    }
+  }
+
+  if (!shouldInstall && !shouldRefresh) {
+    return report;
+  }
+
+  if (shouldInstall) {
+    if (!report.latest) {
+      throw new Error("cannot upgrade without a registry version");
+    }
+    writeExactPin(projectDir, report.latest);
+    const install = options.install || defaultInstall;
+    install(projectDir, report.latest);
+  }
+
+  let refreshed = { written: false, backedUp: false, importPresent: report.instructionsImport };
+  if (shouldRefresh) {
+    refreshed = refreshInstructionStub(projectDir, options);
+  }
+
+  const nextReport = {
+    ...report,
+    pinned: shouldInstall ? report.latest : report.pinned,
+    installed: shouldInstall ? report.latest : report.installed,
+    outdated: false,
+    status: shouldInstall ? "upgraded" : refreshed.written ? "instructions_refreshed" : report.status,
+    instructionsImport: shouldRefresh ? true : report.instructionsImport,
+    refreshed: refreshed.written,
+    backedUp: refreshed.backedUp,
+  };
+  nextReport.next = nextAction(nextReport);
+  return nextReport;
+}
+
+export function nagIfOutdated(report, write = (message) => console.error(message)) {
+  if (!report?.outdated) return;
+  write(
+    `foldspace: ${HARNESS_PACKAGE} ${report.pinned || report.installed} is behind ${report.latest}. ${UPGRADE_NEXT}.`,
+  );
+}

package/templates/agent-starter/CLAUDE.md

@@ -1,225 +1,16 @@
-# Foldspace browser actions
+# Foldspace actions for {{APP_DOMAIN}}
 
-## Scope
+@node_modules/@foldspace_npm/harness/CLAUDE.md
 
-This project contains Foldspace action handlers. The customer website, SDK
-snippet, `identify()` call, and layout are out of scope unless the user asks for
-changes there.
+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.
 
-## Before building
+## This product
 
-1. Run `npx foldspace help --json` before an unfamiliar harness operation.
-   Treat its risk, prerequisites, effects, and next-step fields as the current
-   CLI contract.
-2. Connect Product MCP and verify that `list_agents` works.
-3. Inspect the selected agent with `get_agent_settings`, `list_actions`, and
-   `list_task_agents`.
-4. Use `discover_actions` to identify candidate experiences, then let the user
-   choose what to build. Treat those ideas as candidates, not an inventory.
+| | |
+|---|---|
+| Agent | `{{AGENT_API_NAME}}` |
+| Product | `{{PRODUCT_ID}}` |
+| App | `{{APP_DOMAIN}}` |
 
-## Build workflow
-
-An experience can require several reusable actions. Separate lookup actions
-from actions that read or mutate a selected resource.
-
-1. Agree on the candidate experience and how its actions would compose. This is
-   not a publish and not a commitment.
-2. Run `npm run inject`. Ask the user to sign in and perform the real target
-   workflow in that Chrome window.
-3. Capture at least one real HTTP 200 for the data the action needs. Use
-   chrome-devtools MCP against the inject Chrome, or a page-context `fetch`,
-   **before** `attach` owns the debug port. If there is no 200,
-   pivot; do not create Foldspace resources. Write what you establish into
-   `docs/app-profile.md` with **how you know it**. Do not promote an assumption
-   by quoting that file.
-4. Create action metadata as a draft. `generate_action_handler` works from the
-   draft schema; do not publish yet.
-5. Implement the handler using the observed request and response shapes.
-   Import helpers from `agent/utils.ts` — inspect that file before writing
-   another `fetch` or rank helper.
-6. Register the handler in `agent/actions/index.ts` and build (`foldspace build` lints first).
-7. Run `npx foldspace attach --daemon` (add `--bootstrap` or `--replace` when
-   the page requires it). An empty local registry is valid if you only want to
-   see how the agent works.
-8. Ask before publishing. Publishing is required only so the copilot can call
-   the action, and it is a live product change when the agent has real users.
-9. Complete the verification gates below.
-
-## API rules
-
-Actions execute in the user's signed-in browser session.
-
-- Import HTTP, ranking, and widget helpers from `../utils`, not a new
-  `agent/api.ts` copy of `fetch`.
-- Do not guess `API_BASE` or `AUTH_SOURCE`. Capture at least one real 200
-  (and the auth header the page actually sends) before filling them in.
-  `credentials: "include"` is correct only when you have observed the app
-  using cookies that way. Many apps use `Authorization: Bearer` from
-  `localStorage` instead; some use a custom header.
-- Never guess endpoints or schemas. Capture at least one real 200 before
-  implementing a parser. Do not implement a path that was not observed.
-- Verify that the user is signed in before observing a workflow.
-- Do not substitute a public developer API when the browser session is missing;
-  ask the user to sign in.
-- Validate parameters and return sanitized errors. Return **data only** — never
-  `directive`, `instructions`, or a paragraph telling the copilot what to say.
-  Action and agent instructions live in Agent Studio / MCP. Never return
-  `ApiResult.detail` from `execute` — it is for the console.
-- Actions that return data the user will inspect should include a `render`
-  function for in-chat UI (a chatterblock). If it makes more sense to output the data
-  in a UI component instead of text then consider using render to show a component.
-   - `render` receives **`execute`'s return value**, not the action's input params.
-     Returning anything that lacks the ids the card needs is why widgets pass in
-     isolation and fail in the real chat.
-   - `runAction` refuses render actions (`cannot be executed silently`). Driving
-     `render()` yourself never runs `execute()`, so it does not test that contract.
-   - Check https://docs.foldspace.ai/guides/in-chat-ui/ for more information
-
-## Task agents
-
-Use a Task Agent when the handler needs a one-time LLM subtask that
-deterministic code cannot do well: extraction, summarization,
-classification, normalization, enrichment, or generation.
-
-Do not use a Task Agent for API calls, CRUD, routing, or parsing a
-known response shape. Those stay in `execute`.
-
-Task agents are created in Agent Studio, not in this repo. Ask before
-creating or publishing one. Call a published task agent from the
-handler with `runTask({ taskKey, data })` (if not published the runTask won't work).
-`data` carries extracted facts only — not `prompt` / `instructions` strings.
-Prefer JSON output when the handler must consume the result.
-
-See https://docs.foldspace.ai/user-guides/task-agents/ and
-https://docs.foldspace.ai/reference/task-agent-api/
-
-## Local harness loop
-
-```bash
-npm run dev
-npm run inject
-npx foldspace attach --daemon
-```
-
-`inject` launches an isolated Chrome profile and records its debug port.
-It does not generate or load an application extension. Observe the customer's
-workflow after inject and **before** attach, while chrome-devtools MCP can use
-the same Chrome. `attach` prepares the page and loads the local `dist/index.js`
-bundle through CDP. Coding agents must use `--daemon` so the invoking tool
-returns after `[lifecycle] inspect_registration:…`; foreground `npm run attach`
-is for humans watching the terminal. An empty local registry is valid. `npm run
-build` is still required so `dist/index.js` exists.
-
-Use the default swap only when the page already has the configured product and
-agent. Use `--bootstrap` only when the page has no Foldspace SDK, and
-`--replace` when it embeds a different product or agent, or when an SDK is
-present without the configured agent.
-
-The attach log must report `inspect_registration:registration_ok` before
-treating the page as registered. Zero captured actions is success when the
-local registry is empty. On `registration_mismatch`, read
-`npx foldspace help attach --json` diagnostics and map those names onto the
-lifecycle details (`missingActionNames`, `unexpectedActionNames`,
-`diagnosticError`).
-
-While attach is running it owns the debug port. Detach (`attach --stop`, or
-Ctrl-C in the foreground) before using chrome-devtools MCP against the same
-Chrome.
-
-Prove a named action through the visible agent. After the user talks to the
-copilot, read the daemon log for `[actions]` SDK callback and local
-execute/render lines; do not invoke the handler directly. Those lines record
-names, statuses, durations, and parameter keys only — not results or error
-bodies.
-
-## Product defaults
-
-These are not Joist-specific. Lint can catch some of them in handler code;
-Agent Studio copy is on you.
-
-- **No emoji** in copilot replies, cards, or handler strings. Put that in the
-  agent's Behavior instructions (MCP cannot write that field, so each new
-  action's Studio `instructions` must carry the line too).
-- **Never send the user out of the host app.** No "open in <product>"
-  button and no pasted URLs — navigate with a navigation route, same tab.
-- **Check row counts before choosing the experience.** On an empty account the
-  useful first action is one that creates data.
-
-## Verification gates
-
-Do not report success without all six:
-
-1. TypeScript compiles with `npm run typecheck` (`tsc --noEmit -p tsconfig.json`).
-   Do not run `npx tsc` — that can install the wrong package.
-2. `foldspace lint` reports no errors (`foldspace build` runs this first).
-3. The expected handler appears in `dist/index.js`.
-4. The browser reports `inspect_registration:registration_ok`. For a named
-   action, the captured registry includes that handler.
-5. The action behaves correctly against the real target workflow. Confirm
-   `[actions] local-handler:execute` in the attach log after the user exercises
-   the visible agent. For a widget, that log must include `local-handler:render`
-   from a real chat turn — not a hand-built `render()` call.
-6. Browser evidence came from the live target, not from hand-authored examples.
-   Neighbour fixtures still pass when they exist.
-
-## Layout
-
-- `agent/actions/` — one handler per action (`execute`, optional `render`),
-  registered in `index.ts`
-- `agent/api/` — one HTTP helper per endpoint
-- `agent/constants.ts` — agent, product, domain, plus empty `API_BASE` /
-  `AUTH_SOURCE` and `LOAD_MODE`
-- `agent/utils.ts` — configure the harness runtime and re-export it. **This is
-  the only import surface for actions.**
-- `foldspace.dev.json` — local harness target configuration
-- `docs/app-profile.md` — what is known about this app, and how it was established
-
-Do not introduce another bundler or bundle format.
-
-## What you already have
-
-Import from `../utils`. Inspect that file before implementing another
-general-purpose helper. MCP `generate_action_handler` may still emit a
-skeleton that does not import it — fix the import when you implement.
-
-| Helper | Use when | Do not use when |
-|---|---|---|
-| `apiFetch` / `apiFetchBinary` | The app's own JSON/file API, after a real 200 | Public marketing hosts (`publicFetch`); custom auth headers |
-| `publicFetch` | Unauthenticated / marketing origin | Signed-in product APIs |
-| `getAuthToken` / `parseJwt` | `AUTH_SOURCE` is `localStorage` or `cookie` | Custom header schemes — override `apiFetch` in `utils.ts` |
-| `rankBy` | User typed a name; API search is exact or ignored | Domain ranking (invoices, coverage, MasterFormat) |
-| `renderLoading` / `Empty` / `Error` / `Fatal` | Chatterblock empty/error paths | Branded cards — those stay in `agent/views/` |
-| `getAgent` | Talking to Foldspace | You need a specific instance — then `agentIds()` |
-| `armAllInstances` | Attach/bootstrap setup | Inside `execute` (can ship into `dist`; attach already arms test mode) |
-| `redact` / `mapWithConcurrency` | Logging tokens; batching fetches | — |
-
-If the observed auth is not Bearer + `localStorage`/`cookie`, stop re-exporting
-that one function and keep the rest:
-
-```ts
-export { getAgent, rankBy, renderEmpty } from "@foldspace_npm/harness/runtime";
-export { apiFetch } from "./api";
-```
-
-## Agent learnings
-
-`docs/app-profile.md` is the durable record of this app. Fill it as you probe,
-not afterwards. Other notes in `docs/` are fine for session-specific lessons.
-
-- Before similar work, read `docs/app-profile.md` and any other notes in `docs/`.
-- After non-obvious discoveries, add them to the profile (or a short extra
-  note) covering verified gotchas, failed approaches, and how they were
-  established.
-- Keep notes concise and evidence-based.
-- Do not store secrets, cookies, HAR files, browser storage, or other transient
-  session data in `docs/`.
-
-## Safety
-
-- Do not commit secrets, cookies, HAR files, browser storage, or
-  `.foldspace-dev/`.
-- Local handler changes are not cloud publication.
-- Creating or publishing Foldspace resources requires explicit approval.
-- Action keys and parameter names must match the published schema.
-- Search Foldspace documentation before asserting unfamiliar platform
-  behaviour.
+Observed API, auth, and account facts for this app live in `docs/app-profile.md`.

package/templates/agent-starter/README.md

@@ -28,7 +28,7 @@ agent/
   utils.ts     Foldspace agent lookup
 docs/          optional notes for coding-agent learnings (create when needed)
 foldspace.dev.json
-CLAUDE.md
+CLAUDE.md          imports platform instructions from the installed harness
 ```
 
 ## Agent learnings