@ekanos/cli 0.13.0 → 0.15.0

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

@@ -18,13 +18,33 @@ Run the CLI as `npx @ekanos/cli … --json` and read the envelope
 every `hint`. Look things up in the `ekanos-sdk-docs` MCP server
 (https://sdk.ekanos.dev) rather than guessing.
 
+## The goal: an agent that can be reached and answers
+
+The user wants an agent that **responds and does things** where their people
+work — someone @mentions it in Linear (or assigns it an issue, or writes in
+Slack) and it picks the work up, acts with its tools and answers in that
+thread. "Published", "turned on" and "connected" are steps toward that, not
+the finish. Whenever the agent has a channel trigger (`linear.mentioned`,
+`linear.assigned`, any Linear event, a Slack trigger), the job is not done
+until a real mention has started a run and the reply has landed.
+
+A channel trigger fires only once that channel is **installed for the team**,
+and for Linear that is a second identity beside the personal connection: the
+team's own Linear app installed as a workspace member (the `agent`
+connection). The personal connection lets the agent's tools act; only the
+installed Linear agent makes Linear send the mention. Nothing stops a team
+from turning the agent on with the trigger saved and the agent never
+installed — so check it, every time (§ 4, "Make it reachable").
+
 ## Hard rules
 
 - Never ask for, accept or write a secret (API key, client secret, webhook
-  signing secret). Teams enter those in the Ekanos app.
-- Never `publish` or `rollback` without the user's explicit yes to that
-  version, after they have seen it. `--yes` records that consent; it is never
-  a way past a question.
+  signing secret). The user types it at their own terminal — `apps set`,
+  `apps connect`, `teams app set` and `teams connect` ask with hidden input
+  and refuse an agent run — or a team enters it in the Ekanos app.
+- Never `publish`, `rollback` or `archive` without the user's explicit yes to
+  that version or agent, after they have seen it. `--yes` records that
+  consent; it is never a way past a question.
 - Never `--overwrite` a version conflict (exit 7) you have not shown the user:
   someone else changed the agent; pull it and reconcile.
 - Use product and tool names exactly as the catalog lists them.
@@ -53,7 +73,8 @@ every `hint`. Look things up in the `ekanos-sdk-docs` MCP server
      agent's docs, policies or FAQs should live, offer **Knowledge** first:
      Ekanos's own knowledge base, nothing to sign up for. One collection per
      team plus the Source's General one; load a folder of markdown with
-     `ekanos knowledge push <dir> [--team <team>]`, check with
+     `ekanos knowledge push <dir> [--team <team>]` (add `--prune` on the
+     user's yes to delete the ones whose files they removed), check with
      `ekanos knowledge search "<words>" --team <team>`, and grant the agent
      `search_knowledge` + `read_knowledge_article` (`references/agent-json.md`
      → `tools`). Keep skills for how-to-work instructions; Knowledge for the
@@ -122,7 +143,10 @@ in parentheses are the recommendation when the user has no preference.
    event a product declares (Linear also has `linear.issue_labeled`,
    `linear.issue_created` and `linear.assigned`; Zendesk also has
    `zendesk.comment_added`) — map an old trigger onto the matching event
-   rather than onto an @mention. Say what each team needs connected first.
+   rather than onto an @mention. Say what each team needs connected first —
+   and for a channel trigger, that each team also installs that channel's
+   agent (Linear: `teams connect <team> linear --connection agent`), or the
+   trigger never fires.
 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,
@@ -150,21 +174,81 @@ in parentheses are the recommendation when the user has no preference.
    `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:
+   Then test it on **one** team, without publishing. Put that team on the
+   draft first — this works before anything is published, and lets the test
+   use tools the draft adds:
+   `npx @ekanos/cli teams agents enable <team> <key> --draft --json` (agent
+   not on that team yet) or `teams agents pin <team> <key> --draft --json`
+   (already on). Then
    `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).
+   (or `--input example.json` for a real ticket or event). Only that team runs
+   the draft, only when started by hand — its triggers don't start it — and
+   every write waits for an approval (see "Running, watching and deciding"
+   below). After the next `agents apply`, run `pin --draft` again to test the
+   new draft; publishing puts the team back to following.
 4. Ask: publish this version to every team now? Only on yes:
    `npx @ekanos/cli agents publish <key> --source <slug> --to <n> --yes`.
