@ekanos/cli 0.11.0 → 0.13.0

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

@@ -49,6 +49,15 @@ every `hint`. Look things up in the `ekanos-sdk-docs` MCP server
      `provider-app`) is not set up, so no team can connect. Offer to walk them
      through it now — `references/app-setup.md` — or after the interview. The
      agent can be drafted while it is pending.
+   - **Docs and know-how with no home yet** — when the user asks where the
+     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 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
+     facts the agent looks up.
    - **Missing** — no product does it. Say so plainly. Options: build the
      integration (the `build-integration` skill), use a remote MCP server
      instead if the service offers one (common for docs and knowledge bases:
@@ -99,15 +108,21 @@ in parentheses are the recommendation when the user has no preference.
    connection lives (`references/set-up-an-integration.md` § 2): each team
    connects its own, and it is `required` (the agent waits at "needs setup"
    until the team connects it) or `optional` (its tools appear once
-   connected). One connection shared by every team is not available yet;
-   say so if they ask for it. Then offer to set up any that are not ready.
+   connected). Or, for integrations that support it, the Source connects it
+   once for every team (`owner: "source"`): each team's agent then works only
+   inside what is routed to that team (`references/set-up-an-integration.md`
+   § 5). Then offer to set up any that are not ready.
 6. **What teams may add** — their own MCP servers, their own skills, more of
    their own integrations, or narrowing (removing tools, more approvals). All
    off unless there is a reason. Give one concrete example per knob.
 7. **What starts it** — see `references/triggers.md`. 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.
+   team. Take event ids from the catalog's `agentEvents`, which lists every
+   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.
 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,

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

@@ -39,7 +39,7 @@ conflicting change unless `--overwrite`. Unknown fields are refused.
       "key": "new-tickets",
       "type": "event",
       "event": "zendesk.ticket_created",
