@volter/world 3.0.145 → 3.0.146

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (15) hide show
  1. package/dist/examples/customer-onboarding/README.md +20 -20
  2. package/dist/examples/customer-onboarding/package.json +4 -4
  3. package/dist/examples/integration-branches/README.md +32 -32
  4. package/dist/examples/integration-branches/package.json +4 -4
  5. package/dist/examples/workplace-agent/README.md +19 -19
  6. package/dist/examples/workplace-agent/package.json +4 -4
  7. package/dist/src/agent-prompt.js +1 -1
  8. package/examples/customer-onboarding/README.md +20 -20
  9. package/examples/customer-onboarding/package.json +4 -4
  10. package/examples/integration-branches/README.md +32 -32
  11. package/examples/integration-branches/package.json +4 -4
  12. package/examples/workplace-agent/README.md +19 -19
  13. package/examples/workplace-agent/package.json +4 -4
  14. package/package.json +5 -5
  15. package/src/agent-prompt.ts +1 -1
package/dist/examples/customer-onboarding/README.md CHANGED
@@ -13,7 +13,7 @@ You need Node 22.6+, npm and registry access during installation. The browser pa
13
13
  Copy this starter into a new folder:
14
14
 
15
15
  ```console
16
- $ npx @volter/world@3.0.145 example customer-onboarding --dir onboarding
16
+ $ npx @volter/world@3.0.146 example customer-onboarding --dir onboarding
17
17
  $ cd onboarding
18
18
  $ npm install
19
19
  ```
@@ -23,7 +23,7 @@ The command copies source; it neither installs dependencies nor starts a World.
23
23
  Read [onboarding.mjs](./onboarding.mjs) for the application and [run.mjs](./run.mjs) for the command entry. Empty keys in [.env.example](./.env.example) tell init what the app reads; init supplies throwaway credentials. Do not add real keys.
24
24
 
25
25
  ```console
26
- $ npx volter world init --name onboarding --twins stripe,resend
26
+ $ ./node_modules/.bin/volter world init --name onboarding --twins stripe,resend
27
27
  ```
28
28
 
29
29
  Review Stripe and Resend's exact sources in `.volter/world.json`. The `pg` dependency and `DATABASE_URL` also request a managed PostgreSQL service. Keep it: this app needs SQL. SaaS selection does not exclude a declared native database. `world covers` describes the configured database as part of this workflow.
@@ -31,12 +31,12 @@ Review Stripe and Resend's exact sources in `.volter/world.json`. The `pg` depen
31
31
  ## Create and read an account
32
32
 
33
33
  ```console
34
- $ npx volter world up
35
- $ npx volter world clock set 2026-01-15T12:00:00Z
36
- $ npx volter world run -- node run.mjs create Ada owner@world.test
37
- $ npx volter world clock advance 5s
38
- $ npx volter world run -- node run.mjs read
39
- $ npx volter world log
34
+ $ ./node_modules/.bin/volter world up
35
+ $ ./node_modules/.bin/volter world clock set 2026-01-15T12:00:00Z
36
+ $ ./node_modules/.bin/volter world run -- node run.mjs create Ada owner@world.test
37
+ $ ./node_modules/.bin/volter world clock advance 5s
38
+ $ ./node_modules/.bin/volter world run -- node run.mjs read
39
+ $ ./node_modules/.bin/volter world log
40
40
  ```
41
41
 
42
42
  Read the customer returned by Stripe, the signup row returned by SQL and the email returned by Resend. `completion: complete` means delivery was observed, not merely that a send request was accepted. Opaque IDs can differ between fresh Worlds; customer identity, stored fields and delivery status are the useful outcomes.
@@ -46,25 +46,25 @@ Read the customer returned by Stripe, the signup row returned by SQL and the ema
46
46
  A refusing recipient's mail server creates a bounce after the send was accepted:
47
47
 
48
48
  ```console
49
- $ npx volter world run -- node run.mjs bounce
50
- $ npx volter world run -- node run.mjs create Grace owner@world.test
51
- $ npx volter world clock advance 5s
52
- $ npx volter world run -- node run.mjs read
49
+ $ ./node_modules/.bin/volter world run -- node run.mjs bounce
50
+ $ ./node_modules/.bin/volter world run -- node run.mjs create Grace owner@world.test
51
+ $ ./node_modules/.bin/volter world clock advance 5s
52
+ $ ./node_modules/.bin/volter world run -- node run.mjs read
53
53
  ```
54
54
 
55
55
  Grace's customer and SQL row remain. Her email exists and has `last_event: bounced`; the application reports `partial-email-bounced`. The `bounce` command uses Resend's declared synthetic recipient setting, not a successful-send handler. Restore delivery before later signups:
56
56
 
57
57
  ```console
58
- $ npx volter world run -- node run.mjs deliver
58
+ $ ./node_modules/.bin/volter world run -- node run.mjs deliver
59
59
  ```
60
60
 
61
61
  An unverified sender is refused before an email is accepted:
62
62
 
