uniweb 0.84.0 → 0.86.0

package/src/backend/site-sync.js

@@ -34,15 +34,17 @@ import {
   diffSiteUnits,
   describeSiteDiff,
   computeUnitHashes,
-  collectSiteUnits,
   collectUnitUuids,
   collectFolderItemUuids,
   collectQueryUuids,
+  siteItemsByKey,
+  sameServiceRow,
+  heldServices,
   readBackendState,
   updateBackendMap,
   clearBackendSections,
   normalizeBackendOrigin,
-  removeYamlScalar,
+  writeSiteConfig,
   harvestRecordItems,
   storedRecordItems,
   reprintRecordItems,
@@ -118,6 +120,35 @@ async function explainStaleSiteContent({ client, siteDir, localBuffer, uuid }) {
   }
 }
 
+/**
+ * The items a `stale_base` refusal names by key — `stale_keys`, one
+ * `{ section, key }` per clashing item of a Section matched by a field of its own
+ * (`services` and `queries` by `name`) — as one line per Section.
+ *
+ * @param {*} staleKeys - the refusal's `stale_keys`
+ * @returns {string[]}
+ */
+export function describeStaleKeys(staleKeys) {
+  const bySection = new Map()
+  for (const entry of Array.isArray(staleKeys) ? staleKeys : []) {
+    const section = typeof entry?.section === 'string' && entry.section ? entry.section : null
+    if (!section) continue
+    const key = entry?.key
+    // A single-item Section (`settings`) is named by the Section alone, `key: {}`.
+    const single = key && typeof key === 'object' && !Object.keys(key).length
+    const name =
+      key && typeof key === 'object'
+        ? typeof key.name === 'string' ? key.name : Object.values(key).filter((v) => typeof v === 'string').join(' ')
+        : typeof key === 'string' ? key : null
+    if (!single && !name) continue
+    if (!bySection.has(section)) bySection.set(section, [])
+    if (name) bySection.get(section).push(name)
+  }
+  return [...bySection].map(([section, names]) =>
+    `Changed on your site since your last pull — ${section}${names.length ? `: ${names.join(', ')}` : ''}`
+  )
+}
+
 // A unit in the form it is compared in across the two representations: keys sorted,
 // `$`-keys dropped (`$uuid`, `$id` — identity and payload handles, not content).
 const canonicalUnit = (v) =>
@@ -172,42 +203,65 @@ function writtenAsSent(sent, written) {
  * changes it is `pkg != base, host != base` and refused. And while the backend holds
  * units we don't, the entity token stays where it was, so the next push keeps them.
  *
- * With either document missing there is nothing to compare, and the tokens are banked
- * as the backend sent them — the contract is that `finalized[].document` is always
- * there.
- *
+ * ⭐ SINCE 2026-10-07 A HELD VERSION IS ALSO WHAT LETS A PUSH DELETE, so the rule covers
+ * every item, not only units. The site-content entity sends every version this copy
+ * holds, for items present and items the files dropped (`withBaseVersion`), and the
+ * backend deletes only the items a push holds a version for, while the site left them
+ * unchanged [Diego: "yes, apply it to pages too"; kb/framework/plans/services-exchange.md].
+ * A version banked for an item this copy never saw would therefore delete it. The map
+ * returned is the WHOLE set this copy now holds, in every Section but `secrets`
+ * (`siteItemsByKey`), and it replaces the one held before:
+ *
+ *   - an item the backend holds as we sent it → its new version;
+ *   - an item we sent that it kept for someone else → the version we held, for OUR content;
+ *   - an item it holds that we did not send → the version we held, if we had seen it, and
+ *     none if we had not (a unit of it is `foreign`);
+ *   - an item we held that it no longer holds → none: the push deleted it, or the site did.
+ *
+ * ⛔ Until then only units were compared, and every other item's version was banked as
+ * the backend returned it — harmless only while none of them was ever sent.
+ *
+ * A service is compared by its switch and its whole `config` (`sameServiceRow`), every
+ * other item on the keys we sent (`writtenAsSent`).
+ *
+ * With either document missing there is nothing to compare, and with no versions
+ * returned (an older backend) nothing to bank: `itemVersions` is null, and the versions
+ * held stay as they were. The contract is that `finalized[].document` is always there.
+ *
+ * @param {object} p
+ * @param {object|null} p.sent - the site-content document this push sent
+ * @param {object|null} p.written - the backend's post-write copy of it
+ * @param {string|null} [p.version] - the entity's post-write version
+ * @param {Object<string,string>|null} [p.itemVersions] - the post-write version of every item
+ * @param {Object<string,string>} [p.held] - the versions this copy held before the push
  * @returns {{ version: string|null, itemVersions: Object<string,string>|null,
- *   held: string[], kept: string[], foreign: string[] }} `held`: units the backend
+ *   held: string[], kept: string[], foreign: string[] }} `itemVersions`: the versions
+ *   this copy now holds, or null to leave them as they were; `held`: units the backend
  *   holds as we sent them; `kept`: units it kept someone else's content for;
  *   `foreign`: units it holds that we did not send. All paths.
  */
