uniweb 0.12.33 → 0.12.35

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.33",
+  "version": "0.12.35",
   "description": "Create structured Vite + React sites with content/code separation",
   "type": "module",
   "bin": {
@@ -41,14 +41,14 @@
     "js-yaml": "^4.1.0",
     "prompts": "^2.4.2",
     "tar": "^7.0.0",
-    "@uniweb/kit": "0.9.18",
     "@uniweb/core": "0.7.14",
+    "@uniweb/kit": "0.9.18",
     "@uniweb/runtime": "0.8.20"
   },
   "peerDependencies": {
+    "@uniweb/content-reader": "1.1.12",
     "@uniweb/semantic-parser": "1.1.17",
-    "@uniweb/build": "0.14.16",
-    "@uniweb/content-reader": "1.1.12"
+    "@uniweb/build": "0.14.18"
   },
   "peerDependenciesMeta": {
     "@uniweb/build": {

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)
-uniweb deploy --host=<adapter>    # Deploy to a static host: cloudflare-pages, netlify,
+# Ship a site to Uniweb hosting (or a static host)
+uniweb deploy                     # Build + push + publish in one shot (default; needs `uniweb login`)
+uniweb deploy --host=<adapter>    # Deploy to a static host instead: 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)
+uniweb publish                    # Make the synced site's current backend state live —
+                                  # does NOT push; run `uniweb push` first, or just `uniweb deploy`
+
+# 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 deploy` auto-registers a workspace-local foundation as part of the deploy under a site-scoped slot — no separate `uniweb register` step needed for site-bound foundations.
 
-**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. Only relevant for catalog-registered foundations; site-bound foundations skip this. |
+| `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:
 
-- 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'`).
+- A **catalog foundation** is a deliberate product — named, versioned, listed in the catalog, consumable by other developers' sites. Use `uniweb register --scope @org` for these — cataloging is a deliberate, explicitly-scoped step, 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 register` for it. Just run `uniweb deploy` from the site directory — the CLI auto-registers your local foundation as part of the deploy, **uploaded with the site's other 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 register --scope @org` from the foundation directory and update the site's `site.yml` to 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.
 
@@ -1762,6 +1773,8 @@ export default {
 
 The content handler receives `block.parsedContent.data` and reads raw ProseMirror from `block.rawContent`. It returns a new ProseMirror document — the framework re-parses it through the semantic parser. Returning `null` or the same reference as `block.rawContent` signals no change.
 
+> **`instantiateContent` resolves `{placeholders}` in text nodes only** — not in link `href`s or other node/mark attributes. So `[{email}](mailto:{email})` fills the visible label but leaves the `mailto:` URL literal. For dynamic URLs, emit the value as plain text and let the component linkify it, or build the href in the handler yourself.
+
 ### Reserved frontmatter fields
 
 `source` and `where` are convention-level reserved fields — they flow through to both `block.properties` (for handler access) and `params` (visible to components). Components can ignore them. This is consistent with how `background` and `theme` work. List them in `meta.js` params with descriptions so the editor and schema recognize them.

package/src/backend/client.js

@@ -207,6 +207,25 @@ export class BackendClient {
     return res.json()
   }
 
+  /**
+   * ASSUMED endpoint (not built yet — kb/framework/plans/shipping-verbs-and-freshness.md §6.5).
+   * GET /dev/registry/foundation/{scope}/{name} → { latest_version } for a foundation's
+   * latest registered version, or null on 404 / any failure (callers degrade gracefully).
+   * A bare/unscoped name → null (only `@org/name` can be looked up).
+   * @param {string} scopedName
+   * @returns {Promise<{ latest_version: string }|null>}
+   */
+  async readFoundationLatest(scopedName) {
+    const m = /^@([^/]+)\/([^@/]+)/.exec(String(scopedName || ''))
+    if (!m) return null
+    try {
+      const res = await this.request(`/dev/registry/foundation/${encodeURIComponent(m[1])}/${encodeURIComponent(m[2])}`)
+      return res.ok ? await res.json().catch(() => null) : null
+    } catch {
+      return null
+    }
+  }
+
   // ── Orgs ──────────────────────────────────────────────────────────────────────
 
   /** GET /dev/orgs → { account_handle, personal_org_exists, orgs[] }. */
@@ -311,6 +330,23 @@ export class BackendClient {
     return this.request(`/dev/site/unpublish/${encodeURIComponent(uuid)}`, { method: 'POST' })
   }
 
+  /**
+   * ASSUMED endpoint (not built yet — kb/framework/plans/shipping-verbs-and-freshness.md §6.5).
+   * GET /dev/site/{uuid}/status → the site's publish lifecycle:
+   *   { published: boolean, last_pushed_at?: string, last_published_at?: string, draft_dirty?: boolean }
+   * `draft_dirty` = the synced draft differs from what's currently live. null on 404 / any failure.
+   * @param {string} uuid - the site-content uuid
+   * @returns {Promise<object|null>}
+   */
+  async siteStatus(uuid) {
+    try {
+      const res = await this.request(`/dev/site/${encodeURIComponent(uuid)}/status`)
+      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/data-bundle.js

@@ -0,0 +1,43 @@
+/**
+ * Upload the static-data ball (assembleDataBall's `{ data, search }` doc) to the
+ * backend's content-addressed asset store via the SAME asset lane deploy uses for
+ * media, and return its durable serve URL — the `info.data_bundle` the composite push
+ * stamps on the site-content entity. The backend unwraps the ball into the `/data/*`
+ * + `/_search/*` bytes the gateway serves.
+ *
+ * The ball is in-memory (not a built file on disk), so it rides as `bytes` on the
+ * single upload entry — `uploadSiteAssets` PUTs `bytes` when present, else reads a
+ * `diskPath` (its media path). Content-addressed like every asset: identical ball →
+ * same id → a re-deploy of unchanged data is a cheap no-op PUT.
+ */
+
+import { createHash } from 'node:crypto'
+import { buildAssetUrl } from '../utils/asset-upload.js'
+
+/**
+ * @param {object} client - BackendClient (origin + uploadSiteAssets + discover)
+ * @param {{ data: object, search: object }} ball - the assembled data ball
+ * @param {{ onProgress?: (m: string) => void }} [opts]
+ * @returns {Promise<string>} the content-addressed serve URL (→ `info.data_bundle`)
+ */
+export async function uploadDataBundle(client, ball, { onProgress } = {}) {
+  const bytes = Buffer.from(JSON.stringify(ball))
+  const sha256 = createHash('sha256').update(bytes).digest('hex')
+  const localUrl = '/data-bundle/base.json' // bookkeeping key into assetsByLocalUrl
+
+  const result = await client.uploadSiteAssets({
+    files: [
+      { path: 'data-bundle/base.json', content_type: 'application/json', size: bytes.length, sha256, localUrl, bytes },
+    ],
+    onProgress,
+  })
+  if (result.failed?.length) {
+    const f = result.failed[0]
+    throw new Error(`data-bundle upload failed: HTTP ${f.status} ${f.detail}`)
+  }
+  const entry = result.assetsByLocalUrl[localUrl]
+  if (!entry) throw new Error('data-bundle upload returned no asset id')
+
+  const config = await client.discover()
+  return buildAssetUrl(client.origin, config.assetBase, entry.id, entry.ext)
+}

