@jterrats/open-orchestra 0.5.7 → 1.0.2

package/docs/benchmark.md

@@ -8,9 +8,10 @@ Open Orchestra measures the effectiveness of AI-assisted development across thre
 |------|-------------|
 | **Solo (no LLM)** | Declared by PM or architect at story start — contrafactual estimate |
 | **AI-unguided** | Declared at story start — how long with a general LLM but no roles, gates, or skills |
+| **AI-guided** | Declared at story start — how long with AI plus Orchestra workflow, roles, gates, memory, and evidence |
 | **AI + Orchestra (actual)** | Measured automatically from `AUTONOMOUS_PHASE_DONE` timestamps in the event log |
 
-The first two are self-reported. Orchestra only measures the third. The comparison is meaningful even with declared baselines because it creates a consistent, auditable record across many stories.
+The first three are self-reported. Orchestra measures the actual governed run. The comparison is meaningful even with declared baselines because it creates a consistent, auditable record across many stories.
 
 ## Usage
 
@@ -24,6 +25,7 @@ orchestra estimate \
   --sizing m \
   --solo-days 5 \
   --ai-unguided-days 3 \
+  --ai-guided-days 2 \
   --confidence high \
   --declared-by pm
 ```
@@ -36,6 +38,7 @@ Options:
 | `--sizing` | Yes | — | `xs`, `s`, `m`, `l`, `xl` |
 | `--solo-days` | Yes | — | Estimated days without any AI |
 | `--ai-unguided-days` | Yes | — | Estimated days with a general LLM, no Orchestra |
+| `--ai-guided-days` | Yes | — | Estimated days with AI guided by Orchestra workflow |
 | `--confidence` | No | `medium` | `low`, `medium`, `high` |
 | `--declared-by` | No | `pm` | Role recording the estimate |
 | `--json` | No | — | Structured output |
@@ -66,9 +69,11 @@ Benchmark: FEAT-001  [complete]
   Sizing:      m
   Solo:        5d  (declared)
   AI-unguided: 3d  (declared)
+  AI-guided:   2d  (declared)
   Actual:      1.4d
   vs Solo:     -72%
-  vs AI:       -53%
+  vs AI-U:     -53%
+  vs AI-G:     -30%
   QA loops:    1
   Reviews:     3 (0 blocking)
   Evidence:    5 artifacts
@@ -81,14 +86,15 @@ Benchmark: FEAT-001  [complete]
 Example summary table:
 
 ```
-Story          Size Solo   AI     Actual   vs Solo  vs AI    QA   Rev  Blk  Ev   Les
-────────────────────────────────────────────────────────────────────────────────────
-TASK-042       m    5d     3d     1.4d     -72%     -53%     1    3    0    5    2
-TASK-089       l    8d     5d     2.1d     -74%     -58%     2    4    1    7    3
-TASK-101       s    2d     1.5d   0.6d     -70%     -60%     0    2    0    3    1
+Story          Size Solo   AI-U   AI-G   Actual   vs Solo  vs AI-U vs AI-G QA   Rev  Blk  Ev   Les
+────────────────────────────────────────────────────────────────────────────────────────────────────
+TASK-042       m    5d     3d     2d     1.4d     -72%     -53%    -30%    1    3    0    5    2
+TASK-089       l    8d     5d     3d     2.1d     -74%     -58%    -30%    2    4    1    7    3
+TASK-101       s    2d     1.5d   1d     0.6d     -70%     -60%    -40%    0    2    0    3    1
 
 Avg savings vs solo:        -72%
 Avg savings vs AI-unguided: -57%
