uniweb 1.20.3 → 1.21.0

package/README.md

@@ -1,68 +1,68 @@
 # uniweb
 
-A component content architecture for React. Build sites where content authors and component developers can't break each other's work—and scale from local files to visual editing without rewrites.
+The CLI for [Uniweb](https://uniweb.io): an open-source React framework and a connected visual authoring platform.
 
-Create well-structured Vite + React projects with file-based routing, localization, and clean content/code separation out of the box.
+**Developers define the vocabulary. Authors compose with it. Uniweb keeps both sides in sync.**
 
-## Quick Start
+Developers build real React components, schemas and content structures in a normal codebase. Those definitions become the vocabulary authors use in the Uniweb app to create pages, manage content and work with structured data. Your project and the authors' workspace are two interfaces to the same website, and the CLI keeps them in sync, so both sides keep working.
 
-```bash
-npm create uniweb
+```text
+Traditional:   developer builds → hands off → CMS users edit
+
+Uniweb:        developer project ⇄ Uniweb ⇄ author workspace
+                      ↑                          ↑
+                      └──── both keep working ───┘
 ```
 
-The interactive prompt asks for a project name and template. Pick one, then:
+## Quick Start
 
 ```bash
-cd my-project
-pnpm install  # or npm install
-pnpm dev      # or npm run dev
+npx uniweb@latest create my-site
+cd my-site
+pnpm install    # or npm install
+pnpm dev        # or npm run dev — prints the address it serves the site at
 ```
 
-Edit files in `site/pages/` and `src/sections/` to see changes instantly.
-
-> **pnpm ready** — `pnpm create uniweb` works out of the box. Projects include both `pnpm-workspace.yaml` and npm workspaces.
+At a terminal, `create` asks which template to start from (`npm create uniweb` does the same). Edit the pages in `site/pages/` and the section types in `src/sections/`, and the page updates as you save.
 
-### Templates
+Start with a normal project, and connect the authoring app when you want it:
 
-| Template | Description |
-| --- | --- |
-| **Starter** | Foundation + site + sample content (default) |
-| **None** | Foundation + site with no content |
-| **Marketing** | Landing page, features, pricing, testimonials |
-| **Docs** | Documentation with sidebar and search |
-| **Academic** | Research site with publications and team |
-| **International** | Multilingual site with i18n and blog |
-| **Dynamic** | Live API data fetching with loading states |
-| **Store** | E-commerce with product grid |
-| **Extensions** | Multi-foundation with visual effects extension |
+```bash
+pnpm uniweb login    # sign in to your Uniweb account
+pnpm uniweb sync     # the first sync brings the site and its foundation into the app
+```
 
-**See them live:** [View all template demos](https://uniweb.github.io/templates/)
+> **pnpm ready** — `pnpm create uniweb` works out of the box. Projects include both `pnpm-workspace.yaml` and npm workspaces.
 
-Use `--blank` for an empty workspace (no packages) — grow with `uniweb add`.
+### With an AI agent
 
-**Two starting points.** Either let the CLI create a new directory:
+Building a site with an AI coding agent? Ask it to run `npx uniweb@latest start` first. It prints a short guide written for the agent: how to create the project, where its manual is (`AGENTS.md`), how to run it, and how to bring the site into the Uniweb app. The agent runs every command; you only use your browser, to sign in and to pay when the site goes live.
 
-```bash
-pnpm create uniweb my-site --template docs
-```
+## Two Interfaces to One Website
 
-…or scaffold inside an existing directory (e.g., a freshly-cloned GitHub repo):
+| Developers | Authors |
+| --- | --- |
+| React components | Visual components |
+| Schemas and configuration | Forms and structured records |
+| Vite and local development | Live visual editing |
+| Files and Git | Content and composition |
+| `push` · `pull` · `sync` · `publish` | Changes appear live |
 
-```bash
-pnpm create uniweb . --template docs
-```
+**For developers, it's a normal project.** Section types are React components, content is markdown in the repository, Vite builds it, and git holds the history. You keep your editor, terminal and deployment workflow.
 
-### Local Scripts
+**For authors, it's the Uniweb app.** Your section types become their building blocks: they compose pages from them, set the options each one declares in its `meta.js`, and manage records through your schemas, with live previews. They never see JSX, markdown, YAML or git, and you never build an editing UI. You build the components; Uniweb builds the authoring experience.
 
-Run these from the **project root**:
+### The CLI is the bridge
 
-```bash
-pnpm dev        # Start development server
-pnpm build      # Build foundation + site for production
-pnpm preview    # Preview the production build
-```
+| Command | What it does |
+| --- | --- |
+| `uniweb push` | Sends your section types, schemas and content to the app: a draft, not live |
+| `uniweb pull` | Brings authors' edits into your files, as a git merge |
+| `uniweb sync` | Takes your teammates' commits and the authors' edits, then pushes yours |
+| `uniweb publish` | Pushes, then takes the site live on Uniweb hosting (paid) |
+| `uniweb clone <site-uuid>` | Starts a local project from a site made in the app (`uniweb site list` shows its uuid) |
 
-The `build` command outputs to `site/dist/`. With pre-rendering enabled (the default for official templates), you get static HTML files ready to deploy anywhere. For the actual deploy step (and the `uniweb deploy` / `uniweb register` commands), see [Deployment](#deployment) below.
+Edits to different sections combine. When the same section changed on both sides, `pull` stops at a git conflict for you to settle, and a push stops rather than overwrite what an author changed (only `--force` goes past it), so neither edit is lost. Like git, a push sends what you have committed; `--commit` commits the site's content first.
 
 ## What You Get
 
@@ -71,7 +71,7 @@ Every project starts as a workspace with two packages:
 - **`site/`** — Content, pages, entry point (package name: `site`)
 - **`src/`** — React components, the site's source code (package name: `src`)
 
-A site is pure content. A foundation is the site's source code — that's why it lives in `src/`. Content authors work in markdown. Component authors work in React. Neither can break the other's work. As your project grows, use `uniweb add` to add more foundations, sites, and extensions.
+A site is pure content. A foundation is the site's source code — that's why it lives in `src/`. Content lives in markdown and component code in React, so neither can break the other. As your project grows, use `uniweb add` to add more foundations, sites, and extensions.
 
 ```
 my-project/
@@ -79,25 +79,26 @@ my-project/
 │   ├── pages/                # File-based routing
 │   │   └── home/
 │   │       ├── page.yml      # Page metadata
-│   │       └── hero.md       # Section content
-│   ├── locales/              # i18n (hash-based translations)
+│   │       └── 1-welcome.md  # A section
+│   ├── site.yml              # Site configuration
+│   ├── theme.yml             # Colors, fonts, appearance
 │   ├── entry.js              # Entry point (~6 lines)
-│   ├── vite.config.js        # 3-line config
+│   ├── vite.config.js        # One-line config
 │   └── public/               # Static assets
 │
-└── src/                      # Foundation package (the site's source)
-    ├── sections/             # Section types (addressable from markdown)
-    │   ├── Hero.jsx          # Bare file → section type (no meta.js needed)
-    │   └── Features/
-    │       ├── meta.js       # Content interface (params, presets)
-    │       └── Features.jsx
-    ├── components/           # Regular React components
-    │   └── Button.jsx
-    ├── main.js               # Package exports (vars, defaultLayout, props)
-    ├── styles.css            # Tailwind v4 + CSS tokens
-    ├── package.json          # name: "src"
-    ├── vite.config.js        # 3-line config
-    └── dist/                 # Built output
+├── src/                      # Foundation package (the site's source)
+│   ├── sections/             # Section types (addressable from markdown)
+│   │   ├── Hero.jsx          # Bare file → section type (no meta.js needed)
+│   │   └── Features/
+│   │       ├── index.jsx
+│   │       └── meta.js       # Content interface (params, presets)
+│   ├── components/           # Regular React components
+│   ├── main.js               # Foundation declarations (name, theme variables, default layout)
+│   ├── styles.css            # Tailwind v4 + CSS tokens
+│   ├── package.json          # name: "src"
+│   └── vite.config.js        # 3-line config
+│
+└── AGENTS.md                 # The project's manual, for developers and AI agents
 ```
 
 **Pages are folders.** Create `pages/about/` with markdown files inside → visit `/about`. That's the whole routing model.
@@ -119,7 +120,7 @@ Build something great.
 [Get Started](#)
 ```
 
-Frontmatter specifies the component type and configuration. The body contains the actual content—headings, paragraphs, links, images—which gets semantically parsed into structured data your component receives.
+Frontmatter names the section type and its configuration — `theme: dark` sets the section's color context. The body contains the actual content—headings, paragraphs, links, images—which gets semantically parsed into structured data your component receives.
 
 ### Beyond Markdown
 
@@ -145,32 +146,34 @@ function TeamCard({ content }) {
 }
 ```
 
-Natural content stays in markdown; structured data goes in tagged blocks (YAML or JSON).
+Natural content stays in markdown; structured data goes in tagged blocks (YAML or JSON). Content that many pages share — people, publications, events — can live as records instead, typed by your foundation's schemas, which is what authors then manage as forms in the app.
 
 ### Components as React
 
 ```jsx
-export default function Hero({ content, params }) {
+import { H1, P, Link } from '@uniweb/kit'
+
+export default function Hero({ content }) {
   const { title, paragraphs, links } = content
 
   return (
-    <section className="py-20 text-center">
-      <h1 className="text-4xl font-bold">{title}</h1>
-      <p className="text-xl text-gray-600">{paragraphs[0]}</p>
+    <div className="py-20 text-center">
+      <H1 text={title} className="text-4xl font-bold text-heading" />
+      <P text={paragraphs[0]} className="mt-4 text-xl text-body" />
       {links[0] && (
-        <a
-          href={links[0].href}
-          className="mt-8 px-6 py-3 bg-blue-600 text-white rounded inline-block"
+        <Link
+          to={links[0].href}
+          className="mt-8 inline-block rounded bg-primary px-6 py-3 text-primary-foreground"
         >
           {links[0].label}
-        </a>
+        </Link>
       )}
-    </section>
+    </div>
   )
 }
 ```
 
-Standard React. Standard Tailwind. The `{ content, params }` interface is only for _section types_ — components that content creators select in markdown frontmatter. Everything else uses regular React props.
+Standard React. Standard Tailwind. Classes like `text-heading` and `bg-primary` are theme tokens, so one component adapts to light and dark sections and to every site's colors; the runtime wraps each section in its `<section>` and paints its background. The `{ content, params }` interface is only for _section types_ — components that content creators select in markdown frontmatter. Everything else uses regular React props.
 
 ### Composition
 
@@ -194,13 +197,48 @@ Authors can also compose layouts from reusable section types using child section
 
 ```
 pages/home/
-├── highlights.md            # type: Grid, columns: 3
+├── page.yml                 # nest: { highlights: [stats, testimonial, demo] }
+├── highlights.md            # type: Grid
 ├── @stats.md                # type: StatCard
 ├── @testimonial.md          # type: Testimonial
 └── @demo.md                 # type: SplitContent (with an embedded @LiveDemo inset)
 ```
 
-Three different section types, arranged in a grid, one with an interactive component inside it — all authored in markdown. The developer builds reusable pieces; the content author composes them. See the [Component Patterns guide](https://github.com/uniweb/docs/blob/main/development/component-patterns.md) for the full composition model.
+Three different section types, arranged in a grid, one with an interactive component inside it — all authored in markdown. An `@` file is a child section, and `nest:` in `page.yml` says whose. The developer builds reusable pieces; the content author composes them. See the [Component Patterns guide](https://github.com/uniweb/docs/blob/main/development/component-patterns.md) for the full composition model.
+
+## Templates
+
+| Template | Description |
+| --- | --- |
+| **Starter** | Foundation + site + sample content (default) |
+| **None** | Foundation + site with no content |
+| **Blank** (`--blank`) | An empty workspace — grow it with `uniweb add` |
+
+**Official templates** — marketing sites, documentation, blogs, academic sites and more — each come with a working foundation and sample content. `uniweb template list` shows the ones your CLI scaffolds, and you can [see them live](https://uniweb.github.io/templates/).
+
+**Two starting points.** Either let the CLI create a new directory:
+
+```bash
+pnpm create uniweb my-site --template docs
+```
+
+…or scaffold inside an existing directory (e.g., a freshly-cloned GitHub repo):
+
+```bash
+pnpm create uniweb . --template docs
+```
+
+### Local Scripts
+
+Run these from the **project root**:
+
+```bash
+pnpm dev        # Start development server
+pnpm build      # Build foundation + site for production
+pnpm preview    # Preview the production build
+```
+
+The `build` command outputs to `site/dist/`. With pre-rendering enabled (the default for official templates), you get static HTML files ready to deploy anywhere.
 
 ## Next Steps
 
@@ -212,17 +250,17 @@ After creating your project:
 
 3. **Learn the configuration** — Run `uniweb docs site` or `uniweb docs page` for quick reference on configuration options.
 
-4. **Create a section type** — Add a file to `src/sections/` (e.g., `Banner.jsx`) and rebuild. Bare files at the root are discovered automatically — no `meta.js` needed. Add `meta.js` when you want to declare params or presets. See the [Component Metadata Reference](https://github.com/uniweb/docs/blob/main/reference/component-metadata.md) for the full schema.
+4. **Create a section type** — `uniweb add section Banner` scaffolds one, or add a file to `src/sections/` (e.g., `Banner.jsx`): the dev server picks it up. Bare files at the root are discovered automatically — no `meta.js` needed. Add `meta.js` when you want to declare params or presets. See the [Component Metadata Reference](https://github.com/uniweb/docs/blob/main/reference/component-metadata.md) for the full schema.
 
-The `meta.js` file defines what content and parameters a component accepts. The runtime uses this metadata to apply defaults and guarantee content structure—no defensive null checks needed in your component code.
+`meta.js` declares what content and parameters a section type accepts. The runtime fills each param from its default there, and hands every section the full content shape, so your components need no defensive null checks.
 
 ### Your First Content Change
 
-Open `site/pages/home/hero.md` and edit the headline:
+Open a section of the home page (in the starter, `site/pages/home/1-welcome.md`) and edit the headline:
 
 ```markdown
 ---
-type: Hero
+type: Section
 ---
 
 # Your New Headline Here
@@ -236,10 +274,10 @@ Save and see the change instantly in your browser.
 
 ### Your First Component Change
 
-Open `src/sections/Hero.jsx`. The component receives parsed content:
+Open the section type that renders it (in the starter, `src/sections/Section/index.jsx`). The component receives parsed content:
 
 ```jsx
-export default function Hero({ content }) {
+export default function Section({ content, params }) {
   const { title, paragraphs, links, images, items } = content
   // Edit the JSX below...
 }
@@ -249,7 +287,7 @@ The parser extracts semantic elements from markdown—`title` from the first hea
 
 ## Foundations Are Portable
 
-The `src/` folder (your project's foundation) ships with your project as a convenience, but a foundation is dynamically loaded — sites reference it by configuration, not by folder proximity.
+The `src/` folder (your project's foundation) ships with your project as a convenience, but sites reference a foundation by configuration, not by folder proximity.
 
 **Two ways to use a foundation:**
 
@@ -258,7 +296,7 @@ The `src/` folder (your project's foundation) ships with your project as a conve
 | **Local folder** | Foundation lives in your workspace | Developing site and components together            |
 | **Runtime link** | Foundation loads from a URL        | Independent release cycles, platform-managed sites |
 
-You can delete the `src/` folder entirely and point your site at a registered foundation. Or develop a foundation locally, then register it for other sites to consume. The site doesn't care where its components come from.
+Develop a foundation locally, then register it for other sites to use. A site can also name a registered foundation instead of a local one — a project made by `uniweb clone` does — and `uniweb dev` runs it, while Uniweb hosting builds and serves it. The site doesn't care where its components come from.
 
 **This enables two development patterns:**
 
@@ -282,10 +320,10 @@ cd my-workspace
 uniweb add project blog
 
 # Add a second foundation at root
-uniweb add foundation DocKit
+uniweb add foundation doc-kit
 
 # Add a site wired to a specific foundation
-uniweb add site docs --foundation DocKit
+uniweb add site docs --foundation doc-kit
 
 # Add an extension (auto-wired to the only site)
 uniweb add extension effects
@@ -300,18 +338,13 @@ pnpm dev     # or npm run dev
 
 The workspace grows organically. `add` handles placement, wires dependencies, updates workspace globs, and generates root scripts. The name you provide becomes both the directory name and the package name. Use `--path` to override default placement, or `--project` for explicit co-located layouts.
 
-## Deployment
-
-A Uniweb project produces two artifacts — a **site** (content) and a **foundation** (code). **Who manages the content** decides what you ship:
+## Other Ways to Ship
 
-- If you (or your dev team) manage the content, you ship them together — the site and its foundation, bundled or linked.
-- If someone else manages the content, you ship only the foundation. Content authors compose sites in the Uniweb apps; there's no site to deploy from your repo.
+A Uniweb project produces two artifacts — a **site** (content) and a **foundation** (code). Connected to the app, both sides edit one site, as above. The framework also works on its own, and **who manages the content** decides what you ship.
 
-### Path 1 — You manage the content
+### You manage the content, in files
 
-You (or your dev team) write the markdown. Deploy site + foundation together.
-
-The shortest path to a live site is free, on GitHub Pages, with a custom domain:
+You (or your dev team) write the markdown. Deploy site + foundation together. The shortest path to a live site is free, on GitHub Pages, with a custom domain:
 
 ```bash
 uniweb create .   # from within a freshly-cloned GitHub repo
@@ -325,7 +358,7 @@ uniweb add ci --host=github-pages
 
 **When to choose Uniweb hosting instead** (paid): when you need dynamic-page prerender at the edge (for collections fetched at runtime, not just at build time), foundation/runtime version propagation without redeploying every site, or edge SSR. If your site's content lives in markdown and updates ship via git, free CI is the right call.
 
-### Path 2 — Someone else manages the content
+### Your clients manage the content, in the app
 
 You're building a foundation for clients, content authors, or any team that won't write markdown. The foundation is your product; the repo's `site/` is a test harness for the code (run `pnpm dev` to preview your components against sample content). You don't deploy a site — you register a foundation:
 
@@ -338,10 +371,6 @@ Real sites built on your foundation are managed in the **Uniweb app** — a visu
 
 This is the best path when site content has a life independent of the foundation's release cycle — agencies, design studios, multi-client teams, or any project where content authors aren't the same people as the developers.
 
-### Hybrid
-
-Markdown in a git repo and content in the Uniweb apps can share the same site. `uniweb push` sends local content to the backend, `uniweb pull` brings the backend's content back — in a git repository by merging it into your branch, like `git pull`, so edits made on both surfaces at once are combined and only a genuine overlap is a conflict to settle — and `uniweb clone` bootstraps a local project from a site that already lives in the backend. Authors edit visually, devs edit in their IDE, both surfaces work on the same content. Review flows and branch isolation across the two are still evolving.
-
 ### Commands at a glance
 
 | Command | What it does |
@@ -349,22 +378,20 @@ Markdown in a git repo and content in the Uniweb apps can share the same site. `
 | `uniweb deploy` | Ask where the site should go, then do it. Remembers the answer in `deploy.yml`. |
 | `uniweb add ci --host=<adapter>` | Scaffold a CI workflow (+ PR previews) so every push deploys. `github-pages`, `cloudflare-pages`, `netlify`, `vercel`. |
 | `uniweb add ci --target foundation` | Publish foundations at permanent versioned GitHub Pages URLs — the free alternative to the catalog. |
-| `uniweb publish` | Go live on Uniweb hosting (paid) — syncs content, brings the site's foundation along, and serves dynamically. The canonical verb for Uniweb hosting. |
+| `uniweb publish` | Go live on Uniweb hosting (paid) — brings the site's foundation along, pushes the content, and serves the site dynamically. The canonical verb for Uniweb hosting. |
 | `uniweb deploy --host=<adapter>` | Ship to a third-party static host in one step — builds `dist/`, uploads, invalidates. Drives that host's own CLI. |
 | `uniweb export` | Produce a self-contained `dist/` for any static host. You upload it yourself. `--host=<adapter>` adds host-specific helper files. |
-| `uniweb register --scope @org` | Register a foundation to the registry (path 2). |
+| `uniweb register --scope @org` | Register a foundation to the registry, for sites managed in the app. |
 | `uniweb build` | Inspect a build locally. For shipping, use `publish` (Uniweb hosting) or `deploy`/`export` (static hosts). |
 | `uniweb update` | Align this project with the CLI you're running: bump `@uniweb/*` deps in every `package.json` to the CLI's matrix (then install), and refresh `AGENTS.md`. Pins to *this* CLI's matrix — run `npx uniweb@latest update` to align to the latest release. Updating the CLI itself is your package manager's job (`npm i -g uniweb@latest`). |
 
 `--host=<adapter>` is the same option across `deploy`, `export`, and `add ci`. Built-in adapters: `github-pages`, `cloudflare-pages`, `netlify`, `vercel`, `s3-cloudfront`, and `generic-static` (an artifact shape for `export`, not a deploy target). Each adapter implements only the operations it supports, and the CLI never offers one it can't perform: `add ci` lists only hosts that can scaffold a workflow, and `deploy`'s picker lists only destinations with a working deploy hook.
 
----
-
-Both paths use the same framework. The difference is who edits content, where it lives, and what gets deployed. For the deeper menu — standalone vs cataloged foundations, S3+CloudFront, manual exports, per-host recipes, foundation propagation — see → **[Deploying](https://github.com/uniweb/docs/blob/main/development/deploying.md)**.
+For the deeper menu — standalone vs cataloged foundations, S3+CloudFront, manual exports, per-host recipes, foundation propagation — see → **[Deploying](https://github.com/uniweb/docs/blob/main/development/deploying.md)**.
 
 ---
 
-## Keeping a Project in Sync
+## Keeping a Project Current
 
 Uniweb projects pin to specific `@uniweb/*` versions in their `package.json` files and ship an `AGENTS.md` stamped with the CLI version that wrote it. As the framework releases, both can drift from what the CLI you're running expects.
 
@@ -395,7 +422,7 @@ yarn global add uniweb@latest # yarn
 
 ## Documentation
 
-Full documentation is available at **[github.com/uniweb/docs](https://github.com/uniweb/docs)**:
+Full documentation is at **[uniweb.io/docs](https://uniweb.io/docs)**, written in the public [uniweb/docs](https://github.com/uniweb/docs) repository:
 
 | Section | Topics |
 | ------- | ------ |
@@ -404,6 +431,8 @@ Full documentation is available at **[github.com/uniweb/docs](https://github.com
 | [Development](https://github.com/uniweb/docs/tree/main/development) | Building foundations, component patterns, data fetching, layouts |
 | [Reference](https://github.com/uniweb/docs/tree/main/reference) | Configuration files, kit API, CLI commands, deployment |
 
+For AI agents, the documentation's index is [uniweb.io/llms.txt](https://uniweb.io/llms.txt).
+
 ### Quick Reference
 
 | Topic              | Guide                                                               |
@@ -443,7 +472,6 @@ import { defineFoundationConfig } from '@uniweb/build'
 
 export default defineFoundationConfig({
   // All options are optional - entry is auto-generated
-  fileName: 'foundation', // Output file name
   externals: [], // Additional packages to externalize
   includeDefaultExternals: true, // Include react, @uniweb/core, etc.
   tailwind: true, // Enable Tailwind CSS v4 Vite plugin
@@ -495,21 +523,25 @@ packages:
 
 ## FAQ
 
-**How is this different from MDX?**
+**Do I need the Uniweb app?**
 
-MDX blends markdown and JSX—content authors write code. Uniweb keeps them separate: content stays in markdown, components stay in React. Authors can still embed interactive components (via `![](@Component)` syntax), but they never see JSX. Component updates don't require content changes, and content changes can't break components.
+No. The framework works on its own: content in markdown, built and deployed like any Vite project, to any static host. Connect the app when people who don't write code need to edit the site — or when you'd rather not build an editing interface for them.
+
+**Is the app a CMS?**
 
-**How is this different from Astro?**
+It's where authors work: they compose pages from your section types and manage records through your schemas, with live previews. There's no admin interface or editing UI for you to build, and a site's content isn't locked in it: `uniweb clone` or `uniweb pull` brings it into a project as files in git, kept in sync both ways.
 
-Astro is a static site generator. Uniweb is a component content architecture that works with any deployment (static, SSR, or platform-managed). The foundation model means components are portable across sites and ready for integration with visual editors.
+**How is this different from MDX?**
+
+MDX blends markdown and JSX—content authors write code. Uniweb keeps them separate: content stays in markdown, components stay in React. Authors can still embed interactive components (via `![](@Component)` syntax), but they never see JSX. Component updates don't require content changes, and content changes can't break components.
 
-**Do I need uniweb.app?**
+**How is this different from Astro and other site frameworks?**
 
-No. Local markdown files work great for developer-managed sites. The platform adds dynamic content, visual editing, and team collaboration when you need it.
+They build sites from code and content files, and so does Uniweb. Uniweb adds the other interface: a visual authoring app, kept in sync with your project, where your components are the authors' building blocks. The foundation model also makes components portable across sites, with any deployment — static, SSR, or platform-managed.
 
 **Can I use an existing component library?**
 
-Yes. Foundations are standard React. Import any library into your foundation components. The `{ content, params }` interface only applies to section types (components with `meta.js`) — everything else uses regular React props.
+Yes. Foundations are standard React. Import any library into your foundation components. The `{ content, params }` interface only applies to section types (the components authors pick from markdown) — everything else uses regular React props.
 
 **Is this SEO-friendly?**
 
@@ -531,4 +563,4 @@ Yes — documentation is a natural fit. Content stays in markdown (easy to versi
 
 ## License
 
-Apache 2.0
+Apache 2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "1.20.3",
+  "version": "1.21.0",
   "description": "Create structured Vite + React sites with content/code separation",
   "type": "module",
   "bin": {
@@ -41,15 +41,15 @@
     "js-yaml": "^4.3.2",
     "prompts": "^2.4.2",
     "tar": "^7.5.21",
+    "@uniweb/content-writer": "~1.3.1",
     "@uniweb/core": "~1.4.7",
     "@uniweb/schemas": "~1.6.5",
-    "@uniweb/semantic-parser": "~1.13.0",
-    "@uniweb/content-writer": "~1.3.1"
+    "@uniweb/semantic-parser": "~1.13.0"
   },
   "peerDependencies": {
     "@uniweb/build": "~1.10.2",
-    "@uniweb/semantic-parser": "~1.13.0",
-    "@uniweb/content-reader": "~1.5.7"
+    "@uniweb/content-reader": "~1.5.7",
+    "@uniweb/semantic-parser": "~1.13.0"
   },
   "peerDependenciesMeta": {
     "@uniweb/build": {

package/partials/agents.md

@@ -33,15 +33,18 @@ You're building a *system* of section types, not individual pages. That's what m
 | Existing project, component task (new section type, restyle) | **Part 2**, then Part 4 |
 | Porting a design from React / Next / a generated site | **Part 1**, then Part 5 → *Migrating* |
 
-### Three commands that replace guessing
+### Four commands that replace guessing
 
 ```bash
+uniweb status                # what changed in the app, in git and in Uniweb — and what to run
 uniweb inspect <path>        # print the parsed content shape of a section or page
 uniweb <command> --help      # exact flags, always current — no side effects
 uniweb doctor                # diagnose project configuration (--fix to repair)
 ```
 
-`uniweb inspect` is the important one. Every parse rule in Part 3 is faster to *confirm* than to re-derive, and re-deriving from memory is where agents go wrong. Don't predict the shape — print it.
+`uniweb inspect` is the important one for content. Every parse rule in Part 3 is faster to *confirm* than to re-derive, and re-deriving from memory is where agents go wrong. Don't predict the shape — print it.
+
+`uniweb status` is the one for a project other people edit. A site in the Uniweb app can change there at any time, teammates push to git, and Uniweb releases often. Run it when you begin, before you push, and after a command refuses: it changes nothing, and ends with the commands to run, in order (`--json` for a script).
 
 ### The four silent failures
 
@@ -59,7 +62,7 @@ This guide covers what you can't derive by reading code. Everything else is in t
 **Start at the index.** One address, and it's the only documentation URL worth memorizing:
 
 ```
-https://www.uniweb.io/llms.txt
+https://uniweb.io/llms.txt
 ```
 
 It lists every documentation page with a one-line description and a fetchable link. Go there whenever your question isn't answered in this file — and *especially* when you don't know whether a feature exists at all. That's where guessing does the most damage: **a 404 on a path you invented tells you your guess was wrong, not that the feature is missing.** Concluding "the framework doesn't support X" from a failed fetch is a mistake worth actively guarding against; the index answers the existence question directly.
@@ -76,7 +79,7 @@ Same content, greppable, and one network operation instead of many. `grep -ri "q
 
 Documentation paths in this guide are given bare — `development/creating-components.md` — so they resolve three ways: as a key in the index, as a file in a clone, or at `https://raw.githubusercontent.com/uniweb/docs/main/{path}`.
 
-> **Don't confuse the two doc sites.** `www.uniweb.io/docs` is the **developer** documentation — this is the one you want. `docs.uniweb.app` is the *author-facing* app documentation, written for non-technical people using the visual editor; it won't answer framework questions.
+> **Don't confuse the two doc sites.** `uniweb.io/docs` is the **developer** documentation — this is the one you want. `docs.uniweb.app` is the *author-facing* app documentation, written for non-technical people using the visual editor; it won't answer framework questions.
 
 **The table below saves you the round trip** for the tasks that come up most:
 
@@ -189,6 +192,8 @@ The rest of this guide explains how Uniweb works. This part is what to do *first
 
 ### 1. Orient — what kind of workspace is this?
 
+**Run `uniweb status` first.** It says whether the site changed in the app since this copy last synced, whether git or Uniweb has something newer, and what to run about each — before you edit something someone else just changed.
+
 **There is no single layout. Read `pnpm-workspace.yaml` first** — its `packages:` globs name the shape in one glance:
 
 | Globs | Layout | What it implies |
@@ -2818,7 +2823,8 @@ uniweb publish                    # Ship to Uniweb hosting, foundation included
 uniweb add ci --target foundation # Publish a foundation for free at permanent versioned URLs
                                   # (GitHub Pages → foundations/<name>/<version>/entry.js)
 
-uniweb push / pull / clone / status   # Git-style content sync with the Uniweb backend
+uniweb status                         # What changed in the app, in git and in Uniweb — and what to run
+uniweb push / pull / clone            # Git-style content sync with the Uniweb backend
 uniweb refresh / sync                 # Catch up (git + backend, never pushes) / catch up, then push
 uniweb login --org @acme              # The workspace you work in — new sites are created there (see below)
 uniweb register [--scope @scope]      # Register a foundation + its data schemas to the registry
@@ -2830,7 +2836,7 @@ uniweb rename <foundation|site|extension> <old> <new>   # Rename across the whol
 uniweb i18n extract / init / sync / status / audit      # Translation workflow (build first)
 uniweb i18n init-freeform / update-hash / move / rename / prune --freeform
 
-uniweb -v                         # Installed CLI version — and whether a newer one exists
+uniweb -v                         # CLI version — only a global install also says whether a newer one exists
 uniweb doctor                     # Diagnose project configuration (--fix to auto-repair)
 uniweb validate                   # Check file-based data against declared schemas (fails on a violation; --lax)
 npx uniweb@latest update          # Align @uniweb/* deps + AGENTS.md (--dry-run, --yes)
@@ -2896,6 +2902,8 @@ Foundations have their own free path too: `uniweb add ci --target foundation` pu
 - **Git is the reviewed, durable record** — you `pull` content back, read it with `git diff`, and commit.
 - **Authors never push or pull.** For them, content simply updates, whether the change came from another author or from a developer's CLI.
 
+**Working on a site others edit — run `uniweb status` when you begin, before you push, and after any refusal.** It reads the backend without taking anything: what changed there since this copy last synced, file by file; what you hold that it lacks; whether the site is live; who has it open in the app right now, and on which file. Then it lists the commands to run, in an order that works from the top — `uniweb pull` before the push it would otherwise refuse. Three habits go with it: take what changed (`pull`, or `refresh`) before you edit; never `--force` past a refusal; and when someone has a page open in the app, tell the person before you change that page. A step marked *ask the person first* — going live, which may cost money — is theirs to decide.
+
 **Nobody's work is overwritten without asking.** `uniweb push` is refused if the site changed on the backend since your last pull — usually an author editing in the app — and reports what changed; nothing is written. Edits to different sections never collide. **In a git repository `uniweb pull` merges, like `git pull`:** it commits the backend's content (*"The site's content on …"*) and merges that commit into your branch, against the last state of the site your history shares with the backend. Your work, committed or not, and a teammate's arriving through git are kept; a file the backend never had is never deleted; changes to different parts of a file combine silently; and only a genuine overlap leaves conflict markers and a non-zero exit — so `uniweb pull && uniweb push` never ships markers. Settle a conflict as in any merge, then `git commit`; where your uncommitted changes overlap what the pull brought, the markers are theirs — settle them and `git add` each file, then `git stash drop` (git keeps them in the stash too). A push or publish is refused while a file under the site is in conflict. **In a git repository a push sends what you have committed:** with the site's content not committed it is refused before anything is sent, naming the files — commit them, or run `uniweb push --commit -m "…"` (it commits the site's content only, and leaves anything else staged as it is); `publish` and `sync` take `--commit` too. That commit is where the next pull merges from, which is how the pull tells your changes from the backend's. What the push writes back into the files — the ids the backend assigned — it commits itself, as `uniweb`. When the backend has nothing new, a pull says so and lists the files where yours hold changes it lacks. `uniweb refresh` runs `git pull` first, then the same pull. A push is also refused when your branch does not hold what this copy last took from the backend — after `git merge --abort`, or in a fresh clone that has not pulled — so pull, then push. Outside git — which includes a folder the repository around it ignores, such as a scratch directory — `uniweb pull` takes the backend's version over your files, asking first. `--force` is the deliberate overwrite (on `push` it replaces the backend's changes, on `pull` it discards yours); don't use it to get past a refusal. `uniweb sync` is `refresh` then `push`; neither publishes.
 
 **`sync.json` says which site this is, on each backend.** The first push to a backend records what that backend assigned — the site's id and owner, the ids of its records and uploaded files — in `sync.json` beside `site.yml`. In a git repository the push commits it; never edit it. **To make a new site from a copy of a project, run `uniweb forget --all` in the copy before its first push** — the copy carries the original's `sync.json`, so otherwise its push updates the original's site. When two projects in one workspace hold the same site, a push or publish from either is refused until that is done. `uniweb forget --server <url>` removes just one backend's records, such as a scratch server's. A record file's `$uuid` is its own id and stays in both cases. **`push`, `pull` and `publish` go to the backend you are logged in to** — the last `uniweb login --server <url>` — and never to one you are not logged in to. A bare `uniweb login` logs in to https://uniweb.app; for any other backend, name it — logging in is how you switch, and the backend commands take no `--server` of their own. When the project has no site on that backend but has one elsewhere, a push says so before creating a new one.
@@ -2942,12 +2950,15 @@ Either side can publish. Nothing about this changes how you build: the same foun
 ### Staying current
 
 ```bash
-uniweb -v                  # installed CLI version, and whether a newer one is available
+uniweb status              # among its checks: whether a newer Uniweb is out than this project runs
+uniweb -v                  # CLI version — only a global install also says whether a newer one exists
 uniweb doctor              # report drift in this project, changing nothing
 npx uniweb@latest update --dry-run   # preview exactly what update would change
 npx uniweb@latest update             # apply: align @uniweb/* deps AND refresh AGENTS.md
 ```
 
+When `status` names a newer release, take it: `npx uniweb@latest update`, then build and look at the pages. Releases rarely ask anything of a project.
+
 **`npx uniweb@latest update` is the command for bringing a project up to date.** It aligns the project's `@uniweb/*` dependencies *and* this AGENTS.md to the version matrix of the CLI that runs it. Deps and documentation move together — that's the whole point of the verb.
 
 **What the version numbers mean.** A patch brings fixes and features; a minor version is where Uniweb puts breaking changes — `update` lists each package that crosses one, so build and check the project before shipping — and a major is kept for something really big. Dependencies are written as tilde ranges (`~1.0.1`), so `pnpm install` and `pnpm update` never cross a minor on their own. The move from 0.x to 1.0.1 asks nothing of a project that was on the latest 0.x versions — 1.0.1 carried every package's 0.x line over — though `update` marks each package `major · BREAKING`.
@@ -3134,7 +3145,7 @@ Loud failures:
 
 ## Documentation index
 
-**Index of every page: https://www.uniweb.io/llms.txt** — start there when you don't know which page you need.
+**Index of every page: https://uniweb.io/llms.txt** — start there when you don't know which page you need.
 
 Source repo (public, cloneable): **https://github.com/uniweb/docs** · any page as raw markdown at `https://raw.githubusercontent.com/uniweb/docs/main/{section}/{page}.md`. See *Documentation* in Part 0 for when to fetch versus clone.