@close-by/clay 0.2.6 → 0.2.8

package/docs/getting-started.md

@@ -0,0 +1,278 @@
+# Getting started
+
+## Requirements
+
+- [Bun](https://bun.sh/) 1.1+ (runtime for `clay` and app code)
+- Node-compatible OS (macOS / Linux / WSL)
+- For local tarball installs: npm (links co-installed `file:` packages; Bun may try the registry for rewritten versions)
+
+## Outside the monorepo
+
+Consumers import `@close-by/clay` and run apps with the `clay` binary from `@close-by/clay-cli`. The CLI ships prebuilt Vite assets (`client-dist`); you do **not** need `@close-by/clay-client` or a monorepo `build:client`.
+
+Walkthrough (tasks list → two pages + `--app`): [Sample app](./tutorial.md).
+
+### From local packs (this repo)
+
+```bash
+# In the Clay checkout:
+bun install
+bun run pack:publishable   # build:client + bun pm pack → dist-pack/*.tgz
+# workspace:* is rewritten to real versions inside each tarball
+
+# In your app directory:
+npm install \
+  /path/to/clay/dist-pack/close-by-clay-core-0.1.0.tgz \
+  /path/to/clay/dist-pack/close-by-clay-auth-0.1.0.tgz \
+  /path/to/clay/dist-pack/close-by-clay-compiler-0.1.0.tgz \
+  /path/to/clay/dist-pack/close-by-clay-persistence-file-0.1.0.tgz \
+  /path/to/clay/dist-pack/close-by-clay-components-0.1.0.tgz \
+  /path/to/clay/dist-pack/close-by-clay-server-0.1.0.tgz \
+  /path/to/clay/dist-pack/close-by-clay-0.1.0.tgz \
+  /path/to/clay/dist-pack/close-by-clay-cli-0.1.0.tgz
+```
+
+Install **all** runtime tarballs together so `@close-by/clay` and `@close-by/clay-*@0.1.0` resolve from the co-installed packs (they are not on the public registry yet).
+
+### When published to npm
+
+```bash
+bun add @close-by/clay-cli @close-by/clay
+# transitive: core, components, server, persistence-file
+# optional: bun add @close-by/clay-auth
+```
+
+### Publishing to npm (maintainers)
+
+Runtime packages are scoped (`@close-by/clay` and `@close-by/clay-*`) and public (`publishConfig.access: public`). Publish **in dependency order** so the registry can resolve rewritten versions:
+
+1. `@close-by/clay-core`
+2. `@close-by/clay-auth`
+3. `@close-by/clay-compiler`
+4. `@close-by/clay-persistence-file`
+5. `@close-by/clay-components`
+6. `@close-by/clay-server`
+7. `@close-by/clay`
+8. `@close-by/clay-cli`
+
+```bash
+# In the Clay checkout:
+bun install
+npm login                          # once; needs rights on the @close-by org
+
+bun run publish:dry                # pack + validate + npm publish --dry-run (no upload)
+bun run publish:npm                # pack + validate + real npm publish (same order)
+# Re-run is safe: versions already on npm are skipped.
+```
+
+Equivalent manual flow from packed tarballs:
+
+```bash
+bun run pack:publishable
+npm publish ./dist-pack/close-by-clay-core-0.1.0.tgz --access public
+npm publish ./dist-pack/close-by-clay-auth-0.1.0.tgz --access public
+npm publish ./dist-pack/close-by-clay-compiler-0.1.0.tgz --access public
+npm publish ./dist-pack/close-by-clay-persistence-file-0.1.0.tgz --access public
+npm publish ./dist-pack/close-by-clay-components-0.1.0.tgz --access public
+npm publish ./dist-pack/close-by-clay-server-0.1.0.tgz --access public
+npm publish ./dist-pack/close-by-clay-0.1.0.tgz --access public
+npm publish ./dist-pack/close-by-clay-cli-0.1.0.tgz --access public
+```
+
+`publish:dry` checks each tarball for rewritten deps (no `workspace:*`), `license` / README / LICENSE, CLI `bin` + `client-dist`, `@close-by/clay` `docs/` (via `prepack` → `scripts/sync-docs.ts`), then runs `npm publish --dry-run`. `publish:npm` looks up each `name@version` on the registry and **skips** if it is already published (resume after a partial failure). Use `--skip-pack` to reuse an existing `dist-pack/`: `bun scripts/publish-from-pack.ts --dry-run --skip-pack`.
+
+After install, version-matched docs live at `node_modules/@close-by/clay/docs/` (import paths like `@close-by/clay/docs/api.md` with Bun, or `resolveClayDocsDir` from `@close-by/clay/docs-dir`).
+
+### Run
+
+```typescript
+// hello.ts
+import { ui } from '@close-by/clay';
+
+export default function () {
+  ui.label('Hello Clay');
+  ui.button('Ping', { onClick: () => ui.notify('hi', 'success') });
+}
+```
+
+```bash
+bunx clay hello.ts   # → http://localhost:3000 (opens browser)
+```
+
+`ui.run(() => { … })` also works; CLI `-p` / `--title` / `--app` apply when the entry uses a default export or `ui.page` and lets the CLI start the server.
+
+## Three-line app (`clay`) — monorepo
+
+```typescript
+// hello.ts
+import { ui } from '@close-by/clay';
+
+ui.run(() => {
+  ui.label('Hello Clay');
+  ui.button('Ping', { onClick: () => ui.notify('hi', 'success') });
+});
+```
+
+**This monorepo:** build the client once (also copies assets into `@close-by/clay-cli` for packaging), then use the workspace CLI:
+
+```bash
+bun install
+bun run build:client          # Vite → packages/client/dist (+ copy → packages/cli/client-dist)
+bun run clay hello.ts        # → http://localhost:3000 (opens browser)
+```
+
+The CLI prefers `packages/cli/client-dist` when present, otherwise falls back to `packages/client/dist` so local `bun run clay` / `demo:cli` work after a single `build:client`.
+
+Or a default export (CLI registers `/` and starts the server for you):
+
+```typescript
+import { ui } from '@close-by/clay';
+
+export default function () {
+  ui.label('Hello Clay');
+}
+```
+
+```bash
+bun run clay hello.ts --port 4000
+```
+
+### Multi-page SPA with shell
+
+```bash
+bun run clay ./pages --app --title "My App"
+# loadPages + ui.run({ app: { title, nav: navFromPages() } })
+```
+
+| Flag | Meaning |
+|------|---------|
+| `-p, --port` | Port (default `3000`) |
+| `-t, --title` | HTML / shell title |
+| `--app` | Dashboard shell + nav from discovered pages |
+| `--no-open` | Do not open the browser |
+| `--reload` | Restart on file changes (`bun --watch`); opens the browser once; prints `↻ clay: reloading…` and re-imports pages (clears `require.cache`) |
+| `--reactive-let` | Enable compile-time reactive `let` Bun loader (**off** by default; still needs `// @clay-reactive` or `"use reactive";` in source) |
+| `--no-reactive-let` | Disable the reactive-let plugin (default) |
+
+See [`docs/reactive-let.md`](./reactive-let.md) for `ui.state` / `ui.auto` (recommended), `ui.label(() => …)`, and the opt-in Phase 2 `let` transform.
+
+**Complex pages (Orders-scale):** use Phase 1 `ui.state` + `ui.auto`, or opt-in reactive `let` with the [region decision table](./reactive-let.md#decision-table-complex-pages) — who wraps `ui.auto` for top-level helpers, widget callbacks, inline UI, and handlers.
+
+For production deployment, auth, and server exposure, see [Production & security](./production.md).
+
+## Install and run the demo
+
+```bash
+bun install
+bun run build:client   # builds packages/client → dist, copies into @close-by/clay-cli
+bun run demo           # starts apps/demo on :4000
+# or
+bun run demo:cli       # same examples via `clay … --app`
+```
+
+Or in one step:
+
+```bash
+bun run dev
+```
+
+Open:
+
+- http://localhost:4000 — home with links to examples
+- http://localhost:4000/examples/counter
+- http://localhost:4000/examples/todo
+- http://localhost:4000/examples/form-demo
+- http://localhost:4000/examples/auth
+
+| Script | What it does |
+|--------|----------------|
+| `bun run build:client` | Vite production build of the React client + copy into `@close-by/clay-cli` |
+| `bun run pack:publishable` | `build:client` + pack `@close-by/clay-core` … `@close-by/clay` … `@close-by/clay-cli` → `dist-pack/` |
+| `bun run publish:dry` | Pack + validate tarballs + `npm publish --dry-run` (no registry upload) |
+| `bun run publish:npm` | Pack + validate + `npm publish` in order (requires `npm login`) |
+| `bun run demo` | Start demo server (`main.ts`; expects client already built) |
+| `bun run demo:cli` | Start demo via `clay apps/demo/src/examples --app` (loads `_run.ts` auth config) |
+| `bun run clay …` | CLI runtime (`@close-by/clay-cli`) |
+| `bun run dev` | Build client, then start demo |
+| `bun test` | Run package tests |
+
+### Packaging notes (maintainers)
+
+- Source packages keep `workspace:*` for the monorepo; `bun pm pack` / publish rewrites them to the package version.
+- `@close-by/clay-client` is **private**; only its Vite `dist` is copied into `@close-by/clay-cli` (`copy-client` / CLI `prepack`, also invoked by `build:client`).
+- Root stays `private: true`. Each runtime package ships `license`, `README.md`, `LICENSE`, and `publishConfig.access: public`.
+- Publish order: `core` → `auth` → `compiler` → `persistence-file` → `components` → `server` → `ui` → `cli` (see **Publishing to npm** above).
+
+## Library mode (multi-page entrypoint)
+
+Create a page file and an entrypoint:
+
+```typescript
+// pages/counter.ts
+import { ui } from '@close-by/clay';
+
+export const pageMeta = { label: 'Counter', icon: 'hash', order: 10 };
+
+ui.page('/counter', () => {
+  let count = 0;
+  const label = ui.label(`Count: ${count}`).classes('text-2xl');
+
+  ui.row(() => {
+    ui.button('-', {
+      variant: 'destructive',
+      onClick: () => {
+        count--;
+        label.setText(`Count: ${count}`);
+      },
+    });
+    ui.button('+', {
+      onClick: () => {
+        count++;
+        label.setText(`Count: ${count}`);
+      },
+    });
+  }, { gap: 2 });
+});
+```
+
+```typescript
+// main.ts
+import { ui } from '@close-by/clay';
+
+await ui.loadPages(new URL('./pages', import.meta.url));
+
+ui.run({
+  port: 4000,
+  title: 'My App',
+  css: './globals.css', // optional theme overrides
+  app: {
+    title: 'My App',
+    nav: ui.navFromPages(),
+  },
+});
+```
+
+Point `clientDir` with `resolveClayClientDir()` (or omit it — `ui.run` does the same) instead of hardcoding `node_modules/@close-by/clay-cli/client-dist`. Details: [Boot](./boot.md).
+
+Use `css` to inject your own stylesheet after the built client styles. **Token overrides** (`--primary`, `--background`, …) always work. **Tailwind utilities** in page modules are auto-scanned by default (`clay` / `ui.run`) — see [Tailwind](./tailwind.md).
+
+## Project layout (monorepo)
+
+```
+apps/demo/           Demo pages + server entry (`loadPages` + `ui.run({ app })`)
+packages/cli/         `clay` binary — file/dir launcher + shipped client-dist
+packages/ui/         NiceGUI-style ui facade (`loadPages`, `navFromPages`, `run`)
+packages/core/       Element tree, session, page wrapper, reactive, storage (tab/user/app)
+packages/auth/       Optional password hash, login limiter, requireAuth / requireRole, audit
+packages/persistence-file/  File-backed PersistenceAdapter for storage.configure
+packages/components/ Element factories (button, input, dataTable, areaChart / barChart / lineChart / pieChart / radarChart / radialChart, …)
+packages/client/     React + ShadCN renderer (Sonner toasts, BoundDataTable, …) — private, not published
+packages/server/     Bun HTTP + WebSocket
+docs/                This documentation
+```
+
+## Next
+
+- [Concepts](./concepts.md) — sessions, patches, refreshable
+- [API](./api.md) — full `ui.*` reference
+- [Examples](./examples.md) — demo catalog

package/docs/jsx-investigation.md

@@ -0,0 +1,167 @@
+# JSX investigation — context & recommendation
+
+Status: **investigation complete** (2026-08). Spike B POC landed in `@close-by/clay-core/jsx-runtime` (experimental). Spike A deferred.
+
+Related backlog: [TASKS.md](../TASKS.md) Later → Investigate `ui.jsx`. Historical HTMX-era note: [iterations/iteration-10.md](../iterations/iteration-10.md) (string `render()` → JSX; **superseded** by today’s Element + WebSocket model).
+
+---
+
+## Problem
+
+Apps (notably UQ Hub) still build markup as **strings** and pass them to `ui.html`:
+
+| Use (uq-hub) | Example |
+|--------------|---------|
+| Status dots | `` ui.html(`<span class="… rounded-full ${color}">`) `` |
+| Sparkline bars | `` ui.html(`<div style="width:…;background:…">`) `` |
+| SigNoz iframe | `` ui.html(`<iframe src="${url}" …>`) `` |
+| Trace icon link | HTML `<a>` + inline SVG string |
+
+Pain:
+
+1. No IDE structure / prop types / rename
+2. Easy XSS if values aren’t escaped
+3. Can’t compose real Clay components inside the blob
+4. Client path is `dangerouslySetInnerHTML` — no Clay events inside the string
+
+Goal: **author markup as markup** with IDE support for tags + user-defined components — without inventing a second UI stack.
+
+---
+
+## Current architecture (constraints)
+
+```
+Page builder (Bun)  →  Element tree  →  JSON mount/patch  →  ElementRenderer (React)
+```
+
+- `new Element(type, props)` **attaches immediately** to `getCurrentParent()` via `attachToContext`.
+- Layout uses **callback children**: `ui.row(props, () => { ui.button(…) })` so children run *after* the parent is on the stack.
+- Standard JSX evaluates **children before parents**. That fights attach-on-construct unless we create nodes **detached** and **reparent**.
+
+POC fix: `Element.adopt(child)` + `withDetached(() => new Element(…))` in `jsx()`.
+
+---
+
+## Spike A — JSX → static HTML → `ui.html`
+
+```tsx
+ui.html(renderToStaticMarkup(
+  <div className="flex">
+    <span className="h-1.5 w-1.5 rounded-full bg-emerald-500" />
+  </div>
+));
+```
+
+| Pros | Cons |
+|------|------|
+| Familiar HTML tags | Still opaque to Clay (one `html` node) |
+| IDE for DOM + React-ish function components | **No** `onClick` / Clay handlers inside |
+| Fits iframe / SVG blobs | Pulls React (or similar) into the **server** app, or a custom HTML serializer |
+| | Duplicates styling (Tailwind must scan these modules too) |
+
+**Verdict:** Only useful for true opaque HTML (iframe, third-party SVG). Most UQ Hub dots/bars should become Clay nodes instead. Prefer first-class `ui.iframe` over A for SigNoz embed.
+
+---
+
+## Spike B — JSX → Clay `Element` tree
+
+```tsx
+/** @jsxImportSource @close-by/clay-core */
+function StatusDot({ ok }: { ok: boolean }) {
+  return <badge text={ok ? 'up' : 'down'} size="xs" color={ok ? 'emerald' : 'red'} />;
+}
+
+ui.page('/', () => {
+  <row gap={2}>
+    <StatusDot ok={true} />
+    <button text="Refresh" icon="refresh-cw" onClick={() => void load()} />
+  </row>;
+});
+```
+
+| Pros | Cons |
+|------|------|
+| Same protocol / renderer / events | Intrinsics are Clay types (`button`, `row`), **not** HTML (`div`, `span`) |
+| IDE + custom components with props | Children-first requires `adopt` (POC done) |
+| Mix with `ui.*` under same parent | Layout/API mismatch: `ui.button(text, props)` vs `<button text props>` |
+| Aligns with long-term DX | Need docs so people don’t expect DOM JSX |
+
+**POC (landed):**
+
+- `Element.adopt`
+- `@close-by/clay-core/jsx-runtime` (`jsx` / `jsxs` / `Fragment`)
+- Tests: `packages/core/src/jsx-runtime.test.ts`
+
+Opt-in:
+
+```json
+"compilerOptions": {
+  "jsx": "react-jsx",
+  "jsxImportSource": "@close-by/clay-core"
+}
+```
+
+(Use `.tsx` page modules; keep default Clay apps on `.ts` + `ui.*` until DX is documented. Resolves to `@close-by/clay-core/jsx-runtime`.)
+
+---
+
+## Mixing `ui.*` and JSX
+
+| Pattern | Supported? |
+|---------|------------|
+| JSX inside `ui.row(() => { … })` | Yes — `jsx()` attaches to current parent |
+| `ui.button` inside a function component used as `<Foo />` | Yes — if the component runs under `withParent` / current session |
+| `<div>` HTML intrinsic | **No** (Spike B) — use Clay `container` / `row` / future `box`, or Spike A / `ui.html` |
+| `ui.html` string escape hatch | Keep forever for trusted blobs |
+
+---
+
+## Trust model
+
+| API | Trust |
+|-----|--------|
+| `ui.html(string)` | Trusted HTML only (XSS if user data interpolated) |
+| Spike A static markup | Same as `ui.html` once stringified |
+| Spike B Clay JSX | Props go through Element / protocol; handlers stay on server — **preferred** |
+
+---
+
+## Recommendation (phased)
+
+### Phase 0 — eliminate most strings without JSX (high ROI)
+
+Ship small primitives that replace UQ Hub’s `ui.html` call sites:
+
+1. **`ui.iframe({ src, title?, className?, … })`** — SigNoz embed  
+2. **`ui.dot({ color / tone, className? })`** or document `badge` + `size: 'xs'` as status chip (dots may still want a 6px circle — tiny `container`/`html` one-liner ok)  
+3. Prefer **`ui.externalLink` / `ui.copyButton`** (already shipped) over HTML `<a>` icon buttons; SVG brand icons can stay `ui.html` until `ui.image` / icon upload exists  
+
+### Phase 1 — productize Spike B (recommended north-star)
+
+1. Export jsx runtime from `@close-by/clay` as well (`jsxImportSource: "@close-by/clay"`) for one import path  
+2. Document Clay intrinsics list + function-component rules in `docs/jsx.md`  
+3. Demo page mixing `<row>` JSX with `ui.auto` / `ui.state`  
+4. Consider `ui.jsx` as a **hyperscript alias** only if needed; automatic runtime is enough  
+5. Do **not** default `jsxImportSource` in the Clay monorepo root (client already uses React JSX)
+
+### Phase 2 — Spike A only if still needed
+
+If trusted SVG/iframe authoring remains painful after Phase 0–1, add optional `renderClayHtml(vnode)` **without** depending on React (small tag→string walker), feeding `ui.html`. Otherwise skip.
+
+---
+
+## Decision
+
+| Spike | Decision |
+|-------|----------|
+| **B (Clay JSX)** | **Pursue** — POC in core; next = docs + clay re-export + demo |
+| **A (SSR HTML)** | **Defer / maybe skip** — replaced by `ui.iframe` + Clay nodes for hub cases |
+| **`ui.html(string)`** | **Keep** as escape hatch |
+
+---
+
+## Open questions
+
+1. Should Clay intrinsics use DOM-like names (`div` → `container`) for familiarity, or stay honest (`container` / `row`)?  
+2. TypeScript JSX intrinsic elements (`JSX.IntrinsicElements`) for autocomplete of `button` / `row` props?  
+3. Can `ui.auto(() => <row>…</row>)` be the documented reactive pattern once B is stable?

package/docs/kibana.md

@@ -0,0 +1,138 @@
+# Kibana (`@close-by/clay-kibana`)
+
+Authenticated (or internal) Kibana REST client: arbitrary API calls, Elasticsearch via console proxy or `/elasticsearch`, and `search_after` pagination for walking every matching log line.
+
+```typescript
+import { Kibana } from '@close-by/clay-kibana';
+
+// Modern Kibana (console proxy)
+const kbn = new Kibana({
+  baseUrl: 'https://kibana.example.com',
+  apiKey: process.env.KIBANA_API_KEY!, // or username + password
+  space: 'sales', // optional
+});
+
+// Kibana 6.x style (same as `…/elasticsearch/{index}/_search`)
+const logs = new Kibana({
+  baseUrl: 'https://kibana.internal.factsandit.pt',
+  kbnVersion: '6.8.0',
+  esTransport: 'path', // → /elasticsearch/…
+});
+```
+
+## Auth & headers
+
+| Option | Description |
+|--------|-------------|
+| `apiKey` | `Authorization: ApiKey …` (optional) |
+| `username` + `password` | `Authorization: Basic …` (optional) |
+| `kbnVersion` | Sets `kbn-version` (needed on older Kibana ES proxies) |
+| `space` | Prefixes Kibana API paths with `/s/{space}` |
+| `headers` | Extra headers on every request |
+| `fetch` | Inject a custom `fetch` (tests) |
+
+Every request also sends `kbn-xsrf: true`.
+
+## Elasticsearch transport
+
+| `esTransport` | Behavior |
+|---------------|----------|
+| `'console'` (default) | `POST /api/console/proxy?path=…&method=…` |
+| `'path'` | `{esPathPrefix}/{index}/_search` (default prefix `/elasticsearch`) |
+
+```typescript
+const result = await logs.search('logstash-production-logback-*', {
+  query: { match_all: {} },
+  size: 10,
+});
+
+await logs.es('GET', '_cluster/health');
+```
+
+## Paginate every hit (`search_after`)
+
+```typescript
+for await (const hit of logs.paginateSearch(index, body, { pageSize: 1000 })) {
+  // …
+}
+```
+
+## Guided query builder
+
+Chain filters instead of hand-writing Elasticsearch JSON:
+
+```typescript
+type LogLine = { '@timestamp': string; message: string };
+
+for await (const hit of logs
+  .query<LogLine>('logstash-production-logback-*')
+  .lastDays(1) // or .between(start, end)
+  .match('*receivePartnerEvent*')
+  .exclude('*ag_ibersol_webhook_notify_queue*')
+  .select('@timestamp', 'message')
+  .pageSize(1000)
+  .stream()) {
+  console.log(hit._source?.message);
+}
+
+// Or collect sources
+const lines = await logs
+  .query<LogLine>('logstash-production-logback-*')
+  .between(start, end)
+  .match('*receivePartnerEvent*')
+  .select('@timestamp', 'message')
+  .sources();
+```
+
+| Method | Purpose |
+|--------|---------|
+| `from` / `to` / `between` / `lastDays` | `@timestamp` range (override field with `timeField`) |
+| `match(query, field?)` | `query_string` must (default field `message`) |
+| `exclude(query, field?)` | `query_string` must_not |
+| `term` / `where` / `whereNot` | Exact term or raw clauses |
+| `select(...fields)` | `_source` filter |
+| `pageSize` / `sort` | Pagination controls |
+| `body()` | Inspect built ES JSON |
+| `first()` / `stream()` / `all()` / `sources()` | Execute |
+| `toParquet(path)` | Export all hits to a Parquet file (via DuckDB) |
+
+### Export to Parquet
+
+```typescript
+const { path, rows } = await logs
+  .query('logstash-production-logback-*')
+  .lastDays(1)
+  .match('*receivePartnerEvent*')
+  .select('@timestamp', 'message')
+  .toParquet('./data/logs.parquet');
+
+// Later in DuckDB:
+// SELECT * FROM 'data/logs.parquet'
+// or COPY / CREATE TABLE … AS SELECT * FROM 'data/logs.parquet'
+```
+
+Options: optional `map(hit => row)` for a custom shape. By default each Parquet row is the document **`_source` only** (no `_id`, `_index`, `_type`, `_score`, or `sort`).
+
+```sql
+SELECT message, "@timestamp" FROM 'data/logs.parquet'
+```
+
+## Raw Kibana REST
+
+```typescript
+const spaces = await kbn.request('GET', '/api/spaces/space');
+```
+
+Failures throw `KibanaError` with `status` and parsed `body`.
+
+## Saved Objects
+
+```typescript
+const found = await kbn.findSavedObjects({
+  type: ['dashboard', 'visualization'],
+  search: 'Sales',
+  perPage: 20,
+});
+
+const dash = await kbn.getSavedObject('dashboard', 'my-dashboard-id');
+```

package/docs/llms.txt

@@ -0,0 +1,44 @@
+# Clay
+
+> Server-driven UI for TypeScript. Write imperative `ui.*` on the server; Clay owns a per-tab element tree and syncs it to a React + ShadCN client over WebSocket. Inspired by NiceGUI.
+
+Clay is not a React app framework. Do not write React, JSX, or client components for screens. App code uses `@close-by/clay` (`ui.page`, `ui.run`, `ui.button`, …). The React client is a renderer.
+
+Notes for agents:
+
+- Public API and wire protocol are camelCase (`onClick`, `bindValue`, `setText`).
+- Page builders run once per WebSocket session (per browser tab). `let` is per-tab, not shared.
+- Update existing nodes with `setText` / `setValue` / bindings. Prefer `ui.state` + `ui.auto` (+ `ui.timer`) for async/live UIs; `ui.refreshable` for simple one-shot rebuilds. Shared or persisted state: `ui.storage` (`tab` / `user` / `app`).
+- Never use `window` / `navigator` in page code — use `ui.clipboard`, `ui.setUrlHash`, `ui.openExternal`.
+- Runtime is Bun. In this repo: `bun run build:client`, then `bun run demo` (http://localhost:4000) or `bun run clay hello.ts`.
+- `ui.ai.*` is visual primitives only — no model or streaming runtime.
+
+## Docs
+
+- [Human README](README.md): What Clay is, what you can build, try-it commands
+- [Getting started](docs/getting-started.md): Install, `clay` CLI, first app, publishing
+- [Boot](docs/boot.md): CLI vs library, `clientDir`, `_run.ts`, reload stubs
+- [Tailwind](docs/tailwind.md): Scanned utilities + `ui.run({ css })`
+- [Sample app](docs/tutorial.md): Step-by-step tasks list, then two pages + shell
+- [Concepts](docs/concepts.md): Sessions, element tree, patches, refreshable, bindings, storage
+- [Browser APIs](docs/browser-apis.md): `ui.clipboard` / hash / `openExternal` — no `window` in page code
+- [Ops patterns](docs/ops-patterns.md): Dense consoles — chips, feeds, sensitive codeBlock, auth nav
+- [API reference](docs/api.md): Complete `ui.*` and Element API
+- [Elements](docs/elements.md): Wire types and client mapping
+- [Documentation index](docs/README.md): Full guide list
+
+## Examples
+
+- [Examples catalog](docs/examples.md): Demo routes and patterns
+- [Demo pages](apps/demo/src/examples/): Runnable `ui.page` modules
+
+## Optional
+
+- [Architecture](docs/architecture.md): Packages and data flow
+- [WebSocket protocol](docs/protocol.md): Message formats
+- [AI UI](docs/ai.md): `ui.ai.*` visual primitives
+- [Reactive let](docs/reactive-let.md): `ui.state` / `ui.auto` and the compile-time `let` transform
+- [DuckDB](docs/duckdb.md): `@close-by/clay-duckdb`
+- [ClickHouse](docs/clickhouse.md): `@close-by/clay-clickhouse`
+- [Kibana](docs/kibana.md): `@close-by/clay-kibana`
+- [NiceGUI](https://nicegui.io/documentation): Inspiration for the `ui.*` style