uniweb 0.30.1 → 0.31.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.30.1",
+  "version": "0.31.1",
   "description": "Create structured Vite + React sites with content/code separation",
   "type": "module",
   "bin": {
@@ -41,13 +41,13 @@
     "js-yaml": "^4.1.0",
     "prompts": "^2.4.2",
     "tar": "^7.0.0",
-    "@uniweb/core": "^0.12.1",
-    "@uniweb/kit": "^0.13.6",
-    "@uniweb/semantic-parser": "^1.3.1",
-    "@uniweb/runtime": "^0.12.13"
+    "@uniweb/core": "^0.13.0",
+    "@uniweb/kit": "^0.13.7",
+    "@uniweb/runtime": "^0.13.0",
+    "@uniweb/semantic-parser": "^1.3.1"
   },
   "peerDependencies": {
-    "@uniweb/build": "^0.26.1",
+    "@uniweb/build": "^0.27.1",
     "@uniweb/semantic-parser": "^1.3.1",
     "@uniweb/content-reader": "^1.2.4"
   },

package/partials/agents.md

@@ -287,7 +287,7 @@ Paths are relative to the site package you identified in step 1 — `site/` in t
 
 **Change a nav item.** First check how nav is produced. If `<site>/layout/header.md` lists the links (a markdown list, or a `yaml:nav` block), edit it there. If it doesn't, the Header is generating nav from the page hierarchy — change page titles and order in `site.yml` / `page.yml` instead.
 
-**Update the project's Uniweb dependencies — and this file.** `uniweb update`. One command aligns every `@uniweb/*` dependency *and* refreshes this AGENTS.md together, to the version matrix of the CLI that runs it. Preview with `--dry-run`. **Don't reach for `npm update` / `pnpm update`** — see *Staying current* in Part 5 for why that breaks things quietly.
+**Update the project's Uniweb dependencies — and this file.** `npx uniweb@latest update`. One command aligns every `@uniweb/*` dependency *and* refreshes this AGENTS.md together. Preview with `--dry-run`. ⛔ **The `@latest` is doing the work** — a bare `uniweb update` runs the CLI this project already pins, which aligns you to the matrix you already have and correctly reports nothing to do. **Don't reach for `npm update` / `pnpm update`** — see *Staying current* in Part 5 for why that breaks things quietly.
 
 **Change one section's columns / spacing / variant.** Check that type's `meta.js` `params:` first. If the knob exists, set it in that section's frontmatter and you're done, in the content lane. If it doesn't, it's a foundation change — see the warning in step 3.
 
@@ -1751,7 +1751,7 @@ fetch:
   limit: 3
 ```
 
-**Lean lists with `deferred:`.** Collections with heavy fields (article bodies, large nested arrays) can declare `deferred: [body]` in `site.yml`. The cascade payload omits those fields; per-record full files are emitted at `/data/<name>/<slug>.json` (file-based collections) or fetched from an author-declared `detailUrl:` (API-backed). On dynamic-route pages the focused record's full data is delivered automatically; elsewhere components fetch on demand via `useEntityDetail`.
+**Lean lists with `deferred:`.** Collections with heavy fields (article bodies, large nested arrays) can declare `deferred: [body]` in `site.yml`. The cascade payload omits those fields; per-record full files are emitted at `/data/<name>/<slug>.json` (file-based collections) or fetched from an author-declared `detailUrl:` (API-backed). On dynamic-route pages the focused record's full data is delivered automatically; elsewhere components fetch on demand via `useEntityDetail`. The hook is safe to call on any collection: when there is no separate detail source it returns the record you passed in, because nothing was stripped from it.
 
 **Component-side fetching.** When a component genuinely needs to fetch on its own (a search box, "load more", a lazy popover), use the kit hooks — `useFetched`, `useCacheEntry`, `useEntityDetail`. They share the framework's cache and dispatcher with declarative fetches; same-key requests dedupe automatically.
 
@@ -2024,8 +2024,9 @@ collector's event dimension into a cardinality problem.
 
 ### Choosing what a site sends
 
-By default a site sends `page_view`, `outbound_click` and `section_view`. Narrow
-or widen that with `emit`:
+By default a site sends `page_view`, `outbound_click` and `section_view` — or,
+where a host supplies the collector, whatever that host declares it collects.
+Narrow or widen that with `emit`:
 
 ```yaml
 # site.yml — your own collector
