@volter/world 2.0.1 → 2.0.2

package/src/agents.ts

@@ -0,0 +1,166 @@
+// `volter agents install` (docs/contributing/architecture.md, "The way in is the app's folder"): the skill
+// (skills/volter-world) and the MCP server (`volter mcp`) put into the coding agents on this machine. Each change is
+// idempotent and said; an entry another tool wrote is never touched: only our own `volter` entry and our own skill
+// folder or marked block are written.
+import { spawnSync } from 'node:child_process';
+import { cpSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { delimiter, dirname, isAbsolute, join, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export type Agent = 'claude' | 'cursor' | 'vscode' | 'codex';
+export const AGENTS: readonly Agent[] = ['claude', 'cursor', 'vscode', 'codex'];
+const NAMES: Record<Agent, string> = { claude: 'Claude Code', cursor: 'Cursor', vscode: 'VS Code', codex: 'Codex' };
+
+/** A command on PATH (with Windows' extensions), or null. */
+function which(cmd: string): string | null {
+  const exts = process.platform === 'win32' ? (process.env.PATHEXT ?? '.EXE;.CMD;.BAT').split(';').map((e) => e.toLowerCase()) : [''];
+  for (const dir of (process.env.PATH ?? '').split(delimiter)) {
+    if (!dir) continue;
+    for (const ext of ['', ...exts]) { const p = join(dir, `${cmd}${ext}`); if (existsSync(p)) return p; }
+  }
+  return null;
+}
+
+/** The skill's folder: the one shipped in the package (skills/, copied in at pack time), else this checkout's. */
+export function skillSource(): string {
+  const here = dirname(fileURLToPath(import.meta.url));
+  for (const candidate of [resolve(here, '..', 'skills', 'volter-world'), resolve(here, '..', '..', 'skills', 'volter-world'), resolve(here, '..', '..', '..', 'skills', 'volter-world'), resolve(here, '..', '..', '..', '..', 'skills', 'volter-world')]) {
+    if (existsSync(join(candidate, 'SKILL.md'))) return candidate;
+  }
+  throw new Error('the volter-world skill is not in this installation (skills/volter-world)');
+}
+
+/** How an agent starts the server: `volter mcp` when the command is on PATH, else this installation by its path. */
+export function mcpCommand(): { command: string; args: string[] } {
+  if (which('volter')) return { command: 'volter', args: ['mcp'] };
+  const cli = fileURLToPath(new URL(`./cli${import.meta.url.endsWith('.ts') ? '.ts' : '.js'}`, import.meta.url));
+  return { command: process.execPath, args: [cli, 'mcp'] };
+}
+
+/** The agents this machine (and this project) shows signs of. */
+export function detectAgents(project: string): Agent[] {
+  const home = homedir();
+  const found: Agent[] = [];
+  if (existsSync(join(home, '.claude')) || which('claude')) found.push('claude');
+  if (existsSync(join(home, '.cursor')) || which('cursor')) found.push('cursor');
+  if (existsSync(join(project, '.vscode')) || which('code')) found.push('vscode');
+  if (existsSync(join(home, '.codex')) || which('codex')) found.push('codex');
+  return found;
+}
+
+/** A path as a person reads it: inside the project relative to it, inside the home folder from ~, with forward slashes. */
+function shown(path: string): string {
+  const within = (base: string): string | null => { const r = relative(base, path); return r && !r.startsWith('..') && !isAbsolute(r) ? r.replace(/\\/g, '/') : null; };
+  const inProject = within(process.cwd()); if (inProject) return inProject;
+  const inHome = within(homedir()); if (inHome) return `~/${inHome}`;
+  return path;
+}
+
+const readJson = (path: string): Record<string, unknown> => {
+  if (!existsSync(path)) return {};
+  const raw = readFileSync(path, 'utf8').trim();
+  if (!raw) return {};
+  try { const v = JSON.parse(raw) as unknown; return v && typeof v === 'object' && !Array.isArray(v) ? v as Record<string, unknown> : {}; } catch { throw new Error(`${path} is not JSON; not changing it (add the volter server by hand)`); }
+};
+/** A config file replaced whole in one step (written beside it, then renamed over it): a reader never sees half of it. */
+const writeAtomic = (path: string, text: string): void => { mkdirSync(dirname(path), { recursive: true }); const tmp = `${path}.volter-${process.pid}.tmp`; writeFileSync(tmp, text); renameSync(tmp, path); };
+const writeJson = (path: string, value: unknown): void => writeAtomic(path, `${JSON.stringify(value, null, 2)}\n`);
+/** A command run as itself; on Windows, where `claude` is a .cmd that runs only in cmd, one line to cmd with each argument
+ *  quoted (a path with a space stays one argument), as cross-spawn does. */
+const runTool = (bin: string, args: string[]): ReturnType<typeof spawnSync> => process.platform === 'win32'
+  ? spawnSync(process.env.ComSpec ?? 'cmd.exe', ['/d', '/s', '/c', `"${[bin, ...args].map((a) => `"${a.replace(/"/g, '""')}"`).join(' ')}"`], { windowsHide: true, encoding: 'utf8', windowsVerbatimArguments: true })
+  : spawnSync(bin, args, { windowsHide: true, encoding: 'utf8' });
+const same = (a: unknown, b: unknown): boolean => JSON.stringify(a) === JSON.stringify(b);
+
+/** Our entry under `key` in a JSON config's server map: added, or already there; someone else's `volter` is left alone. */
+function mergeServer(path: string, key: 'mcpServers' | 'servers', entry: Record<string, unknown>): string {
+  const doc = readJson(path);
+  const servers = (doc[key] && typeof doc[key] === 'object' ? doc[key] : {}) as Record<string, unknown>;
+  const mine = servers.volter as Record<string, unknown> | undefined;
+  if (mine && same(mine, entry)) return `${shown(path)}: the volter server is already there`;
+  if (mine && !(typeof mine.command === 'string' && /volter|cli\.[tj]s/.test(`${mine.command} ${JSON.stringify(mine.args ?? [])}`))) return `${shown(path)}: a "volter" server someone else configured is there; left alone`;
+  doc[key] = { ...servers, volter: entry };
+  writeJson(path, doc);
+  return `${shown(path)}: ${mine ? 'updated' : 'added'} the volter server`;
+}
+
+/** The skill copied into an agent's skills folder: our own folder, replaced whole. */
+function copySkill(target: string): string {
+  const dest = join(target, 'volter-world');
+  rmSync(dest, { recursive: true, force: true });
+  mkdirSync(target, { recursive: true });
+  cpSync(skillSource(), dest, { recursive: true });
+  return `${shown(dest)}: the volter-world skill`;
+}
+
+const BEGIN = '<!-- volter-world:begin -->';
+const END = '<!-- volter-world:end -->';
+/** The skill's instructions as a marked block in a Markdown instructions file; the rest of the file untouched. */
+function markedBlock(path: string): string {
+  const body = readFileSync(join(skillSource(), 'AGENTS.md'), 'utf8').trimEnd();
+  const existing = existsSync(path) ? readFileSync(path, 'utf8') : '';
+  const start = existing.indexOf(BEGIN); const end = existing.indexOf(END);
+  const outside = start >= 0 && end > start ? `${existing.slice(0, start)}${existing.slice(end + END.length)}`.replace(/\n{3,}$/, '\n\n') : existing;
+  const next = `${outside.trimEnd()}${outside.trim() ? '\n\n' : ''}${BEGIN}\n${body}\n${END}\n`;
+  if (next === existing) return `${shown(path)}: the volter-world instructions are already there`;
+  writeAtomic(path, next);
+  return `${shown(path)}: ${start >= 0 ? 'updated' : 'added'} the volter-world instructions`;
+}
+
+/** Codex's config.toml: a [mcp_servers.volter] table appended when there is none; an existing one is left alone. */
+function codexServer(path: string, entry: { command: string; args: string[] }): string {
+  const existing = existsSync(path) ? readFileSync(path, 'utf8') : '';
+  if (/^\s*\[mcp_servers\.(?:volter|"volter"|'volter')\]\s*$/m.test(existing)) return `${shown(path)}: a [mcp_servers.volter] table is already there; left alone`;
+  const q = (s: string): string => JSON.stringify(s);
+  const table = `[mcp_servers.volter]\ncommand = ${q(entry.command)}\nargs = [${entry.args.map(q).join(', ')}]\n`;
+  mkdirSync(dirname(path), { recursive: true });
+  writeAtomic(path, `${existing.trimEnd()}${existing.trim() ? '\n\n' : ''}${table}`);
+  return `${shown(path)}: added the volter server`;
+}
+
+/** Claude Code: `claude mcp add` at user scope when the command is here (it owns its config file), else ~/.claude.json. */
+function claudeServer(entry: { command: string; args: string[] }): string {
+  const claude = which('claude');
+  if (claude) {
+    const has = runTool(claude, ['mcp', 'get', 'volter']);
+    if (has.status === 0) return 'Claude Code: the volter server is already registered (claude mcp get volter)';
+    const add = runTool(claude, ['mcp', 'add', '--scope', 'user', 'volter', '--', entry.command, ...entry.args]);
+    if (add.status === 0) return 'Claude Code: registered the volter server (claude mcp add --scope user volter)';
+  }
+  return mergeServer(join(homedir(), '.claude.json'), 'mcpServers', { type: 'stdio', command: entry.command, args: entry.args });
+}
+
+/** Install into each agent: what changed, one line each. */
+export function installAgents(agents: Agent[], project: string): string[] {
+  const entry = mcpCommand(); const home = homedir(); const lines: string[] = [];
+  for (const a of agents) {
+    try {
+      if (a === 'claude') { lines.push(copySkill(join(home, '.claude', 'skills'))); lines.push(claudeServer(entry)); }
+      if (a === 'cursor') lines.push(mergeServer(join(home, '.cursor', 'mcp.json'), 'mcpServers', { command: entry.command, args: entry.args }));
+      if (a === 'vscode') lines.push(mergeServer(join(project, '.vscode', 'mcp.json'), 'servers', { type: 'stdio', command: entry.command, args: entry.args }));
+      if (a === 'codex') { lines.push(markedBlock(join(home, '.codex', 'AGENTS.md'))); lines.push(codexServer(join(home, '.codex', 'config.toml'), entry)); }
+    } catch (e) { lines.push(`${NAMES[a]}: not changed: ${e instanceof Error ? e.message : String(e)}`); }
+  }
+  return lines;
+}
+
+/** `volter agents install [--claude] [--cursor] [--vscode] [--codex] [--yes]`. */
+export async function agentsCommand(verb: string | undefined, args: string[], out: (s: string) => void): Promise<void> {
+  if (verb !== 'install') throw new Error('volter agents install [--claude] [--cursor] [--vscode] [--codex] [--yes]');
+  const project = process.cwd();
+  const named = AGENTS.filter((a) => args.includes(`--${a}`));
+  const agents = named.length ? named : detectAgents(project);
+  if (agents.length === 0) { out('no coding agent found here (Claude Code, Cursor, VS Code, Codex); name one: volter agents install --claude'); process.exitCode = 1; return; }
+  const entry = mcpCommand();
+  out(`for      ${agents.map((a) => NAMES[a]).join(', ')}\nskill    volter-world\nserver   ${[entry.command, ...entry.args].join(' ')}`);
+  if (!args.includes('--yes')) {
+    if (!process.stdin.isTTY) { out('\nnothing changed: run again with --yes to install'); return; }
+    process.stdout.write('\nInstall? [y/N] ');
+    const answer = await new Promise<string>((done) => { process.stdin.once('data', (d) => done(String(d).trim().toLowerCase())); });
+    process.stdin.pause();
+    if (answer !== 'y' && answer !== 'yes') { out('nothing changed'); return; }
+  }
+  for (const line of installAgents(agents, project)) out(`  ${line}`);
+  out('\nRestart the agent, then ask it to "set up Volter World for this app".');
+}

package/src/cli.ts

@@ -3,27 +3,41 @@
 // verb. `volter world …` acts on the world of the cwd the way git acts on the repository of the
 // cwd; `volter twin <vendor> …` runs one twin on its own; `volter remote …` is the hosted remote.
 // One client of `World`; it adds nothing the SDK does not have.
-import { formatInitReport, resolveCatalog, findInstalledPackage, packCli, serveConsoleFor } from '@volter/world-runtime';
+import { detectRepoVendors, formatInitReport, resolveCatalog, findInstalledPackage, packCli, serveConsoleFor } from '@volter/world-runtime';
 import { readFileSync, realpathSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
-import { spawn } from 'node:child_process';
+import { spawn, spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { hostname } from 'node:os';
 import { formatLedgerDelta } from '@volter/world-core';
 import { existsSync } from 'node:fs';
 import { join, relative, resolve } from 'node:path';
-import { platformOrigin, requireToken, storePlatform, storeToken, tokenFor } from './credentials.ts';
+import { forgetPlatform, forgetToken, platformOrigin, requireToken, storePlatform, storeToken, tokenFor } from './credentials.ts';
 import { parseOriginUrl, World } from './world.ts';
 import { waitForServeShutdown } from './serve-shutdown.ts';
+import { startUpdateCheck } from './update-notice.ts';
+import type { ViewConsole } from '@volter/world-runtime';
+
+/** Open a URL in the person's browser; a machine without one only loses the convenience. */
+function openInBrowser(url: string): void {
+  // an http(s) URL only, and on Windows through the URL handler rather than cmd.exe, which would read `"`, `&` or `%VAR%`
+  // in it as commands
+  let target: string; try { const u = new URL(url); if (u.protocol !== 'http:' && u.protocol !== 'https:') return; target = u.href; } catch { return; }
+  const [cmd, ...pre] = process.platform === 'darwin' ? ['open'] : process.platform === 'win32' ? ['rundll32', 'url.dll,FileProtocolHandler'] : ['xdg-open'];
+  try { spawn(cmd!, [...pre, target], { windowsHide: true, stdio: 'ignore', detached: true }).on('error', () => undefined).unref(); } catch { /* no browser here */ }
+}
 
 export const HELP = `volter — run your app against a world of twins
 
 world  — the twins your app needs, running together (the world of the current directory)
-  volter world init [--name <world>] [--allow-unknown]   detect the app's vendors, write .volter/world.json
+  volter world init [--install] [--name <world>] [--allow-unknown]   detect the app's vendors (installing their twins when none are), write .volter/world.json
   volter world up [--sandbox] [--no-seed]                start the twins on this branch (loads the default data the first time)
   volter world run [--verbose] -- <command...>           run the app or its tests inside the world
   volter world activate                                  eval "$(volter world activate)": vendor CLIs and curl in this shell reach the twins
   volter world shell                                     a subshell with the world active
   volter world init --bare <org>/<world> --twins a,b      a world with no app: a shared world for a team, or one standing in for a vendor
-  volter world serve [--port <p>] [--console-port <c>]   serve this world on a URL under /<org>/<world>/; prints the token and the console (its own origin, port p+1 by default)
+  volter world serve [--port <p>] [--console-port <c>]   serve this world on a URL under /<org>/<world>/ for apps; prints the token and the console (on loopback: view's front, no token in the browser)
+  volter world view [--port <p>] [--host <h>] [--no-open] [--no-origins]   step into this world in a browser: its twins' own UIs, timeline, clock, branches (a non-loopback --host serves them on one origin)
   volter world console [<https://host/org/world>] [--port <p>]  the console on this machine for a World served elsewhere (default: this world's origin); needs @volter/world-console
   volter world status                                    world, branch, origin, unpushed changes, what is running
   volter world log [--receipts] [--json]                 every write the app made; --receipts adds each change's receipt
@@ -55,9 +69,17 @@ twin   — one twin: in this world, or on its own
   volter twin <vendor> mirror [--port <p>]               the twin's UI mirror
   volter twin <vendor> conformance                       check the twin against the vendor's spec
 
+agents — your coding agent, driving the same verbs
+  volter agents install [--claude] [--cursor] [--vscode] [--codex] [--yes]   put the volter-world skill and the MCP server into the agents found here
+  volter mcp                                             the MCP server (stdio) an agent starts: the verbs above as tools
+
 remote — the worlds this one pushes to and fetches from, by name
-  volter login <platform url> --token <personal token>  sign the CLI into the hosted platform (a personal token from the console)
-  volter remote add <name> <url|path|org/world> [--token <token>]  name a remote; org/world resolves through the platform you logged into
+  volter login <platform url> [--token <personal token>]  sign the CLI into the hosted platform: approve it in the browser (or a token made under Account, for CI)
+  volter whoami                                          the platform the CLI is signed into, as whom, and its orgs
+  volter logout                                          revoke the CLI's token at the platform and forget it here
+  volter remote add <name> <url|path|org/world> [--token <token>] [--create]  name a remote; org/world (or world, in one org) resolves through the platform you logged into; --create makes it there from this world's twins
+  volter open [<org>/<world>] [--no-open]                a World's dashboard: a hosted one through the platform, else this world's (as view)
+  volter completion bash|zsh|fish|powershell             print a completion script for your shell
   volter remote remove <name>                            forget it
   volter remote list                                     every remote, with its URL and whether a token is stored
   (the hosting product's serve answers here for one release: volter remote serve)
@@ -96,7 +118,7 @@ function when(iso: string): string { return iso.slice(11, 23); }
 
 /** Run another CLI in the foreground and adopt its exit code; a signal to us is a signal to it. */
 async function passthrough(cmd: string[], cwd = process.cwd()): Promise<number> {
-  const child = spawn(cmd[0]!, cmd.slice(1), { cwd, stdio: 'inherit' });
+  const child = spawn(cmd[0]!, cmd.slice(1), { windowsHide: true, cwd, stdio: 'inherit' });
   const forward = (signal: NodeJS.Signals) => () => { try { child.kill(signal); } catch { /* already gone */ } };
   for (const signal of ['SIGTERM', 'SIGINT', 'SIGHUP'] as const) process.on(signal, forward(signal));
   return await new Promise<number>((resolve, reject) => { child.once('error', reject); child.once('exit', (code, signal) => resolve(code ?? (signal ? 128 : 1))); });
@@ -123,12 +145,14 @@ async function worldCommand(verb: string, args: string[]): Promise<void> {
   }
   if (verb === 'init') {
     const app = resolve(worldDir ?? process.cwd());
+    await installDetectedTwins(app, flag(args, '--install'));
     const { result } = World.init(app, { ...(value(args, '--name') ? { name: value(args, '--name')! } : {}), force: flag(args, '--force'), allowUnknown: flag(args, '--allow-unknown') });
     if (asJson) json({ ok: result.ok, plan: result.plan, coverage: result.coverage, next: result.next });
     else {
       const twins = result.plan.vendors.filter((v) => v.service !== null).map((v) => v.vendor).sort();
       out(`twins  ${twins.join(', ') || '(none)'}\nwrote  ${relative(process.cwd(), result.plan.configPath) || result.plan.configPath}`);
       out(formatInitReport(result));
+      if (result.ok) await offerAgents();
     }
     if (!result.ok) process.exitCode = 1;
     return;
@@ -299,10 +323,45 @@ async function worldCommand(verb: string, args: string[]): Promise<void> {
       out(`changeset  ${cs.name}  ${cs.actions.length} change${cs.actions.length === 1 ? '' : 's'}\n  ${message}${cs.narration ? `\n${cs.narration.split('\n').map((l) => `  ${l}`).join('\n')}` : ''}`);
       return;
     }
+    case 'view':
     case 'serve': {
-      const served = await world.serve({ ...(value(args, '--port') ? { port: Number(value(args, '--port')) } : {}), ...(value(args, '--console-port') ? { consolePort: Number(value(args, '--console-port')) } : {}), ...(value(args, '--host') ? { host: value(args, '--host') } : {}), announce: (info) => out(`serving  ${info.name}  ${info.base}\ntoken    ${info.token}\nread     ${info.readToken}${info.console ? `\nconsole  ${info.console}` : ''}`) });
-      await waitForServeShutdown(() => served.stop());
-      process.exit(0); // success follows confirmed shutdown; failures reach main's error path
+      // `view` steps into the World in a browser; `serve` serves it for apps and scripts. Bound to this machine's
+      // loopback both are the same local front (the World's own origin, its console beside it) and the browser never
+      // needs a token (served-world.ts localSession); `serve` only leaves the browser closed. A non-loopback --host,
+      // or `serve --console-port`, is a World served for others: its console asks for a token.
+      const host = value(args, '--host');
+      const local = host === undefined || host === '127.0.0.1' || host === 'localhost' || host === '::1';
+      if (verb === 'serve' && (!local || value(args, '--console-port') !== undefined)) {
+        const served = await world.serve({ ...(value(args, '--port') ? { port: Number(value(args, '--port')) } : {}), ...(value(args, '--console-port') ? { consolePort: Number(value(args, '--console-port')) } : {}), ...(value(args, '--host') ? { host: value(args, '--host') } : {}), announce: (info) => out(`serving  ${info.name}  ${info.base}\ntoken    ${info.token}\nread     ${info.readToken}${info.console ? `\nconsole  ${info.console}` : ''}`) });
+        await waitForServeShutdown(() => served.stop());
+        process.exit(0); // success follows confirmed shutdown; failures reach main's error path
+        return;
+      }
+      // the console mounts when it is installed beside the CLI; without it the World serves its doors and mirrors
+      const console = await (async (): Promise<ViewConsole | undefined> => {
+        try { const mod = await import('@volter/world-console') as { createConsole: () => ViewConsole }; return mod.createConsole(); } catch (error) {
+          // not installed is one thing; installed and broken is another, and says why
+          const missing = /ERR_MODULE_NOT_FOUND|Cannot find (package|module)/.test(`${(error as { code?: string }).code ?? ''} ${String(error)}`);
+          if (!missing) process.stderr.write(`the console failed to load (the World is served without it): ${error instanceof Error ? error.message : String(error)}\n`);
+          return undefined;
+        }
+      })();
+      // `serve` says what it always said first (`serving <name> <url>`, then the tokens: scripts and the guides read
+      // those lines), and the local front's own lines after them; `view` says `viewing` as it goes
+      const later: string[] = [];
+      const view = await world.view({ ...(value(args, '--port') ? { port: Number(value(args, '--port')) } : {}), ...(host ? { host } : {}), ...(console ? { console } : {}), ...(args.includes('--no-origins') ? { origins: false } : {}), announce: (line) => { if (verb !== 'serve') out(line); else if (!line.startsWith('viewing')) later.push(line); } });
+      if (verb === 'serve') { out(`serving  ${view.served}  ${view.base}\ntoken    ${view.token}\nread     ${view.readToken}`); for (const line of later) out(line); }
+      // a local World's page opens itself; a World served for others is handed its token in the URL's fragment
+      // (which the browser never sends), taken once
+      // (with --no-origins every World shares one origin, where no page is handed a session: the token again)
+      const open = view.console ? (local && view.origin ? view.console : `${view.console}#token=${encodeURIComponent(view.token)}`) : null;
+      // the read token's own one-line way in, for handing to someone who should look and not touch
+      // (not on a local World: any of its pages can open a write session there, so a read-only link restricts nothing)
+      const readOnly = view.console && !(local && view.origin) ? `${view.console}#token=${encodeURIComponent(view.readToken)}` : null;
+      out(`${local && view.origin ? `apps     the World's tokens are in .volter/token and .volter/token.read (apps and scripts present them; the browser needs none)` : verb === 'serve' ? '' : `token    ${view.token}\nread     ${view.readToken}`}${readOnly ? `\nread-only view  ${readOnly}` : ''}${view.console ? '' : '\n(no console installed: `npm install -D @volter/world-console` to look around in a browser)'}${view.origin ? '\n(the World opens at its own *.localhost origin; if your browser cannot reach *.localhost, run again with --no-origins)' : ''}`);
+      if (open && verb === 'view' && !args.includes('--no-open')) openInBrowser(open);
+      await waitForServeShutdown(() => view.stop());
+      process.exit(0);
       return;
     }
     case 'rebase': {
@@ -410,17 +469,90 @@ function remoteCli(): string {
   throw new Error('volter remote: the hosting product (@volter/world-host) is not installed — `bun add -d @volter/world-host`');
 }
 
-/** `volter login <platform url> --token <personal token>`: the CLI signed into the hosted platform as you — the
- *  token is a personal access token from the console (shown once there), kept in your config directory. */
+/** `volter login <platform url>`: the CLI signed into the hosted platform as you, through the browser (the device
+ *  authorization grant, as `gh auth login`): the platform shows a code, you approve it there signed in as yourself,
+ *  and the command collects a personal token named for this machine. `--token <personal token>` (one made in the
+ *  platform under Account) signs in without a browser, for CI. Either way it is kept in your config directory. */
 async function loginCommand(args: string[]): Promise<void> {
-  const url = positionals(args, VALUE_FLAGS)[0]; const token = value(args, '--token');
-  if (!url || !token) throw new Error('volter login <platform url> --token <personal token>  (make one in the console under "You")');
-  const origin = url.replace(/\/+$/, '');
+  const url = positionals(args, VALUE_FLAGS)[0];
+  if (!url) throw new Error('volter login <platform url> [--token <personal token>] [--no-open]');
+  let origin: string; try { const u = new URL(url); if (u.protocol !== 'https:' && u.protocol !== 'http:') throw new Error(); origin = u.origin; } catch { throw new Error(`${url} is not a platform address (https://…)`); }
+  const token = value(args, '--token') ?? await deviceSignIn(origin, !flag(args, '--no-open'));
   const res = await fetch(`${origin}/-/orgs`, { headers: { authorization: `Bearer ${token}` } });
   const body = (await res.json().catch(() => ({}))) as { person?: { email?: string; id?: string }; orgs?: Array<{ slug: string | null; name: string }>; error?: string };
   if (!res.ok) throw new Error(`${origin} answered ${res.status}: ${body.error ?? 'not signed in'}`);
   storeToken(origin, token); storePlatform(origin);
-  out(`signed in  ${origin}  as ${body.person?.email ?? body.person?.id ?? 'you'}\norgs       ${(body.orgs ?? []).map((o) => o.slug ?? o.name).join(', ') || '(none yet)'}\nnext       volter remote add origin <org>/<world>`);
+  out(`signed in  ${origin}  as ${body.person?.email ?? body.person?.id ?? 'you'}\norgs       ${(body.orgs ?? []).map((o) => o.slug ?? o.name).join(', ') || '(none yet)'}\nnext       in your app's folder: volter world init, then volter remote add origin ${(body.orgs ?? [])[0]?.slug ?? '<org>'}/<world> --create`);
+}
+
+/** `volter whoami`: which platform the command is signed into, as whom, and the orgs it reaches. */
+async function whoamiCommand(): Promise<void> {
+  const origin = platformOrigin(); const token = origin ? tokenFor(origin) : undefined;
+  if (!origin || !token) { out('not signed in  (volter login <platform url>)'); process.exitCode = 1; return; }
+  const res = await fetch(`${origin}/-/orgs`, { headers: { authorization: `Bearer ${token}` } }).catch(() => null);
+  if (!res) throw new Error(`${origin} did not answer`);
+  const body = (await res.json().catch(() => ({}))) as { person?: { email?: string; id?: string }; orgs?: Array<{ slug: string | null; name: string; role?: string }>; error?: string };
+  // a token the platform no longer takes is signed out; one it takes but that may not read orgs is still signed in
+  if (res.status === 403) { out(`signed in  ${origin}  (this token may not read your orgs: ${body.error ?? 'refused'})`); return; }
+  if (!res.ok) { out(`signed out  ${origin}: ${body.error ?? res.status} — volter login ${origin}`); process.exitCode = 1; return; }
+  out(`signed in  ${origin}  as ${body.person?.email ?? body.person?.id ?? 'you'}\norgs       ${(body.orgs ?? []).map((o) => `${o.slug ?? o.name}${o.role === 'org:admin' ? ' (admin)' : ''}`).join(', ') || '(none yet)'}`);
+}
+
+/** `volter logout`: the command's token is revoked at the platform (a token may always revoke itself) and forgotten here. */
+async function logoutCommand(): Promise<void> {
+  const origin = platformOrigin(); const token = origin ? tokenFor(origin) : undefined;
+  if (!origin || !token) { out('not signed in'); return; }
+  const id = createHash('sha256').update(token).digest('hex');
+  const res = await fetch(`${origin}/-/tokens/${id}`, { method: 'DELETE', headers: { authorization: `Bearer ${token}` } }).catch(() => null);
+  forgetToken(origin); forgetPlatform();
+  out(res?.ok ? `signed out  ${origin}  (its token is revoked)` : `signed out  ${origin}  (forgotten here; the platform did not revoke the token${res ? ` — ${res.status}` : ''}, so revoke it under Account)`);
+}
+
+/** The browser half of `volter login`: ask the platform for a code, send the person to approve it, and wait (at the
+ *  platform's pace) for the personal token it hands over once they do. */
+async function deviceSignIn(origin: string, openBrowser: boolean): Promise<string> {
+  const started = await fetch(`${origin}/-/cli/device`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ name: hostname() }) }).catch((e: unknown) => { throw new Error(`${origin} did not answer: ${e instanceof Error ? e.message : String(e)}`); });
+  const grant = (await started.json().catch(() => ({}))) as { device_code?: string; user_code?: string; verification_uri_complete?: string; expires_in?: number; interval?: number; error?: string };
+  if (!started.ok || !grant.device_code || !grant.user_code || !/^[A-Z]{4}-[A-Z]{4}$/.test(grant.user_code)) throw new Error(`${origin} cannot sign the command in through the browser (${started.status}${grant.error ? `: ${grant.error}` : ''}) — make a token on the platform under Account and use --token`);
+  // the page is this platform's own, built here from the address you gave and the code: nothing the platform answers is
+  // opened as it stands
+  const page = `${origin}/-/cli/approve?code=${grant.user_code}`;
+  process.stderr.write(`approve    ${page}\ncode       ${grant.user_code}  (check the page shows the same)\n`);
+  if (openBrowser) openInBrowser(page);
+  const until = Date.now() + (grant.expires_in ?? 600) * 1000; const every = Math.max(1, grant.interval ?? 5) * 1000;
+  while (Date.now() < until) {
+    await new Promise((r) => setTimeout(r, every));
+    const res = await fetch(`${origin}/-/cli/token`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ device_code: grant.device_code }) }).catch(() => null);
+    if (!res) continue;
+    const body = (await res.json().catch(() => ({}))) as { token?: string; error?: string };
+    if (res.ok && body.token) return body.token;
+    if (body.error === 'authorization_pending' || body.error === 'slow_down') continue;
+    if (body.error === 'access_denied') throw new Error('refused in the browser: the command was not signed in');
+    throw new Error(`the code expired or was already used (${body.error ?? res.status}) — run volter login again`);
+  }
+  throw new Error('the code expired before it was approved — run volter login again');
+}
+
+/** "a, b and c". */
+const listed = (names: string[]): string => (names.length <= 1 ? names.join('') : `${names.slice(0, -1).join(', ')} and ${names[names.length - 1]}`);
+
+/** A yes from the person at the terminal; no terminal is a no (a script says --create instead). */
+async function confirm(question: string): Promise<boolean> {
+  if (!process.stdin.isTTY || !process.stderr.isTTY) return false;
+  const { createInterface } = await import('node:readline/promises');
+  const rl = createInterface({ input: process.stdin, output: process.stderr });
+  try { return /^y(es)?$/i.test((await rl.question(question)).trim()); } finally { rl.close(); }
+}
+
+/** The org a bare world name belongs to: the one org the person is in, else a question they answer by naming it. */
+async function onlyOrg(platform: string, personal: string, world: string): Promise<string> {
+  const res = await fetch(`${platform}/-/orgs`, { headers: { authorization: `Bearer ${personal}` } });
+  const body = (await res.json().catch(() => ({}))) as { orgs?: Array<{ slug: string | null; id?: string }>; error?: string };
+  if (!res.ok) throw new Error(`${platform} answered ${res.status}: ${body.error ?? 'not signed in'} — volter login ${platform}`);
+  const orgs = (body.orgs ?? []).map((o) => o.slug ?? o.id ?? '').filter(Boolean);
+  if (orgs.length === 1) return orgs[0]!;
+  if (orgs.length === 0) throw new Error(`you are in no org on ${platform} yet — make one there, then volter remote add origin <org>/${world}`);
+  throw new Error(`you are in ${orgs.length} orgs (${listed(orgs)}): say which, volter remote add origin <org>/${world}`);
 }
 
 async function remoteCommand(verb: string, args: string[]): Promise<void> {
@@ -429,16 +561,35 @@ async function remoteCommand(verb: string, args: string[]): Promise<void> {
     const pos = positionals(args, VALUE_FLAGS);
     if (verb === 'add') {
       const [name, target] = pos;
-      if (!name || !target) throw new Error('volter remote add <name> <url|path|org/world> [--token <token>]');
-      // `org/world`: a world the hosted platform serves for your org — its address and token come through the platform, never by hand
-      if (/^[a-z0-9][a-z0-9-]*\/[a-z0-9][a-z0-9-]*$/.test(target) && !existsSync(target)) {
-        const platform = platformOrigin(); if (!platform) throw new Error(`${target} looks like a hosted world (org/world) — \`volter login <platform url> --token <personal token>\` first`);
+      if (!name || !target) throw new Error('volter remote add <name> <url|path|org/world> [--token <token>] [--create]');
+      // `org/world` (or `world`, when you are in one org): a world the hosted platform serves for your org — its address
+      // and token come through the platform, never by hand; one that is not there yet is made there from this world's
+      // vendors, asked first, or at once with --create (a script's or an agent's way)
+      // a bare word is a hosted world only when this command is signed into a platform; otherwise it is a folder, as ever
+      const hosted = !existsSync(target) && (/^[a-z0-9][a-z0-9-]*\/[a-z0-9][a-z0-9-]*$/.test(target) || (/^[a-z0-9][a-z0-9-]*$/.test(target) && Boolean(platformOrigin())));
+      if (hosted) {
+        const platform = platformOrigin(); if (!platform) throw new Error(`${target} looks like a hosted world (org/world) — \`volter login <platform url>\` first`);
         const personal = tokenFor(platform); if (!personal) throw new Error(`no personal token stored for ${platform} — \`volter login\` again`);
-        const res = await fetch(`${platform}/-/worlds/${target}/token`, { headers: { authorization: `Bearer ${personal}` } });
-        const body = (await res.json().catch(() => ({}))) as { base?: string; token?: string; error?: string };
+        const served = target.includes('/') ? target : `${await onlyOrg(platform, personal, target)}/${target}`;
+        const key = (): Promise<Response> => fetch(`${platform}/-/worlds/${served}/token`, { headers: { authorization: `Bearer ${personal}` } });
+        let res = await key();
+        let body = (await res.clone().json().catch(() => ({}))) as { base?: string; token?: string; scope?: string; error?: string };
+        if (res.status === 404 && /^no world /.test(body.error ?? '')) {
+          const vendors = world.vendors();
+          if (vendors.length === 0) throw new Error(`${served} is not on ${platform} yet, and this world names no twins to make it with — \`volter world init\` first`);
+          if (!flag(args, '--create') && !(await confirm(`${served} is not on ${platform}. Make it there with ${listed(vendors)}? [y/N] `))) {
+            throw new Error(`${served} is not on ${platform}${process.stdin.isTTY ? '' : ' — add --create to make it with this world\'s twins'}${target.includes('/') ? '' : ` (a folder? name it ./${target})`}`);
+          }
+          const [org, worldName] = served.split('/') as [string, string];
+          const made = await fetch(`${platform}/-/worlds`, { method: 'POST', headers: { authorization: `Bearer ${personal}`, 'content-type': 'application/json' }, body: JSON.stringify({ org, world: worldName, vendors }) });
+          const madeBody = (await made.json().catch(() => ({}))) as { name?: string; error?: string };
+          if (!made.ok) throw new Error(`the platform did not make ${served} (${made.status}): ${madeBody.error ?? 'refused'}`);
+          out(`made     ${madeBody.name ?? served}  on ${platform}  (${listed(vendors)})`);
+          res = await key(); body = (await res.json().catch(() => ({}))) as typeof body;
+        }
         if (!res.ok || !body.base || !body.token) throw new Error(`the platform answered ${res.status}: ${body.error ?? 'no such world in your orgs'}`);
         world.addRemote(name, body.base, { token: body.token });
-        out(`remote   ${name}  ${body.base}  (through ${platform})`);
+        out(`remote   ${name}  ${body.base}  (through ${platform}${body.scope === 'read' ? ', read only: this token may not write Worlds' : ''})`);
         return;
       }
       world.addRemote(name, target, { ...(value(args, '--token') ? { token: value(args, '--token') } : {}) });
@@ -456,8 +607,133 @@ async function remoteCommand(verb: string, args: string[]): Promise<void> {
   throw new Error(`volter remote: unknown verb "${verb}"\n\n${HELP}`);
 }
 
+/** `volter open [<org>/<world>] [--no-open]`: a World's dashboard. A hosted World (named, or this world's origin on the
+ *  platform the command is signed into) opens through the platform, which signs the person in with a pass; otherwise
+ *  it is this world's own, as `volter world view` serves it. */
+async function openCommand(args: string[]): Promise<void> {
+  const named = positionals(args, VALUE_FLAGS)[0];
+  const platform = platformOrigin();
+  let served = named && /^[a-z0-9][a-z0-9-]*\/[a-z0-9][a-z0-9-]*$/.test(named) ? named : null;
+  if (!served && !named && platform) {
+    // this world's origin, when it is a World the platform serves: its namespace is <org>/<world>
+    try { const origin = World.open({ ...(value(args, '--world') ? { root: value(args, '--world') } : {}) }).remote(); if (origin && tokenFor(origin.url) && /^[a-z0-9-]+\/[a-z0-9-]+$/.test(origin.namespace)) served = origin.namespace; } catch { /* no world here */ }
+  }
+  if (named && !served) throw new Error(`volter open ${named}: name a hosted World as <org>/<world>, or run it in the app's folder for this world`);
+  if (served) {
+    if (!platform) throw new Error(`${served} is a hosted World — \`volter login <platform url>\` first`);
+    const url = `${platform}/-/worlds/${served}/open`;
+    out(url);
+    if (!flag(args, '--no-open')) openInBrowser(url);
+    return;
+  }
+  await worldCommand('view', args);
+}
+
+/** The command tree for completion, read from HELP (the one list of commands): noun → its verbs. */
+function commandTree(): Record<string, string[]> {
+  const tree: Record<string, string[]> = { open: [], completion: ['bash', 'zsh', 'fish', 'powershell'] };
+  for (const m of HELP.matchAll(/^\s+volter ([a-z]+)(?: ([a-z][a-z-]*))?/gm)) {
+    const [, noun, verb] = m; (tree[noun!] ??= []);
+    if (verb && !tree[noun!]!.includes(verb)) tree[noun!]!.push(verb);
+  }
+  return tree;
+}
+
+/** `volter completion bash|zsh|fish|powershell`: a script that completes volter's nouns and verbs in that shell. */
+function completionScript(shell: string | undefined): string {
+  const tree = commandTree(); const nouns = Object.keys(tree).join(' ');
+  const cases = (fmt: (noun: string, verbs: string) => string): string => Object.entries(tree).filter(([, v]) => v.length).map(([n, v]) => fmt(n, v.join(' '))).join('\n');
+  switch (shell) {
+    case 'bash': case 'zsh':
+      return `${shell === 'zsh' ? 'autoload -U +X bashcompinit && bashcompinit\n' : ''}# volter completion (${shell}): eval "$(volter completion ${shell})"
+_volter() {
+  local cur=\${COMP_WORDS[COMP_CWORD]}
+  if [ "$COMP_CWORD" -eq 1 ]; then COMPREPLY=($(compgen -W "${nouns}" -- "$cur")); return; fi
+  if [ "$COMP_CWORD" -eq 2 ]; then
+    case "\${COMP_WORDS[1]}" in
+${cases((n, v) => `      ${n}) COMPREPLY=($(compgen -W "${v}" -- "$cur")) ;;`)}
+    esac
+  fi
+}
+complete -o default -F _volter volter
+`;
+    case 'fish':
+      return `# volter completion (fish): volter completion fish | source
+complete -c volter -f -n '__fish_use_subcommand' -a '${nouns}'
+${cases((n, v) => `complete -c volter -f -n '__fish_seen_subcommand_from ${n}; and test (count (commandline -opc)) -eq 2' -a '${v}'`)}
+`;
+    case 'powershell':
+      return `# volter completion (PowerShell): volter completion powershell | Out-String | Invoke-Expression
+Register-ArgumentCompleter -Native -CommandName volter -ScriptBlock {
+  param($wordToComplete, $commandAst, $cursorPosition)
+  $words = @($commandAst.CommandElements | ForEach-Object { $_.ToString() })
+  $tree = @{
+${Object.entries(tree).map(([n, v]) => `    '${n}' = @(${v.map((x) => `'${x}'`).join(', ')})`).join('\n')}
+  }
+  $choices = if ($words.Count -le 1 -or ($words.Count -eq 2 -and $wordToComplete)) { $tree.Keys } elseif ($tree.ContainsKey($words[1])) { $tree[$words[1]] } else { @() }
+  $choices | Where-Object { $_ -like "$wordToComplete*" } | Sort-Object | ForEach-Object { [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_) }
+}
+`;
+    default:
+      throw new Error('volter completion bash|zsh|fish|powershell');
+  }
+}
+
+/** A fresh app has no twins installed, so `init` has nothing to plan with: its vendors are found from what the app
+ *  depends on and names in its env (the signatures ship with the command), and the twins for them are installed with
+ *  the app's own package manager: asked at a terminal, or at once with `--install` (a script's or an agent's way). */
+async function installDetectedTwins(app: string, install: boolean): Promise<void> {
+  try { if (resolveCatalog(app).vendors().length > 0) return; } catch { /* no twins here yet */ }
+  const found = detectRepoVendors(app).detected;
+  const vendors = [...found.keys()].filter((v) => /^[a-z0-9][a-z0-9-]*$/.test(v)).sort();
+  if (vendors.length === 0) return; // init says what it found and how to add a twin by hand
+  const pkgs = vendors.map((v) => `@volter/twin-${v}`);
+  const has = (file: string): boolean => existsSync(join(app, file));
+  // the app's own package manager, by its lockfile; npm where there is none
+  const command = has('bun.lock') || has('bun.lockb') ? `bun add -d ${pkgs.join(' ')}` : has('pnpm-lock.yaml') ? `pnpm add -D ${pkgs.join(' ')}` : has('yarn.lock') ? `yarn add -D ${pkgs.join(' ')}` : `npm install -D ${pkgs.join(' ')}`;
+  out(`detected  ${vendors.map((v) => `${v} (${(found.get(v) ?? []).slice(0, 2).join(', ')})`).join('; ')}`);
+  out(`twins     ${pkgs.join(' ')}`);
+  let yes = install;
+  if (!yes && process.stdin.isTTY && process.stdout.isTTY) {
+    process.stdout.write(`Install them now (${command})? [Y/n] `);
+    const answer = await new Promise<string>((done) => { process.stdin.once('data', (d) => done(String(d).trim().toLowerCase())); });
+    process.stdin.pause();
+    yes = answer === '' || answer === 'y' || answer === 'yes';
+  }
+  if (!yes) throw new Error(`install the twins first: ${command}
+then run volter world init again (or volter world init --install does both)`);
+  // one command line built from the checked names above: nothing of anyone's input reaches the shell
+  const ran = spawnSync(command, { cwd: app, stdio: 'inherit', shell: true, windowsHide: true });
+  if (ran.status !== 0) throw new Error(`${command} failed (exit ${ran.status ?? 'none'})`);
+}
+
+/** After `volter world init`: a person at a terminal is asked whether to set up their coding agents; anyone else is
+ *  told the command. */
+async function offerAgents(): Promise<void> {
+  const { detectAgents, installAgents } = await import('./agents.ts');
+  const found = detectAgents(process.cwd());
+  if (found.length === 0) return;
+  if (!process.stdin.isTTY || !process.stdout.isTTY) { out('\nagents   volter agents install --yes   (the volter-world skill and MCP server for your coding agents)'); return; }
+  process.stdout.write(`\nSet up your coding agent${found.length === 1 ? '' : 's'} (${found.join(', ')}) to drive this World? [y/N] `);
+  const answer = await new Promise<string>((done) => { process.stdin.once('data', (d) => done(String(d).trim().toLowerCase())); });
+  process.stdin.pause();
+  if (answer === 'y' || answer === 'yes') for (const line of installAgents(found, process.cwd())) out(`  ${line}`);
+  else out('later: volter agents install');
+}
+
+/** This package's version, for the MCP server's handshake. */
+function ownVersion(): string {
+  try { return (JSON.parse(readFileSync(fileURLToPath(new URL('../package.json', import.meta.url)), 'utf8')) as { version?: string }).version ?? '0.0.0'; } catch { return '0.0.0'; }
+}
+
 async function main(): Promise<void> {
   const [noun, verb, ...args] = process.argv.slice(2);
+  const notice = startUpdateCheck(process.argv.slice(2));
+  await dispatch(noun, verb, args);
+  await notice();
+}
+
+async function dispatch(noun: string | undefined, verb: string | undefined, args: string[]): Promise<void> {
   if (!noun || noun === '--help' || noun === '-h' || noun === 'help') { out(HELP); return; }
   if (verb === '--help' || verb === '-h') { out(HELP); return; }
   switch (noun) {
@@ -467,14 +743,22 @@ async function main(): Promise<void> {
       return;
     }
     case 'login': await loginCommand([verb, ...args].filter((a): a is string => a !== undefined)); return;
+    case 'logout': await logoutCommand(); return;
+    case 'whoami': await whoamiCommand(); return;
     case 'twin': await twinCommand([verb, ...args].filter((a): a is string => a !== undefined)); return;
+    case 'mcp': { const { serveMcp } = await import('./mcp.ts'); await serveMcp(ownVersion()); return; }
+    case 'agents': { const { agentsCommand } = await import('./agents.ts'); await agentsCommand(verb, args, out); return; }
     case 'remote': {
       if (!verb) throw new Error('volter remote: which verb? add | remove | list | serve');
       await remoteCommand(verb, args);
       return;
     }
+    case 'open': await openCommand([verb, ...args].filter((a): a is string => a !== undefined)); return;
+    case 'completion': process.stdout.write(completionScript(verb)); return;
     default:
-      throw new Error(`volter: unknown noun "${noun}" — world, twin or remote\n\n${HELP}`);
+      throw new Error(`volter: unknown noun "${noun}" — world, twin, remote, open, completion, agents or mcp
+
+${HELP}`);
   }
 }