@onesi/genesis-cli 0.1.13 → 0.2.0

package/dist/index.js

@@ -1,8 +1,11 @@
 import { registerMinds } from './minds.js';
 import { registerRelaysEnrollment } from './relays-enrollment.js';
+import { RELAYS_COMMANDS } from './relays-commands/index.js';
 import { registerBeacons } from './beacons.js';
 import { registerDials } from './dials.js';
-import { registerProducts } from './products.js';
+import { registerIamDirectory } from './iam-directory.js';
+import { registerOperationCommands, registerProducts } from './products.js';
+import { registerOrgs } from './orgs.js';
 import { Command, CommanderError } from 'commander';
 import { Genesis, GenesisError, errorCatalog, errorOutcome, isMindsOperation, HivesOperationError, HivesQueueOperationError, MindsAgentError, MindsOwnerError, hivesResponseBytes, MAX_FUNCTION_BODY_BYTES, MAX_FUNCTION_JSON_BYTES, DEFAULT_BASE_URL, requireSecureUrl } from '@onesi/genesis';
 import { authConfig, completeLogin, selectSavedContext, savedLoginProvider, startLogin } from './auth.js';
@@ -16,6 +19,7 @@ import { registerFlocks } from './flocks.js';
 import { registerRunner } from './runner.js';
 import { createHivesNodeTransport } from './hives-node-transport.js';
 import { registerHivesOperations } from './hives-operations.js';
+import { registerHivesCoverage } from './hives-coverage.js';
 import { readFunctionFile, readFunctionJson, writeFunctionOutput } from './function-input.js';
 import { basename } from 'node:path';
 import { readWasmFile } from './wasm-input.js';
