uniweb 1.31.2 → 1.31.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -101,7 +101,7 @@ my-project/
101
101
  └── AGENTS.md # The project's manual, for developers and AI agents
102
102
  ```
103
103
 
104
- **Pages are folders.** Create `pages/about/` with markdown files inside → visit `/about`. That's the whole routing model.
104
+ **Pages are directories.** Create `pages/about/` with markdown files inside → visit `/about`. That's the whole routing model.
105
105
 
106
106
  **Batteries included:** File-based routing, pre-rendering, localization, dynamic routes, media processing, search indexing, and more. See [Building with Uniweb](https://github.com/uniweb/docs/blob/main/development/building-with-uniweb.md) for the full list.
107
107
 
@@ -244,7 +244,7 @@ The `build` command outputs to `site/dist/`. With pre-rendering enabled (the def
244
244
 
245
245
  After creating your project:
246
246
 
247
- 1. **Explore the structure** — Browse `site/pages/` to see how content is organized. Each page folder contains `page.yml` (metadata) and `.md` files (sections).
247
+ 1. **Explore the structure** — Browse `site/pages/` to see how content is organized. Each page's directory contains `page.yml` (metadata) and `.md` files (sections).
248
248
 
249
249
  2. **Generate component docs** — Run `uniweb docs` to create `COMPONENTS.md` with all available components, their parameters, and presets.
250
250
 
@@ -287,16 +287,16 @@ The parser extracts semantic elements from markdown—`title` from the first hea
287
287
 
288
288
  ## Foundations Are Portable
289
289
 
290
- 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.
290
+ The `src/` directory (your project's foundation) ships with your project as a convenience, but sites reference a foundation by configuration, not by where its directory is.
291
291
 
292
292
  **Two ways to use a foundation:**
293
293
 
294
294
  | Mode | How it works | Best for |
295
295
  | ---------------- | ---------------------------------- | -------------------------------------------------- |
296
- | **Local folder** | Foundation lives in your workspace | Developing site and components together |
296
+ | **Local directory** | Foundation lives in your workspace | Developing site and components together |
297
297
  | **Runtime link** | Foundation loads from a URL | Independent release cycles, platform-managed sites |
298
298
 
299
- 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.
299
+ 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 both `uniweb dev` and Uniweb hosting run it. The site doesn't care where its components come from.
300
300
 
301
301
  **This enables two development patterns:**
302
302
 
@@ -356,7 +356,7 @@ uniweb add ci --host=github-pages
356
356
 
357
357
  **Other free static hosts.** Cloudflare Pages, Netlify, and Vercel work three ways: `uniweb add ci --host=<adapter>` scaffolds a workflow (and a per-PR preview that comments the URL), connecting the repo through their dashboard lets the host build it with no config at all, or `uniweb deploy --host=<adapter>` uploads from your machine.
358
358
 
359
- **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.
359
+ **When to choose Uniweb hosting instead** (paid): when you need pages prerendered over live data (records 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.
360
360
 
361
361
  ### Your clients manage the content, in the app
362
362
 
@@ -364,9 +364,11 @@ You're building a foundation for clients, content authors, or any team that won'
364
364
 
365
365
  ```bash
366
366
  cd src
367
- uniweb register --scope @your-org
367
+ uniweb register
368
368
  ```
369
369
 
370
+ It registers under the scope of the Uniweb workspace you logged in to (`uniweb login --org @your-org`); `--scope` names another scope.
371
+
370
372
  Real sites built on your foundation are managed in the **Uniweb app** — a visual editor designed for non-technical authors. They never see git, markdown, yaml, or React. They see *your* components, with live previews and visual controls for the params you defined. The foundation becomes the editor's native vocabulary for that site: you keep creative control of the design system, they get an editor that feels custom-built for them.
371
373
 
372
374
  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.
@@ -381,7 +383,7 @@ This is the best path when site content has a life independent of the foundation
381
383
  | `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. |
382
384
  | `uniweb deploy --host=<adapter>` | Ship to a third-party static host in one step — builds `dist/`, uploads, invalidates. Drives that host's own CLI. |
383
385
  | `uniweb export` | Produce a self-contained `dist/` for any static host. You upload it yourself. `--host=<adapter>` adds host-specific helper files. |
384
- | `uniweb register --scope @org` | Register a foundation to the registry, for sites managed in the app. |
386
+ | `uniweb register` | Register a foundation to the registry, under your Uniweb workspace's scope, for sites managed in the app. |
385
387
  | `uniweb build` | Inspect a build locally. For shipping, use `publish` (Uniweb hosting) or `deploy`/`export` (static hosts). |
386
388
  | `uniweb guide [name]` | Print a guide to building with Uniweb: `content`, `foundation`, `theme` and more. A project's `AGENTS.md` says which a task needs. |
387
389
  | `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`). |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "uniweb",
3
- "version": "1.31.2",
3
+ "version": "1.31.4",
4
4
  "description": "Create structured Vite + React sites with content/code separation",
5
5
  "type": "module",
6
6
  "bin": {
@@ -41,15 +41,15 @@
41
41
  "js-yaml": "^4.3.2",
42
42
  "prompts": "^2.4.2",
43
43
  "tar": "^7.5.21",
44
- "@uniweb/core": "~1.6.9",
44
+ "@uniweb/schemas": "~1.7.0",
45
45
  "@uniweb/semantic-parser": "~1.13.2",
46
- "@uniweb/content-writer": "~1.3.1",
47
- "@uniweb/schemas": "~1.7.0"
46
+ "@uniweb/core": "~1.6.10",
47
+ "@uniweb/content-writer": "~1.3.1"
48
48
  },
49
49
  "peerDependencies": {
50
+ "@uniweb/build": "~1.20.4",
50
51
  "@uniweb/semantic-parser": "~1.13.2",
51
- "@uniweb/content-reader": "~1.5.9",
52
- "@uniweb/build": "~1.20.2"
52
+ "@uniweb/content-reader": "~1.5.9"
53
53
  },
