@orchestraworks/cli 0.5.5 → 0.5.8

package/node_modules/@orchestraworks/client/dist/models/index.js

@@ -83,7 +83,7 @@ __exportStar(require("./CreateDecisionRequest"), exports);
 __exportStar(require("./CreateEnvironmentRequest"), exports);
 __exportStar(require("./CreateFileRequest"), exports);
 __exportStar(require("./CreateGatewayKeyRequest"), exports);
-__exportStar(require("./CreateGroupRequest"), exports);
+__exportStar(require("./CreateImageRequest"), exports);
 __exportStar(require("./CreateMachineAccessTokenRequest"), exports);
 __exportStar(require("./CreateMachineEndpointRequest"), exports);
 __exportStar(require("./CreateMachineEnrollmentRequest"), exports);
@@ -95,11 +95,9 @@ __exportStar(require("./CreateModelConfigRequest"), exports);
 __exportStar(require("./CreateModelProviderKeyRequest"), exports);
 __exportStar(require("./CreateOrganizationInvitationRequest"), exports);
 __exportStar(require("./CreateOrganizationMembershipRequest"), exports);
-__exportStar(require("./CreateOrganizationRequest"), exports);
 __exportStar(require("./CreatePipelineRequest"), exports);
 __exportStar(require("./CreatePipelineWorkflowRequest"), exports);
 __exportStar(require("./CreatePolicyRequest"), exports);
-__exportStar(require("./CreateProjectRequest"), exports);
 __exportStar(require("./CreateProviderConnectionIntentRequest"), exports);
 __exportStar(require("./CreateReplyRequest"), exports);
 __exportStar(require("./CreateRoleRequest"), exports);
@@ -108,15 +106,15 @@ __exportStar(require("./CreateSecretRequest"), exports);
 __exportStar(require("./CreateServiceAccountRequest"), exports);
 __exportStar(require("./CreateSessionRequest"), exports);
 __exportStar(require("./CreateSkillRequest"), exports);
+__exportStar(require("./CreateTeamMembershipRequest"), exports);
+__exportStar(require("./CreateTeamRequest"), exports);
 __exportStar(require("./CreateTriggerRequest"), exports);
 __exportStar(require("./CreateUserGrantRequest"), exports);
-__exportStar(require("./CreateUserRequest"), exports);
 __exportStar(require("./CreateVolumeRequest"), exports);
 __exportStar(require("./CreateWorkItemAction"), exports);
 __exportStar(require("./CreateWorkItemActivityRequest"), exports);
 __exportStar(require("./CreateWorkItemRequest"), exports);
 __exportStar(require("./CreateWorkflowRequest"), exports);
-__exportStar(require("./CredentialBinding"), exports);
 __exportStar(require("./CreditBalance"), exports);
 __exportStar(require("./CreditLedgerEntry"), exports);
 __exportStar(require("./CreditUsageBreakdownLine"), exports);
@@ -138,6 +136,7 @@ __exportStar(require("./DependencyMove"), exports);
 __exportStar(require("./EgressPolicyRule"), exports);
 __exportStar(require("./EmbeddedResourceResource"), exports);
 __exportStar(require("./EntitlementPeriodUsage"), exports);
+__exportStar(require("./EntitlementTeamUsage"), exports);
 __exportStar(require("./Environment"), exports);
 __exportStar(require("./EnvironmentDisk"), exports);
 __exportStar(require("./EnvironmentDiskMount"), exports);
@@ -165,14 +164,9 @@ __exportStar(require("./FilterNode"), exports);
 __exportStar(require("./FramePointAnchor"), exports);
 __exportStar(require("./GatewayKey"), exports);
 __exportStar(require("./GatewayKeyWithToken"), exports);
-__exportStar(require("./Group"), exports);
-__exportStar(require("./GroupMember"), exports);
-__exportStar(require("./GroupMemberAgent"), exports);
-__exportStar(require("./GroupMemberReference"), exports);
-__exportStar(require("./GroupMemberUser"), exports);
-__exportStar(require("./GroupSummary"), exports);
 __exportStar(require("./HealthStatus"), exports);
 __exportStar(require("./IdentitySet"), exports);