63
63
  ```console
64
- $ npx volter world run -- node run.mjs refused
65
- $ npx volter world run -- node run.mjs retry
66
- $ npx volter world clock advance 5s
67
- $ npx volter world run -- node run.mjs read
64
+ $ ./node_modules/.bin/volter world run -- node run.mjs refused
65
+ $ ./node_modules/.bin/volter world run -- node run.mjs retry
66
+ $ ./node_modules/.bin/volter world clock advance 5s
67
+ $ ./node_modules/.bin/volter world run -- node run.mjs read
68
68
  ```
69
69
 
70
70
  The first command creates Lin's customer and SQL row, then records the email refusal. The second resumes that pending welcome on the same customer. It refuses to resend an email that already has an accepted ID. These application receipts do not guarantee exactly-once delivery after an ambiguous network failure; resolve acceptance before retrying an uncertain send.
@@ -80,7 +80,7 @@ $ node prepare-ui.mjs
80
80
  Then start the app through the World:
81
81
 
82
82
  ```console
83
- $ npx volter world run -- node server.mjs
83
+ $ ./node_modules/.bin/volter world run -- node server.mjs
84
84
  ```
85
85
 
86
86
  Open the printed app URL in your browser. Submit a signup, advance the World clock in another terminal and reload. The page shows the completion state and full stored outcome. Its server registers its app URL with the World after listening; consumers can discover it with `world app-url`.
@@ -88,8 +88,8 @@ Open the printed app URL in your browser. Submit a signup, advance the World clo
88
88
  To open the World dashboard, stop the app with Ctrl-C first, then switch the owned compute to the viewer:
89
89
 
90
90
  ```console
91
- $ npx volter world down
92
- $ npx volter world view --no-open
91
+ $ ./node_modules/.bin/volter world down
92
+ $ ./node_modules/.bin/volter world view --no-open
93
93
  ```
94
94
 
95
95
  The viewer prints the dashboard URL and keeps running. Start `world run -- node server.mjs` in a second terminal if you want the application alongside it. Open **Stripe** under **Records**, then select the customer to inspect its name, email and stored ID. Open **Resend** to inspect the accepted email and delivery event. **Board** opens the vendor pages declared by the installed twin; its root workspace may cover settings rather than customers. Provisioning remains in full history even when hidden from the business-activity view. Read the application's SQL completion record with `run.mjs read` or its browser page.
package/dist/examples/customer-onboarding/package.json CHANGED
@@ -11,10 +11,10 @@
11
11
  "pg": "8.16.3"
12
12
  },
13
13
  "devDependencies": {
14
- "@volter/world": "3.0.145",
15
- "@volter/world-core": "3.0.145",
16
- "@volter/world-runtime": "3.0.145",
17
- "@volter/world-console": "3.0.140",
14
+ "@volter/world": "3.0.146",
15
+ "@volter/world-core": "3.0.146",
16
+ "@volter/world-runtime": "3.0.146",
17
+ "@volter/world-console": "3.0.141",
18
18
  "@volter/twin-stripe": "3.0.2",
19
19
  "@volter/twin-resend": "1.0.1"
20
20
  }
package/dist/examples/integration-branches/README.md CHANGED
@@ -13,21 +13,21 @@ Give two workers the same Stripe baseline, let them change different existing cu
13
13
  Use an empty parent folder. Create the baseline starter there:
14
14
 
15
15
  ```console
16
- $ npx @volter/world@3.0.145 example integration-branches --dir baseline
16
+ $ npx @volter/world@3.0.146 example integration-branches --dir baseline
17
17
  $ cd baseline
18
18
  $ npm install
19
- $ npx volter world init --name baseline --twins stripe
19
+ $ ./node_modules/.bin/volter world init --name baseline --twins stripe
20
20
  ```
21
21
 
22
22
  Review the selected vendor, then create Ada and Grace through the SDK:
23
23
 
24
24
  ```console
25
- $ npx volter world up
26
- $ npx volter world clock set 2026-01-15T12:00:00Z
27
- $ npx volter world run -- node customer.mjs create Ada
28
- $ npx volter world run -- node customer.mjs create Grace
29
- $ npx volter world run -- node customer.mjs read
30
- $ npx volter world down
25
+ $ ./node_modules/.bin/volter world up
26
+ $ ./node_modules/.bin/volter world clock set 2026-01-15T12:00:00Z
27
+ $ ./node_modules/.bin/volter world run -- node customer.mjs create Ada
28
+ $ ./node_modules/.bin/volter world run -- node customer.mjs create Grace
29
+ $ ./node_modules/.bin/volter world run -- node customer.mjs read
30
+ $ ./node_modules/.bin/volter world down
31
31
  $ cd ..
32
32
  ```
33
33
 
@@ -38,9 +38,9 @@ The stopped baseline retains its history and can supply local path remotes. Defa
38
38
  Create three more copies in the same parent folder:
39
39
 
40
40
  ```console
41
- $ npx @volter/world@3.0.145 example integration-branches --dir integration
42
- $ npx @volter/world@3.0.145 example integration-branches --dir worker-a
43
- $ npx @volter/world@3.0.145 example integration-branches --dir worker-b
41
+ $ npx @volter/world@3.0.146 example integration-branches --dir integration
42
+ $ npx @volter/world@3.0.146 example integration-branches --dir worker-a
43
+ $ npx @volter/world@3.0.146 example integration-branches --dir worker-b
44
44
  ```
45
45
 
