@ekanos/cli 0.10.0 → 0.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ekanos/cli",
-  "version": "0.10.0",
+  "version": "0.11.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.13.0",
+    "@ekanos/integration-schema": "0.14.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.13.0",
-    "@ekanos/ui": "^0.13.0"
+    "@ekanos/sdk": "^0.14.0",
+    "@ekanos/ui": "^0.14.0"
   },
   "devDependencies": {
-    "@ekanos/cli": "^0.10.0",
-    "@ekanos/harness": "^0.7.4",
+    "@ekanos/cli": "^0.11.0",
+    "@ekanos/harness": "^0.14.0",
     "@hookform/resolvers": "^5.2.2",
     "@tailwindcss/postcss": "^4.3.3",
     "@tanstack/react-query": "^5.101.4",

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

@@ -68,7 +68,12 @@ through it? It takes about ten minutes." Then follow
 `references/set-up-an-integration.md`. It covers where the connection should
 live (each team through the Source's app, each team with its own app, or one
 for the whole Source), the integration's own steps, one per message, and
-checking each one with `ekanos teams show` before moving on. For the
+checking each one with `ekanos teams show` before moving on. If the team
+itself does not exist yet, create it and invite its people first
+(`ekanos teams create`, `ekanos teams members invite`, `ekanos teams roles
+list` to find the role holding `agents.review` for reviewers — see the
+`ekanos-platform` skill, "Onboarding a team"), and send the member who will
+sign in the link from `ekanos teams connect <team> <product>`. For the
 Source's app itself, `references/app-setup.md` has the console walk-through.
 Secrets are only ever entered at the user's terminal or in the app.
 
@@ -88,7 +93,8 @@ in parentheses are the recommendation when the user has no preference.
    (Reads only to start; add writes once it has earned trust.)
 4. **What waits for a person.** Reads run on their own, changes wait for
    approval — and any per-tool exceptions (a public reply to a customer
-   almost always waits). See `references/agent-json.md` → `policy`.
+   almost always waits). See `references/agent-json.md` → `policy`. If
+   anything waits, ask who decides it — see **Reviewers** below.
 5. **Whose connections.** For each product and MCP server, where the
    connection lives (`references/set-up-an-integration.md` § 2): each team
    connects its own, and it is `required` (the agent waits at "needs setup"
@@ -98,10 +104,16 @@ in parentheses are the recommendation when the user has no preference.
 6. **What teams may add** — their own MCP servers, their own skills, more of
    their own integrations, or narrowing (removing tools, more approvals). All
    off unless there is a reason. Give one concrete example per knob.
-7. **What starts it** — see `references/triggers.md`. Triggers belong to each
-   team and are set after turning the agent on; say what each team will have
-   to set up (an @mention, a label, a new ticket, a schedule) and what it
-   needs connected first.
+7. **What starts it** — see `references/triggers.md`. Declare the triggers in
+   the template (an event such as `zendesk.ticket_created` with its filters,
+   a schedule, a webhook) so every team gets them, or leave them to each
+   team. Say what each team needs connected first.
+8. **Who it works with** — other agents of this Source it may ask or hand
+   work to (`links`). A link only exists in a team that runs both agents.
+9. **What teams may change** — `teamOverrides` per area (approvals,
+   triggers, links). Off (the default) means teams follow the template
+   exactly; on lets a team keep its own differences. Switching an area off
+   later keeps a team's differences but stops applying them.
 
 ## 3. Draft, apply, publish
 
@@ -111,21 +123,91 @@ in parentheses are the recommendation when the user has no preference.
    The instructions say: the job, the sources of truth and when to consult
    each, what to do when unsure (ask, or hand to a person), tone, and what
    never to do. Show the user both files and walk through them.
+   Know-how the agent loads only when needed (a policy, a playbook) goes in
+   a skill folder, `agents/<key>/skills/<slug>/SKILL.md` — see
+   `references/skills.md`. Content only one team may see is a **team
+   skill**: `ekanos skills push <dir> --team <team-slug>`.
 2. On their go: `npx @ekanos/cli agents apply agents/<key> --source <slug> --json`.
    A refusal (exit 3) lists each problem with its path in the body — explain
    and fix them together. The stored version is a **draft**: no team sees it.
+   Skill folders beside the agent are pushed first and are **live at once**
+   (unlike the agent) — say so before applying, and show the user what
+   `skills` the output reports as created or changed.
 3. `npx @ekanos/cli agents show <key> --source <slug>` — review the stored draft
    with the user.
+   Then test it on one team that has turned the agent on, without publishing:
+   `npx @ekanos/cli agents test <key> --team <team> --prompt "…" --follow --json`
+   (or `--input example.json` for a real ticket or event). It runs the latest
+   version on that team as a test run — same tools, approvals and audit; the
+   team's current agent still bounds what it may do, so a draft can only do
+   less. A write waits for an approval like any run (see "Running, watching
+   and deciding" below).
 4. Ask: publish this version to every team now? Only on yes:
    `npx @ekanos/cli agents publish <key> --source <slug> --to <n> --yes`.
-5. Hand over the team-side checklist (`references/triggers.md` has the
+5. If anything waits for approval, name its reviewers (**Reviewers**
+   below) before teams turn it on — a draft nobody may decide just waits.
+6. Hand over the team-side checklist (`references/triggers.md` has the
    per-integration parts): find it under Agents → "Provided for your team",
    Turn on, connect what it needs, confirm access, add triggers. Suggest one
    team pilots it first, and plan a first test run with them.
 
+## Reviewers
+
+Reply drafts held under an `approve` policy are decided by the team's own
+managers (`agents.manage`) and reviewers (`agents.review`), and — for agents
+the Source provides — by the Source's **named reviewers**. A Source admin
+names them; each must be a member of one of the Source's teams, and is
+notified of every draft in their reach.
+
+- `npx @ekanos/cli reviewers list --source <slug> --json` — who reviews now.
+- `npx @ekanos/cli reviewers add <email> --reach source --source <slug>` —
+  decides drafts from every team's provided agents, in the Source's review
+  queue at `/reviews` (reviewers are managed at `/management/reviewers`).
+- `npx @ekanos/cli reviewers add <email> --reach team --team <team-slug> --source <slug>`
+  — decides one team's drafts, from the same review queue (they need not be
+  a member of that team).
+- `npx @ekanos/cli reviewers remove <email> [--team <team-slug>] --source <slug>`
+  — every reach, or just that team's.
+
+The first decision settles a draft for everyone. Recommend one or two
+source-reach reviewers for an agent provided to every team, plus team-reach
+reviewers where a team wants its own people deciding. A refusal with
+`USER_NOT_IN_SOURCE` means the person is not on any of the Source's teams yet.
+
 ## Changing it later
 
 `npx @ekanos/cli agents pull <key> --source <slug>` writes the latest version to
 `agents/<key>/`; edit, `apply` (a new draft), `show`, then `publish` on the
-user's yes. `rollback <key> --to <n> --yes` republishes an earlier version.
+user's yes. For one small change, edit the stored draft directly — `agents
+policy <key> set <tool> approve`, `agents triggers <key> add|remove …`,
+`agents links <key> add|remove …`, `agents overrides <key> enable|disable
+<area>` (each stores a new draft; see `references/agent-json.md` § Editing
+one area without a file) — then `publish` on the user's yes. `rollback <key> --to <n> --yes` republishes an earlier version.
 Teams that pinned a version stay on it and are told a newer one exists.
+
+## Running, watching and deciding
+
+All as the Source admin, on one team (`--team <slug>`; `ekanos teams list`
+names them). Add `--json` for a stable record a script can assert on.
+
+- `npx @ekanos/cli runs start <key> --team <team> --prompt "…" [--follow]` —
+  the app's "Run now": runs as the agent's owner under its own tools and
+  approvals, recorded as started by you. `--input <file.json>` passes a
+  payload instead of (or beside) the prompt. `--follow` prints status,
+  messages and each tool call until the run ends or waits on an approval.
+- `npx @ekanos/cli runs list --team <team> [--agent <key>]` — recent runs.
+- `npx @ekanos/cli runs show <run-id> --team <team> --json` — trigger, version
+  (and `draftTemplateVersion` on a test run), output, transcript, every tool
+  call with `authorizedVia` (`auto` or `approved`), and its approvals. A leak
+  test is a script over this: e.g. assert no `transcript` tool result and no
+  `output` contains a value the agent must never reveal.
+- `npx @ekanos/cli approvals list --team <team>` — what is waiting.
+- `npx @ekanos/cli approvals approve <id> --team <team> [--reason "…"]` /
+  `approvals reject <id> --team <team> --reason "…"` — decided as you, with
+  the authority a team's agent manager has in the app.
+- `npx @ekanos/cli approvals edit <id> --team <team> --body ./reply.md` — Edit &
+  send a reply draft: approves it with your text instead. Only reply drafts
+  take an edit.
+
+Never approve on the user's behalf without asking: show them what the agent
+proposes (`approvals list`) and decide only on their word.

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

@@ -33,7 +33,25 @@ conflicting change unless `--overwrite`. Unknown fields are refused.
       "toolEffects": { "search": "read" }
     }
   ],
-  "teamCustomization": { "mcpServers": false, "skills": false, "integrations": false, "narrow": false }
+  "teamCustomization": { "mcpServers": false, "skills": false, "integrations": false, "narrow": false },
+  "triggers": [
+    {
+      "key": "new-tickets",
+      "type": "event",
+      "event": "zendesk.ticket_created",
+      "filter": { "tags": ["vip", "urgent"], "brand": "123", "reply_as": "internal_note" }
+    },
+    {
+      "key": "weekday-digest",
+      "type": "schedule",
+      "cron": "0 9 * * 1-5",
+      "timezone": "America/Los_Angeles",
+      "prompt": "Summarize yesterday's open escalations."
+    },
+    { "key": "inbound", "type": "webhook", "prompt": "Triage the posted ticket." }
+  ],
+  "links": [{ "to": "billing-agent", "kind": "delegate", "mode": "handoff" }],
+  "teamOverrides": { "policy": false, "triggers": true, "links": false }
 }
 ```
 
@@ -58,7 +76,9 @@ The tool names above are illustrations. Take real ones from
   defaults by the tool's effect; `overrides` set single tools by name. An
   undeclared tool effect counts as a write. MCP tools are named
   `mcp__<server key>__<tool>` in `overrides`.
-- **`skills`** — skill slugs the Source or the platform already has.
+- **`skills`** — skill slugs the Source or the platform already has. Skill
+  folders in `agents/<key>/skills/<slug>/` are pushed and added here by
+  `agents apply` (see `skills.md`).
 - **`connections`** — by product slug: `{ "owner": "team", "team": "required" | "optional" }`.
   A product with no entry is `team`/`optional`. `owner: "source"` (one
   connection for every team) is refused today.
@@ -77,6 +97,62 @@ The tool names above are illustrations. Take real ones from
   - `narrow` — remove tools or make more of them wait for approval. Never
     loosens.
 
+- **`triggers`** — what starts a run, set up on every team's copy when it
+  turns the agent on (and kept in step on every publish). Each has a `key`
+  (lowercase-hyphenated, unique in the agent: what versions are matched by),
+  an optional `prompt` (what to do each time), and `enabled` (default
+  `true`; `false` sets it up turned off). Types:
+  - `event` — `event` is an integration event (`<slug>.<event>`, as
+    `ekanos catalog <product>` lists under `agentEvents`); `filter` holds the
+    event's declared filter fields (Zendesk: `organization`, `brand`,
+    `group`, `tags`, `reply_as` …).
+  - `schedule` — `cron` (5 fields, on a 5-minute boundary) and `timezone`
+    (IANA, default `UTC`); give it a `prompt`.
+  - `webhook` — each team gets its **own** URL and secret, created or
+    rotated by the team in the app. A template never holds a webhook secret.
+- **`links`** — other agents of this Source it may ask (`kind: "talk"`) or
+  hand work to (`kind: "delegate"`, `mode: "await"` to wait for the answer,
+  default, or `"handoff"` to let go). `to` is the other agent's key. A link
+  is made in a team only where that team runs both agents; it appears when
+  the team turns the other one on.
+- **`teamOverrides`** — which areas a team may change on its copy:
+  `policy`, `triggers`, `links`. **The template wins.** An area that is off
+  follows the template exactly and the team cannot change it (it shows
+  "Set by your administrator"). An area that is on lets the team keep its
+  own differences: its own triggers and on/off for the template's, its own
+  links, its own auto/approve answers. Switching an area off again keeps the
+  team's differences but stops applying them; switching it back on restores
+  them. Omitted: `policy` is off; `triggers` and `links` are off when this
+  file declares them and on (the team's, as before) when it does not.
+
+## Editing one area without a file
+
+Each of these reads the latest version, changes one thing, and stores the
+result as a new **draft** version (`--publish` also rolls it out, with
+`--yes`). A pulled `agent.json` is left alone; `agents pull` refreshes it.
+
+```
+ekanos agents policy <key>                                    # show
+ekanos agents policy <key> set zendesk_add_comment approve
+ekanos agents policy <key> unset zendesk_add_comment
+ekanos agents policy <key> --reads auto --writes approve
+ekanos agents triggers <key>                                  # list
+ekanos agents triggers <key> add event new-tickets --event zendesk.ticket_created \
+  --filter tags=vip,urgent --filter brand=123 --filter reply_as=internal_note
+ekanos agents triggers <key> add schedule weekday-digest --cron "0 9 * * 1-5" \
+  --timezone America/Los_Angeles --prompt "Summarize yesterday's escalations."
+ekanos agents triggers <key> add webhook inbound --prompt "Triage the posted ticket."
+ekanos agents triggers <key> remove inbound
+ekanos agents links <key> add billing-agent --kind delegate --mode handoff
+ekanos agents links <key> remove billing-agent
+ekanos agents overrides <key>                                 # show the switches
+ekanos agents overrides <key> enable triggers
+ekanos agents overrides <key> disable policy
+```
+
+`--filter field=value` repeats; a value with commas is a list, `true` or
+`false` a switch, anything else text. `--disabled` adds a trigger turned off.
+
 ## What the host checks on `apply`
 
 Every product and tool must be in the Source's catalog, every skill must

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

@@ -32,7 +32,15 @@ Built with `ekanos agents` by a Source admin.
 Good for: the same job done by several teams; a central owner who improves
 it over time; consistent behaviour and approvals.
 
-Piloting: publish, then have one team turn it on first. Teams that never
+**A Source admin can do a team's part from the terminal**:
+`ekanos teams agents enable <team> <key> [--as <member-email>]` turns it on
+for the team (running as that member, the team's owner by default),
+`ekanos teams agents pin|unpin`, `ekanos teams agents policy`, and
+`ekanos teams triggers|links|mcp` set up the rest. `ekanos teams agents list
+<team>` shows where each team stands and what it still needs connected.
+
+Piloting: publish, then have one team turn it on first (or turn it on for
+them with `ekanos teams agents enable`). Teams that never
 turn it on are unaffected. Or keep it as an applied draft until the pilot
 plan is ready.
 

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

@@ -62,7 +62,8 @@ connected (`references/agent-json.md`).
   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
+  `teams show` (or just the link and whether it is connected yet:
+  `teams connect <team> <product>`). 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

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

@@ -0,0 +1,78 @@
+# Skills: what an agent knows how to do
+
+A skill is a folder — `SKILL.md` plus optional `references/` and `assets/` —
+in the same format Claude Code uses. An agent lists its skills by name and
+description and loads one when the task calls for it.
+
+```
+agents/support-triage/
+  agent.json
+  AGENT.md
+  skills/
+    refund-policy/
+      SKILL.md          # frontmatter: name, description; then the instructions
+      references/policy-2026.md
+```
+
+`SKILL.md` frontmatter:
+
+```markdown
+---
+name: refund-policy
+description: How we decide refunds — use when a customer asks for money back.
+---
+
+# Refund policy
+...
+```
+
+The slug is `name` when it is lowercase-with-hyphens, else the folder's
+name. The `description` is how the agent decides to load the skill — write it
+as "what it is — when to use it".
+
+## Two levels
+
+| Level | Command | Who sees it |
+|---|---|---|
+| **Source** (default) | `ekanos skills push <dir>` | Every team on the Source. An agent template may name it in `skills`. |
+| **Team** | `ekanos skills push <dir> --team <team-slug>` | That one team only. For content another team must not see (one bank's own guide). |
+
+Pushing is a Source admin's. A push is **live at once**: there is no draft
+and no publish step, and every agent naming the skill reads the new version
+on its next run. Show the user the folder before pushing it.
+
+## Commands
+
+```bash
+npx @ekanos/cli skills list --source <slug> --json             # the Source's + platform skills
+npx @ekanos/cli skills list --team <team> --source <slug>      # one team's own
+npx @ekanos/cli skills show <slug> --source <slug>             # files, versions
+npx @ekanos/cli skills push agents/<key>/skills/<slug> --source <slug> --json
+npx @ekanos/cli skills pull <slug> --source <slug> [--out <dir>]
+```
+
+`push` prints what changed (files added, changed, removed) and the new
+version; an identical folder is `unchanged` and stores nothing — safe to run
+again.
+
+## With `agents apply`
+
+`ekanos agents apply agents/<key>` pushes every `agents/<key>/skills/<slug>/`
+folder at Source level first, then names those slugs in the agent's `skills`
+(you need not repeat them in `agent.json`). `--no-skills` skips that.
+Because pushing needs a Source admin, a `developer` seat applying an agent
+with skill folders gets SOURCE_ADMIN_REQUIRED; pass `--no-skills` and ask a
+Source admin to `skills push` them.
+
+A provided agent (template) names Source or platform skills only. A team
+skill is attached by that team to its own agents — or to a provided agent
+whose `teamCustomization.skills` is on.
+
+## Limits today
+
+- Prompt skills only: the agent reads `SKILL.md`'s instructions. Files under
+  `references/` and `assets/` are stored with each version and come back with
+  `pull`, but the agent does not open them at run time — put what it must
+  know in `SKILL.md`.
+- A `scripts/` folder is refused: executable skills need the in-app review.
+- Up to 100 files, 1 MB per file, 3 MB per skill.

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

@@ -1,9 +1,28 @@
 # What starts the agent: triggers
 
-Triggers belong to each team. They are not part of the agent template: a team
-adds them on its copy (Agents → the agent → Triggers) after turning it on.
-Your job in the interview is to say which triggers each team will want, and
-what it must connect first, so the team-side checklist is complete.
+The template can declare its triggers (`triggers` in `agent.json`, or
+`ekanos agents triggers <key> add …`): every team that turns the agent on gets
+them, and each publish keeps them in step. By default a team cannot change
+them — they show as "Set by your administrator". Turn on
+`teamOverrides.triggers` (`ekanos agents overrides <key> enable triggers`) to
+let teams add their own and turn the template's on or off. A template that
+declares no triggers leaves them to each team, set on its copy (Agents → the
+agent → Triggers) after turning it on.
+
+Ask in the interview: should the Source set what starts the agent for every
+team (recommended when every team works the same way), or each team? Either
+way say what each team must connect first, so the checklist is complete.
+A webhook trigger's secret is always per team: the template declares the
+trigger, each team creates or rotates its own secret in the app.
+
+A Source admin can add them for the team from the terminal instead:
+`ekanos teams triggers list|add|remove <team> <key> …` — for example
+`ekanos teams triggers add acme-support support-agent event zendesk.ticket_created --filter '{"tags":["billing"]}'`,
+`… schedule --cron "0 9 * * 1-5" --timezone America/Los_Angeles --prompt "…"`,
+`… webhook --prompt "…"` (prints the URL and token once) or `… manual`.
+Slack and Linear triggers are added in the app. When a provided agent's
+template declares triggers and has not turned on team overrides for them, the
+team's triggers follow the template and these commands refuse to change them.
 
 ## Kinds a team can add
 
@@ -45,4 +64,5 @@ internal notes, or approval on public replies, until the team trusts it.
    it (the agent shows what is missing).
 3. Do each integration's own setup (team app, webhook) from its guide.
 4. Confirm access if asked.
-5. Add the triggers above, then run one real example and review it.
+5. Add the triggers above — unless the template already sets them — then
+   run one real example and review it.

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
@@ -97,12 +128,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 +207,14 @@ 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 |
 | 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` |