@foldspace_npm/harness 0.1.33 → 0.1.35

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
@@ -269,6 +319,16 @@ and asking are not the only options — **observing is, and it comes first**:
    not open a path that does something (`/logout`, `/…/delete`); and `read`
    only goes to the app's own origin, a host configured for this project, or
    an origin `screen` saw the page call.
+
+   **A button you need to look behind** (a report tile, a "View details"):
+   ask the human first, naming it - *"May I click 'Staff Overview'? It's a
+   button, so it could do something."* Only after their yes in this chat, run
+   `npx foldspace observe screen --click "Staff Overview" --human-said-yes`.
+   One yes covers that one button, once. Never pass `--human-said-yes`
+   without it. Even with a yes, observe refuses a label that reads like an
+   action (Export, Send, Delete, Run…), a form submit, a download and signing
+   out: hand those to the human. If the result has `buttonWarning`, the button
+   sent changes to the server: tell the human what, in one line, first.
 3. **Ask the human to perform the workflow** — only for what you cannot reach:
    an MFA step, a paywall, a screen that needs a record the account does not
    have, or anything that would write.
@@ -277,10 +337,11 @@ Signing in is the human's step, because `inject` launches its own Chrome
 profile (empty the first time; it keeps the sign-in after that).
 Navigating is yours. **While you drive a signed-in account you are read-only:**
 GET only, never submit a form, never click anything that creates, sends or
-deletes.
+deletes, and a plain button only after the human's yes (above).
 
 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 +489,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 +526,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 +561,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 +584,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 +605,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 +724,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 +839,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 +888,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 +919,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 +959,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

@@ -6,7 +6,7 @@
  *
  *   foldspace observe pages
  *   foldspace observe menu
