@ekanos/cli 0.8.0 → 0.9.0

package/dist/commands/apps.js

@@ -54,7 +54,7 @@ export async function runApps(ctx, args) {
         rows: [
             ['Source', result.source.slug],
             ['Teams can connect', result.configured ? 'yes' : 'not yet'],
-            ['Callback URL', result.callbackUrl],
+            ['Callback URLs', callbackUrls(result)],
         ],
     }));
 }
@@ -72,11 +72,11 @@ export function walkthrough(status) {
     const steps = ((_b = status.setup) === null || _b === void 0 ? void 0 : _b.steps.length)
         ? [
             ...status.setup.steps,
-            `Make sure the callback URL is exactly: ${status.callbackUrl}`,
+            `Check the app lists exactly: ${callbackUrls(status).join(', ')}`,
         ]
         : [
             `In ${name}, create an OAuth app (or open the one you use).`,
-            `Register this callback URL exactly: ${status.callbackUrl}`,
+            `Register exactly these callback URLs: ${callbackUrls(status).join(', ')}`,
         ];
     steps.push("Enter its client ID and secret below. The secret is stored in Ekanos's vault and never shown again.");
     lines.push(...steps.map((step, index) => `  ${index + 1}. ${step}`));
@@ -106,7 +106,7 @@ function summary(ctx, status) {
                 ? 'yes — teams can connect'
                 : 'no — no team can connect yet',
         ],
-        ['Callback URL', status.callbackUrl],
+        ['Callback URLs', callbackUrls(status)],
     ];
     return [
         ctx.ui.result({ title: `${status.product.name} app`, rows }),
@@ -186,4 +186,11 @@ async function promptHidden(question) {
         process.stderr.write('\n');
     }
 }
+/** Every redirect URI to register; an older host sends only the one. */
+function callbackUrls(status) {
+    var _a;
+    return ((_a = status.callbackUrls) === null || _a === void 0 ? void 0 : _a.length)
+        ? status.callbackUrls
+        : [status.callbackUrl];
+}
 //# sourceMappingURL=apps.js.map

package/dist/commands/apps.js.map

