@graph8/sdk 0.370.0 → 0.373.0

package/blocks/company-intelligence/lib/safe-markdown.tsx

@@ -0,0 +1,150 @@
+"use client";
+
+/**
+ * SafeMarkdown: renders the markdown the API returns (research reports, wiki documents) without ever turning it into HTML.
+ * Every piece of text becomes a React text node, so raw HTML, `<script>`, event handlers and `javascript:` links in a
+ * report show up as plain text instead of running. Links are drawn only for http(s) URLs (with `rel="noopener noreferrer"`);
+ * images are not drawn, they stay as their text. No `dangerouslySetInnerHTML` anywhere.
+ *
+ * Supported: headings, paragraphs, bullet and numbered lists, block quotes, fenced code, horizontal rules, pipe tables,
+ * and inline bold, italic, code and links. Anything else is a paragraph of plain text.
+ *
+ * SDK operations: none.
+ */
+import type { ReactNode } from "react";
+import { cn } from "@graph8/sdk/ui";
+import { safeHttpUrl } from "./intelligence-types";
+
+// Underscore emphasis only at word edges, so snake_case_names are left alone.
+const INLINE = /(\*\*([^*]+)\*\*|(?<!\w)__([^_]+)__(?!\w)|`([^`]+)`|\[([^\]]+)\]\(([^)\s]+)\)|\*([^*\s][^*]*)\*|(?<!\w)_([^_\s][^_]*)_(?!\w))/g;
+
+/** Inline markup to React nodes. Unsafe link targets keep their text and lose the link. */
+export function renderInline(source: string, keyPrefix = "i"): ReactNode[] {
+  const out: ReactNode[] = [];
+  let last = 0;
+  let n = 0;
+  for (const m of source.matchAll(INLINE)) {
+    const at = m.index ?? 0;
+    if (at > last) out.push(source.slice(last, at));
+    const key = `${keyPrefix}${n++}`;
+    if (m[2] ?? m[3]) out.push(<strong key={key}>{m[2] ?? m[3]}</strong>);
+    else if (m[4]) out.push(<code key={key} className="rounded bg-muted px-1 py-0.5 text-[0.9em]">{m[4]}</code>);
+    else if (m[5]) {
+      const href = safeHttpUrl(m[6]);
+      out.push(href ? <a key={key} href={href} target="_blank" rel="noopener noreferrer" className="underline underline-offset-2">{m[5]}</a> : <span key={key}>{m[5]}</span>);
+    } else out.push(<em key={key}>{m[7] ?? m[8]}</em>);
+    last = at + m[0].length;
+  }
+  if (last < source.length) out.push(source.slice(last));
+  return out;
+}
+
+const HEADING = /^(#{1,6})\s+(.*)$/;
+const BULLET = /^\s*[-*+]\s+(.*)$/;
+const ORDERED = /^\s*\d+[.)]\s+(.*)$/;
+const RULE = /^\s*([-*_])(\s*\1){2,}\s*$/;
+const TABLE_ROW = /^\s*\|.*\|\s*$/;
+const TABLE_SEP = /^\s*\|?\s*:?-{2,}:?\s*(\|\s*:?-{2,}:?\s*)*\|?\s*$/;
+
+const cells = (line: string): string[] => line.trim().replace(/^\|/, "").replace(/\|$/, "").split("|").map((c) => c.trim());
+
+type Block =
+  | { kind: "heading"; level: number; text: string }
+  | { kind: "para"; text: string }
+  | { kind: "ul" | "ol"; items: string[] }
+  | { kind: "quote"; text: string }
+  | { kind: "code"; text: string }
+  | { kind: "rule" }
+  | { kind: "table"; head: string[]; rows: string[][] };
+
+/** Split markdown into blocks. Pure, so it is tested without rendering. */
+export function parseBlocks(markdown: string): Block[] {
+  const lines = markdown.replace(/\r\n?/g, "\n").split("\n");
+  const blocks: Block[] = [];
+  let i = 0;
+  while (i < lines.length) {
+    const line = lines[i];
+    if (!line.trim()) { i++; continue; }
+    if (/^\s*```/.test(line)) {
+      const body: string[] = [];
+      for (i++; i < lines.length && !/^\s*```/.test(lines[i]); i++) body.push(lines[i]);
+      i++;
+      blocks.push({ kind: "code", text: body.join("\n") });
+      continue;
+    }
+    const h = HEADING.exec(line);
+    if (h) { blocks.push({ kind: "heading", level: h[1].length, text: h[2].trim() }); i++; continue; }
+    if (RULE.test(line)) { blocks.push({ kind: "rule" }); i++; continue; }
+    if (TABLE_ROW.test(line) && i + 1 < lines.length && TABLE_SEP.test(lines[i + 1])) {
+      const rows: string[][] = [];
+      let j = i + 2;
+      for (; j < lines.length && TABLE_ROW.test(lines[j]); j++) rows.push(cells(lines[j]));
+      blocks.push({ kind: "table", head: cells(line), rows });
+      i = j;
+      continue;
+    }
+    if (BULLET.test(line) || ORDERED.test(line)) {
+      const ordered = ORDERED.test(line) && !BULLET.test(line);
+      const items: string[] = [];
+      for (; i < lines.length; i++) {
+        const m = (ordered ? ORDERED : BULLET).exec(lines[i]);
+        if (!m) break;
+        items.push(m[1]);
+      }
+      blocks.push({ kind: ordered ? "ol" : "ul", items });
+      continue;
+    }
+    if (/^\s*>/.test(line)) {
+      const body: string[] = [];
+      for (; i < lines.length && /^\s*>/.test(lines[i]); i++) body.push(lines[i].replace(/^\s*>\s?/, ""));
+      blocks.push({ kind: "quote", text: body.join(" ") });
+      continue;
+    }
+    const para: string[] = [];
+    for (; i < lines.length && lines[i].trim() && !HEADING.test(lines[i]) && !BULLET.test(lines[i]) && !ORDERED.test(lines[i]) && !/^\s*(```|>)/.test(lines[i]); i++) para.push(lines[i].trim());
+    blocks.push({ kind: "para", text: para.join(" ") });
+  }
+  return blocks;
+}
+
+const HEADING_CLASS = ["", "text-lg font-semibold", "text-base font-semibold", "text-sm font-semibold", "text-sm font-medium", "text-sm font-medium", "text-sm font-medium"];
+
+function BlockView({ block, k }: { block: Block; k: number }): ReactNode {
+  switch (block.kind) {
+    case "heading": {
+      const Tag = `h${Math.min(block.level + 1, 6)}` as "h2";
+      return <Tag className={cn("mt-4 text-foreground first:mt-0", HEADING_CLASS[block.level])}>{renderInline(block.text, `h${k}-`)}</Tag>;
+    }
+    case "ul":
+    case "ol": {
+      const Tag = block.kind;
+      return <Tag className={cn("my-2 space-y-1 pl-5", block.kind === "ul" ? "list-disc" : "list-decimal")}>{block.items.map((t, n) => <li key={n}>{renderInline(t, `l${k}-${n}-`)}</li>)}</Tag>;
+    }
+    case "quote": return <blockquote className="my-2 border-l-2 border-border pl-3 text-muted-foreground">{renderInline(block.text, `q${k}-`)}</blockquote>;
+    case "code": return <pre className="my-2 overflow-x-auto rounded-md bg-muted p-3 text-xs"><code>{block.text}</code></pre>;
+    case "rule": return <hr className="my-3 border-border" />;
+    case "table":
+      return (
+        <div className="my-2 overflow-x-auto">
+          <table className="w-full border-collapse text-left text-xs">
+            <thead><tr>{block.head.map((c, n) => <th key={n} className="border-b border-border px-2 py-1 font-medium">{renderInline(c, `th${k}-${n}-`)}</th>)}</tr></thead>
+            <tbody>{block.rows.map((r, ri) => <tr key={ri}>{r.map((c, n) => <td key={n} className="border-b border-border px-2 py-1 align-top">{renderInline(c, `td${k}-${ri}-${n}-`)}</td>)}</tr>)}</tbody>
+          </table>
+        </div>
+      );
+    default: return <p className="my-2 leading-6">{renderInline(block.text, `p${k}-`)}</p>;
+  }
+}
+
+export interface SafeMarkdownProps {
+  markdown: string;
+  className?: string;
+}
+
+export function SafeMarkdown({ markdown, className }: SafeMarkdownProps) {
+  return (
+    <div data-testid="safe-markdown" className={cn("text-sm text-foreground", className)}>
+      {parseBlocks(markdown).map((b, n) => <BlockView key={n} block={b} k={n} />)}
+    </div>
+  );
+}