@@ -2044,10 +2045,19 @@ are read key by key, so naming `emit` alone overrides nothing else the host
 declared. And declaring your own `endpoint:` always wins, so a site pointing at
 its own collector keeps working on any host, including none.
 
-`minimal` is `page_view` alone. `standard` is the default. `all` is a standing
-yes, so an event added in a later framework release is included without you
-changing anything — which is exactly why `standard` exists as well: it is a
-curated set that a release cannot grow behind your back.
+`minimal` is `page_view` alone. `standard` is the default when you supply your
+own `endpoint:`. `all` is a standing yes, so an event added in a later framework
+release is included without you changing anything — which is exactly why
+`standard` exists as well: it is a curated set that a release cannot grow behind
+your back.
+
+⭐ **Saying nothing means two different things, and which one depends on who
+supplies the address.** A site with its own `endpoint:` gets `standard`. A site
+on a **host-supplied** collector gets **whatever that host declares it
+collects** — it has no address of its own, so the arrangement is that the host
+does analytics for it, and the set grows when the host starts collecting
+something new. **Naming `emit` always wins**, so pin it if you would rather not
+follow your host.
 
 A site can also set **`flushIntervalMs`** to widen the batching window (default
 5000, milliseconds — `30` is thirty *milliseconds*). A host that supplies your
@@ -2216,7 +2226,8 @@ uniweb i18n init-freeform / update-hash / move / rename / prune --freeform
 uniweb -v                         # Installed CLI version — and whether a newer one exists
 uniweb doctor                     # Diagnose project configuration (--fix to auto-repair)
 uniweb validate                   # Check file-based data against declared schemas (--strict for CI)
-uniweb update                     # Align @uniweb/* deps + AGENTS.md to the CLI (--dry-run, --yes)
+npx uniweb@latest update          # Align @uniweb/* deps + AGENTS.md (--dry-run, --yes)
+                                  #   bare `uniweb update` aligns to the CLI you ALREADY have
 uniweb inspect <path>             # Show parsed content for a section or page (--raw for the AST)
 
 uniweb <command> --help           # Per-command flags — no side effects. Prefer this over guessing.
@@ -2284,15 +2295,28 @@ Either side can publish. Nothing about this changes how you build: the same foun
 ```bash
 uniweb -v                  # installed CLI version, and whether a newer one is available
 uniweb doctor              # report drift in this project, changing nothing
-uniweb update --dry-run    # preview exactly what update would change
-uniweb update              # apply: align @uniweb/* deps AND refresh AGENTS.md
+npx uniweb@latest update --dry-run   # preview exactly what update would change
+npx uniweb@latest update             # apply: align @uniweb/* deps AND refresh AGENTS.md
 ```
 
