orbitmap 0.8.0 → 0.9.0

package/dist/commands/doc-errors.d.ts

@@ -0,0 +1,43 @@
+/**
+ * The document surface's refusal vocabulary, in ONE place (IN-jnz64x / S10).
+ *
+ * Every document command can now be refused for a reason that is about *scope* rather than
+ * about the reference the caller typed: the document exists, but it lives at a scope the
+ * caller did not address, or in an area the caller cannot write to. The intent's binding
+ * decision is that such a refusal must name the real cause — "wrong slug" was exactly the
+ * lie that made IS-fzczuw and IS-2psuq5 undiagnosable — so the wire codes are translated
+ * once, here, instead of once per command file.
+ *
+ * The map was born inside `doc-patch.ts`; the patch-only entries stay there and are merged
+ * on top of these by {@link printDocumentError}'s caller.
+ */
+import { OrbitMapAPIError } from '../errors.js';
+/**
+ * A write the server acknowledged as NOT having happened (`updated: false` / `imported:
+ * false` in an otherwise successful envelope).
+ *
+ * It is not a server error code: a server that knows a write failed answers
+ * `STORAGE_WRITE_FAILED` 503. This code exists for the contract violation in between — a
+ * 2xx whose own acknowledgement says the write did not land. Reporting success off the
+ * version number alone (what the CLI did before) is the one outcome that must not survive.
+ */
+export declare const WRITE_NOT_ACKNOWLEDGED = "WRITE_NOT_ACKNOWLEDGED";
+/** Friendly text for the server codes the document commands can be refused with. */
+export declare const DOCUMENT_FRIENDLY_ERRORS: Record<string, string>;
+/**
+ * Print an error, replacing the server's text with the friendly one when we have it.
+ *
+ * The lookup goes through the CANONICAL code (`ERROR_CODE_ALIASES` in `errors.ts`) while
+ * the reported code stays the wire one, so nothing a user sees changes across the API's
+ * `PROJECT_*` → `AREA_*` rename. Exit code is the caller's business — every command sets
+ * `process.exitCode = 1` in its catch, as it always did.
+ *
+ * @param extra Command-specific entries (e.g. `doc-patch`'s), merged over the shared map.
+ */
+export declare function printDocumentError(error: unknown, jsonMode: boolean, extra?: Record<string, string>): void;
+/**
+ * The error a command raises when the server's own acknowledgement says the write did not
+ * land. `subject` is what the user typed (title or reference), so the message names the
+ * thing that was NOT written.
+ */
+export declare function writeNotAcknowledged(operation: string, subject: string, details?: Record<string, unknown>): OrbitMapAPIError;

package/dist/commands/doc-errors.js

