# AGENTS.md *This file ends with the line `End of AGENTS.md`. If you can't see that line, your tool cut the file short (Codex stops at `project_doc_max_bytes`, 32 KiB by default): read the rest of `AGENTS.md` yourself.* A Uniweb project separates **what the site says** from **how it's built**. The site is structured content, not prose: a section file's frontmatter names a section type and sets its params; its body is written in markdown but is **parsed into a typed content object** — `title`, `subtitle`, `paragraphs`, `links`, `items`, `data`, … — before any component sees it. Markdown is the authoring syntax, not the thing rendered: headings mark structure, not size, and a heading after body text starts an item. The foundation is the React that receives that object, under a runtime that owns the content pipeline, section wrapping, backgrounds, theming, light/dark, prerendering, routing and i18n. The components that face authors — **section types**, in `sections/` — receive `{ content, params, block }` and render; they are the only components with that signature. Developers define the vocabulary; authors compose with it. Everything behind one, in `components/`, is ordinary React with ordinary props: install any package, import any library, use any pattern. The foundation is a normal Node project; the few things you don't install (2.1, 2.4) are the exceptions. §1 says why the constraints are worth keeping; §2 is where your priors are wrong — each row a reflex from React / Next / Astro / Vite habits, what Uniweb does instead, and whether anything will tell you. Read both, then follow §3 before touching a file; its step 6 loads the lane guide and is not optional. Commands are written `uniweb `; without a global install, run them in the project as `npx uniweb `. ## 1. Why this is worth doing right 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: **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. **Your work survives.** A component built on tokens renders correctly in every section context, on every site that adopts the foundation, through every rebrand, in the visual editor and in prerendered HTML. A component with `text-gray-900` breaks the first time an author writes `theme: dark`. **Nothing has to be guessed.** The content shape is guaranteed. The directory listing is the catalog. `meta.js` is the interface. `inspect` prints the truth. The architecture removes exactly the uncertainties — what shape, which component, what it accepts — that make agents invent things. **Other people can act without you.** Every param you declare and every content slot you name is something an author can change in markdown or in the visual editor with no developer, no build and no pull request. The care you put into `meta.js` is the autonomy someone else gets. **A section type is a front desk, not a worker.** It reads params, picks a worker, and translates author vocabulary (`content`, `params`) into developer vocabulary (ordinary props). The workers live in `components/` and know nothing about CCA. That is the whole shape of a foundation: thin section types at the boundary, ordinary React behind them. ```jsx const workers = { slider: SliderHero, contact: ContactHero } export default function Hero({ content, params, block }) { const Worker = workers[params.variant] || SliderHero return } ``` One `type:` for the author, as many renderings as the design needs. A second section type that differs only in layout, or a conditional tree inside one, means you want a param and a worker. **Content is an offer, not a contract.** As the developer: a section type takes what it expects from `content` — the first paragraph if it needs one, every paragraph or every item only when showing them all is the point — and neither touches nor reacts to the rest. No check for unexpected content, no warning. `meta.js content:` says what the type *reads*, not what a section may hold, and a param combination that leaves some content unused is normal. As the author: write what the type reads; extra content isn't a goal. The tolerance exists so that switching `type:` or a `variant` is a one-line trial — change it, compare, switch back — with nothing to rewrite first. When you make such a switch, don't strip what the new rendering ignores; whether it stays is the author's decision once the trial is settled. The principles to reason from when a table in §2 doesn't cover the case: - **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. - **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. - **Configuration cascades** page → folder → site → foundation, like CSS specificity: defaults high, exceptions local. - **Metadata declares the interface.** `meta.js` drives defaults, the editor's controls, the schema and the docs. - **The site owns the theme.** Foundations declare variables, sites set values, components use tokens. When a rule in §2 feels like friction, that is the moment you are about to take back a job the runtime already does — and do it worse, once per component instead of once per site. The architecture doesn't limit what you can build; it fixes where each decision lives. ## 2. Where your priors are wrong ### 2.1 Project and tooling | By reflex you'd… | Here | Signal | |---|---|---| | Write `package.json`, `vite.config.js`, `index.html`, an entry file | `npx uniweb@latest create --template `; `uniweb add site / foundation / section / project / extension`. The CLI owns those files. | build fails far from the cause | | `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 | | `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 | | 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 at `. `uniweb dev --status` / `--stop` know only that server. | wrong server, silent | | 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` | | Trust folder names for the workspace layout | `pnpm-workspace.yaml` globs decide (§3.2). | — | | `main.jsx`; JSX in a `.js` file | `main.js` is plain JS; JSX lives in `.jsx`. | build stops | | Guess which section types exist or what a param is called | `ls /sections/`, `cat …//meta.js`. Every foundation's vocabulary is different; `uniweb docs --from-source` writes it all to `COMPONENTS.md`. | red box / silent | | Predict what markdown parses to | `uniweb inspect ` prints the shape. | silent (wrong field) | | Rely on what you remember about Uniweb | The pinned version is the truth: `uniweb --help`, `uniweb guide`, `uniweb.io/llms.txt` (§6). A 404 on a URL you invented means your guess was wrong. | — | | `--force` past a refusal; treat `git push` as deploy; publish on the person's behalf | Never force. Commit your own work as you go. `git push`, creating a site on a backend, going live, spending money and whatever `status` marks "ask the person first" are theirs. | push refused / money | ### 2.2 Content | By reflex you'd… | Here | Signal | |---|---|---| | Pick heading levels for size | Levels are **structure**: `#` title; exactly one step smaller = `subtitle`; two steps smaller, a `---`, or any heading after body text = an `item`. `###` right after `#` is an item; `##` is a subtitle line. A later heading as large as the first leaves no `title`: all of them become items. | silent | | Order the file the way the page should look | Write semantically; the component arranges. | — | | Put an icon or image above the title, as it will look | Anything above the first heading empties `title`: an icon or text puts the heading in `items[0]`, an image puts it in `headings`. Write it under the heading — it is still `icons[0]` or `images[0]`. | silent; `inspect` shows it | | ``, `
` in markdown | Shown as text. `[text]{accent}`, `**bold**`; a line break is `
` or a trailing `\`. | build names the file | | Write `pages: [a, b]` or `sections: [a, b]` to set order | Those lists are **strict**: an unlisted page leaves every menu, an unlisted section leaves the page. `[a, b, ...]` means "these first". At the site root the first of `pages:` is `/`, whatever `index:` says. | silent | | `primary: #3b82f6` | `'#3b82f6'` — an unquoted `#` starts a YAML comment. | build warns | | Expect any frontmatter key to do something, any `type:` name to work | A key reaches `params` and does nothing unless the type reads it (its `meta.js` says which); one named for a content field (`title:`) replaces that field. Only types present in `sections/` work. | silent / red box | | 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 | | `pages/fr/about.md` for French | `locales/` beside `pages/`; `pages/` holds the default language only. | silent — it becomes a page at `/fr` | | `t('key')`, `` | Nothing — content arrives translated; each language is its own build. | — | | `src/assets/`, `assets/img.png` | `./img.png` beside the page, or `/img.png` in `public/`. There is no assets folder. | build stops, or warns | | `fetch: /api/posts`, `fetch: ./data.json` | `fetch:` names a query from `queries.yml`; a URL belongs on the query (`url:`). | build stops | | `records/blog/2025/post.md`; one YAML file holding a list | Flat: `records//.md`, one record per file; the file name is `$name`. | folder read as a schema, silent | | `` `/blog/${slug}` `` | `item.$route` — never compose a URL. | works until a page moves | | `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 | | 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 | | Expect `{company}` to resolve | Only under a foundation with `createLoomHandlers`; otherwise it renders literally. | build warns if `site.yml` has `placeholders:` | | `hidden: true` on `pages/404/` to keep it out of nav | That makes it a draft. `hideIn: ['*']` controls nav. | silent | | 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 | ### 2.3 Section types and the components behind them | By reflex you'd… | Here | Signal | |---|---|---| | Wrap the component in `
`; `Header.as = 'header'` | The runtime wraps every section in a bare `
` (no padding to reset); `Type.className` adds classes to it. The built-in layout already wraps the header and footer areas in `
`/`