uniweb 0.13.6 → 0.13.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.13.6",
+  "version": "0.13.8",
   "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/kit": "0.9.38",
-    "@uniweb/core": "0.7.30",
-    "@uniweb/runtime": "0.8.37"
+    "@uniweb/kit": "0.9.40",
+    "@uniweb/runtime": "0.8.38",
+    "@uniweb/core": "0.7.31"
   },
   "peerDependencies": {
-    "@uniweb/build": "0.15.6",
-    "@uniweb/content-reader": "1.1.16",
-    "@uniweb/semantic-parser": "1.1.19"
+    "@uniweb/content-reader": "1.1.17",
+    "@uniweb/semantic-parser": "1.1.20",
+    "@uniweb/build": "0.15.8"
   },
   "peerDependenciesMeta": {
     "@uniweb/build": {

package/partials/agents.md

@@ -472,6 +472,8 @@ Optional attributes: `{size=20}`, `{color=red}`. Custom SVGs: `![Logo](./logo.sv
 
 **Quote values containing spaces:** `{note="Ready to go"}`, not `{note=Ready to go}` — unquoted values end at the first space.
 
+**Separators are forgiving.** `:` works wherever `=` does, and pairs may be separated by whitespace, a comma, or both — `{role=banner width=1200}`, `{role:banner, width:1200}` and `{role:banner,width:1200}` are identical. `=` and spaces are canonical, and that is what gets written back on save. Two rules keep it unambiguous: the separator must **touch** the key (`{note:warning}` is one pair, `{note : warning}` is two flags), and a value containing a **comma** must be quoted (`{style="a, b"}`). A value containing a colon needs no quoting — only the first colon separates, so `{href:https://example.com}` is fine.
+
 Standalone links (alone on a line) become buttons in `content.links[]`. Inline links stay as `<a>` tags inside `content.paragraphs[]`. Multiple links sharing a paragraph are all promoted:
 
 ```markdown
@@ -1278,8 +1280,9 @@ Pages are sequences of sections — the obvious layer. The framework also suppor
 | **Items** (`content.items`) | Heading groups within one `.md` | Repeating content in one section: cards, features, FAQ entries |
 | **Child sections** (`block.childBlocks`) | `@`-prefixed `.md` files + `nest:` | Children needing their own section type, rich content, or independent editing |
 | **Insets** (`block.insets`) | `![](@Component)` in markdown | Self-contained visuals/widgets: charts, diagrams, code demos |
+| **Block insets** (`block.insets`) | ` ```@Component ` fence around markdown | A component that *wraps* authored prose: callouts, disclosures, admonitions |
 
-Does the author write content *inside* the nested element? **Yes** → child sections. **No** (self-contained, param-driven) → inset. Repeating same-structure groups → items. These compose: a child section can contain insets; items work inside children.
+Does the author write content *inside* the nested element? **Yes** → child sections, or a block inset when the wrapper is presentational and lives mid-page. **No** (self-contained, param-driven) → inset. Repeating same-structure groups → items. These compose: a child section can contain insets; items work inside children; a block inset can contain both.
 
 **Insets — embedding components in content.** Many section types need a "visual" — a hero's illustration, a split-content section's media. Classically an image or video. But what if it's a JSX + SVG diagram, a ThreeJS animation, an interactive playground? Elsewhere you'd reach for MDX or prop-drilling. Here the author writes standard image syntax:
 
@@ -1297,6 +1300,23 @@ The developer builds `NetworkDiagram` as an ordinary React component with `inset
 
 **Don't use `hidden: true` on insets.** `hidden` means "don't export this component at all" (internal helpers); `inset: true` means "available for `@Component` references in markdown."
 
+**Block insets — a component that wraps content.** The image form is a leaf: it takes params but no body. When the component should surround authored prose — a callout, a disclosure, an admonition — use the fenced form instead. Same `@Component{params}` reference, written as a code fence's info string:
+
+````markdown
+```@Alert{type=warning}
+Back up your database **before** running this.
+
+- The migration is not reversible
+- Allow ten minutes of downtime
+```
+````
+
+The body is ordinary content, not text: it is parsed exactly like the rest of the page, so headings, lists, tables, icons, inline styling, leaf insets and further containers all work inside one. To nest a code block or another container, open the outer fence with more backticks than the inner one.
+
+**The component is yours, and it receives parsed content.** `@Alert` resolves against the foundation through the same lookup as `![](@NetworkDiagram)` — declare it with `inset: true` in `meta.js`. Where a leaf inset gets its alt text as `content.title` and nothing else, a container gets its whole body parsed: `title`, `paragraphs`, `items`, `sequence`. Render it with `<Prose content={content} block={block} />` or read the fields directly. A name the foundation doesn't define falls back to a plain bordered box that still shows the body — never a drop.
+
+Prefer a **child section** when the author needs their own section type and independent editing; prefer a **block inset** when the wrapper is presentational and belongs inline in a single file's prose.
+
 **Child sections.** You hit a complex layout — a 2:1 split with a panel and a main area. Your instinct says build a specialized component. Step back: the panel is a reusable section type, the main area is another, and the split is a Grid with `columns: "1fr 2fr"`. Your child components already adapt to narrow containers — container queries handle that. But hardcoding which components go where means the author can't rearrange or swap them. Child sections solve that:
 
 ```
@@ -1664,6 +1684,9 @@ uniweb add ci --target foundation # Publish a foundation for free at permanent v
 
 uniweb push / pull / clone / status   # Git-style content sync with the Uniweb backend
 uniweb register [--scope @org]        # Register a foundation + its data schemas to the registry
+uniweb login / logout                 # Start or clear the backend session the verbs above reuse
+uniweb org list / create <handle>     # Publish orgs you belong to — the @org in a scoped ref
+uniweb content export [dir]           # Package a site (or a built foundation's schema) as .uwx
 
 uniweb rename <foundation|site|extension> <old> <new>   # Rename across the whole workspace
 uniweb i18n extract / init / sync / status / audit      # Translation workflow (build first)
@@ -1678,6 +1701,8 @@ uniweb inspect <path>             # Show parsed content for a section or page (-
 uniweb <command> --help           # Per-command flags — no side effects. Prefer this over guessing.
 ```
 
+**Four verbs dispatch but are deliberately not listed above.** `invite`, `handoff` and `template` are **reserved names with no implementation** — the flows they named ran against a backend the CLI no longer talks to, and the names are held so a future rebuild doesn't need a breaking change. `runtime register` uploads a built runtime and is internal. Running any of them is not useful; their absence from this list is the answer, not an omission to fix.
+
 ### Where a site can live
 
 **There is no lock-in, and no default you're pushed toward.** Four independent paths, and a project can change its mind:

package/src/backend/site-media.js

@@ -24,16 +24,24 @@ import { contentTypeFor } from '../utils/code-upload.js'
  * @param {string} siteDir - the site root (site-root refs resolve under public/)
  * @param {string[]} refs - site-root local asset refs (`/images/x.png`)
  * @param {{ onProgress?: (m: string) => void, warn?: (m: string) => void }} [opts]
- * @returns {Promise<Record<string,string>>} ref → serve URL (only resolved + uploaded refs)
+ * @returns {Promise<{ map: Record<string,string>, missing: string[], failed: Array<{path:string,status:number,detail?:string}> }>}
+ *   `map` is ref → serve URL for refs that resolved AND uploaded. The two failure
+ *   kinds are reported SEPARATELY because callers must treat them differently:
+ *   `missing` is a ref with no file under the site — an authoring mistake, already
+ *   broken before us, worth a warning; `failed` is a ref whose bytes we could not
+ *   store — a transport or QUOTA refusal, and shipping content that still points at
+ *   the local path would publish a broken image while only warning about it.
  */
 export async function uploadSiteMedia(client, siteDir, refs, { onProgress, warn } = {}) {
-  if (!refs?.length) return {}
+  if (!refs?.length) return { map: {}, missing: [], failed: [] }
 
   const files = []
+  const missing = []
   for (const ref of refs) {
     const { resolved } = resolveAssetPath(ref, siteDir, siteDir)
     if (!resolved || !existsSync(resolved)) {
       warn?.(`local-media: ${ref} not found under the site (skipped)`)
+      missing.push(ref)
       continue
     }
     const bytes = readFileSync(resolved)
@@ -46,10 +54,11 @@ export async function uploadSiteMedia(client, siteDir, refs, { onProgress, warn
       diskPath: resolved,
     })
   }
-  if (!files.length) return {}
+  if (!files.length) return { map: {}, missing, failed: [] }
 
   const result = await client.uploadSiteAssets({ files, onProgress })
-  for (const f of result.failed || []) warn?.(`local-media: upload failed for ${f.path} (HTTP ${f.status})`)
+  const failed = result.failed || []
+  for (const f of failed) warn?.(`local-media: upload failed for ${f.path} (HTTP ${f.status})`)
 
   const config = await client.discover()
   const map = {}
@@ -57,5 +66,25 @@ export async function uploadSiteMedia(client, siteDir, refs, { onProgress, warn
     const entry = result.assetsByLocalUrl[ref]
     if (entry) map[ref] = entry.serveUrl || buildAssetUrl(client.origin, config.assetBase, entry.id, entry.ext)
   }
-  return map
+  return { map, missing, failed }
+}
+
+/**
+ * Is this asset-lane error the backend refusing on storage grounds?
+ *
+ * The plan step throws `Asset plan failed: HTTP <status>` for any non-2xx, so a quota
+ * refusal is currently indistinguishable from any other rejection except by status.
+ * These three are the plausible spellings — 402 (payment required), 413 (payload too
+ * large), 507 (insufficient storage).
+ *
+ * DELIBERATELY a heuristic, and it should not stay one: the backend owes a typed
+ * error carrying used / limit / needed so the CLI can say what a push costs and what
+ * is left. Until that contract exists this at least turns an opaque HTTP number into
+ * the right advice. See the collab charter in the handoff.
+ *
+ * @param {Error} err
+ * @returns {boolean}
+ */
+export function isStorageRefusal(err) {
+  return /Asset plan failed: HTTP (402|413|507)\b/.test(err?.message || '')
 }

package/src/commands/publish.js

@@ -65,7 +65,7 @@ import {
   pushSyncPackages,
 } from '../backend/site-sync.js'
 import { uploadDataBundle } from '../backend/data-bundle.js'
-import { uploadSiteMedia } from '../backend/site-media.js'
+import { uploadSiteMedia, isStorageRefusal } from '../backend/site-media.js'
 import { bringFoundationAlong } from '../backend/foundation-bring-along.js'
 import { settlePaymentIfNeeded } from '../backend/payment-handoff.js'
 
@@ -275,14 +275,29 @@ export async function publish(args = []) {
   if (mediaRefs.length) {
     say.info('Uploading media…')
     try {
-      const map = await uploadSiteMedia(client, siteDir, mediaRefs, {
+      const { map, failed } = await uploadSiteMedia(client, siteDir, mediaRefs, {
         onProgress: (m) => say.dim(`  ${m}`),
         warn: (m) => say.dim(`! ${m}`),
       })
+      // A ref whose bytes did not land must NOT be published: the content would go
+      // out still pointing at the local path, so the site ships a broken image and
+      // the only trace is a warning nobody reads. A missing FILE is different —
+      // already broken before us, warned above, and not worth blocking a publish.
+      if (failed.length) {
+        say.err(`${failed.length} asset(s) failed to upload — not publishing.`)
+        for (const f of failed) say.dim(`  ${f.path} (HTTP ${f.status})`)
+        return { exitCode: 1 }
+      }
       if (Object.keys(map).length) assetRewrite = map
       if (ballAssets.length) ball = rewriteBallAssets(ball, map)
       say.dim(`Media          : ${Object.keys(map).length}/${mediaRefs.length} ref(s) → serve URL`)
     } catch (err) {
+      if (isStorageRefusal(err)) {
+        say.err('Storage quota reached — the media in this publish does not fit.')
+        say.dim('  Remove or shrink assets, or raise the plan limit, then re-run.')
+        say.dim(`  ${err.message}`)
+        return { exitCode: 1 }
+      }
       say.err(`Media upload failed: ${err.message}`)
       return { exitCode: 1 }
     }

package/src/commands/push.js

@@ -55,6 +55,7 @@
 import { writeFileSync } from 'node:fs'
 import { resolve } from 'node:path'
 import { emitSyncPackages } from '@uniweb/build/uwx'
+import { uploadSiteMedia, isStorageRefusal } from '../backend/site-media.js'
 import { BackendClient } from '../backend/client.js'
 import { resolveSiteDir, resolveSiteBackend } from './deploy.js'
 import {
@@ -131,6 +132,75 @@ export async function push(args = []) {
   // to what a real push would send. Only the network RECOVERY is skipped, so a
   // preview never reaches the backend. (Emitting `{}` here instead would make the
   // preview quietly unrepresentative, which is the one thing `-o` exists to avoid.)
+  // Local media rides the SAME asset lane `publish` uses, and it rides it FIRST.
+  //
+  // Push is the collaboration verb: a teammate opens the site in the visual app
+  // right after it. Content that still points at `/images/hero.png` — bytes the
+  // backend never received — shows them a broken image, which is precisely what
+  // push exists to avoid. `publish` uploaded and rewrote; push dropped
+  // `localAssets` on the floor.
+  //
+  // Ordering is deliberate: BEFORE `ensureItemUuids`, which mints uuids on the
+  // backend. A refusal here then leaves nothing minted and nothing submitted.
+  //
+  // The probe emit runs WITHOUT `priorHashes`, so it surfaces every local ref
+  // rather than only the changed ones. That is not waste — the lane is
+  // content-addressed with a `present` skip-list, so unchanged bytes are a no-op
+  // PUT. It is also what makes the storage rule fall out of the mechanism instead
+  // of needing a special case: a content-only push presents the same plan as last
+  // time, every file is already present, zero new bytes are requested, and no
+  // quota check can refuse it. Only a push that genuinely ADDS bytes can be
+  // blocked.
+  //
+  // It also has to be this emit that carries `assetRewrite` below: the push cache
+  // stores hashes of the REWRITTEN content, so the emit compared against it must
+  // rewrite too, or every entity reads as changed forever.
+  let assetRewrite = null
+  if (!output && !dryRun) {
+    let mediaRefs = []
+    try {
+      const probe = await emitSyncPackages(siteDir, {
+        ...(foundationDir ? { foundationDir } : {}),
+        resolveModel: makeModelResolver({ client, offline: false }),
+      })
+      mediaRefs = probe.localAssets || []
+    } catch (err) {
+      error(`Could not scan the site for local media: ${err.message}`)
+      return { exitCode: 2 }
+    }
+    if (mediaRefs.length) {
+      info('Uploading media…')
+      try {
+        const { map, failed } = await uploadSiteMedia(client, siteDir, mediaRefs, {
+          onProgress: (m) => note(`  ${m}`),
+          warn: (m) => note(`! ${m}`),
+        })
+        // Bytes that did not land must not be pushed around: the content would go
+        // up still naming the local path, so the teammate sees the broken image
+        // this whole change exists to prevent, and the only trace is a warning. A
+        // missing FILE is a different thing — already broken before us, warned by
+        // the uploader, and not worth blocking a push over.
+        if (failed.length) {
+          error(`${failed.length} asset(s) failed to upload — nothing was pushed.`)
+          for (const f of failed) note(`  ${f.path} (HTTP ${f.status})`)
+          return { exitCode: 1 }
+        }
+        if (Object.keys(map).length) assetRewrite = map
+        note(`${Object.keys(map).length}/${mediaRefs.length} media ref(s) → serve URL`)
+      } catch (err) {
+        if (isStorageRefusal(err)) {
+          error('Storage quota reached — this push adds media that does not fit.')
+          note('  A push that changes only content costs no storage and still works.')
+          note('  Remove or shrink the new assets, or raise the plan limit, then re-run.')
+          note(`  ${err.message}`)
+          return { exitCode: 1 }
+        }
+        error(`Media upload failed: ${err.message}`)
+        return { exitCode: 1 }
+      }
+    }
+  }
+
   const itemUuids = (output || dryRun)
     ? readItemUuids(siteDir)
     : await ensureItemUuids({ client, siteDir, note })
@@ -145,6 +215,7 @@ export async function push(args = []) {
       // Both grains are dropped together by --force: one flag, one meaning,
       // no partial-force mode.
       ...(force ? {} : { baseVersions: readBaseVersions(siteDir), itemBaseVersions: readItemBaseVersions(siteDir) }),
+      ...(assetRewrite ? { assetRewrite } : {}),
     })
   } catch (err) {
     error(`Could not build the sync package: ${err.message}`)

package/src/commands/update.js

@@ -31,6 +31,8 @@
  *   --no-agents         Skip the AGENTS.md step.
  *   --no-deps           Skip the deps-alignment step.
  *   --dry-run           Print survey + would-be writes; no mutations.
+ *   --verbose           List every surveyed dep, including aligned ones
+ *                       (the default collapses those to a count).
  *   --allow-mismatch    Refresh AGENTS.md even if declared deps lag.
  *   --yes               Don't prompt — apply edits and run the install.
  *   --non-interactive   Auto-detected; prints the plan, never mutates
@@ -50,6 +52,7 @@ import { detectWorkspacePm, installCmd, detectGlobalCliPm, globalCliUpdateCmd }
 import { writeJsonPreservingStyle } from '../utils/json-file.js'
 import { surveyWorkspaceDeps, compareSemver } from '../utils/dep-survey.js'
 import { checkWorkspaceInstall, readDeclaredFoundation } from '../utils/install-integrity.js'
+import { getLatestVersion } from '../utils/update-check.js'
 
 const colors = {
   reset: '\x1b[0m',
@@ -110,16 +113,45 @@ function findUniwebWorkspace(cwd) {
   }
 }
 
-/** Fetch the latest published CLI 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
+/**
+ * Trailing advisory: a newer CLI exists, and this run could not have used it.
+ *
+ * Placed AFTER the work, not before, because it is a what-to-do-next — the
+ * same reason update-check calls its post-command notice the 'soft' tone.
+ * It also has to be the last thing on screen when it fires: a run that ends
+ * on `✓ deps aligned` + `✓ AGENTS.md up to date` reads as "all good", and
+ * those ticks are measured against THIS CLI's matrix. True, and beside the
+ * point, when the CLI itself is two releases back.
+ *
+ * The remedy is per-provenance because the wrong one is useless advice:
+ *   - project-local — the version is pinned by the project's package.json,
+ *     so a global install is irrelevant. `npx uniweb@latest update` both
+ *     aligns the deps AND rewrites that pin, so it is self-healing; say so,
+ *     or the reader assumes they'll be back here next release.
+ *   - global — updating the global install is the durable fix.
+ *   - npx — skipped entirely. The version was chosen explicitly on the
+ *     command line, and the lead-in already named it.
+ *
+ * Exported for tests: this notice must fire when behind and stay silent
+ * when current, and it's the half of the command that had no coverage.
+ *
+ * @returns {boolean} true if a notice was printed.
+ */
+export function printStaleCliNotice({ cliVersion, latest, isNpx, isGlobal, globalPm }) {
+  if (isNpx) return false
+  if (!latest || compareSemver(latest, cliVersion) <= 0) return false
+
+  log('')
+  log(`${colors.yellow}⚠${colors.reset}  ${colors.bright}A newer uniweb is available:${colors.reset} ${colors.dim}v${cliVersion}${colors.reset} → ${colors.cyan}v${latest}${colors.reset}`)
+  if (isGlobal) {
+    log(`${colors.dim}This run aligned the project to v${cliVersion}'s matrix. To update the CLI:${colors.reset} ${colors.cyan}${globalCliUpdateCmd(globalPm)}${colors.reset}`)
+    log(`${colors.dim}Or align to the latest release without a global install:${colors.reset} ${colors.cyan}npx uniweb@latest update${colors.reset}`)
+  } else {
+    log(`${colors.dim}This run aligned the project to v${cliVersion}'s matrix — the version your project pins.${colors.reset}`)
+    log(`${colors.dim}To move to v${latest}:${colors.reset} ${colors.cyan}npx uniweb@latest update${colors.reset} ${colors.dim}(updates the pin too).${colors.reset}`)
   }
+  log('')
+  return true
 }
 
 /** Run a shell command, inheriting stdio. Resolves with the exit code. */
@@ -132,8 +164,22 @@ function runCommand(cmd, cwd) {
   })
 }
 