- *   foldspace observe screen [--click "<label>"] [--goto /path | https://<one of this project's hosts>/path] [--match "deal stage"] [--wait 4000]
+ *   foldspace observe screen [--click "<label>" [--human-said-yes]] [--goto /path | https://<one of this project's hosts>/path] [--match "deal stage"] [--wait 4000]
  *   foldspace observe read <path-or-url>
  *   foldspace observe auth [--wait 5000]
  *   foldspace observe styles
@@ -30,6 +30,7 @@ import {
   NAV_SCOPE_SELECTOR,
   analyzeAuthHeaders,
   buildAuthSummary,
+  buttonRefusal,
   clickRefusal,
   displayUrl,
   isCandidateRequest,
@@ -50,13 +51,14 @@ 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";
 
 const SUBCOMMANDS = {
   pages: { values: [], flags: [] },
   menu: { values: [], flags: [] },
-  screen: { values: ["click", "goto", "match", "wait"], flags: [] },
+  screen: { values: ["click", "goto", "match", "wait"], flags: ["human-said-yes"] },
   read: { values: [], flags: [] },
   auth: { values: ["wait"], flags: [] },
   styles: { values: [], flags: ["write"] },
@@ -123,11 +125,16 @@ async function evaluateInFrames(page, expression, { stopWhen } = {}) {
   return values;
 }
 
-/** Page code shared by `menu` (click = null) and `screen --click`. */
-function navigationScript(clickLabel) {
+/**
+ * Page code shared by `menu` (click = null) and `screen --click`. With
+ * humanSaidYes, a plain button anywhere on the page may be clicked too, once
+ * buttonRefusal lets its label through.
+ */
+function navigationScript(clickLabel, humanSaidYes = false) {
   return `(() => {
   ${pickByLabel}
   ${clickRefusal}
+  ${buttonRefusal}
   ${VISIBLE_JS}
   const labelOf = (el) =>
     (el.innerText || el.textContent || "").replace(/\\s+/g, " ").trim() ||
@@ -180,17 +187,48 @@ function navigationScript(clickLabel) {
   }
   const want = ${JSON.stringify(clickLabel ?? null)};
   if (want === null) return { items };
+  // A button the human said yes to: screened by buttonRefusal, then clicked.
+  const clickButton = (el, item) => {
+    const why = buttonRefusal(item);
+    if (why) return { clicked: false, refused: why };
+    el.click();
+    return { clicked: true, item, button: true };
+  };
   const index = pickByLabel(items, want);
   if (index < 0) {
     const lower = want.toLowerCase();
-    const elsewhere = [...document.querySelectorAll("a, button, input[type=submit], [role=button], [role=menuitem], [role=tab], [role=link]")]
-      .some((el) => visible(el) && (labelOf(el) || el.value || "").toLowerCase().includes(lower));
+    const anywhere = [...document.querySelectorAll("a, button, [role=button], [role=menuitem], [role=tab], [role=link]")]
+      .filter((el) => visible(el) && !el.closest("form") && (labelOf(el) || "").length <= 60);
+    const elsewhere = anywhere.some((el) => (labelOf(el) || "").toLowerCase().includes(lower));
+    if (${JSON.stringify(Boolean(humanSaidYes))} && elsewhere) {
+      const found = anywhere.map((el) => ({ el, label: labelOf(el) }));
+      const at = pickByLabel(found, want);
+      if (at >= 0) {
+        const el = found[at].el;
+        const href = el.getAttribute("href");
+        if (el.tagName === "A" && href && href !== "#" && !/^javascript:/i.test(href)) {
+          return { clicked: false, refused: '"' + found[at].label + '" is a link outside the navigation: open it with --goto ' + new URL(href, location.href).pathname + "." };
+        }
+        return clickButton(el, {
+          label: found[at].label,
+          kind: kindOf(el),
+          path: null,
+          submitsForm: false,
+          download: el.hasAttribute("download"),
+          filePicker: el.matches("input[type=file], label[for]"),
+          expands: el.hasAttribute("aria-expanded") || el.hasAttribute("aria-haspopup"),
+        });
+      }
+    }
     return { clicked: false, outsideNavigation: elsewhere, available: items.map((item) => item.label) };
   }
   const refused = clickRefusal(items[index]);
-  if (refused) return { clicked: false, refused };
-  elements[index].click();
-  return { clicked: true, item: items[index] };
+  if (!refused) {
+    elements[index].click();
+    return { clicked: true, item: items[index] };
+  }
+  if (!${JSON.stringify(Boolean(humanSaidYes))} || items[index].kind === "link" && items[index].path) return { clicked: false, refused };
+  return clickButton(elements[index], items[index]);
 })()`;
 }
 
@@ -326,6 +364,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 +404,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." }),
   };
 }
@@ -371,7 +425,7 @@ async function runScreen(page, flags) {
     if (flags.click !== undefined) await network.settle(Math.min(waitMs, 3000));
   }
   if (flags.click !== undefined) {
-    const results = await evaluateInFrames(page, navigationScript(String(flags.click)), {
+    const results = await evaluateInFrames(page, navigationScript(String(flags.click), Boolean(flags["human-said-yes"])), {
       stopWhen: (value) => value?.clicked === true,
     });
     const hit = results.find((value) => value?.clicked);
@@ -381,7 +435,7 @@ async function runScreen(page, flags) {
       const error = refused
         ? refused.refused
         : outside
-          ? `"${flags.click}" is on the page but not in the app's navigation. observe only clicks navigation, never a control that could create, send, save or delete.`
+          ? `"${flags.click}" is on the page but not in the app's navigation. Ask the human in chat whether you may click it, naming it; only after their yes, run this again with --human-said-yes.`
           : `No navigation item is labelled "${flags.click}".`;
       throw new ObserveExit(
         {
@@ -392,7 +446,7 @@ async function runScreen(page, flags) {
         1,
       );
     }
-    reached = { how: "click", ...publicItem(hit.item) };
+    reached = { how: "click", ...publicItem(hit.item), ...(hit.button ? { button: true } : {}) };
   }
   if (!reached) {
     // Nothing to reach: reload so this screen's own requests are seen.
@@ -432,6 +486,7 @@ async function runScreen(page, flags) {
     writes.set(`${entry.method} ${entry.path}`, entry);
   }
   const ranked = rankCandidates(candidates, words, 8);
+  const buttonWrote = reached.button && writes.size > 0;
   return {
     ok: true,
     reached,
@@ -440,6 +495,10 @@ async function runScreen(page, flags) {
     requestsSeen: all.filter(isApiCall).length,
     candidates: ranked,
     writesSeen: [...writes.values()].slice(0, 20),
+    ...(buttonWrote
+      ? { buttonWarning: `The button "${reached.label}" sent ${writes.size} change(s) to the server (writesSeen). Tell the human what it sent, in one line, before anything else.` }
+      : {}),
+    ...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." }),