@ekanos/cli 0.9.0 → 0.11.0

package/dist/teams-api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"teams-api.js","sourceRoot":"","sources":["../src/teams-api.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  type TeamAppSetResult,\n  TeamAppSetResultSchema,\n  type TeamCreateRequest,\n  type TeamCreateResult,\n  TeamCreateResultSchema,\n  type TeamMemberChangeResult,\n  TeamMemberChangeResultSchema,\n  type TeamMemberInviteResult,\n  TeamMemberInviteResultSchema,\n  type TeamMemberList,\n  TeamMemberListSchema,\n  type TeamRoles,\n  TeamRolesSchema,\n  type TeamIntegrationStatus,\n  TeamIntegrationStatusSchema,\n  type TeamList,\n  TeamListSchema,\n  type TeamWebhookMintResult,\n  TeamWebhookMintResultSchema,\n} from '@ekanos/integration-schema';\nimport type { z } from 'zod';\n\nimport { request } from './auth/ekanos-api';\nimport {\n  authRequiredError,\n  forbiddenError,\n  invalidStateError,\n  networkError,\n  notFoundError,\n  usageError,\n  validationError,\n} from './errors';\n\n/**\n * The CLI's client for a Source's teams and their integration setup — the\n * team-level counterpart of `apps-api.ts`.\n *\n *   GET  /api/partner/teams?source=<slug>                              → TeamList\n *   GET  /api/partner/teams/<team>/integrations/<product>?source=<slug> → TeamIntegrationStatus\n *   PUT  …/integrations/<product>/app?source=<slug>  { connectionId?, fields }\n *                                                                      → TeamAppSetResult\n *   POST …/integrations/<product>/webhooks/<id>?source=<slug>         → TeamWebhookMintResult\n *   POST /api/partner/teams?source=<slug>  { name, slug?, ownerEmail? } → TeamCreateResult\n *   GET  /api/partner/teams/<team>/members?source=<slug>               → TeamMemberList\n *   POST …/<team>/members?source=<slug>  { email, role }               → TeamMemberInviteResult\n *   PATCH  …/<team>/members/<email>?source=<slug>  { role }            → TeamMemberChangeResult\n *   DELETE …/<team>/members/<email>?source=<slug>                      → TeamMemberChangeResult\n *   GET  /api/partner/teams/<team>/roles?source=<slug>                 → TeamRoles\n *\n *   → 401 / 3xx  refresh once and retry\n *   → 403 { code: \"SOURCE_ADMIN_REQUIRED\" | \"MFA_REQUIRED\" | \"FORBIDDEN\" }\n *   → 404 { code: \"TEAM_NOT_FOUND\" | \"PRODUCT_NOT_ENTITLED\" | \"WEBHOOK_NOT_FOUND\"\n *               | \"CONNECTION_NOT_FOUND\" | \"SOURCE_NOT_FOUND\" }\n *               | \"MEMBER_NOT_FOUND\" }\n *   → 409 { code: \"NO_TEAM_APP\" | \"SLUG_TAKEN\" | \"TEAM_ACCOUNTS_DISABLED\"\n *               | \"ALREADY_MEMBER\" | \"ALREADY_INVITED\" | \"PRIMARY_OWNER\" }\n *   → 400 { code: \"INVALID_FIELDS\" | \"INVALID_REQUEST\" | \"UNKNOWN_ROLE\" }\n */\n\nexport type TeamsApiResult<T> =\n  | { status: 'ok'; data: T }\n  | { status: 'unauthorized' };\n\nexport function listTeams(\n  host: string,\n  accessToken: string,\n  source: string,\n): Promise<TeamsApiResult<TeamList>> {\n  return call(host, accessToken, TeamListSchema, {\n    method: 'GET',\n    path: '/api/partner/teams',\n    source,\n  });\n}\n\nexport function showTeamIntegration(\n  host: string,\n  accessToken: string,\n  target: { source: string; team: string; product: string },\n): Promise<TeamsApiResult<TeamIntegrationStatus>> {\n  return call(host, accessToken, TeamIntegrationStatusSchema, {\n    method: 'GET',\n    path: integrationPath(target),\n    source: target.source,\n  });\n}\n\nexport function setTeamApp(\n  host: string,\n  accessToken: string,\n  target: { source: string; team: string; product: string },\n  body: { connectionId?: string; fields: Record<string, string> },\n): Promise<TeamsApiResult<TeamAppSetResult>> {\n  return call(host, accessToken, TeamAppSetResultSchema, {\n    method: 'PUT',\n    path: `${integrationPath(target)}/app`,\n    source: target.source,\n    body,\n  });\n}\n\nexport function mintTeamWebhook(\n  host: string,\n  accessToken: string,\n  target: { source: string; team: string; product: string },\n  webhookId: string,\n): Promise<TeamsApiResult<TeamWebhookMintResult>> {\n  return call(host, accessToken, TeamWebhookMintResultSchema, {\n    method: 'POST',\n    path: `${integrationPath(target)}/webhooks/${encodeURIComponent(webhookId)}`,\n    source: target.source,\n  });\n}\n\nexport function createTeam(\n  host: string,\n  accessToken: string,\n  source: string,\n  body: TeamCreateRequest,\n): Promise<TeamsApiResult<TeamCreateResult>> {\n  return call(host, accessToken, TeamCreateResultSchema, {\n    method: 'POST',\n    path: '/api/partner/teams',\n    source,\n    body,\n  });\n}\n\nexport function listTeamMembers(\n  host: string,\n  accessToken: string,\n  target: { source: string; team: string },\n): Promise<TeamsApiResult<TeamMemberList>> {\n  return call(host, accessToken, TeamMemberListSchema, {\n    method: 'GET',\n    path: membersPath(target.team),\n    source: target.source,\n  });\n}\n\nexport function inviteTeamMember(\n  host: string,\n  accessToken: string,\n  target: { source: string; team: string },\n  body: { email: string; role: string },\n): Promise<TeamsApiResult<TeamMemberInviteResult>> {\n  return call(host, accessToken, TeamMemberInviteResultSchema, {\n    method: 'POST',\n    path: membersPath(target.team),\n    source: target.source,\n    body,\n  });\n}\n\nexport function setTeamMemberRole(\n  host: string,\n  accessToken: string,\n  target: { source: string; team: string; email: string },\n  role: string,\n): Promise<TeamsApiResult<TeamMemberChangeResult>> {\n  return call(host, accessToken, TeamMemberChangeResultSchema, {\n    method: 'PATCH',\n    path: `${membersPath(target.team)}/${encodeURIComponent(target.email)}`,\n    source: target.source,\n    body: { role },\n  });\n}\n\nexport function removeTeamMember(\n  host: string,\n  accessToken: string,\n  target: { source: string; team: string; email: string },\n): Promise<TeamsApiResult<TeamMemberChangeResult>> {\n  return call(host, accessToken, TeamMemberChangeResultSchema, {\n    method: 'DELETE',\n    path: `${membersPath(target.team)}/${encodeURIComponent(target.email)}`,\n    source: target.source,\n  });\n}\n\nexport function listTeamRoles(\n  host: string,\n  accessToken: string,\n  target: { source: string; team: string },\n): Promise<TeamsApiResult<TeamRoles>> {\n  return call(host, accessToken, TeamRolesSchema, {\n    method: 'GET',\n    path: `/api/partner/teams/${encodeURIComponent(target.team)}/roles`,\n    source: target.source,\n  });\n}\n\nfunction membersPath(team: string): string {\n  return `/api/partner/teams/${encodeURIComponent(team)}/members`;\n}\n\nfunction integrationPath(target: { team: string; product: string }): string {\n  return `/api/partner/teams/${encodeURIComponent(target.team)}/integrations/${encodeURIComponent(target.product)}`;\n}\n\n/** One partner teams call; shared by the team-agent clients (`team-agents-api.ts`). */\nexport async function call<T>(\n  host: string,\n  accessToken: string,\n  schema: z.ZodType<T>,\n  init: {\n    method: 'GET' | 'PUT' | 'POST' | 'PATCH' | 'DELETE';\n    path: string;\n    source: string;\n    body?: unknown;\n  },\n): Promise<TeamsApiResult<T>> {\n  const response = await request(\n    `${host}${init.path}?${new URLSearchParams({ source: init.source })}`,\n    {\n      method: init.method,\n      headers: {\n        accept: 'application/json',\n        authorization: `Bearer ${accessToken}`,\n        ...(init.body === undefined\n          ? {}\n          : { 'content-type': 'application/json' }),\n      },\n      body: init.body === undefined ? undefined : JSON.stringify(init.body),\n    },\n  );\n\n  if (\n    response.status === 401 ||\n    (response.status >= 300 && response.status < 400)\n  ) {\n    return { status: 'unauthorized' };\n  }\n\n  const body = await readOptionalJson(response);\n  const code = typeof body.code === 'string' ? body.code : null;\n  const message =\n    typeof body.error === 'string' && body.error ? body.error : null;\n\n  if (response.status === 403 && code === 'MFA_REQUIRED') {\n    throw authRequiredError(\n      message ?? `${host} requires multi-factor authentication.`,\n      'Complete MFA in the browser, then run \"ekanos login\" again.',\n    );\n  }\n  if (response.status === 403) {\n    throw forbiddenError(\n      message ?? 'Not permitted on this Source.',\n      code === 'SOURCE_ADMIN_REQUIRED'\n        ? \"Only a Source admin manages its teams' integrations. Ask one to run it.\"\n        : 'Run \"ekanos sources\" to list the sources you hold a seat on.',\n    );\n  }\n  if (response.status === 404) {\n    throw notFoundError(\n      message ?? 'Not found.',\n      code === 'TEAM_NOT_FOUND'\n        ? 'Run \"ekanos teams list\" to see the teams on this Source.'\n        : code === 'PRODUCT_NOT_ENTITLED'\n          ? '\"ekanos catalog\" lists what this Source has; Ekanos enables a product for a Source.'\n          : code === 'WEBHOOK_NOT_FOUND' || code === 'CONNECTION_NOT_FOUND'\n            ? 'Run \"ekanos teams show <team> <product>\" to see its team apps and webhooks.'\n            : code === 'MEMBER_NOT_FOUND'\n              ? 'Run \"ekanos teams members list <team>\" to see its members and invitations.'\n              : code?.startsWith('AGENT_') || code === 'TEMPLATE_NOT_FOUND'\n                ? 'Run \"ekanos teams agents list <team>\" to see the team\\'s agents.'\n                : /^(TRIGGER|LINK|MCP)_/.test(code ?? '')\n                  ? 'List them first: \"ekanos teams triggers|links|mcp list <team> ...\"'\n                  : 'Run \"ekanos sources\" to list the sources you hold a seat on.',\n    );\n  }\n  if (response.status === 409 && code === 'NO_TEAM_APP') {\n    throw invalidStateError(\n      message ?? 'This integration takes no team app.',\n      'Teams connect through the Source\\'s app: \"ekanos apps show <product>\".',\n    );\n  }\n  if (response.status === 409 || response.status === 422) {\n    throw invalidStateError(\n      message ?? 'The host refused the change.',\n      code === 'SLUG_TAKEN'\n        ? 'Pick another with --slug, or run \"ekanos teams list\" to see the teams.'\n        : code === 'ALREADY_MEMBER' || code === 'ALREADY_INVITED'\n          ? 'Run \"ekanos teams members list <team>\"; change a role with \"ekanos teams members role <team> <email> <role>\".'\n          : code === 'PRIMARY_OWNER'\n            ? \"The primary owner's ownership is transferred in the app (team Settings → Members).\"\n            : code === 'TEAM_ACCOUNTS_DISABLED'\n              ? 'Ekanos switches team accounts on for a Source; ask a super-admin.'\n              : 'See \"ekanos teams --help\".',\n    );\n  }\n  if (response.status === 400 && code === 'UNKNOWN_ROLE') {\n    throw validationError(\n      message ?? 'No such role.',\n      'Run \"ekanos teams roles list <team>\" for the roles this Source uses.',\n    );\n  }\n  if (response.status === 400 && code === 'INVALID_FIELDS') {\n    throw validationError(\n      message ?? 'The host refused the fields.',\n      'Run \"ekanos teams app set <team> <product>\" again.',\n    );\n  }\n  if (response.status === 400) {\n    throw usageError(\n      message ?? 'The host refused the request.',\n      'See \"ekanos teams --help\".',\n    );\n  }\n  if (!response.ok) {\n    throw networkError(\n      `${host}${init.path} responded ${response.status}.`,\n      response.status >= 500\n        ? 'The Ekanos deployment returned a server error. Retry shortly.'\n        : 'Confirm the host runs a build that includes the teams routes.',\n    );\n  }\n\n  const parsed = schema.safeParse(body.data);\n  if (!parsed.success) {\n    throw networkError(\n      `${host}/api/partner/teams answered in a shape this CLI does not read.`,\n      'Run \"ekanos upgrade\" — the CLI and the host disagree on the teams contract.',\n    );\n  }\n  return { status: 'ok', data: parsed.data };\n}\n\nasync function readOptionalJson(\n  response: Response,\n): Promise<Record<string, unknown>> {\n  try {\n    const parsed: unknown = await response.json();\n    return typeof parsed === 'object' && parsed !== null\n      ? (parsed as Record<string, unknown>)\n      : {};\n  } catch {\n    return {};\n  }\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ekanos/cli",
-  "version": "0.9.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.12.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.12.0",
-    "@ekanos/ui": "^0.12.0"
+    "@ekanos/sdk": "^0.14.0",
+    "@ekanos/ui": "^0.14.0"
   },
   "devDependencies": {
-    "@ekanos/cli": "^0.9.0",
-    "@ekanos/harness": "^0.7.3",
+    "@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

@@ -60,12 +60,22 @@ every `hint`. Look things up in the `ekanos-sdk-docs` MCP server
 Tell the user this map in a few lines before the interview. Don't hide a gap
 behind a plan that assumes it away.
 
-## Setting up an app, step by step
-
-When a provider app or a team app is not set up and the user wants to do it,
-follow `references/app-setup.md`: one step at a time, in the provider's own
-console words, with the exact URLs to paste from the catalog, waiting for the
-user after each step, and the secret entered only at their terminal.
+## Setting up an integration, concierge-style
+
+When something the agent needs is not set up yet, offer to set it up with
+the user now: "Zendesk isn't connected for any team yet; want me to walk you
+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. 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.
 
 ## 2. The interview
 
@@ -83,18 +93,27 @@ 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`.
-5. **Whose connections.** For each product and MCP server: each team
-   connects its own — `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.
+   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.
 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
 
@@ -104,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

@@ -0,0 +1,134 @@
+# 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` (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
+  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/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
 
@@ -33,7 +52,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.
 
@@ -44,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.