@graph8/sdk 0.308.1 → 0.357.0

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

@@ -0,0 +1,159 @@
+"use client";
+
+/**
+ * SeoReport: site audits (score and issues) and rank tracking for a domain.
+ *
+ * Starting an audit RESERVES credits sized by the page limit and runs in the background, so the screen polls the
+ * audit until its state is terminal. Reading audits, issues and rankings is free.
+ *
+ * SDK operations, in the order the screen uses them:
+ *   1. listSeoAudits            GET  /seo/audits                       (read)
+ *   2. startSeoAudit            POST /seo/audits {domain, max_pages}   (billable; reserves credits by max_pages)
+ *   3. getSeoAudit              GET  /seo/audits/{id}                  (read; polled until state.is_terminal)
+ *   4. getSeoAuditIssues        GET  /seo/audits/{id}/issues           (read)
+ *   5. listSeoTrackedKeywords   GET  /seo/rank-tracking?domain         (read)
+ *   6. saveSeoTrackedKeywords   POST /seo/rank-tracking/keywords       (write)
+ *   7. removeSeoTrackedKeywords POST /seo/rank-tracking/keywords/remove (write)
+ *
+ * Starting an audit goes through ConfirmSpendDialog. The API has no credit-balance read, so the dialog explains
+ * the reservation instead of quoting a number.
+ */
+
+import { useState } from "react";
+import { Button, Card, CardContent, CardHeader, CardTitle, Input, Skeleton, Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "@graph8/sdk/ui";
+import { g8Get, g8Post } from "@/g8/lib/g8-client";
+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 { EmptyState } from "@/g8/components/empty-state";
+import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
+import { asRec, num, rowsOf, shortDate, text } from "../lib/studio";
+import type { Rec } from "../lib/studio";
+
+export interface SeoReportProps {
+  /** Pre-fill the domain, for example the customer's own site. */
+  defaultDomain?: string;
+  className?: string;
+}
+
+const SEVERITY_ORDER = ["critical", "high", "warning", "medium", "low", "info"];
+const rank = (s: string) => (SEVERITY_ORDER.indexOf(s.toLowerCase()) + 1 || 99);
+
+function AuditDetail({ auditId }: { auditId: string }) {
+  const poll = useJobPoll<Rec>(async (signal) => asRec((await g8Get(`/seo/audits/${encodeURIComponent(auditId)}`, undefined, { signal })).data), {
+    isTerminal: (a) => asRec(a.state).is_terminal === true,
+  });
+  const issues = useG8Query((signal) => g8Get(`/seo/audits/${encodeURIComponent(auditId)}/issues`, undefined, { signal }), [auditId, poll.done], { enabled: poll.done });
+  const audit = poll.status ?? {};
+  const state = asRec(audit.state);
+  const list = rowsOf<Rec>(asRec(issues.data?.data), "issues").sort((a, b) => rank(text(a.severity)) - rank(text(b.severity)));
+  return (
+    <Card>
+      <CardHeader><CardTitle className="text-sm">{text(audit.domain, "Audit")}</CardTitle></CardHeader>
+      <CardContent className="space-y-3">
+        {poll.error ? <ApiError error={poll.error} title="Could not read the audit" onRetry={poll.start} /> : null}
+        <p className="text-sm" data-testid="audit-state">{text(state.headline, poll.polling ? "Running" : "")}{state.detail ? ` ${text(state.detail)}` : ""}</p>
+        {poll.done ? (
+          <p className="text-sm">On-page score <strong>{num(audit.onpage_score) ?? "-"}</strong> across {num(audit.pages_crawled) ?? 0} pages.</p>
+        ) : <Skeleton className="h-6 w-48" />}
+        {issues.error ? <ApiError error={issues.error} onRetry={() => void issues.refetch()} /> : null}
+        {poll.done && !issues.loading && list.length === 0 && !issues.error ? <p className="text-muted-foreground text-sm">No issues found.</p> : null}
+        {list.length ? (
+          <Table>
+            <TableHeader><TableRow><TableHead>Issue</TableHead><TableHead>Severity</TableHead><TableHead className="text-right">Affected pages</TableHead></TableRow></TableHeader>
+            <TableBody>
+              {list.map((i) => (
+                <TableRow key={text(i.issue_type)}><TableCell>{text(i.issue_type).replace(/_/g, " ")}</TableCell><TableCell className="capitalize">{text(i.severity)}</TableCell><TableCell className="text-right">{num(i.affected_count) ?? 0}</TableCell></TableRow>
+              ))}
+            </TableBody>
+          </Table>
+        ) : null}
+      </CardContent>
+    </Card>
+  );
+}
+
+function Keywords({ domain }: { domain: string }) {
+  const [kw, setKw] = useState("");
+  const list = useG8Query((signal) => g8Get("/seo/rank-tracking", { domain: domain || undefined }, { signal }), [domain]);
+  const add = useG8Mutation(() => g8Post("/seo/rank-tracking/keywords", { domain, keywords: kw.split(",").map((k) => k.trim()).filter(Boolean).map((keyword) => ({ keyword })) }), { onSuccess: () => { setKw(""); void list.refetch(); } });
+  const remove = useG8Mutation((id: string) => g8Post("/seo/rank-tracking/keywords/remove", { keyword_ids: [id] }), { onSuccess: () => void list.refetch() });
+  const rows = rowsOf<Rec>(list.data?.data);
+  return (
+    <Card>
+      <CardHeader><CardTitle className="text-sm">Tracked keywords</CardTitle></CardHeader>
+      <CardContent className="space-y-3">
+        <div className="flex gap-2">
+          <Input aria-label="Keywords" placeholder="Keywords, comma separated" value={kw} onChange={(e) => setKw(e.target.value)} />
+          <Button disabled={!domain || !kw.trim()} loading={add.loading} onClick={() => void add.mutate(undefined)}>Track</Button>
+        </div>
+        {list.error ? <ApiError error={list.error} onRetry={() => void list.refetch()} /> : null}
+        {add.error ? <ApiError error={add.error} title="Could not track those keywords" /> : null}
+        {remove.error ? <ApiError error={remove.error} title="Could not stop tracking" /> : null}
+        {!list.loading && !list.error && rows.length === 0 ? <EmptyState title="No keywords tracked" description="Add keywords to see where this domain ranks." /> : null}
+        {rows.length ? (
+          <Table>
+            <TableHeader><TableRow><TableHead>Keyword</TableHead><TableHead>Rank</TableHead><TableHead>Volume</TableHead><TableHead>Checked</TableHead><TableHead /></TableRow></TableHeader>
+            <TableBody>
+              {rows.map((r) => (
+                <TableRow key={text(r.id)}>
+                  <TableCell>{text(r.keyword)}</TableCell><TableCell>{num(r.latest_rank) ?? "-"}</TableCell><TableCell>{num(r.search_volume) ?? "-"}</TableCell><TableCell>{shortDate(r.latest_checked_at)}</TableCell>
+                  <TableCell className="text-right"><Button size="sm" variant="ghost" aria-label={`Stop tracking ${text(r.keyword)}`} onClick={() => void remove.mutate(text(r.id))}>Remove</Button></TableCell>
+                </TableRow>
+              ))}
+            </TableBody>
+          </Table>
+        ) : null}
+      </CardContent>
+    </Card>
+  );
+}
+
+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 start = useG8Mutation(() => g8Post("/seo/audits", { domain: domain.trim(), max_pages: maxPages }), {
+    onSuccess: (res) => {
+      setConfirm(false);
+      setSelected(text(asRec(res.data).id) || null);
+      void audits.refetch();
+    },
+    onError: () => setConfirm(false),
+  });
+  const rows = rowsOf<Rec>(audits.data?.data);
+  return (
+    <div className={className}>
+      <div className="mb-4 flex flex-wrap items-end gap-2">
+        <Input aria-label="Domain" placeholder="example.com" value={domain} onChange={(e) => setDomain(e.target.value)} className="w-64" />
+        <Input aria-label="Max pages" type="number" min={1} value={maxPages} onChange={(e) => setMaxPages(Math.max(1, Number(e.target.value) || 1))} className="w-28" />
+        <Button disabled={!domain.trim()} onClick={() => setConfirm(true)}>Run audit</Button>
+      </div>
+      {start.error ? <ApiError error={start.error} title="Could not start the audit" /> : null}
+      {audits.error ? <ApiError error={audits.error} onRetry={() => void audits.refetch()} /> : null}
+      {audits.loading && !audits.data ? <Skeleton className="mb-4 h-16 w-full" /> : null}
+      {!audits.loading && !audits.error && rows.length === 0 ? <EmptyState title="No audits yet" description="Run an audit to see your on-page score and what to fix first." /> : null}
+      {rows.length ? (
+        <div className="mb-4 flex flex-wrap gap-2">
+          {rows.map((a) => (
+            <Button key={text(a.id)} size="sm" variant={selected === text(a.id) ? "default" : "outline"} onClick={() => setSelected(text(a.id))}>
+              {text(a.domain)} · {shortDate(a.created_at)}
+            </Button>
+          ))}
+        </div>
+      ) : null}
+      <div className="space-y-4">
+        {selected ? <AuditDetail key={selected} auditId={selected} /> : null}
+        <Keywords domain={domain.trim()} />
+      </div>
+      {confirm ? (
+        <ConfirmSpendDialog open tier="billable" title={`Audit ${domain.trim()} (up to ${maxPages} pages)`}
+          description="Credits are reserved up front, sized by the page limit, and the unused part is released when the crawl completes."
+          confirmLabel="Run audit" confirming={start.loading} onConfirm={() => void start.mutate(undefined)} onCancel={() => setConfirm(false)} />
+      ) : null}
+    </div>
+  );
+}