package/blocks/company-intelligence/recipes/read-competitors-and-news.ts

@@ -0,0 +1,33 @@
+/**
+ * @title Read the competitors and the news the research found
+ * @when Feeding a briefing, a battle-card draft or a Slack digest. Both reads are free. They describe the competitors of YOUR
+ * website (the research is locked to it) and brand news about YOUR company, not about arbitrary companies, and the
+ * API has no lookup for another company's profile, technology or org chart. Article text and URLs come from the web: treat
+ * them as untrusted text and only open http(s) URLs.
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+type Source = { data?: Record<string, unknown> | null; collected_at?: string };
+const entry = (res: unknown): Source => ((res as { data?: Source } | null)?.data ?? (res as Source) ?? {}) as Source;
+
+export interface Competitor { name?: string; domain?: string; description?: string; competitive_type?: string; similarity?: string; confidence?: string; reasoning?: string }
+export interface Article { title?: string; url?: string; description?: string; published_at?: string; sentiment?: number | null; source?: { name?: string } }
+
+export async function competitors(websiteUrl: string): Promise<Competitor[]> {
+  const res = entry(await g8.api.companyIntelligence.getIntelligenceData({ path: { data_type: "competitor_discovery" }, query: { website_url: websiteUrl } }));
+  return (Array.isArray(res.data?.competitors) ? res.data?.competitors : []) as Competitor[];
+}
+
+/** Only http(s) links, newest first. `sentiment` is -1 to 1 or null (unknown, not neutral). */
+export async function recentNews(websiteUrl: string): Promise<Article[]> {
+  const res = entry(await g8.api.companyIntelligence.getIntelligenceData({ path: { data_type: "brand_news" }, query: { website_url: websiteUrl } }));
+  const articles = (Array.isArray(res.data?.articles) ? res.data?.articles : []) as Article[];
+  return articles.filter((a) => /^https?:\/\//i.test(a.url ?? "")).sort((a, b) => String(b.published_at ?? "").localeCompare(String(a.published_at ?? "")));
+}
+
+/** Everything collected, keyed by source type, in one read. */
+export async function everything(websiteUrl: string) {
+  return entry(await g8.api.companyIntelligence.getAllIntelligenceData({ path: { website_url: websiteUrl } })) as Record<string, Source>;
+}

package/blocks/company-intelligence/recipes/research-your-website.ts

@@ -0,0 +1,43 @@
+/**
+ * @title Research your own website and read the company profile
+ * @when Setting up company intelligence for a workspace. The research is locked to ONE website (the workspace's primary
+ * website, set by the first run), so this reads it first and never guesses a domain. Starting a run is BILLABLE and the API
+ * quotes no price (it is metered by usage): tell a human what will be collected and get a yes first. A run finished less than an
+ * hour ago is returned as is (no new work, no charge) unless `force` is true. Order: primary website -> analyze -> poll the
+ * run -> read the company profile.
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+type Body = Record<string, unknown>;
+const body = (res: unknown): Body => ((res as { data?: Body } | null)?.data ?? (res as Body) ?? {}) as Body;
+
+/** The website the research is locked to, or null before the first run. Never invent one. */
+export async function primaryWebsite(): Promise<string | null> {
+  const res = body(await g8.api.companyIntelligence.getIntelligencePrimaryWebsite());
+  return typeof res.primary_website_url === "string" && res.primary_website_url ? res.primary_website_url : null;
+}
+
+/** Billable. Only after a person approved researching `websiteUrl`. With no primary website yet, this one becomes the locked one. */
+export async function startResearch(websiteUrl: string, force = false) {
+  const res = body(await g8.api.companyIntelligence.analyzeWebsite({ body: force ? { website_url: websiteUrl, force: true } : { website_url: websiteUrl } }));
+  return res.task_id as string;
+}
+
+export async function waitForRun(taskId: string) {
+  let delay = 3000;
+  for (let i = 0; i < 100; i++) {
+    const run = body(await g8.api.companyIntelligence.getIntelligenceStatus({ path: { task_id: taskId } }));
+    if (run.status !== "pending" && run.status !== "running") return run;
+    await new Promise((r) => setTimeout(r, delay));
+    delay = Math.min(15000, Math.round(delay * 1.3));
+  }
+  throw new Error("the research did not finish in time; read the status again later");
+}
+
+/** Free. A source that was not collected answers 404: treat that as "not collected", not as an error. */
+export async function companyProfile(websiteUrl: string) {
+  const entry = body(await g8.api.companyIntelligence.getIntelligenceData({ path: { data_type: "company_enrichment" }, query: { website_url: websiteUrl } }));
+  return (entry.data ?? null) as Record<string, unknown> | null;
+}

package/blocks/company-intelligence/recipes/write-the-research-reports.ts

@@ -0,0 +1,54 @@
+/**
+ * @title Write the six research reports, follow them and approve one
+ * @when Building market research from your website. Writing a report is the most expensive single action in Studio and
+ * the API quotes no price: `generateResearchReport` is one long multi-pass run, `generateAllResearchReports` is six,
+ * `resumeResearchWorkflow` writes every report that is not finished. Read the workflow first to count them, tell a human the
+ * number, and get a yes. Approving a report indexes it into the knowledge base that campaigns and the copilot read.
+ * Order: workflow status -> generate (or retry a failed one) -> poll the workflow -> read the report -> approve.
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+type Body = Record<string, unknown>;
+const body = (res: unknown): Body => ((res as { data?: Body } | null)?.data ?? (res as Body) ?? {}) as Body;
+
+export interface Slot { id: string | null; report_number: number; report_type: string; status: string; approved?: boolean }
+
+/** Free. Always six slots (`report_1`..`report_6`), including the ones not written yet. */
+export async function workflow(websiteUrl: string) {
+  const w = body(await g8.api.research.getResearchWorkflowStatus({ query: { website_url: websiteUrl } }));
+  const slots = Object.values((w.reports ?? {}) as Record<string, Slot>);
+  return { status: w.workflow_status as string, slots, missing: slots.filter((s) => s.status !== "completed" && s.status !== "approved" && s.status !== "generating") };
+}
+
+/** Billable. `reportNumber` is 1 to 6. */
+export async function writeReport(websiteUrl: string, reportNumber: number) {
+  return g8.api.research.generateResearchReport({ body: { website_url: websiteUrl, report_number: reportNumber } });
+}
+
+/** Billable. Re-runs ONE failed report; `reportType` is one of the six types in the workflow slots. */
+export async function retryFailed(websiteUrl: string, reportType: "review_sentiment" | "competitive_teardown" | "voice_of_customer" | "gtm_channel" | "analyst_media" | "buyer_psychology") {
+  return g8.api.research.retryResearchReport({ body: { website_url: websiteUrl, report_type: reportType } });
+}
+
+export async function waitForReports(websiteUrl: string) {
+  let delay = 5000;
+  for (let i = 0; i < 200; i++) {
+    const w = await workflow(websiteUrl);
+    if (!w.slots.some((s) => s.status === "generating")) return w;
+    await new Promise((r) => setTimeout(r, delay));
+    delay = Math.min(30000, Math.round(delay * 1.3));
+  }
+  throw new Error("the reports did not finish in time; read the workflow again later");
+}
+
+/** Free. The markdown is model output: render it as text, never as HTML. */
+export async function readReport(reportId: string) {
+  return body(await g8.api.research.getResearchReport({ path: { report_id: reportId } }));
+}
+
+/** Free, but it publishes the report to everything that reads the knowledge base. */
+export async function approve(reportId: string) {
+  return g8.api.research.approveResearchReport({ path: { report_id: reportId } });
+}

package/blocks/copilot/components/copilot-memory.tsx

@@ -16,6 +16,7 @@
 import { useState } from "react";
 import { Button, Input, Skeleton } from "@graph8/sdk/ui";
 import { ApiError } from "@/g8/components/api-error";
+import { FirstNotice } from "@/g8/components/paging-notices";
 import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
 import { EmptyState } from "@/g8/components/empty-state";
 import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
@@ -30,6 +31,8 @@ export interface CopilotMemoryProps {
   className?: string;
 }
 
+/** The memory API has no paging: a full read is announced under the list. */
+const MEMORY_LIMIT = 100;
 const idOf = (m: MemoryRow): string => m.memory_id ?? m.id ?? "";
 
 export function CopilotMemory({ scope = "user", className }: CopilotMemoryProps) {
@@ -37,7 +40,7 @@ export function CopilotMemory({ scope = "user", className }: CopilotMemoryProps)
   const [forgetting, setForgetting] = useState<MemoryRow | null>(null);
   const [showTools, setShowTools] = useState(false);
 
-  const memories = useG8Query((signal) => g8Get("/copilot/memory", { scope, limit: 100 }, { signal }), [scope]);
+  const memories = useG8Query((signal) => g8Get("/copilot/memory", { scope, limit: MEMORY_LIMIT }, { signal }), [scope]);
   const tools = useG8Query((signal) => g8Get("/copilot/tools", undefined, { signal }), [], { enabled: showTools });
   const add = useG8Mutation(() => g8Post("/copilot/memory", { content: note.trim(), scope }), { onSuccess: () => { setNote(""); void memories.refetch(); } });
   const forget = useG8Mutation((id: string) => g8Delete(`/copilot/memory/${id}`), { onSuccess: () => { setForgetting(null); void memories.refetch(); } });
@@ -62,6 +65,7 @@ export function CopilotMemory({ scope = "user", className }: CopilotMemoryProps)
           </li>
         ))}
       </ul>
