@orchestraworks/cli 0.5.1 → 0.5.3

package/skills/orchestra-fdk/references/integrations/analytics.md

@@ -0,0 +1,18 @@
+# Analytics
+
+The agents read product usage to judge a change, or pull it into the platform's custom metrics. A pull that
+needs no judgment fits a `script` agent on a schedule (orchestra skill, section 2). Give access with a Secret
+the network edge adds, with read scopes only. Egress is open, so add only the rule that adds the credential.
+The agent installs or uses whatever client it prefers. The edge adds the credential to its requests.
+
+Phase 3, "From a recipe to code", turns a recipe into a Secret and a rule.
+
+| Provider | Access | Scopes | Check command |
+|---|---|---|---|
+| Pendo | `app.pendo.io → x-pendo-integration-key: <SECRET>`. The EU region is `app.eu.pendo.io` | A read-only integration key | `curl -fsS https://app.pendo.io/api/v1/page -H 'Content-Type: application/json'` (check the vendor page) |
+| Mixpanel | `mixpanel.com → Authorization: Basic <service account user>:<SECRET>` | A service account with the Consumer role | `curl -fsS "https://mixpanel.com/api/app/me"` (check the vendor page) |
+| Amplitude | `amplitude.com → Authorization: Basic <api key>:<SECRET>`, with the secret key as the Secret | The project's API key and secret key | `curl -fsS "https://amplitude.com/api/2/events/list"` (check the vendor page) |
+| Google Analytics | Not released yet: its Data API takes short-lived OAuth tokens | The Viewer role, when it is released | Not released yet |
+
+Token pages: Pendo **Settings › Integrations › Integration Keys**; Mixpanel **Organization Settings ›
+Service Accounts**; Amplitude **Settings › Projects**.

package/skills/orchestra-fdk/references/integrations/ci-cd.md

@@ -0,0 +1,20 @@
+# CI and CD
+
+The agents read build results and logs to find why a check failed. Give access with a Secret the network edge
+adds, or reuse the code host's access where the CI lives on the code host. Egress is open, so add only the
+rule that adds the credential. Read access is enough for most work. The agent installs or uses whatever
+client it prefers. The edge adds the credential to its requests.
+
+Phase 3, "From a recipe to code", turns a recipe into a Secret and a rule.
+
+| Provider | Access | Scopes | Check command |
+|---|---|---|---|
+| GitHub Actions | The GitHub access of `code-repo.md`. A GitHub App connection adds `actions:read` to `install.permissions` | Actions: read | `curl -fsS "https://api.github.com/repos/<owner>/<name>/actions/runs?per_page=1"` |
+| Azure Pipelines | The Azure DevOps access of `code-repo.md` | Build (Read) | `curl -fsS "https://dev.azure.com/<organization>/<project>/_apis/build/builds?api-version=7.1&\$top=1"` |
+| Jenkins | `<jenkins host> → Authorization: Basic <user>:<SECRET>`, with the user's API token | A user with read access to the jobs | `curl -fsS https://<jenkins host>/api/json` |
+| CircleCI | `circleci.com → Circle-Token: <SECRET>` | Personal API token | `curl -fsS https://circleci.com/api/v2/me` |
+
+Token pages: Jenkins, the user's **Configure › API Token**; CircleCI **User Settings › Personal API Tokens**.
+
+A Jenkins server inside the team's network is not on the internet. Hosted machines cannot reach it.
+`../environment.md`, section 5, part C, says where the machines can run instead.

package/skills/orchestra-fdk/references/integrations/cloud.md

@@ -0,0 +1,19 @@
+# Cloud accounts
+
+Cloud access is read-only: the agents read resources, logs and settings, and change nothing. The network
+edge adds a credential as a header. The three cloud APIs below do not take a fixed key in a header: AWS signs
+each request with its key, and Azure and Google Cloud take short-lived tokens. So the edge cannot add their
+credentials today, and none of them is released yet. Egress is open, so a public endpoint is reachable with
+no key.
+
+Never put a cloud key in an env value, the setup script or the agent's instructions to work around this.
+Every process on the machine reads them.
+
+| Provider | Access | Scopes | Check command |
+|---|---|---|---|
+| AWS | Not released yet: each request is signed with the key | A read-only role, such as `ReadOnlyAccess`, when it is released | Not released yet |
+| Azure | Not released yet: Entra tokens expire within hours | The Reader role, when it is released | Not released yet |
+| Google Cloud | Not released yet: OAuth tokens expire within an hour | The Viewer role, when it is released | Not released yet |
+
+Until it is released, the agent asks a person in the item for what it needs from the cloud, such as a log
+excerpt.

package/skills/orchestra-fdk/references/integrations/code-repo.md