+__exportStar(require("./Image"), exports);
 __exportStar(require("./ImageContent"), exports);
 __exportStar(require("./InboundWebhookEdge"), exports);
 __exportStar(require("./InboundWebhookEndpoint"), exports);
@@ -181,6 +175,7 @@ __exportStar(require("./InjectionHeader"), exports);
 __exportStar(require("./InjectionRecipe"), exports);
 __exportStar(require("./InterruptSessionRequest"), exports);
 __exportStar(require("./InterruptSessionResponse"), exports);
+__exportStar(require("./InvitationTeamMembership"), exports);
 __exportStar(require("./LauncherDisk"), exports);
 __exportStar(require("./LauncherInventory"), exports);
 __exportStar(require("./LauncherInventoryEntry"), exports);
@@ -269,7 +264,7 @@ __exportStar(require("./PageEnvironment"), exports);
 __exportStar(require("./PageEvent"), exports);
 __exportStar(require("./PageFile"), exports);
 __exportStar(require("./PageGatewayKey"), exports);
-__exportStar(require("./PageGroupSummary"), exports);
+__exportStar(require("./PageImage"), exports);
 __exportStar(require("./PageMachine"), exports);
 __exportStar(require("./PageMachineAccessToken"), exports);
 __exportStar(require("./PageMachineEnrollment"), exports);
@@ -286,13 +281,14 @@ __exportStar(require("./PageOrganizationInvitation"), exports);
 __exportStar(require("./PageOrganizationMembership"), exports);
 __exportStar(require("./PagePipeline"), exports);
 __exportStar(require("./PagePolicy"), exports);
-__exportStar(require("./PageProject"), exports);
 __exportStar(require("./PageProviderConnectionIntent"), exports);
 __exportStar(require("./PageRole"), exports);
 __exportStar(require("./PageSecret"), exports);
 __exportStar(require("./PageServiceAccount"), exports);
 __exportStar(require("./PageSessionSummary"), exports);
 __exportStar(require("./PageSkill"), exports);
+__exportStar(require("./PageTeam"), exports);
+__exportStar(require("./PageTeamMembership"), exports);
 __exportStar(require("./PageTrigger"), exports);
 __exportStar(require("./PageUser"), exports);
 __exportStar(require("./PageUserGrant"), exports);
@@ -320,7 +316,6 @@ __exportStar(require("./Preferences"), exports);
 __exportStar(require("./PreviewPipelineRequest"), exports);
 __exportStar(require("./PreviewPipelineResponse"), exports);
 __exportStar(require("./Principal"), exports);
-__exportStar(require("./Project"), exports);
 __exportStar(require("./ProposedPipelineWorkflow"), exports);
 __exportStar(require("./Provider"), exports);
 __exportStar(require("./ProviderAutoRespondField"), exports);
@@ -345,7 +340,6 @@ __exportStar(require("./ResourceLink"), exports);
 __exportStar(require("./ResumeMachineResponse"), exports);
 __exportStar(require("./RevertWorkflowRequest"), exports);
 __exportStar(require("./Role"), exports);
-__exportStar(require("./RoleAssignment"), exports);
 __exportStar(require("./RoomToken"), exports);
 __exportStar(require("./RoomTokenRoom"), exports);
 __exportStar(require("./RoomTokenRoomRequest"), exports);
@@ -383,6 +377,8 @@ __exportStar(require("./Statement"), exports);
 __exportStar(require("./StreamedViewStatus"), exports);
 __exportStar(require("./SuspendMachineRequest"), exports);
 __exportStar(require("./SuspendMachineResponse"), exports);
+__exportStar(require("./Team"), exports);
+__exportStar(require("./TeamMembership"), exports);
 __exportStar(require("./TextAnchor"), exports);
 __exportStar(require("./TextContent"), exports);
 __exportStar(require("./TextResourceContents"), exports);
@@ -406,7 +402,6 @@ __exportStar(require("./UpdateConnectorRequest"), exports);
 __exportStar(require("./UpdateDashboardRequest"), exports);
 __exportStar(require("./UpdateEnvironmentRequest"), exports);
 __exportStar(require("./UpdateGatewayKeyRequest"), exports);
