@shardflux/cli 0.23.1 → 0.24.1

package/dist/args.js

@@ -11,9 +11,10 @@
  */
 import { parseArgs } from 'node:util';
 import { ACCOUNT_COMMANDS } from "./account-args.js";
+import { BOARD_COMMANDS } from "./board-args.js";
 import { UsageError } from "./errors.js";
 import { DEFAULT_CHOICE, MODEL_CHOICES } from "./agent-models.js";
-export const CLI_VERSION = '0.23.1';
+export const CLI_VERSION = '0.24.1';
 export const GLOBAL_OPTIONS = {
     'api-url': { type: 'string', value: '<url>', description: 'API base URL (default $SHARDFLUX_API_URL, else https://api.shardflux.dev).' },
     json: { type: 'boolean', description: 'Print machine-readable JSON on stdout (errors as JSON on stderr).' },
@@ -147,15 +148,52 @@ const LAYER_HELP = {
 };
 const KEY_COMMANDS = [
     { path: ['conversations', 'list'], summary: 'List project conversations', positionals: [], options: { all: { type: 'boolean', description: 'Fetch every page.' },
-            project: { type: 'string', value: '<id>', description: 'Project ID for a user session.' }, state: { type: 'string', value: '<state>', description: 'Conversation state.' },
-            parent: { type: 'string', value: '<id>', description: 'Children of this conversation.' }, limit: { type: 'string', value: '<count>', description: 'Page size.' }, cursor: { type: 'string', value: '<cursor>', description: 'Next page cursor.' } } },
+            project: { type: 'string', value: '<id>', description: 'Project ID for a user session.' }, org: { type: 'string', value: '<id|slug>', description: 'Signed in: the conversations of every project of this organization you work in (0.25.0+).' }, state: { type: 'string', value: '<state>', description: 'Conversation state.' },
+            parent: { type: 'string', value: '<id>', description: 'Children of this conversation.' }, 'updated-after': { type: 'string', value: '<time>', description: 'Only conversations changed after this time (RFC 3339).' },
+            limit: { type: 'string', value: '<count>', description: 'Page size.' }, cursor: { type: 'string', value: '<cursor>', description: 'Next page cursor.' } },
+        description: 'With an API key: its project’s conversations. Signed in (shard auth login) without a key: the conversations of every project you work in, across your organizations (0.25.0+); --org narrows them to one organization and --project to one project. --org uses your sign-in when you have one.',
+        examples: ['shard c list --state needs_you', 'shard c list --org acme --all --json'] },
+    { path: ['conversations', 'feed'], summary: 'Print project conversations as they change', positionals: [], options: {
+            project: { type: 'string', value: '<id>', description: 'Project ID for a user session.' }, org: { type: 'string', value: '<id|slug>', description: 'Signed in: every project of this organization you work in (0.25.0+).' }, cursor: { type: 'string', value: '<cursor>', description: 'Continue after this feed cursor (--json prints it with each change).' }
+        },
+        description: 'Prints each conversation the moment it changes, until interrupted: "<id>  <title>  <state>", and why it needs you when it does; --json prints one {conversation, cursor} object per line. With an API key: its project. Signed in without a key: every project you work in, on one cursor (0.25.0+); --org follows one organization’s projects and uses your sign-in when you have one.',
+        examples: ['shard c feed', 'shard c feed --org acme --json'] },
     { path: ['conversations', 'resume'], summary: 'Resume a saved conversation in a fresh VM', positionals: [{ name: 'id', required: true }], options: {} },
     { path: ['conversations', 'reader'], summary: 'Open a read-only project space reader', positionals: [{ name: 'project_id', required: true }], options: {} },
-    { path: ['conversations', 'get'], summary: 'Show a conversation and its current VM', positionals: [{ name: 'id', required: true }], options: {} },
-    { path: ['conversations', 'send'], summary: 'Send the next user turn', positionals: [{ name: 'id', required: true }, { name: 'text', required: true, variadic: true, words: true }], options: {} },
+    { path: ['conversations', 'get'], summary: 'Show a conversation and its current VM', positionals: [{ name: 'id', required: true }], options: {},
+        description: 'Prints its title, state and branch, why it needs you when it does, then one line per port a process listens on in its computer: the port, the program, and its URL once exposed (or 127.0.0.1 only). --json returns the conversation with pty_id, listening_ports and listening_ports_at.' },
+    { path: ['conversations', 'watch'], summary: 'Watch a conversation’s terminal live, read-only', positionals: [{ name: 'id', required: true }], options: {},
+        description: 'Shows the terminal the conversation’s agent runs in (its pty_id, terminal conversations) as the agent works: its last 256 KiB, then live output, until the agent’s session exits or you press Ctrl-C. Nothing you type reaches it. Watching never keeps the computer awake while the agent is idle, and ends when the computer sleeps. The output is the terminal’s own bytes, so there is no --json form; shard agents logs <id> --json returns recent output as JSON.',
+        examples: ['shard conversations watch conv_a7k2m4q6s3t5v7x2z4b6d3f5h7'] },
+    { path: ['conversations', 'send'], summary: 'Send the next user turn', positionals: [{ name: 'id', required: true }, { name: 'text', variadic: true, words: true }], options: {
+            file: { type: 'string', multiple: true, value: '<path>', description: 'Attach a file (repeatable, up to 20 of 64 MiB each): it lands in the conversation’s computer before the message, which lists its path there (0.25.0+).' }
+        },
+        description: 'Text and files reach the conversation’s agent as its next turn. A conversation that ended is restored into a fresh computer first. Attached files keep their names under /home/user/.shardflux/attachments/<conversation id>/; each stored path is printed.',
+        examples: ['shard conversations send conv_6qz2dmu4kd3xa7v5l2hgmfnpjy "Fix the failing export test"', 'shard conversations send conv_6qz2dmu4kd3xa7v5l2hgmfnpjy "Why does this page break?" --file screenshot.png --file console.log'] },
     { path: ['conversations', 'wait'], summary: 'Wait for a result or question', positionals: [{ name: 'id', required: true }], options: {
             until: { type: 'string', value: '<states>', description: 'Comma-separated conversation states.' }, timeout: { type: 'string', value: '<seconds>', description: 'Wait for 0..900 seconds (default 900).' }
         } },
