@orchestraworks/cli 0.5.2 → 0.5.4

package/skills/orchestra-fdk/SKILL.md

@@ -1,561 +1,128 @@
 ---
 name: orchestra-fdk
-description: Use when building and applying an Orchestra factory with the factory development kit for a developer's codebase - installing the kit, signing in, looking at the account to tell a new factory from a new environment for an existing one, the bug-fix fast path (one agent, one bug, a pull request), writing the engineering-team starter, explaining its plan, choosing how the agents reach a model, the first apply without tokens, proving the machines locally first and applying them, the "Set up" item that runs the repository from a git bundle, the steps the code cannot declare, connecting the code host and the tracker, and starting the Bootstrap. Reads the orchestra skill for the platform's ideas and references/environment.md for the machines.
+description: Use when building and applying an Orchestra factory with the factory development kit for a developer's codebase - a playbook of seven phases (start, discover, plan, connect, build, prove, hand over), each with a goal, its steps and an exit check, plus one file per integration category (code host, tracker, knowledge base, chat, package registries, CI, observability, support desk, design, cloud, databases, secrets managers, incidents, analytics, feature flags) that says how to give the agents access. Reads the orchestra skill for the platform's ideas, references/environment.md for the machines and references/troubleshooting.md when a check fails.
 ---
 
 # Build and apply an Orchestra factory
 
