uniweb 0.12.34 → 0.12.36

package/README.md

@@ -62,7 +62,7 @@ pnpm build      # Build foundation + site for production
 pnpm preview    # Preview the production build
 ```
 
-The `build` command outputs to `site/dist/`. With pre-rendering enabled (the default for official templates), you get static HTML files ready to deploy anywhere. For the actual deploy step (and the `uniweb publish` / `uniweb deploy` commands), see [Deployment](#deployment) below.
+The `build` command outputs to `site/dist/`. With pre-rendering enabled (the default for official templates), you get static HTML files ready to deploy anywhere. For the actual deploy step (and the `uniweb deploy` / `uniweb register` commands), see [Deployment](#deployment) below.
 
 ## What You Get
 
@@ -258,7 +258,7 @@ The `src/` folder (your project's foundation) ships with your project as a conve
 | **Local folder** | Foundation lives in your workspace | Developing site and components together            |
 | **Runtime link** | Foundation loads from a URL        | Independent release cycles, platform-managed sites |
 
-You can delete the `src/` folder entirely and point your site at a published foundation. Or develop a foundation locally, then publish it for other sites to consume. The site doesn't care where its components come from.
+You can delete the `src/` folder entirely and point your site at a registered foundation. Or develop a foundation locally, then register it for other sites to consume. The site doesn't care where its components come from.
 
 **This enables two development patterns:**
 
@@ -327,20 +327,20 @@ uniweb add ci --host=github-pages
 
 ### Path 2 — Someone else manages the content
 
-You're building a foundation for clients, content authors, or any team that won't write markdown. The foundation is your product; the repo's `site/` is a test harness for the code (run `pnpm dev` to preview your components against sample content). You don't deploy a site — you publish a foundation:
+You're building a foundation for clients, content authors, or any team that won't write markdown. The foundation is your product; the repo's `site/` is a test harness for the code (run `pnpm dev` to preview your components against sample content). You don't deploy a site — you register a foundation:
 
 ```bash
 cd src
