@ekanos/cli 0.12.0 → 0.14.0

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,14 +13,31 @@ 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
 `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
+Any event in a connected integration's `agentEvents` is added this way,
+including every Linear integration event (`event linear.issue_labeled
+--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
 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.
 
@@ -39,30 +56,77 @@ team's triggers follow the template and these commands refuse to change them.
 
 ## Integrations with agent events
 
-Check `ekanos catalog <product> --source <slug> --json` for what is actually
-there; these are the known shapes.
+`ekanos catalog <product> --source <slug> --json` is the authority: its
+`agentEvents` lists **every** event the product declares, with each one's
+filter keys (`filterFields`). The lists below are the known shapes; never
+conclude a product lacks an event because an example here or elsewhere
+names only one. A refused event id is answered with the ids the product
+does declare, and a refused filter with the keys the event takes.
 
-**Linear** (`linear.mentioned`, `linear.assigned`, `linear.issue_labeled`) —
-the agent becomes a teammate in Linear: @mention it, assign it an issue, or
-apply a label. 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).
+An event can be declared and still never fire for a team until the team
+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
+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
 
-**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
-(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.
+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 |
+| `linear.assigned` | someone assigns (delegates) an issue to the agent | `teamKeys` | webhook with **Agent session events** ticked |
+| `linear.issue_labeled` | someone applies one of the given labels to an issue | `labels` (**required**), `teamKeys` | webhook with **Issues** ticked |
+| `linear.issue_created` | someone creates an issue (optionally only with given labels) | `labels`, `teamKeys` | webhook with **Issues** ticked |
+
+**Zendesk** — 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 (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.
+
+| Event | Starts when | Filter keys | Needs in Zendesk |
+|---|---|---|---|
+| `zendesk.ticket_created` | a new ticket arrives | `brands`, `groups`, `tags`, `organizations` | a Zendesk trigger on *Ticket is Created* notifying the webhook |
+| `zendesk.comment_added` | an end user (requester or CC) comments on a ticket; agent and admin comments never start it | `brands`, `groups`, `tags`, `organizations` | a **second** Zendesk trigger, on a customer's public reply, notifying the webhook |
+
+Filter values are lists (`{"tags":["billing"],"brands":["Acme Support"]}`);
+brands, groups and organizations match by name or id. Where the answer goes
+(`reply_as`) is set in the Zendesk trigger's body, not in the filter.
 
 ## Checklist to hand each team
 
 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 person it runs as runs `npx @ekanos/cli teams agents
+   confirm <team> <key> --source <slug>` as themselves (or turned it on with
+   `--confirm-access`). `teams agents list <team>` shows anyone still to.
+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,12 +48,15 @@ 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
 npx @ekanos/cli teams members role bank-a raj@bank-a.com member
 npx @ekanos/cli teams members remove bank-a raj@bank-a.com --yes
-npx @ekanos/cli teams connect bank-a zendesk                  # the link a member opens to connect
+npx @ekanos/cli teams connect bank-a zendesk                  # connect it for the team (asks, signs in, waits)
+npx @ekanos/cli teams connect bank-a linear --as raj@bank-a.com   # a sign-in link for raj
+npx @ekanos/cli sources products                             # what the Source has enabled (super-admin enables)
 ```
 
 - `create` without `--owner` seats the person running it as the team's
@@ -66,9 +69,18 @@ npx @ekanos/cli teams connect bank-a zendesk                  # the link a membe
   customized ones). Pick a reviewer for agents by the role holding
   `agents.review` in `teams roles list`. The primary owner's role cannot be
   changed here; ownership moves in the app.
-- Connecting an integration is always a team member signing in in their
-  browser. `teams connect` prints the link to send them and whether the team
-  is connected yet; `teams show <team> <product>` has the full checklist.
+- `teams connect <team> <product>` does the connect: it asks a form's fields
+  at the user's terminal (hidden for secrets — so the user runs it, never you
+  with values), runs the team-app prompts first when needed (Zendesk), or
+  opens a one-time sign-in link and waits. The person who signs in is a team
+  member (owner/admin for a team-wide connection): the user when they are
+  one, else `--as <email>` prints a link to send that member. `--no-wait`,
+  `--no-open`, `--link-only` (just the team's page). `teams show <team>
+  <product>` has the full checklist.
+- A product the Source does not have is refused; `sources products` lists
+  what it has. Enabling one is a super-admin grant (`sources products enable`)
+  that an `ekanos login` session cannot make — the super-admin does it in
+  /admin.
 
 ## Products: integrations and experiences
 
@@ -77,7 +89,16 @@ Everything in the catalog (`npx @ekanos/cli catalog --source <slug> --json`) is
 
 - **Integration** — a connection to a third party (Linear, Zendesk, Slack…).
   Brings tools an agent can call, and may declare **agent events** that start
-  agents (`linear.mentioned`, `zendesk.ticket_created`…).
+  agents — Linear declares `linear.mentioned`, `linear.assigned`,
+  `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 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.
 
@@ -144,6 +165,16 @@ Skills are folders (`SKILL.md` + references) an agent loads when needed.
 A Source admin pushes them with `ekanos skills push <dir>`: at Source level
 every team can use them, with `--team <slug>` only that team can.
 
+**Knowledge** is Ekanos's own knowledge base (no outside account): markdown
+articles, one collection per team plus the Source's **General** collection
+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.
+
 The `build-agent` skill walks through choosing between these and building one.
 
 A Source admin can also do a team's agent setup from the terminal, acting on
@@ -153,19 +184,36 @@ 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; with `--confirm-access`, you).
+- `ekanos teams agents confirm <team> <key>` — the person the agent runs as
+  confirms, as themselves, that it may use their connections in runs no one
+  watches; the output says which products' connections that covers. It
+  confirms only the version it printed: a newer publish since is refused, to
+  be reviewed and confirmed again. Nobody confirms for anyone else.
 - `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
+  of the person it runs as, and the agent waits for them to confirm again
+  (`--confirm-access` when that person is you).
+- `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
-  integration events (`event zendesk.ticket_created --filter '{…}'`).
+  (`--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"]}'`), 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
@@ -197,7 +245,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
@@ -210,11 +258,12 @@ 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 |
 | One connection for the whole Source, used by provided agents in every team | A Source admin, with `ekanos apps connect` (status: `ekanos apps show`), or **Shared integrations › Connections** in the Source admin area |
@@ -222,5 +271,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 a person's connections | Only the person it runs as, signed in as themselves: `ekanos teams agents confirm <team> <key>` (or `enable --confirm-access`, `agents publish --confirm-access`), or **Confirm access** in the app. On a team held on an earlier version (a newer one reaches further than they confirmed) it moves the team to the version waiting |

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.