uniweb 0.87.4 → 0.88.1

package/README.md

@@ -268,7 +268,7 @@ _Foundation-first_ — You're building a component system. The site is a test ha
 
 ## Growing Your Project
 
-> **Install the CLI globally** with `npm i -g uniweb` for the best experience. You can also use `npx uniweb` or `pnpm uniweb` without a global install.
+> **Install the CLI globally** with `npm i -g uniweb` for the best experience — inside a project it runs the project's own copy. Keep it current: `create` and `clone` start a project on the CLI that runs them, so a global install stops them when a newer release is out. Without a global install, use `npx uniweb@latest create` to start a project and `pnpm uniweb` inside one.
 
 Start simple. Add what you need, when you need it:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.87.4",
+  "version": "0.88.1",
   "description": "Create structured Vite + React sites with content/code separation",
   "type": "module",
   "bin": {
@@ -41,17 +41,17 @@
     "js-yaml": "^4.1.0",
     "prompts": "^2.4.2",
     "tar": "^7.0.0",
+    "@uniweb/core": "^0.38.0",
     "@uniweb/content-writer": "^0.3.4",
+    "@uniweb/semantic-parser": "^1.5.1",
     "@uniweb/kit": "^0.20.0",
     "@uniweb/schemas": "^0.13.0",
-    "@uniweb/runtime": "^0.29.4",
-    "@uniweb/core": "^0.38.0",
-    "@uniweb/semantic-parser": "^1.5.1"
+    "@uniweb/runtime": "^0.29.5"
   },
   "peerDependencies": {
-    "@uniweb/content-reader": "^1.2.8",
+    "@uniweb/build": "^0.80.3",
     "@uniweb/semantic-parser": "^1.5.1",
-    "@uniweb/build": "^0.80.3"
+    "@uniweb/content-reader": "^1.2.8"
   },
   "peerDependenciesMeta": {
     "@uniweb/build": {

package/partials/agents.md

@@ -109,11 +109,13 @@ For anything not in that table, start at the index. For CLI flags, prefer `uniwe
 **Always use the CLI to scaffold — never hand-write `package.json`, `vite.config.js`, `entry.js`, or `index.html`.** The CLI resolves correct versions and structure; hand-written config is the most common way to end up with a project that can't build.
 
 ```bash
-npx uniweb create my-project --template marketing
+npx uniweb@latest create my-project --template marketing
 cd my-project && pnpm install
 uniweb dev
 ```
 
+`@latest` matters: a project starts on the packages and templates of the CLI that creates it, and a bare `npx uniweb` runs a globally installed `uniweb` when there is one, however old.
+
 **Choosing a template.** `--template <name>` gives you a working site plus a foundation you can study and edit. `--template none` gives you the same two packages with no content — the right choice when you're building a foundation from scratch or porting a design. `--blank` gives you an empty workspace and assumes you'll add packages with `uniweb add`; use it only if you already know the framework.
 
 Official templates include `marketing` (tokens, insets, grids, multi-line headings), `docs` (sidebar nav, code highlighting), `blog` (records of the standard `@std/article` schema, a query, a parametric `[slug]` page), `dynamic` (live API data, loading states), `international` (i18n, records, multi-locale routing), `store` (product grids, e-commerce), `academic` (publications, timeline, math), `extensions` (multi-foundation, runtime loading). `uniweb template list` shows them all.

package/src/commands/add.js

@@ -1066,7 +1066,7 @@ async function applyFromTemplate(
   })
 
   try {
-    const metadata = await validateTemplate(resolved.path, {})
+    const metadata = await validateTemplate(resolved.path)
 
     // Look in contentDirs for matching package type
     const match =
@@ -1083,10 +1083,7 @@ async function applyFromTemplate(
           projectName,
           versions: getVersionsForTemplates()
         },
-        {
-          onProgress: (msg) => info(`  ${msg}`),
-          renames: match.renames
-        }
+        { onProgress: (msg) => info(`  ${msg}`) }
       )
 
       // Merge template dependencies

package/src/commands/template.js

@@ -1,29 +1,25 @@
 /**
- * template — `list` is live; `register` is RESERVED (not on the new backend yet).
- *
- * `uniweb template publish` submitted a site as a cloud template to the legacy
- * registry (the PHP backend + Cloudflare Worker) the CLI no longer talks to. A
- * new-backend equivalent isn't built; when it is, a template is REGISTERED (like
- * a foundation or a schemas package) — the verb will be `register`, not `publish`
- * (`publish` is for SITES only). The command name is kept reserved.
- *
- * (Unrelated: scaffolding FROM a template — `uniweb create --template <name>` —
- * is a separate path and is unaffected.)
+ * template — lists the official templates.
  *
  * ⭐ `list` exists so a SCRIPT can enumerate the official templates. The
- * interactive picker in `create` has always shown this list; `--json` is the
- * same data, second rendering, for tooling that scaffolds several templates in
- * a row and needs their names first.
+ * interactive picker in `create` shows the same list; `--json` is the same
+ * data, second rendering, for tooling that scaffolds several templates in a
+ * row and needs their names first. A bare `uniweb template` lists too.
+ *
+ * ⚠️ IT REPORTS THIS CLI'S SNAPSHOT, NOT A LIVE FETCH — the roster is baked into
+ * the CLI at publish time (`src/framework-index.json`), and `create` downloads
+ * these templates from the release that same snapshot names. So it answers
+ * "which official templates does THIS CLI scaffold", which is the right
+ * question when the next step is resolving one of those names with the same
+ * CLI. `cliVersion` is in the JSON for exactly that reason. A newer template
+ * than your CLI will not appear — and an unknown name is not fatal either way,
+ * since `create` falls through to npm `@uniweb/template-<name>`, so this is the
+ * OFFICIAL roster rather than the set of resolvable names.
  *
- * ⚠️ IT REPORTS A BUNDLED SNAPSHOT, NOT A LIVE FETCH — the roster is baked into
- * the CLI at publish time (`src/framework-index.json`, rewritten from
- * `templates/manifest.json` by the pre-publish hook). So it answers "which
- * official templates does THIS CLI know", which is the right question when the
- * next step is resolving one of those names with the same CLI. `cliVersion` is
- * in the JSON for exactly that reason. A newer template than your CLI will not
- * appear — and an unknown name is not fatal either way, since `create` falls
- * through to npm `@uniweb/template-<name>`, so this is the OFFICIAL roster
- * rather than the set of resolvable names.
+ * ⛔ There is no `template register` [Diego, 2026-10-08]: a site is offered as a
+ * template by the backend it is pushed to when its `site.yml` says
+ * `template: true`, so there is nothing for a verb to do. It was a reserved
+ * refusal until then, and never worked on the current backend.
  */
 
 import { OFFICIAL_TEMPLATE_MAP } from '../templates/resolver.js'
@@ -37,24 +33,6 @@ const colors = {
   red: '\x1b[31m'
 }
 
-function reserved() {
-  console.error(
-    "\x1b[31m✗\x1b[0m `uniweb template register` isn't available on the new backend yet."
-  )
-  console.error(
-    '  Submitting a site as a cloud template was retired with the PHP backend.'
-  )
-  console.error(
-    '  A template is REGISTERED, like a foundation — `publish` is for sites only.'
-  )
-  console.error(
-    '  (Scaffolding FROM a template still works: `uniweb create --template <name>`.)'
-  )
-  console.error('')
-  console.error('  To list the official templates: `uniweb template list`.')
-  process.exit(1)
-}
-
 function listTemplates(args) {
   const entries = Object.entries(OFFICIAL_TEMPLATE_MAP).map(([id, info]) => ({
     id,
@@ -73,19 +51,19 @@ function listTemplates(args) {
         2
       ) + '\n'
     )
-    return
+    return { exitCode: 0 }
   }
 
   if (entries.length === 0) {
-    // Not a crash: a CLI whose snapshot failed to load falls back to an empty
-    // map, and `create` then routes every name to npm. Say which happened.
+    // Not a crash: a CLI whose snapshot failed to load has an empty map, and
+    // `create` then routes every name to npm. Say which happened.
     console.error(
       `${colors.red}✗${colors.reset} No official templates found in this CLI's bundled index.`
     )
     console.error(
       `  ${colors.dim}A template name will still resolve through npm as @uniweb/template-<name>.${colors.reset}`
     )
-    process.exit(1)
+    return { exitCode: 1 }
   }
 
   const width = Math.max(...entries.map((e) => e.id.length))
