@orchestraworks/cli 0.5.5 → 0.5.8

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

@@ -57,17 +57,19 @@ path from `orchestra fdk init` to a first fix, and the traps on the way.
 
 Every **managed construct** takes `(scope, id, props)` — the scope it hangs off, an id unique among
 its siblings, and its props. The one exception is the root: `Factory` takes props only,
-`new Factory({ name, project? })`, because there is nothing above it to scope to. It is required, and
+`new Factory({ name })`, because there is nothing above it to scope to. It is required, and
 one synth run has exactly one factory — a second root throws.
 
 ```ts
-import { Agent, EgressPolicy, Environment, Factory, Image, Secret, SecretValue, bearer, egressPreset } from "@orchestraworks/cli";
+import { Agent, EgressPolicy, Environment, Factory, Image, Secret, SecretValue, egressPreset } from "@orchestraworks/cli";
 
 const factory = new Factory({ name: "acme-support" });
 
-const openaiKey = new Secret(factory, "openai-api-key", {
+new Secret(factory, "openai-api-key", {
   name: "OpenAI API key",
   value: SecretValue.fromEnv("OPENAI_API_KEY_VALUE"), // read from env at apply — never in the plan
+  hosts: ["api.openai.com"], // where the edge presents it
+  injection: { headers: [{ name: "Authorization", value: "Bearer ${secret}" }] }, // how
 });
 
 const runtime = new Environment(factory, "runtime", {
@@ -79,8 +81,7 @@ const runtime = new Environment(factory, "runtime", {
     .applyPreset(egressPreset.softwareDevelopment()) // ready-made reachability — reach for a bundle first
     .allow("openai-model-api", {
       hosts: ["api.openai.com"], // …and hand-write only what no bundle covers
-      priority: 300,
-      credential: bearer("Authorization", openaiKey),
+      priority: 300, // a rule opens the network; it carries no credential
     }),
 });
 
@@ -143,16 +144,16 @@ deletes.
 
 ### References: pass the object, there is no `.ref`
 
-Twelve resource families can be *referenced* by another construct, and each one has an interface `IX`
-(`IAgent`, `IEnvironment`, `ISecret`, `IGatewayKey`, `ISkill`, `IWorkflow`, `IPipeline`, `IProject`,
-`IVolume`, `IConnection`, `IConnector`, `IComputeProvider`); every reference-accepting prop is typed by that interface. Passing the
+Fourteen resource families can be *referenced* by another construct, and each one has an interface `IX`
+(`IAgent`, `IEnvironment`, `ISecret`, `IGatewayKey`, `ISkill`, `IWorkflow`, `IPipeline`, `ITeam`, `IRole`,
+`IPolicy`, `IVolume`, `IConnection`, `IConnector`, `IComputeProvider`); every reference-accepting prop is typed by that interface. Passing the
 construct object *is* passing the reference — there is no `.ref` indirection, no id string to thread
 through, and no plain object literal that will do instead. The three constructs nothing ever points
 *at* — `Trigger` (a routing rule), `ModelProviderKey` (read only by the model gateway,
 server-side) and `Factory` (the root) — have no `I` interface, because there is no prop anywhere
 that takes one.
 
-All twelve of those extend **`IResource`**, the identity base. `IResource` is one internal producer
+All fourteen of those extend **`IResource`**, the identity base. `IResource` is one internal producer
 method (`_resourceId()`), not a public field, and that is deliberate: an interface of nothing but
 `readonly agentId: string` would be satisfied by the bare literal `{ agentId: "x" }`, so requiring a
 method is what makes "you must hold a real reference" a compile-time check rather than an intention.
@@ -160,7 +161,7 @@ method is what makes "you must hold a real reference" a compile-time check rathe
 registry coordinate, not a platform row with an id and a slug.
 
 **The id-or-slug rule.** Each `IX` names its reference property after the resource — `agentId`,
-`environmentId`, `secretId`, `gatewayKeyId`, `skillId`, `projectId`, `workflowId`, `volumeId`,
+`environmentId`, `secretId`, `gatewayKeyId`, `skillId`, `teamId`, `roleId`, `policyId`, `workflowId`, `volumeId`,
 `connectionId`, `connectorId` — and **every one of them accepts a platform id or a slug
 interchangeably**. Ids always contain `_` and tenant slugs never do, so a key matches at most one of
 the two; global catalog rows are seeded with slug = id (`skill_zendesk`), so their single key is both
@@ -168,6 +169,37 @@ at once. This also means `Agent.fromId` still resolves a slug and `Agent.fromSlu
 id — the platform lookup is shape-opaque. Whichever you write, the platform stores the id and reads
 return it, so `orchestra fdk apply` and `orchestra fdk diff` resolve every reference to its id before they send or compare.
 
