orbitmap 0.4.2 → 0.4.4

package/README.md

@@ -94,7 +94,8 @@ for the local path.
   missions/MS-<num>.md
   intents/IN-<num>.md
   ideas/ID-<num>.md
-  documents/<slug>.md
+  docs/<slug>.md               # one copy of each document, same path and format as the
+                               # cloud doc cache (`<project>/.orbitmap/docs/`)
   issues/IS-<num>.md           # workspace-level issues (no area)
   areas/
     <area-slug>/
@@ -194,10 +195,15 @@ pass `--type task|issue|idea|intent` for bare UUIDs and bare codes.
 
 | Command | Description |
 |---------|-------------|
-| `orbitmap log <id-or-number> <message>` | Log work on a task |
+| `orbitmap log <id-or-number> <message>` | Log work on a task, intent or mission |
+
+The target follows from the reference: `TS-…` writes against the task, `IN-…` against the
+intent, `MS-…` against the mission. A bare UUID or bare code means a **task** unless
+`--target` says otherwise.
 
 **Options:**
-- `--type <type>` — Log type: `note` (default), `code_change`, `decision`, `blocker`, `discovery`, `exploration`, `fix`
+- `--type <type>` — Log type: `note` (default), `code_change`, `decision`, `blocker`. For `discovery`, `exploration` and `fix` use `orbitmap vibe log` — those are vibe types, not work-log types. `status_change` is written by the server on a status change and cannot be authored by a client.
+- `--target <kind>` — Which object a bare UUID names: `task` (default), `intent`, `mission`
 - `--meta <json>` — JSON metadata, e.g. `'{"files":["src/app.ts"]}'`
 
 **Examples:**
@@ -205,8 +211,25 @@ pass `--type task|issue|idea|intent` for bare UUIDs and bare codes.
 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
+orbitmap log IN-a1b2c3 "Chose 3 FKs + a CHECK over a polymorphic target" --type decision
+orbitmap log MS-a1b2c3 "Mission scope trimmed to the two gating intents" --type note
 ```
 
+#### Work log entries on a status change
+
+`intent update`, `mission update` and `mission status` take a **repeatable** `--log
+<type>:<content>`, sent as one batch with the update. The content is split on the FIRST
+colon only, so it may contain colons of its own.
+
+```bash
+orbitmap intent update IN-a1b2c3 --status plan \
+  --log decision:"chose 3 FKs + CHECK" \
+  --log note:"resume: CLI next"
+```
+
+The API **requires at least one entry when the status changes** and writes nothing at all
+when there is none — so a rejected transition is re-run with `--log`, not retried as-is.
+
 ### Documents
 
 | Command | Description |
@@ -287,8 +310,8 @@ Workspace-level desired outcomes. Tasks and issues hang off an intent; an intent
 |---------|-------------|
 | `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 create <title>` | Create an intent (`--outcome`, `--design`, `--plan`, `--status`, `--orbit`) |
+| `orbitmap intent update <id>` | Update title, outcome, design, plan, or status (`--log <type>:<content>`, repeatable) |
 | `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) |
@@ -298,9 +321,16 @@ Workspace-level desired outcomes. Tasks and issues hang off an intent; an intent
 ```bash
 orbitmap intent create "Cut onboarding time in half" \
   --outcome "New users reach first value in under 5 minutes" \
+  --design "Two-step wizard replacing the current five-step form." \
+  --plan "Phase 1: wizard skeleton. Phase 2: inline validation." \
   --status design --orbit growth-q3
 
 orbitmap intent link IN-a1b2c3 --type task --id <task-uuid>
+
+# A status change carries its reason — the API rejects it (422) without at least one entry.
+orbitmap intent update IN-a1b2c3 --status plan \
+  --log decision:"chose 3 FKs + CHECK" \
+  --log note:"resume: CLI next"
 ```
 
 `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.
@@ -314,8 +344,8 @@ Time-boxed workspace focus. Only one mission can be `active` at a time.
 | `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 update <id>` | Update title, description, outcome, or end date (`--log <type>:<content>`, repeatable) |
+| `orbitmap mission status <id> <status>` | Set lifecycle status (`--move-to` to relocate unfinished work; `--log` required by the API) |
 | `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 |
 
