@foldspace_npm/harness 0.1.33 → 0.1.34

package/CLAUDE.md

@@ -11,15 +11,23 @@ session ends at something they can **see on their own page** - not at
 ## Every session starts the same way
 
 1. **Harness version.** Run `npx foldspace help --json` (from an older install,
-   `npx --yes @foldspace_npm/harness@latest upgrade --check`). If
-   `update.outdated` is true, say which version the project is on and which is
-   newest, and **ask before upgrading**; then `npx foldspace upgrade --yes` and
-   `npm run build`. Never upgrade as a side effect of build, attach or
-   implementing an action. `build` and `attach` check too: on an older version
-   they print one line and carry on; on a version Foldspace **withdrew** they
-   refuse to run and say why. Tell the human the reason and ask to upgrade.
-   Only if they decide not to, rerun with `FOLDSPACE_SKIP_UPDATE_CHECK=1` -
-   never set it on your own. If the project `CLAUDE.md` does not contain
+   `npx --yes @foldspace_npm/harness@latest upgrade --check`). Several people
+   can build one agent, so every session runs the newest harness:
+   - **`update.autoUpgrade` is true** - a newer version in the same line, such
+     as 0.1.30 to 0.1.34. Run `npx foldspace upgrade --yes` and
+     `npm run build` without asking, and tell the human in one line: *"I've
+     updated the Foldspace tools to the newest version."*
+   - **`update.outdated` is true, `autoUpgrade` is not** - the newest is a new
+     line (0.1 to 0.2). Say which version the project is on and which is
+     newest, and **ask before upgrading**; then the same two commands.
+
+   `build` and `attach` never upgrade by themselves. They check too: on an
+   older version they print one line and carry on - upgrade then, the same
+   way. On a version Foldspace **withdrew** they refuse to run and say why:
+   within the line, upgrade without asking; across a line, tell the human the
+   reason and ask. Only if they decide not to, rerun with
+   `FOLDSPACE_SKIP_UPDATE_CHECK=1` - never set it on your own. If the project
+   `CLAUDE.md` does not contain
    `@node_modules/@foldspace_npm/harness/CLAUDE.md`, ask before
    `npx foldspace upgrade --refresh-instructions`.
 2. **Is Foldspace connected? Check — never assume.** `region` in
@@ -49,22 +57,18 @@ session ends at something they can **see on their own page** - not at
    shows them.
    - **A code project.** Call `repo_read` with command `instructions` and
      follow what it returns. The project's `agent/` is the copy Foldspace
-     builds and publishes, and it may hold work someone else saved. Before you
-     build, replace this folder's `agent/` with it (`repo_read` commands `tree`
-     and `file`, with the `ref` the instructions name - the default can be
-     older than what someone saved): delete what is there rather than copying
-     over the top, or their page shows the template instead of their agent.
-     This folder's `agent/` may hold work a session never saved, so copy it to
-     `.foldspace-dev/agent-kept/` first. Put back the action files the project
-     lacks; where a file differs, the project's wins. If any differed, tell
+     builds and publishes, and it may hold work someone else saved. Before
+     you build, pull it into this folder (**Several builders, one agent**):
+     `npx foldspace sync` replaces the template with their agent, keeps a copy of this folder's
+     `agent/` in `.foldspace-dev/agent-kept/`, and puts back unsaved action
+     files the project lacks. Where a file differs, the project's wins: tell
      the human in one line which actions had changes on this computer that
      were never saved.
    - **`NO_REPO`.** Nothing is saved yet. Follow the next step `status` gives:
      it creates the code project in about a minute and changes nothing anyone
      sees - say you are setting up their project, no need to ask. Get the agent
      live in this folder meanwhile (L0 needs no code). Once `status` shows the
-     project, replace this folder's `agent/` with its `agent/` as above, before
-     you write the first action.
+     project, pull its `agent/` as above, before you write the first action.
    - **A refusal that names `foldspace-ai-access`.** This agent has saved
      code that Foldspace has not opened to these tools; that is final. Tell
      the human that Foldspace manages their agent's saved code, so this build
@@ -145,19 +149,29 @@ marks their turn: they may type whatever, whenever; the pill only ever asks them
 to wait. `npx foldspace badge label` puts the small corner tag back;
 `npx foldspace badge off` removes it, for a screenshot they will share.
 
-**After they have tried it, the second wave: tell Foldspace who the user is
-(item 3 - no question, one line in chat), and offer the rest as one choice,
-recommended first.** Once you have handed over (`badge ready`), the human has
-asked the agent the question and - with a code project - you have taken the
-steps in **Done, and what you say at the end**:
+**After they have tried it, the second wave: write the page starters (item 2)
+and tell Foldspace who the user is (item 3) - no question, one line in chat
+each - and offer the rest as one choice, recommended first.** Once you have
+handed over (`badge ready`), the human has asked the agent the question and -
+with a code project - you have taken the steps in **Done, and what you say at
+the end**:
 
 1. **Starters.** The sign-up starters point at actions the agent does not have
    (clicking one answers "that action isn't available"): replace them with the
    question this experience answers. `set_conversation_starters` replaces the