+      <FirstNotice shown={rows.length} limit={MEMORY_LIMIT} noun="memories" />
       {!memories.loading && !memories.error && rows.length === 0 ? <EmptyState title="Nothing remembered yet" description="Add the rules and facts you want in every answer." /> : null}
       {forget.error ? <ApiError error={forget.error} title="Could not forget it" /> : null}
 
@@ -73,7 +77,7 @@ export function CopilotMemory({ scope = "user", className }: CopilotMemoryProps)
             {toolRows.map((t) => (
               <li key={t.name} className="flex items-start justify-between gap-3 p-2 text-sm">
                 <span><span className="font-medium">{t.name}</span>{t.description ? <span className="block text-xs text-muted-foreground">{t.description}</span> : null}</span>
-                {t.requires_approval || t.needs_approval ? <span className="text-xs text-amber-700">needs approval</span> : null}
+                {t.requires_approval || t.needs_approval ? <span className="text-xs text-warning-foreground">needs approval</span> : null}
               </li>
             ))}
           </ul>

package/blocks/copilot/components/copilot-panel.tsx

@@ -153,7 +153,7 @@ export function CopilotPanel({ context, initialTab = "ask", confirmEveryMessage
               <div key={t.id} data-testid={`turn-${t.role}`} className={`max-w-[85%] rounded-lg px-3 py-2 text-sm ${t.role === "user" ? "self-end bg-primary text-primary-foreground" : t.error ? "self-start border border-destructive" : "self-start bg-muted"}`}>
                 <p className="whitespace-pre-wrap">{t.text}</p>
                 {t.tools?.length ? <p className="mt-1 text-xs opacity-70">Used: {t.tools.join(", ")}</p> : null}
-                {t.needsApproval?.length ? <p className="mt-1 text-xs text-amber-700">Needs your approval in {brand.linkLabel} before it runs: {t.needsApproval.join(", ")}</p> : null}
+                {t.needsApproval?.length ? <p className="mt-1 text-xs text-warning-foreground">Needs your approval in {brand.linkLabel} before it runs: {t.needsApproval.join(", ")}</p> : null}
                 {t.sources ? <p className="mt-1 text-xs opacity-70">{t.sources} sources</p> : null}
               </div>
             ))}

