@graph8/sdk 0.361.0 → 0.370.0

package/blocks/appointments/components/meetings-screen.tsx

@@ -0,0 +1,157 @@
+"use client";
+
+/**
+ * MeetingsScreen: the finished meetings product. Upcoming, past, cancelled and recorded meetings, a detail panel
+ * for the open one, and a "Schedule a meeting" flow. No props are required.
+ *
+ * It composes: MeetingList (views, search, paging), MeetingDetail (booking or recorded meeting) and BookingPage.
+ *
+ * Flows:
+ *   - Headline numbers: meetings coming up and bookings waiting for your approval.
+ *   - Open a booking (deep link ?sel=booking:<uid>, full page with &view=full) -> accept or decline a pending one, add an internal note,
+ *     cancel (all confirmed because they email attendees). Open a recorded meeting -> summary, topics, action
+ *     items and transcript.
+ *   - Schedule a meeting: pick an event type, a day and time, enter the attendee, confirm, and the invite is
+ *     emailed (external, confirmed inside BookingPage).
+ *   - Calendar connection and working hours live in SchedulingScreen; Google or Microsoft sign-in is only possible
+ *     in the graph8 app, so this screen links out instead of showing a dead button.
+ *
+ * SDK operations (through the composed parts): listBookings, getBooking, confirmBooking (external), cancelBooking
+ * (destructive), addBookingNote (external), listMeetings, getMeeting, listEventTypes, getEventType,
+ * getAvailableSlots, createBooking (external). Every confirmation uses ConfirmSpendDialog.
+ *
+ * Slots (all optional): renderDetailActions, extraDetailTabs, toolbarActions.
+ */
+import { useMemo, useState, type ReactNode } from "react";
+import { CalendarClock, CalendarPlus, ExternalLink } from "lucide-react";
+import { Button, Skeleton } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { EmptyState } from "@/g8/components/empty-state";
+import { DetailPanel } from "@/g8/components/screen/detail-panel";
+import { FormSheet } from "@/g8/components/screen/form-sheet";
+import { ScreenLayout } from "@/g8/components/screen/screen-layout";
+import { SectionCard } from "@/g8/components/screen/section-card";
+import { SplitView } from "@/g8/components/screen/split-view";
+import { useUrlState } from "@/g8/hooks/use-url-state";
+import { g8Get } from "@/g8/lib/g8-client";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { useEventTypes } from "../hooks/use-event-types";
+import { listOf, type Booking } from "../lib/appointments-types";
+import { BookingPage } from "./booking-page";
+import { MeetingDetail } from "./meeting-detail";
+import { MeetingList, type MeetingSelection } from "./meeting-list";
+import { useBrand } from "@/g8/hooks/use-brand";
+
+export interface MeetingsScreenProps {
+  /** Where a person connects a calendar (graph8 app). */
+  connectCalendarUrl?: string;
+  /** Extra buttons in the detail header. */
+  renderDetailActions?: (selection: MeetingSelection) => ReactNode;
+  /** Extra tabs in the detail panel (for example the contact's CRM record). */
+  extraDetailTabs?: Array<{ id: string; label: string; render: (selection: MeetingSelection) => ReactNode }>;
+  /** Extra controls next to "Schedule a meeting". */
+  toolbarActions?: ReactNode;
+}
+
+const COUNT_CAP = 100;
+
+function parseSelection(raw: string | null | undefined): MeetingSelection | null {
+  const [kind, ...rest] = (raw ?? "").split(":");
+  const id = rest.join(":");
+  return id && (kind === "booking" || kind === "meeting") ? { kind, id } : null;
+}
+
+function useBookingCounts(refreshKey: number) {
+  const now = useMemo(() => new Date().toISOString(), []);
+  const q = useG8Query(async (signal) => {
+    const [upcoming, pending] = await Promise.all([
+      g8Get("/appointments/bookings", { after_start: now, take: COUNT_CAP, skip: 0 }, { signal }),
+      g8Get("/appointments/bookings", { status: "pending", take: COUNT_CAP, skip: 0 }, { signal }),
+    ]);
+    return { upcoming: listOf<Booking>(upcoming, "bookings"), pending: listOf<Booking>(pending, "bookings") };
+  }, [now, refreshKey]);
+  return q;
+}
+
+function countLabel(list: Booking[]): string {
+  return list.length >= COUNT_CAP ? `${COUNT_CAP}+` : String(list.length);
+}
+
+function ScheduleSheet({ open, onOpenChange, onBooked }: { open: boolean; onOpenChange: (open: boolean) => void; onBooked: () => void }) {
+  const types = useEventTypes();
+  const [chosen, setChosen] = useState<number | null>(null);
+  const eventTypeId = chosen ?? types.eventTypes.find((t) => !t.hidden)?.id ?? types.eventTypes[0]?.id ?? null;
+  return (
+    <FormSheet open={open} onOpenChange={onOpenChange} title="Schedule a meeting" description="Pick a time that works for the host, then enter who is joining.">
+      {types.error ? <ApiError error={types.error} title="Could not load event types" onRetry={() => void types.refetch()} /> : types.loading && !types.data ? <Skeleton className="h-32 w-full" aria-label="Loading event types" /> : eventTypeId == null ? (
+        <EmptyState icon={<CalendarClock className="size-8" />} title="No event types yet" description="Create an event type in Scheduling first, then book meetings with it here." />
+      ) : (
+        <div className="space-y-4">
+          <div className="space-y-1">
+            <label htmlFor="schedule-event-type" className="text-sm font-medium">Event type</label>
+            <select id="schedule-event-type" className="h-9 w-full rounded-md border bg-background px-2 text-sm" value={eventTypeId} onChange={(e) => setChosen(Number(e.target.value))}>
+              {types.eventTypes.map((t) => <option key={t.id} value={t.id}>{t.title} ({t.length} min)</option>)}
+            </select>
+          </div>
+          <BookingPage eventTypeId={eventTypeId} onBooked={onBooked} />
+        </div>
+      )}
+    </FormSheet>
+  );
+}
+
+export function MeetingsScreen({ connectCalendarUrl: connectCalendarUrlProp, renderDetailActions, extraDetailTabs, toolbarActions }: MeetingsScreenProps) {
+  const brand = useBrand();
+  const connectCalendarUrl = connectCalendarUrlProp ?? brand.appUrl;
+  const [raw, setRaw] = useUrlState("sel");
+  const [mode, setMode] = useUrlState("view");
+  const selection = parseSelection(raw);
+  const [version, setVersion] = useState(0);
+  const [scheduling, setScheduling] = useState(false);
+  const counts = useBookingCounts(version);
+  const changed = () => setVersion((v) => v + 1);
+  const close = () => { setRaw(null); setMode(null); };
+
+  const stats = [
+    { label: "Upcoming", value: counts.data ? countLabel(counts.data.upcoming) : "-", hint: "Meetings starting from now" },
+    { label: "Awaiting approval", value: counts.data ? countLabel(counts.data.pending) : "-", tone: counts.data && counts.data.pending.length > 0 ? ("warning" as const) : undefined, hint: "Pending bookings you can accept or decline" },
+  ];
+
+  const detail = selection ? (
+    <DetailPanel
+      title={selection.kind === "booking" ? "Booking" : "Recorded meeting"}
+      actions={renderDetailActions?.(selection)}
+      onClose={close}
+      onExpand={mode === "full" ? undefined : () => setMode("full")}
+      onCollapse={mode === "full" ? () => setMode(null) : undefined}
+      tabs={[
+        { id: "overview", label: "Overview", content: <MeetingDetail selection={selection} onChanged={changed} /> },
+        ...(extraDetailTabs ?? []).map((t) => ({ id: t.id, label: t.label, content: t.render(selection) })),
+      ]}
+    />
+  ) : null;
+
+  return (
+    <ScreenLayout
+      title="Meetings"
+      description="Everything booked and recorded, and the next meeting to prepare for."
+      icon={<CalendarClock className="size-5" />}
+      actions={<><Button onClick={() => setScheduling(true)}><CalendarPlus className="size-4" aria-hidden />Schedule a meeting</Button>{toolbarActions}</>}
+      stats={stats}
+    >
+      {counts.error ? <ApiError error={counts.error} title="Could not load meeting numbers" onRetry={() => void counts.refetch()} /> : null}
+      <SplitView
+        detailOpen={Boolean(selection)}
+        onCloseDetail={close}
+        expanded={mode === "full" && Boolean(selection)}
+        onExpandedChange={(full) => setMode(full ? "full" : null)}
+        detail={detail}
+        list={<MeetingList linkParam="sel" refreshKey={version} selectedId={selection?.id ?? null} onSelect={(s) => setRaw(`${s.kind}:${s.id}`)} />}
+      />
+      <SectionCard title="Calendar sync" description={`Google and Microsoft sign-in happens in the ${brand.linkLabel} app. Once connected, booked and recorded meetings appear here.`}>
+        <a className="inline-flex items-center gap-1 text-sm underline" href={connectCalendarUrl} target="_blank" rel="noreferrer">Connect a calendar in {brand.linkLabel}<ExternalLink className="size-3.5" aria-hidden /></a>
+      </SectionCard>
+      <ScheduleSheet open={scheduling} onOpenChange={setScheduling} onBooked={changed} />
+    </ScreenLayout>
+  );
+}