-export function heldTokens({ sent, written, version = null, itemVersions = null }) {
-  if (!sent || !written) return { version, itemVersions, held: [], kept: [], foreign: [] }
-  const ours = collectSiteUnits(sent)
-  const theirs = collectSiteUnits(written)
-  const uuidAt = collectUnitUuids(written)
-  const units = new Set(Object.values(uuidAt))
+export function heldTokens({ sent, written, version = null, itemVersions = null, held: before = {} }) {
+  if (!sent || !written) return { version, itemVersions: null, held: [], kept: [], foreign: [] }
+  const prior = before && typeof before === 'object' ? before : {}
+  const ours = siteItemsByKey(sent)
+  const theirs = siteItemsByKey(written)
+  const same = (key, a, b) => (key.startsWith('services:') ? sameServiceRow(a, b) : writtenAsSent(a, b))
   const held = []
   const kept = []
   const foreign = []
   const items = {}
-  for (const [path, uuid] of Object.entries(uuidAt)) {
-    if (!ours.has(path)) {
-      foreign.push(path)
+  for (const [key, item] of theirs) {
+    if (!item.uuid) continue
+    const unit = key.startsWith('unit:') ? key.slice('unit:'.length) : null
+    const mine = ours.get(key)
+    if (mine && same(key, mine.record, item.record)) {
+      if (unit) held.push(unit)
+      const token = itemVersions?.[item.uuid] ?? prior[item.uuid]
+      if (token) items[item.uuid] = token
       continue
     }
-    if (!writtenAsSent(ours.get(path), theirs.get(path))) {
-      kept.push(path)
-      continue
-    }
-    held.push(path)
-    if (itemVersions?.[uuid]) items[uuid] = itemVersions[uuid]
-  }
-  // A token for an item that is not a unit (a `queries` declaration) is never sent
-  // back — the emit narrows preconditions to units (`withBaseVersion`) — so it is
-  // banked as before: it can neither arm nor disarm anything.
-  for (const [uuid, token] of Object.entries(itemVersions || {})) {
-    if (!units.has(uuid)) items[uuid] = token
+    if (unit) (mine ? kept : foreign).push(unit)
+    if (prior[item.uuid]) items[item.uuid] = prior[item.uuid]
   }
   return {
     version: foreign.length ? null : version,
@@ -218,6 +272,26 @@ export function heldTokens({ sent, written, version = null, itemVersions = null
   }
 }
 
+/**
+ * The versions a pull leaves this copy holding: one for every site-content item the
+ * pulled document carries, in every Section but `secrets` (`siteItemsByKey`) — the
+ * whole set, replacing what was held. A pull is how a copy sees the site, so an item
+ * the site no longer has is forgotten, and the next push does not send its version.
+ *
+ * @param {object|null} doc - the pulled site-content document
+ * @param {Object<string,string>|null} itemVersions - the pull manifest's `item_versions`
+ * @returns {Object<string,string>|null} null when there is nothing to bank (no document, or
+ *   an older backend that sends no item versions)
+ */
+export function pulledItemVersions(doc, itemVersions) {
+  if (!doc || !itemVersions || typeof itemVersions !== 'object') return null
+  const out = {}
+  for (const { uuid } of siteItemsByKey(doc).values()) {
+    if (uuid && typeof itemVersions[uuid] === 'string') out[uuid] = itemVersions[uuid]
+  }
+  return out
+}
+
 // The files a unit projects to, under the site's own roots — `site.yml::paths` can
 // relocate `pages` and `layout`. `site.yml` stands for the `info` unit, which projects
 // to three files.
@@ -378,7 +452,9 @@ export function keepModels(siteDir, backend, models) {
 // ⭐ **Everything here is regenerable and losing it never produces a WRONG result** —
 // only a slower transfer or a round trip. That is the membership test; anything
 // failing it belongs in `sync.json` (which is where the uuid maps went on
-// 2026-09-20 — see `readItemUuids` below).
+// 2026-09-20 — see `readItemUuids` below). ⚠️ One exception since 2026-10-07, and it
+// is said where it lives: the item versions are what lets a push delete, so without
+// them a dropped page is kept until the next pull (`readItemBaseVersions`).
 //
 // ⚠️ It was `sync-cache.json` and its header called it "a pure wire-efficiency
 // cache — NOT identity, the minted `$uuid` lives in the source files". That was
@@ -495,7 +571,7 @@ const readMap = (siteDir, backend, key) => {
  *     not change** — a partial site, published successfully, with nothing to
  *     indicate it.
  *
- * The guidance is `uniweb forget --backend <url>` now, which removes the uuid and the
+ * The guidance is `uniweb forget --server <url>` now, which removes the uuid and the
  * maps together, so following it no longer leads here.
  *
  * Call this BEFORE `ensureSiteExists`, which mints a uuid and would otherwise make
@@ -642,7 +718,7 @@ export function dropSiteBoundValues(siteDir, backend) {
   if (
     y.preview !== undefined &&
     !isAuthoredPreview(y.preview) &&
-    removeYamlScalar(file, 'preview')
+    writeSiteConfig(siteDir, { preview: null }) === 'updated'
   ) {
     dropped.push('preview')
   }
@@ -771,20 +847,35 @@ export function readBaseVersions(siteDir, backend) {
 }
 
 /**
- * Per-ITEM staleness tokens: `{ <record $uuid>: <opaque version> }`.
+ * Per-ITEM staleness tokens: `{ <item $uuid>: <opaque version> }` — one for every item
+ * of the site-content entity this copy has seen.
  *
  * The entity token gates the whole document, so a stale base on any one record
  * refuses the entire push — which fires on the common case of two people editing
- * different sections and teaches them to reach for `--force`. These gate per record
+ * different sections and teaches them to reach for `--force`. These gate per item
  * instead. Same contract as the entity token: opaque, cached, echoed, never parsed.
  *
- * Merged rather than replaced: a push carries only CHANGED entities, so a response
- * reports tokens for a subset of the site. Replacing would drop the tokens of every
- * record that wasn't in this package and silently degrade those to ungated.
+ * ⭐ AND THEY ARE WHAT LETS A PUSH DELETE (2026-10-07): the backend deletes only the
+ * items a push holds a version for, so every one held is sent, present or dropped
+ * (`withBaseVersion`). Hence the set is REPLACED, never merged — by a pull
+ * (`pulledItemVersions`) and by a push of the site-content lane (`heldTokens`) — and
+ * holds only items this copy has seen. ⚠️ The one thing losing this cache now costs that
+ * is not a round trip: until the next pull, a page or section the files dropped is kept
+ * on the site rather than deleted, since there is no version to send for it.
+ * ⛔ *It was merged until then, across both lanes, for a push that sent only units.*
  */
 export function readItemBaseVersions(siteDir, backend) {
   return readMap(siteDir, backend, 'itemBaseVersions')
 }
+/**
+ * Replace the item versions this copy holds — a push's (`heldTokens`) or a pull's
+ * (`pulledItemVersions`) whole set. ⛔ Not a merge: an item that left the set must
+ * leave the map, or its version is sent again and asks the backend to delete it.
+ */
+export function writeItemBaseVersions(siteDir, backend, versions) {
+  if (!versions || typeof versions !== 'object') return
+  updateSyncCache(siteDir, backend, { itemBaseVersions: { ...versions } })
+}
 export function mergeItemBaseVersions(siteDir, backend, versions) {
   if (!versions || !Object.keys(versions).length) return
   // ⛔ The read names the backend. Without it the read keyed nothing, came back `{}`,
@@ -1811,7 +1902,7 @@ export async function pushSyncPackages({
     } catch (err) {
       error(describeRequestError(err, client.origin))
       if (!(err instanceof WorkspaceMismatchError))
-        note('Is that the backend you meant? Switch with: uniweb login --backend <url>')
+        note('Is that the backend you meant? Switch with: uniweb login --server <url>')
       return null
     }
     if (!res.ok) {
@@ -1933,7 +2024,11 @@ export async function pushSyncPackages({
         // for choosing between pulling and forcing.
         const detail = await explainStale()
         for (const line of detail) note(line)
-        if (!detail.length) {
+        // ⭐ Items no file path names — a service, a query — come named by their Section's
+        // key (`stale_keys`, `{ section, key: { name } }`), so say them by name.
+        const keyed = describeStaleKeys(problem.stale_keys)
+        for (const line of keyed) note(line)
+        if (!detail.length && !keyed.length) {
           const stale = Array.isArray(problem.stale_entities)
             ? problem.stale_entities
             : []
@@ -1972,7 +2067,7 @@ export async function pushSyncPackages({
       error(`${label} push rejected: HTTP ${res.status} ${res.statusText}`)
       if (res.status === 401 || res.status === 403) {
         note(
-          "Credentials weren't accepted — log in again (`uniweb login --backend <url>`), or check UNIWEB_TOKEN."
+          "Credentials weren't accepted — log in again (`uniweb login --server <url>`), or check UNIWEB_TOKEN."
         )
       } else if (res.status === 404 && boundUuid) {
         // The clone is bound to a site the backend does not have. There is no CLI
@@ -2002,10 +2097,10 @@ export async function pushSyncPackages({
           'Two causes. Check the cheap one first: is this the backend the site lives on?'
         )
         note(
-          `  wrong backend  →  uniweb login --backend <the right one>   (nothing is lost)`
+          `  wrong backend  →  uniweb login --server <the right one>   (nothing is lost)`
         )
         note(
-          `  deleted there  →  uniweb forget --backend ${client.origin}, then push again: it creates a NEW site`
+          `  deleted there  →  uniweb forget --server ${client.origin}, then push again: it creates a NEW site`
         )
         note('Deleting this folder removes only your local copy, either way.')
       } else if (problem?.reason === 'template_records_not_copyable' && Array.isArray(problem.records)) {
@@ -2079,9 +2174,11 @@ export async function pushSyncPackages({
   // otherwise the next attempt would re-send lane 1 with a base the backend has
   // already moved past, and refuse a push the user just made.
   const newVersions = {}
-  // Per-item tokens from the SAME response. Keyed by record `$uuid` and flat
-  // across entities (the cache is a single map), unlike `newVersions`, which is
-  // keyed by entity uuid.
+  // Per-item tokens from the SAME response — the site-content entity's, keyed by item
+  // `$uuid`: the whole set this copy now holds (`heldTokens`), which replaces the one
+  // it held. Null until that lane lands, which leaves the held set as it was.
+  // ⛔ The records lane's are not kept: that lane is gated by its entity version, and
+  // until 2026-10-07 they were merged into the same map, which was sent for nothing.
   //
   // ⛔ Both grains must be re-armed from the push, for one reason: a push writes,
   // so every token this clone holds for a record it just changed is now stale. Read
@@ -2094,22 +2191,19 @@ export async function pushSyncPackages({
   // exact shape one grain up (see delivery-lane.md "Both feed directions are
   // load-bearing"); the item grain had the same hole until backend `d7e46335`
   // started echoing `item_versions` here.
-  const newItemVersions = {}
+  let heldItemVersions = null
   const harvest = (finalized) => {
     for (const f of finalized || []) {
+      // NOT gated on `changed`: the backend pins "zero-write ⇒ version unmoved", so a
+      // no-op resubmit hands back the value we already hold. (The site-content lane
+      // filters first, `harvestSiteContent`.)
       if (f.uuid && f.version) newVersions[f.uuid] = f.version
-      // NOT gated on `changed` — same rule as the entity token: the backend pins
-      // "zero-write ⇒ version unmoved", so a no-op resubmit hands back the value we
-      // already hold. (The site-content lane filters first, `harvestSiteContent`.)
-      // An older backend omits the field entirely, which leaves the cached tokens
-      // alone and degrades to the entity grain, exactly as before.
-      if (f.itemVersions) Object.assign(newItemVersions, f.itemVersions)
     }
   }
   // Both grains land together, at every point the old code banked the entity one.
   const mergeHarvested = () => {
     mergeBaseVersions(siteDir, client.origin, newVersions)
-    mergeItemBaseVersions(siteDir, client.origin, newItemVersions)
+    if (heldItemVersions) writeItemBaseVersions(siteDir, client.origin, heldItemVersions)
   }
   // ⛔ The site-content lane banks only the tokens for content this copy holds — the
   // document we sent against the one the backend stored (`heldTokens`, and the two
@@ -2124,9 +2218,11 @@ export async function pushSyncPackages({
         sent: sentSiteDoc,
         written: f.document,
         version: f.version,
-        itemVersions: f.itemVersions
+        itemVersions: f.itemVersions,
+        held: heldItemVersions ?? readItemBaseVersions(siteDir, client.origin)
       })
-      harvest([{ ...f, version: held.version, itemVersions: held.itemVersions }])
+      harvest([{ ...f, version: held.version }])
+      if (held.itemVersions) heldItemVersions = held.itemVersions
       heldUnits.push(...held.held)
       notHeld.kept.push(...held.kept)
       notHeld.foreign.push(...held.foreign)
@@ -2153,6 +2249,17 @@ export async function pushSyncPackages({
     if (siteFinalizedDoc) {
       const recordIds = collectQueryUuids(siteFinalizedDoc)
       if (Object.keys(recordIds).length) writeQueryUuids(siteDir, client.origin, recordIds)
+      // ⭐ THE SERVICES THIS COPY NOW HOLDS, `{ name: $uuid }`: those the push stated and
+      // those held before, as the site returned them (`heldServices`). A service added on
+      // the site since this copy's last pull is left out — held, the next push would state
+      // it off, switching off a service nobody here has seen. Replaced, not merged.
+      updateBackendState(siteDir, client.origin, {
+        services: heldServices({
+          written: siteFinalizedDoc.services,
+          sent: Array.isArray(sentSiteDoc?.services) ? sentSiteDoc.services : [],
+          prior: readBackendState(siteDir, client.origin).services
+        })
+      })
     }
     // Re-base the page attribution: our emitted document and the backend's post-write
     // copy of it are the two sides' new agreed state.

package/src/commands/build.js

@@ -138,10 +138,11 @@ function detectProjectType(projectDir) {
  */
 function runCommand(command, args, cwd) {
   return new Promise((resolve, reject) => {
+    // No shell: the command is node and a script path, which needs none — and a shell
+    // splits a path with a space in it. (Node warns DEP0190 on args passed with one.)
     const proc = spawn(command, args, {
       cwd,
-      stdio: 'inherit',
-      shell: true
+      stdio: 'inherit'
     })
 
     proc.on('close', (code) => {
@@ -246,6 +247,9 @@ async function buildFoundation(projectDir, options = {}) {
   log('')
   log(`${colors.green}${colors.bright}Build complete!${colors.reset}`)
 
+  // The next step is for someone who ran `uniweb build` — not for a push or publish
+  // that builds the foundation as one of its own steps (UNIWEB_BUILD_STEP).
+  if (process.env.UNIWEB_BUILD_STEP) return
   log('')
   log(`${colors.bright}Share with clients:${colors.reset}`)
   log(

package/src/commands/clone.js

@@ -44,7 +44,7 @@
  *                                        another workspace stops it.
  *
  * Backend: via BackendClient (the site-content pull lane). Origin from
- *   UNIWEB_REGISTER_URL  >  the local default (internal dev overrides;
+ *   UNIWEB_SERVER  >  the local default (internal dev overrides;
  *   not the user-facing path — `uniweb login` determines the origin).
  * Auth:  UNIWEB_TOKEN  >  the stored session  >  `uniweb login`. No `--token` (retired
  *   from the backend commands 2026-09-21).

package/src/commands/deploy.js

@@ -195,8 +195,8 @@ export async function deploy(args = []) {
     // 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'
+    const aimedBy = process.env.UNIWEB_SERVER
+      ? 'UNIWEB_SERVER'
       : loggedInOrigin()
         ? 'the backend you are logged in to'
         : 'the default backend — you are not logged in'
@@ -215,7 +215,7 @@ export async function deploy(args = []) {
         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}`)
+        say.dim(`To publish there, log in to it first: uniweb login --server ${targetBackend}`)
         process.exit(1)
       }
       say.dim(

package/src/commands/doctor.js

@@ -19,6 +19,7 @@ import {
 } from '@uniweb/build'
 import { loadDeployYml, AGENTS_KEYS } from '@uniweb/build/site'
 import { listAdapters } from '@uniweb/build/hosts'
+import { RUNTIME_KEYS } from '@uniweb/build/uwx'
 import { getCliVersion } from '../versions.js'
 import { readAgentsVersion } from '../utils/agents-stamp.js'
 import { writeJsonPreservingStyle } from '../utils/json-file.js'
@@ -388,17 +389,12 @@ function nearestKnownKey(input, known) {
 }
 
 /**
- * The options `tracking:` actually has a reader.
- *
- * ⚠️ **Kept here rather than imported, because nothing at runtime enumerates
- * them** — `wireTracker` reads named properties off the resolved declaration, it
- * does not iterate a list. So there is no existing array to import and this
- * duplicates nothing. It does mean the list can drift: the readers are
- * `runtime/src/wire-foundation.js::wireTracker` (`consent`, `scripts`, `debug`)
- * and `core/src/services.js::readEndpoint` (`endpoint`). Add a key there, add it
- * here.
+ * The options `services.tracking` has a reader for — the build's list, which also
+ * decides what a push sends the host as its settings (`RUNTIME_KEYS`, `@uniweb/build`).
+ * ⛔ *Until 2026-10-06 doctor kept a copy of its own, which had drifted: it lacked
+ * `emit` and `flushIntervalMs`, which `wireTracker` reads.*
  */
-const TRACKING_KEYS = ['endpoint', 'consent', 'scripts', 'debug']
+const TRACKING_KEYS = RUNTIME_KEYS.tracking
 
 /**
  * Spellings that read as an ATTEMPT to require consent but do not require it.
@@ -414,10 +410,10 @@ const TRACKING_KEYS = ['endpoint', 'consent', 'scripts', 'debug']
 const CONSENT_NEAR_MISSES = new Set(['require', 'requires', 'required.', 'true', 'yes', 'on', '1'])
 
 /**
- * `tracking:` — flag the keys and values that are carried and never acted on.
+ * `services.tracking` — flag the keys and values that are carried and never acted on.
  *
- * The block is forwarded to the host as opaque data and resolved at render, so
- * nothing downstream rejects a mistake in it. Every error here therefore fails
+ * A key the site's tracking does not read goes to the host as a setting, and the
+ * rest is resolved at render, so nothing downstream rejects a mistake in it. Every error here therefore fails
  * the same way: **silently, at a visitor's browser, as an absence** — which is
  * also exactly what a site that configured nothing looks like. There is no
  * symptom to notice and nothing to grep for.
@@ -425,8 +421,8 @@ const CONSENT_NEAR_MISSES = new Set(['require', 'requires', 'required.', 'true',
  * ⭐ That is the whole argument for checking it at `doctor` time: it is the only
  * moment in the chain where a person who can fix it is looking at it.
  *
- * A bare `tracking: <url>` string is the documented shorthand and carries no
- * options — there is nothing in it to be wrong.
+ * An address, `true` or `false` carries no options — there is nothing in it to be
+ * wrong.
  */
 /**
  * `uniweb doctor` — is `package.json` behind what the build derived?
@@ -806,8 +802,8 @@ export function checkUngatedServiceControls({ foundationName, folderName, srcDir
 }
 
 export function checkTrackingBlock({ siteName, siteYml, issues }) {
-  const tracking = siteYml?.tracking
-  if (tracking === undefined || tracking === null) return
+  const tracking = siteYml?.services?.tracking
+  if (tracking === undefined || tracking === null || typeof tracking === 'boolean') return
   if (typeof tracking === 'string') return
 
   if (typeof tracking !== 'object' || Array.isArray(tracking)) {
@@ -816,9 +812,9 @@ export function checkTrackingBlock({ siteName, siteYml, issues }) {
       id,
       type: 'warning',
       site: siteName,
-      message: `site.yml: \`tracking:\` should be an endpoint string, or a map of options`
+      message: `site.yml: \`services.tracking\` should be true, false, an address, or a map of options`
     })
-    warn(`[${id}] ${siteName}: \`tracking:\` is neither an endpoint string nor a map of options.`)
+    warn(`[${id}] ${siteName}: \`services.tracking\` is neither true, false, an address nor a map of options.`)
     return
   }
 
@@ -830,10 +826,10 @@ export function checkTrackingBlock({ siteName, siteYml, issues }) {
       id,
       type: 'warning',
       site: siteName,
-      message: `site.yml: \`tracking:\` has ${unknown.length === 1 ? 'an unknown key' : 'unknown keys'}: ${unknown.join(', ')}`
+      message: `site.yml: \`services.tracking\` has ${unknown.length === 1 ? 'an unknown key' : 'unknown keys'}: ${unknown.join(', ')}`
     })
     warn(
-      `[${id}] ${siteName}: \`tracking:\` ${unknown.length === 1 ? 'key' : 'keys'} ${unknown
+      `[${id}] ${siteName}: \`services.tracking\` ${unknown.length === 1 ? 'key' : 'keys'} ${unknown
         .map((k) => `'${k}'`)
         .join(', ')} ${unknown.length === 1 ? 'is' : 'are'} not recognized.`
     )
@@ -842,7 +838,7 @@ export function checkTrackingBlock({ siteName, siteYml, issues }) {
       if (near) log(`    ${colors.dim}'${key}' — did you mean ${colors.reset}${colors.green}${near}${colors.reset}${colors.dim}?${colors.reset}`)
     }
     log(
-      `    ${colors.dim}Carried to the host as opaque data and never read. Known: ${TRACKING_KEYS.join(', ')}.${colors.reset}`
+      `    ${colors.dim}Not an option the site's tracking reads — sent to your host as a setting. Known: ${TRACKING_KEYS.join(', ')}.${colors.reset}`
     )
   }
 
@@ -869,9 +865,9 @@ export function checkTrackingBlock({ siteName, siteYml, issues }) {
         id,
         type: 'warning',
         site: siteName,
-        message: `site.yml: \`tracking.consent:\` is ${shown} — only the exact value \`required\` turns the gate on`
+        message: `site.yml: \`services.tracking.consent\` is ${shown} — only the exact value \`required\` turns the gate on`
       })
-      warn(`[${id}] ${siteName}: \`tracking.consent:\` is ${shown}; the gate is OFF.`)
+      warn(`[${id}] ${siteName}: \`services.tracking.consent\` is ${shown}; the gate is OFF.`)
       log(
         `    ${colors.dim}Only \`consent: required\` holds events until a visitor answers. Anything else${colors.reset}`
       )
@@ -894,10 +890,10 @@ export function checkTrackingBlock({ siteName, siteYml, issues }) {
         id,
         type: 'warning',
         site: siteName,
-        message: `site.yml: \`tracking.scripts:\` has ${bad.length} ${bad.length === 1 ? 'entry' : 'entries'} with no URL`
+        message: `site.yml: \`services.tracking.scripts\` has ${bad.length} ${bad.length === 1 ? 'entry' : 'entries'} with no URL`
       })
       warn(
-        `[${id}] ${siteName}: ${bad.length} \`tracking.scripts:\` ${bad.length === 1 ? 'entry has' : 'entries have'} no URL and will not load.`
+        `[${id}] ${siteName}: ${bad.length} \`services.tracking.scripts\` ${bad.length === 1 ? 'entry has' : 'entries have'} no URL and will not load.`
       )
       log(
         `    ${colors.dim}An entry is a URL, or an object with a \`src\`. Anything else is dropped silently.${colors.reset}`
@@ -927,19 +923,19 @@ function editDistance(a, b) {
 /**
  * A site whose content declares a form needs somewhere to send it.
  *
- * Two things can supply that: `submit:` in site.yml, or the host at serve time.
- * Doctor can only see the first — so it warns only when *nothing* could
- * plausibly supply one: no declaration, and no deploy target that would put a
- * host in the picture. On a site bound to a host, having no `submit:` is the
- * correct configuration, and warning there would nag exactly the people who got
- * it right.
+ * Two things can supply that: `services.submit` in site.yml — asking the host for
+ * form handling, or naming the site's own — or the host at serve time. Doctor can
+ * only see the first — so it warns only when *nothing* could plausibly supply one:
+ * no entry, and no deploy target that would put a host in the picture. On a site
+ * bound to a host, an absent entry can be the correct configuration, and warning
+ * there would nag exactly the people who got it right.
  *
  * The consequence of being wrong in the other direction is what justifies the
- * check at all: a form with no destination renders disabled, which is visible
- * on the page but easy to ship without noticing.
+ * check at all: a form with no destination is not drawn, which is easy to ship
+ * without noticing.
  */
 export async function checkFormSubmitTarget({ sitePath, siteName, siteYml, issues }) {
-  if (siteYml?.submit) return
+  if (siteYml?.services?.submit) return
 
   const forms = findFormContent(sitePath, siteYml)
   if (forms.length === 0) return
@@ -966,7 +962,7 @@ export async function checkFormSubmitTarget({ sitePath, siteName, siteYml, issue
   for (const f of forms.slice(0, 5)) log(`    • ${f}`)
   if (n > 5) log(`    ${colors.dim}…and ${n - 5} more${colors.reset}`)
   log(
-    `    Set ${colors.green}submit${colors.reset} in site.yml if you are providing the endpoint.`
+    `    Ask your host for form handling — ${colors.green}services: { submit: true }${colors.reset} — or name your own: ${colors.green}services: { submit: https://… }${colors.reset}.`
   )
   log(
     `    ${colors.dim}A host that handles submissions supplies one itself — this check is skipped once a deploy target is configured.${colors.reset}`

package/src/commands/forget.js

@@ -2,10 +2,10 @@
  * `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 --server <url>   one backend
  *   uniweb forget --all             everything — for a COPY that is to become a new project
  *
- * ## `--backend <url>`
+ * ## `--server <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;
@@ -43,12 +43,12 @@
  * ## 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`)
+ * removes the traces of it without discarding the rest of the project (`--server`)
  * — 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
+ * creates a second site there, so the verb makes you name it — `--server` is
  * required even when the project has synced with only one.
  */
 
@@ -96,9 +96,9 @@ export async function forget(args = []) {
   }
 
   const all = args.includes('--all')
-  const flag = readFlagValue(args, '--backend')
+  const flag = readFlagValue(args, '--server')
   if (all && flag) {
-    say.err('Use --backend <url> or --all, not both.')
+    say.err('Use --server <url> or --all, not both.')
     return { exitCode: 2 }
   }
 
@@ -108,7 +108,7 @@ export async function forget(args = []) {
   if (all) return forgetAll(siteDir)
 
   if (!flag) {
-    say.err('Name what to forget: uniweb forget --backend <url>')
+    say.err('Name what to forget: uniweb forget --server <url>')
     if (known.length) {
       say.dim(`This project has synced with: ${known.join(', ')}`)
     } else {