-You build and apply an Orchestra factory for the developer you are working with, with the factory
-development kit. A *factory* is a team of AI agents, the machines they work on, the keys they use, and the
-pipelines their work moves through. You run every command. The developer only answers questions and approves
-things in the browser.
-
-The `orchestra` skill explains every idea named here, how the CLI works, and what the platform cannot do yet.
-When this skill says "orchestra skill, section N", read that section of `orchestra/SKILL.md` in your skill
-folder. Use it to answer a case the steps do not cover, and never promise one of its "Cannot yet" lines.
-
-The CLI's own help is the full list of commands and flags: `orchestra --help` and
-`orchestra <noun> <verb> --help`. The kit's reference, `docs/REFERENCE.md`, ships in the package;
-`references/authoring.md` says how to find it. This skill names a flag only where a step needs it.
-
-Ask questions with your question tool: `AskUserQuestion` in Claude Code, its counterpart in Codex. Ask one
-thing at a time. Never ask the developer to paste a token into the chat.
-
-## The bug-fix fast path
-
-`orchestra fdk init` without `--template` writes the bug-fix starter: one agent that takes a bug as its
-first message and answers with a pull request and a report. Take this path when the developer wants one bug
-fixed in a GitHub repository. Do steps 1 to 3 below first. Then:
-
-1. Make a new folder beside the codebase, `<codebase>/../orchestra-factory`, called `<factory>`. In it, run
-   `npm init -y`, then `npm install @orchestraworks/cli`.
-2. Write the starter. `<owner>/<name>` is the GitHub repository. Add `--model-key anthropic` or
-   `--model-key openai` only when the organization brings its own model key to the model gateway (step 6).
-
-   ```bash
-   npx orchestra fdk init --repository <owner>/<name>
-   ```
-
-3. Run `npm install`, then `npm run typecheck`. Both must pass.
-4. Fill in `<factory>/skills/codebase/SKILL.md` with how the codebase installs, tests and starts, and the
-   services it needs. When the codebase has an `AGENTS.md` or `CLAUDE.md`, write one line naming it instead.
-5. Set the shell inputs. `main.ts` reads them, and `init` printed each with what it is. They come with the
-   hand-over note: `ORCHESTRA_FDK_IMAGE_REPOSITORY`, `ORCHESTRA_FDK_RUNTIME_IMAGE`,
-   `ORCHESTRA_FDK_MODEL_GATEWAY_HOST`, `ORCHESTRA_FDK_IMAGE_PULL_ACCESS_KEY_ID` and
-   `ORCHESTRA_FDK_IMAGE_PULL_SECRET_ACCESS_KEY`, plus `ORCHESTRA_FDK_ANTHROPIC_API_KEY` or
-   `ORCHESTRA_FDK_OPENAI_API_KEY` with `--model-key`. Ask the developer to write them into a file only they
-   can read, as in step 6, and load it in each command that runs `orchestra`:
-   `set -a; . ~/.config/orchestra/fdk-inputs.env; set +a`. Docker on this computer must also be signed in
-   to the image registry, with the details in the same note.
-6. Run `npx orchestra fdk diff` and show the developer the change list. On their yes, run
-   `npx orchestra fdk apply --require-approval never --install-timeout 0`. It builds and pushes the image,
-   prints a GitHub App install link, and stops without waiting. The link is shown once. Give it to the
-   developer, and ask them to say when the app is installed. Then run the same apply again: it finds the
-   installation and applies the rest. If the link was lost, add `--remint-install-links` to the apply. That
-   revokes the old link and prints a new one.
-7. Send the bug. The agent's id is `<factory name>-bugfix`, where the factory name is the one `init` printed:
-
-   ```bash
-   npx orchestra sessions start --agent-id <factory name>-bugfix --content "<the bug, in the reporter's words>" --output json
-   ```
-
-   The answer is `{"session":{…},"firstItem":{…}}`. The session id is `.session.id`.
-8. Wait for the turn to end, in the foreground, with one blocking command:
-
-   ```bash
-   npx orchestra sessions wait <session id> --timeout 540
-   ```
-
-   Do not start the wait in the background and end your turn. A headless agent exits when its turn ends,
-   and the waiting command goes with it. `--timeout 540` ends the wait before a ten-minute command limit.
-   When it times out, it prints the session's last status and exits non-zero: run the same command again.
-9. `sessions wait` shows no progress. To see what the agent did, read the conversation's items:
-   `npx orchestra sessions list-items <session id> --output json`. The rows are in `data`. The developer
-   can watch the same session live in the console at `https://app.orchestraworks.ai`.
-
-**Check:** the session's status is `COMPLETE`, and its last message names the pull request and the report.
-
-## The steps
-
-Do them in order. Each step ends with a check. Do not go on until the check passes.
-
-Before every apply, run the check in `references/environment.md` under "Before any cloud apply". It
-removes every local-only credential from the factory code.
-
-A *clean diff* is a `npx orchestra fdk diff` that creates, updates and deletes no agent, environment or
-pipeline. While a token or key is loaded, each secret it fills shows `value-write-pending` on every diff, even
-right after an apply. That is expected, and a clean diff may show it.
-
-The factory is applied three times. The first apply comes before any token or input, so the developer sees
-the agents and pipelines first. The second apply adds the machine setup, after you prove it on this computer.
-The third apply adds the code host and tracker tokens and the inputs.
-
-After the first apply, the steps follow the order of the starter's README, "After apply":
-
-1. Set up the machines (step 8).
-2. Grant the Manager Agent its role and create the score metrics (step 9).
-3. Set up: make the repository run from a bundle (step 10).
-4. Connect the code and the tracker (steps 11 and 12).
-5. The Bootstrap (step 13).
-6. Commissioning (later, when the Bootstrap passes).
-
-### 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 (steps 2 to 4), 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`.
-
-1. Find the developer's codebase folder. Call it `<codebase>`.
-2. Run `npx --package @orchestraworks/cli orchestra --help`.
-
-**Check:** the help prints the command list, and `fdk init --help` lists `--template`. Node 22 or later is
-needed.
-
-The kit's full authoring reference is `references/authoring.md` in this skill's folder. Read it when you need
-a building block this skill does not cover.
-
-### 2. Sign in
-
-1. Tell the developer: "A browser window will open. Sign in to Orchestra there and confirm."
-2. Run `npx --package @orchestraworks/cli orchestra auth login`, 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, and 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. Note the organization id.
-
-**Check:** the login printed the developer's email and the organization the developer named.
-
-### 3. Look before you ask: 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:
+You build and apply an Orchestra factory for the developer you work with, with the factory development kit.
+A *factory* is a team of AI agents, the machines they work on, the keys they use, and the pipelines their
+work moves through. You run every command. The developer answers questions and approves changes.
+
+The work has seven phases. Do them in order, apart from phase 3 on a first run (below). Each phase has a
+file in `references/phases/` with its full steps. Read the file before you start the phase. A phase ends with
+an exit check. Do not start the next phase until the check passes.
+
+The first run needs no optional integration. The starter applies and runs with only the model route, and you
+create the first work by hand. So on a first run, phase 3 connects only what the build needs, such as a
+private package feed: phase 5 cannot install the code without it. When the build needs nothing private, skip
+phase 3. The code host, the tracker and the other services wait until phase 5 passes.
+
+The `orchestra` skill explains every idea named here and what the platform cannot do yet. When a phase file
+says "orchestra skill, section N", read that section of `orchestra/SKILL.md` in your skill folder. The CLI's
+own help lists every command and flag: `orchestra --help` and `orchestra <noun> <verb> --help`.
+
+## Rules
+
+- **Look before you ask, and ask once.** Read the account, the codebase and the files first. Then ask the
+  developer only what they cannot answer, in one question with your question tool (`AskUserQuestion` in
+  Claude Code, its counterpart in Codex). Put your inference first, marked as the recommendation.
+- **State each change with its reason before every apply.** Say what changes on the platform and why, in
+  plain words.
+- **Never take a token through chat. Tokens come from files.** The developer writes each token into a
+  private file. You load the file into the command's shell and never print it.
+- **Stop at a failed exit check.** Go to `references/troubleshooting.md`, find the cause, and fix it before
+  you go on.
+- **No apply without a reviewed diff and the developer's yes.** Show `fdk diff` first. Only after the
+  developer approves that change list, run the apply with `--require-approval never`. Never use that flag, or
+  any other flag that skips the approval, before the yes.
+
+## The phases
+
+### 0. Start
+
+**Goal:** the kit is installed, you are signed in, and you know the platform.
+**Steps:** install or update the kit, sign in through the browser, confirm the organization, and read the
+`orchestra` skill in full.
+**Exit:** `orchestra me get --output json` shows the developer's email, the saved profile names the
+confirmed organization id, and you have read the `orchestra` skill.
+**File:** `references/phases/0-start.md`.
+
+### 1. Discover
+
+**Goal:** you know what to build.
+**Steps:** read the account (a new factory, or a new environment for an existing one), read the repository,
+and name the integration category and the provider of each service it needs.
+**Exit:** a written finding in `orchestra-factory-notes.md`.
+**File:** `references/phases/1-discover.md`.
+
+### 2. Plan
+
+**Goal:** the developer approves what you will build.
+**Steps:** adapt the starter to the finding, the environment first, and choose the model route. Show the
+agents table and the working environment table, each change with its reason.
+**Exit:** the developer said yes.
+**File:** `references/phases/2-plan.md`.
+
+### 3. Connect (the build's feeds first, the rest after the first run)
+
+**Goal:** the agents can reach each service the developer chose to connect. On a first run, that is only what
+the build needs, such as a private package feed.
+**Steps:** give access to the code host, the tracker and each other service found in phase 1, from its file
+in `references/integrations/`: the access rule, and a trigger where events should make work.
+**Exit:** every service the developer chose to connect has its access (a Secret, an env value or a platform
+connection), and egress is open. On a first run, each feed's token is in the token file, and phase 4 checks
+the access after its apply.
+**File:** `references/phases/3-connect.md`.
+
+### 4. Build
+
+**Goal:** the platform matches the plan.
+**Steps:** `fdk init`, edit, `fdk synth`, prove the machine locally, `fdk synth` again, `fdk diff`, the
+developer's yes, then `fdk apply`. On a first run, the apply carries only the model route and
+any private package feed the build needs.
+**Exit:** a clean apply, and the platform lists every agent and environment.
+**File:** `references/phases/4-build.md`.
+
+### 5. Prove
+
+**Goal:** the customer's app runs on an agent's machine, and one real item goes end to end.
+**Steps:** a machine starts, gets the code from a git bundle or a public clone, and installs it. The app
+builds, runs and is reachable at a machine endpoint or a machine view. Then one small real item, created by
+hand, goes end to end.
+**Exit:** the app is reachable, and the first item's report page exists.
+**File:** `references/phases/5-prove.md`.
+
+### 6. Hand over
+
+**Goal:** the developer can run the factory without you.
+**Steps:** show how to send work, where to watch it, where cost is shown, and what to do next.
+**Exit:** the developer has sent, or knows how to send, the next item.
+**File:** `references/phases/6-handover.md`.
+
+## Look first
+
+Phase 1 starts with these reads. They change nothing:
 
 ```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
 ```
 
