@orchestraworks/cli 0.5.0 → 0.5.2

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

@@ -49,7 +49,7 @@ orchestra fdk init --repository acme/shop
 writes a bug-fix factory for that GitHub repository: `fdk.json`, `tsconfig.json`, `main.ts`, the machine
 image under `image/`, the agent's standing instructions and an empty codebase skill. In `package.json` it
 sets `"type": "module"`, adds a `typecheck` script, and adds `tsx`, `typescript` and `@types/node`. `--model-key anthropic` or `--model-key openai` adds the organization's own
-model key; without it the agent runs on credits through the model gateway. It touches no platform and
+model key; without it the agent runs through the model gateway. It touches no platform and
 overwrites nothing. **Setting up a factory for a codebase is the `orchestra-fdk` skill's job**: the fast
 path from `orchestra fdk init` to a first fix, and the traps on the way.
 
@@ -103,6 +103,17 @@ 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.
 
+### Platform skills are attached by id
+
+An agent uses a platform skill only when its `skills` list names it: `Skill.fromId(factory, "skill_<key>")`
+in the kit, or `skillIds` on the API. Not released yet: managed skills that the kit and the create request
+add by default (`includeManagedSkills`).
+
+### Not released yet: an environment's working folder, `workingDirectory`
+
+Today the harness starts outside the code. The agent clones or uses its code under `/work` in its own first
+turn, as the starter's agents do.
+
 ### Identity comes from the construct path
 
 With no explicit `slug`, a resource's slug is the **factory name + full construct path**,
@@ -505,7 +516,7 @@ const claudeSignIn = new Secret(factory, "claude-sign-in", {
 });
 
 // …in the Environment's props:
-env: { CLAUDE_CODE_OAUTH_TOKEN: "placeholder", ANTHROPIC_API_KEY: "" },
+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 }),
 ```
@@ -593,6 +604,106 @@ which the harness would otherwise send instead.
   (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.
 
+## How the agents reach a model
+
+Ask the person which of three ways they want, and walk them through its steps once.
+
+**1. Subscription: their own Claude or Codex sign-in.** The person makes the sign-in in a real terminal
+on their own computer; run from your shell, its browser step hangs. Never read or copy a value yourself.
+
+- **Claude: a long-lived token in a Secret, the recommended way.** `claude setup-token` prints an
+  `sk-ant-oat…` token made for servers. It lasts about a year, and nothing on a machine renews or revokes
+  it, so it needs no shared `/home`. The person copies it and saves it to a file only they can read,
+  without pasting it into a chat: `umask 077 && pbpaste | tr -d '\n' > <file> && pbcopy </dev/null`.
+  At apply, the shell exports it from that file into the variable the Secret reads. Declare the Claude
+  sign-in recipe (§ Secrets are recipes, never values): a `Secret`, an egress rule that allows
+  `api.anthropic.com` and sets `Authorization: Bearer ${secret}` with `x-api-key` removed, and, in the
+  environment's `env`, `CLAUDE_CODE_OAUTH_TOKEN: "software-factory-egress-placeholder"` and an empty
+  `ANTHROPIC_API_KEY`. Turn `enableModelGateway` off for the agent. The machine holds only the
+  placeholder; the edge adds the token. Copying the renewing credentials file instead is the fallback,
+  and follows the ChatGPT sign-in steps below.
+- **Codex: a personal access token, where the workspace allows one.** A ChatGPT Business or Enterprise
+  member creates it at chatgpt.com/admin/access-tokens, once the workspace owner allows access tokens,
+  and chooses how long it lasts, such as 7 to 90 days. Codex never renews it, so it needs no shared
+  `/home`; the person supplies a new one before it expires. It begins `at-` and goes in
+  `ORCHESTRA_WORKER_CODEX_PERSONAL_ACCESS_TOKEN`, which outranks a ChatGPT sign-in or an API key beside
+  it. On their own computer, `codex login --with-access-token` reads the same token from standard input.
+- **Codex otherwise: a separate ChatGPT sign-in on a shared `/home`.** The other long-lived choice is an
+  OpenAI API key, billed by use rather than by the subscription (option 3).
+  1. **Make a separate sign-in, never a copy of the local one:** `mkdir -p <dir> && CODEX_HOME=<dir>
+     codex login`, with `--device-auth` only on a machine with no browser. Its tokens in
+     `<dir>/auth.json` go in the `ORCHESTRA_WORKER_CODEX_` variables below, or a setup step writes the
+     file.
+  2. **Put it on a shared `/home`.** Give the environment a durable `/home` volume, shared by every
+     machine that uses the sign-in, so one file renews for all of them. Separate copies fight: each
+     renewal replaces the refresh token, so the first copy to renew signs out the others. Two machines
+     that renew in the same second can still sign each other out; then make a new separate sign-in.
+     Remove the variables after the first machine starts, or each new machine writes the old token back.
+  3. **Never sign in again in the default folder after the copy.** A new `codex login` in `~/.codex`
+     revokes the cloud copy, and every machine then answers "refresh token was revoked". If it
+     happened, make a new separate sign-in.
+- **Keep a Codex sign-in off an agent that uses the model gateway.** With a ChatGPT sign-in or a personal
+  access token, Codex compresses its requests, and the gateway refuses them with `model_not_found`, a
+  known issue. Give such an agent the subscription directly, with `enableModelGateway` off, or keep the
+  homes apart.
+
+**2. Model gateway: Orchestra provides the key.** One endpoint reaches OpenAI, Anthropic and open-source
+models, on the organization's credits. The person can also bring their own provider key to the gateway:
+`orchestra fdk init --model-key anthropic` (or `openai`) declares a `ModelProviderKey`, which the gateway uses for
+that provider's calls. The gateway also routes models: `orchestra model-configs` sets which providers serve a
+model and in what order, so a call falls back to the next one when a provider is down, and
+`orchestra model-aliases` gives a model a name of the organization's own, such as `default`, that one change
+points elsewhere.
+
+**3. Own API key via the vault.** Their Anthropic or OpenAI API key is a platform `Secret`, added at the
+network edge on calls straight to the provider, with no gateway in between, and nothing to sync, because
+an API key does not renew. Declare it as the Claude sign-in recipe (§ Secrets are recipes) does, with the provider's own
+header, and leave `enableModelGateway` off in the agent's model settings:
+
+```ts
+const anthropicKey = new Secret(factory, "anthropic-api-key", {
+  value: SecretValue.fromEnv("ORCHESTRA_FDK_ANTHROPIC_API_KEY"),
+  injection: { headers: [{ name: "x-api-key", value: "${secret}" }] },
+});
+// …in the Environment's props:
+egress: EgressPolicy.allowAll()
+  .allow("anthropic", { hosts: ["api.anthropic.com"], priority: 300, credential: anthropicKey }),
+```
+
+For OpenAI, inject `authorization: Bearer ${secret}` on `api.openai.com`. Recommend this over a
+subscription when the person has an API key: there is no file to copy and no shared `/home`.
+
+### The subscription variables
+
+The worker writes each value into the file the harness reads, once per machine start, and hands none of
+these variables to the harness. pi can also run on the provider you name.
+
+| Variable | claude | codex | pi |
+|---|---|---|---|
+| `ORCHESTRA_WORKER_CLAUDE_OAUTH_TOKEN`: a `claude setup-token` token as a worker setting, in plain text; the Claude sign-in recipe's Secret is the recommended way | yes | — | yes |
+| `ORCHESTRA_WORKER_CLAUDE_ACCESS_TOKEN` and `ORCHESTRA_WORKER_CLAUDE_REFRESH_TOKEN`, plus `ORCHESTRA_WORKER_CLAUDE_EXPIRES_AT` in milliseconds if you have it: a renewing Claude sign-in | yes | — | yes |
+| `ORCHESTRA_WORKER_OPENAI_API_KEY` | — | yes | yes |
+| `ORCHESTRA_WORKER_CODEX_PERSONAL_ACCESS_TOKEN`: a Codex personal access token, which outranks the other Codex rows | — | yes | — |
+| `ORCHESTRA_WORKER_CODEX_ID_TOKEN`, `ORCHESTRA_WORKER_CODEX_ACCESS_TOKEN`, `ORCHESTRA_WORKER_CODEX_REFRESH_TOKEN` and `ORCHESTRA_WORKER_CODEX_ACCOUNT_ID` (`tokens.account_id`, which Codex needs to renew): a ChatGPT sign-in | — | yes | — |
+| `ORCHESTRA_WORKER_PI_PROVIDER`: pi's `defaultProvider`, such as `anthropic` or `openai` | — | — | yes |
+
+You can also bake the harness's own sign-in or settings file into the image with the setup script. With
+no variable set, the worker leaves a value already in that file alone. For pi, your own
+`ANTHROPIC_AUTH_TOKEN`, `ANTHROPIC_OAUTH_TOKEN`, `ANTHROPIC_API_KEY` or `OPENAI_API_KEY` in `env` still works: the worker then leaves that provider's
+placeholder out of pi's sign-in file, which pi would otherwise read first, and holds back the image's
+`ANTHROPIC_OAUTH_TOKEN` placeholder beside your own `ANTHROPIC_API_KEY`.
+
+- **The value is plain text.** `env` is stored unencrypted, and an environment read returns it. Anyone
+  who can read the environment can read its setup script.
+- **Allow the sign-in hosts with no credential bound**: `platform.claude.com` for a copied Claude
+  credentials file, `api.openai.com` for an OpenAI key, `auth.openai.com` and `chatgpt.com` for ChatGPT. A
+  rule that binds a credential on one of these hosts replaces your sign-in on every call.
+- **Name pi's provider when the model is not a Claude one.** pi runs the agent's model under its
+  `defaultProvider`, which `ORCHESTRA_WORKER_PI_PROVIDER` sets; with no variable, pi keeps the image's
+  `anthropic` or the provider you configured. The platform never picks it from the model.
+- **On a Mac outpost, Claude Code reads the login Keychain first.** Sign out of Claude Code there, or
+  use `ORCHESTRA_WORKER_CLAUDE_OAUTH_TOKEN`, which Claude Code reads before the Keychain.
+
 ## Egress: apply the bundles, hand-write the rest
 
 An environment's `egress` is a policy you build up from one of **two starting points**:

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

@@ -1,6 +1,7 @@
 # Port a codebase's setup to Orchestra machines
 
-Step 6 of the orchestra-fdk skill sends you here. When you finish, go back to that step.
+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.
 
 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.
@@ -10,9 +11,15 @@ An *environment* is the declared shape of a machine, and every machine an agent
 The orchestra skill, sections 4 to 6, explains environments, machines, network rules and secrets, and says what
 they cannot do yet. Read those sections before you choose a mode.
 
-In the engineering team template, every environment is built by `declareEnvironment` in
-`<factory>/lib/environment.ts`. You edit only the section marked `WHAT THE CODE NEEDS`, and the end of
-`<factory>/lib/setup.sh`, unless the chosen path needs more.
+Where you edit depends on the starter:
+
+- *Engineering-team starter:* every environment is built by `declareEnvironment` in
+  `<factory>/lib/environment.ts`. You edit only the section marked `WHAT THE CODE NEEDS`, and the end of
+  `<factory>/lib/setup.sh`, unless the chosen path needs more.
+- *Bug-fix starter:* each environment is a `new Environment` in `<factory>/main.ts`. Its setup script is
+  `<factory>/image/setup.sh`, and its image is built from `<factory>/image/Dockerfile`.
+
+Below, *the setup script* and *the environment code* mean these files for your starter.
 
 ## 1. Find the sources
 
@@ -74,7 +81,7 @@ the computer's own operating system picks among them.
 
 Even when rows 1 and 2 do not work, a Linux full VM is the preferred cloud machine, on a Mac or Windows
 computer too. Use a hosted Mac or a Windows full VM only when the project truly depends on that operating
-system, such as iOS or Xcode. A hosted Mac is a dedicated Apple machine, billed for a 24-hour minimum.
+system, such as iOS or Xcode. A hosted Mac is a dedicated Apple machine.
 Today Orchestra launches no Mac: path B says what works now.
 
 **Open: proving a Linux full VM locally on a Mac or Windows computer.** The host outpost there runs on
@@ -149,16 +156,16 @@ proves the agent works in the environment.
 
 ### The agent's model key, locally
 
-The local agent needs a model key. The developer picks one of three sources, in this order, and exports
+The local agent needs a model key. The developer uses one of three sources, the one they have, and exports
 it in the shell that starts `orchestra local`:
 
 1. **A local token from their own subscription,** such as the one `claude setup-token` prints for Claude
    Code.
 2. **An API key from the model provider.**
-3. **A model gateway key from Orchestra,** when neither of those is at hand. It is a separate key for local
-   work, such as `local-dev`, with a monthly cap. The developer creates it in the console at
-   **Settings > Gateway keys**, which shows the value once. The model gateway is a public service at
-   `models.orchestraworks.ai`, so the key works locally too. Usage is charged to the organization's credit.
+3. **A model gateway key from Orchestra.** It is a separate key for local work, such as `local-dev`, with a
+   monthly cap. The developer creates it in the console at **Settings › Gateway keys**, which shows the
+   value once. The model gateway is a public service at `models.orchestraworks.ai`, so the key works locally
+   too.
 
 **What each harness itself accepts:**
 
@@ -183,7 +190,7 @@ sign-in is reported by the Orchestra team and not yet verified in pi's docs.
 | `pi` | `ANTHROPIC_OAUTH_TOKEN` for Anthropic. OpenAI: not wired yet | Anthropic and OpenAI keys: not wired yet | `ANTHROPIC_OAUTH_TOKEN` (not proven yet) |
 | `script`, `custom` | No key needed | No key needed | No key needed |
 
-The path that works tonight is a `claude` agent with `CLAUDE_CODE_OAUTH_TOKEN`. Use it unless the agent
+The path that works today is a `claude` agent with `CLAUDE_CODE_OAUTH_TOKEN`. Use it unless the agent
 must run another harness.
 
 - **For a gateway key,** also export
@@ -222,9 +229,12 @@ the settings are stored as plain text and shown on every read.
 2. The two export lines point `orchestra` at this local run. Load them only into the commands meant for the
    run. Never load them into a command meant for Orchestra's cloud.
 3. Create the environment and an agent on the run with `npx orchestra environments create --body @<file>` and
-   `npx orchestra agents create --body @<file>`. Build each body from the `manager-work-lg` and `manager-agent`
-   entries in `<factory>/fdk.out/plan.json`. Keep the setup script from `<factory>/lib/setup.sh` in the
-   environment's body. The network rules may stay: the local environment does not enforce them. Set the
+   `npx orchestra agents create --body @<file>`. Build each body from the entries in
+   `<factory>/fdk.out/plan.json` for the environment you are proving and an agent on it. For a new
+   engineering-team factory, that is `manager-work-lg` and `manager-agent`. For a new environment in an
+   existing factory, it is the environment and the agent you added. Keep that environment's setup script in
+   its body: `<factory>/lib/setup.sh` or `<factory>/image/setup.sh`, as the top of this file says. The
+   network rules may stay: the local environment does not enforce them. Set the
    agent's model settings for the key source, as "The agent's model key, locally" says.
    `npx orchestra fdk apply` does not work against a run: it stops at the first thing the run does not serve.
 4. Cut a git bundle of the default branch outside the codebase:
@@ -240,7 +250,7 @@ the settings are stored as plain text and shown on every read.
    `orchestra local status` shows checks 1 and 2 (the machine started, and the harness opened its
    conversation).
 2. Find the machine's container with `docker ps`. Copy in the bundle with `docker cp`.
-3. Change the setup in `<factory>/lib/setup.sh`, so the script you prove is the script you apply. Then
+3. Change the setup in the setup script, so the script you prove is the script you apply. Then
    update the environment on the run and start a new machine.
    *Fallback until the local environment runs the setup script:* copy the script in with `docker cp` and run
    it as root yourself: `docker exec -u root <container> bash /tmp/setup.sh`.
@@ -308,10 +318,10 @@ 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 provider key, declare a Secret and a rule that adds it on the provider's host (orchestra skill,
-  sections 6 and 7).
+- 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).
 
-Ask the developer to revoke the `local-dev` gateway key, at **Settings > Gateway keys**, when local work is
+Ask the developer to revoke the `local-dev` gateway key, at **Settings › Gateway keys**, when local work is
 done.
 
 **Check:** milestones 1 and 2 pass and the agent turn completes in the chosen mode, or you know which one
@@ -346,6 +356,8 @@ agent can run the team's own `docker compose up` unchanged.
    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
    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.
 
 #### Setup script or a baked image
 
@@ -404,23 +416,26 @@ Write down what is missing and stop here. Report it to the developer, and go bac
 
 ## 6. Write and check
 
-1. Edit `lib/environment.ts` for the chosen path.
+1. Edit the environment code for the chosen path: `lib/environment.ts` in the engineering-team starter,
+   `main.ts` and `image/` in the bug-fix starter.
 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-gateway` rule. No environment has a Bitbucket or Jira rule yet: those come with the tokens,
