uniweb 0.11.0 → 0.12.1

package/README.md

@@ -18,7 +18,7 @@ npm install
 npm run dev
 ```
 
-Edit files in `site/pages/` and `foundation/src/sections/` to see changes instantly.
+Edit files in `site/pages/` and `src/sections/` to see changes instantly.
 
 > **pnpm ready** — `pnpm create uniweb` works out of the box. Projects include both `pnpm-workspace.yaml` and npm workspaces.
 
@@ -62,10 +62,10 @@ The `build` command outputs to `site/dist/`. With pre-rendering enabled (the def
 
 Every project starts as a workspace with two packages:
 
-- **`site/`** — Content, pages, entry point
-- **`foundation/`** — React components
+- **`site/`** — Content, pages, entry point (package name: `site`)
+- **`src/`** — React components, the site's source code (package name: `src`)
 
-Content authors work in markdown. Component authors work in React. Neither can break the other's work. As your project grows, use `uniweb add` to add more foundations, sites, and extensions.
+A site is pure content. A foundation is the site's source code — that's why it lives in `src/`. Content authors work in markdown. Component authors work in React. Neither can break the other's work. As your project grows, use `uniweb add` to add more foundations, sites, and extensions.
 
 ```
 my-project/
@@ -75,19 +75,21 @@ my-project/
 │   │       ├── page.yml      # Page metadata
 │   │       └── hero.md       # Section content
 │   ├── locales/              # i18n (hash-based translations)
-│   ├── main.js               # Entry point (~6 lines)
+│   ├── entry.js              # Entry point (~6 lines)
 │   ├── vite.config.js        # 3-line config
 │   └── public/               # Static assets
 │