@@ -0,0 +1,77 @@
+/**
+ * The document surface's refusal vocabulary, in ONE place (IN-jnz64x / S10).
+ *
+ * Every document command can now be refused for a reason that is about *scope* rather than
+ * about the reference the caller typed: the document exists, but it lives at a scope the
+ * caller did not address, or in an area the caller cannot write to. The intent's binding
+ * decision is that such a refusal must name the real cause — "wrong slug" was exactly the
+ * lie that made IS-fzczuw and IS-2psuq5 undiagnosable — so the wire codes are translated
+ * once, here, instead of once per command file.
+ *
+ * The map was born inside `doc-patch.ts`; the patch-only entries stay there and are merged
+ * on top of these by {@link printDocumentError}'s caller.
+ */
+import { OrbitMapAPIError } from '../errors.js';
+import { printError } from '../output.js';
+/**
+ * A write the server acknowledged as NOT having happened (`updated: false` / `imported:
+ * false` in an otherwise successful envelope).
+ *
+ * It is not a server error code: a server that knows a write failed answers
+ * `STORAGE_WRITE_FAILED` 503. This code exists for the contract violation in between — a
+ * 2xx whose own acknowledgement says the write did not land. Reporting success off the
+ * version number alone (what the CLI did before) is the one outcome that must not survive.
+ */
+export const WRITE_NOT_ACKNOWLEDGED = 'WRITE_NOT_ACKNOWLEDGED';
+/** Friendly text for the server codes the document commands can be refused with. */
+export const DOCUMENT_FRIENDLY_ERRORS = {
+    DOCUMENT_NOT_REACHABLE: 'The document exists, but none of the areas it is linked to are areas you reach — ' +
+        'this is a scope refusal, not a wrong reference. Ask for access to one of its areas, ' +
+        'or have it shared into an area you belong to (`orbitmap doc-share`).',
+    DOCUMENT_NOT_WRITABLE: 'The document exists and you can read it, but your role in its area(s) is too low to ' +
+        'write to it. A workspace-level document (linked to no area) needs the matching ' +
+        'workspace role.',
+    LAST_AREA_DETACH: 'This is the document\'s last area: detaching it makes the document workspace-level ' +
+        'and drops the per-agent restrictions on that share. Re-run with ' +
+        '--confirm-workspace-scope if that is what you want.',
+    STORAGE_WRITE_FAILED: 'The content could not be stored, so NOTHING was written — the version was not bumped ' +
+        'and the previous content is intact. Try again; if it persists, the object storage is ' +
+        'down.',
+    CROSS_WORKSPACE: 'That area belongs to a different workspace. A document lives in exactly one workspace ' +
+        'and can only be linked to areas of that workspace.',
+    NOT_SHARED: 'The document is not shared with that area, so there was nothing to remove. Run ' +
+        '`orbitmap doc <id-or-slug>` to see where it is linked.',
+};
+/**
+ * Print an error, replacing the server's text with the friendly one when we have it.
+ *
+ * The lookup goes through the CANONICAL code (`ERROR_CODE_ALIASES` in `errors.ts`) while
+ * the reported code stays the wire one, so nothing a user sees changes across the API's
+ * `PROJECT_*` → `AREA_*` rename. Exit code is the caller's business — every command sets
+ * `process.exitCode = 1` in its catch, as it always did.
+ *
+ * @param extra Command-specific entries (e.g. `doc-patch`'s), merged over the shared map.
+ */
+export function printDocumentError(error, jsonMode, extra) {
+    if (error instanceof OrbitMapAPIError) {
+        const friendly = extra?.[error.canonicalCode] ?? DOCUMENT_FRIENDLY_ERRORS[error.canonicalCode];
+        if (friendly) {
+            // Re-wrap rather than hand-rolling the envelope: the `--json` consumer keeps the same
+            // `code`/`status` it always got, and still gets `details` like every other error.
+            printError(new OrbitMapAPIError(friendly, error.code, error.status, error.details), jsonMode);
+            return;
+        }
+    }
+    printError(error, jsonMode);
+}
+/**
+ * The error a command raises when the server's own acknowledgement says the write did not
+ * land. `subject` is what the user typed (title or reference), so the message names the
+ * thing that was NOT written.
+ */
+export function writeNotAcknowledged(operation, subject, details) {
+    return new OrbitMapAPIError(`The server accepted the request but reported that "${subject}" was NOT ${operation}. ` +
+        'Nothing was written — do not treat this as a success. Re-read the document to see ' +
+        'its current state before retrying.', WRITE_NOT_ACKNOWLEDGED, 500, details);
+}
+//# sourceMappingURL=doc-errors.js.map

