@graph8/sdk 0.362.0 → 0.373.0

package/blocks/company-intelligence/components/source-view.tsx

@@ -0,0 +1,274 @@
+"use client";
+
+/**
+ * SourceView: shows what one intelligence source collected, in a form a person can read. No SDK operations: pass it the
+ * `data` of a source (`GET /intelligence/data/{data_type}` or one entry of `GET /intelligence/all/{website}`).
+ *
+ * The payloads are open-shaped, so every field is read defensively: a missing value shows a dash (never 0 and never a
+ * guess), web content is drawn as text (never HTML), and links are drawn only for http(s) URLs. A source with a shape
+ * this component does not know falls back to a readable tree of its values.
+ *
+ * Known shapes (from the writers in the app): company_enrichment (flat profile), competitor_discovery ({ competitors }),
+ * brand_news ({ articles }), product_inventory ({ products, services, capabilities }), company_keywords / organic_keywords /
+ * paid_keywords ({ keywords }), audience_questions ({ questions }), search_trends ({ trends }), top_content ({ pages }),
+ * website_scrape ({ pages }), visual_assets ({ logo_url, branding }), brand_sentiment (aggregates).
+ */
+import { useState } from "react";
+import { ExternalLink } from "lucide-react";
+import { Button } from "@graph8/sdk/ui";
+import { KeyValueList, EmptyValue } from "@/g8/components/screen/key-value-list";
+import { StatusPill } from "@/g8/components/screen/status-pill";
+import { SectionCard } from "@/g8/components/screen/section-card";
+import { plural } from "@/g8/lib/plural";
+import { asArray, humanize, isRec, num, safeHttpUrl, text, whenDate } from "../lib/intelligence-types";
+import type { Rec } from "../lib/intelligence-types";
+
+const SHOW = 12;
+const HEX = /^#(?:[0-9a-f]{3}|[0-9a-f]{6})$/i;
+
+function Link({ url, children }: { url: unknown; children?: React.ReactNode }) {
+  const href = safeHttpUrl(url);
+  if (!href) return <>{children ?? text(url) ?? <EmptyValue />}</>;
+  return (
+    <a href={href} target="_blank" rel="noopener noreferrer" className="inline-flex items-center gap-1 underline underline-offset-2">
+      {children ?? href.replace(/^https?:\/\/(www\.)?/, "")}
+      <ExternalLink className="size-3" aria-hidden />
+    </a>
+  );
+}
+
+/** A list that shows its first rows and says how many more there are, with a button to see them. */
+function More<T>({ items, noun, render }: { items: T[]; noun: string; render: (item: T, index: number) => React.ReactNode }) {
+  const [all, setAll] = useState(false);
+  const shown = all ? items : items.slice(0, SHOW);
+  return (
+    <div className="space-y-2">
+      <ul className="divide-y divide-border">{shown.map((item, i) => <li key={i} className="py-2 text-sm">{render(item, i)}</li>)}</ul>
+      {items.length > SHOW ? (
+        <div className="flex items-center justify-between text-xs text-muted-foreground">
+          <span role="status">Showing {shown.length.toLocaleString()} of {plural(items.length, noun)}</span>
+          <Button type="button" variant="outline" size="sm" onClick={() => setAll((v) => !v)}>{all ? "Show fewer" : "Show all"}</Button>
+        </div>
+      ) : null}
+    </div>
+  );
+}
+
+const PROFILE_FIELDS: Array<[string, string]> = [
+  ["company_name", "Company name"], ["industry", "Industry"], ["employee_count", "Employees"], ["revenue", "Revenue"],
+  ["founded_year", "Founded"], ["funding", "Funding"], ["address", "Headquarters"], ["phone", "Phone"], ["primary_email", "Email"],
+];
+const PROFILE_LINKS: Array<[string, string]> = [
+  ["linkedin", "LinkedIn"], ["twitter", "X / Twitter"], ["facebook", "Facebook"], ["instagram", "Instagram"], ["youtube", "YouTube"], ["github", "GitHub"],
+];
+
+export function CompanyProfileFields({ data }: { data: Rec }) {
+  const description = text(data.description);
+  return (
+    <div className="space-y-3">
+      {description ? <p className="text-sm leading-6">{description}</p> : null}
+      <KeyValueList columns={2} items={[
+        ...PROFILE_FIELDS.map(([k, label]) => ({ label, value: text(data[k]) ?? <EmptyValue /> })),
+        ...PROFILE_LINKS.filter(([k]) => text(data[k])).map(([k, label]) => ({ label, value: <Link url={data[k]} /> })),
+      ]} />
+    </div>
+  );
+}
+
+function Competitors({ data }: { data: Rec }) {
+  const rows = asArray(data.competitors).filter(isRec);
+  const summary = text(data.market_summary);
+  return (
+    <div className="space-y-3">
+      {summary ? <p className="text-sm text-muted-foreground">{summary}</p> : null}
+      {rows.length === 0 ? <p className="text-sm text-muted-foreground">No competitors in this source.</p> : (
+        <More items={rows} noun="competitor" render={(c) => (
+          <div className="space-y-1">
+            <div className="flex flex-wrap items-center gap-2">
+              <span className="font-medium">{text(c.name) ?? text(c.domain) ?? "Unnamed"}</span>
+              {text(c.domain) ? <span className="text-xs text-muted-foreground">{text(c.domain)}</span> : null}
+              {text(c.competitive_type) ? <StatusPill tone="info">{humanize(text(c.competitive_type) as string)}</StatusPill> : null}
+              {text(c.similarity) ? <StatusPill tone="neutral">{`${humanize(text(c.similarity) as string)} similarity`}</StatusPill> : null}
+              {text(c.confidence) ? <StatusPill tone="neutral" quiet>{`${humanize(text(c.confidence) as string)} confidence`}</StatusPill> : null}
+            </div>
+            {text(c.description) ? <p className="text-muted-foreground">{text(c.description)}</p> : null}
+            {text(c.reasoning) ? <p className="text-xs text-muted-foreground">{text(c.reasoning)}</p> : null}
+          </div>
+        )} />
+      )}
+    </div>
+  );
+}
+
+const sentimentTone = (s: number | null): "positive" | "negative" | "neutral" => (s == null ? "neutral" : s > 0.2 ? "positive" : s < -0.2 ? "negative" : "neutral");
+
+function News({ data }: { data: Rec }) {
+  const rows = asArray(data.articles).filter(isRec);
+  if (rows.length === 0) return <p className="text-sm text-muted-foreground">No articles in this source.</p>;
+  return (
+    <More items={rows} noun="article" render={(a) => {
+      const source = isRec(a.source) ? text(a.source.name) : text(a.source);
+      const sentiment = num(a.sentiment);
+      return (
+        <div className="space-y-0.5">
+          <div className="font-medium"><Link url={a.url}>{text(a.title) ?? "Untitled article"}</Link></div>
+          <div className="flex flex-wrap items-center gap-2 text-xs text-muted-foreground">
+            {source ? <span>{source}</span> : null}
+            {whenDate(a.published_at) ? <span>{whenDate(a.published_at)}</span> : null}
+            {sentiment != null ? <StatusPill tone={sentimentTone(sentiment)} quiet>{`Sentiment ${sentiment.toFixed(2)}`}</StatusPill> : null}
+          </div>
+          {text(a.description) ? <p className="text-muted-foreground">{text(a.description)}</p> : null}
+        </div>
+      );
+    }} />
+  );
+}
+
+function Products({ data }: { data: Rec }) {
+  const lists: Array<[string, unknown[]]> = [["Products", asArray(data.products)], ["Services", asArray(data.services)], ["Capabilities", asArray(data.capabilities)]];
+  const description = text(data.company_description);
+  return (
+    <div className="space-y-3">
+      {description ? <p className="text-sm leading-6">{description}</p> : null}
+      {lists.filter(([, rows]) => rows.length).map(([label, rows]) => (
+        <SectionCard key={label} title={label} description={plural(rows.length, label.toLowerCase().replace(/s$/, ""))}>
+          <More items={rows} noun={label.toLowerCase().replace(/s$/, "")} render={(r) => isRec(r)
+            ? <div><span className="font-medium">{text(r.name) ?? "Unnamed"}</span>{text(r.description) ? <p className="text-muted-foreground">{text(r.description)}</p> : null}</div>
+            : <span>{text(r) ?? <EmptyValue />}</span>} />
+        </SectionCard>
+      ))}
+    </div>
+  );
+}
+
+/** Keyword rows use legacy SEMrush codes: Ph = phrase, Nq = monthly searches, Cp = cost per click, Po = position, Ur = url. */
+const KEYWORD_COLUMNS: Array<[string, string]> = [["Nq", "Searches"], ["Po", "Position"], ["Cp", "CPC"], ["Ur", "URL"]];
+
+function Keywords({ data }: { data: Rec }) {
+  const rows = asArray(data.keywords);
+  if (rows.length === 0) return <p className="text-sm text-muted-foreground">No keywords in this source.</p>;
+  return (
+    <More items={rows} noun="keyword" render={(k) => {
+      if (!isRec(k)) return <span>{text(k) ?? <EmptyValue />}</span>;
+      const extras = KEYWORD_COLUMNS.filter(([key]) => k[key] != null && k[key] !== "");
+      return (
+        <div className="flex flex-wrap items-baseline gap-x-3">
+          <span className="font-medium">{text(k.Ph) ?? text(k.keyword) ?? text(k.name) ?? "Keyword"}</span>
+          {extras.map(([key, label]) => <span key={key} className="text-xs text-muted-foreground">{label} {key === "Ur" ? <Link url={k[key]} /> : text(k[key])}</span>)}
+        </div>
+      );
+    }} />
+  );
+}
+
+function Questions({ data }: { data: Rec }) {
+  const rows = asArray(data.questions);
+  if (rows.length === 0) return <p className="text-sm text-muted-foreground">No questions in this source.</p>;
+  return <More items={rows} noun="question" render={(q) => <span>{isRec(q) ? text(q.question) ?? text(q.text) ?? <EmptyValue /> : text(q) ?? <EmptyValue />}</span>} />;
+}
+
+function Trends({ data }: { data: Rec }) {
+  const rows = asArray(data.trends);
+  if (rows.length === 0) return <p className="text-sm text-muted-foreground">No trends in this source.</p>;
+  return <More items={rows} noun="trend" render={(t) => (isRec(t) ? <GenericRow row={t} lead="keyword" /> : <span>{text(t) ?? <EmptyValue />}</span>)} />;
+}
+
+function Pages({ data, withText }: { data: Rec; withText?: boolean }) {
+  const rows = asArray(data.pages).filter(isRec);
+  const [open, setOpen] = useState<number | null>(null);
+  if (rows.length === 0) return <p className="text-sm text-muted-foreground">No pages in this source.</p>;
+  return (
+    <More items={rows} noun="page" render={(p, i) => {
+      const body = text(p.markdown) ?? text(p.content);
+      return (
+        <div className="space-y-1">
+          <div className="flex items-center justify-between gap-2">
+            <Link url={p.url ?? p.Ur}>{text(p.title) ?? undefined}</Link>
+            {withText && body ? <Button type="button" variant="ghost" size="sm" onClick={() => setOpen(open === i ? null : i)}>{open === i ? "Hide text" : `Read text (${plural(body.length, "character")})`}</Button> : null}
+          </div>
+          {withText && open === i && body ? <pre className="max-h-64 overflow-auto whitespace-pre-wrap rounded-md bg-muted p-2 text-xs">{body.slice(0, 20_000)}</pre> : null}
+        </div>
+      );
+    }} />
+  );
+}
+
+function Visual({ data }: { data: Rec }) {
+  const logo = safeHttpUrl(data.logo_url);
+  const branding = isRec(data.branding) ? data.branding : {};
+  const colors = isRec(branding.colors) ? Object.entries(branding.colors).filter(([, v]) => typeof v === "string" && HEX.test(v)) : [];
+  const fonts = asArray(branding.fonts).map((f) => (isRec(f) ? text(f.family) ?? text(f.name) : text(f))).filter(Boolean) as string[];
+  return (
+    <div className="space-y-3">
+      {logo ? <img src={logo} alt="Company logo" className="h-12 max-w-48 object-contain" /> : null}
+      {colors.length ? (
+        <ul className="flex flex-wrap gap-3">
+          {colors.map(([name, value]) => (
+            <li key={name} className="flex items-center gap-2 text-xs">
+              <span aria-hidden className="size-6 rounded border border-border" style={{ backgroundColor: value as string }} />
+              <span>{humanize(name)} <span className="text-muted-foreground">{value as string}</span></span>
+            </li>
+          ))}
+        </ul>
+      ) : null}
+      {fonts.length ? <p className="text-sm">Fonts: {fonts.join(", ")}</p> : null}
+      {!logo && !colors.length && !fonts.length ? <p className="text-sm text-muted-foreground">No brand assets in this source.</p> : null}
+    </div>
+  );
+}
+
+function GenericRow({ row, lead }: { row: Rec; lead?: string }) {
+  const entries = Object.entries(row).filter(([, v]) => typeof v === "string" || typeof v === "number" || typeof v === "boolean");
+  const first = lead ? entries.find(([k]) => k === lead) : undefined;
+  return (
+    <div className="flex flex-wrap items-baseline gap-x-3">
+      {first ? <span className="font-medium">{String(first[1])}</span> : null}
+      {entries.filter(([k]) => k !== lead).slice(0, 8).map(([k, v]) => <span key={k} className="text-xs text-muted-foreground">{humanize(k)} {String(v)}</span>)}
+    </div>
+  );
+}
+
+/** Fallback: scalars as key/value pairs, nested objects and lists one level down. Depth-limited so a huge blob stays readable. */
+export function GenericData({ value, depth = 0 }: { value: unknown; depth?: number }) {
+  if (Array.isArray(value)) {
+    if (value.length === 0) return <p className="text-sm text-muted-foreground">Nothing here.</p>;
+    return <More items={value} noun="item" render={(v) => (isRec(v) && depth < 2 ? <GenericRow row={v} /> : <span>{typeof v === "object" ? "" : text(v) ?? ""}</span>)} />;
+  }
+  if (!isRec(value)) return <span className="text-sm">{text(value) ?? <EmptyValue />}</span>;
+  const scalars = Object.entries(value).filter(([, v]) => ["string", "number", "boolean"].includes(typeof v));
+  const nested = Object.entries(value).filter(([, v]) => v != null && typeof v === "object");
+  return (
+    <div className="space-y-3">
+      {scalars.length ? <KeyValueList columns={2} items={scalars.map(([k, v]) => ({ label: humanize(k), value: String(v) }))} /> : null}
+      {depth < 2 ? nested.map(([k, v]) => <SectionCard key={k} title={humanize(k)}><GenericData value={v} depth={depth + 1} /></SectionCard>) : null}
+    </div>
+  );
+}
+
+export interface SourceViewProps {
+  /** The source's type key, for example `company_enrichment`. */
+  dataType: string;
+  /** The `data` blob of the source. */
+  data: unknown;
+}
+
+export function SourceView({ dataType, data }: SourceViewProps) {
+  if (data == null) return <p className="text-sm text-muted-foreground">This source has no data yet.</p>;
+  const rec = isRec(data) ? data : null;
+  if (!rec) return <GenericData value={data} />;
+  switch (dataType) {
+    case "company_enrichment": return <CompanyProfileFields data={rec} />;
+    case "competitor_discovery": return <Competitors data={rec} />;
+    case "brand_news": return <News data={rec} />;
+    case "product_inventory": return <Products data={rec} />;
+    case "company_keywords":
+    case "organic_keywords":
+    case "paid_keywords": return <Keywords data={rec} />;
+    case "audience_questions": return <Questions data={rec} />;
+    case "search_trends": return <Trends data={rec} />;
+    case "top_content": return <Pages data={rec} />;
+    case "website_scrape": return <Pages data={rec} withText />;
+    case "visual_assets": return <Visual data={rec} />;
+    default: return <GenericData value={rec} />;
+  }
+}

