@orchestraworks/cli 0.5.8 → 0.6.0

package/skills/orchestra/SKILL.md

@@ -265,8 +265,8 @@ unless you set one, so it wins over the open default and over the usual allow ru
 **Live effect.** The edge reads the environment's rules on each request. So an apply that changes the rules
 reaches every machine at once, machines already running included, from their next request.
 
-**How it relates.** On a request a rule allows, the edge adds the secret or connection whose `hosts` cover the
-host, and only on `https` (section 6). Calls to the Orchestra platform itself skip these rules: the agent's
+**How it relates.** On a request a rule allows, the edge adds a secret or connection whose `hosts` cover the
+host, only on `https`, and only when the request names it or an environment default covers it (section 6). Calls to the Orchestra platform itself skip these rules: the agent's
 role decides them (section 1). So a machine blocked from the code host still downloads a file through
 `orchestra files get-content`. The worker points each harness's tools at the edge through proxy variables, so
 a service the agent runs in a container needs its name in `NO_PROXY` in the environment's settings.
@@ -291,10 +291,19 @@ resolved at the edge on an allow); AGENTS.md "Egress And Credentials". Kit: cli/
 **What it's for.** It lets agents use a key without seeing it. No agent, no person and no apply output ever shows
 the value.
 
-**What it is.** A *secret* is a stored value that can be written and never read back. It declares its `hosts`
-and an `injection` recipe, the headers it sets, and the network edge adds it to each allowed `https` request
-to one of those hosts. This is *credential injection at the network edge*. When two credentials cover one
-host, the request names one with a reference, `orchestra:secret/<id>`, in place of its key.
+**What it is.** A *secret* is a stored value that can be written and never read back. It declares an
+`injection` recipe, the headers it sets and the `hosts` it sets them on, and the network edge adds it to an
+allowed `https` request to one of those hosts. A secret with no recipe is stored only, and the edge never adds it. This is *credential injection at the network edge*. The edge adds it only in two cases:
+
+- The request names it with a reference, `orchestra:secret/<id>` or `orchestra:connection/<id>`, in place
+  of its key. A `Secret` or `Connection` set as an environment `env` value is written as that reference:
+  `ANTHROPIC_API_KEY` for claude, `GH_TOKEN` for `gh`, `GITLAB_TOKEN` for `glab`, `ORCHESTRA_GIT_CREDENTIAL`
+  for git. `routeModelsViaGateway({ key })` names the gateway key this way for claude and codex. The
+  `linear`, `slack` and `teams` commands take `--connection-id <id>`.
+- The environment's `credentials` list covers the host, for a request that names nothing. The first
+  covering entry serves; with `replace: false`, a request carrying its own value keeps it.
+
+A request that names nothing and that no default covers leaves as it was sent.
 
 **How it relates.** A secret is added only where a network rule lets the request leave (section 5). Never put
 a key in an environment's settings or in instructions: the machine's processes read every setting.
@@ -325,8 +334,9 @@ network rules carry the option (sections 2 and 5).
 **A Claude or Codex subscription.**
 
 - *Claude.* `claude setup-token` prints a long-lived token. It is stored as a secret, and the network edge
-  adds it to each call to `api.anthropic.com`. The machine holds only a placeholder token and an empty API
-  key, so no agent and no person sees the real one. Never put the token in an environment's settings: they
+  adds it to each call to `api.anthropic.com` that names it. The environment's `env` names the secret in
+  `CLAUDE_CODE_OAUTH_TOKEN` by reference, `orchestra:secret/<id>`, beside an empty API key, so no agent
+  and no person sees the real one. Never put the token in an environment's settings: they
   are plain text.
 - *Codex.* A personal access token, made by a ChatGPT Business or Enterprise member, or a separate ChatGPT
   sign-in kept on a `/home` volume that every machine using it shares. A Codex sign-in stays off the model
@@ -337,7 +347,8 @@ network rules carry the option (sections 2 and 5).
 
 **An Orchestra account, through the model gateway.** The model gateway is a hosted service at
 `models.orchestraworks.ai`. One endpoint reaches OpenAI, Anthropic and open models. A *gateway key* is a key
