@graph8/sdk 0.362.0 → 0.373.0

package/blocks/pages/components/page-tracking.tsx

@@ -0,0 +1,137 @@
+"use client";
+
+/**
+ * PageTracking: how one landing page is measured. Whether visits are recorded on the workspace stream, on a stream of
+ * its own or not at all, which form it reports, whether the chat widget shows, and what counts as a conversion.
+ * Changes apply the next time the page is published.
+ *
+ * SDK operations, in the order the screen uses them:
+ *   1. getLandingPageTracking          GET    /landing-pages/{id}/tracking            (read)
+ *   2. updateLandingPageTracking       PATCH  /landing-pages/{id}/tracking            (write; ONLY the fields you changed are sent)
+ *   3. provisionLandingPageTracking    POST   /landing-pages/{id}/tracking/provision  (write; gives the page its own stream)
+ *   4. clearLandingPageConsentOverride DELETE /landing-pages/{id}/tracking/consent    (destructive, confirmed: drops the page's own consent banner settings)
+ *
+ * The form is seeded from the loaded record only, and Save stays disabled until that record has arrived, so a blank
+ * form can never be written over real settings. "Dedicated" is reached through Provision (the API refuses a direct switch).
+ */
+import { useState } from "react";
+import { Button, Input, Label, Skeleton, Switch } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
+import { useConfirmAction } from "@/g8/components/confirmed-action";
+import { KeyValueList } from "@/g8/components/screen/key-value-list";
+import { SectionCard } from "@/g8/components/screen/section-card";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { g8Delete, g8Get, g8Patch, g8Post } from "@/g8/lib/g8-client";
+import { asRec, shortDate, text } from "../lib/studio";
+import type { Rec } from "../lib/studio";
+
+export interface PageTrackingProps {
+  pageId: string;
+  onChanged?: () => void;
+  className?: string;
+}
+
+const SELECT = "border-input bg-background h-9 rounded-md border px-2 text-sm";
+const MODES = [
+  { value: "org_default", label: "Workspace stream (default)" },
+  { value: "disabled", label: "Off (no visits recorded)" },
+];
+const GOALS = [
+  { value: "", label: "Not set" },
+  { value: "form_submission", label: "A form is submitted" },
+  { value: "workspace_signup", label: "Someone signs up" },
+  { value: "paid_account", label: "Someone pays" },
+  { value: "traffic_only", label: "Traffic only" },
+];
+
+/** The fields that differ from the saved record: the body of the PATCH. Empty means nothing to save. */
+export function trackingChanges(saved: Rec, draft: { mode: string; form_id: string; chat_enabled: boolean; conversion_goal: string }): Rec {
+  const out: Rec = {};
+  if (draft.mode !== text(saved.mode, "org_default") && draft.mode !== "dedicated") out.mode = draft.mode;
+  if (draft.form_id.trim() !== text(saved.form_id)) out.form_id = draft.form_id.trim();
+  if (draft.chat_enabled !== (saved.chat_enabled !== false)) out.chat_enabled = draft.chat_enabled;
+  if (draft.conversion_goal && draft.conversion_goal !== text(saved.conversion_goal)) out.conversion_goal = draft.conversion_goal;
+  return out;
+}
+
+function TrackingForm({ pageId, saved, onSaved }: { pageId: string; saved: Rec; onSaved: () => void }) {
+  const base = `/landing-pages/${encodeURIComponent(pageId)}/tracking`;
+  const { ask, dialog, failure } = useConfirmAction();
+  // Only what the person changed is held as `edits`, shown over the saved copy, so a reload never wipes typing.
+  const base0 = { mode: text(saved.mode, "org_default"), form_id: text(saved.form_id), chat_enabled: saved.chat_enabled !== false, conversion_goal: text(saved.conversion_goal) };
+  const [edits, setEdits] = useState<Partial<typeof base0>>({});
+  const draft = { ...base0, ...edits };
+  const setDraft = (next: typeof base0): void => setEdits(Object.fromEntries(Object.entries(next).filter(([k, v]) => v !== base0[k as keyof typeof base0])) as Partial<typeof base0>);
+  const changes = trackingChanges(saved, draft);
+  const dirty = Object.keys(changes).length > 0;
+  const save = useG8Mutation(() => g8Patch(base, changes), { onSuccess: () => { setEdits({}); onSaved(); } });
+  const provision = useG8Mutation(() => g8Post(`${base}/provision`), { onSuccess: onSaved });
+  const dedicated = saved.mode === "dedicated";
+  return (
+    <div className="grid gap-4">
+      <form className="grid gap-3 sm:grid-cols-2" onSubmit={(e) => { e.preventDefault(); if (dirty) void save.mutate(undefined); }}>
+        <div>
+          <Label htmlFor="pt-mode" className="mb-1">Measure visits</Label>
+          {dedicated ? <p className="text-sm">On a stream of its own</p> : (
+            <select id="pt-mode" className={`${SELECT} w-full`} value={draft.mode} onChange={(e) => setDraft({ ...draft, mode: e.target.value })}>
+              {MODES.map((m) => <option key={m.value} value={m.value}>{m.label}</option>)}
+            </select>
+          )}
+        </div>
+        <div>
+          <Label htmlFor="pt-goal" className="mb-1">A conversion is</Label>
+          <select id="pt-goal" className={`${SELECT} w-full`} value={draft.conversion_goal} onChange={(e) => setDraft({ ...draft, conversion_goal: e.target.value })}>
+            {GOALS.map((g) => <option key={g.value} value={g.value} disabled={g.value === "" && Boolean(saved.conversion_goal)}>{g.label}</option>)}
+          </select>
+        </div>
+        <div>
+          <Label htmlFor="pt-form" className="mb-1">Form label</Label>
+          <Input id="pt-form" value={draft.form_id} placeholder="demo-request" onChange={(e) => setDraft({ ...draft, form_id: e.target.value })} />
+        </div>
+        <div className="flex items-end gap-2">
+          <Switch id="pt-chat" checked={draft.chat_enabled} onCheckedChange={(v) => setDraft({ ...draft, chat_enabled: v })} aria-label="Show the chat widget" />
+          <Label htmlFor="pt-chat">Show the chat widget on this page</Label>
+        </div>
+        <div className="flex gap-2 sm:col-span-2">
+          <Button type="submit" loading={save.loading} disabled={!dirty}>Save tracking</Button>
+          {!dedicated ? <Button type="button" variant="outline" loading={provision.loading} onClick={() => void provision.mutate(undefined)}>Give this page its own stream</Button> : null}
+        </div>
+      </form>
+      {save.error ? <ApiError error={save.error} title="Could not save tracking" /> : null}
+      {save.data && !dirty ? <p role="status" className="text-sm">Tracking saved. It applies the next time the page is published.</p> : null}
+      {provision.error ? <ApiError error={provision.error} title="Could not set up the stream" /> : null}
+      <KeyValueList columns={2} items={[
+        { label: "Stream", value: text(saved.stream_name) || "Workspace stream" },
+        { label: "Provisioned", value: shortDate(saved.provisioned_at) },
+        { label: "Page has a form", value: saved.has_forms === true ? "Yes" : saved.has_forms === false ? "No" : "" },
+        { label: "Page has a sign-up", value: saved.has_graph8_signup === true ? "Yes" : saved.has_graph8_signup === false ? "No" : "" },
+      ]} />
+      <div>
+        <Button size="sm" variant="ghost" onClick={() => ask({
+          tier: "destructive",
+          title: "Use the workspace consent banner on this page",
+          confirmLabel: "Use workspace setting",
+          description: "Drops this page's own consent banner settings. The page follows the workspace default the next time it is published.",
+          run: () => g8Delete(`${base}/consent`),
+          onDone: onSaved,
+        })}>Reset consent to the workspace default</Button>
+      </div>
+      {failure ? <ApiError error={failure} title="That did not work" /> : null}
+      <ConfirmSpendDialog {...dialog} />
+    </div>
+  );
+}
+
+export function PageTracking({ pageId, onChanged, className }: PageTrackingProps) {
+  const res = useG8Query((signal) => g8Get(`/landing-pages/${encodeURIComponent(pageId)}/tracking`, undefined, { signal }), [pageId]);
+  const saved = asRec(res.data?.data);
+  return (
+    <SectionCard className={className} title="Tracking" description="Applies the next time the page is published.">
+      {res.error ? <ApiError error={res.error} title="Could not load tracking" onRetry={() => void res.refetch()} /> : !res.data ? <Skeleton className="h-32 w-full" aria-busy="true" /> : (
+        <TrackingForm key={pageId} pageId={pageId} saved={saved} onSaved={() => { void res.refetch(); onChanged?.(); }} />
+      )}
+    </SectionCard>
+  );
+}

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