+   The publish is the confirmation: every team that follows the agent
+   moves to the new version, and one that had confirmed what it may use
+   stays confirmed, now in the publisher's name — even when the version
+   reaches further. No team is held. Ask once whether to add
+   `--confirm-access` (it also confirms, as the user, every team on that
+   version that was never confirmed; never add it without their yes). The
+   output lists any team pinned to another version, what the new version
+   would add to it, and the `teams agents unpin` command that moves it —
+   relay it.
 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.
+   Turn on, connect what it needs, **install the channel's agent for a
+   channel trigger**, confirm access (`teams agents confirm <team> <key>`
+   or `teams agents enable … --confirm-access`, as the user; or a team
+   manager in the app — never a plain member), add triggers. Suggest one
+   team pilots
+   it first, and do § 4 with them.
+
+## 4. Make it reachable, and prove it end to end
+
+For each team that turns on an agent with a channel trigger, start with
+`npx @ekanos/cli teams agents show <team> <key> --source <slug>`: it says
+whether the agent is live on that team and, if not, the one next step
+(`npx @ekanos/cli teams show <team> --source <slug>` is the whole team on one
+screen). For the detail behind it:
+
+1. `npx @ekanos/cli teams agents list <team> --json` — each agent's
+   `channels` says what its triggers need installed (`ready`, `problem`).
+   A `ready: false` entry is a trigger that can never fire; its `problem`
+   reads "Linear agent not installed for this team".
+2. `npx @ekanos/cli teams show <team> linear --json` — `connections` has one
+   entry per connection: `default` (the personal connection: `connected`)
+   and `agent` (`credentialsSaved`, `connected` = installed, `neededBy`),
+   and the `agent-events` webhook in `teamApps[].webhooks` must have an
+   `endpoint`. Read the state back to the user in those words.
+3. Not installed: the user runs, **in their own terminal** (it asks for the
+   Linear app's secrets, which you never handle):
+   `npx @ekanos/cli teams connect <team> linear --connection agent --source <slug>`.
+   It asks for the app's client ID, secret and webhook signing secret if
+   missing, opens the install (a Linear workspace admin approves it) and
+   waits. No webhook URL yet: `npx @ekanos/cli teams webhook <team> linear
+   agent-events --source <slug>` (shown once, and saved to a file only the
+   user can read — the output names it; the user copies it into the Linear
+   app. Never open or print that file yourself).
+   `references/set-up-an-integration.md` § 4 has the app walk-through. Then
+   run step 2 again until `agent` reads `connected: true` with a webhook.
+4. The real check, never skipped: ask the user to @mention the agent on a
+   Linear issue (or assign it one). Then
+   `npx @ekanos/cli runs list --team <team> --json` shows a run whose
+   `trigger` is the event (`integration_event`), started in the last minute;
+   `npx @ekanos/cli runs show <run-id> --team <team> --json` shows its work,
+   and the user confirms the reply landed in the Linear thread. No run:
+   go back to step 1 — the trigger, its filter (`teamKeys`), the webhook
+   events ticked in the Linear app (**Agent session events**), the latest
+   webhook URL.
+
+`agents test` and `runs start` run the agent by hand: they pass without the
+channel, so they never prove it. When the agent's real trigger could never
+fire they print a `Warning:` (and `warnings` in `--json`) — act on it.
 
 ## Reviewers
 
@@ -181,7 +265,7 @@ notified of every draft in their reach.
 - `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>`
+- `npx @ekanos/cli reviewers remove <email> [--team <team-slug>] --source <slug> --yes`
   — every reach, or just that team's.
 
 The first decision settles a draft for everyone. Recommend one or two
@@ -192,7 +276,8 @@ reviewers where a team wants its own people deciding. A refusal with
 ## 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
+`agents/<key>/` (it refuses to overwrite a local file that differs; `--force`
+replaces it); edit, `apply` (a new draft), `show`, then `publish` on the
 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
@@ -219,7 +304,9 @@ names them). Add `--json` for a stable record a script can assert on.
 - `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.
+  the authority a team's agent manager has in the app. A team's own agent
+  (not provided) is the team's: you decide its approvals only as a member of
+  that team who manages its agents (`NOT_A_TEAM_APPROVER` otherwise).
 - `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.

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