-__exportStar(require("./UpdateGroupRequest"), exports);
 __exportStar(require("./UpdateMetricRequest"), exports);
 __exportStar(require("./UpdateModelAliasRequest"), exports);
 __exportStar(require("./UpdateModelConfigRequest"), exports);
@@ -418,13 +413,14 @@ __exportStar(require("./UpdatePipelineRequest"), exports);
 __exportStar(require("./UpdatePipelineWorkflowRequest"), exports);
 __exportStar(require("./UpdatePolicyRequest"), exports);
 __exportStar(require("./UpdatePreferencesRequest"), exports);
-__exportStar(require("./UpdateProjectRequest"), exports);
 __exportStar(require("./UpdateReplyRequest"), exports);
 __exportStar(require("./UpdateRoleRequest"), exports);
 __exportStar(require("./UpdateSecretRequest"), exports);
 __exportStar(require("./UpdateServiceAccountRequest"), exports);
 __exportStar(require("./UpdateSessionRequest"), exports);
 __exportStar(require("./UpdateSkillRequest"), exports);
+__exportStar(require("./UpdateTeamMembershipRequest"), exports);
+__exportStar(require("./UpdateTeamRequest"), exports);
 __exportStar(require("./UpdateTriggerRequest"), exports);
 __exportStar(require("./UpdateUserRequest"), exports);
 __exportStar(require("./UpdateVolumeRequest"), exports);

package/node_modules/@orchestraworks/client/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orchestraworks/client",
-  "version": "0.5.5",
+  "version": "0.5.8",
   "description": "Orchestra public API TypeScript client",
   "author": "Living Computers",
   "repository": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orchestraworks/cli",
-  "version": "0.5.5",
+  "version": "0.5.8",
   "type": "module",
   "description": "The Orchestra command line.",
   "license": "Apache-2.0",
@@ -109,13 +109,13 @@
   },
   "dependencies": {
     "@agentclientprotocol/sdk": "1.3.0",
-    "@orchestraworks/client": "0.5.5",
-    "@orchestraworks/worker": "0.0.139",
+    "@orchestraworks/client": "0.5.8",
+    "@orchestraworks/worker": "0.0.141",
     "commander": "^14.0.0",
     "liquidjs": "^10.28.0"
   },
   "optionalDependencies": {
-    "@orchestraworks/local": "0.0.139"
+    "@orchestraworks/local": "0.0.141"
   },
   "bundleDependencies": [
     "@orchestraworks/client"

package/skills/orchestra/SKILL.md

@@ -34,19 +34,19 @@ Sections:
 ## 1. Organization, member and role
 
 <!-- Sources, on develop at 19459f9ebb: docs/architecture/iam.md:295-332 (six managed roles, their grants,
-agent-worker at agent create, scoped to the agent's project); AGENTS.md "Services And Transactions" (IAM is the
-only access check; an agent is a principal like a user); docs/architecture/multi-tenancy-and-access-model.md:35-47
-(membership gates the organization); docs/architecture/project-axis.md:95-124 and
-platform/.../service/project/ProjectReferenceService.kt:241-245 (project reference directions);
-platform/.../workplane/service/WorkplaneWorkItemService.kt:206,556 (assignee confined to the item's project or
-the shared space). -->
+agent-worker at agent create); AGENTS.md "Services And Transactions" (IAM is the only access check; an agent is a
+principal like a user); docs/architecture/multi-tenancy-and-access-model.md:35-47 (membership gates the
+organization); docs/architecture/project-axis.md (teams, Shared, team memberships, scope coverage); the teams spec,
+docs/specs/2026-10-04_2545_team_and_organization_boundary_spec.md § Team memberships, § Scope coverage, § Using
+credentials and volumes, § Defaults and § Kit. -->
 
 **What it's for.** The organization is the customer's account: everything they build sits in it.
 Roles decide who may do what, so each person and each agent can do its own job and no more.
 
 **What it is.** A *member* is a person, an agent or a service account with a membership in the organization.
