orbitmap 0.4.2 → 0.4.3

package/dist/commands/tasks.js

@@ -1,5 +1,6 @@
 import { createAdapter } from '../adapters/factory.js';
 import { formatOutput, printError, formatTable } from '../output.js';
+import { groupByArea } from '../area-grouping.js';
 export async function tasksCommand(options) {
     try {
         const client = await createAdapter(options.area);
@@ -8,6 +9,8 @@ export async function tasksCommand(options) {
             priority: options.priority,
             orbit: options.orbit,
         }));
+        // Passed through verbatim, so the per-task `area` of the workspace-scoped listing
+        // survives into `--json` — agents group on it.
         if (options.json) {
             console.log(formatOutput(response, true));
             return;
@@ -17,19 +20,52 @@ export async function tasksCommand(options) {
             console.log('No tasks found.');
             return;
         }
-        console.log(`Tasks (${response.meta.count}):\n`);
-        const hasDelivery = tasks.some((t) => t.delivery_status);
-        const headers = hasDelivery
-            ? ['#', 'Title', 'Status', 'Delivery', 'Priority', 'Effort']
-            : ['#', 'Title', 'Status', 'Priority', 'Effort'];
-        const rows = tasks.map((t) => hasDelivery
-            ? [t.display_number ?? t.task_number, t.title, t.status, t.delivery_status ?? '', t.priority, t.estimated_effort ?? '']
-            : [t.display_number ?? t.task_number, t.title, t.status, t.priority, t.estimated_effort ?? '']);
-        console.log(formatTable(headers, rows));
+        const workspaceScope = response.meta.scope === 'workspace';
+        console.log(workspaceScope
+            ? `Tasks (${response.meta.count}) — whole workspace${response.meta.workspace ? ` ${response.meta.workspace.slug}` : ''}, grouped by area:\n`
+            : `Tasks (${response.meta.count}):\n`);
+        if (!workspaceScope) {
+            console.log(renderTable(tasks));
+            return;
+        }
+        // The server already orders by area, so grouping is a fold over the rows, not a sort —
+        // whatever ordering the API applies inside an area is preserved as-is.
+        const groups = groupTasksByArea(tasks);
+        groups.forEach((group, index) => {
+            if (index > 0)
+                console.log('');
+            console.log(`── ${group.label} (${group.tasks.length}) ──`);
+            console.log(renderTable(group.tasks));
+        });
+        console.log("\nNarrow this down with --area <slug>, or run from inside that area's directory.");
     }
     catch (error) {
         printError(error, options.json);
         process.exitCode = 1;
     }
 }
+/**
+ * Rows folded into one group per area, in arrival order; area-less rows land in one bucket.
+ *
+ * The fold itself now lives in `area-grouping.ts`, shared with the issue/idea/vibe/document
+ * listings that grew the same need (TS-adanc8). This keeps the task-shaped result (`tasks`,
+ * not `rows`) that callers and tests already use.
+ */
+export function groupTasksByArea(tasks) {
+    return groupByArea(tasks).groups.map((group) => ({
+        label: group.label,
+        slug: group.slug,
+        tasks: group.rows,
+    }));
+}
+function renderTable(tasks) {
+    const hasDelivery = tasks.some((t) => t.delivery_status);
+    const headers = hasDelivery
+        ? ['#', 'Title', 'Status', 'Delivery', 'Priority', 'Effort']
+        : ['#', 'Title', 'Status', 'Priority', 'Effort'];
+    const rows = tasks.map((t) => hasDelivery
+        ? [t.display_number ?? t.task_number, t.title, t.status, t.delivery_status ?? '', t.priority, t.estimated_effort ?? '']
+        : [t.display_number ?? t.task_number, t.title, t.status, t.priority, t.estimated_effort ?? '']);
+    return formatTable(headers, rows);
+}
 //# sourceMappingURL=tasks.js.map

package/dist/commands/tasks.js.map

