orcastrator 0.2.20 → 0.2.24

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bradley Inniss
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -6,7 +6,7 @@
 
 # Orca
 
-Coordinated agent run harness. Breaks down a task into a task graph, then executes it end-to-end via a persistent [Codex](https://github.com/ratley/codex-client) session with full context across tasks.
+Coordinated agent run harness. Breaks a task into a graph, then executes it end-to-end via a persistent [Codex](https://github.com/ratley/codex-client) session.
 
 ## Install
 
@@ -14,465 +14,267 @@ Coordinated agent run harness. Breaks down a task into a task graph, then execut
 npm install -g orcastrator
 ```
 
-## Run A Task
-
-Start with a plain-language task:
+## Quick Start
 
 ```bash
-orca "add auth to the app"
-```
+# 1. Go into a git repo
+cd /path/to/repo
 
-Orca will create a run, plan tasks, run a pre-execution review/improvement pass on the task graph, execute the reviewed graph, and persist run state.
+# 2. Run a task
+orca "add input validation to the signup form in src/auth/signup.ts"
 
-### Pre-execution review-improvement stage
+# 3. Check status
+orca status --last
 
-After planning, Orca runs a structured review pass that can edit the task graph before execution starts. The review output is schema-validated and supports concrete graph operations:
-
-- update task fields (`name`, `description`, `acceptance_criteria`)
-- add/remove task
-- add/remove dependency
+# 4. Once done, open a PR
+orca pr create --last
+```
 
-By default, Orca applies valid review improvements and continues execution. The edited graph is re-validated as a DAG. If the review stage output is invalid, Orca fails with an actionable error (`review.plan.onInvalid: "fail"`). Set `review.plan.onInvalid: "warn_skip"` to log a warning and continue with the original planner graph instead.
+**Write specific goals.** Orca passes your task to a planner — vague input produces vague plans.
 
-### Post-execution review / fix cycles
+- Bad: `"fix the bug"`
+- Good: `"Fix the TypeError thrown on logout with an expired token in src/auth/session.ts. Ensure existing tests pass and add a regression test."`
 
-After task execution, Orca can run deterministic validation commands, then ask Codex to review findings and optionally auto-fix issues in bounded cycles.
+---
 
-- `review.execution.enabled` (default `true`)
-- `review.execution.maxCycles` (default `2`)
-- `review.execution.onFindings`:
-  - `auto_fix` (default): apply fixes and continue until clean or max cycles
-  - `report_only`: report findings and stop
-  - `fail`: mark run failed when findings exist
-- `review.execution.validator.auto` (default `true`): auto-detect validator commands from `package.json`
-  - Caveat: `ORCA_SKIP_VALIDATORS=1` forces this to `false` at runtime
-- `review.execution.validator.commands` (optional explicit command list)
-- `review.execution.prompt` (optional custom reviewer instruction)
+## Common Workflows
 
-When using the Codex executor, Orca enforces a strict reviewer JSON schema (`{summary, findings, fixed}`) as the primary path. If the first response is malformed, Orca issues one deterministic repair prompt (max 2 attempts total); if still invalid, it emits an `onFindings` event with an explicit parse error and stops auto-fix progression for that cycle.
+### Status & monitoring
 
-Run the dedicated integration coverage for this JSON retry/validation path with `npm run test:postexec-json`.
+```bash
+orca status                  # list all runs
+orca status --last           # most recent run
+orca status --run <run-id>   # specific run
+orca list                    # alias for status
+```
 
-Orca then prints a final post-execution review summary.
+Run states: `planning` → `running` → `completed` | `failed` | `cancelled` | `waiting_for_answer`
 
-## Spec And Plan Files
+### Answering questions
 
-Use a spec/plan markdown file when you already have a written breakdown:
+If a run hits `waiting_for_answer`, it's blocked until you respond:
 
 ```bash
-orca --spec ./specs/feature.md
-orca --plan ./specs/feature.md
+orca status --last                          # read the question
+orca answer <run-id> "yes, use migration A"  # unblock it
 ```
 
-If you only want planning (no execution):
+### Spec / plan files
+
+Use a markdown spec instead of an inline task:
 
 ```bash
-orca plan --spec ./specs/feature.md
+orca --spec ./specs/feature.md   # plan + execute
+orca plan --spec ./specs/feature.md  # plan only, no execution
 ```
 
-## Run Management
+### Failure & recovery
 
 ```bash
-orca status                  # list all runs (summary table)
-orca status --last           # status of the most recent run
-orca status --run <run-id>   # status of a specific run
-
-orca list
+orca resume --last   # retry from last checkpoint
+orca cancel --last   # abort
+```
 
-orca resume --last
-orca resume --run <run-id>
+Common failures:
+- `auth error` → re-auth Codex (`codex auth`) or set `OPENAI_API_KEY` / `ORCA_OPENAI_API_KEY`
+- `no git repo` → `cd` into a git repo
+- `plan invalid` → goal too vague; cancel and restate
+- Session logs: `./session-logs/` (or `sessionLogs` config path)
 
-orca cancel --last
-orca cancel --run <run-id>
+### PR workflow
 
-orca answer <run-id> "yes, use migration A"
+```bash
+orca pr draft --last     # open a draft PR (won't trigger CI)
+orca pr publish --last   # un-draft it
+orca pr create --last    # draft + publish in one step
+orca pr status --last    # check PR and CI status
 ```
 
-## PR Workflow
+Orca always works on a branch — never pushes directly to main/master.
 
-```bash
-orca pr
-orca pr draft --run <run-id>
-orca pr create --run <run-id>
-orca pr publish --run <run-id>
-orca pr status --run <run-id>
-
-orca pr publish --last
-orca pr publish --config ./orca.config.js   # accepted, currently unused by PR command resolution
-
-# Non-TTY requires explicit run selection
-orca pr publish --run <run-id>
-orca pr publish --last
-```
+---
 
 ## Config
 
-Orca auto-discovers config in this order:
+Orca loads config in this order (later overrides earlier):
 
-1. `~/.orca/config.js`
-2. Project config: `./orca.config.ts` (preferred when both exist) or `./orca.config.js`
-3. `--config <path>` (if passed)
+1. `~/.orca/config.ts` or `~/.orca/config.js` (global)
+2. `./orca.config.ts` or `./orca.config.js` (project)
+3. `--config <path>` (explicit)
 
-Later entries override earlier ones.
+`.ts` is preferred over `.js` when both exist.
 
 ```ts
 // orca.config.ts
 import { defineOrcaConfig } from "orcastrator";
 
 export default defineOrcaConfig({
-  executor: "codex",
-  anthropicApiKey: process.env.ANTHROPIC_API_KEY,
-  openaiApiKey: process.env.OPENAI_API_KEY,
-  runsDir: "./.orca/runs",
+  executor: "codex",              // only supported value
+  runsDir: "./.orca/runs",        // default: ~/.orca/runs
   sessionLogs: "./session-logs",
   skills: ["./.orca/skills"],
   maxRetries: 1,
-  claude: {
-    model: "claude-sonnet-4-20250514",
-    effort: "medium",
-    useV2Preview: true,
-    maxTurnsPerTask: 12,
-    allowTextJsonFallback: false
-  },
+
   codex: {
-    enabled: true,
     model: "gpt-5.3-codex",
-    effort: "medium",
-    command: "codex",
+    effort: "medium",             // "low" | "medium" | "high" — applies to all Codex turns
     timeoutMs: 300000,
-    multiAgent: false,
+    multiAgent: false,      // see Multi-agent section
     perCwdExtraUserRoots: [
       { cwd: process.cwd(), extraUserRoots: ["/tmp/shared-skills"] }
-    ]
-  },
-  hooks: {
-    onTaskComplete: async (event, context) => {
-      console.log(`task done: ${event.taskId} (${event.taskName}) from pid ${context.pid}`);
-    },
-    onError: async (event) => {
-      console.error(event.error);
-    }
-  },
-  hookCommands: {
-    onTaskComplete: "node ./scripts/on-task-complete.mjs",
-    onComplete: "echo run complete",
-    onError: "echo run failed"
-  },
-  pr: {
-    enabled: true,
-    requireConfirmation: true
+    ],
   },
+
   review: {
-    // Deprecated compatibility aliases (prefer review.plan.*):
-    // enabled: true,
-    // onInvalid: "fail",
     plan: {
       enabled: true,
-      onInvalid: "fail"
+      onInvalid: "fail",    // "fail" | "warn_skip"
     },
     execution: {
       enabled: true,
       maxCycles: 2,
-      onFindings: "auto_fix",
+      onFindings: "auto_fix",  // "auto_fix" | "report_only" | "fail"
       validator: {
-        auto: true,
-        // commands: ["npm run validate"]
+        auto: true,            // auto-detect validators from package.json
+        // commands: ["npm run validate"]  // explicit override
       },
       // prompt: "Prefer minimal safe fixes"
-    }
-  }
-});
-```
-
-### Config field reference (OrcaConfig)
-
-Top-level: `executor`, `anthropicApiKey`, `openaiApiKey`, `runsDir`, `sessionLogs`, `skills`, `maxRetries`, `hooks`, `hookCommands`, `pr`, `review`, `claude`, `codex`.
-
-- `pr.enabled`, `pr.requireConfirmation`
-- `maxRetries` is part of `OrcaConfig`; current planner-generated task retries remain fixed in task graph contracts
-- `claude.model`, `claude.effort`, `claude.useV2Preview`, `claude.maxTurnsPerTask`, `claude.allowTextJsonFallback`
-- `codex.enabled`, `codex.model`, `codex.effort`, `codex.command`, `codex.timeoutMs`, `codex.multiAgent`, `codex.perCwdExtraUserRoots`
-- `review.plan.enabled`, `review.plan.onInvalid`
-- `review.execution.enabled`, `review.execution.maxCycles`, `review.execution.onFindings`, `review.execution.validator.auto`, `review.execution.validator.commands`, `review.execution.prompt`
-- Deprecated compatibility aliases: `review.enabled`, `review.onInvalid` (still accepted; prefer `review.plan.*`)
-
-### Multi-agent mode
+    },
+  },
 
