@graph8/sdk 0.361.0 → 0.370.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,15 +496,19 @@ 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.
 

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`. |
@@ -16,6 +18,9 @@ Shared base every other block depends on. Install it first (the CLI does it for
 | `components/confirm-spend-dialog.tsx` | `ConfirmSpendDialog`: shows tier, estimated credits, recipients, before a billable/external/destructive call. |
 | `components/api-error.tsx` | `ApiError`: shows `detail`, 422 field errors, request id, retry. |
 | `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
 
@@ -28,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
@@ -60,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
@@ -67,6 +129,115 @@ redirects (an upstream 3xx becomes a 502); caps the request body at 5 MiB (413),
 an oversized upload is never held whole in memory; returns 500 with a clear message if `G8_API_KEY` is unset
 and a generic 502 if graph8 is unreachable. The key is never logged, echoed or included in any response.
 
+## Screen kit
+
+Finished screens (`<Name>Screen` in every block) are composed from these parts, so an Apollo clone and a
+HubSpot clone look like one product. Import each part from `@/g8/components/screen/<file>` (or everything
+from `@/g8/components/screen`). The look follows graph8's rules: ink on white, calm density, colour only
+for meaning, no entrance animations, light and dark through the tokens.
+
+| Part | File | Use it for |
+|---|---|---|
+| `ScreenLayout` | `screen-layout` | The frame: sticky header (icon, title, description, actions, underline `tabs`), `stats`, `toolbar`, content. One per route. |
+| `StatStrip` | `stat-strip` | KPI tiles. `StatItem = { label, value, delta?, hint?, tone?, sparkline?, footer?, onClick? }`. Numbers are ink; a delta takes colour only through `tone`. |
+| `SplitView` | `split-view` | `list` beside the selected record (`detail`), `detailWidth` md, lg, xl. Under 1024px the detail is a right sheet. `expanded` + `onExpandedChange` make it a full-page record screen with a Back affordance. |
+| `DetailPanel` | `detail-panel` | The record: sticky header (avatar, title, subtitle, badges, actions, close) + `tabs: { id, label, content, count? }[]` or children. `onExpand` shows "Open full page"; `onCollapse` shows "Back to split view". |
+| `Toolbar` | `toolbar` | Debounced `search` (Enter flushes, Escape clears), `filters`, right-aligned `actions`, `status` (polite result count), a chips row as children. |
+| `StatusPill` | `status-pill` | `tone`: neutral, info, positive, warning, negative. `toneForStatus(raw)` maps API states; unknown is warning, never positive. `humanizeStatus`. |
+| `EntityAvatar` | `entity-avatar` | `kind` person (circle, initials) or company (rounded square, letter); `size` sm, md, lg; `imageUrl`. |
+| `SectionCard` | `section-card` | A flat, hairlined section: title, description, actions, body (`flush` for tables), footer. |
+| `FormSheet` | `form-sheet` | Create/edit sheet: `title`, `description`, fields as children, `footer` (Cancel, then the primary), `onSubmit` wraps the body in a form. |
+| `KeyValueList` | `key-value-list` | Facts about a record, `columns` 1 or 2, `inline` for dense rows. A missing value is a faint dash. |
+| `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:
+
+```tsx
+"use client";
+import { Users, Plus } from "lucide-react";
+import { Button } from "@graph8/sdk/ui";
+import { ScreenLayout } from "@/g8/components/screen/screen-layout";
+import { Toolbar } from "@/g8/components/screen/toolbar";
+import { SplitView } from "@/g8/components/screen/split-view";
+import { DetailPanel } from "@/g8/components/screen/detail-panel";
+import { EntityAvatar } from "@/g8/components/screen/entity-avatar";
+import { StatusPill, toneForStatus, humanizeStatus } from "@/g8/components/screen/status-pill";
+import { KeyValueList } from "@/g8/components/screen/key-value-list";
+import { SectionCard } from "@/g8/components/screen/section-card";
+import { FormSheet } from "@/g8/components/screen/form-sheet";
+import { useUrlState } from "@/g8/hooks/use-url-state";
+
+export function ContactsScreen() {
+  const [q, setQ] = useUrlState("q");
+  const [id, setId] = useUrlState("id");
+  const [creating, setCreating] = useUrlState("new");
+  const [view, setView] = useUrlState("view"); // "full" = the record as a full page (?id=X&view=full)
+  const contacts = useContacts(q); // your block's hook; { data, loading, error, refetch }
+  const open = contacts.data?.find((c) => c.id === id);
+
+  return (
+    <ScreenLayout
+      title="Contacts"
+      description="Everyone your team is working"
+      icon={<Users />}
+      stats={[{ label: "Contacts", value: contacts.total ?? "-" }, { label: "Replied this week", value: 12, delta: 8, tone: "positive" }]}
+      actions={<Button onClick={() => setCreating("1")}><Plus />Add contact</Button>}
+      toolbar={<Toolbar search={{ value: q, onChange: setQ, placeholder: "Search contacts" }} status={contacts.total != null ? `${contacts.total} contacts` : undefined} />}
+      fill
+    >
+      <SplitView
+        detailOpen={!!open}
+        onCloseDetail={() => { setId(null); setView(null); }}
+        expanded={view === "full"}
+        onExpandedChange={(full) => setView(full ? "full" : null)}
+        list={<ContactTable rows={contacts.data} selectedId={id} onOpen={(c) => setId(c.id)} />}
+        detail={open ? (
+          <DetailPanel
+            title={open.name}
+            subtitle={open.title}
+            avatar={<EntityAvatar name={open.name} imageUrl={open.avatar_url} size="lg" />}
+            badges={<StatusPill tone={toneForStatus(open.status)} dot>{humanizeStatus(open.status)}</StatusPill>}
+            onClose={() => { setId(null); setView(null); }}
+            onExpand={view === "full" ? undefined : () => setView("full")}
+            onCollapse={view === "full" ? () => setView(null) : undefined}
+            tabs={[
+              { id: "overview", label: "Overview", content: (
+                <SectionCard title="Details">
+                  <KeyValueList columns={2} items={[{ label: "Email", value: open.email }, { label: "Phone", value: open.phone }]} />
+                </SectionCard>
+              ) },
+              { id: "activity", label: "Activity", content: <ActivityFeed contactId={open.id} /> },
+            ]}
+          />
+        ) : null}
+      />
+      <FormSheet open={!!creating} onOpenChange={(o) => setCreating(o ? "1" : null)} title="Add contact" onSubmit={submit}
+        footer={<><Button variant="outline" type="button" onClick={() => setCreating(null)}>Cancel</Button><Button type="submit">Add contact</Button></>}>
+        {/* fields */}
+      </FormSheet>
+    </ScreenLayout>
+  );
+}
+```
+
+Rules the kit encodes, so screens stay consistent:
+
+- The URL owns the open record, the tab and the search (`useUrlState`): reload and Back work, links are shareable.
+- Every record has a full-page view, not only a side panel: `?id=X&view=full` opens it (SplitView `expanded`), and
+  the panel's "Open full page" button gets there. Back returns to the split view with the list.
+- One primary action per screen, last on the right. Bulk actions appear on selection. Edits autosave where possible.
+- Colour means good or bad for the user: `tone` on deltas, pills and series; everything else is ink.
+- An unknown status is a warning pill with the humanized value, never a green "Active".
+- A failed load is `ApiError` with Retry, never an empty list; an empty list is `EmptyState` with the first step.
+- 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>`.
+
 ## Prerequisites
 
 - `G8_API_KEY` in the server env; verify with `recipes/verify-proxy-key.ts`.

