@graph8/sdk 0.370.0 → 0.374.0

package/blocks/crm/components/verify-email-button.tsx

@@ -0,0 +1,93 @@
+"use client";
+
+/**
+ * VerifyEmailButton: verify the work emails of a selection. Counts what it will charge for, shows that count and cost
+ * in ConfirmSpendDialog, and sends exactly that set.
+ *
+ * SDK operations, behind ConfirmSpendDialog (billable, scope enrichment:run):
+ *   1. verifyContactEmails POST /contacts/verify-email { contact_pks }      about 1 credit per verified email
+ *        Only contacts with a real (not locked, not empty) work email are counted and sent: the "***" placeholder is never
+ *        sent. Already verified emails come back as `already_verified` and inconclusive checks are not stored or
+ *        charged; the result line states what was charged (`charged_credits`) rather than the estimate. At most 1000.
+ *
+ * The confirm is disabled while its request runs, and a failed call keeps the selection so the person can retry.
+ */
+
+import { useState } from "react";
+import { Button } from "@graph8/sdk/ui";
+import { MailCheck } from "lucide-react";
+import { ApiError } from "@/g8/components/api-error";
+import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { g8Post } from "@/g8/lib/g8-client";
+import { plural } from "@/g8/lib/plural";
+import type { ContactRecord } from "../lib/crm-types";
+import { MAX_PAID_BATCH, VERIFY_CREDITS_PER_EMAIL, verifySummary, verifyTargets } from "../lib/record-actions";
+import type { VerifyRow } from "../lib/record-actions";
+
+export interface PaidActionProps {
+  rows: ReadonlyArray<ContactRecord>;
+  onDone?: () => void;
+  variant?: "default" | "outline" | "secondary" | "ghost";
+  size?: "default" | "sm";
+  className?: string;
+  /** Start with the confirm open and render no trigger (the row actions dialog opens it). */
+  defaultOpen?: boolean;
+  onClosed?: () => void;
+}
+
+/** A list answer that is a bare array or an envelope with the list under a common key. */
+function anyRows<T>(data: unknown): T[] {
+  if (Array.isArray(data)) return data as T[];
+  const o = data as Record<string, unknown> | null | undefined;
+  for (const k of ["items", "results", "contacts", "data"]) if (Array.isArray(o?.[k])) return o![k] as T[];
+  return [];
+}
+
+export function VerifyEmailButton({ rows, onDone, variant = "outline", size = "sm", className, defaultOpen = false, onClosed }: PaidActionProps) {
+  const [open, setOpen] = useState(defaultOpen);
+  const [summary, setSummary] = useState<string | null>(null);
+  // One filter, used for the count, the cost and the request body.
+  const targets = verifyTargets(rows);
+  const left = rows.length - targets.length;
+
+  const verify = useG8Mutation(async (ids: number[]) => {
+    const res = await g8Post<unknown>("/contacts/verify-email", { contact_pks: ids });
+    return anyRows<VerifyRow>(res.data);
+  }, {
+    invalidates: [["contacts", "list"], ["contacts", "detail"], ["contacts", "record"]],
+    onSuccess: (out) => { setOpen(false); setSummary(verifySummary(out)); onDone?.(); onClosed?.(); },
+  });
+
+  return (
+    <>
+      {defaultOpen ? null : (
+        <Button className={className} variant={variant} size={size} disabled={targets.length === 0} title={targets.length === 0 ? "None of the selected contacts has an unlocked work email" : undefined} onClick={() => { setSummary(null); verify.reset(); setOpen(true); }}>
+          <MailCheck className="size-4" aria-hidden />Verify email
+        </Button>
+      )}
+      {summary ? <span role="status" className="text-xs text-muted-foreground">{summary}</span> : null}
+      {verify.error && !open ? <ApiError compact error={verify.error} title="Could not verify the emails" /> : null}
+      <ConfirmSpendDialog
+        open={open}
+        tier="billable"
+        title={`Verify ${plural(targets.length, "email")}`}
+        description={
+          <>
+            Checks whether each address can receive mail and stores the answer on the contact. Already verified emails and inconclusive checks are not charged.
+            {left > 0 ? ` ${plural(left, "selected contact")} ${left === 1 ? "has" : "have"} no unlocked email and ${left === 1 ? "is" : "are"} left out.` : ""}
+            {rows.filter((r) => !!r.work_email).length > MAX_PAID_BATCH ? ` Only the first ${MAX_PAID_BATCH.toLocaleString()} are verified in one go.` : ""}
+            {verify.error ? <span role="alert" className="mt-2 block text-destructive">The check failed. Nothing was charged for the failed call; you can try again.</span> : null}
+          </>
+        }
+        estimatedCredits={targets.length * VERIFY_CREDITS_PER_EMAIL}
+        affected={targets.length}
+        confirmLabel="Verify"
+        confirming={verify.loading}
+        onConfirm={() => void verify.mutate(targets.map((t) => t.id))}
+        onCancel={() => { setOpen(false); onClosed?.(); }}
+      />
+    </>
+  );
+}
+