+Avg savings vs AI-guided:   -33%
 Stories with actuals:       3/3
 ```
 
@@ -194,9 +200,11 @@ All benchmark and burndown commands support `--json` for structured output.
   "sizingLabel": "m",
   "soloEstimateDays": 5,
   "aiUnguidedEstimateDays": 3,
+  "aiGuidedEstimateDays": 2,
   "actualDays": 1.4,
   "vsSoloPct": -72,
   "vsAiUnguidedPct": -53,
+  "vsAiGuidedPct": -30,
   "qaIterations": 1,
   "quality": {
     "reviewCount": 3,

package/docs/command-contracts.md

@@ -2,7 +2,8 @@
 
 `orchestra commands manifest --json` is the supported discovery surface for
 automation. Entries include command text, required and optional flags, JSON
-support, compatibility status, and reusable schema/message references.
+support, surface classification, compatibility status, contract version, exit
+codes, error shape, and reusable schema/message references.
 
 ## Compatibility
 
@@ -11,6 +12,22 @@ support, compatibility status, and reusable schema/message references.
 - `experimental`: command is intended for humans or workflow mutation and should
   not be consumed as a stable machine contract unless a future schema is linked.
 
+## Surfaces
+
+- `public`: stable automation contract for project workflows, documentation,
+  bootstrap files, and CI usage.
+- `experimental`: supported CLI behavior, but not a frozen machine contract for
+  `1.0.0`.
+- `internal`: implementation or adapter support surface. It may expose `--json`
+  for local tooling, but it is not part of the public 1.0 automation contract.
+
+Public commands use contract version `1.0`, exit codes `0` and `1`, and the
+generic JSON error contract unless a command-specific schema replaces it.
+
+Config migration is exposed as a public contract through
+`orchestra config migrate --json`. It is dry-run by default and requires
+`--apply` before writing `.agent-workflow/config.json`.
+
 ## Reusable Contracts
 
 - `schemas/commands/generic-json-output.schema.json` defines the baseline JSON

package/docs/core-command-surface.md

@@ -17,16 +17,48 @@ orchestra commands manifest --json
 Core commands are the first screen for a new project or a production delivery
 workflow. They are stable enough to appear in onboarding and public examples.
 
-| Job | Commands |
-| --- | --- |
-| Install and verify | `orchestra version`, `orchestra upgrade --smoke --json` |
-| Initialize workspace | `orchestra init`, `orchestra health --json`, `orchestra status` |
-| Create and inspect work | `orchestra task add`, `orchestra task list`, `orchestra task show` |
-| Run governed delivery | `orchestra workflow run`, `orchestra workflow runs` |
-| Resolve workflow gates | `orchestra decision add`, `orchestra workflow gate-approve` |
-| Record delivery proof | `orchestra evidence add`, `orchestra review` |
-| Sync tracker state | `orchestra github sync --issue <number>` |
-| Check release readiness | `orchestra release check --json`, `orchestra release candidate --dry-run --json` |
+For first visible value, show this compact sequence before introducing every
+artifact type:
+
+```bash
+orchestra init
+orchestra health --json
+orchestra task add --id DEMO-001 --title "Ship a governed README update" --owner developer --paths "README.md"
+orchestra workflow run --task DEMO-001 --gates none
+orchestra status
+orchestra release candidate --dry-run --json
+```
+
+For production delivery, follow with estimates, architecture sizing decisions,
+human gates, evidence, QA reviews, and `orchestra release check --json`.
+
+| Job                                       | Commands                                                                                                                        |
+| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| Install and verify                        | `orchestra version`, `orchestra upgrade --smoke --json`                                                                         |
+| Initialize workspace                      | `orchestra init`, `orchestra health --json`, `orchestra status`                                                                 |
+| Create and inspect work                   | `orchestra task add`, `orchestra task list`, `orchestra task show`                                                              |
+| Run governed delivery                     | `orchestra workflow run`, `orchestra workflow runs`                                                                             |
+| Inspect workflow shape and playbooks      | `orchestra workflow phase-plan --task <id>`, `orchestra workflow render --task <id> --phase <phase>`                            |
+| Resolve workflow gates and clarifications | `orchestra decision add`, `orchestra workflow gate-approve`, `orchestra workflow clarify`, `orchestra workflow clarify-respond` |
+| Record delivery proof                     | `orchestra evidence add`, `orchestra review`                                                                                    |
+| Plan QA automation                        | `orchestra qa coverage --task <id>`, `orchestra playwright plan --task <id>`                                                    |
+| Sync tracker state                        | `orchestra github sync --issue <number>`, `orchestra tracker sync --tracker <provider> --remote <id> --issue-file <file>`       |
+| Check release readiness                   | `orchestra release check --json`, `orchestra release candidate --dry-run --json`                                                |
+
+## Run Command Guidance
+
+`orchestra workflow run` is the governed delivery lifecycle. It creates phase
+sub-tasks, handoffs, run state, and gates across PM, PO, Architect, Developer,
+QA, and Release. Use it for product work, issue delivery, QA handoff, release
+readiness, and dogfooding the end-to-end process.
+
+`orchestra run` executes the task's local execution plan. It is useful for
+lower-level plan execution and budget/fallback validation, but it does not
+replace the autonomous lifecycle or its phase gates.
+
+For the full workflow narrative, phase matrix, gate-versus-clarify decision
+table, and playbook authoring guidance, see
+[autonomous-workflow.md](autonomous-workflow.md).
 
 ## Advanced Commands
 
@@ -39,8 +71,20 @@ should be linked from onboarding, not mixed into first-run copy.
 - Runtime and skills: `orchestra runtime brief`,
   `orchestra runtime delegate-plan`, `orchestra skills plan`,
   `orchestra skills render`, `orchestra protocol render`.
+- Extensions: `orchestra extensions list --json`,
+  `orchestra extensions validate --json`.
+- Provider profiles: `orchestra model profile set`,
+  `orchestra model profile apply`, `orchestra model profile smoke`,
+  `orchestra model providers`.
+- Generated-file operations: `orchestra refresh --check --json`,
+  `orchestra refresh --dry-run`, `orchestra refresh --force`,
+  `orchestra cursor canvas status --json`,
+  `orchestra cursor canvas sync --dry-run --json`.
 - Memory and source selection: `orchestra memory query`,
-  `orchestra memory hook`, `orchestra sources list`, `orchestra lessons list`.
+  `orchestra memory hook`, `orchestra memory governance`,
+  `orchestra sources list`, `orchestra lessons list`,
+  `orchestra lessons archive`, `orchestra lessons redact`,
+  `orchestra lessons prune`.
 - Metrics and cost: `orchestra estimate`, `orchestra benchmark`,
   `orchestra burndown`, `orchestra usage`, `orchestra budget check`.
 - Governance policy: `orchestra policy evaluate` checks routine, elevated,
@@ -70,5 +114,7 @@ unless a specific workflow needs them.
 ## Documentation Rule
 
 Do not duplicate the full command manifest in README or the site. Show the core
-path, then link to `orchestra commands manifest --json` and
-[command-contracts.md](command-contracts.md) for automation consumers.
+path, then link to `orchestra -h` for human onboarding,
+`orchestra help commands` for the full CLI catalog, and
+`orchestra commands manifest --json` plus [command-contracts.md](command-contracts.md)
+for automation consumers.

package/docs/end-to-end-demo.md

@@ -31,6 +31,7 @@ orchestra estimate \
   --sizing s \
   --solo-days 1 \
   --ai-unguided-days 0.5 \
+  --ai-guided-days 0.25 \
   --confidence medium
 ```
 

