@graph8/sdk 0.373.0 → 0.374.0

package/blocks/documents/recipes/log-account-correspondence.ts

@@ -0,0 +1,27 @@
+/**
+ * @title Import an account's messages so running it twice does not duplicate them
+ * @when Bringing emails, LinkedIn messages or call notes in from another system. Partial success is normal: the status is 200
+ * even when rows failed, so read `imported`, `skipped` and `errors`. A row whose `external_id` is already stored is SKIPPED,
+ * so send one on every row. `correspondence_date` is when the message HAPPENED, not when you import it: generated documents
+ * read it as the relationship timeline. `channel` is email, linkedin or call_notes; `direction` is inbound or outbound.
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+const accountId = process.env.G8_COMPANY_ID!; // a company id from g8.api.companies.listCompanies
+
+const result = await g8.api.documents.importAccountCorrespondence({
+  path: { account_id: accountId },
+  body: {
+    items: [
+      { channel: "email", direction: "inbound", subject: "Re: pricing", content: "Thanks for the call, sending the quote today.", correspondence_date: "2026-09-30T14:00:00Z", external_id: "msg-1001" },
+      { channel: "call_notes", direction: "outbound", content: "Walked through the security review.", correspondence_date: "2026-10-02T16:30:00Z", external_id: "call-2002" },
+    ],
+  },
+});
+const r = result.data as { imported?: number; skipped?: number; errors?: string[] };
+console.log(`${r.imported ?? 0} imported, ${r.skipped ?? 0} skipped, ${(r.errors ?? []).length} failed`);
+
+const recent = await g8.api.documents.listAccountCorrespondence({ path: { account_id: accountId }, query: { limit: 10 } });
+console.log((recent.data.items ?? []).length, "messages on the account");

package/blocks/documents/recipes/organize-the-library.ts

@@ -0,0 +1,25 @@
+/**
+ * @title Create a Library folder and a text document in it, then list what the folder holds
+ * @when Seeding the Library from a script. The folder must exist before a document can land in it, and a folder name is
+ * letters, numbers, spaces, hyphens and underscores (at most 50), three levels deep at most. A text document is stored exactly
+ * as sent (no extraction). Nothing here reaches anyone. To add a FILE (PDF, Word ...) the API takes multipart, which this
+ * typed client does not send: post it with `fetch` and a `FormData` to /api/v1/library/documents/upload.
+ */
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+
+const folder = await g8.api.documents.createLibraryFolder({ body: { name: "Case studies 2026", parent_path: "Library" } });
+const folderPath = String((folder.data as { full_path?: string }).full_path ?? "Library/Case studies 2026");
+
+const doc = await g8.api.documents.createLibraryDocument({
+  body: {
+    folder_path: folderPath,
+    file_name: "acme-rollout.md",
+    display_name: "Acme rollout",
+    content: "Acme moved 400 seats in six weeks.",
+  },
+});
+
+const inFolder = await g8.api.documents.listLibraryDocuments({ query: { folder_path: folderPath } });
+console.log(folderPath, (doc.data as { id?: string }).id, (inFolder.data.items ?? []).length);

package/blocks/email-signatures/README.md

