@volter/world 2.0.1 → 2.0.3

package/dist/src/mcp.js

@@ -0,0 +1,203 @@
+// `volter mcp` (docs/contributing/architecture.md, "The way in is the app's folder"): an MCP server over stdio whose tools
+// are the `volter` command's own verbs. A tool that reads (status, log, diff, branches) asks the SDK; a tool that acts runs
+// the command itself, as a child, so there is one implementation of each verb and an agent gets what a person would.
+// Locally a World is reached with its own token (the command finds it); the platform with the person's token from
+// `volter login`, which only the person can approve, in their browser.
+import { spawn, spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { resolve } from 'node:path';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { World } from "./world.js";
+import { agentPrompt } from "./agent-prompt.js";
+/** This command's own entry, beside this module (src/cli.ts in a checkout, dist/src/cli.js when published). */
+const CLI = fileURLToPath(new URL(`./cli${import.meta.url.endsWith('.ts') ? '.ts' : '.js'}`, import.meta.url));
+const MAX_OUTPUT = 20_000;
+/** Run `volter <args>` in `dir` to its end (or its timeout), its stdout and stderr together, the tail kept. */
+function volter(args, dir, timeoutSeconds = 600) {
+    return new Promise((done) => {
+        const child = spawn(process.execPath, [CLI, ...args], { cwd: dir, windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'], env: process.env });
+        let output = '';
+        const take = (d) => { output += d.toString(); if (output.length > MAX_OUTPUT * 2)
+            output = output.slice(-MAX_OUTPUT); };
+        child.stdout.on('data', take);
+        child.stderr.on('data', take);
+        const timer = setTimeout(() => { output += `\n(stopped after ${timeoutSeconds}s)`; child.kill(); }, timeoutSeconds * 1000);
+        child.on('error', (e) => { clearTimeout(timer); done({ code: 1, output: `${output}${e.message}` }); });
+        child.on('close', (code) => { clearTimeout(timer); done({ code: code ?? 1, output: output.length > MAX_OUTPUT ? `…${output.slice(-MAX_OUTPUT)}` : output }); });
+    });
+}
+/** A command that keeps running (the World's view, a sign-in waiting for approval): started once, answered as soon as
+ *  its first lines say what the agent needs, left running for as long as this server runs. */
+const background = new Map();
+function startBackground(key, args, dir, ready, seconds = 60) {
+    background.get(key)?.kill();
+    background.delete(key);
+    return new Promise((done) => {
+        const child = spawn(process.execPath, [CLI, ...args], { cwd: dir, windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'], env: process.env });
+        background.set(key, child);
+        let output = '';
+        let answered = false;
+        const answer = (code) => { if (!answered) {
+            answered = true;
+            clearTimeout(timer);
+            done({ code, output });
+        } };
+        const take = (d) => { output += d.toString(); if (ready.test(output))
+            answer(0); };
+        child.stdout.on('data', take);
+        child.stderr.on('data', take);
+        child.on('error', (e) => { output += e.message; answer(1); });
+        child.on('close', (code) => { background.delete(key); answer(code ?? 1); });
+        const timer = setTimeout(() => answer(0), seconds * 1000);
+    });
+}
+/** Everything this server left running, ended: a World under a dashboard is brought down through its own command first
+ *  (its state kept, its teardown recorded), then the command itself. */
+function stopAll() {
+    for (const [key, child] of background) {
+        if (key.startsWith('view:'))
+            spawnSync(process.execPath, [CLI, 'world', 'down'], { cwd: key.slice('view:'.length), windowsHide: true, stdio: 'ignore', timeout: 60_000 });
+        child.kill();
+    }
+    background.clear();
+}
+for (const signal of ['SIGINT', 'SIGTERM'])
+    process.on(signal, () => { stopAll(); process.exit(0); });
+process.on('exit', stopAll);
+const text = (s, isError = false) => ({ content: [{ type: 'text', text: s.trim() || '(no output)' }], ...(isError ? { isError: true } : {}) });
+const ran = (r) => text(r.output, r.code !== 0);
+const asJson = (v) => text(JSON.stringify(v, null, 2));
+const fail = (e) => text(e instanceof Error ? e.message : String(e), true);
+const INSTRUCTIONS = `Volter World runs an app against twins of the SaaS APIs it calls (Stripe, Slack, GitHub, OpenAI and about a hundred more): the app keeps its real SDKs and code, and every write lands in a World that can be branched, reset and looked at on each vendor's own screens.
+
+Work in the app's folder (each tool takes "dir", defaulting to where this server was started).
+- Set up: world_init detects the vendors from the app's manifests and env names; show the person the list before keeping it. Then world_up.
+- Run the app or its tests inside the World with world_run (never bare against the real vendors).
+- Look: world_log and world_diff say what the app changed at each vendor; world_view starts the dashboard and returns its link for the person.
+- Branch and reset like a database: world_branch, world_checkout, world_reset.
+- Share with a team: platform_login returns a link and a code the PERSON must approve in their browser (you cannot approve it); after they do, remote_link links this World to <org>/<world> on the platform (create: true makes it there from this World's vendors); world_changeset cuts the changes with a message, and world_push sends them.
+The guide: https://github.com/volter-ai/twin/blob/main/docs/guides/use-with-a-coding-agent.md`;
+export async function serveMcp(version) {
+    const server = new McpServer({ name: 'volter', title: 'Volter World', version }, { instructions: INSTRUCTIONS });
+    const here = (dir) => resolve(dir ?? process.cwd());
+    const dirArg = { dir: z.string().optional().describe("The app's folder (the World's root). Defaults to where this server was started.") };
+    server.registerTool('world_status', {
+        title: 'World status', description: 'The World of the app folder: its branch, whether it is running, each twin\'s URL, its origin (the remote it pushes to) and unpushed changes.',
+        inputSchema: dirArg, annotations: { readOnlyHint: true },
+    }, async ({ dir }) => { try {
+        return asJson(World.open({ root: here(dir) }).status());
+    }
+    catch (e) {
+        return fail(e);
+    } });
+    server.registerTool('world_init', {
+        title: 'Set up a World for the app', description: "Detect the vendors the app calls (from its package manifests and env var names), install their twins when none are installed yet, and write .volter/world.json beside the code. Show the person the detected vendors; pass allowUnknown to keep going when some have no twin yet.",
+        inputSchema: { ...dirArg, name: z.string().optional().describe('The World\'s name (defaults to the folder\'s).'), allowUnknown: z.boolean().optional(), force: z.boolean().optional().describe('Overwrite an existing .volter/world.json.') },
+    }, async ({ dir, name, allowUnknown, force }) => ran(await volter(['world', 'init', '--install', ...(name ? ['--name', name] : []), ...(allowUnknown ? ['--allow-unknown'] : []), ...(force ? ['--force'] : [])], here(dir))));
+    server.registerTool('world_up', {
+        title: 'Start the World', description: 'Start the twins on the current branch. A fresh branch loads its default data (the story); a stopped one resumes where it was.',
+        inputSchema: { ...dirArg, seed: z.boolean().optional().describe('Load the default data on a fresh branch (default true).') },
+    }, async ({ dir, seed }) => ran(await volter(['world', 'up', ...(seed === false ? ['--no-seed'] : [])], here(dir))));
+    server.registerTool('world_run', {
+        title: 'Run a command in the World', description: "Run the app or its tests inside the World: the vendors' hosts go to their twins, so the real SDKs work unchanged. Returns the command's exit code and the tail of its output.",
+        inputSchema: { ...dirArg, command: z.array(z.string()).min(1).describe('The command and its arguments, e.g. ["npm", "test"].'), timeoutSeconds: z.number().int().positive().max(3600).optional() },
+    }, async ({ dir, command, timeoutSeconds }) => { const r = await volter(['world', 'run', '--', ...command], here(dir), timeoutSeconds ?? 600); return text(`exit ${r.code}\n${r.output}`, r.code !== 0); });
+    server.registerTool('world_down', {
+        title: 'Stop the World', description: 'Stop the twins. Their state is kept for the next world_up unless purge is true.',
+        inputSchema: { ...dirArg, purge: z.boolean().optional() }, annotations: { destructiveHint: true },
+    }, async ({ dir, purge }) => ran(await volter(['world', 'down', ...(purge ? ['--purge'] : [])], here(dir))));
+    server.registerTool('world_view', {
+        title: 'Open the dashboard', description: "Run the World with its dashboard on this machine (each vendor's own screens, the calls, the changes, the branches) and return its link for the person. The dashboard runs the World itself: a World already started with world_up is stopped first (its state is kept) and comes back under the dashboard. It keeps running while this server does; world_run works against it meanwhile.",
+        inputSchema: dirArg,
+    }, async ({ dir }) => {
+        const root = here(dir);
+        let before = '';
+        try {
+            const s = World.open({ root }).status();
+            if (s.running && !s.served) {
+                const down = await volter(['world', 'down'], root);
+                if (down.code !== 0)
+                    return ran(down);
+                before = `${down.output.trim()} (state kept; the dashboard runs it now)\n`;
+            }
+        }
+        catch (e) {
+            return fail(e);
+        }
+        const r = await startBackground(`view:${root}`, ['world', 'view', '--no-open'], root, /console\s+\S+/);
+        return text(`${before}${r.output}`, r.code !== 0);
+    });
+    server.registerTool('world_log', {
+        title: 'What the app changed', description: 'Every write the app made in this World, newest last: vendor, operation and subject.',
+        inputSchema: { ...dirArg, limit: z.number().int().positive().max(1000).optional().describe('The newest this many (default 50).') }, annotations: { readOnlyHint: true },
+    }, async ({ dir, limit }) => { try {
+        const rows = World.open({ root: here(dir) }).log();
+        return asJson(rows.slice(-(limit ?? 50)).map((r) => ({ vendor: r.service, operation: r.operation ?? r.op, subject: r.subject, ...(r.receipt ? { receipt: r.receipt } : {}) })));
+    }
+    catch (e) {
+        return fail(e);
+    } });
+    server.registerTool('world_diff', {
+        title: 'Changes since the default data', description: 'How many changes each vendor has since the default data (or the last mark).',
+        inputSchema: dirArg, annotations: { readOnlyHint: true },
+    }, async ({ dir }) => { try {
+        const d = World.open({ root: here(dir) }).diff();
+        return asJson({ base: d.base, vendors: d.vendors });
+    }
+    catch (e) {
+        return fail(e);
+    } });
+    server.registerTool('world_branch', {
+        title: 'List or make branches', description: 'Without a name, the branches (the checked-out one first). With a name, make a branch from here and check it out, like a database branch: try something, then check out the old one or reset.',
+        inputSchema: { ...dirArg, name: z.string().optional() },
+    }, async ({ dir, name }) => {
+        if (name)
+            return ran(await volter(['world', 'branch', name], here(dir)));
+        try {
+            const w = World.open({ root: here(dir) });
+            return asJson({ current: w.name, branches: w.branches() });
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool('world_checkout', {
+        title: 'Switch branch', description: 'Check out another branch of the World.',
+        inputSchema: { ...dirArg, name: z.string() },
+    }, async ({ dir, name }) => ran(await volter(['world', 'checkout', name], here(dir))));
+    server.registerTool('world_reset', {
+        title: 'Back to the default data', description: "Discard the current branch's changes and load its default data again.",
+        inputSchema: dirArg, annotations: { destructiveHint: true },
+    }, async ({ dir }) => ran(await volter(['world', 'reset'], here(dir))));
+    server.registerTool('platform_login', {
+        title: 'Sign in to a platform', description: 'Start signing this machine\'s `volter` command in to a Volter World platform. Returns a link and a code: give both to the PERSON, who approves it in their browser (you cannot). The sign-in completes by itself once they do; check with platform_whoami.',
+        inputSchema: { url: z.string().url().describe("The platform's address (https://…), as the person gave it") },
+    }, async ({ url }) => ran(await startBackground('login', ['login', url, '--no-open'], process.cwd(), /code\s+[A-Z]{4}-[A-Z]{4}/, 30)));
+    server.registerTool('platform_whoami', {
+        title: 'Who the command is signed in as', description: 'The platform this machine\'s `volter` command is signed in to, as whom, and their orgs.',
+        inputSchema: {}, annotations: { readOnlyHint: true },
+    }, async () => ran(await volter(['whoami'], process.cwd())));
+    server.registerTool('remote_link', {
+        title: 'Link the World to the platform', description: "Link this World to <org>/<world> on the platform the command is signed in to, as the remote it pushes to. create: true makes that World on the platform from this World's vendors when it does not exist.",
+        inputSchema: { ...dirArg, target: z.string().regex(/^[a-z0-9][a-z0-9-]*\/[a-z0-9][a-z0-9-]*$/).describe('<org>/<world>'), name: z.string().optional().describe('The remote\'s name (default origin).'), create: z.boolean().optional() },
+    }, async ({ dir, target, name, create }) => ran(await volter(['remote', 'add', name ?? 'origin', target, ...(create ? ['--create'] : [])], here(dir))));
+    server.registerTool('world_changeset', {
+        title: 'Cut a changeset', description: "Cut the World's unpushed changes into a reviewable changeset, with a message saying what and why; world_push sends it.",
+        inputSchema: { ...dirArg, message: z.string().min(1).describe('What the changes are and why.'), name: z.string().optional() },
+    }, async ({ dir, message, name }) => ran(await volter(['world', 'changeset', ...(name ? [name] : []), '-m', message], here(dir))));
+    server.registerTool('world_push', {
+        title: 'Push to the remote', description: "Send this World's unpushed changes to its remote (the platform's World after remote_link); the remote answers with a receipt for each change.",
+        inputSchema: { ...dirArg, changeset: z.string().optional().describe('Push one changeset by name; default all unpushed.') },
+    }, async ({ dir, changeset }) => ran(await volter(['world', 'push', ...(changeset ? [changeset] : [])], here(dir))));
+    server.registerPrompt('get-started', {
+        title: 'Set up Volter World for this app', description: 'Walks through setting up a World for the app in this folder, running its tests in it, and optionally sharing it on a platform.',
+        argsSchema: { platform: z.string().optional().describe("A platform to share the World on: its address"), world: z.string().optional().describe('<org>/<world> on that platform') },
+    }, ({ platform, world }) => ({ messages: [{ role: 'user', content: { type: 'text', text: agentPrompt({ ...(platform ? { platform } : {}), ...(world ? { world } : {}), tools: true }) } }] }));
+    // the client closing the connection (its stdin ends) ends this server, and the commands it left running with it
+    const stop = () => { stopAll(); process.exit(0); };
+    server.server.onclose = stop;
+    process.stdin.on('end', stop);
+    await server.connect(new StdioServerTransport());
+}

package/dist/src/update-notice.d.ts

@@ -0,0 +1,7 @@
+/** This package's version, read from its own package.json. */
+export declare function currentVersion(): string;
+/** Whether `a` is a newer release than `b` (major.minor.patch; a prerelease is not offered). */
+export declare function newer(a: string, b: string): boolean;
+/** Start the day's check if one is due, while the command runs; the returned function, called when the command is
+ *  done, waits a moment at most for it and prints the notice when there is one. Off, it does nothing and asks nothing. */
+export declare function startUpdateCheck(args: string[], env?: NodeJS.ProcessEnv): () => Promise<void>;

package/dist/src/update-notice.js

@@ -0,0 +1,60 @@
+// The update notice (docs/contributing/architecture.md, "The way in is the app's folder"): at most once a day the command
+// asks the npm registry for @volter/world's latest version, while it does its own work, and says in one line on stderr
+// when a newer one exists. Never in CI, never for --json, never when the person opted out (VOLTER_NO_UPDATE_NOTIFIER=1):
+// then nothing is asked at all. The answer is kept beside the credentials, so a day's commands ask once.
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { credentialsPath } from "./credentials.js";
+const DAY = 86_400_000;
+const REGISTRY = 'https://registry.npmjs.org/@volter/world/latest';
+/** This package's version, read from its own package.json. */
+export function currentVersion() {
+    try {
+        return JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version ?? '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+}
+/** Whether `a` is a newer release than `b` (major.minor.patch; a prerelease is not offered). */
+export function newer(a, b) {
+    const parse = (v) => (/^\d+\.\d+\.\d+$/.test(v) ? v.split('.').map(Number) : null);
+    const x = parse(a);
+    const y = parse(b);
+    if (!x || !y)
+        return false;
+    for (let i = 0; i < 3; i++)
+        if (x[i] !== y[i])
+            return x[i] > y[i];
+    return false;
+}
+/** Start the day's check if one is due, while the command runs; the returned function, called when the command is
+ *  done, waits a moment at most for it and prints the notice when there is one. Off, it does nothing and asks nothing. */
+export function startUpdateCheck(args, env = process.env) {
+    if (env.VOLTER_NO_UPDATE_NOTIFIER || env.CI || args.includes('--json') || !process.stderr.isTTY)
+        return async () => undefined;
+    const path = join(dirname(credentialsPath()), 'update-check.json');
+    let kept = null;
+    try {
+        if (existsSync(path))
+            kept = JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        kept = null;
+    }
+    const due = !kept || Date.now() - Date.parse(kept.checkedAt) > DAY;
+    const check = due
+        ? fetch(REGISTRY, { signal: AbortSignal.timeout(1500) }).then(async (r) => (r.ok ? (await r.json()).version ?? null : null)).catch(() => null)
+            .then((latest) => { try {
+            mkdirSync(dirname(path), { recursive: true });
+            writeFileSync(path, `${JSON.stringify({ checkedAt: new Date().toISOString(), latest })}\n`);
+        }
+        catch { /* a read-only home only loses the cache */ } return latest; })
+        : Promise.resolve(kept?.latest ?? null);
+    return async () => {
+        const latest = await Promise.race([check, new Promise((r) => setTimeout(() => r(null), 800))]);
+        const here = currentVersion();
+        if (latest && newer(latest, here))
+            process.stderr.write(`\nvolter ${latest} is out (you have ${here}): npm install -g @volter/world\n`);
+    };
+}

package/dist/src/world.d.ts

@@ -1,5 +1,5 @@
 import { rebaseChangeset, worldBootMarker, type Changeset, type LedgerDelta, type TwinAction, type WorldMarker, type ApplyReceipt, applyTwinWrite, type TwinResource } from '@volter/world-core';
-import { approveWorldChangeset, createWorldChangeset, downWorld, fetchFromOrigin, pushWorldChangeset, rebaseWorldChangeset, replayWorldChangeset, resetWorld, seedWorld, statusWorldChangeset, verifyWorldChangeset, type ServedWorld, type DeployTwinOutcome, type ChangesetLocation, type InitOptions, type InitResult, type WorldInstance } from '@volter/world-runtime';
+import { approveWorldChangeset, createWorldChangeset, downWorld, fetchFromOrigin, pushWorldChangeset, rebaseWorldChangeset, replayWorldChangeset, resetWorld, seedWorld, statusWorldChangeset, verifyWorldChangeset, type ServedWorld, type ViewConsole, type WorldView, type DeployTwinOutcome, type ChangesetLocation, type InitOptions, type InitResult, type WorldInstance } from '@volter/world-runtime';
 import { rebaseBranch, type Receipt, type RootConfig } from '@volter/world-core';
 export type WorldRef = {
     name?: string;
@@ -198,6 +198,16 @@ export declare class World {
             console: string | null;
         }) => void;
     }): Promise<ServedWorld>;
+    /** `volter world view`: this World, its mirrors, its branches and the console on one origin (docs/contributing/architecture.md, "Viewing a World"). */
+    view(opts?: {
+        port?: number;
+        host?: string;
+        console?: ViewConsole;
+        announce?: (line: string) => void;
+        origins?: boolean;
+    }): Promise<WorldView>;
+    /** The vendors this world has a twin of, as world.json names them (a twin service's package, else its id). */
+    vendors(): string[];
     /** The remotes named in world.json (`volter remote add`), name → url or path. */
     remotes(): Record<string, string>;
     /** Name a remote; `origin` is the one fetch and push use by default. A token given is remembered for it. */

package/dist/src/world.js

@@ -5,7 +5,7 @@
 import { rebaseChangeset, worldBootMarker, listActions, isTwinBookkeeping, pushablePendingActions, pendingActions, applyTwinWrite, twinResources } from '@volter/world-core';
 import { spawnSync } from 'node:child_process';
 import clockForm from '@volter/world-core/world-clock';
-import { activateScript, approveWorldChangeset, branchWorld, clockFile, checkoutWorld, createWorldChangeset, diffWorld, downWorld, fetchFromOrigin, findWorldChangeset, initWorld, listWorldChangesets, listWorldMarks, listWorlds, markWorld, pushWorldChangeset, rebaseWorldChangeset, replayWorldChangeset, resetWorld, runWithWorldEnv, seedWorld, shellWorld, statusWorld, statusWorldChangeset, upWorld, verifyWorldChangeset, worldLedgers, worldOrigin, deployWorld, loadWorldConfig, writeWorldConfig, readServeRecord, refreshTwin, serveWorld, findInstalledPackage, rootForControlRoot, sealTwinCredential, sealedCredentialInfo, setTwinRoot, credentialPayloadFrom, materializeRoots } from '@volter/world-runtime';
+import { activateScript, approveWorldChangeset, branchWorld, clockFile, checkoutWorld, createWorldChangeset, diffWorld, downWorld, fetchFromOrigin, findWorldChangeset, initWorld, listWorldChangesets, listWorldMarks, listWorlds, markWorld, pushWorldChangeset, rebaseWorldChangeset, replayWorldChangeset, resetWorld, runWithWorldEnv, seedWorld, shellWorld, statusWorld, statusWorldChangeset, upWorld, verifyWorldChangeset, worldLedgers, worldOrigin, deployWorld, loadWorldConfig, writeWorldConfig, readServeRecord, refreshTwin, serveWorld, serveWorldView, findInstalledPackage, rootForControlRoot, sealTwinCredential, sealedCredentialInfo, setTwinRoot, credentialPayloadFrom, materializeRoots } from '@volter/world-runtime';
 import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { requireToken, storeToken } from "./credentials.js";
@@ -94,7 +94,7 @@ export class World {
         if (opts.install !== false && !twins.every((t) => findInstalledPackage(dir, `@volter/twin-${t}`))) {
             // the runtime's own installer: bun under Bun, npm under Node — never assumed
             const cmd = typeof Bun !== 'undefined' ? ['bun', 'add', '-d'] : ['npm', 'install', '--save-dev'];
-            const r = spawnSync(cmd[0], [...cmd.slice(1), ...twins.map((t) => `@volter/twin-${t}`)], { cwd: dir, stdio: 'inherit' });
+            const r = spawnSync(cmd[0], [...cmd.slice(1), ...twins.map((t) => `@volter/twin-${t}`)], { windowsHide: true, cwd: dir, stdio: 'inherit' });
             if (r.status !== 0)
                 throw new Error(`installing the twins failed (${cmd.join(' ')} exited ${r.status})`);
         }
@@ -357,7 +357,14 @@ export class World {
     // ── serving ─────────────────────────────────────────────────────────────────────────────
     /** Serve this world on a port under `/<org>/<world>/`; returns when listening. */
     serve(opts = {}) { return serveWorld(this.name, { root: this.root, ...opts }); }
+    /** `volter world view`: this World, its mirrors, its branches and the console on one origin (docs/contributing/architecture.md, "Viewing a World"). */
+    view(opts = {}) { return serveWorldView(this.name, { root: this.root, ...opts }); }
     // ── remotes ─────────────────────────────────────────────────────────────────────────────
+    /** The vendors this world has a twin of, as world.json names them (a twin service's package, else its id). */
+    vendors() {
+        const { config } = loadWorldConfig(this.configRef(), this.root);
+        return [...new Set(config.services.filter((s) => (s.type ?? 'twin') === 'twin').map((s) => /^@volter\/twin-(.+)$/.exec(s.package ?? '')?.[1] ?? s.id))].sort();
+    }
     /** The remotes named in world.json (`volter remote add`), name → url or path. */
     remotes() { return { ...(loadWorldConfig(this.configRef(), this.root).config.remotes ?? {}) }; }
     /** Name a remote; `origin` is the one fetch and push use by default. A token given is remembered for it. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/world",
-  "version": "2.0.1",
+  "version": "2.0.3",
   "description": "Run your app against a world of twins. `World` and `Repo` — one method per verb: init, up, run, log, diff, reset, branch, checkout, clone, fetch, changeset, push — and the `volter` command, one client of them.",
   "keywords": [
     "volter",
@@ -25,18 +25,32 @@
   "main": "dist/src/index.js",
   "files": [
     "src",
-    "dist"
+    "dist",
+    "skills"
   ],
   "dependencies": {
-    "@volter/world-core": "2.0.1",
-    "@volter/world-runtime": "2.0.1"
+    "@modelcontextprotocol/sdk": "^1.30.1",
+    "@volter/world-core": "2.0.2",
+    "@volter/world-runtime": "2.0.3",
+    "zod": "^4.6.5"
+  },
+  "peerDependencies": {
+    "@volter/world-console": "2.0.3"
+  },
+  "peerDependenciesMeta": {
+    "@volter/world-console": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@volter/world-console": "2.0.3"
   },
   "bin": {
     "volter": "dist/src/cli.js"
   },
   "scripts": {
     "build": "node ../../scripts/publish/build.mjs",
-    "prepack": "node ../../scripts/publish/prepare-publish.mjs prepack",
-    "postpack": "node ../../scripts/publish/prepare-publish.mjs postpack"
+    "prepack": "node ./scripts/ship-skill.mjs in && node ../../scripts/publish/prepare-publish.mjs prepack",
+    "postpack": "node ../../scripts/publish/prepare-publish.mjs postpack && node ./scripts/ship-skill.mjs out"
   }
 }

package/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/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/src/agent-prompt.ts

@@ -0,0 +1,35 @@
+// 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.
+
+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 function agentPrompt(o: AgentPromptOptions = {}): string {
+  const cmd = (shell: string, tool: string): string => (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');
+}