-   whole set - send the full list. Their account, so their yes.
-2. **The bottom bar** - `recipes/bottom-bar`: the agent's resting place at the
-   foot of the page, with starters that change per screen. Ships in this
-   project's start-up code; nothing in their source changes.
+   whole set - send the full list, **at most 3**, each in the right group
+   (**How the agent looks and opens is configuration**). Their account, so
+   their yes.
+2. **Page starters** - `recipes/bottom-bar`. Foldspace already shows the bar
+   at the foot of the page; this picks what it offers on each screen. It
+   ships in this project's start-up code; nothing in their source changes.
+   1. `npx foldspace observe menu` lists the main-menu pages.
+   2. For each page, write at most 3 starters the agent can answer today.
+      Early on most pages have none: leave them out, and they keep Agent
+      Studio's starters.
+   3. `ACTION` when clicking it runs an action, `KNOWLEDGE` when the answer
+      comes from the knowledge base.
+   4. `npm run build`, attach, and look at one page that has starters.
 3. **Tell Foldspace who the user is** - `recipes/who-is-the-user`: from then on
    their conversations and analytics stop being anonymous, and the agent has
    real-time context about who it is talking to.
@@ -184,7 +198,7 @@ Every question to the human is an **enumerated choice with the recommended
 option first** (in Claude Code, `AskUserQuestion`; elsewhere, the editor's own question tool), asked once - not repeated in your message. A first session asks only
 this: which agent (only if several), the app's hostname, which experience
 first - and a yes wherever this manual asks for one, such as agreeing the
-experience (below), upgrading, publishing an action, task agent or
+experience (below), upgrading to a new line (0.1 to 0.2), publishing an action, task agent or
 navigation, publishing their code for their users, replacing their starters or
 adding hosts. The hostname is the only free-text question. Everything else -
 attach mode, folder, name, level - you **state and move on**.
@@ -229,6 +243,42 @@ command refuses the window.
   with both, the user sees an extra message and the agent takes a second
   turn.
 
+## Each customer on their own subdomain
+
+Some products give each of their customers their own address -
+`acme.example.com`, `globex.example.com` - and often a backend that carries
+it too (`acme.api.example.com`). You build signed in to **one** of those
+customers, and the code goes to **all** of them: an address you copy as you
+saw it sends every user's agent to that one customer's data.
+
+- **Find out before you write `API_BASE`.** `npx foldspace observe menu` and
+  `observe screen` report `customerSubdomain` when the page's address starts
+  with what looks like a customer's name, and `screen` names the backend
+  calls that carry it too. Ask the human once, as a choice: *"Does each of
+  your customers get their own address, like acme.example.com?"* Never decide
+  it from the address alone - `reports.` or `eu1.` is a part of the product,
+  and only they know.
+- **Write their answer** in `agent/constants.ts`:
+  `PER_CUSTOMER_SUBDOMAIN = true` or `false`. Until it is set, observe keeps
+  asking and the build refuses an address that may be one customer's.
+- **With `true`, `API_BASE` is built from the page's address**, at run time,
+  in the user's own browser:
+  - the backend is on the page's own host - `API_BASE = "/api"`;
+  - the backend's address carries the customer - write it with
+    `{subdomain}` where their name was:
+    `API_BASE = "https://{subdomain}.api.example.com"`;
+  - one backend for every customer (`api.example.com`, the customer known
+    from the sign-in) - the address as it is.
+
+  The runtime puts each user's own subdomain in (`apiBaseUrl()`), and
+  `apiFetch` uses it. A page whose address has no subdomain gets `reason:
+  "config"`, never another customer's backend.
+- **Nothing else names one customer either:** a link is a path (`"/invoices/42"`),
+  never `https://acme.example.com/invoices/42`. The build refuses one
+  customer's address anywhere in `agent/` (`no-fixed-customer-address`).
+- **Record it** in `docs/app-profile.md`: what the human said, and the
+  address you observed, with the customer's name marked as theirs.
+
 ## Find the call yourself
 
 Never guess `API_BASE`, `AUTH_SOURCE`, an endpoint or a schema. But guessing
@@ -280,7 +330,8 @@ GET only, never submit a form, never click anything that creates, sends or
 deletes.
 
 Capture at least one real HTTP 200 for the data the action needs. If there is
-none, pivot; do not create Foldspace resources. Write what you establish into
+none, pivot; do not create Foldspace resources. Before that address goes into
+`API_BASE`, settle **Each customer on their own subdomain**. Write what you establish into
 `docs/app-profile.md` **with how you know it**, at that moment. Do not promote
 an assumption by quoting that file later.
 
@@ -428,6 +479,33 @@ of the human's, read the attach log for the `[actions]` SDK callback and local
 execute/render lines. Those record names, statuses, durations and parameter
 keys only - never results or error bodies.
 
+## Several builders, one agent
+
+With a code project, other people - or other machines - may save to the same
+agent while you work. So this folder pulls the saved code again whenever
+someone saved since it last did. Saving and publishing stay exactly as
+`repo_read` command `instructions` says; this only keeps `agent/` current.
+
+**Pull at session start (step 5), before each new experience, and before each
+save or publish:**
+
+1. `repo_read` `status` gives `develop_head`. Then `repo_read` `tree` with
+   `ref` `foldspace/<Agent Key>` - the line of work the instructions save to -
+   gives its head (the sha after the ref). If that line does not exist yet,
+   nothing has been saved to it: use `develop` only.
+2. `npx foldspace sync check --develop <develop_head>`, plus
+   `--line <its head>` when the line exists. Its `baseSha` is the `base_sha`
+   for your next save, as the instructions say.
+3. If `pull` lists anything: read `agent/` at each `ref` (`tree` and `file`)
+   into its `into` folder, same paths (`<into>/agent/actions/x.ts`). Then
+   `npx foldspace sync apply`, and do what its `next` says. Files under
+   `conflicts` changed both here and in the saved code: they now hold the
+   saved version - put your change back on top from the kept copy. Then build.
+
+**After each save**, `npx foldspace sync saved --head <commit_sha> --paths
+<committed_paths, comma-separated>`, so your own save is not taken for
+someone else's.
+
 ## Done, and what you say at the end
 
 A first session is done when the customer has seen one experience answer from
@@ -438,9 +516,16 @@ gates pass, and not when there is nothing left to improve.
 their users is yours to do. Once they have tried it in the test window, before
 you offer the second wave:
 
-1. Say *"I'm saving your changes and publishing them to dev"* - no need to
-   ask - then save with `repo_write` and publish with the `deploy` tool, the
-   way `repo_read` command `instructions` says. One exception: a dev preview
+1. Before **every** save, review the experience with the
+   `review-experience` skill (`.claude/skills/review-experience/SKILL.md`;
+   any other editor: read
+   `node_modules/@foldspace_npm/harness/templates/agent-starter/skills/review-experience/SKILL.md`):
+   only the data the answer needs, a yes from the user before every write,
+   nothing the user cannot reach in the product. A serious finding stops the
+   save until it is fixed. Then say *"I'm saving your changes and publishing
+   them to dev"* - no need to
+   ask - then pull (**Several builders, one agent**), and save and publish
+   the way `repo_read` command `instructions` says. One exception: a dev preview
    that comes back with no warnings means this agent loads dev for its users -
    then ask first, as for production. In chat it is "saving your changes",
    "publishing to dev" and "publishing for your users" - never GitHub,
@@ -466,8 +551,8 @@ with `--bootstrap` or `--replace`, it does not yet: do step 1, keep attach
 running, and give the answer below for the rest - their site loading the agent
 is the step the Foldspace team does with them.
 
-A save refused because someone saved after you read is not final: the
-instructions say how to redo it. Any other refusal from the Foldspace tools
+A save refused because someone saved after you read is not final: pull again
+(**Several builders, one agent**), put your change on top and save. Any other refusal from the Foldspace tools
 here is final: then the answer below.
 
 **Without a code project**, the answer to *"how do I put this in front of my
@@ -489,7 +574,9 @@ Do not report success without all six:
 
 1. `npm run typecheck` compiles (`tsc --noEmit -p tsconfig.json`). Do not run
    `npx tsc` — it can install the wrong package.
-2. `foldspace lint` reports no errors (`foldspace build` runs it first).
+2. `foldspace lint` reports no errors (`foldspace build` runs it first). It
+   also refuses what is unsafe for the product's users - **What the build
+   refuses**, below.
 3. The handler appears in `dist/index.js`.
 4. The browser reports `inspect_registration:registration_ok`, and for a named
    action the captured registry includes it.
@@ -508,12 +595,27 @@ Do not report success without all six:
    (**Agentic UI components**).
 6. Browser evidence came from the live target, not hand-authored examples.
 
+### What the build refuses
+
+The first three are errors: the build stops, and the message says what to do
+instead. Fix the code; never work round the rule. `known-hosts-only` is a
+warning: the build goes on; mention it to the human in one line. Cards may draw
+any markup and code they need - that is what they are for.
+
+| Rule | Refuses | Do instead |
+|---|---|---|
+| `no-fixed-customer-address` | One customer's address in `API_BASE` or anywhere in `agent/`, on a product with a subdomain per customer - or one that may be, while `PER_CUSTOMER_SUBDOMAIN` is undecided | `"/api"` or `"https://{subdomain}.…"`; a path for a link (**Each customer on their own subdomain**) |
+| `token-stays-home` | The user's sign-in token returned from `execute` or a card, handed to Foldspace, logged, stored again (storage, a cookie, `window`) or sent to a host that is not the product's backend | Let `apiFetch` add it; log `redact(token)` |
+| `no-secrets` | API keys, JWTs, bearer tokens, cookie values, `.har` captures, storage dumps and `.env` files anywhere in the project | Names and where things live go in `docs/app-profile.md`; values never |
+| `known-hosts-only` | A call (`fetch`, `sendBeacon`, `WebSocket`, `XMLHttpRequest`, `publicFetch`) to a host that is neither the product's own, Foldspace's (`*.foldspace.ai`), nor named in `agent/constants.ts` | The product's backend through `apiFetch`; another host only with the human's yes, as a constant in `agent/constants.ts` |
+
 ## Rules that are not negotiable
 
 1. **Handlers return data only.** Never `directive`, `instructions`, or a
    paragraph telling the agent what to say - those live in Agent Studio.
    Never return from `execute` a token, a cookie, any other secret or
-   `ApiResult.detail` (it is for the console): the agent reads what
+   `ApiResult.detail` (it is for the console) - the build refuses the
+   user's token there (`token-stays-home`): the agent reads what
    `execute` returns for an action with no card or a view card (rule 2).
    Validate parameters and return sanitised errors.
    **What goes back to the agent states what happened - it never says what to
@@ -612,14 +714,29 @@ wins**. <https://docs.foldspace.ai/customize/configuration/>
   list. It changes their Foldspace account, so it needs their yes. Offer it in
   the second wave, replacing the sign-up starters that point at actions the
   agent does not have.
-- **Page-specific starters and the bottom bar are code** -
-  `setConversationStarters` (`null` restores Agent Studio's) and
-  `setConfiguration({ bottomBarSettings })` then `openBottomBar()`. Send one
-  whole settings group per call, as the docs do. That code lives in this
-  project's start-up (`recipes/bottom-bar`, kind `page-setup`) and ships with
-  the actions bundle, so nothing in the customer's source changes; their own
-  mount code is the other place it can live, their engineers' call. Offer it in
-  the second wave.
+  1. **At most 3, both groups together.** They are also the agent panel's
+     opening screen, and a long list buries the one that matters. When the
+     list already holds more, say which 3 you would keep and ask.
+  2. **Each in its group.** `conversation_starters` takes
+     `{"KNOWLEDGE": [{"title": ...}], "ACTION": [{"title": ...}]}`, both keys
+     always. `ACTION` when clicking it runs one of the agent's actions (it
+     shows the action icon); `KNOWLEDGE` when the answer comes from the
+     knowledge base. Starters for the experiences you built go in `ACTION`.
+  3. **`default_type`** picks the group shown first: `ACTION` when only that
+     group has starters.
+- **Page starters are code** - `setConversationStarters` (`null` restores
+  Agent Studio's), the same 3-at-most and the same two groups;
+  `npx foldspace lint` refuses more than 3. That code lives in this project's
+  start-up (`recipes/bottom-bar`, kind `page-setup`) and ships with the
+  actions bundle, so nothing in the customer's source changes; their own mount
+  code is the other place it can live, their engineers' call. The first
+  session writes them for the main-menu pages (second wave, item 2).
+- **The bottom bar is on by default** - Foldspace turns it on from its own
+  settings, so code never sends `enabled`. Send `bottomBarSettings` only for a
+  setting the human asks to change, one whole settings group per call, as the
+  docs do, with `enabled: true` in it (⚠️ whether a partial group merges with
+  Foldspace's own settings is not verified). `maxVisibleStarters` caps the
+  bar only, never the panel.
 - **An action's `execute` never calls `setConfiguration`**: a partial call from
   one can collapse the agent's panel to nothing.
 
@@ -712,7 +829,8 @@ Each of these cost a real build.
   a mismatch does not error, the action simply never fires.
 - `agent/api/` — one HTTP helper per endpoint
 - `agent/constants.ts` — agent, product, domain, plus empty `API_BASE` /
-  `AUTH_SOURCE` and `LOAD_MODE`
+  `AUTH_SOURCE`, undecided `PER_CUSTOMER_SUBDOMAIN` and `LOAD_MODE`. Any
+  host outside the product the human agreed to is named here too
 - `agent/utils.ts` — configures the harness runtime and re-exports it. **The
   only import surface for actions.**
 - `agent/runtime/` — a code project only: this harness's runtime, which every
@@ -760,6 +878,7 @@ 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 |
+| `apiBaseUrl` | Your own `apiFetch` (custom header, cookies) builds its URLs from it - `"/api"` and `{subdomain}` resolved for this page | Reading `API_BASE` or `getConfig().apiBase` directly: on a product with a subdomain per customer that is the wrong backend |
 | `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, industry classification codes) |
@@ -790,8 +909,8 @@ Import the helpers the way the project's own `agent/utils.ts` does - from
 `./runtime` - in a recipe file you copy too. `agent/runtime/` is this harness's
 runtime, copied in for that reason. A build that changes files there names
 them: save exactly those files in a save of their own as soon as the agent is
-on their page. Say you are bringing their project up to date - no need to ask,
-it changes nothing for their users. If their account cannot save, carry on.
+on their page; a save of only those files needs no `review-experience`. Say you are bringing their project up to date - no
+need to ask, it changes nothing for their users. If their account cannot save, carry on.
 Never edit a file there: the next build puts the harness's copy back. To change
 how a helper behaves, define it in `agent/utils.ts` and export it from there in
 place of the runtime's. A project with an `agent/utils/` folder has its own
@@ -830,7 +949,8 @@ import is right.
   goes. **Never widen your own access**: if something is refused for a site or
   a permission, say so and ask; do not try others.
 - Do not commit secrets, cookies, HAR files, browser storage, or
-  `.foldspace-dev/`. Nothing transient goes in `docs/`.
+  `.foldspace-dev/` - the build refuses them in the project (`no-secrets`).
+  Nothing transient goes in `docs/`.
 - Local handler changes are not cloud publication.
 - Creating or publishing Foldspace resources needs the human's yes - except
   the agent's code: creating its code project, saving to it and publishing it

package/README.md

@@ -157,11 +157,14 @@ 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 human, then bump:
+newer package does not move them: each session checks and bumps. Several
+builders can work on one agent, so within one line (0.1.x to a newer 0.1.y,
+`update.autoUpgrade`) the coding agent upgrades without asking and says so in
+one line; across a line (0.1 to 0.2) it asks the human first.
 
 ```bash
 npx --yes @foldspace_npm/harness@latest upgrade --check
-foldspace upgrade --yes   # only after the human agrees
+foldspace upgrade --yes   # within the line: no question; across a line: after the human agrees
 ```
 
 `--check` (and a non-interactive `upgrade` with no `--yes`) never installs.
@@ -180,6 +183,27 @@ FOLDSPACE_SKIP_UPDATE_CHECK=1 npm run build
 
 That turns the check off entirely; it does not fix the withdrawn version.
 
+### Keep up with the saved code
+
+With a code project, several builders can save to one agent. `foldspace sync`
+keeps a folder's `agent/` up to date: it never reaches Foldspace itself - the
+coding agent reads the saved code with the Foldspace tools and passes the
+heads it read.
+
+```bash
+npx foldspace sync check --develop <sha> [--line <sha>]          # what to pull, and where to write it
+npx foldspace sync apply                                         # merge it into agent/
+npx foldspace sync saved --head <commit_sha> --paths <a,b>       # after a save
+```
+
+`--line` is the head of `foldspace/<Agent Key>`, the line of work the code
+project's instructions save to, once it exists. `apply` keeps a copy of
+`agent/` in `.foldspace-dev/agent-kept/<time>/` and merges file by file
+against what the folder last pulled (kept in `.foldspace-dev/saved-code/`): a
+file only one side changed takes that side; a file both changed takes the
+saved version and is listed under `conflicts`. Saving and publishing are
+unchanged: they follow the code project's instructions.
+
 ### Withdrawing a release (maintainers)
 
 When a published version is broken badly enough that nobody should build on
@@ -234,6 +258,10 @@ v1 flags:
 - **error** `no-runtask-prompt` — `runTask({ data: { prompt } })` and the same keys; a customer API field named `prompt` is allowed
 - **error** `card-contract` - `awaitUserInput: true` on a view card (its `render` uses no `callback`, `cancel` or `readyState`): the chat panel ignores it, but in headless mode the agent waits for a callback that never comes
 - **error** `no-test-mode-in-bundle` - `armAllInstances` used anywhere in `agent/` (called, or handed on to be called later), or `setTestMode(...)` with anything but a literal `false`. A code project's own copy of the runtime in `agent/runtime/` is not refused for the `setTestMode` inside its `armAllInstances`
+- **error** `no-fixed-customer-address` - on a product with a subdomain per customer (`PER_CUSTOMER_SUBDOMAIN` in `agent/constants.ts`), one customer's address in `API_BASE` or anywhere in `agent/`; while that is undecided, an address whose first part looks like a customer's name (`acme.` - not `app.`, `eu1.`, `reports.`)
+- **error** `token-stays-home` - the user's sign-in token (`getAuthToken`, a session-named storage key, `document.cookie`, followed through variables and helper functions) returned from `execute` or a card, handed to Foldspace, logged, stored again, or sent to a host that is not the product's backend
+- **error** `no-secrets` - API keys, JWTs, bearer tokens, cookie values, secret-named strings, `.har` captures, storage dumps and `.env` files anywhere in the project (not `node_modules/`, `dist/`, `.foldspace-dev/`, `agent/runtime/`)
+- **warning** `known-hosts-only` - `fetch`, `sendBeacon`, `WebSocket`, `EventSource`, `XMLHttpRequest`, `publicFetch` or `import()` to an address written out whose host is neither Foldspace's (`*.foldspace.ai`), the product's (`foldspace.dev.json` hosts, `API_BASE`, the app's own domain) nor written in `agent/constants.ts`
 - **warning** `card-contract` - any other `awaitUserInput` on a view card, `awaitUserInput` on an input card (not needed), or a `render` that declares `callback`, `cancel` or `readyState` and uses none of them (the SDK treats it as a view card)
 - **warning** `no-emoji` — emoji in handler or `agent/views` string literals
 - **warning** `registry-integrity` — duplicate keys, `{ execute }` not registered, registry value missing `execute`

package/bin/inject.mjs

@@ -20,7 +20,7 @@ import {
   waitForOwnedCdp,
   writeLaunchSentinel,
 } from "../src/cdp-ownership.mjs";
-import { findChrome } from "../src/chrome-binary.mjs";
+import { findChrome, testWindowArgs } from "../src/chrome-binary.mjs";
 
 // Resolve the CONSUMING repo, not this package. FOLDSPACE_PROJECT_DIR lets a
 // hosted builder point the harness at a workspace it controls.
@@ -205,23 +205,7 @@ function nameProfile() {
 }
 nameProfile();
 
-const chromeArgs = [
-  `--user-data-dir=${profileDir}`,
-  `--remote-debugging-port=${debugPort}`,
-  // The theme only paints the isolated window Foldspace blue. SDK and action
-  // code are loaded later by attach over CDP.
-  `--load-extension=${themeDir}`,
-  `--disable-extensions-except=${themeDir}`,
-  // Chrome 136+ dropped --load-extension. Keep the legacy switch for older
-  // builds, and enable the CDP Extensions domain so we can load it at runtime.
-  "--disable-features=DisableLoadExtensionCommandLineSwitch",
-  "--enable-unsafe-extension-debugging",
-  "--no-first-run",
-  "--no-default-browser-check",
-  "--test-type",
-  "--remote-allow-origins=*",
-  startUrl,
-];
+const chromeArgs = testWindowArgs({ profileDir, debugPort, themeDir, startUrl });
 
 console.log(`\nOpening the test window - profile ${path.relative(root, profileDir)}, debugging port :${debugPort}.`);
 console.log("The human signs in there; the profile keeps what the site remembers between runs.\n");

package/bin/observe.mjs

@@ -50,6 +50,7 @@ import {
   summarizeJson,
   toHex,
 } from "../src/observe-core.mjs";
+import { customerSubdomainHint, readCustomerSubdomainSetting } from "../src/customer-subdomain.mjs";
 import { recordEvent } from "../src/session-events.mjs";
 import { resolveProjectDir } from "../src/upgrade.mjs";
 
@@ -326,6 +327,21 @@ async function runPages() {
   };
 }
 
+// Whether the project has settled PER_CUSTOMER_SUBDOMAIN in agent/constants.ts:
+// once it has, observe stops asking.
+function customerSubdomainSetting() {
+  try {
+    return readCustomerSubdomainSetting(fs.readFileSync(path.join(projectDir, "agent", "constants.ts"), "utf8"));
+  } catch {
+    return undefined;
+  }
+}
+
+function customerSubdomainFields(pageUrl, requestUrls) {
+  const found = customerSubdomainHint(pageUrl, requestUrls, customerSubdomainSetting());
+  return found ? { customerSubdomain: found } : {};
+}
+
 async function runMenu(page) {
   const perFrame = await evaluateInFrames(page, navigationScript(null));
   const seen = new Set();
@@ -351,6 +367,7 @@ async function runMenu(page) {
     count: items.length,
     items,
     ...(siblings ? { otherHosts: siblings.hosts, hostsHint: siblings.hint } : {}),
+    ...customerSubdomainFields(url, []),
     ...(items.length ? {} : { note: "No visible navigation found. The app may still be loading, or showing a login page." }),
   };
 }
@@ -440,6 +457,7 @@ async function runScreen(page, flags) {
     requestsSeen: all.filter(isApiCall).length,
     candidates: ranked,
     writesSeen: [...writes.values()].slice(0, 20),
+    ...customerSubdomainFields(url, all.filter(isApiCall).map((request) => request.url)),
     ...(ranked.length
       ? {}
       : { note: "No successful JSON GET was seen. The data may load after another click, or arrive inside the HTML." }),

package/bin/record.mjs

@@ -37,6 +37,7 @@ import {
   checkRecordingMatches,
   closeAllHeadless,
   loadRecording,
+  wideWindowNote,
   needsChrome,
   probeEncoder,
   renderInChrome,
@@ -337,6 +338,7 @@ async function compose(config, recordDir, chromePath) {
           note: `${Math.round(plan.fit.totalS)} s, longer than the ${TIMING.maxTotalS} s it should be at most, with the waits already shortened: drop a scene, or pick questions with shorter answers.`,
         }
       : {}),
+    ...(wideWindowNote(recording) ? { wideWindow: wideWindowNote(recording) } : {}),
     sceneSeconds: plan.clips.filter((clip) => clip.kind === "scene").map((clip) => Math.round(clip.durationS * 10) / 10),
     lastFrames: lastFrames(recording),
   };

package/bin/sync.mjs

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+/**
+ * foldspace sync <check|apply|saved> [options]
+ *
+ * Keeps this folder's agent/ up to date with the agent's saved code, which
+ * several builders can work on. The coding agent reads the saved code with the
+ * Foldspace tools and passes the heads it read; this command remembers what
+ * this folder last pulled (.foldspace-dev/saved-code/) and merges.
+ *
+ *   check --develop <sha> [--line <sha>]
+ *   apply
+ *   saved --head <commit_sha> --paths <a,b,...>
+ *
+ * Saving and publishing follow the code project's own instructions.
+ */
+import { resolveProjectDir } from "../src/upgrade.mjs";
+import { syncApply, syncCheck, syncSaved } from "../src/sync-core.mjs";
+
+const VALUE_FLAGS = new Set(["--develop", "--line", "--head", "--paths"]);
+
+function parse(argv) {
+  const flags = {};
+  const rest = [];
+  for (let index = 0; index < argv.length; index++) {
+    const arg = argv[index];
+    if (VALUE_FLAGS.has(arg)) flags[arg.slice(2)] = argv[++index];
+    else if (arg.startsWith("--")) throw new Error(`unknown option '${arg}'`);
+    else rest.push(arg);
+  }
+  return { flags, rest };
+}
+
+try {
+  const projectDir = resolveProjectDir();
+  const { flags, rest } = parse(process.argv.slice(2));
+  const [verb, extra] = rest;
+  if (extra) throw new Error(`unexpected argument '${extra}'`);
+  const allowed = { check: ["develop", "line"], apply: [], saved: ["head", "paths"] }[verb];
+  if (!allowed) throw new Error("usage: foldspace sync <check|apply|saved> - see foldspace help sync");
+  const stray = Object.keys(flags).find((name) => !allowed.includes(name));
+  if (stray) throw new Error(`option '--${stray}' does not go with sync ${verb}`);
+  const report =
+    verb === "check" ? syncCheck(projectDir, flags) : verb === "apply" ? syncApply(projectDir) : syncSaved(projectDir, flags);
+  process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+} catch (error) {
+  console.error(`sync: ${error instanceof Error ? error.message : String(error)}`);
+  process.exitCode = 1;
+}

package/package.json

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

package/recipes/INDEX.md

@@ -8,7 +8,7 @@ Read this whole table, then open the recipe closest to the outcome.
 | [`find-by-name`](find-by-name/) | **L2** | The agent turns a name the user said into the id the next action needs; a count when no name is given; every tie when the name is ambiguous; near-misses when nothing matches | A data action. **No card** | 3 production builds |
 | [`lookup-then-view`](lookup-then-view/) | **L2** | Show one account the user names - **start here**. One clear match: its card, no question. Several or none: the **pick-one** list - search, pages, one click - then the card: who it is, the money, open deals, people, open cases. The card action's **required** `accountId`, described as coming from the lookup, makes the agent call the lookup first. The app already hands over the id → `account-overview` | Two actions - an input card (`find_account`) and a view card (`show_account_overview`) - with their Agent Studio definitions word for word | 1 production build |
 | [`pick-from-a-list`](pick-from-a-list/) | **L2** | A clickable list, shown **only** when the user has to choose — with "none of these" and cancel | An input card: the agent waits for the user's answer | 1 production build |
-| [`bottom-bar`](bottom-bar/) | **L0** | The agent's resting entry point is a bar at the foot of the page whose starters change with the screen the user is on - configured from code, the way customers do it | Page set-up, runs once at start-up | 2 production builds |
+| [`bottom-bar`](bottom-bar/) | **L0** | The agent's resting entry point is a bar at the foot of the page (Foldspace turns it on) whose starters - at most 3 - change with the screen the user is on, set from code | Page set-up, runs once at start-up | 2 production builds |
 | [`swap-the-login-method`](swap-the-login-method/) | any | `apiFetch` for an app that authenticates with a custom header, or with cookies, instead of a bearer token | A replacement `agent/utils.ts` | 2 production builds (a third uses the default bearer token) |
 | [`account-overview`](account-overview/) | **L2** | One account on a card, when the app already hands over its id: identity, pipeline total, contacts, cases, meetings. The agent gets what the card shows. An account the user names → `lookup-then-view` | A view card: no `callback`, no `awaitUserInput` | 1 production build |
 | [`upload-contacts`](upload-contacts/) | **L4** | A CSV is previewed, then written only after the user chooses Import | An input card: the agent waits for the user's answer | 1 production build |

package/recipes/bottom-bar/README.md

@@ -5,17 +5,19 @@ page that shows a few starters and opens the agent when one is clicked. Its
 starters change with the screen the user is on, so an agent with two actions
 still looks useful everywhere.
 
-It is configured **from code** — Agent Studio has no UI for it today, and this
-is how customers set it. **Proven by 2 production builds** (one in the
-product's own source, one from the agent project behind a feature flag).
+**Foldspace turns the bar on** from its own settings - this code does not.
+What the code does is pick each page's starters.
+**Proven by 2 production builds** (one in the product's own source, one from
+the agent project behind a feature flag).
 
 ## Adapt it
 
 | In `agent/bottomBar.ts` | Change |
 |---|---|
-| `PAGE_STARTERS` | This product's screens (path prefixes) and, for each, two or three questions **its actions can answer**. A starter for something the agent cannot do is worse than none |
-| `DEFAULT_STARTERS` | What to show on any other page. It replaces the agent-wide starters there |
-| `BOTTOM_BAR_SETTINGS` | The docs' settings, except two: `enabled: true` (the docs default it to `false`, and the bar then never renders) and `maxVisibleStarters: 3` (the docs default 5). Change any of them only if the human asks |
+| `PAGE_STARTERS` | The product's main-menu screens (`npx foldspace observe menu`: path prefixes) and, for each, **at most 3 starters** the agent can answer today. A starter for something the agent cannot do is worse than none: leave that page out |
+| `ACTION` or `KNOWLEDGE` | `ACTION` when clicking it runs one of the agent's actions - the bar shows the action icon. `KNOWLEDGE` when the answer comes from what the agent knows (its knowledge base) |
+
+A page that is not listed shows Agent Studio's starters (`setConversationStarters(null)`).
 
 Then call it from the bundle's entry point:
 
@@ -30,14 +32,25 @@ installBottomBar();
 - **`setConversationStarters` replaces the whole set for the page** — both
   groups. `null` restores Agent Studio's. So always pass the full list you
   want shown.
+- **It also sets the agent panel's opening screen**, not only the bar. One
+  customer's list had 7 there. At most 3 per page, both groups together:
+  `npx foldspace lint` refuses more. `maxVisibleStarters` caps the bar only.
+- **Route changes in a single-page app don't reload**, so the starters must be
+  re-applied on navigation. The recipe uses the browser's own page-change
+  event (`navigation`'s `currententrychange`); where a browser has no
+  Navigation API (⚠️ some Safari and Firefox versions, not tried live) it
+  wraps `pushState` / `replaceState` and listens to `popstate`. It brings the
+  bar back to full only when the starters change; a navigation that keeps the
+  same starters leaves a bar that has folded to compact as it is.
+- **An older SDK may lack these calls.** The recipe then logs once in the
+  console and leaves Agent Studio's starters.
+- **No `bottomBarSettings`.** Send one only if the human asks for a setting
+  that differs from the default (the fields are on the Bottom Bar page), and
+  send `enabled: true` in the same group. ⚠️ Whether a partial group merges
+  with Foldspace's own settings is not verified.
 - **In embedded mode the bar needs `openEmbeddedCallback`**, or the bar does
   not render at all. This recipe is for the overlay agent; see the docs for
   embedded.
-- **Route changes in a single-page app don't reload**, so the starters must be
-  re-applied on navigation - this recipe wraps `pushState` / `replaceState`
-  and listens to `popstate`. It brings the bar back to full only when the
-  starters change; a navigation that keeps the same starters leaves a bar
-  that has folded to compact (after `idleTimeoutMs`) as it is.
 - **Dark mode**: the SDK's default colours do not follow a dark theme yet
   (PLG-5891, in the backlog); a product in dark mode may need `theme` /
   `darkModeSettings` set.