package/docs/extension-contracts.md

@@ -0,0 +1,83 @@
+# Extension Contracts
+
+Open Orchestra discovers local extensions from:
+
+```text
+.agent-workflow/extensions/<extension-id>/manifest.json
+```
+
+The manifest is metadata only. Discovery and validation do not import or execute
+extension code.
+
+## Manifest
+
+```json
+{
+  "id": "acme-tracker",
+  "name": "Acme Tracker Adapter",
+  "version": "1.0.0",
+  "compatibility": { "orchestra": "^1.0.0" },
+  "extensionPoints": ["tracker-adapter"],
+  "entry": "adapter.js",
+  "capabilities": ["normalized-issue-sync"],
+  "riskAreas": ["network", "tracker-state"]
+}
+```
+
+Supported extension points for the 1.0 contract are:
+
+- `skill`
+- `tracker-adapter`
+- `provider-adapter`
+- `phase-playbook`
+- `refresh-target`
+
+`entry` must be a relative path inside the extension directory. Absolute paths
+and traversal are rejected. Provider adapter extensions are currently
+metadata-only until runtime provider loading is stabilized.
+
+## Commands
+
+```bash
+orchestra extensions list --json
+orchestra extensions validate --json
+```
+
+## Provider-Like Example
+
+```json
+{
+  "id": "acme-models",
+  "name": "Acme Models Provider",
+  "version": "1.0.0",
+  "compatibility": { "orchestra": "^1.0.0" },
+  "extensionPoints": ["provider-adapter"],
+  "entry": "provider.js",
+  "capabilities": ["chat-completions", "json-mode"],
+  "riskAreas": ["secrets", "network"]
+}
+```
+
+## Tracker-Like Example
+
+```json
+{
+  "id": "acme-tracker",
+  "name": "Acme Tracker Adapter",
+  "version": "1.0.0",
+  "compatibility": { "orchestra": "^1.0.0" },
+  "extensionPoints": ["tracker-adapter"],
+  "entry": "tracker.js",
+  "capabilities": ["normalized-issue-sync"],
+  "riskAreas": ["network", "tracker-state"]
+}
+```
+
+## Stability
+
+Stable for 1.0.0: manifest shape, discovery path, extension point names, local
+path safety validation, and JSON output from `extensions list` and
+`extensions validate`.
+
+Experimental: dynamic code loading, provider runtime registration, tracker live
+transport execution, and generated-file refresh target execution.