@@ -1 +1 @@
-{"version":3,"file":"tasks.js","sourceRoot":"","sources":["../../src/commands/tasks.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAsBrE,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,OAMlC;IACC,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,aAAa,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QACjD,MAAM,QAAQ,GAAG,CAAC,MAAM,MAAM,CAAC,QAAQ,CAAC;YACtC,MAAM,EAAE,OAAO,CAAC,MAAM;YACtB,QAAQ,EAAE,OAAO,CAAC,QAAQ;YAC1B,KAAK,EAAE,OAAO,CAAC,KAAK;SACrB,CAAC,CAAkB,CAAC;QAErB,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC;YACjB,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC,CAAC;YAC1C,OAAO;QACT,CAAC;QAED,MAAM,KAAK,GAAG,QAAQ,CAAC,IAAI,CAAC;QAE5B,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACvB,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC;YAC/B,OAAO;QACT,CAAC;QAED,OAAO,CAAC,GAAG,CAAC,UAAU,QAAQ,CAAC,IAAI,CAAC,KAAK,MAAM,CAAC,CAAC;QACjD,MAAM,WAAW,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC;QACzD,MAAM,OAAO,GAAG,WAAW;YACzB,CAAC,CAAC,CAAC,GAAG,EAAE,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,UAAU,EAAE,QAAQ,CAAC;YAC5D,CAAC,CAAC,CAAC,GAAG,EAAE,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,QAAQ,CAAC,CAAC;QACnD,MAAM,IAAI,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAC3B,WAAW;YACT,CAAC,CAAC,CAAC,CAAC,CAAC,cAAc,IAAI,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,eAAe,IAAI,EAAE,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,gBAAgB,IAAI,EAAE,CAAC;YACvH,CAAC,CAAC,CAAC,CAAC,CAAC,cAAc,IAAI,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,gBAAgB,IAAI,EAAE,CAAC,CACjG,CAAC;QACF,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC;IAC1C,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,UAAU,CAAC,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;QAChC,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;IACvB,CAAC;AACH,CAAC"}
+{"version":3,"file":"tasks.js","sourceRoot":"","sources":["../../src/commands/tasks.ts"],"names":[],"mappings":"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"}

package/dist/commands/vibes.d.ts

@@ -1,7 +1,9 @@
 export declare function vibeLogCommand(options: {
     json: boolean;
     area?: string;
-    content: string;
+    yes?: boolean;
+    /** Positional content, or the deprecated `--content` alias — resolved in `src/index.ts`. */
+    content?: string;
     type: string;
     title?: string;
     task?: string;

package/dist/commands/vibes.js

@@ -1,20 +1,34 @@
 import { createAdapter } from '../adapters/factory.js';
-import { formatOutput, printError, printSuccess, formatTable } from '../output.js';
-const VALID_VIBE_TYPES = ['note', 'code_change', 'decision', 'discovery', 'idea', 'exploration', 'fix'];
+import { confirmWriteTarget } from '../write-target.js';
+import { formatOutput, printError, printSuccess, formatTable, printValidationError } from '../output.js';
+import { printAreaGroups } from '../area-grouping.js';
+/**
+ * Vibe types this command will log. `Vibe::TYPES` also allows `idea`, but ideas have their
+ * own first-class command (`orbitmap idea add`) — logging one as a vibe buries it outside
+ * the idea backlog. Same narrowing as `log_work` in orbitmap-mcp. The full enum stays in
+ * the contract layer (`adapters/local/rules.ts`), which mirrors the API.
+ */
+const VALID_VIBE_TYPES = ['note', 'code_change', 'decision', 'discovery', 'exploration', 'fix'];
+/** Rejection message for a vibe type, redirecting `idea` to its own command. */
+function vibeTypeError(type) {
+    return type === 'idea'
+        ? 'Ideas are not tracked as vibes. Use `orbitmap idea add "…"` instead, or pick one of: ' +
+            `${VALID_VIBE_TYPES.join(', ')}.`
+        : `Invalid vibe type "${type}". Valid: ${VALID_VIBE_TYPES.join(', ')}`;
+}
 // ── Commands ──
 export async function vibeLogCommand(options) {
+    if (!options.content) {
+        printValidationError('Vibe content is required: `orbitmap vibe log "<content>" --type <type>`.', options.json);
+        return;
+    }
     if (!VALID_VIBE_TYPES.includes(options.type)) {
-        const msg = `Invalid vibe type "${options.type}". Valid: ${VALID_VIBE_TYPES.join(', ')}`;
-        if (options.json) {
-            console.error(JSON.stringify({ error: { message: msg } }));
-        }
-        else {
-            console.error(`Error: ${msg}`);
-        }
-        process.exitCode = 1;
+        const msg = vibeTypeError(options.type);
+        printValidationError(msg, options.json);
         return;
     }
     try {
+        await confirmWriteTarget('log vibe', options);
         const client = await createAdapter(options.area);
         const response = (await client.logVibe({
             content: options.content,
@@ -51,18 +65,25 @@ export async function vibeListCommand(options) {
             return;
         }
         console.log(`Vibes (${response.meta.count}):\n`);
-        console.log(formatTable(['Type', 'Title / Content', 'Author', 'Created'], vibes.map((v) => [
-            v.type,
-            v.title ?? v.content.slice(0, 60) + (v.content.length > 60 ? '...' : ''),
-            v.author ? (typeof v.author === 'object' ? v.author.name : v.author) : '',
-            v.created_at.replace('T', ' ').replace(/\+.*$/, ''),
-        ])));
+        printAreaGroups(vibes, renderVibeTable);
     }
     catch (error) {
         printError(error, options.json);
         process.exitCode = 1;
     }
 }
+/** `Number` leads, the way it does in `issue list` and `idea list` — it is what you act on. */
+function renderVibeTable(vibes) {
+    return formatTable(['Number', 'Type', 'Title / Content', 'Author', 'Created'], vibes.map((v) => [
+        // Fall back through the bare code to the uuid: `vibe show` accepts all three, so the
+        // column is never empty even against an older API that omits `display_number`.
+        v.display_number ?? (v.vibe_number ? `VB-${v.vibe_number}` : v.id),
+        v.type,
+        v.title ?? v.content.slice(0, 60) + (v.content.length > 60 ? '...' : ''),
+        v.author ? (typeof v.author === 'object' ? v.author.name : v.author) : '',
+        v.created_at.replace('T', ' ').replace(/\+.*$/, ''),
+    ]));
+}
 export async function vibeShowCommand(id, options) {
     try {
         const client = await createAdapter(options.area);
@@ -99,28 +120,17 @@ export async function vibeUpdateCommand(id, options) {
         }
         catch {
             const msg = 'Invalid JSON in --metadata option';
-            if (options.json) {
-                console.error(JSON.stringify({ error: { message: msg } }));
-            }
-            else {
-                console.error(`Error: ${msg}`);
-            }
-            process.exitCode = 1;
+            printValidationError(msg, options.json);
             return;
         }
     }
     if (options.type && !VALID_VIBE_TYPES.includes(options.type)) {
-        const msg = `Invalid vibe type "${options.type}". Valid: ${VALID_VIBE_TYPES.join(', ')}`;
-        if (options.json) {
-            console.error(JSON.stringify({ error: { message: msg } }));
-        }
-        else {
-            console.error(`Error: ${msg}`);
-        }
-        process.exitCode = 1;
+        const msg = vibeTypeError(options.type);
+        printValidationError(msg, options.json);
         return;
     }
     try {
+        await confirmWriteTarget('update vibe', options, 'existing');
         const client = await createAdapter(options.area);
         const response = (await client.updateVibe(id, {
             type: options.type,

package/dist/commands/vibes.js.map

@@ -1 +1 @@
-{"version":3,"file":"vibes.js","sourceRoot":"","sources":["../../src/commands/vibes.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAsDnF,MAAM,gBAAgB,GAAG,CAAC,MAAM,EAAE,aAAa,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,EAAE,aAAa,EAAE,KAAK,CAAC,CAAC;AAExG,iBAAiB;AAEjB,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,OAOC;IAED,IAAI,CAAC,gBAAgB,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QAC7C,MAAM,GAAG,GAAG,sBAAsB,OAAO,CAAC,IAAI,aAAa,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QACzF,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC;YACjB,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC,CAAC;QAC7D,CAAC;aAAM,CAAC;YACN,OAAO,CAAC,KAAK,CAAC,UAAU,GAAG,EAAE,CAAC,CAAC;QACjC,CAAC;QACD,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;QACrB,OAAO;IACT,CAAC;IAED,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,aAAa,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QACjD,MAAM,QAAQ,GAAG,CAAC,MAAM,MAAM,CAAC,OAAO,CAAC;YACrC,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,IAAI,EAAE,OAAO,CAAC,IAAI;YAClB,KAAK,EAAE,OAAO,CAAC,KAAK;YACpB,OAAO,EAAE,OAAO,CAAC,IAAI;SACtB,CAAC,CAAuB,CAAC;QAE1B,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC;YACjB,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC,CAAC;YAC1C,OAAO;QACT,CAAC;QAED,YAAY,CAAC,gBAAgB,QAAQ,CAAC,IAAI,CAAC,IAAI,aAAa,QAAQ,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC;IAC1F,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,UAAU,CAAC,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;QAChC,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;IACvB,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,OAMC;IAED,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,aAAa,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QACjD,MAAM,QAAQ,GAAG,CAAC,MAAM,MAAM,CAAC,SAAS,CAAC;YACvC,IAAI,EAAE,OAAO,CAAC,IAAI;YAClB,KAAK,EAAE,OAAO,CAAC,KAAK;YACpB,KAAK,EAAE,OAAO,CAAC,KAAK;SACrB,CAAC,CAAqB,CAAC;QAExB,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC;YACjB,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC,CAAC;YAC1C,OAAO;QACT,CAAC;QAED,MAAM,KAAK,GAAG,QAAQ,CAAC,IAAI,CAAC;QAE5B,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACvB,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC;YAC/B,OAAO;QACT,CAAC;QAED,OAAO,CAAC,GAAG,CAAC,UAAU,QAAQ,CAAC,IAAI,CAAC,KAAK,MAAM,CAAC,CAAC;QACjD,OAAO,CAAC,GAAG,CACT,WAAW,CACT,CAAC,MAAM,EAAE,iBAAiB,EAAE,QAAQ,EAAE,SAAS,CAAC,EAChD,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;YACf,CAAC,CAAC,IAAI;YACN,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;YACxE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE;YACzE,CAAC,CAAC,UAAU,CAAC,OAAO,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC;SACpD,CAAC,CACH,CACF,CAAC;IACJ,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,UAAU,CAAC,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;QAChC,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;IACvB,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,EAAU,EACV,OAAyC;IAEzC,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,aAAa,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QACjD,MAAM,QAAQ,GAAG,CAAC,MAAM,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC,CAAuB,CAAC;QAElE,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC;YACjB,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC,CAAC;YAC1C,OAAO;QACT,CAAC;QAED,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAC;QAC3B,OAAO,CAAC,GAAG,CAAC,SAAS,IAAI,CAAC,KAAK,IAAI,YAAY,KAAK,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC;QAClE,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YAChB,MAAM,UAAU,GAAG,OAAO,IAAI,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC;YACpF,OAAO,CAAC,GAAG,CAAC,WAAW,UAAU,EAAE,CAAC,CAAC;QACvC,CAAC;QACD,IAAI,IAAI,CAAC,OAAO;YAAE,OAAO,CAAC,GAAG,CAAC,SAAS,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC;QACvD,OAAO,CAAC,GAAG,CAAC,eAAe,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC;QAC3C,IAAI,IAAI,CAAC,QAAQ,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC3D,OAAO,CAAC,GAAG,CAAC,gBAAgB,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC;QACxE,CAAC;QACD,OAAO,CAAC,GAAG,CAAC,cAAc,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC;QACpF,OAAO,CAAC,GAAG,CAAC,YAAY,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC;IACpF,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,UAAU,CAAC,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;QAChC,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;IACvB,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,EAAU,EACV,OAOC;IAED,IAAI,QAA6C,CAAC;IAClD,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;QACrB,IAAI,CAAC;YACH,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QAC1C,CAAC;QAAC,MAAM,CAAC;YACP,MAAM,GAAG,GAAG,mCAAmC,CAAC;YAChD,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC;gBACjB,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC,CAAC;YAC7D,CAAC;iBAAM,CAAC;gBACN,OAAO,CAAC,KAAK,CAAC,UAAU,GAAG,EAAE,CAAC,CAAC;YACjC,CAAC;YACD,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;YACrB,OAAO;QACT,CAAC;IACH,CAAC;IAED,IAAI,OAAO,CAAC,IAAI,IAAI,CAAC,gBAAgB,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QAC7D,MAAM,GAAG,GAAG,sBAAsB,OAAO,CAAC,IAAI,aAAa,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QACzF,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC;YACjB,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC,CAAC;QAC7D,CAAC;aAAM,CAAC;YACN,OAAO,CAAC,KAAK,CAAC,UAAU,GAAG,EAAE,CAAC,CAAC;QACjC,CAAC;QACD,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;QACrB,OAAO;IACT,CAAC;IAED,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,aAAa,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QACjD,MAAM,QAAQ,GAAG,CAAC,MAAM,MAAM,CAAC,UAAU,CAAC,EAAE,EAAE;YAC5C,IAAI,EAAE,OAAO,CAAC,IAAI;YAClB,KAAK,EAAE,OAAO,CAAC,KAAK;YACpB,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,QAAQ;SACT,CAAC,CAAuB,CAAC;QAE1B,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC;YACjB,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC,CAAC;YAC1C,OAAO;QACT,CAAC;QAED,YAAY,CAAC,QAAQ,QAAQ,CAAC,IAAI,CAAC,EAAE,WAAW,EAAE,KAAK,CAAC,CAAC;IAC3D,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,UAAU,CAAC,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;QAChC,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;IACvB,CAAC;AACH,CAAC"}
+{"version":3,"file":"vibes.js","sourceRoot":"","sources":["../../src/commands/vibes.ts"],"names":[],"mappings":"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"}

package/dist/config.d.ts

@@ -21,6 +21,17 @@ export declare const CURRENT_SCHEMA_VERSION = 1;
 export declare const DEFAULT_API_HOST = "https://app.orbitmap.ai";
 /** Default Agent API base URL: {@link DEFAULT_API_HOST} + the `/api/agent` prefix. */
 export declare const DEFAULT_API_URL = "https://app.orbitmap.ai/api/agent";
+/**
+ * The Agent API base URL for this process: `ORBITMAP_API_URL` env → {@link DEFAULT_API_URL}.
+ *
+ * The single source of truth for "which host am I talking to", shared by {@link resolveAuth}
+ * and by `init`. They used to disagree: `init` hardcoded the default, so a non-interactive
+ * `init --key …` validated a dev key against production and failed with "Invalid API key"
+ * while every later command in the same shell happily used the dev host. There is
+ * deliberately no config-file override (ADR 0002) — a stale pinned host is worse than an
+ * env var the caller can see.
+ */
+export declare function resolveApiUrl(): string;
 /** Reset the once-per-process migration latch. Tests only. */
 export declare function resetConfigMigrationForTests(): void;
 /** Load `~/.orbitmap/config.json` (or the XDG/legacy equivalent). Runs the one-time

package/dist/config.js

@@ -20,6 +20,19 @@ const LEGACY_AGENT_PROFILE = 'default';
 export const DEFAULT_API_HOST = 'https://app.orbitmap.ai';
 /** Default Agent API base URL: {@link DEFAULT_API_HOST} + the `/api/agent` prefix. */
 export const DEFAULT_API_URL = `${DEFAULT_API_HOST}/api/agent`;
+/**
+ * The Agent API base URL for this process: `ORBITMAP_API_URL` env → {@link DEFAULT_API_URL}.
+ *
+ * The single source of truth for "which host am I talking to", shared by {@link resolveAuth}
+ * and by `init`. They used to disagree: `init` hardcoded the default, so a non-interactive
+ * `init --key …` validated a dev key against production and failed with "Invalid API key"
+ * while every later command in the same shell happily used the dev host. There is
+ * deliberately no config-file override (ADR 0002) — a stale pinned host is worse than an
+ * env var the caller can see.
+ */
+export function resolveApiUrl() {
+    return process.env['ORBITMAP_API_URL'] || DEFAULT_API_URL;
+}
 // ── Raw file I/O ────────────────────────────────────────────────────────────
 /** The file's JSON object exactly as written, or `undefined` when it is missing,
  *  unreadable or not a JSON object. Used to preserve keys this version does not know. */
@@ -197,7 +210,7 @@ export async function saveProjectConfig(config, dir = process.cwd()) {
 export async function resolveAuth(options = {}) {
     const cwd = options.cwd ?? process.cwd();
     const config = options.config ?? (await loadConfig());
-    const apiUrl = process.env['ORBITMAP_API_URL'] || DEFAULT_API_URL;
+    const apiUrl = resolveApiUrl();
     let apiKey = process.env['ORBITMAP_API_KEY'];
     if (!apiKey) {
         const agent = process.env['ORBITMAP_AGENT'] ||

package/dist/config.js.map

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

package/dist/doc-cache.d.ts

@@ -1,4 +1,25 @@
+/**
+ * The document cache — **one copy of a document per machine, globally** (IN-rwb5qu).
+ *
+ * Where that copy lives is resolved, not assumed:
+ *
+ * - **cloud mode** — `<project>/.orbitmap/docs/`, where `<project>` is the nearest ancestor
+ *   of the current directory that owns an `.orbitmap/` ({@link findProjectOrbitMapDir}).
+ * - **local mode** — `<workspace>/docs/`, the workspace's own documents directory. Those
+ *   files *are* the documents, so nothing here downloads over them, writes a manifest next
+ *   to them or cleans them up; that is what {@link DocCache.managed} distinguishes.
+ *
+ * For the ordinary in-project local workspace (`<project>/.orbitmap`) the two are literally
+ * the same path, which is the point: identical location and identical format in both modes.
+ * There are **no per-area subdirectories** — the data model does not record which area a
+ * document belongs to, so the directory tree must not pretend it does.
+ *
+ * This replaces a bare `join('.orbitmap', 'docs')` resolved against `process.cwd()` with no
+ * walk-up, which gave every subdirectory a command ran from its own private copy of every
+ * document.
+ */
 import type { WorkspaceAdapter } from './adapters/types.js';
+import { type ResolvedWorkspaceContext, type ResolveOptions } from './workspace-resolve.js';
 export interface ManifestEntry {
     doc_id: string;
     version: number;
@@ -14,9 +35,50 @@ export interface DownloadResult {
     cached: boolean;
     slug: string;
 }
-export declare function getCacheDir(): string;
-export declare function readManifest(): Manifest;
-export declare function writeManifest(manifest: Manifest): void;
+/** Where the one copy of every document lives for the current invocation. */
+export interface DocCache {
+    /** Absolute directory holding `<slug>.md`. */
+    dir: string;
+    /**
+     * True when the CLI **owns** this directory as a cache (cloud mode): downloads are written
+     * into it, `.manifest.json` tracks them, stale files may be deleted and the directory is
+     * gitignored.
+     *
+     * False in local mode, where the very same directory is the workspace's own `docs/` —
+     * domain data, meant to be committed. Every write path below is a no-op then: the document
+     * is already there, in the same format, and re-downloading it would replace a file that
+     * carries YAML frontmatter with a frontmatter-less copy of its body.
+     */
+    managed: boolean;
+    /** Project root whose `.gitignore` covers {@link DocCache.dir}. Only set when `managed`. */
+    gitignoreRoot?: string;
+}
+/**
+ * Resolve the doc cache for this invocation through the ordinary context ladder (so the
+ * mode, the workspace directory and every override behave exactly as they do everywhere
+ * else). Commands resolve it once and hand it to the functions below.
+ */
+export declare function resolveDocCache(options?: ResolveOptions): Promise<DocCache>;
+/** {@link resolveDocCache} for a context that is already resolved. */
+export declare function docCacheFor(context: Pick<ResolvedWorkspaceContext, 'mode' | 'workspacePath'>, cwd?: string): DocCache;
+/** Cached documents this CLI is tracking; always empty for an unmanaged (local) directory. */
+export declare function readManifest(cache: DocCache): Manifest;
+/** Persist the manifest; a no-op for an unmanaged (local) directory, which has none. */
+export declare function writeManifest(cache: DocCache, manifest: Manifest): void;
+/**
+ * Keep the doc cache out of git, in the `.gitignore` that actually covers it.
+ *
+ * Two things the old unconditional `ensureGitignore()` inside `downloadDocument` got wrong
+ * now that the cache is resolved rather than assumed:
+ *
+ * - it wrote into `process.cwd()`, which since the walk-up is no longer the project the cache
+ *   belongs to — the entries are relative to that project's root, so they must land in that
+ *   root's `.gitignore` or they ignore nothing;
+ * - it ran in local mode too, where `<workspace>/docs/` is domain data the user is meant to
+ *   commit. Ignoring it there would quietly drop the workspace's documents from the
+ *   repository, which is the opposite of what local mode is for.
+ */
+export declare function ensureDocCacheGitignore(cache: DocCache): string[];
 /**
  * Append any of `entries` missing from `<cwd>/.gitignore` (creating the file if needed) and
  * return the entries actually written.
@@ -38,7 +100,14 @@ export declare function ensureGitignore(entries?: string[], cwd?: string): strin
  * shadowing would be a false alarm.
  */
 export declare function gitignoreShadowsProjectConfig(cwd?: string): boolean;
-export declare function downloadDocument(client: WorkspaceAdapter, idOrSlug: string): Promise<DownloadResult>;
-export declare function cleanupCache(availableDocSlugs: string[]): {
+export declare function downloadDocument(client: WorkspaceAdapter, idOrSlug: string, cache: DocCache): Promise<DownloadResult>;
+/**
+ * Drop cached documents that are stale *and* no longer offered by the workspace.
+ *
+ * Never touches an unmanaged (local) directory: those files are the documents themselves,
+ * and a `.manifest.json` left behind there by a pre-v2 doc cache would otherwise name them
+ * as deletable. (The v1 → v2 migration removes that manifest; this is the second lock.)
+ */
+export declare function cleanupCache(availableDocSlugs: string[], cache: DocCache): {
     removed: string[];
 };

package/dist/doc-cache.js

@@ -1,13 +1,55 @@
+/**
+ * The document cache — **one copy of a document per machine, globally** (IN-rwb5qu).
+ *
+ * Where that copy lives is resolved, not assumed:
+ *
+ * - **cloud mode** — `<project>/.orbitmap/docs/`, where `<project>` is the nearest ancestor
+ *   of the current directory that owns an `.orbitmap/` ({@link findProjectOrbitMapDir}).
+ * - **local mode** — `<workspace>/docs/`, the workspace's own documents directory. Those
+ *   files *are* the documents, so nothing here downloads over them, writes a manifest next
+ *   to them or cleans them up; that is what {@link DocCache.managed} distinguishes.
+ *
+ * For the ordinary in-project local workspace (`<project>/.orbitmap`) the two are literally
+ * the same path, which is the point: identical location and identical format in both modes.
+ * There are **no per-area subdirectories** — the data model does not record which area a
+ * document belongs to, so the directory tree must not pretend it does.
+ *
+ * This replaces a bare `join('.orbitmap', 'docs')` resolved against `process.cwd()` with no
+ * walk-up, which gave every subdirectory a command ran from its own private copy of every
+ * document.
+ */
 import { existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync, statSync } from 'node:fs';
-import { join, dirname } from 'node:path';
-const CACHE_DIR = join('.orbitmap', 'docs');
-const MANIFEST_FILE = '.manifest.json';
+import { join, dirname, resolve } from 'node:path';
+import { DOCS_DIR, DOC_CACHE_MANIFEST, ORBITMAP_DIR, findProjectOrbitMapDir, } from './paths.js';
+import { LINK_FILE, resolveWorkspaceContext, } from './workspace-resolve.js';
 const STALE_DAYS = 7;
-export function getCacheDir() {
-    return CACHE_DIR;
+/**
+ * Resolve the doc cache for this invocation through the ordinary context ladder (so the
+ * mode, the workspace directory and every override behave exactly as they do everywhere
+ * else). Commands resolve it once and hand it to the functions below.
+ */
+export async function resolveDocCache(options = {}) {
+    const context = await resolveWorkspaceContext(options);
+    return docCacheFor(context, options.cwd);
+}
+/** {@link resolveDocCache} for a context that is already resolved. */
+export function docCacheFor(context, cwd = process.cwd()) {
+    if (context.mode === 'local' && context.workspacePath) {
+        return { dir: join(context.workspacePath, DOCS_DIR), managed: false };
+    }
+    const start = resolve(cwd);
+    const root = findProjectOrbitMapDir(start) ?? start;
+    return {
+        dir: join(root, ORBITMAP_DIR, DOCS_DIR),
+        managed: true,
+        gitignoreRoot: root,
+    };
 }
-export function readManifest() {
-    const manifestPath = join(CACHE_DIR, MANIFEST_FILE);
+/** Cached documents this CLI is tracking; always empty for an unmanaged (local) directory. */
+export function readManifest(cache) {
+    if (!cache.managed)
+        return {};
+    const manifestPath = join(cache.dir, DOC_CACHE_MANIFEST);
     if (!existsSync(manifestPath))
         return {};
     try {
@@ -17,8 +59,11 @@ export function readManifest() {
         return {};
     }
 }
-export function writeManifest(manifest) {
-    const manifestPath = join(CACHE_DIR, MANIFEST_FILE);
+/** Persist the manifest; a no-op for an unmanaged (local) directory, which has none. */
+export function writeManifest(cache, manifest) {
+    if (!cache.managed)
+        return;
+    const manifestPath = join(cache.dir, DOC_CACHE_MANIFEST);
     mkdirSync(dirname(manifestPath), { recursive: true });
     writeFileSync(manifestPath, JSON.stringify(manifest, null, 2), 'utf-8');
 }
@@ -28,7 +73,28 @@ export function writeManifest(manifest) {
  * — `<project>/.orbitmap/config.json` (ADR 0002) lives in the same directory and is meant
  * to be committed, so ignoring the whole directory would silently swallow it.
  */
-const DEFAULT_GITIGNORE_ENTRIES = ['.orbitmap/docs/', '.orbitmap/link.json'];
+const DEFAULT_GITIGNORE_ENTRIES = [
+    `${ORBITMAP_DIR}/${DOCS_DIR}/`,
+    `${ORBITMAP_DIR}/${LINK_FILE}`,
+];
+/**
+ * Keep the doc cache out of git, in the `.gitignore` that actually covers it.
+ *
+ * Two things the old unconditional `ensureGitignore()` inside `downloadDocument` got wrong
+ * now that the cache is resolved rather than assumed:
+ *
+ * - it wrote into `process.cwd()`, which since the walk-up is no longer the project the cache
+ *   belongs to — the entries are relative to that project's root, so they must land in that
+ *   root's `.gitignore` or they ignore nothing;
+ * - it ran in local mode too, where `<workspace>/docs/` is domain data the user is meant to
+ *   commit. Ignoring it there would quietly drop the workspace's documents from the
+ *   repository, which is the opposite of what local mode is for.
+ */
+export function ensureDocCacheGitignore(cache) {
+    if (!cache.managed || !cache.gitignoreRoot)
+        return [];
+    return ensureGitignore(DEFAULT_GITIGNORE_ENTRIES, cache.gitignoreRoot);
+}
 /**
  * Append any of `entries` missing from `<cwd>/.gitignore` (creating the file if needed) and
  * return the entries actually written.
@@ -96,26 +162,35 @@ function normalizeGitignoreLine(line) {
     const withoutComment = line.replace(/(?:^|\s)#.*$/, '');
     return withoutComment.trim();
 }
-export async function downloadDocument(client, idOrSlug) {
+export async function downloadDocument(client, idOrSlug, cache) {
     const response = (await client.getDocument(idOrSlug, 'file'));
     const doc = response.data;
     const slug = doc.slug;
-    const manifest = readManifest();
+    // Local mode: the workspace file the adapter just read *is* the copy. Nothing to download,
+    // nothing to record — and nothing may be written over it (see `DocCache.managed`).
+    if (!cache.managed) {
+        const filePath = join(cache.dir, `${slug}.md`);
+        if (!existsSync(filePath)) {
+            throw new Error(`Document ${slug} is not stored in this workspace (${filePath}).`);
+        }
+        return { filePath, version: doc.version, cached: true, slug };
+    }
+    const manifest = readManifest(cache);
     const existing = manifest[slug];
     // Version match — skip download
     if (existing && existing.version === doc.version) {
-        const filePath = join(CACHE_DIR, existing.file);
+        const filePath = join(cache.dir, existing.file);
         if (existsSync(filePath)) {
             existing.last_accessed = new Date().toISOString();
-            writeManifest(manifest);
+            writeManifest(cache, manifest);
             return { filePath, version: doc.version, cached: true, slug };
         }
     }
     // Need to download
-    mkdirSync(CACHE_DIR, { recursive: true });
-    ensureGitignore();
+    mkdirSync(cache.dir, { recursive: true });
+    ensureDocCacheGitignore(cache);
     const fileName = `${slug}.md`;
-    const filePath = join(CACHE_DIR, fileName);
+    const filePath = join(cache.dir, fileName);
     if (doc.download_url) {
         const res = await fetch(doc.download_url);
         if (!res.ok) {
@@ -141,11 +216,20 @@ export async function downloadDocument(client, idOrSlug) {
         size_bytes: size,
         file: fileName,
     };
-    writeManifest(manifest);
+    writeManifest(cache, manifest);
     return { filePath, version: doc.version, cached: false, slug };
 }
-export function cleanupCache(availableDocSlugs) {
-    const manifest = readManifest();
+/**
+ * Drop cached documents that are stale *and* no longer offered by the workspace.
+ *
+ * Never touches an unmanaged (local) directory: those files are the documents themselves,
+ * and a `.manifest.json` left behind there by a pre-v2 doc cache would otherwise name them
+ * as deletable. (The v1 → v2 migration removes that manifest; this is the second lock.)
+ */
+export function cleanupCache(availableDocSlugs, cache) {
+    if (!cache.managed)
+        return { removed: [] };
+    const manifest = readManifest(cache);
     const slugSet = new Set(availableDocSlugs);
     const now = Date.now();
     const staleMs = STALE_DAYS * 24 * 60 * 60 * 1000;
@@ -157,7 +241,7 @@ export function cleanupCache(availableDocSlugs) {
         if (now - lastAccessed <= staleMs)
             continue;
         // Stale and not in available docs — remove
-        const filePath = join(CACHE_DIR, entry.file);
+        const filePath = join(cache.dir, entry.file);
         try {
             if (existsSync(filePath))
                 unlinkSync(filePath);
@@ -169,7 +253,7 @@ export function cleanupCache(availableDocSlugs) {
         removed.push(slug);
     }
     if (removed.length > 0) {
-        writeManifest(manifest);
+        writeManifest(cache, manifest);
     }
     return { removed };
 }