46
46
  In `integration`, then `worker-a`, then `worker-b`, install dependencies and initialize with the folder's name. Before a first boot or app write, link and pull the baseline:
@@ -48,10 +48,10 @@ In `integration`, then `worker-a`, then `worker-b`, install dependencies and ini
48
48
  ```console
49
49
  $ cd integration
50
50
  $ npm install
51
- $ npx volter world init --name integration --twins stripe
52
- $ npx volter remote add origin ../baseline
53
- $ npx volter world pull
54
- $ npx volter world clock set 2026-01-15T12:00:00Z
51
+ $ ./node_modules/.bin/volter world init --name integration --twins stripe
52
+ $ ./node_modules/.bin/volter remote add origin ../baseline
53
+ $ ./node_modules/.bin/volter world pull
54
+ $ ./node_modules/.bin/volter world clock set 2026-01-15T12:00:00Z
55
55
  $ cd ..
56
56
  ```
57
57
 
@@ -61,12 +61,12 @@ Repeat that block in each worker, replacing both occurrences of `integration` wi
61
61
 
62
62
  ```console
63
63
  $ cd worker-a
64
- $ npx volter world run -- node customer.mjs rename Ada Ada-worker-A
65
- $ npx volter world changeset worker-a-change -m "Worker A renames Ada"
66
- $ npx volter remote add integration ../integration
67
- $ npx volter world push worker-a-change --remote integration
68
- $ npx volter world run -- node receipt.mjs
69
- $ npx volter world down
64
+ $ ./node_modules/.bin/volter world run -- node customer.mjs rename Ada Ada-worker-A
65
+ $ ./node_modules/.bin/volter world changeset worker-a-change -m "Worker A renames Ada"
66
+ $ ./node_modules/.bin/volter remote add integration ../integration
67
+ $ ./node_modules/.bin/volter world push worker-a-change --remote integration
68
+ $ ./node_modules/.bin/volter world run -- node receipt.mjs
69
+ $ ./node_modules/.bin/volter world down
70
70
  $ cd ..
71
71
  ```
72
72
 
@@ -76,19 +76,19 @@ The delivery receipt names integration. The worker's tracked `origin` still name
76
76
 
77
77
  ```console
78
78
  $ cd worker-b
79
- $ npx volter world run -- node customer.mjs rename Grace Grace-worker-B
80
- $ npx volter world changeset worker-b-change -m "Worker B renames Grace"
81
- $ npx volter remote add integration ../integration
82
- $ npx volter world push worker-b-change --remote integration
83
- $ npx volter world down
79
+ $ ./node_modules/.bin/volter world run -- node customer.mjs rename Grace Grace-worker-B
80
+ $ ./node_modules/.bin/volter world changeset worker-b-change -m "Worker B renames Grace"
81
+ $ ./node_modules/.bin/volter remote add integration ../integration
82
+ $ ./node_modules/.bin/volter world push worker-b-change --remote integration
83
+ $ ./node_modules/.bin/volter world down
84
84
  $ cd ../integration
85
- $ npx volter world run -- node customer.mjs read
86
- $ npx volter world run -- node receipt.mjs
87
- $ npx volter world down
85
+ $ ./node_modules/.bin/volter world run -- node customer.mjs read
86
+ $ ./node_modules/.bin/volter world run -- node receipt.mjs
87
+ $ ./node_modules/.bin/volter world down
88
88
  $ cd ../baseline
89
- $ npx volter world up
90
- $ npx volter world run -- node customer.mjs read
91
- $ npx volter world down
89
+ $ ./node_modules/.bin/volter world up
90
+ $ ./node_modules/.bin/volter world run -- node customer.mjs read
91
+ $ ./node_modules/.bin/volter world down
92
92
  ```
93
93
 
94
94
  Integration holds the two renamed customers. Baseline still holds Ada and Grace. This example deliberately changes distinct records. A named delivery binds to the destination head it reads and refuses a concurrent move; it does not provide an automatic semantic merge for two workers changing the same field. Read the integration diff and coordinate overlapping work before accepting it.
package/dist/examples/integration-branches/package.json CHANGED
@@ -9,10 +9,10 @@
9
9
  "stripe": "17.7.0"
10
10
  },
11
11
  "devDependencies": {
12
- "@volter/world": "3.0.145",
13
- "@volter/world-core": "3.0.145",
14
- "@volter/world-runtime": "3.0.145",
15
- "@volter/world-console": "3.0.140",
12
+ "@volter/world": "3.0.146",
13
+ "@volter/world-core": "3.0.146",
14
+ "@volter/world-runtime": "3.0.146",
15
+ "@volter/world-console": "3.0.141",
16
16
  "@volter/twin-stripe": "3.0.2"
17
17
  }
18
18
  }
package/dist/examples/workplace-agent/README.md CHANGED
@@ -13,18 +13,18 @@ You need Node 22.6+, npm and registry access during installation. No platform ac
13
13
  ## Prepare an ordinary workplace
14
14
 
15
15
  ```console
16
- $ npx @volter/world@3.0.145 example workplace-agent --dir workplace
16
+ $ npx @volter/world@3.0.146 example workplace-agent --dir workplace
17
17
  $ cd workplace
18
18
  $ npm install
19
- $ npx volter world init --name workplace --twins github,linear,slack
19
+ $ ./node_modules/.bin/volter world init --name workplace --twins github,linear,slack
20
20
  ```
