@orchestraworks/cli 0.5.2 → 0.5.4

package/skills/orchestra-fdk/references/authoring.md

@@ -103,6 +103,21 @@ entrypoint decides what answers. Omit `harness`, or misspell it, and synth fails
 a message naming the five; there is no default, because guessing which one an author meant would pick a
 different program than the one they wanted.
 
+### Every agent's instructions start with an Attribution section
+
+The starter's agents start their instructions with it. When you write an agent of your own, start its
+instructions with the same section, with the agent's display name and slug filled in:
+
+```
+## Attribution
+You are <agent display name>. Mark the work you produce as yours:
+- every commit message and pull request description ends with
+  Co-Authored-By: <agent display name> <<agent-slug>@agents.orchestraworks.ai>
+- every comment and tracker edit ends with one line: — <agent display name>, Orchestra
+```
+
+A person who reads a commit, a pull request, a comment or a tracker edit then sees which agent made it.
+
 ### Platform skills are attached by id
 
 An agent uses a platform skill only when its `skills` list names it: `Skill.fromId(factory, "skill_<key>")`
@@ -1077,9 +1092,9 @@ cookie your app sets must carry `SameSite=None; Secure; Partitioned`, or the bro
 frame and your app's own sign-in or session state is lost on each load. The platform's own access
 cookie is already set this way, and your app never sees it.
 
-### Typed flows: `user-grants grant` and `sessions wait`
+### Typed flows: `user-grants grant`, `sessions wait` and `sessions tail`
 
-Two commands stay hand-shaped, because the orchestration is the value a bare generated call would
+Three commands stay hand-shaped, because the orchestration is the value a bare generated call would
 drop. Both are platform commands — they read and write the live factory, not your code.
 
 ```bash
@@ -1104,6 +1119,18 @@ taking no more messages), which settles too. `--interval` and `--timeout` are yo
 any settlement (the printed state
 carries the outcome) and non-zero only on a timeout or a failed call.
 
+```bash
+orchestra sessions tail session_01abc --until-settled
+```
+
+Prints each item of the session as it is saved: a reply line by line as it grows, a tool call as one
+line, printed again when its status changes. With `--output json` it prints each item once, as one
+JSON line, when the item can no longer change. It starts with the items that
+already exist; `--after <item id>` starts after that item instead. While a turn runs, each read waits
+on the platform for the next saved output, so the command does not poll on a timer. `--until-settled`
+exits once the turn has ended and prints the session's status, with exit 0 whatever the status, as
+`sessions wait` does. Without it, the command follows the session until Ctrl-C.
+
 ### The backup: `orchestra api`
 
 `orchestra api GET "/sessions?limit=5"` makes a raw authenticated call — exactly `gh api`'s role — through

package/skills/orchestra-fdk/references/environment.md

@@ -1,7 +1,7 @@
 # Port a codebase's setup to Orchestra machines
 
-Step 8 of the orchestra-fdk skill, "Set up the machines", sends you here, and so does its step 3 for a new
-environment in an existing factory. When you finish, go back to the step that sent you.
+Phase 4 of the orchestra-fdk skill, "Build", sends you here, for a new factory and for a new environment in
+an existing factory. When you finish section 6, go back to phase 4 for the apply.
 
 An agent can fix, test or show a codebase only if its machine can install and run it. You find out how
 this team sets up their code, prove it on this computer first, write it into the factory, and apply it.
@@ -319,7 +319,7 @@ Orchestra Secret, and our network edge adds it to each model call, so no machine
 
 - For the gateway, `apply` creates the gateway key and its secret. The starter already declares them.
 - For a subscription token or a provider key, declare a Secret and a rule that adds it on the provider's
-  host, as step 6 of the orchestra-fdk skill says (orchestra skill, sections 6 and 7).
+  host, as phase 2 of the orchestra-fdk skill, "The model route", says (orchestra skill, sections 6 and 7).
 
 Ask the developer to revoke the `local-dev` gateway key, at **Settings › Gateway keys**, when local work is
 done.
@@ -332,6 +332,116 @@ fails and why. Report which tests ran and which could not. Then run `orchestra l
 Ask the developer to confirm the path you recommend, with your question tool. The mode you proved points
 to the path, as the table in section 2 says: a container machine to A, the host outpost to B.
 
