uniweb 1.0.2 → 1.2.0

package/src/commands/build.js

@@ -58,14 +58,15 @@ import {
   discoverComponents,
   resolveFoundationSrcPath,
   classifyPackage,
-  isExtensionPackage
+  isExtensionPackage,
+  detectFoundationType
 } from '@uniweb/build'
 import {
   resolveDefaultLocale,
   normalizeLanguageList
 } from '@uniweb/core/locale-config'
 import { readSiteConfig } from '@uniweb/build/site'
-import { readWorkspaceConfig, resolveGlob } from '../utils/config.js'
+import { workspacePackages } from '../utils/workspace-packages.js'
 
 // Colors for terminal output
 const colors = {
@@ -289,10 +290,11 @@ async function buildFoundation(projectDir, options = {}) {
  *
  * Freshness rule: a built artifact (`dist/entry.js` or the legacy
  * `dist/foundation.js`) exists AND its mtime is >= the newest mtime of
- * any tracked source file. Tracked sources: every file under
- * `<foundation>/src/`, plus root-level `package.json`, `foundation.js`,
- * `meta.js` (the structural files that drive entry generation and
- * schema). Build outputs and node_modules are skipped.
+ * any tracked source file. Tracked sources: every file under the
+ * package's source root (the package itself when flat, `src/` when
+ * nested — `isFoundationSourceNewerThan`), plus root-level `package.json`,
+ * `foundation.js`, `meta.js` (the structural files that drive entry
+ * generation and schema). Build outputs and node_modules are skipped.
  *
  * Both artifact names are accepted because the foundation build emitter
  * was renamed `dist/foundation.js → dist/entry.js` in `@uniweb/build`
@@ -300,7 +302,7 @@ async function buildFoundation(projectDir, options = {}) {
  * the legacy name; we don't want the cascade to keep rebuilding such a
  * foundation forever just because the new name is missing.
  */
-async function ensureFoundationFresh(foundationDir, label = 'foundation') {
+export async function ensureFoundationFresh(foundationDir, label = 'foundation') {
   const distArtifact = findFoundationDistArtifact(foundationDir)
 
   if (!distArtifact) {
@@ -344,17 +346,26 @@ function findFoundationDistArtifact(foundationDir) {
 
 /**
  * Returns true if any tracked foundation source file has an mtime newer
- * than `referenceMtime`. Walks `<foundationDir>/src/` recursively (skipping
- * dotfiles, node_modules, and dist). Also stats the root structural files.
+ * than `referenceMtime`. Walks the package's source root — the folder
+ * `package.json::main` names (`resolveFoundationSrcPath`): the package itself
+ * for a flat package, `src/` for a nested one — recursively, skipping dotfiles,
+ * node_modules, dist and the generated entry. Also stats the root structural
+ * files.
+ *
+ * ⛔ Until 2026-10-13 it walked `<foundationDir>/src/` whatever the layout, and
+ * every package scaffolded since the flat layout keeps its sources at its root —
+ * so an edit to a section never made one stale. Measured: touching a section of
+ * a flat foundation and building its site rebuilt nothing, and prerender rendered
+ * the static HTML with the foundation as last built.
  */
-function isFoundationSourceNewerThan(foundationDir, referenceMtime) {
+export function isFoundationSourceNewerThan(foundationDir, referenceMtime) {
   const rootFiles = ['package.json', 'foundation.js', 'meta.js']
   for (const f of rootFiles) {
     const p = join(foundationDir, f)
     if (existsSync(p) && statSync(p).mtimeMs > referenceMtime) return true
   }
 
-  const srcDir = join(foundationDir, 'src')
+  const srcDir = resolveFoundationSrcPath(foundationDir)
   if (!existsSync(srcDir)) return false
 
   const stack = [srcDir]
@@ -370,6 +381,7 @@ function isFoundationSourceNewerThan(foundationDir, referenceMtime) {
       if (
         e.name === 'node_modules' ||
         e.name === 'dist' ||
+        e.name === '_entry.generated.js' ||
         e.name.startsWith('.')
       )
         continue
@@ -522,75 +534,34 @@ async function generateLocalizedHtml(projectDir, i18nConfig) {
 }
 
 /**
- * Resolve foundation directory based on site config and project structure
+ * The site's local foundation folder — what `site.yml::foundation` names, found by
+ * the build's one resolver (`detectFoundationType`, `@uniweb/build`) — or null
+ * when the foundation is a URL or a catalog ref, or does not resolve.
+ *
+ * Best-effort on purpose: the site's own build resolves the same declaration
+ * through the same function and raises the canonical error, so null here only
+ * skips what needs a local foundation — the freshness cascade, prerender's
+ * import, link mode's theme defaults.
+ *
+ * ⛔ Until 2026-10-13 this file held two copies of that resolver, weaker in
+ * different ways: one checked a same-named folder beside the site before the
+ * site's `file:` dep and took any folder, so a site named like its foundation
+ * resolved to itself; the other looked in `foundations/<name>` only when the
+ * site sat in a folder called `sites`, then fell back to `../foundation`
+ * whatever the site declared.
  *
- * Priority:
- * 1. Read site's package.json to find foundation dependency path (most reliable)
- * 2. Check foundations/{name} for multi-site projects
- * 3. Check ../foundation for single-site projects
- * 4. Check ../{name} as fallback
+ * @param {string} projectDir - the site's folder
+ * @param {object|null} [siteConfig] - its `site.yml`, when already read
+ * @returns {string|null}
  */
 function resolveFoundationDir(projectDir, siteConfig) {
-  const foundationName = siteConfig?.foundation
-
-  // First, try to resolve from site's package.json dependencies
-  // This is the most reliable method as it matches how Vite resolves imports
-  if (foundationName) {
-    const pkgPath = join(projectDir, 'package.json')
-    if (existsSync(pkgPath)) {
-      try {
-        const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'))
-        const deps = { ...pkg.dependencies, ...pkg.devDependencies }
-        const depValue = deps[foundationName]
-
-        // Check for file: protocol (local dependency)
-        if (depValue && depValue.startsWith('file:')) {
-          const relativePath = depValue.slice(5) // Remove 'file:' prefix
-          const resolvedPath = join(projectDir, relativePath)
-          if (existsSync(resolvedPath)) {
-            return resolvedPath
-          }
-        }
-      } catch {
-        // Ignore JSON parse errors, fall through to other methods
-      }
-    }
-  }
-
-  // Check if we're in a multi-site structure (site is under sites/)
-  const parentDir = join(projectDir, '..')
-  const grandParentDir = join(projectDir, '..', '..')
-  const isMultiSite =
-    parentDir.endsWith('/sites') || parentDir.endsWith('\\sites')
-
-  if (isMultiSite && foundationName) {
-    // Multi-site: look for foundations/{name}
-    const multiFoundationDir = join(
-      grandParentDir,
-      'foundations',
-      foundationName
-    )
-    if (existsSync(multiFoundationDir)) {
-      return multiFoundationDir
-    }
-  }
-
-  // Single site: ../foundation
-  const singleFoundationDir = join(projectDir, '..', 'foundation')
-  if (existsSync(singleFoundationDir)) {
-    return singleFoundationDir
-  }
-
-  // Fallback: try to find by foundation name in parent
-  if (foundationName) {
-    const namedFoundationDir = join(parentDir, foundationName)
-    if (existsSync(namedFoundationDir)) {
-      return namedFoundationDir
-    }
+  const cfg = siteConfig || readSiteConfig(projectDir)
+  try {
+    const info = detectFoundationType(cfg?.foundation, projectDir)
+    return info.type === 'local' ? info.path : null
+  } catch {
+    return null
   }
-
-  // Ultimate fallback
-  return singleFoundationDir
 }
 
 /**
@@ -633,10 +604,7 @@ async function buildSiteLink(projectDir, options = {}) {
   // 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)
+  const foundationDir = resolveFoundationDir(projectDir, siteConfig)
 
   // Link mode does NOT (re)build the foundation. It reads only the
   // foundation's SOURCE config (foundation.js::theme.vars, passed as
@@ -709,44 +677,6 @@ async function buildSiteLink(projectDir, options = {}) {
   )
 }
 
-/**
- * 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 (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
  */
@@ -844,8 +774,10 @@ async function buildSite(projectDir, options = {}) {
       const { prerenderSite } = await import('@uniweb/build/prerender')
 
       const result = await prerenderSite(projectDir, {
+        // `undefined`, not null, when there is none: prerenderSite skips a URL or
+        // catalog foundation before it reads this, and defaults it otherwise.
         foundationDir:
-          foundationDir || resolveFoundationDir(projectDir, siteConfig),
+          foundationDir || resolveFoundationDir(projectDir, siteConfig) || undefined,
         host,
         onProgress: (msg) => log(`  ${colors.dim}${msg}${colors.reset}`)
       })
@@ -927,23 +859,20 @@ async function discoverWorkspacePackages(workspaceDir) {
   const extensions = []
   const sites = []
 
-  const { packages } = await readWorkspaceConfig(workspaceDir)
-
-  for (const pattern of packages) {
-    const dirs = await resolveGlob(workspaceDir, pattern)
-    for (const dir of dirs) {
-      const fullPath = join(workspaceDir, dir)
-      const name = dir.split('/').pop()
+  // The workspace's packages as pnpm reads its patterns — each folder once. Named
+  // by their path: in a workspace of projects every foundation's folder is `src`.
+  for (const dir of workspacePackages(workspaceDir)) {
+    const fullPath = join(workspaceDir, dir)
+    const name = dir
 
-      if (isFoundation(fullPath)) {
-        if (isExtensionDir(fullPath)) {
-          extensions.push({ name, path: fullPath })
-        } else {
-          foundations.push({ name, path: fullPath })
-        }
-      } else if (isSite(fullPath)) {
-        sites.push({ name, path: fullPath })
+    if (isFoundation(fullPath)) {
+      if (isExtensionDir(fullPath)) {
+        extensions.push({ name, path: fullPath })
+      } else {
+        foundations.push({ name, path: fullPath })
       }
+    } else if (isSite(fullPath)) {
+      sites.push({ name, path: fullPath })
     }
   }
 
@@ -1193,10 +1122,7 @@ export async function build(args = []) {
       // to the local foundation when the user runs `uniweb build` from a
       // site dir on a fresh checkout where dist/ doesn't exist yet.
       const resolvedFoundationDir =
-        foundationDir ||
-        (await resolveFoundationDirForSite(projectDir, siteConfig).catch(
-          () => null
-        ))
+        foundationDir || resolveFoundationDir(projectDir, siteConfig)
 
       await buildSite(projectDir, {
         prerender,

package/src/commands/clone.js

@@ -54,9 +54,9 @@ import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs'
 import { join, resolve, basename, dirname } from 'node:path'
 import { spawnSync } from 'node:child_process'
 import { scaffoldWorkspace, scaffoldSite } from '../utils/scaffold.js'
-import { resolvePlacement, SITE_KIND } from '../utils/placement.js'
+import { resolvePlacement, projectConflictLines, SITE_KIND } from '../utils/placement.js'
 import { findWorkspaceRoot } from '../utils/workspace.js'
-import { addWorkspaceGlob } from '../utils/config.js'
+import { registerWorkspacePackage } from '../utils/config.js'
 import { detectWorkspacePm, installCmd } from '../utils/pm.js'
 import { BackendClient, describeRequestError, refusalDetail } from '../backend/client.js'
 import { resolveWorkspace } from '../backend/workspace.js'
@@ -298,6 +298,18 @@ export async function clone(args = [], deps = {}) {
       { path: pathFlag, project: projectFlag },
       SITE_KIND
     )
+    // `--project` names the folder itself, so a name or `--path` beside it is refused.
+    if (placement.projectConflict) {
+      const [first, ...rest] = projectConflictLines(
+        'site',
+        target,
+        { path: pathFlag, project: projectFlag },
+        `${getCliPrefix()} clone ${siteUuid}`
+      )
+      error(first)
+      for (const line of rest) note(line)
+      return { exitCode: 1 }
+    }
     if (placement.outsideRoot) {
       error(`--path must name a folder inside the workspace: ${placement.outsideRoot}`)
       note(
@@ -364,7 +376,7 @@ export async function clone(args = [], deps = {}) {
       `Adding site ${colors.bright}${sitePkgName}${colors.reset} to the workspace at ${colors.dim}${placement.relativePath}/${colors.reset} …`
     )
     await scaffoldSite(siteDir, siteContext, { onProgress })
-    await addWorkspaceGlob(existingRoot, placement.relativePath)
+    await registerWorkspacePackage(existingRoot, placement.relativePath)
   }
 
   // 4. Seed the identity this clone was pulled by, under the backend that minted it.

package/src/commands/dev.js

@@ -149,6 +149,8 @@ export async function dev(args = []) {
     )
   }
 
+  await ensureSiteExtensionsBuilt(sitePath)
+
   console.error(
     `${DIM}→ ${command}${RESET} ${DIM}(site: ${site.name}, dir: ${sitePath})${RESET}`
   )
@@ -162,6 +164,61 @@ export async function dev(args = []) {
   })
 }
 
+/**
+ * Build the site's workspace extensions that are missing or older than their
+ * sources, before its dev server starts — as `uniweb build` builds extensions
+ * before sites. A site loads a workspace extension from its BUILD in dev as in a
+ * built site (the dev server serves its `dist/`), so an unbuilt one is a 404 and a
+ * stale one is the code as it was. Found by the rule the build follows
+ * (`findSiteExtension`, `@uniweb/build`).
+ *
+ * Nothing watches an extension while the server runs: after editing one, run
+ * `uniweb build` and reload. A failed build warns and dev starts anyway — the
+ * site without its extension is still worth looking at.
+ */
+export async function ensureSiteExtensionsBuilt(sitePath) {
+  let build, readSiteConfig, ensureFoundationFresh
+  try {
+    build = await import('@uniweb/build')
+    ;({ readSiteConfig } = await import('@uniweb/build/site'))
+    ;({ ensureFoundationFresh } = await import('./build.js'))
+  } catch {
+    return // Not installed yet — the dev server says so in its own words.
+  }
+  let declared
+  try {
+    declared = readSiteConfig(sitePath)?.extensions
+  } catch {
+    return // An unreadable site.yml is the dev server's to report.
+  }
+  if (!Array.isArray(declared)) return
+
+  const dirs = new Set()
+  for (const entry of declared) {
+    const named = build.extensionNameOf(typeof entry === 'string' ? entry : entry?.url)
+    const dir = named && build.findSiteExtension(named.name, sitePath)
+    if (dir) dirs.add(dir)
+  }
+  const step = process.env.UNIWEB_BUILD_STEP
+  process.env.UNIWEB_BUILD_STEP = 'dev' // a step of `dev`: no "what next" after each build
+  try {
+    for (const dir of dirs) {
+      try {
+        await ensureFoundationFresh(dir, 'extension')
+      } catch (err) {
+        console.error(
+          `${YELLOW}⚠${RESET} Could not build the extension at ${dir}: ${err.message}`
+        )
+        console.error(`  The site will start without it. Fix it, then run \`uniweb build\` and reload.`)
+        console.error('')
+      }
+    }
+  } finally {
+    if (step === undefined) delete process.env.UNIWEB_BUILD_STEP
+    else process.env.UNIWEB_BUILD_STEP = step
+  }
+}
+
 /**
  * Say so if the site is about to be served from an install that no longer
  * matches the workspace. Warns rather than exits — the server may still be

package/src/commands/doctor.js

@@ -15,7 +15,9 @@ import yaml from 'js-yaml'
 import {
   resolveFoundationSrcPath,
   classifyPackage,
-  isExtensionPackage as buildIsExtensionPackage
+  isExtensionPackage as buildIsExtensionPackage,
+  extensionNameOf,
+  findSiteExtension
 } from '@uniweb/build'
 import { loadDeployYml, AGENTS_KEYS } from '@uniweb/build/site'
 import { listAdapters } from '@uniweb/build/hosts'
@@ -26,6 +28,7 @@ import { writeJsonPreservingStyle } from '../utils/json-file.js'
 import { surveyWorkspaceDeps } from '../utils/dep-survey.js'
 import { discoverFoundations, discoverSites } from '../utils/discover.js'
 import { checkSiteInstall } from '../utils/install-integrity.js'
+import { editWorkspaceFilePackages } from '../utils/workspace-packages.js'
 import { findWorkspaceRoot } from '../utils/workspace.js'
 import { DATA_DIR } from '@uniweb/core/data-paths'
 import { FAMILIES, resolveFamily } from '@uniweb/schemas/families'
@@ -1090,7 +1093,7 @@ export async function doctor(args = []) {
 
   // Workspace manifest sync — keep `pnpm-workspace.yaml::packages` and
   // `package.json::workspaces` aligned. The CLI writes both on every
-  // mutation (see addWorkspaceGlob in utils/config.js), but a user who
+  // mutation (see registerWorkspacePackage in utils/config.js), but a user who
   // manually edits one can introduce drift. Drift breaks projects that
   // switch package managers (pnpm-workspace.yaml is pnpm-only;
   // package.json::workspaces is what npm and yarn read).
@@ -1133,21 +1136,28 @@ export async function doctor(args = []) {
       if (onlyInPkg.length)
         log(`    only in package.json::workspaces:    ${onlyInPkg.join(', ')}`)
       if (shouldFix('workspace-manifests-out-of-sync')) {
-        // Canonical resolution: write the union to both manifests.
-        const union = Array.from(
-          new Set([...ymlPackages, ...pkgWorkspaces])
-        ).sort()
-        writeFileSync(
-          ymlPath,
-          yaml.dump({ packages: union }, { flowLevel: -1, quotingType: '"' })
-        )
-        const rootPkgPath = join(workspaceDir, 'package.json')
-        const rootPkgSrc = readFileSync(rootPkgPath, 'utf-8')
-        const rootPkg = JSON.parse(rootPkgSrc)
-        rootPkg.workspaces = union
-        writeJsonPreservingStyle(rootPkgPath, rootPkg, rootPkgSrc)
-        issue.fixed = true
-        fixed(`wrote union [${union.join(', ')}] to both manifests`)
+        // Canonical resolution: each manifest gains what only the other lists. The
+        // yaml is edited in place — its comments and every other key stay.
+        // ⛔ Until 2026-10-13 it was rewritten as `{ packages: union }`, deleting
+        // `onlyBuiltDependencies` and `allowBuilds` with the comments that explain them.
+        const nextYml = editWorkspaceFilePackages(readFileSync(ymlPath, 'utf8'), (list) => [
+          ...list,
+          ...onlyInPkg
+        ])
+        if (nextYml == null) {
+          warn(
+            `Could not edit the packages: list in pnpm-workspace.yaml in place, and it is not rewritten whole. Add ${onlyInPkg.join(', ')} to it by hand.`
+          )
+        } else {
+          writeFileSync(ymlPath, nextYml)
+          const rootPkgPath = join(workspaceDir, 'package.json')
+          const rootPkgSrc = readFileSync(rootPkgPath, 'utf-8')
+          const rootPkg = JSON.parse(rootPkgSrc)
+          rootPkg.workspaces = [...pkgWorkspaces, ...onlyInYml]
+          writeJsonPreservingStyle(rootPkgPath, rootPkg, rootPkgSrc)
+          issue.fixed = true
+          fixed(`both manifests now list [${[...ymlPackages, ...onlyInPkg].join(', ')}]`)
+        }
       } else {
         log(
           `  ${colors.dim}Pick one set of globs and copy it to the other manifest. The two should always match — pnpm reads pnpm-workspace.yaml, npm/yarn read package.json::workspaces.${colors.reset}`
@@ -1674,37 +1684,31 @@ export async function doctor(args = []) {
     }
   }
 
-  // Validate extension URLs in site.yml
+  // Validate site-relative extension URLs in site.yml — by the rule the build
+  // follows to copy the extension into the site (`findSiteExtension`, from
+  // `@uniweb/build`), so doctor reports what the build will do. ⛔ Until
+  // 2026-10-13 doctor parsed the URL itself and matched any workspace extension
+  // of that name, wherever it was, so it passed a site whose build could not
+  // find its extension.
   for (const site of sites) {
     const siteYml = loadSiteYml(site.path)
     if (!siteYml?.extensions || !Array.isArray(siteYml.extensions)) continue
 
-    for (const extUrl of siteYml.extensions) {
-      if (typeof extUrl !== 'string') continue
-
-      // Skip remote URLs — can't validate those
-      if (extUrl.startsWith('http://') || extUrl.startsWith('https://'))
-        continue
-
-      // Local extension URL: check if it maps to a known extension
-      // URLs like /effects/foundation.js or /extensions/effects/foundation.js
-      const urlParts = extUrl.replace(/^\//, '').split('/')
-      const extName =
-        urlParts.length >= 2 ? urlParts[urlParts.length - 2] : urlParts[0]
-
-      // Check if a matching extension exists and is built
-      const matchingExt = extensions.find(
-        (e) => e.folderName === extName || e.name === extName
-      )
-      if (
-        matchingExt &&
-        !existsSync(join(matchingExt.path, 'dist', 'entry.js'))
-      ) {
-        issues.push({
-          type: 'warn',
-          site: site.name,
-          message: `Extension "${extName}" referenced in site.yml is not built`
-        })
+    for (const entry of siteYml.extensions) {
+      const url = typeof entry === 'string' ? entry : entry?.url
+      // Remote URLs and catalog refs are not the site's to serve.
+      const named = extensionNameOf(url)
+      if (!named) continue
+
+      const dir = findSiteExtension(named.name, site.path)
+      if (!dir) {
+        const message = `site.yml lists ${url}, and no workspace extension named '${named.name}' is where the site looks: ${named.name}/ or extensions/${named.name}/, in the folder the site is in or a folder above it, up to the workspace root. The build cannot copy it, and the site will 404 on it.`
+        issues.push({ type: 'warn', site: site.name, message })
+        warn(`[${site.name}] ${message}`)
+      } else if (!existsSync(join(dir, 'dist', named.rest))) {
+        const message = `Extension '${named.name}' (${relative(workspaceDir, dir)}/) referenced in site.yml is not built`
+        issues.push({ type: 'warn', site: site.name, message })
+        warn(`[${site.name}] ${message}`)
       }
     }
   }

package/src/commands/rename.js

@@ -51,8 +51,7 @@ import yaml from 'js-yaml'
 import { isExtensionPackage } from '@uniweb/build'
 import { findWorkspaceRoot } from '../utils/workspace.js'
 import {
-  readWorkspaceConfig,
-  writeWorkspaceConfig,
+  moveWorkspacePackage,
   readRootPackageJson,
   writeRootPackageJson,
   updateRootScripts
@@ -150,31 +149,17 @@ function computeNewFolderPath(rootDir, oldPath, oldName, newName) {
 }
 
 /**
- * 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.
+ * Update the workspace manifests when a folder path moves — in place, through the
+ * one editor of the workspace file (`moveWorkspacePackage`): an entry naming the
+ * old path is renamed, a pattern (`extensions/*`) is left as written, and the new
+ * path is registered if no pattern covers it any more. Both pnpm-workspace.yaml and
+ * package.json::workspaces are kept in sync (the multi-PM compatibility invariant).
+ *
+ * ⛔ Until 2026-10-13 the yaml was rewritten from its `packages` alone, deleting its
+ * comments, `onlyBuiltDependencies` and `allowBuilds`.
  */
-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)
-  }
+async function updateWorkspaceManifestsForFolderMove(rootDir, oldPath, newPath) {
+  await moveWorkspacePackage(rootDir, oldPath, newPath)
 }
 
 /**

package/src/commands/update.js

@@ -304,11 +304,13 @@ export function printSurvey(
       const r = breakingRows.find((x) => x.name === name)
       log(`     ${colors.red}${name}${colors.reset}  ${r.current} → ${r.target}  ${colors.dim}(${r.bump})${colors.reset}`)
     }
+    // ⛔ The second line said "Read their changelogs before shipping" until 2026-10-13,
+    // when most packages kept none.
     log(
-      `   ${colors.dim}A minor version is where Uniweb's breaking changes go, so these are releases${colors.reset}`
+      `   ${colors.dim}A minor version is where Uniweb's breaking changes go (a major is rarer still),${colors.reset}`
     )
     log(
-      `   ${colors.dim}you may need to act on. Read their changelogs before shipping.${colors.reset}`
+      `   ${colors.dim}so these are releases you may need to act on: build and check before shipping.${colors.reset}`
     )
   }
   log('')
@@ -374,6 +376,8 @@ export async function update(args = []) {
   const depsOnly = args.includes('--deps-only')
   const skipAgents = args.includes('--no-agents') || depsOnly
   const skipDeps = args.includes('--no-deps') || agentsOnly
+  // The flag that kept the deps step from running — what the AGENTS.md step's hint names.
+  const depsSkippedBy = agentsOnly ? '--agents-only' : skipDeps ? '--no-deps' : null
   const dryRun = args.includes('--dry-run')
   const allowMismatch = args.includes('--allow-mismatch')
   const verbose = args.includes('--verbose')
@@ -636,6 +640,7 @@ export async function update(args = []) {
       hasYes,
       nonInteractive,
       agentsOnly,
+      depsSkippedBy,
       depsEdited,
       installRan,
       installPm
@@ -734,6 +739,7 @@ async function refreshAgents(ctx) {
     hasYes,
     nonInteractive,
     agentsOnly,
+    depsSkippedBy,
     depsEdited,
     installRan,
     installPm
@@ -757,13 +763,21 @@ async function refreshAgents(ctx) {
   // Re-survey: deps may have just been edited+installed, which clears the
   // declared-deps gate.
   const finalSurvey = await surveyWorkspaceDeps(workspaceDir)
-  if (finalSurvey.anyDrift && !allowMismatch) {
+  // ⭐ A dry run moves no deps, so they still lag here whenever the deps step has
+  // something to align — while the run it previews aligns and installs them before
+  // this step. Say what that run would do, rather than that this step would skip.
+  const onceInstalled = finalSurvey.anyDrift && dryRun && !depsSkippedBy
+  if (finalSurvey.anyDrift && !allowMismatch && !onceInstalled) {
     warn('AGENTS.md refresh skipped: workspace deps still lag the CLI.')
     log(
       `${colors.dim}AGENTS.md from v${cliVersion} would document features not in your installed packages.${colors.reset}`
     )
+    // ⛔ This always said "Re-run without --no-deps": wrong under --agents-only, and
+    // when the deps edit was declined or left to a non-interactive run's plan.
     log(
-      `${colors.dim}Re-run without ${colors.reset}${colors.cyan}--no-deps${colors.reset}${colors.dim}, or pass ${colors.reset}${colors.cyan}--allow-mismatch${colors.reset}${colors.dim} to override.${colors.reset}`
+      depsSkippedBy
+        ? `${colors.dim}Re-run without ${colors.reset}${colors.cyan}${depsSkippedBy}${colors.reset}${colors.dim}, or pass ${colors.reset}${colors.cyan}--allow-mismatch${colors.reset}${colors.dim} to override.${colors.reset}`
+        : `${colors.dim}Align the deps first — accept the edit, or re-run with ${colors.reset}${colors.cyan}--yes${colors.reset}${colors.dim} — or pass ${colors.reset}${colors.cyan}--allow-mismatch${colors.reset}${colors.dim} to override.${colors.reset}`
     )
     log('')
     if (agentsOnly) process.exit(1)
@@ -797,7 +811,7 @@ async function refreshAgents(ctx) {
 
   if (dryRun) {
     info(
-      `Dry-run: would ${currentAgentsVersion ? `update AGENTS.md (v${currentAgentsVersion} → v${cliVersion})` : `create AGENTS.md (v${cliVersion})`}${keeping}.`
+      `Dry-run: would ${currentAgentsVersion ? `update AGENTS.md (v${currentAgentsVersion} → v${cliVersion})` : `create AGENTS.md (v${cliVersion})`}${keeping}${onceInstalled ? ', once the deps above are installed' : ''}.`
     )
     return 'skipped'
   }