orbitmap 0.4.2 → 0.4.3

package/dist/paths.js

@@ -1,6 +1,6 @@
-import { existsSync, realpathSync } from 'node:fs';
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { dirname, join, resolve } from 'node:path';
+import { basename, dirname, join, resolve } from 'node:path';
 /** Name of the per-project OrbitMap directory (`<project>/.orbitmap`). */
 export const ORBITMAP_DIR = '.orbitmap';
 /**
@@ -12,6 +12,28 @@ export const ORBITMAP_DIR = '.orbitmap';
 export const CONFIG_FILENAME = 'config.json';
 /** Filename of the machine-local secret store (`~/.orbitmap/credentials.json`). */
 export const CREDENTIALS_FILENAME = 'credentials.json';
+/**
+ * Filename of the gitignored, machine-specific link file (`<project>/.orbitmap/link.json`).
+ *
+ * Duplicated from `workspace-resolve.ts`'s `LINK_FILE` rather than imported: that module
+ * sits above this one, and this is a leaf.
+ */
+const LINK_FILENAME = 'link.json';
+/**
+ * The one directory holding documents, in **both** modes (IN-rwb5qu).
+ *
+ * Cloud mode: `<project>/.orbitmap/docs/` is the download cache. Local mode: the same
+ * `docs/` inside the workspace directory is the domain data itself — and for the usual
+ * in-project workspace (`<project>/.orbitmap`) that is literally the same path. Hence one
+ * name here rather than one per layer: there is exactly ONE copy of a document on disk,
+ * globally, with **no per-area subdirectories** (the data model does not record a
+ * document's home area, so the directory tree must not pretend it does).
+ */
+export const DOCS_DIR = 'docs';
+/** Pre-v2 local-workspace name of {@link DOCS_DIR}; migrated away by `LocalStore.migrate()`. */
+export const LEGACY_DOCUMENTS_DIR = 'documents';
+/** Cache bookkeeping inside {@link DOCS_DIR}; written in cloud mode only. */
+export const DOC_CACHE_MANIFEST = '.manifest.json';
 let homeCache;
 /**
  * The resolved OrbitMap home, memoised.
@@ -141,22 +163,165 @@ export function findProjectConfigFiles(startDir = process.cwd()) {
     const found = [];
     const globals = new Set(globalConfigPaths().map(canonical));
     const homeStop = canonical(homedir());
+    const seenFiles = new Set();
+    const seenStarts = new Set();
+    // Directories whose walk-up still has to run: `startDir` first, then any workspace root a
+    // `link.json` back-pointer found along the way names (see the doc comment above).
+    const queue = [resolve(startDir)];
+    while (queue.length > 0) {
+        const start = queue.shift();
+        if (seenStarts.has(canonical(start)))
+            continue;
+        seenStarts.add(canonical(start));
+        let dir = start;
+        for (;;) {
+            const orbitmapDir = join(dir, ORBITMAP_DIR);
+            const candidate = join(orbitmapDir, CONFIG_FILENAME);
+            if (existsSync(candidate) &&
+                !globals.has(canonical(candidate)) &&
+                !isOrbitMapHomeDir(orbitmapDir)) {
+                const key = canonical(candidate);
+                if (!seenFiles.has(key)) {
+                    seenFiles.add(key);
+                    found.push(candidate);
+                }
+            }
+            // An out-of-tree area cannot reach its workspace root by walking up; its machine-local
+            // `link.json` says where the root is, so the walk hops there and continues rather than
+            // ending with `agent`/`mode`/`workspace` unresolved (IS-ktfg5z).
+            const pointer = workspacePointer(orbitmapDir);
+            if (pointer && !seenStarts.has(canonical(pointer)))
+                queue.push(pointer);
+            if (canonical(dir) === homeStop)
+                break;
+            const parent = dirname(dir);
+            if (parent === dir)
+                break;
+            dir = parent;
+        }
+    }
+    return found;
+}
+/**
+ * The nearest directory at or above `startDir` that owns an `.orbitmap/` — the project (or
+ * workspace) root the doc cache and the `.gitignore` entries belong to. `undefined` when the
+ * walk finds none.
+ *
+ * The same walk and the same guards as {@link findProjectConfigFiles}, for the same reasons:
+ * an OrbitMap *home* is never a project (a relocated or mis-`$HOME`-ed `~/.orbitmap` sits on
+ * the walk path as an ordinary ancestor), and nothing above the user's home is that user's
+ * project. Only the *directory* is required to exist here — a project that has never had a
+ * `config.json` still owns its `.orbitmap/link.json` or `.orbitmap/docs/`.
+ *
+ * This is what replaces the doc cache's old `join('.orbitmap', 'docs')`, which resolved
+ * against `process.cwd()` with no walk-up at all and therefore scattered a fresh copy of
+ * every document into every subdirectory a command happened to run from.
+ *
+ * **One workspace = one directory = one `.orbitmap`.** The walk is not a search for any
+ * `.orbitmap` that happens to look like a workspace: it stops at the first ancestor that
+ * declares one ({@link declaresWorkspace}) and returns it, or follows an explicit
+ * back-pointer ({@link workspacePointer}) when the area lives outside the tree. Climbing
+ * past the first declaration used to hand the deepest directory to the *furthest* ancestor
+ * declaring a workspace — by construction not its owner — so two workspaces side by side
+ * under a third pooled their documents into the outermost one's flat `<slug>.md` namespace
+ * and overwrote each other (IS-8hv2wn).
+ */
+export function findProjectOrbitMapDir(startDir = process.cwd()) {
+    const globals = new Set(globalConfigPaths().map(canonical));
+    const homeStop = canonical(homedir());
+    let nearest;
     let dir = resolve(startDir);
     for (;;) {
         const orbitmapDir = join(dir, ORBITMAP_DIR);
-        const candidate = join(orbitmapDir, CONFIG_FILENAME);
-        if (existsSync(candidate) &&
-            !globals.has(canonical(candidate)) &&
-            !isOrbitMapHomeDir(orbitmapDir)) {
-            found.push(candidate);
+        if (existsSync(orbitmapDir) &&
+            !isOrbitMapHomeDir(orbitmapDir) &&
+            !globals.has(canonical(join(orbitmapDir, CONFIG_FILENAME)))) {
+            nearest ??= dir;
+            // A back-pointer wins outright: this directory has been told, in writing, where its
+            // workspace lives, so there is nothing left to search for.
+            const pointer = workspacePointer(orbitmapDir);
+            if (pointer)
+                return pointer;
+            // The FIRST declaring config is the owner. Climbing further would hand `startDir`
+            // to whichever unrelated ancestor happens to declare a workspace too — by
+            // definition not the one that owns it (IS-8hv2wn).
+            if (declaresWorkspace(orbitmapDir))
+                return dir;
         }
         if (canonical(dir) === homeStop)
-            return found;
+            break;
         const parent = dirname(dir);
         if (parent === dir)
-            return found;
+            break;
         dir = parent;
     }
+    return nearest;
+}
+/** Parse a JSON file into a plain object, or `undefined` when it is missing/unreadable. */
+function readJsonObject(file) {
+    try {
+        const raw = JSON.parse(readFileSync(file, 'utf-8'));
+        if (typeof raw !== 'object' || raw === null || Array.isArray(raw))
+            return undefined;
+        return raw;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The workspace **directory** this `.orbitmap/` points at, when it points at one elsewhere.
+ *
+ * An area directory living outside the workspace tree cannot reach the workspace root by
+ * walking up — there is nothing above it but unrelated directories. `init` therefore writes
+ * `{"workspace": "<path>"}` into that area's own machine-local `link.json` (the same field,
+ * the same meaning, as in local mode: *where* the workspace is). Following it is what keeps
+ * such an area sharing the one global `docs/` instead of quietly starting a second copy.
+ *
+ * Accepts either the workspace root or its `.orbitmap/` directory — `resolveWorkspacePath`
+ * hands back the latter for a `workspace.yml`-marked local workspace, so both spellings of
+ * "the workspace is over there" exist in the wild, and both must mean the same directory
+ * here. Relative paths resolve against the link file, exactly as in `resolveWorkspacePath`.
+ */
+function workspacePointer(orbitmapDir) {
+    const link = readJsonObject(join(orbitmapDir, LINK_FILENAME));
+    const target = link?.['workspace'];
+    if (typeof target !== 'string' || !target)
+        return undefined;
+    const resolved = resolve(orbitmapDir, target);
+    return basename(resolved) === ORBITMAP_DIR ? dirname(resolved) : resolved;
+}
+/**
+ * Does this `.orbitmap/` belong to a *workspace* root rather than an area directory?
+ *
+ * The distinction is **location**, not identity. An out-of-tree area marker also carries a
+ * `workspace` field, because it needs the slug for the `X-Orbitmap-Workspace` header and has
+ * no root config to inherit it from — but naming your workspace is not the same as being its
+ * root, and reading it as one gave that directory its own second copy of every document.
+ * A file that pins an `area` is a marker, full stop; a root is what maps `areas` (or names a
+ * workspace without claiming to be an area). Read directly rather than through
+ * `project-config.ts`, which sits above this module.
+ *
+ * `link.json` is deliberately *not* enough on its own: its `workspace` field is a pointer at
+ * a workspace somewhere else (see {@link workspacePointer}) — the opposite of being one. Only
+ * its `areas` map, which lists the out-of-tree areas *of this workspace*, marks a root.
+ */
+function declaresWorkspace(orbitmapDir) {
+    const link = readJsonObject(join(orbitmapDir, LINK_FILENAME));
+    if (isPlainObject(link?.['areas']))
+        return true;
+    const raw = readJsonObject(join(orbitmapDir, CONFIG_FILENAME));
+    if (!raw)
+        return false;
+    if (isPlainObject(raw['areas']))
+        return true;
+    // `typeof null === 'object'` used to make `"areas": null` a workspace root; hence the
+    // explicit shape check above and the `area`-marker exclusion here.
+    return typeof raw['workspace'] === 'string' && typeof raw['area'] !== 'string';
+}
+/** A non-null, non-array object — what an `areas` map has to be to mean anything. */
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
 /**
  * Per-field walk-up: hand each project config file, nearest first, to `read` and return the

package/dist/paths.js.map

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

package/dist/project-config.d.ts

@@ -41,11 +41,52 @@ export interface OrbitMapConfig {
     workspace_path?: string;
     /** Name of the agent profile to use — looked up in `~/.orbitmap/credentials.json`. */
     agent?: string;
-    /** Default area slug/id. */
+    /**
+     * Workspace this config belongs to — a workspace **slug or UUID**, never a path (the
+     * *directory* is `workspace_path` / the `link.json` pointer / the marker walk-up).
+     *
+     * Written into the workspace directory's own `.orbitmap/config.json` (schema v2), which is
+     * committable and holds no secrets. Purely declarative here: this field says *which*
+     * workspace the tree belongs to, it does not participate in the workspace-directory ladder.
+     */
+    workspace?: string;
+    /**
+     * Directory → area slug map (schema v2): "the code for area `x` lives in this directory".
+     *
+     * **Keys are relative directory paths, resolved against the parent of the `.orbitmap`
+     * directory that holds this config file** — i.e. against the workspace/project root, not
+     * against the current directory and not against `.orbitmap/` itself. `"."` is that root.
+     * Keys are normalised on read ({@link normalizeAreaPathKey}): backslashes become `/`,
+     * `./` prefixes and trailing slashes are dropped, and an empty result becomes `"."`.
+     *
+     * Values are area slugs.
+     *
+     * **Absolute keys and keys that escape upward (`..`) are rejected**, deliberately: a
+     * directory outside the tree is machine-specific and therefore belongs in the gitignored
+     * `link.json` (see `WorkspaceLink.areas` in `workspace-resolve.ts`), not in a file meant to
+     * be committed and to mean the same thing in every checkout.
+     */
+    areas?: Record<string, string>;
+    /**
+     * Default area slug/id.
+     *
+     * Still read on every rung for back-compat — an existing project config that pins `area`
+     * keeps working unchanged. Schema v2 replaces it with the directory-scoped {@link areas}
+     * map plus a per-area marker config, so `orbitmap init` no longer *writes* this field.
+     */
     area?: string;
     /** @deprecated Legacy secret, read once for migration then dropped. Never written. */
     api_key?: string;
 }
+/**
+ * Canonical form of one {@link OrbitMapConfig.areas} key, or `undefined` when the key is not
+ * a usable relative directory path.
+ *
+ * Normalises what a hand-written (or Windows-written) config may contain — `.\packages\api`,
+ * `packages/api/`, `./` — into one comparable form (`packages/api`, `.`). Rejects absolute
+ * paths and any `..` segment; see {@link OrbitMapConfig.areas} for why.
+ */
+export declare function normalizeAreaPathKey(key: string): string | undefined;
 /**
  * Parse and validate a raw config object (either file) — mistyped fields drop out instead
  * of propagating a garbage value into the resolution ladders. Unknown keys are not

package/dist/project-config.js

@@ -1,5 +1,51 @@
 import { readFileSync } from 'node:fs';
 import { resolveProjectField } from './paths.js';
+/** Matches a Windows drive prefix (`C:`), which `node:path`'s POSIX `isAbsolute` does not —
+ *  an `areas` key is a portable, committable path and must be rejected on every platform. */
+const WINDOWS_DRIVE = /^[a-zA-Z]:/;
+/**
+ * Canonical form of one {@link OrbitMapConfig.areas} key, or `undefined` when the key is not
+ * a usable relative directory path.
+ *
+ * Normalises what a hand-written (or Windows-written) config may contain — `.\packages\api`,
+ * `packages/api/`, `./` — into one comparable form (`packages/api`, `.`). Rejects absolute
+ * paths and any `..` segment; see {@link OrbitMapConfig.areas} for why.
+ */
+export function normalizeAreaPathKey(key) {
+    const slashed = key.replace(/\\/g, '/').trim();
+    if (!slashed)
+        return undefined;
+    if (slashed.startsWith('/') || WINDOWS_DRIVE.test(slashed))
+        return undefined;
+    const segments = slashed.split('/').filter((part) => part.length > 0 && part !== '.');
+    if (segments.some((part) => part === '..'))
+        return undefined;
+    return segments.length === 0 ? '.' : segments.join('/');
+}
+/**
+ * Validate the `areas` map: a plain object of relative-directory → non-empty area slug.
+ *
+ * **Rejected per entry, not per file.** One unusable key (absolute, `..`, non-string value)
+ * must not take the rest of a repository's mapping down with it — the same reasoning as the
+ * per-field validation in {@link parseConfig}. When nothing valid is left the field itself is
+ * dropped, so a ladder sees "not set" rather than an empty map. On a collision (two keys
+ * normalising to the same directory) the first entry wins.
+ */
+function parseAreasMap(raw) {
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw))
+        return undefined;
+    const areas = {};
+    for (const [key, value] of Object.entries(raw)) {
+        if (typeof value !== 'string' || !value)
+            continue;
+        const dir = normalizeAreaPathKey(key);
+        if (dir === undefined)
+            continue;
+        if (!(dir in areas))
+            areas[dir] = value;
+    }
+    return Object.keys(areas).length > 0 ? areas : undefined;
+}
 /**
  * Parse and validate a raw config object (either file) — mistyped fields drop out instead
  * of propagating a garbage value into the resolution ladders. Unknown keys are not
@@ -19,6 +65,11 @@ export function parseConfig(raw) {
     }
     if (typeof r['agent'] === 'string' && r['agent'])
         config.agent = r['agent'];
+    if (typeof r['workspace'] === 'string' && r['workspace'])
+        config.workspace = r['workspace'];
+    const areas = parseAreasMap(r['areas']);
+    if (areas)
+        config.areas = areas;
     if (typeof r['area'] === 'string' && r['area'])
         config.area = r['area'];
     if (typeof r['api_key'] === 'string' && r['api_key'])

package/dist/project-config.js.map

@@ -1 +1 @@
-{"version":3,"file":"project-config.js","sourceRoot":"","sources":["../src/project-config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAqDjD;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,GAAY;IACtC,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI;QAAE,OAAO,EAAE,CAAC;IACvD,MAAM,CAAC,GAAG,GAA8B,CAAC;IACzC,MAAM,MAAM,GAAmB,EAAE,CAAC;IAElC,IAAI,OAAO,CAAC,CAAC,gBAAgB,CAAC,KAAK,QAAQ;QAAE,MAAM,CAAC,cAAc,GAAG,CAAC,CAAC,gBAAgB,CAAC,CAAC;IACzF,IAAI,CAAC,CAAC,MAAM,CAAC,KAAK,OAAO,IAAI,CAAC,CAAC,MAAM,CAAC,KAAK,OAAO;QAAE,MAAM,CAAC,IAAI,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC;IAC5E,IAAI,OAAO,CAAC,CAAC,gBAAgB,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,gBAAgB,CAAC,EAAE,CAAC;QACnE,MAAM,CAAC,cAAc,GAAG,CAAC,CAAC,gBAAgB,CAAC,CAAC;IAC9C,CAAC;IACD,IAAI,OAAO,CAAC,CAAC,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,OAAO,CAAC;QAAE,MAAM,CAAC,KAAK,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC;IAC5E,IAAI,OAAO,CAAC,CAAC,MAAM,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,MAAM,CAAC;QAAE,MAAM,CAAC,IAAI,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC;IACxE,IAAI,OAAO,CAAC,CAAC,SAAS,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,SAAS,CAAC;QAAE,MAAM,CAAC,OAAO,GAAG,CAAC,CAAC,SAAS,CAAC,CAAC;IAEpF,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;sFACsF;AACtF,MAAM,UAAU,qBAAqB,CAAC,IAAY;IAChD,IAAI,CAAC;QACH,OAAO,WAAW,CAAC,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;IAC9D,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AASD;;;;;;;;;;GAUG;AACH,MAAM,UAAU,yBAAyB,CACvC,KAAQ,EACR,WAAmB,OAAO,CAAC,GAAG,EAAE;IAEhC,MAAM,GAAG,GAAG,mBAAmB,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,qBAAqB,CAAC,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC;IAC1F,OAAO,GAAG;QACR,CAAC,CAAC,EAAE,KAAK,EAAE,GAAG,CAAC,KAAuC,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE;QACxE,CAAC,CAAC,SAAS,CAAC;AAChB,CAAC"}
+{"version":3,"file":"project-config.js","sourceRoot":"","sources":["../src/project-config.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;
 }