uniweb 0.56.4 → 0.56.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.56.4",
+  "version": "0.56.6",
   "description": "Create structured Vite + React sites with content/code separation",
   "type": "module",
   "bin": {
@@ -41,16 +41,17 @@
     "js-yaml": "^4.1.0",
     "prompts": "^2.4.2",
     "tar": "^7.0.0",
+    "@uniweb/content-writer": "^0.3.4",
     "@uniweb/core": "^0.29.4",
-    "@uniweb/kit": "^0.19.2",
-    "@uniweb/schemas": "^0.2.15",
-    "@uniweb/runtime": "^0.26.4",
-    "@uniweb/semantic-parser": "^1.4.0"
+    "@uniweb/kit": "^0.19.3",
+    "@uniweb/semantic-parser": "^1.4.1",
+    "@uniweb/schemas": "^0.3.1",
+    "@uniweb/runtime": "^0.26.4"
   },
   "peerDependencies": {
-    "@uniweb/build": "^0.52.3",
-    "@uniweb/content-reader": "^1.2.5",
-    "@uniweb/semantic-parser": "^1.4.0"
+    "@uniweb/semantic-parser": "^1.4.1",
+    "@uniweb/build": "^0.52.5",
+    "@uniweb/content-reader": "^1.2.5"
   },
   "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
     }
   }
 
@@ -1074,6 +1101,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 +1197,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 +1256,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 +1291,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('')
+      }
+    }
+  }
 }
 
 /**
@@ -1730,7 +1822,20 @@ function parseNodeMajor(engines) {
 }
 
 /**
- * Show help for the add command
+ * Show help for the add command.
+ *
+ * ⚠️ CURRENTLY UNREACHABLE, and the second copy of this text is the cost.
+ * `src/index.js` short-circuits ANY `--help` in the args before dispatching
+ * (its comment says why — `deploy --help` used to open a browser), and `add`
+ * has a dedicated block in that file's HELP map, so `printCommandHelp('add')`
+ * always wins and the `args[0] === '--help'` guard above never fires.
+ *
+ * ⛔ Which means a flag documented here and not there is documented nowhere.
+ * Measured 2026-09-16, when `--starter` was added to both: this copy's
+ * unescaped backticks around \`content:\` closed the template literal and broke
+ * the WHOLE module — every `uniweb add` subcommand failed with "missing ) after
+ * argument list" — and `uniweb add --help` printed correctly throughout,
+ * because it never reaches this function.
  */
 function showAddHelp() {
   log(`
@@ -1762,6 +1867,13 @@ ${colors.bright}Extension Options:${colors.reset}
 
 ${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
@@ -1790,6 +1902,10 @@ ${colors.bright}Examples:${colors.reset}
   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

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-16T04:55:41.770Z",
+  "generatedAt": "2026-09-16T20:35:26.755Z",
   "packages": {
     "@uniweb/api": {
       "version": "0.3.6",
@@ -10,7 +10,7 @@
       ]
     },
     "@uniweb/build": {
-      "version": "0.52.3",
+      "version": "0.52.5",
       "path": "framework/build",
       "deps": [
         "@uniweb/content-reader",
@@ -54,7 +54,7 @@
       ]
     },
     "@uniweb/kit": {
-      "version": "0.19.2",
+      "version": "0.19.3",
       "path": "framework/kit",
       "deps": [
         "@uniweb/core",
@@ -95,7 +95,7 @@
       "deps": []
     },
     "@uniweb/schemas": {
-      "version": "0.2.15",
+      "version": "0.3.1",
       "path": "framework/schemas",
       "deps": []
     },
@@ -105,12 +105,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

@@ -1505,7 +1505,7 @@ ${colors.bright}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}Common options:${colors.reset}
@@ -1514,6 +1514,15 @@ ${colors.bright}Common options:${colors.reset}
   --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}Starter content (add section):${colors.reset}
+  --starter               Generate starter content from the section's
+                          \`content:\` declaration — what an author would begin
+                          editing. Works on an existing section (writes nothing)
+                          and on a new one (the scaffold gets a declaration)
+  --preset <name>         Frontmatter it with this preset's params
+  --write <file>          Write the markdown to a file instead of printing
+  --json                  Emit the structure + ProseMirror doc instead
 `,
     export: `
 ${colors.cyan}${colors.bright}uniweb export${colors.reset} ${colors.dim}— Export a self-contained site for third-party hosting${colors.reset}
@@ -1888,7 +1897,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