uniweb 1.20.3 → 1.21.0

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

package/partials/adding-pages.hbs

@@ -1,77 +0,0 @@
-### Adding a New Page
-
-1. Create a folder: `site/pages/my-page/`
-2. Add `page.yml`:
-   ```yaml
-   title: My Page
-   ```
-3. Add section files: `1-hero.md`, `2-content.md`, etc.
-
-### Section Ordering
-
-By default, sections are discovered from `.md` files and sorted by numeric prefix (`1-`, `2-`, `3-`).
-
-**Decimal prefixes** allow inserting sections without renumbering: `2.5-` sorts between `2-` and `3-`.
-
-For explicit control, use the `sections` property in `page.yml`:
-
-```yaml
-title: My Page
-sections:
-  - hero
-  - features
-  - pricing
-```
-
-This makes reordering easy (move lines) and allows commenting out sections temporarily.
-
-**Options:**
-- `sections: *` or omit — auto-discover and sort `.md` files by prefix (default)
-- `sections: [hero, features]` — explicit ordering, no prefixes needed
-- `sections: []` — pure route with no content sections
-
-### Section Hierarchy (Subsections)
-
-For parent-child relationships, use the explicit array with nesting:
-
-```yaml
-sections:
-  - hero
-  - features:
-      - logocloud
-      - stats
-  - pricing
-```
-
-This is clearer than prefix notation and easier to restructure.
-
-**Advanced:** Comma prefixes (`1,1-`, `1,2-`) also denote hierarchy, but explicit arrays are recommended for readability.
-
-### Page Ordering and Index Pages
-
-Parent controls which page is the "index" for its route. The index page gets the parent's route.
-
-**In `site.yml`** (for top-level pages):
-```yaml
-name: My Site
-pages: [home, about, features]  # First (home) is homepage at /
-# Or just name the homepage:
-index: home
-```
-
-**In `page.yml`** (for child pages):
-```yaml
-title: Documentation
-pages: [getting-started, installation, config]  # First is index for /docs
-# Or just name the index:
-index: getting-started
-```
-
-**How it works:**
-- `pages: [a, b, c]` — Explicit order, first item gets parent route
-- `index: name` — Just set the index, auto-discover the rest
-- Omit both — Sort by `order` prop, lowest becomes index
-
-**Example:** If `getting-started` is the index for `/docs`:
-- `pages/docs/getting-started/` → route `/docs`
-- `pages/docs/installation/` → route `/docs/installation`

package/partials/ai-assistance.hbs

@@ -1,28 +0,0 @@
-## Developer Guide
-
-[AGENTS.md](./AGENTS.md) is a comprehensive guide to building with Uniweb — content authoring, component development, theming, configuration, and the kit API. Despite the name, it's written for developers and AI assistants alike. Read it to get productive fast.
-
-### AI Prompts
-
-AI coding assistants (Claude Code, Cursor, Copilot, etc.) read AGENTS.md automatically. 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 foundation component and extract
-all text content into markdown files in site/pages/home/. The final page
-should render identically to the original. See AGENTS.md for the full guide.
-```
-
-**Adding a new component:**
-```
-Create a Pricing component with 3-column cards. It should support light and
-dark themes. Use content.items for the pricing tiers — each item has a title,
-paragraph (price), and links (CTA button).
-```
-
-**Adding a new page:**
-```
-Add a /contact page with a hero section and a form section. Reuse the Hero
-component from the homepage. Create a new ContactForm component for the form.
-```

package/partials/components-docs.hbs

@@ -1,13 +0,0 @@
-## Component Documentation
-
-Generate up-to-date documentation for all foundation components:
-
-```bash
-# From foundation directory
-uniweb docs
-
-# Or from site directory (auto-detects linked foundation)
-cd site && uniweb docs
-```
-
-This creates `COMPONENTS.md` with details on each component's parameters, presets, and content elements. The documentation is generated from component `meta.js` files, so it's always current.

package/partials/config-reference.hbs

@@ -1,66 +0,0 @@
-## Configuration Reference
-
-### site.yml
-
-Site-wide configuration in `site/site.yml`:
-
-```yaml
-name: My Site                    # Site name
-defaultLanguage: en              # Default locale code
-foundation: foundation           # Foundation package name
-
-# Page ordering (controls top-level navigation)
-pages: [home, about, features]   # First is homepage at /
-# Or just name the homepage:
-index: home
-
-# Internationalization
-i18n:
-  locales: [es, fr]              # Non-default locales to build
-  localesDir: locales            # Translation files directory
-
-# Build options
-build:
-  prerender: true                # Enable static site generation
-```
-
-### page.yml
-
-Page-level configuration in `site/pages/[page]/page.yml`:
-
-```yaml
-title: About Us                  # Page title (used in <title> and nav)
-description: Learn about us      # Meta description
-label: About                     # Short nav label (optional)
-order: 2                         # Navigation sort order
-
-# Child page ordering
-pages: [intro, guide, reference] # First is index for this route
-index: intro                     # Or just name the index
-
-# Navigation visibility
-hidden: true                     # Hide from all navigation
-hideIn: [header]                 # Hide from named nav areas only (header, footer, sidebar, …)
-
-# Layout overrides
-layout:
-  header: false                  # Don't render header
-  footer: false                  # Don't render footer
-
-# Section ordering
-sections:                        # Explicit section order
-  - hero
-  - features:                    # Nested = subsections
-      - logocloud
-      - stats
-  - pricing
-
-# SEO
-seo:
-  noindex: true
-  image: /og-image.png
-  changefreq: monthly
-  priority: 0.8
-```
-
-Run `uniweb docs site` or `uniweb docs page` for complete reference.

package/partials/deployment.hbs

@@ -1,13 +0,0 @@
-## Deployment
-
-Build and deploy the `site/dist` folder:
-
-```bash
-pnpm build
-```
-
-**Supported platforms:**
-- **Vercel**: `cd site && vercel`
-- **Netlify**: Build command `pnpm build`, publish `site/dist`
-- **GitHub Pages**: Use GitHub Actions
-- **Cloudflare Pages**: Connect repo, set `pnpm build` and `site/dist`

package/partials/learn-more.hbs

@@ -1,6 +0,0 @@
-## Learn More
-
-- [AGENTS.md](./AGENTS.md) — comprehensive guide to building with Uniweb
-- [Uniweb Documentation](https://github.com/uniweb/docs) — full reference docs
-- [Uniweb CLI](https://github.com/uniweb/cli) — project scaffolding and build tools
-- [Tailwind CSS v4](https://tailwindcss.com)

package/partials/quick-start.hbs

@@ -1,8 +0,0 @@
-## Quick Start
-
-```bash
-pnpm install    # Install dependencies
-pnpm dev        # Start development server
-```
-
-Visit `http://localhost:5173` to see your site.