+    { path: ['conversations', 'permissions'], summary: 'List what a conversation’s agent asked permission for, oldest first', positionals: [{ name: 'id', required: true }], options: {
+            state: { type: 'string', value: '<state>', description: 'pending, answered or canceled (default every state).' }, all: { type: 'boolean', description: 'Fetch every page.' },
+            limit: { type: 'string', value: '<count>', description: 'Page size (1..200, default 50).' }, cursor: { type: 'string', value: '<cursor>', description: 'Next page cursor.' }
+        },
+        description: 'A conversation is needs_you while its agent waits on a permission request: to run a command, edit a file or fetch a URL. Each line is the request id, its state, what the agent wants to do, the command, path or URL, and the decision once answered. Answer a pending one with shard conversations answer (0.25.0+).',
+        examples: ['shard conversations permissions <conversation-id> --state pending', 'shard c permissions <conversation-id> --all --json'] },
+    { path: ['conversations', 'answer'], summary: 'Answer a permission request (allow, always or deny) or the agent’s question (--pick)', positionals: [{ name: 'id', required: true }, { name: 'permission_id', required: true }, { name: 'decision' }], options: {
+            pick: { type: 'string', multiple: true, value: '<option|question=option>', description: 'The option you pick for the agent’s question (0.25.0+): its label or your own words; repeat it for a multi-select question; "<question>=<option>" when it asks several.' }
+        },
+        description: 'allow lets the agent run the tool this once, always also lets its harness stop asking for this kind of call, deny refuses it (allow_once, allow_always and deny work too). The agent’s question (a request with questions, such as Claude Code’s AskUserQuestion) takes --pick, or deny to decline it; the agent gets exactly what you picked. The agent goes on with its turn, and a parked computer wakes to take the answer. A request answered already, here or where the agent runs, is refused with permission_answered (0.25.0+).',
+        examples: ['shard conversations answer <conversation-id> <permission-id> allow', 'shard c answer <conversation-id> <permission-id> --pick Blue', 'shard c answer <conversation-id> <permission-id> deny'] },
+    { path: ['conversations', 'transcript'], summary: 'Print a conversation’s transcript: its agent’s own JSONL (0.25.0+)', positionals: [{ name: 'id', required: true }], options: {
+            offset: { type: 'string', value: '<bytes>', description: 'Start at this byte offset, such as the next_offset of an earlier read.' },
+            session: { type: 'string', value: '<id>', description: 'An earlier session of the conversation (default: the latest).' },
+            follow: { type: 'boolean', short: 'f', description: 'Keep printing new lines as they are stored, until Ctrl-C.' }
+        },
+        description: 'Prints the Claude Code or Codex transcript byte for byte, as the agent wrote it, for working, parked and finished conversations alike, without waking a VM. With --json: one object (session_id, file, offset, next_offset, size, data); with --follow, one object per line.',
+        examples: ['shard c transcript conv_k3m5q7s2u4w6y3b5d7f2h4j6ln > session.jsonl', 'shard c transcript conv_k3m5q7s2u4w6y3b5d7f2h4j6ln --follow | jq -c \'select(.type=="assistant")\''] },
+    { path: ['conversations', 'events'], summary: 'Follow a conversation live: state, transcript, reply text and tool calls (0.25.0+)', positionals: [{ name: 'id', required: true }], options: {},
+        description: 'Streams the conversation until Ctrl-C, one line per event: state changes, new transcript lines and tool calls, with the reply written as the agent streams it. With --json: one event per line, {"type":"conversation"|"transcript"|"delta","id":…} with the conversation, the transcript lines or the ACP session updates.',
+        examples: ['shard c events conv_k3m5q7s2u4w6y3b5d7f2h4j6ln', 'shard c events conv_k3m5q7s2u4w6y3b5d7f2h4j6ln --json | jq -c \'select(.type=="delta")\''] },
     { path: ['conversations', 'land'], summary: 'Record the landing action performed by the agent', positionals: [{ name: 'id', required: true }, { name: 'action', required: true }], options: { into: { type: 'string', value: '<ref>', description: 'Destination branch or PR URL.' } } },
     { path: ['conversations', 'move'], summary: 'Move at the end of the turn', positionals: [{ name: 'id', required: true }, { name: 'to', required: true }], options: {} },
     { path: ['conversations', 'landing'], summary: 'Show or set how finished conversations reach this checkout', positionals: [{ name: 'mode' }, { name: 'backup' }], options: {
@@ -1296,7 +1334,19 @@ const AGENT_COMMANDS = [
             detach: { type: 'boolean', description: 'Start it in the cloud without opening it here.' },
         }, examples: ['shard move --last', 'shard move --list', 'shard move --session 3d085e35-aa66-4866-9a53-f09719d6767c --detach --json'] },
     { path: ['device', 'requests'], summary: 'Review local device requests waiting for approval', positionals: [], options: {} },
-    ...['approve', 'deny'].map((action) => ({ path: ['device', action], summary: `${action} a local device request`, positionals: [{ name: 'id', required: true }], options: action === 'approve' ? { always: { type: 'boolean', description: 'Allow matching requests for this project; never for outside-folder access.' } } : {} })),
+    ...['approve', 'deny'].map((action) => ({ path: ['device', action], summary: `${action} a local device request`, positionals: [{ name: 'id', required: true }], options: action === 'approve' ? { always: { type: 'boolean', description: 'Allow matching requests for this project, or for a folder request (0.25.0+) that folder and what is inside it; never for other access outside the conversation folder.' } } : {} })),
+    { path: ['conversations', 'start'], summary: 'Start a conversation from the project or on your machine, no folder needed (0.25.0+)', positionals: [], options: {
+            project: { type: 'string', value: '<id>', description: 'The project (default: the API key’s, or this computer’s selected project).' },
+            home: { type: 'boolean', description: 'Start on your machine’s home, without a repository: the agent runs in /home/user and starts threads in the project’s repositories.' },
+            repo: { type: 'string', value: '<remote>', description: 'The repository (default: the project’s most recently active one).' },
+            branch: { type: 'string', value: '<name>', description: 'Start from this branch’s newest saved point in the project (default main, then master).' },
+            app: { type: 'string', value: '<claude|codex>', description: 'Agent app (default claude).' },
+            title: { type: 'string', value: '<text>', description: 'The conversation’s title (default: named by its first message).' },
+            ...MODEL_OPTIONS,
+            prompt: { type: 'string', value: '<text>', description: 'The first message.' },
+            file: { type: 'string', multiple: true, value: '<path>', description: 'Attach a file to the first message (repeatable, up to 20 of 64 MiB each; needs --prompt).' },
+        }, description: 'Starts a Claude Code or Codex conversation in its own cloud computer straight from the project: the repository is checked out from the project’s saved branches, so no local folder is needed. --home starts a coordinator on your machine instead, which spawns threads in the project’s repositories. Prints the conversation id, key and state; open it with shard agents open <id>.',
+        examples: ['shard conversations start --prompt "Add CSV export to the invoices page"', 'shard conversations start --repo https://github.com/acme/app.git --branch main --app codex --prompt "Fix the flaky login test" --file trace.log', 'shard conversations start --home --title "Plan the billing work" --json'] },
     { path: ['conversations', 'try'], summary: 'Try a conversation in a synced local worktree', positionals: [{ name: 'conversation', required: true }], options: { path: { type: 'string', value: '<path>', description: 'Local project checkout.' }, stop: { type: 'boolean', description: 'Stop the device helper’s local sync and ports.' } } },
     { path: ['agents', 'targets'], summary: 'Detect apps or configure managed desktop connections', positionals: [{ name: 'agent' }], options: {
             remove: { type: 'boolean', description: 'Remove this agent’s managed entries, or all entries for this API URL.' },
@@ -1374,12 +1424,97 @@ const SETTINGS_COMMANDS = [{
         description: 'Shows the title marker, where new conversations open and the terminal app (change those two with "shard agents targets --open-in" and "--terminal"). The menu bar and desktop apps change the same settings.',
         examples: ['shard settings', 'shard settings --title-prefix SF', 'shard settings --title-prefix none', 'shard settings --title-prefix default --json'],
     }];
-export const COMMANDS = [...ACCOUNT_COMMANDS.filter((c) => c.path[0] !== 'templates'), ...AGENT_COMMANDS, ...AGENT_CREDENTIAL_COMMANDS, ...AGENT_ACCOUNT_COMMANDS, ...ACCOUNT_ALIASES, ...CLI_PROXY_COMMANDS, ...MENUBAR_COMMANDS, ...SETTINGS_COMMANDS, ...KEY_COMMANDS, ...ACCOUNT_COMMANDS.filter((c) => c.path[0] === 'templates')];
+/** The board's input bar from a terminal (0.25.0+): route a line of input, ask a quick question about the work. */
+const BOARD_SCOPE = {
+    org: { type: 'string', value: '<id|slug>', description: 'Organization whose board to read (default: the saved one, shard orgs use, else your only organization). Slugs need your signed-in session.' },
+    project: { type: 'string', value: '<id|slug>', description: 'A project of it: the input leans to it when nothing else decides.' },
+};
+const BOARD_SCOPE_HELP = 'Reads your organization’s projects and open tasks with your signed-in session; with SHARDFLUX_API_KEY set (or only a saved project API key), that key’s project. It never starts work and never wakes a computer.';
+const ROUTER_COMMANDS = [
+    {
+        path: ['route'],
+        summary: 'Route input like the board’s input bar: its project, task, question or steer, split per task (0.25.0+)',
+        description: [
+            'Decides which project the input belongs to (or your home, for personal work), whether it is a new task, a question or a steer for an open task, and splits input that asks for several tasks into your own words per task, each with a title. "?" or "quick question" at the start makes it a question.',
+            BOARD_SCOPE_HELP,
+            'Prints the kind and where it goes, then each part. With --json: the RouterResult (kind, parts with text, title, project_id and home, task_ref, confidence, uncertain, forced, routed_by, latency_ms).',
+        ].join('\n\n'),
+        positionals: [{ name: 'text', variadic: true, words: true, required: true }],
+        options: {
+            task: { type: 'string', value: '<task-id>', description: 'The open task you point at (task_…): input about it steers it, unless it asks about it.' },
+            ...BOARD_SCOPE,
+        },
+        examples: ['shard route "fix the hero image on the landing page and add a GPU row to the pricing table"', 'shard route --task task_healthzhealthzhealthzhealt return 503 instead of 500 when the database is down', 'shard route "? is the deploy done" --json'],
+    },
+    {
+        path: ['ask'],
+        summary: 'Ask a quick question about your work, answered from the board as it is written (0.25.0+)',
+        description: [
+            'Answers from your tasks, their plans and states, sealed reports, the conversations behind them and what their agents last wrote. The answer streams to standard output as it is written; one that needs work ends with "Make it a task?".',
+            BOARD_SCOPE_HELP,
+            'With --json: the whole answer as one object (text, needs_work, sources, answered_by, first_token_ms, total_ms).',
+        ].join('\n\n'),
+        positionals: [{ name: 'question', variadic: true, words: true, required: true }],
+        options: {
+            task: { type: 'string', value: '<task-id>', description: 'The task the question is about (task_…).' },
+            ...BOARD_SCOPE,
+        },
+        examples: ['shard ask what is the healthz work doing right now', 'shard ask --task task_healthzhealthzhealthzhealt "is it done?"', 'shard ask "what is blocking the pricing page?" --json'],
+    },
+];
+/** The project a drive or models command acts in (0.25.0+). */
+const PROJECT_SCOPE = {
+    project: { type: 'string', value: '<id|slug>', description: 'The project (default: the API key’s, else your default project). Signed in, any of your projects, by id or slug.' },
+};
+const DRIVE_HELP = 'The project drive keeps a project’s files: the screenshots, logs, reports and notes your agents and people save and read by path, the same from a phone, a script or another agent whether the project’s computers are working, asleep or gone. Paths are relative to the project space root, the names agents see under /shardflux/project (tasks/t_ab12/evidence/healthz.png, BOARD.md). Every save is a new version named by the SHA-256 of its bytes, and every version stays readable by its sha256, also after the path is overwritten or removed.';
+const DRIVE_COMMANDS = [
+    { path: ['drive', 'ls'], summary: 'List the project drive’s files: size, saved time, type and path (0.25.0+)', positionals: [{ name: 'prefix' }], options: {
+            ...PROJECT_SCOPE,
+            all: { type: 'boolean', description: 'Fetch every page.' },
+            limit: { type: 'string', value: '<n>', description: 'Page size (1 to 1000, default 200).' },
+            cursor: { type: 'string', value: '<cursor>', description: 'Continue from a previous page.' },
+        }, description: `${DRIVE_HELP} Lists the current version of each file, by path; a prefix such as tasks/t_ab12/ lists only that folder. --json returns data (each file with its sha256) and next_cursor.`,
+        examples: ['shard drive ls', 'shard drive ls tasks/t_ab12/evidence/', 'shard drive ls --all --json'] },
+    { path: ['drive', 'get'], summary: 'Read a file from the project drive: its bytes to standard output, or to a file with -o (0.25.0+)', positionals: [{ name: 'path', required: true }], options: {
+            ...PROJECT_SCOPE,
+            sha256: { type: 'string', value: '<hex>', description: 'Read exactly this version (the current one or an earlier one).' },
+            out: { type: 'string', short: 'o', value: '<file>', description: 'Write the bytes to this file.' },
+        }, description: `${DRIVE_HELP} The bytes are checked against their SHA-256 before they are written. --json without -o returns the file as content_base64 with its sha256, size and content_type.`,
+        examples: ['shard drive get BOARD.md', 'shard drive get tasks/t_ab12/evidence/healthz.png -o healthz.png', 'shard drive get BOARD.md --sha256 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08'] },
+    { path: ['drive', 'put'], summary: 'Save a file to the project drive as a new version, and print its path and sha256 (0.25.0+)', positionals: [{ name: 'local-file', required: true }, { name: 'drive-path' }], options: {
+            ...PROJECT_SCOPE,
+            'content-type': { type: 'string', value: '<type>', description: 'Stored with the file (default: from its extension, e.g. .png image/png, .md text/markdown).' },
+        }, description: `${DRIVE_HELP} The drive path defaults to the file’s name; - reads the file from standard input (name the drive path). Saving the bytes that are already current keeps that version.`,
+        examples: ['shard drive put BOARD.md', 'shard drive put ./out/healthz.png tasks/t_ab12/evidence/healthz.png', 'git diff | shard drive put - tasks/t_ab12/review.diff --json'] },
+    { path: ['drive', 'rm'], summary: 'Remove a file from the project drive; its versions stay readable by sha256 (0.25.0+)', positionals: [{ name: 'path', required: true }], options: { ...PROJECT_SCOPE },
+        description: `${DRIVE_HELP} After rm the path no longer lists or reads; shard drive get <path> --sha256 <hex> still reads each of its versions.`,
+        examples: ['shard drive rm tasks/t_ab12/notes/draft.md'] },
+];
+const MODELS_HELP = 'The model template: which agent app (harness), model and effort each role of a task runs with, from the Claude and Codex accounts your organization connected. master plans and coordinates, builder does the work, hard takes the hardest parts, light the small ones, and reviewer reviews with a fresh context. The primary provider runs master, builder and hard; the other one, light and reviewer. A role whose account waits for its next usage window shows until when, and what the other provider would run now.';
+const MODEL_COMMANDS = [
+    { path: ['models'], summary: 'Show which harness, model and effort each role of a task runs with (0.25.0+)', positionals: [], options: {
+            ...PROJECT_SCOPE,
+            harness: { type: 'string', value: '<claude|codex>', description: 'The provider the task runs on: keeps master, builder and hard work on it.' },
+            attempt: { type: 'string', value: '<n>', description: 'A retry after a failure (1 to 10): retries move to the other provider, or one tier up when only one is connected.' },
+        }, description: `${MODELS_HELP} --json returns the template: primary, secondary, connected and roles, with each role’s harness, model and effort exactly as shard conversations start --app, --model and --effort take them.`,
+        examples: ['shard models', 'shard models --harness codex --attempt 1', 'shard models --json'] },
+    { path: ['models', 'primary'], summary: 'Make Claude or Codex the primary provider of this project or your organization, or clear it (0.25.0+)', positionals: [{ name: 'claude|codex|clear', required: true }], options: {
+            ...PROJECT_SCOPE,
+            org: { type: 'string', value: '<id|slug>', description: 'Set the organization’s default for every project instead (owners and admins, signed in).' },
+        }, description: `${MODELS_HELP} The primary is this project’s choice when it has one, else the organization’s, else the provider connected first; clear removes the choice. Prints the template with the new primary.`,
+        examples: ['shard models primary codex', 'shard models primary claude --org acme', 'shard models primary clear --project web'] },
+];
+export const COMMANDS = [...ACCOUNT_COMMANDS.filter((c) => c.path[0] !== 'templates'), ...AGENT_COMMANDS, ...ROUTER_COMMANDS, ...AGENT_CREDENTIAL_COMMANDS, ...AGENT_ACCOUNT_COMMANDS, ...ACCOUNT_ALIASES, ...CLI_PROXY_COMMANDS, ...MENUBAR_COMMANDS, ...SETTINGS_COMMANDS, ...KEY_COMMANDS, ...BOARD_COMMANDS, ...DRIVE_COMMANDS, ...MODEL_COMMANDS, ...ACCOUNT_COMMANDS.filter((c) => c.path[0] === 'templates')];
 const GROUPS = {
     device: 'Local device approvals',
     'cli-proxy': 'Your hosted CLIProxyAPI, reachable at http://127.0.0.1:8317 on this computer and in every VM',
     menubar: 'macOS menu bar app',
     conversations: 'Project conversations, branches and messages',
+    task: 'Tasks on the board, in your own words: add, show, edit, move, steer, delete and clear them (0.25.0+)',
+    'needs-you': 'Everything your agents wait on, oldest first, and one answer command for each (0.25.0+)',
+    approvals: 'The approval mode and always-allow rules your agents work under (0.25.0+)',
+    drive: 'The project drive: files every agent, phone and person of the project reads and writes, each version kept by its SHA-256 (0.25.0+)',
+    models: 'The model template: which harness, model and effort each role of a task runs with, and the primary provider (0.25.0+)',
     agents: 'Cloud agent sessions and copied credentials',
     auth: 'Create an account and sign in (the session is saved in the credentials file); passwords, email, two-factor authentication and sessions',
     'auth password': 'Change or reset your password',
@@ -1692,6 +1827,17 @@ export function parseCommandLine(argv, options = {}) {
         if (positionals[1] === undefined && flagged[0] !== undefined && positionals.length === 1)
             positionals.push(flagged[0]);
     }
+    if (command.path[0] === 'volumes' && ['attach', 'detach'].includes(command.path[1] ?? '')) {
+        if (values.machine === true && values.template === true)
+            throw new UsageError('Choose --machine or --template');
+        if (values.path !== undefined && values.template !== true)
+            throw new UsageError('--path requires --template');
+        const defaults = values.machine === true || values.template === true;
+        if (positionals.length < (defaults ? 1 : 2))
+            throw new UsageError(`missing <volume> for "shard ${command.path.join(' ')}"`);
+        if (defaults && positionals.length !== 1)
+            throw new UsageError('Supply one volume with --machine or --template');
+    }
     const specs = command.positionals;
     const variadic = specs.at(-1)?.variadic === true;
     const required = specs.filter((s) => s.required && !s.variadic).length;
@@ -1781,7 +1927,7 @@ export const EXIT_CODE_HELP = [
 /** The top help's sections: every command's group (first word) is in exactly one (args.test.ts checks). */
 export const HELP_SECTIONS = [
     { title: 'Account (a user session: shard signup or shard auth login)', groups: ['signup', 'verify', 'auth', 'setup', 'env', 'orgs', 'projects', 'api-keys', 'members', 'invitations', 'billing', 'audit', 'account'] },
-    { title: 'Cloud agents (shard ./ starts one; a project API key)', groups: ['conversations', 'move', 'machine', 'template', 'agents', 'settings', 'accounts', 'device', 'cli-proxy', 'ssh-proxy'] },
+    { title: 'Cloud agents (shard ./ starts one; a project API key)', groups: ['conversations', 'board', 'task', 'needs-you', 'approvals', 'route', 'ask', 'drive', 'models', 'move', 'machine', 'template', 'agents', 'settings', 'accounts', 'device', 'cli-proxy', 'ssh-proxy'] },
     { title: 'Workspaces for your app (a project API key: SHARDFLUX_API_KEY, else the one shard setup saved)', groups: ['login', 'whoami', 'status', 'usage', 'workspaces', 'files', 'operations', 'executions', 'secrets', 'credentials', 'volumes', 'egress'] },
     { title: 'Templates for your app’s workspaces (not for cloud agents; publish and archive use the session, the rest the API key)', groups: ['templates'] },
     { title: 'Other', groups: ['menubar', 'update', 'feedback', 'version'] },

package/dist/board-args.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The Orchestrator board's command table (0.25.0+, SDK 0.28.0): `shard board`, `shard task …`, `shard needs-you …` and
+ * `shard approvals …`. Pure data like args.ts, which merges it into COMMANDS; board-commands.ts has the handlers.
+ */
+import type { CommandSpec } from './args.js';
+export declare const BOARD_COMMANDS: CommandSpec[];

package/dist/board-args.js

@@ -0,0 +1,155 @@
+const PROJECT_FILTER = { project: { type: 'string', value: '<id>', description: 'Only this project.' } };
+const PROJECT = { project: { type: 'string', value: '<id>', description: 'The project (default: the API key’s).' } };
+const BUCKET_FLAGS = (verb) => ({
+    now: { type: 'boolean', description: `${verb} Now.` },
+    next: { type: 'boolean', description: `${verb} Next.` },
+    later: { type: 'boolean', description: `${verb} Later.` },
+});
+const ORDER = {
+    after: { type: 'string', value: '<task-id>', description: 'Place it right after this task of its bucket.' },
+    first: { type: 'boolean', description: 'Place it first in its bucket.' },
+};
+const MODES = 'ask sends every permission request to you (shard needs-you); routine approves tests, builds, reads and installs for you; trusted approves everything except deploys, pushes to main and spending.';
+export const BOARD_COMMANDS = [
+    {
+        path: ['board'],
+        summary: 'Show the board: what needs you, then every task in Now, Next and Later (0.25.0+)',
+        positionals: [],
+        options: { ...PROJECT_FILTER, follow: { type: 'boolean', short: 'f', description: 'Keep printing each change as it happens, until Ctrl-C.' } },
+        description: [
+            'One board on every device: what waits on you comes first, oldest first, each with its id (shard needs-you answer',
+            'takes it) and what is asked. Then the tasks of Now, Next and Later in order: id, state (queued, working, needs_you,',
+            'done, unverified, failed), title or your words, and project. Reading the board never wakes a computer.',
+            '',
+            '--follow keeps printing changes from the held feed: a changed task with its bucket (or deleted, cleared), a sealed',
+            'report with its evidence, what started or stopped waiting on you, the approval policy. --json prints the board;',
+            'with --follow, the board on the first line, then one feed answer per line.',
+        ].join('\n'),
+        examples: ['shard board', 'shard board --follow', `shard board --json | jq -r '.needs_you[] | "\\(.id)\\t\\(.ask)"'`],
+    },
+    {
+        path: ['task', 'add'],
+        summary: 'Add a task in your own words (0.25.0+)',
+        positionals: [{ name: 'words', variadic: true, words: true, required: true }],
+        options: {
+            ...PROJECT,
+            next: { type: 'boolean', description: 'Add it to Next (default: Now).' },
+            later: { type: 'boolean', description: 'Add it to Later.' },
+            home: { type: 'boolean', description: 'A personal task: it runs on the project’s machine home, without a repository.' },
+            after: { type: 'string', value: '<task-id>', description: 'Place it right after this task of its bucket (default: last).' },
+            first: { type: 'boolean', description: 'Place it first in its bucket.' },
+        },
+        description: 'Your words are kept exactly as you wrote them. The project’s master agent picks the task up and starts the work; its reports arrive on the board (shard task show). Prints the task id, its bucket and its state.',
+        examples: ['shard task add Fix the wake race in resume', 'shard task add --later "Try a shorter pricing headline"', 'shard task add --first Hotfix the login redirect'],
+    },
+    {
+        path: ['task', 'show'],
+        summary: 'Show a task, its plan and every report sealed for it (0.25.0+)',
+        positionals: [{ name: 'id', required: true }],
+        options: {},
+        description: 'Prints its title or your words, its state, bucket and project, your exact words, the plan with each step’s state, the conversations that work on it, then each report oldest first: milestone, title, outcome and evidence (tests 12/12, live probe 200, screenshot) with the command, URL or file behind each. --json returns {task, reports}.',
+        examples: ['shard task show task_h7g4d7tqyv2pz3a2npyo4rpgzq', 'shard task show task_h7g4d7tqyv2pz3a2npyo4rpgzq --json | jq ".reports[-1].evidence"'],
+    },
+    {
+        path: ['task', 'edit'],
+        summary: 'Edit, move, keep or clear a task (0.25.0+)',
+        positionals: [{ name: 'id', required: true }],
+        options: {
+            text: { type: 'string', value: '<words>', description: 'New words; its master hears the change.' },
+            title: { type: 'string', value: '<title>', description: 'A short title ("" removes it).' },
+            ...BUCKET_FLAGS('Move it to'),
+            ...ORDER,
+            keep: { type: 'boolean', description: 'Keep an agent’s suggestion as a task of your own.' },
+            clear: { type: 'boolean', description: 'Clear it from the board (--no-clear brings it back).' },
+        },
+        description: 'Moving a task (--now, --next, --later, --after, --first) sets the order its master works in. Prints the task as shard board lists it.',
+        examples: ['shard task edit task_h7g4d7tqyv2pz3a2npyo4rpgzq --first', 'shard task edit task_h7g4d7tqyv2pz3a2npyo4rpgzq --next --title "Wake race"', 'shard task edit task_h7g4d7tqyv2pz3a2npyo4rpgzq --keep'],
+    },
+    {
+        path: ['task', 'rm'],
+        summary: 'Delete a task; its master stops the work (0.25.0+)',
+        positionals: [{ name: 'id', required: true }],
+        options: {},
+        description: 'Its follow-ups go with it, on every device.',
+    },
+    {
+        path: ['task', 'steer'],
+        summary: 'Send steering words to a task’s master (0.25.0+)',
+        positionals: [{ name: 'id', required: true }, { name: 'words', variadic: true, words: true, required: true }],
+        options: {},
+        description: 'Your words go to the agent that runs the task, which adjusts its plan. The task keeps its own words.',
+        examples: ['shard task steer task_h7g4d7tqyv2pz3a2npyo4rpgzq use postgres instead'],
+    },
+    {
+        path: ['task', 'clear-done'],
+        summary: 'Clear every finished task from the board (0.25.0+)',
+        positionals: [],
+        options: PROJECT_FILTER,
+        description: 'Clears done and unverified tasks on every device. shard task show <id> still reads their reports.',
+    },
+    {
+        path: ['needs-you'],
+        summary: 'List what waits on you, oldest first (0.25.0+)',
+        positionals: [],
+        options: PROJECT_FILTER,
+        description: [
+            'Everything your agents wait on, across the board: permission requests (perm_…), questions (cq_…, ask_…),',
+            'credential requests (cred_…), finished work to land (land_…) and Later tasks to keep or clear (prune_…). Each line is',
+            'the id, what is asked, and the command, options or branch behind it. Answer with shard needs-you answer <id>.',
+            '--json returns {data}.',
+        ].join('\n'),
+        examples: ['shard needs-you', 'shard needs-you --json'],
+    },
+    {
+        path: ['needs-you', 'answer'],
+        summary: 'Answer something that waits on you (0.25.0+)',
+        positionals: [{ name: 'id', required: true }, { name: 'decision' }],
+        options: {
+            everywhere: { type: 'boolean', description: 'With always: the rule covers every project.' },
+            text: { type: 'string', value: '<answer>', description: 'Your answer to an agent’s question.' },
+            pick: { type: 'string', multiple: true, value: '<option|question=option>', description: 'The option you pick for an agent’s question in a permission request (repeatable for a multi-select question; "<question>=<option>" when it asks several).' },
+            keep: { type: 'string', multiple: true, value: '<task-id>', description: 'Later tasks: keep these (repeatable); the rest are cleared.' },
+        },
+        description: [
+            'One command for every kind:',
+            '  perm_…    allow (this once), always (also adds the always-allow rule for the project; --everywhere for every',
+            '            project) or deny; an agent’s question takes --pick',
+            '  cq_…      --text <answer>: the agent gets it as its next message',
+            '  ask_…     --text <answer>: the task’s master gets it',
+            '  cred_…    deny (the value goes through the credential request, sealed for its computer)',
+            '  land_…    land (the worker merges its branch and pushes it), keep (the branch stays) or discard',
+            '  prune_…   --keep <task-id> for each task to keep, keep for all of them, or discard to clear them',
+            'The agent goes on as soon as you answer.',
+        ].join('\n'),
+        examples: ['shard needs-you answer perm_01a1300c-0000-7000-8000-000000000001 always', 'shard needs-you answer ask_rep_66cbevz65m72ij7mbiyrw4xvdy --text "eu-north-1"', 'shard needs-you answer land_conv_id4zts6jxsqraju2pggr55n3tq land'],
+    },
+    {
+        path: ['approvals'],
+        summary: 'Show the approval mode and the always-allow rules your agents work under (0.25.0+)',
+        positionals: [],
+        options: {},
+        description: `The mode answers the permission requests of your board’s conversations before they reach you: ${MODES} A rule always allows a tool for commands (or paths, URLs) that start with its pattern. Prints the default mode, each project’s own mode, then each rule: its id, tool, pattern and project.`,
+    },
+    {
+        path: ['approvals', 'set'],
+        summary: 'Set the approval mode of a project or the default (0.25.0+)',
+        positionals: [{ name: 'mode', required: true }],
+        options: { ...PROJECT, default: { type: 'boolean', description: 'Set the default mode, for every project without a mode of its own.' } },
+        description: `${MODES} default puts the project back on the default mode. Requests already waiting that the new mode covers are answered at once.`,
+        examples: ['shard approvals set trusted', 'shard approvals set ask --project 01a1415f-759f-7fb0-9d56-973ed5d27465', 'shard approvals set default'],
+    },
+    {
+        path: ['approvals', 'allow'],
+        summary: 'Always allow a tool for commands that start with a pattern (0.25.0+)',
+        positionals: [{ name: 'tool', required: true }, { name: 'pattern', variadic: true, words: true, required: true }],
+        options: { ...PROJECT, everywhere: { type: 'boolean', description: 'Cover every project.' } },
+        description: 'The tool as the agent’s harness names it (Bash, WebFetch, Edit) and the command prefix, path or URL it allows: "shard approvals allow Bash pnpm test" allows pnpm test and pnpm test --watch; "" allows every use of the tool. Waiting requests the rule covers are answered at once. Prints the rule’s id, tool, pattern and project.',
+        examples: ['shard approvals allow Bash pnpm test', 'shard approvals allow WebFetch https://docs.shardflux.dev/'],
+    },
+    {
+        path: ['approvals', 'remove'],
+        summary: 'Remove an always-allow rule (0.25.0+)',
+        positionals: [{ name: 'rule-id', required: true }],
+        options: {},
+    },
+];

package/dist/board-commands.d.ts

@@ -0,0 +1,62 @@
+/**
+ * The Orchestrator board (0.25.0+, SDK 0.28.0): `shard board` (with --follow), `shard task add|show|edit|rm|steer|
+ * clear-done`, `shard needs-you [answer]` and `shard approvals [set|allow|remove]`. The command table is board-args.ts.
+ *
+ * Every command uses the project API key (SHARDFLUX_API_KEY, else the saved one): its board is the key's project.
+ * Text output is one line per item, tab-separated, id first; --json prints the API's objects.
+ */
+import type { ApprovalPolicy, ApprovalRule, Board, BoardUpdate, NeedsYouAnswer, NeedsYouAnswered, NeedsYouItem, Task, TaskDetail, TaskReport } from '@shardflux/sdk';
+import type { Handler } from './commands.js';
+/** A task as people read it: its title once it has one, else your words, on one line of at most `max` characters. */
+export declare function taskLabel(t: Pick<Task, 'title' | 'text'>, max?: number): string;
+/**
+ * One task as `shard board` lists it: id, state (with why it waits to start: "queued (Claude usage resets 15:00)"),
+ * title or words (a follow-up ↳, a suggestion marked), project.
+ */
+export declare function taskLine(t: Task): string;
+/** One item that waits on you: its id, what is asked, then the command, the suggested answers or the branch behind it. */
+export declare function needsLine(n: NeedsYouItem): string;
+/** A sealed report as --follow prints it: id, milestone, title, then its evidence labels. */
+export declare function reportLine(r: TaskReport): string;
+/** The board as text: Needs you first (oldest first), then Now, Next and Later in their order. */
+export declare function boardText(b: Pick<Board, 'tasks' | 'needs_you'>): string;
+/** The approval policy on one line: the default, each project's own mode, the number of rules. */
+export declare function policyLine(p: ApprovalPolicy): string;
+/** One always-allow rule: id, tool, the pattern it allows, its project. */
+export declare function ruleLine(r: ApprovalRule): string;
+/** `shard approvals`: the default mode, each project's own mode, then each rule. */
+export declare function policyText(p: ApprovalPolicy): string;
+/**
+ * `shard board --follow`: the lines of each feed answer. A changed task is its board line plus its bucket (deleted,
+ * cleared once gone); a sealed report its report line; an item that started waiting on you its needs line, one that
+ * stopped `<id>\tresolved`; a policy change one line. After a reset the whole board is printed again.
+ */
+export declare class BoardFollower {
+    #private;
+    constructor(board: Pick<Board, 'needs_you'>);
+    next(u: BoardUpdate): string;
+}
+/** A feed answer as `board --follow --json` prints it: the API's fields (with `board` after a reset). */
+export declare function feedJson(u: BoardUpdate): Record<string, unknown>;
+/** `shard task show`: the task, its plan and conversations, then every report oldest first with its evidence. */
+export declare function taskDetailText(d: TaskDetail): string;
+/** An item's kind from its id (perm_, cq_, ask_, cred_, land_, prune_); undefined for another id. */
+export declare function itemKind(id: string): NeedsYouItem['kind'] | undefined;
+export interface AnswerInput {
+    word?: string | undefined;
+    text?: string | undefined;
+    picks: readonly string[];
+    keep: readonly string[];
+    everywhere: boolean;
+}
+/** Whether the answer needs the item itself: the questions of a permission request, every task of a prune prompt. */
+export declare const answerNeedsItem: (id: string, a: AnswerInput) => boolean;
+/**
+ * The API answer for item `id` from the command's words and options, checked before anything is sent: each kind takes
+ * its own (needs-you.ts). `item` is the waiting item when answerNeedsItem says it is needed; without it such an answer
+ * is only checked (its `answers` or `keep` come back empty).
+ */
+export declare function needsAnswer(id: string, a: AnswerInput, item?: NeedsYouItem): NeedsYouAnswer;
+/** What an answer did, in one line. */
+export declare function answeredText(r: NeedsYouAnswered, a: NeedsYouAnswer): string;
+export declare const BOARD_HANDLERS: Record<string, Handler>;