-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 before step 7.
-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, sm and bare."
-3. Ask once, with your question tool, with the inferred choice first and marked as the recommendation.
-   Then follow the branch below for the answer.
-
-**A new factory.** Go on with step 4, or with the bug-fix fast path.
-
-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 step 2 says, with `--org <the new organization>`.
-3. Start again at step 3, in the new organization.
-
-**A new environment for the existing factory.** Do not run `orchestra fdk init`. 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. Add the environment, and the agent that works on it:
-   - Engineering-team starter: call `declareEnvironment` in `main.ts`, as the existing agents do.
-   - Bug-fix starter: add a `new Environment(factory, "<name>", …)` beside `runtime` in `main.ts`, and an
-     `Agent` on it.
-5. Prove the new environment with `references/environment.md`, sections 1 to 6, then come back here. Prove
-   the environment and the agent you added, not the existing ones.
-6. Apply as step 12 says, with the inputs loaded: diff, explain, approve, apply. The diff after it is clean.
-7. Give the new agent its first work, and wait for it. Engineering-team starter: create an item in the
-   right pipeline and assign it to the new agent, as step 10 does, then wait as step 10 says. Bug-fix
-   starter: start a session with the new agent and wait, as the fast path's points 7 to 9 say.
-
-**Check:** the developer confirmed one of the two choices.
-
-### 4. Write the factory
-
-Ask one question, with these three choices:
-
-- **A todo app sample.** A small public app, for a quick first success.
-- **An engineering team (your real repository).** Recommended.
-- **I already have a factory.ts.**
-
-What each answer does:
-
-- *Engineering team:* go on below. This starter connects Bitbucket and Jira only. For a GitHub repository,
-  take the bug-fix fast path instead.
-- *Todo app sample:* write it as below, with `--template todo-factory` in point 2. It works on the public
-  `orchestraworks/todo-app`. Then go on with step 5.
-- *I already have a factory.ts:* copy their folder into `<factory>` (below). It needs `fdk.json` and a
-  `"type": "module"` package. Install the kit in it as in point 3, then go on with step 5, using their
-  own inputs.
-
-For the engineering team:
-
-1. Make a new, empty folder beside the codebase: `<codebase>/../orchestra-factory`. Call it `<factory>`.
-   Do not install the kit in it before point 2.
-2. In `<factory>`, write the starter:
-
-   ```bash
-   npx --package @orchestraworks/cli orchestra fdk init --template engineering-team
-   ```
-
-   Run it in the new, empty folder, with no kit installed there: the starter brings its own
-   `package.json`.
-
-   It writes `README.md`, `main.ts`, `inputs.json`, `package.json`, `fdk.json`, `tsconfig.json`,
-   `agents/`, `lib/` and `onboarding/`. It overwrites nothing. If a file is in the way, it writes nothing
-   and names it.
-3. In `<factory>`, install what the starter's `package.json` names, the kit among them:
-
-   ```bash
-   npm install
-   ```
-
-   From now on, run `npx orchestra` in `<factory>`.
-4. Read `<factory>/README.md` whole. It says what the starter declares, and why.
-5. Leave `inputs.json` empty for now. Step 11 fills it in.
-
-**Check:** `npm run typecheck` passes in `<factory>`.
-
-### 5. Read the plan and explain it
-
-Before anything reaches the platform, show the developer what the factory is. Explain it from what the
-code produced, not from memory.
-
-1. In `<factory>`, run `npx orchestra fdk synth`. It works offline and changes nothing.
-2. Read `<factory>/fdk.out/plan.json`. Each entry in `resources` has a `kind` (`agent`, `environment`,
-   `gateway-key`, `secret`, `pipeline`), a `slug` and a `payload`.
-3. Read `<factory>/fdk.out/warnings.json`.
-4. Explain it to the developer. Explain each idea from its section in the orchestra skill: what it is for
-   first, then what it is. Use short, plain sentences. Name no file, no class and no field. Cover the four
-   parts below, in this order.
-
-**What each kind of thing is, and why it is there.**
-
-- *Agents* do the work: orchestra skill, section 2. There are five. The Manager Agent sets up the factory
-  and grades the others. The three Engineer Agents (lg, md and sm) fix bugs and build features. Engineer
-  Agent bare takes only the Bootstrap's baseline replays, to show what the study adds. Say which AI model
-  each one uses.
-- *Environments* are the machines the agents work on: sections 4 and 5. There are four: Engineer Agent bare
-  uses the same one as Engineer Agent lg. Say each one's size and its network rules.
-- *Pipelines* are where work items live: sections 9 and 10.
-- *The warning* says the repository and the tracker are not connected yet. Part four explains it.
-
-**The gateway key.** The starter's code as written sends every agent's model calls through the model
-gateway, with one gateway key: orchestra skill, section 7. The key is a key to `models.orchestraworks.ai`,
-stored as a secret. Our network edge adds it to each model call, so no agent and no person sees it.
+## Apply
 