package/partials/search-docs.hbs

@@ -1,110 +0,0 @@
-## Search Functionality
-
-Uniweb sites support full-text search out of the box. Search indexes are generated automatically at build time.
-
-### Enabling Search in Your Foundation
-
-To add search to your site, your foundation needs the **Fuse.js** library:
-
-```bash
-cd foundation
-pnpm add fuse.js
-```
-
-Then use the search helpers from `@uniweb/kit`:
-
-```jsx
-import { useSearch } from '@uniweb/kit'
-
-function SearchComponent({ website }) {
-  const { query, results, isLoading, clear } = useSearch(website)
-
-  return (
-    <div>
-      <input
-        type="search"
-        placeholder="Search..."
-        onChange={e => query(e.target.value)}
-      />
-      {isLoading && <span>Searching...</span>}
-      <ul>
-        {results.map(result => (
-          <li key={result.id}>
-            <a href={result.href}>{result.title}</a>
-            <p dangerouslySetInnerHTML=\{{ __html: result.snippetHtml }} />
-          </li>
-        ))}
-      </ul>
-    </div>
-  )
-}
-```
-
-### Search Configuration
-
-Search is enabled by default. To customize, add to `site/site.yml`:
-
-```yaml
-search:
-  enabled: true
-  exclude:
-    routes: [/admin, /private]    # Don't index these routes
-    components: [Debug]            # Don't index these component types
-```
-
-### How It Works
-
-1. **Build time**: Uniweb extracts text from all pages and sections
-2. **Output**: A `search-index.json` file is generated in `dist/`
-3. **Runtime**: Components fetch and search the index client-side
-4. **Multi-locale**: Each locale gets its own search index
-
-### Search API
-
-The `website` object provides these methods:
-
-```javascript
-// Check if search is available
-website.isSearchEnabled()      // Returns boolean
-
-// Get the URL for the search index
-website.getSearchIndexUrl()    // "/search-index.json" or "/es/search-index.json"
-
-// Get full search configuration
-website.getSearchConfig()      // { enabled, indexUrl, locale, include, exclude }
-```
-
-### Search Result Format
-
-Results from `useSearch()` include:
-
-| Field | Description |
-|-------|-------------|
-| `id` | Unique result identifier |
-| `type` | `"page"` or `"section"` |
-| `route` | Page route |
-| `href` | Full link including anchor |
-| `title` | Result title |
-| `pageTitle` | Parent page title (for sections) |
-| `snippetHtml` | Excerpt with `<mark>` highlighted matches |
-| `snippetText` | Plain text excerpt |
-
-### Without @uniweb/kit
-
-If you prefer not to use the kit helpers, you can fetch the index directly:
-
-```javascript
-// Fetch the search index
-const response = await fetch(website.getSearchIndexUrl())
-const index = await response.json()
-
-// Use with Fuse.js directly
-import Fuse from 'fuse.js'
-const fuse = new Fuse(index.entries, {
-  keys: ['title', 'content'],
-  threshold: 0.35,
-  includeMatches: true
-})
-
-const results = fuse.search('your query')
-```