-to it, stored as a secret. The network edge adds it to each model call, so no agent and no person sees it.
+to it, stored as a secret. `routeModelsViaGateway({ key })` names it to each harness, and the network edge
+adds it to each model call, so no agent and no person sees it.
 Without it, an agent's first message fails with "Invalid API key".
 
 - *Routing.* `orchestra model-configs` sets which providers serve a model, and in which order, so a call
@@ -348,10 +359,11 @@ Without it, an agent's first message fails with "Invalid API key".
 - *A cap.* Each gateway key can carry a monthly cap, set in the console at **Settings › Gateway keys**.
 
 **Their own provider API key.** The team's Anthropic or OpenAI API key is a secret that the network edge adds
-to calls straight to the provider, with no gateway in between.
+to calls straight to the provider, with no gateway in between. The environment names it in `ANTHROPIC_API_KEY`
+or `ORCHESTRA_WORKER_OPENAI_API_KEY`, or lists it in `credentials`.
 
 **How it relates.** Each option reaches the model through an ordinary allow rule on the model's host, and a
-secret whose `hosts` name that host (sections 5 and 6). An agent on the model gateway turns it on in its model settings (section 2). An agent on a
+secret whose recipe's `hosts` name that host (sections 5 and 6). An agent on the model gateway turns it on in its model settings (section 2). An agent on a
 subscription or its own key turns it off. For plan questions, send the person to **Settings › Plan & usage**
 in the console.
 