@@ -126,7 +126,8 @@ The tool names above are illustrations. Take real ones from
   - `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.
+    rotated by the team in the app or by a Source admin with
+    `ekanos teams triggers rotate`. 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
@@ -146,7 +147,8 @@ The tool names above are illustrations. Take real ones from
 
 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.
+`--yes`). A pulled `agent.json` is left alone; `agents pull --force` refreshes
+it (without `--force`, a pull refuses to overwrite a file that differs).
 
 ```
 ekanos agents policy <key>                                    # show

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

@@ -22,19 +22,38 @@ Built with `ekanos agents` by a Source admin.
   when a newer one is published.
 - **Rollback.** `ekanos agents rollback <key> --to <n> --yes` publishes an
   earlier version to every team that follows it.
+- **Retiring it.** `ekanos agents archive <key> --yes` stops every team from
+  turning it on; it cannot be applied over or published until
+  `ekanos agents unarchive <key>`. It is refused while any team has it on,
+  and the refusal lists each team with the `teams agents disable` command
+  that turns it off there. `agents list` hides archived agents (`--all`
+  shows them). Archive only on the user's explicit yes.
 - **What stays the team's:** whether it is on, its triggers, its own
   connections, its run history, and whatever `teamCustomization` lets it add.
+- **Confirming access.** The agent uses the connections of the person it
+  runs as, and in runs no one watches only once someone who sets it up
+  confirms it may: the Source admin with `ekanos teams agents confirm <team>
+  <key>` (or `teams agents enable <team> <key> --confirm-access` to turn it
+  on and confirm at once), or one of the team's agent managers with
+  **Confirm access** in the app. Each confirms as themselves; a plain team
+  member never does. It confirms only the version it printed: a newer
+  publish since is refused, not confirmed unseen.
 - **When a new version needs more access** than a team confirmed (a new
-  product, a tool that now runs without approval), the team's owner is asked
-  to confirm again; until then the agent keeps only what needs no new
-  confirmation.
+  product or tool, `custom` → `read_only`/`all`, a tool that now runs without
+  approval), the publish is the confirmation: every following team moves to
+  it and stays confirmed, now in the publisher's name. No team is held.
+  `agents publish --confirm-access` also confirms every team on that version
+  that was never confirmed. A team that never confirmed moves unconfirmed; a
+  pinned team stays on its pin, and `agents publish` lists it with what the
+  new version would add and the `teams agents unpin` command.
 
 Good for: the same job done by several teams; a central owner who improves
 it over time; consistent behaviour and approvals.
 
 **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),
