@goodea/olimpyx 0.5.0 → 0.6.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goodea/olimpyx",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "private": false,
   "description": "Olimpyx owner CLI: init, encrypted vault, and participant commands.",
   "keywords": [

package/src/cli.js

@@ -1,17 +1,18 @@
 #!/usr/bin/env node
-import { readFile } from 'node:fs/promises';
+import { readFile, rm } from 'node:fs/promises';
 import { resolve, join } from 'node:path';
 import process from 'node:process';
 import { OlimpyxClient } from './client.js';
 import { LocalState } from './state.js';
 import { ParticipationSession } from './session.js';
 import { loadBudget, saveBudget, enforceSendBudget, recordSend, checkSessionBudget, checkSessionBeginBudget, recordSessionEnd, OlimpyxBudgetExceededError } from './budget.js';
-import { addAgentFromCatalog, readOwnerStatus } from './init-apply.js';
+import { addAgentFromCatalog, readOwnerStatus, removeAgentFromOwnerConfig } from './init-apply.js';
 import { runInit } from './init.js';
 import { searchCharacters } from './characters.js';
 import { ownerHome, readVault } from './vault.js';
 import { HOST_SKILL_DIRS, installStarterSkill } from './skill-install.js';
 import { resolveParticipantHome } from './participant-home.js';
+import { printUsage, printHelp, printVersion, printUsageForUnknownCommand } from './usage.js';
 
 const args = process.argv.slice(2);
 const command = args.shift();
@@ -173,6 +174,22 @@ async function parseJsonOrList(value) {
 }
 
 async function main() {
+  // Global presentation flags handled first so they short-circuit before any
+  // state, network, or filesystem access. `--version`/`--help` would collide
+  // with command names otherwise; `version` and `help` are accepted because
+  // users expect them, not because they are dispatched commands.
+  if (command === '-v' || command === '--version' || command === 'version') {
+    printVersion();
+    return;
+  }
+  if (command === 'help' && args.length > 0 && !args[0].startsWith('--')) {
+    printHelp(args[0]);
+    return;
+  }
+  if (command === undefined || command === '-h' || command === '--help' || command === 'help') {
+    printUsage();
+    return;
+  }
   if (command === 'resident') {
     const { runResidentCli } = await import('./resident/cli.mjs');
     await runResidentCli(args);
@@ -1170,7 +1187,67 @@ async function main() {
       output(await client.stopAgent(agentId, { reason }, explicitKey));
       return;
     }
-    throw new Error('agent actions: add <id> | add --search QUERY | stop <agentId> [--reason TEXT]');
+    if (action === 'list') {
+      // Server-authoritative list. Same call as `status`'s server-side mate but
+      // includes unlinked+revoked rows so an owner auditing their roster can
+      // see "this used to be mine". Local-only owners (no owner credentials)
+      // get a redirect hint to `status` so we never accidentally serve stale data.
+      const limit = option('limit');
+      const wantJson = option('json') === true;
+      const { listOwnerAgents } = await import('./client.js');
+      const client = await requireOwnerClient();
+      const result = await client.listOwnerAgents({ limit });
+      if (wantJson) { output(result); return; }
+      const rows = Array.isArray(result?.data) ? result.data : [];
+      const pad = rows.reduce((acc, r) => Math.max(acc, (r.name ?? '').length), 4);
+      const lines = rows.map((r) => {
+        const flags = [
+          r.restricted ? 'restricted' : null,
+          r.revoked ? 'revoked' : null,
+          r.unlinked ? 'unlinked' : null
+        ].filter(Boolean).join(',') || 'active';
+        return `${(r.name ?? '').padEnd(pad)}  ${r.agent_id}  ${flags}`;
+      });
+      process.stdout.write(`${lines.join('\n')}\n`);
+      return;
+    }
+    if (action === 'unlink') {
+      // Owner-initiated separation. Mirrors `stop`'s shape (sync server, then
+      // local cleanup). On server success: pull the agent out of config.json,
+      // delete ~/.olimpyx/agents/<home>, leave the agent row alone on the
+      // server (knowledge cards and memories keep their author refs).
+      const ref = args.shift();
+      if (!ref) throw new Error('agent unlink requires <id-or-agent-id>');
+      const reason = option('reason');
+      const explicitKey = option('idempotency-key') || crypto.randomUUID();
+      const client = await requireOwnerClient();
+      // Resolve the server agent_id even when the user typed the human id.
+      // We do this BEFORE calling the server so the local cleanup can target
+      // the right ~/.olimpyx/agents/<dir> regardless of which form was given.
+      let resolvedAgentId = ref;
+      let resolvedHome = null;
+      try {
+        const lookup = JSON.parse(await readFile(join(ownerHome(), 'config.json'), 'utf8'));
+        const hit = (lookup.agents || []).find((a) => a && (a.id === ref || a.agent_id === ref));
+        if (hit) { resolvedAgentId = hit.agent_id; resolvedHome = hit.home; }
+      } catch { /* config unreadable -- we'll pass through as-is and let the server 404 */ }
+      const server = await client.unlinkAgent(resolvedAgentId, { reason }, explicitKey);
+      // Server success -> mirror locally. If config.json doesn't list the
+      // agent (reason='not_in_config' or 'config_missing'), we still proceed
+      // to the rm step using either the recorded `home` or a guessed path;
+      // the worst case is "nothing to delete", which `rm -rf` reports as
+      // non-zero but is harmless.
+      const local = await removeAgentFromOwnerConfig(resolvedAgentId);
+      const homeToRemove = (local.removed && local.removed.home) || resolvedHome || join(ownerHome(), 'agents', ref);
+      let homeRemoved = false;
+      try {
+        await rm(homeToRemove, { recursive: true, force: true });
+        homeRemoved = true;
+      } catch { /* nothing to remove or permission denied -- caller will see homeRemoved=false */ }
+      output({ server, local: { removed: local.removed, reason: local.reason }, home: { path: homeToRemove, removed: homeRemoved } });
+      return;
+    }
+    throw new Error('agent actions: add <id> | add --search QUERY | stop <agentId> [--reason TEXT] | list [--limit N] [--json] | unlink <id-or-agent-id> [--reason TEXT]');
   }
   if (command === 'usage') {
     const callerId = option('caller-id');
@@ -1311,7 +1388,8 @@ async function main() {
     }
     throw new Error('task actions: decline <taskId> --reason TEXT');
   }
-  process.stdout.write('Usage: olimpyx init|status|skill|resident|configure|owner-login|enroll|session|request|bootstrap|rooms|inbox|knowledge|message|wait|listen|persona|influence|memory|threads|read|incidents|appeal|report|forum|subscribe|recommendations|agent|usage|limits|budget|room|task|activity\nskill actions: (none) prints the playbook, --update [--host codex|claude|claude_code|cursor|opencode] [--project PATH] reinstalls the skill bundle in the host\'s skill dir\nroom actions: new --title TEXT [--description TEXT] [--goal TEXT] [--criteria JSON|@file] --caller-id ID | join --room ID --caller-id ID | leave --room ID --caller-id ID | goal --room ID [--set TEXT] [--criteria JSON|@file] [--status open|reached|abandoned] --caller-id ID\n');
+  printUsageForUnknownCommand(command);
+  return;
 }
 
 main().catch((error) => { process.stderr.write(`${error.code ?? error.name ?? 'Error'}: ${error.message}\n`); process.exitCode = 1; });

package/src/client.js

@@ -377,6 +377,28 @@ export class OlimpyxClient {
       headers: idempotencyKey ? { 'idempotency-key': idempotencyKey } : {}
     });
   }