package/blocks/appointments/components/scheduling-screen.tsx

@@ -0,0 +1,122 @@
+"use client";
+
+/**
+ * SchedulingScreen: the finished scheduling product. Your event types (meeting links), their settings, a live
+ * preview of each booking page, and your weekly working hours and calendar status. No props are required.
+ *
+ * It composes: EventTypeEditor (create, edit, delete), BookingPage (the preview), AvailabilityEditor (hours,
+ * date overrides, connected calendars) and the useEventTypes list.
+ *
+ * Flows:
+ *   - Event types tab (full page with &view=full): see every event type with its length and status, create one, open one (deep link
+ *     ?id=<event type id>) for Overview (every field), Bookings (who booked it, open one to accept, decline, note or
+ *     cancel), Settings (edit, delete confirmed) and its Booking page preview. Booking from the preview is a real booking and emails the attendee (confirmed).
+ *   - Working hours tab: edit the weekly hours and date overrides of a schedule. Connecting a Google or Microsoft
+ *     calendar is only possible in the graph8 app, so the editor links out.
+ *
+ * SDK operations (through the composed parts): listEventTypes, getEventType, createEventType, updateEventType,
+ * deleteEventType (destructive, confirmed), listSchedules, getAvailability, updateAvailability, listCalendars,
+ * getAvailableSlots, createBooking (external, confirmed).
+ *
+ * Slots (all optional): renderRowActions, renderDetailActions, extraDetailTabs, toolbarActions.
+ */
+import { useState, type ReactNode } from "react";
+import { CalendarClock, Plus } from "lucide-react";
+import { Button, Skeleton, Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { EmptyState } from "@/g8/components/empty-state";
+import { DetailPanel } from "@/g8/components/screen/detail-panel";
+import { FormSheet } from "@/g8/components/screen/form-sheet";
+import { ScreenLayout } from "@/g8/components/screen/screen-layout";
+import { SplitView } from "@/g8/components/screen/split-view";
+import { StatusPill } from "@/g8/components/screen/status-pill";
+import { useUrlState } from "@/g8/hooks/use-url-state";
+import { useEventTypes } from "../hooks/use-event-types";
+import type { EventType } from "../lib/appointments-types";
+import { AvailabilityEditor } from "./availability-editor";
+import { BookingPage } from "./booking-page";
+import { EventTypeEditor } from "./event-type-editor";
+import { EventTypeBookings, EventTypeOverview } from "./event-type-related";
+import { rowActivationProps } from "@/g8/hooks/use-row-activation";
+
+export interface SchedulingScreenProps {
+  /** Where a person connects a calendar (graph8 app). */
+  connectCalendarUrl?: string;
+  renderRowActions?: (eventType: EventType) => ReactNode;
+  renderDetailActions?: (eventType: EventType) => ReactNode;
+  extraDetailTabs?: Array<{ id: string; label: string; render: (eventType: EventType) => ReactNode }>;
+  toolbarActions?: ReactNode;
+}
+
+const TABS = [{ id: "types", label: "Event types" }, { id: "hours", label: "Working hours" }];
+
+export function SchedulingScreen({ connectCalendarUrl, renderRowActions, renderDetailActions, extraDetailTabs, toolbarActions }: SchedulingScreenProps) {
+  const [tabParam, setTab] = useUrlState("tab", "types");
+  const [idParam, setId] = useUrlState("id");
+  const [mode, setMode] = useUrlState("view");
+  const [creating, setCreating] = useState(false);
+  const types = useEventTypes();
+  const tab = tabParam === "hours" ? "hours" : "types";
+  const selected = types.eventTypes.find((t) => String(t.id) === idParam);
+  const selectedId = idParam && /^\d+$/.test(idParam) ? Number(idParam) : null;
+  const close = () => { setId(null); setMode(null); };
+
+  const detail = selectedId != null ? (
+    <DetailPanel
+      title={selected?.title ?? "Event type"}
+      subtitle={selected ? `${selected.length} minutes` : undefined}
+      badges={selected?.hidden ? <StatusPill tone="neutral">Hidden</StatusPill> : undefined}
+      actions={selected ? renderDetailActions?.(selected) : undefined}
+      onClose={close}
+      onExpand={mode === "full" ? undefined : () => setMode("full")}
+      onCollapse={mode === "full" ? () => setMode(null) : undefined}
+      tabs={[
+        { id: "overview", label: "Overview", content: <EventTypeOverview key={selectedId} eventTypeId={selectedId} /> },
+        { id: "bookings", label: "Bookings", content: <EventTypeBookings key={selectedId} eventTypeId={selectedId} /> },
+        { id: "settings", label: "Settings", content: <EventTypeEditor key={selectedId} eventTypeId={selectedId} onSaved={() => void types.refetch()} onDeleted={() => { close(); void types.refetch(); }} /> },
+        { id: "preview", label: "Booking page", content: <BookingPage key={selectedId} eventTypeId={selectedId} /> },
+        ...(extraDetailTabs ?? []).map((t) => ({ id: t.id, label: t.label, content: selected ? t.render(selected) : null })),
+      ]}
+    />
+  ) : null;
+
+  const list = types.error ? <ApiError error={types.error} title="Could not load event types" onRetry={() => void types.refetch()} /> : types.loading && !types.data ? (
+    <div className="space-y-2" aria-busy="true" aria-label="Loading event types">{[0, 1, 2].map((i) => <Skeleton key={i} className="h-10 w-full" />)}</div>
+  ) : types.eventTypes.length === 0 ? (
+    <EmptyState icon={<CalendarClock className="size-8" />} title="No event types yet" description="An event type is a meeting link, like a 30 minute intro call. Create one and share its booking page." action={<Button onClick={() => setCreating(true)}>New event type</Button>} />
+  ) : (
+    <Table>
+      <TableHeader><TableRow><TableHead>Event type</TableHead><TableHead className="text-right">Length</TableHead><TableHead>Rules</TableHead>{renderRowActions ? <TableHead /> : null}</TableRow></TableHeader>
+      <TableBody>
+        {types.eventTypes.map((t) => (
+          <TableRow key={t.id} className="cursor-pointer" data-state={String(t.id) === idParam ? "selected" : undefined} {...rowActivationProps(() => setId(String(t.id)))}>
+            <TableCell><button type="button" className="font-medium hover:underline" onClick={(e) => { e.stopPropagation(); setId(String(t.id)); }}>{t.title}</button><div className="text-xs text-muted-foreground">/{t.slug}</div></TableCell>
+            <TableCell className="text-right tabular-nums">{t.length} min</TableCell>
+            <TableCell className="space-x-1">
+              {t.hidden ? <StatusPill tone="neutral">Hidden</StatusPill> : <StatusPill tone="positive" dot>Bookable</StatusPill>}
+              {t.requires_confirmation ? <StatusPill tone="info">Needs approval</StatusPill> : null}
+            </TableCell>
+            {renderRowActions ? <TableCell onClick={(e) => e.stopPropagation()}>{renderRowActions(t)}</TableCell> : null}
+          </TableRow>
+        ))}
+      </TableBody>
+    </Table>
+  );
+
+  return (
+    <ScreenLayout
+      title="Scheduling"
+      description="Meeting links people can book, and the hours you are available."
+      icon={<CalendarClock className="size-5" />}
+      actions={<>{toolbarActions}<Button onClick={() => setCreating(true)}><Plus className="size-4" aria-hidden />New event type</Button></>}
+      tabs={TABS.map((t) => (t.id === "types" ? { ...t, count: types.data ? types.eventTypes.length : undefined } : t))}
+      activeTab={tab}
+      onTabChange={(id) => { setTab(id); close(); }}
+    >
+      {tab === "hours" ? <AvailabilityEditor connectCalendarUrl={connectCalendarUrl} /> : <SplitView detailOpen={selectedId != null} onCloseDetail={close} expanded={mode === "full" && selectedId != null} onExpandedChange={(full) => setMode(full ? "full" : null)} detail={detail} list={list} />}
+      <FormSheet open={creating} onOpenChange={setCreating} title="New event type" description="Name it, set its length and pick the working hours it uses.">
+        {creating ? <EventTypeEditor onSaved={(et) => { setCreating(false); void types.refetch(); setTab("types"); setId(String(et.id)); }} /> : null}
+      </FormSheet>
+    </ScreenLayout>
+  );
+}

package/blocks/appointments/hooks/use-event-types.ts

@@ -0,0 +1,17 @@
+"use client";
+
+/**
+ * useEventTypes: the org's bookable event types (meeting links), newest data first.
+ *
+ * SDK operations: GET /event-types?include_hidden= (gtmLaunchHelpers.listEventTypes), read tier, scope campaigns:read.
+ * This is the list operation the editor and booking screens were missing: ids no longer have to be remembered.
+ * Hidden event types are included so a rep can still edit them.
+ */
+import { g8Get } from "@/g8/lib/g8-client";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { listOf, type EventType } from "../lib/appointments-types";
+
+export function useEventTypes() {
+  const query = useG8Query(async (signal) => listOf<EventType>(await g8Get("/event-types", { include_hidden: true }, { signal }), "event_types", "items"), []);
+  return { ...query, eventTypes: query.data ?? [] };
+}

package/blocks/block.schema.json

@@ -36,6 +36,24 @@
         }
       }
     },
