uniweb 0.16.5 → 0.18.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.16.5",
+  "version": "0.18.0",
   "description": "Create structured Vite + React sites with content/code separation",
   "type": "module",
   "bin": {
@@ -43,7 +43,7 @@
     "tar": "^7.0.0",
     "@uniweb/core": "^0.8.5",
     "@uniweb/kit": "^0.11.3",
-    "@uniweb/runtime": "^0.11.5"
+    "@uniweb/runtime": "^0.11.7"
   },
   "peerDependencies": {
     "@uniweb/build": "^0.18.5",

package/partials/agents.md

@@ -1906,6 +1906,7 @@ uniweb add ci --target foundation # Publish a foundation for free at permanent v
                                   # (GitHub Pages → foundations/<name>/<version>/entry.js)
 
 uniweb push / pull / clone / status   # Git-style content sync with the Uniweb backend
+uniweb push --org @acme               # First push/publish of a site: who owns it (see below)
 uniweb register [--scope @org]        # Register a foundation + its data schemas to the registry
 uniweb login / logout                 # Start or clear the backend session the verbs above reuse
 uniweb org list / create <handle>     # Publish orgs you belong to — the @org in a scoped ref
@@ -1947,6 +1948,26 @@ Foundations have their own free path too: `uniweb add ci --target foundation` pu
 
 **Content authors work visually in the Uniweb App.** They compose the same extended markdown and set the same component params you defined, through a visual editor — never touching code, git, or the CLI. They see exactly the section types your foundation offers and exactly the knobs each one exposes, because **every `meta.js` is registered as the foundation's schema** when you publish. Your `meta.js` is the app's UI (see *meta.js* in Part 4).
 
+> ⚠️ **The FIRST push or publish of a site asks who owns it — and refuses if it cannot ask.**
+> That create decides which organization owns the site (and whose storage its assets are billed
+> to), it is the only moment the choice is made, and there is no CLI command to change it
+> afterwards. At a terminal you get a picker. **Without a terminal — CI, a script, or you, an
+> agent — the command exits non-zero instead of choosing**, and `--yes` refuses too, because
+> guessing an owner is not an answer. Name it and it never asks again:
+>
+> ```bash
+> uniweb publish --org @acme     # an organization
+> uniweb publish --personal      # your personal account, deliberately
+> ```
+>
+> The answer is recorded in `site.yml::$org` and committed, so it is a one-time choice per site,
+> not per machine. **Ask the human which one to use** rather than picking for them — a site in
+> the wrong org cannot be moved from here. Sites that already exist are unaffected: their
+> ownership is settled, so nothing is asked.
+>
+> Relatedly: these commands now **reject flags they do not recognize** instead of ignoring them.
+> If you get `Unknown flag`, read the suggestion — it is usually a near miss.
+
 **Sync is developer-only and one-sided by design.** `uniweb push` and `uniweb pull` are your commands, not theirs:
 
 - **The app is the live source of truth for content** — where authors work and where your push lands live.

package/src/backend/site-sync.js

@@ -444,6 +444,164 @@ function recordSiteOrg(siteDir, asOrg) {
   }
 }
 