-   in step 10 of the orchestra-fdk skill.
+   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.
 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 step 6 of the
-orchestra-fdk skill for the apply.
+**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.
 
 ## 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 7 of the orchestra-fdk skill starts. It proves what only the
+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.
 
@@ -439,6 +454,61 @@ bundle. Keep the safety rule:
 When a step fails, fix it here, prove the fix locally if a local mode runs, apply again, and assign the
 item again.
 
+### The model in the cloud: subscription, model gateway, or own key via the vault
+
+The cloud agents reach a model in one of three ways. Ask the developer which one, and walk them through
+its steps once. They copy every value themselves; you never read, print or copy it.
+
+1. **Subscription: their own Claude or Codex sign-in.** Follow the sign-in steps below.
+2. **Model gateway: Orchestra provides the key.** One endpoint reaches OpenAI, Anthropic and open-source
+   models, on the organization's credits. They can also bring their own provider key to the gateway, with
+   `orchestra fdk init --model-key anthropic` or `openai`. The gateway also routes models:
+   `orchestra model-configs` sets which providers serve a model and in what order, so a call falls back to
+   the next one when a provider is down, and `orchestra model-aliases` gives a model a name of their own, such as `default`.
+3. **Own API key via the vault.** Their Anthropic or OpenAI API key is a platform Secret, added at the
+   network edge on calls straight to `api.anthropic.com` or `api.openai.com`, with no gateway in between
+   and with the agent's gateway setting off. Nothing to sync, because an API key does not renew. When they
+   have an API key, recommend this over a subscription: no file to copy and no shared `/home`.
+   `references/authoring.md` § How the agents reach a model shows the declaration.
+
+The sign-in steps. The developer makes the sign-in in a real terminal on their computer; run from an
+agent's shell, its browser step hangs.
+
+- **Claude: a long-lived token in a Secret, the recommended way.** `claude setup-token` prints an
+  `sk-ant-oat…` token made for servers. It lasts about a year, and nothing on a machine renews or revokes
+  it, so it needs no shared `/home`. Save it to a file only the developer can read, never through a chat:
+  copy it, then `umask 077 && pbpaste | tr -d '\n' > <file> && pbcopy </dev/null`. At apply, the shell
+  exports it from that file into the variable a `Secret` reads. An egress rule allows `api.anthropic.com`
+  and adds `Authorization: Bearer ${secret}`, removing `x-api-key`. The environment's `env` holds only
+  `CLAUDE_CODE_OAUTH_TOKEN=software-factory-egress-placeholder` and an empty `ANTHROPIC_API_KEY`, and the
+  agent's gateway setting is off. Never put the token itself in `env`. The Claude sign-in recipe in
+  `references/authoring.md` shows the declaration. Copying the renewing credentials file is the fallback,
+  and follows the ChatGPT sign-in steps below.
+- **Codex: a personal access token, where the workspace allows one.** A ChatGPT Business or Enterprise
+  member creates it at chatgpt.com/admin/access-tokens, once the workspace owner allows access tokens,
+  and chooses how long it lasts, such as 7 to 90 days. Codex never renews it, so it needs no shared
+  `/home`; the developer supplies a new one before it expires. It begins `at-` and goes in
+  `ORCHESTRA_WORKER_CODEX_PERSONAL_ACCESS_TOKEN`, which outranks a ChatGPT sign-in or an API key beside
+  it. On their own computer, `codex login --with-access-token` reads the same token from standard input.
+- **Codex otherwise: a separate ChatGPT sign-in on a shared `/home`.** The other long-lived choice is an
+  OpenAI API key, billed by use rather than by the subscription (option 3).
+  1. **Make a separate sign-in, never a copy of the local one:** `mkdir -p <dir> && CODEX_HOME=<dir> codex
+     login` (`--device-auth` only with no browser). Its tokens in `<dir>/auth.json` go in the
+     `ORCHESTRA_WORKER_CODEX_` variables, or a setup step writes the file.
+  2. **Give the environment a durable `/home` volume,** shared by every machine that uses the sign-in, so
+     one file renews for all of them. Each renewal replaces the refresh token, so separate copies sign
+     each other out; two machines that renew in the same second can too, and then need a new sign-in.
+     Remove the variables after the first machine starts.
+  3. **Never sign in again in the default folder after the copy.** A new `codex login` in `~/.codex`
+     revokes the cloud copy, and every machine answers "refresh token was revoked". If it happened, make
+     a new separate sign-in.
+- **Keep a Codex sign-in off an agent that uses the model gateway.** With a ChatGPT sign-in or a personal
+  access token, Codex compresses its requests, and the gateway refuses them with `model_not_found`, a
+  known issue. Give such an agent the subscription directly, with its gateway setting off, or keep the
+  homes apart.
+
+The sign-in values are plain text: the environment's settings are stored unencrypted and shown on every read.
+
 ## What the platform can do
 
 Use the orchestra skill to build an answer for a case the paths do not cover. Never promise one of its "Cannot

