@orchestraworks/cli 0.5.2 → 0.5.3

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".

package/skills/orchestra-fdk/references/phases/1-discover.md

@@ -0,0 +1,111 @@
+# Phase 1: Discover
+
+**Goal:** you know what to build: a new factory or a new environment, what the codebase needs to run, and
+which services the agents must reach. You write it down before any factory code exists.
+
+Write every finding into `<codebase>/../orchestra-factory-notes.md`, one line for each item, with the file,
+page or command that shows it.
+
+## 1. Read the account: a new factory or a new environment
+
+An organization usually holds one factory, or none yet. Read what it holds before you ask the developer
+anything. These commands only read. `--all-pages` follows every page, and prints the rows as one array:
+
+```bash
+npx --package @orchestraworks/cli orchestra agents list --all-pages --output json
+npx --package @orchestraworks/cli orchestra environments list --all-pages --output json
+npx --package @orchestraworks/cli orchestra pipelines list --all-pages --output json
+npx --package @orchestraworks/cli orchestra workflows list --all-pages --output json
+npx --package @orchestraworks/cli orchestra connections list --output json
+```
+
+A row that an apply made carries the label `sfdk.managedBy`, whose value is the factory's name.
+
+1. Infer what the developer most likely wants:
+   - *No agents and no pipelines:* the account is empty. Infer **a new factory**.
+   - *Rows labeled with a factory name:* a factory exists. Infer **a new environment for that factory**,
+     such as another repository, a bigger machine, or a machine of the team's own.
+   - *Rows with no label:* someone made them by hand or with the CLI. Infer a new factory. If a row's slug
+     is one the starter declares, such as `manager-agent`, the apply updates that row. Say so in phase 2.
+2. Tell the developer what you found, in one or two sentences, for example: "This organization already has
+   the factory `factory`, with the agents Manager Agent, Engineer Agent lg, md and sm."
+3. Ask once, with your question tool, with the inferred choice first and marked as the recommendation.
+
+**A new factory.** Go on with section 2.
+
+The starters build one factory per organization. When the organization already holds a factory and the
+developer wants another one, make a separate organization for it:
+
+1. Create it: `npx --package @orchestraworks/cli orchestra organizations create --name "<name>"`. Read
+   `organizations create --help` for its other flags. When the command refuses, the developer creates the
+   organization in the console at `https://app.orchestraworks.ai`.
+2. Sign in to it as phase 0 says, with `--org <the new organization>`.
+3. Start this phase again, in the new organization.
+
+**A new environment for the existing factory.** Do not run `orchestra fdk init` in phase 4. Edit the factory
+that exists instead:
+
+1. Find the existing factory's folder: the folder with `fdk.json` and `main.ts`. Ask the developer where it
+   is when it is not on this computer.
+2. Load the factory's inputs, the same way every earlier apply loaded them. The engineering-team starter
+   reads `~/.config/orchestra/tokens.env`; the bug-fix starter reads `~/.config/orchestra/fdk-inputs.env`.
+   Load the file with `set -a; . <file>; set +a`, and never print it. Ask the developer when the file is not
+   there. An apply without these inputs removes the token rules the factory has now.
+3. With the inputs loaded, run `npm install` and `npx orchestra fdk diff` in that folder. It must be a clean
+   diff before you edit anything. If it is not, show the changes to the developer and ask what to keep.
+4. Then read the repository (section 2) for the new environment only. Phase 2 plans the new environment and
+   the agent that works on it, and phase 4 adds them to the existing code.
+
+## 2. Read the repository
+
+Read the codebase before you write any factory code. The factory must match it, and the machines most of
+all. Note each item:
+
+- **The operating system it builds and runs on.** These mean Windows: a `.sln` or `.csproj` that targets
+  .NET Framework, WinForms, WPF or IIS, PowerShell build scripts, or `windows-latest` in CI.
+- **The runtime it needs.** A kernel feature, a GPU, nested virtualization, an Android emulator, or a tool
+  for another operating system, such as Xcode, means a full virtual machine or the team's own machine.
+- The languages and toolchains, with their versions: `global.json`, `.nvmrc`, `.tool-versions`, the CI's
+  setup steps.
+- The build and test commands, from the CI file first, then the README and the build scripts.
+- The package feeds, private ones included: `nuget.config`, `.npmrc`, `pip.conf`, a feed in the CI file.
+- The services it needs, such as a database or a queue: a compose file, test containers, connection
+  settings.
+- Docker use: a `Dockerfile`, a compose file, Testcontainers.
+- The repository size: `du -sh <codebase>` and `git -C <codebase> count-objects -vH`.
+- The code host and the tracker: the remote URL (`git -C <codebase> remote get-url origin`), and links in
+  the README, the branch names or the CI file.
+
+These are facts for the later phases. Ask the developer only what the files cannot answer.
+
+## 3. Name each service, by category and provider
+
+For each outside service the agents need, name its category and its provider. Each category has one file in
+`../integrations/`:
+
+| Category | File | Examples |
+|---|---|---|
+| Code host | `code-repo.md` | GitHub, Bitbucket, GitLab, Azure DevOps |
+| Tracker | `issue-tracker.md` | Jira, Linear, GitHub Issues, Azure Boards |
+| Knowledge base | `knowledge-base.md` | Notion, Confluence, Guru |
+| Chat | `messaging.md` | Slack, Microsoft Teams |
+| Package registries | `dependencies.md` | npm, PyPI, NuGet, Maven |
+| CI and CD | `ci-cd.md` | GitHub Actions, Azure Pipelines, Jenkins, CircleCI |
+| Observability | `observability.md` | Sentry, Datadog, New Relic, Grafana |
+| Support desk | `support-desk.md` | Zendesk, Intercom, Freshdesk |
+| Design | `design.md` | Figma |
+| Cloud | `cloud.md` | AWS, Azure, Google Cloud |
+| Databases | `databases.md` | A staging database or a read replica |
+| Secrets managers | `secrets-managers.md` | 1Password, Vault, Azure Key Vault |
+| Incidents | `incident.md` | PagerDuty, Opsgenie |
+| Analytics | `analytics.md` | Pendo, Mixpanel, Amplitude |
+| Feature flags | `feature-flags.md` | LaunchDarkly, Split, Unleash, ConfigCat |
+
+Infer each one from the codebase and the connections list. Then tell the developer what you found, and ask
+once, with your question tool, which code host, which tracker and which other services the agents need.
+Put your inference first, marked as the recommendation. No provider is a default.
+
+## Exit check
+
+`orchestra-factory-notes.md` has a line for each item in sections 2 and 3, or says the item does not apply,
+and it records the answer to section 1: a new factory, or a new environment for a named factory.