+/**
+ * Resolve WHICH ORG will own a site that is about to be created.
+ *
+ * The create that mints `$uuid` is the only call that reads `as_org`, and the
+ * backend never moves ownership afterwards. There is also no CLI verb to transfer
+ * or delete a site. So this is a **one-shot, unrepealable** decision — and until
+ * this function existed the CLI made it silently, by sending nothing and letting
+ * the backend fall back to the session's personal context. A developer who belongs
+ * to several orgs could put a company site, and the storage it bills, somewhere
+ * they never named.
+ *
+ * `register` has refused to guess a scope for the foundation lane since it shipped
+ * (`deriveScope` → `package.json::uniweb.scope`). This is the same refusal, one
+ * lane over.
+ *
+ * Order, and only the last step is new:
+ *   1. `--as-org @org`      — explicit, rides verbatim
+ *   2. `--personal`         — explicit "no org, I mean it" → sends NO `as_org`
+ *   3. `site.yml::$org`     — recorded at this site's own create
+ *   4. the site already exists (`$uuid`) → null; ownership is settled, ask nothing
+ *   5. otherwise ASK (TTY) or REFUSE (non-interactive)
+ *
+ * ⛔ **`--personal` sends no `as_org`, and is NOT the same as `--as-org @<handle>`.**
+ * The personal *org* `@jane` is an org like any other, lazily created on first use;
+ * the session's personal context is not an org at all. Whether the backend gives
+ * them the same owning unit is **its** business and unverified here, so the
+ * deliberate-personal spelling reproduces today's wire byte-for-byte rather than
+ * asserting an equivalence this lane cannot check.
+ *
+ * @returns {Promise<{ asOrg: string|null, refused?: true, reason?: string }>}
+ *   `asOrg: null` with no `refused` means "send no as_org" — either a settled site
+ *   or a deliberate personal choice.
+ */
+export async function resolveSiteOrgForCreate({
+  client,
+  siteDir,
+  args = [],
+  flag,
+  personal = false,
+  offline = false
+}) {
+  if (flag) return { asOrg: flag }
+  if (personal) return { asOrg: null }
+
+  const recorded = readSiteOrg(siteDir)
+  if (recorded) return { asOrg: recorded }
+
+  // Already created ⇒ nothing to decide. This is what keeps every existing site
+  // silent: ownership was settled at its create, and re-asking would be theatre.
+  let siteYml = {}
+  try {
+    const y = yaml.load(readFileSync(join(siteDir, 'site.yml'), 'utf8'))
+    if (y && typeof y === 'object') siteYml = y
+  } catch {
+    /* unreadable — treat as un-created and let the resolution below decide */
+  }
+  if (typeof siteYml.$uuid === 'string') return { asOrg: null }
+
+  // An offline preview (`--dry-run` / `-o`) must never authenticate, and it is
+  // creating nothing, so there is no decision to force. Say what is unresolved
+  // instead of prompting for an answer the run will not use.
+  if (offline) return { asOrg: null }
+
+  // `--yes` promises "never block on a prompt", so it has to answer this one too —
+  // and the only honest non-blocking answer to an unanswerable ownership question
+  // is a refusal. Treating it as consent-to-anything would reinstate the silent
+  // default this whole path exists to remove, behind a flag that reads like
+  // approval.
+  const { isNonInteractive } = await import('../utils/interactive.js')
+  if (isNonInteractive(args) || args.includes('--yes')) {
+    return {
+      asOrg: null,
+      refused: true,
+      reason:
+        'This site does not exist on the backend yet, and no org was named.\n' +
+        '  The create decides who OWNS it — and which workspace its storage is billed to —\n' +
+        '  one time, with no CLI way to change it afterwards. Name it explicitly:\n' +
+        '    --as-org @org     create it under an organization\n' +
+        '    --personal        create it under your personal account, deliberately'
+    }
+  }
+
+  // Interactive: offer the real choice. Deliberately NOT `deriveScope` — that one
+  // serves the foundation lane, where every answer is an org and 0-orgs means
+  // "claim your personal org". Here "personal" must stay reachable as *no org*,
+  // and reusing deriveScope would quietly turn it into an org creation.
+  const { fetchOrgs, createOrg, validateHandle, bareHandle } = await import(
+    '../utils/registry-orgs.js'
+  )
+  let envelope
+  try {
+    envelope = await fetchOrgs({
+      apiBase: client.origin,
+      token: await client.token()
+    })
+  } catch (err) {
+    return { asOrg: null, refused: true, reason: err.message }
+  }
+  const personalHandle = envelope.account_handle || null
+  const prompts = (await import('prompts')).default
+  const choices = [
+    ...envelope.orgs.map((o) => ({
+      title: `@${o.handle}${o.handle === personalHandle ? ' — your personal org' : o.is_primary ? ' (primary)' : ''}`,
+      value: o.handle
+    })),
+    {
+      title: `Personal — no organization${personalHandle ? ` (${personalHandle})` : ''}`,
+      value: ':personal'
+    },
+    { title: 'A new organization…', value: ':new' }
+  ]
+  const { choice } = await prompts(
+    {
+      type: 'select',
+      name: 'choice',
+      message: 'Create this site under which owner?',
+      choices,
+      initial: 0
+    },
+    {
+      onCancel: () => {
+        console.log('\nCancelled.')
+        process.exit(0)
+      }
+    }
+  )
+  if (!choice) return { asOrg: null, refused: true, reason: 'No owner chosen.' }
+  if (choice === ':personal') return { asOrg: null }
+  if (choice !== ':new') return { asOrg: `@${choice}` }
+
+  const answer = await prompts(
+    {
+      type: 'text',
+      name: 'handle',
+      message: 'Org handle (e.g. acme):',
+      validate: (v) => validateHandle(v) || true
+    },
+    {
+      onCancel: () => {
+        console.log('\nCancelled.')
+        process.exit(0)
+      }
+    }
+  )
+  if (!answer.handle)
+    return { asOrg: null, refused: true, reason: 'No org handle given.' }
+  try {
+    const org = await createOrg({
+      apiBase: client.origin,
+      token: await client.token(),
+      handle: bareHandle(answer.handle)
+    })
+    return { asOrg: `@${org.handle}` }
+  } catch (err) {
+    return { asOrg: null, refused: true, reason: err.message }
+  }
+}
+
 /**
  * Guarantee the site EXISTS on the backend before anything is uploaded against it.
  *
@@ -525,7 +683,8 @@ export async function ensureSiteExists({
           : `HTTP ${res?.status} ${res?.statusText || ''}${body ? ` — ${body.slice(0, 200)}` : ''}`
     }
   }
-  const minted = extractMintedSiteUuid(await res.json().catch(() => null))
+  const payload = await res.json().catch(() => null)
+  const minted = extractMintedSiteUuid(payload)
   if (!minted) {
     return {
       uuid: null,
@@ -538,16 +697,65 @@ export async function ensureSiteExists({
   // this point cannot leave a cache pointing at a different site with no way to
   // detect it.
   updateSyncCache(siteDir, { siteUuid: minted })
-  // Ownership is decided HERE and nowhere else — this is the one call that reads
-  // `as_org`. Recording it beside the uuid is what makes the answer readable later,
-  // and naming it now is the "show what resolved" half of the ask-once pattern.
-  const org = recordSiteOrg(siteDir, asOrg)
+  const org = await recordAndDescribeOwner({
+    client,
+    siteDir,
+    payload,
+    asOrg,
+    note
+  })
+  return { uuid: minted, created: true, org }
+}
+
+/**
+ * Record and announce who owns a just-created site, from the backend's own echo.
+ *
+ * The echo reports what the site **is**; `asOrg` is only what we asked for. They
+ * agree in the normal case and the echo is the one to trust — it is read back off
+ * the created entity, so it also covers the case we could never record before: no
+ * `--as-org` at all, where the backend picked and we had nothing true to write.
+ *
+ * ⚠️ `org: null` is MEANINGFUL (personal), not missing. An older backend omits the
+ * key entirely, which is the only case that falls back to what we asked for.
+ *
+ * @returns {Promise<string|null>} the display handle recorded, or null for personal
+ */
+async function recordAndDescribeOwner({ client, siteDir, payload, asOrg, note }) {
+  const echoed = payload && 'org' in payload ? payload.org : undefined
+  const owner =
+    echoed === undefined ? asOrg : typeof echoed === 'string' ? echoed : null
+  const org = recordSiteOrg(siteDir, owner)
+
   note?.(
     org
       ? `Created the site on the backend under ${org} (recorded $uuid + $org in site.yml).`
-      : `Created the site on the backend (recorded $uuid in site.yml).`
+      : `Created the site on the backend, owned personally (recorded $uuid in site.yml).`
   )
-  return { uuid: minted, created: true, org }
+
+  // The billing line needs the JOIN of two independent facts, and either alone
+  // gives a wrong answer:
+  //   hosts_free               — a property of the SCOPE (is this owner exempt?)
+  //   siteSubscriptionRequired — a property of the DEPLOYMENT (does it charge at all?)
+  // Keyed on the scope alone, this fires on every local publish — where nothing
+  // enforces — until the warning is trained away. Keyed on the deployment alone it
+  // fires at exempt owners. An older backend supplies neither, so both read falsy
+  // and nothing is said: silence beats a claim we cannot justify.
+  const hostsFree = payload?.hosts_free === true
+  let enforces = false
+  try {
+    const cfg = await client.discover()
+    enforces = cfg?.delivery?.siteSubscriptionRequired === true
+  } catch {
+    /* discovery is advisory here — never fail a create over a message */
+  }
+  if (hostsFree) {
+    note?.('This owner is hosted free — publishing will not require a subscription.')
+  } else if (enforces) {
+    note?.(
+      'Publishing this site live will require a hosting subscription on this backend.'
+    )
+  }
+  return org
 }
 
 /**
@@ -904,7 +1112,15 @@ export async function pushSyncPackages({
       // which is gated on the site having local media). Both mint a site, so both
       // owe the same record — recording it in only one place would make `$org`
       // present or absent depending on whether the site happens to have images.
-      const createdOrg = recordSiteOrg(siteDir, asOrg)
+      // The backend echoes `org`/`hosts_free` top-level here too, beside `report`
+      // and `site` (NOT beside `finalized`, which lives at report.finalized).
+      const createdOrg = await recordAndDescribeOwner({
+        client,
+        siteDir,
+        payload,
+        asOrg,
+        note
+      })
       if (createdOrg) wrote.push(`recorded site $org (${createdOrg}) in site.yml`)
       const createdFinalized = extractFinalized(payload)
       harvest(createdFinalized)

package/src/commands/clone.js

@@ -57,6 +57,8 @@ import { BackendClient } from '../backend/client.js'
 import { isNonInteractive, getCliPrefix } from '../utils/interactive.js'
 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'
 
 const colors = {
   reset: '\x1b[0m',
@@ -159,6 +161,13 @@ function pullExecArgv(pm, extra) {
  *   runPull(siteDir, pm, extraArgs).
  */
 export async function clone(args = [], deps = {}) {
+  // See utils/flag-guard.js — an unrecognized flag is invisible to a
+  // literal scan, so it silently keeps the default (production, for --backend).
+  const badFlag = checkFlags('clone', args)
+  if (badFlag) {
+    error(badFlag.message)
+    return { exitCode: 2 }
+  }
   const positionals = args.filter((a) => !a.startsWith('-'))
   const siteUuid = positionals[0]
   const target = positionals[1] || null // [name|.]
@@ -348,6 +357,31 @@ export async function clone(args = [], deps = {}) {
     }
   }
 