-**`uniweb update` is the command for bringing a project up to date.** It aligns the project's `@uniweb/*` dependencies *and* this AGENTS.md to the version matrix of the CLI that runs it. Deps and documentation move together — that's the whole point of the verb.
+**`npx uniweb@latest update` is the command for bringing a project up to date.** It aligns the project's `@uniweb/*` dependencies *and* this AGENTS.md to the version matrix of the CLI that runs it. Deps and documentation move together — that's the whole point of the verb.
+
+> ### ⛔ WRITE `@latest`. A BARE `uniweb update` IS USUALLY A NO-OP, AND IT SAYS SO CONVINCINGLY
+>
+> `update` reconciles this project against **the matrix of the CLI that runs it** — and in a project,
+> `uniweb` resolves to the copy in your own `node_modules`, pinned by your own `package.json`. That
+> copy has no way to know a newer release exists.
+>
+> ⇒ **It reports everything aligned and changes nothing — correctly.** It answered the question it
+> was asked, which is why the output looks like success rather than a mistake. The same applies to
+> `pnpm uniweb update` and to a stale global install.
+>
+> ⭐ **`@latest` is what makes it a question about the newest release** rather than about the one you
+> already have. It also bumps the pin, so the next bare invocation is no longer stale.
 
 > **Don't run `npm update` or `pnpm update` on the `@uniweb/*` packages.** They're a matched set resolved by the CLI's version matrix, not independently versioned libraries you upgrade one at a time. Updating them directly gets you a combination nobody tested, and it won't refresh AGENTS.md — so this guide silently drifts out of sync with the code it describes, which is worse than being out of date, because nothing looks wrong.
 
-Two ordering rules: `update` won't refresh AGENTS.md while declared deps still lag the CLI, or while edited deps haven't been installed — either would put the doc ahead of the code. And updating the CLI itself is your package manager's job (`npm i -g uniweb@latest`, `pnpm add -g uniweb@latest`); `uniweb update` does not do that. To pin a project to the newest published release with no global install: `npx uniweb@latest update --yes`.
+Two ordering rules: `update` won't refresh AGENTS.md while declared deps still lag the CLI, or while edited deps haven't been installed — either would put the doc ahead of the code. And updating the CLI itself is your package manager's job (`npm i -g uniweb@latest`, `pnpm add -g uniweb@latest`); `uniweb update` does not do that.
 
 ### `package.json` `uniweb` block
 

package/src/backend/client.js

@@ -537,28 +537,6 @@ export class BackendClient {
     }
   }
 
-  /**
-   * ASSUMED endpoint (not built yet).
-   * GET /dev/site/{uuid}/can-go-live — the pre-go-live payment gate:
-   *   { ok: true }                                          // already paid → proceed
-   *   { payment_required: true, checkout_url, wait_token? } // open the URL, settle, retry
-   * The framework is provider-agnostic: it only opens `checkout_url` and waits.
-   * null on 404 / any failure → the caller PROCEEDS (degrade: publish ships
-   * before payment lands; same posture as siteStatus on a missing route).
-   * @param {string} uuid - the site-content uuid
-   * @returns {Promise<object|null>}
-   */
-  async canGoLive(uuid) {
-    try {
-      const res = await this.request(
-        `/dev/site/${encodeURIComponent(uuid)}/can-go-live`
-      )
-      return res.ok ? await res.json().catch(() => null) : null
-    } catch {
-      return null
-    }
-  }
-
   /**
    * Deliver a site's processed assets (plan → PUT-per-file) to the backend's
    * content-addressed store. Thin pass-through to utils/asset-upload.js with this

package/src/backend/payment-handoff.js

@@ -1,124 +1,160 @@
 /**
- * Payment handoff — the one piece of `uniweb publish` that's three-way
- * (framework + backend + the `uniweb.app` web app). Design: payment-handoff-plan.md.
+ * Payment refusal — what `uniweb publish` does when the backend says a site
+ * cannot go live until it is paid for.
  *
- * The intent: `uniweb publish` on an unpaid (or newly-charged) site should just
- * handle it — open a browser to `uniweb.app`, let the user pay, and continue.
- * An already-paid site never opens a browser.
+ * THE BACKEND IS THE ONLY GATE. It evaluates on every publish, on every
+ * backend, whatever that deployment is configured to require — a backend with
+ * subscriptions switched off simply never refuses. The CLI holds no opinion about whether a
+ * backend charges and must never form one: it attempts the publish and reads
+ * the answer.
  *
- * The framework's ENTIRE payment knowledge is "open this URL, wait for done" —
- * PROVIDER-AGNOSTIC. The CLI opens whatever `checkout_url` the backend hands it;
- * the app drives the provider (Stripe or anything else) and settles with the
- * backend. We reuse `awaitBrowserCallback` (the same loopback `uniweb login`
- * uses) for the open + wait.
+ * ⛔ THERE IS NO PRE-FLIGHT, AND ADDING ONE BACK IS A REGRESSION. A
+ * `GET …/can-go-live` probe used to run before go-live; it called a route no
+ * backend serves, and it folded every failure — 404 included — into
+ * "proceed". A check that answers "fine" when it cannot reach the server is not
+ * a check, and it made the CLI assume a posture it has no business assuming. A
+ * pre-flight also cannot be authoritative: the backend re-evaluates at publish
+ * time regardless, so a second asker is a second producer of one decision.
  *
- * DEGRADES: when the backend exposes no can-go-live route (404 / any failure),
- * `canGoLive` returns null and we PROCEED — so publish ships before the payment
- * route lands (same posture as `status --remote` on a missing endpoint). Live
- * acceptance is the three-way test.
+ * WHAT THE CLI KNOWS ABOUT PAYMENT: nothing. It opens whatever settlement URL
+ * the backend hands it, VERBATIM — provider-agnostic, and route-agnostic. The
+ * app drives the provider and settles with the backend.
+ *
+ * ⛔ AND IT APPENDS NOTHING TO THAT URL. The old handoff added
+ * `redirect_uri=http://127.0.0.1:<port>/callback`, `state` and `wait_token`,
+ * then waited on a loopback for the app to redirect back. Two reasons it is
+ * gone: it obliged the web app to know a CLI exists and honour a callback, and
+ * a loopback callback requires the browser and the CLI
+ * on the SAME MACHINE, so over SSH or in a container it hung for its full
+ * timeout and then reported "payment was not completed", which was false.
  */
 
