uniweb 1.20.3 → 1.21.0

package/partials/start.md

@@ -0,0 +1,126 @@
+{{#if project}}
+# Working on a Uniweb project
+
+You're in the Uniweb project at `{{root}}`.
+
+Its pages are markdown files, and how they look and behave comes from its foundation:
+React components that the pages pick by name. The `uniweb` CLI builds and runs the
+project, and brings it into the Uniweb app, where the person you're working with can keep
+editing it visually.
+
+`uniweb start` only prints this guide; `npx uniweb dev` runs the site. To start a new
+project instead, run `npx uniweb@latest start` in a folder outside this one.
+{{else}}
+# Build a website with Uniweb
+
+You're building a website for the person you're working with. In Uniweb, the pages are
+markdown files, and how they look and behave comes from a foundation: React components
+that the pages pick by name. One project holds both. The `uniweb` CLI builds and runs it,
+and brings it into the Uniweb app, where the person can keep editing it visually.
+{{/if}}
+
+## The person doesn't use a terminal
+
+Run every command yourself, and never ask them to run one. They do two things, in their
+browser: sign in, and pay when the site goes live. When a command prints an address to
+finish something in a browser, open it for them and say what it's for.
+
+Uniweb needs Node.js 22.12 or later. If `node --version` shows an older one, install a
+current one yourself.
+{{#unless project}}
+
+## Create the project
+
+```bash
+npx uniweb@latest create <name> --template starter
+cd <name>
+```
+
+`<name>` is lowercase letters, digits and hyphens, and becomes the project's folder.
+`create` asks no questions when it runs without a terminal. `starter` has one generic
+section type and two short pages: a working example of each convention, to replace as
+you build. `--template none` is the same project without them.
+{{#if otherProject}}
+
+Create it outside `{{otherProject}}`: that folder holds another project, and `create`
+does not make one inside it.
+{{/if}}
+{{/unless}}
+
+## Read the project's guide
+
+{{#if agents}}
+AGENTS.md, at the project's root, is the manual for this project and its version of
+Uniweb. Read its Part 0 before writing code: it says which parts your task needs.
+{{else}}
+This project has no AGENTS.md, the manual for a Uniweb project. Write one with
+`npx uniweb update --agents-only`, then read its Part 0 before writing code: it says
+which parts your task needs.
+{{/if}}
+
+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
+
+```bash
+{{install}}
+npx uniweb dev
+```
+
+Run `dev` in the background. Once the server listens, it prints
+`Serving <site> at <url>`: open that address to show the person.
+`npx uniweb dev --stop` stops it.
+
+## Sign them in to Uniweb
+
+When they want the site in the Uniweb app, to edit it there or to take it live:
+
+```bash
+npx uniweb login --browser --personal
+```
+
+This opens their browser. If they're signed in to Uniweb there, it finishes on its own;
+otherwise they sign in, or sign up if they're new, and it waits up to five minutes. Never
+ask for a password or a token.
+
+`--personal` puts their sites in their own workspace. If they ask for one of their
+organizations instead, use `--org @<its handle>`.
+
+## Bring the site into the app, and take it live
+
+```bash
+npx uniweb push --commit -m "<what you built>"      # to see or edit it in the app
+npx uniweb publish --commit -m "<what you built>"   # to take it live
+```
+
+`push` sends the site and its foundation to their workspace, where they'll find it in
+the app. `publish` does the same and then takes the site live, so it needs no push
+first. `--commit` commits the site's content first: in a git repository, both send only
+what is committed.
+
+If the site needs paying for, `publish` prints an address instead of going live. Open
+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
+- Every command's options: `npx uniweb <command> --help`

package/src/backend/app-changes.js

@@ -0,0 +1,153 @@
+/**
+ * What changed on the backend since this copy last synced — READ, never taken.
+ *
+ * `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/payment-handoff.js

@@ -244,6 +244,28 @@ async function openDoor({ url, say, open }) {
   return { opened }
 }
 
+/**
+ * Where a charge that was not asked is confirmed — at a terminal with `--yes`, or with no one at
+ * the terminal at all.
+ *
+ * ⛔ **UNATTENDED, NEVER "AT A TERMINAL".** The run with no one at the terminal is often an AI agent
+ * working for someone who does not use one, and it passes this line on: the person confirms in
+ * their browser, at the door the refusal printed, or in the app when there is none. *(Until
+ * 2026-10-26 every case said "run `uniweb publish` at a terminal".)* Either way a person confirms
+ * it, which is why the line says that `--yes` cannot.
+ *
+ * @param {{ interactive: boolean, door: boolean }} o - someone is at the terminal; a door was printed
+ * @returns {string}
+ */
+function confirmChargeLine({ interactive, door }) {
+  if (interactive) {
+    return 'This change charges the site\'s card, so only you can confirm it: run `uniweb publish` without `--yes`.'
+  }
+  return door
+    ? 'This change charges the site\'s card, so a person confirms it, in a browser at the address above. `--yes` never confirms a charge.'
+    : 'This change charges the site\'s card, so a person confirms it, in the app. `--yes` never confirms a charge.'
+}
+
 const CONFIRM = 'Confirm and publish'
 const CONTINUE = 'Continue and publish'
 const OPEN = 'Open it in the app'
@@ -275,7 +297,8 @@ const MAX_UNATTENDED = 3
  * "allow it for reductions only, keep charges interactive".]*
  *
  * With no one at the terminal and nothing to answer it, there is no prompt: the refusal is reported as
- * before, its door printed, and the publish fails. A refusal with no `confirm` behaves as it always has.
+ * before, its door printed, and the publish fails — and a charge says where a person confirms it, in a
+ * browser (`confirmChargeLine`). A refusal with no `confirm` behaves as it always has.
  *
  * @param {object} o
  * @param {ReturnType<typeof readPaymentRefusal>} o.verdict - the first refusal
@@ -312,7 +335,7 @@ export async function settleRefusal({ verdict, args = [], say, republish, intera
     } else if (!offer || !interactive || (yes && !reduction)) {
       await reportPaymentRefusal({ verdict: current, args, say, open, interactive: interactive && !yes })
       if (offer && !reduction) {
-        say.dim('This change charges the site\'s card, so only you can confirm it: run `uniweb publish` at a terminal, without `--yes`.')
+        say.dim(confirmChargeLine({ interactive, door: current.kind === 'settle' }))
       } else if (reduction) {
         say.dim('This change only lowers what the site pays: `uniweb publish --yes` continues it without a prompt.')
       }

package/src/commands/clone.js

@@ -421,6 +421,8 @@ export async function clone(args = [], deps = {}) {
       {
         projectName: workspaceName,
         workspaceGlobs: ['site'],
+        packages: [{ path: 'site', site: true }],
+        cloned: true,
         scripts: { dev: 'uniweb dev', build: 'uniweb build' }
       },
       { onProgress }

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('')
@@ -2076,6 +2105,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 +2123,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})`
     })

package/src/commands/pull.js

@@ -238,7 +238,7 @@ function pullCachePath(siteDir) {
 // Ignoring those once costs one full pull. (In a repository an ETag is echoed only while
 // the sync point it was banked with is in the history — see `cacheHolds` below.)
 const PULL_CACHE_VERSION = 2
-function readPullCache(siteDir) {
+export function readPullCache(siteDir) {
   try {
     const obj = JSON.parse(readFileSync(pullCachePath(siteDir), 'utf8'))
     return obj && typeof obj === 'object' && obj.version >= PULL_CACHE_VERSION ? obj : {}
@@ -246,6 +246,21 @@ function readPullCache(siteDir) {
     return {}
   }
 }
+
+/**
+ * Whether the ETags this copy banked still describe its files — the condition a
+ * conditional GET is sent on. Outside git, always. In a repository, only while HEAD's
+ * history holds the sync point they were banked with: a merge abandoned, a branch reset,
+ * and the backend did not move but the files did.
+ *
+ * One rule for both readers of the lanes — this pull and `uniweb status`, which asks the
+ * same question without taking the answer.
+ */
+export function etagsHold(siteDir, origin, repo = repoOf(siteDir)) {
+  if (!repo) return true
+  const held = readSyncPoint(siteDir, origin)
+  return Boolean(held && isAncestor(repo, held))
+}
 function writePullCache(siteDir, { content, folder }) {
   const p = pullCachePath(siteDir)
   mkdirSync(dirname(p), { recursive: true })
@@ -767,7 +782,7 @@ export async function pull(args = [], deps = {}) {
   // only while the sync point it was banked with is.
   const cache = readPullCache(siteDir)
   const held = repo ? readSyncPoint(siteDir, client.origin) : null
-  const cacheHolds = !repo || Boolean(held && isAncestor(repo, held))
+  const cacheHolds = etagsHold(siteDir, client.origin, repo)
   let etagContent = cache.content
   let etagFolder = cache.folder
 

package/src/commands/register.js

@@ -385,21 +385,6 @@ export async function settleFoundationScope(targetDir, { args, isPreview, flagSc
   return { scope, source }
 }
 
-/**
- * The scope a bare name registers under when `--scope` names none — as `@handle`, or null
- * when none was chosen.
- *
- * ⭐ THE WORKSPACE THIS COMMAND WORKS IN *[Diego, 2026-10-06]* — an organization's handle,
- * or your own for your personal workspace — said, not asked (`scopeOfWorkspace`). A team
- * working in `@acme` registers `@acme/…`, which any of its members can release.
- * ⛔ Until 2026-10-06 the default was your personal scope wherever you worked, so a team's
- * foundation registered as `@jane/…` — releasable by Jane alone, and fixed only by
- * renaming it into a new foundation.
- *
- * When the workspace names no scope — none is chosen, or it is a unit without a handle —
- * the scope is derived from your orgs as before (`deriveScope`): your personal scope when
- * you belong to none, else a pick at a terminal, your personal scope without one.
- */
 /**
  * Refuse a reserved scope wherever it came from, before anything is written or sent —
  * `@uniweb` names the framework's own packages and a system account on every Uniweb
@@ -417,6 +402,21 @@ function refusedReservedScope(scope, lead) {
   return true
 }
 
+/**
+ * The scope a bare name registers under when `--scope` names none — as `@handle`, or null
+ * when none was chosen.
+ *
+ * ⭐ THE WORKSPACE THIS COMMAND WORKS IN *[Diego, 2026-10-06]* — an organization's handle,
+ * or your own for your personal workspace — said, not asked (`scopeOfWorkspace`). A team
+ * working in `@acme` registers `@acme/…`, which any of its members can release.
+ * ⛔ Until 2026-10-06 the default was your personal scope wherever you worked, so a team's
+ * foundation registered as `@jane/…` — releasable by Jane alone, and fixed only by
+ * renaming it into a new foundation.
+ *
+ * When the workspace names no scope — none is chosen, or it is a unit without a handle —
+ * the scope is derived from your orgs as before (`deriveScope`): your personal scope when
+ * you belong to none, else a pick at a terminal, your personal scope without one.
+ */
 async function deriveScopeFromLogin(client, args) {
   const token = await client.token()
   const ws = await resolveWorkspace({ client, args })

package/src/commands/start.js

@@ -0,0 +1,60 @@
+/**
+ * `uniweb start` — the guide an AI agent reads first.
+ *
+ * ⭐ FOR AN AGENT WORKING FOR SOMEONE WHO DOES NOT USE A TERMINAL. The person asks their
+ * agent for a website; the agent runs `npx uniweb@latest start` and follows what it
+ * prints: create a project, read its AGENTS.md, run it, sign the person in, and bring the
+ * site into the Uniweb app. The person's part is their browser — signing in, and paying
+ * when the site goes live — so nothing here asks them to run a command.
+ *
+ * ⛔ READ-ONLY, AND SAFE ANYWHERE. It asks nothing, writes nothing and makes no request,
+ * so an agent can run it in any folder, as often as it likes. That is also why
+ * `index.js` answers it before the update check, which can write a cache and fetch.
+ *
+ * ⭐ THE TEXT SHIPS WITH THIS CLI (`partials/start.md`), so it describes the version that
+ * prints it. Inside a Uniweb project (`findUniwebWorkspace`) it starts from that project
+ * instead of creating one, and names that project's own package manager.
+ *
+ * It is answered by the CLI that was invoked, never delegated to a project's own copy
+ * (`STANDALONE_COMMANDS`): an older project CLI does not have it.
+ */
+
+import { existsSync, readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import Handlebars from 'handlebars'
+import { findUniwebWorkspace, findWorkspaceRoot } from '../utils/workspace.js'
+import { detectWorkspacePm, installCmd } from '../utils/pm.js'
+
+const PARTIAL = join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'partials', 'start.md')
+
+/**
+ * The guide, as Markdown, for a command run in `cwd`.
+ *
+ * Outside a project, `otherProject` names a workspace of another kind that holds `cwd`:
+ * `create` refuses to make a project inside one, so the guide says to create it elsewhere.
+ *
+ * @param {{ cwd?: string }} [o]
+ * @returns {string}
+ */
+export function startGuide({ cwd = process.cwd() } = {}) {
+  const root = findUniwebWorkspace(cwd)
+  const template = Handlebars.compile(readFileSync(PARTIAL, 'utf8'), { noEscape: true })
+  return template({
+    project: !!root,
+    root,
+    // A project `create` makes has one; one already here may not.
+    agents: root ? existsSync(join(root, 'AGENTS.md')) : true,
+    otherProject: root ? null : findWorkspaceRoot(cwd),
+    install: installCmd(root ? detectWorkspacePm(root) : 'npm')
+  })
+}
+
+/**
+ * @param {string[]} [args] - none are read
+ * @returns {Promise<{ exitCode: number }>}
+ */
+export async function start(args = []) {
+  console.log(startGuide())
+  return { exitCode: 0 }
+}