@weft-js/cli 0.1.1 → 0.1.3

package/docs/async.md

@@ -6,16 +6,26 @@ 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>
+  // A new id refetches and aborts the old request.
+  const user = resource(signal =>
+    fetch(`/api/users/${id}`, { signal })
+      .then(r => r.json() as Promise<User>),
+  )
+  // On a refetch, dim the old value 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.
+// Name makes the resource inside the Boundary, which waits for it.
 export function Profile({ id }: { id: string }) {
   return (
-    <Boundary pending={<p>Loading…</p>} error={(e, retry) => <button onClick={retry}>Retry</button>}>
+    <Boundary
+      pending={<p>Loading…</p>}
+      error={(e, retry) => <button onClick={retry}>Retry</button>}
+    >
       <Name id={id} />
     </Boundary>
   )

package/docs/browser.md

@@ -2,20 +2,34 @@
 
 ```tsx
 import { state } from '@weft-js/core'
-import { online, visible, lifecycle, media, on, interval } from '@weft-js/core/browser'
+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 isOnline = online() // Derived<boolean>; server: true
+  const shown = visible() // Derived<boolean>; server: true
+  // 'active' | 'passive' | 'hidden' | 'frozen' | 'terminated'
+  const page = lifecycle()
+  // Server renders `ssr`.
+  const dark = media('(prefers-color-scheme: dark)', { ssr: false })
   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
+  on(window, 'keydown', e => { // e: KeyboardEvent
+    if (e.key === 'Escape') open.value = false
+  })
+  // Also '500ms', '5m', '1h', or a number of ms.
+  interval('1s', () => { now.value = Date.now() })
   return (
     <p hidden={!open.value}>
-      {isOnline.value ? 'online' : 'offline'}, {dark.value ? 'dark' : 'light'}, {shown.value ? page.value : 'hidden'},
+      {isOnline.value ? 'online' : 'offline'}{', '}
+      {dark.value ? 'dark' : 'light'}{', '}
+      {shown.value ? page.value : 'hidden'},
       {new Date(now.value).toLocaleTimeString()}
     </p>
   )

package/docs/config.md

@@ -12,24 +12,41 @@ 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'] },
+    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)
+  // Metadata defaults: static tags in the first response.
+  // See weft docs meta.
+  site: {
     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
+    // Default 'auto': generated card; false: none (weft docs meta).
+    image: { url: '/og.png', width: 1200, height: 630 },
     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
+    // Default true: first-paint CSS. False keeps plain links,
+    // as a strict CSP needs (D012).
+    inlineCss: false,
+    // Default true: one hashed sheet and first-paint CSS.
+    // False splits by chunk and inlines up to 48 KB.
+    criticalCss: false,
+    // Selector words to keep for classes set by a head script.
+    criticalKeep: ['theme-x'],
+    // Raw HTML before stylesheets on every page. dialScript from
+    // @weft-js/warp/plugin restores setDial(…, { persist: true })
+    // before the first paint.
+    head: dialScript,
   },
-  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
+  // Plugin factories; plain { name, provides } entries are data.
+  plugins: [warp()],
+  // Names the winner when two plugins provide one slot.
+  slots: {},
 })
 ```
 
@@ -91,3 +108,16 @@ that hides itself or code in dependencies (your package manager's lockfile pins
 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.
+
+
+## Indexing intent
+
+For a site intended for public search, declare
+`build: { audit: { indexing: 'public' } }`. L024 then fails the build or audit if
+robots metadata or an HTTP X-Robots-Tag header says noindex. `private` or the
+backward-compatible `auto` leaves this a warning; neither removes a directive.
+After deployment, run `weft audit --url https://your-site.example --indexing public`:
+a host or proxy may add a header that a local build cannot see. Preserve intentional
+preview/private exclusions. A noindex finding is an indexing policy issue, not
+chat-agent traffic; use a clean profile before attributing other audit failures
+to application or framework code.

package/docs/core.md

@@ -0,0 +1,30 @@
+# Core entrypoints
+
+Import application APIs such as `state`, `derived`, `watch`, `context` and `createRoot`
+from `@weft-js/core`. Use the `State<T>` and `Derived<T>` types for boxes.
+
+`memo(fn)` returns a cached accessor, `() => T`. Call it to read the current value.
+It tracks the same dependencies as `derived(fn)` and recomputes when they change.
+
+```ts
+import { memo, state } from '@weft-js/core'
+
+const count = state(1)
+const twice = memo(() => count.value * 2)
+console.log(twice()) // 2
+```
+
+Compiler output and framework integrations use `@weft-js/core/internal`. This
+entrypoint re-exports the runtime's existing implementations and shares its graph,
+box constructors and server state. It does not create another runtime instance.
+
+The root no longer exports `DIRTY`, `rt`, `listener`, `read`, `reach`, `clean`,
+`setFlat`, `flat`, `collecting`, `runMounts`, `setKeyed`, `NONE`, `stats`,
+`devComponent` or `Box`. Integrations that require these use the internal entrypoint.
+Applications create boxes with `state` rather than constructing `Box`.
+
+`hole`, `localProps` and `restOf` also live under the internal entrypoint. `hole`
+tracks a renderer's child binding. `localProps` implements writable prop locals.
+`restOf` takes the prop snapshot used by a compiled native-element spread. These
+are compiler and renderer contracts, rather than application APIs. The `hole`
+export of `@weft-js/core/ssr` is a separate server-rendering helper.

package/docs/deploy.md

@@ -4,10 +4,14 @@ weft reads what the app uses and says which hosts can run it, before a build and
 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
+# Host fit, cost and suggestion
+weft deploy hosts
+# Host files, GitHub workflow and deploy config
+weft deploy init
+# Dry run: build and commands that --yes would run
+weft deploy
+# Preview; add --prod for production
+weft deploy --yes
 ```
 
 `weft deploy` without `--yes` runs nothing. An agent runs the dry run on its own, and asks before `--yes`: a deploy
@@ -34,11 +38,19 @@ It needs a second origin and a cookie both can read, and is designed (research 4
 
 ```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
+  // netlify | vercel | cloudflare | fly | render
+  target: 'fly',
+  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' } },
+  cdn: {
+    proxy: 'cloudflare',
+    images: { provider: 'cloudinary', cloud: 'shop' },
+  },
 }
 ```
 
@@ -81,3 +93,16 @@ file as stale (**E006**); `init` rewrites it. A file you edited keeps its old ha
 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.
+
+
+## Indexing intent
+
+For a site intended for public search, declare
+`build: { audit: { indexing: 'public' } }`. L024 then fails the build or audit if
+robots metadata or an HTTP X-Robots-Tag header says noindex. `private` or the
+backward-compatible `auto` leaves this a warning; neither removes a directive.
+After deployment, run `weft audit --url https://your-site.example --indexing public`:
+a host or proxy may add a header that a local build cannot see. Preserve intentional
+preview/private exclusions. A noindex finding is an indexing policy issue, not
+chat-agent traffic; use a clean profile before attributing other audit failures
+to application or framework code.

package/docs/design.md

@@ -4,7 +4,15 @@ An app with warp has one design language: `@weft-js/warp`'s primitives and compo
 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'
+import {
+  Button,
+  Card,
+  Heading,
+  Input,
+  Row,
+  Stack,
+  Text,
+} from '@weft-js/warp'
 
 export function Billing() {
   return (
@@ -85,13 +93,14 @@ In every app:
 | 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.
+D010 is warp's contrast gate on the seed and tokens: `weft build` stops on it. D012 is a CSP that blocks the inlined CSS. 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`
+The theme is `warp({ seed, dials, fields, radius, fonts, tokens })`: every value goes through the contrast check. `weft docs theme`
+has worked looks and the button channels. `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/entrypoints.md

@@ -0,0 +1,79 @@
+# Core and Start entrypoints
+
+These paths are retained package exports. Node tooling must not enter a browser bundle.
+The snapshots cover export paths, targets and conditions, not names or signatures.
+
+## @weft-js/core
+
+- `@weft-js/core`: Application reactive runtime and components.
+- `@weft-js/core/internal`: Compiler and renderer contract; shares the runtime graph, not an app API.
+- `@weft-js/core/keyed`: Keyed state helpers.
+- `@weft-js/core/jsx-runtime`: JSX types for compiler output; types only.
+- `@weft-js/core/dom`: Browser DOM rendering and hydration; other helpers serve compiler output.
+- `@weft-js/core/ssr`: Server rendering and compiler helpers.
+- `@weft-js/core/head`: Browser route metadata updates.
+- `@weft-js/core/test`: Test utilities; requires the test peers.
+- `@weft-js/core/test/plugins`: Plugin conformance test suites; browser layout tests need a browser.
+- `@weft-js/core/persist`: State persistence.
+- `@weft-js/core/history`: State history.
+- `@weft-js/core/sync`: State synchronization.
+- `@weft-js/core/interaction`: Interaction state.
+- `@weft-js/core/browser`: Browser APIs and browser state.
+- `@weft-js/core/style`: Style groups and styling helpers.
+- `@weft-js/core/ds`: Design system primitives.
+- `@weft-js/core/media`: Media components and helpers.
+- `@weft-js/core/shape`: Shape components and helpers.
+- `@weft-js/core/text`: Text components and helpers.
+- `@weft-js/core/surface`: Surface components and helpers.
+- `@weft-js/core/media-probe`: Media probing for tooling; Node entry.
+- `@weft-js/core/client`: Client type declarations only; no runtime condition.
+- `@weft-js/core/style/matrix`: Style matrix tooling; Node entry.
+- `@weft-js/core/hydration`: Hydration tooling; Node entry.
+- `@weft-js/core/markup`: Shared markup helpers and types.
+- `@weft-js/core/node-purge`: Node cache purge tooling.
+- `@weft-js/core/hmr`: Compiler-generated development hot updates.
+- `@weft-js/core/plugin`: Plugin declarations and runtime helpers.
+- `@weft-js/core/devtools`: Development tools.
+- `@weft-js/core/agent`: In-page development agent; requires testing peers.
+- `@weft-js/core/config`: Configuration declarations and runtime helpers.
+- `@weft-js/core/vite`: Vite plugin; Node tooling.
+- `@weft-js/core/compiler`: Compiler binding; Node tooling and native or WASM compiler.
+
+## @weft-js/start
+
+- `@weft-js/start`: Application server functions, forms and routing APIs.
+- `@weft-js/start/data`: Server function and data primitives.
+- `@weft-js/start/derive`: Server-side page metadata derivation.
+- `@weft-js/start/media`: Media schema and asset types.
+- `@weft-js/start/hub`: Realtime hub and topics; server.
+- `@weft-js/start/live`: Streams and live queries.
+- `@weft-js/start/bus`: Realtime bus interfaces.
+- `@weft-js/start/changes`: Database change feeds; server.
+- `@weft-js/start/changes-sql`: SQL for database change triggers; server tooling.
+- `@weft-js/start/live-target`: Live target capability checks; Node tooling.
+- `@weft-js/start/listen`: Database change listener; server.
+- `@weft-js/start/verify`: Live verification; server tooling.
+- `@weft-js/start/bus/postgres`: Postgres realtime bus; server, requires Postgres.
+- `@weft-js/start/list`: List queries and helpers.
+- `@weft-js/start/list/drizzle`: Drizzle list integration; requires Drizzle.
+- `@weft-js/start/channel`: Realtime channels.
+- `@weft-js/start/share`: Shared state.
+- `@weft-js/start/db`: Drizzle schema helpers; requires Drizzle.
+- `@weft-js/start/db/core`: Database interfaces and core helpers.
+- `@weft-js/start/db/sqlite`: SQLite database adapter.
+- `@weft-js/start/db/postgres`: Postgres database adapter; requires Postgres driver.
+- `@weft-js/start/db/mysql`: MySQL database adapter; requires MySQL driver.
+- `@weft-js/start/auth`: Authentication provider interface.
+- `@weft-js/start/auth/better-auth`: Better Auth integration; requires Better Auth.
+- `@weft-js/start/auth/drizzle`: Drizzle authentication integration; requires Drizzle.
+- `@weft-js/start/extension`: Server extension contract.
+- `@weft-js/start/client`: Client application bootstrap; browser.
+- `@weft-js/start/server`: Server application rendering and request handling.
+- `@weft-js/start/vite`: Start Vite plugin; Node tooling.
+- `@weft-js/start/routes`: Route manifest tooling.
+- `@weft-js/start/og`: Open Graph image tooling; server.
+- `@weft-js/start/app`: Development and build application tooling; Node.
+- `@weft-js/start/inspect`: Route metadata inspection; Node tooling.
+- `@weft-js/start/contract`: Server function contract generation; Node tooling.
+- `@weft-js/start/rust`: Rust remote function support.
+- `@weft-js/start/sidecar`: Rust sidecar supervisor; Node tooling.

package/docs/fonts.md

@@ -10,8 +10,18 @@ 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 },
+        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,
+        },
       },
     }),
   ],

package/docs/icons.md

@@ -12,20 +12,24 @@ Three forms, and all three build to the same bytes:
 import { CheckIcon } from '@weft-js/warp-icons'
 <CheckIcon />
 
-import Icons from '@weft-js/warp-icons'           // or: import * as Icons
+// Or: import * as Icons
+import Icons from '@weft-js/warp-icons'
 <Icons.Check />
 
-import { Icon } from '@weft-js/warp'         // or: '@weft-js/warp-icons/icon'
+// Or import from '@weft-js/warp-icons/icon'.
+import { Icon } from '@weft-js/warp'
 <Icon name="check" />
 ```
 
 Props on any of them:
 
 ```tsx
-<CheckIcon />                 // decorative: aria-hidden, focusable="false"
+// Decorative: aria-hidden, focusable="false"
+<CheckIcon />
 <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
+// This tier regardless of the page's expression.
+<CheckIcon tier="vivid" />
 ```
 
 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.
@@ -41,7 +45,7 @@ One scheme, generated from the art with its types:
 | `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.
+The tier is a prop, never a name. Hollow and solid describe the object: an open mark like an arrow is an outlined arrow in hollow and a filled one in solid, never a badge. 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
 
@@ -69,9 +73,11 @@ A remote icon renders an empty `<svg data-icon data-loading>` of the right size
 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
+// Hover, focus and press on the icon or its parent.
+<Icon name="trash" action />
 <Icon name="refresh" action="on" />   // now; refresh keeps spinning
-<TrashIconAction action="press" />    // 'hover' | 'focus' | 'press' | 'on'
+// 'hover' | 'focus' | 'press' | 'on'
+<TrashIconAction action="press" />
 ```
 
 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.

package/docs/lists.md

@@ -11,7 +11,9 @@
   every row re-runs on every change (1 DOM write, hundreds of re-runs). Replace only what changed:
 
   ```ts
-  products.value = products.value.map(p => (p.id === id ? { ...p, price } : p))
+  products.value = products.value.map(p =>
+    p.id === id ? { ...p, price } : p,
+  )
   ```
 
   The compiler sees this inside one file; `weft check` follows the box through props into other files.

package/docs/meta.md

@@ -11,7 +11,11 @@ on what the reader gets, from what is on the page:
 ```tsx
 import type { Meta } from '@weft-js/start'
 
-export const meta: Meta = { title: 'Pricing', description: 'Three plans, billed monthly, and what each one includes.' }
+export const meta: Meta = {
+  title: 'Pricing',
+  description: 'Three plans, billed monthly, ' +
+    'and what each one includes.',
+}
 ```
 
 On a param route, build it from `data` and `params`, so each page says what it is:
@@ -22,8 +26,14 @@ On a param route, build it from `data` and `params`, so each page says what it i
 import { notFound, type LoadArgs, type Meta } from '@weft-js/start'
 import { getUser } from '#/server/users'
 
-export const load = async ({ params }: LoadArgs<'/users/[id]'>) => (await getUser.fetch({ id: params.id })) ?? notFound()
-export const meta: Meta<typeof load> = ({ data }) => ({ title: data.name, description: data.bio })
+export const load = async ({ params }: LoadArgs<'/users/[id]'>) => {
+  const user = await getUser.fetch({ id: params.id })
+  return user ?? notFound()
+}
+export const meta: Meta<typeof load> = ({ data }) => ({
+  title: data.name,
+  description: data.bio,
+})
 ```
 
 `meta` is plain data: it runs once per request after the loaders and before the first byte. It can't read a box (H006)

package/docs/plugins.md

@@ -8,8 +8,8 @@ own diagnostics and `weft add` steps. It uses only what any plugin can use, and
 
 ```
 packages/pay/                     packages/pay/ (`src/stripe.ts`)
-  plugin.mjs       the manifest     plugin.mjs       a `pay.rail` provider
-  src/index.ts     client-safe      src/index.ts     stripeRail(options)
+  plugin.mjs       the manifest     plugin.mjs  `pay.rail` provider
+  src/index.ts     client-safe      src/index.ts  stripeRail(options)
   src/server.ts    the ledger
   src/test.ts      fakePay, payRailSuite
   src/checks.mjs   PAY-codes
@@ -24,8 +24,12 @@ A rail is how a payment happens. `fakePay` is a second rail, which is how you kn
 
 ```js
 export const pay = definePlugin({
-  name: '@weft-js/pay', version: '0.1.0', weft: '*', namespace: 'PAY', permissions: {},
-  contribute: () => ({ provides: [...], diagnostics, check, docs, setup, agents, catalog, map }),
+  name: '@weft-js/pay',
+  version: '0.1.0', weft: '*', namespace: 'PAY', permissions: {},
+  contribute: () => ({
+    provides: [...], diagnostics, check, docs, setup,
+    agents, catalog, map,
+  }),
 })
 ```
 
@@ -42,8 +46,18 @@ imports lazily, on that side only. That's why an app that doesn't use a plugin c
 Pay provides `server.extension`, the slot for anything that needs a server presence:
 
 ```js
-provide(defineSlot({ id: 'server.extension', version: 1, cardinality: 'keyed', sides: ['server'] }),
-  { key: 'pay', sides: { server: { module: '@weft-js/pay/server', export: 'extension' } } })
+provide(
+  defineSlot({
+    id: 'server.extension', version: 1,
+    cardinality: 'keyed', sides: ['server'],
+  }),
+  {
+    key: 'pay',
+    sides: { server: {
+      module: '@weft-js/pay/server', export: 'extension',
+    } },
+  },
+)
 ```
 
 The key is the mount: `/_weft/x/pay/...`. A keyed provider also needs `src/<key>.server.ts`, the app's own configuration, and
@@ -82,7 +96,11 @@ and a good template for a provider.
 `diagnostics` declares each code: severity, what it catches, the fix. `check` finds them:
 
 ```js
-check: { include: ['src/**/*.{ts,tsx}'], run: ctx => import('./src/checks.mjs').then(c => c.run(ctx)) }
+check: {
+  include: ['src/**/*.{ts,tsx}'],
+  run: ctx => import('./src/checks.mjs')
+    .then(c => c.run(ctx)),
+}
 ```
 
 `run(ctx)` gets `files`, `read`, `exists`, `jsx`, `slots`, and returns findings: `{ code, file, start, end, why, help?, fix? }`.
@@ -108,9 +126,14 @@ sees what a user sees. It's imported from `@weft-js/pay/test`, since core can't
 ```js
 export const setup = {
   with: ['@weft-js/pay/stripe'],     // added too
-  needs: ['db', 'auth'],                 // refused, with nothing changed, until they're there
+  // Refused without changes until these are present.
+  needs: ['db', 'auth'],
   run({ engine, layer, read }) {
-    return { files: {...}, edits: {...}, env: { STRIPE_SECRET_KEY: 'sk_test_placeholder' }, next: ['...'] }
+    return {
+      files: {...}, edits: {...},
+      env: { STRIPE_SECRET_KEY: 'sk_test_placeholder' },
+      next: ['...'],
+    }
   },
 }
 ```

package/docs/props.md

@@ -7,10 +7,21 @@ Leave a component's props unannotated. weft infers them from its callers and its
 
 ```tsx
 function Row(props) {
-  return <li><button type="button" onClick={props.onPick}>{props.label.toUpperCase()}</button></li>
+  const { label, onPick } = props
+  return (
+    <li>
+      <button type="button" onClick={onPick}>
+        {label.toUpperCase()}
+      </button>
+    </li>
+  )
 }
 export default function List() {
-  return <ul><Row label="One" onPick={() => console.log('picked one')} /></ul>
+  return (
+    <ul>
+      <Row label="One" onPick={() => console.log('picked one')} />
+    </ul>
+  )
 }
 ```
 

package/docs/reactivity.md

@@ -0,0 +1,26 @@
+# Reading reactive values
+
+`state(initial)` returns a writable `State<T>`. Read or assign its `.value`.
+`derived(fn)` returns a read-only `Derived<T>`. Read `.value` to evaluate it and
+track its dependencies.
+
+Use `memo(fn)` when a caller needs an accessor instead of a box:
+
+```ts
+import { derived, memo, state } from '@weft-js/core'
+
+const count = state(1)
+const doubled = derived(() => count.value * 2)
+const readDoubled = memo(() => count.value * 2)
+
+console.log(doubled.value, readDoubled()) // 2, 2
+```
+
+Both forms cache their result and refresh it when a dependency changes. `memo`
+returns a function, so call it; it has no `.value` property. The compiler also uses
+this accessor form to cache component children.
+
+For side effects, `watch(source, callback)` tracks reads in `source`. Keep the
+source pure and give reactive work an owner with a component or `createRoot`.
+Graph tracking, mount queues and renderer helpers belong to
+`@weft-js/core/internal`; application code uses the public lifecycle APIs.