uniweb 0.30.0 → 0.31.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.30.0",
+  "version": "0.31.0",
   "description": "Create structured Vite + React sites with content/code separation",
   "type": "module",
   "bin": {
@@ -41,15 +41,15 @@
     "js-yaml": "^4.1.0",
     "prompts": "^2.4.2",
     "tar": "^7.0.0",
-    "@uniweb/kit": "^0.13.5",
+    "@uniweb/kit": "^0.13.7",
+    "@uniweb/core": "^0.13.0",
     "@uniweb/semantic-parser": "^1.3.1",
-    "@uniweb/core": "^0.12.0",
-    "@uniweb/runtime": "^0.12.10"
+    "@uniweb/runtime": "^0.13.0"
   },
   "peerDependencies": {
-    "@uniweb/build": "^0.26.0",
-    "@uniweb/content-reader": "^1.2.4",
-    "@uniweb/semantic-parser": "^1.3.1"
+    "@uniweb/semantic-parser": "^1.3.1",
+    "@uniweb/build": "^0.27.0",
+    "@uniweb/content-reader": "^1.2.4"
   },
   "peerDependenciesMeta": {
     "@uniweb/build": {

package/partials/agents.md

@@ -287,7 +287,7 @@ Paths are relative to the site package you identified in step 1 — `site/` in t
 
 **Change a nav item.** First check how nav is produced. If `<site>/layout/header.md` lists the links (a markdown list, or a `yaml:nav` block), edit it there. If it doesn't, the Header is generating nav from the page hierarchy — change page titles and order in `site.yml` / `page.yml` instead.
 
-**Update the project's Uniweb dependencies — and this file.** `uniweb update`. One command aligns every `@uniweb/*` dependency *and* refreshes this AGENTS.md together, to the version matrix of the CLI that runs it. Preview with `--dry-run`. **Don't reach for `npm update` / `pnpm update`** — see *Staying current* in Part 5 for why that breaks things quietly.
+**Update the project's Uniweb dependencies — and this file.** `npx uniweb@latest update`. One command aligns every `@uniweb/*` dependency *and* refreshes this AGENTS.md together. Preview with `--dry-run`. ⛔ **The `@latest` is doing the work** — a bare `uniweb update` runs the CLI this project already pins, which aligns you to the matrix you already have and correctly reports nothing to do. **Don't reach for `npm update` / `pnpm update`** — see *Staying current* in Part 5 for why that breaks things quietly.
 
 **Change one section's columns / spacing / variant.** Check that type's `meta.js` `params:` first. If the knob exists, set it in that section's frontmatter and you're done, in the content lane. If it doesn't, it's a foundation change — see the warning in step 3.
 
@@ -1751,7 +1751,7 @@ fetch:
   limit: 3
 ```
 
-**Lean lists with `deferred:`.** Collections with heavy fields (article bodies, large nested arrays) can declare `deferred: [body]` in `site.yml`. The cascade payload omits those fields; per-record full files are emitted at `/data/<name>/<slug>.json` (file-based collections) or fetched from an author-declared `detailUrl:` (API-backed). On dynamic-route pages the focused record's full data is delivered automatically; elsewhere components fetch on demand via `useEntityDetail`.
+**Lean lists with `deferred:`.** Collections with heavy fields (article bodies, large nested arrays) can declare `deferred: [body]` in `site.yml`. The cascade payload omits those fields; per-record full files are emitted at `/data/<name>/<slug>.json` (file-based collections) or fetched from an author-declared `detailUrl:` (API-backed). On dynamic-route pages the focused record's full data is delivered automatically; elsewhere components fetch on demand via `useEntityDetail`. The hook is safe to call on any collection: when there is no separate detail source it returns the record you passed in, because nothing was stripped from it.
 
 **Component-side fetching.** When a component genuinely needs to fetch on its own (a search box, "load more", a lazy popover), use the kit hooks — `useFetched`, `useCacheEntry`, `useEntityDetail`. They share the framework's cache and dispatcher with declarative fetches; same-key requests dedupe automatically.
 
@@ -2024,8 +2024,9 @@ collector's event dimension into a cardinality problem.
 
 ### Choosing what a site sends
 
-By default a site sends `page_view`, `outbound_click` and `section_view`. Narrow
-or widen that with `emit`:
+By default a site sends `page_view`, `outbound_click` and `section_view` — or,
+where a host supplies the collector, whatever that host declares it collects.
+Narrow or widen that with `emit`:
 
 ```yaml
 # site.yml — your own collector
@@ -2044,10 +2045,19 @@ are read key by key, so naming `emit` alone overrides nothing else the host
 declared. And declaring your own `endpoint:` always wins, so a site pointing at
 its own collector keeps working on any host, including none.
 
-`minimal` is `page_view` alone. `standard` is the default. `all` is a standing
-yes, so an event added in a later framework release is included without you
-changing anything — which is exactly why `standard` exists as well: it is a
-curated set that a release cannot grow behind your back.
+`minimal` is `page_view` alone. `standard` is the default when you supply your
+own `endpoint:`. `all` is a standing yes, so an event added in a later framework
+release is included without you changing anything — which is exactly why
+`standard` exists as well: it is a curated set that a release cannot grow behind
+your back.
+
+⭐ **Saying nothing means two different things, and which one depends on who
+supplies the address.** A site with its own `endpoint:` gets `standard`. A site
+on a **host-supplied** collector gets **whatever that host declares it
+collects** — it has no address of its own, so the arrangement is that the host
+does analytics for it, and the set grows when the host starts collecting
+something new. **Naming `emit` always wins**, so pin it if you would rather not
+follow your host.
 
 A site can also set **`flushIntervalMs`** to widen the batching window (default
 5000, milliseconds — `30` is thirty *milliseconds*). A host that supplies your
@@ -2216,7 +2226,8 @@ uniweb i18n init-freeform / update-hash / move / rename / prune --freeform
 uniweb -v                         # Installed CLI version — and whether a newer one exists
 uniweb doctor                     # Diagnose project configuration (--fix to auto-repair)
 uniweb validate                   # Check file-based data against declared schemas (--strict for CI)
-uniweb update                     # Align @uniweb/* deps + AGENTS.md to the CLI (--dry-run, --yes)
+npx uniweb@latest update          # Align @uniweb/* deps + AGENTS.md (--dry-run, --yes)
+                                  #   bare `uniweb update` aligns to the CLI you ALREADY have
 uniweb inspect <path>             # Show parsed content for a section or page (--raw for the AST)
 
 uniweb <command> --help           # Per-command flags — no side effects. Prefer this over guessing.
@@ -2284,15 +2295,28 @@ Either side can publish. Nothing about this changes how you build: the same foun
 ```bash
 uniweb -v                  # installed CLI version, and whether a newer one is available
 uniweb doctor              # report drift in this project, changing nothing
-uniweb update --dry-run    # preview exactly what update would change
-uniweb update              # apply: align @uniweb/* deps AND refresh AGENTS.md
+npx uniweb@latest update --dry-run   # preview exactly what update would change
+npx uniweb@latest update             # apply: align @uniweb/* deps AND refresh AGENTS.md
 ```
 
-**`uniweb update` is the command for bringing a project up to date.** It aligns the project's `@uniweb/*` dependencies *and* this AGENTS.md to the version matrix of the CLI that runs it. Deps and documentation move together — that's the whole point of the verb.
+**`npx uniweb@latest update` is the command for bringing a project up to date.** It aligns the project's `@uniweb/*` dependencies *and* this AGENTS.md to the version matrix of the CLI that runs it. Deps and documentation move together — that's the whole point of the verb.
+
+> ### ⛔ WRITE `@latest`. A BARE `uniweb update` IS USUALLY A NO-OP, AND IT SAYS SO CONVINCINGLY
+>
+> `update` reconciles this project against **the matrix of the CLI that runs it** — and in a project,
+> `uniweb` resolves to the copy in your own `node_modules`, pinned by your own `package.json`. That
+> copy has no way to know a newer release exists.
+>
+> ⇒ **It reports everything aligned and changes nothing — correctly.** It answered the question it
+> was asked, which is why the output looks like success rather than a mistake. The same applies to
+> `pnpm uniweb update` and to a stale global install.
+>
+> ⭐ **`@latest` is what makes it a question about the newest release** rather than about the one you
+> already have. It also bumps the pin, so the next bare invocation is no longer stale.
 
 > **Don't run `npm update` or `pnpm update` on the `@uniweb/*` packages.** They're a matched set resolved by the CLI's version matrix, not independently versioned libraries you upgrade one at a time. Updating them directly gets you a combination nobody tested, and it won't refresh AGENTS.md — so this guide silently drifts out of sync with the code it describes, which is worse than being out of date, because nothing looks wrong.
 
-Two ordering rules: `update` won't refresh AGENTS.md while declared deps still lag the CLI, or while edited deps haven't been installed — either would put the doc ahead of the code. And updating the CLI itself is your package manager's job (`npm i -g uniweb@latest`, `pnpm add -g uniweb@latest`); `uniweb update` does not do that. To pin a project to the newest published release with no global install: `npx uniweb@latest update --yes`.
+Two ordering rules: `update` won't refresh AGENTS.md while declared deps still lag the CLI, or while edited deps haven't been installed — either would put the doc ahead of the code. And updating the CLI itself is your package manager's job (`npm i -g uniweb@latest`, `pnpm add -g uniweb@latest`); `uniweb update` does not do that.
 
 ### `package.json` `uniweb` block
 

package/src/commands/publish.js

@@ -409,8 +409,13 @@ export async function publish(args = []) {
   if (!fnd.proceed) return { exitCode: fnd.refused ? 1 : 0 }
 
   // 2. Build the site data (link mode): dist/site-content.json (+ per-locale),
-  //    dist/data/*, dist/_search/*, dist/assets/*. Spawn the SAME CLI binary so
-  //    the inner build can't resolve to a different installed version.
+  //    dist/data/*, dist/assets/*. Spawn the SAME CLI binary so the inner
+  //    build can't resolve to a different installed version.
+  //
+  //    ⛔ NO SEARCH INDEX. This listed `dist/_search/*` until 2026-08-26; the
+  //    link lane stopped emitting one on 2026-08-01 (`@uniweb/build`
+  //    `site/build-site-data.js` step 5) because only one of the two
+  //    publishers produced it.
   say.info('Building site…')
   console.log('')
   execSync(`node ${JSON.stringify(process.argv[1])} build --link`, {
@@ -627,7 +632,7 @@ export async function publish(args = []) {
   //
   // A file map needs a name nothing else claims (`static_data` / `data_files`
   // were proposed) AND a consumer that reads it — neither settled. See
-  // `kb/framework/build/data-ball-retirement.md`.
+  // one object per file, no bundle.
   const injectInfo = {
     ...(fnd.ref ? { foundation: fnd.ref } : {})
   }

package/src/framework-index.json

@@ -1,9 +1,9 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-08-25T21:53:35.373Z",
+  "generatedAt": "2026-08-27T04:57:15.265Z",
   "packages": {
     "@uniweb/build": {
-      "version": "0.26.0",
+      "version": "0.27.0",
       "path": "framework/build",
       "deps": [
         "@uniweb/content-reader",
@@ -29,7 +29,7 @@
       "deps": []
     },
     "@uniweb/core": {
-      "version": "0.12.0",
+      "version": "0.13.0",
       "path": "framework/core",
       "deps": [
         "@uniweb/semantic-parser",
@@ -42,14 +42,14 @@
       "deps": []
     },
     "@uniweb/icons": {
-      "version": "0.4.3",
+      "version": "0.4.4",
       "path": "framework/icons",
       "deps": [
         "@uniweb/core"
       ]
     },
     "@uniweb/kit": {
-      "version": "0.13.5",
+      "version": "0.13.7",
       "path": "framework/kit",
       "deps": [
         "@uniweb/core",
@@ -68,7 +68,7 @@
       "deps": []
     },
     "@uniweb/projections": {
-      "version": "0.3.5",
+      "version": "0.3.7",
       "path": "framework/projections",
       "deps": [
         "@uniweb/content-writer",
@@ -76,7 +76,7 @@
       ]
     },
     "@uniweb/runtime": {
-      "version": "0.12.10",
+      "version": "0.13.0",
       "path": "framework/runtime",
       "deps": [
         "@uniweb/core",
@@ -89,7 +89,7 @@
       "deps": []
     },
     "@uniweb/schemas": {
-      "version": "0.2.10",
+      "version": "0.2.11",
       "path": "framework/schemas",
       "deps": []
     },
@@ -114,7 +114,7 @@
       "deps": []
     },
     "@uniweb/unipress": {
-      "version": "0.8.12",
+      "version": "0.8.13",
       "path": "framework/unipress",
       "deps": [
         "@uniweb/build",

package/src/utils/site-data-upload.js

@@ -38,7 +38,7 @@
  * runtime — so it is returned for parity and for a caller that wants to verify
  * an upload landed.
  *
- * Contract ratified 2026-08-18; see `kb/framework/build/data-ball-retirement.md`.
+ * Contract ratified with the backend lane, 2026-08-18.
  * **Wired into `publish.js` and shipped in `uniweb` 0.25.3.** Both arms of the
  * endpoint exist (presigned landed 2026-08-18, per Diego).
  *