uniweb 1.20.3 → 1.21.0

package/src/commands/update.js

@@ -44,7 +44,7 @@ import { join } from 'node:path'
 import { spawn } from 'node:child_process'
 import prompts from 'prompts'
 
-import { findWorkspaceRoot } from '../utils/workspace.js'
+import { findUniwebWorkspace } from '../utils/workspace.js'
 import {
   readAgentsVersion,
   refreshAgentsContent,
@@ -108,28 +108,6 @@ function isNpxInvocation() {
   return p.includes('/_npx/')
 }
 
-/**
- * Find a *Uniweb* workspace root from cwd. Stricter than findWorkspaceRoot
- * — also requires that the workspace's root package.json declares uniweb
- * as a dep or devDep. Otherwise we'd write AGENTS.md and edit package.json
- * files in unrelated monorepos.
- */
-function findUniwebWorkspace(cwd) {
-  const workspaceDir = findWorkspaceRoot(cwd)
-  if (!workspaceDir) return null
-  const pkgPath = join(workspaceDir, 'package.json')
-  if (!existsSync(pkgPath)) return null
-  try {
-    const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'))
-    const hasUniwebDep = !!(
-      pkg.devDependencies?.uniweb || pkg.dependencies?.uniweb
-    )
-    return hasUniwebDep ? workspaceDir : null
-  } catch {
-    return null
-  }
-}
-
 /**
  * Trailing advisory: a newer CLI exists, and this run could not have used it.
  *

package/src/index.js

@@ -152,6 +152,8 @@ function getCliVersion() {
 // against *this* CLI's version matrix — when run from a (newer) global
 // install that's the whole point; delegating to the project-local copy
 // would align the project to the version it already has, i.e. a no-op.
+// `start` is here because a project's older CLI may not have it, and its
+// guide describes the CLI that prints it.
 const STANDALONE_COMMANDS = new Set([
   'create',
   'clone',
@@ -161,6 +163,7 @@ const STANDALONE_COMMANDS = new Set([
   '-v',
   'login',
   'logout',
+  'start',
   'update'
 ])
 
@@ -347,6 +350,10 @@ async function createFromPackageTemplates(
     {
       projectName,
       workspaceGlobs: ['site', 'src'],
+      packages: [
+        { path: 'src', foundation: true },
+        { path: 'site', site: true }
+      ],
       scripts: {
         dev: 'uniweb dev',
         build: 'uniweb build',
@@ -413,6 +420,7 @@ async function createBlankWorkspace(projectDir, projectName, options = {}) {
     {
       projectName,
       workspaceGlobs: [],
+      packages: [],
       scripts: {
         build: 'uniweb build'
       }
@@ -480,6 +488,8 @@ async function createFromContentTemplate(
     {
       projectName,
       workspaceGlobs,
+      // `type` is foundation, extension or site: the README's table reads it as a flag.
+      packages: placed.map((p) => ({ path: p.relativePath, [p.type]: true })),
       scripts
     },
     { onProgress, onWarning }
@@ -696,6 +706,19 @@ async function main() {
     // Commands that need @uniweb/build will get a helpful error via importProjectCommand().
   }
 
+  // `start` — the guide an AI agent reads first (commands/start.js). Answered before the
+  // update check: it asks nothing, writes nothing and makes no request, and the check can
+  // write a cache and fetch.
+  if (command === 'start') {
+    if (args.slice(1).some((a) => a === '--help' || a === '-h')) {
+      printCommandHelp('start')
+      return
+    }
+    const { start } = await import('./commands/start.js')
+    await start(args.slice(1))
+    return
+  }
+
   // Update check for global installs.
   //
   //   - `create` / `clone` STOP when a newer release exists, before anything is
@@ -853,7 +876,7 @@ async function main() {
     await exitWhenDrained(result?.exitCode ?? 0)
   }
 
-  // Handle status command (dynamic import — offline emit via @uniweb/build)
+  // Handle status command (dynamic import — its checks reach @uniweb/build)
   if (command === 'status') {
     const { status } = await importProjectCommand('./commands/status.js')
     const result = await status(args.slice(1))
@@ -1132,6 +1155,9 @@ async function main() {
   if (nonInteractive && !projectName) {
     error(`Missing project name.\n`)
     log(`Usage: ${prefix} create <project-name> [--template <name>] [--blank]`)
+    log(
+      `\nAn AI agent building a site for someone: run ${colors.cyan}npx uniweb@latest start${colors.reset} first — it says how, step by step.`
+    )
     await exitWhenDrained(1)
   }
 
@@ -1389,6 +1415,10 @@ async function main() {
       `  ${colors.cyan}${runCmd(recPm, 'dev')}${colors.reset}   ${colors.dim}# start the dev server${colors.reset}`
     )
   }
+  log('')
+  log(
+    `  ${colors.bright}AGENTS.md${colors.reset} is the project's manual, for you and for AI agents: its Part 0 says where to begin.`
+  )
   if (recPm !== 'pnpm') {
     log('')
     log(
@@ -1529,6 +1559,21 @@ ${colors.bright}Examples:${colors.reset}
   uniweb create .                                # Scaffold into current dir
   uniweb create . --template docs                # In place + a content template
   uniweb create . --name=my-app                  # In place, explicit slug
+`,
+    start: `
+${colors.cyan}${colors.bright}uniweb start${colors.reset} ${colors.dim}— How an AI agent begins a Uniweb site${colors.reset}
+
+${colors.bright}Usage:${colors.reset}
+  npx uniweb@latest start    Print the guide, in Markdown
+
+A short guide for an AI agent building a website for someone: create a
+project, read its AGENTS.md, run it, sign the person in, and bring the site
+into the Uniweb app. The person only uses their browser, to sign in and to
+pay when the site goes live; the guide has the agent run every command.
+
+Inside a Uniweb project it starts from that project instead of creating one.
+It asks nothing, writes nothing and makes no request, so it is safe to run
+anywhere. To run a site's dev server, use \`uniweb dev\`.
 `,
     dev: `
 ${colors.cyan}${colors.bright}uniweb dev${colors.reset} ${colors.dim}— Start a dev server for a site${colors.reset}
@@ -1725,6 +1770,38 @@ ${colors.bright}Options:${colors.reset}
   --non-interactive  Fail with usage info instead of prompting
 
 Exit code is 1 if errors are found (warnings only → exit 0).
+`,
+    status: `
+${colors.cyan}${colors.bright}uniweb status${colors.reset} ${colors.dim}— What to know before working on a site, and what to run about it${colors.reset}
+
+${colors.bright}Usage:${colors.reset}
+  uniweb status [options]
+
+Run it when you begin, before you push, and after a command refuses. It checks:
+
+  git      conflicts, a merge waiting, the site's files not committed, the git remote
+  app      the session, what changed on the backend since this copy last synced,
+           what is not pushed, whether the site is live, who has it open in the app,
+           the foundation
+  uniweb   whether a newer release is out
+  health   doctor's findings
+  dev      the dev server
+
+and ends with the steps to take, in the order to take them. A step marked
+"ask the person first" is theirs to decide — going live, for one.
+
+It changes nothing and asks nothing: with no session it says how to sign in.
+A check it could not make says so, and is never reported as fine.
+
+${colors.bright}Options:${colors.reset}
+  --offline          Ask nothing beyond this machine — no backend, npm, git remote
+                     or dev server
+  --json             One JSON document: { schema: 1, checks: [...], next: [...] }
+  --org @org         The workspace to ask the backend in, for this command only
+  --personal         Your personal workspace, for this command only
+
+Exit code is 0 whenever a status is produced, 2 for a usage error — read the
+document, not the exit code, for what needs doing.
 `,
     validate: `
 ${colors.cyan}${colors.bright}uniweb validate${colors.reset} ${colors.dim}— Check your content against your foundation's data schemas${colors.reset}
@@ -2075,6 +2152,7 @@ ${colors.bright}Usage:${colors.reset}
   uniweb <command> [options]
 
 ${colors.bright}Commands:${colors.reset}
+  start              How an AI agent begins a site (a guide; changes nothing)
   create [name]      Create a new project
   clone <site-uuid>  Clone a backend site into a local file project
   add <type> [name]  Add a foundation, site, or extension to a project
@@ -2091,7 +2169,7 @@ ${colors.bright}Commands:${colors.reset}
   pull               Pull a site's content from the backend
   refresh            Catch up with the git remote AND the backend (never pushes)
   sync               Catch up, then push (refresh + push)
-  status             Show a site's sync state (unpushed content, foundation)
+  status             What changed in the app, in git and in Uniweb — and what to run
   forget             Forget a backend, or --all to make a copied project a new one
   site <cmd>         The sites in a workspace: list, unpublish, delete
   inspect <path>     Inspect parsed content shape of a markdown file or folder

package/src/utils/code-upload.js

@@ -119,33 +119,6 @@ export function uploadOrder(files) {
   return [...rest, ...entry]
 }
 
-/**
- * The deterministic content digest of a built foundation — the freshness
- * fingerprint `register` records and `publish`/`status` later compare against
- * (shipping-model.md §4.1). It answers one question — "did the foundation change
- * since it was released?" — with NO local state, so it has to be reproducible:
- * the same source, built on any machine, must yield the same digest.
- *
- * Algorithm (§4.1): `sha256` over the newline-joined, SORTED list of the
- * per-file `sha256` (hex) of exactly what `register` ships for a foundation —
- *   - the code-upload set (`collectDistFiles`: entry + chunks + assets, with
- *     `meta/**` and `*.map` already excluded), and
- *   - the schema source (`meta/schema.json`) — NOT uploaded as a file, and not
- *     sent verbatim: register submits its *content* as the foundation-schema
- *     ENTITY in the `.uwx`. It's read here only to fold the schema into the
- *     local freshness fingerprint (so a schema edit shows as "changed").
- * Hashes are SORTED (so the digest is order-independent) and taken over file
- * CONTENTS, not names, so content-hashed chunk filenames don't perturb it.
- * Returns null when there's nothing to hash (no usable dist), so callers skip
- * cleanly rather than fingerprinting emptiness.
- *
- * The result is OPAQUE to the backend — it stores the string and returns it
- * verbatim; the framework owns the algorithm end-to-end and can change it
- * freely (a digest only ever compares against one the same CLI computed).
- *
- * @param {string} distDir - the built `dist/` directory
- * @returns {string|null} `sha256:<hex>` or null when there's nothing to hash
- */
 /**
  * The `@uniweb/runtime` version a built foundation linked against, from
  * `dist/runtime-pin.json`.
@@ -180,6 +153,33 @@ export function readRuntimePin(distDir) {
   }
 }
 
+/**
+ * The deterministic content digest of a built foundation — the freshness
+ * fingerprint `register` records and `publish`/`status` later compare against
+ * (shipping-model.md §4.1). It answers one question — "did the foundation change
+ * since it was released?" — with NO local state, so it has to be reproducible:
+ * the same source, built on any machine, must yield the same digest.
+ *
+ * Algorithm (§4.1): `sha256` over the newline-joined, SORTED list of the
+ * per-file `sha256` (hex) of exactly what `register` ships for a foundation —
+ *   - the code-upload set (`collectDistFiles`: entry + chunks + assets, with
+ *     `meta/**` and `*.map` already excluded), and
+ *   - the schema source (`meta/schema.json`) — NOT uploaded as a file, and not
+ *     sent verbatim: register submits its *content* as the foundation-schema
+ *     ENTITY in the `.uwx`. It's read here only to fold the schema into the
+ *     local freshness fingerprint (so a schema edit shows as "changed").
+ * Hashes are SORTED (so the digest is order-independent) and taken over file
+ * CONTENTS, not names, so content-hashed chunk filenames don't perturb it.
+ * Returns null when there's nothing to hash (no usable dist), so callers skip
+ * cleanly rather than fingerprinting emptiness.
+ *
+ * The result is OPAQUE to the backend — it stores the string and returns it
+ * verbatim; the framework owns the algorithm end-to-end and can change it
+ * freely (a digest only ever compares against one the same CLI computed).
+ *
+ * @param {string} distDir - the built `dist/` directory
+ * @returns {string|null} `sha256:<hex>` or null when there's nothing to hash
+ */
 export function computeFoundationDigest(distDir) {
   const hashes = collectDistFiles(distDir).map((f) => f.sha256)
   // The schema rides in the register `.uwx`, not the code-upload set, so fold

package/src/utils/flag-guard.js

@@ -109,11 +109,14 @@ const VERBS = {
    */
   site: ['--json', '--yes', '--org', '--personal'],
   status: [
-    '--json', '--remote', '--dry-run',
+    '--json', '--offline', '--dry-run',
     '--force', '--no-verify', '--no-validate', '--yes', '--org', '--personal',
     // inert here, reachable through the bring-along module status imports for
     // `resolveLocalFoundation` — listed per the over-approximation note above
-    '--no-release', '--bump', ...VIA_DEPLOY
+    '--no-release', '--bump', ...VIA_DEPLOY,
+    // inert here too, reachable through `commands/pull.js`, whose lane readers status uses
+    // to ask what changed on the backend (`backend/app-changes.js`)
+    '--no-assets', '--no-delete', '--no-prune', '--no-records', '--content-only'
   ],
   /**
    * `refresh` = `git pull`, then a DELEGATED `pull`.
@@ -249,6 +252,18 @@ export function checkFlags(verb, args = []) {
       message: `\`--as-org\` is retired — use \`--org @org\` (e.g. \`uniweb ${verb} --org @acme\`).`
     }
   }
+  // ⭐ `status --remote` is RETIRED (2026-10-26): a status asks the backend by default, and
+  // `--offline` keeps it to this machine.
+  if (flag === '--remote' && verb === 'status') {
+    return {
+      flag,
+      suggestion: null,
+      message: [
+        '`uniweb status` has no `--remote`: it asks the backend by default now.',
+        '  Run `uniweb status`, or `uniweb status --offline` to ask nothing beyond this machine.'
+      ].join('\n')
+    }
+  }
   // ⭐ `pull --merge` is RETIRED (2026-10-17): in a repository a pull always merges — from the
   // newest sync point the history holds (`utils/sync-point.js`) — and outside one there is
   // nothing to merge against.

package/src/utils/git.js

@@ -21,7 +21,7 @@
  * project counted as inside the harness, so `refresh` ran `git pull` on the harness.
  */
 
-import { execFileSync } from 'node:child_process'
+import { execFile, execFileSync } from 'node:child_process'
 import { readFileSync } from 'node:fs'
 import { join } from 'node:path'
 import yaml from 'js-yaml'
@@ -198,6 +198,96 @@ export function pullRemote(dir) {
   }
 }
 
+/**
+ * The branch HEAD is on and the one it tracks — `{ branch, remote, merge, tracking }`
+ * (`main`, `origin`, `refs/heads/main`, `origin/main`) — or null: no branch, or no upstream.
+ */
+export function upstreamOf(dir) {
+  try {
+    const branch = git(['symbolic-ref', '--short', '-q', 'HEAD'], dir).trim()
+    if (!branch) return null
+    const remote = git(['config', '--get', `branch.${branch}.remote`], dir).trim()
+    const merge = git(['config', '--get', `branch.${branch}.merge`], dir).trim()
+    const tracking = git(['rev-parse', '--abbrev-ref', '--symbolic-full-name', '@{u}'], dir).trim()
+    return remote && merge && tracking ? { branch, remote, merge, tracking } : null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * The commits HEAD has that its upstream lacks (`ahead`), and the reverse (`behind`) — as of
+ * the last fetch, which is all a repository knows without asking its remote. Null with no
+ * upstream.
+ */
+export function aheadBehind(dir) {
+  try {
+    const [behind, ahead] = git(['rev-list', '--left-right', '--count', '@{u}...HEAD'], dir)
+      .trim()
+      .split(/\s+/)
+      .map(Number)
+    return Number.isInteger(ahead) && Number.isInteger(behind) ? { ahead, behind } : null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Does the git remote hold commits HEAD does not — teammates' work since the last fetch?
+ * Asked with `git ls-remote`, which fetches nothing and writes nothing, so a read-only
+ * command can ask it.
+ *
+ * ⛔ IT NEVER PROMPTS. A credential prompt would hang a command run by an agent, so: no
+ * terminal prompt (`GIT_TERMINAL_PROMPT=0`), no credential manager window
+ * (`GCM_INTERACTIVE=never`), ssh in batch mode with a connect timeout — added to the ssh
+ * command the person configured, never instead of it — and the whole call bounded.
+ *
+ * @param {string} dir
+ * @param {{ timeoutMs?: number }} [opts]
+ * @returns {Promise<{ moved: boolean, upstream: object } | null>} null when there is no
+ *   upstream, or the remote did not answer in time
+ */
+export async function remoteMoved(dir, { timeoutMs = 5000 } = {}) {
+  const upstream = upstreamOf(dir)
+  if (!upstream) return null
+  let ssh = process.env.GIT_SSH_COMMAND || ''
+  try {
+    ssh ||= git(['config', '--get', 'core.sshCommand'], dir).trim()
+  } catch {
+    // not configured
+  }
+  const env = {
+    ...process.env,
+    GIT_TERMINAL_PROMPT: '0',
+    GCM_INTERACTIVE: 'never',
+    GIT_SSH_COMMAND: `${ssh || 'ssh'} -o BatchMode=yes -o ConnectTimeout=${Math.ceil(timeoutMs / 1000)}`
+  }
+  let out
+  try {
+    out = await new Promise((resolve, reject) => {
+      execFile('git', ['ls-remote', '--', upstream.remote, upstream.merge], { cwd: dir, env, timeout: timeoutMs, encoding: 'utf8' }, (err, stdout) =>
+        err ? reject(err) : resolve(stdout)
+      )
+    })
+  } catch {
+    return null
+  }
+  const head = String(out)
+    .split('\n')
+    .map((line) => line.split('\t'))
+    .find(([, ref]) => ref === upstream.merge)?.[0]
+  if (!head) return null
+  // A head HEAD already holds — fetched earlier, or HEAD's own — is nothing new.
+  let held = false
+  try {
+    git(['merge-base', '--is-ancestor', head, 'HEAD'], dir)
+    held = true
+  } catch {
+    held = false
+  }
+  return { moved: !held, upstream }
+}
+
 /**
  * Provenance for a deploy record: `{ sha, dirty }`, or null outside a repo.
  * Answers "what is actually live?" later, which a version number cannot.

package/src/utils/registry-auth.js

@@ -311,12 +311,15 @@ export async function ensureRegistryAuth({
       `\x1b[31m✗\x1b[0m ${reason} ${command} requires a Uniweb account, and the CLI is non-interactive (CI / no TTY / --non-interactive).`
     )
     console.error('  Options:')
-    console.error(`    • Set UNIWEB_TOKEN to a bearer token.`)
+    // ⛔ Not "run `login` interactively": with no one at the terminal this is often an AI
+    // agent working for someone who does not use one, and it passes the line on. A browser
+    // sign-in asks nothing here. *(It said "interactively" until 2026-10-26.)*
     console.error(
-      `    • Set UNIWEB_USERNAME + UNIWEB_PASSWORD to log in non-interactively.`
+      `    • Run \`${prefix} login --browser\` first — someone signs in, in a browser on this machine — then re-run.`
     )
+    console.error(`    • Set UNIWEB_TOKEN to a bearer token.`)
     console.error(
-      `    • Run \`${prefix} login\` interactively first, then re-run.`
+      `    • Set UNIWEB_USERNAME + UNIWEB_PASSWORD to log in non-interactively.`
     )
     process.exit(1)
   }
@@ -515,7 +518,9 @@ export async function awaitBrowserCallback({
       res.end(
         `<!doctype html><html><body style="font-family:system-ui,sans-serif;text-align:center;padding:60px">` +
           `<h2 style="color:${failed ? '#dc2626' : '#16a34a'}">${failed ? errTitle : okTitle}</h2>` +
-          `<p>You can close this tab and return to your terminal.</p></body></html>`
+          // ⛔ Not "return to your terminal": the person signing in may have none — an AI
+          // agent ran the login for them. *(It said so until 2026-10-26.)*
+          `<p>You can close this tab.</p></body></html>`
       )
       cleanup()
       resolve(failed ? { error: verdict.error } : { value: verdict.value })
@@ -817,11 +822,16 @@ export async function runRegistryLogin({ apiBase, args = [] } = {}) {
       } else {
         // Only what works without a terminal: `--password` and `--token-paste` prompt. The
         // command keeps the backend named, or re-run as printed it would go to the default.
+        // ⭐ `--browser` first: it asks nothing here, and it is the way for an AI agent working
+        // for someone who signs in in their browser. *(It was missing until 2026-10-26.)*
         const server = args.some((a) => a === '--server' || a.startsWith('--server='))
           ? ` --server ${key}`
           : ''
         console.error(
-          '\x1b[31m✗\x1b[0m Without a terminal, a login needs a way to sign in that asks nothing:'
+          '\x1b[31m✗\x1b[0m Without a terminal, a login needs a way to sign in that asks nothing here:'
+        )
+        console.error(
+          `    ${getCliPrefix()} login${server} --browser          (someone signs in, in a browser on this machine)`
         )
         console.error(
           `    ${getCliPrefix()} login${server} --token <bearer>   (with --org @org or --personal)`

package/src/utils/scaffold.js

@@ -31,6 +31,10 @@ const STARTER_DIR = join(__dirname, '..', '..', 'starter')
  * @param {string} context.projectName - Workspace/project name
  * @param {string[]} context.workspaceGlobs - Workspace glob patterns
  * @param {Object} context.scripts - Root package.json scripts
+ * @param {Array<{ path: string, foundation?: boolean, extension?: boolean, site?: boolean }>} context.packages -
+ *   The packages the project starts with, each by its folder and kind, for the README's
+ *   table. `[]` for a blank workspace, which the README tells how to grow.
+ * @param {boolean} [context.cloned] - The project is a `uniweb clone` of a site in the app
  * @param {Object} [options] - Processing options
  */
 export async function scaffoldWorkspace(targetDir, context, options = {}) {

package/src/utils/status-next.js

@@ -0,0 +1,47 @@
+/**
+ * The order `uniweb status`'s next steps are taken in.
+ *
+ * ⭐ FOLLOWED FROM THE TOP, THE LIST WORKS: each step's precondition is met by the ones above
+ * it. A list of individually right steps in the wrong order is a guard that names an
+ * unavailable recovery step — a push before the pull it needs is refused, and the refusal
+ * then sends the reader back up. So the order is one table, not each check's own idea:
+ *
+ *   sign in → settle conflicts → finish a merge → take what others did (refresh, or pull)
+ *   → push → push to git → go live → update Uniweb → read doctor's findings
+ *
+ * Each check proposes steps by name (`step`); this sorts them, folds the ones another step
+ * already does, and drops duplicates.
+ */
+
+const ORDER = ['login', 'conflicts', 'merge', 'refresh', 'pull', 'push', 'gitpush', 'publish', 'update', 'doctor']
+
+/**
+ * @param {Array<{ step: string, command: string|null, why: string, ask?: boolean }>} proposals
+ * @returns {Array<{ command: string|null, why: string, ask: boolean }>}
+ */
+export function planNext(proposals) {
+  const steps = [...proposals]
+  // `refresh` is `git pull`, then the same pull: it takes the app's changes too.
+  const refresh = steps.find((p) => p.step === 'refresh')
+  const pull = steps.find((p) => p.step === 'pull')
+  if (refresh && pull) {
+    refresh.why = `${refresh.why}, and ${pull.why}`
+    steps.splice(steps.indexOf(pull), 1)
+  }
+  // A newer release's update aligns the dependencies and AGENTS.md too: the project's own
+  // CLI aligning them to its matrix is then one step too many.
+  if (steps.some((p) => p.step === 'update' && p.latest)) {
+    for (let i = steps.length - 1; i >= 0; i--) if (steps[i].step === 'update' && !steps[i].latest) steps.splice(i, 1)
+  }
+  const seen = new Set()
+  return steps
+    .filter((p) => ORDER.includes(p.step))
+    .sort((a, b) => ORDER.indexOf(a.step) - ORDER.indexOf(b.step))
+    .filter((p) => {
+      const key = p.command ?? `${p.step}:${p.why}`
+      if (seen.has(key)) return false
+      seen.add(key)
+      return true
+    })
+    .map(({ command, why, ask }) => ({ command: command ?? null, why, ask: Boolean(ask) }))
+}

package/src/utils/update-check.js

@@ -12,8 +12,10 @@ import { join } from 'node:path'
 import { detectGlobalCliPm, globalCliUpdateCmd } from './pm.js'
 
 const CHECK_INTERVAL = 24 * 60 * 60 * 1000 // 1 day
-const STATE_DIR = join(homedir(), '.uniweb')
-const STATE_FILE = join(STATE_DIR, 'update-check.json')
+// Found when read, not when this module loads — as `getAuthDir` is — so HOME is the one in
+// effect: a run with its own HOME (a test's) never reads or writes the person's cache.
+const stateDir = () => join(homedir(), '.uniweb')
+const stateFile = () => join(stateDir(), 'update-check.json')
 
 /**
  * Compare two semver strings.
@@ -34,8 +36,8 @@ function compareSemver(a, b) {
  */
 function readState() {
   try {
-    if (existsSync(STATE_FILE)) {
-      return JSON.parse(readFileSync(STATE_FILE, 'utf8'))
+    if (existsSync(stateFile())) {
+      return JSON.parse(readFileSync(stateFile(), 'utf8'))
     }
   } catch {
     /* ignore corrupt cache */
@@ -48,8 +50,8 @@ function readState() {
  */
 function writeState(state) {
   try {
-    if (!existsSync(STATE_DIR)) mkdirSync(STATE_DIR, { recursive: true })
-    writeFileSync(STATE_FILE, JSON.stringify(state))
+    if (!existsSync(stateDir())) mkdirSync(stateDir(), { recursive: true })
+    writeFileSync(stateFile(), JSON.stringify(state))
   } catch {
     /* ignore write errors */
   }

package/src/utils/workspace.js

@@ -60,6 +60,32 @@ export function findWorkspaceRoot(startDir = process.cwd()) {
   return null
 }
 
+/**
+ * Find a *Uniweb* workspace root from cwd. Stricter than findWorkspaceRoot
+ * — also requires that the workspace's root package.json declares uniweb
+ * as a dep or devDep. Otherwise `update` would write AGENTS.md and edit
+ * package.json files in unrelated monorepos, and `start` would take one for
+ * a Uniweb project.
+ *
+ * @param {string} [cwd]
+ * @returns {string|null} - Workspace root path or null
+ */
+export function findUniwebWorkspace(cwd = process.cwd()) {
+  const workspaceDir = findWorkspaceRoot(cwd)
+  if (!workspaceDir) return null
+  const pkgPath = join(workspaceDir, 'package.json')
+  if (!existsSync(pkgPath)) return null
+  try {
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'))
+    const hasUniwebDep = !!(
+      pkg.devDependencies?.uniweb || pkg.dependencies?.uniweb
+    )
+    return hasUniwebDep ? workspaceDir : null
+  } catch {
+    return null
+  }
+}
+
 /**
  * Get workspace packages from pnpm-workspace.yaml or package.json workspaces —
  * read as pnpm reads them (`workspacePackages`, ./workspace-packages.js).

package/starter/foundation/sections/Section/index.jsx

@@ -5,14 +5,14 @@ import { H1, H2, P, Link, cn } from '@uniweb/kit'
  *
  * A versatile content section that handles headings, text, and links.
  * Uses semantic tokens so it adapts to any theme context automatically.
+ *
+ * No fallbacks needed: the runtime hands every section the full content shape
+ * (empty strings and arrays where the markdown has nothing), and fills each
+ * param from its `default` in meta.js.
  */
 export default function Section({ content, params }) {
-  const { title, pretitle, subtitle, paragraphs = [], links = [], images = [] } = content || {}
-
-  const {
-    align = 'center',
-    width = 'default',
-  } = params || {}
+  const { title, pretitle, subtitle, paragraphs, links, images } = content
+  const { align, width } = params
 
   const alignments = {
     left: 'text-left',

package/starter/site/pages/home/1-welcome.md.hbs

@@ -11,4 +11,4 @@ align: center
 This is a minimal starting point for your Uniweb project. Edit the content in `site/pages/` and build section types in `src/sections/`.
 
 [About](/about)
-[Documentation](https://github.com/uniweb)
+[Documentation](https://uniweb.io/docs)

package/templates/site/site.yml.hbs

@@ -32,11 +32,10 @@ index: home
 # mounted directory is a folder of pages. Whatever that stub leaves unset comes
 # from the mounted directory's own folder.yml, so it need only say what differs.
 #
-# ! A `pages/<segment>:` sub-mount is BUILD-ONLY today. `uniweb export` and
-#   `uniweb deploy --host <adapter>` mount it normally, but `uniweb push` /
-#   `uniweb publish` do not read the key, so the mounted pages do not reach a
-#   backend (the CLI warns when it skips them). The whole-directory form
-#   `paths: { pages: <dir> }` IS carried by both. Static hosting: use either.
+# A `pages/<segment>:` mount goes wherever the site goes: builds, `uniweb export`
+# and `uniweb deploy --host <adapter>`, and `uniweb push` / `uniweb publish`,
+# which send the mounted pages as they are on disk — update a mounted repository
+# before you publish. A pull never writes into a mount.
 
 # ─── Structured Content ───────────────────────────────────────────────────────
 # Three things, and they are separate on purpose: