@oneie/claude 0.5.0 → 0.7.0

package/skills/astro/SKILL.md

@@ -0,0 +1,368 @@
+---
+name: astro
+description: Build pages, layouts and API routes in `one.ie/web` — Astro 6 + React 19 islands on Cloudflare Workers. Covers the real astro.config.mjs shape, adapter v13, SSR vs prerender, the `(await import('cloudflare:workers')).env` access pattern, and the LOCKED bundle-size rules. Use when editing `.astro` files, `astro.config.mjs`, or `src/pages/api/**`. For the `template/` tree use `template:astro` (Astro 7) instead.
+user-invocable: true
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash
+---
+
+# Astro 6 on Cloudflare Workers — `one.ie/web`
+
+**Which tree:** this skill describes `one.ie/web` only — Astro 6, single Cloudflare
+adapter. `template/site` is a **different major** (Astro 7) with its own conventions;
+use the `template:astro` skill there. Every claim below was checked against
+`one.ie/web/astro.config.mjs` and `one.ie/web/package.json` on 2026-08-02.
+
+Server-rendered pages with strategic React islands, on `@astrojs/cloudflare@13` +
+Workers with Static Assets (the Pages era is retired).
+
+## Stack
+
+| Package | Declared (2026-08-02) | Role |
+|---|---|---|
+| `astro` | `^6.2.2` (6.3.7 installed) | Framework |
+| `@astrojs/cloudflare` | `^13.3.1` | Workers adapter (no longer supports Pages) |
+| `@astrojs/react` | `^5.0.4` | React 19 islands |
+| `@astrojs/node` | `^10.0.6` | Declared but **unused** — not imported by `astro.config.mjs` |
+| `wrangler` | `^4.14.0` | Workers CLI |
+
+`@astrojs/node` is a leftover dependency. There is no dev/prod adapter swap in this
+tree — don't add one back on the strength of the package being present.
+
+## Works With
+
+| Skill      | Load when                                                                             |
+|------------|---------------------------------------------------------------------------------------|
+| `/react19` | React components inside islands — pick `client:load` / `client:visible` / `client:only`. |
+| `/cloudflare` | `wrangler.toml`, `[assets]` binding, secrets, `wrangler tail`, Workers+Assets semantics. |
+| `/signal`  | `src/pages/api/*.ts` — every API route is the substrate's HTTP surface.                |
+| `/shadcn`  | shadcn components live inside islands; dark-theme tokens + hydration strategy.         |
+| `/sui`     | SSR pages reading on-chain data — use `client:only="react"` to keep the worker small.  |
+| `/typedb`  | SSR data fetching — pages call `typedbQuery()` from `src/lib/substrate.ts`.            |
+
+Auto-loads on `*.astro`: `.claude/rules/astro.md`. The deploy pipeline (8 steps,
+Astro build is step 3) is the `/deploy` **command**, not a skill:
+`.claude/commands/deploy.md`.
+
+## The Config (the ONE shape)
+
+One adapter, always Cloudflare. `astro.config.mjs` is ~200 lines — three Vite plugins,
+a large `optimizeDeps` block, and a Durable-Object export plugin. **Read the file for
+the rest; the load-bearing shape is:**
+
+```js
+// astro.config.mjs — the parts this skill's rules depend on
+export default defineConfig({
+  output: 'server',                    // all routes SSR unless prerender=true
+  adapter: cloudflare({
+    prerenderEnvironment: 'node',      // prerender under node, not workerd
+    imageService: 'passthrough',
+    sessions: false,
+    remoteBindings: false,
+    // NOT { enabled: true } — loading [env.production] during build sync
+    // makes Miniflare evaluate the DO before the export plugin runs
+    platformProxy: { environment: undefined },
+  }),
+  integrations: [react(), devWarmupIntegration()],
+  build: { inlineStylesheets: 'auto' },   // LOCKED — never 'always'
+  markdown: { syntaxHighlight: false },   // LOCKED — keeps Shiki out of the worker
+  security: { checkOrigin: false },
+  vite: { /* ssr.external, ssr.noExternal, optimizeDeps, plugins — see the file */ },
+})
+```
+
+**Don't copy a `vite.ssr` list out of this skill.** `astro.config.mjs` §
+`vite.ssr.external` is the authority (`.claude/commands/deploy.md` Rule 2 says so
+explicitly: *never reconcile that file to a doc*). Note the direction — `recharts`,
+Stripe, `@xyflow/react`, `motion`, `media-chrome` and the 100ms packages are
+**external**; `react`, `react-dom`, `@astrojs/react`, `better-auth` and `kysely` are
+**noExternal**. Getting that backwards breaks the build.
+
+A companion `ssrExternalPlugin()` also swaps three packages for tiny SSR stubs
+(`pusher-js`, `media-chrome/react`, `@mux/mux-player-react` → `src/lib/stubs/`).
+
+## Adapter v13 — What Changed from Astro 5/v12
+
+| Change | v12 (old) | v13 (current) | Action |
+|---|---|---|---|
+| Pages support | ✓ | **removed** | Deploy target is Workers + Static Assets only |
+| `output: "hybrid"` | ✓ | **removed** | Use `"server"` + `prerender = true` per-page, or `"static"` + `prerender = false` |
+| `Astro.locals.runtime` | populated | **removed** | Use `cloudflare:workers` (see below) |
+| `prerenderEnvironment` | n/a | `workerd` default | ONE sets `'node'` — prerender breaks under workerd here |
+| `imageService` default | `"compile"` | `"cloudflare-binding"` | ONE overrides to `'passthrough'` — no IMAGES binding needed |
+| `sessionKVBindingName` | n/a | default `"SESSION"` | ONE sets `sessions: false`; the `SESSION` KV is used directly |
+| `workerEntryPoint` | option | **removed** | Adapter emits the bundled entry; `dist/server/wrangler.json` injects it |
+| `cloudflareModules` | option | **removed** | Use Vite's built-in WASM/text imports |
+
+**Migration memory:** check adapter + deploy-target compatibility BEFORE bumping
+Astro major. Astro 6's `@astrojs/cloudflare@13` dropped Pages in a single minor jump;
+~8-commit cascade to fix.
+
+## Output Modes (Astro 6)
+
+```astro
+// Per-page opt-in / opt-out (works under any output mode)
+export const prerender = true   // force static — skips worker
+export const prerender = false  // force SSR  — runs in worker
+```
+
+| `output` | Default per page | Use when |
+|---|---|---|
+| `"static"` | prerendered | Mostly-static sites with few dynamic pages |
+| `"server"` | SSR | ONE's choice — most routes are dynamic; static pages opt in |
+| `"hybrid"` | — | **removed** in Astro 6; use `"server"` + per-page `prerender = true` |
+
+**ONE's rule:** `output: "server"`. Static shell pages export `prerender = true` AND
+load heavy islands with `client:only="react"`, so the worker ships no React for them.
+Current split in `src/pages`: 53 files `prerender = true`, 601 `prerender = false`.
+
+## cloudflare:workers — The Canonical Env Import
+
+**Always the dynamic form.** A top-level `import { env } from "cloudflare:workers"`
+is not used anywhere in this tree (0 files under `src/`); the dynamic import is (407 files). The
+static import resolves at module-eval time, which breaks prerender and any non-worker
+context that touches the module.
+
+```ts
+// src/pages/api/whatever.ts (SSR API route)
+import type { APIRoute } from "astro";
+
+type Env = { DB?: D1Database; SESSION?: KVNamespace }
+
+async function getEnv(): Promise<Env> {
+  return (await import('cloudflare:workers' as string)).env as Env
+}
+
+export const GET: APIRoute = async () => {
+  const env = await getEnv()
+  if (!env.DB) return Response.json({ error: 'no_db' }, { status: 503 })
+  const { results } = await env.DB.prepare("SELECT * FROM signals LIMIT 10").all();
+  return Response.json({ signals: results });
+};
+```
+
+**Typing.** There is no `worker-configuration.d.ts` in this tree and `wrangler types`
+is not wired into any script. Bindings are typed by hand in `src/env.d.ts` — the
+`Runtime` interface lists every binding (`DB`, `CONTENT`, `SESSION`, `CHAT_CACHE`,
+`ANALYTICS_HUB`, `WORKFLOW_RUN`, …) alongside `App.Locals`. Add a new binding there
+when you add it to `wrangler.toml`. Routes that declare a narrow local `Env` type (as
+above) are the prevailing pattern.
+
+### Legacy `Astro.locals.runtime.env` (compat shim)
+
+`src/env.d.ts` still declares `runtime?: Runtime` on `App.Locals`, and 7 files read
+`locals?.runtime?.env?.*` from the Astro 5 era. **New code uses the dynamic
+`cloudflare:workers` import** — it survives the shim's removal.
+
+## Hydration Directives (unchanged in Astro 6)
+
+```astro
+client:load       → Hydrate immediately (above-fold, critical)
+client:idle       → Hydrate on requestIdleCallback (non-critical widgets)
+client:visible    → Hydrate when scrolled into view (below-fold)
+client:only="react" → Client-only, skip SSR entirely (heavy deps, keeps worker bundle small)
+client:media="(min-width: 768px)" → Hydrate on media query match
+```
+
+**Bundle rule (LOCKED):** heavy components (shiki, recharts, Stripe, 100ms, Puck)
+MUST be `client:only="react"` OR listed in `vite.ssr.external`. Both together is the
+common case — `ssr.external` is only safe when the package never executes on the
+server path, and `client:only` is what guarantees that. 216 `client:only="react"`
+uses across pages and components today.
+
+## Page Patterns
+
+### Pure-shell pre-rendered page
+
+```astro
+---
+// src/pages/about.astro — stays out of the worker entirely
+import Layout from "@/layouts/Layout.astro";
+import HeavyChart from "@/components/HeavyChart";
+export const prerender = true;
+---
+<Layout title="About">
+  <HeavyChart client:only="react" />
+</Layout>
+```
+
+### SSR page reading CF bindings
+
+```astro
+---
+// src/pages/dashboard.astro
+import Layout from "@/layouts/Layout.astro";
+import Dashboard from "@/components/Dashboard";
+
+const { env } = await import('cloudflare:workers' as string);
+const paths = (await env.CHAT_CACHE?.get("paths.json", "json")) ?? [];
+---
+<Layout title="Dashboard">
+  <Dashboard client:load paths={paths} />
+</Layout>
+```
+
+### API route (signal receiver)
+
+```ts
+// src/pages/api/signal.ts
+import type { APIRoute } from "astro";
+
+export const prerender = false
+
+export const POST: APIRoute = async ({ request }) => {
+  const { env } = await import('cloudflare:workers' as string);
+  const signal = await request.json();
+  await env.CHAT_CACHE.put(`signal:${Date.now()}`, JSON.stringify(signal));
+  return Response.json({ received: true });
+};
+```
+
+## Bundle-Size Rules (LOCKED — do not revert)
+
+Wrangler reports both `Total Upload` (uncompressed) and `gzip` — only gzip counts.
+The documented ceiling is **3 MiB gzipped** free tier / 10 MiB paid, but this
+account's real ceiling is **unconfirmed**: deploys at 3.22 MiB (2026-07-08) and
+4.43 MiB (2026-07-19) both succeeded. Treat the current number as a floor to watch,
+not a hard gate, and re-run the diagnosis if it keeps climbing.
+`.claude/commands/deploy.md § Bundle Size Rules` + § Verified Bundle Numbers is the
+authority — reconcile to it, not to this table.
+
+| Rule | Where | Saves |
+|---|---|---|
+| `markdown: { syntaxHighlight: false }` | `astro.config.mjs` | ~5.8 MiB (Shiki grammars/WASM) |
+| `vite.ssr.external` for heavy packages | `astro.config.mjs` | Bare imports — safe only if the package never runs server-side (shiki's callers are all `client:only`) |
+| `prerender = true` + `client:only="react"` on shell pages | per-page | Page handler collapses to a stub; no React in the worker |
+| `build: { inlineStylesheets: 'auto' }` — **NEVER `'always'`** | `astro.config.mjs` | ~8 MiB at 100+ routes. `'always'` inlines the full Tailwind stylesheet into every route's manifest entry. `'auto'` ships one external `<link>`. |
+| `react-dom/server` → `react-dom/server.edge` alias, production only | `astro.config.mjs` `vite.resolve.alias` | Ships the edge build instead of the Node build |
+
+Verified deltas:
+- 2026-04-15: 21 MiB Pages → 9.5 MiB Worker (Rules 1-3). Pages deploy FAILED → Workers ✓.
+- 2026-05-22: worker-entry 9.5 MiB → 672 KiB (Rule 4). gzip 3.3 MiB → 2.1 MiB.
+
+## Dev Commands
+
+```bash
+bun run dev          # localhost:4321 — regenerates playbook meta + promises, then astro dev
+bun run build        # builds @oneie/sdk, astro build, patches dist/server/wrangler.json
+bun run preview      # astro preview (NOT wrangler — see dev:wrangler for production shape)
+bun run dev:wrangler # build + wrangler dev against dist/server/wrangler.json on :8787
+bun run check        # astro check
+bun run typecheck    # tsc --noEmit
+bun run verify       # build SDK + typecheck + vitest — the gate
+
+# Bindings against real CF resources
+bun wrangler dev --remote    # production KV/D1 — use with care
+```
+
+There is no `wrangler types` step. Bindings are hand-typed in `src/env.d.ts`.
+
+## Dynamic Routes
+
+Real routes in this tree:
+
+```
+src/pages/
+  p/[slug].astro             → /p/my-landing-page
+  studio/[agent].astro       → /studio/donal
+  u/[slug]/[...path].astro   → catch-all under a workspace
+  go/[id].ts                 → a dynamic API-shaped route (.ts, not .astro)
+  tasks/[...view].astro      → catch-all
+```
+
+```astro
+---
+// src/pages/studio/[agent].astro
+export const prerender = false
+const { agent } = Astro.params;
+if (!agent) return new Response(null, { status: 404 });
+---
+<Layout title={`Studio: ${agent}`}>
+  <AgentCard client:load agentId={agent} />
+</Layout>
+```
+
+## File Locations
+
+| Type | Location |
+|------|----------|
+| Pages | `src/pages/*.astro` |
+| API routes | `src/pages/api/**/*.ts` |
+| Layouts | `src/layouts/*.astro` |
+| React islands | `src/components/**/*.tsx` |
+| Content collections | `src/content.config.ts` + `src/content/` |
+| Astro config | `astro.config.mjs` |
+| Worker config | `wrangler.toml` (`main` intentionally omitted) |
+| Binding + Locals types | `src/env.d.ts` |
+
+## Performance Budgets (from `text/speed.md`)
+
+| Metric | Measured |
+|---|---|
+| Routing decision (in-memory) | <0.005ms (320 tests) |
+| KV read / highway cache (edge) | <10ms |
+| `ask()` round-trip (no LLM) | 50–200ms |
+| Chat TTFB p50 (browser) | ~97ms — gate ≤100ms |
+| Agent first SSE token (end-to-end) | ~500ms |
+
+Static pages served from the `[assets]` binding don't count against request quota —
+pre-render anything that doesn't need SSR.
+
+## Common Tasks
+
+Five sub-workflows live beside this file: `create-page.md`, `create-component.md`,
+`add-content-collection.md`, `check-build.md`, `optimize-performance.md`.
+
+### Add a new page
+
+1. Create `src/pages/<name>.astro` with a Layout import
+2. If mostly static → `export const prerender = true`
+3. If it needs CF bindings → `await import('cloudflare:workers')` in frontmatter
+4. React islands: default to `client:visible`; `client:load` only for above-fold critical UI
+
+### Add an API route
+
+1. Create `src/pages/api/<name>.ts`, `export const prerender = false`
+2. Export `GET` / `POST` / `PUT` / `DELETE` as `APIRoute`
+3. Read bindings via `(await import('cloudflare:workers')).env`
+4. Authorize before touching workspace data (`authorizeWorkspace` from `@/lib/analytics/authz`)
+5. Return `Response.json(...)` or `new Response(...)`
+
+### Convert static component to interactive
+
+1. Create `.tsx` in `src/components/`
+2. Import into the `.astro` page
+3. Pick directive: above-fold → `client:load`, below-fold → `client:visible`, heavy → `client:only="react"`
+
+### Type a new binding
+
+1. Add the binding to `wrangler.toml` (`[[kv_namespaces]]`, `[[d1_databases]]`, etc.)
+2. Add the field to the `Runtime.env` interface in `src/env.d.ts` (by hand — no codegen)
+3. Narrow it in the route's local `Env` type where you read it
+
+## Gotchas
+
+- **Dev and prod both run the Cloudflare adapter**, but dev goes through Vite +
+  Miniflare. Behaviour still diverges — `bun run dev:wrangler` for a production-shape smoke.
+- **A top-level `import { env } from "cloudflare:workers"` breaks prerender.** Always
+  the dynamic form. Zero files in this tree use the static one.
+- **`import.meta.env.*`** is build-time only. Runtime secrets/bindings come from `env`.
+- **Shiki will crash your deploy** if imported from SSR. All callers must be `client:only="react"`.
+- **`output: "hybrid"`** throws in Astro 6. Replace with `"server"` + per-page `prerender = true`.
+- **Never delete a `vite.ssr.external` entry to match a doc snippet** — the config file is
+  the authority and the list is longer than any snippet.
+- **`platformProxy: { enabled: true }`** is wrong here. This tree uses
+  `{ environment: undefined }` so `astro build` doesn't make Miniflare evaluate the
+  Durable Object before `durableObjectExportsPlugin` has run.
+
+## References
+
+- [Astro Cloudflare adapter](https://docs.astro.build/en/guides/integrations-guide/cloudflare/) — authoritative for v13
+- [CF Workers framework guide — Astro](https://developers.cloudflare.com/workers/frameworks/framework-guides/astro/)
+- `.claude/commands/deploy.md` — 8-step pipeline, 5 LOCKED bundle rules, verified bundle numbers, rollback
+- `.claude/rules/astro.md` — auto-loaded on `*.astro` edits
+- `one.ie/web/astro.config.mjs` — the authority for adapter options and every `vite.ssr` list
+
+---
+
+**Version**: 3.0.0 — reconciled against `one.ie/web` (2026-08-02)
+**Previous**: 2.0.0 (2026-04-18, described a dual-adapter config this tree never had)

package/skills/astro/add-content-collection.md

@@ -0,0 +1,46 @@
+# Add Content Collection
+
+**Category:** astro
+**Version:** 2.0.0
+**Used By:** `astro` skill · `/do` W3 edit wave
+
+## Purpose
+
+Adds a collection to `one.ie/web/src/content.config.ts`. This tree is on the Astro
+Content Layer — every collection declares a **`loader`**; the legacy `type: 'content'`
+shape is gone. Five collections exist today: `videos`, `playbook`, `moversPlaybook`,
+`legal`, `blog`.
+
+## Example
+
+```typescript
+// src/content.config.ts
+import { defineCollection, z } from "astro:content";
+import { glob } from "astro/loaders";
+
+const GuideSchema = z.object({
+  title: z.string(),
+  order: z.number().default(0),
+  publishedAt: z.coerce.date(),   // coerce — frontmatter dates arrive as strings
+  tags: z.array(z.string()).default([]),
+  draft: z.boolean().default(false),
+});
+
+const guides = defineCollection({
+  loader: glob({ pattern: "**/*.md", base: "./src/content/guides" }),
+  schema: GuideSchema,
+});
+
+// Append to the single exported object — do not add a second export.
+export const collections = { videos, playbook, moversPlaybook, legal, blog, guides };
+```
+
+Then create `src/content/guides/` and put the markdown in it. Read it with
+`getCollection('guides')`; filter `draft` yourself — the schema defaults it, it
+doesn't exclude it.
+
+## Version History
+
+- **2.0.0** (2026-08-02): Rewritten for the Content Layer `loader` API and the real
+  `content.config.ts`. The 1.0.0 example used the pre-Astro-5 shape with no loader.
+- **1.0.0** (2025-10-18): Initial implementation

package/skills/astro/check-build.md

@@ -0,0 +1,35 @@
+# Check Astro Build
+
+**Category:** astro
+**Version:** 2.0.0
+**Used By:** `astro` skill · `/do` W4 verify wave
+
+## Purpose
+
+Verify `one.ie/web` compiles before shipping. `astro check` emits **human-readable
+text, not JSON** — parse the exit code, not the stdout.
+
+## Example
+
+```bash
+cd one.ie/web
+
+bun run verify     # THE gate: builds @oneie/sdk, then tsc --noEmit, then vitest run
+bun run check      # astro check — types inside .astro templates
+bun run typecheck  # tsc --noEmit only (fastest signal on .ts/.tsx)
+bun run build      # full production build; the only thing that catches bundler breaks
+```
+
+`astro check` prints a summary line of the form
+`Result (N files): X errors, Y warnings, Z hints` and exits non-zero on errors.
+
+**Build the SDK first.** `bun run typecheck` on its own reports phantom `TS2307`
+module-not-found errors when `packages/sdk/dist` is stale or missing — `bun run verify`
+already does the SDK build, which is why it is the gate. In a `/do` worktree also
+confirm `node_modules` is present; a partial install fakes a ratchet violation.
+
+## Version History
+
+- **2.0.0** (2026-08-02): Replaced the invented JSON output with the real commands and
+  exit-code contract; added the build-SDK-first trap.
+- **1.0.0** (2025-10-18): Initial implementation

package/skills/astro/create-component.md

@@ -0,0 +1,56 @@
+# Create React Component
+
+**Category:** astro
+**Version:** 2.0.0
+**Used By:** `astro` skill · `/do` W3 edit wave
+
+## Purpose
+
+Add a React 19 island under `one.ie/web/src/components/`, styled with the ONE 6-token
+design system. `.claude/rules/design.md` and `.claude/rules/react.md` auto-load on
+`*.tsx` — this file is the short version.
+
+## Example
+
+```tsx
+// src/components/pricing/PricingTable.tsx
+import { cn } from "@/lib/utils"
+import { Card } from "@/components/ui/card"
+
+interface PricingTableProps {
+  tiers: { name: string; price: number }[]
+  className?: string
+}
+
+export function PricingTable({ tiers, className }: PricingTableProps) {
+  return (
+    <div className={cn("grid gap-6 md:grid-cols-3", className)}>
+      {tiers.map((tier) => (
+        <Card key={tier.name} className="bg-foreground text-font p-6">
+          <h3 className="text-lg font-medium">{tier.name}</h3>
+          <p className="text-muted">${tier.price}/mo</p>
+        </Card>
+      ))}
+    </div>
+  )
+}
+```
+
+Rules that bite:
+
+- **Token classes only — never a hex value.** The 6 editable tokens are `background`,
+  `foreground`, `font`, `primary`, `secondary`, `tertiary`; plus the invariants
+  (`white`, `black`, `transparent`, `destructive`, `success`) and derived helpers
+  (`muted`, `border`, `on-primary`, …). `Layout.astro` sets `--color-*: initial`, so a
+  Tailwind default palette class emits **no CSS at all** — it fails silently.
+- Depth: L1 canvas is `background`, L2 chrome (cards, panels, sidebar) is `foreground`.
+- Take a `className?` and merge it through `cn` so callers can position the island.
+- Import shadcn primitives from `@/components/ui/*`; add new ones via the CLI, not by hand.
+- Mount it from the `.astro` page — `client:load` above the fold, `client:visible` below,
+  `client:only="react"` when the dependency tree is heavy.
+
+## Version History
+
+- **2.0.0** (2026-08-02): Added the 6-token constraint, `cn`, the silent-failure trap,
+  and the hydration hand-off. The 1.0.0 example used none of the ONE conventions.
+- **1.0.0** (2025-10-18): Initial implementation

package/skills/astro/create-page.md

@@ -0,0 +1,59 @@
+# Create Astro Page
+
+**Category:** astro
+**Version:** 2.0.0
+**Used By:** `astro` skill · `/do` W3 edit wave
+
+## Purpose
+
+Add a route under `one.ie/web/src/pages/`. Decide first: prerendered shell (cheap, no
+worker) or SSR page (reads bindings). `output: 'server'` means SSR is the default —
+opt out explicitly.
+
+## Example
+
+Prerendered shell — the common case. Modelled on the real `src/pages/activity.astro`:
+
+```astro
+---
+export const prerender = true
+import Layout from "@/layouts/Layout.astro"
+import { ActivityFeed } from "@/components/activity/ActivityFeed"
+---
+
+<Layout title="Activity — ONE" sidebar="none">
+  <ActivityFeed client:only="react" />
+</Layout>
+```
+
+SSR page reading a Cloudflare binding — note the **dynamic** import; a top-level
+`import { env } from "cloudflare:workers"` breaks prerender and is used nowhere in
+this tree:
+
+```astro
+---
+export const prerender = false
+import Layout from "@/layouts/Layout.astro"
+import { Dashboard } from "@/components/Dashboard"
+
+const { env } = await import('cloudflare:workers' as string)
+const rows = await env.DB.prepare("SELECT id, name FROM things LIMIT 20").all()
+---
+
+<Layout title="Dashboard — ONE" sidebar="full">
+  <Dashboard client:load rows={rows.results} />
+</Layout>
+```
+
+`Layout` requires `title`; useful optional props include `description`, `sidebar`
+(`none | mini | full | rail`) and the `chat*` family. Read `src/layouts/Layout.astro`
+for the full `Props` interface before inventing one.
+
+Hydration: above-fold → `client:load`, below-fold → `client:visible`, heavy deps →
+`client:only="react"`.
+
+## Version History
+
+- **2.0.0** (2026-08-02): Replaced the Convex example (Convex is not a dependency of
+  this repo) with the two real page shapes and the dynamic `cloudflare:workers` import.
+- **1.0.0** (2025-10-18): Initial implementation

package/skills/astro/optimize-performance.md

@@ -0,0 +1,49 @@
+# Optimize Astro Performance
+
+**Category:** astro
+**Version:** 2.0.0
+**Used By:** `astro` skill · `/do` W4 verify wave
+
+## Purpose
+
+Cut worker bundle size and page latency in `one.ie/web`. Two separate budgets: the
+**upload** (gzip, gated at deploy) and the **request** (TTFB, measured in
+`text/speed.md`).
+
+## Recommendations
+
+Bundle — the 5 LOCKED rules, authority `.claude/commands/deploy.md § Bundle Size Rules`:
+
+- `markdown: { syntaxHighlight: false }` — keeps ~5.8 MiB of Shiki grammars out.
+- `vite.ssr.external` for heavy client-only packages. **`astro.config.mjs` is the
+  authority for that list** — never trim it to match a snippet in a doc.
+- `export const prerender = true` + `client:only="react"` on shell pages, so the worker
+  ships no React for them.
+- `build: { inlineStylesheets: 'auto' }` — **never `'always'`** (~8 MiB at 100+ routes).
+- `react-dom/server` → `react-dom/server.edge` alias in production.
+
+Runtime:
+
+- Pick the cheapest hydration directive that works: `client:visible` below the fold,
+  `client:only="react"` for heavy trees, `client:load` only above the fold.
+- Smart Placement is on (`[placement] mode = "smart"` in `wrangler.toml`) — the isolate
+  runs near D1/R2/DO instead of at the visitor's PoP. Don't remove it; it was dropped
+  once in a config rewrite and cost ~1s of pre-flight per chat turn.
+- `optimizeDeps.include` / `ssr.optimizeDeps.include` in `astro.config.mjs` pre-bundle
+  React and friends at boot. Mid-session re-optimisation produces two `?v=` hashes for
+  react-dom and breaks hydration — add new hot deps to the list rather than debugging
+  the symptom.
+- Static assets come from the `[assets]` binding and don't count against request quota.
+
+Measure, don't guess: `text/speed.md` carries the real table (routing <0.005ms, KV read
+<10ms, `ask()` 50–200ms, chat TTFB p50 ~97ms, first SSE token ~500ms). Run
+`.claude/commands/deploy.md § Bundle Size Diagnosis` before optimising a bundle.
+
+**Not applicable here:** `@astrojs/image` — deprecated and not a dependency of this
+repo. Astro's built-in `astro:assets` replaces it.
+
+## Version History
+
+- **2.0.0** (2026-08-02): Replaced generic advice with the 5 LOCKED bundle rules, Smart
+  Placement, the optimizeDeps trap, and the real speed table; dropped `@astrojs/image`.
+- **1.0.0** (2025-10-18): Initial implementation