@foldspace_npm/harness 0.1.24 → 0.1.26

package/CLAUDE.md

@@ -21,12 +21,15 @@ something they can **see on their own page** — not at "it builds".
    project `CLAUDE.md` does not contain
    `@node_modules/@foldspace_npm/harness/CLAUDE.md`, ask before
    `foldspace upgrade --refresh-instructions`.
-2. **Is Foldspace connected? Check — never assume.** Call `list_agents`:
+2. **Is Foldspace connected? Check — never assume.** `region` in
+   `foldspace.dev.json` (absent means `us`) picks the server: `foldspace`, or
+   `foldspace-eu` for `eu`. Use that server's tools all session. Call its
+   `list_agents`:
 
    | Result | Do |
    |---|---|
-   | The tool does not exist | The Foldspace MCP is not installed in this editor. Give the one install step for *this* editor — Claude Code: `claude plugin install foldspace-agent-builder@foldspace-plugins`; anything else: the MCP block on <https://foldspace.ai/agents.md> — then check again |
-   | It exists but fails on auth | Installed, not signed in. Only the human can approve sign-in. Tell them exactly where — Claude Code: `/mcp` → **foldspace** → finish in the browser — then check again |
+   | The tool does not exist | The Foldspace MCP is not installed in this editor. Give the one install step for *this* region and editor — **EU**, any editor: the MCP block on <https://foldspace.ai/eu/agents.md>, never the plugin. **US** — Claude Code: `claude plugin install foldspace-agent-builder@foldspace-plugins`; anything else: the MCP block on <https://foldspace.ai/agents.md>. Then check again |
+   | It exists but fails on auth | Installed, not signed in. Only the human can approve sign-in. Tell them exactly where — Claude Code: `/mcp` → **foldspace-eu** (**EU**) or **foldspace** (**US**) → finish in the browser — then check again |
    | It returns agents | One agent: state its name, Agent Key and product in a line and carry on; the human objects if it is wrong. Several: ask which, as a choice |
 
 3. **Orient** — `get_agent_settings`, `list_actions`, `list_task_agents`,
@@ -78,9 +81,11 @@ current CLI contract — risk, prerequisites, effects, next step.
    one that creates data - say so instead.
 
 **Say when the test window is yours, and when it is theirs - on the page and
