uniweb 1.20.3 → 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/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/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/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)

package/templates/workspace/README.md.hbs

@@ -1,87 +1,169 @@
 # {{projectName}}
 
-A website built with [Uniweb](https://github.com/uniweb/cli) — a component web platform that separates content from code.
+A website made with [Uniweb](https://uniweb.io): an open-source React framework and a connected
+visual authoring platform.
 
-{{> quick-start}}
+**Developers define the vocabulary. Authors compose with it. Uniweb keeps both sides in sync.**
 
-## Project Structure
+This project and the Uniweb app are two interfaces to the same website. Here, in code and git,
+you build its **foundation**: React components, called section types, and the schemas of its
+structured content. In the app, authors compose pages from those section types and manage records
+through those schemas: visually, with live previews, and with no markdown, YAML or git to learn.
+You build the components. Uniweb builds the authoring experience.
+{{#if cloned}}
 
+This project was cloned from a site in the Uniweb app (`uniweb clone`), so it is already in sync
+with it. Its foundation is a registered one, not a folder of this project.
+{{/if}}
+
+## Quick start
+
+{{#if packages.length}}
+```bash
+pnpm install
+pnpm dev          # prints the address it serves the site at
 ```
-{{projectName}}/
-├── src/                 # Foundation package (the site's source code; pkg name: src)
-│   ├── sections/        # Section types (selectable by content authors)
-│   ├── styles.css       # Tailwind CSS v4 theme
-│   ├── main.js          # Foundation declarations (name, vars, defaultLayout)
-│   └── vite.config.js   # defineFoundationConfig()
-│
-├── site/                # Content (markdown)
-│   ├── pages/           # Content pages
-│   │   └── home/
-│   │       ├── page.yml
-│   │       └── 1-welcome.md
-│   ├── site.yml         # Site configuration (foundation: src)
-│   └── vite.config.js   # defineSiteConfig()
-│
-└── AGENTS.md            # Developer guide (human + AI)
+
+Edit a page or a section type and the page updates as you save. With npm, use `npm install`,
+`npm run dev` and `npx uniweb`.
+{{else}}
+This workspace started empty. Add a foundation and a site, then run them:
+
+```bash
+npx uniweb add project <name>    # a foundation in <name>/src, a site in <name>/site
+pnpm install
+pnpm uniweb dev                  # prints the address it serves the site at
 ```
+{{/if}}
 
-A site is pure content. A foundation is the site's source code — that's why it lives in `src/`.
+## What's here
 
-## Content Authoring
+| Folder | What it holds |
+|---|---|
+{{#each packages}}
+| `{{path}}/` | {{#if foundation}}a foundation: section types in `sections/`, written in React, and any data schemas in `schemas/`{{/if}}{{#if extension}}an extension: more section types, loaded beside a foundation{{/if}}{{#if site}}a site: its pages in `pages/`, with `site.yml` and `theme.yml`{{/if}} |
+{{/each}}
+| `AGENTS.md` | the manual for this project and its version of Uniweb, for you and for AI agents |
 
-Content lives in markdown files under `site/pages/`:
+Each markdown file in a site's `pages/` is one section of a page. Its frontmatter names a
+section type, and the component receives the content already parsed. For example:
 
 ```markdown
 ---
-type: Section
-theme: light
+type: Hero
 ---
 
-# Welcome
-
-Your content here.
+# Build something great
 
-[Call to Action](#)
+Edit this text, not the component.
 ```
 
-{{> adding-pages}}
-
-## Component Development
-
-Section types live in `src/sections/`. Each is a folder with an `index.jsx` and a `meta.js`:
-
 ```jsx
-// src/sections/Hero/index.jsx
+// sections/Hero/index.jsx
 import { H1, P } from '@uniweb/kit'
 
 export default function Hero({ content }) {
-  const { title, paragraphs = [] } = content || {}
-
   return (
-    <div className="max-w-4xl mx-auto px-6">
-      <H1 text={title} className="text-heading text-4xl font-bold" />
-      <P text={paragraphs} className="text-body mt-4" />
+    <div className="mx-auto max-w-4xl px-6">
+      <H1 text={content.title} className="text-4xl font-bold text-heading" />
+      <P text={content.paragraphs} className="mt-4 text-body" />
     </div>
   )
 }
 ```
 
-Components receive parsed content from markdown. Classes like `text-heading` and `text-body` are semantic tokens — the site controls their actual colors through theming, so the same component adapts to any context automatically.
+`text-heading` and `text-body` are theme tokens. A site's `theme.yml` sets their colors, so one
+component works in light and dark sections, and on every site that uses it.
 
-{{> components-docs}}
+## Connect the authoring app
 
-## Building
+Start with a normal project, and connect the app when you want visual authoring:
 
 ```bash
-# Build foundation (generates dist/foundation.js)
-cd foundation && pnpm build
+pnpm uniweb login       # sign in to your Uniweb account
+pnpm uniweb sync        # the first sync brings the site and its foundation into the app
+```
+
+From then on, the CLI is the bridge between the two workflows:
+
+| Command | What it does |
+|---|---|
+| `pnpm uniweb push` | sends your section types, schemas and content to the app: a draft, not live |
+| `pnpm uniweb pull` | brings authors' edits into your files, as a git merge |
+| `pnpm uniweb sync` | takes your teammates' commits and the authors' edits, then pushes yours |
+| `pnpm uniweb publish` | pushes, then takes the site live on Uniweb hosting, a paid service |
+
+Authors never need to think about synchronization: in the app, their changes appear live. On
+your side, edits to different sections combine, and nothing overwrites an author's edit. When
+the same section changed on both sides, `sync` stops at a git conflict for you to settle. Like
+git, a push sends what you have committed; `--commit` commits the site's content first.
+
+### Structured content, editable without an admin app
+
+A section type declares the data it shows, by schema, in its `meta.js`:
 
-# Build site for production
-cd site && pnpm build
+```js
+export default {
+  data: {
+    people: '@std/person',   // a standard schema, from @uniweb/schemas
+    events: '@/event'        // this foundation's own, in schemas/event.yml
+  }
+}
 ```
 
-Deploy `site/dist/` to any static host (Vercel, Netlify, Cloudflare Pages, etc.)
+A standard schema needs `@uniweb/schemas` as a dependency of the foundation. In the app, authors
+get forms and records for those schemas. No separate admin application is needed to make the
+data editable.
+
+## Other ways to use it
+
+The framework works on its own, too.
+
+- **Content in files only.** If you manage the content yourself, the site needs no Uniweb account.
+  `pnpm build` makes each site's `dist/`, a static site for any host, and `pnpm uniweb deploy`
+  ships it to GitHub Pages, Cloudflare Pages, Netlify, Vercel or S3 + CloudFront.
+- **Foundations for your clients' sites.** If the sites belong to your clients, who make and edit
+  them in the app, this project is where you build and test the foundation.
+  `pnpm uniweb register` publishes it to Uniweb for their sites.
+
+## Working with AI agents
+
+A Uniweb project gives an agent a system to work within, its section types, schemas and content
+conventions, instead of a blank canvas. What an agent builds here, authors can use in the app
+after the next sync.
+
+[AGENTS.md](./AGENTS.md) is written for developers and AI agents alike. Many coding agents read it
+on their own when they start in this folder; point any other agent at it first.
+`npx uniweb@latest update` moves the project to the latest release of Uniweb, and AGENTS.md with
+it.
+
+Some prompts to try:
+
+**Converting an existing design:**
+```
+I have a landing page design in `homepage.jsx`. Convert it into this Uniweb
+project. Decompose each visual section into a section type in the foundation,
+and extract all text content into markdown files in the site's pages/home/.
+The final page should render identically to the original. See AGENTS.md.
+```
+
+**Adding a section type:**
+```
+Create a Pricing section type with 3-column cards. It should work in light and
+dark sections. Use content.items for the pricing tiers — each item has a title,
+a paragraph (the price), and a link (the call to action).
+```
+
+**Adding a page:**
+```
+Add a /contact page with a hero section and a contact details section. Reuse
+the Hero section type from the homepage.
+```
 
-{{> ai-assistance}}
+## Learn more
 
-{{> learn-more}}
+- [Documentation](https://uniweb.io/docs): guides and reference. For AI agents, its index is
+  https://uniweb.io/llms.txt
+- [Uniweb app](https://uniweb.app): the visual authoring platform
+- `pnpm uniweb <command> --help`: every command's options
+- `pnpm uniweb doctor`: checks the project's configuration