+### The machine's runtime, by operating system
+
+An environment's `platform` is `{ os, arch, runtime }`, set when the environment is created. `runtime` never
+changes. On a provisioned environment it is `microvm` (the default) or `vm`. An enrolled environment is
+`host`: the team's own machine, as it is, with no network rules of ours.
+
+The setup script runs once, as root or as the machine's service account, on each new machine, before the
+agent arrives and before any code is cloned. It is at most 64 KiB. It has 10 minutes. The limit is fixed for
+now, and an environment cannot raise it. A worker that starts again on the same
+machine reuses the result it kept, and does not run the script again.
+
+#### Linux
+
+Most code: web, backend, mobile build tools, anything that runs in Docker.
+
+| Runtime and where it runs | Base image: what's in it | Sizes | Disks and shared volumes | Setup script | Home and continuity | Requirements and limits |
+|---|---|---|---|---|---|---|
+| `microvm`: a Kata micro VM on Kubernetes, amd64. `vm`: an EC2 Ubuntu VM, amd64 or arm64 | `microvm`: Debian with Node 24, Java 21 and 25, Python 3, a C and C++ build toolchain, git, the GitHub CLI `gh`, and Docker with Compose and Buildx (not started until the setup script starts it). `vm`: Ubuntu 24.04 with Node 24, git, and rootless Docker with Buildx, which runs from boot as the agent's user. The VM has no Java and no Compose plugin: install the ones the code needs in the setup script. Both carry the worker and the `claude`, `codex`, `pi` and `script` harnesses | `microvm`: 0.5, 1, 2, 4, 8, 16 or 32 CPU. `vm`: 2, 4 or 8 CPU. 2 GB of memory per CPU | `vm`: a 40 GiB root disk. Up to four extra disks (`disks`), such as `/var/lib/docker` and `/work`. Shared volumes (`volumeMounts`) on EFS, which every machine of an environment can mount together | Bash, run with `bash -e`. One exit code per step | A volume at `/home` keeps the agent's home across machines. Without it, nothing in `/home` outlives the machine | No Windows or macOS programs. A kernel of its own, an Android device or nested virtualization needs `vm` |
+
+#### Windows
+
+Code that builds or runs only on Windows: .NET Framework, WinForms, WPF, IIS, Windows-only tools.
+
+| Runtime and where it runs | Base image: what's in it | Sizes | Disks and shared volumes | Setup script | Home and continuity | Requirements and limits |
+|---|---|---|---|---|---|---|
+| `vm`: an EC2 Windows Server VM, amd64. Set `platform: { os: "windows", arch: "amd64", runtime: "vm" }` | Our image only: Windows Server 2025 Core, Node 24, Docker for Windows containers with the Containers feature, the worker, the `orchestra` command, and the `claude`, `codex`, `pi` and `script` harnesses. No git: install it in the setup script. A hosted Windows machine cannot start from another image | 4 or 8 CPU, 2 GB of memory per CPU | The image's 100 GiB root disk. No extra disks: remove `disks`. Shared volumes: not stated | PowerShell 5.1, run as the machine's service account. One exit code per step. Template: "A Windows setup script" below | The machine is parked when idle and keeps its disk, so the home (`C:\sf\home`) and `C:\work` stay. The setup script runs once per machine | Docker runs Windows containers only, for administrators only. A machine takes up to 15 minutes to start the first time |
+
+**Windows in three stages.** Guide a Windows team through these stages, in order. Write the stage you plan
+into `orchestra-factory-notes.md`.
+
+1. **Start on hosted Windows, with our image.** This proves the factory works, with nothing to run in the
+   team's own cloud. The setup script installs what fits in its 10 minutes: Git, and the small tools. A
+   larger toolchain, such as Visual Studio Build Tools or an old SDK, goes in the agent's first turn. The
+   machine is parked when idle and keeps its disk, so the next turn finds the toolchain installed. The agent
+   runs the install in the turn and waits for it: a park stops the VM and kills an install still running.
+   The machine is deleted after `ttl`, 2 hours by default, and a new one starts without the toolchain.
+2. **Then move to the team's own Windows image, through a compute provider in their cloud.** The benefit:
+   each machine starts with the whole toolchain installed, with no setup limit, and the team's licenses,
+   such as Visual Studio's, stay in their own image. The Launcher, the program the team runs in their
+   cloud, starts Windows VMs from the image its environment names. The Launcher runs on Azure (the
+   orchestra skill, section 18). The team bakes the image on Windows Server 2025 and adds their own
+   toolchain: git, MSBuild and .NET are theirs to install. Windows 11 is not supported, and a plain
+   captured Windows VM does not register. The image must contain these three parts:
+   - The worker's release package, for example at `C:\ProgramData\sfdk\worker\package`.
+   - The worker's Windows service, `SfdkWorker`. It runs `worker.exe run --root C:\ProgramData\sfdk\worker
+     --service` as LocalSystem. It is demand-start (`Manual`), not automatic. On a failure it restarts
+     three times, 2 seconds apart, and a clean stop with a non-zero exit code counts as a failure.
+   - The startup task `orchestra-azure-userdata`. It runs `azure-userdata.ps1` as SYSTEM at each boot
+     (`AtStartup`). The script writes the files that the VM's startup data carries, then starts
+     `SfdkWorker`.
+
+   Our image builds the same parts: `install-vm-runtime.ps1` and the image template
+   `infra/packer/azure-windows-runtime.pkr.hcl`. Under a Launcher, the image needs no WinDivert, no
+   redirect firewall rule, no Docker, no Node and no preinstalled harness: a harness installs itself on
+   its first turn, in about 60 seconds. Credentials are the team's to set on the VM (part C, "Tokens on a
+   compute provider's machines"). Our own image is in a public Azure gallery:
+   `/CommunityGalleries/orchestraworks-881a796f-0a84-4be1-af80-0a38564a406a/Images/runtime-win/Versions/0.0.136`
+   (Gen2). An environment that names no image boots its `Versions/latest`. Not released yet: a one-command
+   installer for a team's own image, the Launcher on AWS, and a team's own image on hosted Windows.
+3. **Then keep machines ready, for speed.** `standbyCapacity` on the agent (`Agent` in the kit) keeps
+   `count` machines started, set up and with the agent installed, on a schedule or always. A new
+   conversation then starts at once, with no wait for a Windows first boot. The platform refuses it only
+   for an enrolled environment or a `custom` harness, so it applies to hosted Windows and to a compute
+   provider. Proven on a compute provider's Windows VM: a new conversation got a ready machine, and its
+   turn started in 3.5 seconds. A standby minute is billed: the plan page shows the price.
+   `npx orchestra agents get <agent>` shows `standbyStatus`: how many machines are ready now, and why
+   fewer when that is so.
+
+#### macOS
+
+Code that needs Xcode, the iOS Simulator or another Apple tool.
+
+Not released yet: Orchestra launches no Mac. A Mac works only as the team's own enrolled machine
+(`host`), with the worker installed on it, no network rules of ours and no keys added at the edge. Agree it
+with the Orchestra team first (the orchestra skill, section 18).
+
+#### A custom image
+
+A team's own image, when the stock image plus a setup script is too slow or cannot hold the toolchain.
+
+- Build it `FROM` our runtime image, so it keeps the worker and the harnesses. The public name is
+  `public.ecr.aws/orchestraworks/runtime` (until AWS approves that alias: `public.ecr.aws/z8d3m6s5/runtime`).
+  Pin it by digest; the Orchestra team gives the current one.
+- Push it to the team's own registry. `Image.fromBuild` builds and pushes it at apply. The environment names
+  a pull key Secret in `imagePullCredential` (`provisionSpec.imagePullSecretId` on the platform), made with
+  `SecretValue.registryCredential(<user>, <password>)` or `SecretValue.ecrCredential(<key id>, <secret>)`.
+  The platform reads it at each machine create, and never gives it to the agent. The bug-fix starter's
+  `main.ts` shows the code.
+- Not released yet: a registry hosted by Orchestra.
+- A custom image applies to `microvm`. An EC2 VM starts from our machine image, not from a container image.
+
+#### On this computer
+
+`orchestra local` runs Linux containers only, on Docker Desktop, OrbStack or Docker Engine. On an
+Apple-silicon Mac it runs an `amd64` environment natively as `arm64` when the image carries that pair, and
+never by emulation. Docker set to Windows containers is refused.
+
+A Windows agent runs locally only as an enrolled machine: `orchestra outpost up --agent <id>` on a Windows
+PC, against the local environment (section 4, "Host outpost"). Use it to work out the build, run and test
+commands before the cloud.
+
+Locally the network edge does nothing: no egress rule is enforced, no key is added, and no certificate is
+re-signed. The cloud proves those.
+
+#### Which to pick
+
+Pick `microvm` when the code runs on Linux, with or without Docker. This is most code.
+Pick `vm` when the code needs Windows, an Android device or a kernel of its own.
+Pick `host` when the code must run on the team's own machine, such as a Mac.
+
 ### A. Containers on Linux
 
 Choose A when the code and its services run on Linux, in Docker, Docker Compose, or a setup script. Most
@@ -349,7 +459,7 @@ agent can run the team's own `docker compose up` unchanged.
    machine's processes, the agent included, read every value.
 3. Put each dev server's port in `PORTS`, with a short name. The agent can then show the app at a
    *machine endpoint*, a web address that only signed-in members of the organization can open.
-4. Write the app's own settings files (`.env.local`) into the Set up item's instructions, because the code
+4. Write the app's own settings files (`.env.local`) into the Set up item's description, because the code
    is not on the machine when the setup script runs. Put only local or test values there. A real secret
    becomes a Secret plus a rule that adds it.
 5. Choose the size by what CI uses for the same work. The template's sizes are fixed per agent: lg is
@@ -358,6 +468,28 @@ agent can run the team's own `docker compose up` unchanged.
    the inner Docker's images across machine starts (next part).
 7. Not released yet: `workingDirectory`, the folder where every conversation starts. Today each agent clones
    or uses its code under `/work` in its own first turn, as the starter's agents do.
+8. To keep the agent's home, such as a harness sign-in, across machines, mount one volume at `/home` on
+   every environment that shares it. Make the volume once with `npx orchestra volumes create`, then add
+   `volumeMounts: [{ volume: Volume.fromSlug(factory, "<slug>"), mountPath: "/home" }]`. Without it,
+   nothing in `/home` outlives the machine.
+
+#### Network
+
+Egress starts open, and stays open for the first run: `EgressPolicy.allowAll()`. Any host is reachable, and
+only the hosts that need a key, such as the model gateway, have rules that add one. Never close it while the
+factory is being set up.
+
+Tightening is a later, optional step, after the factory works and the developer asks for it:
+
+1. Start from `EgressPolicy.denyAll()`. A host that no rule allows is refused.
+2. Add `applyPreset(egressPreset.softwareDevelopment())`: package and container registries, and reads
+   from common services, with no key.
+3. Keep `routeModelsViaGateway(...)` or the model key's rule, and every token or connection rule.
+4. Add one `allow` rule for each other host the agents reach, with `priority: 100` and the methods it needs.
+
+Prove the closed list on Orchestra's cloud, not locally: a local run enforces no egress rule ("On this
+computer" above). Apply the tightened policy, then ask an agent to run the build and the tests once on a cloud
+machine. A refused host shows as `destination is not allowed` (`troubleshooting.md`).
 
 #### Setup script or a baked image
 
@@ -392,27 +524,152 @@ Choose B when the code needs a particular kernel or operating system.
 
 - **Windows:** possible. Set `platform: { os: "windows", arch: "amd64", runtime: "vm" }` on the
   environment. A Windows machine is a full EC2 virtual machine with 4 or 8 CPU. Docker data disks are not
-  available on Windows, so remove `disks` and the Docker setup. The Linux `setup.sh` cannot run there. Ask the Orchestra team
-  how a setup script runs on Windows before you rely on one.
+  available on Windows, so remove `disks` and the Docker setup. The Linux `setup.sh` cannot run there: write
+  a PowerShell script from "A Windows setup script" below. Follow "Windows in three stages" in section 5.
 - **Linux on a full VM:** possible with `runtime: "vm"`, at 2, 4 or 8 CPU.
 - **macOS:** only as the team's own Mac, enrolled with the worker. Say what that needs before you offer it
   (the orchestra skill, section 18), and agree it with the Orchestra team first.
 
-### C. The team's private network
-
-Choose C when development needs services or data inside their VPN or their own cloud.
-
-Orchestra's machines cannot reach a private network today. The planned answer is the *Launcher*, which
-runs machines inside the team's own cloud; it does not exist yet, and there is no Azure support. Tell the
-developer:
-
-- what their code needs from the private network, host by host;
-- that this needs a later Orchestra release, or one of their Macs or Linux servers enrolled as a machine
-  (the orchestra skill, section 18);
-- that they can still see a first fix today on the todo sample, or on the parts of the code that need no
-  private service.
-
-Write down what is missing and stop here. Report it to the developer, and go back to the orchestra-fdk skill.
+### A Windows setup script
+
+Tried by us: not yet.
+
+A Windows machine runs the setup script with PowerShell 5.1 (`powershell -NonInteractive -NoProfile
+-ExecutionPolicy Bypass -File setup.ps1`), as the worker's service account, once per machine. A parked VM that
+starts again does not run it again. A new VM does, for example after `ttl` deletes the old one. So write each
+step so that it can run again: check before you install, as the template does. Start from this template. Keep the steps in this order, and give each one its own exit code. The work folder is
+`C:\work\code`. The setup script does not clone the code. It runs before any code host key exists, so a
+clone of a private repository fails, and the machine start fails with it. The agent clones the code in its
+turn, from a git bundle or a public address (`phases/5-prove.md`, section 1).
+
+```powershell
+$ErrorActionPreference = 'Stop'
+$ProgressPreference = 'SilentlyContinue'
+[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
+
+# 10: the egress edge's certificate authority is trusted machine-wide. The worker hands the script its path.
+$ca = $env:GIT_SSL_CAINFO
+if ($ca) {
+  try {
+    $cert = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2($ca)
+    if (-not (Test-Path "Cert:\LocalMachine\Root\$($cert.Thumbprint)")) {
+      Import-Certificate -FilePath $ca -CertStoreLocation Cert:\LocalMachine\Root | Out-Null
+    }
+  } catch { Write-Output "trusting the edge authority failed: $_"; exit 10 }
+}
+
+# 11: the work folder, for the service account and the administrators only.
+try { New-Item -ItemType Directory -Force -Path C:\work | Out-Null } catch { exit 11 }
+icacls C:\work /inheritance:r /grant:r '*S-1-5-18:(OI)(CI)F' '*S-1-5-32-544:(OI)(CI)F' | Out-Null
+if ($LASTEXITCODE -ne 0) { exit 11 }
+
+# 12: Git for Windows. Set the version the team uses.
+$git = 'C:\Program Files\Git\cmd\git.exe'
+if (-not (Test-Path $git)) {
+  $version = '<version, such as 2.47.1>'
+  $installer = 'C:\work\git-setup.exe'
+  try {
+    Invoke-WebRequest -UseBasicParsing -OutFile $installer `
+      -Uri "https://github.com/git-for-windows/git/releases/download/v$version.windows.1/Git-$version-64-bit.exe"
+  } catch { exit 12 }
+  $run = Start-Process -FilePath $installer -ArgumentList '/VERYSILENT', '/NORESTART', '/NOCANCEL', '/SP-' -Wait -PassThru
+  if ($run.ExitCode -ne 0) { exit 12 }
+}
+# For the rest of this script only. The agent does not get this PATH.
+$env:Path = "C:\Program Files\Git\cmd;$env:Path"
+
+# 13: git trusts the Windows certificate store, for every process on the machine.
+& $git config --system http.sslBackend schannel
+if ($LASTEXITCODE -ne 0) { exit 13 }
+
+# 14 and on: the team's toolchain that fits in the time limit, one exit code per step.
+```
+
+Why each step is there:
+
+- `$ErrorActionPreference = 'Stop'` stops on a failing PowerShell command, but not on a failing program such as
+  `icacls` or `git`. So each program call is followed by a `$LASTEXITCODE` check that exits non-zero.
+- The worker already imports the edge's authority into `Cert:\LocalMachine\Root` before the script runs, and
+  logs a failure without stopping. Step 10 checks it, and imports it when it is missing. The worker sets each
+  certificate variable a harness reads, `GIT_SSL_CAINFO` among them, to the authority's file.
+- PowerShell 5.1 does not always offer TLS 1.2, so a download can fail before it reaches the edge.
+- The Windows image has no git.
+- The agent does not find git on its PATH. Its PATH is the worker's, fixed when the worker started, before
+  the setup script ran. The installer's change to the machine PATH and the script's `$env:Path` do not
+  reach it. So the agent calls git by its full path, `C:\Program Files\Git\cmd\git.exe`. Write this in the
+  agent's instructions or in the codebase skill.
+- Git for Windows reads its own certificate bundle, not the Windows store. The worker sets `GIT_SSL_CAINFO` for
+  the setup script and the harness only, so git run any other way fails on the edge's certificate. The
+  `schannel` setting makes every git on the machine read the Windows store.
+- The SIDs `S-1-5-18` (the service account, LocalSystem) and `S-1-5-32-544` (the administrators) work on every
+  language of Windows, where the account names do not. On Windows the agent runs as the worker's account.
+- The setup script has 10 minutes, and the limit is fixed for now. A toolchain such as Visual Studio Build
+  Tools can take 10 to 20 minutes to install. Leave such an install to the agent's first turn: a Windows
+  machine is parked when idle and keeps its disk, so it stays installed. The agent waits for the install in
+  the turn: a park kills an install that is still running. A process the setup script leaves running is
+  killed the same way. For machines that start with it
+  installed, use the team's own image ("Windows in three stages", stage 2).
+- The output is kept as it is. Never print a token.
+
+### C. Where the machines run, when the code needs private services
+
+Choose here when development needs a database, internal APIs or a package feed inside the team's network
+or cloud. List what the code needs, host by host, before you choose.
+
+| | Hosted | A compute provider in their cloud | Their own machine | The whole platform in their cloud |
+|---|---|---|---|---|
+| Benefit | The simplest start. Nothing to run. Keys added at our network edge, machine endpoints and views, machines kept ready, and we keep it running. | Keeps their setup, networks, images and private services inside their own cloud, under their own account and controls. | Their own machine or network, as it is. | Nothing leaves their cloud. |
+| What reaches what | Our machines reach their services over the internet, through the network edge | Their Launcher asks our platform for orders over HTTPS. Their machines connect out to our platform. Nothing connects in. | The worker on their machine connects out to our platform | All inside their cloud |
+| Where keys live | Secrets, added at our network edge | On their machines, set by their own boot step. No network edge of ours stands in front of their machines yet | On their machine | In their cloud |
+| Where files rest | Our object store (S3) | Not stated yet | Not stated yet | Their cloud |
+| Setup | None | Make a compute provider record, deploy the Launcher template to their Azure subscription, name the record in `provisionSpec.computeProviderId` | Enroll the machine (`orchestra worker enroll`) | An installation of the platform's Helm chart |
+| Status | Released | Released on Azure. Not released yet: AWS | Released | Not released yet |
+
+Pick hosted when the private services can be reached over the internet with a key.
+Pick a compute provider when the services must stay inside their cloud, and they use Azure.
+Pick their own machine when the code needs one machine they already run, such as a Mac.
+
+Tell the developer the benefit of each choice first. The limits are for troubleshooting. Do not lead with
+them when you present the choice.
+
+Cannot do:
+
+- Hosted: reach a service that is not on the internet.
+- A compute provider: run on AWS or Google Cloud; run on arm64; keep `/home` on a Kata pod target; add
+  keys at our network edge.
+
+Tokens on a compute provider's machines:
+
+- The team manages every credential on their own machines. The platform delivers none there.
+- The model sign-in goes in the worker service's own environment, by harness:
+  - `claude` with a Claude subscription token: `ORCHESTRA_WORKER_CLAUDE_OAUTH_TOKEN`.
+  - `claude` with an Anthropic API key or an Orchestra gateway key: `ANTHROPIC_API_KEY`. This value
+    replaces the placeholder that our image sets. With a gateway key, keep the agent's model gateway on:
+    the platform sets the gateway address.
+  - `codex`: `ORCHESTRA_WORKER_OPENAI_API_KEY`, or `ORCHESTRA_WORKER_CODEX_PERSONAL_ACCESS_TOKEN`.
+  - On Windows, the worker service is `SfdkWorker`, and its environment is the service's `Environment`
+    registry value.
+- Other tokens, such as for git, a package feed or an Azure DevOps personal access token: the team's own
+  boot step sets them. For example, the step reads their Key Vault with a managed identity on the VM.
+- The worker reads its environment when its service starts. So the boot step runs before the worker
+  starts, or restarts the worker service after it sets the values. On our Windows image, the startup task
+  `orchestra-azure-userdata` starts `SfdkWorker` at each boot.
+- Do not put a token in the environment's `env` (`provisionSpec.env`). The platform stores it, an
+  environment read returns it, and it travels in plain text in the VM's startup data.
+- The Launcher attaches no managed identity to the VMs it creates. The team's automation finds the VMs by
+  two tags: `orchestra-launcher` holds the compute provider record's id, and `orchestra-machine` holds
+  the machine's id. Not released yet: a managed identity attached when the Launcher creates a VM.
+- Never bake a credential into an image: that is not supported.
+- Not released yet: our network edge for machines in the team's own network, which adds keys from
+  Secrets as it does for hosted machines.
+
+The Launcher's VM targets use the `Dsv5` size family by default. A subscription with no `Dsv5` capacity
+sets `vmSizeFamily: Dsv6` on each VM target in the Launcher's settings.
+- Their own machine: hold network rules; add keys at the edge; start a machine on demand.
+
+When no choice fits, write down what is missing and stop here. Report it to the developer, and go back to
+the orchestra-fdk skill. They can still see a first fix on the todo sample, or on the parts of the code
+that need no private service.
 
 ## 6. Write and check
 
@@ -421,38 +678,34 @@ Write down what is missing and stop here. Report it to the developer, and go bac
 2. In `<factory>`, run `npm run typecheck`, then `npx orchestra fdk synth`. The starter is one program, at the folder's
    root.
 3. Read `<factory>/fdk.out/plan.json`. Every environment has your setup script, ports and settings, and
-   the model rule from step 6 of the orchestra-fdk skill: the `model-gateway` rule,
-   or a Secret's rule on the provider's host. On a new factory, no environment has a Bitbucket or Jira rule
-   yet: those come with the tokens, in step 12 of the orchestra-fdk skill. On an existing factory, with its
-   inputs loaded, the rules it has now stay as they are.
+   the model rule of the orchestra-fdk skill's phase 2: the `model-gateway` rule, or a Secret's rule on the
+   provider's host. On a new factory, no environment has a code host or tracker rule yet: phase 3 adds them
+   after the first run. On an existing factory, with its token file loaded, the rules it has now stay as
+   they are.
 4. Write `ENVIRONMENT.md` in `<factory>`: what you found and where, the mode you proved in and its result
    for each success criterion, the commands, every outbound attempt the proof logged, and what is still
    unknown.
 
 **Check:** the typecheck and the synth pass, and the plan is as in item 3. Go back to the orchestra-fdk
-step that sent you for the apply.
+skill's phase 4 for the apply.
 
 ## 7. The cloud
 
 The cloud is the fallback when no local mode can run. It is also the confirmation after the local proof:
-the Manager Agent's "Set up" item, which step 10 of the orchestra-fdk skill starts. It proves what only the
-cloud can: the micro VM, Docker, the network rules and the tokens. The Engineer Agents' machines cannot clone from
-Bitbucket, so the Set up item also proves the tests run from a git bundle.
+the Set up item, which phase 5 of the orchestra-fdk skill starts. It proves what only the cloud can: the
+micro VM, Docker, the network edge and the machine endpoints. The Engineer Agents start each item from a git
+bundle, so Set up also proves the tests run from one.
 
 It is slower. Each try is an apply plus a machine start, and access problems show one at a time.
 
-To prove in the cloud, write the environment as in sections 5 and 6, apply it, and run Set up with the git
-bundle. Keep the safety rule:
+To prove in the cloud, write the environment as in sections 5 and 6, apply it, and run Set up. Egress stays
+open. Keep the safety rule this way:
 
-1. For the proof, set the environment's default action to `deny`. Allow only the package registries and
-   image registries the install uses, and keep the `model-gateway` rule. Calls to the Orchestra platform
-   skip these rules.
-2. Use only local settings in the Set up item's instructions.
-3. Ask the Manager Agent to report every refused host, and to note any production host it sees and
-   continue.
+1. Use only local settings in the Set up item's description.
+2. Ask the Manager Agent to note any production host it sees in a setting or a log, and to continue.
 
-When a step fails, fix it here, prove the fix locally if a local mode runs, apply again, and assign the
-item again.
+When a step fails, fix it here, prove the fix locally if a local mode runs, apply again, and assign Set up
+again. `troubleshooting.md` names each failure.
 
 ### The model in the cloud: subscription, model gateway, or own key via the vault
 
@@ -515,8 +768,9 @@ Use the orchestra skill to build an answer for a case the paths do not cover. Ne
 yet" lines. The sections this work needs:
 
 - Section 4: environments, machines, sizes, images, setup scripts, disks, Windows and full VMs.
-- Section 5: network rules, their live effect on running machines, and commissioning.
+- Section 5: network rules, and their live effect on running machines.
 - Section 6: secrets, and where their values come from.
 - Section 7: the model gateway rule every environment needs.
-- Section 17: connections, the later option for the code host and the tracker.
+- Section 17: connections. The files under `references/integrations/` say how to give access to each
+  service.
 - Section 18: the team's own machines, the local environment, and private networks.

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.