@@ -0,0 +1,76 @@
+# Code hosts
+
+Give access with a Secret the network edge adds, or with the provider's platform connection. Egress is open,
+so add only the rule that adds the credential. Git over HTTPS and the REST API often take the token in
+different forms: give each its own rule, scoped by host or by path. A connection also brings events, which
+a `Trigger` turns into work. The agent installs or uses whatever git or API client it prefers. The edge adds
+the credential to its requests.
+
+Phase 3, "From a recipe to code", turns a recipe into a Secret and a rule.
+
+| Provider | Access | Scopes | Check command |
+|---|---|---|---|
+| GitHub | Platform connection `github` (the Orchestra GitHub App), with `.applyPreset(github.egressPolicy())`. Or a token: `api.github.com → Authorization: Bearer <SECRET>` and `github.com → Authorization: Basic x-access-token:<SECRET>` | Fine-grained token for the repository: Contents, Pull requests and Issues, read and write | `curl -fsS https://api.github.com/repos/<owner>/<name>` |
+| Bitbucket Cloud | `api.bitbucket.org → Authorization: Bearer <SECRET>` and `bitbucket.org → Authorization: Basic x-bitbucket-api-token-auth:<SECRET>`. Platform connection `bitbucket` for events | API token with the repository and pull request read and write scopes | `curl -fsS https://api.bitbucket.org/2.0/repositories/<workspace>/<repository>` |
+| GitLab | `gitlab.com`, paths `/api/*`, priority 310 → `PRIVATE-TOKEN: <SECRET>`, and `gitlab.com`, priority 300 → `Authorization: Basic oauth2:<SECRET>`. Platform connection `gitlab` for events | Personal or project access token with `api` | `curl -fsS https://gitlab.com/api/v4/projects/<url-encoded group/project>` |
+| Azure DevOps | `dev.azure.com → Authorization: Basic pat:<SECRET>`, for the API and git. Platform connection `azure-devops` for events | Personal access token: Code (Read & write), and Work Items (Read & write) for Boards | `curl -fsS "https://dev.azure.com/<organization>/_apis/projects?api-version=7.1"` |
+
+Token pages: GitHub `https://github.com/settings/personal-access-tokens`; Bitbucket
+`https://id.atlassian.com/manage-profile/security/api-tokens`; GitLab **Settings › Access tokens** in the
+project or the profile; Azure DevOps **User settings › Personal access tokens**.
+
+## Git over HTTPS
+
+Git sends Basic auth. The edge adds it, so the agent clones `https://<host>/<path>.git` with no user name
+and no password in the address.
+
+- **GitHub:** the user name is `x-access-token`, and the password is the token:
+  `SecretValue.basicAuth("x-access-token", SecretValue.fromEnv("ORCHESTRA_FDK_GITHUB_TOKEN"))`. The GitHub
+  App connection's preset adds git on `github.com` and `codeload.github.com` itself. Its `{ git: "read" }`
+  option gives clone and fetch, and no push.
+- **Bitbucket:** the fixed user name `x-bitbucket-api-token-auth`. The Bitbucket connection adds its key on
+  `api.bitbucket.org` only, so git keeps this rule beside the connection.
+- **GitLab:** the user name `oauth2`. The GitLab connection declares no git transport, so git keeps this
+  rule beside the connection.
+- **Azure DevOps:** the user name is not checked, and the kit refuses an empty one, so use `pat`. One rule on
+  `dev.azure.com` serves the API and git.
+
+## GitLab: two rules on one host
+
+The API and git are both on `gitlab.com`. Two credentialed rules on one host at one priority are a tie, and
+the first declared wins for every request. So scope the API rule to `paths: ["/api/*"]` and give it the higher
+priority, 310. The git rule at 300 takes the rest of the host.
+
+The API rule replaces the `PRIVATE-TOKEN` header. A project access token must be sent this way: sent as
+`Authorization: Bearer` beside a placeholder `PRIVATE-TOKEN`, GitLab answers 401. A personal token works the
+same way.
+
+With the `gitlab` connection and `Auth.oauth()`, use `.allow(gitlab, { paths: ["/api/*"], priority: 310 })`
+for the API instead, and keep the git rule. GitLab does not let the platform register the webhook. The
+developer adds it in the project, under **Settings › Webhooks**, with the connection's address. Write the
+address to a file the developer can read, and never print it:
+`npx orchestra connections rotate-webhook-token gitlab --output-file <path>`. Each run makes a new address and
+ends the old one. The platform's GitLab connection covers `gitlab.com` only.
+
+## Connections and events
+
+- **GitHub:** `Auth.githubApp()`. `install.permissions` adds to the default the platform gives
+  (`contents:read`, `metadata:read`, `pull_requests:write`), as `<permission>:<level>`, such as
+  `contents:write`. The apply prints an install link once. Give it to the developer only after they approved
+  the diff, and run the same apply again when the app is installed. Events: `PullRequest`, `Issues`,
+  `IssueComment`.
+- **Bitbucket:** `Auth.customerManagedToken(<secret>)`, or `Auth.oauth()` once the organization registers
+  its own Bitbucket OAuth consumer. Install fields `workspace` and `repository`. The platform registers the
+  webhook. Run `orchestra connections list-event-types <connection>` for the events.
+- **GitLab:** install field `projectPath` or `projectId`. Events: `Push`, `MergeRequestOpened`,
+  `MergeRequestUpdated`, `IssueOpened`, `IssueUpdated`, `NoteCreated`.
+- **Azure DevOps:** `Auth.oauth()`: a Microsoft work account consents. Install fields `organization` and
+  `project`. `.allow(<connection>)` adds the key on `dev.azure.com` for the API. Git keeps the token rule,
+  scoped to `paths: ["*/info/refs", "*/git-upload-pack", "*/git-receive-pack"]` at priority 310, so the two
+  rules do not tie on one host. A path pattern that starts with `*` matches the end of the path only, so
+  a `*` in the middle of a pattern matches nothing. To allow clone and fetch without push, add
+  `.deny("azure-devops-no-push", { hosts: ["dev.azure.com"], paths: ["*/git-receive-pack"] })`. A deny at its
+  default priority, 900, wins over both rules. Leaving `*/git-receive-pack` out of the git rule does not stop
+  a push, because the connection's rule covers every path on the host. Or use a read-only token.
+  The platform registers the webhooks. The events fire for every repository in the project, so narrow a
+  trigger with `where`.

