orbitmap 0.3.0 → 0.4.0-next.0

package/README.md

@@ -1,212 +1,443 @@
-# 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.app) 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. Start working
+npx orbitmap start
+```
+
+## 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/` to
+`.gitignore`. 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` → 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 config file, defaulting to `cloud` when absent. The auto-detect rung is what lets
+one project stay local and another stay cloud on the same machine — `init` never writes `mode` to
+the global config.
+
+### 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`. Legacy `ORBITMAP_PROJECT_ID` / `project_id` are still read as a fallback, so old configs keep working — but they are never written back.
+
+## Commands
+
+### Task Management
+
+| Command | Description |
+|---------|-------------|
+| `orbitmap tasks` | List your assigned tasks (`--status`, `--priority`, `--orbit`) |
+| `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 (`--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> <title>` | Create a subtask |
+| `orbitmap assign <id> [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> <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`
+
+`assign` auto-detects the object type from the prefix (`IS-…` → issue, `IN-…` → intent, …); pass `--type task|issue|idea|intent` for bare UUIDs.
+
+### 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`, `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` | Interactive setup — mode, then credentials or workspace (`--key`, `--area`, `--profile`, `--advanced`; `--local`, `--workspace`, `--workspace-name`, `--no-skills`) |
+| `orbitmap login` / `orbitmap logout` | Browser-based OAuth login / token revocation |
+| `orbitmap setup-agent` | Install OrbitMap instructions into your agent config |
+| `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
+
+### 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_...",
+  "area": "my-area-slug",
+  "mode": "cloud",
+  "workspace_path": "/home/me/orbits/personal"
+}
+```
+
+`mode` is `"cloud"` (the default when the key is absent, so existing configs keep working) or
+`"local"`; `workspace_path` is the default local workspace directory and is written only in local
+mode. A legacy `"project_id"` key is still honoured if `area` is absent.
+
+### Environment Variables
+
+Environment variables take precedence over the config file:
+
+| Variable | Description |
+|----------|-------------|
+| `ORBITMAP_API_KEY` | Agent API key |
+| `ORBITMAP_API_URL` | API base URL |
+| `ORBITMAP_AREA` | Area UUID or slug |
+| `ORBITMAP_MODE` | `cloud` or `local` — overrides the config `mode` |
+| `ORBITMAP_WORKSPACE` | Local workspace directory (local mode) |
+| `ORBITMAP_PROJECT_ID` | Deprecated alias for `ORBITMAP_AREA` (read-only fallback) |
+
+### Resolution Priority
+
+1. Explicit `--area` flag (area context only)
+2. Environment variables (`ORBITMAP_AREA`, then legacy `ORBITMAP_PROJECT_ID`)
+3. `.orbitmap/link.json` (`area`) found by walking up from the current directory — local mode
+4. `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
+5. Config file (`~/.orbitmap/config.json` — `area`, then legacy `project_id`). In local mode this
+   rung is ignored when it names an area the workspace does not have (the workspace's own single
+   area is used instead); an area you name explicitly always fails loudly when it does not exist
+6. Defaults (local mode: the only area in the workspace, when there is exactly one)
+
+## 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 — get it 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
+
+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. 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