+  // Tell the delegated pull which files WE wrote, or it refuses on them.
+  //
+  // Pull guards against overwriting uncommitted work under the paths it rewrites,
+  // and `site.yml` / `theme.yml` are exactly those paths — uncommitted here
+  // because clone scaffolded them seconds ago. Without this, clone reliably ends
+  // in "Refusing to pull: 2 uncommitted change(s)" on a project it just created,
+  // where there is no user work to protect. The advice it prints (`--force`) is
+  // both unreachable — clone does not forward that flag — and wrong, since it
+  // means "discard my changes" and the changes are ours.
+  //
+  // ⭐ This exempts them for the RIGHT reason rather than overriding the guard.
+  // `recordWritten` stores a content hash, so a file the user edits between
+  // scaffold and pull no longer matches and the refusal correctly stands. The
+  // guard keeps its teeth; it just stops firing on machine output, which is what
+  // it already does for pull's own writes.
+  //
+  // Recorded AFTER the uuid seeding above — the hash has to be of the final
+  // bytes on disk, not of what the scaffolder first wrote.
+  recordWritten(
+    siteDir,
+    ['site.yml', 'theme.yml', 'head.html', 'collections.yml']
+      .map((f) => join(siteDir, f))
+      .filter((p) => existsSync(p))
+  )
+
   const pullExtra = []
   if (explicitBackend) pullExtra.push('--backend', explicitBackend)
   if (tokenFlag) pullExtra.push('--token', tokenFlag)

package/src/commands/publish.js

@@ -28,12 +28,15 @@
  *   uniweb publish --dry-run       Resolve everything; POST nothing
  *   uniweb publish --yes           Skip confirmations (CI); never block on a prompt
  *   uniweb publish --force         Overwrite upstream app-side edits (drop the push gate)
- *   uniweb publish --as-org @org   Publish under @org (membership-gated). Only the
+ *   uniweb publish --org @org      Publish under @org (alias: --as-org). Only the
  *                                  FIRST publish of a site reads it — that create is
  *                                  what decides which org owns the site and whose
  *                                  storage its assets are charged to. It is then
  *                                  recorded as `site.yml::$org` and replayed, so it
  *                                  never has to be re-typed.
+ *   uniweb publish --personal      Own the new site personally, deliberately. Sends
+ *                                  NO `as_org` — byte-identical to the wire before
+ *                                  the owner prompt existed. First publish only.
  *   uniweb publish --no-save       Skip the deploy.yml lastDeploy auto-save
  *   uniweb publish --backend <url> Override the backend origin
  *   uniweb publish --token <bearer> Auth bearer (skips `uniweb login`)
@@ -61,7 +64,8 @@ import { resolveDefaultLocale } from '@uniweb/core/locale-config'
 import { BackendClient } from '../backend/client.js'
 import { resolveSiteDir, resolveSiteBackend } from './deploy.js'
 import { warnIfContentDoesNotConform } from '../utils/conformance.js'
