@walkeros/cli 4.0.0-next-1773967844643 → 4.0.0-next-1777463920154

package/CHANGELOG.md

@@ -1,6 +1,424 @@
 # @walkeros/cli
 
-## 4.0.0-next-1773967844643
+## 4.0.0-next-1777463920154
+
+### Major Changes
+
+- 0ffb1d3: Remove dead `bundleRemote()` and add OpenAPI drift detection.
+
+  Breaking changes:
+  - Removed `bundleRemote()` export from `@walkeros/cli`. The corresponding
+    `/api/bundle` endpoint was removed from the walkerOS app on 2026-04-08, so
+    this function had been silently broken in production for ~3 weeks. Local
+    bundling via `bundle()` is unaffected.
+  - Removed `remote` and `content` options from the MCP `flow_bundle` tool. The
+    tool now bundles locally only.
+
+  New:
+  - Added `npm run -w @walkeros/cli validate:openapi-spec` script that diffs the
+    checked-in `packages/cli/openapi/spec.json` against the live app's OpenAPI
+    document. Detects drift between the walkerOS-side type contract and the
+    actual API. Wired into PR-time CI, daily cron, and a pre-commit lint-staged
+    hook. All layers are gated on a `WALKEROS_APP_URL` secret and skip silently
+    when unset, so the change ships safely without configuration. To activate:
+    set `WALKEROS_APP_URL` in repo secrets pointing to a deployed app instance.
+
+- 93ea9c4: Event model v4: breaking changes to the `Event`, `Source`, and
+  `Entity` shapes.
+  - `event.id` is now a W3C span_id (16 lowercase hex chars), generated by the
+    collector. Reference: W3C Trace Context (W3C Recommendation, January 2020).
+  - `event.version`, `event.group`, `event.count` are removed.
+  - `source.type` is now the source kind (e.g. `browser`, `gtag`, `mcp`, `cli`).
+    New `source.platform` holds the runtime (`web` | `server` | `app` | ...).
+  - `source.id` and `source.previous_id` are removed.
+  - Browser source now sets `source.url` and `source.referrer`.
+  - MCP source sets `source.tool` per emission. CLI source sets
+    `source.command`.
+  - `Entity.nested` and `Entity.context` are now optional. Root `event.nested`
+    and `event.context` remain required.
+  - Each source self-registers via TypeScript module augmentation of `SourceMap`
+    in `@walkeros/core`.
+  - App-side coordination (`/workspaces/developer/app`) is a follow-up plan, not
+    part of this release. Telemetry from v4 CLI/MCP will not validate against
+    the existing app schema until that follow-up ships.
+  - `Mapping.Rule.skip` is renamed to `Mapping.Rule.silent`. Customer flow.json
+    configs using `skip: true` in mapping rules must rename to `silent: true`.
+    Hard cut: no legacy alias, the field is gone.
+
+- 942a7fe: Flow v4: type redesign and cross-flow references.
+
+  Breaking changes:
+  - Renamed `Flow.Settings` (single-flow shape) to `Flow`. The new
+    `Flow.Settings` is the arbitrary kv-bag inside `Flow.Config` (matches
+    `Destination.Settings` semantics).
+  - Renamed `Flow.Config` (root file shape) to `Flow.Json`.
+  - Removed `Flow.Web` and `Flow.Server`. Replaced by
+    `config.platform: 'web' | 'server'` (a string discriminator).
+  - Renamed `Flow.InlineCode` to `Flow.Code`.
+  - Renamed `Flow.SourceReference` / `DestinationReference` /
+    `TransformerReference` / `StoreReference` to `Flow.Source` / `Destination` /
+    `Transformer` / `Store` (Reference suffix dropped).
+  - Renamed `Flow.ContractEntry` to `Flow.ContractRule`.
+  - Lifted `bundle` and platform fields into the per-flow `config` block.
+  - `flow.json` `version` bumped from 3 to 4. v3 input is rejected (no compat
+    shim).
+
+  New:
+  - `$flow.X.Y` reference resolves to `flows.X.config.Y` in the same file.
+    Useful for linking a web flow's API destination to a server flow's deployed
+    URL without duplicating values.
+  - Per-flow `Flow.Config` block: `{ platform, url, settings, bundle }`.
+  - `walkeros validate` warns on unresolved `$flow.X.Y` (use `--strict` to
+    error). `walkeros bundle` and `walkeros deploy` always error on unresolved
+    refs.
+  - See `docs/migrating/v3-to-v4.mdx` on the website for the manual migration
+    steps. No automated codemod is shipped.
+
+### Minor Changes
+
+- cfc7469: **Breaking — `@walkeros/core`:** `fetchPackage(name, { baseUrl })`
+  now expects the host app to expose the v2 `/api/packages/[name]` endpoint that
+  returns the merged `WalkerOSPackage` shape directly (single round-trip,
+  `?expand=all`). The previous two-fetch pattern (`?path=package.json` +
+  `?path=dist/walkerOS.json`) is removed. Hosts must serve the v2 shape; the
+  offline jsdelivr fallback is unchanged.
+
+  **Feature — CLI/MCP/explorer:** Outbound walkerOS-aware HTTP clients now
+  identify themselves to the configured app origin via
+  `X-Walkeros-Client: walkeros-{cli|mcp}/{version}`. `@walkeros/explorer`
+  exports `setPackageTypesBaseUrl(url?)` so host apps can proxy `.d.ts` through
+  their own origin (used by the walkerOS Tag Manager app to drop the jsdelivr
+  CDN allowance entirely).
+
+- 8e06b1f: **BREAKING:** Unified reference syntax: `$store:id` and
+  `$secret:NAME` now use the dot separator: `$store.id` and `$secret.NAME`.
+
+  The coherent rule across every walkerOS reference is:
+  - **`.`** key or path (resolver looks up or walks what follows)
+  - **`:`** literal value or raw-code payload (resolver uses what follows
+    verbatim)
+
+  `$var.`, `$def.`, `$env.NAME[:default]`, `$contract.`, and `$code:(…)` are
+  unchanged, they already fit the rule.
+
+  Every shipped example, published `walkerOS.json` metadata, doc page, and skill
+  has been updated. A new canonical reference-syntax guide lives at
+  `/docs/guides/reference-syntax`. Regex constants (`REF_VAR`, `REF_DEF`,
+  `REF_ENV`, `REF_CONTRACT`, `REF_STORE`, `REF_SECRET`, `REF_CODE_PREFIX`) are
+  exported from `@walkeros/core` import these instead of hand-rolling regexes.
+
+  ### Upgrade
+
+  Search-and-replace across your flow configs:
+
+  ```
+  $store:<id>      → $store.<id>
+  $secret:<NAME>   → $secret.<NAME>
+  ```
+
+  Everything else stays the same. Your `$var.*`, `$def.*`, `$env.*`,
+  `$contract.*`, and `$code:*` references need no changes.
+
+### Patch Changes
+
+- 6422b9b: Validate device-code and token responses from the auth server with
+  Zod schemas at the trust boundary in `login/index.ts`. Malformed responses now
+  surface as structured errors instead of being trusted into config writes or
+  browser launches. Replaces the hand-rolled type guards for Items 1 and 3 of
+  the cli-auth feedback review. No public API change.
+- 78b651a: Explicit opt-in anonymous usage telemetry for CLI and MCP. Telemetry
+  is off by default; users opt in with `walkeros telemetry enable` and out with
+  `walkeros telemetry disable`. No persistent identifier is written before
+  opt-in. No ingest endpoint ships in this release: opting in records consent
+  locally; emission begins when a managed endpoint is released. The data
+  contract lives at `packages/cli/src/telemetry/flow.json`.
+- 6422b9b: Add `flowId` filter to CLI `listDeployments` and redesign the MCP
+  `deploy_manage` tool around it.
+
+  **CLI (`@walkeros/cli`):**
+  - `listDeployments({ projectId?, type?, status?, flowId? })` now forwards
+    `flowId` as a query parameter to `GET /api/projects/{id}/deployments`.
+  - New helper `deleteDeploymentByFlowId({ projectId?, flowId, slug? })` deletes
+    the active deployment for a flow, surfacing a `DeploymentAmbiguityError`
+    (code `MULTIPLE_DEPLOYMENTS`, with a `details[]` list) when a flow has more
+    than one active deployment and no slug was supplied.
+
+  **MCP (`@walkeros/mcp`) breaking:**
+  - `deploy_manage`'s `get`, `delete`, and `list` actions now take
+    `{ projectId?, flowId, slug? }`. The old `id` parameter has been removed.
+    `flowId` is required for `get`/`delete` and optional for `list`.
+    Soft-deleted deployments are always excluded.
+  - When a flow has multiple active deployments and `slug` is not provided,
+    `get`/`delete` return a `MULTIPLE_DEPLOYMENTS` error with a `details[]` list
+    of `{ slug, type, status, updatedAt }` entries so the caller can pick one.
+    `deploy` action is unchanged.
+
+- Updated dependencies [93ea9c4]
+- Updated dependencies [942a7fe]
+- Updated dependencies [cfc7469]
+- Updated dependencies [8e06b1f]
+- Updated dependencies [3d50dd6]
+  - @walkeros/core@4.0.0-next-1777463920154
+  - @walkeros/collector@4.0.0-next-1777463920154
+  - @walkeros/server-destination-api@4.0.0-next-1777463920154
+  - @walkeros/server-core@4.0.0-next-1777463920154
+
+## 3.4.2
+
+### Patch Changes
+
+- 2d25eda: Replace `api` mega-tool with four focused management tools: `auth`
+  (device code login), `project_manage`, `flow_manage`, and `deploy_manage`.
+  Enforce strict CLI/MCP separation of concern — MCP no longer reads config
+  files or checks env vars directly. All tools are always registered regardless
+  of auth state.
+
+  CLI exports new functions: `requestDeviceCode`, `pollForToken`,
+  `setDefaultProject`, `getDefaultProject`, `listAllFlows`,
+  `setFeedbackPreference`, `getFeedbackPreference`, `resolveToken`,
+  `deleteConfig`.
+
+  Preview CRUD (`preview_list`, `preview_get`, `preview_create`,
+  `preview_delete`) is now part of `flow_manage` — previews are a flow-scoped
+  concern and belong alongside the flow lifecycle actions rather than in a
+  separate tool.
+
+- cb4c069: Runtime fetchers (`fetchConfig`, `fetchSecrets`) now classify 401/403
+  responses from the app as a typed `RunnerAuthError` with a structured `reason`
+  (`'unauthorised' | 'flow' | 'scope' | 'forbidden'`) and the app's error `code`
+  (`FORBIDDEN_FLOW` / `FORBIDDEN_SCOPE`). Callers can log a specific reason
+  instead of a generic "token may have expired" message, and exit cleanly rather
+  than retry on scope/flow mismatches.
+  - @walkeros/core@3.4.2
+  - @walkeros/server-core@3.4.2
+
+## 3.4.1
+
+### Patch Changes
+
+- caea905: Add `walkeros previews {list|get|create|delete}` commands for
+  managing preview bundles. `create` supports `--flow <name>` or
+  `--settings-id <id>` to target a flow settings entry, and `--url <siteUrl>` to
+  produce a ready-to-open activation URL. Use `--open` to launch it in your
+  default browser.
+- caea905: Preview preflight now self-heals when a preview bundle is deleted.
+  Instead of injecting the preview script directly and letting it 404, the
+  preflight does a `fetch(HEAD)` first. If the bundle is missing, it clears the
+  `elbPreview` cookie and loads the production walker, so visitors never see
+  silent analytics breakage.
+- Updated dependencies [12adf24]
+- Updated dependencies [75aa26b]
+  - @walkeros/core@3.4.1
+  - @walkeros/server-core@3.4.1
+
+## 3.4.0
+
+### Minor Changes
+
+- 1a0f8f2: Add `target` option to `bundle()`:
+  `cdn | cdn-skeleton | runner | simulate | push`. Replaces
+  `buildOverrides.skipWrapper` (deprecated) to stop dev schemas leaking into
+  production CDN bundles. Stage 2 entry generators gain `platform` option and
+  inject `env.window`/`env.document` for browser targets, fixing
+  `window.elbLayer` in deployed walker.js.
+- 9f97bdd: Clients now send `User-Agent`, `X-WalkerOS-Client`, and
+  `X-WalkerOS-Client-Version` on every request to the walkerOS app. When the app
+  returns `426 Upgrade Required`, the CLI prints the required version + upgrade
+  instruction and exits with code 2; the MCP surfaces the same info in tool
+  errors. Set `WALKEROS_CLIENT_TYPE=runner` to have the CLI binary identify as a
+  long-lived runner instead of an interactive CLI (used by the runtime image so
+  runners are distinguishable from interactive sessions).
+
+### Patch Changes
+
+- Updated dependencies [74940cc]
+- Updated dependencies [525f5d9]
+  - @walkeros/core@3.4.0
+  - @walkeros/server-core@3.4.0
+
+## 3.3.1
+
+### Patch Changes
+
+- 62f6a38: Force collector.run=true during push and simulate so flows with
+  run:false work in CLI
+  - @walkeros/server-core@3.3.1
+  - @walkeros/core@3.3.1
+
+## 3.3.0
+
+### Minor Changes
+
+- 2849acb: **BREAKING CHANGE:** The `packages` block has moved from
+  `flow.<name>.packages` to `flow.<name>.bundle.packages`. Flow files using the
+  old shape fail fast with a migration error pointing to the new location.
+
+  Also adds `flow.<name>.bundle.overrides` — a `Record<string, string>` for
+  pinning transitive dependency versions, matching npm's `overrides` semantics.
+  Use this to resolve version conflicts when a transitive dependency's declared
+  range conflicts with another required version in the same tree (the original
+  motivating case: `@amplitude/engagement-browser` pins
+  `@amplitude/analytics-types@^1.0.0` while `@amplitude/analytics-browser`
+  transitively requires `analytics-types@2.11.1` exact — previously an
+  unresolvable bundler conflict).
+
+  **Migration:** move the existing `packages` block one level deeper into a new
+  `bundle` wrapper.
+
+  ```diff
+    {
+      "version": 3,
+      "flows": {
+        "default": {
+          "web": {},
+  -       "packages": {
+  -         "@walkeros/collector": {}
+  -       },
+  +       "bundle": {
+  +         "packages": {
+  +           "@walkeros/collector": {}
+  +         }
+  +       },
+          "sources": { },
+          "destinations": { }
+        }
+      }
+    }
+  ```
+
+  **Overrides example:**
+
+  ```json
+  {
+    "flows": {
+      "default": {
+        "web": {},
+        "bundle": {
+          "packages": {
+            "@walkeros/web-destination-amplitude": {}
+          },
+          "overrides": {
+            "@amplitude/analytics-types": "2.11.1"
+          }
+        }
+      }
+    }
+  }
+  ```
+
+  Overrides only substitute **transitive** dependencies during resolution —
+  direct package specs declared in `bundle.packages` always win. Overrides
+  targeting a direct local-path package emit a warning and are ignored. Peer
+  constraint mismatches against the chosen override emit a warning but do not
+  error (the override is an explicit user directive).
+
+- 08c365a: Add preview mode preflight to web bundles
+  - `WrapSkeletonOptions` accepts optional `previewOrigin` and `previewScope`
+    fields
+  - `generateWrapEntry` injects a preflight snippet before `startFlow` when both
+    are set: checks `?elbPreview` param / cookie, loads preview bundle from
+    `{previewOrigin}/preview/{previewScope}/walker.{token}.js`, skips production
+    flow. Zero overhead when preview options are absent.
+  - Input validation rejects path-traversal in `previewScope` and special
+    characters in `previewOrigin`.
+
+- 08c365a: Bundle /dev exports into stage 1 skeleton for environment-agnostic
+  simulation
+  - `/dev` exports from packages are included in the skipWrapper bundle as
+    `__devExports`
+  - Stage 2 production bundles tree-shake dev exports (no size impact)
+  - `prepareFlow()` accepts `Flow.Config` object or pre-built `bundlePath`
+  - Simulate functions read env/createTrigger from bundle instead of filesystem
+
+### Patch Changes
+
+- ae02457: Fix bare filename resolution in bundle command —
+  `walkeros bundle flow.json` now resolves relative to cwd instead of CLI
+  examples directory. Add TTY hint when writing to stdout
+- Updated dependencies [2849acb]
+- Updated dependencies [08c365a]
+- Updated dependencies [08c365a]
+- Updated dependencies [08c365a]
+- Updated dependencies [08c365a]
+  - @walkeros/core@3.3.0
+  - @walkeros/server-core@3.3.0
+
+## 3.2.0
+
+### Minor Changes
+
+- eb865e1: Add chainPath to ingest metadata and support path-specific mocks via
+  --mock destination.ga4.before.redact='...'
+- f007c9f: Wire initConfig.hooks into collector instance. Simulation uses
+  prePush/postDestinationPush hooks for event capture. Hooks are wired by
+  startFlow before events fire.
+- da0b640: Add include/exclude destination filter to collector.push PushOptions.
+  Sources can now control which destinations receive their events. Destination
+  simulation uses the full collector pipeline with include filter, giving
+  production-identical event enrichment, consent, and mapping.
+- a0b019f: Add --snapshot flag to push command for setting up global state
+  before bundle execution
+- 431be04: Refactor bundler to two-step compilation: ESM code compilation +
+  platform wrapper. Config changes no longer require full rebuilds. Production
+  bundles carry zero dev/simulate code.
+- 884527d: Unify simulation for sources, destinations, and transformers through
+  the push command.
+  - All step types simulate via `push` with auto-env loading and call tracking
+  - Add `--simulate transformer.X` to invoke a transformer directly with an
+    event
+  - Before chains run as mandatory preparation; next chains are skipped
+  - Source simulation captures at the collector.push boundary, preserving the
+    full before chain
+  - Hooks (prePush/postDestinationPush) capture events instead of manual
+    overrides
+  - Timer interception flushes setTimeout/setInterval deterministically for
+    async patterns (debounced batches, detached Promise chains)
+  - MCP migrated to the push-based simulation pipeline
+  - Legacy simulate code removed
+
+### Patch Changes
+
+- f55fc1d: Unify duplicated CLI patterns for reliability and consistency
+  - Add unified event validator with graduated levels (strict/standard/minimal)
+  - Fix package resolution in simulate to respect packages.path from flow config
+  - Extract shared readStdinToTempFile utility, remove copy-paste dynamic
+    imports
+  - Standardize duration output to milliseconds (matching MCP schema contract)
+  - Fix temp file cleanup in run command (hot-swap accumulation, shutdown
+    handler)
+  - Fix simulator bare /tmp cleanup bug
+  - Unify URL fetching into shared fetchContentString, eliminate temp file
+    roundtrip
+  - Refactor loadJsonFromSource as thin wrapper around loadJsonConfig
+  - Remove unused downloadFromUrl function
+
+- bbbeba1: Replace externalServer hack with typed sourceSettings override in
+  bundle wrapper
+- 7d1a268: Polyfill fetch and navigator.sendBeacon in JSDOM during web
+  simulation to prevent throws and capture network calls
+- 616b9b2: Resolve transitive dependencies from local path packages
+  automatically
+- 91159be: Support path-based package: references on flow config components
+- 2cc1b54: Support single .ts files and directories without package.json as
+  local packages in flow.json
+- Updated dependencies [eb865e1]
+- Updated dependencies [c0a53f9]
+- Updated dependencies [f007c9f]
+- Updated dependencies [bf2dc5b]
+- Updated dependencies [da0b640]
+  - @walkeros/core@3.2.0
+  - @walkeros/server-core@3.2.0
+
+## 3.1.1
+
+### Patch Changes
+
+- a5d98d2: Fix inline JSON config support in detectInput for MCP tools
+  (flow_simulate, flow_push)
+  - @walkeros/core@3.1.1
+  - @walkeros/server-core@3.1.1
+
+## 3.1.0
 
 ### Minor Changes
 