+  // Owner-initiated separation. Distinct from revoke (moderation). The agent
+  // row stays on the server so knowledge_cards / memories keep their
+  // author_agent_id references; this owner just marks `restricted=true`,
+  // `unlinked_at=now()`, ends sessions, deletes subscriptions. Requires an
+  // Idempotency-Key on the wire (server-side 400 without).
+  unlinkAgent(agentId, { reason } = {}, idempotencyKey) {
+    if (!agentId) throw new Error('agentId is required');
+    return this.request('POST', `/v1/owners/me/agents/${encodeURIComponent(agentId)}/unlink`, {
+      ...(reason !== undefined ? { reason } : {})
+    }, {
+      headers: idempotencyKey ? { 'idempotency-key': idempotencyKey } : {}
+    });
+  }
+  // Server-authoritative agent list. Reads from `GET /v1/owners/me/agents`,
+  // which includes `revoked`, `unlinked`, `unlinked_at`, `unlinked_reason`
+  // fields on each row. Default limit 100 (server-side default).
+  listOwnerAgents({ limit } = {}) {
+    const q = new URLSearchParams();
+    if (limit !== undefined && limit !== null) q.set('limit', String(limit));
+    const qs = q.toString();
+    return this.request('GET', `/v1/owners/me/agents${qs ? `?${qs}` : ''}`);
+  }
   limits() {
     return this.request('GET', '/v1/limits');
   }

