@volter/world 2.0.0 → 2.0.2

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
@@ -34,7 +48,7 @@ world  — the twins your app needs, running together (the world of the current
   volter world branch [<name>]                           list branches, or make one from here and check it out
   volter world checkout <name>                           switch branches
   volter world replay <changeset> --into <branch>        feed a changeset's changes into another branch's twins
-  volter world clock show | set <iso> | advance <N s|m|h|d>   the world's clock: set, not observed
+  volter world clock show | set <iso> | advance <N s|m|h|d> | shift <N s|m|h|d> | clear   the world's clock: set, not observed
   volter world clone <url> --token <token> [--admin-token <t>]   connect this world to a remote and fetch its history (the admin token copies the whole tree at once)
   volter world fetch                                     what the remote observed since the last fetch
   volter world origin                                    where this world clones from and pushes to
@@ -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;
@@ -248,8 +272,10 @@ async function worldCommand(verb: string, args: string[]): Promise<void> {
       const [action, arg] = pos;
       if (action === 'set') { if (!arg) throw new Error('volter world clock set <iso-8601>'); out(world.setClock(arg)); return; }
       if (action === 'advance') { if (!arg) throw new Error('volter world clock advance <N s|m|h|d>'); out(world.advanceClock(arg)); return; }
-      if (action === undefined || action === 'show') { const c = world.clock(); out(`${c.at}${c.frozen ? '' : ' (wall clock — not set)'}`); return; }
-      throw new Error('volter world clock show | set <iso> | advance <N s|m|h|d>');
+      if (action === 'shift') { if (!arg) throw new Error('volter world clock shift <N s|m|h|d>'); out(world.shiftClock(arg)); return; }
+      if (action === 'clear') { out(world.clearClock()); return; }
+      if (action === undefined || action === 'show') { const c = world.clock(); out(`${c.at}${c.frozen ? '' : c.running ? ' (running)' : ' (wall clock — not set)'}`); return; }
+      throw new Error('volter world clock show | set <iso> | advance <N s|m|h|d> | shift <N s|m|h|d> | clear');
     }
     case 'replay': {
       const name = pos[0]; const into = value(args, '--into');
@@ -297,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': {
@@ -408,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> {
@@ -427,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') } : {}) });
@@ -454,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) {
@@ -465,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}`);
   }
 }
 

package/src/credentials.ts

@@ -36,12 +36,23 @@ export function storeToken(origin: string, token: string, path: string = credent
   chmodSync(path, 0o600);
 }
 
+/** Forget the token stored for an origin; whether one was stored. */
+export function forgetToken(origin: string, path: string = credentialsPath()): boolean {
+  const store = readStore(path); const key = normalizeOrigin(origin);
+  if (!(key in store)) return false;
+  delete store[key];
+  writeFileSync(path, `${JSON.stringify(store, null, 2)}\n`, { mode: 0o600 });
+  return true;
+}
+
 /** `volter login`: the hosted platform a person signed the CLI into — its origin, beside the credentials. */
 export function platformPath(): string { return join(dirname(credentialsPath()), 'platform.json'); }
 export function storePlatform(origin: string, path: string = platformPath()): void {
   mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
   writeFileSync(path, `${JSON.stringify({ url: normalizeOrigin(origin), savedAt: new Date().toISOString() }, null, 2)}\n`, { mode: 0o600 });
 }
+/** Forget which platform the CLI is signed into. */
+export function forgetPlatform(path: string = platformPath()): void { if (existsSync(path)) writeFileSync(path, '{}\n', { mode: 0o600 }); }
 export function platformOrigin(path: string = platformPath()): string | undefined {
   if (!existsSync(path)) return undefined;
   try { return (JSON.parse(readFileSync(path, 'utf8')) as { url?: string }).url; } catch { return undefined; }