uniweb 0.56.5 → 0.56.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.56.5",
+  "version": "0.56.7",
   "description": "Create structured Vite + React sites with content/code separation",
   "type": "module",
   "bin": {
@@ -42,15 +42,16 @@
     "prompts": "^2.4.2",
     "tar": "^7.0.0",
     "@uniweb/core": "^0.29.4",
-    "@uniweb/kit": "^0.19.2",
     "@uniweb/runtime": "^0.26.4",
-    "@uniweb/schemas": "^0.3.0",
-    "@uniweb/semantic-parser": "^1.4.0"
+    "@uniweb/schemas": "^0.3.1",
+    "@uniweb/content-writer": "^0.3.4",
+    "@uniweb/kit": "^0.19.3",
+    "@uniweb/semantic-parser": "^1.4.1"
   },
   "peerDependencies": {
-    "@uniweb/build": "^0.52.4",
+    "@uniweb/build": "^0.52.6",
     "@uniweb/content-reader": "^1.2.5",
-    "@uniweb/semantic-parser": "^1.4.0"
+    "@uniweb/semantic-parser": "^1.4.1"
   },
   "peerDependenciesMeta": {
     "@uniweb/build": {

package/partials/agents.md

@@ -341,7 +341,7 @@ Description paragraph.
 ![Image](./image.jpg)
 ```
 
-Heading levels set *structure* (pretitle, title, subtitle), not font size — the component controls visual sizing. The `#>` label line marks a pretitle explicitly (any number of leading `#`s spells the same label); a smaller ordinary heading directly above the title also becomes the pretitle.
+Heading levels set *structure* (pretitle, title, subtitle), not font size — the component controls visual sizing. Write a pretitle as a `#>` label line — any number of leading `#`s spells the same label, so match the heading you are labelling. A smaller ordinary heading directly above the title is *also* read as a pretitle, which is how files written before label lines keep working; prefer `#>`, because it says what it is wherever it lands rather than depending on what follows it.
 
 **A section with no `type:` renders through the foundation's default section type — a component named `Section`, unless the foundation's `main.js` sets `defaultSection` to something else.** This is what lets a folder of plain markdown with no frontmatter at all become pages: mounted documentation, an imported wiki, anything written before it met this framework. If such content renders blank, the foundation has no `Section` — that, not the markdown, is what to fix.
 
@@ -356,8 +356,9 @@ The semantic parser produces a flat, guaranteed structure. No null checks needed
 ```js
 content = {
   title: '',        // Main heading (string or string[] for multi-line)
-  pretitle: '',     // `#>` label line(s), or smaller headings stacked above
-                    //   the title (string or string[])
+  pretitle: '',     // `#>` label line(s) — also filled by smaller headings
+                    //   stacked above the title, for older content
+                    //   (string or string[])
   subtitle: '',     // Line(s) one step below the title — each further
                     //   one-step descent is another line (string or string[])
   paragraphs: [],   // Text blocks
@@ -401,7 +402,7 @@ Lightning quick.               │  content.items[0].paragraphs[0] = "Lightning
 Enterprise-grade security.     │  content.items[1].paragraphs[0] = "Enterprise-grade…"
 ```
 
-The staircase rule produces this — each heading relates to the one before it: the same size adds another line to the same part; **one step smaller** joins the headline as the next part down (the subtitle, then further subtitle lines); **two steps smaller** starts an item; and once body content has begun, *any* heading starts an item. `#>` label lines, and smaller headings stacked above the title, become `pretitle`.
+The staircase rule produces this — each heading relates to the one before it: the same size adds another line to the same part; **one step smaller** joins the headline as the next part down (the subtitle, then further subtitle lines); **two steps smaller** starts an item; and once body content has begun, *any* heading starts an item. `#>` label lines become `pretitle`; so do smaller headings stacked above the title, which is the older spelling.
 
 ### Items have the full content shape
 

package/src/commands/add.js

@@ -35,6 +35,7 @@ import {
   updateRootScripts
 } from '../utils/config.js'
 import { discoverFoundations, discoverSites } from '../utils/discover.js'
+import { generateStarter, reportStarter, declarationFor } from './starter.js'
 import {
   validatePackageName,
   getExistingPackageNames,
@@ -73,17 +74,30 @@ const colors = {
   red: '\x1b[31m'
 }
 
+// Porcelain (`--json`) mode: stdout carries ONLY the JSON, so every human line
+// diverts to stderr — the convention `register.js` already follows and
+// `families.js` states ("stdout carries JSON and nothing else, so it pipes").
+//
+// ⛔ It is set per run rather than only when true, because a module-level flag
+// that is only ever turned ON leaks into the next call in the same process —
+// which is every call in the test suite.
+let jsonMode = false
+export function setAddJsonMode(on) {
+  jsonMode = Boolean(on)
+}
+
 function log(message) {
-  console.log(message)
+  if (jsonMode) console.error(message)
+  else console.log(message)
 }
 function success(message) {
-  console.log(`${colors.green}✓${colors.reset} ${message}`)
+  log(`${colors.green}✓${colors.reset} ${message}`)
 }
 function error(message) {
   console.error(`${colors.red}✗${colors.reset} ${message}`)
 }
 function info(message) {
-  console.log(`${colors.dim}${message}${colors.reset}`)
+  log(`${colors.dim}${message}${colors.reset}`)
 }
 
 /**
@@ -106,12 +120,19 @@ function parseArgs(args) {
     // scaffold PR-preview workflows.
     target: null,
     projectName: null,
-    previews: true
+    previews: true,
+    // `add section` only: generate starter content for the section type from
+    // its `content:` declaration, and which preset's params to frontmatter it
+    // with. `--write` sends the markdown to a file instead of stdout.
+    starter: false,
+    preset: null,
+    write: null,
+    json: false
   }
 
   // Booleans (no value) consumed up-front so the value-flag loop below
   // doesn't accidentally swallow the next positional.
-  const BOOLEAN_FLAGS = new Set(['--force', '--no-previews'])
+  const BOOLEAN_FLAGS = new Set(['--force', '--no-previews', '--starter', '--json'])
 
   // Value flags, mapped to their result key. Both spellings are accepted:
   // `--host github-pages` and `--host=github-pages`.
@@ -131,7 +152,9 @@ function parseArgs(args) {
     '--host': 'host',
     '--domain': 'domain',
     '--target': 'target',
-    '--project-name': 'projectName'
+    '--project-name': 'projectName',
+    '--preset': 'preset',
+    '--write': 'write'
   }
 
   /** Split `--flag=value` into [flag, value]; `--flag` into [flag, null]. */
@@ -169,6 +192,10 @@ function parseArgs(args) {
       result.force = true
     } else if (flag === '--no-previews') {
       result.previews = false
+    } else if (flag === '--starter') {
+      result.starter = true
+    } else if (flag === '--json') {
+      result.json = true
     }
   }
 
@@ -182,11 +209,6 @@ export async function add(rawArgs) {
   const nonInteractive = isNonInteractive(rawArgs)
   const args = stripNonInteractiveFlag(rawArgs)
 
-  if (args[0] === '--help' || args[0] === '-h') {
-    showAddHelp()
-    return
-  }
-
   const pm = detectPackageManager()
   const prefix = getCliPrefix()
 
@@ -1074,6 +1096,7 @@ async function wireExtensionToSite(
  * Add a section type to a foundation
  */
 async function addSection(rootDir, opts) {
+  setAddJsonMode(opts.json)
   let name = opts.name
 
   // Interactive name prompt when not provided
@@ -1169,10 +1192,31 @@ async function addSection(rootDir, opts) {
   const sectionDir = join(sectionsDir, name)
   const relSectionPath = relative(foundationDir, sectionDir)
 
+  // ⭐ `--starter` ON AN EXISTING SECTION IS NOT AN ERROR. The flag asks one
+  // question — *what content would an author start this section with?* — and a
+  // section type that already exists is the case where it has a real `content:`
+  // declaration to answer from. Refusing here would make the flag testable only
+  // against stubs, which is the one case where the answer is least interesting.
+  // Nothing is scaffolded and nothing is overwritten on this path.
   if (existsSync(sectionDir)) {
+    if (opts.starter) {
+      const { markdown, result } = await generateStarter({
+        name,
+        sectionDir,
+        preset: opts.preset,
+        json: opts.json,
+        write: opts.write,
+      })
+      if (!opts.json) {
+        if (!opts.write) log('\n' + markdown.trimEnd())
+        reportStarter(result, { write: opts.write })
+      }
+      return
+    }
     error(
       `Section '${name}' already exists at ${foundation.path}/${relSectionPath}/`
     )
+    log(`  ${colors.dim}--starter generates starter content for it without touching the files.${colors.reset}`)
     process.exit(1)
   }
 
@@ -1207,9 +1251,21 @@ export default function ${name}({ content, params }) {
 }
 `
 
+  // With `--starter`, the scaffold gets a `content:` declaration derived from
+  // the family the name resolves to — so the three pieces agree: a declaration,
+  // a component that reads it, and content that fills it. Without the flag the
+  // stub declares nothing, exactly as before.
+  let starterDeclaration = ''
+  let starterResult = null
+  if (opts.starter) {
+    const preview = await generateStarter({ name, sectionDir: sectionDir })
+    starterResult = preview.result
+    starterDeclaration = await declarationFor(preview.result)
+  }
+
   const metaContent = `export default {
   title: '${name}',
-  description: '',
+  description: '',${starterDeclaration}
   params: {},
 }
 `
@@ -1230,6 +1286,37 @@ export default function ${name}({ content, params }) {
       `${colors.dim}The dev server will pick it up automatically.${colors.reset}`
     )
   }
+
+  if (starterResult) {
+    // Regenerate against the declaration just written, so what is printed is
+    // what this section's own `meta.js` now asks for rather than the family's
+    // guess — the two agree here, and saying it from the file keeps them so.
+    const { markdown, result } = await generateStarter({
+      name,
+      sectionDir,
+      preset: opts.preset,
+      json: opts.json,
+      write: opts.write,
+    })
+    if (!opts.json) {
+      log('')
+      log(`${colors.dim}Starter content for a page section:${colors.reset}`)
+      if (!opts.write) log('\n' + markdown.trimEnd())
+      reportStarter(result, { write: opts.write })
+      // The stub component reads three elements. The declaration above may name
+      // more, because it comes from the family rather than from the stub — say
+      // so, rather than leave a developer wondering why half the content they
+      // were just handed renders as nothing.
+      const stubReads = new Set(['title', 'paragraphs', 'links'])
+      const unread = Object.keys(result.content).filter((slot) => !stubReads.has(slot))
+      if (unread.length) {
+        log(
+          `  ${colors.dim}index.jsx reads title, paragraphs and links — extend it for: ${unread.join(', ')}${colors.reset}`
+        )
+        log('')
+      }
+    }
+  }
 }
 
 /**
@@ -1729,74 +1816,3 @@ function parseNodeMajor(engines) {
   return match ? match[1] : null
 }
 
-/**
- * Show help for the add command
- */
-function showAddHelp() {
-  log(`
-${colors.cyan}${colors.bright}Uniweb Add${colors.reset}
-
-Add projects, foundations, sites, extensions, section types, or CI workflows to your workspace.
-
-${colors.bright}Usage:${colors.reset}
-  uniweb add project [name] [options]
-  uniweb add foundation [name] [options]
-  uniweb add site [name] [options]
-  uniweb add extension <name> [options]
-  uniweb add section <name> [options]
-  uniweb add ci [options]
-
-${colors.bright}Common Options:${colors.reset}
-  --from <template>  Apply content from a template after scaffolding
-  --path <dir>       Custom directory for the package
-
-${colors.bright}Foundation Options:${colors.reset}
-  --project <name>   Group under a project directory (co-located layout)
-
-${colors.bright}Site Options:${colors.reset}
-  --foundation <n>   Foundation to wire to (prompted if multiple exist)
-  --project <name>   Group under a project directory (co-located layout)
-
-${colors.bright}Extension Options:${colors.reset}
-  --site <name>      Site to wire extension URL into
-
-${colors.bright}Section Options:${colors.reset}
-  --foundation <n>   Foundation to add section to (prompted if multiple exist)
-
-${colors.bright}CI Options:${colors.reset}
-  --host <name>          github-pages | cloudflare-pages | netlify | vercel
-                         (prompted when omitted)
-  --target <what>        site (default) | foundation
-                         'foundation' publishes built foundations at permanent
-                         versioned URLs — the free alternative to the catalog
-  --site <name>          Site the workflow builds (prompted if multiple exist)
-  --foundation <name>    With --target foundation: publish just this one
-  --domain <host>        Custom domain (GitHub Pages: writes CNAME, serves at root)
-  --project-name <name>  Name to register under on the host (default: the
-                         workspace name; Cloudflare Pages project, etc.)
-  --no-previews          Skip the per-PR preview workflow
-  --force                Overwrite an existing workflow file
-
-${colors.dim}Hosts that support PR previews: cloudflare-pages, netlify, vercel.
-GitHub Pages has no preview environment, so it scaffolds a deploy workflow only.${colors.reset}
-
-${colors.bright}Examples:${colors.reset}
-  uniweb add project docs                              # Create docs/foundation/ + docs/site/
-  uniweb add project docs --from academic              # Co-located pair + academic content
-  uniweb add foundation                                # Create ./foundation/ at root
-  uniweb add foundation ui                             # Create ./foundations/ui/
-  uniweb add site                                      # Create ./site/ at root
-  uniweb add site blog --foundation marketing          # Create ./sites/blog/ wired to marketing
-  uniweb add extension effects --site site             # Create ./extensions/effects/
-  uniweb add section Hero                              # Create Hero section type
-  uniweb add section Hero --foundation ui              # Target specific foundation
-  uniweb add foundation --project docs                 # Create ./docs/foundation/ (co-located)
-  uniweb add site --project docs                       # Create ./docs/site/ (co-located)
-  uniweb add ci                                        # Pick a host, add a deploy workflow
-  uniweb add ci --host github-pages --site marketing   # Pick host + site explicitly
-  uniweb add ci --host netlify                         # Deploy + PR-preview workflows
-  uniweb add ci --host vercel --no-previews            # Deploy workflow only
-  uniweb add ci --domain mysite.com                    # Custom domain → writes CNAME + UNIWEB_BASE=/
-  uniweb add ci --target foundation                    # Publish foundations at versioned URLs
-`)
-}

package/src/commands/starter.js

@@ -0,0 +1,202 @@
+/**
+ * Starter content for a section type — `uniweb add section <Name> --starter`.
+ *
+ * ⭐ IT IS DERIVED FROM `content:`, NOT AUTHORED. A developer declares what
+ * their component expects; this turns that declaration into something an author
+ * can edit instead of an empty box. There is no `starter:` key in `meta.js` and
+ * there should not be [Diego, 2026-09-16] — authored sample copy drifts against
+ * the declaration it is meant to match, and it can never be localized, because a
+ * developer's string is the foundation's own words and is shown verbatim in
+ * every UI language.
+ *
+ * ⚖️ THE GENERATOR IS NOT HERE. It is `@uniweb/schemas/starter`, because the
+ * visual editor is its other caller and must reach it in a browser — this file
+ * is the CLI's rendering of the same answer. Anything that decides WHAT the
+ * content is belongs there; what is left here is reading a `meta.js` off disk
+ * and serializing.
+ */
+
+import { existsSync } from 'node:fs'
+import { readFile, writeFile } from 'node:fs/promises'
+import { join, dirname } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { createHash } from 'node:crypto'
+
+const colors = {
+  reset: '\x1b[0m',
+  bright: '\x1b[1m',
+  dim: '\x1b[2m',
+  cyan: '\x1b[36m',
+  yellow: '\x1b[33m',
+}
+
+/**
+ * Load a section's `meta.js` as it is on disk NOW.
+ *
+ * ⛔ The URL carries the file's content hash. Node caches an ES module by URL
+ * for the life of the process, and `@uniweb/build`'s own loader hit exactly this
+ * — a dev server regenerating after a `meta.js` edit re-imported the file it had
+ * started with. Same rule here, same reason.
+ */
+async function loadMeta(metaPath) {
+  const version = createHash('sha1').update(await readFile(metaPath)).digest('hex').slice(0, 16)
+  const mod = await import(`${pathToFileURL(metaPath).href}?content=${version}`)
+  return mod.default
+}
+
+/**
+ * The three framework functions this composes, imported at call time.
+ *
+ * ⚖️ Dynamic, matching `inspect.js`: these resolve through the project's own
+ * workspace, and a clear message beats a stack trace when one is missing.
+ */
+async function loadPipeline() {
+  try {
+    const [schemas, content, parser, writer] = await Promise.all([
+      import('@uniweb/schemas/starter'),
+      import('@uniweb/schemas/content'),
+      import('@uniweb/semantic-parser'),
+      import('@uniweb/content-writer'),
+    ])
+    return {
+      starterContent: schemas.starterContent,
+      describeContent: content.describeContent,
+      buildDoc: parser.buildDoc,
+      serializeSection: writer.serializeSection,
+    }
+  } catch (err) {
+    throw new Error(
+      `Starter content needs @uniweb/schemas, @uniweb/semantic-parser and @uniweb/content-writer.\n` +
+        `  ${err.message}\n` +
+        `  Run your package manager's install in this workspace and try again.`,
+    )
+  }
+}
+
+/**
+ * Generate starter content for one section type and render it.
+ *
+ * @param {object} args
+ * @param {string} args.name        - the section type (PascalCase).
+ * @param {string} args.sectionDir  - the section's directory in the foundation.
+ * @param {string} [args.preset]    - a declared preset whose params become the frontmatter.
+ * @param {boolean} [args.json]     - emit the structure and the ProseMirror doc instead of markdown.
+ * @param {string} [args.write]     - write the markdown to this path instead of printing it.
+ * @returns {Promise<{markdown: string, result: object}>}
+ */
+export async function generateStarter({ name, sectionDir, preset, json, write }) {
+  const { starterContent, describeContent, buildDoc, serializeSection } = await loadPipeline()
+
+  const metaPath = join(sectionDir, 'meta.js')
+  const meta = existsSync(metaPath) ? await loadMeta(metaPath) : {}
+  const result = starterContent({ name, ...meta }, { preset })
+
+  const doc = buildDoc(result.content)
+  const markdown = doc ? serializeSection(result.params, doc) : ''
+
+  if (json) {
+    process.stdout.write(
+      JSON.stringify(
+        {
+          section: name,
+          family: result.family,
+          elementsInferred: result.elementsInferred,
+          unfilled: result.unfilled,
+          // What the component SAYS it expects, parsed — the same structure an
+          // editor renders a "what does this section want?" panel from. Carried
+          // here so the declaration and what was generated from it can be read
+          // side by side, without the app.
+          expects: describeContent({ name, ...meta }),
+          params: result.params,
+          content: result.content,
+          doc,
+        },
+        null,
+        2,
+      ) + '\n',
+    )
+    return { markdown, result }
+  }
+
+  if (write) {
+    await writeFile(write, markdown, 'utf-8')
+  }
+
+  return { markdown, result }
+}
+
+/**
+ * The human-facing report that follows generation.
+ *
+ * ⭐ It SAYS when the element list was ours. A component declaring no `content:`
+ * gets its family's canonical set, and a developer reading generated content
+ * they never specified should be told why — otherwise the natural conclusion is
+ * that the generator invented a declaration on their behalf.
+ */
+export function reportStarter(result, { write } = {}) {
+  const c = colors
+  const fam = result.family.id
+    ? `${c.cyan}${result.family.id}${c.reset} ${c.dim}(${result.family.source})${c.reset}`
+    : `${c.dim}no family — generic copy${c.reset}`
+
+  console.log('')
+  console.log(`  ${c.dim}family:${c.reset}   ${fam}`)
+  console.log(`  ${c.dim}slots:${c.reset}    ${Object.keys(result.content).join(', ') || '—'}`)
+
+  if (result.elementsInferred) {
+    console.log('')
+    console.log(
+      `  ${c.yellow}!${c.reset} This section declares no ${c.bright}content:${c.reset} — the elements above came from its family.`,
+    )
+    console.log(
+      `    ${c.dim}Declare what the component expects and the starter content follows it instead.${c.reset}`,
+    )
+  }
+
+  if (result.unfilled.length) {
+    console.log('')
+    console.log(`  ${c.yellow}!${c.reset} Not filled: ${result.unfilled.join(', ')}`)
+    console.log(
+      `    ${c.dim}\`background\` is frontmatter, not content. A video needs an address we cannot invent.${c.reset}`,
+    )
+    console.log(
+      `    ${c.dim}A \`data\` block needs a schema: a @/ ref resolves at build, and an empty {} declares no shape.${c.reset}`,
+    )
+  }
+
+  if (write) {
+    console.log('')
+    console.log(`  ${c.cyan}→${c.reset} written to ${write}`)
+  }
+  console.log('')
+}
+
+/**
+ * A `content:` declaration for a section being scaffolded, derived from the
+ * family the name resolves to. Written into the new `meta.js` so the scaffold is
+ * coherent: a declaration, a component, and content that fills it.
+ */
+export async function declarationFor(result) {
+  const LABELS = {
+    title: 'Headline',
+    pretitle: 'Small label above the headline',
+    subtitle: 'Secondary headline',
+    paragraphs: 'Body copy [1-2]',
+    links: 'Calls to action [0-2]',
+    lists: 'Bullet points [0-1]',
+    items: 'One per entry [3-6]',
+    images: 'Image [1]',
+    icons: 'Icon [1]',
+    videos: 'Video [1]',
+    snippets: 'Code sample [1]',
+    data: 'The data block the author writes',
+  }
+  // ⛔ The slot → declaration spelling comes from @uniweb/schemas, not from a
+  // copy here. `image` declares and `images` delivers; that mapping is the
+  // generator's, and a second copy rots the moment a row is added there.
+  const { declarationKey } = await import('@uniweb/schemas/starter')
+  const lines = Object.keys(result.content).map(
+    (slot) => `    ${declarationKey(slot)}: '${LABELS[slot] || slot}',`,
+  )
+  return lines.length ? `\n  content: {\n${lines.join('\n')}\n  },\n` : ''
+}

package/src/framework-index.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-09-16T12:39:33.539Z",
+  "generatedAt": "2026-09-16T20:57:12.370Z",
   "packages": {
     "@uniweb/api": {
       "version": "0.3.6",
@@ -10,7 +10,7 @@
       ]
     },
     "@uniweb/build": {
-      "version": "0.52.4",
+      "version": "0.52.6",
       "path": "framework/build",
       "deps": [
         "@uniweb/content-reader",
@@ -18,6 +18,7 @@
         "@uniweb/core",
         "@uniweb/projections",
         "@uniweb/runtime",
+        "@uniweb/runtime",
         "@uniweb/schemas",
         "@uniweb/semantic-parser",
         "@uniweb/theming"
@@ -54,7 +55,7 @@
       ]
     },
     "@uniweb/kit": {
-      "version": "0.19.2",
+      "version": "0.19.3",
       "path": "framework/kit",
       "deps": [
         "@uniweb/core",
@@ -95,7 +96,7 @@
       "deps": []
     },
     "@uniweb/schemas": {
-      "version": "0.3.0",
+      "version": "0.3.1",
       "path": "framework/schemas",
       "deps": []
     },
@@ -105,12 +106,12 @@
       "deps": []
     },
     "@uniweb/semantic-parser": {
-      "version": "1.4.0",
+      "version": "1.4.1",
       "path": "framework/semantic-parser",
       "deps": []
     },
     "@uniweb/templates": {
-      "version": "0.14.4",
+      "version": "0.14.5",
       "path": "framework/templates",
       "deps": []
     },

package/src/index.js

@@ -1498,22 +1498,82 @@ ${colors.bright}Options:${colors.reset}
   --platform <name>  (Deprecated alias for --host)
 `,
     add: `
-${colors.cyan}${colors.bright}uniweb add${colors.reset} ${colors.dim}— Add a foundation, site, or extension${colors.reset}
+${colors.cyan}${colors.bright}Uniweb Add${colors.reset}
 
-${colors.bright}Subcommands:${colors.reset}
-  add project [name]      Add a co-located foundation + site pair
-  add foundation [name]   Add a foundation (--from, --path, --project)
-  add site [name]         Add a site (--from, --foundation, --path, --project)
-  add extension <name>    Add an extension (--from, --site, --path)
-  add section <name>      Add a section type to a foundation (--foundation)
-  add ci                  Add a CI workflow so every push deploys (--host, --target)
+Add projects, foundations, sites, extensions, section types, or CI workflows to your workspace.
 
-${colors.bright}Common options:${colors.reset}
-  --from <template>       Source content from a template
-  --path <dir>            Override default folder location
-  --foundation <name>     Wire site/extension to this foundation (CI-friendly)
-  --site <name>           Wire extension to this site (CI-friendly)
-  --non-interactive       Fail with usage info instead of prompting
+${colors.bright}Usage:${colors.reset}
+  uniweb add project [name] [options]
+  uniweb add foundation [name] [options]
+  uniweb add site [name] [options]
+  uniweb add extension <name> [options]
+  uniweb add section <name> [options]
+  uniweb add ci [options]
+
+${colors.bright}Common Options:${colors.reset}
+  --from <template>  Apply content from a template after scaffolding
+  --path <dir>       Custom directory for the package
+  --non-interactive  Fail with usage info instead of prompting
+
+${colors.bright}Foundation Options:${colors.reset}
+  --project <name>   Group under a project directory (co-located layout)
+
+${colors.bright}Site Options:${colors.reset}
+  --foundation <n>   Foundation to wire to (prompted if multiple exist)
+  --project <name>   Group under a project directory (co-located layout)
+
+${colors.bright}Extension Options:${colors.reset}
+  --site <name>      Site to wire extension URL into
+
+${colors.bright}Section Options:${colors.reset}
+  --foundation <n>   Foundation to add section to (prompted if multiple exist)
+  --starter          Generate starter content from the section's \`content:\`
+                     declaration — what an author would begin editing. Works on
+                     a section that already exists (nothing is written), and on
+                     a new one (the scaffold gets a matching declaration)
+  --preset <name>    Frontmatter the starter content with this preset's params
+  --write <file>     Write the starter markdown to a file instead of printing it
+  --json             Emit the content structure and ProseMirror doc instead
+
+${colors.bright}CI Options:${colors.reset}
+  --host <name>          github-pages | cloudflare-pages | netlify | vercel
+                         (prompted when omitted)
+  --target <what>        site (default) | foundation
+                         'foundation' publishes built foundations at permanent
+                         versioned URLs — the free alternative to the catalog
+  --site <name>          Site the workflow builds (prompted if multiple exist)
+  --foundation <name>    With --target foundation: publish just this one
+  --domain <host>        Custom domain (GitHub Pages: writes CNAME, serves at root)
+  --project-name <name>  Name to register under on the host (default: the
+                         workspace name; Cloudflare Pages project, etc.)
+  --no-previews          Skip the per-PR preview workflow
+  --force                Overwrite an existing workflow file
+
+${colors.dim}Hosts that support PR previews: cloudflare-pages, netlify, vercel.
+GitHub Pages has no preview environment, so it scaffolds a deploy workflow only.${colors.reset}
+
+${colors.bright}Examples:${colors.reset}
+  uniweb add project docs                              # Create docs/foundation/ + docs/site/
+  uniweb add project docs --from academic              # Co-located pair + academic content
+  uniweb add foundation                                # Create ./foundation/ at root
+  uniweb add foundation ui                             # Create ./foundations/ui/
+  uniweb add site                                      # Create ./site/ at root
+  uniweb add site blog --foundation marketing          # Create ./sites/blog/ wired to marketing
+  uniweb add extension effects --site site             # 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
+  uniweb add section Pricing --starter                 # Scaffold Pricing + content that fills it
+  uniweb add section Hero --starter --preset split     # Frontmatter it with the 'split' preset
+  uniweb add section Hero --starter --json             # The structure + ProseMirror, for a script
+  uniweb add foundation --project docs                 # Create ./docs/foundation/ (co-located)
+  uniweb add site --project docs                       # Create ./docs/site/ (co-located)
+  uniweb add ci                                        # Pick a host, add a deploy workflow
+  uniweb add ci --host github-pages --site marketing   # Pick host + site explicitly
+  uniweb add ci --host netlify                         # Deploy + PR-preview workflows
+  uniweb add ci --host vercel --no-previews            # Deploy workflow only
+  uniweb add ci --domain mysite.com                    # Custom domain → writes CNAME + UNIWEB_BASE=/
+  uniweb add ci --target foundation                    # Publish foundations at versioned URLs
 `,
     export: `
 ${colors.cyan}${colors.bright}uniweb export${colors.reset} ${colors.dim}— Export a self-contained site for third-party hosting${colors.reset}
@@ -1888,7 +1948,7 @@ ${colors.bright}Add Subcommands:${colors.reset}
   add foundation [name]   Add a foundation (--from, --path, --project)
   add site [name]         Add a site (--from, --foundation, --path, --project)
   add extension <name>    Add an extension (--from, --site, --path)
-  add section <name>      Add a section type to a foundation (--foundation)
+  add section <name>      Add a section type to a foundation (--foundation, --starter)
   add ci                  Add a CI workflow so every push deploys (--host, --target)
 
 ${colors.bright}Global Options:${colors.reset}

package/src/utils/scaffold.js

@@ -122,7 +122,16 @@ export async function scaffoldSite(targetDir, context, options = {}) {
   registerVersions(getVersionsForTemplates())
 
   const templatePath = join(TEMPLATES_DIR, 'site')
-  await copyTemplateDirectory(templatePath, targetDir, context, {
+  // A ref is written as a YAML scalar, not pasted as text: a scoped ref
+  // (`@acme/base@1.0.0`, `@acme/marketing`) starts with `@`, which plain YAML
+  // reserves, so the file would not parse — and every reader that swallows
+  // the parse error then reports the site as having no `$uuid`. js-yaml quotes
+  // only when needed, so `src` stays `src`. Rendered with `{{{ }}}`, because
+  // Handlebars' HTML escaping would also rewrite a URL's `&` and `=`.
+  const siteContext = context.foundationRef
+    ? { ...context, foundationRefYaml: yaml.dump(context.foundationRef, { lineWidth: -1 }).trim() }
+    : context
+  await copyTemplateDirectory(templatePath, targetDir, siteContext, {
     onProgress: options.onProgress,
     onWarning: options.onWarning
   })

package/templates/site/site.yml.hbs

@@ -4,7 +4,7 @@
 name: {{projectName}}
 
 {{#if foundationRef}}
-foundation: {{foundationRef}}
+foundation: {{{foundationRefYaml}}}
 
 {{/if}}
 index: home