package/blocks/crm/hooks/use-all-lists.ts

@@ -0,0 +1,18 @@
+"use client";
+
+/**
+ * useAllLists: every list of the workspace, for a screen that must look one up by id (its size, its name). The lists API
+ * pages (`page`, `limit`), so this reads page after page (100 each, up to 20 pages) instead of one capped `limit=200`
+ * call; `truncated` says the page cap was reached. To CHOOSE a list use ListSelect (searchable, paged).
+ *
+ * SDK operations: GET /lists?page&limit   (lists.listLists)   read - through lib/read-lists.ts
+ */
+import { useAllPages } from "@/g8/hooks/use-all-pages";
+import type { ListSelectOption } from "@/g8/components/list-select";
+import { readLists } from "../lib/read-lists";
+
+const PAGE = 100;
+
+export function useAllLists(deps: readonly unknown[] = [], enabled = true) {
+  return useAllPages<ListSelectOption>((page, signal) => readLists("", page, PAGE, signal), deps, { enabled });
+}

package/blocks/crm/hooks/use-contact-tags.ts

@@ -0,0 +1,29 @@
+"use client";
+
+/**
+ * useContactTags: the org's tag definitions (`GET /contacts/tags`), cached under ["contact-tags"] so every chip row, the
+ * assign dialog and the tag manager share one request and refresh together after a write.
+ *
+ * SDK operations: listContactTags (read). The list is not paged by the API (it answers every tag at once with a
+ * contact count), so there is no "first N" to disclose. Archived tags are left out unless asked for.
+ */
+
+import { useMemo } from "react";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { g8Get } from "@/g8/lib/g8-client";
+import { isArchivedTag, rowsOf } from "../lib/record-actions";
+import type { ContactTag } from "../lib/record-actions";
+
+export function useContactTags(options: { enabled?: boolean; includeArchived?: boolean } = {}) {
+  const { enabled = true, includeArchived = false } = options;
+  const query = useG8Query(
+    (signal) => g8Get<unknown>("/contacts/tags", includeArchived ? { include_archived: true } : undefined, { signal }),
+    [includeArchived],
+    { enabled, key: ["contact-tags", includeArchived ? "all" : "active"] },
+  );
+  const tags = useMemo(() => {
+    const rows = rowsOf<ContactTag>(query.data?.data, "tags").filter((t) => t && typeof t.id === "string" && t.id !== "");
+    return includeArchived ? rows : rows.filter((t) => !isArchivedTag(t));
+  }, [query.data, includeArchived]);
+  return { tags, loading: query.loading && !query.data, error: query.error, refetch: query.refetch, loaded: query.data != null };
+}

package/blocks/crm/hooks/use-page-query.ts