+### Teams, roles and an agent's team memberships
+
+A *team* is a group inside the organization, and every row sits in one. Every organization has the team
+**Shared**; a construct that names no `team:` is created in it, so a program that declares no team puts
+everything in Shared. `team:` is a prop, never part of the construct path, so setting it changes no slug.
+A row's team is fixed when the row is made: a live row in another team is `refused`, never moved.
+
+```ts
+import { Agent, Role, Team, Policy } from "@orchestraworks/cli";
+
+const mobile = new Team(factory, "mobile", { name: "Mobile", assignment: "AGENT_FIRST" });
+const reviewer = new Role(factory, "reviewer", { name: "Reviewer", policies: [Policy.fromId(factory, "pol_01jq…")] });
+new Agent(factory, "triage", {
+  // …
+  team: mobile,
+  memberships: [
+    { team: mobile, role: Role.managed("role_managed_agent_worker") },
+    { allTeams: true, role: reviewer },
+  ],
+});
+```
+
+- `Team.fromSlug(scope, "shared")` or `Team.fromId` names a team this program does not manage.
+- `Role.managed(slug)` names a managed role by slug; `new Role` declares a custom role over policies.
+- An agent's `memberships`, when declared, is its whole set of team-membership rows: each row is one role
+  at one team, or one role at all teams. Apply leaves the rows the platform minted at the agent's create
+  alone. A person's rows are never declared in code; give them in the console or with
+  `orchestra team-memberships create`.
+- Apply writes a team, a custom role or an all-teams row only with a key that holds Owner or Admin at all
+  teams, and a team's rows with Admin at that team. A weaker key sees that row `refused` in `diff`.
+
 ### Consuming what you do not manage
 
 Importers resolve at apply and are never created or mutated:
@@ -431,24 +463,24 @@ orchestra fdk apply    # reconciles the platform to the synthesized desired stat
   and an informational orphan report, plus — when the plan would write credential bytes — the same
   value-free sensitive block `apply` prints, row for row (`diff` says "would", `apply` says "will").
   It mutates nothing and never prompts. `refused` means the
-  resource already exists but under a different project than the one your factory declares: a project
-  placement is *identity*, like a slug, so orchestra never moves it — `apply` stops at that resource
+  resource already exists but in a different team than the one your factory declares (a row that names no
+  `team:` is declared in Shared): a team placement is *identity*, like a slug, so orchestra never moves it — `apply` stops at that resource
   instead. **The printed message names the remedy for that specific kind — follow it rather than
   guessing**, because the remedies are not interchangeable. A kind that has an importer (agent,
   environment, skill, ordinary secret, connector, connection) can keep its live placement and be
-  *referenced* instead of declared, or be redeclared under a new slug in the intended project. A kind
+  *referenced* instead of declared, or be redeclared under a new slug in the intended team. A kind
   that has none (gateway key, trigger) cannot be referenced, so its two remedies are a
-  new slug in the intended project, or dropping the declaration entirely and leaving the live row
+  new slug in the intended team, or dropping the declaration entirely and leaving the live row
   untouched. A gateway key's paired secret is never offered for import in any state — a conflicted pair
   is redeclared under new slugs for both members, or dropped for both. **A new slug is a replacement,
-  never a move**: it creates a fresh row in the intended project and leaves the existing one exactly
+  never a move**: it creates a fresh row in the intended team and leaves the existing one exactly
   where it is, untouched, for you to reference or clean up.
 - **`apply`** prints the resolved-organization banner and the approval-policy banner, then — at its
   default approval level — renders the whole pending change-set as a read-only pre-flight and takes
   **one confirmation before anything is built or written** (next section). Only after that does it
   build and push any `Image.fromBuild` images, gate pending credential writes behind their own
-  consolidated confirmation, and reconcile in dependency order — project → secrets → connectors →
-  connections → environments → skills → agents → pipelines, then workflows and each pipeline's workflow
+  consolidated confirmation, and reconcile in dependency order — teams → custom roles → secrets → connectors →
+  connections → environments → skills → agents → pipelines → agents' team memberships, then workflows and each pipeline's workflow
   entries, then triggers — writing `fdk.out/result.json`.
 - **`plan.json` is preview-only.** `apply` always re-synthesizes from code and deletes any stale
   on-disk plan first, so a committed or hand-edited plan is never trusted as state. Re-running apply