package/blocks/pages/lib/studio.ts

@@ -0,0 +1,77 @@
+"use client";
+
+/**
+ * Small helpers for the Studio payloads the pages block reads.
+ *
+ * Studio responses are open-shaped: a list comes back as `{ items, <named key>, total }` (the original key,
+ * for example `landing_pages`, is kept AND mirrored onto `items`), a single record as a plain object.
+ * Nothing here knows more than that, so a field the API adds later never breaks a screen.
+ */
+
+export type Rec = Record<string, unknown>;
+
+export function asRec(value: unknown): Rec {
+  return value && typeof value === "object" && !Array.isArray(value) ? (value as Rec) : {};
+}
+
+/** The rows of a list payload: a bare array, or the first of `keys` (then `items`) that holds one. */
+export function rowsOf<T = Rec>(data: unknown, ...keys: string[]): T[] {
+  if (Array.isArray(data)) return data as T[];
+  const rec = asRec(data);
+  for (const key of [...keys, "items"]) {
+    if (Array.isArray(rec[key])) return rec[key] as T[];
+  }
+  return [];
+}
+
+export function text(value: unknown, fallback = ""): string {
+  return typeof value === "string" ? value : value == null ? fallback : String(value);
+}
+
+export function num(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+
+export function shortDate(value: unknown): string {
+  const raw = text(value);
+  if (!raw) return "";
+  const date = new Date(raw);
+  return Number.isNaN(date.getTime()) ? raw : date.toLocaleDateString(undefined, { year: "numeric", month: "short", day: "numeric" });
+}
+
+export interface LandingPageRow {
+  id: string;
+  name: string;
+  slug?: string | null;
+  status: string;
+  generation_mode?: string | null;
+  published_url?: string | null;
+  published_at?: string | null;
+  section_count?: number;
+  updated_at?: string | null;
+}
+
+export interface LandingSection {
+  type?: string;
+  content?: Rec;
+  [key: string]: unknown;
+}
+
+export interface ContentPageRow {
+  id: string;
+  url: string;
+  domain?: string;
+  title?: string | null;
+  content_type?: string | null;
+  content_status?: string | null;
+  primary_keyword?: string | null;
+  seo_score?: number | null;
+  word_count?: number | null;
+  is_owned?: boolean;
+}
+
+/** Where a publish/unpublish response keeps the live URL (the API names it differently per route). */
+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);
+}

