@ekanos/cli 0.1.5 → 0.1.7

package/templates/skills/build-integration/SKILL.md

@@ -0,0 +1,178 @@
+---
+name: build-integration
+description: Interview-driven workflow for building and publishing a Fusion integration with the Ekanos SDK. Use when building a new integration from scratch ("build an integration for X", "connect a service like Stripe or Slack", a fresh ekanos scaffold with no substance yet), when adding or changing API wiring ("add an endpoint", "wire this to the API", "add a webhook/tool/schedule"), when researching the target service's API ("how does this API paginate", "what auth does it use", "where are the docs"), or when publishing.
+---
+
+# Build a Fusion Integration
+
+Guide the user from intent to a published integration. The user supplies
+judgment (what service, what it should show and do); the CLI supplies
+determinism (scaffold, validate, test, publish). Never hand-roll what a verb
+does; never guess at platform APIs — the contract is in `AGENTS.md` at the
+project root. Read it before writing any integration code. The integration's
+identity is the `slug` in `ekanos.json`; the definition is one
+`defineIntegration()` in `src/integration.ts`.
+
+Every `ekanos` verb supports `--json` and exits nonzero on failure. Validate
+findings carry a `hint` that is a remediation instruction: follow it.
+
+## Workflow
+
+1. **Interview** — establish the plan and the docs, get approval
+2. **Research** — ground the target API in its real docs (see `references/api-docs-research.md`)
+3. **Declare** — write the `defineIntegration` skeleton, validate clean
+4. **Widgets** — design-first, all four states (see `references/widget-design.md`)
+5. **Wire** — activation → secrets → `ctx.fetch`/storage → tools/webhooks/schedules (see `references/api-wiring.md`)
+6. **Verify** — validate + test + human look at the harness
+7. **Publish** — checklist, explicit human approval, `ekanos publish`
+
+Work one phase at a time. After each phase, state in one line what was done
+and what is next.
+
+## Phase 1: Interview
+
+Ask in order, ONE message per step, skipping anything the user already said.
+Use AskUserQuestion for the multiple-choice steps when the tool is available;
+otherwise ask in plain prose with lettered options.
+
+1. **The service** (free text): which target service or API? Whether they
+   already have an account / API key / sandbox.
+2. **The docs** (free text): where does the target API's documentation live?
+   Prefer, in this order:
+   - (a) an **OpenAPI/Swagger spec URL** — the gold standard: exact paths,
+     params, and auth schemes with no prose ambiguity;
+   - (b) an official docs URL;
+   - (c) a local file the developer drops into `docs/`.
+
+   If `ekanos.json` already has a `docs` array (set via `ekanos init
+--docs`), confirm those entries instead of re-asking. Whatever the
+   developer supplies, WRITE it into `ekanos.json`'s `docs` array (http(s)
+   URLs or repo-relative paths) so it is versioned with the project.
+
+3. **The outcomes** (free text): "What should a team see on their dashboard,
+   and what should the integration be able to do?" Push for 1–3 concrete
+   outcomes ("show open invoices", "alert on new disputes", "let the
+   assistant create a customer"). Each SEE-outcome becomes a widget; each
+   DO-outcome becomes a tool, webhook, or schedule.
+4. **Auth** (choice): API key / Bearer / OAuth 2.0 / Basic / not sure
+   (research will settle it). This decides the activation-form fields — and
+   every string field name on that form IS a secret name (see AGENTS.md).
+5. **Freshness** (choice): live fetch on view / cached with a refresh
+   schedule / pushed by webhooks. This decides storage keys and schedules.
+
+Then present **the plan** as a short table — widgets (name, what it shows),
+activation fields (exact names), egress origins, storage keys (with data-type
+prefixes), tools/webhooks/schedules — and get an explicit yes before writing
+code. The plan is the contract for the rest of the session; note any change
+the user makes to it later.
+
+## Phase 2: Research
+
+Read `references/api-docs-research.md` before this phase — it carries the
+mechanics: how to read a spec without ingesting it whole, what to extract
+from prose, when Context7 helps, and the notes-file skeleton.
+
+Resolve documentation down this ladder — stop at the first rung that answers
+the question at hand:
+
+1. **Local files** listed in `ekanos.json`'s `docs` array — read them.
+2. **OpenAPI/Swagger spec URL** — fetch it; prefer it over prose docs.
+3. **Official docs URL** — fetch and extract.
+4. **Context7 MCP** (available via this project's `.mcp.json`) — best for
+   questions about the service's official client libraries and SDKs, not
+   for raw REST surfaces.
+5. **Web search** — last resort, and SAY you are falling back to search.
+
+**Never invent an API surface from memory alone.** If nothing on the ladder
+resolves, stop and ask the developer for a file or URL rather than
+proceeding.
+
+Write findings into `docs/api-notes.md` (the scaffold ships a stub): auth
+model, base URL(s), the endpoints each planned outcome needs (method, path,
+key params), pagination scheme, rate limits, error shapes, webhook/event
+surfaces if planned. One reason it is a file and not a comment: it is
+versioned, reviewable, and survives docs-site rot — later sessions read it
+instead of re-researching. Correct the plan if research contradicts it and
+tell the user what changed.
+
+## Phase 3: Declare
+
+Write the `defineIntegration` skeleton per AGENTS.md: metadata, `egress`
+(only the origins from the plan), `storage` schemas (declared keys only,
+data-type prefixes from the closed vocabulary), empty-but-typed widgets/tools
+lists. Then:
+
+    npx ekanos validate
+
+Zero findings before moving on. Re-run after EVERY change to the declaration
+for the rest of the session — it is fast and its findings are instructions.
+
+## Phase 4: Widgets — design first
+
+Read `references/widget-design.md` before the first widget. Build each widget
+with realistic mock data first, make it distinctive and polished, implement
+all four states (loading / empty / error / success), THEN wire real data.
+Check rendering in the harness:
+
+    npx ekanos dev
+
+and ask the user to look at http://localhost:3100 at each significant visual
+change — do not claim a widget looks good without either a screenshot or the
+user's confirmation. A review-and-fix pass over widgets that already exist
+(flat rows, no hierarchy, overflow, a bare tile) is the `polish-widgets`
+skill — use it here as the final styling pass and again before publish.
+
+## Phase 5: Wire
+
+Read `references/api-wiring.md`. Work from `docs/api-notes.md`, not
+conversational memory — every endpoint, header, and param in client code
+must trace to a line in the notes. When the live API disagrees with the
+notes, update `docs/api-notes.md` in the same commit as the code fix.
+
+Order: activation form (field names = secret names, keep them in exported
+constants) → server handlers using `ctx.fetch` / `ctx.storage` /
+`ctx.secrets` only → tools → webhooks/schedules. Write tests alongside each
+handler with `createMockContext` / `invokeWebhook` / `invokeSchedule` from
+`@ekanos/sdk/testing`, and run:
+
+    npx ekanos test
+
+## Phase 6: Verify
+
+All of these, in order, all green:
+
+1. `npx ekanos validate` — zero findings
+2. `npx ekanos test` — all passing, including at least one test per handler
+   and one failure-path test per external call
+3. Harness check — every widget renders all four states (mock the states if
+   needed); user has seen and approved the visuals
+4. Grep your own diff for leaks: no credential in `ctx.storage`, `configData`,
+   logs, or tool results; no global `fetch`/`process.env`/`node:fs`
+
+## Phase 7: Publish — gated
+
+Publishing sends the project to the Fusion host and is versioned immutably.
+NEVER run it on your own judgment. Show the user:
+
+- the verify results (1–4 above)
+- `package.json` version (bump it if this slug+version was already published)
+- the target host and source (from ekanos.json, or ask)
+
+and ask plainly: "Ready to publish?" Only on an explicit yes:
+
+    npx ekanos publish
+
+If it exits 4 (auth required), the user must run `npx ekanos login` — the
+device flow needs their browser; wait for them. On success, report the
+submission id and state, and mention `npx ekanos status` shows it from now
+on. On `invalid_state` (exit 7), the version exists — bump `package.json`
+and re-confirm before retrying.
+
+## Failure etiquette
+
+- A validate finding, test failure, or nonzero verb exit is never something
+  to narrate past — fix it or surface it.
+- If the same error survives two fix attempts, stop and show the user the
+  exact output.
+- Never edit files under `.ekanos/` (generated) or weaken a test to get to
+  green.

package/templates/skills/build-integration/references/api-docs-research.md

@@ -0,0 +1,93 @@
+# Researching the target API
+
+Read this at Phase 2 (Research), before fetching anything. The ladder and the
+hard rule live in SKILL.md; this file is the mechanics — how to work each
+rung and what to leave behind in `docs/api-notes.md`.
+
+## Reading an OpenAPI/Swagger spec efficiently
+
+Do not ingest the whole spec — production specs run to megabytes and most of
+it is endpoints the plan will never touch. Read in this order:
+
+1. `servers` (or Swagger 2.0 `host` + `basePath`) — the real base URL(s),
+   including environment variants (sandbox vs production).
+2. `components.securitySchemes` (2.0: `securityDefinitions`) plus top-level
+   `security` — the auth model and the EXACT header/query shape. This settles
+   the interview's "not sure" auth answer.
+3. Only the paths the plan needs: search the spec for the resource nouns from
+   the plan's outcomes, then read those operations fully — method, path
+   template, required params, request/response schemas, error responses.
+4. Pagination: look at the list operations' params (`cursor`, `page`,
+   `limit`, `starting_after`) and response envelopes (`next`, `has_more`,
+   `Link` header) — pagination is per-operation, never assume one scheme.
+
+If the spec is JSON, `jq` the sections above rather than reading linearly.
+Note the spec's own `info.version` and the URL it was fetched from in the
+notes — that is the line future sessions use to detect drift.
+
+## Extracting from prose docs
+
+Capture: base URL, auth header shape (copy a verbatim example request),
+endpoint tables (method, path, required params), pagination scheme, documented
+rate limits and the 429 behavior, error response body shape, webhook event
+names and signature scheme. Copy exact strings — paths, header names, event
+names — never paraphrase them.
+
+Skip: marketing pages, quickstart tutorials, SDK installation guides,
+changelog prose. Watch for versioned base URLs (`/v1/` vs `/v2/`) — docs
+sites routinely show both, and mixing them is a classic silent 404.
+
+## Using Context7
+
+Context7 (via this project's `.mcp.json`) serves indexed documentation for
+libraries and SDKs. It is good for: the target service's OFFICIAL client
+library — method signatures, initialization, idiomatic usage — and for
+questions about packages the integration depends on. It is NOT an authority
+on raw REST surfaces: when Context7's account of an endpoint disagrees with
+the OpenAPI spec or official docs, the spec wins. If the integration calls
+the REST API directly (the common case — `ctx.fetch` means no vendor SDK),
+Context7 is a supplement, not a source.
+
+## The `docs/api-notes.md` structure
+
+The scaffold ships a stub; grow it into this shape (drop sections that do not
+apply, keep the order):
+
+    # API notes: <service>
+    Sources: <spec/docs URLs + fetch date>
+
+    ## Auth
+    <scheme; exact header shape, e.g. `Authorization: Bearer <key>`>
+
+    ## Base URLs
+    <production; sandbox if any>
+
+    ## Endpoints
+    | Outcome | Method | Path | Key params |
+    |---|---|---|---|
+    | open invoices widget | GET | /v1/invoices | status, limit, cursor |
+
+    ## Pagination
+    <scheme, per-operation exceptions>
+
+    ## Rate limits
+    <documented limits; 429 behavior, Retry-After>
+
+    ## Errors
+    <error body shape; which statuses are retryable>
+
+    ## Webhooks
+    <events used, signature header + scheme, retry behavior>
+
+Every endpoint the Wire phase touches must have a row here first. Keep it a
+snapshot, not a mirror — only what THIS integration uses.
+
+## When the live API contradicts the notes
+
+A 404 on a noted path, an auth header that bounces, a response missing a
+noted field: believe the live API. Update `docs/api-notes.md` in the SAME
+commit as the code fix — a note that disagrees with shipped code is worse
+than no note — and record what was observed and when, so the correction is
+not "fixed back" from the stale docs site later. If the contradiction changes
+the plan (an endpoint gone, auth scheme different), surface it to the user
+before wiring around it.

package/templates/skills/build-integration/references/api-wiring.md

@@ -0,0 +1,94 @@
+# Wiring an integration to its target API
+
+Read this at Phase 5 (Wire). The binding contract (ctx surface, storage
+vocabulary, secret naming) is `AGENTS.md`; the target API's contract is
+`docs/api-notes.md` — write client code from the notes, not from memory, and
+when the live API contradicts them, fix the notes in the same commit as the
+code. This file is the order of work and the traps.
+
+## Order of work
+
+1. **Constants first** — `src/config.ts` exporting every name that crosses a
+   boundary: secret names (= activation field names), storage keys, webhook
+   ids, egress origins. Both the form and every handler import from here;
+   a renamed form field silently orphans its secret otherwise.
+2. **Activation form** — zod schema + react-hook-form inside
+   `BaseActivationForm` (see AGENTS.md). Every string field the user submits
+   becomes `ctx.secrets.get('<field name>')`. Validate the credential shape
+   in the schema (prefix, length) so a paste error fails at the form, not in
+   a handler.
+3. **A thin API client** — one module owning base URL, auth header assembly,
+   response parsing, and error mapping, taking `ctx` (or just
+   `{ fetch, secrets }`) as an argument. Handlers never call `ctx.fetch`
+   directly for endpoints the client covers.
+4. **Handlers** — tools, then webhooks, then schedules, each with tests as
+   they are written (`createMockContext`, `invokeWebhook`, `invokeSchedule`
+   from `@ekanos/sdk/testing`).
+5. **Widget data** — widgets cannot call the target API (no client-side
+   `ctx`). The pattern: a schedule (or webhook) fetches and writes a
+   `clientReadable` storage key; the widget reads it back with
+   `fetchIntegrationStorage()` from `@ekanos/sdk/hooks`. Cache freshness in
+   the stored value (`fetchedAt`) and show it in the UI when staleness
+   matters.
+
+## Traps, each one earned
+
+- **Egress is an allowlist, checked synchronously.** Every origin the client
+  touches must be in `egress` — including the OAuth token host and any host a
+  redirect lands on. A missing origin is a thrown error, not a warning.
+- **Secrets never leave the secrets surface.** Not into `ctx.storage`, not
+  into logs, not into a tool result, not into a widget's stored value. Token
+  rotation: `ctx.secrets.set()` (account tier only).
+- **`ctx.storage.user` throws for machine actors** (workflow runs). A tool
+  that touches user storage must branch on `ctx.actor.kind` or stick to
+  account storage.
+- **Webhook signatures are declared, not hand-verified** — `signature:
+{ header, secretName }` in the declaration; the transport verifies before
+  the handler runs. Return `{ status: 'ignored' }` for valid-but-irrelevant
+  deliveries so the sender stops retrying; throw only for retryable faults.
+- **Handlers run under redelivery and "Run now".** Make writes idempotent
+  (stable keys, upsert semantics); `invocation.trigger` distinguishes cron
+  from manual.
+- **Schedules are 5-field numeric cron** — no names, no `@daily`.
+- **Rate limits**: respect `Retry-After` on 429 in the client; a schedule
+  that hammers a free-tier API takes every tenant down with it.
+- **Storage schema evolution**: a stored value that no longer parses throws
+  on read — version the key or widen with a union; never edit a schema to a
+  shape old rows can't satisfy.
+- **Cache rows must know what they were built from.** A cache keyed by
+  nothing and invalidated only by time serves the PREVIOUS configuration
+  after the user changes activation data (old city, old account, old list)
+  until the next schedule tick — confidently wrong answers. Embed a config
+  fingerprint in the stored value (the activation fields the fetch depended
+  on) and treat a mismatch on read as a cache miss. Tools reading the cache
+  must check the fingerprint, not just row freshness. Three details that are
+  each easy to get wrong:
+  - Include the fields that change the VALUES, not just the ones that select
+    the data — units, currency, locale, timezone. They leave the identity
+    byte-identical while making every number wrong.
+  - Stabilize noisy members (round coordinates, normalize case) so the
+    fingerprint doesn't churn under inputs the answer doesn't depend on.
+  - Declare the fingerprint field `.optional()` and treat ABSENT as a miss.
+    A required field makes every pre-existing row throw on read (see the
+    schema-evolution trap above) — and for a `clientReadable` key that throw
+    reaches the widgets, turning a cache improvement into a dashboard
+    outage. Optional-plus-absent-is-stale degrades to a refetch instead.
+
+## Test floor per handler
+
+- happy path against `createMockContext` with seeded secrets + programmed
+  fetch responses
+- one failure path (API 500/timeout) proving the handler returns/throws the
+  designed way rather than leaking the raw error
+- for webhooks: one `ignored` case; for schedules: one idempotency case
+  (same invocation twice, no duplicate writes)
+
+## Verifying against the real API — live mode
+
+The harness mocks Fusion, never the vendor. Do not tell the developer that
+local work is mock-only: opt the integration into live mode (a `live` block
+on its `harness.config.ts` entry — see AGENTS.md "Live mode") and the
+toolbar's fixtures ⇄ live switch runs real widget queries against the real
+API, gated only by the declared `egress`. Use fixtures for the Fusion-side
+state widgets need first, and for webhook/schedule handlers (the Triggers
+surface runs those against the mock context by design).

package/templates/skills/build-integration/references/widget-design.md

@@ -0,0 +1,132 @@
+# Widget design for Ekanos integrations
+
+Read this before building the first widget. The mechanics (declaration shape,
+`Widget.*` API, `WidgetContext`, preview) are in `AGENTS.md` and the
+`@ekanos/sdk` README §`components.widgets` — this file is the design judgment.
+
+## Philosophy: form over function
+
+Build the widget beautiful with realistic MOCK data first; wire real data
+last. A widget that renders nothing interesting with perfect plumbing is a
+failure; the reverse is a demo. Sequence per widget:
+
+1. Distinctive UI with hardcoded, realistic mock data
+2. All four states (loading / empty / error / success)
+3. Real data via the wiring reference
+4. A final styling pass against the checklist below
+
+"Distinctive" means: if the mock data were swapped for another service's, the
+widget should NOT still look right. Lead with the one number, chart, or list
+the user said matters (the interview's SEE-outcome); trim everything that
+does not serve it.
+
+## The key question — decide it before writing JSX
+
+Every widget answers 1–2 questions, and the answer must be the most prominent
+element on it — size, weight, position. Everything else is supporting context
+and recedes (`text-muted-foreground`, smaller). Name the question from the
+interview's SEE-outcome before writing the first class; a widget you cannot
+name the question for is a widget you cannot design.
+
+| Widget type         | Key question                       | Most prominent element                                                |
+| ------------------- | ---------------------------------- | --------------------------------------------------------------------- |
+| KPI / stat          | "How are we doing?"                | The hero number: `text-3xl font-semibold tracking-tight tabular-nums` |
+| List / feed         | "What needs my attention?"         | Item name `text-base font-medium` + its value, right-aligned          |
+| Chart               | "Which way is it going?"           | The chart + current value; axes and legends muted                     |
+| Action / connection | "What can I do / who's connected?" | One clear CTA or the identity + status                                |
+
+The default failure is uniform weight: everything `text-sm`, values dressed
+like labels. Squint at the render — if nothing reads first, there is no
+hierarchy, and no amount of padding will save it.
+
+## Layout recipes (the shapes that work)
+
+**KPI / stat card** — one hero, a delta, supporting stats demoted:
+
+- Center block: label `text-sm text-muted-foreground`, then the hero value
+  `text-3xl font-semibold tracking-tight tabular-nums`, then a delta line
+  `text-sm font-medium` in `text-success-strong` / `text-destructive`.
+- Supporting stats as a `border-t` footer strip: per-stat
+  `text-lg font-semibold` over a `text-xs text-muted-foreground` label,
+  columns separated by `bg-border h-8 w-px`.
+- One `text-3xl` element per widget — two heroes is zero heroes.
+
+**List / feed** — rows with a first read:
+
+- Container `divide-y`; each row `flex items-center gap-3 px-4 py-3`.
+- Name: `min-w-0 flex-1` wrapping `truncate text-base font-medium`, with an
+  optional `text-sm text-muted-foreground` second line.
+- Value: `shrink-0 text-right text-base font-semibold tabular-nums`.
+- 5–7 rows visible; the rest behind inner scroll or a "View all" ghost button.
+- One status treatment per row: a `Badge` variant (`success` / `warning` /
+  `info` / `destructive`) or an `h-2.5 w-2.5` semantic dot — never both.
+
+**Chart** — the picture is the point:
+
+- Chart fills the body; current value as a `text-2xl font-semibold` readout
+  above or beside it, axes/gridlines/legend all muted.
+- Series colors from chart tokens (`--chart-1`…), never hand-picked palette.
+
+## The skeleton
+
+Every widget: `'use client'`, `Widget.DataState` wrapping `Widget.Card` →
+`Widget.Header` + `Widget.Loading` + `Widget.Error` + `Widget.Active`. Gate
+fetching on `ctx?.state.state === 'active'` from `WidgetContext`. Copy the
+canonical example from the SDK README rather than improvising the tree.
+
+## Four states, no exceptions
+
+- **Loading**: `Widget.Loading` (or `skeleton` blocks shaped like the real
+  content — never a bare spinner in a big empty card).
+- **Error**: `Widget.Error`, plus a one-line human cause when known. Never
+  render an exception message verbatim.
+- **Empty**: a real designed state — icon (h-8 w-8, muted), one sentence
+  saying what will appear here and what action produces it. Empty ≠ error.
+- **Success**: the design.
+
+While iterating, expose a temporary way to flip states (a dev-only prop or a
+mock switch) so the harness can show all four; remove it before publish.
+
+## Fusion design rules (the harness applies the host theme)
+
+- **Semantic tokens only**: `bg-card`, `text-foreground`, `text-muted-foreground`,
+  `border-border`, `bg-primary`, `text-destructive`. NEVER raw palette
+  classes (`bg-white`, `text-gray-500`, `bg-amber-400`) or hex/oklch
+  literals — they break in dark mode and off-brand tenants.
+- **Accent discipline**: the primary (coral-orange) on ≤10% of the widget —
+  one CTA, one highlighted value, one active state. Semantic status colors
+  (success/warning/destructive) are not accents.
+- **Depth via shadow, not borders** where a surface needs lift.
+- **Sizing floors**: body text `text-sm`+; `text-xs` only for tertiary
+  metadata (timestamps, badge counts). Icons in lists `h-5 w-5`+. Card
+  padding `p-5`/`p-6`. Row padding: `px-4 py-3` (the recipes above use
+  this; hard floor `py-2 px-3` — never below). Section gaps `space-y-5`+.
+- **Numbers**: hero/KPI values large and `tracking-tight` with
+  `tabular-nums` when digits align.
+- **Overflow**: the widget must hold its grid size — inner scroll
+  (`overflow-y-auto` on the list, never the card) and `truncate` on
+  user-supplied strings. Test the sm layout, not just lg.
+- **Components**: build from `@ekanos/ui/*` (the module list is in
+  AGENTS.md); `cn()` from `@ekanos/ui/utils` for conditional classes; icons
+  through `@ekanos/ui/icon` (Font Awesome names — they render empty outside
+  a host that loads FA; that is expected in bare tests).
+
+## Layout sizing
+
+Pick `layouts` from the content, not habit: KPI/stat cards 3–4 wide × 6–8
+high; lists and feeds 4–6 × 10–14; charts 6–8 × 10–12 (grid units, lg
+breakpoint). Give md/sm the same content priority order — cut columns, not
+meaning.
+
+## Checklist before calling a widget done
+
+- [ ] Four states render in the harness; user has seen them
+- [ ] No raw color literals; accent ≤10%; dark mode looks intentional
+- [ ] Text floors respected; nothing truncates that matters at sm
+- [ ] Mock data replaced by real data (or the mock is clearly temporary and
+      the wiring phase is next)
+- [ ] Widget id is slug-prefixed and globally unique
+
+A styling review of existing widgets — worst-first findings, before→after
+fixes, the tile — is the `polish-widgets` skill; use it rather than
+re-deriving a review pass from this file.

package/templates/skills/polish-widgets/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: polish-widgets
+description: Review-and-fix pass over existing widget styling. Use when the user asks to review widget styling, wants widgets or the marketplace tile to look better, says the tile design is bad or the widgets look plain/generic/flat, reports overflow or responsiveness problems, or before publishing as a final styling pass.
+---
+
+# Polish Widgets
+
+A widget that renders the right data can still be a bad widget: every row the
+same weight, no element answering the widget's question, a grid of identical
+stat chips. This skill is the fix pass — render each widget in the harness,
+find the worst offenses, fix them, show the user before and after. The
+creation-time design rules live in
+`../build-integration/references/widget-design.md`; this skill assumes they
+exist and enforces them on code already written.
+
+## The key question
+
+Every widget exists to answer 1–2 questions. Name the question FIRST. Its
+answer must be the most prominent element — size, weight, position — and
+everything else demotes to supporting context. If you cannot name the
+question, that is the finding: ask the user what the widget is for before
+touching its classes.
+
+| Widget type         | Key question                       | Most prominent element                                                      |
+| ------------------- | ---------------------------------- | --------------------------------------------------------------------------- |
+| KPI / stat          | "How are we doing?"                | The hero number: `text-3xl font-semibold tracking-tight tabular-nums`       |
+| List / feed         | "What needs my attention?"         | Item name `text-base font-medium` + its value, right-aligned `tabular-nums` |
+| Chart               | "Which way is it going?"           | The chart plus the current value; axes and legends muted                    |
+| Action card         | "What can I do here?"              | One clear CTA; supporting copy secondary                                    |
+| Status / connection | "Is it working? What's connected?" | Badge or status dot + the identity it describes                             |
+
+The most common failure is uniform weight: everything `text-sm`, values styled
+like their labels. Squint at the rendered widget — if nothing reads first,
+there is no hierarchy, and that fix comes before any padding nit.
+
+## Review procedure
+
+1. **Enumerate** the widgets from `components.widgets` in `src/integration.ts`
+   — id, name, component file. Review all of them unless the user scoped it.
+2. **Render**: `npx ekanos dev`, then the Widgets surface at
+   `http://localhost:3100/<slug>/widgets`. Drive the review from the dev
+   toolbar: Render state (loading / error / inactive / disabled / active),
+   Viewport presets (check sm, not just lg), Collapsed, Unhealthy, and the
+   theme toggle — dark mode is part of the review, not an extra.
+3. **Assess** each widget against the checklist below and write findings per
+   widget, worst-first. Missing hierarchy outranks spacing; a broken sm layout
+   outranks a badge color.
+4. **Fix** worst-first, one widget at a time. After each: `npx tsc --noEmit`,
+   re-render in the harness.
+5. **Show the user** before/after for each widget — screenshots or ask them to
+   look — and get their read before the next one. Never claim a widget looks
+   better without one of the two.
+
+## Checklist
+
+**Hierarchy**
+
+- The key question's answer is the visually dominant element
+- One prominent element per row; supporting info is `text-muted-foreground`
+- Hero/stat values match the recipe: `text-3xl font-semibold tracking-tight
+tabular-nums` (never below `text-2xl`, and never `text-sm` on a number
+  that matters)
+- List row titles `text-base font-medium`; subtitles `text-sm text-muted-foreground`
+- `text-xs` only on tertiary metadata (timestamps, header badge counts)
+
+**Tokens & color**
+
+- Semantic tokens only — no `bg-white`, `text-gray-500`, hex, raw palette shades
+- Primary accent on ≤10% of the widget; status through `Badge` variants
+  (`success` / `warning` / `info` / `destructive`) or a semantic status dot
+- No two colored elements competing in one row
+- Both themes checked with the toolbar toggle
+
+**Layout & overflow**
+
+- Lists cap at 5–7 visible items; more goes behind inner scroll
+  (`min-h-0 flex-1 overflow-y-auto` on the list, never the card) or "View all"
+- `truncate` + `min-w-0` on user-supplied strings; values `shrink-0` and right-aligned
+- The sm viewport holds: cut columns, keep meaning
+- Sizing floors hold: rows `px-4 py-3`+, list icons `h-5 w-5`+, gaps `gap-3`+,
+  body text `text-sm`+
+
+**States & numbers**
+
+- All four states render (the toolbar flips loading/error/inactive; empty needs
+  a data mock) and empty is a designed state, not a blank card
+- Digits that align use `tabular-nums`; money is right-aligned with fixed width
+
+The canonical fix for the flat-row failure, since it is the one you will apply
+most:
+
+```tsx
+// Before: three spans, one size, no first read
+<div className="flex justify-between text-sm">
+  <span>{item.name}</span>
+  <span>{item.amount}</span>
+</div>
+
+// After: name leads, value anchors, metadata recedes
+<div className="flex items-center gap-3 px-4 py-3">
+  <div className="min-w-0 flex-1">
+    <p className="truncate text-base font-medium">{item.name}</p>
+    <p className="text-muted-foreground text-sm">{item.detail}</p>
+  </div>
+  <span className="shrink-0 text-base font-semibold tabular-nums">
+    {formatCurrency(item.amount)}
+  </span>
+</div>
+```
+
+Full before→after gallery — hero KPI, status treatment, sizing floors, inner
+scroll, row actions, designed empty state — in `references/patterns.md`. Read
+it before rewriting any widget body.
+
+## The marketplace tile
+
+"The tile looks bad" is usually not a styling bug — it is missing branding.
+The tile is `components.marketplaceTile` in the definition, typically built on
+`BaseMarketplaceTile` from `@ekanos/sdk/components`, and it renders from the
+props you pass: `name`, `summary` (1–2 sentences shown on the card),
+`brandName`, `logoPath`, `categories`, `productColor`, `ctaText`. Omit
+`logoPath` and the card falls back to a single-letter monogram; omit `summary`
+and the body sits blank next to its neighbours. Check the props before
+touching CSS.
+
+Review it at `http://localhost:3100/<slug>/tile` — the harness renders it
+inside the real catalogue grid with two inert neighbour cards, which is the
+only honest test: does the title wrap at column width, does the summary clamp
+like the neighbours', is the card the same height? (Register the component as
+`tile:` in `harness.config.ts` if the surface says none is registered.) The
+harness also notes this surface is lightly used by the live marketplace today
+— keep it correct and branded, don't gold-plate it.
+
+## Reporting
+
+Finish with a per-widget summary: the key question you assigned it, the
+findings fixed (worst-first), anything deliberately left, and confirmation the
+user saw the result. Then run the standard gate: `npx tsc --noEmit` and
+`npx ekanos validate` clean.