21
21
 
22
22
  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.
23
23
 
24
24
  ```console
25
- $ npx volter world up
26
- $ npx volter world clock set 2026-01-15T12:00:00Z
27
- $ npx volter world run -- node seed.mjs
25
+ $ ./node_modules/.bin/volter world up
26
+ $ ./node_modules/.bin/volter world clock set 2026-01-15T12:00:00Z
27
+ $ ./node_modules/.bin/volter world run -- node seed.mjs
28
28
  ```
29
29
 
30
30
  [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.
@@ -32,10 +32,10 @@ $ npx volter world run -- node seed.mjs
32
32
  ## Complete a handoff
33
33
 
34
34
  ```console
35
- $ npx volter world run -- node handoff.mjs
36
- $ npx volter world run -- node operate.mjs read
37
- $ npx volter world log
38
- $ npx volter world diff
35
+ $ ./node_modules/.bin/volter world run -- node handoff.mjs
36
+ $ ./node_modules/.bin/volter world run -- node operate.mjs read
37
+ $ ./node_modules/.bin/volter world log
38
+ $ ./node_modules/.bin/volter world diff
39
39
  ```
40
40
 
41
41
  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.
@@ -45,7 +45,7 @@ Read the ticket's title, priority and team, then the channel and posted source/t
45
45
  Install the World skill and MCP tools into your agent's configuration:
46
46
 
47
47
  ```console
48
- $ npx volter agents install
48
+ $ ./node_modules/.bin/volter agents install
49
49
  ```
50
50
 
51
51
  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:
@@ -59,23 +59,23 @@ The agent uses the same public SDKs as [clients.mjs](./clients.mjs); the [coding
59
59
  Archive the channel, then create another source issue:
60
60
 
61
61
  ```console
62
- $ npx volter world run -- node operate.mjs archive
63
- $ npx volter world run -- node operate.mjs issue
62
+ $ ./node_modules/.bin/volter world run -- node operate.mjs archive
63
+ $ ./node_modules/.bin/volter world run -- node operate.mjs issue
64
64
  ```
65
65
 
66
66
  Use the returned issue number in both commands below:
67
67
 
68
68
  ```console
69
- $ npx volter world run -- node handoff.mjs <issue-number>
70
- $ npx volter world run -- node operate.mjs read <issue-number>
69
+ $ ./node_modules/.bin/volter world run -- node handoff.mjs <issue-number>
70
+ $ ./node_modules/.bin/volter world run -- node operate.mjs read <issue-number>
71
71
  ```
72
72
 
73
73
  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:
74
74
 
75
75
  ```console
76
- $ npx volter world run -- node operate.mjs unarchive
77
- $ npx volter world run -- node handoff.mjs <issue-number>
78
- $ npx volter world run -- node operate.mjs read <issue-number>
76
+ $ ./node_modules/.bin/volter world run -- node operate.mjs unarchive
77
+ $ ./node_modules/.bin/volter world run -- node handoff.mjs <issue-number>
78
+ $ ./node_modules/.bin/volter world run -- node operate.mjs read <issue-number>
79
79
  ```
80
80
 
81
81
  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.
@@ -98,9 +98,9 @@ Personal repositories use GitHub's ordinary create-repository API. Organization
98
98
  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:
99
99
 
100
100
  ```console
101
- $ npx volter world run -- node create-organization.mjs
101
+ $ ./node_modules/.bin/volter world run -- node create-organization.mjs
102
102
  ```
103
103
 
104
104
  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.
105
105
 
106
- 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.
106
+ Stop with `./node_modules/.bin/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/dist/examples/workplace-agent/package.json CHANGED
@@ -11,10 +11,10 @@
11
11
  "@slack/web-api": "7.19.0"
12
12
  },
13
13
  "devDependencies": {
14
- "@volter/world": "3.0.145",
15
- "@volter/world-core": "3.0.145",
16
- "@volter/world-runtime": "3.0.145",
17
- "@volter/world-console": "3.0.140",
14
+ "@volter/world": "3.0.146",
15
+ "@volter/world-core": "3.0.146",
16
+ "@volter/world-runtime": "3.0.146",
17
+ "@volter/world-console": "3.0.141",
18
18
  "@volter/twin-github": "3.0.6",
19
19
  "@volter/twin-linear": "3.0.4",
20
20
  "@volter/twin-slack": "3.0.5"
package/dist/src/agent-prompt.js CHANGED
@@ -9,7 +9,7 @@ export function agentPrompt(o = {}) {
9
9
  '',
10
10
  o.tools
11
11
  ? '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`.'
12
- : '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`.',
12
+ : '1. Keep the app\'s pinned World tools if present, running `./node_modules/.bin/volter` from the app folder after installing its locked dependencies. A missing local binary stops without fetching another package. Otherwise install the command: `npm install -g @volter/world`. Install the agent tooling with `volter agents install --yes`.',
13
13
  `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')}.`,
14
14
  `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.`,
15
15
  `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'}).`,
package/examples/customer-onboarding/README.md CHANGED
@@ -13,7 +13,7 @@ You need Node 22.6+, npm and registry access during installation. The browser pa
13
13
  Copy this starter into a new folder:
14
14
 
15
15
  ```console
16
- $ npx @volter/world@3.0.145 example customer-onboarding --dir onboarding
16
+ $ npx @volter/world@3.0.146 example customer-onboarding --dir onboarding
17
17
  $ cd onboarding
18
18
  $ npm install
19
19
  ```
@@ -23,7 +23,7 @@ The command copies source; it neither installs dependencies nor starts a World.
23
23
  Read [onboarding.mjs](./onboarding.mjs) for the application and [run.mjs](./run.mjs) for the command entry. Empty keys in [.env.example](./.env.example) tell init what the app reads; init supplies throwaway credentials. Do not add real keys.
24
24
 
25
25
  ```console
26
- $ npx volter world init --name onboarding --twins stripe,resend
26
+ $ ./node_modules/.bin/volter world init --name onboarding --twins stripe,resend
27
27
  ```
28
28
 
29
29
  Review Stripe and Resend's exact sources in `.volter/world.json`. The `pg` dependency and `DATABASE_URL` also request a managed PostgreSQL service. Keep it: this app needs SQL. SaaS selection does not exclude a declared native database. `world covers` describes the configured database as part of this workflow.
@@ -31,12 +31,12 @@ Review Stripe and Resend's exact sources in `.volter/world.json`. The `pg` depen
31
31
  ## Create and read an account
32
32
 
33
33
  ```console
34
- $ npx volter world up
35
- $ npx volter world clock set 2026-01-15T12:00:00Z
36
- $ npx volter world run -- node run.mjs create Ada owner@world.test
37
- $ npx volter world clock advance 5s
38
- $ npx volter world run -- node run.mjs read
39
- $ npx volter world log
34
+ $ ./node_modules/.bin/volter world up
35
+ $ ./node_modules/.bin/volter world clock set 2026-01-15T12:00:00Z
36
+ $ ./node_modules/.bin/volter world run -- node run.mjs create Ada owner@world.test
37
+ $ ./node_modules/.bin/volter world clock advance 5s
38
+ $ ./node_modules/.bin/volter world run -- node run.mjs read
39
+ $ ./node_modules/.bin/volter world log
40
40
  ```
41
41
 
42
42
  Read the customer returned by Stripe, the signup row returned by SQL and the email returned by Resend. `completion: complete` means delivery was observed, not merely that a send request was accepted. Opaque IDs can differ between fresh Worlds; customer identity, stored fields and delivery status are the useful outcomes.
@@ -46,25 +46,25 @@ Read the customer returned by Stripe, the signup row returned by SQL and the ema
46
46
  A refusing recipient's mail server creates a bounce after the send was accepted:
47
47
 
48
48
  ```console
49
- $ npx volter world run -- node run.mjs bounce
50
- $ npx volter world run -- node run.mjs create Grace owner@world.test
51
- $ npx volter world clock advance 5s
52
- $ npx volter world run -- node run.mjs read
49
+ $ ./node_modules/.bin/volter world run -- node run.mjs bounce
50
+ $ ./node_modules/.bin/volter world run -- node run.mjs create Grace owner@world.test
51
+ $ ./node_modules/.bin/volter world clock advance 5s
52
+ $ ./node_modules/.bin/volter world run -- node run.mjs read
53
53
  ```
54
54
 
55
55
  Grace's customer and SQL row remain. Her email exists and has `last_event: bounced`; the application reports `partial-email-bounced`. The `bounce` command uses Resend's declared synthetic recipient setting, not a successful-send handler. Restore delivery before later signups:
56
56
 
57
57
  ```console
58
- $ npx volter world run -- node run.mjs deliver
58
+ $ ./node_modules/.bin/volter world run -- node run.mjs deliver
59
59
  ```
60
60
 
61
61
  An unverified sender is refused before an email is accepted:
62
62
 
63
63
  ```console
64
- $ npx volter world run -- node run.mjs refused
65
- $ npx volter world run -- node run.mjs retry
66
- $ npx volter world clock advance 5s
67
- $ npx volter world run -- node run.mjs read
64
+ $ ./node_modules/.bin/volter world run -- node run.mjs refused
65
+ $ ./node_modules/.bin/volter world run -- node run.mjs retry
66
+ $ ./node_modules/.bin/volter world clock advance 5s
67
+ $ ./node_modules/.bin/volter world run -- node run.mjs read
68
68
  ```
69
69
 
70
70
  The first command creates Lin's customer and SQL row, then records the email refusal. The second resumes that pending welcome on the same customer. It refuses to resend an email that already has an accepted ID. These application receipts do not guarantee exactly-once delivery after an ambiguous network failure; resolve acceptance before retrying an uncertain send.
@@ -80,7 +80,7 @@ $ node prepare-ui.mjs
80
80
  Then start the app through the World:
81
81
 
82
82
  ```console
83
- $ npx volter world run -- node server.mjs
83
+ $ ./node_modules/.bin/volter world run -- node server.mjs
84
84
  ```
85
85
 
86
86
  Open the printed app URL in your browser. Submit a signup, advance the World clock in another terminal and reload. The page shows the completion state and full stored outcome. Its server registers its app URL with the World after listening; consumers can discover it with `world app-url`.
@@ -88,8 +88,8 @@ Open the printed app URL in your browser. Submit a signup, advance the World clo
88
88
  To open the World dashboard, stop the app with Ctrl-C first, then switch the owned compute to the viewer:
89
89
 
90
90
  ```console
91
- $ npx volter world down
92
- $ npx volter world view --no-open
91
+ $ ./node_modules/.bin/volter world down
92
+ $ ./node_modules/.bin/volter world view --no-open
93
93
  ```
94
94
 
95
95
  The viewer prints the dashboard URL and keeps running. Start `world run -- node server.mjs` in a second terminal if you want the application alongside it. Open **Stripe** under **Records**, then select the customer to inspect its name, email and stored ID. Open **Resend** to inspect the accepted email and delivery event. **Board** opens the vendor pages declared by the installed twin; its root workspace may cover settings rather than customers. Provisioning remains in full history even when hidden from the business-activity view. Read the application's SQL completion record with `run.mjs read` or its browser page.
package/examples/customer-onboarding/package.json CHANGED
@@ -11,10 +11,10 @@
11
11
  "pg": "8.16.3"
12
12
  },
13
13
  "devDependencies": {
14
- "@volter/world": "3.0.145",
15
- "@volter/world-core": "3.0.145",
16
- "@volter/world-runtime": "3.0.145",
17
- "@volter/world-console": "3.0.140",
14
+ "@volter/world": "3.0.146",
15
+ "@volter/world-core": "3.0.146",
16
+ "@volter/world-runtime": "3.0.146",
17
+ "@volter/world-console": "3.0.141",
18
18
  "@volter/twin-stripe": "3.0.2",
19
19
  "@volter/twin-resend": "1.0.1"
20
20
  }
package/examples/integration-branches/README.md CHANGED
@@ -13,21 +13,21 @@ Give two workers the same Stripe baseline, let them change different existing cu
13
13
  Use an empty parent folder. Create the baseline starter there:
14
14
 
15
15
  ```console
16
- $ npx @volter/world@3.0.145 example integration-branches --dir baseline
16
+ $ npx @volter/world@3.0.146 example integration-branches --dir baseline
17
17
  $ cd baseline
18
18
  $ npm install
19
- $ npx volter world init --name baseline --twins stripe
19
+ $ ./node_modules/.bin/volter world init --name baseline --twins stripe
20
20
  ```
21
21
 
22
22
  Review the selected vendor, then create Ada and Grace through the SDK:
23
23
 
24
24
  ```console
25
- $ npx volter world up
26
- $ npx volter world clock set 2026-01-15T12:00:00Z
27
- $ npx volter world run -- node customer.mjs create Ada
28
- $ npx volter world run -- node customer.mjs create Grace
29
- $ npx volter world run -- node customer.mjs read
30
- $ npx volter world down
25
+ $ ./node_modules/.bin/volter world up
26
+ $ ./node_modules/.bin/volter world clock set 2026-01-15T12:00:00Z
27
+ $ ./node_modules/.bin/volter world run -- node customer.mjs create Ada
28
+ $ ./node_modules/.bin/volter world run -- node customer.mjs create Grace
29
+ $ ./node_modules/.bin/volter world run -- node customer.mjs read
30
+ $ ./node_modules/.bin/volter world down
31
31
  $ cd ..
32
32
  ```
33
33
 
@@ -38,9 +38,9 @@ The stopped baseline retains its history and can supply local path remotes. Defa
38
38
  Create three more copies in the same parent folder:
39
39
 
40
40
  ```console
41
- $ npx @volter/world@3.0.145 example integration-branches --dir integration
42
- $ npx @volter/world@3.0.145 example integration-branches --dir worker-a
43
- $ npx @volter/world@3.0.145 example integration-branches --dir worker-b
41
+ $ npx @volter/world@3.0.146 example integration-branches --dir integration
42
+ $ npx @volter/world@3.0.146 example integration-branches --dir worker-a
43
+ $ npx @volter/world@3.0.146 example integration-branches --dir worker-b
44
44
  ```
45
45
 
46
46
  In `integration`, then `worker-a`, then `worker-b`, install dependencies and initialize with the folder's name. Before a first boot or app write, link and pull the baseline:
@@ -48,10 +48,10 @@ In `integration`, then `worker-a`, then `worker-b`, install dependencies and ini
48
48
  ```console
49
49
  $ cd integration
50
50
  $ npm install
51
- $ npx volter world init --name integration --twins stripe
52
- $ npx volter remote add origin ../baseline
53
- $ npx volter world pull
54
- $ npx volter world clock set 2026-01-15T12:00:00Z
51
+ $ ./node_modules/.bin/volter world init --name integration --twins stripe
52
+ $ ./node_modules/.bin/volter remote add origin ../baseline
53
+ $ ./node_modules/.bin/volter world pull
54
+ $ ./node_modules/.bin/volter world clock set 2026-01-15T12:00:00Z
55
55
  $ cd ..
56
56
  ```
57
57
 
@@ -61,12 +61,12 @@ Repeat that block in each worker, replacing both occurrences of `integration` wi
61
61
 
62
62
  ```console
63
63
  $ cd worker-a
64
- $ npx volter world run -- node customer.mjs rename Ada Ada-worker-A
65
- $ npx volter world changeset worker-a-change -m "Worker A renames Ada"
66
- $ npx volter remote add integration ../integration
67
- $ npx volter world push worker-a-change --remote integration
68
- $ npx volter world run -- node receipt.mjs
69
- $ npx volter world down
64
+ $ ./node_modules/.bin/volter world run -- node customer.mjs rename Ada Ada-worker-A
65
+ $ ./node_modules/.bin/volter world changeset worker-a-change -m "Worker A renames Ada"
66
+ $ ./node_modules/.bin/volter remote add integration ../integration
67
+ $ ./node_modules/.bin/volter world push worker-a-change --remote integration
68
+ $ ./node_modules/.bin/volter world run -- node receipt.mjs
69
+ $ ./node_modules/.bin/volter world down
70
70
  $ cd ..
71
71
  ```
72
72
 
@@ -76,19 +76,19 @@ The delivery receipt names integration. The worker's tracked `origin` still name
76
76
 
77
77
  ```console
78
78
  $ cd worker-b
79
- $ npx volter world run -- node customer.mjs rename Grace Grace-worker-B
80
- $ npx volter world changeset worker-b-change -m "Worker B renames Grace"
81
- $ npx volter remote add integration ../integration
82
- $ npx volter world push worker-b-change --remote integration
83
- $ npx volter world down
79
+ $ ./node_modules/.bin/volter world run -- node customer.mjs rename Grace Grace-worker-B
80
+ $ ./node_modules/.bin/volter world changeset worker-b-change -m "Worker B renames Grace"
81
+ $ ./node_modules/.bin/volter remote add integration ../integration
82
+ $ ./node_modules/.bin/volter world push worker-b-change --remote integration
83
+ $ ./node_modules/.bin/volter world down
84
84
  $ cd ../integration
85
- $ npx volter world run -- node customer.mjs read
86
- $ npx volter world run -- node receipt.mjs
87
- $ npx volter world down
85
+ $ ./node_modules/.bin/volter world run -- node customer.mjs read
86
+ $ ./node_modules/.bin/volter world run -- node receipt.mjs
87
+ $ ./node_modules/.bin/volter world down
88
88
  $ cd ../baseline
89
- $ npx volter world up
90
- $ npx volter world run -- node customer.mjs read
91
- $ npx volter world down
89
+ $ ./node_modules/.bin/volter world up
90
+ $ ./node_modules/.bin/volter world run -- node customer.mjs read
91
+ $ ./node_modules/.bin/volter world down
92
92
  ```
93
93
 
94
94
  Integration holds the two renamed customers. Baseline still holds Ada and Grace. This example deliberately changes distinct records. A named delivery binds to the destination head it reads and refuses a concurrent move; it does not provide an automatic semantic merge for two workers changing the same field. Read the integration diff and coordinate overlapping work before accepting it.
package/examples/integration-branches/package.json CHANGED
@@ -9,10 +9,10 @@
9
9
  "stripe": "17.7.0"
10
10
  },