@@ -647,7 +659,7 @@ local/launch/modelkey.go (model key carriers per harness, the gateway address va
 worker/facts/families.json (how each harness takes the gateway address); on develop at f62fad1481,
 agents/runtime/assembly/common/placeholder-env (the images' placeholder ANTHROPIC_API_KEY),
 LauncherProperties.kt (the gallery images at Versions/latest), launcher/config/config.go (Dsv5 default);
-worker/facts/families.json (the ORCHESTRA_WORKER_ names), worker/service/manager_windows.go (SfdkWorker),
+worker/facts/families.json (the ORCHESTRA_WORKER_ names), worker/service/service.go (OrchestraWorker, and the previous SfdkWorker),
 infra/packer/azure-windows-runtime.pkr.hcl (the startup task), launcher/cloud/cloud.go (the VM tags);
 the proven list is the test run of 2026-10-05. -->
 
@@ -677,8 +689,8 @@ the proven list is the test run of 2026-10-05. -->
     1. The environment's `env` (`provisionSpec.env`). A declared value replaces our image's placeholder,
        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.
-    2. Baked into the team's image at machine scope: on Windows the `SfdkWorker` service's `Environment`
-       registry value, on Linux a drop-in on `sfdk-worker.service`.
+    2. Baked into the team's image at machine scope: on Windows the `OrchestraWorker` service's
+       `Environment` registry value, on Linux a drop-in on `orchestra-worker.service`.
     3. The `onStartAgent` hook writes the harness's own key file: `.claude/.credentials.json` for a Claude
        sign-in, `.codex/auth.json` for `codex`, `.pi/agent/auth.json` for `pi`. A raw Claude API key has
        no file.
@@ -686,6 +698,10 @@ the proven list is the test run of 2026-10-05. -->
     `ORCHESTRA_WORKER_CLAUDE_OAUTH_TOKEN` for a Claude subscription token; `ORCHESTRA_WORKER_OPENAI_API_KEY`
     or `ORCHESTRA_WORKER_CODEX_PERSONAL_ACCESS_TOKEN` for `codex`. With a gateway key, keep the agent's
     model gateway on. The platform sets the gateway address.
+  - An install replaces the service an earlier release registered as `SfdkWorker` on Windows,
+    `sfdk-worker.service` on Linux or `ai.livingcomputers.sfdk.worker` on macOS. The new ones are
+    `OrchestraWorker`, `orchestra-worker.service` and `ai.livingcomputers.orchestra.worker`. Change your own
+    scripts that name the old ones.
   - 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 details: the orchestra-fdk skill's `references/environment.md`, "Tokens on a compute provider's

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

@@ -68,8 +68,10 @@ const factory = new Factory({ name: "acme-support" });
 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
+  injection: {
+    headers: [{ name: "Authorization", value: "Bearer ${secret}" }], // how the edge presents it
+    hosts: ["api.openai.com"], // where
+  },
 });
 
 const runtime = new Environment(factory, "runtime", {
@@ -554,26 +556,29 @@ 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
-new Secret(factory, "claude-sign-in", {
+const claudeSignIn = 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
+    hosts: ["api.anthropic.com"],
   },
 });
 
 // …in the Environment's props:
-env: { CLAUDE_CODE_OAUTH_TOKEN: "software-factory-egress-placeholder", ANTHROPIC_API_KEY: "" },
+env: { CLAUDE_CODE_OAUTH_TOKEN: claudeSignIn, ANTHROPIC_API_KEY: "" },
 egress: EgressPolicy.allowAll()
   .allow("claude-sign-in", { hosts: ["api.anthropic.com"], priority: 300 }),
 ```
 
 It injects `authorization` and nothing else. **Never inject an `anthropic-beta` header**: an injected
-one replaces the harness's own list of beta flags, and every call then answers 400. The placeholder
-`CLAUDE_CODE_OAUTH_TOKEN` makes the harness sign in the subscription way and send its own list, and the
-edge swaps the real token in. The empty `ANTHROPIC_API_KEY` covers the runtime image's placeholder key,
-which the harness would otherwise send instead.
+one replaces the harness's own list of beta flags, and every call then answers 400. A Secret as an `env`
+value is written as its reference, `orchestra:secret/<id>`, with the id resolved at apply. In
+`CLAUDE_CODE_OAUTH_TOKEN` it makes the harness sign in the subscription way and send its own list, and the
+edge reads the reference where the token goes and swaps the real token in. The edge adds a credential only
+to a request that names one, or that an environment default covers (`references/environment.md`, "Naming a
+credential"). The empty `ANTHROPIC_API_KEY` covers the runtime image's placeholder key, which the harness
+would otherwise send instead.
 
 - Sources: `SecretValue.fromEnv(NAME)`, `SecretValue.fromCommandLine(label?)` and
   `SecretValue.fromGatewayKey(key)`, plus the derived recipes `basicAuth`, `registryCredential` and
@@ -613,7 +618,7 @@ which the harness would otherwise send instead.
   `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 the edge then
-  adds on its `hosts` like any other. It is legal only as the whole top-level value of exactly one Secret:
+  adds on its recipe's `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
@@ -648,11 +653,12 @@ 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.
-- 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.
+- Presenting a secret on the network: the `Secret` itself declares an `injection` recipe — how: the
+  headers it sets, reading `${secret}`, or `${secret.<field>}` for a `SecretValue.fields` value; and
+  where: its `hosts`, each an exact host, `*.suffix`, or `*`. Egress rules carry no credential, so a rule
+  that passes `credential` or `credentials` is a synth error. A Secret with no `injection` is stored
+  only, and one whose recipe has no `hosts` is presented nowhere. The top-level `hosts` prop is
+  deprecated: it is moved into the recipe for one release.
 
 ## How the agents reach a model
 
@@ -668,9 +674,9 @@ on their own computer; run from your shell, its browser step hangs. Never read o
   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,
+  environment's `env`, `CLAUDE_CODE_OAUTH_TOKEN` set to that Secret and an empty `ANTHROPIC_API_KEY`.
+  Turn `enableModelGateway` off for the agent. The machine holds only the Secret's reference; 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,
@@ -762,7 +768,7 @@ An environment's `egress` is a policy you build up from one of **two starting po
 - **`EgressPolicy.allowAll()`** allows every host no rule 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.
+only to the hosts its own recipe's `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
@@ -1079,7 +1085,7 @@ orchestra gateway-keys create --slug ci-smoke --output-file key.json
   export, a CI secret) suppresses the only prompt you would have seen, the command says so in one
   line on **stderr**, naming the lever — stdout stays the response document.
 - **Writing to a factory-managed resource warns.** `apply` stamps what it manages with an
-  `sfdk.managedBy` labels key naming the owning factory, and a write to a stamped resource says so:
+  `orchestra.managedBy` labels key naming the owning factory, and a write to a stamped resource says so:
   the next `apply` reverts it. It is a warning, not a refusal — the fallback has to stay usable in an
   emergency — and it is the CLI telling you this belongs in `main.ts`.
 

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 whose `hosts` name where the edge adds it. Tell the developer why: the setup script and
+instead: a gateway key, or a Secret whose recipe's `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,7 +318,7 @@ 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 whose `hosts` name the provider's host, and a
+- For a subscription token or a provider key, declare a Secret whose recipe's `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).
 