package/blocks/company-intelligence/components/wiki-document-detail.tsx

@@ -0,0 +1,116 @@
+"use client";
+
+/**
+ * WikiDocumentDetail: the complete screen for one wiki document. Finds it by id (so `?id=` deep links work), shows its
+ * content as safe formatted text (markdown from the API is never turned into HTML), its state and version, and can write
+ * it again from the collected research.
+ *
+ * SDK operations, in order:
+ *   1. getGlobalContextTreeFlat           GET  /global-context/tree/flat            (read)
+ *   2. getIntelligencePrimaryWebsite      GET  /intelligence/primary-website        (read, through useResearchTarget)
+ *   3. generateGlobalContextDocument      POST /global-context/generate/{doc_type}  (BILLABLE) a model rewrites this ONE document; ConfirmSpendDialog first
+ * After the call is accepted the document is read again until its update time moves. The confirm shows what this document
+ * used the last time it was written (a real number from the document), when the API reports one; there is no advance price.
+ */
+import { useRef, useState, type ReactNode } from "react";
+import { RefreshCw } from "lucide-react";
+import { Button, Skeleton } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
+import { useConfirmAction } from "@/g8/components/confirmed-action";
+import { EmptyState } from "@/g8/components/empty-state";
+import { DetailPanel } from "@/g8/components/screen/detail-panel";
+import { KeyValueList, EmptyValue } from "@/g8/components/screen/key-value-list";
+import { StatusPill, toneForStatus } from "@/g8/components/screen/status-pill";
+import { useJobPoll } from "@/g8/hooks/use-job-poll";
+import { g8Post } from "@/g8/lib/g8-client";
+import { refreshIntelligence, useResearchTarget, useWikiDocuments } from "../hooks/use-intelligence";
+import { docTitle, humanize, num, text, when } from "../lib/intelligence-types";
+import { SafeMarkdown } from "../lib/safe-markdown";
+
+export interface WikiDocumentDetailProps {
+  docId: string;
+  onClose?: () => void;
+  onExpand?: () => void;
+  onCollapse?: () => void;
+  onChanged?: () => void;
+  extraActions?: ReactNode;
+  extraTabs?: { id: string; label: string; content: ReactNode }[];
+}
+
+export function WikiDocumentDetail({ docId, onClose, onExpand, onCollapse, onChanged, extraActions, extraTabs }: WikiDocumentDetailProps) {
+  const { ask, dialog, failure } = useConfirmAction();
+  const target = useResearchTarget();
+  const { docs, error, refetch } = useWikiDocuments();
+  const [waiting, setWaiting] = useState(false);
+  const before = useRef<string | null>(null);
+  const doc = docs?.find((d) => d.id === docId);
+
+  useJobPoll<string | null>(async () => { const rows = await refetch(); return text(rows?.find((d) => d.id === docId)?.updated_at); }, {
+    enabled: waiting, intervalMs: 4000, maxAttempts: 40,
+    isTerminal: (updated) => updated != null && updated !== before.current,
+    onDone: () => { setWaiting(false); void refreshIntelligence(); onChanged?.(); },
+  });
+
+  if (error) return <ApiError error={error} title="Could not load the document" onRetry={() => void refetch()} />;
+  if (!docs) return <Skeleton className="h-40 w-full" />;
+  if (!doc) return <EmptyState title="Document not found" description="It may have been deleted." />;
+
+  const title = docTitle(doc);
+  const lastCredits = num(doc.credits_used);
+  const canRegenerate = Boolean(doc.file_type && target.primary);
+  const askRegenerate = () => ask({
+    tier: "billable",
+    title: `Rewrite ${title}`,
+    confirmLabel: "Rewrite",
+    estimatedCredits: lastCredits != null && lastCredits > 0 ? lastCredits : undefined,
+    description: <p>A model writes this one document again from the collected research and replaces version {doc.version ?? "the current one"}.{lastCredits != null && lastCredits > 0 ? " The credits shown are what it used the last time." : " The API gives no price in advance."}</p>,
+    run: async () => {
+      before.current = text(doc.updated_at);
+      await g8Post(`/global-context/generate/${encodeURIComponent(doc.file_type as string)}`, { doc_type: doc.file_type, website_url: target.primary });
+      setWaiting(true);
+    },
+    onDone: () => { void refreshIntelligence(); },
+  });
+  const actions = (
+    <div className="flex flex-wrap items-center gap-2">
+      <Button type="button" size="sm" variant="outline" disabled={!canRegenerate || waiting} onClick={askRegenerate} title={canRegenerate ? undefined : "Start the website research first"}>
+        <RefreshCw className="size-3.5" aria-hidden />{waiting ? "Writing..." : "Rewrite"}
+      </Button>
+      {extraActions}
+    </div>
+  );
+  const content = text(doc.content);
+  const tabs = [
+    { id: "document", label: "Document", content: content ? <SafeMarkdown markdown={content} /> : <EmptyState title="No content yet" description="This document has not been written." compact /> },
+    {
+      id: "details", label: "Details",
+      content: (
+        <KeyValueList columns={2} items={[
+          { label: "Type", value: text(doc.file_type) ?? <EmptyValue />, mono: true },
+          { label: "Folder", value: text(doc.folder_path) ?? <EmptyValue /> },
+          { label: "Category", value: text(doc.category) ?? <EmptyValue /> },
+          { label: "Version", value: doc.version ?? <EmptyValue /> },
+          { label: "Last updated", value: when(doc.updated_at) ?? <EmptyValue /> },
+          { label: "Credits used last time", value: lastCredits != null && lastCredits > 0 ? lastCredits : <EmptyValue /> },
+        ]} />
+      ),
+    },
+  ];
+  return (
+    <>
+      <DetailPanel
+        title={title}
+        subtitle={text(doc.folder_path) ?? undefined}
+        badges={<StatusPill tone={toneForStatus(doc.status ?? "")}>{doc.status ? humanize(doc.status) : "Unknown"}</StatusPill>}
+        actions={actions}
+        tabs={extraTabs?.length ? [...tabs, ...extraTabs] : tabs}
+        onClose={onClose}
+        onExpand={onExpand}
+        onCollapse={onCollapse}
+      />
+      {failure ? <ApiError error={failure} title="That did not work" /> : null}
+      <ConfirmSpendDialog {...dialog} />
+    </>
+  );
+}