@@ -369,7 +399,7 @@ orbitmap status abc123 done --delivery released
 
 | 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 init` | Full setup — mode, then the workspace + its area directories (cloud) or a local workspace, then `.mcp.json` and the agent skills (`--key`, `--workspace-id`, `--area`, `--profile`, `--allow-nested`, `--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) |
@@ -390,11 +420,15 @@ 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.
+Run `npx orbitmap init` for interactive setup. Cloud setup is **workspace-first**: the key is
+validated with `GET /areas`, you pick the workspace (`--workspace-id` in a script), and `init`
+works out which directory holds which area — by directory name, by the `origin` git remote
+matched against the area's repository URL, by the slugified name, or by asking. It writes
+`<root>/.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. Re-running `init` merges, so running it inside a newly cloned area
+adds that area to the workspace map that already exists above it.
 
 ### Project config file — `<project>/.orbitmap/config.json`
 
@@ -403,15 +437,22 @@ never into a config file, either way.
   "schema_version": 1,
   "mode": "cloud",
   "agent": "orbitmap-app-bot",
-  "area": "my-area-slug"
+  "workspace": "my-workspace",
+  "areas": { "orbitmap-cli": "orbitmap-cli", "packages/api": "api" }
 }
 ```
 
 `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.
+credentials file (below) holds *that agent's* key. `workspace` is a workspace slug or UUID,
+never a path. `areas` maps directories (relative to this file's parent; `"."` is that
+directory) to area slugs, which is how one root can hold several areas; each mapped
+subdirectory also gets a marker config of its own holding nothing but `{"area": "<slug>"}`.
+The older single `area` field is still read for back-compat. This file is meant to be
+committed: a team shares the workspace, the `agent` name and the area layout through version
+control, and each member's own copy of `credentials.json` supplies their own agent's key.
+Areas living **outside** the tree cannot be expressed portably, so they go to the gitignored
+`<root>/.orbitmap/link.json` instead (`"areas": { "<slug>": "/abs/path" }`).
 
 ### Global config file — `~/.orbitmap/config.json`
 
@@ -528,13 +569,66 @@ npx orbitmap setup-agent          # auto-detects your agent
 npx orbitmap setup-agent --agent claude
 ```
 
+### Where it installs: `--scope user` (global) vs `--scope project`
+
+Run interactively, both commands **ask** where the skills should go — global (your home directory)
+or project (this directory only) — right after the agent-type question. Global is recommended and
+is what Enter picks; `--scope` skips the question; a scripted run takes global without prompting
+and says so in its output.
+
+Global (user) scope means `~/.claude/skills/` and `~/.claude/CLAUDE.md`
+for Claude Code, `~/.gemini/GEMINI.md` and `~/.codex/AGENTS.md` for Gemini and Codex. Agent skills
+do **not** traverse directories: a project-level `.claude/skills/` is invisible to a session
+started in a sibling or child repository, while `CLAUDE.md` *is* inherited downwards. A user-scope
+install is the only one that is consistent everywhere — and it matters now that one workspace
+routinely spans several area directories, where a single project install would cover just one.
+
+A user-scope install writes **nothing** into your project directory.
+
+```bash
+npx orbitmap setup-agent --scope project   # this directory only (the old behaviour)
+npx orbitmap init --agent claude --scope project
+```
+
+At project scope the hook says so explicitly, so an agent that inherits `CLAUDE.md` from a parent
+directory but cannot load the skills knows why, and knows to re-run with `--scope user`.
+
+**Upgrading from an older setup?** If you already have skills in `./.claude/skills/`, that project
+copy silently wins in this directory. A user-scope install detects it and names the paths; it
+offers to clean up when run interactively, and otherwise tells you to run:
+
+```bash
+npx orbitmap setup-agent --agent claude --scope user --clean-project
+```
+
+Cleanup removes only the six OrbitMap skill directories and OrbitMap's own marker block — never
+your own skills, never unrelated `CLAUDE.md` content, never a whole `.claude` directory.
+
 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 **deep, on-demand instructions** — full parity with the MCP `full` profile (plus `orbitmap-brainstorm` and `orbitmap-design`, CLI-native, no MCP counterpart). For **Claude Code** these are installed as loaded-on-demand skills (`orbitmap`, `orbitmap-execute`, `orbitmap-plan`, `orbitmap-brainstorm`, `orbitmap-design`, `orbitmap-docs`, zero per-turn context cost) under `~/.claude/skills/` (or `./.claude/skills/` at project scope); for other agents they're inlined as a markdown fallback.
