@graph8/sdk 0.370.0 → 0.374.0

package/blocks/documents/components/question-row.tsx

@@ -0,0 +1,130 @@
+"use client";
+
+/**
+ * QuestionRow: one question of a security questionnaire with the AI's answer and every review action.
+ *
+ * SDK operations, in order (each is one button; the row shows its own spinner and error):
+ *   1. updateQuestionnaireAnswer (PATCH .../questions/{question_id})            write  replace the answer with a human one; the AI's original is kept beside it
+ *   2. approveQuestionnaireAnswer (POST .../questions/{question_id}/approve)    write  confirm the answer is right (no text changes)
+ *   3. escalateQuestionnaireQuestion (POST .../escalate)                         write  hand it to the security team, with notes
+ *   4. skipQuestionnaireQuestion (POST .../mark-skip)                            write  not applicable to this organization; the workbook says so
+ *   5. flagQuestionnaireAnswer (POST .../mark-wrong)                             write  say the AI's answer is wrong so a person rewrites it
+ *   6. saveQuestionnaireAnswerToLibrary (POST .../save-to-library)               write  keep the answer as org knowledge: the NEXT questionnaire is answered from it
+ * Nothing here is billable, external or destructive. After any action the questionnaire is read again, so the row shows the
+ * state the API holds, never a guess.
+ */
+
+import { useState } from "react";
+import { BookmarkPlus, Check, Flag, MinusCircle, Pencil, UserRound } from "lucide-react";
+import { Button, Textarea } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { StatusPill } from "@/g8/components/screen/status-pill";
+import { g8Patch, g8Post } from "@/g8/lib/g8-client";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { answerOf, reviewState } from "../lib/documents-types";
+import type { Question, Rec } from "../lib/documents-types";
+
+export interface QuestionRowProps {
+  accountId: number | string;
+  questionnaireId: string;
+  question: Question;
+  /** Called after any action succeeds, so the questionnaire is read again. */
+  onChanged: () => void;
+}
+
+type Mode = null | "edit" | "escalate" | "skip" | "wrong";
+type Action = { kind: "edit"; text: string } | { kind: "approve" } | { kind: "escalate" | "skip" | "wrong"; notes: string } | { kind: "library" };
+
+const NOTE_COPY: Record<"escalate" | "skip" | "wrong", { label: string; confirm: string; hint: string }> = {
+  escalate: { label: "Notes for the security team", confirm: "Escalate", hint: "What the person picking this up needs to know." },
+  skip: { label: "Why it does not apply (optional)", confirm: "Mark not applicable", hint: "The filled workbook says this question does not apply." },
+  wrong: { label: "What is wrong with the answer (optional)", confirm: "Mark wrong", hint: "A person rewrites it; this does not change the text." },
+};
+
+export function QuestionRow({ accountId, questionnaireId, question: q, onChanged }: QuestionRowProps) {
+  const [mode, setMode] = useState<Mode>(null);
+  const [text, setText] = useState("");
+  const [saved, setSaved] = useState<string | null>(null);
+  const base = `/accounts/${encodeURIComponent(String(accountId))}/security-questionnaires/${encodeURIComponent(questionnaireId)}/questions/${encodeURIComponent(q.id)}`;
+  const state = reviewState(q);
+  const current = answerOf(q);
+
+  const run = useG8Mutation(
+    async (a: Action): Promise<Rec> => {
+      if (a.kind === "edit") return (await g8Patch<Rec>(base, { final_answer: a.text })).data;
+      if (a.kind === "approve") return (await g8Post<Rec>(`${base}/approve`)).data;
+      if (a.kind === "library") return (await g8Post<Rec>(`${base}/save-to-library`)).data;
+      const notes = a.notes.trim() || null;
+      if (a.kind === "escalate") return (await g8Post<Rec>(`${base}/escalate`, { notes })).data;
+      if (a.kind === "skip") return (await g8Post<Rec>(`${base}/mark-skip`, { notes })).data;
+      return (await g8Post<Rec>(`${base}/mark-wrong`, { notes })).data;
+    },
+    {
+      onSuccess: (_r, a) => {
+        setMode(null);
+        setSaved(a.kind === "library" ? "Saved to the answer library." : null);
+        onChanged();
+      },
+    },
+  );
+  const open = (m: Exclude<Mode, null>): void => { setMode(m); setText(m === "edit" ? current : ""); setSaved(null); };
+  const busy = run.loading;
+  const [pending, setPending] = useState<Action["kind"] | null>(null);
+  const go = async (a: Action): Promise<void> => {
+    setPending(a.kind);
+    await run.mutate(a);
+    setPending(null);
+  };
+  const spin = (k: Action["kind"]): boolean => busy && pending === k;
+
+  return (
+    <li className="grid gap-2 rounded-md border p-3" aria-label={q.question_text ?? "Question"}>
+      <div className="flex flex-wrap items-start justify-between gap-2">
+        <div className="min-w-0">
+          <p className="font-medium">{q.question_text || "Untitled question"}</p>
+          <p className="text-muted-foreground text-xs">{[q.question_topic, q.sheet_name, q.cell_reference].filter(Boolean).join(" · ") || "-"}</p>
+        </div>
+        <div className="flex shrink-0 gap-1">
+          <StatusPill tone={state.tone}>{state.label}</StatusPill>
+          {q.confidence && q.confidence !== "confirmed" && q.confidence !== "pending" ? <StatusPill tone="neutral" quiet>{q.confidence} confidence</StatusPill> : null}
+        </div>
+      </div>
+      {mode === "edit" ? (
+        <div className="grid gap-2">
+          <Textarea aria-label="Your answer" rows={5} value={text} onChange={(e) => setText(e.target.value)} />
+          <div className="flex gap-2">
+            <Button size="sm" loading={spin("edit")} disabled={busy || text.trim() === "" || text === current} onClick={() => void go({ kind: "edit", text })}>Save answer</Button>
+            <Button size="sm" variant="outline" disabled={busy} onClick={() => setMode(null)}>Cancel</Button>
+          </div>
+        </div>
+      ) : (
+        <p className="whitespace-pre-wrap text-sm">{current || <span className="text-muted-foreground">No answer yet.</span>}</p>
+      )}
+      {q.final_answer && q.answer_text ? <details className="text-xs"><summary className="text-muted-foreground cursor-pointer">AI answer before your edit</summary><p className="mt-1 whitespace-pre-wrap">{q.answer_text}</p></details> : null}
+      {(q.guardrail_warnings ?? []).length > 0 ? <ul className="text-warning-foreground list-disc pl-5 text-xs">{(q.guardrail_warnings ?? []).map((w) => <li key={w}>{w}</li>)}</ul> : null}
+      {q.escalation_notes ? <p className="text-muted-foreground text-xs">Note: {q.escalation_notes}</p> : null}
+      {mode === "escalate" || mode === "skip" || mode === "wrong" ? (
+        <div className="grid gap-2">
+          <Textarea aria-label={NOTE_COPY[mode].label} rows={3} value={text} placeholder={NOTE_COPY[mode].hint} onChange={(e) => setText(e.target.value)} />
+          <p className="text-muted-foreground text-xs">{NOTE_COPY[mode].label}</p>
+          <div className="flex gap-2">
+            <Button size="sm" loading={spin(mode)} disabled={busy} onClick={() => void go({ kind: mode, notes: text })}>{NOTE_COPY[mode].confirm}</Button>
+            <Button size="sm" variant="outline" disabled={busy} onClick={() => setMode(null)}>Cancel</Button>
+          </div>
+        </div>
+      ) : null}
+      {mode === null ? (
+        <div className="flex flex-wrap gap-1">
+          <Button size="sm" variant="ghost" disabled={busy} onClick={() => open("edit")}><Pencil className="size-4" />Edit answer</Button>
+          <Button size="sm" variant="ghost" loading={spin("approve")} disabled={busy || state.label === "Approved" || !current} onClick={() => void go({ kind: "approve" })}><Check className="size-4" />Approve</Button>
+          <Button size="sm" variant="ghost" disabled={busy} onClick={() => open("escalate")}><UserRound className="size-4" />Escalate</Button>
+          <Button size="sm" variant="ghost" disabled={busy} onClick={() => open("skip")}><MinusCircle className="size-4" />Not applicable</Button>
+          <Button size="sm" variant="ghost" disabled={busy || !q.answer_text} onClick={() => open("wrong")}><Flag className="size-4" />Wrong answer</Button>
+          <Button size="sm" variant="ghost" loading={spin("library")} disabled={busy || !current} onClick={() => void go({ kind: "library" })}><BookmarkPlus className="size-4" />Save to answer library</Button>
+        </div>
+      ) : null}
+      {saved ? <p role="status" className="text-xs">{saved}</p> : null}
+      {run.error ? <ApiError error={run.error} title="Could not update this question" compact /> : null}
+    </li>
+  );
+}

