@ekanos/cli 0.10.0 → 0.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ekanos/cli",
-  "version": "0.10.0",
+  "version": "0.12.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.15.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.15.0",
+    "@ekanos/ui": "^0.15.0"
   },
   "devDependencies": {
-    "@ekanos/cli": "^0.10.0",
-    "@ekanos/harness": "^0.7.4",
+    "@ekanos/cli": "^0.12.0",
+    "@ekanos/harness": "^0.15.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,20 +93,29 @@ 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"
    until the team connects it) or `optional` (its tools appear once
-   connected). One connection shared by every team is not available yet;
-   say so if they ask for it. Then offer to set up any that are not ready.
+   connected). Or, for integrations that support it, the Source connects it
+   once for every team (`owner: "source"`): each team's agent then works only
+   inside what is routed to that team (`references/set-up-an-integration.md`
+   § 5). Then offer to set up any that are not ready.
 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 +125,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,10 +76,17 @@ 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.
+  A product with no entry is `team`/`optional`. `{ "owner": "source" }` is
+  one connection the Source admin makes for every team (`ekanos apps
+  connect`), used only by this provided agent and limited per team by the
+  Source's routing (`ekanos routes`); `apply` refuses it for an integration
+  that does not declare `sourceConnection`. Teams cannot add a Source-owned
+  product in their overlay. `mcpServers` with `owner: "source"` are still
+  refused.
 - **`mcpServers`** — remote MCP servers (streamable HTTP, `https` only, up to
   10): `key` (lowercase, ≤31), `name`, `url`, `auth` (`none` | `bearer` |
   `oauth`, default `oauth`), `owner`/`team` as for connections, and
@@ -77,6 +102,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

@@ -35,12 +35,14 @@ integration: its members, its data and its connections.
 |---|---|---|---|
 | **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 |
+| **One connection for the whole Source** | Every team's provided agent uses the Source's single connection, limited to the records routed to that team (for Zendesk, the tickets of the organizations mapped to it) | The Source admin, once, plus a routing table | One shared Zendesk for many teams (§ 5). Only for integrations that declare it (Zendesk from 0.2.0; `agents apply` refuses the others), and only for **provided agents**: a team's own agents, widgets and assistant never use it |
 
 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`).
+connected (`references/agent-json.md`). `{ "zendesk": { "owner": "source" } }`
+means every team's copy of the agent uses the Source's one Zendesk; teams
+connect nothing for it.
 
 ## 3. Walk it, one step per message
 
@@ -62,7 +64,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
@@ -89,6 +92,59 @@ pilot), the team-side steps can be done from the CLI:
 5. Someone on the team opens the link from `teams show` and clicks Connect.
 6. `teams show` again: every step ✓.
 
+## 5. One connection for the whole Source
+
+Use it when one account at the provider serves many teams: one Zendesk where
+each bank is an organization. The Source admin connects once; events are
+routed to teams by a value inside them (for Zendesk, the ticket's
+**organization**); each team's provided agent then works only inside what is
+routed to that team. Say all three parts before starting, and say plainly
+what it does **not** do: a team's own agents, widgets and assistant never see
+the Source's connection.
+
+1. **Connect, once, as the Source.** For an integration where each customer
+   brings its own app (Zendesk), first create that app in the shared account,
+   exactly as in the worked example below (OAuth client, Confidential), but
+   once, for the Source. Then, **in their own terminal**:
+   `npx @ekanos/cli apps connect <product> --source <slug>`. It asks for the
+   app's fields it doesn't have yet (Zendesk: subdomain, client ID, client
+   secret, webhook signing secret; secrets hidden, never as flags, and it
+   refuses to run inside Claude), prints the redirect URL to register and the
+   consent link, then waits up to ten minutes until it is connected. Whoever
+   clicks the link is the account the integration acts as for every team, so
+   suggest a dedicated seat ("Support agent"). `apps list` shows every
+   integration the Source can connect this way. Check with
+   `npx @ekanos/cli apps show <product> --source <slug>`: connected, by whom,
+   when. In the app the same lives in the Source admin area under
+   **Shared integrations › Connections**.
+2. **The Source's webhook.** `npx @ekanos/cli routes webhook <product> --source <slug>`
+   prints one URL, **once**, for the whole Source. Paste it into the
+   provider at that moment (for Zendesk, the webhook the triggers notify).
+   The team webhooks from § 4 are not used for this connection.
+3. **Map values to teams.** `npx @ekanos/cli routes options <product> --source <slug>`
+   lists what can be mapped (Zendesk organizations, with names), then one
+   line per team:
+   `npx @ekanos/cli routes set <product> <value> <team> --source <slug>`.
+   `routes list` shows the table. One value goes to exactly one team.
+4. **The agent.** In `agent.json`, `connections.<product>` is
+   `{ "owner": "source" }`; `agents apply` accepts it only when the
+   integration supports a Source connection. Teams turn the agent on as
+   usual; they connect nothing for that product.
+5. **Try it.** A ticket from a mapped organization starts that team's agent
+   only. A ticket from an organization nobody mapped starts **nothing**: the
+   integration leaves its own fixed note (Zendesk: an internal note saying
+   no team has it yet), and it is listed by
+   `npx @ekanos/cli routes unrouted <product> --source <slug>`. Map the
+   value, then `routes replay <event-id>` to send it on once.
+
+What is enforced, so you can say it accurately: the host routes each event
+to exactly one team or to none (never to a default team), and gives a
+team's agent only that team's mapped values (`ctx.routing`); the
+integration's tools keep to them (for Zendesk, reads are limited to the
+team's organizations, and anything that reads or changes one ticket first
+checks its organization and refuses otherwise). The agent's policy,
+approvals and audit apply exactly as on a team connection.
+
 ## Worked example: Zendesk for one team
 
 The steps below are what Zendesk's own setup says, in order. Take the URLs

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

@@ -0,0 +1,81 @@
+# 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. At run time the agent gets the whole folder: loading
+  the skill returns `SKILL.md`'s instructions plus the list of every other
+  file (`references/`, `assets/`, …), and it reads one on demand
+  (`read_skill_file`) when the instructions point to it — so keep `SKILL.md`
+  short and name the reference to open, e.g. `references/policy-2026.md`.
+  Text files are read in parts of about 12,000 characters; binary files are
+  listed but cannot be read as text.
+- 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.