orbitmap 0.4.2 → 0.4.4

package/dist/index.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { Command } from 'commander';
+import { Command, Option } from 'commander';
 import { initCommand } from './commands/init.js';
 import { contextCommand } from './commands/context.js';
 import { areasCommand } from './commands/areas.js';
@@ -35,7 +35,7 @@ import { depAddCommand, depRemoveCommand } from './commands/dep.js';
 import { getCommand } from './commands/get.js';
 import { createRequire } from 'node:module';
 import { createAreaCommand } from './commands/create-area.js';
-import { setWorkspaceFlag } from './workspace-resolve.js';
+import { setWorkspaceFlag, setWorkspaceIdFlag } from './workspace-resolve.js';
 const program = new Command();
 /**
  * `--version` reads the real package version instead of a hardcoded literal, which had gone
@@ -44,25 +44,55 @@ const program = new Command();
  * always ships package.json in the tarball regardless of the `files` allow-list.
  */
 const { version } = createRequire(import.meta.url)('../package.json');
+/**
+ * Commander collector for a REPEATABLE option: each occurrence is appended, so `--log a
+ * --log b` arrives as `['a', 'b']` in the order typed. Without it Commander keeps only the
+ * last value, and a work log batch would silently lose every entry but one.
+ *
+ * Register with an explicit `[]` default (`.option(..., collect, [])`) — the default is the
+ * accumulator's seed, and Commander does not supply one.
+ */
+function collect(value, previous) {
+    return [...previous, value];
+}
+/** `--log` help text, identical on every command that carries a work log batch. */
+const LOG_FLAG_HELP = 'Work log entry as <type>:<content>; repeatable, order preserved. ' +
+    'Types: note, code_change, decision, blocker. Required by the API when the status changes';
 program
     .name('orbitmap')
     .description('CLI tool for OrbitMap Agent API')
     .version(version)
     .option('--json', 'Output in JSON format', false)
     .option('--area <id>', 'Area ID or slug to use')
-    .option('--workspace <path>', 'Local workspace directory to use (local mode)');
-// The workspace flag is program-level and consumed by the resolver, not by the
-// command modules, so capture it once before any action runs.
-program.hook('preAction', (thisCommand) => {
+    .option('--workspace <path>', 'Local workspace directory to use (local mode)')
+    .option('--workspace-id <slug-or-uuid>', 'Workspace to use (slug or UUID)')
+    // Satisfies the write-target confirmation non-interactively (see src/write-target.ts).
+    .option('--yes', 'Accept the resolved target area for writes without confirming', false);
+// Both workspace flags are consumed by the resolver, not by the command modules, so
+// capture them once before any action runs. They are different things: `--workspace` is a
+// directory on this disk (and forces local mode), `--workspace-id` names a workspace in the
+// backend and does not touch the mode.
+//
+// `--workspace-id` is read from the SUBCOMMAND first and only then from the program level.
+// Previously only `thisCommand` (the program) was consulted, so `create-area --workspace-id`,
+// `doc-import --workspace-id` and `init --workspace-id` put the value in the request body
+// but never sent `X-Orbitmap-Workspace` — the same flag reached the header ladder or not
+// purely depending on where the user typed it.
+program.hook('preAction', (thisCommand, actionCommand) => {
     setWorkspaceFlag(thisCommand.opts()['workspace']);
+    const subcommandWorkspaceId = actionCommand.opts()['workspaceId'];
+    setWorkspaceIdFlag(subcommandWorkspaceId ?? thisCommand.opts()['workspaceId']);
 });
 program
     .command('init')
     .description('Set up OrbitMap (cloud account or local files) and install the agent skills')
     .option('--key <api-key>', 'Agent API key (enables non-interactive mode)')
     .option('--token <api-key>', 'Alias for --key')
-    .option('--area <id>', 'Default area ID (cloud) or first area name (local)')
+    .option('--area <id>', 'Area this directory is (cloud) or first area name (local)')
+    .option('--workspace-id <slug-or-uuid>', 'Cloud: workspace to set up (skips the workspace question)')
     .option('--profile <profile>', 'MCP profile: full, lite, manager (default: full)')
+    .option('--allow-nested', 'Cloud: set up a workspace here even though another workspace root sits above or below ' +
+    'this directory')
     .option('--advanced', 'Show advanced options (e.g. custom API URL)')
     .option('--local', 'Set up local-files mode without the interactive question')
     .option('--workspace <path>', 'Local workspace directory (default: ./.orbitmap)')
@@ -70,6 +100,8 @@ program
     .option('--no-skills', 'Skip installing the OrbitMap agent skills')
     .option('--agent <type>', 'Coding agent to install the skills for: claude, gemini, codex, cursor, windsurf, generic ' +
     '(default: detected from this directory, or asked)')
+    .option('--scope <scope>', 'Where to install the skills: user (default, ~/.claude/skills — visible from every ' +
+    'directory) or project (this directory only)')
     .option('--global', 'Cloud: write to ~/.orbitmap/config.json instead of ./.orbitmap/config.json')
     .action(async (opts, command) => {
     // `--workspace` also exists as a program-level flag, and Commander binds it there;
@@ -80,12 +112,17 @@ program
         key: opts.key,
         token: opts.token,
         area: opts.area ?? all['area'],
+        // `--workspace-id` is also a program-level flag; take it from whichever position it
+        // was given in (same pattern as `--workspace` above).
+        workspaceId: opts.workspaceId ?? all['workspaceId'],
         profile: opts.profile,
+        allowNested: opts.allowNested,
         local: opts.local,
         workspace: opts.workspace ?? all['workspace'],
         workspaceName: opts.workspaceName,
         skills: opts.skills,
         agent: opts.agent,
+        scope: opts.scope,
         global: opts.global,
     });
 });
