--- title: "Your first verified fix" description: "Run a real failure, inspect its evidence and verify a source-only repair." canonical: "https://agenttwin.si/docs/quickstart/" --- # Your first verified fix Run a real failure, inspect its evidence and verify a source-only repair. ## What you will accomplish The primary entry point is now: ```sh npx agenttwin init ``` Bare `npx agenttwin` opens the same control menu. From it, review service coverage, select a reviewed world file, run its checks, explore seeded faults, replay the captured failure, verify a source-only patch, and save a trial as a regression. Account connection, reviewed sharing, incident imports and protected CI installation are also menu actions. `npx agenttwin refresh` updates discovery without executing your application. These changes describe the current checkout and require a matching published package for registry `npx` use. A world still needs explicit application files, synthetic starting state and correctness checks. AgentTwin does not automatically infer every business requirement or implement every detected provider. The menu's demo is labeled as an example. Noninteractive init performs discovery only. Seeded exploration currently varies timeout-after-write targets and delays, with an unfaulted control and fresh state for every trial. It does not reproduce OS scheduling. Captured trials preserve checks and application snapshots; replay uses the snapshot, while patch verification runs the current source against the same captured checks. Untriggered faults and unsupported operations remain incomplete. Commit a saved regression to a trusted baseline before requiring it in CI. The commands below are the advanced automation equivalents for a concrete walkthrough. Create a local test world, reproduce a lost-response retry that creates duplicate tickets, fix the application, and rerun the same checks. You need Node.js 22.12 or newer and a terminal. A dashboard account, Docker and cloud credentials are not required for this local example. This guide describes the current checkout. If an installed CLI does not expose `world`, `scenario` or `contracts`, check its version and use the built CLI from this repository. Do not assume an older published package has every capability shown here. ## 1. Generate the example Run from a working directory where AgentTwin can save its local records: ```sh npx agenttwin example --out ./agenttwin-example npx agenttwin contracts --file ./agenttwin-example/reusable.world.json --json ``` The example includes application source, a reusable world specification and `support.scenario.json`. Read the files before execution. The operation matrix establishes which requests the adapters actually support. The primary `agenttwin.world.json` is clean by default. Compare the same source and assertions with and without the fault: ```sh npx agenttwin run --file ./agenttwin-example/agenttwin.world.json --seed 00000000000000000000000000000001 --json npx agenttwin run --file ./agenttwin-example/agenttwin.world.json --fault timeout-after-write --seed 00000000000000000000000000000001 --json ``` Expect exit 0 with one ticket and one notification, then exit 1 with two tickets and a triggered timeout-after-write fault. `--fault none` explicitly disables an active fault; `--fault ` selects a declared `faults` preset or the active fault type, and `--fault configured` selects the active fault. Unconfigured selections are rejected. Verification needs the same selection (for example `verify --file RECEIPT --world ./agenttwin-example/agenttwin.world.json --fault timeout-after-write`); replay automatically uses the effective world saved beside its receipt. No assertions change between the two runs. The separate `reusable.world.json` used below retains the active fault for the lifecycle and application-repair walkthrough. ## 2. Save the baseline and create a world ```sh npx agenttwin scenario save --file ./agenttwin-example/support.scenario.json --json npx agenttwin world create --file ./agenttwin-example/reusable.world.json --scenario support_retry@1 --ttl 3600 --json ``` Keep the returned world ID. Endpoints and generated credentials belong to this test world. Keep credentials private. The services run on loopback; the application runs on your computer, with host filesystem and network access. ## 3. Reproduce and inspect ```sh npx agenttwin world run --id WORLD_ID --json npx agenttwin receipt --id RUN_ID --json ``` Replace the uppercase placeholders with returned IDs. The first run is expected to fail: the ticket write commits, its response is delayed, and a retry without a stable idempotency key creates another ticket. Find the expected one-ticket outcome, actual two-ticket count and ordered service events. An intentional failed test is useful evidence, not a setup error. ## 4. Patch application source only Open `agenttwin-example/workflow.mjs`. The generated example contains a `safe` flag: set its assignment to `const safe = true` to activate the stable-key request and retry. Review that code to understand the repair. In your own application, implement the same behavior in the actual retry path rather than adding an example flag. Leave the world specification, assertions and scenario version unchanged. Reusing the same baseline makes the before/after comparison meaningful. ```sh npx agenttwin world run --id WORLD_ID --json npx agenttwin receipt --id NEW_RUN_ID --json npx agenttwin verify --file .agenttwin/runs/NEW_RUN_ID/run.json --world ./agenttwin-example/reusable.world.json --scenario support_retry@1 --json ``` Expect one ticket, one notification and unchanged customer records. Check that the source digest changed while specification and scenario digests stayed fixed. Verification recomputes evidence and checks freshness; it is not independent execution attestation. ## 5. Inspect in the dashboard and clean up Open [Runs](/dashboard/) and import the broken and fixed `run.json` receipts, or connect your account and use `npx agenttwin sync`. Manual imports stay in the browser session. Compare final state, checks and recorded steps, not just the green status. ```sh npx agenttwin world teardown --id WORLD_ID --json ``` Teardown closes the world endpoints. Keep receipts as evidence. Next, [prepare your own workflow](/docs/preparation/) or read about [scenario versions](/docs/scenarios/).