package/blocks/documents/components/questionnaire-detail.tsx

@@ -0,0 +1,197 @@
+"use client";
+
+/**
+ * QuestionnaireDetail: one security questionnaire, the review loop on its questions, and its file actions.
+ *
+ * SDK operations, in order:
+ *   1. getSecurityQuestionnaire (GET .../security-questionnaires/{questionnaire_id})         read         the questionnaire with EVERY question and its answer
+ *   2. getSecurityQuestionnaireStatus (GET .../{questionnaire_id}/status)                     read         the cheap progress read, polled while it is still being answered
+ *   3. QuestionRow (update, approve, escalate, skip, flag, save to library)                   write        the review actions, one per button
+ *   4. downloadSecurityQuestionnaire (GET .../{questionnaire_id}/download)                    read         the FILLED workbook (XLSX bytes, not the JSON envelope); the API refuses it until the questionnaire is completed or needs review
+ *   5. updateSecurityQuestionnaire (PATCH .../{questionnaire_id})                             write        rename only; never touches an answer
+ *   6. deleteSecurityQuestionnaire (DELETE .../{questionnaire_id})                            DESTRUCTIVE  removes it AND every question; behind ConfirmSpendDialog
+ * Uploading a questionnaire (the billable step) lives in QuestionnairesPanel.
+ */
+
+import { useState } from "react";
+import { Download, Pencil, Trash2 } from "lucide-react";
+import { Button, Input, Label, Skeleton } from "@graph8/sdk/ui";
+import { useBrand } from "@/g8/hooks/use-brand";
+import { ApiError } from "@/g8/components/api-error";
+import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
+import { EmptyState } from "@/g8/components/empty-state";
+import { DetailPanel } from "@/g8/components/screen/detail-panel";
+import { FormSheet } from "@/g8/components/screen/form-sheet";
+import { KeyValueList } from "@/g8/components/screen/key-value-list";
+import { StatusPill } from "@/g8/components/screen/status-pill";
+import { g8Delete, g8Get, g8Patch } from "@/g8/lib/g8-client";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { useJobPoll } from "@/g8/hooks/use-job-poll";
+import { plural } from "@/g8/lib/plural";
+import { downloadFile } from "../lib/download";
+import { canDownload, isWorking, percentOf, reviewState, statusInfo, when } from "../lib/documents-types";
+import type { Question, Questionnaire, QuestionnaireProgress, Rec } from "../lib/documents-types";
+import { QuestionRow } from "./question-row";
+
+export interface QuestionnaireDetailProps {
+  accountId: number;
+  questionnaire: Questionnaire;
+  /** The list should be read again (a rename, a delete, a status change). */
+  onChanged: () => void;
+  onClose: () => void;
+  onDeleted?: (q: Questionnaire) => void;
+  onExpand?: () => void;
+  onCollapse?: () => void;
+}
+
+const PAGE = 25;
+const FILTERS = [
+  { id: "all", label: "All" },
+  { id: "attention", label: "Needs attention" },
+  { id: "approved", label: "Approved" },
+  { id: "skipped", label: "Not applicable" },
+] as const;
+
+const nameOf = (q: Questionnaire): string => q.display_name || q.original_file_name || "Untitled questionnaire";
+
+export function QuestionnaireDetail({ accountId, questionnaire, onChanged, onClose, onDeleted, onExpand, onCollapse }: QuestionnaireDetailProps) {
+  const brand = useBrand();
+  const [filter, setFilter] = useState<(typeof FILTERS)[number]["id"]>("all");
+  const [shown, setShown] = useState(PAGE);
+  const [renaming, setRenaming] = useState(false);
+  const [name, setName] = useState("");
+  const [deleting, setDeleting] = useState(false);
+  const [downloadError, setDownloadError] = useState<unknown>(undefined);
+  const [downloading, setDownloading] = useState(false);
+  const base = `/accounts/${encodeURIComponent(String(accountId))}/security-questionnaires/${encodeURIComponent(questionnaire.id)}`;
+
+  const full = useG8Query((signal) => g8Get<Questionnaire>(base, {}, { signal }).then((r) => r.data), [base], { key: ["documents", "questionnaire", accountId, questionnaire.id], placeholderData: questionnaire });
+  const q = full.data && full.data.id === questionnaire.id ? full.data : questionnaire;
+  const loaded = !full.isPlaceholderData && full.data?.id === questionnaire.id;
+  const poll = useJobPoll<QuestionnaireProgress>((signal) => g8Get<QuestionnaireProgress>(`${base}/status`, {}, { signal }).then((r) => r.data), {
+    enabled: isWorking(q.status),
+    intervalMs: 4000,
+    isTerminal: (s) => !isWorking(s.status),
+    onDone: () => { void full.refetch(); onChanged(); },
+  });
+  const live = poll.status ?? q;
+  const info = statusInfo(live.status ?? q.status);
+  const total = live.total_questions ?? q.total_questions ?? null;
+  const answered = live.answered_questions ?? q.answered_questions ?? null;
+  const pct = percentOf(answered, total);
+
+  const rename = useG8Mutation((next: string) => g8Patch<Rec>(base, { display_name: next.trim() || null }), {
+    onSuccess: () => { setRenaming(false); void full.refetch(); onChanged(); },
+  });
+  const remove = useG8Mutation(() => g8Delete(base), { onSuccess: () => { setDeleting(false); onChanged(); onDeleted?.(questionnaire); } });
+
+  const save = async (): Promise<void> => {
+    setDownloading(true);
+    setDownloadError(undefined);
+    try {
+      await downloadFile(`${base}/download`, `${(q.original_file_name || nameOf(q)).replace(/\.[a-z0-9]+$/i, "")}_filled.xlsx`);
+    } catch (err) {
+      setDownloadError(err);
+    } finally {
+      setDownloading(false);
+    }
+  };
+
+  const all = q.questions ?? [];
+  const keep = (x: Question): boolean => {
+    const s = reviewState(x).label;
+    if (filter === "approved") return s === "Approved";
+    if (filter === "skipped") return s === "Not applicable";
+    if (filter === "attention") return s !== "Approved" && s !== "Not applicable";
+    return true;
+  };
+  const visible = all.filter(keep);
+
+  const review = full.error && !loaded ? <ApiError error={full.error} title="Could not load this questionnaire" onRetry={() => void full.refetch()} /> : !loaded ? (
+    <Skeleton className="h-40 w-full" aria-label="Loading questions" />
+  ) : (
+    <div className="grid gap-3">
+      <div role="group" aria-label="Show questions" className="flex flex-wrap gap-1">
+        {FILTERS.map((f) => <Button key={f.id} size="sm" variant={filter === f.id ? "default" : "outline"} aria-pressed={filter === f.id} onClick={() => { setFilter(f.id); setShown(PAGE); }}>{f.label}</Button>)}
+      </div>
+      {all.length === 0 ? (
+        <EmptyState compact title={isWorking(live.status ?? q.status) ? "Questions are still being read" : "No questions"} description={q.status === "failed" ? "No questions could be read from this file." : `Questions appear here as ${brand.name} reads the file.`} />
+      ) : visible.length === 0 ? (
+        <EmptyState compact title="No questions here" description="Try another view." />
+      ) : (
+        <>
+          <p role="status" className="text-muted-foreground text-xs">{visible.length === all.length ? plural(all.length, "question") : `${visible.length} of ${plural(all.length, "question")}`}</p>
+          <ul className="grid gap-2" aria-label="Questions">
+            {visible.slice(0, shown).map((x) => <QuestionRow key={x.id} accountId={accountId} questionnaireId={questionnaire.id} question={x} onChanged={() => { void full.refetch(); onChanged(); }} />)}
+          </ul>
+          {visible.length > shown ? <Button variant="outline" onClick={() => setShown((n) => n + PAGE)}>Show {Math.min(PAGE, visible.length - shown)} more</Button> : null}
+        </>
+      )}
+    </div>
+  );
+
+  return (
+    <>
+      <DetailPanel
+        title={nameOf(q)}
+        subtitle={q.original_file_name && q.original_file_name !== nameOf(q) ? q.original_file_name : undefined}
+        badges={<StatusPill tone={info.tone}>{info.label}</StatusPill>}
+        actions={(
+          <>
+            <Button size="sm" variant="outline" disabled={!loaded} onClick={() => { setName(q.display_name ?? ""); setRenaming(true); }}><Pencil className="size-4" />Rename</Button>
+            <Button size="sm" variant="outline" loading={downloading} disabled={!canDownload(q.status)} title={canDownload(q.status) ? undefined : "The filled workbook is available once the questionnaire is completed or needs review."} onClick={() => void save()}><Download className="size-4" />Download filled workbook</Button>
+            <Button size="sm" variant="outline" onClick={() => setDeleting(true)}><Trash2 className="size-4" />Delete</Button>
+          </>
+        )}
+        onClose={onClose}
+        onExpand={onExpand}
+        onCollapse={onCollapse}
+        summary={(
+          <div className="grid gap-2 px-4 pt-3">
+            <p className="text-sm" role="status">{total != null ? `${answered ?? "-"} of ${plural(total, "question")} answered${pct != null ? ` (${pct}%)` : ""}.` : "Reading the file."}{live.escalated_questions ? ` ${live.escalated_questions} escalated.` : ""}</p>
+            {pct != null ? <div role="progressbar" aria-valuenow={pct} aria-valuemin={0} aria-valuemax={100} aria-label="Answered" className="bg-muted h-1.5 overflow-hidden rounded-full"><div className="bg-foreground h-full" style={{ width: `${pct}%` }} /></div> : null}
+            {q.status === "failed" && (live.error_message || q.error_message) ? <p role="alert" className="text-error text-sm">{live.error_message || q.error_message}</p> : null}
+            {poll.error ? <ApiError error={poll.error} title="Could not check progress" compact onRetry={poll.start} /> : null}
+            {downloadError ? <ApiError error={downloadError} title="Could not download the workbook" compact /> : null}
+          </div>
+        )}
+        tabs={[
+          { id: "review", label: "Review", content: review, count: loaded ? all.length : undefined },
+          { id: "details", label: "Details", content: (
+            <KeyValueList columns={2} items={[
+              { label: "Name", value: q.display_name },
+              { label: "File", value: q.original_file_name },
+              { label: "File type", value: q.original_file_type ? q.original_file_type.toUpperCase() : "" },
+              { label: "Status", value: info.label },
+              { label: "Questions", value: total != null ? String(total) : "" },
+              { label: "Answered", value: answered != null ? String(answered) : "" },
+              { label: "Escalated", value: q.escalated_questions != null ? String(q.escalated_questions) : "" },
+              { label: "Uploaded", value: when(q.created_at) },
+              { label: "Completed", value: when(q.completed_at) },
+              { label: "Questionnaire id", value: q.id, mono: true },
+            ]} />
+          ) },
+        ]}
+      />
+      <FormSheet open={renaming} onOpenChange={setRenaming} title="Rename questionnaire" description="The name is only a label. No answer changes.">
+        <form className="grid gap-3" onSubmit={(e) => { e.preventDefault(); void rename.mutate(name); }}>
+          <div><Label htmlFor="g8-qd-name" className="mb-1">Name</Label><Input id="g8-qd-name" value={name} onChange={(e) => setName(e.target.value)} placeholder={q.original_file_name ?? "Questionnaire"} /><p className="text-muted-foreground mt-1 text-xs">Left blank, the file name is shown.</p></div>
+          {rename.error ? <ApiError error={rename.error} title="Could not rename the questionnaire" /> : null}
+          <div className="flex gap-2"><Button type="submit" loading={rename.loading} disabled={name.trim() === (q.display_name ?? "")}>Save name</Button><Button type="button" variant="outline" onClick={() => setRenaming(false)}>Cancel</Button></div>
+        </form>
+      </FormSheet>
+      <ConfirmSpendDialog
+        open={deleting}
+        tier="destructive"
+        title={`Delete ${nameOf(q)}?`}
+        affected={1}
+        description={<><p>The questionnaire and {total != null ? plural(total, "question") : "every question"} with their answers are removed. This cannot be undone. Answers you saved to the answer library stay there.</p>{remove.error ? <ApiError error={remove.error} title="Could not delete the questionnaire" /> : null}</>}
+        confirmLabel="Delete"
+        confirming={remove.loading}
+        onCancel={() => setDeleting(false)}
+        onConfirm={() => void remove.mutate(undefined)}
+      />
+    </>
+  );
+}

