uniweb 0.12.11 → 0.12.13

package/README.md

@@ -315,7 +315,7 @@ A Uniweb project produces two artifacts — a **site** (content) and a **foundat
 - **Standalone mode** — site and foundation built into one self-contained `dist/`, deployed to any static host.
 - **Linked mode** — the foundation is a separate file the site loads at runtime, with two flavours:
   - **Site-bound** — the foundation belongs to one site and rides with it (`foundation: ~self/<name>@<version>` in `site.yml`).
-  - **Cataloged** — the foundation is a catalog product, published once and licensed to consuming sites (`foundation: '@<org>/<name>@<version>'`).
+  - **Cataloged** — the foundation is a private catalog product, published once and licensed to consuming sites (`foundation: '@<org>/<name>@<version>'`).
 
 `uniweb publish` ships a cataloged foundation; `uniweb deploy` ships a site (and, for site-bound, the foundation along with it). Most projects start standalone or site-bound and grow into cataloged when a foundation needs to serve more than one site.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.12.11",
+  "version": "0.12.13",
   "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/runtime": "0.8.13",
     "@uniweb/core": "0.7.11",
-    "@uniweb/kit": "0.9.11"
+    "@uniweb/kit": "0.9.11",
+    "@uniweb/runtime": "0.8.13"
   },
   "peerDependencies": {
     "@uniweb/build": "0.14.2",
-    "@uniweb/semantic-parser": "1.1.17",
-    "@uniweb/content-reader": "1.1.10"
+    "@uniweb/content-reader": "1.1.10",
+    "@uniweb/semantic-parser": "1.1.17"
   },
   "peerDependenciesMeta": {
     "@uniweb/build": {

package/partials/agents.md

@@ -148,8 +148,7 @@ uniweb deploy --host=<adapter>    # Deploy to a static host: cloudflare-pages, n
                                   # vercel, github-pages, s3-cloudfront, generic-static
 uniweb deploy --dry-run           # Resolve foundation/runtime + print summary; no writes
 uniweb export                     # Build dist/ for any static host (no Uniweb account)
-uniweb publish                    # Publish a foundation as a catalog product (deliberate;
-                                  # for site-bound foundations use `uniweb deploy` instead)
+uniweb publish                    # Publish a foundation to the Uniweb registry
 uniweb doctor                     # Diagnose project configuration issues (--fix to auto-repair)
 
 # Help

package/src/commands/rename.js

@@ -1,35 +1,50 @@
 /**
  * Rename Command
  *
- * Renames packages across the workspace transactionally. Currently
- * supports `rename foundation <old> <new>`; sites and extensions can be
- * added with the same scaffolding when needed.
+ * Renames packages across the workspace transactionally. Supports
+ * `rename foundation`, `rename site`, and `rename extension`. Each
+ * subcommand updates a different set of touch points:
  *
- * What a foundation rename touches (in order):
- *   1. The foundation's own package.json::name.
- *   2. Folder name on disk (when folder leaf matches old package name).
- *   3. Each site's package.json: dep key (old → new) + file: path.
- *   4. Each site's site.yml::foundation.
- *   5. pnpm-workspace.yaml::packages and package.json::workspaces
- *      (when the folder rename moved the path).
- *   6. Root scripts (`pnpm --filter <old>` references).
+ *   foundation: package.json::name + folder + every dependent site's
+ *     package.json (dep key + file: path) + every site.yml::foundation
+ *     reference + workspace manifests + root scripts.
+ *
+ *   site: package.json::name + folder + workspace manifests + root
+ *     scripts (sites are referenced by name in `pnpm --filter`-style
+ *     scripts, hence the regen).
+ *
+ *   extension: package.json::name + folder + every site.yml::extensions
+ *     entry whose URL prefix matches the old folder path + workspace
+ *     manifests. Sites don't carry a `file:` dep on extensions (extensions
+ *     load by URL at runtime), so no per-site package.json updates.
+ *
+ * Extensions are technically a flavor of foundation (same build, same
+ * package.json shape, distinguished only by `extension: true` in
+ * src/foundation.js or `role: 'extension'` in the built schema). The
+ * rename verb still keeps them on a separate subcommand because the
+ * touch-point sets differ — `rename foundation` against an extension
+ * would update the wrong things. Each subcommand guards its target
+ * type and points at the right verb when wrong.
  *
  * Pre-flight checks run before any mutation. If anything would conflict
- * (target name already taken, foundation not found, folder collision)
- * we bail with a clear message and no partial state.
+ * (target name already taken, target not found, folder collision,
+ * type mismatch) we bail with a clear message and no partial state.
  *
- * Out of scope: registry side. The publish id (`package.json::uniweb.id`)
+ * Out of scope: registry side. The publish id (package.json::uniweb.id)
  * is independent of the workspace name and stays untouched. Users who
  * want to also rename on the registry run `uniweb publish --name <new>`.
  *
  * Usage:
  *   uniweb rename foundation <old> <new>
+ *   uniweb rename site <old> <new>
+ *   uniweb rename extension <old> <new>
  */
 
 import { existsSync } from 'node:fs'
 import { readFile, writeFile, rename as fsRename } from 'node:fs/promises'
 import { join, relative, dirname, basename } from 'node:path'
 import yaml from 'js-yaml'
+import { isExtensionPackage } from '@uniweb/build'
 import { findWorkspaceRoot } from '../utils/workspace.js'
 import {
   discoverFoundations,
@@ -59,6 +74,8 @@ const error = (msg) => console.error(`${colors.red}✗${colors.reset} ${msg}`)
 const info = (msg) => console.log(`${colors.dim}${msg}${colors.reset}`)
 const log = console.log
 
+const SUPPORTED_SUBCOMMANDS = new Set(['foundation', 'site', 'extension'])
+
 export async function rename(args = []) {
   const [subcommand, oldName, newName] = args
   const prefix = getCliPrefix()
@@ -68,15 +85,15 @@ export async function rename(args = []) {
     return
   }
 
-  if (subcommand !== 'foundation') {
+  if (!SUPPORTED_SUBCOMMANDS.has(subcommand)) {
     error(`Unknown subcommand: ${subcommand}`)
-    log(`Supported: rename foundation <old> <new>`)
+    log(`Supported: rename foundation|site|extension <old> <new>`)
     process.exit(1)
   }
 
   if (!oldName || !newName) {
     error('Missing arguments.')
-    log(`Usage: ${prefix} rename foundation <old> <new>`)
+    log(`Usage: ${prefix} rename ${subcommand} <old> <new>`)
     process.exit(1)
   }
 
@@ -92,24 +109,92 @@ export async function rename(args = []) {
     process.exit(1)
   }
 
-  await renameFoundation(rootDir, oldName, newName, prefix)
+  if (subcommand === 'foundation') {
+    await renameFoundation(rootDir, oldName, newName, prefix)
+  } else if (subcommand === 'site') {
+    await renameSite(rootDir, oldName, newName, prefix)
+  } else if (subcommand === 'extension') {
+    await renameExtension(rootDir, oldName, newName, prefix)
+  }
 }
 
-async function renameFoundation(rootDir, oldName, newName, prefix) {
-  // ─── Pre-flight ───────────────────────────────────────────────
+// ─── Common helpers ──────────────────────────────────────────────
 
-  // Validate the new name (format + reserved-name check). `src` is
-  // grandfathered in for the same reason add foundation grandfathers
-  // it (the convention for "the package that lives in src/").
-  if (newName !== 'src') {
+/**
+ * Compute the new folder path for a rename. Returns { folderWillRename,
+ * newPath, newDir }. The leaf is renamed to match the new package name
+ * only when the leaf already matched the old package name — preserves
+ * any folder convention the user adopted that diverges from the package
+ * name.
+ */
+function computeNewFolderPath(rootDir, oldPath, oldName, newName) {
+  const leaf = basename(oldPath)
+  const folderWillRename = leaf === oldName
+  if (!folderWillRename) {
+    return { folderWillRename, newPath: oldPath, newDir: join(rootDir, oldPath) }
+  }
+  const parent = dirname(oldPath)
+  const newPath = parent === '.' ? newName : join(parent, newName)
+  return { folderWillRename, newPath, newDir: join(rootDir, newPath) }
+}
+
+/**
+ * Update the workspace manifests when a folder path moves. Both
+ * pnpm-workspace.yaml and package.json::workspaces are kept in sync
+ * (the multi-PM compatibility invariant). Wildcard entries
+ * (`extensions/*`) are left alone — only specific paths get rewritten.
+ */
+async function updateWorkspaceManifestsForFolderMove(rootDir, oldPath, newPath) {
+  const wsConfig = await readWorkspaceConfig(rootDir)
+  const rootPkg = await readRootPackageJson(rootDir)
+  if (wsConfig.packages.includes(oldPath)) {
+    const idx = wsConfig.packages.indexOf(oldPath)
+    wsConfig.packages[idx] = newPath
+    await writeWorkspaceConfig(rootDir, wsConfig)
+  }
+  if (Array.isArray(rootPkg.workspaces) && rootPkg.workspaces.includes(oldPath)) {
+    const idx = rootPkg.workspaces.indexOf(oldPath)
+    rootPkg.workspaces[idx] = newPath
+    await writeRootPackageJson(rootDir, rootPkg)
+  }
+}
+
+/**
+ * Validate that a name is a legal package name and not already taken in
+ * the workspace. Bails the process with an error if either check fails.
+ * `src` and `site` are grandfathered as valid names because they're the
+ * default folder leaf for the canonical foundation and site, and `add
+ * foundation` / `add site` already grandfather them at scaffold time.
+ */
+async function validateRenameName(rootDir, newName) {
+  if (newName !== 'src' && newName !== 'site') {
     const valid = validatePackageName(newName)
     if (valid !== true) {
       error(valid)
       process.exit(1)
     }
   }
+  const existingNames = await getExistingPackageNames(rootDir)
+  if (existingNames.has(newName)) {
+    error(`Cannot rename: a package named ${colors.bright}${newName}${colors.reset} already exists in this workspace.`)
+    process.exit(1)
+  }
+}
+
+/**
+ * Rewrite the `name` field in a package.json file.
+ */
+async function rewritePackageJsonName(pkgPath, newName) {
+  const pkg = JSON.parse(await readFile(pkgPath, 'utf-8'))
+  pkg.name = newName
+  await writeFile(pkgPath, JSON.stringify(pkg, null, 2) + '\n')
+}
+
+// ─── Foundation rename ───────────────────────────────────────────
+
+async function renameFoundation(rootDir, oldName, newName, prefix) {
+  await validateRenameName(rootDir, newName)
 
-  // The foundation must exist under its current name.
   const foundations = await discoverFoundations(rootDir)
   const target = foundations.find(f => f.name === oldName)
   if (!target) {
@@ -120,33 +205,24 @@ async function renameFoundation(rootDir, oldName, newName, prefix) {
     process.exit(1)
   }
 
-  // The new name must be free across the entire workspace.
-  const existingNames = await getExistingPackageNames(rootDir)
-  if (existingNames.has(newName)) {
-    error(`Cannot rename: a package named ${colors.bright}${newName}${colors.reset} already exists in this workspace.`)
+  // Type guard — point users at the right subcommand if they're trying
+  // to rename an extension via the foundation verb. They share a build
+  // shape but their touch-point sets differ (foundation rename touches
+  // sites' deps + site.yml::foundation; extension rename touches
+  // site.yml::extensions URLs).
+  if (isExtensionPackage(join(rootDir, target.path))) {
+    error(`${colors.bright}${oldName}${colors.reset} is an extension, not a foundation.`)
+    log(`Use \`${prefix} rename extension ${oldName} ${newName}\` instead.`)
     process.exit(1)
   }
 
-  const oldFoundationPath = target.path  // workspace-relative
+  const oldFoundationPath = target.path
   const oldFoundationDir = join(rootDir, oldFoundationPath)
-  const folderLeaf = basename(oldFoundationPath)
-
-  // Decide the new folder path. Rule: if the folder leaf matches the
-  // old package name, rename the leaf to match the new package name
-  // (preserving any parent dirs like `foundations/`). Otherwise leave
-  // the folder alone — the user named the folder differently than the
-  // package, and we honor that.
-  let newFoundationPath = oldFoundationPath
-  let newFoundationDir = oldFoundationDir
-  const folderWillRename = folderLeaf === oldName
-  if (folderWillRename) {
-    const parent = dirname(oldFoundationPath)
-    newFoundationPath = parent === '.' ? newName : join(parent, newName)
-    newFoundationDir = join(rootDir, newFoundationPath)
-    if (existsSync(newFoundationDir)) {
-      error(`Cannot rename: target folder ${colors.bright}${newFoundationPath}/${colors.reset} already exists.`)
-      process.exit(1)
-    }
+  const { folderWillRename, newPath: newFoundationPath, newDir: newFoundationDir } =
+    computeNewFolderPath(rootDir, oldFoundationPath, oldName, newName)
+  if (folderWillRename && existsSync(newFoundationDir)) {
+    error(`Cannot rename: target folder ${colors.bright}${newFoundationPath}/${colors.reset} already exists.`)
+    process.exit(1)
   }
 
   // Find every site that depends on the foundation. Two signals must
@@ -159,17 +235,15 @@ async function renameFoundation(rootDir, oldName, newName, prefix) {
   for (const site of sites) {
     const sitePkgPath = join(rootDir, site.path, 'package.json')
     const siteYmlPath = join(rootDir, site.path, 'site.yml')
-    let pkg, ymlText, ymlData
+    let pkg, ymlData
     try {
       pkg = JSON.parse(await readFile(sitePkgPath, 'utf-8'))
     } catch {
       pkg = null
     }
     try {
-      ymlText = await readFile(siteYmlPath, 'utf-8')
-      ymlData = yaml.load(ymlText) || {}
+      ymlData = yaml.load(await readFile(siteYmlPath, 'utf-8')) || {}
     } catch {
-      ymlText = null
       ymlData = null
     }
     const hasDep = pkg?.dependencies && oldName in pkg.dependencies
@@ -188,12 +262,6 @@ async function renameFoundation(rootDir, oldName, newName, prefix) {
     }
   }
 
-  // Read workspace config + root package.json once. Both manifests
-  // are kept in sync by addWorkspaceGlob; we update both here too
-  // (the multi-PM compatibility invariant).
-  const wsConfig = await readWorkspaceConfig(rootDir)
-  const rootPkg = await readRootPackageJson(rootDir)
-
   // ─── Print plan, then execute ────────────────────────────────
 
   log('')
@@ -215,31 +283,19 @@ async function renameFoundation(rootDir, oldName, newName, prefix) {
   }
   log('')
 
-  // 1. Rename the folder (if applicable). Do this first because every
-  //    later write needs paths under the new location.
   if (folderWillRename) {
     await fsRename(oldFoundationDir, newFoundationDir)
   }
+  await rewritePackageJsonName(join(newFoundationDir, 'package.json'), newName)
 
-  // 2. Rewrite the foundation's package.json::name.
-  const fndPkgPath = join(newFoundationDir, 'package.json')
-  const fndPkg = JSON.parse(await readFile(fndPkgPath, 'utf-8'))
-  fndPkg.name = newName
-  await writeFile(fndPkgPath, JSON.stringify(fndPkg, null, 2) + '\n')
-
-  // 3 + 4. For each affected site, update package.json deps and site.yml.
   for (const s of affectedSites) {
     if (s.hasDep) {
-      // Rename the dep key. Recompute the file: path against the new
-      // foundation location (the old one no longer exists if the
-      // folder was renamed).
       const newRel = relative(join(rootDir, s.path), newFoundationDir) || '.'
       const oldValue = s.pkg.dependencies[oldName]
       delete s.pkg.dependencies[oldName]
       s.pkg.dependencies[newName] = oldValue.startsWith('file:')
         ? `file:${newRel}`
-        : oldValue  // npm-pinned, leave it; rename-then-republish would
-                    // need a separate `pnpm update` step that's out of scope.
+        : oldValue  // npm-pinned, leave it; rename-then-republish is out of scope.
       await writeFile(s.sitePkgPath, JSON.stringify(s.pkg, null, 2) + '\n')
     }
     if (s.ymlMatches) {
@@ -248,38 +304,185 @@ async function renameFoundation(rootDir, oldName, newName, prefix) {
     }
   }
 
-  // 5. Update workspace manifests. Both pnpm-workspace.yaml and
-  //    package.json::workspaces (sync invariant) — only the entry
-  //    matching the old folder path moves; bare globs like
-  //    `foundations/*` don't change.
   if (folderWillRename) {
-    if (wsConfig.packages.includes(oldFoundationPath)) {
-      const idx = wsConfig.packages.indexOf(oldFoundationPath)
-      wsConfig.packages[idx] = newFoundationPath
-      await writeWorkspaceConfig(rootDir, wsConfig)
-    }
-    if (Array.isArray(rootPkg.workspaces) && rootPkg.workspaces.includes(oldFoundationPath)) {
-      const idx = rootPkg.workspaces.indexOf(oldFoundationPath)
-      rootPkg.workspaces[idx] = newFoundationPath
-      await writeRootPackageJson(rootDir, rootPkg)
+    await updateWorkspaceManifestsForFolderMove(rootDir, oldFoundationPath, newFoundationPath)
+  }
+
+  // Root scripts can reference the foundation by name (e.g. `pnpm --filter
+  // <name> build`). updateRootScripts regenerates them from the current
+  // discoverSites output, which has fresh names after the writes above.
+  const pm = detectPackageManager()
+  const freshSites = await discoverSites(rootDir)
+  await updateRootScripts(rootDir, freshSites, pm)
+
+  log('')
+  success(`Renamed foundation ${colors.bright}${oldName}${colors.reset} → ${colors.bright}${newName}${colors.reset}`)
+  printNextSteps(prefix, pm)
+}
+
+// ─── Site rename ─────────────────────────────────────────────────
+
+async function renameSite(rootDir, oldName, newName, prefix) {
+  await validateRenameName(rootDir, newName)
+
+  const sites = await discoverSites(rootDir)
+  const target = sites.find(s => s.name === oldName)
+  if (!target) {
+    error(`No site named ${colors.bright}${oldName}${colors.reset} in this workspace.`)
+    if (sites.length > 0) {
+      log(`Available: ${sites.map(s => s.name).join(', ')}`)
     }
+    process.exit(1)
+  }
+
+  const oldSitePath = target.path
+  const oldSiteDir = join(rootDir, oldSitePath)
+  const { folderWillRename, newPath: newSitePath, newDir: newSiteDir } =
+    computeNewFolderPath(rootDir, oldSitePath, oldName, newName)
+  if (folderWillRename && existsSync(newSiteDir)) {
+    error(`Cannot rename: target folder ${colors.bright}${newSitePath}/${colors.reset} already exists.`)
+    process.exit(1)
   }
 
-  // 6. Root scripts can reference the foundation by name (e.g.
-  //    `pnpm --filter <name> build`). updateRootScripts regenerates
-  //    them from the current discoverSites output, which has fresh
-  //    names after the writes above.
+  log('')
+  log(`${colors.bright}Rename site${colors.reset}: ${colors.yellow}${oldName}${colors.reset} → ${colors.green}${newName}${colors.reset}`)
+  log('')
+  if (folderWillRename) {
+    info(`  Folder:  ${oldSitePath}/  →  ${newSitePath}/`)
+  } else {
+    info(`  Folder:  ${oldSitePath}/  (unchanged — leaf doesn't match package name)`)
+  }
+  info(`  package.json::name:  "${oldName}"  →  "${newName}"`)
+  log('')
+
+  if (folderWillRename) {
+    await fsRename(oldSiteDir, newSiteDir)
+  }
+  await rewritePackageJsonName(join(newSiteDir, 'package.json'), newName)
+  if (folderWillRename) {
+    await updateWorkspaceManifestsForFolderMove(rootDir, oldSitePath, newSitePath)
+  }
+
+  // Root scripts include `pnpm --filter <site-name>` style invocations
+  // for `dev` / `preview` and per-site aliases. Regenerate from fresh
+  // site discovery to pick up the new name.
   const pm = detectPackageManager()
   const freshSites = await discoverSites(rootDir)
   await updateRootScripts(rootDir, freshSites, pm)
 
-  // ─── Done ─────────────────────────────────────────────────────
+  log('')
+  success(`Renamed site ${colors.bright}${oldName}${colors.reset} → ${colors.bright}${newName}${colors.reset}`)
+  printNextSteps(prefix, pm)
+}
+
+// ─── Extension rename ────────────────────────────────────────────
+
+async function renameExtension(rootDir, oldName, newName, prefix) {
+  await validateRenameName(rootDir, newName)
+
+  // Extensions are a subset of foundations (same build, distinguished
+  // by `extension: true` declaration). Find via discoverFoundations,
+  // then verify the extension marker.
+  const foundations = await discoverFoundations(rootDir)
+  const target = foundations.find(f => f.name === oldName)
+  if (!target) {
+    error(`No package named ${colors.bright}${oldName}${colors.reset} in this workspace.`)
+    process.exit(1)
+  }
+  if (!isExtensionPackage(join(rootDir, target.path))) {
+    error(`${colors.bright}${oldName}${colors.reset} is a foundation, not an extension.`)
+    log(`Use \`${prefix} rename foundation ${oldName} ${newName}\` instead.`)
+    process.exit(1)
+  }
+
+  const oldExtPath = target.path
+  const oldExtDir = join(rootDir, oldExtPath)
+  const { folderWillRename, newPath: newExtPath, newDir: newExtDir } =
+    computeNewFolderPath(rootDir, oldExtPath, oldName, newName)
+  if (folderWillRename && existsSync(newExtDir)) {
+    error(`Cannot rename: target folder ${colors.bright}${newExtPath}/${colors.reset} already exists.`)
+    process.exit(1)
+  }
+
+  // Find every site referencing this extension via its site.yml's
+  // `extensions:` array. Sites declare extensions by URL, with the
+  // shape `/<workspace-relative-path>/dist/<file>` (where <file> is
+  // `entry.js` post-Phase-4, `foundation.js` for older builds — match
+  // both). Foreign URLs (https://, anything not starting with
+  // `/<oldExtPath>/`) are left untouched.
+  const oldUrlPrefix = `/${oldExtPath}/`
+  const newUrlPrefix = `/${newExtPath}/`
+  const sites = await discoverSites(rootDir)
+  const affectedSites = []
+  for (const site of sites) {
+    const siteYmlPath = join(rootDir, site.path, 'site.yml')
+    let ymlData
+    try {
+      ymlData = yaml.load(await readFile(siteYmlPath, 'utf-8')) || {}
+    } catch {
+      continue
+    }
+    const exts = Array.isArray(ymlData.extensions) ? ymlData.extensions : []
+    const hits = exts.filter(e => typeof e === 'string' && e.startsWith(oldUrlPrefix))
+    if (hits.length > 0) {
+      affectedSites.push({ site, ymlData, siteYmlPath, hits })
+    }
+  }
 
   log('')
-  success(`Renamed foundation ${colors.bright}${oldName}${colors.reset} → ${colors.bright}${newName}${colors.reset}`)
+  log(`${colors.bright}Rename extension${colors.reset}: ${colors.yellow}${oldName}${colors.reset} → ${colors.green}${newName}${colors.reset}`)
+  log('')
+  if (folderWillRename) {
+    info(`  Folder:  ${oldExtPath}/  →  ${newExtPath}/`)
+  } else {
+    info(`  Folder:  ${oldExtPath}/  (unchanged — leaf doesn't match package name)`)
+  }
+  info(`  package.json::name:  "${oldName}"  →  "${newName}"`)
+  if (affectedSites.length === 0) {
+    info(`  Sites referencing this extension: none`)
+  } else {
+    info(`  Sites referencing this extension:`)
+    for (const { site, hits } of affectedSites) {
+      info(`    • ${site.name} at ${site.path}/  (${hits.length} entr${hits.length === 1 ? 'y' : 'ies'})`)
+    }
+  }
+  log('')
+
+  if (folderWillRename) {
+    await fsRename(oldExtDir, newExtDir)
+  }
+  await rewritePackageJsonName(join(newExtDir, 'package.json'), newName)
+
+  for (const a of affectedSites) {
+    const newExts = (a.ymlData.extensions || []).map(e =>
+      typeof e === 'string' && e.startsWith(oldUrlPrefix)
+        ? newUrlPrefix + e.slice(oldUrlPrefix.length)
+        : e
+    )
+    const newYmlData = { ...a.ymlData, extensions: newExts }
+    await writeFile(a.siteYmlPath, yaml.dump(newYmlData, { flowLevel: -1, quotingType: "'" }))
+  }
+
+  if (folderWillRename) {
+    await updateWorkspaceManifestsForFolderMove(rootDir, oldExtPath, newExtPath)
+  }
+
+  // Extensions don't appear in root scripts (no dev/preview filter by
+  // extension name — the foundation's own scripts handle building).
+  // No updateRootScripts needed.
+
+  const pm = detectPackageManager()
+  log('')
+  success(`Renamed extension ${colors.bright}${oldName}${colors.reset} → ${colors.bright}${newName}${colors.reset}`)
+  printNextSteps(prefix, pm)
+}
+
+// ─── Shared output ───────────────────────────────────────────────
+
+function printNextSteps(prefix, pm) {
   log('')
   log(`Next: ${colors.cyan}${installCmd(pm)}${colors.reset}  ${colors.dim}(refresh symlinks under the new name)${colors.reset}`)
-  log(`      ${colors.cyan}${getCliPrefix()} doctor${colors.reset}  ${colors.dim}(verify wiring)${colors.reset}`)
+  log(`      ${colors.cyan}${prefix} doctor${colors.reset}  ${colors.dim}(verify wiring)${colors.reset}`)
 }
 
 function showHelp(prefix) {
@@ -290,8 +493,10 @@ Rename a package across the workspace, keeping all wiring in sync.
 
 ${colors.bright}Usage:${colors.reset}
   ${prefix} rename foundation <old-name> <new-name>
+  ${prefix} rename site <old-name> <new-name>
+  ${prefix} rename extension <old-name> <new-name>
 
-${colors.bright}What it does (foundation):${colors.reset}
+${colors.bright}What rename foundation does:${colors.reset}
   • Updates the foundation's package.json::name.
   • Renames the folder if its leaf matched the old package name.
   • Updates every site's package.json dependency key + file: path.
@@ -299,12 +504,25 @@ ${colors.bright}What it does (foundation):${colors.reset}
   • Updates pnpm-workspace.yaml + package.json::workspaces (kept in sync).
   • Regenerates root scripts.
 
-${colors.bright}What it does NOT do:${colors.reset}
+${colors.bright}What rename site does:${colors.reset}
+  • Updates the site's package.json::name.
+  • Renames the folder if its leaf matched the old package name.
+  • Updates pnpm-workspace.yaml + package.json::workspaces.
+  • Regenerates root scripts (\`dev\` / \`preview\` filter by site name).
+
+${colors.bright}What rename extension does:${colors.reset}
+  • Updates the extension's package.json::name.
+  • Renames the folder if its leaf matched the old package name.
+  • Updates every site.yml::extensions URL whose path matched the old folder.
+  • Updates pnpm-workspace.yaml + package.json::workspaces.
+
+${colors.bright}What rename does NOT do (any subcommand):${colors.reset}
   • Push to the registry. The publish id (package.json::uniweb.id) is
     independent. To rename on the registry too, run \`${prefix} publish --name <new>\`.
 
 ${colors.bright}Examples:${colors.reset}
   ${prefix} rename foundation src marketing-src
-  ${prefix} rename foundation marketing acme-marketing
+  ${prefix} rename site site marketing-com
+  ${prefix} rename extension effects animations
 `)
 }

package/src/commands/update.js

@@ -1,16 +1,47 @@
 /**
- * uniweb update - Update generated project files
+ * uniweb update — Update the CLI itself, and (in a Uniweb project) the
+ * project's AGENTS.md.
  *
- * Regenerates AGENTS.md from the installed CLI version.
+ * Two responsibilities, in priority order:
+ *
+ * 1. **Self-update the global install.** Most users running `uniweb update`
+ *    expect the verb to update the CLI binary itself (this is what `npm
+ *    update -g`, `gh update`, `claude update`, etc. all do). The CLI
+ *    detects the relevant package manager and runs the global-install
+ *    command for it (`npm i -g uniweb@latest`, `pnpm add -g uniweb@latest`,
+ *    `yarn global add uniweb@latest`). In TTY, prompts before executing.
+ *    In non-interactive mode, prints the command and exits — never runs an
+ *    unconfirmed self-update from a script.
+ *
+ * 2. **Refresh AGENTS.md** (only when the cwd resolves to a *Uniweb*
+ *    project — checked via `package.json::devDependencies::uniweb` or
+ *    `dependencies::uniweb` at the workspace root). The previous
+ *    implementation walked up looking for ANY pnpm-workspace.yaml or
+ *    `package.json::workspaces` root, which falsely identified unrelated
+ *    monorepos as Uniweb projects and wrote AGENTS.md into them.
+ *
+ * Flags:
+ *   --agents-only        Skip self-update; only refresh AGENTS.md.
+ *   --no-agents          Skip AGENTS.md; only self-update.
+ *   --yes                Skip the confirmation prompt before self-update.
+ *   --non-interactive    Auto-detected; never runs unconfirmed self-update.
+ *
+ * Project-local case (CLI lives in node_modules, not global): self-update
+ * isn't possible — that's a project decision (bump the dep in
+ * package.json). The verb prints that explanation and proceeds with the
+ * AGENTS.md refresh path only.
  */
 
-import { existsSync, writeFileSync } from 'node:fs'
-import { join, resolve } from 'node:path'
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { spawn } from 'node:child_process'
+import prompts from 'prompts'
+
 import { findWorkspaceRoot } from '../utils/workspace.js'
 import { readAgentsVersion, generateAgentsContent } from '../utils/agents-stamp.js'
 import { getCliVersion } from '../versions.js'
+import { isNonInteractive } from '../utils/interactive.js'
 
-// ANSI colors
 const colors = {
   reset: '\x1b[0m',
   bright: '\x1b[1m',
@@ -18,7 +49,7 @@ const colors = {
   red: '\x1b[31m',
   green: '\x1b[32m',
   yellow: '\x1b[33m',
-  blue: '\x1b[36m'
+  cyan: '\x1b[36m',
 }
 
 const success = (msg) => console.log(`${colors.green}✓${colors.reset} ${msg}`)
@@ -26,30 +57,196 @@ const warn = (msg) => console.log(`${colors.yellow}⚠${colors.reset} ${msg}`)
 const error = (msg) => console.log(`${colors.red}✗${colors.reset} ${msg}`)
 const log = console.log
 
-export async function update(args = []) {
-  const workspaceDir = findWorkspaceRoot(process.cwd())
+/**
+ * Detect whether this CLI is running from a global install. Mirrors the
+ * logic in index.js::isGlobalInstall — when global, process.argv[1]
+ * points outside any node_modules.
+ */
+function isGlobalInstall() {
+  const scriptPath = process.argv[1]
+  if (!scriptPath) return false
+  return !scriptPath.split('/').includes('node_modules') &&
+         !scriptPath.split('\\').includes('node_modules')
+}
 
-  if (!workspaceDir) {
-    error('Not in a Uniweb workspace')
-    log(`${colors.dim}Run this command from your project root or a package directory.${colors.reset}`)
-    process.exit(1)
+/**
+ * Find a *Uniweb* workspace root from cwd. Stricter than findWorkspaceRoot
+ * — also requires that the workspace's root package.json declares uniweb
+ * as a dep or devDep. Otherwise the previous behavior (walking up to any
+ * pnpm-workspace.yaml) writes AGENTS.md into unrelated monorepos.
+ */
+function findUniwebWorkspace(cwd) {
+  const workspaceDir = findWorkspaceRoot(cwd)
+  if (!workspaceDir) return null
+  const pkgPath = join(workspaceDir, 'package.json')
+  if (!existsSync(pkgPath)) return null
+  try {
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'))
+    const hasUniwebDep = !!(pkg.devDependencies?.uniweb || pkg.dependencies?.uniweb)
+    return hasUniwebDep ? workspaceDir : null
+  } catch {
+    return null
   }
+}
 
+/**
+ * Detect the package manager that owns the global install. Heuristic
+ * based on the CLI's filesystem path — pnpm and yarn berry use distinctive
+ * directory layouts; npm is the fallback.
+ *
+ * @returns {'pnpm'|'yarn'|'npm'}
+ */
+function detectGlobalPm() {
+  const path = (process.argv[1] || '').toLowerCase()
+  if (path.includes('/pnpm/') || path.includes('\\pnpm\\')) return 'pnpm'
+  if (path.includes('/yarn/') || path.includes('\\yarn\\')) return 'yarn'
+  return 'npm'
+}
+
+/**
+ * Build the global-install command for a given PM.
+ */
+function globalInstallCmd(pm) {
+  if (pm === 'pnpm') return 'pnpm add -g uniweb@latest'
+  if (pm === 'yarn') return 'yarn global add uniweb@latest'
+  return 'npm i -g uniweb@latest'
+}
+
+/**
+ * Fetch the latest published version. Returns null on network error.
+ */
+async function fetchLatestVersion() {
+  try {
+    const res = await fetch('https://registry.npmjs.org/uniweb/latest')
+    if (!res.ok) return null
+    const data = await res.json()
+    return data?.version || null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Compare two semver strings: 1 if a>b, -1 if a<b, 0 if equal.
+ */
+function compareSemver(a, b) {
+  const pa = a.split('.').map(Number)
+  const pb = b.split('.').map(Number)
+  for (let i = 0; i < 3; i++) {
+    if ((pa[i] || 0) > (pb[i] || 0)) return 1
+    if ((pa[i] || 0) < (pb[i] || 0)) return -1
+  }
+  return 0
+}
+
+/**
+ * Run a shell command, inheriting stdio. Resolves with the exit code.
+ */
+function runCommand(cmd) {
+  return new Promise((resolve) => {
+    const [bin, ...rest] = cmd.split(' ')
+    const child = spawn(bin, rest, { stdio: 'inherit' })
+    child.on('close', code => resolve(code ?? 0))
+    child.on('error', () => resolve(1))
+  })
+}
+
+export async function update(args = []) {
+  const agentsOnly = args.includes('--agents-only')
+  const skipAgents = args.includes('--no-agents')
+  const skipPrompt = args.includes('--yes') || isNonInteractive(args)
+  const isGlobal = isGlobalInstall()
+  const workspaceDir = findUniwebWorkspace(process.cwd())
+  const inProject = !!workspaceDir
   const cliVersion = getCliVersion()
-  const agentsPath = join(workspaceDir, 'AGENTS.md')
-  const currentVersion = readAgentsVersion(agentsPath)
 
-  if (currentVersion === cliVersion) {
-    success(`AGENTS.md is already up to date (v${cliVersion})`)
+  // ─── Step 1: Self-update path ─────────────────────────────────
+  if (!agentsOnly) {
+    if (!isGlobal) {
+      // Project-local: can't self-update meaningfully.
+      log(`${colors.dim}Running the project-local CLI (v${cliVersion}). This copy is pinned by your${colors.reset}`)
+      log(`${colors.dim}project's package.json. To update it, bump${colors.reset} ${colors.cyan}uniweb${colors.reset}${colors.dim} in${colors.reset} ${colors.cyan}package.json${colors.reset}${colors.dim} and re-install.${colors.reset}`)
+      log('')
+    } else {
+      const latest = await fetchLatestVersion()
+      if (latest === null) {
+        warn('Could not reach the npm registry to check for updates.')
+        log(`${colors.dim}Current: ${cliVersion}. Try later, or run${colors.reset} ${colors.cyan}${globalInstallCmd(detectGlobalPm())}${colors.reset}${colors.dim} manually.${colors.reset}`)
+        log('')
+      } else if (compareSemver(latest, cliVersion) <= 0) {
+        success(`uniweb is up to date (v${cliVersion}).`)
+        log('')
+      } else {
+        const pm = detectGlobalPm()
+        const cmd = globalInstallCmd(pm)
+        log(`${colors.yellow}Update available:${colors.reset} ${colors.dim}${cliVersion}${colors.reset} → ${colors.cyan}${latest}${colors.reset}`)
+        log(`${colors.dim}Detected package manager:${colors.reset} ${pm}`)
+        log(`${colors.dim}Will run:${colors.reset} ${colors.cyan}${cmd}${colors.reset}`)
+        log('')
+
+        if (skipPrompt) {
+          log(`${colors.dim}Non-interactive — skipping self-update. Run the command above to update.${colors.reset}`)
+          log('')
+        } else {
+          const { go } = await prompts({
+            type: 'confirm',
+            name: 'go',
+            message: `Run \`${cmd}\` now?`,
+            initial: true,
+          })
+          if (go) {
+            const code = await runCommand(cmd)
+            if (code === 0) {
+              success(`Self-update complete.`)
+            } else {
+              error(`Self-update failed (exit ${code}). Run the command above manually if needed.`)
+            }
+            log('')
+          } else {
+            log(`${colors.dim}Skipped self-update.${colors.reset}`)
+            log('')
+          }
+        }
+      }
+    }
+  }
+
+  // ─── Step 2: AGENTS.md refresh path ───────────────────────────
+  if (skipAgents) return
+  if (!inProject) {
+    if (agentsOnly) {
+      error('Not in a Uniweb project (no `uniweb` dep in the workspace root package.json).')
+      log(`${colors.dim}Run this command from inside a project created by${colors.reset} ${colors.cyan}uniweb create${colors.reset}${colors.dim}.${colors.reset}`)
+      process.exit(1)
+    }
+    // Self-update-only path. Quietly skip AGENTS.md.
     return
   }
 
+  const agentsPath = join(workspaceDir, 'AGENTS.md')
+  const currentAgentsVersion = readAgentsVersion(agentsPath)
+  if (currentAgentsVersion === cliVersion) {
+    success(`AGENTS.md is already up to date (v${cliVersion}).`)
+    return
+  }
+
+  // Prompt before writing in TTY, unless --yes / non-interactive (in which
+  // case we err on the side of doing the right thing — refresh — since the
+  // user explicitly invoked `uniweb update` from a Uniweb project).
+  if (!skipPrompt && !agentsOnly) {
+    const action = currentAgentsVersion ? `Update AGENTS.md (v${currentAgentsVersion} → v${cliVersion})?` : `Create AGENTS.md (v${cliVersion})?`
+    const { yes } = await prompts({ type: 'confirm', name: 'yes', message: action, initial: true })
+    if (!yes) {
+      log(`${colors.dim}Skipped AGENTS.md.${colors.reset}`)
+      return
+    }
+  }
+
   const content = generateAgentsContent()
   writeFileSync(agentsPath, content)
-
-  if (currentVersion) {
-    success(`Updated AGENTS.md (v${currentVersion} → v${cliVersion})`)
+  if (currentAgentsVersion) {
+    success(`Updated AGENTS.md (v${currentAgentsVersion} → v${cliVersion}).`)
   } else {
-    success(`Created AGENTS.md (v${cliVersion})`)
+    success(`Created AGENTS.md (v${cliVersion}).`)
   }
 }

package/src/index.js

@@ -103,8 +103,12 @@ function getCliVersion() {
 /**
  * Commands that always run from the global CLI (no project context needed)
  */
+// Commands that always run from the global CLI, never delegating to a
+// project-local copy. `update` is here because its primary job is to
+// self-update the GLOBAL install — delegating it to project-local would
+// short-circuit that intent.
 const STANDALONE_COMMANDS = new Set([
-  'create', '--help', '-h', '--version', '-v', 'login',
+  'create', '--help', '-h', '--version', '-v', 'login', 'update',
 ])
 
 /**
@@ -441,8 +445,20 @@ async function main() {
   const pm = detectPackageManager()
 
   // Handle --version / -v
+  //
+  // Output convention: the version goes to stdout (parseable, scriptable —
+  // `version=$(uniweb --version)` should keep working). Any staleness
+  // notice goes to stderr, so it shows in interactive terminals but
+  // doesn't pollute captured output. Cache-only — never makes a network
+  // call from this path.
   if (command === '--version' || command === '-v') {
     console.log(`uniweb ${getCliVersion()}`)
+    if (isGlobalInstall()) {
+      try {
+        const { maybeNotifyFromCache } = await import('./utils/update-check.js')
+        maybeNotifyFromCache(getCliVersion(), 'soft')
+      } catch { /* ignore */ }
+    }
     return
   }
 
@@ -1047,12 +1063,30 @@ ${colors.cyan}${colors.bright}uniweb rename${colors.reset} ${colors.dim}— Rena
 
 ${colors.bright}Usage:${colors.reset}
   uniweb rename foundation <old> <new>
+  uniweb rename site <old> <new>
+  uniweb rename extension <old> <new>
+
+Each subcommand updates a different set of touch points:
+
+  foundation: package.json::name + folder + every dependent site's
+    package.json (dep key + file: path) + every site.yml::foundation +
+    pnpm-workspace.yaml / package.json::workspaces + root scripts.
 
-Today supports renaming foundations only. Updates folder name, foundation
-package.json::name, every dependent site's site.yml::foundation, every
-dependent site's package.json::dependencies, pnpm-workspace.yaml, and
-package.json::workspaces. Transactional — bails on conflict before any
-filesystem mutation.
+  site: package.json::name + folder + workspace manifests + root
+    scripts (\`dev\` / \`preview\` are filtered by site name).
+
+  extension: package.json::name + folder + every site.yml::extensions
+    URL whose path matches the old folder + workspace manifests.
+    (Sites don't carry a \`file:\` dep on extensions — they load by
+    URL at runtime, so no per-site package.json updates.)
+
+Transactional — bails on conflict (target name taken, target not found,
+folder collision, type mismatch) before any filesystem mutation.
+
+Type guards: \`rename foundation\` against an extension errors and
+points at \`rename extension\` (and vice versa). They share a build
+shape but the touch-point sets differ; using the wrong subcommand
+would update the wrong things.
 `,
     login: `
 ${colors.cyan}${colors.bright}uniweb login${colors.reset} ${colors.dim}— Log in to your Uniweb account${colors.reset}
@@ -1139,14 +1173,28 @@ Prints the parsed content shape of a markdown file or folder — the
 Useful for debugging "why isn't my section getting X?".
 `,
     update: `
-${colors.cyan}${colors.bright}uniweb update${colors.reset} ${colors.dim}— Update AGENTS.md to match installed CLI version${colors.reset}
+${colors.cyan}${colors.bright}uniweb update${colors.reset} ${colors.dim}— Update the CLI itself, plus AGENTS.md when in a project${colors.reset}
 
 ${colors.bright}Usage:${colors.reset}
-  uniweb update
-
-Refreshes the project's AGENTS.md from the CLI's bundled version. Run
-after upgrading the \`uniweb\` package to pick up new content authoring
-patterns and platform documentation.
+  uniweb update                Self-update + (in project) refresh AGENTS.md
+  uniweb update --agents-only  Only refresh AGENTS.md (skip self-update)
+  uniweb update --no-agents    Only self-update (skip AGENTS.md)
+  uniweb update --yes          Skip the confirmation prompts
+
+${colors.bright}What it does:${colors.reset}
+  1. Self-update the global install via npm / pnpm / yarn (auto-detected).
+     In TTY, prompts before running. In CI / non-interactive, prints the
+     command and exits without running it.
+  2. If the cwd resolves to a Uniweb project (root package.json declares
+     \`uniweb\` as a dep), refreshes AGENTS.md from the CLI's bundled
+     version. Outside a Uniweb project, this step is skipped — the
+     command will not write AGENTS.md into unrelated directories.
+
+${colors.bright}Project-local installs:${colors.reset}
+  When the running CLI is project-local (lives in node_modules), self-
+  update is a no-op — the version is pinned by your project's
+  package.json. The verb prints that explanation and proceeds with the
+  AGENTS.md refresh path only.
 `,
   }
 
@@ -1165,12 +1213,12 @@ ${colors.bright}Usage:${colors.reset}
 ${colors.bright}Commands:${colors.reset}
   create [name]      Create a new project
   add <type> [name]  Add a foundation, site, or extension to a project
-  rename <type>      Rename a workspace package (foundation today)
+  rename <type>      Rename a foundation, site, or extension across the workspace
   dev                Start a dev server for a site
   build              Build the current project
   deploy             Deploy a site to Uniweb hosting
   export             Export a self-contained site for third-party hosting
-  publish            Publish a foundation to the Uniweb catalog (deliberate; for site-bound foundations, use deploy)
+  publish            Publish a foundation to the Uniweb registry
   invite <email>     Create a foundation invite for a client
   handoff <email>    Hand off a site to a client
   inspect <path>     Inspect parsed content shape of a markdown file or folder
@@ -1294,15 +1342,15 @@ ${colors.bright}Examples:${colors.reset}
   uniweb create my-project --template ./my-template  # Local template
 
   cd my-project
-  uniweb add project docs                            # Add docs/foundation/ + docs/site/
+  uniweb add project docs                            # Add docs/src/ + docs/site/
   uniweb add project docs --from academic            # Co-located pair + academic content
-  uniweb add foundation                              # Add foundation at root
-  uniweb add site blog --foundation marketing        # Add site wired to marketing
-  uniweb add extension effects --site site           # Add extensions/effects/
+  uniweb add marketing                               # Add marketing/ at root
+  uniweb add site blog --foundation marketing        # Add site/ wired to marketing
+  uniweb add extension effects --site site           # Add effects/ at root
 
   uniweb build
-  uniweb build --target foundation
-  cd foundation && uniweb docs                       # Generate COMPONENTS.md
+  uniweb build --target src                          # Build src/ package
+  cd src && uniweb docs                              # Generate COMPONENTS.md
 
 ${colors.bright}Install:${colors.reset}
   npm i -g uniweb          Global install (recommended)

package/src/utils/update-check.js

@@ -74,26 +74,33 @@ function printNotification(current, latest, tone = 'soft') {
 }
 
 /**
- * Synchronously read the cache and print an eager notification if a newer
+ * Synchronously read the cache and print a notification if a newer
  * version is known. No network fetch — only reads what `startUpdateCheck`
  * has previously cached. Returns true if a notification was printed.
  *
- * Use this for staleness-sensitive verbs (`create`) BEFORE the verb does
- * its work, so the user sees the warning before any files are written
- * from CLI-bundled templates. For other verbs, the trailing soft
- * notification from startUpdateCheck() is sufficient.
+ * Two call sites today, with different tone needs:
+ *   - `create` (tone='eager'): loud leading notice — templates ship with
+ *     the CLI, the user is about to scaffold files, this matters.
+ *   - `--version` / `-v` (tone='soft'): brief trailing notice — the user
+ *     was already asking about version, mention staleness while we're
+ *     here. Goes to stderr so scripts capturing stdout aren't affected.
  *
  * @param {string} currentVersion
+ * @param {'eager'|'soft'} [tone='eager']
  * @returns {boolean} true if a notification was printed
  */
-export function maybeEagerNotification(currentVersion) {
+export function maybeNotifyFromCache(currentVersion, tone = 'eager') {
   const state = readState()
   if (!state.latestVersion) return false
   if (compareSemver(state.latestVersion, currentVersion) <= 0) return false
-  printNotification(currentVersion, state.latestVersion, 'eager')
+  printNotification(currentVersion, state.latestVersion, tone)
   return true
 }
 
+// Old name preserved as alias — `create` calls it without a tone arg
+// and gets the eager default. Keeps that call site unchanged.
+export const maybeEagerNotification = maybeNotifyFromCache
+
 /**
  * Start a non-blocking update check.
  *