@graph8/sdk 0.362.0 → 0.373.0

package/blocks/coach/components/coach-screen.tsx

@@ -0,0 +1,222 @@
+"use client";
+
+/**
+ * CoachScreen: the finished sales coach page. Tabs: Practice calls (graded calls newest first with a score and the first
+ * tip; open one for the full scorecard, recording and transcript, deep link `?id=`), Leaderboard (reps ranked by score) and
+ * Real calls (the rep's dialer calls, only when a rep email is known). Stats summarise the loaded calls: how many, the
+ * average and best score, and the stage reps miss most.
+ *
+ * Flows: browse and open calls; load a signed recording (CallScorecard); delete a call (destructive, ConfirmSpendDialog;
+ * hide with allowDelete={false}); create a practice call row (write; the live practice conversation itself runs in the
+ * graph8 app, so the form links out); managers type a rep's email to read that rep's calls (needs a manager key, a 403 is shown).
+ *
+ * SDK operations (through the composed parts): GET /sales-coach/calls, GET /sales-coach/leaderboard, POST /sales-coach/calls,
+ * and CallScorecard's getCall, getCallTranscript, getCallAudioUrl and deleteCall; GET /voice/dialer/calls via the dialer block.
+ */
+import { useEffect, useMemo, useRef, useState, type ReactNode } from "react";
+import { GraduationCap } from "lucide-react";
+import { Button, Input, Label, Skeleton, Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { EmptyState } from "@/g8/components/empty-state";
+import { DetailPanel } from "@/g8/components/screen/detail-panel";
+import { EntityAvatar } from "@/g8/components/screen/entity-avatar";
+import { FormSheet } from "@/g8/components/screen/form-sheet";
+import { ScreenLayout } from "@/g8/components/screen/screen-layout";
+import { SplitView } from "@/g8/components/screen/split-view";
+import { StatusPill } from "@/g8/components/screen/status-pill";
+import { Toolbar } from "@/g8/components/screen/toolbar";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { useUrlState } from "@/g8/hooks/use-url-state";
+import { g8Get, g8Post } from "@/g8/lib/g8-client";
+import { CallHistory } from "@/g8/dialer/components/call-log-screen";
+import { avgOf, listOf, scorecardOf } from "../lib/coach-types";
+import type { CoachCall, LeaderboardRow } from "../lib/coach-types";
+import { CallScorecard } from "./call-scorecard";
+import { useBrand } from "@/g8/hooks/use-brand";
+
+export interface CoachScreenProps {
+  /** Whose practice calls. Omit for the key owner's own; managers may type another rep's email. */
+  userEmail?: string;
+  /** Show the "New practice call" button (creates the row only). Default true when no rep email is set. */
+  allowCreate?: boolean;
+  allowDelete?: boolean;
+  toolbarActions?: ReactNode;
+  renderRowActions?: (call: CoachCall) => ReactNode;
+  renderDetailActions?: (call: CoachCall) => ReactNode;
+  extraDetailTabs?: Array<{ id: string; label: string; render: (call: CoachCall) => ReactNode }>;
+  className?: string;
+}
+
+function useDebounced<T>(value: T, ms = 400): T {
+  const [v, setV] = useState(value);
+  useEffect(() => {
+    const t = setTimeout(() => setV(value), ms);
+    return () => clearTimeout(t);
+  }, [value, ms]);
+  return v;
+}
+
+const scoreTone = (pct: number | null | undefined) => (pct == null ? "neutral" : pct >= 75 ? "positive" : pct >= 50 ? "warning" : "negative");
+const EMPTY_FORM = { call_mode: "assisted" as "assisted" | "compete", prospect_name: "", prospect_company: "", persona_type: "" };
+
+function weakestStage(rows: CoachCall[]): string | null {
+  const sums = new Map<string, { total: number; n: number }>();
+  for (const c of rows) for (const s of scorecardOf(c)?.stages ?? []) if (s.pct != null) sums.set(s.label, { total: (sums.get(s.label)?.total ?? 0) + s.pct, n: (sums.get(s.label)?.n ?? 0) + 1 });
+  const ranked = [...sums].map(([k, v]) => [k, v.total / v.n] as const).sort((a, b) => a[1] - b[1]);
+  return ranked[0]?.[0] ?? null;
+}
+
+function NewCallSheet({ open, onOpenChange, onCreated }: { open: boolean; onOpenChange: (o: boolean) => void; onCreated: () => void }) {
+  const brand = useBrand();
+  const [form, setForm] = useState(EMPTY_FORM);
+  const create = useG8Mutation(
+    () => g8Post("/sales-coach/calls", { call_mode: form.call_mode, prospect_name: form.prospect_name.trim() || undefined, prospect_company: form.prospect_company.trim() || undefined, persona_type: form.persona_type.trim() || undefined }),
+    { onSuccess: () => { setForm(EMPTY_FORM); onOpenChange(false); onCreated(); } },
+  );
+  const field = (id: string, text: string, key: "prospect_name" | "prospect_company" | "persona_type") => (
+    <div className="flex flex-col gap-1"><Label htmlFor={id}>{text}</Label><Input id={id} value={form[key]} onChange={(e) => setForm({ ...form, [key]: e.target.value })} /></div>
+  );
+  return (
+    <FormSheet
+      open={open}
+      onOpenChange={onOpenChange}
+      title="New practice call"
+      description={`This adds the call to your list. The live practice conversation runs in ${brand.linkLabel}.`}
+      footer={<><Button variant="ghost" onClick={() => onOpenChange(false)}>Cancel</Button><Button loading={create.loading} onClick={() => void create.mutate(undefined)}>Create call</Button></>}
+    >
+      <div className="grid gap-3">
+        {field("pc-name", "Prospect", "prospect_name")}
+        {field("pc-company", "Company", "prospect_company")}
+        {field("pc-persona", "Persona", "persona_type")}
+        <div className="flex flex-col gap-1"><Label htmlFor="pc-mode">Mode</Label>
+          <select id="pc-mode" className="h-9 rounded-md border border-border bg-background px-2 text-sm" value={form.call_mode} onChange={(e) => setForm({ ...form, call_mode: e.target.value as "assisted" | "compete" })}><option value="assisted">Training</option><option value="compete">Compete</option></select>
+        </div>
+        {create.error ? <ApiError error={create.error} title="Could not create the call" /> : null}
+        <a className="text-sm underline" href={brand.appUrl} target="_blank" rel="noreferrer">Practice in {brand.linkLabel}</a>
+      </div>
+    </FormSheet>
+  );
+}
+
+function Leaderboard({ enabled }: { enabled: boolean }) {
+  const board = useG8Query((signal) => g8Get("/sales-coach/leaderboard", undefined, { signal }), [], { enabled });
+  const ranked = [...listOf<LeaderboardRow>(board.data, "items")].sort((a, b) => b.score - a.score);
+  if (board.error) return <ApiError error={board.error} title="Could not load the leaderboard" onRetry={() => void board.refetch()} />;
+  if (board.loading && ranked.length === 0) return <Skeleton className="h-32 w-full" aria-label="Loading leaderboard" />;
+  if (ranked.length === 0) return <EmptyState title="Nobody on the board yet" description="Completed practice calls rank here." />;
+  return (
+    <Table>
+      <TableHeader><TableRow><TableHead className="w-12">#</TableHead><TableHead>Rep</TableHead><TableHead className="text-right">Calls</TableHead><TableHead className="text-right">Avg</TableHead><TableHead className="text-right">Total</TableHead></TableRow></TableHeader>
+      <TableBody>
+        {ranked.map((r, i) => (
+          <TableRow key={r.email} data-testid={`rank-${r.email}`}>
+            <TableCell>{i + 1}</TableCell>
+            <TableCell><span className="flex items-center gap-2"><EntityAvatar name={r.name || r.email} kind="person" size="sm" />{r.name}<span className="text-xs text-muted-foreground">{r.email}</span></span></TableCell>
+            <TableCell className="text-right">{r.calls}</TableCell><TableCell className="text-right">{avgOf(r)}</TableCell><TableCell className="text-right">{r.score}</TableCell>
+          </TableRow>
+        ))}
+      </TableBody>
+    </Table>
+  );
+}
+
+export function CoachScreen(props: CoachScreenProps) {
+  const brand = useBrand();
+  const { allowDelete, toolbarActions, renderRowActions, renderDetailActions, extraDetailTabs, className } = props;
+  const [tab, setTab] = useUrlState("tab", "calls");
+  const [openId, setOpenId] = useUrlState("id");
+  const [view, setView] = useUrlState("view");
+  const [typed, setTyped] = useState("");
+  const [shown, setShown] = useState(15);
+  const [creating, setCreating] = useState(false);
+  const typedEmail = useDebounced(typed.trim());
+  const email = props.userEmail || typedEmail || undefined;
+  const allowCreate = props.allowCreate ?? !email;
+
+  const calls = useG8Query((signal) => g8Get("/sales-coach/calls", { email }, { signal }), [email]);
+  // Another rep's calls are a different list: forget the selection and paging.
+  const lastEmail = useRef(email);
+  useEffect(() => {
+    if (lastEmail.current === email) return; // keep a deep-linked ?id= on first render
+    lastEmail.current = email;
+    setShown(15);
+    setOpenId(null);
+  }, [email]); // eslint-disable-line react-hooks/exhaustive-deps
+  const rows = listOf<CoachCall>(calls.data, "items");
+  const selected = openId ? rows.find((c) => c.id === openId) : undefined;
+  const cards = useMemo(() => rows.map((c) => scorecardOf(c)?.scorePct).filter((n): n is number => typeof n === "number"), [rows]);
+  const avg = cards.length ? Math.round(cards.reduce((a, b) => a + b, 0) / cards.length) : null;
+  const tabs = [{ id: "calls", label: "Practice calls", count: rows.length || undefined }, { id: "board", label: "Leaderboard" }, ...(email ? [{ id: "real", label: "Real calls" }] : [])];
+  const active = tabs.some((t) => t.id === tab) ? tab : "calls";
+
+  const list = (
+    <div className="space-y-2">
+      {calls.error ? <ApiError error={calls.error} title="Could not load practice calls" onRetry={() => void calls.refetch()} /> : null}
+      {calls.loading && rows.length === 0 ? Array.from({ length: 3 }, (_, i) => <Skeleton key={i} className="h-16 w-full" />) : null}
+      <ul className="flex flex-col gap-2" data-testid="feed">
+        {rows.slice(0, shown).map((c) => {
+          const card = scorecardOf(c);
+          const tip = card?.improvements[0];
+          return (
+            <li key={c.id} className="flex items-start gap-1">
+              <button type="button" data-testid={`call-${c.id}`} onClick={() => setOpenId(c.id)} className={`min-w-0 flex-1 rounded-md border border-border p-3 text-left ${openId === c.id ? "bg-muted" : "hover:bg-muted/50"}`}>
+                <span className="flex items-center justify-between gap-2">
+                  <span className="truncate font-medium">{c.prospect_name || "Practice call"}{c.prospect_company ? ` at ${c.prospect_company}` : ""}</span>
+                  {card?.scorePct != null ? <StatusPill tone={scoreTone(card.scorePct)}>{`${Math.round(card.scorePct)}%`}</StatusPill> : <StatusPill tone="neutral">{c.call_status ?? "not graded"}</StatusPill>}
+                </span>
+                <span className="block text-xs text-muted-foreground">{c.date_of_call ? new Date(c.date_of_call).toLocaleDateString() : ""} {c.call_mode ?? ""}</span>
+                {tip ? <span className="mt-1 block text-sm">Work on: {tip}</span> : null}
+              </button>
+              {renderRowActions ? <div className="shrink-0 p-1">{renderRowActions(c)}</div> : null}
+            </li>
+          );
+        })}
+      </ul>
+      {!calls.loading && !calls.error && rows.length === 0 ? (
+        <EmptyState icon={<GraduationCap className="size-6" />} title="No practice calls yet" description={`Graded practice calls and what to work on next show up here. Practice calls run in ${brand.linkLabel}.`} action={allowCreate ? <Button size="sm" onClick={() => setCreating(true)}>New practice call</Button> : undefined} />
+      ) : null}
+      {rows.length > shown ? <Button variant="outline" size="sm" onClick={() => setShown(shown + 15)}>Show more</Button> : null}
+    </div>
+  );
+  const expanded = view === "full" && Boolean(openId);
+  const detail = openId ? (
+    <DetailPanel
+      title={selected?.prospect_name || "Practice call"}
+      subtitle={selected?.prospect_company ?? undefined}
+      actions={selected ? renderDetailActions?.(selected) : undefined}
+      onClose={() => { setOpenId(null); setView(null); }}
+      onExpand={expanded ? undefined : () => setView("full")}
+      onCollapse={expanded ? () => setView(null) : undefined}
+      tabs={[
+        { id: "scorecard", label: "Scorecard", content: <CallScorecard key={openId} callId={openId} allowDelete={allowDelete} onDeleted={() => { setOpenId(null); setView(null); void calls.refetch(); }} /> },
+        ...(selected ? (extraDetailTabs ?? []).map((t) => ({ id: t.id, label: t.label, content: t.render(selected) })) : []),
+      ]}
+    />
+  ) : null;
+
+  return (
+    <ScreenLayout
+      className={className}
+      title="Sales coach"
+      description="Scored practice calls, what to work on next, and how the team ranks."
+      icon={<GraduationCap className="size-5" />}
+      actions={<>{allowCreate ? <Button size="sm" onClick={() => setCreating(true)}>New practice call</Button> : null}{toolbarActions}</>}
+      tabs={tabs}
+      activeTab={active}
+      onTabChange={(id) => { setTab(id); setOpenId(null); setView(null); }}
+      stats={rows.length > 0 ? [
+        { label: "Calls loaded", value: rows.length },
+        { label: "Average score", value: avg != null ? `${avg}%` : "", tone: scoreTone(avg) },
+        { label: "Best score", value: cards.length ? `${Math.round(Math.max(...cards))}%` : "" },
+        { label: "Weakest stage", value: weakestStage(rows) ?? "", hint: "lowest average" },
+      ] : undefined}
+      toolbar={props.userEmail ? undefined : <Toolbar search={{ value: typed, onChange: setTyped, placeholder: "Rep email (managers)" }} />}
+    >
+      {active === "calls" ? <SplitView list={list} detail={detail} detailOpen={Boolean(openId)} onCloseDetail={() => { setOpenId(null); setView(null); }} expanded={expanded} onExpandedChange={(next) => setView(next ? "full" : null)} /> : null}
+      {active === "board" ? <Leaderboard enabled /> : null}
+      {active === "real" ? <CallHistory userEmail={email} idParam="call" /> : null}
+      <NewCallSheet open={creating} onOpenChange={setCreating} onCreated={() => void calls.refetch()} />
+    </ScreenLayout>
+  );
+}

package/blocks/company-intelligence/README.md

@@ -0,0 +1,132 @@
+# company-intelligence
+
+Research **your own website** and read what it found: the company profile, competitors, brand news, products, keywords,
+audience questions and brand assets; the wiki documents written from that research; and the six market research reports
+(review sentiment, competitive teardown, voice of customer, GTM channels, analyst and media, buyer psychology). Billable steps
+(a research run, a document rewrite, writing a report) are confirmed with the number of things they touch; deleting and
+resetting are confirmed as destructive.
+
+**What this is not.** The company intelligence API researches the workspace's own website and is locked to it. It has **no
+lookup for other companies**, no technographics, no org chart, no firmographics for a prospect and no AI briefing endpoint (see
+"API gaps"). The screens say so instead of inventing data.
+
+## Screens
+
+`CompanyIntelligenceScreen` (`components/company-intelligence-screen.tsx`) is the finished page. Copy it as your route; no props are required.
+
+```tsx
+import { CompanyIntelligenceScreen } from "@/g8/company-intelligence/components/company-intelligence-screen";
+export default function Page() { return <CompanyIntelligenceScreen />; }
+```
+
+Tabs (`?tab=`): **Overview** (start, follow and reset the research; the company profile), **Sources** (everything collected, and the sources that failed; open one with `?id=<type>` to read it and re-collect it), **Documents** (the wiki documents; `?id=` opens one to read or rewrite), **Reports** (the six reports and their workflow; `?id=` opens one). `&view=full` shows a detail as a full page.
+
+Flows: research the website (confirmed; follows progress step by step), research again (`force`), reset the research (confirmed with the real record count), read each source (profile, competitors, news with sentiment, products, keywords, questions, trends, pages, brand assets), re-collect one source (confirmed), search and filter the wiki documents, read one as formatted text, rewrite one (confirmed), write one report or all six (confirmed with the count), retry a failed report, write the missing ones, stop a run, reset the workflow, read a report, edit its text (changed text only), approve it into the knowledge base and remove it again, read the model's recorded reasoning, write a report again, delete it. Optional props: `toolbarActions`, `renderDetailActions(record)`, `extraDetailTabs` (each `{ id, label, render(record) }`), where `record` is `{ kind: "source" | "document" | "report", id }`.
+
+Parts you can mount alone: `ResearchRun`, `CompanyProfileCard`, `IntelligenceSources`, `SourceDetail`, `SourceView`, `WikiDocuments`, `WikiDocumentDetail`, `ResearchReports`, `ReportDetail`, and the CRM tab below.
+
+### On a CRM company page: `CompanyIntelligenceTab`
+
+```tsx
+<CompaniesScreen
+  extraDetailTabs={[{ id: "intelligence", label: "Intelligence", render: (c) => <CompanyIntelligenceTab company={c} /> }]}
+/>
+```
+
+The stacks that include both `crm` and this block (apollo, zoominfo, clay, 6sense) already mount it. It shows the full profile when the company on screen **is** your workspace's website, the competitor entry your research holds when it is one of the competitors the research found, and otherwise says plainly that there is nothing to show. It never invents data for other companies.
+
+## Install
+
+```
+npx @graph8/sdk add company-intelligence
+```
+
+Installs `foundation` first if missing. Everything lands under `g8/company-intelligence/`. Add `intelligence`, `global-context` and `research-reports` to the proxy allowlist (the installer does this from the block's operations).
+
+## Prerequisites (the human must do these)
+
+| Where | What | How to verify |
+|---|---|---|
+| graph8 key | `knowledge:read`, `knowledge:run`, `knowledge:delete` (research, documents) and `campaigns:read`, `campaigns:write`, `campaigns:run`, `campaigns:delete` (research reports). | `g8.api.me.describeCurrentKey()` |
+| Credits | Research runs, document rewrites and report writing spend credits. The API quotes no price and has no balance read. | The owner knows the balance. |
+| The business | Which website is researched. The first run locks the workspace to it. | `GET /api/v1/intelligence/primary-website` shows `has_website: true`. |
+
+## The flow, in order (IDs passed between steps)
+
+1. **Target**: `getIntelligencePrimaryWebsite` -> `primary_website_url` (null before the first run). If null, `getIntelligenceOrgDomain` -> `company_domain` is only a **suggestion**; a person confirms it.
+2. **Research**: `analyzeWebsite({ website_url, force? })` behind `ConfirmSpendDialog` -> **`task_id`**. A run that finished less than an hour ago is returned as is (no new work, no charge) unless `force` is true. If a primary website is set, any other website answers 400.
+3. **Follow**: `getIntelligenceStatus(task_id)` until `status` is not `pending`/`running`; `steps` has one state per source. `getLatestIntelligenceTask` gives the last `task_id`.
+4. **Read**: `listIntelligenceDocuments` (what was collected), `getIntelligenceData(data_type, { website_url })` (one source, 404 = not collected), `getAllIntelligenceData(website_url)` (all of them, keyed by type; `website_url` here is the host without a scheme).
+5. **Fix one source**: `retryIntelligenceSource({ website_url, data_type })` (billable). The last good data stays if it fails.
+6. **Wiki documents**: `getGlobalContextTreeFlat` (each has `id`, `file_type`, `content`, `status`, `version`, `credits_used`), `getGlobalContextTree` (`stats.total`, `stats.completed`), `generateGlobalContextDocument(file_type, { doc_type, website_url })` (billable, rewrites one document).
+7. **Reports**: `getResearchWorkflowStatus({ website_url })` -> six slots `report_1..report_6` with `id`, `report_number`, `report_type`, `status`. Then `generateResearchReport({ website_url, report_number })`, `generateAllResearchReports`, `resumeResearchWorkflow`, `retryResearchReport({ website_url, report_type })` (all billable), `stopAllResearch`, `resetResearchWorkflow` (destructive). `getResearchReport(id)` has the markdown; `updateResearchReport(id, { markdown_content })`, `approveResearchReport(id)`, `unapproveResearchReport(id)`, `deleteResearchReport(id)`, `getResearchReportThinking(id)` (recorded reasoning).
+
+## Default decisions (do not ask the human unless marked)
+
+| Decision | Default | Ask? |
+|---|---|---|
+| Which website is researched | The primary website once set; the workspace settings' company domain only as a suggestion | **yes** |
+| Run again within the hour | No: the API returns the recent run for free | no |
+| Writing reports | Never automatic; a person confirms the number first | no |
+| Approving a report into the knowledge base | Only when asked (campaigns and the copilot read approved reports) | **yes** |
+| Editing a report | Send only the changed text; clearing it sends `""` | no |
+| Missing data | A dash, never 0, never a guess | no |
+
+## Cost, in plain numbers
+
+The API gives **no price in advance** and no balance read, so no screen shows an invented figure. Each confirm states the quantity
+it can compute from the data on screen, and a real "last time" number when the API reports one.
+
+| Action | Tier | Confirm says |
+|---|---|---|
+| Research the website | billable | Collects the sources of the last run (their count when known); or that a run under an hour old would be returned for free; that the first website becomes locked |
+| Re-collect one source | billable | The one source and the website |
+| Rewrite one wiki document | billable | The document and its version; credits it used last time when the API reports them |
+| Write one report | billable | 1 report |
+| Write all reports | billable | The number of reports, and how many finished ones are written again |
+| Write the missing reports | billable | The count and the titles of the unfinished reports |
+| Retry a failed report | billable | 1 report |
+| Save report text | billable tier (re-indexes into knowledge) | That saving re-indexes the text |
+| Reset the research | destructive | The real number of collected sources it deletes |
+| Reset the report workflow | destructive | The number of reports that have content |
+| Delete a report | destructive | 1 report, and what it used last time when known |
+| Reads, approve, unapprove, stop | none / write | (stop is confirmed too: it cancels paid work in flight) |
+
+## Operation coverage
+
+Used (26): `analyzeWebsite`, `getIntelligenceStatus`, `getLatestIntelligenceTask`, `getIntelligencePrimaryWebsite`, `getIntelligenceOrgDomain`, `listIntelligenceDocuments`, `getIntelligenceData`, `getAllIntelligenceData`, `retryIntelligenceSource`, `resetIntelligence`, `getGlobalContextTree`, `getGlobalContextTreeFlat`, `generateGlobalContextDocument`, `getResearchReportThinking` (the 14 `companyIntelligence` operations, all used), plus from the `research` and `gtmContext` namespaces the report operations they need: `getResearchWorkflowStatus`, `getResearchReport`, `generateResearchReport`, `generateAllResearchReports`, `resumeResearchWorkflow`, `retryResearchReport`, `stopAllResearch`, `resetResearchWorkflow`, `approveResearchReport`, `unapproveResearchReport`, `deleteResearchReport`, `updateResearchReport`.
+
+Skipped on purpose:
+
+| Operation | Why |
+|---|---|
+| `scaffoldResearchReports` | Creates six empty placeholder rows. The Reports tab already shows all six slots from the workflow status, and writing a report creates its row. |
+| `getResearchReportByNumber` | The same report `getResearchReport` returns by id; the workflow status gives every id. |
+| `listResearchReports` (gtmContext) | The workflow status lists the same six reports with their ids and approval state, per website. |
+| `listIntelligenceData` (gtmContext) | The same sources as `listIntelligenceDocuments` / `getAllIntelligenceData`. |
+| `getGlobalContextDocument`, `listGlobalContextDocuments`, `updateGlobalContextDocument`, `deleteDocument`, `deleteAllDocuments`, `regenerateGlobalContext`, `generateAllDocuments`, `resumePipeline`, `stopAllGeneration`, `scaffold*`, `reindexAllDocuments`, `resetStuckDocuments`, pipelines, highlights, analytics, feedback, usage tracking, buying-journey (gtmContext) | Wiki editing and the whole-wiki pipeline belong to the campaigns/GTM context surface, not to company intelligence. This block reads and rewrites one document at a time. |
+
+## API gaps (what was asked for and the API does not have)
+
+| Asked for | Reality | What the block does |
+|---|---|---|
+| Company profile / firmographics / technographics of **any** company | The research is of the workspace's own website and is locked to it (`analyze` answers 400 for another website). Only `company_enrichment`, `product_inventory`, `company_keywords` etc. of that one website exist. No technology-stack data at all. | Shows the own-company profile; the CRM tab says plainly that other companies have none. |
+| News and signals for a prospect | `brand_news` is news about the workspace's own brand. Buying signals are the `intent` and `radar` blocks. | News tab content is the brand's own news. |
+| Competitors | `competitor_discovery` lists the competitors of the workspace's website (name, domain, type, similarity, confidence, reasoning). Battle cards and tracking are the `radar` block. | Shown in Sources; the CRM tab matches a company to it by domain. |
+| Org chart | No endpoint. Buying committees are in the `intent` block (ABM rollup). | Not offered. |
+| AI briefings for a company | No briefing endpoint; the research reports are market-level, not per company. | Not offered. |
+| A price before running | None, and no credit balance read. | Confirms state quantities, never a made-up cost. |
+| Live progress stream | The thinking stream is SSE and excluded; only the recorded history is exposed. | Reasoning tab shows the recorded steps; runs are polled. |
+| Editing collected data / Ask AI revisions | The in-app field overrides and revise endpoints are not in the developer API. | Collected data is read-only; edits made in the app are shown and flagged. |
+| Reset everything | `DELETE /intelligence/reset-all` is deliberately not published. | Reset removes intelligence records and runs only. |
+| Report type names | The list filter documents `industry_analyst` but the retry enum is `analyst_media`. | The block uses the retry enum. |
+
+## Things that surprise people
+
+- The first research run **locks** the workspace to that website and also records it as the workspace's company domain. Pick it deliberately.
+- `analyze` is collapsed: within an hour of a finished run it returns that run (`message: "Recent analysis available"`) without new work. Pass `force` to re-run.
+- Every payload is open-shaped. A missing field is unknown, not zero.
+- Web content (article titles, snippets, scraped pages, report markdown) is untrusted. This block draws it as text; links open only when they are http(s).
+- A report's `credits_used` is `0` until it ran; the UI shows a dash, not 0.
+- `getIntelligenceData` answers 404 for a source that was never collected; that is "not collected", not an outage.
+- Reports need the website: `getResearchWorkflowStatus` requires `website_url`.