uniweb 0.12.15 → 0.12.17

package/README.md

@@ -40,12 +40,18 @@ Edit files in `site/pages/` and `src/sections/` to see changes instantly.
 
 Use `--blank` for an empty workspace (no packages) — grow with `uniweb add`.
 
-Or skip the interactive prompt:
+**Two starting points.** Either let the CLI create a new directory:
 
 ```bash
 pnpm create uniweb my-site --template docs
 ```
 
+…or scaffold inside an existing directory (e.g., a freshly-cloned GitHub repo):
+
+```bash
+pnpm create uniweb . --template docs
+```
+
 ### Local Scripts
 
 Run these from the **project root**:
@@ -243,7 +249,7 @@ The parser extracts semantic elements from markdown—`title` from the first hea
 
 ## Foundations Are Portable
 
-The `src/` folder (your project's foundation) ships with your project as a convenience, but a foundation is a dynamically linked module (DML) with no dependency on any specific site. Sites reference foundations by configuration, not by folder proximity.
+The `src/` folder (your project's foundation) ships with your project as a convenience, but a foundation is dynamically loaded — sites reference it by configuration, not by folder proximity.
 
 **Two ways to use a foundation:**
 
@@ -308,8 +314,7 @@ You (or your dev team) write the markdown. Deploy site + foundation together.
 The shortest path to a live site is free, on GitHub Pages, with a custom domain:
 
 ```bash
-npm create uniweb my-site
-cd my-site
+uniweb create .   # from within a freshly-cloned GitHub repo
 uniweb add ci --host=github-pages
 # Commit, push to GitHub, enable Pages in repo settings → live site
 ```
@@ -346,6 +351,7 @@ A future version will let markdown in a git repo and content in the Uniweb apps
 | `uniweb export` | Produce a self-contained `dist/` for any static host. You upload it yourself. `--host=<adapter>` adds host-specific helper files. |
 | `uniweb publish @org/name` | Publish a foundation to the registry (path 2). |
 | `uniweb build` | Inspect a build locally. For shipping, use `deploy` or `export`. |
+| `uniweb update` | Reconcile workspace state with the CLI: self-update the global install, align `@uniweb/*` deps in every `package.json` to the CLI's matrix, refresh `AGENTS.md`. Refuses to outpace declared deps with a stale doc. |
 
 `--host=<adapter>` is the same option across `deploy`, `export`, and `add ci`. Built-in adapters: `cloudflare-pages`, `netlify`, `github-pages`, `vercel`, `s3-cloudfront`, `generic-static`. Each adapter implements only the operations it supports — `add ci` is currently `github-pages`-only because it's the only one that needs a workflow file in the repo.
 
@@ -373,7 +379,7 @@ Full documentation is available at **[github.com/uniweb/docs](https://github.com
 | Content Structure  | [How markdown becomes component props](https://github.com/uniweb/docs/blob/main/reference/content-structure.md) |
 | Component Metadata | [The meta.js schema](https://github.com/uniweb/docs/blob/main/reference/component-metadata.md) |
 | Site Configuration | [site.yml reference](https://github.com/uniweb/docs/blob/main/reference/site-configuration.md) |
-| CLI Commands       | [create, add, build, docs, doctor, i18n](https://github.com/uniweb/docs/blob/main/reference/cli-commands.md) |
+| CLI Commands       | [All CLI commands and flags](https://github.com/uniweb/docs/blob/main/reference/cli-commands.md) |
 | Templates          | [Built-in, official, and external templates](https://github.com/uniweb/docs/blob/main/getting-started/templates.md) |
 | Deployment         | [Two artifacts, two verbs — bundled, linked, and per-host recipes](https://github.com/uniweb/docs/blob/main/development/deploying.md) |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.12.15",
+  "version": "0.12.17",
   "description": "Create structured Vite + React sites with content/code separation",
   "type": "module",
   "bin": {
@@ -46,8 +46,8 @@
     "@uniweb/kit": "0.9.11"
   },
   "peerDependencies": {
-    "@uniweb/content-reader": "1.1.10",
     "@uniweb/build": "0.14.3",
+    "@uniweb/content-reader": "1.1.10",
     "@uniweb/semantic-parser": "1.1.17"
   },
   "peerDependenciesMeta": {

package/partials/agents.md

@@ -150,6 +150,9 @@ uniweb deploy --dry-run           # Resolve foundation/runtime + print summary;
 uniweb export                     # Build dist/ for any static host (no Uniweb account)
 uniweb publish                    # Publish a foundation to the Uniweb registry
 uniweb doctor                     # Diagnose project configuration issues (--fix to auto-repair)
+uniweb update                     # Reconcile workspace state with the CLI: align @uniweb/*
+                                  # deps in every package.json + refresh this AGENTS.md.
+                                  # Use --dry-run to preview, --deps-only to skip the doc.
 
 # Help
 uniweb --help                     # Top-level help
@@ -158,6 +161,8 @@ uniweb <command> --help           # Per-command help (no side effects)
 
 `uniweb deploy` auto-publishes a workspace-local foundation as part of the deploy under a site-scoped slot — no separate `uniweb publish` step needed for site-bound foundations.
 
+If this AGENTS.md was stamped against an older CLI than the workspace's installed `@uniweb/*` packages, run `uniweb update --dry-run` to see the gap. The verb refuses to refresh the doc while declared deps lag the CLI — a stale doc that documents features the installed code doesn't have is worse than no refresh.
+
 ---
 
 ## `package.json` `uniweb` configuration

package/src/commands/update.js

@@ -1,35 +1,32 @@
 /**
- * uniweb update — Update the CLI itself, and (in a Uniweb project) the
- * project's AGENTS.md.
+ * uniweb update — Reconcile a Uniweb workspace's state with the running
+ * CLI's expectations. Three convergence steps, in order:
  *
- * Two responsibilities, in priority order:
+ *   1. Self-update the global CLI install (npm / pnpm / yarn auto-detected).
+ *   2. Align workspace `@uniweb/*` + `uniweb` deps to the CLI's bundled
+ *      version matrix (`getResolvedVersions`), then run `<pm> install`.
+ *   3. Refresh AGENTS.md from the CLI's bundled partial.
  *
- * 1. **Self-update the global install.** Most users running `uniweb update`
- *    expect the verb to update the CLI binary itself (this is what `npm
- *    update -g`, `gh update`, `claude update`, etc. all do). The CLI
- *    detects the relevant package manager and runs the global-install
- *    command for it (`npm i -g uniweb@latest`, `pnpm add -g uniweb@latest`,
- *    `yarn global add uniweb@latest`). In TTY, prompts before executing.
- *    In non-interactive mode, prints the command and exits — never runs an
- *    unconfirmed self-update from a script.
- *
- * 2. **Refresh AGENTS.md** (only when the cwd resolves to a *Uniweb*
- *    project — checked via `package.json::devDependencies::uniweb` or
- *    `dependencies::uniweb` at the workspace root). The previous
- *    implementation walked up looking for ANY pnpm-workspace.yaml or
- *    `package.json::workspaces` root, which falsely identified unrelated
- *    monorepos as Uniweb projects and wrote AGENTS.md into them.
+ * Why steps 2 and 3 belong together: AGENTS.md is regenerated from the
+ * CLI's *current* partials and stamped with `cliVersion`. Refreshing it
+ * while declared deps in `package.json` lag the CLI silently produces a
+ * doc that documents features the installed code doesn't have. The
+ * verb's drift gate refuses that combination unless `--allow-mismatch`
+ * is explicit.
  *
  * Flags:
- *   --agents-only        Skip self-update; only refresh AGENTS.md.
- *   --no-agents          Skip AGENTS.md; only self-update.
- *   --yes                Skip the confirmation prompt before self-update.
- *   --non-interactive    Auto-detected; never runs unconfirmed self-update.
+ *   --agents-only       Skip self-update + deps; only refresh AGENTS.md.
+ *   --deps-only         Skip self-update + AGENTS.md; only align deps.
+ *   --no-agents         Skip the AGENTS.md step.
+ *   --no-deps           Skip the deps-alignment step.
+ *   --dry-run           Print survey + would-be writes; no mutations.
+ *   --allow-mismatch    Permit AGENTS.md refresh when declared deps lag.
+ *   --yes               Skip confirmation prompts (still respects gates).
+ *   --non-interactive   Auto-detected; never auto-installs from a script.
  *
  * Project-local case (CLI lives in node_modules, not global): self-update
- * isn't possible — that's a project decision (bump the dep in
- * package.json). The verb prints that explanation and proceeds with the
- * AGENTS.md refresh path only.
+ * is a no-op (the version is pinned by package.json). Deps + AGENTS.md
+ * paths still run.
  */
 
 import { existsSync, readFileSync, writeFileSync } from 'node:fs'
@@ -37,10 +34,11 @@ import { join } from 'node:path'
 import { spawn } from 'node:child_process'
 import prompts from 'prompts'
 
-import { findWorkspaceRoot } from '../utils/workspace.js'
+import { findWorkspaceRoot, getWorkspacePackages } from '../utils/workspace.js'
 import { readAgentsVersion, generateAgentsContent } from '../utils/agents-stamp.js'
-import { getCliVersion } from '../versions.js'
+import { getCliVersion, getResolvedVersions, updatePackageVersions } from '../versions.js'
 import { isNonInteractive } from '../utils/interactive.js'
+import { detectWorkspacePm, installCmd } from '../utils/pm.js'
 
 const colors = {
   reset: '\x1b[0m',
@@ -55,6 +53,7 @@ const colors = {
 const success = (msg) => console.log(`${colors.green}✓${colors.reset} ${msg}`)
 const warn = (msg) => console.log(`${colors.yellow}⚠${colors.reset} ${msg}`)
 const error = (msg) => console.log(`${colors.red}✗${colors.reset} ${msg}`)
+const info = (msg) => console.log(`${colors.cyan}ℹ${colors.reset} ${msg}`)
 const log = console.log
 
 /**
@@ -72,8 +71,8 @@ function isGlobalInstall() {
 /**
  * Find a *Uniweb* workspace root from cwd. Stricter than findWorkspaceRoot
  * — also requires that the workspace's root package.json declares uniweb
- * as a dep or devDep. Otherwise the previous behavior (walking up to any
- * pnpm-workspace.yaml) writes AGENTS.md into unrelated monorepos.
+ * as a dep or devDep. Otherwise we'd write AGENTS.md and edit package.json
+ * files in unrelated monorepos.
  */
 function findUniwebWorkspace(cwd) {
   const workspaceDir = findWorkspaceRoot(cwd)
@@ -90,9 +89,9 @@ function findUniwebWorkspace(cwd) {
 }
 
 /**
- * Detect the package manager that owns the global install. Heuristic
- * based on the CLI's filesystem path — pnpm and yarn berry use distinctive
- * directory layouts; npm is the fallback.
+ * Detect the package manager that owns the *global* CLI install.
+ * Path-based (different signal than detectWorkspacePm, which reads
+ * lockfiles in the workspace).
  *
  * @returns {'pnpm'|'yarn'|'npm'}
  */
@@ -127,11 +126,21 @@ async function fetchLatestVersion() {
 }
 
 /**
- * Compare two semver strings: 1 if a>b, -1 if a<b, 0 if equal.
+ * Strip a leading semver range operator (^, ~, >=, <, etc.) so two specs
+ * can be compared by their underlying version. Range expressions like
+ * ">=0.5 <0.7" aren't fully parsed — we take the first version-shaped
+ * token. Sufficient for `@uniweb/*` deps which use `^x.y.z` consistently.
+ */
+function stripRange(spec) {
+  return (spec || '').replace(/^[\^~>=<\s]+/, '').trim().split(/\s+/)[0] || ''
+}
+
+/**
+ * Compare two version specs (range prefix tolerated). Returns 1/-1/0.
  */
 function compareSemver(a, b) {
-  const pa = a.split('.').map(Number)
-  const pb = b.split('.').map(Number)
+  const pa = stripRange(a).split('.').map(Number)
+  const pb = stripRange(b).split('.').map(Number)
   for (let i = 0; i < 3; i++) {
     if ((pa[i] || 0) > (pb[i] || 0)) return 1
     if ((pa[i] || 0) < (pb[i] || 0)) return -1
@@ -142,28 +151,177 @@ function compareSemver(a, b) {
 /**
  * Run a shell command, inheriting stdio. Resolves with the exit code.
  */
-function runCommand(cmd) {
+function runCommand(cmd, cwd) {
   return new Promise((resolve) => {
     const [bin, ...rest] = cmd.split(' ')
-    const child = spawn(bin, rest, { stdio: 'inherit' })
+    const child = spawn(bin, rest, { stdio: 'inherit', cwd })
     child.on('close', code => resolve(code ?? 0))
     child.on('error', () => resolve(1))
   })
 }
 
+/**
+ * Survey workspace `@uniweb/*` and `uniweb` deps against the CLI's
+ * bundled version matrix. Returns a structured report with one row per
+ * (package directory, dep section, dep name).
+ *
+ * Comparison is on *declared* versions (package.json), not installed
+ * (node_modules) — that's what the user committed and what they'll
+ * `git diff` after `applyDepUpdates`.
+ */
+async function surveyVersions(workspaceDir) {
+  const targets = getResolvedVersions()
+  const packages = await getWorkspacePackages(workspaceDir)
+  const dirs = ['', ...packages]
+  const rows = []
+  let anyDrift = false
+  let anyAhead = false
+
+  for (const relDir of dirs) {
+    const pkgDir = relDir ? join(workspaceDir, relDir) : workspaceDir
+    const pkgPath = join(pkgDir, 'package.json')
+    if (!existsSync(pkgPath)) continue
+    let pkg
+    try { pkg = JSON.parse(readFileSync(pkgPath, 'utf8')) } catch { continue }
+
+    for (const sectionName of ['dependencies', 'devDependencies', 'peerDependencies']) {
+      const section = pkg[sectionName]
+      if (!section) continue
+      for (const [name, current] of Object.entries(section)) {
+        if (!(name.startsWith('@uniweb/') || name === 'uniweb')) continue
+        const target = targets[name]
+        if (!target) continue
+        const cmp = compareSemver(target, current)
+        let status
+        if (cmp > 0) { status = 'behind'; anyDrift = true }
+        else if (cmp < 0) { status = 'ahead'; anyAhead = true }
+        else { status = 'aligned' }
+        rows.push({
+          relDir: relDir || '(root)',
+          section: sectionName,
+          name,
+          current,
+          target,
+          status,
+        })
+      }
+    }
+  }
+
+  return { targets, rows, anyDrift, anyAhead }
+}
+
+/**
+ * Print the survey report grouped by package directory.
+ */
+function printSurvey(report, cliVersion, agentsVersion) {
+  log('')
+  log(`${colors.bright}uniweb CLI:${colors.reset}             v${cliVersion}`)
+  log(`${colors.bright}AGENTS.md stamp:${colors.reset}        ${agentsVersion ? 'v' + agentsVersion : colors.dim + '(none)' + colors.reset}`)
+  log('')
+
+  if (report.rows.length === 0) {
+    log(`${colors.dim}No @uniweb/* deps found in workspace package.json files.${colors.reset}`)
+    log('')
+    return
+  }
+
+  const byDir = {}
+  for (const row of report.rows) {
+    if (!byDir[row.relDir]) byDir[row.relDir] = []
+    byDir[row.relDir].push(row)
+  }
+
+  log(`${colors.bright}Workspace deps (declared):${colors.reset}`)
+  for (const [dir, dirRows] of Object.entries(byDir)) {
+    log(`  ${colors.dim}${dir}/${colors.reset}`)
+    const maxName = Math.max(...dirRows.map(r => r.name.length))
+    for (const row of dirRows) {
+      const padding = ' '.repeat(maxName - row.name.length)
+      let icon, statusText
+      if (row.status === 'aligned') {
+        icon = `${colors.green}✓${colors.reset}`
+        statusText = `${colors.dim}aligned${colors.reset}`
+      } else if (row.status === 'behind') {
+        icon = `${colors.yellow}✗${colors.reset}`
+        statusText = `${colors.yellow}behind${colors.reset}`
+      } else {
+        icon = `${colors.cyan}↑${colors.reset}`
+        statusText = `${colors.cyan}ahead of CLI${colors.reset}`
+      }
+      log(`    ${icon} ${row.name}${padding}  ${row.current.padEnd(10)} → ${row.target.padEnd(10)}  ${statusText}`)
+    }
+  }
+  log('')
+}
+
+/**
+ * Apply the CLI's bundled matrix to every workspace package.json.
+ * `updatePackageVersions` only touches `@uniweb/*` + `uniweb` keys, so
+ * unrelated deps (`react`, `vite`, `file:../foundation`, etc.) are left
+ * untouched. Returns the list of paths that actually changed.
+ */
+async function applyDepUpdates(workspaceDir, dryRun) {
+  const packages = await getWorkspacePackages(workspaceDir)
+  const dirs = ['', ...packages]
+  const edited = []
+
+  for (const relDir of dirs) {
+    const pkgDir = relDir ? join(workspaceDir, relDir) : workspaceDir
+    const pkgPath = join(pkgDir, 'package.json')
+    if (!existsSync(pkgPath)) continue
+    const original = readFileSync(pkgPath, 'utf8')
+    let pkg
+    try { pkg = JSON.parse(original) } catch { continue }
+
+    const updated = updatePackageVersions(pkg)
+    const newContent = JSON.stringify(updated, null, 2) + (original.endsWith('\n') ? '\n' : '')
+
+    if (newContent !== original) {
+      edited.push(pkgPath)
+      if (!dryRun) writeFileSync(pkgPath, newContent)
+    }
+  }
+
+  return edited
+}
+
+function relativize(path, root) {
+  return path.startsWith(root) ? path.slice(root.length + 1) : path
+}
+
 export async function update(args = []) {
   const agentsOnly = args.includes('--agents-only')
-  const skipAgents = args.includes('--no-agents')
-  const skipPrompt = args.includes('--yes') || isNonInteractive(args)
+  const depsOnly = args.includes('--deps-only')
+  const skipAgents = args.includes('--no-agents') || depsOnly
+  const skipDeps = args.includes('--no-deps') || agentsOnly
+  const dryRun = args.includes('--dry-run')
+  const allowMismatch = args.includes('--allow-mismatch')
+  const nonInteractive = isNonInteractive(args)
+  const skipPrompt = args.includes('--yes') || nonInteractive || dryRun
   const isGlobal = isGlobalInstall()
   const workspaceDir = findUniwebWorkspace(process.cwd())
   const inProject = !!workspaceDir
   const cliVersion = getCliVersion()
 
-  // ─── Step 1: Self-update path ─────────────────────────────────
-  if (!agentsOnly) {
+  if ((agentsOnly || depsOnly) && !inProject) {
+    error(`${agentsOnly ? '--agents-only' : '--deps-only'} requires a Uniweb project (no \`uniweb\` dep in the workspace root).`)
+    log(`${colors.dim}Run this command from inside a project created by${colors.reset} ${colors.cyan}uniweb create${colors.reset}${colors.dim}.${colors.reset}`)
+    process.exit(1)
+  }
+
+  // ── Survey first (always, when in a Uniweb project) ──────────────
+  let survey = null
+  let agentsVersion = null
+  if (inProject) {
+    survey = await surveyVersions(workspaceDir)
+    agentsVersion = readAgentsVersion(join(workspaceDir, 'AGENTS.md'))
+    printSurvey(survey, cliVersion, agentsVersion)
+  }
+
+  // ── Step 1: Self-update path ─────────────────────────────────────
+  if (!agentsOnly && !depsOnly) {
     if (!isGlobal) {
-      // Project-local: can't self-update meaningfully.
       log(`${colors.dim}Running the project-local CLI (v${cliVersion}). This copy is pinned by your${colors.reset}`)
       log(`${colors.dim}project's package.json. To update it, bump${colors.reset} ${colors.cyan}uniweb${colors.reset}${colors.dim} in${colors.reset} ${colors.cyan}package.json${colors.reset}${colors.dim} and re-install.${colors.reset}`)
       log('')
@@ -184,7 +342,10 @@ export async function update(args = []) {
         log(`${colors.dim}Will run:${colors.reset} ${colors.cyan}${cmd}${colors.reset}`)
         log('')
 
-        if (skipPrompt) {
+        if (dryRun) {
+          info(`${colors.dim}--dry-run: would run \`${cmd}\`.${colors.reset}`)
+          log('')
+        } else if (skipPrompt) {
           log(`${colors.dim}Non-interactive — skipping self-update. Run the command above to update.${colors.reset}`)
           log('')
         } else {
@@ -211,15 +372,148 @@ export async function update(args = []) {
     }
   }
 
-  // ─── Step 2: AGENTS.md refresh path ───────────────────────────
+  // ── Step 2: Deps alignment ───────────────────────────────────────
+  if (!skipDeps && inProject && survey) {
+    if (!survey.anyDrift) {
+      success('Workspace deps are aligned with the CLI.')
+      if (survey.anyAhead) {
+        log(`${colors.dim}(Some deps are ahead of the CLI's bundled matrix — left untouched.)${colors.reset}`)
+      }
+      log('')
+    } else {
+      log(`${colors.yellow}⚠${colors.reset}  Some workspace deps lag the CLI's bundled matrix.`)
+      log('')
+
+      let proceed
+      if (dryRun) {
+        proceed = false
+      } else if (skipPrompt) {
+        proceed = !nonInteractive || args.includes('--yes')
+        // In CI without --yes, refuse to mutate. The survey above is the report.
+        if (!proceed) {
+          info(`${colors.dim}Non-interactive — printing the alignment plan; not editing files.${colors.reset}`)
+          log(`${colors.dim}To apply, re-run with${colors.reset} ${colors.cyan}--yes${colors.reset}${colors.dim}, or align manually:${colors.reset}`)
+          log(`  ${colors.cyan}pnpm update "@uniweb/*" uniweb -r${colors.reset}`)
+          log('')
+        }
+      } else {
+        const { go } = await prompts({
+          type: 'confirm',
+          name: 'go',
+          message: `Edit workspace package.json files to align with v${cliVersion}?`,
+          initial: true,
+        })
+        proceed = !!go
+      }
+
+      if (dryRun) {
+        const wouldEdit = await applyDepUpdates(workspaceDir, true)
+        if (wouldEdit.length > 0) {
+          info('Dry-run: would update package.json in:')
+          for (const path of wouldEdit) log(`  ${colors.dim}- ${relativize(path, workspaceDir)}${colors.reset}`)
+          const pm = detectWorkspacePm(workspaceDir)
+          if (pm) {
+            log(`${colors.dim}Then would run:${colors.reset} ${colors.cyan}${installCmd(pm)}${colors.reset}`)
+          } else {
+            log(`${colors.dim}Then would prompt for an install command (no lockfile detected).${colors.reset}`)
+          }
+          log('')
+        }
+      } else if (proceed) {
+        const edited = await applyDepUpdates(workspaceDir, false)
+        if (edited.length === 0) {
+          info('No package.json files needed changes.')
+          log('')
+        } else {
+          for (const path of edited) {
+            success(`Updated ${relativize(path, workspaceDir)}`)
+          }
+          log('')
+
+          // Resolve the workspace PM (lockfile-driven). If absent, ask.
+          let pm = detectWorkspacePm(workspaceDir)
+          if (!pm) {
+            if (nonInteractive) {
+              warn('No lockfile in workspace root — cannot pick an install command for you.')
+              log(`${colors.dim}Run one of:${colors.reset} ${colors.cyan}pnpm install${colors.reset} ${colors.dim}/${colors.reset} ${colors.cyan}yarn install${colors.reset} ${colors.dim}/${colors.reset} ${colors.cyan}npm install${colors.reset}`)
+              log('')
+            } else {
+              const { picked } = await prompts({
+                type: 'select',
+                name: 'picked',
+                message: 'No lockfile found. Which package manager does this workspace use?',
+                choices: [
+                  { title: 'pnpm', value: 'pnpm' },
+                  { title: 'yarn', value: 'yarn' },
+                  { title: 'npm', value: 'npm' },
+                  { title: 'skip — I\'ll install manually', value: null },
+                ],
+              })
+              pm = picked || null
+            }
+          }
+
+          if (pm) {
+            const cmd = installCmd(pm)
+            let runInstall
+            if (nonInteractive) {
+              runInstall = false
+              info(`${colors.dim}Non-interactive — printing install command:${colors.reset}`)
+              log(`  ${colors.cyan}${cmd}${colors.reset}`)
+              log('')
+            } else if (skipPrompt) {
+              runInstall = true
+            } else {
+              const { go } = await prompts({
+                type: 'confirm',
+                name: 'go',
+                message: `Run \`${cmd}\` now?`,
+                initial: true,
+              })
+              runInstall = !!go
+            }
+
+            if (runInstall) {
+              const code = await runCommand(cmd, workspaceDir)
+              if (code === 0) {
+                success('Install complete.')
+                log('')
+              } else {
+                error(`Install failed (exit ${code}). package.json edits are intact.`)
+                const editedRel = edited.map(p => relativize(p, workspaceDir)).join(' ')
+                log(`${colors.dim}To revert:${colors.reset} ${colors.cyan}git checkout -- ${editedRel}${colors.reset}`)
+                log(`${colors.dim}To retry: ${colors.reset} ${colors.cyan}${cmd}${colors.reset}`)
+                log('')
+                process.exit(code)
+              }
+            } else {
+              log(`${colors.dim}Skipped install. Edits saved; run${colors.reset} ${colors.cyan}${cmd}${colors.reset} ${colors.dim}to apply.${colors.reset}`)
+              log('')
+            }
+          }
+        }
+      } else {
+        log(`${colors.dim}Skipped deps alignment.${colors.reset}`)
+        log('')
+      }
+    }
+  }
+
+  // ── Step 3: AGENTS.md ────────────────────────────────────────────
   if (skipAgents) return
   if (!inProject) {
-    if (agentsOnly) {
-      error('Not in a Uniweb project (no `uniweb` dep in the workspace root package.json).')
-      log(`${colors.dim}Run this command from inside a project created by${colors.reset} ${colors.cyan}uniweb create${colors.reset}${colors.dim}.${colors.reset}`)
-      process.exit(1)
-    }
-    // Self-update-only path. Quietly skip AGENTS.md.
+    // Self-update-only invocation outside a Uniweb project: quietly skip.
+    return
+  }
+
+  // Re-survey: deps may have just been edited, which clears the gate.
+  const finalSurvey = await surveyVersions(workspaceDir)
+  if (finalSurvey.anyDrift && !allowMismatch) {
+    warn('AGENTS.md refresh skipped: workspace deps still lag the CLI.')
+    log(`${colors.dim}AGENTS.md from v${cliVersion} would document features not in your installed packages.${colors.reset}`)
+    log(`${colors.dim}Re-run without ${colors.reset}${colors.cyan}--no-deps${colors.reset}${colors.dim}, or pass ${colors.reset}${colors.cyan}--allow-mismatch${colors.reset}${colors.dim} to override.${colors.reset}`)
+    log('')
+    if (agentsOnly) process.exit(1)
     return
   }
 
@@ -230,11 +524,15 @@ export async function update(args = []) {
     return
   }
 
-  // Prompt before writing in TTY, unless --yes / non-interactive (in which
-  // case we err on the side of doing the right thing — refresh — since the
-  // user explicitly invoked `uniweb update` from a Uniweb project).
+  if (dryRun) {
+    info(`Dry-run: would ${currentAgentsVersion ? `update AGENTS.md (v${currentAgentsVersion} → v${cliVersion})` : `create AGENTS.md (v${cliVersion})`}.`)
+    return
+  }
+
   if (!skipPrompt && !agentsOnly) {
-    const action = currentAgentsVersion ? `Update AGENTS.md (v${currentAgentsVersion} → v${cliVersion})?` : `Create AGENTS.md (v${cliVersion})?`
+    const action = currentAgentsVersion
+      ? `Update AGENTS.md (v${currentAgentsVersion} → v${cliVersion})?`
+      : `Create AGENTS.md (v${cliVersion})?`
     const { yes } = await prompts({ type: 'confirm', name: 'yes', message: action, initial: true })
     if (!yes) {
       log(`${colors.dim}Skipped AGENTS.md.${colors.reset}`)

package/src/framework-index.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-05-06T16:32:45.366Z",
+  "generatedAt": "2026-05-06T17:01:18.376Z",
   "packages": {
     "@uniweb/build": {
       "version": "0.14.3",
@@ -92,7 +92,7 @@
       "deps": []
     },
     "@uniweb/unipress": {
-      "version": "0.4.7",
+      "version": "0.4.8",
       "path": "framework/unipress",
       "deps": [
         "@uniweb/build",

package/src/index.js

@@ -23,7 +23,7 @@
 
 import { existsSync, readFileSync } from 'node:fs'
 import { execSync, spawn as spawnChild } from 'node:child_process'
-import { resolve, join, relative, dirname } from 'node:path'
+import { resolve, join, relative, dirname, basename } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import prompts from 'prompts'
 // `doctor`, `add`, `publish`, and `deploy` are loaded lazily via
@@ -43,7 +43,7 @@ import {
   parseTemplateId,
 } from './templates/index.js'
 import { validateTemplate } from './templates/validator.js'
-import { scaffoldWorkspace, scaffoldFoundation, scaffoldSite, applyContent, applyStarter, mergeTemplateDependencies } from './utils/scaffold.js'
+import { scaffoldWorkspace, scaffoldFoundation, scaffoldSite, applyContent, applyStarter, mergeTemplateDependencies, getWorkspaceTemplateOutputs } from './utils/scaffold.js'
 import { detectPackageManager, filterCmd, installCmd, runCmd } from './utils/pm.js'
 import { isNonInteractive, getCliPrefix, stripNonInteractiveFlag, formatOptions } from './utils/interactive.js'
 import { findWorkspaceRoot } from './utils/workspace.js'
@@ -73,6 +73,30 @@ const TEMPLATE_CHOICES = [
   { title: 'Blank workspace', value: 'blank', description: 'Empty workspace — grow with uniweb add' },
 ]
 
+// Files that may pre-exist in the target dir during `uniweb create .` and
+// will be silently overwritten by the scaffold. Anything else colliding
+// causes the verb to abort. README and .gitignore are the only two files
+// the workspace template writes that overlap with what `gh repo create`
+// puts in a fresh repo, and the scaffold's versions are more useful in
+// this context (Vite/Node-aware .gitignore, project-shaped README).
+const IN_PLACE_OVERWRITE_ALLOWED = new Set(['README.md', '.gitignore'])
+
+/**
+ * Slugify a directory name into a valid project slug — lowercase,
+ * `[a-z0-9-]+`, no leading/trailing/duplicated hyphens. Matches the
+ * validation regex used for the interactive name prompt.
+ *
+ * @param {string} name
+ * @returns {string} Slugified name; empty if no valid characters remain.
+ */
+function slugifyName(name) {
+  return String(name)
+    .toLowerCase()
+    .replace(/[^a-z0-9-]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .replace(/-{2,}/g, '-')
+}
+
 function log(message) {
   console.log(message)
 }
@@ -669,6 +693,18 @@ async function main() {
   let projectName = args[1]
   let templateType = null  // null = use new package template flow
 
+  // In-place mode: `uniweb create .` scaffolds into the current working
+  // directory instead of creating a new one. Pairs with the GitHub-first
+  // workflow where the user already cloned an empty repo (README.md and
+  // optionally .gitignore present) and wants to scaffold inside it.
+  const inPlace = projectName === '.'
+  if (inPlace) {
+    // Clear the positional so downstream logic (template prompt, name
+    // prompt, etc.) doesn't see `.` as a literal name. The actual project
+    // name is derived below from the cwd basename or `--name`.
+    projectName = null
+  }
+
   // Check for --template flag
   const templateIndex = args.indexOf('--template')
   if (templateIndex !== -1 && args[templateIndex + 1]) {
@@ -682,11 +718,14 @@ async function main() {
     }
   }
 
-  // Check for --name flag (used for project display name)
+  // Check for --name flag. Accepts both `--name foo` and `--name=foo`.
   let displayName = null
   const nameIndex = args.indexOf('--name')
   if (nameIndex !== -1 && args[nameIndex + 1]) {
     displayName = args[nameIndex + 1]
+  } else {
+    const nameEq = args.find(a => a.startsWith('--name='))
+    if (nameEq) displayName = nameEq.slice('--name='.length)
   }
 
   // Check for --blank flag
@@ -708,6 +747,28 @@ async function main() {
 
   const prefix = getCliPrefix()
 
+  // In-place: derive the project name from the cwd basename (slugified),
+  // or use --name when provided. Skip the interactive name prompt below.
+  if (inPlace) {
+    if (displayName) {
+      projectName = displayName
+    } else {
+      const dirName = basename(process.cwd())
+      const slug = slugifyName(dirName)
+      if (!slug) {
+        error(`Could not derive a valid project name from the current directory ("${dirName}").`)
+        log(`Re-run with ${colors.cyan}--name=<your-name>${colors.reset}.`)
+        process.exit(1)
+      }
+      projectName = slug
+      if (slug !== dirName) {
+        log(`${colors.dim}Project name:${colors.reset} ${slug} ${colors.dim}(slugified from "${dirName}")${colors.reset}`)
+      } else {
+        log(`${colors.dim}Project name:${colors.reset} ${slug}`)
+      }
+    }
+  }
+
   // Non-interactive: fail with actionable message instead of prompting
   if (nonInteractive && !projectName) {
     error(`Missing project name.\n`)
@@ -720,7 +781,7 @@ async function main() {
     templateType = 'starter'
   }
 
-  // Interactive prompts
+  // Interactive prompts (skipped in in-place mode — name was derived above)
   const response = await prompts([
     {
       type: projectName ? null : 'text',
@@ -773,14 +834,40 @@ async function main() {
 
   const effectiveName = displayName || projectName
 
-  // Create project directory
-  const projectDir = resolve(process.cwd(), projectName)
+  // Resolve target directory. In-place mode scaffolds into the cwd;
+  // otherwise create `./<projectName>`.
+  const projectDir = inPlace ? process.cwd() : resolve(process.cwd(), projectName)
 
-  if (existsSync(projectDir)) {
+  if (!inPlace && existsSync(projectDir)) {
     error(`Directory already exists: ${projectName}`)
     process.exit(1)
   }
 
+  if (inPlace) {
+    // Conflict check: enumerate the workspace template's would-write paths
+    // (the only stage that touches the project root) and bail if any
+    // collide with existing files outside the small allowlist.
+    //
+    // Allowlist: README.md and .gitignore overwrite cleanly. README is
+    // typically GitHub-generated boilerplate; .gitignore should be ours
+    // since the scaffold ships sensible Vite/Node ignores.
+    const outputs = await getWorkspaceTemplateOutputs({ blank: isBlank })
+    const conflicts = []
+    for (const rel of outputs) {
+      const full = resolve(projectDir, rel)
+      if (existsSync(full) && !IN_PLACE_OVERWRITE_ALLOWED.has(rel)) {
+        conflicts.push(rel)
+      }
+    }
+    if (conflicts.length > 0) {
+      error(`Cannot scaffold in place — these files would be overwritten:`)
+      for (const c of conflicts) log(`  ${colors.yellow}${c}${colors.reset}`)
+      log('')
+      log(`Move or remove them, then re-run ${colors.cyan}uniweb create .${colors.reset}.`)
+      process.exit(1)
+    }
+  }
+
   // Template routing logic
   const progressCb = (msg) => log(`  ${colors.dim}${msg}${colors.reset}`)
   const warningCb = (msg) => log(`  ${colors.yellow}Warning: ${msg}${colors.reset}`)
@@ -879,13 +966,13 @@ async function main() {
 
   if (isBlank) {
     log(`Next steps:\n`)
-    log(`  ${colors.cyan}cd ${projectName}${colors.reset}`)
+    if (!inPlace) log(`  ${colors.cyan}cd ${projectName}${colors.reset}`)
     log(`  ${colors.cyan}${prefix} add project${colors.reset}`)
     log(`  ${colors.cyan}${installCmd(pm)}${colors.reset}`)
     log(`  ${colors.cyan}${prefix} dev${colors.reset}                       ${colors.dim}# Start dev server${colors.reset}`)
   } else {
     log(`Next steps:\n`)
-    log(`  ${colors.cyan}cd ${projectName}${colors.reset}`)
+    if (!inPlace) log(`  ${colors.cyan}cd ${projectName}${colors.reset}`)
     log(`  ${colors.cyan}${installCmd(pm)}${colors.reset}`)
     log(`  ${colors.cyan}${prefix} dev${colors.reset}                       ${colors.dim}# Start dev server${colors.reset}`)
   }
@@ -979,6 +1066,7 @@ ${colors.cyan}${colors.bright}uniweb create${colors.reset} ${colors.dim}— Crea
 
 ${colors.bright}Usage:${colors.reset}
   uniweb create [name] [options]
+  uniweb create .                Scaffold into the current directory
 
 ${colors.bright}Options:${colors.reset}
   --template <type>  Project template (default: starter)
@@ -987,13 +1075,24 @@ ${colors.bright}Options:${colors.reset}
                      npm:      @scope/template-name
                      GitHub:   github:user/repo or https://github.com/user/repo
   --blank            Create an empty workspace (grow with \`uniweb add\`)
-  --name <name>      Project display name
+  --name <name>      Project name (overrides slugified basename when used with \`.\`)
   --no-git           Skip git repository initialization
 
+${colors.bright}In-place mode (\`uniweb create .\`):${colors.reset}
+  Pairs with the GitHub-first workflow — clone an empty repo locally
+  (README, optional .gitignore), then scaffold inside it. Project name
+  is the cwd basename, slugified to a valid npm name. Pass \`--name\` to
+  override. Pre-existing \`README.md\` and \`.gitignore\` are overwritten;
+  any other collision aborts with the list of conflicting files. Skips
+  \`git init\` when a \`.git/\` directory already exists.
+
 ${colors.bright}Examples:${colors.reset}
   uniweb create my-project                       # Foundation + site + starter content
   uniweb create my-project --template marketing  # Official template
   uniweb create my-project --blank               # Empty workspace
+  uniweb create .                                # Scaffold into current dir
+  uniweb create . --template docs                # In place + a content template
+  uniweb create . --name=my-app                  # In place, explicit slug
 `,
     dev: `
 ${colors.cyan}${colors.bright}uniweb dev${colors.reset} ${colors.dim}— Start a dev server for a site${colors.reset}
@@ -1185,28 +1284,39 @@ Prints the parsed content shape of a markdown file or folder — the
 Useful for debugging "why isn't my section getting X?".
 `,
     update: `
-${colors.cyan}${colors.bright}uniweb update${colors.reset} ${colors.dim}— Update the CLI itself, plus AGENTS.md when in a project${colors.reset}
+${colors.cyan}${colors.bright}uniweb update${colors.reset} ${colors.dim}— Reconcile workspace state with the running CLI${colors.reset}
 
 ${colors.bright}Usage:${colors.reset}
-  uniweb update                Self-update + (in project) refresh AGENTS.md
-  uniweb update --agents-only  Only refresh AGENTS.md (skip self-update)
-  uniweb update --no-agents    Only self-update (skip AGENTS.md)
-  uniweb update --yes          Skip the confirmation prompts
+  uniweb update                     Self-update + align deps + refresh AGENTS.md
+  uniweb update --deps-only         Only align workspace @uniweb/* deps
+  uniweb update --agents-only       Only refresh AGENTS.md
+  uniweb update --no-deps           Skip the deps-alignment step
+  uniweb update --no-agents         Skip the AGENTS.md step
+  uniweb update --dry-run           Print survey + would-be writes; no mutations
+  uniweb update --allow-mismatch    Refresh AGENTS.md even if declared deps lag
+  uniweb update --yes               Skip confirmation prompts
 
 ${colors.bright}What it does:${colors.reset}
-  1. Self-update the global install via npm / pnpm / yarn (auto-detected).
-     In TTY, prompts before running. In CI / non-interactive, prints the
-     command and exits without running it.
-  2. If the cwd resolves to a Uniweb project (root package.json declares
-     \`uniweb\` as a dep), refreshes AGENTS.md from the CLI's bundled
-     version. Outside a Uniweb project, this step is skipped — the
-     command will not write AGENTS.md into unrelated directories.
+  Prints a version survey first (CLI version, AGENTS.md stamp, every
+  @uniweb/* + uniweb dep declared in workspace package.json files,
+  marked aligned / behind / ahead). Then three steps:
+
+  1. ${colors.bright}Self-update${colors.reset} the global install via npm / pnpm / yarn
+     (auto-detected). TTY prompts; non-interactive prints the command.
+  2. ${colors.bright}Align workspace deps${colors.reset} to the CLI's bundled version matrix —
+     edits every workspace package.json (only @uniweb/* + uniweb keys),
+     then offers to run the workspace's package manager (lockfile-detected:
+     pnpm-lock.yaml → pnpm, yarn.lock → yarn, package-lock.json → npm).
+     If the install fails, package.json edits are kept and a revert
+     command is printed.
+  3. ${colors.bright}Refresh AGENTS.md${colors.reset} from the CLI's bundled partial. Refuses to
+     run while declared deps still lag the CLI (would document features
+     not in your installed packages); pass --allow-mismatch to override.
 
 ${colors.bright}Project-local installs:${colors.reset}
   When the running CLI is project-local (lives in node_modules), self-
   update is a no-op — the version is pinned by your project's
-  package.json. The verb prints that explanation and proceeds with the
-  AGENTS.md refresh path only.
+  package.json. The deps + AGENTS.md steps still run.
 `,
   }
 

package/src/templates/processor.js

@@ -224,6 +224,53 @@ export async function copyTemplateDirectory(sourcePath, targetPath, data, option
   }
 }
 
+/**
+ * Enumerate the output paths a template directory would write, without
+ * touching disk. Mirrors `copyTemplateDirectory`'s naming rules:
+ *   - `.hbs` extension is stripped
+ *   - `_dir` is renamed to `.dir` (but `__dir` is preserved as `_dir` would be)
+ *   - `template.json` is excluded
+ *   - `skip` filenames are excluded by their post-rename name
+ *
+ * Returns relative paths (POSIX-style separators on POSIX, native on Windows
+ * — `path.join` semantics). Used by the in-place create flow to detect
+ * conflicts before any I/O begins.
+ *
+ * @param {string} sourcePath - Source template directory
+ * @param {Object} [options]
+ * @param {string[]} [options.skip] - Output filenames to exclude
+ * @returns {Promise<string[]>}
+ */
+export async function enumerateTemplateOutputs(sourcePath, options = {}) {
+  const { skip = [] } = options
+  const outputs = []
+  await enumerateInto(sourcePath, '', outputs, skip)
+  return outputs
+}
+
+async function enumerateInto(sourcePath, relPath, outputs, skip) {
+  const entries = await fs.readdir(sourcePath, { withFileTypes: true })
+  for (const entry of entries) {
+    const sourceName = entry.name
+    if (entry.isDirectory()) {
+      const targetName = sourceName.startsWith('_') && !sourceName.startsWith('__')
+        ? `.${sourceName.slice(1)}`
+        : sourceName
+      await enumerateInto(
+        path.join(sourcePath, sourceName),
+        relPath ? path.join(relPath, targetName) : targetName,
+        outputs,
+        skip,
+      )
+    } else {
+      if (sourceName === 'template.json') continue
+      const outputName = sourceName.endsWith('.hbs') ? sourceName.slice(0, -4) : sourceName
+      if (skip.includes(outputName)) continue
+      outputs.push(relPath ? path.join(relPath, outputName) : outputName)
+    }
+  }
+}
+
 /**
  * Clear the template cache
  */

package/src/utils/pm.js

@@ -5,9 +5,17 @@
  * and generate PM-appropriate commands for output messages.
  */
 
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+
 /**
  * Detect which package manager invoked the CLI.
  * Uses the standard npm_config_user_agent env var (same technique as create-vite, create-next-app).
+ *
+ * Note: this returns the *invoker* PM, which is empty when the user runs
+ * a global CLI binary directly from a shell. For the workspace's own PM
+ * (driven by lockfile presence), use `detectWorkspacePm`.
+ *
  * @returns {'pnpm' | 'npm'}
  */
 export function detectPackageManager() {
@@ -16,6 +24,22 @@ export function detectPackageManager() {
   return 'npm'
 }
 
+/**
+ * Detect the workspace's package manager by inspecting lockfiles at the
+ * workspace root. This is the right signal for "what PM should I use to
+ * install in this workspace" — independent of how the CLI was invoked.
+ *
+ * @param {string} workspaceRoot - Absolute path to workspace root
+ * @returns {'pnpm' | 'yarn' | 'npm' | null} - null when no lockfile is present
+ */
+export function detectWorkspacePm(workspaceRoot) {
+  if (!workspaceRoot) return null
+  if (existsSync(join(workspaceRoot, 'pnpm-lock.yaml'))) return 'pnpm'
+  if (existsSync(join(workspaceRoot, 'yarn.lock'))) return 'yarn'
+  if (existsSync(join(workspaceRoot, 'package-lock.json'))) return 'npm'
+  return null
+}
+
 /**
  * Generate a workspace-filtered command.
  * pnpm: "pnpm --filter site dev"
@@ -33,11 +57,13 @@ export function filterCmd(pm, pkg, cmd) {
 
 /**
  * Generate an install command.
- * @param {'pnpm' | 'npm'} pm
+ * @param {'pnpm' | 'yarn' | 'npm'} pm
  * @returns {string}
  */
 export function installCmd(pm) {
-  return pm === 'pnpm' ? 'pnpm install' : 'npm install'
+  if (pm === 'pnpm') return 'pnpm install'
+  if (pm === 'yarn') return 'yarn install'
+  return 'npm install'
 }
 
 /**

package/src/utils/scaffold.js

@@ -11,7 +11,7 @@ import { join, dirname } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import yaml from 'js-yaml'
 import Handlebars from 'handlebars'
-import { copyTemplateDirectory, registerVersions } from '../templates/processor.js'
+import { copyTemplateDirectory, enumerateTemplateOutputs, registerVersions } from '../templates/processor.js'
 import { getVersionsForTemplates, getCliVersion } from '../versions.js'
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
@@ -48,6 +48,28 @@ export async function scaffoldWorkspace(targetDir, context, options = {}) {
   })
 }
 
+/**
+ * Return the relative paths the workspace template would write into the
+ * project root, given the same skip rules `scaffoldWorkspace` applies.
+ * Used by the in-place create flow (`uniweb create .`) to detect conflicts
+ * before any I/O begins.
+ *
+ * Only the workspace template's outputs are enumerated. The foundation,
+ * site, and starter stages write into newly-created subdirectories
+ * (`src/`, `site/`) that don't pre-exist in a target like a fresh GitHub
+ * clone, so they can't conflict.
+ *
+ * @param {Object} [options]
+ * @param {boolean} [options.blank] - True when scaffolding a blank workspace
+ *   (no packages yet) — skips `pnpm-workspace.yaml`, mirroring scaffoldWorkspace.
+ * @returns {Promise<string[]>}
+ */
+export async function getWorkspaceTemplateOutputs({ blank = false } = {}) {
+  const skip = blank ? ['pnpm-workspace.yaml'] : []
+  const templatePath = join(TEMPLATES_DIR, 'workspace')
+  return enumerateTemplateOutputs(templatePath, { skip })
+}
+
 /**
  * Scaffold a foundation from the foundation package template
  *