create-bascik 1.0.0-rc.4 → 1.0.0-rc.6

package/README.md

@@ -25,8 +25,8 @@ npm create bascik@latest
 
 ```text
 my-site/
-├── .github/skills/bascik/SKILL.md  ← AI Copilot skill file
-├── .claude/skills/bascik/SKILL.md  ← Claude skill file
+├── .agents/skills/                 ← Bascik agent skills for Copilot, Cursor, Codex, and others
+├── .claude/skills/                 ← The same skills for Claude Code
 ├── .vscode/
 │   ├── launch.json                 ← Debug launchers for dev server and tests
 │   └── extensions.json             ← Recommends official Bascik extension

package/assets/skills/README.md

@@ -0,0 +1,64 @@
+# Bascik Agent Skills
+
+[Agent Skills](https://agentskills.io) that teach AI coding assistants (GitHub Copilot, Claude Code, Cursor, Codex, Gemini CLI, OpenCode, Windsurf, and others) how to build sites with [Bascik](https://bascik.dev).
+
+## Install
+
+With the [skills CLI](https://skills.sh):
+
+```sh
+npx skills add bascikdev/bascik
+# or from the docs site's /.well-known/agent-skills/ index:
+npx skills add https://bascik.dev
+```
+
+Without it, download every skill into the shared `.agents/skills/` folder (use `.claude/skills` for Claude Code, or `.github/skills` if you prefer):
+
+```sh
+mkdir -p .agents/skills && curl -fsSL https://bascik.dev/assets/skills.tar.gz | tar -xz -C .agents/skills
+```
+
+New projects created with `npm create bascik@latest` include these skills already.
+
+## Skills
+
+| Skill | Use it for |
+|---|---|
+| [`bascik`](bascik/SKILL.md) | Start here: project layout, components, slots, props, the CLI, verifying output, examples, and building a new site |
+| [`bascik-components`](bascik-components/SKILL.md) | Component CSS and scripts that work with many instances, interactivity, and theming |
+| [`bascik-compatibility`](bascik-compatibility/SKILL.md) | Which HTML, CSS, and JavaScript features to use: Baseline support and Bascik scoping |
+| [`bascik-scripts`](bascik-scripts/SKILL.md) | Build, routes, server, and stream scripts, API routes, and Markdown blogs |
+| [`bascik-seo`](bascik-seo/SKILL.md) | Head tags, social cards, structured data, sitemap, and `llms.txt` |
+| [`bascik-config`](bascik-config/SKILL.md) | `bascik.config.ts`, exec scripts, assets, deployment, and monorepos |
+| [`bascik-testing`](bascik-testing/SKILL.md) | Unit and E2E tests, debugging, spec validation, Lighthouse |
+| [`bascik-migrate`](bascik-migrate/SKILL.md) | Moving a site from React, Next.js, Vue, Svelte, Astro, Eleventy, Hugo, or WordPress |
+
+The skills hold the rules an assistant must follow and point to the docs at https://bascik.dev for everything else, so the guidance lives in one place. `bascik/scripts/read-doc.mjs` prints any docs page.
+
+## Scripts
+
+The skills ship dependency-free Node.js scripts (Node 22.18+) that agents run from the project root:
+
+| Script | Purpose |
+|---|---|
+| `bascik/scripts/verify.mjs` | `bascik --check` plus the language server linter (including component folders outside the project), optionally a build |
+| `bascik/scripts/preview.mjs` | Compile a snippet or page with the project's components and print readable output |
+| `bascik/scripts/list-components.mjs` | Inventory components with props, slots, and descriptions |
+| `bascik/scripts/new-component.mjs` | Create a component that follows the conventions |
+| `bascik/scripts/search-docs.mjs` | Search the live docs |
+| `bascik/scripts/read-doc.mjs` | Print a docs page as text |
+| `bascik/scripts/add-example.mjs` | Copy an example from https://bascik.dev/example-components into the project |
+| `bascik/scripts/check-links.mjs` | Find broken internal links and `#fragments` in `dist/` |
+| `bascik-components/scripts/check-tokens.mjs` | Find CSS custom properties components use but nothing declares |
+| `bascik-compatibility/scripts/lookup.mjs` | Search Bascik's live compatibility matrix |
+| `bascik-compatibility/scripts/baseline.mjs` | Baseline browser support for a web feature |
+| `bascik-scripts/scripts/new-post.mjs` | Create a Markdown post with valid front matter |
+| `bascik-seo/scripts/audit-seo.mjs` | Check titles, descriptions, canonicals, social tags, and JSON-LD in `dist/` |
+| `bascik-config/scripts/audit-config.mjs` | Flag redundant or risky `bascik.config.ts` values |
+| `bascik-config/scripts/check-workspace.mjs` | Map every site in a repository and report cross-site problems |
+
+The example components and the starter site live in the repository's [`examples/`](https://github.com/bascikdev/bascik/tree/main/examples) folder, not in the skills. The docs build publishes them at `https://bascik.dev/assets/examples.json`, which `add-example.mjs` downloads.
+
+## Contributing
+
+These files are the source of truth. The docs build publishes them to `https://bascik.dev/assets/skills.tar.gz`, `https://bascik.dev/.well-known/agent-skills/` (one archive per skill plus `index.json`), and the core skill to `https://bascik.dev/assets/SKILL.md`, and `create-bascik` bundles a copy in `create/assets/skills/` (`yarn create:prepack`). Contributor-only skills for working on Bascik itself live in `.github/skills/` and are marked `metadata.internal`, so `npx skills add` does not offer them.