-      "filter": { "tags": ["vip", "urgent"], "brand": "123", "reply_as": "internal_note" }
+      "filter": { "tags": ["vip", "urgent"], "brands": ["Acme Support"] }
     },
     {
       "key": "weekday-digest",
@@ -70,6 +70,13 @@ The tool names above are illustrations. Take real ones from
   - `all`: every tool, reads and changes.
   - `custom`: whole `products` (slugs) plus single `tools` (names).
   A tool it must never call is simply not granted — there is no deny list.
+  **Knowledge** (Ekanos's own knowledge base, `ekanos knowledge`): add
+  `search_knowledge` and `read_knowledge_article` to `tools.tools` for an
+  agent that should look things up — they read the team's collection plus
+  the Source's General collection, and the agent never picks which. A
+  feedback agent that turns reviewer corrections into articles also gets
+  `propose_knowledge_article` (a write: it waits for approval by default).
+  These are named one by one; no mode or product grants them.
   Extra team integrations (`teamCustomization.integrations`) need `custom`.
 - **`policy`** — for each granted tool, `auto` (runs on its own) or
   `approve` (waits for a person in the app). `reads`/`writes` set the
@@ -80,8 +87,13 @@ The tool names above are illustrations. Take real ones from
   folders in `agents/<key>/skills/<slug>/` are pushed and added here by
   `agents apply` (see `skills.md`).
 - **`connections`** — by product slug: `{ "owner": "team", "team": "required" | "optional" }`.
-  A product with no entry is `team`/`optional`. `owner: "source"` (one
-  connection for every team) is refused today.
+  A product with no entry is `team`/`optional`. `{ "owner": "source" }` is
+  one connection the Source admin makes for every team (`ekanos apps
+  connect`), used only by this provided agent and limited per team by the
+  Source's routing (`ekanos routes`); `apply` refuses it for an integration
+  that does not declare `sourceConnection`. Teams cannot add a Source-owned
+  product in their overlay. `mcpServers` with `owner: "source"` are still
+  refused.
 - **`mcpServers`** — remote MCP servers (streamable HTTP, `https` only, up to
   10): `key` (lowercase, ≤31), `name`, `url`, `auth` (`none` | `bearer` |
   `oauth`, default `oauth`), `owner`/`team` as for connections, and
@@ -103,9 +115,14 @@ The tool names above are illustrations. Take real ones from
   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` …).
+    `ekanos catalog <product> --json` lists under `agentEvents` — every
+    event the product declares, e.g. Zendesk `zendesk.ticket_created` and
+    `zendesk.comment_added`, Linear `linear.mentioned`, `linear.assigned`,
+    `linear.issue_labeled` and `linear.issue_created`); `filter` holds only
+    the keys in that event's `filterFields` (Zendesk: `brands`, `groups`,
+    `tags`, `organizations`, each a list; Linear: `teamKeys`, plus `labels`,
+    which `linear.issue_labeled` requires). Zendesk's `reply_as` is not a
+    filter: it is set in the Zendesk trigger's body (`triggers.md`).
   - `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
@@ -138,7 +155,9 @@ 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
+  --filter tags=vip,urgent --filter brands=Acme,
+ekanos agents triggers <key> add event feedback-label --event linear.issue_labeled \
+  --filter labels=feedback,
 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."
@@ -151,7 +170,9 @@ 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.
+`false` a switch, anything else text. A list field (`tags`, `brands`,
+`labels`, `teamKeys` …) needs a list even for one item, so end a single
+item with a comma: `--filter labels=feedback,`. `--disabled` adds a trigger turned off.
 
 ## What the host checks on `apply`
 

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

@@ -47,7 +47,8 @@ working from those rather than from Ekanos.
   npx @ekanos/cli apps set <product> --source <slug>
   ```
 
-  It asks for the client ID, then the secret with hidden input. For a team's
+  It asks for the client ID, then the secret with hidden input; Enter keeps
+  a saved value, so either can be changed on its own. For a team's
   app, they enter the fields in the team's setup panel in the Ekanos app.
 - Then check: `apps show <product> --source <slug> --json` should say
   `configured: true`, and the catalog's step should be `done`. Tell them

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

@@ -35,12 +35,14 @@ integration: its members, its data and its connections.
 |---|---|---|---|
 | **Each team, through the Source's app** | One app, created once for the whole Source under the Source's own name. Each team then signs in through it. | The Source admin creates the app (`references/app-setup.md`, `ekanos apps set`); each team connects | Linear, Slack: products where every team is a separate workspace |
 | **Each team, with its own app** | Each team creates its own app in the provider and enters its credentials | Each team, or the Source admin on the team's behalf with `ekanos teams` (below) | Zendesk: each bank or business has its own Zendesk |
-| **One connection for the whole Source** | Every team's provided agent uses the Source's single connection, limited to what is routed to that team | The Source admin, once | One shared Zendesk for many teams. **Not available yet**: say so, and suggest a connection per team for now |
+| **One connection for the whole Source** | Every team's provided agent uses the Source's single connection, limited to the records routed to that team (for Zendesk, the tickets of the organizations mapped to it) | The Source admin, once, plus a routing table | One shared Zendesk for many teams (§ 5). Only for integrations that declare it (Zendesk from 0.2.0; `agents apply` refuses the others), and only for **provided agents**: a team's own agents, widgets and assistant never use it |
 
 The agent records the choice in `agent.json` → `connections`:
 `{ "zendesk": { "owner": "team", "team": "required" } }` means each team
 uses its own Zendesk and the agent waits at "needs setup" until it is
-connected (`references/agent-json.md`).
+connected (`references/agent-json.md`). `{ "zendesk": { "owner": "source" } }`
+means every team's copy of the agent uses the Source's one Zendesk; teams
+connect nothing for it.
 
 ## 3. Walk it, one step per message
 
@@ -60,11 +62,16 @@ connected (`references/agent-json.md`).
   `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
+- **Connect with `teams connect <team> <product>`, run by the user in their
+  own terminal.** It does whatever the integration needs: asks a form's fields
+  (secrets hidden), runs the team-app prompts first when the team's own app is
+  missing, or opens a one-time sign-in link and waits until the team is
+  connected. The provider's consent is still a person's click, by a member of
+  the team (owner/admin for a team-wide connection): the user when they are
+  one, else `--as <email>` prints a link to send that member. `--link-only`
+  prints just the team's page. Tell them who should sign in: the account the
+  integration acts as. If the product is not enabled for the Source, a
+  super-admin enables it (`sources products` shows what the Source has). 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
@@ -80,8 +87,13 @@ pilot), the team-side steps can be done from the CLI:
 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.
+   for each field and hides the secret ones; Enter keeps a saved value. It
+   refuses to run inside Claude; that is deliberate. To change one value
+   later, they need not re-enter the rest:
+   `teams app set <team> <product> --field <name>` asks for just that field
+   (names are in brackets in `teams show`), `--set <name>=<value>` sets a
+   non-secret field (a subdomain, a client ID) without a prompt — you may run
+   that one yourself — and `--clear <name>` removes a value.
 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
@@ -90,6 +102,59 @@ pilot), the team-side steps can be done from the CLI:
 5. Someone on the team opens the link from `teams show` and clicks Connect.
 6. `teams show` again: every step ✓.
 