@@ -36,7 +40,7 @@ export function buildProgram(deps = {}) {
     const auth = { ...authConfig(env, f), sleep: deps.sleep };
     const program = new Command('genesis')
         .description('One CLI for every Genesis service.')
-        .version('0.1.13')
+        .version('0.2.0')
         .option('--json', 'machine-readable JSON output')
         .option('--api-key <key>', 'use this API key (default: GENESIS_API_KEY, then your `genesis login`)')
         .option('--base-url <url>', 'gateway URL (default: GENESIS_BASE_URL or https://os.one.ml/api)')
@@ -52,7 +56,7 @@ export function buildProgram(deps = {}) {
         const opts = {
             apiKey: o.apiKey ?? env.GENESIS_API_KEY, token: env.GENESIS_TOKEN,
             baseUrl: o.baseUrl ?? env.GENESIS_BASE_URL, routing: o.direct || env.GENESIS_ROUTING === 'direct' ? 'direct' : 'gateway',
-            fetch: f, userAgent: 'genesis-cli/0.1.13',
+            fetch: f, userAgent: 'genesis-cli/0.2.0',
             credentials: store ? savedLoginProvider(auth, store) : undefined,
         };
         return new Genesis(hivesTransport ? { ...opts, fetch: createHivesNodeTransport(opts, deps.signal) } : opts);
@@ -82,23 +86,102 @@ export function buildProgram(deps = {}) {
         return (await gen.whoami()).org;
     };
     const silos = program.command('silos').description('Serverless PostgreSQL');
-    const silosDatabases = silos.command('databases').description('Read existing owned database metadata; no provisioning');
-    silosDatabases.command('list <project_id>').action(async (id) => out.log(JSON.stringify(await (await client()).silos.databases.list(id), null, 2)));
-    silosDatabases.command('get <project_id> <database_id>').action(async (project, database) => out.log(JSON.stringify(await (await client()).silos.databases.get(project, database), null, 2)));
-    const silosProjects = silos.command('projects').description('Projects in your verified organization');
-    silosProjects.command('list').action(async () => out.log(JSON.stringify(await (await client()).silos.projects.list(), null, 2)));
-    silosProjects.command('get <project_id>').action(async (id) => out.log(JSON.stringify(await (await client()).silos.projects.get(id), null, 2)));
-    silosProjects.command('create').requiredOption('--name <name>', 'Project name').requiredOption('--slug <slug>', 'Unique project slug')
-        .action(async (options) => out.log(JSON.stringify(await (await client()).silos.projects.create({ name: options.name, slug: options.slug }), null, 2)));
+    const silosInstances = silos.command('instances').description('Database instances in the selected Genesis project (genesis select)');
+    silosInstances.command('list').action(async () => out.log(JSON.stringify(await (await client()).silos.instances.list(), null, 2)));
+    silosInstances.command('get <instance_id>').action(async (id) => out.log(JSON.stringify(await (await client()).silos.instances.get(id), null, 2)));
+    silosInstances.command('create').requiredOption('--name <name>', 'Instance name (lowercase, 1-63 characters)')
+        .action(async (options) => out.log(JSON.stringify(await (await client()).silos.instances.create({ name: options.name }), null, 2)));
+    const silosJson = (value) => out.log(JSON.stringify(value, null, 2));
+    silosInstances.command('rename <instance_id>').requiredOption('--name <name>', 'New instance name (lowercase, 1-63 characters)')
+        .action(async (id, options) => silosJson(await (await client()).silos.instances.update(id, { name: options.name })));
+    silosInstances.command('delete <instance_id>').description('Delete an instance and stop it; its name is free again at once')
+        .action(async (id) => silosJson((await (await client()).silos.instances.delete(id)) ?? { deleted: id }));
+    silosInstances.command('suspend <instance_id>').description('Checkpoint, then stop the instance')
+        .action(async (id) => silosJson(await (await client()).silos.instances.suspend(id)));
+    silosInstances.command('resume <instance_id>').description('Start the instance now')
+        .action(async (id) => silosJson(await (await client()).silos.instances.resume(id)));
+    silosInstances.command('query <instance_id>').description('Run one SQL statement (never replayed)')
+        .requiredOption('--sql <sql>', 'SQL statement').option('--params <json>', 'JSON array of positional parameters for $1, $2, …')
+        .option('--branch <branch_id>', 'run on this branch instead of the default branch')
+        .action(async (id, options) => {
+        let params;
+        if (options.params !== undefined) {
+            try {
+                params = JSON.parse(options.params);
+            }
+            catch {
+                params = undefined;
+            }
+            if (!Array.isArray(params))
+                throw new Error('--params must be a JSON array, for example \'[1,"a"]\'.');
+        }
+        silosJson(await (await client()).silos.instances.query(id, { sql: options.sql, ...(params ? { params } : {}), ...(options.branch ? { branchId: options.branch } : {}) }));
+    });
+    silosInstances.command('batch <instance_id>').description('Run up to 50 statements in one transaction (never replayed)')
+        .option('--file <path>', 'UTF-8 JSON file: {"statements":[{"sql":"…","params":[…]}]}').option('--stdin', 'read that JSON from stdin')
+        .action(async (id, o) => {
+        let body;
+        if (Boolean(o.file) === Boolean(o.stdin))
+            throw new Error('Choose exactly one input source: --file or --stdin.');
+        const text = await (deps.readSecretInput ?? readSecretInput)(o, 64 * 1024);
+        try {
+            body = JSON.parse(text);
+        }
+        catch {
+            throw new Error('Batch input must be JSON: {"statements":[{"sql":"…"}]}.');
+        }
+        silosJson(await (await client()).silos.instances.batch(id, body));
+    });
+    silosInstances.command('metrics <instance_id>').description('Live counters, storage and activity times')
+        .action(async (id) => silosJson(await (await client()).silos.instances.metrics(id)));
+    silosInstances.command('listen <instance_id>').description('Wait for NOTIFY on channels (up to --wait ms, at most 15000)')
+        .requiredOption('--channel <name...>', 'channel to listen on (repeatable, up to 10)').option('--wait <ms>', 'how long to wait (default 10000)')
+        .option('--branch <branch_id>', 'listen on this branch instead of the default branch')
+        .action(async (id, o) => {
+        const waitMs = o.wait === undefined ? undefined : Number(o.wait);
+        if (waitMs !== undefined && !(Number.isInteger(waitMs) && waitMs >= 0 && waitMs <= 15000))
+            throw new Error('--wait must be an integer from 0 to 15000.');
+        silosJson(await (await client()).silos.instances.listen(id, { channels: o.channel, ...(waitMs !== undefined ? { waitMs } : {}), ...(o.branch ? { branchId: o.branch } : {}) }));
+    });
+    silos.command('usage').description('Silos usage of the selected Genesis project, last 30 days')
+        .action(async () => silosJson(await (await client()).silos.usage()));
+    silos.command('regions').description('Regions Silos instances are created in')
+        .action(async () => silosJson(await (await client()).silos.regions.list()));
+    const silosBranches = silos.command('branches').description('Branches of a database instance');
+    silosBranches.command('list <instance_id>').action(async (id) => silosJson(await (await client()).silos.instances.branches.list(id)));
+    silosBranches.command('get <instance_id> <branch_id>').action(async (id, branch) => silosJson(await (await client()).silos.instances.branches.get(id, branch)));
+    silosBranches.command('create <instance_id>').description('Copy the latest checkpoint of the parent (default: the default branch)')
+        .requiredOption('--name <name>', 'Branch name (lowercase, 1-63 characters)').option('--parent <branch_id>', 'parent branch')
+        .action(async (id, o) => silosJson(await (await client()).silos.instances.branches.create(id, o.parent ? { name: o.name, parentBranchId: o.parent } : { name: o.name })));
+    silosBranches.command('rename <instance_id> <branch_id>').requiredOption('--name <name>', 'New branch name')
+        .action(async (id, branch, o) => silosJson(await (await client()).silos.instances.branches.update(id, branch, { name: o.name })));
+    silosBranches.command('delete <instance_id> <branch_id>').description('Delete a branch other than the default branch')
+        .action(async (id, branch) => silosJson((await (await client()).silos.instances.branches.delete(id, branch)) ?? { deleted: branch }));
+    silosBranches.command('restore <instance_id> <branch_id>').description('Replace the branch data with a stored snapshot')
+        .requiredOption('--snapshot <snapshot_id>', 'snapshot id from `genesis silos snapshots list`').option('--from <branch_id>', 'branch the snapshot was taken on (default: this branch)')
+        .action(async (id, branch, o) => silosJson(await (await client()).silos.instances.branches.restore(id, branch, o.from ? { snapshotId: o.snapshot, sourceBranchId: o.from } : { snapshotId: o.snapshot })));
+    const silosSnapshots = silos.command('snapshots').description('Stored snapshots of a database instance');
+    silosSnapshots.command('list <instance_id>').action(async (id) => silosJson(await (await client()).silos.instances.snapshots.list(id)));
+    silosSnapshots.command('create <instance_id>').description('Checkpoint a branch and store the snapshot').option('--branch <branch_id>', 'branch (default: the default branch)')
+        .action(async (id, o) => silosJson(await (await client()).silos.instances.snapshots.create(id, o.branch ? { branchId: o.branch } : {})));
     const traces = program.command('traces').description('Research and evidence');
     const tracesRuns = traces.command('runs').description('Research runs in your verified organization');
     tracesRuns.command('create').requiredOption('--type <type>', 'Run type, e.g. deep_research').requiredOption('--query <query>', 'Research question')
         .requiredOption('--idempotency-key <key>', 'Stable key; reuse it to replay instead of creating a second run')
-        .action(async (o) => out.log(JSON.stringify(await (await client()).traces.runs.create({ type: o.type, query: o.query }, o.idempotencyKey), null, 2)));
+        .option('--max-sources <n>', 'Most sources the run may collect (1-100)')
+        .option('--include-domain <domain...>', 'Search only these domains, e.g. wikipedia.org')
+        .action(async (o) => {
+        const config = { ...(o.maxSources !== undefined ? { max_sources: positiveInteger(o.maxSources, '--max-sources', 100) } : {}), ...(o.includeDomain?.length ? { include_domains: o.includeDomain } : {}) };
+        out.log(JSON.stringify(await (await client()).traces.runs.create({ type: o.type, query: o.query, ...(Object.keys(config).length ? { config } : {}) }, o.idempotencyKey), null, 2));
+    });
     tracesRuns.command('list').action(async () => out.log(JSON.stringify(await (await client()).traces.runs.list(), null, 2)));
     tracesRuns.command('get <run_id>').action(async (id) => out.log(JSON.stringify(await (await client()).traces.runs.get(id), null, 2)));
     traces.command('search <query>').requiredOption('--idempotency-key <key>', 'Stable key; metered once')
-        .action(async (query, o) => out.log(JSON.stringify(await (await client()).traces.search({ query, max_results: 3 }, o.idempotencyKey), null, 2)));
+        .option('--max-results <n>', 'Results to return (1-20, default 3)')
+        .option('--include-domain <domain...>', 'Search only these domains, e.g. wikipedia.org')
+        .action(async (query, o) => out.log(JSON.stringify(await (await client()).traces.search({
+        query, max_results: positiveInteger(o.maxResults, '--max-results', 20) ?? 3, ...(o.includeDomain?.length ? { include_domains: o.includeDomain } : {})
+    }, o.idempotencyKey), null, 2)));
     traces.command('usage').action(async () => out.log(JSON.stringify(await (await client()).traces.usage.events(), null, 2)));
     const blinds = program.command('blinds').description('Blinds credential custody');
     const show = async (call) => out.log(JSON.stringify(await call((await client()).blinds), null, 2));
@@ -115,7 +198,41 @@ export function buildProgram(deps = {}) {
             ...(o.domain ? { destination_domains: o.domain } : {}), ...(o.provider ? { provider: o.provider } : {}) }, key(o)));
     });
     credentials.command('revoke <variable>').option(...keyOption).action((variable, o) => show(b => b.credentials.revoke(variable, key(o))));
