@weft-js/cli 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,16 @@
+MIT License
+
+Copyright (c) 2026 ravonus
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
+documentation files (the "Software"), to deal in the Software without restriction, including without limitation the
+rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit
+persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the
+Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,3 +1,75 @@
-# Temporary Holding Version
+# @weft-js/cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> **Early release (0.1.1).** APIs will change between minor versions.
+
+The `weft` command. It runs an app (`dev`, `build`, `start`), checks it (`check`, `tsc`, `fix`), serves its docs to people
+and agents (`docs`, `agents-md`, `mcp`) and manages plugins (`add`, `plugins`). An app made with `npm create @weft-js`
+already has it.
+
+```bash
+npm install -D @weft-js/cli
+npx weft check
+```
+
+Each problem prints as `file:line:col  CODE severity  why`, with a `fix:` line under it, and the run ends with a count of
+files, errors and warnings.
+
+## Commands
+
+`npx weft help` prints this list.
+
+| Command | What it does |
+|---|---|
+| `check [files…]` | Compiles every component in check mode and reports diagnostics with fixes. `--verbose` says which compiler ran |
+| `tsc` | Type-checks the whole project with inferred props, for CI |
+| `fix [files…]` | Applies the safe autofixes |
+| `doctor` | Which compiler this install uses, whether Rust is around (it's optional), and what live data does on the target |
+| `dev [--port <n>]` | The dev server, for an app with `src/routes` |
+| `build [--runtime node\|bun\|deno] [--preset <p>]` | The production build, into `.output/` |
+| `start [--runtime <r>]` | Runs the build |
+| `db generate [name]`, `db live`, `db listen` | A migration for schema changes; one with change triggers; the change feed as its own process |
+| `routes [--meta]` | The route table; `--meta` adds each route's metadata and H-diagnostics |
+| `test --gate` | The test gate on the diff: fail-before, mutants on changed lines and no weakened tests |
+| `browser <cmd>` | Drives the running app: open, snapshot, act, assert and more (`weft browser help`) |
+| `docs [topic\|code]` | Prints a docs page or a diagnostic (`weft docs props`, `weft docs W014`) |
+| `agents-md [--check]` | Writes AGENTS.md from the installed weft; `--check` exits 1 when it's stale |
+| `map [--stdout]` | Writes `.weft/map.md`: what to call in this app |
+| `tasks`, `run <task>` | Lists commands and project tasks; runs a task from `weft.config.ts` |
+| `add <feature>` | Installs a plugin and wires it into the config; also `tailwind`, `auth`, `db` and `rust` |
+| `plugins [list\|explain\|sync\|audit\|approve]` | Plugins, their slots and permissions |
+| `style find\|explain\|matrix` | Style groups |
+| `tokens` | warp's resolved tokens as DTCG, in `.weft/tokens/` |
+| `lsp` | A language server for editors, with inferred props |
+| `mcp` | These commands as MCP tools, on stdio |
+
+Every command takes `--root <dir>` (the working directory by default) and `--json`. JSON goes to stdout and text for
+people to stderr. Exit codes: 0 ok, 1 errors found (or a stale AGENTS.md under `--check`), 2 a usage or internal error.
+
+## Docs
+
+- `weft docs config`: `weft.config.ts` and every key in it.
+- `weft docs diagnostics`: every code, and which ones the installed weft reports.
+- `weft docs verify`: `weft browser` and the test gate.
+- `weft docs plugins`: writing a plugin.
+
+The source of each page is in [docs/](docs). Adding a diagnostic is in [CONTRIBUTING.md](../../CONTRIBUTING.md).
+
+## A diagnostic
+
+`check`, `tasks` and the MCP tools report the same shape:
+
+```json
+{ "code": "W014", "severity": "error", "owner": "core", "file": "src/App.tsx",
+  "span": [21, 44, 21, 117], "offset": [867, 940],
+  "why": "`.map(p => ({ ...p, … }))` gives every item a new identity on each update…",
+  "fix": { "text": "Keep items stable … or replace only the item that changed." },
+  "project": true,
+  "related": [{ "file": "src/components/ProductList.tsx", "span": [29, 10, 29, 10], "why": "rendered here as a keyed list" }],
+  "docs": "weft docs W014" }
+```
+
+- `span` is 1-based `[line, col, endLine, endCol]`, with columns in UTF-16 units. `offset` is UTF-16 indices into the
+  file's text.
+- `fix.edits` (`{ file, span, offset, text }`) is there when there's a mechanical change, and `fix.safe` says whether
+  `weft fix` applies it without asking.
+- `project: true` marks a result that needed more than one file to find.

package/bin/weft.mjs

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import { main } from '../src/cli.mjs'
+
+// Not `exitCode`: an app's module can leave a pool open, and a finished command must still end.
+const code = await main(process.argv.slice(2))
+// A pipe holds about 64 KB: exiting first would cut off long --json output.
+await Promise.all([process.stdout, process.stderr].map(out => new Promise(done => { out.write('', done) })))
+process.exit(code)

package/docs/async.md

@@ -0,0 +1,40 @@
+# Async data, Boundary and SSR
+
+```tsx
+import { resource, Boundary } from '@weft-js/core'
+
+type User = { name: string }
+
+function Name({ id }: { id: string }) {
+  // `id` is read before the first `await`, so a new id fetches again and aborts the old request.
+  const user = resource(signal => fetch(`/api/users/${id}`, { signal }).then(r => r.json() as Promise<User>))
+  // `pending` is also true on a refetch, while the old value is still here: dim it rather than replace it (X033).
+  return <h1 aria-busy={user.pending ? 'true' : 'false'}>{user.value?.name}</h1>
+}
+
+// The resource is made inside the Boundary (in Name), so the Boundary waits for it.
+export function Profile({ id }: { id: string }) {
+  return (
+    <Boundary pending={<p>Loading…</p>} error={(e, retry) => <button onClick={retry}>Retry</button>}>
+      <Name id={id} />
+    </Boundary>
+  )
+}
+```
+
+- **`resource(fetcher)`** is async `derived`: `.value`, `.pending`, `.error`, `.refresh()`. It re-fetches when what it
+  read before the first `await` changes, and aborts the superseded fetch through `signal`. `derived(async …)` is
+  **W012**.
+- **`<Boundary pending error>`** covers every resource created while its children are built, and every error they
+  throw. A resource made above the `<Boundary>` in the same component isn't below it, and the fallback never shows (X037). The fallback shows after 150 ms and
+  stays at least 400 ms; refetches keep the current content (no flash). `error(e, retry)` gets failed resources and
+  children that throw during render.
+- **`@weft-js/core/ssr`**: `renderToString(() => <App />)` renders what it can now; `await renderToStringAsync(() => <App />)`
+  waits for resources first and puts their values in the page. Pass `{ hydratable: true }` when the client hydrates.
+  `renderToStream(() => <App />, { hydratable: true })` sends `shell` at once, then one chunk per `<Boundary>` as its
+  resources resolve (`chunks`, an async iterable), and `data()` for `hydrate` when they're done. `@weft-js/start`
+  streams this way for you.
+- **`hydrate(() => <App />, el)`** from `@weft-js/core/dom` takes over server HTML without rewriting it. Use it instead of
+  `render` when the HTML came from `@weft-js/core/ssr`.
+- Import only `renderToString`, `renderToStringAsync` and `renderToStream` from `@weft-js/core/ssr`; its other exports are
+  what compiled server code calls.

package/docs/browser.md

@@ -0,0 +1,39 @@
+# Browser values (`@weft-js/core/browser`)
+
+```tsx
+import { state } from '@weft-js/core'
+import { online, visible, lifecycle, media, on, interval } from '@weft-js/core/browser'
+
+export function Toolbar() {
+  const isOnline = online()                                         // Derived<boolean>; server: true
+  const shown = visible()                                           // Derived<boolean>; server: true
+  const page = lifecycle()                                          // 'active' | 'passive' | 'hidden' | 'frozen' | 'terminated'
+  const dark = media('(prefers-color-scheme: dark)', { ssr: false }) // server renders `ssr`
+  const open = state(true)
+  const now = state(Date.now())
+  on(window, 'keydown', e => { if (e.key === 'Escape') open.value = false })  // e: KeyboardEvent
+  interval('1s', () => { now.value = Date.now() })                  // also '500ms', '5m', '1h', or a number of ms
+  return (
+    <p hidden={!open.value}>
+      {isOnline.value ? 'online' : 'offline'}, {dark.value ? 'dark' : 'light'}, {shown.value ? page.value : 'hidden'},
+      {new Date(now.value).toLocaleTimeString()}
+    </p>
+  )
+}
+```
+
+- Call them in setup (a component body, a `defineState` setup, or `createRoot`). Their owner removes them; created
+  anywhere else (module scope, a timer, a handler, after `await`) they throw in dev and are **W051**.
+- Values subscribe on first read and share one listener per event, however many components read them.
+- On the server a value is its `ssr` value (`online`/`visible`: `true`, `lifecycle`: `'active'`). `media` has no
+  default: pass `ssr` in server-rendered components (**W054**). Hydration renders the server value, then the real one.
+- Not `window.addEventListener` / `setInterval` in components (**W050**, with an edit to `on` / `interval`), and not
+  `watch(() => live.value, v => { s.value = v })` (**W056**): read `live.value` where you need it.
+- `tabs.channel('cart', schema)` is a validated `BroadcastChannel` between tabs: `.post(msg)`, `.on(fn)`, `.value`.
+  `state(init, { persist: 'local', sync: 'tabs' })` in a `defineState` keeps a box the same in every tab (S008 without
+  `persist`, or with `session`).
+
+In tests (`@weft-js/core/test`): `await net.offline()`, `net.online()`, `page.hide()`, `page.show()`, `page.blur()`,
+`page.focus()`, `page.freeze()`, `page.resume()`, `page.leave({ persisted })`, `page.restore()`,
+`page.media(query, true)`, `tabs.post(name, msg)`, `tabs.posted(name)`. Each test starts online, visible and focused with every query false. After each test
+@weft-js/core/test fails if anything is still open (**T012**); `leaks()` lists it.

package/docs/config.md

@@ -0,0 +1,93 @@
+# weft.config
+
+`weft.config.ts` is the default. `weft.config.json` and `weft.config.yaml` take the same keys, and `weft check` writes
+`.weft/config.schema.json` for editor completion. In JSON and YAML a plugin is a package name or `[name, options]`, like
+`["@weft-js/warp", { "fields": "classic" }]`; anything that needs a function belongs in `weft.config.ts`. Keep one file:
+two is P010. `weft add <plugin>` installs a plugin and adds it to whichever format you use; `weft add tailwind` sets up Tailwind, `weft add db mysql --layer native` adds a database, and `weft add auth` adds Better Auth to it.
+
+```ts
+import { defineConfig } from '@weft-js/core/config'
+import { dialScript, warp } from '@weft-js/warp/plugin'
+
+export default defineConfig({
+  scope: { write: ['src/**', 'test/**'], forbid: ['.env*'] },
+  tasks: {
+    seed: { run: 'node scripts/seed.mjs', description: 'Load demo products into the dev db', sideEffects: ['db'], env: ['dev'] },
+  },
+  environments: { dev: { url: 'http://localhost:5173' } },
+  site: {        // page metadata defaults: static tags in the server's first response (weft docs meta)
+    name: 'Acme',
+    url: 'https://acme.dev',
+    title: '%s · Acme',
+    description: 'Tools for builders.',
+    locale: 'en_US',
+    image: { url: '/og.png', width: 1200, height: 630 },   // default 'auto': a generated card (weft docs meta); false: none
+    twitter: { card: 'summary_large_image', site: '@acme' },
+    inlineCss: false, // default true: each page carries what its first paint needs; false keeps plain links
+    criticalCss: false, // default true: one hashed sheet plus a first-paint part; false splits by chunk and inlines up to 48 KB
+    criticalKeep: ['theme-x'], // words of selectors a first paint keeps, for classes a head script sets
+    head: dialScript, // raw HTML in every page's head, before the stylesheets: dialScript from @weft-js/warp/plugin restores `setDial(…, { persist: true })` before the first paint
+  },
+  plugins: [warp()],   // plugin factories (@weft-js/core/plugin); a plain `{ name, provides }` entry is data only
+  slots: {},           // names the winner when two plugins provide one slot
+})
+```
+
+| Key | What it holds, and what `weft check` reports |
+|---|---|
+| `scope` | `write`, `read` and `forbid` globs. `forbid` is never compiled or written. `write` will bound `weft fix` (P005, not reported yet) |
+| `tasks` | Project commands for `weft run` and `weft tasks`. P003 duplicate name or command, P004 missing `description` or `sideEffects` |
+| `environments` | Named places the app runs, with a `url` |
+| `test` | `include` (default `**/*.{test,spec}.*`), `lanes`, and `gate: { mutationBudgetSec, maxMutants }` for `weft test --gate` |
+| `check` | `include` and `exclude` globs; `design: false` turns off the D-codes, `routes: false` the route pass (H001–H007, H011–H016, which run the app's loaders once), `props: false` or `'manual'` the prop inference (`weft docs props`) |
+| `plugins` | P116 duplicate name; P100 two entries provide one `one` slot; P115 bad options; P117 impure `contribute()`; P111 code outside the plugin's namespace; P112 AGENTS section over 1 KB; P113 token-namespace or catalog collision; and the codes plugins report themselves (e.g. warp's D010) |
+| `slots` | Which plugin wins a slot two provide. P008 unknown slot id, P009 winner not in `plugins` or not providing the slot |
+| `site` | Page metadata defaults and CSS delivery. P007 `url` not absolute http(s), `title` without `%s`, `locale` not `en_US` style; H001 no `url`; H003 no `description`; H004 a title over 60 or a description over 160 (warnings) |
+| `site.card` | The generated share card's colours and fonts. P007 a colour that isn't `#rrggbb`, a font family that isn't a name. `weft docs meta` has the rest |
+| `site.headers` | Response headers by route pattern |
+| `runtime` | `node`, `bun` or `deno`: what `weft build` targets (`weft docs start`) |
+| `hydration` | `'lazy'` (default): islands load when needed; `'partial'`: every island loads with the page; `'full'`: every route hydrates whole |
+| `rust` | `unions` and `services` for Rust bodies (`weft docs rust`) |
+| `live` | `targets` for a live query's `verify` (`weft docs start`) |
+| `trust` | `'enforce'` (default) or `'warn'`: see P109 and P110 under Plugins |
+| anything else | P007: unknown key or wrong type, with the path |
+
+`package.json` scripts may only alias `weft …` (P002). Project commands live in `tasks`.
+
+## Plugins
+
+A plugin is a factory made with `definePlugin` from `@weft-js/core/plugin`. Its pure `contribute(options, env)` returns what it
+adds: slot providers, `tokens` (`--<namespace>-*`), one AGENTS.md section (≤ 1 KB), catalog entries and diagnostic
+codes in its namespace. Components stay normal imports.
+
+- `weft plugins --json` lists plugins (sorted by name), the slots they provide and bind, permissions and codes.
+- `weft plugins explain <slot> --json` shows config → plugin → module → `.weft/slots/<id>.ts`.
+- `weft plugins sync` (and `weft check`) writes `.weft/slots/<id>.ts`, `.weft/slots.d.ts` and `.weft/tokens/<ns>.css`.
+  Import a slot as `weft:slot/<id>`; its provider loads lazily through `load()`. Unbound: `load()` throws P101.
+- Output is the same for any order of `plugins: []`; array order never decides a binding (P100).
+
+### Permissions and the lock
+
+A plugin declares `permissions` (`fs: { read, write }`, `net`, `env`, `spawn`, `native`). `.weft/plugins.lock.json`
+records what you approved, plus a hash of each installed plugin's files. Commit it.
+
+- **P109** stops `weft check`, `weft dev` and `weft build` when a plugin asks for a permission the lock doesn't give it,
+  or the audit finds it using one it didn't declare.
+- **P110** stops them when an installed plugin's code isn't what the lock recorded, or the lock can't be read.
+- `weft plugins audit --json` shows every plugin against the lock: permissions added and removed, undeclared use with
+  file and line, and the dependencies it didn't read. It exits 1 if anything is blocked.
+- `weft plugins approve <name…>` records those plugins, and `--all` records every plugin and drops ones you removed.
+  With neither it shows what's waiting and writes nothing. If `.gitignore` hides the lock, it fixes that line. In a
+  monorepo, check the ignore file at the repository root yourself.
+- `weft add` never approves. It tells you what the plugin asks for, and the next `weft check` stops until you do.
+- A plugin that asks for nothing and passes the audit needs no approval, and `approve` pins it if you want that.
+- `npm create @weft-js` approves the plugins you pick. It can't hash code before the install, so run
+  `weft plugins approve --all` once to pin them.
+- `trust: 'warn'` in the config turns P109 and P110 into warnings, for a project that vets dependencies some other way.
+
+This shows you changes; it isn't a sandbox. `contribute()` runs when the config loads, before any of this. The audit
+reads the source of the plugin's own package from its entry and its build and server modules, so it won't see code
+that hides itself or code in dependencies (your package manager's lockfile pins those). A workspace package has no
+fixed code to hash, so it's audited on every check instead. A plugin defined in the config file is your own code:
+only its permissions are compared. A plugin is matched to its package by name, so one that claims another's name is
+hashed as that package.

package/docs/deploy.md

@@ -0,0 +1,83 @@
+# Deploy: from `weft build` to a live URL
+
+weft reads what the app uses and says which hosts can run it, before a build and before an account exists. Then it
+writes the host's files and a workflow, and `weft deploy` runs the host's own CLI and reports the URL.
+
+```bash
+weft deploy hosts          # which hosts fit, why not, what each costs, and the suggestion
+weft deploy init           # the suggested host's files, a GitHub workflow, and `deploy` in weft.config.ts
+weft deploy                # a dry run: the build and the exact commands --yes would run
+weft deploy --yes          # a preview deploy; add --prod for production
+```
+
+`weft deploy` without `--yes` runs nothing. An agent runs the dry run on its own, and asks before `--yes`: a deploy
+publishes, and a host may bill for it. Nothing in weft creates a site, an app, a volume or a DNS record; `init` prints the
+one command per host that does, for you to run.
+
+## Which host
+
+| The app uses | Netlify / Vercel | Cloudflare | Fly / Render |
+|---|---|---|---|
+| pages, queries, mutations, forms, `stream()` | ✓ | ✓ | ✓ |
+| `channel`, `sharedState`, `realtime({ share })` | ✗ E001 | ✓ (Durable Objects) | ✓ |
+| `.live({ required })`, `remote()` sidecars | ✗ E002 | ✗ E002 | ✓ |
+| a SQLite file, media uploads | ✗ E003 | ✗ E003 | with a volume or disk (billed) |
+| `changes` without an external listener | degraded (R014) | degraded | ✓ |
+
+The suggestion: Netlify when nothing needs a server that stays up (a CDN with functions is the cheapest and fastest
+host), Cloudflare when channels are all that need one, Fly when data must last on disk, else Fly or Render.
+
+A function host blocked by a channel has a third way, the split: pages on the function host, realtime on a small server.
+It needs a second origin and a cookie both can read, and is designed (research 46 §10), not built.
+
+## `deploy` in weft.config.ts
+
+```ts
+deploy: {
+  target: 'fly',                                       // netlify | vercel | cloudflare | fly | render
+  fly: { app: 'shop', region: 'iad', volume: { name: 'data', sizeGb: 1 } },
+  ci: 'github',                                        // the workflow; false for none
+  branch: 'main',
+  cdn: { proxy: 'cloudflare', images: { provider: 'cloudinary', cloud: 'shop' } },
+}
+```
+
+Names, regions and sizes only. Every token comes from the environment, and one written into the config, a host file or a
+workflow is **E008**. With `deploy.target` set, `weft build` builds for it, and `weft check` reports E001–E003 for it.
+
+A volume or disk mounts at `/app/.data`: SQLite's default `file:.data/app.db` is already there, and uploads go to
+`.data/media` (`WEFT_MEDIA_DIR`).
+
+## What each target writes and runs
+
+| Target | Files | `weft deploy --yes` runs | Reads |
+|---|---|---|---|
+| netlify | `netlify.toml` | `weft build --preset netlify`, `netlify deploy --dir dist --functions .netlify/functions-internal --json` | `NETLIFY_AUTH_TOKEN`, `NETLIFY_SITE_ID` |
+| vercel | `vercel.json` | `weft build --preset vercel`, `vercel deploy --prebuilt` | `VERCEL_TOKEN`, `VERCEL_ORG_ID`, `VERCEL_PROJECT_ID` |
+| cloudflare | `wrangler.toml` | `weft build --preset cloudflare_durable`, `wrangler deploy` in `.output/` | `CLOUDFLARE_API_TOKEN`, `CLOUDFLARE_ACCOUNT_ID` |
+| fly | `fly.toml`, `Dockerfile`, `.dockerignore` | `flyctl deploy --remote-only` (Fly builds the image) | `FLY_API_TOKEN` |
+| render | `render.yaml`, `Dockerfile`, `.dockerignore` | the deploy hook (Render builds the pushed commit) | `RENDER_DEPLOY_HOOK_URL` |
+
+Every target also gets `.github/workflows/weft-deploy.yml`: on push to `branch`, install, `weft check`, then `weft deploy
+--yes --prod`; on a pull request, a preview where the host has them. Add the variables as repository secrets (`gh secret
+set NAME`). Netlify, Vercel and Cloudflare deploy what was built, so build where the host runs: the workflow builds on
+Linux, and a native addon built on a Mac is **E004**.
+
+Each written file starts with `# weft deploy init <target>, sha <hash>`. Change the config and `weft check` reports the
+file as stale (**E006**); `init` rewrites it. A file you edited keeps its old hash, and `init` leaves it alone unless
+`--force`.
+
+## CDN and media
+
+- **Cloudflare in front of a server host** (`cdn.proxy: 'cloudflare'`): proxy the domain to the Fly or Render origin.
+  Hashed assets are already `immutable`, and pages are `private` unless a route caches, so the proxy can't serve one
+  user's page to another. E010: `site.url` is still the host's own domain. E011: a proxy in front of a CDN host.
+- **Cloudinary for uploads** (`cdn.images`): checked (E012 without `@weft-js/plugin-media`, E013 without a cloud or with
+  two), not yet wired: uploads still go to the media server's disk (E014). `?media` imports never need it: the build
+  already makes sized AVIF and WebP files that any CDN serves.
+
+## Codes
+
+E001 sockets on a function host, E002 a held process or a sidecar, E003 data on a disk that doesn't last, E004 a native
+addon deployed from another OS, E005 no target (with the suggestion), E006 a stale host file, E007 an unset variable,
+E008 a written credential, E009 the memory bus on many instances, E010–E014 CDN and media. `weft docs E003` explains one.

package/docs/design.md

@@ -0,0 +1,97 @@
+# Design: tokens, primitives, D-codes
+
+An app with warp has one design language: `@weft-js/warp`'s primitives and components, on warp's tokens. Name what a thing
+is, and the look follows the theme, the dials and the density.
+
+```tsx
+import { Button, Card, Heading, Input, Row, Stack, Text } from '@weft-js/warp'
+
+export function Billing() {
+  return (
+    <Stack as="section" gap="section">
+      <Heading level={1} role="title">Billing</Heading>
+      <Card title="Card on file">
+        <Stack gap="related">
+          <Text subtle>Visa ending 4242</Text>
+          <Input label="Billing email" type="email" />
+          <Row gap="tight" justify="end">
+            <Button emphasis="ghost">Cancel</Button>
+            <Button>Save</Button>
+          </Row>
+        </Stack>
+      </Card>
+    </Stack>
+  )
+}
+```
+
+## Vocabulary
+
+| Thing | Use |
+|---|---|
+| Vertical flow | `Stack gap align divided` |
+| Horizontal cluster | `Row gap justify align wrap reflow` (`reflow` stacks it below a width step) |
+| Columns | `Grid min cols gap` |
+| Side + main | `Split side width at gap` |
+| Measured column | `Center max gutter intrinsic` |
+| Full-screen, one centred child | `Cover`, with `data-part="center"` on the child |
+| Media box | `Frame ratio` |
+| Push to the far end | `Spacer` |
+| Sunken region | `Inset pad` |
+| Raised box | `Card` (warp's surface: `<Surface>` is weft's canvas) |
+| Heading | `Heading level role`: `level` is the outline and picks the look (`title` for h1, `heading` for h2 and h3, `label` below); `role` overrides it |
+| Text | `Text role tone subtle faint inline` |
+| Link | `Link href subtle external`; a bare `<a>` still gets warp's colour |
+
+`gap`: `none hair tight related group section page`, a relationship and not a size: `related` inside a thing, `group`
+between things, `section` between sections. `as` picks the element: `div section article main header footer nav aside
+form ul ol`. There are no breakpoint props, since boxes answer to their container. `@weft-js/core/ds` exports these names as
+constants and types.
+
+`style={{ … }}` and `class` still work; the D-codes below tell you when they leave the system. For a named look of your
+own, use a style group (`weft docs style`), not a class list.
+
+## D-codes
+
+`weft check` reports them. `weft fix` applies the safe autofixes. A fix that changes an element is a suggested edit in
+`fix.edits`; a raw colour has none, since a token follows the theme and the raw value didn't.
+
+Where the app has warp's tokens (`@weft-js/warp` in package.json; headless `@weft-js/warp-core` ships none):
+
+| Code | Catches | Fix |
+|---|---|---|
+| D001 | Raw colour, palette class | A token or `tone` |
+| D002 | Spacing off the scale, or a step by hand | Autofix when exactly a step |
+| D003 | Raw type, radius, shadow | `Heading`, `Text`, radius and elevation tokens; autofix for an exact radius |
+| D004 | Layout spelled out on an element | `Stack`, `Row` (suggested edit) |
+| D040 | The style gate (`data-weft="styled"`) on main content or an h1 | A secondary part, or no marker |
+| D005 | A browser-painted control: `<button>`, `<select>`, `<textarea>`, an input type such as `date`, `number` or `range`, or a `title` tooltip | The warp component (suggested edit for a button) |
+| D006 | One heading level at two roles across the app, or a bare `<hN>` beside `<Heading>` | Match the level's main role (suggested edit at each site) |
+| D007 | A bare `<a href>` | `<Link>`, or `Shell`'s `nav` (suggested edit) |
+
+In every app:
+
+| Code | Catches | Fix |
+|---|---|---|
+| D011 | A literal colour pair below 4.5:1 | Tokens, or better colours |
+| D030 | A form control with no label | `<label>`, `aria-label`, warp's `label` |
+| D031 | A button or link with no name | Text, `aria-label`, warp's `label` |
+| D032 | `<img>` with no `alt` | Describe it; `alt=""` for decoration |
+| D033 | `onClick` on a non-interactive element | `<button type="button">` (suggested edit) |
+| D034 | A control inside a control | One control |
+| D035 | A heading level that jumps | The next level |
+| D036 | Focus ring removed | Remove the override, or add a `focus-visible:` style |
+| D037 | Positive `tabindex` | `0` (autofix) |
+| D038 | Two solid Buttons side by side | One primary action per region |
+| D039 | `<html>` with no `lang` | Set it |
+
+D010 is warp's contrast gate on the seed and tokens. D020–D025 are style groups.
+
+`// weft-allow D001: <reason>` on the line above keeps one site; the reason is required. `check: { design: false }` in
+the config turns these off.
+
+## Tokens
+
+The theme is `warp({ seed, dials, radius, fonts, tokens })`: every value goes through the contrast check. `weft tokens`
+writes the resolved tokens to `.weft/tokens/` as DTCG 2025.10, one file per theme × expression plus a resolver, for
+Figma, Style Dictionary or Terrazzo.

package/docs/fonts.md

@@ -0,0 +1,70 @@
+# Fonts
+
+`@weft-js/text` is the one place an app's fonts are declared. `weft add text` installs it; then:
+
+```ts
+import { defineConfig } from '@weft-js/core/config'
+import { text } from '@weft-js/text'
+
+export default defineConfig({
+  plugins: [
+    text({
+      fonts: {
+        body: { family: 'Inter', src: 'assets/fonts/inter.woff2', fallback: 'Arial', axes: { wght: [100, 900] } },
+        display: { family: 'Fraunces', src: 'assets/fonts/fraunces.woff2', fallback: 'Georgia', weight: 700 },
+      },
+    }),
+  ],
+})
+```
+
+`src` is relative to the project root (woff2, woff, ttf or otf). `fallback` is a system face: Arial, Helvetica, Times New
+Roman, Georgia, Courier New, Verdana. The keys are roles of your choosing; `body` and `display` are preloaded unless a
+face sets `preload: false`, others only with `preload: true`. Other options: `display` (`swap`, `optional`, `fallback`),
+`weight`, `style`, `axes`, and beside `fonts`, `subsets` (default `['latin']`) and `trim` (default `true`).
+
+## What the build does
+
+- Subsets each face per `unicode-range` to hashed woff2 files.
+- Writes the `@font-face` rules, and a `"<Family> Fallback"` face matched to the font's metrics, so the swap doesn't shift
+  layout.
+- Adds the preload links to the page's head, before the first byte.
+- Trims each face, in a build only. Font bytes are what hold back the largest paint on a text hero, so nothing here needs
+  turning on, and neither cut changes how the page looks or which characters it can show:
+  - **Axes.** A custom axis (`SOFT`, `WONK`, `GRAD`…) is pinned to the one value your `font-variation-settings` give it, or
+    to the font's default if the source never sets it. An axis set to two values stays. A value weft can't read from the
+    source (`var()`, a template, an expression) keeps every axis. `wght`, `wdth`, `opsz`, `slnt` and `ital` are never
+    pinned: CSS drives them. A pinned value applies to every use of the face, so a face used both with and without the
+    setting needs the axis declared.
+  - **Characters.** `latin` becomes two files. The core is preloaded: ASCII, common punctuation, and every other latin
+    character in your source. The rest is fetched through `unicode-range` only by a page that shows one of those
+    characters, so text from a database still gets the face, after a fallback-matched swap.
+
+Keep one axis by naming it in `axes`, such as `axes: { SOFT: [0, 100] }`, for values set at runtime or by a dependency's CSS
+(only your own source is read). `trim: false` turns all of it off. `weft dev` always serves whole faces, so an axis you are
+editing responds.
+
+**There is nothing to import.** `@weft-js/core/vite` loads the generated CSS in the client entry (Start) or the page (an HTML app).
+`import 'weft:fonts'` still works and changes nothing. `import { preloads } from 'weft:fonts/preloads'` gives the preload
+list to a custom server.
+
+## Using a face
+
+The build declares faces; it doesn't apply them. Name one in your CSS, with its fallback second:
+
+```css
+body { font-family: "Inter", "Inter Fallback", sans-serif; }
+h1 { font-family: "Fraunces", "Fraunces Fallback", Georgia, serif; }
+```
+
+## Diagnostics
+
+| Code | Catches |
+|---|---|
+| X020 | A hand-written `@font-face` with no `"<Family> Fallback"` face, so the swap shifts layout: declare it in `text({ fonts })` |
+| X021 | `font-display: block` or `auto`, which hide text while the font loads |
+| X022 | A hand-written `@font-face` with no `unicode-range`, or the font build over budget: 100 KB of preloads or 1.5 KB of font CSS (brotli). Preload fewer faces or use fewer weights |
+| X023 | A preload no `@font-face` uses |
+
+The plugin also provides `text.measure`, line breaking for canvas text and exact row heights. It loads only when something
+measures; `measure: 'off'` removes it. See `weft docs surface`.

package/docs/icons.md

@@ -0,0 +1,102 @@
+# Icons
+
+`@weft-js/warp-icons` is weft's own set: 651 original icons in warp's three expression tiers. Outline at quiet and balanced, pixel art on a 16×16 grid at vivid. Each has two forms, hollow (the default) and solid, drawn apart in every tier and shaded with dither.
+
+`weft add icons` installs it and adds `icons()` to the config. warp already depends on it.
+
+## Using one
+
+Three forms, and all three build to the same bytes:
+
+```tsx
+import { CheckIcon } from '@weft-js/warp-icons'
+<CheckIcon />
+
+import Icons from '@weft-js/warp-icons'           // or: import * as Icons
+<Icons.Check />
+
+import { Icon } from '@weft-js/warp'         // or: '@weft-js/warp-icons/icon'
+<Icon name="check" />
+```
+
+Props on any of them:
+
+```tsx
+<CheckIcon />                 // decorative: aria-hidden, focusable="false"
+<CheckIcon label="Saved" />   // role="img" with that name
+<CheckIcon size={24} />       // otherwise warp's icon sizes apply
+<CheckIcon tier="vivid" />    // this tier whatever the page's expression is
+```
+
+An icon you don't use costs nothing. One adds about 164 B of brotli with all tiers in. `sideEffects` lists only CSS, so a named import ships that icon.
+
+## Names and variants
+
+One scheme, generated from the art with its types:
+
+| Export | Pack | `<Icon>` | What it is |
+|---|---|---|---|
+| `BellIcon` | `Icons.Bell` | `name="bell"` | hollow, the default |
+| `BellIconHollow` | `Icons.BellHollow` | | the same, by name |
+| `BellIconSolid` | `Icons.BellSolid` | `solid` | the solid form |
+| `BellIconAction` | `Icons.BellAction` | `action` | has a built-in animation |
+
+The tier is a prop, never a name. An open mark, like an arrow, has a notched badge as its solid, with the mark cut out. Pick it on the sheet: `npm run sheet` in the package writes `contact-sheet.html`, with tier, variant, size, theme and search. `dither-sheet.html` compares the treatments.
+
+## A wrong name
+
+`<Icon name>` is typed, so a bad name is a type error. Untyped code gets the same from the compiler and from `weft check`:
+
+```
+I001 no icon 'chekc', did you mean 'check'?
+```
+
+It fails the build, and so does a variant an icon doesn't have.
+
+## Names that aren't literal
+
+The build follows a name through variables, props, conditionals, maps and component boundaries, and ships what it finds. A name it can't follow, such as one from an API, is legal. `weft check` reports it as I002 with the file and the cost (I003 if the pack itself is passed around). That use then gets one of two things:
+
+- **The pack, as its own chunk.** The default. About 111 KB of brotli for all 651 with every tier in, loaded only by a page that reaches it. A page stays about 1.6 KB bigger than one with no dynamic name.
+- **Single icons from a URL.** `icons({ source: 'https://cdn.example.com/icons/' })`. Nothing of the pack is built; each icon is fetched when first drawn.
+
+`weft icons publish <dir>` writes every icon and variant as static `.svg` files, with a `manifest.json`, for that URL. It writes files and uploads nothing. Action icons aren't published.
+
+A remote icon renders an empty `<svg data-icon data-loading>` of the right size until it arrives, then swaps with no layout shift, and carries `data-failed` if the fetch fails. It stays empty on the server, so SSR needs no network. Elements are allowlisted before they are inserted. A Content-Security-Policy needs that origin in `connect-src`.
+
+## Actions
+
+Five icons have a built-in animation: `trash` (the lid lifts), `bell` (it rings), `check` (it draws on), `refresh` (it spins), `copy` (the sheet stacks).
+
+```tsx
+<Icon name="trash" action />          // hover, focus and press, on the icon or its parent
+<Icon name="refresh" action="on" />   // now; refresh keeps spinning
+<TrashIconAction action="press" />    // 'hover' | 'focus' | 'press' | 'on'
+```
+
+It's CSS alone, and each one's stylesheet ships only if that icon is used (about 230 B of CSS and 50 B of JS, brotli). Outlines ease; pixels move in whole cells, in frames. warp's motion dial and `prefers-reduced-motion` turn it off. An action on another icon is I001.
+
+## Tiers
+
+With no options each icon carries its tiers, and CSS shows the one for the nearest `data-expression`. Switching needs no script, doesn't flash and doesn't change the box. A nested `data-expression` is honoured. The build keeps only the tiers your config and `data-expression` attributes name.
+
+To compile one tier in, with no switch, name it in the config:
+
+<!-- example: skip @weft-js/warp-icons/plugin has no type declarations yet (TS7016 under strict) -->
+```ts
+import { icons } from '@weft-js/warp-icons/plugin'
+
+export default { plugins: [icons({ tier: 'vivid' })] }
+```
+
+`tier` is `quiet`, `balanced` or `vivid`. warp's own icons follow it too. After that a page's `data-expression` no longer changes icons: run `weft plugins sync` if you change it.
+
+## Pixel sizes
+
+The pixel tier is exact at 16, 32 and 48. At 20 and 24 a 1× screen rounds cells unevenly; a 2× screen draws 24 evenly. Prefer 16 or 32 at vivid.
+
+## Styling
+
+A solid cuts its marks with `--warp-icon-knock`, which defaults to `Canvas`. On a coloured surface, like a solid button, set it to that surface's colour.
+
+Icons are `currentColor`. The weft stroke, the one that says what the icon means, is `[data-w]`, so `svg [data-w] { stroke: var(--warp-color-accent-text) }` colours it. Its weight is `--warp-icon-weft`.