uniweb 0.12.3 → 0.12.5

package/README.md

@@ -14,8 +14,8 @@ The interactive prompt asks for a project name and template. Pick one, then:
 
 ```bash
 cd my-project
-npm install
-npm run dev
+pnpm install  # or npm install
+pnpm dev      # or npm run dev
 ```
 
 Edit files in `site/pages/` and `src/sections/` to see changes instantly.
@@ -46,17 +46,17 @@ Or skip the interactive prompt:
 pnpm create uniweb my-site --template docs
 ```
 
-### Development Commands
+### Local Scripts
 
 Run these from the **project root**:
 
 ```bash
-npm run dev        # Start development server
-npm run build      # Build foundation + site for production
-npm run preview    # Preview the production build
+pnpm dev        # Start development server
+pnpm build      # Build foundation + site for production
+pnpm preview    # Preview the production build
 ```
 
-The `build` command outputs to `site/dist/`. With pre-rendering enabled (the default for official templates), you get static HTML files ready to deploy anywhere.
+The `build` command outputs to `site/dist/`. With pre-rendering enabled (the default for official templates), you get static HTML files ready to deploy anywhere. For the actual deploy step (and the `uniweb publish` / `uniweb deploy` commands), see [Deployment](#deployment) below.
 
 ## What You Get
 
@@ -243,14 +243,13 @@ The parser extracts semantic elements from markdown—`title` from the first hea
 
 ## Foundations Are Portable
 
-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.
+The `src/` folder (your project's foundation) ships with your project as a convenience, but a foundation is a dynamically linked module (DML) with no dependency on any specific site. Sites reference foundations by configuration, not by folder proximity.
 
-**Three ways to use a foundation:**
+**Two ways to use a foundation:**
 
 | Mode             | How it works                       | Best for                                           |
 | ---------------- | ---------------------------------- | -------------------------------------------------- |
 | **Local folder** | Foundation lives in your workspace | Developing site and components together            |
-| **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 `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.
@@ -259,7 +258,7 @@ You can delete the `src/` folder entirely and point your site at a published fou
 
 _Site-first_ — You're building a website. The foundation is your component library, co-developed with the site. This is the common case.
 
-_Foundation-first_ — You're building a component system. The site is a test harness with sample content. The real sites live elsewhere—other repositories, other teams, or managed on [hub.uniweb.app](https://hub.uniweb.app). Use `uniweb add site` to add multiple test sites exercising a shared foundation.
+_Foundation-first_ — You're building a component system. The site is a test harness with sample content. The real sites live elsewhere—other repositories, other teams, or managed on [uniweb.app](https://uniweb.app). Use `uniweb add site` to add multiple test sites exercising a shared foundation.
 
 ## Growing Your Project
 
@@ -301,14 +300,25 @@ The structure you start with scales without rewrites:
 
 1. **Single project** — One site, one foundation. Develop and deploy together. Most projects stay here.
 