-/** Print the survey report grouped by package directory. */
-function printSurvey(report, cliVersion, agentsVersion) {
+/**
+ * Print the survey report grouped by package directory.
+ *
+ * Only rows that need attention get a line. An aligned dep renders as
+ * `0.9.37 → 0.9.37  aligned` — an identity mapping that says nothing, and
+ * on a typical workspace there are six of them. That is the whole screen
+ * on the command's most common outcome (a no-op), and it buries the one
+ * line that isn't noise. Aligned deps collapse to a count instead.
+ *
+ * `--verbose` restores the full table for anyone auditing the matrix.
+ *
+ * Exported for tests: the collapse is the point of the function, and a
+ * regression here is invisible — the command still works, it just stops
+ * being readable.
+ */
+export function printSurvey(report, cliVersion, agentsVersion, { verbose = false } = {}) {
   log('')
   log(`${colors.bright}uniweb CLI:${colors.reset}             v${cliVersion}`)
   log(`${colors.bright}AGENTS.md stamp:${colors.reset}        ${agentsVersion ? 'v' + agentsVersion : colors.dim + '(none)' + colors.reset}`)
@@ -145,8 +191,16 @@ function printSurvey(report, cliVersion, agentsVersion) {
     return
   }
 
+  const needsAttention = report.rows.filter(r => r.status !== 'aligned')
+  const shown = verbose ? report.rows : needsAttention
+  const alignedCount = report.rows.length - needsAttention.length
+
+  // Everything aligned and not auditing: step 1's success line says so in
+  // one sentence. A header over an empty table is worse than no header.
+  if (shown.length === 0) return
+
   const byDir = {}
-  for (const row of report.rows) {
+  for (const row of shown) {
     if (!byDir[row.relDir]) byDir[row.relDir] = []
     byDir[row.relDir].push(row)
   }
@@ -171,6 +225,9 @@ function printSurvey(report, cliVersion, agentsVersion) {
       log(`    ${icon} ${row.name}${padding}  ${row.current.padEnd(10)} → ${row.target.padEnd(10)}  ${statusText}`)
     }
   }
+  if (!verbose && alignedCount > 0) {
+    log(`  ${colors.dim}(${alignedCount} other${alignedCount === 1 ? '' : 's'} already aligned — ${colors.reset}${colors.cyan}--verbose${colors.reset}${colors.dim} to list)${colors.reset}`)
+  }
   log('')
 }
 
@@ -228,6 +285,7 @@ export async function update(args = []) {
   const skipDeps = args.includes('--no-deps') || agentsOnly
   const dryRun = args.includes('--dry-run')
   const allowMismatch = args.includes('--allow-mismatch')
+  const verbose = args.includes('--verbose')
   const hasYes = args.includes('--yes')
   const nonInteractive = isNonInteractive(args)
   const isGlobal = isGlobalInstall()
@@ -248,30 +306,39 @@ export async function update(args = []) {
   if (inProject) {
     survey = await surveyWorkspaceDeps(workspaceDir)
     agentsVersion = readAgentsVersion(join(workspaceDir, 'AGENTS.md'))
-    printSurvey(survey, cliVersion, agentsVersion)
+    printSurvey(survey, cliVersion, agentsVersion, { verbose })
   }
 
   // ── This command reconciles the *project*, not the CLI ───────────
-  // Surface (but don't act on) a newer published CLI: this run aligns
-  // the project to *this* CLI's matrix.
+  // Which CLI is running is a lead-in — it belongs before the work. Whether
+  // that CLI is STALE is a what-to-do-next, and it is printed after the work
+  // by printStaleCliNotice() so it lands last instead of under two green
+  // ticks. The lookup happens here because the check must run on every
+  // provenance, not just a global install.
+  //
+  // Why the project-local path needs it MORE than the global one: a global
+  // CLI also gets the general notifier in index.js, but that is gated on
+  // `if (global)` — so a project-local run gets no staleness signal from
+  // anywhere. That is exactly the case where the user cannot work it out
+  // themselves, because the project pins the version. It was the quiet path
+  // and it should have been the loud one.
   let installPm = inProject ? detectWorkspacePm(workspaceDir) : null
+  const globalPm = isGlobal ? detectGlobalCliPm() : null
+  // Non-TTY reads cache only: scripted runs stay fast and offline-safe, the
+  // same convention `--version` follows in index.js. Skipped entirely when
+  // there is nothing to reconcile — the notice is never reached from those
+  // paths, and looking it up anyway would spend a network call on nothing.
+  const latestCli = (isNpx || !inProject)
+    ? null
+    : await getLatestVersion({ allowNetwork: !!process.stdout.isTTY })
+
   if (isNpx) {
     log(`${colors.dim}Running${colors.reset} ${colors.cyan}uniweb@${cliVersion}${colors.reset} ${colors.dim}via npx — aligning this project to v${cliVersion}'s matrix.${colors.reset}`)
     log(`${colors.dim}(To install the CLI:${colors.reset} ${colors.cyan}npm i -g uniweb${colors.reset}${colors.dim}.)${colors.reset}`)
     log('')
-  } else if (isGlobal) {
-    const latest = await fetchLatestVersion()
-    if (latest && compareSemver(latest, cliVersion) > 0) {
-      const pm = detectGlobalCliPm()
-      log(`${colors.yellow}A newer uniweb is available:${colors.reset} ${colors.dim}v${cliVersion}${colors.reset} → ${colors.cyan}v${latest}${colors.reset}`)
-      log(`${colors.dim}This run aligns the project to v${cliVersion}. To update the CLI:${colors.reset} ${colors.cyan}${globalCliUpdateCmd(pm)}${colors.reset}`)
-      log(`${colors.dim}Or, to align to the latest release without a global install:${colors.reset} ${colors.cyan}npx uniweb@latest update${colors.reset}`)
-      log('')
-    }
-  } else {
+  } else if (!isGlobal) {
     // Project-local copy (lives in this project's node_modules).
     log(`${colors.dim}Running the project-local CLI (v${cliVersion}) — pinned by your project's${colors.reset} ${colors.cyan}package.json${colors.reset}${colors.dim}.${colors.reset}`)
-    log(`${colors.dim}To use a newer CLI, bump${colors.reset} ${colors.cyan}uniweb${colors.reset}${colors.dim} in${colors.reset} ${colors.cyan}package.json${colors.reset}${colors.dim} and re-install, or run${colors.reset} ${colors.cyan}npx uniweb@latest update${colors.reset}${colors.dim}.${colors.reset}`)
     log('')
   }
 
@@ -289,7 +356,8 @@ export async function update(args = []) {
 
   if (!skipDeps && survey) {
     if (!survey.anyDrift) {
-      success('Workspace deps are aligned with the CLI.')
+      // The count carries the work the collapsed table no longer shows.
+      success(`Workspace deps are aligned with the CLI (${survey.rows.length} checked).`)
       if (survey.anyAhead) {
         log(`${colors.dim}(Some deps are ahead of the CLI's bundled matrix — left untouched.)${colors.reset}`)
       }
@@ -438,6 +506,11 @@ export async function update(args = []) {
   if (!dryRun && (depsEdited || agentsResult === 'created' || agentsResult === 'updated')) {
     printSummary({ editedPaths, depsEdited, installRan, installPm, agentsResult, cliVersion })
   }
+
+  // Last, deliberately — see printStaleCliNotice. Everything above reports
+  // against THIS CLI's matrix; if the CLI itself is behind, that is the note
+  // the reader should leave with.
+  printStaleCliNotice({ cliVersion, latest: latestCli, isNpx, isGlobal, globalPm })
 }
 
 /**

package/src/framework-index.json

@@ -1,9 +1,9 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-07-26T22:08:46.287Z",
+  "generatedAt": "2026-07-27T15:44:34.893Z",
   "packages": {
     "@uniweb/build": {
-      "version": "0.15.6",
+      "version": "0.15.8",
       "path": "framework/build",
       "deps": [
         "@uniweb/content-reader",
@@ -16,17 +16,17 @@
       ]
     },
     "@uniweb/content-reader": {
-      "version": "1.1.16",
+      "version": "1.1.17",
       "path": "framework/content-reader",
       "deps": []
     },
     "@uniweb/content-writer": {
-      "version": "0.2.8",
+      "version": "0.2.9",
       "path": "framework/content-writer",
       "deps": []
     },
     "@uniweb/core": {
-      "version": "0.7.30",
+      "version": "0.7.31",
       "path": "framework/core",
       "deps": [
         "@uniweb/semantic-parser",
@@ -44,7 +44,7 @@
       "deps": []
     },
     "@uniweb/kit": {
-      "version": "0.9.38",
+      "version": "0.9.40",
       "path": "framework/kit",
       "deps": [
         "@uniweb/core",
@@ -62,7 +62,7 @@
       "deps": []
     },
     "@uniweb/projections": {
-      "version": "0.1.1",
+      "version": "0.1.2",
       "path": "framework/projections",
       "deps": [
         "@uniweb/content-writer",
@@ -70,7 +70,7 @@
       ]
     },
     "@uniweb/runtime": {
-      "version": "0.8.37",
+      "version": "0.8.38",
       "path": "framework/runtime",
       "deps": [
         "@uniweb/core",
@@ -93,7 +93,7 @@
       "deps": []
     },
     "@uniweb/semantic-parser": {
-      "version": "1.1.19",
+      "version": "1.1.20",
       "path": "framework/semantic-parser",
       "deps": []
     },
@@ -108,7 +108,7 @@
       "deps": []
     },
     "@uniweb/unipress": {
-      "version": "0.5.5",
+      "version": "0.5.7",
       "path": "framework/unipress",
       "deps": [
         "@uniweb/build",

package/src/utils/update-check.js

@@ -103,6 +103,61 @@ export function maybeNotifyFromCache(currentVersion, tone = 'eager') {
 // and gets the eager default. Keeps that call site unchanged.
 export const maybeEagerNotification = maybeNotifyFromCache
 
+/**
+ * Resolve the latest published CLI version WITHOUT printing anything.
+ *
+ * The notify helpers in this module own both the lookup and the message.
+ * That's right for callers who want the house notice, and wrong for callers
+ * whose remedy differs — `uniweb update` running from a project's
+ * node_modules can't tell the user to `npm i -g uniweb`, because the version
+ * they're on is pinned by their own package.json. Those callers need the
+ * fact, not the sentence.
+ *
+ * Caching and the timeout live here rather than at the call site so every
+ * lookup gets them. `update.js` previously had its own copy with neither: an
+ * unbounded `await fetch()` before the command did any work, which turns a
+ * flaky network into a hang on a routine verb.
+ *
+ * @param {object} [opts]
+ * @param {number} [opts.timeoutMs=1500] Network cap. Slow/offline returns
+ *   whatever the cache holds rather than blocking.
+ * @param {boolean} [opts.allowNetwork=true] False = cache-only. Pass false
+ *   for non-TTY callers; scripts must stay fast and offline-safe (the same
+ *   convention `--version` follows).
+ * @param {number} [opts.maxAgeMs] How old a cache entry may be before a
+ *   refetch is attempted. Defaults to the module's 1-day interval.
+ * @returns {Promise<string|null>} The latest version, or null if unknown.
+ */
+export async function getLatestVersion({
+  timeoutMs = 1500,
+  allowNetwork = true,
+  maxAgeMs = CHECK_INTERVAL,
+} = {}) {
+  const state = readState()
+  const cached = state.latestVersion || null
+  const fresh = state.lastCheck && (Date.now() - state.lastCheck) < maxAgeMs
+  if (fresh && cached) return cached
+  // A stale cache entry still beats nothing for an advisory, so it's the
+  // fallback for every failure path below rather than a hard null.
+  if (!allowNetwork) return cached
+
+  const controller = new AbortController()
+  const timer = setTimeout(() => controller.abort(), timeoutMs)
+  try {
+    const res = await fetch('https://registry.npmjs.org/uniweb/latest', { signal: controller.signal })
+    if (!res.ok) return cached
+    const data = await res.json()
+    const latest = data?.version || null
+    if (!latest) return cached
+    writeState({ lastCheck: Date.now(), latestVersion: latest })
+    return latest
+  } catch {
+    return cached
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
 /**
  * Fetch the latest version (with a tight timeout) and print a notice if
  * a newer version is found. Updates the on-disk cache as a side effect