package/blocks/pages/recipes/audit-site-seo.ts

@@ -0,0 +1,28 @@
+/**
+ * @title Run an SEO site audit and list what to fix first
+ * @when The customer wants an on-page score for a domain. Starting an audit RESERVES credits sized by `max_pages`
+ * (billable tier), so confirm the page limit with the person. The crawl is asynchronous: poll until the audit state
+ * is terminal, then read the issues.
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
+
+export async function auditSite(domain: string, maxPages = 100): Promise<Array<{ issue: string; severity: string; pages: number }>> {
+  const started = await g8.api.seo.startSeoAudit({ body: { domain, max_pages: maxPages } });
+  const auditId = started.data.id;
+
+  for (let attempt = 0; attempt < 60; attempt++) {
+    const audit = await g8.api.seo.getSeoAudit({ path: { audit_id: auditId } });
+    if (audit.data.state.is_terminal) {
+      if (audit.data.state.category !== "complete") throw new Error(`${audit.data.state.headline}: ${audit.data.state.detail}`);
+      break;
+    }
+    await sleep(Math.min(30_000, 2_000 * 1.5 ** attempt));
+  }
+
+  const issues = await g8.api.seo.getSeoAuditIssues({ path: { audit_id: auditId } });
+  return issues.data.issues.map((i) => ({ issue: i.issue_type, severity: i.severity, pages: i.affected_count }));
+}

package/blocks/pages/recipes/create-and-publish-page.ts

@@ -0,0 +1,26 @@
+/**
+ * @title Create a landing page, edit it, and publish it
+ * @when The customer asks for a new page. Creating with `generate: false` is free and gives an empty page; with
+ * `generate: true` (the API default) the AI writes the whole page and SPENDS credits. Publishing puts the page on a
+ * public URL (external tier): confirm with the person first, or let them click Publish in PageEditor.
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+export async function createAndPublishPage(name: string, opts: { generate: boolean; publish: boolean }): Promise<string | undefined> {
+  // 1. Create. The new page's id is in the response; every later call needs it.
+  const created = await g8.api.landingPages.createLandingPage({ body: { name, generate: opts.generate } });
+  const pageId = String((created.data as Record<string, unknown>).id);
+
+  // 2. Read it back. `sections` is an array for sections-mode pages and null for freeform pages.
+  const page = await g8.api.landingPages.getLandingPage({ path: { landing_page_id: pageId } });
+  const sections = (page.data as Record<string, unknown>).sections;
+  console.log(`page ${pageId} has ${Array.isArray(sections) ? sections.length : 0} sections`);
+
+  if (!opts.publish) return undefined;
+
+  // 3. Publish. Only after the person agreed: the page is public as soon as this returns.
+  const live = await g8.api.landingPages.publishLandingPage({ path: { landing_page_id: pageId } });
+  return String((live.data as Record<string, unknown>).published_url ?? "");
+}

package/blocks/pages/recipes/edit-page-section.ts

@@ -0,0 +1,25 @@
+/**
+ * @title Change the text of one section of a landing page
+ * @when A person (or the agent) wants a headline or button label changed without re-running AI. The section
+ * content is REPLACED, so read the section first and send back the whole object with your change merged in.
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+export async function editSectionText(pageId: string, sectionIdx: number, field: string, value: string): Promise<void> {
+  const page = await g8.api.landingPages.getLandingPage({ path: { landing_page_id: pageId } });
+  const sections = (page.data as { sections?: Array<{ content?: Record<string, unknown> }> | null }).sections;
+  if (!sections) throw new Error("Freeform page: it has no sections. Use the HTML edit routes instead.");
+  const current = sections[sectionIdx]?.content;
+  if (!current) throw new Error(`Page ${pageId} has no section ${sectionIdx}`);
+
+  await g8.api.landingPages.updateLandingPageSection({
+    path: { landing_page_id: pageId, section_idx: sectionIdx },
+    body: { content: { ...current, [field]: value } },
+  });
+
+  // Every edit is snapshotted; this is how to find the version to restore if the change was wrong.
+  const versions = await g8.api.landingPages.listLandingPageVersions({ path: { landing_page_id: pageId } });
+  console.log(JSON.stringify(versions.data).slice(0, 400));
+}

package/blocks/pages/recipes/refresh-brand-kit.ts

@@ -0,0 +1,22 @@
+/**
+ * @title Re-scan the brand kit from the customer's website
+ * @when Brand colors, fonts or logo look stale, or the customer changed their site. The scan is asynchronous: the
+ * overview reports `status: "generating"` until it finishes. Passing a different `website_url` REPLACES the stored
+ * design tokens, so only do that when the person asked to switch sites.
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
+
+export async function refreshBrandKit(websiteUrl?: string): Promise<Record<string, unknown>> {
+  await g8.api.brandKit.triggerBrandExtraction({ body: websiteUrl ? { website_url: websiteUrl } : undefined });
+
+  for (let attempt = 0; attempt < 40; attempt++) {
+    const overview = (await g8.api.brandKit.getBrandKitOverview({})).data as Record<string, unknown>;
+    if (overview.status !== "generating") return overview;
+    await sleep(Math.min(15_000, 2_000 * 1.4 ** attempt));
+  }
+  throw new Error("Brand scan still running after about 5 minutes; check again later.");
+}

package/blocks/quotes/README.md

@@ -0,0 +1,79 @@
+# quotes: quotes & e-sign
+
+Quote list, a draft builder, a quotable-product picker, a quote viewer that sends for signature, and signature status.
+Install with `npx @graph8/sdk add quotes`.
+
+| Component | What it is |
+|---|---|
+| `QuoteList` | Quotes with status filter and paging; scope with `dealId` or `companyId`. |
+| `QuoteBuilder` | Create or edit a draft: details, signer search, line items, live totals, lists what is missing. |
+| `ProductPicker` | Quotable products (Stripe + manual) and their prices; returns a ready line item. |
+| `QuoteViewer` | One quote with totals and status-based actions: send/resend, edit as draft, duplicate, delete. |
+| `SignatureStatus` | Envelope state, signers, activity, reminder. |
+
+## Flow, in order (and the ids passed between steps)
+
+1. `GET /quotable-products` -> items with `prices[]`. A line item needs `stripe_product_id` + `stripe_price_id`, or `manual_product_id`
+   copied from here. The API refuses non-quotable products. Tiered Stripe prices are not offered.
+2. `GET /quote-contacts?q&company_id&deal_id` -> contacts with `id`, `email`, `name` (a picker LABEL, may be an email) and `person_name` (the real name or null). Use `person_name` as the signer name, never `name`. Or give `signer_email`.
+3. `POST /quotes` with `deal_id` (from the **deals** block), `title`, `contract_start_date`, a signer, and `line_items` (amounts in **cents**) -> `data.id` = quote id.
+   Required fields are checked in the form before the call, so the agent does not hit a 422.
+4. `PATCH /quotes/{id}` edits a **draft** only. A sent quote is changed with `POST /quotes/{id}/edit-as-draft` (`sent` status only; voids the sent copy and returns `new_quote_id`).
+5. `POST /quotes/{id}/send` emails the signer a signing link (**external**, confirmed). Sending a `sent`/`viewed` quote resends the same link.
+6. `GET /quotes/{id}` carries `envelope` (`sent | viewed | signed | declined`), `signers`, audit events. `POST /envelopes/{envelope.id}/resend` is the reminder (**external**, confirmed).
+
+## Mounting
+
+```tsx
+<QuoteList dealId={dealId} onOpen={(id) => router.push(`/quotes/${id}`)} onNew={() => router.push(`/quotes/new?deal=${dealId}`)} />
+<QuoteBuilder dealId={dealId} onSaved={(id) => router.push(`/quotes/${id}`)} />
+<QuoteViewer quoteId={id} onEdit={(q) => router.push(`/quotes/${q}/edit`)} onOpenQuote={(q) => router.push(`/quotes/${q}`)} />
+```
+
+## Prerequisites
+
+- `foundation` installed (and `deals`, which supplies the `dealId`); proxy `allowedPrefixes` include `quotes`, `quotable-products`, `quote-contacts`, `envelopes`.
+- `where: "api"`: at least one quotable product.
+- `where: "app"`: quote settings (company legal name, terms, sender) filled in; Stripe connected for Stripe products and subscriptions.
+
+## Tiers and what is confirmed
+
+Quote writes (`createQuote`, `updateQuotePatch`, `duplicateQuote`) are tiered `external` in the contract because the same family sends quotes, but they only store a
+draft. The builder therefore saves in one click, and the confirmation sits on the steps that reach the customer or destroy data: **send / resend, edit as draft, reminder** (external)
+and **delete** (destructive). From code, never call `sendQuote` without the person's agreement.
+
+## Defaults the agent should use without asking
+
+- Net 30, USD, 25 rows per page, the first flat price of a product.
+
+## Ask the person first
+
+- **Sending or resending** any quote, and **editing a sent quote** (it voids the signing link).
+
+## Known limits
+
+- Accept, expire and revoke (`markQuoteAccepted`, `expireQuote`, `revokeQuote`), quote templates, quote settings writes and manual-product CRUD are not wired into screens.
+- The `signatures.*` operations are EMAIL signatures, unrelated to e-signature of quotes; this block uses `eSignature.*`.
+- There is no webhook for "quote signed" here; poll the envelope (see `track-quote-signature.ts`).
+
+## Operations
+
+| SDK method (`g8.api.*`) | Route | Tier | Scope |
+|---|---|---|---|
+| `listQuotes` | GET `/api/v1/quotes` | read | `quotes:read` |
+| `getQuote` | GET `/api/v1/quotes/{quote_id}` | read | `quotes:read` |
+| `searchQuoteContacts` | GET `/api/v1/quote-contacts` | read | `quotes:read` |
+| `createQuote` | POST `/api/v1/quotes` | external | `quotes:run` |
+| `updateQuotePatch` | PATCH `/api/v1/quotes/{quote_id}` | external | `quotes:run` |
+| `listQuotableProducts` | GET `/api/v1/quotable-products` | read | `quotes:read` |
+| `sendQuote` | POST `/api/v1/quotes/{quote_id}/send` | external | `quotes:run` |
+| `editQuoteAsDraft` | POST `/api/v1/quotes/{quote_id}/edit-as-draft` | external | `quotes:run` |
+| `duplicateQuote` | POST `/api/v1/quotes/{quote_id}/duplicate` | external | `quotes:run` |
+| `deleteQuote` | DELETE `/api/v1/quotes/{quote_id}` | destructive | `quotes:delete` |
+| `resendEnvelope` | POST `/api/v1/envelopes/{envelope_id}/resend` | external | `quotes:run` |
+
+## Recipes
+
+- `recipes/create-and-send-quote.ts`: Create a quote from quotable products and send it for signature
+- `recipes/track-quote-signature.ts`: Wait for a quote to be signed (or declined)
+- `recipes/revise-sent-quote.ts`: Change a quote that was already sent

package/blocks/quotes/block.json

@@ -0,0 +1,183 @@
+{
+  "$schema": "../block.schema.json",
+  "id": "quotes",
+  "title": "Quotes & e-sign",
+  "summary": "Quote list, a draft builder with a quotable-product picker, a quote viewer that sends for signature, and signature status.",
+  "features": [
+    "quotes list with status filter",
+    "draft builder with live totals and signer search",
+    "quotable product picker (Stripe and manual products)",
+    "send, resend and edit-as-draft behind confirms",
+    "e-signature status with reminder"
+  ],
+  "dependsOn": [
+    "deals"
+  ],
+  "operations": [
+    "list_quotes_quotes_get",
+    "get_quote_quotes__quote_id__get",
+    "search_quote_contacts_quote_contacts_get",
+    "create_quote_quotes_post",
+    "update_quote_quotes__quote_id__patch",
+    "list_quotable_products_quotable_products_get",
+    "send_quote_quotes__quote_id__send_post",
+    "edit_quote_as_draft_quotes__quote_id__edit_as_draft_post",
+    "duplicate_quote_quotes__quote_id__duplicate_post",
+    "delete_quote_quotes__quote_id__delete",
+    "resend_envelope_envelopes__envelope_id__resend_post"
+  ],
+  "components": [
+    {
+      "name": "QuoteList",
+      "file": "components/quote-list.tsx",
+      "purpose": "Quotes with a status filter, totals in the quote currency, and paging; optionally scoped to a deal or company.",
+      "operations": [
+        "list_quotes_quotes_get"
+      ],
+      "tiers": [
+        "read"
+      ]
+    },
+    {
+      "name": "QuoteBuilder",
+      "file": "components/quote-builder.tsx",
+      "purpose": "Create or edit a draft quote: details, signer search, line items from the product picker, live totals; lists what is still missing.",
+      "operations": [
+        "get_quote_quotes__quote_id__get",
+        "search_quote_contacts_quote_contacts_get",
+        "create_quote_quotes_post",
+        "update_quote_quotes__quote_id__patch"
+      ],
+      "tiers": [
+        "read",
+        "external"
+      ]
+    },
+    {
+      "name": "ProductPicker",
+      "file": "components/product-picker.tsx",
+      "purpose": "Pick a quotable product and price (Stripe or manual) and get back a ready line item.",
+      "operations": [
+        "list_quotable_products_quotable_products_get"
+      ],
+      "tiers": [
+        "read"
+      ]
+    },
+    {
+      "name": "QuoteViewer",
+      "file": "components/quote-viewer.tsx",
+      "purpose": "Read a quote with its totals and actions by status: send or resend for signature, edit as draft, duplicate, delete.",
+      "operations": [
+        "get_quote_quotes__quote_id__get",
+        "send_quote_quotes__quote_id__send_post",
+        "edit_quote_as_draft_quotes__quote_id__edit_as_draft_post",
+        "duplicate_quote_quotes__quote_id__duplicate_post",
+        "delete_quote_quotes__quote_id__delete"
+      ],
+      "tiers": [
+        "read",
+        "external",
+        "destructive"
+      ]
+    },
+    {
+      "name": "SignatureStatus",
+      "file": "components/signature-status.tsx",
+      "purpose": "E-signature state of a quote: sent, viewed, signed or declined, who still has to sign, activity, and a reminder behind a confirm.",
+      "operations": [
+        "get_quote_quotes__quote_id__get",
+        "resend_envelope_envelopes__envelope_id__resend_post"
+      ],
+      "tiers": [
+        "read",
+        "external"
+      ]
+    }
+  ],
+  "hooks": [
+    {
+      "name": "useDebounced",
+      "file": "hooks/use-debounced.ts",
+      "purpose": "Debounce a fast-changing value (the signer search box)."
+    }
+  ],
+  "lib": [
+    {
+      "file": "lib/quotes.ts",
+      "purpose": "Line-item math in cents, product and line types, request line mapping, status labels."
+    }
+  ],
+  "recipes": [
+    {
+      "file": "recipes/create-and-send-quote.ts",
+      "title": "Create a quote from quotable products and send it for signature",
+      "when": "A deal is ready for paper; products must be quotable, amounts are cents, sending emails the signer (external)."
+    },
+    {
+      "file": "recipes/track-quote-signature.ts",
+      "title": "Wait for a quote to be signed (or declined)",
+      "when": "After sending, when the next step depends on the signature; poll the envelope status."
+    },
+    {
+      "file": "recipes/revise-sent-quote.ts",
+      "title": "Change a quote that was already sent",
+      "when": "Terms changed after sending; edit-as-draft voids the sent copy, then edit and resend (both external)."
+    }
+  ],
+  "prerequisites": [
+    {
+      "id": "quotable-products",
+      "description": "At least one product is marked quotable (a Stripe product opted in, or a manual product); quotes can only contain quotable products.",
+      "where": "api",
+      "verify": "GET /quotable-products returns at least one item with a flat price."
+    },
+    {
+      "id": "quote-settings",
+      "description": "Quote settings (company legal details, terms, sender identity) are filled in, so sent quotes carry the right branding and terms.",
+      "where": "app",
+      "verify": "GET /quote-settings returns your company name and terms."
+    },
+    {
+      "id": "stripe-connected",
+      "description": "Stripe is connected if quotes should carry Stripe products or turn into subscriptions when accepted.",
+      "where": "app",
+      "verify": "GET /stripe/integration-status reports connected."
+    }
+  ],
+  "scopes": [
+    "quotes:delete",
+    "quotes:read",
+    "quotes:run"
+  ],
+  "defaults": [
+    {
+      "decision": "Saving a draft",
+      "default": "One click, no confirmation: a draft emails nobody",
+      "askHuman": false
+    },
+    {
+      "decision": "Sending or resending a quote",
+      "default": "Always confirmed in the UI; from code, only after the person agreed",
+      "askHuman": true
+    },
+    {
+      "decision": "Payment terms",
+      "default": "net 30",
+      "askHuman": false
+    },
+    {
+      "decision": "Currency",
+      "default": "USD unless the deal or products say otherwise",
+      "askHuman": false
+    },
+    {
+      "decision": "Where the deal id comes from",
+      "default": "The deals block (PipelineBoard / DealDetail pass dealId); never typed by hand",
+      "askHuman": false
+    }
+  ],
+  "peerDependencies": {
+    "react": ">=18"
+  }
+}