+## 5. One connection for the whole Source
+
+Use it when one account at the provider serves many teams: one Zendesk where
+each bank is an organization. The Source admin connects once; events are
+routed to teams by a value inside them (for Zendesk, the ticket's
+**organization**); each team's provided agent then works only inside what is
+routed to that team. Say all three parts before starting, and say plainly
+what it does **not** do: a team's own agents, widgets and assistant never see
+the Source's connection.
+
+1. **Connect, once, as the Source.** For an integration where each customer
+   brings its own app (Zendesk), first create that app in the shared account,
+   exactly as in the worked example below (OAuth client, Confidential), but
+   once, for the Source. Then, **in their own terminal**:
+   `npx @ekanos/cli apps connect <product> --source <slug>`. It asks for the
+   app's fields it doesn't have yet (Zendesk: subdomain, client ID, client
+   secret, webhook signing secret; secrets hidden, never as flags, and it
+   refuses to run inside Claude), prints the redirect URL to register and the
+   consent link, then waits up to ten minutes until it is connected. Whoever
+   clicks the link is the account the integration acts as for every team, so
+   suggest a dedicated seat ("Support agent"). `apps list` shows every
+   integration the Source can connect this way. Check with
+   `npx @ekanos/cli apps show <product> --source <slug>`: connected, by whom,
+   when. In the app the same lives in the Source admin area under
+   **Shared integrations › Connections**.
+2. **The Source's webhook.** `npx @ekanos/cli routes webhook <product> --source <slug>`
+   prints one URL, **once**, for the whole Source. Paste it into the
+   provider at that moment (for Zendesk, the webhook the triggers notify).
+   The team webhooks from § 4 are not used for this connection.
+3. **Map values to teams.** `npx @ekanos/cli routes options <product> --source <slug>`
+   lists what can be mapped (Zendesk organizations, with names), then one
+   line per team:
+   `npx @ekanos/cli routes set <product> <value> <team> --source <slug>`.
+   `routes list` shows the table. One value goes to exactly one team.
+4. **The agent.** In `agent.json`, `connections.<product>` is
+   `{ "owner": "source" }`; `agents apply` accepts it only when the
+   integration supports a Source connection. Teams turn the agent on as
+   usual; they connect nothing for that product.
+5. **Try it.** A ticket from a mapped organization starts that team's agent
+   only. A ticket from an organization nobody mapped starts **nothing**: the
+   integration leaves its own fixed note (Zendesk: an internal note saying
+   no team has it yet), and it is listed by
+   `npx @ekanos/cli routes unrouted <product> --source <slug>`. Map the
+   value, then `routes replay <event-id>` to send it on once.
+
+What is enforced, so you can say it accurately: the host routes each event
+to exactly one team or to none (never to a default team), and gives a
+team's agent only that team's mapped values (`ctx.routing`); the
+integration's tools keep to them (for Zendesk, reads are limited to the
+team's organizations, and anything that reads or changes one ticket first
+checks its organization and refuses otherwise). The agent's policy,
+approvals and audit apply exactly as on a team connection.
+
 ## Worked example: Zendesk for one team
 
 The steps below are what Zendesk's own setup says, in order. Take the URLs