-uniweb publish @your-org/foundation-name
+uniweb register --scope @your-org
 ```
 
 Real sites built on your foundation are managed in the **Uniweb apps** (web + desktop) — visual editors designed for non-technical authors. They never see git, markdown, yaml, or React. They see *your* components, with live previews and visual controls for the params you defined. The foundation becomes the editor's native vocabulary for that site: you keep creative control of the design system, they get an editor that feels custom-built for them.
 
 This is the best path when site content has a life independent of the foundation's release cycle — agencies, design studios, multi-client teams, or any project where content authors aren't the same people as the developers.
 
-### Roadmap — Hybrid
+### Hybrid
 
-A future version will let markdown in a git repo and content in the Uniweb apps stay in two-way sync. Authors edit visually, devs edit in their IDE, both surfaces work on the same content. On the roadmap; not available today.
+Markdown in a git repo and content in the Uniweb apps can share the same site. Directional sync is available today: `uniweb push` sends local content to the backend, `uniweb pull` brings the backend's content back to local files, and `uniweb clone` bootstraps a local project from a site that already lives in the backend. Authors edit visually, devs edit in their IDE, both surfaces work on the same content. The advanced two-way-merge experience — conflict resolution, branch isolation, and review flows when both surfaces change the same content concurrently — is still evolving.
 
 ### Commands at a glance
 
@@ -349,7 +349,7 @@ A future version will let markdown in a git repo and content in the Uniweb apps
 | `uniweb add ci --host=<adapter>` | Scaffold a CI workflow in your repo (today: `github-pages`). The host runs `uniweb build` on each push. |
 | `uniweb deploy` | Deploy to Uniweb hosting (default). With `--host=<adapter>`, push directly to a static host — builds, uploads, invalidates in one step. |
 | `uniweb export` | Produce a self-contained `dist/` for any static host. You upload it yourself. `--host=<adapter>` adds host-specific helper files. |
-| `uniweb publish @org/name` | Publish a foundation to the registry (path 2). |
+| `uniweb register --scope @org` | Register a foundation to the registry (path 2). |
 | `uniweb build` | Inspect a build locally. For shipping, use `deploy` or `export`. |
 | `uniweb update` | Align this project with the CLI you're running: bump `@uniweb/*` deps in every `package.json` to the CLI's matrix (then install), and refresh `AGENTS.md`. Pins to *this* CLI's matrix — run `npx uniweb@latest update` to align to the latest release. Updating the CLI itself is your package manager's job (`npm i -g uniweb@latest`). |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.12.34",
+  "version": "0.12.36",
   "description": "Create structured Vite + React sites with content/code separation",
   "type": "module",
   "bin": {
@@ -46,8 +46,8 @@
     "@uniweb/runtime": "0.8.20"
   },
   "peerDependencies": {
-    "@uniweb/build": "0.14.17",
     "@uniweb/content-reader": "1.1.12",
+    "@uniweb/build": "0.14.19",
     "@uniweb/semantic-parser": "1.1.17"
   },
   "peerDependenciesMeta": {

package/partials/agents.md

@@ -142,28 +142,39 @@ pnpm install                      # Install dependencies
 pnpm build                        # Build for production
 pnpm preview                      # Preview production build (SSG + SPA)
 
-# Ship the site (uniweb verbs)
-uniweb deploy                     # Deploy to Uniweb hosting (default; needs `uniweb login` first)
+# Ship a site to Uniweb hosting (needs `uniweb login`)
+uniweb publish                    # The smart path: bring the foundation along (releasing it to the
+                                  # catalog if its code changed), sync content, and go live
+
+# Ship a site to a third-party host instead
 uniweb deploy --host=<adapter>    # Deploy to a static host: cloudflare-pages, netlify,
                                   # vercel, github-pages, s3-cloudfront, generic-static
-uniweb deploy --dry-run           # Resolve foundation/runtime + print summary; no writes
 uniweb export                     # Build dist/ for any static host (no Uniweb account)
-uniweb publish                    # Publish a foundation to the Uniweb registry
-uniweb register                   # Register a foundation + the data schemas it defines
+
+# Sync a site with the Uniweb backend (git-style; needs `uniweb login`)
+uniweb push                       # Push local content to the backend (creates the site on first push)
+uniweb pull                       # Pull backend content back to local files
+uniweb clone <site-uuid>          # Start a new local project from a site already in the backend
+uniweb status                     # Show what's unpushed / out of sync (local, offline)
+
+# Register a foundation + its data schemas to the Uniweb registry
+uniweb register                   # Register this foundation + the data schemas it defines
+uniweb register --scope @org      # Register under @org (also works from a schemas-only package)
+
+# Project health + maintenance
 uniweb doctor                     # Diagnose project configuration issues (--fix to auto-repair)
-uniweb validate                   # Check your file-based data against your declared schemas (--strict for CI)
-uniweb update                     # Align @uniweb/* deps + this AGENTS.md with the CLI's matrix.
-                                  # Use --dry-run to preview, --yes for non-interactive.
-                                  # `npx uniweb@latest update` pins to the latest release.
+uniweb validate                   # Check file-based data against your declared schemas (--strict for CI)
+uniweb update                     # Align @uniweb/* deps + this AGENTS.md with the CLI's matrix
+                                  # (--dry-run to preview, --yes for non-interactive)
 
 # Help
 uniweb --help                     # Top-level help
 uniweb <command> --help           # Per-command help (no side effects)
 ```
 
-`uniweb deploy` auto-publishes a workspace-local foundation as part of the deploy under a site-scoped slot — no separate `uniweb publish` step needed for site-bound foundations.
+`uniweb publish` brings the site's local foundation along — releasing it to the catalog under your `@org` when its code changed — so a single site needs no separate `uniweb register` step.
 
-**Registering data schemas.** A foundation that defines data schemas (`@/article`, …) uses `uniweb register` to register the foundation together with those schemas in the Uniweb registry — so content authors can create and manage entities of those types. It requires authentication: run `uniweb login`, or supply a bearer token directly with `--token <bearer>` (or the `UNIWEB_TOKEN` env var). Point at a specific registry with `--registry <url>` (or `UNIWEB_REGISTER_URL`). Preview without auth using `--dry-run` (or `-o <file>` to write the submission), and set the publish org with `--scope @org` (default: the foundation's `package.json` `uniweb.scope`).
+**Registering data schemas.** A foundation that defines data schemas (`@/article`, …) uses `uniweb register` to register the foundation together with those schemas in the Uniweb registry — so content authors can create and manage entities of those types. It requires authentication: run `uniweb login`, or supply a bearer token directly with `--token <bearer>` (or the `UNIWEB_TOKEN` env var). Point at a specific registry with `--registry <url>` (or `UNIWEB_REGISTER_URL`). Preview without auth using `--dry-run` (or `-o <file>` to write the submission), and set the org scope with `--scope @org` (default: the foundation's `package.json` `uniweb.scope`).
 
 **Registering standard or shared schemas (no foundation).** Data schemas can also be registered on their own — without a foundation — straight from a schemas package. Run `uniweb register` from a package that *exports* schemas (`@uniweb/schemas`, or any `@org/schemas` you maintain), or from a bare folder of `schemas/*.{yml,json,js}` files: it detects the schemas-only package automatically and submits just the data schemas (no foundation) under `--scope`. This is how the standard schemas are published under `@std`, and how an org publishes its own shared `@org/schemas` once for many foundations to reference. The same flags apply (`--scope`, `--dry-run`, `-o`, `--token`, `--registry`); `--dry-run` (or `-o <file>`) previews the exact submission without authenticating.
 
@@ -192,16 +203,16 @@ The `uniweb` block in `package.json` carries platform-specific configuration tha
 
 | Field | Where used | Default | Purpose |
 |---|---|---|---|
-| `id` | `uniweb publish` | (set via `--name` or scoped `package.json::name`) | The foundation's published id — the bare-name segment in `@org/<id>`. Decoupled from `package.json::name` (a workspace concern), so renaming the foundation on the registry doesn't ripple through site dependencies. Only relevant for catalog-published foundations; site-bound foundations skip this. |
-| `namespace` | `uniweb publish` | (none — see scope resolution) | Legacy explicit org-namespace override. Equivalent to using a scoped `package.json::name` (`"@myorg/foundation"`). Rarely needed in modern foundations. |
+| `id` | `uniweb register` | (the bare segment of a scoped `package.json::name`, or `uniweb.id`) | The foundation's registered id — the bare-name segment in `@org/<id>`. Decoupled from `package.json::name` (a workspace concern), so renaming the foundation on the registry doesn't ripple through site dependencies. |
+| `namespace` | `uniweb register` | (none — see scope resolution) | Legacy explicit org-namespace override. Equivalent to using a scoped `package.json::name` (`"@myorg/foundation"`). Rarely needed in modern foundations. |
 | `runtimePolicy` | `dist/runtime-pin.json` (foundation build) | `"auto-minor"` | Controls how sites using this foundation receive runtime updates. Three values: `"exact"`, `"auto-patch"`, `"auto-minor"`. See "Foundation runtime policy" below. |
 
-**Catalog vs site-bound foundations.** Two distribution intents share the same `dist/foundation.js` artifact:
+**How a foundation reaches the catalog.** Foundations on Uniweb hosting always live in the catalog as `@org/name@version`. Two ways to get one there, both from the same `dist/foundation.js` artifact:
 
-- A **catalog foundation** is a deliberate product — named, versioned, listed in the catalog, consumable by other developers' sites. Use `uniweb publish @org/name` for these. The CLI requires an explicit name argument so you don't accidentally catalog a foundation that was meant to be site-bound.
-- A **site-bound foundation** powers exactly one site. Don't run `uniweb publish` for it. Just run `uniweb deploy` from the site directory — the CLI auto-publishes your local foundation as part of the deploy, **uploaded with the site's other published assets** (per-site storage, never to the catalog). With no naming ceremony, no catalog visibility, and no developer-vs-site ownership confusion. To later promote the foundation to a catalog product, run `uniweb publish @org/name` from the foundation directory and update the site's `site.yml` to a versioned ref (`foundation: '@org/name@1.2.3'`).
+- **Brought along by `uniweb publish`.** When a foundation powers a single site, don't run `uniweb register` yourself. Run `uniweb publish` from the site directory — it releases the site's local foundation to the catalog under your `@org` (when its code changed) and then goes live, in one step. No separate register ceremony.
+- **Registered deliberately with `uniweb register --scope @org`.** When the foundation is a product meant for multiple sites — listed in the catalog, consumable by other developers' sites — register it on its own schedule. Consuming sites then pin a versioned ref (`foundation: '@org/name@1.2.3'`).
 
-**On the split between `package.json::name` and `uniweb.id`:** the workspace name is what pnpm uses for `file:` linking and what `site.yml::foundation` references. The published id is what the registry stores. Keeping them separate means renaming on the registry (e.g. `marketing` → `marketing-pro`) is a one-shot `uniweb publish --name marketing-pro` — it persists to `uniweb.id` without touching the workspace.
+**On the split between `package.json::name` and `uniweb.id`:** the workspace name is what pnpm uses for `file:` linking and what `site.yml::foundation` references. The published id is what the registry stores. Keeping them separate means a workspace rename (e.g. `marketing` → `marketing-pro`) is a one-shot `uniweb rename foundation marketing marketing-pro` — it updates the package, folder, and every dependent site, while the foundation's registered id (`uniweb.id`) stays independent.
 
 These are the only fields the platform consumes today. Future platform features that need static configuration will land here too.
 

package/src/backend/client.js

@@ -28,28 +28,34 @@
  */
 
 import { getRegistryApiBaseUrl } from '../utils/config.js'