+for the team (running as that member, the team's owner by default; with
+`--confirm-access`, you confirm it in the same step),
 `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.

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

@@ -18,7 +18,10 @@ guess.
 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.
+   in the app. If it says the product is hidden from the team by its product
+   scope, the team cannot see it in the app however connected it is: show
+   the user the fix it prints (`ekanos sources scopes add <scope> <product>`,
+   or `ekanos teams scope set <team> <scope>`) and run it on their yes.
 
 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
@@ -102,6 +105,34 @@ 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 ✓.
 
+### A channel's own install: the Linear agent
+
+Some integrations have a second connection beside the main one, and an
+agent's channel trigger fires only once it is installed. Linear's is
+`agent`: the team's own Linear app, installed in the team's Linear workspace
+as a member people can @mention and assign. The personal connection
+(`teams connect <team> linear`) is a different identity and does not make
+mentions arrive. When the agent has any Linear trigger:
+
+1. `teams show <team> linear --json` → `connections`: the `agent` entry's
+   `credentialsSaved`, `connected` (installed) and `neededBy` (the agents
+   waiting on it), and in `teamApps` the `agent-events` webhook's `endpoint`.
+2. The Linear app itself (Linear › Settings › API › Applications › New): the
+   steps are in `teams show` under "Team app: Linear agent (agent)" —
+   redirect URIs, webhooks on with **Agent session events** and **Issues**.
+3. Its webhook URL: `teams webhook <team> linear agent-events` (once; paste
+   it into the Linear app's webhook URL).
+4. **In their own terminal:**
+   `npx @ekanos/cli teams connect <team> linear --connection agent --source <slug>`
+   — asks for the client ID, secret and webhook signing secret if any is
+   missing, opens the install for a Linear workspace admin to approve, and
+   waits until it is installed. (`teams connect <team> linear` with no
+   `--connection` offers this itself once the personal connection is made,
+   when the team has agents with Linear triggers.)
+5. `teams show` again: `✓ Linear agent (agent): app credentials saved ·
+   installed … · webhook URL made`. Then the end-to-end check in the
+   build-agent skill, § 4: a real @mention starts a run and the reply lands.
+
 ## 5. One connection for the whole Source
 
 Use it when one account at the provider serves many teams: one Zendesk where
@@ -130,6 +161,9 @@ the Source's connection.
 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).
+   Once a URL is live the command refuses to mint another: a new one
+   revokes it for every routed team. Add `--yes` only when the user is
+   ready to paste the new URL into the provider.
    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
@@ -171,16 +205,23 @@ from `teams show zendesk`.
    their terminal: subdomain, client ID, client secret, webhook signing
    secret. Any of them can be entered or changed later on its own
    (`--field <name>`); `teams show` says which are saved.
-4. **Connect.** Someone on the team opens the link and connects, as the
-   Zendesk agent the integration should reply as.
+4. **Connect.** `npx @ekanos/cli teams connect <team> zendesk --source <slug>`
+   opens the sign-in and waits; whoever approves it should be the Zendesk
+   agent the integration replies as (`--as <member-email>` to send the link
+   to that member instead). A team member can also connect from the team's
+   page in the app.
 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.
+6. **The agent's trigger.** In the template, for every team:
+   `npx @ekanos/cli agents triggers <key> add event new-tickets --event zendesk.ticket_created --source <slug>`
+   (and `zendesk.comment_added` for a customer's reply), with any
+   `--filter field=a,b`. For one team only, where the template lets teams
+   change triggers:
+   `npx @ekanos/cli teams triggers add <team> <key> event zendesk.ticket_created --source <slug>`.
 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
@@ -194,7 +235,14 @@ from `teams show zendesk`.
 - **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.
+  right webhook. If it has been used but nothing ran, run
+  `teams events <team> zendesk --since 24h`: each event says whether it
+  started a run, and if not, why (no enabled trigger subscribes to it, none
+  matched its filter, or it failed with the error shown).
+- **Mentions in Linear do nothing:** `teams agents list <team>` — a
+  `channels` entry with `ready: false` names what is missing ("Linear agent
+  not installed for this team", or no webhook URL) and the command that
+  fixes it. Installed and still silent: the Linear app's webhook must send
+  **Agent session events** to the latest URL from `teams webhook`.
 - **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

@@ -37,6 +37,19 @@ as "what it is — when to use 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). |
 
+A template can't name a team skill, so a provided agent reads one only once
+it is **attached** on that team, and only when the template allows team
+skills (`"teamCustomization": { "skills": true }` in `agent.json`, applied
+and published):
+
+```bash
+npx @ekanos/cli teams agents skills <team> <key> --source <slug>                    # what it reads, and whether the team may add
+npx @ekanos/cli teams agents skills <team> <key> add <skill-slug> --source <slug>   # attach (team, Source or platform skill)
+npx @ekanos/cli teams agents skills <team> <key> remove <skill-slug> --source <slug>
+```
+
+The template's own skills stay; `remove` refuses them.
+
 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.
@@ -48,13 +61,19 @@ npx @ekanos/cli skills list --source <slug> --json             # the Source's +
 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>]
+npx @ekanos/cli skills pull <slug> --source <slug> [--out <dir>] [--force]  # --force: overwrite local edits
 ```
 
 `push` prints what changed (files added, changed, removed) and the new
 version; an identical folder is `unchanged` and stores nothing — safe to run
 again.
 
