@orchestraworks/cli 0.5.0 → 0.5.1

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**,

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.