package/docs/orchestra-mvp.md

@@ -145,6 +145,9 @@ orchestra skills render --target codex --task TASK-1
 orchestra protocol render --target codex --task TASK-1
 orchestra workflow render --target codex --task TASK-1
 orchestra runtime brief --task TASK-1 --runtime codex-cli --json
+orchestra runtime delegate-plan --task TASK-1 --runtime claude-cli --roles developer,qa --json
+orchestra runtime sessions --task TASK-1 --json
+orchestra runtime session --session TASK-1:claude-cli --action suspend --json
 ```
 
 Memory hooks are explicit retrieval points for lessons learned and prompt
@@ -153,6 +156,11 @@ registry entries. Bundles are scoped by role (`product_owner`, `architect`,
 tokens, kept and omitted sections, and trimming rationale in both JSON and human
 output.
 
+Runtime delegation sessions are derived from append-only events. Session
+operations record suspend, resume, cancel, or close events for the parent
+runtime and web console to reconcile active work, stale sessions, and handoff
+state without creating a second session store.
+
 Delivery evidence, handoff, and gates:
 
 ```bash
@@ -173,6 +181,42 @@ locks, and missing smoke or rollback evidence. Browser/UI criteria require
 Playwright-style screenshot, trace, or video evidence unless the task has an
 accepted risk.
 
+For `1.0.0` release candidates, the same report includes `gaReadiness`. This is
+the repeatable go/no-go layer for production promotion. A GA-ready workspace
+must have no uncovered acceptance criteria, no blocking reviews, no active
+locks, smoke and rollback evidence, documentation or release notes evidence,
+observability evidence, security and permissions review evidence, package
+provenance evidence, public CLI contract evidence, migration or upgrade
+readiness evidence, and release test matrix evidence. Accepted risks must include
+an owner, a rationale, and a follow-up or expiry signal in the rationale.
+
+The human release check summary reports both the legacy release readiness gaps
+and the number of GA blockers. Use JSON output for the full criterion list:
+
+```bash
+orchestra release check --json
+```
+
+## Config Schema Migrations
+
+Open Orchestra workspace config is versioned through
+`.agent-workflow/config.json`. For pre-1.0 workspaces, inspect migrations before
+writing anything:
+
+```bash
+orchestra config migrate --json
+```
+
+Apply a supported migration only after reviewing the plan:
+
+```bash
+orchestra config migrate --apply --json
+```
+
+Migration apply writes a backup under `.agent-workflow/backups/` before updating
+`config.json`. Newer unsupported schema versions are reported as errors and are
+not modified.
+
 Upgrade dogfooding:
 
 ```bash
@@ -184,7 +228,10 @@ orchestra upgrade --smoke --json
 Stable installs use `npm install -g @jterrats/open-orchestra@latest`; beta
 dogfooding uses `npm install -g @jterrats/open-orchestra@beta` or the exact
 version reported by `orchestra upgrade --beta`. After upgrading, run the smoke
-command shown by the CLI to verify the installed binary and health report.
+command shown by the CLI to verify the installed binary and health report. The
+upgrade output also includes the exact rollback install command for the
+previous version plus `orchestra config migrate --json` as the migration
+compatibility check before accepting the new package.
 Set `SKIP_NETWORK_TESTS=1` in CI jobs that must avoid external network calls;
 package update checks and provider smoke tests honor it, while localhost E2E
 coverage remains available.
@@ -192,12 +239,41 @@ coverage remains available.
 Release go/no-go:
 
 - Run `npm run precommit` locally before pushing release changes.
+- Confirm `npm run security:audit` passes or attach an accepted security risk.
+- Confirm `orchestra release check --json` passes the package provenance gate,
+  which runs `npm pack --dry-run --json` and rejects private workflow state,
+  generated prompts, env files, and missing public package entry points.
 - Confirm GitHub Actions CI is green for the latest pushed HEAD.
 - Confirm installed-package dogfooding passes on `ubuntu-latest`,
   `macos-latest`, and `windows-latest`.
 - Confirm `Create release tag`, site publish, and npm publish workflows are
   successful for the intended release commit.
 
+Support diagnostics:
+
+```bash
+orchestra diagnostics bundle --json
+orchestra diagnostics bundle --output support/diagnostics.json --json
+```
+
+The diagnostics bundle is written inside the workspace and includes local
+health, workflow validation, task and lock counts, run failure summaries, and a
+sanitized config summary. It redacts token-like values, email addresses, user
+home paths, and credential fields before writing the JSON artifact so it can be
+attached to an issue or support handoff.
+
+Performance budgets:
+
+```bash
+npm run performance:bench -- --json
+npm run performance:bench -- --tasks 500 --json
+```
+
+The benchmark seeds a synthetic workspace and measures core CLI commands plus
+read-only web API routes against documented millisecond budgets. Use the JSON
+result as release evidence for large-workspace readiness and investigate any
+failed budget before promoting a production release.
+
 Model routing, budget, telemetry, and release:
 
 ```bash
