uniweb 0.61.0 → 0.63.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.61.0",
+  "version": "0.63.0",
   "description": "Create structured Vite + React sites with content/code separation",
   "type": "module",
   "bin": {
@@ -41,15 +41,15 @@
     "js-yaml": "^4.1.0",
     "prompts": "^2.4.2",
     "tar": "^7.0.0",
-    "@uniweb/core": "^0.29.7",
+    "@uniweb/content-writer": "^0.3.4",
     "@uniweb/kit": "^0.19.4",
-    "@uniweb/schemas": "^0.3.3",
-    "@uniweb/semantic-parser": "^1.4.1",
-    "@uniweb/runtime": "^0.27.3",
-    "@uniweb/content-writer": "^0.3.4"
+    "@uniweb/core": "^0.29.8",
+    "@uniweb/runtime": "^0.27.4",
+    "@uniweb/schemas": "^0.3.4",
+    "@uniweb/semantic-parser": "^1.4.1"
   },
   "peerDependencies": {
-    "@uniweb/build": "^0.57.0",
+    "@uniweb/build": "^0.59.0",
     "@uniweb/content-reader": "^1.2.5",
     "@uniweb/semantic-parser": "^1.4.1"
   },

package/partials/agents.md

@@ -129,7 +129,7 @@ my-project/
 └── pnpm-workspace.yaml
 ```
 
-A site is pure content. A foundation is the site's source code — that's why it lives in `src/`. The foundation's `package.json::name` is `src`, symmetric with `site`.
+A site is pure content. A foundation is the site's source code — that's why it lives in `src/`. The foundation's `package.json::name` is `src`, symmetric with `site` — a **workspace** name, how the site depends on it. What the foundation **registers as** (`@org/<name>`, the name sites pin) is `name` in its `main.js`, which `uniweb create` sets to the project's name. **`src` and `foundation` are never a foundation's name** — `uniweb register` refuses them, because every project in an org would register the same one.
 
 - **Foundation** (`src/`): React components. Those in `sections/` and `layouts/` are *section types* — selectable by authors via `type:`, or used for layout areas. Everything in `components/` and `utils/` is ordinary React and JS: the developer's workbench, not visible to authors.
 - **Site** (`site/`): markdown content and configuration, plus optional records of structured content and the queries that reach them or an external data source.
@@ -845,13 +845,13 @@ It is a small database, not a page tree. Three things, deliberately separate:
 ```
 site/
 ├── pages/
-├── records/           # your site's records — every file here is one
+├── records/           # your site's records — every file in a schema folder is one
 │   ├── article/       # the folder names their data schema
 │   │   ├── getting-started.md
 │   │   └── design-tips.md
-│   └── person/
-│       └── alice.yml
-├── records.yml        # optional: sorts records into folders
+│   ├── person/
+│   │   └── alice.yml
+│   └── folder.yml     # optional: sorts records into folders
 ├── queries.yml        # how content is REACHED
 └── site.yml
 ```
@@ -864,7 +864,7 @@ site/
 | `records/std/person/…` | `@std/person` — the shared standard set |
 | `records/acme/project/…` | `@acme/project` — an org's |
 
-Keep those folders flat: `records/article/design-tips.md` works; `records/article/2025/design-tips.md` is read as the `2025` schema of an `article` org, which is not what you meant. Organise in `records.yml` instead. A file whose name starts with `_` is not a record — somewhere to keep work in progress.
+Keep those folders flat: `records/article/design-tips.md` works; `records/article/2025/design-tips.md` is read as the `2025` schema of an `article` org, which is not what you meant. Organise in `records/folder.yml` instead. A file whose name starts with `_` is not a record — somewhere to keep work in progress.
 
 **Four formats, one shape.** All of these produce the same records at runtime:
 
@@ -877,9 +877,9 @@ Keep those folders flat: `records/article/design-tips.md` works; `records/articl
 
 **One record per file, or many.** A single mapping at the top of a file makes one record and the filename stem becomes its `slug`. A top-level array (YAML/JSON) or a multi-entry `.bib` makes many, each carrying its own `slug`. You can mix both in one folder — an exported `refs.bib` beside a hand-written `extras.yml`.
 