@@ -484,7 +516,7 @@ default to `sensitive-only` instead, because typing the command already names th
 **The gate is change-sensitive, so a converged factory stays silent.** Re-applying with nothing to
 change asks nothing at all — the gate fires on an actual pending change, never on a declaration
 count — so idempotent re-applies keep working. Rows that would be *refused* before writing anything
-(a project-identity conflict, an unset credential source) are not part of what you approve: they
+(a team-identity conflict, an unset credential source) are not part of what you approve: they
 print in their own "blocked — will fail, not approved here" section, each carrying the remedy for
 that specific kind, and reconcile's own error is what you act on.
 
@@ -522,8 +554,9 @@ token the platform mints. The **Claude sign-in recipe** is the one to copy when
 on a person's Claude subscription token rather than an API key:
 
 ```ts
-const claudeSignIn = new Secret(factory, "claude-sign-in", {
+new Secret(factory, "claude-sign-in", {
   value: SecretValue.fromEnv("ORCHESTRA_FDK_CLAUDE_CODE_OAUTH_TOKEN"),
+  hosts: ["api.anthropic.com"],
   injection: {
     headers: [{ name: "authorization", value: "Bearer ${secret}" }],
     removeHeaders: ["x-api-key"], // stripped before injection
@@ -533,7 +566,7 @@ const claudeSignIn = new Secret(factory, "claude-sign-in", {
 // …in the Environment's props:
 env: { CLAUDE_CODE_OAUTH_TOKEN: "software-factory-egress-placeholder", ANTHROPIC_API_KEY: "" },
 egress: EgressPolicy.allowAll()
-  .allow("claude-sign-in", { hosts: ["api.anthropic.com"], priority: 300, credential: claudeSignIn }),
+  .allow("claude-sign-in", { hosts: ["api.anthropic.com"], priority: 300 }),
 ```
 
 It injects `authorization` and nothing else. **Never inject an `anthropic-beta` header**: an injected
@@ -579,14 +612,14 @@ which the harness would otherwise send instead.
 - **`fromGatewayKey` is the one source whose value the platform mints.** It pairs this Secret to a
   `GatewayKey` you declare in the same factory — `new GatewayKey(factory, "model-gateway-key", props)`,
   whose only props are `slug`, `displayName`, `monthlyCreditCap` and `labels` — so apply mints the
-  key and writes the token it shows *exactly once* straight into this Secret, which you then bind at
-  egress like any other. It is legal only as the whole top-level value of exactly one Secret:
+  key and writes the token it shows *exactly once* straight into this Secret, which the edge then
+  adds on its `hosts` like any other. It is legal only as the whole top-level value of exactly one Secret:
   nesting it inside another recipe, or a key with zero or two Secrets, is a synth error, and there
   is no importer because an existing key's token is unrecoverable. Rotation is new-slug-only.
 - A **`ModelProviderKey`** is the other credential you can declare: your organization's own key for
   one model provider (`{ modelProvider: "fireworks", credential: SecretValue.fromEnv(NAME) }`),
   read only by the model gateway. It reuses the same recipe machinery, including `fromCommandLine`,
-  but it is **not** a `Secret` — write-only, unbindable at egress, and referenced by nothing.
+  but it is **not** a `Secret` — write-only, never added at egress, and referenced by nothing.
 - Secret bytes are **never serialized**: not into `plan.json`, `graph.mmd`, diff output, apply logs,
   `result.json`, errors, or stack traces. They are never printed **in full** either — with one named
   exception: the `fromCommandLine` reader masks every character while you type, then on Enter shows
@@ -615,9 +648,11 @@ which the harness would otherwise send instead.
   suppresses it and none can supply it either, so a headless apply of a `fromCommandLine`
   declaration refuses at *every* level and tells you to run from a terminal or change the source —
   it never recommends a policy lever that could not clear it.
-- Binding a secret to an egress rule: pass the bare `Secret` when it carries an `injection` recipe
-  (the recipe supplies the headers), or use `bearer(header, secret)` / `basic(...)` / `header(...)`
-  for one-header bindings, or `inject(secret, recipe)` for a binding-owned recipe.
+- Presenting a secret on the network: the `Secret` itself declares `hosts` (where: an exact host,
+  `*.suffix`, or `*`) and an `injection` recipe (how: the headers it sets, reading `${secret}`, or
+  `${secret.<field>}` for a `SecretValue.fields` value). Egress rules carry no credential, so a rule
+  that passes `credential` or `credentials` is a synth error; a Secret with no `hosts` is presented
+  nowhere.
 
 ## How the agents reach a model
 
