uniweb 0.11.0 → 0.12.1

package/src/utils/auth.js

@@ -5,6 +5,22 @@
  * User-global (not workspace-local) — you publish as yourself, not as a project.
  *
  * Used by `login`, `publish`, and `deploy` commands.
+ *
+ * Stored shape (auth.json):
+ *   {
+ *     token: string,           // bearer JWT, sent in Authorization: Bearer <token>
+ *     email: string,           // signup_email; permanent, deliverable
+ *     loginName?: string,      // PHP session login_name; immutable per session model
+ *     sub?: string,            // memberId from JWT; permanent, numeric
+ *     namespaces?: string[],   // org handles the user can publish under
+ *     expiresAt?: string       // ISO timestamp; JWT exp claim
+ *   }
+ *
+ * The extra identity fields (loginName, sub, namespaces) are decoded from
+ * the JWT at write time and persisted alongside the token. They're cheap
+ * to derive (HS256 payload is base64url-encoded JSON), but persisting them
+ * means callers don't need to decode the JWT themselves to ask
+ * "who is the user?" — they just `readAuth()`.
  */
 
 import { existsSync } from 'node:fs'
@@ -29,28 +45,88 @@ export function getAuthPath() {
 }
 
 /**
- * Read stored credentials.
- * @returns {Promise<{ token: string, email: string, expiresAt?: string } | null>}
+ * Decode the payload of a JWT. Returns `null` for malformed tokens.
+ * No signature verification — that's the server's job; we just want to
+ * read the claims locally.
+ *
+ * @param {string} token
+ * @returns {Object|null}
+ */
+export function decodeJwtPayload(token) {
+  if (typeof token !== 'string') return null
+  const parts = token.split('.')
+  if (parts.length < 2) return null
+  try {
+    // base64url → base64
+    const b64 = parts[1].replace(/-/g, '+').replace(/_/g, '/')
+    return JSON.parse(Buffer.from(b64, 'base64').toString('utf8'))
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Read stored credentials. If the persisted record predates the
+ * identity-fields plumbing (no loginName/sub/namespaces) but has a
+ * token, derive the missing fields from the JWT in memory so callers
+ * see a consistent shape regardless of write generation.
+ *
+ * @returns {Promise<{ token: string, email: string, loginName?: string, sub?: string, namespaces?: string[], expiresAt?: string } | null>}
  */
 export async function readAuth() {
   const authPath = getAuthPath()
   if (!existsSync(authPath)) return null
 
+  let auth
   try {
-    return JSON.parse(await readFile(authPath, 'utf8'))
+    auth = JSON.parse(await readFile(authPath, 'utf8'))
   } catch {
     return null
   }
+
+  // Backfill identity fields from the JWT for older auth.json files
+  // that were written before this plumbing existed. Read-only — the
+  // file isn't rewritten until the next login.
+  if (auth?.token && (auth.loginName === undefined || auth.sub === undefined || auth.namespaces === undefined)) {
+    const payload = decodeJwtPayload(auth.token)
+    if (payload) {
+      if (auth.loginName === undefined && typeof payload.loginName === 'string') {
+        auth.loginName = payload.loginName
+      }
+      if (auth.sub === undefined && typeof payload.sub === 'string') {
+        auth.sub = payload.sub
+      }
+      if (auth.namespaces === undefined && Array.isArray(payload.namespaces)) {
+        auth.namespaces = payload.namespaces
+      }
+    }
+  }
+
+  return auth
 }
 
 /**
- * Write credentials to storage.
- * @param {{ token: string, email: string, expiresAt?: string }} auth
+ * Write credentials to storage. Decodes the JWT and persists the
+ * identity claims (loginName, sub, namespaces) alongside the token,
+ * so future `readAuth()` calls don't have to decode it themselves.
+ *
+ * @param {{ token: string, email: string, expiresAt?: string }} auth - Caller passes the basics; identity fields are derived.
  */
 export async function writeAuth(auth) {
+  const record = { ...auth }
+
+  if (record.token) {
+    const payload = decodeJwtPayload(record.token)
+    if (payload) {
+      if (typeof payload.loginName === 'string') record.loginName = payload.loginName
+      if (typeof payload.sub === 'string') record.sub = payload.sub
+      if (Array.isArray(payload.namespaces)) record.namespaces = payload.namespaces
+    }
+  }
+
   const dir = getAuthDir()
   await mkdir(dir, { recursive: true })
-  await writeFile(join(dir, 'auth.json'), JSON.stringify(auth, null, 2))
+  await writeFile(join(dir, 'auth.json'), JSON.stringify(record, null, 2))
 }
 
 /**

package/src/utils/names.js

@@ -14,12 +14,19 @@ import { join } from 'node:path'
  * Names that must not be used as package names.
  * - JS module keywords: default, undefined, null, true, false
  * - Node/filesystem: node_modules, package
- * - Common directory names that would cause confusion: src, dist, build
+ * - Common build-output directories: dist, build (would shadow `dist/` /
+ *   `build/` references)
+ *
+ * Note: `src` is NOT reserved. A foundation in `src/` whose package name is
+ * also `src` is the default scaffold pattern — folder name and package name
+ * match. Multi-foundation co-located workspaces still use suffixes
+ * (`<project>-src`) because pnpm requires workspace-unique package names;
+ * that's a real constraint, not aesthetic.
  */
 const RESERVED_NAMES = new Set([
   'default', 'undefined', 'null', 'true', 'false',
   'node_modules', 'package',
-  'src', 'dist', 'build',
+  'dist', 'build',
 ])
 
 /**

package/src/utils/registry.js

@@ -1,20 +1,36 @@
 /**
  * Local Foundation Registry
  *
- * Manages published foundations in .unicloud/registry/.
- * Same on-disk format as scripts/platform/registry.js, so
- * scripts/platform/serve.js can still serve them.
+ * Manages published foundations in .unicloud/registry/. The on-disk
+ * shape mirrors uniweb-edge's registry index (versions as an array of
+ * { version, ... } objects, plus top-level namespace and latest) so
+ * `--local` exercises the same data shape that ships in production.
  *
  * Layout:
  *   .unicloud/
  *     registry/
- *       index.json                  # { "name": { versions: { "1.0.0": { ... } } } }
+ *       index.json                  # see "Index format" below
  *       packages/
  *         name/
  *           1.0.0/
  *             foundation.js
  *             schema.json
  *             assets/...
+ *
+ * Index format:
+ *   {
+ *     "@ns/name": {
+ *       namespace: "ns",
+ *       versions: [
+ *         { version: "1.0.0", publishedAt, publishedBy, ... },
+ *         ...
+ *       ],
+ *       latest: "1.0.0"
+ *     }
+ *   }
+ *
+ *   Legacy entries (versions as an object keyed by version) are migrated
+ *   to this shape on read. The next write persists the new shape.
  */
 
 import { existsSync } from 'node:fs'
@@ -37,7 +53,7 @@ export function getRegistryDir(startDir = process.cwd()) {
 
 /**
  * Sanitize a package name for filesystem use.
- * '@org/pkg' → '@org__pkg'
+ * '@org/pkg' → 'org/pkg'
  * @param {string} name
  * @returns {string}
  */
@@ -46,6 +62,38 @@ function sanitizeName(name) {
   return name.startsWith('@') ? name.slice(1) : name
 }
 
+/**
+ * Parse the namespace out of a scoped package name. '@org/pkg' → 'org';
+ * unscoped → ''.
+ * @param {string} name
+ * @returns {string}
+ */
+function parseNamespace(name) {
+  const m = /^@([a-z0-9_-]+)\//.exec(name)
+  return m ? m[1] : ''
+}
+
+/**
+ * Migrate a legacy index entry (versions as object, no namespace/latest)
+ * to the current shape (versions as array, namespace + latest at top).
+ * Mutates and returns the entry.
+ */
+function normalizeEntry(name, entry) {
+  if (!entry) return entry
+  if (entry.versions && !Array.isArray(entry.versions) && typeof entry.versions === 'object') {
+    entry.versions = Object.entries(entry.versions).map(([version, data]) => ({
+      version,
+      ...data,
+    }))
+  }
+  if (!Array.isArray(entry.versions)) entry.versions = []
+  if (!entry.namespace) entry.namespace = parseNamespace(name)
+  if (!entry.latest && entry.versions.length > 0) {
+    entry.latest = entry.versions[entry.versions.length - 1].version
+  }
+  return entry
+}
+
 /**
  * Local registry — stores published foundations in .unicloud/registry/
  */
@@ -58,7 +106,11 @@ export class LocalRegistry {
 
   async _readIndex() {
     if (!existsSync(this.indexPath)) return {}
-    return JSON.parse(await readFile(this.indexPath, 'utf8'))
+    const raw = JSON.parse(await readFile(this.indexPath, 'utf8'))
+    for (const name of Object.keys(raw)) {
+      normalizeEntry(name, raw[name])
+    }
+    return raw
   }
 
   async _writeIndex(index) {
@@ -74,17 +126,20 @@ export class LocalRegistry {
    */
   async exists(name, version) {
     const index = await this._readIndex()
-    return !!index[name]?.versions?.[version]
+    const versions = index[name]?.versions
+    if (!Array.isArray(versions)) return false
+    return versions.some(v => v.version === version)
   }
 
   /**
-   * Get all published versions for a package.
+   * Get all published versions for a package as an array of
+   * `{ version, publishedAt, ... }` entries (matches uniweb-edge).
    * @param {string} name
-   * @returns {Promise<Object>}
+   * @returns {Promise<Array>}
    */
   async getVersions(name) {
     const index = await this._readIndex()
-    return index[name]?.versions || {}
+    return index[name]?.versions || []
   }
 
   /**
@@ -104,12 +159,26 @@ export class LocalRegistry {
 
     const index = await this._readIndex()
     if (!index[name]) {
-      index[name] = { versions: {} }
+      index[name] = {
+        namespace: parseNamespace(name),
+        versions: [],
+        latest: null,
+      }
     }
-    index[name].versions[version] = {
+
+    const versionEntry = {
+      version,
       publishedAt: new Date().toISOString(),
       ...metadata,
     }
+    const existingIdx = index[name].versions.findIndex(v => v.version === version)
+    if (existingIdx >= 0) {
+      index[name].versions[existingIdx] = versionEntry
+    } else {
+      index[name].versions.push(versionEntry)
+    }
+    index[name].latest = version
+
     await this._writeIndex(index)
   }
 
@@ -165,20 +234,23 @@ export class RemoteRegistry {
   async exists(name, version) {
     try {
       const index = await this._fetchIndex()
-      return !!index[name]?.versions?.[version]
+      const versions = index[name]?.versions
+      if (!Array.isArray(versions)) return false
+      return versions.some(v => v.version === version)
     } catch {
       return false
     }
   }
 
   /**
-   * Get all published versions for a package.
+   * Get all published versions for a package as an array of
+   * `{ version, publishedAt, ... }` entries.
    * @param {string} name
-   * @returns {Promise<Object>}
+   * @returns {Promise<Array>}
    */
   async getVersions(name) {
     const index = await this._fetchIndex()
-    return index[name]?.versions || {}
+    return index[name]?.versions || []
   }
 
   /**

package/src/utils/scaffold.js

@@ -94,12 +94,23 @@ export async function scaffoldSite(targetDir, context, options = {}) {
  * Apply content overlay from a content directory onto a target
  *
  * Content files overwrite scaffolded defaults. Structural files
- * (package.json, vite.config.js, main.js, index.html) are NOT overwritten.
+ * (package.json, vite.config.js, entry.js, index.html) are NOT overwritten.
+ *
+ * Note: a foundation's `main.js` (the user-authored declarations file) is
+ * NOT structural — templates legitimately provide their own `main.js` to
+ * override the empty scaffold default. The site's `entry.js` (formerly
+ * `main.js`) IS structural — the boilerplate `start({...})` is identical
+ * across all sites and shouldn't be overwritten.
  *
  * @param {string} contentDir - Source content directory (e.g., starter/foundation/)
  * @param {string} targetDir - Target directory to overlay onto
  * @param {Object} context - Handlebars context for .hbs files
  * @param {Object} [options] - Processing options
+ * @param {Object} [options.renames] - Top-level filename remapping
+ *   (e.g. `{ 'foundation.js': 'main.js' }`). Applied only at depth 0
+ *   so renames don't accidentally rewrite same-named files in nested
+ *   directories. Used to migrate legacy `foundation/foundation.js`
+ *   templates onto the new flat `src/main.js` layout.
  */
 export async function applyContent(contentDir, targetDir, context, options = {}) {
   if (!existsSync(contentDir)) return
@@ -110,7 +121,7 @@ export async function applyContent(contentDir, targetDir, context, options = {})
   const STRUCTURAL_FILES = new Set([
     'package.json',
     'vite.config.js',
-    'main.js',
+    'entry.js',
     'index.html',
     '.gitignore',
   ])
@@ -121,29 +132,41 @@ export async function applyContent(contentDir, targetDir, context, options = {})
     'site.yml': ['name', 'foundation'],
   }
 
-  await copyContentRecursive(contentDir, targetDir, context, STRUCTURAL_FILES, MERGE_FILES, options)
+  await copyContentRecursive(contentDir, targetDir, context, STRUCTURAL_FILES, MERGE_FILES, options, 0)
 }
 
 /**
- * Recursively copy content files, skipping structural files
+ * Recursively copy content files, skipping structural files.
+ *
+ * `depth` is tracked so the `renames` map (passed via options) only
+ * applies at depth 0 — the top of the content directory. Without this
+ * guard, a rename like `foundation.js → main.js` would also rewrite a
+ * nested `sections/foo/foundation.js` if one existed, which is not the
+ * intent.
  */
-async function copyContentRecursive(sourceDir, targetDir, context, structuralFiles, mergeFiles, options) {
+async function copyContentRecursive(sourceDir, targetDir, context, structuralFiles, mergeFiles, options, depth = 0) {
   await fs.mkdir(targetDir, { recursive: true })
 
   const entries = readdirSync(sourceDir, { withFileTypes: true })
+  const renames = (depth === 0 && options.renames) || null
 
   for (const entry of entries) {
     const sourcePath = join(sourceDir, entry.name)
 
     if (entry.isDirectory()) {
       const targetSubDir = join(targetDir, entry.name)
-      await copyContentRecursive(sourcePath, targetSubDir, context, structuralFiles, mergeFiles, options)
+      await copyContentRecursive(sourcePath, targetSubDir, context, structuralFiles, mergeFiles, options, depth + 1)
     } else {
       // Determine the output filename (strip .hbs extension)
-      const outputName = entry.name.endsWith('.hbs')
+      let outputName = entry.name.endsWith('.hbs')
         ? entry.name.slice(0, -4)
         : entry.name
 
+      // Apply top-level rename (e.g. legacy `foundation.js` → `main.js`)
+      if (renames && Object.prototype.hasOwnProperty.call(renames, outputName)) {
+        outputName = renames[outputName]
+      }
+
       // Skip structural files
       if (structuralFiles.has(outputName)) continue
 
@@ -184,8 +207,17 @@ async function copyContentRecursive(sourceDir, targetDir, context, structuralFil
         for (const key of preserveKeys) {
           if (existing[key] === undefined) continue
           const baseLine = matchTopLevelLine(existingContent, key)
-          if (baseLine) {
+          if (!baseLine) continue
+          // If the new content carries the key, replace its line with
+          // the scaffolded value (preserving the user's project/foundation
+          // choice). Otherwise insert the line — older content templates
+          // (notably `docs/site/site.yml.hbs`) omit `foundation:` entirely,
+          // and dropping it leaves the site without a foundation ref so
+          // the entry's `import '#foundation/styles'` fails at build time.
+          if (matchTopLevelLine(merged, key)) {
             merged = replaceTopLevelLine(merged, key, baseLine)
+          } else {
+            merged = insertTopLevelLine(merged, baseLine)
           }
         }
 
@@ -207,14 +239,20 @@ async function copyContentRecursive(sourceDir, targetDir, context, structuralFil
 /**
  * Apply the built-in starter content
  *
+ * The starter ships its foundation content under `cli/starter/foundation/`
+ * (a description of the *kind* of content), and is applied into whatever
+ * folder the workspace uses for the foundation package — which is `src/`
+ * in the current single-foundation layout, not `foundation/`. Callers
+ * can override via options when scaffolding multi-foundation workspaces.
+ *
  * @param {string} projectDir - Root project directory
  * @param {Object} context - Template context
  * @param {Object} [options] - Processing options
- * @param {string} [options.foundationDir] - Foundation directory name (default: 'foundation')
+ * @param {string} [options.foundationDir] - Foundation directory name (default: 'src')
  * @param {string} [options.siteDir] - Site directory name (default: 'site')
  */
 export async function applyStarter(projectDir, context, options = {}) {
-  const foundationDir = options.foundationDir || 'foundation'
+  const foundationDir = options.foundationDir || 'src'
   const siteDir = options.siteDir || 'site'
 
   // Apply foundation starter content
@@ -260,6 +298,25 @@ function replaceTopLevelLine(content, key, replacement) {
   )
 }
 
+/**
+ * Insert a top-level YAML line into a content string.
+ *
+ * Used by the merge path when the content template omits a key that
+ * the scaffolded base file declared (e.g. an older `site.yml.hbs` with
+ * no `foundation:` line). Inserts immediately after the `name:` line
+ * if one exists — that's the conventional position for site
+ * configuration — and otherwise prepends to the file. The original
+ * trailing newline (or lack thereof) of the file is preserved.
+ */
+function insertTopLevelLine(content, line) {
+  const nameMatch = content.match(/^name:.*$/m)
+  if (nameMatch) {
+    const idx = nameMatch.index + nameMatch[0].length
+    return content.slice(0, idx) + '\n' + line + content.slice(idx)
+  }
+  return line + '\n' + content
+}
+
 /**
  * Resolve a dependency version string from a template.json entry.
  *

package/src/utils/workspace.js

@@ -10,6 +10,7 @@ import { existsSync, readdirSync, readFileSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
 import { resolve, dirname, join } from 'node:path'
 import yaml from 'js-yaml'
+import { classifyPackage as classifyPackageSync } from '@uniweb/build'
 
 /**
  * Check if a directory is a workspace root.
@@ -124,38 +125,17 @@ export async function getWorkspacePackages(workspaceRoot) {
 }
 
 /**
- * Classify a package as foundation, site, or unknown
+ * Classify a package as foundation, site, or unknown.
  *
- * Classification logic:
- * - Site: has @uniweb/runtime in dependencies (checked first, more specific)
- * - Foundation: has @uniweb/build in devDependencies but NOT @uniweb/runtime
- *
- * Note: Sites also have @uniweb/build for the Vite plugin, so we check
- * for @uniweb/runtime first to distinguish them.
+ * Re-exports the canonical (sync) classifier from @uniweb/build, kept
+ * async-shaped here so existing call sites continue to work without an
+ * await-removal sweep. New code should import directly from @uniweb/build.
  *
  * @param {string} packagePath - Full path to package directory
  * @returns {Promise<'foundation'|'site'|null>}
  */
 export async function classifyPackage(packagePath) {
-  const pkgJsonPath = join(packagePath, 'package.json')
-  if (!existsSync(pkgJsonPath)) return null
-
-  try {
-    const pkg = JSON.parse(await readFile(pkgJsonPath, 'utf-8'))
-
-    // Site: has @uniweb/runtime in dependencies (check first - more specific)
-    if (pkg.dependencies?.['@uniweb/runtime']) {
-      return 'site'
-    }
-    // Foundation: has @uniweb/build in devDependencies (and not a site)
-    if (pkg.devDependencies?.['@uniweb/build']) {
-      return 'foundation'
-    }
-  } catch {
-    // Ignore parse errors
-  }
-
-  return null
+  return classifyPackageSync(packagePath)
 }
 
 /**
@@ -165,16 +145,7 @@ export async function classifyPackage(packagePath) {
  */
 export async function findFoundations(workspaceRoot) {
   const packages = await getWorkspacePackages(workspaceRoot)
-  const foundations = []
-
-  for (const pkg of packages) {
-    const fullPath = join(workspaceRoot, pkg)
-    if ((await classifyPackage(fullPath)) === 'foundation') {
-      foundations.push(pkg)
-    }
-  }
-
-  return foundations
+  return packages.filter(pkg => classifyPackageSync(join(workspaceRoot, pkg)) === 'foundation')
 }
 
 /**
@@ -184,16 +155,7 @@ export async function findFoundations(workspaceRoot) {
  */
 export async function findSites(workspaceRoot) {
   const packages = await getWorkspacePackages(workspaceRoot)
-  const sites = []
-
-  for (const pkg of packages) {
-    const fullPath = join(workspaceRoot, pkg)
-    if ((await classifyPackage(fullPath)) === 'site') {
-      sites.push(pkg)
-    }
-  }
-
-  return sites
+  return packages.filter(pkg => classifyPackageSync(join(workspaceRoot, pkg)) === 'site')
 }
 
 /**

package/starter/site/pages/home/1-welcome.md.hbs

@@ -8,7 +8,7 @@ align: center
 
 ## Your Uniweb project is ready
 
-This is a minimal starting point for your Uniweb project. Edit the content in `site/pages/` and build section types in `foundation/src/sections/`.
+This is a minimal starting point for your Uniweb project. Edit the content in `site/pages/` and build section types in `src/sections/`.
 
 [About](/about)
 [Documentation](https://github.com/uniweb)

package/templates/foundation/{src/foundation.js.hbs → main.js.hbs}

@@ -19,7 +19,7 @@ export default {
 {{else}}
 export default {
   // ─── Layout ─────────────────────────────────────────────────────────────────
-  // Create layouts in src/layouts/MyLayout/index.jsx (auto-discovered).
+  // Create layouts in layouts/MyLayout/index.jsx (auto-discovered).
   // defaultLayout: 'MyLayout',
 
   // ─── Props ──────────────────────────────────────────────────────────────────

package/templates/foundation/package.json.hbs

@@ -3,18 +3,18 @@
   "version": "0.1.0",
   "description": "{{projectName}} foundation",
   "type": "module",
-  "main": "./src/_entry.generated.js",
+  "main": "./_entry.generated.js",
   "exports": {
-    ".": "./src/_entry.generated.js",
-    "./styles": "./src/styles.css",
+    ".": "./_entry.generated.js",
+    "./styles": "./styles.css",
     "./dist": "./dist/foundation.js",
     "./dist/styles": "./dist/assets/style.css"
   },
   "imports": {
-    "#components/*": "./src/components/*",
-    "#utils/*": "./src/utils/*"
+    "#components/*": "./components/*",
+    "#utils/*": "./utils/*"
   },
-  "files": ["dist", "src"],
+  "files": ["dist", "sections", "components", "layouts", "utils", "main.js", "styles.css", "_entry.generated.js"],
   "scripts": {
     "dev": "vite",
     "build": "uniweb build",

package/templates/foundation/{src/styles.css → styles.css}

@@ -3,4 +3,4 @@
 
 @source "./sections/**/*.{js,jsx}";
 @source "./layouts/**/*.{js,jsx}";
-@source "../node_modules/@uniweb/kit/src/**/*.{js,jsx}";
+@source "./node_modules/@uniweb/kit/src/**/*.{js,jsx}";

package/templates/site/index.html.hbs

@@ -8,6 +8,6 @@
   </head>
   <body>
     <div id="root"></div>
-    <script type="module" src="/main.js"></script>
+    <script type="module" src="/entry.js"></script>
   </body>
 </html>

package/templates/site/theme.yml

@@ -93,7 +93,7 @@ colors:
 
 # ─── Foundation Variables ──────────────────────────────────────────────────────
 # Override variables declared by the foundation (e.g., header-height, max-width).
-# Available variables depend on the foundation — check its foundation.js.
+# Available variables depend on the foundation — check its main.js.
 
 # vars:
 #   header-height: 5rem

package/templates/workspace/README.md.hbs

@@ -8,10 +8,10 @@ A website built with [Uniweb](https://github.com/uniweb/cli) — a component web
 
 ```
 {{projectName}}/
-├── foundation/          # React component library
-│   ├── src/
-│   │   ├── sections/    # Section types (selectable by content authors)
-│   │   └── styles.css   # Tailwind CSS v4 theme
+├── src/                 # Foundation package (the site's source code; pkg name: src)
+│   ├── sections/        # Section types (selectable by content authors)
+│   ├── styles.css       # Tailwind CSS v4 theme
+│   ├── main.js          # Foundation declarations (vars, defaultLayout, props)
 │   └── vite.config.js   # defineFoundationConfig()
 │
 ├── site/                # Content (markdown)
@@ -19,12 +19,14 @@ A website built with [Uniweb](https://github.com/uniweb/cli) — a component web
 │   │   └── home/
 │   │       ├── page.yml
 │   │       └── 1-welcome.md
-│   ├── site.yml         # Site configuration
+│   ├── site.yml         # Site configuration (foundation: src)
 │   └── vite.config.js   # defineSiteConfig()
 │
 └── AGENTS.md            # Developer guide (human + AI)
 ```
 
+A site is pure content. A foundation is the site's source code — that's why it lives in `src/`.
+
 ## Content Authoring
 
 Content lives in markdown files under `site/pages/`:
@@ -46,10 +48,10 @@ Your content here.
 
 ## Component Development
 
-Section types live in `foundation/src/sections/`. Each is a folder with an `index.jsx` and a `meta.js`:
+Section types live in `src/sections/`. Each is a folder with an `index.jsx` and a `meta.js`:
 
 ```jsx
-// foundation/src/sections/Hero/index.jsx
+// src/sections/Hero/index.jsx
 import { H1, P } from '@uniweb/kit'
 
 export default function Hero({ content }) {