@@ -121,7 +158,7 @@ program
     .description('Create a new area')
     .option('--desc <description>', 'Area description')
     .option('--slug <slug>', 'Area slug (auto-generated from name if omitted)')
-    .option('--workspace-id <uuid>', 'Workspace to create the area in')
+    .option('--workspace-id <slug-or-uuid>', 'Workspace to create the area in (slug or UUID)')
     .action(async (name, opts, cmd) => {
     const globalOpts = cmd.optsWithGlobals();
     await createAreaCommand(name, {
@@ -129,7 +166,9 @@ program
         area: globalOpts.area,
         desc: opts.desc,
         slug: opts.slug,
-        workspaceId: opts.workspaceId,
+        // `--workspace-id` also exists as a program-level flag; `optsWithGlobals()` picks it
+        // up whichever position it was given in (same pattern as `--workspace` on `init`).
+        workspaceId: opts.workspaceId ?? globalOpts.workspaceId,
     });
 });
 program
@@ -148,7 +187,8 @@ program
 });
 program
     .command('tasks')
-    .description('List your assigned tasks')
+    .description('List tasks in the current area — or, when the context is workspace-scoped, every ' +
+    'area in the workspace grouped by area')
     .option('--status <statuses>', 'Filter by status (comma-separated)', 'todo,in_progress')
     .option('--priority <priority>', 'Filter by priority')
     .option('--orbit <id-or-slug>', 'Filter by orbit (UUID or slug)')
@@ -209,6 +249,7 @@ program
     await statusCommand(taskId, status, {
         json: globalOpts.json,
         area: globalOpts.area,
+        yes: globalOpts.yes,
         delivery: opts.delivery,
         force: opts.force,
     });
@@ -220,17 +261,18 @@ program
     .option('--priority <priority>', 'Priority (critical, high, medium, low)')
     .option('--status <status>', 'Initial status')
     .option('--effort <effort>', 'Estimated effort (e.g. 4h, 2d)')
-    .option('--agent-id <id>', 'Assign to agent')
+    .option('--agent-id <id-or-slug>', 'Assign to agent (UUID or slug)')
     .option('--branch <name>', 'Git branch name')
     .option('--instructions <text>', 'Agent instructions')
