@orchestraworks/cli 0.5.0 → 0.5.2

package/skills/orchestra/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: orchestra
-description: Use when you need to understand or explain an Orchestra concept - organization, role, agent, version, environment, machine, network rules, secret, model gateway and gateway key, session, pipeline, work item, workflow rules, trigger, skill, file, credit, plan, or the factory as code - or how the orchestra command line works, what the platform cannot do yet, and where an agent's knowledge belongs. A reference to read, not a list of steps.
+description: Use when you need to understand or explain an Orchestra concept - organization, role, agent, version, environment, machine, network rules, secret, reaching a model (subscription, model gateway and gateway key, own key), session, pipeline, work item, workflow rules, trigger, skill, file, plan, or the factory as code - or how the orchestra command line works, what the platform cannot do yet, and where an agent's knowledge belongs. A reference to read, not a list of steps.
 ---
 
 # Orchestra: the ideas behind the platform
@@ -17,14 +17,14 @@ Sections:
 4. Environment, machine, size, image and setup script
 5. Network rules (egress)
 6. Secret
-7. Model gateway and gateway key
+7. Reaching a model: subscription, model gateway or own key
 8. Session and turn
 9. Pipeline and stage
 10. Work item
 11. Workflow rules and the judge
 12. Trigger (listener)
 13. Skill and file
-14. Credit and plan
+14. Plan
 15. The factory as code
 16. How the CLI works
 17. Connections
