@graph8/sdk 0.362.0 → 0.373.0

package/blocks/deals/components/stage-editor.tsx

@@ -45,21 +45,21 @@ export function StageEditor({ pipelineId, onChanged, className }: StageEditorPro
     const saved = dataOf<Stage>(await g8Put(`${base}/stages/${encodeURIComponent(s.id)}`, { name: s.name, probability: s.probability ?? 0, stage_type: s.stage_type ?? "open", color: s.color ?? undefined }));
     done(stages.map((x) => (x.id === saved.id ? { ...x, ...saved } : x)));
     } finally { setSavingId(null); }
-  });
+  }, { invalidates: [["deals", "pipelines"]] });
   const add = useG8Mutation(async (name: string) => {
     const created = dataOf<Stage>(await g8Post(`${base}/stages`, { name, probability: 0, stage_type: "open" }));
     done([...stages, created]);
     setNewName("");
-  });
+  }, { invalidates: [["deals", "pipelines"]] });
   const reorder = useG8Mutation(async (next: Stage[]) => {
     await g8Put(`${base}/stages/reorder`, { stage_ids: next.map((s) => s.id) });
     done(next);
-  });
+  }, { invalidates: [["deals", "pipelines"]] });
   const remove = useG8Mutation(async (s: Stage) => {
     await g8Delete(`${base}/stages/${encodeURIComponent(s.id)}`);
     done(stages.filter((x) => x.id !== s.id));
     setRemoving(null);
-  }, { onError: () => setRemoving(null) });
+  }, { invalidates: [["deals", "pipelines"]], onError: () => setRemoving(null) });
 
   const patch = (id: string, change: Partial<Stage>) => setStages((all) => all.map((s) => (s.id === id ? { ...s, ...change } : s)));
   const swap = (i: number, j: number) => { const next = [...stages]; [next[i], next[j]] = [next[j], next[i]]; void reorder.mutate(next); };