11
11
  "devDependencies": {
12
- "@volter/world": "3.0.145",
13
- "@volter/world-core": "3.0.145",
14
- "@volter/world-runtime": "3.0.145",
15
- "@volter/world-console": "3.0.140",
12
+ "@volter/world": "3.0.146",
13
+ "@volter/world-core": "3.0.146",
14
+ "@volter/world-runtime": "3.0.146",
15
+ "@volter/world-console": "3.0.141",
16
16
  "@volter/twin-stripe": "3.0.2"
17
17
  }
18
18
  }
package/examples/workplace-agent/README.md CHANGED
@@ -13,18 +13,18 @@ You need Node 22.6+, npm and registry access during installation. No platform ac
13
13
  ## Prepare an ordinary workplace
14
14
 
15
15
  ```console
16
- $ npx @volter/world@3.0.145 example workplace-agent --dir workplace
16
+ $ npx @volter/world@3.0.146 example workplace-agent --dir workplace
17
17
  $ cd workplace
18
18
  $ npm install
19
- $ npx volter world init --name workplace --twins github,linear,slack
19
+ $ ./node_modules/.bin/volter world init --name workplace --twins github,linear,slack
20
20
  ```
21
21
 
22
22
  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.
23
23
 
24
24
  ```console
25
- $ npx volter world up
26
- $ npx volter world clock set 2026-01-15T12:00:00Z
27
- $ npx volter world run -- node seed.mjs
25
+ $ ./node_modules/.bin/volter world up
26
+ $ ./node_modules/.bin/volter world clock set 2026-01-15T12:00:00Z
27
+ $ ./node_modules/.bin/volter world run -- node seed.mjs
28
28
  ```