package/src/backend/site-media.js

@@ -0,0 +1,61 @@
+/**
+ * Upload a site's local media to the backend's content-addressed asset store via the
+ * SAME asset lane the data bundle rides, and return a `{ ref → serveUrl }` map for the
+ * deploy's second emit (`assetRewrite`) to swap the entity content refs for.
+ *
+ * Input is the site-root asset refs the producer surfaced in
+ * `emitSyncPackages().localAssets` (`/images/hero.png`); `resolveAssetPath` finds the
+ * file under the site's `public/` (or `assets/`). A ref whose file is missing is
+ * skipped (warned), never a broken serve URL. The serve URL is the backend's canonical
+ * `serve_url` when present, else reconstructed from `id`+`assetBase` (the dev fallback).
+ * Content-addressed like every asset: identical bytes → same id → a re-deploy of
+ * unchanged media is a cheap no-op PUT (the lane's `present` skip-list).
+ */
+
+import { createHash } from 'node:crypto'
+import { existsSync, readFileSync } from 'node:fs'
+import { basename } from 'node:path'
+import { resolveAssetPath } from '@uniweb/build/site'
+import { buildAssetUrl } from '../utils/asset-upload.js'
+import { contentTypeFor } from '../utils/code-upload.js'
+
+/**
+ * @param {object} client - BackendClient (origin + uploadSiteAssets + discover)
+ * @param {string} siteDir - the site root (site-root refs resolve under public/)
+ * @param {string[]} refs - site-root local asset refs (`/images/x.png`)
+ * @param {{ onProgress?: (m: string) => void, warn?: (m: string) => void }} [opts]
+ * @returns {Promise<Record<string,string>>} ref → serve URL (only resolved + uploaded refs)
+ */
+export async function uploadSiteMedia(client, siteDir, refs, { onProgress, warn } = {}) {
+  if (!refs?.length) return {}
+
+  const files = []
+  for (const ref of refs) {
+    const { resolved } = resolveAssetPath(ref, siteDir, siteDir)
+    if (!resolved || !existsSync(resolved)) {
+      warn?.(`local-media: ${ref} not found under the site (skipped)`)
+      continue
+    }
+    const bytes = readFileSync(resolved)
+    files.push({
+      path: ref.replace(/^\/+/, ''), // bookkeeping key into the plan (must be unique)
+      content_type: contentTypeFor(basename(resolved)),
+      size: bytes.length,
+      sha256: createHash('sha256').update(bytes).digest('hex'),
+      localUrl: ref, // the rewrite key — the original content ref
+      diskPath: resolved,
+    })
+  }
+  if (!files.length) return {}
+
+  const result = await client.uploadSiteAssets({ files, onProgress })
+  for (const f of result.failed || []) warn?.(`local-media: upload failed for ${f.path} (HTTP ${f.status})`)
+
+  const config = await client.discover()
+  const map = {}
+  for (const ref of refs) {
+    const entry = result.assetsByLocalUrl[ref]
+    if (entry) map[ref] = entry.serveUrl || buildAssetUrl(client.origin, config.assetBase, entry.id, entry.ext)
+  }
+  return map
+}