package/blocks/copilot/components/copilot-team-chat.tsx

@@ -19,6 +19,7 @@
 import { useEffect, useRef, useState } from "react";
 import { Button, Input } from "@graph8/sdk/ui";
 import { ApiError } from "@/g8/components/api-error";
+import { FirstNotice } from "@/g8/components/paging-notices";
 import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
 import { EmptyState } from "@/g8/components/empty-state";
 import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
@@ -43,6 +44,9 @@ interface Page { conversation_id?: string; messages?: WorkMessageRow[] }
 
 const newKey = (): string => `team-${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
 
+/** The agents roster read has no paging here: a full read is announced under the composer. */
+const AGENT_LIMIT = 50;
+
 export function CopilotTeamChat({ channelId, pollMs = 4000, hideChannelPicker, className }: CopilotTeamChatProps) {
   const [channel, setChannel] = useState<string | undefined>(channelId);
   const [text, setText] = useState("");
@@ -51,7 +55,7 @@ export function CopilotTeamChat({ channelId, pollMs = 4000, hideChannelPicker, c
   const draftKey = useRef(newKey());
 
   const channels = useG8Query((signal) => g8Get("/work/channels", undefined, { signal }), [], { enabled: !(hideChannelPicker && channelId) });
-  const agents = useG8Query((signal) => g8Get("/work/agents", { limit: 50 }, { signal }), []);
+  const agents = useG8Query((signal) => g8Get("/work/agents", { limit: AGENT_LIMIT }, { signal }), []);
   const rows = listOf<WorkChannel>(channels.data, "channels");
   const roster = listOf<AgentRow>(agents.data, "items");
   const active = channel ?? rows[0]?.id ?? undefined;
@@ -103,6 +107,7 @@ export function CopilotTeamChat({ channelId, pollMs = 4000, hideChannelPicker, c
               onKeyDown={(e) => { if (e.key === "Enter" && text.trim() && !post.loading) submit(); }} />
             <Button loading={post.loading} disabled={!text.trim()} onClick={submit}>Post</Button>
           </div>
+          <FirstNotice shown={roster.length} limit={AGENT_LIMIT} noun="agents" />
         </>
       ) : null}
 

package/blocks/crm/README.md

@@ -148,3 +148,9 @@ Ask the person: who may delete or merge records (decide it in the proxy's `autho
 | mergeContact / mergeCompany | POST /contacts/{id}/merge, /companies/{id}/merge | destructive | DedupeReview |
 | listAllTasks / getTask / createGlobalTask | GET /tasks, GET /tasks/{task_id}, POST /tasks | read / read / write | TasksScreen |
 | assertContact, assertCompany (+ batch) | PUT /contacts/assert, /companies/assert | write | recipes (`g8.contacts.upsert`) |