29
29
 
30
30
  [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.
@@ -32,10 +32,10 @@ $ npx volter world run -- node seed.mjs
32
32
  ## Complete a handoff
33
33
 
34
34
  ```console
35
- $ npx volter world run -- node handoff.mjs
36
- $ npx volter world run -- node operate.mjs read
37
- $ npx volter world log
38
- $ npx volter world diff
35
+ $ ./node_modules/.bin/volter world run -- node handoff.mjs
36
+ $ ./node_modules/.bin/volter world run -- node operate.mjs read
37
+ $ ./node_modules/.bin/volter world log
38
+ $ ./node_modules/.bin/volter world diff
39
39
  ```
40
40
 
41
41
  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.
@@ -45,7 +45,7 @@ Read the ticket's title, priority and team, then the channel and posted source/t
45
45
  Install the World skill and MCP tools into your agent's configuration:
46
46
 
47
47
  ```console
48
- $ npx volter agents install
48
+ $ ./node_modules/.bin/volter agents install
49
49
  ```
50
50
 
51
51
  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:
@@ -59,23 +59,23 @@ The agent uses the same public SDKs as [clients.mjs](./clients.mjs); the [coding
59
59
  Archive the channel, then create another source issue:
60
60
 
61
61
  ```console
62
- $ npx volter world run -- node operate.mjs archive
63
- $ npx volter world run -- node operate.mjs issue
62
+ $ ./node_modules/.bin/volter world run -- node operate.mjs archive
63
+ $ ./node_modules/.bin/volter world run -- node operate.mjs issue
64
64
  ```
65
65
 
66
66
  Use the returned issue number in both commands below:
67
67
 
68
68
  ```console
69
- $ npx volter world run -- node handoff.mjs <issue-number>
70
- $ npx volter world run -- node operate.mjs read <issue-number>
69
+ $ ./node_modules/.bin/volter world run -- node handoff.mjs <issue-number>
70
+ $ ./node_modules/.bin/volter world run -- node operate.mjs read <issue-number>
71
71
  ```
72
72
 
73
73
  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:
74
74
 
75
75
  ```console
76
- $ npx volter world run -- node operate.mjs unarchive
77
- $ npx volter world run -- node handoff.mjs <issue-number>
78
- $ npx volter world run -- node operate.mjs read <issue-number>
76
+ $ ./node_modules/.bin/volter world run -- node operate.mjs unarchive
77
+ $ ./node_modules/.bin/volter world run -- node handoff.mjs <issue-number>
78
+ $ ./node_modules/.bin/volter world run -- node operate.mjs read <issue-number>
79
79
  ```
80
80
 
81
81
  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.
@@ -98,9 +98,9 @@ Personal repositories use GitHub's ordinary create-repository API. Organization
98
98
  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:
99
99
 
100
100
  ```console
101
- $ npx volter world run -- node create-organization.mjs
101
+ $ ./node_modules/.bin/volter world run -- node create-organization.mjs
102
102
  ```
103
103
 
104
104
  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.
105
105
 
106
- 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.
106
+ Stop with `./node_modules/.bin/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/package.json CHANGED
@@ -11,10 +11,10 @@
11
11
  "@slack/web-api": "7.19.0"
12
12
  },
13
13
  "devDependencies": {
14
- "@volter/world": "3.0.145",
15
- "@volter/world-core": "3.0.145",
16
- "@volter/world-runtime": "3.0.145",
17
- "@volter/world-console": "3.0.140",
14
+ "@volter/world": "3.0.146",
15
+ "@volter/world-core": "3.0.146",
16
+ "@volter/world-runtime": "3.0.146",
17
+ "@volter/world-console": "3.0.141",
18
18
  "@volter/twin-github": "3.0.6",
19
19
  "@volter/twin-linear": "3.0.4",
20
20
  "@volter/twin-slack": "3.0.5"
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@volter/world",
3
- "version": "3.0.145",
3
+ "version": "3.0.146",
4
4
  "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.",
5
5
  "keywords": [
6
6
  "volter",
@@ -31,12 +31,12 @@
31
31
  ],
32
32
  "dependencies": {
33
33
  "@modelcontextprotocol/sdk": "^1.30.1",
34
- "@volter/world-core": "3.0.145",
35
- "@volter/world-runtime": "3.0.145",
34
+ "@volter/world-core": "3.0.146",
35
+ "@volter/world-runtime": "3.0.146",
36
36
  "zod": "^4.6.5"
37
37
  },
38
38
  "peerDependencies": {
39
- "@volter/world-console": "3.0.140"
39
+ "@volter/world-console": "3.0.141"
40
40
  },
41
41
  "peerDependenciesMeta": {
42
42
  "@volter/world-console": {
@@ -44,7 +44,7 @@
44
44
  }
45
45
  },
46
46
  "devDependencies": {
47
- "@volter/world-console": "3.0.140"
47
+ "@volter/world-console": "3.0.141"
48
48
  },
49
49
  "bin": {
50
50
  "volter": "dist/src/cli.js"
package/src/agent-prompt.ts CHANGED
@@ -19,7 +19,7 @@ export function agentPrompt(o: AgentPromptOptions = {}): string {
19
19
  '',
20
20
  o.tools
21
21
  ? '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`.'
22
- : '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`.',
22
+ : '1. Keep the app\'s pinned World tools if present, running `./node_modules/.bin/volter` from the app folder after installing its locked dependencies. A missing local binary stops without fetching another package. Otherwise install the command: `npm install -g @volter/world`. Install the agent tooling with `volter agents install --yes`.',
23
23
  `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')}.`,
24
24
  `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.`,
25
25
  `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'}).`,