@@ -0,0 +1,123 @@
+# email-signatures
+
+Managed email signatures: design **one signature for the team** and keep every mailbox on it. A *template* is the shared
+design (blocks, layout, font, colour, with placeholders such as `{{member.name}}`). A *deployment* binds one mailbox to one
+employee and a template, and the platform installs or applies it. A *policy* decides whether signatures are managed at all,
+which template is the default, and whether employees may change the unlocked parts. A *campaign* adds a banner to signatures
+for a time window. Changing what a mailbox sends is consequential, so every such action is confirmed with the real number of
+mailboxes it touches.
+
+## Screens
+
+`EmailSignaturesScreen` (`components/email-signatures-screen.tsx`) is the finished page: templates, mailboxes, campaigns,
+policy and report.
+
+```tsx
+import { EmailSignaturesScreen } from "@/g8/email-signatures/components/email-signatures-screen";
+export default function Page() { return <EmailSignaturesScreen />; }
+```
+
+Tabs (`?tab=`): **Templates**, **Mailboxes**, **Campaigns**, **Policy**, **Report**. Open a template (`?id=`) for Preview,
+Edit, Use on mailboxes and Details; `&view=full` shows it as a full page.
+
+Flows: see every template (the list is complete: the API does not page it); create one from blocks and placeholders with a
+live preview; preview a stored template as a sample or as a real employee on a real mailbox (full, compact, with the campaign
+banner, or plain text); edit it (the form opens only after the full record has loaded, and a stale save is refused with
+"Load the newer version"); apply it to chosen mailboxes, a department or every mailbox; make it the organisation default;
+archive it. On **Mailboxes**: assign an employee to a mailbox (with a setup check first), push, restore the old signature and
+change what a mailbox sends, one by one or in bulk. **Campaigns**: create and edit banner campaigns, preview the banner, and
+test which mailbox and recipients it would reach. **Policy**: off, managed or enforced, default and department templates.
+**Report**: impressions and clicks by mailbox and campaign.
+
+Parts you can mount alone: `SignatureTemplateForm`, `TemplatePreview` (and `SafeSignatureFrame`), `SignatureAssignTemplate`,
+`SignatureTemplateDetails`, `SignatureMailboxes`, `SignatureIdentityForm`, `SignaturePolicy`, `SignatureCampaigns`,
+`SignatureCampaignForm`, `SignatureReport`, `SignatureBlockEditor`.
+
+## Install
+
+```
+npx @graph8/sdk add email-signatures
+```
+
+Installs `foundation` and `mailboxes` first if missing. Everything lands under `g8/email-signatures/`. The block does not use the `pickers` block on purpose: its `MemberPicker` reports a
+user id, while a signature is assigned to a *directory employee* (`listSignatureMembers`, a different id), and the mailbox
+list is merged with each mailbox's signature status, which no generic picker knows.
+
+## Prerequisites (the human must do these)
+
+| Where | What | How to verify |
+|---|---|---|
+| graph8 | Mailboxes connected (Google or Microsoft in the app, or the mailboxes block). A signature is bound to a mailbox. | `GET /api/v1/mailboxes` lists it. |
+| graph8 | The people who sign are team members **with an email address**. An employee without one cannot be assigned. | `GET /api/v1/signatures/members` lists them. |
+| The app | Installing a signature inside a Google account needs the Google Workspace integration with the signature permission, granted by a Workspace admin. A deployment stuck at `needs_admin_grant` is missing it. Without native installation the signature is applied when mail is sent from the platform. | A deployment leaves `needs_admin_grant`. |
+| graph8 key | `signatures:read`, `signatures:write`, `signatures:delete` (archive). `campaigns:read` lists mailboxes. | `g8.api.me.describeCurrentKey()` |
+| Your app | `allowedPrefixes` must include `signatures` and `mailboxes`. | The route file lists them. |
+
+## The flow, in order (IDs passed between steps)
+
+1. **Template**: `createSignatureTemplate({ data: { name, layout, blocks, primary_color, font, brand_source } })` -> **`template.id`** and `template.version`. Exactly one required, locked `identity` block; at most one optional `banner`; unique block ids; required blocks are locked.
+2. **Preview**: `previewSignatureTemplate({ data })` for a draft, `previewSavedSignatureTemplate(template.id, { mailbox_id, member_id })` for a stored one. Pass **both** `mailbox_id` and `member_id` to render with that employee's real details, neither for sample data. Reads only.
+3. **Policy**: `getSignatureSettings` -> **`version`** (the *policy* version). `setDefaultSignatureTemplate(template.id, { version })` makes the template the default (confirmed). `updateSignatureSettings({ version, data })` turns management off, on (`default`) or `enforced`; on needs a default template, enforced needs every active mailbox assigned.
+4. **Employee and mailbox**: `listSignatureMembers` -> **`member.id`**; the mailbox from `listMailboxes` -> **`mailbox.id`**; `listSignatureDeployments` -> the mailbox's **`revision`** (0 when it has no assignment).
+5. **Check**: `previewSignatureSetup({ mailbox_id, data })` is a dry run against the mail provider (account and send-as resolve).
+6. **Assign**: `assignSignatureIdentity({ mailbox_ids, expected_revisions: { [mailbox.id]: revision }, confirm_takeover: true, data: { member_id, account_subject, send_as_email, template_id? } })` behind a confirmation. `account_subject` must be the employee's own directory email and `send_as_email` the mailbox address.
+7. **Bulk**: `assignSignatureTemplate(template.id, { mailbox_ids } | { department } | { all_mailboxes: true })` (exactly one; every target already assigned), `pushSignatures({ mailbox_ids })`, `pushSignature(mailbox.id, { version: revision })`.
+8. **Change or undo**: `changeSignatureSource(mailbox.id, { version, source: "org" | "template" | "custom", template_id? })`; `restoreSignature(mailbox.id, { version })` puts back what the mailbox had before (refused while the policy is `enforced`; parked as `restore_conflict` if the signature was edited elsewhere since).
+9. **Campaign**: `createSignatureCampaign({ data })` (banner block, `starts_at` / `ends_at` timezone-aware, status `draft`, `scheduled` or `paused`); only a `scheduled` campaign inside its dates is added. `previewSignatureCampaign` renders it and, with a mailbox and recipients, says whether it would apply.
+10. **Read**: `getSignatureReport`.
+
+## Default decisions (do not ask the human unless marked)
+
+| Decision | Default | Ask? |
+|---|---|---|
+| New template | Classic stacked, Arial, text colour `#222222`, brand kit colour and font, one required locked identity block (the API's own defaults) | no |
+| Which mailboxes get a template | None: a person chooses the mailboxes, a department or everyone and confirms the count | **yes** |
+| Policy mode | Left as it is | **yes** |
+| Assigning an employee to a mailbox | Account = the employee's directory email, send-as = the mailbox address, after the person agrees to the takeover | **yes** |
+| Stopping a campaign | Set it to Paused (there is no delete) | no |
+| Removing a template | Archive it, after giving its mailboxes another template | no |
+| After editing a template | Push the mailboxes that use it | no |
+
+## Operation coverage (24 signatures operations, all reachable from `EmailSignaturesScreen`)
+
+| Operation | Where |
+|---|---|
+| `listSignatureTemplates`, `getSignatureTemplate` | template list; the edit form (full record) |
+| `createSignatureTemplate`, `updateSignatureTemplate` | `SignatureTemplateForm` |
+| `archiveSignatureTemplate` | `SignatureTemplateDetails` (destructive, confirmed; disabled while the template is in use) |
+| `setDefaultSignatureTemplate` | `SignatureTemplateDetails` (confirmed, sized from the mailboxes that follow the default) |
+| `assignSignatureTemplate` | `SignatureAssignTemplate` (confirmed, sized from the mailboxes the choice covers) |
+| `previewSignatureTemplate`, `previewSavedSignatureTemplate` | `TemplatePreview` |
+| `listSignatureMembers` | employee menus |
+| `listSignatureDeployments` | `SignatureMailboxes` and every count in a confirmation |
+| `assignSignatureIdentity`, `previewSignatureSetup` | `SignatureIdentityForm` (takeover confirmed; setup check first) |
+| `pushSignature`, `pushSignatures`, `restoreSignature`, `changeSignatureSource` | `SignatureMailboxes` (each confirmed) |
+| `getSignatureSettings`, `updateSignatureSettings` | `SignaturePolicy` (save confirmed) |
+| `listSignatureCampaigns`, `createSignatureCampaign`, `updateSignatureCampaign`, `previewSignatureCampaign` | `SignatureCampaigns`, `SignatureCampaignForm` |
+| `getSignatureReport` | `SignatureReport` |
+
+No operation of the namespace is skipped. The block also reads `listMailboxes` (the mailboxes to assign). Previews and the setup check are POSTs, so the contract tiers them as `write`; they change nothing.
+
+## API gaps (what is asked for that the API does not have)
+
+| Asked for | Reality | What the block does |
+|---|---|---|
+| A list of template variables | None. The renderer resolves a fixed set (`member.*`, `mailbox.*`, `company.*`, `brand.*`). | A built-in placeholder list that mirrors the renderer (`lib/signatures-types.ts`). `{{x\|fallback}}` is supported. |
+| Delete a template or a campaign | Templates can only be archived (refused while in use); campaigns cannot be removed. | Archive with the reason it is blocked; pause a campaign. |
+| Read one campaign | There is `list` only. | Edit seeds from the list row, which is the complete stored campaign, and refreshes the list after a save. |
+| Paging and filters | The template, member, deployment and campaign lists take no paging parameters and return everything. `listMailboxes` takes `limit` up to 500 and no page. | The UI says "All N"; a mailbox read that comes back full says "Showing the first 500 mailboxes". |
+| Mailboxes with no signature yet | `listSignatureDeployments` only lists mailboxes that already have a deployment. | Merged with `listMailboxes` (needs `campaigns:read`); without that scope only the assigned mailboxes show, with a note. |
+| Upload a logo or photo | Multipart uploads are not in the developer API. | Images are referenced by address. |
+| Pick audience lists for a campaign | The block has no list picker (it does not depend on the lists block). | A campaign that already targets lists keeps them on every save and can have the targeting removed; add lists through `createSignatureCampaign` / `updateSignatureCampaign` (`recipient_list_ids`). |
+| Employee self-service (`/me`) | An API key has no seat or directory identity. | Out of scope. Employee overrides are carried over unchanged when an assignment is edited. |
+| Choose the Workspace integration | The integrations used by signatures are not listed by the API. | An existing assignment's integration is carried over; a new one lets the API pick. |
+| Click-tracking redirect | Public, unauthenticated by design. | Not an API capability. |
+| Edit part of a template | `updateSignatureTemplate` and `updateSignatureSettings` replace the document. | The whole template is sent, built from the full record that was read; a cleared field is sent empty (`""`), a cleared default template as `null`; a save with no change sends nothing. |
+
+## Things that surprise people
+
+- Every write carries the version or revision that was read. A concurrent change answers **409**; the screen says so and offers the newer version. The **policy** has its own version, used by set-default and the policy save.
+- Signature HTML comes from the API and a template can carry custom markup, so the preview shows it in a **sandboxed frame** with no scripts. Never put signature HTML into your own page with `dangerouslySetInnerHTML`.
+- A required block with a placeholder that has no fallback fails to render for an employee whose directory entry lacks that value. Add `{{member.title|Team}}`.
+- Campaign targeting by audience list applies only to mail sent from a sequence. Dates are picked in the viewer's time zone and sent as timezone-aware instants.
+- Enforced mode refuses a restore and employee changes; turning management **off** stops managing every mailbox.

package/blocks/email-signatures/block.json

@@ -0,0 +1,341 @@
+{
+  "$schema": "../block.schema.json",
+  "id": "email-signatures",
+  "title": "Email signatures",
+  "summary": "Design one signature for the team and keep every mailbox on it: templates with a live preview, assignment to mailboxes and employees, the organisation default, banner campaigns, policy and engagement.",
+  "features": [
+    "signature templates built from blocks and placeholders, with a safe live preview as a sample or as a real employee",
+    "apply a template to chosen mailboxes, a department or everyone, confirmed with the real number of mailboxes",
+    "make a template the organisation default or archive it, both confirmed",
+    "assign an employee to a mailbox (setup check first), push, restore the old signature and change a mailbox's source",
+    "banner campaigns for a time window with targeting, a preview and a who-would-see-it test",
+    "policy: off, managed or enforced, default and department templates, employee overrides, cold-send variant",
+    "impressions and clicks by mailbox and campaign, with the limits of the numbers"
+  ],
+  "dependsOn": [
+    "mailboxes"
+  ],
+  "operations": [
+    "archive_signature_template_signatures_templates__template_id__delete",
+    "assign_signature_identity_signatures_assignments_post",
+    "assign_signature_template_signatures_templates__template_id__assign_post",
+    "change_signature_source_signatures_mailboxes__mailbox_id__source_post",
+    "create_signature_campaign_signatures_campaigns_post",
+    "create_signature_template_signatures_templates_post",
+    "get_signature_report_signatures_reports_get",
+    "get_signature_settings_signatures_settings_get",
+    "get_signature_template_signatures_templates__template_id__get",
+    "list_mailboxes_mailboxes_get",
+    "list_signature_campaigns_signatures_campaigns_get",
+    "list_signature_deployments_signatures_mailboxes_get",
+    "list_signature_members_signatures_members_get",
+    "list_signature_templates_signatures_templates_get",
+    "preview_saved_signature_template_signatures_templates__template_id__preview_post",
+    "preview_signature_campaign_signatures_campaigns_preview_post",
+    "preview_signature_setup_signatures_setup_preview_post",
+    "preview_signature_template_signatures_preview_post",
+    "push_signature_signatures_mailboxes__mailbox_id__push_post",
+    "push_signatures_signatures_mailboxes_push_post",
+    "restore_signature_signatures_mailboxes__mailbox_id__restore_post",
+    "set_default_signature_template_signatures_templates__template_id__set_default_post",
+    "update_signature_campaign_signatures_campaigns__campaign_id__patch",
+    "update_signature_settings_signatures_settings_put",
+    "update_signature_template_signatures_templates__template_id__patch"
+  ],
+  "components": [
+    {
+      "name": "EmailSignaturesScreen",
+      "file": "components/email-signatures-screen.tsx",
+      "purpose": "Finished email-signatures workspace: templates with a live preview, apply to mailboxes, the organisation default, mailboxes with push, restore and source, banner campaigns, the policy and the engagement report.",
+      "operations": [
+        "get_signature_settings_signatures_settings_get",
+        "list_signature_deployments_signatures_mailboxes_get",
+        "list_signature_templates_signatures_templates_get"
+      ],
+      "tiers": [
+        "read"
+      ]
+    },
+    {
+      "name": "SignatureTemplateForm",
+      "file": "components/signature-template-form.tsx",
+      "purpose": "Create or edit a signature template (layout, font, colour, blocks, placeholders) with a live preview; edit reads the full record first and a stale save is refused.",
+      "operations": [
+        "create_signature_template_signatures_templates_post",
+        "get_signature_template_signatures_templates__template_id__get",
+        "update_signature_template_signatures_templates__template_id__patch"
+      ],
+      "tiers": [
+        "read",
+        "write"
+      ]
+    },
+    {
+      "name": "SignatureBlockEditor",
+      "file": "components/signature-block-editor.tsx",
+      "purpose": "The ordered block list of a template: type, text, link, image, locked, required, placeholders, reorder and remove. A pure control that calls no operation.",
+      "operations": [],
+      "tiers": []
+    },
+    {
+      "name": "TemplatePreview",
+      "file": "components/signature-preview.tsx",
+      "purpose": "Render a draft or a stored template as a sample or as a real employee on a real mailbox, in full, compact or campaign form, or as plain text; the HTML is shown in a sandboxed frame (also exports SafeSignatureFrame).",
+      "operations": [
+        "list_mailboxes_mailboxes_get",
+        "list_signature_deployments_signatures_mailboxes_get",
+        "list_signature_members_signatures_members_get",
+        "preview_saved_signature_template_signatures_templates__template_id__preview_post",
+        "preview_signature_template_signatures_preview_post"
+      ],
+      "tiers": [
+        "read",
+        "write"
+      ]
+    },
+    {
+      "name": "SignatureAssignTemplate",
+      "file": "components/signature-assign-template.tsx",
+      "purpose": "Apply a template to chosen mailboxes, a department or every mailbox; confirmed with the number of mailboxes it really covers.",
+      "operations": [
+        "assign_signature_template_signatures_templates__template_id__assign_post",
+        "list_mailboxes_mailboxes_get",
+        "list_signature_deployments_signatures_mailboxes_get",
+        "list_signature_members_signatures_members_get"
+      ],
+      "tiers": [
+        "read",
+        "write"
+      ]
+    },
+    {
+      "name": "SignatureTemplateDetails",
+      "file": "components/signature-template-details.tsx",
+      "purpose": "One template's facts, make it the organisation default (confirmed, sized from the mailboxes that follow it) and archive it (confirmed; disabled while it is in use).",
+      "operations": [
+        "archive_signature_template_signatures_templates__template_id__delete",
+        "get_signature_settings_signatures_settings_get",
+        "list_signature_deployments_signatures_mailboxes_get",
+        "list_signature_members_signatures_members_get",
+        "set_default_signature_template_signatures_templates__template_id__set_default_post"
+      ],
+      "tiers": [
+        "read",
+        "write",
+        "destructive"
+      ]
+    },
+    {
+      "name": "SignatureMailboxes",
+      "file": "components/signature-mailboxes.tsx",
+      "purpose": "Every mailbox with its employee, template source and status; assign an employee, push (one or many), restore the old signature and change what a mailbox sends, each confirmed.",
+      "operations": [
+        "change_signature_source_signatures_mailboxes__mailbox_id__source_post",
+        "get_signature_settings_signatures_settings_get",
+        "list_mailboxes_mailboxes_get",
+        "list_signature_deployments_signatures_mailboxes_get",
+        "list_signature_members_signatures_members_get",
+        "list_signature_templates_signatures_templates_get",
+        "push_signature_signatures_mailboxes__mailbox_id__push_post",
+        "push_signatures_signatures_mailboxes_push_post",
+        "restore_signature_signatures_mailboxes__mailbox_id__restore_post"
+      ],
+      "tiers": [
+        "read",
+        "write"
+      ]
+    },
+    {
+      "name": "SignatureIdentityForm",
+      "file": "components/signature-identity-form.tsx",
+      "purpose": "Bind one mailbox to an employee: account and send-as derived from the choices, a dry-run setup check, then a confirmed takeover.",
+      "operations": [
+        "assign_signature_identity_signatures_assignments_post",
+        "list_signature_deployments_signatures_mailboxes_get",
+        "list_signature_members_signatures_members_get",
+        "list_signature_templates_signatures_templates_get",
+        "preview_signature_setup_signatures_setup_preview_post"
+      ],
+      "tiers": [
+        "read",
+        "write"
+      ]
+    },
+    {
+      "name": "SignaturePolicy",
+      "file": "components/signature-policy.tsx",
+      "purpose": "The organisation policy: off, managed or enforced, default and department templates, employee overrides, cold-send variant and native installation; a confirmed save of the changed fields.",
+      "operations": [
+        "get_signature_settings_signatures_settings_get",
+        "list_signature_deployments_signatures_mailboxes_get",
+        "list_signature_members_signatures_members_get",
+        "list_signature_templates_signatures_templates_get",
+        "update_signature_settings_signatures_settings_put"
+      ],
+      "tiers": [
+        "read",
+        "write"
+      ]
+    },
+    {
+      "name": "SignatureCampaigns",
+      "file": "components/signature-campaigns.tsx",
+      "purpose": "Banner campaigns with status, dates and priority; create and edit in a sheet.",
+      "operations": [
+        "list_signature_campaigns_signatures_campaigns_get"
+      ],
+      "tiers": [
+        "read"
+      ]
+    },
+    {
+      "name": "SignatureCampaignForm",
+      "file": "components/signature-campaign-form.tsx",
+      "purpose": "Create or edit a banner campaign (banner, dates, status, priority, who sees it), preview the banner and test which mailbox and recipients it would reach.",
+      "operations": [
+        "create_signature_campaign_signatures_campaigns_post",
+        "list_mailboxes_mailboxes_get",
+        "list_signature_deployments_signatures_mailboxes_get",
+        "list_signature_members_signatures_members_get",
+        "preview_signature_campaign_signatures_campaigns_preview_post",
+        "update_signature_campaign_signatures_campaigns__campaign_id__patch"
+      ],
+      "tiers": [
+        "read",
+        "write"
+      ]
+    },
+    {
+      "name": "SignatureReport",
+      "file": "components/signature-report.tsx",
+      "purpose": "Impressions and clicks by mailbox and campaign, with the limits the API states about the numbers.",
+      "operations": [
+        "get_signature_report_signatures_reports_get",
+        "list_mailboxes_mailboxes_get",
+        "list_signature_campaigns_signatures_campaigns_get",
+        "list_signature_deployments_signatures_mailboxes_get"
+      ],
+      "tiers": [
+        "read"
+      ]
+    }
+  ],
+  "hooks": [
+    {
+      "name": "useSignaturesData",
+      "file": "hooks/use-signatures-data.ts",
+      "purpose": "Shared cached reads: templates, one template, members, mailbox deployments, the policy, campaigns, and mailboxes merged with their deployments (the mailbox list is read once at the API's limit of 500 and says when it may be longer).",
+      "operations": [
+        "get_signature_settings_signatures_settings_get",
+        "get_signature_template_signatures_templates__template_id__get",
+        "list_mailboxes_mailboxes_get",
+        "list_signature_campaigns_signatures_campaigns_get",
+        "list_signature_deployments_signatures_mailboxes_get",
+        "list_signature_members_signatures_members_get",
+        "list_signature_templates_signatures_templates_get"
+      ]
+    }
+  ],
+  "lib": [
+    {
+      "file": "lib/signatures-types.ts",
+      "purpose": "Template, policy, deployment and campaign types; the API's exact vocabularies (block kinds, layouts, fonts, modes, statuses, sources); the placeholder list; template rules checked before a save; local-time helpers for campaign dates."
+    }
+  ],
+  "recipes": [
+    {
+      "file": "recipes/create-a-template-and-make-it-default.ts",
+      "title": "Create a signature template and make it the organisation default",
+      "when": "First-time setup; making it the default changes what mailboxes send, so a person confirms."
+    },
+    {
+      "file": "recipes/assign-a-signature-to-a-new-hire.ts",
+      "title": "Give a new hire's mailbox a managed signature",
+      "when": "Onboarding; a takeover of the mailbox's signature that a person agrees to."
+    },
+    {
+      "file": "recipes/signature-engagement-report.ts",
+      "title": "Report signature impressions and clicks",
+      "when": "A weekly digest or a dashboard backend."
+    }
+  ],
+  "prerequisites": [
+    {
+      "id": "mailboxes",
+      "description": "Mailboxes connected in the app (Google or Microsoft) or added through the mailboxes block. A signature is bound to a mailbox.",
+      "where": "api",
+      "verify": "GET /api/v1/mailboxes lists the mailbox."
+    },
+    {
+      "id": "directory-employees",
+      "description": "The people who sign must be team members with an email address in the directory. An employee without an email cannot be assigned.",
+      "where": "api",
+      "verify": "GET /api/v1/signatures/members lists them."
+    },
+    {
+      "id": "workspace-signature-access",
+      "description": "Installing a signature inside a Google account needs the Google Workspace integration with the signature permission granted by a Workspace admin in the app. A deployment that stops at needs_admin_grant is missing it. Without native installation the signature is applied when mail is sent from the platform.",
+      "where": "app",
+      "verify": "A deployment reaches an installed status instead of needs_admin_grant."
+    },
+    {
+      "id": "signature-scopes",
+      "description": "The key needs signatures:read, signatures:write and signatures:delete (archive). Listing mailboxes needs campaigns:read.",
+      "where": "api",
+      "verify": "g8.api.me.describeCurrentKey() lists the scopes."
+    },
+    {
+      "id": "proxy-allowlist",
+      "description": "Add \"signatures\" and \"mailboxes\" to allowedPrefixes in app/api/g8/[...path]/route.ts.",
+      "where": "app",
+      "verify": "The route file's allowedPrefixes contains them."
+    }
+  ],
+  "scopes": [
+    "campaigns:read",
+    "signatures:delete",
+    "signatures:read",
+    "signatures:write"
+  ],
+  "defaults": [
+    {
+      "decision": "New template",
+      "default": "Classic stacked layout, Arial, text colour #222222, brand kit colour and font, one required locked identity block with the employee's name and title",
+      "askHuman": false
+    },
+    {
+      "decision": "Which mailboxes get a template",
+      "default": "None: a person always chooses the mailboxes, a department or everyone, and confirms the count",
+      "askHuman": true
+    },
+    {
+      "decision": "Policy mode",
+      "default": "Leave it as it is; turning management on needs a default template, enforcing needs every active mailbox assigned",
+      "askHuman": true
+    },
+    {
+      "decision": "Assigning an employee to a mailbox",
+      "default": "Account = the employee's directory email, send-as = the mailbox address; only after a person agrees to the takeover",
+      "askHuman": true
+    },
+    {
+      "decision": "Stopping a campaign",
+      "default": "Set it to Paused (the API cannot delete a campaign)",
+      "askHuman": false
+    },
+    {
+      "decision": "Removing a template",
+      "default": "Archive it, after giving its mailboxes another template",
+      "askHuman": false
+    },
+    {
+      "decision": "After editing a template",
+      "default": "Push the mailboxes that use it from the Mailboxes tab",
+      "askHuman": false
+    }
+  ],
+  "peerDependencies": {
+    "react": ">=18",
+    "lucide-react": ">=0.400.0"
+  }
+}