+`npx @ekanos/cli skills archive <slug> [--team <team>] --source <slug> --yes`
+retires a skill (only on the user's explicit yes): no agent can name it and a
+push to it is refused until `skills unarchive <slug>`. It is refused while an
+agent names it or a team agent has it attached; the refusal lists each use
+and the command that stops it. Platform skills cannot be archived.
+
 ## With `agents apply`
 
 `ekanos agents apply agents/<key>` pushes every `agents/<key>/skills/<slug>/`

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

@@ -13,7 +13,11 @@ 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.
+trigger, each team creates or rotates its own secret in the app, or a
+Source admin does with `ekanos teams triggers rotate <team> <key> <trigger-key>`
+(shown once, saved to a file only the user can read and named in the
+output — the user copies it to the sender; never open or print that file
+yourself; replacing a live one needs `--yes`).
 
 A Source admin can add them for the team from the terminal instead:
 `ekanos teams triggers list|add|remove <team> <key> …` — for example
@@ -22,9 +26,15 @@ A Source admin can add them for the team from the terminal instead:
 `… webhook --prompt "…"` (prints the URL and token once) or `… manual`.
 Any event in a connected integration's `agentEvents` is added this way,
 including every Linear integration event (`event linear.issue_labeled
---filter '{"labels":["feedback"]}'`). Only two trigger *types* are app-only:
-a **Slack** trigger, and a **Linear (Agents app)** trigger — Ekanos's own
-Linear app, which answers @mentions and assignments only. That app is not
+--filter '{"labels":["feedback"]}'`). A **Slack** trigger and a **Linear
+(Agents app)** trigger — Ekanos's own Linear app, which answers @mentions
+and assignments — answer through an install the team makes first:
+`ekanos teams connect <team> slack` or `ekanos teams connect <team>
+linear-app` (a one-time link for a team member, opened and waited on like
+any `teams connect`). Then `ekanos teams triggers add <team> <key> slack
+--channel '#support' [--dms] --yes` (the bot must be in each channel; `--yes`
+confirms that anyone there can ask the agent to act) or `… linear [--label
+<name>]… [--no-mention]`. That app is not
 the Linear integration, and its limits are not the integration's: an agent
 that should start when a label is applied uses `linear.issue_labeled`, not an
 @mention. When a provided agent's
@@ -58,11 +68,28 @@ finishes that event's own setup on the provider's side. That is a setup
 step, not a missing event — say which step, as below.
 
 **Linear** — the agent becomes a teammate in Linear. Each team needs two
-things in the app: each person's own Linear connection (for the tools), and
-the team's own Linear app for the agent (client id, secret and webhook
-signing secret, entered in Ekanos).
+identities, and they are not the same thing:
+
+- **The personal connection** (`default`): someone's own Linear sign-in, for
+  the agent's tools. `teams connect <team> linear`.
+- **The Linear agent** (`agent`): the team's own Linear app, installed in its
+  workspace as a member people can @mention and assign. Linear sends every
+  agent event below only to an installed app, so **without it no Linear
+  trigger ever fires** — the trigger is saved, on, and silent.
+  `teams connect <team> linear --connection agent` (asks for the app's client
+  id, secret and webhook signing secret, opens the install, waits), plus the
+  webhook URL: `teams webhook <team> linear agent-events`.
+
+Check both with `teams show <team> linear`: under **Connections**, `default`
+connected, and `agent` with app credentials saved, installed and its webhook
+URL made. `teams agents list <team>` lists a Linear-triggered agent whose
+agent is not installed as missing ("Linear agent not installed for this
+team"), and the agent's Setup tab in the app says the same.
 Guide: https://sdk.ekanos.dev/guides/linear-agent
 
+Every event needs the Linear agent installed; the last column is what the
+installed app's webhook must also send.
+
 | Event | Starts when | Filter keys | Needs on the team's Linear app |
 |---|---|---|---|
 | `linear.mentioned` | someone @mentions the agent, or writes to it again in that conversation | `teamKeys` | webhook with **Agent session events** ticked |
@@ -91,7 +118,16 @@ brands, groups and organizations match by name or id. Where the answer goes
 1. Agents → "Provided for your team" → Turn on.
 2. Connect every `required` product and sign in to any MCP server that needs
    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 — unless the template already sets them — then
-   run one real example and review it.
+3. Install the channel each trigger listens on: for any Linear trigger the
+   Linear agent (`teams connect <team> linear --connection agent`, and its
+   webhook URL), for a Slack trigger the team's Slack. `teams agents list
+   <team>` shows each agent's `channels`; none may be `ready: false`.
+4. Do each integration's own setup (team app, webhook) from its guide.
+5. Confirm access: the Source admin runs `npx @ekanos/cli teams agents
+   confirm <team> <key> --source <slug>` (or turned it on with
+   `--confirm-access`), or a team manager confirms in the app. `teams agents
+   list <team>` shows any agent still unconfirmed.
+6. Add the triggers above — unless the template already sets them.
+7. Prove it end to end: a real @mention (or the real event) → a run in
+   `runs list --team <team>` → the agent's reply where it was asked. A test
+   run started by hand does not count; it passes without the channel.

package/templates/skills/build-integration/references/widget-design.md

@@ -77,9 +77,9 @@ import {
 </Stat>;
 ```
 
-- `StatLabel` is uppercase `text-xs` — the one place `text-xs` is a primary
-  label. `StatValue` is the heading face at `text-2xl`, `tracking-tight`,
-  `tabular-nums`. Do not override those sizes.
+- `StatLabel` is the uppercase `text-eyebrow` overline. `StatValue` is
+  `figure`: the heading face at the Headline tier, tabular. Do not override
+  those sizes.
 - `StatChange`'s `tone` is the READING, not the direction: expenses falling is
   `positive`. It pairs an arrow glyph with the color, so the tone never rides
   on hue alone.

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

@@ -48,6 +48,7 @@ command takes `--source <slug>` (else the Source `ekanos use` set) and
 ```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 rename bank-a "Bank A Support"           # the slug follows the name
 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
@@ -92,7 +93,12 @@ Everything in the catalog (`npx @ekanos/cli catalog --source <slug> --json`) is
   `linear.issue_labeled` and `linear.issue_created`; Zendesk declares
   `zendesk.ticket_created` and `zendesk.comment_added`. The catalog's
   `agentEvents` is the authority: read it before concluding a product lacks
-  an event, never infer the set from an example.
+  an event, never infer the set from an example. An event can also need a
+  **channel install** before it ever fires: every Linear event arrives only
+  through the team's Linear agent (`teams connect <team> linear --connection
+  agent`), a second identity beside the personal connection. `teams agents
+  list` names any agent whose trigger waits on one (`channels`, `ready:
+  false`).
 - **Experience** — an Ekanos-native capability (Agents, Workflows, Home…).
   Never "connected"; it is simply on or off for the Source.
 
@@ -161,9 +167,11 @@ every team can use them, with `--team <slug>` only that team can.
 
 **Knowledge** is Ekanos's own knowledge base (no outside account): markdown
 articles, one collection per team plus the Source's **General** collection
-every team reads. A Source admin loads folders of `.md` with
-`ekanos knowledge push <dir> [--team <slug>]`; team members edit theirs in
-the app (Agents → Knowledge). Agents granted `search_knowledge` /
+that every team's agents granted `search_knowledge` also read. A Source admin loads folders of `.md` with
+`ekanos knowledge push <dir> [--team <slug>]` (`--prune` also deletes the
+articles an earlier push of that folder made whose files are gone, never
+ones written or edited in the app); team members edit theirs in the app
+(Agents → Knowledge). Agents granted `search_knowledge` /
 `read_knowledge_article` search their own team's collection and General.
 Skills say *how* to work; Knowledge holds the facts an agent looks up.
 
@@ -176,21 +184,38 @@ 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 enable <team> <key> [--as <member-email>]
+  [--confirm-access]` / `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); `--confirm-access` also confirms it, as you.
+- `ekanos teams agents confirm <team> <key>` — you confirm, as yourself,
+  that the agent may use its connections (the person it runs as's) in runs
+  no one watches; the output says which products' connections that covers.
+  Whoever sets an agent up confirms it — the Source admin, or a team
+  manager in the app — never a plain team member. It confirms only the
+  version it printed: a newer publish since is refused, to be reviewed and
+  confirmed again.
 - `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.
+  On any agent, a change that lets more run on its own drops the
+  confirmation, and the agent uses only what needs none until someone who
+  sets it up confirms again (`--confirm-access` does it in the same step).
+- `ekanos teams agents skills <team> <key> [add|remove <skill>]` — the
+  skills the agent reads; attach a team skill (pushed with
+  `skills push --team`) or a Source one. A provided agent takes them only
+  when its template's `teamCustomization.skills` is on; its own stay.
 - `ekanos teams triggers list|add|remove <team> <key> …` — manual, schedule
-  (`--cron`, `--timezone`), webhook (URL and token shown once) and
+  (`--cron`, `--timezone`), webhook (the token goes to a file only the
+  user can read, never the output) and
   integration events (`event zendesk.ticket_created --filter '{…}'`, or any
   other id in the product's `agentEvents`, e.g. `event linear.issue_labeled
-  --filter '{"labels":["feedback"]}'`).
+  --filter '{"labels":["feedback"]}'`), plus `slack --channel '#name' [--dms]
+  --yes` and `linear [--label <name>]` once the team has installed Slack or
+  Ekanos's Linear app with `ekanos teams connect <team> slack|linear-app`.
 - `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
@@ -222,7 +247,7 @@ 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>
+npx @ekanos/cli reviewers remove <email> [--team <team-slug>] --source <slug> --yes
 ```
 
 `remove` without `--team` takes the person off at every reach; with it, only
@@ -235,11 +260,11 @@ is refused (`USER_NOT_IN_SOURCE`): `ekanos teams list` shows the teams.
 |---|---|
 | 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>` |
+| Agents provided for every team | A Source admin, with `ekanos agents` (`agents archive <key>` retires one once no team has it on) |
+| Testing an unpublished agent version on one team | A Source admin: `ekanos teams agents enable\|pin <team> <key> --draft`, then `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) |
+| 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` (for a team's own agent, only a Source admin who manages that team's agents) |
+| Skills (SKILL.md folders) for every team, or one team's own | A Source admin, with `ekanos skills push` (`--team <slug>` for one team); `ekanos skills archive` retires one nothing uses |
 | Knowledge articles for every team (General), or one team's own | A Source admin, with `ekanos knowledge push` (`--team <slug>` for one team); a team's members in the app |
 | 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 |
@@ -248,5 +273,9 @@ is refused (`USER_NOT_IN_SOURCE`): `ekanos teams list` shows the teams.
 | 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` |
 | 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 |