-A membership carries *role assignments*, each for the whole organization or for one *project*, a group inside
-the organization. Orchestra ships six roles:
+A *team* is a group inside the organization, and every row, such as an agent or a pipeline, sits in one team.
+Every organization has the team *Shared*, and a row that names no team sits in it. A member holds its roles
+through *team memberships*: one role at one team, or one role at all teams. Orchestra ships these roles:
 
 | Role | Who it is for | What it allows |
 |---|---|---|
@@ -57,20 +57,21 @@ the organization. Orchestra ships six roles:
 | `agent-worker` | Every new agent | Its sessions, work on items, reads. No change to environments, secrets, connections, pipelines, workflows or access. |
 | `agent-manager` | An agent that runs other agents | What `factory-developer` has, without the right to grant people access to their own provider accounts. Reads of the organization's settings only. |
 
-**How it relates.** Access is checked one way only, by these roles: an agent is a member like a person. A new
-agent gets `agent-worker`, in its own project or, for an agent in no project, in the whole organization. A row
-in a project may point at its own project or the shared space; a row in the shared space may point only at the
-shared space. So a shared agent takes items from every project, and an agent in a project takes items only
-from that project.
+**How it relates.** Access is checked one way only, by these roles: an agent is a member like a person. A role
+at a team covers that team's rows. A role at all teams covers every team that is not private, Shared included.
+A role at one team does not cover Shared: a member limited to one team needs a role at Shared to see Shared's
+rows. A new agent gets `agent-worker` at its own team. An agent in a team other than Shared, made by someone
+with a role at Shared, also gets `factory-user` at Shared. An agent may use a secret, connection or volume in
+its own team or in Shared, and no other, unless an access policy allows it.
 
-**In the starter.** The organization has no project. Each of the four agents starts with `agent-worker`. The
-Manager Agent is then given `agent-manager`, because it works in every pipeline and changes the Engineer
-Agents.
+**In the starter.** The organization has Shared alone, and every row sits in it. Each of the four agents
+starts with `agent-worker` at Shared. The Manager Agent is then given `agent-manager` at all teams, because it
+works in every pipeline and changes the Engineer Agents.
 
 **Cannot yet.**
-- The factory code cannot grant a role to an agent. Use the CLI. The role list you send replaces the old one,
-  so keep the old entries.
-- Hide the shared space from people limited to one project. They see its pipelines. This is accepted for now.
+- Declare a person's roles in factory code. An agent's roles are declared as its `memberships`; a person's
+  are given in the console or the CLI.
+- Move a row to another team. Its team is set when it is made; remove the row and make it again.
 
 ## 2. Agent, harness and model
 
@@ -177,7 +178,8 @@ machine carries one agent.
 - *Setup script.* A script that runs once, as root, on each new machine, before the agent arrives and before
   any code is cloned. Bash on Linux, PowerShell on Windows. At most 64 KiB. After 10 minutes the worker
   kills it with every process it started, and the machine fails. A failed script fails the machine. Its
-  output is kept as is, so it must never print a secret. A process the script starts in the background keeps
+  output is kept as is, so it must never print a secret. The edge adds no key to its requests, and it runs
+  without each setting whose value starts `orchestra:`. A process the script starts in the background keeps
   running after the script ends, until the machine stops. Write the script so that it can run again on a
   new machine, over a `/home` that already has files.
 - *Network edge certificate.* The edge re-signs each HTTPS answer with its own certificate authority. The
@@ -230,12 +232,9 @@ data on its own disk.
 - macOS machines that Orchestra launches. A Mac works only as the team's own enrolled machine (section 18).
 - Extra disks on Windows or on an enrolled machine.
 - A launched Windows machine on Windows 11, or on any version other than Windows Server 2025. A customer's
-  Windows image must carry our
-  worker, installed as our Windows runtime assembly installs it (`install-vm-runtime.ps1`, which ends with
-  `orchestra install --role image --yes`). A plain captured Windows VM does not register.
-- Not released yet: a one-command installer that turns a customer's own Windows image into one Orchestra can
-  run. What such an image carries today: the orchestra-fdk skill's `references/environment.md`, "Windows in
-  three stages", stage 2.
+  Windows image must carry our worker, put there by `worker install-machine --cloud azure`. A plain captured
+  Windows VM does not register. The steps: the orchestra-fdk skill's `references/environment.md`, "A team's
+  own image".
 - Not proven yet: the 32 CPU size on production capacity. If an lg machine waits a long time for room, tell the
   Orchestra team.
 