@@ -362,7 +438,11 @@ The VS Code Control Center scaffold is under `extensions/vscode-open-orchestra`.
 - `orchestra model set-role` configures provider/model routing per role without invoking real model APIs.
 - `orchestra model complete-fake` simulates provider fallback behavior without invoking real model APIs.
 - `orchestra model provenance` records model usage metadata in the append-only event log without storing raw prompts, raw responses, or secrets.
-- `orchestra release check`, `release candidate`, `release tag`, and `release evidence` provide a local release-readiness flow for stable, beta, and other prerelease tags.
+- `orchestra release check`, `release candidate`, `release tag`, and
+  `release evidence` provide a local release-readiness flow for stable, beta,
+  and other prerelease tags. Candidate plans include rollout, rollback,
+  post-release, changelog, and semver-impact sections; release evidence accepts
+  `smoke`, `rollback`, `post-release`, and `release-notes` kinds.
 - `orchestra health --network` can check for a newer published package version and print the exact `npm install -g @jterrats/open-orchestra@<version>` update command when one is available.
 - Package identity is intentionally split: `@jterrats/open-orchestra` is the
   canonical npm package and `orchestra` is the installed CLI binary. Do not use
@@ -384,7 +464,7 @@ Quality signals collected automatically:
 
 ```bash
 # Declare baseline at story start (once per story)
-orchestra estimate --task TASK-1 --sizing m --solo-days 5 --ai-unguided-days 3
+orchestra estimate --task TASK-1 --sizing m --solo-days 5 --ai-unguided-days 3 --ai-guided-days 2
 
 # Per-story benchmark after run completes
 orchestra benchmark --task TASK-1

package/docs/persona-workflows.md

@@ -4,6 +4,36 @@ Use these paths when you want to operate Open Orchestra by role instead of
 learning the full command catalog first. Commands assume the installed CLI form:
 `orchestra`.
 
+## First Visible Value
+
+Goal: complete one local workflow run and preview release readiness before
+learning every role-specific artifact.
+
+Commands:
+
+```bash
+orchestra init
+orchestra health --json
+orchestra task add --id DEMO-001 --title "Ship a governed README update" --owner developer --paths "README.md"
+orchestra workflow run --task DEMO-001 --gates none
+orchestra status
+orchestra release candidate --dry-run --json
+```
+
+Expected artifacts:
+
+- `.agent-workflow/tasks.json` contains `DEMO-001`.
+- `.agent-workflow/workflow-runs.jsonl` contains the completed lifecycle.
+- Release candidate dry-run output shows what is ready and what evidence is
+  still missing.
+
+Recovery:
+
+- Run `orchestra health --json` if local tools are missing.
+- Use `orchestra workflow runs` to find a paused or failed run.
+- Move to the production paths below when the story needs human gates,
+  explicit sizing, command evidence, QA review, and release readiness approval.
+
 ## Product Owner Refinement
 
 Goal: turn a backlog item into a task that is ready for architecture and
@@ -169,6 +199,8 @@ Commands:
 orchestra release check --json
 orchestra release evidence --kind smoke --summary "smoke passed"
 orchestra release evidence --kind rollback --summary "rollback verified"
+orchestra release evidence --kind post-release --summary "post-release smoke passed"
+orchestra release evidence --kind release-notes --summary "release notes published"
 orchestra gate --gate release-readiness --task STORY-001
 orchestra release candidate --version 0.5.0-beta.0 --json
 ```

