chore: release 0.2.0 — version bump, changelog, release notes, roadmap sync, discovery strings

.agents/plugins/marketplace.json

@@ -10,7 +10,7 @@
         "source": "local",
         "path": "./"
       },
-      "description": "Multi-repo Git workspaces for any AI coding agent — one agent across many repos."
+      "description": "One agent across many repos — real git worktrees, no index"
     }
   ]
 }

.claude-plugin/marketplace.json

@@ -7,7 +7,7 @@
     {
       "name": "claude-orbit",
       "source": "./",
-      "description": "Multi-repo Git workspaces for any AI coding agent — one agent across many repos."
+      "description": "One agent across many repos — real git worktrees, no index"
     }
   ]
 }

.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "claude-orbit",
-  "version": "0.1.0",
-  "description": "Multi-repo Git workspaces for any AI coding agent — one agent across many repos.",
+  "version": "0.2.0",
+  "description": "One agent across many repos — real git worktrees, no index",
   "author": {
     "name": "orbcli contributors"
   },

.codex-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "codex-orbit",
-  "version": "0.1.0",
-  "description": "Multi-repo Git workspaces for any AI coding agent — one agent across many repos.",
+  "version": "0.2.0",
+  "description": "One agent across many repos — real git worktrees, no index",
   "author": {
     "name": "orbcli contributors"
   },
