uniweb 0.1.6 → 0.2.0

package/README.md

@@ -1,24 +1,116 @@
 # uniweb
 
-CLI for the Uniweb Component Web Platform.
+Create a well-structured Vite + React site with content/code separation, file-based routing, localization, and structured content—out of the box. The architecture scales to dynamic content management and collaborative visual editing when you need it.
 
 ## Quick Start
 
-Create a new Uniweb project with a starter template:
-
-```bash
-npx uniweb@latest create my-project --template workspace
-```
-
-This scaffolds a Vite project with everything wired—routing, state, and build pipeline ready. You get a site and a Foundation in a monorepo, pre-configured to work together.
+Create a new Uniweb project:
 
 ```bash
+npx uniweb@latest create my-project
 cd my-project
 pnpm install
 pnpm dev
 ```
 
-No heavy framework to learn. Foundations are React component libraries built with Vite and styled with Tailwind. Sites are Vite apps that load content from markdown files. The CLI handles the wiring.
+You get a workspace with two packages:
+
+- **`site/`** — Content, pages, entry point
+- **`foundation/`** — Your React components
+
+Content authors work in markdown. Component authors work in React. Neither can break the other's work, and component updates flow to every site using them.
+
+## What You Get
+
+```
+my-project/
+├── site/                     # Content + configuration
+│   ├── pages/                # File-based routing
+│   │   └── home/
+│   │       ├── page.yml      # Page metadata
+│   │       └── 1-hero.md     # Section content
+│   ├── locales/              # i18n (mirrors pages/)
+│   │   └── es/
+│   └── public/               # Static assets
+│
+└── foundation/               # Your components
+    └── src/
+        └── components/
+            └── Hero/
+                └── index.jsx
+```
+
+**Pages are folders.** Create `pages/about/` with a markdown file inside → visit `/about`. That's the whole routing model.
+
+### Content as Markdown
+
+```markdown
+---
+component: Hero
+theme: dark
+---
+
+# Welcome
+
+Build something great.
+
+[Get Started](#)
+```
+
+Frontmatter specifies the component and configuration. The body contains the actual content—headings, paragraphs, links, images—which gets semantically parsed into structured data your component receives.
+
+### Beyond Markdown
+
+For content that doesn't fit markdown patterns—products, team members, events—use JSON blocks with schema tags:
+
+````markdown
+```json #team-member
+{
+  "name": "Sarah Chen",
+  "role": "Lead Architect"
+}
+```
+````
+
+Components receive validated, localized data. Natural content stays in markdown; structured data goes in JSON blocks.
+
+### Components as React
+
+```jsx
+export function Hero({ content, params }) {
+  const { title } = content.main.header;
+  const { paragraphs, links } = content.main.body;
+  const { theme = 'light' } = params;
+
+  return (
+    <section className={`py-20 text-center ${theme === 'dark' ? 'bg-gray-900 text-white' : ''}`}>
+      <h1 className="text-4xl font-bold">{title}</h1>
+      <p className="text-xl text-gray-600">{paragraphs[0]}</p>
+      {links[0] && (
+        <a href={links[0].url} className="mt-8 px-6 py-3 bg-blue-600 text-white rounded inline-block">
+          {links[0].text}
+        </a>
+      )}
+    </section>
+  );
+}
+```
+
+Standard React. Standard Tailwind. The `{ content, params }` interface is only for *exposed* components—the ones content creators select in markdown frontmatter. Internal components (the majority of your codebase) use regular React props.
+
+No framework to learn. Foundations are purpose-built component systems designed for a specific domain (marketing, documentation, learning, etc.). Sites are Vite apps that load content from markdown files. The CLI handles the wiring.
+
+## The Bigger Picture
+
+The structure you start with scales without rewrites:
+
+1. **Single project** — One site, one component library. Most projects stay here.
+2. **Multi-site** — One foundation powers multiple sites. Release it once, updates propagate automatically.
+3. **Full platform** — [uniweb.app](https://uniweb.app) adds visual editing, live content management, and team collaboration. Your foundation plugs in and its components become native to the editor.
+
+Start with local markdown files deployed anywhere. Connect to [uniweb.app](https://uniweb.app) when you're ready for dynamic content and team collaboration.
+
+---
 
 ## Installation
 
@@ -42,9 +134,9 @@ uniweb create [project-name] [options]
 
 **Options:**
 
-| Option              | Description                                            |
-| ------------------- | ------------------------------------------------------ |
-| `--template <type>` | Project template: `workspace`, `site`, or `foundation` |
+| Option              | Description                           |
+| ------------------- | ------------------------------------- |
+| `--template <type>` | Project template: `single` or `multi` |
 
 **Examples:**
 
@@ -52,17 +144,14 @@ uniweb create [project-name] [options]
 # Interactive prompts
 uniweb create
 
-# Create with specific name
+# Create with specific name (defaults to single template)
 uniweb create my-project
 
-# Full workspace (site + foundation)
-uniweb create my-workspace --template workspace
-
-# Standalone foundation
-uniweb create my-foundation --template foundation
+# Single project with site + foundation
+uniweb create my-project --template single
 
-# Standalone site
-uniweb create my-site --template site
+# Multi-site/foundation monorepo
+uniweb create my-workspace --template multi
 ```
 
 ### `build`
@@ -75,9 +164,10 @@ uniweb build [options]
 
 **Options:**
 
-| Option            | Description                                                           |
-| ----------------- | --------------------------------------------------------------------- |
-| `--target <type>` | Build target: `foundation` or `site` (auto-detected if not specified) |
+| Option              | Description                                                           |
+| ------------------- | --------------------------------------------------------------------- |
+| `--target <type>`   | Build target: `foundation` or `site` (auto-detected if not specified) |
+| `--platform <name>` | Deployment platform (e.g., `vercel`) for platform-specific output     |
 
 **Examples:**
 
@@ -90,56 +180,112 @@ uniweb build --target foundation
 
 # Explicitly build as site
 uniweb build --target site
+
+# Build for Vercel deployment
+uniweb build --platform vercel
 ```
 
 ## Project Templates
 
-### Workspace
+### Single (Default)
 
-A monorepo with both a site and foundation for co-development.
+A minimal workspace with a site and foundation as sibling packages. This is the recommended starting point.
 
 ```
-my-workspace/
-├── package.json
-├── pnpm-workspace.yaml
-└── packages/
-    ├── site/           # Website using the foundation
-    └── foundation/     # Component library
+my-project/
+├── package.json              # Workspace root (includes workspaces field for npm)
+├── pnpm-workspace.yaml       # Pre-configured for evolution (see below)
+│
+├── site/                     # Site package (content + entry)
+│   ├── package.json
+│   ├── vite.config.js
+│   ├── index.html
+│   ├── site.yml
+│   ├── src/
+│   │   └── main.jsx          # Thin entry point
+│   ├── pages/                # Content structure
+│   │   └── home/
+│   │       ├── page.yml
+│   │       └── 1-hero.md
+│   ├── locales/              # i18n (mirrors pages/)
+│   │   └── es/
+│   │       └── home/
+│   └── public/               # Static assets
+│
+└── foundation/               # Foundation package (components)
+    ├── package.json
+    ├── vite.config.js
+    ├── src/
+    │   ├── index.js          # Component registry
+    │   ├── styles.css        # Tailwind
+    │   ├── meta.js           # Foundation metadata
+    │   └── components/
+    │       └── Hero/
+    │           ├── index.jsx
+    │           └── meta.js
+    └── ...
 ```
 
-### Site
+**Key characteristics:**
 
-A standalone site using an existing foundation.
+- **Convention-compliant** — Each package has its own `src/`
+- **Clear dep boundaries** — Component libs → `foundation/package.json`, runtime → `site/package.json`
+- **Zero extraction** — `foundation/` is already a complete, publishable package
+- **Scales naturally** — Rename to `sites/marketing/` and `foundations/marketing/` when needed
+
+### Multi
+
+A monorepo for multi-site or multi-foundation development.
 
 ```
-my-site/
-├── package.json
-├── vite.config.js
-├── site.yml
-├── src/
-│   └── main.jsx
-└── pages/
-    └── home/
-        ├── page.yml
-        └── 1-hero.md
+my-workspace/
+├── package.json              # Workspace root (includes workspaces field for npm)
+├── pnpm-workspace.yaml       # Same config as site template
+│
+├── sites/
+│   ├── marketing/            # Main marketing site
+│   │   ├── package.json
+│   │   ├── site.yml
+│   │   ├── src/
+│   │   ├── pages/
+│   │   └── ...
+│   └── docs/                 # Documentation site
+│
+└── foundations/
+    ├── marketing/            # Marketing foundation
+    │   ├── package.json
+    │   ├── src/components/
+    │   └── ...
+    └── documentation/        # Documentation foundation
 ```
 
-### Foundation
+Use this when you need:
 
-A standalone component library.
+- Multiple sites sharing foundations
+- Multiple foundations for different purposes
+- A testing site for foundation development
 
-```
-my-foundation/
-├── package.json
-├── vite.config.js
-├── tailwind.config.js
-└── src/
-    ├── meta.js          # Foundation metadata
-    ├── styles.css
-    └── components/
-        └── Hero/
-            ├── index.jsx
-            └── meta.js
+## Dependency Management
+
+Each package manages its own dependencies:
+
+**`site/package.json`:**
+
+- `@uniweb/runtime`
+- `@my-project/foundation` (workspace link)
+- Vite, Tailwind (dev)
+
+**`foundation/package.json`:**
+
+- Component libraries (carousel, icons, etc.)
+- React as peer dependency
+
+```bash
+# Add component dependency
+cd foundation && pnpm add embla-carousel
+
+# Site references foundation via workspace
+# No path gymnastics needed
 ```
 
 ## Foundation Build Process
@@ -165,10 +311,96 @@ dist/
         └── [preset].webp
 ```
 
+## Workspace Configuration
+
+Both templates use the same unified workspace configuration:
+
+```yaml
+# pnpm-workspace.yaml
+packages:
+  - "site"
+  - "foundation"
+  - "sites/*"
+  - "foundations/*"
+```
+
+```json
+// package.json (workspaces field for npm compatibility)
+{
+  "workspaces": ["site", "foundation", "sites/*", "foundations/*"]
+}
+```
+
+This means **no config changes when evolving your project**.
+
+## Evolving Your Project
+
+The workspace is pre-configured for growth. Choose your path:
+
+**Add alongside existing structure:**
+
+```bash
+# Keep site/ and foundation/, add more in sites/ and foundations/
+mkdir -p sites/docs
+mkdir -p foundations/documentation
+```
+
+**Or migrate to multi-site structure:**
+
+```bash
+# Move and rename by purpose
+mv site sites/marketing
+mv foundation foundations/marketing
+
+# Update package names and workspace dependencies in package.json files
+```
+
+Both patterns work simultaneously—evolve gradually as needed.
+
+## Releasing a Foundation
+
+Publish your foundation to [uniweb.app](https://uniweb.app) to make it available for your sites:
+
+```bash
+uniweb login          # First time only
+uniweb build
+uniweb publish        # Publishes the foundation in the current directory
+```
+
+Each release creates a new version. Sites link to foundations at runtime and control their own update strategy—automatic, minor-only, patch-only, or pinned to a specific version. You own your foundations and license them to sites—yours or your clients'.
+
+You can also publish to npm:
+
+```bash
+npm publish
+```
+
+## FAQ
+
+**How is this different from MDX?**
+
+MDX blends markdown and JSX—content authors write code. Uniweb keeps them separate: content stays in markdown, components stay in React. Content authors can't break components, and component updates don't require content changes.
+
+**How is this different from Astro?**
+
+Astro is a static site generator. Uniweb is a content architecture that works with any deployment (static, SSR, or platform-managed). The Foundation model means components are reusable across sites and ready for visual editing.
+
+**Do I need uniweb.app?**
+
+No. Local markdown files work great for developer-managed sites. The platform adds dynamic content, visual editing, and team collaboration when you need it.
+
+**Is this SEO-friendly?**
+
+Yes. Content is pre-embedded in the initial HTML—no fetch waterfalls, no layout shifts, instant interaction. Meta tags are generated per page for proper social sharing previews. SSG and SSR are also supported.
+
+**What about dynamic routes?**
+
+Pages can define data sources that auto-generate subroutes. A `/blog` page can have an index (listing) and a `[slug]` template that renders each post. No manual folders for every entry.
+
 ## Related Packages
 
-- [`@uniweb/build`](https://github.com/uniweb/build) - Foundation build tooling
-- [`@uniweb/runtime`](https://github.com/uniweb/runtime) - Runtime loader for sites
+- [`@uniweb/build`](https://github.com/uniweb/build) — Foundation build tooling
+- [`@uniweb/runtime`](https://github.com/uniweb/runtime) — Runtime loader for sites
 
 ## License
 

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "uniweb",
-  "version": "0.1.6",
-  "description": "CLI for the Uniweb Component Web Platform",
+  "version": "0.2.0",
+  "description": "Create structured Vite + React sites with content/code separation",
   "type": "module",
   "bin": {
-    "uniweb": "./src/index.js"
+    "uniweb": "src/index.js"
   },
   "files": [
     "src"

package/src/index.js

@@ -7,9 +7,8 @@
  *
  * Usage:
  *   npx uniweb create [project-name]
- *   npx uniweb create --template site
- *   npx uniweb create --template foundation
- *   npx uniweb create --template workspace
+ *   npx uniweb create --template single      # site/ + foundation/ (default)
+ *   npx uniweb create --template multi       # sites/* + foundations/*
  *   npx uniweb build
  *   npx uniweb build --target foundation
  */
@@ -51,17 +50,13 @@ function title(message) {
 
 // Template definitions
 const templates = {
-  workspace: {
-    name: 'Site + Foundation Workspace',
-    description: 'Monorepo with a site and foundation for co-development',
+  single: {
+    name: 'Single Project',
+    description: 'One site + one foundation in site/ and foundation/ (recommended)',
   },
-  site: {
-    name: 'Site Only',
-    description: 'A site that uses an existing foundation',
-  },
-  foundation: {
-    name: 'Foundation Only',
-    description: 'A standalone foundation package',
+  multi: {
+    name: 'Multi-Site Project',
+    description: 'Multiple sites and foundations in sites/* and foundations/*',
   },
 }
 
@@ -126,19 +121,14 @@ async function main() {
       message: 'What would you like to create?',
       choices: [
         {
-          title: templates.workspace.name,
-          description: templates.workspace.description,
-          value: 'workspace',
-        },
-        {
-          title: templates.site.name,
-          description: templates.site.description,
-          value: 'site',
+          title: templates.single.name,
+          description: templates.single.description,
+          value: 'single',
         },
         {
-          title: templates.foundation.name,
-          description: templates.foundation.description,
-          value: 'foundation',
+          title: templates.multi.name,
+          description: templates.multi.description,
+          value: 'multi',
         },
       ],
     },
@@ -169,14 +159,11 @@ async function main() {
 
   // Generate project based on template
   switch (templateType) {
-    case 'workspace':
-      await createWorkspace(projectDir, projectName)
-      break
-    case 'site':
-      await createSite(projectDir, projectName)
+    case 'single':
+      await createSingleProject(projectDir, projectName)
       break
-    case 'foundation':
-      await createFoundation(projectDir, projectName)
+    case 'multi':
+      await createMultiProject(projectDir, projectName)
       break
   }
 
@@ -186,15 +173,7 @@ async function main() {
   log(`Next steps:\n`)
   log(`  ${colors.cyan}cd ${projectName}${colors.reset}`)
   log(`  ${colors.cyan}pnpm install${colors.reset}`)
-
-  if (templateType === 'workspace') {
-    log(`  ${colors.cyan}pnpm dev${colors.reset}`)
-  } else if (templateType === 'site') {
-    log(`  ${colors.cyan}pnpm dev${colors.reset}`)
-  } else {
-    log(`  ${colors.cyan}pnpm build${colors.reset}`)
-  }
-
+  log(`  ${colors.cyan}pnpm dev${colors.reset}`)
   log('')
 }
 
@@ -210,50 +189,62 @@ ${colors.bright}Commands:${colors.reset}
   build              Build the current project
 
 ${colors.bright}Create Options:${colors.reset}
-  --template <type>  Project template (workspace, site, foundation)
+  --template <type>  Project template (single, multi)
 
 ${colors.bright}Build Options:${colors.reset}
   --target <type>    Build target (foundation, site) - auto-detected if not specified
+  --platform <name>  Deployment platform (e.g., vercel) for platform-specific output
 
 ${colors.bright}Examples:${colors.reset}
   npx uniweb create my-project
-  npx uniweb create my-site --template site
-  npx uniweb create my-foundation --template foundation
+  npx uniweb create my-project --template single
+  npx uniweb create my-workspace --template multi
   npx uniweb build
   npx uniweb build --target foundation
 
 ${colors.bright}Templates:${colors.reset}
-  workspace    Site + Foundation monorepo for co-development
-  site         Standalone site using an existing foundation
-  foundation   Standalone foundation package
+  single       One site + one foundation in site/ and foundation/ (default)
+  multi        Multiple sites and foundations in sites/* and foundations/*
 `)
 }
 
 // Template generators
-async function createWorkspace(projectDir, projectName) {
+
+/**
+ * Creates the common project base: package.json, pnpm-workspace.yaml, .gitignore
+ * Both single and multi templates share the same workspace configuration.
+ */
+function createProjectBase(projectDir, projectName, defaultFilter) {
   mkdirSync(projectDir, { recursive: true })
 
-  // Root package.json
+  // Root package.json (workspaces field for npm compatibility)
   writeJSON(join(projectDir, 'package.json'), {
     name: projectName,
     version: '0.1.0',
     private: true,
     type: 'module',
-    workspaces: ['packages/*'],
     scripts: {
-      dev: 'pnpm --filter site dev',
-      'dev:runtime': 'VITE_FOUNDATION_MODE=runtime pnpm --filter site dev',
-      'build:foundation': 'pnpm --filter foundation build',
-      build: 'pnpm build:foundation && pnpm --filter site build',
+      dev: `pnpm --filter ${defaultFilter} dev`,
+      'dev:runtime': `VITE_FOUNDATION_MODE=runtime pnpm --filter ${defaultFilter} dev`,
+      build: 'pnpm -r build',
     },
+    workspaces: [
+      'site',
+      'foundation',
+      'sites/*',
+      'foundations/*',
+    ],
     pnpm: {
       onlyBuiltDependencies: ['esbuild', 'sharp'],
     },
   })
 
-  // pnpm-workspace.yaml
+  // pnpm-workspace.yaml (all patterns for seamless evolution)
   writeFile(join(projectDir, 'pnpm-workspace.yaml'), `packages:
-  - 'packages/*'
+  - 'site'
+  - 'foundation'
+  - 'sites/*'
+  - 'foundations/*'
 `)
 
   // .gitignore
@@ -262,11 +253,19 @@ dist
 .DS_Store
 *.local
 `)
+}
+
+/**
+ * Creates a single project with site/ and foundation/ as sibling packages.
+ * This is the default template for new projects.
+ */
+async function createSingleProject(projectDir, projectName) {
+  createProjectBase(projectDir, projectName, 'site')
 
   // README.md
   writeFile(join(projectDir, 'README.md'), `# ${projectName}
 
-A Uniweb workspace with a site and foundation for co-development.
+Structured Vite + React, ready to go.
 
 ## Quick Start
 
@@ -281,16 +280,21 @@ Open [http://localhost:3000](http://localhost:3000) to see your site.
 
 \`\`\`
 ${projectName}/
-├── packages/
-│   ├── site/           # Your website
-│   │   ├── pages/      # Content pages (markdown + YAML)
-│   │   ├── src/        # Site entry point
-│   │   └── vite.config.js
-│   └── foundation/     # Your component library
-│       └── src/
-│           ├── components/   # React components
-│           ├── meta.js       # Foundation metadata
-│           └── styles.css    # Tailwind styles
+├── site/                     # Content + configuration
+│   ├── pages/                # File-based routing
+│   │   └── home/
+│   │       ├── page.yml      # Page metadata
+│   │       └── 1-hero.md     # Section content
+│   ├── locales/              # i18n (mirrors pages/)
+│   ├── src/                  # Site entry point
+│   └── public/               # Static assets
+│
+├── foundation/               # Your components
+│   └── src/
+│       ├── components/       # React components
+│       ├── meta.js           # Foundation metadata
+│       └── styles.css        # Tailwind styles
+│
 ├── package.json
 └── pnpm-workspace.yaml
 \`\`\`
@@ -303,8 +307,8 @@ ${projectName}/
 pnpm dev
 \`\`\`
 
-Edit components in \`packages/foundation/src/components/\` and see changes instantly via HMR.
-Edit content in \`packages/site/pages/\` to add or modify pages.
+Edit components in \`foundation/src/components/\` and see changes instantly via HMR.
+Edit content in \`site/pages/\` to add or modify pages.
 
 ### Runtime Loading Mode
 
@@ -318,24 +322,23 @@ Use this to debug issues that only appear in production.
 ## Building for Production
 
 \`\`\`bash
-# Build both foundation and site
 pnpm build
 \`\`\`
 
-Output:
-- \`packages/foundation/dist/\` — Bundled foundation (JS + CSS + schema)
-- \`packages/site/dist/\` — Production-ready site
+**Output:**
+- \`foundation/dist/\` — Bundled components, CSS, and schema.json
+- \`site/dist/\` — Production-ready static site
 
 ## Adding Components
 
-1. Create a new folder in \`packages/foundation/src/components/YourComponent/\`
+1. Create a new folder in \`foundation/src/components/YourComponent/\`
 2. Add \`index.jsx\` with your React component
 3. Add \`meta.js\` describing the component's content slots and options
-4. Export from \`packages/foundation/src/index.js\`
+4. Export from \`foundation/src/index.js\`
 
 ## Adding Pages
 
-1. Create a folder in \`packages/site/pages/your-page/\`
+1. Create a folder in \`site/pages/your-page/\`
 2. Add \`page.yml\` with page metadata
 3. Add markdown files (\`1-section.md\`, \`2-section.md\`, etc.) for each section
 
@@ -344,24 +347,48 @@ Each markdown file specifies which component to use:
 \`\`\`markdown
 ---
 component: Hero
-title: Your Title
-subtitle: Your subtitle
 ---
 
-Optional body content here.
+# Your Title
+
+Your subtitle or description here.
+
+[Get Started](#)
 \`\`\`
 
-## Configuration
+## Scaling Up
 
-Each site has a \`site.yml\` that configures which foundation it uses:
+The workspace is pre-configured for growth—no config changes needed.
 
-\`\`\`yaml
-name: site
-defaultLanguage: en
-foundation: foundation    # References packages/foundation
+**Add a second site** (keep existing structure):
+
+\`\`\`bash
+mkdir -p sites/docs
+# Create your docs site in sites/docs/
 \`\`\`
 
-To add multiple sites or foundations, create new packages and update each site's \`site.yml\`.
+**Or migrate to multi-site structure**:
+
+\`\`\`bash
+# Move and rename by purpose
+mv site sites/marketing
+mv foundation foundations/marketing
+
+# Update package names in package.json files
+# Update dependencies to reference new names
+\`\`\`
+
+Both patterns work simultaneously—evolve gradually as needed.
+
+## Publishing Your Foundation
+
+Your \`foundation/\` is already a complete package:
+
+\`\`\`bash
+cd foundation
+npx uniweb build
+npm publish
+\`\`\`
 
 ## What is Uniweb?
 
@@ -372,22 +399,145 @@ Sites provide content that flows through Foundations.
 Learn more:
 - [Uniweb on GitHub](https://github.com/uniweb)
 - [CLI Documentation](https://github.com/uniweb/cli)
-- [uniweb.app](https://uniweb.app) — Full publishing platform
+- [uniweb.app](https://uniweb.app) — Visual editing platform
 
 `)
 
   // Create site package
-  await createSite(join(projectDir, 'packages/site'), 'site', true)
+  await createSite(join(projectDir, 'site'), 'site', true)
 
   // Create foundation package
-  await createFoundation(join(projectDir, 'packages/foundation'), 'foundation', true)
+  await createFoundation(join(projectDir, 'foundation'), 'foundation', true)
 
   // Update site to reference workspace foundation
-  const sitePackageJson = join(projectDir, 'packages/site/package.json')
+  const sitePackageJson = join(projectDir, 'site/package.json')
   const sitePkg = JSON.parse(readFile(sitePackageJson))
   sitePkg.dependencies['foundation'] = 'workspace:*'
   writeJSON(sitePackageJson, sitePkg)
 
+  success(`Created project: ${projectName}`)
+}
+
+/**
+ * Creates a multi-site/foundation workspace with sites/ and foundations/ directories.
+ * Used for larger projects with multiple sites sharing foundations.
+ */
+async function createMultiProject(projectDir, projectName) {
+  createProjectBase(projectDir, projectName, 'marketing')
+
+  // README.md
+  writeFile(join(projectDir, 'README.md'), `# ${projectName}
+
+A Uniweb workspace for multiple sites and foundations.
+
+## Quick Start
+
+\`\`\`bash
+pnpm install
+pnpm dev
+\`\`\`
+
+Open [http://localhost:3000](http://localhost:3000) to see the marketing site.
+
+## Project Structure
+
+\`\`\`
+${projectName}/
+├── sites/
+│   └── marketing/            # Main marketing site
+│       ├── pages/            # Content pages
+│       ├── locales/          # i18n
+│       └── src/
+│
+├── foundations/
+│   └── marketing/            # Marketing foundation
+│       └── src/
+│           ├── components/   # React components
+│           └── styles.css    # Tailwind styles
+│
+├── package.json
+└── pnpm-workspace.yaml
+\`\`\`
+
+## Development
+
+\`\`\`bash
+# Run the marketing site (default)
+pnpm dev
+
+# Run a specific site
+pnpm --filter docs dev
+
+# Runtime loading mode (tests production behavior)
+pnpm dev:runtime
+\`\`\`
+
+## Adding More Sites
+
+Create a new site in \`sites/\`:
+
+\`\`\`bash
+mkdir -p sites/docs
+# Copy structure from sites/marketing or create manually
+\`\`\`
+
+Update \`sites/docs/site.yml\` to specify which foundation:
+
+\`\`\`yaml
+name: docs
+defaultLanguage: en
+foundation: documentation    # Or marketing, or any foundation
+\`\`\`
+
+## Adding More Foundations
+
+Create a new foundation in \`foundations/\`:
+
+\`\`\`bash
+mkdir -p foundations/documentation
+# Build components for documentation use case
+\`\`\`
+
+Name foundations by purpose: marketing, documentation, learning, etc.
+
+## Building for Production
+
+\`\`\`bash
+# Build everything
+pnpm build
+
+# Build specific packages
+pnpm --filter marketing build
+pnpm --filter foundations/marketing build
+\`\`\`
+
+## Learn More
+
+- [Uniweb on GitHub](https://github.com/uniweb)
+- [uniweb.app](https://uniweb.app) — Visual editing platform
+
+`)
+
+  // Create first site in sites/marketing
+  await createSite(join(projectDir, 'sites/marketing'), 'marketing', true)
+
+  // Create first foundation in foundations/marketing
+  await createFoundation(join(projectDir, 'foundations/marketing'), 'marketing', true)
+
+  // Update site to reference workspace foundation
+  const sitePackageJson = join(projectDir, 'sites/marketing/package.json')
+  const sitePkg = JSON.parse(readFile(sitePackageJson))
+  sitePkg.dependencies['marketing'] = 'workspace:*'
+  writeJSON(sitePackageJson, sitePkg)
+
+  // Update site.yml to reference the marketing foundation
+  writeFile(join(projectDir, 'sites/marketing/site.yml'), `name: marketing
+defaultLanguage: en
+
+# Foundation to use for this site
+foundation: marketing
+`)
+
   success(`Created workspace: ${projectName}`)
 }
 
@@ -569,13 +719,13 @@ order: 1
   // pages/home/1-hero.md
   writeFile(join(projectDir, 'pages/home/1-hero.md'), `---
 component: Hero
-title: Welcome to ${projectName}
-subtitle: Built with Uniweb and Vite
-ctaText: Get Started
-ctaUrl: "#"
 ---
 
-Your content goes here.
+# Welcome to ${projectName}
+
+Built with Uniweb and Vite.
+
+[Get Started](#)
 `)
 
   // README.md (only for standalone site, not workspace)
@@ -623,19 +773,22 @@ order: 2
 \`\`\`markdown
 ---
 component: Hero
-title: Section Title
-subtitle: Section subtitle
+theme: dark
 ---
 
-Optional markdown content here.
+# Section Title
+
+Section description here.
+
+[Call to Action](#)
 \`\`\`
 
 ## How It Works
 
 - Each folder in \`pages/\` becomes a route (\`/home\`, \`/about\`, etc.)
 - Section files are numbered to control order (\`1-*.md\`, \`2-*.md\`)
-- The \`component\` field specifies which Foundation component renders the section
-- Other frontmatter fields become the component's content
+- Frontmatter specifies the component and configuration parameters
+- Content in the markdown body is semantically parsed into structured data
 
 ## Configuration
 
@@ -847,22 +1000,36 @@ export { default } from './index.js'
   // src/components/Hero/index.jsx
   writeFile(join(projectDir, 'src/components/Hero/index.jsx'), `import React from 'react'
 
-export function Hero({ content }) {
-  const { title, subtitle, ctaText, ctaUrl } = content
+export function Hero({ content, params }) {
+  // Extract from semantic parser structure
+  const { title } = content.main?.header || {}
+  const { paragraphs = [], links = [] } = content.main?.body || {}
+  const { theme = 'light' } = params || {}
+
+  const isDark = theme === 'dark'
+  const cta = links[0]
 
   return (
-    <section className="py-20 px-6 bg-gradient-to-br from-primary to-blue-700 text-white">
+    <section className={\`py-20 px-6 \${isDark ? 'bg-gradient-to-br from-primary to-blue-700 text-white' : 'bg-gray-50'}\`}>
       <div className="max-w-4xl mx-auto text-center">
-        <h1 className="text-4xl md:text-5xl font-bold mb-6">{title}</h1>
-        {subtitle && (
-          <p className="text-lg text-blue-100 mb-8">{subtitle}</p>
+        {title && (
+          <h1 className="text-4xl md:text-5xl font-bold mb-6">{title}</h1>
+        )}
+        {paragraphs[0] && (
+          <p className={\`text-lg mb-8 \${isDark ? 'text-blue-100' : 'text-gray-600'}\`}>
+            {paragraphs[0]}
+          </p>
         )}
-        {ctaText && ctaUrl && (
+        {cta && (
           <a
-            href={ctaUrl}
-            className="inline-block px-6 py-3 bg-white text-primary font-semibold rounded-lg hover:bg-blue-50 transition-colors"
+            href={cta.url}
+            className={\`inline-block px-6 py-3 font-semibold rounded-lg transition-colors \${
+              isDark
+                ? 'bg-white text-primary hover:bg-blue-50'
+                : 'bg-primary text-white hover:bg-blue-700'
+            }\`}
           >
-            {ctaText}
+            {cta.text}
           </a>
         )}
       </div>
@@ -876,26 +1043,45 @@ export default Hero
   // src/components/Hero/meta.js
   writeFile(join(projectDir, 'src/components/Hero/meta.js'), `/**
  * Hero Component Metadata
+ *
+ * Content comes from the markdown body (parsed semantically):
+ * - H1 → title (content.main.header.title)
+ * - Paragraphs → description (content.main.body.paragraphs)
+ * - Links → CTA buttons (content.main.body.links)
  */
 export default {
   title: 'Hero Banner',
-  description: 'A prominent header section with headline, subtitle, and call-to-action',
+  description: 'A prominent header section with headline, description, and call-to-action',
   category: 'Headers',
 
+  // Content structure (informational - describes what the semantic parser provides)
   elements: {
     title: {
       label: 'Headline',
+      description: 'From H1 in markdown',
       required: true,
     },
-    subtitle: {
-      label: 'Subtitle',
+    paragraphs: {
+      label: 'Description',
+      description: 'From paragraphs in markdown',
     },
     links: {
       label: 'Call to Action',
+      description: 'From links in markdown',
     },
   },
 
+  // Configuration parameters (set in frontmatter)
   properties: {
+    theme: {
+      type: 'select',
+      label: 'Theme',
+      options: [
+        { value: 'light', label: 'Light' },
+        { value: 'dark', label: 'Dark' },
+      ],
+      default: 'light',
+    },
     alignment: {
       type: 'select',
       label: 'Text Alignment',