package/docs/release-test-matrix.md

@@ -0,0 +1,42 @@
+# 1.0.0 Release Test Matrix
+
+The release test matrix is the minimum validation surface for a production
+`1.0.0` candidate. It is intentionally explicit so release readiness can attach
+reviewable evidence instead of relying on conversational sign-off.
+
+## Command
+
+```bash
+npm run release:matrix -- --json
+```
+
+Use the JSON output as the release-manager checklist and attach the final
+execution summary as release test matrix evidence before running:
+
+```bash
+orchestra release check --json
+```
+
+## Required Environments
+
+- `ubuntu-latest` with Node `>=22` and npm.
+- `macos-latest` with Node `>=22` and npm.
+- `windows-latest` with Node `>=22` and npm.
+
+## Required Flows
+
+| Flow | Command | Evidence |
+| --- | --- | --- |
+| Source quality gate | `npm run precommit` | lint, typecheck, secret scan, security audit, build, unit tests, workflow validation |
+| Browser E2E | `npm run test:e2e` | Playwright regression coverage for browser workflows |
+| Installed package init | `npm run test:e2e:init` | npm package init, health, task, workflow, evidence, readiness smoke |
+| Public site build | `npm run site:build` | production site build |
+| Release readiness | `orchestra release check --json` | `releaseReadiness` and `gaReadiness` report |
+| Package contents | `npm pack --dry-run --json` | package file list and provenance check |
+| Performance budgets | `npm run performance:bench -- --json` | CLI and web API timings on a synthetic large workspace |
+
+## Network Policy
+
+The default release matrix is offline-friendly. Provider and tracker tests that
+need network access must honor `SKIP_NETWORK_TESTS` and report skipped status
+instead of failing offline CI.

package/docs/runtime-adapters.md

@@ -20,6 +20,35 @@ Current targets:
   and `.vscode/open-orchestra.md`.
 - `windsurf`: Windsurf rules in `.windsurf/rules/open-orchestra.md`.
 
+Execution adapters are separate from instruction-file targets. They describe
+how an already-authenticated runtime should receive a brief or delegation
+packet:
+
+- `codex-cli`: use the current Codex CLI/session. Tool permissions and shell
+  approvals stay inside Codex; Orchestra renders briefs and packets only.
+- `opencode-cli`: use an authenticated OpenCode CLI with its own provider
+  config. Orchestra uses the generic instruction target and never copies
+  provider keys into workflow artifacts.
+- `generic-runtime`: produce portable briefs when the executor has no known
+  invocation or permission model.
+
+Provider-backed model adapters are configured separately from execution
+adapters. `gemini` and `ollama` can be used for workflow phases without making
+them child process runtimes:
+
+```bash
+orchestra model connect --provider gemini --model gemini-2.5-pro \
+  --roles architect,developer --api-key-file ~/.env_jt/gemini
+
+orchestra model connect --provider ollama --model llama3.1 \
+  --roles qa --base-url http://127.0.0.1:11434
+```
+
+Secrets stay in environment variables or local secret files referenced from
+config. Runtime packets keep `directProviderApiAllowed: false`; provider API
+execution only happens in the workflow phase provider layer when policy allows
+it.
+
 ## Init Modes
 
 Default project init keeps the current compact bootstrap behavior:
@@ -34,6 +63,18 @@ Generate only selected runtime files:
 orchestra init --target claude,cursor,windsurf
 ```
 
+Refresh managed runtime blocks and generated instruction files:
+
+```bash
+orchestra refresh --check --json
+orchestra refresh --dry-run
+orchestra refresh --force --target codex
+```
+
+`refresh --check` reports drift without writing. `refresh --dry-run` shows the
+planned changes. `refresh --force` rewrites managed blocks only; user-authored
+content outside generated blocks is preserved.
+
 Advisory mode creates workflow state without root instruction files unless a
 target is explicit:
 
@@ -85,6 +126,7 @@ The API contracts are:
 ```bash
 curl -s http://127.0.0.1:3717/api/workspace/classification
 curl -s http://127.0.0.1:3717/api/runtime/adapters
