@volter/world 2.0.0 → 2.0.2

package/dist/skills/volter-world/AGENTS.md

@@ -0,0 +1,155 @@
+# volter-world — operating a World
+
+A World contains only the vendors deliberately selected for substitution in the current workflow.
+Review detected vendors before including them. The app uses its real SDKs unchanged;
+environment injection, a Node preload and a scoped HTTPS proxy route configured vendors to twins.
+
+The state model is **Neon for every SaaS**: a log, checkpoints and branches over a parent position.
+Git-inspired verbs describe operations; there is no staging or commit step. Push moves entries
+between Worlds. Deploy performs them against a vendor at a real-system root under its policy.
+The canonical [model](https://github.com/volter-ai/twin/blob/main/docs/concepts/the-model.md),
+[lifecycle](https://github.com/volter-ai/twin/blob/main/docs/concepts/worlds.md) and
+[CLI reference](https://github.com/volter-ai/twin/blob/main/docs/reference/cli.md) own the details.
+
+## Set up a World for an app
+
+In the app's folder (the [guide](https://github.com/volter-ai/twin/blob/main/docs/guides/use-with-a-coding-agent.md)):
+
+```bash
+npm install -g @volter/world     # once; `volter agents install` then adds this skill and the MCP server to your agents
+volter world init                # detects the vendors from the app's manifests and env names; writes .volter/world.json
+volter world up
+volter world run -- npm test     # the app's own test command
+volter world log                 # what the app did at each vendor
+```
+
+Show the person the vendors `init` detected, and why, before keeping them. Keys the app reads
+(named in `.env.example`) get throwaway values in the World's env; never put real credentials in
+a World to get a test past validation. `volter world view --no-open` runs the World with its
+dashboard and prints its link for the person; it keeps running, so start it in the background,
+and stop a World you started with `up` first (`down` keeps its state).
+
+## Share it on a platform
+
+A team shares Worlds on a Volter World platform (Volter's cloud, or one the team runs):
+
+```bash
+volter login <platform url>                     # prints a link and a code: the PERSON approves it in their browser
+volter remote add origin <org>/<world> --create  # links this World to that one, making it from world.json's vendors
+volter world changeset -m "<what and why>"       # the unpushed changes, as one reviewable changeset
+volter world push                                # sends it; the platform answers with receipts
+```
+
+You cannot approve a sign-in; hand the link and code to the person and wait. Ask the person for
+`<org>/<world>` rather than guessing it. Keys for apps and CI are made on the platform.
+
+## The MCP tools
+
+`volter mcp` serves the same verbs to an agent: `world_init`, `world_up`, `world_run`,
+`world_status`, `world_log`, `world_diff`, `world_view`, `world_branch`, `world_checkout`,
+`world_reset`, `world_down`, `platform_login`, `platform_whoami`, `remote_link`, `world_changeset` and
+`world_push`,
+each taking the app's folder as `dir`. They run the `volter` command itself, so their answers and
+refusals are the command's: act on a refusal's reason rather than working around it.
+
+## Run through the World
+
+Run apps and tests inside a World, never bare. For a repo with `.volter/world.json`:
+
+```bash
+volter world up
+volter world run -- npm test
+volter world down
+```
+
+`volter world up` resumes a stopped branch's state and seeds a fresh branch.
+`volter world run` runs a command inside that World; it does not own teardown.
+`reset` discards the current branch's state and reloads default data. `down` retains state;
+`down --purge` removes it after verified teardown, unless another local branch references it.
+Fresh boot, reset and prune also refuse to remove a referenced parent; stop compute with
+ordinary `down`, or remove dependent branches first.
+
+For existing operator configs, use the explicit name and root:
+
+```bash
+volter-world up <config> --root <twins-checkout> --env-file <live-env> --owner <task>
+# From the app repo so the seed's SDK dependencies resolve:
+volter-world attach <world> --root <twins-checkout> -- bun <seed-entry>
+volter-world attach <world> --root <twins-checkout> -- <command...>
+volter-world down <world> --root <twins-checkout>
+```
+
+The lower-level `volter-world up` starts a fresh instance: reseed after each successful boot.
+Do not confuse this with the resumable `volter world up` API. The env file passed to `up` is the
+live env; an init-generated preview is not. Use `url` and `app-url` to discover endpoints rather
+than parsing env files. Registered commands carry `VOLTER_WORLD`.
+
+For a task that owns the entire lifecycle, use:
+
+```bash
+volter-world run <config> --root <twins-checkout> --env-file <live-env> --owner <task> -- <command...>
+```
+
+This operator command owns boot, its command and teardown. `--keep` makes it persistent.
+Its cleanup process handles caller loss if it survives; uncertain teardown retains diagnostics
+and lifecycle evidence. Stop registered consumers before explicitly bringing their World down.
+
+## State and behavior
+
+Create stored data through the vendor's own API using the real SDK pointed at the twin.
+Identity comes from credentials in the vendor's manner; inspect `GET /twin` for the twin's
+identity and time rules. Use `clock set` and `clock advance` for backdated history. Without a
+frozen World clock, the runtime uses wall time.
+
+Author judgment, stateless lookups and faults in `handlers/<vendor>.json` in the World config
+directory (typically `.volter/handlers/`). These are ordered, first-match scenario rules.
+Edit the file and restart to load changes; a handler must never fake success for a stored
+mutation. `GET /twin/scenario` shows handler matches and misses; `tail` records misses to author.
+Model twins serve deterministic scripts or labeled stubs, so verify calls and state changes,
+not the quality of prose from an unconfigured model.
+
+Local default data is synthetic. A World cloned or refreshed from a real root may contain real
+records; treat its files accordingly. Fake opaque keys are intentional. If an SDK parses a key
+locally, use `fake-env` to produce a structurally valid throwaway credential; never substitute
+real credentials to get a local test past validation.
+
+## Capacity and ownership
+
+Use `resources` to inspect actual filesystem capacity and registered lifecycle owners/consumers.
+Runtime v3 does not reserve speculative per-World memory or storage. Configure supported limits
+in the execution backend; deprecated `resources` declarations are not enforced limits.
+On a storage failure, inspect the actual destination and backend error. Preview `prune` for
+eligible stopped instance files; it never stops a running World. Inspect ownership before apply.
+Unknown use remains unknown; age never proves safety. Preserve cleanup evidence and parent
+history. Never delete another actor's World, worktree, package cache or rate-budget ledger.
+Migrate an old installation only after verified teardown with its pinned runtime, then pin all
+entrypoints to the new version and resume retained state. Never run two runtime versions over
+one instance or erase legacy ownership records to make startup pass.
+
+Worlds own their declared infrastructure. Start, inspect and stop it through World commands;
+never operate its underlying process, container or database separately. Install locked repository
+dependencies from the normal registry/cache; use a registry twin only when registry behavior
+needs substitution. Build workspace packages when needed. Do not delete `node_modules` as a World repair.
+
+When booting an app, register its URL as the last step with `app-url --set <url>` (or `--detect`).
+An app declared as a World service supplies its own endpoint record. Consumers read `app-url`.
+An app that answers as its own production hostnames (`app.example.com`) records them with
+`app-url --host <name>`: inside the World they reach the app with their Host, `x-forwarded-host` and
+`x-forwarded-proto` (https when the caller used TLS).
+
+## Diagnose before changing the app
+
+1. Check whether the failing vendor belongs in this World before seeding or repairing its twin.
+   For app/test execution, check `VOLTER_WORLD` and the intended World environment.
+2. Run `doctor`, then `tail --no-follow`, and inspect the twin's `GET /twin` manifest.
+3. Run `covers <world> --repo <app>` for missing vendor coverage.
+4. Determine whether the failure belongs to the app, twin fidelity, scenario, routing or runtime.
+
+Sandbox mode refuses untwinned destinations in cooperating clients, including Node sockets a
+client opens around the injector. It does not constrain binaries or non-Node processes that
+ignore the injector/proxy; network isolation needs an enforced boundary.
+Do not disable routing to hide a coverage gap.
+
+Current packages are `@volter/world`, `@volter/world-core`, `@volter/world-runtime`,
+`@volter/world-access`, `@volter/world-attach` and `@volter/twin-<vendor>`. Use the CLI reference for commands instead of
+retired `volter-twin`, `plan` or `review` examples.

package/dist/skills/volter-world/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: volter-world
+description: Set up, run and diagnose an app inside a Volter World (twins of Stripe, Slack, GitHub, OpenAI and the other SaaS APIs it calls), share it on a Volter World platform, with explicit ownership and cleanup. Use when asked to set up Volter World, run an app or its tests against twins, look at what an app did at a vendor, branch or reset that state, or link a World to a team's platform.
+---
+
+# Operating a World
+
+Read [AGENTS.md](./AGENTS.md) before setting up, running or changing a World. It is the single
+operator instruction source shipped with this skill: setting a World up for an app, linking it
+to a platform, the `volter mcp` tools, and the lifecycle distinction between the product command
+`volter world` and the explicit operator command `volter-world`.
+
+The [documentation map](https://github.com/volter-ai/twin/blob/main/docs/README.md) links the
+canonical model, task guides and command reference. Do not maintain a second copy here.

package/dist/src/agent-prompt.d.ts

@@ -0,0 +1,10 @@
+export type AgentPromptOptions = {
+    /** A platform to share the World on: its address. */
+    platform?: string;
+    /** The World on that platform, `<org>/<world>`; without it, the agent asks. */
+    world?: string;
+    /** Phrase the steps for an agent that has `volter mcp`'s tools rather than a shell. */
+    tools?: boolean;
+};
+/** The prompt, as plain text a person copies. */
+export declare function agentPrompt(o?: AgentPromptOptions): string;

package/dist/src/agent-prompt.js

@@ -0,0 +1,23 @@
+// The prompt a person hands their coding agent to set Volter World up for their app (docs/contributing/architecture.md,
+// "The way in is the app's folder"): one text for every place it is offered (the landing page, the platform's Get
+// started, the dashboard's Connect, `volter mcp`'s get-started prompt). Pure, with no imports: browser bundles use it.
+/** The prompt, as plain text a person copies. */
+export function agentPrompt(o = {}) {
+    const cmd = (shell, tool) => (o.tools ? `${tool} (\`${shell}\`)` : `\`${shell}\``);
+    const steps = [
+        'Set up Volter World for this app, so its calls to Stripe, Slack, GitHub, OpenAI and the other services it uses go to local twins instead of the real APIs. The app keeps its real SDKs and code.',
+        '',
+        o.tools
+            ? '1. You have the Volter World tools (volter mcp). If the `volter` command is missing, install it: `npm install -g @volter/world`.'
+            : '1. Install the command and your agent tooling: `npm install -g @volter/world`, then `volter agents install --yes`.',
+        `2. In the app's folder, ${cmd('volter world init --install', 'world_init')}: it detects the vendors the app calls and installs their twins. Show me the vendors it detected and why, before keeping them.`,
+        `3. ${o.tools ? 'Start it with world_up' : 'Start it: `volter world up`'}, then run the tests inside it: ${cmd('volter world run -- <the test command>', 'world_run')}. Fix anything that fails because a call went to the real service.`,
+        `4. Tell me what the app did at each vendor (${cmd('volter world log', 'world_log')}), and give me the dashboard link (${o.tools ? 'world_view' : '`volter world view --no-open`, started in the background: it keeps running'}).`,
+    ];
+    if (o.platform) {
+        const target = o.world ?? '<org>/<world>';
+        steps.push(`5. Share it with my team on ${o.platform}: ${cmd(`volter login ${o.platform}`, 'platform_login')} gives a link and a code for me to approve in my browser. Once I have, link it with ${cmd(`volter remote add origin ${target} --create`, 'remote_link with create: true')}${o.world ? '' : ' (ask me for <org>/<world>)'}, then send what the app did: ${cmd('volter world changeset -m "<what and why>"', 'world_changeset')} and ${cmd('volter world push', 'world_push')}.`);
+    }
+    steps.push('', 'The guide: https://github.com/volter-ai/twin/blob/main/docs/guides/use-with-a-coding-agent.md');
+    return steps.join('\n');
+}

package/dist/src/agents.d.ts

@@ -0,0 +1,15 @@
+export type Agent = 'claude' | 'cursor' | 'vscode' | 'codex';
+export declare const AGENTS: readonly Agent[];
+/** The skill's folder: the one shipped in the package (skills/, copied in at pack time), else this checkout's. */
+export declare function skillSource(): string;
+/** How an agent starts the server: `volter mcp` when the command is on PATH, else this installation by its path. */
+export declare function mcpCommand(): {
+    command: string;
+    args: string[];
+};
+/** The agents this machine (and this project) shows signs of. */
+export declare function detectAgents(project: string): Agent[];
+/** Install into each agent: what changed, one line each. */
+export declare function installAgents(agents: Agent[], project: string): string[];
+/** `volter agents install [--claude] [--cursor] [--vscode] [--codex] [--yes]`. */
+export declare function agentsCommand(verb: string | undefined, args: string[], out: (s: string) => void): Promise<void>;

package/dist/src/agents.js

@@ -0,0 +1,206 @@
+// `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 const AGENTS = ['claude', 'cursor', 'vscode', 'codex'];
+const NAMES = { claude: 'Claude Code', cursor: 'Cursor', vscode: 'VS Code', codex: 'Codex' };
+/** A command on PATH (with Windows' extensions), or null. */
+function which(cmd) {
+    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() {
+    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() {
+    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) {
+    const home = homedir();
+    const found = [];
+    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) {
+    const within = (base) => { 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) => {
+    if (!existsSync(path))
+        return {};
+    const raw = readFileSync(path, 'utf8').trim();
+    if (!raw)
+        return {};
+    try {
+        const v = JSON.parse(raw);
+        return v && typeof v === 'object' && !Array.isArray(v) ? v : {};
+    }
+    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, text) => { mkdirSync(dirname(path), { recursive: true }); const tmp = `${path}.volter-${process.pid}.tmp`; writeFileSync(tmp, text); renameSync(tmp, path); };
+const writeJson = (path, value) => 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, args) => 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, b) => 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, key, entry) {
+    const doc = readJson(path);
+    const servers = (doc[key] && typeof doc[key] === 'object' ? doc[key] : {});
+    const mine = servers.volter;
+    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) {
+    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) {
+    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, entry) {
+    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) => 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) {
+    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, project) {
+    const entry = mcpCommand();
+    const home = homedir();
+    const lines = [];
+    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, args, out) {
+    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((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/dist/src/cli.d.ts

@@ -1,2 +1,2 @@
 #!/usr/bin/env node
-export declare const HELP = "volter \u2014 run your app against a world of twins\n\nworld  \u2014 the twins your app needs, running together (the world of the current directory)\n  volter world init [--name <world>] [--allow-unknown]   detect the app's vendors, write .volter/world.json\n  volter world up [--sandbox] [--no-seed]                start the twins on this branch (loads the default data the first time)\n  volter world run [--verbose] -- <command...>           run the app or its tests inside the world\n  volter world activate                                  eval \"$(volter world activate)\": vendor CLIs and curl in this shell reach the twins\n  volter world shell                                     a subshell with the world active\n  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\n  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)\n  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\n  volter world status                                    world, branch, origin, unpushed changes, what is running\n  volter world log [--receipts] [--json]                 every write the app made; --receipts adds each change's receipt\n  volter world diff [--json]                             what changed since the default data (or the last mark)\n  volter world seed                                      load the default data\n  volter world reset                                     back to the default data\n  volter world down [--purge]                            stop the twins (--purge forgets this branch's state)\n  volter world branch [<name>]                           list branches, or make one from here and check it out\n  volter world checkout <name>                           switch branches\n  volter world replay <changeset> --into <branch>        feed a changeset's changes into another branch's twins\n  volter world clock show | set <iso> | advance <N s|m|h|d>   the world's clock: set, not observed\n  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)\n  volter world fetch                                     what the remote observed since the last fetch\n  volter world origin                                    where this world clones from and pushes to\n  volter world changeset [<name>] -m \"<message>\"         cut the unpushed changes into a reviewable changeset\n  volter world pull [--token <token>]                    fetch, then move this branch onto what came in (git's pull)\n  volter world push [<name>] [--token <token>] [--force] push to the remote, which deploys and answers with receipts\n  volter world rebase [<changeset>]                      rebase this branch onto its moved base, or a changeset onto the moved mirror\n  volter world verify <changeset>                        run the world's checks over a changeset and record the result\n  volter world approve <changeset> --as <principal>      sign a changeset's current hash\n  volter world deploy [<changeset>]                      perform landed changes against each twin's root, by its policy\n\ntwin   \u2014 one twin: in this world, or on its own\n  volter twin <vendor>                                   the twin's URL, root, deploy policy, whether a credential is sealed\n  volter twin <vendor> root <url> [--deploy auto|gated|hold] [--scope <path>]   the vendor's real account behind this twin (--none clears it)\n  volter twin <vendor> credential                        seal a credential read from stdin beside the world; never readable back\n  volter twin <vendor> refresh                           observe the root now\n  volter twin <vendor> serve [--port <p>] [--read-only]  serve the twin; your SDK talks to it at http://127.0.0.1:<p>\n  volter twin <vendor> mirror [--port <p>]               the twin's UI mirror\n  volter twin <vendor> conformance                       check the twin against the vendor's spec\n\nremote \u2014 the worlds this one pushes to and fetches from, by name\n  volter login <platform url> --token <personal token>  sign the CLI into the hosted platform (a personal token from the console)\n  volter remote add <name> <url|path|org/world> [--token <token>]  name a remote; org/world resolves through the platform you logged into\n  volter remote remove <name>                            forget it\n  volter remote list                                     every remote, with its URL and whether a token is stored\n  (the hosting product's serve answers here for one release: volter remote serve)\n\n  --world <dir>    the world root, when the cwd is not inside it\n  --branch <name>  act on that branch instead of the checked-out one\n  --json           machine-readable output where offered\n";
+export declare const HELP = "volter \u2014 run your app against a world of twins\n\nworld  \u2014 the twins your app needs, running together (the world of the current directory)\n  volter world init [--install] [--name <world>] [--allow-unknown]   detect the app's vendors (installing their twins when none are), write .volter/world.json\n  volter world up [--sandbox] [--no-seed]                start the twins on this branch (loads the default data the first time)\n  volter world run [--verbose] -- <command...>           run the app or its tests inside the world\n  volter world activate                                  eval \"$(volter world activate)\": vendor CLIs and curl in this shell reach the twins\n  volter world shell                                     a subshell with the world active\n  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\n  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)\n  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)\n  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\n  volter world status                                    world, branch, origin, unpushed changes, what is running\n  volter world log [--receipts] [--json]                 every write the app made; --receipts adds each change's receipt\n  volter world diff [--json]                             what changed since the default data (or the last mark)\n  volter world seed                                      load the default data\n  volter world reset                                     back to the default data\n  volter world down [--purge]                            stop the twins (--purge forgets this branch's state)\n  volter world branch [<name>]                           list branches, or make one from here and check it out\n  volter world checkout <name>                           switch branches\n  volter world replay <changeset> --into <branch>        feed a changeset's changes into another branch's twins\n  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\n  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)\n  volter world fetch                                     what the remote observed since the last fetch\n  volter world origin                                    where this world clones from and pushes to\n  volter world changeset [<name>] -m \"<message>\"         cut the unpushed changes into a reviewable changeset\n  volter world pull [--token <token>]                    fetch, then move this branch onto what came in (git's pull)\n  volter world push [<name>] [--token <token>] [--force] push to the remote, which deploys and answers with receipts\n  volter world rebase [<changeset>]                      rebase this branch onto its moved base, or a changeset onto the moved mirror\n  volter world verify <changeset>                        run the world's checks over a changeset and record the result\n  volter world approve <changeset> --as <principal>      sign a changeset's current hash\n  volter world deploy [<changeset>]                      perform landed changes against each twin's root, by its policy\n\ntwin   \u2014 one twin: in this world, or on its own\n  volter twin <vendor>                                   the twin's URL, root, deploy policy, whether a credential is sealed\n  volter twin <vendor> root <url> [--deploy auto|gated|hold] [--scope <path>]   the vendor's real account behind this twin (--none clears it)\n  volter twin <vendor> credential                        seal a credential read from stdin beside the world; never readable back\n  volter twin <vendor> refresh                           observe the root now\n  volter twin <vendor> serve [--port <p>] [--read-only]  serve the twin; your SDK talks to it at http://127.0.0.1:<p>\n  volter twin <vendor> mirror [--port <p>]               the twin's UI mirror\n  volter twin <vendor> conformance                       check the twin against the vendor's spec\n\nagents \u2014 your coding agent, driving the same verbs\n  volter agents install [--claude] [--cursor] [--vscode] [--codex] [--yes]   put the volter-world skill and the MCP server into the agents found here\n  volter mcp                                             the MCP server (stdio) an agent starts: the verbs above as tools\n\nremote \u2014 the worlds this one pushes to and fetches from, by name\n  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)\n  volter whoami                                          the platform the CLI is signed into, as whom, and its orgs\n  volter logout                                          revoke the CLI's token at the platform and forget it here\n  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\n  volter open [<org>/<world>] [--no-open]                a World's dashboard: a hosted one through the platform, else this world's (as view)\n  volter completion bash|zsh|fish|powershell             print a completion script for your shell\n  volter remote remove <name>                            forget it\n  volter remote list                                     every remote, with its URL and whether a token is stored\n  (the hosting product's serve answers here for one release: volter remote serve)\n\n  --world <dir>    the world root, when the cwd is not inside it\n  --branch <name>  act on that branch instead of the checked-out one\n  --json           machine-readable output where offered\n";