uniweb 1.16.0 → 1.16.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "1.16.0",
+  "version": "1.16.2",
   "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/core": "~1.4.0",
-    "@uniweb/schemas": "~1.6.5",
+    "@uniweb/content-writer": "~1.3.0",
     "@uniweb/semantic-parser": "~1.12.2",
-    "@uniweb/content-writer": "~1.3.0"
+    "@uniweb/core": "~1.4.0",
+    "@uniweb/schemas": "~1.6.5"
   },
   "peerDependencies": {
-    "@uniweb/build": "~1.7.4",
-    "@uniweb/semantic-parser": "~1.12.2",
-    "@uniweb/content-reader": "~1.5.4"
+    "@uniweb/build": "~1.7.5",
+    "@uniweb/content-reader": "~1.5.4",
+    "@uniweb/semantic-parser": "~1.12.2"
   },
   "peerDependenciesMeta": {
     "@uniweb/build": {

package/partials/agents.md

@@ -131,7 +131,7 @@ my-project/
 └── pnpm-workspace.yaml
 ```
 
-A site is pure content. A foundation is the site's source code — that's why it lives in `src/`. The foundation's `package.json::name` is `src`, symmetric with `site` — a **workspace** name, how the site depends on it. What the foundation **registers as** (`@org/<name>`, the name sites pin) is `name` in its `main.js`, which `uniweb create` sets to the project's name. **`src` and `foundation` are never a foundation's name** — `uniweb register` refuses them, because every project in an org would register the same one.
+A site is pure content. A foundation is the site's source code — that's why it lives in `src/`. The foundation's `package.json::name` is `src`, symmetric with `site` — a **workspace** name, how the site depends on it. What the foundation **registers as** (`@org/<name>`, the name sites pin) is `name` in its `main.js`, which `uniweb create` sets to the project's name. **`src` and `foundation` are never a foundation's name** — `uniweb register` refuses them, because every project in an org would register the same one. **Nor is any name under `@uniweb`**: that scope is the Uniweb framework's own, and `uniweb create`, `uniweb add` and `uniweb register` refuse it.
 
 - **Foundation** (`src/`): React components. Those in `sections/` and `layouts/` are *section types* — selectable by authors via `type:`, or used for layout areas. Everything in `components/` and `utils/` is ordinary React and JS: the developer's workbench, not visible to authors.
 - **Site** (`site/`): markdown content and configuration, plus optional records of structured content and the queries that reach them or an external data source.

package/src/backend/workspace.js

@@ -91,6 +91,33 @@ export function listedWorkspaces(envelope) {
     .filter((w) => w.name)
 }
 
+/**
+ * The top-level organization of a unit named by its child handle — `@studio` for `@studio:acme`,
+ * the part before the colon (backend, 2026-10-22).
+ *
+ * @param {string} handle - `@top:part`
+ * @returns {string} `@top`
+ */
+export function topOfChildHandle(handle) {
+  return `@${String(handle).replace(/^@/, '').split(':')[0]}`
+}
+
+/**
+ * The account's own handle, as the header would name it (`@jane`), from the orgs read — or null.
+ *
+ * ⛔ **An account's handle names no workspace** (backend, 2026-10-22, pinned by its tests). A
+ * handle names a person or an org, and only an org is a workspace: the header answers
+ * `@<account handle>` with `400`, never as the personal workspace, which a request names by
+ * naming none. So `--org @<your handle>` is refused, saying what names your own.
+ */
+export function ownHandle(envelope) {
+  return envelope?.account_handle ? workspaceHandle(envelope.account_handle) : null
+}
+
+/** What naming your own handle as a workspace is told — `--personal`, or `UNIWEB_WORKSPACE=personal`. */
+export const ownHandleNamesNone = (named, personal) =>
+  `${named} is your own handle, which names no workspace — your personal workspace is ${personal}.`
+
 /**
  * What a backend whose orgs read lists no workspaces is told. ⛔ The CLI does not check
  * against `orgs` in its place: that list leaves out every unit below an org.
@@ -185,22 +212,36 @@ export async function resolveWorkspace({ client, args = [], offline = false }) {
  * decides which SITE a command works on; here it only answers the question a bare name
  * asks the first time it registers.
  *
+ * ⭐ **A unit below an organization — a sub-org, a project — takes its organization's scope**
+ * *[Diego, 2026-10-22]*: its child handle (`@studio:acme`) names no scope (backend, the same day),
+ * and a bare name registered from it defaults to the top-level org's handle, `@studio`, when that
+ * org is among the account's organizations — the orgs read's `orgs`, the scopes. Not otherwise: a
+ * project's guest belongs to the project alone and has only their own scope, and so do the people
+ * of a sub-org whose belonging stops there — which the orgs read cannot tell apart, so membership is
+ * read from `orgs` and nothing else.
+ *
  * Null when the workspace names no scope, and the caller derives one as before
  * (`deriveScope`): none is chosen (you belong to organizations and none is named), the
  * command is a preview, the workspace is a unit without a handle, the workspace is a unit
- * below an organization — a sub-org or a project, whose child handle (`@studio:acme`) names
- * no scope (backend, 2026-10-22) — or the account has no handle (a service account).
+ * below an organization the account is not a member of, or the account has no handle (a
+ * service account).
  *
  * @param {{ workspace?: string|null, source?: string, refused?: boolean }} ws -
  *   `resolveWorkspace`'s answer
  * @param {string|null} accountHandle - the account's own handle (`GET /dev/orgs`), read
  *   only for the personal workspace
+ * @param {Array<{ handle?: string }>} [orgs] - the orgs read's `orgs`, read only for a unit
+ *   below an organization
  * @returns {string|null} `@handle`
  */
-export function scopeOfWorkspace(ws, accountHandle) {
+export function scopeOfWorkspace(ws, accountHandle, orgs = []) {
   if (!ws || ws.refused || ws.source === 'offline') return null
   if (typeof ws.workspace === 'string') {
-    return ws.workspace.startsWith('@') && !ws.workspace.includes(':') ? ws.workspace : null
+    if (!ws.workspace.startsWith('@')) return null
+    if (!ws.workspace.includes(':')) return ws.workspace
+    const top = topOfChildHandle(ws.workspace)
+    const member = (Array.isArray(orgs) ? orgs : []).some((o) => `@${bareHandle(o?.handle)}` === top)
+    return member ? top : null
   }
   const h = bareHandle(accountHandle || '')
   return h && !validateHandle(h) ? `@${h}` : null
@@ -228,12 +269,14 @@ export async function chooseWorkspace({ apiBase, token, args = [] }) {
   const flag = readOrgFlag(args)
   if (!flag && args.includes('--personal')) return { choice: PERSONAL }
 
-  const listed = listedWorkspaces(await fetchOrgs({ apiBase, token }))
+  const envelope = await fetchOrgs({ apiBase, token })
+  const listed = listedWorkspaces(envelope)
   if (!listed) return { refused: true, reason: noWorkspaceList(apiBase) }
   const mine = listed.map((w) => w.name)
   if (flag) {
     const named = namedWorkspace(flag)
     if (!named) return { refused: true, reason: `--org ${flag} names no workspace — give @org, or --personal.` }
+    if (named === ownHandle(envelope)) return { refused: true, reason: ownHandleNamesNone(named, '--personal') }
     if (!mine.includes(named)) {
       return {
         refused: true,

package/src/commands/add.js

@@ -46,7 +46,8 @@ import {
 import { findWorkspaceRoot } from '../utils/workspace.js'
 import {
   normalizeFoundationName,
-  ensureFoundationName
+  ensureFoundationName,
+  reservedScopeIn
 } from '../utils/foundation-name.js'
 import {
   detectPackageManager,
@@ -305,6 +306,21 @@ export async function add(rawArgs) {
     parsed = parseArgs(args)
   }
 
+  // ⛔ A FOUNDATION NAMED UNDER THE RESERVED SCOPE IS REFUSED before anything is placed
+  // [Diego, 2026-10-23]. The name read as `@scope/name` would otherwise be a folder
+  // path, and the foundation named `name` — the scope dropped in silence.
+  const reserved = ['project', 'foundation', 'extension'].includes(parsed.subcommand)
+    ? reservedScopeIn(parsed.name)
+    : null
+  if (reserved) {
+    error(`${reserved.problem}.`)
+    log(
+      `Add it without the scope — ${colors.cyan}${prefix} add ${parsed.subcommand} ${reserved.bare}${colors.reset} — and ` +
+        `${colors.cyan}${prefix} register${colors.reset} gives it the scope of the workspace you work in.`
+    )
+    process.exit(1)
+  }
+
   // Read root package.json for project name
   const rootPkg = JSON.parse(
     await readFile(join(rootDir, 'package.json'), 'utf-8').catch(() => '{}')

package/src/commands/register.js

@@ -76,6 +76,7 @@ import {
   collectStandaloneSchemas,
   readFoundationName,
   checkFoundationName,
+  checkRegistrationScope,
   splitFoundationName
 } from '@uniweb/build'
 import {
@@ -90,7 +91,7 @@ import {
 } from '../utils/code-upload.js'
 import { deriveScope, publishScope, belongsToScope } from '../utils/registry-orgs.js'
 import { BackendClient } from '../backend/client.js'
-import { resolveWorkspace, scopeOfWorkspace, SOURCE_LABEL } from '../backend/workspace.js'
+import { resolveWorkspace, scopeOfWorkspace, topOfChildHandle, SOURCE_LABEL } from '../backend/workspace.js'
 import { writeJsonPreservingStyleAsync } from '../utils/json-file.js'
 import {
   findWorkspaceRoot,
@@ -252,7 +253,12 @@ export async function settleFoundationName(targetDir, { args, isPreview }) {
   if (!problem) return true
 
   const where = relative(process.cwd(), read.mainFile) || read.mainFile
-  const suggestion = suggestFoundationName(targetDir)
+  // A name refused for its reserved scope keeps the rest of itself: `@uniweb/marketing`
+  // suggests `marketing`, which registers under the scope of the workspace you work in.
+  const { scope: nameScope, bare } = splitFoundationName(read.name)
+  const suggestion =
+    (nameScope && checkRegistrationScope(nameScope) && !checkFoundationName(bare) ? bare : null) ||
+    suggestFoundationName(targetDir)
   const reason = `${problem[0].toUpperCase()}${problem.slice(1)}.`
 
   // Nobody to ask — a script, a preview (which writes nothing), or --json (whose
@@ -334,6 +340,7 @@ export async function settleFoundationScope(targetDir, { args, isPreview, flagSc
   const { scope: nameScope, bare } = splitFoundationName(read.name)
 
   if (nameScope) {
+    if (refusedReservedScope(nameScope, `${where} names this foundation ${read.name}, under`)) return null
     if (flagScope && flagScope !== nameScope) {
       error(
         `${where} names this foundation ${read.name}, so it registers under ${nameScope} — ` +
@@ -352,6 +359,7 @@ export async function settleFoundationScope(targetDir, { args, isPreview, flagSc
 
   let scope = flagScope
   let source = flagScope ? '--scope' : null
+  if (refusedReservedScope(scope, '--scope names')) return null
   if (!scope) {
     scope = await deriveScopeFromLogin(client, args)
     if (!scope) return null
@@ -392,26 +400,50 @@ export async function settleFoundationScope(targetDir, { args, isPreview, flagSc
  * the scope is derived from your orgs as before (`deriveScope`): your personal scope when
  * you belong to none, else a pick at a terminal, your personal scope without one.
  */
+/**
+ * Refuse a reserved scope wherever it came from, before anything is written or sent —
+ * `@uniweb` names the framework's own packages and a system account on every Uniweb
+ * backend [Diego, 2026-10-23] (`checkRegistrationScope`).
+ *
+ * @param {string|null} scope
+ * @param {string} lead - where the scope came from, said before it: `--scope names`
+ * @returns {boolean} true when refused — the reason printed
+ */
+function refusedReservedScope(scope, lead) {
+  const problem = scope ? checkRegistrationScope(scope) : null
+  if (!problem) return false
+  error(`${lead} ${scope}. ${problem}.`)
+  log(`  ${colors.dim}Register under your own scope or an organization's: --scope @org.${colors.reset}`)
+  return true
+}
+
 async function deriveScopeFromLogin(client, args) {
   const token = await client.token()
   const ws = await resolveWorkspace({ client, args })
-  const personal = !ws.refused && ws.source !== 'offline' && ws.workspace === null
-  const accountHandle = personal ? (await client.fetchOrgs()).account_handle : null
-  const fromWorkspace = scopeOfWorkspace(ws, accountHandle)
+  const live = !ws.refused && ws.source !== 'offline'
+  const personal = live && ws.workspace === null
+  // A unit below an organization — a sub-org, a project — names no scope; its organization's is
+  // the default for the organization's members (`scopeOfWorkspace`), read from the same answer.
+  const child = live && typeof ws.workspace === 'string' && ws.workspace.includes(':')
+  const envelope = personal || child ? await client.fetchOrgs() : null
+  const fromWorkspace = scopeOfWorkspace(ws, envelope?.account_handle ?? null, envelope?.orgs)
   if (fromWorkspace) {
+    if (refusedReservedScope(fromWorkspace, 'The workspace you work in is')) return null
     const named = `${colors.bright}${fromWorkspace}${colors.reset}`
     console.error(
       personal
         ? `Registering under your personal scope ${named} — you work in your personal workspace (${SOURCE_LABEL[ws.source]}). For an org: --scope @org.`
-        : `Registering under ${named} — the workspace you work in (${SOURCE_LABEL[ws.source]}). For another scope: --scope @org.`
+        : child
+          ? `Registering under ${named} — the organization of ${ws.workspace}, the workspace you work in (${SOURCE_LABEL[ws.source]}). For another scope: --scope @org.`
+          : `Registering under ${named} — the workspace you work in (${SOURCE_LABEL[ws.source]}). For another scope: --scope @org.`
     )
     return fromWorkspace
   }
-  // A unit below an organization — a sub-org, a project — is a workspace and no scope (backend,
-  // 2026-10-22), so a bare name is asked for one as when no workspace names any.
-  if (typeof ws.workspace === 'string' && ws.workspace.includes(':')) {
+  // Not a member of the unit's organization — a project's guest — so it gives no scope, and a bare
+  // name is asked for one as when no workspace names any.
+  if (child) {
     console.error(
-      `${colors.dim}${ws.workspace}, the workspace you work in, is a unit below an organization, and names no scope.${colors.reset}`
+      `${colors.dim}${ws.workspace}, the workspace you work in, names no scope, and ${topOfChildHandle(ws.workspace)} is not among your organizations.${colors.reset}`
     )
   }
   const sess = await readRegistryAuth(client.origin)
@@ -421,6 +453,7 @@ async function deriveScopeFromLogin(client, args) {
     accountHandle: sess?.handle || null,
     args
   })
+  if (derived && refusedReservedScope(`@${derived}`, 'The scope chosen is')) return null
   return derived ? `@${derived}` : null
 }
 
@@ -642,6 +675,7 @@ async function runRegister(args = []) {
     log(`  ${colors.dim}Pass --scope @org.${colors.reset}`)
     return { exitCode: 2 }
   }
+  if (refusedReservedScope(scope, `${scopeSource} names`)) return { exitCode: 2 }
   const isPreview = !!output || dryRun
 
   // Each path supplies a different schema source: the standalone path discovers

package/src/framework-index.json

@@ -1,12 +1,12 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-10-22T17:15:55.292Z",
+  "generatedAt": "2026-10-23T16:20:14.706Z",
   "packages": {
     "@uniweb/api": {
       "version": "1.6.4"
     },
     "@uniweb/build": {
-      "version": "1.7.4"
+      "version": "1.7.5"
     },
     "@uniweb/content-reader": {
       "version": "1.5.4"
@@ -27,10 +27,10 @@
       "version": "1.6.0"
     },
     "@uniweb/loom": {
-      "version": "1.1.0"
+      "version": "1.1.1"
     },
     "@uniweb/press": {
-      "version": "1.1.3"
+      "version": "1.1.4"
     },
     "@uniweb/projections": {
       "version": "1.1.6"
@@ -54,13 +54,13 @@
       "version": "1.1.0"
     },
     "@uniweb/templates": {
-      "version": "1.1.4"
+      "version": "1.1.5"
     },
     "@uniweb/theming": {
       "version": "1.2.1"
     },
     "@uniweb/unipress": {
-      "version": "1.1.11"
+      "version": "1.1.12"
     }
   },
   "templates": {
@@ -198,7 +198,7 @@
     },
     "business-docs": {
       "name": "Business Documents",
-      "description": "A complete business-document site: invoice and SOW records, pages listing them, and a filtered engagement report with XLSX export. Built on @uniweb/business-docs and demonstrates the same foundation that ships the unipress invoice template.",
+      "description": "A complete business-document site: invoice and SOW records, pages listing them, and a filtered engagement report with XLSX export. Built on @unipress/business-docs and demonstrates the same foundation that ships the unipress invoice template.",
       "tags": [
         "business-docs",
         "invoice",

package/src/index.js

@@ -54,7 +54,8 @@ import {
 } from './utils/scaffold.js'
 import {
   normalizeFoundationName,
-  ensureFoundationName
+  ensureFoundationName,
+  reservedScopeIn
 } from './utils/foundation-name.js'
 import {
   detectPackageManager,
@@ -1171,6 +1172,21 @@ async function main() {
     await exitWhenDrained(1)
   }
 
+  // ⛔ A NAME UNDER THE RESERVED SCOPE IS REFUSED before anything is asked or written
+  // [Diego, 2026-10-23]. The foundation's name is the project's without its scope, so
+  // `@uniweb/marketing` would be dropped to `marketing` in silence — read as granted
+  // until `register` refused it.
+  const reserved = reservedScopeIn(projectName)
+  if (reserved) {
+    error(`${reserved.problem}.`)
+    const again = inPlace ? `create . --name ${reserved.bare}` : `create ${reserved.bare}`
+    log(
+      `Create it without the scope — ${colors.cyan}${prefix} ${again}${colors.reset} — and ` +
+        `${colors.cyan}${prefix} register${colors.reset} gives its foundation the scope of the workspace you work in.`
+    )
+    await exitWhenDrained(1)
+  }
+
   // Prompt for template if not specified via --template or --blank
   if (!templateType && !isBlank) {
     const templateResponse = await prompts(
@@ -1759,7 +1775,9 @@ ${colors.bright}Options:${colors.reset}
                      org's — and write it into the name (refused when the name has another
                      scope). A schemas-only package: publish under @scope; default:
                      package.json uniweb.scope
-  --org @org         Work in @org for this command: a bare name registers under it
+  --org @org         Work in @org for this command: a bare name registers under it —
+                     a sub-org's or project's (@studio:acme): under its organization's,
+                     when you are a member of it
   --personal         Work in your personal workspace: a bare name registers under your
                      personal scope
   --dry-run          Print the .uwx; submit nothing

package/src/utils/foundation-name.js

@@ -2,9 +2,10 @@
  * Giving a foundation its name — `name` in `main.js`'s default export.
  *
  * The rule itself (main.js `name`, else package.json `name`; `src` and `foundation`
- * refused) is `@uniweb/build`'s `foundation-name.js`, shared by the build, `register`
- * and `push`. This module only WRITES the name: the scaffold at `create` / `add`, and
- * `register` when it asks for one.
+ * refused, and so is the `@uniweb` scope) is `@uniweb/build`'s `foundation-name.js`,
+ * shared by the build, `register` and `push`. This module only WRITES the name: the
+ * scaffold at `create` / `add`, and `register` when it asks for one — and refuses, at
+ * `create` / `add`, a name that asks for the reserved scope (`reservedScopeIn`).
  *
  * ⛔ NO `@uniweb/build` IMPORT, AND NO IMPORT OF main.js. `uniweb create` runs before
  * any project exists: `@uniweb/build` is an optional peer that may not be installed,
@@ -21,6 +22,35 @@ import { join, resolve, basename, dirname } from 'node:path'
 // (`@uniweb/build`'s FORBIDDEN_FOUNDATION_NAMES; the test keeps them equal).
 export const SCAFFOLD_FOLDER_NAMES = new Set(['src', 'foundation'])
 
+// Scopes no foundation is named under — `@uniweb`, the framework's own (`@uniweb/build`'s
+// RESERVED_SCOPES and its reason, which the test keeps equal).
+export const RESERVED_SCOPES = new Set(['uniweb'])
+
+/**
+ * The reserved scope a name asks for — `@uniweb/marketing` asks for `@uniweb` — with why
+ * it is refused and the name without it. Null when the name asks for no reserved scope.
+ *
+ * `create` and `add` drop any scope from the name they write, so this is for refusing
+ * what was ASKED for, before anything is written: a scope dropped in silence would read
+ * as granted until `register` refused it.
+ *
+ * @param {unknown} raw - a name as typed
+ * @returns {{ scope: string, bare: string, problem: string } | null}
+ */
+export function reservedScopeIn(raw) {
+  const text = String(raw ?? '').trim()
+  const scoped = /^@([^/]+)\/(.+)$/.exec(text)
+  if (!scoped || !RESERVED_SCOPES.has(scoped[1].toLowerCase())) return null
+  const scope = `@${scoped[1].toLowerCase()}`
+  return {
+    scope,
+    bare: scoped[2],
+    problem:
+      `"${text}" is named under ${scope}, which is reserved: it names the Uniweb framework's ` +
+      'own packages and the system account of every Uniweb backend, so nothing registers under it'
+  }
+}
+
 // Written above the name wherever the CLI adds one — the scaffold's main.js
 // template says the same.
 const NAME_COMMENT = '// What this foundation registers as — @<org>/<name> — and what sites pin.'

package/src/utils/registry-auth.js

@@ -952,8 +952,16 @@ async function reportTokenProcess({ named, token }) {
   // Their workspace is UNIWEB_WORKSPACE's — never the stored session's — and, with none
   // named, personal for an account in no organization or project (resolveWorkspace,
   // workspace.js). Checked, as a login's `--org` is, against the workspaces the orgs read lists.
-  const { WORKSPACE_ENV, PERSONAL, parseWorkspaceChoice, headerOf, describeWorkspace, listedWorkspaces, noWorkspaceList } =
-    await import('../backend/workspace.js')
+  const {
+    WORKSPACE_ENV,
+    PERSONAL,
+    parseWorkspaceChoice,
+    headerOf,
+    describeWorkspace,
+    listedWorkspaces,
+    noWorkspaceList,
+    ownHandle
+  } = await import('../backend/workspace.js')
   const unsettled = (reason, { commandsRefuse }) => {
     console.error(`\x1b[31m✗\x1b[0m ${reason}`)
     if (commandsRefuse) {
@@ -968,18 +976,27 @@ async function reportTokenProcess({ named, token }) {
       commandsRefuse: true
     })
   }
-  let listed
+  let envelope
   try {
-    listed = listedWorkspaces(await (await import('./registry-orgs.js')).fetchOrgs({ apiBase: origin, token }))
+    envelope = await (await import('./registry-orgs.js')).fetchOrgs({ apiBase: origin, token })
   } catch (err) {
     console.error(`\x1b[33m⚠\x1b[0m ${err.message} — the workspace is not checked.`)
     return
   }
+  const listed = listedWorkspaces(envelope)
   if (!listed) {
     console.error(`\x1b[33m⚠\x1b[0m ${noWorkspaceList(origin)}`)
     return
   }
   const mine = listed.map((w) => w.name)
+  if (choice && choice === ownHandle(envelope)) {
+    // As a login refuses `--org @<own handle>` (chooseWorkspace): a handle names a person or an org,
+    // and only an org is a workspace.
+    unsettled(
+      `${WORKSPACE_ENV}=${raw} names the account's own handle, which names no workspace — its personal workspace is ${WORKSPACE_ENV}=personal.`,
+      { commandsRefuse: false }
+    )
+  }
   if (choice && choice !== PERSONAL && !mine.includes(choice)) {
     // As a login refuses `--org` for one (chooseWorkspace).
     unsettled(`${WORKSPACE_ENV}=${raw} is not one of this account's workspaces on ${origin}.`, {