-import { randomBytes } from 'node:crypto'
-
-import { awaitBrowserCallback } from '../utils/registry-auth.js'
-import { isNonInteractive } from '../utils/interactive.js'
-
-// Append query params to a backend-supplied URL without disturbing its own.
-function withParams(url, params) {
-  const u = new URL(url)
-  for (const [k, v] of Object.entries(params)) {
-    if (v != null) u.searchParams.set(k, String(v))
-  }
-  return u.toString()
-}
+/** Reasons the CLI knows how to act on. An ALLOWLIST, never an inventory. */
+const ACTIONABLE_REASONS = new Set(['no_subscription'])
 
 /**
- * Settle payment for a site before go-live, if the backend says it's needed.
+ * Read a `402` from the publish call and decide what the CLI does. Pure — no
+ * network, no browser, no process exit — so the decision is testable on its own.
+ *
+ * ⛔ THE RULE, and it is a property of the wire rather than a CLI preference:
+ * NEVER route to a purchase surface from the ABSENCE of a recognised token. A
+ * purchase surface is opened by a `reason` that NAMES one; everything else
+ * surfaces the backend's own sentence and stops. Degrading that way means an
+ * older CLI shows you the message — annoying, honest, recoverable. Degrading
+ * the other way sends someone to a checkout for something they cannot buy.
+ *
+ * ⛔ Do NOT turn `ACTIONABLE_REASONS` into "every reason the backend has". The
+ * set is open by design and a stale copy here fails in the worst direction; an
+ * allowlist is safe precisely because what it misses lands on `stop`.
+ * ⛔ Do NOT parse `detail` — it is deliberately not asserted word-for-word, and
+ * `reason` exists to do the job parsing it would.
+ *
+ * NOTE ON `reason`'s PRESENCE: it is NOT guaranteed by the content type. A 402
+ * naming a condition the caller can act on carries one; nothing guarantees it
+ * in general — a declined card is `problem+json` and deliberately carries none,
+ * because there is no machine decision for a client to make about it. This reads `reason` when it is there and needs
+ * no invariant, which is why that correction cost this branch nothing.
  *
  * @param {object} o
- * @param {import('./client.js').BackendClient} o.client
- * @param {string|null} o.uuid - the site-content uuid (null only on a dry run; a
- *   real publish creates the site before anything uploads, so it is set by here)
- * @param {string[]} o.args
- * @param {object} o.say - { ok, info, warn, err, dim } reporters
- * @param {boolean} [o.dryRun]
- * @returns {Promise<{ proceed: boolean }>} proceed:false → the caller aborts go-live.
+ * @param {number} o.status - the HTTP status
+ * @param {string} [o.contentType] - the response's content-type header
+ * @param {string} [o.body] - the raw response body
+ * @returns {{ kind: 'not-payment' }
+ *          | { kind: 'settle', url: string, handle: string|null, reason: string, message: string|null }
+ *          | { kind: 'stop', reason: string|null, message: string|null }}
  */