package/dist/commands/doc-errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"doc-errors.js","sourceRoot":"","sources":["../../src/commands/doc-errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE1C;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,wBAAwB,CAAC;AAE/D,oFAAoF;AACpF,MAAM,CAAC,MAAM,wBAAwB,GAA2B;IAC9D,sBAAsB,EACpB,mFAAmF;QACnF,sFAAsF;QACtF,sEAAsE;IACxE,qBAAqB,EACnB,sFAAsF;QACtF,iFAAiF;QACjF,iBAAiB;IACnB,gBAAgB,EACd,qFAAqF;QACrF,kEAAkE;QAClE,qDAAqD;IACvD,oBAAoB,EAClB,uFAAuF;QACvF,uFAAuF;QACvF,OAAO;IACT,eAAe,EACb,wFAAwF;QACxF,oDAAoD;IACtD,UAAU,EACR,iFAAiF;QACjF,wDAAwD;CAC3D,CAAC;AAEF;;;;;;;;;GASG;AACH,MAAM,UAAU,kBAAkB,CAChC,KAAc,EACd,QAAiB,EACjB,KAA8B;IAE9B,IAAI,KAAK,YAAY,gBAAgB,EAAE,CAAC;QACtC,MAAM,QAAQ,GACZ,KAAK,EAAE,CAAC,KAAK,CAAC,aAAa,CAAC,IAAI,wBAAwB,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC;QAChF,IAAI,QAAQ,EAAE,CAAC;YACb,sFAAsF;YACtF,kFAAkF;YAClF,UAAU,CACR,IAAI,gBAAgB,CAAC,QAAQ,EAAE,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,OAAO,CAAC,EACvE,QAAQ,CACT,CAAC;YACF,OAAO;QACT,CAAC;IACH,CAAC;IACD,UAAU,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;AAC9B,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAClC,SAAiB,EACjB,OAAe,EACf,OAAiC;IAEjC,OAAO,IAAI,gBAAgB,CACzB,sDAAsD,OAAO,aAAa,SAAS,IAAI;QACrF,oFAAoF;QACpF,oCAAoC,EACtC,sBAAsB,EACtB,GAAG,EACH,OAAO,CACR,CAAC;AACJ,CAAC"}

package/dist/commands/doc-import.d.ts

