uniweb 1.20.2 → 1.20.4

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/backend/workspace.js

@@ -139,6 +139,44 @@ export const SOURCE_LABEL = {
   offline: 'not resolved in a preview'
 }
 
+/**
+ * What a preview (`--dry-run`) says about the workspace: the one the command would work in,
+ * and a warning when the project's record says its site was created in another.
+ *
+ * ⭐ A preview resolves the workspace offline (`resolveWorkspace`): a flag, `UNIWEB_WORKSPACE`
+ * or the login's choice. With none of those, which one the command settles on takes the
+ * backend, so the preview says what the command does instead of guessing.
+ *
+ * ⚠️ The record says where the site was CREATED (`readSiteWorkspace`), not where the backend
+ * keeps it now. The backend decides, and a site kept outside the workspace stops the command
+ * (`409 wrong_workspace`), so a difference is worded as a warning about the record.
+ *
+ * @param {{ workspace: string|null, source: string }} ws - `resolveWorkspace`'s answer
+ * @param {string|null} createdIn - `readSiteWorkspace` for the project's site on this backend;
+ *   null when it has none, or no workspace is recorded for it
+ * @param {string} verb - `publish`, `push`
+ * @returns {{ workspace: string, warning: string|null }}
+ */
+export function previewWorkspace(ws, createdIn, verb) {
+  if (ws.source === 'offline') {
+    return {
+      workspace:
+        `none chosen at login — the ${verb} works in your personal workspace if you belong to no ` +
+        'organization or project, and otherwise stops and says how to choose one',
+      warning: null
+    }
+  }
+  const differs =
+    typeof createdIn === 'string' && createdIn.toLowerCase() !== String(ws.workspace ?? '').toLowerCase()
+  return {
+    workspace: `${describeWorkspace(ws.workspace)} (${SOURCE_LABEL[ws.source]})`,
+    warning: differs
+      ? `sync.json records this site as created in ${describeWorkspace(createdIn)}. If the backend ` +
+        `still keeps it there, it stops this ${verb}: add --org ${createdIn} to work in it.`
+      : null
+  }
+}
+
 /** How to choose, for a command on `origin` — its login names the backend when it must (`loginCommand`). */
 const choose = (origin) =>
   [

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/publish.js

@@ -111,11 +111,12 @@ import {
   commitWriteBacks,
   reportWriteBacks,
   dropSiteBoundValues,
-  pushSyncPackages
+  pushSyncPackages,
+  readSiteWorkspace
 } from '../backend/site-sync.js'
 import { repoOf } from '../utils/sync-point.js'
 import { commitBeforeSending } from '../backend/commit-before-sending.js'
-import { resolveWorkspace, describeWorkspace, SOURCE_LABEL } from '../backend/workspace.js'
+import { resolveWorkspace, describeWorkspace, previewWorkspace, SOURCE_LABEL } from '../backend/workspace.js'
 import { uploadSiteMedia, describeAssetRefusal } from '../backend/site-media.js'
 import {
   updateBackendMap,
@@ -479,13 +480,15 @@ export async function publish(args = []) {
   }
 
   if (dryRun) {
+    const siteUuid = readBackendState(siteDir, client.origin).site?.uuid
+    const preview = previewWorkspace(ws, siteUuid ? readSiteWorkspace(siteDir, client.origin) : null, 'publish')
     say.info('Dry run — would bring the foundation along, sync, and go live:')
     say.dim(`Backend     : ${client.origin}`)
-    say.dim(
-      `site_uuid   : ${readBackendState(siteDir, client.origin).site?.uuid || '(none — the site is created before anything uploads)'}`
-    )
+    say.dim(`Workspace   : ${preview.workspace}`)
+    say.dim(`site_uuid   : ${siteUuid || '(none — the site is created before anything uploads)'}`)
     const langs = languagesFromSiteYml(siteYml)
     if (langs) say.dim(`Languages   : ${langs.join(', ')}`)
+    if (preview.warning) say.warn(preview.warning)
     await bringFoundationAlong({
       client,
       siteDir,

package/src/commands/push.js

@@ -103,10 +103,11 @@ import {
   commitWriteBacks,
   reportWriteBacks,
   holdUnchangedPush,
-  pushSyncPackages
+  pushSyncPackages,
+  readSiteWorkspace
 } from '../backend/site-sync.js'
 import { commitBeforeSending } from '../backend/commit-before-sending.js'
-import { resolveWorkspace, describeWorkspace, SOURCE_LABEL } from '../backend/workspace.js'
+import { resolveWorkspace, describeWorkspace, previewWorkspace, SOURCE_LABEL } from '../backend/workspace.js'
 
 // Re-exported for downstream importers (pull.js, push.test.js) that read these
 // helpers from this module — their canonical home is now ../backend/site-sync.js.
@@ -685,6 +686,10 @@ export async function push(args = [], deps = {}) {
         `Dry run — would push the folder at ${colors.dim}${client.origin}${colors.reset}`
       )
     }
+    const siteUuid = readBackendState(siteDir, client.origin).site?.uuid
+    const preview = previewWorkspace(ws, siteUuid ? readSiteWorkspace(siteDir, client.origin) : null, 'push')
+    note(`Workspace: ${preview.workspace}`)
+    if (preview.warning) warn(preview.warning)
     return { exitCode: 0 }
   }
 

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 }
+}

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/framework-index.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-10-26T00:04:57.896Z",
+  "generatedAt": "2026-10-26T02:00:48.151Z",
   "packages": {
     "@uniweb/api": {
       "version": "1.6.4"
@@ -24,7 +24,7 @@
       "version": "1.0.6"
     },
     "@uniweb/kit": {
-      "version": "1.6.4"
+      "version": "1.6.5"
     },
     "@uniweb/loom": {
       "version": "1.1.2"

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
@@ -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}
@@ -2075,6 +2120,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

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/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)