package/blocks/documents/components/questionnaires-panel.tsx

@@ -0,0 +1,173 @@
+"use client";
+
+/**
+ * QuestionnairesPanel: an account's security questionnaires as a finished page: the list, upload a new one, and the
+ * selected questionnaire's review (QuestionnaireDetail).
+ *
+ * SDK operations, in order:
+ *   1. listSecurityQuestionnaires (GET /accounts/{account_id}/security-questionnaires)  read     the account's questionnaires, newest first, paged 50 at a time with Load more
+ *   2. uploadSecurityQuestionnaire (POST /accounts/{account_id}/security-questionnaires) BILLABLE  uploads an XLSX or PDF and starts answering it in the background; behind ConfirmSpendDialog
+ * Everything on one questionnaire (read, progress, review actions, workbook download, rename, delete) is QuestionnaireDetail.
+ * Answering uses credits, but the API publishes no price for it, so the confirmation names the file and says so instead of
+ * showing a made-up estimate. Pass `accountId` (a company id); without one the panel asks for an account.
+ * URL: `?qid=` the open questionnaire, `&view=full` as a page.
+ */
+
+import { useState } from "react";
+import type { ReactNode } from "react";
+import { FileSpreadsheet, Upload } from "lucide-react";
+import { Button, Label, Skeleton } from "@graph8/sdk/ui";
+import { useBrand } from "@/g8/hooks/use-brand";
+import { ApiError } from "@/g8/components/api-error";
+import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
+import { EmptyState } from "@/g8/components/empty-state";
+import { FormSheet } from "@/g8/components/screen/form-sheet";
+import { SplitView } from "@/g8/components/screen/split-view";
+import { StatStrip } from "@/g8/components/screen/stat-strip";
+import { StatusPill } from "@/g8/components/screen/status-pill";
+import { Toolbar } from "@/g8/components/screen/toolbar";
+import { LoadMore } from "@/g8/components/paging-notices";
+import { useLoadMoreList } from "@/g8/hooks/use-load-more-list";
+import { useUrlState } from "@/g8/hooks/use-url-state";
+import { byOffset } from "@/g8/lib/paging";
+import { g8Get, g8Post } from "@/g8/lib/g8-client";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { plural } from "@/g8/lib/plural";
+import { DEFAULT_MAX_BYTES, QUESTIONNAIRE_EXTENSIONS, QUESTIONNAIRE_STATUS, checkFiles, fileLimit, fmtSize, rowsOf, statusInfo, totalOf, when } from "../lib/documents-types";
+import type { Questionnaire, Rec } from "../lib/documents-types";
+import { QuestionnaireDetail } from "./questionnaire-detail";
+
+export interface QuestionnairesPanelProps {
+  /** The account (company id) whose questionnaires to show. */
+  accountId: number | null;
+  renderRowActions?: (q: Questionnaire) => ReactNode;
+  toolbarActions?: ReactNode;
+  /** Largest upload in bytes. Default 5 MiB, the /api/g8 proxy's body limit. */
+  maxBytes?: number;
+}
+
+const PAGE = 50;
+const SELECT = "border-input bg-background h-9 rounded-md border px-2 text-sm";
+const nameOf = (q: Questionnaire): string => q.display_name || q.original_file_name || "Untitled questionnaire";
+
+export function QuestionnairesPanel({ accountId, renderRowActions, toolbarActions, maxBytes = DEFAULT_MAX_BYTES }: QuestionnairesPanelProps) {
+  const brand = useBrand();
+  const [qid, setQid] = useUrlState("qid", "");
+  const [view, setView] = useUrlState("view", "");
+  const [search, setSearch] = useState("");
+  const [status, setStatus] = useState("");
+  const [uploading, setUploading] = useState(false);
+  const [file, setFile] = useState<File | null>(null);
+  const [problems, setProblems] = useState<string[]>([]);
+  const [confirming, setConfirming] = useState(false);
+
+  const list = useLoadMoreList<Questionnaire>(
+    byOffset(PAGE, async (offset, signal) => {
+      if (accountId == null) return { rows: [], hasNext: false };
+      const env = await g8Get<Rec>(`/accounts/${encodeURIComponent(String(accountId))}/security-questionnaires`, { status: status || undefined, limit: PAGE, offset }, { signal });
+      const rows = rowsOf<Questionnaire>(env.data);
+      const total = totalOf(env.data);
+      return { rows, hasNext: total != null ? offset + rows.length < total : rows.length >= PAGE };
+    }),
+    [accountId, status],
+  );
+
+  const send = useG8Mutation(
+    async (f: File): Promise<Questionnaire> => {
+      const form = new FormData();
+      form.append("file", f);
+      return (await g8Post<Questionnaire>(`/accounts/${encodeURIComponent(String(accountId))}/security-questionnaires`, form)).data;
+    },
+    {
+      onSuccess: (created) => { setConfirming(false); setUploading(false); setFile(null); void list.refetch(); setQid(created.id); },
+      invalidates: [["documents", "questionnaire"]],
+    },
+  );
+
+  const rows = list.data ?? [];
+  const q = search.trim().toLowerCase();
+  const shown = rows.filter((r) => !q || `${nameOf(r)} ${r.original_file_name ?? ""}`.toLowerCase().includes(q));
+  const selected = rows.find((r) => r.id === qid) ?? null;
+  const closeDetail = (): void => { setQid(null); setView(null); };
+  const count = (s: string): string => (list.data ? `${rows.filter((r) => r.status === s).length.toLocaleString()}${list.hasMore ? "+" : ""}` : "...");
+
+  if (accountId == null) {
+    return <EmptyState icon={<FileSpreadsheet className="size-8" />} title="Choose an account" description="Pick a company above to see the security questionnaires it sent you, or to upload a new one." />;
+  }
+
+  const body = list.error ? <ApiError error={list.error} title="Could not load questionnaires" onRetry={() => void list.refetch()} /> : list.loading && !list.data ? (
+    <div aria-busy="true" className="grid gap-2"><Skeleton className="h-16 w-full" /><Skeleton className="h-16 w-full" /></div>
+  ) : shown.length === 0 ? (
+    <EmptyState icon={<FileSpreadsheet className="size-8" />} title={rows.length === 0 && !status ? "No questionnaires yet" : "No questionnaires match"} description={rows.length === 0 && !status ? `Upload the spreadsheet or PDF a buyer sent. ${brand.name} answers it from your answer library and policy documents, and you review the answers here.` : "Try another search or status."} action={rows.length === 0 && !status ? <Button onClick={() => setUploading(true)}>Upload a questionnaire</Button> : undefined} />
+  ) : (
+    <>
+      <ul className="grid gap-2">
+        {shown.map((r) => {
+          const info = statusInfo(r.status);
+          return (
+            <li key={r.id} className={`flex flex-wrap items-center justify-between gap-2 rounded-md border p-3 ${r.id === qid ? "bg-muted" : ""}`}>
+              <button type="button" className="min-w-0 flex-1 text-left" onClick={() => setQid(r.id)}>
+                <span className="block truncate font-medium">{nameOf(r)}</span>
+                <span className="text-muted-foreground block truncate text-xs">{r.total_questions != null ? `${r.answered_questions ?? "-"} of ${plural(r.total_questions, "question")} answered` : "Questions not counted yet"} · {when(r.created_at) || "-"}</span>
+              </button>
+              <StatusPill tone={info.tone}>{info.label}</StatusPill>
+              {renderRowActions?.(r)}
+            </li>
+          );
+        })}
+      </ul>
+      <LoadMore shown={rows.length} noun="questionnaires" hasMore={list.hasMore} loading={list.loadingMore} onLoadMore={list.loadMore} />
+    </>
+  );
+
+  const chosen = file ? checkFiles([file], QUESTIONNAIRE_EXTENSIONS, fileLimit(maxBytes)) : null;
+  return (
+    <div className="grid gap-4">
+      <StatStrip items={[
+        { label: "Questionnaires", value: list.data ? `${rows.length.toLocaleString()}${list.hasMore ? "+" : ""}` : "..." },
+        { label: "Needs review", value: count("needs_review"), tone: "warning" },
+        { label: "Answering", value: count("processing") },
+        { label: "Completed", value: count("completed"), tone: "positive" },
+      ]} />
+      <SplitView
+        list={(
+          <div className="grid gap-3">
+            <Toolbar
+              search={{ value: search, onChange: setSearch, placeholder: "Search questionnaires" }}
+              filters={<select aria-label="Filter by status" className={SELECT} value={status} onChange={(e) => { setStatus(e.target.value); closeDetail(); }}><option value="">All statuses</option>{Object.entries(QUESTIONNAIRE_STATUS).map(([v, s]) => <option key={v} value={v}>{s.label}</option>)}</select>}
+              actions={<>{toolbarActions}<Button size="sm" onClick={() => setUploading(true)}><Upload className="size-4" />Upload questionnaire</Button></>}
+            />
+            {body}
+          </div>
+        )}
+        detail={selected ? <QuestionnaireDetail key={selected.id} accountId={accountId} questionnaire={selected} onChanged={() => void list.refetch()} onClose={closeDetail} onDeleted={closeDetail} onExpand={() => setView("full")} onCollapse={view === "full" ? () => setView(null) : undefined} /> : null}
+        detailOpen={Boolean(selected)}
+        onCloseDetail={closeDetail}
+        expanded={view === "full"}
+        onExpandedChange={(e) => setView(e ? "full" : null)}
+        detailWidth="xl"
+      />
+      <FormSheet open={uploading} onOpenChange={(o) => { setUploading(o); if (!o) { setFile(null); setProblems([]); } }} title="Upload a questionnaire" description={`${brand.name} reads the questions and answers each one in the background. Nothing is sent to the buyer.`}>
+        <form className="grid gap-3" onSubmit={(e) => { e.preventDefault(); if (chosen && chosen.ok.length === 1) setConfirming(true); }}>
+          <div>
+            <Label htmlFor="g8-qp-file" className="mb-1">Questionnaire file</Label>
+            <input id="g8-qp-file" type="file" accept={QUESTIONNAIRE_EXTENSIONS.map((x) => `.${x}`).join(",")} className="border-input bg-background w-full rounded-md border p-2 text-sm" onChange={(e) => { const f = e.target.files?.[0] ?? null; setFile(f); setProblems(f ? checkFiles([f], QUESTIONNAIRE_EXTENSIONS, fileLimit(maxBytes)).problems : []); }} />
+            <p className="text-muted-foreground mt-1 text-xs">{QUESTIONNAIRE_EXTENSIONS.join(" or ")}, up to {fmtSize(fileLimit(maxBytes))}. A spreadsheet keeps its layout; a PDF is answered into a new spreadsheet.</p>
+          </div>
+          {problems.length > 0 ? <ul role="alert" className="text-error list-disc pl-5 text-xs">{problems.map((p) => <li key={p}>{p}</li>)}</ul> : null}
+          <div className="flex gap-2"><Button type="submit" disabled={!chosen || chosen.ok.length !== 1}>Upload and answer</Button><Button type="button" variant="outline" onClick={() => setUploading(false)}>Cancel</Button></div>
+        </form>
+      </FormSheet>
+      <ConfirmSpendDialog
+        open={confirming && file !== null}
+        tier="billable"
+        title={`Upload and answer ${file?.name ?? "this file"}?`}
+        description={<><p>{brand.name} reads every question in the file and writes an answer to each from your answer library and policy documents. Answering uses credits. The API does not publish a price for it, so no estimate is shown here.</p>{send.error ? <ApiError error={send.error} title="Could not upload the questionnaire" /> : null}</>}
+        confirmLabel="Upload and answer"
+        confirming={send.loading}
+        onCancel={() => setConfirming(false)}
+        onConfirm={() => { if (file) void send.mutate(file); }}
+      />
+    </div>
+  );
+}

