@ekanos/cli 0.8.0 → 0.10.0

package/templates/skills/build-agent/references/set-up-an-integration.md

@@ -0,0 +1,133 @@
+# Setting up an integration, concierge-style
+
+The user wants an agent to use something (Zendesk, Linear, Slack…) and it is
+not ready yet. Your job is to get it ready **with** them, the way a good
+concierge would: you already know the way, you say what happens next and
+why, you hand them exactly what to type or paste, and you check that each
+step worked before moving on. They should never have to read a manual or
+guess.
+
+## 1. Find out where it stands (before saying anything)
+
+1. `npx @ekanos/cli catalog <product> --source <slug> --json`. Its
+   `setupSteps` are the integration's own steps, already filled in with this
+   Source's exact callback URLs and scopes. Each step has an `actor`:
+   `ekanos` (an Ekanos super admin), `source_admin` (the user, if they hold
+   that seat), or `team`.
+2. Which teams will use it: `npx @ekanos/cli teams list --source <slug> --json`.
+3. For a team: `npx @ekanos/cli teams show <team> <product> --source <slug> --json`
+   shows what that team has already done (app fields entered, webhook URL
+   minted, connected, who connected and when) and the link to the team's page
+   in the app.
+
+Then tell the user, in two or three lines, what is done, what is left, and
+who does each remaining step. If a step needs Ekanos (the product is not
+enabled for the Source), say so and stop there for that product; nobody else
+can do it.
+
+## 2. Decide where the connection lives
+
+Explain the choice in plain words, recommend one, and let them pick. There
+are three places, and **the team account is the default owner** of an
+integration: its members, its data and its connections.
+
+| Where | What it means | Who sets it up | Typical for |
+|---|---|---|---|
+| **Each team, through the Source's app** | One app, created once for the whole Source under the Source's own name. Each team then signs in through it. | The Source admin creates the app (`references/app-setup.md`, `ekanos apps set`); each team connects | Linear, Slack: products where every team is a separate workspace |
+| **Each team, with its own app** | Each team creates its own app in the provider and enters its credentials | Each team, or the Source admin on the team's behalf with `ekanos teams` (below) | Zendesk: each bank or business has its own Zendesk |
+| **One connection for the whole Source** | Every team's provided agent uses the Source's single connection, limited to what is routed to that team | The Source admin, once | One shared Zendesk for many teams. **Not available yet**: say so, and suggest a connection per team for now |
+
+The agent records the choice in `agent.json` → `connections`:
+`{ "zendesk": { "owner": "team", "team": "required" } }` means each team
+uses its own Zendesk and the agent waits at "needs setup" until it is
+connected (`references/agent-json.md`).
+
+## 3. Walk it, one step per message
+
+- **Say why before what.** "Zendesk needs to know where to send new tickets,
+  so we'll give it a webhook address from Ekanos." One sentence, then the step.
+- **Exact values only.** Take URLs, field names and console paths from the
+  catalog or `teams show`, never from memory. Paste URLs exactly; providers
+  match them byte for byte.
+- **Use the provider's words** for its screens ("Admin Center › Apps and
+  integrations › Webhooks"), and Ekanos's words for Ekanos.
+- **Wait** for "done" or a question after each step. Then **check**: re-run
+  `teams show` (or `catalog`) and say what changed ("Ekanos sees the client ID
+  and secret now"). If the check disagrees with what they said, look at the
+  difference with them; don't move on.
+- **Secrets never pass through the chat.** Client secrets and signing
+  secrets go in at the user's own terminal (`ekanos apps set`,
+  `ekanos teams app set`, with hidden input) or in the team's page in the app.
+  If they paste one into the chat anyway, tell them to rotate it in the
+  provider's console and enter the new one at the terminal.
+- **Signing in is a person's click.** Connecting (the provider's consent
+  screen) happens in the browser, by someone on the team, from the link in
+  `teams show`. Tell them who should click it: the account the integration
+  acts as. A dedicated seat such as "Support agent" makes its replies easy
+  to recognise.
+- **Close each product out**: one line on what now works ("New tickets in
+  Acme's Zendesk will start the support agent"), then move on to the next
+  product or back to the agent.
+
+## 4. A team's own app, from the terminal
+
+When the user is a Source admin setting things up for a team (common in a
+pilot), the team-side steps can be done from the CLI:
+
+1. `npx @ekanos/cli teams show <team> <product> --source <slug>`: the
+   callback URL to register and the integration's steps.
+2. They create the app in the provider's console, step by step as above.
+3. **In their own terminal:**
+   `npx @ekanos/cli teams app set <team> <product> --source <slug>`. It asks
+   for each field and hides the secret ones. It refuses to run inside Claude;
+   that is deliberate.
+4. If the integration takes webhooks:
+   `npx @ekanos/cli teams webhook <team> <product> --source <slug>` prints the
+   team's webhook URL **once**. Have them paste it into the provider at that
+   moment. Running it again makes a new URL and the old one stops working, so
+   it asks for `--yes` when one already exists.
+5. Someone on the team opens the link from `teams show` and clicks Connect.
+6. `teams show` again: every step ✓.
+
+## Worked example: Zendesk for one team
+
+The steps below are what Zendesk's own setup says, in order. Take the URLs
+from `teams show zendesk`.
+
+1. **OAuth client.** Admin Center › Apps and integrations › APIs › OAuth
+   Clients › Add OAuth client. Client kind **Confidential**, Redirect URL =
+   the callback URL. Save; copy the Identifier and the Secret (shown once).
+2. **Webhook address.** `ekanos teams webhook <team> zendesk`, then in Admin
+   Center › Apps and integrations › Webhooks › Create webhook › Trigger or
+   automation: that URL, POST, JSON, no authentication. Open it and Reveal
+   secret.
+3. **Credentials into Ekanos.** `ekanos teams app set <team> zendesk` in
+   their terminal: subdomain, client ID, client secret, webhook signing
+   secret.
+4. **Connect.** Someone on the team opens the link and connects, as the
+   Zendesk agent the integration should reply as.
+5. **Zendesk triggers.** Objects and rules › Triggers: one for *Ticket is
+   Created* and one for a customer's public reply, each notifying the webhook
+   with the body from the steps. `"reply_as": "internal"` makes the agent's
+   answer an internal note a person reviews before the customer sees it.
+   Recommend that until the team trusts the agent; `"public"` lets it answer
+   the customer directly.
+6. **The agent's trigger.** In the app, on the agent: *A ticket is created*
+   (and *A customer replies*), with any filters.
+7. **Try it.** Open a test ticket as a customer and watch: the agent reads
+   the ticket, looks things up, and answers on it. If it wants to change the
+   ticket (status, priority, assignee), it leaves an internal note saying
+   what it asked for, and someone approves it in Ekanos.
+
+## When something goes wrong
+
+- **Redirect mismatch on Connect:** the callback URL in the provider differs
+  from `teams show`'s, often by a trailing slash or a custom domain. Fix it in
+  the provider.
+- **Tickets don't start the agent:** `teams show` should list a live webhook
+  that has been used recently. If it has never been used, the provider is not
+  calling it: check the Zendesk trigger's conditions and that it notifies the
+  right webhook. If it has been used but nothing ran, check that the agent has
+  a trigger for that event and that the team connected the product.
+- **A command says it needs a terminal:** it was run inside Claude. Ask them
+  to run it in a terminal tab themselves.

package/templates/skills/build-agent/references/triggers.md

@@ -33,7 +33,8 @@ Guide: https://sdk.ekanos.dev/guides/linear-agent
 **Zendesk** (`zendesk.ticket_created`, `zendesk.comment_added`; filters such
 as brand, group, tags, organization) — when present in the catalog, each team
 connects its own Zendesk (subdomain plus an OAuth client it creates in
-Zendesk) and adds a Zendesk webhook pointing at its Ekanos endpoint. The agent
+Zendesk) and adds a Zendesk webhook pointing at its Ekanos endpoint
+(walk-through: `set-up-an-integration.md`, worked example). The agent
 answers on the ticket as a public reply or an internal note — recommend
 internal notes, or approval on public replies, until the team trusts it.
 

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

