uniweb 0.2.40 → 0.2.42

package/README.md

@@ -1,24 +1,42 @@
 # uniweb
 
-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.
+A component content architecture for React. Build sites where content authors and component developers can't break each other's work—and scale from local files to visual editing without rewrites.
 
-## Quick Start
+Create well-structured Vite + React projects with file-based routing, localization, and clean content/code separation out of the box.
 
-Create a new Uniweb project:
+## Quick Start
 
 ```bash
-npx uniweb@latest create my-project
-cd my-project
+npx uniweb@latest create my-site --template marketing
+cd my-site
 pnpm install
 pnpm dev
 ```
 
-You get a workspace with two packages:
+The `marketing` template includes real components (Hero, Features, Pricing, Testimonials, FAQ, and more) with sample content—a working site you can explore and modify.
+
+**Other templates:**
+
+```bash
+# Multilingual business site (English, Spanish, French)
+npx uniweb@latest create my-site --template international
+
+# Academic site (researcher portfolios, lab pages)
+npx uniweb@latest create my-site --template academic
+
+# Documentation site
+npx uniweb@latest create my-site --template docs
+
+# Minimal starter (build from scratch)
+npx uniweb@latest create my-site
+```
+
+Every project is a workspace with two packages:
 
 - **`site/`** — Content, pages, entry point
-- **`foundation/`** — Your React components
+- **`foundation/`** — 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.
+Content authors work in markdown. Component authors work in React. Neither can break the other's work.
 
 ## What You Get
 
@@ -30,8 +48,6 @@ my-project/
 │   │       ├── page.yml      # Page metadata
 │   │       └── 1-hero.md     # Section content
 │   ├── locales/              # i18n (hash-based translations)
-│   │   ├── manifest.json     # Auto-extracted strings
-│   │   └── es.json           # Spanish translations
 │   ├── main.js               # Entry point (~6 lines)
 │   ├── vite.config.js        # 3-line config
 │   └── public/               # Static assets
