orbitmap 0.4.2 → 0.4.4

package/dist/work-log.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"work-log.js","sourceRoot":"","sources":["../src/work-log.ts"],"names":[],"mappings":"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"}

package/dist/workspace-resolve.d.ts

@@ -9,12 +9,37 @@ export { ORBITMAP_DIR };
 export declare const LINK_FILE = "link.json";
 /** Marker file that identifies a directory as a local workspace. */
 export declare const WORKSPACE_FILE = "workspace.yml";
-/** Contents of `<project>/.orbitmap/link.json`. */
+/**
+ * Contents of a `.orbitmap/link.json` — the **machine-specific, gitignored** half of the
+ * OrbitMap files, holding everything that is a path on *this* disk.
+ *
+ * Two shapes, both valid, distinguished only by which fields are present:
+ *
+ * - **project-level** (the original): `workspace` points at the workspace directory living
+ *   elsewhere on this machine, `area` names the area this project is.
+ * - **workspace-level** (schema v2): the file sits in the workspace's own `.orbitmap/` and
+ *   carries {@link WorkspaceLink.areas} — the areas whose code is *not* under the workspace
+ *   tree, which therefore cannot be expressed in the committable
+ *   `config.json` `areas` map (see `OrbitMapConfig.areas`).
+ *
+ * Nothing forbids a single file from having all three fields; they are independent.
+ */
 export interface WorkspaceLink {
     /** Absolute path, or a path relative to the link file itself. */
     workspace?: string;
     /** Area slug within that workspace. */
     area?: string;
+    /**
+     * Area slug → the directory holding that area's code, for areas that live **outside the
+     * workspace tree** (the inverse direction of `OrbitMapConfig.areas`, which maps
+     * in-tree directory → slug).
+     *
+     * Values are absolute paths; a relative one is resolved against the link file's own
+     * directory, exactly like {@link WorkspaceLink.workspace}. This is why the mapping is
+     * split across two files: an absolute path is true only on one machine, so it must not
+     * land in the committable `config.json`.
+     */
+    areas?: Record<string, string>;
 }
 /** A `link.json` that was found on disk, with the file it came from. */
 export interface FoundWorkspaceLink {
@@ -24,6 +49,8 @@ export interface FoundWorkspaceLink {
 }
 export declare function setWorkspaceFlag(value?: string): void;
 export declare function getWorkspaceFlag(): string | undefined;
+export declare function setWorkspaceIdFlag(value?: string): void;
+export declare function getWorkspaceIdFlag(): string | undefined;
 /**
  * Walk up from `startDir` to the filesystem root looking for `.orbitmap/link.json`
  * (same discovery behaviour as git). Returns the nearest one, or `undefined`.
@@ -38,9 +65,22 @@ export declare function findLinkFile(startDir?: string): FoundWorkspaceLink | un
  * subdirectory is both what makes the mode local and what the path ladder returns.
  */
 export declare function findWorkspaceDir(startDir?: string): string | undefined;
+/**
+ * Parse and validate a raw `link.json` object — **per field**, like `parseConfig`: a
+ * mistyped `area` must not stop the `workspace` pointer next to it from working, and a
+ * single bad entry in {@link WorkspaceLink.areas} must not discard the rest of the map.
+ * Unknown keys are not represented here; nothing in the CLI rewrites this file wholesale.
+ */
+export declare function parseWorkspaceLink(raw: unknown): WorkspaceLink | undefined;
 export interface ResolveOptions {
     /** Explicit `--workspace <path>`; defaults to the captured global flag. */
     workspace?: string;
+    /**
+     * Explicit `--workspace-id <slug-or-uuid>`; defaults to the captured global flag.
+     * Identifies a workspace in the backend — unrelated to {@link ResolveOptions.workspace},
+     * which is a directory on this disk.
+     */
+    workspaceId?: string;
     /** Explicit `--area <slug>`. */
     area?: string;
     /** Directory the resolution starts from (defaults to `process.cwd()`). */
@@ -105,13 +145,54 @@ export declare function resolveWorkspacePath(options?: ResolveOptions): string;
 /**
  * Which rung of the area ladder produced a slug.
  *
- * `flag`/`env`/`link`/`project-config` are **explicit**: the user, the project's own
- * `link.json`, or the project's own `.orbitmap/config.json` named that area, so a slug that
- * does not exist must fail loudly. `config` is the machine-wide default (the deprecated
- * global `~/.orbitmap/config.json` `area` — ADR 0002) — the weakest rung, and the only one
- * a local workspace is allowed to override or ignore (see `createLocalContext`).
+ * `flag`/`env`/`link`/`project-config`/`cwd-map` are **explicit**: the user, the project's
+ * own `link.json`, or the project's own `.orbitmap/config.json` named that area (directly or
+ * by mapping the current directory to it), so a slug that does not exist must fail loudly.
+ * `config` is the machine-wide default (the deprecated global `~/.orbitmap/config.json`
+ * `area` — ADR 0002) — the weakest rung, and the only one a local workspace is allowed to
+ * override or ignore (see `createLocalContext`).
+ */
+export type AreaSource = 'flag' | 'env' | 'link' | 'project-config' | 'cwd-map' | 'config';
+/** One entry of the directory ↔ area mapping: "the code for `area` lives in `dir`". */
+export interface AreaDirectoryMapping {
+    /** Area slug. */
+    area: string;
+    /** Absolute directory holding that area's code. */
+    dir: string;
+    /** Which file declared it: the committable `config.json` or the machine-local `link.json`. */
+    from: 'config' | 'link';
+}
+/**
+ * True when `child` is `dir` itself or lives underneath it. Segment-wise (via `relative`)
+ * rather than a string prefix, so `/repo/app` does not swallow `/repo/app-legacy`, and
+ * case-folded on win32 via {@link comparablePath}, where `C:\Work\Repo` and `c:\work\repo`
+ * are one directory.
+ *
+ * Exported because `init` asks the same question about the same paths on the write side. It
+ * had grown its own weaker copy — no case-fold, and a `/^[a-zA-Z]:/` test on the *relative*
+ * result standing in for "different drive" — under which a root recorded as `C:\Work\Repo`
+ * did not contain `c:\work\repo\pkg`, so `init` silently laid down a second, competing
+ * `areas` map for the same workspace (TS-5c4yg9). One question, one answer.
  */
-export type AreaSource = 'flag' | 'env' | 'link' | 'project-config' | 'config';
+export declare function isWithin(dir: string, child: string): boolean;
+/**
+ * Every directory → area mapping visible from `cwd`, **deepest first** (so the first match is
+ * the most specific one, exactly like the nearest-file rule everywhere else).
+ *
+ * Two sources, both schema v2, pointing in opposite directions on purpose:
+ *
+ * - `OrbitMapConfig.areas` (directory → slug) from the nearest `.orbitmap/config.json` that
+ *   **sets `areas`** (per-field walk-up, ADR 0002 §2). Its keys are relative to the parent of
+ *   the `.orbitmap` directory holding that file — the workspace/project root — so they mean
+ *   the same thing in every checkout, which is why that file is the committable one.
+ * - `WorkspaceLink.areas` (slug → directory) from the nearest `.orbitmap/link.json`, for
+ *   areas whose code sits *outside* the tree. Absolute, or relative to the link file itself.
+ *
+ * Purely lexical: no directory is required to exist. Used both by the `cwd-map` rung of
+ * {@link resolveArea} and by the `AREA_CONTEXT_REQUIRED` details, so the error always lists
+ * exactly the directories that would have resolved an area.
+ */
+export declare function resolveAreaDirectoryMap(options?: ResolveOptions): AreaDirectoryMapping[];
 /** An area slug together with the rung it came from. */
 export interface ResolvedAreaSlug {
     area?: string;
@@ -120,11 +201,25 @@ export interface ResolvedAreaSlug {
 /**
  * Area resolution (ADR 0002, extending spec §3.3), explicit sources only:
  * `--area` → `ORBITMAP_AREA` → `link.json.area` → nearest `.orbitmap/config.json`
- * **that sets `area`** **[ADR 0002]** → global config `area` (deprecated).
+ * **that sets `area`** **[ADR 0002]** → **cwd matched against the `areas` directory map**
+ * (schema v2) → global config `area` (deprecated).
  *
  * The project-config rung is per-field (`resolveProjectConfigField`): a nested config that
  * sets only `agent` does not hide an `area` pinned by the repository root.
  *
+ * Every file-reading rung is bounded by {@link workspaceBoundary}: the config that names the
+ * `workspace` is the furthest ancestor allowed to name the area, because an area named above
+ * it belongs to another workspace (IS-e6q7je). The machine-wide `config` rung is left alone —
+ * it is already deprecated and warns on use.
+ *
+ * The `cwd-map` rung is what lets one workspace cover a whole monorepo without a config file
+ * in every package: the workspace's `config.json` says which directory is which area, and the
+ * current directory picks one (deepest mapping wins — see {@link resolveAreaDirectoryMap}).
+ * It sits *below* the `area` field on purpose, so a per-directory marker — a
+ * `.orbitmap/config.json` holding nothing but `area`, which is all schema v2 needs to pin one
+ * directory — still overrides the map, and every pre-v2 config that pins `area` keeps
+ * behaving exactly as it did.
+ *
  * The two remaining rungs — the workspace's own `workspace.yml` `default_area` (which
  * sits *between* the project config and the global config) and "workspace has exactly one
  * area → auto-select it" — require reading the workspace tree and therefore live in the
@@ -138,15 +233,90 @@ export declare function resolveAreaSlug(options?: ResolveOptions): string | unde
 /**
  * Assert that an area was resolved. Adapters call this after their own last-resort
  * auto-selection; `availableAreas` (when known) is surfaced in the error details.
+ *
+ * Missing area context is **not** a global error — most of the CLI (missions, intents, the
+ * workspace-level document tree) works without one, so `resolveWorkspaceContext` returns
+ * `scope: 'workspace'` rather than throwing. Only the operations that genuinely need an area
+ * come here, which is why the details carry `mapped_directories`: when an area exists but the
+ * current directory is not inside it, the fix is to `cd` into one of the listed directories
+ * (or pass `--area`), and the error is the only place that can say which ones those are.
+ *
+ * `options` scopes that lookup; omitted, it is computed from `process.cwd()` — the right
+ * answer for a real invocation, and what lets callers deep in the adapters (which have no
+ * `ResolveOptions` of their own) still produce a useful error.
+ */
+export declare function requireArea(area: string | undefined, availableAreas?: string[], options?: ResolveOptions): string;
+/**
+ * The same "which areas, and how to get into one" advice, for an `AREA_CONTEXT_REQUIRED`
+ * that arrived **from the server** (TS-jt6q36 follow-up).
+ *
+ * The API answers with its own text ("Pass area_id parameter or set the X-Orbitmap-Area
+ * header. Call GET /api/agent/areas…"), which describes the HTTP contract, not the CLI a
+ * person is actually holding — and it used to reach the terminal verbatim, so the improved
+ * local wording only ever showed up in local mode. This is what the cloud adapter wraps it
+ * with. Unlike {@link requireArea} it never knows the workspace's full area list (that would
+ * cost a request), so it falls back to the ways out alone, which are always actionable.
  */
-export declare function requireArea(area: string | undefined, availableAreas?: string[]): string;
+export declare function areaContextHint(options?: ResolveOptions): {
+    message: string;
+    mappedDirectories: Array<{
+        area: string;
+        dir: string;
+    }>;
+};
+/**
+ * Which rung of the workspace-identity ladder produced the slug/uuid — mirrors
+ * {@link AreaSource}, minus the rungs that only ever name an area.
+ */
+export type WorkspaceSource = 'flag' | 'env' | 'project-config' | 'config';
+/** A workspace slug/uuid together with the rung it came from. */
+export interface ResolvedWorkspaceId {
+    workspace?: string;
+    source?: WorkspaceSource;
+}
+/**
+ * Workspace **identity** resolution (schema v2), first match wins:
+ * 1. `--workspace-id <slug-or-uuid>` flag
+ * 2. `ORBITMAP_WORKSPACE_ID` env var
+ * 3. nearest `.orbitmap/config.json` **that sets `workspace`** (per-field, ADR 0002 §2)
+ * 4. global config `workspace`
+ *
+ * Strictly separate from {@link resolveWorkspacePath}, which answers a different question —
+ * *which directory on this disk* — and keeps its own unchanged ladder (`--workspace` →
+ * `ORBITMAP_WORKSPACE` → `link.json` → `workspace.yml` → `workspace_path`). A slug is never a
+ * path and a path is never a slug: `--workspace <path>` still means local mode and this rung
+ * never touches it, `--workspace-id` never implies a mode.
+ *
+ * Undefined is a normal outcome (an un-migrated cloud project, or local mode, where the
+ * workspace is a directory), not an error.
+ */
+export declare function resolveWorkspaceId(options?: ResolveOptions): ResolvedWorkspaceId;
+/**
+ * What the current invocation is scoped to.
+ *
+ * `'area'` when an area resolved — the historical behaviour, and what area-scoped commands
+ * need. `'workspace'` when none did: not an error, just a wider scope (missions, intents and
+ * workspace-level documents live there). Commands that cannot work without an area call
+ * {@link requireArea} and get `AREA_CONTEXT_REQUIRED`.
+ */
+export type ContextScope = 'area' | 'workspace';
 export interface ResolvedWorkspaceContext {
     mode: OrbitMapMode;
     /** Absolute workspace directory; only resolved in local mode. */
     workspacePath?: string;
+    /**
+     * Workspace **identity** — slug or uuid, never a path (see {@link resolveWorkspaceId}).
+     * Independent of {@link ResolvedWorkspaceContext.workspacePath}; either, both or neither
+     * may be set.
+     */
+    workspace?: string;
+    /** Which rung produced {@link ResolvedWorkspaceContext.workspace}. */
+    workspaceSource?: WorkspaceSource;
     area?: string;
     /** Which rung of the area ladder produced {@link ResolvedWorkspaceContext.area}. */
     areaSource?: AreaSource;
+    /** `'area'` when an area resolved, `'workspace'` otherwise. Never absent. */
+    scope: ContextScope;
     link?: FoundWorkspaceLink;
     config: OrbitMapConfig;
 }

package/dist/workspace-resolve.js

@@ -1,5 +1,5 @@
 import { existsSync, readFileSync } from 'node:fs';
-import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
 import { loadConfig } from './config.js';
 import { OrbitMapAPIError } from './errors.js';
 import { CONFIG_FILENAME, globalConfigReadPath, ORBITMAP_DIR } from './paths.js';
@@ -26,6 +26,21 @@ export function setWorkspaceFlag(value) {
 export function getWorkspaceFlag() {
     return workspaceFlag;
 }
+/**
+ * Value of the global `--workspace-id <slug-or-uuid>` flag.
+ *
+ * Deliberately a **different** flag from `--workspace <path>`, which keeps its historical
+ * meaning (the local workspace *directory*, and therefore local mode). `--workspace-id`
+ * names a workspace in the OrbitMap backend and changes nothing about the mode; the two
+ * never trade places. Captured program-level in `src/index.ts`, like `--workspace`.
+ */
+let workspaceIdFlag;
+export function setWorkspaceIdFlag(value) {
+    workspaceIdFlag = value && value.length > 0 ? value : undefined;
+}
+export function getWorkspaceIdFlag() {
+    return workspaceIdFlag;
+}
 /**
  * Walk up from `startDir` to the filesystem root looking for `.orbitmap/link.json`
  * (same discovery behaviour as git). Returns the nearest one, or `undefined`.
@@ -65,12 +80,39 @@ export function findWorkspaceDir(startDir = process.cwd()) {
         dir = parent;
     }
 }
+/**
+ * Parse and validate a raw `link.json` object — **per field**, like `parseConfig`: a
+ * mistyped `area` must not stop the `workspace` pointer next to it from working, and a
+ * single bad entry in {@link WorkspaceLink.areas} must not discard the rest of the map.
+ * Unknown keys are not represented here; nothing in the CLI rewrites this file wholesale.
+ */
+export function parseWorkspaceLink(raw) {
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw))
+        return undefined;
+    const r = raw;
+    const link = {};
+    if (typeof r['workspace'] === 'string' && r['workspace'])
+        link.workspace = r['workspace'];
+    if (typeof r['area'] === 'string' && r['area'])
+        link.area = r['area'];
+    const rawAreas = r['areas'];
+    if (typeof rawAreas === 'object' && rawAreas !== null && !Array.isArray(rawAreas)) {
+        const areas = {};
+        for (const [slug, path] of Object.entries(rawAreas)) {
+            if (!slug.trim())
+                continue;
+            if (typeof path !== 'string' || !path)
+                continue;
+            areas[slug] = path;
+        }
+        if (Object.keys(areas).length > 0)
+            link.areas = areas;
+    }
+    return link;
+}
 function readLinkFile(file) {
     try {
-        const parsed = JSON.parse(readFileSync(file, 'utf-8'));
-        if (typeof parsed !== 'object' || parsed === null)
-            return undefined;
-        return parsed;
+        return parseWorkspaceLink(JSON.parse(readFileSync(file, 'utf-8')));
     }
     catch {
         return undefined;
@@ -190,14 +232,135 @@ function warnRelativeWorkspacePath(configured) {
         'be an absolute path. A relative one would mean a different directory in every ' +
         'project. Use --workspace or ORBITMAP_WORKSPACE for a per-invocation override.');
 }
+/** Case-folded on Windows, whose filesystem is case-insensitive; lexical otherwise. */
+function comparablePath(path) {
+    const out = resolve(path);
+    return process.platform === 'win32' ? out.toLowerCase() : out;
+}
+/**
+ * True when `child` is `dir` itself or lives underneath it. Segment-wise (via `relative`)
+ * rather than a string prefix, so `/repo/app` does not swallow `/repo/app-legacy`, and
+ * case-folded on win32 via {@link comparablePath}, where `C:\Work\Repo` and `c:\work\repo`
+ * are one directory.
+ *
+ * Exported because `init` asks the same question about the same paths on the write side. It
+ * had grown its own weaker copy — no case-fold, and a `/^[a-zA-Z]:/` test on the *relative*
+ * result standing in for "different drive" — under which a root recorded as `C:\Work\Repo`
+ * did not contain `c:\work\repo\pkg`, so `init` silently laid down a second, competing
+ * `areas` map for the same workspace (TS-5c4yg9). One question, one answer.
+ */
+export function isWithin(dir, child) {
+    const rel = relative(comparablePath(dir), comparablePath(child));
+    return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel));
+}
+/**
+ * Every directory → area mapping visible from `cwd`, **deepest first** (so the first match is
+ * the most specific one, exactly like the nearest-file rule everywhere else).
+ *
+ * Two sources, both schema v2, pointing in opposite directions on purpose:
+ *
+ * - `OrbitMapConfig.areas` (directory → slug) from the nearest `.orbitmap/config.json` that
+ *   **sets `areas`** (per-field walk-up, ADR 0002 §2). Its keys are relative to the parent of
+ *   the `.orbitmap` directory holding that file — the workspace/project root — so they mean
+ *   the same thing in every checkout, which is why that file is the committable one.
+ * - `WorkspaceLink.areas` (slug → directory) from the nearest `.orbitmap/link.json`, for
+ *   areas whose code sits *outside* the tree. Absolute, or relative to the link file itself.
+ *
+ * Purely lexical: no directory is required to exist. Used both by the `cwd-map` rung of
+ * {@link resolveArea} and by the `AREA_CONTEXT_REQUIRED` details, so the error always lists
+ * exactly the directories that would have resolved an area.
+ */
+export function resolveAreaDirectoryMap(options = {}) {
+    const cwd = resolve(options.cwd ?? process.cwd());
+    const mappings = [];
+    // A map declared above the workspace boundary describes another workspace's areas
+    // (IS-e6q7je) — it must neither resolve an area nor be offered as a way out.
+    const boundary = workspaceBoundary(cwd);
+    const configAreas = resolveProjectConfigField('areas', cwd);
+    if (configAreas && withinWorkspace(boundary, configAreas.file)) {
+        // <root>/.orbitmap/config.json → <root>; `"."` is that root.
+        const root = dirname(dirname(configAreas.file));
+        for (const [dir, area] of Object.entries(configAreas.value)) {
+            mappings.push({ area, dir: dir === '.' ? root : resolve(root, dir), from: 'config' });
+        }
+    }
+    const found = options.link !== undefined ? options.link : findLinkFile(cwd);
+    if (found?.link.areas && withinWorkspace(boundary, found.file)) {
+        const linkDir = dirname(found.file);
+        for (const [area, dir] of Object.entries(found.link.areas)) {
+            mappings.push({
+                area,
+                dir: isAbsolute(dir) ? resolve(dir) : resolve(linkDir, dir),
+                from: 'link',
+            });
+        }
+    }
+    // Stable sort: deeper paths first, config before link on a tie (the committed file is the
+    // shared truth; the machine-local one only ever *adds* out-of-tree areas).
+    return mappings
+        .map((mapping, index) => ({ mapping, index }))
+        .sort((a, b) => {
+        const depth = b.mapping.dir.length - a.mapping.dir.length;
+        return depth !== 0 ? depth : a.index - b.index;
+    })
+        .map((entry) => entry.mapping);
+}
+/**
+ * Root directory of the workspace this invocation belongs to, or `undefined` when no config
+ * file names one (IS-e6q7je).
+ *
+ * The per-field walk-up (ADR 0002 §2) resolves `workspace` and `area` **independently**, which
+ * is right inside one tree — a package that pins only `agent` still inherits the root's
+ * `area`. Across trees it is not: a directory whose own `.orbitmap/config.json` says
+ * `workspace: "mcp-test"` nested under a checkout whose config says `area: "orbitmap-app"`
+ * used to resolve to the pair (workspace `mcp-test`, area `orbitmap-app`) — an area that
+ * belongs to a *different* workspace, so every command 404'd with `AREA_NOT_FOUND`.
+ *
+ * The file that names the workspace is therefore the boundary: an area may only be named by
+ * that file or by one below it. Nothing changes for a tree where no config sets `workspace` —
+ * there is no boundary to cross, and the ladder runs exactly as before.
+ */
+function workspaceBoundary(cwd) {
+    const declared = resolveProjectConfigField('workspace', cwd);
+    // <root>/.orbitmap/config.json → <root>
+    return declared ? dirname(dirname(declared.file)) : undefined;
+}
+/**
+ * True when a `.orbitmap/<file>` may speak for the workspace rooted at `boundary` — i.e. it
+ * sits at that root or below it. No boundary ⇒ every file qualifies.
+ */
+function withinWorkspace(boundary, file) {
+    if (!boundary)
+        return true;
+    return isWithin(boundary, dirname(dirname(file)));
+}
+/** The area whose mapped directory contains `cwd`, if any. */
+function resolveAreaFromCwd(options) {
+    const cwd = resolve(options.cwd ?? process.cwd());
+    return resolveAreaDirectoryMap(options).find((mapping) => isWithin(mapping.dir, cwd))?.area;
+}
 /**
  * Area resolution (ADR 0002, extending spec §3.3), explicit sources only:
  * `--area` → `ORBITMAP_AREA` → `link.json.area` → nearest `.orbitmap/config.json`
- * **that sets `area`** **[ADR 0002]** → global config `area` (deprecated).
+ * **that sets `area`** **[ADR 0002]** → **cwd matched against the `areas` directory map**
+ * (schema v2) → global config `area` (deprecated).
  *
  * The project-config rung is per-field (`resolveProjectConfigField`): a nested config that
  * sets only `agent` does not hide an `area` pinned by the repository root.
  *
+ * Every file-reading rung is bounded by {@link workspaceBoundary}: the config that names the
+ * `workspace` is the furthest ancestor allowed to name the area, because an area named above
+ * it belongs to another workspace (IS-e6q7je). The machine-wide `config` rung is left alone —
+ * it is already deprecated and warns on use.
+ *
+ * The `cwd-map` rung is what lets one workspace cover a whole monorepo without a config file
+ * in every package: the workspace's `config.json` says which directory is which area, and the
+ * current directory picks one (deepest mapping wins — see {@link resolveAreaDirectoryMap}).
+ * It sits *below* the `area` field on purpose, so a per-directory marker — a
+ * `.orbitmap/config.json` holding nothing but `area`, which is all schema v2 needs to pin one
+ * directory — still overrides the map, and every pre-v2 config that pins `area` keeps
+ * behaving exactly as it did.
+ *
  * The two remaining rungs — the workspace's own `workspace.yml` `default_area` (which
  * sits *between* the project config and the global config) and "workspace has exactly one
  * area → auto-select it" — require reading the workspace tree and therefore live in the
@@ -212,14 +375,26 @@ export function resolveArea(options = {}) {
     if (env)
         return { area: env, source: 'env' };
     const cwd = resolve(options.cwd ?? process.cwd());
+    // Everything below reads a file, and a file above the workspace boundary names an area of
+    // a different workspace (IS-e6q7je). No config sets `workspace` ⇒ no boundary ⇒ unchanged.
+    const boundary = workspaceBoundary(cwd);
     const found = options.link !== undefined ? options.link : findLinkFile(cwd);
-    if (found?.link.area)
+    if (found?.link.area && withinWorkspace(boundary, found.file)) {
         return { area: found.link.area, source: 'link' };
-    const projectArea = resolveProjectConfigField('area', cwd)?.value;
-    if (projectArea)
-        return { area: projectArea, source: 'project-config' };
+    }
+    const projectArea = resolveProjectConfigField('area', cwd);
+    if (projectArea && withinWorkspace(boundary, projectArea.file)) {
+        return { area: projectArea.value, source: 'project-config' };
+    }
+    const mapped = resolveAreaFromCwd({ ...options, cwd, link: found });
+    if (mapped)
+        return { area: mapped, source: 'cwd-map' };
+    // The machine-wide rung is bounded too, and for the same reason: a slug written once in
+    // `~/.orbitmap/config.json` cannot be known to name an area of *this* workspace, and when a
+    // project has declared which workspace it is, taking it anyway reproduces IS-e6q7je one rung
+    // lower. Without a declared workspace it stays exactly as it was (deprecated, warned).
     const configured = options.config?.area;
-    if (configured) {
+    if (configured && !boundary) {
         warnDeprecatedGlobalArea();
         return { area: configured, source: 'config' };
     }
@@ -249,13 +424,102 @@ export function resolveAreaSlug(options = {}) {
 /**
  * Assert that an area was resolved. Adapters call this after their own last-resort
  * auto-selection; `availableAreas` (when known) is surfaced in the error details.
+ *
+ * Missing area context is **not** a global error — most of the CLI (missions, intents, the
+ * workspace-level document tree) works without one, so `resolveWorkspaceContext` returns
+ * `scope: 'workspace'` rather than throwing. Only the operations that genuinely need an area
+ * come here, which is why the details carry `mapped_directories`: when an area exists but the
+ * current directory is not inside it, the fix is to `cd` into one of the listed directories
+ * (or pass `--area`), and the error is the only place that can say which ones those are.
+ *
+ * `options` scopes that lookup; omitted, it is computed from `process.cwd()` — the right
+ * answer for a real invocation, and what lets callers deep in the adapters (which have no
+ * `ResolveOptions` of their own) still produce a useful error.
  */
-export function requireArea(area, availableAreas) {
+export function requireArea(area, availableAreas, options) {
     if (area)
         return area;
-    throw OrbitMapAPIError.areaContextRequired(undefined, availableAreas && availableAreas.length > 0
-        ? { available_areas: availableAreas }
-        : undefined);
+    const details = {};
+    if (availableAreas && availableAreas.length > 0)
+        details['available_areas'] = availableAreas;
+    const mapped = resolveAreaDirectoryMap(options ?? {});
+    if (mapped.length > 0) {
+        details['mapped_directories'] = mapped.map(({ area: slug, dir }) => ({ area: slug, dir }));
+    }
+    throw OrbitMapAPIError.areaContextRequired(areaContextMessage(availableAreas, mapped), Object.keys(details).length > 0 ? details : undefined);
+}
+/**
+ * The `AREA_CONTEXT_REQUIRED` message, written around the areas of the *current* workspace
+ * (TS-jt6q36).
+ *
+ * "Pass --area <slug>" is only useful to someone who already knows the slugs; the two places
+ * that do know them are the workspace itself (`availableAreas`, handed in by the adapter)
+ * and the committed `areas` map in `.orbitmap/config.json` (`mapped`). Naming them turns the
+ * error into an instruction. Falls back to the generic wording when this invocation can see
+ * neither — a bare cloud client outside any project directory.
+ */
+function areaContextMessage(availableAreas, mapped) {
+    const slugs = [
+        ...new Set([...(availableAreas ?? []), ...mapped.map((entry) => entry.area)]),
+    ];
+    if (slugs.length === 0)
+        return undefined;
+    return (`This command needs one area, but this directory maps to none. Areas of this ` +
+        `workspace: ${slugs.join(', ')}. ${AREA_CONTEXT_WAYS_OUT}`);
+}
+/** The half of the message that is true whether or not the area slugs are known. */
+const AREA_CONTEXT_WAYS_OUT = 'Pick one with --area <slug>, cd into its directory (listed below when the project ' +
+    'config maps them), or use a workspace-wide command — `orbitmap tasks` with no area ' +
+    'lists every area, `orbitmap context` shows the whole workspace.';
+/**
+ * The same "which areas, and how to get into one" advice, for an `AREA_CONTEXT_REQUIRED`
+ * that arrived **from the server** (TS-jt6q36 follow-up).
+ *
+ * The API answers with its own text ("Pass area_id parameter or set the X-Orbitmap-Area
+ * header. Call GET /api/agent/areas…"), which describes the HTTP contract, not the CLI a
+ * person is actually holding — and it used to reach the terminal verbatim, so the improved
+ * local wording only ever showed up in local mode. This is what the cloud adapter wraps it
+ * with. Unlike {@link requireArea} it never knows the workspace's full area list (that would
+ * cost a request), so it falls back to the ways out alone, which are always actionable.
+ */
+export function areaContextHint(options) {
+    const mapped = resolveAreaDirectoryMap(options ?? {});
+    return {
+        message: areaContextMessage(undefined, mapped) ?? AREA_CONTEXT_WAYS_OUT,
+        mappedDirectories: mapped.map(({ area, dir }) => ({ area, dir })),
+    };
+}
+/**
+ * Workspace **identity** resolution (schema v2), first match wins:
+ * 1. `--workspace-id <slug-or-uuid>` flag
+ * 2. `ORBITMAP_WORKSPACE_ID` env var
+ * 3. nearest `.orbitmap/config.json` **that sets `workspace`** (per-field, ADR 0002 §2)
+ * 4. global config `workspace`
+ *
+ * Strictly separate from {@link resolveWorkspacePath}, which answers a different question —
+ * *which directory on this disk* — and keeps its own unchanged ladder (`--workspace` →
+ * `ORBITMAP_WORKSPACE` → `link.json` → `workspace.yml` → `workspace_path`). A slug is never a
+ * path and a path is never a slug: `--workspace <path>` still means local mode and this rung
+ * never touches it, `--workspace-id` never implies a mode.
+ *
+ * Undefined is a normal outcome (an un-migrated cloud project, or local mode, where the
+ * workspace is a directory), not an error.
+ */
+export function resolveWorkspaceId(options = {}) {
+    const flag = options.workspaceId ?? workspaceIdFlag;
+    if (flag)
+        return { workspace: flag, source: 'flag' };
+    const env = process.env['ORBITMAP_WORKSPACE_ID'];
+    if (env)
+        return { workspace: env, source: 'env' };
+    const cwd = resolve(options.cwd ?? process.cwd());
+    const projectWorkspace = resolveProjectConfigField('workspace', cwd)?.value;
+    if (projectWorkspace)
+        return { workspace: projectWorkspace, source: 'project-config' };
+    const configured = options.config?.workspace;
+    if (configured)
+        return { workspace: configured, source: 'config' };
+    return {};
 }
 /**
  * Full context resolution. Loads the global config when one is not injected.
@@ -269,16 +533,20 @@ export async function resolveWorkspaceContext(options = {}) {
     const opts = { ...options, cwd, config, link };
     const mode = resolveMode(opts);
     const { area, source: areaSource } = resolveArea(opts);
-    if (mode !== 'local') {
-        return { mode, area, areaSource, link, config };
-    }
-    return {
+    const { workspace, source: workspaceSource } = resolveWorkspaceId(opts);
+    const scope = area ? 'area' : 'workspace';
+    const base = {
         mode,
-        workspacePath: resolveWorkspacePath(opts),
+        workspace,
+        workspaceSource,
         area,
         areaSource,
+        scope,
         link,
         config,
     };
+    if (mode !== 'local')
+        return base;
+    return { ...base, workspacePath: resolveWorkspacePath(opts) };
 }
 //# sourceMappingURL=workspace-resolve.js.map