@@ -35,8 +453,8 @@
 - Updated dependencies [bee8ba7]
 - Updated dependencies [966342b]
 - Updated dependencies [df990d4]
-  - @walkeros/core@4.0.0-next-1773967844643
-  - @walkeros/server-core@4.0.0-next-1773967844643
+  - @walkeros/core@3.1.0
+  - @walkeros/server-core@3.1.0
 
 ## 3.0.2
 

package/README.md

@@ -8,7 +8,7 @@ flows.
 The walkerOS CLI is a developer tool that:
 
 - **Bundles** flow configurations into optimized JavaScript
-- **Simulates** event processing for testing
+- **Simulates** event processing for testing (via `push --simulate`)
 - **Runs** flows locally without Docker daemon
 
 Think of it as your development toolchain for walkerOS - from config to running
@@ -46,7 +46,7 @@ npm install @walkeros/cli
 walkeros bundle flow.json
 
 # Test with simulated events (no real API calls)
-walkeros simulate flow.json --event '{"name":"product view"}'
+walkeros push flow.json --event '{"name":"product view"}' --simulate destination.demo
 
 # Push real events to destinations
 walkeros push flow.json --event '{"name":"product view"}'
@@ -99,41 +99,11 @@ walkeros bundle flow.json --dockerfile Dockerfile.custom
 The output path uses convention-based defaults: `./dist/bundle.mjs` for server,
 `./dist/walker.js` for web.
 