@@ -62,8 +62,12 @@ Ask them in this order; each catalog product reports where it stands
    is an Ekanos super admin's step (`setupSteps` names it with actor
    `ekanos`) — not something a Source admin or the CLI can do.
 2. **Connected by a team** — a team (or a person, for per-person
-   integrations) signed in to the third party. Connections belong to a team,
-   never to the Source: two teams using Linear each connect their own.
+   integrations) signed in to the third party. The team account owns the
+   connection: two teams using Linear each connect their own. A Source admin
+   can do a team's setup for it from the terminal (`ekanos teams show`,
+   `ekanos teams app set`, `ekanos teams webhook`), but signing in is a click
+   by someone on the team. One connection for the whole Source, shared by
+   every team's agents, is not available yet.
 3. **Set up by the team** where needed — some integrations have each team
    bring its own app (a team-provided app: client id, secret, webhook signing
    secret entered in Ekanos). Those secrets are typed into the app, never
@@ -72,11 +76,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.
@@ -104,4 +111,5 @@ The `build-agent` skill walks through choosing between these and building one.
 | 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 |
+| A team's own app for an integration (client ID, secrets, webhook URL) | The team in the app, or a Source admin with `ekanos teams` |
 | Connecting an integration; turning on a provided agent; its triggers | Each team, in the app |