+
+## Cross-block glue
+
+- `ContactLookupLink` (`components/contact-lookup-link.tsx`): "Open contact" for something that only knows an email (an inbox thread, a meeting attendee). It looks the email up (`GET /contacts?email=`) and shows a button only when a contact has it; `onOpen(contactId)` routes to your contacts screen. `ContactsScreen.onOpenCompany`, `CompaniesScreen.onOpenContact` and `TasksScreen.onOpenRecord` are the other ends of the same links: the stack pages pass them (`router.push("/companies?id=...")`).
+
+- `RecordEngagementTab` (`components/record-engagement-tab.tsx`): engagement counts, last touch (contacts) and pages visited for a contact or company, an `extraDetailTabs` entry: `{ id: "engagement", label: "Engagement", render: (c) => <RecordEngagementTab kind="contacts" id={c.id} /> }`. Reads `getContactEngagementSummary` / `getCompanyEngagementSummary` and `getContactSitesVisited` / `getCompanySitesVisited`. Also: the contact subtitle is `contactSubtitle(contact)` ("VP of Sales at Acme"; the company is never the person's own name, and "at" is left out without a company).

package/blocks/crm/block.json

@@ -37,7 +37,11 @@
     "get_activity_feed_activity_feed_get",
     "get_bulk_merge_status_duplicates_bulk_merge__run_id__get",
     "get_company_companies__company_id__get",
+    "get_company_engagement_summary_companies__company_id__engagement_summary_get",
+    "get_company_sites_visited_companies__company_id__sites_visited_get",
     "get_contact_contacts__contact_id__get",
+    "get_contact_engagement_summary_contacts__contact_id__engagement_summary_get",
+    "get_contact_sites_visited_contacts__contact_id__sites_visited_get",
     "get_task_tasks__task_id__get",
     "import_contacts_imports__import_id__contacts_post",
     "list_all_tasks_tasks_get",
@@ -296,17 +300,53 @@
       "file": "components/tasks-screen.tsx",
       "purpose": "Workspace-wide task queue: Open/Completed/All, search and filters, complete or reopen, create, edit, delete, bulk complete and delete, detail panel.",
       "operations": [
-        "list_all_tasks_tasks_get",
-        "get_task_tasks__task_id__get",
         "create_global_task_tasks_post",
-        "update_task_tasks__task_id__patch",
-        "delete_task_tasks__task_id__delete"
+        "delete_task_tasks__task_id__delete",
+        "get_task_tasks__task_id__get",
+        "list_all_tasks_tasks_get",
+        "update_task_tasks__task_id__patch"
       ],
       "tiers": [
         "read",
         "write",
         "destructive"
       ]
+    },
+    {
+      "name": "ListSelect",
+      "file": "components/list-select.tsx",
+      "purpose": "Audience-list dropdown, searchable and paged (the foundation ListSelect with GET /lists wired in). Replaces a select fed by one capped list read.",
+      "operations": [
+        "list_lists_lists_get"
+      ],
+      "tiers": [
+        "read"
+      ]
+    },
+    {
+      "name": "ContactLookupLink",
+      "file": "components/contact-lookup-link.tsx",
+      "purpose": "\"Open contact\" button for something that only knows an email (inbox thread, meeting attendee, visitor): looks the email up in the CRM and calls onOpen(contactId); renders nothing when nobody has it.",
+      "operations": [
+        "list_contacts_contacts_get"
+      ],
+      "tiers": [
+        "read"
+      ]
+    },
+    {
+      "name": "RecordEngagementTab",
+      "file": "components/record-engagement-tab.tsx",
+      "purpose": "Engagement counts, last touch and pages visited for one contact or company; an extraDetailTabs entry for ContactsScreen and CompaniesScreen.",
+      "operations": [
+        "get_contact_engagement_summary_contacts__contact_id__engagement_summary_get",
+        "get_company_engagement_summary_companies__company_id__engagement_summary_get",
+        "get_contact_sites_visited_contacts__contact_id__sites_visited_get",
+        "get_company_sites_visited_companies__company_id__sites_visited_get"
+      ],
+      "tiers": [
+        "read"
+      ]
     }
   ],
   "hooks": [
@@ -328,6 +368,11 @@
         "list_contact_fields_fields_get",
         "list_company_fields_fields_companies_get"
       ]