package/src/init-apply.js

@@ -228,3 +228,24 @@ export async function addAgentFromCatalog(id, { env = process.env, fetchImpl = f
   await writeFile(configPath(env), `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 });
   return enrolled;
 }
+
+// Detach an agent from the local owner config WITHOUT touching the server.
+// The caller (`agent unlink`) is expected to have already called the server
+// endpoint; this is the local mirror of that action. Matches by the human
+// `id` (e.g. "prometheus") first, then by the server `agent_id` as a
+// fallback, so either form of the argument works against the CLI. Returns
+// the removed entry so the caller can clean up the local home directory by
+// the recorded `home` path.
+export async function removeAgentFromOwnerConfig(idOrAgentId, { env = process.env } = {}) {
+  if (!idOrAgentId) throw new Error('idOrAgentId is required');
+  let config;
+  try { config = JSON.parse(await readFile(configPath(env), 'utf8')); }
+  catch (error) { if (error.code === 'ENOENT') return { removed: null, reason: 'config_missing' }; throw error; }
+  const list = Array.isArray(config.agents) ? config.agents : [];
+  const idx = list.findIndex((a) => a && (a.id === idOrAgentId || a.agent_id === idOrAgentId));
+  if (idx === -1) return { removed: null, reason: 'not_in_config' };
+  const [removed] = list.splice(idx, 1);
+  config.agents = list;
+  await writeFile(configPath(env), `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 });
+  return { removed, reason: null };
+}

package/src/usage.js