@@ -84,13 +100,13 @@ Components receive validated, localized data. Natural content stays in markdown;
 
 ```jsx
 export function Hero({ content, params }) {
-  const { title } = content.main.header;
-  const { paragraphs, links } = content.main.body;
-  const { theme = "light" } = 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" : ""}`}
+      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>
@@ -103,23 +119,45 @@ export function Hero({ content, params }) {
         </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.
+Standard React. Standard Tailwind. The `{ content, params }` interface is only for _exposed_ components—the ones content creators select in markdown frontmatter. Internal components 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.
+## Foundations Are Portable
+
+The `foundation/` folder ships with your project as a convenience, but a foundation is a self-contained artifact with no dependency on any specific site. Sites reference foundations by configuration, not by folder proximity.
+
+**Three ways to use a foundation:**
+
+| Mode             | How it works                       | Best for                                           |
+| ---------------- | ---------------------------------- | -------------------------------------------------- |
+| **Local folder** | Foundation lives in your workspace | Developing site and components together            |
+| **npm package**  | `pnpm add @acme/foundation`        | Distributing via standard package tooling          |
+| **Runtime link** | Foundation loads from a URL        | Independent release cycles, platform-managed sites |
+
+You can delete the `foundation/` folder entirely and point your site at a published foundation. Or develop a foundation locally, then publish it for other sites to consume. The site doesn't care where its components come from.
+
+**This enables two development patterns:**
+
+_Site-first_ — You're building a website. The foundation is your component library, co-developed with the site. This is the common case.
+
+_Foundation-first_ — You're building a component system. The site is a test harness with sample content. The real sites live elsewhere—other repositories, other teams, or managed on [uniweb.app](https://uniweb.app). The `multi` template supports this workflow with multiple test sites exercising a shared foundation.
 
 ## 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.
+1. **Single project** — One site, one foundation. Develop and deploy together. Most projects stay here.
+
+2. **Published foundation** — Release your foundation as an npm package or to [uniweb.app](https://uniweb.app). Other sites can use it without copying code.
+
+3. **Multiple sites** — Several sites share one foundation. Update components once, every site benefits.
+
+4. **Platform-managed sites** — Sites built on [uniweb.app](https://uniweb.app) with visual editing tools can use your foundation. You develop components locally; content teams work in the browser.
 
-Start with local markdown files deployed anywhere. Connect to [uniweb.app](https://uniweb.app) when you're ready for dynamic content and team collaboration.
+Start with local files deployed anywhere. The same foundation works across all these scenarios.
 
 ---
 
@@ -250,123 +288,58 @@ build:
   prerender: true
 ```
 
-Or use the `--prerender` flag to force it on (or `--no-prerender` to skip it). This is useful for:
+Or use the `--prerender` flag. This gives you:
 
 - **SEO**: Search engines see fully rendered content immediately
-- **Performance**: First contentful paint is instant (no JavaScript required)
+- **Performance**: First contentful paint is instant
 - **Hosting**: Deploy to any static host (GitHub Pages, Netlify, S3, etc.)
 
-**How it works:**
-
-1. The site build runs first, generating the JavaScript bundle and `site-content.json`
-2. The prerenderer loads the foundation and site content in Node.js
-3. Each page is rendered to HTML using React's `renderToString()`
-4. The HTML is injected into the shell with the site content embedded
-
-**Hydration:**
-
-The pre-rendered HTML includes a `<script id="__SITE_CONTENT__">` tag with the full site data. When the page loads in the browser:
-
-1. The static HTML displays immediately (no flash of loading state)
-2. React hydrates the existing DOM instead of replacing it
-3. The site becomes fully interactive with client-side routing
-
-**Usage:**
-
-```bash
-# From site directory (with build.prerender: true in site.yml)
-cd site
-pnpm build
-
-# Or force pre-rendering via CLI flag
-cd site && uniweb build --prerender
-```
+The pre-rendered HTML includes embedded site content. When the page loads, React hydrates the existing DOM—no flash of loading state, then full client-side interactivity.
 
 ## Built-in Templates
 
 ### Single (Default)
 
-A minimal workspace with a site and foundation as sibling packages. This is the recommended starting point.
+A minimal workspace with a site and foundation as sibling packages. The recommended starting point.
 
 ```
 my-project/
-├── package.json              # Workspace root (npm + pnpm compatible)
-├── pnpm-workspace.yaml       # Pre-configured for evolution (see below)
-├── CLAUDE.md                 # AI assistant instructions
-│
-├── site/                     # Site package (content + entry)
+├── package.json              # Workspace root
+├── pnpm-workspace.yaml
+├── site/
 │   ├── package.json
-│   ├── vite.config.js        # 3-line config
-│   ├── index.html
-│   ├── site.yml              # Site configuration (foundation, title, i18n)
-│   ├── main.js               # Entry point (~6 lines)
-│   ├── pages/                # Content pages (file-based routing)
-│   │   └── home/
-│   │       ├── page.yml
-│   │       └── 1-hero.md
-│   └── public/               # Static assets
-│
-└── foundation/               # Foundation package (components)
+│   ├── vite.config.js
+│   ├── site.yml
+│   ├── main.js
+│   └── pages/
+└── foundation/
     ├── package.json
-    ├── vite.config.js        # 3-line config
-    └── src/
-        ├── styles.css        # Tailwind CSS v4
-        ├── meta.js           # Foundation metadata
-        ├── exports.js        # (optional) Custom Layout, props
-        └── components/
-            └── Section/
-                ├── index.jsx
-                └── meta.js
+    ├── vite.config.js
+    └── src/components/
 ```
 
-**Key characteristics:**
-
-- **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.
+A monorepo for foundation development or multi-site projects.
 
 ```
 my-workspace/
-├── package.json              # Workspace root (npm + pnpm compatible)
-├── pnpm-workspace.yaml       # Same config as single template
-├── CLAUDE.md                 # AI assistant instructions
-│
 ├── sites/
-│   ├── marketing/            # Main marketing site
-│   │   ├── package.json
-│   │   ├── vite.config.js    # 3-line config
-│   │   ├── site.yml
-│   │   ├── main.js           # Entry point (~6 lines)
-│   │   └── pages/
-│   └── docs/                 # Documentation site
-│
+│   ├── marketing/            # Main site or test site
+│   └── docs/                 # Additional site
 └── foundations/
-    ├── marketing/            # Marketing foundation
-    │   ├── package.json
-    │   ├── vite.config.js    # 3-line config
-    │   └── src/components/
-    └── documentation/        # Documentation foundation
+    ├── marketing/            # Primary foundation
+    └── documentation/        # Additional foundation
 ```
 
-Use this when you need:
-
-- Multiple sites sharing foundations
-- Multiple foundations for different purposes
-- A testing site for foundation development
+Use this when you need multiple sites sharing foundations, multiple foundations for different purposes, or test sites for foundation development.
 
 ## Official Templates
 
-Feature-rich templates that demonstrate what's possible with Uniweb. These include real components, sample content, and production-ready structure.
+Feature-rich templates with real components and sample content.
 
 ### Marketing
 
-A complete marketing site with landing page components:
-
 ```bash
 uniweb create my-site --template marketing
 ```
@@ -383,8 +356,6 @@ uniweb create my-site --template marketing --variant tailwind3
 
 ### Academic
 
-A professional academic site for researchers, labs, and departments:
-
 ```bash
 uniweb create my-site --template academic
 ```
@@ -395,8 +366,6 @@ Perfect for researcher portfolios, lab websites, and academic department sites.
 
 ### Docs
 
-A documentation site with navigation levels:
-
 ```bash
 uniweb create my-site --template docs
 ```
@@ -405,9 +374,34 @@ uniweb create my-site --template docs
 
 Perfect for technical documentation, guides, and API references.
 
+### International
+
+```bash
+uniweb create my-site --template international
+```
+
+**Includes:** Hero, Features, Team, CTA, Header (with language switcher), Footer (with language links)
+
+**Languages:** English (default), Spanish, French
+
+A multilingual business site demonstrating Uniweb's i18n capabilities. Includes pre-configured translation files and a complete localization workflow:
+
+```bash
+# Extract translatable strings
+uniweb i18n extract
+
+# Check translation coverage
+uniweb i18n status
+
+# Build generates locale-specific output (dist/es/, dist/fr/)
+uniweb build
+```
+
+Perfect for international businesses and learning the i18n workflow.
+
 ## External Templates
 
-You can use templates from npm or GitHub:
+Use templates from npm or GitHub:
 
 ```bash
 # npm package
@@ -420,8 +414,6 @@ uniweb create my-site --template github:user/repo
 uniweb create my-site --template github:user/repo#v1.0.0
 ```
 
-External templates must follow the same structure as official templates. See [`@uniweb/templates`](https://github.com/uniweb/templates) for the template format specification.
-
 ## Dependency Management
 
 Each package manages its own dependencies:
@@ -452,14 +444,14 @@ cd foundation && pnpm add embla-carousel
 The `defineSiteConfig()` function handles all Vite configuration for sites:
 
 ```javascript
-import { defineSiteConfig } from "@uniweb/build/site";
+import { defineSiteConfig } from '@uniweb/build/site'
 
 export default defineSiteConfig({
   // All options are optional
   tailwind: true, // Enable Tailwind CSS v4 (default: true)
   plugins: [], // Additional Vite plugins
   // ...any other Vite config options
-});
+})
 ```
 
 ### Foundation Configuration
@@ -467,11 +459,11 @@ export default defineSiteConfig({
 The `defineFoundationConfig()` function handles all Vite configuration for foundations:
 
 ```javascript
-import { defineFoundationConfig } from "@uniweb/build";
+import { defineFoundationConfig } from '@uniweb/build'
 
 export default defineFoundationConfig({
   // All options are optional - entry is auto-generated
-  fileName: "foundation", // Output file name
+  fileName: 'foundation', // Output file name
   externals: [], // Additional packages to externalize
   includeDefaultExternals: true, // Include react, @uniweb/core, etc.
   tailwind: true, // Enable Tailwind CSS v4 Vite plugin
@@ -479,7 +471,7 @@ export default defineFoundationConfig({
   plugins: [], // Additional Vite plugins
   build: {}, // Additional Vite build options
   // ...any other Vite config options
-});
+})
 ```
 
 For Tailwind CSS v3 projects, set `tailwind: false` and use PostCSS:
@@ -487,7 +479,7 @@ For Tailwind CSS v3 projects, set `tailwind: false` and use PostCSS:
 ```javascript
 export default defineFoundationConfig({
   tailwind: false, // Uses PostCSS instead of Vite plugin
-});
+})
 ```
 
 ## Foundation Build Process
@@ -520,62 +512,40 @@ Both templates use the same unified workspace configuration:
 ```yaml
 # pnpm-workspace.yaml
 packages:
-  - "site"
-  - "foundation"
-  - "sites/*"
-  - "foundations/*"
+  - 'site'
+  - 'foundation'
+  - 'sites/*'
+  - 'foundations/*'
 ```
 
+Also set in `package.json` for npm compatibility.
+
 ```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
+This means no config changes when evolving from single to multi-site.
 
-The workspace is pre-configured for growth. Choose your path:
+## Releasing a Foundation
 
-**Add alongside existing structure:**
+Publish your foundation to npm:
 
 ```bash
-# Keep site/ and foundation/, add more in sites/ and foundations/
-mkdir -p sites/docs
-mkdir -p foundations/documentation
+cd foundation
+npm publish
 ```
 
-**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:
+Or to [uniweb.app](https://uniweb.app) for use with platform-managed sites:
 
 ```bash
 uniweb login          # First time only
 uniweb build
-uniweb publish        # Publishes the foundation in the current directory
+uniweb publish
 ```
 
-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
-```
+Sites control their own update strategy—automatic, minor-only, patch-only, or pinned to a specific version.
 
 ## FAQ
 
@@ -585,19 +555,23 @@ MDX blends markdown and JSX—content authors write code. Uniweb keeps them sepa
 
 **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.
+Astro is a static site generator. Uniweb is a component content architecture that works with any deployment (static, SSR, or platform-managed). The foundation model means components are portable across sites and ready for integration with visual editors.
 
 **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.
 
+**Can I use an existing component library?**
+
+Yes. Foundations are standard React. Import any library into your foundation components. The `{ content, params }` interface only applies to exposed components—internal components use regular props.
+
 **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.
+Yes. Content is pre-embedded in the initial HTML—no fetch waterfalls, no layout shifts. Meta tags are generated per page. SSG is supported by default.
 
 **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.
+Pages can define data sources that auto-generate subroutes. A `/blog` page can have an index and a `[slug]` template that renders each post.
 
 ## Related Packages
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.2.40",
+  "version": "0.2.42",
   "description": "Create structured Vite + React sites with content/code separation",
   "type": "module",
   "bin": {
@@ -37,8 +37,8 @@
     "js-yaml": "^4.1.0",
     "prompts": "^2.4.2",
     "tar": "^7.0.0",
-    "@uniweb/build": "0.1.21",
-    "@uniweb/core": "0.1.9",
+    "@uniweb/build": "0.1.23",
+    "@uniweb/core": "0.1.10",
     "@uniweb/kit": "0.1.5",
     "@uniweb/runtime": "0.2.11"
   }

package/partials/{claude-md.hbs → agents-md.hbs}

@@ -1,4 +1,4 @@
-# CLAUDE.md
+# AGENTS.md
 
 This file provides guidance for AI assistants working with this Uniweb project.
 

package/partials/ai-assistance.hbs

@@ -1,3 +1,3 @@
 ## AI Assistance
 
-See [CLAUDE.md](./CLAUDE.md) for detailed instructions that AI assistants can use.
+See [AGENTS.md](./AGENTS.md) for detailed instructions that AI assistants can use.

package/partials/components-docs.hbs

@@ -3,13 +3,11 @@
 Generate up-to-date documentation for all foundation components:
 
 ```bash
-# From within the foundation directory
-pnpm docs
-```
+# From foundation directory
+pnpm uniweb docs
 
-This creates `COMPONENTS.md` with full details on each component's:
-- Content elements (title, paragraphs, links, images, items)
-- Parameters (theme, layout, columns, etc.)
-- Presets (pre-configured parameter combinations)
+# Or from site directory (auto-detects linked foundation)
+cd site && pnpm uniweb docs
+```
 
-The documentation is generated from component `meta.js` files, so it's always current.
+This creates `COMPONENTS.md` with details on each component's parameters, presets, and content elements. The documentation is generated from component `meta.js` files, so it's always current.

package/src/commands/docs.js

@@ -7,10 +7,14 @@
  *   uniweb docs                    # Generate docs for current directory
  *   uniweb docs --output README.md # Custom output filename
  *   uniweb docs --from-source      # Build schema from source (no build required)
+ *
+ * When run from a site directory, automatically finds and documents the
+ * linked foundation, placing COMPONENTS.md in the site folder.
  */
 
 import { existsSync } from 'node:fs'
-import { resolve, join } from 'node:path'
+import { readFile } from 'node:fs/promises'
+import { resolve, join, dirname } from 'node:path'
 import { generateDocs } from '@uniweb/build'
 
 // Colors for terminal output
@@ -72,7 +76,7 @@ function showHelp() {
 ${colors.bright}uniweb docs${colors.reset} - Generate component documentation
 
 ${colors.dim}Usage:${colors.reset}
-  uniweb docs                         Generate COMPONENTS.md from schema.json
+  uniweb docs                         Generate COMPONENTS.md
   uniweb docs --output DOCS.md        Custom output filename
   uniweb docs --from-source           Build schema from source (no build required)
 
@@ -82,8 +86,9 @@ ${colors.dim}Options:${colors.reset}
   -h, --help             Show this help message
 
 ${colors.dim}Notes:${colors.reset}
-  By default, docs are generated from dist/schema.json (requires build).
-  Use --from-source to generate without building first.
+  Run from a foundation directory to generate docs there.
+  Run from a site directory to auto-detect the linked foundation
+  and generate docs in the site folder for convenience.
 `)
 }
 
@@ -96,6 +101,47 @@ function isFoundation(dir) {
   return existsSync(componentsDir)
 }
 
+/**
+ * Detect if current directory is a site
+ */
+function isSite(dir) {
+  return existsSync(join(dir, 'site.yml')) || existsSync(join(dir, 'site.yaml'))
+}
+
+/**
+ * Resolve foundation path from a site directory
+ * Reads package.json to find foundation dependency with file: protocol
+ */
+async function resolveFoundationFromSite(siteDir) {
+  const pkgPath = join(siteDir, 'package.json')
+  if (!existsSync(pkgPath)) {
+    return null
+  }
+
+  try {
+    const pkg = JSON.parse(await readFile(pkgPath, 'utf-8'))
+    const deps = { ...pkg.dependencies, ...pkg.devDependencies }
+
+    // Look for foundation dependency with file: protocol
+    // Common names: "foundation", or the foundation name from site.yml
+    for (const [name, version] of Object.entries(deps)) {
+      if (typeof version === 'string' && version.startsWith('file:')) {
+        const relativePath = version.slice(5) // Remove 'file:' prefix
+        const absolutePath = resolve(siteDir, relativePath)
+
+        // Check if this is actually a foundation
+        if (isFoundation(absolutePath)) {
+          return { name, path: absolutePath }
+        }
+      }
+    }
+  } catch {
+    // Ignore parse errors
+  }
+
+  return null
+}
+
 /**
  * Main docs command
  */
@@ -108,19 +154,34 @@ export async function docs(args) {
   }
 
   const projectDir = resolve(process.cwd())
+  let foundationDir = projectDir
+  let outputDir = projectDir
+
+  // Check if we're in a site directory
+  if (isSite(projectDir)) {
+    const foundation = await resolveFoundationFromSite(projectDir)
+    if (!foundation) {
+      error('Could not find a linked foundation in this site.')
+      log(`${colors.dim}Make sure package.json has a foundation dependency like:${colors.reset}`)
+      log(`${colors.dim}  "foundation": "file:../foundation"${colors.reset}`)
+      process.exit(1)
+    }
 
-  // Verify this is a foundation
-  if (!isFoundation(projectDir)) {
-    error('This directory does not appear to be a foundation.')
-    log(`${colors.dim}Foundations have a src/components/ directory with component folders.${colors.reset}`)
+    foundationDir = foundation.path
+    outputDir = projectDir
+    info(`Found foundation: ${foundation.name} (${foundation.path})`)
+  } else if (!isFoundation(projectDir)) {
+    error('This directory does not appear to be a foundation or site.')
+    log(`${colors.dim}Foundations have a src/components/ directory.${colors.reset}`)
+    log(`${colors.dim}Sites have a site.yml file.${colors.reset}`)
     process.exit(1)
   }
 
   // Check if schema.json exists (if not using --from-source)
-  const schemaPath = join(projectDir, 'dist', 'schema.json')
+  const schemaPath = join(foundationDir, 'dist', 'schema.json')
   if (!options.fromSource && !existsSync(schemaPath)) {
-    log(`${colors.yellow}⚠${colors.reset} No dist/schema.json found.`)
-    log(`${colors.dim}Run 'uniweb build' first, or use '--from-source' to read meta.js files directly.${colors.reset}`)
+    log(`${colors.yellow}⚠${colors.reset} No dist/schema.json found in foundation.`)
+    log(`${colors.dim}Run 'uniweb build' in the foundation first, or use '--from-source'.${colors.reset}`)
     log('')
     info('Falling back to --from-source mode')
     options.fromSource = true
@@ -129,8 +190,8 @@ export async function docs(args) {
   try {
     info('Generating documentation...')
 
-    const result = await generateDocs(projectDir, {
-      output: options.output,
+    const result = await generateDocs(foundationDir, {
+      output: join(outputDir, options.output),
       fromSource: options.fromSource,
     })
 

package/src/templates/resolver.js

@@ -6,7 +6,7 @@
 export const BUILTIN_TEMPLATES = ['single', 'multi', 'template']
 
 // Official templates from @uniweb/templates package (downloaded from GitHub releases)
-export const OFFICIAL_TEMPLATES = ['marketing', 'academic', 'docs']
+export const OFFICIAL_TEMPLATES = ['marketing', 'academic', 'docs', 'international']
 
 /**
  * Parse a template identifier and determine its source type

package/templates/_shared/AGENTS.md.hbs

@@ -0,0 +1 @@
+{{> agents-md}}

package/templates/multi/AGENTS.md.hbs

@@ -0,0 +1 @@
+{{> agents-md}}

package/templates/multi/README.md.hbs

@@ -22,7 +22,7 @@ A multi-site workspace built with [Uniweb](https://github.com/uniweb/cli) — a
 │       ├── main.js
 │       └── vite.config.js
 │
-├── CLAUDE.md            # AI assistant instructions
+├── AGENTS.md            # AI assistant instructions
 └── README.md            # This file
 ```
 

package/templates/multi/foundations/default/package.json.hbs

@@ -14,8 +14,7 @@
     "dev": "vite",
     "build": "uniweb build",
     "build:vite": "vite build",
-    "preview": "vite preview",
-    "docs": "uniweb docs"
+    "preview": "vite preview"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",

package/templates/single/README.md.hbs

@@ -22,7 +22,7 @@ A website built with [Uniweb](https://github.com/uniweb/cli) — a component web
 │   ├── site.yml         # Site configuration
 │   └── vite.config.js   # defineSiteConfig()
 │
-└── CLAUDE.md            # AI assistant instructions
+└── AGENTS.md            # AI assistant instructions
 ```
 
 ## Content Authoring

package/templates/single/foundation/package.json.hbs

@@ -14,8 +14,7 @@
     "dev": "vite",
     "build": "uniweb build",
     "build:vite": "vite build",
-    "preview": "vite preview",
-    "docs": "uniweb docs"
+    "preview": "vite preview"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",

package/templates/single/template.json

@@ -3,7 +3,7 @@
   "description": "A minimal Uniweb project with one foundation and one site. The canonical starting point for any Uniweb project.",
   "base": "_shared",
   "structure": {
-    "root": ["package.json.hbs", "pnpm-workspace.yaml", ".gitignore", "CLAUDE.md.hbs"],
+    "root": ["package.json.hbs", "pnpm-workspace.yaml", ".gitignore", "AGENTS.md.hbs"],
     "foundation": ["package.json.hbs", "vite.config.js", ".gitignore", "src/"],
     "site": ["package.json.hbs", "vite.config.js", "index.html.hbs", "site.yml.hbs", "src/", "pages/"]
   }

package/templates/template/template/{CLAUDE.md.hbs → AGENTS.md.hbs}

@@ -1,4 +1,4 @@
-# CLAUDE.md - AI Assistant Instructions
+# AGENTS.md - AI Assistant Instructions
 
 This file provides guidance for AI assistants working with this Uniweb template project.
 

package/templates/_shared/CLAUDE.md.hbs

@@ -1 +0,0 @@
-{{> claude-md}}

package/templates/multi/CLAUDE.md.hbs

@@ -1 +0,0 @@
-{{> claude-md}}