@@ -34,12 +34,14 @@ export function usePageQuery<T>(
   deps: readonly unknown[],
   pageSize = 25,
   cacheKey?: readonly unknown[],
+  /** Hold the read (for example until URL filters are known). Default true. */
+  enabled = true,
 ): UsePageQueryResult<T> {
   const key = JSON.stringify(deps);
   const [state, setState] = useState({ key, page: 1 });
   const page = state.key === key ? state.page : 1;
   const queryKey: G8QueryKey | undefined = cacheKey ? [...cacheKey, { page, pageSize, deps: key }] : undefined;
-  const query = useG8Query((signal) => fetchPage(page, signal), [key, page], { key: queryKey });
+  const query = useG8Query((signal) => fetchPage(page, signal), [key, page], { key: queryKey, enabled });
 
   const info = query.data?.pagination as Partial<PageInfo> | undefined;
   const rows = (query.data?.data ?? []) as T[];

package/blocks/crm/lib/crm-types.ts

@@ -31,6 +31,8 @@ export interface ContactRecord {
   last_name?: string | null;
   full_name?: string | null;
   work_email?: string | null;
+  /** Personal addresses, comma separated. */
+  personal_emails?: string | null;
   direct_phone?: string | null;
   mobile_phone?: string | null;
   job_title?: string | null;
@@ -107,6 +109,18 @@ export function contactName(c: Pick<ContactRecord, "first_name" | "last_name" |
   return joined || c.full_name || (c.work_email && !isMasked(c.work_email) ? c.work_email : "") || (c.id != null ? `#${c.id}` : "-");
 }
 
+/**
+ * The line under a contact's name: "VP of Sales at Acme". The company is the company's own name (`company.name`, else the
+ * list row's `company_name`); it never falls back to anything about the person. "at ..." is left out when there is no
+ * title or no company. A company that happens to share the person's name (a freelancer) is shown as the API sent it.
+ */
+export function contactSubtitle(c: Pick<ContactRecord, "job_title" | "company_name" | "company">): string {
+  const company = [c.company?.name, c.company_name].map((n) => (n ?? "").trim()).find((n) => n !== "");
+  const title = (c.job_title ?? "").trim();
+  if (title && company) return `${title} at ${company}`;
+  return title || company || "No title or company";
+}
+
 /** A company's display name: name, then domain, then `#id`, then a dash. Never "Unnamed". */
 export function companyName(c: { name?: string | null; domain?: string | null; id?: number | string }): string {
   return c.name || c.domain || (c.id != null ? `#${c.id}` : "-");

package/blocks/crm/lib/read-lists.ts

@@ -0,0 +1,16 @@
+"use client";
+
+/**
+ * readLists: one page of audience lists, for ListSelect and useAllLists.
+ *
+ * SDK operations: GET /lists?search&page&limit   (lists.listLists)   read
+ */
+import { g8Get } from "@/g8/lib/g8-client";
+import { hasNextOf } from "@/g8/lib/paging";
+import type { ListSelectOption, ListsReader } from "@/g8/components/list-select";
+
+export const readLists: ListsReader = async (q, page, pageSize, signal) => {
+  const env = await g8Get<ListSelectOption[]>("/lists", { search: q || undefined, page, limit: pageSize }, { signal });
+  const rows = (env.data ?? []) as ListSelectOption[];
+  return { rows, hasNext: hasNextOf(env, pageSize, rows.length) };
+};

package/blocks/crm/lib/record-actions.ts

@@ -0,0 +1,102 @@
+"use client";
+
+/**
+ * Shared helpers for the CRM record actions (owner, tags, bulk update, verify, unlock, AI documents, next best step).
+ * Pure functions and types only: no operations of its own.
+ *
+ * Why the sets are computed here: a confirm dialog must COUNT exactly the set the request SENDS (#25642). Every paid
+ * action filters its selection once with one of these helpers and uses the SAME array for the count, the cost line
+ * and the request body.
+ */
+
+import { isMasked } from "./crm-types";
+import type { ContactRecord } from "./crm-types";
+
+/** One contact tag definition (`GET /contacts/tags`). The handler sends `archived_at`; the contract types `archived`. */
+export interface ContactTag {
+  id: string;
+  name: string;
+  color?: string | null;
+  description?: string | null;
+  contact_count?: number | null;
+  archived?: boolean | null;
+  archived_at?: string | null;
+  is_default?: boolean | null;
+}
+
+export function isArchivedTag(tag: ContactTag): boolean {
+  return tag.archived === true || (tag.archived_at != null && tag.archived_at !== "");
+}
+
+/** The API takes six-digit hex colours only (`^#[0-9A-Fa-f]{6}$`). */
+export const HEX_COLOR = /^#[0-9A-Fa-f]{6}$/;
+
+/**
+ * The tag palette offered in the tag manager. Free choice of a hex colour is also allowed; these are only the
+ * one-click choices, so no screen ever shows a raw colour input as its only control.
+ */
+export const TAG_COLORS = ["#2563EB", "#0F766E", "#B45309", "#B91C1C", "#6D28D9", "#475569"] as const;
+
+/** `POST /contacts/unlock-info` takes at most 1000 contact ids; `POST /contacts/verify-email` at most 1000 too. */
+export const MAX_PAID_BATCH = 1000;
+
+/** One credit per newly unlocked contact (contacts/interfaces/fastapi/router.py: "estimated_credits ... 1 credit per contact"). */
+export const UNLOCK_CREDITS_PER_CONTACT = 1;
+/** One credit per verified email (the same price the enrichment block shows for a single verification). */
+export const VERIFY_CREDITS_PER_EMAIL = 1;
+
+/** A contact with any masked email or phone: unlocking reveals it. */
+export function isLockedContact(row: Pick<ContactRecord, "work_email" | "direct_phone" | "mobile_phone">): boolean {
+  return isMasked(row.work_email) || isMasked(row.direct_phone) || isMasked(row.mobile_phone);
+}
+
+/** The contacts an unlock would charge for: only the locked ones, capped at the API's batch size. */
+export function unlockTargets(rows: ReadonlyArray<ContactRecord>): ContactRecord[] {
+  return rows.filter(isLockedContact).slice(0, MAX_PAID_BATCH);
+}
+
+/** The contacts with a real work email. A locked or empty email cannot be verified, and the "***" placeholder is never sent. */
+export function verifyTargets(rows: ReadonlyArray<ContactRecord>): ContactRecord[] {
+  return rows.filter((r) => !!r.work_email && r.work_email.trim() !== "" && !isMasked(r.work_email)).slice(0, MAX_PAID_BATCH);
+}
+
+/**
+ * Fields the bulk updater offers. Names are the contact's own columns (`bulk-update` only accepts `CONTACT_*` and `udo_*` keys); anything else, including the owner (own action) and tags (own action), is not editable here.
+ */
+export const BULK_FIELDS = [
+  { key: "CONTACT_JOB_TITLE", label: "Job title" },
+  { key: "CONTACT_JOB_DEPARTMENT", label: "Department" },
+  { key: "CONTACT_SENIORITY_LEVEL", label: "Seniority" },
+  { key: "CONTACT_CITY", label: "City" },
+  { key: "CONTACT_STATE", label: "State" },
+  { key: "CONTACT_COUNTRY", label: "Country" },
+] as const;
+export type BulkFieldKey = (typeof BULK_FIELDS)[number]["key"];
+
+/** The result rows of a verify call. */
+export interface VerifyRow {
+  contact_pk?: number;
+  outcome?: "verified" | "already_verified" | "inconclusive" | "not_verified" | null;
+  verification_result?: string | null;
+  charged_credits?: number;
+}
+
+/** "Verified 3, already verified 1, inconclusive 1 (not charged). 3 credits charged." */
+export function verifySummary(rows: ReadonlyArray<VerifyRow>): string {
+  const n = (o: string) => rows.filter((r) => r.outcome === o).length;
+  const parts = [
+    `Verified ${n("verified")}`,
+    n("already_verified") ? `already verified ${n("already_verified")}` : "",
+    n("inconclusive") ? `inconclusive ${n("inconclusive")} (not charged)` : "",
+    n("not_verified") ? `no answer for ${n("not_verified")} (not charged)` : "",
+  ].filter(Boolean);
+  const charged = rows.reduce((max, r) => Math.max(max, r.charged_credits ?? 0), 0);
+  return `${parts.join(", ")}. ${charged.toLocaleString()} ${charged === 1 ? "credit" : "credits"} charged.`;
+}
+
+/** The array inside an envelope `data` that is either the array itself or `{ <key>: [...] }`. */
+export function rowsOf<T>(data: unknown, key: string): T[] {
+  if (Array.isArray(data)) return data as T[];
+  const inner = (data as Record<string, unknown> | null | undefined)?.[key];
+  return Array.isArray(inner) ? (inner as T[]) : [];
+}

package/blocks/deals/README.md

@@ -11,19 +11,33 @@ compose under `DealDetail`'s `children`). Drag and drop needs `npm i @dnd-kit/co
 
 - Board and List views, search by name, a pipeline switcher when there is more than one pipeline.
 - Headline numbers: open deals, open value, estimated weighted value, won value.
-- Open a deal (board card or list row, deep link `?id=<deal id>`): Details (edit, stage history, confirmed delete) and
-  Activity tabs. Moving a card into a won or lost stage asks for the close date and amount first.
+- Open a deal (board card or list row, deep link `?id=<deal id>`): Details (edit, stage history, confirmed delete),
+  Contacts (add with a role, change a role, make primary, remove), Line items (add, edit, remove, totals), Notes (add,
+  edit, delete), Tasks (add, complete), Quotes and Activity tabs. Moving a card into a won or lost stage asks for the
+  close date and amount first.
+- **Close deal** (detail header): won or lost, with a close date, an amount for won, and a reason picked from the org's
+  close reasons (add one on the spot). **API gap:** no deal operation accepts a close reason (`closed_lost_reason` is
+  read only), so the reason is saved as a deal note, "Closed lost. Reason: Price". **Move to pipeline** is next to it.
+- Filters on Board and List: owner, stage, outcome (open, won, lost), stale (no activity for 7 to 90 days, or never),
+  activity, close-date range and "no contact". `filterQuery(state)` turns them into the `GET /deals` parameters.
+- Pipeline settings: create, rename, make default and delete (confirmed) pipelines, add or archive close reasons,
+  then the stage summary and StageEditor.
+- Quotes tab: the deal's quotes. To offer "Create quote from this deal", pass the quotes block's button:
+  `<DealsScreen renderQuoteActions={(deal) => <CreateQuoteFromDeal dealId={deal.id} />} />` (quotes depends on deals,
+  so the deals block cannot import it).
 - **New deal**: name, amount, close date, stage, an **owner** and **at least one contact**. The API requires both
   (`owner_id`, and `contact_ids` with one or more mashup contact ids that all work at one company; the older note that
   the list may be empty was wrong). A company that already has a deal is refused with 409 unless "Allow another deal"
   is ticked.
-- Forecast tab (totals, win rate, stuck deals, estimated weighted pipeline) and Pipeline settings tab (stage names,
-  probabilities, won/lost types, order, delete).
+- Forecast tab (totals, win rate, stuck deals, estimated weighted pipeline) and Pipeline settings tab (pipelines, close
+  reasons, stage names, probabilities, won/lost types, order, delete).
 - Slots for cross-block glue, all optional: `renderRowActions(deal)`, `renderDetailActions(deal)`,
   `extraDetailTabs`, `toolbarActions`. Example: add a Quotes tab with `<QuoteList dealId={deal.id} />`.
 
-Scopes the screen needs on top of the lists below: `team:read` (owner default and picker) and `contacts:read`
-(contact search). Proxy `allowedPrefixes` must include `deals`, `pipelines`, `team-members`, `contacts` (and `activity`
+Scopes the screen needs on top of the lists below: `team:read` (owner default and picker), `contacts:read`
+(contact search), `notes:read` and `notes:write` (Notes tab), `tasks:read` and `tasks:write` (Tasks tab) and
+`deals:delete` (remove a contact, delete a note, archive a close reason).
+Proxy `allowedPrefixes` must include `deals`, `pipelines`, `team-members`, `contacts`, `tasks` (and `activity`
 for the timeline).
 
 
@@ -107,3 +121,8 @@ create), `deal.id` + `deal.revision` (card -> detail -> update/delete).
 - `01-create-deal-and-advance.ts`: create, move, close as won.
 - `02-pipeline-report.ts`: totals, win rate, stall points, estimated weighted forecast.
 - `03-stale-deals-sweep.ts`: find neglected open deals, optionally flag them with one bulk write.
+
+## Cross-block glue
+
+- `RecordDealsTab` (`components/record-deals-tab.tsx`): the deals of one contact or company (`GET /contacts/{id}/deals`, `GET /companies/{id}/deals`), each opening in the deals screen. Use it as an `extraDetailTabs` entry of `ContactsScreen` / `CompaniesScreen`. `DealsScreen` also takes optional `onOpenContact` / `onOpenCompany`: the Contacts tab gains "Open in contacts" and the contact sheet gains "Open company".
+- `CreateDealButton` (`components/create-deal-button.tsx`): "Create deal" for one contact. A sheet with the deal form already filled in from the contact and their company (linked contact, name "<company> - <contact>", owner from the key's person or a picker). `onCreated(dealId)` routes to the new deal. The company comes from the contact (the API derives it), and a company that already has a deal is refused until "Create another deal for this company" is ticked. Use it in `ContactsScreen.renderDetailActions`.

package/blocks/deals/block.json

@@ -8,30 +8,57 @@
     "optimistic stage moves with rollback and closed-stage rules handled",
     "deal create, edit, stage history and confirmed delete",
     "stage editor: names, probabilities, won/lost types, order",
-    "forecast: totals, win rate, stuck deals and an estimated weighted pipeline"
+    "forecast: totals, win rate, stuck deals and an estimated weighted pipeline",
+    "deal notes, tasks, contacts with roles and primary, and line items with totals",
+    "close a deal as won or lost with a reason",
+    "create, rename, default and delete pipelines, and manage close reasons",
+    "list filters: owner, stage, outcome, stale, activity, close-date range, no contact"
   ],
   "dependsOn": [
     "crm"
   ],
   "operations": [
+    "add_deal_contact_deals__deal_id__contacts_post",
+    "archive_deal_close_reason_deals_close_reasons__reason_id__delete",
+    "create_deal_close_reason_deals_close_reasons_post",
     "create_deal_deals_post",
+    "create_deal_note_deals__deal_id__notes_post",
+    "create_global_task_tasks_post",
+    "create_pipeline_pipelines_post",
     "create_stage_pipelines__pipeline_id__stages_post",
     "delete_deal_deals__deal_id__delete",
+    "delete_deal_note_deals__deal_id__notes__note_id__delete",
+    "delete_pipeline_pipelines__pipeline_id__delete",
     "delete_stage_pipelines__pipeline_id__stages__stage_id__delete",
+    "get_company_deals_companies__company_id__deals_get",
+    "get_contact_contacts__contact_id__get",
+    "get_contact_deals_contacts__contact_id__deals_get",
     "get_deal_analytics_deals_analytics_get",
     "get_deal_deals__deal_id__get",
     "get_deal_stage_velocity_deals_stage_velocity_get",
     "get_my_team_member_team_members_me_get",
     "get_pipeline_pipelines__pipeline_id__get",
+    "list_all_tasks_tasks_get",
     "list_contacts_contacts_get",
+    "list_deal_close_reasons_deals_close_reasons_get",
     "list_deal_history_deals__deal_id__history_get",
+    "list_deal_line_items_deals__deal_id__line_items_get",
+    "list_deal_notes_deals__deal_id__notes_get",
     "list_deals_deals_get",
     "list_pipelines_deals_pipelines_get",
     "list_quotes_quotes_get",
     "list_team_members_team_members_get",
+    "move_deal_to_pipeline_deals__deal_id__pipeline_put",
+    "remove_deal_contact_deals__deal_id__contacts__person_id__delete",
     "reorder_stages_pipelines__pipeline_id__stages_reorder_put",
+    "replace_deal_line_items_deals__deal_id__line_items_put",
+    "set_deal_contact_role_deals__deal_id__contacts__contact_id__put",
+    "set_primary_deal_contact_deals__deal_id__contacts__person_id__primary_put",
     "update_deal_deals__deal_id__patch",
-    "update_stage_pipelines__pipeline_id__stages__stage_id__put"
+    "update_deal_note_deals__deal_id__notes__note_id__put",
+    "update_pipeline_pipelines__pipeline_id__put",
+    "update_stage_pipelines__pipeline_id__stages__stage_id__put",
+    "update_task_tasks__task_id__patch"
   ],
   "components": [
     {
@@ -120,6 +147,137 @@
       "tiers": [
         "read"
       ]
+    },
+    {
+      "name": "DealNotesTab",
+      "file": "components/deal-notes-tab.tsx",
+      "purpose": "Notes of one deal: list, add, edit (only when the text changed) and confirmed delete; synced notes are read only.",
+      "operations": [
+        "create_deal_note_deals__deal_id__notes_post",
+        "delete_deal_note_deals__deal_id__notes__note_id__delete",
+        "list_deal_notes_deals__deal_id__notes_get",
+        "update_deal_note_deals__deal_id__notes__note_id__put"
+      ],
+      "tiers": [
+        "read",
+        "write",
+        "destructive"
+      ]
+    },
+    {
+      "name": "DealTasksTab",
+      "file": "components/deal-tasks-tab.tsx",
+      "purpose": "Follow-up tasks linked to one deal: list (open or all), add with due date and priority, complete and reopen.",
+      "operations": [
+        "create_global_task_tasks_post",
+        "list_all_tasks_tasks_get",
+        "update_task_tasks__task_id__patch"
+      ],
+      "tiers": [
+        "read",
+        "write"
+      ]
+    },
+    {
+      "name": "DealContactsEditor",
+      "file": "components/deal-contacts-editor.tsx",
+      "purpose": "Buying committee of one deal: add a contact with a role, change a role, make one primary, remove one (confirmed).",
+      "operations": [
+        "add_deal_contact_deals__deal_id__contacts_post",
+        "get_deal_deals__deal_id__get",
+        "list_contacts_contacts_get",
+        "remove_deal_contact_deals__deal_id__contacts__person_id__delete",
+        "set_deal_contact_role_deals__deal_id__contacts__contact_id__put",
+        "set_primary_deal_contact_deals__deal_id__contacts__person_id__primary_put"
+      ],
+      "tiers": [
+        "read",
+        "write",
+        "destructive"
+      ]
+    },
+    {
+      "name": "DealLineItems",
+      "file": "components/deal-line-items.tsx",
+      "purpose": "Products on a deal: add, edit and remove lines (dollars in, cents sent), per-line totals, the deal total and the quote-mismatch warning.",
+      "operations": [
+        "list_deal_line_items_deals__deal_id__line_items_get",
+        "replace_deal_line_items_deals__deal_id__line_items_put"
+      ],
+      "tiers": [
+        "read",
+        "write"
+      ]
+    },
+    {
+      "name": "DealActions",
+      "file": "components/close-deal-dialog.tsx",
+      "purpose": "Deal header actions: Close deal as won or lost with a reason (saved as a note, the API has no reason field), add close reasons, and Move to pipeline. CloseDealDialog is the dialog alone.",
+      "operations": [
+        "create_deal_close_reason_deals_close_reasons_post",
+        "create_deal_note_deals__deal_id__notes_post",
+        "list_deal_close_reasons_deals_close_reasons_get",
+        "move_deal_to_pipeline_deals__deal_id__pipeline_put",
+        "update_deal_deals__deal_id__patch"
+      ],
+      "tiers": [
+        "read",
+        "write"
+      ]
+    },
+    {
+      "name": "PipelineEditor",
+      "file": "components/pipeline-editor.tsx",
+      "purpose": "Create, rename, make default and delete (confirmed) pipelines, and add or archive (confirmed) close reasons. Stages are edited by StageEditor.",
+      "operations": [
+        "archive_deal_close_reason_deals_close_reasons__reason_id__delete",
+        "create_deal_close_reason_deals_close_reasons_post",
+        "create_pipeline_pipelines_post",
+        "delete_pipeline_pipelines__pipeline_id__delete",
+        "list_deal_close_reasons_deals_close_reasons_get",
+        "list_pipelines_deals_pipelines_get",
+        "update_pipeline_pipelines__pipeline_id__put"
+      ],
+      "tiers": [
+        "read",
+        "write",
+        "destructive"
+      ]
+    },
+    {
+      "name": "DealFilterBar",
+      "file": "components/deal-filters.tsx",
+      "purpose": "List filters: owner, stage, outcome, stale (7 to 90 days), activity, close-date range and no contact. Pass filterQuery(state) to usePipelineDeals.",
+      "operations": [],
+      "tiers": []
+    },
+    {
+      "name": "RecordDealsTab",
+      "file": "components/record-deals-tab.tsx",
+      "purpose": "The deals linked to one contact or company, each opening in the deals screen; an extraDetailTabs entry for ContactsScreen and CompaniesScreen.",
+      "operations": [
+        "get_contact_deals_contacts__contact_id__deals_get",
+        "get_company_deals_companies__company_id__deals_get"
+      ],
+      "tiers": [
+        "read"
+      ]
+    },
+    {
+      "name": "CreateDealButton",
+      "file": "components/create-deal-button.tsx",
+      "purpose": "\"Create deal\" for one contact: a sheet with the deal form prefilled from the contact and their company (linked contact, name \"<company> - <contact>\", owner, pipeline stage). Calls onCreated(dealId) so you can route to the new deal.",
+      "operations": [
+        "create_deal_deals_post",
+        "get_contact_contacts__contact_id__get",
+        "get_my_team_member_team_members_me_get",
+        "list_pipelines_deals_pipelines_get",
+        "list_team_members_team_members_get"
+      ],
+      "tiers": [
+        "read",
+        "write"
+      ]
     }
   ],
   "hooks": [
@@ -154,6 +312,10 @@
     {
       "file": "lib/deals-types.ts",
       "purpose": "Deal, pipeline and stage types, stage kind, money formatting, weighted-pipeline estimate and closed-stage error markers."
+    },
+    {
+      "file": "lib/deal-extras.ts",
+      "purpose": "Note, task, line-item and close-reason shapes, contact roles, money in cents, and the deal filter state with its GET /deals query."
     }
   ],
   "recipes": [
@@ -201,7 +363,11 @@
     "deals:delete",
     "deals:read",
     "deals:write",
+    "notes:read",
+    "notes:write",
     "quotes:read",
+    "tasks:read",
+    "tasks:write",
     "team:read"
   ],
   "defaults": [