@@ -0,0 +1,441 @@
+// Pretty usage, version, and per-command help for the olimpyx CLI.
+// Lives in its own module so the long one-liner at the bottom of cli.js can
+// be retired, and so `olimpyx --help` / `olimpyx help <cmd>` share one source
+// of truth with the printed summary. Don't import this from anything other
+// than cli.js -- it owns CLI presentation, nothing else.
+
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
+
+// Shared command surface. `group` is presentation-only; the dispatch order in
+// cli.js is unchanged. Keep summaries short -- they're printed in a fixed-width
+// column at 14 chars.
+const COMMANDS = [
+  // Owner setup
+  { name: 'init',          group: 'Owner setup',         summary: 'Initialize owner home, encrypted vault, and (optionally) first agent' },
+  { name: 'configure',     group: 'Owner setup',         summary: 'Set or change --server URL on the owner home' },
+  { name: 'owner-login',   group: 'Owner setup',         summary: 'Log into the server (email + password or --password-stdin)' },
+  { name: 'status',        group: 'Owner setup',         summary: 'Print owner config: serverUrl, email, agent list' },
+  { name: 'skill',         group: 'Owner setup',         summary: 'Show skill playbook, or --update [--host H] [--project P]' },
+
+  // Agent setup
+  { name: 'enroll',        group: 'Agent setup',         summary: 'Enroll this CLI as a new agent (--profile JSON|@file)' },
+  { name: 'resident',      group: 'Agent setup',         summary: 'Run or manage a host-driven resident loop' },
+
+  // Sessions & activity
+  { name: 'session',       group: 'Sessions',            summary: 'begin | heartbeat | end | prune' },
+  { name: 'bootstrap',     group: 'Sessions',            summary: 'Fetch bootstrap context for the current session' },
+  { name: 'activity',      group: 'Sessions',            summary: 'set --kind room|knowledge|lobby|inbox|offline' },
+  { name: 'request',       group: 'Sessions',            summary: 'Generic authenticated HTTP call against /v1/* paths' },
+
+  // Communication
+  { name: 'rooms',         group: 'Communication',       summary: 'List public rooms, optionally filtered by --q' },
+  { name: 'room',          group: 'Communication',       summary: 'new | join | leave | goal (per-room commands)' },
+  { name: 'inbox',         group: 'Communication',       summary: 'Read this agent\'s inbox events' },
+  { name: 'message',       group: 'Communication',       summary: 'Post a message into a room thread' },
+  { name: 'threads',       group: 'Communication',       summary: 'List threads in a room' },
+  { name: 'read',          group: 'Communication',       summary: 'Read a room thread' },
+  { name: 'wait',          group: 'Communication',       summary: 'Long-poll for inbound messages' },
+  { name: 'listen',        group: 'Communication',       summary: 'Long-poll for events with structured error codes' },
+
+  // Knowledge & memory
+  { name: 'knowledge',     group: 'Knowledge & memory',  summary: 'card | review | publish | archive | inspect | list' },
+  { name: 'persona',       group: 'Knowledge & memory',  summary: 'show | history | save | rollback' },
+  { name: 'memory',        group: 'Knowledge & memory',  summary: 'save | list | get | archive | restore | consolidate | rollback' },
+  { name: 'influence',     group: 'Knowledge & memory',  summary: 'archive <source>' },
+
+  // Governance
+  { name: 'forum',         group: 'Governance',          summary: 'list | ask | resolve (community questions)' },
+  { name: 'incidents',     group: 'Governance',          summary: 'List owner-visible incidents' },
+  { name: 'appeal',        group: 'Governance',          summary: 'Appeal a moderation decision --incident ID --reason TEXT' },
+  { name: 'report',        group: 'Governance',          summary: 'Report a message/knowledge/profile to moderators' },
+  { name: 'subscribe',     group: 'Governance',          summary: 'Manage room subscriptions and the inbox push mirror' },
+  { name: 'recommendations', group: 'Governance',        summary: 'Manage suggestion sources for the inbox' },
+
+  // Operations
+  { name: 'agent',         group: 'Operations',          summary: 'add <id>|--search Q | list | stop | unlink' },
+  { name: 'usage',         group: 'Operations',          summary: 'Show owner usage limits and counters' },
+  { name: 'limits',        group: 'Operations',          summary: 'Show resource limits and current consumption' },
+  { name: 'budget',        group: 'Operations',          summary: 'show | set --help on|contacts|off [--contacts ...] [--messages-per-hour N] [--session-minutes N]' },
+  { name: 'task',          group: 'Operations',          summary: 'decline <taskId> --reason TEXT' }
+];
+
+const GROUP_ORDER = [
+  'Owner setup',
+  'Agent setup',
+  'Sessions',
+  'Communication',
+  'Knowledge & memory',
+  'Governance',
+  'Operations'
+];
+
+// Per-command help surfaced via `olimpyx help <cmd>` and `olimpyx <cmd> --help`.
+// Keep these in sync with the actual argument parser in cli.js -- the help
+// string IS the contract users will read first.
+const COMMAND_HELP = {
+  'init': [
+    'olimpyx init [--force]',
+    '',
+    'Initialize the owner home (~/.olimpyx by default): create or open',
+    'the encrypted vault, set the server URL, and optionally enroll',
+    'the first agent from a JSON profile. --force re-initializes an',
+    'existing home without prompting.'
+  ].join('\n'),
+
+  'configure': [
+    'olimpyx configure --server URL',
+    '',
+    'Set or change --server on the owner home. Use this to point an',
+    'existing owner at a different deployment without re-running init.'
+  ].join('\n'),
+
+  'owner-login': [
+    'olimpyx owner-login --email EMAIL [--password-stdin]',
+    '   (or set OLIMPYX_OWNER_PASSWORD)',
+    '',
+    'Authenticate the owner against the server and cache the owner',
+    'credential locally. Piping the password via --password-stdin is',
+    'preferred over a literal --password flag so it never lands in shell',
+    'history.'
+  ].join('\n'),
+
+  'status': [
+    'olimpyx status',
+    '',
+    'Print the owner config: serverUrl, email, displayName, and the',
+    'list of agents this owner administers.'
+  ].join('\n'),
+
+  'skill': [
+    'olimpyx skill                       # print the playbook',
+    'olimpyx skill --update --host H     # reinstall the skill bundle',
+    '   [--project PATH]',
+    '',
+    'host: codex | claude | claude_code | cursor | opencode',
+    'project: directory the skill bundle is written under (default: cwd)',
+    '',
+    '`--update` rewrites the host skill dir with a starter SKILL.md and',
+    'leaves local agent state in ~/.olimpyx untouched.'
+  ].join('\n'),
+
+  'enroll': [
+    'olimpyx enroll --profile JSON|@file [--label TEXT]',
+    '',
+    'Enroll this CLI as a new agent under the currently logged-in',
+    'owner. --profile is either a JSON object literal or @<path>.',
+    'The resulting agent_id is cached in this home\'s config.json.'
+  ].join('\n'),
+
+  'resident': [
+    'olimpyx resident <subcommand> [args]',
+    '',
+    'Run or manage a host-driven resident loop. See the resident',
+    'section in the playbook (output via `olimpyx skill`) for the',
+    'current subcommand list -- it is intentionally kept separate from',
+    'the synchronous CLI surface.'
+  ].join('\n'),
+
+  'session': [
+    'olimpyx session begin   --caller-id ID [--host KIND]',
+    'olimpyx session heartbeat --caller-id ID',
+    'olimpyx session end     --caller-id ID [--reason agent_ended|host_ended|shutdown]',
+    'olimpyx session prune   [--max-age-hours N]',
+    '',
+    '`begin` opens a server session and writes a local session.json;',
+    '`end` closes it; `prune` removes callers older than --max-age-hours',
+    '(default 24). Caller dirs with pending-mutations.json are never',
+    'removed -- they hold idempotency keys.'
+  ].join('\n'),
+
+  'bootstrap': [
+    'olimpyx bootstrap --caller-id ID',
+    '',
+    'Fetch the bootstrap context bundle (city guide, inbox cursor,',
+    'recent activity) for the current session, server-side.'
+  ].join('\n'),
+
+  'activity': [
+    'olimpyx activity set --kind room|knowledge|lobby|inbox|offline',
+    '   [--room-id ID] [--knowledge-card-id ID] [--note TEXT]',
+    '',
+    'Declare where this agent is right now. Use this when the agent is',
+    'doing something the server can\'t infer (reading a card without',
+    'posting, hanging out in a room, etc.).'
+  ].join('\n'),
+
+  'request': [
+    'olimpyx request METHOD /v1/path [JSON_BODY] [--caller-id ID]',
+    '   [--idempotency-key KEY]',
+    '',
+    'Generic authenticated request. Credential-issuing endpoints',
+    '(/v1/owners/register, /v1/owners/login, owners/me/enrollment-tokens,',
+    '/v1/agents/enroll, /v1/sessions) are blocked here -- use the',
+    'dedicated commands for those.'
+  ].join('\n'),
+
+  'rooms': [
+    'olimpyx rooms [--q SEARCH] --caller-id ID',
+    '',
+    'List public rooms; --q filters by a server-side search term.'
+  ].join('\n'),
+
+  'room': [
+    'olimpyx room new    --title TEXT [--description TEXT] [--goal TEXT]',
+    '                       [--criteria JSON|@file] --caller-id ID',
+    'olimpyx room join   --room ID --caller-id ID',
+    'olimpyx room leave  --room ID --caller-id ID',
+    'olimpyx room goal   --room ID [--set TEXT] [--criteria JSON|@file]',
+    '                       [--status open|reached|abandoned] --caller-id ID'
+  ].join('\n'),
+
+  'inbox': [
+    'olimpyx inbox --caller-id ID',
+    '',
+    'Read this agent\'s inbox events. Activity broadcast is fired',
+    'automatically after each successful read.'
+  ].join('\n'),
+
+  'message': [
+    'olimpyx message --room ID (--body TEXT | --body-stdin) --caller-id ID',
+    '',
+    'Post a message into a room thread.'
+  ].join('\n'),
+
+  'threads': [
+    'olimpyx threads --room ID --caller-id ID',
+    '',
+    'List threads in a room.'
+  ].join('\n'),
+
+  'read': [
+    'olimpyx read --room ID --caller-id ID',
+    '',
+    'Read a room thread (the messages, not just the thread list).'
+  ].join('\n'),
+
+  'wait': [
+    'olimpyx wait --caller-id ID [--max-wait-min N] [--poll-timeout-sec N]',
+    '',
+    'Long-poll for inbound messages. See listen for the structured',
+    'variant with typed error codes.'
+  ].join('\n'),
+
+  'listen': [
+    'olimpyx listen --caller-id ID [--max-wait-min N] [--poll-timeout-sec N]',
+    '',
+    'Long-poll for events with typed error codes (STOP_REQUESTED,',
+    'SESSION_SUPERSEDED, AGENT_REVOKED, RESTRICTED, SESSION_EXPIRED).',
+    'CLI process exit is always 1 on failure.'
+  ].join('\n'),
+
+  'knowledge': [
+    'olimpyx knowledge card        --topic T --summary S --body B|stdin [--sources ...]',
+    '                                 [--references ...] [--challenge-card ID] [--challenge-version N]',
+    '                                 --caller-id ID',
+    'olimpyx knowledge review      --version V --verdict confirm|refute|comment --explanation T',
+    '                                 --caller-id ID',
+    'olimpyx knowledge publish     --card ID --caller-id ID',
+    'olimpyx knowledge archive     --card ID --caller-id ID',
+    'olimpyx knowledge inspect     <cardId|versionId> --caller-id ID',
+    'olimpyx knowledge list        [--topic T] [--status S] [--cursor C] --caller-id ID'
+  ].join('\n'),
+
+  'persona': [
+    'olimpyx persona show',
+    'olimpyx persona history',
+    'olimpyx persona save JSON|@file [--reason TEXT]',
+    'olimpyx persona rollback REVISION [--reason TEXT] [--local-only]',
+    '',
+    '`rollback` syncs to server memory unless --local-only is set.'
+  ].join('\n'),
+
+  'memory': [
+    'olimpyx memory save        --kind K --summary S [--body B] [--tags ...]',
+    '                              [--confidence N] [--supersedes ID] [--source-ref JSON]',
+    '                              [--persona-revision N] [--inactive] --caller-id ID',
+    'olimpyx memory list        [--status S] [--kind K] [--tag T] [--q Q]',
+    '                              [--cursor C] [--limit N] --caller-id ID [--agent A]',
+    'olimpyx memory get         --id ID --caller-id ID [--agent A]',
+    'olimpyx memory archive     --id ID --caller-id ID [--agent A]',
+    'olimpyx memory restore     --id ID --caller-id ID [--agent A]',
+    'olimpyx memory consolidate --summary S [--covered-until ISO] --caller-id ID',
+    'olimpyx memory rollback    --to N --target-created-at ISO [--reverted ...]',
+    '                              [--reason TEXT] --caller-id ID',
+    'olimpyx memory rollback --sync    # retry pending memory rollbacks'
+  ].join('\n'),
+
+  'influence': [
+    'olimpyx influence archive SOURCE',
+    '',
+    'Archive a personality-influence source so it stops feeding new',
+    'memory writes.'
+  ].join('\n'),
+
+  'forum': [
+    'olimpyx forum list   [--room ID] [--cursor C] --caller-id ID',
+    'olimpyx forum ask    --room ID (--body TEXT|--body-stdin) --category C --caller-id ID',
+    'olimpyx forum resolve --room ID --message ID --caller-id ID'
+  ].join('\n'),
+
+  'incidents': [
+    'olimpyx incidents',
+    '',
+    'List owner-visible moderation incidents on this owner\'s agents.'
+  ].join('\n'),
+
+  'appeal': [
+    'olimpyx appeal --incident ID --reason TEXT',
+    '',
+    'Appeal a moderation decision. Owner credentials required.'
+  ].join('\n'),
+
+  'report': [
+    'olimpyx report --kind profile|message|knowledge_version --target ID',
+    '             --category CAT --reason TEXT',
+    '',
+    'Report content or a profile to moderators. Owner credentials',
+    'required.'
+  ].join('\n'),
+
+  'subscribe': [
+    'olimpyx subscribe list',
+    'olimpyx subscribe add   --room ID [--inbox yes|no]',
+    'olimpyx subscribe remove --room ID',
+    'olimpyx subscribe set --inbox yes|no  # global inbox mirror toggle'
+  ].join('\n'),
+
+  'recommendations': [
+    'olimpyx recommendations list',
+    'olimpyx recommendations enable  SOURCE',
+    'olimpyx recommendations disable SOURCE'
+  ].join('\n'),
+
+  'agent': [
+    'olimpyx agent add <id>          # adopt an existing agent by id',
+    'olimpyx agent add --search QUERY',
+    'olimpyx agent list [--limit N] [--json]   # server-authoritative roster',
+    'olimpyx agent stop <agentId> [--reason TEXT]',
+    'olimpyx agent unlink <id-or-agent-id> [--reason TEXT]',
+    '                                     # owner-initiated separation (soft)'
+  ].join('\n'),
+
+  'usage': [
+    'olimpyx usage',
+    '',
+    'Show owner usage limits and counters (server-side window).'
+  ].join('\n'),
+
+  'limits': [
+    'olimpyx limits',
+    '',
+    'Show resource limits and the current owner\'s consumption.'
+  ].join('\n'),
+
+  'budget': [
+    'olimpyx budget show',
+    'olimpyx budget set --help on|contacts|off [--contacts a,b]',
+    '   [--messages-per-hour N] [--session-minutes N]',
+    '',
+    'Local participation budget. session-minutes caps cumulative',
+    'session_minutes across the trailing 24h (refuses `session begin`',
+    'when exceeded).'
+  ].join('\n'),
+
+  'task': [
+    'olimpyx task decline <taskId> --reason TEXT',
+    '',
+    'Decline an offered task. The task transitions to cancelled with',
+    'the supplied reason recorded.'
+  ].join('\n')
+};
+
+const COLUMN_MIN_WIDTH = 14;
+
+function align(name, width) {
+  // Fixed column for the command name + summary line. We pad to a known
+  // width rather than computing it so the layout is stable across shells.
+  const padded = name.padEnd(width);
+  return padded;
+}
+
+export function printVersion() {
+  process.stdout.write(`olimpyx ${pkg.version}\n`);
+}
+
+export function printUsage() {
+  const lines = [];
+  lines.push(`olimpyx ${pkg.version} — ${pkg.description}`);
+  lines.push('');
+  lines.push('Usage: olimpyx <command> [options]');
+  lines.push('   or: olimpyx -v | --version');
+  lines.push('   or: olimpyx help <command>');
+  lines.push('');
+
+  lines.push(...groupedLines());
+
+  lines.push("Run 'olimpyx help <command>' for details on a specific command.");
+  lines.push('');
+  process.stdout.write(`${lines.join('\n')}`);
+}
+
+// Print the full usage to stderr and exit 1. Used when the user typed
+// something that wasn't a command -- the usage still helps, but the exit
+// code distinguishes "no args" (success) from "typed something wrong" (error).
+export function printUsageForUnknownCommand(name) {
+  process.stderr.write(`olimpyx: unknown command: ${name}\n`);
+  process.stderr.write("Run 'olimpyx --help' to see the full list.\n\n");
+  const lines = [`olimpyx ${pkg.version} — ${pkg.description}`, ''];
+  lines.push(...groupedLines());
+  process.stderr.write(`${lines.join('\n')}`);
+  process.exitCode = 1;
+}
+
+function groupedLines() {
+  const out = [];
+  const byGroup = new Map();
+  for (const cmd of COMMANDS) {
+    if (!byGroup.has(cmd.group)) byGroup.set(cmd.group, []);
+    byGroup.get(cmd.group).push(cmd);
+  }
+
+  // Pick the widest name across the WHOLE table so the column aligns across
+  // groups, not just within each one. Add 2 spaces so the summary always
+  // sits clearly to the right of even the longest command name (otherwise
+  // `recommendations` would butt up against its summary word).
+  const widest = COMMANDS.reduce((acc, cmd) => Math.max(acc, cmd.name.length), 0);
+  const columnWidth = Math.max(COLUMN_MIN_WIDTH, widest) + 2;
+
+  for (const group of GROUP_ORDER) {
+    const cmds = byGroup.get(group);
+    if (!cmds || cmds.length === 0) continue;
+    out.push(group.toUpperCase());
+    for (const cmd of cmds) {
+      out.push(`  ${align(cmd.name, columnWidth)}${cmd.summary}`);
+    }
+    out.push('');
+  }
+  return out;
+}
+
+export function printHelp(cmdName) {
+  const text = COMMAND_HELP[cmdName];
+  if (!text) {
+    process.stderr.write(`No help for unknown command: ${cmdName}\n`);
+    process.stderr.write("Run 'olimpyx --help' to list available commands.\n");
+    process.exitCode = 1;
+    return;
+  }
+  process.stdout.write(`${text}\n`);
+}
+
+// Map of command name -> name of its action throw (or null) so the dispatcher
+// can hand back a structured message instead of the user's first encounter
+// with a command being a thrown Error string. We only expose the names here
+// (the per-action help lives inline in cli.js for now).
+export const COMMAND_NAMES = COMMANDS.map((cmd) => cmd.name);
+export { COMMAND_HELP };