@@ -104,7 +169,8 @@ from `teams show zendesk`.
    secret.
 3. **Credentials into Ekanos.** `ekanos teams app set <team> zendesk` in
    their terminal: subdomain, client ID, client secret, webhook signing
-   secret.
+   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.
 5. **Zendesk triggers.** Objects and rules › Triggers: one for *Ticket is

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

@@ -70,9 +70,12 @@ 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`.
+- Prompt skills only. At run time the agent gets the whole folder: loading
+  the skill returns `SKILL.md`'s instructions plus the list of every other
+  file (`references/`, `assets/`, …), and it reads one on demand
+  (`read_skill_file`) when the instructions point to it — so keep `SKILL.md`
+  short and name the reference to open, e.g. `references/policy-2026.md`.
+  Text files are read in parts of about 12,000 characters; binary files are
+  listed but cannot be read as text.
 - A `scripts/` folder is refused: executable skills need the in-app review.
 - Up to 100 files, 1 MB per file, 3 MB per skill.

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

@@ -20,7 +20,14 @@ A Source admin can add them for the team from the terminal instead:
 `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"]}'`). 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
+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,23 +46,45 @@ 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
+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).
 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.
+| 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
 

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

@@ -53,7 +53,9 @@ npx @ekanos/cli teams members invite bank-a raj@bank-a.com --role admin   # defa
 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 +68,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 +88,11 @@ 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.
 - **Experience** — an Ekanos-native capability (Agents, Workflows, Home…).
   Never "connected"; it is simply on or off for the Source.
 
@@ -97,8 +112,12 @@ Ask them in this order; each catalog product reports where it stands
    connection: two teams using Linear each connect their own. A Source admin
    can do a team's setup for it from the terminal (`ekanos teams show`,
    `ekanos teams app set`, `ekanos teams webhook`), but signing in is a click
-   by someone on the team. One connection for the whole Source, shared by
-   every team's agents, is not available yet.
+   by someone on the team. For integrations that support it, a Source admin
+   can instead connect **once for the whole Source** (`ekanos apps connect`),
+   for provided agents only: events are routed to teams by a value inside
+   them (`ekanos routes`, Zendesk by organization), and each team's agent
+   works only inside its own routed values. A team never sees that
+   connection.
 3. **Set up by the team** where needed — some integrations have each team
    bring its own app (a team-provided app: client id, secret, webhook signing
    secret entered in Ekanos). Those secrets are typed into the app, never
@@ -140,6 +159,14 @@ 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
+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` /
+`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
@@ -161,7 +188,9 @@ always `ekanos teams <area> <verb> <team> …`:
   follows its template unless the template turns on team overrides for it.
 - `ekanos teams triggers list|add|remove <team> <key> …` — manual, schedule
   (`--cron`, `--timezone`), webhook (URL and token shown once) and
-  integration events (`event zendesk.ticket_created --filter '{…}'`).
+  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"]}'`).
 - `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
@@ -211,8 +240,11 @@ is refused (`USER_NOT_IN_SOURCE`): `ekanos teams list` shows the teams.
 | 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) |
+| 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 |
+| Which team gets which events on that connection (Zendesk organization → team) | A Source admin, with `ekanos routes` (`webhook`, `options`, `set`, `list`, `remove`, `unrouted`, `replay`), or **Shared integrations › Routing** in the Source admin area |
 | 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) |