@graph8/sdk 0.362.0 → 0.373.0

package/README.md

@@ -8,7 +8,7 @@ The most comprehensive GTM SDK. One `npm install`. Every graph8 capability.
 > operation in [`docs/api/`](docs/api/README.md). It ships with the package, so it matches this version.
 > Run `npx @graph8/sdk init-agent` to point Claude Code, Codex and Cursor in your project at it automatically.
 >
-> Blocks (copy-in components and hooks per feature): `npx @graph8/sdk list`, `search <text>`, `add <block>[/<Component>]`, `create <stack> <dir>` (a whole Next.js app: `npx @graph8/sdk create starter my-app`), and `doctor` to check your key, scopes and subscription. Each takes `--help`.
+> Blocks (copy-in components and hooks per feature): `npx @graph8/sdk list`, `search <text>`, `add <block>[/<Component>]` (`--routes` also wires its screens as routes and nav entries in a created app), `create <stack> <dir>` (a whole Next.js app: `npx @graph8/sdk create starter my-app`), and `doctor` to check your key, scopes and subscription. Each takes `--help`.
 
 ## Install
 
@@ -496,18 +496,41 @@ npx @graph8/sdk create mailchimp my-app   # then: cd my-app && cp .env.local.exa
 | Stack | Screens |
 |---|---|
 | `starter` | An empty app: proxy, shell and one landing page |
-| `mailchimp` | Contacts, companies, forms, submissions, lists, suppressions, newsletter, subscribers, nurture |
-| `clay` | Contacts, companies, lists, suppressions, prospect search, bulk enrichment, workbench |
-| `6sense` | Contacts, companies, intent feed, website visitors, competitor tracker |
-| `intercom` | Contacts, companies, web chat conversations, mailboxes, AI inbox, AI agents |
-| `outreach` | Contacts, companies, lists, mailboxes, sequences, inbox, dialer, call log, meetings, analytics |
-| `apollo` | Outreach's screens plus prospect search, enrichment, intent, visitors, deals and integrations |
-| `gong` | Contacts, companies, lists, dialer, call log, meetings, coaching feed, analytics |
-| `salesforce` | Contacts, companies, custom objects, lists, lifecycle, deals, quotes, analytics, workflows, copilot, integrations |
-| `hubspot` | The full CRM and marketing suite: forms, newsletter, nurture, web chat, sequences, inbox, pages, lifecycle, deals, quotes, workflows |
+| `mailchimp` | Newsletter, nurture, forms, contacts, companies, tasks, lists, suppressions |
+| `clay` | Prospect search, workbench, enrichment, lists, contacts, companies, tasks, suppressions |
+| `6sense` | Intent, visitors, competitors, companies, contacts, tasks |
+| `intercom` | Inbox, web chat conversations, contacts, companies, tasks, AI agents, mailboxes |
+| `calendly` | Meetings and scheduling (event types, availability, booking pages) over contacts, companies and tasks |
+| `pipedrive` | Analytics, deals, quotes, contacts, companies, inbox, meetings, scheduling, tasks and mailboxes; deals and quotes open each other, replies can start a deal |
+| `outreach` | Analytics, contacts, companies, lists, sequences, campaigns, inbox, dialer, call log, meetings, scheduling, tasks, mailboxes, suppressions |
+| `apollo` | Outreach's screens plus prospect search, enrichment, intent, visitors, deals and integrations; contacts get Enrich, Add to sequence and a Deals tab |
+| `gong` | Analytics, call log, coaching, dialer, meetings, scheduling, contacts, companies, tasks, lists, suppressions |
+| `salesforce` | Analytics, contacts, companies, lists, deals, quotes, lifecycle, tasks, workflows, copilot, custom objects, suppressions, integrations |
+| `hubspot` | The full CRM and marketing suite: inbox, web chat, sequences, campaigns, newsletter, nurture, forms, pages, social, ads, deals, quotes, lifecycle, workflows |
+| `zoominfo` | Prospect search, enrichment, intent and visitors over contacts, companies and lists |
+| `hootsuite` | Social posts, ads, landing pages and analytics over your contacts and lists |
 
 Every available stack is proven by `npm run build && npm run e2e:create -- <stack>`, which packs the SDK, scaffolds the app with the built CLI, installs it and requires `next build` to pass. More stacks appear here as their blocks land; `create` refuses a stack that is not available yet.
 
