uniweb 0.34.0 → 0.34.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.34.0",
+  "version": "0.34.2",
   "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/kit": "^0.15.0",
-    "@uniweb/runtime": "^0.13.2",
-    "@uniweb/core": "^0.14.0",
-    "@uniweb/semantic-parser": "^1.3.1"
+    "@uniweb/core": "^0.14.1",
+    "@uniweb/semantic-parser": "^1.3.1",
+    "@uniweb/runtime": "^0.13.3",
+    "@uniweb/kit": "^0.15.0"
   },
   "peerDependencies": {
-    "@uniweb/build": "^0.30.0",
     "@uniweb/semantic-parser": "^1.3.1",
-    "@uniweb/content-reader": "^1.2.4"
+    "@uniweb/content-reader": "^1.2.4",
+    "@uniweb/build": "^0.30.2"
   },
   "peerDependenciesMeta": {
     "@uniweb/build": {

package/partials/agents.md

@@ -2234,6 +2234,112 @@ For cases the factory doesn't cover, write handlers directly using `Loom`, `inst
 
 ---
 
+## Part 4b — When the site is also an app
+
+Everything above is a site: content the author writes, built into pages. Some sites
+also have **their own backend** — accounts, per-visitor data, records their members
+create and edit. That is `@uniweb/api`.
+
+⛔ **Only reach for this when the site actually has one.** A site with no backend is
+the normal case, and a foundation that assumes one breaks on every other site it is
+used with.
+
+```bash
+npm install @uniweb/api      # in the FOUNDATION, beside @uniweb/kit
+```
+
+### Ask before you draw
+
+```jsx
+import { isEnabled, useSession, SignedIn, SignedOut } from '@uniweb/api'
+
+if (!isEnabled(website)) return <StaticVersion />   // synchronous — nothing to await
+```
+
+⛔ **When there is no backend, draw nothing** — not a disabled control, and not an
+explanation. Same rule as `services` in Part 4: which capabilities a site's operator
+set up is none of a visitor's business, and "sign-in unavailable" reads as breakage
+when it is simply a feature this site does not have. Render the version of your
+component that never needed one.
+
+### Reading
+
+```jsx
+const { status, records } = useRecords({ schema: '@/session' })
+```
+
+⭐ **`absent` and an empty `ready` are different answers, and confusing them is the
+mistake to avoid.** `absent` = there is no live source (no backend, or nobody signed
+in) → render the site's authored content. `ready` with `records: []` = the backend
+answered and there is nothing there → render your empty state. Showing "nothing yet"
+for the first tells a visitor their content is gone when it was never requested.
+
+### Writing
+
+```jsx
+const writer = useEntityWriter({ schema: '@/track', uuid: track.uuid })
+
+await writer.create({ title: 'Keynote' }, { section: 'sessions', position: 'last' })
+await writer.update(itemId, { ...item.data, room: 'Hall A' })   // whole-data replace
+await writer.move(itemId, { after: previousItemId })            // never an index
+await writer.remove(itemId)
+```
+
+- **`section` is required on `create`.** An entity has several, and a rule declared on
+  one — insert-only, say — does not reach an item that landed in another. Getting it
+  wrong stores the item happily and quietly voids the rule.
+- **`update` replaces the item's data whole.** Spread what you are not editing.
+- **Ordering is the server's.** Say `'first'`, `'last'` or `{ after }` — never compute
+  an order number, or two people arranging one list will produce an order neither
+  chose.
+- ⛔ **`writer.conflict` is reported, not retried.** Someone else changed the item
+  first; a retry would succeed by overwriting a change nobody looked at. Tell the
+  person.
+
+### ⛔ Permissions are the SERVER'S, and your UI is only a courtesy
+
+Gate your controls on what the viewer may do — `viewer.actingUnitId`, `viewer.roles` —
+but **never rely on that for safety**. A foundation runs with exactly the viewer's
+own authority, so hiding a button hides a button. The rule belongs in the data
+schema, where the store enforces it:
+
+```yaml
+# foundation/schemas/session.yml
+creatable_by: unit_members     # only members of the owning unit may create these
+
+sections:
+  checkins:
+    many: true
+    append_only: true          # may be added; never edited or removed, by anyone
+```
+
+`append_only` holds against the item's own author. That is the difference between a
+permission model and a CSS one.
+
+### A backend on your machine
+
+You do not need a live backend to build against one. In `site.yml`:
+
+```yaml
+api: /_api                 # where it answers — the same value in production
+$devApi: ./mock/api.js     # what answers it locally; `$` keys are never published
+```
+
+```js
+// site/mock/api.js
+import { createMockBackend } from '@uniweb/api/mock'
+export default createMockBackend({ seed }).fetch
+```
+
+`uniweb dev` mounts it at your `api:` address, same-origin, so cookies and your
+site's configuration behave exactly as they will in production. It **enforces**
+`creatable_by` and `append_only`, so a permission you are relying on fails on your
+machine rather than in front of a user. State is in memory; restart to reset.
+
+`uniweb create my-event --template conference` is a worked example of all of this.
+
+---
+
 ## Part 5 — Commands, shipping, and migration
 
 ```bash

package/src/backend/client.js

@@ -105,34 +105,39 @@ export function resolveBackendOrigin(flag, { siteScope, siteBackend } = {}) {
 }
 
 /**
- * The fallback capability doc when `GET /dev/config` is absent or unreachable
- * (an older backend, or no backend at all). Keeps the client non-breaking: the
- * bases mirror a self-serve dev backend.
+ * The fallback capability doc for when `GET /dev/config` was not asked for (no
+ * credential in hand) or did not answer. Keeps the client non-breaking.
+ *
+ * ⭐ **It is EMPTY, and that is the accurate shape.** The CLI reads exactly one leaf of
+ * that document — `delivery.siteSubscriptionRequired` — and its absence is meaningful:
+ * unknown reads falsy, and the caller stays silent rather than claiming a deployment
+ * does or does not charge. Every other key that used to sit here had no reader.
+ *
+ * ⛔ **Do not restore a key "for completeness".** A default for a field nothing reads is
+ * a reader waiting to happen, and it is how this file came to describe a client that
+ * discovered its backend's gateway base, asset base and login path — none of which was
+ * ever true. The removals, and why each was not merely unused but wrong:
+ *
+ *   `gatewayBase`  sat here UNREAD until 2026-07-29. A serve location is read from the
+ *                  response that carries it (an upload plan's `serve_base`, an asset
+ *                  entry's `serve_url`, a payload's `config.base`) — never from a
+ *                  handshake, which cannot know a per-response answer.
+ *   `assetBase`    until 2026-08-17: one production host, hardcoded, applied to every
+ *                  deployment the CLI can be pointed at. Read only to compose an asset
+ *                  URL the plan already returns verbatim. Reader and composer both gone.
+ *   `runtime`      until 2026-08-22. A backend does not hold runtimes — a version comes
+ *                  from a CDN — so there is no installed set to report. What a site gets
+ *                  follows from its foundation's floor (`info.runtime`, at register).
+ *   `auth`         `loginPath` was never read: the login path is a constant in
+ *                  `utils/registry-auth.js`, and the ORIGIN comes from the resolution
+ *                  ladder, so the CLI is never told where to log in — it is born knowing.
+ *   `delivery`     `deploy` and `broker` had no reader. `publish` had one, but it could
+ *                  never refuse: the backend sent a literal true for every deployment,
+ *                  so the gate read a constant. Removed on both sides 2026-08-30.
+ *   `assets`       `supported` had no reader; the asset lane reports its own capability
+ *                  through the upload plan it returns.
  */
-export const DISCOVERY_DEFAULTS = {
-  // ⛔ No serve-root default, and no `assetBase`. Serve locations are read from
-  // discovery or from a per-response field (an upload plan's `serve_base`, an
-  // asset entry's `serve_url`); nothing here reconstructs one, so a default is a
-  // route name with no consumer. (A `gatewayBase` entry lived here unread until
-  // 2026-07-29.)
-  //
-  // `assetBase: 'https://assets.uniweb.app/'` sat here until 2026-08-17 — one
-  // production host, hardcoded, applied to EVERY deployment the CLI can be
-  // pointed at. It was only ever read to compose an asset URL, which the plan
-  // already returns as `serve_url`; both the reader and the composer are gone.
-  //
-  // No `runtime` entry, and there must not be one. A backend does not hold
-  // runtimes: a version is acquired from a CDN — the official mirror, the
-  // distribution channel, or a local server — so there is no installed set for
-  // it to report and nothing here to default. `runtime.installed` lived here
-  // until 2026-08-22, alongside a `uniweb runtime register` verb that pushed
-  // builds to a backend; both are gone. The runtime a site gets follows from
-  // its foundation's floor (`info.runtime`, stated at register), not from
-  // anything the CLI asks a backend about.
-  auth: { loginPath: '/dev/auth/login', required: true },
-  delivery: { deploy: true, publish: true, broker: 'self-serve' },
-  assets: { supported: false }
-}
+export const DISCOVERY_DEFAULTS = {}
 
 export class BackendClient {
   /**
@@ -250,18 +255,78 @@ export class BackendClient {
   // ── Discovery ─────────────────────────────────────────────────────────────────
 
   /**
-   * GET /dev/config — the anonymous capability/handshake document. The one route
-   * that answers before login (`auth: false`). Lazy + cached for the client's
-   * lifetime; a missing route or any transport/parse error falls back to
-   * DISCOVERY_DEFAULTS (non-breaking — an older backend still works). Lets the
-   * CLI hardcode nothing about a backend but its origin and discover the rest:
-   * `auth`, `delivery` (deploy/publish? broker), `assets` (lane built yet?).
+   * The session bearer IF one can be had without asking — an explicit `--token`, an
+   * env var, or a stored unexpired session. Never prompts, never logs in, returns null
+   * instead. `token()` is the one that may block; this is for calls that want to be
+   * authenticated when possible but must not *cause* an authentication.
+   * @returns {Promise<string|null>}
+   */
+  async _tokenIfAvailable() {
+    if (this._token) return this._token
+    // ⛔ The injected resolver must be honoured here too, not just in `token()`.
+    // `pull` and `clone` pass one (`deps.getToken`), so skipping it would treat a caller
+    // that supplies its own auth as unauthenticated — and, worse, fall through to the
+    // machine's stored session, quietly using a DIFFERENT credential than the caller
+    // asked for. A throwing resolver is "no token", never a failed command.
+    if (this._getToken) {
+      try {
+        return (await this._getToken()) || null
+      } catch {
+        return null
+      }
+    }
+    try {
+      const stored = await readRegistryAuth()
+      if (stored?.token && !isExpired(stored)) return stored.token
+    } catch {
+      /* advisory — a missing or unreadable session is simply "no token" */
+    }
+    return null
+  }
+
+  /**
+   * GET /dev/config — the capability/handshake document. Lazy + cached for the client's
+   * lifetime; a missing route, a 401, or any transport/parse error falls back to
+   * DISCOVERY_DEFAULTS, so this can never be the reason a command fails.
+   *
+   * ⭐ **Authenticated, or not sent at all.** `/dev/*` is the CLI's lane and the CLI is
+   * an authenticated client, so this attaches the bearer when it has one and **makes no
+   * request when it does not** — which keeps that true by construction rather than by
+   * ordering luck, and makes the route moving behind auth a no-op here.
+   *
+   * ⚠️ It uses `_tokenIfAvailable()` and never `token()`, deliberately: **discovery must
+   * never be the thing that triggers a login.** A capability probe that opens a password
+   * prompt would be a worse defect than the anonymous call it replaced.
+   *
+   * ⛔ **Most of this document is deliberately not read.** `gatewayBase` and `assetBase`
+   * were dropped because a serve location is read from the response that carries it
+   * (`serve_base`, `serve_url`, `config.base`), never from a handshake; `auth.loginPath`
+   * is not read either — the login path is a hardcoded constant
+   * (`utils/registry-auth.js`). What is actually consumed is ONE leaf —
+   * `delivery.siteSubscriptionRequired` — and nothing else. Do not add a reader for the
+   * rest: each one would be a second place a backend's layout is pinned.
+   *
    * @returns {Promise<object>}
    */
   async discover() {
     if (this._discovery) return this._discovery
+    const bearer = await this._tokenIfAvailable()
+
+    // ⛔ NO CREDENTIAL ⇒ NO REQUEST. This is the rule made structural rather than
+    // incidental: apart from the login routes themselves, the CLI does not touch
+    // `/dev/*` without a bearer. The defaults are the honest answer here — we do not
+    // know this backend's capabilities and are not entitled to ask yet — and every
+    // caller already treats them as non-breaking, so nothing downstream changes.
+    if (!bearer) {
+      this._discovery = { ...DISCOVERY_DEFAULTS }
+      return this._discovery
+    }
+
     try {
-      const res = await this.request('/dev/config', { auth: false })
+      const res = await this.request('/dev/config', {
+        auth: false,
+        headers: { Authorization: `Bearer ${bearer}` }
+      })
       this._discovery = res.ok ? await res.json() : { ...DISCOVERY_DEFAULTS }
     } catch {
       this._discovery = { ...DISCOVERY_DEFAULTS }
@@ -519,7 +584,29 @@ export class BackendClient {
    * shipped backend-side — collab backend-framework-b220):
    *   { published: boolean, last_pushed_at?: string, last_published_at?: string, draft_dirty?: boolean }
    * `draft_dirty` = never-published, or the synced draft changed since the last
-   * publish ("pushed but not published"). The path is VERB-FIRST (`status/{uuid}`)
+   * publish ("pushed but not published").
+   *
+   * ⭐ **The backend also serves a LIVE-SITE record here, and nothing in this CLI reads
+   * it yet** (shipped 2026-08-29; documented here so it is not lost twice):
+   *
+   *   last_published_url · last_published_foundation · last_published_extensions
+   *   last_published_runtime · last_published_runtime_floor · last_published_runtime_resolution
+   *
+   * Three things about it that a reader will otherwise get wrong:
+   *
+   * ⛔ `runtime_resolution` is `resolved` or `pinned:<reason>` (`operator` / `unknown_floor` /
+   *    `no_foundations`). **A pin is a first-class answer, not a failure** — most sites are pinned
+   *    at any moment, and an "old" runtime still satisfies the site's floor. Never surface
+   *    `pinned:*` as an error state.
+   * ⛔ `extensions` is there because a site's code surface is the primary foundation **plus N
+   *    extensions**; reading the primary alone describes a site nobody has.
+   * ⛔ `last_*` is deliberate on every one. `unpublish` LEAVES the URL populated (the static site
+   *    may still be reachable), so beside `published: bool` a bare `published_url` would read as a
+   *    liveness claim and be wrong exactly when it matters. And **nothing back-fills** — a site
+   *    published before this reports them absent, which means "published before we recorded it",
+   *    never "has no foundation".
+   *
+   * The path is VERB-FIRST (`status/{uuid}`)
    * to match the lane (`publish/{uuid}`, `content/push/{uuid}`, `folder/pull/{uuid}`),
    * not the `{uuid}/status` the shipping-verbs §8 sketch assumed. null on
    * 404 (unknown/not-yours) / 401 / any failure — `status --remote` degrades to local.

package/src/backend/site-media.js

@@ -17,6 +17,7 @@ import { existsSync, readFileSync } from 'node:fs'
 import { basename } from 'node:path'
 import { resolveAssetPath } from '@uniweb/build/site'
 import { contentTypeFor } from '../utils/code-upload.js'
+import { humanBytes } from '../utils/bytes.js'
 
 /**
  * @param {object} client - BackendClient (uploadSiteAssets). No `discover` — this
@@ -123,20 +124,6 @@ export async function uploadSiteMedia(
 // rewording). Same house style as the push-staleness `reason: "stale_base"` in
 // site-sync.js.
 
-const KIB = 1024
-function humanBytes(n) {
-  if (typeof n !== 'number' || !Number.isFinite(n) || n < 0) return null
-  if (n < KIB) return `${n} B`
-  const units = ['KiB', 'MiB', 'GiB', 'TiB']
-  let v = n / KIB
-  let i = 0
-  while (v >= KIB && i < units.length - 1) {
-    v /= KIB
-    i++
-  }
-  return `${v >= 10 || Number.isInteger(v) ? Math.round(v) : v.toFixed(1)} ${units[i]}`
-}
-
 // Append `label: <bytes>` when the value is a usable number. A refusal that omits an
 // extra still produces a useful message — never print `undefined` at a user.
 function pushBytes(lines, label, n) {
@@ -146,9 +133,17 @@ function pushBytes(lines, label, n) {
 
 /**
  * Turn an asset-plan refusal into user-facing lines, or null when this is not a
- * refusal we recognise (including every refusal shipped today, which is still
- * prose — the typed `reason` values are agreed but NOT YET EMITTED). Null means
- * "fall through to the generic error", so this degrades rather than swallowing.
+ * refusal we recognise. Null means "fall through to the generic error", so this
+ * degrades rather than swallowing.
+ *
+ * ⛔ This comment used to assert that the typed `reason` values were "agreed but
+ * NOT YET EMITTED" — an unverified claim about ANOTHER LANE's deployed state,
+ * sitting in our source where it read as fact and nobody would think to re-check
+ * it. That is the precise shape that cost the backend lane a metering hole (a
+ * comment claiming what the app sent, wrong the whole time). What we can say is
+ * ours: we branch on `reason` and fall through cleanly when there is none, so
+ * this function is correct whether or not any given backend emits one, and no
+ * sentence here needs to track what a deployment is running.
  *
  * Two wording rules are load-bearing and come from the ratified accounting model,
  * not from taste:

package/src/backend/site-sync.js

@@ -16,6 +16,7 @@ import { join, dirname } from 'node:path'
 import yaml from 'js-yaml'
 import { hasUncommittedContent } from '../utils/git.js'
 import { recordSiteBackend } from '../utils/site-identity.js'
+import { humanBytes } from '../utils/bytes.js'
 import {
   backfillEntityUuids,
   writeSiteEntityUuid,
@@ -647,9 +648,8 @@ export async function resolveSiteOrgForCreate({
   // serves the foundation lane, where every answer is an org and 0-orgs means
   // "claim your personal org". Here "personal" must stay reachable as *no org*,
   // and reusing deriveScope would quietly turn it into an org creation.
-  const { fetchOrgs, createOrg, validateHandle, bareHandle } = await import(
-    '../utils/registry-orgs.js'
-  )
+  const { fetchOrgs, createOrg, validateHandle, bareHandle } =
+    await import('../utils/registry-orgs.js')
   let envelope
   try {
     envelope = await fetchOrgs({
@@ -719,6 +719,59 @@ export async function resolveSiteOrgForCreate({
   }
 }
 
+/**
+ * Turn a typed site-create refusal into a sentence, or null to fall through to the
+ * generic HTTP line.
+ *
+ * ⭐ Why this exists separately from `describeAssetRefusal`. The asset lane grew a
+ * typed describer because a raw status dump is useless to the person who has to act
+ * on it; the create lane had the same hole and nobody had met it, because until the
+ * backend shipped account capacity a create could not be refused for space at all.
+ * So this is the same fix on the second door, written before anyone hits it rather
+ * than after.
+ *
+ * ⛔ Branch on `reason`, never on the status. `507` alone cannot be told from any
+ * other 507 and carries none of the numbers a user needs, and `detail` is prose the
+ * backend may reword.
+ *
+ * ⚖️ The wording deliberately DIVERGES from the asset lane's on one point. There the
+ * allowance belongs to the site's owner, who may not be the person pushing. Here
+ * there is no site yet, so the only workspace in play is the one the site would be
+ * created in — `--as <org>` included. Saying "the site owner's workspace" would be
+ * incoherent for a site that does not exist.
+ *
+ * @param {string} body - the raw response body
+ * @returns {string|null}
+ */
+function describeCreateRefusal(body) {
+  if (!body) return null
+  let p
+  try {
+    p = JSON.parse(body)
+  } catch {
+    return null // prose refusal, or an upstream error page
+  }
+  if (!p || typeof p !== 'object' || typeof p.reason !== 'string') return null
+
+  if (p.reason === 'storage_quota_exceeded') {
+    const parts = []
+    const used = humanBytes(p.used_bytes)
+    const limit = humanBytes(p.limit_bytes)
+    const needed = humanBytes(p.needed_bytes)
+    if (used && limit) parts.push(`${used} of ${limit} used`)
+    if (needed) parts.push(`a new site needs ${needed}`)
+    return (
+      'storage quota reached — the workspace this site would belong to has no room for it' +
+      (parts.length ? ` (${parts.join('; ')})` : '') +
+      '. Quota is returned by deleting a site or entity, not by editing content.'
+    )
+  }
+  // An unrecognised typed reason still beats a status dump: name it, and let the
+  // backend's own prose follow when it sent any.
+  const detail = typeof p.detail === 'string' ? p.detail : ''
+  return `the backend refused the site create (${p.reason})${detail ? ` — ${detail}` : ''}`
+}
+
 /**
  * Guarantee the site EXISTS on the backend before anything is uploaded against it.
  *
@@ -797,7 +850,8 @@ export async function ensureSiteExists({
       reason:
         res?.status === 404
           ? 'this backend has no /dev/site route (it predates the empty-site create)'
-          : `HTTP ${res?.status} ${res?.statusText || ''}${body ? ` — ${body.slice(0, 200)}` : ''}`
+          : (describeCreateRefusal(body) ??
+            `HTTP ${res?.status} ${res?.statusText || ''}${body ? ` — ${body.slice(0, 200)}` : ''}`)
     }
   }
   const payload = await res.json().catch(() => null)
@@ -837,7 +891,13 @@ export async function ensureSiteExists({
  *
  * @returns {Promise<string|null>} the display handle recorded, or null for personal
  */
-async function recordAndDescribeOwner({ client, siteDir, payload, asOrg, note }) {
+async function recordAndDescribeOwner({
+  client,
+  siteDir,
+  payload,
+  asOrg,
+  note
+}) {
   const echoed = payload && 'org' in payload ? payload.org : undefined
   const owner =
     echoed === undefined ? asOrg : typeof echoed === 'string' ? echoed : null
@@ -851,7 +911,8 @@ async function recordAndDescribeOwner({ client, siteDir, payload, asOrg, note })
   //
   // A no-op on the default backend, so the common case writes nothing.
   const scope = await recordSiteBackend(siteDir, client.origin)
-  if (scope) note?.(`Bound this project to ${scope} (recorded $backend in site.yml).`)
+  if (scope)
+    note?.(`Bound this project to ${scope} (recorded $backend in site.yml).`)
 
   note?.(
     org
@@ -859,27 +920,28 @@ async function recordAndDescribeOwner({ client, siteDir, payload, asOrg, note })
       : `Created the site on the backend, owned personally (recorded $uuid in site.yml).`
   )
 
-  // The billing line needs the JOIN of two independent facts, and either alone
-  // gives a wrong answer:
-  //   hosts_free               — a property of the SCOPE (is this owner exempt?)
-  //   siteSubscriptionRequired — a property of the DEPLOYMENT (does it charge at all?)
-  // Keyed on the scope alone, this fires on every local publish — where nothing
-  // enforces — until the warning is trained away. Keyed on the deployment alone it
-  // fires at exempt owners. An older backend supplies neither, so both read falsy
-  // and nothing is said: silence beats a claim we cannot justify.
-  const hostsFree = payload?.hosts_free === true
-  let enforces = false
-  try {
-    const cfg = await client.discover()
-    enforces = cfg?.delivery?.siteSubscriptionRequired === true
-  } catch {
-    /* discovery is advisory here — never fail a create over a message */
-  }
-  if (hostsFree) {
-    note?.('This owner is hosted free — publishing will not require a subscription.')
-  } else if (enforces) {
+  // What the create echoed about this site's OWNER, and nothing beyond it.
+  //
+  // `hosts_free` is a property of the SCOPE — is this owner exempt? — and it is the only
+  // billing fact the CLI holds. This used to JOIN it with `siteSubscriptionRequired`
+  // from the discovery document, a property of the DEPLOYMENT. That leaf left the wire:
+  // every deployment charges, so it read true everywhere and the join was testing a
+  // constant.
+  //
+  // ⛔ AND THE WARNING WENT WITH IT — this is NOT a fallback to keying on the scope
+  // alone, which is the exact thing the join existed to prevent. Whether a given publish
+  // is charged is derived per-site at publish time, on a side the CLI cannot see, so any
+  // prediction made here can only be approximately right and would go stale silently.
+  // The backend's typed 402 (`reason: "no_subscription"`) is exact, per-site, and
+  // arrives when it matters; `backend/payment-handoff.js` already turns it into a
+  // checkout. Deciding whether payment is due is not the CLI's job.
+  //
+  // ⇒ What survives is the reassuring direction only, and only when it was stated:
+  // `false` is an answer we deliberately do not speak to, and missing is not an answer
+  // at all. Do not reintroduce a "you will be charged" line here.
+  if (payload?.hosts_free === true) {
     note?.(
-      'Publishing this site live will require a hosting subscription on this backend.'
+      'This owner is hosted free — publishing will not require a subscription.'
     )
   }
   return org
@@ -1004,7 +1066,10 @@ export async function probeUnpushed(siteDir, { sendAll = false } = {}) {
  * Offline by design — measured at zero HTTP requests, a property the cross-client
  * flows rely on.
  */
-async function comparisonEmit(siteDir, { priorHashes = {}, sendAll = false } = {}) {
+async function comparisonEmit(
+  siteDir,
+  { priorHashes = {}, sendAll = false } = {}
+) {
   const applied = readAppliedInjections(siteDir)
   const assetIds = readAssetMap(siteDir)
   const org = readSiteOrg(siteDir)
@@ -1265,9 +1330,7 @@ export async function pushSyncPackages({
         note(
           `  deleted in the app  →  clearing \`$uuid\` from site.yml re-publishes it as a NEW site`
         )
-        note(
-          'Deleting this folder removes only your local copy, either way.'
-        )
+        note('Deleting this folder removes only your local copy, either way.')
       } else if (res.status === 409) {
         // The site's @uniweb/folder is genesis-owned: its structure is fixed on first
         // deploy and not reconciled in place (the v1 rule — see gotcha #20's mode switch).
@@ -1417,7 +1480,8 @@ export async function pushSyncPackages({
         asOrg,
         note
       })
-      if (createdOrg) wrote.push(`recorded site $org (${createdOrg}) in site.yml`)
+      if (createdOrg)
+        wrote.push(`recorded site $org (${createdOrg}) in site.yml`)
       const createdFinalized = extractFinalized(payload)
       harvest(createdFinalized)
       siteFinalizedDoc = createdFinalized?.[0]?.document || null
@@ -1465,7 +1529,8 @@ export async function pushSyncPackages({
     const folderDoc = finalized.find((f) => f?.document?.contents)?.document
     if (folderDoc) {
       const placements = collectFolderItemUuids(folderDoc)
-      if (Object.keys(placements).length) writeFolderItemUuids(siteDir, placements)
+      if (Object.keys(placements).length)
+        writeFolderItemUuids(siteDir, placements)
     }
     finalizedTotal += finalized.length
   }

package/src/commands/publish.js

@@ -248,15 +248,17 @@ export async function publish(args = []) {
   }
   const asOrg = org.asOrg
 
-  // Capability handshake (cached). Publish ends in a go-live, so the publish
-  // lane must be offered.
-  const config = await client.discover()
-  if (config?.delivery && config.delivery.publish === false) {
-    say.err(
-      `Backend at ${client.origin} does not offer the publish lane (delivery.publish=false).`
-    )
-    return { exitCode: 1 }
-  }
+  // ⛔ There is no capability gate here any more, deliberately.
+  //
+  // This used to read `delivery.publish` from the discovery document and refuse when it
+  // was false. It could never fire: the backend sent a literal true for every deployment,
+  // so the gate compared a constant against false. The key is now gone on both sides
+  // (2026-08-30). Restoring a reader for it would re-create a check that cannot fail
+  // while implying a capability that was never negotiable.
+  //
+  // Discovery is not consulted on this path at all. The one leaf the CLI still reads
+  // (`delivery.siteSubscriptionRequired`) is read after the site create, where a
+  // credential is already in hand.
 
   // ⛔ NOTHING about a runtime is sent from here. `site.yml::runtime` was a
   // vestigial prop and is no longer read [Diego, 2026-08-22]; `?runtime=` is no

package/src/framework-index.json

@@ -1,9 +1,16 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-08-29T19:59:22.061Z",
+  "generatedAt": "2026-09-01T22:08:19.670Z",
   "packages": {
+    "@uniweb/api": {
+      "version": "0.1.0",
+      "path": "framework/api",
+      "deps": [
+        "@uniweb/core"
+      ]
+    },
     "@uniweb/build": {
-      "version": "0.30.0",
+      "version": "0.30.2",
       "path": "framework/build",
       "deps": [
         "@uniweb/content-reader",
@@ -27,7 +34,7 @@
       "deps": []
     },
     "@uniweb/core": {
-      "version": "0.14.0",
+      "version": "0.14.1",
       "path": "framework/core",
       "deps": [
         "@uniweb/semantic-parser",
@@ -74,7 +81,7 @@
       ]
     },
     "@uniweb/runtime": {
-      "version": "0.13.2",
+      "version": "0.13.3",
       "path": "framework/runtime",
       "deps": [
         "@uniweb/core",
@@ -87,7 +94,7 @@
       "deps": []
     },
     "@uniweb/schemas": {
-      "version": "0.2.11",
+      "version": "0.2.12",
       "path": "framework/schemas",
       "deps": []
     },
@@ -102,7 +109,7 @@
       "deps": []
     },
     "@uniweb/templates": {
-      "version": "0.10.0",
+      "version": "0.11.0",
       "path": "framework/templates",
       "deps": []
     },
@@ -112,7 +119,7 @@
       "deps": []
     },
     "@uniweb/unipress": {
-      "version": "0.8.16",
+      "version": "0.8.17",
       "path": "framework/unipress",
       "deps": [
         "@uniweb/build",
@@ -291,6 +298,18 @@
         "quote",
         "trades"
       ]
+    },
+    "conference": {
+      "name": "Conference",
+      "description": "A site that is also an app — sign-in, per-viewer data, and an editable programme. Ships a local backend so it runs with nothing installed.",
+      "tags": [
+        "app",
+        "api",
+        "backend",
+        "auth",
+        "permissions",
+        "conference"
+      ]
     }
   }
 }

package/src/index.js

@@ -814,10 +814,45 @@ async function main() {
     const originFlag =
       readFlagValue(loginArgs, '--backend') ||
       readFlagValue(loginArgs, '--registry')
-    await runRegistryLogin({
-      apiBase: resolveBackendOrigin(originFlag),
-      args: loginArgs
-    })
+    const apiBase = resolveBackendOrigin(originFlag)
+
+    // ⭐ The project says where it belongs — say so BEFORE authenticating elsewhere.
+    //
+    // `login` is deliberately NOT given the `site.yml::$backend` tier the site verbs
+    // get (see resolveBackendOrigin): the session it writes is machine-wide, so letting
+    // cwd pick the account you log into would be a silent surprise. But staying silent
+    // does not remove the failure, it MOVES it — you log into the default, and the next
+    // push/pull/publish resolves to `$backend` and warns about the mismatch. That is the
+    // routed-not-nagged case `$backend` was added for, missing at the one command a
+    // teammate runs FIRST after cloning.
+    //
+    // ⛔ Silent when the origin was named explicitly (--backend / --registry /
+    // UNIWEB_REGISTER_URL). A deliberate aim is not a mistake to warn about; a genuinely
+    // wrong one is still caught by the session-mismatch guard in BackendClient.token().
+    if (!originFlag && !process.env.UNIWEB_REGISTER_URL) {
+      try {
+        const { findNearbySiteBackend } = await import(
+          './utils/site-identity.js'
+        )
+        const nearby = findNearbySiteBackend(process.cwd())
+        if (nearby && nearby.backend !== apiBase) {
+          console.error(
+            `\x1b[33m⚠\x1b[0m This project syncs with ${nearby.backend} (site.yml::$backend), but login is targeting ${apiBase}.`
+          )
+          console.error(
+            `  Log in where the project belongs:  uniweb login --backend ${nearby.backend}`
+          )
+          console.error(
+            `  Continuing with ${apiBase} — a session is machine-wide, so this is a heads-up, not a block.\n`
+          )
+        }
+      } catch {
+        // Advisory only. A malformed site.yml, an unreadable directory or anything else
+        // here must never be the reason someone cannot log in.
+      }
+    }
+
+    await runRegistryLogin({ apiBase, args: loginArgs })
     return
   }
 

package/src/utils/bytes.js

@@ -0,0 +1,30 @@
+/**
+ * Byte formatting for refusal messages.
+ *
+ * Lives on its own because TWO lanes now print a storage refusal — the asset plan
+ * (`backend/site-media.js`) and the site create (`backend/site-sync.js`) — and the
+ * numbers must read identically in both. A second copy would drift in units or
+ * rounding, and a user comparing "you have 1.1 GiB" against "this needs 100 MB"
+ * cannot tell a real gap from a formatting difference.
+ */
+
+const KIB = 1024
+
+/**
+ * `1073741824` → `1 GiB`. Returns null for anything that is not a usable byte
+ * count, so a refusal that omits an extra prints nothing rather than `undefined`.
+ * @param {unknown} n
+ * @returns {string|null}
+ */
+export function humanBytes(n) {
+  if (typeof n !== 'number' || !Number.isFinite(n) || n < 0) return null
+  if (n < KIB) return `${n} B`
+  const units = ['KiB', 'MiB', 'GiB', 'TiB']
+  let v = n / KIB
+  let i = 0
+  while (v >= KIB && i < units.length - 1) {
+    v /= KIB
+    i++
+  }
+  return `${v >= 10 || Number.isInteger(v) ? Math.round(v) : v.toFixed(1)} ${units[i]}`
+}

package/src/utils/site-identity.js

@@ -28,8 +28,8 @@
  * and it has to move the readers and the writers together or it makes the split worse.
  */
 
-import { existsSync, readFileSync } from 'node:fs'
-import { join } from 'node:path'
+import { existsSync, readFileSync, readdirSync } from 'node:fs'
+import { join, dirname } from 'node:path'
 import yaml from 'js-yaml'
 import { DEFAULT_BACKEND_ORIGIN } from './config.js'
 
@@ -232,3 +232,66 @@ export function assertSiteBackendScope(siteDir, origin) {
     hint
   }
 }
+
+/**
+ * The `$backend` of the site project `startDir` sits in — for verbs that are NOT site
+ * verbs and so never resolve a site directory of their own.
+ *
+ * ⛔ **This does NOT feed the origin ladder, deliberately.** `login` writes a
+ * MACHINE-WIDE session (`~/.uniweb/registry-auth.json`), not a per-project one, so
+ * letting whichever directory you happen to stand in decide which backend you
+ * authenticate against would be a silent surprise — the same class of surprise
+ * `$backend` exists to remove. What this enables is a **notice**: the project says
+ * where it belongs, so we say so before authenticating somewhere else.
+ *
+ * ⭐ **Conservative by construction — it answers only when there is exactly ONE
+ * candidate.** A workspace of several sites has no single answer, and a confident
+ * *"did you mean localhost?"* aimed at the wrong one of three sites is worse than
+ * saying nothing. Ambiguity returns null and the caller stays quiet.
+ *
+ * ⚠️ Build-free, like everything else in this file — `login` is a STANDALONE command
+ * that must work outside a project, where `@uniweb/build` is not installed. That is why
+ * this cannot reuse `resolveSiteDir` (`commands/deploy.js`), which pulls build in.
+ *
+ * @param {string} startDir
+ * @returns {{ siteDir: string, backend: string }|null}
+ */
+export function findNearbySiteBackend(startDir) {
+  // 1. Walk UP for the site we are standing in or under. Bounded: a `site.yml` more
+  //    than a few levels above is not "the project you are in", it is a coincidence,
+  //    and at the filesystem root it would be someone else's entirely.
+  let dir = startDir
+  for (let i = 0; i < 4; i++) {
+    if (existsSync(join(dir, 'site.yml'))) {
+      const { backend } = readSiteIdentity(dir)
+      return backend ? { siteDir: dir, backend } : null
+    }
+    const up = dirname(dir)
+    if (up === dir) break
+    dir = up
+  }
+
+  // 2. Standing AT a project root, the site is one level down — `site/` in the default
+  //    layout, or a lone entry under `sites/`. Two or more candidates is a workspace,
+  //    which is exactly the ambiguity above.
+  const candidates = []
+  if (existsSync(join(startDir, 'site', 'site.yml')))
+    candidates.push(join(startDir, 'site'))
+  const sitesDir = join(startDir, 'sites')
+  if (existsSync(sitesDir)) {
+    let entries = []
+    try {
+      entries = readdirSync(sitesDir, { withFileTypes: true })
+    } catch {
+      entries = []
+    }
+    for (const e of entries) {
+      if (!e.isDirectory()) continue
+      const d = join(sitesDir, e.name)
+      if (existsSync(join(d, 'site.yml'))) candidates.push(d)
+    }
+  }
+  if (candidates.length !== 1) return null
+  const { backend } = readSiteIdentity(candidates[0])
+  return backend ? { siteDir: candidates[0], backend } : null
+}