+    credentials.command('revoke-all').description('Revoke every credential in the selected organization (irreversible)')
+        .requiredOption('--yes', 'Confirm the bulk revoke').option(...keyOption).action((o) => show(b => b.credentials.revokeAll(key(o))));
     blinds.command('connections').description('Active OAuth connections (metadata only)').action(() => show(b => b.oauth.connections({ signal: deps.signal })));
+    const offsetInteger = (value) => {
+        if (value === undefined)
+            return undefined;
+        if (!/^\d+$/.test(value) || !Number.isSafeInteger(Number(value)))
+            throw new Error('--offset must be a non-negative integer.');
+        return Number(value);
+    };
+    const catalog = (o) => {
+        const limit = positiveInteger(o.limit, '--limit', 1000), offset = offsetInteger(o.offset);
+        return { ...(o.q ? { q: o.q } : {}), ...(o.category ? { category: o.category } : {}),
+            ...(limit !== undefined ? { limit } : {}), ...(offset !== undefined ? { offset } : {}) };
+    };
+    const providers = blinds.command('providers').description('Provider catalog: what a credential can be bound to');
+    providers.command('list').option('--q <text>', 'Match slug, name or description').option('--category <name>').option('--auth-mode <mode>', 'oauth2, api_key, ...')
+        .option('--oauth', 'Only providers that use OAuth 2.0 (cannot be combined with --auth-mode)').option('--limit <n>', 'Page size, 1 to 1000').option('--offset <n>')
+        .action((o) => {
+        if (o.oauth && o.authMode)
+            throw new Error('--oauth already selects auth mode oauth2; drop --auth-mode.');
+        const query = catalog(o);
+        return show(b => o.oauth ? b.oauth.providers(query, { signal: deps.signal })
+            : b.providers.list({ ...query, ...(o.authMode ? { auth_mode: o.authMode } : {}) }, { signal: deps.signal }));
+    });
+    providers.command('get <slug>').action((slug) => show(b => b.providers.get(slug, { signal: deps.signal })));
+    const settings = blinds.command('settings').description('Consent policy and notifications');
+    settings.command('get').action(() => show(b => b.settings.get({ signal: deps.signal })));
+    settings.command('set').description('Replace the settings: an omitted --email or --slack turns that notification off').requiredOption('--consent-policy <policy>', 'never, per_variable or per_delegate')
+        .option('--email', 'Email notifications on').option('--slack', 'Slack notifications on').option(...keyOption)
+        .action((o) => show(b => b.settings.update({ consent_policy: o.consentPolicy, email_notifications: !!o.email, slack_notifications: !!o.slack }, key(o))));
+    blinds.command('agents').description('Agents seen using Blinds, with request counts').action(() => show(b => b.agents({ signal: deps.signal })));
+    blinds.command('alerts').description('Failed or denied Blinds events').action(() => show(b => b.alerts({ signal: deps.signal })));
+    blinds.command('operation <operation_id>').description('Receipt for a mutation, by its Idempotency-Key')
+        .action((id) => show(b => b.operations.get(id, { signal: deps.signal })));
     const consent = blinds.command('consent').description('Agent consent requests and decisions');
     consent.command('pending').action(() => show(b => b.consent.pending({ signal: deps.signal })));
     consent.command('list').action(() => show(b => b.consent.records({ signal: deps.signal })));
@@ -141,7 +258,22 @@ export function buildProgram(deps = {}) {
         });
     }
     registerDials(program, { client, orgId, emit });
+    registerIamDirectory(program, { client, orgId, emit });
     registerProducts(program, { client, emit, signal: deps.signal });
+    registerOrgs(program, { client, emit, signal: deps.signal });
+    // Agent enrollment sends only the grant's enrollment key (mek_...), never this CLI's login or API key.
+    (program.commands.find(c => c.name() === 'iam').commands.find(c => c.name() === 'agents')).command('enroll')
+        .description('Enroll an agent under an agent enrollment grant (POST /v1/iam/agents/enroll); the credential secret is shown once')
+        .requiredOption('--body-file <path>', 'JSON request body (externalKey, displayName, mindId, permissions, ...)')
+        .option('--key-file <path>', 'file holding the enrollment key (mek_...)').option('--key-stdin', 'read the enrollment key from stdin')
+        .action(async (o) => {
+        const key = o.keyFile || o.keyStdin ? (await (deps.readSecretInput ?? readSecretInput)({ file: o.keyFile, stdin: o.keyStdin }, 1024)).trim() : env.GENESIS_ENROLLMENT_KEY;
+        if (!key)
+            throw new Error('Give the enrollment key with --key-file, --key-stdin or GENESIS_ENROLLMENT_KEY; it is never accepted as an argument.');
+        const body = await readFunctionJson(o.bodyFile, 16 * 1024);
+        const result = await new Genesis({ baseUrl: g().baseUrl ?? env.GENESIS_BASE_URL, fetch: f, userAgent: 'genesis-cli/0.1.13' }).iam.agents.enroll(key, body);
+        emit(result, () => JSON.stringify(result, null, 2));
+    });
     // ---- auth ------------------------------------------------------------
     program.command('login').description('Sign in with One in your browser').option('--no-browser', 'just print the link')
         .option('--device', 'sign in from a machine without a local browser: approve a code from any signed-in browser')
