@volter/world 3.0.138 → 3.0.140

package/examples/workplace-agent/README.md

@@ -0,0 +1,106 @@
+---
+title: GitHub issue to Linear ticket and Slack update
+---
+
+# GitHub issue to Linear ticket and Slack update
+
+Give a tool-using agent an isolated workplace: a GitHub repository and source issue, a Linear team and existing runbook task, and a Slack triage channel with a policy message. The starter reads an issue, creates a linked ticket and posts the result to the channel through the real SDKs.
+
+This application uses a labeled fixed policy: titles beginning with `P1:` receive priority 1; other titles receive priority 3. It exercises tools and stored outcomes. To assess an agent's planning or judgment, replace that decision with your own agent and configure its model twin's scripted answers separately. A successful fixed-rule handoff does not assess a model.
+
+You need Node 22.6+, npm and registry access during installation. No platform account, private application checkout or real vendor key is required.
+
+## Prepare an ordinary workplace
+
+```console
+$ npx @volter/world@3.0.140 example workplace-agent --dir workplace
+$ cd workplace
+$ npm install
+$ npx volter world init --name workplace --twins github,linear,slack
+```
+
+Read [package.json](./package.json), [package-lock.json](./package-lock.json) and [clients.mjs](./clients.mjs) for exact tool, twin and SDK versions. Keep the lockfile created by your installation. Review the three configured vendors and synthetic credentials before booting. No model vendor is selected by this starter.
+
+```console
+$ npx volter world up
+$ npx volter world clock set 2026-01-15T12:00:00Z
+$ npx volter world run -- node seed.mjs
+```
+
+[seed.mjs](./seed.mjs) creates stored records through each vendor's API. Run it once per fresh or reset World. It writes `company.json` with the returned repository owner, issue number, team and channel IDs. Existing runbook and policy records give your agent something to read before acting.
+
+## Complete a handoff
+
+```console
+$ npx volter world run -- node handoff.mjs
+$ npx volter world run -- node operate.mjs read
+$ npx volter world log
+$ npx volter world diff
+```
+
+Read the ticket's title, priority and team, then the channel and posted source/ticket links. [handoff.mjs](./handoff.mjs) writes an application receipt under `outcomes/` as soon as the ticket exists. A repeated completed handoff prints that receipt; it does not create another ticket. [operate.mjs](./operate.mjs) reads the vendor's stored result rather than trusting the receipt alone.
+
+## Give the task to your coding agent
+
+Install the World skill and MCP tools into your agent's configuration:
+
+```console
+$ npx volter agents install
+```
+
+If you already completed the example handoff, create another source issue with `world run -- node operate.mjs issue`. Give your agent that returned issue number and this task:
+
+> Read this starter's README and `company.json`. Work in its existing World. Read the source GitHub issue, the Linear backlog and the Slack policy message using the installed real SDKs inside `volter world run`. Apply the supplied priority policy, create a ticket with the source link, then notify the channel with both links. Preserve an application receipt as soon as the ticket exists. If notification is refused, report the stored ticket and pending notification separately. Read the resulting vendor records and show the World log; do not claim success from the script's exit alone. Inspect existing receipts before repeating a mutation.
+
+The agent uses the same public SDKs as [clients.mjs](./clients.mjs); the [coding-agent guide](https://world.volter.ai/docs/guides/use-with-a-coding-agent.html) owns CLI/MCP setup. You can leave the fixed policy in place to exercise tool use, or supply your own agent decision and model scenario. The requested outcomes are stored links, team, priority and completion state; a scripted response still does not measure model judgment.
+
+## Keep a partial result and retry it
+
+Archive the channel, then create another source issue:
+
+```console
+$ npx volter world run -- node operate.mjs archive
+$ npx volter world run -- node operate.mjs issue
+```
+
+Use the returned issue number in both commands below:
+
+```console
+$ npx volter world run -- node handoff.mjs <issue-number>
+$ npx volter world run -- node operate.mjs read <issue-number>
+```
+
+Slack's archived-channel refusal leaves the Linear ticket stored. The application reports `partial-ticket-created-notification-failed` and preserves the vendor error in its receipt. Unarchive the channel and resume that same handoff:
+
+```console
+$ npx volter world run -- node operate.mjs unarchive
+$ npx volter world run -- node handoff.mjs <issue-number>
+$ npx volter world run -- node operate.mjs read <issue-number>
+```
+
+The retry uses the recorded ticket and attempts only the notification. An uncertain process exit between a successful vendor call and writing its receipt requires inspecting the vendor before retrying; this example does not claim exactly-once external execution.
+
+`company.json` and `outcomes/` are application files outside declared World services. They are not branched or reset with vendor history. After explicitly resetting this disposable World, clear only this example's receipts with `node reset-receipts.mjs`, restore the frozen clock, then seed again. Do not reuse receipts from one World with another.
+
+## Create a synthetic GitHub organization
+
+Personal repositories use GitHub's ordinary create-repository API. Organization creation is a settings-page operation; this twin provides the declared `POST /_twin/orgs` endpoint for synthetic setup. [create-organization.mjs](./create-organization.mjs) discovers the authenticated account and sends:
+
+```json
+{
+  "login": "example-payments",
+  "name": "Example Payments",
+  "owner": "<login returned by GitHub users.getAuthenticated()>",
+  "billing_email": "owner@example.invalid"
+}
+```
+
+It expects HTTP 201 with the organization's `login` and `id`, then creates a private repository using `github.repos.createInOrg`. Run it once in this World:
+
+```console
+$ npx volter world run -- node create-organization.mjs
+```
+
+Without the owner or signed-in browser identity, the settings operation can redirect to sign-in. Inspect `GET /twin` for its declared setup endpoints rather than guessing a request body or inserting state files.
+
+Stop with `npx volter world down` to retain the workplace. [Inspect a World](https://world.volter.ai/docs/guides/inspect-a-world.html) shows its vendor screens, semantic relations and event history. [Failure handoff](https://world.volter.ai/docs/guides/reproduce-a-failure.html) describes how to share source, clock, handlers and application receipt conditions. [Source files](./public-files.json) identify the starter. The source instructions carry no new execution claim.

package/examples/workplace-agent/clients.mjs

@@ -0,0 +1,7 @@
+import { Octokit } from '@octokit/rest';
+import { LinearClient } from '@linear/sdk';
+import { WebClient } from '@slack/web-api';
+if (!process.env.VOLTER_WORLD) throw new Error('Run this application with volter world run');
+export const github = new Octokit({ auth: process.env.GITHUB_TOKEN, request: { timeout: 1500 } });
+export const linear = new LinearClient({ apiKey: process.env.LINEAR_API_KEY });
+export const slack = new WebClient(process.env.SLACK_BOT_TOKEN, { retryConfig: { retries: 0 }, timeout: 1500 });

package/examples/workplace-agent/create-organization.mjs

@@ -0,0 +1,11 @@
+import { github } from './clients.mjs';
+const owner = (await github.users.getAuthenticated()).data.login;
+const response = await fetch(`${process.env.GITHUB_TWIN_URL}/_twin/orgs`, {
+  method: 'POST', headers: { 'content-type': 'application/json' },
+  body: JSON.stringify({ login: 'example-payments', name: 'Example Payments', owner, billing_email: 'owner@example.invalid' }),
+  signal: AbortSignal.timeout(1500),
+});
+if (!response.ok) throw new Error(`Organization setup: ${response.status} ${await response.text()}`);
+console.log(await response.json());
+// GitHub's API exposes repository creation once its organization exists; org creation itself is a settings-page door.
+console.log((await github.repos.createInOrg({ org: 'example-payments', name: 'service', private: true })).data.full_name);

package/examples/workplace-agent/gitignore.template

@@ -0,0 +1,8 @@
+node_modules/
+.volter/worlds/
+.volter/world.env
+.volter/*.world.env
+.volter/token*
+company.json
+outcomes/
+brand/

package/examples/workplace-agent/handoff.mjs

@@ -0,0 +1,30 @@
+import { readFileSync, writeFileSync } from 'node:fs';
+import { github, linear, slack } from './clients.mjs';
+const company = JSON.parse(readFileSync('company.json', 'utf8'));
+const number = Number(process.argv[2] ?? company.sourceIssue);
+const path = `outcomes/issue-${number}.json`;
+const source = (await github.issues.get({ owner: company.owner, repo: company.repo, issue_number: number })).data;
+// A labeled fixed policy, not an assessment of a model's judgment. Bring your own agent here.
+const priority = source.title.startsWith('P1:') ? 1 : 3;
+let outcome;
+try { outcome = JSON.parse(readFileSync(path, 'utf8')); } catch (error) { if (error.code !== 'ENOENT') throw error; }
+if (outcome && outcome.world !== process.env.VOLTER_WORLD) throw new Error('This receipt belongs to another World; inspect its vendor state before proceeding');
+if (outcome?.completion === 'complete') { console.log(JSON.stringify(outcome, null, 2)); process.exit(0); }
+if (!outcome) {
+  const payload = await linear.createIssue({ teamId: company.teamId, title: source.title, description: `Source: ${source.html_url}\n\n${source.body}`, priority });
+  const ticket = await payload.issue;
+  if (!payload.success || !ticket) throw new Error('Linear did not create a ticket');
+  outcome = { world: process.env.VOLTER_WORLD, source: { number, url: source.html_url }, ticket: { id: ticket.id, identifier: ticket.identifier, url: ticket.url, title: ticket.title, priority }, message: null, completion: 'ticket-created-notification-pending' };
+  writeFileSync(path, JSON.stringify(outcome, null, 2) + '\n');
+}
+// Resume a refused notification from its application receipt; never create a second ticket on that retry.
+try {
+  const posted = await slack.chat.postMessage({ channel: company.channelId, text: `${outcome.ticket.identifier}: ${source.title}. Ticket: ${outcome.ticket.url}. Source: ${source.html_url}. Team: Reliability. Priority: ${priority}.` });
+  outcome.message = { channel: posted.channel, ts: posted.ts };
+  outcome.completion = 'complete'; delete outcome.error;
+} catch (error) {
+  outcome.completion = 'partial-ticket-created-notification-failed';
+  outcome.error = { code: error.code, vendorError: error.data?.error, message: error.message };
+}
+writeFileSync(path, JSON.stringify(outcome, null, 2) + '\n');
+console.log(JSON.stringify(outcome, null, 2));

package/examples/workplace-agent/operate.mjs

@@ -0,0 +1,21 @@
+import { readFileSync } from 'node:fs';
+import { github, linear, slack } from './clients.mjs';
+const company = JSON.parse(readFileSync('company.json', 'utf8'));
+switch (process.argv[2] ?? 'read') {
+  case 'issue': {
+    const made = await github.issues.create({ owner: company.owner, repo: company.repo, title: 'P1: Duplicate receipt after a retry', body: 'Synthetic second issue: deduplicate receipts while keeping history.' });
+    console.log(`New source issue ${made.data.number}`); break;
+  }
+  case 'archive': console.log(await slack.conversations.archive({ channel: company.channelId })); break;
+  case 'unarchive': console.log(await slack.conversations.unarchive({ channel: company.channelId })); break;
+  case 'read': {
+    const number = Number(process.argv[3] ?? company.sourceIssue);
+    const outcome = JSON.parse(readFileSync(`outcomes/issue-${number}.json`, 'utf8'));
+    const ticket = await linear.issue(outcome.ticket.id);
+    const team = await ticket.team;
+    const channel = await slack.conversations.info({ channel: company.channelId });
+    const messages = await slack.conversations.history({ channel: company.channelId, limit: 20 });
+    console.log(JSON.stringify({ completion: outcome.completion, ticket: { id: ticket.id, identifier: ticket.identifier, title: ticket.title, description: ticket.description, priority: ticket.priority, team: { id: team.id, name: team.name } }, channel: channel.channel, messages: messages.messages }, null, 2)); break;
+  }
+  default: throw new Error('Use issue, archive, unarchive or read [issue-number]');
+}

package/examples/workplace-agent/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "world-workplace-agent",
+  "private": true,
+  "type": "module",
+  "engines": {
+    "node": ">=22.6"
+  },
+  "dependencies": {
+    "@octokit/rest": "22.0.1",
+    "@linear/sdk": "86.0.0",
+    "@slack/web-api": "7.19.0"
+  },
+  "devDependencies": {
+    "@volter/world": "3.0.140",
+    "@volter/world-core": "3.0.140",
+    "@volter/world-runtime": "3.0.140",
+    "@volter/world-console": "3.0.135",
+    "@volter/twin-github": "3.0.6",
+    "@volter/twin-linear": "3.0.4",
+    "@volter/twin-slack": "3.0.5"
+  }
+}

package/examples/workplace-agent/public-files.json

@@ -0,0 +1,14 @@
+[
+  ".env.example",
+  ".gitignore",
+  "README.md",
+  "clients.mjs",
+  "create-organization.mjs",
+  "handoff.mjs",
+  "operate.mjs",
+  "package-lock.json",
+  "package.json",
+  "public-files.json",
+  "reset-receipts.mjs",
+  "seed.mjs"
+]

package/examples/workplace-agent/reset-receipts.mjs

@@ -0,0 +1,5 @@
+// Only this example's named application receipts. Never a World, credential or unknown directory.
+import { existsSync, readdirSync, unlinkSync } from 'node:fs';
+if (existsSync('company.json')) unlinkSync('company.json');
+if (existsSync('outcomes')) for (const name of readdirSync('outcomes')) if (/^issue-\d+\.json$/.test(name)) unlinkSync('outcomes/' + name);
+console.log('Application receipts cleared; vendor state was not changed');

package/examples/workplace-agent/seed.mjs

@@ -0,0 +1,16 @@
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { github, linear, slack } from './clients.mjs';
+const owner = (await github.users.getAuthenticated()).data.login;
+await github.repos.createForAuthenticatedUser({ name: 'payments', private: true, description: 'Synthetic payments app' });
+const source = await github.issues.create({ owner, repo: 'payments', title: 'P1: Retried webhook creates duplicate orders', body: 'Deliver the same provider event twice. Expected: one order and one receipt. Preserve audit history; deduplicate by provider event ID.' });
+const teamPayload = await linear.createTeam({ name: 'Reliability', key: 'REL' });
+const team = await teamPayload.team;
+if (!teamPayload.success || !team) throw new Error('Linear did not create the Reliability team');
+await linear.createIssue({ teamId: team.id, title: 'Document the on-call runbook', priority: 3 });
+const channel = await slack.conversations.create({ name: 'payments-triage', is_private: false });
+if (!channel.channel?.id) throw new Error('Slack did not create the triage channel');
+await slack.chat.postMessage({ channel: channel.channel.id, text: 'Payment integrity issues go to Reliability. Every update includes the source and ticket links.' });
+mkdirSync('outcomes', { recursive: true });
+const company = { name: 'Example Payments', owner, repo: 'payments', sourceIssue: source.data.number, teamId: team.id, channelId: channel.channel.id, policy: 'P1 payment integrity → Reliability, priority 1' };
+writeFileSync('company.json', JSON.stringify(company, null, 2) + '\n');
+console.log(JSON.stringify(company, null, 2));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/world",
-  "version": "3.0.138",
+  "version": "3.0.140",
   "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",
@@ -26,16 +26,17 @@
   "files": [
     "src",
     "dist",
-    "skills"
+    "skills",
+    "examples"
   ],
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.1",
-    "@volter/world-core": "3.0.138",
-    "@volter/world-runtime": "3.0.138",
+    "@volter/world-core": "3.0.140",
+    "@volter/world-runtime": "3.0.140",
     "zod": "^4.6.5"
   },
   "peerDependencies": {
-    "@volter/world-console": "3.0.133"
+    "@volter/world-console": "3.0.135"
   },
   "peerDependenciesMeta": {
     "@volter/world-console": {
@@ -43,14 +44,14 @@
     }
   },
   "devDependencies": {
-    "@volter/world-console": "3.0.133"
+    "@volter/world-console": "3.0.135"
   },
   "bin": {
     "volter": "dist/src/cli.js"
   },
   "scripts": {
-    "build": "node ../../scripts/publish/build.mjs",
-    "prepack": "node ./scripts/ship-skill.mjs in && node ../../scripts/publish/prepare-publish.mjs prepack",
+    "build": "node ../../scripts/prepare-world-examples.mjs && node ../../scripts/publish/build.mjs",
+    "prepack": "node ../../scripts/prepare-world-examples.mjs && 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"
   },
   "homepage": "https://world.volter.ai/docs/getting-started"

package/src/agent-prompt.ts

@@ -15,13 +15,13 @@ export type AgentPromptOptions = {
 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.',
+    'Set up Volter World for the workflow I want to run in this app. Select only the vendors that workflow deliberately substitutes with local twins. Keep the app\'s real SDKs.',
     '',
     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.`,
+      ? '1. You have the Volter World tools (volter mcp). Keep an app\'s existing pinned World tools. If the `volter` command is missing, install it: `npm install -g @volter/world`.'
+      : '1. Keep the app\'s pinned World tools if present, using its local CLI through `npx`. Otherwise install the command: `npm install -g @volter/world`. Install the agent tooling with `volter agents install --yes`.',
+    `2. Read the app's manifests, env names and any .volter/world.json. Show me the likely vendors and why, before keeping them. Preserve a saved World and its state; do not initialize it again to resume. For a new World, choose the exact catalog releases and initialize only the selected vendors with ${cmd('volter world init --twins <selected-vendors> --source <vendor>=<package>', 'world_init with vendors and sources')}.`,
+    `3. ${o.tools ? 'Start it with world_up' : 'Start it: `volter world up`'}, then run my usual app command inside it: ${cmd('volter world run -- <the app command>', 'world_run')}. Use throwaway credentials. Diagnose a failure as routing, data, scenario, unsupported operation or runtime; preserve the refusal's evidence rather than bypassing it.`,
     `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) {

package/src/cli.ts

@@ -14,6 +14,7 @@ import { existsSync } from 'node:fs';
 import { join, relative, resolve } from 'node:path';
 import { forgetPlatform, forgetToken, platformOrigin, requireToken, storePlatform, storeToken, tokenFor } from './credentials.ts';
 import { parseOriginUrl, World } from './world.ts';
+import { copyExample, examples } from './examples.ts';
 import { waitForServeShutdown } from './serve-shutdown.ts';
 import { startUpdateCheck } from './update-notice.ts';
 import type { ViewConsole } from '@volter/world-runtime';
@@ -37,6 +38,8 @@ world  — the twins your app needs, running together (the world of the current
   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 example list                                   ready application starters included in this CLI release
+  volter example <name> [--dir <path>]                    copy a cookbook starter into an empty directory; does not install or start it
   volter world serve [--port <p>] [--console-port <c>] [--origin <url>]   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] [--origin <url>]   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
@@ -55,7 +58,7 @@ world  — the twins your app needs, running together (the world of the current
   volter world origin                                    where this world clones from and pushes to
   volter world changeset [<name>] -m "<message>"         cut the unpushed changes into a reviewable changeset
   volter world pull [--token <token>]                    fetch, then move this branch onto what came in (git's pull)
-  volter world push [<name>] [--token <token>] [--force] send entries to the remote; vendor deployment follows its root policy
+  volter world push [<name>] [--remote <remote>] [--token <token>] [--force] send entries to the selected remote (default origin); vendor deployment follows its root policy
   volter world rebase [<changeset>]                      rebase this branch onto its moved base, or a changeset onto the moved remote
   volter world verify <changeset>                        run the world's checks over a changeset and record the result
   volter world approve <changeset> --as <principal>      sign a changeset's current hash
@@ -106,7 +109,19 @@ function positionals(args: string[], valueFlags: string[]): string[] {
   return out;
 }
 function afterDashes(args: string[]): string[] { const i = args.indexOf('--'); return i < 0 ? [] : args.slice(i + 1); }
-const VALUE_FLAGS = ['--world', '--branch', '--name', '--token', '--admin-token', '-m', '--message', '--base', '--org', '--vendors', '--into', '--deploy', '--as', '--note', '--port', '--twins', '--source', '--host', '--origin', '--scope', '--refresh', '--at-most', '--at'];
+const VALUE_FLAGS = ['--world', '--branch', '--name', '--token', '--admin-token', '-m', '--message', '--base', '--org', '--vendors', '--into', '--deploy', '--as', '--note', '--port', '--twins', '--source', '--host', '--origin', '--remote', '--dir', '--scope', '--refresh', '--at-most', '--at'];
+
+/** Help is resolved before opening a World; the child after `run --` owns its own flags. */
+function wantsHelp(noun: string | undefined, verb: string | undefined, args: string[]): boolean {
+  const boundary = args.indexOf('--');
+  const options = boundary < 0 ? args : args.slice(0, boundary);
+  return !noun || noun === 'help' || noun === '--help' || noun === '-h'
+    || verb === '--help' || verb === '-h' || options.some((arg) => arg === '--help' || arg === '-h');
+}
+function printHelp(noun?: string, verb?: string): void {
+  const lines = noun && verb ? HELP.split('\n').filter((line) => line.startsWith(`  volter ${noun} ${verb} `)) : [];
+  out(lines.length ? `${lines.join('\n')}\n\n  --world <dir>    select the app's World\n  --branch <name>  select a branch\n  --json           machine-readable output where offered` : HELP);
+}
 
 /** A subject as a person names it: an id that already carries its context (`acme/web#1`, `C-ops/ts`) stands alone, with an embedded `<type>:` dropped; a bare id gets its type. */
 function subjectLabel(subject: { type: string; id: string }): string {
@@ -272,8 +287,9 @@ async function worldCommand(verb: string, args: string[]): Promise<void> {
         }
         return { positions, views };
       })();
+      const parent = world.name;
       const made = await world.branch(name, at ? { at } : {});
-      out(`branch  ${made.name}  from ${world.isMain() ? 'main' : world.name}${at ? `  at ${atText}` : ''}`);
+      out(`branch  ${made.name}  from ${parent}${at ? `  at ${atText}` : ''}`);
       return;
     }
     case 'checkout': {
@@ -419,8 +435,16 @@ async function worldCommand(verb: string, args: string[]): Promise<void> {
       return;
     }
     case 'push': {
-      const remoteName = 'origin';
-      const outcomes = await world.push({ ...(pos[0] ? { name: pos[0] } : {}), ...(value(args, '--token') ? { token: value(args, '--token')! } : {}), force: flag(args, '--force') });
+      if (pos.length > 1) throw new Error('volter world push [<changeset>] [--remote <name>]: choose the destination with --remote');
+      for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i]!;
+        if (['--remote', '--token', '--world', '--branch'].includes(arg)) {
+          if (!args[i + 1] || args[i + 1]!.startsWith('-')) throw new Error(`volter world push: ${arg} needs a value`);
+          i += 1;
+        } else if (arg.startsWith('-') && !['--force', '--json'].includes(arg)) throw new Error(`volter world push: unknown option ${arg}`);
+      }
+      const remoteName = value(args, '--remote') ?? 'origin';
+      const outcomes = await world.push({ remote: remoteName, ...(pos[0] ? { name: pos[0] } : {}), ...(value(args, '--token') ? { token: value(args, '--token')! } : {}), force: flag(args, '--force') });
       if (asJson) { json(outcomes); return; }
       if (outcomes.length === 0) { out('nothing to push'); return; }
       for (const o of outcomes) {
@@ -799,16 +823,30 @@ function ownVersion(): string {
 
 async function main(): Promise<void> {
   const [noun, verb, ...args] = process.argv.slice(2);
+  if (wantsHelp(noun, verb, args)) { printHelp(noun, verb); return; }
   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; }
+  if (wantsHelp(noun, verb, args)) { printHelp(noun, verb); return; }
   if (noun === '--version' || noun === '-v' || noun === 'version') { out(`volter ${ownVersion()}`); return; }
   switch (noun) {
+    case 'example': {
+      if (!verb || verb === 'list') {
+        if (args.length) throw new Error('volter example list takes no arguments');
+        for (const e of examples()) out(`${e.id}  ${e.title}`); return;
+      }
+      for (let i = 0; i < args.length; i++) {
+        if (args[i] !== '--dir' || !args[i + 1] || args[i + 1]!.startsWith('-')) throw new Error('volter example <name> [--dir <path>]');
+        i++;
+      }
+      const target = copyExample(verb, value(args, '--dir') ?? verb);
+      out(`example  ${verb}  ${target}`);
+      out(`Read ${target}/README.md, install its dependencies, then review the vendors before world init.`);
+      return;
+    }
     case 'world': {
       if (!verb) throw new Error(`volter world: which verb?\n\n${HELP}`);
       await worldCommand(verb, args);

package/src/examples.ts

@@ -0,0 +1,24 @@
+import { copyFileSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+type Example = { id: string; title: string; files: string[] };
+const packaged = () => fileURLToPath(new URL('../examples/', import.meta.url));
+export function examples(): Example[] {
+  const index = join(packaged(), 'index.json');
+  if (!existsSync(index)) throw new Error('Starter files are absent from this CLI build; build @volter/world or install a release containing examples');
+  return JSON.parse(readFileSync(index, 'utf8')) as Example[];
+}
+export function copyExample(id: string, directory: string): string {
+  const example = examples().find(e => e.id === id);
+  if (!example) throw new Error(`Unknown example ${id}; use volter example list`);
+  const target = resolve(directory);
+  if (existsSync(target) && (!lstatSync(target).isDirectory() || lstatSync(target).isSymbolicLink() || readdirSync(target).length)) throw new Error(`Example destination must be an empty directory: ${target}`);
+  const source = join(packaged(), example.id);
+  const sourceFile = (file: string): string => join(source, file === '.gitignore' ? 'gitignore.template' : file);
+  for (const file of example.files) {
+    if (!file || file.includes('..') || file.includes('\\') || file.startsWith('/') || file === '.env' || !lstatSync(sourceFile(file)).isFile() || lstatSync(sourceFile(file)).isSymbolicLink()) throw new Error(`Invalid packaged example file ${file}`);
+  }
+  mkdirSync(target, { recursive: true });
+  for (const file of example.files) { mkdirSync(dirname(join(target, file)), { recursive: true }); copyFileSync(sourceFile(file), join(target, file)); }
+  return target;
+}

package/src/mcp.ts

@@ -165,8 +165,8 @@ export async function serveMcp(version: string): Promise<void> {
 
   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))));
+    inputSchema: { ...dirArg, changeset: z.string().optional().describe('Push one changeset by name; default all unpushed.'), remote: z.string().optional().describe('Named destination; default origin.') },
+  }, async ({ dir, changeset, remote }) => ran(await volter(['world', 'push', ...(changeset ? [changeset] : []), ...(remote ? ['--remote', remote] : [])], 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.',

package/src/world.ts

@@ -61,10 +61,10 @@ export type WorldStatus = {
 };
 
 /** `https://host/org/world` → the remote's base URL and the namespace it addresses. */
-export function parseOriginUrl(url: string): { url: string; namespace: string } {
+export function parseOriginUrl(url: string, worldRoot = process.cwd()): { url: string; namespace: string } {
   // a PATH is a world on this machine (git's file transport): its directory, and its served name
   if (!/^[a-z][a-z0-9+.-]*:\/\//i.test(url)) {
-    const root = resolve(url);
+    const root = resolve(worldRoot, url);
     const configPath = join(root, '.volter', 'world.json');
     if (!existsSync(configPath)) throw new Error(`Not a remote URL or world directory: ${url} (want https://<host>/<org>/<world>, or a directory holding .volter/world.json)`);
     const config = loadWorldConfig(configPath, root).config;
@@ -134,7 +134,7 @@ export class World {
     const existing = this.instance();
     if (existing?.running) return existing; // already up: nothing to do
     const instance = await upWorld(worldConfigRelative(), {
-      name: this.name, root: this.root, envFile: worldEnvPath(this.root),
+      name: this.name, root: this.root, envFile: existing?.envFile ?? worldEnvPath(this.root),
       ...(opts.mode ? { mode: opts.mode } : existing ? { mode: existing.mode } : {}),
       ...(existing ? { keepState: true } : {}),
     });
@@ -182,7 +182,7 @@ export class World {
       // pushed to it has not fetched, but it has an origin all the same)
       origin: (() => { const o = this.origin(); return o ? { url: o.url, namespace: o.namespace, ...(o.fetchedAt ? { fetchedAt: o.fetchedAt } : {}) } : null; })(),
       unpushed: instance ? this.unpushed().length : 0,
-      changesets: { total: changesets.length, pushed: changesets.filter((c) => c.changeset.applied?.outcome === 'applied').length },
+      changesets: { total: changesets.length, pushed: changesets.filter(({ changeset: c }) => c.applied?.outcome === 'applied' && (!c.applied.destination || (c.applied.destination.url === this.origin()?.url && c.applied.destination.namespace === this.origin()?.namespace))).length },
       services,
       ...(instance ? { envFile: instance.envFile } : {}),
     };
@@ -198,7 +198,7 @@ export class World {
   }
 
   // ── the log ─────────────────────────────────────────────────────────────────────────────
-  /** Every write the app made, across the twins, oldest first, with the receipt against each pushed one. */
+  /** Every recorded write grouped by vendor in its position order, with delivery receipts where available. */
   log(): LogEntry[] {
     const receipts = new Map<string, { receipt: ApplyReceipt; changeset: string }>();
     for (const located of this.changesets()) for (const receipt of located.changeset.applied?.receipts ?? []) receipts.set(receipt.actionId, { receipt, changeset: located.changeset.name });
@@ -227,7 +227,10 @@ export class World {
         rows.push(l ? { ...row, landed: l } : r ? { ...row, receipt: r.receipt, changeset: r.changeset } : row);
       }
     }
-    return rows.sort((a, b) => a.occurredAt.localeCompare(b.occurredAt) || a.id.localeCompare(b.id));
+    // Each vendor has its own position; timestamps (including a frozen clock) never shuffle it.
+    // Group vendors rather than inventing a global sequence from independent positions.
+    return rows.sort((a, b) => a.service.localeCompare(b.service) ||
+      (a.position !== undefined && b.position !== undefined ? a.position - b.position : a.occurredAt.localeCompare(b.occurredAt)));
   }
   /** Changes not yet pushed (`log origin..HEAD`), across the twins. */
   unpushed(): TwinAction[] { return this.repos().flatMap((r) => r.unpushed({ pushable: true })).sort((a, b) => a.occurredAt.localeCompare(b.occurredAt)); }
@@ -363,7 +366,7 @@ export class World {
     const { path, config } = loadWorldConfig(this.configRef(), this.root);
     const remotes = { ...(config.remotes ?? {}), [name]: target };
     writeWorldConfig(path, { ...config, remotes });
-    if (opts.token) storeToken(parseOriginUrl(target).url, opts.token);
+    if (opts.token) storeToken(parseOriginUrl(target, this.root).url, opts.token);
   }
   removeRemote(name: string): void {
     const { path, config } = loadWorldConfig(this.configRef(), this.root);
@@ -376,7 +379,7 @@ export class World {
     const instance = name === 'origin' ? this.instance() : null;
     if (instance && instance.name !== instance.config) return instance.origin ? { url: instance.origin.url, namespace: instance.origin.namespace } : null;
     const target = this.remotes()[name];
-    if (target) return parseOriginUrl(target);
+    if (target) return parseOriginUrl(target, this.root);
     if (name !== 'origin') return null;
     const recorded = this.recordedOrigin();
     return recorded ? { url: recorded.url, namespace: recorded.namespace } : null;
@@ -398,7 +401,7 @@ export class World {
    * the world's, which is what `fetch` and `push` use afterwards.
    */
   async clone(url: string, opts: { token?: string; adminToken?: string } = {}): Promise<ReturnType<typeof fetchFromOrigin>> {
-    const origin = parseOriginUrl(url);
+    const origin = parseOriginUrl(url, this.root);
     if (opts.token !== undefined && opts.token !== '') storeToken(origin.url, opts.token);
     if (opts.adminToken !== undefined && opts.adminToken !== '') {
       if (opts.token === undefined || opts.token === '') storeToken(origin.url, opts.adminToken);
@@ -448,23 +451,32 @@ export class World {
   }
   changesets(): ChangesetLocation[] { return listWorldChangesets({ root: this.root, world: this.name }); }
   /**
-   * Push to the origin, which deploys to the vendor with its own keys and answers with receipts:
+   * Push to a selected remote (origin by default), which answers with receipts under its policy:
    * the named changeset, or every changeset not yet pushed, oldest first. A local world never
    * holds a vendor credential.
    */
-  async push(opts: { name?: string; token?: string; force?: boolean } = {}): Promise<Array<Awaited<ReturnType<typeof pushWorldChangeset>>>> {
-    const origin = this.origin();
-    if (!origin) throw new Error(`World "${this.name}" has no origin to push to — the default data cannot be pushed to. \`volter world clone <url>\` connects a remote.`);
+  async push(opts: { name?: string; remote?: string; token?: string; force?: boolean } = {}): Promise<Array<Awaited<ReturnType<typeof pushWorldChangeset>>>> {
+    const remoteName = opts.remote ?? 'origin';
+    const origin = this.remote(remoteName);
+    if (!origin) throw new Error(remoteName === 'origin'
+      ? `World "${this.name}" has no origin to push to — the default data cannot be pushed to. \`volter world clone <url>\` connects a remote.`
+      : `World "${this.name}" has no remote "${remoteName}" — \`volter remote add ${remoteName} <url|path>\` names one.`);
+    const tracked = this.origin();
+    const trackOrigin = tracked?.url === origin.url && tracked.namespace === origin.namespace;
     if (opts.token !== undefined && opts.token !== '') storeToken(origin.url, opts.token);
     const key = requireToken(origin.url, opts.token);
     const to = { to: origin.url, namespace: origin.namespace };
     const queue = opts.name !== undefined
       ? [findWorldChangeset(opts.name, { root: this.root, world: this.name })]
-      : this.changesets().filter((c) => c.changeset.applied === null || c.changeset.applied.outcome === 'refused').sort((a, b) => a.changeset.createdAt.localeCompare(b.changeset.createdAt));
+      : this.changesets().filter((c) => {
+        const applied = c.changeset.applied;
+        if (!applied || applied.outcome === 'refused') return true;
+        return applied.destination ? applied.destination.url !== origin.url || applied.destination.namespace !== origin.namespace : !trackOrigin;
+      }).sort((a, b) => a.changeset.createdAt.localeCompare(b.changeset.createdAt));
     if (queue.length === 0) throw new Error(this.unpushed().length ? 'Nothing to push: cut a changeset first — `volter world changeset -m "<what and why>"`' : 'Nothing to push: no unpushed changes');
     const outcomes: Array<Awaited<ReturnType<typeof pushWorldChangeset>>> = [];
     for (const located of queue) {
-      const outcome = await pushWorldChangeset(located.changeset.name, { root: this.root, world: this.name, ...to, key, ...(opts.force ? { force: true } : {}) });
+      const outcome = await pushWorldChangeset(located.changeset.name, { root: this.root, world: this.name, ...to, key, trackOrigin, ...(opts.force ? { force: true } : {}) });
       outcomes.push(outcome);
       if (outcome.application.outcome === 'refused') break;
     }