-import { ensureRegistryAuth, fetchMe } from '../utils/registry-auth.js'
+import { ensureRegistryAuth, fetchMe, readRegistryAuth, isExpired } from '../utils/registry-auth.js'
 import { fetchOrgs as fetchOrgsImpl, createOrg as createOrgImpl } from '../utils/registry-orgs.js'
 import { uploadFoundationCode } from '../utils/code-upload.js'
 import { uploadSiteAssets } from '../utils/asset-upload.js'
 import { uploadRuntime } from '../utils/runtime-upload.js'
 
 /**
- * Resolve the backend origin: an explicit flag value wins; otherwise defer to
- * the shared origin resolver (env override > saved config > local default). A
- * full URL is reduced to its origin, so callers may pass a whole endpoint URL.
+ * Resolve the backend origin via the resolution ladder (highest precedence
+ * first). A full URL is reduced to its origin, so callers may pass a whole
+ * endpoint URL; an unparseable value falls through to the next tier.
  *
- * One resolver, one place to revisit when we settle the single-origin-input +
- * discovery-handshake decision — kept delegating for now so this stays a pure,
- * behavior-preserving consolidation.
+ *   1. `flag` — the raw --backend / --registry value (this command)
+ *   2. UNIWEB_REGISTER_URL env — session-wide override (CI / local dev)
+ *   3. `siteBackend` — the site's bound backend from deploy.yml (site verbs)
+ *   4–6. the logged-in session origin > ~/.uniweb/config.json > the default
+ *        (uniweb.app) — all via getRegistryApiBaseUrl()
  *
  * @param {string} [flag] - the raw value of --backend / --registry, if supplied
+ * @param {object} [opts]
+ * @param {string} [opts.siteBackend] - a site's deploy.yml-bound backend origin
  * @returns {string} a bare origin with no trailing slash
  */