@@ -196,7 +328,8 @@ export function buildProgram(deps = {}) {
             emit({ user: saved.user, organization_id: saved.organization_id, verified: false, reason: e.message }, () => `${c.bold('User')}  ${saved.user?.email ?? saved.user?.id}\n${c.bold('Org')}   ${saved.organization_id ?? '-'}\n${c.yellow('!')} ${c.dim('From your saved login; One account verify unavailable: ' + e.message)}`);
         }
     });
-    const orgs = program.command('orgs').description('Your organizations');
+    // `orgs usage|observations|billing|payment-methods|service` and the Orgs (legal entity) commands are registered by registerProducts and registerOrgs.
+    const orgs = (program.commands.find(command => command.name() === 'orgs') ?? program.command('orgs')).description('Your organizations, their usage and billing reads, and Orgs: legal entities, seats, resolutions, documents, filings, formation and the record');
     orgs.command('list', { isDefault: true }).description('Show your current organization').action(async () => {
         const s = await (await getStore()).get();
         if (!s)
@@ -247,7 +380,8 @@ export function buildProgram(deps = {}) {
         emit({ revoked: id }, () => `${c.green('✓')} Revoked ${id} ${c.dim('(takes effect within 60s)')}`);
     });
     // ---- foundry ---------------------------------------------------------
-    const foundry = program.command('foundry').description('Foundry: models and inference');
+    // registerProducts (above) already added the generated `foundry` commands; the hand-written ones join them.
+    const foundry = program.commands.find(c => c.name() === 'foundry') ?? program.command('foundry').description('Foundry: models and inference');
     const foundryBilling = foundry.command('billing').description('Current organization’s native TEST billing; original One account human login required');
     foundryBilling.command('profile').action(async () => out.log(JSON.stringify(await (await client()).foundry.billing.profile({ signal: deps.signal }), null, 2)));
     foundryBilling.command('ensure').requiredOption('--operation-key <key>', 'Persisted operation key; reconcile unknown outcomes before retrying').action(async (o) => out.log(JSON.stringify(await (await client()).foundry.billing.ensureProfile(o.operationKey, { signal: deps.signal }), null, 2)));
@@ -285,7 +419,7 @@ export function buildProgram(deps = {}) {
     const hivesClient = () => client(true);
     // ---- hives -----------------------------------------------------------
     const hives = program.command('hives').description('Hives: projects, secrets, deployments, functions, schedules and activity');
-    registerHivesOperations(hives, { client: hivesClient, emit, readRequest: deps.readHivesRequest });
+    registerHivesOperations(hives, { client: hivesClient, emit, readRequest: deps.readHivesRequest, line: (text) => out.log(text) });
     const deployments = hives.command('deployments').description('Real WASM artifacts and deployment lifecycle');
     const emitDeployment = (data) => emit(data, () => table(data && typeof data === 'object' && !Array.isArray(data) && !('data' in data) ? [data] : listOf(data), ['id', 'version', 'status', 'module_hash', 'created_at']));
     deployments.command('list <project_id>')
@@ -358,10 +492,10 @@ export function buildProgram(deps = {}) {
         const result = await (await hivesClient()).hives.functions.delete(project, id);
         emit(result, () => `Deleted function ${id}.`);
     });
-    function invocationCommand(command, kind) {
+    function invocationCommand(command, kind, alias = false) {
         if (kind === 'functions')
             command.option('--idempotency-key <key>', 'Persisted original invocation key; required by Genesis funding. Reuse it after uncertainty.');
-        command.description('Complete real guest execution; write exact bytes, including executed HTTP error bodies')
+        command.description(alias ? 'Compatibility alias of invoke (/invoke/async): the same completed guest response, no durable queue' : 'Complete real guest execution; write exact bytes, including executed HTTP error bodies')
             .option('--request-file <file>', 'JSON method/path/headers/body or body_base64')
             .option('--body-file <file>', 'Exact binary body (up to 10 MiB; serialized guest envelope may reach its cap earlier)')
             .option('--method <method>', 'guest HTTP method', 'POST').option('--path <path>', 'guest path including query', '/')
@@ -374,7 +508,8 @@ export function buildProgram(deps = {}) {
             let request = o.requestFile ? await readFunctionJson(o.requestFile, MAX_FUNCTION_JSON_BYTES) : { method: o.method, path: o.path };
             if (o.bodyFile)
                 request.body_base64 = Buffer.from(await readFunctionFile(o.bodyFile, MAX_FUNCTION_BODY_BYTES)).toString('base64');
-            const response = await (await hivesClient()).hives[kind].invoke(project, id, request, { idempotencyKey: o.idempotencyKey });
+            const hivesApi = (await hivesClient()).hives;
+            const response = alias ? await hivesApi.functions.invokeAsync(project, id, request, { idempotencyKey: o.idempotencyKey }) : await hivesApi[kind].invoke(project, id, request, { idempotencyKey: o.idempotencyKey });
             const bytes = await hivesResponseBytes(response);
             if (g().json)
                 out.log(JSON.stringify({ status: response.status, headers: Object.fromEntries(response.headers), body_base64: Buffer.from(bytes).toString('base64') }));
@@ -389,6 +524,8 @@ export function buildProgram(deps = {}) {
     }
     invocationCommand(functions.command('invoke <project_id> <function_id>'), 'functions');
     invocationCommand(deployments.command('invoke <project_id> <deployment_id>'), 'deployments');
+    // The service's /invoke/async compatibility alias: the same completed guest response, no durable queue.
+    invocationCommand(functions.command('invoke-async <project_id> <function_id>'), 'functions', true);
     const operations = functions.command('operations').description('Read or release the original funding operation without replaying the guest');
     operations.command('get <project_id> <function_id> <operation_id>').action(async (project, fn, operation) => {
         const result = await (await hivesClient()).hives.functions.operations.get(project, fn, operation);
@@ -545,9 +682,12 @@ export function buildProgram(deps = {}) {
             page: positiveInteger(o.page, '--page', 10000), per_page: positiveInteger(o.perPage, '--per-page', 100) });
         emit(r, () => table(listOf(r), ['created_at', 'action', 'actor_id', 'resource_type', 'resource_name']));
     });
+    // Last: extends the hives groups defined above (flights, logs, env values, domain reads).
+    registerHivesCoverage(hives, { client: hivesClient, emit, readRequest: deps.readHivesRequest });
     // ---- relays ----------------------------------------------------------
     const relays = program.command('relays').description('Relays: DNS zones and records');
     registerRelaysEnrollment(relays, client, emit);
+    registerOperationCommands(relays, RELAYS_COMMANDS, { client, emit, signal: deps.signal });
     relays.command('zones').description('List DNS zones').option('--search <q>').action(async (o) => {
         const r = await (await client()).relays.zones.list(o.search ? { search: o.search } : {});
         emit(r, () => table((r.zones ?? []), ['name', 'type', 'record_count', 'dnssec_enabled', 'status']));
@@ -560,7 +700,58 @@ export function buildProgram(deps = {}) {
         const result = await (await client()).relays.zones.dnssec(zone);
         emit(result, () => JSON.stringify(result, null, 2));
     });
+    // Writes need relays:write and act on the selected project's existing Relays account.
+    const dnsInt = (value, option, minimum, maximum) => {
+        if (value === undefined)
+            return undefined;
+        if (!/^\d+$/.test(value) || Number(value) < minimum || Number(value) > maximum)
+            throw new Error(`${option} must be an integer from ${minimum} to ${maximum}.`);
+        return Number(value);
+    };
+    const recordId = (value) => dnsInt(value, '<record_id>', 1, Number.MAX_SAFE_INTEGER);
+    relays.command('create-zone <name>').description('Create a DNS zone')
+        .option('--type <type>', 'NATIVE, MASTER or SLAVE (default NATIVE)').option('--no-default-records', 'skip the default records')
+        .action(async (name, o) => {
+        const result = await (await client()).relays.zones.create({ name, ...(o.type ? { type: o.type.toUpperCase() } : {}),
+            create_default_records: o.defaultRecords });
+        emit(result, () => `${c.green('✓')} Created zone ${name}`);
+    });
+    relays.command('update-zone <zone>').description('Update a zone\'s type or SOA settings')
+        .option('--type <type>', 'NATIVE, MASTER or SLAVE').option('--primary-ns <host>').option('--hostmaster <email>')
+        .option('--refresh <seconds>').option('--retry <seconds>').option('--expire <seconds>').option('--soa-ttl <seconds>')
+        .action(async (zone, o) => {
+        const soa = Object.fromEntries(Object.entries({ primary_ns: o.primaryNs, hostmaster: o.hostmaster,
+            refresh: dnsInt(o.refresh, '--refresh', 60, 2 ** 31), retry: dnsInt(o.retry, '--retry', 60, 2 ** 31),
+            expire: dnsInt(o.expire, '--expire', 3600, 2 ** 31), ttl: dnsInt(o.soaTtl, '--soa-ttl', 60, 2 ** 31) }).filter(([, v]) => v !== undefined));
+        const body = { ...(o.type ? { type: o.type.toUpperCase() } : {}), ...(Object.keys(soa).length ? { soa } : {}) };
+        if (!Object.keys(body).length)
+            throw new Error('Nothing to update: pass --type or an SOA option.');
+        const result = await (await client()).relays.zones.update(zone, body);
+        emit(result, () => `${c.green('✓')} Updated zone ${zone}`);
+    });
+    relays.command('delete-zone <zone>').description('Delete a zone and all its records').action(async (zone) => {
+        const result = await (await client()).relays.zones.delete(zone);
+        emit(result, () => `${c.green('✓')} Deleted zone ${zone}`);
+    });
     const records = relays.command('records').description('DNS records in a zone');
+    records.command('get <zone> <record_id>').description('Read one record').action(async (zone, id) => {
+        const result = await (await client()).relays.records.get(zone, recordId(id));
+        emit(result, () => JSON.stringify(result, null, 2));
+    });
+    records.command('update <zone> <record_id>').description('Update a record')
+        .option('--name <name>').option('--type <type>').option('--content <content>').option('--ttl <seconds>', 'TTL, 60 to 86400')
+        .option('--priority <n>', '0 to 65535').option('--comment <text>').option('--disable', 'disable the record').option('--enable', 'enable the record')
+        .action(async (zone, id, o) => {
+        if (o.disable && o.enable)
+            throw new Error('Pass --disable or --enable, not both.');
+        const body = Object.fromEntries(Object.entries({ name: o.name, type: o.type?.toUpperCase(), content: o.content,
+            ttl: dnsInt(o.ttl, '--ttl', 60, 86400), priority: dnsInt(o.priority, '--priority', 0, 65535), comment: o.comment,
+            disabled: o.disable ? true : o.enable ? false : undefined }).filter(([, v]) => v !== undefined));
+        if (!Object.keys(body).length)
+            throw new Error('Nothing to update: pass at least one field option.');
+        const result = await (await client()).relays.records.update(zone, recordId(id), body);
+        emit(result, () => `${c.green('✓')} Updated record ${id} in ${zone}`);
+    });
     records.command('list <zone>', { isDefault: true }).option('--type <type>').action(async (zone, o) => {
         const r = await (await client()).relays.records.list(zone, o.type ? { type: o.type } : {});
         emit(r, () => table((r.records ?? []), ['id', 'name', 'type', 'content', 'ttl']));
@@ -573,10 +764,31 @@ export function buildProgram(deps = {}) {
         await (await client()).relays.records.delete(zone, Number(id));
         emit({ deleted: Number(id) }, () => `${c.green('✓')} Deleted record ${id} from ${zone}`);
     });
-    addHenryCommands(program, client, value => out.log(JSON.stringify(value, null, 2)));
+    addHenryCommands(program, client, value => out.log(JSON.stringify(value, null, 2)), { line: text => out.log(text), ...(deps.signal ? { signal: deps.signal } : {}) });
     registerFleets(program, client, (data) => emit(data, () => JSON.stringify(data, null, 2)));
-    registerFlocks(program, client, (data) => emit(data, () => JSON.stringify(data, null, 2)), env);
+    registerFlocks(program, client, emit, env, deps.readFlocksCode, () => !!g().json);
     registerBeacons(program, client, emit);
+    // ---- setup -----------------------------------------------------------
+    // The first-run experience lives in ./onboard and is imported only here, so no other command loads it.
+    program.command('setup [step]').description('Set up Genesis: sign in, pick a project, add the MCP server to your agents (resumable)')
+        .option('--restart', 'start again from the first step')
+        .option('--no-animation', 'draw every step still (also GENESIS_REDUCED_MOTION=1)')
+        .option('--screen-reader', 'linear output for screen readers (also GENESIS_SCREEN_READER=1)')
+        .option('--screencast', 'mask account names, emails and IDs, for recording demos (also GENESIS_SCREENCAST=1)')
+        .option('--sound', 'a soft chime when you are signed in and when setup finishes (also GENESIS_SOUND=1)')
+        .action(async (step, o) => {
+        const code = await runSetupLazily(o, step);
+        if (code)
+            throw new CommanderError(code, 'genesis.setup', '');
+    });
+    const runSetupLazily = async (o, step) => {
+        const [{ runSetup }, authModule, deviceModule] = await Promise.all([import('./onboard/index.js'), import('./auth.js'), import('./device-login.js')]);
+        return runSetup({ version: program.version() ?? '', env, fetch: f, auth, getStore, client: () => client(), openBrowser: deps.openBrowser ?? defaultOpen,
+            baseUrl: g().baseUrl ?? env.GENESIS_BASE_URL ?? DEFAULT_BASE_URL, log: (s) => out.log(s),
+            flags: { json: g().json, animation: o.animation, screenReader: o.screenReader, sound: o.sound, screencast: o.screencast, restart: o.restart, step },
+            login: { startLogin: authModule.startLogin, completeLogin: authModule.completeLogin, selectSavedContext: authModule.selectSavedContext,
+                savedLoginProvider: authModule.savedLoginProvider, startDeviceLogin: deviceModule.startDeviceLogin, completeDeviceLogin: deviceModule.completeDeviceLogin } });
+    };
     // ---- status ----------------------------------------------------------
     program.command('status').description('Live state of each Genesis service, from the gateway (GET /v1/status)').action(async () => {
         const configured = g().baseUrl ?? env.GENESIS_BASE_URL ?? DEFAULT_BASE_URL;
@@ -591,7 +803,7 @@ export function buildProgram(deps = {}) {
         const url = `${base.href.replace(/\/+$/, '')}/v1/status`;
         let response;
         try {
-            response = await f(url, { method: 'GET', headers: { accept: 'application/json', 'user-agent': 'genesis-cli/0.1.13' }, signal: AbortSignal.timeout(15_000) });
+            response = await f(url, { method: 'GET', headers: { accept: 'application/json', 'user-agent': 'genesis-cli/0.2.0' }, signal: AbortSignal.timeout(15_000) });
         }
         catch (e) {
             throw new Error(`Gateway unreachable at ${safe(url)}: ${safe(e.message)}`);
@@ -609,9 +821,26 @@ export function buildProgram(deps = {}) {
     });
     return program;
 }
+/**
+ * A bare `genesis` on a terminal, before setup is finished, is the first run: it opens `genesis setup`. Everywhere
+ * else (a pipe, CI, TERM=dumb, setup complete) it prints the help as before. Only the setup state file is read here.
+ */
+async function firstRun(argv, deps) {
+    if (argv.length > 2 || deps.out)
+        return false;
+    const env = deps.env ?? process.env;
+    const set = (v) => !!v && v !== '0' && v !== 'false';
+    if (!process.stdout.isTTY || !process.stdin.isTTY || env.TERM === 'dumb'
+        || set(env.CI) || env.GITHUB_ACTIONS || env.BUILDKITE || env.GITLAB_CI || env.TF_BUILD)
+        return false;
+    const { SetupStore, complete } = await import('./onboard/state.js');
+    return !complete(await SetupStore.for(env).read());
+}
 export async function main(argv, deps = {}) {
     const out = deps.out ?? stdio;
     const program = buildProgram(deps);
+    if (await firstRun(argv, deps).catch(() => false))
+        argv = [...argv, 'setup'];
     try {
         await program.parseAsync(argv);
         return 0;
@@ -621,6 +850,9 @@ export async function main(argv, deps = {}) {
             return e.exitCode;
         const json = program.opts().json;
         if (e instanceof GenesisError) {
+            // Dials needs a project, workspace and environment: from flags, a selected context or an org key's binding.
+            const dialsScopeHint = e.operationId?.startsWith('dials_') && /invalid_scope/i.test(`${e.code ?? ''} ${e.message} ${e.type}`)
+                ? ' Pass --workspace, --project and --environment, select a context (genesis context select), or use an org API key bound to a project.' : '';
             if (json)
                 out.err(JSON.stringify({ error: { type: e.type, status: e.status, message: e.message, request_id: e.requestId, ...errorCatalog(e),
                         ...((e instanceof HivesOperationError || e instanceof HivesQueueOperationError) ? { operation: e.operation } : {}),
@@ -628,7 +860,7 @@ export async function main(argv, deps = {}) {
                         ...(e instanceof MindsAgentError || e instanceof MindsOwnerError ? { code: e.code, ...(e instanceof MindsAgentError ? { dpop_nonce: e.dpopNonce } : {}),
                             ...(errorOutcome(e.body) !== undefined ? { outcome: errorOutcome(e.body) } : {}) } : {}) } }));
             else
-                out.err(`${c.red('✗')} ${safe(e.message)}${(e instanceof HivesOperationError || e instanceof HivesQueueOperationError) ? ` Operation: ${safe(e.operation.operation_id)} (${safe(e.operation.state)}).` : ''}${e.status ? c.dim(` (${e.status} ${safe(e.type)}${e.requestId ? `, request ${safe(e.requestId)}` : ''})`) : ''}`);
+                out.err(`${c.red('✗')} ${safe(e.message)}${dialsScopeHint}${(e instanceof HivesOperationError || e instanceof HivesQueueOperationError) ? ` Operation: ${safe(e.operation.operation_id)} (${safe(e.operation.state)}).` : ''}${e.status ? c.dim(` (${e.status} ${safe(e.type)})`) : ''}${e.requestId ? `\n${c.dim(`request_id: ${safe(e.requestId)}`)}` : ''}`);
             return 1;
         }
         const msg = e.message ?? String(e);

package/dist/minds.d.ts

@@ -1,3 +1,3 @@
 import { type Command } from 'commander';
-import type { Genesis } from '@onesi/genesis';
+import { type Genesis } from '@onesi/genesis';
 export declare function registerMinds(program: Command, client: () => Promise<Genesis>, emit: (data: unknown) => void, agentClient?: () => Promise<Genesis>, signal?: AbortSignal, ownerClient?: () => Promise<Genesis>): void;

package/dist/minds.js

@@ -1,8 +1,10 @@
 import { readFile, stat } from 'node:fs/promises';
 import { registerMindsOwner } from './minds-owner.js';
 import { Option } from 'commander';
+import { mindsServices } from '@onesi/genesis';
 export function registerMinds(program, client, emit, agentClient = client, signal, ownerClient = client) {
-    const minds = program.command('minds').description('Owned Minds and persisted memory; requires an admitted human Console Sandbox session');
+    // `minds engine ...` (generated, products.ts) may already have created the root.
+    const minds = (program.commands.find(c => c.name() === 'minds') ?? program.command('minds')).description('Owned Minds and persisted memory; a human Console Sandbox session, or an org API key with minds:read/minds:write/minds:manage');
     registerMindsOwner(minds, ownerClient, emit, signal);
     minds.command('list').option('--after <uuid>').option('--limit <number>').description('List real Minds and the current creation context fingerprint').action(async (options) => {
         emit(await (await client()).minds.list({ ...(options.after ? { after: options.after } : {}), ...(options.limit ? { limit: Number(options.limit) } : {}) }));
@@ -17,7 +19,13 @@ export function registerMinds(program, client, emit, agentClient = client, signa
         .requiredOption('--context-sha256 <hash>', 'context_sha256 from the current minds list response')
         .addOption(new Option('--plan <plan>', 'explicit plan; entitlement remains server-authorized').choices(['free', 'pro']))
         .addOption(new Option('--profile-id <profile>', 'fixed native profile; Pro defaults to D1, Free accepts only F1').choices(['F1', 'D1', 'D2']))
-        .action(async (name, options) => emit(await (await client()).minds.create(name, { idempotencyKey: options.idempotencyKey, contextSha256: options.contextSha256, ...(options.plan === undefined ? {} : { plan: options.plan }), ...(options.profileId === undefined ? {} : { profileId: options.profileId }) })));
+        .option('--services <list>', `comma-separated engine service groups (${mindsServices.join(', ')}); kv and memory always run`)
+        .action(async (name, options) => {
+        const services = options.services === undefined ? undefined : String(options.services).split(',').map((item) => item.trim()).filter(Boolean);
+        if (services && services.some(item => !mindsServices.includes(item)))
+            throw new Error(`Unknown Minds service; choose from ${mindsServices.join(', ')}.`);
+        emit(await (await client()).minds.create(name, { idempotencyKey: options.idempotencyKey, contextSha256: options.contextSha256, ...(options.plan === undefined ? {} : { plan: options.plan }), ...(options.profileId === undefined ? {} : { profileId: options.profileId }), ...(services === undefined ? {} : { services }) }));
+    });
     minds.command('resume <mind_id>').description('Resume the same Mind and retained volume; 202 means the operation is accepted')
         .requiredOption('--expected-generation <number>', 'desired_generation from a fresh owned Mind read')
         .requiredOption('--idempotency-key <uuid>', 'persist this UUID4 with the original generation after an uncertain response')
@@ -27,6 +35,23 @@ export function registerMinds(program, client, emit, agentClient = client, signa
         .requiredOption('--expected-generation <number>', 'desired_generation from a fresh owned Mind read')
         .requiredOption('--idempotency-key <uuid>', 'persist this UUID4 and original generation; no automatic retry')
         .action(async (id, options) => emit(await (await client()).minds.stop(id, Number(options.expectedGeneration), { idempotencyKey: options.idempotencyKey })));
+    minds.command('delete <mind_id>').description('Delete the Mind (lifecycle delete; org API keys need minds:write); 202 means accepted')
+        .requiredOption('--expected-generation <number>', 'desired_generation from a fresh owned Mind read')
+        .requiredOption('--idempotency-key <uuid>', 'persist this UUID4 and original generation; no automatic retry')
+        .action(async (id, options) => emit(await (await client()).minds.delete(id, Number(options.expectedGeneration), { idempotencyKey: options.idempotencyKey })));
+    minds.command('resize <mind_id>').description('Resize to an existing Pro profile (org API keys need minds:manage); 202 means accepted')
+        .requiredOption('--expected-generation <number>', 'desired_generation from a fresh owned Mind read')
+        .addOption(new Option('--profile-id <profile>', 'existing Pro profile').choices(['F1', 'D1', 'D2']).makeOptionMandatory())
+        .requiredOption('--idempotency-key <uuid>', 'persist this UUID4 and original generation; no automatic retry')
+        .action(async (id, options) => emit(await (await client()).minds.resize(id, Number(options.expectedGeneration), options.profileId, { idempotencyKey: options.idempotencyKey })));
+    const deliveries = minds.command('webhook-deliveries').description('Durable webhook receipts for an owned Mind; a stopped-idle Mind is woken');
+    deliveries.command('create <mind_id>').description('Record one delivery; replay the same delivery_id and body to read the original receipt')
+        .requiredOption('--delivery-id <uuid>', 'caller-chosen non-nil UUID; retain it after an uncertain response')
+        .requiredOption('--event-reference <reference>', 'opaque upstream event reference ([A-Za-z0-9_.:/-], at most 200)')
+        .requiredOption('--event-sha256 <hash>', 'lowercase hex SHA-256 of the upstream event')
+        .action(async (id, options) => emit(await (await client()).minds.webhookDeliveries.create(id, { delivery_id: options.deliveryId, event_reference: options.eventReference, event_sha256: options.eventSha256 })));
+    deliveries.command('get <mind_id> <delivery_id>').description('Read a receipt this principal issued')
+        .action(async (id, delivery) => emit(await (await client()).minds.webhookDeliveries.get(id, delivery)));
     const memory = minds.command('memory').description('Every operation selects one owned, ready Mind');
     memory.command('insert <mind_id>').requiredOption('--event-file <path>', 'JSON event with id, content and timestamp; returned id is its storage UUID')
         .action(async (id, options) => {
@@ -55,6 +80,16 @@ export function registerMinds(program, client, emit, agentClient = client, signa
         emit(await (await client()).minds.memory.search(mind, text, Number(options.limit)));
     });
     const agent = minds.command('agent').description('Use an existing agent credential; does not create an attachment or exchange a human session');
+    const createProof = async (path) => ({ signal, dpopProof: await readBounded(path, 4_096) });
+    agent.command('create <name>').description('Create a Free/F1 Sandbox Mind with an approved agent-create token; 202 means provisioning')
+        .requiredOption('--approval-id <uuid>', 'owner approval admitting this creation')
+        .requiredOption('--approval-version <number>', 'approval version')
+        .requiredOption('--operation-id <uuid>', 'persisted UUID4; also the idempotency key and the status lookup id')
+        .requiredOption('--dpop-proof-file <path>', 'fresh DPoP proof for the controller create method and URL')
+        .action(async (name, options) => emit(await (await agentClient()).minds.agent.create({ name, approvalId: options.approvalId, approvalVersion: Number(options.approvalVersion), operationId: options.operationId }, await createProof(options.dpopProofFile))));
+    agent.command('create-status <operation_id>').description('Read an agent Mind creation operation')
+        .requiredOption('--dpop-proof-file <path>', 'fresh DPoP proof for the controller status method and URL')
+        .action(async (operation, options) => emit(await (await agentClient()).minds.agent.createStatus(operation, await createProof(options.dpopProofFile))));
     const agentMemory = agent.command('memory').description('Private or explicitly authorized group memory; requests are never automatically retried');
     const scoped = (command) => command.option('--group <agp_id>', 'explicit canonical group; omit for private memory')
         .option('--dpop-proof-file <path>', 'fresh DPoP proof for the controller capability method and URL');

package/dist/onboard/art.d.ts

@@ -0,0 +1,50 @@
+/**
+ * One's marks as drawings: the emblem (Digital One, the disc with the eye knocked out), the Ones, and the hybrid ONE
+ * logotype whose O can close to the disc, wake as the eye, hop through the Ones and open back to the ring (JR-B103's
+ * cycle, the One site's components/ui/nav-logotype.tsx). Everything is drawn into a raster.Canvas from brand.ts.
+ *
+ * Paint rules (one-system.css): the disc is One's black on light and chalk on dark, never outlined or glowing; amber
+ * is only ever light inside the eye; the Ones wear their own colours, and those colours mean nothing else.
+ */
+import { ONES, type OneShape } from './brand.js';
+import { Canvas, type Color, type Mat } from './raster.js';
+import { sample, LIGHT, type Pose } from './eye.js';
+/**
+ * The terminal's own foreground. When the probe could not learn the background we draw ink and Digital One in this
+ * colour and the encoder emits SGR 39, so the mark is always the user's own ink: black on light, chalk on dark.
+ */
+export declare const DEFAULT_INK: Color;
+export declare const isDefaultInk: (c: Color) => boolean;
+export type Tone = 'light' | 'dark' | 'unknown';
+export declare const inkFor: (tone: Tone) => Color;
+export interface Head {
+    /** null: Digital One. Otherwise one of the Ones. */
+    one: OneShape | null;
+    pose: Pose;
+    /** agent-eye's light moment, -1 (waiting below) … 0 (full) … 1 (gone above); amber, inside the eye only. */
+    light?: number;
+    /** Squash for a hop: 1 is at rest; below 1 squats onto the pivot, above stretches. */
+    squash?: number;
+    /** Vertical offset in head units (a hop's lift). */
+    hop?: number;
+}
+/** Draw a head into the -100…100 box mapped by `m`. */
+export declare function drawHead(cv: Canvas, m: Mat, head: Head, tone: Tone): void;
+export declare const LOGO_ASPECT: number;
+export interface LogoState {
+    /** 0…1: the ring draws on clockwise from twelve o'clock. */
+    ring: number;
+    /** 0 the ring … 1 the disc (its hole closes on the enter curve). */
+    fill: number;
+    /** When set, the O is a head (One's eye awake, or one of the Ones) in the O's circle. */
+    head?: Head | null;
+    /** 0…1 each: the N and the E arrive, rising into place. */
+    n: number;
+    e: number;
+}
+export declare const LOGO_REST: LogoState;
+/** The hybrid ONE, `px` tall (cap height plus the O's overshoot), its top-left at (x, y) in canvas pixels. */
+export declare function drawLogotype(cv: Canvas, x: number, y: number, px: number, s: LogoState, tone: Tone, hint?: boolean): void;
+/** Digital One, `px` across, centred at (cx, cy). */
+export declare function drawEmblem(cv: Canvas, cx: number, cy: number, px: number, head: Partial<Head>, tone: Tone): void;
+export { ONES, LIGHT, sample };