@@ -69,7 +69,7 @@ export function StageEditor({ pipelineId, onChanged, className }: StageEditorPro
   if (pipeline.loading && !pipeline.data) return <Skeleton className="h-48 w-full" aria-label="Loading stages" />;
   return (
     <div className={`space-y-3 ${className ?? ""}`}>
-      <h2 className="text-base font-semibold">{pipeline.data?.name} stages</h2>
+      <h2 className="text-base font-medium">{pipeline.data?.name} stages</h2>
       {failure ? <ApiError error={failure} title="That stage change failed" /> : null}
       <ol className="space-y-2">
         {stages.map((s, i) => (

package/blocks/deals/hooks/use-pipeline-deals.ts

@@ -4,7 +4,7 @@
  * usePipelineDeals: the deals in one pipeline, all pages up to `maxDeals`, with an optimistic stage move.
  *
  * SDK operations:
- *   GET   /deals?pipeline_id=&search=&owner_id=&page=&limit=   (deals.listDeals)   read
+ *   GET   /deals?pipeline_id=&search=&owner_id=&stage_id=&outcome=&stale_before=&has_activity=&close_after=&close_before=&has_contact=&page=&limit=   (deals.listDeals)   read
  *   PATCH /deals/{deal_id}                                      (deals.updateDeal)  write - the stage move
  *
  * `moveDeal` updates the board immediately and, if the API refuses, refetches the list (the server is the truth)
@@ -15,12 +15,26 @@
 import { useCallback, useEffect, useState } from "react";
 import { g8Get, g8Patch } from "@/g8/lib/g8-client";
 import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { invalidate } from "@/g8/lib/g8-cache";
 import type { Deal } from "../lib/deals-types";
 import { dataOf } from "../lib/deals-types";
 
 export interface PipelineDealFilters {
   search?: string;
   ownerId?: string;
+  /** Only this stage (GET /deals stage_id). */
+  stageId?: string;
+  /** Exactly one of open, won or lost. */
+  outcome?: string;
+  /** Deals last touched before this timestamp OR never touched (GET /deals stale_before). */
+  staleBefore?: string;
+  hasActivity?: boolean;
+  /** Close date on or after this timestamp or YYYY-MM-DD (inclusive). */
+  closeAfter?: string;
+  /** Close date strictly before this timestamp or YYYY-MM-DD (exclusive). */
+  closeBefore?: string;
+  /** false returns the deals with no contact. */
+  hasContact?: boolean;
 }
 
 export interface MoveExtra {
@@ -35,14 +49,14 @@ export function usePipelineDeals(pipelineId: string | undefined, filters: Pipeli
     async (signal) => {
       const all: Deal[] = [];
       for (let page = 1; all.length < maxDeals; page++) {
-        const env = await g8Get<Deal[]>("/deals", { pipeline_id: pipelineId, search: filters.search || undefined, owner_id: filters.ownerId || undefined, page, limit: 100 }, { signal });
+        const env = await g8Get<Deal[]>("/deals", { pipeline_id: pipelineId, search: filters.search || undefined, owner_id: filters.ownerId || undefined, stage_id: filters.stageId, outcome: filters.outcome, stale_before: filters.staleBefore, has_activity: filters.hasActivity, close_after: filters.closeAfter, close_before: filters.closeBefore, has_contact: filters.hasContact, page, limit: 100 }, { signal });
         all.push(...(env.data ?? []));
         if (!env.pagination?.has_next) break;
       }
       return all.slice(0, maxDeals);
     },
-    [pipelineId, filters.search, filters.ownerId, maxDeals],
-    { enabled: Boolean(pipelineId) },
+    [pipelineId, filters.search, filters.ownerId, filters.stageId, filters.outcome, filters.staleBefore, filters.hasActivity, filters.closeAfter, filters.closeBefore, filters.hasContact, maxDeals],
+    { enabled: Boolean(pipelineId), key: ["deals", "list", "board", { pipelineId, search: filters.search || undefined, ownerId: filters.ownerId || undefined, stageId: filters.stageId, outcome: filters.outcome, staleBefore: filters.staleBefore, hasActivity: filters.hasActivity, closeAfter: filters.closeAfter, closeBefore: filters.closeBefore, hasContact: filters.hasContact, maxDeals }] },
   );
   useEffect(() => { if (query.data) setDeals(query.data); }, [query.data]);
 
@@ -53,6 +67,9 @@ export function usePipelineDeals(pipelineId: string | undefined, filters: Pipeli
     try {
       const saved = dataOf<Deal>(await g8Patch(`/deals/${encodeURIComponent(deal.id)}`, { stage_id: stageId, expected_revision: deal.revision ?? undefined, ...extra }));
       setDeals((all) => all.map((d) => (d.id === deal.id ? { ...d, ...saved } : d)));
+      // The deal's revision changed: a cached detail or history of it is out of date.
+      void invalidate(["deals", "detail"]);
+      void invalidate(["deals", "history"]);
       return saved;
     } catch (err) {
       // Roll back by re-reading the server's truth: a snapshot taken before the move could itself be stale.

package/blocks/deals/hooks/use-pipelines.ts

@@ -13,7 +13,7 @@ export function usePipelines() {
   const q = useG8Query(async (signal) => {
     const env = await g8Get<Pipeline[]>("/deals/pipelines", undefined, { signal });
     return (env.data ?? []).map((p) => ({ ...p, stages: sortedStages(p) }));
-  }, []);
+  }, [], { key: ["deals", "pipelines"] });
   const pipelines = q.data ?? [];
   return { ...q, pipelines, defaultPipeline: pipelines.find((p) => p.is_default) ?? pipelines[0] };
 }

package/blocks/deals/lib/deal-extras.ts

@@ -0,0 +1,156 @@
+"use client";
+
+/**
+ * Shapes and pure helpers for the deal depth components: notes, tasks, contact roles, line items, close reasons
+ * and the list filters. Types only describe the fields the components read; the API may return more.
+ *
+ * Money: a deal's `amount` is in DOLLARS (major units); a LINE ITEM's `unit_amount` and `line_total` are in CENTS.
+ * Dates: date-only values are `YYYY-MM-DD` and are shifted with UTC arithmetic, never through a local Date.
+ */
+import { dataOf } from "./deals-types";
+
+/** Buying-committee roles the API accepts on a deal contact (any other value is a 422). */
+export const CONTACT_ROLES = ["champion", "decision_maker", "influencer", "blocker", "coach", "end_user"] as const;
+
+export function roleLabel(role: string | null | undefined): string {
+  if (!role) return "No role";
+  const text = role.replace(/_/g, " ");
+  return text.charAt(0).toUpperCase() + text.slice(1);
+}
+
+export interface DealNote {
+  id: string;
+  content: string;
+  created_by_name?: string | null;
+  created_at?: string | null;
+  updated_at?: string | null;
+  read_only?: boolean;
+}
+
+export interface DealTask {
+  id: string;
+  title: string;
+  description?: string | null;
+  due_date?: string | null;
+  status?: string | null;
+  priority?: number | null;
+  assignee_name?: string | null;
+}
+
+export interface DealLineItem {
+  id?: string;
+  product_name: string;
+  description?: string | null;
+  quantity: number;
+  /** Cents. */
+  unit_amount: number;
+  discount_pct: number;
+  billing_frequency?: string | null;
+  sort_order?: number;
+  stripe_product_id?: string | null;
+  stripe_price_id?: string | null;
+  manual_product_id?: string | null;
+}
+
+export interface LineItemsPayload {
+  deal_id: string;
+  /** Dollars. */
+  amount?: number | null;
+  currency?: string | null;
+  line_items?: DealLineItem[];
+  amount_mismatch?: boolean;
+  /** Dollars. */
+  linked_quote_total?: number | null;
+}
+
+export interface CloseReason {
+  id: string;
+  label: string;
+  kind: string;
+  /** Whether this person may archive it (created it themselves, or may manage all). */
+  canArchive: boolean;
+}
+
+/** Rows of a list response that is either a bare array or `{ items | tasks | notes | reasons | contacts: [] }`. */
+export function rowsOf<T>(env: unknown): T[] {
+  const inner = dataOf<unknown>(env);
+  if (Array.isArray(inner)) return inner as T[];
+  const o = inner as Record<string, unknown> | null;
+  for (const key of ["items", "tasks", "notes", "reasons", "contacts"]) if (o && Array.isArray(o[key])) return o[key] as T[];
+  return [];
+}
+
+/** The close reasons of `GET /deals/close-reasons`: `{ can_manage, reasons: [{ id, label, kind, archived? }] }`. */
+export function reasonsOf(env: unknown): CloseReason[] {
+  const inner = dataOf<{ can_manage?: boolean | null; reasons?: Array<Record<string, unknown>> } | null>(env);
+  const manage = Boolean(inner?.can_manage);
+  return (inner?.reasons ?? [])
+    .filter((r) => !r.archived && !r.archived_at)
+    .map((r) => ({ id: String(r.id ?? ""), label: String(r.label ?? r.name ?? ""), kind: String(r.kind ?? ""), canArchive: manage || r.can_archive === true || r.can_delete === true }))
+    .filter((r) => r.id && r.label);
+}
+
+/** Whole cents from a dollars text input; null when it is not a non-negative number. */
+export function dollarsToCents(text: string): number | null {
+  const n = Number(text.trim());
+  return text.trim() !== "" && Number.isFinite(n) && n >= 0 ? Math.round(n * 100) : null;
+}
+
+export const centsToDollarsText = (cents: number): string => (cents / 100).toFixed(2);
+
+export function lineTotalCents(l: Pick<DealLineItem, "unit_amount" | "quantity" | "discount_pct">): number {
+  return Math.round(l.unit_amount * l.quantity * (1 - Math.min(100, Math.max(0, l.discount_pct)) / 100));
+}
+
+export function formatCents(cents: number | null | undefined, currency?: string | null): string {
+  if (cents == null) return "";
+  try {
+    return new Intl.NumberFormat(undefined, { style: "currency", currency: currency || "USD" }).format(cents / 100);
+  } catch {
+    return String(cents / 100);
+  }
+}
+
+/** `date` (YYYY-MM-DD) shifted by whole days, in UTC so the result is the same in every time zone. */
+export function addDaysUtc(date: string, days: number): string {
+  const d = new Date(`${date}T00:00:00Z`);
+  d.setUTCDate(d.getUTCDate() + days);
+  return d.toISOString().slice(0, 10);
+}
+
+/** Midnight UTC `days` before today, as an ISO timestamp. Stable all day, so it can sit in a query key. */
+export function staleCutoff(days: number, now = new Date()): string {
+  return new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate() - days)).toISOString();
+}
+
+export interface DealFilterState {
+  ownerId: string;
+  stageId: string;
+  outcome: "" | "open" | "won" | "lost";
+  /** Only deals untouched for this many days (or never touched). "" = off. */
+  staleDays: "" | "7" | "14" | "30" | "60" | "90";
+  activity: "" | "yes" | "no";
+  /** Inclusive date range of the close date. */
+  closeFrom: string;
+  closeTo: string;
+  /** Only deals with no contact at all. */
+  orphaned: boolean;
+}
+
+export const NO_FILTERS: DealFilterState = { ownerId: "", stageId: "", outcome: "", staleDays: "", activity: "", closeFrom: "", closeTo: "", orphaned: false };
+
+export const filtersActive = (f: DealFilterState): boolean => (Object.keys(NO_FILTERS) as Array<keyof DealFilterState>).some((k) => f[k] !== NO_FILTERS[k]);
+
+/** The `GET /deals` query for a filter state. `close_before` is exclusive, so the inclusive "to" date becomes the next day. */
+export function filterQuery(f: DealFilterState, now = new Date()) {
+  return {
+    ownerId: f.ownerId || undefined,
+    stageId: f.stageId || undefined,
+    outcome: f.outcome || undefined,
+    staleBefore: f.staleDays ? staleCutoff(Number(f.staleDays), now) : undefined,
+    hasActivity: f.activity === "" ? undefined : f.activity === "yes",
+    closeAfter: f.closeFrom || undefined,
+    closeBefore: f.closeTo ? addDaysUtc(f.closeTo, 1) : undefined,
+    hasContact: f.orphaned ? false : undefined,
+  };
+}

package/blocks/dialer/README.md

@@ -9,6 +9,28 @@ browser, record outcomes, and review transcripts. Copy `DialerWorkspace` for the
 > voicemail, or mints a softphone credential without a confirm dialog first, and the block never auto-advances to
 > the next batch.
 
+## Screens
+
+- `DialerScreen` (`components/dialer-screen.tsx`): **Session** tab picks a list (ListPicker), creates a session (dials
+  nobody), then runs the queue: every batch, voicemail drop, softphone credential and stop is confirmed; finished calls
+  open the outcome panel and transcript. **Sessions** tab lists every session; a row opens `DialerSessionDetail` (stats, details, calls, queue; pause, confirmed resume, confirmed stop; `?tab=sessions&session=<id>`). **History** tab lists the rep's calls. Props are optional: `userId` (overrides the rep; without it the
+  rep is the signed-in team member from `GET /team-members/me`, so the softphone works out of the box with a personal key,
+  and a `MemberPicker` switches rep where the API allows it; a personal key naming another rep gets a 403, which the form
+  explains; an organisation key is not a person, so the rep is chosen with the picker), `userEmail`, `listId`, `sessionId`, `transport` (default: the Twilio adapter, loaded
+  on demand, needs `@twilio/voice-sdk`). Resume a session with `?session=<id>`. Add `&view=full` to any detail (session, call, and the same in the other screens) to open it as a full page.
+- `CallLogScreen` (`components/call-log-screen.tsx`): history of one rep, contact or session with outcome filter and search;
+  open a call for recording, transcript and AI grade (`?id=<room_name>`), and **Call back** the number (`CallContactButton`). Needs a rep email (it asks) or a prop.
+- Slots on both: `toolbarActions`, `renderRowActions`, `renderDetailActions`, `extraDetailTabs`.
+- `CallContactButton` (`components/call-contact-button.tsx`): **call one contact from any screen**. Drop it into a
+  contact page's `renderDetailActions` (the apollo and outreach stacks do) or a row slot: `<CallContactButton contact={c} />`.
+  Closed, it loads nothing. Open: pick the number (masked `***` numbers are never offered), a PAUSED or COMPLETED
+  session to log the call under, and the caller ID; turn on the softphone; confirm (external, 1 recipient). It calls
+  `POST /dialer/parallel-calls/manual-dial` and the softphone joins the returned `conference_name`. The rep is
+  `userId` if passed, else the personal key's user (`GET /team-members/me`); an organisation key is not a rep, so it
+  then asks for `userId`. Why not `next-batch` with `force_next_contact`: that only picks a contact already in the
+  session's list and dials a whole batch.
+Scopes: `voice:read`, `voice:write`, `voice:run` (and `team:read` for `CallContactButton` without `userId`). A phone number must exist (buy or verify it in the graph8 app).
+
 ## How it works (read this before building)
 
 - graph8 places the calls **from its servers** into a conference. The rep's browser only **joins that
@@ -70,8 +92,10 @@ Softphone), `call_id` = `room_name` (live call -> disposition -> transcript -> r
 
 ## Stack nav pages
 
-`CallQueue` and `CallLog` render with no props (a stack uses them as pages): the start form asks for the rep's user id
-and the call log for a rep email. Pass `userId` / `userEmail` from your session to skip those fields.
+`CallQueue` and `CallLog` render with no props (a stack uses them as pages): the start form defaults the rep to the
+signed-in team member (a `MemberPicker` switches it; the raw user id is only a fallback under "Use a user id instead"),
+the list is a `ListPicker`, and the call log shows the signed-in rep's calls (a rep email can still be typed). Pass
+`userId` / `userEmail` from your session to override.
 
 ## Gotchas
 
@@ -81,13 +105,22 @@ and the call log for a rep email. Pass `userId` / `userEmail` from your session
 - Voicemail drop plays the rep's cloned voice to a stranger's phone. The confirm dialog names the contact.
 - Another tenant's session id is a 404, the same as a missing one.
 - Manual dial (`POST /dialer/parallel-calls/manual-dial`, external) needs a PAUSED or COMPLETED session and can
-  create a contact; it is a server recipe here, not a component.
+  create a contact (an unknown number is matched to a contact or one is created). `CallContactButton` uses it.
+- **Late join.** The conference name of a batch is only known from the `next-batch` (or `manual-dial`) response; the
+  app learns the NEXT batch's name earlier over a WebSocket the API does not have, and the session read does not
+  expose it. Voice waits up to 2 s for the rep only when the name was announced, so an SDK softphone joins after the
+  dials go out and the first second of an instant answer can be missed (voice's late-join reconciliation still
+  connects the audio). Keep the softphone registered BEFORE dialing (`CallContactButton` only enables the call once
+  it is ready) so the join is a single `joinConference` the moment the response lands.
+- `next-batch` `user_email`: with a personal key the dialer's rep is the key's own user (naming someone else is a
+  403); with an organisation key the name is passed through but not vouched for, so voice keeps dialing without
+  moving the session to that rep.
 
 ## Operations
 
 | Operation | Method and path | Tier | Used by |
 |---|---|---|---|
-| `voice.listDialerNumbers` | GET /voice/dialer/numbers | read | SessionStartForm |
+| `voice.listDialerNumbers` | GET /voice/dialer/numbers | read | SessionStartForm, CallContactButton |
 | `dialer.createSessionDraft` | POST /dialer/sessions/draft | write | SessionStartForm |
 | `dialer.readQueueStats` | GET /dialer/sessions/{id}/queue-stats | read | useDialerSession |
 | `voice.getDialerSession` | GET /dialer/sessions/{id} | read | useDialerSession |
@@ -106,9 +139,17 @@ and the call log for a rep email. Pass `userId` / `userEmail` from your session
 | `voice.getCallTranscript` | GET /voice/dialer/calls/{room}/transcript | read | TranscriptViewer |
 | `voice.getCallGrading` | GET /voice/dialer/calls/{room}/grading | read | TranscriptViewer |
 | `voice.downloadCallRecording` | GET /voice/calls/{id}/recording | read | TranscriptViewer |
+| `teamMembers.getMyTeamMember` | GET /team-members/me | read | CallContactButton, DialerScreen, SessionStartForm, CallLogScreen (only without `userId` / `userEmail`; via the pickers block `useCurrentMember`) |
+| `voice.listDialerSessions` | GET /voice/dialer/sessions | read | CallContactButton |
+| `dialer.manualDial` | POST /dialer/parallel-calls/manual-dial | external | CallContactButton |
 
 ## Recipes (server side)
 
 - `01-create-session-and-dial.ts`: draft, one confirmed batch, poll queue-stats.
 - `02-disposition-calls.ts`: record outcomes from the org's accepted list.
 - `03-review-a-call.ts`: transcript, AI grade, rep performance (`dialerAnalytics`).
+
+## Cross-block glue
+
+
+- `RecordCallsTab` (`components/record-calls-tab.tsx`): a contact's call history (`listCallsForContact`, 25 then "Show more" up to the API maximum of 100, then a notice) with a confirmed `CallContactButton`. `extraDetailTabs` entry for ContactsScreen.

package/blocks/dialer/block.json

@@ -11,7 +11,8 @@
     "call log, transcript, AI grading and recording per call"
   ],
   "dependsOn": [
-    "lists"
+    "lists",
+    "pickers"
   ],
   "operations": [
     "create_session_draft_dialer_sessions_draft_post",
@@ -21,15 +22,20 @@
     "get_call_grading_voice_dialer_calls__room_name__grading_get",
     "get_call_transcript_voice_dialer_calls__room_name__transcript_get",
     "get_dialer_session_dialer_sessions__session_id__get",
+    "get_my_team_member_team_members_me_get",
     "hangup_session_call_dialer_sessions_calls_hangup_post",
     "list_calls_for_contact_voice_dialer_calls_get",
     "list_dialer_numbers_voice_dialer_numbers_get",
+    "list_dialer_sessions_voice_dialer_sessions_get",
+    "list_team_members_team_members_get",
     "list_voice_dispositions_voice_dispositions_get",
+    "manual_dial_dialer_parallel_calls_manual_dial_post",
     "mint_softphone_token_dialer_sessions_token_get",
     "mute_call_dialer_sessions_calls_mute_post",
     "pause_dialer_session_dialer_sessions__session_id__pause_post",
     "read_queue_stats_dialer_sessions__session_id__queue_stats_get",
     "read_session_grid_dialer_sessions__session_id__grid_post",
+    "resume_dialer_session_voice_dialer_sessions__session_id__resume_post",
     "set_call_disposition_dialer_parallel_calls_calls__livekit_room_name__disposition_patch",
     "skip_contact_dialer_sessions__session_id__calls_skip_contact_post",
     "stop_dialer_session_dialer_sessions__session_id__stop_post"
@@ -60,7 +66,9 @@
       "purpose": "Create a draft session (dials nobody) for a list, caller ID and mode.",
       "operations": [
         "create_session_draft_dialer_sessions_draft_post",
-        "list_dialer_numbers_voice_dialer_numbers_get"
+        "get_my_team_member_team_members_me_get",
+        "list_dialer_numbers_voice_dialer_numbers_get",
+        "list_team_members_team_members_get"
       ],
       "tiers": [
         "read",
@@ -135,6 +143,72 @@
       "purpose": "The whole rep screen wiring queue, softphone, outcome panel and transcript together.",
       "operations": [],
       "tiers": []
+    },
+    {
+      "name": "DialerScreen",
+      "file": "components/dialer-screen.tsx",
+      "purpose": "Finished calling page: pick a list, run a session, softphone, outcomes, transcript and history.",
+      "operations": [
+        "get_dialer_session_dialer_sessions__session_id__get",
+        "list_dialer_sessions_voice_dialer_sessions_get"
+      ],
+      "tiers": [
+        "read"
+      ]
+    },
+    {
+      "name": "CallLogScreen",
+      "file": "components/call-log-screen.tsx",
+      "purpose": "Finished call history page with outcome filter, recording, transcript and AI grade, and Call back on a call (CallContactButton, confirmed); also exports CallHistory.",
+      "operations": [
+        "list_calls_for_contact_voice_dialer_calls_get"
+      ],
+      "tiers": [
+        "read"
+      ]
+    },
+    {
+      "name": "DialerSessionDetail",
+      "file": "components/dialer-session-detail.tsx",
+      "purpose": "One dialing session as a full record: stats, details, calls and queue, with pause, confirmed resume and confirmed stop.",
+      "operations": [
+        "get_dialer_session_dialer_sessions__session_id__get",
+        "pause_dialer_session_dialer_sessions__session_id__pause_post",
+        "read_queue_stats_dialer_sessions__session_id__queue_stats_get",
+        "resume_dialer_session_voice_dialer_sessions__session_id__resume_post",
+        "stop_dialer_session_dialer_sessions__session_id__stop_post"
+      ],
+      "tiers": [
+        "read",
+        "write",
+        "external"
+      ]
+    },
+    {
+      "name": "CallContactButton",
+      "file": "components/call-contact-button.tsx",
+      "purpose": "Call one contact from any screen (contact page, table row): pick the number, a paused or completed session and the caller ID, turn on the softphone, confirm (external), and the softphone joins the call.",
+      "operations": [
+        "get_my_team_member_team_members_me_get",
+        "list_dialer_sessions_voice_dialer_sessions_get",
+        "list_dialer_numbers_voice_dialer_numbers_get",
+        "manual_dial_dialer_parallel_calls_manual_dial_post"
+      ],
+      "tiers": [
+        "read",
+        "external"
+      ]
+    },
+    {
+      "name": "RecordCallsTab",
+      "file": "components/record-calls-tab.tsx",
+      "purpose": "One contact's call history with a confirmed Call button; an extraDetailTabs entry for ContactsScreen.",
+      "operations": [
+        "list_calls_for_contact_voice_dialer_calls_get"
+      ],
+      "tiers": [
+        "read"
+      ]
     }
   ],
   "hooks": [
@@ -222,6 +296,7 @@
     }
   ],
   "scopes": [
+    "team:read",
     "voice:read",
     "voice:run",
     "voice:write"
@@ -251,10 +326,16 @@
       "decision": "Browser audio vendor for the Softphone",
       "default": "Twilio via lib/twilio-transport.ts; graph8's dialer runs on Twilio conferences. For another vendor write a SoftphoneTransport and delete twilio-transport.ts",
       "askHuman": true
+    },
+    {
+      "decision": "How a single contact is called outside a dialing session",
+      "default": "manual-dial under a PAUSED or COMPLETED session the rep picks (same call log and analytics), only once the softphone is ready; the rep is the personal key's user unless userId is passed",
+      "askHuman": false
     }
   ],
   "peerDependencies": {
     "react": ">=18",
-    "@twilio/voice-sdk": "^2.18.5"
+    "@twilio/voice-sdk": "^2.18.5",
+    "lucide-react": ">=0.400.0"
   }
 }