-Item frontmatter conventionally uses `title`, `date`, `tags`, `image`, `description`, `author` — plus any fields your content needs (`price`, `role`, `order`). Images can sit beside the item file and be referenced with `./`. **`draft: true` keeps a record off the live site without deleting it**: it is still a record, in `records/`, and `pnpm dev` shows it so you can preview it, but a build for hosting leaves it out — and `uniweb push` stops at it, naming it. (`published: false`, an older spelling, is refused.)
+Item frontmatter conventionally uses `title`, `date`, `tags`, `image`, `description`, `author` — plus any fields your content needs (`price`, `role`, `order`). Images can sit beside the item file and be referenced with `./`. **`draft: true` keeps a record off the live site without deleting it**: it is still a record, in `records/`, and `pnpm dev` shows it so you can preview it, but a build for hosting leaves it out, and a backend you `uniweb push` it to keeps it in the site's folder without delivering it. (`published: false`, an older spelling, is refused.)
 
-**`records.yml` — optional, and only for folders.** Every record sits at the top of the site's records folder unless `records.yml` places it in a sub-folder. Add one only when a query needs to ask for a *slice* of the records rather than all of them — most sites never do:
+**`records/folder.yml` — optional, and only for folders.** It is the one file in `records/` that is not a record, it moves with the directory (`paths.records`), and like a pages folder's `folder.yml` it describes the folder it sits in. Every record sits at the top of the site's records folder unless `folder.yml` places it in a sub-folder. Add one only when a query needs to ask for a *slice* of the records rather than all of them — most sites never do:
 
 ```yaml
 - folder: archive
@@ -888,7 +888,7 @@ Item frontmatter conventionally uses `title`, `date`, `tags`, `image`, `descript
     - article/2025-*.md
 ```
 
-A path under a folder is relative to `records/`, naming one file or matching many. A query reads one folder with `scope: archive` — the folder and everything inside it. A record sits in one folder; if you want a computed subset, that is a query, not a second placement. Structure is for querying, not for navigation — and `records.yml` never lists a record at the top level (the build refuses it: every file in `records/` is a record already).
+A path under a folder is relative to `records/`, naming one file or matching many. A query reads one folder with `scope: archive` — the folder and everything inside it. A record sits in one folder; if you want a computed subset, that is a query, not a second placement. Structure is for querying, not for navigation — and `folder.yml` never lists a record at the top level (the build refuses it: every file in `records/` is a record already).
 
 ⚠️ **With a backend, `records/` is what `uniweb push` sends** — every record in it. A site with no `records/` at all leaves the backend's records alone; an *empty* `records/` removes them, and the CLI asks before it does. Records pushed to a backend are served once the site is published.
 
@@ -942,7 +942,7 @@ pages/blog/
 
 > **The record arrives as a single-element array under the key the component declares** — `content.data.recent[0]` for a component declaring `recent`, `content.data.article[0]` for one declaring `article: '@std/article'` over an `@std/article` query. The runtime never coerces it to an object. See *Data* in Part 4.
 
-**Records with URLs of their own shape — `[...path]/`.** A folder named exactly `[...path]` (one fixed spelling) captures the rest of the URL: `/blog/my-post` and `/blog/rust/2025/my-post` both reach it. The capture yields three standard variables — `:path` (the whole capture), `:dir` (everything before the last segment), `:slug` (the last segment, the record's handle) — and the record is still delivered by its handle, so the section reads `content.data.recent[0]` as before. The same three variables exist under every parametric page: under `[slug]`, `:slug` and `:path` are the segment and `:dir` is empty. A record's URL is its folder placement plus its slug (`- folder: rust/2025` in `records.yml` → `/blog/rust/2025/my-post`). A query may bind a part — `scope: :dir` exposes the folder branch, `where: { tag: :dir }` keeps it private — and an unbound or empty variable drops its clause, so one saved query serves the query's page and its parametric page, on a static site and a hosted one alike. Without `scope: :dir` the directory is decoration: the record is found by its handle wherever it sits. Reference: `reference/dynamic-routes.md`.
+**Records with URLs of their own shape — `[...path]/`.** A folder named exactly `[...path]` (one fixed spelling) captures the rest of the URL: `/blog/my-post` and `/blog/rust/2025/my-post` both reach it. The capture yields three standard variables — `:path` (the whole capture), `:dir` (everything before the last segment), `:slug` (the last segment, the record's handle) — and the record is still delivered by its handle, so the section reads `content.data.recent[0]` as before. The same three variables exist under every parametric page: under `[slug]`, `:slug` and `:path` are the segment and `:dir` is empty. A record's URL is its folder placement plus its slug (`- folder: rust/2025` in `records/folder.yml` → `/blog/rust/2025/my-post`). A query may bind a part — `scope: :dir` exposes the folder branch, `where: { tag: :dir }` keeps it private — and an unbound or empty variable drops its clause, so one saved query serves the query's page and its parametric page, on a static site and a hosted one alike. Without `scope: :dir` the directory is decoration: the record is found by its handle wherever it sits. Reference: `reference/dynamic-routes.md`.
 
 **Two options for bigger sets:**
 
@@ -1006,7 +1006,7 @@ import LessonHeader from '../../components/LessonHeader' // ❌ breaks if you re
 
 Within the same directory, use normal relative imports (`./AIFeedbackCard`).
 
-**Foundation entry (`main.js`).** A single `export default { … }` whose top-level keys are the capabilities the foundation provides — `name`, `description`, `defaultLayout`, `defaultSection`, `viewTransitions`, `props`, `defaultInsets`, `xref`, `outputs`, `handlers` — plus an optional named `vars` export. Everything here is read at render; the one thing a foundation declares that *isn't* — which host services it supports — lives in `package.json` instead (see [Declaring what your foundation supports](#declaring-what-your-foundation-supports)). Section types and layouts are auto-discovered and merged in by `@uniweb/build`. The build wraps your default export under `default.capabilities` in `dist/entry.js`; you never write that wrapper. The one place it matters: when you import your **own** `main.js` from a component (e.g. a download button calling `compileDocument(website, { foundation })`), you get the bare default object — pass it through directly, Press handles both shapes.
+**Foundation entry (`main.js`).** A single `export default { … }` whose top-level keys are the foundation's identity — `name` (what it registers as, `@org/<name>`) and `description` — and the capabilities it provides — `defaultLayout`, `defaultSection`, `viewTransitions`, `props`, `defaultInsets`, `xref`, `outputs`, `handlers` — plus an optional named `vars` export. The capabilities are read at render; the one thing a foundation declares that *isn't* — which host services it supports — lives in `package.json` instead (see [Declaring what your foundation supports](#declaring-what-your-foundation-supports)). Section types and layouts are auto-discovered and merged in by `@uniweb/build`. The build wraps your default export under `default.capabilities` in `dist/entry.js`; you never write that wrapper. The one place it matters: when you import your **own** `main.js` from a component (e.g. a download button calling `compileDocument(website, { foundation })`), you get the bare default object — pass it through directly, Press handles both shapes.
 
 ### Props interface
 
@@ -2575,7 +2575,9 @@ Foundations have their own free path too: `uniweb add ci --target foundation` pu
 > The answer is recorded in `sync.json` and committed, so it is a one-time choice per site,
 > not per machine. **Ask the human which one to use** rather than picking for them — a site in
 > the wrong org cannot be moved from here. Sites that already exist are unaffected: their
-> ownership is settled, so nothing is asked.
+> ownership is settled, so nothing is asked. After the create, every command names the
+> recorded org for you; an `--org` that disagrees with where the backend keeps the site
+> **stops the command** rather than acting in another org.
 >
 > Relatedly: these commands now **reject flags they do not recognize** instead of ignoring them.
 > If you get `Unknown flag`, read the suggestion — it is usually a near miss.
@@ -2594,7 +2596,7 @@ Foundations have their own free path too: `uniweb add ci --target foundation` pu
 
 Either side can publish. Nothing about this changes how you build: the same foundation and the same site run under `uniweb dev`, `uniweb export`, or a CI deploy with no account at all.
 
-**Publishing vs registering.** Foundations on Uniweb Cloud live in the catalog as `@org/name@version`. When a foundation powers a single site, **don't run `uniweb register` yourself** — `uniweb publish` from the site directory releases the local foundation to the catalog (when its code changed) and goes live in one step. Register deliberately only when the foundation is a product meant for multiple sites; consuming sites then pin `foundation: '@org/name@1.2.3'`. **The catalog is private and access-segregated, not a public package registry** — people see only the foundations licensed to sites they own or edit. The *site* carries the license, and it rides along with site ownership when a developer hands a site to a client. Don't describe publishing as making a foundation publicly discoverable. Schemas can also be registered on their own from a schemas-only package (`@uniweb/schemas`, any `@org/schemas`, or a bare folder of `schemas/*.{yml,json,js}`) — that's how `@std` schemas are published. Auth via `uniweb login` (`uniweb login --backend <url> --token <bearer>` without a terminal) or `UNIWEB_TOKEN`; preview with `--dry-run`.
+**Publishing vs registering.** Foundations on Uniweb Cloud live in the catalog as `@org/name@version` — `name` from the foundation's `main.js`. When a foundation powers a single site, **don't run `uniweb register` yourself** — `uniweb publish` from the site directory releases the local foundation to the catalog (when its code changed) and goes live in one step. Register deliberately only when the foundation is a product meant for multiple sites; consuming sites then pin `foundation: '@org/name@1.2.3'`. **The catalog is private and access-segregated, not a public package registry** — people see only the foundations licensed to sites they own or edit. The *site* carries the license, and it rides along with site ownership when a developer hands a site to a client. Don't describe publishing as making a foundation publicly discoverable. Schemas can also be registered on their own from a schemas-only package (`@uniweb/schemas`, any `@org/schemas`, or a bare folder of `schemas/*.{yml,json,js}`) — that's how `@std` schemas are published. Auth via `uniweb login` (`uniweb login --backend <url> --token <bearer>` without a terminal) or `UNIWEB_TOKEN`; preview with `--dry-run`.
 
 ### Staying current
 
@@ -2630,10 +2632,10 @@ Platform-specific configuration that doesn't belong in npm-standard fields. All
 
 | Field | Where used | Default | Purpose |
 |---|---|---|---|
-| `id` | `uniweb register` | bare segment of a scoped `name` | The foundation's registered id — the bare name in `@org/<id>`. Decoupled from `package.json::name` (a workspace concern), so renaming on the registry doesn't ripple through site dependencies. |
-| `namespace` | `uniweb register` | none | Legacy explicit org-namespace override; equivalent to a scoped `package.json::name`. Rarely needed. |
 | `runtimePolicy` | `dist/runtime-pin.json` | unset | Declares how far past the recorded runtime version a host may move a site. |
 
+**The foundation's name is not here — it is `name` in `main.js`** (else `package.json`'s `name`), **and so is the org it registers under: the scope is part of the name**, `name: '@acme/marketing'`. A name with no scope has not been registered yet: the first `uniweb register` takes `--scope @org` (else one of your orgs) and writes it into the name, and a `--scope` naming another org than the name's is refused. The foundation's own data schemas register under the same scope (`@/article` → `@acme/article`). ⛔ `uniweb.id` and `uniweb.scope` are no longer read for a foundation: `uniweb register` refuses them and prints the `main.js` line to write instead. (A schemas-only package has no `main.js`, and still records its scope in `uniweb.scope`.)
+
 **Runtime updates — handled for you.** Your foundation's code links against the runtime: it externalizes `react`, `react-dom`, `react-dom/server`, both JSX runtimes and `@uniweb/core`, and the runtime supplies all of them at load time. So a build is bound to *that* React and *that* core API.
 
 You don't declare anything for this. At build time your foundation records the `@uniweb/runtime` version it actually linked against (read from `node_modules`, not chosen) into `dist/runtime-pin.json`, and `uniweb register` sends it with your foundation, so the version you built against travels with it. **Whether two runtime versions are compatible is our determination, not a setting** — you have no way to know whether we changed anything your code can reach, so we don't ask you to guess.

package/src/backend/client.js

@@ -105,6 +105,141 @@ export function resolveBackendOrigin() {
  */
 export const DISCOVERY_DEFAULTS = {}
 