package/blocks/company-intelligence/components/wiki-documents.tsx

@@ -0,0 +1,66 @@
+"use client";
+
+/**
+ * WikiDocuments: the wiki documents graph8 writes from the research (brand, audience, market, messaging ...), listed by
+ * folder with their state, version and last update. Search and a folder filter narrow the list. Click a row to open it.
+ *
+ * SDK operations, in order:
+ *   1. getGlobalContextTreeFlat  GET /global-context/tree/flat  (read)  every wiki document, content included
+ * The API does not page this list (a few dozen documents); the header says how many there are. Folder and search filter on
+ * screen. Opening and regenerating a document is WikiDocumentDetail.
+ */
+import { useMemo, useState } from "react";
+import { FileText } from "lucide-react";
+import { Skeleton } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { EmptyState } from "@/g8/components/empty-state";
+import { RecordLink } from "@/g8/components/screen/record-link";
+import { SelectFilter } from "@/g8/components/screen/filter-controls";
+import { StatusPill, toneForStatus } from "@/g8/components/screen/status-pill";
+import { Toolbar } from "@/g8/components/screen/toolbar";
+import { plural } from "@/g8/lib/plural";
+import { useWikiDocuments } from "../hooks/use-intelligence";
+import { docTitle, humanize, text, whenDate } from "../lib/intelligence-types";
+import type { WikiDoc } from "../lib/intelligence-types";
+
+export interface WikiDocumentsProps {
+  onSelect?: (doc: WikiDoc) => void;
+  selectedId?: string;
+  /** The URL param the owning screen reads for the open document, so Cmd-click opens it in a new tab. */
+  idParam?: string;
+  className?: string;
+}
+
+export function WikiDocuments({ onSelect, selectedId, idParam, className }: WikiDocumentsProps) {
+  const { docs, error, refetch } = useWikiDocuments();
+  const [search, setSearch] = useState("");
+  const [folder, setFolder] = useState("");
+  const folders = useMemo(() => [...new Set((docs ?? []).map((d) => text(d.folder_path)).filter(Boolean) as string[])].sort(), [docs]);
+  if (error) return <ApiError error={error} title="Could not load the documents" onRetry={() => void refetch()} />;
+  if (!docs) return <Skeleton className="h-40 w-full" />;
+  if (docs.length === 0) return <EmptyState title="No documents yet" description="The wiki documents are written from the research. Run the website research first." icon={<FileText />} />;
+  const needle = search.trim().toLowerCase();
+  const rows = docs.filter((d) => (!folder || d.folder_path === folder) && (!needle || docTitle(d).toLowerCase().includes(needle)));
+  return (
+    <div className={className}>
+      <Toolbar
+        search={{ value: search, onChange: setSearch, placeholder: "Search documents", label: "Search documents" }}
+        filters={folders.length > 1 ? <SelectFilter label="folder" value={folder} onChange={setFolder} any="All folders" options={folders} /> : undefined}
+        status={rows.length === docs.length ? `All ${plural(docs.length, "document")}` : `${rows.length.toLocaleString()} of ${plural(docs.length, "document")}`}
+      />
+      {rows.length === 0 ? <EmptyState title="No documents match" description="Try another search or folder." compact /> : (
+        <ul className="mt-2 divide-y divide-border rounded-md border border-border">
+          {rows.map((d) => (
+            <li key={d.id} aria-current={d.id === selectedId ? "true" : undefined} className="flex items-center justify-between gap-3 px-3 py-2 text-sm aria-[current=true]:bg-muted">
+              <div className="min-w-0">
+                <RecordLink id={d.id} param={idParam} onOpen={() => onSelect?.(d)}>{docTitle(d)}</RecordLink>
+                <div className="text-xs text-muted-foreground">{[text(d.folder_path), d.version != null ? `Version ${d.version}` : null, whenDate(d.updated_at) ? `Updated ${whenDate(d.updated_at)}` : null].filter(Boolean).join(", ")}</div>
+              </div>
+              <StatusPill tone={toneForStatus(d.status ?? "")} quiet>{d.status ? humanize(d.status) : "Unknown"}</StatusPill>
+            </li>
+          ))}
+        </ul>
+      )}
+    </div>
+  );
+}