package/skills/orchestra-fdk/references/integrations/databases.md

@@ -0,0 +1,22 @@
+# Databases
+
+Use a staging database or a read replica only, through a read-only user. Never give the agents a production
+database, and never a user that can write to production.
+
+The network edge adds a credential to HTTPS requests only. A database's own protocol, such as PostgreSQL's,
+carries the password inside its connection, where the edge cannot add it. A database reached over an HTTPS
+API can take a Secret like any other service. Egress is open. The agent installs or uses whatever client it
+prefers.
+
+Phase 3, "From a recipe to code", turns a recipe into a Secret and a rule.
+
+| Provider | Access | Scopes | Check command |
+|---|---|---|---|
+| PostgreSQL, MySQL, SQL Server (their own protocol) | Not released yet: the password would sit on the machine | A read-only user on staging or a replica, when it is released | Not released yet |
+| Supabase (a staging project) | `<project ref>.supabase.co → apikey: <SECRET>` and `Authorization: Bearer <SECRET>`, one Secret on two headers | The project's `anon` key, with row-level security on (check the vendor page) | `curl -fsS "https://<project ref>.supabase.co/rest/v1/<table>?limit=1"` |
+
+For local work, the codebase's own local database, such as one from its compose file, needs no access: the
+agent starts it on its machine (`../environment.md`).
+
+Never put a database password in an env value, the setup script or the agent's instructions. Every process
+on the machine reads them.

package/skills/orchestra-fdk/references/integrations/dependencies.md

@@ -0,0 +1,29 @@
+# Package registries
+
+Public registries need no access: egress is open. A private registry or feed needs a Secret the network edge
+adds on the registry's host. Point the package manager at the registry's address with no user name and no
+token in it: in `.npmrc`, `nuget.config`, `pip.conf` or an env value. The edge adds the credential. The agent
+installs or uses whatever client it prefers.
+
+Phase 3, "From a recipe to code", turns a recipe into a Secret and a rule.
+
+| Provider | Access | Scopes | Check command |
+|---|---|---|---|
+| npm, private registry (GitHub Packages, JFrog, Nexus) | `<registry host> → Authorization: Bearer <SECRET>` | Read packages | `curl -fsS https://<registry host>/<package name>` |
+| PyPI, private index (JFrog, Nexus) | `<index host> → Authorization: Basic <user>:<SECRET>`. Ask which user name the index wants | Read packages | `curl -fsS https://<index host>/simple/<package name>/` |
+| NuGet, Azure Artifacts | `pkgs.dev.azure.com → Authorization: Basic pat:<SECRET>` | Packaging (Read) | `curl -fsS "https://pkgs.dev.azure.com/<organization>/_packaging/<feed>/nuget/v3/index.json"` |
+| NuGet, GitHub Packages | `nuget.pkg.github.com → Authorization: Basic <user>:<SECRET>` | `read:packages` | `curl -fsS https://nuget.pkg.github.com/<owner>/index.json` |
+| Maven or Gradle, private repository | `<repository host> → Authorization: Basic <user>:<SECRET>` (check the vendor page) | Read packages | `curl -fsS https://<repository host>/<path to a known artifact>.pom` |
+
+The public registries, such as `registry.npmjs.org`, `pypi.org`, `files.pythonhosted.org` and
+`api.nuget.org`, need no rule.
+
+## Never write the token on the machine
+
+Never write the token into `.npmrc`, `pip.conf`, `nuget.config`, an env value or the setup script. Every
+process on the machine reads them, and the setup script's output is kept. Keep the codebase's own file when it
+holds the address only, for example:
+
+```
+@<scope>:registry=https://<registry host>/
+```

package/skills/orchestra-fdk/references/integrations/design.md