@@ -378,12 +378,15 @@ into `orchestra-factory-notes.md`.
    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
+   - The worker's release package, at `C:\ProgramData\orchestra\worker\package`.
+   - The worker's Windows service, `OrchestraWorker`. It runs `worker.exe run --root C:\ProgramData\orchestra\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 `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`.
+     at each boot. It writes the files that the VM's startup data carries, then starts `OrchestraWorker`.
+   - An install replaces the service an earlier release registered as `SfdkWorker`. Change your own
+     scripts that name it. On an image an earlier release built, the startup task still starts
+     `SfdkWorker`.
 
    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
@@ -463,7 +466,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 whose `hosts` name where the edge adds it.
+   becomes a Secret whose recipe's `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
@@ -650,8 +653,8 @@ 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`.
+- It copies the worker's package to the machine-wide root, `C:\ProgramData\orchestra\worker` or
+  `/var/lib/orchestra/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.
@@ -691,7 +694,7 @@ a Launcher machine, and the team installs their own tools.
    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
+   & "$env:ProgramData\orchestra\worker\package\worker.exe" check --profile launcher --output json
    ```
 
 6. Generalize with Sysprep. It takes about 4 minutes, and the VM then stops:
@@ -815,8 +818,8 @@ Tokens on a compute provider's machines:
      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`.
+     is the `OrchestraWorker` service's `Environment` registry value. On Linux, it is a drop-in on
+     `orchestra-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
@@ -870,6 +873,40 @@ that need no private service.
 **Check:** the typecheck and the synth pass, and the plan is as in item 3. Go back to the orchestra-fdk
 skill's phase 4 for the apply.
 
+### Naming a credential
+
+The network edge adds a credential to a request in two cases only. A request that names none and that no
+environment default covers leaves with the headers it was sent, a placeholder included.
+
+- **The request names it.** Set the variable a tool reads its token from to a `Secret` or a `Connection`
+  in the environment's `env`. Apply writes `orchestra:secret/<id>` or `orchestra:connection/<id>`, and the
+  tool sends that reference where its token goes. The edge reads it and adds the credential, if the
+  agent may use it.
+
+  | Tool | Variable |
+  |---|---|
+  | claude, pi | `ANTHROPIC_API_KEY`, or `CLAUDE_CODE_OAUTH_TOKEN` for a subscription token |
+  | codex | `ORCHESTRA_WORKER_OPENAI_API_KEY`, which the worker writes into codex's own auth file |
+  | `gh` | `GH_TOKEN` |
+  | `glab` | `GITLAB_TOKEN`, which `glab` sends as `Private-Token` |
+  | git | `ORCHESTRA_GIT_CREDENTIAL`: the image's git credential helper answers it when the server asks |
+  | `linear`, `slack`, `teams` | `--connection-id <id>` on the command; it reads no connection |
+
+  `routeModelsViaGateway({ key })` sets `ANTHROPIC_API_KEY` and `ORCHESTRA_WORKER_OPENAI_API_KEY` to the
+  key Secret itself, so declare neither beside it.
+
+- **An environment credential covers the host.** `credentials` lists Secrets and Connections. A
+  request from the environment's machines that names none gets the first whose hosts cover its host,
+  whatever the agent. `replace` is true unless set: with `replace: false`, a request that carries its own
+  value in the credential's header keeps it and gets nothing. Adding an entry needs your own use of that
+  credential.
+
+  ```ts
+  credentials: [{ credential: githubConnection }, { credential: modelKey, replace: false }],
+  ```
+
+  With no `credentials` declared, apply leaves the live list alone; `[]` clears it.
+
 ## 7. The cloud
 
 The cloud is the fallback when no local mode can run. It is also the confirmation after the local proof:
@@ -914,7 +951,7 @@ agent's shell, its browser step hangs.
   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
+  `CLAUDE_CODE_OAUTH_TOKEN` set to the Secret, its reference, 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.

package/skills/orchestra-fdk/references/integrations/code-repo.md

@@ -4,7 +4,10 @@ Give access with a Secret the network edge adds, or with the provider's platform
 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.
+the credential only to a request that names it, or that an environment default covers
+(`../environment.md`, "Naming a credential"). Name it in the environment's `env`: `GH_TOKEN` for `gh`,
+`GITLAB_TOKEN` for `glab`, and `ORCHESTRA_GIT_CREDENTIAL` for git, each set to the Secret or the
+Connection.
 
 Phase 3, "From a recipe to code", turns a recipe into a Secret and a rule.
 
@@ -21,8 +24,25 @@ 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.
+Git sends Basic auth. The image's git credential helper answers the reference in `ORCHESTRA_GIT_CREDENTIAL`
+as the password when the server asks, and the edge replaces it, so the agent clones
+`https://<host>/<path>.git` with no user name and no password in the address. A default that covers the
+host adds the credential with no reference.
+
+A git token Secret stores the encoded value `base64("<user>:<token>")` and presents it as `Basic`. The
+recipe has no base64 step, so encode the pair first. `SecretValue.basicAuth(user, value)` encodes it at
+apply; to store it through the API or the console, encode it yourself:
+
+```sh
+printf 'x-access-token:%s' "$TOKEN" | base64 | tr -d '\n'
+```
+
+```ts
+new Secret(factory, "github-git", {
+  value: SecretValue.basicAuth("x-access-token", SecretValue.fromEnv("ORCHESTRA_FDK_GITHUB_TOKEN")),
+  injection: { headers: [{ name: "Authorization", value: "Basic ${secret}" }], hosts: ["github.com"] },
+});
+```
 
 - **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