+| Connecting an integration for a team (signing in) | A team member in the app, or a Source admin with `ekanos teams connect <team> <product>` (`--as <member-email>` when the connection is a person's own) |
 | 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` |
+| Which products a team sees in the app (product scopes) | A Source admin: `ekanos sources scopes` (and `add`/`remove <scope> <product>`), `ekanos teams scope show\|set <team>`; creating a scope is in /admin |
+| Is a team's agent live, and if not, what is the next step | A Source admin, with `ekanos teams agents show <team> <key>`; the whole team on one screen with `ekanos teams show <team>` |
+| Disconnecting a team's integration, removing a team's MCP server | A Source admin, with `ekanos teams disconnect <team> <product> --yes` / `ekanos teams mcp remove <team> <server-key> --yes`, or the team in the app |
+| Confirming an agent may use its connections | Whoever sets it up, as themselves: the Source admin with `ekanos teams agents confirm <team> <key>` (or `enable --confirm-access`, `agents publish --confirm-access`), or a team manager with **Confirm access** in the app — never a plain member. A publish is the confirmation for following teams: no team is held on an earlier version |

package/templates/skills/polish-widgets/references/patterns.md

@@ -116,8 +116,8 @@ import {
 </div>
 ```
 
-`Stat` owns the sizes — the heading face, `text-2xl`, `tracking-tight`,
-`tabular-nums`, and the arrow glyph that pairs with `StatChange`'s color so
+`Stat` owns the sizes — the `figure` value (heading face, Headline tier,
+tabular), the `text-eyebrow` label, and the arrow glyph that pairs with `StatChange`'s color so
 the tone never rides on hue alone. Don't override them, and don't rebuild
 them by hand: a Source that swaps typefaces carries the component, not your
 spans.