uniweb 0.59.2 → 0.61.0

package/src/commands/clone.js

@@ -19,7 +19,8 @@
  *      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).
+ *   3. seed the site's identity on that backend — its section of `sync.json` (plain
+ *      JSON, written with no dependencies).
  *      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
@@ -42,7 +43,8 @@
  * Backend: via BackendClient (the site-content pull lane). Origin from
  *   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.
+ * Auth:  UNIWEB_TOKEN  >  the stored session  >  `uniweb login`. No `--token` (retired
+ *   from the backend commands 2026-09-21).
  */
 
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs'
@@ -59,7 +61,6 @@ import { extractFoundationRef } from '../utils/site-content-refs.js'
 import { readUwxDocuments } from '../utils/uwx-read.js'
 import { recordWritten } from '../utils/pull-written.js'
 import { checkFlags } from '../utils/flag-guard.js'
-import { recordSiteBackend } from '../utils/site-identity.js'
 
 const colors = {
   reset: '\x1b[0m',
@@ -128,24 +129,35 @@ export function extractCloneSeeds(document) {
   }
 }
 
-// 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
+// Seed `sync.json` with the identity this clone was pulled by.
+//
+// ⛔ **Dependency-free on purpose, and this has bitten before.** `clone` runs BEFORE
+// `pnpm install`, so `@uniweb/build`'s store is not on disk yet. The previous version
+// of this recorded the scope through a lazy `import('@uniweb/build/uwx')` whose
+// failure branch returned null and wrote NOTHING — so a fresh clone recorded nothing
+// essentially always, and the next command stopped dead complaining about a backend
+// the user had named on the command line. Measured by the backend lane 2026-09-18:
+// 0.48.5 recorded it, 0.57.0 did not.
+//
+// ⭐ JSON needs no parser, which is most of why the store is JSON rather than YAML —
+// `site.yml`'s equivalent needed a hand-rolled dependency-free WRITER for exactly
+// this. The store stays the one writer everywhere else; this seeds a fresh file.
+// `test/clone.test.js` covers it end to end with `skipInstall: true`.
+function seedSyncJson(siteDir, origin, uuid) {
+  const file = join(siteDir, 'sync.json')
+  let doc = { version: 1, backends: {} }
+  if (existsSync(file)) {
+    try {
+      const parsed = JSON.parse(readFileSync(file, 'utf8'))
+      if (parsed?.backends && typeof parsed.backends === 'object') doc = parsed
+    } catch {
+      /* unreadable — a fresh clone's file is ours to write */
     }
   }
-  mkdirSync(dirname(filePath), { recursive: true })
-  writeFileSync(filePath, text)
+  const key = new URL(origin).origin
+  doc.backends[key] = { ...(doc.backends[key] || {}), site: { ...(doc.backends[key]?.site || {}), uuid } }
+  mkdirSync(dirname(file), { recursive: true })
+  writeFileSync(file, JSON.stringify(doc, null, 2) + '\n')
 }
 
 // Build the package-manager argv to run the project-local `uniweb pull`.