-export async function settlePaymentIfNeeded({
-  client,
-  uuid,
-  args,
-  say,
-  dryRun = false
-}) {
-  // No uuid yet (a first publish mints it on push) → nothing to check here; the
-  // post-push go-live is the moment the backend gates on payment.
-  if (!uuid) return { proceed: true }
+export function readPaymentRefusal({ status, contentType = '', body = '' } = {}) {
+  if (status !== 402) return { kind: 'not-payment' }
+
+  let problem = null
+  try {
+    problem = JSON.parse(body)
+  } catch {
+    /* a non-JSON 402 is simply unrecognised — it falls to `stop` below */
+  }
+  if (!problem || typeof problem !== 'object') {
+    return { kind: 'stop', reason: null, message: null }
+  }
+
+  // The human sentence, in the backend's own words. `detail` is the 7807
+  // member; `title` is the fallback when a body carries no detail.
+  const message =
+    (typeof problem.detail === 'string' && problem.detail) ||
+    (typeof problem.title === 'string' && problem.title) ||
+    null
+
+  // `status` is NOT a discriminator: the backend's problem bodies carry it as
+  // the NUMBER 402 while at least one hand-built 402 elsewhere on their wire
+  // carries a STRING. Same key, two types, neither failing loudly — so this
+  // reads `reason` and the content type instead, and never `body.status`.
+  const isProblem = String(contentType).includes('application/problem+json')
+  const reason =
+    isProblem && typeof problem.reason === 'string' && problem.reason
+      ? problem.reason
+      : null
 
-  // Dry-run reports the intent WITHOUT touching the network — the can-go-live
-  // read is auth-gated and must not force a login on a dry-run.
-  if (dryRun) {
-    say.dim(
-      `Payment     : would check whether go-live needs payment for ${uuid}`
-    )
-    return { proceed: true }
+  if (!reason || !ACTIONABLE_REASONS.has(reason)) {
+    return { kind: 'stop', reason, message }
   }
 
-  const verdict = await client.canGoLive(uuid)
-  // Degrade (no route) or already-paid → proceed.
-  if (!verdict || verdict.ok || !verdict.payment_required)
-    return { proceed: true }
+  // Actionable — but only if the backend actually handed over somewhere to go.
+  // A recognised reason with no settlement block is a backend that has not
+  // built that half yet: still a stop, and still with its own sentence.
+  const s = problem.settlement
+  const url = s && typeof s.url === 'string' && s.url ? s.url : null
+  if (!url) return { kind: 'stop', reason, message }
 
-  const checkoutUrl = verdict.checkout_url
-  if (!checkoutUrl) {
-    say.warn(
-      'The backend reports payment is required but returned no checkout URL — proceeding.'
-    )
-    return { proceed: true }
+  return {
+    kind: 'settle',
+    url,
+    handle: s && typeof s.handle === 'string' && s.handle ? s.handle : null,
+    reason,
+    message
   }
+}
+
+/**
+ * Report a payment refusal to the user, and open the settlement page when the
+ * backend supplied one.
+ *
+ * ⛔ Returns rather than exits — the caller owns the exit code, and a refusal
+ * is not a crash: the content is already synced as a draft, so re-running
+ * after paying is the recovery.
+ *
+ * @param {object} o
+ * @param {ReturnType<typeof readPaymentRefusal>} o.verdict
+ * @param {string[]} o.args - argv slice (for --non-interactive detection)
+ * @param {object} o.say - { ok, info, warn, err, dim } reporters
+ * @param {(url: string) => Promise<boolean>} [o.open] - injected for tests
+ * @returns {Promise<{ opened: boolean }>}
+ */
+export async function reportPaymentRefusal({ verdict, args = [], say, open }) {
+  // The backend's own sentence is the HEADLINE when there is one. A generic
+  // lead would be wrong as often as right — "payment is required" does not
+  // describe a declined card — and `detail` is written for this reader.
+  say.err(verdict.message || 'This site cannot go live until it is paid for.')
 
-  if (dryRun) {
-    say.dim(`Payment     : required — would open ${checkoutUrl}`)
-    return { proceed: true }
+  if (verdict.kind !== 'settle') {
+    // The push completed before go-live, so the content is safely stored.
+    say.dim('The site is synced as a draft; nothing was made live.')
+    return { opened: false }
   }
 
+  const { isNonInteractive } = await import('../utils/interactive.js')
   if (isNonInteractive(args)) {
-    say.err(
-      'Payment is required to publish this site, and the CLI is non-interactive.'
-    )
-    say.dim(`Complete it in a browser, then re-run: ${checkoutUrl}`)
-    return { proceed: false }
+    say.dim(`Complete it in a browser, then re-run \`uniweb publish\`:`)
+    say.dim(`  ${verdict.url}`)
+    return { opened: false }
   }
 
-  // The CSRF nonce the app echoes back on the done-signal redirect. The
-  // wait_token (when present) lets the app correlate the session backend-side.
-  const state = randomBytes(16).toString('hex')
-  say.info('Payment required — completing it in your browser…')
-  try {
-    await awaitBrowserCallback({
-      buildUrl: (redirectUri) =>
-        withParams(checkoutUrl, {
-          redirect_uri: redirectUri,
-          state,
-          wait_token: verdict.wait_token
-        }),
-      validate: (params) => {
-        if (params.get('error')) return { error: params.get('error') }
-        if (params.get('state') !== state)
-          return { error: 'state mismatch — please retry.' }
-        return { value: true } // ok=1 / any non-error return = the app settled with the backend
-      },
-      openingLabel: 'Opening uniweb.app to complete payment…',
-      waitingLabel: 'Waiting for payment to complete (5 min)…',
-      timeoutMs: 5 * 60 * 1000,
-      okTitle: 'Payment complete',
-      errTitle: 'Payment failed'
-    })
-  } catch (err) {
-    say.err(`Payment was not completed: ${err.message}`)
-    say.dim('Re-run `uniweb publish` once payment is done.')
-    return { proceed: false }
+  const openBrowser = open || (await import('../utils/registry-auth.js')).openBrowser
+  say.info('Opening your browser to complete it…')
+  say.dim(`  ${verdict.url}`)
+  // VERBATIM. Nothing is appended — see the header.
+  const opened = await openBrowser(verdict.url)
+  if (!opened) {
+    say.warn('Could not open a browser automatically — open the URL above.')
   }
-  say.ok('Payment complete.')
-  return { proceed: true }
+  say.dim('Once payment is complete, re-run `uniweb publish`.')
+  return { opened }
 }

package/src/commands/publish.js

@@ -88,7 +88,10 @@ import {
   bringFoundationAlong,
   bringExtensionsAlong
 } from '../backend/foundation-bring-along.js'
-import { settlePaymentIfNeeded } from '../backend/payment-handoff.js'
+import {
+  readPaymentRefusal,
+  reportPaymentRefusal
+} from '../backend/payment-handoff.js'
 import { reportSchemalessCollections } from '../utils/schemaless-report.js'
 import { uploadSiteData } from '../utils/site-data-upload.js'
 
@@ -353,13 +356,10 @@ export async function publish(args = []) {
       cliBin: process.argv[1],
       dryRun: true
     })
-    await settlePaymentIfNeeded({
-      client,
-      uuid: siteYml.$uuid || null,
-      args,
-      say,
-      dryRun: true
-    })
+    // No payment line on a dry run. The backend is the only gate and it
+    // answers at go-live, so the honest dry-run answer is silence rather than
+    // a guess. (The old "would check whether go-live needs payment" described
+    // a pre-flight probe that has been removed — payment-handoff.js.)
     return { exitCode: 0 }
   }
 
@@ -409,8 +409,13 @@ export async function publish(args = []) {
   if (!fnd.proceed) return { exitCode: fnd.refused ? 1 : 0 }
 
   // 2. Build the site data (link mode): dist/site-content.json (+ per-locale),
-  //    dist/data/*, dist/_search/*, dist/assets/*. Spawn the SAME CLI binary so
-  //    the inner build can't resolve to a different installed version.
+  //    dist/data/*, dist/assets/*. Spawn the SAME CLI binary so the inner
+  //    build can't resolve to a different installed version.
+  //
+  //    ⛔ NO SEARCH INDEX. This listed `dist/_search/*` until 2026-08-26; the
+  //    link lane stopped emitting one on 2026-08-01 (`@uniweb/build`
+  //    `site/build-site-data.js` step 5) because only one of the two
+  //    publishers produced it.
   say.info('Building site…')
   console.log('')
   execSync(`node ${JSON.stringify(process.argv[1])} build --link`, {
@@ -435,6 +440,8 @@ export async function publish(args = []) {
   let probe
   try {
     probe = await emitSyncPackages(siteDir, {
+      // Resolves a foundation-relative `@/x` model ref into `@org/x`.
+      ...(asOrg ? { org: asOrg } : {}),
       ...(foundationDir ? { foundationDir } : {}),
       resolveModel
     })
@@ -634,6 +641,8 @@ export async function publish(args = []) {
   let pkg
   try {
     pkg = await emitSyncPackages(siteDir, {
+      // Resolves a foundation-relative `@/x` model ref into `@org/x`.
+      ...(asOrg ? { org: asOrg } : {}),
       ...(foundationDir ? { foundationDir } : {}),
       resolveModel,
       priorHashes,
@@ -673,18 +682,6 @@ export async function publish(args = []) {
     return { exitCode: 1 }
   }
 
-  // 6. Payment gate — the backend says whether go-live needs payment. Settles
-  //    via a browser handoff to uniweb.app; degrades to "proceed" when the
-  //    backend exposes no payment route. The draft is already synced, so a
-  //    decline leaves a recoverable state (re-run after paying).
-  const pay = await settlePaymentIfNeeded({ client, uuid: siteUuid, args, say })
-  if (!pay.proceed) {
-    say.info(
-      'Site synced as a draft but not made live. Re-run `uniweb publish` once payment is complete.'
-    )
-    return { exitCode: 0 }
-  }
-
   // 7. Go live — make the just-pushed composite live (its current backend state).
   const siteContent = JSON.parse(await readFile(contentPath, 'utf8'))
   const languages = languagesFromContent(siteContent)
@@ -700,13 +697,29 @@ export async function publish(args = []) {
     return { exitCode: 1 }
   }
   if (!pubRes.ok) {
+    const body = await pubRes.text().catch(() => '')
+
+    // A 402 is the backend's payment gate — the ONLY gate, evaluated here on
+    // every publish against whatever posture that deployment runs. It is a
+    // refusal, not a fault: the content is already synced as a draft, so the
+    // recovery is to settle and re-run. Give it the backend's own sentence
+    // rather than the raw envelope.
+    const refusal = readPaymentRefusal({
+      status: pubRes.status,
+      contentType: pubRes.headers?.get?.('content-type') || '',
+      body
+    })
+    if (refusal.kind !== 'not-payment') {
+      await reportPaymentRefusal({ verdict: refusal, args, say })
+      return { exitCode: 1 }
+    }
+
     say.err(`Publish rejected: HTTP ${pubRes.status} ${pubRes.statusText}`)
     if (pubRes.status === 401 || pubRes.status === 403) {
       say.dim(
         "Credentials weren't accepted — run `uniweb login` (or pass --token <bearer>)."
       )
     }
-    const body = await pubRes.text().catch(() => '')
     if (body) say.dim(body.slice(0, 800))
     return { exitCode: 1 }
   }

package/src/commands/push.js

@@ -373,6 +373,8 @@ export async function push(args = [], deps = {}) {
     let mediaRefs = []
     try {
       const probe = await emitSyncPackages(siteDir, {
+      // Resolves a foundation-relative `@/x` model ref into `@org/x`.
+      ...(asOrg ? { org: asOrg } : {}),
         ...(foundationDir ? { foundationDir } : {}),
         resolveModel: makeModelResolver({ client, offline: false })
       })
@@ -467,6 +469,8 @@ export async function push(args = [], deps = {}) {
   let pkg
   try {
     pkg = await emitSyncPackages(siteDir, {
+      // Resolves a foundation-relative `@/x` model ref into `@org/x`.
+      ...(asOrg ? { org: asOrg } : {}),
       ...(foundationDir ? { foundationDir } : {}),
       resolveModel: makeModelResolver({
         client,

package/src/framework-index.json

@@ -1,9 +1,9 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-08-26T01:46:58.853Z",
+  "generatedAt": "2026-08-27T16:19:55.310Z",
   "packages": {
     "@uniweb/build": {
-      "version": "0.26.1",
+      "version": "0.27.1",
       "path": "framework/build",
       "deps": [
         "@uniweb/content-reader",
@@ -29,7 +29,7 @@
       "deps": []
     },
     "@uniweb/core": {
-      "version": "0.12.1",
+      "version": "0.13.0",
       "path": "framework/core",
       "deps": [
         "@uniweb/semantic-parser",
@@ -42,14 +42,14 @@
       "deps": []
     },
     "@uniweb/icons": {
-      "version": "0.4.3",
+      "version": "0.4.4",
       "path": "framework/icons",
       "deps": [
         "@uniweb/core"
       ]
     },
     "@uniweb/kit": {
-      "version": "0.13.6",
+      "version": "0.13.7",
       "path": "framework/kit",
       "deps": [
         "@uniweb/core",
@@ -68,7 +68,7 @@
       "deps": []
     },
     "@uniweb/projections": {
-      "version": "0.3.6",
+      "version": "0.3.7",
       "path": "framework/projections",
       "deps": [
         "@uniweb/content-writer",
@@ -76,7 +76,7 @@
       ]
     },
     "@uniweb/runtime": {
-      "version": "0.12.13",
+      "version": "0.13.0",
       "path": "framework/runtime",
       "deps": [
         "@uniweb/core",
@@ -89,7 +89,7 @@
       "deps": []
     },
     "@uniweb/schemas": {
-      "version": "0.2.10",
+      "version": "0.2.11",
       "path": "framework/schemas",
       "deps": []
     },
@@ -114,7 +114,7 @@
       "deps": []
     },
     "@uniweb/unipress": {
-      "version": "0.8.13",
+      "version": "0.8.14",
       "path": "framework/unipress",
       "deps": [
         "@uniweb/build",

package/src/utils/registry-auth.js

@@ -321,7 +321,9 @@ async function loginViaTokenPaste({ apiBase, nonInteractive }) {
 }
 
 // Open a URL in the default browser. Returns whether it launched.
-async function openBrowser(url) {
+// Exported for the publish payment refusal, which opens the backend's
+// settlement URL VERBATIM and needs no loopback (backend/payment-handoff.js).
+export async function openBrowser(url) {
   try {
     const { exec } = await import('node:child_process')
     const cmd =