package/assets/skills/bascik/SKILL.md

@@ -0,0 +1,214 @@
+---
+name: bascik
+description: Build websites with Bascik, the zero-runtime HTML component build tool. Use whenever a project depends on @bascik/bascik, has a bascik.config.ts, or keeps components in src/components/*.html, or when the user mentions Bascik. Covers pages, components, slots, props, attribute inheritance, the bascik CLI (dev, --build, --server, --check, add), project layout, verifying compiled dist/ output, building a new site, and copying tested example components. Start here; companion skills cover components, compatibility, scripts, SEO, config, testing, and migration.
+license: MIT
+metadata:
+  author: bascik
+  homepage: https://bascik.dev
+---
+
+# Bascik
+
+Bascik is a build tool for HTML components. It expands custom tags such as `<site-nav />` into the matching component file, scopes the component's CSS, IDs, classes, and scripts, and writes plain HTML pages to `dist/`. It adds zero JavaScript: every script in the output is one you wrote.
+
+It is not a framework. There is no virtual DOM, reactive state, client router, template language, Shadow DOM, or runtime. Write vanilla HTML, CSS, and JavaScript, and let Bascik do the isolation at build time.
+
+Code in this skill is illustrative. Adapt tag names, paths, and values to the project instead of copying example names literally.
+
+## Recognize a Bascik project
+
+- `package.json` depends on `@bascik/bascik`, or the root has `bascik.config.ts` / `bascik.config.js`, or there are `.html` files under `src/components/`.
+- Node.js 22.18 or newer (24 LTS recommended). Node runs `.ts` helpers natively, so no TypeScript build step exists.
+- Standard scripts: `npm run dev` (`bascik`), `npm run build` (`bascik --build`), `npm run lint` (`bascik-language-server --check`).
+
+## Project layout
+
+```text
+src/
+  components/            component templates; the file name is the tag name
+    site-nav/
+      site-nav.html      <site-nav>
+      site-nav.css       optional companion stylesheet, scoped to site-nav
+      site-nav.ts        optional companion script, loaded with <script src="site-nav.ts">
+  pages/                 one .html file per URL, plus public assets
+    index.html           /
+    about.html           /about
+    blog/post.html       /blog/post
+    404.html             served for unknown routes
+    css/styles.css       copied to dist/css/styles.css (global, unscoped)
+  lib/                   shared Node helpers for build and server scripts (import with @/lib/...)
+  api/                   optional API route handlers (bascik --server only)
+dist/                    compiled output, never edited by hand, never committed
+```
+
+## Write a component
+
+Default pattern: `<style>` above the markup, markup in the middle, `<script>` below. Give every element a script must control an `id` and find it with `getElementById`.
+
+```html
+<!-- src/components/like-button/like-button.html -->
+<style>
+  .like { padding: 0.5rem 1rem; border-radius: 6px; }
+  .like.active { background: #d3ff8d; }
+</style>
+<button class="like" id="btn" type="button">
+  <span data-bascik-prop-label>Like</span>
+</button>
+<script>
+  const btn = document.getElementById('btn');
+  btn.addEventListener('click', () => btn.classList.toggle('active'));
+</script>
+```
+
+```html
+<!-- src/pages/index.html -->
+<like-button data-bascik-prop-label="Like this post" />
+<like-button data-bascik-prop-label="Like this comment" />
+```
+
+Bascik rewrites `.like` to `.bascik__like-button__like`, gives each instance its own `id` (`bascik__like-button__<instance>__btn`), rewrites the `getElementById` string and the `classList` class to match, and wraps the script in an IIFE. Both buttons work independently. To see the exact output, run [`scripts/preview.mjs`](scripts/preview.mjs).
+
+New components are picked up by the running dev server automatically; no restart is needed.
+
+## Rules (must follow)
+
+1. **Hyphenated, lowercase file names.** `feature-card.html` becomes `<feature-card>`. Never name a component after a native element (`header.html`, `dialog.html`): it replaces every such element on the page. Names must be unique across every component root.
+2. **Per-instance targeting uses `id`.** Use `getElementById` (or `getElementsByName`) for elements a script controls. `querySelector('.cls')` returns the first instance on the page, so the other instances look broken.
+3. **Order:** `<style>` above the markup, `<script>` below it.
+4. **Props carry text only.** `data-bascik-prop-*` values are HTML-escaped strings. Pass markup or nested components through slots (`data-bascik-slot`).
+5. **Self-close** components that take no slot content: `<site-head />`, `<site-footer />`.
+6. **HTML and CSS first.** Reach for JavaScript only when HTML and CSS cannot do the job cleanly (`<details>`, `<dialog>`, `:has()`, `popover` cover a lot).
+7. **Runtime state in `data-` attributes.** Toggle `data-state="open"` and style `.panel[data-state="open"]`; anchor attribute selectors on a scoped class.
+8. **Zero config.** Do not create `bascik.config.ts` unless a requirement differs from a default, and never put `siteUrl` in it. See the `bascik-config` skill.
+9. **Never write generated files into `src/`.** Generated output goes to `dist/` (`BASCIK_OUT_DIR`) from an existing `pipeline.exec` script.
+10. **Client scripts are not bundled.** Bare imports such as `import x from 'pkg'` fail in the browser. They work only in Node-side scripts (`data-bascik-build`, `data-bascik-server`).
+11. **Extract shared layout.** Repeated `<head>` tags, headers, and footers become components (`<site-head />`, `<site-header />`, `<site-footer />`). Pages keep their own `<html>`, `<head>`, and `<body>`.
+12. **Script directives are exclusive.** One `<script>` tag takes at most one of `data-bascik-build`, `data-bascik-routes`, `data-bascik-server`, `data-bascik-stream`.
+
+## Slots, props, and attributes
+
+| Need | Component template | Usage site |
+|---|---|---|
+| Default slot (rich HTML) | `<div data-bascik-slot>fallback</div>` | `<my-card><h2>Title</h2></my-card>` |
+| Named slot | `<div data-bascik-slot="header"></div>` | `<div data-bascik-slot="header"><h1>Hi</h1></div>` inside the tag |
+| Text prop | `<p data-bascik-prop-title></p>` | `<my-card data-bascik-prop-title="Hello" />` |
+| Prop into an attribute | `<img data-bascik-attr-src="image" data-bascik-attr-alt="alt">` | `<my-card data-bascik-prop-image="/a.png" data-bascik-prop-alt="A" />` |
+| Forward attributes | (nothing) | `<my-card class="wide" aria-label="Promo" />` lands on the first root element |
+
+Pass props as `data-bascik-prop-<name>="..."` on the usage tag. A plain attribute such as `label="..."` is not a prop: it is forwarded to the root element and the prop keeps its default. The slot element itself is replaced by the content, so named-slot wrappers disappear: wrap headings and links in a `<div data-bascik-slot="x">` rather than putting the attribute on the `<h1>` or `<a>`. Details: `read-doc.mjs /slots`, `/props`, `/attribute-inheritance`.
+
+## Script tags at a glance
+
+| Tag | Runs | Use for |
+|---|---|---|
+| `<script>` | Browser | Component and page behavior (scoped, IIFE-wrapped) |
+| `<script data-bascik-build>` | Node, at build time | Markup from files, Markdown, APIs; output replaces the tag |
+| `<script data-bascik-routes>` | Node, at build time | Expanding `[slug].html` templates into many pages |
+| `<script data-bascik-server>` | Node, per request | Personalized markup (needs `bascik --server` or a serverless target) |
+| `<script data-bascik-stream>` | Node, per request, streamed | Slow per-request blocks that should not delay the page shell |
+| `<script data-bascik-dev>` | Browser, dev only | Debug helpers removed from production builds |
+
+Node-side scripts export a default function that returns an HTML string. Details are in the `bascik-scripts` skill.
+
+## CLI
+
+```sh
+bascik                      # dev server at http://localhost:8080 with live reload and watch
+bascik --build              # production build to dist/ (HTML, CSS, JS, and identifier minification on)
+bascik --build --only "blog/**"   # rebuild matching pages without cleaning dist/
+bascik --server             # serve a built dist/ (needed for server/stream scripts and API routes)
+bascik --check              # validate pages, components, config, and API routes without building
+bascik add <package>        # copy components from an installed npm package into src/components/
+bascik init                 # add Bascik to an existing project
+npx @bascik/language-server --check   # lint scoping patterns, unclosed tags, and directives
+```
+
+New project: `npm create bascik@latest my-site -y`. Production builds need a site URL for `sitemap.xml` and `robots.txt`: `BASCIK_SITE_URL=https://example.com bascik --build` (or `--site-url`, or `.env`). Full CLI and error output: `read-doc.mjs /cli`.
+
+## Verify every change
+
+Do not stop at "the file looks right". Run these from the project root:
+
+1. `node <skill-dir>/scripts/verify.mjs` runs `bascik --check` and the language server linter and summarizes both. Add `--build` to also run a production build.
+2. `node <skill-dir>/scripts/preview.mjs '<my-card data-bascik-prop-title="Hi" />' --count 2` compiles a snippet with the project's real components and config and prints the unminified output, so you can confirm scoped names, slot placement, and script rewrites.
+3. Read the relevant file in `dist/` after a build. A hyphenated tag still present in `dist/` means no component matched it.
+
+`<skill-dir>` is the directory containing this file, for example `.agents/skills/bascik`.
+
+## Bundled scripts
+
+All scripts are dependency-free Node.js (22.18+) and run from the project root. Each prints `--help`.
+
+| Script | Purpose |
+|---|---|
+| [`scripts/verify.mjs`](scripts/verify.mjs) | `bascik --check` plus `@bascik/language-server --check`, with an optional `--build` |
+| [`scripts/preview.mjs`](scripts/preview.mjs) | Compile a snippet, file, or existing page in a temporary build and print the result |
+| [`scripts/list-components.mjs`](scripts/list-components.mjs) | Inventory components with their props, slots, companion files, and `@bascik` descriptions |
+| [`scripts/new-component.mjs`](scripts/new-component.mjs) | Create a component folder that follows the naming and ordering rules |
+| [`scripts/search-docs.mjs`](scripts/search-docs.mjs) | Search the live docs at bascik.dev for a topic |
+| [`scripts/read-doc.mjs`](scripts/read-doc.mjs) | Print the current text of a docs page, such as `/scoped-javascript` |
+| [`scripts/add-example.mjs`](scripts/add-example.mjs) | Copy a tested example component or part of the starter site from bascik.dev into the project (`--list` shows them) |
+| [`scripts/check-links.mjs`](scripts/check-links.mjs) | Find broken internal links, missing assets, and dead `#fragments` in the built `dist/`, honoring `base` |
+
+Run `list-components.mjs` before creating a component so you reuse what exists instead of duplicating it.
+
+## Look it up in the docs
+
+The docs at https://bascik.dev are the reference; this skill only holds the rules. Read the page for any task below before writing code, instead of guessing:
+
+```sh
+node <skill-dir>/scripts/read-doc.mjs /dynamic-routes
+node <skill-dir>/scripts/search-docs.mjs "dynamic routes trailing slash"
+```
+
+| How do I... | Read |
+|---|---|
+| Write components, slots, props, attributes | `/components`, `/slots`, `/props`, `/attribute-inheritance` |
+| Pass shared `<head>` tags | `/how-to/templating` |
+| Use a library (petite-vue, Alpine.js, HTMX, Tailwind) | `/libraries` |
+| Use a third-party web component | `/how-to/third-party-web-components` |
+| Share components between projects | `/how-to/sharing-components`, `/how-to/publishing-components` |
+| Find answers to edge cases | `/faq` |
+| Use the CLI and the dev server | `/cli`, `/development-server` |
+
+The full page index is at https://bascik.dev/llms.txt.
+
+## Start from an example
+
+https://bascik.dev/example-components has tested components (tabs, dialog, popover menu, copy button, filter list, contact form, theme toggle). `add-example.mjs` also offers `starter-site`, a complete site (layout components, SEO helper, Markdown blog, feed, `llms.txt`, contact page) whose README is at https://github.com/bascikdev/bascik/tree/main/examples/starter-site. Copy instead of writing from scratch, then adapt:
+
+```sh
+node <skill-dir>/scripts/add-example.mjs --list
+node <skill-dir>/scripts/add-example.mjs tab-group
+node <skill-dir>/scripts/add-example.mjs starter-site/src/lib/seo.ts
+```
+
+The script downloads from bascik.dev, maps files to the project's configured folders, also copies example components a file uses, and writes nothing if any file would overwrite a different one. It prints `bascik.config.ts` and `package.json` instead of copying them.
+
+## Build a new site
+
+1. `npm create bascik@latest my-site -y`, or read the existing project first with `list-components.mjs`. Add `BASCIK_SITE_URL=https://example.com` to `.env`.
+2. Plan the pages and URLs (one purpose and one `<h1>` each), the shared layout (head, header, footer), repeated content (a collection in `content/`), and anything that needs a server (API routes, per-request markup). Ask when the plan is unclear.
+3. Copy the foundation: `add-example.mjs starter-site`, or only the parts you need. Then replace the example name, navigation (`src/components/site-header/links.ts`), colors (tokens in `src/pages/css/styles.css`), and every page's `seo({ title, description })`.
+4. Add pages, components (`new-component.mjs`), and interactive examples. Load the companion skill for each area.
+5. Before launch: `npx bascik --build`, then `verify.mjs`, `check-links.mjs`, the `bascik-seo` audit, and the `bascik-components` token check. The starter site README's "Build and Check It" section has the manual checklist.
+
+## Companion skills
+
+| Skill | Load it when |
+|---|---|
+| `bascik-components` | Writing component CSS or `<script>` code, adding interactivity, theming, or compiled class and ID names look wrong |
+| `bascik-compatibility` | Deciding whether an HTML, CSS, or JavaScript feature works in browsers and inside a component |
+| `bascik-scripts` | Using `data-bascik-build`, `-routes`, `-server`, `-stream`, API routes, Markdown, or a blog |
+| `bascik-seo` | Titles, descriptions, canonical URLs, social cards, JSON-LD, sitemap, `llms.txt` |
+| `bascik-config` | Creating or editing `bascik.config.ts`, monorepos, deploying, or running `bascik --server` |
+| `bascik-testing` | Writing tests, debugging, validating output, or tuning Lighthouse scores |
+| `bascik-migrate` | Moving a site from React, Next.js, Vue, Svelte, Astro, Eleventy, Hugo, or WordPress |
+
+If the companions or this skill's `scripts/` folder are missing, the skill was installed as a single file. Reinstall the full set:
+
+```sh
+npx skills add bascikdev/bascik
+# or, without npx skills:
+mkdir -p .agents/skills && curl -fsSL https://bascik.dev/assets/skills.tar.gz | tar -xz -C .agents/skills
+```

package/assets/skills/bascik/scripts/add-example.mjs

@@ -0,0 +1,250 @@
+#!/usr/bin/env node
+// Copy an example component or site from https://bascik.dev/example-components into the current Bascik project.
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { parseArgs } from 'node:util';
+import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
+import { componentRoots, docsBaseUrl, fail, findProjectRoot, isMain, loadProjectConfig, pagesDirectory } from './lib/project.mjs';
+import { listComponents } from './lib/components.mjs';
+
+const HELP = `Usage: node add-example.mjs --list
+       node add-example.mjs <example>[/<path>] [...more] [--dry-run] [--force]
+
+Copies examples from https://bascik.dev/example-components into this project. Every example is tested with the real compiler
+and in a browser before it is published.
+
+References:
+  tab-group                          a component, into your first component folder
+  starter-site                       a whole example site
+  starter-site/src/lib/seo.ts        one file of a site
+  starter-site/src/pages/blog        a folder of a site
+
+Copying site files also copies the components they use, from the site or from the example components.
+Site files map to your config's folders:
+src/components -> first directory.components root, src/pages -> directory.pages, src/lib -> <scripts.importRoot>/lib,
+src/api -> directory.api, and anything else (scripts/, content/) to the same path under the project root.
+bascik.config.ts, package.json, and README.md are printed, never copied: merge them by hand.
+
+Nothing is written when any file would overwrite a different existing file, unless you pass --force.
+
+Options:
+  --list            List every example
+  --dry-run         Show what would be copied without writing
+  --force           Overwrite files that exist and differ
+  --source <where>  Read the examples from a URL or a local examples.json (default: <docs>/assets/examples.json)
+  --help            Show this message
+
+Environment:
+  BASCIK_DOCS_URL   Docs origin (default https://bascik.dev)`;
+
+const REFERENCE_ONLY = new Set(['bascik.config.ts', 'bascik.config.js', 'package.json', 'README.md']);
+
+/** Load the examples bundle from a URL or a local file. Exported for tests. */
+export async function loadBundle(source = `${docsBaseUrl()}/assets/examples.json`) {
+  let text;
+  if (/^https?:\/\//i.test(source)) {
+    let response;
+    try {
+      response = await fetch(source, { signal: AbortSignal.timeout(20_000) });
+    } catch (error) {
+      throw new Error(`could not reach ${source}: ${error.message}. Check the network, or pass --source <examples.json>.`);
+    }
+    if (!response.ok) throw new Error(`${source} returned HTTP ${response.status}`);
+    text = await response.text();
+  } else {
+    text = readFileSync(resolve(source), 'utf8');
+  }
+  const bundle = JSON.parse(text);
+  if (bundle?.version !== 1 || !Array.isArray(bundle.examples)) {
+    throw new Error(`${source} is not a supported examples bundle (version ${bundle?.version}). Update the skills.`);
+  }
+  return bundle;
+}
+
+/**
+ * Where a file of an example lands in the project, or undefined for files that are only printed.
+ * `layout` holds absolute paths: root, componentRoot, pagesDir, importRoot, apiDir. Exported for tests.
+ */
+export function destinationFor(example, filePath, layout) {
+  const segments = filePath.split(/[\\/]/);
+  if (isAbsolute(filePath) || segments.some((segment) => segment === '..' || segment === '' || segment === '.')) {
+    throw new Error(`unsafe path in the examples bundle: ${filePath}`);
+  }
+  if (example.kind === 'component') {
+    if (typeof example.name !== 'string' || !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(example.name)) {
+      throw new Error(`unsafe example name in the examples bundle: ${example.name}`);
+    }
+    return join(layout.componentRoot, example.name, filePath);
+  }
+  if (REFERENCE_ONLY.has(filePath)) return undefined;
+  const [first, second, ...rest] = filePath.split('/');
+  if (first === 'src') {
+    const tail = rest.join('/');
+    if (second === 'components') return join(layout.componentRoot, tail);
+    if (second === 'pages') return join(layout.pagesDir, tail);
+    if (second === 'api') return join(layout.apiDir, tail);
+    return join(layout.importRoot, second, tail);
+  }
+  return join(layout.root, filePath);
+}
+
+/**
+ * The files a reference selects, plus the example components those files use. Returns
+ * [{ example, file }] with each file once. Throws on an unknown reference. Exported for tests.
+ */
+export function selectFiles(bundle, references) {
+  const byName = new Map(bundle.examples.map((example) => [example.name, example]));
+  const picked = new Map();
+  const add = (example, file) => picked.set(`${example.name}/${file.path}`, { example, file });
+  // [example the using file belongs to, component name]
+  const queue = [];
+  for (const reference of references) {
+    const [name, ...rest] = reference.replace(/\\/g, '/').replace(/\/+$/, '').split('/');
+    const example = byName.get(name);
+    if (!example) {
+      const names = bundle.examples.map((e) => e.name).join(', ');
+      throw new Error(`no example named "${name}". Available: ${names}`);
+    }
+    const path = rest.join('/');
+    const files = path ? example.files.filter((file) => file.path === path || file.path.startsWith(`${path}/`)) : example.files;
+    if (files.length === 0) throw new Error(`${name} has no file or folder "${path}". Run with --list, or see ${example.docs}`);
+    for (const file of files) {
+      add(example, file);
+      queue.push(...file.uses.map((name) => [example, name]));
+    }
+  }
+  const seen = new Set();
+  while (queue.length) {
+    const [owner, name] = queue.shift();
+    // A site's own src/components/<name>/ wins over the example component of the same name.
+    const local = owner.kind === 'site' ? owner.files.filter((file) => new RegExp(`^src/components/(?:.*/)?${name}/`).test(file.path)) : [];
+    const [example, files] = local.length ? [owner, local] : [byName.get(name), byName.get(name)?.files ?? []];
+    const key = `${example?.name}:${name}`;
+    if (!example || seen.has(key)) continue;
+    seen.add(key);
+    for (const file of files) {
+      add(example, file);
+      queue.push(...file.uses.map((used) => [example, used]));
+    }
+  }
+  return [...picked.values()];
+}
+
+async function main() {
+  const { values, positionals } = parseArgs({
+    allowPositionals: true,
+    options: {
+      list: { type: 'boolean', default: false },
+      'dry-run': { type: 'boolean', default: false },
+      force: { type: 'boolean', default: false },
+      source: { type: 'string' },
+      help: { type: 'boolean', short: 'h', default: false },
+    },
+  });
+  if (values.help || (!values.list && positionals.length === 0)) return console.log(HELP);
+
+  let bundle;
+  try {
+    bundle = await loadBundle(values.source);
+  } catch (error) {
+    fail(`add-example: ${error.message}`);
+  }
+  // An example's docs link is a docs path, or a full URL for examples without a docs page (sites link to GitHub).
+  const docsLink = (example) => new URL(example.docs, `${docsBaseUrl()}/`).href;
+
+  if (values.list) {
+    for (const kind of ['component', 'site']) {
+      const examples = bundle.examples.filter((example) => example.kind === kind);
+      if (!examples.length) continue;
+      console.log(`\n${kind === 'component' ? 'Components' : 'Sites'}`);
+      for (const example of examples) {
+        const firstSentence = example.description.match(/^.*?[.!?](?=\s|$)/)?.[0] ?? example.description;
+        console.log(`  ${example.name.padEnd(16)} ${firstSentence}`);
+        console.log(`  ${''.padEnd(16)} ${docsLink(example)}`);
+      }
+    }
+    return;
+  }
+
+  const root = findProjectRoot();
+  const config = await loadProjectConfig(root);
+  if (config?.error) fail(`add-example: could not load ${config.path}: ${config.error.message}`);
+  const directory = config?.module?.default?.directory ?? {};
+  const roots = componentRoots(root, config?.module);
+  const layout = {
+    root,
+    componentRoot: roots[0],
+    pagesDir: pagesDirectory(root, config?.module),
+    importRoot: resolve(root, config?.module?.default?.scripts?.importRoot ?? 'src'),
+    apiDir: resolve(root, directory.api ?? 'src/api'),
+  };
+
+  let selected;
+  try {
+    selected = selectFiles(bundle, positionals);
+  } catch (error) {
+    fail(`add-example: ${error.message}`);
+  }
+
+  const existingComponents = listComponents(roots, root);
+  const plan = [];
+  const printed = [];
+  for (const { example, file } of selected) {
+    let destination;
+    try {
+      destination = destinationFor(example, file.path, layout);
+    } catch (error) {
+      fail(`add-example: ${error.message}`);
+    }
+    if (!destination) {
+      if (file.path !== 'README.md') printed.push({ example, file });
+      continue;
+    }
+    if (destination.endsWith('.html') && example.kind === 'component' && file.path === `${example.name}.html`) {
+      const clash = existingComponents.find((c) => c.tag === example.name && resolve(root, c.file) !== destination);
+      if (clash) {
+        const same = readFileSync(resolve(root, clash.file), 'utf8') === file.content;
+        if (same) {
+          console.log(`same  ${clash.file}  (already in the project)`);
+          continue;
+        }
+        fail(`add-example: a component named <${example.name}> already exists at ${clash.file}. Rename one of them first.`);
+      }
+    }
+    plan.push({ example, file, destination });
+  }
+
+  const show = (path) => relative(root, path).replace(/\\/g, '/');
+  const conflicts = plan.filter(({ file, destination }) => existsSync(destination) && readFileSync(destination, 'utf8') !== file.content);
+  if (conflicts.length && !values.force) {
+    const list = conflicts.map(({ example, file, destination }) => `  ${show(destination)}  (compare with ${docsLink(example)}, file ${file.path})`);
+    fail(`add-example: these files already exist and differ; nothing was written. Merge by hand, or rerun with --force:\n${list.join('\n')}`);
+  }
+
+  let written = 0;
+  for (const { file, destination } of plan) {
+    if (existsSync(destination) && readFileSync(destination, 'utf8') === file.content) {
+      console.log(`same  ${show(destination)}`);
+      continue;
+    }
+    console.log(`${values['dry-run'] ? 'would' : 'write'} ${show(destination)}`);
+    if (values['dry-run']) continue;
+    mkdirSync(dirname(destination), { recursive: true });
+    writeFileSync(destination, file.content);
+    written++;
+  }
+
+  for (const { example, file } of printed) {
+    console.log(`\n--- ${example.name}/${file.path} (not copied: merge what you need by hand) ---\n${file.content.trimEnd()}`);
+  }
+  const packageJson = printed.find(({ file }) => file.path === 'package.json');
+  if (packageJson) {
+    const wanted = Object.keys(JSON.parse(packageJson.file.content).dependencies ?? {});
+    const projectPackage = existsSync(join(root, 'package.json')) ? JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')) : {};
+    const have = new Set([...Object.keys(projectPackage.dependencies ?? {}), ...Object.keys(projectPackage.devDependencies ?? {})]);
+    const missing = wanted.filter((name) => !have.has(name));
+    if (missing.length) console.log(`\nInstall the dependencies this example uses: npm install ${missing.join(' ')}`);
+  }
+  if (!values['dry-run']) console.log(`\n${written} file${written === 1 ? '' : 's'} written. Read each file's comments for setup steps.`);
+}
+
+if (isMain(import.meta.url)) await main();