orbitmap 0.6.0 → 0.8.0

package/dist/adapters/types.d.ts

@@ -7,6 +7,20 @@
  * command modules, never by the adapter.
  */
 import type { WorkLogEntry } from '../work-log.js';
+/**
+ * Where a new idea lands — the `scope` field of `POST /ideas` (API 10.6.0).
+ *
+ * - `'area'` — the idea belongs to the area the invocation is scoped to (the
+ *   `X-Orbitmap-Area` header in cloud mode, the `areas/<slug>/` subtree in local mode).
+ * - `'workspace'` — the idea belongs to the workspace and is linked to no area.
+ *
+ * The CLI always sends it. The server's own ladder (`scope=workspace` → body `area_id` →
+ * `X-Orbitmap-Area` → no area context at all) would resolve an omitted `scope` from the
+ * ambient header, which is exactly the guess this field exists to remove: from the
+ * workspace root the CLI means "workspace level", and it has to say so rather than let a
+ * default decide.
+ */
+export type IdeaScope = 'workspace' | 'area';
 export interface WorkspaceAdapter {
     /**
      * `GET /context` — since API 10.0.0 this is MATCHING MATERIAL, not a work queue:
@@ -76,6 +90,7 @@ export interface WorkspaceAdapter {
         area_id?: string;
         source_issue_id?: string;
         intent_id?: string;
+        mission_id?: string;
         orbit_id?: string | null;
     }): Promise<unknown>;
     editTaskContent(taskId: string, data: {
@@ -131,7 +146,13 @@ export interface WorkspaceAdapter {
         workspace_id?: string;
     }): Promise<unknown>;
     updateDocument(idOrSlug: string, content: string, changelog?: string): Promise<unknown>;
-    patchDocument(idOrSlug: string, operations: Array<Record<string, unknown>>, baseVersion: number, changelog?: string): Promise<unknown>;
+    patchDocument(idOrSlug: string, operations: Array<Record<string, unknown>>, baseVersion: number, changelog?: string, 
+    /**
+     * Compute the patch server-side and report the section boundaries it would touch
+     * WITHOUT writing (`dry_run` in the PATCH body, API 10.9.0). The response then carries
+     * `dry_run: true`, an `operations` array and the CURRENT (unchanged) version.
+     */
+    dryRun?: boolean): Promise<unknown>;
     requestUploadUrl(data: {
         title: string;
         type: string;
@@ -262,11 +283,16 @@ export interface WorkspaceAdapter {
     }): Promise<unknown>;
     /** `GET /ideas/{id_or_number}` — uuid, bare code or `ID-xxxxxx`; the server resolves it. */
     getIdea(idOrNumber: string): Promise<unknown>;
+    /**
+     * `POST /ideas`. {@link IdeaScope} is sent EXPLICITLY on every call — see its doc for why
+     * a server-side default is not good enough.
+     */
     createIdea(data: {
         content: string;
         title?: string;
         priority?: string;
         metadata?: Record<string, unknown>;
+        scope?: IdeaScope;
     }): Promise<unknown>;
     /** `PATCH /ideas/{id_or_number}/status`. */
     updateIdeaStatus(idOrNumber: string, data: {
@@ -332,6 +358,11 @@ export interface WorkspaceAdapter {
         bundle?: boolean;
         slim?: boolean;
     }): Promise<unknown>;
+    /**
+     * `area_ids` on create declares the intent's areas from the start, exactly as on
+     * {@link WorkspaceAdapter.updateIntent} — each entry a slug or uuid, written to the
+     * `intent_area` pivot. Distinct from `area_id`, which only derives workspace context.
+     */
     createIntent(data: {
         name: string;
         outcome?: string;
@@ -339,6 +370,7 @@ export interface WorkspaceAdapter {
         plan?: string;
         status?: string;
         area_id?: string;
+        area_ids?: string[];
     }): Promise<unknown>;
     /**
      * `logs` is the status-transition batch: entries written verbatim, in order, inside the
@@ -356,6 +388,12 @@ export interface WorkspaceAdapter {
         status?: string;
         area_ids?: string[];
         logs?: WorkLogEntry[];
+        /**
+         * Answer to the INTENT_CLOSE_OPEN_ITEMS refusal (API 10.8.0): how a close to
+         * done/cancelled should treat still-open child items. Cloud-only semantics —
+         * the local adapter performs no open-children refusal, so it ignores the flag.
+         */
+        close_with_open_items?: 'relocate' | 'cancel' | 'force';
     }): Promise<unknown>;
     linkIntentItem(idOrNumber: string, data: {
         item_type: string;

package/dist/agent-instructions.d.ts

@@ -32,21 +32,24 @@ export declare const SKILL_NAME = "orbitmap";
 export declare const SESSION_FOCUS_SECTION = "## Session focus\n\nSESSION FOCUS \u2014 Ensure, don't call. A session focus file ({mission, intents (\u22643 typical \u2014\na SOFT cap: focus holds what the session is actively advancing), areas, agent_id,\nmatched_at}) lives in your session temp directory. If present and the agent identity\nmatches: do NOT call context. If missing or invalid \u2014 an identity or area mismatch\ninvalidates it \u2014 call `orbitmap context` once, match the conversation against its\nhandles, write the file, and STATE the match in one line \u2014 the intent's NAME, its number\nonly at first mention. Never narrow silently: every task query you send still carries\n`--intent` explicitly. An intent you just created or fetched joins the focus by its\nhandle \u2014 no context call. If a write fails INTENT_CLOSED: your focus is stale \u2014 re-derive\nand say so. Before creating a new intent or declaring none exists: fetch the 1\u20133 nearest\ncandidates with `intent show --no-logs` and judge from their bodies, not TL;DRs \u2014 a rule\nfor creation/dedup decision points only. If nothing matches: offer to frame an intent\n(brainstorm gate) \u2014 never create a bare shell; if declined, work from the fetched missions\nand intents (\"look wider\").\n\nTRANSIENT references never enter focus: an intent fetched for a dedup check or a\ncross-comparison is read and used, not focused; a real focus switch is stated aloud\n(\"focus now X, parking Y\"). The file is an optimization with graceful failure \u2014 the\nconversation is the primary carrier, the file only compaction insurance: no file \u2192 the\nensure rule above triggers one context call. Agent memory directories are the WRONG store\nfor focus (a cross-session lifetime means stale focus).";
 export declare const FRESHNESS_SECTION = "## Freshness\n\nTwo universal rules \u2014 they apply to EVERY OrbitMap object, in every flow:\n- TRUST THE WRITE'S ECHO. A successful write already returns the updated object \u2014 the\n  echo IS the current state. Never re-fetch an object just to verify a write you made.\n- COMPARE THE HELD MARKER BEFORE RE-FETCHING ANYTHING BIG. Every full fetch hands you a\n  change marker \u2014 the `updated_at` + `last_log_id` pair on intents (tasks and missions\n  carry the pair too), `version` on documents. Hold it; re-fetch only on a mismatch.\n\nPROBE FLOW (intents): the session focus file remembers each focused intent's\n`updated_at` + `last_log_id` pair from the last FULL fetch. To check whether an\nintent moved, run `orbitmap intent show IN-x --slim` \u2014 a ~150-token probe (handle,\nTL;DRs, areas, mission, task counts, the pair). Pair unchanged \u2192 the intent has not\nmoved: SAY SO in one line and keep working from what you hold \u2014 no full fetch. Pair\nchanged \u2192 re-fetch (`intent show IN-x`, with `--no-logs` when the log tail is not\nneeded) and remember the new pair in the focus file.";
 export declare function worklogKeepDropTest(indent?: string): string;
-export declare const SKILL_ORBITMAP_FRONTMATTER = "---\nname: orbitmap\ndescription: >\n  OrbitMap project management via the orbitmap CLI. Use when the user mentions OrbitMap,\n  orbit, tasks, backlog, missions, intents, ideas, issues, vibes, or asks to track,\n  plan, or log work. Entry point: object model, context resolution, command reference.\n---";
-export declare const SKILL_ORBITMAP_BODY = "# OrbitMap CLI \u2014 core\n\nOrbitMap is an agentic project management platform. You interact with it exclusively\nthrough the `orbitmap` CLI (run with `npx orbitmap \u2026` if not on PATH). The CLI works\nidentically in cloud mode and local-files mode \u2014 never assume which one is active, and\nnever read or write the workspace's data files directly. The CLI is the only interface.\n\n## Goal\nOperate OrbitMap correctly: ensure session focus (below) instead of ritually calling\ncontext, act on the mission and intents the session is about, write every item to the area\nthe work belongs to, and go through the CLI only \u2014 never the data files.\n\n**Interface:** every action below is an OrbitMap operation \u2014 run the `orbitmap` CLI command\nshown, or its equivalent MCP tool when this session uses MCP; `orbitmap <cmd> --help` and the\nMCP tool schemas are the authority. Never edit the workspace data files directly.\n\n## General behaviour\n- Always prioritise the user's direct request. If the user asks you to do something\n  (read a file, write code, answer a question), handle that first.\n- Only interact with OrbitMap when the user explicitly asks you to (e.g. \"check my\n  tasks\", \"start a task\", \"what's on my backlog\", \"log this idea\").\n- When the user mentions OrbitMap, orbit, task, backlog, or project-management concepts\n  in the context of tracking work, use `orbitmap` commands to handle the request.\n\n## Object model\n- Workspace = team level. Area = repo-level scope (formerly Project) \u2014 tasks, vibes and\n  most issues live in an area. Mission (MS-) = time-boxed workspace focus; at most one\n  active. Intent (IN-) = workspace-level goal grouping tasks/issues. Idea (ID-) = future\n  possibility, not a problem. Issue (IS-) = problem/bug. Vibe (VB-) = ad-hoc work log\n  outside a task. Task (TS-) = unit of work.\n- Entity numbers (TS-xxxxxx etc.) are accepted by every command that takes an id.\n\n## Session focus\n\nSESSION FOCUS \u2014 Ensure, don't call. A session focus file ({mission, intents (\u22643 typical \u2014\na SOFT cap: focus holds what the session is actively advancing), areas, agent_id,\nmatched_at}) lives in your session temp directory. If present and the agent identity\nmatches: do NOT call context. If missing or invalid \u2014 an identity or area mismatch\ninvalidates it \u2014 call `orbitmap context` once, match the conversation against its\nhandles, write the file, and STATE the match in one line \u2014 the intent's NAME, its number\nonly at first mention. Never narrow silently: every task query you send still carries\n`--intent` explicitly. An intent you just created or fetched joins the focus by its\nhandle \u2014 no context call. If a write fails INTENT_CLOSED: your focus is stale \u2014 re-derive\nand say so. Before creating a new intent or declaring none exists: fetch the 1\u20133 nearest\ncandidates with `intent show --no-logs` and judge from their bodies, not TL;DRs \u2014 a rule\nfor creation/dedup decision points only. If nothing matches: offer to frame an intent\n(brainstorm gate) \u2014 never create a bare shell; if declined, work from the fetched missions\nand intents (\"look wider\").\n\nTRANSIENT references never enter focus: an intent fetched for a dedup check or a\ncross-comparison is read and used, not focused; a real focus switch is stated aloud\n(\"focus now X, parking Y\"). The file is an optimization with graceful failure \u2014 the\nconversation is the primary carrier, the file only compaction insurance: no file \u2192 the\nensure rule above triggers one context call. Agent memory directories are the WRONG store\nfor focus (a cross-session lifetime means stale focus).\n\n## Freshness\n\nTwo universal rules \u2014 they apply to EVERY OrbitMap object, in every flow:\n- TRUST THE WRITE'S ECHO. A successful write already returns the updated object \u2014 the\n  echo IS the current state. Never re-fetch an object just to verify a write you made.\n- COMPARE THE HELD MARKER BEFORE RE-FETCHING ANYTHING BIG. Every full fetch hands you a\n  change marker \u2014 the `updated_at` + `last_log_id` pair on intents (tasks and missions\n  carry the pair too), `version` on documents. Hold it; re-fetch only on a mismatch.\n\nPROBE FLOW (intents): the session focus file remembers each focused intent's\n`updated_at` + `last_log_id` pair from the last FULL fetch. To check whether an\nintent moved, run `orbitmap intent show IN-x --slim` \u2014 a ~150-token probe (handle,\nTL;DRs, areas, mission, task counts, the pair). Pair unchanged \u2192 the intent has not\nmoved: SAY SO in one line and keep working from what you hold \u2014 no full fetch. Pair\nchanged \u2192 re-fetch (`intent show IN-x`, with `--no-logs` when the log tail is not\nneeded) and remember the new pair in the focus file.\n\n## Context\n- Ensure session focus (above) \u2014 at most ONE `orbitmap context` call per session, and none\n  while a valid focus file is held. `orbitmap context` is authoritative MATCHING MATERIAL:\n  your agent identity, the missions and intents as handles with TL;DR summaries, standalone\n  mission workitems, the areas you work in, and document metadata. It carries no task\n  lists and no bodies \u2014 fetch deeper on demand (`orbitmap intent show IN-x`,\n  `orbitmap tasks --intent IN-x`, `orbitmap doc <slug>`). Never list areas and never\n  ask the user \"which area?\" before you have read it.\n- You work in a WORKSPACE, not inside a single area. Missions, intents\n  and documents are workspace-level and take no area \u2014 a document is exactly ONE copy,\n  global to the workspace, never per-area. Tasks, vibes, issues and ideas are\n  AREA-scoped.\n- Missions and intents outrank individual tasks. Asked to work on \"what matters\", take the\n  active mission and open intents from context and pick work that serves them.\n- The area follows from the directory, never from a question to the user:\n  `.orbitmap/config.json` maps directories \u2192 area slugs at the workspace root, and each\n  area directory carries its own `.orbitmap/config.json` marker naming its area. That\n  config is the only source of truth \u2014 never hard-code area names anywhere.\n  So: do area-scoped work from the directory it belongs to and let the CLI resolve it.\n- `--area <slug>` is an OVERRIDE for a single call, not part of normal usage \u2014 reach for it\n  only to read or write outside the area the current directory resolves to.\n- If a command fails with `AREA_CONTEXT_REQUIRED`, its details list the mapped\n  directories: cd into the right one, or retry with `--area <slug>`.\n- WRITES: the resolved area is a default for *reading*, never a statement of where the\n  work belongs. Before creating anything area-scoped (task, subtask, issue, vibe),\n  derive the target area from the work itself (which repo/package it lives in) and pass\n  `--area <slug>` if that differs from the area the CLI echoes. If the work itself is\n  genuinely ambiguous, ASK THE USER; do not guess. There is no\n  `move` command: a write in the wrong area has to be recreated.\n- Every write echoes its scope on stderr: `creates in area <slug> (source: \u2026)` when it\n  creates an object, `scoped to area <slug> (source: \u2026)` when it changes one by id. A\n  `source` of `global ~/.orbitmap/config.json` is a machine-wide leftover that nothing\n  here chose \u2014 treat it as unconfirmed and pass `--area` explicitly.\n\n## Task or intent?\n\nAn intent earns its gates when the work carries knowledge someone would otherwise\nre-derive or re-litigate: a decision with a rejected alternative, a design that outlives\nthe change, a constraint worth recording. Work with none of that \u2014 a typo, a copy tweak,\nan obvious one-file fix \u2014 is a task: create it, do it, log it, done. The same test the\nwork log uses for what to write down. If a \"small\" fix turns out to hide a real decision,\nstop and frame it; discovering that mid-change is normal, not a failure.\n\n## Task statuses\nbacklog, todo, in_progress, in_review, review_changes, done, blocked.\n`orbitmap tasks` defaults to todo,in_progress. Ask for others explicitly, e.g.\n`orbitmap tasks --status backlog` when the user asks about the backlog.\n\n## Listing tasks\n- A list spans EVERY area you can reach and EVERY assignee \u2014 nothing narrows it to the\n  current directory or to you. It is capped at 30 rows with the totals behind the cap\n  printed, and every list states the filters that produced it. Read that line before you\n  answer from a list.\n- While you are executing an intent, EVERY task query carries `--intent IN-x`. Nothing\n  narrows a list to an intent on your behalf: a bare `orbitmap tasks` is you having\n  deliberately left the intent to look at the whole workspace.\n- `orbitmap intent show IN-x` already carries the intent's own tasks, so intent lifecycle\n  work needs no filter at all. `orbitmap tasks --intent IN-x` is the escape hatch for the\n  times you want the task-list shape \u2014 statuses, assignees, the filter line \u2014 instead.\n\n## Command reference (all commands accept --json)\n- Context: `orbitmap context` (once per session at most \u2014 see Session focus),\n  `orbitmap overview`, `orbitmap areas`\n  (rarely needed \u2014 context already lists the areas you work in)\n- Tasks: `orbitmap tasks [--status s1,s2] [--intent IN-x]`, `orbitmap task TS-x`,\n  `orbitmap get <ID>`,\n  `orbitmap start [TS-x]`, `orbitmap status TS-x <status> [--delivery <d>]`,\n  `orbitmap create \"title\" [--intent IN-x|--mission MS-x] [--priority p]`,\n  `orbitmap subtask TS-parent \"title\"`, `orbitmap assign TS-x [agent]`,\n  `orbitmap dep add|remove TS-a TS-b`, `orbitmap log TS-x \"msg\" --type <t>`\n- Issues: `orbitmap issue register|list|show|status|resolve`\n- Ideas: `orbitmap idea add|list|show|status`\n- Vibes: `orbitmap vibe log|list|show`\n- Missions: `orbitmap mission list|show|create|update|status|link|unlink`\n- Intents: `orbitmap intent list|show|create|update|link|unlink`\n  (`show` embeds the context bundle \u2014 `--no-bundle` strips it, `--slim` is the\n  freshness probe, `--no-logs` skips the log tail)\n- Documents: `orbitmap docs`, `orbitmap doc <slug> [--section \"## H\"|--full]`,\n  `orbitmap doc-import`, `orbitmap doc-update`\n\n## Error handling\n- If OrbitMap is unreachable (network down / workspace directory unavailable), inform\n  the user and continue the primary work without logging. Do NOT retry failed orbitmap\n  calls in a loop \u2014 report the issue and proceed with the task.";
-export declare const SKILL_EXECUTE_FRONTMATTER = "---\nname: orbitmap-execute\ndescription: >\n  Executing OrbitMap work \u2014 the fourth gate of the product-building flow. Two flows:\n  \"execute IN-x\" delivers a whole planned intent in the background (parallel worker\n  waves, per-task tests, the intent test, an impact pass against a baseline, a\n  goal-based fix loop, everything ending in_review on an intent branch \u2014 merging stays\n  the user's), and \"work on TS-x\" runs a single tracked task (starting/resuming,\n  logging, finishing with the correct status, git branches and delivery status). Use\n  whenever executing a planned intent or implementing, resuming, or finishing a\n  tracked task.\n---";
+export declare const SKILL_ORBITMAP_FRONTMATTER = "---\nname: orbitmap\ndescription: >\n  OrbitMap project management via the orbitmap CLI \u2014 the entry point other orbitmap-*\n  skills require. Use whenever the user wants to build, add, change or fix something, in\n  whatever words they use \u2014 do not wait for OrbitMap vocabulary \u2014 as well as when they\n  mention OrbitMap, orbit, tasks, backlog, missions, intents, ideas, issues, vibes, or ask\n  to track, plan, or log work. Covers the object model, context resolution, and command\n  reference.\n---";
+export declare const SKILL_ORBITMAP_BODY = "# OrbitMap CLI \u2014 core\n\nOrbitMap is an agentic project management platform. You interact with it exclusively\nthrough the `orbitmap` CLI (run with `npx orbitmap \u2026` if not on PATH). The CLI works\nidentically in cloud mode and local-files mode \u2014 never assume which one is active, and\nnever read or write the workspace's data files directly. The CLI is the only interface.\n\n## Goal\nOperate OrbitMap correctly: ensure session focus (below) instead of ritually calling\ncontext, act on the mission and intents the session is about, write every item to the area\nthe work belongs to, and go through the CLI only \u2014 never the data files.\n\n**Interface:** every action below is an OrbitMap operation \u2014 run the `orbitmap` CLI command\nshown, or its equivalent MCP tool when this session uses MCP; `orbitmap <cmd> --help` and the\nMCP tool schemas are the authority. Never edit the workspace data files directly.\n\n## General behaviour\n- Always prioritise the user's direct request. If the user asks you to do something\n  (read a file, write code, answer a question), handle that first.\n- When the user mentions OrbitMap, orbit, task, backlog, or project-management concepts\n  in the context of tracking work \u2014 in whatever words they use \u2014 use `orbitmap` commands\n  to handle the request.\n\n## Object model\n- Workspace = team level. Area = repo-level scope (formerly Project) \u2014 tasks, vibes and\n  most issues live in an area. Mission (MS-) = time-boxed workspace focus; at most one\n  active. Intent (IN-) = workspace-level goal grouping tasks/issues. Idea (ID-) = future\n  possibility, not a problem. Issue (IS-) = problem/bug. Vibe (VB-) = ad-hoc work log\n  outside a task. Task (TS-) = unit of work.\n- Entity numbers (TS-xxxxxx etc.) are accepted by every command that takes an id.\n\n## Naming workitems in output\nRefer to a workitem by its NAME together with its key, at first mention in any message,\nsummary or report \u2014 \"Align skills and validators (IN-b2h63q)\". NEVER a bare key: a key\nalone is unreadable to the user, who tracks the work by name. Keep no key-to-name mapping\nanywhere \u2014 not in a file, not in memory. Every list, `show` and context response already\npairs the two, so take the name from the response you already have; if you do not have it,\nfetch the item rather than emitting the key on its own.\n\n## Session focus\n\nSESSION FOCUS \u2014 Ensure, don't call. A session focus file ({mission, intents (\u22643 typical \u2014\na SOFT cap: focus holds what the session is actively advancing), areas, agent_id,\nmatched_at}) lives in your session temp directory. If present and the agent identity\nmatches: do NOT call context. If missing or invalid \u2014 an identity or area mismatch\ninvalidates it \u2014 call `orbitmap context` once, match the conversation against its\nhandles, write the file, and STATE the match in one line \u2014 the intent's NAME, its number\nonly at first mention. Never narrow silently: every task query you send still carries\n`--intent` explicitly. An intent you just created or fetched joins the focus by its\nhandle \u2014 no context call. If a write fails INTENT_CLOSED: your focus is stale \u2014 re-derive\nand say so. Before creating a new intent or declaring none exists: fetch the 1\u20133 nearest\ncandidates with `intent show --no-logs` and judge from their bodies, not TL;DRs \u2014 a rule\nfor creation/dedup decision points only. If nothing matches: offer to frame an intent\n(brainstorm gate) \u2014 never create a bare shell; if declined, work from the fetched missions\nand intents (\"look wider\").\n\nTRANSIENT references never enter focus: an intent fetched for a dedup check or a\ncross-comparison is read and used, not focused; a real focus switch is stated aloud\n(\"focus now X, parking Y\"). The file is an optimization with graceful failure \u2014 the\nconversation is the primary carrier, the file only compaction insurance: no file \u2192 the\nensure rule above triggers one context call. Agent memory directories are the WRONG store\nfor focus (a cross-session lifetime means stale focus).\n\n## Freshness\n\nTwo universal rules \u2014 they apply to EVERY OrbitMap object, in every flow:\n- TRUST THE WRITE'S ECHO. A successful write already returns the updated object \u2014 the\n  echo IS the current state. Never re-fetch an object just to verify a write you made.\n- COMPARE THE HELD MARKER BEFORE RE-FETCHING ANYTHING BIG. Every full fetch hands you a\n  change marker \u2014 the `updated_at` + `last_log_id` pair on intents (tasks and missions\n  carry the pair too), `version` on documents. Hold it; re-fetch only on a mismatch.\n\nPROBE FLOW (intents): the session focus file remembers each focused intent's\n`updated_at` + `last_log_id` pair from the last FULL fetch. To check whether an\nintent moved, run `orbitmap intent show IN-x --slim` \u2014 a ~150-token probe (handle,\nTL;DRs, areas, mission, task counts, the pair). Pair unchanged \u2192 the intent has not\nmoved: SAY SO in one line and keep working from what you hold \u2014 no full fetch. Pair\nchanged \u2192 re-fetch (`intent show IN-x`, with `--no-logs` when the log tail is not\nneeded) and remember the new pair in the focus file.\n\n## Context\n- Ensure session focus (above) \u2014 at most ONE `orbitmap context` call per session, and none\n  while a valid focus file is held. `orbitmap context` is authoritative MATCHING MATERIAL:\n  your agent identity, the missions and intents as handles with TL;DR summaries, standalone\n  mission workitems, the areas you work in, and document metadata. It carries no task\n  lists and no bodies \u2014 fetch deeper on demand (`orbitmap intent show IN-x`,\n  `orbitmap tasks --intent IN-x`, `orbitmap doc <slug>`). Never list areas and never\n  ask the user \"which area?\" before you have read it.\n- You work in a WORKSPACE, not inside a single area. Missions and intents are\n  workspace-level and take no area. Documents live at area OR workspace level.\n  Tasks, vibes, issues and ideas are AREA-scoped.\n- Missions and intents outrank individual tasks. Asked to work on \"what matters\", take the\n  active mission and open intents from context and pick work that serves them.\n- The area follows from the directory, never from a question to the user:\n  `.orbitmap/config.json` maps directories \u2192 area slugs at the workspace root, and each\n  area directory carries its own `.orbitmap/config.json` marker naming its area. That\n  config is the only source of truth \u2014 never hard-code area names anywhere.\n  So: do area-scoped work from the directory it belongs to and let the CLI resolve it.\n- `--area <slug>` is an OVERRIDE for a single call, not part of normal usage \u2014 reach for it\n  only to read or write outside the area the current directory resolves to.\n- If a command fails with `AREA_CONTEXT_REQUIRED`, its details list the mapped\n  directories: cd into the right one, or retry with `--area <slug>`.\n- WRITES: the resolved area is a default for *reading*, never a statement of where the\n  work belongs. Before creating anything area-scoped (task, subtask, issue, vibe),\n  derive the target area from the work itself (which repo/package it lives in) and pass\n  `--area <slug>` if that differs from the area the CLI echoes. If the work itself is\n  genuinely ambiguous, ASK THE USER; do not guess. There is no\n  `move` command: a write in the wrong area has to be recreated.\n- Every write echoes its scope on stderr: `creates in area <slug> (source: \u2026)` when it\n  creates an object, `scoped to area <slug> (source: \u2026)` when it changes one by id. A\n  `source` of `global ~/.orbitmap/config.json` is a machine-wide leftover that nothing\n  here chose \u2014 treat it as unconfirmed and pass `--area` explicitly.\n\n## Task or intent?\n\nAn intent earns its gates when the work carries knowledge someone would otherwise\nre-derive or re-litigate: a decision with a rejected alternative, a design that outlives\nthe change, a constraint worth recording. Work with none of that \u2014 a typo, a copy tweak,\nan obvious one-file fix \u2014 is a task: create it, do it, log it, done. The same test the\nwork log uses for what to write down. If a \"small\" fix turns out to hide a real decision,\nstop and frame it; discovering that mid-change is normal, not a failure.\n\n## Task statuses\nbacklog, todo, in_progress, in_review, review_changes, done, blocked.\n`orbitmap tasks` defaults to todo,in_progress. Ask for others explicitly, e.g.\n`orbitmap tasks --status backlog` when the user asks about the backlog.\n\n## Listing tasks\n- A list spans EVERY area you can reach and EVERY assignee \u2014 nothing narrows it to the\n  current directory or to you. It is capped at 30 rows with the totals behind the cap\n  printed, and every list states the filters that produced it. Read that line before you\n  answer from a list.\n- While you are executing an intent, EVERY task query carries `--intent IN-x`. Nothing\n  narrows a list to an intent on your behalf: a bare `orbitmap tasks` is you having\n  deliberately left the intent to look at the whole workspace.\n- `orbitmap intent show IN-x` already carries the intent's own tasks, so intent lifecycle\n  work needs no filter at all. `orbitmap tasks --intent IN-x` is the escape hatch for the\n  times you want the task-list shape \u2014 statuses, assignees, the filter line \u2014 instead.\n\n## Command reference (all commands accept --json)\n- Context: `orbitmap context` (once per session at most \u2014 see Session focus),\n  `orbitmap overview`, `orbitmap areas`\n  (rarely needed \u2014 context already lists the areas you work in)\n- Tasks: `orbitmap tasks [--status s1,s2] [--intent IN-x]`, `orbitmap task TS-x`,\n  `orbitmap get <ID>`,\n  `orbitmap start [TS-x]`, `orbitmap status TS-x <status> [--delivery <d>]`,\n  `orbitmap create \"title\" [--intent IN-x] [--priority p]`,\n  `orbitmap subtask TS-parent \"title\"`, `orbitmap assign TS-x [agent]`,\n  `orbitmap dep add|remove TS-a TS-b`, `orbitmap log TS-x \"msg\" --type <t>`\n- Issues: `orbitmap issue register|list|show|status|resolve`\n- Ideas: `orbitmap idea add|list|show|status`\n- Vibes: `orbitmap vibe log|list|show`\n- Missions: `orbitmap mission list|show|create|update|status|link|unlink`\n- Intents: `orbitmap intent list|show|create|update|link|unlink`\n  (`show` embeds the context bundle \u2014 `--no-bundle` strips it, `--slim` is the\n  freshness probe, `--no-logs` skips the log tail)\n- Documents: `orbitmap docs`, `orbitmap doc <slug> [--section \"## H\"|--full]`,\n  `orbitmap doc-import`, `orbitmap doc-update`\n\n## Error handling\n- If OrbitMap is unreachable (network down / workspace directory unavailable), inform\n  the user and continue the primary work without logging. Do NOT retry failed orbitmap\n  calls in a loop \u2014 report the issue and proceed with the task.";
+export declare const SKILL_EXECUTE_FRONTMATTER = "---\nname: orbitmap-execute\ndescription: >\n  Executing OrbitMap work \u2014 the fourth gate of the product-building flow. Two flows:\n  \"execute IN-x\" delivers a whole planned intent in the background (parallel worker\n  waves, per-task tests, the intent test, an impact pass against a baseline, a\n  goal-based fix loop, everything ending in_review on an intent branch \u2014 merging stays\n  the user's), and \"work on TS-x\" runs a single tracked task (starting/resuming,\n  logging, finishing with the correct status, git branches and delivery status). Use\n  whenever executing a planned intent or implementing, resuming, or finishing a\n  tracked task. Requires the `orbitmap` core skill.\n---";
 export declare const SKILL_EXECUTE_BODY: string;
 export declare const SKILL_EXECUTE_REFERENCES: Readonly<Record<string, string>>;
-export declare const SKILL_PLAN_FRONTMATTER = "---\nname: orbitmap-plan\ndescription: >\n  Planning an intent's design into executable tasks in OrbitMap \u2014 the third gate of the\n  product-building flow (after design). Decomposes the agreed design into Orb-hierarchy\n  tasks that provably cover the intent: tests per task + an intent-level test, a coverage\n  hard-gate, correct-area placement, self-contained context/doc-grounded agent_instructions,\n  cross-task notes in the intent plan field, and a doc-update-after-green step; then creates\n  the tasks and hands off to orbitmap-execute. Use for \"plan this intent\", \"break this down\n  into tasks\", an intent entering `plan` status \u2014 and for general planning (missions,\n  intents, promoting ideas, triaging issues).\n---";
+export declare const SKILL_PLAN_FRONTMATTER = "---\nname: orbitmap-plan\ndescription: >\n  Planning an intent's design into executable tasks in OrbitMap \u2014 the third gate of the\n  product-building flow (after design). Decomposes the agreed design into Orb-hierarchy\n  tasks that provably cover the intent: tests per task + an intent-level test, a coverage\n  hard-gate, correct-area placement, self-contained context/doc-grounded agent_instructions,\n  cross-task notes in the intent plan field, and a doc-update-after-green step; then creates\n  the tasks and hands off to orbitmap-execute. Use for \"plan this intent\", \"break this down\n  into tasks\", an intent entering `plan` status \u2014 and for general planning (missions,\n  intents, promoting ideas, triaging issues). Requires the `orbitmap` core skill.\n---";
 export declare const SKILL_PLAN_BODY: string;
-export declare const SKILL_BRAINSTORM_FRONTMATTER = "---\nname: orbitmap-brainstorm\ndescription: >\n  Brainstorming an idea into an agreed outcome in OrbitMap \u2014 the first gate of the\n  product-building flow, run as a natural thinking-partner conversation. You MUST use this\n  before any creative work \u2014 creating features, building components, adding functionality,\n  or modifying behavior. It explores intent, requirements and constraints one question at a\n  time until the outcome is AGREED, writes that outcome to the intent's outcome field, and\n  files useful asides to the design (and, when relevant, plan) fields for the later gates.\n  Use for \"I have an idea\", \"brainstorm this\", \"let's think through X\", \"what should we\n  build/do about X\", shaping an intent's outcome, or an intent at `new` status.\n---";
+export declare const SKILL_BRAINSTORM_FRONTMATTER = "---\nname: orbitmap-brainstorm\ndescription: >\n  Brainstorming an idea into an agreed outcome in OrbitMap \u2014 the first gate of the\n  product-building flow, run as a natural thinking-partner conversation. You MUST use this\n  before any creative work \u2014 creating features, building components, adding functionality,\n  or modifying behavior. It explores intent, requirements and constraints one question at a\n  time until the outcome is AGREED, writes that outcome to the intent's outcome field, and\n  files useful asides to the design (and, when relevant, plan) fields for the later gates.\n  Use for \"I have an idea\", \"brainstorm this\", \"let's think through X\", \"what should we\n  build/do about X\", shaping an intent's outcome, or an intent at `new` status. Requires\n  the `orbitmap` core skill.\n---";
 export declare const SKILL_BRAINSTORM_BODY: string;
-export declare const SKILL_DESIGN_FRONTMATTER = "---\nname: orbitmap-design\ndescription: >\n  Designing an intent's solution in OrbitMap \u2014 the second gate of the product-building\n  flow (after brainstorm): turns an agreed outcome into an approach,\n  technical spec, and UX (when there's UI), one question at a time, then writes the\n  result to the intent's design field. Use for \"design this intent\", \"let's design X\", or\n  an intent entering `design` status. Use it once the outcome is agreed; if the outcome is\n  still missing or vague, step aside to `orbitmap-brainstorm` first.\n---";
+export declare const SKILL_DESIGN_FRONTMATTER = "---\nname: orbitmap-design\ndescription: >\n  Designing an intent's solution in OrbitMap \u2014 the second gate of the product-building\n  flow (after brainstorm): turns an agreed outcome into an approach,\n  technical spec, and UX (when there's UI), one question at a time, then writes the\n  result to the intent's design field. Use for \"design this intent\", \"let's design X\", or\n  an intent entering `design` status. Use it once the outcome is agreed; if the outcome is\n  still missing or vague, step aside to `orbitmap-brainstorm` first. Requires the\n  `orbitmap` core skill.\n---";
 export declare const SKILL_DESIGN_BODY: string;
-export declare const SKILL_DOCS_FRONTMATTER = "---\nname: orbitmap-docs\ndescription: >\n  Reading and updating OrbitMap documents (specs, architecture, guides, decisions).\n  Use when the user asks to read, import, or update project documentation tracked in\n  OrbitMap.\n---";
-export declare const SKILL_DOCS_BODY = "# OrbitMap documents\n\nDocuments are workspace-level: exactly ONE copy per workspace, never per-area. No document\ncommand takes an area, and their metadata (slug, when to use) already rides the context\npayload your session focus was matched from (see Session focus in the `orbitmap` skill \u2014\nensure, don't re-call).\n\n## Goal\nRead and update OrbitMap documents efficiently: pull only the context you need (TOC \u2192\nsection \u2192 full, never dump a whole doc into the conversation), and make every change\nthrough the CLI \u2014 never by editing the workspace files directly.\n\n**Interface:** every action below is an OrbitMap operation \u2014 run the `orbitmap` CLI command\nshown, or its equivalent MCP tool when this session uses MCP; `orbitmap <cmd> --help` and the\nMCP tool schemas are the authority. Never edit the workspace data files directly.\n\n## Choosing what to read\n`orbitmap docs` lists documents with their `context` (when the doc is relevant) and\n`sections_count`. Use context to pick the right document; use sections_count to decide\nwhether to fetch the TOC first (many sections) or go straight to full.\n\n## Token-efficient reading flow\n1. `orbitmap doc <slug>` \u2192 context + table of contents (cheap).\n2. `orbitmap doc <slug> --section \"## Auth\"` \u2192 just that section.\n3. `orbitmap doc <slug> --full` \u2192 full content (expensive \u2014 last resort).\nUse the lightest mode that answers your question. When the CLI reports a local file path\nfor the full content, read that file instead of printing the content into the\nconversation.\n\n## Editing\n- Import a new document: `orbitmap doc-import <file.md> --title \"\u2026\" --type\n  spec|architecture|api|guide|decision|changelog|other [--context \"\u2026\"]`.\n- Update: `orbitmap doc-update <slug> --file <file.md>` (replaces content, bumps\n  version).\n- To change an OrbitMap document, ALWAYS go through these commands \u2014 NEVER edit files\n  inside the OrbitMap workspace/cache directories directly.\n\n## Editing safely \u2014 documents have NO revert (known server defects: IS-8wwkb9)\n- Prefer section ops (`doc-patch --replace-section/--insert-section`); use line-based\n  ops only when no section op can express the change \u2014 line coordinates are shifted\n  server-side assuming ASCENDING order, and blank edges of op content get trimmed.\n- The section parser is not fence-aware: a line-start `#` INSIDE a code block is taken\n  for a heading and becomes a section boundary. Keep code-block comments inline\n  (`cmd  # comment`), and check target sections for this hazard BEFORE replacing them.\n- Never read a document between a `doc-update` upload and its confirm \u2014 a cached read\n  makes the confirm silently re-save the OLD content while still bumping the version.\n- After ANY write, re-read the changed section (or TOC for structure) and verify the\n  result actually matches what you sent. A bumped version number is not proof.";
+export declare const SKILL_DOCS_FRONTMATTER = "---\nname: orbitmap-docs\ndescription: >\n  Reading and updating OrbitMap documents (specs, architecture, guides, decisions).\n  Use when the user asks to read, import, or update project documentation tracked in\n  OrbitMap. Requires the `orbitmap` core skill.\n---";
+export declare const SKILL_DOCS_BODY = "# OrbitMap documents\n\nDocuments live at area or workspace level: `orbitmap docs` lists every document you can\nreach \u2014 your areas' documents plus the workspace-level ones \u2014 and their metadata (slug,\nwhen to use) already rides the context payload your session focus was matched from (see\nSession focus in the `orbitmap` skill \u2014 ensure, don't re-call).\n\n## Goal\nRead and update OrbitMap documents efficiently: pull only the context you need (TOC \u2192\nsection \u2192 full, never dump a whole doc into the conversation), and make every change\nthrough the CLI \u2014 never by editing the workspace files directly.\n\n**Interface:** every action below is an OrbitMap operation \u2014 run the `orbitmap` CLI command\nshown, or its equivalent MCP tool when this session uses MCP; `orbitmap <cmd> --help` and the\nMCP tool schemas are the authority. Never edit the workspace data files directly.\n\n## Choosing what to read\n`orbitmap docs` lists documents with their `context` (when the doc is relevant) and\n`sections_count`. Use context to pick the right document; use sections_count to decide\nwhether to fetch the TOC first (many sections) or go straight to full.\n\n## Token-efficient reading flow\n1. `orbitmap doc <slug>` \u2192 context + table of contents (cheap).\n2. `orbitmap doc <slug> --section \"## Auth\"` \u2192 just that section.\n3. `orbitmap doc <slug> --full` \u2192 full content (expensive \u2014 last resort).\nUse the lightest mode that answers your question. When the CLI reports a local file path\nfor the full content, read that file instead of printing the content into the\nconversation.\n\n## Editing\n- Import a new document: `orbitmap doc-import <title> --file <file.md> --type\n  spec|architecture|api|guide|decision|changelog|other [--context \"\u2026\"]`. It lands\n  area-level, resolved from the current directory; add `--workspace-id <slug-or-uuid>`\n  to create it workspace-level instead.\n- Update: `orbitmap doc-update <slug> --file <file.md>` (replaces content, bumps\n  version).\n- To change an OrbitMap document, ALWAYS go through these commands \u2014 NEVER edit files\n  inside the OrbitMap workspace/cache directories directly.\n\n## Editing safely \u2014 documents have NO revert\n- Section ops are the only ops (`doc-patch --replace-section/--insert-section/\n  --delete-section/--append`); the line-based ones are gone. On a document with an\n  unclosed code fence every patch op is REFUSED \u2014 repair it with a full `doc-update`.\n  `doc-patch --dry-run` reports the boundaries each op would touch, without writing.\n- The section parser is fence-aware: a line-start `#` inside a code block is never a\n  section boundary, and a patch whose result would leave an unclosed fence is refused.\n- After ANY write, re-read the changed section (or TOC for structure) and verify the\n  result actually matches what you sent. A bumped version number is not proof.";
 export interface SkillDef {
-    /** Skill name = directory name under `.claude/skills/`. */
+    /**
+     * Skill name = directory name under the agent's skills directory (`~/.claude/skills/`,
+     * `~/.codex/skills/`, or a project's `.claude/skills/`).
+     */
     name: string;
     /** Verbatim YAML frontmatter block, including the `---` fences. */
     frontmatter: string;
@@ -55,7 +58,7 @@ export interface SkillDef {
     /**
      * Extra files shipped with the skill (a skill = SKILL.md + optional reference
      * files). Key = POSIX path RELATIVE to the skill's directory
-     * (`.claude/skills/<name>/`), and may contain subdirectories, e.g.
+     * (`<skills dir>/<name>/`), and may contain subdirectories, e.g.
      * `references/worker-contract.md`. Value = verbatim file content (no trailing
      * newline; the installer appends one, matching buildSkillFile).
      *
@@ -67,27 +70,39 @@ export interface SkillDef {
     references?: Readonly<Record<string, string>>;
 }
 export declare const SKILLS: readonly SkillDef[];
-export declare const THIN_HOOK_CLAUDE = "## OrbitMap\n\nWork is tracked in OrbitMap via the `orbitmap` CLI. You work in a WORKSPACE, which can span\nseveral repositories: each repo is an AREA, while missions, intents and documents belong to\nthe workspace itself, not to any one repo.\nLoad the OrbitMap skills whenever the user wants to build, add, change or fix something, in\nwhatever words they use \u2014 do not wait for OrbitMap vocabulary. Load them too when they talk\nabout tracking work (backlog, tasks, missions, intents, ideas, issues, documents, planning).\nNothing gets built before it is framed: a feature, component or behaviour change gets an intent\n\u2014 outcome (brainstorm) \u2192 design \u2192 plan \u2192 build (execute), one gate at a time, written to the\nintent as you go. Small self-contained work (a typo, an obvious one-file fix) is just a task.\nNEVER finish a task, intent or mission without a final `orbitmap log` entry and a status update;\nthe final entry closes a record that already exists. Finished work defaults to `in_review`, not `done`.\nOrbitMap tool responses may carry an Instructions section \u2014 act on it before continuing.";
+export declare const THIN_HOOK_SKILLS = "## OrbitMap\n\nWork is tracked in OrbitMap via the `orbitmap` CLI. You work in a WORKSPACE, which can span\nseveral repositories: each repo is an AREA, while missions, intents and documents belong to\nthe workspace itself, not to any one repo.\nLoad the OrbitMap skills whenever the user wants to build, add, change or fix something, in\nwhatever words they use \u2014 do not wait for OrbitMap vocabulary. Load them too when they talk\nabout tracking work (backlog, tasks, missions, intents, ideas, issues, documents, planning).\nLoad the core skill 'orbitmap' first, before any other orbitmap-* skill \u2014 they all build on it.\nNothing gets built before it is framed: a feature, component or behaviour change gets an intent\n\u2014 outcome (brainstorm) \u2192 design \u2192 plan \u2192 build (execute), one gate at a time, written to the\nintent as you go. Small self-contained work (a typo, an obvious one-file fix) is just a task.\nNEVER finish a task, intent or mission without a final `orbitmap log` entry and a status update;\nthe final entry closes a record that already exists. Finished work defaults to `in_review`, not `done`.\nOrbitMap tool responses may carry an Instructions section \u2014 act on it before continuing.";
 export declare const THIN_HOOK_GENERIC = "## OrbitMap\n\nWork is tracked in OrbitMap via the `orbitmap` CLI. You work in a WORKSPACE, which can span\nseveral repositories: each repo is an AREA, while missions, intents and documents belong to\nthe workspace itself, not to any one repo.\nFollow the sections below whenever the user wants to build, add, change or fix something, in\nwhatever words they use \u2014 do not wait for OrbitMap vocabulary. Follow them too when they talk\nabout tracking work (backlog, tasks, missions, intents, ideas, issues, documents, planning).\nNothing gets built before it is framed: a feature, component or behaviour change gets an intent\n\u2014 outcome (brainstorm) \u2192 design \u2192 plan \u2192 build (execute), one gate at a time, written to the\nintent as you go. Small self-contained work (a typo, an obvious one-file fix) is just a task.\nNEVER finish a task, intent or mission without a final `orbitmap log` entry and a status update;\nthe final entry closes a record that already exists. Finished work defaults to `in_review`, not `done`.\nOrbitMap tool responses may carry an Instructions section \u2014 act on it before continuing.";
-/** Build one SKILL.md file (frontmatter + body) for Claude. */
+/**
+ * Build one SKILL.md file (frontmatter + body). The layout is the same for every
+ * skills-capable agent — Claude Code and Codex read identical frontmatter — so one
+ * renderer serves all of them.
+ */
 export declare function buildSkillFile(skill: SkillDef): string;
 /**
- * One extra line appended to the Claude hook when the skills were installed at PROJECT
+ * One extra line appended to the thin hook when the skills were installed at PROJECT
  * scope. `CLAUDE.md` is inherited by every sub-directory, but a project-level
  * `.claude/skills/` directory is not: a session started in a sibling or child repository
  * reads this hook and cannot load the skills it names. The hook must therefore say where
  * the skills actually are, and how to make them visible everywhere. At user scope the
  * skills are visible wherever the hook is, so no caveat is needed.
+ *
+ * It names `.claude/skills/` because Claude Code is the only agent that can reach it:
+ * project scope installs skills only for an agent that READS them at project scope, and
+ * Codex — the other skills-capable agent — discovers skills under `$CODEX_HOME` only.
  */
 export declare const SKILL_SCOPE_CAVEAT_PROJECT: string;
 /**
- * Build the thin always-on block for a Claude config file (CLAUDE.md).
+ * Build the thin always-on block for ANY skills-capable agent's config file — `CLAUDE.md`
+ * for Claude Code, `AGENTS.md` for Codex. Both get the same block, because both load the
+ * skills the block points at; the file it lands in is the installer's business, not this
+ * function's.
+ *
  * `scope` is where the accompanying skill files were installed — see
  * {@link SKILL_SCOPE_CAVEAT_PROJECT}.
  */
-export declare function buildClaudeBlock(scope?: 'user' | 'project'): string;
+export declare function buildSkillsBlock(scope?: 'user' | 'project'): string;
 /**
- * Build the markdown fallback block for non-Claude agents: the thin hook plus every
- * skill body inlined (no skill ecosystem to lean on).
+ * Build the markdown fallback block for agents with no skill ecosystem: the thin hook plus
+ * every skill body inlined, because there is nothing to load on demand.
  */
 export declare function buildGenericBlock(): string;