@@ -1 +1 @@
-{"version":3,"file":"apps.js","sourceRoot":"","sources":["../../src/commands/apps.ts"],"names":[],"mappings":"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","sourcesContent":["import type { ProviderAppStatus } from '@ekanos/integration-schema';\n\nimport {\n  type AppsApiResult,\n  setProviderApp,\n  showProviderApp,\n} from '../apps-api';\nimport type { StoredSession } from '../auth/credential-store';\nimport {\n  type AuthEnvironment,\n  refreshStoredSession,\n  requireSession,\n  resolveAuthEnvironment,\n} from '../auth/session';\nimport type { CliContext } from '../context';\nimport { authRequiredError, usageError, validationError } from '../errors';\nimport type { ExitCode } from '../exit-codes';\nimport { resolveSourceTarget } from '../source-target';\nimport type { ResultRow } from '../ui';\nimport { promptYesNo } from './publish';\n\nexport const APPS_SUBCOMMANDS = ['show', 'set'] as const;\ntype AppsSubcommand = (typeof APPS_SUBCOMMANDS)[number];\n\nexport interface AppsArgs {\n  host?: string;\n  source?: string;\n  subcommand?: string;\n  product?: string;\n  dir: string;\n  env: Record<string, string | undefined>;\n  stdinIsTTY?: boolean;\n  /** Test seams for the questions `set` asks. */\n  ask?: (question: string) => Promise<string>;\n  askSecret?: (question: string) => Promise<string>;\n  confirm?: (question: string) => Promise<boolean>;\n}\n\n/**\n * `apps` — a Source's provider apps: the OAuth client an integration signs\n * every team in through (Linear's, say). `show` says whether the Source has\n * one and which callback URL to register; `set` takes the client id and\n * secret from the Source admin at the terminal — never from a flag, a file\n * or a non-interactive run, so an agent driving the CLI never handles the\n * secret.\n */\nexport async function runApps(\n  ctx: CliContext,\n  args: AppsArgs,\n): Promise<ExitCode> {\n  const subcommand = parseSubcommand(args.subcommand);\n  const product = requireProduct(args.product, subcommand);\n\n  if (subcommand === 'set' && !canPrompt(ctx, args)) {\n    throw usageError(\n      'apps set takes the client secret at a terminal, never in a script or an agent run.',\n      `Run it yourself in your terminal: npx @ekanos/cli apps set ${product}${args.source ? ` --source ${args.source}` : ''}`,\n    );\n  }\n\n  const env = resolveAuthEnvironment(ctx, args.host, args.env, {\n    projectDir: args.dir,\n  });\n  const resolved = await resolveSourceTarget(\n    env,\n    requireSession(env.store, env.host),\n    args,\n  );\n  const client = new AppsClient(env, resolved.session);\n  const source = resolved.source;\n\n  const status = await client.call((token) =>\n    showProviderApp(env.host, token, source, product),\n  );\n\n  if (subcommand === 'show') {\n    return ctx.succeed({ host: env.host, ...status }, summary(ctx, status));\n  }\n\n  ctx.log(walkthrough(status).join('\\n'));\n  if (status.configured) {\n    const replace = await (args.confirm ?? promptYesNo)(\n      `${status.source.slug} already has ${status.product.name} credentials. Replace them? [y/N]`,\n    );\n    if (!replace) {\n      throw validationError(\n        'Nothing was changed.',\n        `Run \"ekanos apps show ${product}\" to see the current state.`,\n      );\n    }\n  }\n\n  const clientId = (await (args.ask ?? promptLine)('Client ID: ')).trim();\n  const clientSecret = (\n    await (args.askSecret ?? promptHidden)('Client secret (hidden): ')\n  ).trim();\n  if (!clientId || !clientSecret) {\n    throw validationError(\n      'Both the client ID and the client secret are needed.',\n      `Run \"ekanos apps set ${product}\" again.`,\n    );\n  }\n\n  const result = await client.call((token) =>\n    setProviderApp(env.host, token, {\n      source,\n      product,\n      clientId,\n      clientSecret,\n    }),\n  );\n  return ctx.succeed(\n    { host: env.host, ...result },\n    ctx.ui.result({\n      title: result.replaced\n        ? `Replaced the ${result.product.name} app`\n        : `Set up the ${result.product.name} app`,\n      rows: [\n        ['Source', result.source.slug],\n        ['Teams can connect', result.configured ? 'yes' : 'not yet'],\n        ['Callback URL', result.callbackUrl],\n      ],\n    }),\n  );\n}\n\n/**\n * How to create the app: the integration's own steps (`oauth.setup`, with the\n * callback URL filled in) when it declares them, else the generic three.\n */\nexport function walkthrough(status: ProviderAppStatus): string[] {\n  const name = status.product.name;\n  const lines = [`${name} app for ${status.source.slug}`];\n  if (status.setup?.consoleUrl) {\n    lines.push(`  Open: ${status.setup.consoleUrl}`);\n  }\n  const steps = status.setup?.steps.length\n    ? [\n        ...status.setup.steps,\n        `Make sure the callback URL is exactly: ${status.callbackUrl}`,\n      ]\n    : [\n        `In ${name}, create an OAuth app (or open the one you use).`,\n        `Register this callback URL exactly: ${status.callbackUrl}`,\n      ];\n  steps.push(\n    \"Enter its client ID and secret below. The secret is stored in Ekanos's vault and never shown again.\",\n  );\n  lines.push(...steps.map((step, index) => `  ${index + 1}. ${step}`));\n  if (status.setup?.guideUrl) lines.push(`  Guide: ${status.setup.guideUrl}`);\n  return lines;\n}\n\nfunction summary(ctx: CliContext, status: ProviderAppStatus): string {\n  const rows: ResultRow[] = [\n    ['Source', status.source.slug],\n    ...(status.setup\n      ? ([\n          [\n            'How to create it',\n            [\n              ...(status.setup.consoleUrl\n                ? [`Open ${status.setup.consoleUrl}`]\n                : []),\n              ...status.setup.steps.map(\n                (step, index) => `${index + 1}. ${step}`,\n              ),\n            ],\n          ],\n        ] as const)\n      : []),\n    [\n      'Set up',\n      status.configured\n        ? 'yes — teams can connect'\n        : 'no — no team can connect yet',\n    ],\n    ['Callback URL', status.callbackUrl],\n  ];\n  return [\n    ctx.ui.result({ title: `${status.product.name} app`, rows }),\n    ...(status.configured\n      ? []\n      : [\n          ctx.ui.hint(\n            `Run \"ekanos apps set ${status.product.slug}\" in your terminal to enter its credentials.`,\n          ),\n        ]),\n  ].join('\\n');\n}\n\nclass AppsClient {\n  constructor(\n    private readonly env: AuthEnvironment,\n    private session: StoredSession,\n  ) {}\n\n  async call<T>(\n    send: (accessToken: string) => Promise<AppsApiResult<T>>,\n  ): Promise<T> {\n    let result = await send(this.session.accessToken);\n    if (result.status === 'unauthorized') {\n      this.session = await refreshStoredSession(this.env, this.session);\n      result = await send(this.session.accessToken);\n    }\n    if (result.status === 'ok') return result.data;\n    throw authRequiredError(\n      `The session for ${this.env.host} could not authorize the apps call.`,\n      `Run \"ekanos login --host ${this.env.host}\" and retry.`,\n    );\n  }\n}\n\nfunction canPrompt(ctx: CliContext, args: AppsArgs): boolean {\n  return !ctx.jsonMode && (args.stdinIsTTY ?? process.stdin.isTTY === true);\n}\n\nfunction parseSubcommand(value: string | undefined): AppsSubcommand {\n  const match = APPS_SUBCOMMANDS.find((name) => name === value);\n  if (match) return match;\n  throw usageError(\n    value ? `Unknown apps subcommand \"${value}\".` : 'apps needs a subcommand.',\n    `Run one of: ${APPS_SUBCOMMANDS.map((name) => `ekanos apps ${name} <product>`).join(', ')}.`,\n  );\n}\n\nfunction requireProduct(value: string | undefined, verb: string): string {\n  const slug = value?.trim().toLowerCase();\n  if (slug && /^[a-z0-9][a-z0-9-]*$/.test(slug)) return slug;\n  throw usageError(\n    value\n      ? `\"${value}\" is not a product slug.`\n      : `apps ${verb} needs a product.`,\n    `Pass the product's slug, e.g. \"ekanos apps ${verb} linear\". \"ekanos catalog\" lists them.`,\n  );\n}\n\nasync function promptLine(question: string): Promise<string> {\n  const readline = await import('node:readline/promises');\n  const rl = readline.createInterface({\n    input: process.stdin,\n    output: process.stderr,\n  });\n  try {\n    return await rl.question(question);\n  } finally {\n    rl.close();\n  }\n}\n\n/** Read a line without echoing it: the secret never appears on screen or in scrollback. */\nasync function promptHidden(question: string): Promise<string> {\n  const readline = await import('node:readline');\n  process.stderr.write(question);\n  const rl = readline.createInterface({\n    input: process.stdin,\n    output: process.stderr,\n    terminal: true,\n  });\n  // Swallow readline's echo of each keystroke; the question is already written.\n  (rl as unknown as { _writeToOutput: (text: string) => void })._writeToOutput =\n    () => {};\n  try {\n    return await new Promise<string>((resolve) => {\n      rl.question('', resolve);\n    });\n  } finally {\n    rl.close();\n    process.stderr.write('\\n');\n  }\n}\n"]}
+{"version":3,"file":"apps.js","sourceRoot":"","sources":["../../src/commands/apps.ts"],"names":[],"mappings":"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","sourcesContent":["import type { ProviderAppStatus } from '@ekanos/integration-schema';\n\nimport {\n  type AppsApiResult,\n  setProviderApp,\n  showProviderApp,\n} from '../apps-api';\nimport type { StoredSession } from '../auth/credential-store';\nimport {\n  type AuthEnvironment,\n  refreshStoredSession,\n  requireSession,\n  resolveAuthEnvironment,\n} from '../auth/session';\nimport type { CliContext } from '../context';\nimport { authRequiredError, usageError, validationError } from '../errors';\nimport type { ExitCode } from '../exit-codes';\nimport { resolveSourceTarget } from '../source-target';\nimport type { ResultRow } from '../ui';\nimport { promptYesNo } from './publish';\n\nexport const APPS_SUBCOMMANDS = ['show', 'set'] as const;\ntype AppsSubcommand = (typeof APPS_SUBCOMMANDS)[number];\n\nexport interface AppsArgs {\n  host?: string;\n  source?: string;\n  subcommand?: string;\n  product?: string;\n  dir: string;\n  env: Record<string, string | undefined>;\n  stdinIsTTY?: boolean;\n  /** Test seams for the questions `set` asks. */\n  ask?: (question: string) => Promise<string>;\n  askSecret?: (question: string) => Promise<string>;\n  confirm?: (question: string) => Promise<boolean>;\n}\n\n/**\n * `apps` — a Source's provider apps: the OAuth client an integration signs\n * every team in through (Linear's, say). `show` says whether the Source has\n * one and which callback URL to register; `set` takes the client id and\n * secret from the Source admin at the terminal — never from a flag, a file\n * or a non-interactive run, so an agent driving the CLI never handles the\n * secret.\n */\nexport async function runApps(\n  ctx: CliContext,\n  args: AppsArgs,\n): Promise<ExitCode> {\n  const subcommand = parseSubcommand(args.subcommand);\n  const product = requireProduct(args.product, subcommand);\n\n  if (subcommand === 'set' && !canPrompt(ctx, args)) {\n    throw usageError(\n      'apps set takes the client secret at a terminal, never in a script or an agent run.',\n      `Run it yourself in your terminal: npx @ekanos/cli apps set ${product}${args.source ? ` --source ${args.source}` : ''}`,\n    );\n  }\n\n  const env = resolveAuthEnvironment(ctx, args.host, args.env, {\n    projectDir: args.dir,\n  });\n  const resolved = await resolveSourceTarget(\n    env,\n    requireSession(env.store, env.host),\n    args,\n  );\n  const client = new AppsClient(env, resolved.session);\n  const source = resolved.source;\n\n  const status = await client.call((token) =>\n    showProviderApp(env.host, token, source, product),\n  );\n\n  if (subcommand === 'show') {\n    return ctx.succeed({ host: env.host, ...status }, summary(ctx, status));\n  }\n\n  ctx.log(walkthrough(status).join('\\n'));\n  if (status.configured) {\n    const replace = await (args.confirm ?? promptYesNo)(\n      `${status.source.slug} already has ${status.product.name} credentials. Replace them? [y/N]`,\n    );\n    if (!replace) {\n      throw validationError(\n        'Nothing was changed.',\n        `Run \"ekanos apps show ${product}\" to see the current state.`,\n      );\n    }\n  }\n\n  const clientId = (await (args.ask ?? promptLine)('Client ID: ')).trim();\n  const clientSecret = (\n    await (args.askSecret ?? promptHidden)('Client secret (hidden): ')\n  ).trim();\n  if (!clientId || !clientSecret) {\n    throw validationError(\n      'Both the client ID and the client secret are needed.',\n      `Run \"ekanos apps set ${product}\" again.`,\n    );\n  }\n\n  const result = await client.call((token) =>\n    setProviderApp(env.host, token, {\n      source,\n      product,\n      clientId,\n      clientSecret,\n    }),\n  );\n  return ctx.succeed(\n    { host: env.host, ...result },\n    ctx.ui.result({\n      title: result.replaced\n        ? `Replaced the ${result.product.name} app`\n        : `Set up the ${result.product.name} app`,\n      rows: [\n        ['Source', result.source.slug],\n        ['Teams can connect', result.configured ? 'yes' : 'not yet'],\n        ['Callback URLs', callbackUrls(result)],\n      ],\n    }),\n  );\n}\n\n/**\n * How to create the app: the integration's own steps (`oauth.setup`, with the\n * callback URL filled in) when it declares them, else the generic three.\n */\nexport function walkthrough(status: ProviderAppStatus): string[] {\n  const name = status.product.name;\n  const lines = [`${name} app for ${status.source.slug}`];\n  if (status.setup?.consoleUrl) {\n    lines.push(`  Open: ${status.setup.consoleUrl}`);\n  }\n  const steps = status.setup?.steps.length\n    ? [\n        ...status.setup.steps,\n        `Check the app lists exactly: ${callbackUrls(status).join(', ')}`,\n      ]\n    : [\n        `In ${name}, create an OAuth app (or open the one you use).`,\n        `Register exactly these callback URLs: ${callbackUrls(status).join(', ')}`,\n      ];\n  steps.push(\n    \"Enter its client ID and secret below. The secret is stored in Ekanos's vault and never shown again.\",\n  );\n  lines.push(...steps.map((step, index) => `  ${index + 1}. ${step}`));\n  if (status.setup?.guideUrl) lines.push(`  Guide: ${status.setup.guideUrl}`);\n  return lines;\n}\n\nfunction summary(ctx: CliContext, status: ProviderAppStatus): string {\n  const rows: ResultRow[] = [\n    ['Source', status.source.slug],\n    ...(status.setup\n      ? ([\n          [\n            'How to create it',\n            [\n              ...(status.setup.consoleUrl\n                ? [`Open ${status.setup.consoleUrl}`]\n                : []),\n              ...status.setup.steps.map(\n                (step, index) => `${index + 1}. ${step}`,\n              ),\n            ],\n          ],\n        ] as const)\n      : []),\n    [\n      'Set up',\n      status.configured\n        ? 'yes — teams can connect'\n        : 'no — no team can connect yet',\n    ],\n    ['Callback URLs', callbackUrls(status)],\n  ];\n  return [\n    ctx.ui.result({ title: `${status.product.name} app`, rows }),\n    ...(status.configured\n      ? []\n      : [\n          ctx.ui.hint(\n            `Run \"ekanos apps set ${status.product.slug}\" in your terminal to enter its credentials.`,\n          ),\n        ]),\n  ].join('\\n');\n}\n\nclass AppsClient {\n  constructor(\n    private readonly env: AuthEnvironment,\n    private session: StoredSession,\n  ) {}\n\n  async call<T>(\n    send: (accessToken: string) => Promise<AppsApiResult<T>>,\n  ): Promise<T> {\n    let result = await send(this.session.accessToken);\n    if (result.status === 'unauthorized') {\n      this.session = await refreshStoredSession(this.env, this.session);\n      result = await send(this.session.accessToken);\n    }\n    if (result.status === 'ok') return result.data;\n    throw authRequiredError(\n      `The session for ${this.env.host} could not authorize the apps call.`,\n      `Run \"ekanos login --host ${this.env.host}\" and retry.`,\n    );\n  }\n}\n\nfunction canPrompt(ctx: CliContext, args: AppsArgs): boolean {\n  return !ctx.jsonMode && (args.stdinIsTTY ?? process.stdin.isTTY === true);\n}\n\nfunction parseSubcommand(value: string | undefined): AppsSubcommand {\n  const match = APPS_SUBCOMMANDS.find((name) => name === value);\n  if (match) return match;\n  throw usageError(\n    value ? `Unknown apps subcommand \"${value}\".` : 'apps needs a subcommand.',\n    `Run one of: ${APPS_SUBCOMMANDS.map((name) => `ekanos apps ${name} <product>`).join(', ')}.`,\n  );\n}\n\nfunction requireProduct(value: string | undefined, verb: string): string {\n  const slug = value?.trim().toLowerCase();\n  if (slug && /^[a-z0-9][a-z0-9-]*$/.test(slug)) return slug;\n  throw usageError(\n    value\n      ? `\"${value}\" is not a product slug.`\n      : `apps ${verb} needs a product.`,\n    `Pass the product's slug, e.g. \"ekanos apps ${verb} linear\". \"ekanos catalog\" lists them.`,\n  );\n}\n\nasync function promptLine(question: string): Promise<string> {\n  const readline = await import('node:readline/promises');\n  const rl = readline.createInterface({\n    input: process.stdin,\n    output: process.stderr,\n  });\n  try {\n    return await rl.question(question);\n  } finally {\n    rl.close();\n  }\n}\n\n/** Read a line without echoing it: the secret never appears on screen or in scrollback. */\nasync function promptHidden(question: string): Promise<string> {\n  const readline = await import('node:readline');\n  process.stderr.write(question);\n  const rl = readline.createInterface({\n    input: process.stdin,\n    output: process.stderr,\n    terminal: true,\n  });\n  // Swallow readline's echo of each keystroke; the question is already written.\n  (rl as unknown as { _writeToOutput: (text: string) => void })._writeToOutput =\n    () => {};\n  try {\n    return await new Promise<string>((resolve) => {\n      rl.question('', resolve);\n    });\n  } finally {\n    rl.close();\n    process.stderr.write('\\n');\n  }\n}\n\n/** Every redirect URI to register; an older host sends only the one. */\nfunction callbackUrls(status: ProviderAppStatus): string[] {\n  return status.callbackUrls?.length\n    ? status.callbackUrls\n    : [status.callbackUrl];\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ekanos/cli",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "private": false,
   "description": "The Ekanos partner toolchain CLI: scaffold, validate, and test an Ekanos integration against the published @ekanos packages. Agent-native — every verb speaks JSON with a stable exit-code taxonomy.",
   "keywords": [
@@ -35,7 +35,7 @@
   },
   "dependencies": {
     "@clack/prompts": "1.7.0",
-    "@ekanos/integration-schema": "0.11.0",
+    "@ekanos/integration-schema": "0.12.0",
     "esbuild": "0.28.1",
     "picocolors": "1.1.1"
   },

package/templates/package.json.tmpl

@@ -12,12 +12,12 @@
     "prepare": "node scripts/setup-hooks.mjs"
   },
   "dependencies": {
-    "@ekanos/sdk": "^0.11.0",
-    "@ekanos/ui": "^0.11.0"
+    "@ekanos/sdk": "^0.12.0",
+    "@ekanos/ui": "^0.12.0"
   },
   "devDependencies": {
-    "@ekanos/cli": "^0.8.0",
-    "@ekanos/harness": "^0.7.2",
+    "@ekanos/cli": "^0.9.0",
+    "@ekanos/harness": "^0.7.3",
     "@hookform/resolvers": "^5.2.2",
     "@tailwindcss/postcss": "^4.3.3",
     "@tanstack/react-query": "^5.101.4",

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

@@ -45,22 +45,28 @@ every `hint`. Look things up in the `ekanos-sdk-docs` MCP server
    - **Not set up yet** — offered but not enabled, or a setup step left
      (`setupSteps` says who: `ekanos` = an Ekanos super admin, `source_admin`
      = the user if they hold that seat, `team` = each team). The common one a
-     Source admin can clear: an integration's **app for the Source** is not
-     set up, so no team can connect. Run
-     `npx @ekanos/cli apps show <product> --source <slug> --json` for the
-     callback URL to register in the provider, then ask the user to run
-     `npx @ekanos/cli apps set <product> --source <slug>` **in their own
-     terminal** — it asks for the secret there; never ask for it in chat.
-     The agent can be drafted while that is pending.
+     Source admin clears: an integration's **app for the Source** (step
+     `provider-app`) is not set up, so no team can connect. Offer to walk them
+     through it now — `references/app-setup.md` — or after the interview. The
+     agent can be drafted while it is pending.
    - **Missing** — no product does it. Say so plainly. Options: build the
      integration (the `build-integration` skill), use a remote MCP server
      instead if the service offers one (common for docs and knowledge bases:
-     a Mintlify docs site serves one at `https://<docs-host>/mcp`), or ship
+     a Mintlify docs site serves one at `https://<docs-host>/mcp`, and
+     knowledge bases such as Guru offer their own — check the service's docs
+     for its MCP URL and whether it needs sign-in), or ship
      the agent without it and add it in a later version.
 
 Tell the user this map in a few lines before the interview. Don't hide a gap
 behind a plan that assumes it away.
 