-### simulate
-
-Test event processing with simulated events. The config JSON gets bundled and
-executed with destination mocking.
-
-```bash
-walkeros simulate <config> --event '{"name":"page view"}' [options]
-```
-
-**Options:**
-
-- `-e, --event <json>` - Event to simulate (JSON string, file path, or URL)
-- `--flow <name>` - Flow name for multi-flow configs
-- `-p, --platform <platform>` - Platform override (`web` or `server`)
-- `--json` - Output as JSON
-- `-v, --verbose` - Verbose output
-- `-s, --silent` - Suppress output
-
-**Examples:**
-
-```bash
-# Simulate with config (auto-bundled)
-walkeros simulate examples/web-serve.json \
-  --event '{"name":"page view","data":{"title":"Home"}}' \
-  --json
-
-# Simulate specific flow from multi-flow config
-walkeros simulate flow.json --flow server --event '{"name":"test"}'
-```
-
 ### push
 
-Execute your flow with real API calls to configured destinations. Unlike
-`simulate` which mocks API calls, `push` performs actual HTTP requests. Accepts
-either a config JSON (which gets bundled) or a pre-built bundle.
+Execute your flow with real API calls, or simulate specific steps with
+`--simulate`. Accepts either a config JSON (which gets bundled) or a pre-built
+bundle.
 
 ```bash
 walkeros push <input> --event '<json>' [options]
@@ -149,9 +119,15 @@ The CLI auto-detects the input type by attempting to parse as JSON.
 **Options:**
 
 - `-e, --event <source>` - Event to push (JSON string, file path, or URL)
-  **Required**
+  **Required** (unless simulating a source)
 - `--flow <name>` - Flow name (for multi-flow configs)
 - `-p, --platform <platform>` - Platform override (`web` or `server`)
+- `--simulate <step>` - Simulate a step (repeatable). Mocks the step's push,
+  captures result. Use `destination.NAME` or `source.NAME`.
+- `--mock <step=value>` - Mock a step with a specific return value (repeatable).
+  Use `destination.NAME=VALUE`.
+- `--snapshot <source>` - JS file to eval before execution. Sets global state
+  (`window.dataLayer`, `process.env`, etc.).
 - `--json` - Output results as JSON
 - `-v, --verbose` - Verbose output
 - `-s, --silent` - Suppress output (for CI/CD)
@@ -169,6 +145,19 @@ walkeros push flow.json --event ./events/order.json
 walkeros push flow.json --event https://example.com/sample-event.json
 ```
 