@@ -41,7 +41,7 @@ platform/.../service/project/ProjectReferenceService.kt:241-245 (project referen
 platform/.../workplane/service/WorkplaneWorkItemService.kt:206,556 (assignee confined to the item's project or
 the shared space). -->
 
-**What it's for.** The organization is the customer's account: everything they build and pay for sits in it.
+**What it's for.** The organization is the customer's account: everything they build sits in it.
 Roles decide who may do what, so each person and each agent can do its own job and no more.
 
 **What it is.** A *member* is a person, an agent or a service account with a membership in the organization.
@@ -63,7 +63,7 @@ in a project may point at its own project or the shared space; a row in the shar
 shared space. So a shared agent takes items from every project, and an agent in a project takes items only
 from that project.
 
-**In the starter.** The organization has no project. Each of the four agents starts with `agent-worker`. The
+**In the starter.** The organization has no project. Each of the five agents starts with `agent-worker`. The
 Manager Agent is then given `agent-manager`, because it works in every pipeline and changes the Engineer
 Agents.
 
@@ -89,8 +89,9 @@ model the harness calls, set in the agent's model settings.
 the model gateway when its model settings turn the gateway on (section 7). Work reaches it as sessions (section
 8), most often started by assigning it a work item (section 10).
 
-**In the starter.** The Manager Agent and Engineer Agent lg run `claude` on `claude-opus-5-5`. Engineer Agent md
-runs `codex` on `gpt-6.1-sol`, and Engineer Agent sm runs `codex` on `gpt-6-luna`.
+**In the starter.** The Manager Agent, Engineer Agent lg and Engineer Agent bare run `claude` on
+`claude-opus-5-5`. Engineer Agent md runs `codex` on `gpt-6.1-sol`, and Engineer Agent sm runs `codex` on
+`gpt-6-luna`. Engineer Agent bare takes only the Bootstrap's baseline replays.
 
 **Cannot yet.**
 - Change an agent's harness after it is created. Make a new agent instead.
@@ -137,7 +138,7 @@ ports, settings and network rules. A *machine* is one live computer made from it
 machine carries one agent.
 
 - *Size.* CPU and memory, from a fixed ladder: 0.5, 1, 2, 4, 8, 16 or 32 CPU, with 2 GB of memory per CPU.
-- *Image.* The disk the machine starts from. The stock image is Debian with Node 22, Java 21 and 25, git,
+- *Image.* The disk the machine starts from. The stock image is Debian with Node 24, Java 21 and 25, git,
   Docker with Compose, `gh` and `acli`, and all four harnesses.
 - *Setup script.* A script that runs once, as root, on each new machine, before the agent arrives and before
   any code is cloned. Bash on Linux, PowerShell on Windows. At most 64 KiB, stopped after 10 minutes. A failed
@@ -147,6 +148,9 @@ machine carries one agent.
 - *Ports.* Each declared port gets a *machine endpoint*, a web address that only signed-in members of the
   organization can open.
 - *Home.* A volume at `/home` keeps the agent's files when it moves to a new machine.
+- *Working folder* (`workingDirectory`). Not released yet: a folder where the harness starts every
+  conversation. Today the agent clones or uses its code under `/work` in its own first turn, as the
+  starter's agents do.
 - *Lifetime.* A conversation lets go of its machine 5 minutes after its last turn, and a machine lives at
   most 2 hours, unless the environment sets other values.
 
@@ -154,9 +158,10 @@ machine carries one agent.
 disks reaches only machines made after the change. A change to the network rules is different: it reaches
 running machines too (section 5).
 
-**In the starter.** Four environments, one per agent: `manager-work-lg` and `engineer-work-lg` at 32 CPU,
-`engineer-work-md` at 16, `engineer-work-sm` at 2. Each uses the stock image, starts Docker in `lib/setup.sh`,
-and keeps Docker's data on its own disk.
+**In the starter.** Four environments: `manager-work-lg` and `engineer-work-lg` at 32 CPU, `engineer-work-md`
+at 16, `engineer-work-sm` at 2. Engineer Agent bare uses `engineer-work-lg` with Engineer Agent lg; each agent
+still gets its own machines. Each uses the stock image, starts Docker in `lib/setup.sh`, and keeps Docker's
+data on its own disk.
 
 **Can.**
 - Linux micro VMs at every size; full Linux VMs (2 to 8 CPU); Windows VMs (4 or 8 CPU).
@@ -238,52 +243,58 @@ terminal (`fromCommandLine`), or from a gateway key the platform mints (`fromGat
 
 **Cannot yet.** Read a value from a file on the developer's computer. Load the file into the shell first.
 
-## 7. Model gateway and gateway key
-
-<!-- Sources, on develop at 19459f9ebb: docs/architecture/model-gateway.md:32-40 (gateway key; platform models
-billed to credit; own provider keys), :576-580 and :974-983 (the monthly cap is per key, compared at catalog
-rates before the markup; a guard against a runaway loop), :991 (/gateway-keys); egress.md:937-941 (the key
-reaches the gateway through an ordinary rule and a Secret);
-platform/.../service/CreditMeteringService.kt:43 (getKeySpendCached sums one key's month);
-platform/.../model/GatewayKey.kt:15-60 (monthlyCreditCap; monthToDateCreditSpend on each read; the cap check
-may lag minutes); console/src/features/models/GatewayKeysPanel.tsx:69, 544, 748 and
-console/src/app/navSections.ts:83 (Settings > Gateway keys sets the cap in dollars; a credit is $0.01; the
-console shows no per-key spend). Price: migrations/v3/2468/dml.sql (gateway fee 0.1, so platform tokens cost 1.1
-times list and own-key tokens 0.1 times list); it lands with that change. develop still holds 0.2
-(docs/architecture/commercial-plans-and-credits.md:114-120). Kit: cli/src/constructs/environment.ts:129 (default
-host models.orchestraworks.ai). -->
-
-**What it's for.** The model gateway is a hosted service that manages model spending in one place. Every agent's
-model calls go through it, so the organization pays one bill, from its credit, and sees what each gateway key
-spends. Each key can carry a monthly cap, a guard that stops a runaway agent loop from spending without limit.
-Today:
-
-- In the console, at **Settings > Gateway keys**, a person sets or lifts a key's monthly cap, in US dollars.
-- `orchestra gateway-keys get <key> --output json` shows the key's spend this month, `monthToDateCreditSpend`, in
-  credits. A credit is $0.01. The console does not show per-key spend yet.
-- The cap is compared at the model's list price, before the 10%, and the gateway can notice a reached cap up to a
-  few minutes late. The nightly charge is the final number.
-
-**What it is.** A *gateway key* is a key to `models.orchestraworks.ai`, stored as a secret. The network edge adds
-it to each model call, so no agent and no person sees it. The gateway swaps it for the AI provider's own key, so
-the customer brings no Anthropic or OpenAI key. Usage is charged to the organization's credit at the provider's
-list price plus 10%. Without the key, an agent's first message fails with "Invalid API key".
-
-The 10% price lands with a price change that has not reached the platform yet. Until then the charge is list
-price plus 20%.
-
-**How it relates.** The key reaches the gateway through an ordinary allow rule on the gateway's host, with the
-key's secret (sections 5 and 6). The agent turns the gateway on in its model settings (section 2).
-
-**In the starter.** One key, `model-gateway`, for the whole organization, with no cap. Every environment declares
-the gateway rule.
-
-**Can.** Bring the organization's own provider key instead, one per provider for the whole organization. Calls
-still go through the gateway and the gateway key stays. The provider bills the organization for the tokens, and
-Orchestra charges 10% of the list price for the gateway, from the same price change.
-
-**Cannot yet.** A gateway route without the rule on the environment. An environment declared in code keeps only
-what it declares, so the rule must be on every environment.
+## 7. Reaching a model: subscription, model gateway or own key
+
+<!-- Sources, on develop at 0ddbb8568d: docs/architecture/model-gateway.md:32-40 (gateway key; own provider
+keys), :576-580 and :974-983 (a per-key monthly cap), :991 (/gateway-keys); docs/architecture/egress.md:937-941
+(the key reaches the gateway through an ordinary rule and a Secret); console/src/app/navSections.ts:83
+(Settings › Gateway keys). Kit: cli/src/constructs/environment.ts:129 (default host models.orchestraworks.ai);
+cli/docs/REFERENCE.md "Model traffic through the gateway" and "Gateway keys and bring-your-own provider keys";
+cli/skills/orchestra-fdk/references/authoring.md "Secrets are recipes, never values" (the Claude sign-in
+recipe). -->
+
+**What it's for.** Every agent that runs a model needs a way to reach it. There are three options, and the
+team uses the one that matches what it already has. Each agent's model settings and its environment's
+network rules carry the option (sections 2 and 5).
+
+**A Claude or Codex subscription.**
+
+- *Claude.* `claude setup-token` prints a long-lived token. It is stored as a secret, and the network edge
+  adds it to each call to `api.anthropic.com`. The machine holds only a placeholder token and an empty API
+  key, so no agent and no person sees the real one. Never put the token in an environment's settings: they
+  are plain text.
+- *Codex.* A personal access token, made by a ChatGPT Business or Enterprise member, or a separate ChatGPT
+  sign-in kept on a `/home` volume that every machine using it shares. A Codex sign-in stays off the model
+  gateway, which refuses its requests with `model_not_found`.
+
+**An Orchestra account, through the model gateway.** The model gateway is a hosted service at
+`models.orchestraworks.ai`. One endpoint reaches OpenAI, Anthropic and open models. A *gateway key* is a key
+to it, stored as a secret. The network edge adds it to each model call, so no agent and no person sees it.
+Without it, an agent's first message fails with "Invalid API key".
+
+- *Routing.* `orchestra model-configs` sets which providers serve a model, and in which order, so a call
+  falls back to the next provider. `orchestra model-aliases` gives a model the organization's own name, such
+  as `default`, which one change points elsewhere.
+- *A provider key through the gateway.* The organization can add its own key for one provider, a
+  `ModelProviderKey`, which the gateway then uses for that provider's calls. The gateway key stays.
+- *A cap.* Each gateway key can carry a monthly cap, set in the console at **Settings › Gateway keys**.
+
+**Their own provider API key.** The team's Anthropic or OpenAI API key is a secret that the network edge adds
+to calls straight to the provider, with no gateway in between.
+
+**How it relates.** Each option reaches the model through an ordinary allow rule that adds a secret (sections
+5 and 6). An agent on the model gateway turns it on in its model settings (section 2). An agent on a
+subscription or its own key turns it off. For plan questions, send the person to **Settings › Plan & usage**
+in the console.
+
+**In the starter.** The code as written uses the model gateway: one key, `model-gateway`, and the gateway rule
+on every environment. A subscription or an own key needs an edit, as the orchestra-fdk skill's step 6 says.
+
+**Cannot yet.**
+- A gateway route without the rule on the environment. An environment declared in code keeps only what it
+  declares, so the rule must be on every environment.
+- Not released yet: the worker settings that put a Codex sign-in on a machine. Until they are, a `codex`
+  agent uses the model gateway or an OpenAI API key.
 
 ## 8. Session and turn
 
@@ -350,8 +361,8 @@ and a stage's conditions can read them.
 **How it relates.** An item's sessions are listed on it (section 8). An agent can be asked about an item without
 taking it over (`work-items message`). Rules and judges act on items (section 11).
 
-**In the starter.** Set up, Study and Experiment items in Onboarding. The Manager Agent creates Replay items and
-assigns them to Engineer Agents.
+**In the starter.** The Set up and Bootstrap items in Onboarding. In the Bootstrap, the Manager Agent creates
+Replay items and assigns them to Engineer Agent lg and Engineer Agent bare.
 
 **Cannot yet.** Declare items in the factory code. Create them with `orchestra work-items create`.
 
@@ -400,44 +411,40 @@ switching a listener on.
 
 ## 13. Skill and file
 
-<!-- Sources, on develop at 19459f9ebb: docs/architecture/agent-skills-and-runtime-manifest.md:53-60, 100-150 (a
+<!-- Sources, on develop at 0ddbb8568d: docs/architecture/agent-skills-and-runtime-manifest.md:53-60, 100-150 (a
 File is stored bytes; a Skill is a set of files by reference with a root SKILL.md carrying name and
 description; an agent references up to 32 skills), :762-770 (global skills); docs/architecture/artifacts.md:36-44
 (File under everything). Kit: cli/src/constructs/skill.ts (declare a Skill in code); cli/src/cli/upload.ts
-(--file); platform/.../service/FileService.kt:163-165 (no projectId means the shared space). -->
+(--file); platform/.../service/FileService.kt:163-165 (no projectId means the shared space);
+platform/src/main/resources/catalog/skills/ (the platform's own skills, served as skill_<key>);
+cli/src/constructs/skill.ts:111 (Skill.fromId). -->
 
 **What it is.** A *file* is stored content, text or any upload. A *skill* is a set of files with a root
 `SKILL.md` that has a `name` and a `description`: instructions an agent loads when it needs them. An agent lists
 the skills it uses, up to 32.
 
+**Platform skills.** Orchestra's own skills have ids of the form `skill_<key>`, such as `skill_sf-report`.
+An agent gets one only when its skills list names it: `skillIds` on the agent, or `Skill.fromId` in the kit.
+Not released yet: managed skills that a new agent's list carries by default (`includeManagedSkills`).
+
 **How it relates.** An agent version records which skills an agent uses, not their text (section 3). Files also
 carry work between agents.
 
-**In the starter.** No skills are declared yet. The Manager Agent uploads each git bundle as a file, and the
-Engineer Agent answers with a patch file.
-
-## 14. Credit and plan
+**In the starter.** The Manager Agent uploads each git
+bundle as a file, and the Engineer Agent answers with a patch file. The Bootstrap writes a codebase skill, and
+commissioning adds it to the Engineer Agents.
 
-<!-- Sources, on develop at 19459f9ebb: docs/architecture/commercial-plans-and-credits.md:413-430 (two buckets:
-allowance resets monthly and floors at 0; purchased persists and may go negative; a burn draws allowance first),
-:95 (1 credit = $0.01), :157 (the starting grant goes to purchased), :221-240 (individual, scale, enterprise),
-:867-880 (balance and ledger reads); docs/architecture/model-gateway.md:32-40 (model use billed to credit). -->
+## 14. Plan
 
-**What it's for.** Credit is one prepaid meter for everything the organization uses: machine time and model
-calls. The *plan* sets the price, the monthly allowance and the limits.
+<!-- Sources, on develop at 0ddbb8568d: console/src/app/navSections.ts:149 (Settings › Plan & usage);
+cli/docs/REFERENCE.md "Model traffic through the gateway" (no secrets or managed egress on the individual
+plan). -->
 
-**What it is.** A credit is worth $0.01. An organization has two balances:
+The organization's *plan* sets its limits. There are three plans: `individual`, `scale` and `enterprise`. For
+any plan question, send the person to **Settings › Plan & usage** in the console. Name no figure yourself.
 
-- *Allowance*: the plan's monthly credit. Use it or lose it: it resets each month and never goes below zero.
-- *Purchased*: credit bought, and a plan's one-time starting grant. It stays from month to month, and can go
-  below zero.
-
-Use takes from the allowance first, then from purchased. There are three plans: `individual` (free to hold, no
-monthly allowance, a one-time 1,000-credit grant, one member), `scale` ($100 a month, which is 10,000 credits
-with five seats), and `enterprise` (quoted per customer).
-
-**How it relates.** Model calls through the gateway (section 7) and machine time (section 4) use credit. The
-organization's balance and its credit history, with the model of each charge, are on the organization.
+**Cannot yet.** On the `individual` plan: store a secret, or add one at the network edge. An apply that
+declares either stops with a plan error.
 
 ## 15. The factory as code
 
@@ -473,44 +480,37 @@ pipelines, workflows, triggers, skills, connections and projects.
 ## 16. How the CLI works
 
 <!-- Sources, on the kit's own branch: cli/src/cli/main.ts:60-160 (two jobs; nouns match API paths; standard
-verbs; --output json; --body @file.json; --file; values masked; approval defaults; orchestra api), cli/src/cli/core/
-auth.ts:1-45 (ORCHESTRA_API_TOKEN, then the login profile, then the machine's edge; default address
-api.orchestraworks.ai; ORCHESTRA_BASE_URL), cli/src/cli/core/profile.ts:39-52 (profiles in
-~/.config/orchestra/config.json, "default"), cli/src/cli/core/invocation.ts:19 (--profile),
-cli/src/generated/cli-commands.json ("me get"; each command's answer), cli/src/cli/core/output.ts:94-113 and
-:143-145 (json prints the answer as it is), cli/src/cli/core/errors.ts:287-296 and :366-370 (the json error, on
-stderr), cli/src/cli/core/login.ts:361-363 (a pasted token keeps no refresh token). -->
+verbs; --output json; --body @file.json; approval defaults; orchestra api), cli/src/cli/core/auth.ts:1-45
+(ORCHESTRA_API_TOKEN, then the login profile, then the machine's edge; ORCHESTRA_BASE_URL),
+cli/src/cli/core/profile.ts:39-52 (profiles in ~/.config/orchestra/config.json), cli/src/generated/cli-commands.json
+(each command's answer), cli/src/cli/core/output.ts:94-113 and :143-145 (json prints the answer as it is),
+cli/src/cli/core/errors.ts:287-296 and :366-370 (the json error, on stderr), cli/src/cli/core/login.ts:361-363 (a
+pasted token keeps no refresh token); cli/docs/REFERENCE.md section 3 (one membership is selected for you). -->
 
 The `orchestra` command does two jobs. *Factory as code* (section 15) is where change happens. *Platform commands*
 read and probe what exists: observe with commands, change in code.
 
-- **Nouns and verbs.** `orchestra <noun> <verb>`. Nouns match the API's paths: `agents`, `work-items`, `sessions`,
-  `gateway-keys`, `organization-memberships` and more. The usual verbs are `list`, `get`, `create`, `update` and
-  `delete`. Commands keep their own verb, such as `work-items assign`, `work-items move` and
-  `sessions interrupt`. `orchestra sessions wait <session id>` waits for a turn to end. `orchestra <noun> --help` lists a noun's
-  verbs and flags.
-- **Output.** `--output json` on every platform command. The default is a table for people. JSON mode prints
-  the API's answer as it is on stdout, with key values masked. Read the field you need from its place:
-  - A list answers a page: `{"data":[…],"page":1,"limit":20,"total":42}`. The rows are in `data`. This is
-    true for every `list` verb, and for list verbs with another name, such as `sessions list-items`.
-  - `get`, `update` and most `create` verbs answer the resource itself: `{"id":"…",…}`.
-  - Some verbs wrap the resource with what came with it. `sessions start` answers
-    `{"session":{…},"firstItem":{…}}`, so the session id is `.session.id`. `sessions append-item` answers
-    `{"item":{…},"turnState":"…"}`, and `sessions interrupt` answers `{"session":{…},"withdrawnItems":[…]}`.
+The full list of commands and flags is the CLI's own help: `orchestra --help`, `orchestra <noun> --help` and
+`orchestra <noun> <verb> --help`. The kit's reference, `docs/REFERENCE.md` in the installed package, explains
+each part at length. What follows is only what a reader needs to run a command safely.
+
+- **Nouns and verbs.** `orchestra <noun> <verb>`. Nouns match the API's paths, such as `agents`, `work-items`
+  and `sessions`. The usual verbs are `list`, `get`, `create`, `update` and `delete`; a command keeps its own
+  verb, such as `work-items assign`. `orchestra sessions wait <session id>` waits for a turn to end.
+- **Output.** `--output json` prints the API's answer as it is on stdout, with key values masked. Read the field
+  you need from its place:
+  - A list answers a page: `{"data":[…],"page":1,"limit":20,"total":42}`. The rows are in `data`.
+  - `get`, `update` and most `create` verbs answer the resource itself.
+  - `sessions start` answers `{"session":{…},"firstItem":{…}}`, so the session id is `.session.id`.
   - A create that shows a key once answers the resource beside the key, such as `gateway-keys create`,
-    `{"gatewayKey":{…},"token":"…"}`. `files create` answers `{"file":{…},"upload":{…}}`.
-  - `orchestra sessions wait` prints the session itself, as `sessions get` does. A delete prints `null`.
+    `{"gatewayKey":{…},"token":"…"}`.
   - An error prints `{"status":404,"message":"…"}` on stderr, and the command exits non-zero.
-- **Input.** `--body @file.json` sends a full request body. `--file <path>` uploads bytes on `files create`.
-- **Values.** Key values in answers print masked.
-- **Approval.** A platform command asks first only for key values and access changes.
-  `--require-approval never` skips the question, only after the person approved.
-- **Sign-in.** `orchestra auth login --org <organization>` signs in through the browser and saves a *profile* in
-  `~/.config/orchestra/config.json`. `--no-browser` asks for an API token at a hidden prompt instead. `--profile
-  <name>` picks another saved profile. It signs in to `https://api.orchestraworks.ai` unless `ORCHESTRA_BASE_URL`
-  or `--base-url` says otherwise. The browser sign-in renews itself. A token typed at the `--no-browser`
-  prompt cannot renew itself, so it suits a short run only.
-- **Who am I.** `orchestra me get` shows the signed-in user, and `orchestra organizations list` the organization.
+- **Approval.** A platform command asks first only for key values and access changes. `--require-approval
+  never` skips the question, only after the person approved.
+- **Sign-in.** `orchestra auth login` signs in through the browser and saves a *profile* in
+  `~/.config/orchestra/config.json`. It selects the person's organization when they have one; with several,
+  name it: `orchestra auth login --org <organization>`. The browser sign-in renews itself. A token typed at the
+  `--no-browser` prompt cannot renew itself, so it suits a short run only.
 - **Scripts.** `ORCHESTRA_API_TOKEN` and `ORCHESTRA_BASE_URL` in the shell are used before the profile. On an
   Orchestra machine, the network edge signs the agent's calls, so it needs no token.
 - **Fallback.** `orchestra api <METHOD> </path>` makes a raw call when a typed command is missing.
@@ -530,17 +530,31 @@ orchestra api GET /agents
 
 ## 17. Connections
 
-<!-- Sources, on develop at 19459f9ebb: cli/src/generated/providers.json (bitbucket, jira, jira-classic);
-docs/architecture/integrations.md:240, 275. -->
+<!-- Sources, on develop at 0ddbb8568d: cli/src/generated/providers.json (fourteen providers and their authModes);
+docs/architecture/integrations.md:240, 275; cli/docs/REFERENCE.md section 7, "Connections, triggers, and
+workflows", "Bring your own OAuth app", "Per-user OAuth grants" and "Chat presence". -->
 
 A *connection* is an app the customer approves in the browser, instead of a personal token. It brings provider
-events to the platform and can add its credential at the network edge.
+events to the platform and can add its credential at the network edge. These providers have one:
 
-- Bitbucket: the connection type exists, with OAuth, a stored token, or a webhook secret, and it receives every
-  Bitbucket webhook event. Cannot yet: OAuth needs an OAuth consumer the organization registers first. Cannot
-  yet: git over `bitbucket.org` through the connection; it adds its credential only on `api.bitbucket.org`, so
-  git still needs the token rule.
-- Jira: a Jira Cloud app connection and a classic Jira connection exist, with issue events.
+| Provider | Kind | How it signs in |
+|---|---|---|
+| GitHub | Code | GitHub App |
+| GitLab, Bitbucket | Code | OAuth, a stored token, or a webhook secret |
+| Azure DevOps | Code | OAuth or a stored token |
+| Jira | Tracker | Jira Cloud app |
+| Jira (classic), Linear | Tracker | OAuth, a stored token, or a webhook secret |
+| Zendesk, Intercom | Customer support | OAuth, a stored token, or a webhook secret |
+| Notion, Guru | Knowledge | OAuth, a stored token, or a webhook secret |
+| Slack, Microsoft Teams | Chat | OAuth |
+| Generic webhook | Any sender | A webhook secret |
+
+How to declare one, its events and its network rules, the team's own OAuth app, per-person grants and chat:
+the kit's reference, `docs/REFERENCE.md`, section 7, "Connections, triggers, and workflows".
+
+- Cannot yet: Bitbucket OAuth without an OAuth consumer the organization registers first.
+- Cannot yet: git over `bitbucket.org` through the Bitbucket connection. It adds its credential only on
+  `api.bitbucket.org`, so git still needs the token rule.
 - In the starter: none. For the first run, personal tokens are enough. Connections and listeners come later.
 
 ## 18. The team's own machines and network
@@ -594,8 +608,9 @@ What an agent knows lives in one of five places. Put each thing in its place.
 
 - **Agent instructions.** The agent's role, its limits, when to ask a person, and how to report. Change them
   rarely. Each change makes a new agent version.
-- **Platform skills.** Ours, the same for every customer: how to work on the Orchestra platform. They are
-  attached to every agent. The customer's agents never edit them.
+- **Platform skills.** Ours, the same for every customer, such as how to work on the Orchestra platform. An
+  agent uses one only when its skills list names it by id (section 13). The customer's agents never edit
+  them.
 - **Codebase skills.** How this codebase builds, tests and is reviewed. They live in the customer's repository,
   in `AGENTS.md` and `.agents/skills/`, change with the code, and are reviewed by their team. During a pilot they
   start as a skill in Orchestra, and the Manager Agent hands them over as a pull request.