@@ -1,3 +1,6 @@
+import type { DocumentScope } from '../adapters/types.js';
+/** The two spellings `--scope` accepts — the server's own enum (`workspace` | `area`). */
+export declare const DOCUMENT_SCOPES: readonly DocumentScope[];
 export declare function docImportCommand(title: string, options: {
     json: boolean;
     area?: string;
@@ -7,4 +10,10 @@ export declare function docImportCommand(title: string, options: {
     sourcePath?: string;
     context?: string;
     workspaceId?: string;
+    /**
+     * `--scope workspace|area`. Where the document LANDS. Separate from `workspaceId`,
+     * which only says WHICH workspace — the two used to be the same flag, and a caller who
+     * meant "workspace level" got an area document whenever the presigned path was taken.
+     */
+    scope?: string;
 }): Promise<void>;

package/dist/commands/doc-import.js

@@ -1,8 +1,11 @@
 import { readFileSync, statSync } from 'node:fs';
 import { createAdapter } from '../adapters/factory.js';
 import { confirmWriteTarget } from '../write-target.js';
-import { formatOutput, printError, printSuccess, printValidationError } from '../output.js';
+import { formatOutput, printSuccess, printValidationError } from '../output.js';
 import { DOCUMENT_TYPES } from '../enums.js';
+import { printDocumentError, writeNotAcknowledged } from './doc-errors.js';
+/** The two spellings `--scope` accepts — the server's own enum (`workspace` | `area`). */
+export const DOCUMENT_SCOPES = ['workspace', 'area'];
 function formatBytes(bytes) {
     if (bytes < 1024)
         return `${bytes} B`;
@@ -16,6 +19,15 @@ export async function docImportCommand(title, options) {
         printValidationError(msg, options.json);
         return;
     }
+    if (options.scope !== undefined &&
+        !DOCUMENT_SCOPES.includes(options.scope)) {
+        const msg = `Invalid --scope "${options.scope}". Valid: ${DOCUMENT_SCOPES.join(', ')} — ` +
+            '`workspace` links the document to no area (reachable from every one), `area` links ' +
+            'it to the area this invocation is scoped to.';
+        printValidationError(msg, options.json);
+        return;
+    }
+    const scope = options.scope;
     // Verify file is readable before doing anything
     try {
         statSync(options.file);
@@ -26,7 +38,9 @@ export async function docImportCommand(title, options) {
         return;
     }
     try {
-        await confirmWriteTarget('import document', options);
+        // `--scope workspace` creates ABOVE every area, so the echo must name the workspace
+        // rather than promise an area the document will not be linked to (see write-target.ts).
+        await confirmWriteTarget('import document', options, scope === 'workspace' ? 'workspace' : 'new');
         const client = await createAdapter(options.area);
         // Try presigned URL upload first
         const presignedResult = await client.presignedImport(options.file, {
@@ -35,6 +49,7 @@ export async function docImportCommand(title, options) {
             source_path: options.sourcePath,
             context: options.context,
             workspace_id: options.workspaceId,
+            scope,
         }, options.json
             ? undefined
             : (uploaded, total) => {
@@ -44,6 +59,16 @@ export async function docImportCommand(title, options) {
             if (!options.json) {
                 process.stderr.write('\n');
             }
+            // The server's own acknowledgement, not the fact that a 2xx came back: `imported:
+            // false` means the document was NOT created, and printing a slug for it would send
+            // the caller looking for something that does not exist.
+            if (presignedResult.data.imported === false) {
+                throw writeNotAcknowledged('imported', title, {
+                    document_id: presignedResult.data.document_id,
+                    slug: presignedResult.data.slug,
+                    upload_method: 'presigned',
+                });
+            }
             if (options.json) {
                 console.log(formatOutput({ ...presignedResult, upload_method: 'presigned' }, true));
                 return;
@@ -60,7 +85,15 @@ export async function docImportCommand(title, options) {
             source_path: options.sourcePath,
             context: options.context,
             workspace_id: options.workspaceId,
+            scope,
         }));
+        if (response.data.imported === false) {
+            throw writeNotAcknowledged('imported', title, {
+                document_id: response.data.document_id,
+                slug: response.data.slug,
+                upload_method: 'direct',
+            });
+        }
         if (options.json) {
             console.log(formatOutput({ ...response, upload_method: 'direct' }, true));
             return;
@@ -72,7 +105,7 @@ export async function docImportCommand(title, options) {
             // Clear progress line if present
             process.stderr.write('\n');
         }
-        printError(error, options.json);
+        printDocumentError(error, options.json);
         process.exitCode = 1;
     }
 }

package/dist/commands/doc-import.js.map

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

package/dist/commands/doc-patch.js

@@ -1,7 +1,12 @@
 import { createAdapter } from '../adapters/factory.js';
 import { confirmWriteTarget } from '../write-target.js';
-import { formatOutput, printError, printSuccess, printValidationError } from '../output.js';
-import { OrbitMapAPIError } from '../errors.js';
+import { formatOutput, printSuccess, printValidationError } from '../output.js';
+import { printDocumentError } from './doc-errors.js';
+/**
+ * The refusals only a PATCH can raise. Everything a document write can be refused with in
+ * general — the scope and storage codes — lives in `doc-errors.ts` and is merged under
+ * these by {@link printDocumentError}.
+ */
 const FRIENDLY_ERRORS = {
     CONTENT_UNAVAILABLE: 'Storage unavailable — patch aborted to prevent data loss. Try again later.',
     PATCH_RESULT_EMPTY: 'Patch would result in an empty document — aborted.',
@@ -135,17 +140,7 @@ export async function docPatchCommand(idOrSlug, options) {
         }
     }
     catch (error) {
-        // Look the friendly text up by the canonical code (ERROR_CODE_ALIASES in errors.ts) but
-        // keep reporting the wire code, so nothing the user sees changes across the API rename.
-        const friendly = error instanceof OrbitMapAPIError ? FRIENDLY_ERRORS[error.canonicalCode] : undefined;
-        if (error instanceof OrbitMapAPIError && friendly) {
-            // Re-wrap rather than hand-rolling the envelope: the `--json` consumer keeps the same
-            // `code`/`status` it always got, and now also gets `details` like every other error.
-            printError(new OrbitMapAPIError(friendly, error.code, error.status, error.details), options.json);
-            process.exitCode = 1;
-            return;
-        }
-        printError(error, options.json);
+        printDocumentError(error, options.json, FRIENDLY_ERRORS);
         process.exitCode = 1;
     }
 }

package/dist/commands/doc-patch.js.map

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

package/dist/commands/doc-share.d.ts

@@ -6,6 +6,7 @@ export declare function docShareCommand(documentId: string, areaId: string, opti
 export declare function docUnshareCommand(documentId: string, areaId: string, options: {
     json: boolean;
     area?: string;
+    confirmWorkspaceScope?: boolean;
 }): Promise<void>;
 export declare function docVisibilityCommand(documentId: string, areaId: string, options: {
     json: boolean;

package/dist/commands/doc-share.js

@@ -1,6 +1,7 @@
 import { createAdapter } from '../adapters/factory.js';
 import { confirmWriteTarget } from '../write-target.js';
-import { formatOutput, printError, printSuccess } from '../output.js';
+import { formatOutput, printSuccess } from '../output.js';
+import { printDocumentError } from './doc-errors.js';
 export async function docShareCommand(documentId, areaId, options) {
     const agentIds = options.agents
         ? options.agents.split(',').map((s) => s.trim())
@@ -19,7 +20,7 @@ export async function docShareCommand(documentId, areaId, options) {
         printSuccess(`Document ${documentId} shared with area ${areaId}${restriction}.`, false);
     }
     catch (error) {
-        printError(error, options.json);
+        printDocumentError(error, options.json);
         process.exitCode = 1;
     }
 }
@@ -27,15 +28,22 @@ export async function docUnshareCommand(documentId, areaId, options) {
     try {
         await confirmWriteTarget('unshare document', options, 'existing');
         const client = await createAdapter(options.area);
-        const response = (await client.unshareDocument(documentId, areaId));
+        const response = (await client.unshareDocument(documentId, areaId, options.confirmWorkspaceScope));
         if (options.json) {
             console.log(formatOutput(response, true));
             return;
         }
-        printSuccess(`Document ${documentId} unshared from area ${areaId}.`, false);
+        // Detaching the last area RE-SCOPES the document to the workspace and drops that
+        // share's per-agent restrictions. Saying only "unshared" would hide a change of scope
+        // behind a routine-sounding line.
+        const rescoped = response.data.scope === 'workspace'
+            ? ' It was the last area, so the document is now workspace-level: reachable from ' +
+                'every area, and no longer restricted to specific agents.'
+            : '';
+        printSuccess(`Document ${documentId} unshared from area ${areaId}.${rescoped}`, false);
     }
     catch (error) {
-        printError(error, options.json);
+        printDocumentError(error, options.json);
         process.exitCode = 1;
     }
 }
@@ -51,13 +59,14 @@ export async function docVisibilityCommand(documentId, areaId, options) {
             console.log(formatOutput(response, true));
             return;
         }
-        const restriction = response.data.restricted_to_agents.length > 0
-            ? `Restricted to ${response.data.restricted_to_agents.length} agent(s).`
+        const agentIdsInResponse = response.data.agent_ids ?? [];
+        const restriction = agentIdsInResponse.length > 0
+            ? `Restricted to ${agentIdsInResponse.length} agent(s).`
             : 'All agents can access.';
         printSuccess(`Visibility updated for document ${documentId} in area ${areaId}. ${restriction}`, false);
     }
     catch (error) {
-        printError(error, options.json);
+        printDocumentError(error, options.json);
         process.exitCode = 1;
     }
 }

package/dist/commands/doc-share.js.map

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

package/dist/commands/doc-update.js

@@ -1,7 +1,8 @@
 import { readFileSync, statSync } from 'node:fs';
 import { createAdapter } from '../adapters/factory.js';
 import { confirmWriteTarget } from '../write-target.js';
-import { formatOutput, printError, printSuccess, printValidationError } from '../output.js';
+import { formatOutput, printSuccess, printValidationError } from '../output.js';
+import { printDocumentError, writeNotAcknowledged } from './doc-errors.js';
 function formatBytes(bytes) {
     if (bytes < 1024)
         return `${bytes} B`;
@@ -32,6 +33,16 @@ export async function docUpdateCommand(idOrSlug, options) {
             if (!options.json) {
                 process.stderr.write('\n');
             }
+            // The acknowledgement, not the version number: `updated: false` says the content did
+            // NOT land, and reporting "updated to version N" off the bumped counter alone is the
+            // exact lie S7 exists to remove — the caller walks away believing the write happened.
+            if (presignedResult.data.updated === false) {
+                throw writeNotAcknowledged('updated', idOrSlug, {
+                    document_id: presignedResult.data.document_id,
+                    version: presignedResult.data.version,
+                    upload_method: 'presigned',
+                });
+            }
             if (options.json) {
                 console.log(formatOutput({ ...presignedResult, upload_method: 'presigned' }, true));
                 return;
@@ -42,6 +53,13 @@ export async function docUpdateCommand(idOrSlug, options) {
         // Fallback: read file into memory and send as JSON body
         const content = readFileSync(options.file, 'utf-8');
         const response = (await client.updateDocument(idOrSlug, content, options.changelog));
+        if (response.data.updated === false) {
+            throw writeNotAcknowledged('updated', idOrSlug, {
+                document_id: response.data.document_id,
+                version: response.data.version,
+                upload_method: 'direct',
+            });
+        }
         if (options.json) {
             console.log(formatOutput({ ...response, upload_method: 'direct' }, true));
             return;
@@ -53,7 +71,7 @@ export async function docUpdateCommand(idOrSlug, options) {
             // Clear progress line if present
             process.stderr.write('\n');
         }
-        printError(error, options.json);
+        printDocumentError(error, options.json);
         process.exitCode = 1;
     }
 }

package/dist/commands/doc-update.js.map

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

package/dist/index.js

@@ -38,7 +38,7 @@ import { createRequire } from 'node:module';
 import { createAreaCommand } from './commands/create-area.js';
 import { setWorkspaceFlag, setWorkspaceIdFlag } from './workspace-resolve.js';
 import { printValidationError } from './output.js';
-import { ALL_HELP, commandPath, DOCS_DESCRIPTION, IDEA_STATUS_HELP, IDEAS_DESCRIPTION, INTENT_STATUS_HELP, INTENTS_DESCRIPTION, ISSUE_STATUS_HELP, ISSUES_DESCRIPTION, LIMIT_HELP, MISSION_STATUS_HELP, MISSIONS_DESCRIPTION, multiAreaRejection, TASKS_DESCRIPTION, TASK_STATUS_HELP, VIBES_DESCRIPTION, } from './list-options.js';
+import { ALL_HELP, commandPath, DOCS_DESCRIPTION, IDEA_STATUS_HELP, IDEAS_DESCRIPTION, INTENT_STATUS_HELP, INTENTS_DESCRIPTION, ISSUE_STATUS_HELP, ISSUES_DESCRIPTION, LIMIT_HELP, MISSION_STATUS_HELP, MISSIONS_DESCRIPTION, multiAreaRejection, allAreasWriteRejection, DOCUMENT_SCOPE_NOTE, TASKS_DESCRIPTION, TASK_STATUS_HELP, VIBES_DESCRIPTION, } from './list-options.js';
 const program = new Command();
 /**
  * `--version` reads the real package version instead of a hardcoded literal, which had gone
@@ -95,7 +95,11 @@ program.hook('preAction', (thisCommand, actionCommand) => {
     const path = commandPath(actionCommand.name(), actionCommand.parent?.name());
     const area = actionCommand.opts()['area'] ??
         thisCommand.opts()['area'];
-    const rejected = multiAreaRejection(path, area);
+    const rejected = 
+    // `--area all` first: `multiAreaRejection` strips `all` before counting (it is not an
+    // area), which is why the multi-area guard could never fire on it and a document write
+    // took the flag as if it had said nothing.
+    allAreasWriteRejection(path, area) ?? multiAreaRejection(path, area);
     if (rejected) {
         printValidationError(rejected, Boolean(thisCommand.opts()['json']));
         // `printValidationError` sets the exit code; stop before the command writes anything.
@@ -434,12 +438,14 @@ program
 });
 program
     .command('doc-import <title>')
-    .description('Import a markdown file as a document (area or workspace level)')
+    .description(`Import a markdown file as a document. ${DOCUMENT_SCOPE_NOTE} — pick it with --scope`)
     .requiredOption('--type <type>', 'Document type: spec, architecture, api, guide, decision, changelog, other')
     .requiredOption('--file <path>', 'Path to markdown file')
     .option('--source-path <path>', 'Original source path for reference')
     .option('--context <text>', 'Short description of when this document is relevant')
-    .option('--workspace-id <slug-or-uuid>', 'Create as workspace-level document (cross-area knowledge); slug or UUID')
+    .option('--scope <scope>', 'Where the document lands: `workspace` (linked to no area, reachable from every one) ' +
+    'or `area` (linked to this invocation\'s area). Default: area')
+    .option('--workspace-id <slug-or-uuid>', 'WHICH workspace to create it in (slug or UUID) — not the scope; use --scope for that')
     .action(async (title, opts, cmd) => {
     const globalOpts = cmd.optsWithGlobals();
     await docImportCommand(title, {
@@ -450,6 +456,7 @@ program
         file: opts.file,
         sourcePath: opts.sourcePath,
         context: opts.context,
+        scope: opts.scope,
         // Program-level `--workspace-id` is the fallback when it was given before the
         // subcommand name (see `create-area`).
         workspaceId: opts.workspaceId ?? globalOpts.workspaceId,
@@ -457,7 +464,8 @@ program
 });
 program
     .command('doc-update <id-or-slug>')
-    .description('Update a document with content from a file')
+    .description(`Update a document with content from a file. ${DOCUMENT_SCOPE_NOTE}; the id or slug ` +
+    'resolves across the whole workspace, whatever this directory maps to')
     .requiredOption('--file <path>', 'Path to markdown file with new content')
     .option('--changelog <text>', 'Description of what changed')
     .action(async (idOrSlug, opts, cmd) => {
@@ -471,7 +479,8 @@ program
 });
 program
     .command('doc-patch <id-or-slug>')
-    .description('Patch a document with section-based operations')
+    .description(`Patch a document with section-based operations. ${DOCUMENT_SCOPE_NOTE}; the id or ` +
+    'slug resolves across the whole workspace')
     .requiredOption('--base-version <n>', 'Document version to patch against (optimistic lock)')
     .option('--operations <json>', 'JSON array of patch operations')
     .option('--replace-section <heading>', 'Replace a section body (requires --content)')
@@ -501,7 +510,8 @@ program
 });
 program
     .command('doc-share <document-id> <area-id>')
-    .description('Share a document with another area')
+    .description(`Link a document to another area. ${DOCUMENT_SCOPE_NOTE} — sharing a workspace-level ` +
+    'document into one area NARROWS it to that area')
     .option('--agents <ids>', 'Comma-separated agent IDs to restrict visibility')
     .action(async (documentId, areaId, opts, cmd) => {
     const globalOpts = cmd.optsWithGlobals();
@@ -513,17 +523,22 @@ program
 });
 program
     .command('doc-unshare <document-id> <area-id>')
-    .description('Remove document sharing from an area')
-    .action(async (documentId, areaId, _opts, cmd) => {
+    .description(`Unlink a document from an area. ${DOCUMENT_SCOPE_NOTE}, so detaching the LAST area ` +
+    'makes the document workspace-level')
+    .option('--confirm-workspace-scope', 'Allow detaching the document\'s last area: it becomes workspace-level (reachable ' +
+    'from every area) and that share\'s per-agent restrictions are dropped')
+    .action(async (documentId, areaId, opts, cmd) => {
     const globalOpts = cmd.optsWithGlobals();
     await docUnshareCommand(documentId, areaId, {
         json: globalOpts.json,
         area: globalOpts.area,
+        confirmWorkspaceScope: opts.confirmWorkspaceScope,
     });
 });
 program
     .command('doc-visibility <document-id> <target-area-id>')
-    .description('Update document visibility (restrict to specific agents or allow all)')
+    .description('Update document visibility in one area (restrict to specific agents or allow all). ' +
+    `${DOCUMENT_SCOPE_NOTE}, and a restriction applies to one of those links`)
     .option('--agents <ids>', 'Comma-separated agent IDs to restrict visibility (omit to allow all)')
     .action(async (documentId, targetAreaId, opts, cmd) => {
     const globalOpts = cmd.optsWithGlobals();