@oneie/claude 0.5.0 → 0.6.0

package/skills/puck/SKILL.md

@@ -0,0 +1,568 @@
+---
+name: puck
+description: Build with Puck — the drag-drop visual editor for ONE. Covers @puckeditor/core API, Config/Data types, block registries, PuckEditor (client:only) + PuckRenderer (SSR), iframe brand injection, data-bound blocks, email target mode, and the funnels-pages architecture.
+user-invocable: true
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash
+---
+
+# Puck — ONE's universal content editor
+
+Puck is the drag-drop visual editor powering ONE's page system. Every landing page (`/p/`), funnel step (`/f/`), and eventually newsletter, product page, and course lesson is authored in one editor, stored as one typed JSON shape (Puck `Data`), and rendered by a small set of per-target renderers.
+
+**Architecture doc:** `text/funnels-pages-plan.md`  
+**Repo:** `../apps/puckeditor/` (cloned from https://github.com/puckeditor/puck)  
+**Package:** `@puckeditor/core` (^0.21.3, published on npm) — Puck moved from `@measured/puck`@0.20.x to the `@puckeditor` org; the funnels-pages doc set is synced to this name (2026-06-22). Source mirror: `../apps/puckeditor/`.  
+**ONE block registry:** `one.ie/web/src/lib/puck/config.tsx`
+
+## Works With
+
+| Skill | Load when |
+|---|---|
+| `/astro` | The editor is a `client:only` island; the renderer runs SSR in `.astro` files |
+| `/react19` | Block `render` fns are React 19 components; use `use()` + `useTransition` for data-bound blocks |
+| `/shadcn` | Every block wraps a real shadcn component — brand tokens are inherited via the iframe injection |
+
+Auto-loads with `*puck*` file patterns.
+
+---
+
+## Package imports
+
+```ts
+// @puckeditor/core ships Puck (editor), Render (SSR renderer), and all types
+import { Puck, Render } from "@puckeditor/core";
+import type { Config, Data, ComponentConfig, Field, Fields } from "@puckeditor/core";
+
+// Puck CSS — scope to the editor ONLY; never import in the renderer
+import "@puckeditor/core/puck.css"; // in the PuckEditor component only
+```
+
+> **CSS isolation rule:** `@puckeditor/core/puck.css` must only be imported inside the `PuckEditor` component (the `client:only` island). Never import it in `PuckRenderer` or any server-rendered path — it will bleed Puck's chrome styles into visitor pages.
+
+---
+
+## The `Config` shape
+
+A Puck config is the block registry: a map of component names to their field schema and render function.
+
+```ts
+import type { Config } from "@puckeditor/core";
+
+const config: Config = {
+  // Optional: group palette by category
+  categories: {
+    Structural: { components: ["Heading", "Text", "Image", "Button", "Form", "Columns", "Spacer"] },
+    CRO:        { components: ["LandingHero", "ProofBar", "HowItWorks", "LandingFeatures", "Testimonials", "ComparisonTable", "PricingSection", "FAQSection", "SecondaryCTA"] },
+    Funnel:     { components: ["CheckoutBlock", "UpsellBlock"] },
+    "Data-bound": { components: ["ProductBlock", "ListBlock"] },
+  },
+
+  components: {
+    Heading: {
+      label: "Heading",
+      fields: {
+        text:  { type: "text" },
+        level: { type: "select", options: [{ label: "H1", value: "h1" }, { label: "H2", value: "h2" }] },
+      },
+      defaultProps: { text: "Heading", level: "h1" },
+      render: ({ text, level }) => {
+        const Tag = level as "h1" | "h2";
+        return <Tag className="font-bold tracking-tight">{text}</Tag>;
+      },
+    },
+    // ... more blocks
+  },
+};
+```
+
+### ComponentConfig anatomy
+
+```ts
+type ComponentConfig<Props> = {
+  label?: string;           // palette display name (defaults to component key)
+  fields: Fields<Props>;    // inspector form schema
+  defaultProps?: Props;     // initial values on drag-in
+  render: (props: WithId<Props>) => JSX.Element;  // the block renderer
+  resolveData?: (data, params) => Promise<{props?>}>;  // async data resolution (data-bound blocks)
+  resolveFields?: (data, params) => Promise<Fields<Props>>;  // dynamic inspector fields
+  permissions?: { drag?, duplicate?, delete?, insert?, move? };  // per-block permission overrides
+  inline?: boolean;         // renders inline (no wrapper div)
+};
+```
+
+---
+
+## Field types
+
+The inspector is driven by `fields` in each block's config. ONE uses these field types:
+
+| Type | Usage |
+|---|---|
+| `{ type: "text" }` | Single-line text input; `contentEditable?: true` for inline editing on canvas |
+| `{ type: "textarea" }` | Multi-line text |
+| `{ type: "number", min?, max?, step? }` | Numeric |
+| `{ type: "richtext" }` | Rich text with Tiptap; `contentEditable?: true` |
+| `{ type: "select", options: [{label, value}] }` | Dropdown |
+| `{ type: "radio", options: [{label, value}] }` | Radio group |
+| `{ type: "array", arrayFields: {…}, getItemSummary?, min?, max? }` | Repeating sub-items (e.g. list of CTA buttons) |
+| `{ type: "object", objectFields: {…} }` | Nested group |
+| `{ type: "external", fetchList, mapProp?, showSearch?, filterFields? }` | The data-bound picker (products, agents) |
+| `{ type: "custom", render: ({value, onChange}) => JSX }` | Fully custom inspector widget |
+| `{ type: "slot" }` | A droppable zone inside a block (DropZone) |
+
+### External field — the data-bound picker
+
+Used for `ProductBlock`, `ListBlock`, and any block that binds to live workspace data:
+
+```ts
+import type { ExternalField } from "@puckeditor/core";
+
+const productPickerField: ExternalField = {
+  type: "external",
+  placeholder: "Search products…",
+  showSearch: true,
+  fetchList: async ({ query }) => {
+    const res = await fetch(`/api/ask`, {
+      method: "POST",
+      body: JSON.stringify({ receiver: "products:list", data: { query } }),
+    });
+    const { result } = await res.json();
+    return result?.items ?? [];
+  },
+  mapProp: (item) => ({ productId: item.id, name: item.name, price: item.price }),
+  mapRow: (item) => ({ Name: item.name, Price: `$${item.price}` }),
+};
+```
+
+---
+
+## `Data` shape (the stored IR)
+
+Everything authored in Puck is stored as `Data`:
+
+```ts
+type Data = {
+  root: { props?: { title?: string; [key: string]: any } };
+  content: Array<{ type: string; props: { id: string; [key: string]: any } }>;
+  zones?: Record<string, Array<{ type: string; props: { id: string } }>>;
+};
+
+// An empty page
+const emptyData: Data = { root: { props: {} }, content: [] };
+```
+
+**Where ONE stores it:**
+- Landing pages: `pages.data` column (D1) — row written by `pages:create` / `pages:edit`
+- Funnel steps: `funnel_definitions.steps[N].config.puck` (JSON column)
+- Newsletters (sweep C7): `broadcast.data` column
+
+---
+
+## `PuckEditor` — the client:only island
+
+The editor must be `client:only` because Puck requires browser APIs. Use the `Puck` component from `@puckeditor/core`:
+
+```tsx
+// one.ie/web/src/components/puck/PuckEditor.tsx
+"use client"; // Astro will ignore this; the client:only directive handles it
+import { Puck } from "@puckeditor/core";
+import "@puckeditor/core/puck.css";
+import { puckConfig } from "@/lib/puck/config";
+import type { Data } from "@puckeditor/core";
+
+interface Props {
+  initialData: Partial<Data>;
+  onPublish: (data: Data) => Promise<void>;
+}
+
+export function PuckEditor({ initialData, onPublish }: Props) {
+  return (
+    <Puck
+      config={puckConfig}
+      data={initialData}
+      onPublish={onPublish}
+      // Optional: inject brand tokens into the editor iframe
+      iframe={{ enabled: true }}
+    />
+  );
+}
+```
+
+Mounted in Astro as:
+```astro
+<PuckEditor client:only="react" initialData={data} onPublish={handlePublish} />
+```
+
+### Brand injection into the iframe
+
+The editor canvas runs in a sandboxed `<iframe>` — Tailwind 4 globals and workspace CSS tokens do **not** cascade in by default. Inject them via `computeStyleBlock` from `lib/site.ts`:
+
+```tsx
+import { useEffect } from "react";
+import { computeStyleBlock } from "@/lib/site"; // (tokens, darkTokens?, font?) → CSS rule text (:root{--color-*}), goes in a <style>.textContent (site.ts:59)
+import { Puck } from "@puckeditor/core";
+
+// VERIFIED against @puckeditor/core@0.21 source: the `iframe` OVERRIDE receives the real
+// iframe contentDocument (AutoFrame/index.tsx:420). This is the first-class injection API —
+// no portal, no hack. `overrides.iframe: RenderFunc<{ children; document? }>`.
+const overrides = {
+  iframe: ({ children, document }: { children: React.ReactNode; document?: Document }) => {
+    useEffect(() => {
+      if (!document?.head) return;
+      const el = document.createElement("style");
+      el.setAttribute("data-one-brand", "");
+      el.textContent = computeStyleBlock(tokens, darkTokens, font); // tokens/darkTokens: Partial<Record<SiteToken,string>>, font?: string — passed into PuckEditor as workspace-branding props
+      document.head.appendChild(el);
+      return () => el.remove();
+    }, [document]);
+    return <>{children}</>;
+  },
+};
+
+<Puck
+  config={puckConfig}
+  data={initialData}
+  onPublish={onPublish}
+  iframe={{ enabled: true }}     // IframeConfig: { enabled?, waitForStyles?, syncHostStyles? }
+  overrides={overrides}
+/>
+```
+
+**Pre-mortem guard (verified step, not an open risk):** the `iframe` override is the documented injection point (`apps/puckeditor/apps/docs/.../overrides/iframe.mdx` — "useful for injecting styles"). W4 asserts a `<style data-one-brand>` lands in the iframe `<head>` and a `--color-*` var resolves inside the canvas. First confirm `computeStyleBlock`'s real arg signature at `site.ts:59`.
+
+**Tailwind 4 guard:** Tailwind 4 uses `--color-*: initial` wipes at the `:root` level. Scope `@puckeditor/core/puck.css` to the editor chrome class only (e.g. `.puck-editor`). The renderer must import **no** Puck CSS.
+
+---
+
+## `PageStudio` — the editor surface (chat-left, build-right)
+
+`PageStudio.tsx` is the live editor surface mounted at `/u/[slug]/pages/[pageSlug]/edit`. It composes the workspace **`Chat`** on the LEFT with the editable **`PuckEditor`** on the RIGHT — one surface, not two. The operator edits by talking to the agent *and* by direct canvas manipulation.
+
+- **Chat (left):** `<Chat slug mode="rail-45" context={{ surface: 'builder', entityId: pageSlug, entityLabel: title }} onTurnSettled={reReadPage} />`. The `entityId` is the deterministic page target. `chat.ts` adds a `builderSuffix` for `surface:'builder'` that pins `edit_page slug=entityId` (channels does **not** auto-default the page slug from `entityId` the way it does for newsletter — the model needs the instruction).
+- **Canvas refresh:** on each settled turn, `reReadPage` GETs `/api/pages/[slug]`, runs `componentsToPuck(components)` → `normalizePuckData`, and bumps the `PuckEditor` key — guarded on `updated_at` so a no-op turn never remounts/flickers.
+- **Templates → chat:** picking a template applies its skeleton instantly, then dispatches `one:chat-seed` with the template's tuned `prompt` so the same Chat streams a complete page. (This retired the old right-side `PuckAiPanel`.)
+- **Shell:** the host `edit.astro` uses `Layout sidebar="none" chat="none"` so `Layout`'s `ChatHost` doesn't render a second chat — `PageStudio` owns its left rail. Same guard as `build.astro`.
+
+Note the column split: the channels `edit_page`/`create_page` tools write the `pages.components` column (CRO sections); `PageStudio.save()` (manual Puck edits) writes `pages.data` (Puck JSON). The canvas re-read uses `components` (the chat's write).
+
+---
+
+## `PuckRenderer` — SSR render
+
+No editor chrome, no editor JS shipped to visitors. Pure server-side render via `<Render>`:
+
+```tsx
+// one.ie/web/src/components/puck/PuckRenderer.tsx
+import { Render } from "@puckeditor/core";
+import { puckConfig } from "@/lib/puck/config";
+import type { Data } from "@puckeditor/core";
+
+interface Props {
+  data: Data;
+}
+
+export function PuckRenderer({ data }: Props) {
+  // Render is fully SSR-safe — no browser APIs, no editor state
+  return <Render config={puckConfig} data={data} />;
+}
+```
+
+Used in Astro routes:
+```astro
+---
+// pages/p/[slug].astro — always prerender:false (avoids astro#16529, two React copies)
+export const prerender = false;
+import { PuckRenderer } from "@/components/puck/PuckRenderer";
+const data = JSON.parse(page.data); // from D1
+---
+<Layout>
+  <PuckRenderer data={data} />
+</Layout>
+```
+
+> **Never set `prerender:true` on a Puck route** — Astro's static rendering triggers the two-React-copies bug (astro#16529) when `@puckeditor/core` ships its own React copy. All `/p/` and `/f/` routes are SSR (`prerender:false`).
+
+---
+
+## ONE's block registry (`lib/puck/config.tsx`)
+
+All blocks live in one export: `puckConfig`. The file declares:
+- **7 structural blocks:** `Heading`, `Text`, `Image`, `Button`, `Form`, `Columns`, `Spacer`
+- **9 CRO blocks (migrated 1:1):** `LandingHero`, `ProofBar`, `HowItWorks`, `LandingFeatures`, `Testimonials`, `ComparisonTable`, `PricingSection`, `FAQSection`, `SecondaryCTA`
+- **2 funnel widgets:** `CheckoutBlock` (wraps `PayPanel`), `UpsellBlock`
+- **2 data-bound blocks (sweep):** `ProductBlock`, `ListBlock`
+
+Each CRO block wraps the existing component from `one.ie/web/src/components/cro/`:
+
+```tsx
+import { LandingHero as LandingHeroComponent } from "@/components/cro/LandingHero";
+import type { Config } from "@puckeditor/core";
+
+// In puckConfig.components:
+LandingHero: {
+  label: "Landing Hero",
+  fields: {
+    headline:     { type: "text" },
+    highlight:    { type: "text" },
+    subhead:      { type: "text" },
+    eyebrow:      { type: "text" },
+    frictionText: { type: "text" },
+    primaryCta:   {
+      type: "object",
+      objectFields: {
+        label: { type: "text" },
+        href:  { type: "text" },
+      }
+    },
+    secondaryCta: {
+      type: "object",
+      objectFields: {
+        label: { type: "text" },
+        href:  { type: "text" },
+      }
+    },
+  },
+  defaultProps: {
+    headline: "Your headline here",
+    subhead: "Your sub-headline here",
+    primaryCta: { label: "Get started", href: "#" },
+  },
+  render: (props) => <LandingHeroComponent {...props} />,
+},
+```
+
+**Reuse contract:** CRO components are **never reimplemented** inside the block — they are always imported and wrapped. `wc -l` of `config.tsx` must stay reasonable; blocks are thin wrappers.
+
+### Per-block target field (planned, C1 stubs it)
+
+Each block declares which render targets it supports. This gates the email palette in C7:
+
+```ts
+// VERIFIED: Puck's ComponentConfig REJECTS unknown sibling keys (0.21 type is strict —
+// render/label/defaultProps/fields/permissions/inline/resolveFields/resolveData/metadata).
+// `targets` is NOT a bare sibling — it lives under the supported `metadata` key:
+const block = {
+  label: "Heading",
+  metadata: { targets: ["web"] },   // future: ["web", "email"] for email-capable blocks
+  fields: { … },
+  render: (props) => <…/>,
+};
+```
+
+The editor reads `block.metadata.targets` when filtering the palette for `target:'email'` mode (newsletter composer). `metadata` is the supported channel for any ONE-specific block flag — never add bare keys to a Puck component config.
+
+---
+
+## Data-bound blocks (`resolveData`)
+
+A block that renders live workspace data (products, lists) uses Puck's `resolveData` hook to fetch on insert/load:
+
+```tsx
+ProductBlock: {
+  label: "Product",
+  fields: {
+    product: {
+      type: "external",
+      placeholder: "Pick a product…",
+      showSearch: true,
+      fetchList: async ({ query }) => {
+        const r = await fetch("/api/ask", {
+          method: "POST",
+          body: JSON.stringify({ receiver: "products:list", data: { query, limit: 20 } }),
+        });
+        const { result } = await r.json();
+        return result?.items ?? [];
+      },
+      mapProp: (item) => item,  // store the whole record
+    },
+    showPrice:  { type: "radio", options: [{ label: "Yes", value: true }, { label: "No", value: false }] },
+    showButton: { type: "radio", options: [{ label: "Yes", value: true }, { label: "No", value: false }] },
+  },
+  defaultProps: { product: null, showPrice: true, showButton: true },
+  render: ({ product, showPrice, showButton }) => {
+    if (!product) return <div className="text-muted-foreground text-sm p-4">Pick a product in the inspector.</div>;
+    return (
+      <div className="rounded-lg border p-6">
+        <h3 className="font-semibold">{product.name}</h3>
+        {showPrice && <p className="text-font/60">${product.price}</p>}
+        {showButton && <button className="btn-primary mt-4">Buy</button>}
+      </div>
+    );
+  },
+},
+```
+
+> **C6 dependency:** `products:get` (read one product by ID) does not exist yet — only `products:list`. Until C6 lands, `ProductBlock` falls back to `products:list` + local filter. Never make N+1 list calls per block.
+>
+> **⚠ Shape correction (verified against `lib/resolvers/commerce.ts:73`):** the `fetchList` examples above are illustrative but wrong on the wire shape. `products:list` takes **`{ slug }`** (the workspace) and returns **`{ products: ProductWithPrices[] }`** — NOT `{ query }` / `{ items }`. There is **no server-side `query` filter** yet, so fetch the workspace's products once and filter client-side. Fix before C6: `const { result } = await r.json(); return (result?.products ?? []).filter(p => p.name.toLowerCase().includes(query.toLowerCase()))`.
+
+---
+
+## The `usePuck` hook (custom editor UI)
+
+Inside a custom field or a custom Puck override, `usePuck()` gives you access to editor state:
+
+```tsx
+import { usePuck } from "@puckeditor/core";
+
+function MyCustomField({ value, onChange }) {
+  const { appState, dispatch } = usePuck();
+  // appState.data — the full page Data
+  // dispatch({ type: "INSERT", ... }) — programmatic mutations
+  return <input value={value} onChange={(e) => onChange(e.target.value)} />;
+}
+```
+
+---
+
+## Migration (`components[]` → Puck `Data`)
+
+C3 migrates existing `pages.components` rows (the old `{component, props}[]` shape) to Puck `Data`. The transform is 1:1 because block `type` names match the old `component` names exactly:
+
+```ts
+// one.ie/web/src/lib/puck/migrate.ts
+import type { Data } from "@puckeditor/core";
+
+type LegacySection = { component: string; props: Record<string, unknown> };
+
+export function componentsToPuck(sections: LegacySection[]): Data {
+  return {
+    root: { props: {} },
+    content: sections.map((s, i) => ({
+      type: s.component,                     // e.g. "LandingHero" — 1:1 name match
+      props: { ...s.props, id: `migrated-${i}` },
+    })),
+  };
+}
+```
+
+**Migration gate (C3 W4):** row-count parity — `pages` rows must equal rows with non-null `pages.data` before deleting `PageRenderer.tsx`. The `components` column is kept for one release as a rollback.
+
+---
+
+## Starter templates (C5)
+
+Seed `Data` objects that make the first page one click. Store in `lib/puck/templates.ts`:
+
+```ts
+import type { Data } from "@puckeditor/core";
+
+export const OPT_IN_TEMPLATE: Data = {
+  root: { props: {} },
+  content: [
+    { type: "LandingHero", props: { id: "hero", headline: "Get early access", subhead: "…", primaryCta: { label: "Join", href: "#" } } },
+    { type: "Form",        props: { id: "form", submitLabel: "Join waitlist", receiver: "funnel:advance" } },
+  ],
+};
+
+export const TEMPLATES: Record<string, { label: string; data: Data }> = {
+  "opt-in":  { label: "Opt-in",  data: OPT_IN_TEMPLATE },
+  "sales":   { label: "Sales",   data: SALES_TEMPLATE },
+  "thanks":  { label: "Thank you", data: THANKS_TEMPLATE },
+  "webinar": { label: "Webinar", data: WEBINAR_TEMPLATE },
+};
+```
+
+---
+
+## Email target mode (sweep C7)
+
+When composing a newsletter, the editor runs in `target:'email'` mode:
+- **Palette filtered** — only blocks with `targets.includes('email')` appear
+- **Canvas width** — fixed 600px (email-client safe)
+- **Serializer** — `broadcast/render.ts` reads the same Puck `Data` but emits table-based, inline-styled HTML with `safeUrl` scheme-allowlisting and `/go/:id` tracking
+
+A block gains email support by adding an `email` impl to its block registration in `config.tsx`:
+
+```ts
+// Conceptual (C7 shape — not in C1):
+Heading: {
+  targets: ["web", "email"],
+  emailRender: (props) => `<h2 style="font-size:24px;font-weight:700">${props.text}</h2>`,
+  // ... standard Puck fields and render
+}
+```
+
+**Email rendering is never done via React DOM `renderToString`** — that produces flexbox HTML that breaks in Gmail. The email serializer is a separate function that walks the `Data.content` array and calls each block's `emailRender()`.
+
+---
+
+## The three target renderers (decision matrix)
+
+| Target | Renderer | Input | Output | ONE path |
+|---|---|---|---|---|
+| **Web** | `<Render>` (Puck SSR) | Puck `Data` | React → flexbox HTML | `PuckRenderer.tsx` |
+| **Email** | `broadcast/render.ts` serializer | Puck `Data` | Table-based, inline-style HTML | C7 (sweep) |
+| **Data** | `lib/data-bindings.ts` + `ResourceType` | `{type, id|filter}` | Live workspace rows | C6 (sweep) |
+
+Do not force email through React or web through the email serializer — they are separate, intentional.
+
+---
+
+## Kill-switch (the plan's exit criterion)
+
+```bash
+# Exits 0 only when the core (C1–C5) is complete:
+grep -q '@puckeditor/core' one.ie/web/package.json \
+  && test -f one.ie/web/src/lib/puck/config.tsx \
+  && ! test -f one.ie/web/src/components/cro/PageRenderer.tsx \
+  && (cd one.ie/web && bun vitest run tests/unit/puck/)
+```
+
+Note: `@puckeditor/core` is canonical across the funnels-pages doc set (synced 2026-06-22); `@measured/puck`@0.20.x is the superseded upstream name.
+
+---
+
+## No Puck cloud
+
+ONE does **not** use Puck's hosted cloud service or any Puck-managed storage. There is no `/puck/api` route. Storage goes through ONE's own D1 via receivers:
+
+- `pages:create` / `pages:edit` — landing pages → `pages.data`
+- `funnel:update-step` — funnel step pages → `funnel_definitions.steps[N].config.puck`
+- `broadcast:update` (C7) — newsletters → `broadcast.data`
+
+The `onPublish` callback in `<Puck>` calls ONE's own `/api/ask` endpoint:
+
+```tsx
+<Puck
+  config={puckConfig}
+  data={initialData}
+  onPublish={async (data) => {
+    await fetch("/api/ask", {
+      method: "POST",
+      body: JSON.stringify({ receiver: "pages:edit", data: { slug, data } }),
+    });
+  }}
+/>
+```
+
+Do not use `resolveAllData` with external Puck cloud endpoints. All data resolution is through ONE's receivers, `lib/data-bindings.ts`, and the binding resolver.
+
+---
+
+## Don'ts (the guards)
+
+| Don't | Why | Guard |
+|---|---|---|
+| Use Puck cloud / puckeditor.com hosted backend | ONE stores all page data in its own D1 via receivers | No `/puck/api` route; `onPublish` must call `/api/ask` |
+| Import `@puckeditor/core/puck.css` in `PuckRenderer` or any Astro layout | Puck chrome styles bleed into visitor pages | Grep: `puck.css` appears only in `PuckEditor.tsx` |
+| Set `prerender:true` on any `/p/` or `/f/` route | astro#16529: two React copies crash the page | All Puck routes must have `export const prerender = false` |
+| Reimplement CRO components inside block `render` fns | They already exist in `components/cro/`; re-registration is a thin wrapper | `wc -l config.tsx` gate + named import grep |
+| Trust `body.actorId` or `body.slug` in receiver resolvers | IDOR — use `ctx.ownerSlug` (attested) only | `authorizeWorkspace(locals, slug, db)` on every media/page write route |
+| Fetch live data on every `render()` call | N+1 — use `resolveData` or the binding resolver | No `fetch` inside block `render` fns; data-bound blocks use `resolveData` or the `external` field |
+| Merge Puck with the Workflow (ReactFlow) canvas | Different substrates: pages = layout tree, workflows = signal DAG | `lib/puck/` and `lib/workflow*/` must stay separate |
+
+---
+
+## Checklist — starting a new Puck cycle
+
+1. **Read the plan** — `text/funnels-pages-plan.md` (architecture + pre-mortem table)
+2. **Run the kill-switch** to see current state before editing
+3. **Check the block registry** — `lib/puck/config.tsx` for what exists (don't reimplement)
+4. **Check `components/cro/`** — the 9 CRO components are sources, not blocks; import them
+5. **Check migration number** — `one.ie/web/migrations/` highest number before creating a new SQL file
+6. **Keep all Puck routes `prerender:false`**
+7. **Scope `puck.css` to the editor component only**
+8. **authorizeWorkspace on every write route** (IDOR guard from `lib/analytics/authz.ts`)
+9. **Put vitest files in `tests/unit/puck/`** — not in `src/` (web vitest only discovers `tests/**`)
+10. **Run via `bun vitest run`** (not `bunx vitest`) — uses the local binary

package/skills/rag-adversarial/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: rag-adversarial
+description: Pattern 12 of the RAG query library - query the RAG twice with opposing framings (the case FOR and the case AGAINST), retrieve evidence for each side, then weigh them into a balanced verdict that names what the strongest counter-argument is. Kills confirmation bias in RAG-backed decisions. Triggers when Donal says "steelman both sides", "should we / should we not", "devil's advocate this", or before a contestable go/no-go call.
+model: claude-sonnet-4-6
+source: oo-internal
+---
+
+# Skill: /rag-adversarial - Two-Sided Evidence Weighing
+
+**Purpose:** Defeat confirmation bias in RAG lookups. A single "why should we X" query retrieves only pro-X chunks. This fires BOTH framings (for and against), retrieves evidence for each, and weighs them - surfacing the strongest counter-argument the corpus holds. Pattern 12 of `docs/rag-query-pattern-library.md`.
+**Output:** A balanced verdict: case FOR (cited) → case AGAINST (cited) → strongest counter → verdict + confidence. To `--out` (default `/tmp/adversarial-<slug>.md`).
+**Time to run:** 2-4 min.
+**Cost:** Tier 1 in-chat $0. Scripted ~$0.50 (2-4 searches + Sonnet weigh). Hard-cap $2.
+
+---
+
+## HARD RULES
+
+- **Closed-loop non-negotiable.** Each framing query (and any per-side fan-out) gets its own `mark_retrieval`.
+- **Genuinely opposing framings.** The two queries must be real opposites ("why X is right" / "why X is wrong"), not cosmetic rewordings. The whole value is retrieving evidence the affirmative query would never surface.
+- **Steelman both sides.** Present the STRONGEST version of each side from the corpus, not a strawman of the side you suspect is weaker. If one side has no corpus support, say "the corpus offers no evidence against" - that itself is a finding.
+- **Name the strongest counter explicitly.** The verdict must state the single best argument against its own conclusion. A verdict that hides its weakest point is bias, not analysis.
+- **Verdict ≠ decision.** Output a reasoned verdict + confidence; the go/no-go is Donal's. For client/money/strategy calls, frame as input.
+- **W1-W4:** W1 (build the two framings) Haiku · W3 (retrieve both + weigh) Sonnet · W4 (close loop) Haiku.
+
+## When to use
+- Contestable go/no-go: "should we take this client" / "should we add this offer" / "is this pricing right"
+- Pre-decision bias check on something you already lean toward (most valuable here - it surfaces what you're discounting)
+- Stress-testing a plan's assumption before committing
+- When `/rag-deep-question` or a strategy doc reaches a binary fork
+
+**Not for:** open-ended research (`/rag-fanout`); questions with no real "against" side (factual lookups); persona/values questions (`/persona-council`).
+
+## Input
+**Required:** `<proposition>` - the contestable claim/decision (e.g. "OO should take on the tax-prep niche").
+**Optional:**
+- `--vault <name>` (auto-routes; override)
+- `--k <N>` chunks per side (default 5)
+- `--fanout` run a small `/rag-fanout` per side instead of one query each (deeper, pricier)
+- `--out <path>`
+- `--dry-run` show the two framings without firing
+
+## Process
+
+### Step 1 (W1, Haiku): Build opposing framings
+From the proposition, write:
+- `for_q` = the affirmative case search ("reasons / evidence supporting <proposition>")
+- `against_q` = the negative case search ("risks / reasons against / failure modes of <proposition>")
+Confirm they're genuine opposites. If `--dry-run`: print both + vault + exit.
+
+### Step 2 (W3): Retrieve both sides
+- `search_notes(for_q, k, vault)` → pro chunks
+- `search_notes(against_q, k, vault)` → con chunks
+- If `--fanout`: run `/rag-fanout` per side with --max-subqueries 3 instead.
+
+### Step 3 (W3, Sonnet): Weigh
+```markdown
+# Adversarial: "<proposition>" (<date>)
+## Case FOR (steelmanned)
+- <strongest pro> [source: <file>, "<excerpt>"]
+## Case AGAINST (steelmanned)
+- <strongest con> [source: <file>, "<excerpt>"]
+## Strongest single counter-argument
+<the one thing most likely to make the verdict wrong>
+## Verdict: <lean for | lean against | genuinely balanced> — confidence <high|med|low>
+<reasoning weighing both>
+## Your call (Donal)
+<what to decide + what evidence would flip it>
+```
+
+### Step 4 (W4, Haiku): Close the loop
+`mark_retrieval` for each side's query (and fan-out sub-queries if `--fanout`).
+
+### Step 5: Emit
+Write `--out`. Print: `ADVERSARIAL: <proposition> | verdict <lean> conf <level> | for <n>/against <m> chunks | closed-loop <k>/<k>.`
+
+## Quality Checks
+- [ ] Framings are genuine opposites (not reworded)
+- [ ] Both sides steelmanned from the corpus
+- [ ] "Strongest single counter-argument" section present
+- [ ] Verdict has a confidence level + "what would flip it"
+- [ ] One mark_retrieval per search_notes
+- [ ] If a side has no corpus support, said plainly
+
+## Escalation rules
+Escalate to Donal if: the AGAINST side is materially stronger than the lean Donal expressed (the bias-check fired - surface it clearly); evidence is thin on BOTH sides (decision is being made on vibes, not corpus - flag it); the proposition touches client/money/legal where a wrong call is costly (verdict is input only, recommend real diligence).
+
+## Cost note (Rule 15)
+2 searches + Sonnet weigh ≈ $0.50; `--fanout` mode ≈ $1.50. Hard-cap $2. Tier 1 in-chat $0.
+
+## Composition
+`composes_with_sesh: false`. Single-shot verdict.
+
+## Cross-references
+
+- Cost levers (sub-token / API): `docs/rag-cost-optimization.md` (Haiku cache floor ~4k empirical; dedup sub-queries + chunks; OpenAI-embedding vs Anthropic-synthesis surfaces)
+- Pattern source: `docs/rag-query-pattern-library.md` (Pattern 12)
+- Sibling: `/rag-deep-question` (multi-dimension), `/rag-fanout` (used per side in `--fanout` mode)
+- Rules: 08, 15; Sub-plan 15
+
+## Pickup Prompt
+```
+/rag-adversarial "OO should take on the tax-prep niche"
+/rag-adversarial "<proposition>" --fanout --out /tmp/adversarial.md
+/rag-adversarial "<proposition>" --dry-run
+```