orbitmap 0.3.0 → 0.4.1

package/README.md

@@ -1,212 +1,546 @@
-# OrbitMap CLI
-
-> Project management for AI coding agents — without MCP.
-
-## What is this?
-
-OrbitMap CLI gives AI agents (Gemini CLI, GPT Codex, Claude Code without MCP, etc.) access to [OrbitMap](https://orbitmap.app) project management through simple shell commands. It's the non-MCP alternative to [orbitmap-mcp](https://github.com/BTA-Systems/orbitmap-mcp).
-
-**Use cases:**
-- AI agents that can run shell commands but don't support MCP (Gemini CLI, GPT Codex CLI)
-- Environments where MCP configuration is impractical
-- Quick task management from your terminal
-
-## Quick Start
-
-```bash
-# 1. Run the setup wizard
-npx orbitmap init
-
-# 2. Enter your credentials:
-#    - API Key (from OrbitMap dashboard)
-#    - Project ID (optional — auto-detected if you have one project)
-
-# 3. Start working
-npx orbitmap start
-```
-
-## Commands
-
-### Task Management
-
-| Command | Description |
-|---------|-------------|
-| `orbitmap tasks` | List your assigned tasks |
-| `orbitmap task <id>` | Show full task details (UUID or 6-char task number) |
-| `orbitmap start [id]` | Start working on a task (auto-picks next TODO if no ID) |
-| `orbitmap status <task-id> <status>` | Update task status |
-| `orbitmap create <title>` | Create a new task (`--from-issue` to link an issue) |
-| `orbitmap subtask <parent-id> <title>` | Create a subtask |
-| `orbitmap assign <task-id> <agent-id>` | Assign an agent to a task |
-| `orbitmap get <prefixed-id>` | Show any object by prefixed ID (TS-xxx, IS-xxx, ID-xxx, VB-xxx) |
-| `orbitmap dep add <id> <target-id>` | Add a dependency between tasks |
-| `orbitmap dep remove <id> <target-id>` | Remove a dependency |
-| `orbitmap task-edit-content <id>` | Edit task title, description, or agent instructions |
-
-**Valid statuses:** `backlog`, `todo`, `in_progress`, `in_review`, `review_changes`, `done`, `blocked`
-
-### Work Logging
-
-| Command | Description |
-|---------|-------------|
-| `orbitmap log <task-id> <message>` | Log work on a task |
-
-**Options:**
-- `--type <type>` — Log type: `note` (default), `code_change`, `decision`, `blocker`
-- `--meta <json>` — JSON metadata, e.g. `'{"files":["src/app.ts"]}'`
-
-**Examples:**
-```bash
-orbitmap log abc123 "Implemented user auth endpoint" --type code_change
-orbitmap log abc123 "Using JWT over sessions for stateless auth" --type decision
-orbitmap log abc123 "Blocked on missing API credentials" --type blocker
-```
-
-### Documents
-
-| Command | Description |
-|---------|-------------|
-| `orbitmap docs` | List project documents |
-| `orbitmap doc <id-or-slug>` | Show full document content |
-| `orbitmap doc-import <title>` | Import a markdown file (`--context` to set when-to-use hint) |
-| `orbitmap doc-update <id-or-slug>` | Update a document from a file |
-| `orbitmap doc-patch <id-or-slug>` | Patch a document with operations (replace_section, append, etc.) |
-| `orbitmap doc-share <doc-id> <project-id>` | Share a document with another project |
-| `orbitmap doc-unshare <doc-id> <project-id>` | Remove document sharing |
-| `orbitmap docs pull [slug]` | Download document(s) to local cache |
-| `orbitmap docs list-cache` | Show locally cached documents |
-| `orbitmap docs clean` | Remove stale cached documents |
-
-**Examples:**
-```bash
-# List all API docs
-orbitmap docs --type api
-
-# Search documents by title
-orbitmap docs --search "auth"
-
-# View a document
-orbitmap doc api-specification
-
-# Import a new document
-orbitmap doc-import "API Spec" --type api --file ./docs/api-spec.md
-
-# Update existing document
-orbitmap doc-update api-specification --file ./docs/api-spec.md --changelog "Added auth section"
-
-# Share with another project
-orbitmap doc-share <doc-uuid> <project-uuid> --agents agent1-uuid,agent2-uuid
-```
-
-### Project & Agent Info
-
-| Command | Description |
-|---------|-------------|
-| `orbitmap context` | Show agent identity and current project |
-| `orbitmap projects` | List all your projects |
-| `orbitmap members <project-id>` | List agents and users in a project (accepts slug) |
-| `orbitmap overview [project-id]` | Project overview with task statistics (uses default project) |
-
-### Issues, Ideas & Vibes
-
-| Command | Description |
-|---------|-------------|
-| `orbitmap issues` | List open issues |
-| `orbitmap issue show <id>` | Show issue details (UUID or number) |
-| `orbitmap issue register` | Register a new issue |
-| `orbitmap issue resolve <id>` | Resolve an issue |
-| `orbitmap ideas` | List ideas |
-| `orbitmap idea add` | Add a new idea |
-| `orbitmap idea show <id>` | Show idea details (UUID or number) |
-| `orbitmap idea status <id>` | Update idea status |
-| `orbitmap vibes` | List vibes |
-| `orbitmap vibe log` | Log a new vibe |
-| `orbitmap vibe show <id>` | Show vibe details |
-| `orbitmap vibe update <id>` | Update a vibe |
-
-### Orbits
-
-| Command | Description |
-|---------|-------------|
-| `orbitmap orbit items <id-or-slug>` | List items in an orbit |
-| `orbitmap orbit attach <id-or-slug>` | Attach an object to an orbit |
-| `orbitmap orbit detach <id-or-slug>` | Detach an object from an orbit |
-
-### Delivery Status
-
-Track code delivery lifecycle on tasks:
-
-```bash
-orbitmap status abc123 done --delivery on_branch
-orbitmap status abc123 done --delivery merged
-orbitmap status abc123 done --delivery released
-```
-
-### Global Options
-
-| Option | Description |
-|--------|-------------|
-| `--json` | Output raw JSON (for scripting/piping) |
-| `--project <id>` | Override project context (UUID or slug) |
-
-## Configuration
-
-### Setup
-
-Run `npx orbitmap init` for interactive setup. Credentials are stored in `~/.orbitmap/config.json`.
-
-### Config file
-
-```json
-{
-  "api_url": "https://orbitmap.app/api/agent",
-  "api_key": "orbitmap_...",
-  "project_id": "my-project-slug"
-}
-```
-
-### Environment Variables
-
-Environment variables take precedence over the config file:
-
-| Variable | Description |
-|----------|-------------|
-| `ORBITMAP_API_KEY` | Agent API key |
-| `ORBITMAP_API_URL` | API base URL (default: `https://orbitmap.app/api/agent`) |
-| `ORBITMAP_PROJECT_ID` | Project UUID or slug |
-
-### Resolution Priority
-
-1. Environment variables
-2. Config file (`~/.orbitmap/config.json`)
-3. Defaults
-
-## Authentication
-
-OrbitMap CLI uses a single **Agent API Key** for authentication (`Authorization: Bearer` header). Each agent has its own key — get it from the OrbitMap dashboard.
-
-Optionally, set a default **Project ID** if your agent is assigned to multiple projects.
-
-## For AI Agents
-
-Run the setup wizard to teach your agent about OrbitMap:
-
-```bash
-npx orbitmap setup-agent          # auto-detects your agent
-npx orbitmap setup-agent --agent claude
-```
-
-It installs two layers, mirroring the OrbitMap MCP server:
-
-- A **thin always-on hook** (~10 lines) in your agent config (`CLAUDE.md`, `AGENTS.md`, …) so the agent always knows the project uses OrbitMap and knows the workflow skeleton.
-- The **deep, on-demand instructions** — full parity with the MCP `full` profile (all 27 tools mapped to commands). For **Claude Code** this is installed as a loaded-on-demand skill at `.claude/skills/orbitmap/SKILL.md` (zero per-turn context cost); for other agents it's inlined as a markdown fallback.
-
-See [Agent Instructions](docs/agent-instructions.md) for details.
-
-## Requirements
-
-- Node.js 18+
-
-## License
-
-MIT
+# OrbitMap CLI
+
+> Project management for AI coding agents — without MCP.
+
+## What is this?
+
+OrbitMap CLI gives AI agents (Gemini CLI, GPT Codex, Claude Code without MCP, etc.) access to [OrbitMap](https://orbitmap.ai) project management through simple shell commands. It's the non-MCP alternative to [orbitmap-mcp](https://github.com/BTA-Systems/orbitmap-mcp), and tracks the same Agent API contract (currently **schema_version 6.3.0**).
+
+**Use cases:**
+- AI agents that can run shell commands but don't support MCP (Gemini CLI, GPT Codex CLI)
+- Environments where MCP configuration is impractical
+- Quick task management from your terminal
+
+## Quick Start
+
+```bash
+# 1. Run the setup wizard — it asks where your data should live:
+#    [1] Orbitmap.ai account (cloud)  [2] Local files (no account)
+npx orbitmap init
+
+# 2. Cloud: enter your credentials
+#    - API Key (from OrbitMap dashboard)
+#    - Area ID (optional — auto-detected if you belong to a single area)
+#    Local: pick a workspace directory, a workspace name and a first area
+
+# 3. Confirm the agent skills — `init` installs them in the same run, creating
+#    CLAUDE.md / AGENTS.md if this directory has none yet. `--agent claude`
+#    picks the type without asking; `--no-skills` opts out.
+
+# 4. Start working
+npx orbitmap start
+```
+
+`init` is the whole install: config, credentials, MCP block and the agent skills. There is no
+mandatory second command.
+
+## Local mode
+
+The CLI runs in one of two modes, chosen once during `orbitmap init`:
+
+| | **Cloud mode** | **Local mode** |
+|---|---|---|
+| Storage | Orbitmap.ai workspace (Agent API) | Markdown files with YAML frontmatter on your disk |
+| Account | required | none |
+| Web UI, team, multiple agents | yes | no — solo developer |
+| Commands | all of them | all of them, minus the limitations below |
+
+Both modes speak the **same commands with the same output** — `orbitmap start`, `orbitmap log`,
+`orbitmap tasks --json` behave identically, and agent skills installed by `orbitmap init` never
+need to know which mode is active.
+
+### Set up local mode
+
+Interactive — answer `2` at the mode question, then accept or override the three defaults
+(workspace directory `./.orbitmap`, workspace name, first area):
+
+```bash
+npx orbitmap init
+```
+
+Scripted / CI:
+
+```bash
+npx orbitmap init --local \
+  --workspace ~/orbits/personal \   # where the files live (default: ./.orbitmap)
+  --workspace-name "My Orbit" \     # default: current directory name
+  --area "My App" \                 # first area (default: current directory name)
+  --no-skills                       # skip installing agent skills
+```
+
+If the workspace directory is **outside** the project, `init` writes a pointer at
+`<project>/.orbitmap/link.json` (`{"workspace": "…", "area": "…"}`) and adds
+`.orbitmap/link.json` and `.orbitmap/docs/` to `.gitignore` (not the whole `.orbitmap/`
+directory — `.orbitmap/config.json`, see [Configuration](#configuration), is meant to be
+committed). The pointer is found by walking up from the current directory, like `.git`, so
+commands work from any subdirectory. If the workspace *is* `./.orbitmap`, nothing is gitignored —
+the data is meant to be committable.
+
+Resolution order for the workspace directory: `--workspace` → `ORBITMAP_WORKSPACE` →
+`.orbitmap/link.json` → `./.orbitmap/workspace.yml` → `workspace_path` in
+`~/.orbitmap/config.json`. The mode itself is resolved per-project, first match wins: `--workspace`
+(explicit → local) → `ORBITMAP_MODE=local|cloud` → nearest `.orbitmap/config.json` `mode` field →
+auto-detect (walk up from cwd looking for `.orbitmap/workspace.yml` or `.orbitmap/link.json`, same
+as git looking for `.git` → local) → `mode` in the global config file, defaulting to `cloud` when
+absent. The auto-detect rung (and the project config rung above it) is what lets one project stay
+local and another stay cloud on the same machine — `init` never writes `mode` to the global config
+for the local path.
+
+### Where the data lives
+
+```
+<workspace-dir>/
+  workspace.yml                # workspace header, default area + entity-number counters
+  missions/MS-<num>.md
+  intents/IN-<num>.md
+  ideas/ID-<num>.md
+  documents/<slug>.md
+  issues/IS-<num>.md           # workspace-level issues (no area)
+  areas/
+    <area-slug>/
+      area.yml                 # area header (git url, default branch, …)
+      tasks/TS-<num>.md
+      issues/IS-<num>.md       # area-scoped issues
+      vibes/VB-<num>.md
+```
+
+Every entity is one Markdown file: the YAML frontmatter holds the fields, the body holds the long
+text (`## Description`, and for tasks an append-only `## Work Log`). Relations are stored as entity
+numbers and slugs, so the files stay readable and diff cleanly in git.
+
+**The CLI is the only writer.** Editing these files by hand (or letting an agent do it) bypasses
+validation and the counters — always go through `orbitmap` commands.
+
+### Current limitations
+
+Local mode is a proof of concept. Not supported yet:
+
+- **No import/export between a local workspace and the cloud** (planned next; entity-number format
+  and response shapes are already identical so the future import is a data copy).
+- **No orbits** — `orbit *` commands fail with `NOT_SUPPORTED_IN_LOCAL_MODE` and exit 1.
+- **No document section-patching, sharing or presigned uploads** — `doc-patch`, `doc-share`,
+  `doc-unshare`, `doc-visibility` fail the same way. `docs`, `doc`, `doc-import` and `doc-update`
+  work.
+- **No OAuth** (`login` / `logout`) — meaningless without a server.
+- **No human team members**: exactly one implicit user (`me`) and one implicit agent
+  (`local-agent`). `members` returns them; `assign` accepts only them.
+- **No sync or merge between machines** — you may sync the workspace directory with git yourself,
+  the CLI does not mediate conflicts.
+
+See [`docs/architecture.md`](docs/architecture.md) for the adapter split and
+[`docs/adr/0001-local-mode.md`](docs/adr/0001-local-mode.md) for why local storage exists at all.
+
+## Object model
+
+OrbitMap organises work on several levels. The CLI mirrors them 1:1:
+
+| Level | Prefix | What it is |
+|-------|--------|-----------|
+| **Workspace** | — | Top-level container that owns areas, orbits, intents and missions |
+| **Area** | — | A single product/repo/domain (formerly called *project*) — the default scope of most commands |
+| **Orbit** | — | Cross-area grouping of work (a theme, an initiative); items of any type can be attached |
+| **Intent** | `IN-` | A desired outcome at workspace level; tasks and issues can be linked to it |
+| **Mission** | `MS-` | A time-boxed workspace focus; only one mission can be `active` |
+| **Task** | `TS-` | The unit of work agents execute |
+| **Issue** | `IS-` | A reported problem |
+| **Idea** | `ID-` | A future possibility |
+| **Vibe** | `VB-` | Ad-hoc work context outside the task lifecycle |
+
+> **Project → Area rename.** What used to be called a *project* is now an **area**. The global flag is `--area`, the env var is `ORBITMAP_AREA`, and the config key is `area`. The legacy `ORBITMAP_PROJECT_ID` env var and `project_id` config key were read-only fallbacks for one release and were removed by [ADR 0002](docs/adr/0002-project-scoped-config.md) — they had the same cross-project leak as the machine-wide `area` they aliased. Set `area` in your project's `.orbitmap/config.json` instead.
+
+## Commands
+
+### Task Management
+
+| Command | Description |
+|---------|-------------|
+| `orbitmap tasks` | List your assigned tasks (`--status`, `--priority`, `--orbit`) |
+| `orbitmap task <id-or-number>` | Show full task details |
+| `orbitmap start [id-or-number]` | Start working on a task (auto-picks next TODO if no ID) |
+| `orbitmap status <id-or-number> <status>` | Update task status (`--force` to move a parent to `done` with unfinished subtasks) |
+| `orbitmap create <title>` | Create a new task (`--from-issue`, `--intent`, `--orbit`) |
+| `orbitmap subtask <parent-id-or-number> <title>` | Create a subtask |
+| `orbitmap assign <id-or-number> [agent-id]` | Assign a task, issue, idea, or intent to an agent or user |
+| `orbitmap get <prefixed-id>` | Show any object by prefixed ID (TS-, IS-, ID-, VB-, IN-, MS-) |
+| `orbitmap dep add <id-or-number> <target-id-or-number>` | Add a dependency between tasks |
+| `orbitmap dep remove <id-or-number> <target-id-or-number>` | Remove a dependency |
+| `orbitmap task-edit-content <id-or-number>` | Edit task title, description, or agent instructions |
+
+**Valid statuses:** `backlog`, `todo`, `in_progress`, `in_review`, `review_changes`, `done`, `blocked`
+
+### Referring to objects: `<id-or-number>`
+
+Every command that takes an object reference accepts all three forms interchangeably:
+
+- the prefixed display ID the CLI prints — `TS-uw9yh5`, `IS-4k2p9q`, `IN-6htga8`
+- the bare 6-character code — `uw9yh5`
+- the UUID
+
+You can therefore paste any identifier straight out of `orbitmap tasks`, `orbitmap context` or
+the message `orbitmap create` prints. This was previously true of `orbitmap task` and
+`orbitmap get` only: `status`, `log`, `subtask`, `start`, `assign`, `task-edit-content` and
+`dep add`/`dep remove` rejected prefixed IDs with a 404, including identifiers the CLI had
+just printed itself.
+
+The Agent API resolves a prefixed ID inline for issues, ideas, intents and missions, but not
+for tasks — a task reference that is not a UUID needs a `/tasks/by-number/{n}` lookup first.
+The CLI now does that once, in the adapter layer, so every task command behaves the same and a
+UUID still costs exactly one request. See `src/id-resolve.ts`.
+
+`assign` auto-detects the object type from the prefix (`IS-…` → issue, `IN-…` → intent, …);
+pass `--type task|issue|idea|intent` for bare UUIDs and bare codes.
+
+### Work Logging
+
+| Command | Description |
+|---------|-------------|
+| `orbitmap log <id-or-number> <message>` | Log work on a task |
+
+**Options:**
+- `--type <type>` — Log type: `note` (default), `code_change`, `decision`, `blocker`, `discovery`, `exploration`, `fix`
+- `--meta <json>` — JSON metadata, e.g. `'{"files":["src/app.ts"]}'`
+
+**Examples:**
+```bash
+orbitmap log abc123 "Implemented user auth endpoint" --type code_change
+orbitmap log abc123 "Using JWT over sessions for stateless auth" --type decision
+orbitmap log abc123 "Blocked on missing API credentials" --type blocker
+```
+
+### Documents
+
+| Command | Description |
+|---------|-------------|
+| `orbitmap docs` | List area documents |
+| `orbitmap doc <id-or-slug>` | Show document (TOC by default, `--full`, `--section`) |
+| `orbitmap doc-import <title>` | Import a markdown file (`--context` to set when-to-use hint) |
+| `orbitmap doc-update <id-or-slug>` | Replace a document from a file |
+| `orbitmap doc-patch <id-or-slug>` | Patch a document with section operations |
+| `orbitmap doc-share <doc-id> <area-id>` | Share a document with another area |
+| `orbitmap doc-unshare <doc-id> <area-id>` | Remove document sharing |
+| `orbitmap doc-visibility <doc-id> <area-id>` | Restrict a share to specific agents (or allow all) |
+| `orbitmap docs pull [slug]` | Download document(s) to local cache |
+| `orbitmap docs list-cache` | Show locally cached documents |
+| `orbitmap docs clean` | Remove stale cached documents |
+
+**Examples:**
+```bash
+# List all API docs
+orbitmap docs --type api
+
+# Search documents by title
+orbitmap docs --search "auth"
+
+# Read cheaply: TOC → one section → full content
+orbitmap doc api-specification
+orbitmap doc api-specification --section "## Authentication"
+orbitmap doc api-specification --full
+
+# Import a new document
+orbitmap doc-import "API Spec" --type api --file ./docs/api-spec.md
+
+# Update existing document
+orbitmap doc-update api-specification --file ./docs/api-spec.md --changelog "Added auth section"
+
+# Patch a single section (optimistic locking via --base-version)
+orbitmap doc-patch api-specification --base-version 7 \
+  --replace-section "## Authentication" --content "Bearer tokens only." \
+  --changelog "Reworded auth"
+
+# Share with another area
+orbitmap doc-share <doc-uuid> <area-uuid> --agents agent1-uuid,agent2-uuid
+```
+
+### Area & Agent Info
+
+| Command | Description |
+|---------|-------------|
+| `orbitmap context` | Show agent identity and current area |
+| `orbitmap areas` | List all areas assigned to this agent |
+| `orbitmap create-area <name>` | Create a new area (`--desc`, `--slug`, `--workspace-id`) |
+| `orbitmap members <area-id>` | List agents and users in an area (accepts slug) |
+| `orbitmap overview [area-id]` | Area overview with task statistics (uses default area) |
+
+### Issues, Ideas & Vibes
+
+| Command | Description |
+|---------|-------------|
+| `orbitmap issues` | List open issues |
+| `orbitmap issue show <id>` | Show issue details (UUID or number) |
+| `orbitmap issue register` | Register a new issue (`--intent` to link it to an intent) |
+| `orbitmap issue status <id> <status>` | Update issue status |
+| `orbitmap issue resolve <id>` | Resolve an issue |
+| `orbitmap ideas` | List ideas |
+| `orbitmap idea add` | Add a new idea |
+| `orbitmap idea show <id>` | Show idea details (UUID or number) |
+| `orbitmap idea status <id>` | Update idea status |
+| `orbitmap vibes` | List vibes |
+| `orbitmap vibe log` | Log a new vibe |
+| `orbitmap vibe show <id>` | Show vibe details |
+| `orbitmap vibe update <id>` | Update a vibe |
+
+### Intents
+
+Workspace-level desired outcomes. Tasks and issues hang off an intent; an intent can sit in an orbit.
+
+| Command | Description |
+|---------|-------------|
+| `orbitmap intents` | List intents (shortcut for `intent list`) |
+| `orbitmap intent show <id-or-number>` | Show an intent (UUID or `IN-xxxxxx`) |
+| `orbitmap intent create <title>` | Create an intent (`--outcome`, `--status`, `--orbit`) |
+| `orbitmap intent update <id>` | Update title, outcome, or status |
+| `orbitmap intent link <id> --type task\|issue --id <uuid>` | Link a task or issue |
+| `orbitmap intent unlink <id> --type task\|issue --id <uuid>` | Unlink a task or issue |
+| `orbitmap intent orbit <id> [orbit-id]` | Set the intent's orbit (`--clear` to remove) |
+
+**Statuses:** `new`, `design`, `plan`, `build`, `done`, `cancelled`
+
+```bash
+orbitmap intent create "Cut onboarding time in half" \
+  --outcome "New users reach first value in under 5 minutes" \
+  --status design --orbit growth-q3
+
+orbitmap intent link IN-a1b2c3 --type task --id <task-uuid>
+```
+
+`intent create --orbit` is create-then-attach. If the attach step fails the intent is still created — the CLI reports the failure and does not retry.
+
+### Missions
+
+Time-boxed workspace focus. Only one mission can be `active` at a time.
+
+| Command | Description |
+|---------|-------------|
+| `orbitmap missions` | List missions (shortcut for `mission list`) |
+| `orbitmap mission show <id-or-number>` | Show a mission (UUID or `MS-xxxxxx`) |
+| `orbitmap mission create <title>` | Create a mission (`--desc`, `--outcome`, `--end-date`) |
+| `orbitmap mission update <id>` | Update title, description, outcome, or end date |
+| `orbitmap mission status <id> <status>` | Set lifecycle status (`--move-to` to relocate unfinished work) |
+| `orbitmap mission link <id> --type <t> --id <uuid>` | Link a task, issue, idea, or intent |
+| `orbitmap mission unlink <id> --type <t> --id <uuid>` | Unlink a directly-linked item |
+
+**Statuses:** created as `new`; then `active`, `completed`, `cancelled`.
+
+```bash
+orbitmap mission create "Ship v2 beta" --outcome "Beta live for 50 customers" --end-date 2026-09-30
+orbitmap mission status MS-a1b2c3 active
+orbitmap mission status MS-a1b2c3 completed --move-to MS-d4e5f6
+```
+
+Linking a task or issue to a mission clears its `intent_id` — an item belongs either to an intent or directly to a mission.
+
+### Orbits
+
+| Command | Description |
+|---------|-------------|
+| `orbitmap orbit list` | List orbits (workspace-scoped from the area context, `--workspace`) |
+| `orbitmap orbit show <id-or-slug>` | Show orbit details (areas, task counts, resources) |
+| `orbitmap orbit create <name>` | Create an orbit (`--desc`, `--color`, `--areas`) |
+| `orbitmap orbit update <id-or-slug>` | Update name, description, status, or color |
+| `orbitmap orbit items <id-or-slug>` | List items in an orbit (`--type`) |
+| `orbitmap orbit attach <id-or-slug>` | Attach an object to an orbit |
+| `orbitmap orbit detach <id-or-slug>` | Detach an object from an orbit |
+| `orbitmap orbit area link <id-or-slug> <area-id>` | Link an area to an orbit |
+| `orbitmap orbit area unlink <id-or-slug> <area-id>` | Unlink an area from an orbit |
+| `orbitmap orbit dep <id-or-slug> <target-orbit-id>` | Add an orbit-to-orbit dependency |
+
+**Item types:** `task`, `issue`, `vibe`, `idea`, `document`
+**Orbit statuses:** `active`, `completed`, `archived`
+
+```bash
+orbitmap orbit create "Growth Q3" --color "#5B8DEF" --areas <area-uuid>,<area-uuid>
+orbitmap orbit attach growth-q3 --type task --id <task-uuid> --note "core flow"
+orbitmap orbit items growth-q3 --type task
+```
+
+There is no orbit delete and no dependency remove in the API — archive via `orbit update --status archived`.
+
+### Delivery Status
+
+Track code delivery lifecycle on tasks:
+
+```bash
+orbitmap status abc123 done --delivery on_branch
+orbitmap status abc123 done --delivery merged
+orbitmap status abc123 done --delivery released
+```
+
+### Setup helpers
+
+| Command | Description |
+|---------|-------------|
+| `orbitmap init` | Full setup — mode, then credentials or workspace, then the agent skills (`--key`, `--area`, `--profile`, `--advanced`, `--global`; `--local`, `--workspace`, `--workspace-name`; `--agent <type>`, `--no-skills`) |
+| `orbitmap login` / `orbitmap logout` | Browser-based OAuth login / token revocation |
+| `orbitmap setup-agent` | Refresh the installed instructions (after a CLI upgrade) or add another agent type — `init` installs them once already |
+| `orbitmap setup-mcp` | Write/merge an `orbitmap` entry into `.mcp.json` (no API calls) |
+
+### Global Options
+
+| Option | Description |
+|--------|-------------|
+| `--json` | Output raw JSON (for scripting/piping) |
+| `--area <id>` | Override area context (UUID or slug) |
+| `--workspace <path>` | Override the local workspace directory (local mode only) |
+
+## Configuration
+
+See `docs/adr/0002-project-scoped-config.md` for the full design and rationale (this
+replaced a single global config file — breaking for scripted `init` callers that relied on
+that, see the ADR's Consequences section).
+
+### Setup
+
+Run `npx orbitmap init` for interactive setup. For cloud mode, it writes
+`<project>/.orbitmap/config.json` (committable, no secrets) by default; pass `--global` to
+write `~/.orbitmap/config.json` instead (a machine-wide default, like `git config --global`).
+The API key always goes to `~/.orbitmap/credentials.json`, under a named **agent profile** —
+never into a config file, either way.
+
+### Project config file — `<project>/.orbitmap/config.json`
+
+```json
+{
+  "schema_version": 1,
+  "mode": "cloud",
+  "agent": "orbitmap-app-bot",
+  "area": "my-area-slug"
+}
+```
+
+`mode` is `"cloud"` (the default when the key is absent) or `"local"`. `agent` names a
+profile in `~/.orbitmap/credentials.json` — the project says *which* agent to use, the
+credentials file (below) holds *that agent's* key. This file is meant to be committed: a
+team shares the `agent` name and `area` pinning through version control, and each member's
+own copy of `credentials.json` supplies their own agent's key.
+
+### Global config file — `~/.orbitmap/config.json`
+
+Same shape, used as the fallback for any field a project's own config doesn't set, and as
+the only place `workspace_path` (the default local workspace directory) is read from. Only
+written by `orbitmap init --global`, or left over from before ADR 0002 — in which case a
+lingering `area` is still honoured but prints a one-time deprecation warning telling you to
+move it into a project's own `.orbitmap/config.json`.
+
+### Credentials file — `~/.orbitmap/credentials.json`
+
+Never committed, never leaves the machine. Also holds the OAuth session used by
+`orbitmap login`/`orbitmap logout` (unrelated top-level fields, unchanged shape):
+
+```json
+{
+  "agents": {
+    "orbitmap-app-bot": { "api_key": "orbitmap_..." },
+    "orbitmap-cli-bot": { "api_key": "orbitmap_..." }
+  }
+}
+```
+
+An agent name that resolves to nothing here (nothing named `agent` anywhere, including the
+global config) falls back to the `"default"` profile — which is also where a pre-ADR-0002
+global `api_key` is migrated to. That migration runs inside `loadConfig()`, i.e. on the
+first command of any kind after upgrading, not only on `orbitmap init`; it rewrites
+`~/.orbitmap/config.json` without the key (preserving every other key in the file) and
+prints a one-time notice. If the write fails — read-only `$HOME`, a `credentials.json` owned
+by another user — it says so and keeps using the key from the config file, so the CLI never
+locks you out over a key that is right there on disk.
+
+`~/.orbitmap` itself can be relocated with `ORBITMAP_CONFIG_HOME` or the standard
+`XDG_CONFIG_HOME` (as `$XDG_CONFIG_HOME/orbitmap`); reads fall back to the legacy
+`~/.orbitmap` location when the new one has nothing yet.
+
+### Environment Variables
+
+Environment variables take precedence over every config file:
+
+| Variable | Description |
+|----------|-------------|
+| `ORBITMAP_API_KEY` | Agent API key (bypasses agent-profile lookup entirely) |
+| `ORBITMAP_API_URL` | API base URL — the only remaining override; there is no config-file equivalent any more (see the ADR) |
+| `ORBITMAP_AGENT` | Name of the agent profile in `credentials.json` to use |
+| `ORBITMAP_AREA` | Area UUID or slug |
+| `ORBITMAP_MODE` | `cloud` or `local` — overrides the config `mode` |
+| `ORBITMAP_WORKSPACE` | Local workspace directory (local mode) |
+| `ORBITMAP_CONFIG_HOME` / `XDG_CONFIG_HOME` | Relocate `~/.orbitmap` |
+
+### Resolution Priority
+
+**Area** (first match wins):
+1. Explicit `--area` flag
+2. `ORBITMAP_AREA` env
+3. `.orbitmap/link.json` (`area`) found by walking up from the current directory — local mode
+4. Nearest `.orbitmap/config.json` **that sets `area`**, found the same way. Resolution is
+   per field: a `packages/api/.orbitmap/config.json` that sets only `agent` does not hide an
+   `area` pinned by the repository root
+5. `default_area` in the workspace's `workspace.yml` — local mode; written by `orbitmap init` for
+   the first area, so a workspace outranks the machine-wide default of an unrelated project
+6. Global config `area` (deprecated — prints a warning when hit)
+7. Defaults (local mode: the only area in the workspace, when there is exactly one)
+
+**Agent / API key** (first match wins):
+1. `ORBITMAP_API_KEY` env — used directly, no profile lookup
+2. Otherwise resolve an agent name (`ORBITMAP_AGENT` env → nearest `.orbitmap/config.json`
+   that sets `agent` → global config `agent` → `"default"`) and look up its key in
+   `credentials.json`
+
+**Mode** (first match wins): `--workspace` (explicit → local) → `ORBITMAP_MODE` → nearest
+`.orbitmap/config.json` that sets `mode` → local auto-detect (`.orbitmap/workspace.yml` or
+`.orbitmap/link.json` found by walking up) → `mode` in the global config, defaulting to
+`cloud`.
+
+**Workspace directory** (local mode, first match wins): `--workspace` → `ORBITMAP_WORKSPACE`
+→ `.orbitmap/link.json` (`workspace`) → nearest `.orbitmap/workspace.yml` → the `.orbitmap/`
+directory of the nearest config that sets `mode: "local"`, when it is itself a workspace →
+`workspace_path` in the global config, **which must be an absolute path** (a relative one
+would mean a different directory in every project, so it is ignored with a warning).
+
+## Authentication
+
+In cloud mode, OrbitMap CLI uses a single **Agent API Key** for authentication (`Authorization: Bearer` header). Local mode has no authentication at all — access to the workspace directory is the only credential. Each agent has its own key, named by an agent profile in `~/.orbitmap/credentials.json` — get the key itself from the OrbitMap dashboard. Area context travels in the `X-Orbitmap-Area` header.
+
+Optionally, set a default **Area ID** if your agent is assigned to multiple areas.
+
+## Error handling
+
+API errors are printed as `Error [CODE] (status): message`. Alongside the regular envelope, the client normalises the flat billing/usage shape returned by 402/429 responses into:
+
+| Code | When |
+|------|------|
+| `PAYMENT_REQUIRED` | HTTP 402 — billing action needed |
+| `RATE_LIMITED` | HTTP 429 — too many requests |
+| `USAGE_LIMIT` | Other flat-error responses |
+| `TIMEOUT` | No response within 30s |
+
+## For AI Agents
+
+`orbitmap init` already teaches your agent about OrbitMap — the skills are its last step, in
+both cloud and local mode, and it creates the agent config file when the directory has none:
+
+```bash
+npx orbitmap init --agent claude   # or let it detect / ask; --no-skills opts out
+```
+
+`setup-agent` does the same install on its own, for the two cases `init` does not cover:
+refreshing the content after upgrading the CLI, and adding a second agent type to a directory
+that is already set up.
+
+```bash
+npx orbitmap setup-agent          # auto-detects your agent
+npx orbitmap setup-agent --agent claude
+```
+
+Either way it installs two layers, mirroring the OrbitMap MCP server:
+
+- A **thin always-on hook** (~10 lines) in your agent config (`CLAUDE.md`, `AGENTS.md`, …) so the agent always knows the project uses OrbitMap and knows the workflow skeleton.
+- The **deep, on-demand instructions** — full parity with the MCP `full` profile. For **Claude Code** these are installed as loaded-on-demand skills (`.claude/skills/orbitmap`, `orbitmap-working`, `orbitmap-planning`, `orbitmap-docs`, zero per-turn context cost); for other agents they're inlined as a markdown fallback.
+
+The instructions are mode-agnostic: they reference CLI commands only, so the same skills drive an agent whether the data goes to the cloud or to local files.
+
+See [Agent Instructions](docs/agent-instructions.md) for details.
+
+## Requirements
+
+- Node.js 18+
+
+## License
+
+MIT