@@ -0,0 +1,18 @@
+# Design
+
+The agents read design files to build what the designer drew. Give access with a Secret the network edge adds,
+with read scopes only. Egress is open, so add only the rule that adds the credential. The platform has no
+design connection, so no design events reach the platform. The agent installs or uses whatever client it
+prefers. The edge adds the credential to its requests.
+
+Phase 3, "From a recipe to code", turns a recipe into a Secret and a rule.
+
+| Provider | Access | Scopes | Check command |
+|---|---|---|---|
+| Figma | `api.figma.com → X-Figma-Token: <SECRET>` | A personal access token with `file_content:read` | `curl -fsS "https://api.figma.com/v1/files/<file key>?depth=1"` |
+
+Token page: Figma **Settings › Security › Personal access tokens**.
+
+The file key is the part after `/design/` or `/file/` in the file's address.
+
+The token sees every file its user can open. Make it for a user who sees only the team's files.

package/skills/orchestra-fdk/references/integrations/feature-flags.md

@@ -0,0 +1,19 @@
+# Feature flags
+
+The agents read flag settings to see what each user gets, and turn a flag on only in a test environment.
+Give access with a Secret the network edge adds, with read scopes, or write only on non-production
+environments. Egress is open, so add only the rule that adds the credential. The agent installs or uses
+whatever client it prefers. The edge adds the credential to its requests.
+
+Phase 3, "From a recipe to code", turns a recipe into a Secret and a rule.
+
+| Provider | Access | Scopes | Check command |
+|---|---|---|---|
+| LaunchDarkly | `app.launchdarkly.com → Authorization: <SECRET>`, with no `Bearer` | An API access token with the Reader role | `curl -fsS https://app.launchdarkly.com/api/v2/projects` |
+| Split | `api.split.io → Authorization: Bearer <SECRET>` | An Admin API key scoped to the test environments (check the vendor page) | `curl -fsS https://api.split.io/internal/api/v2/workspaces` |
+| Unleash | `<unleash host> → Authorization: <SECRET>`, with no `Bearer` | A personal or service account token with read access | `curl -fsS https://<unleash host>/api/admin/projects` |
+| ConfigCat | `api.configcat.com → Authorization: Basic <user>:<SECRET>` | Public API credentials | `curl -fsS https://api.configcat.com/v1/me` |
+| Azure App Configuration | Not released yet: each request is signed with the key, or takes a short-lived Entra token | The App Configuration Data Reader role, when it is released | Not released yet |
+
+Token pages: LaunchDarkly **Organization settings › Authorization**; Split **Admin settings › API keys**;
+Unleash **Admin › API access**; ConfigCat **Public API credentials**.

package/skills/orchestra-fdk/references/integrations/incident.md

@@ -0,0 +1,29 @@
+# Incidents
+
+The agents read incidents and their timelines to find what broke. Give access with a Secret the network edge
+adds, with read scopes only. Egress is open, so add only the rule that adds the credential. The platform has
+no incident connection, so no incident events reach the platform. The agent installs or uses whatever client
+it prefers. The edge adds the credential to its requests.
+
+Phase 3, "From a recipe to code", turns a recipe into a Secret and a rule.
+
+| Provider | Access | Scopes | Check command |
+|---|---|---|---|
+| PagerDuty | `api.pagerduty.com → Authorization: Token token=<SECRET>` | A read-only REST API key | `curl -fsS https://api.pagerduty.com/abilities -H 'Accept: application/vnd.pagerduty+json;version=2'` |
+| Opsgenie | `api.opsgenie.com → Authorization: GenieKey <SECRET>`. The EU region is `api.eu.opsgenie.com` | An API key with Read access | `curl -fsS https://api.opsgenie.com/v2/account` |
+
+Token pages: PagerDuty **Integrations › API Access Keys**; Opsgenie **Settings › API key management**.
+
+## A header with its own word
+
+Both put a word of their own before the key, so neither is `Bearer` nor `Basic`. Bind them with `inject`:
+
+```ts
+.allow("pagerduty", {
+  hosts: ["api.pagerduty.com"],
+  priority: 300,
+  credential: inject(pagerduty, { headers: [{ name: "authorization", value: "Token token=${secret}" }] }),
+})
+```
+
+For Opsgenie, the value is `GenieKey ${secret}`.

package/skills/orchestra-fdk/references/integrations/issue-tracker.md