package/blocks/company-intelligence/hooks/use-intelligence.ts

@@ -0,0 +1,173 @@
+"use client";
+
+/**
+ * Shared reads for the company-intelligence components, all cached under the `company-intelligence` key prefix so one
+ * `refreshIntelligence()` after any write refreshes every panel that shows the result.
+ *
+ * SDK operations, in order:
+ *   1. getIntelligencePrimaryWebsite  GET /intelligence/primary-website   (read)  the website the research is locked to
+ *   2. getIntelligenceOrgDomain       GET /intelligence/org-domain        (read)  a suggestion for it, read only while none is set
+ *   3. getLatestIntelligenceTask      GET /intelligence/latest-task       (read)  the most recent research run
+ *   4. getAllIntelligenceData         GET /intelligence/all/{website_url} (read)  every source collected for one website
+ *   5. getIntelligenceStatus          GET /intelligence/status/{task_id}  (read)  the step states of one run
+ *   6. listIntelligenceDocuments      GET /intelligence/documents         (read)  every collected source
+ *   7. getGlobalContextTreeFlat       GET /global-context/tree/flat       (read)  the wiki documents
+ *   8. getGlobalContextTree           GET /global-context/tree            (read)  how many wiki documents exist and are finished
+ *   9. getResearchWorkflowStatus      GET /research-reports/workflow      (read)  the six research reports and how far they are
+ *  10. getIntelligenceData            GET /intelligence/data/{data_type}  (read)  one collected source
+ */
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { invalidate } from "@/g8/lib/g8-cache";
+import { g8Get } from "@/g8/lib/g8-client";
+import { canonicalDomain, intelBody, isRec, num, rowsOf, text } from "../lib/intelligence-types";
+import type { IntelDocument, LatestTask, Rec, RunStatus, WikiDoc, WorkflowStatus } from "../lib/intelligence-types";
+
+export const INTEL_KEY = "company-intelligence";
+
+/** Mark every intelligence read stale after a write, so the panels on screen show the new state. */
+export function refreshIntelligence(): Promise<void> {
+  return invalidate([INTEL_KEY]);
+}
+
+/**
+ * The website intelligence is about. `primary` is the workspace's own website (set by the first research run, then
+ * locked); `suggested` is the company domain in the workspace settings, offered only while no primary website exists.
+ * Neither is ever invented: with both null the person types the website.
+ */
+export function useResearchTarget() {
+  const primary = useG8Query(
+    async (signal) => {
+      const body = intelBody<unknown>(await g8Get("/intelligence/primary-website", undefined, { signal }));
+      return isRec(body) ? text(body.primary_website_url) : null;
+    },
+    [],
+    { key: [INTEL_KEY, "primary-website"] },
+  );
+  const wantSuggestion = primary.data === null;
+  const suggestion = useG8Query(
+    async (signal) => {
+      const body = intelBody<unknown>(await g8Get("/intelligence/org-domain", undefined, { signal }));
+      return isRec(body) ? text(body.company_domain) : null;
+    },
+    [],
+    { key: [INTEL_KEY, "org-domain"], enabled: wantSuggestion },
+  );
+  return {
+    primary: primary.data ?? null,
+    primaryDomain: primary.data ? canonicalDomain(primary.data) : null,
+    suggested: wantSuggestion ? suggestion.data ?? null : null,
+    loading: primary.loading && primary.data === undefined,
+    error: primary.error,
+    refetch: primary.refetch,
+  };
+}
+
+/** The most recent research run of the workspace, or null when none ran yet. */
+export function useLatestRun() {
+  const q = useG8Query(
+    async (signal) => {
+      const body = intelBody<unknown>(await g8Get("/intelligence/latest-task", undefined, { signal }));
+      return isRec(body) && text(body.task_id) ? (body as LatestTask) : null;
+    },
+    [],
+    { key: [INTEL_KEY, "latest-run"] },
+  );
+  return { run: q.data ?? null, loading: q.loading && q.data === undefined, error: q.error, refetch: q.refetch };
+}
+
+/**
+ * Everything collected for one website, keyed by source type (`GET /intelligence/all/{website_url}`, read).
+ * `host` is the website as a host (no scheme); pass null to hold the request.
+ */
+export function useAllIntelligence(host: string | null) {
+  const q = useG8Query(
+    async (signal) => {
+      const body = intelBody<unknown>(await g8Get(`/intelligence/all/${encodeURIComponent(host as string)}`, undefined, { signal }));
+      const out: Record<string, Rec> = {};
+      if (isRec(body)) for (const [type, entry] of Object.entries(body)) if (isRec(entry)) out[type] = entry;
+      return out;
+    },
+    [host],
+    { key: [INTEL_KEY, "all", host ?? "none"], enabled: Boolean(host) },
+  );
+  return { entries: q.data ?? null, loading: q.loading && q.data === undefined, error: q.error, refetch: q.refetch };
+}
+
+/** The `data` blob of one source entry, or null. */
+export function entryData(entry: Rec | undefined | null): Rec | null {
+  return entry && isRec(entry.data) ? entry.data : null;
+}
+
+/** One read of a run's step states (`GET /intelligence/status/{task_id}`, read). For the live view use ResearchRun, which polls. */
+export function useRunStatus(taskId: string | null | undefined) {
+  const q = useG8Query(
+    async (signal) => intelBody<RunStatus>(await g8Get(`/intelligence/status/${encodeURIComponent(taskId as string)}`, undefined, { signal })),
+    [taskId],
+    { key: [INTEL_KEY, "status", taskId ?? "none"], enabled: Boolean(taskId) },
+  );
+  return { status: q.data ?? null, loading: q.loading && q.data === undefined, error: q.error, refetch: q.refetch };
+}
+
+/** Every collected source of the workspace (`GET /intelligence/documents`, read), newest first as the API returns them. */
+export function useSourceDocuments() {
+  const q = useG8Query(
+    async (signal) => rowsOf<IntelDocument>(intelBody(await g8Get("/intelligence/documents", undefined, { signal })), "documents"),
+    [],
+    { key: [INTEL_KEY, "documents"] },
+  );
+  return { docs: q.data ?? null, loading: q.loading && q.data === undefined, error: q.error, refetch: q.refetch };
+}
+
+/**
+ * The wiki documents graph8 writes from the research (brand, audience, market, messaging ...), content included
+ * (`GET /global-context/tree/flat`, read). The API does not page this list and it holds a few dozen documents.
+ */
+export function useWikiDocuments() {
+  const q = useG8Query(
+    async (signal) => rowsOf<WikiDoc>(intelBody(await g8Get("/global-context/tree/flat", undefined, { signal })), "documents"),
+    [],
+    { key: [INTEL_KEY, "wiki", "flat"] },
+  );
+  return { docs: q.data ?? null, loading: q.loading && q.data === undefined, error: q.error, refetch: q.refetch };
+}
+
+/** How many wiki documents exist and how many are finished (`GET /global-context/tree`, read). Null when the API did not say. */
+export function useWikiStats() {
+  const q = useG8Query(
+    async (signal) => {
+      const body = intelBody<unknown>(await g8Get("/global-context/tree", undefined, { signal }));
+      const stats = isRec(body) && isRec(body.stats) ? body.stats : null;
+      const total = num(stats?.total);
+      const completed = num(stats?.completed);
+      return total != null && completed != null ? { total, completed } : null;
+    },
+    [],
+    { key: [INTEL_KEY, "wiki", "tree"] },
+  );
+  return { stats: q.data ?? null, loading: q.loading && q.data === undefined, error: q.error, refetch: q.refetch };
+}
+
+/**
+ * How the six-report research workflow is going for a website (`GET /research-reports/workflow`, read). It always lists
+ * all six slots, including the ones not generated yet. `host` null holds the request.
+ */
+export function useWorkflow(host: string | null) {
+  const q = useG8Query(
+    async (signal) => intelBody<WorkflowStatus>(await g8Get("/research-reports/workflow", { website_url: host }, { signal })),
+    [host],
+    { key: [INTEL_KEY, "workflow", host ?? "none"], enabled: Boolean(host) },
+  );
+  return { workflow: q.data ?? null, loading: q.loading && q.data === undefined, error: q.error, refetch: q.refetch };
+}
+
+/**
+ * One collected source for a website (`GET /intelligence/data/{data_type}`, read): the entry with its `data` blob,
+ * collection time and any edits. A 404 means the source was not collected (the query errors with status 404).
+ */
+export function useSourceEntry(dataType: string, host: string | null, enabled = true) {
+  return useG8Query(
+    async (signal) => intelBody<Rec>(await g8Get(`/intelligence/data/${encodeURIComponent(dataType)}`, host ? { website_url: host } : undefined, { signal })),
+    [dataType, host],
+    { key: [INTEL_KEY, "source", dataType, host ?? "any"], enabled },
+  );
+}