-2. **Published foundation** — Release your foundation as an npm package or to [hub.uniweb.app](https://hub.uniweb.app). Other sites can use it without copying code.
+2. **Published foundation** — Release your foundation as a dynamically linked module to [uniweb.app](https://uniweb.app). Other sites can use it without copying code.
 
 3. **Multiple sites** — Several sites share one foundation. Update components once, every site benefits.
 
-4. **Platform-managed sites** — Sites built on [hub.uniweb.app](https://hub.uniweb.app) with visual editing tools can use your foundation. You develop components locally; content teams work in the browser.
+4. **Platform-managed sites** — Sites built on [uniweb.app](https://uniweb.app) with visual editing tools can use your foundation. You develop components locally; content teams work in the browser.
 
 Start with local files deployed anywhere. The same foundation works across all these scenarios.
 
+## Deployment
+
+A Uniweb project produces two artifacts — a **site** (content) and a **foundation** (code) — and they don't have to ship together. That opens up deployment options other frameworks can't express:
+
+- **Bundled mode** — site and foundation built into one self-contained `dist/`, deployed to any static host.
+- **Linked mode** — the foundation lives in any host and the site in any other host; different sites can dynamically link with the same foundation. Update the foundation, every site picks it up — no site rebuilds.
+
+Two verbs handle it: `uniweb publish` sends a foundation to a registry, `uniweb deploy` sends a site to a host. Most projects start bundled (one command, one destination) and grow into linked mode by changing one line in `site.yml`. Mix providers freely — foundation on GitHub Pages, site on Vercel; or use Uniweb's registry + hosting for propagation, gated rollouts, and edge SSR.
+
+→ **[Deploying](https://github.com/uniweb/docs/blob/main/development/deploying.md)** — the full menu: bundled vs linked, the two-verb model, one-foundation-many-sites, optimized hosting on the Uniweb platform, and recipes for other hosting services.
+
 ---
 
 ## Documentation
@@ -331,7 +341,7 @@ Full documentation is available at **[github.com/uniweb/docs](https://github.com
 | Site Configuration | [site.yml reference](https://github.com/uniweb/docs/blob/main/reference/site-configuration.md) |
 | CLI Commands       | [create, add, build, docs, doctor, i18n](https://github.com/uniweb/docs/blob/main/reference/cli-commands.md) |
 | Templates          | [Built-in, official, and external templates](https://github.com/uniweb/docs/blob/main/getting-started/templates.md) |
-| Deployment         | [Vercel, Netlify, Cloudflare, and more](https://github.com/uniweb/docs/blob/main/reference/deployment.md) |
+| Deployment         | [Two artifacts, two verbs — bundled, linked, and per-host recipes](https://github.com/uniweb/docs/blob/main/development/deploying.md) |
 
 ---
 
@@ -387,7 +397,7 @@ A default project has two packages, listed in both `pnpm-workspace.yaml` and `pa
 ```yaml
 # pnpm-workspace.yaml
 packages:
-  - foundation
+  - src
   - site
 ```
 
@@ -395,20 +405,20 @@ In `package.json` (for npm compatibility):
 
 ```json
 {
-  "workspaces": ["foundation", "site"]
+  "workspaces": ["src", "site"]
 }
 ```
 
-When you `add` more packages, the CLI adds the appropriate globs to both files automatically:
+When you `add` more packages, the CLI adds the appropriate workspaces automatically:
 
 ```yaml
-# After: uniweb add foundation blog → adds foundations/*
-# After: uniweb add extension effects → adds extensions/*
+# After: uniweb add site marketing/blog
+# After: uniweb add foundation marketing/blogger
 packages:
-  - foundation
+  - src
   - site
-  - foundations/*
-  - extensions/*
+  - marketing/blog
+  - marketing/blogger
 ```
 
 ## FAQ

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.12.3",
+  "version": "0.12.5",
   "description": "Create structured Vite + React sites with content/code separation",
   "type": "module",
   "bin": {
@@ -41,12 +41,12 @@
     "js-yaml": "^4.1.0",
     "prompts": "^2.4.2",
     "tar": "^7.0.0",
+    "@uniweb/runtime": "0.8.10",
     "@uniweb/core": "0.7.9",
-    "@uniweb/kit": "0.9.9",
-    "@uniweb/runtime": "0.8.10"
+    "@uniweb/kit": "0.9.9"
   },
   "peerDependencies": {
-    "@uniweb/build": "0.13.2",
+    "@uniweb/build": "0.13.3",
     "@uniweb/content-reader": "1.1.9",
     "@uniweb/semantic-parser": "1.1.16"
   },

package/src/commands/add.js

@@ -196,7 +196,9 @@ async function addFoundation(rootDir, projectName, opts, pm = 'pnpm') {
   // both. Format validation runs on the derived package name below, not
   // on the raw input — slashes in the input are intentional path syntax.
   const FOUNDATION_KIND = { defaultDir: 'src', defaultPkg: 'src', projectSub: 'src' }
-  const { relativePath, packageName } = resolvePlacement(rootDir, name, opts, FOUNDATION_KIND)
+  const placement = resolvePlacement(rootDir, name, opts, FOUNDATION_KIND)
+  const { relativePath } = placement
+  let { packageName } = placement
   const fullPath = join(rootDir, relativePath)
 
   // Validate the derived package name (format + reserved-name check). The
@@ -222,11 +224,33 @@ async function addFoundation(rootDir, projectName, opts, pm = 'pnpm') {
 
   // Collision check 2: a package with the same name already exists somewhere
   // in the workspace.
+  //
+  // Cross-role collisions auto-resolve. If a *site* already owns this name,
+  // suffix the foundation with `-src` (matching the `add project` and
+  // `add extension` precedents). The site keeps its name; the foundation
+  // gets a self-documenting suffix that says "this is the source code for
+  // the site that owns this name." Same-role collisions stay an error —
+  // two foundations with the same name is a real "be more specific"
+  // situation, not a disambiguation case.
   if (existingNames.has(packageName)) {
-    error(`Cannot create foundation: a package named ${colors.bright}${packageName}${colors.reset} already exists in this workspace.`)
-    log(`Pick a different name:`)
-    log(`  ${colors.cyan}${getCliPrefix()} add foundation <other-name>${colors.reset}`)
-    process.exit(1)
+    const sites = await discoverSites(rootDir)
+    const isSiteCollision = sites.some(s => s.name === packageName)
+    if (isSiteCollision) {
+      const suffixed = `${packageName}-src`
+      if (existingNames.has(suffixed)) {
+        error(`Cannot create foundation: both ${colors.bright}${packageName}${colors.reset} and ${colors.bright}${suffixed}${colors.reset} are taken in this workspace.`)
+        log(`Pick a different name:`)
+        log(`  ${colors.cyan}${getCliPrefix()} add foundation <other-name>${colors.reset}`)
+        process.exit(1)
+      }
+      info(`Package "${packageName}" is taken by a site; using "${suffixed}" for this foundation.`)
+      packageName = suffixed
+    } else {
+      error(`Cannot create foundation: a foundation named ${colors.bright}${packageName}${colors.reset} already exists in this workspace.`)
+      log(`Pick a different name:`)
+      log(`  ${colors.cyan}${getCliPrefix()} add foundation <other-name>${colors.reset}`)
+      process.exit(1)
+    }
   }
 
   // Scaffold
@@ -266,7 +290,9 @@ async function addSite(rootDir, projectName, opts, pm = 'pnpm') {
 
   // Resolve placement first (path + package name); see notes in addFoundation.
   const SITE_KIND = { defaultDir: 'site', defaultPkg: 'site', projectSub: 'site' }
-  const { relativePath, packageName: siteName } = resolvePlacement(rootDir, name, opts, SITE_KIND)
+  const placement = resolvePlacement(rootDir, name, opts, SITE_KIND)
+  const { relativePath } = placement
+  let siteName = placement.packageName
   const fullPath = join(rootDir, relativePath)
 
   // Validate the package name (skip for the auto-derived 'site' default).
@@ -288,12 +314,28 @@ async function addSite(rootDir, projectName, opts, pm = 'pnpm') {
     process.exit(1)
   }
 
-  // Collision check 2: package name already in workspace.
+  // Collision check 2: cross-role collisions auto-resolve with `-site`
+  // suffix; same-role collisions error. See the symmetric logic in
+  // addFoundation for the rationale.
   if (existingNames.has(siteName)) {
-    error(`Cannot create site: a package named ${colors.bright}${siteName}${colors.reset} already exists in this workspace.`)
-    log(`Pick a different name:`)
-    log(`  ${colors.cyan}${getCliPrefix()} add site <other-name>${colors.reset}`)
-    process.exit(1)
+    const foundations = await discoverFoundations(rootDir)
+    const isFoundationCollision = foundations.some(f => f.name === siteName)
+    if (isFoundationCollision) {
+      const suffixed = `${siteName}-site`
+      if (existingNames.has(suffixed)) {
+        error(`Cannot create site: both ${colors.bright}${siteName}${colors.reset} and ${colors.bright}${suffixed}${colors.reset} are taken in this workspace.`)
+        log(`Pick a different name:`)
+        log(`  ${colors.cyan}${getCliPrefix()} add site <other-name>${colors.reset}`)
+        process.exit(1)
+      }
+      info(`Package "${siteName}" is taken by a foundation; using "${suffixed}" for this site.`)
+      siteName = suffixed
+    } else {
+      error(`Cannot create site: a site named ${colors.bright}${siteName}${colors.reset} already exists in this workspace.`)
+      log(`Pick a different name:`)
+      log(`  ${colors.cyan}${getCliPrefix()} add site <other-name>${colors.reset}`)
+      process.exit(1)
+    }
   }
 
   // Resolve foundation
@@ -430,14 +472,45 @@ async function addExtension(rootDir, projectName, opts, pm = 'pnpm') {
   // Update workspace globs
   await addWorkspaceGlob(rootDir, 'extensions/*')
 
-  // Wire extension to site if specified (or only one site exists)
+  // Wire extension to site:
+  //   - --site <name>: explicit, wire it.
+  //   - exactly one site: silent auto-wire (intent is unambiguous).
+  //   - multiple sites, interactive: single-select prompt (extensions are
+  //     typically per-site specialization — pick which site).
+  //   - multiple sites, non-interactive: don't wire silently. Print a
+  //     warning so the user/agent knows wiring is pending, and exit 0
+  //     (the extension itself is fine).
+  //   - no sites: print a note and exit 0.
   let wiredSite = null
+  let unwiredReason = null
   if (opts.site) {
     wiredSite = await wireExtensionToSite(rootDir, opts.site, name, target)
   } else {
     const sites = await discoverSites(rootDir)
     if (sites.length === 1) {
       wiredSite = await wireExtensionToSite(rootDir, sites[0].name, name, target)
+    } else if (sites.length > 1) {
+      if (isNonInteractive(process.argv)) {
+        unwiredReason = `Multiple sites in workspace; extension not wired. Re-run with --site <name>, or edit <site>/site.yml::extensions: manually.`
+      } else {
+        const sortedSites = [...sites].sort((a, b) => a.name.localeCompare(b.name))
+        const response = await prompts({
+          type: 'select',
+          name: 'site',
+          message: 'Which site is this extension for?',
+          choices: sortedSites.map(s => ({ title: s.name, description: s.path, value: s.name })),
+        }, {
+          onCancel: () => {
+            log('\nCancelled.')
+            process.exit(0)
+          },
+        })
+        if (response.site) {
+          wiredSite = await wireExtensionToSite(rootDir, response.site, name, target)
+        }
+      }
+    } else {
+      unwiredReason = `No site in this workspace yet. Wire this extension into a site's site.yml::extensions: once you create one.`
     }
   }
 
@@ -450,6 +523,9 @@ async function addExtension(rootDir, projectName, opts, pm = 'pnpm') {
     msg += ` → wired to site '${wiredSite}'`
   }
   success(msg)
+  if (unwiredReason) {
+    log(`  ${colors.yellow}⚠ ${unwiredReason}${colors.reset}`)
+  }
   log('')
   log(`Next: ${colors.cyan}${installCmd(pm)}${colors.reset}`)
 }

package/src/commands/build.js

@@ -1,13 +1,33 @@
 /**
  * Build Command
  *
- * Builds foundations with schema generation.
+ * Builds foundations with schema generation, or sites in either link or
+ * bundle mode.
+ *
+ * Site build modes:
+ *   --bundle (default for sites)
+ *     Full vite + post-vite pipeline. Produces a static-host JS bundle
+ *     (`dist/index.html`, `dist/entry.js`, `_importmap/*`, `_pages/*` for
+ *     split mode, sitemap/robots/search-index, prerendered HTML when
+ *     configured). Targets non-Uniweb hosts (Netlify, Vercel, GitHub
+ *     Pages) and the future Uniweb bundled-mode hosting.
+ *
+ *   --link
+ *     Data-only pipeline. No vite. Emits ONLY what the Uniweb-edge
+ *     deploy needs: `dist/site-content.json` (with full sections),
+ *     `dist/<lang>/site-content.json` per non-default locale,
+ *     `dist/data/*.json` (collections), and `dist/assets/<media>` (images,
+ *     fonts, video posters). Worker generates HTML at request time using
+ *     its own runtime + the foundation served from the registry — the
+ *     site's JS bundle is dead weight on this path.
  *
  * Usage:
- *   uniweb build                    # Build current directory
+ *   uniweb build                    # Build current directory (sites default to --bundle)
  *   uniweb build --target foundation # Explicitly build as foundation
  *   uniweb build --target site       # Explicitly build as site
- *   uniweb build --prerender         # Build site + pre-render to static HTML (SSG)
+ *   uniweb build --link              # Site: link-mode (data only, no vite)
+ *   uniweb build --bundle            # Site: bundle-mode (full pipeline, today's behavior)
+ *   uniweb build --prerender         # Bundle-mode site + SSG (static HTML)
  */
 
 import { existsSync, readFileSync } from 'node:fs'
@@ -375,6 +395,136 @@ function resolveFoundationDir(projectDir, siteConfig) {
   return singleFoundationDir
 }
 
+/**
+ * Build a site in link mode — data only, no vite.
+ *
+ * Emits exactly what `uniweb deploy` ships to Uniweb-edge:
+ *   dist/site-content.json (full sections inlined)
+ *   dist/<lang>/site-content.json per non-default locale
+ *   dist/data/<collection>.json (+ per-record files for `deferred:`)
+ *   dist/assets/<media> (processed images, video posters, PDF thumbnails)
+ *
+ * Does NOT emit HTML, JS, CSS, source maps, _importmap chunks, or
+ * static-host extras (sitemap, robots, search-index, _pages/*) — none
+ * of these are consumed on the link-mode deploy path. The worker
+ * generates HTML at request time and re-derives split-content per-page
+ * files from the full payload it receives.
+ *
+ * The `buildLocalizedContent` step is the same call bundle mode makes
+ * post-vite, so multi-locale sites get identical per-locale outputs in
+ * either mode. Collection translation (`buildLocalizedCollections`)
+ * also runs here so deploy ships translated collection JSONs.
+ *
+ * Bug surfaced + fixed by routing deploy through this path: the bundle
+ * pipeline's prerender step rewrites `dist/site-content.json` into a
+ * lightweight manifest (sections stripped) when split-content is active,
+ * and deploy was reading that stripped version, causing the worker to
+ * mis-detect split and serve blank pages. Link mode skips prerender
+ * entirely; `dist/site-content.json` keeps full sections; the worker
+ * splits correctly. See `kb/framework/build/workspace-ergonomics.md`.
+ */
+async function buildSiteLink(projectDir, options = {}) {
+  const { siteConfig = null } = options
+
+  info('Building site (link mode)...')
+
+  const { buildSiteData } = await import('@uniweb/build/site')
+  const distDir = join(projectDir, 'dist')
+
+  // Resolve the local foundation path so collectSiteContent can pick up
+  // theme variable defaults from `foundation.js::theme.vars`. When the
+  // foundation is purely a registry ref (no local sibling), this stays
+  // null and theme defaults come from theme.yml only.
+  const foundationDir = await resolveFoundationDirForSite(projectDir, siteConfig).catch(() => null)
+
+  await buildSiteData({
+    siteRoot: projectDir,
+    distDir,
+    foundationPath: foundationDir,
+    assets: siteConfig?.build?.assets || {},
+  })
+  success(`Wrote ${join('dist', 'site-content.json')}`)
+
+  // Per-locale variants — same call bundle mode makes post-vite. Both
+  // modes produce identical `dist/<lang>/site-content.json` outputs so
+  // the deploy CLI walks the same path shape regardless of mode.
+  const i18nConfig = await loadI18nConfig(projectDir, siteConfig)
+  if (i18nConfig && i18nConfig.locales.length > 0) {
+    log('')
+    info(`Building localized content for: ${i18nConfig.locales.join(', ')}`)
+    try {
+      const outputs = await buildLocalizedContent(projectDir, i18nConfig)
+      success(`Generated ${Object.keys(outputs).length} locale(s)`)
+      for (const [locale] of Object.entries(outputs)) {
+        log(`  ${colors.dim}dist/${locale}/site-content.json${colors.reset}`)
+      }
+
+      // Collection translations — optional; don't fail the build if
+      // missing. Bundle mode does the same.
+      try {
+        const { buildLocalizedCollections } = await import('@uniweb/build/i18n')
+        const collectionOutputs = await buildLocalizedCollections(projectDir, {
+          locales: i18nConfig.locales,
+          outputDir: distDir,
+          collectionsLocalesDir: join(projectDir, i18nConfig.localesDir, 'collections'),
+        })
+        const collectionCount = Object.values(collectionOutputs).reduce(
+          (sum, localeOutputs) => sum + Object.keys(localeOutputs).length,
+          0
+        )
+        if (collectionCount > 0) {
+          success(`Translated collections for ${Object.keys(collectionOutputs).length} locale(s)`)
+        }
+      } catch (err) {
+        if (process.env.DEBUG) console.error('Collection translation:', err.message)
+      }
+    } catch (err) {
+      error(`i18n build failed: ${err.message}`)
+      if (process.env.DEBUG) console.error(err.stack)
+      log(`${colors.yellow}Continuing without localized content${colors.reset}`)
+    }
+  }
+
+  log('')
+  log(`${colors.green}${colors.bright}Build complete (link mode)${colors.reset}`)
+}
+
+/**
+ * Best-effort resolution of the local foundation directory for a site,
+ * used by `buildSiteLink` to pass `foundationPath` to the data pipeline.
+ *
+ * Mirrors a subset of `@uniweb/build`'s `detectFoundationType` semantics:
+ * when the site declares `foundation: <name>` and a sibling/file: dep
+ * resolves to a local foundation, return its path. When the foundation
+ * is a registry ref or URL, return null (data pipeline still works
+ * without a local foundation; theme defaults just come from theme.yml).
+ */
+async function resolveFoundationDirForSite(siteDir, siteConfig) {
+  const cfg = siteConfig || readSiteConfig(siteDir)
+  const foundation = cfg?.foundation
+  if (!foundation || typeof foundation !== 'string') return null
+  // Registry ref or URL — no local foundation.
+  if (/^@[a-z0-9_-]+\/[a-z0-9_-]+@/.test(foundation)) return null
+  if (/^~[A-Za-z0-9_-]+\/[a-z0-9_-]+@/.test(foundation)) return null
+  if (foundation.startsWith('http://') || foundation.startsWith('https://')) return null
+
+  // Workspace sibling.
+  const sibling = resolve(siteDir, '..', foundation)
+  if (existsSync(sibling)) return sibling
+
+  // file: dep declared in package.json.
+  try {
+    const pkg = JSON.parse(readFileSync(join(siteDir, 'package.json'), 'utf-8'))
+    const dep = pkg.dependencies?.[foundation]
+    if (typeof dep === 'string' && dep.startsWith('file:')) {
+      const filePath = resolve(siteDir, dep.slice(5))
+      if (existsSync(filePath)) return filePath
+    }
+  } catch { /* no package.json or malformed — fall through */ }
+
+  return null
+}
+
 /**
  * Build a site
  */
@@ -650,13 +800,24 @@ export async function build(args = []) {
     }
   }
 
-  // Check for --shell flag (shell mode: no embedded content, for dynamic backend)
-  const shellFlag = args.includes('--shell')
-
   // Check for --prerender / --no-prerender flags
   const prerenderFlag = args.includes('--prerender')
   const noPrerenderFlag = args.includes('--no-prerender')
 
+  // Check for --link / --bundle flags. These select between two
+  // mutually exclusive site build pipelines:
+  //   --link:   data only, no vite (for Uniweb-edge hosting)
+  //   --bundle: full vite pipeline (for static hosts; today's behavior)
+  // Bare `uniweb build` for a site defaults to --bundle for back-compat
+  // with users targeting static hosts. `uniweb deploy` always passes one
+  // of the two explicitly based on the resolved deploy mode.
+  const linkFlag = args.includes('--link')
+  const bundleFlag = args.includes('--bundle')
+  if (linkFlag && bundleFlag) {
+    error('Cannot pass both --link and --bundle (they select different build pipelines)')
+    process.exit(1)
+  }
+
   // Check for --foundation-dir flag (for prerendering)
   let foundationDir = null
   const foundationDirIndex = args.indexOf('--foundation-dir')
@@ -685,9 +846,12 @@ export async function build(args = []) {
     process.exit(1)
   }
 
-  // Validate --shell is only used with site target
-  if (shellFlag && targetType !== 'site') {
-    error('--shell can only be used with site builds')
+  // Validate --link / --bundle are only used with site target.
+  // (Foundation builds have no equivalent split — they always produce
+  // dist/foundation.js + schema.json regardless of how a downstream
+  // site consumes the result.)
+  if ((linkFlag || bundleFlag) && targetType === 'foundation') {
+    error('--link and --bundle apply to site builds only')
     process.exit(1)
   }
 
@@ -700,6 +864,23 @@ export async function build(args = []) {
     } else {
       // For sites, read config to determine prerender default
       const siteConfig = readSiteConfig(projectDir)
+
+      // Link mode: data-only pipeline, no vite. The deployed Uniweb-edge
+      // site never consumes the JS bundle, so we skip producing it.
+      // Worker generates HTML at request time using its own runtime +
+      // the foundation served from the registry. See
+      // `framework/build/src/site/build-site-data.js` for what gets
+      // emitted (and what doesn't).
+      if (linkFlag) {
+        if (prerenderFlag) {
+          error('--prerender does not apply to link mode (no static HTML is produced)')
+          process.exit(1)
+        }
+        await buildSiteLink(projectDir, { siteConfig })
+        return
+      }
+
+      // Bundle mode (default for sites, or explicit --bundle).
       const configPrerender = siteConfig.build?.prerender === true
 
       // CLI flags override config: --prerender forces on, --no-prerender forces off
@@ -707,21 +888,7 @@ export async function build(args = []) {
       if (prerenderFlag) prerender = true
       if (noPrerenderFlag) prerender = false
 
-      // Shell mode: set env var for Vite config, force no prerender
-      if (shellFlag) {
-        process.env.UNIWEB_SHELL = 'true'
-        prerender = false
-        info('Building in shell mode (no embedded content)')
-      }
-
       await buildSite(projectDir, { prerender, foundationDir, siteConfig })
-
-      if (shellFlag) {
-        log('')
-        log(`${colors.green}${colors.bright}Shell build complete!${colors.reset}`)
-        log(`  The shell contains no embedded content.`)
-        log(`  Use ${colors.cyan}node scripts/platform/serve.js${colors.reset} to serve with dynamic content.`)
-      }
     }
   } catch (err) {
     error(err.message)