@@ -0,0 +1,65 @@
+# Trackers
+
+Give access with a Secret the network edge adds, or with the tracker's platform connection. Egress is open,
+so add only the rule that adds the credential. A connection also brings events: a `Trigger` on them makes a
+work item for each new issue. The agent installs or uses whatever client it prefers. The edge adds the
+credential to its requests.
+
+Phase 3, "From a recipe to code", turns a recipe into a Secret and a rule.
+
+| Provider | Access | Scopes | Check command |
+|---|---|---|---|
+| Jira Cloud, API token | `<site>.atlassian.net → Authorization: Basic <email>:<SECRET>` | API token without scopes | `curl -fsS https://<site>.atlassian.net/rest/api/3/myself` |
+| Jira Cloud, `jira` | Platform connection `jira` (the Orchestra app for Jira), with `.applyPreset(jira.egressPolicy())` | Set by the app | `curl -fsS https://api.atlassian.com/ex/jira/<cloudId>/rest/api/3/myself` |
+| Jira Cloud, `jira-classic` | Platform connection `jira-classic`, with `.allow(jiraClassic)` on `api.atlassian.com` | Set by the consent | `curl -fsS https://api.atlassian.com/ex/jira/<cloudId>/rest/api/3/myself` |
+| Linear | `api.linear.app → Authorization: <SECRET>`, with no `Bearer`. Or platform connection `linear` | Personal API key | `curl -fsS https://api.linear.app/graphql -H 'Content-Type: application/json' -d '{"query":"{ viewer { id } }"}'` |
+| GitHub Issues | The GitHub access of `code-repo.md`, with Issues read and write | Issues: read and write | `curl -fsS "https://api.github.com/repos/<owner>/<name>/issues?per_page=1"` |
+| Azure Boards | The Azure DevOps access of `code-repo.md` | Work Items (Read & write) | `curl -fsS "https://dev.azure.com/<organization>/<project>/_apis/wit/workitems?ids=<id>&api-version=7.1"` |
+
+Token pages: Jira `https://id.atlassian.com/manage-profile/security/api-tokens`; Linear **Settings › Account ›
+Security & access**.
+
+## Jira: three routes
+
+- **API token.** Basic auth over the account email and the token: `SecretValue.basicAuth("<email>",
+  SecretValue.fromEnv("<VAR>"))`. Make the token without scopes: a token with scopes
+  works only through `api.atlassian.com`, and this rule adds it on the site host. The site host, such as
+  `acme.atlassian.net`, is an env value or a constant in the code. No events.
+- **`jira`, the Orchestra app for Jira.** `Auth.forgeApp()`, install field `siteUrl`. A Jira admin installs
+  the app from the connection's `auth.authorizationUrl` (`npx orchestra connections get jira --output json`).
+  The connection turns `ACTIVE` at the first event from the site. The app's key works only on
+  `api.atlassian.com`. Grant it with `.applyPreset(jira.egressPolicy())`: the preset adds the key on
+  `api.atlassian.com` only, and opens the site host with no key. A plain `.allow(jira)` would add the key on
+  both. Events: `CreatedIssue`, `UpdatedIssue`, `DeletedIssue`, `CommentedIssue`. The field `selfGenerated`
+  is true on a change the app made: filter it out with `where`.
+- **`jira-classic`.** Install field `projectKey`. `Auth.oauth()`: the apply prints no link for it. Read
+  `auth.authorizationUrl` from `npx orchestra connections get <slug> --output json`, the developer consents,
+  and you apply again. The platform registers the webhook. Grant the key with
+  `.allow(jiraClassic)`, which adds it on `api.atlassian.com`. Events: `IssueCreated`, `IssueUpdated`,
+  `IssueDeleted`, `CommentCreated`.
+
+A connection keeps its credential apart from the network rules. Without the grant on an environment, the
+agents on it reach Jira with no key.
+
+## GitHub Issues: one item per issue
+
+A trigger that makes one work item per issue keys it with a `binding`. Issue numbers repeat across
+repositories, so key on GitHub's global issue id, or put the repository in the key:
+
+```ts
+binding: binding`${context.connection.slug}:${context.event.payload("repository.full_name")}:${context.event.payload("issue.number")}`
+```
+
+A comment on a pull request also arrives as `IssueComment`: filter it out with
+`field("issue.pull_request").isAbsent()`.
+
+## Linear
+
+The key goes bare in the `Authorization` header: `header("Authorization", secret)`. With the `linear`
+connection, `Auth.customerManagedToken(<secret>)` or `Auth.oauth()`, and `.allow(linear)` adds its key. The
+platform registers the webhook. Events: `IssueCreate`, `IssueUpdate`, `IssueRemove`, `CommentCreate`.
+
+## Azure Boards
+
+A work item comment arrives as `WorkitemUpdated`, with its text at
+`resource.fields["System.History"].newValue`. There is no separate comment event.

package/skills/orchestra-fdk/references/integrations/knowledge-base.md

