uniweb 1.20.4 → 1.21.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "1.20.4",
+  "version": "1.21.1",
   "description": "Create structured Vite + React sites with content/code separation",
   "type": "module",
   "bin": {
@@ -42,14 +42,14 @@
     "prompts": "^2.4.2",
     "tar": "^7.5.21",
     "@uniweb/content-writer": "~1.3.1",
-    "@uniweb/core": "~1.4.7",
     "@uniweb/schemas": "~1.6.5",
+    "@uniweb/core": "~1.4.7",
     "@uniweb/semantic-parser": "~1.13.0"
   },
   "peerDependencies": {
-    "@uniweb/build": "~1.10.2",
-    "@uniweb/content-reader": "~1.5.7",
-    "@uniweb/semantic-parser": "~1.13.0"
+    "@uniweb/build": "~1.10.3",
+    "@uniweb/semantic-parser": "~1.13.0",
+    "@uniweb/content-reader": "~1.5.7"
   },
   "peerDependenciesMeta": {
     "@uniweb/build": {

package/partials/agents.md

@@ -33,15 +33,18 @@ You're building a *system* of section types, not individual pages. That's what m
 | Existing project, component task (new section type, restyle) | **Part 2**, then Part 4 |
 | Porting a design from React / Next / a generated site | **Part 1**, then Part 5 → *Migrating* |
 
-### Three commands that replace guessing
+### Four commands that replace guessing
 
 ```bash
+uniweb status                # what changed in the app, in git and in Uniweb — and what to run
 uniweb inspect <path>        # print the parsed content shape of a section or page
 uniweb <command> --help      # exact flags, always current — no side effects
 uniweb doctor                # diagnose project configuration (--fix to repair)
 ```
 
-`uniweb inspect` is the important one. Every parse rule in Part 3 is faster to *confirm* than to re-derive, and re-deriving from memory is where agents go wrong. Don't predict the shape — print it.
+`uniweb inspect` is the important one for content. Every parse rule in Part 3 is faster to *confirm* than to re-derive, and re-deriving from memory is where agents go wrong. Don't predict the shape — print it.
+
+`uniweb status` is the one for a project other people edit. A site in the Uniweb app can change there at any time, teammates push to git, and Uniweb releases often. Run it when you begin, when you come back to the project, before you push, publish or deploy, and after a command refuses: it changes nothing, opens with what the site is — synced where, live where — and ends with the commands to run, in order (`--json` for a script).
 
 ### The four silent failures
 
@@ -189,6 +192,8 @@ The rest of this guide explains how Uniweb works. This part is what to do *first
 
 ### 1. Orient — what kind of workspace is this?
 
+**Run `uniweb status` first.** It says whether the site changed in the app since this copy last synced, whether git or Uniweb has something newer, and what to run about each — before you edit something someone else just changed.
+
 **There is no single layout. Read `pnpm-workspace.yaml` first** — its `packages:` globs name the shape in one glance:
 
 | Globs | Layout | What it implies |
@@ -2818,7 +2823,8 @@ uniweb publish                    # Ship to Uniweb hosting, foundation included
 uniweb add ci --target foundation # Publish a foundation for free at permanent versioned URLs
                                   # (GitHub Pages → foundations/<name>/<version>/entry.js)
 
-uniweb push / pull / clone / status   # Git-style content sync with the Uniweb backend
+uniweb status                         # What changed in the app, in git and in Uniweb — and what to run
+uniweb push / pull / clone            # Git-style content sync with the Uniweb backend
 uniweb refresh / sync                 # Catch up (git + backend, never pushes) / catch up, then push
 uniweb login --org @acme              # The workspace you work in — new sites are created there (see below)
 uniweb register [--scope @scope]      # Register a foundation + its data schemas to the registry
@@ -2830,7 +2836,7 @@ uniweb rename <foundation|site|extension> <old> <new>   # Rename across the whol
 uniweb i18n extract / init / sync / status / audit      # Translation workflow (build first)
 uniweb i18n init-freeform / update-hash / move / rename / prune --freeform
 
-uniweb -v                         # Installed CLI version — and whether a newer one exists
+uniweb -v                         # CLI version — only a global install also says whether a newer one exists
 uniweb doctor                     # Diagnose project configuration (--fix to auto-repair)
 uniweb validate                   # Check file-based data against declared schemas (fails on a violation; --lax)
 npx uniweb@latest update          # Align @uniweb/* deps + AGENTS.md (--dry-run, --yes)
@@ -2858,6 +2864,14 @@ uniweb <command> --help           # Per-command flags — no side effects. Prefe
 
 Foundations have their own free path too: `uniweb add ci --target foundation` publishes to permanent versioned URLs on GitHub Pages.
 
+**Three facts about a site, and they are independent — `uniweb status` opens with all three:**
+
+- **Synced** — the project has a site on a backend, so authors can edit it in the Uniweb app. `sync.json` names it on each backend: `https://uniweb.app` by default, or a server of your own (`uniweb login --server <url>`).
+- **Published** — that backend serves it live: Uniweb Cloud, on `https://uniweb.app`. A published site is a synced site; a synced site need not be published — it can sit in the app as a draft.
+- **Deployed** — a build of it is on another host, such as GitHub Pages or S3: by CI on every push (`uniweb add ci`), or by hand (`uniweb deploy`). `deploy.yml` lists those hosts, and a bare `uniweb deploy` goes to its default target.
+
+A site can be in more than one place — usually while it moves from one host to another. Before you ship, read where it is: `publish` makes a change live on Uniweb Cloud, `git push` on a CI-deployed host, and `uniweb deploy --target <name>` on one deployed by hand — and each of these is the person's to decide. `uniweb status` also lists the services the live site has (`services:` in `site.yml` is the request, never proof of what the site has).
+
 ### Uniweb Cloud and the two-sided workflow
 
 `uniweb publish` ships to Uniweb Cloud, and it's worth understanding what that buys, because it isn't only hosting — it's how a team of technical and non-technical people works on one site.
@@ -2896,6 +2910,8 @@ Foundations have their own free path too: `uniweb add ci --target foundation` pu
 - **Git is the reviewed, durable record** — you `pull` content back, read it with `git diff`, and commit.
 - **Authors never push or pull.** For them, content simply updates, whether the change came from another author or from a developer's CLI.
 
+**Working on a site others edit — run `uniweb status` when you begin, when you come back to it, before you push, publish or deploy, and after any refusal.** It reads the backend without taking anything: what changed there since this copy last synced, file by file — as `uniweb pull` would write it, translations and records included; what you hold that it lacks; where the site is live, and what services it has; who has it open in the app right now, and on which file. Then it lists the commands to run, in an order that works from the top — `uniweb pull` before the push it would otherwise refuse. Three habits go with it: take what changed (`pull`, or `refresh`) before you edit; never `--force` past a refusal; and when someone has a page open in the app, tell the person before you change that page. A step marked *ask the person first* — going live, which may cost money — is theirs to decide.
+
 **Nobody's work is overwritten without asking.** `uniweb push` is refused if the site changed on the backend since your last pull — usually an author editing in the app — and reports what changed; nothing is written. Edits to different sections never collide. **In a git repository `uniweb pull` merges, like `git pull`:** it commits the backend's content (*"The site's content on …"*) and merges that commit into your branch, against the last state of the site your history shares with the backend. Your work, committed or not, and a teammate's arriving through git are kept; a file the backend never had is never deleted; changes to different parts of a file combine silently; and only a genuine overlap leaves conflict markers and a non-zero exit — so `uniweb pull && uniweb push` never ships markers. Settle a conflict as in any merge, then `git commit`; where your uncommitted changes overlap what the pull brought, the markers are theirs — settle them and `git add` each file, then `git stash drop` (git keeps them in the stash too). A push or publish is refused while a file under the site is in conflict. **In a git repository a push sends what you have committed:** with the site's content not committed it is refused before anything is sent, naming the files — commit them, or run `uniweb push --commit -m "…"` (it commits the site's content only, and leaves anything else staged as it is); `publish` and `sync` take `--commit` too. That commit is where the next pull merges from, which is how the pull tells your changes from the backend's. What the push writes back into the files — the ids the backend assigned — it commits itself, as `uniweb`. When the backend has nothing new, a pull says so and lists the files where yours hold changes it lacks. `uniweb refresh` runs `git pull` first, then the same pull. A push is also refused when your branch does not hold what this copy last took from the backend — after `git merge --abort`, or in a fresh clone that has not pulled — so pull, then push. Outside git — which includes a folder the repository around it ignores, such as a scratch directory — `uniweb pull` takes the backend's version over your files, asking first. `--force` is the deliberate overwrite (on `push` it replaces the backend's changes, on `pull` it discards yours); don't use it to get past a refusal. `uniweb sync` is `refresh` then `push`; neither publishes.
 
 **`sync.json` says which site this is, on each backend.** The first push to a backend records what that backend assigned — the site's id and owner, the ids of its records and uploaded files — in `sync.json` beside `site.yml`. In a git repository the push commits it; never edit it. **To make a new site from a copy of a project, run `uniweb forget --all` in the copy before its first push** — the copy carries the original's `sync.json`, so otherwise its push updates the original's site. When two projects in one workspace hold the same site, a push or publish from either is refused until that is done. `uniweb forget --server <url>` removes just one backend's records, such as a scratch server's. A record file's `$uuid` is its own id and stays in both cases. **`push`, `pull` and `publish` go to the backend you are logged in to** — the last `uniweb login --server <url>` — and never to one you are not logged in to. A bare `uniweb login` logs in to https://uniweb.app; for any other backend, name it — logging in is how you switch, and the backend commands take no `--server` of their own. When the project has no site on that backend but has one elsewhere, a push says so before creating a new one.
@@ -2942,12 +2958,15 @@ Either side can publish. Nothing about this changes how you build: the same foun
 ### Staying current
 
 ```bash
-uniweb -v                  # installed CLI version, and whether a newer one is available
+uniweb status              # among its checks: whether a newer Uniweb is out than this project runs
+uniweb -v                  # CLI version — only a global install also says whether a newer one exists
 uniweb doctor              # report drift in this project, changing nothing
 npx uniweb@latest update --dry-run   # preview exactly what update would change
 npx uniweb@latest update             # apply: align @uniweb/* deps AND refresh AGENTS.md
 ```
 
+When `status` names a newer release, take it: `npx uniweb@latest update`, then build and look at the pages. Releases rarely ask anything of a project.
+
 **`npx uniweb@latest update` is the command for bringing a project up to date.** It aligns the project's `@uniweb/*` dependencies *and* this AGENTS.md to the version matrix of the CLI that runs it. Deps and documentation move together — that's the whole point of the verb.
 
 **What the version numbers mean.** A patch brings fixes and features; a minor version is where Uniweb puts breaking changes — `update` lists each package that crosses one, so build and check the project before shipping — and a major is kept for something really big. Dependencies are written as tilde ranges (`~1.0.1`), so `pnpm install` and `pnpm update` never cross a minor on their own. The move from 0.x to 1.0.1 asks nothing of a project that was on the latest 0.x versions — 1.0.1 carried every package's 0.x line over — though `update` marks each package `major · BREAKING`.

package/partials/start.md

@@ -60,6 +60,19 @@ which parts your task needs.
 
 Uniweb's mistakes are quiet: an unknown section type or param builds fine and renders
 wrong. AGENTS.md says how to check.
+{{#if project}}
+
+## Check what changed
+
+```bash
+npx uniweb status
+```
+
+The site may have been edited in the Uniweb app since this copy last synced, by the
+person or someone they work with, and Uniweb may have a newer release. `status` says so,
+changes nothing, and ends with the commands to run, in order. A step it marks "ask the
+person first" is theirs to decide.
+{{/if}}
 
 ## Install and run
 
@@ -103,6 +116,10 @@ If the site needs paying for, `publish` prints an address instead of going live.
 it for the person, tell them it's where they pay, and run `publish` again once they're
 done.
 
+Once the site is in the app, it can be edited there at any time. Before you change it
+again, and before each push, run `npx uniweb status`: it says what changed in the app
+since your last push or pull, and what to run.
+
 ## More
 
 - Documentation index: https://uniweb.io/llms.txt

package/src/backend/app-changes.js

@@ -0,0 +1,159 @@
+/**
+ * What changed on the backend since this copy last synced — READ, never taken.
+ *
+ * ⚠️ THE SECOND ANSWER. In a repository `uniweb status` asks the pull itself
+ * (`commands/pull.js::probePull`), which names every file a pull would change. This answers
+ * where that cannot — outside git, or with no sync point to merge from — by units and
+ * records, not files: a section's translations, which a pull writes to `locales/*.json`,
+ * travel inside the section here (measured 2026-10-26: 8 units named, 11 files pulled).
+ *
+ * `uniweb pull` takes the backend's content; `uniweb status` asks what there is to take.
+ * The two must agree on what "changed" means, so this reads the backend as a pull does —
+ * the same two lanes, the same conditional GET (`etagsHold`) — and compares the answer
+ * with what this copy recorded at its last sync, each in the backend's own representation:
+ *
+ *   - the site-content entity's version against `baseVersions`: nothing moved, said
+ *     precisely;
+ *   - each unit's hash against `unitBases.remote`, which a pull and a push both bank from
+ *     the backend's own copy: which files moved. A unit's hash is only ever compared with a
+ *     base in its own representation (`@uniweb/build`'s `site-diff.js`);
+ *   - each record's version against `baseVersions`: which records moved.
+ *
+ * Whoever made the change — an author in the app, or a push from another copy — it is the
+ * backend's content this copy does not hold yet.
+ *
+ * ⛔ IT TAKES NOTHING. An ETag, a version or a hash banked here would say this copy holds
+ * content it never took, and the next pull would hear 304 and never catch up — the failure
+ * `pull.js` records beside `PULL_CACHE_VERSION`. Nothing here writes a file.
+ */
+
+import { computeUnitHashes, documentSchema, indexFolder, readBackendState } from '@uniweb/build/uwx'
+import {
+  etagsHold,
+  readPullCache,
+  readPullDocuments,
+  readPullVersions,
+  splitRecordsPull
+} from '../commands/pull.js'
+import { readBaseVersions, readUnitBases } from './site-sync.js'
+
+/**
+ * @param {object} p
+ * @param {import('./client.js').BackendClient} p.client - signed in; never prompts here
+ * @param {string} p.siteDir
+ * @param {string} p.siteUuid - the site's uuid on `client.origin` (sync.json)
+ * @returns {Promise<{ content: object, records: object }>} each lane's account:
+ *   `state` — `unchanged`, `changed` or `unknown` (with `detail`) — and what moved:
+ *   content `changed` / `added` / `removed` unit paths and `outsideUnits` (the site's
+ *   settings, services or queries moved, and no page did); records `changed` / `added`
+ *   labels (`<schema>/<slug>`), a `removed` count and `folder` (the records' sub-folders).
+ */
+export async function readAppChanges({ client, siteDir, siteUuid }) {
+  const etags = etagsHold(siteDir, client.origin) ? readPullCache(siteDir) : {}
+  const bases = readBaseVersions(siteDir, client.origin)
+  const [content, folder] = await Promise.all([
+    readLane(() => client.pullSiteContent(siteUuid, { etag: etags.content })),
+    readLane(() => client.pullFolder(siteUuid, { etag: etags.folder }))
+  ])
+  return {
+    content: contentChanges(content, { siteDir, origin: client.origin, siteUuid, bases }),
+    records: recordChanges(folder, { siteDir, origin: client.origin, bases })
+  }
+}
+
+async function readLane(request) {
+  let res
+  try {
+    res = await request()
+  } catch (err) {
+    return { error: err }
+  }
+  if (res.status === 304) return { notModified: true }
+  if (!res.ok) return { status: res.status }
+  try {
+    const buf = Buffer.from(await res.arrayBuffer())
+    return { docs: readPullDocuments(buf), versions: readPullVersions(buf) }
+  } catch (err) {
+    return { error: err }
+  }
+}
+
+function laneDetail(lane) {
+  if (lane.error) return lane.error.message || String(lane.error)
+  if (lane.status === 404) return 'the backend has no such site, or you lack access to it'
+  return `the backend answered HTTP ${lane.status}`
+}
+
+/** The content lane against this copy's last sync — see the header. */
+export function contentChanges(lane, { siteDir, origin, siteUuid, bases }) {
+  const none = { changed: [], added: [], removed: [], outsideUnits: false }
+  if (lane.notModified) return { state: 'unchanged', ...none }
+  if (!lane.docs) return { state: 'unknown', ...none, detail: laneDetail(lane) }
+  const doc = lane.docs.find((d) => d?.info || documentSchema(d)) || lane.docs[0] || null
+  if (!doc) return { state: 'unknown', ...none, detail: 'the backend sent no site content' }
+
+  const now = lane.versions?.[siteUuid]
+  const then = bases[siteUuid]
+  if (now && then && now === then) return { state: 'unchanged', ...none }
+
+  const base = readUnitBases(siteDir, origin).remote
+  if (!Object.keys(base).length) {
+    return { state: 'unknown', ...none, detail: "this copy holds no record of the backend's content at its last sync" }
+  }
+  const hashes = computeUnitHashes(doc)
+  const changed = []
+  const added = []
+  for (const [path, hash] of Object.entries(hashes)) {
+    if (!(path in base)) added.push(path)
+    else if (base[path] !== hash) changed.push(path)
+  }
+  const removed = Object.keys(base).filter((path) => !(path in hashes))
+  const units = changed.length + added.length + removed.length
+  // The entity moved and no unit did: what moved is outside the pages — the site's
+  // settings, its services, its queries.
+  const outsideUnits = !units && Boolean(now && then)
+  return {
+    state: units || outsideUnits ? 'changed' : 'unchanged',
+    changed: changed.sort(),
+    added: added.sort(),
+    removed: removed.sort(),
+    outsideUnits
+  }
+}
+
+// `@acme/article` → `article`: how a record's folder under `records/` is named.
+const shortSchema = (schema) => (typeof schema === 'string' ? schema.replace(/^@[^/]+\//, '') : null)
+
+/** The folder lane against this copy's last sync — see the header. */
+export function recordChanges(lane, { siteDir, origin, bases }) {
+  const none = { changed: [], added: [], removed: 0, folder: false }
+  if (lane.notModified) return { state: 'unchanged', ...none }
+  if (!lane.docs) return { state: 'unknown', ...none, detail: laneDetail(lane) }
+  const { folderDoc, recordDocs } = splitRecordsPull(lane.docs)
+  // The records this copy synced, by the backend's uuid (sync.json's `records`: own id → theirs).
+  const known = new Set(Object.values(readBackendState(siteDir, origin).records || {}))
+  if (!known.size && !recordDocs.length) return { state: 'unchanged', ...none }
+
+  const index = indexFolder(folderDoc)
+  const label = (doc) => {
+    const slug = index.get(doc.$uuid)?.slug ?? (typeof doc.$id === 'string' ? doc.$id.split('/').pop() : null)
+    const schema = shortSchema(documentSchema(doc))
+    return slug ? (schema ? `${schema}/${slug}` : slug) : doc.$uuid
+  }
+  const versions = lane.versions || {}
+  const changed = []
+  const added = []
+  const seen = new Set()
+  for (const doc of recordDocs) {
+    const uuid = doc?.$uuid
+    if (!uuid) continue
+    seen.add(uuid)
+    if (!known.has(uuid)) added.push(label(doc))
+    else if (bases[uuid] && versions[uuid] && bases[uuid] !== versions[uuid]) changed.push(label(doc))
+  }
+  const removed = [...known].filter((uuid) => !seen.has(uuid)).length
+  const folderUuid = folderDoc?.$uuid
+  const folder = Boolean(folderUuid && bases[folderUuid] && versions[folderUuid] && bases[folderUuid] !== versions[folderUuid])
+  const moved = changed.length || added.length || removed || folder
+  return { state: moved ? 'changed' : 'unchanged', changed: changed.sort(), added: added.sort(), removed, folder }
+}

package/src/backend/client.js

@@ -948,7 +948,7 @@ export class BackendClient {
    *   { published: boolean, last_pushed_at?: string, last_published_at?: string, draft_dirty?: boolean }
    * `draft_dirty` = never-published, or the synced draft changed since the last
    * publish ("pushed but not published"). Since 2026-10-13 it also carries `editors`:
-   * who has the site open in the app right now, and on what — `status --remote` shows
+   * who has the site open in the app right now, and on what — `uniweb status` shows
    * it (`describeEditors`, commands/status.js).
    *
    * ⭐ **The backend also serves a LIVE-SITE record here, and nothing in this CLI reads
@@ -974,14 +974,14 @@ export class BackendClient {
    * The path is VERB-FIRST (`status/{uuid}`)
    * to match the lane (`publish/{uuid}`, `content/push/{uuid}`, `folder/pull/{uuid}`),
    * not the `{uuid}/status` the shipping-verbs §8 sketch assumed. null on
-   * 404 (unknown/not-yours) / 401 / any failure — `status --remote` degrades to local.
+   * 404 (unknown/not-yours) / 401 / any failure — `uniweb status` says what it could not tell.
    * @param {string} uuid - the site-content uuid
    * @returns {Promise<object|null>}
    */
   /**
    * Whether the backend holds the site `uuid` names — `live`, `gone` or `unknown`, kept
    * apart — for a script that must decide, before any push, whether a binding still
-   * points at a site (`uniweb status --remote --json`, `remote.site_state`).
+   * points at a site (`uniweb status --json`, its `app.site` check).
    *
    * ⛔ `gone` ONLY ON THE BACKEND'S OWN WORD ABOUT THIS SITE: a `404` whose problem names
    * it — `kind: "site"`, `key: <uuid>`. A push from an unbound copy CREATES a site, so a

package/src/backend/foundation-bring-along.js

@@ -34,7 +34,7 @@
  * no local state, multi-machine-safe. When the site references a published
  * registry ref or a URL there's nothing to bring along. When the backend
  * doesn't expose the stored digest yet, the compare DEGRADES to "ask" (same
- * posture as `status --remote` on a 404).
+ * posture as `uniweb status` on a 404).
  *
  * "Release" here is literally `uniweb register` run in the foundation directory
  * — same build-if-stale → schema submit → code upload → digest the standalone

package/src/backend/service-request.js

@@ -164,27 +164,43 @@ const names = (list) => list.map((n) => `\`${n}\``).join(', ')
  * @param {string[]|null} [p.supports] - from `foundationSupports`; null = unknown
  */
 export function announceServices({ siteYml, say, supports = null }) {
+  for (const note of serviceNotes({ siteYml, supports, warn: (m) => say.warn(m) })) say.warn(note)
+}
+
+/**
+ * Where `site.yml::services` and the foundation disagree — the notes `announceServices`
+ * says, as lines, for a caller that reports them (`uniweb status`).
+ *
+ * @param {object} p
+ * @param {object} p.siteYml - parsed
+ * @param {string[]|null} [p.supports] - from `foundationSupports`; null = unknown
+ * @param {(m: string) => void} [p.warn] - told what the file asks that will not be sent as written
+ * @returns {string[]}
+ */
+export function serviceNotes({ siteYml, supports = null, warn = () => {} }) {
   // An entry the push cannot read stops the package build next, which says what to write
   // (`refuseUnreadableServices`). Nothing to add before it — and what this would say, read
   // past that entry, is wrong: `search: yes` was "site.yml turns on `search`" (F14).
-  if (unreadableServices(siteYml?.services).length) return
-  const asks = readServicesRequest(siteYml?.services, { warn: (m) => say.warn(m) }) || []
-  if (!Array.isArray(supports)) return
+  if (unreadableServices(siteYml?.services).length) return []
+  const asks = readServicesRequest(siteYml?.services, { warn }) || []
+  if (!Array.isArray(supports)) return []
+  const notes = []
   const ignored = new Set(['tracking', 'records'])
   const has = (ask) => ask.enabled !== false || typeof ask.config?.endpoint === 'string'
   const unrendered = asks.filter((a) => has(a) && !ignored.has(a.name) && !supports.includes(a.name)).map((a) => a.name)
   if (unrendered.length) {
-    say.warn(`site.yml turns on ${names(unrendered)}, which your foundation does not say it renders (\`uniweb.supports\`).`)
+    notes.push(`site.yml turns on ${names(unrendered)}, which your foundation does not say it renders (\`uniweb.supports\`).`)
   }
   const mentioned = new Set(asks.map((a) => a.name))
   const unasked = supports.filter((n) => !ignored.has(n) && !mentioned.has(n))
   if (unasked.length) {
-    say.warn(
+    notes.push(
       `Your foundation renders ${names(unasked)}, which site.yml does not ask for — a service is off ` +
         `unless the site asks for it. Add ${unasked.length === 1 ? 'it' : 'them'} under \`services:\`, or set ` +
         `${unasked.length === 1 ? 'it' : 'each'} to \`false\` if that is what you mean.`
     )
   }
+  return notes
 }
 
 /**

package/src/commands/doctor.js

@@ -62,11 +62,16 @@ const colors = {
   blue: '\x1b[36m'
 }
 
-const success = (msg) => console.log(`${colors.green}✓${colors.reset} ${msg}`)
-const warn = (msg) => console.log(`${colors.yellow}⚠${colors.reset} ${msg}`)
-const error = (msg) => console.log(`${colors.red}✗${colors.reset} ${msg}`)
-const info = (msg) => console.log(`${colors.blue}→${colors.reset} ${msg}`)
-const log = console.log
+// Where the report goes: the terminal — whatever `console.log` is when a line is printed —
+// or nowhere while another command reads the findings (`doctor(args, { quiet: true })`,
+// `uniweb status`).
+const toConsole = (...args) => console.log(...args)
+let print = toConsole
+const success = (msg) => print(`${colors.green}✓${colors.reset} ${msg}`)
+const warn = (msg) => print(`${colors.yellow}⚠${colors.reset} ${msg}`)
+const error = (msg) => print(`${colors.red}✗${colors.reset} ${msg}`)
+const info = (msg) => print(`${colors.blue}→${colors.reset} ${msg}`)
+const log = (...args) => print(...args)
 
 /**
  * Check if a directory is a site
@@ -1196,7 +1201,24 @@ export function checkGeneratedDataDir({ sitePath, siteName, siteYml, issues, sho
 /**
  * Main doctor command
  */
-export async function doctor(args = []) {
+/**
+ * @param {string[]} [args]
+ * @param {{ quiet?: boolean }} [opts] - `quiet`: print nothing, for a command that reads the
+ *   findings (`uniweb status`). Without `--fix` doctor writes nothing, so a quiet run is a
+ *   read.
+ * @returns {Promise<{ issues: object[], errors: number, warnings: number, fixed: number }>}
+ */
+export async function doctor(args = [], { quiet = false } = {}) {
+  const before = print
+  print = quiet ? () => {} : toConsole
+  try {
+    return await runDoctor(args)
+  } finally {
+    print = before
+  }
+}
+
+async function runDoctor(args = []) {
   log('')
   log(`${colors.blue}${colors.bright}Uniweb Doctor${colors.reset}`)
   log(`${colors.dim}Checking project configuration...${colors.reset}`)
@@ -1212,7 +1234,7 @@ export async function doctor(args = []) {
   // the failure the guess was moved here to avoid. Those checks ask for the id.
   const shouldFixExplicitly = (id) => fixFlag === id
   const fixed = (msg) =>
-    console.log(`  ${colors.green}↳ Fixed:${colors.reset} ${msg}`)
+    print(`  ${colors.green}↳ Fixed:${colors.reset} ${msg}`)
 
   const projectDir = resolve(process.cwd())
 
@@ -1225,7 +1247,14 @@ export async function doctor(args = []) {
     log(
       `${colors.dim}Run this command from your project root or a site/foundation directory.${colors.reset}`
     )
-    process.exit(1)
+    // Returned, not exited, so a command reading the findings gets them; the CLI exits 1 on
+    // an error either way.
+    return {
+      issues: [{ id: 'not-a-workspace', type: 'error', message: 'Not in a Uniweb workspace' }],
+      errors: 1,
+      warnings: 0,
+      fixed: 0
+    }
   }
 
   log('')
@@ -1964,6 +1993,54 @@ export async function doctor(args = []) {
       }
     }
 
+    // ⛔ The keys retired on 2026-09-20 read as nothing, without a word: a deploy recorded
+    // under `lastDeploy:` is one `uniweb status` cannot see, and `autoSave: off` is ignored,
+    // so deploys are recorded after all. A renamed key returns empty; it does not fail.
+    const retired = ['lastDeploy', 'autoSave'].filter((k) => deployYml[k] !== undefined)
+    if (retired.length) {
+      const id = 'deploy-yml-retired-key'
+      const issue = {
+        id,
+        type: 'warn',
+        site: siteName,
+        message: `deploy.yml uses ${retired.map((k) => `\`${k}:\``).join(' and ')}, which the CLI no longer reads`
+      }
+      issues.push(issue)
+      warn(`[${id}] ${siteName}: deploy.yml uses ${retired.map((k) => `\`${k}:\``).join(' and ')}, which the CLI no longer reads.`)
+      const lost = []
+      if (deployYml.lastDeploy && typeof deployYml.lastDeploy === 'object') {
+        const names = Object.keys(deployYml.lastDeploy).filter((n) => !deployYml.deploys?.[n])
+        if (names.length) lost.push(`the last deploy of ${names.map((n) => `\`${n}\``).join(', ')} is recorded only there, where nothing sees it`)
+      }
+      if (String(deployYml.autoSave) === 'off') lost.push('`autoSave: off` is ignored, so deploys are recorded')
+      const renamed = { lastDeploy: 'deploys', autoSave: 'saveDeploys' }
+      log(
+        `    ${colors.dim}${retired.map((k) => `\`${k}:\` is \`${renamed[k]}:\``).join(' and ')} now${lost.length ? ` — ${lost.join('; ')}` : ''}.${colors.reset}`
+      )
+      if (shouldFix(id)) {
+        try {
+          const { retireDeployYmlKeys } = await import('@uniweb/build/site')
+          const done = await retireDeployYmlKeys(sitePath)
+          if (done) {
+            issue.fixed = true
+            fixed(
+              `${relative(workspaceDir, deployYmlPath)}: ${[
+                done.moved.length && `moved ${done.moved.join(', ')} to \`deploys:\``,
+                done.saveDeploys === false && 'wrote `saveDeploys: false`',
+                'removed the old keys'
+              ]
+                .filter(Boolean)
+                .join(', ')}`
+            )
+          }
+        } catch (err) {
+          warn(`[${id}] could not rewrite ${relative(workspaceDir, deployYmlPath)}: ${err.message}`)
+        }
+      } else {
+        log(`    ${colors.dim}Run \`uniweb doctor --fix ${id}\` to move them, keeping your comments.${colors.reset}`)
+      }
+    }
+
     // github-pages-specific: if a target has `domain`, `site/public/CNAME`
     // should exist with that value. Vite copies public/ into dist/, and
     // GH Pages reads dist/CNAME on each deploy to keep the custom domain
@@ -2076,6 +2153,7 @@ export async function doctor(args = []) {
     )
     info(`Run: uniweb update`)
     issues.push({
+      id: 'deps-behind-cli',
       type: 'warn',
       message: `${behindDeps.length} @uniweb/* dep declaration(s) behind CLI v${cliVersion}`
     })
@@ -2093,16 +2171,17 @@ export async function doctor(args = []) {
   if (!existsSync(agentsPath)) {
     warn('AGENTS.md not found')
     info(`Run: uniweb update`)
-    issues.push({ type: 'warn', message: 'AGENTS.md not found' })
+    issues.push({ id: 'agents-md-missing', type: 'warn', message: 'AGENTS.md not found' })
   } else if (!agentsVersion) {
     // No stamp — manually created or pre-stamp version
     warn('AGENTS.md has no version stamp (may be outdated)')
     info(`Run: uniweb update`)
-    issues.push({ type: 'warn', message: 'AGENTS.md has no version stamp' })
+    issues.push({ id: 'agents-md-unstamped', type: 'warn', message: 'AGENTS.md has no version stamp' })
   } else if (agentsVersion !== cliVersion) {
     warn(`AGENTS.md is outdated (v${agentsVersion} → v${cliVersion})`)
     info(`Run: uniweb update`)
     issues.push({
+      id: 'agents-md-outdated',
       type: 'warn',
       message: `AGENTS.md outdated (v${agentsVersion} → v${cliVersion})`
     })