@@ -726,8 +761,8 @@ An environment's `egress` is a policy you build up from one of **two starting po
 - **`EgressPolicy.denyAll()`** refuses every host no rule allows.
 - **`EgressPolicy.allowAll()`** allows every host no rule refuses.
 
-Rules fold onto either one the same way: a credentialed allow rule still injects its credential at the
-edge, and a deny still refuses.
+Rules fold onto either one the same way: a rule only opens or closes the network, a credential still goes
+only to the hosts its own `hosts` cover, and a deny still refuses.
 
 Most of what an agent needs to reach arrives ready-made as a **bundle** — a list of rules folded onto
 the policy by one `applyPreset(...)` call — so **reach for the bundles first** and hand-write allow/deny
@@ -738,21 +773,22 @@ import { EgressPolicy, egressPreset } from "@orchestraworks/cli";
 
 // …in the Environment's props:
 egress: EgressPolicy.denyAll()
-  .applyPreset(github.egressPolicy())               // credentialed: this connection's API + git transport
+  .applyPreset(github.egressPolicy())               // this connection's API and git transport hosts
   .applyPreset(egressPreset.softwareDevelopment())  // anonymous: registries, public git, SaaS reads
   .deny("no-slack", { hosts: ["slack.com"] }),      // …minus one, at the deny default's 900
 ```
 
-**The ownership rule is one line: anonymous rules ride presets, credentialed rules ride the
+**The ownership rule is one line: anonymous rules ride presets, a provider's own hosts ride its
 connection.** `egressPreset.softwareDevelopment()` is a static, **credential-free** bundle anyone may
 apply — package and container registries (npm, PyPI, Maven Central, Go, crates.io, Gradle's plugin
 portal and wrapper chain, Docker Hub, GHCR), public git reads on GitHub, and read access to widely used
 development services (Atlassian, Zendesk, PagerDuty, Datadog, Sentry, Slack, Notion, Statuspage,
 Linear). It is about *reachability*, never credentials: every row is `GET`/`HEAD` bar three deliberate
-path-scoped `POST`s, so git *push* stays closed and a service still needs whatever auth a connection
-bundle or a Secret-bound rule supplies. Anything that does need a credential is the **connection's own**
-surface, `connection.egressPolicy()` — compiled from the provider catalog rather than written out rule
-by rule, and available identically on a managed `Connection` and on every import.
+path-scoped `POST`s, so git *push* stays closed and a service still needs the credential a connection or a
+Secret with `hosts` supplies. A provider's own API and git hosts are the **connection's own** surface,
+`connection.egressPolicy()` — compiled from the provider catalog rather than written out rule by rule, and
+available identically on a managed `Connection` and on every import. Its rules open the network only; the
+connection's `hosts` decide which of those hosts get its credential.
 
 **A bundle is not a new concept.** Every entry lands as an ordinary allow rule, where the call sits in
 the chain, so `plan.json`, `orchestra fdk diff` and the live environment show only rules — there is nothing about
@@ -907,7 +943,7 @@ new Trigger(factory, "bug-intake", {
 - **A rule's text is Liquid over the item**: `workItem`, `stage`, `pipeline`, `connection` and, in a
   `changed` rule, `old`. The `event` root exists only in a rule firing on an outside event
   (`activity("INBOUND_EVENT", …)`); anywhere else, synth refuses it, because no other rule has one.
-- **References are slugs or constructs.** Apply resolves every agent, group, stage, connection and
+- **References are slugs or constructs.** Apply resolves every agent, team, stage, connection and
   pipeline a rule names to its id before it compares, so an unchanged factory writes nothing.
 - **A workflow's pipeline is fixed.** Moving the rules to another pipeline means a new slug; apply
   refuses the change and says so.
@@ -985,7 +1021,7 @@ PLATFORM COMMANDS   orchestra <noun> <verb> — nouns match API paths exactly
   Build & run
     agents  environments  sessions  machines  compute-enrollments
     pipelines  work-items  workflows  decisions  skills
-    files  artifacts  volumes  projects  room-tokens  compute-providers
+    files  images  artifacts  volumes  room-tokens  compute-providers
   Events & wiring
     triggers  events  deliveries  connections  connection-intents
     install-links  connectors  providers
@@ -996,7 +1032,7 @@ PLATFORM COMMANDS   orchestra <noun> <verb> — nouns match API paths exactly
     secrets  api-keys
   Organization
     organizations  organization-memberships  organization-invitations  users
-    groups  user-grants  service-accounts  roles  policies  me
+    teams  team-memberships  user-grants  service-accounts  roles  policies  me
   Observability
     metrics  dashboards  health
 ```