+## Setting up an app, step by step
+
+When a provider app or a team app is not set up and the user wants to do it,
+follow `references/app-setup.md`: one step at a time, in the provider's own
+console words, with the exact URLs to paste from the catalog, waiting for the
+user after each step, and the secret entered only at their terminal.
+
 ## 2. The interview
 
 One topic per message. Summarize what you heard before moving on. Defaults

package/templates/skills/build-agent/references/app-setup.md

@@ -0,0 +1,64 @@
+# Walking a Source admin through an app setup
+
+Most integrations sign people in through an OAuth **app** someone creates in
+the provider's console. Two kinds:
+
+- **The Source's app** (setup step `provider-app`, actor `source_admin`) —
+  one app every team on the Source connects through, e.g. Linear's. For a
+  white-label Source this is the common case and it is *their* app: their
+  product name and their company on the provider's consent screen, not
+  Ekanos's. Set it up once per Source.
+- **A team's own app** (setup step `team-app:<id>`, actor `team`) — each team
+  creates one, e.g. Zendesk's OAuth client or Linear's agent app. When the
+  user is testing as a team, walk them through it the same way.
+
+## Get the facts first — never invent them
+
+1. `npx @ekanos/cli catalog <product> --source <slug> --json`: the step's
+   `instructions` (the integration's own steps, already filled with the
+   Source's exact callback URLs and scopes), `consoleUrl`, `guideUrl`.
+2. For the Source's app, also
+   `npx @ekanos/cli apps show <product> --source <slug> --json`:
+   `callbackUrls` (every redirect URI to register — the Source's own
+   domains first, then its subdomain), `configured`, and `setup`.
+
+If a step has no `instructions`, say the integration ships none, use the
+`guideUrl` or the provider's docs (search them), and be explicit that you are
+working from those rather than from Ekanos.
+
+## Walk it
+
+- One step per message. Start with the `consoleUrl` as a link.
+- Say what to type in each field, in the console's words. For a white-label
+  Source: the app's **name** is the Source's product name (ask what their
+  customers call it), the **developer / company** is the Source's company,
+  and any homepage is theirs. Ask once and reuse the answers.
+- Paste URLs **exactly** as the catalog gives them — every callback URL in
+  `callbackUrls`, each on its own line. Providers match redirect URIs
+  byte for byte.
+- After each step, wait for "done" (or a question). If they report something
+  the steps don't cover — a field you didn't name, an error — look it up in
+  the provider's docs rather than guessing.
+- The last console step is always "copy the client ID and the secret".
+  **Never ask them to paste the secret into the chat.** For the Source's app,
+  have them run, **in their own terminal**:
+
+  ```bash
+  npx @ekanos/cli apps set <product> --source <slug>
+  ```
+
+  It asks for the client ID, then the secret with hidden input. For a team's
+  app, they enter the fields in the team's setup panel in the Ekanos app.
+- Then check: `apps show <product> --source <slug> --json` should say
+  `configured: true`, and the catalog's step should be `done`. Tell them
+  teams can now connect, and what the team-side steps are.
+
+## When it goes wrong
+
+- `apps set` says it needs a terminal: it was run inside Claude or a script.
+  Ask them to run it in a terminal tab themselves.
+- `apps set` asks which host: they are signed in to more than one Ekanos;
+  add `--host <url>` (the Source's site) or log out of the other.
+- Sign-in later fails with a redirect mismatch: the app is missing one of the
+  `callbackUrls` (often a custom domain added after the app was made). Re-run
+  `apps show` and add the missing one in the provider's console.

package/templates/skills/ekanos-platform/SKILL.md

@@ -72,11 +72,14 @@ Ask them in this order; each catalog product reports where it stands
 
 Some integrations sign every team in through **one app for the whole Source**
 (Linear's OAuth app, say): until the Source has its credentials, no team can
-connect (`setupSteps` step `provider-app`). A Source admin sets it up —
-`ekanos apps show <product>` gives the callback URL to register with the
-provider, and `ekanos apps set <product>`, run by the admin at their own
-terminal, takes the client ID and secret. Integrations whose teams each bring
-their own app (Zendesk) have no Source app.
+connect (`setupSteps` step `provider-app`). It is the Source's own app — for a
+white-label Source, under its product name and company — and its admin
+creates it once in the provider's console. The integration ships the steps
+(the catalog's `instructions`, with the Source's exact callback URLs filled
+in); `ekanos apps set <product>`, run by the admin at their own terminal,
+takes the client ID and secret. The `build-agent` skill walks through it
+(`references/app-setup.md`). Integrations whose teams each bring their own
+app (Zendesk) have no Source app; each team follows that app's steps.
 
 A product that is "enabled" is not therefore "connected". Say which one you
 mean.