-└── foundation/               # Your components
-    ├── src/
-    │   ├── sections/         # Section types (addressable from markdown)
-    │   │   ├── Hero.jsx      # Bare file → section type (no meta.js needed)
-    │   │   └── Features/
-    │   │       ├── meta.js   # Content interface (params, presets)
-    │   │       └── Features.jsx
-    │   └── components/       # Regular React components
-    │       └── Button.jsx
+└── src/                      # Foundation package (the site's source)
+    ├── sections/             # Section types (addressable from markdown)
+    │   ├── Hero.jsx          # Bare file → section type (no meta.js needed)
+    │   └── Features/
+    │       ├── meta.js       # Content interface (params, presets)
+    │       └── Features.jsx
+    ├── components/           # Regular React components
+    │   └── Button.jsx
+    ├── main.js               # Package exports (vars, defaultLayout, props)
+    ├── styles.css            # Tailwind v4 + CSS tokens
+    ├── package.json          # name: "src"
     ├── vite.config.js        # 3-line config
     └── dist/                 # Built output
 ```
@@ -204,7 +206,7 @@ After creating your project:
 
 3. **Learn the configuration** — Run `uniweb docs site` or `uniweb docs page` for quick reference on configuration options.
 
-4. **Create a section type** — Add a file to `foundation/src/sections/` (e.g., `Banner.jsx`) and rebuild. Bare files at the root are discovered automatically — no `meta.js` needed. Add `meta.js` when you want to declare params or presets. See the [Component Metadata Reference](https://github.com/uniweb/docs/blob/main/reference/component-metadata.md) for the full schema.
+4. **Create a section type** — Add a file to `src/sections/` (e.g., `Banner.jsx`) and rebuild. Bare files at the root are discovered automatically — no `meta.js` needed. Add `meta.js` when you want to declare params or presets. See the [Component Metadata Reference](https://github.com/uniweb/docs/blob/main/reference/component-metadata.md) for the full schema.
 
 The `meta.js` file defines what content and parameters a component accepts. The runtime uses this metadata to apply defaults and guarantee content structure—no defensive null checks needed in your component code.
 
@@ -228,7 +230,7 @@ Save and see the change instantly in your browser.
 
 ### Your First Component Change
 
-Open `foundation/src/sections/Hero.jsx`. The component receives parsed content:
+Open `src/sections/Hero.jsx`. The component receives parsed content:
 
 ```jsx
 export default function Hero({ content }) {
@@ -241,7 +243,7 @@ The parser extracts semantic elements from markdown—`title` from the first hea
 
 ## Foundations Are Portable
 
-The `foundation/` folder ships with your project as a convenience, but a foundation is a self-contained artifact with no dependency on any specific site. Sites reference foundations by configuration, not by folder proximity.
+The `src/` folder (your project's foundation) ships with your project as a convenience, but a foundation is a self-contained artifact with no dependency on any specific site. Sites reference foundations by configuration, not by folder proximity.
 
 **Three ways to use a foundation:**
 
@@ -251,7 +253,7 @@ The `foundation/` folder ships with your project as a convenience, but a foundat
 | **npm package**  | `npm add @acme/foundation`         | Distributing via standard package tooling          |
 | **Runtime link** | Foundation loads from a URL        | Independent release cycles, platform-managed sites |
 
-You can delete the `foundation/` folder entirely and point your site at a published foundation. Or develop a foundation locally, then publish it for other sites to consume. The site doesn't care where its components come from.
+You can delete the `src/` folder entirely and point your site at a published foundation. Or develop a foundation locally, then publish it for other sites to consume. The site doesn't care where its components come from.
 
 **This enables two development patterns:**
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.11.0",
+  "version": "0.12.1",
   "description": "Create structured Vite + React sites with content/code separation",
   "type": "module",
   "bin": {
@@ -41,14 +41,14 @@
     "js-yaml": "^4.1.0",
     "prompts": "^2.4.2",
     "tar": "^7.0.0",
-    "@uniweb/core": "0.7.8",
-    "@uniweb/kit": "0.9.8",
-    "@uniweb/runtime": "0.8.9"
+    "@uniweb/core": "0.7.9",
+    "@uniweb/kit": "0.9.9",
+    "@uniweb/runtime": "0.8.10"
   },
   "peerDependencies": {
-    "@uniweb/build": "0.12.0",
+    "@uniweb/build": "0.13.1",
     "@uniweb/content-reader": "1.1.9",
-    "@uniweb/semantic-parser": "1.1.15"
+    "@uniweb/semantic-parser": "1.1.16"
   },
   "peerDependenciesMeta": {
     "@uniweb/build": {

package/partials/agents.md

@@ -56,21 +56,23 @@ Most projects start as a workspace with two packages:
 
 ```
 project/
-├── foundation/     # Component developer's domain
+├── src/            # Component developer's domain (the foundation package)
 ├── site/           # Content author's domain
 └── pnpm-workspace.yaml
 ```
 
-- **Foundation** (developer): React components. Those in `src/sections` and `src/layouts` are *section types* — selectable by content authors via `type:` in frontmatter, or used for site-level layout areas (header, footer, panel). Most have a `meta.js` with metadata in them. Everything in `src/components` (or elsewhere) is ordinary React — the developer's workbench for helper components that section types import and compose internally.
-- **Site** (content author): Markdown content + configuration. Each section file references a section type. Authors work here without touching foundation code. It may also contain collections of structured content and/or references to external data sources.
+A site is pure content. A foundation is the site's source code — that's why it lives in `src/`. The foundation's `package.json::name` is `src` (a unique workspace package name; symmetric with `site`).
 
-**The composition boundary:** Authors compose pages from finished section types — choosing types, writing content, setting params. Developers compose section types from building blocks — importing helpers from `src/components/`, using libraries, writing JSX. These are two different levels of composition. The section type is the boundary between them. Don't expose building-block composition to authors; build complete, self-contained section types that handle their own internal structure.
+- **Foundation** (developer, in `src/`): React components. Those in `src/sections` and `src/layouts` are *section types* — selectable by content authors via `type:` in frontmatter, or used for site-level layout areas (header, footer, panel). Most have a `meta.js` with metadata in them. Everything in `src/components` (or elsewhere) is ordinary React — the developer's workbench for helper components that section types import and compose internally.
+- **Site** (content author, in `site/`): Markdown content + configuration. Each section file references a section type. Authors work here without touching foundation code. It may also contain collections of structured content and/or references to external data sources.
 
-> Multi-site projects use sub-folders with site/foundation pairs in them, or segregate foundations and sites into separate folders (`foundations/`, `sites/`).
+**The composition boundary:** Authors compose pages from finished section types — choosing types, writing content, setting params. Developers compose section types from building blocks — importing helpers from `components/`, using libraries, writing JSX. These are two different levels of composition. The section type is the boundary between them. Don't expose building-block composition to authors; build complete, self-contained section types that handle their own internal structure.
+
+> Multi-site projects use sub-folders with site/foundation pairs in them (each project gets its own `src/` + `site/`), or segregate foundations and sites into separate folders (`foundations/`, `sites/`).
 
 ## Project Setup
 
-Always use the CLI to scaffold projects — never write `package.json`, `vite.config.js`, `main.js`, or `index.html` manually. The CLI resolves correct versions and structure.
+Always use the CLI to scaffold projects — never write `package.json`, `vite.config.js`, `entry.js`, or `index.html` manually. The CLI resolves correct versions and structure.
 
 **npm or pnpm.** Projects include both `pnpm-workspace.yaml` and npm workspaces. Replace `pnpm` with `npm` in any command below.
 
@@ -89,18 +91,26 @@ uniweb add project docs
 pnpm install
 ```
 
-This creates `docs/foundation/` + `docs/site/` with package names `docs-foundation` and `docs-site`. Use `--from <template>` to apply template content to both packages.
+This creates `docs/src/` + `docs/site/` with package names `docs-src` and `docs-site`. Use `--from <template>` to apply template content to both packages.
 
 ### Adding individual packages
 
+The CLI creates exactly the folder you ask for. No silent nesting under `foundations/` or `sites/` — the framework doesn't require a particular folder layout, so the CLI doesn't impose one.
+
 ```bash
-uniweb add foundation           # First foundation → ./foundation/
-uniweb add foundation ui        # Named → ./ui/
-uniweb add site                 # First site → ./site/
-uniweb add site blog            # Named → ./blog/
+uniweb add foundation           # No name → ./src/                    (package: src)
+uniweb add foundation ui        # Bare name → ./ui/                   (package: ui)
+uniweb add foundation foundations/effects   # Slash → folder is the path  (package: effects)
+uniweb add foundation marketing --path libs # name + parent → ./libs/marketing/  (package: marketing)
+
+uniweb add site                 # No name → ./site/                   (package: site)
+uniweb add site blog            # Bare name → ./blog/                 (package: blog)
+uniweb add site sites/store     # Slash → folder is the path           (package: store)
 ```
 
-The name is both the directory name and the package name. Use `--project <n>` to co-locate under a project directory (e.g., `--project docs` → `docs/foundation/`).
+If the target folder already exists, or the package name is already taken by another package in the workspace, the CLI stops with a precise error and suggests alternatives. The check uses the same `classifyPackage` logic the build uses, so cross-type collisions are caught (you can't `add site marketing` if a foundation named `marketing` is already in the workspace).
+
+Use `--project <n>` to co-locate a foundation+site pair under a project directory: `--project docs` → `docs/src/` (package `docs-src`) + `docs/site/` (package `docs-site`). The `-src` / `-site` suffix is the convention for co-located projects only — single-foundation workspaces use bare `src`.
 
 ### Adding section types
 
@@ -109,19 +119,19 @@ uniweb add section Hero
 uniweb add section Hero --foundation ui   # When multiple foundations exist
 ```
 
-Creates `src/sections/Hero/index.jsx` and `meta.js` with a minimal CCA-proper starter. The dev server picks it up automatically — no build or install needed.
+Creates `sections/Hero/index.jsx` and `meta.js` with a minimal CCA-proper starter. The dev server picks it up automatically — no build or install needed.
 
 ### What the CLI generates
 
-**Foundation** (`vite.config.js`, `package.json`, `src/foundation.js`, `src/styles.css`):
+**Foundation** (`vite.config.js`, `package.json`, `main.js`, `styles.css`):
 - `defineFoundationConfig()` in vite.config.js
 - Dependencies pinned to current npm versions
 - `@import "@uniweb/kit/theme-tokens.css"` in styles.css
 
-**Site** (`vite.config.js`, `package.json`, `main.js`, `index.html`, `site.yml`):
+**Site** (`vite.config.js`, `package.json`, `entry.js`, `index.html`, `site.yml`):
 - `defineSiteConfig()` in vite.config.js
 - `react-router-dom` in devDependencies (required by pnpm strict mode)
-- Standard `start()` call in main.js
+- Standard `start()` call in entry.js
 
 ## Commands
 
@@ -134,6 +144,116 @@ pnpm preview    # Preview production build (SSG + SPA)
 
 ---
 
+## `package.json` `uniweb` configuration
+
+The `uniweb` block in `package.json` carries platform-specific configuration that doesn't belong in the npm-standard fields. All fields are optional; defaults apply when omitted.
+
+```json
+{
+  "name": "src",
+  "version": "1.0.0",
+  "uniweb": {
+    "id": "marketing",
+    "runtimePolicy": "auto-minor"
+  },
+  "dependencies": {
+    "@uniweb/core": "0.7.8",
+    "@uniweb/runtime": "0.8.9"
+  }
+}
+```
+
+| Field | Where used | Default | Purpose |
+|---|---|---|---|
+| `id` | `uniweb publish` | (set on first publish via the prompt, or via `--name`) | The foundation's published id — the bare-name segment in `~handle/<id>` or `@org/<id>`. Decoupled from `package.json::name` (a workspace concern), so renaming the foundation on the registry doesn't ripple through site dependencies. |
+| `namespace` | `uniweb publish` | (none — see scope resolution) | Legacy explicit org-namespace override. Equivalent to using a scoped `package.json::name` (`"@myorg/foundation"`). Rarely needed in modern foundations. |
+| `runtimePolicy` | `dist/runtime-pin.json` (foundation build) | `"auto-minor"` | Controls how sites using this foundation receive runtime updates. Three values: `"exact"`, `"auto-patch"`, `"auto-minor"`. See "Foundation runtime policy" below. |
+
+**On the split between `package.json::name` and `uniweb.id`:** the workspace name is what pnpm uses for `file:` linking and what `site.yml::foundation` references. The published id is what the registry stores. Keeping them separate means renaming on the registry (e.g. `marketing` → `marketing-pro`) is a one-shot `uniweb publish --name marketing-pro` — it persists to `uniweb.id` without touching the workspace.
+
+These are the only fields the platform consumes today. Future platform features that need static configuration will land here too.
+
+---
+
+## Foundation runtime policy
+
+(Foundation authors only — sites don't set this.)
+
+When a foundation builds, it pins the `@uniweb/runtime` version it was built against (from its own dependencies) into `dist/runtime-pin.json`. Foundations can also declare a *policy* that controls how the runtime version moves forward on already-published sites:
+
+```json
+// foundation's package.json
+{
+  "name": "@uniweb/votiverse",
+  "version": "0.1.1",
+  "uniweb": {
+    "runtimePolicy": "auto-minor"
+  },
+  "dependencies": {
+    "@uniweb/core": "0.7.8"
+  }
+}
+```
+
+Three valid values:
+
+| Value | Meaning |
+|---|---|
+| `exact` | The site stays on exactly the runtime version this foundation built against. Newer runtime versions are not auto-applied. |
+| `auto-patch` | The site auto-updates within the same `MAJOR.MINOR.x` (e.g. `0.8.9` → `0.8.10`). Conservative; matches typical npm patch semantics. |
+| `auto-minor` | The site auto-updates within the same `MAJOR.x.y` (e.g. `0.8.9` → `0.9.0`). |
+
+**Default when unset:** `auto-minor`. Most foundations don't need to set this field — the platform's runtime is internally backwards-compatible at the minor level by convention, and `auto-minor` lets your foundation's sites pick up bug fixes and additive features without rebuilding the foundation.
+
+Set `exact` if your foundation depends on undocumented runtime internals or has been audited against one specific runtime release and you don't want to allow drift.
+
+The field is read by `@uniweb/build` at build time and emitted into `dist/runtime-pin.json` next to the runtime version:
+
+```json
+// dist/runtime-pin.json (auto-generated)
+{ "runtime": "0.8.9", "policy": "auto-minor" }
+```
+
+Sites using your foundation will see this pin + policy when they're served. Site owners cannot override your policy choice — this is the foundation author's contract with the platform.
+
+### Where does the pinned runtime version come from?
+
+You may notice your foundation's `dist/runtime-pin.json` reports a runtime version (e.g. `0.8.9`) without your `package.json` declaring `@uniweb/runtime` anywhere. This is intentional.
+
+`@uniweb/runtime` is pulled in **transitively** through `@uniweb/build` (which every foundation has as a devDependency). The runtime version baked into your foundation's pin is whichever version your `@uniweb/build` version pulled in at install time:
+
+```
+your foundation
+  └─ devDependencies: "@uniweb/build": "0.12.0"
+       └─ pulls in @uniweb/runtime  (whatever version that build version locks)
+            → resolved at install time → version goes into dist/runtime-pin.json
+```
+
+Practical implications:
+
+- **You don't need to add `@uniweb/runtime` to your foundation's dependencies.** Runtime is the host environment, not a foundation import.
+- **To bump the runtime version your foundation pins, bump your `@uniweb/build` dep.** When a newer build version ships pulling in a newer runtime, updating your devDependency is how you adopt it.
+- **You can override by adding `@uniweb/runtime` directly to your foundation's `dependencies`** — but this is rarely needed and creates two sources of truth for the runtime version. Don't do this unless you have a specific reason.
+- **Whichever runtime version is pinned, your `runtimePolicy` controls how sites can move forward beyond it.** Pinning `0.8.9` with `auto-minor` lets sites pick up `0.9.0` or higher (within the same major); pinning with `exact` locks them at `0.8.9` until you rebuild your foundation.
+
+### What happens when fields aren't set
+
+The system has multi-layer fallbacks so missing or partial information is always handled gracefully:
+
+| Scenario | What happens |
+|---|---|
+| **`uniweb.runtimePolicy` not set in `package.json`** | `dist/runtime-pin.json` is emitted with the runtime version but no `policy` field. At serve time the platform applies `auto-minor` as the implicit default. Most foundations don't need to set `runtimePolicy` — leaving it unset is the correct choice when you want default behavior. |
+| **`@uniweb/runtime` not resolvable at build time** | The build silently skips emitting `runtime-pin.json`. This was the pre-Strategy-S behavior — your foundation falls back to the legacy self-contained build path. New foundations created with `npx uniweb create` always have `@uniweb/runtime` as a dependency, so this only affects unusual workspace setups. |
+| **`runtime-pin.json` is missing or malformed** | The platform's edge dispatcher detects the absence and serves the foundation through the legacy bundling path (the foundation's own `ssr-worker-bundle.js` is used). Your sites still work; they just don't participate in runtime propagation. |
+| **`runtime-pin.json` has a `runtime` version that's not actually deployed to the platform** | The site publish flow rejects the publish with a clear error message asking you to deploy the pinned runtime version first. This is caught at publish time, not at serve time. |
+| **You set `policy: "auto-minor"` but no compatible newer version exists** | The site stays on the version you pinned. The resolver only moves forward when a newer version satisfying the policy is actually available. |
+
+Bottom line: a foundation that doesn't set `runtimePolicy` gets `auto-minor` behavior automatically. A foundation that doesn't ship `runtime-pin.json` at all (e.g. a legacy build) still serves correctly through the platform's compatibility path — you just don't get the propagation benefits. Set `runtimePolicy` explicitly only when you want to override the default (typically to `exact` for stability-critical builds).
+
+(For platform operators interested in how propagation walks consume this field, see `kb/platform/operations/version-propagation.md` in the private docs.)
+
+---
+
 ## Content Authoring
 
 The decision rule: **would a content author need to change this?** Yes → it belongs in markdown, frontmatter, or a tagged data block. No → it belongs in component code.
@@ -833,7 +953,7 @@ Foundation-level CSS variables are for values that must stay consistent **across
 
 If you need them, declare vars in two places:
 
-**`foundation.js`** — metadata for the editor and schema:
+**`main.js`** — metadata for the editor and schema:
 
 ```js
 export const vars = {
@@ -853,7 +973,7 @@ export const vars = {
 }
 ```
 
-The `styles.css` declaration ensures defaults are present in the foundation's CSS output and enables Tailwind shorthand (`rounded-(--radius)` instead of `rounded-[var(--radius)]`). The `foundation.js` declaration provides descriptions and types for the visual editor. Sites override values in `theme.yml` under `vars:` — the site's theme CSS takes priority over the foundation defaults.
+The `styles.css` declaration ensures defaults are present in the foundation's CSS output and enables Tailwind shorthand (`rounded-(--radius)` instead of `rounded-[var(--radius)]`). The `main.js` declaration provides descriptions and types for the visual editor. Sites override values in `theme.yml` under `vars:` — the site's theme CSS takes priority over the foundation defaults.
 
 **Common mistake:** Using foundation vars for values that belong to a specific component. A header height is a layout param, not a foundation var — the layout component owns it. A sidebar width is a layout param too. Foundation vars are for values that multiple unrelated components share — radii, spacing, shadows.
 
@@ -862,7 +982,7 @@ The `styles.css` declaration ensures defaults are present in the foundation's CS
 Tokens handle context adaptation — the hard problem. **They are a floor, not a ceiling.** A great foundation adds design vocabulary on top:
 
 ```css
-/* foundation/src/styles.css */
+/* styles.css */
 .border-subtle { border-color: color-mix(in oklch, var(--border), transparent 50%); }
 .border-strong { border-color: color-mix(in oklch, var(--border), var(--heading) 30%); }
 .text-tertiary { color: color-mix(in oklch, var(--body), var(--subtle) 50%); }
@@ -1245,10 +1365,10 @@ This is the system-building pattern at its clearest: **section types are the pub
 
 ### Section components are composites
 
-A section component is rarely a single flat render. It imports helper components from `src/components/` and utilities from `src/utils/` to build a complex UI while presenting a single `type:` to the content author. These directories are the developer's workbench — ordinary React and JS, not selectable by authors, not auto-discovered.
+A section component is rarely a single flat render. It imports helper components from `components/` and utilities from `utils/` to build a complex UI while presenting a single `type:` to the content author. These directories are the developer's workbench — ordinary React and JS, not selectable by authors, not auto-discovered.
 
 ```jsx
-// src/sections/Pricing/index.jsx
+// sections/Pricing/index.jsx
 import PricingCard from '#components/PricingCard'
 import formatPrice from '#utils/formatPrice'
 
@@ -1264,7 +1384,7 @@ export default function Pricing({ content, params }) {
 }
 ```
 
-The content author writes `type: Pricing` and defines tiers as content items. The section component maps items to cards using a helper component from `src/components/` and a formatting utility from `src/utils/`. Neither is selectable by authors — they're implementation details behind the section type boundary.
+The content author writes `type: Pricing` and defines tiers as content items. The section component maps items to cards using a helper component from `components/` and a formatting utility from `utils/`. Neither is selectable by authors — they're implementation details behind the section type boundary.
 
 **When to reach for this pattern:** When a page type has consistent structural elements (header bars, navigation footers, contextual sidebars) that the content author shouldn't need to add as separate sections. If the author would have to add the same boilerplate sections to every page of a certain type, the section component should compose them internally.
 
@@ -1273,7 +1393,7 @@ The content author writes `type: Pricing` and defines tiers as content items. Th
 ### Foundation Organization
 
 ```
-foundation/src/
+src/                     # the foundation package (folder name is `src`)
 ├── sections/            # Section types (auto-discovered)
 │   ├── Hero.jsx         # Bare file — no folder needed
 │   ├── Features/        # Folder when you need meta.js
@@ -1293,17 +1413,21 @@ foundation/src/
 │   └── Card.jsx
 ├── utils/               # Helper functions, non-React logic
 │   └── splitContent.js
-└── styles.css
+├── main.js
+├── styles.css
+└── package.json         # name: "src"
 ```
 
-**Discovery:** PascalCase files/folders at root of `sections/` are auto-discovered. Nested levels require `meta.js`. Lowercase directories are organizational only. `hidden: true` excludes a component entirely. Everything outside `sections/` is ordinary React.
+**Discovery:** PascalCase files/folders at root of `src/sections/` are auto-discovered. Nested levels require `meta.js`. Lowercase directories are organizational only. `hidden: true` excludes a component entirely. Everything outside `src/sections/` is ordinary React.
+
+**Source root.** The foundation package's source files live at the package root — the `src/` folder *is* the foundation. The build reads `package.json::main` to know that (for new scaffolds, `main: "./_entry.generated.js"`). Older foundations may use an even-more-nested layout where the source lives in `foundation/src/` and `main` points to `./src/_entry.generated.js`; both shapes work through the same code path.
 
-**Import aliases:** Foundations include subpath imports in `package.json` that map to `src/` subdirectories. Use them instead of brittle relative paths:
+**Import aliases:** Foundations include subpath imports in `package.json` for shared internals. Use them instead of brittle relative paths:
 
 | Alias | Maps to | Use for |
 |-------|---------|---------|
-| `#components/*` | `./src/components/*` | Shared React components |
-| `#utils/*` | `./src/utils/*` | Helper functions, non-React logic |
+| `#components/*` | `./components/*` | Shared React components |
+| `#utils/*` | `./utils/*` | Helper functions, non-React logic |
 
 ```jsx
 // ✅ Clean — use aliases
@@ -1316,7 +1440,7 @@ import LessonHeader from '../../components/LessonHeader'
 
 Within the same directory (e.g., one component importing a sibling), use normal relative imports (`./AIFeedbackCard`).
 
-**Foundation entry shape (`src/foundation.js`).** A single `export default { … }` whose top-level keys are the capabilities the foundation provides — e.g. `name`, `description`, `defaultLayout`, `defaultSection`, `viewTransitions`, `props`, `defaultInsets`, `xref`, `outputs`, `handlers`. Optionally a named `vars` export for theme-variable metadata (see *Foundation variables*). Everything else (section types, layouts) is auto-discovered from `src/sections/` and `src/layouts/` and merged in by `@uniweb/build`. The build wraps your default export under `default.capabilities` in the produced `dist/foundation.js`; you don't write that wrapper yourself, and most foundation code never sees it. The one place it matters: when you import your **own** `src/foundation.js` from a foundation component (e.g., a download button calling `compileDocument(website, { foundation })`), you get the bare default object — pass it through directly, Press handles both shapes.
+**Foundation entry shape (`main.js`).** A single `export default { … }` whose top-level keys are the capabilities the foundation provides — e.g. `name`, `description`, `defaultLayout`, `defaultSection`, `viewTransitions`, `props`, `defaultInsets`, `xref`, `outputs`, `handlers`. Optionally a named `vars` export for theme-variable metadata (see *Foundation variables*). Everything else (section types, layouts) is auto-discovered from `sections/` and `layouts/` and merged in by `@uniweb/build`. The build wraps your default export under `default.capabilities` in the produced `dist/foundation.js`; you don't write that wrapper yourself, and most foundation code never sees it. The one place it matters: when you import your **own** `main.js` from a foundation component (e.g., a download button calling `compileDocument(website, { foundation })`), you get the bare default object — pass it through directly, Press handles both shapes.
 
 ### Website and Page APIs
 
@@ -1438,10 +1562,10 @@ Other navigation methods: `block.getPrevBlockInfo()`, `block.page.getFirstBodyBl
 
 ### Custom Layouts
 
-Layouts live in `foundation/src/layouts/` and are auto-discovered:
+Layouts live in `layouts/` (inside the foundation package) and are auto-discovered:
 
 ```js
-// foundation/src/foundation.js
+// main.js
 export default {
   name: 'My Template',
   description: 'A brief description',
@@ -1450,7 +1574,7 @@ export default {
 ```
 
 ```jsx
-// foundation/src/layouts/DocsLayout/index.jsx
+// layouts/DocsLayout/index.jsx
 export default function DocsLayout({ header, body, footer, left, right, params }) {
   return (
     <div className="min-h-screen flex flex-col">
@@ -1485,14 +1609,14 @@ Named subdirectories are self-contained — no inheritance. Layout cascade: `pag
 
 ## Content Handlers
 
-Content handlers are a transform layer that runs between data assembly and the component. They're declared in `foundation.js` and apply to every section in the foundation. The standard content shape (title, paragraphs, items, sequence) is the default — handlers can reshape it.
+Content handlers are a transform layer that runs between data assembly and the component. They're declared in `main.js` and apply to every section in the foundation. The standard content shape (title, paragraphs, items, sequence) is the default — handlers can reshape it.
 
 ### The three hooks
 
 The foundation declares handlers as an object in its default export:
 
 ```js
-// foundation.js
+// main.js
 export default {
   handlers: {
     data:    (data, block) => { /* ... */ },
@@ -1598,7 +1722,7 @@ Don't port line-by-line. Study the source, then rebuild from first principles. O
 
 2. **Use named layouts** for different page groups — marketing layout for landing pages, docs layout for `/docs/*`.
 
-3. **Dump legacy components under `src/components/`** — they're not section types. Import from section types during transition.
+3. **Dump legacy components under `components/`** — they're not section types. Import from section types during transition.
 
 4. **Create section types one at a time.** Migration levels:
    - **Level 0**: Paste the original as one section type. Routing and dev tooling work immediately.
@@ -1610,13 +1734,13 @@ Don't port line-by-line. Study the source, then rebuild from first principles. O
 
 6. **Name by purpose, not content** — `TheModel` → `SplitContent`, `WorkModes` → `FeatureColumns`.
 
-7. **UI helpers → `components/`** — Buttons, badges, cards in `src/components/` (no `meta.js`, not selectable by authors).
+7. **UI helpers → `components/`** — Buttons, badges, cards in `components/` (no `meta.js`, not selectable by authors).
 
 ---
 
 ## Tailwind CSS v4
 
-Foundation styles in `foundation/src/styles.css`:
+Foundation styles in `styles.css`:
 
 ```css
 @import "tailwindcss";
@@ -1660,10 +1784,10 @@ uniweb add project marketing --from marketing
 pnpm install
 ```
 
-This creates `marketing/foundation/` + `marketing/site/` alongside your existing project. You don't need to build or run it — just read the source files to see how working components handle content, params, theming, and data.
+This creates `marketing/src/` (the foundation, package `marketing-src`) + `marketing/site/` (the site, package `marketing-site`) alongside your existing project. You don't need to build or run it — just read the source files to see how working components handle content, params, theming, and data.
 
 **What to study:**
-- `{name}/foundation/src/sections/` — components with meta.js (content expectations, params, presets)
+- `{name}/src/sections/` — components with meta.js (content expectations, params, presets)
 - `{name}/site/pages/` — real content files showing markdown → component mapping
 - `{name}/site/theme.yml` + `site.yml` — theming and configuration patterns