@ekanos/cli 0.1.6 → 0.1.7

package/dist/validate-findings.js.map

@@ -1 +1 @@
-{"version":3,"file":"validate-findings.js","sourceRoot":"","sources":["../src/validate-findings.ts"],"names":[],"mappings":"AAIA,OAAO,EACL,wBAAwB,EACxB,yBAAyB,GAC1B,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAC7C,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAEnD,OAAO,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAE1D;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,MAAqB;IAErB,MAAM,QAAQ,GAAc,EAAE,CAAC;IAC/B,MAAM,WAAW,GAA+B,EAAE,CAAC;IAEnD,KAAK,MAAM,WAAW,IAAI,MAAM,CAAC,YAAY,EAAE,CAAC;QAC9C,MAAM,MAAM,GAAG,MAAM,cAAc,CACjC,WAAW,CAAC,SAAS,EACrB,MAAM,CAAC,UAAU,CAClB,CAAC;QAEF,IAAI,MAAM,CAAC,EAAE,EAAE,CAAC;YACd,QAAQ,CAAC,IAAI,CACX,GAAG,yBAAyB,CAAC,MAAM,CAAC,UAAU,EAAE;gBAC9C,IAAI,EAAE,WAAW,CAAC,SAAS;aAC5B,CAAC,CACH,CAAC;YACF,QAAQ,CAAC,IAAI,CACX,GAAG,4BAA4B,CAC7B,WAAW,EACX,MAAM,CAAC,UAAgC,CACxC,CACF,CAAC;YACF,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,UAAsC,CAAC,CAAC;YAChE,SAAS;QACX,CAAC;QAED,IAAI,MAAM,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;YAC/B,yEAAyE;YACzE,iEAAiE;YACjE,QAAQ,CAAC,IAAI,CAAC;gBACZ,KAAK,EAAE,iBAAiB;gBACxB,QAAQ,EAAE,OAAO;gBACjB,IAAI,EAAE,WAAW,CAAC,SAAS;gBAC3B,OAAO,EAAE,MAAM,CAAC,OAAO;gBACvB,IAAI,EACF,oEAAoE;oBACpE,uBAAuB;aAC1B,CAAC,CAAC;YACH,SAAS;QACX,CAAC;QAED,kEAAkE;QAClE,MAAM,iBAAiB,CACrB,kDAAkD,WAAW,CAAC,IAAI,KAAK;YACrE,MAAM,CAAC,OAAO,EAChB,oEAAoE;YAClE,6BAA6B,CAChC,CAAC;IACJ,CAAC;IAED,0EAA0E;IAC1E,QAAQ,CAAC,IAAI,CAAC,GAAG,wBAAwB,CAAC,WAAW,CAAC,CAAC,CAAC;IACxD,QAAQ,CAAC,IAAI,CAAC,GAAG,sBAAsB,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC;IAE5D,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;;;;;;GAUG;AACH,SAAS,4BAA4B,CACnC,WAA+D,EAC/D,UAA8B;IAE9B,MAAM,QAAQ,GAAG,UAAU,CAAC,IAAI,CAAC;IACjC,IAAI,OAAO,QAAQ,KAAK,QAAQ,IAAI,QAAQ,KAAK,WAAW,CAAC,IAAI;QAAE,OAAO,EAAE,CAAC;IAE7E,OAAO;QACL;YACE,KAAK,EAAE,wBAAwB;YAC/B,QAAQ,EAAE,OAAO;YACjB,IAAI,EAAE,WAAW,CAAC,SAAS;YAC3B,OAAO,EACL,8BAA8B,WAAW,CAAC,IAAI,wBAAwB;gBACtE,wBAAwB,QAAQ,4BAA4B;gBAC5D,sEAAsE;gBACtE,qCAAqC;YACvC,IAAI,EACF,sDAAsD,QAAQ,OAAO;gBACrE,+BAA+B,WAAW,CAAC,IAAI,OAAO;gBACtD,sBAAsB;SACzB;KACF,CAAC;AACJ,CAAC","sourcesContent":["import type {\n  DefinitionCollisionInput,\n  Finding,\n} from '@ekanos/integration-schema';\nimport {\n  collectCollisionFindings,\n  collectDefinitionFindings,\n} from '@ekanos/integration-schema';\n\nimport { preconditionError } from './errors';\nimport { loadDefinition } from './load-definition';\nimport type { LoadedProject } from './project';\nimport { collectProjectFindings } from './project-checks';\n\n/**\n * The full findings pass shared by `validate` (which reports them) and\n * `publish` (which refuses to submit on any error-severity finding). One\n * implementation so the publish gate can never drift from what `validate`\n * checks — a project that validates clean is, by construction, a project that\n * publish will accept locally.\n *\n * NOTE on schema skew: an earlier version of this function rewrote the\n * unrecognized-key hint when the project's `@ekanos/integration-schema` was\n * newer than the CLI's (see `schema-skew.ts`). That rewrite was dead code —\n * `assertSchemaNotSkewed` throws PRECONDITION_FAILED before either `validate`\n * or `publish` ever calls this function in that state, so a project-newer\n * finding can never reach here to be rewritten, and the precondition error\n * already names both versions and points at the fix. It was removed rather\n * than kept \"just in case\": if a future caller ever makes validate proceed\n * under skew instead of failing fast, THAT is when a rewrite here becomes\n * necessary again, and it should be reintroduced with a real caller driving\n * it, not tests that fake their own reachability.\n */\nexport async function collectAllFindings(\n  loaded: LoadedProject,\n): Promise<Finding[]> {\n  const findings: Finding[] = [];\n  const definitions: DefinitionCollisionInput[] = [];\n\n  for (const integration of loaded.integrations) {\n    const result = await loadDefinition(\n      integration.entryPath,\n      loaded.projectDir,\n    );\n\n    if (result.ok) {\n      findings.push(\n        ...collectDefinitionFindings(result.definition, {\n          file: integration.entryPath,\n        }),\n      );\n      findings.push(\n        ...collectSlugAgreementFindings(\n          integration,\n          result.definition as { slug?: unknown },\n        ),\n      );\n      definitions.push(result.definition as DefinitionCollisionInput);\n      continue;\n    }\n\n    if (result.kind === 'rejected') {\n      // The module loaded but the SDK/schema rejected the definition at import\n      // time — surface it as a validation finding rather than a crash.\n      findings.push({\n        check: 'definition.load',\n        severity: 'error',\n        file: integration.entryPath,\n        message: result.message,\n        hint:\n          'Fix the integration definition so defineIntegration() accepts it, ' +\n          'then re-run validate.',\n      });\n      continue;\n    }\n\n    // A genuine module-load failure is a precondition, not a finding.\n    throw preconditionError(\n      `Could not load the integration definition for \"${integration.slug}\": ` +\n        result.message,\n      'Ensure the entry module and its installed dependencies load under ' +\n        'Node, then re-run validate.',\n    );\n  }\n\n  // Cross-checks only mean something with more than one definition in hand.\n  findings.push(...collectCollisionFindings(definitions));\n  findings.push(...collectProjectFindings(loaded.projectDir));\n\n  return findings;\n}\n\n/**\n * `ekanos.json` and the definition each carry a slug, and nothing compared\n * them: a project could declare `something-else` while the definition said\n * `repo-activity` and validate would report `{ ok: true, findings: [] }`.\n *\n * That is the identifier every surface addresses the integration by — the\n * harness route, the product slug, the widget id prefix, the MCP server — so\n * two sources of truth disagreeing is not a style question. It is an error,\n * not a warning, for the same reason a silent default is worse than a loud\n * one: the failure it causes shows up somewhere else entirely.\n */\nfunction collectSlugAgreementFindings(\n  integration: { slug: string; entry: string; entryPath: string },\n  definition: { slug?: unknown },\n): Finding[] {\n  const declared = definition.slug;\n  if (typeof declared !== 'string' || declared === integration.slug) return [];\n\n  return [\n    {\n      check: 'project.slug-agreement',\n      severity: 'error',\n      file: integration.entryPath,\n      message:\n        `ekanos.json declares slug \"${integration.slug}\" for this entry, but ` +\n        `the definition says \"${declared}\". The slug addresses the ` +\n        'integration everywhere — its harness route, its product record, its ' +\n        'widget ids — so the two must agree.',\n      hint:\n        `Change one to match the other: either set \"slug\": \"${declared}\" in ` +\n        `ekanos.json, or pass slug: '${integration.slug}' to ` +\n        'defineIntegration().',\n    },\n  ];\n}\n"]}
+{"version":3,"file":"validate-findings.js","sourceRoot":"","sources":["../src/validate-findings.ts"],"names":[],"mappings":"AAIA,OAAO,EACL,wBAAwB,EACxB,yBAAyB,GAC1B,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAC7C,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAEnD,OAAO,EAAE,mBAAmB,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAE/E;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,MAAqB;IAErB,MAAM,QAAQ,GAAc,EAAE,CAAC;IAC/B,MAAM,WAAW,GAA+B,EAAE,CAAC;IAEnD,KAAK,MAAM,WAAW,IAAI,MAAM,CAAC,YAAY,EAAE,CAAC;QAC9C,MAAM,MAAM,GAAG,MAAM,cAAc,CACjC,WAAW,CAAC,SAAS,EACrB,MAAM,CAAC,UAAU,CAClB,CAAC;QAEF,IAAI,MAAM,CAAC,EAAE,EAAE,CAAC;YACd,QAAQ,CAAC,IAAI,CACX,GAAG,yBAAyB,CAAC,MAAM,CAAC,UAAU,EAAE;gBAC9C,IAAI,EAAE,WAAW,CAAC,SAAS;aAC5B,CAAC,CACH,CAAC;YACF,QAAQ,CAAC,IAAI,CACX,GAAG,4BAA4B,CAC7B,WAAW,EACX,MAAM,CAAC,UAAgC,CACxC,CACF,CAAC;YACF,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,UAAsC,CAAC,CAAC;YAChE,SAAS;QACX,CAAC;QAED,IAAI,MAAM,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;YAC/B,yEAAyE;YACzE,iEAAiE;YACjE,QAAQ,CAAC,IAAI,CAAC;gBACZ,KAAK,EAAE,iBAAiB;gBACxB,QAAQ,EAAE,OAAO;gBACjB,IAAI,EAAE,WAAW,CAAC,SAAS;gBAC3B,OAAO,EAAE,MAAM,CAAC,OAAO;gBACvB,IAAI,EACF,oEAAoE;oBACpE,uBAAuB;aAC1B,CAAC,CAAC;YACH,SAAS;QACX,CAAC;QAED,kEAAkE;QAClE,MAAM,iBAAiB,CACrB,kDAAkD,WAAW,CAAC,IAAI,KAAK;YACrE,MAAM,CAAC,OAAO,EAChB,oEAAoE;YAClE,6BAA6B,CAChC,CAAC;IACJ,CAAC;IAED,0EAA0E;IAC1E,QAAQ,CAAC,IAAI,CAAC,GAAG,wBAAwB,CAAC,WAAW,CAAC,CAAC,CAAC;IACxD,QAAQ,CAAC,IAAI,CAAC,GAAG,sBAAsB,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC;IAC5D,QAAQ,CAAC,IAAI,CAAC,GAAG,mBAAmB,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC;IAEzE,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;;;;;;GAUG;AACH,SAAS,4BAA4B,CACnC,WAA+D,EAC/D,UAA8B;IAE9B,MAAM,QAAQ,GAAG,UAAU,CAAC,IAAI,CAAC;IACjC,IAAI,OAAO,QAAQ,KAAK,QAAQ,IAAI,QAAQ,KAAK,WAAW,CAAC,IAAI;QAAE,OAAO,EAAE,CAAC;IAE7E,OAAO;QACL;YACE,KAAK,EAAE,wBAAwB;YAC/B,QAAQ,EAAE,OAAO;YACjB,IAAI,EAAE,WAAW,CAAC,SAAS;YAC3B,OAAO,EACL,8BAA8B,WAAW,CAAC,IAAI,wBAAwB;gBACtE,wBAAwB,QAAQ,4BAA4B;gBAC5D,sEAAsE;gBACtE,qCAAqC;YACvC,IAAI,EACF,sDAAsD,QAAQ,OAAO;gBACrE,+BAA+B,WAAW,CAAC,IAAI,OAAO;gBACtD,sBAAsB;SACzB;KACF,CAAC;AACJ,CAAC","sourcesContent":["import type {\n  DefinitionCollisionInput,\n  Finding,\n} from '@ekanos/integration-schema';\nimport {\n  collectCollisionFindings,\n  collectDefinitionFindings,\n} from '@ekanos/integration-schema';\n\nimport { preconditionError } from './errors';\nimport { loadDefinition } from './load-definition';\nimport type { LoadedProject } from './project';\nimport { collectDocsFindings, collectProjectFindings } from './project-checks';\n\n/**\n * The full findings pass shared by `validate` (which reports them) and\n * `publish` (which refuses to submit on any error-severity finding). One\n * implementation so the publish gate can never drift from what `validate`\n * checks — a project that validates clean is, by construction, a project that\n * publish will accept locally.\n *\n * NOTE on schema skew: an earlier version of this function rewrote the\n * unrecognized-key hint when the project's `@ekanos/integration-schema` was\n * newer than the CLI's (see `schema-skew.ts`). That rewrite was dead code —\n * `assertSchemaNotSkewed` throws PRECONDITION_FAILED before either `validate`\n * or `publish` ever calls this function in that state, so a project-newer\n * finding can never reach here to be rewritten, and the precondition error\n * already names both versions and points at the fix. It was removed rather\n * than kept \"just in case\": if a future caller ever makes validate proceed\n * under skew instead of failing fast, THAT is when a rewrite here becomes\n * necessary again, and it should be reintroduced with a real caller driving\n * it, not tests that fake their own reachability.\n */\nexport async function collectAllFindings(\n  loaded: LoadedProject,\n): Promise<Finding[]> {\n  const findings: Finding[] = [];\n  const definitions: DefinitionCollisionInput[] = [];\n\n  for (const integration of loaded.integrations) {\n    const result = await loadDefinition(\n      integration.entryPath,\n      loaded.projectDir,\n    );\n\n    if (result.ok) {\n      findings.push(\n        ...collectDefinitionFindings(result.definition, {\n          file: integration.entryPath,\n        }),\n      );\n      findings.push(\n        ...collectSlugAgreementFindings(\n          integration,\n          result.definition as { slug?: unknown },\n        ),\n      );\n      definitions.push(result.definition as DefinitionCollisionInput);\n      continue;\n    }\n\n    if (result.kind === 'rejected') {\n      // The module loaded but the SDK/schema rejected the definition at import\n      // time — surface it as a validation finding rather than a crash.\n      findings.push({\n        check: 'definition.load',\n        severity: 'error',\n        file: integration.entryPath,\n        message: result.message,\n        hint:\n          'Fix the integration definition so defineIntegration() accepts it, ' +\n          'then re-run validate.',\n      });\n      continue;\n    }\n\n    // A genuine module-load failure is a precondition, not a finding.\n    throw preconditionError(\n      `Could not load the integration definition for \"${integration.slug}\": ` +\n        result.message,\n      'Ensure the entry module and its installed dependencies load under ' +\n        'Node, then re-run validate.',\n    );\n  }\n\n  // Cross-checks only mean something with more than one definition in hand.\n  findings.push(...collectCollisionFindings(definitions));\n  findings.push(...collectProjectFindings(loaded.projectDir));\n  findings.push(...collectDocsFindings(loaded.project, loaded.projectDir));\n\n  return findings;\n}\n\n/**\n * `ekanos.json` and the definition each carry a slug, and nothing compared\n * them: a project could declare `something-else` while the definition said\n * `repo-activity` and validate would report `{ ok: true, findings: [] }`.\n *\n * That is the identifier every surface addresses the integration by — the\n * harness route, the product slug, the widget id prefix, the MCP server — so\n * two sources of truth disagreeing is not a style question. It is an error,\n * not a warning, for the same reason a silent default is worse than a loud\n * one: the failure it causes shows up somewhere else entirely.\n */\nfunction collectSlugAgreementFindings(\n  integration: { slug: string; entry: string; entryPath: string },\n  definition: { slug?: unknown },\n): Finding[] {\n  const declared = definition.slug;\n  if (typeof declared !== 'string' || declared === integration.slug) return [];\n\n  return [\n    {\n      check: 'project.slug-agreement',\n      severity: 'error',\n      file: integration.entryPath,\n      message:\n        `ekanos.json declares slug \"${integration.slug}\" for this entry, but ` +\n        `the definition says \"${declared}\". The slug addresses the ` +\n        'integration everywhere — its harness route, its product record, its ' +\n        'widget ids — so the two must agree.',\n      hint:\n        `Change one to match the other: either set \"slug\": \"${declared}\" in ` +\n        `ekanos.json, or pass slug: '${integration.slug}' to ` +\n        'defineIntegration().',\n    },\n  ];\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ekanos/cli",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "type": "module",
   "description": "The Ekanos partner toolchain CLI: scaffold, validate, and test a Fusion integration against the published @ekanos packages. Agent-native — every verb speaks JSON with a stable exit-code taxonomy.",
   "license": "MIT",

package/templates/AGENTS.md.tmpl

@@ -43,6 +43,29 @@ structurally un-settable — the closest you get is the `proposes` block.
 `ekanos.json` at the project root maps the slug to the entry module. The slug
 lives in both files; `ekanos validate` reports a finding if they disagree.
 
+## API documentation — ground every claim about the target API
+
+`ekanos.json` may declare a `docs` array: http(s) URLs and project-relative
+paths pointing at the target API's documentation (an OpenAPI spec, the
+official docs site, a vendored export). `docs/api-notes.md` is this project's
+own structured snapshot of that API — auth model, base URL, key endpoints,
+pagination, rate limits, error shapes, webhooks — written and updated during
+research and kept under version control so a reviewer can see what the
+integration believes. `ekanos validate` warns (`docs/missing-file`, never
+blocking) when a listed local file does not exist.
+
+Resolve documentation in this order, and announce which rung you are on: a
+local file from `docs` → an OpenAPI spec URL → the official docs URL → the
+Context7 MCP server (configured in `.mcp.json`) → a web search, announced as
+such.
+
+**Never invent an API surface from memory.** If none of those rungs resolves
+to real documentation, stop and ask the developer for a file or URL rather
+than guessing at endpoints, parameters, or error shapes.
+
+Codex users (and other agents without `.mcp.json` support) can add Context7 to
+their own MCP configuration to get the same fallback.
+
 ## The capability context (`ctx`) — the ONLY platform surface
 
 Every server-side handler (tool `run`, webhook `handler`, schedule `handler`,
@@ -212,6 +235,40 @@ Free set (`pnpm --filter @ekanos/ui check:fa-free-names`, or
 https://fontawesome.com/search?o=r&s=solid,regular,brands) before relying on
 it looking like anything in particular.
 
+## Live mode — real API calls, locally
+
+The harness (`npx ekanos dev`) mocks FUSION, not your vendor. **You do not
+need mock data to develop against the real API**, and never claim otherwise:
+the dev toolbar has a fixtures ⇄ live switch per integration, and in live
+mode your widgets' real query functions run and their requests reach the
+real vendor API. The only gate is the `egress` allowlist from
+`defineIntegration()` — enforced locally by the same matcher production
+uses, so an origin you forgot to declare fails on this machine with
+`EgressDeniedError` instead of in review.
+
+Live mode is opt-in per integration. Add a `live` block to the entry in
+`harness.config.ts`:
+
+```ts
+live: {
+  // Fusion-side state widgets read before calling anything — what your
+  // host route would have returned. Everything NOT seeded runs its real
+  // query function against the real network.
+  seeds: [{ queryKey: settingsKey, data: MY_SETTINGS }],
+},
+```
+
+Egress is read off the definition automatically — do not repeat it here.
+
+What stays mocked either way (the Fusion bits): storage, secrets/vault,
+auth, host `/api/` routes — that is what `seeds` and fixtures are for.
+Boundaries to know: live-mode widget requests come from the BROWSER, so a
+vendor that blocks browser origins (CORS) or needs a server-held secret
+must be exercised through handlers instead; and the Triggers surface runs
+webhook/schedule/onActivate handlers against the mock context (its
+`ctx.fetch` never touches the network) — cover handler network behavior
+with fixtures in tests, then for real on the dev host after publishing.
+
 ## Testing
 
 `@ekanos/sdk/testing` builds the same context production uses, in memory —

package/templates/claude-skill.md.tmpl

@@ -10,6 +10,13 @@ rules, widget and testing patterns — lives in **AGENTS.md** at the project
 root. Read it before writing integration code. The definition is one
 `defineIntegration()` in `src/integration.ts`, exported as `integration`.
 
+For the full authoring workflow — interview, API research, widgets, wiring,
+publish — use the `build-integration` skill. For a styling review of widgets
+that already exist (plain/flat widgets, overflow, a bare marketplace tile),
+use the `polish-widgets` skill. The target API's contract lives
+in `docs/api-notes.md`: write API client code from that file, and update it
+in the same commit when the live API disagrees.
+
 ## The loop
 
 1. `npx ekanos dev` — local harness (only when you need to see UI).

package/templates/docs/api-notes.md.tmpl

@@ -0,0 +1,21 @@
+# __DISPLAY_NAME__ — API notes
+
+This file is the structured snapshot of the target API: what this integration
+currently believes about the upstream service. It is written and updated by
+the build-integration skill's Research phase, and it is versioned so a
+reviewer can see exactly what the integration assumes.
+
+As the authoring agent, fill in and maintain the sections below from real
+documentation (the `docs` entries in `ekanos.json`, an OpenAPI spec, the
+official docs site) — never from memory. Record:
+
+- **Auth model** — scheme, token lifetime, where the credential comes from.
+- **Base URL(s)** — per environment, and what `egress` must allowlist.
+- **Key endpoints** — method, path, purpose, request/response shape.
+- **Pagination** — parameter names, page-size limits, cursor semantics.
+- **Rate limits** — the numeric limits and the backoff the API expects.
+- **Error shapes** — status codes, error body structure, retryable or not.
+- **Webhooks** — events, payloads, signature scheme, retry behaviour.
+
+Update this file in the same change as the code that depends on the new
+knowledge. If the API contradicts these notes, the notes are wrong — fix them.

package/templates/mcp.json.tmpl

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "context7": {
+      "command": "npx",
+      "args": ["-y", "@upstash/context7-mcp"]
+    }
+  }
+}

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.