package/templates/engineering-team/lib/setup.sh

@@ -45,11 +45,11 @@ chown agent:agent /work || exit 16
 
 # ---- Add the team's system setup here: packages, language runtimes, tools. -----------------------------------
 
-# Optional, off by default: a Node major version other than the image's. To turn it on, remove the leading `# `
-# from the lines from NODE_MAJOR to `esac`, and set NODE_MAJOR. It replaces the image's Node in /usr/local. The
-# image's own npm and corepack go first: unpacking a second Node over them leaves a mix of two npm versions, and
-# every npm command then exits 1. Use this Node's own corepack for pnpm or yarn.
-# NODE_MAJOR=24
+# Optional, off by default: a Node major version other than the image's Node 24. To turn it on, remove the
+# leading `# ` from the lines from NODE_MAJOR to `esac`, and set NODE_MAJOR. It replaces the image's Node in
+# /usr/local. The image's own npm and corepack go first: unpacking a second Node over them leaves a mix of two npm
+# versions, and every npm command then exits 1. Use this Node's own corepack for pnpm or yarn.
+# NODE_MAJOR=22
 # case "$(node --version 2>/dev/null)" in "v$NODE_MAJOR".*) ;; *)
 #   case "$(uname -m)" in aarch64 | arm64) node_arch=arm64 ;; *) node_arch=x64 ;; esac
 #   node_version=$(curl -fsSL --retry 3 https://nodejs.org/dist/index.json |