+### Branding: your Brand Kit, automatically
+
+If your graph8 organization already has a Brand Kit (Studio), `create` uses it. With a key in `G8_API_KEY` (environment or `.env.local`), the new app gets your organization's name, primary colour and logo without any flags; the logo is downloaded into `public/brand/` (never hot-linked), and the colour becomes `--brand` / `--primary` with button text checked for WCAG AA.
+
+```bash
+G8_API_KEY=... npx @graph8/sdk create apollo my-app           # picks up the Brand Kit
+npx @graph8/sdk create apollo my-app --no-org-brand            # skip it
+npx @graph8/sdk create apollo my-app --brand-color "#0f62fe"   # your colour wins; the kit still fills the name and logo
+npx @graph8/sdk brand --from-org                               # brand an existing app from the kit
+```
+
+| Brand Kit field (Developer API) | App brand input |
+|---|---|
+| `GET /me` `org_name` | `--name` (`g8.config.ts` `name`) |
+| `GET /brand-kit` `design_tokens.colors.primary` (else `brand`, `accent`, button background) | `--brand-color` |
+| `GET /brand-kit` `logo_url` (one logo; no light, dark or icon variant) | `--logo` (`public/brand/logo.*`) |
+
+Explicit flags always win, field by field. With no key, a missing or empty kit, no `campaigns:read` scope or no network, the app keeps the default look and the CLI prints one info line; it never fails. The key is never printed or written. Fonts, tagline and voice traits are in the kit but have no brand input, so they are not applied. Icons stay Lucide.
+
 ## UI kit (`@graph8/sdk/ui`)
 
 The React component kit and design tokens behind the graph8 app (primitives, light and dark

package/blocks/_foundation/README.md

@@ -8,7 +8,9 @@ Shared base every other block depends on. Install it first (the CLI does it for
 |---|---|
 | `lib/g8-client.ts` | Browser caller: `g8Get/g8Post/g8Put/g8Patch/g8Delete` -> your own `/api/g8/...` proxy. No API key. Returns the API envelope `{ data, pagination? }`, throws `G8Error`. |
 | `server/proxy.ts` | `createG8Proxy(config)`: the logic of the proxy (forwarding, allowlist, `authorize` hook). |
-| `server/route.ts` | Installs as `app/api/g8/[...path]/route.ts` and mounts the proxy. |
+| `server/route.ts` | Installs as `app/api/g8/[...path]/route.ts` and mounts the proxy. `allowedPrefixes` is generated from the installed blocks' operations; local preview is on. |
+| `server/local-key.ts`, `server/connect.ts`, `server/connect-route.ts` | Local preview key store: `app/api/g8-connect/route.ts` checks a pasted key (GET /me) and keeps it in `.g8/local-key` on the server. 404 in production. |
+| `components/connect-graph8.tsx` | `ConnectGraph8Panel` + `G8ConnectGate`: the first-run Connect graph8 panel in `next dev`; a no-op in production. |
 | `hooks/use-g8-query.ts` | `useG8Query(fetcher, deps)` -> `{ data, error, loading, refetch }`. Latest request wins. |
 | `hooks/use-g8-mutation.ts` | `useG8Mutation(fn)` -> `{ mutate, mutateAsync, data, error, loading, reset }`. |
 | `hooks/use-paginated.ts` | `usePaginated(fetchPage, deps)` -> `{ items, hasMore, loadMore, reload, loading, loadingMore, error }`. Follows `pagination.next_cursor`. |
@@ -18,6 +20,7 @@ Shared base every other block depends on. Install it first (the CLI does it for
 | `components/empty-state.tsx` | `EmptyState`: empty list with a first step. |
 | `components/screen/*.tsx` | The **screen kit** (below): `ScreenLayout`, `StatStrip`, `SplitView`, `DetailPanel`, `Toolbar`, `StatusPill`, `EntityAvatar`, `SectionCard`, `FormSheet`, `KeyValueList`, `Sparkline`, `BarList`, `TimeSeriesChart`. Barrel: `@/g8/components/screen`. |
 | `hooks/use-url-state.ts` | `useUrlState(key, default = "")` -> `[value, set]`. One string in the URL query as state (replaceState + popstate, SSR-safe). |
+| `lib/g8-cache.ts` | The shared query cache behind the hooks' optional `key`: dedupe, stale-while-revalidate, focus/reconnect refresh, `invalidate(prefix)`, `setQueryData`, bounded LRU. See "Query cache" below. |
 
 ## Flow of every call
 
@@ -30,6 +33,48 @@ Shared base every other block depends on. Install it first (the CLI does it for
 Ids that pass between calls always come from a previous response (a list's `id` into the next call's
 path). Never invent one.
 
+## Query cache (opt in with a `key`)
+
+Every hook works exactly as before without a key. Pass one and the data lives in one app-wide cache
+(`lib/g8-cache.ts`, no dependencies):
+
+```ts
+const contacts = useG8Query(
+  (signal) => g8Get("/contacts", { page, limit: 25, q }, { signal }),
+  [page, q],
+  { key: ["contacts", "list", { page, q }] },          // name EVERY input the fetcher reads
+);
+const contact = useG8Query((s) => g8Get(`/contacts/${id}`, {}, { signal: s }), [id], { key: ["contacts", "detail", id] });
+const save = useG8Mutation((v: Patch) => g8Patch(`/contacts/${v.id}`, v), { invalidates: ["contacts"] });
+```
+
+- **Dedupe**: components asking for the same key share one request and one answer.
+- **Stale-while-revalidate**: a cached key renders instantly on mount (no skeleton) and refreshes in the
+  background once older than `staleTime` (default 0). Use `staleTime: 60_000` for data that rarely changes
+  (custom-field schemas, pipelines, dispositions).
+- **Focus/reconnect**: watched keys refresh when the window regains focus or the network returns, at most
+  once per 5 s per key (`refetchOnFocus: false` opts out; `usePaginated` defaults to false so a scroll is kept).
+- **Invalidation**: `invalidate("contacts")` (or a mutation's `invalidates: ["contacts"]`) marks every key
+  starting with `"contacts"` stale; keys on screen refetch now, a request started before the write is
+  superseded, the rest refetch when next shown. Prefixes match whole parts (`"deals"` never matches `"deals-x"`).
+- **Writes into the cache**: `setQueryData(key, value | old => new)`; `useG8Mutation(fn, { optimistic: { prefix, update } })`
+  changes cached data before the request and puts it back if the write fails.
+- **Memory**: at most 200 keys (LRU); a key nobody watches is dropped after 5 minutes; requests abort when
+  their LAST subscriber unmounts.
+- **`placeholderData`**: show a list row while the full record loads (`isPlaceholderData: true`). Never seed
+  an edit form from it (edit-before-load PATCHes blanks over real values): enable Edit only when
+  `!isPlaceholderData && !loading`.
+- **SSR**: nothing is cached on the server; hooks render their initial state and fetch after hydration.
+- **Keys are JSON-like**: strings, numbers, booleans, null, arrays, plain objects and Dates. A `Map`, `Set`,
+  `URLSearchParams` or class instance throws (it would otherwise collide with every other one).
+- **Sign-out and org switch**: the cache is one per page and is not keyed by user or org. Call
+  `g8QueryCache.clear()` on sign-out or org switch, and add the org to your keys if you pass `targetOrgId`,
+  so one org's cached rows are never shown to another.
+
+Key convention used by the blocks: `[area, "list" | "detail" | <sub-resource>, ...inputs]`, area = the API
+path's first segment (`contacts`, `companies`, `deals`, `sequences`, `lists`, `inbox`, `tasks`...), so a write
+to an area invalidates that area with one prefix.
+
 ## Tiers: when to confirm
 
 Every operation has a tier (`read`, `write`, `billable`, `external`, `destructive`); each component's
@@ -62,6 +107,21 @@ The proxy therefore **refuses every request (500) until you configure it**:
 5. Local prototypes only: `dangerouslyAllowUnauthenticated: true` and `dangerouslyAllowAllPaths: true`
    switch the two gates off. Never ship them.
 
+### Local preview (apps made by `graph8-sdk create`)
+
+Created apps run before they have sign-in: the route sets `localPreview: true`. While `authorize` is unset the
+proxy answers a request only if NODE_ENV is not `production` AND it comes from this machine: Host is
+`localhost`, `127.0.0.1` or `[::1]` (blocks DNS rebinding), the browser's `Sec-Fetch-Site`/`Origin` say it is
+the app's own page (blocks other sites in the same browser), and no forwarding proxy names a remote client
+(blocks tunnels). `npm run dev` listens on 127.0.0.1, because a machine on your network could forge those
+headers. Other hosts get 403; a production build gets 500 until `authorize` is set. Once `authorize` is set,
+`localPreview` does nothing.
+
+The key comes from `G8_API_KEY` (env, `.env.local`) or, in local preview only, the key pasted in the
+Connect graph8 panel, which the server checks against `GET /me` and stores in `.g8/local-key` (0600, git-ignored).
+`npx @graph8/sdk doctor --production` fails until the route is safe to deploy;
+`npx @graph8/sdk doctor --fix-prefixes` regenerates `allowedPrefixes` after you add or remove blocks.
+
 What the proxy does on its own: rejects `..`, encoded slashes and empty segments (400); forwards only
 `content-type`, `accept`, `accept-language` and `idempotency-key` (never the browser's cookies or
 `Authorization`); strips hop-by-hop headers, `set-cookie` and `location` from the response; does not follow
@@ -91,6 +151,9 @@ for meaning, no entrance animations, light and dark through the tokens.
 | `Sparkline` | `sparkline` | Tiny SVG trend for tiles and cells. `data: number[]`, optional `tone`. |
 | `BarList` | `bar-list` | Ranked rows with a proportional ink bar; `href` makes a row a link. |
 | `TimeSeriesChart` | `time-series-chart` | `data`, `xKey`, `series: { key, label?, tone? }[]`, `kind` line, area, bar. Needs the `recharts` peer. `tone: "prior"` is the dashed comparison. |
+| `useRowActivation` | `hooks/use-row-activation` | `<TableRow {...rowActivationProps(() => open(row.id))}>` (inside `.map()`; `useRowActivation` is the hook form): the whole row is focusable, Enter/Space/click open it, nested checkboxes, buttons and links keep their own behaviour. Pass `{ role: "button" }` for a non-table row. |
+| `RecordLink` | `components/screen/record-link` | A record name as a real `<a href="?id=X">`: plain click opens in place (URL state), Cmd/Ctrl/middle-click opens a new tab on the same record. `full` adds `view=full`. |
+| `plural`, `pluralWord` | `lib/plural` | `plural(1, "contact")` -> "1 contact", `plural(3, "company", "companies")` -> "3 companies". Never hand-roll `=== 1 ? "" : "s"`. |
 | `useUrlState` | `hooks/use-url-state` | `const [id, setId] = useUrlState("id")`; `setId(null)` removes it; `{ push: true }` adds a history entry. |
 
 A finished list screen, start to end:
@@ -175,6 +238,20 @@ Rules the kit encodes, so screens stay consistent:
 - Loading is visible and distinct from empty: `StatStrip loading`, `Skeleton` rows.
 - Dates show short text; the full timestamp is the `title` of a `<time dateTime>`.
 
+## Long lists: paging, notices and filters (no silent truncation)
+
+A list read that sends a `limit` must page or say it stopped. The foundation ships the pieces:
+
+| Need | Use |
+|---|---|
+| Show rows with a "Load more" button (the API pages by `page` or `offset`) | `useLoadMoreList(byPage(size, read))` or `byOffset(size, read)` (`lib/paging.ts`), then `<LoadMore>` under the rows |
+| The API has only a `limit` (no paging) | `<FirstNotice shown={rows.length} limit={LIMIT} noun="mailboxes" />`: "Showing the first N ..." appears only when the read came back full |
+| A screen needs EVERY row (a lookup by id, a full dropdown) | `useAllPages(read, deps)`: reads page after page, reports `truncated` if the page cap cut it short |
+| Choose one audience list | crm's `ListSelect`: a native select with server search and "Load more lists" |
+| Filters for a list screen | `useUrlFilters(keys, { prefix })` keeps them in the URL (`c_email=...`); `TextFilter`, `SelectFilter`, `RangeFilter` and `MoreFilters` (a "More filters" disclosure) go in the Toolbar `filters` slot |
+
+`tests/blocks/list-paging-guard.test.ts` in the SDK repo fails on a new `g8Get(..., { limit })` read that does none of these.
+
 ## Prerequisites
 
 - `G8_API_KEY` in the server env; verify with `recipes/verify-proxy-key.ts`.

package/blocks/_foundation/block.json

@@ -7,10 +7,14 @@
     "browser-safe API calls via a server proxy",
     "query, mutation, pagination and job-polling hooks",
     "spend/send/delete confirmation dialog",
-    "screen kit: layout, stats, split view, detail panel, toolbar, status pills, avatars, cards, form sheet, charts"
+    "screen kit: layout, stats, split view, detail panel, toolbar, status pills, avatars, cards, form sheet, charts",
+    "local preview: a Connect graph8 screen stores the server's key for `next dev`; generated allowedPrefixes",
+    "white-label: BrandProvider + useBrand give every block's copy and link-outs your platform name and app URL (default graph8)"
   ],
   "dependsOn": [],
-  "operations": [],
+  "operations": [
+    "describe_current_key_me_get"
+  ],
   "components": [
     {
       "name": "ConfirmSpendDialog",
@@ -19,6 +23,13 @@
       "operations": [],
       "tiers": []
     },
+    {
+      "name": "AskButton",
+      "file": "components/confirmed-action.tsx",
+      "purpose": "useConfirmAction + AskButton: a button asks, one ConfirmSpendDialog per screen confirms, then the write runs (Cancel is ignored while it runs).",
+      "operations": [],
+      "tiers": []
+    },
     {
       "name": "ApiError",
       "file": "components/api-error.tsx",
@@ -123,23 +134,65 @@
       "purpose": "Line, area or bar chart over time on recharts: ink series, tones only for meaning, dashed prior period, hairline grid.",
       "operations": [],
       "tiers": []
+    },
+    {
+      "name": "RecordLink",
+      "file": "components/screen/record-link.tsx",
+      "purpose": "A record's name as a real <a href=\"?id=X\">: a plain click opens it in place (URL state), Cmd/Ctrl/middle-click opens a new tab on the same record.",
+      "operations": [],
+      "tiers": []
+    },
+    {
+      "name": "ConnectGraph8Panel",
+      "file": "components/connect-graph8.tsx",
+      "purpose": "Local preview only: paste a graph8 API key, the server checks it (GET /me) and stores it in .g8/local-key, never in the browser; replace or remove it. G8ConnectGate shows it until a key is connected and is a no-op in production.",
+      "operations": [],
+      "tiers": []
+    },
+    {
+      "name": "BrandProvider",
+      "file": "components/brand-provider.tsx",
+      "purpose": "White-label context: the app's name, logo, and what the platform is called and where it lives, for every block's copy and link-outs. Fields left out stay graph8's.",
+      "operations": [],
+      "tiers": []
+    },
+    {
+      "name": "ListSelect",
+      "file": "components/list-select.tsx",
+      "purpose": "Audience-list dropdown, searchable and paged (native select + server search + Load more). It owns no API call: the block that uses it passes a `read` (crm ships ListSelect with the /lists read wired in).",
+      "operations": [],
+      "tiers": []
+    },
+    {
+      "name": "FirstNotice",
+      "file": "components/paging-notices.tsx",
+      "purpose": "FirstNotice (\"Showing the first N ...\" when a read without paging came back full) and LoadMore (\"Showing N\" + Load more): the two honest endings of a capped list.",
+      "operations": [],
+      "tiers": []
+    },
+    {
+      "name": "TextFilter",
+      "file": "components/screen/filter-controls.tsx",
+      "purpose": "Toolbar filter controls: TextFilter, SelectFilter, RangeFilter (from/to) and MoreFilters (a disclosure that opens by itself when a hidden filter is set).",
+      "operations": [],
+      "tiers": []
     }
   ],
   "hooks": [
     {
       "name": "useG8Query",
       "file": "hooks/use-g8-query.ts",
-      "purpose": "Load data with loading/error/data, an out-of-order guard and refetch."
+      "purpose": "Load data with loading/error/data, an out-of-order guard and refetch. Optional `key` joins the shared cache (dedupe, stale-while-revalidate, focus refresh, invalidation)."
     },
     {
       "name": "useG8Mutation",
       "file": "hooks/use-g8-mutation.ts",
-      "purpose": "Run a write with loading/error state and success/error callbacks."
+      "purpose": "Run a write with loading/error state and success/error callbacks. Optional `invalidates` refreshes cached keys; optional `optimistic` update with rollback."
     },
     {
       "name": "usePaginated",
       "file": "hooks/use-paginated.ts",
-      "purpose": "Cursor pagination over the API envelope (pagination.next_cursor) with load-more and reload."
+      "purpose": "Cursor pagination over the API envelope (pagination.next_cursor) with load-more and reload. Optional `key` caches the loaded pages."
     },
     {
       "name": "useJobPoll",
@@ -150,6 +203,31 @@
       "name": "useUrlState",
       "file": "hooks/use-url-state.ts",
       "purpose": "One string in the URL query as state (replaceState + popstate, SSR-safe, no next/navigation): the open record, tab or search survives reload and Back."
+    },
+    {
+      "name": "useRowActivation",
+      "file": "hooks/use-row-activation.ts",
+      "purpose": "Props that make a whole list row focusable and openable with Enter/Space and click, leaving nested checkboxes, buttons and links alone. rowActivationProps is the same as a plain function for use inside .map()."
+    },
+    {
+      "name": "useBrand",
+      "file": "hooks/use-brand.ts",
+      "purpose": "The current brand ({ name, appUrl, linkLabel, logo }) from the nearest BrandProvider, else graph8's defaults; brandUrl(brand, path) builds a link-out."
+    },
+    {
+      "name": "useAllPages",
+      "file": "hooks/use-all-pages.ts",
+      "purpose": "Read every page of a list a screen needs in full (lookups, full dropdowns), up to a page cap, and report when the cap cut it short."
+    },
+    {
+      "name": "useLoadMoreList",
+      "file": "hooks/use-load-more-list.ts",
+      "purpose": "A list read with Load more: the shape of a useG8Query list (data, loading, error, refetch) plus hasMore / loadMore. Pair with byPage / byOffset and the LoadMore notice."
+    },
+    {
+      "name": "useUrlFilters",
+      "file": "hooks/use-url-filters.ts",
+      "purpose": "List-screen filters kept in the URL (debounced, prefixed, SSR-safe): draft for the inputs, query for the read, clear()."
     }
   ],
   "lib": [
@@ -157,9 +235,33 @@
       "file": "lib/g8-client.ts",
       "purpose": "Browser caller for the app's own /api/g8 proxy. Holds no key, returns the SDK envelope, throws G8Error."
     },
+    {
+      "file": "components/screen/time-series-chart-recharts.tsx",
+      "purpose": "The recharts implementation of TimeSeriesChart, code-split: TimeSeriesChart loads it on first render, so pages without a chart never download recharts."
+    },
+    {
+      "file": "components/screen/time-series-format.ts",
+      "purpose": "TimeSeriesChart props, series type and axis formatters (defaultFormatX/defaultFormatY), with no recharts import."
+    },
+    {
+      "file": "lib/g8-cache.ts",
+      "purpose": "Shared query cache behind the hooks' optional `key`: one in-flight request per key, stale-while-revalidate, focus/reconnect refresh, invalidate(prefix), setQueryData, optimistic writes, bounded LRU (200) with GC."
+    },
     {
       "file": "components/screen/index.ts",
       "purpose": "Barrel for the screen kit: import every part from @/g8/components/screen."
+    },
+    {
+      "file": "lib/plural.ts",
+      "purpose": "plural(n, 'contact') -> '1 contact' / '2 contacts' (and pluralWord): one correct plural helper for titles, counts and bulk dialogs."
+    },
+    {
+      "file": "lib/paging.ts",
+      "purpose": "byPage / byOffset adapt page-number and offset lists to usePaginated's cursor shape; hasNextOf reads the API's has_next / next_cursor."
+    },
+    {
+      "file": "lib/use-debounced-value.ts",
+      "purpose": "useDebounced: a value after it stopped changing (foundation-local copy)."
     }
   ],
   "server": [
@@ -168,10 +270,25 @@
       "purpose": "createG8Proxy(): forwards browser calls to the graph8 API with the server-side key, a required path allowlist and authorize hook (it refuses to run without them) and a server-side org hook.",
       "target": "g8/server/proxy.ts"
     },
+    {
+      "file": "server/local-key.ts",
+      "purpose": "Node only: the local-preview key file (.g8/local-key, 0600, self-gitignored) and resolveApiKey() (environment first, then the file outside production).",
+      "target": "g8/server/local-key.ts"
+    },
+    {
+      "file": "server/connect.ts",
+      "purpose": "createG8ConnectRoute(): GET status, POST a key (checked with GET /me), DELETE it; answers only next dev requests from this machine, 404 in production.",
+      "target": "g8/server/connect.ts"
+    },
     {
       "file": "server/route.ts",
       "purpose": "The Next.js App Router catch-all route that mounts the proxy.",
       "target": "app/api/g8/[...path]/route.ts"
+    },
+    {
+      "file": "server/connect-route.ts",
+      "purpose": "The Next.js route behind the Connect graph8 screen.",
+      "target": "app/api/g8-connect/route.ts"
     }
   ],
   "recipes": [
@@ -210,7 +327,7 @@
     },
     {
       "decision": "How the proxy knows the caller is a signed-in user of the app",
-      "default": "None: the route refuses every request until `authorize` is set",
+      "default": "Local preview: until `authorize` is set the route answers only `next dev` requests from this machine; a production build refuses every request until `authorize` is set",
       "askHuman": true
     },
     {

package/blocks/_foundation/components/api-error.tsx

@@ -1,8 +1,9 @@
 "use client";
 
-import { G8Error } from "@graph8/sdk";
+import { G8Error } from "@graph8/sdk/errors";
 import { CircleAlert } from "lucide-react";
 import { Button, cn } from "@graph8/sdk/ui";
+import { DEFAULT_BRAND, useBrand } from "../hooks/use-brand";
 
 export interface ApiErrorProps {
   error: unknown;
@@ -23,22 +24,22 @@ interface FieldError {
 }
 
 /** A readable one-line reason for any thrown value. 422 field errors are listed. */
-export function describeError(error: unknown): { message: string; fields: string[]; status?: number; requestId?: string } {
+export function describeError(error: unknown, platform: string = DEFAULT_BRAND.linkLabel): { message: string; fields: string[]; status?: number; requestId?: string } {
   if (error instanceof G8Error) {
     const fields = Array.isArray(error.detail)
       ? (error.detail as FieldError[]).map((f) => `${(f.loc ?? []).filter((p) => p !== "body").join(".")}: ${f.msg ?? ""}`.trim())
       : [];
     const message =
-      typeof error.detail === "string" ? error.detail : fields.length ? "Some fields are invalid." : explain(error);
+      typeof error.detail === "string" ? error.detail : fields.length ? "Some fields are invalid." : explain(error, platform);
     return { message, fields, status: error.status, requestId: error.requestId };
   }
   return { message: error instanceof Error ? error.message : "Something went wrong.", fields: [] };
 }
 
-function explain(error: G8Error): string {
-  if (error.status === 401) return "Your session with graph8 is not valid. Check the server API key.";
+function explain(error: G8Error, platform: string): string {
+  if (error.status === 401) return `Your session with ${platform} is not valid. Check the server API key.`;
   if (error.status === 403) return "This API key is not allowed to do that (missing scope, or the proxy blocked the path).";
-  if (error.status === 429) return "graph8 is rate limiting requests. Wait a moment and retry.";
+  if (error.status === 429) return `${platform} is rate limiting requests. Wait a moment and retry.`;
   if (error.status === 0) return "Could not reach the server. Check your connection.";
   return error.message;
 }
@@ -48,8 +49,9 @@ function explain(error: G8Error): string {
  * is an error with Retry, never an empty list. Ember is reserved for this: errors and alerts.
  */
 export function ApiError({ error, title = "Something went wrong", onRetry, className, compact, retryLabel = "Retry", actions }: ApiErrorProps) {
+  const brand = useBrand();
   if (error == null) return null;
-  const info = describeError(error);
+  const info = describeError(error, brand.linkLabel);
 
   if (compact) {
     return (

package/blocks/_foundation/components/brand-provider.tsx

@@ -0,0 +1,23 @@
+"use client";
+
+/**
+ * Wraps the app so every block shows YOUR brand: the platform's name in copy and link-outs, and where those links
+ * go. A created app renders it in components/app-shell.tsx from `g8.config.ts`:
+ *
+ *   <BrandProvider brand={brand}>{children}</BrandProvider>
+ *
+ * Fields left out keep graph8's defaults (see hooks/use-brand.ts). No API calls.
+ */
+
+import { useMemo, type ReactNode } from "react";
+import { BrandContext, resolveBrand, type BrandConfig } from "../hooks/use-brand";
+
+export interface BrandProviderProps {
+  brand?: Partial<BrandConfig> | null;
+  children: ReactNode;
+}
+
+export function BrandProvider({ brand, children }: BrandProviderProps) {
+  const value = useMemo(() => resolveBrand(brand), [brand?.name, brand?.appUrl, brand?.linkLabel, brand?.logo]); // eslint-disable-line react-hooks/exhaustive-deps
+  return <BrandContext.Provider value={value}>{children}</BrandContext.Provider>;
+}

package/blocks/_foundation/components/confirm-spend-dialog.tsx

@@ -39,6 +39,13 @@ const TIER_COPY: Record<ConfirmTier, { badge: string; confirm: string; note: str
 };
 
 /** True for the tiers an app should confirm before calling. read/write never need it. */
+/** The tier badge: ember for what cannot be undone, ochre for spend and outreach. Token classes only. */
+const TIER_BADGE: Record<ConfirmTier, string> = {
+  billable: "bg-warning text-warning-foreground",
+  external: "bg-warning text-warning-foreground",
+  destructive: "bg-error text-error-foreground",
+};
+
 export function tierRequiresConfirmation(tier: string): tier is ConfirmTier {
   return tier === "billable" || tier === "external" || tier === "destructive";
 }
@@ -83,7 +90,7 @@ export function ConfirmSpendDialog(props: ConfirmSpendDialogProps) {
         showCloseButton={false}
         data-tier={tier}
         style={interactive}
-        className={`max-w-md sm:max-w-md bg-white p-5 shadow-xl ${props.className ?? ""}`}
+        className={`max-w-md gap-4 border-border bg-background p-5 shadow-xl sm:max-w-md ${props.className ?? ""}`}
         onOpenAutoFocus={(event) => {
           event.preventDefault();
           openerRef.current = document.activeElement instanceof HTMLElement ? document.activeElement : null;
@@ -98,15 +105,15 @@ export function ConfirmSpendDialog(props: ConfirmSpendDialogProps) {
         onInteractOutside={(event) => event.preventDefault()}
         onEscapeKeyDown={(event) => confirming && event.preventDefault()}
       >
-        <span className="inline-block w-fit rounded bg-gray-100 px-2 py-0.5 text-xs font-medium text-gray-700">
+        <span className={`inline-flex h-5 w-fit items-center rounded-full px-2 text-[11px] font-medium leading-none ${TIER_BADGE[tier]}`}>
           {copy.badge}
         </span>
-        <DialogTitle className="text-base font-semibold text-gray-900">{title}</DialogTitle>
+        <DialogTitle className="text-base font-medium leading-6 text-foreground">{title}</DialogTitle>
         <DialogDescription asChild>
-          <div className="space-y-2 text-sm text-gray-600">
+          <div className="space-y-2 text-sm leading-5 text-muted-foreground">
             {description ? <div>{description}</div> : null}
             {summary.length > 0 ? (
-              <ul className="list-disc pl-5 text-gray-900">
+              <ul className="list-disc space-y-0.5 pl-5 tabular-nums text-foreground">
                 {summary.map((line) => (
                   <li key={line}>{line}</li>
                 ))}
@@ -115,14 +122,14 @@ export function ConfirmSpendDialog(props: ConfirmSpendDialogProps) {
             <p>{copy.note}</p>
           </div>
         </DialogDescription>
-        <div className="flex justify-end gap-2">
+        <div className="flex justify-end gap-2 pt-1">
           <button
             ref={cancelRef}
             type="button"
             disabled={confirming}
             onClick={onCancel}
             style={interactive}
-            className="rounded border border-gray-300 px-3 py-1.5 text-sm text-gray-700 disabled:opacity-50"
+            className="inline-flex h-8 items-center rounded-md border border-border bg-background px-3 text-sm font-medium text-foreground transition-colors hover:bg-surface-hover focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring disabled:opacity-50"
           >
             {props.cancelLabel ?? "Cancel"}
           </button>
@@ -131,7 +138,7 @@ export function ConfirmSpendDialog(props: ConfirmSpendDialogProps) {
             disabled={confirming}
             onClick={onConfirm}
             style={interactive}
-            className="rounded bg-gray-900 px-3 py-1.5 text-sm font-medium text-white disabled:opacity-50"
+            className={`inline-flex h-8 items-center rounded-md px-3 text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background disabled:opacity-50 ${tier === "destructive" ? "bg-destructive text-destructive-foreground hover:bg-destructive/90" : "bg-primary text-primary-foreground hover:bg-primary/90"}`}
           >
             {confirming ? "Working..." : (props.confirmLabel ?? copy.confirm)}
           </button>

package/blocks/_foundation/components/confirmed-action.tsx

@@ -0,0 +1,90 @@
+"use client";
+
+/**
+ * useConfirmAction + AskButton (foundation, shared by every block's record detail): the pattern detail screens use for every write. A button calls `ask(config)`; the screen
+ * renders ONE `<ConfirmSpendDialog {...dialog} />` (so the confirmation is visible in the screen's own source), the person confirms,
+ * then `config.run()` executes and the failure, if any, is shown in `failure`.
+ *
+ * SDK operations: none of its own; `run` is whatever the caller passes. `tolerateStatus` lists HTTP statuses that count as done
+ * (a delete answering 404); `mapError` can turn a thrown error into a clearer one (return null to treat it as done).
+ */
+import { useState } from "react";
+import type { ReactNode } from "react";
+import { Button } from "@graph8/sdk/ui";
+import type { ConfirmTier } from "@/g8/components/confirm-spend-dialog";
+
+export interface ConfirmActionConfig {
+  tier: ConfirmTier;
+  title: string;
+  description?: ReactNode;
+  confirmLabel?: string;
+  estimatedCredits?: number;
+  recipients?: number;
+  affected?: number;
+  tolerateStatus?: number[];
+  mapError?: (error: unknown) => unknown;
+  run: () => Promise<unknown>;
+  onDone?: () => void;
+}
+
+export interface AskButtonProps extends ConfirmActionConfig {
+  ask: (config: ConfirmActionConfig) => void;
+  label: string;
+  variant?: "default" | "outline" | "ghost";
+  disabled?: boolean;
+}
+
+export function useConfirmAction() {
+  const [cfg, setCfg] = useState<ConfirmActionConfig | null>(null);
+  const [busy, setBusy] = useState(false);
+  const [failure, setFailure] = useState<unknown>(null);
+
+  const go = async () => {
+    if (!cfg) return;
+    setBusy(true);
+    setFailure(null);
+    try {
+      await cfg.run();
+      cfg.onDone?.();
+    } catch (err) {
+      const status = (err as { status?: number })?.status;
+      if (status != null && cfg.tolerateStatus?.includes(status)) cfg.onDone?.();
+      else {
+        const shown = cfg.mapError ? cfg.mapError(err) : err;
+        if (shown == null) cfg.onDone?.();
+        else setFailure(shown);
+      }
+    } finally {
+      setBusy(false);
+      setCfg(null);
+    }
+  };
+
+  return {
+    ask: (config: ConfirmActionConfig) => setCfg(config),
+    busy,
+    failure,
+    dialog: {
+      open: cfg != null,
+      tier: cfg?.tier ?? ("external" as ConfirmTier),
+      title: cfg?.title ?? "",
+      description: cfg?.description,
+      estimatedCredits: cfg?.estimatedCredits,
+      recipients: cfg?.recipients,
+      affected: cfg?.affected,
+      confirmLabel: cfg?.confirmLabel,
+      confirming: busy,
+      onConfirm: () => void go(),
+      // While the write is running, Cancel does nothing: closing then would hide a write that still lands.
+      onCancel: () => { if (!busy) setCfg(null); },
+    },
+  };
+}
+
+export function AskButton({ ask, label, variant = "outline", disabled, ...config }: AskButtonProps) {
+  return (
+    <Button size="sm" variant={variant} disabled={disabled} onClick={() => ask({ confirmLabel: label, ...config })}>
+      {label}
+    </Button>
+  );
+}