@@ -0,0 +1,43 @@
+# Knowledge bases
+
+Give access with a Secret the network edge adds, or with the provider's platform connection. Egress is open,
+so add only the rule that adds the credential. The agent installs or uses whatever client it prefers. The
+edge adds the credential to its requests.
+
+Phase 3, "From a recipe to code", turns a recipe into a Secret and a rule.
+
+| Provider | Access | Scopes | Check command |
+|---|---|---|---|
+| Notion | `api.notion.com → Authorization: Bearer <SECRET>`. Or platform connection `notion`, with `.allow(notion)` | An internal integration, shared with each page or database the agents need | `curl -fsS https://api.notion.com/v1/users/me -H 'Notion-Version: 2022-06-28'` |
+| Confluence Cloud | `<site>.atlassian.net → Authorization: Basic <email>:<SECRET>` | API token without scopes | `curl -fsS "https://<site>.atlassian.net/wiki/api/v2/spaces?limit=1"` |
+| Guru | `api.getguru.com → Authorization: Basic <email>:<SECRET>`. Or platform connection `guru` (OAuth, read only), with `.allow(guru)` | User API token | `curl -fsS https://api.getguru.com/api/v1/whoami` (check the vendor page) |
+
+Token pages: Notion `https://www.notion.so/profile/integrations`; Confluence
+`https://id.atlassian.com/manage-profile/security/api-tokens`; Guru, the user's API tokens in Guru's
+settings.
+
+## Notion
+
+The integration sees only the pages and databases the developer shares with it in Notion. Each Notion API
+call also needs a `Notion-Version` header, which the agent's client sends itself.
+
+The `notion` connection takes `Auth.customerManagedToken(<secret>)` or `Auth.oauth()`, install fields
+`workspaceId` and `workspaceUrl`, both optional. Its events are `PageCreated` and `PageContentUpdated`.
+The platform does not register the webhook. The developer adds it by hand in the integration's settings in
+Notion, with the connection's address. Write the address to a file the developer can read, and never print
+it: `npx orchestra connections rotate-webhook-token notion --output-file <path>`. Each run makes a new
+address and ends the old one.
+
+## Confluence
+
+Basic auth over the account email and the token, on the site host. Make the token without scopes, for the
+same reason as Jira's (`issue-tracker.md`). When the team uses a Jira API token on the same site with the
+same account, reuse that Secret and its rule: one rule on the site host serves both. The platform has no
+Confluence connection, so Confluence sends no events.
+
+## Guru
+
+The `guru` connection asks Guru for read access with `Auth.oauth()`. The apply prints no link for it: read
+`auth.authorizationUrl` from `npx orchestra connections get <slug> --output json`, the developer consents, and
+you apply again. The platform registers the webhook. Events: `CardCreated`,
+`CardUpdated`, `CardDeleted`.

package/skills/orchestra-fdk/references/integrations/messaging.md

@@ -0,0 +1,38 @@
+# Chat
+
+Slack and Microsoft Teams take no personal token here. Access is the platform connection only: the developer
+or a tenant admin approves the app in the browser, and the network edge adds the app's key to the agent's
+replies. Egress is open, so the connection's own rule, `.allow(<connection>)`, is the only rule to add. The
+agent installs or uses whatever client it prefers. The edge adds the key to its requests.
+
+| Provider | Access | Scopes | Check command |
+|---|---|---|---|
+| Slack | Platform connection `slack` (the Orchestra Slack app), `Auth.oauth()`, with `.allow(slack)` on `slack.com` | Set by the app | `curl -sS -X POST https://slack.com/api/auth.test`. Passes only when the answer holds `"ok":true`: Slack answers `200` with `"ok":false` when no key was added |
+| Microsoft Teams | Platform connection `teams` (the Orchestra bot), `Auth.oauth()`, with `.allow(teams)` | Set by the app; a tenant admin consents | The agent sends one message with its own choice of tool, on a conversation where the bot has seen a message. Passes only when the answer carries the new message's `id` and the message shows in Teams |
+
+## OAuth only
+
+Both apps sign in with OAuth, and the platform fills the install fields, so `install` stays empty. The apply
+prints `connection '<slug>' needs attention — authorize at: <link>`. For Slack, the developer opens it and
+adds the app to the workspace. For Teams, the consent is for the whole Microsoft tenant, so a tenant admin
+must open it. Then run the same apply again.
+
+Without `.allow(<connection>)` on the agent's environment, a reply is refused at the network edge, and synth
+prints a warning.
+
+## Conversations
+
+`Providers.Slack.conversation` and `Providers.Teams.conversation` give the events and the bindings for a
+trigger that starts or wakes an agent's conversation: Slack's `mention`, `dm`, `groupChat` and `threadReply`;
+Teams' `message`, split by `inChannel()`, `inDirectMessage()` and `inGroupChat()`. Both have
+`sessionPerThread()`, `sessionPerConversation()` and `rooms([...])`. Set `attributeConnection: true` on the
+trigger's agent target. `autoRespond` on the connection sets what the app shows on each message: Slack takes
+a reaction, a typing status and a failure notice; Teams takes `typing` and `failureNotice`.
+
+The agent replies through the provider's own API: Slack's Web API on `slack.com`, and the Bot Framework for
+Teams. On Teams, the edge adds the bot's key only for a conversation where the bot has already seen a
+message.
+
+**Not built yet:** acting as the person who wrote the message (the agent speaks as the app), starting a Teams
+conversation where the bot has not been seen, and dropping the app's own messages before the agent sees
+them.

package/skills/orchestra-fdk/references/integrations/observability.md

