uniweb 0.14.32 → 0.14.34

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.14.32",
+  "version": "0.14.34",
   "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.10.22",
+    "@uniweb/kit": "0.10.23",
     "@uniweb/core": "0.8.2",
     "@uniweb/runtime": "0.9.10"
   },
   "peerDependencies": {
-    "@uniweb/build": "0.16.22",
-    "@uniweb/content-reader": "1.2.2",
-    "@uniweb/semantic-parser": "1.2.1"
+    "@uniweb/build": "0.16.23",
+    "@uniweb/semantic-parser": "1.2.1",
+    "@uniweb/content-reader": "1.2.2"
   },
   "peerDependenciesMeta": {
     "@uniweb/build": {

package/partials/agents.md

@@ -1924,7 +1924,7 @@ 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.
+**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 — an **escape hatch** for a build npm does not have (an unreleased version, a local workspace tree, or a deployment that cannot reach the distribution channel), never the normal way a runtime reaches a backend. 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
 

package/src/commands/runtime.js

@@ -3,6 +3,37 @@
  * can serve the runtime version. The runtime is a SYSTEM artifact: registering it
  * requires **@std membership** (a non-@std bearer 403s).
  *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * ⛔ THIS IS AN ESCAPE HATCH. IT IS NOT HOW A RUNTIME NORMALLY REACHES A BACKEND.
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ * The normal path is **publish to npm**, which CI mirrors into the public
+ * distribution channel, from which a backend acquires the version itself — no
+ * login, no per-backend push, no credentials leaving the backend.
+ *
+ * This verb pushes ONE build to ONE backend, by hand. Its cost is not the
+ * upload, it is that the result is **invisible to every other backend and to
+ * the channel**: a version installed this way exists nowhere else, cannot be
+ * verified against a published digest, and will not be what a second
+ * environment resolves. Two backends can end up serving different bytes under
+ * one version number, which is the exact defect the channel's immutability
+ * exists to make impossible.
+ *
+ * It stays because three cases have no other path, and they are all LOCAL or
+ * pre-release:
+ *
+ *   • **an unpublished build** — npm versions are immutable, so you cannot
+ *     iterate on a published one. Testing a runtime before releasing it goes
+ *     through here.
+ *   • **local workspace development** — `@uniweb/runtime` is a pnpm symlink to
+ *     the working tree; there is no published artifact for the code you are
+ *     editing.
+ *   • **a deployment that cannot pull** — air-gapped or policy-restricted, or
+ *     any environment without the egress the channel needs.
+ *
+ * ⇒ **If the version you are pushing is on npm, you almost certainly want the
+ * channel instead.** The command warns at runtime for that reason.
+ *
  * A foundation emits `dist/runtime-pin.json`. `uniweb register` now reads it and
  * ships it as the foundation's `info.runtime` — but **NOTHING ENFORCES IT** in
  * any lane. An earlier version of this comment claimed `uniweb register` of a
@@ -25,7 +56,7 @@
  * manifest-last. Wire + the two-half artifact set (SPA + ssr-edge isolate, the
  * orchestrator stays platform-owned): utils/runtime-upload.js.
  *
- * Usage:
+ * Usage (escape hatch — prefer publishing to npm; see above):
  *   uniweb runtime register                  From framework/runtime (or --path <dir>)
  *   uniweb runtime register --path <dir>     The @uniweb/runtime package dir
  *   uniweb runtime register --version <v>    Override dist/app/manifest.json's version
@@ -95,6 +126,17 @@ export async function runtime(args = []) {
   const rest = args.slice(1)
   const dryRun = rest.includes('--dry-run')
 
+  // Say it at the moment of use, not only in the header. A verb that works
+  // fine is a verb people keep reaching for: this one succeeds quietly and
+  // leaves a version that exists on exactly one backend, unverifiable against
+  // any published digest.
+  say.warn('`runtime register` is an escape hatch, not the normal path.')
+  say.dim('A published runtime reaches a backend through the distribution channel — no push, no login.')
+  say.dim('Use this for a build npm does not have: an unreleased version, a local workspace tree,')
+  say.dim('or a deployment that cannot reach the channel. Pushing a version that IS on npm installs')
+  say.dim('bytes nothing else can verify, and a second environment will resolve something different.')
+  console.log('')
+
   const runtimeDir = resolveRuntimeDir(rest)
   if (!runtimeDir) {
     say.err('Not an @uniweb/runtime package.')

package/src/framework-index.json

@@ -1,9 +1,9 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-08-05T20:10:52.306Z",
+  "generatedAt": "2026-08-07T21:37:12.976Z",
   "packages": {
     "@uniweb/build": {
-      "version": "0.16.22",
+      "version": "0.16.23",
       "path": "framework/build",
       "deps": [
         "@uniweb/content-reader",
@@ -46,7 +46,7 @@
       "deps": []
     },
     "@uniweb/kit": {
-      "version": "0.10.22",
+      "version": "0.10.23",
       "path": "framework/kit",
       "deps": [
         "@uniweb/core",
@@ -86,7 +86,7 @@
       "deps": []
     },
     "@uniweb/schemas": {
-      "version": "0.2.9",
+      "version": "0.2.10",
       "path": "framework/schemas",
       "deps": []
     },
@@ -111,7 +111,7 @@
       "deps": []
     },
     "@uniweb/unipress": {
-      "version": "0.6.20",
+      "version": "0.6.22",
       "path": "framework/unipress",
       "deps": [
         "@uniweb/build",

package/src/index.js

@@ -1654,7 +1654,7 @@ ${colors.bright}Commands:${colors.reset}
   export             Export a self-contained site for third-party hosting
   register           Register a foundation + its data schemas with the backend registry
   release            Release a foundation version (synonym of register)
-  runtime register   Register an @uniweb/runtime version to the backend (@std only)
+  runtime register   Escape hatch: push a LOCAL/unreleased runtime build (@std only)
   push               Push a site's content to the backend
   pull               Pull a site's content from the backend
   refresh            Catch up with the git remote AND the backend (never pushes)