-Say that this is one of three options. Step 6 asks which one the developer has.
+Phase 4 ends with these two, in the factory folder. Run the second only after the developer approved the
+change list the first one printed:
 
-**The pipelines and their stages.** Show this table, built from the `pipeline` entries in the plan: the
-name, the item prefix and the stages, in order.
-
-| Pipeline | Item prefix | Stages | What it is for |
-|---|---|---|---|
-| Onboarding | `onbd` | Todo, In progress, Needs review, Done | Setting up the factory: Set up, the Bootstrap and every Replay item. It goes away at commissioning. |
-| Bugs | `bug` | Triage, Parked, In progress, In review, Done, Won't fix | Bugs. Parked holds a bug that waits until the Bootstrap passes, or one a person set aside. |
-| Features | `feat` | Backlog, Todo, In progress, In review, Done | New features. |
-| Support | `supp` | Triage, Answering, Waiting on requester, Resolved, Closed | Questions from the team's users. |
-
-If the plan differs from this table, show the plan. Say that, for now, an item can move from any stage to
-any other. A person or an agent moves it to where the work stands.
-
-**What the warning means.** The repository and the tracker are not connected yet. So this first apply
-adds no Bitbucket or Jira token, and the Manager Agent cannot reach them. It asks for them in Needs review
-until they are connected. A later apply, after the machines are set up and the tokens and inputs are in,
-connects them and the warning goes away.
-
-5. Ask the developer, with your question tool, whether they have questions. Answer each one. Then go on.
-
-**Check:** the developer has no more questions about the plan.
-
-### 6. Choose how the agents reach a model
-
-Each agent needs a way to reach its AI model. There are three options, and the developer uses the one that
-matches what they already have. Ask which they have, with your question tool, or infer it from what is set
-up, such as an existing factory's model Secret or `ModelProviderKey`. Then follow that option. For plan
-questions, send the developer to **Settings › Plan & usage** in the console.
-
-**A Claude or Codex subscription.** The developer signs in a real terminal on their own computer. Run from
-your shell, its browser step hangs. You never read or copy the value.
-
-- *Claude.* `claude setup-token` prints a long-lived token. The developer saves it in the private file
-  below, as `ORCHESTRA_FDK_CLAUDE_CODE_OAUTH_TOKEN`. The factory stores it as a Secret, and the network edge
-  adds it to calls to `api.anthropic.com`. The machine holds only a placeholder token and an empty API key.
-  Declare the Claude sign-in recipe from `references/authoring.md`, "Secrets are recipes, never values".
-  Never put the token in the environment's settings: they are stored and shown in plain text.
-- *Codex.* A personal access token, which begins `at-`. A ChatGPT Business or Enterprise member makes it
-  at `chatgpt.com/admin/access-tokens`, when the workspace owner allows it. Or a separate ChatGPT sign-in:
-  `CODEX_HOME=<dir> codex login`, never a copy of the developer's own `~/.codex` sign-in. A separate
-  sign-in must live on a `/home` volume that every machine using it shares, because each renewal
-  replaces the sign-in. After the copy, a new `codex login` in `~/.codex` signs the cloud copy out.
-  Keep a Codex sign-in off the model gateway: the gateway refuses its requests with `model_not_found`.
-  Not released yet: the worker settings that put a Codex sign-in on a machine. Until they are, use the
-  model gateway or an OpenAI API key for a `codex` agent.
-
-An agent on a subscription turns the model gateway off: remove `enableModelGateway: true` from its model
-settings.
-
-**An Orchestra account, through the model gateway.** One endpoint reaches OpenAI, Anthropic and open
-models. The organization can also route models: `orchestra model-configs` sets which providers serve a
-model and in which order, so a call falls back to the next provider, and `orchestra model-aliases` gives a
-model the organization's own name. The organization can add its own provider key to the gateway as a
-`ModelProviderKey` (orchestra skill, section 7). The starter's code as written uses this option, so it
-needs no edit.
-
-**Their own provider API key.** The key is a Secret that the network edge adds to calls straight to the
-provider, with no gateway in between. For Anthropic, add `x-api-key: ${secret}` on `api.anthropic.com`;
-for OpenAI, add `authorization: Bearer ${secret}` on `api.openai.com`. Read the key from a shell variable
-such as `ORCHESTRA_FDK_ANTHROPIC_API_KEY`, and turn `enableModelGateway` off for the agent.
-`references/authoring.md` shows the Secret and the rule.
-
-For a subscription or an own key, the apply reads the token or key from the shell, so it must be saved
-before step 7:
-
-1. Ask the developer to make a file only they can read, outside the codebase:
-
-   ```bash
-   mkdir -p ~/.config/orchestra && touch ~/.config/orchestra/tokens.env && chmod 600 ~/.config/orchestra/tokens.env
-   ```
-
-2. Ask them to add one line to it, filled in by them, such as `ORCHESTRA_FDK_CLAUDE_CODE_OAUTH_TOKEN=...`.
-   Step 11 adds the Bitbucket and Jira tokens to the same file later.
-3. Load the file into each apply's shell without printing it: `set -a; . ~/.config/orchestra/tokens.env;
-   set +a`.
-
-Then edit `<factory>/main.ts` and `<factory>/lib/environment.ts`, and run `npm run typecheck` and
-`npx orchestra fdk synth`.
-
-**Check:** the developer chose an option, and the plan shows it: a gateway rule for the model gateway, or a
-Secret and a rule on the provider's host for a subscription or an own key. For those two, the file exists
-with mode 600 (`stat`). Do not read its contents.
-
-### 7. The first apply (no code host or tracker tokens)
-
-`orchestra fdk apply` makes the platform match the code. The developer approves the change list first.
-
-1. For a subscription or an own key (step 6), load the token or key from the private file. Use a shell without the
-   Bitbucket and Jira tokens: if `ORCHESTRA_FDK_BITBUCKET_TOKEN` or `ORCHESTRA_FDK_JIRA_TOKEN` is set,
-   unset it for this step.
-2. In `<factory>`, run `npx orchestra fdk diff`. It changes nothing.
-3. Show the developer the change list in plain words: the five agents, their four machines, the keys and
-   their secrets, and the four pipelines.
-4. Ask them to approve it, with your question tool.
-5. On a yes, run `npx orchestra fdk apply --require-approval never` in `<factory>`. The flag is needed
-   because your shell has no terminal to type "y" at. It is safe only after the developer approved the
-   same change list.
-
-An organization on the `individual` plan cannot store a key or add one at the network edge, so this apply
-stops with a plan error. Tell the developer, and point them to **Settings › Plan & usage** in the console.
-
-**Check:** a second `npx orchestra fdk diff` is a clean diff, and `<factory>/fdk.out/result.json` exists.
-
-### 8. Set up the machines
-
-Read and follow `references/environment.md`, in this skill's folder. It finds how the codebase is installed,
-tested and started. It proves that on this computer first, in the local environment, and the cloud is the
-fallback. It writes what worked into `<factory>/lib/environment.ts` and `<factory>/lib/setup.sh`.
-
-Then apply the machine setup, in a shell loaded as in step 7: the model token or key of step 6 if there
-is one, and no Bitbucket or Jira token yet.
-
-1. In `<factory>`, run `npx orchestra fdk diff`.
-2. Explain what changed, in plain words: the setup script, the settings and the ports.
-   Say that each new machine gets them, and that running machines keep their old setup.
-3. Ask the developer to approve it, with your question tool.
-4. On a yes, run `npx orchestra fdk apply --require-approval never` in `<factory>`.
-
-**Check:** the checks in `references/environment.md` pass, and a second `npx orchestra fdk diff` is a clean
-diff.
-
-### 9. The steps the code cannot declare
-
-Do these before Set up starts, in the README's order: the first two steps of "After apply: steps the code
-cannot declare" in `<factory>/README.md`. It holds the exact commands.
-
-1. **Grant the Manager Agent the `agent-manager` role**, for the whole organization. The Manager Agent
-   works on items in every pipeline, reads the Engineer Agents' sessions, and changes the Engineer Agents.
-   An agent starts with only `agent-worker`. The role list you send replaces the old one, so keep every
-   entry it has now. Ask the developer to approve: "Give the Manager Agent the agent-manager role in the
-   whole organization?" On a yes, send the update with `--require-approval never`.
-2. **Create the score metrics**: `bash onboarding/create-score-metrics.sh`, once, in `<factory>`. The
-   Manager Agent writes each replay's scores into them.
-
-**Check:** `npx orchestra organization-memberships get <membership id>` lists both roles, and
-`npx orchestra metrics list --output json` lists the five `replay-` metrics.
-
-### 10. Set up: run the repository from a bundle
-
-The Manager Agent has no access to the code host yet. So it gets the code as a *git bundle*: one file that
-holds the repository's history. This item is also the cloud's confirmation of what you proved on this
-computer.
-
-1. Find the default branch: `git -C <codebase> symbolic-ref refs/remotes/origin/HEAD`.
-2. Cut the bundle outside the codebase:
-   `git -C <codebase> bundle create <codebase>/../orchestra-setup.bundle <default branch>`.
-3. Upload it: `npx orchestra files create --file <codebase>/../orchestra-setup.bundle --output json`. Note
-   the file id.
-4. The kit cannot declare items. Create them in the Onboarding pipeline, in this order:
-
-   ```bash
-   npx orchestra work-items create --pipeline onboarding --title "Set up" --description "<what done means>" --output json
-   npx orchestra work-items create --pipeline onboarding --title "Bootstrap" --description "<the threshold>" --output json
-   ```
-
-   The Set up description says:
-   - Get the bundle with `orchestra files get-content <file id> --output-file setup.bundle`, and clone the
-     code from it under `/work`.
-   - Install with the internet. Then run the stack with local settings only, such as the local Supabase
-     stack's. Write those settings files, such as `.env.local`, from what `references/environment.md`
-     found.
-   - Note in the report any setting or log that names a production or live host, and continue.
-   - Stack up: start the whole stack with the project's own scripts, and load its seed data.
-   - Validation: call the API and check real answers; for a web UI, sign in as a local test user and do one
-     real business operation at the machine endpoint.
-   - Tests: then run the unit, functional and end-to-end tests. Report which ran, which could not, and
-     whether they match the team's CI.
-   - Report each command, its result and its time.
-   - Done means the stack is up and validation passes. The tests do not decide Done.
-   - Prove that an Engineer Agent can run the tests from the same bundle.
-
-   The Bootstrap description holds the two values of "The Bootstrap threshold" in `<factory>/README.md`.
-   Leave the Bootstrap unassigned in Todo.
-5. Start Set up: `npx orchestra work-items assign <set-up item id> --agent-id manager-agent`. Assigning
-   starts the Manager Agent's conversation on the item.
-6. Watch it: `npx orchestra work-items get <id> --output json` lists the item's `sessions`. Run
-   `npx orchestra sessions wait <session id> --timeout 540` in the foreground, and run it again when it
-   times out, as the fast path says. The developer can watch the same session in the console at
-   `https://app.orchestraworks.ai`.
-7. When it ends, read the agent's report with the developer. Fix a failed step in the environment: go back
-   to `references/environment.md`, prove the fix on this computer, apply it as in step 8, then assign the
-   item again to wake the agent. Note the time before you assign. The session can still show the last
-   turn's `COMPLETE`, and then `sessions wait` returns at once. So run
-   `npx orchestra sessions get <session id> --output json` first, and wait only once its `lastActiveAt` is
-   later than that time.
-
-**Check:** the report shows the stack up, validation passing at a machine endpoint, and the test result.
-
-### 11. Connect the code and the tracker
-
-The agents reach Bitbucket and Jira with two personal API tokens. The platform stores each one as a
-*Secret*, a value the agents never see: the network edge adds it to their requests. You never see the
-values either. Connect the code first, then the tracker.
-
-1. Fill in `<factory>/inputs.json`. Read the values from `<codebase>` where you can, and ask for the rest:
-   - `repositoryUrl`: the repository's HTTPS address, from `git -C <codebase> remote get-url origin`.
-     Write it as `https://bitbucket.org/<workspace>/<repository>`.
-   - `repositoryDefaultBranch`: the default branch from step 10.
-   - `jiraSite`: the Jira site host, such as `acme.atlassian.net`. Ask.
-   - `jiraEmail`: the Atlassian account email the Jira token belongs to. Ask.
-2. Ask the developer to create two tokens:
-   - The code: a Bitbucket API token, at `https://id.atlassian.com/manage-profile/security/api-tokens`,
-     with the Bitbucket scopes to read and write repositories and pull requests.
-   - The tracker: a Jira API token, at the same page, without scopes. A token with scopes works only
-     through `api.atlassian.com`, which this starter does not add the token to.
-3. Ask the developer to add both to the private file of step 6. If it does not exist yet, they make it
-   first:
-
-   ```bash
-   mkdir -p ~/.config/orchestra && touch ~/.config/orchestra/tokens.env && chmod 600 ~/.config/orchestra/tokens.env
-   ```
-
-   Then they add these two lines, filled in by them:
-
-   ```
-   ORCHESTRA_FDK_BITBUCKET_TOKEN=...
-   ORCHESTRA_FDK_JIRA_TOKEN=...
-   ```
-
-4. Load the file into a command's shell without printing it:
-   `set -a; . ~/.config/orchestra/tokens.env; set +a`.
-
-You may use the same tokens on this computer to read past pull requests and issues. Load the file the same
-way and send `Authorization: Bearer $ORCHESTRA_FDK_BITBUCKET_TOKEN` to `https://api.bitbucket.org/2.0/`.
-For Jira, use Basic auth with `jiraEmail` and `$ORCHESTRA_FDK_JIRA_TOKEN` on
-`https://<jiraSite>/rest/api/3/`. Never print a token, and never write one into a file in `<codebase>` or
-`<factory>`.
-
-Other code hosts and trackers connect through a *connection*: orchestra skill, section 17.
-
-**Check:** the file exists and has mode 600 (`stat`). Do not read its contents. With the tokens loaded,
-`npx orchestra fdk synth` writes an empty `fdk.out/warnings.json`.
-
-### 12. The token apply
-
-1. In `<factory>`, with the tokens loaded, run `npx orchestra fdk diff`.
-2. Explain only what changed since step 8, in plain words:
-   - *The token secrets.* The Bitbucket token (twice: once for the API, once for git) and the Jira token
-     are stored as secrets. No one sees their values.
-   - *The Manager Agent's machine.* It gets rules that add the Bitbucket token on `api.bitbucket.org` and
-     `bitbucket.org`, and the Jira token on the Jira site. So it can clone, open pull requests and read
-     issues.
-   - *The Engineer Agents' machines.* They get deny rules for Bitbucket and for the Jira site. Say why:
-     in the Bootstrap, the Engineer Agents redo past pull requests, called replays, to show how well they
-     work. A replay must not see the real fix. So they cannot reach Bitbucket or Jira until commissioning,
-     when they start real work. They get the code as a file the Manager Agent uploads.
-   - The Manager Agent's instructions now name the repository and the tracker.
-3. Ask the developer to approve it, with your question tool.
-4. On a yes, run `npx orchestra fdk apply --require-approval never` in `<factory>`, with the tokens loaded.
-
-Run every later apply with the tokens loaded. An apply without them takes the token rules off the
-Manager Agent's machine again.
-
-**Check:** a second `npx orchestra fdk diff`, with the tokens loaded, is a clean diff.
-
-### 13. The Bootstrap
-
-The Bootstrap teaches the Engineer Agents this codebase, then tests them on past pull requests they have
-not seen. `<factory>/README.md`, "Bootstrap", says each step and the threshold.
-
-1. Once Set up is in Done, assign the Bootstrap:
-   `npx orchestra work-items assign <bootstrap item id> --agent-id manager-agent`. Watch it as in step 10.
-2. The Manager Agent creates the Replay items and scores them. It moves the Bootstrap to Done on a pass,
-   or to Needs review after two rounds that do not pass. Read its report with the developer.
-
-Commissioning comes after a pass: `<factory>/README.md`, "Commissioning".
-
-**Check:** the Bootstrap has a session, and the Onboarding pipeline lists its Replay items.
+```bash
+npx orchestra fdk diff
+npx orchestra fdk apply --require-approval never
+```
 
-## Beyond the steps
+## The other references
 
-- What the platform can and cannot do yet: the orchestra skill, sections 1 to 19. Read the section for the
-  idea in question.
-- Where an agent's knowledge goes (instructions, platform skills, codebase skills, the customer's own skills,
-  versions): the orchestra skill, section 19.
+- `references/environment.md`: how to find the codebase's setup, prove it on this computer, and write it into
+  the environment.
+- `references/integrations/`: one file per category of service, with how to give the agents access.
+- `references/authoring.md`: the kit's building blocks, for a case the phases do not cover.
+- `references/troubleshooting.md`: what each failure means, and what to do.