@@ -188,12 +200,7 @@ export async function clone(args = [], deps = {}) {
     args.includes('--no-records') || args.includes('--content-only')
   const pathFlag = flagValue(args, '--path')
   const projectFlag = flagValue(args, '--project')
-  const tokenFlag = flagValue(args, '--token')
-  const explicitBackend =
-    flagValue(args, '--backend')
   const client = new BackendClient({
-    originFlag: explicitBackend,
-    token: tokenFlag,
     getToken: deps.getToken,
     fetchImpl: deps.fetch,
     args,
@@ -222,7 +229,7 @@ export async function clone(args = [], deps = {}) {
     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>).')
+        note('Run `uniweb login` first.')
       return { exitCode: 1 }
     }
     documents = readUwxDocuments(Buffer.from(await res.arrayBuffer()))
@@ -340,21 +347,19 @@ export async function clone(args = [], deps = {}) {
     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)
-  // …and the SYNC SCOPE that makes it meaningful. `clone` is the sharpest case for it:
-  // the uuid comes from whoever we read, and until now nothing on disk recorded that —
-  // so a teammate who cloned this project and ran `uniweb pull` while logged in
-  // elsewhere sent this backend's uuid to a different one. A no-op on the default
-  // backend. (The two CREATE paths record it via `recordAndDescribeOwner`; clone seeds
-  // an existing site and never reaches them, which is why it is written here too.)
-  const scope = await recordSiteBackend(siteDir, client.origin)
+  // 4. Seed the identity this clone was pulled by, under the backend that minted it.
+  // The folder is pulled by the same uuid (the backend resolves the site's
+  // @uniweb/folder from it), so there is no separate folder uuid to seed.
+  //
+  // ⭐ The backend is the KEY, not a separate note. `clone` was the sharpest case for
+  // the old `$backend`: the uuid came from whoever we read and nothing on disk said
+  // so, and a teammate who pulled while logged in elsewhere sent it to the wrong
+  // backend. Stored under the origin, that cannot be expressed.
+  seedSyncJson(siteDir, client.origin, siteUuid)
   success(
     `Scaffolded the site harness${foundationRef ? ` (foundation: ${foundationRef})` : ''}.`
   )
-  if (scope) note(`Bound to ${scope} (recorded $backend in site.yml).`)
+  note(`Bound to ${client.origin} (recorded in sync.json).`)
 
   // 5. Install, then delegate the projection to the project-local `uniweb pull`.
   const pm = detectWorkspacePm(projectDir) || 'pnpm'
@@ -400,8 +405,6 @@ export async function clone(args = [], deps = {}) {
   )
 
   const pullExtra = []
-  if (explicitBackend) pullExtra.push('--backend', explicitBackend)
-  if (tokenFlag) pullExtra.push('--token', tokenFlag)
   if (noRecords) pullExtra.push('--no-records')
 
   if (deps.skipPull) {

package/src/commands/deploy.js

@@ -40,7 +40,7 @@
  *   uniweb deploy --host=uniweb    Delegate to `uniweb publish` (Uniweb hosting)
  *   uniweb deploy --target <name>  Pick a target from deploy.yml
  *   uniweb deploy --dry-run        Resolve everything; upload nothing
- *   uniweb deploy --no-save        Skip the deploy.yml lastDeploy auto-save
+ *   uniweb deploy --no-save        Do not record this deploy in deploy.yml
  *
  * Escape hatch: UNIWEB_SKIP_BUILD=1 reuses an existing dist/.
  */
@@ -56,6 +56,8 @@ import {
 } from '@uniweb/build/site'
 import { promptForDestination } from '../utils/destination-prompt.js'
 import { readFlagValue } from '../utils/args.js'
+import { DEFAULT_BACKEND_ORIGIN, getRegistryApiBaseUrl, loggedInOrigin } from '../utils/config.js'
+import { normalizeOrigin } from '../utils/site-identity.js'
 import { parseBoolEnv } from '../utils/env.js'
 import { headProvenance } from '../utils/git.js'
 import { warnIfContentDoesNotConform } from '../utils/conformance.js'
@@ -185,10 +187,42 @@ export async function deploy(args = []) {
   // Uniweb Cloud is `publish`'s flow — delegate so deploy.yml stays one
   // actionable record and there's a single implementation of go-live.
   if (plan.kind === 'uniweb') {
+    // ⭐ `--host=uniweb` IS `publish` *[Diego, 2026-09-21]*: it goes to the backend you are
+    // logged in to — deploy follows the login like every other command. A deploy.yml
+    // uniweb target's `backend:` records where that target's publishes went; it routes
+    // nothing (publish files its record under the target naming its backend).
+    const goingTo = getRegistryApiBaseUrl()
+    const aimedBy = process.env.UNIWEB_REGISTER_URL
+      ? 'UNIWEB_REGISTER_URL'
+      : loggedInOrigin()
+        ? 'the backend you are logged in to'
+        : 'the default backend — you are not logged in'
+    const fromTarget =
+      resolved.fromFile &&
+      resolved.host === 'uniweb' &&
+      // not after the wizard (`--host` with no value): a pick there names no target
+      (hostFromFlag === undefined || hostFromFlag === 'uniweb')
+    const targetBackend = fromTarget
+      ? normalizeOrigin(resolved.config?.backend || DEFAULT_BACKEND_ORIGIN)
+      : null
+    if (targetBackend && targetBackend !== goingTo) {
+      if (targetFromFlag) {
+        // ⛔ A refusal, not a route: the user TYPED this destination, and going live
+        // somewhere else would contradict it with nothing said. Switching is a login.
+        say.err(
+          `Target '${resolved.targetName}' is on ${targetBackend}, but this would publish to ${goingTo} (${aimedBy}).`
+        )
+        say.dim(`To publish there, log in to it first: uniweb login --backend ${targetBackend}`)
+        process.exit(1)
+      }
+      say.dim(
+        `deploy.yml's default target '${resolved.targetName}' is on ${targetBackend}; publishing to ${goingTo} (${aimedBy}).`
+      )
+    }
     say.info('Uniweb Cloud → running `uniweb publish`.')
     console.log('')
-    // publish ignores deploy's --host/--target; --dry-run/--no-save/--backend
-    // /--token pass straight through.
+    // publish ignores deploy's --host/--target; --dry-run/--no-save pass straight
+    // through.
     const { publish } = await import('./publish.js')
     // Conformance was already reported above, and publish runs the same check
     // — without this the user reads one warning twice and learns to skim it.
@@ -225,11 +259,13 @@ export async function deploy(args = []) {
   // want a one-off experiment to rewrite the file). A host picked interactively
   // for a bare `deploy` is NOT an override — we DO want to remember it.
   const hostOverridden = !!hostFromFlag && hostFromFlag !== resolved.host
-  const autoSave = noSave || hostOverridden ? 'off' : resolved.autoSave
+  // An ad-hoc --host override describes no target, so there is nothing to file a
+  // deploy under — the switch goes off without anyone typing it.
+  const saveDeploys = !(noSave || hostOverridden) && resolved.saveDeploys !== false
 
   await deployStaticHost(siteDir, plan.host, resolved, {
     dryRun,
-    autoSave,
+    saveDeploys,
     hostOverridden
   })
 }
@@ -280,7 +316,7 @@ async function deployStaticHost(
   siteDir,
   hostName,
   resolved,
-  { dryRun, autoSave, hostOverridden }
+  { dryRun, saveDeploys, hostOverridden }
 ) {
   let getAdapter
   try {
@@ -399,7 +435,7 @@ async function deployStaticHost(
   }
 
   // Record a fresh lastDeploy.<target> entry. Skipped on --no-save and
-  // on ad-hoc --host overrides — see autoSave gating in deploy().
+  // on ad-hoc --host overrides — see saveDeploys gating in deploy().
   const gitStamp = {
     at: new Date().toISOString(),
     git: headProvenance(siteDir)
@@ -409,7 +445,7 @@ async function deployStaticHost(
     targetConfig: resolved.fromFile
       ? null
       : { host: hostName, ...deployConfig },
-    autoSave,
+    saveDeploys,
     lastDeploy: {
       at: gitStamp.at,
       host: hostName,
@@ -434,7 +470,7 @@ async function deployStaticHost(
 // ─── deploy.yml lastDeploy persistence ──────────────────────────
 
 async function persistLastDeploy(siteDir, opts) {
-  if (opts.autoSave === 'off') return
+  if (opts.saveDeploys === false) return
   try {
     const result = await recordLastDeploy(siteDir, opts)
     if (result?.created) {
@@ -497,21 +533,3 @@ export async function resolveSiteDir(args, verb = 'deploy') {
   }
   process.exit(1)
 }
-
-// The site's deploy.yml-bound backend origin (for the resolved `uniweb` target),
-// or null when there's no deploy.yml, the target isn't Uniweb hosting, or no
-// backend was recorded. Site verbs pass this to BackendClient as `siteBackend`
-// so a site stays bound to the backend it publishes to — deploy.yml is the
-// record of *where* a site is deployed (the 98% case is uniweb.app, but a B2B
-// university backend is just a `backend:` on the target). Sits below --backend
-// and UNIWEB_REGISTER_URL but above the logged-in session in the resolution
-// ladder (see resolveBackendOrigin). Best-effort: any read/parse error → null.
-export async function resolveSiteBackend(siteDir) {
-  try {
-    const deployYml = await loadDeployYml(siteDir)
-    const resolved = resolveTarget(deployYml, null)
-    return resolved.host === 'uniweb' ? resolved.config?.backend || null : null
-  } catch {
-    return null
-  }
-}

package/src/commands/doctor.js

@@ -166,9 +166,9 @@ function loadSiteYml(dir) {
 /**
  * Diagnose the compiled-collection output directory.
  *
- * `public/<DATA_DIR>/` holds what the build compiles from `entities/`, and
- * nothing else — `entities/` + `records.yml` is the only supported way to provide
- * structured data. Two consequences, both checked here:
+ * `public/<DATA_DIR>/` holds what the build compiles from `records/`, and
+ * nothing else — `records/` is the only supported way to provide structured
+ * data. Two consequences, both checked here:
  *
  * 1. **The mapping is a bijection.** Every entry should be backed by a
  *    declared collection. An entry that isn't is stale — most often a
@@ -969,7 +969,7 @@ function checkGeneratedDataDir({ sitePath, siteName, siteYml, issues, shouldFix,
   const dataDir = join(sitePath, 'public', DATA_DIR)
   // ⚠️ THE QUERIES, not the pool. `public/<DATA_DIR>/x.json` is a query's
   // MATERIALIZATION — one file per named query — so the bijection is with the
-  // declared queries, never with the schema folders under `entities/`.
+  // declared queries, never with the schema folders under `records/`.
   //
   // ⛔ BOTH HOMES, or this reports every compiled file as an orphan. A site that
   // keeps its queries in `queries.yml` has none in `site.yml`, and reading one
@@ -1045,7 +1045,7 @@ function checkGeneratedDataDir({ sitePath, siteName, siteYml, issues, shouldFix,
       const body = existing === null ? '' : existing.replace(/\n*$/, '\n')
       writeFileSync(
         gitignorePath,
-        `${body}\n# Compiled query results — generated from entities/ + queries.yml\n${rule}\n`
+        `${body}\n# Compiled query results — generated from records/ + queries.yml\n${rule}\n`
       )
       fixed(`added ${rule} to ${gitignorePath}`)
       if (existsSync(dataDir)) {
@@ -1418,8 +1418,7 @@ export async function doctor(args = []) {
     }
 
     // `public/<DATA_DIR>/` is the build's output directory and nothing else —
-    // `entities/` + `records.yml` is the only supported way to provide structured
-    // data. That makes the mapping a bijection: every entry there should be backed
+    // `records/` is the only supported way to provide structured data. That makes the mapping a bijection: every entry there should be backed
     // by a declared QUERY, so anything else is stale, and identifiable.
     //
     // It matters because the directory is written into the source tree rather

package/src/commands/forget.js

@@ -0,0 +1,197 @@
+/**
+ * `uniweb forget` — remove what this project recorded about where it has synced and
+ * deployed. Local files only; nothing on any backend changes.
+ *
+ *   uniweb forget --backend <url>   one backend
+ *   uniweb forget --all             everything — for a COPY that is to become a new project
+ *
+ * ## `--backend <url>`
+ *
+ *   - that backend's section of `sync.json` — the site uuid, the record map, asset
+ *     ids, provisioned services and the rest of what it minted;
+ *   - that backend's section of `.uniweb/backend-cache.json`;
+ *   - the `deploys:` records in `deploy.yml` that name it. ⭐ Its TARGETS stay: a
+ *     target is where you chose to ship, not something the backend told us, and the
+ *     next publish there simply creates a new site.
+ *
+ * Every other backend is untouched, which is only possible because all three are
+ * keyed by backend.
+ *
+ * ## `--all`
+ *
+ * A copied project carries the original's `sync.json`, so its first push updates the
+ * ORIGINAL's site — the copy sends uuids that are the original's. `--all` deletes
+ * `sync.json`, `.uniweb/backend-cache.json` and `deploy.yml`, after which the copy's
+ * next push creates a new site.
+ *
+ * ⭐ **`deploy.yml` goes whole, targets included** *[Diego, 2026-09-21]*. Its targets
+ * name the original's destinations — its Pages project, its bucket, its domain — so a
+ * deploy from the copy would overwrite the original there. The copy's first deploy
+ * writes a fresh one.
+ *
+ * ## What neither form touches
+ *
+ * ⛔ **Record files.** A record's `$uuid` is its OWN id, not any backend's. It is
+ * written once, on the record's first push anywhere, and never changes after;
+ * removing it would delete the record's identity, which is not what forgetting a
+ * backend means. A copy keeps them too: they never reach a backend again once the
+ * map that pointed them at the original's entities is gone. *[Diego, 2026-09-20.]*
+ *
+ * ⛔ **Any backend.** Every site still exists where it was. Deleting one is a
+ * different operation, on the backend's side.
+ *
+ * ## Why it exists
+ *
+ * Two jobs. A script pushes a template site to a short-lived dev server and then
+ * removes the traces of it without discarding the rest of the project (`--backend`)
+ * — which is also why traceless publish was dropped: push and pull leave traces too.
+ * And someone duplicates a project to start a new site from it (`--all`).
+ *
+ * ⚠️ **No default target.** Forgetting a backend you still use means its next push
+ * creates a second site there, so the verb makes you name it — `--backend` is
+ * required even when the project has synced with only one.
+ */
+
+import { readFlagValue } from '../utils/args.js'
+import { checkFlags } from '../utils/flag-guard.js'
+import { resolveSiteDir } from './deploy.js'
+import { forgetBackendCache, forgetAllBackendCaches } from '../backend/site-sync.js'
+import { clearBackend, forgetSyncStore, readBackendState } from '@uniweb/build/uwx'
+import { forgetDeploys, forgetDeployYml } from '@uniweb/build/site'
+import { syncedBackends, normalizeOrigin } from '../utils/site-identity.js'
+
+const c = {
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+  dim: '\x1b[2m',
+  cyan: '\x1b[36m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  red: '\x1b[31m'
+}
+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}`),
+  err: (m) => console.error(`${c.red}✗${c.reset} ${m}`),
+  dim: (m) => console.log(`  ${c.dim}${m}${c.reset}`)
+}
+
+/** "a", "a and b", "a, b and c" */
+function listed(items) {
+  return items.length < 2
+    ? items.join('')
+    : `${items.slice(0, -1).join(', ')} and ${items[items.length - 1]}`
+}
+
+/**
+ * @param {string[]} args
+ * @returns {Promise<{ exitCode: number, forgot?: string[], removed?: string[] }>}
+ */
+export async function forget(args = []) {
+  const badFlag = checkFlags('forget', args)
+  if (badFlag) {
+    say.err(badFlag.message)
+    return { exitCode: 2 }
+  }
+
+  const all = args.includes('--all')
+  const flag = readFlagValue(args, '--backend')
+  if (all && flag) {
+    say.err('Use --backend <url> or --all, not both.')
+    return { exitCode: 2 }
+  }
+
+  const siteDir = await resolveSiteDir(args, 'forget')
+  const known = syncedBackends(siteDir)
+
+  if (all) return forgetAll(siteDir)
+
+  if (!flag) {
+    say.err('Name what to forget: uniweb forget --backend <url>')
+    if (known.length) {
+      say.dim(`This project has synced with: ${known.join(', ')}`)
+    } else {
+      say.dim('This project has not synced with any backend.')
+    }
+    say.dim('For a copied project that should become a new one: uniweb forget --all')
+    return { exitCode: 2 }
+  }
+
+  const origin = normalizeOrigin(flag)
+  if (!origin) {
+    say.err(`Not a URL: ${flag}`)
+    return { exitCode: 2 }
+  }
+
+  // Read before removing, so the report can say what the section held.
+  const state = readBackendState(siteDir, origin)
+  const removed = []
+  if (clearBackend(siteDir, origin)) removed.push('sync.json')
+  if (forgetBackendCache(siteDir, origin)) removed.push('.uniweb/backend-cache.json')
+  let deploys = []
+  try {
+    deploys = await forgetDeploys(siteDir, origin)
+    if (deploys.length) removed.push('deploy.yml')
+  } catch (err) {
+    // Not a stop: the identity above is already forgotten, and a deploy.yml that does
+    // not parse fails every deploy on its own. Rewriting a file we could not read
+    // would be the one thing worse than leaving it.
+    say.warn(`${err.message} — its deploy records were left as they are.`)
+  }
+
+  // Idempotent on purpose: a script calls this after every run, and a second call
+  // (or a call for a backend the push never reached) is not an error.
+  if (!removed.length) {
+    say.info(`Nothing recorded for ${origin} — nothing to forget.`)
+    if (known.length) say.dim(`This project has synced with: ${known.join(', ')}`)
+    return { exitCode: 0, forgot: [origin], removed }
+  }
+
+  say.ok(`Forgot ${c.bold}${origin}${c.reset}`)
+  if (state.site?.uuid) say.dim(`site ${state.site.uuid}`)
+  const counts = [
+    ['records', state.records],
+    ['assets', state.assets]
+  ]
+    .map(([name, map]) => [name, map ? Object.keys(map).length : 0])
+    .filter(([, n]) => n > 0)
+    .map(([name, n]) => `${n} ${name}`)
+  if (counts.length) say.dim(counts.join(' · '))
+  if (deploys.length) {
+    say.dim(`deploy records: ${deploys.join(', ')} (the targets stay)`)
+  }
+  say.dim(`removed from ${listed(removed)}`)
+  say.dim('The site still exists on that backend; this removed only what this project recorded.')
+
+  return { exitCode: 0, forgot: [origin], removed }
+}
+
+/** `--all`: the three files, whole. */
+async function forgetAll(siteDir) {
+  const origins = forgetSyncStore(siteDir)
+  const cache = forgetAllBackendCaches(siteDir)
+  const targets = await forgetDeployYml(siteDir)
+
+  const removed = []
+  if (origins) removed.push('sync.json')
+  if (targets) removed.push('deploy.yml')
+  if (cache) removed.push('.uniweb/backend-cache.json')
+
+  if (!removed.length) {
+    say.info('Nothing recorded — this project has not synced or deployed anywhere.')
+    return { exitCode: 0, forgot: [], removed }
+  }
+
+  say.ok('Forgot every backend and deploy target')
+  if (origins?.length) say.dim(`backends: ${origins.join(', ')}`)
+  if (targets?.length) say.dim(`deploy targets: ${targets.join(', ')}`)
+  say.dim(`removed ${listed(removed)}`)
+  say.dim('Its next push creates a new site. Every existing site is untouched.')
+  // ⛔ The mistake this cannot prevent: running it in the ORIGINAL. That project's
+  // next push would then mint a second site on every backend. Both files are
+  // committed, so the way back is one command — say it now, while it is cheap.
+  say.dim('If this was the original rather than a copy, restore sync.json and deploy.yml from git.')
+
+  return { exitCode: 0, forgot: origins || [], removed }
+}

package/src/commands/i18n.js

@@ -319,7 +319,7 @@ async function runExtract(siteRoot, config, args) {
     const dataDir = join(siteRoot, 'public', DATA_DIR)
     if (!existsSync(dataDir)) {
       if (recordsOnly) {
-        error('No records found. Add entities under entities/ and list them in records.yml.')
+        error('No records found. Every file in records/<schema>/ is a record — add some there.')
         process.exit(1)
       }
       log(`${colors.dim}No records found in public/data/.${colors.reset}`)
@@ -1022,11 +1022,11 @@ async function runAudit(siteRoot, config, args) {
  * Usage:
  *   uniweb i18n init-freeform es pages/about hero
  *   uniweb i18n init-freeform es page-ids/installation intro
- *   uniweb i18n init-freeform es entities/article getting-started
+ *   uniweb i18n init-freeform es records/article getting-started
  */
 async function runInitFreeform(siteRoot, config, args) {
   const locale = args[0]
-  const pathType = args[1] // pages/about, page-ids/installation, entities/article
+  const pathType = args[1] // pages/about, page-ids/installation, records/article
   const sectionId = args[2] // hero, intro, getting-started
 
   if (!locale || !pathType || !sectionId) {
@@ -1035,11 +1035,20 @@ async function runInitFreeform(siteRoot, config, args) {
     log('  uniweb i18n init-freeform es pages/about hero')
     log('  uniweb i18n init-freeform es page-ids/installation intro')
     log(
-      `  uniweb i18n init-freeform es entities/article getting-started${colors.reset}`
+      `  uniweb i18n init-freeform es records/article getting-started${colors.reset}`
     )
     process.exit(1)
   }
 
+  // A path names a page by route, a page by id, or a record by its schema folder —
+  // and nothing else. Said up front: past this point an unknown kind would only
+  // surface as "source content not found", which names the wrong cause.
+  if (!/^(pages|page-ids|records)\//.test(pathType)) {
+    error(`Unknown kind of path: ${pathType}`)
+    log(`${colors.dim}A path starts with pages/, page-ids/ or records/ (a record's schema folder).${colors.reset}`)
+    process.exit(1)
+  }
+
   const localesPath = join(siteRoot, config.localesDir)
   const freeformDir = join(localesPath, 'freeform', locale)
 
@@ -1091,15 +1100,15 @@ async function runInitFreeform(siteRoot, config, args) {
           if (sourceContent) break
         }
       }
-    } else if (pathType.startsWith('entities/')) {
+    } else if (pathType.startsWith('records/')) {
       // ⛔ ADDRESSED BY THE RECORD, matching where the loader reads. The freeform
-      // tree is `entities/<schema dirs>/<slug>.md`; this used to take
+      // tree is `records/<schema dirs>/<slug>.md`; this used to take
       // `collections/<query>` and write a path nothing read — the loader moved
       // and this did not.
       //
       // The record's CONTENT still lives in a query's materialization, so the
       // query that covers this schema is resolved rather than named.
-      const poolDirs = pathType.replace('entities/', '')
+      const poolDirs = pathType.slice('records/'.length)
       const { resolveQueriesConfig, poolDirsForSchema } = await import('@uniweb/build/uwx')
       let queryName = null
       try {
@@ -1509,7 +1518,7 @@ async function runPrune(siteRoot, config, args) {
     // reads one (`freeformSourceIndex`, the build's own index): every path a section's
     // translation is read from — ⛔ until 2026-09-14 only `page-ids/<id>/…` on a page with
     // an `id`, so a route-addressed translation the page rendered was deleted — and only
-    // what the built content can see: never a record's translation (`entities/…`), and
+    // what the built content can see: never a record's translation (`records/…`), and
     // never one for a page whose sections the content does not carry.
     const { validPaths, canJudge } = freeformSourceIndex(siteContent)
 
@@ -1657,7 +1666,7 @@ ${colors.bright}File Structure:${colors.reset}
         .manifest.json       Staleness tracking
         pages/about/hero.md  Translated content for /about page, hero section
         page-ids/install/intro.md  Translated content by page ID
-        entities/article/getting-started.md
+        records/article/getting-started.md
 
 ${colors.bright}Examples:${colors.reset}
   ${colors.dim}# Hash-based workflow${colors.reset}
@@ -1677,7 +1686,7 @@ ${colors.bright}Examples:${colors.reset}
   ${colors.dim}# Free-form workflow (complete section replacement)${colors.reset}
   uniweb i18n init-freeform es pages/about hero
   uniweb i18n init-freeform es page-ids/installation intro
-  uniweb i18n init-freeform es entities/article getting-started
+  uniweb i18n init-freeform es records/article getting-started
   uniweb i18n status --freeform    # Show free-form translation status
   uniweb i18n update-hash es --all-stale  # Update hashes after review
   uniweb i18n move pages/docs/setup pages/getting-started