@orchestraworks/cli 0.3.0 → 0.5.1

package/docs/REFERENCE.md

@@ -0,0 +1,1278 @@
+# orchestra: the full reference
+
+The full developer guide for `@orchestraworks/cli`: the agent-as-code kit and its `orchestra` CLI.
+The short introduction is the package [README](../README.md).
+
+> This guide assumes you already have a **running** orchestra platform to target (SaaS or self-hosted):
+> `ORCHESTRA_BASE_URL` points at it, and you hold an API token. It does **not** cover standing up a
+> local stack.
+
+## 1. What is orchestra
+
+orchestra is CDK for your software factory: you declare agents, environments, secrets, connections, and
+workflows as typed TypeScript constructs and apply them to build one. `synth` compiles them into a
+deterministic, value-free plan; `apply` reconciles that plan against the platform's **public APIs**
+(last-writer-wins on the fields you manage — orchestra makes no platform changes). Like CDK, construct
+paths derive stable logical ids, and the plan is a reviewable artifact you can commit and diff. That
+model in condensed form — the construct tree, the loop, and the six design principles that settle
+design questions — ships with the kit in
+[`skills/orchestra-fdk/references/authoring.md`](../skills/orchestra-fdk/references/authoring.md), beside the
+two skills [`skills/orchestra/SKILL.md`](../skills/orchestra/SKILL.md) and
+[`skills/orchestra-fdk/SKILL.md`](../skills/orchestra-fdk/SKILL.md); §2 links both into your own coding harness.
+
+## 2. Prerequisites & install
+
+- **Node ≥ 22** (see `engines` in `package.json`).
+- **A `package.json` in the folder you install into.** In a new folder, run `npm init -y` before installing
+  the kit. Without one, npm installs into the nearest parent folder that has one.
+
+The kit is published as `@orchestraworks/cli`. Install it globally, which puts `orchestra` on your path:
+
+```bash
+npm install -g @orchestraworks/cli
+```
+
+Run every command from the **factory directory** (the one holding `fdk.json`).
+
+### Teach your coding agent: `orchestra skills install`
+
+The kit ships two skills. `skills/orchestra/SKILL.md` is the general reference: the platform's ideas, how
+the CLI works, what the platform cannot do yet, and where an agent's knowledge belongs.
+`skills/orchestra-fdk/SKILL.md` builds and applies a factory for an existing codebase, with the authoring
+reference and environment porting in its `references/` folder. Hand them to your coding agent once:
+
+1. Install the CLI globally: `npm install -g @orchestraworks/cli`.
+2. Link both skills into your harness, naming the harness and the scope:
+
+   ```bash
+   orchestra skills install --harness claude --scope user
+   ```
+
+   `--harness` is `claude`, `codex` or `both`. Both flags are required, because a coding agent has no
+   terminal to answer a question.
+3. Read the `SKILL.md` in each skill folder the command prints. A harness loads a new skill only at its next
+   start, so read them now.
+4. `npm update -g @orchestraworks/cli` keeps the CLI and both skills current.
+
+The command **links** each skill under its own name — `orchestra` and `orchestra-fdk` — into the harness's
+skills folder (Claude Code → `.claude/skills/`; Codex → `.agents/skills/`), from the package that runs it.
+It never copies: a copy silently rots, while a link keeps teaching whatever the last update installed. Every
+destination is checked before anything is created, so one blocked path means no link is made; an occupied
+path is refused with the remedy rather than overwritten, and a dead link left by a package relocation is the
+one thing it repairs. `--scope project` links into this project and is accepted only when the kit is
+installed in this project. `--harness other` prints both skills' paths instead of linking. A run from npm's
+`npx` cache is refused, because npm may clean that cache at any time. Nothing here touches the platform.
+
+## 3. Authenticate
+
+The CLI is **identity-agnostic**: it sends the methods, and the platform's IAM decides what the caller
+may do. It never inspects what kind of bearer it holds. `login` is the one exception, and only at
+**persist** time — it refuses to save an **agent runtime token** (recognizable by its `sfagt_v1~` prefix)
+as a workstation profile, because a profile is meant to be a durable operator identity.
+
+**Interactive (`login`)** — for a workstation:
+
+```bash
+orchestra auth login                # browser sign-in (the default)
+orchestra auth login --no-browser   # paste an existing API token instead
+```
+
+By default `login` **opens your browser**: it prints a sign-in URL and opens it, catches the redirect on
+a loopback port it holds for the duration, exchanges the result for a token pair, confirms which
+organization the profile is for, and saves a `0600` profile to `~/.config/orchestra/config.json`. Because
+that profile carries a **renewal credential**, ordinary commands keep working after the short-lived
+access token expires — the CLI refreshes silently, both before a command runs and on a 401 mid-flight.
+
+The browser has to run on **the same machine as the CLI**: the sign-in returns to a local address only
+that machine can reach. Over SSH or from a container, forward the printed port to your own machine, or
+use the paste flow.
+
+**`login` never asks which platform to sign in to.** It resolves the address from four tiers, in order —
+`--base-url`, then `ORCHESTRA_BASE_URL` (or `PLATFORM_BASE_URL`), then the base URL already stored in the profile you are logging
+into (so re-running `login` stays on that profile's platform), and otherwise the built-in default
+`https://api.orchestraworks.ai` — and prints the address in effect, with where it came from, as its first line:
+
+```text
+Platform: https://api.orchestraworks.ai (default — override with --base-url or ORCHESTRA_BASE_URL)
+```
+
+Another deployment — a staging platform, a local dev stack — is reached by **overriding**, never by being
+asked: `ORCHESTRA_BASE_URL=https://…` or `--base-url https://…`. If the address in effect answers nothing
+(no DNS record, nothing listening), `login` says exactly that, names the address and where it came from,
+and points at the two overrides — it does not report a bare network error.
+
+**With `ORCHESTRA_API_TOKEN` set, only the two explicit tiers may name the platform.** That token already belongs
+to one deployment and `login` cannot tell which, so it will not infer an address for it from your stored
+profile or from the default — sending an exported token to the wrong platform would disclose it there.
+Name the deployment with `--base-url` or `ORCHESTRA_BASE_URL`, or the login is refused before anything is
+sent. A token you *paste* at the hidden prompt keeps all four tiers: you are at the terminal, reading the
+address on screen before you type.
+
+`--no-browser` is the paste flow: a hidden prompt for an existing API token (nothing you type is
+echoed), validated against `GET /organizations` (confirming the org is one of your memberships) and
+stored the same way. A pasted token cannot renew itself. With `ORCHESTRA_API_TOKEN` set, a bare `orchestra auth login`
+stores that token and never opens a browser.
+
+`--profile <name>` stores/reads named profiles. `--org <id>` (or `ORCHESTRA_ORGANIZATION_ID`) names the
+organization the profile is for, and **the two flows ask for it differently**: after a browser sign-in a
+lone membership is selected for you and several prompt you to choose — with no terminal to ask at, that
+login refuses and tells you to pass `--org`. The paste flow neither selects nor checks for a terminal: it
+asks for an organization id every time one was not supplied, however many you belong to, so a
+non-interactive `--no-browser` (or `ORCHESTRA_API_TOKEN`) login must pass `--org`/`ORCHESTRA_ORGANIZATION_ID` itself.
+The organization's slug is accepted wherever its id is.
+There is **no `--token` flag** in any spelling — a token on the command line is visible in `ps`, in shell
+history and in CI logs.
+
+**CI / env** — no `login` needed:
+
+```bash
+export ORCHESTRA_BASE_URL="https://factory.example.com"
+export ORCHESTRA_API_TOKEN="…"            # any principal's bearer; the CLI never inspects it
+export ORCHESTRA_ORGANIZATION_ID="org_…"
+```
+
+**The auth-provider chain** (one ordered chain for every command, presence is selection):
+`ORCHESTRA_API_TOKEN` → the `login` profile → the platform-injected machine edge flag
+(`SFDK_AUTH_EDGE_INJECTED`, which makes the CLI send the request **bare** so the egress edge
+stamps the agent's authorization — no credential ever enters the machine) → a named
+missing-credentials error. There is **no `--token` flag**: a token never appears in argv.
+
+**Resolved alongside the chain, per field:** the base URL (`--base-url` → `ORCHESTRA_BASE_URL`, then `PLATFORM_BASE_URL` → profile;
+`login` alone adds the built-in default as a fourth tier, because it is the command that has no profile
+to read yet — every other command needs one of the three, and says so if it has none)
+and the organization (`--org` → `ORCHESTRA_ORGANIZATION_ID` → profile; under the edge provider the organization
+rides the stamped identity server-side). Every authenticated request requires HTTPS or loopback — the
+bearer is itself a credential — with the unauthenticated `health` ping the one exemption. `diff`/`apply`
+print the resolved target org as a banner before any read/write, and warn when an exported
+`ORCHESTRA_ORGANIZATION_ID` diverges from the profile's org (so a stale export can't silently redirect writes).
+
+The conversation (`SFDK_SESSION_ID`, under every provider). The worker sets it on each harness process
+it starts, so a command an agent runs knows which conversation it is in. When it is set, `orchestra` adds
+`sessionId` to every JSON request body that has none: typed commands, `orchestra api`, `apply`, and the
+`login` and refresh token requests. A body that already names a `sessionId` is sent unchanged, so
+`artifacts create --session-id <id>` wins. Query strings, uploads and other non-JSON bodies are never
+changed, and an empty or whitespace-only value counts as unset. The platform checks a supplied session as
+usual. An artifact takes its project from the session, so a command that must publish into another project
+than its conversation's runs without the variable: `env -u SFDK_SESSION_ID orchestra artifacts create …`. A
+value you export by hand in your own shell applies the same way.
+
+## 4. Author your first factory
+
+### Start from the bug-fix starter: `orchestra fdk init`
+
+In a new folder beside your codebase:
+
+```bash
+npm init -y
+npm install @orchestraworks/cli
+npx orchestra fdk init --repository acme/shop
+npm install
+```
+
+`init` writes a bug-fix factory for that GitHub repository: `fdk.json`, `main.ts`, the machine image
+(`image/Dockerfile` and a setup script, `image/setup.sh`, that starts Docker on each machine), the agent's
+standing instructions (`agents/bugfix.md`) and an empty codebase skill (`skills/codebase/SKILL.md`). It sets
+`"type": "module"` in `package.json` and adds `tsx` to its development dependencies, keeping every other key.
+`--model-key anthropic` or `--model-key openai` adds your organization's own model key as a
+`ModelProviderKey`, and `openai` also selects the `codex` harness; without it the agent runs on credits
+through the model gateway.
+
+It touches no platform and overwrites nothing: when a file path it would write already exists, a folder path it
+would write into is not a folder, or a link sits at either or at `package.json`, the folder has no
+`package.json`, or `package.json` does not list the kit or lists a package other than the kit and `tsx`, it
+names each one and writes nothing. It then prints the next steps: `npm install`, the shell inputs `main.ts`
+reads and signing Docker in to the image registry, `npx orchestra fdk diff`, and `npx orchestra fdk apply`, which prints the
+GitHub App install link and waits for you to install it. The `orchestra-fdk` skill (§2) takes a coding agent through
+fitting a starter to your codebase.
+
+### Start from another starter: `orchestra fdk init --template <name>`
+
+The kit carries more than one starter. `engineering-team` is a factory for one engineering team: a Manager
+Agent and Engineer Agents sm, md and lg, their machines, and four pipelines. A starter other than `bug-fix`
+brings its own `package.json`, so run it in a new, empty folder, with nothing installed:
+
+```bash
+mkdir factory && cd factory
+npx --package @orchestraworks/cli orchestra fdk init --template engineering-team
+npm install
+```
+
+It copies the starter's files as they are and fills nothing in, so `--repository` and `--model-key` are
+refused with it. It refuses an unknown name and lists the starters the kit carries. It overwrites nothing:
+when a file path it would write exists, a folder path it would write into is not a folder, or a link sits at
+either, `package.json` included, it names each one and writes nothing. Then read the
+`README.md` it wrote, which names the values to fill in and the steps to run.
+
+### The factory program
+
+A factory program is an ordinary Node program. Two files:
+
+`fdk.json` — names the command that runs the factory program:
+
+```json
+{ "factory": "npx tsx main.ts" }
+```
+
+`main.ts` — the declarative definition (imports are exactly what `orchestra` exports):
+
+```ts
+import {
+  Agent,
+  EgressPolicy,
+  Environment,
+  Factory,
+  Image,
+  Secret,
+  SecretValue,
+  bearer,
+} from "@orchestraworks/cli";
+
+const factory = new Factory({ name: "acme-support" });
+
+const openaiKey = new Secret(factory, "openai-api-key", {
+  name: "OpenAI API key",
+  value: SecretValue.fromEnv("OPENAI_API_KEY_VALUE"), // value read from env at apply — never in the plan
+});
+
+const runtime = new Environment(factory, "runtime", {
+  name: "Support agent environment",
+  image: Image.fromTag("acme/support-agent:1.0.0"),
+  platform: { os: "linux", arch: "amd64" },
+  resources: { cpu: "2", memory: "4G" }, // an Agent Compute Capacity: cores : 2 G per core
+  env: { LOG_LEVEL: "debug" }, // plaintext configuration for the agent process — NOT a secret store:
+                               // these values are stored unencrypted and returned by every read, so a
+                               // credential belongs in a Secret bound to an egress allow rule instead.
+  egress: EgressPolicy.denyAll().allow("openai-model-api", {
+    hosts: ["api.openai.com"],
+    priority: 300,
+    credential: bearer("Authorization", openaiKey), // binds the Secret to an injected header
+  }),
+  ingress: [{ name: "web", port: 3000 }],
+});
+
+new Agent(factory, "agent", {
+  name: "Support Agent",
+  environment: runtime,
+  harness: "claude", // required: which harness family answers this agent's turns
+  instructions: "You are a support agent. Keep raw credentials out of logs and outputs.",
+});
+```
+
+- **ESM factory program.** The program runs as an ES module, so its own `package.json` must declare `"type": "module"`
+  (the in-repo example carries it). Without it, a fresh out-of-repo consumer — `npm init -y` defaults to
+  CommonJS — fails at the very first `import` with `ERR_PACKAGE_PATH_NOT_EXPORTED`, because the package
+  `exports` map exposes only an `import` condition for `"."`. (Two files are orchestra-specific; the program still
+  needs an ordinary ESM `package.json` alongside them.)
+- **Construct id → slug.** With no explicit `slug`, the slug is the **factory name + full construct path**,
+  kebab-joined: the secret above becomes `acme-support-openai-api-key`, the environment
+  `acme-support-runtime`, the agent `acme-support-agent`. Every derived slug must be ≤ 60 chars and match
+  `^[a-z0-9]+(-[a-z0-9]+)*$`; synth fails loudly (no silent hashing) if it doesn't.
+- An explicit **`slug`** prop is verbatim — no namespace, no transformation.
+- Renaming the factory or any path segment means **"new resource"** (the old slug becomes an orphan).
+- Passing a construct object where a reference is expected *is* passing the reference; there is no `.ref`.
+
+### The durable home: state that survives a machine recycle
+
+An environment's **durable home** is one volume mounted at `/home`. It is what makes a conversation
+continue: the agent's own state directory lives under `$HOME`, so when a machine is reclaimed and a later turn
+revives it, the agent replays its history instead of starting over. `/home` is the path because that is where
+the account inside the runtime image has its home directory — the platform sets no `HOME` of its own, so
+mounting a volume at the account's home is what makes that home durable.
+
+There is no dedicated prop for it. `/home` is an **ordinary volume mount** — the same `volumeMounts` array
+as any other path, and the same reference rules:
+
+```ts
+new Environment(factory, "runtime", {
+  image: "acme/support-agent:1.0.0",
+  egress: EgressPolicy.denyAll(),
+  volumeMounts: [
+    { volume: Volume.fromSlug(factory, "support-home"), mountPath: "/home" },
+    { volume: Volume.fromSlug(factory, "cache-vol"), mountPath: "/var/cache" },
+  ],
+});
+```
+
+**Declare no `/home` mount and the environment keeps no durable home** — every machine it starts begins with a
+fresh home directory, which is the right choice for a stateless environment. Nothing is derived on your
+behalf either way: the mount list you write is the mount list that applies.
+
+The platform sets neither `HOME` nor `USERPROFILE`. You may declare `HOME` in the environment's `env` map to
+point the harness at a different directory, and it will conform to that or complain — but a home off the
+mounted volume is a home that does not survive a machine recycle.
+
+A `Volume` is a platform resource orchestra only **references**, exactly like an image tag — orchestra never creates
+one. Create it first, then mount it:
+
+```
+orchestra volumes create --name "Support agent home" --slug support-home --size 50G
+```
+
+Then reference that slug with `Volume.fromSlug(factory, "support-home")`. Because a mount is plain desired
+state, editing the list converges the ordinary way: add an entry and the next apply mounts it, remove one
+and the next apply unmounts it. Removing a `/home` mount **detaches** the volume — it is kept, stays listed
+under `/volumes`, and never loses its data.
+
+### Declared images: `Image.fromTag` vs `Image.fromBuild`
+
+`Image.fromTag("acme/support-agent:1.0.0")` is a pure reference — the tag rides the environment payload
+and you build/push the image yourself. `Image.fromBuild` instead declares an image the factory builds
+and `apply` publishes for you (single build step — the Dockerfile pins its base in `FROM`):
+
+```ts
+const factory = new Factory({ name: "acme-support" }); // MUST precede any fromBuild call
+
+const agentImage = Image.fromBuild({
+  dockerfile: "../Dockerfile",                            // required, relative to the factory dir
+  context: "../../../..",                                 // optional, relative to factory dir; default "."
+  tag: process.env.ORCHESTRA_FDK_AGENT_IMAGE ?? "ghcr.io/acme/support-agent:1.4",
+  // platform: "linux/amd64",                             // optional: docker build --platform target
+  // buildArgs: { SOME_VERSION: "9.5.1" },                // optional, rare: genuine build parameters only
+});
+// … image: agentImage,
+```
+
+| Prop | Required | Meaning |
+| --- | --- | --- |
+| `dockerfile` | yes | Dockerfile path, relative to the factory dir (may escape it, e.g. `../Dockerfile`). |
+| `context` | no | Build context, relative to the factory dir; defaults to `"."`. |
+| `tag` | yes | Image tag (≤ 512 chars); flows to the environment payload byte-identically to `fromTag`. |
+| `platform` | no | `docker build --platform` target (e.g. `"linux/amd64"`). Absent leaves the invocation unchanged; set it to push a cross-architecture manifest — e.g. an arm64 workstation building the amd64 image the target machines pull. |
+| `buildArgs` | no | `--build-arg` values. **Non-secret only** — recorded verbatim in `plan.json` and committed snapshots, so a secret here lands in a committed artifact; a high-entropy value triggers a `warnings.json` warning naming the key. Use a BuildKit `--secret` mount outside orchestra for secret build inputs. |
+
+`new Factory(...)` must run **before** any `fromBuild` (the options-only call resolves the active
+factory via a process singleton). Two `fromBuild` calls with the same tag are a synth error.
+
+### Two starting points: `EgressPolicy.denyAll()` and `EgressPolicy.allowAll()`
+
+`EgressPolicy.denyAll()` refuses every host no rule allows; `EgressPolicy.allowAll()` allows every host no
+rule refuses. Every rule form folds onto either one the same way: a credentialed allow rule still injects its
+credential at the edge, and a `deny` still refuses. A first factory starts open, since a first run fails far
+more often on a blocked host than on anything else, and tightens once runs succeed: read which hosts the agent
+reached, switch to `denyAll()`, and allow those.
+
+```ts
+egress: EgressPolicy.allowAll()
+  .applyPreset(github.egressPolicy())                                // the connection's credentialed rules
+  .deny("no-hosted-data", { hosts: ["*.supabase.co", "db.acme.example"] }), // keep the team's real data out
+```
+
+Open egress opens hosts, not ports: a service on another port still needs a rule naming `host:port`.
+
+### Egress allow rules: paths and multiple credential bindings
+
+`EgressPolicy.denyAll().allow(name, rule)` opens one named outbound rule. Beyond `hosts` and
+`priority` it takes:
+
+- **`paths?: string[]`** — path globs the rule matches; default `["*"]` (all paths). Scope a rule to a
+  subtree with e.g. `paths: ["/backend-api/*"]`.
+- **`credential?: ICredentialBinding`** — a single credential: a bare `Secret` (its own `injection`
+  recipe supplies the headers), or a `bearer`/`basic`/`header`/`inject` binding (see §6).
+- **`credentials?: ICredentialBinding[]`** — several credentials injected on one request, for a
+  destination that needs more than one credential header. Both must ride **one** rule: the platform egress
+  matcher selects exactly one rule per (destination, path, method) and hydrates once per request, so
+  co-required headers cannot be split across two rules.
+
+Every entry is an `ICredentialBinding` — a `Secret`/import or a factory result, never a plain object
+literal. Valid credential shapes are **neither** (a credential-free allow — e.g. `allow(connection)`),
+**one `credential`**, or a **non-empty `credentials` list**. Setting both forms, passing an empty
+`credentials` array, or listing case-insensitively duplicate header names is a **synth error** (a
+duplicate would silently drop a binding at broker hydration). A recipe binding (a bare `Secret` or an
+`inject()` override) names no header of its own — its `injection` recipe does — so it never participates
+in that uniqueness check; uniqueness still holds across the legacy `bearer`/`basic`/`header` bindings
+beside it.
+
+```ts
+import { bearer, header } from "@orchestraworks/cli";
+
+EgressPolicy.denyAll().allow("chatgpt", {
+  hosts: ["chatgpt.com"],
+  paths: ["/backend-api/*"],
+  priority: 10,
+  credentials: [
+    bearer("Authorization", codexAccess),
+    header("ChatGPT-Account-Id", codexAccount), // raw value, no scheme prefix
+  ],
+});
+```
+
+### Ready-made egress: presets and a connection's own rules
+
+Most of an environment's egress is reachability an app used to type out host by host. Two calls replace
+that, and the line between them is the one rule to remember: **anonymous rules ride presets, credentialed
+rules ride the connection.**
+
+- **`egressPreset.softwareDevelopment()`** — a static bundle of **credential-free** public-internet allows
+  that anyone may apply. A preset is about *reachability*, never credentials.
+- **`connection.egressPolicy(options?)`** — one connection's own outbound surface, compiled from the
+  **provider catalog**: the provider-API rules `allow(connection)` emits, plus the provider's git transport,
+  each bound to that connection's credential.
+
+Both return the same bundle value, and `EgressPolicy.applyPreset(bundle)` folds either onto a policy —
+chainable like `allow` and `deny`:
+
+```ts
+import { EgressPolicy, egressPreset } from "@orchestraworks/cli";
+
+// …in the Environment's props:
+egress: EgressPolicy.denyAll()
+  .applyPreset(github.egressPolicy())               // credentialed: the provider API + the git transport
+  .applyPreset(egressPreset.softwareDevelopment()), // anonymous: registries, public git reads, SaaS reads
+```
+
+**A bundle is not a new concept.** Every entry lands as an ordinary allow rule, in the order you applied
+them, so `plan.json`, `orchestra fdk diff` and the live environment show only rules — there is nothing about presets to
+learn when reading a plan. Priorities arbitrate without you picking numbers: a preset row rides `100`, every
+connection-bundle rule `300`, and a `deny` defaults to `900` — so a credentialed rule always wins a host a
+preset row also opens, and a prohibition wins both. Customization is additive: author more rules beside a
+bundle, and `deny(...)` anything you do not want.
+
+**What `softwareDevelopment()` contains** is what ordinary development actually contacts: package registries
+(npm, PyPI, Maven Central, Go, crates.io, the Gradle plugin portal and wrapper chain), container registries
+(Docker Hub, GHCR), public git reads on GitHub, and read access to widely used development services
+(Atlassian, Zendesk, PagerDuty, Datadog, Sentry, Slack, Notion, Statuspage, Linear). Every row is
+`GET`/`HEAD` except three deliberate, path-scoped POSTs — git's `git-upload-pack` (fetch), Notion's
+query/search, and Linear's `/graphql` — and **no row carries a credential**, so git *push* stays closed and
+a service still needs whatever auth a connection bundle or a Secret-bound rule supplies. It takes no
+arguments today, and each call returns fresh arrays, so two environments applying it share nothing.
+
+**The connection bundle** is available identically on a managed `Connection` and on every import
+(`fromSlug`/`fromId`/`fromEnv`), and it **supersedes a plain `allow(connection)`** — apply one or the other.
+Rule names are connection-qualified, so two connections of the same provider can both hand one environment
+their bundle. Its one option is `git` — `github.egressPolicy({ git: "read" })` — and it applies when the
+provider declares a git transport:
+
+| `git` | What it opens |
+| --- | --- |
+| `"readWrite"` (default) | clone/fetch **and** push — the connection's own authority, because the credential is the real write fence: a token without write scope cannot push whatever the network admits. |
+| `"read"` | clone/fetch only. A push then fails at its *second* request — the `info/refs` discovery `GET` is a read and succeeds, then the push `POST` meets the policy's default deny as a 403. |
+| `"none"` | no transport rules at all, narrowing **only this bundle** — an environment that also applies the anonymous preset keeps public git reads from that preset's own rows. |
+
+Passing `git` to a provider that declares **no** transport is a synth error rather than a silent no-op. A
+grant that needs its own hosts, paths, name or priority stays on `EgressPolicy.allow(connection, …)`, which
+supports all four.
+
+Two authoring notes:
+
+- **Preset rule names are contract, not decoration.** Every row carries a fully-qualified
+  `software-development-*` name, and a bundle is a plain readonly array — so an app that wants a subset
+  filters it by name (`egressPreset.softwareDevelopment().filter((rule) => …)`) rather than the preset
+  growing a parameter. The names stay stable across releases for exactly that reason.
+- **Every rule on one policy must have its own name.** Applying a preset over a rule you already named
+  `software-development-npm` is a **synth error** naming the duplicate — and so is applying the same bundle
+  twice, or applying a connection's bundle beside `allow(connection)`. Two rules under one name cannot apply
+  correctly (which one wins a request is decided by priority and declaration order, never by the name), so
+  the kit refuses instead of shipping the ambiguity.
+
+Why the split is enforced rather than merely conventional — the bundle type has no credential field an app
+could fill in, the priority bands above, and the platform matcher preferring a credentialed rule at an equal
+priority — is in the architecture note `docs/architecture/fdk-agent-as-code.md`, § *Egress bundles*.
+
+### Model traffic through the gateway: `routeModelsViaGateway()`
+
+`EgressPolicy.denyAll().routeModelsViaGateway({ key })` lets the agent reach the platform's model gateway
+with a gateway key it never holds. `key` is the `Secret` whose value is `SecretValue.fromGatewayKey(...)`
+(next section):
+
+```ts
+egress: EgressPolicy.denyAll().allow(github).routeModelsViaGateway({ key: gatewayToken }),
+```
+
+It appends one ordinary allow rule, named `model-gateway` at priority `300`, on the gateway host. The
+rule's binding adds `Authorization: Bearer <your gateway key>` at the egress edge and removes `x-api-key`,
+so the agent calls the gateway with no key and the gateway swaps yours for the provider key.
+
+The rule only adds the key. The agent learns the gateway's address from its own model settings, so set
+`modelSettings: { enableModelGateway: true }` on each agent that routes through the gateway (§ *The model an
+agent runs* below).
+
+Four authoring notes:
+
+- **The host defaults to the production gateway, `models.orchestraworks.ai`.** On any other deployment pass its host:
+  `routeModelsViaGateway({ key, host: "models.<your-deployment>" })`. It must be the host of the gateway
+  address your deployment gives agents, or no rule matches the address the agent dials. A `host` that is not
+  a bare hostname (blank, or carrying a scheme, a path, a port or a `*`) and a missing `key` are synth errors.
+- **Do not tie priorities on the same host.** The name and priority are fixed: another rule named
+  `model-gateway` is a duplicate-name synth error, and if you *also* hand-author an allow rule over the
+  gateway host, give it a different priority. Higher priority is evaluated first; at an equal priority the
+  platform matcher silently takes the first match in declaration order.
+- **Your organization needs secrets and managed egress.** Storing the key needs a plan with secrets, and a
+  rule carrying a credential needs managed egress; without them `apply` fails with a named plan error. An
+  organization on a plan without them, the individual plan among them, puts its gateway key into its
+  runtime itself, in environment variables or by hand; orchestra has no helper for that.
+- **Calling a provider directly is a different thing, and it has no sugar.** If you want the agent to
+  talk straight to `api.anthropic.com` (or any other provider), write the ordinary rule for it and bind
+  *your* credential — `allow("anthropic", { hosts: ["api.anthropic.com"], priority: 200, credentials:
+  [header("x-api-key", myKey)] })`. That path uses your provider account, and it can coexist with the
+  gateway rule: the agent's model settings send its own traffic to the gateway, while the direct rule
+  covers whatever the agent addresses at the provider host itself (a CLI, a raw HTTP call). A direct
+  credential that never seems to fire is usually this, not a bug.
+
+### Gateway keys (`GatewayKey`) and bring-your-own provider keys (`ModelProviderKey`)
+
+`routeModelsViaGateway({ key })` takes the `Secret` holding a gateway key. A key and the `Secret` that
+receives its token are declared as a **pair**:
+
+```ts
+const modelGateway = new GatewayKey(factory, "model-gateway", {
+  slug: "factory-triage",           // optional, as on every construct
+  displayName: "Factory triage",    // optional; defaults to the construct id
+  monthlyCreditCap: 840,            // optional; omitting it leaves a live cap unchanged, not uncapped
+});
+
+const gatewayToken = new Secret(factory, "model-gateway-key", {
+  value: SecretValue.fromGatewayKey(modelGateway), // apply mints the key and writes its token here
+});
+// … then route through it: EgressPolicy.denyAll().routeModelsViaGateway({ key: gatewayToken })
+```
+
+A gateway key's token is shown **exactly once**, at mint, which is why the pair is mandatory: **exactly one**
+`Secret` per key, since zero would discard the token and two would make the write ambiguous. Both are synth
+errors, as is nesting `fromGatewayKey` inside another recipe. There is no importer (an existing key's token
+is unrecoverable) and no in-place rotation — a revoked key permanently reserves its slug, so rotating means
+declaring a **new slug**.
+
+`ModelProviderKey` is the opposite direction — **BYOK**: your organization's own credential for one model
+provider, which the gateway then uses upstream on your behalf.
+
+```ts
+new ModelProviderKey(factory, "fireworks", {
+  modelProvider: "fireworks",                          // the catalog provider — the real uniqueness key
+  credential: SecretValue.fromEnv("FIREWORKS_API_KEY"), // or fromCommandLine() to type it at apply (§6)
+});
+```
+
+It is **not** a `Secret`: the credential is write-only, has no id to bind, cannot be injected at egress, and
+leaves only through the gateway — so nothing in a factory references it (there is no `IModelProviderKey`). The
+platform holds one active key per (organization, provider), so a declaration for a provider that already has
+one **adopts** that row when the declared slug matches and refuses with a named error when it differs.
+
+### The model an agent runs: `modelSettings`
+
+An `Agent` declares the model it runs and the address its model calls go to. Two dials, no image build:
+
+```ts
+new Agent(factory, "fixer", {
+  harness: "codex",
+  environment: runtime,
+  instructions: brief,
+  modelSettings: {
+    model: "accounts/fireworks/models/deepseek-v4p1-flash", // what the harness runs
+    enableModelGateway: true,                               // where it sends its model calls
+  },
+});
+```
+
+- **`model`** is the model name the harness asks for. Omit it and the harness runs its own default.
+- **`baseUrl`** is the origin the harness addresses, without a path (`https://models.example.com`, never
+  `https://models.example.com/` and never a path). Omit it and the harness reaches its vendor's own
+  endpoint.
+- **`enableModelGateway: true`** fills `baseUrl` in with the gateway origin of the platform you are
+  applying to. That address is a property of the deployment, not of your factory, so this is the one way
+  to name it without writing it down. Declaring it *and* `baseUrl` is an apply-time error: one address.
+
+**It names an address, never a credential.** The key the gateway authenticates you with is an ordinary
+egress rule on the agent's environment — a `GatewayKey`, the `Secret` it mints into, and the rule
+`routeModelsViaGateway({ key })` writes on the gateway host — and you declare that yourself, as you would any
+other grant. The two halves are
+independent: an address with no rule that allows it fails at the harness's own HTTP layer, like any other
+denied destination.
+
+Three things worth knowing before you declare one:
+
+- **A `script` or `custom` agent takes no model settings**, because the platform configures no model for
+  either. A block with any member set on one is a `400`; an empty block is accepted on every harness and
+  means "none".
+- **A change takes effect on the agent's next conversation**, not on one already running. The block is
+  versioned content, like `instructions`, so editing it mints a new agent version and the next placement
+  carries it.
+- **Removing a member clears it.** `orchestra` sends the whole block on every apply and compares it in both
+  directions, so deleting `model` from your declaration is an `update` that clears the live value — unlike
+  most fields, where an omitted key means "leave it alone".
+
+## 5. Synth → diff → apply
+
+Run all three from the factory directory. The CLI never rebuilds the plan itself — it spawns your factory program and
+reads back the artifacts it writes.
+
+```bash
+orchestra fdk synth   # local only: no platform access
+orchestra fdk diff    # read-only: compares synth against live platform state
+orchestra fdk apply   # reconciles the platform to the synthesized desired state
+```
+
+- **`synth`** writes `fdk.out/{plan.json, graph.mmd, warnings.json}`. `plan.json` is
+  deterministic and value-free (stable key order, no ids/timestamps/secret values) — safe to commit and
+  review. Output:
+  `Synthesized 3 resource(s) and 0 import(s) to …/fdk.out`.
+- **`diff`** prints per-resource states — `create` / `update` / `refused` / `no-change`, plus
+  `value-write-pending` for a declared secret whose source env var is set, or for a
+  `SecretValue.fromCommandLine` source on a resource that **already exists** (an absent one is simply
+  `create`). A CLI value is unreadable outside the apply prompt, so a metadata-level `no-change` must
+  not hide a pending overwrite. That is followed by an informational orphan report (namespace siblings
+  absent from the plan; never deleted). It mutates nothing and **never prompts**: a CLI-sourced
+  credential is reported, not asked for, and is never an error under `diff`, headless runs included.
+  `refused` is a project-identity conflict: the live row sits in a different project than the one
+  declared, and because a placement is identity (like a slug) orchestra never moves it — `apply` stops at
+  that resource. The printed message names the remedies for that kind: keep the live placement and
+  *reference* the row instead of declaring it (§7, for the kinds that have an importer), or redeclare it
+  under a new slug in the project you intended. Gateway keys, workflows and triggers have no
+  importer, so theirs are the new slug or dropping the declaration and leaving the live row untouched; a
+  conflicted gateway key and its paired secret are redeclared under new slugs together or dropped
+  together, and the paired secret is never imported. A new slug is a **replacement, not a move** — it
+  creates a fresh row in the intended project and leaves the existing one untouched where it is.
+
+  ```
+  Target organization: org_…
+    organization slug: acme
+    create              secret acme-support-openai-api-key
+    create              environment acme-support-runtime
+    create              agent acme-support-agent
+  Diff: 3 to create, 0 to update, 0 refused, 0 secret value write(s) pending, 0 unchanged (synth in …).
+  ```
+
+- **`apply`** prints the org banner, gates any secret writes behind one consolidated confirmation
+  (see §6), then reconciles in dependency order — the `PLAN_KINDS` order (project → secrets →
+  connectors → connections → environments → skills → agents), followed by workflows and then
+  triggers — and writes `fdk.out/result.json`: the resolved `organization`, a `resources` array
+  of `{ path, kind, slug, id, action }`, and value-free `verificationHints`.
+- **Declared-image build phase.** If the plan declares `Image.fromBuild` images, `apply` builds and
+  pushes them **before** reconcile — it is the only docker-touching command (`synth`/`diff` never touch
+  docker). It probes the daemon (`docker info`), builds each image in declaration order, and pushes
+  every ref containing a `/` (a single-segment `foo:local` is local-only and skipped); a push is skipped
+  when a local digest proves the remote tag is already up to date. On a push auth failure it offers an
+  interactive `docker login` recovery on a TTY (credential via stdin, never stored or echoed) and
+  retries once. A build/push failure aborts before any platform write; already-pushed images stay
+  published. Pass **`--no-docker-build`** to skip the phase entirely (CI that only reconciles a
+  pre-published tag, or a docker-less host) — otherwise a missing daemon is a loud failure naming the
+  flag. A factory with no `fromBuild` images never invokes docker.
+
+  ```
+  Applied: 3 created, 0 updated, 0 unchanged.
+  ```
+
+- **`plan.json` is preview-only.** `apply` always re-synthesizes from code and deletes any stale on-disk
+  plan first — a committed or hand-edited plan is never trusted as state. Re-running `apply` with nothing
+  changed reports **all unchanged** (reconciliation is idempotent). A green apply does *not* prove runtime
+  viability (e.g. image pullability) — verify with an end-to-end machine smoke.
+
+## 6. Secrets
+
+A declaration never carries a secret value. It carries a **recipe** naming where the value will come from,
+and there are three kinds of source: read from the environment at apply (`fromEnv`, byte-for-byte with no
+trimming), typed into the terminal at apply (`fromCommandLine`), or minted by the platform itself
+(`fromGatewayKey`, below). The plan carries only the recipe — the env-var *name*, the bare fact that a value
+is CLI-supplied, or the declared key's reference — never a value.
+
+**Secret bytes are never serialized:** not in plan.json, graph.mmd, diff, apply logs, result.json, errors,
+or stack traces. They are never printed **in full** either, with one deliberate exception worth knowing
+about: when you type a credential at the `fromCommandLine` prompt, the reader shows the **first 4
+characters** back to you once you press Enter (and only if what you typed is at least 8 characters long).
+Those 4 characters are on your screen, so a shell transcript, a CI log wrapper or a screen recording
+captures them. That is the only place any part of a secret value reaches a terminal.
+
+### Choosing a source: `fromEnv` vs `fromCommandLine`
+
+```ts
+new Secret(factory, "openai", {
+  value: SecretValue.fromEnv("OPENAI_API_KEY_VALUE"), // exported by you (or CI) before apply
+});
+
+new Secret(factory, "deepseek", {
+  value: SecretValue.fromCommandLine(), // apply asks you to type it
+});
+
+new Secret(factory, "anthropic", {
+  value: SecretValue.fromCommandLine("the org's Anthropic key"), // optional label shown in the prompt
+});
+```
+
+Pick `fromEnv` when a machine supplies the value (CI, a secret manager, your shell profile). Pick
+`fromCommandLine` when a **human** holds the credential and you never want it sitting in an environment
+variable. The declaration says which, so the same factory behaves the same way on every machine — that is
+the whole point of the split.
+
+**`fromEnv` is strict.** A declared env var that is unset, empty, or whitespace-only is an **error** at
+apply, naming the declaration and the variable, identically on your laptop and in CI. Earlier versions of
+orchestra fell back to an interactive prompt when the variable happened to be unset and stdin was a terminal;
+that fallback is **gone**. If you want to be asked, say so with `fromCommandLine`.
+
+| Source env var | Secret on platform | Behavior |
+| --- | --- | --- |
+| set (non-empty) | absent | confirm → create |
+| set (non-empty) | exists | **warn + explicit approval** → overwrite the live value |
+| unset, empty, or whitespace-only | absent | **error** naming the declaration and the variable — on a TTY and headless alike |
+| unset, empty, or whitespace-only | exists | **no-op** — the live value is left alone |
+| **some but not all** parts of a composed value available | any | **error** before any read, so no half-value is composed |
+
+**Strictness is scoped to writes that actually need the value.** An unset variable fails a *create*,
+because the declaration promises a value that is not there. It does **not** fail an apply whose secret
+already exists — that stays a clean no-op, so a factory can be applied from a shell that never exported
+the credential, and "leave the live value alone" remains expressible.
+
+That last table row is about supplying a value *half way*, and it applies to any composed recipe — an
+`ecrCredential` with one of its two variables exported, or one typed leaf beside an unset variable.
+Exporting **none** of them is the no-op above ("leave the live value alone"); exporting **some** of them
+is an error, because the alternative is an apply that reports "unchanged" while quietly keeping the
+value you thought you had just rotated.
+
+**Replacing a live value warns and needs explicit approval.** When the variable *is* set and the secret
+already exists, apply overwrites what is stored — so that write is listed in its own block naming each
+credential whose live value is replaced, and it takes an affirmative of its own. `--approve-secrets` (or
+`ORCHESTRA_APPROVE_SECRETS=true`) pre-approves it for automation; a non-interactive apply carrying such a write
+without it refuses by name rather than proceeding. A credential whose value is **entirely**
+`fromCommandLine` is exempt: it is overwritten every apply by design and you are typing the value at the
+prompt, so typing it is the confirmation. A composed recipe that mixes `fromCommandLine` with `fromEnv`
+is **not** exempt — you are typing one part while a variable supplies the other, and typing your part
+says nothing about that one, so it keeps the warning and the second question.
+
+**The optional label is display text only.** `fromCommandLine("the org's Anthropic key")` puts that text on
+the prompt line in place of the structural description; with no label the prompt names the resource itself.
+Synth rejects a label that is blank, spans more than one line, is longer than 80 characters, or contains
+`${` (the recipe is serialized into the plan, and the graph renderer scans recipes for `${ref:…}` tokens, so
+an unconstrained label could draw a fake edge to a real resource).
+
+**Where a CLI value is asked for, and what you see.** All CLI-sourced credentials are collected in one pass
+that runs **after** the consolidated confirmation below and before the first credential write:
+
+```
+Secret 2 of 3 — deepseek-api-key (the org's DeepSeek key)
+  value: sk-6••••••••••••••••••••••••••••
+  ✓ captured (32 chars)
+```
+
+- Every character **masks while you type**. When you press Enter the line is redrawn with the first 4
+  characters visible — but only if the value is at least 8 characters; anything shorter stays fully masked,
+  so a short credential is never shown in full. The prefix is there so you can tell *which* credential you
+  just typed (`sk-`, `ghp_`, `xoxb`) without revealing it.
+- **Everything the prompt writes goes to stderr** — the heading, the `•` echoes, the 4-character
+  reveal, the `✓ captured` line. stdout is the command's result channel, so redirecting it
+  (`orchestra secrets create --value-from-command-line --output json > key.json`) captures the response
+  document alone, never the prompt or the reveal.
+- `N of M` counts individual values, not resources: a composed recipe with two CLI-sourced parts (an
+  `ecrCredential`, say) asks twice, access key first.
+- Blank or whitespace-only input re-prompts, up to 3 attempts, then fails naming the resource. Ctrl-C or
+  EOF aborts before any credential is written.
+- **Declining the confirmation asks you for nothing at all** — the prompts come after that gate, so a "no"
+  never makes you type a secret for a write that will not happen.
+- **A headless apply fails with a named error** — "this resource declares an interactive credential", not
+  "environment variable unset". `fromCommandLine` needs a terminal by construction; use `fromEnv` in CI.
+- **Every apply re-prompts every CLI-sourced credential.** That is deliberate, and it is the rotation
+  path: retyping the credential rotates it, and there is no flag to discover. (An env-sourced secret works
+  the same way — it is overwritten on every apply where its variable is set.)
+
+`fromCommandLine` is legal anywhere `fromEnv` is legal, including nested inside `basicAuth`,
+`registryCredential` and `ecrCredential`, and as a `ModelProviderKey` credential.
+
+**Where a minted value comes from.** `SecretValue.fromGatewayKey(key)` is the one source whose value the
+platform produces instead of you. A gateway-key-backed Secret therefore has no env var, no prompt and no row
+in the table above: at apply the declared `GatewayKey` (§4) is minted and the token it shows **exactly
+once** is written straight into its paired Secret, by a protocol that marks the Secret *before* minting so
+an interrupted run is detectable rather than silently stranding a token you can never see again. A
+`ModelProviderKey` (§4) writes a credential too — from an ordinary `fromEnv` or `fromCommandLine` recipe —
+but mints no `Secret` at all.
+
+Pending writes are confirmed with **one consolidated value-free table and a `y/N` prompt**, covering all
+three credential kinds: ordinary secrets, gateway-key mints, and model-provider-key credentials. When that
+plan also **replaces the live value** of an existing env-sourced credential, a second `WARNING:` block
+lists those replacements and takes an affirmative of its own — so there are two prompts, and the
+destructive one is answered separately from the routine one. For automation, pass `--approve-secrets` or set `ORCHESTRA_APPROVE_SECRETS=true` — it only suppresses
+the prompt, never widens what is written. Without it, an apply that has pending writes and **no terminal**
+fails by name, listing the writes it did not make: a prompt nobody can answer is refused, never waited on. An apply that declares no `GatewayKey`, no `ModelProviderKey` and
+no CLI source, and has no secret env vars set, never touches a credential value at all. A CLI-sourced write
+shows up in that table before you are asked to type anything, and it travels the same value-safe channel as
+an env value (request body only — never logged, serialized, in `result.json`, or in the plan snapshot),
+behind the same TLS transport guard, which refuses a credential write over non-loopback plain HTTP.
+
+Derived credentials: `SecretValue.basicAuth("x-access-token", tokenValue)` renders
+`base64("x-access-token:<token>")` (the base64 derivation happens only at apply). Bind a rendered value to
+an egress header with `bearer(header, secret)`, `basic(header, secret)`, or `header(name, secret)` — the
+raw binder, which injects the secret value **verbatim** (no `Bearer `/`Basic ` scheme prefix), for a
+destination that wants the credential in a bare custom header.
+
+### Injection recipes: several headers from one secret
+
+Those three binders are all one-header-per-secret. A destination that needs a **set** of headers derived
+from one credential — or that needs a client-sent header **stripped** — declares an `injection` recipe on
+the Secret itself and binds it by passing the bare `Secret` as the credential (no binder call — the
+recipe supplies the headers):
+
+The **Claude sign-in recipe** is the one to copy when the claude harness runs on a person's Claude
+subscription token rather than an API key:
+
+```ts
+import { EgressPolicy, Secret, SecretValue } from "@orchestraworks/cli";
+
+const claudeSignIn = new Secret(factory, "claude-sign-in", {
+  value: SecretValue.fromEnv("SFDK_CLAUDE_CODE_OAUTH_TOKEN"),
+  injection: {
+    headers: [{ name: "authorization", value: "Bearer ${secret}" }],
+    removeHeaders: ["x-api-key"], // stripped before injection, so a runtime placeholder cannot leak
+  },
+});
+
+// …in the Environment's props:
+env: { CLAUDE_CODE_OAUTH_TOKEN: "placeholder", ANTHROPIC_API_KEY: "" },
+egress: EgressPolicy.allowAll().allow("claude-sign-in", {
+  hosts: ["api.anthropic.com"],
+  priority: 300,
+  credential: claudeSignIn, // the bare Secret — its injection recipe supplies the headers
+}),
+```
+
+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.
+
+- **`headers[].value`** templates take `${secret}` (the whole value) or `${secret.<field>}` (a top-level
+  field of a JSON-object secret value); a literal-only value is fine for companion headers.
+- **`removeHeaders`** strips client-sent headers before injection; injecting a header the client also
+  sent replaces it.
+- Synth mirrors the platform's write-time rules: header-name charset, the routing/hop-by-hop denylist
+  (`host`, `content-length`, `transfer-encoding`, `connection`, `te`, `upgrade`, any `proxy-*`), the two
+  placeholder forms, and the caps (≤ 8 header ops, ≤ 8 removals).
+
+The **binding determines application**: a legacy `bearer`/`basic`/`header` binding over a recipe-carrying
+secret is a valid, explicit choice to present that secret as one header (its recipe is not applied on that
+rule). The one remaining synth error is passing a recipe-**less** secret **bare** — there is no recipe to
+apply, so bind it with `bearer`/`basic`/`header` or an `inject()` override instead. `inject(secret,
+recipe)` binds any secret (recipe-carrying or not) under a **binding-owned** recipe that overrides the
+secret's own recipe wholesale — the recipe is validated once at synth and deep-copied into the plan, so a
+later mutation of your input cannot smuggle an unvalidated header. A bare recipe-less check only fires for
+**locally declared** secrets; a `Secret.fromSlug`/`fromId` import carries no visible recipe, so it defers
+to the server.
+
+## 7. Work with existing resources
+
+Reference platform resources you don't manage — they resolve at apply and are never created or mutated:
+
+```ts
+Secret.fromSlug(factory, "shared-openai-key");
+Secret.fromId(factory, "secret_…");
+Agent.fromSlug(factory, "existing-agent");
+Environment.fromSlug(factory, "shared-runtime");
+Volume.fromSlug(factory, "cache-vol");
+Volume.fromId(factory, "volume_…");
+Connection.fromEnv(factory, "SFDK_ZENDESK_CONNECTION_ID", { provider: Providers.Zendesk });
+```
+
+`Connection.fromEnv` resolves the connection id from `process.env` at apply, so **no tenant id
+ever lands in a committed plan** (use it instead of `fromId` when the plan is committed). Imports validate
+at apply: a connection must be `ACTIVE`, and its live provider (plus any declared `install` values) must
+match the declared `{ provider, install? }`; a missing import is a 404 naming the reference source. A secret
+reference that looks like a **raw credential** (fails the id/slug shape allowlist, or matches a
+`sk-`/`ghp_`/`Bearer …` denylist) is **rejected at synth**, before it can be echoed anywhere.
+
+### Connections, triggers, and workflows
+
+Install an external provider as a managed `Connection` (from the generated `Providers.*` catalog), route its
+events with standalone `Trigger` rows — the ONE routing mechanism — and grant the runtime outbound access
+with `env.egressPolicy.allow(connection)`.
+
+Those are the **three statements that wire a connection**, and authoring all three is the model:
+
+| | Statement | What it is |
+|---|---|---|
+| **1. Connection** | `new Connection(factory, …)` | the identity: provider, auth, install, `autoRespond` |
+| **2. Inbound** | `new Trigger(factory, …)` | events → agent or pipeline — **what the agent hears** |
+| **3. Outbound** | `egress.allow(connection)` | agent → provider — **what the agent may say** |
+
+Every connection is wired twice — inbound is what the agent hears, outbound is what the agent may say — and
+both statements are yours. Nothing derives the second from the first, and only the third is invisible when
+forgotten: everything synths, applies and routes, and then the agent's reply gets a 403 from the egress fence
+inside its own machine. Synth warns on that shape (below), but the grant is always authored.
+
+The outbound statement has a fuller form: `egress.applyPreset(connection.egressPolicy())` folds the whole
+surface the provider catalog declares for that connection — the provider API *and* its git transport — on in
+one call, and supersedes `allow(connection)` (§4).
+
+A trigger is flat: `{ on: {connection, events[]} | {schedule}, where[], target }`. The **target** names a
+definition (`Targets.agent` or `Targets.pipeline`, never an instance) plus a **binding** — one render template
+over the raw event payload whose value is the holder key. Equal keys share a holder, so a conversation or a
+work item tracks one provider item for its whole life:
+
+```ts
+import {
+  Auth, Connection, Pipeline, Providers, Targets, Trigger, Workflow,
+  activity, any, assign, check, created, field, message, move, not, rule, scoped, toAssignee,
+} from "@orchestraworks/cli";
+import { Jira, Events as JiraEvents, Bindings as JiraBindings } from "@orchestraworks/cli/jira";
+
+const jira = new Connection(factory, "jira-main", {
+  provider: Providers.Jira,
+  auth: Auth.oauth(), // or customerManagedToken(secret) / webhookSecret() / githubApp() / forgeApp()
+  install: { projectKey: "SF" }, // the generated per-provider install type
+});
+
+// One conversation per Jira issue: created/updated/commented all render the same key, so the agent keeps
+// one session per issue (establish → steer at the turn boundary → wake). `binding` is omitted because the
+// selection's canonical binding (JiraBindings.Issue) already covers it — it materializes into the wire at
+// synth, so `plan.json` shows the truth and the platform never infers.
+new Trigger(factory, "jira-worker", {
+  on: { connection: jira, events: [JiraEvents.IssueCreated, JiraEvents.IssueUpdated, JiraEvents.CommentCreated] },
+  target: Targets.agent(fixer, {
+    successorContext: "SUMMARY",
+    prompt: "Work Jira issue {{event.issue.key}}. Read and update it via the Jira API.",
+  }),
+});
+
+// Work that moves through stages is a pipeline of work items; a workflow is that pipeline's rules. Each rule
+// is named for what it does, verb first.
+const triage = new Pipeline(factory, "triage", {
+  itemSlugPrefix: "tri",
+  stages: [
+    { slug: "fixing", category: "IN_PROGRESS" },
+    { slug: "review", category: "IN_PROGRESS" },
+    { slug: "done", category: "DONE", requires: [{ field: "checks.review.result", op: "is", value: "PASS" }] },
+  ],
+});
+new Workflow(factory, "triage-flow", {
+  pipeline: triage,
+  rules: [
+    rule({ name: "Assign the fixer on arrival", when: created(), then: [assign({ agent: fixer })] }),
+    rule({
+      name: "Relay each comment to the assignee",
+      when: activity("INBOUND_EVENT"),
+      then: [message(toAssignee(), "{{event.payload.comment.body}}")],
+    }),
+    rule({ name: "Send a rejected fix back to Fixing", when: check("review").is("FAIL"), then: [move("fixing")] }),
+  ],
+});
+
+// A pipeline-target trigger creates one work item per key. `where` narrows admission only — it never touches
+// the key. Its entries AND together; `any(...)`, `all(...)` and `not(...)` nest a group, and `and(...)` inside
+// one groups its parts.
+new Trigger(factory, "start-triage", {
+  on: { connection: jira, events: [JiraEvents.IssueCreated] },
+  where: [
+    field("issue.fields.priority.name").oneOf(["Highest", "High"]),
+    any(field("issue.fields.labels").has("customer"), not(field("issue.fields.assignee").exists())),
+  ],
+  target: Targets.pipeline(triage, {
+    binding: JiraBindings.Issue,
+    onMissing: "START_NEW",
+    title: "{{event.payload.issue.fields.summary}}",
+  }),
+});
+
+// The composition pattern: a feed-only row delivers comments to the item already holding that key, and drops
+// the delivery when there is none.
+new Trigger(factory, "triage-comments", {
+  on: { connection: jira, events: [JiraEvents.CommentCreated] },
+  target: Targets.pipeline(triage, { binding: JiraBindings.Issue, onMissing: "SKIP" }),
+});
+
+// Grant the runtime outbound access to the provider; hosts come from the provider's apiHosts
+// (install-parameterized), the credential is broker-resolved from the connection.
+const env = new Environment(factory, "runtime", { /* … */ egress: EgressPolicy.denyAll().allow(jira) });
+```
+
+**Binding authoring is three all-static layers** — no lambdas, no tagged templates:
+
+| Layer | Example | When |
+|---|---|---|
+| generated canonical | `JiraBindings.Issue` | the provider package's key for a resource family |
+| composition | `scoped(field("issue.key"))`, `key(connection, ":", ref)` | a key the canonical one does not express |
+| raw template | `"{{connection.slug}}:{{event.payload.issue.key}}"` | anything else; always valid |
+
+A generated binding is typed to the events that can render it, so using one across payload shapes that do not
+all carry its field is a **compile error**, not a silent misgroup. The remedy is the composition pattern above:
+split into per-shape triggers sharing one binding constant and one anchor. `{{connection.slug}}` is authorial
+— include it to scope keys per connection (what `scoped(...)` and every generated binding do), omit it
+deliberately to join work across connections.
+
+Verb defaults all materialize into the wire at synth: an agent target's `onMissing: START_NEW`, `onBusy:
+STEER` and `successorContext: NONE`, and a pipeline target's `onMissing: START_NEW`, `onOpen: DELIVER`,
+`onClosed: SKIP` and `onBusy: STEER`.
+
+**The authorize handoff.** An `Auth.oauth()` connection is created `NEEDS_ATTENTION` — the factory holds no
+provider credential, and the consent dance is a human's browser session, not something apply can perform. So
+apply reconciles the full dependent graph first and then, for every managed or imported OAuth connection still awaiting
+authorization, prints one non-fatal line:
+
+```
+  connection 'workspace-slack' needs attention — authorize at: https://…/connections/conn_…?organizationId=org_…
+```
+
+That printed line **is** the human step: open it, complete consent, and re-run `apply`. Apply itself always
+exits successfully — an unauthorized connection is a pending handoff, not a failure — and re-running is a
+no-op for everything already reconciled.
+
+**App-established connections (`Auth.githubApp()`, `Auth.forgeApp()`).** Two modes are **mode-only**: they
+take no options and carry no credential of yours, because the identity is the platform's own GitHub App or
+Atlassian Forge app, whose credential is minted server-side per request. What replaces the consent dance is a
+**provider-side installation ceremony** — so a from-zero `Auth.githubApp()` connection cannot simply be
+created (its installation id does not exist yet). Apply mints an **install link** instead, prints it, and
+waits at that connection's own step, because everything downstream resolves the connection's id:
+
+```
+connection 'github': needs a provider-side installation before it can be created.
+  1. Open this link and complete the installation:
+       https://<platform>/integrations/install/…
+     This link is shown ONCE and cannot be reprinted. It stays usable until
+     2026-08-25 09:30 UTC, so you can hand it to whoever administers the provider account.
+  2. Leave this apply running — it waits up to 10m and then continues.
+```
+
+The link is long-lived (days, not minutes) precisely because the person who runs `apply` is usually not the
+person who administers the GitHub account: send it on, and it still works next week.
+
+**Re-running is reuse-first.** A later `apply` that finds a link still pending for the same connection
+**reports it instead of minting another one**, because minting revokes the pending one — which would break
+the URL a delegated administrator is still holding:
+
+```
+connection 'github': an install link for this connection is already pending and is valid until
+2026-08-25 09:30 UTC — whoever you sent it to can still use it, so this apply did not mint a new one.
+  1. Ask the provider's administrator to open the link they were sent and complete the installation.
+     The link's URL is shown only when it is minted and is never recoverable, so it cannot be
+     reprinted here. If it was lost, re-run `orchestra fdk apply --remint-install-links`: that revokes this
+     link and prints a fresh one.
+  2. Leave this apply running — it waits up to 10m and then continues.
+```
+
+Pass **`--remint-install-links`** when the link was lost, leaked, or sent to the wrong person: it mints a
+fresh link (revoking the pending one) for every App-established connection that apply reconciles.
+
+The wait ends after 10 minutes or at the link's own expiry, whichever comes first, and checks every 5
+seconds. **`--install-timeout <seconds>`** changes the bound (`0` checks once, then stops with the resume
+message), and **`--install-poll-interval <seconds>`** changes how often it checks.
+
+Finish the installation and the same apply adopts the connection at its declared slug and carries on. On a
+timeout nothing downstream was applied, and the message says to re-run `apply` after installing — the re-run
+adopts the connection and applies the rest. Authorable install fields ride `install` as usual
+(`install: { permissions: ["issues:write"] }`); declaring a real `installationId` opts back into the ordinary
+direct create, for an App you have already installed. A connection that installs your organization's **own**
+registered App (`Connector`, below) mints its link against that registration, not the platform's.
+
+### Bring your own OAuth app (`Connector`)
+
+By default a `Connection` installs through the **platform's** registered provider app. A `Connector` declares
+your organization's **own** app registration instead — one registered app that many connections ride, with a
+single place to rotate its material. Every secret-classed field takes an org `Secret` **reference**; no
+credential material ever enters a declaration or `plan.json`:
+
+```ts
+import { Auth, Connection, Connector, Providers, Secret, SecretValue } from "@orchestraworks/cli";
+
+const ourSlackApp = new Connector(factory, "our-slack-app", {
+  provider: Providers.Slack,
+  clientId: "1234.5678",
+  appId: "A0ACME",
+  clientSecret: new Secret(factory, "slack-client-secret", { value: SecretValue.fromEnv("SFDK_SLACK_CLIENT_SECRET") }),
+  signingSecret: new Secret(factory, "slack-signing-secret", { value: SecretValue.fromEnv("SFDK_SLACK_SIGNING_SECRET") }),
+});
+
+const workspace = new Connection(factory, "workspace", {
+  provider: Providers.Slack,
+  auth: Auth.oauth({ connector: ourSlackApp }), // omit `connector` to use the platform app
+  install: {},
+});
+```
+
+Which fields a provider requires is catalog knowledge the **platform** owns: apply rejects a field the target
+provider does not declare, and rejects a declared field left unsupplied. Import a pre-existing registration
+(including the platform's own) with `Connector.fromSlug` / `Connector.fromId`.
+
+Three rules the CLI surfaces for you:
+
+- **Registering a custom app needs the `flags.customConnectorApps` entitlement.** Synth cannot check it (the
+  plan names no organization), so declaring a `Connector` emits a warning and `apply` is the authoritative
+  gate — a `403` plan-feature denial when the target org lacks it.
+- **A registration's identity is create-only, but its configuration is not.** Which is which comes from the
+  provider catalog, per field. An *identity* field — `clientId`, `appId`, `botAppId`, `botId`, or the
+  `provider` itself — IS the app registration, so changing one (or switching a connection between the
+  platform app and your own) is delete-and-recreate and `apply` says so instead of silently dropping the
+  change. A *configuration* field — GitHub's `appSlug`, or `scope`/`redirectUri` — is freely re-configurable
+  and rides an ordinary PATCH, as does rotating a secret reference. GitHub's App page slug is the motivating
+  case: GitHub re-derives it when you rename the App, without issuing a new `appId`.
+- **Removing an optional configuration value is not appliable.** The platform's connector update is
+  *set-only*: an omitted field means "leave unchanged", and there is no way to clear a stored one. So deleting
+  the prop from your declaration neither clears it nor is silently ignored — `apply` prints a `note:` naming
+  the field and leaves the live value alone. Declare the intended value to change it, or delete and re-declare
+  the registration to drop it.
+
+### Per-user OAuth grants (`orchestra user-grants grant`)
+
+Some providers can act **as the individual user** rather than as the org install. That credential is the
+user's own, proved by a browser consent dance, so it is never a declared resource — but the dance is
+API-first, so you can drive one for testing:
+
+```bash
+orchestra user-grants grant --connection workspace-slack --open
+```
+
+The command mints the grant intent under **your** token, prints (and with `--open` launches) the consent URL,
+and polls until the grant activates — you finish it in your own signed-in browser session, which is exactly
+what the platform's authenticated callback requires. `--timeout 0` mints and prints without waiting. Grants
+carry lifecycle metadata only; no surface ever reads the credential back.
+
+### Chat presence (Slack and Microsoft Teams)
+
+There is **no chat construct** — the `Channel` construct was removed, because the orchestra convention is
+construct ⇄ resource and no chat resource exists any more. A chat presence is exactly the connection triad above —
+**Connection**, **Inbound**, **Outbound** — with **approval delivery** (`approvalPolicy` on the `Workflow`)
+as the one extra owner. Nothing is bundled; there is no remainder.
+
+#### 1. Connection — the installation's identity and voice
+
+`autoRespond` is the ack reaction / typing status / failure notice the provider speaks per delivery. It lives
+on the connection because that hook fires once per delivery while several triggers can match one: the bot
+presence acks once, per its installation's config. Its type is generated from the provider's own catalog
+declaration, so `ack` does not typecheck on a Teams connection (Bot Framework gives a bot no reaction to add):
+
+```ts
+import { Auth, Connection, Providers, Targets, Trigger } from "@orchestraworks/cli";
+
+const slack = new Connection(factory, "slack", {
+  provider: Providers.Slack,
+  auth: Auth.oauth(), // created NEEDS_ATTENTION; apply prints the authorize handoff line
+  autoRespond: { ack: { reaction: "eyes" }, typing: true, failureNotice: true },
+});
+```
+
+#### 2. Inbound — what the agent hears
+
+Each posture the retired `respondTo` flags bundled is now one trigger. The
+`Providers.<P>.conversation` helpers are generated from the same catalog block, so hand-authored wire and
+orchestra read one source: event handles
+(Slack `.mention`/`.dm`/`.groupChat`/`.threadReply`; Teams one `.message` wire split by `.inChannel()` /
+`.inDirectMessage()` / `.inGroupChat()`), the binding templates that set session granularity
+(`.sessionPerThread()` / `.sessionPerConversation()`) and `.rooms([...])`. There is no echo exclusion: the
+bot's own messages reach the agent, which ignores them. `{{ event | xmlify }}` places the encoded `Event` in the prompt — the whole
+layout is yours, and the platform parses and reproduces nothing of the message itself:
+
+```ts
+const conversation = Providers.Slack.conversation;
+const PROMPT = `A Slack message arrived. Help the user and reply with the Slack CLI.\n\n{{ event | xmlify }}`;
+
+new Trigger(factory, "slack-mentions", {
+  on: { connection: slack, events: [conversation.mention] },
+  target: Targets.agent(responder, {
+    binding: conversation.sessionPerThread(),
+    prompt: PROMPT,
+    attributeConnection: true, // the reply path's egress resolves against this installation
+  }),
+});
+
+new Trigger(factory, "slack-thread-replies", {
+  on: { connection: slack, events: [conversation.threadReply] },
+  target: Targets.agent(responder, {
+    binding: conversation.sessionPerThread(),
+    prompt: PROMPT,
+    attributeConnection: true,
+    requireEverParticipated: true, // the old ThreadReplies.Participating: only threads already joined
+  }),
+});
+```
+
+#### 3. Outbound — what the agent may say
+
+The reply is an ordinary outbound request from the machine, so it needs an egress grant like any other. One
+line on the **receiving agent's environment** synthesizes the provider's `apiHosts` rule plus the
+`Authorization` binding the broker hydrates from that installation:
+
+```ts
+const responderEnv = new Environment(factory, "responder-env", {
+  /* … */
+  egress: EgressPolicy.denyAll().allow("anthropic", { hosts: ["api.anthropic.com"], /* … */ }).allow(slack),
+});
+```
+
+Forget it and nothing looks wrong: synth, apply and routing all succeed, the agent runs — and then its reply
+CLI gets a 403 from the egress fence inside its own machine, where nothing surfaces it but decision logs. So
+synth notices that exact shape (a connection wired inbound to an agent whose environment has no rule bound to
+it) and prints:
+
+```
+warning: connection 'slack' is wired inbound to agent 'codex-agent' but its environment 'codex-env' has no outbound rule for it — add .allow(slack) to its egress, or ignore this if that is deliberate (listener-only, or the hosts are covered by a hand-written rule).
+```
+
+It never blocks, and **the deliberate listener simply ignores it**: an agent that only reads a provider's
+events and answers somewhere else (or not at all) needs no outbound grant, and so does an agent whose access
+you authored as a hand-written named rule with its own credential — detection is by connection-bound rule
+only, and that false positive is accepted rather than papered over with host matching (a covering rule with
+the wrong credential still 403s). Anything synth cannot prove stays silent instead: an imported agent or
+environment is not in the plan, and a `Connection.fromEnv`/`fromId` binding resolves only at apply.
+
+#### Asking a person to approve
+
+An approval is a check a person sets on the work item, and a stage's `requires` can wait on it. A rule posts
+the request to a chat channel through the connection, which apply resolves to its id and checks is usable:
+
+```ts
+new Workflow(factory, "release-flow", {
+  pipeline: releases,
+  rules: [
+    rule({
+      name: "Ask the release channel to sign off",
+      when: entered("sign-off"),
+      then: [message(toChannel(slack, "C0RELEASES"), "{{workItem.title}} is ready to ship. Approve it on the board.")],
+    }),
+    rule({ name: "Ship a release once a person approves it", when: check("approval").is("PASS"), then: [move("shipped")] }),
+  ],
+});
+```
+
+The agent replies through its provider CLI (egress injects the Connection credential and fences the target
+conversation); the Session transcript never carries provider credentials or Teams transport addresses.
+The three statements above are the whole lane for either provider — Teams differs only in which
+`conversation` handles typecheck (no reaction to add, one `.message` wire split by scope).
+
+## 8. Running several instances
+
+Parameterize the factory name to get a fresh slug namespace per deployment instance (the pattern the
+support-bugfix example uses):
+
+```ts
+const instance = process.env.ORCHESTRA_FDK_INSTANCE?.trim();
+const factoryName = instance ? `acme-support-${instance}` : "acme-support";
+const factory = new Factory({ name: factoryName });
+```
+
+Each distinct factory name globally reserves its slug namespace on first apply. Watch the **slug budget**:
+every derived slug (factory name + construct path) must stay ≤ 60 chars, so keep `ORCHESTRA_FDK_INSTANCE` short
+(≤ 16 chars is safe); synth enforces the bound.
+
+## 9. Troubleshooting
+
+| Symptom | Cause & fix |
+| --- | --- |
+| **409 on create** | The globally-unique slug is claimed. Three indistinguishable causes: (a) a concurrent apply already created it — re-run apply; (b) another org owns the slug — pick a new explicit slug or rename the factory; (c) a soft-deleted same-org tombstone still holds it (no slug reclaim) — restore out-of-band or accept a new slug. |
+| **401 / 403** | The token lacks access to the resolved org, or it expired and could not be renewed. A profile from a browser `login` renews itself silently, so a 401 that survives that means the renewal credential is gone too — re-run `orchestra auth login`. A pasted or exported token has no renewal path at all: replace it, or fix `ORCHESTRA_ORGANIZATION_ID`. |
+| **"the platform rejected the stored refresh credential… Run `orchestra auth login` to sign in again."** | The stored renewal credential was refused (revoked, expired, or a sibling process already rotated past it). Nothing on disk is changed by that failure, so re-running `orchestra auth login` is the whole remedy. A *retryable* failure — the platform unreachable, timing out, or answering `temporarily_unavailable` — reports itself as such and never tells you to log in again; run the command again. |
+| **`ERR_PACKAGE_PATH_NOT_EXPORTED` at first import** | The factory program's own `package.json` is missing `"type": "module"` (a fresh `npm init -y` defaults to CommonJS). orchestra is ESM-only — its `exports` map defines only an `import` condition — so add `"type": "module"` to the factory `package.json` (see §4). |
+| **Import 404** | The referenced slug/id isn't visible in the resolved org. Check the org and the reference. |
+| **"refusing to send secrets over plain HTTP to non-loopback host …"** | A secret write needs TLS. Use an `https://` base URL; only loopback (`127.0.0.1`/`localhost`/`::1`) dev stacks may use `http://`. |
+| **`tsc` error on `target: Targets.…({ binding })`** | The binding is scoped to events the trigger does not fully select (its field is absent from one payload shape). Split into per-shape triggers sharing one binding constant and one anchor (the composition pattern), or author a binding valid for the whole selection. |
+| **Synth note: "the selected events share no canonical binding"** | The target declared no `binding` and the selection's events carry different (or no) canonical keys, so the target is keyless — one-shot sessions, or one work item per event. Declare a binding explicitly if a keyed holder was intended. |
+| **Synth warning: "connection '…' is wired inbound to agent '…' but its environment '…' has no outbound rule for it"** | The connection triad is missing its third statement: add `.allow(connection)` to that environment's egress. Ignorable when deliberate — a listener-only agent, or hosts already covered by a hand-written named rule. |
+| **Synth error: "selects on a connection import that carries no slug"** | `on.connection` rides the wire as the connection SLUG, which the platform matches verbatim. `Connection.fromId`/`fromEnv` resolve an id, so pass a managed `Connection`, `Connection.fromSlug(...)`, or the slug string. |
+| **Synth error: "connection '…' selects '…' in its install '…', which provider '…' does not admit"** | A per-connection event selection (an install field whose values are the provider's own event tokens, e.g. Azure DevOps' `events`) names a token outside the provider's admitted vocabulary — usually a typo. The message lists the admitted set; fix the value, or omit the field entirely (an absent or empty selection means all admitted types). The platform's install write seam rejects the same value at apply, so synth just says it sooner. |
+| **Synth warning: "trigger '…' selects event '…' on connection '…', whose install '…' selection excludes it"** | That trigger can never fire: the connection's selection narrows what the provider is subscribed to, and this wire type is not in it. Add the named token to the connection's selection, or ignore it — narrowing now and widening later is legitimate authoring order, and a trigger staged ahead of its selection is a normal intermediate state. |
+| **Synth error: "egress rule '…': this policy already declares a rule with that name"** | Every rule on one `EgressPolicy` needs its own name (§4). Usual causes: a rule you hand-authored collides with a preset row (`software-development-npm`), the same bundle is applied twice, or a connection's bundle is applied beside `allow(connection)` — which it supersedes. Rename your rule, or drop the duplicate call; the message names both the rule and the knob to turn. |
+| **`allow(connection)`: missing install param** | A provider `apiHost` carries a `{param}` (e.g. `{subdomain}.zendesk.com`) with no matching `install` value on the connection. Add the install field the error names. |
+| **Apply error naming a secret and an env var that "is not set"** | `SecretValue.fromEnv` is strict (§6): unset, empty and whitespace-only are all failures, on a terminal and in CI alike. Export the variable, or change the declaration to `SecretValue.fromCommandLine()` if a human is meant to type the value. There is no interactive fallback — older orchestra versions had one, and it is gone. |
+| **Apply error: the resource "declares an interactive credential"** | A `SecretValue.fromCommandLine` credential reached an apply with no terminal to type into (CI, a piped run, a cron job). Either run it interactively, or switch that declaration to `SecretValue.fromEnv("NAME")` and supply the value through the environment. |
+
+## 10. Learn more
+
+Everything orchestra knows ships inside the installed package — this guide is the reference, and:
+
+- [`skills/orchestra/SKILL.md`](../skills/orchestra/SKILL.md) — the reference skill: the platform's ideas,
+  how the CLI works, what the platform cannot do yet, and where an agent's knowledge belongs.
+- [`skills/orchestra-fdk/SKILL.md`](../skills/orchestra-fdk/SKILL.md) — the setup skill: building and applying
+  a factory for an existing codebase, with environment porting in `references/environment.md` and the
+  authoring reference — the construct model, the two-file factory shape, the synth → diff → apply loop,
+  secrets-as-recipes and the six design principles — in `references/authoring.md`. `orchestra skills install`
+  (§2) links both into your own coding harness, so the agent writing your factory reads them too.
+- `orchestra --help` lists every command, and `orchestra <command> --help` gives its flags — the authoritative
+  list is the CLI you just installed, never a doc that can drift from it.
+
+## 11. License
+
+orchestra is released under the [Apache License 2.0](../LICENSE) — the full text ships in this package.
+
+Copyright 2026 Living Computers