@ekanos/cli 0.6.0 → 0.8.0

package/templates/skills/build-integration/references/oauth-setup.md

@@ -41,6 +41,26 @@ the default is HTTP Basic (`'client_secret_basic'`), but a provider that wants
 harness derives the rest — provider host, redirect URI, scopes, PKCE — from
 `defineIntegration({ oauth })`, so do not repeat those in `notes`.
 
+Also declare the same guidance **on the connection itself** for the hosted
+product — `setup` in `defineIntegration({ oauth: { … } })` (and on each
+`oauthConnections` entry). That is what a Source admin sees in `ekanos apps`
+and a team sees in its setup panel once the integration is live:
+
+```ts
+setup: {
+  consoleUrl: 'https://<provider developer console>/apps/new',
+  steps: [
+    'Create an app and set its callback URL to {callbackUrl}.',
+    'Enable the scopes {scopes}.',
+    'Copy <the console's name for the client id> and <for the secret>.',
+  ],
+},
+```
+
+Ekanos fills `{callbackUrl}` and `{scopes}`; write the console's own words
+for everything else. `ekanos validate` warns (`oauth.setup-missing`) about
+a connection without it.
+
 ## What the harness then shows (so you can point the user at it)
 
 The Activation surface (`npx ekanos dev` → `http://localhost:3100/<slug>/activation`)

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

@@ -29,19 +29,19 @@ docs — ask, or check the CLI.
 
 ## Seats: who can use the CLI on a Source
 
-`npx ekanos sources --json` lists the user's seats.
+`npx @ekanos/cli sources --json` lists the user's seats.
 
 | Seat | Can |
 |---|---|
 | `developer` | Submit integrations; read the catalog; apply agent **drafts** |
-| `source_admin` | Everything a developer can, plus **publish** agents to every team and manage the Source's roster |
+| `source_admin` | Everything a developer can, plus **publish** agents to every team, set up the Source's **provider apps** (`ekanos apps`), and manage the Source's roster |
 
 Only an Ekanos super admin grants seats. If the user lacks the seat a step
 needs, say which and stop — there is no way around it from the CLI.
 
 ## Products: integrations and experiences
 
-Everything in the catalog (`npx ekanos catalog --source <slug> --json`) is a
+Everything in the catalog (`npx @ekanos/cli catalog --source <slug> --json`) is a
 **product** of one of two kinds:
 
 - **Integration** — a connection to a third party (Linear, Zendesk, Slack…).
@@ -70,6 +70,14 @@ Ask them in this order; each catalog product reports where it stands
    into a chat or a file.
 4. **Used by an agent** — granted in the agent's tools.
 
+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.
+
 A product that is "enabled" is not therefore "connected". Say which one you
 mean.
 
@@ -95,4 +103,5 @@ The `build-agent` skill walks through choosing between these and building one.
 | Making a product available to a Source; granting seats | Ekanos super admin, in Ekanos's admin |
 | Building or updating an integration | A developer, with `ekanos validate` / `ekanos publish` |
 | Agents provided for every team | A Source admin, with `ekanos agents` |
+| An integration's app for the whole Source (client ID and secret) | A Source admin, with `ekanos apps set` at their own terminal |
 | Connecting an integration; turning on a provided agent; its triggers | Each team, in the app |