+**Simulation examples:**
+
+```bash
+# Simulate a destination (mock its push, capture API calls)
+walkeros push flow.json -e event.json --simulate destination.ga4
+
+# Simulate a source (capture events, disable all destinations)
+walkeros push flow.json --simulate source.browser
+
+# Mock a destination with a specific return value
+walkeros push flow.json -e event.json --mock destination.ga4='{"status":"ok"}'
+```
+
 **Bundle input:**
 
 ```bash
@@ -179,16 +168,16 @@ walkeros push dist/bundle.mjs --event '{"name":"order complete"}'
 walkeros push dist/bundle.js --platform server --event '{"name":"order complete"}'
 ```
 
-**Push vs Simulate:**
+**Push modes:**
 
-| Feature      | `push`                              | `simulate`         |
-| ------------ | ----------------------------------- | ------------------ |
-| API Calls    | Real HTTP requests                  | Mocked (captured)  |
-| Use Case     | Integration testing                 | Safe local testing |
-| Side Effects | Full (writes to DBs, sends to APIs) | None               |
+| Mode | Flag | API Calls | Use Case |
+| ---- | ---- | --------- | -------- |
+| Real | (none) | Real HTTP requests | Integration testing |
+| Simulate | `--simulate` | Mocked (captured) | Safe local testing |
+| Mock | `--mock` | Returns mock value | Controlled testing |
 
