uniweb 0.12.34 → 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.34",
+  "version": "0.12.35",
   "description": "Create structured Vite + React sites with content/code separation",
   "type": "module",
   "bin": {
@@ -46,9 +46,9 @@
     "@uniweb/runtime": "0.8.20"
   },
   "peerDependencies": {
-    "@uniweb/build": "0.14.17",
     "@uniweb/content-reader": "1.1.12",
-    "@uniweb/semantic-parser": "1.1.17"
+    "@uniweb/semantic-parser": "1.1.17",
+    "@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.
 

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/site-sync.js

@@ -13,7 +13,7 @@
 
 import { writeFileSync, readFileSync, mkdirSync } from 'node:fs'
 import { join, dirname } from 'node:path'
-import { backfillEntityUuids, writeSiteEntityUuid } from '@uniweb/build/uwx'
+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
@@ -106,6 +106,27 @@ export function writeSyncCache(siteDir, hashes) {
   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

package/src/commands/publish.js

@@ -33,9 +33,13 @@ import { readFile } from 'node:fs/promises'
 import { join } from 'node:path'
 import yaml from 'js-yaml'
 
+import { createInterface } from 'node:readline/promises'
+
 import { BackendClient } from '../backend/client.js'
 import { resolveSiteDir } from './deploy.js'
 import { readFlagValue } from '../utils/args.js'
+import { isNonInteractive } from '../utils/interactive.js'
+import { probeUnpushed } from '../backend/site-sync.js'
 
 const c = {
   reset: '\x1b[0m', bold: '\x1b[1m', dim: '\x1b[2m',
@@ -49,6 +53,18 @@ const say = {
   dim: (m) => console.log(`  ${c.dim}${m}${c.reset}`),
 }
 
+// Minimal yes/no prompt. Returns `defaultYes` on an empty answer.
+async function confirm(question, defaultYes = false) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout })
+  try {
+    const a = (await rl.question(`${question} ${defaultYes ? '[Y/n]' : '[y/N]'} `)).trim().toLowerCase()
+    if (!a) return defaultYes
+    return a === 'y' || a === 'yes'
+  } finally {
+    rl.close()
+  }
+}
+
 // Highest installed runtime from the backend's /dev/config list (numeric-aware
 // sort). Mirrors deploy.js's resolver. Null when the list is empty.
 function pickHighestRuntime(installed) {
@@ -76,6 +92,7 @@ function extractLanguages(siteYml) {
 
 export async function publish(args = []) {
   const dryRun = args.includes('--dry-run')
+  const skipVerify = args.includes('--yes') || args.includes('--force') || args.includes('--no-verify')
   const siteDir = await resolveSiteDir(args, 'publish')
 
   // The site-content uuid lives in site.yml::$uuid (written by `uniweb push`).
@@ -134,6 +151,27 @@ export async function publish(args = []) {
     return { exitCode: 0 }
   }
 
+  // Pre-flight: `publish` makes the BACKEND's current state live — NOT your local
+  // files. If local content differs from the last push, surface it. Interactive
+  // only; --yes / --force / --no-verify skip it, and a build error never blocks.
+  if (!skipVerify && !isNonInteractive(args)) {
+    let probe = null
+    try {
+      probe = await probeUnpushed(siteDir)
+    } catch {
+      probe = null
+    }
+    if (probe && probe.changed > 0) {
+      say.warn(`You have ${probe.changed} unpushed local content change${probe.changed === 1 ? '' : 's'}.`)
+      say.dim('`publish` makes the backend state live as-is; local edits are not included. Push first, or `uniweb deploy` to do both.')
+      const proceed = await confirm('Publish the current backend state anyway?', true)
+      if (!proceed) {
+        say.info('Aborted — run `uniweb push`, then `uniweb publish`.')
+        return { exitCode: 0 }
+      }
+    }
+  }
+
   say.info(`Publishing the synced site to ${c.dim}${client.origin}${c.reset} …`)
   say.dim('Publishes the CURRENT backend state (incl. app-side edits) — run `uniweb push` first to include local edits.')
   let res

package/src/commands/rename.js

@@ -30,9 +30,11 @@
  * (target name already taken, target not found, folder collision,
  * type mismatch) we bail with a clear message and no partial state.
  *
- * Out of scope: registry side. The publish id (package.json::uniweb.id)
- * is independent of the workspace name and stays untouched. Users who
- * want to also rename on the registry run `uniweb publish --name <new>`.
+ * Out of scope: registry side. The registered id (the scoped
+ * `package.json::name` / `uniweb.id`) is independent of the workspace name and
+ * stays untouched. There is no registry-rename flag — a registered version is
+ * immutable; to change a foundation's registered identity, register it under
+ * the new name (consuming sites repoint their `foundation:` ref).
  *
  * Usage:
  *   uniweb rename foundation <old> <new>

package/src/commands/status.js

@@ -0,0 +1,174 @@
+/**
+ * uniweb status — show how a site's local files compare to the Uniweb backend:
+ * its sync identity, unpushed content changes, and the foundation it references.
+ *
+ * LOCAL + OFFLINE by default: it builds the sync packages with an OFFLINE Model
+ * resolver and diffs them against the send-only-changed cache (the same diff
+ * `uniweb push` runs) — no auth, no backend round-trip.
+ *
+ * `--remote` adds the backend signals (may prompt for login, like `git fetch`):
+ *   - whether the synced draft differs from what's live (publish needed), and
+ *   - whether a newer foundation version is registered than the site pins.
+ * Those use ASSUMED endpoints (see kb shipping-verbs-and-freshness.md §6.5); until
+ * the backend exposes them, `--remote` degrades silently to the local view.
+ *
+ * Usage:
+ *   uniweb status            Sync identity + unpushed content + foundation ref (local)
+ *   uniweb status --remote   Also: draft-vs-live + a newer-registered-foundation check
+ *   uniweb status --json     One JSON line (adds a `remote` object under --remote)
+ *
+ * Run from a site, or a workspace with one site.
+ */
+
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import yaml from 'js-yaml'
+
+import { resolveSiteDir } from './deploy.js'
+import { probeUnpushed } from '../backend/site-sync.js'
+import { BackendClient } from '../backend/client.js'
+import { readFlagValue } from '../utils/args.js'
+
+const c = {
+  reset: '\x1b[0m', bold: '\x1b[1m', dim: '\x1b[2m',
+  cyan: '\x1b[36m', green: '\x1b[32m', yellow: '\x1b[33m',
+}
+const say = {
+  ok: (m) => console.log(`${c.green}✓${c.reset} ${m}`),
+  info: (m) => console.log(`${c.cyan}→${c.reset} ${m}`),
+  warn: (m) => console.log(`${c.yellow}⚠${c.reset} ${m}`),
+  dim: (m) => console.log(`  ${c.dim}${m}${c.reset}`),
+}
+
+function readSiteYml(siteDir) {
+  const p = join(siteDir, 'site.yml')
+  if (!existsSync(p)) return {}
+  try {
+    return yaml.load(readFileSync(p, 'utf8')) || {}
+  } catch {
+    return {}
+  }
+}
+
+function foundationRef(siteYml) {
+  const f = siteYml.foundation
+  if (!f) return null
+  return typeof f === 'string' ? f : f.ref || null
+}
+
+// A versioned registry ref `@org/name@1.2.3` → its scoped name `@org/name` and
+// pinned version `1.2.3`. A bare/local/unversioned ref → nulls.
+function splitFoundationRef(fnd) {
+  if (!fnd || fnd[0] !== '@') return { scope: null, version: null }
+  const at = fnd.lastIndexOf('@')
+  return at > 0 ? { scope: fnd.slice(0, at), version: fnd.slice(at + 1) } : { scope: null, version: null }
+}
+
+export async function status(args = []) {
+  const jsonMode = args.includes('--json')
+  const remote = args.includes('--remote')
+  const siteDir = await resolveSiteDir(args, 'status')
+  const siteYml = readSiteYml(siteDir)
+  const uuid = siteYml.$uuid || null
+  const fnd = foundationRef(siteYml)
+  const { scope: fndScope, version: fndVersion } = splitFoundationRef(fnd)
+
+  // Local content diff — builds the sync packages, never authenticates.
+  let probe = null
+  let probeErr = null
+  try {
+    probe = await probeUnpushed(siteDir)
+  } catch (err) {
+    probeErr = err.message
+  }
+
+  // Remote signals — opt-in (`--remote`). May prompt for login. Degrades to null
+  // on 404 / any failure, so a backend without the endpoints just shows local.
+  let site = null
+  let fdnLatest = null
+  if (remote) {
+    try {
+      const client = new BackendClient({
+        originFlag: readFlagValue(args, '--backend') || readFlagValue(args, '--registry'),
+        token: readFlagValue(args, '--token') || undefined,
+        args,
+        command: 'Status',
+      })
+      if (uuid) site = await client.siteStatus(uuid)
+      if (fndScope) fdnLatest = await client.readFoundationLatest(fndScope)
+    } catch {
+      // degrade silently
+    }
+  }
+
+  if (jsonMode) {
+    console.log(
+      JSON.stringify({
+        synced: Boolean(uuid),
+        uuid,
+        foundation: fnd,
+        changed: probe ? probe.changed : null,
+        unchanged: probe ? probe.unchanged : null,
+        ...(probeErr ? { error: probeErr } : {}),
+        ...(remote ? { remote: { site, foundation_latest: fdnLatest?.latest_version ?? null } } : {}),
+      })
+    )
+    return { exitCode: 0 }
+  }
+
+  console.log('')
+
+  // Sync identity
+  if (uuid) {
+    say.ok(`Synced — site-content ${c.bold}${uuid}${c.reset}`)
+  } else {
+    say.warn('Not synced — this site has never been pushed to a backend.')
+    say.dim('Run `uniweb push` to create it, or `uniweb deploy` to ship it in one step.')
+  }
+
+  // Content
+  if (probeErr) {
+    say.warn(`Couldn't compute content changes: ${probeErr}`)
+    say.dim('A build error or an unresolved data Model can block the offline diff.')
+  } else if (!uuid) {
+    const n = probe.changed
+    say.info(`${n} content ${n === 1 ? 'entity' : 'entities'} ready to push.`)
+  } else if (probe.changed === 0) {
+    say.ok('Content is in sync with the last push.')
+  } else {
+    const n = probe.changed
+    say.info(
+      `${c.bold}${n}${c.reset} content ${n === 1 ? 'entity' : 'entities'} not pushed` +
+        (probe.unchanged ? ` (${probe.unchanged} unchanged)` : '') +
+        '.'
+    )
+    say.dim('Run `uniweb push` to sync, then `uniweb publish` to go live (or `uniweb deploy` for both).')
+  }
+
+  // Foundation
+  if (fnd) say.dim(`Foundation: ${fnd}`)
+
+  // Remote signals
+  if (remote) {
+    if (site) {
+      if (site.draft_dirty) {
+        say.info('Synced draft has changes not yet live — run `uniweb publish` to go live.')
+      } else if (site.published) {
+        say.ok('Live with the latest synced content.')
+      } else {
+        say.info('Synced but not published yet — run `uniweb publish` to go live.')
+      }
+    }
+    if (fdnLatest?.latest_version && fndVersion && fdnLatest.latest_version !== fndVersion) {
+      say.info(`A newer foundation version (${fdnLatest.latest_version}) is registered than the site pins (${fndVersion}).`)
+    }
+    if (!site && !fdnLatest) {
+      say.dim('(No remote signals — the backend may not expose them yet.)')
+    }
+  }
+
+  console.log('')
+  return { exitCode: 0 }
+}
+
+export default status

package/src/framework-index.json

@@ -1,9 +1,9 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-06-23T17:13:47.118Z",
+  "generatedAt": "2026-06-24T03:15:27.555Z",
   "packages": {
     "@uniweb/build": {
-      "version": "0.14.17",
+      "version": "0.14.18",
       "path": "framework/build",
       "deps": [
         "@uniweb/content-reader",
@@ -99,7 +99,7 @@
       "deps": []
     },
     "@uniweb/unipress": {
-      "version": "0.4.23",
+      "version": "0.4.24",
       "path": "framework/unipress",
       "deps": [
         "@uniweb/build",

package/src/index.js

@@ -627,6 +627,13 @@ async function main() {
     process.exit(result?.exitCode ?? 0)
   }
 
+  // Handle status command (dynamic import — offline emit via @uniweb/build)
+  if (command === 'status') {
+    const { status } = await importProjectCommand('./commands/status.js')
+    const result = await status(args.slice(1))
+    process.exit(result?.exitCode ?? 0)
+  }
+
   // Handle clone command (global — bootstraps a new project from a backend site;
   // STANDALONE, so a global `uniweb clone` runs here instead of delegating to a
   // project-local CLI that doesn't exist yet. clone.js avoids any static
@@ -1470,6 +1477,7 @@ ${colors.bright}Commands:${colors.reset}
   runtime register   Register an @uniweb/runtime version to the backend (@std only)
   push               Push a site's content to the backend
   pull               Pull a site's content from the backend
+  status             Show a site's sync state (unpushed content, foundation)
   inspect <path>     Inspect parsed content shape of a markdown file or folder
   docs               Generate component documentation
   doctor             Diagnose project configuration issues