+    "screens": {
+      "type": "array",
+      "description": "Optional. How the block's finished screens become routes and sidebar entries in an app made with `create --blocks`. Absent: derived from the components named `*Screen` (ContactsScreen -> /contacts, label Contacts, group = the block title, icon from a built-in per-block map).",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["component", "path", "label"],
+        "properties": {
+          "component": { "type": "string", "pattern": "^[A-Z][A-Za-z0-9]*$", "description": "A component of this block." },
+          "path": { "type": "string", "pattern": "^/[a-z0-9]+(-[a-z0-9]+)*(/[a-z0-9]+(-[a-z0-9]+)*)*$", "description": "Static route path. On a collision in a generated app it is prefixed with the block id." },
+          "label": { "type": "string", "minLength": 1 },
+          "icon": { "type": "string", "pattern": "^[A-Z][A-Za-z0-9]*$", "description": "A lucide-react export name." },
+          "group": { "type": "string", "minLength": 1, "description": "Sidebar section (default: the block title)." },
+          "description": { "type": "string", "minLength": 1 },
+          "order": { "type": "number", "description": "Sort position inside the block; lower first." }
+        }
+      }
+    },
     "hooks": {
       "type": "array",
       "items": {

package/blocks/block.types.ts

@@ -59,6 +59,21 @@ export interface BlockDefault {
   askHuman: boolean;
 }
 
+/** Optional route metadata for a finished screen (`create --blocks`, `add` inside a created app). */
+export interface BlockScreen {
+  /** A component of this block. */
+  component: string;
+  /** Static route path; prefixed with the block id when it collides in a generated app. */
+  path: string;
+  label: string;
+  /** lucide-react export name. */
+  icon?: string;
+  /** Sidebar section (default: the block title). */
+  group?: string;
+  description?: string;
+  order?: number;
+}
+
 export interface BlockManifest {
   $schema?: string;
   id: string;
@@ -71,6 +86,8 @@ export interface BlockManifest {
   /** Contract operationIds (keys of API_OPERATIONS). */
   operations: string[];
   components: BlockComponent[];
+  /** Optional. Absent: derived from the components named `*Screen`. */
+  screens?: BlockScreen[];
   hooks: BlockHook[];
   lib?: BlockFile[];
   server?: BlockServerFile[];
@@ -94,6 +111,13 @@ export interface StackNavItem {
   component: string;
   /** JSON props passed to the component on its route (for a component that needs input to render anything). */
   props?: Record<string, unknown>;
+  /** lucide-react export name shown beside the label in the sidebar (for example `Users`). */
+  icon?: string;
+  /** Sidebar section label. */
+  group?: string;
+  description?: string;
+  /** Hand-written page template (`pages/*.tsx.tmpl`, relative to `stacks/<stack-id>/`) used instead of the generic route page. */
+  page?: string;
 }
 
 export interface StackManifest {
@@ -106,4 +130,6 @@ export interface StackManifest {
   /** Install order: each block's `dependsOn` come earlier. */
   blocks: string[];
   nav: StackNavItem[];
+  /** A nav path that `/` redirects to. */
+  home?: string;
 }

package/blocks/campaigns/README.md

@@ -7,6 +7,26 @@ Apollo / HubSpot "campaigns" screen, with generation behind credit confirmations
 Depends on: `lists` (the audience picker), `mailboxes` (senders and the connect-a-mailbox link). Install:
 `npx @graph8/sdk add campaigns`.
 
+## Screens
+
+`CampaignsScreen` is the finished page: mount it as the route. Every record type has a complete detail view,
+deep-linkable (`?tab=campaigns|profile|personas`, `?id=` the record, `?dtab=` the tab, `?doc=` a document).
+
+- **Campaigns tab**: list (delete confirmed) beside a detail panel with Details (every field, audience, edit name,
+  goal and brief, confirmed), Metrics, Documents (each document opens with its fields and editor), Audience,
+  Sequence and Launch. "New campaign" runs the five-step wizard in a sheet.
+- **Company profile tab**: the profile plus ICPs; `IcpDetail` shows every field and edits, pins or archives.
+- **Personas tab**: `PersonaDetail` shows every field, the campaigns that target it, and edits, pins or archives.
+
+Slot props: `toolbarActions`, `renderDetailActions(campaign)`, `extraDetailTabs`, `websiteUrl`. Prerequisites: a
+company profile with the real website, an active mailbox, a contact list, and credits for AI generation.
+`IcpEditor` and `PersonaEditor` gained optional `onOpen` and `refreshKey`; `CampaignAssets` optional
+`documentId` and `onDocumentChange`.
+
+Known limits: there is no single-ICP read, so `IcpDetail` finds the ICP in the first 200 (the API maximum).
+`PersonaDetail` lists the campaigns whose `target_persona` matches the persona title among the first 100
+campaigns; the API does not link campaigns to ICPs, so ICPs show none.
+
 ## Components
 
 | Component | What it does | Tiers |
@@ -16,7 +36,7 @@ Depends on: `lists` (the audience picker), `mailboxes` (senders and the connect-
 | `CampaignWizard` | A page. Idea (AI, polled) -> create -> audience -> steps -> launch. Also exports the three step components below. | all |
 | `CampaignAudienceStep` | Attach or detach a contact list (uses the lists block `ListPicker`; reads `getCampaignFull`, since `getCampaign` omits the audience). | read, write, external |
 | `CampaignSequenceStep` | Add, edit, remove and AI-write sequence steps. | read, billable, external, destructive |
-| `CampaignLaunchStep` | Readiness checklist, sender choice, deliverability warning, confirmed launch. | read, external |
+| `CampaignLaunchStep` | Readiness checklist (audience, steps, written copy, sender), deliverability and warm-up hold warnings, writes missing email copy with AI, confirmed launch. | read, billable, external |
 | `CampaignList` | A page. All campaigns; open one for metrics and documents; delete. | read, billable, external, destructive |
 | `CampaignAssets` | Campaign documents: read, edit, rewrite with AI, add, delete. Standalone: shows a campaign picker. | read, billable, external, destructive |
 | `CampaignMetrics` | A page. Metrics for 7, 30, 90 or 365 days. Standalone: shows a campaign picker. | read |
@@ -40,15 +60,24 @@ read, so credit numbers are estimates: edit `CREDIT_ESTIMATES` in `lib/campaigns
 3. **Ideas.** `generateCampaignIdeasAsync` (billable) -> `task_id` -> poll `getCampaignIdeasTaskStatus` every
    2-3 seconds until `completed`; `ideas[]` carry `campaign_name`, `core_concept`, `primary_hook`.
 4. **Create.** `createCampaign` -> `id`. Store it at once; later steps reuse it and "Create" becomes
-   "Save changes" (`updateCampaign`). With `auto_generate_documents` the documents generate in the
-   background: poll `getCampaignGenerationStatus`.
+   "Save changes" (`updateCampaign`). With `auto_generate_documents` (on by default in the wizard and the
+   recipe) the documents generate in the background: poll `getCampaignGenerationStatus`; a `generation_error`
+   there, or `generation_status: "failed_to_dispatch"` on create, means the writing never started.
 5. **Audience.** `getCampaignFull` shows what is attached (`audience_list_id`, `audience`). `ListPicker` (lists block) -> a list `id` -> `attachAudienceToCampaign` with `list_id` as a
    string. Build the list in the search/lists blocks first.
 6. **Steps and copy.** `getCampaignSequence` -> `createCampaignStep` (channel -> mode matrix: email -> email,
    phone -> call|voicemail, sms -> sms, social -> connect_note|dm|comment|reply) -> `generateCampaignStepContent`
-   (billable) per step. `CampaignAssets` edits the documents behind them.
-7. **Launch.** `CampaignLaunchStep` -> `getCampaignFull` (audience attached with its size, >= 1 step, `is_launched`),
-   `listMailboxes` (active ones), `getSafeToSend` (a warning) -> `launchCampaign` with `sender_mailbox_ids`.
+   (billable) per step. `CampaignAssets` edits the documents behind them. Writing an EMAIL step needs the
+   campaign's `emails` document to exist already (created by `auto_generate_documents`); without it the step
+   write answers 404.
+7. **Launch.** `CampaignLaunchStep` -> `getCampaignFull` (audience attached with its size, >= 1 step, written copy,
+   `is_launched`), `listMailboxes` (active ones), `getSafeToSend` (`safe`, a warning) -> `launchCampaign` with
+   `sender_mailbox_ids`. The launch is refused (400 "no completed copy documents") unless a document other than
+   `sequence` and `step_catalog` has `status: "completed"`, so Launch stays disabled until one does; "Write the
+   email copy with AI" creates the `emails` document if missing (`createCampaignDocument`, once) and has AI write it
+   (`regenerateCampaignDocument`, billable). `is_launched` is true only for a live launch, so a failed launch can be
+   retried. A mailbox added less than 14 days ago is in its warm-up hold: the campaign goes live but sends nothing
+   from it until the hold ends (the step warns).
    The one-step launch executes email only; configure other channels in the sequencer block.
 8. **Measure.** `CampaignMetrics` -> `getCampaignMetrics` with `days`.
 
@@ -62,8 +91,9 @@ read, so credit numbers are estimates: edit `CREDIT_ESTIMATES` in `lib/campaigns
 
 ## Defaults (do not ask the human)
 
-- 5 ideas, goal `awareness`, channel `email`, no auto-generated documents (generate per step so each spend is
-  confirmed), sender = the first active mailbox.
+- 5 ideas, goal `awareness`, channel `email`, AI-written documents ON (a campaign without written copy cannot
+  launch; the create confirmation shows the spend), personas picked by AI when none are chosen
+  (`persona_mode: "ai_pick"`), sender = the first active mailbox.
 - **Ask the human**: whether to launch and to which list (state the recipient count), and whether to approve
   (lock) the company profile.
 
@@ -95,7 +125,7 @@ read, so credit numbers are estimates: edit `CREDIT_ESTIMATES` in `lib/campaigns
 | `get_campaign_ideas_task_status_campaigns_ideas_status__task_id__get` | GET /campaigns/ideas/status/{task_id} | read | CampaignWizard |
 | `create_campaign_campaigns_post` | POST /campaigns | external | CampaignWizard |
 | `update_campaign_campaigns__campaign_id__patch` | PATCH /campaigns/{campaign_id} | external | CampaignWizard |
-| `get_campaign_generation_status_campaigns__campaign_id__status_get` | GET /campaigns/{campaign_id}/status | read | CampaignWizard |
+| `get_campaign_generation_status_campaigns__campaign_id__status_get` | GET /campaigns/{campaign_id}/status | read | CampaignWizard, CampaignLaunchStep |
 | `get_campaign_full_campaigns__campaign_id__full_get` | GET /campaigns/{campaign_id}/full | read | CampaignWizard, CampaignAudienceStep, CampaignLaunchStep |
 | `attach_audience_to_campaign_campaigns__campaign_id__audience_put` | PUT /campaigns/{campaign_id}/audience | external | CampaignWizard, CampaignAudienceStep |
 | `get_campaign_sequence_campaigns__campaign_id__sequence_get` | GET /campaigns/{campaign_id}/sequence | read | CampaignWizard, CampaignSequenceStep |
@@ -112,7 +142,7 @@ read, so credit numbers are estimates: edit `CREDIT_ESTIMATES` in `lib/campaigns
 | `get_campaign_metrics_campaigns__campaign_id__metrics_get` | GET /campaigns/{campaign_id}/metrics | read | CampaignList, CampaignMetrics |
 | `list_campaign_documents_campaigns__campaign_id__documents_get` | GET /campaigns/{campaign_id}/documents | read | CampaignList, CampaignAssets |
 | `get_campaign_document_campaigns__campaign_id__documents__document_id__get` | GET /campaigns/{campaign_id}/documents/{document_id} | read | CampaignList, CampaignAssets |
-| `create_campaign_document_campaigns__campaign_id__documents_post` | POST /campaigns/{campaign_id}/documents | external | CampaignList, CampaignAssets |
+| `create_campaign_document_campaigns__campaign_id__documents_post` | POST /campaigns/{campaign_id}/documents | external | CampaignWizard, CampaignLaunchStep, CampaignList, CampaignAssets |
 | `update_campaign_document_campaigns__campaign_id__documents__document_id__put` | PUT /campaigns/{campaign_id}/documents/{document_id} | external | CampaignList, CampaignAssets |
 | `delete_campaign_document_campaigns__campaign_id__documents__document_id__delete` | DELETE /campaigns/{campaign_id}/documents/{document_id} | destructive | CampaignList, CampaignAssets |
-| `regenerate_campaign_document_campaigns__campaign_id__documents__document_id__regenerate_post` | POST /campaigns/{campaign_id}/documents/{document_id}/regenerate | billable | CampaignList, CampaignAssets |
+| `regenerate_campaign_document_campaigns__campaign_id__documents__document_id__regenerate_post` | POST /campaigns/{campaign_id}/documents/{document_id}/regenerate | billable | CampaignWizard, CampaignLaunchStep, CampaignList, CampaignAssets |