@ekanos/cli 0.10.0 → 0.12.0

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

@@ -34,11 +34,42 @@ docs — ask, or check the CLI.
 | Seat | Can |
 |---|---|
 | `developer` | Submit integrations; read the catalog; apply agent **drafts** |
-| `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 |
+| `source_admin` | Everything a developer can, plus **publish** agents to every team, set up the Source's **provider apps** (`ekanos apps`), name its **reviewers** (`ekanos reviewers`), 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.
 
+## Onboarding a team (Source admin)
+
+A Source admin can stand a team up end to end from the terminal. Every
+command takes `--source <slug>` (else the Source `ekanos use` set) and
+`--json`:
+
+```sh
+npx @ekanos/cli teams create "Bank A" --slug bank-a           # you are its owner
+npx @ekanos/cli teams create "Bank A" --owner ana@bank-a.com  # ana is invited as owner
+npx @ekanos/cli teams roles list bank-a                       # roles + permissions (e.g. agents.review)
+npx @ekanos/cli teams members invite bank-a raj@bank-a.com --role admin   # default role: member
+npx @ekanos/cli teams members list bank-a                     # members and pending invitations
+npx @ekanos/cli teams members role bank-a raj@bank-a.com member
+npx @ekanos/cli teams members remove bank-a raj@bank-a.com --yes
+npx @ekanos/cli teams connect bank-a zendesk                  # the link a member opens to connect
+```
+
+- `create` without `--owner` seats the person running it as the team's
+  owner. With `--owner`, that person gets the invitation email and becomes
+  the owner when they accept. Say which happened.
+- An invitation is an email sent from the Source's own address; the person
+  joins when they accept it. `members role` / `members remove` on someone who
+  has not accepted yet change or withdraw the invitation.
+- Roles are the team roles (owner / admin / member, or the Source's own
+  customized ones). Pick a reviewer for agents by the role holding
+  `agents.review` in `teams roles list`. The primary owner's role cannot be
+  changed here; ownership moves in the app.
+- Connecting an integration is always a team member signing in in their
+  browser. `teams connect` prints the link to send them and whether the team
+  is connected yet; `teams show <team> <product>` has the full checklist.
+
 ## Products: integrations and experiences
 
 Everything in the catalog (`npx @ekanos/cli catalog --source <slug> --json`) is a
@@ -66,8 +97,12 @@ Ask them in this order; each catalog product reports where it stands
    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.
+   by someone on the team. For integrations that support it, a Source admin
+   can instead connect **once for the whole Source** (`ekanos apps connect`),
+   for provided agents only: events are routed to teams by a value inside
+   them (`ekanos routes`, Zendesk by organization), and each team's agent
+   works only inside its own routed values. A team never sees that
+   connection.
 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
@@ -97,12 +132,78 @@ changed through the CLI or the app, with no deploy.
 - **Provided for every team** — a Source admin defines it once with
   `ekanos agents` (a template). Each team sees it under Agents → "Provided for
   your team" and turns it on; it then runs on that team's own connections.
-  Publishing a new version updates every team that follows it.
+  Publishing a new version updates every team that follows it. The template
+  can also set what starts it (triggers), which other agents it works with
+  (links) and which calls wait for approval, and — per area, with
+  `teamOverrides` — whether a team may change them. The template wins unless
+  an area is opened to teams.
 - **A team's own** — built by a team in the app (Agents → New). Only that team
   has it, and the Source cannot update it.
 
+Skills are folders (`SKILL.md` + references) an agent loads when needed.
+A Source admin pushes them with `ekanos skills push <dir>`: at Source level
+every team can use them, with `--team <slug>` only that team can.
+
 The `build-agent` skill walks through choosing between these and building one.
 
+A Source admin can also do a team's agent setup from the terminal, acting on
+that team (every write is recorded under the admin's own name). The shape is
+always `ekanos teams <area> <verb> <team> …`:
+
+- `ekanos teams agents list <team>` — provided agents, on or off, the version
+  each runs (pinned or following), triggers, links, the team's MCP servers,
+  and what each still needs connected.
+- `ekanos teams agents enable <team> <key> [--as <member-email>]` /
+  `disable <team> <key>` — the app's "Turn on" / "Turn off". The agent runs
+  as a team member who manages agents (the team's owner by default); that
+  person confirms in the app that it may use their connections.
+- `ekanos teams agents pin <team> <key> <version>` / `unpin <team> <key>`.
+- `ekanos teams agents policy <team> <key>` — every tool the agent can call,
+  read or write, and whether it runs on its own or waits for approval;
+  `… policy <team> <key> set <tool> auto|approve`, `unset <tool>`,
+  `--reads auto|approve --writes auto|approve`. A provided agent's policy
+  follows its template unless the template turns on team overrides for it.
+- `ekanos teams triggers list|add|remove <team> <key> …` — manual, schedule
+  (`--cron`, `--timezone`), webhook (URL and token shown once) and
+  integration events (`event zendesk.ticket_created --filter '{…}'`).
+- `ekanos teams links list|add|remove <team> <from-key> [<to-key>] --kind
+  talk|delegate [--mode await|handoff]`.
+- `ekanos teams mcp list|add|status|token|effect <team> [<server-key> …]` — a
+  team's own MCP server (`--url`, `--auth none|token|oauth`); a token is typed
+  at the admin's terminal with hidden input, never in chat or arguments; OAuth
+  prints a link for a team member to open.
+
+Triggers, links and the policy of a provided agent follow its template by
+default; when the template has not turned on team overrides for that area,
+these commands show the template's settings and refuse to change them.
+
+### Reviewers
+
+A call that waits for a person (the `approve` policy — a customer reply
+draft, usually) is decided by the Source's **named reviewers**. A Source
+admin picks them from the Source's own users — anyone who is a member of one
+of its teams — each at a reach:
+
+- **`source`** — decides drafts from every team's provided agents, in the
+  Source's review queue at `/reviews` (reviewers are managed at
+  `/management/reviewers`).
+- **`team`** — decides one named team's drafts, from the same review queue
+  (they need not be a member of that team).
+
+The first decision settles a draft for everyone; it then leaves every other
+reviewer's queue.
+
+```
+npx @ekanos/cli reviewers list --source <slug> --json
+npx @ekanos/cli reviewers add <email> --reach source --source <slug>
+npx @ekanos/cli reviewers add <email> --reach team --team <team-slug> --source <slug>
+npx @ekanos/cli reviewers remove <email> [--team <team-slug>] --source <slug>
+```
+
+`remove` without `--team` takes the person off at every reach; with it, only
+that team's. Adding someone who is not a member of any of the Source's teams
+is refused (`USER_NOT_IN_SOURCE`): `ekanos teams list` shows the teams.
+
 ## Where each thing is done
 
 | Done by | Where |
@@ -110,6 +211,16 @@ 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` |
+| Testing an unpublished agent version on one team | A Source admin, with `ekanos agents test <key> --team <slug>` |
+| Running a team's agent, reading its runs (transcript, tool calls) | A team's agent manager in the app, or a Source admin with `ekanos runs` |
+| Deciding what an agent run waits on (approve, reject, edit & send a reply) | A team's agent manager in the app, or a Source admin with `ekanos approvals` |
+| Skills (SKILL.md folders) for every team, or one team's own | A Source admin, with `ekanos skills push` (`--team <slug>` for one team) |
+| Who decides agent drafts that wait for a person | A Source admin, with `ekanos reviewers` |
 | An integration's app for the whole Source (client ID and secret) | A Source admin, with `ekanos apps set` at their own terminal |
+| One connection for the whole Source, used by provided agents in every team | A Source admin, with `ekanos apps connect` (status: `ekanos apps show`), or **Shared integrations › Connections** in the Source admin area |
+| Which team gets which events on that connection (Zendesk organization → team) | A Source admin, with `ekanos routes` (`webhook`, `options`, `set`, `list`, `remove`, `unrouted`, `replay`), or **Shared integrations › Routing** in the Source admin area |
 | 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 |
+| A provided agent's triggers, links and approvals | A Source admin, in the template (`ekanos agents triggers / links / policy / overrides`); teams change them only where `teamOverrides` allows |
+| Creating a team, inviting its members, changing their roles | A Source admin, with `ekanos teams create` / `ekanos teams members` (or the team's owner in the app) |
+| Connecting an integration (signing in) | Each team, in the app |
+| Turning on a provided agent for a team, pinning its version, its triggers, links, MCP servers and approval policy | Each team in the app, or a Source admin with `ekanos teams agents\|triggers\|links\|mcp` |