-Codex supports experimental [multi-agent workflows](https://developers.openai.com/codex/multi-agent) where it can spawn parallel sub-agents for complex tasks.
+  pr: {
+    enabled: true,
+    requireConfirmation: true,
+  },
 
-To enable it in Orca, set `codex.multiAgent: true` in your config:
+  hooks: {
+    onTaskComplete: async (event, context) => {
+      console.log(`task done: ${event.taskId} from pid ${context.pid}`);
+    },
+    onError: async (event) => { console.error(event.error); },
+  },
 
-```js
-export default {
-  codex: { multiAgent: true }
-};
+  hookCommands: {
+    onComplete: "echo run complete",
+    onError: "echo run failed",
+    onTaskComplete: "node ./scripts/on-task-complete.mjs",
+  },
+});
 ```
 
-When enabled, Orca adds `multi_agent = true` to your global `~/.codex/config.toml`. If you already have multi-agent enabled in your Codex config, it will work automatically without setting anything in Orca.
-
-> **Note:** Multi-agent is off by default because enabling it modifies your global Codex configuration. It is currently an experimental Codex feature.
-
-## Reference
-
-### Flags
-
-Global:
-
-- `-h, --help`
-- `-V, --version`
-
-`orca` / `orca run`:
-
-- positional: `[task]`
-- also works: `--task <text>`, `-p, --prompt <text>`
-- `--spec <path>`
-- `--plan <path>`
-- `--config <path>`
-- `--codex-only` (force Codex executor for this run)
-- `--claude-only` (force Claude executor for this run)
-- `--codex-effort <low|medium|high>`
-- `--claude-effort <low|medium|high|max>`
-- `--on-milestone <cmd>`
-- `--on-task-complete <cmd>`
-- `--on-task-fail <cmd>`
-- `--on-invalid-plan <cmd>`
-- `--on-findings <cmd>`
-- `--on-complete <cmd>`
-- `--on-error <cmd>`
+### Review cycle
 
-`orca plan`:
+After planning, Orca runs a pre-execution review that can edit the task graph (add/remove tasks, update fields, adjust dependencies) before execution starts.
 
-- `--spec <path>`
-- `--config <path>`
-- `--on-milestone <cmd>`
-- `--on-error <cmd>`
+After execution, Orca runs validation commands and asks Codex to review findings. With `onFindings: "auto_fix"`, it applies fixes and retries up to `maxCycles` times, then reports. Set `ORCA_SKIP_VALIDATORS=1` to skip validator auto-detection at runtime.
 
-`orca status`:
-
-- `--run <run-id>`
-- `--last`
-- `--config <path>`
-
-`orca resume`:
-
-- `--run <run-id>`
-- `--last`
-- `--config <path>`
-- `--codex-only`
-- `--claude-only`
-- `--codex-effort <low|medium|high>`
-- `--claude-effort <low|medium|high|max>`
-
-`orca cancel`:
-
-- `--run <run-id>`
-- `--last`
-- `--config <path>`
+### Multi-agent mode
 
-`orca answer`:
+Set `codex.multiAgent: true` to spawn parallel Codex agents per task. Faster for large refactors with independent subtasks; higher token cost. **Note:** this writes `multi_agent = true` to your global `~/.codex/config.toml`.
 
-- positional: `[run-id] [answer]`
-- `--run <id>`
+### Skills
 
-`orca list`:
+Orca auto-loads skills in this precedence order (first name wins):
 
-- `--config <path>`
+1. `config.skills[]`
+2. `./.orca/skills/` (project-local)
+3. `~/.orca/skills/` (global)
+4. Bundled defaults (includes `code-simplifier`)
 
-`orca pr draft|create|publish|status`:
+Inject additional app-server-visible skills via `codex.perCwdExtraUserRoots`.
 
-- `--run <run-id>`
-- `--last`
-- `--config <path>` (accepted for compatibility; currently unused by PR command run resolution)
+---
 
-`orca pr publish`:
+## CLI Reference
 
-- `--run <run-id>`
-- `--last`
-- `--config <path>` (accepted for compatibility; currently unused by PR command run resolution)
-- If neither `--run` nor `--last` is provided: interactive run picker in TTY; non-TTY requires `--run` or `--last`
+```
+orca <task>                              Start a run
+orca --spec <path>                       Run from a spec file
+orca plan --spec <path>                  Plan only, no execution
+
+orca status [--last | --run <id>]        Run status
+orca list                                List all runs
+orca resume [--last | --run <id>]        Retry from checkpoint
+orca cancel [--last | --run <id>]        Abort a run
+orca answer <run-id> "<text>"            Answer a waiting question
+
+orca pr draft [--last | --run <id>]      Open draft PR
+orca pr create [--last | --run <id>]     Create and publish PR
+orca pr publish [--last | --run <id>]    Un-draft an existing PR
+orca pr status [--last | --run <id>]     PR and CI status
+                                         (non-TTY: --run or --last required)
+
+orca skills                              List loaded skills
+orca setup                               Interactive setup wizard
+```
 
-`orca skills`:
+**Key flags for `orca` (run):**
 
-- `--config <path>`
+- `--codex-only` — force Codex executor
+- `--codex-effort <low|medium|high>` — override effort for this run
+- `--config <path>` — explicit config file
+- `--on-complete <cmd>`, `--on-error <cmd>`, `--on-task-complete <cmd>`, `--on-findings <cmd>`, etc.
 
-`orca setup`:
+**Key flags for `orca resume`:**
 
-- `--anthropic-key <key>` — override Anthropic API key (written to config)
-- `--openai-key <key>` — override OpenAI API key (written to config)
-- `--executor <codex|claude>` — explicitly set executor in written config
-- `--global` — save to `~/.orca/config.js` (default)
-- `--project` — save to `./orca.config.js`
-- `--project-config-template` — write typed project hook template to `./orca.config.ts`
-- `--skip-project-config` — skip project config prompt
+- `--codex-only`, `--codex-effort <low|medium|high>`, `--config <path>`, `--run <id>`, `--last`
 
-`orca help`:
+**`orca setup` flags:**
 
-- positional: `[command]` — show help for a specific command (e.g. `orca help plan`)
-- no flags; also works as `orca --help` or `orca <command> --help`
+- `--openai-key <key>` — write key to config
+- `--executor <codex>` — set executor
+- `--ts` — write TypeScript config
+- `--global` — write to `~/.orca/config.js`
+- `--project` — write to `./orca.config.js`
 
 ### Hooks
 
-Hook names:
-
-- `onMilestone`
-- `onTaskComplete`
-- `onTaskFail`
-- `onInvalidPlan`
-- `onFindings`
-- `onComplete`
-- `onError` (fires on run failures and hook-dispatch failures)
-
-Run hooks from CLI with `--on-...` flags or from config via `hooks` / `hookCommands`.
-Unknown hook keys in config are rejected at load time with an explicit allowed-hook list.
-
-Hook contract:
-- Function hooks (`config.hooks`) are the primary path and are strongly typed per hook event.
-- Every function hook receives `(event, context)` where `context` is deterministic: `{ cwd, pid, invokedAt }`.
-- Command hooks (`--on-...` and `config.hookCommands`) receive the full event payload as JSON over stdin.
-- Orca no longer injects hook payload via `ORCA_*` env vars.
-
-Smoke-test the hook contract (function + command + concurrency): `npm run smoke:hooks`.
+Available hook names: `onMilestone`, `onTaskComplete`, `onTaskFail`, `onInvalidPlan`, `onFindings`, `onComplete`, `onError`.
 
-### Run ID Format
-
-Run IDs are generated as:
-
-- `<slug>-<unix-ms>-<hex4>`
-- Example: `feature-auth-1766228123456-1a2b`
-
-### Config File Locations
-
-- Global: `~/.orca/config.js`
-- Project: `./orca.config.js` or `./orca.config.ts`
-- Explicit: `--config <path>`
-
-### Project Instruction Files
-
-During planning, Orca automatically injects project instruction files when present:
-
-1. `AGENTS.md`
-2. `CLAUDE.md`
-
-Files are discovered from the project root (nearest `.git` from the spec/task context) and injected in that order.
-
-If both filenames resolve to the same underlying file (for example, `CLAUDE.md` symlinked to `AGENTS.md`), Orca injects that content only once and keeps the first entry in order (`AGENTS.md`).
-
-### Project Skills
-
-Orca auto-loads skills in this precedence order (first matching skill name wins):
-
-1. `config.skills[]`
-2. `./.orca/skills/` (project-local, from current working directory)
-3. `~/.orca/skills/` (global)
-4. Bundled defaults from the Orca package: `<orca package root>/.orca/skills/`
+- Function hooks (`config.hooks`): receive `(event, context)` where `context = { cwd, pid, invokedAt }`
+- Command hooks (`config.hookCommands` / `--on-*` flags): receive full event JSON over stdin
+- Unknown hook keys in config are rejected at load time
 
-This repo ships a bundled default `code-simplifier` skill at `./.orca/skills/code-simplifier/SKILL.md`, and it loads even when Orca runs in arbitrary target repositories. Project/global/config skills can still override it by reusing the same skill name. Planner/reviewer/executor prompts explicitly apply `code-simplifier` guidance for all code-writing and code-review steps while keeping behavior unchanged unless a task explicitly requires behavior changes.
+### Run ID format
 
-When Orca uses the Codex executor, each turn is sent with both:
-- a text input item (`{ type: "text", text: ... }`), and
-- explicit skill input items (`{ type: "skill", name, path }`) for every loaded skill in the same precedence order above.
+`<slug>-<unix-ms>-<hex4>` — e.g. `feature-auth-1766228123456-1a2b`
 
-At session startup, Orca also calls Codex app-server `skills/list` with `forceReload: true` (and optional `codex.perCwdExtraUserRoots`) so additional app-server-visible skills can be appended deterministically without overriding Orca-local precedence.
+### Run state locations
 
-This keeps Codex skill loading deterministic instead of relying only on prompt/context pickup.
-
-### Run State Locations
-
-- Run status: `<runsDir>/<run-id>/status.json`
+- Status: `<runsDir>/<run-id>/status.json`
 - Answer payloads: `<runsDir>/<run-id>/answer.txt`
-- `runsDir` defaults to `~/.orca/runs` unless overridden by `ORCA_RUNS_DIR`.
+- `runsDir` defaults to `~/.orca/runs` (override with `ORCA_RUNS_DIR`)
 
-## Development
+### Project instruction files
 
-Install dependencies with npm (primary lockfile):
+Orca injects `AGENTS.md` into planning context when found at the project root.
 
-```bash
-npm install
-```
+---
 
-Run local development and tests with Bun (faster runtime for this project):
+## Development
 
 ```bash
-bun run src/cli/index.ts "your task here"
+npm install        # canonical install (use npm for deps)
+bun run src/cli/index.ts "task"   # local dev
 bun test src
 npm run test:postexec-json
 ```
 
-## Validation pipeline
-
-Use the full validation gate before opening/publishing changes:
+Full validation gate (runs lint → type-check → tests → build):
 
 ```bash
 npm run validate
 ```
 
-This runs, in order:
-
-1. `npm run lint` (Oxlint syntax/style/static rules)
-2. `npm run lint:type-aware` (Oxlint + tsgolint alpha type-aware + type-check diagnostics)
-3. `npm run typecheck` (TypeScript Native Preview via `tsgo --noEmit`, with environment fallback to `tsc --noEmit`)
-4. `npm run test`
-5. `npm run build`
-
-`npm run build` remains `tsc` because the native preview compiler is used here as a fast typecheck gate; production JS emission stays on stable `typescript` for predictable package output.
-
-## GitHub release tracking (tags only)
-
-Orca includes a lightweight GitHub Actions workflow at `.github/workflows/release.yml`:
-
-- Trigger: push a tag matching `v*` (workflow only releases SemVer tags like `v0.4.0` or `v0.4.0-rc.1`)
-- Behavior: create or update the matching GitHub Release
-- Notes: auto-generated by GitHub (`generate_release_notes: true`)
-
-This workflow is for release tracking/changelogs only. It does not publish to npm.
-
-## npm publish automation (GitHub Actions)
+### Package manager policy
 
-Orca includes a publish workflow at `.github/workflows/publish.yml`.
+- **npm** — canonical for deps, CI, and publish (`package-lock.json`)
+- **Bun** — used as runtime/test runner locally (`bun.lock`)
 
-- Primary trigger: push a tag matching `v*` (for example `v1.2.3` or `v1.2.3-rc.1`)
-- Optional fallback: manual `workflow_dispatch`
-- Required secret: `NPM_TOKEN`
-- Behavior: checkout → Node setup (npm registry auth) → safety checks → `npm ci` → `npm run validate` → publish if version is not already on npm
+Commit both lockfiles. When changing deps: `npm install && bun install`.
 
-Safety checks enforced before publish:
+---
 
-1. Tag must be SemVer-like (`vX.Y.Z` with optional prerelease/build metadata)
-2. Release commit must be reachable from the repository default branch
-3. `package.json` version must match the tag version (without the leading `v`)
-4. If the version already exists on npm, publish is skipped as a safe no-op
-
-### Safe setup
-
-1. In GitHub, open **Settings → Secrets and variables → Actions** for this repository.
-2. Add a repository secret named `NPM_TOKEN`.
-   - Create this token in npm as a granular automation/publish token scoped only to `orcastrator`.
-3. Use least privilege, avoid reusing broad account tokens, and rotate the token periodically.
-
-### Safe run flow
-
-1. Bump `package.json` to the intended release version.
-2. Create and push a matching tag, for example: `git tag v1.2.3 && git push origin v1.2.3`.
-3. Verify the package on npm after the workflow completes.
-4. If needed, run the same workflow manually from **Actions → npm Publish → Run workflow** as a fallback (use an existing tag so the workflow publishes that exact tagged commit).
-
-## Package manager + lockfile policy
-
-Orca uses a mixed runtime/tooling model on purpose:
-
-- **npm is canonical for dependency resolution, release builds, and deterministic installs**.
-- **Bun is used as a runtime/test runner in local workflows** (`dev`, `start`, `test`).
-
-Commit both lockfiles:
-
-- `package-lock.json` — canonical dependency graph for npm/CI/publish
-- `bun.lock` — Bun runtime resolution parity for local Bun commands
-
-When dependencies change, update both lockfiles in the same PR:
-
-```bash
-npm install
-bun install
-```
+## License
 
-This keeps npm and Bun behavior aligned without forcing a disruptive full migration.
+MIT — see [LICENSE](./LICENSE).