@@ -42,8 +62,9 @@ the first declared wins for every request. So scope the API rule to `paths: ["/a
 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.
+`Authorization: Bearer` beside another `PRIVATE-TOKEN`, GitLab answers 401. A personal token works the
+same way. `glab` sends `GITLAB_TOKEN` as `Private-Token`, so set `GITLAB_TOKEN` to the Secret or the
+Connection, and the edge reads the reference there.
 
 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

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

@@ -19,7 +19,7 @@ npx --package @orchestraworks/cli orchestra workflows list --all-pages --output
 npx --package @orchestraworks/cli orchestra connections list --output json
 ```
 
-A row that an apply made carries the label `sfdk.managedBy`, whose value is the factory's name.
+A row that an apply made carries the label `orchestra.managedBy`, whose value is the factory's name.
 
 1. Infer what the developer most likely wants:
    - *No agents and no pipelines:* the account is empty. Infer **a new factory**.

package/skills/orchestra-fdk/references/phases/2-plan.md

@@ -90,7 +90,7 @@ your shell, its browser step hangs. You never read or copy the value.
 
 - *Claude.* `claude setup-token` prints a long-lived token. The developer saves it in the private file as
   `ORCHESTRA_FDK_CLAUDE_CODE_OAUTH_TOKEN`. The factory stores it as a Secret, and the network edge adds it to
-  calls to `api.anthropic.com`. The machine holds only a placeholder token and an empty API key. Declare the
+  calls to `api.anthropic.com` that name it. The machine holds only the Secret's reference and an empty API key. Declare the
   Claude sign-in recipe from `../authoring.md`, "Secrets are recipes, never values". Never put the token in
   the environment's settings: they are stored and shown in plain text.
 - *Codex.* A personal access token, which begins `at-`. A ChatGPT Business or Enterprise member makes it at

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

@@ -83,7 +83,8 @@ C, "Tokens on a compute provider's machines").
 
 - A `401` from the model provider, or "Invalid API key": the agent has no model key. Check the route the
   team chose: the environment's `env`, the image's worker service environment (on Windows, the
-  `SfdkWorker` service's `Environment` registry value), or the key file the `onStartAgent` hook writes.
+  `OrchestraWorker` service's `Environment` registry value, or `SfdkWorker` on an image an earlier
+  release built), or the key file the `onStartAgent` hook writes.
 - The image's value is a real key and `env` declares another: the image's value wins. A declared value
   replaces only our image's placeholder.
 - Never restart the worker service to load a key. A restart after the worker registered stops the
@@ -109,7 +110,7 @@ C, "Tokens on a compute provider's machines").
 - A trigger that could not start a session shows the reason on the trigger's `lastDecision`. A work item
   shows a feed note: `No session started for <agent>: ...`.
 - The model gateway answers `403` with `credits_exhausted` or `budget_exceeded`, in the model provider's