@@ -1070,17 +1106,19 @@ itself a credential.
 An agent running inside a machine types the **same commands** as an operator at a workstation. There
 is no separate agent CLI, no agent-only spelling, and nothing for you to author differently:
 
-- **The agent holds no token.** Its machine is declared as edge-injected, so the CLI sends the request
-  *bare* to the platform's public HTTPS name (`PLATFORM_BASE_URL`), and the egress edge stamps the
-  authorization onto it on the way out. Credential material never enters the machine. Setting
-  `ORCHESTRA_API_TOKEN` deliberately still wins — the edge leaves an `Authorization` header the client
-  supplied alone.
+- **The agent sets no token.** The worker writes the agent's own short-lived platform token to a file,
+  renews it before it expires, and sets `ORCHESTRA_API_TOKEN_FILE` to that file's path on each agent
+  process. The CLI reads the file before each request and sends its token to the platform's public HTTPS
+  name (`PLATFORM_BASE_URL`), with no organization header, because the token names its organization.
+  The token works only while the agent is placed on that machine. A token set in `ORCHESTRA_API_TOKEN`
+  comes before the file. On a machine behind the platform's network edge, the edge replaces the
+  `Authorization` header of each call with a token for the same agent, whatever token the call carried.
 - **IAM is the only difference between principals.** The same command run by an agent and by a human
   differs only in what their grants allow; a refusal is a permission error naming the action, never
   an instruction to log in (there is nothing in a machine to log into).
 - **The factory loop works there too.** `synth`, `diff` and `apply` (and `grant`) are ordinary
   platform callers, so an agent can preview and apply a factory from inside its machine with no token
-  and no organization set — the same bare send, judged by the same IAM.
+  and no organization set — the same token file, judged by the same IAM.
 - **Triggers are runtime wiring: agents observe it, they do not author it.** Declare them in code
   (`new Trigger(factory, …)`) or have an explicitly granted principal create them. The managed
   worker role deliberately carries **no** trigger-authoring capability, so `triggers create`
@@ -1160,8 +1198,8 @@ The kit's full reference is `docs/REFERENCE.md` at the root of the package, two
 `skill_link=.claude/skills/orchestra-fdk; [ -e "$skill_link" ] || skill_link=~/.claude/skills/orchestra-fdk; cat "$(realpath "$skill_link")/../../docs/REFERENCE.md"`
 (use `.agents/skills/orchestra-fdk` and `~/.agents/skills/orchestra-fdk` for Codex). It ships inside the package, so it
 is already on disk in any project that has orchestra installed, wherever the install landed. Go there
-for what this skill states without unpacking: the complete egress rule shapes (`paths[]` scoping, several
-credential bindings on one rule) and every row a preset bundle contains, declared images (`Image.fromTag` vs `Image.fromBuild`), secret
+for what this skill states without unpacking: the complete egress rule shapes (`paths[]` and method
+scoping), a credential's `hosts` and form, and every row a preset bundle contains, declared images (`Image.fromTag` vs `Image.fromBuild`), secret
 injection recipes, adopting resources that already exist, connections, triggers, pipelines and
 workflows including bring-your-own OAuth app and per-user grants, chat presence for Slack and Microsoft Teams,
 running several factory instances from one program, and a troubleshooting table keyed by the message the

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

@@ -219,7 +219,7 @@ the `agent` user. The worker writes a sign-in file only when none is there, so t
 **Before any cloud apply,** search `<factory>` for that marker, and for any credential in the setup script,
 in the environment's settings (`ENV`, which becomes `provisionSpec.env`), in the agents' instructions, and
 in every work-item description you write. Remove each one. Use a Secret
-instead: a gateway key, or a Secret plus a rule that adds it. Tell the developer why: the setup script and
+instead: a gateway key, or a Secret whose `hosts` name where the edge adds it. Tell the developer why: the setup script and
 the settings are stored as plain text and shown on every read.
 
 ### Start the local environment
@@ -318,8 +318,9 @@ The local key is never carried over. It stays on the developer's computer. In th
 Orchestra Secret, and our network edge adds it to each model call, so no machine and no person holds it:
 
 - 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 phase 2 of the orchestra-fdk skill, "The model route", says (orchestra skill, sections 6 and 7).