package/src/backend/site-sync.js

@@ -0,0 +1,267 @@
+/**
+ * site-sync — the reusable core of `uniweb push`: given a site's emitted sync
+ * packages, submit them over the two directional lanes (site-content first, then the
+ * folder keyed by the site's uuid), back-fill the minted uuids into the source files,
+ * and persist the send-only-changed cache. Extracted from the push command so
+ * `uniweb deploy` (the composite path) reuses the exact same lane submission.
+ *
+ * The command keeps flag parsing, the emit, and the `-o`/`--dry-run` preview;
+ * everything from "the packages are built, now POST them" lives here. Logging is
+ * injected via `report` ({ info, note, error, dim }) so each caller styles output its
+ * own way.
+ */
+
+import { writeFileSync, readFileSync, mkdirSync } from 'node:fs'
+import { join, dirname } from 'node:path'
+import { backfillEntityUuids, writeSiteEntityUuid, emitSyncPackages } from '@uniweb/build/uwx'
+
+// Pull the finalized entities out of the restore response. The backend returns
+// `{ report: { finalized: [ { index, uuid, changed, document }, … ] } }` — each entry
+// carries its position in the SUBMITTED sequence (`index`, the correlation key — `$id`
+// is not echoed), the minted entity `uuid`, a `changed` flag, and the full `document`
+// (verbatim stored content with every `$uuid` filled in). A couple of shapes are
+// tolerated; only entries with a valid `index` + `uuid` are usable.
+export function extractFinalized(payload) {
+  const list = Array.isArray(payload?.report?.finalized)
+    ? payload.report.finalized
+    : Array.isArray(payload?.finalized)
+      ? payload.finalized
+      : Array.isArray(payload)
+        ? payload
+        : null
+  if (!list) return null
+  return list
+    .map((d) => ({
+      index: d?.index,
+      uuid: d?.uuid ?? d?.document?.$uuid ?? null,
+      changed: d?.changed,
+      document: d?.document ?? null,
+    }))
+    .filter((e) => Number.isInteger(e.index) && e.uuid)
+}
+
+// Pull the minted site-content uuid out of a CREATE response. The exact shape is an
+// open backend item, so the extractor is deliberately tolerant of a bare
+// `{ siteContentUuid }` / `{ $uuid }` / `{ uuid }`, or the same `report.finalized[]`
+// envelope the update/folder lanes return (the site entity is submitted alone, so its
+// minted uuid is the first finalized entry). Returns null if none is present.
+export function extractMintedSiteUuid(payload) {
+  if (typeof payload?.siteContentUuid === 'string') return payload.siteContentUuid
+  if (typeof payload?.$uuid === 'string') return payload.$uuid
+  if (typeof payload?.uuid === 'string') return payload.uuid
+  const finalized = extractFinalized(payload)
+  if (finalized && finalized.length) {
+    const site = finalized.find((f) => f.index === 0) || finalized[0]
+    return site?.uuid ?? null
+  }
+  return null
+}
+
+// One-line summary from the authoritative per-entity `changed` flag (`false` = a true
+// no-op). Falls back silently when the backend omits it.
+function changedSummary(finalized) {
+  const changed = finalized.filter((f) => f.changed === true).length
+  const unchanged = finalized.filter((f) => f.changed === false).length
+  const parts = []
+  if (changed) parts.push(`${changed} changed`)
+  if (unchanged) parts.push(`${unchanged} unchanged`)
+  return parts.length ? parts.join(', ') : null
+}
+
+// Resolve a Model NOT defined by the local foundation by reading its declaration (the
+// `@uniweb/data-schema` form) from the backend via the client. Cached per run; HTTP
+// 404 → null (the emitter then says "register it first"). The bearer is acquired lazily
+// by the client, so a fully-local sync never authenticates.
+//
+// `offline` (set for `-o` / `--dry-run`) forces every non-local Model to null WITHOUT
+// touching the backend — an offline emit must never authenticate.
+export function makeModelResolver({ client, offline = false }) {
+  const cache = new Map()
+  return async (modelName) => {
+    if (cache.has(modelName)) return cache.get(modelName)
+    const decl = offline ? null : await client.readDataSchema(modelName)
+    cache.set(modelName, decl)
+    return decl
+  }
+}
+
+// "Send only changed" cache: content hashes from the last successful sync, keyed
+// `<model> <id>`. Gitignored, per-clone, deletable (a deleted cache just means one full
+// re-sync, which the backend then no-ops). NOT identity — the minted `$uuid` lives in
+// the source files; this is a pure wire-efficiency cache.
+function syncCachePath(siteDir) {
+  return join(siteDir, '.uniweb', 'sync-cache.json')
+}
+export function readSyncCache(siteDir) {
+  try {
+    const obj = JSON.parse(readFileSync(syncCachePath(siteDir), 'utf8'))
+    return obj && typeof obj.hashes === 'object' && obj.hashes ? obj.hashes : {}
+  } catch {
+    return {} // missing / unreadable → treat everything as changed
+  }
+}
+export function writeSyncCache(siteDir, hashes) {
+  const p = syncCachePath(siteDir)
+  mkdirSync(dirname(p), { recursive: true })
+  writeFileSync(p, JSON.stringify({ version: 1, hashes }, null, 2) + '\n')
+}
+
+/**
+ * Offline-probe how many of a site's entities differ from the last successful push.
+ * Runs the SAME emit + send-only-changed diff `uniweb push` runs, but with an
+ * OFFLINE Model resolver — no auth, no submit, no backend round-trip. Used by
+ * `uniweb status` and the `uniweb publish` pre-flight. Throws if the producer
+ * can't build the sync packages (e.g. an unresolved data Model); callers report it.
+ *
+ * @param {string} siteDir
+ * @returns {Promise<{ changed: number, unchanged: number, warnings: string[] }>}
+ */
+export async function probeUnpushed(siteDir, { sendAll = false } = {}) {
+  const priorHashes = readSyncCache(siteDir)
+  const pkg = await emitSyncPackages(siteDir, {
+    resolveModel: makeModelResolver({ client: null, offline: true }),
+    priorHashes,
+    sendAll,
+  })
+  const changed = (pkg.siteContent?.entityCount || 0) + (pkg.collections?.entityCount || 0)
+  return { changed, unchanged: pkg.skipped || 0, warnings: pkg.warnings || [] }
+}
+
+/**
+ * Submit a site's emitted sync packages over both directional lanes, back-fill the
+ * minted uuids, and persist the send-only-changed cache. The HTTP + file-write-back
+ * half that `emitSyncPackages` (producer-pure) deliberately omits.
+ *
+ * @param {object} params
+ * @param {object} params.client - BackendClient (carries the origin + the lane methods)
+ * @param {string} params.siteDir - the site root (for $uuid write-back + the cache)
+ * @param {object} params.pkg - the `emitSyncPackages` result
+ *        ({ siteContent, collections, siteContentUuid, hashes })
+ * @param {string|null} [params.asOrg] - act-as org (membership-gated), forwarded to each lane
+ * @param {{info,note,error,dim?:Function}} params.report - injected logging
+ * @returns {Promise<{ exitCode: number, boundSiteUuid?: string, finalizedTotal: number, wrote: string[] }>}
+ *   exitCode 1 on any lane failure (already reported, cache NOT persisted); 0 on success.
+ */
+export async function pushSyncPackages({ client, siteDir, pkg, asOrg, report }) {
+  const { siteContent, collections, siteContentUuid, hashes } = pkg
+  const { info, note, error } = report
+  const dim = report.dim || ((s) => s)
+
+  const wrote = []
+  let finalizedTotal = 0
+
+  // POST one lane via the client and parse the JSON response. `doRequest` is a thunk
+  // returning the client's Response promise (so the "Pushing …" line prints before the
+  // request fires). The client carries `collision=force` (last-push-wins) + the optional
+  // `--as-org`. Returns the parsed payload, or null on any transport/HTTP/parse failure
+  // (already reported).
+  const postLane = async (label, doRequest) => {
+    info(`Pushing ${label} to ${dim(client.origin)} …`)
+    let res
+    try {
+      res = await doRequest()
+    } catch (err) {
+      error(`Could not reach the backend at ${client.origin}: ${err.message}`)
+      note('Set the origin with --registry <url> or UNIWEB_REGISTER_URL.')
+      return null
+    }
+    if (!res.ok) {
+      error(`${label} push rejected: HTTP ${res.status} ${res.statusText}`)
+      if (res.status === 401 || res.status === 403) {
+        note("Credentials weren't accepted — supply a bearer with --token <bearer> (or UNIWEB_TOKEN).")
+      } 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).
+        note(
+          "This site's collection structure is already established on the backend and can't be changed " +
+            'in place — e.g. adding or removing a schema-backed collection, or switching one between ' +
+            'static (data-bundle) and schema-backed delivery. To change it: delete the deployed site and ' +
+            'redeploy, or clear `$uuid` in site.yml to deploy a fresh one.'
+        )
+      }
+      const body = await res.text().catch(() => '')
+      if (body) note(body.slice(0, 800))
+      return null
+    }
+    try {
+      return await res.json()
+    } catch (err) {
+      error(`Could not parse the ${label} response as JSON: ${err.message}`)
+      return null
+    }
+  }
+
+  // POST a lane that round-trips entity uuids (content UPDATE + the folder): parse the
+  // finalized list (for record back-fill + the changed summary). Returns the finalized
+  // array, or null on failure (already reported).
+  const pushLane = async (label, doRequest) => {
+    const payload = await postLane(label, doRequest)
+    if (payload === null) return null
+    const finalized = extractFinalized(payload)
+    if (!finalized) {
+      error(`The ${label} response carried no recognizable finalized list (expected report.finalized[] with index + uuid).`)
+      note(JSON.stringify(payload).slice(0, 800))
+      return null
+    }
+    const summary = changedSummary(finalized)
+    if (summary) note(`${label}: ${summary}`)
+    return finalized
+  }
+
+  // Lane 1 — site-content (the site is born here; it must exist before its folder). A
+  // known site uuid → UPDATE by uuid; none → CREATE (the backend mints + adopts the site
+  // and returns its uuid, which we record into site.yml). `boundSiteUuid` carries the
+  // minted/known uuid forward to key the folder push.
+  let boundSiteUuid = siteContentUuid
+  if (siteContent) {
+    if (siteContentUuid) {
+      const finalized = await pushLane(
+        'site-content',
+        () => client.updateSiteContent(siteContentUuid, siteContent.buffer, { asOrg })
+      )
+      if (!finalized) return { exitCode: 1, finalizedTotal, wrote }
+      finalizedTotal += finalized.length
+    } else {
+      const payload = await postLane(
+        'site-content',
+        () => client.createSiteContent(siteContent.buffer, { asOrg })
+      )
+      if (payload === null) return { exitCode: 1, finalizedTotal, wrote }
+      const minted = extractMintedSiteUuid(payload)
+      if (!minted) {
+        error('The create response carried no minted site-content uuid — cannot record the site identity or push its folder.')
+        note(JSON.stringify(payload).slice(0, 800))
+        return { exitCode: 1, finalizedTotal, wrote }
+      }
+      writeSiteEntityUuid(siteDir, minted)
+      boundSiteUuid = minted
+      wrote.push('recorded site $uuid in site.yml')
+      finalizedTotal += extractFinalized(payload)?.length ?? 1
+    }
+  }
+
+  // Lane 2 — collections (the @uniweb/folder + the records it references), keyed by the
+  // site-content uuid. On a brand-new site the backend creates the folder on this first
+  // push. Records round-trip their own $uuid (back-filled into source files); the folder
+  // itself has no uuid (the backend owns it).
+  if (collections) {
+    if (!boundSiteUuid) {
+      error('Cannot push collections — the site has no uuid yet. Push the site-content lane first.')
+      return { exitCode: 1, finalizedTotal, wrote }
+    }
+    const finalized = await pushLane(
+      'collections',
+      () => client.pushFolder(boundSiteUuid, collections.buffer, { asOrg })
+    )
+    if (!finalized) return { exitCode: 1, finalizedTotal, wrote }
+    const bf = backfillEntityUuids({ index: collections.index, finalized })
+    for (const w of bf.warnings) note(`! ${w}`)
+    for (const d of bf.deferred) note(`↷ ${d.id ?? `#${d.index}`}: ${d.reason}`)
+    if (bf.updated.length) wrote.push(`wrote ${bf.updated.length} record file(s)`)
+    finalizedTotal += finalized.length
+  }
+
+  // Persist the full content-hash map so the next push skips unchanged entities.
+  writeSyncCache(siteDir, hashes)
+  return { exitCode: 0, boundSiteUuid, finalizedTotal, wrote }
+}