@@ -0,0 +1,36 @@
+# Observability
+
+The agents read errors, traces and metrics to find the cause of a bug. Give access with a Secret the network
+edge adds, with read scopes only. Egress is open, so add only the rule that adds the credential. None of these
+has a platform connection, so none sends events to the platform. The agent installs or uses whatever client
+it prefers. The edge adds the credential to its requests.
+
+Phase 3, "From a recipe to code", turns a recipe into a Secret and a rule.
+
+| Provider | Access | Scopes | Check command |
+|---|---|---|---|
+| Sentry | `sentry.io → Authorization: Bearer <SECRET>`. The EU region is `de.sentry.io`; a self-hosted Sentry uses its own host | `project:read`, `event:read` | `curl -fsS https://sentry.io/api/0/organizations/` |
+| Datadog | `api.datadoghq.com → DD-API-KEY: <SECRET>` and `DD-APPLICATION-KEY: <SECRET>`, two Secrets on one rule. Other sites use their own host, such as `api.datadoghq.eu` | An application key with read scopes | `curl -fsS https://api.datadoghq.com/api/v1/validate` |
+| New Relic | `api.newrelic.com → API-Key: <SECRET>`. The EU region is `api.eu.newrelic.com` | A user key | `curl -fsS https://api.newrelic.com/graphql -H 'Content-Type: application/json' -d '{"query":"{ actor { user { email } } }"}'` |
+| Grafana Cloud | `<stack>.grafana.net → Authorization: Bearer <SECRET>` | A service account token with the Viewer role | `curl -fsS "https://<stack>.grafana.net/api/search?limit=1"` |
+| Application Insights | `api.applicationinsights.io → x-api-key: <SECRET>` (check the vendor page: Microsoft is moving this API to Entra sign-in) | Read telemetry | `curl -fsS "https://api.applicationinsights.io/v1/apps/<app id>/metadata"` |
+| CloudWatch | Not released yet. AWS signs each request with its key, so the edge cannot add it as a header | Not released yet | Not released yet |
+
+Token pages: Sentry **Settings › Auth Tokens**; Datadog **Organization Settings › API Keys** and
+**Application Keys**; New Relic **API keys**; Grafana **Administration › Service accounts**.
+
+## Datadog: two headers
+
+Datadog wants two keys on each API call: the organization's API key and a user's application key. Store each
+as its own Secret, and add both on one rule:
+
+```ts
+.allow("datadog", {
+  hosts: ["api.datadoghq.com"],
+  priority: 300,
+  credentials: [header("DD-API-KEY", datadogApiKey), header("DD-APPLICATION-KEY", datadogAppKey)],
+})
+```
+
+The application key carries the user's rights. Make it for a user, or a service account, with read access
+only.

package/skills/orchestra-fdk/references/integrations/secrets-managers.md

@@ -0,0 +1,25 @@
+# Secrets managers
+
+A secrets manager is a source for the factory's Secrets, not a service the agents call. The developer reads
+each token from the manager into the shell of the apply, on their own computer. The apply stores it as an
+Orchestra Secret, and the network edge adds it. The value is never printed, never in the chat, and never on
+a machine.
+
+| Provider | Access | Scopes | Check command |
+|---|---|---|---|
+| 1Password | On the developer's computer: `ORCHESTRA_FDK_<NAME>_TOKEN=$(op read "op://<vault>/<item>/<field>")` in the apply's shell | Read on the vault | `op whoami` |
+| HashiCorp Vault | On the developer's computer: `ORCHESTRA_FDK_<NAME>_TOKEN=$(vault kv get -field=<field> <path>)` in the apply's shell | A policy with `read` on the path | `vault token lookup` |
+| Azure Key Vault | On the developer's computer: `ORCHESTRA_FDK_<NAME>_TOKEN=$(az keyvault secret show --vault-name <vault> --name <name> --query value -o tsv)` in the apply's shell | The Key Vault Secrets User role | `az account show` |
+
+The check commands run on the developer's computer, with their own sign-in to the manager.
+
+## How the value travels
+
+1. The developer exports the variable in the shell that runs the apply. You run the apply in that shell
+   only when the developer can export it there. Otherwise the developer writes the value into the private
+   token file (phase 2, "The private token file") from the manager.
+2. The factory reads it with `SecretValue.fromEnv("ORCHESTRA_FDK_<NAME>_TOKEN")`.
+3. Never echo the variable, and never pass the value as a command argument: both can reach a log.
+
+A Secret keeps the value it had at its last apply. After the developer rotates a token in the manager, apply
+again with the new value loaded.

package/skills/orchestra-fdk/references/integrations/support-desk.md