package/blocks/documents/components/record-documents-tab.tsx

@@ -0,0 +1,109 @@
+"use client";
+
+/**
+ * RecordDocumentsTab: the paperwork behind one account, on a company, contact or deal page. Use it as an `extraDetailTabs`
+ * entry of CompaniesScreen / ContactsScreen / DealsScreen:
+ *   { id: "documents", label: "Documents", render: (c) => <RecordDocumentsTab companyId={c.id} documentsPath="/documents" /> }
+ *   { id: "documents", label: "Documents", render: (c) => <RecordDocumentsTab contactId={c.id} /> }          (a contact: their company's paperwork, messages with them first)
+ *   { id: "documents", label: "Documents", render: (d) => <RecordDocumentsTab contactId={d.primary_contact?.id} scope="account" /> }  (a deal: the primary contact finds the company; all its messages show)
+ *
+ * SDK operations, in order:
+ *   1. getContact (GET /contacts/{contact_id})                                          read  only when only a contactId is given: finds the contact's company
+ *   2. listAccountCorrespondence (GET /accounts/{account_id}/correspondence)            read  the latest messages (with that person only when a contactId is given)
+ *   3. listSecurityQuestionnaires (GET /accounts/{account_id}/security-questionnaires)  read  the latest questionnaires for the account
+ * Both lists are the newest five; "Open in documents" goes to the full screen with the account chosen. Read only: recording,
+ * uploading and reviewing happen in DocumentsScreen. A contact with no company has no account to read, and the tab says so.
+ */
+
+import { Mail } from "lucide-react";
+import { Skeleton } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { EmptyState } from "@/g8/components/empty-state";
+import { SectionCard } from "@/g8/components/screen/section-card";
+import { StatusPill } from "@/g8/components/screen/status-pill";
+import { g8Get } from "@/g8/lib/g8-client";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { plural } from "@/g8/lib/plural";
+import { CORRESPONDENCE_CHANNELS, rowsOf, statusInfo, totalOf, when } from "../lib/documents-types";
+import type { Correspondence, Questionnaire, Rec } from "../lib/documents-types";
+
+export interface RecordDocumentsTabProps {
+  /** The company (account) id. */
+  companyId?: number | null;
+  /** A contact: narrows the messages to this person and, without a companyId, finds the company. */
+  contactId?: number | null;
+  /** "person" (default with a contactId) shows only the messages with that contact; "account" shows the whole account's, using the contact only to find the company (a deal page). */
+  scope?: "person" | "account";
+  /** Path of your documents screen for the links. Default "/documents". */
+  documentsPath?: string;
+  /** Route to the documents screen yourself (for example with the router) instead of a plain link. */
+  onOpenDocuments?: (href: string) => void;
+}
+
+const LIMIT = 5;
+
+export function RecordDocumentsTab({ companyId, contactId, scope = "person", documentsPath = "/documents", onOpenDocuments }: RecordDocumentsTabProps) {
+  const personal = contactId != null && scope !== "account";
+  const needContact = companyId == null && contactId != null;
+  const contact = useG8Query((signal) => g8Get<{ company_id?: number | null }>(`/contacts/${contactId}`, {}, { signal }).then((r) => r.data), [contactId], { enabled: needContact, key: ["documents", "contact-company", contactId ?? ""] });
+  const account = companyId ?? contact.data?.company_id ?? null;
+  const base = `/accounts/${account}`;
+  const mail = useG8Query(
+    (signal) => g8Get<Rec>(`${base}/correspondence`, { stakeholder_id: personal ? String(contactId) : undefined, limit: LIMIT }, { signal }).then((r) => ({ rows: rowsOf<Correspondence>(r.data), total: totalOf(r.data) })),
+    [account, personal ? contactId : null],
+    { enabled: account != null, key: ["documents", "correspondence", "tab", account ?? "", personal ? contactId ?? "" : ""] },
+  );
+  const forms = useG8Query(
+    (signal) => g8Get<Rec>(`${base}/security-questionnaires`, { limit: LIMIT }, { signal }).then((r) => ({ rows: rowsOf<Questionnaire>(r.data), total: totalOf(r.data) })),
+    [account],
+    { enabled: account != null, key: ["documents", "questionnaire", "tab", account ?? ""] },
+  );
+
+  if (companyId == null && contactId == null) return <EmptyState compact icon={<Mail className="size-8" />} title="No account to show" description="Documents are kept per company. Add a contact or a company to this record to see them." />;
+  if (needContact && contact.error) return <ApiError error={contact.error} title="Could not find this person's company" onRetry={() => void contact.refetch()} />;
+  if (needContact && contact.loading && !contact.data) return <Skeleton className="h-24 w-full" aria-label="Loading documents" />;
+  if (account == null) return <EmptyState compact icon={<Mail className="size-8" />} title="No company on this contact" description="Messages and questionnaires are kept per company, so there is nothing to show until this person has one." />;
+
+  const href = (tab: string): string => `${documentsPath}?tab=${tab}&account=${account}`;
+  const link = (tab: string, text: string) => (
+    <a href={href(tab)} className="text-sm underline" onClick={(e) => { if (!onOpenDocuments || e.defaultPrevented || e.button !== 0 || e.metaKey || e.ctrlKey || e.shiftKey || e.altKey) return; e.preventDefault(); onOpenDocuments(href(tab)); }}>{text}</a>
+  );
+
+  return (
+    <div className="grid gap-4">
+      <SectionCard title={personal ? "Messages with this person" : "Correspondence"} actions={link("correspondence", "Open in documents")}>
+        {mail.error ? <ApiError error={mail.error} title="Could not load messages" compact onRetry={() => void mail.refetch()} /> : !mail.data ? <Skeleton className="h-16 w-full" aria-label="Loading messages" /> : mail.data.rows.length === 0 ? (
+          <EmptyState compact title="No messages recorded" description="Emails, LinkedIn messages and call notes recorded for this account show up here." />
+        ) : (
+          <ul className="divide-y rounded-md border" aria-label="Messages">
+            {mail.data.rows.map((m) => (
+              <li key={m.id} className="flex items-center justify-between gap-3 p-3 text-sm">
+                <span className="min-w-0"><span className="block truncate font-medium">{m.subject || (m.content ? m.content.slice(0, 80) : "No subject")}</span><span className="text-muted-foreground block text-xs">{CORRESPONDENCE_CHANNELS.find((c) => c.value === m.channel)?.label ?? m.channel ?? "-"} · {when(m.correspondence_date) || "-"}</span></span>
+                {m.direction ? <StatusPill tone={m.direction === "inbound" ? "info" : "neutral"}>{m.direction === "inbound" ? "Inbound" : "Outbound"}</StatusPill> : null}
+              </li>
+            ))}
+          </ul>
+        )}
+        {mail.data && mail.data.total != null && mail.data.total > mail.data.rows.length ? <p className="text-muted-foreground mt-2 text-xs">Showing the newest {mail.data.rows.length} of {plural(mail.data.total, "message")}.</p> : null}
+      </SectionCard>
+      <SectionCard title="Security questionnaires" description="Kept for the company, not the person." actions={link("questionnaires", "Open in documents")}>
+        {forms.error ? <ApiError error={forms.error} title="Could not load questionnaires" compact onRetry={() => void forms.refetch()} /> : !forms.data ? <Skeleton className="h-16 w-full" aria-label="Loading questionnaires" /> : forms.data.rows.length === 0 ? (
+          <EmptyState compact title="No questionnaires" description="Questionnaires uploaded for this account show up here." />
+        ) : (
+          <ul className="divide-y rounded-md border" aria-label="Questionnaires">
+            {forms.data.rows.map((f) => {
+              const info = statusInfo(f.status);
+              return (
+                <li key={f.id} className="flex items-center justify-between gap-3 p-3 text-sm">
+                  <span className="min-w-0"><span className="block truncate font-medium">{f.display_name || f.original_file_name || "Untitled questionnaire"}</span><span className="text-muted-foreground block text-xs">{f.total_questions != null ? `${f.answered_questions ?? "-"} of ${plural(f.total_questions, "question")} answered` : "-"}</span></span>
+                  <StatusPill tone={info.tone}>{info.label}</StatusPill>
+                </li>
+              );
+            })}
+          </ul>
+        )}
+        {forms.data && forms.data.total != null && forms.data.total > forms.data.rows.length ? <p className="text-muted-foreground mt-2 text-xs">Showing the newest {forms.data.rows.length} of {plural(forms.data.total, "questionnaire")}.</p> : null}
+      </SectionCard>
+    </div>
+  );
+}