+
+A skill is not always a single file: `orbitmap-execute` ships `SKILL.md` **plus**
+`references/worker-contract.md` (the rules a dispatched worker subagent follows). `init` and
+`setup-agent` install every file a skill carries, and refresh them all on a re-run.
 
 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.
 
+### Executing work: two flows
+
+The installed `orbitmap-execute` skill covers two ways of working, chosen by what you ask for:
+
+- **"work on TS-x"** runs a single tracked task — start or resume it, implement, log, and
+  finish with the correct status (`in_review` by default, so a human verifies before closing).
+- **"execute IN-x"** delivers a **whole planned intent** in the background: tasks are built by
+  parallel workers in dependency-ordered waves, each task gated by its own tests, then the
+  intent-level test and an impact pass diffed against a test baseline captured before the run,
+  with a goal-based fix loop (no retry cap) until the gates are green. A stuck task ends
+  `blocked` with a logged blocker while the rest of the intent completes. The run ends with
+  every completed task `in_review` on an `intent/<number>-<slug>` branch — **merging is left
+  to you**: the run never merges and never pushes to the default branch.
+
 See [Agent Instructions](docs/agent-instructions.md) for details.
 
 ## Requirements

package/dist/adapters/cloud.d.ts

@@ -1,17 +1,40 @@
 import { type OrbitMapConfig } from '../config.js';