@@ -19,7 +19,7 @@
   "hooks": "./hooks/codex/hooks.json",
   "interface": {
     "displayName": "Orbit",
-    "shortDescription": "Multi-repo Git workspaces for AI coding agents",
+    "shortDescription": "One agent across many repos — real git worktrees, no index",
     "longDescription": "Orbit is a Git-native multi-repo workspace manager that lets AI coding agents work across many repositories in a single session. It provides workspace management, repo discovery, memo cards for guiding repo pull decisions, and jot-based knowledge capture for incremental discovery.",
     "developerName": "orbcli contributors",
     "category": "Developer Tools",

.opencode-plugin/package.json

@@ -1,7 +1,7 @@
 {
   "name": "opencode-orbit",
-  "version": "0.1.0",
-  "description": "Multi-repo Git workspaces for OpenCode — one agent across many repos",
+  "version": "0.2.0",
+  "description": "One agent across many repos — real git worktrees, no index",
   "type": "module",
   "main": "index.ts",
   "files": [

.qoder-plugin/marketplace.json

@@ -7,7 +7,7 @@
     {
       "name": "qoder-orbit",
       "source": "./",
-      "description": "Multi-repo Git workspaces for any AI coding agent — one agent across many repos."
+      "description": "One agent across many repos — real git worktrees, no index"
     }
   ]
 }

.qoder-plugin/plugin.json

@@ -1,8 +1,8 @@
 {
   "name": "qoder-orbit",
   "displayName": "Orbit",
-  "version": "0.1.0",
-  "description": "Multi-repo Git workspaces for any AI coding agent — one agent across many repos.",
+  "version": "0.2.0",
+  "description": "One agent across many repos — real git worktrees, no index",
   "author": {
     "name": "orbcli contributors"
   },

README.md

@@ -183,7 +183,7 @@ Resuming a workspace with repos already present skips priming — the same `--st
 
 ## Auto-approving safe commands
 
-Plugin users: nothing to configure — all four plugins (Claude, Codex, OpenCode, Qoder) auto-approve safe orbit subcommands. Skill-only users can allowlist by hand. See [`skills/CONSTRAINTS.md`](skills/CONSTRAINTS.md#permission-and-auto-execution-policy) for command tiers and the allowlist snippet.
+Plugin users: nothing to configure — all four plugins (Claude Code, Codex, OpenCode, Qoder) auto-approve safe orbit subcommands. The hook needs `jq` on PATH; without it the hook stays inert and you keep the native prompts. The dependency goes away in a future release. Skill-only users can allowlist by hand. See [`skills/CONSTRAINTS.md`](skills/CONSTRAINTS.md#permission-and-auto-execution-policy) for command tiers and the allowlist snippet.
 
 ## Command Reference
 

RELEASE_NOTES.md

@@ -1,5 +1,37 @@
+# 🚀 Orbit v0.2.0 — MaxQ
+
+*Released 2026-08-23*
+
+**Multi-repo Git workspaces for any coding agent — real worktrees, no index, no server.**
+
+MaxQ is the ascent phase where aerodynamic stress peaks and the airframe either holds or doesn't — seven weeks of daily dogfooding put this release under exactly that, and the structure held: 26 PRs of hardening, contract pinning, and repair.
+
+## Highlights
+
+- **The destructive surface is now machine-enforced.** `prune` and `sync --force`/`--branch` run from the project root only, verified by process ancestry — not by convention. Prune was rebuilt around all-or-nothing validation, per-branch verdicts, and a `.prune-trash` recovery window.
+- **The context system was redesigned.** Session start injects a purpose-built startup block (goal, repo memos, staleness); resume/compact get a cheap cruise block. Hooks anchor to the host-injected project dir, so injection works across Claude Code, Codex, OpenCode, and Qoder — IDE included.
+- **Install means latest.** Every install run now refreshes the marketplace snapshot and reinstalls the plugin from it; `--force` is a full reset (with a reachability probe so an offline reset can't destroy your last working install). The runtime itself refreshes the same way.
+
+## ⚠️ Breaking changes (upgrading from 0.1.0)
+
+- `prune` and `sync --force`/`--branch` run from the project root only — the CLI checks the calling shell's process ancestry, so `cd`-ing out first does not bypass it, and no flag does either. `prune` also left the agent skill's action surface: agents report the need, humans run it.
+- `prune --force` now overrides the data guards too, not just branch protection — it announces what it discards first.
+- `prune --verify` removed (merged-PR evidence now applies automatically from recorded PR URLs when `gh` is available); `ORBIT_BRANCH_PREFIX` is no longer read (use `orbit config branch.prefix`).
+- `install.sh` refreshes on every run; `--force` is now a full plugin+marketplace reset (it probes source reachability first).
+- Pool fetch and push config is Orbit-maintained (wildcard refspec + `fetch.prune` + `push.default=upstream`; opt out per key via `orbit config`) — a bare `git fetch`/`git pull` in any worktree now fetches every branch.
+- Output contracts changed: the old fetch-refspec reconciliation lines are gone and prune's report shape changed — update anything that greps orbit's output.
+- OpenCode plugin/skill removal is directory-level — anything inside `~/.config/opencode/skills/orbit/` is deleted.
+
+Also in: network-resilient installs (source chain + retries), SSH-less plugin install, demo runs on zero-config machines, guidance for config-management tools that silently roll back plugin registration ([USAGE](USAGE.md#config-management-tools) — recovery and prevention, per host), and a set of removals (stop hooks, the refspec registry, `--replace-marketplace`, and more — the full list is in the changelog); the mission drops spent weight to stay on course. Covered by 396 bats tests.
+
+Full details in the [changelog](CHANGELOG.md).
+
+---
+
 # 🚀 Orbit v0.1.0 — Liftoff
 
+*Released 2026-07-06 · superseded by v0.2.0 (see above)*
+
 **Source code as agent knowledge — multi-repo Git workspaces where agents read, code, and ship.**
 
 Orbit manages multi-repo Git workspaces for AI coding agents. Instead of embeddings, vector stores, or stitching together scattered docs, agents work directly against full source worktrees — grepping API signatures, tracing call chains, then editing, committing, and pushing, all from one directory. Every task gets its own isolated workspace, so multiple agents can run in parallel without stepping on each other.

ROADMAP.md

@@ -6,49 +6,56 @@
 - Command system aligned with design specs: 18 commands covering the complete workflow (clone / new / add / switch / jot / sync / done / prune / status / goal / repos / info / memo / config / context / doctor / completion / version)
 - Metadata infrastructure (`.repos/.orbit` global index + per-repo `.md` + workspace `.orbit` + brief extraction + staleness detection)
 - CLI experience: `--json` output + bash/zsh shell completion
-- Claude Code skill + Qoder skill + Unified installer
+- Skills/plugins bundled for four agents (Claude Code / Codex / OpenCode / Qoder) + unified installer
 - Core documentation (README / USAGE / ROADMAP / PRINCIPLES / spec series)
 - `orbit add --ref <tag/branch>`: checkout to specified ref when creating worktree, ensuring the source code version the agent verifies matches the project's actual dependencies
 - `orbit memo --scaffold`: generate scaffold template to stdout (directory structure + README first paragraph + primary language detection), agent uses this as reference to write formal memo
-- `orbit context`: output complete context of current workspace (goal + repo brief/memo + background info), agent gets all needed context with one command after entering workspace
-- `orbit repos --json` output adds `memoBehind` field: agent can judge memo freshness at Level 0
 - `orbit sync [repo...] [--force] [--branch <branch>]`: sync pool repo to upstream latest (fast-forward / force reset / switch tracking branch)
 - `orbit info` two-layer staleness detection (remoteAhead / memoBehind), reading last-fetched refs
 - `orbit doctor`: environment health check (git ≥2.20 / bash ≥3.2 / jq+gh optional dependencies / `.repos/` structural integrity diagnostics)
 - `orbit jot`: lightweight discovery queue (push/pop) for recording knowledge during work, aggregated into memo at natural breakpoints — reduces per-discovery cost from ~500 tokens to ~20 tokens
-- Deterministic session-start context injection: the plugin ships a `SessionStart` hook (startup / resume / compact) that runs `orbit context` to keep the agent aware it is inside a workspace — proven on **Claude Code** and **Qoder**, zero user effort (prompts to install the runtime when `orbit` is missing).
+- Deterministic session-context injection: plugin-shipped hooks (SessionStart / resume / compact) keep the agent workspace-aware, working across all four bundled agents — zero user effort (prompts to install the runtime when `orbit` is missing)
+- Destructive-surface hardening: machine-enforced root-only `prune` / `sync --force`, per-branch verdicts, `.prune-trash` recovery
+- Context system: startup/cruise injection blocks; hook CWD anchoring across all four agents (incl. Qoder IDE JSON wrappers)
+- Install semantics: every install refreshes to latest; `--force` = full plugin+marketplace reset with reachability probe
+- Network-resilient installs (source chain + retries); SSH-less install; zero-config demo (`try.sh`)
+- Plugin distribution: Claude Code / Codex / OpenCode / Qoder marketplaces + npm (`opencode-orbit`)
+
+## Short-term
+
+### Runtime & UX
+
+- [ ] Performance: hot paths (session start, `status`, `context`, `prune`) get measurably faster
+- [ ] Drop the `jq` dependency — auto-approve hooks parse payloads natively
+- [ ] Color output (TTY-aware): auto-colorize when `[ -t 1 ]`, plain text when piped
+
+### Integrity (pool & workspace)
+
+- [ ] Pool repo lifecycle: `retire` / `rename` for pool repos (clone gives birth; nothing takes them away)
+- [ ] Pool shared-config self-heal via touchpoint convergence (native git has no permission model — prevention isn't possible, so converge-and-repair it is)
+- [ ] Workspace integrity recovery: best-effort restoration of required elements
 
 ## Mid-term
 
-### Knowledge Sharing
+### Agent Ecosystem
 
-- [ ] `export`: export repos + workspace combination as a reproducible rebuild script, enabling team members to one-click replicate the knowledge base (strategic: portability foundation for repos as team knowledge assets)
-- [ ] `import`: rebuild repos + workspace environment from export script
+- [ ] [pi](https://github.com/earendil-works/pi) support: bundled integration (skill + session-context injection) for the pi coding agent
 
 ### Feature Enhancements
 
-- [ ] Color output (TTY-aware): auto-colorize when `[ -t 1 ]` detects TTY, plain text when piped/redirected
 - [ ] `orbit new --auto-name` agent auto-naming (opt-in)
-- [ ] Cross-worktree conflict detection: detect files modified in the same repo across different workspaces, warning of potential merge conflicts
-- [ ] PR URL → worktree: `orbit add <repo> --pr <url>` auto-fetch PR head branch to create worktree (depends on gh CLI)
+- [ ] PR URL → worktree: `orbit add <repo> --pr <url>` fetches the PR head via origin's `pull/N/head` ref (GitHub first; no extra remote, no gh dependency)
 
 ## Long-term
 
-- [ ] `graph`: cross-repo dependency graph
+### Repo Graph
 
-## Backlog
+- [ ] `graph`: cross-repo dependency/reference graph over the pool — code refs and memo links alike; the long-run shape is an Obsidian-style graph view built on the link structure
 
-The following items come from community benchmarking analysis. Not prioritized now but not excluded for the future. Entry criteria: short-term feasibility + validated real demand.
+### Memo Management
 
-- [ ] `trust` security model: repo-defined executable hooks require explicit approval before execution, preventing malicious repo injection (distinct from the plugin `SessionStart` hook; prerequisite: after a repo-hooks mechanism exists)
-- [ ] Workspace fork: `orbit fork <src-ws> <new-ws>` derive from existing workspace (prerequisite: after lifecycle stabilization)
-- [ ] `orbit watch`: daemon monitoring PR merged / branch deleted, triggering notifications or auto prune
-- [ ] Port range environment isolation: each workspace assigned an independent port range to avoid multi dev server conflicts (opt-in)
-- [ ] MCP server: expose orbit capabilities as MCP endpoint (skill already provides agent integration path, MCP is supplementary not prerequisite)
-- [ ] `exec "<cmd>"`: batch execute on all repos within workspace (not essential for agent scenarios, nice-to-have for human scenarios)
-- [ ] `orbit add` config file copy: copy gitignored config files from repos to worktree (only serves "running code" scenarios, not core to agent knowledge path)
-- [ ] `.code-workspace` auto-generation: pure human IDE DX, not core to agent knowledge path
-- [ ] Optional TUI mode: pure human interactive experience (prerequisite: after core command system stabilization)
+- [ ] Memo write-pollution guard: a weaker agent's card write must not silently overwrite a stronger one (single-level `.bak` rotation before writeback)
+- [ ] Memo staleness by content anchors (best-effort hints only: free-form card input means no hard verdicts)
 
 ## Known Issues and Compatibility
 
@@ -58,7 +65,7 @@ The following items come from community benchmarking analysis. Not prioritized n
 | 2 | JetBrains IDE worktree support | IntelliJ / GoLand | Unconfirmed | Whether VCS model correctly recognizes worktree |
 | 3 | Language server cross-repo references | gopls / tsserver | Unconfirmed | Multi-repo cross-references under workspace |
 | 4 | Qoder / VS Code worktree recognition | Qoder + VS Code | Confirmed (working) | Branch, status, diff all work correctly |
-| 5 | Session-start context injection on other frameworks | Agent frameworks beyond Claude Code / Qoder | Fallback only | No native `SessionStart`-equivalent hook means deterministic injection isn't available; the agent relies on the `orbit start` trigger phrase, which depends on the launch phrase actually being used |
+| 5 | Session-start context injection on other frameworks | Agent frameworks beyond the four bundled ones (Claude Code / Codex / OpenCode / Qoder) | Fallback only | No native `SessionStart`-equivalent hook means deterministic injection isn't available; the agent relies on the `orbit start` trigger phrase, which depends on the launch phrase actually being used |
 
 ## Notes
 

USAGE.md

@@ -605,7 +605,7 @@ orbit completion bash > /path/to/bash-completion/completions/orbit
 
 An orbit session runs read-only and idempotent subcommands (`context` / `repos` / `info` / `status`, plus workspace-writes like `add` / `memo` / `jot`) constantly, so per-command confirmation prompts add up. Those framework-verified tiers can run without a prompt; destructive or externally-visible commands (`prune` `clone` `config`) always keep prompting. Workflow-timing commands (`done` `new`) are deliberately outside the framework's list — orbit takes no position on when they should run; allowlist them in your own agent settings if you want them prompt-less.
 
-**Plugin users — nothing to do:** all four plugins ship an auto-approve hook that approves exactly the framework-verified subcommands and fails safe. **Skill-only / other agents:** add a static allowlist to your agent settings.
+**Plugin users — nothing to do:** all four plugins ship an auto-approve hook that approves exactly the framework-verified subcommands and fails safe. The hook needs `jq` on PATH; without it the hook stays inert and you keep the native prompts. The dependency goes away in a future release. **Skill-only / other agents:** add a static allowlist to your agent settings.
 
 The exact command tiers, the ready-to-paste allowlist snippet, and the rationale for each tier all live in [`skills/CONSTRAINTS.md`](skills/CONSTRAINTS.md#permission-and-auto-execution-policy).
 

docs/spec-commands.md

@@ -322,7 +322,7 @@ Environment health check; does not require being inside an orbit project.
 
 ## orbit version
 
-Prints the orbit runtime version (e.g. `0.1.0`) to stdout and exits 0. Does not require being inside an orbit project. `--version` and `-v` are aliases. This is the runtime version, distinct from the plugin manifest version — the runtime is installable on its own (`install.sh` / curl bootstrap), so it carries its own version.
+Prints the orbit runtime version (e.g. `0.2.0`) to stdout and exits 0. Does not require being inside an orbit project. `--version` and `-v` are aliases. This is the runtime version, distinct from the plugin manifest version — the runtime is installable on its own (`install.sh` / curl bootstrap), so it carries its own version.
 
 ## Edge Case Handling
 

orbit.sh

@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-ORBIT_VERSION="0.1.0"
+ORBIT_VERSION="0.2.0"
 ORBIT_ROOT="${ORBIT_ROOT:-}"
 ORBIT_DEFAULT_BRANCH_PREFIX="ws"
 ORBIT_CMD="${0##*/}"