+- For a subscription token or a provider key, declare a Secret whose `hosts` name the provider's host, and a
+  rule that opens that 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.
@@ -374,23 +375,24 @@ into `orchestra-factory-notes.md`.
    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`.
+   captured Windows VM does not register. The worker's own command, `worker install-machine --cloud
+   azure`, adds the three parts the image must contain. The section "A team's own image" below gives the
+   steps:
+   - The worker's release package, 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`.
+   - The startup task `orchestra-azure-userdata`. It runs `worker.exe boot-files --cloud azure` as SYSTEM
+     at each boot. It 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
+   Our image runs the same command, from `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.
+   (Gen2). An environment that names no image boots its `Versions/latest`. Not released yet: 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
@@ -461,7 +463,7 @@ agent can run the team's own `docker compose up` unchanged.
    *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 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.
+   becomes a Secret whose `hosts` name where the edge adds it.
 5. Choose the size by what CI uses for the same work. The template's sizes are fixed per agent: lg is
    32 CPU, md 16, sm 2.
 6. When the project runs containers, keep the disk at `/var/lib/docker`. The starter declares it. It keeps
@@ -527,6 +529,8 @@ Choose B when the code needs a particular kernel or operating system.
   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.
+- **The team's own image, under a compute provider on Azure:** Windows stage 2 in section 5, and the same
+  for Linux. Follow "A team's own image" below.
 - **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.
 
@@ -611,6 +615,167 @@ Why each step is there:
   installed, use the team's own image ("Windows in three stages", stage 2).
 - The output is kept as it is. Never print a token.
 
+### A team's own image
+
+Tried by us (2026-10-05): a Windows Server 2025 Core image with IIS and an Ubuntu 24.04 image, each
+made by these steps with a branch build of the worker, started by our Launcher on test. Each VM
+registered, ran a turn that reached the internet, updated itself to a second build, and after a restart
+registered again and ran a second turn. Windows registered about 2 minutes after the session started
+and finished its first turn at about 4 minutes. Ubuntu registered at about 40 seconds and finished its
+first turn at about 80 seconds.
+
+Tested by a customer (2026-10-05): their own Windows Server 2025 image, with worker 0.0.137 laid out by
+hand, started by their Launcher on a `D4s_v6` VM.
+
+- The VM was up 27 seconds after the session started. The first turn came at about 2 minutes 48 seconds.
+- The model worked through an Orchestra gateway key, set as `ANTHROPIC_API_KEY` in the `SfdkWorker`
+  service's environment.
+- git to dev.azure.com worked, with a token their own boot step read from their Key Vault.
+- A machine endpoint on port 80 served.
+
+The team builds the image in their own Azure subscription, from Microsoft's or Canonical's image, with
+their toolchain and the worker. Their Launcher then starts machines from it. Do these steps with the
+developer, in order. The commands run on the build VM, as an administrator on Windows and with `sudo` on
+Linux. Use a worker version that has `install-machine`: `worker install-machine --help` answers on it.
+
+The image must reach these hosts. The worker does not test them:
+
+- The platform, and its object store.
+- While the team builds the image: `registry.npmjs.org` and `nodejs.org`. On Linux, the Ubuntu package
+  mirror.
+
+`worker install-machine --cloud azure` does these steps. Each one prints `ok` or `changed`, and the first
+failure stops the run and names the step. The team can run it again.
+
+- It refuses a VM that has already run as a machine, and a running worker service. Build on a new VM.
+- On Windows it creates the worker's folders for SYSTEM and the administrators only, so other accounts on
+  the VM cannot add programs or read the boot files.
+- It copies the worker's package to the machine-wide root, `C:\ProgramData\sfdk\worker` or
+  `/var/lib/sfdk/worker`.
+- On Linux it creates the `agent` account, uid 1000, home `/home`.
+- It defines the worker's service, and the startup task that writes the boot files and starts the worker.
+- `--harness claude` preinstalls a harness. Without it, the harness installs itself on its first turn.
+- It ends with `worker check --profile launcher`, which names every missing part.
+
+The image needs no `--egress-redirect`, `--docker` or `--node`: no network edge of ours stands in front of
+a Launcher machine, and the team installs their own tools.
+
+**Windows Server 2025, Core or Desktop, Generation 2:**
+
+1. Create the build VM with `--security-type Standard`. A Trusted Launch VM cannot be captured into the
+   image definition of step 7.
+2. Install the team's toolchain.
+3. Download the worker and check it against the digest npm publishes. Set the version:
+
+   ```powershell
+   [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
+   $version = '<worker version>'
+   $meta = Invoke-RestMethod "https://registry.npmjs.org/@orchestraworks%2Fworker-win32-x64/$version"
+   $tarball = Join-Path $env:TEMP 'worker.tgz'
+   Invoke-WebRequest -UseBasicParsing -Uri $meta.dist.tarball -OutFile $tarball
+   $digest = [Security.Cryptography.SHA512]::Create().ComputeHash([IO.File]::ReadAllBytes($tarball))
+   if (('sha512-' + [Convert]::ToBase64String($digest)) -ne $meta.dist.integrity) { throw 'the download does not match the digest npm publishes' }
+   $unpacked = Join-Path $env:TEMP 'worker'
+   New-Item -ItemType Directory -Force -Path $unpacked | Out-Null
+   tar.exe -xzf $tarball -C $unpacked
+   ```
+
+4. Install the worker:
+
+   ```powershell
+   & "$unpacked\package\worker.exe" install-machine --cloud azure
+   if ($LASTEXITCODE -ne 0) { throw "install-machine exited $LASTEXITCODE" }
+   ```
+
+5. Restart the VM until no restart is pending. Sysprep refuses to run, or stops, while one is pending.
+   After each restart, run the check. Stop when it shows `"restartPending":false`:
+
+   ```powershell
+   & "$env:ProgramData\sfdk\worker\package\worker.exe" check --profile launcher --output json
+   ```
+
+6. Generalize with Sysprep. It takes about 4 minutes, and the VM then stops:
+
+   ```powershell
+   & "$env:SystemRoot\System32\Sysprep\Sysprep.exe" /oobe /generalize /mode:vm /shutdown
+   ```
+
+   - Do not remove the built-in Administrator account. Azure renames it, so `Remove-LocalUser` fails.
+     Sysprep resets it.
+   - An installed SQL Server is generalized only through SQL Server's own image preparation, as Microsoft
+     documents for SQL Server and Sysprep. Plain Sysprep does not generalize it.
+
+7. Capture the VM into an image definition in the team's Azure Compute Gallery. The Launcher creates
+   Standard security VMs, and uses the NVMe disk controller on the `Dsv6` sizes. So the definition is
+   `TrustedLaunchSupported`, with both disk controllers:
+
+   ```bash
+   az vm deallocate --resource-group <rg> --name <vm>
+   az vm generalize --resource-group <rg> --name <vm>
+   az sig image-definition create --resource-group <rg> --gallery-name <gallery> \
+     --gallery-image-definition <definition> --publisher <publisher> --offer <offer> --sku <sku> \
+     --os-type Windows --os-state Generalized --hyper-v-generation V2 \
+     --features "SecurityType=TrustedLaunchSupported DiskControllerTypes=SCSI,NVMe"
+   az sig image-version create --resource-group <rg> --gallery-name <gallery> \
+     --gallery-image-definition <definition> --gallery-image-version 1.0.0 \
+     --virtual-machine "$(az vm show --resource-group <rg> --name <vm> --query id --output tsv)"
+   ```
+
+   Keep the quotes around `--features`: without them the Azure CLI refuses the second feature.
+
+8. Name the image version's resource id as the environment's image. A new version is a new image: name
+   it again after each build.
+
+**Ubuntu 22.04 or 24.04, Generation 2.** A Linux image for a Launcher must be Ubuntu: the worker refuses
+`--cloud azure` on another Linux.
+
+1. Create the build VM with `--security-type Standard`.
+2. Install the team's toolchain.
+3. Download the worker and check it against the digest npm publishes. On arm64 the package is
+   `worker-linux-arm64`:
+
+   ```bash
+   version='<worker version>'
+   curl -fsSL "https://registry.npmjs.org/@orchestraworks%2Fworker-linux-x64/${version}" -o worker.json
+   tarball="$(python3 -c 'import json; print(json.load(open("worker.json"))["dist"]["tarball"])')"
+   integrity="$(python3 -c 'import json; print(json.load(open("worker.json"))["dist"]["integrity"])')"
+   curl -fsSL "${tarball}" -o worker.tgz
+   [ "sha512-$(openssl dgst -sha512 -binary worker.tgz | base64 -w0)" = "${integrity}" ] ||
+     { echo "the download does not match the digest npm publishes" >&2; exit 1; }
+   mkdir -p worker && tar -xzf worker.tgz -C worker
+   ```
+
+4. Install the worker:
+
+   ```bash
+   sudo ./worker/package/worker install-machine --cloud azure
+   ```
+
+5. Generalize. This removes the account the team built with, which can hold uid 1000 beside `agent`.
+   Run it from `/`: it deletes the account's home, and the Azure agent stops with an error when its
+   working directory is gone. Afterwards uid 1000 is `agent`, and its group 1000 may have no name:
+
+   ```bash
+   cd / && sudo waagent -force -deprovision+user && export HISTSIZE=0 && sync
+   ```
+
+6. Capture as in Windows step 7, with `--os-type Linux`.
+7. Name the image version's resource id as the environment's image.
+
+If the image serves an app, the team's boot step ends with one request to the app. The first request
+after a boot is slow, so this request takes that delay instead of the first user.
+
+What can go wrong:
+
+- `install-machine` says a boot file or `state` is on the host: the VM has run as a machine. Build a new VM.
+- `worker check` names a missing part: run `install-machine` again. It repairs what it can.
+- The Launcher's VM never registers: read the worker's log on the VM, and run
+  `orchestra compute-providers check <id-or-slug>` (the orchestra skill, section 18).
+- The turn fails with `invalid_gateway_key` or `budget_exceeded`: the key the machine has is old, or the key
+  reached its `monthlyCreditCap`. See "Tokens on a compute provider's machines".
+- The team restarted a machine's VM in Azure, and the machine is now stopped: the worker reported that
+  it was stopping, so the platform stopped the VM. The next message starts it again.
+
 ### 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
@@ -620,7 +785,7 @@ or cloud. List what the code needs, host by host, before you choose.
 |---|---|---|---|---|
 | 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 keys live | Secrets, added at our network edge | On their machines, set by the team. 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 |
@@ -641,25 +806,41 @@ Cannot do:
 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.
+- The model key reaches the agent in one of three ways. Each works on every machine, hosted or the team's
+  own, with or without our network edge. The edge and its Secrets are an addition, never needed for the
+  team's own key.
+  1. **The environment's `env`** (`provisionSpec.env`, `env` in the kit). The worker reads it when it
+     starts. A declared value replaces the placeholder our image sets, never a real value. The platform
+     stores `env` values in plain text, an environment read returns them, and the machine's startup data
+     carries them. Tell the developer this. If it is not acceptable, use route 2 or 3, or a Secret added
+     at our network edge where one stands in front.
+  2. **Baked into the team's image**, at machine scope, before Sysprep or generalizing. On Windows, that
+     is the `SfdkWorker` service's `Environment` registry value. On Linux, it is a drop-in on
+     `sfdk-worker.service`.
+  3. **The `onStartAgent` hook** writes the harness's own key file in the agent's home:
+     `.claude/.credentials.json` for a Claude sign-in, `.codex/auth.json` for `codex`, or
+     `.pi/agent/auth.json` for `pi`. The worker keeps a real value it finds there. The hook can read the
+     team's Key Vault with a managed identity on the VM. A raw Claude API key has no file: use route 1 or 2.
+- The names, by harness. Tested by a customer on Windows, with a gateway key as `ANTHROPIC_API_KEY`
+  (see "A team's own image"):
+  - `claude` with an Anthropic API key or an Orchestra gateway key: `ANTHROPIC_API_KEY`. With a gateway
+    key, keep the agent's model gateway on: the platform sets the gateway address.
+  - `claude` with a Claude subscription token: `ORCHESTRA_WORKER_CLAUDE_OAUTH_TOKEN`. A renewing sign-in:
+    `ORCHESTRA_WORKER_CLAUDE_ACCESS_TOKEN` and `ORCHESTRA_WORKER_CLAUDE_REFRESH_TOKEN`.
   - `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.
+  - `pi`: `ORCHESTRA_WORKER_OPENAI_API_KEY` or `ORCHESTRA_WORKER_CLAUDE_OAUTH_TOKEN`.
+    `ORCHESTRA_WORKER_PI_PROVIDER` chooses the provider.
+  - Other tokens, such as for git, a package feed or an Azure DevOps personal access token: the team's
+    own names, by the same three routes.
+- Never restart the worker service to load a key. A restart after the worker registered stops the
+  machine's work, and the platform parks the VM. The next message starts it again, 1 to 2 minutes later.
+- A gateway key with a `monthlyCreditCap` stops at the cap. One short turn can cost about 30 credits.
 - 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.
+  the machine's id. Not released yet: a VM target's `userAssignedIdentities` field in the Launcher's
+  settings, a list of user-assigned identity resource ids. The Launcher attaches them when it creates
+  each VM, so a hook gets a token at once. The Launcher's own identity
+  needs Managed Identity Operator on each one.
 - 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.
 
@@ -678,10 +859,10 @@ that need no private service.
 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 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.
+   the model rule of the orchestra-fdk skill's phase 2: the `model-gateway` rule, or a rule on the provider's
+   host, with a Secret whose `hosts` name it. 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.