-export function resolveBackendOrigin(flag) {
-  if (flag) {
-    try { return new URL(flag).origin } catch { /* not a URL — fall through */ }
-  }
+export function resolveBackendOrigin(flag, { siteBackend } = {}) {
+  const norm = (v) => { try { return new URL(v).origin } catch { return null } }
+  if (flag) { const o = norm(flag); if (o) return o }
+  const env = process.env.UNIWEB_REGISTER_URL
+  if (env) { const o = norm(env); if (o) return o }
+  if (siteBackend) { const o = norm(siteBackend); if (o) return o }
   return getRegistryApiBaseUrl()
 }
 
@@ -74,6 +80,7 @@ export class BackendClient {
    * @param {object} [opts]
    * @param {string} [opts.origin] - explicit origin (wins over originFlag/env)
    * @param {string} [opts.originFlag] - raw --backend/--registry value to resolve
+   * @param {string} [opts.siteBackend] - a site's deploy.yml-bound backend (site verbs)
    * @param {string} [opts.token] - explicit bearer (wins over env + stored session)
    * @param {() => Promise<string>} [opts.getToken] - injected bearer resolver (tests, or
    *        callers with their own auth); used when no explicit token/env is present
@@ -81,8 +88,8 @@ export class BackendClient {
    * @param {string} [opts.command] - label for the login prompt ('Pushing', 'Registering', …)
    * @param {typeof fetch} [opts.fetchImpl] - injectable fetch (tests)
    */
-  constructor({ origin, originFlag, token, getToken, args = [], command = 'This command', fetchImpl } = {}) {
-    this.origin = (origin || resolveBackendOrigin(originFlag)).replace(/\/+$/, '')
+  constructor({ origin, originFlag, siteBackend, token, getToken, args = [], command = 'This command', fetchImpl } = {}) {
+    this.origin = (origin || resolveBackendOrigin(originFlag, { siteBackend })).replace(/\/+$/, '')
     this._token = token || process.env.UNIWEB_TOKEN || null
     this._getToken = getToken || null
     this._args = args
@@ -103,6 +110,19 @@ export class BackendClient {
       this._token = await this._getToken()
       return this._token
     }
+    // Origin-mismatch guard: a usable session authed against a DIFFERENT origin
+    // than this command targets means the bearer will be rejected — warn once
+    // and point at the fix (the stored token IS for `stored.origin`, not here).
+    if (!this._warnedOriginMismatch) {
+      this._warnedOriginMismatch = true
+      try {
+        const stored = await readRegistryAuth()
+        if (stored?.token && !isExpired(stored) && stored.origin &&
+            stored.origin.replace(/\/+$/, '') !== this.origin) {
+          console.error(`\x1b[33m⚠\x1b[0m Logged in to ${stored.origin}, but this command targets ${this.origin} — the session may be rejected. Run \`uniweb login --backend ${this.origin}\`, or pass --token.`)
+        }
+      } catch { /* advisory only */ }
+    }
     this._token = await ensureRegistryAuth({ apiBase: this.origin, command: this._command, args: this._args })
     return this._token
   }
@@ -207,6 +227,35 @@ export class BackendClient {
     return res.json()
   }
 
+  /**
+   * GET /dev/registry/{scope}/{name} → the latest registered foundation version
+   * + its content digest, or null on 404 / any failure (callers degrade).
+   *
+   * The bare `{scope}/{name}` path resolves the latest foundation version (the
+   * data-schema sibling is `/dev/registry/data-schemas/{scope}/{name}`). The
+   * backend returns `version` (+ schema ids); we normalize it to `latest_version`
+   * for callers and tolerate either key. `digest` is the framework-computed
+   * fingerprint the backend stores OPAQUE and echoes here (null when the version
+   * carries none) — the freshness signal for publish/status (shipping-model.md
+   * §4.1). A bare/unscoped name → null (only `@org/name` can be looked up).
+   * @param {string} scopedName
+   * @returns {Promise<{ latest_version: string|null, digest: string|null }|null>}
+   */
+  async readFoundationLatest(scopedName) {
+    const m = /^@([^/]+)\/([^@/]+)/.exec(String(scopedName || ''))
+    if (!m) return null
+    try {
+      const res = await this.request(`/dev/registry/${encodeURIComponent(m[1])}/${encodeURIComponent(m[2])}`)
+      if (!res.ok) return null
+      const body = await res.json().catch(() => null)
+      if (!body) return null
+      // The read returns `version`; callers use `latest_version`. Tolerate both.
+      return { ...body, latest_version: body.latest_version ?? body.version ?? null }
+    } catch {
+      return null
+    }
+  }
+
   // ── Orgs ──────────────────────────────────────────────────────────────────────
 
   /** GET /dev/orgs → { account_handle, personal_org_exists, orgs[] }. */
@@ -311,6 +360,47 @@ export class BackendClient {
     return this.request(`/dev/site/unpublish/${encodeURIComponent(uuid)}`, { method: 'POST' })
   }
 
+  /**
+   * GET /dev/site/status/{uuid} → the site's publish lifecycle (Contract 3,
+   * 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}`)
+   * 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.
+   * @param {string} uuid - the site-content uuid
+   * @returns {Promise<object|null>}
+   */
+  async siteStatus(uuid) {
+    try {
+      const res = await this.request(`/dev/site/status/${encodeURIComponent(uuid)}`)
+      return res.ok ? await res.json().catch(() => null) : null
+    } catch {
+      return null
+    }
+  }
+
+  /**
+   * ASSUMED endpoint (not built yet — kb/framework/build/payment-handoff-plan.md).
+   * 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/foundation-bring-along.js

@@ -0,0 +1,229 @@
+/**
+ * Bring-the-foundation-along — the freshness loop `uniweb publish` runs before
+ * it makes a site live (shipping-model.md §4).
+ *
+ * A publish must never ship a site pointing at stale or missing foundation code
+ * (the footgun: a site goes live referencing a version the catalog doesn't
+ * have). So when the site references a LOCAL foundation, publish fingerprints it
+ * and reconciles with the catalog. Three cases (§4):
+ *
+ *   | version not yet registered    | release it, then publish        |
+ *   | registered, code unchanged    | skip the release (digest match) |
+ *   | registered, code CHANGED      | warn / prompt — never silent    |
+ *
+ * The freshness signal is the backend-stored, framework-computed digest (§4.1):
+ * no local state, multi-machine-safe. When the site references a published
+ * registry ref or a URL there's nothing to bring along. When the backend
+ * doesn't expose the stored digest yet, the compare DEGRADES to "ask" (same
+ * posture as `status --remote` on a 404).
+ *
+ * "Release" here is literally `uniweb register` run in the foundation directory
+ * — same build-if-stale → schema submit → code upload → digest the standalone
+ * verb does, so there is exactly one foundation-release path.
+ */
+
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { execFileSync } from 'node:child_process'
+
+import { detectFoundationType } from '@uniweb/build'
+import { computeFoundationDigest } from '../utils/code-upload.js'
+import { readFlagValue } from '../utils/args.js'
+import { isNonInteractive } from '../utils/interactive.js'
+
+/**
+ * Resolve the site's LOCAL foundation — the one publish should bring along — or
+ * null when the site references a published registry ref / URL (the catalog
+ * already has it; nothing to do). Uses the SAME resolver the build uses
+ * (`detectFoundationType`), so "which foundation" never drifts between them.
+ *
+ * @param {string} siteDir
+ * @param {object} siteYml - parsed site.yml
+ * @returns {{ dir: string, scopedName: string|null, version: string|null }|null}
+ */
+export function resolveLocalFoundation(siteDir, siteYml) {
+  const decl = siteYml?.foundation
+  if (!decl) return null
+  let info
+  try {
+    info = detectFoundationType(decl, siteDir)
+  } catch {
+    // Unresolved declaration — the site build will surface the canonical
+    // error; bring-along simply has nothing local to act on.
+    return null
+  }
+  if (!info || info.type !== 'local' || !info.path) return null
+  return {
+    dir: info.path,
+    scopedName: foundationScopedName(info.path),
+    version: readPkgField(info.path, 'version'),
+  }
+}
+
+// The foundation's scoped catalog name (`@org/name`) from its package.json — an
+// already-scoped `name`, else `uniweb.scope` + a bare `name`. Null when neither
+// yields a scoped name (then we can't look up the registered version, so the
+// caller treats the foundation as "release it and let register pick the scope").
+function foundationScopedName(dir) {
+  try {
+    const pkg = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8'))
+    const name = pkg?.name
+    if (typeof name === 'string' && name.startsWith('@')) return name
+    const scope = pkg?.uniweb?.scope
+    if (scope && name) return `${String(scope).replace(/\/+$/, '')}/${name}`
+    return null
+  } catch {
+    return null
+  }
+}
+
+function readPkgField(dir, field) {
+  try {
+    return JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8'))?.[field] || null
+  } catch {
+    return null
+  }
+}
+
+// Forward the origin + auth flags so the spawned `uniweb register` / `build`
+// hits the SAME backend with the SAME session as the publish that called it.
+function forwardedFlags(args) {
+  const out = []
+  for (const name of ['--backend', '--registry', '--token']) {
+    const v = readFlagValue(args, name)
+    if (v) out.push(name, v)
+  }
+  if (isNonInteractive(args)) out.push('--non-interactive')
+  return out
+}
+
+/**
+ * Decide + (maybe) act on the site's local foundation before go-live.
+ *
+ * @param {object} o
+ * @param {import('./client.js').BackendClient} o.client
+ * @param {string} o.siteDir
+ * @param {object} o.siteYml
+ * @param {string[]} o.args
+ * @param {object} o.say - { ok, info, warn, err, dim } reporters
+ * @param {(q: string, def?: boolean) => Promise<boolean>} o.confirm
+ * @param {string} o.cliBin - the CLI entry (process.argv[1]) to re-spawn
+ * @param {boolean} [o.dryRun]
+ * @returns {Promise<{ released: boolean, proceed: boolean, ref: string|null }>}
+ *   proceed:false → the caller should abort the publish (user declined). `ref`
+ *   is the pinned `@scope/name@version` to stamp on the pushed site — read AFTER
+ *   any release, so it reflects the released version + the scope register
+ *   derived. Delivery is version-pinned end-to-end (the gateway serves a
+ *   foundation only by a concrete version, no latest-resolution at serve time —
+ *   collab framework-backend-5c3e), so an unversioned local ref MUST be pinned
+ *   on the wire or the live site points at code the gateway can't serve. null
+ *   when the site already references a registry ref / URL (no override needed)
+ *   or no scoped ref can be formed.
+ */
+export async function bringFoundationAlong({ client, siteDir, siteYml, args, say, confirm, cliBin, dryRun = false }) {
+  const local = resolveLocalFoundation(siteDir, siteYml)
+  if (!local) {
+    // Published registry ref / URL — the catalog (or the URL host) already
+    // serves the code, and site.yml already pins the version. Nothing to bring
+    // along, and no ref override (forward the site.yml ref verbatim).
+    return { released: false, proceed: true, ref: null }
+  }
+
+  const label = local.scopedName || local.version ? `${local.scopedName || 'foundation'}${local.version ? `@${local.version}` : ''}` : 'the local foundation'
+  const skipPrompts = args.includes('--yes') || args.includes('--force') || args.includes('--no-verify')
+
+  // The pinned ref to stamp on the pushed site — read at RETURN time (after any
+  // release), so it reflects the released version + the scope register derived.
+  // null when no scoped ref can be formed (then the site.yml ref is forwarded).
+  const pinnedRef = () => {
+    const s = foundationScopedName(local.dir)
+    const v = readPkgField(local.dir, 'version')
+    return s && v ? `${s}@${v}` : null
+  }
+
+  // Dry-run reports the intent WITHOUT touching the network — it must not force
+  // a login (the digest read is auth-gated). The real run does the compare.
+  if (dryRun) {
+    say.dim(`Foundation  : ${label} — local; would release if changed or not yet registered`)
+    return { released: false, proceed: true, ref: null }
+  }
+
+  // Ask the catalog what it has. Null → not registered (or the backend can't
+  // answer / no scoped name to look up) → release.
+  const reg = local.scopedName ? await client.readFoundationLatest(local.scopedName) : null
+
+  if (!reg) {
+    say.info(`Releasing the foundation ${label} (not yet registered)…`)
+    return { released: releaseFoundation(local, args, cliBin, say), proceed: true, ref: pinnedRef() }
+  }
+
+  // Registered — fingerprint the local build and compare. Build first so the
+  // digest reflects current source (idempotent: a no-op when already fresh).
+  buildFoundation(local, cliBin)
+  const localDigest = computeFoundationDigest(join(local.dir, 'dist'))
+
+  if (reg.digest && localDigest && reg.digest === localDigest) {
+    say.dim(`Foundation  : ${label} — unchanged since release (digest matches); nothing to release.`)
+    return { released: false, proceed: true, ref: pinnedRef() }
+  }
+
+  // A different version locally → a new version to release.
+  if (local.version && local.version !== reg.latest_version) {
+    say.info(`Releasing the foundation ${label} (new version; registered latest is ${reg.latest_version})…`)
+    return { released: releaseFoundation(local, args, cliBin, say), proceed: true, ref: pinnedRef() }
+  }
+
+  // Same version, but the digest differs or the backend can't confirm it.
+  if (!reg.digest) {
+    // Degrade: the backend doesn't return the stored digest yet, so we can't
+    // be sure the registered version matches local. Offer to re-deliver.
+    say.warn(`Can't verify the registered ${label} matches your local copy (backend returned no digest).`)
+    if (skipPrompts || isNonInteractive(args)) {
+      say.dim('Proceeding without re-releasing — pass nothing to re-deliver, or bump the version to publish a change.')
+      return { released: false, proceed: true, ref: pinnedRef() }
+    }
+    const reRelease = await confirm(`Re-release ${label} to be sure its code is current?`, false)
+    if (reRelease) return { released: releaseFoundation(local, args, cliBin, say), proceed: true, ref: pinnedRef() }
+    return { released: false, proceed: true, ref: pinnedRef() }
+  }
+
+  // Case 3 (§4): the foundation was edited but the version wasn't bumped. The
+  // registered version is immutable, so we never silently ship the old code —
+  // the deliberate release gate is a version bump (§3.1).
+  say.warn(`Your local ${label} differs from the registered version ${reg.latest_version}, but the version wasn't bumped.`)
+  say.dim('A registered version is immutable. Bump the foundation\'s version to release the change, then re-run `uniweb publish`.')
+  if (skipPrompts || isNonInteractive(args)) {
+    say.dim(`Proceeding with the already-registered ${reg.latest_version}.`)
+    return { released: false, proceed: true, ref: pinnedRef() }
+  }
+  const proceed = await confirm(`Publish with the already-registered ${reg.latest_version} anyway?`, false)
+  if (!proceed) {
+    say.info('Aborted — bump the foundation version, then re-run `uniweb publish`.')
+    return { released: false, proceed: false, ref: null }
+  }
+  return { released: false, proceed: true, ref: pinnedRef() }
+}
+
+// Build the foundation so its dist/ can be fingerprinted. Idempotent — the
+// foundation build no-ops when already fresh.
+function buildFoundation(local, cliBin) {
+  execFileSync('node', [cliBin, 'build', '--target', 'foundation'], {
+    cwd: local.dir,
+    stdio: 'inherit',
+    env: process.env,
+  })
+}
+
+// Release = `uniweb register` in the foundation directory (the one foundation
+// release path). Returns true on success; throws to the caller on failure so
+// publish stops before going live with missing code.
+function releaseFoundation(local, args, cliBin, say) {
+  console.log('')
+  execFileSync('node', [cliBin, 'register', ...forwardedFlags(args)], {
+    cwd: local.dir,
+    stdio: 'inherit',
+    env: process.env,
+  })
+  console.log('')
+  return true
+}