-  own error shape, with a `[sfdk]` prefix on the message.
+  own error shape, with an `[orchestra]` prefix on the message.
 - `403` with `PLAN_FEATURE_DISABLED`: the plan does not include the feature. This is not a credit problem.
 
 `maxSessionsPerMachine` is not an error. A session past it starts another machine.

package/templates/bug-fix/main.ts

@@ -68,13 +68,16 @@ const github = new Connection(factory, "github", {
   install: { permissions: ["contents:write"] },
 });
 
-// The edge adds the gateway key on the gateway's host. The runtime image's placeholder key rides x-api-key, and
-// the gateway refuses two keys that disagree, so the recipe removes it.
+// The edge adds the gateway key on the gateway's host. Claude sends the key's reference in x-api-key, and the
+// gateway refuses two keys that disagree, so the recipe removes it.
 const gatewayHost = required("ORCHESTRA_FDK_MODEL_GATEWAY_HOST");
 const gatewayKey = new Secret(factory, "model-gateway-key", {
   value: SecretValue.fromGatewayKey(new GatewayKey(factory, "model-gateway", { displayName: "__FACTORY_NAME__ bug fixing" })),
-  hosts: [gatewayHost],
-  injection: { headers: [{ name: "Authorization", value: "Bearer ${secret}" }], removeHeaders: ["x-api-key"] },
+  injection: {
+    headers: [{ name: "Authorization", value: "Bearer ${secret}" }],
+    removeHeaders: ["x-api-key"],
+    hosts: [gatewayHost],
+  },
 });
 // init-if: anthropic
 

package/templates/engineering-team/lib/environment.ts

@@ -59,9 +59,12 @@ export function declareKeys(factory: Factory): Keys {
     name: "Model gateway key",
     description: "Added to model calls at the network edge. The agents never see it.",
     value: SecretValue.fromGatewayKey(gatewayKey),
-    hosts: [DEFAULT_MODEL_GATEWAY_HOST],
-    // The runtime image's placeholder key rides x-api-key, and the gateway refuses two keys that disagree.
-    injection: { headers: [{ name: "Authorization", value: "Bearer ${secret}" }], removeHeaders: ["x-api-key"] },
+    // Claude sends the key's reference in x-api-key, and the gateway refuses two keys that disagree.
+    injection: {
+      headers: [{ name: "Authorization", value: "Bearer ${secret}" }],
+      removeHeaders: ["x-api-key"],
+      hosts: [DEFAULT_MODEL_GATEWAY_HOST],
+    },
   });
   return { modelGateway };
 }

package/templates/engineering-team/package.json

@@ -9,7 +9,7 @@
     "typecheck": "tsc -p tsconfig.json"
   },
   "dependencies": {
-    "@orchestraworks/cli": "^0.5.0"
+    "@orchestraworks/cli": "^0.6.0"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",

package/templates/todo-factory/main.ts

@@ -66,13 +66,16 @@ const github = new Connection(factory, "github", {
   install: { permissions: ["contents:write"] },
 });
 
-// The edge adds the gateway key on the gateway's host. The runtime image's placeholder key rides x-api-key, and
-// the gateway refuses two keys that disagree, so the recipe removes it.
+// The edge adds the gateway key on the gateway's host. Claude sends the key's reference in x-api-key, and the
+// gateway refuses two keys that disagree, so the recipe removes it.
 const gatewayHost = required("ORCHESTRA_FDK_MODEL_GATEWAY_HOST");
 const gatewayKey = new Secret(factory, "model-gateway-key", {
   value: SecretValue.fromGatewayKey(new GatewayKey(factory, "model-gateway", { displayName: "todo-app bug fixing" })),
-  hosts: [gatewayHost],
-  injection: { headers: [{ name: "Authorization", value: "Bearer ${secret}" }], removeHeaders: ["x-api-key"] },
+  injection: {
+    headers: [{ name: "Authorization", value: "Bearer ${secret}" }],
+    removeHeaders: ["x-api-key"],
+    hosts: [gatewayHost],
+  },
 });
 
 // The image tag hashes the runtime image and every file under image/: a rebuilt image under an unchanged tag

package/templates/todo-factory/package.json

@@ -9,7 +9,7 @@
     "typecheck": "tsc -p tsconfig.json"
   },
   "dependencies": {
-    "@orchestraworks/cli": "^0.5.0"
+    "@orchestraworks/cli": "^0.6.0"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",