+    },
+    {
+      "name": "useAllLists",
+      "file": "hooks/use-all-lists.ts",
+      "purpose": "Every list, page after page, for lookups by id (a list's size or name); ListSelect is the picker."
     }
   ],
   "lib": [
@@ -338,6 +383,10 @@
     {
       "file": "lib/screen-parts.tsx",
       "purpose": "Sorting, row selection, bulk delete and pager shared by ContactsScreen, CompaniesScreen and TasksScreen."
+    },
+    {
+      "file": "lib/read-lists.ts",
+      "purpose": "One page of audience lists (GET /lists), the read behind ListSelect and useAllLists."
     }
   ],
   "recipes": [

package/blocks/crm/components/companies-screen.tsx

@@ -37,8 +37,9 @@ import { RecordLink } from "@/g8/components/screen/record-link";
 import { plural } from "@/g8/lib/plural";
 import { useG8Query } from "@/g8/hooks/use-g8-query";
 import { useUrlState } from "@/g8/hooks/use-url-state";
+import { useUrlFilters } from "@/g8/hooks/use-url-filters";
+import { MoreFilters, RangeFilter, TextFilter } from "@/g8/components/screen/filter-controls";
 import { g8Delete, g8Get } from "@/g8/lib/g8-client";
-import { useDebouncedValue } from "../hooks/use-debounced";
 import { usePageQuery } from "../hooks/use-page-query";
 import { companyName, errorStatus, location } from "../lib/crm-types";
 import type { CompanyRecord, ContactRecord, ScreenActionContext } from "../lib/crm-types";
@@ -67,8 +68,10 @@ export interface CompaniesScreenProps {
   className?: string;
 }
 
-interface Filters { name: string; domain: string; industry: string; country: string }
-const NO_FILTERS: Filters = { name: "", domain: "", industry: "", country: "" };
+/** Every filter the companies API takes: text (name, domain, industry, country, state, city, description) and four from/to ranges. */
+const FILTER_KEYS = ["name", "domain", "industry", "country", "state", "city", "description", "employee_count_min", "employee_count_max", "revenue_min", "revenue_max", "founded_year_min", "founded_year_max", "linkedin_followers_min", "linkedin_followers_max"] as const;
+type FilterKey = (typeof FILTER_KEYS)[number];
+const MORE_KEYS: readonly FilterKey[] = FILTER_KEYS.filter((k) => !["name", "domain", "industry", "country"].includes(k));
 
 function sortValue(row: CompanyRecord, key: string): string | null | undefined {
   if (key === "name") return row.name || row.domain;
@@ -91,8 +94,9 @@ export function CompaniesScreen(props: CompaniesScreenProps) {
   const parsedId = idParam ? Number(idParam) : null;
   /** A malformed deep link (`?id=abc`) opens nothing instead of fetching /companies/NaN. */
   const openId = parsedId != null && Number.isFinite(parsedId) ? parsedId : null;
-  const [draft, setDraft] = useState<Filters>(NO_FILTERS);
-  const filters = useDebouncedValue(draft);
+  // The filters live in the URL (`co_city=...`), so a filtered view survives reload, Back and sharing.
+  const urlFilters = useUrlFilters(FILTER_KEYS, { prefix: "co_" });
+  const { draft, filters } = urlFilters;
   const [sheet, setSheet] = useState<"new" | "dupes" | null>(null);
   const [confirmDelete, setConfirmDelete] = useState(false);
   const [note, setNote] = useState<string | null>(null);
@@ -103,15 +107,16 @@ export function CompaniesScreen(props: CompaniesScreenProps) {
     [filters],
     pageSize,
     ["companies", "list", "screen"],
+    urlFilters.ready,
   );
   const dupes = useG8Query((signal) => g8Get<{ pending?: number; count?: number }>("/duplicates/counts", { entity_type: "company" }, { signal }), [], { key: ["duplicates", "counts", "company"] });
   const selection = useRowSelection<CompanyRecord>(JSON.stringify(filters));
   const rows = useMemo(() => sortRows(list.rows, sort, sortValue), [list.rows, sort]);
-  const hasFilters = Object.values(draft).some(Boolean);
+  const hasFilters = urlFilters.active;
   const pending = dupes.data?.data.pending ?? dupes.data?.data.count;
   const industries = new Set(list.rows.map((r) => r.industry).filter(Boolean)).size;
   const reload = () => { void list.refetch(); void dupes.refetch(); };
-  const set = (key: keyof Filters, v: string) => setDraft((f) => ({ ...f, [key]: v }));
+  const set = (key: FilterKey, v: string) => urlFilters.set(key, v);
   const allOnPage = rows.length > 0 && rows.every((r) => selection.selected.has(r.id));
 
   const bulk = useBulkDelete("/companies", (gone, total) => {
@@ -157,7 +162,16 @@ export function CompaniesScreen(props: CompaniesScreenProps) {
                   <input aria-label="Filter by domain" placeholder="Domain" className="h-9 w-36 rounded-md border bg-background px-3 text-sm" value={draft.domain} onChange={(e) => set("domain", e.target.value)} />
                   <input aria-label="Filter by industry" placeholder="Industry" className="h-9 w-36 rounded-md border bg-background px-3 text-sm" value={draft.industry} onChange={(e) => set("industry", e.target.value)} />
                   <input aria-label="Filter by country" placeholder="Country" className="h-9 w-32 rounded-md border bg-background px-3 text-sm" value={draft.country} onChange={(e) => set("country", e.target.value)} />
-                  {hasFilters ? <Button variant="ghost" size="sm" onClick={() => setDraft(NO_FILTERS)}>Clear filters</Button> : null}
+                  <MoreFilters activeCount={MORE_KEYS.filter((k) => draft[k]).length}>
+                    <TextFilter label="state" value={draft.state} onChange={(v) => set("state", v)} className="w-28" />
+                    <TextFilter label="city" value={draft.city} onChange={(v) => set("city", v)} className="w-32" />
+                    <TextFilter label="description" value={draft.description} onChange={(v) => set("description", v)} className="w-44" />
+                    <RangeFilter label="Employees" min={draft.employee_count_min} max={draft.employee_count_max} onMinChange={(v) => set("employee_count_min", v)} onMaxChange={(v) => set("employee_count_max", v)} />
+                    <RangeFilter label="Revenue" min={draft.revenue_min} max={draft.revenue_max} onMinChange={(v) => set("revenue_min", v)} onMaxChange={(v) => set("revenue_max", v)} />
+                    <RangeFilter label="Founded" min={draft.founded_year_min} max={draft.founded_year_max} onMinChange={(v) => set("founded_year_min", v)} onMaxChange={(v) => set("founded_year_max", v)} />
+                    <RangeFilter label="LinkedIn followers" min={draft.linkedin_followers_min} max={draft.linkedin_followers_max} onMinChange={(v) => set("linkedin_followers_min", v)} onMaxChange={(v) => set("linkedin_followers_max", v)} />
+                  </MoreFilters>
+                  {hasFilters ? <Button variant="ghost" size="sm" onClick={urlFilters.clear}>Clear filters</Button> : null}
                 </>
               }
             />
@@ -210,7 +224,7 @@ export function CompaniesScreen(props: CompaniesScreenProps) {
                 <EmptyState
                   title={hasFilters ? "No companies match these filters" : "No companies yet"}
                   description={hasFilters ? "Try fewer filters." : "Add a company, or import contacts and their companies are created from their domains."}
-                  action={hasFilters ? <Button variant="outline" onClick={() => setDraft(NO_FILTERS)}>Clear filters</Button> : <Button onClick={() => setSheet("new")}>New company</Button>}
+                  action={hasFilters ? <Button variant="outline" onClick={urlFilters.clear}>Clear filters</Button> : <Button onClick={() => setSheet("new")}>New company</Button>}
                 />
               ) : null}
               <Pager page={list.page} pageCount={list.pageCount} total={list.total} noun="companies" hasNext={list.hasNext} loading={list.loading} onPage={list.setPage} />

package/blocks/crm/components/company-detail.tsx

@@ -66,9 +66,9 @@ export function CompanyDetail({ companyId, onDeleted, onOpenContact, renderActio
   return (
     <div className={`flex flex-col gap-4 ${className ?? ""}`}>
       <header className="flex flex-wrap items-center gap-3">
-        <div aria-hidden className="flex size-12 items-center justify-center rounded-md bg-muted text-sm font-semibold">{initials(name)}</div>
+        <div aria-hidden className="flex size-12 items-center justify-center rounded-md bg-muted text-sm font-medium">{initials(name)}</div>
         <div className="min-w-0 flex-1">
-          <h2 className="truncate text-lg font-semibold">{name}</h2>
+          <h2 className="truncate text-lg font-medium">{name}</h2>
           <p className="truncate text-sm text-muted-foreground">{[company.domain, company.industry].filter(Boolean).join(" - ") || "No domain or industry"}</p>
         </div>
         <div className="flex flex-wrap items-center gap-2">

package/blocks/crm/components/contact-detail.tsx

@@ -25,7 +25,7 @@ import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
 import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
 import { useG8Query } from "@/g8/hooks/use-g8-query";
 import { g8Delete, g8Get } from "@/g8/lib/g8-client";
-import { contactName, initials, isMasked, location } from "../lib/crm-types";
+import { contactName, contactSubtitle, initials, isMasked, location } from "../lib/crm-types";
 import type { ContactRecord } from "../lib/crm-types";
 import { ActivityTimeline } from "./activity-timeline";
 import { NotesPanel } from "./notes-panel";
@@ -75,11 +75,11 @@ export function ContactDetail({ contactId, onDeleted, onOpenCompany, renderActio
   return (
     <div className={`flex flex-col gap-4 ${className ?? ""}`}>
       <header className="flex flex-wrap items-center gap-3">
-        <div aria-hidden className="flex size-12 items-center justify-center rounded-full bg-muted text-sm font-semibold">{initials(name)}</div>
+        <div aria-hidden className="flex size-12 items-center justify-center rounded-full bg-muted text-sm font-medium">{initials(name)}</div>
         <div className="min-w-0 flex-1">
-          <h2 className="truncate text-lg font-semibold">{name}</h2>
+          <h2 className="truncate text-lg font-medium">{name}</h2>
           <p className="truncate text-sm text-muted-foreground">
-            {[contact.job_title, contact.company?.name].filter(Boolean).join(" at ") || "No title or company"}
+            {contactSubtitle(contact)}
           </p>
         </div>
         <div className="flex flex-wrap items-center gap-2">