+curl -s http://127.0.0.1:3717/api/workflow/progress
 ```
 
 These endpoints are intended for VS Code, Cursor-like extensions, and other
@@ -94,6 +136,33 @@ instruction-file targets and nested execution adapters. Execution adapters
 include tool permission policy metadata so clients can distinguish
 runtime-managed, brief-only, read-only, and opt-in autonomous execution models.
 
+Runtime delegation operations are event-derived:
+
+```bash
+orchestra runtime sessions --json
+orchestra runtime sessions --task STORY-001 --json
+orchestra runtime session --session STORY-001:claude-cli --action suspend --json
+orchestra runtime session --session STORY-001:claude-cli --action resume --json
+orchestra runtime session --session STORY-001:claude-cli --action cancel --json
+```
+
+The matching read API is `/api/runtime/sessions`. Session operations do not kill
+external provider processes directly; they record auditable suspend, resume,
+cancel, or close events so the parent runtime can reconcile claimed work,
+stale sessions, and handoff state without inventing a second source of truth.
+
+Cursor canvas sync is intentionally runtime-specific:
+
+```bash
+orchestra cursor canvas status --json
+orchestra cursor canvas sync --dry-run --json
+orchestra cursor canvas clean --json
+```
+
+Use it only when Cursor canvas artifacts should be copied into the workspace for
+review. Other runtimes should use `runtime brief`, `runtime delegate-plan`, and
+managed bootstrap files instead.
+
 ## Invocation Planning
 
 Direct CLI execution is intentionally disabled. Orchestra can render a typed
@@ -110,3 +179,26 @@ executor is enabled:
 Every invocation plan reports `directExecutionEnabled: false` and
 `canExecute: false`; the contract is for policy review, UI display, and future
 executor hardening, not for spawning tools today.
+
+## Dependency Remediation
+
+Missing tools should be handled as runtime setup problems, not hidden fallback
+behavior:
+
+- Missing Codex CLI: install or authenticate Codex, then rerender the brief with
+  `orchestra runtime brief --task <id> --runtime codex-cli`.
+- Missing OpenCode CLI: install OpenCode and configure its provider credentials
+  in OpenCode, then use `--runtime opencode-cli`.
+- Missing Gemini credentials: set `GEMINI_API_KEY` or configure
+  `--api-key-file` through `orchestra model connect`.
+- Missing Ollama server: start Ollama locally or set the configured base URL to
+  the reachable OpenAI-compatible endpoint.
+
+The stable inspection commands are:
+
+```bash
+orchestra runtime adapters --json
+orchestra runtime brief --task <id> --runtime codex-cli --json
+orchestra runtime delegate-plan --task <id> --runtime opencode-cli --roles qa --json
+orchestra model providers --json
+```

package/docs/runtime-llm-flow.md

@@ -98,6 +98,10 @@ Anthropic Messages API, `gemini` for the Gemini `generateContent` API, or
 
 ```bash
 orchestra model providers --json
+orchestra model profile set --name local-fast --provider fake --model fake-model --roles developer,qa --activate
+orchestra model profile list --json
+orchestra model profile smoke --name local-fast --json
+orchestra workflow run --task STORY-001 --profile local-fast --gates phase
 orchestra model set-role --role qa --provider fake --model fake-model
 orchestra model connect --provider gemini --model gemini-3-pro-preview --roles qa,reviewer_critic --api-key-file /absolute/path/to/gemini-key --allow-direct-provider-api
 OPENAI_API_KEY=... orchestra model set-role --role architect --provider openai --model gpt-5.2
@@ -116,6 +120,15 @@ in one idempotent config update. This is provider-agnostic: `--provider`,
 routing. Project-specific choices such as "Codex for developer and Gemini for
 QA" belong in the consuming workspace config, not in Open Orchestra defaults.
 
+Use named provider runtime profiles when a workspace needs repeatable routing
+presets such as `local-fast`, `premium-review`, `offline`, or `regulated`.
+`model profile set` stores role routing, fallback chains, and required
+environment variable names without storing secrets. `model profile apply`
+updates active role routing deterministically, and `workflow run --profile`
+applies the profile before execution and records command evidence on the task.
+`model profile smoke` performs local configuration checks and reports missing
+secrets or policy failures with sanitized messages.
+
 The OpenAI adapter reads `OPENAI_API_KEY` from the environment and optionally
 `OPENAI_BASE_URL` for an HTTPS-compatible endpoint. API keys must not be stored
 in workflow config, evidence, docs, or committed files.