54
54
  "peerDependenciesMeta": {
55
55
  "@uniweb/build": {
@@ -10,7 +10,7 @@ The foundation is the React that receives that object, under a runtime that owns
10
10
 
11
11
  ## 1. Why this is worth doing right
12
12
 
13
- Uniweb is an implementation of **Component Content Architecture (CCA)**: content and components are separate artifacts — different files, packages and maintainers — joined by a thin runtime at build time and in the browser. Full argument: `uniweb.io/docs/architecture/component-content-architecture.md`. What it buys you:
13
+ Uniweb is an implementation of **Component Content Architecture (CCA)**: content and components are separate artifacts — different files, packages and maintainers — joined by a thin runtime wherever a page renders: in a build, on the host and in the browser. Full argument: `uniweb.io/docs/architecture/component-content-architecture.md`. What it buys you:
14
14
 
15
15
  **You write less.** A section type carries no theme maps, null checks, hardcoded strings, wrapper element, sticky-spacer arithmetic or fetch lifecycle: the runtime does each once, for every section. What remains is rendering logic.
16
16
 
@@ -38,7 +38,7 @@ The principles to reason from when a table in §2 doesn't cover the case:
38
38
 
39
39
  - **The foundation provides options; the site configures.** The foundation doesn't know which site it serves; the site doesn't know how the foundation is built.
40
40
  - **Components render from content, not context.** Never the URL, the router or the layout; variation comes through params or a different type, chosen by the author.
41
- - **Configuration cascades** page → folder → site → foundation, like CSS specificity: defaults high, exceptions local.
41
+ - **Configuration cascades** `page.yml` → `folder.yml` → `site.yml` → foundation, like CSS specificity: defaults high, exceptions local.
42
42
  - **Metadata declares the interface.** `meta.js` drives defaults, the editor's controls, the schema and the docs.
43
43
  - **The site owns the theme.** Foundations declare variables, sites set values, components use tokens.
44
44
 
@@ -51,11 +51,12 @@ When a rule in §2 feels like friction, that is the moment you are about to take
51
51
  | By reflex you'd… | Here | Signal |
52
52
  |---|---|---|
53
53
  | Write `package.json`, `vite.config.js`, `index.html`, an entry file | `npx uniweb@latest create <name> --template <t>`; `uniweb add site / foundation / section / project / extension`. The CLI owns those files. | build fails far from the cause |
54
+ | Add a build step for the site: a Vite plugin, an npm script, code in `entry.js` | Nothing in the site's build runs on Uniweb hosting: `publish` sends the content, and the host renders it with the runtime and the registered foundation. Put code in the foundation and everything else in content. | silent — right under `uniweb dev` and `export`, missing once published |
54
55
  | `npm install` a foundation or theme; `npm install @uniweb/runtime` | A foundation is a workspace `file:` dependency or a catalog ref in `site.yml`, never an npm package. In a foundation the runtime arrives through `@uniweb/build`. Everything else — a carousel, a chart library, a date utility, `@uniweb/api` — you install in the foundation as in any project. | npm 404 / silent version skew |
55
56
  | `npm update` / `pnpm update` the `@uniweb/*` packages; `npx uniweb update` | `npx uniweb@latest update --yes` (`--yes` because there is no terminal to answer the prompt). The packages are a matched set and AGENTS.md updates with them. Without `@latest` it runs the CLI the project already pins and reports "aligned". | `status` and `doctor` name the drift |
56
57
  | Assume `localhost:5173`; run `npm run dev` inside the site | `uniweb dev` serves the site you are in (from the workspace root, the first, with a notice); read `Serving <site> at <url>`. `uniweb dev --status` / `--stop` know only that server. | wrong server, silent |
57
58
  | Read `foundation:` in `site.yml` as a path | A **package name**. Follow the `file:` dep in the site's `package.json`. `@org/name@1.2.3` means the source is not in this repo. | the build: `did not resolve` |
58
- | Trust folder names for the workspace layout | `pnpm-workspace.yaml` globs decide (§3.2). | — |
59
+ | Trust directory names for the workspace layout | `pnpm-workspace.yaml` globs decide (§3.2). | — |
59
60
  | `main.jsx`; JSX in a `.js` file | `main.js` is plain JS; JSX lives in `.jsx`. | build stops |
60
61
  | Guess which section types exist or what a param is called | `ls <foundation>/sections/`, `cat …/<Type>/meta.js`. Every foundation's vocabulary is different; `uniweb docs --from-source` writes it all to `COMPONENTS.md`. | red box / silent |
61
62
  | Predict what markdown parses to | `uniweb inspect <file>` prints the shape. | silent (wrong field) |
@@ -76,15 +77,16 @@ When a rule in §2 feels like friction, that is the moment you are about to take
76
77
  | Strip the content a new `type:` / `variant:` won't render before switching | Nothing to strip (§1): the switch is a one-line trial, and what stays afterwards is the author's call. | content loss |
77
78
  | `pages/fr/about.md` for French | `locales/` beside `pages/`; `pages/` holds the default language only. | silent — it becomes a page at `/fr` |
78
79
  | `t('key')`, `<Trans>` | Nothing — content arrives translated; each language is its own build. | — |
79
- | `src/assets/`, `assets/img.png` | `./img.png` beside the page, or `/img.png` in `public/`. There is no assets folder. | build stops, or warns |
80
+ | `src/assets/`, `assets/img.png` | `./img.png` beside the page, or `/img.png` in `public/`. There is no assets directory. | build stops, or warns |
80
81
  | `fetch: /api/posts`, `fetch: ./data.json` | `fetch:` names a query from `queries.yml`; a URL belongs on the query (`url:`). | build stops |
81
- | `records/blog/2025/post.md`; one YAML file holding a list | Flat: `records/<schema>/<name>.md`, one record per file; the file name is `$name`. | folder read as a schema, silent |
82
+ | `records/blog/2025/post.md`; one YAML file holding a list | Flat: `records/<schema>/<name>.md`, one record per file; the file name is `$name`. | a directory read as a schema, silent |
82
83
  | `` `/blog/${slug}` `` | `item.$route` — never compose a URL. | works until a page moves |
83
- | `page.yml` in a folder of pages | It makes one page, each `.md` a section. `folder.yml` keeps them pages and carries `layout`, `title` and SEO. Over a mount, `page.yml` with markdown of its own is a landing page *above* the mounted pages; a mount is one level under `pages/`, and a local subfolder beside it isn't read. | silent; the build names that subfolder |
84
+ | `page.yml` in a directory of pages | It makes one page, each `.md` a section. `folder.yml` keeps them pages and carries `layout`, `title` and SEO. Over a mount, `page.yml` with markdown of its own is a landing page *above* the mounted pages; a mount is one level under `pages/`, and a local subdirectory beside it isn't read. | silent; the build names that subdirectory |
84
85
  | Paste the gtag / GTM / Meta pixel snippet into a component, `index.html`, or `services.tracking.scripts` | Uniweb Cloud (`publish`): `services.google: { id: G-… }`, or `GTM-…` for a container, and the host loads Google's tag, free, with no code, on any foundation. `head.html` isn't applied there, and `scripts` takes URLs only. Static build (`export`, `deploy --host`): the snippet in `head.html` beside `site.yml`. More: `uniweb guide services`. | silent — Google reports nothing |
85
86
  | Expect `{company}` to resolve | Only under a foundation with `createLoomHandlers`; otherwise it renders literally. | build warns if `site.yml` has `placeholders:` |
86
87
  | `hidden: true` on `pages/404/` to keep it out of nav | That makes it a draft. `hideIn: ['*']` controls nav. | silent |
87
88
  | Treat `@child.md` / `_draft.md` as names | `@` = child section, placed by `nest:` (with none it renders last; a `sections:` list drops it); `_` = ignored. | build warns, unless `sections:` dropped it |
89
+ | Treat the files as the only copy of the content; regenerate pages from a script | On a synced site authors edit the same pages in the app, and a pull writes their edits into the files. Take what changed before you edit (`status` names it), and edit the files rather than regenerate them, or your next push replaces the authors' work. | silent after a pull; a push refuses a section changed on both sides |
88
90
 
89
91
  ### 2.3 Section types and the components behind them
90
92
 
@@ -126,7 +128,7 @@ When a rule in §2 feels like friction, that is the moment you are about to take
126
128
  | `font-serif`, `font-sans` | Tailwind's stack, not the site's — unless the foundation declares it as a `font-*` var in `main.js`. Families are the site's (`theme.yml fonts:`). | silent |
127
129
  | `@import url(fonts.googleapis…)` in CSS | `theme.yml fonts.import` / `faces`. | — |
128
130
  | `@tailwind base;` | Tailwind v4: `@import "tailwindcss"` plus kit's token imports (theme guide). | silent — most utilities missing |
129
- | Trust the foundation's own build to prove a class works | A site build and `uniweb dev` read what `styles.css` names: the whole foundation with `@import "tailwindcss" source("./")`, as the scaffold writes, else only the folders `@source` lists. | each names a folder a list missed, as does `doctor` |
131
+ | Trust the foundation's own build to prove a class works | A site build and `uniweb dev` read what `styles.css` names: the whole foundation with `@import "tailwindcss" source("./")`, as the scaffold writes, else only the directories `@source` lists. | each names a directory a list missed, as does `doctor` |
130
132
  | `prose` from `@tailwindcss/typography`, `prose-invert` | `@import "@uniweb/kit/prose-tokens.css"`; no invert — colors are already the theme's. | build warns; unstyled lists |
131
133
  | `html { scroll-behavior: smooth }` | Never on `html`/`body`; the runtime owns scrolling. | route transitions misbehave |
132
134
  | `filter: blur(80px)` for a glow | Radial gradient + `mask-image`. | Safari jank |
@@ -148,7 +150,7 @@ When a rule in §2 feels like friction, that is the moment you are about to take
148
150
  | `*/src`, `*/sites/*` | projects with sites | each project's foundation with its own sites |
149
151
  | plus a package whose `main.js` has `extension: true` | extensions | extra section types, runtime-loaded |
150
152
 
151
- A site is any package with a `site.yml`. `paths:` in `site.yml` can mount another folder or repo into the page tree, so a route's markdown may not live under `pages/`.
153
+ A site is any package with a `site.yml`. `paths:` in `site.yml` can mount another directory or repo into the page tree, so a route's markdown may not live under `pages/`.
152
154
 
153
155
  **3. Find the foundation by the wiring.** `"docs-src": "file:../src"` in the site's `package.json` → `docs/src/`.
154
156
 
@@ -183,7 +185,7 @@ On a content task and tempted to open the foundation: stop — usually a param a
183
185
  **7. Work in the lane, and check as you go.**
184
186
 
185
187
  ```bash
186
- uniweb inspect pages/home/hero.md # from the site dir: the parsed shape (--full, --sequence, --raw; a folder = the page)
188
+ uniweb inspect pages/home/hero.md # from the site dir: the parsed shape (--full, --sequence, --raw; a directory = the page)
187
189
  uniweb doctor # project configuration (--fix repairs)
188
190
  uniweb validate # records against declared schemas
189
191
  uniweb <command> --help # exact flags, no side effects
@@ -202,7 +204,7 @@ uniweb <command> --help # exact flags, no side effects
202
204
  | Pages missing from the nav | a strict `pages:` list — add `...` |
203
205
  | A color is empty | unquoted `#` in YAML |
204
206
  | Literal `{name}` on the page | no Loom content handler |
205
- | A class works in the foundation's build, not in the site's or `uniweb dev` | `styles.css` lists folders and not this one — `uniweb doctor` names it; `source("./")` on the Tailwind import reads them all |
207
+ | A class works in the foundation's build, not in the site's or `uniweb dev` | `styles.css` lists directories and not this one — `uniweb doctor` names it; `source("./")` on the Tailwind import reads them all |
206
208
  | Sticky header scrolls away | `sticky` class instead of `sticky: true` in `meta.js` |
207
209
  | Modal under the header | z-index instead of `<Overlay>` |
208
210
  | Entrance animation never plays | JS-started; write it in CSS; `uniweb dev` doesn't prerender |
@@ -250,17 +252,17 @@ content = { title, pretitle, subtitle, paragraphs, links, images, icons, videos,
250
252
 
251
253
  **Backgrounds and theme are frontmatter.** `background:` takes an image, video, gradient, quoted color or palette token, or an object (`image`, `video`, `overlay`); `theme: light | medium | dark`, or a map with token overrides (`section: neutral-100`).
252
254
 
253
- **Pages.** `pages/<name>/` → `/<name>`; a name or `slug:` holding `?`, `#` or `%` stops the build. `page.yml`: `title`, `description`, `id`, `order`, `sections: [a, b, ...]`, `pages: [...]`, `nest`, `redirect`, `slug: { fr: … }`, `hidden` (draft; takes the pages below it), `hideIn` (nav only), `knowledge` (agent-only, never rendered — not a security control), `query` / `fetch`, `seo`, `layout`. `folder.yml` for a folder *of pages*. Numeric prefixes (a number then a dash) order sections, pages and page folders and never reach a URL: `2-about/` is `/about`, and `pages:`/`index:` name it `about`; `2.5-x.md` slots between; `3d-printing` has no number. Config cascades `page.yml → folder.yml → site.yml → foundation`. `layout/header.md`, `footer.md` render on every page — a markdown list is the nav, a standalone link the CTA, `yaml:nav` for richer menus. Child sections: `@child.md` + `nest: { parent: [child] }`.
255
+ **Pages.** `pages/<name>/` → `/<name>`; a name or `slug:` holding `?`, `#` or `%` stops the build. `page.yml`: `title`, `description`, `id`, `order`, `sections: [a, b, ...]`, `pages: [...]`, `nest`, `redirect`, `slug: { fr: … }`, `hidden` (draft; takes the pages below it), `hideIn` (nav only), `knowledge` (agent-only, never rendered — not a security control), `query` / `fetch`, `seo`, `layout`. `folder.yml` for a directory *of pages*. Numeric prefixes (a number then a dash) order section files, page files and page directories and never reach a URL: `2-about/` is `/about`, and `pages:`/`index:` name it `about`; `2.5-x.md` slots between; `3d-printing` has no number. Config cascades `page.yml → folder.yml → site.yml → foundation`. `layout/header.md`, `footer.md` render on every page — a markdown list is the nav, a standalone link the CTA, `yaml:nav` for richer menus. Child sections: `@child.md` + `nest: { parent: [child] }`.
254
256
 
255
257
  **`site.yml`.** `index`, `pages`, `foundation`, `extensions`, `paths`, `placeholders`, `languages`, `services`, `agents`, `seo` (`origin`: scheme + host, `image`: 1200×630), `favicon`, `touchIcon`. Everything in `site.yml` and `queries.yml` ships to the browser — **never a secret**.
256
258
 
257
- **Records — run `uniweb guide data` before touching them.** `records/<schema>/<name>.md|yml|json|bib` (`records/article/` → `@/article`); `queries.yml` names → `{ schema, where, sort, limit, scope }`; a page or section shows one with `query: name` or `fetch: { query, … }` (narrows, never widens); a `[slug]/` folder inside the query's page gives each record a page.
259
+ **Records — run `uniweb guide data` before touching them.** `records/<schema>/<name>.md|yml|json|bib` (`records/article/` → `@/article`); `queries.yml` names → `{ schema, where, sort, limit, scope }`; a page or section shows one with `query: name` or `fetch: { query, … }` (narrows, never widens); a `[slug]/` directory inside the query's page gives each record a page.
258
260
 
259
261
  ### Foundation
260
262
 
261
263
  ```
262
264
  src/
263
- ├── sections/ # section types — PascalCase file or folder at the root; a folder when it needs meta.js
265
+ ├── sections/ # section types — PascalCase file or directory at the root; a directory when it needs meta.js
264
266
  ├── layouts/ # custom layouts, auto-discovered
265
267
  ├── components/ # ordinary React — any props, any library, no meta.js, invisible to authors
266
268
  ├── utils/
@@ -326,7 +328,7 @@ Every guide ships with the CLI this project pins, so it describes the version in
326
328
  | start a project, grow the workspace, learn from a template | `uniweb guide start` |
327
329
  | work with records, queries, `[slug]` pages, external APIs, schemas, Loom | `uniweb guide data` |
328
330
  | add search, forms, tracking, Google Analytics or Tag Manager, an assistant | `uniweb guide services` |
329
- | the site has accounts or member data (`services.backend`, `@uniweb/api`) | `uniweb guide backend` |
331
+ | the site has accounts or member data (`services.backend`, `blueprint.yml`, `@uniweb/api`) | `uniweb guide backend` |
330
332
  | add a language | `uniweb guide i18n` |
331
333
  | publish, deploy, push/pull, register, CI, workspaces, updates | `uniweb guide ship` |
332
334
  | port a React / Next / generated design | `uniweb guide migrate` |
@@ -58,7 +58,7 @@ await writer.update(item.id, { ...item.data, bio: 'Bonjour' }, { language: 'fr'
58
58
 
59
59
  Gate controls on what the viewer may do — a record's `can_edit` from a single-entity read — but never rely on that for safety: a foundation runs with the viewer's authority, so hiding a button hides a button. Not on `viewer.roles` alone: a session holds its roles as a reader's until elevated, so a gate on `system_admin` shows the operator nothing until then. Draw a role-acting control from `useElevation().rolesInFull` and let the record answer.
60
60
 
61
- What protects content is the **entry**: a member writes their own entries and not another's, enforced by the store. **Models are open** — anyone signed in may create entries of any Model. A schema protects how an item changes and who reads an entry:
61
+ What protects content is the **entry**: a member writes their own entries and not another's, enforced by the store. **Every type starts closed**: the operator adds its entries, and anyone else only where the site's `blueprint.yml` opens it (below). A schema protects how an item changes and who reads an entry:
62
62
 
63
63
  ```yaml
64
64
  # schemas/attendance.yml
@@ -81,6 +81,29 @@ fields:
81
81
 
82
82
  `readable_with` (`read` | `edit` | `admin`, only on a reference) is one step; a backend refuses adding it to a field entries already fill. `grantable: false` keeps entries from being shared with a person or team. `sold_with` only on a reference; an unmarked one carries nothing. `visitor_fills: true` marks a field a site's visitor may fill, and a type with one takes visitors' submissions, confirmed by email. Mark it per field, on a top-level section's fields only. The build refuses it on files, on a reference with `readable_with`/`sold_with`, and in a section that leaves a `required` field unmarked.
83
83
 
84
+ ## Who adds and reads each type: `blueprint.yml`
85
+
86
+ Beside `site.yml`, in a site whose `services` names `backend`: how a backend started from the site begins.
87
+
88
+ ```yaml
89
+ signup: invite_only # or open, the default: who may create an account
90
+ teams: # founded empty; people join them in the backend's administration
91
+ sales: { label: Sales }
92
+ access:
93
+ '@/vehicle':
94
+ add: [sales] # who adds entries: open (every signed-in account) · [teams] · [] (the operator alone)
95
+ all: { sales: edit } # every entry of the type, not only one's own: <team> or members → read | edit
96
+ '@/request': { add: open } # each member keeps their own
97
+ publicQueries: # what visitors who aren't signed in may read
98
+ '@/vehicle': { whole: true, where: { status: { in: [available, pending] } } } # whole is required; false = briefs
99
+ ```
100
+
101
+ - **Applied once**, when a backend is started from the site: its own, a clone's of a template, or one started again after it was destroyed. Then the operator changes these in the backend's administration. An edited file is pushed and pulled with the site, and reaches no backend already running.
102
+ - A type not listed stays closed. Name types as `queries.yml` does: `@/vehicle` for the foundation's own, sent in its scope.
103
+ - A build, a push and `uniweb doctor` refuse a malformed file, naming the key; a push refuses whole. A type none of the site's foundations declares only warns: a backend started from the site leaves that line out, and the publish says so. `where`, `sort` and `limit` are the backend's to judge, and one it refuses is left out the same way.
104
+ - A team's `all: edit` reaches the entries once the member confirms it is them (below); a team's `add` and `members: edit` need no confirming. Who is in a team, and roles, are never the file's.
105
+ - A static build carries none of it. A pull writes it back here, never into `site.yml`.
106
+
84
107
  ## Acting as an administrator
85
108
 
86
109
  An administrator's session reads what their role reaches and changes nothing through the role until they confirm it is them; their own records they edit as always.
@@ -152,8 +175,11 @@ $devBackend: ./mock/api.js # what answers in `uniweb dev`; `$` keys are never
152
175
 
153
176
  ```js
154
177
  // site/mock/api.js
178
+ import { fileURLToPath } from 'node:url'
155
179
  import { createMockBackend } from '@uniweb/api/mock'
156
- export default createMockBackend({ seed }).fetch
180
+ import { readBlueprint } from '@uniweb/build/blueprint'
181
+ const blueprint = readBlueprint(fileURLToPath(new URL('..', import.meta.url))) // the site's blueprint.yml
182
+ export default createMockBackend({ seed, blueprint }).fetch
157
183
  ```
158
184
 
159
- `uniweb dev` answers the `backend` service with it at an address on its own origin (cookies behave as in production). Write no address of your own: under `services:` an address means a backend you run. The mock **enforces** entry ownership and `append_only`; it doesn't model `readable_with`, `sold_with`, second factors or password rules. Mail it would send prints in the terminal with its link on the site's root. Seed `offers: [{ email, invitations: 1 }]` to try an invitation; a seeded entity takes `grants: { member: 'read' }`; `units: [{ handle, parent?, members, floor? }]` gives a create somewhere to land. The seed names your own types `@/track`. State is in memory; restart to reset. `uniweb create my-event --template conference` is a worked example.
185
+ `uniweb dev` answers the `backend` service with it at an address on its own origin (cookies behave as in production). Write no address of your own: under `services:` an address means a backend you run. The mock begins as a backend started from the site does: every type closed until the blueprint opens it, its `signup`, its teams (a seeded account names its own, `teams: ['sales']`). It **enforces** those, entry ownership and `append_only`; it doesn't model public queries, `readable_with`, `sold_with`, second factors or password rules. Mail it would send prints in the terminal with its link on the site's root. Seed `offers: [{ email, invitations: 1 }]` to try an invitation; a seeded entity takes `grants: { member: 'read' }`; `units: [{ handle, parent?, members, floor? }]` gives a create somewhere to land. The seed names your own types `@/track`. State is in memory; restart to reset. `uniweb create my-event --template conference` is a worked example.
@@ -4,7 +4,7 @@ Lane guide — AGENTS.md procedure step 6 loads it before any content is written
4
4
 
5
5
  ## Sections
6
6
 
7
- **A section with no `type:` renders through the foundation's default section type** — the `defaultSection` its `main.js` sets, else a section type named `Section` where the foundation has one, the fallback for foundations that declare none. This is what lets a folder of plain markdown with no frontmatter become pages: mounted documentation, an imported wiki. If such content shows "Component not found", the foundation has neither: declare `defaultSection` in its `main.js`, naming the type that content should render with. `uniweb doctor` states each foundation's default, and suggests one where a type stands out.
7
+ **A section with no `type:` renders through the foundation's default section type** — the `defaultSection` its `main.js` sets, else a section type named `Section` where the foundation has one, the fallback for foundations that declare none. This is what lets a directory of plain markdown with no frontmatter become pages: mounted documentation, an imported wiki. If such content shows "Component not found", the foundation has neither: declare `defaultSection` in its `main.js`, naming the type that content should render with. `uniweb doctor` states each foundation's default, and suggests one where a type stands out.
8
8
 
9
9
  **Content before the first heading changes the parse:** headings after body content become items, not the section title. That's how repeating groups are made. An icon counts: `![](lu-globe)` above `# Title` leaves `content.title` empty and puts the heading in `items[0]`. For an icon that belongs to the title, write it under the heading, where it is still `content.icons[0]`; `uniweb inspect` shows the shape, and warns about an icon above one heading. An image above the title empties it too, with the heading in `content.headings` and no warning.
10
10
 
@@ -131,7 +131,7 @@ Image attributes: `{width=800 height=600 loading=lazy fit=cover position=center
131
131
 
132
132
  **Section links:** `page:about#team` → `/about#section-team`; `page:/#features` → a homepage section. The id is the file name without its number (`2-features.md` → `features`) or `id:` in frontmatter.
133
133
 
134
- **Where media lives.** `./x` is beside the page, `/x` is in `public/`; both reach a static build and a published site. Keep a page's media beside it, and in `public/` what belongs to the whole site: the favicon, fonts. **Only a static host gives a file a fixed address** at the site root. A site published with Uniweb serves a file that something names from an address the upload gives it, and nothing at `/x` — so for a file other sites or scripts fetch by URL, keep it somewhere with its own address and add a page whose `redirect:` goes there. A static build copies `public/` whole and adds its own copy of each file a page names there. `uniweb push` uploads a file beside a page wherever the page is (mounted folders included); a file outside the site and its mounts is not uploaded — put that in `public/`. There is no `assets/` folder for media; a build stops on a `/x` only `assets/` holds.
134
+ **Where media lives.** `./x` is beside the page, `/x` is in `public/`; both reach a static build and a published site. Keep a page's media beside it, and in `public/` what belongs to the whole site: the favicon, fonts. **Only a static host gives a file a fixed address** at the site root. A site published with Uniweb serves a file that something names from an address the upload gives it, and nothing at `/x` — so for a file other sites or scripts fetch by URL, keep it somewhere with its own address and add a page whose `redirect:` goes there. A static build copies `public/` whole and adds its own copy of each file a page names there. `uniweb push` uploads a file beside a page wherever the page is (mounted directories included); a file outside the site and its mounts is not uploaded — put that in `public/`. There is no `assets/` directory for media; a build stops on a `/x` only `assets/` holds.
135
135
 
136
136
  **Placement** (`{placement=left|right|wide|full}`) on an image or video, or on a table's caption line, which follows the table after a blank line (`: Plans and prices {placement=wide #tbl-plans}`, which also sets caption and id; with no blank line it becomes a row). It's the author's intent, honoured by kit's `<Render>`, `<Prose>` and `<Article>` and ignored by other components; a section type declares which it honours in `meta.js` (`sequence: { placement: true }`) and the build warns on a mismatch.
137
137
 
@@ -217,7 +217,7 @@ site/pages/home/
217
217
  └── 2-features.md
218
218
  ```
219
219
 
220
- Decimals insert between (`2.5-x.md`). A page folder's number works the same way: `pages/2-about/` orders second and is `/about`, named `about` in `pages:` and `index:`. A number counts only with a dash after it, or as the whole name (`404`): `3d-printing.md` keeps its name. Ignored: `README.md`, `_*.md`, `_*/`.
220
+ Decimals insert between (`2.5-x.md`). A page directory's number works the same way: `pages/2-about/` orders second and is `/about`, named `about` in `pages:` and `index:`. A number counts only with a dash after it, or as the whole name (`404`): `3d-printing.md` keeps its name. Ignored: `README.md`, `_*.md`, `_*/`.
221
221
 
222
222
  ```yaml
223
223
  # page.yml
@@ -225,12 +225,12 @@ title: About Us
225
225
  id: about # stable identity for page: links; the app may write a code (id: 3f58142d) — keep it
226
226
  order: 2
227
227
  sections: [hero, team, ...]
228
- pages: [team, history, ...] # child page order when this page has child folders
228
+ pages: [team, history, ...] # child page order when this page has child pages
229
229
  redirect: academic # to a child page (relative/absolute path, or URL)
230
230
  slug: { fr: a-propos } # localized URL segment per language
231
231
  layout: marketing
232
232
 
233
- # folder.yml — a folder OF PAGES (page.yml means a page built from sections)
233
+ # folder.yml — a directory OF PAGES (page.yml means a page built from sections)
234
234
  title: Getting Started
235
235
  pages: [quickstart, app-tour, ...]
236
236
 
@@ -245,13 +245,13 @@ extensions: ['@acme/fx@0.3.1']
245
245
 
246
246
  **Cascade:** `page.yml → folder.yml → site.yml → foundation defaults`. Put `layout: marketing` in a `folder.yml` and every page inherits it; one page can still override.
247
247
 
248
- **A folder of pages holds pages of one section.** Under a `folder.yml`, each page is one `.md` file of one section, and each subfolder is a folder of pages too. The build stops on a subfolder with a `page.yml` of its own, a parametric `[slug]/` included. A page of several sections goes outside the folder. In the app, such a page takes no second section, and a pull holds one made there.
248
+ **A directory of pages holds pages of one section.** Under a `folder.yml`, each page is one `.md` file of one section, and each subdirectory is a directory of pages too. The build stops on a subdirectory with a `page.yml` of its own, a parametric `[slug]/` included. A page of several sections goes outside that directory. In the app, such a page takes no second section, and a pull holds one made there.
249
249
 
250
250
  **Such a page's frontmatter holds its page's settings**, beside its section's `type:` and params: `title` (else its H1), `description`, `label`, `keywords`, `slug`, `hideIn`, `layout`, `seo`, `knowledge`, `trackSections`, as in a `page.yml`. A section param with one of those names goes under `props:` (`props: { label: … }`); the build warns where the section type declares one. `id:` is the section's id there too, and `hidden:` drafts the page. A pull writes the app's changes to them back into the file.
251
251
 
252
- **Routes:** folders map 1:1 to routes; `pages:` controls order only. The site root is the exception: the first of `pages:` sets `/`, else `index:`, declared in `site.yml` or in the pages directory's own `folder.yml`/`page.yml`, with `site.yml` winning. A folder with `page.yml` but no markdown is a structural group (`hasContent: false`); visiting it redirects to the first descendant with content.
252
+ **Routes:** pages map 1:1 to routes, and under `pages/` every directory is a page; `pages:` controls order only. The site root is the exception: the first of `pages:` sets `/`, else `index:`, declared in `site.yml` or in the pages directory's own `folder.yml`/`page.yml`, with `site.yml` winning. A directory with `page.yml` but no markdown is a page with no sections (`hasContent: false`); visiting it redirects to the first descendant with content.
253
253
 
254
- **Mounted folders:** a local folder for a mounted route says how *this site* presents it. Keep `layout:`, `title:` and SEO in a `folder.yml` there; the mounted repo's own `folder.yml` supplies ordering and title where the stub is silent. A `page.yml` with markdown of its own makes a real page above the mounted pages — a landing page for the branch. A mount is one level under `pages/`, and a subfolder in the local folder isn't read, since the branch's pages come from the mount; the build says so. What a site can't do from outside a repo it mounts: leave a file out, title or order a nested folder, or use a `README.md` as a page — those are the mounted repo's to do. A relative link to a markdown file (`./deploying.md#setup`), which is how docs in a repo link to each other, leads to the page that file became; the build names one that leads nowhere. A mount that is its own repository (a submodule, or a clone beside the site) takes its edits as commits there, and `uniweb refresh` takes its latest; a push or publish stops on one that is behind its remote or holds uncommitted changes, and `--mounts-as-is` sends it as it is. A pull writes an author's app edits into a mounted folder where the site's own repository holds it, or a submodule of it does (a commit there, to push before the site's repository). A folder it cannot merge into — a clone beside the site — keeps its text and the app keeps the author's: the pull and `status` name each such page as held, and a push leaves it alone while its file is unchanged. A mount is its folder, `pages/docs: ../docs`; the object form is refused.
254
+ **Mounted directories:** a local directory for a mounted route says how *this site* presents it. Keep `layout:`, `title:` and SEO in a `folder.yml` there; the mounted repo's own `folder.yml` supplies ordering and title where the stub is silent. A `page.yml` with markdown of its own makes a real page above the mounted pages — a landing page for the branch. A mount is one level under `pages/`, and a subdirectory in the local directory isn't read, since the branch's pages come from the mount; the build says so. What a site can't do from outside a repo it mounts: leave a file out, title or order a nested directory, or use a `README.md` as a page — those are the mounted repo's to do. A relative link to a markdown file (`./deploying.md#setup`), which is how docs in a repo link to each other, leads to the page that file became; the build names one that leads nowhere. A mount that is its own repository (a submodule, or a clone beside the site) takes its edits as commits there, and `uniweb refresh` takes its latest; a push or publish stops on one that is behind its remote or holds uncommitted changes, and `--mounts-as-is` sends it as it is. A pull writes an author's app edits into a mounted directory where the site's own repository holds it, or a submodule of it does (a commit there, to push before the site's repository). A directory it cannot merge into — a clone beside the site — keeps its text and the app keeps the author's: the pull and `status` name each such page as held, and a push leaves it alone while its file is unchanged. A mount is its directory, `pages/docs: ../docs`; the object form is refused.
255
255
 
256
256
  **Visibility flags:** `hidden: true` is a draft (not published; `uniweb dev` previews it; on a page it takes the pages below with it; on a section it's also kept from the component's params and takes its children with it); `hideIn: ['*']` or `[header]` controls nav placement only; `knowledge: true` is a different audience (below). An authored `pages/404/` needs no flag — `hidden: true` there makes it a draft and the site falls back to the generic 404.
257
257
 
@@ -274,11 +274,11 @@ seo:
274
274
 
275
275
  **Where the site lives:** every absolute URL (canonical, `og:url`, sitemap, `llms.txt` links) is built on the site's origin plus base path. The GitHub Pages workflow asks GitHub; Netlify and Vercel state their URL; on any other static host set `seo.origin`. With no address, pages state no canonical and no `sitemap.xml` is written — `uniweb doctor` says so.
276
276
 
277
- **Localized URLs:** on a multilingual site, `slug: { <lang>: <segment> }` gives a native segment per language; the folder name stays canonical. See the `i18n` guide.
277
+ **Localized URLs:** on a multilingual site, `slug: { <lang>: <segment> }` gives a native segment per language; the directory name stays canonical. See the `i18n` guide.
278
278
 
279
279
  ### Older versions of docs
280
280
 
281
- Most docs need one version. When a release is about to stop being the latest and its readers need its docs kept, run `uniweb add version v2` (`--in <folder>`, `--label "2.x"`). It copies the docs to a folder named `v2` beside them, at `/docs/v2/…`, with the copy's links leading into the copy, no page ids in it, and search engines told to leave it out. Keep writing where you were: the pages beside version folders are the latest, and their URLs never change. **Don't copy a version folder by hand.** A foundation draws versions with kit's `useVersion` (foundation guide). Reference: `reference/versioning.md`.
281
+ Most docs need one version. When a release is about to stop being the latest and its readers need its docs kept, run `uniweb add version v2` (`--in <folder>`, `--label "2.x"`). It copies the docs to a directory named `v2` beside them, at `/docs/v2/…`, with the copy's links leading into the copy, no page ids in it, and search engines told to leave it out. Keep writing where you were: the pages beside version directories are the latest, and their URLs never change. **Don't copy a version directory by hand.** A foundation draws versions with kit's `useVersion` (foundation guide). Reference: `reference/versioning.md`.
282
282
 
283
283
  ### Knowledge pages
284
284
 
@@ -288,7 +288,7 @@ Who can read it depends on the host: `uniweb publish` (backend-hosted) carries i
288
288
 
289
289
  ### Agent-readable output
290
290
 
291
- A static build emits `/llms.txt` (an annotated index of every page) and `/{route}.md` (each page as clean markdown); a host that serves the site derives its own. Descriptions come from `page.yml description:`, then `seo.ogDescription`, then the opening paragraph. A top-level folder with no page of its own and ≥5 pages gets `/docs/llms.txt`; each language gets its own (`/fr/llms.txt`, `/fr/search-index.json`). Excluded deliberately: `seo.noindex`, `hidden`, `_`-prefixed, and a parametric page's URL pattern; `noindex`/`hidden` on a folder with no page of its own takes the branch.
291
+ A static build emits `/llms.txt` (an annotated index of every page) and `/{route}.md` (each page as clean markdown, and, where the build prerenders it, the records each section shows, as JSON after that section); a host that serves the site derives its own. Descriptions come from `page.yml description:`, then `seo.ogDescription`, then the opening paragraph. A top-level directory with no content of its own and ≥5 pages gets `/docs/llms.txt`; each language gets its own (`/fr/llms.txt`, `/fr/search-index.json`). Excluded deliberately: `seo.noindex`, `hidden`, `_`-prefixed, and a parametric page's URL pattern; `noindex`/`hidden` on a directory with no content of its own takes the branch.
292
292
 
293
293
  ```yaml
294
294
  agents:
@@ -9,8 +9,8 @@ A small database, not a page tree. Three things, deliberately separate:
9
9
  ```
10
10
  site/
11
11
  ├── pages/
12
- ├── records/ # the site's records — every file in a schema folder is one
13
- │ ├── article/ # folder names the data schema
12
+ ├── records/ # the site's records — every file in a schema directory is one
13
+ │ ├── article/ # directory names the data schema
14
14
  │ ├── person/
15
15
  │ └── folder.yml # optional: sorts records into folders
16
16
  ├── queries.yml # how content is REACHED
@@ -23,9 +23,9 @@ site/
23
23
  | `records/std/person/…` | `@std/person` — the shared standard set |
24
24
  | `records/acme/project/…` | `@acme/project` — an org's |
25
25
 
26
- Keep folders flat — `records/article/2025/x.md` reads as the `2025` schema of an `article` org. A `_`-prefixed file is not a record.
26
+ Keep directories flat — `records/article/2025/x.md` reads as the `2025` schema of an `article` org. A `_`-prefixed file is not a record.
27
27
 
28
- **Formats:** `.md` (frontmatter fields, body prose; auto-excerpt and first-image extraction), `.yml`/`.yaml` and `.json` (structured, no body), `.bib` (each `@entry{key, …}` is a record named by its cite key, normalized to CSL-JSON, LaTeX accents → Unicode). Mix freely in one folder. **One record per file**; the file name is `$name`, the one name it carries on every site (no `slug` field). Conventional fields: `title`, `date`, `tags`, `image`, `description`, `author`, plus whatever the content needs. Images sit beside the file (`./`). `draft: true` keeps a record off the live site: still a record, previewed by `pnpm dev`, excluded from a hosting build, kept undelivered on a backend.
28
+ **Formats:** `.md` (frontmatter fields, body prose; auto-excerpt and first-image extraction), `.yml`/`.yaml` and `.json` (structured, no body), `.bib` (each `@entry{key, …}` is a record named by its cite key, normalized to CSL-JSON, LaTeX accents → Unicode). Mix freely in one directory. **One record per file**; the file name is `$name`, the one name it carries on every site (no `slug` field). Conventional fields: `title`, `date`, `tags`, `image`, `description`, `author`, plus whatever the content needs. Images sit beside the file (`./`). `draft: true` keeps a record off the live site: still a record, previewed by `pnpm dev`, excluded from a production build, kept undelivered on a backend.
29
29
 
30
30
  **Links and files are records too.** `records/uniweb/link/x.yml` holding only `url:` (absolute) is a `@uniweb/link`; any file in `records/uniweb/file/` is a `@uniweb/file` named by its file name. Label and tags go on their `records/folder.yml` entry. Declare `data: { videos: '@uniweb/link' }` → `{ url, $name, $label, $tags }`; `data: { downloads: '@uniweb/file' }` → `{ file: { url, name, mime, size }, $name, $label, $tags }`. Two files of one name with different extensions clash. On a backend a component must declare the type for a query over it to be accepted.
31
31
 
@@ -53,7 +53,7 @@ The body — `body.content`.
53
53
 
54
54
  Paths are relative to `records/`, one file or a glob. An entry can be `{ path, tags, label }` — delivered beside the record as `$tags` (in order) and `$label` (one text or `{ en, fr }`, resolved to the page's language); a query reads them like any key (`where: { $tags: featured }`). `scope: archive` reads the folder and everything inside. A record sits in one folder; a computed subset is a query. The build refuses a top-level bare path (every file is a record already).
55
55
 
56
- **With a backend, `records/` is what `uniweb push` sends.** No `records/` leaves the backend alone; an *empty* `records/` takes them out of the site's folder (the CLI asks). Records with a data schema reach published pages only when `services.records: true`; once the site has been published, a push changes its records on the live site with no republish (pages wait for `uniweb publish`). To move records to another schema, move their files into its folder, renamed or not, and keep each file's `$uuid` line: the push sends each as a new record in the place the old one had. A record taken out of the folder stays on the backend, and the push that took it out offers to delete it (`--yes` deletes without asking).
56
+ **With a backend, `records/` is what `uniweb push` sends.** No `records/` leaves the backend alone; an *empty* `records/` takes them out of the site's folder (the CLI asks). Records with a data schema reach published pages only when `services.records: true`; once the site has been published, a push changes its records on the live site with no republish (pages wait for `uniweb publish`). To move records to another schema, move their files into its directory, renamed or not, and keep each file's `$uuid` line: the push sends each as a new record in the place the old one had. A record taken out of the folder stays on the backend, and the push that took it out offers to delete it (`--yes` deletes without asking).
57
57
 
58
58
  ## Queries
59
59
 
@@ -83,7 +83,7 @@ query: recent | type: ArticleTeaser
83
83
 
84
84
  ### Parametric pages
85
85
 
86
- A `[slug]/` folder inside the page that names the query gives each record its own page:
86
+ A `[slug]/` directory inside the page that names the query gives each record its own page:
87
87
 
88
88
  ```
89
89
  pages/blog/
@@ -98,7 +98,7 @@ pages/blog/
98
98
 
99
99
  **Link with `item.$route`, never a composed URL.** Every record a query delivers carries `$route` (the URL of the parametric page whose route query is that query), wherever the list appears. No page or no value → no `$route`, never a broken one. `detailPage: page:<id>` on a fetch links to another page instead. `$` marks framework-filled fields; a record's own `route` is untouched.
100
100
 
101
- **The route query** — which query the URL narrows: the `[slug]` page's own `query:`, else its parent's, else `site.yml`'s (top-level `pages/[slug]/` only); if none, the query its sections all declare. The folder name says what the segment matches: `[slug]` the record's name (`$name`) — or the field the route query binds `:slug` to (`where: { slug: :slug }`, how an external API's records get pages); `[uuid]` its `$uuid`; any other `[name]` the record's field of that name (several values → any member matches; non-unique → the build warns). A folder inside `[slug]/` (`[slug]/cv/`) is a parametric page about the same record.
101
+ **The route query** — which query the URL narrows: the `[slug]` page's own `query:`, else its parent's, else `site.yml`'s (top-level `pages/[slug]/` only); if none, the query its sections all declare. The directory name says what the segment matches: `[slug]` the record's name (`$name`) — or the field the route query binds `:slug` to (`where: { slug: :slug }`, how an external API's records get pages); `[uuid]` its `$uuid`; any other `[name]` the record's field of that name (several values → any member matches; non-unique → the build warns). A directory inside `[slug]/` (`[slug]/cv/`) is a parametric page about the same record.
102
102
 
103
103
  **`current:`** on a section's own `fetch:` chooses how it uses the page's record: `only` (default — the record), `exclude` (the others, "related"), `include` (all, a pager). `fetch: { query: articles, as: related, current: exclude, limit: 3 }`. It follows the query, not the key: a fetch of the route query gets the record unless it says otherwise; a fetch of another query reads `current:` only when written.
104
104
 
@@ -134,9 +134,9 @@ data: {
134
134
  }
135
135
  ```
136
136
 
137
- `single`/`whole` are refused over a schema whose root is a list (`@std/nav`, `@std/form`). A `whole` key its source cannot answer whole is `null`. An optional `schemas.config.js` routes a scope to a folder: `export default { '@acme': '../shared/acme-schemas' }` — a routed scope wins, has no package fallback, and `@/`/`@uniweb` are never routable. Worked examples: `development/schemas-in-practice.md`.
137
+ `single`/`whole` are refused over a schema whose root is a list (`@std/nav`, `@std/form`). A `whole` key its source cannot answer whole is `null`. An optional `schemas.config.js` routes a scope to a directory: `export default { '@acme': '../shared/acme-schemas' }` — a routed scope wins, has no package fallback, and `@/`/`@uniweb` are never routable. Worked examples: `development/schemas-in-practice.md`.
138
138
 
139
- **Any foundation can use a data schema another defines, by its full name** — `data: { members: '@acme/member' }`, `schema: '@acme/member'` in `queries.yml`. No backend is involved, and in a workspace nothing to configure: a local build, `uniweb dev` included, reads the type from the foundation whose name gives the `@acme` scope and whose own `schemas/` defines it. Two packages of the workspace defining it stop the build, naming both. A type outside the workspace comes from `schemas.config.js` (`'@acme/member': '../elsewhere/member.yml'`, or the scope's folder), which wins over the workspace, or an installed `@acme/schemas` package. A scope is a namespace that keeps names from colliding, not a limit on who uses a type. So a type another foundation defines is named, never copied: a copy of its file is a second definition of the same type, which `doctor` points out where the two foundations' names give one scope (`type-defined-twice`). Registering, which only a site with a backend does, names such a type and sends no definition of it. A push also needs one of the site's foundations to declare the type, as a section type's data key or a schema of its own: the backend refuses a query whose type none of them declares, since nothing there would render it. A site can hold another site's records of a type too: `paths: { 'records/acme/member': '../../hub/site/records/acme/member' }` in its `site.yml` reads them as its own, a push adds them by reference rather than as copies once their own site has pushed them, and a pull leaves those files alone. A site's records of it sit in `records/acme/member/`; in `records/member/` they'd be the foundation's own `@/member`.
139
+ **Any foundation can use a data schema another defines, by its full name** — `data: { members: '@acme/member' }`, `schema: '@acme/member'` in `queries.yml`. No backend is involved, and in a workspace nothing to configure: a local build, `uniweb dev` included, reads the type from the foundation whose name gives the `@acme` scope and whose own `schemas/` defines it. Two packages of the workspace defining it stop the build, naming both. A type outside the workspace comes from `schemas.config.js` (`'@acme/member': '../elsewhere/member.yml'`, or the scope's directory), which wins over the workspace, or an installed `@acme/schemas` package. A scope is a namespace that keeps names from colliding, not a limit on who uses a type. So a type another foundation defines is named, never copied: a copy of its file is a second definition of the same type, which `doctor` points out where the two foundations' names give one scope (`type-defined-twice`). Registering, which only a site with a backend does, names such a type and sends no definition of it. A push also needs one of the site's foundations to declare the type, as a section type's data key or a schema of its own: the backend refuses a query whose type none of them declares, since nothing there would render it. A site can hold another site's records of a type too: `paths: { 'records/acme/member': '../../hub/site/records/acme/member' }` in its `site.yml` reads them as its own, a push adds them by reference rather than as copies once their own site has pushed them, and a pull leaves those files alone. A site's records of it sit in `records/acme/member/`; in `records/member/` they'd be the foundation's own `@/member`.
140
140
 
141
141
  ```jsx
142
142
  function Article({ content, block }) { // data: { article: { schema: '@std/article', single: true } }
@@ -166,7 +166,7 @@ posts:
166
166
  url: https://api.example.com/posts/{id}
167
167
  ```
168
168
 
169
- Also `method: POST` + `body`, `where`/`sort`/`limit` (over what arrived, after `transform`), `queryable`. Its records have no `$name`, so a `[slug]` page over it binds the URL field in the query's own `where` (`where: { slug: :slug }`). `record:` takes `url`, `method`, `body`, `transform` (`url`/`method` default to the query's; a placeholder named by the folder — `{id}` for `[id]` — is the segment). `schema`, `scope`, `deferred`, `excerpt`, `path` are refused beside `url:`. The visitor's browser fetches it (a `fetch:` with `prerender: true` makes the build fetch instead); it compiles no `/data` file. A site's own schema records are another matter: on a published site they need `services.records: true`.
169
+ Also `method: POST` + `body`, `where`/`sort`/`limit` (over what arrived, after `transform`), `queryable`. Its records have no `$name`, so a `[slug]` page over it binds the URL field in the query's own `where` (`where: { slug: :slug }`). `record:` takes `url`, `method`, `body`, `transform` (`url`/`method` default to the query's; a placeholder named by the directory — `{id}` for `[id]` — is the segment). `schema`, `scope`, `deferred`, `excerpt`, `path` are refused beside `url:`. The visitor's browser fetches it (a `fetch:` with `prerender: true` makes the build fetch instead); it compiles no `/data` file. A site's own schema records are another matter: on a published site they need `services.records: true`.
170
170
 
171
171
  A backend needing a key, headers, paging or its own wire language is a **transport** — a named `{ resolve, cacheKey? }` exported by the foundation (or an extension), selected by the site per data key:
172
172
 
@@ -4,9 +4,9 @@ Lane guide — AGENTS.md procedure step 6 loads it before any foundation code is
4
4
 
5
5
  ## Discovery and entry
6
6
 
7
- PascalCase files and folders at the root of `sections/` are auto-discovered; nested levels need a `meta.js`; lowercase directories are organizational; `hidden: true` excludes a component entirely. Discovery accepts a `.js` component only without JSX — JSX compiles in `.jsx`/`.tsx` only, and the build stops on a `.js` file holding it.
7
+ PascalCase files and directories at the root of `sections/` are auto-discovered; nested levels need a `meta.js`; lowercase directories are organizational; `hidden: true` excludes a component entirely. Discovery accepts a `.js` component only without JSX — JSX compiles in `.jsx`/`.tsx` only, and the build stops on a `.js` file holding it.
8
8
 
9
- **Source root.** The `src/` folder *is* the foundation; the build reads `package.json::main` (`./_entry.generated.js` for new scaffolds). Older foundations nest source in `foundation/src/` with `main` pointing at `./src/_entry.generated.js`; both work.
9
+ **Source root.** The `src/` directory *is* the foundation; the build reads `package.json::main` (`./_entry.generated.js` for new scaffolds). Older foundations nest source in `foundation/src/` with `main` pointing at `./src/_entry.generated.js`; both work.
10
10
 
11
11
  **`main.js`.** One `export default { … }`: identity (`name`, `description`) and capabilities (`defaultLayout`, `defaultSection`, `viewTransitions`, `defaultInsets`, `xref`, `outputs`, `handlers`, `data`), plus an optional named `vars` export. Section types and layouts are merged in by `@uniweb/build`; you never write that wrapper. The build carries into `dist/entry.js` only what a published page reads — code it calls and lean data (`defaultLayout`, each var's `default`/`type`/`applyTo`, each `data:` key's schema ref); `name`, `description`, labels stay out and reach the editor via the schema. The file is plain JavaScript: a component it declares lives in a `.jsx` it imports. When you import your **own** `main.js` from a component (e.g. `compileDocument(website, { foundation })`), you get the bare default object — pass it through.
12
12
 
@@ -67,7 +67,7 @@ Skip it and prose is unstyled (lists lose bullets) while the markup looks right;
67
67
 
68
68
  Things you won't discover from exports:
69
69
 
70
- - **`<Link>` takes `to` or `href`.** `to="page:about"` resolves a page id (survives moves) or a route, never a folder: the homepage is `page:/`, or `page:home` only when its `page.yml` says `id: home`. External URLs get `target="_blank"`; `reload` forces a full load.
70
+ - **`<Link>` takes `to` or `href`.** `to="page:about"` resolves a page id (survives moves) or a route, never a directory's name: the homepage is `page:/`, or `page:home` only when its `page.yml` says `id: home`. External URLs get `target="_blank"`; `reload` forces a full load.
71
71
  - **A link back to a list is `<Link to="/store" back>`.** A link opens its page at the top, even the page the visitor just left, since the runtime restores a page's scroll only on back and forward. `back` steps back when the page before was that page (steps within this page don't count), so the list returns where they left it, and is an ordinary link otherwise. `useGoBack('/store')` does the same for a button. Keep the list's filter in `usePageState`, which stays with the page, so the view comes back too.
72
72
  - **A modal needs `<Overlay>`, not a bigger z-index.** Each layout area's wrapper has its own layer, which makes it a stacking context; a `fixed` dialog inside one paints at its area's place in the stack, under the header/footer. `<Overlay onClose={close}>` renders into `document.body`, contains focus (moves it in, cycles Tab, marks the rest `inert`, returns it), handles Escape, scrim click, scroll lock; a dimmed scrim you override with `className` (`bg-transparent` removes it). `modal={false}` for a toast. Your dialog markup stays yours.
73
73
  - **A reader can open a picture larger.** `components={{ image: EnlargeableImage }}` does it for an image in a page's body, and `Mermaid` does it on its own (`enlarge={false}` turns it off). `<Enlargeable>` goes around a picture a section draws itself. It's offered only when opening shows the picture noticeably larger, and the prerendered page doesn't change.
@@ -163,7 +163,7 @@ export default function Pricing({ content, params }) {
163
163
 
164
164
  ### Code several foundations share
165
165
 
166
- Code that more than one foundation of a workspace uses lives in a workspace package, not in copies: components are imported as from any package, and Vite bundles them into each foundation. Give the package a stylesheet that reads its own folder, as kit's does — `@source "./**/*.{js,jsx}";` in its `styles.css` — and import it in each foundation's `styles.css` (`@import "@acme/ui/styles.css";`), so Tailwind finds its classes wherever it is installed. A section type the package holds is still each foundation's to offer: a folder in the foundation's `sections/` whose `index.jsx` is `export { default } from '@acme/ui/sections/Banner/index.jsx'`, and whose `meta.js` re-exports the package's the same way. A fix in the package reaches every foundation at its next build and release.
166
+ Code that more than one foundation of a workspace uses lives in a workspace package, not in copies: components are imported as from any package, and Vite bundles them into each foundation. Give the package a stylesheet that reads its own directory, as kit's does — `@source "./**/*.{js,jsx}";` in its `styles.css` — and import it in each foundation's `styles.css` (`@import "@acme/ui/styles.css";`), so Tailwind finds its classes wherever it is installed. A section type the package holds is still each foundation's to offer: a directory in the foundation's `sections/` whose `index.jsx` is `export { default } from '@acme/ui/sections/Banner/index.jsx'`, and whose `meta.js` re-exports the package's the same way. A fix in the package reaches every foundation at its next build and release.
167
167
 
168
168
  ### The Front Desk pattern
169
169
 
@@ -303,9 +303,9 @@ export default function DocsLayout({ header, body, footer, left, right, params }
303
303
 
304
304
  Layouts are auto-discovered in `layouts/`. Set `defaultLayout` in `main.js` or name one `Default`; with neither, a page gets the built-in layout: header, page, footer and nothing else, so `layout/left.md` isn't drawn. A `defaultLayout` naming no layout stops the build. Layouts have their own `params` in `meta.js` (header height, sidebar width).
305
305
 
306
- **Layout `meta.js`:** `{ areas: ['header', 'footer', 'left'], scroll: 'self' }`. Area names are arbitrary; a page renders the areas its site's `layout/` folder fills. `scroll`: unset = runtime manages `window`; `'self'` = the layout scrolls itself; a selector (`'main'`) = runtime manages that element. `transitions` names an area for a move of its own (`{ left: 'sidebar' }`). With no names the page crossfades, and chrome that stays in place stays steady, so name one only to morph it: the name moves its box from where it was on screen to where it lands, so anything `fixed` in a box that scrolls drops through the page. Naming the body (`{ body: 'main' }`) freezes Safari on long pages. `layers` sets which area paints on top (`{ header: 2, left: 1 }`); every area is above the body by default, and a sticky area above non-sticky ones. A `z-index` inside an area cannot lift it past another — use `layers`, or `<Overlay>` to escape entirely.
306
+ **Layout `meta.js`:** `{ areas: ['header', 'footer', 'left'], scroll: 'self' }`. Area names are arbitrary; a page renders the areas its site's `layout/` directory fills. `scroll`: unset = runtime manages `window`; `'self'` = the layout scrolls itself; a selector (`'main'`) = runtime manages that element. `transitions` names an area for a move of its own (`{ left: 'sidebar' }`). With no names the page crossfades, and chrome that stays in place stays steady, so name one only to morph it: the name moves its box from where it was on screen to where it lands, so anything `fixed` in a box that scrolls drops through the page. Naming the body (`{ body: 'main' }`) freezes Safari on long pages. `layers` sets which area paints on top (`{ header: 2, left: 1 }`); every area is above the body by default, and a sticky area above non-sticky ones. A `z-index` inside an area cannot lift it past another — use `layers`, or `<Overlay>` to escape entirely.
307
307
 
308
- **Layout content** lives in `site/layout/`: `header.md`, `footer.md` for the default layout, or a named subdirectory (`site/layout/marketing/`) for named layouts — self-contained, no inheritance; the name matches regardless of case and a trailing `Layout` (`layout/docs/` serves `DocsLayout`). An area with several sections is a folder inside a layout's folder (`layout/default/header/1-topbar.md`); areas have no `page.yml` and render in filename order. Cascade: `page.yml → folder.yml → site.yml → defaultLayout → "default"`.
308
+ **Layout content** lives in `site/layout/`: `header.md`, `footer.md` for the default layout, or a named subdirectory (`site/layout/marketing/`) for named layouts — self-contained, no inheritance; the name matches regardless of case and a trailing `Layout` (`layout/docs/` serves `DocsLayout`). An area with several sections is a directory inside a layout's directory (`layout/default/header/1-topbar.md`); areas have no `page.yml` and render in filename order. Cascade: `page.yml → folder.yml → site.yml → defaultLayout → "default"`.
309
309
 
310
310
  Layout sections are regular section types; each content category takes a role:
311
311
 
@@ -45,13 +45,13 @@ locales/freeform/es/records/article/x.md
45
45
 
46
46
  **Data blocks** translate by the shape their key declares in `meta.js data:` — text fields, never an enum, URL or `translatable: false` field. A key declared `{}` falls to a heuristic that may offer structural strings (`style: display-black`) — declare the shape of every block a translator will see.
47
47
 
48
- **Images** translate by alt text. Words alone give the alt text in that language; a translation that is an image also names the file: `"2d093636": "![La superposition](/docs-media/fr/overview.png)"` — a `/` path in `public/` (a `./` path has no page folder to start from). Captions and a video's `poster` work the same way. Give every image alt text.
48
+ **Images** translate by alt text. Words alone give the alt text in that language; a translation that is an image also names the file: `"2d093636": "![La superposition](/docs-media/fr/overview.png)"` — a `/` path in `public/` (a `./` path has no page directory to start from). Captions and a video's `poster` work the same way. Give every image alt text.
49
49
 
50
50
  **Records** translate in the same `extract` run into `locales/records/manifest.json`, keyed by the record. A record whose query has a data schema translates exactly the fields the schema says are text; mark a code-like string `translatable: false`. Excerpts re-derive per language.
51
51
 
52
52
  **A data schema's own labels** are not in `locales/`: write them in `source_locale`, other languages in the schema's `i18n` keyed by path (`i18n: { fr: { model.label: Séance, section.brief.field.title.label: Titre } }`). See `development/data-schemas.md`.
53
53
 
54
- **Localized URLs:** `slug: { fr: a-propos }` in `page.yml` — the folder name stays canonical; nested folders compose; flows through navigation, switcher and sitemap. Each language gets its own `/fr/llms.txt` and `/fr/search-index.json`.
54
+ **Localized URLs:** `slug: { fr: a-propos }` in `page.yml` — the directory name stays canonical; nested directories compose; flows through navigation, switcher and sitemap. Each language gets its own `/fr/llms.txt` and `/fr/search-index.json`.
55
55
 
56
56
  ## Component side
57
57
 
@@ -108,10 +108,10 @@ The endpoint must accept the framework's batched `{ "events": [ … ] }` POST (`
108
108
 
109
109
  ### Google Analytics, Tag Manager, Meta's pixel
110
110
 
111
- **A `scripts` entry is a URL and nothing else, so these can't be installed that way.** Each one's install runs inline lines; from a URL alone GA sends nothing and Tag Manager never gets its page-load event. A tag carrying an attribute the vendor reads (`data-domain`, `data-website-id`) has the same problem. What works depends on who builds the pages:
111
+ **A `scripts` entry is a URL and nothing else, so these can't be installed that way.** Each one's install runs inline lines; from a URL alone GA sends nothing and Tag Manager never gets its page-load event. A tag carrying an attribute the vendor reads (`data-domain`, `data-website-id`) has the same problem. What works depends on who makes the pages:
112
112
 
113
- - **The framework builds them** (`uniweb export`, `uniweb deploy --host=<adapter>`): the vendor's snippet goes in `head.html` next to `site.yml`, and the build adds it to every page's `<head>`. A `services.google` entry does nothing here.
114
- - **Uniweb Cloud builds them** (`uniweb publish`, or publishing from the app): `head.html` is kept and synced but **not applied**. For Google's two, name the ID and the host loads the tag from the next publish, free, with no code, on any foundation:
113
+ - **A build makes them** (`uniweb export`, `uniweb deploy --host=<adapter>`): the vendor's snippet goes in `head.html` next to `site.yml`, and the build adds it to every page's `<head>`. A `services.google` entry does nothing here.
114
+ - **Uniweb Cloud serves them, with no build** (`uniweb publish`, or publishing from the app): `head.html` is kept and synced but **not applied**. For Google's two, name the ID and the host loads the tag from the next publish, free, with no code, on any foundation:
115
115
 
116
116
  ```yaml
117
117
  services:
@@ -36,7 +36,7 @@ No lock-in and no default you're pushed toward:
36
36
  | Any static host | `uniweb export` | full control; no account |
37
37
  | Uniweb Cloud | `uniweb publish` | non-technical content authors, client work |
38
38
 
39
- Adapters: `github-pages`, `cloudflare-pages`, `netlify`, `vercel`, plus `s3-cloudfront` for `deploy`. On Cloudflare Pages / Netlify / Vercel, `add ci` also adds per-PR previews. With nothing configured, `deploy` opens a picker and records the choice in `deploy.yml` beside `site.yml` — **the CLI writes it**; later deploys rewrite only `deploys:`; edit `targets:` to change where a site ships. A bare `deploy` goes to the default target, and when that's the `host: uniweb` target a publish recorded, it runs `publish`. Host credentials come from the environment. GitHub runs workflows only from the top of a repository: in a project that is a folder of a larger repo, its own `.github/` never runs — `status` says so and `add ci` refuses to write one there.
39
+ Adapters: `github-pages`, `cloudflare-pages`, `netlify`, `vercel`, plus `s3-cloudfront` for `deploy`. On Cloudflare Pages / Netlify / Vercel, `add ci` also adds per-PR previews. With nothing configured, `deploy` opens a picker and records the choice in `deploy.yml` beside `site.yml` — **the CLI writes it**; later deploys rewrite only `deploys:`; edit `targets:` to change where a site ships. A bare `deploy` goes to the default target, and when that's the `host: uniweb` target a publish recorded, it runs `publish`. Host credentials come from the environment. GitHub runs workflows only from the top of a repository: in a project that is a directory of a larger repo, its own `.github/` never runs — `status` says so and `add ci` refuses to write one there.
40
40
 
41
41
  **Three independent facts** `status` opens with:
42
42
 
@@ -54,7 +54,7 @@ A site can be in more than one place. `publish` makes a change live on Cloud, `g
54
54
 
55
55
  **Sync is developer-only and one-sided.** The app is the live source of truth for content; git is the reviewed, durable record. Authors never push or pull.
56
56
 
57
- **Nobody's work is overwritten without asking.** `push` is refused if the site changed on the backend since your last pull, and reports what changed. In a git repository `pull` merges like `git pull`: it commits the backend's content (*"The site's content on …"*) and merges into your branch against the last shared state. Your work and a teammate's are kept; a file the backend never had is never deleted; only a genuine overlap leaves conflict markers and a non-zero exit — settle it as in any merge, then `git commit` (where your uncommitted changes overlap, settle, `git add`, then `git stash drop`). A push or publish is refused while a file is in conflict. **In a repository a push sends what you have committed**: uncommitted site content is refused before anything is sent — commit, or `uniweb push --commit -m "…"` (commits the site's content only; `publish` and `sync` take `--commit` too). The ids the backend assigns are committed by the push itself, as `uniweb`. A push is also refused when your branch doesn't hold what this copy last took from the backend (after `git merge --abort`, or a fresh clone) — pull, then push. Outside git (including a folder the surrounding repo ignores), `pull` takes the backend's version over your files, asking first. `--force` is the deliberate overwrite in either direction. `sync` is `refresh` then `push`; neither publishes.
57
+ **Nobody's work is overwritten without asking.** `push` is refused if the site changed on the backend since your last pull, and reports what changed. In a git repository `pull` merges like `git pull`: it commits the backend's content (*"The site's content on …"*) and merges into your branch against the last shared state. Your work and a teammate's are kept; a file the backend never had is never deleted; only a genuine overlap leaves conflict markers and a non-zero exit — settle it as in any merge, then `git commit` (where your uncommitted changes overlap, settle, `git add`, then `git stash drop`). A push or publish is refused while a file is in conflict. **In a repository a push sends what you have committed**: uncommitted site content is refused before anything is sent — commit, or `uniweb push --commit -m "…"` (commits the site's content only; `publish` and `sync` take `--commit` too). The ids the backend assigns are committed by the push itself, as `uniweb`. A push is also refused when your branch doesn't hold what this copy last took from the backend (after `git merge --abort`, or a fresh clone) — pull, then push. Outside git (including a directory the surrounding repo ignores), `pull` takes the backend's version over your files, asking first. `--force` is the deliberate overwrite in either direction. `sync` is `refresh` then `push`; neither publishes.
58
58
 
59
59
  **Working on a site others edit:** `status` when you begin, when you come back, before push/publish/deploy, after any refusal. It reads the backend without taking anything: what changed file by file, what you hold that it lacks, who has a page open in the app right now, what in the project is uncommitted (an update, foundation source — a push neither sends nor waits for that, but a push or publish releases a changed foundation from the files). Take what changed (`pull` or `refresh`) before you edit; when someone has a page open in the app, tell the person before changing that page.
60
60
 
@@ -68,7 +68,7 @@ A site can be in more than one place. `publish` makes a change live on Cloud, `g
68
68
 
69
69
  ## Publishing vs registering
70
70
 
71
- Foundations on Cloud live in the catalog as `@org/name@version` (`name` from `main.js`). When a foundation powers one site, **don't run `uniweb register` yourself** — `uniweb publish` from the site releases the local foundation (when its code changed) and goes live in one step. A registered version is immutable, so a changed foundation is released under the next **patch** version, written into its `package.json` and committed by the push in a git repository (`--no-release` sends content only). For a change that isn't backwards compatible, set a higher minor/major yourself first. They stop when the registry holds a newer version released from another copy: pull it, or `--bump` to release above it. Register deliberately only when the foundation is a product for multiple sites; consuming sites pin `foundation: '@org/name@1.2.3'`. **The catalog is private and access-segregated** — people see only foundations licensed to sites they own or edit; the site carries the license. Schemas can be registered on their own from a schemas-only package (`@org/schemas`, or a bare `schemas/*.{yml,json,js}` folder). Auth via `uniweb login` or `UNIWEB_TOKEN`; preview with `--dry-run`.
71
+ Foundations on Cloud live in the catalog as `@org/name@version` (`name` from `main.js`). When a foundation powers one site, **don't run `uniweb register` yourself** — `uniweb publish` from the site releases the local foundation (when its code changed) and goes live in one step. A registered version is immutable, so a changed foundation is released under the next **patch** version, written into its `package.json` and committed by the push in a git repository (`--no-release` sends content only). For a change that isn't backwards compatible, set a higher minor/major yourself first. They stop when the registry holds a newer version released from another copy: pull it, or `--bump` to release above it. Register deliberately only when the foundation is a product for multiple sites; consuming sites pin `foundation: '@org/name@1.2.3'`. **The catalog is private and access-segregated** — people see only foundations licensed to sites they own or edit; the site carries the license. Schemas can be registered on their own from a schemas-only package (`@org/schemas`, or a bare `schemas/*.{yml,json,js}` directory). Auth via `uniweb login` or `UNIWEB_TOKEN`; preview with `--dry-run`.
72
72
 
73
73
  **Extensions.** An extension is a foundation: register it (`uniweb register` in its directory) and reference it like one. A site-relative URL (`/effects/entry.js`) works only where the site serves its own files (`export`, `deploy --host`); a site published to Uniweb hosting ships no JS, so `publish` rejects it and points to the catalog-ref form. A workspace-local extension is brought along by `publish` exactly as the primary is — released if its code changed, pinned on the published site.
74
74
 
@@ -105,12 +105,12 @@ When `status` names a newer release, take it: update, restart any running dev se
105
105
  | top-level `search:`, `submit:`, `assistant:`, `tracking:`, `api:`; `services.api`; `$devApi` | `services.<name>`; `services.backend`; `$devBackend` |
106
106
  | `published: false` on a record | `draft: true` |
107
107
  | `slug:` key in a record file; a file holding a list | the file name is the record's name; one record per file |
108
- | `[dir]` / `[path]` as parametric folder names; a folder inside `[...path]/` | `[slug]`, `[uuid]`, `[<field>]`, `[...path]` |
108
+ | `[dir]` / `[path]` as parametric directory names; a directory inside `[...path]/` | `[slug]`, `[uuid]`, `[<field>]`, `[...path]` |
109
109
  | `fonts.mono` | `fonts.code` |
110
110
  | `seo.baseUrl`; `seo.defaultImage`; `seo.locales`; `url:`, `trailingSlash:` in `site.yml` | `seo.origin` (scheme + host, no path); `seo.image`; `languages:`; `seo.origin` again |
111
- | `creatable_by` in a schema | models are open; protect with `append_only`, `readable_with`, `grantable` |
111
+ | `creatable_by` in a schema | who adds a type's entries is `blueprint.yml`'s `access.<type>.add`; a schema protects them with `append_only`, `readable_with`, `grantable` |
112
112
  | `uniweb.id`, `uniweb.scope` in a foundation's `package.json` | `name: '@scope/name'` in `main.js` |
113
113
  | `main.jsx`, `foundation.js`; JSX in a `.js` component | `main.js` (plain JS); `.jsx` |
114
114
  | `visuals:` in `meta.js`; `data` as a `content:` element | a `media:` element in `content:`; declare the tag in `data:` |
115
- | `versions:` in a folder | a folder named `v1` (`uniweb add version`) |
115
+ | `versions:` in a `folder.yml` or `page.yml` | a directory named `v1` (`uniweb add version`) |
116
116
  | `runtimePolicy: auto-patch / auto-minor` | omit; the framework doesn't read it |
@@ -45,7 +45,7 @@ uniweb add section Hero [--foundation ui] # sections/Hero/{index.jsx,me
45
45
  uniweb rename <foundation|site|extension> <old> <new> # rename across the whole workspace
46
46
  ```
47
47
 
48
- The CLI creates exactly the folder you ask for — no silent nesting under `foundations/` or `sites/`. If the target folder exists or another package of the same kind has the name, it stops with a precise error and suggests alternatives; a name held by the other kind gets a suffix (`add site marketing` beside a foundation named `marketing` makes `marketing-site`). `uniweb add section` scaffolds a starter the dev server picks up with no build or install.
48
+ The CLI creates exactly the directory you ask for — no silent nesting under `foundations/` or `sites/`. If the target directory exists or another package of the same kind has the name, it stops with a precise error and suggests alternatives; a name held by the other kind gets a suffix (`add site marketing` beside a foundation named `marketing` makes `marketing-site`). `uniweb add section` scaffolds a starter the dev server picks up with no build or install.
49
49
 
50
50
  Workspace layouts and their wiring (single, segregated, co-located, projects with several sites): `development/project-structures.md`. The same `@scope/name` shape means different things by position: a `foundation:` value is a catalog ref; a data-schema ref in `meta.js` resolves from an npm package (`@uniweb/schemas`, `@org/schemas`); `@uniweb/kit` in `dependencies` is an ordinary npm package.
51
51
 
@@ -108,7 +108,7 @@ The build adds preconnect hints, emits `@font-face` + preload, drops unreference
108
108
 
109
109
  Two more imports are opt-in: `@uniweb/kit/math-tokens.css` lays out equations, and `@uniweb/kit/callout-tokens.css` draws concept blocks such as `md:warning`, which are otherwise plain prose.
110
110
 
111
- **Tailwind reads the whole foundation.** `source("./")` on the import has it read every file under the foundation, in the foundation's own build and in a site's, so a class in any folder reaches both — one kept in a string for code elsewhere to write too, such as a map of colours to classes in `utils/`. A stylesheet that names folders instead (`@source "./sections/**/*.{js,jsx}"`, as older projects do) must name every folder that writes classes: the foundation's own build finds them all, but a site build and `uniweb dev` read only what those lines name, so a class in a folder left out is in one CSS and missing from the other. `uniweb dev`, a site build and `uniweb doctor` (`unread-folder`) name such a folder, and give the `source("./")` line that ends it. `theme-tokens.css` also tells Tailwind to read kit's source, so kit's own classes reach your CSS wherever your package manager put kit; a foundation that skips that import names kit itself, by where kit is (`./node_modules/@uniweb/kit/src/**` under pnpm, `../node_modules/@uniweb/kit/src/**` under npm).
111
+ **Tailwind reads the whole foundation.** `source("./")` on the import has it read every file under the foundation, in the foundation's own build and in a site's, so a class in any directory reaches both — one kept in a string for code elsewhere to write too, such as a map of colours to classes in `utils/`. A stylesheet that names directories instead (`@source "./sections/**/*.{js,jsx}"`, as older projects do) must name every directory that writes classes: the foundation's own build finds them all, but a site build and `uniweb dev` read only what those lines name, so a class in a directory left out is in one CSS and missing from the other. `uniweb dev`, a site build and `uniweb doctor` (`unread-folder`) name such a directory, and give the `source("./")` line that ends it. `theme-tokens.css` also tells Tailwind to read kit's source, so kit's own classes reach your CSS wherever your package manager put kit; a foundation that skips that import names kit itself, by where kit is (`./node_modules/@uniweb/kit/src/**` under pnpm, `../node_modules/@uniweb/kit/src/**` under npm).
112
112
 
113
113
  Custom CSS is expected alongside Tailwind — shadow systems, border hierarchies, gradients, glass. Tokens are a floor; add vocabulary that references them so it adapts per context:
114
114
 
@@ -1,12 +1,12 @@
1
1
  {
2
2
  "schemaVersion": 1,
3
- "generatedAt": "2026-11-09T22:12:50.994Z",
3
+ "generatedAt": "2026-11-10T02:40:30.915Z",
4
4
  "packages": {
5
5
  "@uniweb/api": {
6
6
  "version": "1.7.0"
7
7
  },
8
8
  "@uniweb/build": {
9
- "version": "1.20.2"
9
+ "version": "1.20.4"
10
10
  },
11
11
  "@uniweb/content-reader": {
12
12
  "version": "1.5.9"
@@ -15,7 +15,7 @@
15
15
  "version": "1.3.1"
16
16
  },
17
17
  "@uniweb/core": {
18
- "version": "1.6.9"
18
+ "version": "1.6.10"
19
19
  },
20
20
  "@uniweb/frame-bridge": {
21
21
  "version": "1.0.3"
@@ -33,10 +33,10 @@
33
33
  "version": "1.2.2"
34
34
  },
35
35
  "@uniweb/projections": {
36
- "version": "1.2.13"
36
+ "version": "1.2.14"
37
37
  },
38
38
  "@uniweb/runtime": {
39
- "version": "1.5.4"
39
+ "version": "1.5.5"
40
40
  },
41
41
  "@uniweb/scene": {
42
42
  "version": "1.0.1"