package/blocks/_foundation/block.json

@@ -3,9 +3,18 @@
   "id": "foundation",
   "title": "Foundation",
   "summary": "Shared base for every block: browser client, data hooks, Next.js proxy route, confirm/error/empty components.",
-  "features": ["browser-safe API calls via a server proxy", "query, mutation, pagination and job-polling hooks", "spend/send/delete confirmation dialog"],
+  "features": [
+    "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",
+    "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",
@@ -14,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",
@@ -27,20 +43,209 @@
       "purpose": "Empty-list placeholder with a title, hint and an optional first-step action.",
       "operations": [],
       "tiers": []
+    },
+    {
+      "name": "ScreenLayout",
+      "file": "components/screen/screen-layout.tsx",
+      "purpose": "Frame of a finished screen: sticky header (icon, title, description, actions, underline tabs), StatStrip, toolbar, content.",
+      "operations": [],
+      "tiers": []
+    },
+    {
+      "name": "StatStrip",
+      "file": "components/screen/stat-strip.tsx",
+      "purpose": "Row of KPI tiles: label, value, delta (coloured only through tone), hint tooltip, sparkline, skeleton while loading.",
+      "operations": [],
+      "tiers": []
+    },
+    {
+      "name": "SplitView",
+      "file": "components/screen/split-view.tsx",
+      "purpose": "List beside the selected record; the detail pane becomes a right Sheet under 1024px.",
+      "operations": [],
+      "tiers": []
+    },
+    {
+      "name": "DetailPanel",
+      "file": "components/screen/detail-panel.tsx",
+      "purpose": "The selected record: sticky header (avatar, title, subtitle, badges, actions, close) and underline tabs or plain children.",
+      "operations": [],
+      "tiers": []
+    },
+    {
+      "name": "Toolbar",
+      "file": "components/screen/toolbar.tsx",
+      "purpose": "The row above a list: debounced search (Enter flushes, Escape clears), filters, right-aligned actions, an optional chips row.",
+      "operations": [],
+      "tiers": []
+    },
+    {
+      "name": "StatusPill",
+      "file": "components/screen/status-pill.tsx",
+      "purpose": "State badge with a tone (neutral, info, positive, warning, negative); toneForStatus maps raw API states, unknown ones to warning.",
+      "operations": [],
+      "tiers": []
+    },
+    {
+      "name": "EntityAvatar",
+      "file": "components/screen/entity-avatar.tsx",
+      "purpose": "Person (circle, initials) or company (rounded square, first letter) avatar in three sizes, with an image when there is one.",
+      "operations": [],
+      "tiers": []
+    },
+    {
+      "name": "SectionCard",
+      "file": "components/screen/section-card.tsx",
+      "purpose": "Flat hairlined section with a title row (title, description, actions) and a body; cards cast no shadow.",
+      "operations": [],
+      "tiers": []
+    },
+    {
+      "name": "FormSheet",
+      "file": "components/screen/form-sheet.tsx",
+      "purpose": "Create/edit side sheet: header, scrolling fields, sticky footer; optional onSubmit wraps the body in a form.",
+      "operations": [],
+      "tiers": []
+    },
+    {
+      "name": "KeyValueList",
+      "file": "components/screen/key-value-list.tsx",
+      "purpose": "Labelled facts about a record in one or two columns; a missing value is a faint dash.",
+      "operations": [],
+      "tiers": []
+    },
+    {
+      "name": "Sparkline",
+      "file": "components/screen/sparkline.tsx",
+      "purpose": "Tiny inline SVG trend (ink line, 6% area) for stat tiles and cells; no chart library.",
+      "operations": [],
+      "tiers": []
+    },
+    {
+      "name": "BarList",
+      "file": "components/screen/bar-list.tsx",
+      "purpose": "Ranked rows with a proportional ink bar and a right-aligned value; rows can be links.",
+      "operations": [],
+      "tiers": []
+    },
+    {
+      "name": "TimeSeriesChart",
+      "file": "components/screen/time-series-chart.tsx",
+      "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": []
     }
   ],
   "hooks": [
-    { "name": "useG8Query", "file": "hooks/use-g8-query.ts", "purpose": "Load data with loading/error/data, an out-of-order guard and refetch." },
-    { "name": "useG8Mutation", "file": "hooks/use-g8-mutation.ts", "purpose": "Run a write with loading/error state and success/error callbacks." },
-    { "name": "usePaginated", "file": "hooks/use-paginated.ts", "purpose": "Cursor pagination over the API envelope (pagination.next_cursor) with load-more and reload." },
-    { "name": "useJobPoll", "file": "hooks/use-job-poll.ts", "purpose": "Poll a job-status fetcher with backoff until a terminal state (the API has no streams)." }
+    {
+      "name": "useG8Query",
+      "file": "hooks/use-g8-query.ts",
+      "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. 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. Optional `key` caches the loaded pages."
+    },
+    {
+      "name": "useJobPoll",
+      "file": "hooks/use-job-poll.ts",
+      "purpose": "Poll a job-status fetcher with backoff until a terminal state (the API has no streams)."
+    },
+    {
+      "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."
+    }
   ],
   "lib": [
-    { "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": "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."
+    }
   ],
   "server": [
-    { "file": "server/proxy.ts", "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/route.ts", "purpose": "The Next.js App Router catch-all route that mounts the proxy.", "target": "app/api/g8/[...path]/route.ts" }
+    {
+      "file": "server/proxy.ts",
+      "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": [
     {
@@ -71,9 +276,25 @@
   ],
   "scopes": [],
   "defaults": [
-    { "decision": "Which API paths the browser may call through the proxy", "default": "Only the areas the installed blocks use (allowedPrefixes, required), not all of /api/v1", "askHuman": false },
-    { "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", "askHuman": true },
-    { "decision": "Styling", "default": "Tailwind utility classes on plain elements; overlays (ConfirmSpendDialog) and later blocks use @graph8/sdk/ui, so import its CSS", "askHuman": false }
+    {
+      "decision": "Which API paths the browser may call through the proxy",
+      "default": "Only the areas the installed blocks use (allowedPrefixes, required), not all of /api/v1",
+      "askHuman": false
+    },
+    {
+      "decision": "How the proxy knows the caller is a signed-in user of the app",
+      "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
+    },
+    {
+      "decision": "Styling",
+      "default": "Tailwind utility classes on plain elements; overlays (ConfirmSpendDialog) and later blocks use @graph8/sdk/ui, so import its CSS",
+      "askHuman": false
+    }
   ],
-  "peerDependencies": { "react": ">=18" }
+  "peerDependencies": {
+    "react": ">=18",
+    "lucide-react": ">=0.400.0",
+    "recharts": "^2.15.0 || ^3.0.0"
+  }
 }