@graph8/sdk 0.362.0 → 0.370.0

package/blocks/analytics/components/report-detail.tsx

@@ -0,0 +1,84 @@
+"use client";
+
+/**
+ * ReportDetail: everything about one saved custom-object report: its definition (object, measure, grouping, filters,
+ * chart type, visibility, revision, owner dates), the latest result table, and the actions Run again and Delete.
+ *
+ * SDK operations, in order:
+ *   1. GET    /reports/{id}          (reports.getObjectReportApi)       read    the definition
+ *   2. POST   /reports/{id}/execute  (reports.executeObjectReportApi)   write   run it (creates a run record, sends nothing); runs once on open
+ *   3. DELETE /reports/{id}          (reports.archiveObjectReportApi)   DESTRUCTIVE -> ConfirmSpendDialog
+ * Editing happens in ReportBuilder (`reportId`). Preview and execute share the org's report-run slots (429 `too_many_report_runs`).
+ */
+import { useEffect, useState } from "react";
+import { Button, Skeleton } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
+import { KeyValueList } from "@/g8/components/screen/key-value-list";
+import { StatusPill } from "@/g8/components/screen/status-pill";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { g8Delete, g8Get, g8Post } from "@/g8/lib/g8-client";
+import { reportBody, type ReportResultData, type SavedReport } from "../lib/analytics-types";
+import { ResultTable } from "./report-builder";
+
+export interface ReportDetailProps {
+  reportId: string;
+  /** Called after the report was deleted. */
+  onDeleted?: () => void;
+  /** A result the host already holds (kept across tab switches). While set, opening does not run the report again. */
+  result?: ReportResultData | null;
+  /** Called with every fresh result, so the host can keep it. */
+  onResult?: (result: ReportResultData | null) => void;
+  className?: string;
+}
+
+type Cfg = { measures?: Array<Record<string, unknown>>; group_by?: Array<Record<string, unknown>>; filters?: unknown[] };
+
+const measureText = (m: Record<string, unknown> | undefined): string => (m ? `${String(m.kind)}${m.attribute_slug ? ` of ${String(m.attribute_slug)}` : ""}` : "");
+const groupText = (g: Record<string, unknown> | undefined): string => (g ? (g.kind === "created_at" ? `created date by ${String(g.grain ?? "month")}` : String(g.attribute_slug ?? "")) : "None");
+
+export function ReportDetail({ reportId, onDeleted, result: given, onResult, className }: ReportDetailProps) {
+  const [confirming, setConfirming] = useState(false);
+  const [own, setOwn] = useState<ReportResultData | null>(null);
+  const result = given ?? own;
+  const setResult = (r: ReportResultData | null) => { setOwn(r); onResult?.(r); };
+  const report = useG8Query(async (signal) => reportBody<SavedReport>(await g8Get(`/reports/${encodeURIComponent(reportId)}`, undefined, { signal })), [reportId]);
+  const run = useG8Mutation(async () => { const out = reportBody<ReportResultData>(await g8Post(`/reports/${encodeURIComponent(reportId)}/execute`, {})); setResult(out); return out; });
+  const remove = useG8Mutation(async () => { await g8Delete(`/reports/${encodeURIComponent(reportId)}`); }, { onSuccess: () => { setConfirming(false); onDeleted?.(); }, onError: () => setConfirming(false) });
+
+  // A different report starts clean; it runs once on open unless the host already holds a result.
+  useEffect(() => { run.reset(); if (!given) void run.mutate(undefined); }, [reportId]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  const r = report.data;
+  const cfg = (r?.config ?? {}) as Cfg;
+  if (report.error) return <ApiError error={report.error} title="Could not load the report" onRetry={() => void report.refetch()} />;
+  if (!r) return <Skeleton className="h-40 w-full" aria-label="Loading report" />;
+
+  return (
+    <div className={`space-y-4 ${className ?? ""}`} data-testid="report-detail">
+      <div className="flex flex-wrap items-center gap-2">
+        <StatusPill tone={r.visibility === "private" ? "neutral" : "info"}>{r.visibility}</StatusPill>
+        <span className="text-xs text-muted-foreground">Revision {r.revision}</span>
+        <div className="ml-auto flex gap-2">
+          <Button size="sm" variant="outline" loading={run.loading} onClick={() => void run.mutate(undefined)}>Run again</Button>
+          {r.can_delete ? <Button size="sm" variant="ghost" onClick={() => setConfirming(true)}>Delete</Button> : null}
+        </div>
+      </div>
+      <KeyValueList columns={2} items={[
+        { label: "Object", value: r.source.plural_noun, mono: false },
+        { label: "Object slug", value: r.source.slug, mono: true },
+        { label: "Chart", value: r.chart_type },
+        { label: "Measure", value: (cfg.measures ?? []).map(measureText).join(", ") || "count" },
+        { label: "Grouped by", value: (cfg.group_by ?? []).map(groupText).join(", ") || "None" },
+        { label: "Filters", value: (cfg.filters ?? []).length ? `${(cfg.filters ?? []).length} applied` : "None" },
+      ]} />
+      {run.error ? <ApiError error={run.error} title="Could not run the report" onRetry={() => void run.mutate(undefined)} /> : null}
+      {run.loading && !result ? <Skeleton className="h-24 w-full" aria-label="Running report" /> : null}
+      {result ? <ResultTable result={result} /> : null}
+      {remove.error ? <ApiError error={remove.error} title="Could not delete the report" /> : null}
+      <ConfirmSpendDialog open={confirming} tier="destructive" title={`Delete "${r.title}"?`} description="The saved report is removed for everyone who can see it. The underlying records are not touched."
+        confirmLabel="Delete report" affected={1} confirming={remove.loading} onConfirm={() => void remove.mutate(undefined)} onCancel={() => setConfirming(false)} />
+    </div>
+  );
+}

package/blocks/analytics/components/trend-chart.tsx

@@ -0,0 +1,62 @@
+"use client";
+
+/**
+ * TrendChart: a daily line chart for one outbound channel (email, calls or meetings), drawn with the kit TimeSeriesChart (recharts).
+ *
+ * SDK operations (pick the channel):
+ *   channel "email":    GET /analytics/outbound/email-metrics/trend?days=    (analytics.getEmailTrend)    read   rows { date, sent, replied, ... }
+ *   channel "calls":    GET /analytics/outbound/call-metrics/trend?days=     (analytics.getCallTrend)     read   rows { date, dials, connected, ... }
+ *   channel "meetings": GET /analytics/outbound/meeting-metrics/trend?days=  (analytics.getMeetingTrend)  read   rows { date, booked, cancelled, held, ... }
+ * Two series per channel (the volume and the outcome). Dates are plain `YYYY-MM-DD` days and are shown as UTC days.
+ */
+import { Skeleton } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { EmptyState } from "@/g8/components/empty-state";
+import { TimeSeriesChart } from "@/g8/components/screen/time-series-chart";
+import { useReport } from "../hooks/use-report";
+import { formatNumber } from "../lib/analytics-types";
+
+export type TrendChannel = "email" | "calls" | "meetings";
+
+export const TREND_SERIES: Record<TrendChannel, { path: string; keys: [string, string]; labels: [string, string] }> = {
+  email: { path: "/analytics/outbound/email-metrics/trend", keys: ["sent", "replied"], labels: ["Sent", "Replied"] },
+  calls: { path: "/analytics/outbound/call-metrics/trend", keys: ["dials", "connected"], labels: ["Dials", "Connected"] },
+  meetings: { path: "/analytics/outbound/meeting-metrics/trend", keys: ["booked", "held"], labels: ["Booked", "Held"] },
+};
+
+export type TrendRow = { date?: string } & Record<string, unknown>;
+
+/** Daily values of one key, in date order. */
+export function seriesOf(rows: TrendRow[] | undefined, key: string): number[] {
+  return (Array.isArray(rows) ? rows : []).map((r) => Number(r[key] ?? 0) || 0);
+}
+
+export interface TrendChartProps {
+  channel?: TrendChannel;
+  days?: number;
+  className?: string;
+}
+
+export function TrendChart({ channel = "email", days = 30, className }: TrendChartProps) {
+  const spec = TREND_SERIES[channel];
+  const { data, loading, error, refetch } = useReport<TrendRow[]>(spec.path, { days });
+  const rows = Array.isArray(data) ? data : [];
+  const a = seriesOf(rows, spec.keys[0]);
+  const b = seriesOf(rows, spec.keys[1]);
+  const total = (v: number[]) => v.reduce((x, y) => x + y, 0);
+
+  if (error) return <ApiError error={error} title="Could not load the trend" onRetry={() => void refetch()} />;
+  if (loading && !data) return <Skeleton className="h-48 w-full" aria-label="Loading trend" />;
+  if (rows.length === 0 || total(a) === 0) return <EmptyState className={className} title="No activity in this window" description="Daily numbers appear here as emails, calls and meetings are recorded." />;
+
+  return (
+    <figure className={className} aria-label={`${channel} trend`}>
+      <div className="mb-2 flex flex-wrap gap-4 text-xs text-muted-foreground">
+        <span>{spec.labels[0]} {formatNumber(total(a))}</span>
+        <span>{spec.labels[1]} {formatNumber(total(b))}</span>
+      </div>
+      <TimeSeriesChart data={rows} xKey="date" kind="line" height={200}
+        series={[{ key: spec.keys[0], label: spec.labels[0] }, { key: spec.keys[1], label: spec.labels[1], tone: "positive" }]} />
+    </figure>
+  );
+}

package/blocks/appointments/block.json

@@ -113,8 +113,12 @@
       "name": "MeetingsScreen",
       "file": "components/meetings-screen.tsx",
       "purpose": "Finished meetings product: upcoming, past, cancelled and recorded meetings with detail, approvals, notes and a schedule-a-meeting flow.",
-      "operations": [],
-      "tiers": []
+      "operations": [
+        "list_bookings_appointments_bookings_get"
+      ],
+      "tiers": [
+        "read"
+      ]
     },
     {
       "name": "SchedulingScreen",

package/blocks/appointments/components/availability-editor.tsx

@@ -23,6 +23,7 @@ import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
 import { useG8Query } from "@/g8/hooks/use-g8-query";
 import { useSchedules } from "../hooks/use-schedules";
 import { WEEKDAYS, listOf, toHHMM, unwrap, type AvailabilityRule, type Schedule, type TimeWindow } from "../lib/appointments-types";
+import { useBrand } from "@/g8/hooks/use-brand";
 
 export interface AvailabilityEditorProps {
   /** Schedule to edit; defaults to the org's default schedule. */
@@ -72,6 +73,7 @@ function WindowRow({ window: w, onChange, onRemove }: { window: TimeWindow; onCh
 }
 
 function CalendarPanel({ connectUrl }: { connectUrl: string }) {
+  const brand = useBrand();
   const cals = useG8Query(async (signal) => listOf<CalendarRow>(await g8Get("/appointments/calendars", undefined, { signal }), "calendars"), []);
   return (
     <section aria-label="Calendars" className="space-y-2 rounded-lg border p-3 text-sm">
@@ -84,22 +86,26 @@ function CalendarPanel({ connectUrl }: { connectUrl: string }) {
       ))}
       {!cals.loading && !cals.error && (cals.data ?? []).length === 0 ? <p className="text-muted-foreground">No calendar connected, so busy time is not checked.</p> : null}
       <a className="underline" href={connectUrl} target="_blank" rel="noreferrer">
-        Connect or manage calendars in graph8
+        Connect or manage calendars in {brand.linkLabel}
       </a>
     </section>
   );
 }
 
-export function AvailabilityEditor({ scheduleId, connectCalendarUrl = "https://app.graph8.com", onSaved, className }: AvailabilityEditorProps) {
+export function AvailabilityEditor({ scheduleId, connectCalendarUrl: connectCalendarUrlProp, onSaved, className }: AvailabilityEditorProps) {
+  const brand = useBrand();
+  const connectCalendarUrl = connectCalendarUrlProp ?? brand.appUrl;
   const { schedules, loading: loadingSchedules, error: schedulesError } = useSchedules();
   const [picked, setPicked] = useState<number | undefined>(scheduleId);
   const activeId = picked ?? schedules[0]?.id;
   const [week, setWeek] = useState<Week>({});
   const [overrides, setOverrides] = useState<Override[]>([]);
   const [newDate, setNewDate] = useState("");
+  /** The schedule whose hours are in the form. Save is offered only for a schedule that has loaded, never over a blank week. */
+  const [appliedFor, setAppliedFor] = useState<number | undefined>(undefined);
 
   // Stale context: switching schedule must not show (or save!) the previous schedule's hours.
-  useEffect(() => { setWeek({}); setOverrides([]); }, [activeId]);
+  useEffect(() => { setWeek({}); setOverrides([]); setAppliedFor(undefined); }, [activeId]);
 
   const availability = useG8Query(
     async (signal) => unwrap<Schedule>(await g8Get(`/appointments/schedules/${activeId}/availability`, undefined, { signal })),
@@ -109,9 +115,10 @@ export function AvailabilityEditor({ scheduleId, connectCalendarUrl = "https://a
   useEffect(() => {
     const data = availability.data;
     if (!data) return;
+    setAppliedFor(activeId);
     setWeek(toWeek(data.availability ?? []));
     setOverrides((data.overrides ?? []).filter((o) => o.date).map((o) => ({ date: o.date as string, start: toHHMM(o.start_time), end: toHHMM(o.end_time, "17:00") })));
-  }, [availability.data]);
+  }, [availability.data, activeId]);
 
   const save = useG8Mutation(
     async () =>
@@ -122,10 +129,11 @@ export function AvailabilityEditor({ scheduleId, connectCalendarUrl = "https://a
     { onSuccess: () => onSaved?.() },
   );
 
+  const ready = appliedFor === activeId && !availability.error && !availability.loading;
   const setDay = (day: number, windows: TimeWindow[]) => setWeek((w) => ({ ...w, [day]: windows }));
   if (schedulesError) return <ApiError error={schedulesError} title="Could not load schedules" />;
   if (loadingSchedules) return <Skeleton className="h-64 w-full" aria-label="Loading schedules" />;
-  if (activeId == null) return <EmptyState title="No schedule yet" description="Create a working-hours schedule in graph8 (or POST /appointments/schedules), then edit it here." />;
+  if (activeId == null) return <EmptyState title="No schedule yet" description={`Create a working-hours schedule in ${brand.linkLabel} (or POST /appointments/schedules), then edit it here.`} />;
 
   return (
     <div className={`space-y-4 ${className ?? ""}`}>
@@ -141,6 +149,8 @@ export function AvailabilityEditor({ scheduleId, connectCalendarUrl = "https://a
       <p className="text-sm text-muted-foreground">Times are wall-clock hours in the schedule's time zone: {schedules.find((x) => x.id === activeId)?.time_zone ?? "the schedule's zone"}.</p>
       {availability.error ? <ApiError error={availability.error} title="Could not load availability" onRetry={() => void availability.refetch()} /> : null}
 
+      {!ready ? (availability.error ? null : <Skeleton className="h-48 w-full" aria-label="Loading availability" />) : (
+      <>
       <div className="space-y-2">
         {WEEKDAYS.map(({ day, label }) => {
           const windows = week[day] ?? [];
@@ -186,6 +196,8 @@ export function AvailabilityEditor({ scheduleId, connectCalendarUrl = "https://a
       <Button onClick={() => void save.mutate(undefined)} loading={save.loading}>
         Save availability
       </Button>
+      </>
+      )}
       <CalendarPanel connectUrl={connectCalendarUrl} />
     </div>
   );

package/blocks/appointments/components/event-type-editor.tsx

@@ -116,7 +116,8 @@ export function EventTypeEditor({ eventTypeId, onSaved, onDeleted, className }:
   const valid = form.title.trim().length > 0 && form.length >= 5 && (slugTouched ? form.slug.trim().length > 0 : true);
 
   if (existing.error) return <ApiError error={existing.error} title="Could not load the event type" onRetry={() => void existing.refetch()} />;
-  if (eventTypeId != null && existing.loading && !existing.data) return <Skeleton className="h-64 w-full" aria-label="Loading event type" />;
+  // Also while the NEXT event type loads (the hook keeps the previous one's data meanwhile): the form is blank then, and saving it would blank the record.
+  if (eventTypeId != null && (existing.loading || !existing.data)) return <Skeleton className="h-64 w-full" aria-label="Loading event type" />;
 
   return (
     <form

package/blocks/appointments/components/event-type-related.tsx

@@ -21,6 +21,8 @@ import { g8Get } from "@/g8/lib/g8-client";
 import { useG8Query } from "@/g8/hooks/use-g8-query";
 import { formatDateTime, listOf, unwrap, type Booking, type EventType } from "../lib/appointments-types";
 import { MeetingDetail } from "./meeting-detail";
+import { rowActivationProps } from "@/g8/hooks/use-row-activation";
+import { RecordLink } from "@/g8/components/screen/record-link";
 
 export function EventTypeOverview({ eventTypeId }: { eventTypeId: number }) {
   const q = useG8Query(async (signal) => unwrap<EventType>(await g8Get(`/appointments/event-types/${eventTypeId}`, undefined, { signal })), [eventTypeId]);
@@ -52,8 +54,8 @@ export function EventTypeBookings({ eventTypeId, pageSize = 20 }: { eventTypeId:
         <TableHeader><TableRow><TableHead>When</TableHead><TableHead>Attendees</TableHead><TableHead>Status</TableHead></TableRow></TableHeader>
         <TableBody>
           {q.data.map((b) => (
-            <TableRow key={b.uid} className="cursor-pointer" onClick={() => setOpen(b.uid)}>
-              <TableCell><button type="button" className="font-medium hover:underline" onClick={(e) => { e.stopPropagation(); setOpen(b.uid); }}>{formatDateTime(b.start_time)}</button></TableCell>
+            <TableRow key={b.uid} className="cursor-pointer" {...rowActivationProps(() => setOpen(b.uid))}>
+              <TableCell><RecordLink id={b.uid} onOpen={() => setOpen(b.uid)}>{formatDateTime(b.start_time)}</RecordLink></TableCell>
               <TableCell className="max-w-64 truncate">{b.attendees.map((a) => a.name || a.email).join(", ") || "No attendees"}</TableCell>
               <TableCell><StatusPill tone={toneForStatus(b.status)} dot>{humanizeStatus(b.status)}</StatusPill></TableCell>
             </TableRow>

package/blocks/appointments/components/meeting-list.tsx

@@ -19,11 +19,15 @@ import { EmptyState } from "@/g8/components/empty-state";
 import { g8Get } from "@/g8/lib/g8-client";
 import { useG8Query } from "@/g8/hooks/use-g8-query";
 import { formatDateTime, listOf, type Booking, type RecordedMeeting } from "../lib/appointments-types";
+import { rowActivationProps } from "@/g8/hooks/use-row-activation";
+import { RecordLink } from "@/g8/components/screen/record-link";
 
 export type MeetingView = "upcoming" | "past" | "cancelled" | "recorded";
 export type MeetingSelection = { kind: "booking"; id: string } | { kind: "meeting"; id: string };
 
 export interface MeetingListProps {
+  /** URL param the host screen reads for this record type. With it the name is a real link (Cmd-click opens it in a new tab); without it a plain button. */
+  linkParam?: string;
   onSelect?: (selection: MeetingSelection) => void;
   initialView?: MeetingView;
   pageSize?: number;
@@ -58,7 +62,7 @@ function useDebouncedText(value: string, ms = 300): string {
   return v;
 }
 
-export function MeetingList({ onSelect, initialView = "upcoming", pageSize = 20, refreshKey, selectedId, className }: MeetingListProps) {
+export function MeetingList({ linkParam, onSelect, initialView = "upcoming", pageSize = 20, refreshKey, selectedId, className }: MeetingListProps) {
   const [view, setView] = useState<MeetingView>(initialView);
   const [page, setPage] = useState(0);
   const [search, setSearch] = useState("");
@@ -120,17 +124,17 @@ export function MeetingList({ onSelect, initialView = "upcoming", pageSize = 20,
           <TableBody>
             {result.kind === "booking"
               ? (result.items as Booking[]).map((b) => (
-                  <TableRow key={b.uid} data-state={selectedId === b.uid ? "selected" : undefined} className="cursor-pointer" onClick={() => onSelect?.({ kind: "booking", id: b.uid })}>
+                  <TableRow key={b.uid} data-state={selectedId === b.uid ? "selected" : undefined} className="cursor-pointer" {...(onSelect ? rowActivationProps(() => onSelect({ kind: "booking", id: b.uid })) : {})}>
                     <TableCell className="whitespace-nowrap">{formatDateTime(b.start_time)}</TableCell>
-                    <TableCell className="font-medium">{b.title || b.event_type_title || "Meeting"}</TableCell>
+                    <TableCell className="font-medium">{onSelect ? <RecordLink param={linkParam} id={`booking:${b.uid}`} onOpen={() => onSelect({ kind: "booking", id: b.uid })}>{b.title || b.event_type_title || "Meeting"}</RecordLink> : b.title || b.event_type_title || "Meeting"}</TableCell>
                     <TableCell className="max-w-64 truncate">{attendeeNames(b)}</TableCell>
                     <TableCell className="capitalize">{b.status}</TableCell>
                   </TableRow>
                 ))
               : (result.items as RecordedMeeting[]).map((m) => (
-                  <TableRow key={m.id} data-state={selectedId === m.id ? "selected" : undefined} className="cursor-pointer" onClick={() => onSelect?.({ kind: "meeting", id: m.id })}>
+                  <TableRow key={m.id} data-state={selectedId === m.id ? "selected" : undefined} className="cursor-pointer" {...(onSelect ? rowActivationProps(() => onSelect({ kind: "meeting", id: m.id })) : {})}>
                     <TableCell className="whitespace-nowrap">{formatDateTime(m.start_time)}</TableCell>
-                    <TableCell className="font-medium">{m.subject || "Untitled meeting"}</TableCell>
+                    <TableCell className="font-medium">{onSelect ? <RecordLink param={linkParam} id={`meeting:${m.id}`} onOpen={() => onSelect({ kind: "meeting", id: m.id })}>{m.subject || "Untitled meeting"}</RecordLink> : m.subject || "Untitled meeting"}</TableCell>
                     <TableCell className="max-w-64 truncate">{m.transcript_summary || "No summary yet"}</TableCell>
                     <TableCell className="capitalize">{m.transcript_status ?? "none"}</TableCell>
                   </TableRow>

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

@@ -40,6 +40,7 @@ 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). */
@@ -99,7 +100,9 @@ function ScheduleSheet({ open, onOpenChange, onBooked }: { open: boolean; onOpen
   );
 }
 
-export function MeetingsScreen({ connectCalendarUrl = "https://app.graph8.com", renderDetailActions, extraDetailTabs, toolbarActions }: MeetingsScreenProps) {
+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);
@@ -143,10 +146,10 @@ export function MeetingsScreen({ connectCalendarUrl = "https://app.graph8.com",
         expanded={mode === "full" && Boolean(selection)}
         onExpandedChange={(full) => setMode(full ? "full" : null)}
         detail={detail}
-        list={<MeetingList refreshKey={version} selectedId={selection?.id ?? null} onSelect={(s) => setRaw(`${s.kind}:${s.id}`)} />}
+        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 graph8 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 graph8<ExternalLink className="size-3.5" aria-hidden /></a>
+      <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

@@ -37,6 +37,7 @@ 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). */
@@ -88,7 +89,7 @@ export function SchedulingScreen({ connectCalendarUrl, renderRowActions, renderD
       <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} onClick={() => setId(String(t.id))}>
+          <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">

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[];

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 |