+/**
+ * The header a request names its WORKSPACE with — the unit it works in.
+ *
+ * ⭐ `@<handle>`, the `@` required: a bare value is read as a unit's uuid — the spelling
+ * for a workspace with no handle — so the two can never be mistaken for each other.
+ * Every `/dev` route accepts it; the client names it on the site routes, the ones that
+ * work in a workspace (`namesWorkspace`). ⛔ It replaced `?as_org=` (2026-09-23), which
+ * only routes that declared it accepted — the rest answered `400`.
+ */
+export const WORKSPACE_HEADER = 'x-uniweb-workspace'
+
+/**
+ * Whether a request works IN a workspace — a site route, `/dev/site…`.
+ *
+ * Only those name one. Every `/dev` route accepts the header, but registration reads
+ * none (the `@scope` in the name decides, membership-gated), `/dev/assets` reads none
+ * (a charge lands on the entity's own workspace), and auth, orgs and config are about
+ * the account. Naming the site's workspace there would be harmless and meaningless —
+ * and a workspace that is refused (`400`/`403`) would then fail a registration that
+ * never involved it.
+ *
+ * @param {string} path - leading-slash path
+ * @returns {boolean}
+ */
+export function namesWorkspace(path) {
+  return /^\/dev\/site(\/|$)/.test(String(path))
+}
+
+/**
+ * A workspace as it may be written — `@acme`, `acme`, `@acme/…` — as the header's
+ * `@acme`; null for none (the personal workspace, which a request names by omission).
+ *
+ * @param {unknown} value
+ * @returns {string|null}
+ */
+export function workspaceHandle(value) {
+  const h =
+    typeof value === 'string' ? value.trim().replace(/^@/, '').replace(/\/.*$/, '') : ''
+  return h ? `@${h}` : null
+}
+
+const UNIT_UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+
+/**
+ * A workspace as the header names it — `@handle`, or a unit's bare uuid when the unit
+ * has no handle — or null for none.
+ *
+ * ⚠️ A bare value is taken for a uuid only when it is shaped like one, and our own
+ * handle grammar admits uuid-shaped handles (3–39 lowercase letters, digits, hyphens).
+ * So a HANDLE reaches this already dressed — `--org` through `workspaceHandle`, a
+ * record through `readSiteWorkspace` — and a bare uuid here is a unit.
+ *
+ * @param {unknown} value
+ * @returns {string|null}
+ */
+export function workspaceHeader(value) {
+  if (typeof value !== 'string' || !value.trim()) return null
+  const v = value.trim()
+  return !v.startsWith('@') && UNIT_UUID.test(v) ? v : workspaceHandle(v)
+}
+
+/**
+ * The request named its workspace EXPLICITLY — `--org`, `--personal`, a choice made at
+ * create — and the backend works on the site from another.
+ *
+ * ⛔ Stopping is the point. It is the mismatch check [Diego, 2026-09-22: "there is no org
+ * mismatch when the site is set for an org and the user tries a different one"], and it
+ * is the backend's `409` that decides it, never a handle comparison here: a site in
+ * `@acme/labs` is legitimately worked on from `@acme`. Adopting the answer would override
+ * a choice the user made.
+ */
+export class WorkspaceMismatchError extends Error {
+  /**
+   * @param {{ named: string|null, answer: string|null }} p - the workspace the request
+   *   named, and the one the backend named (`@handle`, null for personal)
+   */
+  constructor({ named, answer }) {
+    const where = (w) =>
+      !w ? 'your personal workspace' : w.startsWith('@') ? w : `the unit ${w}`
+    const flag = named ? '--org' : '--personal'
+    super(
+      `The backend works on this site from ${where(answer)}, not ${where(named)} ` +
+        `(${named ? `--org ${named}` : flag}). ` +
+        // `--org` takes a handle; a unit without one is reached by naming nothing.
+        (answer?.startsWith('@') ? `Pass --org ${answer}, or drop ${flag}.` : `Drop ${flag}.`)
+    )
+    this.name = 'WorkspaceMismatchError'
+    this.status = 409
+    this.named = named
+    this.answer = answer
+  }
+}
+
+/**
+ * The line to print when a request THREW rather than answered.
+ *
+ * A `WorkspaceMismatchError` is the backend's answer, not a transport failure, so it is
+ * printed as itself: "Could not reach the backend" in front of it would send the user
+ * to check their network over a choice they made on the command line.
+ *
+ * @param {unknown} err
+ * @param {string} origin
+ * @returns {string}
+ */
+export function describeRequestError(err, origin) {
+  if (err instanceof WorkspaceMismatchError) return err.message
+  return `Could not reach the backend at ${origin}: ${err?.message ?? err}`
+}
+
+/**
+ * The sentence a refusal carries — a problem document's `detail`, else its `title`, else
+ * the start of a prose body — or null. Consumes the body. For the surfaces that would
+ * otherwise print a status line alone, so a refusal the backend explains is shown as it
+ * is: a deployment with one workspace answers a request naming another with a plain
+ * `409 Conflict` whose `detail` names the one there is.
+ *
+ * @param {Response} res
+ * @returns {Promise<string|null>}
+ */
+export async function refusalDetail(res) {
+  let body = ''
+  try {
+    body = await res.text()
+  } catch {
+    return null
+  }
+  try {
+    const problem = JSON.parse(body)
+    const line = problem?.detail || problem?.title
+    return typeof line === 'string' && line ? line : null
+  } catch {
+    return body ? body.slice(0, 300) : null
+  }
+}
+
 export class BackendClient {
   /**
    * @param {object} [opts]
@@ -134,6 +269,35 @@ export class BackendClient {
     this._command = command
     this._fetch = fetchImpl || ((url, init) => globalThis.fetch(url, init))
     this._discovery = null
+    this._workspace = null
+    this._workspaceExplicit = false
+    this._onWorkspaceAdopted = null
+  }
+
+  /** The workspace this client's requests name — `@handle`, or null (none named). */
+  get workspace() {
+    return this._workspace
+  }
+
+  /**
+   * Name the workspace every request from here on works in (`x-uniweb-workspace`).
+   *
+   * @param {string|null} value - `@acme` / `acme`, a handle-less unit's uuid, or null to
+   *   name none (`workspaceHeader`)
+   * @param {object} [opts]
+   * @param {boolean} [opts.explicit=false] - the user named it (`--org`, `--personal`,
+   *   the create picker). A `409 wrong_workspace` then STOPS the command
+   *   (`WorkspaceMismatchError`) instead of adopting the backend's answer.
+   * @param {(handle: string|null) => void|Promise<void>} [opts.onAdopted] - called when a
+   *   request that named nothing, or a stale workspace, adopts the one the backend named;
+   *   the caller records it (sync.json) and says so
+   * @returns {this}
+   */
+  setWorkspace(value, { explicit = false, onAdopted = null } = {}) {
+    this._workspace = workspaceHeader(value)
+    this._workspaceExplicit = Boolean(explicit)
+    this._onWorkspaceAdopted = onAdopted || null
+    return this
   }
 
   /**
@@ -168,7 +332,9 @@ export class BackendClient {
    * applies query params, and infers a content-type from the body when unset
    * (string → application/json, Buffer/Uint8Array → application/zip). Returns
    * the raw Response so callers branch on status themselves (409 resume,
-   * 404 → null, 401/403 messaging, …).
+   * 404 → null, 401/403 messaging, …) — except a `409 wrong_workspace`, which is
+   * answered here: adopted and retried once when the workspace was not named, and
+   * thrown as `WorkspaceMismatchError` when it was (see the body).
    *
    * @param {string} path - leading-slash path, e.g. '/dev/site/content'
    * @param {object} [opts]
@@ -179,10 +345,41 @@ export class BackendClient {
    * @param {boolean} [opts.auth=true]
    * @returns {Promise<Response>}
    */
-  async request(
-    path,
-    { method = 'GET', body, headers = {}, query, auth = true } = {}
-  ) {
+  async request(path, opts = {}) {
+    const res = await this._send(path, opts)
+    if (res?.status !== 409) return res
+
+    // ⭐ THE WORKSPACE A REQUEST NAMES IS CHECKED BY THE BACKEND, NOT HERE. A request that
+    // names the wrong one for an existing site is refused with `409 wrong_workspace`,
+    // naming a workspace the caller CAN open that contains the site — its own unit, or a
+    // parent the caller belongs to. Two answers, and which one depends on the user:
+    //   - they named it (`--org`, `--personal`) → stop and say so: the mismatch check;
+    //   - they named nothing, or a stale one → adopt the backend's answer, let the caller
+    //     record it, and retry ONCE.
+    // ⛔ No handle comparison anywhere: a site in `@acme/labs` is worked on from `@acme`.
+    const problem =
+      typeof res.clone === 'function' ? await res.clone().json().catch(() => null) : null
+    if (problem?.reason !== 'wrong_workspace') return res
+    const where = problem.workspace || {}
+    // A unit with no handle is named by its uuid, bare — the header takes either.
+    const answer = where.handle
+      ? workspaceHandle(where.handle)
+      : typeof where.unit_uuid === 'string' && where.unit_uuid
+        ? where.unit_uuid
+        : null
+    // Naming what the backend names and still refused: nothing to adopt, or to report
+    // as a mismatch. The caller reads the 409 like any other.
+    if (answer === this._workspace) return res
+    if (this._workspaceExplicit) {
+      throw new WorkspaceMismatchError({ named: this._workspace, answer })
+    }
+    this._workspace = answer
+    if (this._onWorkspaceAdopted) await this._onWorkspaceAdopted(answer)
+    return this._send(path, opts)
+  }
+
+  /** One request, as `request` documents it — naming the client's workspace on a site route. */
+  async _send(path, { method = 'GET', body, headers = {}, query, auth = true } = {}) {
     const url = new URL(path, this.origin)
     if (query) {
       for (const [k, v] of Object.entries(query)) {
@@ -191,6 +388,7 @@ export class BackendClient {
     }
     const h = { ...headers }
     if (auth) h.Authorization = `Bearer ${await this.token()}`
+    if (this._workspace && namesWorkspace(path)) h[WORKSPACE_HEADER] = this._workspace
     if (body != null && h['Content-Type'] == null) {
       if (typeof body === 'string') h['Content-Type'] = 'application/json'
       else if (body instanceof Uint8Array || Buffer.isBuffer(body))
@@ -405,10 +603,13 @@ export class BackendClient {
    * design). Callers must guard on the site's uuid for this backend (sync.json) and
    * write the result back immediately — see `ensureSiteExists`.
    *
-   * @param {{ name: string, foundation: string, asOrg?: string|null }} opts
+   * The owner is the workspace the client names (`setWorkspace`) — the create is where
+   * that choice is made, once.
+   *
+   * @param {{ name: string, foundation: string }} opts
    * @returns {Promise<Response>} `{ site_content_uuid }`
    */
-  async createSite({ name, foundation, asOrg } = {}) {
+  async createSite({ name, foundation } = {}) {
     return this.request('/dev/site', {
       method: 'POST',
       // Both fields are REQUIRED: `info.name` is `required: true` on the model
@@ -417,35 +618,34 @@ export class BackendClient {
       // render), and a site must resolve to a foundation. Adoption of the ref is
       // best-effort on the backend, but the field itself cannot be blank — so send
       // whatever the site declares and let the backend judge it.
-      body: JSON.stringify({ name, foundation }),
-      query: { as_org: asOrg }
+      body: JSON.stringify({ name, foundation })
     })
   }
 
   /** POST /dev/site/content — CREATE a site from its content lane (.uwx zip). */
-  async createSiteContent(buffer, { asOrg } = {}) {
+  async createSiteContent(buffer) {
     return this.request('/dev/site/content', {
       method: 'POST',
       body: buffer,
-      query: pushQuery(asOrg)
+      query: PUSH_QUERY
     })
   }
 
   /** POST /dev/site/content/push/{uuid} — UPDATE the content lane by site uuid (.uwx zip). */
-  async updateSiteContent(uuid, buffer, { asOrg } = {}) {
+  async updateSiteContent(uuid, buffer) {
     return this.request(`/dev/site/content/push/${encodeURIComponent(uuid)}`, {
       method: 'POST',
       body: buffer,
-      query: pushQuery(asOrg)
+      query: PUSH_QUERY
     })
   }
 
   /** POST /dev/site/folder/push/{uuid} — push the folder lane, keyed by the site uuid (.uwx zip). */
-  async pushFolder(uuid, buffer, { asOrg } = {}) {
+  async pushFolder(uuid, buffer) {
     return this.request(`/dev/site/folder/push/${encodeURIComponent(uuid)}`, {
       method: 'POST',
       body: buffer,
-      query: pushQuery(asOrg)
+      query: PUSH_QUERY
     })
   }
 
@@ -565,8 +765,17 @@ export class BackendClient {
       const res = await this.request(
         `/dev/site/status/${encodeURIComponent(uuid)}`
       )
+      if (res.status === 409) {
+        // A refusal about the workspace — e.g. a deployment with one workspace, naming
+        // it — is an answer to report, not an absent status.
+        const refused = new Error((await refusalDetail(res)) || 'HTTP 409 Conflict')
+        refused.status = 409
+        throw refused
+      }
       return res.ok ? await res.json().catch(() => null) : null
-    } catch {
+    } catch (err) {
+      // A mismatch or a refusal is an answer, not an absent status.
+      if (err instanceof WorkspaceMismatchError || err?.status === 409) throw err
       return null
     }
   }
@@ -596,7 +805,9 @@ export function dataSchemaPath(modelName) {
   return `/dev/registry/data-schemas/${encodeURIComponent(modelName)}`
 }
 
-/** The shared push query: last-push-wins, plus an optional acting-org. */
-function pushQuery(asOrg) {
-  return { collision: 'force', ...(asOrg ? { as_org: asOrg } : {}) }
-}
+/**
+ * The shared push query: last-push-wins. ⛔ No `as_org` — the workspace rides the
+ * `x-uniweb-workspace` header on every site request (`BackendClient.setWorkspace`),
+ * since 2026-09-23.
+ */
+const PUSH_QUERY = { collision: 'force' }