uniweb 0.88.1 → 0.89.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.88.1",
+  "version": "0.89.1",
   "description": "Create structured Vite + React sites with content/code separation",
   "type": "module",
   "bin": {
@@ -41,16 +41,16 @@
     "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/core": "^0.38.1",
     "@uniweb/kit": "^0.20.0",
-    "@uniweb/schemas": "^0.13.0",
-    "@uniweb/runtime": "^0.29.5"
+    "@uniweb/runtime": "^0.29.6",
+    "@uniweb/semantic-parser": "^1.5.1",
+    "@uniweb/content-writer": "^0.3.4",
+    "@uniweb/schemas": "^0.13.0"
   },
   "peerDependencies": {
-    "@uniweb/build": "^0.80.3",
     "@uniweb/semantic-parser": "^1.5.1",
+    "@uniweb/build": "^0.80.3",
     "@uniweb/content-reader": "^1.2.8"
   },
   "peerDependenciesMeta": {

package/partials/agents.md

@@ -194,7 +194,7 @@ The rest of this guide explains how Uniweb works. This part is what to do *first
 | `src`, `site` | **single** (the default) | foundation in `src/`, site in `site/` |
 | `foundations/*`, `sites/*` | **segregated** | several sites may share one foundation — a foundation edit hits all of them |
 | `*/src`, `*/site` | **co-located projects** | one self-contained pair per project: `docs/src` + `docs/site` |
-| `extensions/*` (alongside any of the above) | extensions present | extra section types, runtime-loaded — see step 2 |
+| a package whose `main.js` says `extension: true` — `effects`, `extensions/*` (alongside any of the above) | extensions present | extra section types, runtime-loaded — see step 2 |
 
 Those names are convention; the globs are the truth. Full guide with the wiring for each: `development/project-structures.md`.
 
@@ -2510,8 +2510,8 @@ const sessions = entity?.hydrated?.items.filter((item) => item.section === 'sess
 section's fields (`record.brief.name`, not `record.name`), and a record carries **no
 items**. Read one entity for its items. Each item carries `section`, its section's name
 (the word a write takes), and `id`, which is what the writer takes to update, move or
-remove it. `scope: 'mine'` lists only the viewer's own records. Without it, the operator
-also gets everyone else's.
+remove it. `scope: 'mine'` lists only the viewer's own records; without it, a list also
+holds what was shared with the viewer.
 
 ⭐ **`absent` and an empty `ready` are different answers, and confusing them is the
 mistake to avoid.** `absent` = there is no live source (no `backend` service, or nobody signed
@@ -2543,10 +2543,12 @@ await writer.remove(itemId)
 
 ### ⛔ Permissions are the SERVER'S, and your UI is only a courtesy
 
-Gate your controls on what the viewer may do — `viewer.roles` (the site's operator
-holds `system_admin`), or a record's own `can_edit` from a single-entity read — but
-**never rely on that for safety**. A foundation runs with exactly the viewer's own
-authority, so hiding a button hides a button.
+Gate your controls on what the viewer may do — a record's own `can_edit` from a
+single-entity read — but **never rely on that for safety**. A foundation runs with
+exactly the viewer's own authority, so hiding a button hides a button. ⛔ **Not on
+`viewer.roles`:** a session signed in on a site holds a member's rights — the operator's
+too — so its roles never name an administrator, and a gate on `system_admin` shows the
+operator nothing.
 
 What protects content is the **entry**: a member writes their own entries and not
 another's, and the store enforces it. **Models are open** — anyone signed in may
@@ -2565,6 +2567,19 @@ sections:
 `append_only` holds against the item's own author. That is the difference between a
 permission model and a CSS one.
 
+### The Admin link
+
+```jsx
+const { adminHref } = useSession()
+{adminHref && <a href={adminHref}>Admin</a>}
+```
+
+`adminHref` is set only for a signed-in account the backend's administration admits —
+the operator, and whoever else administers it — and is `null` for everyone else. It
+takes them there already signed in. ⛔ **Navigate to it, never `fetch` it**: the answer is
+a redirect carrying a one-time credential no script on the site is to hold. It decides
+what to offer, not what is allowed — on the site the operator acts as a member.
+
 ### A backend on your machine
 
 You do not need a live backend to build against one. In `site.yml`:

package/src/commands/add.js

@@ -27,7 +27,8 @@ import {
 import {
   resolvePlacement,
   SITE_KIND,
-  FOUNDATION_KIND
+  FOUNDATION_KIND,
+  EXTENSION_KIND
 } from '../utils/placement.js'
 import {
   readWorkspaceConfig,
@@ -648,17 +649,8 @@ async function addExtension(rootDir, projectName, opts, pm = 'pnpm') {
   let name = opts.name
   const existingNames = await getExistingPackageNames(rootDir)
 
-  // Reject reserved names (format + reserved check only — collisions handled at package name level)
-  if (name) {
-    const valid = validatePackageName(name)
-    if (valid !== true) {
-      error(valid)
-      process.exit(1)
-    }
-  }
-
-  // Interactive name prompt when name not provided
-  if (!name) {
+  // A name is asked for unless one is given, or `--path` names the folder.
+  if (!name && !opts.path) {
     if (isNonInteractive(process.argv)) {
       error(`Missing extension name.\n`)
       log(`Usage: ${getCliPrefix()} add extension <name>`)
@@ -682,23 +674,41 @@ async function addExtension(rootDir, projectName, opts, pm = 'pnpm') {
     name = response.name
   }
 
+  // ⭐ Placed by the rule `add foundation` follows (utils/placement.js): the folder
+  // you name is the folder created — `effects` → effects/, `extensions/effects` →
+  // extensions/effects/ — and `--path` is the folder it goes in.
+  const placement = resolvePlacement(rootDir, name, opts, EXTENSION_KIND)
+  if (placement.outsideRoot) {
+    error(`--path must name a folder inside the workspace: ${placement.outsideRoot}`)
+    log('')
+    log(`The workspace root is ${colors.bright}${rootDir}${colors.reset}.`)
+    log(`A package outside it cannot be a workspace member.`)
+    process.exit(1)
+  }
+  const { relativePath } = placement
+  // The extension's own name: the last segment of the folder.
+  name = placement.packageName
+
+  // Reject reserved names (format + reserved check only — collisions handled at package name level)
+  const valid = validatePackageName(name)
+  if (valid !== true) {
+    error(valid)
+    process.exit(1)
+  }
+
   // Auto-suffix package name if it collides with an existing package
   const extensionPackageName = existingNames.has(name)
     ? resolveUniqueName(name, '-ext', existingNames)
     : name
 
-  // Determine target
-  let target
-  if (opts.path) {
-    target = opts.path
-  } else {
-    target = `extensions/${name}`
-  }
-
-  const fullPath = join(rootDir, target)
+  const fullPath = join(rootDir, relativePath)
 
   if (existsSync(fullPath)) {
-    error(`Directory already exists: ${target}`)
+    error(
+      `Cannot create extension: ${colors.bright}${relativePath}/${colors.reset} already exists.`
+    )
+    log('')
+    log(`Pick a different name, or pass --path to choose a different folder.`)
     process.exit(1)
   }
 
@@ -728,8 +738,8 @@ async function addExtension(rootDir, projectName, opts, pm = 'pnpm') {
     ensureFoundationName(fullPath, registryName)
   }
 
-  // Update workspace globs
-  await addWorkspaceGlob(rootDir, 'extensions/*')
+  // Register the folder it is in, as add foundation does
+  await addWorkspaceGlob(rootDir, relativePath)
 
   // Wire extension to site:
   //   - --site <name>: explicit, wire it.
@@ -742,17 +752,22 @@ async function addExtension(rootDir, projectName, opts, pm = 'pnpm') {
   //   - no sites: print a note and exit 0.
   let wiredSite = null
   let unwiredReason = null
-  if (opts.site) {
-    wiredSite = await wireExtensionToSite(rootDir, opts.site, name, target)
+  // A site loads a workspace extension from `/<name>/entry.js`, which the build
+  // finds in `<name>/` or `extensions/<name>/` (wireExtensionToSite). An entry
+  // pointing anywhere else would build with a warning and 404 at runtime, so
+  // none is written.
+  const reachable = relativePath === name || relativePath === `extensions/${name}`
+  if (!reachable) {
+    unwiredReason =
+      `A site loads a workspace extension from /${name}/entry.js, which the build finds in ` +
+      `${name}/ or extensions/${name}/ — not ${relativePath}/. Move the folder to one of those, ` +
+      `or list a URL where the built extension is served under <site>/site.yml::extensions:.`
+  } else if (opts.site) {
+    wiredSite = await wireExtensionToSite(rootDir, opts.site, relativePath)
   } else {
     const sites = await discoverSites(rootDir)
     if (sites.length === 1) {
-      wiredSite = await wireExtensionToSite(
-        rootDir,
-        sites[0].name,
-        name,
-        target
-      )
+      wiredSite = await wireExtensionToSite(rootDir, sites[0].name, relativePath)
     } else if (sites.length > 1) {
       if (isNonInteractive(process.argv)) {
         unwiredReason = `Multiple sites in workspace; extension not wired. Re-run with --site <name>, or edit <site>/site.yml::extensions: manually.`
@@ -779,12 +794,7 @@ async function addExtension(rootDir, projectName, opts, pm = 'pnpm') {
           }
         )
         if (response.site) {
-          wiredSite = await wireExtensionToSite(
-            rootDir,
-            response.site,
-            name,
-            target
-          )
+          wiredSite = await wireExtensionToSite(rootDir, response.site, relativePath)
         }
       }
     } else {
@@ -796,7 +806,7 @@ async function addExtension(rootDir, projectName, opts, pm = 'pnpm') {
   const sites = await discoverSites(rootDir)
   await updateRootScripts(rootDir, sites, pm)
 
-  let msg = `Created extension '${name}' at ${target}/`
+  let msg = `Created extension '${name}' at ${relativePath}/`
   if (wiredSite) {
     msg += ` → wired to site '${wiredSite}'`
   }
@@ -1117,12 +1127,7 @@ async function applyFromTemplate(
 /**
  * Wire an extension URL to a site's site.yml
  */
-async function wireExtensionToSite(
-  rootDir,
-  siteName,
-  extensionName,
-  extensionPath
-) {
+async function wireExtensionToSite(rootDir, siteName, extensionFolder) {
   // Find the site directory
   const sites = await discoverSites(rootDir)
   const site = sites.find((s) => s.name === siteName)
@@ -1141,8 +1146,16 @@ async function wireExtensionToSite(
     const content = await readFile(siteYmlPath, 'utf-8')
     const config = yaml.load(content) || {}
 
-    // Add extension URL
-    const extensionUrl = `/${extensionPath}/dist/entry.js`
+    // ⭐ The site loads it from its own origin at `/<name>/entry.js`, `<name>`
+    // being the extension's folder: the build finds that extension's build in
+    // `<name>/` or `extensions/<name>/`, copies it into the site's output there,
+    // and prerender imports it from the same place (`@uniweb/build`,
+    // resolveExtensionDist) — the form the `extensions` template declares.
+    // ⛔ Until 2026-10-08 this wrote `/<folder>/dist/entry.js`, which that lookup
+    // reads as an extension named after the folder's FIRST segment —
+    // `/extensions/effects/dist/entry.js` as one named `extensions` — so the
+    // build warned it found no build, and the site 404'd on the file.
+    const extensionUrl = `/${basename(extensionFolder)}/entry.js`
     if (!config.extensions) {
       config.extensions = []
     }

package/src/commands/build.js

@@ -47,7 +47,7 @@
  */
 
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs'
-import { resolve, join, dirname, basename } from 'node:path'
+import { resolve, join, dirname, basename, relative } from 'node:path'
 import { spawn } from 'node:child_process'
 import { writeFile, mkdir } from 'node:fs/promises'
 import { createRequire } from 'node:module'
@@ -94,6 +94,10 @@ function info(message) {
   console.log(`${colors.cyan}→${colors.reset} ${message}`)
 }
 
+function warn(message) {
+  console.log(`${colors.yellow}⚠${colors.reset} ${message}`)
+}
+
 /**
  * Detect project type based on directory contents
  *
@@ -205,24 +209,29 @@ async function buildFoundation(projectDir, options = {}) {
 
   info('Building foundation...')
 
-  // 1. Discover components
+  // 1. Discover section types
   log('')
-  info('Discovering components...')
+  info('Discovering section types...')
   const components = await discoverComponents(srcDir)
   const componentNames = Object.keys(components)
 
+  // ⭐ A foundation with no section types yet builds — the state
+  // `create --template none` makes on purpose, and one `uniweb dev` and
+  // @uniweb/build's entry generation already accept. ⛔ Until 2026-10-08 this
+  // stopped the build, saying section types belonged in `components/[Name]/`
+  // with a meta.js — where they lived in January — so a fresh `none` project
+  // failed its first build, pointed at the wrong folder.
   if (componentNames.length === 0) {
-    error('No components found with meta.js files')
-    error(
-      `Make sure components are in ${srcDir}/components/[Name]/ with a meta.js file`
+    const sectionsDir = relative(process.cwd(), join(srcDir, 'sections')) || 'sections'
+    warn(`No section types yet: ${sectionsDir}/ is empty.`)
+    log(
+      `  ${colors.dim}Add one: ${colors.reset}uniweb add section Hero${colors.dim} — a PascalCase file or folder there is one.${colors.reset}`
     )
-    process.exit(1)
+  } else {
+    const n = componentNames.length
+    success(`Found ${n} section type${n === 1 ? '' : 's'}: ${componentNames.join(', ')}`)
   }
 
-  success(
-    `Found ${componentNames.length} components: ${componentNames.join(', ')}`
-  )
-
   // 2. Generate entry point
   log('')
   info('Generating entry point...')
@@ -960,11 +969,10 @@ async function buildWorkspace(workspaceDir, options = {}) {
   ) {
     error('No foundations, extensions, or sites found in workspace')
     log('')
-    log('Expected structure (matching pnpm-workspace.yaml globs):')
-    log('  foundation/       or  foundations/*/')
-    log('  site/             or  sites/*/')
-    log('  */foundation      +  */site          (co-located)')
-    log('  extensions/*/')
+    log('Packages are the folders pnpm-workspace.yaml lists. Add one with:')
+    log('  uniweb add foundation [folder]    (src/ when none is named)')
+    log('  uniweb add site [folder]          (site/ when none is named)')
+    log('  uniweb add extension <folder>')
     process.exit(1)
   }
 

package/src/commands/docs.js

@@ -170,7 +170,7 @@ ${colors.dim}Schema: https://raw.githubusercontent.com/uniweb/cli/main/schemas/p
 const META_REFERENCE = `
 ${colors.cyan}${colors.bright}Component meta.js Reference${colors.reset}
 
-Component metadata in <foundation>/components/[Name]/meta.js (or sections/[Name]/meta.js)
+A section type's metadata, in <foundation>/sections/[Name]/meta.js
 
 ${colors.bright}Identity:${colors.reset}
   ${colors.cyan}title${colors.reset}             Display name in editor

package/src/commands/doctor.js

@@ -80,27 +80,6 @@ function isFoundation(dir) {
   return classifyPackage(dir) === 'foundation'
 }
 
-/**
- * Load the foundation's authored declarations file (main.js or legacy
- * foundation.js) and return a minimal summary used by the doctor.
- * Returns null if no declarations file is found.
- */
-function loadFoundationJs(dir) {
-  const srcDir = resolveFoundationSrcPath(dir)
-  for (const name of ['main.js', 'foundation.js']) {
-    const filePath = join(srcDir, name)
-    if (existsSync(filePath)) {
-      try {
-        const content = readFileSync(filePath, 'utf8')
-        return { extension: /extension\s*:\s*true/.test(content) }
-      } catch {
-        return null
-      }
-    }
-  }
-  return null
-}
-
 /**
  * Load a foundation's built schema.json.
  *
@@ -1634,21 +1613,12 @@ export async function doctor(args = []) {
     log('')
     info(`Checking extension: ${ext.name}`)
 
-    // Check if it declares extension: true
-    if (!isExtensionPackage(ext.path)) {
-      issues.push({
-        type: 'warn',
-        message: `Extension "${ext.name}" in extensions/ doesn't declare extension: true in foundation.js`
-      })
-      warn(`Missing extension identity`)
-      log(`  ${colors.dim}Add to src/foundation.js:${colors.reset}`)
-      log(`    export default { extension: true }`)
-    } else {
-      success(`Extension identity: extension: true`)
-    }
+    // An extension is a package that declares `extension: true` — that is how it
+    // was told apart from the foundations above, wherever its folder is. (A check
+    // here that it declares it could never fail, and was removed 2026-10-08.)
+    success(`Extension identity: extension: true`)
 
     // Check for vars or layouts
-    const config = loadFoundationJs(ext.path)
     const schema = loadSchemaJson(ext.path)
 
     if (schema?._self?.vars && Object.keys(schema._self.vars).length > 0) {

package/src/framework-index.json

@@ -1,9 +1,9 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-10-09T02:55:55.375Z",
+  "generatedAt": "2026-10-11T15:34:07.453Z",
   "packages": {
     "@uniweb/api": {
-      "version": "0.7.0"
+      "version": "0.8.0"
     },
     "@uniweb/build": {
       "version": "0.80.3"
@@ -15,7 +15,7 @@
       "version": "0.3.4"
     },
     "@uniweb/core": {
-      "version": "0.38.0"
+      "version": "0.38.1"
     },
     "@uniweb/frame-bridge": {
       "version": "0.3.2"
@@ -36,7 +36,7 @@
       "version": "0.7.15"
     },
     "@uniweb/runtime": {
-      "version": "0.29.5"
+      "version": "0.29.6"
     },
     "@uniweb/scene": {
       "version": "0.1.3"
@@ -54,7 +54,7 @@
       "version": "0.1.2"
     },
     "@uniweb/templates": {
-      "version": "0.18.6"
+      "version": "0.18.8"
     },
     "@uniweb/theming": {
       "version": "0.2.0"

package/src/index.js

@@ -1627,7 +1627,7 @@ ${colors.bright}Usage:${colors.reset}
 
 ${colors.bright}Common Options:${colors.reset}
   --from <template>  Apply content from a template after scaffolding
-  --path <dir>       Custom directory for the package
+  --path <dir>       The folder to put the package in
   --non-interactive  Fail with usage info instead of prompting
 
 ${colors.bright}Foundation Options:${colors.reset}
@@ -1675,7 +1675,8 @@ ${colors.bright}Examples:${colors.reset}
   uniweb add foundation foundations/ui                 # Create ./foundations/ui/
   uniweb add site                                      # Create ./site/ at root
   uniweb add site blog --foundation marketing          # Create ./blog/ wired to marketing
-  uniweb add extension effects --site site             # Create ./extensions/effects/
+  uniweb add extension effects --site site             # Create ./effects/ — the folder you name
+  uniweb add extension extensions/effects              # Create ./extensions/effects/
   uniweb add section Hero                              # Create Hero section type
   uniweb add section Hero --foundation ui              # Target specific foundation
   uniweb add section Hero --starter                    # Starter content for an existing Hero
@@ -1849,11 +1850,16 @@ ${colors.bright}Options:${colors.reset}
   --token-paste      Force the paste-a-token prompt
 
 In non-interactive mode (no TTY — an agent, a script), pass \`--token <bearer>\` with
-\`--org @org\` or \`--personal\`, or set \`UNIWEB_USERNAME\` + \`UNIWEB_PASSWORD\`, or set
-\`UNIWEB_TOKEN\` (per process, not stored) with \`UNIWEB_WORKSPACE=@org\` or \`personal\`.
+\`--org @org\` or \`--personal\`, or set \`UNIWEB_USERNAME\` + \`UNIWEB_PASSWORD\`.
 A login with organizations that names no workspace signs you in but exits 2;
 \`uniweb login --org @org\` (or \`--personal\`) finishes it without signing in again.
 \`uniweb logout\` logs you out.
+
+${colors.bright}Or skip the login.${colors.reset} With \`UNIWEB_TOKEN\` set — and \`UNIWEB_WORKSPACE=@org\` or
+\`personal\` — every backend command in that process uses the token, ahead of any
+session, and nothing is stored. \`uniweb login\` there only checks the token with the
+backend those commands go to — \`UNIWEB_SERVER\`, else the one you are logged in to,
+else the default — and says who and where they work as.
 `,
     refresh: `
 ${colors.cyan}${colors.bright}uniweb refresh${colors.reset} ${colors.dim}— Catch up with teammates AND app authors${colors.reset}
@@ -2216,7 +2222,7 @@ ${colors.bright}Examples:${colors.reset}
   uniweb add project docs --from academic            # Co-located pair + academic content
   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 add extension effects --site site           # Add effects/
 
   uniweb build
   uniweb build --target src                          # Build src/ package

package/src/templates/fetchers/github.js

@@ -1,5 +1,14 @@
 /**
- * GitHub fetcher - downloads templates from GitHub repositories
+ * GitHub fetcher — downloads a template from a GitHub repository
+ * (`github:owner/repo[#ref]`).
+ *
+ * ⭐ Without a token it downloads from GitHub's archive host —
+ * `codeload.github.com/<owner>/<repo>/tar.gz/<ref>`, `HEAD` naming the default
+ * branch — which is not the REST API, so the API's anonymous limit (60 requests an
+ * hour per address) does not apply. With GITHUB_TOKEN set it uses the API's
+ * tarball endpoint, which a private repository needs and which then counts
+ * against the token's own, higher limit. ⛔ Until 2026-10-08 every download went
+ * through the API, token or not.
  */
 
 import { pipeline } from 'node:stream/promises'
@@ -10,6 +19,32 @@ import { join } from 'node:path'
 import * as tar from 'tar'
 import { fetchWithRetry as sharedFetchWithRetry } from '../../utils/fetch-retry.js'
 
+/**
+ * Where to download a repository's tarball from, and with which headers.
+ *
+ * @param {string} owner
+ * @param {string} repo
+ * @param {string} [ref='HEAD'] - Branch, tag, or commit
+ * @param {string|null} [token] - GITHUB_TOKEN, when set
+ * @returns {{ url: string, headers: Record<string, string> }}
+ */
+export function githubTarballRequest(owner, repo, ref = 'HEAD', token = null) {
+  if (token) {
+    return {
+      url: `https://api.github.com/repos/${owner}/${repo}/tarball/${ref}`,
+      headers: {
+        Accept: 'application/vnd.github+json',
+        'User-Agent': 'uniweb-cli',
+        Authorization: `Bearer ${token}`
+      }
+    }
+  }
+  return {
+    url: `https://codeload.github.com/${owner}/${repo}/tar.gz/${ref}`,
+    headers: { 'User-Agent': 'uniweb-cli' }
+  }
+}
+
 /**
  * Fetch a template from a GitHub repository
  *
@@ -27,35 +62,26 @@ export async function fetchGitHubTemplate(owner, repo, options = {}) {
   onProgress?.(`Fetching ${owner}/${repo}@${displayRef} from GitHub...`)
 
   // GitHub provides tarballs without requiring git
-  const tarballUrl = `https://api.github.com/repos/${owner}/${repo}/tarball/${ref}`
+  const token = process.env.GITHUB_TOKEN || null
+  const { url, headers } = githubTarballRequest(owner, repo, ref, token)
 
   const tempDir = await mkdtemp(join(tmpdir(), 'uniweb-template-'))
 
   try {
-    const response = await fetchWithRetry(tarballUrl, {
-      headers: {
-        Accept: 'application/vnd.github+json',
-        'User-Agent': 'uniweb-cli',
-        // Support private repos if GITHUB_TOKEN is set
-        ...(process.env.GITHUB_TOKEN && {
-          Authorization: `Bearer ${process.env.GITHUB_TOKEN}`
-        })
-      }
-    })
+    const response = await fetchWithRetry(url, { headers })
 
     if (!response.ok) {
       if (response.status === 404) {
-        throw new Error(`Repository not found: ${owner}/${repo}`)
+        const at = ref === 'HEAD' ? '' : ` at ${ref}`
+        throw new Error(
+          `Repository not found: ${owner}/${repo}${at}` +
+            (token ? '' : ' — a private repository needs GITHUB_TOKEN')
+        )
       }
-      if (response.status === 403) {
-        const remaining = response.headers.get('x-ratelimit-remaining')
-        if (remaining === '0') {
-          throw new Error(
-            'GitHub API rate limit exceeded. Set GITHUB_TOKEN environment variable for higher limits.'
-          )
-        }
+      if (response.status === 403 && response.headers.get('x-ratelimit-remaining') === '0') {
+        throw new Error('GitHub API rate limit exceeded for this GITHUB_TOKEN.')
       }
-      throw new Error(`GitHub API error: ${response.status}`)
+      throw new Error(`GitHub download failed: HTTP ${response.status}`)
     }
 
     onProgress?.(`Downloading and extracting...`)
@@ -63,7 +89,7 @@ export async function fetchGitHubTemplate(owner, repo, options = {}) {
     await pipeline(
       response.body,
       createGunzip(),
-      tar.extract({ cwd: tempDir, strip: 1 }) // strip 'owner-repo-sha/' prefix
+      tar.extract({ cwd: tempDir, strip: 1 }) // the archive's one top folder: 'repo-ref/' (codeload) or 'owner-repo-sha/' (API)
     )
 
     onProgress?.(`Extracted to ${tempDir}`)

package/src/templates/fetchers/release.js

@@ -1,5 +1,18 @@
 /**
- * GitHub Release fetcher - downloads official templates from GitHub releases
+ * Release fetcher — downloads an official template from the release of the
+ * templates repo this CLI was published with.
+ *
+ * ⭐ ONE REQUEST, AND NOT TO GITHUB'S API. The release is pinned
+ * (templates/resolver.js, OFFICIAL_TEMPLATES_RELEASE) and a release's files sit
+ * at fixed URLs, so the template's tarball is downloaded from its release URL
+ * directly. The name was checked against this CLI's own roster before anything
+ * is fetched, and a tarball the release lacks answers 404.
+ *
+ * ⛔ Until 2026-10-08 a `create` first asked the REST API for the release, to find
+ * its manifest.json, then downloaded the manifest to check the name, then the
+ * tarball: three requests, the first counted against the API's anonymous limit of
+ * 60 an hour per address — which a shared network or a CI runner can spend, and
+ * `create` then failed with "rate limit exceeded".
  */
 
 import { pipeline } from 'node:stream/promises'
@@ -12,69 +25,15 @@ import { fetchWithRetry as sharedFetchWithRetry } from '../../utils/fetch-retry.
 
 // GitHub repository for official templates
 const TEMPLATES_REPO = 'uniweb/templates'
-const GITHUB_API = 'https://api.github.com'
 
 /**
- * Fetch manifest.json from one release of the official templates.
- *
- * ⛔ Always a named release — the one the CLI was published with — and never
- * `latest`: the latest templates can be newer than the packages this CLI pins
- * (templates/resolver.js, OFFICIAL_TEMPLATES_RELEASE).
+ * The URL a release serves one template's tarball at.
  *
- * @param {Object} options - Fetch options
- * @param {string} options.version - The release tag, e.g. `v0.18.4`
- * @param {Function} options.onProgress - Progress callback
- * @returns {Promise<Object>} { version, templates, downloadUrlBase }
+ * @param {string} name - Template name (e.g., 'marketing')
+ * @param {string} version - The release tag, e.g. `v0.18.6`
  */
-export async function fetchManifest(options = {}) {
-  const { version, onProgress } = options
-  if (!version) throw new Error('fetchManifest needs the release tag to read')
-
-  onProgress?.('Fetching template manifest...')
-
-  const releaseResponse = await fetchWithRetry(
-    `${GITHUB_API}/repos/${TEMPLATES_REPO}/releases/tags/${version}`,
-    { headers: getGitHubHeaders() }
-  )
-
-  if (!releaseResponse.ok) {
-    if (releaseResponse.status === 404) {
-      throw new Error(`Release ${version} not found for ${TEMPLATES_REPO}`)
-    }
-    await handleGitHubError(releaseResponse)
-  }
-
-  const release = await releaseResponse.json()
-
-  // Find manifest.json asset
-  const manifestAsset = release.assets?.find((a) => a.name === 'manifest.json')
-  if (!manifestAsset) {
-    throw new Error(
-      `Release ${release.tag_name} does not contain manifest.json. ` +
-        `This may be an older release format.`
-    )
-  }
-
-  // Download manifest
-  const manifestResponse = await fetchWithRetry(
-    manifestAsset.browser_download_url,
-    {
-      headers: getGitHubHeaders()
-    }
-  )
-
-  if (!manifestResponse.ok) {
-    throw new Error(`Failed to download manifest: ${manifestResponse.status}`)
-  }
-
-  const manifest = await manifestResponse.json()
-
-  return {
-    version: release.tag_name,
-    templates: manifest.templates || {},
-    // Base URL for downloading template tarballs
-    downloadUrlBase: `https://github.com/${TEMPLATES_REPO}/releases/download/${release.tag_name}`
-  }
+export function officialTemplateUrl(name, version) {
+  return `https://github.com/${TEMPLATES_REPO}/releases/download/${version}/${name}.tar.gz`
 }
 
 /**
@@ -82,42 +41,25 @@ export async function fetchManifest(options = {}) {
  *
  * @param {string} name - Template name (e.g., 'marketing')
  * @param {Object} options - Fetch options
- * @param {string} options.version - The release tag, e.g. `v0.18.4`
+ * @param {string} options.version - The release tag, e.g. `v0.18.6`
  * @param {Function} options.onProgress - Progress callback
- * @returns {Promise<Object>} { tempDir, version, metadata }
+ * @returns {Promise<Object>} { tempDir, baseTempDir, version }
  */
 export async function fetchOfficialTemplate(name, options = {}) {
   const { version, onProgress } = options
+  if (!version) throw new Error('fetchOfficialTemplate needs the release tag to download from')
 
-  // Get manifest first
-  const manifest = await fetchManifest({ version, onProgress })
+  onProgress?.(`Downloading ${name} template (${version})...`)
 
-  // Check if template exists
-  const templateInfo = manifest.templates[name]
-  if (!templateInfo) {
-    const available = Object.keys(manifest.templates).join(', ')
-    throw new Error(
-      `Template "${name}" not found in release ${manifest.version}.\n` +
-        `Available templates: ${available || 'none'}`
-    )
-  }
-
-  onProgress?.(`Downloading ${name} template (${manifest.version})...`)
-
-  // Download template tarball
-  const tarballUrl = `${manifest.downloadUrlBase}/${name}.tar.gz`
-  const tarballResponse = await fetchWithRetry(tarballUrl, {
-    headers: getGitHubHeaders()
+  const response = await fetchWithRetry(officialTemplateUrl(name, version), {
+    headers: { 'User-Agent': 'uniweb-cli' }
   })
 
-  if (!tarballResponse.ok) {
-    if (tarballResponse.status === 404) {
-      throw new Error(
-        `Template tarball not found: ${name}.tar.gz\n` +
-          `The release may be incomplete or corrupted.`
-      )
+  if (!response.ok) {
+    if (response.status === 404) {
+      throw new Error(`Release ${version} of ${TEMPLATES_REPO} has no template "${name}".`)
     }
-    throw new Error(`Failed to download template: ${tarballResponse.status}`)
+    throw new Error(`Could not download the ${name} template (HTTP ${response.status}).`)
   }
 
   // Extract to temp directory
@@ -126,19 +68,14 @@ export async function fetchOfficialTemplate(name, options = {}) {
   try {
     onProgress?.('Extracting template...')
 
-    await pipeline(
-      tarballResponse.body,
-      createGunzip(),
-      tar.extract({ cwd: tempDir, strip: 0 })
-    )
+    await pipeline(response.body, createGunzip(), tar.extract({ cwd: tempDir, strip: 0 }))
 
-    // Tarball contains template in a subdirectory named after the template
-    // e.g., marketing.tar.gz extracts to marketing/template.json
+    // The tarball holds the template in a folder named after it:
+    // marketing.tar.gz extracts to marketing/template.json
     return {
       tempDir: join(tempDir, name),
       baseTempDir: tempDir, // For cleanup
-      version: manifest.version,
-      metadata: templateInfo
+      version
     }
   } catch (err) {
     // Clean up on error
@@ -147,36 +84,6 @@ export async function fetchOfficialTemplate(name, options = {}) {
   }
 }
 
-/**
- * Get GitHub API headers
- */
-function getGitHubHeaders() {
-  return {
-    Accept: 'application/vnd.github+json',
-    'User-Agent': 'uniweb-cli',
-    // Support private repos or higher rate limits if GITHUB_TOKEN is set
-    ...(process.env.GITHUB_TOKEN && {
-      Authorization: `Bearer ${process.env.GITHUB_TOKEN}`
-    })
-  }
-}
-
-/**
- * Handle GitHub API errors
- */
-async function handleGitHubError(response) {
-  if (response.status === 403) {
-    const remaining = response.headers.get('x-ratelimit-remaining')
-    if (remaining === '0') {
-      throw new Error(
-        'GitHub API rate limit exceeded.\n' +
-          'Set GITHUB_TOKEN environment variable for higher limits.'
-      )
-    }
-  }
-  throw new Error(`GitHub API error: ${response.status}`)
-}
-
 // Retry + timeout live in one place now (`../../utils/fetch-retry.js`).
 // This file carried its own copy, as did the other two fetchers — three
 // byte-identical implementations, and none reachable from the upload paths

package/src/utils/names.js

@@ -5,11 +5,7 @@
  * and detects collisions with existing workspace packages.
  */
 
-import { readWorkspaceConfig, resolveGlob } from './config.js'
 import { discoverFoundations, discoverSites } from './discover.js'
-import { existsSync } from 'node:fs'
-import { readFile } from 'node:fs/promises'
-import { join } from 'node:path'
 
 /**
  * Names that must not be used as package names.
@@ -65,26 +61,13 @@ export async function getExistingPackageNames(rootDir) {
   const foundations = await discoverFoundations(rootDir)
   const sites = await discoverSites(rootDir)
 
+  // An extension is a foundation that declares `extension: true`, so the
+  // discovery above already has it, wherever its folder is. (A second scan of
+  // `extensions/*` stood here until 2026-10-08, when extensions stopped being
+  // placed there by default.)
   for (const f of foundations) names.add(f.name)
   for (const s of sites) names.add(s.name)
 
-  // Extensions (foundations with @uniweb/runtime absent — already captured above)
-  // Also scan extensions/* if it exists
-  const extensionsDir = join(rootDir, 'extensions')
-  if (existsSync(extensionsDir)) {
-    const dirs = await resolveGlob(rootDir, 'extensions/*')
-    for (const dir of dirs) {
-      const pkgPath = join(rootDir, dir, 'package.json')
-      if (!existsSync(pkgPath)) continue
-      try {
-        const pkg = JSON.parse(await readFile(pkgPath, 'utf-8'))
-        if (pkg.name) names.add(pkg.name)
-      } catch {
-        // skip
-      }
-    }
-  }
-
   return names
 }
 

package/src/utils/placement.js

@@ -48,6 +48,20 @@ export const SITE_KIND = {
   projectSub: 'site'
 }
 
+/**
+ * Extension placement: no defaults — `add extension` always has a name, or a
+ * `--path` naming the folder, so neither a default folder nor the co-located
+ * `--project` form is reached. ⛔ Until 2026-10-08 an extension went to
+ * `extensions/<name>/` whatever was asked, `--path` named the folder itself
+ * rather than the one it goes in, and the workspace glob added was always
+ * `extensions/*` — so `--path elsewhere/fx` made a package pnpm never saw.
+ */
+export const EXTENSION_KIND = {
+  defaultDir: null,
+  defaultPkg: null,
+  projectSub: null
+}
+
 /**
  * Resolve where a foundation or site should be placed, given the user's input.
  *

package/src/utils/registry-auth.js

@@ -366,7 +366,7 @@ async function loginViaPassword({ apiBase, nonInteractive }) {
   if (!username || !password) {
     if (nonInteractive) {
       throw new Error(
-        'username/password login needs a terminal — set UNIWEB_USERNAME + UNIWEB_PASSWORD (or UNIWEB_TOKEN).'
+        'username/password login needs a terminal, or UNIWEB_USERNAME + UNIWEB_PASSWORD.'
       )
     }
     const prompts = (await import('prompts')).default
@@ -402,7 +402,7 @@ async function loginViaPassword({ apiBase, nonInteractive }) {
 // Paste a token — verified + identified via /me before it's stored.
 async function loginViaTokenPaste({ apiBase, nonInteractive }) {
   if (nonInteractive) {
-    throw new Error('token paste needs a terminal — set UNIWEB_TOKEN instead.')
+    throw new Error('token paste needs a terminal — pass the token instead: uniweb login --token <bearer>.')
   }
   const prompts = (await import('prompts')).default
   const { token } = await prompts(
@@ -678,7 +678,15 @@ async function workspaceTail(record) {
  *   browser/social (default, once available) · username+password · paste a token.
  * Force a method with --browser / --password / --token-paste (skips the menu).
  * No TTY → no menu; falls back to the non-browser path (env UNIWEB_USERNAME/
- * PASSWORD; UNIWEB_TOKEN is handled earlier by ensureRegistryAuth).
+ * PASSWORD, or `--token <bearer>`).
+ *
+ * ⭐ UNIWEB_TOKEN IS NOT A LOGIN METHOD. It is the one-process bearer each backend
+ * command reads first, ahead of any stored session (ensureRegistryAuth), and it is
+ * never stored — so in a process that has it, login only checks it and says so
+ * (reportTokenProcess). ⛔ This note used to say "UNIWEB_TOKEN is handled earlier by
+ * ensureRegistryAuth", true of the backend commands and not of login, which never
+ * calls it; read as covering login, it put "set UNIWEB_TOKEN" into login's own
+ * refusal — which, with the variable set, refused the same way (measured on 0.88.0).
  *
  * @param {Object} o
  * @param {string} o.apiBase - new-backend origin
@@ -689,7 +697,7 @@ export async function runRegistryLogin({ apiBase, args = [] } = {}) {
   // For THIS backend. It read "the" session and printed `apiBase` beside it, so on a
   // machine logged into another backend it announced "Already logged in … (this origin)"
   // about a session belonging to a different one — and then offered to replace it.
-  const { isNonInteractive } = await import('./interactive.js')
+  const { isNonInteractive, getCliPrefix } = await import('./interactive.js')
   const nonInteractive = isNonInteractive(args)
 
   const key = normOrigin(apiBase)
@@ -701,6 +709,22 @@ export async function runRegistryLogin({ apiBase, args = [] } = {}) {
     args.includes('--browser') ||
     args.includes('--password') ||
     args.includes('--token-paste')
+
+  // A process with UNIWEB_TOKEN is authenticated by it, ahead of any session: a login
+  // that asks for nothing has nothing to do but check it and say so. One that asks for
+  // something — a way of signing in, or a workspace switch — still does it, for the stored
+  // session, after saying that this process does not use that session.
+  const envToken = process.env.UNIWEB_TOKEN
+  if (envToken) {
+    if (!forced && !readOrgFlag(args) && !args.includes('--personal')) {
+      const named = args.some((a) => a === '--server' || a.startsWith('--server='))
+      return reportTokenProcess({ named: named ? key : null, token: envToken })
+    }
+    console.error(
+      `\x1b[2mUNIWEB_TOKEN is set, so this process's backend commands use it (and UNIWEB_WORKSPACE) — not the session or workspace this login stores.\x1b[0m\n`
+    )
+  }
+
   if (existing?.token && !isExpired(existing)) {
     const who =
       existing.username ||
@@ -791,13 +815,21 @@ export async function runRegistryLogin({ apiBase, args = [] } = {}) {
       if (process.env.UNIWEB_USERNAME && process.env.UNIWEB_PASSWORD) {
         method = 'password'
       } else {
+        // Only what works without a terminal: `--password` and `--token-paste` prompt. The
+        // command keeps the backend named, or re-run as printed it would go to the default.
+        const server = args.some((a) => a === '--server' || a.startsWith('--server='))
+          ? ` --server ${key}`
+          : ''
+        console.error(
+          '\x1b[31m✗\x1b[0m Without a terminal, a login needs a way to sign in that asks nothing:'
+        )
         console.error(
-          '\x1b[31m✗\x1b[0m Cannot log in non-interactively without a method.'
+          `    ${getCliPrefix()} login${server} --token <bearer>   (with --org @org or --personal)`
         )
+        console.error('    UNIWEB_USERNAME + UNIWEB_PASSWORD, set for the login')
         console.error(
-          '  Set UNIWEB_USERNAME + UNIWEB_PASSWORD, set UNIWEB_TOKEN, or run `uniweb login` in a terminal.'
+          '  Or skip the login: with UNIWEB_TOKEN set, every backend command in that process uses it, and nothing is stored.'
         )
-        console.error('  Or force one: --password / --token-paste.')
         process.exit(1)
       }
     } else {
@@ -866,3 +898,97 @@ async function finishLogin(record, apiBase, args) {
   console.error(`\x1b[32m✓\x1b[0m Logged in${who} (${apiBase})${await workspaceTail(settled.record)}.`)
   return settled.record
 }
+
+/**
+ * `uniweb login` in a process that has UNIWEB_TOKEN, asking for nothing: there is no login
+ * to do — every backend command here sends the token, ahead of any stored session — so
+ * check it with the backend those commands go to, and say who and where they work as.
+ *
+ * ⭐ CHECKED WHERE IT IS SENT. Those commands go to `getRegistryApiBaseUrl()` — UNIWEB_SERVER,
+ * else the backend logged in to, else the default — while a login goes where `--server`
+ * says. A login naming another backend is refused rather than checked there: a yes from a
+ * backend this process never reaches is a false answer, and the next command would show
+ * it as a 401 from the other one.
+ *
+ * Exits 1 when the token is refused or unreachable, 2 when it is good and its workspace is
+ * not settled (as `finishLogin` does); returns nothing, since nothing is stored.
+ *
+ * @param {object} o
+ * @param {string|null} o.named - the origin `--server` named, or null
+ * @param {string} o.token
+ */
+async function reportTokenProcess({ named, token }) {
+  const { getRegistryApiBaseUrl } = await import('./config.js')
+  const { getCliPrefix } = await import('./interactive.js')
+  const origin = normOrigin(getRegistryApiBaseUrl())
+  if (named && named !== origin) {
+    console.error(
+      `\x1b[31m✗\x1b[0m UNIWEB_TOKEN is set, and this process's backend commands send it to ${origin} — not ${named}.`
+    )
+    console.error(`  To use the token with ${named}: UNIWEB_SERVER=${named}`)
+    console.error(`  To log in to ${named} instead, unset UNIWEB_TOKEN: ${getCliPrefix()} login --server ${named}`)
+    process.exit(1)
+  }
+
+  let account
+  try {
+    account = await fetchMe({ apiBase: origin, token })
+  } catch (err) {
+    console.error(
+      err.status
+        ? `\x1b[31m✗\x1b[0m ${origin} refuses UNIWEB_TOKEN (HTTP ${err.status}).`
+        : `\x1b[31m✗\x1b[0m Could not check UNIWEB_TOKEN with ${origin}: ${err.message}`
+    )
+    process.exit(1)
+  }
+  const who = account?.username || account?.handle || (account?.uuid ? `account ${account.uuid}` : null)
+  console.error(
+    `\x1b[32m✓\x1b[0m No login needed: this process's backend commands use UNIWEB_TOKEN, which ${origin} accepts${who ? ` as \x1b[1m${who}\x1b[0m` : ''}.`
+  )
+  console.error(
+    '\x1b[2m  It comes before any stored session and is never stored. To store a session, name a way to sign in: --password, --browser, --token-paste or --token <bearer>.\x1b[0m'
+  )
+
+  // Their workspace is UNIWEB_WORKSPACE's — never the stored session's — and, with none
+  // named, personal for an account in no organization (resolveWorkspace, workspace.js).
+  const { WORKSPACE_ENV, PERSONAL, parseWorkspaceChoice, headerOf, describeWorkspace } =
+    await import('../backend/workspace.js')
+  const unsettled = (reason, { commandsRefuse }) => {
+    console.error(`\x1b[31m✗\x1b[0m ${reason}`)
+    if (commandsRefuse) {
+      console.error(`\x1b[2m  Until a workspace is named, the commands that work on a site refuse.\x1b[0m`)
+    }
+    process.exit(2)
+  }
+  const raw = process.env[WORKSPACE_ENV]
+  const choice = parseWorkspaceChoice(raw)
+  if (raw && !choice) {
+    unsettled(`${WORKSPACE_ENV}=${JSON.stringify(raw)} names no workspace — give @org, or personal.`, {
+      commandsRefuse: true
+    })
+  }
+  let orgs
+  try {
+    orgs = (await (await import('./registry-orgs.js')).fetchOrgs({ apiBase: origin, token })).orgs
+  } catch (err) {
+    console.error(`\x1b[33m⚠\x1b[0m ${err.message} — the workspace is not checked.`)
+    return
+  }
+  const mine = orgs.map((o) => `@${o.handle}`)
+  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 organizations on ${origin}.`, {
+      commandsRefuse: false
+    })
+  }
+  if (!choice && mine.length) {
+    unsettled(
+      `The account belongs to organizations, so no workspace is assumed: set ${WORKSPACE_ENV}=${mine[0]} (or another, or personal).`,
+      { commandsRefuse: true }
+    )
+  }
+  const where = describeWorkspace(headerOf(choice || PERSONAL))
+  console.error(
+    `  They work in \x1b[1m${where}\x1b[0m${choice ? ` (${WORKSPACE_ENV})` : ' — the account belongs to no organization'}.`
+  )
+}