@@ -107,12 +85,23 @@ function listTemplates(args) {
     `  ${colors.dim}--json for scripts. This is the roster THIS CLI ships with, not a live fetch.${colors.reset}`
   )
   console.log('')
+  return { exitCode: 0 }
 }
 
+/**
+ * @param {string[]} args - what follows `uniweb template`
+ * @returns {{ exitCode: number }}
+ */
 export async function template(args = []) {
   const sub = args.find((a) => !a.startsWith('-'))
-  if (sub === 'list') return listTemplates(args)
-  return reserved()
+  if (sub === undefined || sub === 'list') return listTemplates(args)
+  console.error(
+    `${colors.red}✗${colors.reset} Unknown subcommand: uniweb template ${sub}`
+  )
+  console.error(
+    `  ${colors.dim}uniweb template list   lists the official templates${colors.reset}`
+  )
+  return { exitCode: 2 }
 }
 
 export default template

package/src/framework-index.json

@@ -1,141 +1,66 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-10-08T17:12:48.725Z",
+  "generatedAt": "2026-10-09T02:55:55.375Z",
   "packages": {
     "@uniweb/api": {
-      "version": "0.7.0",
-      "path": "framework/api",
-      "deps": [
-        "@uniweb/core"
-      ]
+      "version": "0.7.0"
     },
     "@uniweb/build": {
-      "version": "0.80.3",
-      "path": "framework/build",
-      "deps": [
-        "@uniweb/content-reader",
-        "@uniweb/content-writer",
-        "@uniweb/core",
-        "@uniweb/projections",
-        "@uniweb/runtime",
-        "@uniweb/runtime",
-        "@uniweb/schemas",
-        "@uniweb/semantic-parser",
-        "@uniweb/theming"
-      ]
+      "version": "0.80.3"
     },
     "@uniweb/content-reader": {
-      "version": "1.2.8",
-      "path": "framework/content-reader",
-      "deps": []
+      "version": "1.2.8"
     },
     "@uniweb/content-writer": {
-      "version": "0.3.4",
-      "path": "framework/content-writer",
-      "deps": []
+      "version": "0.3.4"
     },
     "@uniweb/core": {
-      "version": "0.38.0",
-      "path": "framework/core",
-      "deps": [
-        "@uniweb/semantic-parser",
-        "@uniweb/theming"
-      ]
+      "version": "0.38.0"
     },
     "@uniweb/frame-bridge": {
-      "version": "0.3.2",
-      "path": "framework/frame-bridge",
-      "deps": []
+      "version": "0.3.2"
     },
     "@uniweb/icons": {
-      "version": "0.4.29",
-      "path": "framework/icons",
-      "deps": [
-        "@uniweb/core"
-      ]
+      "version": "0.4.29"
     },
     "@uniweb/kit": {
-      "version": "0.20.0",
-      "path": "framework/kit",
-      "deps": [
-        "@uniweb/core",
-        "@uniweb/projections",
-        "@uniweb/scene",
-        "@uniweb/schemas",
-        "@uniweb/semantic-parser"
-      ]
+      "version": "0.20.0"
     },
     "@uniweb/loom": {
-      "version": "0.2.5",
-      "path": "framework/loom",
-      "deps": []
+      "version": "0.2.5"
     },
     "@uniweb/press": {
-      "version": "0.4.18",
-      "path": "framework/press",
-      "deps": []
+      "version": "0.4.18"
     },
     "@uniweb/projections": {
-      "version": "0.7.15",
-      "path": "framework/projections",
-      "deps": [
-        "@uniweb/content-writer",
-        "@uniweb/core"
-      ]
+      "version": "0.7.15"
     },
     "@uniweb/runtime": {
-      "version": "0.29.4",
-      "path": "framework/runtime",
-      "deps": [
-        "@uniweb/core",
-        "@uniweb/theming"
-      ]
+      "version": "0.29.5"
     },
     "@uniweb/scene": {
-      "version": "0.1.3",
-      "path": "framework/scene",
-      "deps": []
+      "version": "0.1.3"
     },
     "@uniweb/schemas": {
-      "version": "0.13.0",
-      "path": "framework/schemas",
-      "deps": []
+      "version": "0.13.0"
     },
     "@uniweb/scholar": {
-      "version": "0.2.3",
-      "path": "framework/scholar",
-      "deps": []
+      "version": "0.2.3"
     },
     "@uniweb/semantic-parser": {
-      "version": "1.5.1",
-      "path": "framework/semantic-parser",
-      "deps": []
+      "version": "1.5.1"
     },
     "@uniweb/snapshot": {
-      "version": "0.1.2",
-      "path": "framework/snapshot",
-      "deps": []
+      "version": "0.1.2"
     },
     "@uniweb/templates": {
-      "version": "0.18.4",
-      "path": "framework/templates",
-      "deps": []
+      "version": "0.18.6"
     },
     "@uniweb/theming": {
-      "version": "0.2.0",
-      "path": "framework/theming",
-      "deps": []
+      "version": "0.2.0"
     },
     "@uniweb/unipress": {
-      "version": "0.10.24",
-      "path": "framework/unipress",
-      "deps": [
-        "@uniweb/build",
-        "@uniweb/content-reader",
-        "@uniweb/core",
-        "@uniweb/runtime",
-        "@uniweb/semantic-parser"
-      ]
+      "version": "0.10.24"
     }
   },
   "templates": {
@@ -233,8 +158,8 @@
       ]
     },
     "cv-loom": {
-      "name": "CV (Loom)",
-      "description": "A single-page narrative CV whose prose is written with {placeholder} expressions and instantiated at render time via the foundation content handler and @uniweb/loom. Reference implementation of the handler hook.",
+      "name": "CV (Loom + Press)",
+      "description": "An academic CV whose sections are written with Loom {placeholder} expressions, filled in from a single profile at render time by the foundation's content handler, and downloadable as a branded Word document through Press. Ships with Charles Darwin's CV as sample data.",
       "tags": [
         "cv",
         "loom",

package/src/index.js

@@ -41,7 +41,8 @@ import { template } from './commands/template.js'
 import {
   resolveTemplate,
   parseTemplateId,
-  buildTemplateChoices
+  buildTemplateChoices,
+  templatePickerPageSize
 } from './templates/index.js'
 import { validateTemplate } from './templates/validator.js'
 import {
@@ -86,9 +87,8 @@ const colors = {
 }
 
 // Template choices for the interactive prompt — built-ins first, then every
-// official template from the shared manifest (so the list never drifts from
-// framework/templates/manifest.json), with "Blank" last. Composed by
-// buildTemplateChoices() in templates/resolver.js.
+// official template in this CLI's snapshot (the list `create` can download),
+// with "Blank" last. Composed by buildTemplateChoices() in templates/resolver.js.
 const TEMPLATE_CHOICES = buildTemplateChoices()
 
 // Files that may pre-exist in the target dir during `uniweb create .` and
@@ -555,11 +555,7 @@ async function createFromContentTemplate(
         contentDir.dir,
         fullPath,
         { projectName },
-        {
-          onProgress,
-          onWarning,
-          renames: contentDir.renames
-        }
+        { onProgress, onWarning }
       )
       ensureFoundationName(fullPath, registryName)
     }
@@ -677,9 +673,9 @@ async function main() {
         const { fetchAndNotifyIfNewer, maybeNotifyFromCache } =
           await import('./utils/update-check.js')
         if (process.stdout.isTTY) {
-          await fetchAndNotifyIfNewer(getCliVersion(), { tone: 'soft' })
+          await fetchAndNotifyIfNewer(getCliVersion())
         } else {
-          maybeNotifyFromCache(getCliVersion(), 'soft')
+          maybeNotifyFromCache(getCliVersion())
         }
       } catch {
         /* ignore */
@@ -700,30 +696,36 @@ async function main() {
     // Commands that need @uniweb/build will get a helpful error via importProjectCommand().
   }
 
-  // Start non-blocking update check for global installs.
+  // Update check for global installs.
   //
-  // Two surfaces:
-  //   - showUpdateNotification (soft, trailing): printed at command end for
-  //     any verb. Doesn't interrupt the user's workflow.
-  //   - eager (loud, leading): printed BEFORE staleness-sensitive verbs do
-  //     their work. Today: only `create` (templates ship with the CLI, so
-  //     a stale CLI scaffolds stale starter content; the user needs to know
-  //     before files hit disk). Other verbs are insensitive — `deploy` etc.
-  //     are project-bound (delegated to local node_modules), and the
-  //     local-vs-global mismatch warning in delegateToLocal already covers
-  //     that case.
+  //   - `create` / `clone` STOP when a newer release exists, before anything is
+  //     written: a project starts on the packages and templates of the CLI that
+  //     creates it, and a global install runs these two itself — there is no
+  //     project CLI to delegate to yet (refuseOutdatedProjectStart). Their
+  //     `--help` still prints.
+  //   - every other verb gets a trailing notice (showUpdateNotification): they
+  //     are project-bound (delegated to local node_modules) or do not depend on
+  //     the version, and the local-vs-global mismatch warning in
+  //     delegateToLocal covers the first case.
   let showUpdateNotification = () => {}
   if (global) {
+    let updateCheck = null
     try {
-      const { startUpdateCheck, maybeEagerNotification } =
-        await import('./utils/update-check.js')
-      showUpdateNotification = startUpdateCheck(getCliVersion())
-      if (command === 'create') {
-        maybeEagerNotification(getCliVersion())
-      }
+      updateCheck = await import('./utils/update-check.js')
     } catch {
       // Update check is optional — don't fail if the module is missing
     }
+    const startsProject = command === 'create' || command === 'clone'
+    const asksForHelp = args.slice(1).some((a) => a === '--help' || a === '-h')
+    if (
+      updateCheck &&
+      startsProject &&
+      !asksForHelp &&
+      (await updateCheck.refuseOutdatedProjectStart(getCliVersion(), args))
+    ) {
+      await exitWhenDrained(1)
+    }
+    if (updateCheck) showUpdateNotification = updateCheck.startUpdateCheck(getCliVersion())
   }
 
   // Show help
@@ -1028,8 +1030,8 @@ async function main() {
 
   // Handle template command
   if (command === 'template') {
-    await template(args.slice(1))
-    return
+    const result = await template(args.slice(1))
+    await exitWhenDrained(result?.exitCode ?? 0)
   }
 
   // Handle create command
@@ -1190,7 +1192,8 @@ async function main() {
         name: 'template',
         message: 'Template:',
         choices: TEMPLATE_CHOICES,
-        initial: 1
+        initial: 1,
+        optionsPerPage: templatePickerPageSize(TEMPLATE_CHOICES.length)
       },
       {
         onCancel: () => {
@@ -1290,7 +1293,7 @@ async function main() {
       )
 
       // Validate and apply as format 2 content template
-      const metadata = await validateTemplate(resolved.path, {})
+      const metadata = await validateTemplate(resolved.path)
 
       try {
         await createFromContentTemplate(
@@ -1504,7 +1507,8 @@ ${colors.bright}Usage:${colors.reset}
 
 ${colors.bright}Options:${colors.reset}
   --template <type>  Project template (default: starter)
-                     Built-in: starter, none, marketing
+                     Built-in: starter, none, blank
+                     Official: marketing, docs, … (\`uniweb template list\`)
                      Local:    ./path/to/template
                      npm:      @scope/template-name
                      GitHub:   github:user/repo or https://github.com/user/repo
@@ -1664,12 +1668,13 @@ ${colors.dim}Hosts that support PR previews: cloudflare-pages, netlify, vercel.
 GitHub Pages has no preview environment, so it scaffolds a deploy workflow only.${colors.reset}
 
 ${colors.bright}Examples:${colors.reset}
-  uniweb add project docs                              # Create docs/foundation/ + docs/site/
+  uniweb add project docs                              # Create docs/src/ + docs/site/
   uniweb add project docs --from academic              # Co-located pair + academic content
-  uniweb add foundation                                # Create ./foundation/ at root
-  uniweb add foundation ui                             # Create ./foundations/ui/
+  uniweb add foundation                                # Create ./src/ at root
+  uniweb add foundation ui                             # Create ./ui/ — the folder you name
+  uniweb add foundation foundations/ui                 # Create ./foundations/ui/
   uniweb add site                                      # Create ./site/ at root
-  uniweb add site blog --foundation marketing          # Create ./sites/blog/ wired to marketing
+  uniweb add site blog --foundation marketing          # Create ./blog/ wired to marketing
   uniweb add extension effects --site site             # Create ./extensions/effects/
   uniweb add section Hero                              # Create Hero section type
   uniweb add section Hero --foundation ui              # Target specific foundation
@@ -1677,7 +1682,7 @@ ${colors.bright}Examples:${colors.reset}
   uniweb add section Pricing --starter                 # Scaffold Pricing + content that fills it
   uniweb add section Hero --starter --preset split     # Frontmatter it with the 'split' preset
   uniweb add section Hero --starter --json             # The structure + ProseMirror, for a script
-  uniweb add foundation --project docs                 # Create ./docs/foundation/ (co-located)
+  uniweb add foundation --project docs                 # Create ./docs/src/ (co-located)
   uniweb add site --project docs                       # Create ./docs/site/ (co-located)
   uniweb add ci                                        # Pick a host, add a deploy workflow
   uniweb add ci --host github-pages --site marketing   # Pick host + site explicitly
@@ -1969,18 +1974,12 @@ ${colors.bright}Usage:${colors.reset}
 
 ${colors.bright}What \`list\` reports:${colors.reset}
   The roster ${colors.bright}this CLI ships with${colors.reset} — a snapshot baked in at publish time,
-  not a live fetch. That is the right question when the next step is resolving
-  one of those names with the same CLI, which is why \`--json\` stamps
-  \`cliVersion\`. A template newer than your CLI will not be listed.
+  not a live fetch. \`create\` downloads these templates from the release the same
+  snapshot names, which is why \`--json\` stamps \`cliVersion\`. A template newer than
+  your CLI is not listed: \`npx uniweb@latest template list\` shows the current roster.
 
   It is the ${colors.bright}official${colors.reset} roster, not the set of resolvable names: an unknown
   name is not fatal, since \`create\` falls through to npm \`@uniweb/template-<name>\`.
-
-${colors.bright}Reserved:${colors.reset}
-  \`uniweb template register\` is not available on the new backend yet. Submitting
-  a site as a cloud template was retired with the legacy backend; when rebuilt, a
-  template is REGISTERED (like a foundation) — \`publish\` is for sites only.
-  Scaffolding FROM a template is unaffected: \`uniweb create --template <name>\`.
 `,
     docs: `
 ${colors.cyan}${colors.bright}uniweb docs${colors.reset} ${colors.dim}— Generate component documentation${colors.reset}
@@ -2093,6 +2092,7 @@ ${colors.bright}Commands:${colors.reset}
   inspect <path>     Inspect parsed content shape of a markdown file or folder
   docs               Generate component documentation
   families           List the standard section families (for meta.js family:)
+  template list      List the official templates (for create --template)
   doctor             Diagnose project configuration issues
   validate           Check your content against your foundation's data schemas
   update             Align workspace deps + AGENTS.md to the running CLI
@@ -2214,9 +2214,9 @@ ${colors.bright}Examples:${colors.reset}
   cd my-project
   uniweb add project docs                            # Add docs/src/ + docs/site/
   uniweb add project docs --from academic            # Co-located pair + academic content
-  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 add foundation marketing                    # Add marketing/ at root
+  uniweb add site blog --foundation marketing        # Add blog/ wired to marketing
+  uniweb add extension effects --site site           # Add extensions/effects/
 
   uniweb build
   uniweb build --target src                          # Build src/ package