-Use `simulate` first to validate configuration safely, then `push` to verify
-real integrations.
+Use `--simulate` first to validate safely, then push without flags for real
+integrations.
 
 ### run
 
@@ -503,7 +492,7 @@ See [examples/](./examples/) for complete working configurations.
 Use commands programmatically:
 
 ```typescript
-import { bundle, simulate, runCommand } from '@walkeros/cli';
+import { bundle, push, runCommand } from '@walkeros/cli';
 
 // Bundle
 await bundle({
@@ -511,11 +500,18 @@ await bundle({
   stats: true,
 });
 
-// Simulate
-const result = await simulate(
+// Push with simulation
+const result = await push(
+  './flow.json',
+  { name: 'page view', data: { title: 'Test' } },
+  { simulate: ['destination.ga4'], json: true },
+);
+// result.usage = API call tracking data
+
+// Push for real
+await push(
   './flow.json',
   { name: 'page view', data: { title: 'Test' } },
-  { json: true },
 );
 
 // Run
@@ -542,9 +538,10 @@ Try them:
 walkeros bundle examples/server-collect.json --stats
 
 # Simulate
-walkeros simulate \
+walkeros push \
   examples/web-serve.json \
-  --event '{"name":"product view","data":{"id":"P123"}}'
+  --event '{"name":"product view","data":{"id":"P123"}}' \
+  --simulate destination.demo
 
 # Run server
 walkeros run examples/server-collect.json --port 3000
@@ -559,9 +556,10 @@ Typical development cycle:
 vim my-flow.json
 
 # 2. Test with simulation (no real API calls)
-walkeros simulate \
+walkeros push \
   my-flow.json \
   --event '{"name":"product view"}' \
+  --simulate destination.demo \
   --verbose
 
 # 3. Bundle and check stats
@@ -581,7 +579,7 @@ curl -X POST http://localhost:3000/collect \
 ```
 CLI (downloads packages + bundles with esbuild)
  ├─ Bundle → optimized .mjs file
- ├─ Simulate → test bundle with events
+ ├─ Push → execute bundle (with optional --simulate for testing)
  └─ Run → execute bundle with built-in runtime
 ```