-import { readFlagValue } from '../utils/args.js'
+import { readFlagValue, readOrgFlag } from '../utils/args.js'
+import { checkFlags } from '../utils/flag-guard.js'
 import { isNonInteractive } from '../utils/interactive.js'
 import { headProvenance } from '../utils/git.js'
 import {
@@ -73,7 +77,7 @@ import {
   ensureSiteExists,
   clearRemoteSyncStateIfUnbound,
   pushSyncPackages,
-  readSiteOrg
+  resolveSiteOrgForCreate
 } from '../backend/site-sync.js'
 import { uploadDataBundle } from '../backend/data-bundle.js'
 import { uploadSiteMedia, describeAssetRefusal } from '../backend/site-media.js'
@@ -172,18 +176,19 @@ async function persistLastDeploy(siteDir, opts) {
 }
 
 export async function publish(args = []) {
+  // See utils/flag-guard.js — an unrecognized flag is invisible to a literal
+  // scan, and for --backend the silent default can be production.
+  const bad = checkFlags('publish', args)
+  if (bad) {
+    say.err(bad.message)
+    return { exitCode: 2 }
+  }
   const dryRun = args.includes('--dry-run')
   const noSave = args.includes('--no-save')
   const foundationDir = readFlagValue(args, '--foundation') // optional local foundation for Model schemas
 
   const siteDir = await resolveSiteDir(args, 'publish')
 
-  // The acting org: the flag verbatim, else the one this site was CREATED under
-  // (`site.yml::$org`). Only the create reads `as_org`, so replaying the recorded
-  // handle reasserts existing ownership rather than choosing new ownership. Absent
-  // both, no `as_org` is sent — unchanged from before the record existed.
-  const asOrg = readFlagValue(args, '--as-org') || readSiteOrg(siteDir)
-
   // Advisory only — warns and ships. See utils/conformance.js for why this
   // is not a gate.
   await warnIfContentDoesNotConform(siteDir, { args })
@@ -201,6 +206,25 @@ export async function publish(args = []) {
     command: 'Publishing'
   })
 
+  // WHO will own this site, if this publish is the one that creates it. Resolved
+  // up front: `ensureSiteExists` below is the create, and it must not be reached
+  // with the question still open. An already-created site resolves to null without
+  // asking — its ownership was settled once and cannot be changed from here.
+  const org = await resolveSiteOrgForCreate({
+    client,
+    siteDir,
+    args,
+    flag: readOrgFlag(args),
+    personal: args.includes('--personal'),
+    offline: dryRun
+  })
+  if (org.refused) {
+    say.err('Refusing to create this site without naming an owner.')
+    say.dim(org.reason)
+    return { exitCode: 2 }
+  }
+  const asOrg = org.asOrg
+
   // Capability handshake (cached). Publish ends in a go-live, so the publish
   // lane must be offered.
   const config = await client.discover()

package/src/commands/pull.js

@@ -76,8 +76,13 @@ import {
   computeUnitHashes,
   collectUnitUuids
 } from '@uniweb/build/uwx'
-import { makeModelResolver } from './push.js'
 import {
+  readWritten,
+  recordWritten,
+  isPullOutput
+} from '../utils/pull-written.js'
+import {
+  makeModelResolver,
   mergeBaseVersions,
   mergeItemBaseVersions,
   writeUnitBases,
@@ -95,6 +100,7 @@ import {
   resolveSiteDir as defaultResolveSiteDir,
   resolveSiteBackend
 } from './deploy.js'
+import { checkFlags } from '../utils/flag-guard.js'
 
 const FOLDER_MODEL = '@uniweb/folder'
 
@@ -355,79 +361,10 @@ async function checkWorkingTree(siteDir, args) {
   return { exitCode: 1 }
 }
 
-// What the last pull wrote: `{ <repo-relative path>: <sha256 of the bytes it wrote> }`.
-//
-// Without this the guard cries wolf: pull rewrites the tree, so the very next pull
-// sees its OWN output as uncommitted work and refuses, listing files the user never
-// touched. A guard that fires on nothing teaches people to reach for --force, which
-// is the destructive option — the same failure mode as a gate that refuses disjoint
-// edits. A file still byte-identical to what pull last wrote is not user work.
-function writtenCachePath(siteDir) {
-  return join(siteDir, '.uniweb', 'pull-written.json')
-}
-function readWritten(siteDir) {
-  try {
-    const o = JSON.parse(readFileSync(writtenCachePath(siteDir), 'utf8'))
-    return {
-      files: o && typeof o.files === 'object' ? o.files : {},
-      deleted: Array.isArray(o?.deleted) ? o.deleted : []
-    }
-  } catch {
-    return { files: {}, deleted: [] }
-  }
-}
-function recordWritten(siteDir, absPaths, deletedAbs = []) {
-  // MERGE, don't replace. A conditional pull that 304s writes nothing, and a
-  // partial pull writes only some lanes — in both cases the previous record is
-  // still "the last thing pull wrote there". Replacing would forget those paths and
-  // the next pull would see them as the user's work again, which is the false alarm
-  // this cache exists to prevent. A stale entry for a file that no longer exists is
-  // harmless: the hash read fails and it counts as a local change.
-  const prior = readWritten(siteDir)
-  const files = prior.files
-  for (const abs of absPaths) {
-    try {
-      files[relative(siteDir, abs)] = createHash('sha256')
-        .update(readFileSync(abs))
-        .digest('hex')
-    } catch {
-      /* deleted or unreadable — nothing to remember */
-    }
-  }
-  // Pull PRUNES too, and a deletion is a dirty path git reports just like an edit.
-  // Without recording them, pull's own pruning reads as the user having deleted
-  // files — the same false alarm as its writes, arriving by the other door.
-  const deleted = [
-    ...new Set([
-      ...prior.deleted,
-      ...deletedAbs.map((a) => relative(siteDir, a))
-    ])
-  ]
-  try {
-    mkdirSync(dirname(writtenCachePath(siteDir)), { recursive: true })
-    writeFileSync(
-      writtenCachePath(siteDir),
-      JSON.stringify({ version: 1, files, deleted }, null, 2) + '\n'
-    )
-  } catch {
-    /* best-effort: losing it only costs a spurious refusal */
-  }
-}
-// Is this dirty path just pull's own untouched output?
-function isPullOutput(siteDir, relPath, written) {
-  let exists = true
-  let hash = null
-  try {
-    hash = createHash('sha256')
-      .update(readFileSync(join(siteDir, relPath)))
-      .digest('hex')
-  } catch {
-    exists = false
-  }
-  // Absent because pull pruned it — not because the user deleted it.
-  if (!exists) return written.deleted.includes(relPath)
-  return written.files[relPath] === hash
-}
+// The written-record helpers live in `utils/pull-written.js` so `clone` can share
+// them: clone scaffolds site.yml/theme.yml and then delegates here, and this
+// module cannot be imported from there — it statically imports `@uniweb/build`,
+// which resolves from a project that does not exist yet when clone runs.
 
 /**
  * `--merge`: keep local work instead of refusing, by three-way merging it with what
@@ -539,6 +476,13 @@ async function confirm(question) {
 }
 
 export async function pull(args = [], deps = {}) {
+  // See utils/flag-guard.js — an unrecognized flag is invisible to a
+  // literal scan, so it silently keeps the default (production, for --backend).
+  const badFlag = checkFlags('pull', args)
+  if (badFlag) {
+    error(badFlag.message)
+    return { exitCode: 2 }
+  }
   const resolveSiteDir = deps.resolveSiteDir || defaultResolveSiteDir
 
   const dryRun = args.includes('--dry-run')

package/src/commands/push.js

@@ -26,11 +26,15 @@
  *
  * Usage:
  *   uniweb push                          Build, push both lanes, back-fill $uuid
- *   uniweb push --as-org @org            Act as @org (membership-gated). Needed only
- *                                        for the FIRST push of a site — it decides
- *                                        which org owns it (and whose storage its
- *                                        assets are charged to). Recorded as
+ *   uniweb push --org @org               Own the new site under @org (alias: --as-org).
+ *                                        Read only on the FIRST push of a site — it
+ *                                        decides which org owns it, and whose storage
+ *                                        its assets are charged to. Recorded as
  *                                        `site.yml::$org` and replayed after that.
+ *                                        Without it, you are asked once.
+ *   uniweb push --personal               Own the new site personally, deliberately.
+ *                                        Sends NO `as_org` — the same wire as before
+ *                                        this prompt existed. First push only.
  *   uniweb push --dry-run                Report what would be pushed; submit nothing
  *   uniweb push -o out.uwx               Write the .uwx file(s) per lane; submit nothing
  *   uniweb push --registry <url>         Override the backend origin
@@ -63,6 +67,8 @@ import { uploadSiteMedia, describeAssetRefusal } from '../backend/site-media.js'
 import { BackendClient } from '../backend/client.js'
 import { resolveSiteDir, resolveSiteBackend } from './deploy.js'
 import { warnIfContentDoesNotConform } from '../utils/conformance.js'
+import { readOrgFlag } from '../utils/args.js'
+import { checkFlags } from '../utils/flag-guard.js'
 import {
   makeModelResolver,
   readSyncCache,
@@ -73,7 +79,7 @@ import {
   ensureSiteExists,
   clearRemoteSyncStateIfUnbound,
   pushSyncPackages,
-  readSiteOrg
+  resolveSiteOrgForCreate
 } from '../backend/site-sync.js'
 
 // Re-exported for downstream importers (pull.js, push.test.js) that read these
@@ -108,6 +114,13 @@ function flagValue(args, name) {
 }
 
 export async function push(args = []) {
+  // An unrecognized flag is invisible to a literal scan, so it silently keeps the
+  // default — including for --backend, where the default can be production.
+  const bad = checkFlags('push', args)
+  if (bad) {
+    error(bad.message)
+    return { exitCode: 2 }
+  }
   const dryRun = args.includes('--dry-run')
   const output = flagValue(args, '-o') || flagValue(args, '--output')
   const tokenFlag = flagValue(args, '--token')
@@ -122,13 +135,6 @@ export async function push(args = []) {
 
   const siteDir = await resolveSiteDir(args, 'push')
 
-  // The acting org: the flag verbatim, else the one this site was CREATED under
-  // (`site.yml::$org`). The org is consumed by the create that mints `$uuid`, so
-  // a site that already exists is already owned — replaying the recorded handle
-  // reasserts that rather than choosing anything new. A site with no `$org`
-  // recorded sends no `as_org`, exactly as before.
-  const asOrg = flagValue(args, '--as-org') || readSiteOrg(siteDir)
-
   // Advisory only — warns and pushes. A malformed data block otherwise rides
   // the sync wire unchecked; see utils/conformance.js.
   await warnIfContentDoesNotConform(siteDir, { args })
@@ -146,6 +152,25 @@ export async function push(args = []) {
     command: 'Syncing'
   })
 
+  // WHO will own this site, if this push is the one that creates it. Resolved
+  // before any lane runs, because both create paths below consume it and neither
+  // should be reached with the question still open. A site that already exists
+  // resolves to null without asking — ownership was settled at its create.
+  const org = await resolveSiteOrgForCreate({
+    client,
+    siteDir,
+    args,
+    flag: readOrgFlag(args),
+    personal: args.includes('--personal'),
+    offline: !!output || dryRun
+  })
+  if (org.refused) {
+    error('Refusing to create this site without naming an owner.')
+    note(org.reason)
+    return { exitCode: 2 }
+  }
+  const asOrg = org.asOrg
+
   // Build BOTH directional packages (the producer side). Each carries its own
   // `index` — the per-entity source-file map for back-fill, correlated by submission
   // position. Non-local Models are fetched from the registry on demand. `priorHashes`

package/src/commands/register.js

@@ -81,6 +81,7 @@ import {
   promptSelect
 } from '../utils/workspace.js'
 import { isNonInteractive, getCliPrefix } from '../utils/interactive.js'
+import { checkFlags } from '../utils/flag-guard.js'
 
 const colors = {
   reset: '\x1b[0m',
@@ -265,6 +266,13 @@ export function foundationNeedsBuild(targetDir) {
 }
 
 export async function register(args = []) {
+  // See utils/flag-guard.js — an unrecognized flag is invisible to a
+  // literal scan, so it silently keeps the default (production, for --backend).
+  const badFlag = checkFlags('register', args)
+  if (badFlag) {
+    error(badFlag.message)
+    return { exitCode: 2 }
+  }
   jsonMode = args.includes('--json')
   jsonEmitted = false
   lastError = null

package/src/commands/status.js

@@ -30,6 +30,7 @@ import { BackendClient } from '../backend/client.js'
 import { readFlagValue } from '../utils/args.js'
 import { resolveLocalFoundation } from '../backend/foundation-bring-along.js'
 import { computeFoundationDigest } from '../utils/code-upload.js'
+import { checkFlags } from '../utils/flag-guard.js'
 
 const c = {
   reset: '\x1b[0m',
@@ -73,6 +74,14 @@ function splitFoundationRef(fnd) {
 }
 
 export async function status(args = []) {
+  // See utils/flag-guard.js — an unrecognized flag is invisible to a literal scan.
+  // Straight to stderr: this is a usage error, so it must not be mistaken for the
+  // status document even under --json.
+  const badFlag = checkFlags('status', args)
+  if (badFlag) {
+    console.error(`\x1b[31m✗\x1b[0m ${badFlag.message}`)
+    return { exitCode: 2 }
+  }
   const jsonMode = args.includes('--json')
   const remote = args.includes('--remote')
   const siteDir = await resolveSiteDir(args, 'status')

package/src/framework-index.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-08-12T22:01:32.128Z",
+  "generatedAt": "2026-08-12T23:11:50.036Z",
   "packages": {
     "@uniweb/build": {
       "version": "0.18.5",
@@ -73,7 +73,7 @@
       ]
     },
     "@uniweb/runtime": {
-      "version": "0.11.5",
+      "version": "0.11.7",
       "path": "framework/runtime",
       "deps": [
         "@uniweb/core",

package/src/index.js

@@ -1318,10 +1318,14 @@ ${colors.bright}Options:${colors.reset}
   --yes              Skip confirmations (CI); never block on a prompt
   --no-save          Skip the deploy.yml lastDeploy auto-save
   --no-validate      Skip the content-conformance check (it only warns)
-  --as-org @org      Publish under @org (membership-gated). Read only on a site's
-                     FIRST publish — that create decides which org owns the site,
-                     and whose storage its assets are charged to. Recorded as
-                     site.yml \$org and replayed, so it is never re-typed.
+  --org @org         Publish under @org (membership-gated; alias: --as-org). Read
+                     only on a site's FIRST publish — that create decides which org
+                     owns the site, and whose storage its assets are charged to.
+                     Recorded as site.yml \$org and replayed, so it is never
+                     re-typed. Without it, you are asked once.
+  --personal         Create the site under your personal account, deliberately.
+                     Only needed on a first publish, and only to answer the owner
+                     question without a prompt (CI, agents, scripts).
   --backend <url>    Backend origin (default: \$UNIWEB_REGISTER_URL or built-in)
   --token <bearer>   Auth bearer (skips \`uniweb login\`)
 `,
@@ -1697,7 +1701,8 @@ ${colors.bright}Global Options:${colors.reset}
 ${colors.bright}Publish Options:${colors.reset}
   --dry-run          Resolve everything; release/sync/POST nothing
   --yes              Skip confirmations (CI); never block on a prompt
-  --as-org @org      Publish under @org (first publish only; then remembered)
+  --org @org         Publish under @org (first publish only; then remembered)
+  --personal         Own the new site personally, deliberately (first publish only)
   --no-save          Skip the deploy.yml lastDeploy auto-save
   --no-validate      Skip the content-conformance check (it only warns)
   --backend <url>    Backend origin (default: \$UNIWEB_REGISTER_URL or built-in)

package/src/utils/args.js

@@ -20,6 +20,104 @@
  * @param {string} name — Including the leading dashes, e.g. '--host'.
  * @returns {string | null | undefined}
  */
+/**
+ * The org a site is created under. `--org` is the documented spelling; `--as-org`
+ * is a working alias.
+ *
+ * `--as-org` mirrors the wire (`?as_org=`) and names an *acting capacity* — the
+ * request is made as a member of that org, membership-gated. That is accurate, and
+ * it is also not the name anyone reaches for: asked in one day, the backend's docs
+ * said `--as-unit` and a second reader said `--org`; nobody produced `--as-org`.
+ * Since the flag's main job is answering *who owns this site*, `--org` is the name
+ * that matches the question, and the alias costs one `||` (the same shape
+ * `--backend` / `--registry` already uses).
+ *
+ * `||`, not `??`, on purpose: a valueless `--org` falls through to `--as-org`
+ * rather than shadowing it.
+ *
+ * @param {string[]} args
+ * @returns {string|null|undefined}
+ */
+export function readOrgFlag(args) {
+  return readFlagValue(args, '--org') || readFlagValue(args, '--as-org')
+}
+
+/**
+ * Every `--flag` / `-f` token in `args` that `known` does not list.
+ *
+ * The CLI reads flags by scanning argv for a literal, so an unrecognized flag is
+ * not an error — it is *invisible*, and whatever it was meant to change silently
+ * keeps its default. The sharp case is `--backend`: mistype it and the origin
+ * ladder falls through to the session, the saved config, or `https://uniweb.app`,
+ * so a command aimed at localhost can reach production. `--token` degrades the
+ * same way, to a stored session belonging to someone else.
+ *
+ * Scanning rules, chosen to avoid false positives (a wrong rejection is worse than
+ * a missed one — it breaks a working command):
+ *  - only tokens beginning with `-` are candidates; a VALUE is never one unless it
+ *    itself looks like a flag, which `readFlagValue` already refuses to consume;
+ *  - `--flag=value` is checked on the name half;
+ *  - a bare `--` ends flag scanning, the POSIX convention;
+ *  - a lone `-` is a value (stdin), not a flag.
+ *
+ * @param {string[]} args
+ * @param {string[]} known - every flag this command accepts, with dashes
+ * @returns {string[]} the unrecognized tokens, in order, deduped
+ */
+export function findUnknownFlags(args, known) {
+  const set = new Set(known)
+  const out = []
+  for (const raw of args) {
+    if (raw === '--') break
+    if (raw === '-' || !raw.startsWith('-')) continue
+    const name = raw.split('=')[0]
+    if (set.has(name) || out.includes(name)) continue
+    out.push(name)
+  }
+  return out
+}
+
+/** Levenshtein distance, small and iterative — used only for a suggestion. */
+function editDistance(a, b) {
+  const prev = Array.from({ length: b.length + 1 }, (_, i) => i)
+  for (let i = 1; i <= a.length; i++) {
+    let diag = prev[0]
+    prev[0] = i
+    for (let j = 1; j <= b.length; j++) {
+      const tmp = prev[j]
+      prev[j] = Math.min(
+        prev[j] + 1,
+        prev[j - 1] + 1,
+        diag + (a[i - 1] === b[j - 1] ? 0 : 1)
+      )
+      diag = tmp
+    }
+  }
+  return prev[b.length]
+}
+
+/**
+ * The closest known flag to `flag`, or null when nothing is close enough.
+ * The threshold scales with length so `--org` → `--as-org` is offered while two
+ * unrelated short flags are not.
+ * @param {string} flag
+ * @param {string[]} known
+ * @returns {string|null}
+ */
+export function didYouMean(flag, known) {
+  let best = null
+  let bestD = Infinity
+  for (const k of known) {
+    const d = editDistance(flag, k)
+    if (d < bestD) {
+      bestD = d
+      best = k
+    }
+  }
+  const limit = Math.max(2, Math.floor(flag.length / 3))
+  return best && bestD <= limit ? best : null
+}
+
 export function readFlagValue(args, name) {
   const eqPrefix = name + '='
   for (let i = 0; i < args.length; i++) {

package/src/utils/flag-guard.js

@@ -0,0 +1,133 @@
+/**
+ * Reject unrecognized flags on the backend verbs.
+ *
+ * Every one of these commands can send data to, or authenticate against, a remote
+ * host — and the CLI resolves flags by scanning argv for a literal, so a flag it
+ * does not recognize does not fail: it *disappears*, and the thing it was meant to
+ * change silently keeps its default.
+ *
+ * That is tolerable for a cosmetic flag and dangerous for these two:
+ *
+ *   --backend   mistyped ⇒ the origin ladder falls through to the session origin,
+ *               ~/.uniweb/config.json, and finally https://uniweb.app. A command
+ *               aimed at a local backend can reach production.
+ *   --token     mistyped ⇒ falls back to the stored session, so the request is
+ *               made as whoever is logged in rather than whoever was intended.
+ *
+ * Neither produces an error today; both produce a plausible success against the
+ * wrong host. This turns that class into one sentence.
+ *
+ * ⚠️ A wrong rejection is worse than a missed one — it breaks an invocation that
+ * works — so the per-command lists must be complete, INCLUDING flags read by
+ * helpers rather than by the command file itself. Two live examples: `--no-validate`
+ * is consumed inside `utils/conformance.js`, and `--yes` inside
+ * `backend/foundation-bring-along.js`. Grepping only the command's own source
+ * misses both. When you add a flag anywhere on one of these paths, add it here.
+ */
+
+import { findUnknownFlags, didYouMean } from './args.js'
+
+/** Accepted by every command, wherever they are actually consumed. */
+const GLOBAL = ['--non-interactive', '--help', '-h']
+
+/**
+ * Login-method flags. Any verb that can hit an unauthenticated backend may fall
+ * into `ensureRegistryAuth`, which hands `args` to the login picker — so these are
+ * genuinely reachable from all of them, not just from `uniweb login`.
+ */
+const AUTH = ['--browser', '--password', '--token-paste']
+
+/**
+ * Flags a verb inherits by importing `commands/deploy.js` for `resolveSiteDir` /
+ * `resolveSiteBackend`. Inert on these verbs, and listed rather than filtered:
+ * accepting a flag that does nothing is exactly the pre-guard behaviour, while
+ * rejecting one that works is a broken command. The guard's job is catching
+ * `--backed`, not policing inert-but-valid spellings.
+ */
+const VIA_DEPLOY = ['--target', '--host', '--no-save']
+
+/**
+ * Per-verb flag sets. Derived by scanning each command for dash-literals AND the
+ * helpers it calls — not from the help text, which has drifted from the parser in
+ * both directions (`--as-org` was implemented and undocumented; `--yes` is
+ * documented on `publish` and consumed two files away).
+ */
+const VERBS = {
+  push: [
+    '--all', '--as-org', '--org', '--backend', '--dry-run', '--force',
+    '--foundation', '--output', '-o', '--personal', '--registry', '--token',
+    // read in utils/conformance.js and backend/site-sync.js respectively —
+    // neither appears in push.js
+    '--no-validate', '--yes', ...VIA_DEPLOY
+  ],
+  publish: [
+    '--as-org', '--org', '--backend', '--dry-run', '--force', '--foundation',
+    '--personal', '--registry', '--token',
+    // read in utils/conformance.js, backend/site-sync.js, and
+    // backend/foundation-bring-along.js — none appear in publish.js
+    '--no-validate', '--yes', '--no-verify', ...VIA_DEPLOY
+  ],
+  pull: [
+    '--backend', '--content-only', '--dry-run', '--force', '--merge',
+    '--no-collections', '--no-delete', '--no-prune', '--registry', '--token',
+    // via backend/site-sync.js (the owner resolver) and utils/conformance.js
+    '--yes', '--org', '--as-org', '--no-validate', ...VIA_DEPLOY
+  ],
+  clone: [
+    '--backend', '--content-only', '--no-collections', '--path', '--project',
+    '--registry', '--token', '--org', '--as-org'
+  ],
+  register: [
+    '--backend', '--dry-run', '--json', '--output', '-o', '--registry',
+    '--schema-only', '--scope', '--token', '--org', '--as-org'
+  ],
+  status: [
+    '--backend', '--json', '--registry', '--remote', '--token', '--dry-run',
+    '--force', '--no-verify', '--no-validate', '--yes', '--org', '--as-org',
+    ...VIA_DEPLOY
+  ]
+}
+
+/**
+ * The accepted set per verb: its own flags, plus the login-method flags every
+ * backend verb can reach, plus the globals.
+ *
+ * Derived from each verb's IMPORT GRAPH, not from its own source and not from the
+ * help text — `test/flag-guard-coverage.test.js` walks that graph and fails if a
+ * verb can honour a flag this list omits. Deliberately an over-approximation: a
+ * flag accepted here but inert costs nothing (it was ignored before the guard
+ * existed), while one rejected here breaks a working command.
+ */
+export const VERB_FLAGS = Object.fromEntries(
+  Object.entries(VERBS).map(([verb, flags]) => [
+    verb,
+    [...new Set([...flags, ...AUTH])]
+  ])
+)
+
+/**
+ * Check `args` against the verb's accepted set. Returns null when everything is
+ * recognized, or a ready-to-print message naming the first offender (plus a
+ * suggestion when one is close).
+ *
+ * Reports ONE flag rather than all of them: the first is usually the cause, and a
+ * list invites skimming past the suggestion, which is the actionable half.
+ *
+ * @param {string} verb - a key of VERB_FLAGS
+ * @param {string[]} args - the argv slice for this command
+ * @returns {{ flag: string, message: string, suggestion: string|null }|null}
+ */
+export function checkFlags(verb, args = []) {
+  const known = VERB_FLAGS[verb]
+  if (!known) return null
+  const all = [...known, ...GLOBAL]
+  const unknown = findUnknownFlags(args, all)
+  if (!unknown.length) return null
+
+  const flag = unknown[0]
+  const suggestion = didYouMean(flag, all)
+  const lines = [`Unknown flag \`${flag}\` for \`uniweb ${verb}\`.`]
+  if (suggestion) lines.push(`  Did you mean \`${suggestion}\`?`)
+  lines.push(`  Run \`uniweb ${verb} --help\` for the accepted flags.`)
+  return { flag, suggestion, message: lines.join('\n') }
+}

package/src/utils/git.js

@@ -18,8 +18,8 @@
  */
 
 import { execFileSync } from 'node:child_process'
-import { readFileSync } from 'node:fs'
-import { join } from 'node:path'
+import { readFileSync, realpathSync } from 'node:fs'
+import { join, relative } from 'node:path'
 import yaml from 'js-yaml'
 
 /**
@@ -85,11 +85,44 @@ export function isGitRepo(dir) {
  * as modified here: a section file that exists only locally is not on the backend,
  * so a pruning pull deletes it — losing work that was never committed anywhere.
  *
- * @returns {string[]|null} repo-relative-ish paths as git reports them, or `null`
- *   when this isn't a git work tree (distinct from `[]`, which means "clean").
+ * ⛔ **Returned relative to `dir`, which is NOT what git prints.** `--porcelain`
+ * paths are always relative to the REPOSITORY ROOT, whatever directory it runs
+ * in, so they only coincide with `dir`-relative when the site *is* the repo root.
+ * Both callers do `join(siteDir, rel)` with the result, so the un-normalized form
+ * was wrong for every nested layout — a site at `myproject/site/` inside a repo.
+ *
+ * What that cost, measured 2026-08-12: pull exempts its own previous output from
+ * the uncommitted-work guard by looking each dirty path up in a record keyed
+ * `dir`-relative (`utils/pull-written.js`). Given `myproject/site/site.yml` the
+ * lookup missed, so **pull refused on files pull itself had written** — the exact
+ * false alarm that record exists to prevent, and the one its own comment warns
+ * teaches people to reach for `--force`. `captureLocalWork` had the same defect
+ * one door along: it reads each path back with `join(siteDir, rel)`.
+ *
+ * The earlier `@returns` said "repo-relative-ish paths as git reports them" while
+ * the summary above said "relative to `dir`" — the ambiguity was noticed and left,
+ * and both callers had picked the other reading.
+ *
+ * @returns {string[]|null} paths relative to `dir`, or `null` when this isn't a
+ *   git work tree (distinct from `[]`, which means "clean").
  */
 export function uncommittedUnder(dir, relPaths) {
   if (!isGitRepo(dir)) return null
+  // ⚠️ Both sides must be REAL paths before `relative` can compare them.
+  // `rev-parse --show-toplevel` resolves symlinks; the caller's `dir` usually has
+  // not. On macOS that alone breaks it — `/var` is a symlink to `/private/var`,
+  // so a repo under the temp dir yields a root of `/private/var/…` against a dir
+  // of `/var/…`, and `relative` walks all the way up and back down. The result is
+  // a valid-looking path that matches nothing, i.e. the same silent miss this
+  // normalization exists to fix. Any symlinked checkout does it, not just tmp.
+  let root
+  let base
+  try {
+    root = git(['rev-parse', '--show-toplevel'], dir).trim()
+    base = realpathSync(dir)
+  } catch {
+    return null
+  }
   try {
     const out = git(
       ['status', '--porcelain', '--untracked-files=all', '--', ...relPaths],
@@ -102,6 +135,12 @@ export function uncommittedUnder(dir, relPaths) {
         // porcelain v1: XY<space>path, and a rename is "orig -> new".
         .map((line) => line.slice(3).trim())
         .map((p) => (p.includes(' -> ') ? p.split(' -> ')[1] : p))
+        // Porcelain paths are repo-root-relative; callers want them relative to
+        // `dir`. Quoted paths (git quotes names with spaces or non-ASCII when
+        // `core.quotePath` is on) are left alone rather than half-decoded — a
+        // wrong path is worse than an unmatched one here, since an unmatched
+        // path merely stays "dirty" and the guard errs toward refusing.
+        .map((p) => (p.startsWith('"') ? p : relative(base, join(root, p))))
         .filter(Boolean)
     )
   } catch {

package/src/utils/pull-written.js

@@ -0,0 +1,127 @@
+/**
+ * The record of what a machine wrote into a site project — pull's own output.
+ *
+ * ## What it is for
+ *
+ * `uniweb pull` refuses to run when there are uncommitted changes under the files
+ * it rewrites, because it reconciles the working tree to the backend and would
+ * overwrite them. That guard needs one distinction to be useful: **a file the
+ * user edited** versus **a file a previous pull wrote and nobody has touched
+ * since**. Without it the guard cries wolf — pull rewrites the tree, so the next
+ * pull sees its own output as uncommitted work and refuses, listing files the
+ * user never touched. A guard that fires on nothing teaches people to reach for
+ * `--force`, which is the destructive option.
+ *
+ * So each write is recorded with a content hash, and a dirty path whose hash
+ * still matches is not user work.
+ *
+ * ## Why it lives here rather than in `pull.js`
+ *
+ * `uniweb clone` has the same claim to make and cannot make it from there.
+ * `pull.js` statically imports `@uniweb/build`, which resolves from the
+ * *project's* `node_modules` — and `clone` runs before a project exists (see
+ * `utils/uwx-read.js` for the same constraint on the `.uwx` reader).
+ *
+ * Clone scaffolds `site.yml` and `theme.yml` and then delegates to `pull`, so
+ * without this the delegated pull sees clone's own scaffolding as uncommitted
+ * user work and refuses — on a project created seconds earlier, where there is no
+ * user work to protect. Clone records what it wrote; the guard then exempts those
+ * files **for the right reason** rather than being overridden.
+ *
+ * Nothing here imports `@uniweb/build`, and nothing here may start to.
+ */
+
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs'
+import { createHash } from 'node:crypto'
+import { join, dirname, relative } from 'node:path'
+
+/** Where the record lives — gitignored, beside the other per-site caches. */
+export function writtenCachePath(siteDir) {
+  return join(siteDir, '.uniweb', 'pull-written.json')
+}
+
+/**
+ * @param {string} siteDir
+ * @returns {{files: Record<string,string>, deleted: string[]}}
+ */
+export function readWritten(siteDir) {
+  try {
+    const o = JSON.parse(readFileSync(writtenCachePath(siteDir), 'utf8'))
+    return {
+      files: o && typeof o.files === 'object' ? o.files : {},
+      deleted: Array.isArray(o?.deleted) ? o.deleted : []
+    }
+  } catch {
+    return { files: {}, deleted: [] }
+  }
+}
+
+/**
+ * Record files as machine-written, by absolute path.
+ *
+ * MERGE, don't replace. A conditional pull that 304s writes nothing, and a
+ * partial pull writes only some lanes — in both cases the previous record is
+ * still "the last thing written there". Replacing would forget those paths and
+ * the next pull would see them as the user's work again, which is the false alarm
+ * this cache exists to prevent. A stale entry for a file that no longer exists is
+ * harmless: the hash read fails and it counts as a local change.
+ *
+ * @param {string} siteDir
+ * @param {string[]} absPaths - files just written
+ * @param {string[]} [deletedAbs] - files just pruned
+ */
+export function recordWritten(siteDir, absPaths, deletedAbs = []) {
+  const prior = readWritten(siteDir)
+  const files = prior.files
+  for (const abs of absPaths) {
+    try {
+      files[relative(siteDir, abs)] = createHash('sha256')
+        .update(readFileSync(abs))
+        .digest('hex')
+    } catch {
+      /* deleted or unreadable — nothing to remember */
+    }
+  }
+  // Pull PRUNES too, and a deletion is a dirty path git reports just like an edit.
+  // Without recording them, pull's own pruning reads as the user having deleted
+  // files — the same false alarm as its writes, arriving by the other door.
+  const deleted = [
+    ...new Set([...prior.deleted, ...deletedAbs.map((a) => relative(siteDir, a))])
+  ]
+  try {
+    mkdirSync(dirname(writtenCachePath(siteDir)), { recursive: true })
+    writeFileSync(
+      writtenCachePath(siteDir),
+      JSON.stringify({ version: 1, files, deleted }, null, 2) + '\n'
+    )
+  } catch {
+    /* best-effort: losing it only costs a spurious refusal */
+  }
+}
+
+/**
+ * Is this dirty path just machine output nobody has touched?
+ *
+ * The hash comparison is what keeps the guard honest: a scaffolded or pulled file
+ * the user then EDITED no longer matches, so it counts as their work and the
+ * refusal stands.
+ *
+ * @param {string} siteDir
+ * @param {string} relPath
+ * @param {{files: Record<string,string>, deleted: string[]}} written
+ * @returns {boolean}
+ */
+export function isPullOutput(siteDir, relPath, written) {
+  let exists = true
+  let hash = null
+  try {
+    hash = createHash('sha256')
+      .update(readFileSync(join(siteDir, relPath)))
+      .digest('hex')
+  } catch {
+    exists = false
+  }
+  // Absent because pull pruned it — not because the user deleted it.
+  if (!exists) return written.deleted.includes(relPath)
+  return written.files[relPath] === hash
+}