+import type { WorkLogEntry } from '../work-log.js';
 import type { WorkspaceAdapter } from './types.js';
 export declare class CloudAdapter implements WorkspaceAdapter {
     private readonly apiKey;
     private readonly baseUrl;
     private readonly area?;
+    /**
+     * Workspace **identity** (slug or uuid, never a path) from the separate workspace ladder
+     * (`--workspace-id` → `ORBITMAP_WORKSPACE_ID` → project config `workspace` → global config
+     * `workspace`; see `resolveWorkspaceId`). Independent of {@link CloudAdapter.area}: either,
+     * both or neither may be set.
+     */
+    private readonly workspace?;
     /**
      * Task reference → uuid, for the lifetime of this adapter. A command that touches the same
      * task twice (`dep add TS-a TS-b` resolves two, `status` then reads back) pays for one
      * `/tasks/by-number/{n}` lookup per distinct reference, not per call site.
      */
     private readonly taskIdCache;
-    constructor(apiKey: string, area?: string, apiUrl?: string);
+    constructor(apiKey: string, area?: string, apiUrl?: string, workspace?: string);
     private request;
+    /**
+     * Add the client half of the story to the workspace-context errors the server can raise.
+     * The API knows what it received; only the CLI knows what it *sent* and which knobs could
+     * change that, and a bare "workspace context is required" is unactionable without it.
+     * Every other error is returned untouched.
+     *
+     * `AREA_CONTEXT_REQUIRED` is here too (TS-jt6q36 follow-up). The CLI raises that code
+     * itself — with the areas of the current workspace spelled out — but the *server* raises
+     * it as well, in HTTP terms ("set the X-Orbitmap-Area header. Call GET /api/agent/areas"),
+     * and that text used to reach the terminal verbatim: identical situation, two different
+     * answers depending on which side noticed first. The client-side advice is now attached to
+     * both, and the server's own sentence is kept (parenthesised) rather than dropped, because
+     * it is the only part that says what the API actually objected to.
+     */
+    private explainContextError;
     getContext(areaId?: string): Promise<unknown>;
     /**
      * The area this client was constructed with (`--area` → `ORBITMAP_AREA` →
@@ -20,6 +43,12 @@ export declare class CloudAdapter implements WorkspaceAdapter {
      * `workspace-resolve.ts`, applied by `createClient`). No request is made.
      */
     getDefaultArea(): Promise<string | undefined>;
+    /**
+     * The workspace identity this client sends as `X-Orbitmap-Workspace`, or `undefined` when
+     * none resolved (in which case the server derives one from the area or auto-detects it).
+     * No request is made.
+     */
+    getWorkspaceId(): string | undefined;
     getTasks(options?: {
         status?: string;
         priority?: string;
@@ -78,6 +107,8 @@ export declare class CloudAdapter implements WorkspaceAdapter {
     }): Promise<unknown>;
     removeTaskDependency(taskId: string, targetTaskId: string, type?: string): Promise<unknown>;
     logWork(taskId: string, type: string, content: string, metadata?: Record<string, unknown>): Promise<unknown>;
+    logIntentWork(idOrNumber: string, type: string, content: string, metadata?: Record<string, unknown>): Promise<unknown>;
+    logMissionWork(idOrNumber: string, type: string, content: string, metadata?: Record<string, unknown>): Promise<unknown>;
     getDocuments(options?: {
         type?: string;
         search?: string;
@@ -192,28 +223,21 @@ export declare class CloudAdapter implements WorkspaceAdapter {
         severity?: string;
         limit?: string;
     }): Promise<unknown>;
+    /**
+     * `GET /issues/{id_or_number}` — the single issue-read route. It accepts a uuid, a bare
+     * six-char code or the prefixed `IS-xxxxxx` form; the server strips the prefix and resolves
+     * the number workspace-scoped. There is no `/issues/by-number/{n}` route — never add one.
+     */
     getIssue(idOrNumber: string): Promise<unknown>;
-    getIssueByNumber(issueNumber: string): Promise<unknown>;
-    resolveIssueByNumber(issueNumber: string, data: {
-        status: string;
-        resolution?: string;
-        resolved_by_task_id?: string;
-    }): Promise<unknown>;
-    resolveIssue(idOrNumber: string, data: {
-        status: string;
-        resolution?: string;
-        resolved_by_task_id?: string;
-    }): Promise<unknown>;
+    /**
+     * `PATCH /issues/{id_or_number}/status` — the only issue-write route besides `/link` and
+     * `/assign`. `issue resolve` rides on it too: the API has no `/issues/{id}/resolve`.
+     */
     updateIssueStatus(idOrNumber: string, data: {
         status: string;
         resolution?: string;
         resolved_task_id?: string;
     }): Promise<unknown>;
-    updateIssueStatusByNumber(issueNumber: string, data: {
-        status: string;
-        resolution?: string;
-        resolved_task_id?: string;
-    }): Promise<unknown>;
     logVibe(data: {
         content: string;
         type: string;
@@ -237,20 +261,21 @@ export declare class CloudAdapter implements WorkspaceAdapter {
         priority?: string;
         limit?: string;
     }): Promise<unknown>;
+    /**
+     * `GET /ideas/{id_or_number}` — accepts a uuid, a bare code or `ID-xxxxxx`; the server
+     * strips the prefix and resolves the number. There is no `/ideas/by-number/{n}` route.
+     */
     getIdea(idOrNumber: string): Promise<unknown>;
-    getIdeaByNumber(ideaNumber: string): Promise<unknown>;
     createIdea(data: {
         content: string;
         title?: string;
         priority?: string;
         metadata?: Record<string, unknown>;
     }): Promise<unknown>;
+    /** `PATCH /ideas/{id_or_number}/status`. */
     updateIdeaStatus(idOrNumber: string, data: {
         status: string;
     }): Promise<unknown>;
-    updateIdeaStatusByNumber(ideaNumber: string, data: {
-        status: string;
-    }): Promise<unknown>;
     listOrbits(options?: {
         areaId?: string;
         workspaceId?: string;
@@ -294,13 +319,18 @@ export declare class CloudAdapter implements WorkspaceAdapter {
     createIntent(data: {
         name: string;
         outcome?: string;
+        design?: string;
+        plan?: string;
         status?: string;
         area_id?: string;
     }): Promise<unknown>;
     updateIntent(idOrNumber: string, data: {
         name?: string;
         outcome?: string;
+        design?: string;
+        plan?: string;
         status?: string;
+        logs?: WorkLogEntry[];
     }): Promise<unknown>;
     linkIntentItem(idOrNumber: string, data: {
         item_type: string;
@@ -328,10 +358,12 @@ export declare class CloudAdapter implements WorkspaceAdapter {
         description?: string;
         outcome?: string;
         end_date?: string;
+        logs?: WorkLogEntry[];
     }): Promise<unknown>;
     setMissionStatus(idOrNumber: string, data: {
         status: string;
         move_target_mission_id?: string;
+        logs?: WorkLogEntry[];
     }): Promise<unknown>;
     linkMissionItem(idOrNumber: string, data: {
         item_type: string;
@@ -353,6 +385,12 @@ export interface CreateClientOptions {
      * once per command instead of twice.
      */
     area?: string;
+    /**
+     * Workspace identity already produced by the workspace ladder (`resolveWorkspaceId`, via
+     * `resolveWorkspaceContext`). Same reasoning as {@link CreateClientOptions.area}: pass it
+     * when the caller has it so the ladder runs once per command.
+     */
+    workspace?: string;
     /** Global config the caller already loaded, to avoid a second read of the same file. */
     config?: OrbitMapConfig;
 }
@@ -363,5 +401,9 @@ export interface CreateClientOptions {
  * 0002 §2). `resolveAuth` used to carry a second, shorter copy of it that was missing the
  * `link.json` rung, so a cloud project with a `.orbitmap/link.json` got a different area
  * depending on which entry point it came through.
+ *
+ * The workspace identity comes from its own, separate ladder (`resolveWorkspaceId`) and is
+ * resolved here too: an area is no longer required, so a command run outside every area
+ * directory still has a context to send.
  */
 export declare function createClient(explicitArea?: string, options?: CreateClientOptions): Promise<CloudAdapter>;

package/dist/adapters/cloud.js

@@ -1,22 +1,30 @@
 import { createReadStream, statSync } from 'node:fs';
 import { basename, extname } from 'node:path';
-import { OrbitMapAPIError } from '../errors.js';
+import { AREA_CONTEXT_REQUIRED, AREA_WORKSPACE_MISMATCH, OrbitMapAPIError, WORKSPACE_CONTEXT_REQUIRED, } from '../errors.js';
 import { loadConfig, resolveAuth, DEFAULT_API_URL } from '../config.js';
-import { resolveArea } from '../workspace-resolve.js';
+import { areaContextHint, ORBITMAP_DIR, resolveArea, resolveWorkspaceId, } from '../workspace-resolve.js';
 import { isObjectNumber, resolveTaskRef, stripPrefix } from '../id-resolve.js';
 export class CloudAdapter {
     apiKey;
     baseUrl;
     area;
+    /**
+     * Workspace **identity** (slug or uuid, never a path) from the separate workspace ladder
+     * (`--workspace-id` → `ORBITMAP_WORKSPACE_ID` → project config `workspace` → global config
+     * `workspace`; see `resolveWorkspaceId`). Independent of {@link CloudAdapter.area}: either,
+     * both or neither may be set.
+     */
+    workspace;
     /**
      * Task reference → uuid, for the lifetime of this adapter. A command that touches the same
      * task twice (`dep add TS-a TS-b` resolves two, `status` then reads back) pays for one
      * `/tasks/by-number/{n}` lookup per distinct reference, not per call site.
      */
     taskIdCache = new Map();
-    constructor(apiKey, area, apiUrl) {
+    constructor(apiKey, area, apiUrl, workspace) {
         this.apiKey = apiKey;
         this.area = area;
+        this.workspace = workspace;
         this.baseUrl = (apiUrl ?? DEFAULT_API_URL).replace(/\/$/, '');
     }
     async request(method, path, options) {
@@ -32,6 +40,14 @@ export class CloudAdapter {
             Authorization: `Bearer ${this.apiKey}`,
             Accept: 'application/json',
         };
+        // The two context headers are independent and both optional. The server resolves the
+        // workspace from `X-Orbitmap-Workspace` first, then from the area, then by auto-detecting
+        // a unique one — so a workspace-level command (intent, mission, idea, docs) run outside
+        // any area directory works with the workspace header alone, and an area-only client
+        // (everything before schema v2) keeps behaving exactly as it did.
+        if (this.workspace) {
+            headers['X-Orbitmap-Workspace'] = this.workspace;
+        }
         if (this.area) {
             headers['X-Orbitmap-Area'] = this.area;
         }
@@ -64,7 +80,7 @@ export class CloudAdapter {
             }
             if (!response.ok) {
                 if (OrbitMapAPIError.isApiErrorBody(json)) {
-                    throw OrbitMapAPIError.fromResponse(json);
+                    throw this.explainContextError(OrbitMapAPIError.fromResponse(json));
                 }
                 // Billing/usage-limit rejections (402, 429) use a flat shape where
                 // `error` is a string — dispatch on the type of `error`, not status.
@@ -87,6 +103,53 @@ export class CloudAdapter {
             clearTimeout(timeout);
         }
     }
+    /**
+     * Add the client half of the story to the workspace-context errors the server can raise.
+     * The API knows what it received; only the CLI knows what it *sent* and which knobs could
+     * change that, and a bare "workspace context is required" is unactionable without it.
+     * Every other error is returned untouched.
+     *
+     * `AREA_CONTEXT_REQUIRED` is here too (TS-jt6q36 follow-up). The CLI raises that code
+     * itself — with the areas of the current workspace spelled out — but the *server* raises
+     * it as well, in HTTP terms ("set the X-Orbitmap-Area header. Call GET /api/agent/areas"),
+     * and that text used to reach the terminal verbatim: identical situation, two different
+     * answers depending on which side noticed first. The client-side advice is now attached to
+     * both, and the server's own sentence is kept (parenthesised) rather than dropped, because
+     * it is the only part that says what the API actually objected to.
+     */
+    explainContextError(error) {
+        // Dispatch on the canonical code, not the wire code: the API is renaming `PROJECT_*` to
+        // `AREA_*` and both spellings must land here (see ERROR_CODE_ALIASES in errors.ts).
+        if (error.canonicalCode !== WORKSPACE_CONTEXT_REQUIRED &&
+            error.canonicalCode !== AREA_WORKSPACE_MISMATCH &&
+            error.canonicalCode !== AREA_CONTEXT_REQUIRED) {
+            return error;
+        }
+        const sent = {};
+        if (this.workspace)
+            sent['X-Orbitmap-Workspace'] = this.workspace;
+        if (this.area)
+            sent['X-Orbitmap-Area'] = this.area;
+        if (error.canonicalCode === AREA_CONTEXT_REQUIRED) {
+            const { message, mappedDirectories } = areaContextHint();
+            return new OrbitMapAPIError(`${message} (The API added: ${error.message})`, error.code, error.status, {
+                ...error.details,
+                ...(mappedDirectories.length > 0
+                    ? { mapped_directories: mappedDirectories }
+                    : {}),
+                ...(Object.keys(sent).length > 0 ? { sent_context: sent } : {}),
+            });
+        }
+        const hint = error.canonicalCode === WORKSPACE_CONTEXT_REQUIRED
+            ? 'Name a workspace with --workspace-id <slug-or-uuid>, ORBITMAP_WORKSPACE_ID, or a ' +
+                `"workspace" in ${ORBITMAP_DIR}/config.json.`
+            : 'The workspace and the area disagree — check --workspace-id/--area, ' +
+                `ORBITMAP_WORKSPACE_ID/ORBITMAP_AREA and ${ORBITMAP_DIR}/config.json.`;
+        return new OrbitMapAPIError(`${error.message} ${hint}`, error.code, error.status, {
+            ...error.details,
+            ...(Object.keys(sent).length > 0 ? { sent_context: sent } : {}),
+        });
+    }
     // ── Context ──
     async getContext(areaId) {
         return this.request('GET', '/context', {
@@ -102,6 +165,14 @@ export class CloudAdapter {
     async getDefaultArea() {
         return this.area;
     }
+    /**
+     * The workspace identity this client sends as `X-Orbitmap-Workspace`, or `undefined` when
+     * none resolved (in which case the server derives one from the area or auto-detects it).
+     * No request is made.
+     */
+    getWorkspaceId() {
+        return this.workspace;
+    }
     // ── Tasks ──
     async getTasks(options) {
         return this.request('GET', '/tasks', {
@@ -225,6 +296,19 @@ export class CloudAdapter {
             body: { type, content, metadata },
         });
     }
+    async logIntentWork(idOrNumber, type, content, metadata) {
+        // No client-side resolution: `/intents/{id_or_number}/logs` accepts a uuid, an `IN-`
+        // display number or a bare code and resolves it server-side, exactly like every other
+        // intent route (see `tests/reference-passthrough.test.ts`).
+        return this.request('POST', `/intents/${idOrNumber}/logs`, {
+            body: { type, content, metadata },
+        });
+    }
+    async logMissionWork(idOrNumber, type, content, metadata) {
+        return this.request('POST', `/missions/${idOrNumber}/logs`, {
+            body: { type, content, metadata },
+        });
+    }
     // ── Documents ──
     async getDocuments(options) {
         return this.request('GET', '/documents', {
@@ -388,32 +472,23 @@ export class CloudAdapter {
             },
         });
     }
+    /**
+     * `GET /issues/{id_or_number}` — the single issue-read route. It accepts a uuid, a bare
+     * six-char code or the prefixed `IS-xxxxxx` form; the server strips the prefix and resolves
+     * the number workspace-scoped. There is no `/issues/by-number/{n}` route — never add one.
+     */
     async getIssue(idOrNumber) {
         return this.request('GET', `/issues/${idOrNumber}`);
     }
-    async getIssueByNumber(issueNumber) {
-        return this.request('GET', `/issues/by-number/${issueNumber}`);
-    }
-    async resolveIssueByNumber(issueNumber, data) {
-        return this.request('PATCH', `/issues/by-number/${issueNumber}/resolve`, {
-            body: data,
-        });
-    }
-    async resolveIssue(idOrNumber, data) {
-        return this.request('PATCH', `/issues/${idOrNumber}/resolve`, {
-            body: data,
-        });
-    }
+    /**
+     * `PATCH /issues/{id_or_number}/status` — the only issue-write route besides `/link` and
+     * `/assign`. `issue resolve` rides on it too: the API has no `/issues/{id}/resolve`.
+     */
     async updateIssueStatus(idOrNumber, data) {
         return this.request('PATCH', `/issues/${idOrNumber}/status`, {
             body: data,
         });
     }
-    async updateIssueStatusByNumber(issueNumber, data) {
-        return this.request('PATCH', `/issues/by-number/${issueNumber}/status`, {
-            body: data,
-        });
-    }
     // ── Vibes ──
     async logVibe(data) {
         return this.request('POST', '/vibes', { body: data });
@@ -439,21 +514,20 @@ export class CloudAdapter {
             params: { status: options?.status, priority: options?.priority, limit: options?.limit },
         });
     }
+    /**
+     * `GET /ideas/{id_or_number}` — accepts a uuid, a bare code or `ID-xxxxxx`; the server
+     * strips the prefix and resolves the number. There is no `/ideas/by-number/{n}` route.
+     */
     async getIdea(idOrNumber) {
         return this.request('GET', `/ideas/${idOrNumber}`);
     }
-    async getIdeaByNumber(ideaNumber) {
-        return this.request('GET', `/ideas/by-number/${ideaNumber}`);
-    }
     async createIdea(data) {
         return this.request('POST', '/ideas', { body: data });
     }
+    /** `PATCH /ideas/{id_or_number}/status`. */
     async updateIdeaStatus(idOrNumber, data) {
         return this.request('PATCH', `/ideas/${idOrNumber}/status`, { body: data });
     }
-    async updateIdeaStatusByNumber(ideaNumber, data) {
-        return this.request('PATCH', `/ideas/by-number/${ideaNumber}/status`, { body: data });
-    }
     // ── Orbits ──
     async listOrbits(options) {
         return this.request('GET', '/orbits', {
@@ -572,11 +646,16 @@ export { CloudAdapter as OrbitMapClient };
  * 0002 §2). `resolveAuth` used to carry a second, shorter copy of it that was missing the
  * `link.json` rung, so a cloud project with a `.orbitmap/link.json` got a different area
  * depending on which entry point it came through.
+ *
+ * The workspace identity comes from its own, separate ladder (`resolveWorkspaceId`) and is
+ * resolved here too: an area is no longer required, so a command run outside every area
+ * directory still has a context to send.
  */
 export async function createClient(explicitArea, options = {}) {
     const config = options.config ?? (await loadConfig());
     const auth = await resolveAuth({ config });
     const area = explicitArea ?? options.area ?? resolveArea({ config }).area;
-    return new CloudAdapter(auth.apiKey, area, auth.apiUrl);
+    const workspace = options.workspace ?? resolveWorkspaceId({ config }).workspace;
+    return new CloudAdapter(auth.apiKey, area, auth.apiUrl, workspace);
 }
 //# sourceMappingURL=cloud.js.map