uniweb 0.12.21 → 0.12.22

package/README.md

@@ -361,6 +361,35 @@ Both paths use the same framework. The difference is who edits content, where it
 
 ---
 
+## Keeping a Project in Sync
+
+Uniweb projects pin to specific `@uniweb/*` versions in their `package.json` files and ship an `AGENTS.md` stamped with the CLI version that wrote it. As the framework releases, both can drift from what the CLI you're running expects.
+
+Two paired verbs cover the drift:
+
+- **`uniweb doctor`** — diagnoses only. Flags `@uniweb/*` / `uniweb` declarations that lag the running CLI, plus `AGENTS.md` staleness, plus a small set of safely auto-fixable structural issues.
+- **`uniweb update`** — the mutator. Rewrites `@uniweb/*` + `uniweb` version keys in every workspace `package.json` to the CLI's bundled matrix (deps that are *ahead* are left alone — never downgraded), runs your workspace's package manager, and refreshes `AGENTS.md`. Each file's existing indentation is preserved.
+
+```bash
+npx uniweb@latest update          # canonical: pin to the latest release (no install)
+npx uniweb@latest update --yes    # same, non-interactive (CI, agents, automation)
+uniweb update --dry-run           # preview the plan without touching files
+```
+
+`update` aligns your project to *the CLI that's running it*. `npx uniweb@latest update` is the "pin to the newest release" path. A project-local copy (`node_modules/.bin/uniweb`) deliberately pins to your committed `uniweb` version — bump it in `package.json` and re-install, or use the npx form, to go further.
+
+**Updating the CLI itself is separate**, and it's your package manager's job:
+
+```bash
+npm i -g uniweb@latest        # npm
+pnpm add -g uniweb@latest     # pnpm
+yarn global add uniweb@latest # yarn
+```
+
+`uniweb update` prints the right command for your install when a newer release exists. It will *not* update the CLI itself — running it twice was never the intent.
+
+---
+
 ## Documentation
 
 Full documentation is available at **[github.com/uniweb/docs](https://github.com/uniweb/docs)**:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.12.21",
+  "version": "0.12.22",
   "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/runtime": "0.8.14",
-    "@uniweb/core": "0.7.11",
-    "@uniweb/kit": "0.9.13"
+    "@uniweb/core": "0.7.12",
+    "@uniweb/kit": "0.9.14",
+    "@uniweb/runtime": "0.8.15"
   },
   "peerDependencies": {
-    "@uniweb/build": "0.14.5",
-    "@uniweb/content-reader": "1.1.11",
-    "@uniweb/semantic-parser": "1.1.17"
+    "@uniweb/semantic-parser": "1.1.17",
+    "@uniweb/content-reader": "1.1.12",
+    "@uniweb/build": "0.14.6"
   },
   "peerDependenciesMeta": {
     "@uniweb/build": {

package/partials/agents.md

@@ -149,10 +149,12 @@ uniweb deploy --host=<adapter>    # Deploy to a static host: cloudflare-pages, n
 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
 uniweb doctor                     # Diagnose project configuration issues (--fix to auto-repair)
-uniweb update                     # Reconcile workspace state with the CLI: align @uniweb/*
-                                  # deps in every package.json + refresh this AGENTS.md.
-                                  # Use --dry-run to preview, --deps-only to skip the doc.
+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.
 
 # Help
 uniweb --help                     # Top-level help
@@ -161,7 +163,11 @@ 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.
 
-If this AGENTS.md was stamped against an older CLI than the workspace's installed `@uniweb/*` packages, run `uniweb update --dry-run` to see the gap. The verb refuses to refresh the doc while declared deps lag the CLI — a stale doc that documents features the installed code doesn't have is worse than no refresh.
+**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 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.
+
+**Staying current.** `uniweb update` aligns this project's `@uniweb/*` deps and `AGENTS.md` to the CLI that runs it; `uniweb doctor` reports drift without mutating. To pin to the newest published release, run `npx uniweb@latest update --yes` — no global install needed. The verb won't refresh AGENTS.md while declared deps still lag the CLI, or while edited deps haven't been installed: both would put the doc ahead of the code. Updating the CLI itself is your package manager's job (`npm i -g uniweb@latest`, `pnpm add -g uniweb@latest`, …); `uniweb update` does not do that.
 
 ---
 
@@ -276,8 +282,6 @@ The system has multi-layer fallbacks so missing or partial information is always
 
 Bottom line: a foundation that doesn't set `runtimePolicy` gets `auto-minor` behavior automatically. A foundation that doesn't ship `runtime-pin.json` at all (e.g. a legacy build) still serves correctly through the platform's compatibility path — you just don't get the propagation benefits. Set `runtimePolicy` explicitly only when you want to override the default (typically to `exact` for stability-critical builds).
 
-(For platform operators interested in how propagation walks consume this field, see `kb/platform/operations/version-propagation.md` in the private docs.)
-
 ---
 
 ## Content Authoring
@@ -1038,18 +1042,44 @@ All non-reserved frontmatter fields become `params`. Reserved: `type`, `preset`,
 
 ### Data
 
-A component on a page with a `data:` or `fetch:` declaration automatically receives that data in `content.data.{schema}`. No opt-in required in `meta.js`. On a template page (`[slug]/`), the matched item is also delivered as `content.data.{singular}` (e.g. `content.data.article` when the parent declares `data: articles`).
+A component on a page with a `data:` or `fetch:` declaration automatically receives that data in `content.data.{key}`. No opt-in required in `meta.js`. **Bound collections always arrive as arrays.** On a list page, `content.data.articles` is the full collection. On a template page (`[slug]/`), the matched record is delivered under the *same* collection key as a single-element array — the detail section reads `content.data.articles[0]`. When nothing matches, the key is `[]`. The runtime never coerces the array to a single object and never synthesizes a separate singular key.
 
 ```jsx
 function Article({ content, block }) {
   if (block.dataLoading) return <DataPlaceholder />
-  const article = content.data.article
+  const article = content.data.articles?.[0]   // focused record on a [slug] page
   if (!article) return <NotFound />
   return <ArticleView article={article} />
 }
 ```
 
-Components can ignore keys in `content.data` they don't need — the same way unused `params` are ignored. For declarative shape hints consumed by the editor and `prepare-props`, add `data: { entity: 'articles' }` to `meta.js`. For an explicit opt-out (rare), set `data: false`.
+Components can ignore keys in `content.data` they don't need — the same way unused `params` are ignored.
+
+**Declaring data schemas.** `meta.js` declares the schema for each `content.data` key with a single `data:` field — there is no separate `schemas:` key. Each entry's value is one of: a **named ref** (`'@/article'` resolves to this foundation's `foundation/schemas/article.{js,json,yml}`; `'@std/person'` is a shared standard), an **inline field map** (`{ field: { type, default } }`), or an **inline rich-form** (`{ fields: [...] }`, an editor form). Refs use Uniweb namespacing, resolved on disk at build time, never fetched: `@/name` (this foundation's own `foundation/schemas/`), `@std/name` (the shared standard schemas, shipped in the `@uniweb/schemas` package), and `@org/name` (an org's own schemas, from its `@org/schemas` package — define a schema once and share it across foundations). The schema is a hint: it supplies field defaults and drives the editor, not delivery (which is default-on). For an explicit opt-out (rare), set `data: false`.
+
+```js
+// meta.js
+export default {
+  data: {
+    articles: '@/article',                               // named ref (this foundation)
+    authors:  '@std/person',                             // named ref (shared standard)
+    pricing:  { tier: { type: 'string', default: '' } }, // inline field map
+  },
+}
+```
+
+**Routing a scope to a folder.** By default `@org/name` resolves from that org's `@org/schemas` package. A foundation can instead route a scope to a plain folder of schema files — anywhere on disk, no package, no install — via an optional `schemas.config.js` at its root. This is how a team shares one set of schemas across many foundations:
+
+```js
+// schemas.config.js  —  @acme/person → ../shared/acme-schemas/person.{js,yml}
+export default { '@acme': '../shared/acme-schemas', '@brand': process.env.BRAND_SCHEMAS }
+```
+
+Plain JS, so paths can be relative, absolute, or read from an env var. A routed scope wins over the package convention; `@/` and `@uniweb` are never routable; an empty value (e.g. an unset env var) falls back to the package convention.
+
+**Validate your data.** `uniweb validate` checks your file-based data against these declared schemas — missing required fields, type/enum/format mismatches, nested fields — before you ship. Warns by default, `--strict` for a non-zero CI exit. It's distinct from `uniweb doctor` (which checks project structure): `validate` checks your *data* against the schemas you *declared*. Remote (`url:`), `ref`/`options`, and rich `sections`-form inputs are reported deferred — validate those against live data.
+
+When the same record needs to be a single object rather than a one-element array, that's the foundation's job: read `content.data.articles[0]`, or reshape `content.data` once with a `handlers.data` hook.
 
 **Authoring queries.** Fetch declarations (`fetch:` or the `data:` shorthand) accept query operators that describe which records you want, in what order, how many: `where:` (a where-object predicate), `sort:` (e.g. `date desc`), `limit:` (first N records). Whether the source evaluates them or the framework applies them as a runtime fallback is a transport detail controlled by the site's `fetcher.supports:` declaration.
 
@@ -1478,7 +1508,7 @@ const page = website.activePage
 // Returns [{ id, route, navigableRoute, translatedRoute, title, label, description, hasContent, version, children }]
 //
 // Options:
-//   for: 'header' | 'footer'  — filter by nav type (respects hideInHeader/hideInFooter)
+//   for: 'header' | 'footer' | <area>  — filter by nav area (respects the page's hideIn)
 //   nested: true (default)    — nested hierarchy with children; false = flat list
 //   includeHidden: false       — include hidden pages
 //   filter: (page) => bool    — custom filter function
@@ -1490,7 +1520,7 @@ const page = website.activePage
 //   website.getAllPages()     — flat list: getPageHierarchy({ nested: false })
 //
 // Common patterns:
-website.getPageHierarchy({ for: 'header' })           // Header nav (excludes hideInHeader pages)
+website.getPageHierarchy({ for: 'header' })           // Header nav (excludes pages with 'header' in hideIn)
 website.getPageHierarchy()                             // Full nested hierarchy (no nav filtering)
 website.getPageHierarchy({ nested: false })            // Flat list of all visible pages
 website.getPageHierarchy({ nested: false, includeHidden: true })  // Everything including hidden

package/partials/config-reference.hbs

@@ -40,8 +40,7 @@ index: intro                     # Or just name the index
 
 # Navigation visibility
 hidden: true                     # Hide from all navigation
-hideInHeader: true               # Hide from header only
-hideInFooter: true               # Hide from footer only
+hideIn: [header]                 # Hide from named nav areas only (header, footer, sidebar, …)
 
 # Layout overrides
 layout:

package/src/commands/add.js

@@ -18,6 +18,7 @@ import prompts from 'prompts'
 import yaml from 'js-yaml'
 import { resolveFoundationSrcPath } from '@uniweb/build'
 import { scaffoldFoundation, scaffoldSite, applyContent, applyStarter, mergeTemplateDependencies } from '../utils/scaffold.js'
+import { resolvePlacement, SITE_KIND, FOUNDATION_KIND } from '../utils/placement.js'
 import {
   readWorkspaceConfig,
   addWorkspaceGlob,
@@ -212,7 +213,6 @@ async function addFoundation(rootDir, projectName, opts, pm = 'pnpm') {
   // name (`ui`) or a path (`foundations/ui`); resolvePlacement handles
   // both. Format validation runs on the derived package name below, not
   // on the raw input — slashes in the input are intentional path syntax.
-  const FOUNDATION_KIND = { defaultDir: 'src', defaultPkg: 'src', projectSub: 'src' }
   const placement = resolvePlacement(rootDir, name, opts, FOUNDATION_KIND)
   const { relativePath } = placement
   let { packageName } = placement
@@ -306,7 +306,6 @@ async function addSite(rootDir, projectName, opts, pm = 'pnpm') {
   const existingNames = await getExistingPackageNames(rootDir)
 
   // Resolve placement first (path + package name); see notes in addFoundation.
-  const SITE_KIND = { defaultDir: 'site', defaultPkg: 'site', projectSub: 'site' }
   const placement = resolvePlacement(rootDir, name, opts, SITE_KIND)
   const { relativePath } = placement
   let siteName = placement.packageName
@@ -651,91 +650,6 @@ async function addProject(rootDir, projectName, opts, pm = 'pnpm') {
   log(`Next: ${colors.cyan}${installCmd(pm)} && uniweb dev ${sitePkgName}${colors.reset}`)
 }
 
-/**
- * Resolve where a foundation or site should be placed, given the user's input.
- *
- * The rule: **the user names a folder, and we create exactly that folder.**
- * No silent nesting under `foundations/` / `sites/`, no inferring layout from
- * pre-existing globs. The framework doesn't require any particular folder
- * structure (the build classifies packages by their contents, not their
- * location), so the CLI shouldn't impose one.
- *
- * Resolution priority (foundation example, same shape for site):
- *
- *   1. `--path <dir>`                   → explicit folder. Name is the path's
- *                                          last segment (used as the package
- *                                          name unless `name` was also given).
- *   2. `name` contains `/`              → treat as a path (e.g., `foundations/ui`).
- *                                          Folder = the path, package name =
- *                                          the last segment.
- *   3. `name` (no slash)                → folder = `<name>/`, package name = `<name>`.
- *   4. `--project <project>`            → folder = `<project>/<defaultSub>` and
- *                                          package name = `<project>-<defaultSub>`
- *                                          (the co-located convention; only this
- *                                          one uses the `-src` / `-site` suffix).
- *   5. (no input)                       → folder = `<defaultDir>/`, package name
- *                                          = `<defaultPkg>` (`src/` + `src`
- *                                          for foundations; `site/` + `site` for
- *                                          sites).
- *
- * @param {string} rootDir
- * @param {string|null} name - Either a bare name or a path-with-slash.
- * @param {{ path?: string, project?: string }} opts
- * @param {{ defaultDir: string, defaultPkg: string, projectSub: string }} kind
- * @returns {{ relativePath: string, packageName: string }}
- */
-function resolvePlacement(rootDir, name, opts, kind) {
-  // 1. --path is a PARENT directory. The folder is `<path>/<name>` if a
-  //    name was given, or `<path>` itself if not (the path's last segment
-  //    is then taken as the package name).
-  if (opts.path) {
-    const parent = opts.path.replace(/\/+$/, '')
-    if (name) {
-      const last = name.split('/').filter(Boolean).pop()
-      return {
-        relativePath: `${parent}/${name}`.replace(/\/+/g, '/'),
-        packageName: last,
-      }
-    }
-    const lastSegment = parent.split('/').filter(Boolean).pop() || parent
-    return {
-      relativePath: parent,
-      packageName: lastSegment,
-    }
-  }
-
-  // 2. name contains a slash → treat as a path.
-  if (name && name.includes('/')) {
-    const relativePath = name.replace(/\/+$/, '')
-    const lastSegment = relativePath.split('/').filter(Boolean).pop()
-    return {
-      relativePath,
-      packageName: lastSegment,
-    }
-  }
-
-  // 3. Bare name.
-  if (name) {
-    return {
-      relativePath: name,
-      packageName: name,
-    }
-  }
-
-  // 4. --project (co-located convention with -src / -site suffix).
-  if (opts.project) {
-    return {
-      relativePath: `${opts.project}/${kind.projectSub}`,
-      packageName: `${opts.project}-${kind.projectSub}`,
-    }
-  }
-
-  // 5. Default placement.
-  return {
-    relativePath: kind.defaultDir,
-    packageName: kind.defaultPkg,
-  }
-}
 
 /**
  * Resolve which foundation to wire a site to

package/src/commands/build.js

@@ -548,7 +548,7 @@ function resolveFoundationDir(projectDir, siteConfig) {
  * and deploy was reading that stripped version, causing the worker to
  * mis-detect split and serve blank pages. Link mode skips prerender
  * entirely; `dist/site-content.json` keeps full sections; the worker
- * splits correctly. See `kb/framework/build/workspace-ergonomics.md`.
+ * splits correctly.
  */
 async function buildSiteLink(projectDir, options = {}) {
   const { siteConfig = null } = options
@@ -966,7 +966,7 @@ export async function build(args = []) {
   // --host names the host adapter for this build's prerender step.
   // Default = 'cloudflare-pages' (resolved inside prerender.js, via the
   // registry). Build does not read deploy.yml; that is the deploy
-  // orchestrator's job. See kb/framework/plans/static-host-deploy-adapters.md.
+  // orchestrator's job.
   //
   // `--host` with no value → interactive picker (errors in CI / non-TTY).
   const { readFlagValue } = await import('../utils/args.js')

package/src/commands/clone.js

@@ -0,0 +1,337 @@
+/**
+ * uniweb clone <site-uuid> — materialize a backend site as a local file project.
+ *
+ * The "git clone" of the site-content remote model (see
+ * kb/framework/plans/site-content-remote-model.md): the backend is the remote, a
+ * file project is a working clone. `clone` is the create-side sibling of
+ * `uniweb pull`/`uniweb push` — it bootstraps a brand-new project from a site that
+ * already lives in the backend (typically authored in the visual app).
+ *
+ * What it does, and a key constraint: clone runs from a GLOBAL install before any
+ * project exists, so it must NOT statically import `@uniweb/build` (that would crash
+ * `npx uniweb clone`, same reason utils/workspace.js loads the classifier lazily).
+ * So clone does the minimum itself and delegates the heavy lifting:
+ *
+ *   1. plain `fetch` GET <origin>/dev/site/content/pull/<uuid> — read the `foundation`
+ *      ref out of that one document (no `@uniweb/build` needed for a GET);
+ *   2. scaffold the HARNESS — a full Vite site package whose foundation is
+ *      REFERENCED (runtime-loaded), no local foundation sibling (scaffoldSite with
+ *      foundationRef and no foundationPath) + AGENTS.md + deps pinned to this CLI's
+ *      version matrix; placement reuses create (new workspace / in-place) and add's
+ *      resolver (into an existing workspace, any shape);
+ *   3. seed the site's one identity — site.yml::$uuid (a plain YAML scalar write).
+ *      The folder is pulled by this same uuid, so there is no separate folder uuid to
+ *      seed;
+ *   4. install, then delegate the projection to the project-local `uniweb pull` (which
+ *      resolves the now-installed project-local `@uniweb/build`; clone forwards
+ *      `--no-collections` to it when set).
+ *
+ * Sites are private — authenticate with `uniweb login` first; the session carries
+ * identity + the backend origin. There is no `--foundation` flag: the site carries
+ * its foundation ref and clone honors it verbatim (switching a site's foundation is a
+ * deliberate, high-risk operation, never a clone convenience).
+ *
+ * Usage:
+ *   uniweb login
+ *   uniweb clone <site-uuid> [name|.]    New workspace (or `.` in-place / a site in
+ *                                        the current workspace when run inside one)
+ *   uniweb clone <uuid> --path sites     Place under sites/ (segregated layout)
+ *   uniweb clone <uuid> --project docs   Co-located docs/site
+ *   uniweb clone <uuid> --no-collections Pull pages only; skip collection records
+ *
+ * Endpoints: <origin>/dev/site/content/pull/<uuid>. Origin from
+ *   --registry  >  UNIWEB_REGISTER_URL  >  the local default (internal dev overrides;
+ *   not the user-facing path — `uniweb login` determines the origin).
+ * Auth:  --token  >  UNIWEB_TOKEN  >  `uniweb login` session.
+ */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs'
+import { join, resolve, basename, dirname } from 'node:path'
+import { spawnSync } from 'node:child_process'
+import { scaffoldWorkspace, scaffoldSite } from '../utils/scaffold.js'
+import { resolvePlacement, SITE_KIND } from '../utils/placement.js'
+import { findWorkspaceRoot } from '../utils/workspace.js'
+import { addWorkspaceGlob } from '../utils/config.js'
+import { detectWorkspacePm, installCmd } from '../utils/pm.js'
+import { ensureRegistryAuth } from '../utils/registry-auth.js'
+import { isNonInteractive, getCliPrefix } from '../utils/interactive.js'
+import { extractFoundationRef } from '../utils/site-content-refs.js'
+
+const DEFAULT_BACKEND_ORIGIN = 'http://localhost:8080'
+
+const colors = {
+  reset: '\x1b[0m', bright: '\x1b[1m', dim: '\x1b[2m',
+  red: '\x1b[31m', green: '\x1b[32m', yellow: '\x1b[33m', blue: '\x1b[36m', cyan: '\x1b[36m',
+}
+const log = console.log
+const success = (m) => log(`${colors.green}✓${colors.reset} ${m}`)
+const error = (m) => console.error(`${colors.red}✗${colors.reset} ${m}`)
+const info = (m) => log(`${colors.blue}→${colors.reset} ${m}`)
+const note = (m) => log(`  ${colors.dim}${m}${colors.reset}`)
+
+function flagValue(args, name) {
+  const eq = args.find((a) => a.startsWith(`${name}=`))
+  if (eq) return eq.slice(name.length + 1)
+  const i = args.indexOf(name)
+  if (i !== -1 && args[i + 1] && !args[i + 1].startsWith('-')) return args[i + 1]
+  return null
+}
+
+function slugify(s) {
+  return String(s || '').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '')
+}
+
+// Tolerant single-entity document extraction (mirrors pull.js; duplicated rather
+// than imported because pull.js statically imports @uniweb/build).
+export function extractDocument(payload) {
+  if (!payload || typeof payload !== 'object') return null
+  if (payload.$model || payload.$id || payload.info) return payload
+  return payload.document || payload.entity || null
+}
+
+// Unwrap a possibly-localized scalar (a `{ <locale>: value }` map) to a plain string.
+function unwrapScalar(v) {
+  if (typeof v === 'string') return v
+  if (v && typeof v === 'object') {
+    const first = Object.values(v).find((x) => typeof x === 'string')
+    if (first) return first
+  }
+  return null
+}
+
+/**
+ * Read the seeds clone needs out of a site-content `$`-document:
+ *  - foundationRef: the `foundation` ref (a URL or our `@ns/name@ver`) — written
+ *    verbatim into site.yml so the runtime loads it as a federated module;
+ *  - name: a display name for the new project.
+ *
+ * No folder uuid is read: the site holds one identity (its site-content uuid), and
+ * the folder is pulled by that same uuid — the framework never holds a folder uuid.
+ */
+export function extractCloneSeeds(document) {
+  const info = document?.info || {}
+  return {
+    foundationRef: extractFoundationRef(info, document),
+    name: unwrapScalar(info.name) ?? unwrapScalar(document?.name) ?? null,
+  }
+}
+
+// Insert/replace a top-level `$uuid:` scalar in a YAML file's text without
+// disturbing the rest (the scaffolded site.yml is comment-heavy — don't round-trip
+// through a YAML dumper). Inserts after the first `name:` line, else prepends.
+function seedYamlUuid(filePath, uuid) {
+  let text = existsSync(filePath) ? readFileSync(filePath, 'utf8') : ''
+  if (/^\$uuid:/m.test(text)) {
+    text = text.replace(/^\$uuid:.*$/m, `$uuid: ${uuid}`)
+  } else {
+    const nameMatch = text.match(/^name:.*$/m)
+    if (nameMatch) {
+      const idx = nameMatch.index + nameMatch[0].length
+      text = text.slice(0, idx) + `\n$uuid: ${uuid}` + text.slice(idx)
+    } else {
+      text = `$uuid: ${uuid}\n` + text
+    }
+  }
+  mkdirSync(dirname(filePath), { recursive: true })
+  writeFileSync(filePath, text)
+}
+
+// Build the package-manager argv to run the project-local `uniweb pull`.
+function pullExecArgv(pm, extra) {
+  // npm needs `exec --` to forward flags to the binary; pnpm/yarn don't.
+  if (pm === 'npm') return ['exec', '--', 'uniweb', 'pull', ...extra]
+  return ['exec', 'uniweb', 'pull', ...extra]
+}
+
+/**
+ * @param {string[]} args
+ * @param {object} [deps] - injectable seams for testing:
+ *   fetch, getToken, skipInstall, skipPull, runInstall(projectDir, pm),
+ *   runPull(siteDir, pm, extraArgs).
+ */
+export async function clone(args = [], deps = {}) {
+  const fetchImpl = deps.fetch || globalThis.fetch
+
+  const positionals = args.filter((a) => !a.startsWith('-'))
+  const siteUuid = positionals[0]
+  const target = positionals[1] || null // [name|.]
+
+  if (!siteUuid) {
+    error('Missing site uuid.')
+    log(`\nUsage: ${getCliPrefix()} clone <site-uuid> [name|.] [--path <dir>] [--project <name>] [--no-collections]`)
+    log(`${colors.dim}Sites are private — run \`uniweb login\` first.${colors.reset}`)
+    return { exitCode: 2 }
+  }
+
+  const noCollections = args.includes('--no-collections') || args.includes('--content-only')
+  const pathFlag = flagValue(args, '--path')
+  const projectFlag = flagValue(args, '--project')
+  const tokenFlag = flagValue(args, '--token')
+  const registryFlag = flagValue(args, '--registry') || process.env.UNIWEB_REGISTER_URL || DEFAULT_BACKEND_ORIGIN
+
+  let apiBase
+  try {
+    apiBase = new URL(registryFlag).origin
+  } catch {
+    error(`Invalid --registry / UNIWEB_REGISTER_URL: ${registryFlag}`)
+    return { exitCode: 2 }
+  }
+
+  let cachedToken = null
+  const getToken =
+    deps.getToken ||
+    (async () => {
+      if (cachedToken) return cachedToken
+      cachedToken = tokenFlag || process.env.UNIWEB_TOKEN || (await ensureRegistryAuth({ apiBase, command: 'Cloning', args }))
+      return cachedToken
+    })
+
+  // 1. GET the site-content document (plain fetch — no @uniweb/build).
+  const url = `${apiBase}/dev/site/content/pull/${encodeURIComponent(siteUuid)}`
+  info(`Reading site ${colors.bright}${siteUuid}${colors.reset} from ${colors.dim}${url}${colors.reset} …`)
+  let payload
+  try {
+    const res = await fetchImpl(url, { headers: { Authorization: `Bearer ${await getToken()}` } })
+    if (res.status === 404) {
+      error(`Site not found (404) — check the uuid, or you lack access.`)
+      return { exitCode: 1 }
+    }
+    if (!res.ok) {
+      error(`Could not read the site: HTTP ${res.status} ${res.statusText}`)
+      if (res.status === 401 || res.status === 403) note('Run `uniweb login` first (or pass --token <bearer>).')
+      return { exitCode: 1 }
+    }
+    payload = await res.json()
+  } catch (err) {
+    error(`Could not reach the backend at ${url}: ${err.message}`)
+    return { exitCode: 1 }
+  }
+
+  const document = extractDocument(payload)
+  if (!document) {
+    error('The site-content response carried no recognizable document.')
+    return { exitCode: 1 }
+  }
+  const { foundationRef, name: siteDisplayName } = extractCloneSeeds(document)
+  if (!foundationRef) {
+    note('! The pulled site declares no foundation ref — set `foundation:` in site.yml after clone.')
+  }
+
+  // 2. Resolve placement (one verb, context-aware).
+  const cwd = deps.cwd || process.cwd()
+  const inPlace = target === '.'
+  const existingRoot = inPlace ? null : findWorkspaceRoot(cwd)
+
+  let projectDir // the package-manager root (for install)
+  let siteDir // where the site package lands
+  let sitePkgName
+  let workspaceName
+  let isNewWorkspace
+  let placement = null
+
+  if (inPlace) {
+    isNewWorkspace = true
+    projectDir = cwd
+    workspaceName = slugify(basename(cwd)) || 'site'
+    siteDir = join(projectDir, 'site')
+    sitePkgName = 'site'
+  } else if (existingRoot) {
+    isNewWorkspace = false
+    projectDir = existingRoot
+    placement = resolvePlacement(existingRoot, target, { path: pathFlag, project: projectFlag }, SITE_KIND)
+    siteDir = join(existingRoot, placement.relativePath)
+    sitePkgName = placement.packageName
+    workspaceName = sitePkgName
+  } else {
+    isNewWorkspace = true
+    workspaceName = target || slugify(siteDisplayName) || null
+    if (!workspaceName) {
+      error('Could not derive a project name from the site. Pass one: `uniweb clone <uuid> <name>`.')
+      return { exitCode: 2 }
+    }
+    if (!/^[a-z0-9-]+$/.test(workspaceName)) {
+      error(`Invalid project name "${workspaceName}" — use lowercase letters, numbers, and hyphens.`)
+      return { exitCode: 2 }
+    }
+    projectDir = resolve(cwd, workspaceName)
+    siteDir = join(projectDir, 'site')
+    sitePkgName = 'site'
+  }
+
+  // Conflict guards.
+  if (isNewWorkspace && !inPlace && existsSync(projectDir)) {
+    error(`Directory already exists: ${workspaceName}`)
+    return { exitCode: 1 }
+  }
+  if (existsSync(join(siteDir, 'site.yml'))) {
+    error(`A site already exists at ${siteDir} — refusing to overwrite.`)
+    return { exitCode: 1 }
+  }
+
+  // 3. Scaffold the harness (ref-only site: foundationRef, no foundationPath).
+  const onProgress = (m) => note(m)
+  const siteContext = { name: sitePkgName, projectName: workspaceName, ...(foundationRef ? { foundationRef } : {}) }
+
+  if (isNewWorkspace) {
+    info(`Scaffolding ${colors.bright}${workspaceName}${colors.reset} …`)
+    await scaffoldWorkspace(
+      projectDir,
+      { projectName: workspaceName, workspaceGlobs: ['site'], scripts: { dev: 'uniweb dev', build: 'uniweb build' } },
+      { onProgress },
+    )
+    await scaffoldSite(siteDir, siteContext, { onProgress })
+  } else {
+    info(`Adding site ${colors.bright}${sitePkgName}${colors.reset} to the workspace at ${colors.dim}${placement.relativePath}/${colors.reset} …`)
+    await scaffoldSite(siteDir, siteContext, { onProgress })
+    await addWorkspaceGlob(existingRoot, placement.relativePath)
+  }
+
+  // 4. Seed the site's one identity — site.yml::$uuid. The folder is pulled by this
+  // same uuid (the backend resolves the site's @uniweb/folder from it), so there is no
+  // separate folder uuid to seed.
+  seedYamlUuid(join(siteDir, 'site.yml'), siteUuid)
+  success(`Scaffolded the site harness${foundationRef ? ` (foundation: ${foundationRef})` : ''}.`)
+
+  // 5. Install, then delegate the projection to the project-local `uniweb pull`.
+  const pm = detectWorkspacePm(projectDir) || 'pnpm'
+
+  if (deps.skipInstall) {
+    note('Skipping install (test mode).')
+  } else if (deps.runInstall) {
+    await deps.runInstall(projectDir, pm)
+  } else {
+    info(`Installing dependencies (${installCmd(pm)}) …`)
+    const r = spawnSync(pm, ['install'], { cwd: projectDir, stdio: 'inherit' })
+    if (r.status !== 0) {
+      error(`Install failed. Once it succeeds, run \`uniweb pull\` from ${siteDir} to fetch the content.`)
+      return { exitCode: 1 }
+    }
+  }
+
+  const pullExtra = []
+  if (flagValue(args, '--registry')) pullExtra.push('--registry', registryFlag)
+  if (tokenFlag) pullExtra.push('--token', tokenFlag)
+  if (noCollections) pullExtra.push('--no-collections')
+
+  if (deps.skipPull) {
+    note('Skipping pull (test mode).')
+  } else if (deps.runPull) {
+    await deps.runPull(siteDir, pm, pullExtra)
+  } else {
+    info('Pulling content …')
+    const r = spawnSync(pm, pullExecArgv(pm, pullExtra), { cwd: siteDir, stdio: 'inherit' })
+    if (r.status !== 0) {
+      error(`Content pull failed. Fix the issue, then run \`uniweb pull\` from ${siteDir}.`)
+      return { exitCode: 1 }
+    }
+  }
+
+  log('')
+  success(`Cloned site into ${colors.bright}${isNewWorkspace && !inPlace ? workspaceName : siteDir}${colors.reset}`)
+  if (isNewWorkspace && !inPlace) {
+    log(`\nNext: ${colors.cyan}cd ${workspaceName} && uniweb dev${colors.reset}`)
+  } else {
+    log(`\nNext: ${colors.cyan}uniweb dev${colors.reset}`)
+  }
+  return { exitCode: 0 }
+}