@@ -0,0 +1,31 @@
+# Support desks
+
+Give access with a Secret the network edge adds, or with the provider's platform connection. Egress is open,
+so add only the rule that adds the credential. A connection also brings events: a `Trigger` on them makes a
+work item in the Support pipeline for each new ticket. The agent installs or uses whatever client it prefers.
+The edge adds the credential to its requests.
+
+Phase 3, "From a recipe to code", turns a recipe into a Secret and a rule.
+
+| Provider | Access | Scopes | Check command |
+|---|---|---|---|
+| Zendesk | Platform connection `zendesk`, install field `subdomain`, with `.allow(zendesk)` on `<subdomain>.zendesk.com`. Or a token: `<subdomain>.zendesk.com → Authorization: Basic <email>/token:<SECRET>` | An agent's API token | `curl -fsS https://<subdomain>.zendesk.com/api/v2/users/me.json` |
+| Intercom | Platform connection `intercom`, with `.allow(intercom)` on `api.intercom.io`. Or a token: `api.intercom.io → Authorization: Bearer <SECRET>` | An access token from a private app | `curl -fsS https://api.intercom.io/me` |
+| Freshdesk | `<domain>.freshdesk.com → Authorization: Basic <SECRET>:X`. The API key is the user name, and `X` is the password | An agent's API key | `curl -fsS https://<domain>.freshdesk.com/api/v2/agents/me` |
+
+Token pages: Zendesk **Admin Center › Apps and integrations › APIs**; Intercom **Developer Hub**; Freshdesk
+**Profile settings › API key**.
+
+## Basic auth with a fixed suffix
+
+- **Zendesk:** the user name is the agent's email followed by `/token`, and the password is the token:
+  `SecretValue.basicAuth("<email>/token", SecretValue.fromEnv("ORCHESTRA_FDK_ZENDESK_TOKEN"))`.
+- **Freshdesk:** the API key is the user name, and the password is any fixed text, such as `X`. The kit's
+  Basic recipe puts the Secret in the password, so store the whole `<api key>:X` pair, base64-encoded, as the
+  Secret's value, and bind it with `basic("Authorization", secret)` (check the vendor page).
+
+## Events
+
+Each connection's events: `orchestra connections list-event-types <connection>`. The Intercom webhook is set
+up by hand in Intercom's Developer Hub, with the connection's address. Write the address to a file the
+developer can read: `npx orchestra connections rotate-webhook-token <connection> --output-file <path>`.

package/skills/orchestra-fdk/references/phases/0-start.md

@@ -0,0 +1,62 @@
+# Phase 0: Start
+
+**Goal:** the kit is installed and current, you are signed in to the organization the developer chose, and
+you know what the platform can do.
+
+## 1. Install the kit
+
+The kit is the `orchestra` command and the library the factory code imports. It was installed before this
+skill was linked, in one of two places. Keep it and its skills current with the command that matches:
+
+- Globally, with `npm install -g @orchestraworks/cli`. Update it with `npm update -g @orchestraworks/cli`.
+  Then `orchestra` runs in any folder.
+- In the factory folder, with `npm install @orchestraworks/cli` there. Update it with
+  `npm update @orchestraworks/cli`, run in that folder. Run the command there as `npx orchestra`.
+
+Use one way to run the command in each place:
+
+- Where no factory folder with the kit exists yet (phases 0 to 3), run
+  `npx --package @orchestraworks/cli orchestra`. With a global install, plain `orchestra` works too.
+- In a factory folder after its `npm install`, run `npx orchestra`.
+
+Find the developer's codebase folder. Call it `<codebase>`. Then run
+`npx --package @orchestraworks/cli orchestra --help`. It prints the command list. Node 22 or later is needed.
+
+## 2. Sign in
+
+1. Tell the developer: "A browser window will open. Sign in to Orchestra there and confirm."
+2. Run the sign-in with a command timeout of at least five minutes. The CLI opens the browser and waits for
+   the answer on a local port of this computer, so the browser must run on this same computer. When the
+   developer belongs to one organization, the login selects it. When they belong to several, the login stops
+   and asks you to name one. Ask the developer which, then run:
+
+   ```bash
+   npx --package @orchestraworks/cli orchestra auth login --org <organization>
+   ```
+
+   This sign-in renews itself, so a long run stays signed in. The address it signs in to is its first line.
+3. Use this browser sign-in. `orchestra auth login --no-browser` asks for a token at a hidden prompt
+   instead, and a typed token cannot renew itself: it stops working when it expires. Use it only for a short
+   run, with a token someone hands the developer. Users cannot create their own API keys in the console
+   yet; that is coming. If no browser can open on this computer, tell the developer. Ask them to run you on
+   a computer where one can.
+4. Read the two lines the login prints: `Signed in as <email>.` and
+   `Logged in to organization <id> (<slug>).` Tell the developer both, and confirm the organization.
+
+## 3. Read the orchestra skill
+
+Read `orchestra/SKILL.md` in your skill folder, in full, before phase 1. It says what each idea is for, what
+the starter declares, and what the platform cannot do yet. The later phases point at its sections. Never
+promise one of its "Cannot yet" lines.
+
+## Exit check
+
+```bash
+npx --package @orchestraworks/cli orchestra me get --output json
+node -p 'require(require("os").homedir() + "/.config/orchestra/config.json").profiles.default.organizationId'
+```
+
+The first answer's `email` is the developer's. A signed-in person's answer names no organization, so the
+second command reads the organization from the profile the sign-in saved. It prints only that id, never the
+token. The id is the one in `Logged in to organization <id> (<slug>).`, which the developer confirmed. You
+have read the orchestra skill. If the check fails, read `../troubleshooting.md`, "The sign-in stops working".