@@ -5,7 +5,9 @@
  *
  * Composes: ScreenLayout (title, tabs, stats), SplitView + DetailPanel (landing page list and the selected
  * page's editor, deep link `?id=`), PageList (list, filter, blank or AI create, publish, unpublish, delete),
- * PageEditor (details, sections, preview, versions, publish), ContentLibrary, BrandKitEditor, SeoReport.
+ * PageEditor (details, sections, preview, versions, publish), PageDomains (live URLs, publish to a domain, download),
+ * PageTracking, PageAiTools (edit, review, search metadata), PageAnalytics (portfolio tab and per page), PageClone,
+ * ContentLibrary, BrandKitEditor, SeoReport.
  *
  * Every record is deep-linkable: `?id=` opens a landing page (Edit and Details tabs) or, on the Content tab
  * (`?tab=content`), a content item with all of its fields and actions; the Brand kit tab is the one brand record.
@@ -16,30 +18,43 @@
  * (confirmed); manage the content inventory (add by URL, edit, SEO enrichment, delete); re-scan the brand kit and
  * choose page layouts; run an SEO audit and track keywords. The editor changes text fields of sections-mode pages;
  * freeform HTML pages can be previewed, published and versioned, and their HTML is edited in the graph8 app.
+ * Every page also has Publishing (its URLs, publish to a connected domain, remove a URL, download the HTML), Tracking,
+ * AI tools (edit by instruction, review and apply fixes, write search metadata: each AI pass is a confirmed spend) and
+ * Analytics tabs; "Clone a page" rebuilds a URL or pasted HTML as a draft (confirmed spend); the Analytics tab shows
+ * visits, people and companies across all pages.
  *
- * SDK operations: listLandingPages (for the headline numbers only); everything else lives in the composed parts,
- * which confirm every publish, unpublish, delete, AI generation and paid audit.
+ * SDK operations: listLandingPages (the headline numbers read the API's totals, so they stay right past one page),
+ * getLandingPage (the title of a page that is not in the loaded list); everything else lives in the composed parts,
+ * which confirm every publish, unpublish, delete, URL removal, AI pass and paid audit.
  */
 
-import { useState } from "react";
+import { useRef, useState } from "react";
 import type { ReactNode } from "react";
 import { Globe } from "lucide-react";
 import { Skeleton } from "@graph8/sdk/ui";
 import { ApiError } from "@/g8/components/api-error";
+import { FirstNotice } from "@/g8/components/paging-notices";
 import { DetailPanel } from "@/g8/components/screen/detail-panel";
 import { KeyValueList } from "@/g8/components/screen/key-value-list";
 import { ScreenLayout } from "@/g8/components/screen/screen-layout";
 import { SplitView } from "@/g8/components/screen/split-view";
 import { useUrlState } from "@/g8/hooks/use-url-state";
 import { g8Get } from "@/g8/lib/g8-client";
+import { useAllPages } from "@/g8/hooks/use-all-pages";
 import { useG8Query } from "@/g8/hooks/use-g8-query";
 import { StatusPill } from "@/g8/components/screen/status-pill";
 import { asRec, num, rowsOf, shortDate, text } from "../lib/studio";
 import type { LandingPageRow } from "../lib/studio";
 import { BrandKitEditor } from "./brand-kit-editor";
 import { ContentLibrary } from "./content-library";
+import { PageAiTools } from "./page-ai-tools";
+import { PageAnalytics } from "./page-analytics";
+import { PageClone } from "./page-clone";
+import { PageDomains } from "./page-domains";
 import { PageEditor } from "./page-editor";
+import { PageGenerationStatus } from "./page-generation-status";
 import { PageList } from "./page-list";
+import { PageTracking } from "./page-tracking";
 import { SeoReport } from "./seo-report";
 
 export interface PagesScreenProps {
@@ -51,10 +66,10 @@ export interface PagesScreenProps {
   className?: string;
 }
 
-type Tab = "pages" | "content" | "brand" | "seo";
+type Tab = "pages" | "content" | "brand" | "seo" | "analytics";
 
 /** Every field of one landing page (name and slug are edited in the Edit tab). */
-function PageDetails({ pageId }: { pageId: string }) {
+function PageDetails({ pageId, onGenerated }: { pageId: string; onGenerated?: () => void }) {
   const res = useG8Query((signal) => g8Get(`/landing-pages/${encodeURIComponent(pageId)}`, undefined, { signal }), [pageId]);
   if (res.error) return <ApiError error={res.error} title="Could not load the page" onRetry={() => void res.refetch()} />;
   if (!res.data) return <Skeleton className="h-32 w-full" aria-busy="true" />;
@@ -62,6 +77,8 @@ function PageDetails({ pageId }: { pageId: string }) {
   const n = (k: string): string => (d[k] == null || d[k] === "" ? "Not set" : text(d[k]));
   const sections = Array.isArray(d.sections) ? d.sections.length : null;
   return (
+    <div className="grid gap-3">
+    <PageGenerationStatus pageId={pageId} status={text(d.status)} onDone={onGenerated} />
     <KeyValueList
       columns={2}
       items={[
@@ -78,23 +95,40 @@ function PageDetails({ pageId }: { pageId: string }) {
         ...(d.error_message ? [{ label: "Last error", value: text(d.error_message) }] : []),
       ]}
     />
+    </div>
   );
 }
 
+/** Landing pages per read for the counts; the list itself pages through PageList. */
+const LANDING_PAGE_SIZE = 100;
+
 export function PagesScreen({ defaultDomain, renderDetailActions, extraDetailTabs, toolbarActions, className }: PagesScreenProps) {
   const [tabParam, setTabParam] = useUrlState("tab", "pages");
-  const tab = (["pages", "content", "brand", "seo"].includes(tabParam) ? tabParam : "pages") as Tab;
+  const tab = (["pages", "content", "brand", "seo", "analytics"].includes(tabParam) ? tabParam : "pages") as Tab;
   const [pageId, setPageId] = useUrlState("id", "");
   const [view, setView] = useUrlState("view", "");
   const expandProps = { onExpand: () => setView("full"), onCollapse: view === "full" ? () => setView(null) : undefined };
   // The list owns its own fetch; bumping this remounts it after the editor changed something (publish, rename).
   const [rev, setRev] = useState(0);
-  const pages = useG8Query((signal) => g8Get("/landing-pages", { limit: 100 }, { signal }), [rev]);
-  const data = asRec(pages.data?.data);
-  const rows = rowsOf<LandingPageRow>(data, "landing_pages");
-  const total = num(data.total) ?? rows.length;
+  // The stat strip and the open page's name read EVERY landing page (100 per read, offset paged), so the counts are
+  // never those of a capped first read. `total` is the API's own count.
+  const apiTotal = useRef<number | undefined>(undefined);
+  const pages = useAllPages<LandingPageRow>(async (page, signal) => {
+    const offset = (page - 1) * LANDING_PAGE_SIZE;
+    const data = asRec((await g8Get("/landing-pages", { limit: LANDING_PAGE_SIZE, offset: offset || undefined }, { signal })).data);
+    const rows = rowsOf<LandingPageRow>(data, "landing_pages");
+    apiTotal.current = num(data.total) ?? apiTotal.current;
+    return { rows, hasNext: apiTotal.current != null ? offset + rows.length < apiTotal.current : rows.length >= LANDING_PAGE_SIZE };
+  }, [rev]);
+  const rows = pages.items;
+  const total = apiTotal.current ?? rows.length;
   const published = rows.filter((p) => p.status === "published").length;
   const current = tab === "pages" ? rows.find((p) => p.id === pageId) : undefined;
+  const bump = (): void => setRev((r) => r + 1);
+  // Pages whose generation "finished" per /status: held HERE, above the child that remounts on every rev, so a page the list still
+  // calls generating (a dead worker) refreshes the list once instead of looping.
+  const generatedOnce = useRef<Set<string>>(new Set());
+  const onGenerated = (id: string): void => { if (generatedOnce.current.has(id)) return; generatedOnce.current.add(id); bump(); };
 
   const detail = tab === "pages" && pageId ? (
     <DetailPanel
@@ -106,7 +140,11 @@ export function PagesScreen({ defaultDomain, renderDetailActions, extraDetailTab
       {...expandProps}
       tabs={[
         { id: "edit", label: "Edit", content: <PageEditor key={pageId} pageId={pageId} onSaved={() => setRev((r) => r + 1)} /> },
-        { id: "details", label: "Details", content: <PageDetails key={`${pageId}:${rev}`} pageId={pageId} /> },
+        { id: "details", label: "Details", content: <PageDetails key={`${pageId}:${rev}`} pageId={pageId} onGenerated={() => onGenerated(pageId)} /> },
+        { id: "publishing", label: "Publishing", content: <PageDomains key={pageId} pageId={pageId} onChanged={bump} /> },
+        { id: "tracking", label: "Tracking", content: <PageTracking key={pageId} pageId={pageId} onChanged={bump} /> },
+        { id: "ai", label: "AI tools", content: <PageAiTools key={pageId} pageId={pageId} onChanged={bump} /> },
+        { id: "analytics", label: "Analytics", content: <PageAnalytics key={pageId} pageId={pageId} /> },
         ...(extraDetailTabs ?? []).map((t) => ({ id: t.id, label: t.label, content: t.render(pageId) })),
       ]}
     />
@@ -118,9 +156,10 @@ export function PagesScreen({ defaultDomain, renderDetailActions, extraDetailTab
       title="Pages"
       description="Landing pages, your content library, the brand kit and SEO in one place."
       icon={<Globe className="size-5" />}
-      actions={toolbarActions}
+      actions={<>{tab === "pages" ? <PageClone onCreated={(id) => { bump(); setPageId(id); }} /> : null}{toolbarActions}</>}
       tabs={[
         { id: "pages", label: "Landing pages", count: total },
+        { id: "analytics", label: "Analytics" },
         { id: "content", label: "Content" },
         { id: "brand", label: "Brand kit" },
         { id: "seo", label: "SEO" },
@@ -130,12 +169,13 @@ export function PagesScreen({ defaultDomain, renderDetailActions, extraDetailTab
       stats={tab === "pages" ? [
         { label: "Landing pages", value: total.toLocaleString() },
         { label: "Published", value: published.toLocaleString(), tone: "positive" },
-        { label: "Drafts", value: Math.max(0, rows.length - published).toLocaleString() },
+        { label: "Drafts", value: Math.max(0, total - published).toLocaleString() },
       ] : undefined}
     >
       {tab === "pages" ? (
         <>
-          {pages.error ? <ApiError error={pages.error} title="Could not load landing pages" onRetry={() => void pages.refetch()} /> : null}
+          <FirstNotice shown={rows.length} limit={rows.length} force={pages.truncated} noun="landing pages" />
+          {pages.error ? <ApiError error={pages.error} title="Could not load landing pages" onRetry={pages.refetch} /> : null}
           <SplitView
             detailOpen={Boolean(pageId)}
             onCloseDetail={() => { setPageId(null); setView(null); }}
@@ -146,7 +186,8 @@ export function PagesScreen({ defaultDomain, renderDetailActions, extraDetailTab
             detail={detail}
           />
         </>
-      ) : tab === "content" ? <ContentLibrary selectedId={pageId || null} onSelectedChange={(id) => setPageId(id)} />
+      ) : tab === "analytics" ? <PageAnalytics />
+        : tab === "content" ? <ContentLibrary selectedId={pageId || null} onSelectedChange={(id) => setPageId(id)} />
         : tab === "brand" ? <BrandKitEditor />
         : <SeoReport defaultDomain={defaultDomain} />}
     </ScreenLayout>

package/blocks/pages/components/seo-report.tsx

@@ -26,6 +26,7 @@ import { useG8Query } from "@/g8/hooks/use-g8-query";
 import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
 import { useJobPoll } from "@/g8/hooks/use-job-poll";
 import { ApiError } from "@/g8/components/api-error";
+import { FirstNotice } from "@/g8/components/paging-notices";
 import { EmptyState } from "@/g8/components/empty-state";
 import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
 import { asRec, num, rowsOf, shortDate, text } from "../lib/studio";
@@ -110,12 +111,15 @@ function Keywords({ domain }: { domain: string }) {
   );
 }
 
+/** The audits API has no paging: a full read is announced under the audit chips. */
+const AUDIT_LIMIT = 10;
+
 export function SeoReport({ defaultDomain = "", className }: SeoReportProps) {
   const [domain, setDomain] = useState(defaultDomain);
   const [maxPages, setMaxPages] = useState(100);
   const [confirm, setConfirm] = useState(false);
   const [selected, setSelected] = useState<string | null>(null);
-  const audits = useG8Query((signal) => g8Get("/seo/audits", { limit: 10 }, { signal }), []);
+  const audits = useG8Query((signal) => g8Get("/seo/audits", { limit: AUDIT_LIMIT }, { signal }), []);
   const start = useG8Mutation(() => g8Post("/seo/audits", { domain: domain.trim(), max_pages: maxPages }), {
     onSuccess: (res) => {
       setConfirm(false);
@@ -143,6 +147,7 @@ export function SeoReport({ defaultDomain = "", className }: SeoReportProps) {
               {text(a.domain)} · {shortDate(a.created_at)}
             </Button>
           ))}
+          <FirstNotice className="w-full" shown={rows.length} limit={AUDIT_LIMIT} noun="audits" />
         </div>
       ) : null}
       <div className="space-y-4">

package/blocks/pages/lib/studio.ts

@@ -8,6 +8,8 @@
  * Nothing here knows more than that, so a field the API adds later never breaks a screen.
  */
 
+import type { PaginatedResponse } from "@graph8/sdk";
+
 export type Rec = Record<string, unknown>;
 
 export function asRec(value: unknown): Rec {
@@ -75,3 +77,8 @@ export function liveUrl(data: unknown): string {
   const rec = asRec(data);
   return text(rec.published_url) || text(rec.url) || text(asRec(rec.landing_page).published_url);
 }
+
+/** Wrap rows and the API's "next" marker (a cursor or an offset; null or absent when there is no more) for `usePaginated`. */
+export function pageOf<T>(rows: T[], next: unknown): PaginatedResponse<T> {
+  return { data: rows, pagination: { next_cursor: next == null || next === "" ? null : String(next) } } as unknown as PaginatedResponse<T>;
+}

package/blocks/phone-numbers/README.md

@@ -0,0 +1,74 @@
+# phone-numbers: buy, assign, configure and release numbers
+
+Every phone number the workspace owns, in one finished screen: see them all, search a carrier for new ones, buy one,
+give it to a teammate or a voice agent, change how it answers, watch its usage against the daily limit, register for text
+messaging (A2P 10DLC), and release it. Install with `npx @graph8/sdk add phone-numbers` (depends on `pickers`, for the
+assignee picker). The dialer, sequencer and voice agents all pick numbers from this inventory.
+
+> Buying a number spends credits and real money, releasing one is irreversible, and submitting a text registration
+> reaches the carriers. Each of those opens a confirm dialog first; nothing here buys, releases or submits by itself.
+
+## Screens
+
+- `PhoneNumbersScreen` (`components/phone-numbers-screen.tsx`): no required props.
+  - **Numbers** tab: stat strip (numbers, assigned, unassigned, calls today), search, filters (use, carrier, assignment,
+    status, kept in the URL as `n_use=...`), and the list. The list is paged on the client with **Load more** ("Showing 25
+    of 140 numbers"): the two list endpoints return the whole inventory and take no `limit`, so nothing is silently cut off.
+    A row opens the number beside the list (`?id=%2B14155550123`, add `&view=full` for a full page, `&dtab=usage` for a tab).
+  - **Buy a number** (sheet): choose a carrier, number type, area code, and digits or a city; search is free. Choose a number,
+    say what it is for (dialer, voice AI, personal work phone) and who gets it, then **Buy for about 250 credits** opens the
+    confirm dialog with the price. A 402 says nothing was bought and nothing was charged.
+  - **Add a number you own** (sheet): register a number you already hold with the voice platform. It buys nothing.
+  - **Text registration** tab: the A2P 10DLC status (brand, campaign, carrier feedback), a form that saves a draft, a
+    confirmed **Submit registration**, and **Retry stuck numbers**.
+  - The open number has tabs: **Overview**, **Assign** (MemberPicker, Assign to me, Unassign, Re-sync voice record),
+    **Usage** (calls today against the daily limit, 7-day calls, connect rate, confirmed counter reset), **Settings**
+    (answering mode, Telnyx caller-ID verification, who answers) and **Release** (release, or remove voice routing only).
+  - Slots: `toolbarActions`, `renderRowActions`, `renderDetailActions`, `extraDetailTabs`.
+- Parts you can compose yourself: `PhoneNumberList`, `PhoneNumberDetail`, `NumberSearch`, `AssignNumber`, `NumberSettings`,
+  `NumberUsage`, `ReleaseNumber`, `RegisterOwnedNumber`, `A2pRegistration`, and the `usePhoneNumbers` hook.
+
+## What the API gives, and what it does not
+
+- **There is no "list my phone numbers" operation in the `phoneNumbers` namespace.** The inventory is two reads, merged:
+  `GET /voice/dialer/numbers` (every number except the ones a voice AI agent holds, with usage) and
+  `GET /voice/agent-phone-numbers` (AI-capable numbers and which agent holds each). `usePhoneNumbers` does the merge.
+- **No price read.** Prices on the purchase dialog are estimates: 250 credits held on purchase, then about 250 credits a
+  month in rental. The API reports no rental per number, so the block never labels any number "billable". Numbers the
+  platform provisioned for you (the onboarding receptionist line) are never rental-billed.
+- **No operations for call forwarding, voicemail greetings or ring-group routing.** Settings says so and links to the
+  platform app instead of showing a dead control. Porting a number in is also an app flow.
+- **Admin-only writes.** Reassigning, switching the answering mode and resetting counters are admin-only through the API; a
+  403 is explained on the screen.
+- **Telnyx numbers must be verified as a caller ID** before they can place calls; an unverified one shows as "Cannot dial"
+  and stays out of the dialer rotation. Twilio numbers need nothing.
+
+## Operations
+
+| Flow | Operation | Tier |
+|---|---|---|
+| Inventory | `listDialerNumbers`, `listAgentPhoneNumbers` | read |
+| Search | `searchAvailablePhoneNumbers` | read (free) |
+| Buy | `purchasePhoneNumber` (Idempotency-Key) | **billable**, confirmed |
+| Assign | `updatePhoneAssignee` (CRM + voice), `updateVoiceAssignee` (voice only; `""` clears the voice assignment, the API cannot clear the CRM owner) | write |
+| Answering mode | `updatePhoneCapabilities` (voice AI, dialer), `updateVoiceInboundType` (rep, work phone) | write |
+| Caller ID, who answers | `verifyVoiceCallerId`, `getVoiceAnsweringAgent` | write, read |
+| Register an owned number | `provisionVoiceNumber` | write (buys nothing) |
+| Release | `releasePhoneNumber` | **destructive**, type the number, then confirmed |
+| Remove voice routing | `deleteVoiceNumber` (keeps the number and its carrier bill) | **destructive**, confirmed |
+| Reset counters | `resetVoiceDailyCounts` (every number, lifts the daily cap) | **destructive**, confirmed |
+| Text registration | `getPhoneA2pStatus`, `saveA2pInputs`, `startA2pRegistration`, `reconcileA2pRegistration` | read, write, **external** (submit is confirmed), write |
+
+Scopes: `voice:read`, `voice:write`, `voice:run` (buy, submit A2P), `voice:delete` (release, remove routing, reset
+counters) and `team:read` (the assignee picker).
+
+## Defaults (no need to ask the human)
+
+- Carrier: Twilio (Telnyx is one select away). A new number is an **outbound dialer** number, owned by the identity behind the key unless an assignee is chosen.
+- A number's use maps to the API as: dialer = `dialer: true`; voice AI = `dialer: false`; personal work phone = `dialer: true, work: true`.
+- Answering mode: "Voice AI agent" and "Outbound dialer" go through `update-capabilities`; "Rep answers" and "Personal work phone" go through `inbound-type`. Both rebuild the number's routing, so the change takes a second click on a button that says the number answers nothing for a moment.
+- Releasing needs the number typed first and then a confirm. If the carrier is unknown (a number only the agents list knows), the person chooses it: the wrong carrier releases nothing.
+- Saving A2P details sends the whole object, merged over what was saved, so a field the form does not edit (an address) is never wiped. The form appears only after the saved details loaded.
+
+Recipes (`recipes/`): search and buy (human approval required), assign or clear a rep, audit the inventory (read-only), and
+save A2P details and check registration.