@@ -257,8 +256,8 @@ edge: which sites a machine may reach, and which keys are added on the way. The
 
 **What it is.** An environment's *egress policy* has a *default action*, `allow` or `deny`, and a list of rules.
 Each rule allows or denies requests by host, and optionally by path, method and agent. When several rules
-match, the one with the highest *priority* wins. On a tie, a deny wins, then a rule that adds a key, then the
-rule declared first. When no rule matches, the default action decides.
+match, the one with the highest *priority* wins. On a tie, a deny wins, then the rule declared first. When no
+rule matches, the default action decides. A rule carries no key: it only decides whether a request may leave.
 
 In the kit, `EgressPolicy.allowAll()` opens the default and `denyAll()` closes it. A deny rule has priority 900
 unless you set one, so it wins over the open default and over the usual allow rules.
@@ -266,17 +265,19 @@ 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.** An allow rule can add a secret to matching requests (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`.
+**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
+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.
 
 **In the starter.** Every machine is open to every host, and adds the gateway key on the model gateway's
 host. The starter connects no code host or tracker. A rule added for one later still adds its key: the open
 default allows a host only when no rule matches it.
 
-**Can.** Deny rules by host, path and method; keys added as `Bearer <secret>`, `Basic <secret>`, the bare
-secret in any header, or a full header recipe; Basic auth formed from a user name and a secret
-(`SecretValue.basicAuth`).
+**Can.** Deny rules by host, path and method; keys added by the secret's own header recipe, such as
+`Bearer ${secret}`, `Basic ${secret}` or the bare secret in any header; Basic auth formed from a user name and
+a secret (`SecretValue.basicAuth`).
 
 **Cannot yet.** Any network rule on an enrolled machine (section 18).
 
@@ -290,19 +291,22 @@ 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. An egress rule names it,
-and the network edge adds it to each request that rule matches. This is *credential injection at the network
-edge*.
+**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.
 
-**How it relates.** A secret works only through a network rule (section 5). Never put a key in an
-environment's settings or in instructions: the machine's processes read every setting.
+**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.
 
 **In the starter.** The gateway key's secret only.
 
 **Can.** A secret's value comes from a shell variable at apply (`fromEnv`), from a hidden prompt at apply on a
 terminal (`fromCommandLine`), or from a gateway key the platform mints (`fromGatewayKey`).
 
-**Cannot yet.** Read a value from a file on the developer's computer. Load the file into the shell first.
+**Cannot yet.** Read a value from a file on the developer's computer. Load the file into the shell first. On
+the `individual` plan, apply refuses a Secret and the edge adds no key (`plan_feature_disabled`); the
+organization needs a plan that allows both, such as `enterprise`.
 
 ## 7. Reaching a model: subscription, model gateway or own key
 
@@ -346,8 +350,8 @@ Without it, an agent's first message fails with "Invalid API key".
 **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.
 
-**How it relates.** Each option reaches the model through an ordinary allow rule that adds a secret (sections
-5 and 6). An agent on the model gateway turns it on in its model settings (section 2). An agent on a
+**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
 subscription or its own key turns it off. For plan questions, send the person to **Settings › Plan & usage**
 in the console.
 
@@ -407,8 +411,8 @@ names. Close or move the items and remove those first.
 ## 10. Work item
 
 <!-- Sources, on develop at 19459f9ebb: docs/architecture/work-plane.md:142-160 (item fields; slug from the
-prefix; assignment to an agent, person or group; pinned version), :198-202 (checks: PASS, FAIL, SKIP votes per
-key), :233-245 (groups), :394-405 (assigning an agent starts or wakes its session on the item);
+prefix; assignment to an agent, person or team; pinned version), :198-202 (checks: PASS, FAIL, SKIP votes per
+key), :235 (teams as assignees), :394-405 (assigning an agent starts or wakes its session on the item);
 docs/architecture/api.md:985 (message an agent about an item without handing it over); AGENTS.md "API
 Conventions" (labels are the customer's own tags). -->
 
@@ -416,7 +420,7 @@ Conventions" (labels are the customer's own tags). -->
 where it stands, what the agents said, and whether it passed its checks.
 
 **What it is.** An *item* sits in one pipeline, at one stage, with a slug such as `bug-12`, a title and a
-description. It can be *assigned* to an agent, a person or a group. Assigning an agent starts its conversation
+description. It can be *assigned* to an agent, a person or a team. Assigning an agent starts its conversation
 on the item, or wakes its open one. *Labels* are the customer's own key-to-value tags; the platform gives no
 label a meaning. *Checks* are votes on a named key, such as `tests`: each writer votes `PASS`, `FAIL` or `SKIP`,
 and a stage's conditions can read them.
@@ -478,7 +482,7 @@ switching a listener on.
 File is stored bytes; a Skill is a set of files by reference with a root SKILL.md carrying name and
 description; an agent references up to 32 skills), :762-770 (global skills); docs/architecture/artifacts.md:36-44
 (File under everything). Kit: cli/src/constructs/skill.ts (declare a Skill in code); cli/src/cli/upload.ts
-(--file); platform/.../service/FileService.kt:163-165 (no projectId means the shared space);
+(--file); platform/.../service/FileService.kt:163-165 (no team means Shared);
 platform/src/main/resources/catalog/skills/ (the platform's own skills, served as skill_<key>);
 cli/src/constructs/skill.ts:111 (Skill.fromId). -->
 
@@ -513,7 +517,7 @@ declares either stops with a plan error.
 ## 15. The factory as code
 
 <!-- Sources: on develop at 19459f9ebb, docs/architecture/fdk-agent-as-code.md:702 (the approval policy), :785
-(apply order), :821 (what apply sets back); cli/src/core/factory.ts (one project, one Factory per program);
+(apply order), :821 (what apply sets back); cli/src/core/factory.ts (one Factory per program, any number of teams);
 cli/src/constructs/ (what the kit declares). On the kit's own branch: cli/src/cli/factory/init.ts and
 docs/architecture/fdk-agent-as-code.md:2963-2972 (init --template copies a starter into a folder with no
 package.json). -->
@@ -522,7 +526,8 @@ package.json). -->
 code is the truth, and the platform is made to match it.
 
 **What it is.** A program that declares the factory: agents, environments, secrets, gateway keys, provider keys,
-pipelines, workflows, triggers, skills, connections and projects.
+pipelines, workflows, triggers, skills, connections, teams, custom roles and agents' role rows. A row's `team:`
+names its team, and a row with none sits in Shared.
 
 - `orchestra fdk init` writes the bug-fix starter. `orchestra fdk init --template engineering-team` writes the
   engineering team starter, and `--template todo-factory` the todo app sample, into a folder with no
@@ -536,8 +541,7 @@ pipelines, workflows, triggers, skills, connections and projects.
 **Cannot yet.**
 - Keep a change made in the console or by an agent to something declared in code. The next apply sets it back.
   Write the change into the code.
-- Declare work items or role grants. Use the CLI.
-- More than one project in one program.
+- Declare work items or a person's roles. Use the console or the CLI.
 - Answer apply's question without a terminal. Show `diff` to the person, and after they approve the same change
   list, apply with `--require-approval never`.
 
@@ -545,7 +549,8 @@ pipelines, workflows, triggers, skills, connections and projects.
 
 <!-- Sources, on the kit's own branch: cli/src/cli/main.ts:60-160 (two jobs; nouns match API paths; standard
 verbs; --output json; --body @file.json; approval defaults; orchestra api), cli/src/cli/core/auth.ts:1-45
-(ORCHESTRA_API_TOKEN, then the login profile, then the machine's edge; ORCHESTRA_BASE_URL),
+(ORCHESTRA_API_TOKEN, then the file ORCHESTRA_API_TOKEN_FILE names, then the login profile, then the machine's
+edge; ORCHESTRA_BASE_URL),
 cli/src/cli/core/profile.ts:39-52 (profiles in ~/.config/orchestra/config.json), cli/src/generated/cli-commands.json
 (each command's answer), cli/src/cli/core/output.ts:94-113 and :143-145 (json prints the answer as it is),
 cli/src/cli/core/errors.ts:287-296 and :366-370 (the json error, on stderr), cli/src/cli/core/login.ts:361-363 (a
@@ -577,8 +582,12 @@ each part at length. What follows is only what a reader needs to run a command s
   `~/.config/orchestra/config.json`. It selects the person's organization when they have one; with several,
   name it: `orchestra auth login --org <organization>`. The browser sign-in renews itself. A token typed at the
   `--no-browser` prompt cannot renew itself, so it suits a short run only.
-- **Scripts.** `ORCHESTRA_API_TOKEN` and `ORCHESTRA_BASE_URL` in the shell are used before the profile. On an
-  Orchestra machine, the network edge signs the agent's calls, so it needs no token.
+- **Scripts.** `ORCHESTRA_API_TOKEN` and `ORCHESTRA_BASE_URL` in the shell are used before the profile.
+- **On an Orchestra machine.** The worker writes the agent's own token to a file, renews it, and names the
+  file in `ORCHESTRA_API_TOKEN_FILE`. `orchestra` reads that file before each request, so the agent needs no
+  sign-in. Where a network edge stands in front of the machine, the edge replaces that token with one for the
+  same agent. A 401 here is not fixed by `orchestra auth login`: the token expired before the worker renewed
+  it, or the agent is no longer placed on the machine.
 - **Fallback.** `orchestra api <METHOD> </path>` makes a raw call when a typed command is missing.
 
 A first look at an organization, in the order a new reader runs it:
@@ -663,22 +672,28 @@ the proven list is the test run of 2026-10-05. -->
   it, so its network rules may only allow. Not released yet: our network edge for machines in the team's
   own network.
 - Credentials on a Launcher machine are the team's to manage on the machine. The platform delivers none.
-  - The model sign-in goes in the worker service's own environment: `ORCHESTRA_WORKER_CLAUDE_OAUTH_TOKEN`
-    for a Claude subscription token; `ANTHROPIC_API_KEY` for an Anthropic API key or an Orchestra gateway
-    key, which replaces our image's placeholder; `ORCHESTRA_WORKER_OPENAI_API_KEY` or
-    `ORCHESTRA_WORKER_CODEX_PERSONAL_ACCESS_TOKEN` for `codex`. On Windows, that is the `SfdkWorker`
-    service's `Environment` registry value.
-  - With a gateway key, keep the agent's model gateway on. The platform sets the gateway address.
-  - Other tokens, such as git, a package feed or an Azure DevOps personal access token: the team's own boot
-    step sets them, for example from their Key Vault with a managed identity on the VM.
-  - The worker reads its environment when its service starts. The boot step runs before the worker starts,
-    or restarts the worker service after. On our Windows image, the startup task `orchestra-azure-userdata`
-    starts `SfdkWorker`.
-  - Never put a token in `provisionSpec.env` (`env` in the kit). The platform stores it, an environment
-    read returns it, and it travels in plain text in the VM's startup data.
+  - The model key reaches the agent in one of three ways, on every machine, 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`). 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`.
+    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.
+  - The names: `ANTHROPIC_API_KEY` for an Anthropic API key or an Orchestra gateway key;
+    `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.
+  - 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
+    machines".
   - The Launcher attaches no managed identity to the VMs it creates. The tags `orchestra-launcher` (the
     record's id) and `orchestra-machine` (the machine's id) let the team's automation find them. Not
-    released yet: a managed identity attached when the Launcher creates a VM.
+    released yet: a VM target's `userAssignedIdentities` (identity resource ids), which the Launcher
+    attaches at create; its own identity needs Managed Identity Operator on each.
 - Proven on Orchestra's test environment with a new Launcher 0.1.0, a team's own Windows image and the
   `Dsv6` size family:
   - A `claude` turn ran. It reached the model through an Orchestra gateway key, with no network edge.