create-bascik 1.0.0-rc.5 → 1.0.0-rc.7

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,222 @@
+---
+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 --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              # project checks, plus the per-file checks when @bascik/language-server is installed
+bascik --check --fix        # also rewrite fixable findings (needs @bascik/language-server)
+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   # the per-file checks on their own (bascik --check already runs them)
+```
+
+`bascik --check` and the linter are not two overlapping tools. `bascik --check` answers project questions (duplicate routes, unused components, config), and the linter answers per-file questions (attribute typos, CSS that cannot be scoped). `bascik --check` runs the linter too, so use it, and reach for the linter alone only on a folder outside the project.
+
+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` (project and per-file checks) and, for component folders outside the project, the linter, then summarizes each step. 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 the linter on component folders outside the project, 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,347 @@
+#!/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();