-    .option('--from-issue <id-or-number>', 'Link task to an existing issue (UUID, number, or IS-prefixed)')
-    .option('--intent <id>', 'Link task to an intent')
-    .option('--orbit <id>', 'Attach task to an orbit (omit to inherit the intent orbit)')
+    .option('--from-issue <id-or-number>', 'Link task to an existing issue (UUID or display number, e.g. IS-8hv2wn)')
+    .option('--intent <id-or-number>', 'Link task to an intent (UUID or display number, e.g. IN-rwb5qu)')
+    .option('--orbit <id-or-slug>', 'Attach task to an orbit (UUID or slug; omit to inherit the intent orbit)')
     .action(async (title, opts, cmd) => {
     const globalOpts = cmd.optsWithGlobals();
     await createCommand(title, {
         json: globalOpts.json,
         area: globalOpts.area,
+        yes: globalOpts.yes,
         desc: opts.desc,
         priority: opts.priority,
         status: opts.status,
@@ -254,14 +296,15 @@ program
     await subtaskCommand(parentId, title, {
         json: globalOpts.json,
         area: globalOpts.area,
+        yes: globalOpts.yes,
         desc: opts.desc,
         priority: opts.priority,
         effort: opts.effort,
     });
 });
 program
-    .command('assign <id-or-number> [agent-id]')
-    .description('Assign a task, issue, idea, or intent to an agent or user')
+    .command('assign <id-or-number> [agent-id-or-slug]')
+    .description('Assign a task, issue, idea, or intent to an agent (UUID or slug) or user')
     .option('--user-id <id>', 'Assign to a user (by user ID) instead of an agent')
     .option('--type <type>', 'Object type: task, issue, idea, intent (auto-detected from prefixed IDs; default task)')
     .action(async (objectId, agentId, opts, cmd) => {
@@ -269,21 +312,26 @@ program
     await assignCommand(objectId, agentId, {
         json: globalOpts.json,
         area: globalOpts.area,
+        yes: globalOpts.yes,
         userId: opts.userId,
         type: opts.type,
     });
 });
 program
     .command('log <id-or-number> <message>')
-    .description('Log work on a task')
-    .option('--type <type>', 'Log type: note, code_change, decision, blocker, discovery, exploration, fix', 'note')
+    .description('Log work on a task, intent or mission (TS-/IN-/MS- number, or a UUID)')
+    .option('--type <type>', 'Log type: note, code_change, decision, blocker', 'note')
+    .option('--target <kind>', 'Which object a bare UUID names: task, intent, mission (default: read from the ' +
+    'TS-/IN-/MS- prefix, else task)')
     .option('--meta <json>', 'JSON metadata (e.g. \'{"files":["..."]}\')')
-    .action(async (taskId, message, opts, cmd) => {
+    .action(async (idOrNumber, message, opts, cmd) => {
     const globalOpts = cmd.optsWithGlobals();
-    await logCommand(taskId, message, {
+    await logCommand(idOrNumber, message, {
         json: globalOpts.json,
         area: globalOpts.area,
+        yes: globalOpts.yes,
         type: opts.type,
+        target: opts.target,
         meta: opts.meta,
     });
 });
@@ -343,17 +391,20 @@ program
     .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 <uuid>', 'Create as workspace-level document (cross-area knowledge)')
+    .option('--workspace-id <slug-or-uuid>', 'Create as workspace-level document (cross-area knowledge); slug or UUID')
     .action(async (title, opts, cmd) => {
     const globalOpts = cmd.optsWithGlobals();
     await docImportCommand(title, {
         json: globalOpts.json,
         area: globalOpts.area,
+        yes: globalOpts.yes,
         type: opts.type,
         file: opts.file,
         sourcePath: opts.sourcePath,
         context: opts.context,
-        workspaceId: opts.workspaceId,
+        // Program-level `--workspace-id` is the fallback when it was given before the
+        // subcommand name (see `create-area`).
+        workspaceId: opts.workspaceId ?? globalOpts.workspaceId,
     });
 });
 program
@@ -437,21 +488,33 @@ program
     .description('Refresh the OrbitMap agent instructions/skills, or add another agent type ' +
     '(`init` already installs them once)')
     .option('--agent <type>', 'Agent type: claude, gemini, codex, cursor, windsurf, generic')
+    .option('--scope <scope>', 'Where to install: user (default, ~/.claude/skills — visible from every directory) ' +
+    'or project (this directory only)')
+    .option('--clean-project', 'With --scope user: remove an older project-scope install in this directory ' +
+    '(its four OrbitMap skill dirs + the OrbitMap block in the config file) without asking')
     .action(async (opts) => {
-    await setupAgentCommand({ agent: opts.agent });
+    await setupAgentCommand({
+        agent: opts.agent,
+        scope: opts.scope,
+        cleanProject: opts.cleanProject,
+    });
 });
 program
     .command('setup-mcp')
     .description('Install OrbitMap MCP entry into .mcp.json in the current directory (no API calls)')
     .option('--token <api-key>', 'Agent API key (Bearer auth)')
     .option('--oauth', 'Use OAuth (no Authorization header; auth happens on first MCP use)')
-    .option('--area <slug>', 'Area slug or UUID (required for --token, optional for --oauth)')
+    .option('--workspace-id <slug-or-uuid>', 'Workspace to pin in the generated block (X-Orbitmap-Workspace)')
+    .option('--area <slug>', 'Area slug or UUID to pin as well (X-Orbitmap-Area, optional)')
     .option('--profile <profile>', 'MCP profile: full, lite, manager (default: full)')
     .action(async (opts, cmd) => {
+    // `--workspace-id` also exists as a program-level flag; `optsWithGlobals()` picks it up
+    // whichever position it was given in (same pattern as `--area`).
     const globalOpts = cmd.optsWithGlobals();
     await setupMcpCommand({
         token: opts.token,
         oauth: opts.oauth,
+        workspaceId: opts.workspaceId || globalOpts.workspaceId,
         area: opts.area || globalOpts.area,
         profile: opts.profile,
     });
@@ -538,19 +601,26 @@ const issue = program
     .command('issue')
     .description('Manage issues');
 issue
-    .command('register')
+    .command('register [title]')
     .description('Register a new issue')
-    .requiredOption('--title <title>', 'Issue title')
+    // Title is positional, like `create`, `intent create`, `mission create` and `orbit create`.
+    // `--title` stays as a hidden back-compat alias.
+    .addOption(new Option('--title <title>', 'Deprecated: pass the title positionally').hideHelp())
     .requiredOption('--description <text>', 'Issue description')
     .option('--severity <level>', 'Severity: critical, high, medium, low')
-    .option('--related-task <id>', 'Related task UUID')
-    .option('--intent <id>', 'Link issue to an intent')
-    .action(async (opts, cmd) => {
+    // These two stay UUID-only: TS-av6332 relaxed `intent_id`/`orbit_id`/`source_issue_id` on
+    // POST /tasks to `App\Rules\EntityRef`, but IssueController still validates
+    // `related_task_id` and `intent_id` as `uuid`. Do not translate client-side — see the
+    // OrbitMap issue linked from TS-zhmvnc.
+    .option('--related-task <uuid>', 'Related task UUID (this endpoint does not accept display numbers)')
+    .option('--intent <uuid>', 'Link issue to an intent, by UUID (no display numbers here)')
+    .action(async (title, opts, cmd) => {
     const globalOpts = cmd.optsWithGlobals();
     await issueRegisterCommand({
         json: globalOpts.json,
         area: globalOpts.area,
-        title: opts.title,
+        yes: globalOpts.yes,
+        title: title ?? opts.title,
         description: opts.description,
         severity: opts.severity,
         relatedTask: opts.relatedTask,
@@ -586,9 +656,11 @@ issue
 issue
     .command('resolve <id-or-number>')
     .description('Resolve an issue')
-    .requiredOption('--status <status>', 'Resolve status: resolved, wont_fix, duplicate')
+    // The command is named `resolve`, so `resolved` is the obvious default; --status stays
+    // available for the other two terminal states (wont_fix, duplicate).
+    .option('--status <status>', 'Resolve status: resolved, wont_fix, duplicate', 'resolved')
     .option('--resolution <text>', 'Resolution description (required for resolved/wont_fix)')
-    .option('--resolved-task <id>', 'Task UUID that resolved this issue')
+    .option('--resolved-task <uuid>', 'Task UUID that resolved this issue (no display numbers here)')
     .action(async (idOrNumber, opts, cmd) => {
     const globalOpts = cmd.optsWithGlobals();
     await issueResolveCommand(idOrNumber, {
@@ -601,9 +673,11 @@ issue
 });
 issue
     .command('status <id-or-number> <status>')
-    .description('Update issue status (open, investigating, backlog, resolved, wont_fix, duplicate)')
+    .description('Update issue status. Which move is legal depends on the current status ' +
+    '(open <-> investigating <-> backlog, any of them -> resolved/wont_fix/duplicate, ' +
+    'and those back to open); the server rejects anything else with INVALID_TRANSITION')
     .option('--resolution <text>', 'Resolution description (required for resolved/wont_fix)')
-    .option('--resolved-task <id>', 'Task UUID that resolved this issue')
+    .option('--resolved-task <uuid>', 'Task UUID that resolved this issue (no display numbers here)')
     .action(async (idOrNumber, status, opts, cmd) => {
     const globalOpts = cmd.optsWithGlobals();
     await issueStatusCommand(idOrNumber, status, {
@@ -618,18 +692,21 @@ const vibe = program
     .command('vibe')
     .description('Manage vibes');
 vibe
-    .command('log')
+    .command('log [content]')
     .description('Log a new vibe')
-    .requiredOption('--content <text>', 'Vibe content')
-    .requiredOption('--type <type>', 'Type: note, code_change, decision, discovery, idea, exploration, fix')
+    // Content is positional, matching every other "create something" command.
+    // `--content` stays as a hidden back-compat alias.
+    .addOption(new Option('--content <text>', 'Deprecated: pass the content positionally').hideHelp())
+    .requiredOption('--type <type>', 'Type: note, code_change, decision, discovery, exploration, fix')
     .option('--title <title>', 'Optional title')
-    .option('--task <id>', 'Related task UUID')
-    .action(async (opts, cmd) => {
+    .option('--task <uuid>', 'Related task UUID (this endpoint does not accept display numbers)')
+    .action(async (content, opts, cmd) => {
     const globalOpts = cmd.optsWithGlobals();
     await vibeLogCommand({
         json: globalOpts.json,
         area: globalOpts.area,
-        content: opts.content,
+        yes: globalOpts.yes,
+        content: content ?? opts.content,
         type: opts.type,
         title: opts.title,
         task: opts.task,
@@ -652,8 +729,8 @@ vibe
     });
 });
 vibe
-    .command('show <id>')
-    .description('Show full vibe details')
+    .command('show <id-or-number>')
+    .description('Show full vibe details (UUID or display number, e.g. VB-a1b2c3)')
     .action(async (id, _opts, cmd) => {
     const globalOpts = cmd.optsWithGlobals();
     await vibeShowCommand(id, {
@@ -662,8 +739,8 @@ vibe
     });
 });
 vibe
-    .command('update <id>')
-    .description('Update a vibe')
+    .command('update <id-or-number>')
+    .description('Update a vibe (UUID or display number, e.g. VB-a1b2c3)')
     .option('--type <type>', 'New type')
     .option('--title <title>', 'New title')
     .option('--content <text>', 'New content')
@@ -710,17 +787,20 @@ idea
     });
 });
 idea
-    .command('add')
+    .command('add [content]')
     .description('Add a new idea')
-    .requiredOption('--content <text>', 'Idea content')
+    // Content is positional, matching every other "create something" command.
+    // `--content` stays as a hidden back-compat alias.
+    .addOption(new Option('--content <text>', 'Deprecated: pass the content positionally').hideHelp())
     .option('--title <title>', 'Optional short title')
     .option('--priority <priority>', 'Priority (critical, high, medium, low)')
-    .action(async (opts, cmd) => {
+    .action(async (content, opts, cmd) => {
     const globalOpts = cmd.optsWithGlobals();
     await ideaAddCommand({
         json: globalOpts.json,
         area: globalOpts.area,
-        content: opts.content,
+        yes: globalOpts.yes,
+        content: content ?? opts.content,
         title: opts.title,
         priority: opts.priority,
     });
@@ -744,13 +824,23 @@ const orbit = program
 orbit
     .command('list')
     .description('List orbits (workspace-scoped from the area context)')
-    .option('--workspace <id>', 'Filter by workspace UUID')
+    .option('--workspace-id <slug-or-uuid>', 'Filter by workspace (slug or UUID)')
+    // Back-compat: `--workspace <id>` was this filter's original spelling, which collided with
+    // the program-level `--workspace <path>` (a local directory that forces local mode).
+    // Hidden, still accepted, warns once.
+    .addOption(new Option('--workspace <slug-or-uuid>', 'Deprecated alias for --workspace-id').hideHelp())
     .action(async (opts, cmd) => {
     const globalOpts = cmd.optsWithGlobals();
+    if (opts.workspace && !opts.workspaceId) {
+        console.error('Warning: `orbit list --workspace` is deprecated (it collides with the global ' +
+            '`--workspace <path>`). Use `--workspace-id` instead.');
+    }
     await orbitListCommand({
         json: globalOpts.json,
         area: globalOpts.area,
-        workspace: opts.workspace,
+        // Only the *subcommand* flags are considered: the global `--workspace` is a directory,
+        // never a filter. The global `--workspace-id` is picked up as the last fallback.
+        workspaceId: opts.workspaceId ?? opts.workspace ?? globalOpts.workspaceId,
     });
 });
 orbit
@@ -813,7 +903,10 @@ orbit
     .command('attach <orbit-id-or-slug>')
     .description('Attach an object to an orbit')
     .requiredOption('--type <type>', 'Object type: task, issue, vibe, idea, document')
-    .requiredOption('--id <uuid>', 'Object UUID')
+    // OrbitController::findOrbitItemObject now resolves display numbers via entityRefColumn()
+    // for the numbered types (task/issue/vibe/idea). Documents have no display number, so
+    // `--type document` still requires a UUID.
+    .requiredOption('--id <id-or-number>', 'Object UUID or display number (TS-/IS-/VB-/ID-); documents are UUID-only')
     .option('--note <text>', 'Optional note for the attachment')
     .action(async (orbitIdOrSlug, opts, cmd) => {
     const globalOpts = cmd.optsWithGlobals();
@@ -829,7 +922,7 @@ orbit
     .command('detach <orbit-id-or-slug>')
     .description('Detach an object from an orbit')
     .requiredOption('--type <type>', 'Object type: task, issue, vibe, idea, document')
-    .requiredOption('--id <uuid>', 'Object UUID')
+    .requiredOption('--id <id-or-number>', 'Object UUID or display number (TS-/IS-/VB-/ID-); documents are UUID-only')
     .action(async (orbitIdOrSlug, opts, cmd) => {
     const globalOpts = cmd.optsWithGlobals();
     await orbitDetachCommand(orbitIdOrSlug, {
@@ -906,24 +999,33 @@ intent
     .command('create <title>')
     .description('Create a new intent')
     .option('--outcome <text>', 'Desired outcome')
+    .option('--design <text>', 'Design notes (markdown)')
+    .option('--plan <text>', 'Plan notes (markdown)')
     .option('--status <status>', 'Initial status: new, design, plan, build, done, cancelled (default new)')
-    .option('--orbit <id>', 'Attach the intent to an orbit after creation')
+    // PUT /intents/{id}/orbit validates `orbit_id` as `uuid|exists:orbits,id` — unlike
+    // POST /tasks it takes no slug. `orbit list` prints the UUID (TS-adanc8).
+    .option('--orbit <uuid>', 'Attach the intent to an orbit after creation (UUID, not a slug)')
     .action(async (title, opts, cmd) => {
     const globalOpts = cmd.optsWithGlobals();
     await intentCreateCommand(title, {
         json: globalOpts.json,
         area: globalOpts.area,
         outcome: opts.outcome,
+        design: opts.design,
+        plan: opts.plan,
         status: opts.status,
         orbit: opts.orbit,
     });
 });
 intent
     .command('update <id-or-number>')
-    .description('Update an intent (title, outcome, status)')
+    .description('Update an intent (title, outcome, design, plan, status)')
     .option('--title <title>', 'New title')
     .option('--outcome <text>', 'New outcome')
+    .option('--design <text>', 'New design notes (markdown)')
+    .option('--plan <text>', 'New plan notes (markdown)')
     .option('--status <status>', 'Status: new, design, plan, build, done, cancelled')
+    .option('--log <type:content>', LOG_FLAG_HELP, collect, [])
     .action(async (idOrNumber, opts, cmd) => {
     const globalOpts = cmd.optsWithGlobals();
     await intentUpdateCommand(idOrNumber, {
@@ -931,14 +1033,17 @@ intent
         area: globalOpts.area,
         title: opts.title,
         outcome: opts.outcome,
+        design: opts.design,
+        plan: opts.plan,
         status: opts.status,
+        log: opts.log,
     });
 });
 intent
     .command('link <id-or-number>')
     .description('Link a task or issue to an intent')
     .requiredOption('--type <type>', 'Object type: task, issue')
-    .requiredOption('--id <uuid>', 'Object UUID')
+    .requiredOption('--id <uuid>', 'Object UUID (this endpoint does not accept display numbers)')
     .action(async (idOrNumber, opts, cmd) => {
     const globalOpts = cmd.optsWithGlobals();
     await intentLinkCommand(idOrNumber, {
@@ -952,7 +1057,7 @@ intent
     .command('unlink <id-or-number>')
     .description('Unlink a task or issue from an intent')
     .requiredOption('--type <type>', 'Object type: task, issue')
-    .requiredOption('--id <uuid>', 'Object UUID')
+    .requiredOption('--id <uuid>', 'Object UUID (this endpoint does not accept display numbers)')
     .action(async (idOrNumber, opts, cmd) => {
     const globalOpts = cmd.optsWithGlobals();
     await intentUnlinkCommand(idOrNumber, {
@@ -963,8 +1068,8 @@ intent
     });
 });
 intent
-    .command('orbit <id-or-number> [orbit-id]')
-    .description('Set or clear the orbit of an intent')
+    .command('orbit <id-or-number> [orbit-uuid]')
+    .description('Set or clear the orbit of an intent (the orbit is named by UUID, not by slug)')
     .option('--clear', 'Clear the orbit instead of setting one')
     .action(async (idOrNumber, orbitId, opts, cmd) => {
     const globalOpts = cmd.optsWithGlobals();
@@ -1025,6 +1130,7 @@ mission
     .option('--desc <description>', 'New description')
     .option('--outcome <text>', 'New outcome')
     .option('--end-date <date>', 'New end date (YYYY-MM-DD)')
+    .option('--log <type:content>', LOG_FLAG_HELP, collect, [])
     .action(async (idOrNumber, opts, cmd) => {
     const globalOpts = cmd.optsWithGlobals();
     await missionUpdateCommand(idOrNumber, {
@@ -1034,25 +1140,28 @@ mission
         desc: opts.desc,
         outcome: opts.outcome,
         endDate: opts.endDate,
+        log: opts.log,
     });
 });
 mission
     .command('status <id-or-number> <status>')
     .description('Set mission lifecycle status (active, completed, cancelled; only one mission can be active)')
     .option('--move-to <mission-id>', 'Mission to move unfinished work to when completing/cancelling')
+    .option('--log <type:content>', LOG_FLAG_HELP, collect, [])
     .action(async (idOrNumber, status, opts, cmd) => {
     const globalOpts = cmd.optsWithGlobals();
     await missionStatusCommand(idOrNumber, status, {
         json: globalOpts.json,
         area: globalOpts.area,
         moveTo: opts.moveTo,
+        log: opts.log,
     });
 });
 mission
     .command('link <id-or-number>')
     .description('Link a task, issue, idea, or intent to a mission (clears intent_id on tasks/issues)')
     .requiredOption('--type <type>', 'Object type: task, issue, idea, intent')
-    .requiredOption('--id <uuid>', 'Object UUID')
+    .requiredOption('--id <uuid>', 'Object UUID (this endpoint does not accept display numbers)')
     .action(async (idOrNumber, opts, cmd) => {
     const globalOpts = cmd.optsWithGlobals();
     await missionLinkCommand(idOrNumber, {
@@ -1066,7 +1175,7 @@ mission
     .command('unlink <id-or-number>')
     .description('Unlink a directly-linked item from a mission')
     .requiredOption('--type <type>', 'Object type: task, issue, idea, intent')
-    .requiredOption('--id <uuid>', 'Object UUID')
+    .requiredOption('--id <uuid>', 'Object UUID (this endpoint does not accept display numbers)')
     .action(async (idOrNumber, opts, cmd) => {
     const globalOpts = cmd.optsWithGlobals();
     await missionUnlinkCommand(idOrNumber, {