@ekanos/sdk 0.1.1 → 0.1.3

package/README.md

@@ -1,6 +1,42 @@
 # @ekanos/sdk
 
-The official SDK for building Ekanos integrations.
+The official SDK for building Ekanos integrations — the packages that add
+widgets, assistant tools, and event handlers to a Fusion dashboard.
+
+**Start here.** This README is the complete authoring reference: everything you
+can declare, with a worked example for each surface. There is no separate docs
+site — if something is missing here it is missing, and `npm@govastly.com` is
+where to say so.
+
+The other packages, so you know when to leave this page: **`@ekanos/cli`** is
+the toolchain (`init`, `validate`, `dev`, `test`) and owns `ekanos.json`;
+**`@ekanos/harness`** is the local dev harness that renders your surfaces in
+real Fusion chrome; **`@ekanos/ui`** is the component library; and
+**`@ekanos/integration-schema`** is the validation contract underneath this
+one. Each has its own README.
+
+- [Install](#install)
+- [The shape of an integration](#the-shape-of-an-integration)
+- [The capability context (`ctx`)](#the-capability-context-ctx)
+- **Declarable surfaces**
+  - [`storage` — schema-validated per-account state](#storage)
+  - [`egress` — the outbound allowlist](#egress)
+  - [Secrets](#secrets)
+  - [`tools` — assistant / MCP tools](#tools)
+  - [`components.widgets` — dashboard widgets](#componentswidgets)
+  - [`components.marketplaceTile`](#componentsmarketplacetile)
+  - [`components.activationForm`](#componentsactivationform)
+  - [`capabilities` and `permissions`](#capabilities-and-permissions)
+  - [`webhooks`](#webhooks)
+  - [`schedules`](#schedules)
+  - [`oauth`](#oauth)
+  - [`proposes` — what you suggest, the host decides](#proposes)
+  - [`workspaceTargets`](#workspacetargets)
+- [Testing](#testing)
+- [Entrypoints](#entrypoints)
+- [Naming and validation rules, in one table](#naming-and-validation-rules-in-one-table)
+- [Rough edges we know about](#rough-edges-we-know-about)
+- [Publish pipeline](#publish-pipeline)
 
 ## Install
 
@@ -9,23 +45,182 @@ npm install @ekanos/sdk
 ```
 
 `@ekanos/integration-schema` and `@ekanos/ui` come along as dependencies. You
-provide the peers: `react` (^19.2.8), `zod` (^3.25.76), and — if you render
-widgets or an activation form — `@tanstack/react-query` (^5.101.4),
-`react-hook-form` (^7.68.0), `@hookform/resolvers` (^5.2.2), and `next`
-(^16.0.0).
+provide six peers, and **all six are declared as required** — none is marked
+optional, so your package manager expects every one of them even if your
+integration only ships tools:
+
+| Peer | Version | What actually uses it |
+|---|---|---|
+| `react` | ^19.2.8 | everything client-side |
+| `zod` | ^3.25.76 | storage schemas, webhook payload schemas, the definition parse |
+| `@tanstack/react-query` | ^5.101.4 | widget data hooks, and the SDK's own `useActivateIntegration` / `useOAuthConnectionStatus` |
+| `react-hook-form` | ^7.68.0 | activation forms |
+| `@hookform/resolvers` | ^5.2.2 | zod validation in activation forms |
+| `next` | ^16.0.0 | the host's routing primitives the components reach for |
+
+The right-hand column is why each is there, not permission to skip it: leave
+one out and you get peer warnings on install regardless of what you render.
+
+**Why peers and not dependencies:** every one of these creates React context,
+and two copies of a context-creating module is a bug that does not announce
+itself. A provider renders against instance A while a consumer three files away
+reads instance B, finds nothing, and silently falls back to a default. As
+peers, your package manager gives everyone one copy; as dependencies, npm is
+free to give you two.
+
+This is not hypothetical, and it does not require two installs to happen —
+bundling reaches it just as easily. `@ekanos/ui` shipped a version where five
+built entries each inlined their own copy of the icon module, and so each got
+its own `createContext()`. A consumer's `IconStyleOverrideProvider` set one
+instance; the chevron inside the select entry read another, found no provider,
+and fell back to a Font Awesome Pro weight that Free defines no glyph for.
+Three of five icons rendered as `□`. The monorepo could not reproduce it at all
+— it resolves from source, where one module means one context — so it was only
+visible from an installed tarball. If you bundle `@ekanos/*` into your own
+output, keep these singletons.
+
+### What is published, and what is not
+
+Being straight about this up front, because the alternative is you finding out
+by running a command that 404s:
+
+| Package | On npm |
+|---|---|
+| `@ekanos/sdk`, `@ekanos/ui`, `@ekanos/integration-schema` | **yes** — `0.1.2` |
+| `@ekanos/cli`, `@ekanos/harness` | **not yet** |
+
+So `npx @ekanos/cli init` and `pnpm add -D @ekanos/harness` do not resolve
+today. The toolchain and the local dev harness are written and documented —
+their READMEs are in this repo and describe what will ship — but you cannot
+install them yet.
+
+**What that costs you is seeing, not building.** Everything in this document
+works against `@ekanos/sdk` alone:
+
+```bash
+npm install @ekanos/sdk zod
+```
+
+- `defineIntegration()` validates at import time and throws with a remediation
+  message, so your definition is its own feedback loop — you do not need
+  `ekanos validate` to know whether it is correct.
+- The whole [Testing](#testing) section needs nothing but vitest.
+  `createMockContext()` gives you the same context production builds, and
+  `invokeWebhook()` / `invokeSchedule()` run your event handlers with the same
+  payload validation and egress allowlist the real transports will.
 
-## Quick start
+**What you genuinely cannot do yet** is see any of it rendered — widgets in the
+dashboard grid, the marketplace tile, the activation form, the Triggers panel.
+Those are the harness, and the harness is not installable. Webhook, schedule
+and OAuth work collapses back to unit tests, which is a real loss but a
+recoverable one. Widget *appearance* does not: you will be writing it blind
+until the harness ships.
 
-An integration is one call to `defineIntegration()`. It validates at import
-time and hands back a deep-frozen definition; the host re-parses the same
-object against the same schema when it registers you.
+One hard stop worth naming: `ekanos.json`, the project file the CLI reads. Its
+schema and the full generated-shell file list are documented in the
+`@ekanos/cli` README — which ships inside the CLI tarball, so today you can
+only read it if you have this repo. Nothing in this document needs that file;
+if you are hand-rolling something that does, wait for the CLI.
+
+## The shape of an integration
+
+An integration is one call to `defineIntegration()`. It validates at import time
+and hands back a deep-frozen definition; the host re-parses the same object
+against the same schema when it registers you, so a definition that loads
+locally is one the platform accepts. There is no second, looser contract.
 
 ```ts
-// integration.ts
+// src/integration.ts
 import { defineIntegration } from '@ekanos/sdk/integration';
-import { z } from 'zod';
 
-import { CurrentWeatherWidget } from './current-weather-widget';
+export const integration = defineIntegration<MyStorage>({
+  // Identity — all four required.
+  slug: 'acme-payments',        // kebab-case; the route segment and MCP namespace
+  name: 'Acme Payments',
+  description: 'Payment volume, recent activity, and refunds.',
+  version: '1.0.0',             // semver; promotion diffs definitions by it
+
+  // Marketing copy for the detail page.
+  capabilities: [ /* … */ ],
+  permissions: [ /* … */ ],
+
+  // What renders.
+  components: { widgets: [], marketplaceTile, activationForm },
+
+  // What runs.
+  tools: [ /* … */ ],
+  webhooks: [ /* … */ ],
+  schedules: [ /* … */ ],
+  oauth: { /* … */ },
+
+  // What it may touch.
+  storage: { account: {}, user: {} },
+  egress: ['https://api.acme.example'],
+
+  // What you suggest and a reviewer confirms.
+  proposes: { /* … */ },
+});
+```
+
+Only `slug`, `name`, `description` and `version` are required. Every other key
+is optional, and an integration that declares nothing but widgets is a perfectly
+good integration.
+
+**The export must be named `integration`.** Two things import it by that name:
+the host's build, when your package is added to the platform's list of partner
+integrations, and `ekanos.json` — the small file `@ekanos/cli` keeps at your
+project root, holding your `slug` and the `entry` module this export lives in.
+The `@ekanos/cli` README defines that file; this one assumes it.
+
+**The schema is strict everywhere.** An unrecognized key is a hard error, not a
+silently ignored one. That is deliberate: it is what makes host-assigned fields
+structurally un-settable rather than merely absent from the type. You cannot
+declare a `productId`, a `kind`, a trust tier, a `credentialModel`, or per-tool
+`effect`/`sensitivity` — the closest you get is [`proposes`](#proposes). Widget
+fields the platform populates at runtime (`productId`, `widgetConfigId`,
+`workspaceId`, `collapsed`, `isPinned`, `health`, `integrationMetadata`) are
+rejected the same way.
+
+## The capability context (`ctx`)
+
+`ctx` is the entire platform surface a server-side handler gets — tools, webhook
+handlers, schedule handlers and `oauth.onTokens` all receive the same object.
+There is no raw database client, no Supabase, and no request object.
+
+| Field | What it is |
+|---|---|
+| `ctx.storage.account` | `account_product_data` for this `{account, product}` — schema-validated |
+| `ctx.storage.user` | `user_product_data` for this `{user, account, product}`. **Throws for machine actors** |
+| `ctx.secrets` | `get(name)`, `names()`, `set(name, value)` over the resolved credential set |
+| `ctx.fetch` | `fetch`, refusing anything outside `egress` before it opens a socket |
+| `ctx.logger` | `debug`/`info`/`warn`/`error`, each `(context: object, message: string)` — pino-style, pre-bound with `{integration, accountId, actor}` |
+| `ctx.actor` | `{ kind: 'user', userId }` or `{ kind: 'machine', tokenId, createdBy }` |
+
+Plus read-only identity facts, all already authorized: `ctx.accountId`,
+`ctx.accountSlug`, `ctx.userId` (`null` for machine actors), `ctx.sourceId`,
+`ctx.integration` (`{ slug, productId }`) and `ctx.timezone`.
+
+Everything on `ctx` is scoped before your code runs. There is no id parameter
+anywhere for you to get wrong, and none for you to lie in.
+
+The logger takes the context object **first**:
+
+```ts
+ctx.logger.info({ paymentId, from, to }, 'Recorded a payment status change.');
+```
+
+## Declarable surfaces
+
+### `storage`
+
+Per-account (and per-user) state, keyed by strings you declare up front. **Every
+key declares a zod schema.** A key with no declaration cannot be read, written,
+or deleted — that is a type error where the schema map is statically known, and
+always a runtime `StorageValidationError`.
+
+```ts
+import type { StorageSchemas } from '@ekanos/sdk';
+import { z } from 'zod';
 
 const LocationSchema = z.object({
   label: z.string().min(1),
@@ -33,66 +228,252 @@ const LocationSchema = z.object({
   longitude: z.number(),
 });
 
-export const weather = defineIntegration({
-  slug: 'acme-weather',           // kebab-case; becomes the route + MCP namespace
-  name: 'Acme Weather',
-  description: 'Conditions for the places your team cares about.',
-  version: '1.0.0',               // semver; promotion diffs definitions by it
-
-  // Origin-only https allowlist. `ctx.fetch` refuses anything else BEFORE it
-  // opens a socket — redirect targets included.
-  egress: ['https://api.open-meteo.com'],
-
-  // Every storage key declares a zod schema. `clientReadable` (default false)
-  // is what lets a widget read the key back through the host storage route.
-  storage: {
-    account: {
-      'settings/location': { schema: LocationSchema, clientReadable: true },
-      'cache/forecast': z.object({ fetchedAt: z.string() }),
-    },
-  },
+export const myStorage = {
+  account: {
+    // Bare schema — server-only. This is the default and the common case.
+    'cache/forecast': z.object({ fetchedAt: z.string(), body: z.unknown() }),
 
-  components: {
-    widgets: [
-      {
-        id: 'acme-weather-current',
-        name: 'Current conditions',
-        component: CurrentWeatherWidget,
-        widgetState: 'active',
-      },
-    ],
+    // Descriptor form — the only way to widen exposure.
+    'settings/location': { schema: LocationSchema, clientReadable: true },
+  },
+  user: {
+    // Reachable from server handlers only — see "Account scope only" below.
+    'prefs/units': z.enum(['celsius', 'fahrenheit']),
   },
+} satisfies StorageSchemas;
 
-  tools: [
-    {
-      name: 'get_current_weather',   // lowercase snake_case
-      description: 'Current conditions for the saved location.',
-      async run(ctx) {
-        const saved = await ctx.storage.account.get('settings/location');
-        if (!saved) return { error: 'No location saved.' };
-
-        const response = await ctx.fetch(
-          `https://api.open-meteo.com/v1/forecast?latitude=${saved.data.latitude}` +
-            `&longitude=${saved.data.longitude}&current=temperature_2m`,
-        );
-
-        return response.json();
-      },
-    },
-  ],
+export type MyStorage = typeof myStorage;
+```
+
+Pass the type as the generic — `defineIntegration<MyStorage>({ … })` — and
+`ctx.storage.account.get('settings/location')` is typed to that schema's output
+in every handler.
+
+Reading and writing:
+
+```ts
+const saved = await ctx.storage.account.get('settings/location');
+// → { data, externalId, expiresAt, updatedAt } | null
+
+await ctx.storage.account.set('cache/forecast', body, {
+  expiresAt: new Date(Date.now() + 600_000).toISOString(),
 });
+
+await ctx.storage.account.delete('cache/forecast');
 ```
 
-`ctx` is the whole platform surface a handler gets: `ctx.storage` (already
-bound to this account and product, schema-validated on every read and write),
-`ctx.secrets`, `ctx.fetch` (egress-enforced), `ctx.logger`, plus identity
-facts. There is no raw database client and no request object.
+All three are async. `get` returns `null` for a missing key **and** for an entry
+past its `expiresAt`. A read whose stored data no longer matches the current
+schema throws `StorageValidationError` rather than handing you a shape you did
+not expect — evolve a schema with a versioned key (`settings/location.v2`) or a
+`z.union`, never by loosening it in place.
 
-### A widget
+**`clientReadable` is what makes a key browser-readable.** It defaults to
+`false`. The generic storage route (`GET /api/integrations/[slug]/storage`)
+serves only keys that opted in — so a widget can read back its own settings
+without your writing a route, while cursors, cached upstream payloads and
+internal bookkeeping stay server-side. The descriptor is `.strict()`, so
+`clientReadible: true` is an error rather than a key whose author believes it is
+exposed.
 
-Widgets are client components that render through the `Widget.*` compound API.
-Read `WidgetContext` first if you want to skip fetching while the integration
-is inactive.
+From a widget:
+
+```tsx
+import { fetchIntegrationStorage } from '@ekanos/sdk/hooks';
+
+const values = await fetchIntegrationStorage('acme-payments', {
+  accountId,
+  keys: ['settings/location'],
+});
+
+const location = values['settings/location'];   // unknown — narrow it yourself
+```
+
+It requests `GET /api/integrations/<slug>/storage?accountId=…&keys=a,b` and
+returns a `{ key: value }` object.
+
+Four things the signature does not tell you:
+
+- **A key that did not opt in is simply absent**, and so is a key that has
+  never been written. The response does not distinguish them, and neither can
+  you.
+- **It throws for a failed request, never for an absent key.** A 403 covers
+  "not signed in", "not a member", "not activated" and "no such integration" —
+  deliberately indistinguishable, so do not branch on it.
+- **At most 20 keys per request.** Asking for more throws before it fetches.
+  Split the read.
+- **Account scope only, and deliberately so.** `ctx.storage.user` is not
+  exposed on this route, so a per-user preference is server-readable only —
+  a widget cannot fetch one, and you need your own route if you need it in the
+  browser. The reasoning is worth knowing because it tells you what to expect:
+  `clientReadable` works as an opt-in because an account-scope value is
+  something the integration's author decided to expose, and that reasoning does
+  not transfer to personal data, where the person it belongs to made no such
+  decision. Adding `&scope=user` later is additive and would default to today's
+  behaviour, so the door is open — it is a considered "not yet", not an
+  oversight.
+
+Key names are `[a-z0-9_-]+` with at most one `/` segment: `config`,
+`settings/location`, `cache/recent-payments`. Two slashes is a validation error.
+
+### `egress`
+
+An origin-only https allowlist. `ctx.fetch` refuses anything not covered
+**before** it opens a socket — redirect targets included.
+
+```ts
+egress: [
+  'https://api.acme.example',      // exact origin
+  'https://*.acme-cdn.example',    // single leading-label wildcard
+  'https://api.acme.example:8443', // explicit port
+],
+```
+
+Scheme, host and optional port. No path, no query, no fragment, no credentials,
+no `http:`. Wildcards are supported only as one leading `*.`. Anything else is
+rejected by `defineIntegration()` with the offending entry quoted.
+
+A denied call throws `EgressDeniedError` synchronously. Widening this list is a security-posture change a reviewer looks at during
+**promotion** — the human review your integration passes before it is enabled
+for real accounts, where someone reads this declaration against what your
+handlers actually do. Declare the origins you call and no more.
+
+### Secrets
+
+**There is no `secrets` block in the definition.** This surprises people, so:
+secrets are not declared, they are *named*, and read back by name through
+`ctx.secrets`. There are exactly three places a name comes from, and all three
+are just strings you choose:
+
+| Where the name comes from | The name is |
+|---|---|
+| Your **activation form** | the field name you posted, **verbatim** |
+| `webhooks[].signature.secretName` | whatever string you put there |
+| `oauth.credentials.clientIdSecretName` / `clientSecretSecretName` | whatever string you put there |
+
+The activation form is the one every integration uses and the only one that
+looks like magic, so precisely:
+
+**Every field of `activationData` whose value is a string becomes readable as
+`ctx.secrets.get('<that exact field name>')`.** There is no "credential-shaped"
+detection — the platform does not inspect your field names, look for a marker,
+or transform anything. No prefixing, no snake_casing. Non-string values
+(numbers, booleans, nested objects) do not become secrets.
+
+That means a form field named `apiKey` is read back as
+`ctx.secrets.get('apiKey')`, **not** `acme_api_key`. It also means renaming a
+form field renames the secret and breaks every handler reading it — which is
+the argument for the shared constant below.
+
+The host then resolves the name across its credential tiers (account → source
+→ global) plus your activation's values, and hands your handler the resolved
+set. Where two tiers hold the same name, a value the *user* entered at
+activation wins over an admin-issued one; a value your own code wrote with
+`secrets.set()` does not, so a partner cannot shadow a credential an admin
+issues later.
+
+```ts
+const apiKey = await ctx.secrets.get('acme_api_key');   // string | null
+const available = await ctx.secrets.names();            // names only, no values
+await ctx.secrets.set('acme_access_token', token);      // account tier only
+```
+
+`set()` is tier-bound. It writes only to the account-tier store for this
+`{account, product}`. Source- and global-tier credentials are admin-issued and
+structurally unreachable from partner code — a `set()` against a name that
+resolves only from those tiers throws `SecretAccessError`. This is what makes
+OAuth refresh safe to hand to an integration.
+
+Because names are strings on both sides, keep them in one module and import
+them, rather than retyping the literal in the declaration and again in the
+handler:
+
+```ts
+// src/config.ts — the single source for every name that crosses a boundary
+export const ACME_API_KEY = 'acme_api_key';
+export const ACME_SIGNATURE_HEADER = 'x-acme-signature';
+```
+
+Used on both sides, so the form and the handler cannot drift:
+
+```tsx
+// the activation form — the field NAME is the secret name
+const ActivationSchema = z.object({ [ACME_API_KEY]: z.string().min(1) });
+<FormField name={ACME_API_KEY} … />
+```
+
+```ts
+// any server handler — same constant, same string
+const apiKey = await ctx.secrets.get(ACME_API_KEY);
+```
+
+### `tools`
+
+Tools are what the Fusion assistant (and, where the host allows it, the workflow
+engine) can call. Each declares a name, a description the model reads, an
+optional JSON-Schema parameter object, and an async `run`.
+
+```ts
+tools: [
+  {
+    name: 'get_current_weather',            // ^[a-z][a-z0-9_]*$
+    description: 'Current conditions for the account’s saved location.',
+    parameters: {
+      type: 'object',
+      properties: { units: { type: 'string', enum: ['celsius', 'fahrenheit'] } },
+      required: [],
+      additionalProperties: false,
+    },
+    outputExample: { temperature: 12.4, units: 'celsius' },
+
+    async run(ctx, args) {
+      const saved = await ctx.storage.account.get('settings/location');
+      if (!saved) return { error: 'No location saved for this account.' };
+
+      // Same origin the definition's `egress` declares — `ctx.fetch` refuses
+      // anything else synchronously, before it opens a socket.
+      const response = await ctx.fetch(
+        `https://api.acme.example/v1/weather` +
+          `?lat=${saved.data.latitude}&lon=${saved.data.longitude}`,
+      );
+
+      if (!response.ok) {
+        ctx.logger.error({ status: response.status }, 'Forecast fetch failed.');
+        return { error: `Acme returned ${response.status}.` };
+      }
+
+      return response.json();
+    },
+  },
+],
+```
+
+`run` returns a plain JSON-serializable value. Returning `{ error: '…' }` is the
+convention for an expected failure the model should read and explain; **throw**
+for a genuine fault.
+
+`outputExample` is shown to the model as a shape hint. Keep it small and honest.
+
+**`parameters` is a narrow slice of JSON Schema, not all of it.** The top level
+is `.strict()` and accepts exactly four keys — `type` (which must be the
+literal `'object'`), `properties`, `required` and `additionalProperties`.
+A root-level `title`, `description`, `$schema`, `oneOf` or a non-object `type`
+is a hard validation error, not an ignored key. Inside `properties` you are
+unconstrained as long as the value is plain JSON, so nested objects, arrays,
+enums and per-property descriptions all pass — the restriction is on the
+wrapper, not the contents.
+
+**Tool names are namespaced by slug at discovery.** The effective name the
+assistant sees is your slug with hyphens replaced by underscores, then the raw
+name, unless the name already carries that prefix. `acme-payments` +
+`list_recent_payments` → `acme_payments_list_recent_payments`. Two collision-free
+raw pairs can collapse to the same effective name, so the platform checks
+effective names and refuses a duplicate outright.
+
+### `components.widgets`
+
+Dashboard widgets are client components that render through the `Widget.*`
+compound API.
 
 ```tsx
 'use client';
@@ -104,7 +485,8 @@ import { Widget, WidgetContext } from '@ekanos/sdk/components';
 
 export function CurrentWeatherWidget({ accountId }: IntegrationComponentProps) {
   const ctx = use(WidgetContext);
-  const query = useMyData(accountId, ctx?.state.state === 'active');
+  // Skip fetching while the integration is inactive.
+  const query = useCurrentWeather(accountId, ctx?.state.state === 'active');
 
   return (
     <Widget.DataState loading={query.isLoading} error={query.isError}>
@@ -119,10 +501,38 @@ export function CurrentWeatherWidget({ accountId }: IntegrationComponentProps) {
 }
 ```
 
+Declared like this:
+
+```ts
+components: {
+  widgets: [
+    {
+      // Widget ids are GLOBAL — the dashboard resolves widget_config rows by
+      // them — so prefix every one with your slug.
+      id: 'acme-payments-summary',       // kebab-case
+      name: 'Acme Payments',
+      component: AcmePaymentsSummaryWidget,
+      widgetState: 'active',             // 'active' | 'inactive' | 'disabled'
+      isCollapsible: true,
+      isPinnable: false,
+      aiFooterEnabled: true,             // renders the "Ask about this" footer
+      layouts: {
+        lg: { x: 0, y: 0, w: 4, h: 8 },
+        md: { x: 0, y: 0, w: 4, h: 8 },
+        sm: { x: 0, y: 0, w: 4, h: 8 },
+      },
+    },
+  ],
+},
+```
+
+`widgetState` is the only required field beyond `id`, `name` and `component`.
+`layouts` seeds the default dashboard placement per breakpoint; `gridSize` and
+`gridPosition` are the older equivalents and still accepted.
+
 Widget settings live in `ctx.storage`, which is server-side, so a widget reads
-them back over HTTP with `fetchIntegrationStorage()` from `@ekanos/sdk/hooks`
-— only keys declared `clientReadable: true` come back, and a key that did not
-opt in is simply absent.
+them back over HTTP with `fetchIntegrationStorage()` from `@ekanos/sdk/hooks` —
+subject to `clientReadable`, above.
 
 To render a widget anywhere other than the Fusion dashboard — your own app, a
 story, a component test — wrap it in `WidgetPreviewProvider`, which fills the
@@ -131,115 +541,658 @@ same `WidgetContext` the host fills, with local state and no persistence:
 ```tsx
 import { WidgetPreviewProvider } from '@ekanos/sdk/components';
 
-<WidgetPreviewProvider widgetId="acme-weather-current" title="Current conditions">
-  <CurrentWeatherWidget accountId={accountId} productSlug="acme-weather" />
+<WidgetPreviewProvider widgetId="acme-payments-summary" title="Payments">
+  <AcmePaymentsSummaryWidget accountId={accountId} productSlug="acme-payments" />
 </WidgetPreviewProvider>;
 ```
 
-### Testing
+### `components.marketplaceTile`
+
+The card a source admin sees in the marketplace before connecting. Keep it
+plain: no context, no queries, no state, so it renders anywhere from props
+alone.
+
+```tsx
+'use client';
+
+import type { MarketplaceTileProps } from '@ekanos/sdk';
+import { Badge } from '@ekanos/ui/badge';
+import { Button } from '@ekanos/ui/button';
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@ekanos/ui/card';
+import { Icon } from '@ekanos/ui/icon';
+
+export function AcmePaymentsMarketplaceTile({
+  onActivate,
+  isActivated = false,
+  href,
+}: MarketplaceTileProps) {
+  return (
+    <Card className="shadow-card flex h-full flex-col border-0">
+      <CardHeader className="gap-3">
+        <div className="flex items-start justify-between gap-3">
+          <div className="bg-muted flex h-12 w-12 items-center justify-center rounded-lg">
+            <Icon name="fa-light fa-credit-card" className="h-6 w-6" aria-hidden />
+          </div>
+          {isActivated && <Badge variant="secondary">Connected</Badge>}
+        </div>
+        <CardTitle className="text-lg">Acme Payments</CardTitle>
+        <CardDescription>Volume, recent activity, and refunds.</CardDescription>
+      </CardHeader>
+
+      <CardContent className="mt-auto flex items-center justify-between gap-3 pb-6">
+        <span className="text-muted-foreground text-sm">Payments</span>
+        {isActivated ? (
+          <Button variant="outline" size="sm" nativeButton={false} render={<a href={href ?? '#'} />}>
+            Manage
+          </Button>
+        ) : (
+          <Button size="sm" onClick={onActivate}>Connect</Button>
+        )}
+      </CardContent>
+    </Card>
+  );
+}
+```
+
+`MarketplaceTileProps` is `IntegrationComponentProps` plus `onActivate?`,
+`isActivated?` and `href?`. `IntegrationComponentProps` itself is
+`{ accountId, sourceId?, integrationConfig? }` plus exactly one of `productId`
+or `productSlug` — a discriminated union, so passing both is a type error.
+
+A tile is optional. Omit it and the marketplace renders a generic card from
+your `name` and `description`, plus whatever logo the platform holds for your
+product — the logo is assigned host-side, not declared here.
+
+### `components.activationForm`
+
+What a user fills in to connect. `BaseActivationForm` owns the dialog chrome,
+the submit button, and the error/success states; you supply the
+`react-hook-form` instance and the fields.
+
+```tsx
+'use client';
+
+import { useState } from 'react';
+
+import type { ActivationFormProps } from '@ekanos/sdk';
+import { BaseActivationForm } from '@ekanos/sdk/components';
+import { useActivateIntegration } from '@ekanos/sdk/hooks';
+import { FormControl, FormField, FormItem, FormLabel, FormMessage } from '@ekanos/ui/form';
+import { Input } from '@ekanos/ui/input';
+import { zodResolver } from '@hookform/resolvers/zod';
+import { useForm } from 'react-hook-form';
+
+import { ACME_API_KEY } from './config';   // 'acme_api_key'
+
+// Field names ARE secret names — see the note below the example.
+const ActivationSchema = z.object({
+  [ACME_API_KEY]: z.string().min(1, 'Required'),
+  merchantId: z.string().min(1, 'Required'),
+});
+
+export function AcmePaymentsActivationForm({
+  accountId,
+  sourceId,
+  onSuccess,
+  onCancel,
+  isLoading: externalLoading = false,
+  inline = false,          // pass this through — see below
+}: ActivationFormProps) {
+  const [error, setError] = useState<string | null>(null);
+  const [success, setSuccess] = useState(false);
+
+  const form = useForm({ resolver: zodResolver(ActivationSchema),
+                         defaultValues: { [ACME_API_KEY]: '', merchantId: '' } });
+
+  const activate = useActivateIntegration();
+  const isLoading = externalLoading || activate.isPending;
+
+  const handleSubmit = async (data: Record<string, unknown>) => {
+    setError(null);
+    try {
+      await activate.mutateAsync({
+        accountId, sourceId,
+        integrationSlug: 'acme-payments',
+        activationData: data,
+      });
+      setSuccess(true);
+    } catch (cause) {
+      setError(cause instanceof Error ? cause.message : 'Could not connect.');
+    }
+  };
+
+  return (
+    <BaseActivationForm
+      isOpen inline={inline}
+      onClose={() => onCancel?.()}
+      title="Connect Acme Payments"
+      description="Bring volume, activity and refunds into your dashboard."
+      form={form}
+      onSubmit={handleSubmit}
+      isLoading={isLoading}
+      error={error}
+      success={success}
+      successTitle="Acme Payments is connected"
+      onSuccessClose={() => onSuccess?.({
+        success: true,
+        configData: { merchantId: form.getValues('merchantId') },
+        externalId: form.getValues('merchantId'),
+      })}
+      submitButtonText="Connect Acme Payments"
+      submitButtonLoadingText="Connecting…"
+    >
+      <FormField control={form.control} name={ACME_API_KEY} render={({ field }) => (
+        <FormItem>
+          <FormLabel>API key</FormLabel>
+          <FormControl><Input type="password" {...field} /></FormControl>
+          <FormMessage />
+        </FormItem>
+      )} />
+    </BaseActivationForm>
+  );
+}
+```
+
+Three things worth knowing:
+
+- **Pass `inline` through.** Without it the form mounts its own dialog, so any
+  page that embeds it ends up with nested dialogs.
+- **Every string field you submit is readable as a secret, under the exact
+  name you gave it.** There is no "credential-shaped" detection: the platform
+  does not inspect your field names or look for a marker. `activateIntegration`
+  takes whatever `activationData` object you post, and every field whose value
+  is a **string** becomes readable in your server handlers as
+  `ctx.secrets.get('<that same field name>')` and appears in
+  `ctx.secrets.names()`. Non-string values (numbers, booleans, nested objects)
+  do not.
+
+  So the form field name *is* the secret name — no prefixing, no snake_casing,
+  no transformation of any kind. Renaming a form field renames the secret and
+  breaks every handler reading it, so put the name in one constant and use it
+  on both sides:
+
+  ```ts
+  // src/config.ts — imported by the form AND by every handler
+  export const ACME_API_KEY = 'acme_api_key';
+  ```
+
+  Values you want back on the client instead go in `configData` on the
+  `ActivationResult` you hand `onSuccess`.
+- **`useActivateIntegration` needs the host's injected actions.** It reads them
+  from `IntegrationActivationProvider`, which the host mounts. Outside the host
+  — in the dev harness, or your own app — mount that provider yourself, or the
+  hook has nothing to call.
+
+`OAuthActivationForm` is the connect-button variant for OAuth integrations, and
+`useOAuthConnectionStatus()` reports whether the account is connected.
+
+A form is optional. Omit it and the host renders a generic one — a plain field
+per value it needs — rather than nothing.
+
+### `capabilities` and `permissions`
+
+Both are copy for the integration detail page, and both are pure data. **Every
+string here is read by the person connecting the integration** — they render on
+the activation dialog, not just in a catalogue listing. Write `detail` as a
+sentence you would be happy for a customer's security reviewer to read, because
+that is who reads it.
+
+Exactly what appears, so you can write to the shape:
+
+| Section | Renders |
+|---|---|
+| **What it does** | `capability.label`, then ` — ` + `capability.description` when present. `capability.icon` is **not** rendered here |
+| **What it can access** | `permission.label`, a badge reading `Read` or `Write` from `permission.type`, then `permission.detail` on the line below |
+
+Both sections are omitted entirely when their array is empty. `type` drives
+only the badge — it does not reorder or group anything.
+
+```ts
+capabilities: [
+  {
+    label: 'Volume at a glance',
+    description: 'Gross volume, trend, and success/failure counts on one card.',
+    // icon?: an optional component reference — accepted by the schema, but
+    //        NOT rendered on the activation surface
+  },
+],
+
+permissions: [
+  {
+    label: 'Read payments',
+    detail: 'Lists payments and aggregate volume for the connected merchant.',
+    type: 'read',                    // 'read' | 'write'
+  },
+  {
+    label: 'Issue refunds',
+    detail: 'Submits refunds against payments for the connected merchant.',
+    type: 'write',
+  },
+],
+```
+
+`permissions` is a disclosure to the person connecting the integration, not an
+enforcement mechanism. What actually constrains you is `egress`, the storage
+schemas, and the secret tiers.
+
+### `webhooks`
+
+An inbound delivery from your provider. **The declaration is the whole
+contract:** the transport validates the payload against `payloadSchema`,
+verifies the signature, and calls your handler with the same `ctx` every other
+handler gets.
+
+```ts
+import type { PartnerWebhookDeclaration } from '@ekanos/sdk/integration';
+
+export const paymentUpdatedWebhook: PartnerWebhookDeclaration<MyStorage> = {
+  id: 'payment-updated',              // kebab-case; the ingress addresses it by this
+                                      // (NOT the vendor's event name — see below)
+  description:
+    'Acme posts one event per payment status change. Keeps the dashboard cache honest.',
+
+  // Validates every delivery BEFORE the handler runs.
+  payloadSchema: PaymentUpdatedPayloadSchema,
+
+  // How the TRANSPORT verifies. `'none'` states explicitly that the source
+  // is unsigned. Your handler never checks a signature.
+  signature: { header: 'x-acme-signature', secretName: 'acme_webhook_secret' },
+
+  // Seeds the harness's payload editor and documents the shape beside the
+  // schema. Plain JSON only.
+  examplePayload: {
+    eventType: 'payment.updated',
+    payment: {
+      id: 'pay_3RkQ9fLm2xTvB1',
+      customerName: 'Northwind Logistics',
+      amountCents: 128450,
+      currency: 'USD',
+      status: 'succeeded',
+    },
+    previousStatus: 'pending',
+  },
+
+  async handler(ctx, event) {
+    // event: { id, receivedAt, headers, payload }
+    // `payload` is already parsed and validated — narrow it to your type.
+    const { payment, previousStatus } = event.payload as PaymentUpdatedPayload;
+
+    if (payment.status === previousStatus) {
+      // A no-op redelivery. Acknowledged (2xx — do not retry), recorded as
+      // irrelevant.
+      return { status: 'ignored', detail: `Still "${payment.status}".` };
+    }
+
+    await ctx.storage.account.set('events/last-payment-update', {
+      payment, previousStatus, receivedAt: event.receivedAt,
+    });
+    await ctx.storage.account.delete('cache/recent-payments');
+
+    return { status: 'processed', detail: `${previousStatus} → ${payment.status}.` };
+  },
+};
+```
+
+The three-way result contract matters:
+
+| Outcome | How to signal it | What the transport does |
+|---|---|---|
+| Handled it | `return { status: 'processed' }` | 2xx |
+| Valid but irrelevant | `return { status: 'ignored' }` | 2xx — the sender must not retry |
+| Could not handle a valid event | **throw** | retryable failure |
+
+`detail` is optional on both statuses and shows up in the harness and the host's
+delivery log.
+
+**Webhook ids are kebab-case, so you cannot name one after the vendor's event.**
+GitHub sends `pull_request`, Stripe sends `payment_intent.succeeded`, Slack
+sends `app_mention` — none of those are valid ids. Plan on keeping an explicit
+map from vendor event name to your webhook id, and put the vendor's name in
+`description` so the two are readable side by side. The validation error is
+clear about the rule, but it fires after you have already named things.
+
+A payload that fails `payloadSchema` never reaches the handler at all.
+Signature verification is the transport's job in every environment — the host
+ingress enforces it, the local harness logs it as skipped. Do not verify it
+yourself; you would be verifying a header the transport already consumed.
+
+### `schedules`
+
+A cron-driven run. Same handler shape, same `ctx`.
+
+```ts
+import type { PartnerScheduleDeclaration } from '@ekanos/sdk/integration';
+
+export const dailyReconcile: PartnerScheduleDeclaration<MyStorage> = {
+  id: 'daily-reconcile',             // kebab-case
+  description: 'Pull the latest payments each morning and store a summary.',
+  cron: '0 6 * * *',
+
+  async handler(ctx, invocation) {
+    // invocation: { scheduledFor, invokedAt, trigger }
+    const apiKey = await ctx.secrets.get(ACME_API_KEY);   // from src/config.ts
+
+    if (!apiKey) {
+      // Not configured is an EXPECTED state for a schedule — the account has
+      // nothing to reconcile yet. Skip, don't fail.
+      return { status: 'skipped', detail: 'No API key configured.' };
+    }
+
+    const response = await ctx.fetch('https://api.acme.example/v1/payments', {
+      headers: { authorization: `Bearer ${apiKey}` },
+    });
+
+    if (!response.ok) {
+      // An upstream failure IS a failed run — throw so the transport records
+      // it and the scheduler can retry.
+      throw new Error(`Acme returned ${response.status} during reconcile.`);
+    }
+
+    await ctx.storage.account.set('reconcile/daily', summarize(await response.json()));
+
+    return { status: 'completed', detail: 'Reconciled 214 payments.' };
+  },
+};
+```
+
+`completed` means the run did its work; `skipped` means it correctly did nothing.
+A failure throws.
+
+**`trigger` distinguishes the scheduler from a human pressing "Run now"** (in
+the harness, or an admin in the host). Handlers may branch on it — skipping an
+idempotency window for a manual run, say — but must be safe under both, and
+under redelivery. The example above recomputes from the API and overwrites one
+row, so running it twice is harmless. Aim for that.
+
+**Cron syntax.** Standard 5 fields, `minute hour day-of-month month
+day-of-week`, validated by `defineIntegration()` against the same grammar the
+host scheduler uses. Numeric values only, with `*`, lists (`1,15`), ranges
+(`1-5`) and steps (`*/15`, `0-30/5`). Bounds: minute 0-59, hour 0-23,
+day-of-month 1-31, month 1-12, day-of-week 0-7 (0 and 7 both Sunday). **No
+names** (`JAN`, `MON`), no `@daily` macros, no seconds field.
+
+### `oauth`
+
+You declare the provider; **the transport owns the flow.** Authorize redirect,
+state, callback and code exchange are not yours to write. You name the
+endpoints, name the client-credential secrets, and persist the tokens.
+
+```ts
+import type { PartnerOAuthDeclaration } from '@ekanos/sdk/integration';
+
+export const acmeOAuth: PartnerOAuthDeclaration<MyStorage> = {
+  provider: {
+    authorizationUrl: 'https://connect.acme.example/oauth/authorize',
+    tokenUrl: 'https://connect.acme.example/oauth/token',
+    scopes: ['payments:read', 'refunds:write'],
+    pkce: true,
+  },
+  credentials: {
+    clientIdSecretName: 'acme_oauth_client_id',
+    clientSecretSecretName: 'acme_oauth_client_secret',
+  },
+
+  // Called after the code exchange, and again after every refresh.
+  async onTokens(ctx, tokens) {
+    // tokens: { accessToken, refreshToken?, expiresAt?, scope?, tokenType?, raw? }
+    await ctx.secrets.set('acme_access_token', tokens.accessToken);
+
+    if (tokens.refreshToken) {
+      await ctx.secrets.set('acme_refresh_token', tokens.refreshToken);
+    }
+
+    ctx.logger.info(
+      { scope: tokens.scope ?? null, expiresAt: tokens.expiresAt ?? null },
+      'Stored Acme Connect tokens.',
+    );
+  },
+};
+```
+
+Token storage policy is just the capability layer — `ctx.secrets.set()` writes
+to the account tier, nothing new to learn.
+
+**Both endpoint origins must be covered by your `egress` list.**
+`defineIntegration()` rejects the declaration otherwise, with the exact origin
+to add. The code exchange runs through your declared egress, so an origin the
+reviewer never saw is an origin the exchange must not reach.
+
+`raw` on the token set carries provider-specific extras verbatim, for providers
+that return more than the standard fields.
+
+**The redirect URI exists, but you do not declare it.** The schema is
+`.strict()`, so `provider.redirectUri` is a hard error rather than an ignored
+key — and that is correct rather than an omission: the host owns the callback
+route and builds the URI from its own origin, so a value you declared would
+either be ignored or aim the host's callback somewhere it should not go.
+
+Register this with your provider, against whichever host will run the flow:
+
+```
+https://<your-fusion-host>/api/integrations/<your-slug>/callback
+```
+
+The dev harness does not serve that route, so you cannot complete a round trip
+locally. What it *can* check is that both endpoints you declared are inside
+your egress list.
+
+**Honest limitation:** there is no local OAuth loop yet. The harness's Triggers
+panel renders the declaration and checks its egress coverage, but it cannot walk
+you through an authorize redirect. Until that lands, unit-test `onTokens`
+directly against `createMockContext()` — it is an ordinary async function.
+
+### `proposes`
+
+A suggestion block, not a settings block. Security classifications are
+host-assigned; `proposes` is how you tell a reviewer what you believe is true,
+and the reviewer confirms it at promotion.
+
+```ts
+proposes: {
+  // 'account' | 'user' | 'source'. Declaring 'account' asserts that no
+  // handler reads a personal grant or a session client.
+  credentialModel: 'account',
+
+  tools: {
+    list_recent_payments: { effect: 'read',  sensitivity: 'financial' },
+    // Honest classification: this moves money. Marking it 'read' or
+    // 'internal' to get past a gate is what promotion review exists to catch.
+    refund_payment:       { effect: 'write', sensitivity: 'financial' },
+  },
+},
+```
+
+`effect` is `'read' | 'write'`. `sensitivity` is `'public' | 'internal' | 'pii'
+| 'financial'`. Both are optional per tool.
+
+The keys of `proposes.tools` must match declared tool names exactly — a
+proposal for a tool you did not declare is a validation error, so a rename
+cannot leave a stale classification behind.
+
+Why it matters: an undeclared `credentialModel` fails closed. The workflow
+engine's tool allowlist treats it as not machine-executable, so a tool you
+believe is workflow-callable will not be until this is declared and confirmed.
+
+### `workspaceTargets`
+
+Only `kind: 'integration'` packages declare workspace targets — the named
+dashboard sections an integration ships with. This is a first-party surface
+today: composition is admin-curated, and a partner integration's widgets are
+placed individually by an admin. The field is validated if you set it (the
+`WorkspaceTargetDefinition` type is exported from the root entrypoint), but you
+almost certainly should not set it.
+
+## Testing
 
 `@ekanos/sdk/testing` gives you the same context production builds, in memory:
-same schema validation, same egress allowlist, no network.
+same schema validation, same egress allowlist, same secret tier rules, no
+network.
 
 ```ts
 import { createMockContext } from '@ekanos/sdk/testing';
 
 const ctx = createMockContext({
-  integration: { slug: 'acme-weather' },
-  storageSchemas: weather.storage,
-  egress: weather.egress,
-  storage: { account: { 'settings/location': { label: 'HQ', latitude: 45, longitude: -122 } } },
+  integration: { slug: 'acme-payments' },
+  storageSchemas: myStorage,
+  egress: integration.egress,
+  storage: { account: { config: { merchantId: 'mrc_4820193' } } },
+  secrets: {
+    account: { acme_api_key: 'acme_test_9f2c41ab' },   // writable via secrets.set()
+    admin: { platform_key: 'not-writable' },           // set() here throws SecretAccessError
+  },
   fetchHandlers: [
-    { match: 'https://api.open-meteo.com', respond: () => Response.json({ current: {} }) },
+    // `match` as a string matches URLs that START WITH it; a RegExp is tested
+    // against the whole URL. An allowed call that matches nothing resolves 200 {}.
+    { match: 'https://api.acme.example', respond: () => Response.json({ payments: [] }) },
   ],
 });
 
-const result = await weather.tools[0].run(ctx, {});
+const result = await integration.tools[0].run(ctx, {});
 
-expect(ctx.fetchCalls).toHaveLength(1);
+expect(ctx.fetchCalls).toHaveLength(1);         // { url, init, denied }[]
+expect(ctx.logs.at(-1)?.level).toBe('info');    // { level, context, message }[]
+expect(ctx.dumpStorage().account).toMatchObject({ /* … */ });
 ```
 
-`invokeWebhook()` and `invokeSchedule()` do the same for declared event
-surfaces, building the context FROM the definition so a handler can never be
-tested against schemas or an allowlist it does not declare.
+`invokeWebhook()` and `invokeSchedule()` do the same for the event surfaces, and
+they build the context **from the definition** — its slug, storage schemas and
+egress — so a handler can never be tested against schemas or an allowlist it
+does not declare.
 
-### Styling
+```ts
+import { invokeSchedule, invokeWebhook } from '@ekanos/sdk/testing';
+
+const { result, event, ctx } = await invokeWebhook(integration, 'payment-updated', payload, {
+  contextOptions: { storage: { account: { config } }, fetchHandlers: [...] },
+  headers: { 'x-acme-signature': 'ignored — the transport verifies, not you' },
+});
 
-`@ekanos/ui` ships no CSS. Its components emit Tailwind class strings against
-Fusion's semantic tokens, and icons are Font Awesome glyphs the host loads. In
-your own app they render as correct but unstyled HTML, and icons render as
-nothing at all — that is expected, not a bug in your code.
+expect(result.status).toBe('processed');
+
+// Reuse one context across invocations so state accumulates, as it does in a
+// real account. Pass `context` OR `contextOptions`, never both.
+const second = await invokeSchedule(integration, 'daily-reconcile', {
+  context: ctx,
+  trigger: 'schedule',       // defaults to 'manual'
+});
+```
+
+Both throw if the id is not declared, and `invokeWebhook` throws if the payload
+fails `payloadSchema` — the handler never runs. The local transport records the
+signature skip as one `warn` line on `ctx.logs`.
 
 ## Entrypoints
 
 | Import | Runs on | Contents |
 |---|---|---|
 | `@ekanos/sdk` | anywhere | Types only — the integration contract (`IntegrationMetadata`, component prop types, activation/health/data types) and the capability context types (`IntegrationContext`, `ScopedStore`, `StorageSchemas`, …) |
-| `@ekanos/sdk/components` | client | `Widget` compound API + `WidgetContext`, `BaseActivationForm`, `OAuthActivationForm`, `BaseMarketplaceTile`, `AiPromptChip` — implemented here (the inversion); UI primitives from `@ekanos/ui` |
-| `@ekanos/sdk/hooks` | client | `useActivateIntegration`/`useDeactivateIntegration` (host-injected actions via `IntegrationActivationProvider`), `useOAuthConnectionStatus`, widget event bus, `useAskAssistant` |
-| `@ekanos/sdk/mcp` | server | `ToolModule`/`ToolContext` contract + membership/ownership guards — implemented here |
-| `@ekanos/sdk/context` | anywhere (isomorphic, dependency-pure) | Capability-context shared runtime: `EgressDeniedError`, `SecretAccessError`, `StorageValidationError`, the `isEgressAllowed` matcher, the storage validators — one implementation reused by the production wrapper and the mock |
-| `@ekanos/sdk/testing` | anywhere (tests) | `createMockContext()` — the in-memory `IntegrationContext` harness (schema-validated stores, tiered secrets, allowlist-enforcing fetch stub, capturing logger) |
-| `@ekanos/sdk/integration` | anywhere (isomorphic, dependency-pure) | The partner authoring contract: `defineIntegration()` (validate + deep-freeze, storage schemas per ruling 1, https-origin egress per ruling 3, security classifications only as a `proposes` block), `validateIntegrationDefinitions()` (cross-definition slug/widget/tool collision check), and `IntegrationDefinitionSchema` for the gate/dev-mcp validators |
-
-`/context`, `/testing`, and `/integration` import nothing from `@kit/*` and
-carry no `server-only` marker — they are self-contained by construction and
-the pack test typechecks all three in a clean room (alongside the root). The
-capability context spec is
-[`docs/devex/capability-context-proposal.md`](https://github.com/companydotcom/fusion/blob/dev/docs/devex/capability-context-proposal.md).
-Partners never extend `BaseIntegration` — `defineIntegration()` is the v1
-contract, and the host adapts the definition via
-`registerPartnerIntegration` in `@kit/integrations-core` (typed there as a
-structural twin, held in parity by
-`src/integration/__tests__/partner-definition-parity.test-d.ts`).
-
-## Rules
-
-- The root entrypoint is types-only and must stay importable from client code.
-  Never add a value export to it.
-- Additions anywhere require a second consumer and an entry in
-  [`docs/devex/sdk-export-map.md`](https://github.com/companydotcom/fusion/blob/dev/docs/devex/sdk-export-map.md) — the
-  export map is the source of truth for what is public and why.
-- The inversion landed: this package OWNS the `/components`, `/hooks`, and
-  `/mcp` implementations and `@kit/integrations-core` re-exports them. Never
-  import `@kit/*` from SDK source — UI comes from `@ekanos/ui`, host services
-  arrive through injection seams (`IntegrationActivationProvider`,
-  `ToolContext`). There is no `/server` entrypoint: first-party transitional
-  accessors live in `@kit/integrations-core/server` (core depends on the SDK
-  now, so the SDK cannot re-export core without a package cycle).
+| `@ekanos/sdk/components` | client | `Widget` compound API + `WidgetContext`, `WidgetPreviewProvider`, `BaseActivationForm`, `OAuthActivationForm`, `BaseMarketplaceTile`, `AiPromptChip` |
+| `@ekanos/sdk/hooks` | client | `useActivateIntegration`/`useDeactivateIntegration` (host-injected actions via `IntegrationActivationProvider`), `useOAuthConnectionStatus`, `fetchIntegrationStorage`, widget event bus, `useAskAssistant` |
+| `@ekanos/sdk/context` | anywhere (isomorphic, dependency-pure) | `EgressDeniedError`, `SecretAccessError`, `StorageValidationError`, the `isEgressAllowed` matcher, the storage validators — one implementation shared by the production wrapper and the mock |
+| `@ekanos/sdk/testing` | anywhere (tests) | `createMockContext()`, `invokeWebhook()`, `invokeSchedule()` |
+| `@ekanos/sdk/integration` | anywhere (isomorphic, dependency-pure) | `defineIntegration()`, `validateIntegrationDefinitions()`, `IntegrationDefinitionSchema`, and every `Partner*Declaration` type |
+
+`@ekanos/sdk/mcp` is **not in the published package.** It is excluded from the
+tarball (`files` carries `!dist/mcp`) and dropped from `publishConfig.exports`,
+so importing it from an installed `@ekanos/sdk` will not resolve. Tools are
+declared with `tools[]` on your definition, documented above — you do not need
+this entrypoint to write one.
+
+The root entrypoint is types-only and must stay importable from client code.
+`/context`, `/testing` and `/integration` are self-contained by construction and
+carry no `server-only` marker; the pack test typechecks all of them in a clean
+room.
+
+Partners never extend a base class. `defineIntegration()` is the v1 contract,
+and the host adapts the definition internally.
+
+### Styling
+
+`@ekanos/ui` components emit Tailwind class strings against Fusion's semantic
+tokens, and icons are Font Awesome glyphs the host loads. Import
+`@ekanos/ui/styles.css` (or the narrower `tokens.css` / `theme.css` /
+`base.css`) to get the token layer. Outside a host that loads Font Awesome,
+icons render as nothing at all — that is expected, not a bug in your code.
+
+## Naming and validation rules, in one table
+
+| Field | Rule | Example |
+|---|---|---|
+| `slug` | kebab-case, `^[a-z0-9]+(-[a-z0-9]+)*$` | `acme-payments` |
+| `version` | semver, prerelease/build suffix allowed | `1.0.0`, `2.1.0-beta.3` |
+| `components.widgets[].id` | kebab-case, **globally unique** — prefix with your slug | `acme-payments-summary` |
+| `tools[].name` | `^[a-z][a-z0-9_]*$` — lowercase snake_case | `list_recent_payments` |
+| `webhooks[].id` | kebab-case | `payment-updated` |
+| `schedules[].id` | kebab-case | `daily-reconcile` |
+| `schedules[].cron` | 5-field numeric cron | `0 6 * * *` |
+| storage keys | `[a-z0-9_-]+` with at most one `/` | `settings/location` |
+| `egress[]` | https origin, optional one leading `*.`, optional port | `https://*.acme.example` |
+| OAuth endpoints | absolute https, no embedded credentials, origin in `egress` | — |
+| `examplePayload`, `outputExample` | plain JSON only | — |
+
+Duplicate widget ids, tool names, webhook ids or schedule ids inside one
+definition are rejected. Collisions **across** definitions, and against
+first-party ids, are caught by `validateIntegrationDefinitions()` at
+registration.
+
+## Rough edges we know about
+
+Written down rather than papered over, because hitting one and not knowing
+whether it is you or us costs an afternoon.
+
+- **There is no client-side `ctx.fetch`.** `ctx.fetch` is server-side only. A
+  widget that talks to a vendor API straight from the browser has nowhere to
+  get an allowlisted fetch, so it needs a small seam of its own — a React
+  context whose default is the browser's `fetch`. The `@ekanos/harness` README
+  has the whole ~20-line pattern; the dev harness's live mode mounts it for you.
+- **No local OAuth loop.** See [`oauth`](#oauth) above.
+- **`useActivateIntegration()` is inert without the host's provider.** It reads
+  server actions out of `IntegrationActivationProvider`. Nothing warns you at
+  build time.
+- **Storage schema evolution is manual.** A stored value that no longer matches
+  its schema throws on read. Version the key or widen with `z.union`.
+- **`ctx.storage.user` throws for machine actors.** Anything reachable from a
+  workflow should use the account scope.
+- **`isPinnable` on a widget declaration renders nothing by itself.** It
+  reaches `WidgetContext` as `meta.isPinnable`, with the value at
+  `state.pinned` and a working `actions.togglePinned()` — but no shipped
+  `Widget.*` component draws a pin control, and neither does the dashboard,
+  which drives pinning from outside the widget. A pin *inside* your widget is
+  yours to build from those three.
+- **Widget sizing is declared twice, in two unrelated shapes.** `layouts` here
+  drives the real dashboard; the dev harness reads its own `width` instead.
+  Neither validates the other.
+- **Your slug is written in two places** — `ekanos.json` and the definition.
+  `ekanos validate` compares them and reports a
+  `project.slug-agreement` finding if they disagree, so this is caught — but it
+  is caught rather than prevented, and the slug addresses your harness route,
+  product, widget-id prefix and MCP namespace, so fix it early.
 
 ## Publish pipeline
 
-Workspace consumers resolve raw `src/*.ts` via `exports`; the published
-artifact is compiled ESM + declarations in `dist/`, wired through
-`publishConfig` (applied by `pnpm pack`/`pnpm publish`). The tarball ships
-`dist` + `README.md` only.
+Workspace consumers resolve raw `src/*.ts` via `exports`; the published artifact
+is compiled ESM + declarations in `dist/`, wired through `publishConfig`
+(applied by `pnpm pack`/`pnpm publish`). The tarball ships `dist`, this README,
+`LICENSE` and the ESLint preset.
 
 **Runtime dependencies + publish order.** The SDK depends on
 `@ekanos/integration-schema` (the dependency-pure canonical schema — one
-contract shared with `@kit/integrations-core`) and `@ekanos/ui` (the
-published slice of the host design system that `/components` renders
-through). Publish **schema and ui first**, then the SDK: the packed SDK
-declares both as normal dependencies, so they must already be on the registry
-for a fresh `npm install @ekanos/sdk` to resolve. The `pack:test` proves this
-offline by packing all three, installing ONLY the SDK tarball (schema + ui
-pulled transitively) and executing a real
-`import("@ekanos/sdk/integration")`.
+contract shared with the host) and `@ekanos/ui` (the published slice of the host
+design system that `/components` renders through). Publish **schema and ui
+first**, then the SDK: the packed SDK declares both as normal dependencies, so
+they must already be on the registry for a fresh `npm install @ekanos/sdk` to
+resolve.
 
 | Script | What it does |
 |---|---|
-| `pnpm --filter @ekanos/sdk build` | `tsc -p tsconfig.build.json` → `dist/` (ESM + `.d.ts` + maps; `__tests__` excluded) |
+| `pnpm --filter @ekanos/sdk build` | `tsc -p tsconfig.build.json` → `dist/` (ESM + `.d.ts`; `__tests__` excluded) |
 | `pnpm --filter @ekanos/sdk test` | Vitest over `src/**/__tests__` — matcher semantics, storage schema enforcement, secret tier rules, mock recording surfaces |
 | `pnpm --filter @ekanos/sdk api-report` | Regenerates [`api-report.md`](./api-report.md), the checked-in snapshot of every entrypoint's exports |
 | `pnpm --filter @ekanos/sdk api-report:check` | Fails on drift between the surface and `api-report.md` |
-| `pnpm --filter @ekanos/sdk pack:test` | Clean-room test: pack the SDK (and `@ekanos/integration-schema` + `@ekanos/ui`), install ONLY the SDK tarball outside the workspace with the declared peers, typecheck a consumer of EVERY published entrypoint (`skipLibCheck: false`), esbuild-bundle the client and server graphs, grep dist for `@kit/*` import specifiers, and EXECUTE `import("@ekanos/sdk/integration")` in real Node |
+| `pnpm --filter @ekanos/sdk pack:test` | Clean-room test: pack the SDK (and `@ekanos/integration-schema` + `@ekanos/ui`), install ONLY the SDK tarball outside the workspace with the declared peers, typecheck a consumer of EVERY published entrypoint (`skipLibCheck: false`), esbuild-bundle the client and server graphs, and EXECUTE `import("@ekanos/sdk/integration")` in real Node |
 
-The pack test was the forcing function for the SDK inversion
-([export map](https://github.com/companydotcom/fusion/blob/dev/docs/devex/sdk-export-map.md), review outcome 6), and the
-inversion landed: every published entrypoint (root, `/components`, `/hooks`,
-`/mcp`, `/context`, `/testing`, `/integration`) is typechecked in the clean
-room and must be GREEN — no skips remain. Nothing is a v1 contract until it
-passes.
+Every published entrypoint (root, `/components`, `/hooks`, `/mcp`, `/context`,
+`/testing`, `/integration`) is typechecked in the clean room and must be GREEN —
+no skips remain. Nothing is a v1 contract until it passes.
 
 Publishing is a deliberate human step, gated on `pack:test` being GREEN.
-`publishConfig.access` is already `public`.