-in chat.** You and the human share one Chrome window. Before you start looking
-at the app or testing in it, run `npx foldspace badge working` (a bar across
-the top of the window says Foldspace is building here, leave it alone) and say
+in chat.** You and the human share one Chrome window. `observe` and `ask`
+raise the working pill by themselves for as long as they run, and drop it
+after. For the longer stretch - from the moment you start working on their
+window until it is their turn - run `npx foldspace badge working` (the pill at
+the foot of the window says Foldspace is building here, leave it alone) and say
 so in chat: *"I'm going to work in that Chrome window for a few minutes -
 please leave it alone until I tell you it's ready."* When it is their turn,
 `npx foldspace badge ready` takes the pill away (the small corner tag comes
@@ -487,10 +492,15 @@ Each of these cost a real build.
 - **A card matches the panel, not the page.** The card sits in the agent's
   panel - white by default (the agent's theme: `backgroundColor #FFFFFF`,
   `primaryColor` for accents; a `darkTheme` when the panel is dark, and the
-  panel follows the OS colour scheme, not the app's own toggle). `observe
-  styles` samples the page: a dark app gives a dark card in a white panel
-  (seen 2026-09-22). Start from the recipe palettes, put the agent's
-  `primaryColor` in `accent`, and take only font and radius from the page.
+  panel follows the OS colour scheme, not the app's own toggle). **Before the
+  first card, make the brand reference:** `npx foldspace observe styles
+  --write` samples the app's own accent, text, border, font and radius and
+  writes `agent/views/brand.ts` for the panel's white surface - every card
+  imports it, and the recipes' `brand.ts` files are placeholders for it. A
+  dark app keeps its accent and font; its light-on-dark text would vanish on
+  white, so that falls back to greys and the file says so. Record where the
+  values came from in the profile's Brand section. Never copy colours by eye
+  (seen 2026-09-22: a dark card in a white panel).
 - **Plain hex or rgba only.** The panel saves every card to the conversation
   history as an image drawn with html2canvas, which cannot read `oklch()`,
   `lab()` or `color-mix()`: one such value and the saved card is blank

package/README.md

@@ -118,6 +118,12 @@ 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 app domain may be a hostname
 or an HTTP(S) URL without a port or path.
 
+`--region us|eu` (default `us`) is the Foldspace region the account lives in.
+It is written to `foldspace.dev.json` as `region`, and picks the SDK the
+project loads (`sdkUrl`): each region has its own build, pointing at that
+region's servers. A project with no `region` is US. The values per region live
+in `src/region.mjs`.
+
 For safety, `init` requires a target path that does not exist. It does not
 initialize Git or overwrite files. On a TTY it can offer
 `npm install --ignore-scripts` after scaffolding. After creation:

package/bin/ask.mjs

@@ -27,6 +27,7 @@ import {
 import { ATTACH_DAEMON_LOG_FILE } from "../src/attach-daemon.mjs";
 import { CdpPage, parseArgs, printJson, sleep } from "../src/cdp-client.mjs";
 import { recordEvent } from "../src/session-events.mjs";
+import { withWorkingBadge } from "../src/badge-auto.mjs";
 import { resolveProjectDir } from "../src/upgrade.mjs";
 
 const PANEL_ID = "eucera-agent-iframe";
@@ -300,11 +301,15 @@ async function main() {
 
   let attempts = 0;
   let turn;
-  do {
-    if (attempts > 0) await sleep(everyS * 1000);
-    turn = await askOnce();
-    attempts += 1;
-  } while (turn.sent && shouldRetry({ ...turn, attempts, retries }));
+  // The working pill is up while the question is typed and answered - the
+  // human must not type into the same composer - and down before the pictures.
+  await withWorkingBadge(page, async () => {
+    do {
+      if (attempts > 0) await sleep(everyS * 1000);
+      turn = await askOnce();
+      attempts += 1;
+    } while (turn.sent && shouldRetry({ ...turn, attempts, retries }));
+  });
 
   if (!turn.sent) {
     finish({ ok: false, question, reason: "Could not type into the composer.", attempts, url }, 1);

package/bin/observe.mjs

@@ -23,6 +23,7 @@ import path from "node:path";
 
 import { CdpPage, parseArgs, printJson, readLaunchState, sleep } from "../src/cdp-client.mjs";
 import { withoutStealingFocus } from "../src/keep-focus.mjs";
+import { withWorkingBadge } from "../src/badge-auto.mjs";
 import {
   NAV_ITEM_SELECTOR,
   NAV_SCOPE_SELECTOR,
@@ -41,6 +42,7 @@ import {
   rankCandidates,
   readHint,
   refuseWriteFlags,
+  brandFile,
   gotoDestination,
   pageCoverage,
   uncoveredSiblings,
@@ -56,7 +58,7 @@ const SUBCOMMANDS = {
   screen: { values: ["click", "goto", "match", "wait"], flags: [] },
   read: { values: [], flags: [] },
   auth: { values: ["wait"], flags: [] },
-  styles: { values: [], flags: [] },
+  styles: { values: [], flags: ["write"] },
   screenshot: { values: ["out"], flags: [] },
   "wait-login": { values: ["timeout"], flags: [] },
 };
@@ -591,7 +593,7 @@ function lowerKeys(wire = {}, pageSet = {}) {
   return Object.fromEntries(Object.entries(wire).filter(([name]) => !known.has(name.toLowerCase())));
 }
 
-async function runStyles(page) {
+async function runStyles(page, flags = {}) {
   const raw = await page.evaluate(`
     ${VISIBLE_JS}
     const clear = (color) =>
@@ -687,7 +689,7 @@ async function runStyles(page) {
       radius: top(radii)[0] || null,
     };`);
   const { button } = raw;
-  return {
+  const report = {
     ok: true,
     url: printableUrl(raw.url),
     sampledFrom: "computed styles of visible elements",
@@ -709,6 +711,15 @@ async function runStyles(page) {
     boxRadius: raw.radius,
     body: { ...raw.body, color: toHex(raw.body.color) },
   };
+  if (!flags.write) return report;
+  // The brand reference every card imports. Written, not printed: values
+  // copied by hand drift, and re-sampling must be one command.
+  const target = path.join(projectDir, "agent", "views", "brand.ts");
+  const existed = fs.existsSync(target);
+  const { content, notes } = brandFile(report, { url: report.url, date: new Date().toISOString().slice(0, 10) });
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  fs.writeFileSync(target, content, "utf8");
+  return { ...report, wrote: path.relative(projectDir, target), replaced: existed, notes };
 }
 
 async function runScreenshot(page, flags) {
@@ -796,11 +807,14 @@ async function main() {
 
   const page = await CdpPage.open({ projectDir });
   try {
-    if (sub === "menu") return await runMenu(page);
-    if (sub === "screen") return await runScreen(page, flags);
-    if (sub === "read") return await runRead(page, flags, rest);
-    if (sub === "auth") return await runAuth(page, flags);
-    if (sub === "styles") return await runStyles(page);
+    // The working pill goes up while the harness drives the human's window,
+    // and comes down after - nobody has to remember it. Not for screenshot:
+    // the picture is for the human, and the pill would be in it.
+    if (sub === "menu") return await withWorkingBadge(page, () => runMenu(page));
+    if (sub === "screen") return await withWorkingBadge(page, () => runScreen(page, flags));
+    if (sub === "read") return await withWorkingBadge(page, () => runRead(page, flags, rest));
+    if (sub === "auth") return await withWorkingBadge(page, () => runAuth(page, flags));
+    if (sub === "styles") return await withWorkingBadge(page, () => runStyles(page, flags));
     return await runScreenshot(page, flags);
   } finally {
     page.close();

package/package.json

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

package/src/attach-preflight.mjs

@@ -4,6 +4,7 @@ import {
   parseActionRequest,
 } from "./attach-helpers.mjs";
 import { ERROR_CODES } from "./protocol.mjs";
+import { SDK_SCRIPT_HOSTS } from "./region.mjs";
 
 export function productIdFromAgentKey(key) {
   if (typeof key !== "string") return null;
@@ -135,7 +136,7 @@ function sdkScriptIdentity(url) {
     const parsed = new URL(url);
     if (
       parsed.protocol !== "https:" ||
-      parsed.hostname !== "script.eucerahive.io" ||
+      !SDK_SCRIPT_HOSTS.includes(parsed.hostname) ||
       !/^\/web\/sdk\/(?:foldspace|eucera)\.js$/i.test(parsed.pathname)
     ) {
       return null;

package/src/badge-auto.mjs

@@ -0,0 +1,42 @@
+// The working pill, raised by the harness itself while it drives the shared
+// window. `foldspace badge working` exists so the human knows when to leave the
+// window alone - and across a long session of observe and ask it was never
+// set, so both drove the same window (raised by the human, 2026-09-29). The
+// commands know when they are about to drive it, so they raise the pill for
+// as long as they run and put back whatever was there. A pill the agent set
+// on purpose is left alone.
+
+export const BADGE_KEY = "__foldspace_badge__";
+
+export async function readBadge(page) {
+  try {
+    const raw = await page.evaluate(`return sessionStorage.getItem(${JSON.stringify(BADGE_KEY)});`);
+    return raw ? JSON.parse(raw) : null;
+  } catch {
+    return null;
+  }
+}
+
+export async function writeBadge(page, payload) {
+  await page.evaluate(
+    `sessionStorage.setItem(${JSON.stringify(BADGE_KEY)}, ${JSON.stringify(JSON.stringify(payload))}); return true;`,
+  );
+}
+
+/** Run `action` with the working pill up, then restore what was there before. */
+export async function withWorkingBadge(page, action) {
+  const before = await readBadge(page);
+  if (before?.state === "working") return action(); // set on purpose: theirs to drop
+  let raised = false;
+  try {
+    await writeBadge(page, { state: "working", auto: true });
+    raised = true;
+  } catch {
+    // no badge script on this page (attach not running): nothing to raise
+  }
+  try {
+    return await action();
+  } finally {
+    if (raised) await writeBadge(page, before ?? { state: "label" }).catch(() => {});
+  }
+}

package/src/cli-registry.mjs

@@ -1,5 +1,6 @@
 import { diagnosticCatalogue } from "./diagnostics.mjs";
 import { HARNESS_PROTOCOL_VERSION } from "./protocol.mjs";
+import { DEFAULT_REGION, REGION_NAMES } from "./region.mjs";
 
 export const CLI_SCHEMA_VERSION = 1;
 
@@ -21,7 +22,8 @@ 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>] [--app-domain <host>] [--name <display-name>]",
+      "foldspace init [<directory>] [--product-id <id>] [--agent-key <key>] [--app-domain <host>] [--name <display-name>] " +
+      `[--region <${REGION_NAMES.join("|")}>]`,
     risk: "local-write",
     environment: "node",
     environmentVariables: [],
@@ -48,6 +50,12 @@ export const CLI_COMMANDS = Object.freeze([
       value("--name", "display-name", "Display name", {
         default: "directory name",
       }),
+      value(
+        "--region",
+        REGION_NAMES.join("|"),
+        "Foldspace region of the account; sets the SDK the project loads",
+        { default: DEFAULT_REGION, choices: REGION_NAMES },
+      ),
     ],
     prerequisites: [
       "Node 20 or newer",
@@ -306,10 +314,11 @@ export const CLI_COMMANDS = Object.freeze([
     ],
     options: [
       value("--click", "label", "screen: reach the screen by a navigation label, as a person would"),
-      value("--goto", "path", "screen: a same-origin path"),
+      value("--goto", "path", "screen: a path on this host, or a full https address on a host this project names"),
       value("--match", "words", "screen: rank the requests seen by these words"),
       value("--wait", "ms", "screen/auth: how long to keep listening"),
       value("--out", "file", "screenshot: where to save the PNG"),
+      flag("--write", "styles: write agent/views/brand.ts - the brand reference every card imports"),
       value("--timeout", "seconds", "wait-login: give up after this long", { default: "600" }),
     ],
     prerequisites: ["foldspace inject has opened the test window"],
@@ -317,6 +326,7 @@ export const CLI_COMMANDS = Object.freeze([
       "GET only. Never submits a form; clicks navigation elements only",
       "Prints names, shapes and counts - never values, tokens or cookies",
       "Works while foldspace attach is running",
+      "Raises the working pill on the window while it runs (not for screenshot), and drops it after",
     ],
     next: ["Record what you established in docs/app-profile.md", "Write the handler"],
   }),

package/src/init.mjs

@@ -5,6 +5,7 @@ import readline from "node:readline/promises";
 import { stdin as input, stdout as output } from "node:process";
 import { fileURLToPath } from "node:url";
 import { commandByName } from "./cli-registry.mjs";
+import { DEFAULT_REGION, REGIONS, parseRegion } from "./region.mjs";
 
 const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const defaultTemplateRoot = path.join(packageRoot, "templates", "agent-starter");
@@ -15,6 +16,7 @@ const allowedFlags = new Set([
   "agent-api-name",
   "app-domain",
   "domain",
+  "region",
 ]);
 const tokenPattern = /\{\{([A-Z0-9_]+)\}\}/g;
 const defaultDirectory = "foldspace-agent";
@@ -99,6 +101,9 @@ export function parseInitArgs(argv) {
     productId: flags["product-id"] || null,
     agentApiName: flags["agent-key"] || flags["agent-api-name"] || null,
     domain: flags["app-domain"] || flags.domain || null,
+    // Checked here, before any prompt: a typo must not cost a whole
+    // interactive run and then fail at the end.
+    region: flags.region ? parseRegion(flags.region) : null,
   };
 }
 
@@ -275,6 +280,7 @@ function finalizeInitConfig(parsed) {
     productId: parsed.productId,
     agentApiName: parsed.agentApiName,
     domain: parsed.domain,
+    region: parsed.region || DEFAULT_REGION,
   };
 }
 
@@ -300,6 +306,7 @@ function createTemplateValues(config, harnessVersion) {
 
   const productId = validateProductId(config.productId);
   const agentApiName = validateIdentifier(config.agentApiName, "Agent Key");
+  const region = parseRegion(config.region || DEFAULT_REGION);
   const target = normalizeTarget(config.domain);
   const hosts =
     target.domain === "localhost" || /^\d+(?:\.\d+){3}$/.test(target.domain)
@@ -319,6 +326,8 @@ function createTemplateValues(config, harnessVersion) {
     START_URL: target.startUrl,
     START_URL_JSON: JSON.stringify(target.startUrl),
     HOSTS_JSON: JSON.stringify(hosts),
+    REGION_JSON: JSON.stringify(region),
+    SDK_URL_JSON: JSON.stringify(REGIONS[region].sdkUrl),
     HARNESS_VERSION: harnessVersion,
   };
 }

package/src/observe-core.mjs

@@ -705,8 +705,46 @@ export function looksLoggedIn({ url, hasPasswordField = false, hosts = [] }) {
 // ---------------------------------------------------------------- styles
 
 /** 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.
+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;
+  const number = (value, scale = 1) => (value.endsWith("%") ? (Number(value.slice(0, -1)) / 100) * scale : Number(value));
+  const L = number(match[2]);
+  let a;
+  let b;
+  if (match[1].toLowerCase() === "oklch") {
+    const C = number(match[3], 0.4);
+    const H = (Number(match[4]) * Math.PI) / 180;
+    a = C * Math.cos(H);
+    b = C * Math.sin(H);
+  } else {
+    a = number(match[3], 0.4);
+    b = number(match[4], 0.4);
+  }
+  const l = (L + 0.3963377774 * a + 0.2158037573 * b) ** 3;
+  const m = (L - 0.1055613458 * a - 0.0638541728 * b) ** 3;
+  const s = (L - 0.0894841775 * a - 1.291485548 * b) ** 3;
+  const linear = [
+    4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s,
+    -1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s,
+    -0.0041960863 * l - 0.7034186147 * m + 1.707614701 * s,
+  ];
+  const channel = (c) => {
+    const v = c <= 0.0031308 ? 12.92 * c : 1.055 * Math.max(c, 0) ** (1 / 2.4) - 0.055;
+    return Math.max(0, Math.min(255, Math.round(v * 255))).toString(16).padStart(2, "0");
+  };
+  const hex = `#${linear.map(channel).join("")}`;
+  const alpha = match[5] === undefined ? 1 : number(match[5]);
+  return alpha >= 1 ? hex : `${hex}${Math.round(alpha * 255).toString(16).padStart(2, "0")}`;
+}
+
 export function toHex(cssColor) {
   const text = String(cssColor || "").trim();
+  const ok = okToHex(text);
+  if (ok) return ok;
   const match = /^rgba?\(\s*([\d.]+)[\s,]+([\d.]+)[\s,]+([\d.]+)(?:\s*[,/]\s*([\d.]+%?))?\s*\)$/i.exec(text);
   if (!match) return text || null;
   const channel = (value) =>
@@ -720,3 +758,69 @@ export function toHex(cssColor) {
   const hex = `#${channel(match[1])}${channel(match[2])}${channel(match[3])}`;
   return alpha >= 1 ? hex : `${hex}${channel(alpha * 255)}`;
 }
+
+// ------------------------------------------------------------ brand file
+
+function luminance(hex) {
+  const m = /^#([0-9a-f]{2})([0-9a-f]{2})([0-9a-f]{2})/i.exec(String(hex || ""));
+  if (!m) return null;
+  const [r, g, b] = [m[1], m[2], m[3]].map((part) => parseInt(part, 16) / 255);
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
+
+const isHex = (value) => /^#[0-9a-f]{6}([0-9a-f]{2})?$/i.test(String(value || ""));
+
+/**
+ * `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
+ * would vanish on white, so those fall back to neutral greys and say so.
+ */
+export function brandFile(styles, { url, date, agentPrimary } = {}) {
+  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}`);
+    return fallback;
+  };
+  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");
+  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 font = String(styles.fontFamily || "").replace(/["'\\]/g, "").trim() || "Roboto, sans-serif";
+  const radius = /^\d+(\.\d+)?px$/.test(String(styles.boxRadius || "")) ? styles.boxRadius : "8px";
+  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().",
+    `// 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}",`,
+    "} as const;",
+    "",
+  ];
+  return { content: lines.join("\n"), notes, values: { text, muted, border, accent, accentText, font, radius } };
+}

package/src/region.mjs

@@ -0,0 +1,54 @@
+// The Foldspace regions a project can live in. Everything region-specific in
+// the harness comes from here: init writes `region` and its `sdkUrl` into
+// foldspace.dev.json, attach recognizes the SDK on every region's script host,
+// and the startup step in CLAUDE.md names each region's server and playbook.
+//
+// `sdkUrl`: each region has its own SDK build. Same code, but its config
+// 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
+// installs it. Distinct per region, so both can sit side by side.
+export const REGIONS = Object.freeze({
+  us: Object.freeze({
+    label: "US",
+    sdkUrl: "https://script.eucerahive.io/web/sdk/foldspace.js",
+    server: "foldspace",
+    playbook: "https://foldspace.ai/agents.md",
+  }),
+  eu: Object.freeze({
+    label: "EU",
+    sdkUrl: "https://script.eu.eucerahive.io/web/sdk/foldspace.js",
+    server: "foldspace-eu",
+    playbook: "https://foldspace.ai/eu/agents.md",
+  }),
+});
+
+// Projects created before regions existed have no `region`: they are US.
+export const DEFAULT_REGION = "us";
+
+export const REGION_NAMES = Object.freeze(Object.keys(REGIONS));
+
+export function isRegion(value) {
+  return typeof value === "string" && Object.hasOwn(REGIONS, value);
+}
+
+export function parseRegion(value) {
+  const region = typeof value === "string" ? value.trim().toLowerCase() : value;
+  if (!isRegion(region)) {
+    throw new Error(
+      `Unknown region: ${value}. Use one of: ${REGION_NAMES.join(", ")}.`,
+    );
+  }
+  return region;
+}
+
+// The region a foldspace.dev.json belongs to.
+export function regionOf(config) {
+  return REGIONS[parseRegion(config?.region ?? DEFAULT_REGION)];
+}
+
+// Hostnames the Foldspace SDK is served from, in any region.
+export const SDK_SCRIPT_HOSTS = Object.freeze(
+  REGION_NAMES.map((name) => new URL(REGIONS[name].sdkUrl).hostname),
+);

package/src/upgrade.mjs

@@ -307,7 +307,12 @@ export function checkForUpdate(projectDir, options = {}) {
   } else if (skipped) {
     status = "check_skipped";
   } else {
-    const cached = options.cache === false ? null : readCache(projectDir, now);
+    // `fresh` asks the registry whatever was remembered, and still writes the
+    // 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).
+    const cached =
+      options.cache === false || options.fresh === true ? null : readCache(projectDir, now);
     const cachedDeprecation =
       cached?.deprecation?.version === running ? cached.deprecation : null;
     if (cached?.latest && cachedDeprecation) {
@@ -445,7 +450,7 @@ export async function runUpgrade(argv, options = {}) {
     );
   }
 
-  const report = checkForUpdate(projectDir, options);
+  const report = checkForUpdate(projectDir, { ...options, fresh: options.fresh ?? true });
 
   if (parsed.checkOnly || (!parsed.yes && !isInteractive(options) && !parsed.refreshInstructions)) {
     return report;

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

@@ -1,7 +1,8 @@
 {
   "$comment": "Generated by foldspace init. Use the bare product ID, not the EU-… SDK key.",
   "defaultTarget": "app",
-  "sdkUrl": "https://script.eucerahive.io/web/sdk/foldspace.js",
+  "region": {{REGION_JSON}},
+  "sdkUrl": {{SDK_URL_JSON}},
   "targets": {
     "app": {
       "name": "App",