agenttwin 0.3.13 → 0.3.14

package/dist/dashboard/assets/next/static/chunks/app/docs/[[...slug]]/{page-9f7b8dca8b973b15.js → page-9130f219b4b02112.js}

@@ -1 +1 @@
-(self.webpackChunk_N_E=self.webpackChunk_N_E||[]).push([[7870],{622:()=>{},4527:(e,t,n)=>{"use strict";n.d(t,{I:()=>i});var a=n(1778);let r={house:"m3 10.5 9-7.5 9 7.5M5.5 9v10.5h13V9M9.5 19.5v-6h5v6",activity:"M3 12h4l3-8 4 16 3-8h4",boxes:"m12 3 4 2v4l-4 2-4-2V5l4-2Zm-6 9 4 2v4l-4 2-4-2v-4l4-2Zm12 0 4 2v4l-4 2-4-2v-4l4-2Z",workflow:"M6 3v12a3 3 0 0 0 3 3h9M6 3 3 6m3-3 3 3m6 9 3 3 3-3","timer-off":"M12 21a8 8 0 1 0 0-16 8 8 0 0 0 0 16Zm0-12v4l-3 2M9 2h6","badge-check":"M12 3l2.2 1.6 2.7-.2.9 2.6 2.2 1.6-1 2.5 1 2.5-2.2 1.6-.9 2.6-2.7-.2L12 21l-2.2-1.6-2.7.2-.9-2.6L4 15.4l1-2.5-1-2.5 2.2-1.6.9-2.6 2.7.2L12 3Zm-2 9 1.6 1.6L15 10",shield:"M12 3l8 3v6c0 5-3.5 8-8 9-4.5-1-8-4-8-9V6l8-3Zm-3 9 2 2 4-4",layout:"M4 4h16v16H4V4Zm0 6h16M10 10v10",map:"m3 6 6-3 6 3 6-3v15l-6 3-6-3-6 3V6Zm6-3v15M15 6v15","mouse-pointer-click":"M9 9v10l2.5-2.5L14 21l1.8-.9-2.4-4.4H17L9 9Z",help:"M12 21a9 9 0 1 0 0-18 9 9 0 0 0 0 18Zm-2-11a2 2 0 1 1 2.9 1.8c-.6.3-.9.8-.9 1.4v.3M12 17h.01","book-open":"M12 5v15M12 5C9 3 5 3 2 4v15c3-1 7-1 10 1M12 5c3-2 7-2 10-1v15c-3-1-7-1-10 1",layers:"m3 8 9-5 9 5-9 5-9-5Zm0 5 9 5 9-5M3 18l9 5 9-5",compass:"M12 21a9 9 0 1 0 0-18 9 9 0 0 0 0 18Zm3.5-12.5-2 5-5 2 2-5 5-2Z","life-buoy":"M12 21a9 9 0 1 0 0-18 9 9 0 0 0 0 18Zm0-6a3 3 0 1 0 0-6 3 3 0 0 0 0 6Zm0-3-6.5-6.5M12 12l6.5 6.5M12 12 5.5 18.5M12 12l6.5-6.5",globe:"M12 21a9 9 0 1 0 0-18 9 9 0 0 0 0 18Zm-9-9h18M12 3c2.5 2.6 3.8 5.6 3.8 9S14.5 18.4 12 21c-2.5-2.6-3.8-5.6-3.8-9S9.5 5.6 12 3Z",calendar:"M4 6h16v14H4V6Zm0 5h16M8 3v4M16 3v4",play:"M8 5v14l11-7L8 5Z",sun:"M12 17a5 5 0 1 0 0-10 5 5 0 0 0 0 10Zm0-14v2M12 19v2M3 12h2M19 12h2M5.6 5.6 7 7M17 17l1.4 1.4M18.4 5.6 17 7M7 17l-1.4 1.4",moon:"M20 13.5A8 8 0 0 1 10.5 4a8 8 0 1 0 9.5 9.5Z",search:"M11 18a7 7 0 1 0 0-14 7 7 0 0 0 0 14Zm5-2 4 4",copy:"M9 9h10v10H9V9ZM5 15V5h10",menu:"M4 7h16M4 12h16M4 17h16",close:"M6 6l12 12M18 6 6 18",chevron:"m9 5 7 7-7 7",sparkles:"m12 3 1.9 5.1L19 10l-5.1 1.9L12 17l-1.9-5.1L5 10l5.1-1.9L12 3Zm7 11.5.9 2.1 2.1.9-2.1.9-.9 2.1-.9-2.1-2.1-.9 2.1-.9.9-2.1Z",history:"M12 21a9 9 0 1 0-9-9m9 0v4m-9 5 1-4 4 1M3 3v5h5","flask-conical":"M9 3h6M10 3v6L4.5 17.5A2 2 0 0 0 6.2 21h11.6a2 2 0 0 0 1.7-3.5L14 9V3M7 15h10",network:"M5 8a2.5 2.5 0 1 0 0-5 2.5 2.5 0 0 0 0 5Zm14 0a2.5 2.5 0 1 0 0-5 2.5 2.5 0 0 0 0 5ZM5 21a2.5 2.5 0 1 0 0-5 2.5 2.5 0 0 0 0 5Zm14 0a2.5 2.5 0 1 0 0-5 2.5 2.5 0 0 0 0 5ZM5 5.5h14M12 5.5V18m-7 0h14m-7 0v-4"};function i(e){let{name:t,className:n}=e;return(0,a.jsx)("svg",{viewBox:"0 0 24 24",width:16,height:16,fill:"none",stroke:"currentColor",strokeWidth:1.7,strokeLinecap:"round",strokeLinejoin:"round","aria-hidden":"true",className:n,children:(0,a.jsx)("path",{d:r[t]||r["book-open"]})})}},4893:(e,t,n)=>{"use strict";n.d(t,{DocsCopyPage:()=>s});var a=n(1778),r=n(5226),i=n(4527);async function o(e){try{var t;if(null==(t=navigator.clipboard)?void 0:t.writeText)return void await navigator.clipboard.writeText(e)}catch(e){}let n=document.createElement("textarea");n.value=e,n.setAttribute("readonly",""),n.style.cssText="position:fixed;top:-9999px;left:-9999px;opacity:0",document.body.appendChild(n);let a=document.getSelection(),r=(null==a?void 0:a.rangeCount)?a.getRangeAt(0):null;n.select();try{if(!document.execCommand("copy"))throw Error("copy_rejected")}finally{n.remove(),r&&a&&(a.removeAllRanges(),a.addRange(r))}}function s(e){let{slug:t,title:n}=e,[s,d]=(0,r.useState)("idle"),c=(0,r.useRef)(void 0);return(0,r.useEffect)(()=>()=>clearTimeout(c.current),[]),(0,a.jsxs)("button",{type:"button",className:"docs-copy-page",onClick:()=>{(async()=>{try{let e=await fetch("index"===t?"/docs/index.md":"/docs/".concat(t,".md"));if(!e.ok)throw Error("unavailable");await o(await e.text()),d("done")}catch(e){d("failed")}clearTimeout(c.current),c.current=setTimeout(()=>d("idle"),2500)})()},title:"Copy ".concat(n," as Markdown"),children:["done"===s?"Copied":"failed"===s?"Copy unavailable":"Copy page",(0,a.jsx)(i.I,{name:"copy"})]})}},6473:()=>{},6804:(e,t,n)=>{Promise.resolve().then(n.bind(n,9694)),Promise.resolve().then(n.bind(n,6862)),Promise.resolve().then(n.bind(n,4893)),Promise.resolve().then(n.t.bind(n,622,23)),Promise.resolve().then(n.t.bind(n,6473,23)),Promise.resolve().then(n.bind(n,1833)),Promise.resolve().then(n.bind(n,6017)),Promise.resolve().then(n.bind(n,6635)),Promise.resolve().then(n.bind(n,2727)),Promise.resolve().then(n.bind(n,8748)),Promise.resolve().then(n.bind(n,6676)),Promise.resolve().then(n.bind(n,4617)),Promise.resolve().then(n.bind(n,7906)),Promise.resolve().then(n.bind(n,9293)),Promise.resolve().then(n.bind(n,9407)),Promise.resolve().then(n.bind(n,4001)),Promise.resolve().then(n.bind(n,2587)),Promise.resolve().then(n.bind(n,3969)),Promise.resolve().then(n.bind(n,3145)),Promise.resolve().then(n.bind(n,378))},6862:(e,t,n)=>{"use strict";n.d(t,{DocsSearchTrigger:()=>R});var a,r=n(1778),i=n(5226),o=n(4527);let s=[{slug:"index",title:"Welcome to AgentTwin",group:"Start here",headingText:"",headingId:"",text:"The handbook from repository discovery to a reproduced failure and a verified application fix."},{slug:"index",title:"Welcome to AgentTwin",group:"Start here",headingText:"Start with your project",headingId:"start-with-your-project",text:"Run this inside your repository with Node.js 22.12 or newer: npx agenttwin init Review the generated discovery. Init can offer an installed OpenCode session; other coding agents can use .agenttwin/AGENT-TASK.md . Analysis identifies candidates, required dependencies and missing inputs. It does not prove a workflow works. Connect your individual AgentTwin account in the dashboard . Run npx agenttwin login , complete the browser connection, then run npx agenttwin sync . Automation can supply AGENTTWIN TOKEN to send reviewed discovery metadata. You can also import .agenttwin/inventory.json manually. Discover, prepare, execute and inspect your actual code. Environment, Workflows, Runs, Settings and the account menu. Supported contracts and remaining gaps. Understand starting state, credentials and sandbox boundaries."},{slug:"index",title:"Welcome to AgentTwin",group:"Start here",headingText:"Coverage is explicit",headingId:"coverage-is-explicit",text:"The runtime supports custom HTTP collections, a bounded Slack API subset, PostgreSQL and Redis. Catalog selection declares a dependency; it does not implement a vendor adapter or create a real provider account. Unsupported behavior must be reviewed before execution. The product covers many workflows, including support, notifications, sales, payments and agent side effects. Refunds are an example, not the product boundary."},{slug:"index",title:"Welcome to AgentTwin",group:"Start here",headingText:"Read the handbook from start to finish",headingId:"read-the-handbook-from-start-to-finish",text:"Chapter What you will learn --- --- First verified fix Execute an example failure and prove a source-only repair Discover and test Move from repository signals to reviewed execution Prepare application code Build an entrypoint, configure twins and review the bundle Reusable worlds Provision, run, reset, extend and clean up Scenarios and fixtures Link synthetic identities and preserve immutable baselines Fidelity Understand operation coverage and provider limitations Safety Choose local or cloud boundaries and review credentials Evidence and retesting Diagnose failures and compare unchanged checks CLI and MCP Find commands, artifacts and coding-agent tools Troubleshooting Resolve setup, account and execution failures For a first-time user, start with the local quickstart before connecting a real project. For an existing workflow, begin with preparation. For a failed run, begin with evidence. The handbook describes current implemented contracts; planned features remain labeled in the roadmap."},{slug:"quickstart",title:"Your first verified fix",group:"Start here",headingText:"",headingId:"",text:"Run a real failure, inspect its evidence and verify a source-only repair."},{slug:"quickstart",title:"Your first verified fix",group:"Start here",headingText:"What you will accomplish",headingId:"what-you-will-accomplish",text:"The primary entry point is now: 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."},{slug:"quickstart",title:"Your first verified fix",group:"Start here",headingText:"1. Generate the example",headingId:"1-generate-the-example",text:"Run from a working directory where AgentTwin can save its local records: 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: 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."},{slug:"quickstart",title:"Your first verified fix",group:"Start here",headingText:"2. Save the baseline and create a world",headingId:"2-save-the-baseline-and-create-a-world",text:"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."},{slug:"quickstart",title:"Your first verified fix",group:"Start here",headingText:"3. Reproduce and inspect",headingId:"3-reproduce-and-inspect",text:"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."},{slug:"quickstart",title:"Your first verified fix",group:"Start here",headingText:"4. Patch application source only",headingId:"4-patch-application-source-only",text:"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. 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."},{slug:"quickstart",title:"Your first verified fix",group:"Start here",headingText:"5. Inspect in the dashboard and clean up",headingId:"5-inspect-in-the-dashboard-and-clean-up",text:"Open Runs 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. npx agenttwin world teardown --id WORLD ID --json Teardown closes the world endpoints. Keep receipts as evidence. Next, prepare your own workflow or read about scenario versions ."},{slug:"status",title:"What works today",group:"Start here",headingText:"",headingId:"",text:"Shipped capabilities, engineering verification and remaining limitations."},{slug:"status",title:"What works today",group:"Start here",headingText:"Remaining gaps",headingId:"remaining-gaps",text:"Arbitrary vendor API compatibility, real third-party account provisioning, native macOS execution, universal workflow extraction and unattended repairs are not implemented. Reviewed local Chromium recipes, bounded background completion, immutable incident regressions and a protected PR check template are available. Protected browser/background and PostgreSQL/Redis CI execution remain unsupported. Coding-agent analysis still needs reviewed invocation, fixtures and outcome expectations. The API uses a single-instance durable disk store. Distributed scheduling, billing, deletion reconciliation and complete production monitoring remain work to do."},{slug:"status",title:"What works today",group:"Start here",headingText:"Verification and data",headingId:"verification-and-data",text:"Engineering checks passed hosted execution, configured PostgreSQL/Redis assertions, account isolation/revocation, cancellation and persistence. The verified October 14 checkout passed 151 CLI tests and 17 web evidence tests. The guided npx agenttwin init control menu adds seeded timeout-after-write exploration, captured-source replay, unchanged-check patch verification and saved trial regressions. Seeds control fault selection and delays, not OS scheduling; public npx use requires the updated package to be published. Official Stripe SDK calls, runtime observation, Chromium recipes, background completion, incident imports and CI installation are covered. A real Docker check reproduced duplicate writes, passed the patched commit with unchanged checks, and ignored candidate changes to the grading specification. The packaged MCP loop reproduced duplicate writes, patched only source, reran unchanged checks, verified the receipt and exercised reset, extension and teardown. The October 18 source increment (0.3.8, not yet npm latest when checked October 19) adds thirteen vendored HTTP twins (GitHub, Linear, Notion, HubSpot, Shopify, Datadog, Gmail, Google Calendar, GitLab, Jira, Discord, Twilio, Zendesk), client-side seeded runs with exact replay , seed-matrix verdicts, the bounded shrink bisection, blackhole/server-error/duplicate-write fault classes, named property checks, and the public docs v1/ai/search endpoint; 348 CLI tests and a clean typecheck cover the release. Dashboard checks verified saved preferences, account connect/disconnect and full-width sidebar collapse on desktop and mobile. These checks are not customer adoption evidence or proof of production equivalence. The production dashboard starts with an empty inventory and receipt list. The separate prototype uses fictional scenarios; its outcomes are scripted."},{slug:"status",title:"What works today",group:"Start here",headingText:"Latest integration verification",headingId:"latest-integration-verification",text:"Main commit 79cbcd3 combines returning-user onboarding and project removal with organization SSO/Keycloak work. Its CLI and docs GitHub checks passed. Combined local verification passed 358 CLI tests (including a browser-suite rerun after installing Chromium), 17 web tests, production builds and browser onboarding/project-removal checks. Commit 3328277 adds shared-context automation with six passing focused tests and a successful GitHub metadata sync. These are recorded engineering results; this documentation update did not rerun those suites. Live OAuth/OTP acceptance, deployment provenance, clean npm onboarding and a complete real pilot remain separate gates."},{slug:"concepts",title:"Worlds, twins, and replicas",group:"Start here",headingText:"",headingId:"",text:"The vocabulary behind AgentTwin: worlds, service twins, replicas, baselines, and regression artifacts."},{slug:"concepts",title:"Worlds, twins, and replicas",group:"Start here",headingText:"Core vocabulary",headingId:"core-vocabulary",text:"Term Meaning --- --- World A set of service twins plus the shared entities and events that link them. Twin A service stand-in that implements the subset of provider behavior a workflow depends on. Replica A disposable, isolated test copy of a world, created from a baseline. Baseline The versioned starting state a run begins from and can be restored to. Fault injection A deterministic failure applied at a chosen point in a run. Manifest The declared coverage of a replica: what is verified, modeled, or unsupported. Regression artifact The saved starting state, fault point, input, and assertions from a reproduced incident."},{slug:"concepts",title:"Worlds, twins, and replicas",group:"Start here",headingText:'Why "world" and not "mock"',headingId:"why-world-and-not-mock",text:"One customer should be the same logical person in a billing system, a CRM, an inbox, and a support tool. A refund can update billing state, emit a webhook, change an internal record, and trigger a notification. A world evaluates that whole chain, not a single endpoint in isolation."},{slug:"concepts",title:"Worlds, twins, and replicas",group:"Start here",headingText:"What makes a world useful",headingId:"what-makes-a-world-useful",text:"- Shared state — related records across services represent the same people, accounts, and business events. - Observable effects — writes and asynchronous events are recorded so a developer can inspect what actually changed. - Repeatability — a baseline can be restored, a run repeated, and time or randomness controlled so failures can be compared. - Branching — one baseline can be explored under several independent scenarios without contaminating the others. - Failure controls — supported faults can occur at meaningful points, including after a service has already applied a write. - Outcome verification — correctness is checked against final world state and invariants, not only the agent's natural-language explanation. - Honest fidelity — each twin should state what is supported, what has been verified, what is unknown, and when verification last ran. Current runs use explicit fixtures, supported service contracts and fresh sandbox provisioning. Automatic shared-identity compilation, coordinated snapshots and control of all clocks or randomness are outside current coverage."},{slug:"concepts",title:"Worlds, twins, and replicas",group:"Start here",headingText:"The agent should not have to know",headingId:"the-agent-should-not-have-to-know",text:"The agent should not have to know whether it is talking to production or a test world beyond the configuration boundary. The developer, however, should always be able to tell which world is active and what that world can faithfully simulate. How a replica publishes its limits: verified, modeled, and unsupported behavior."},{slug:"workflow",title:"Discover, test and retest",group:"Use your application",headingText:"",headingId:"",text:"The usable path from repository discovery to evidence from a CLI or cloud run."},{slug:"preparation",title:"Prepare your actual application",group:"Use your application",headingText:"",headingId:"",text:"Turn a discovered candidate into an executable, reviewed test bundle."},{slug:"preparation",title:"Prepare your actual application",group:"Use your application",headingText:"Discovery is the starting point",headingId:"discovery-is-the-starting-point",text:"Run npx agenttwin init inside your application repository. Review .agenttwin/inventory.json and the workflow candidates. An entrypoint or dependency found in source is a candidate, not proof of provider access or a runnable test. Choose one narrow workflow with observable effects. Identify its built Node entrypoint, required inputs, every service operation, synthetic starting records and expected outputs. Other coding agents can use .agenttwin/AGENT-TASK.md ; discovery does not automatically supply a correct executable test."},{slug:"preparation",title:"Prepare your actual application",group:"Use your application",headingText:"Build and configure the entrypoint",headingId:"build-and-configure-the-entrypoint",text:"The runtime does not transpile TypeScript or install application dependencies. Bundle them first and list the required built files. command is an argv array beginning with node . Application file paths resolve relative to the world specification. Configure test clients with generated AGENTTWIN URL and AGENTTWIN TOKEN values. A production SDK requires a supported base-URL override and supported operations; merely replacing a token is insufficient. Use synthetic IDs and avoid copying production credentials into the bundle."},{slug:"preparation",title:"Prepare your actual application",group:"Use your application",headingText:"A preparation contract",headingId:"a-preparation-contract",text:'Save this as preparation.json beside your built workflow.mjs . Replace both discovery IDs with the actual IDs in your inventory. This example prepares a Slack notification; it is not a complete Slack replica. { "schema": "agenttwin/preparation-v1", "workflowId": "YOUR DISCOVERED WORKFLOW ID", "world": { "schema": "agenttwin/world-v1", "name": "notification", "files": "workflow.mjs" , "command": "node", "workflow.mjs" , "timeoutSeconds": 20, "services": { "name": "slack", "adapter": "slack", "collections": {"path": "/messages", "seed": }, {"path": "/channels", "seed": {"id": "C TEST", "name": "test"} } } , "assertions": {"service": "slack", "path": "/messages", "count": 1} }, "mappings": { "toolId": "YOUR DISCOVERED SLACK TOOL ID", "service": "slack", "contract": "slack", "operations": "chat.postMessage" , "reviewed": true } } Your application must send a message to the seeded channel using the generated connection information. The assertion checks one recorded message; add stronger observable checks appropriate to your workflow. Include every recorded candidate operation in reviewed mappings. Preparation rejects missing or unsupported mappings, but cannot establish that static discovery found every behavior in arbitrary source.'},{slug:"preparation",title:"Prepare your actual application",group:"Use your application",headingText:"Prepare, review, execute",headingId:"prepare-review-execute",text:"npx agenttwin prepare --file preparation.json --out .agenttwin/prepared/notification npx agenttwin contracts --file .agenttwin/prepared/notification/agenttwin.world.json --json npx agenttwin run --file .agenttwin/prepared/notification/agenttwin.world.json --json Preparation copies unchanged listed source and writes the world spec, a SHA-256 manifest and agenttwin.bundle.json . It does not execute the application. Review the upload list, bundled source, fixtures and checks before running or uploading. Local execution supports HTTP collections and bounded Slack operations. PostgreSQL and Redis need explicit cloud execution. In Workflows, select the bundle and review its upload before submitting a cloud job. See execution boundaries ."},{slug:"preparation",title:"Prepare your actual application",group:"Use your application",headingText:"Retest the right files",headingId:"retest-the-right-files",text:"For a one-shot prepared bundle, changing your original source does not update a previously copied bundle: rebuild and prepare again. For a reusable world, every run restages the files listed by that world's specification and resets its baseline. Confirm which files the spec references before patching. Do not make a failing check pass by weakening the outcome or removing the fault. Inspect evidence, patch source and compare receipts under unchanged test conditions. Understand the receipt before approving a repair."},{slug:"dashboard",title:"Dashboard guide",group:"Use your application",headingText:"",headingId:"",text:"Use the environment map, workflows, run evidence and working settings."},{slug:"dashboard",title:"Dashboard guide",group:"Use your application",headingText:"Environment",headingId:"environment",text:"Start with Connect project and npx agenttwin init . Agent-analysis and sync instructions expand when needed. The environment map appears after discovery or explicit resource selection. It shows those resources with logos and coverage labels; no demonstration services are preselected. Drag empty canvas space to pan, drag cards to move them, or use zoom, Reset view and Arrange. Search the selected-resource list to find a tool, inspect its coverage and remove it. Removal can be undone. Manual catalog selection is a declaration, not account access or provisioning. Once connected, Environment shows the project name and resource map. View all workflows opens the complete searchable candidate inventory."},{slug:"dashboard",title:"Dashboard guide",group:"Use your application",headingText:"Workflows",headingId:"workflows",text:"Review discovered entrypoints and dependencies. Prepare workflow creates a preparation task for your coding agent using the selected candidate. Package real application files and reviewed operation mappings with the CLI, then upload the resulting bundle to execute. Saved configurations store fixtures, faults and assertions separately from application files. Candidates with recorded evidence link to their run results."},{slug:"dashboard",title:"Dashboard guide",group:"Use your application",headingText:"Runs",headingId:"runs",text:"Run history contains loaded account results and any run.json files you explicitly import. Filter by repository, workflow or outcome; search by test name, revision or run ID. On phones, use Select test to switch results. Active executions and executions without a loaded receipt appear separately above the history; completed tests are not duplicated there. - Summary identifies the workflow, test configuration, repository, tested revision, runner and command. It explains the result and lists each expected outcome beside its observed value. Failed checks appear first. Failure scenarios show whether an injected condition actually activated. - Recorded steps shows observed service activity in sequence, including writes and activated failures. It is not a complete trace of every application step. - Run history lists other tests of the same workflow and repository. Select a baseline to compare checks, revisions and final collection state. Different test configurations, starting state, source digests or fault settings are highlighted; a comparison does not establish the cause of a regression. - Technical details contains execution output, state changes, runner metadata and the original receipt. Use Copy fix prompt for a failed test or Copy review prompt for a passed test. The task includes the workflow, available source entrypoint, tested revision, checks, recorded activity and output. Give it to your coding agent in the original repository, review the fix, rerun the same test and sync the new receipt. Local CLI execution is the default; use a cloud machine only when needed. You can also preview or download the task, export a result, or export the selected comparison. A passed result covers its recorded checks, not every behavior of the workflow. A failed check explains what differed; the underlying cause may still require inspecting source and logs. Missing repository or Git information is shown as Not recorded , not inferred. Imported files remain in the current browser session and are not uploaded. The API currently lists the latest 100 account jobs; Settings controls how many receipts load per refresh, and later refreshes fetch unloaded receipts."},{slug:"dashboard",title:"Dashboard guide",group:"Use your application",headingText:"Account menu",headingId:"account-menu",text:"Click the initials in the top-right corner to open account actions: Account & settings, View runs and Disconnect account. Connection status reflects the current tab. Escape or a click outside closes the menu. Disconnect is available only when an account is connected."},{slug:"dashboard",title:"Dashboard guide",group:"Use your application",headingText:"Settings",headingId:"settings",text:"Setting Effect --- --- Workspace name Changes the dashboard label and initials in this browser Default execution limit Suggested duration in coding-agent preparation tasks; each reviewed bundle keeps its own execution limit Refresh automatically Polls account discovery and active jobs while the tab is visible; manual Refresh workspace remains available Compact lists Reduces workflow and receipt row spacing Reduce motion Disables transitions and smooth scrolling; system preferences are also respected Account connection API URL, token visibility, Connect account, Refresh workspace and Disconnect Use Save preferences to persist changes or Reset defaults to restore browser preferences. Preferences are not shared team settings. Account tokens stay in memory and are cleared on reload or disconnect; they are not saved with preferences."},{slug:"dashboard",title:"Dashboard guide",group:"Use your application",headingText:"Navigation and storage",headingId:"navigation-and-storage",text:"The top navigation contains Home, Environment, Workflows, Runs and Settings. The logo returns to Home. Home uses the full-width artwork layout. Other views have a collapsible project sidebar; closing it leaves a full-width content column. Narrow screens use the top navigation and a short repository row. Documentation uses a book icon; infrastructure implementation labels do not occupy the sidebar. Manual declarations, map layout and dashboard preferences persist in browser storage. Imported discovery and receipts stay in memory. Synced discovery and submitted run evidence persist on the account’s API store. Sync sends metadata; executing a reviewed bundle uploads the selected application files. No production OAuth session or production account is cloned. Open the dashboard . The compatibility dashboard is available at the API origin ."},{slug:"dashboard",title:"Dashboard guide",group:"Use your application",headingText:"Failure scenarios",headingId:"failure-scenarios",text:"In Workflows → Advanced: saved configurations and failure scenarios → Edit configuration , select healthy execution or Timeout after write , choose a service collection, and set the response delay. Apply the scenario to the draft, save or export it, and rebuild your application bundle before uploading. Previously reviewed bundles are not changed by this editor. Timeout after write commits a write before delaying its response. Your application decides whether to retry. Inspect fault activation and final-state assertions in Runs to detect duplicate effects. Other fault types are not currently implemented. Settings includes a results-per-refresh limit for larger workspaces. Account changes clear transient resource selections, receipts, prepared uploads and upload approval. Server quotas and organization access policies are not browser preferences."},{slug:"dashboard",title:"Dashboard guide",group:"Use your application",headingText:"Guided workflow",headingId:"guided-workflow",text:"Home shows the next action for your connected project, its detected resources, workflow candidates, recent results, active work and failing assertions. The workflow assistant opens from a compact dock at the bottom of Home. The artwork fades behind the workspace and carries “What should your agent test?”. Customize lets you choose which overview cards appear; those choices and your company/name preferences are saved in this browser. Workflows shows ten candidates per page and searches the complete inventory. Selecting a workflow opens a focused preparation guide with a task for your coding agent and the upload step. Saved JSON configurations and failure controls remain under Advanced: saved configurations and failure scenarios . Preparing application files still happens in your repository; dashboard chat cannot do it automatically."},{slug:"dashboard",title:"Dashboard guide",group:"Use your application",headingText:"Repositories and chat",headingId:"repositories-and-chat",text:"Sync each repository with the same AgentTwin account. The sidebar lists synced repositories and the selected repository’s workflow candidates; selecting a repository changes its environment, saved contracts and chat context. Repository names identify inventories, so use distinct names for separate products. Run history currently spans the account. The sidebar is hidden in Settings. Open the chat dock to see its connection status. Connect your account in Settings before sending a message. Chat explains discovery metadata, saved contracts and selected run evidence; use Workflows to prepare and execute code."},{slug:"dashboard",title:"Dashboard guide",group:"Use your application",headingText:"CLI tests and Git activity",headingId:"cli-tests-and-git-activity",text:"Test reviewed bundled Node workflows through npx agenttwin run --file path/to/agenttwin.world.json from the original repository. This uses in-process HTTP twins by default. Review output and fixtures, then run npx agenttwin sync to send discovery, Git metadata and CLI results to the website. CLI execution uses your machine and is not a VM isolation boundary. Select --runtime hosted or --runtime e2b explicitly for a workflow that needs a cloud machine. PostgreSQL and Redis worlds currently require cloud execution. There is no automatic VM provisioning for discovery, chat or dashboard viewing. Home shows recorded test results, adapter activities and failed checks. Git activity shows up to 100 commits from 14 days, total repository commits, branch and HEAD. Changed workflow entrypoint paths are flagged since the previous sync. Runs retain the tested SHA and source digests; older passing tests do not prove a newer commit passes. This does not yet trace transitive changes across every workflow."},{slug:"dashboard",title:"Dashboard guide",group:"Use your application",headingText:"Workflow review",headingId:"workflow-review",text:"Workflows separates discovered code paths from recorded test evidence. Filter by activity, or choose Not tested , Needs attention , Retest changes , or Last test passed . Each card shows its dependencies and preparation needs; expand Source and setup to inspect its entrypoint and open resource setup. Test status only uses receipts with a matching workflow ID and recorded repository. Missing repository context cannot establish coverage. A changed entrypoint or newer Git revision marks a previously passing workflow for retesting. Counts reflect loaded results, not every historical test. Choose Prepare a test to preview, copy or download a task for your coding agent. The task includes the latest recorded result when available. Review the generated files and assertions, run locally, then sync. Expand cloud execution only when the workflow requires a cloud machine."},{slug:"dashboard",title:"Dashboard guide",group:"Use your application",headingText:"Time-of-day artwork",headingId:"time-of-day-artwork",text:"Home artwork spans the full width, extending behind the assistant and project banner before fading at the top of the workspace cards. Its height adjusts with the layout. It uses your browser’s local time: a bay sunrise from 5am–noon, sunny Golden Gate from noon–5pm, and the moonlit coast from 5pm–5am. It checks again when you return to the tab and once a minute while open. No location permission is needed. Customize → Preview background lets you inspect each scene; previews last for this tab session, and new visits use the automatic schedule."},{slug:"stack-loop",title:"From discovery to a verified fix",group:"Use your application",headingText:"",headingId:"",text:"Observe dependencies, run browser and service workflows, preserve incident regressions and verify committed patches."},{slug:"stack-loop",title:"From discovery to a verified fix",group:"Use your application",headingText:"Find dependencies used at runtime",headingId:"find-dependencies-used-at-runtime",text:"Run a reviewed Node application with instrumentation. By default, observed HTTP calls are recorded and blocked before transmission: agenttwin observe -- node app.mjs agenttwin services list --json agenttwin services confirm --host api.stripe.com --decision include agenttwin discover --json A confirmation adds a dependency to inventory; it does not allow requests or install an adapter. To exercise a permitted destination, explicitly pass --allow-host HOST . Observation starts with only PATH and NODE ENV=test ; use repeatable --env-key NAME for environment variables you deliberately want to forward. Request URLs, headers, payloads and application output are omitted from observations. This instruments Node fetch/http/https. Native clients, direct sockets, subprocess traffic and unexercised branches remain outside coverage. It is not an operating-system network sandbox. Discovery also identifies route callbacks and queue handlers as candidates; invocation and business expectations still require review."},{slug:"stack-loop",title:"From discovery to a verified fix",group:"Use your application",headingText:"Account for every service",headingId:"account-for-every-service",text:"After discovery, run agenttwin services coverage --json . Every application dependency appears with its required operations, available provider subset or real engine, limitations, and the next action for missing coverage. Development tooling is excluded. An available adapter does not make the customer workflow verified, and custom collections do not establish vendor compatibility. Build and validate missing operations before claiming complete workflow coverage."},{slug:"stack-loop",title:"From discovery to a verified fix",group:"Use your application",headingText:"Use verified provider operations",headingId:"use-verified-provider-operations",text:"Run agenttwin contracts --json for the operation matrix. Stripe's bounded adapter supports customer create/retrieve/list and payment-intent create/retrieve/confirm, with test payment methods, pagination, idempotency and modeled errors. Slack supports its advertised message/channel/history subset. Custom collections support explicitly defined HTTP operations. Official Stripe SDK conformance tests exercise the supported subset. No real charge is made. Subscriptions, refunds, webhooks, broader object fields and unmodeled parameters are not covered. Unsupported behavior returns 501 and makes the test incomplete."},{slug:"stack-loop",title:"From discovery to a verified fix",group:"Use your application",headingText:"Exercise the application and background work",headingId:"exercise-the-application-and-background-work",text:'A world can include a local browser recipe for a bundled Node server. Install Chromium using npx playwright install chromium from the CLI package directory. Add these fields to a complete reviewed world: { "browser": { "baseUrl": "http://127.0.0.1:4321", "steps": { "action": "goto", "path": "/" }, { "action": "click", "selector": " create-order" }, { "action": "expectText", "selector": " result", "text": "Created" } }, "background": { "service": "orders", "path": "/orders", "count": 1, "timeoutMs": 3000 } } Run with agenttwin run --file agenttwin.world.json --runtime local . The Node server starts, browser actions execute, and the background check waits for matching collection state. Receipts include browser step outcomes and a screenshot when capture succeeds. Browser requests outside the application and configured twins are blocked and recorded as incomplete coverage. Server code still has the local process\'s host access; this is not a VM sandbox. Browser/background recipes currently require local execution. Hosted submissions reject them before queuing a job. Protected Docker approval also returns incomplete for those recipes until its browser runner is implemented. Background checks do not replicate Bull, SQS or arbitrary queue semantics.'},{slug:"stack-loop",title:"From discovery to a verified fix",group:"Use your application",headingText:"Trace failures and validate a repair",headingId:"trace-failures-and-validate-a-repair",text:"Service events from local instrumented execution carry application-reported call sites. agenttwin receipt --id RUN ID --json links those events and stack frames to tested source files, checks source freshness, and produces repair hypotheses. These locations guide investigation; they do not prove a root cause. Patch application code and rerun the same fixtures, fault and outcomes. A suggestion is unvalidated until execution proves it against unchanged checks. The dashboard's Recorded steps view shows reported call sites; Technical details shows available browser evidence."},{slug:"stack-loop",title:"From discovery to a verified fix",group:"Use your application",headingText:"Turn an incident into a permanent regression",headingId:"turn-an-incident-into-a-permanent-regression",text:"Start with a scoped exported incident containing a linked scenario. The repository includes a runnable example in examples/incident-regression . agenttwin incident import --file incident.json --out reviewed-preview.json Review the redacted records and define the intended outcomes in the world. agenttwin regression save --file agenttwin.world.json \\ --id retry safety --incident reviewed-preview.json Redaction preserves matching identities across services. It is heuristic, so review unusual fields and free text before sharing. Import does not connect to production or infer business correctness. Regression definitions are immutable; change their identifier when deliberately changing the contract."},{slug:"stack-loop",title:"From discovery to a verified fix",group:"Use your application",headingText:"Add coding agents and pull requests",headingId:"add-coding-agents-and-pull-requests",text:"agenttwin mcp exposes world lifecycle, incident import, regression saving and protected checks to coding agents. For CI, commit the reviewed regression to a trusted baseline and run: agenttwin regression run \\ --regression .agenttwin/regressions/retry safety.json \\ --revision FULL CANDIDATE SHA --baseline FULL TRUSTED BASELINE SHA \\ --runtime docker --json Checks come from the baseline commit; application files come from the exact candidate commit. The candidate runs in a restricted Docker container without the grading files or Docker socket. Use a reviewed, digest-pinned image through AGENTTWIN RUNNER IMAGE . Docker checks currently support HTTP twins; unsupported infrastructure returns incomplete. Install a customer-repository workflow with separately pinned AgentTwin tooling: agenttwin ci install --tooling-revision FULL REVIEWED AGENTTWIN SHA \\ --regression .agenttwin/regressions/retry safety.json The selected tooling commit must be available on GitHub and contain these commands. The installer creates .github/workflows/agenttwin.yml once, refuses to overwrite a workflow, checks out trusted tooling separately from the application, and fetches the exact candidate commit without executing candidate installation scripts. Configure the reviewed runner image and protect the workflow through repository rules or an organization-required workflow. A template alone cannot make a check mandatory. Local process execution supplies evidence but never grants protected approval. The complete loop is: discover → confirm → prepare → reproduce → patch → rerun unchanged checks → retain the regression on future pull requests."},{slug:"worlds",title:"Reproduce, fix, and retest",group:"Build a test world",headingText:"",headingId:"",text:"Use operation contracts, shared scenarios, reusable worlds and coding-agent tools to verify a source fix."},{slug:"worlds",title:"Reproduce, fix, and retest",group:"Build a test world",headingText:"Check service support",headingId:"check-service-support",text:"agenttwin contracts --file agenttwin.world.json --json The operation matrix lists endpoints, authentication, state changes, errors and limitations for each configured service. Current adapters are custom JSON collections and a bounded Slack subset. Collection services support GET/list and POST/create with idempotency replay. Slack supports chat.postMessage and conversations.list/history through JSON or form bodies. An unmodeled operation or parameter returns HTTP 501 with X-AgentTwin-Unsupported: true , records an unsupported event and makes the test incomplete. It is never forwarded to a production API. Discovery of a provider does not establish a working twin for that provider."},{slug:"worlds",title:"Reproduce, fix, and retest",group:"Build a test world",headingText:"Save a shared scenario",headingId:"save-a-shared-scenario",text:"A scenario supplies the exact starting records across services. Its schema is agenttwin/scenario-v1 ; it contains an id, positive integer version, description, service seeds and optional shared entities. Each entity links selectors that resolve to exactly one seeded record in at least two services. For example, a CRM customer and a Slack support channel can refer to the same customer. agenttwin scenario save --file support.scenario.json --json agenttwin scenario list --json agenttwin scenario show --scenario support retry@1 --json Versions are immutable. Increment the version when fixtures change. Scenario services, adapter types and collection paths must match the world exactly. Receipts include the scenario id, version and content digest. You can also use a saved scenario in a one-shot run: agenttwin run --file agenttwin.world.json --scenario support retry@1 --json"},{slug:"worlds",title:"Reproduce, fix, and retest",group:"Build a test world",headingText:"Reuse a world while fixing source",headingId:"reuse-a-world-while-fixing-source",text:"agenttwin world create --file agenttwin.world.json --scenario support retry@1 --ttl 3600 --json agenttwin world run --id WORLD ID --json agenttwin receipt --id RUN ID --json Replace WORLD ID and RUN ID with the returned identifiers. Creation starts a background host and returns loopback service endpoints and fresh test credentials. The lifecycle is provisioning, ready, running and ready again, ending in terminated, expired or failed. Every run stages the current explicitly listed source files and resets service state to the captured baseline. Patch the original source, then run the same world again. Source digests change; the scenario and world specification remain fixed. If you change the specification or scenario, create another world. agenttwin world status --id WORLD ID --json agenttwin world reset --id WORLD ID --json agenttwin world extend --id WORLD ID --ttl 3600 --json agenttwin world teardown --id WORLD ID --json Reset clears mutable state, idempotency keys, events, delayed responses and fault activation. TTL is 1–86400 seconds; expiration closes the endpoints and interrupts active execution. Control requests require a separate token and reject browser origins. Test credentials are stored in private local session metadata; keep them local. Reusable worlds support local HTTP services. They execute Node code on your machine and provide no host network or filesystem isolation. Use one-shot hosted/E2B execution for an isolated workload or PostgreSQL/Redis. World state is held in memory; recreate a world after its host process is lost."},{slug:"worlds",title:"Reproduce, fix, and retest",group:"Build a test world",headingText:"Check outcomes and unwanted effects",headingId:"check-outcomes-and-unwanted-effects",text:'Existing assertions describe required final-state counts, optionally filtered by record fields. Add forbiddenEffects to reject particular recorded operations and preservedState to protect seeded records: { "forbiddenEffects": {"id": "no customer write", "service": "crm", "path": "/customers", "operation": "write"} , "preservedState": {"id": "keep customers", "service": "crm", "path": "/customers"} } These are fields added to a complete world specification, not a standalone specification. A forbidden-effect selector can use where ; supported operations are write, read and replay. Filtered effects without a recorded payload fail conservatively as an evidence gap. Preserved-state selectors compare matching records from before and after execution. The receipt\'s evaluation separates taskPassed from safe. An unsafe result fails the run even if every required task assertion passed. Checks include state JSON pointers and event sequence numbers. Dashboard failure explanations and fix prompts include these checks. Unsupported behavior remains incomplete, and execution errors remain errors. agenttwin verify --file .agenttwin/runs/RUN ID/run.json --world agenttwin.world.json --scenario support retry@1 --json agenttwin sync Verification checks current source/specification digests and recomputes local evidence. It does not independently attest execution. Sync uses your existing account connection and sends receipts to your dashboard; scenario storage and reusable lifecycle remain local.'},{slug:"worlds",title:"Reproduce, fix, and retest",group:"Build a test world",headingText:"Connect a coding agent",headingId:"connect-a-coding-agent",text:'Start the MCP stdio server from your repository: agenttwin mcp Configure your MCP client with command agenttwin , arguments "mcp" , and the repository as its working directory. The client can discover operation contracts, save/list scenarios, create/list worlds, read status, run a scenario, inspect receipts, reset/extend/teardown a world, and verify a run. The intended sequence is create world → run scenario → inspect run → patch application source → run scenario → verify run. The coding agent performs the patch in the original repository. AgentTwin does not silently rewrite source or weaken tests.'},{slug:"worlds",title:"Reproduce, fix, and retest",group:"Build a test world",headingText:"Try the complete loop",headingId:"try-the-complete-loop",text:"agenttwin example --out ./agenttwin-example agenttwin scenario save --file ./agenttwin-example/support.scenario.json --json agenttwin world create --file ./agenttwin-example/reusable.world.json --scenario support retry@1 --ttl 3600 --json agenttwin world run --id WORLD ID --json The example creates duplicate tickets after a lost response. Inspect its failing receipt, then fix workflow.mjs to use a stable idempotency key on the original request and retry. In this example, replacing the safe flag assignment with const safe = true activates that fix. Rerun the same world: it should contain one ticket and one Slack notification, with unchanged customer records. Keep the specification and scenario intact, verify the new receipt and tear down the world."},{slug:"scenarios",title:"Design reproducible scenarios",group:"Build a test world",headingText:"",headingId:"",text:"Seed linked identities, version fixtures and keep a stable baseline for retests."},{slug:"scenarios",title:"Design reproducible scenarios",group:"Build a test world",headingText:"World versus scenario",headingId:"world-versus-scenario",text:"The world specification defines executable files, command, services, faults and checks. A scenario supplies versioned starting records for those services. The scenario does not replace the application's code or prove provider fidelity. Use a named scenario when several tests need the same customer, order or channel identities. Choose synthetic data that captures the failure conditions. The same identifier alone is not enough: record the relationship and validate that each selector resolves to one record."},{slug:"scenarios",title:"Design reproducible scenarios",group:"Build a test world",headingText:"Complete linked fixture",headingId:"complete-linked-fixture",text:'{ "schema": "agenttwin/scenario-v1", "id": "support customer", "version": 1, "description": "One synthetic customer linked to a support channel", "services": {"name": "crm", "adapter": "json-collection", "collections": {"path": "/customers", "seed": {"id": "customer 1", "channel": "C TEST"} } }, {"name": "slack", "adapter": "slack", "collections": {"path": "/channels", "seed": {"id": "C TEST", "name": "support"} }, {"path": "/messages", "seed": } } , "entities": { "id": "customer 1", "refs": {"service": "crm", "path": "/customers", "where": {"id": "customer 1"}}, {"service": "slack", "path": "/channels", "where": {"id": "C TEST"}} } } The world using this scenario must declare the same services, adapter types and collection paths. Entity references must cover at least two services; zero or multiple matching records are invalid. The shared entity is a validated seed relationship, not automatic ongoing synchronization between unrelated adapters.'},{slug:"scenarios",title:"Design reproducible scenarios",group:"Build a test world",headingText:"Store and reuse",headingId:"store-and-reuse",text:"npx agenttwin scenario save --file support.scenario.json --json npx agenttwin scenario list --json npx agenttwin scenario show --scenario support customer@1 --json npx agenttwin run --file agenttwin.world.json --scenario support customer@1 --json Saving the same version with identical content is repeatable. Saving changed content under that version fails. Increment version when changing seeds, then create a new world for the new baseline. Stored scenarios live under .agenttwin/scenarios/ ; keep the source JSON in version control if the team needs to recreate them elsewhere."},{slug:"scenarios",title:"Design reproducible scenarios",group:"Build a test world",headingText:"Choose useful test data",headingId:"choose-useful-test-data",text:"Start with the smallest fixture that reproduces the incident: one affected identity, the relevant existing records and explicit empty collections for expected new effects. Include boundary conditions deliberately, such as a duplicate key or an existing notification. More synthetic records do not automatically mean better coverage. For a source-fix comparison, keep the same scenario ID, version and digest. For a new business requirement, version the fixture and explain why checks changed. Receipts preserve scenario provenance so these two kinds of comparison can be distinguished. Automatic production-data import, consistent redaction and live cross-service mutation propagation remain additional work. Current fixtures are reviewed files. See reusable worlds for reset and expiry behavior."},{slug:"fidelity",title:"Fidelity contract",group:"Build a test world",headingText:"",headingId:"",text:"Every replica should publish a versioned manifest that labels each operation verified, modeled, or unsupported."},{slug:"fidelity",title:"Fidelity contract",group:"Build a test world",headingText:"What the manifest records",headingId:"what-the-manifest-records",text:"- Provider version the twin was built against. - Fixture source for starting state and seed data. - Last verification date — when the behavior was last compared with reality. - Configuration fields that were captured, and which were not. - State boundaries — what the replica covers and where it ends. - Known differences from the real provider."},{slug:"fidelity",title:"Fidelity contract",group:"Build a test world",headingText:"Evidence, not just a response",headingId:"evidence-not-just-a-response",text:"A passing response cannot hide a bad write. Every run should show: 1. A trace of provider calls and state transitions, in causal order. 2. A before/after state diff across the systems involved. 3. Assertions against final state and invariants , not only the agent's explanation of what it did. The current runtime records operation coverage, source digests, service events and final-state assertions. Custom HTTP collections and the Slack subset have explicit limits; passing their checks does not establish full provider conformance. PostgreSQL and Redis run as real services in the hosted world. Isolated credentials, sanitized records, and disposable execution."},{slug:"safety",title:"Safety and isolation",group:"Build a test world",headingText:"",headingId:"",text:"Current discovery, credential and hosted execution boundaries."},{slug:"safety",title:"Safety and isolation",group:"Build a test world",headingText:"Execution boundary",headingId:"execution-boundary",text:"Application workflows execute in fresh hosted E2B sandboxes, not local containers. The runtime constructs test credentials and an explicit application environment, runs the application as a non-root user, denies new external guest network connections and checks configured final state. Sandbox deletion is requested after execution with a finite TTL backup. Custom HTTP collections and the supported Slack subset never forward to production. No provider-native accounts or production OAuth sessions are provisioned or copied. Browser/macOS application execution is not supported by this backend."},{slug:"safety",title:"Safety and isolation",group:"Build a test world",headingText:"Credentials and uploads",headingId:"credentials-and-uploads",text:"The operator’s E2B key and administrative key stay on the control plane. Users receive individual revocable tokens for their own jobs and discovery. The dashboard never saves account tokens in local storage; disconnect and reload clear tab memory. Discovery sync whitelists reviewed metadata and omits source bodies and credential values. Workflow execution separately uploads explicit reviewed files. Path filtering and generated-secret redaction cannot guarantee that a source file or log contains no sensitive content; review files, fixtures and fix-task evidence before sharing."},{slug:"safety",title:"Safety and isolation",group:"Build a test world",headingText:"Evidence and operating limits",headingId:"evidence-and-operating-limits",text:"A passing receipt verifies configured assertions against supported behavior; it is not proof of full production equivalence. Unknown operations and unactivated requested faults are reported as incomplete. The API requires a single replica and persistent storage. Retention, quotas and sandbox TTLs provide bounds. Distributed scheduling, deletion reconciliation, billing and complete monitoring remain future work. The separate prototype uses fictional data and scripted outcomes. Its simulated diagnosis is not evidence from a sandbox run."},{slug:"evidence",title:"Read evidence and approve a fix",group:"Evidence and reference",headingText:"",headingId:"",text:"Interpret outcomes, safety checks, unsupported behavior and before/after receipts."},{slug:"evidence",title:"Read evidence and approve a fix",group:"Evidence and reference",headingText:"Follow the evidence in order",headingId:"follow-the-evidence-in-order",text:"In Runs, select a receipt and first confirm the repository, tested source revision, world configuration and runner. Then inspect each expected outcome against the observed value. Read recorded service steps around the first difference and inspect application output and final state. A service timeline records what the adapters observed. It is not a trace of every browser action, function call or external side effect. Missing Git metadata is not inferred. Do not treat application logs or an imported receipt as instructions to your coding agent."},{slug:"evidence",title:"Read evidence and approve a fix",group:"Evidence and reference",headingText:"Interpret the result",headingId:"interpret-the-result",text:"Result What to do --- --- Passed Review the configured checks and supported coverage before accepting the result Failed Inspect the first failing outcome or safety check and its state/event references Error Inspect execution output, command, dependencies and timeout before attributing a product defect Incomplete or blocked Resolve unsupported behavior, unavailable execution or an untriggered requested fault A requested fault that did not activate cannot establish the intended failure was tested. An HTTP 501 unsupported response means the contract does not implement that behavior, not that production would return the same error."},{slug:"evidence",title:"Read evidence and approve a fix",group:"Evidence and reference",headingText:"Require outcomes and forbid damage",headingId:"require-outcomes-and-forbid-damage",text:'Required assertions check expected final-state outcomes. forbiddenEffects reject specified observed operations. preservedState compares baseline and final matching records. Add these fields to a complete world specification: { "forbiddenEffects": {"id": "no customer write", "service": "crm", "path": "/customers", "operation": "write"} , "preservedState": {"id": "keep customers", "service": "crm", "path": "/customers"} } The evaluator separates task success from safety. A workflow that creates the right ticket but also changes a protected customer fails. Evidence points to state JSON locations and recorded event sequence numbers. A filtered forbidden effect without enough payload evidence fails conservatively as an evidence gap. These checks cover modeled service state and recorded operations. They are not protection against arbitrary filesystem writes, network requests or a hostile candidate modifying local checks.'},{slug:"evidence",title:"Read evidence and approve a fix",group:"Evidence and reference",headingText:"Compare broken and repaired executions",headingId:"compare-broken-and-repaired-executions",text:"For a lost-response retry, expect evidence of the committed write followed by the delayed response and retry. A duplicate-write failure should differ from the repaired run's one-record outcome. Confirm any forbidden-effect and preserved-state checks as well. Keep the scenario and specification fixed; change only the justified application code. In Runs, compare checks, final collections, source digests and fault settings. Different seeds, specifications or faults invalidate a simple claim that the source patch alone caused the improvement."},{slug:"evidence",title:"Read evidence and approve a fix",group:"Evidence and reference",headingText:"Verify freshness",headingId:"verify-freshness",text:"npx agenttwin verify --file .agenttwin/runs/RUN ID/run.json --world agenttwin.world.json --scenario support retry@1 --json Use the scenario actually used by the run. Verification recomputes local evidence and compares current source/specification provenance. It does not rerun the application or independently attest that a receipt is authentic. Run again after a code change; an old passing receipt is not evidence for new source."},{slug:"evidence",title:"Read evidence and approve a fix",group:"Evidence and reference",headingText:"Share and retain the result",headingId:"share-and-retain-the-result",text:"npx agenttwin sync sends reviewed receipts to the connected account. You can also import run.json in Runs without uploading it. Fix & retest exports an evidence-based coding task; review its proposed change and run the unchanged checks again. Keep the specification, scenario source and receipts alongside the application change where appropriate. Automatic generation of permanent browser regression tests and protected independent grading are not implemented. Troubleshooting covers common evidence gaps."},{slug:"cli",title:"CLI and coding-agent reference",group:"Evidence and reference",headingText:"",headingId:"",text:"Find commands, local artifacts, exit codes and all twelve coding-agent tools."},{slug:"cli",title:"CLI and coding-agent reference",group:"Evidence and reference",headingText:"Run commands from your repository",headingId:"run-commands-from-your-repository",text:"Use npx agenttwin for an installed release, or a built checkout's CLI for checkout-only features. Node.js 22.12+ is required. --json writes structured results to stdout and logs to stderr. Substitute returned IDs for uppercase placeholders. Command Purpose --- --- init Discover dependencies and workflow candidates login Connect the terminal to your dashboard account sync Send reviewed discovery and receipts to that account example --out ./agenttwin-example Generate runnable example source and worlds prepare --file preparation.json Validate mappings and create an explicit application bundle contracts --file agenttwin.world.json --json Inspect adapter operation coverage run --file agenttwin.world.json --json Execute a one-shot local world run --runtime hosted --file agenttwin.world.json Request optional API-managed cloud execution run --runtime e2b --file agenttwin.world.json Use your own configured E2B runtime scenario save --file support.scenario.json --json Validate and save an immutable scenario version scenario list --json List saved versions and digests scenario show --scenario support retry@1 --json Read a saved fixture world create --file agenttwin.world.json --scenario support retry@1 --ttl 3600 --json Start a reusable local HTTP world world list --json List local lifecycle metadata world status --id WORLD ID --json Inspect lifecycle and connection information world run --id WORLD ID --json Reset baseline, stage current listed source and execute world reset --id WORLD ID --json Clear state, keys, events and activated faults world extend --id WORLD ID --ttl 3600 --json Set a ready world's expiry to now plus TTL world teardown --id WORLD ID --json Close services and end the world receipt --id RUN ID --json Inspect recorded checks and a source-fix task verify --file PATH TO RUN JSON --world agenttwin.world.json --json Recompute checks and inspect freshness without execution mcp Serve coding-agent tools over stdio TTL is 1–86400 seconds. Use the optional --scenario id@version on verification when the receipt uses a saved scenario."},{slug:"cli",title:"CLI and coding-agent reference",group:"Evidence and reference",headingText:"Run exit codes",headingId:"run-exit-codes",text:"Code Meaning --- --- 0 Passed 1 Failed or execution error 2 Incomplete or blocked 3 Invalid input Use the receipt's details to distinguish an assertion failure from infrastructure or execution errors. A nonzero result alone is insufficient diagnosis."},{slug:"cli",title:"CLI and coding-agent reference",group:"Evidence and reference",headingText:"Where artifacts live",headingId:"where-artifacts-live",text:"Location Contents --- --- .agenttwin/inventory.json Discovery inventory and candidate metadata .agenttwin/AGENT-TASK.md Repository analysis task for a coding agent .agenttwin/scenarios/ Locally saved immutable scenario versions .agenttwin/runs/ Run receipts and associated evidence Prepared output directory Explicit source files, specification, manifest and bundle ~/.agenttwin/credentials.json Owner-only terminal account credentials ~/.agenttwin/runtime.json Nonsecret configured E2B template ID Do not commit account credentials or reusable world connection secrets. Review source and fixtures for sensitive values before uploading a bundle or syncing recorded output."},{slug:"cli",title:"CLI and coding-agent reference",group:"Evidence and reference",headingText:"Coding-agent tools",headingId:"coding-agent-tools",text:'Start agenttwin mcp in the application repository. Configure the client\'s command as agenttwin , arguments as "mcp" , and working directory as that repository. Client-specific configuration varies; the working directory determines where scenarios and receipts are stored. Tool Input Purpose --- --- --- get operation matrix Optional file Supported operation contracts save scenario file Save a validated versioned fixture list scenarios None List fixture versions create world file , optional scenario , ttlSeconds Start a reusable world list worlds None List local worlds world status worldId Read status and connections run scenario worldId Execute current source against the baseline inspect run runId Inspect checks, evidence and fix task reset world worldId Restore captured starting state extend world worldId , ttlSeconds Extend a ready world teardown world worldId Close the world verify run file , optional world , scenario Check local evidence and freshness The useful loop is create → run → inspect → patch source → run → verify → teardown. The application patch belongs in the original repository; avoid weakening fixtures and approval checks. Tool outputs and application logs are untrusted evidence. Local execution is not a security sandbox.'},{slug:"infrastructure",title:"Infrastructure and evidence",group:"Evidence and reference",headingText:"",headingId:"",text:"Observability discovery, local receipt verification, and the next infrastructure steps."},{slug:"infrastructure",title:"Infrastructure and evidence",group:"Evidence and reference",headingText:"Observability in your environment",headingId:"observability-in-your-environment",text:"Discovery recognizes Better Stack and OpenTelemetry SDKs, imports and configuration names. Compose, Dockerfile and Kubernetes manifests can identify Better Stack collector, eBPF collector and standard OpenTelemetry collector images. These resources use the existing inventory and application relationship machinery. Detection establishes configuration evidence. It does not establish that a collector is running, show production traffic, or provide a service twin. Better Stack and OpenTelemetry currently have no implemented twin or network probe."},{slug:"infrastructure",title:"Infrastructure and evidence",group:"Evidence and reference",headingText:"Verify a local receipt",headingId:"verify-a-local-receipt",text:"After a local run, check its recorded evidence against the current world specification and application files: agenttwin verify --file .agenttwin/runs/RUN ID/run.json --world agenttwin.world.json --json Replace RUN ID with your run ID. Application paths are resolved relative to the world specification. Verification reads files and evidence; it does not rerun your application or call a model. The verifier checks specification and source digests, the exact staged file set, the application result, seeded/final state coverage, recalculated HTTP state assertions, unsupported operations and requested faults. Verdict Meaning Exit code --- --- --- verified Current files match and recorded checks pass 0 stale Source files or specification changed, or source evidence is missing 2 failed Recorded execution/state checks fail 1 invalid Receipt or specification is invalid, inconsistent or outside the supported runtime 1 This command supports local CLI receipts. Hosted/E2B receipts and database assertions are outside its scope. A verified receipt remains self-reported evidence; it is not independent execution attestation. Digests cover explicitly staged files, not every dependency or external service. The command does not update dashboard status or automatically gate sync."},{slug:"infrastructure",title:"Infrastructure and evidence",group:"Evidence and reference",headingText:"Infrastructure direction",headingId:"infrastructure-direction",text:"The next operational work is correlated telemetry for API requests, queue wait, execution duration and sandbox cleanup, followed by a durable store and queue before scaling replicas. Future scenario evaluation should separately check required outcomes and forbidden side effects. Useful references are the Better Stack collector , Claude Referee , and ArgaBench . AgentTwin's changes are original implementations. No external collector or evaluation service was installed by this work."},{slug:"troubleshooting",title:"Troubleshoot setup and tests",group:"Help and direction",headingText:"",headingId:"",text:"Resolve account, discovery, adapter, execution and verification problems."},{slug:"troubleshooting",title:"Troubleshoot setup and tests",group:"Help and direction",headingText:"Start with the failed boundary",headingId:"start-with-the-failed-boundary",text:"Identify whether the problem is discovery, account connection, preparation, service support, application execution or evidence. Keep the run ID, command, exit code and receipt. Review logs locally and redact sensitive values before sharing them."},{slug:"troubleshooting",title:"Troubleshoot setup and tests",group:"Help and direction",headingText:"CLI command is missing or Node fails",headingId:"cli-command-is-missing-or-node-fails",text:"Run node --version and inspect the CLI version/help. Node.js 22.12+ is required. In this repository, nvm use selects the checked-in runtime version. A previously published package may lack checkout-only world commands: build and use this repository's CLI rather than assuming the docs describe your old installed package."},{slug:"troubleshooting",title:"Troubleshoot setup and tests",group:"Help and direction",headingText:"Onboarding says the account could not be loaded",headingId:"onboarding-says-the-account-could-not-be-loaded",text:"Use Try again and confirm the configured AgentTwin API is reachable. A running website does not establish that the separate account API is healthy. Check the browser's failed account request and API server logs. Sign in again if the session is unauthorized. Do not change assertions or fixtures to resolve an account failure. Browser appearance preferences can be edited without a loaded account; terminal approval and account project checks require the authenticated account. Dashboard guide explains connection state and refresh."},{slug:"troubleshooting",title:"Troubleshoot setup and tests",group:"Help and direction",headingText:"Discovery finds too much or nothing",headingId:"discovery-finds-too-much-or-nothing",text:"Run init from the actual application root. Inspect recorded source and dependency evidence before accepting a candidate. Use --exclude for unused integrations and rediscover after source changes. Environment keys alone do not create supported adapters. Agent analysis and static discovery produce candidates requiring review."},{slug:"troubleshooting",title:"Troubleshoot setup and tests",group:"Help and direction",headingText:"Preparation rejects a workflow",headingId:"preparation-rejects-a-workflow",text:"Use actual discovery workflow and tool IDs. Include reviewed mappings for every recorded candidate operation. Confirm the entrypoint is built, listed files exist relative to the spec, and the command begins with node . Unsupported SDK operations require additional adapter work or a narrower test, not a fabricated mapping marked reviewed."},{slug:"troubleshooting",title:"Troubleshoot setup and tests",group:"Help and direction",headingText:"Module missing or production requests still occur",headingId:"module-missing-or-production-requests-still-occur",text:"Bundle application dependencies before preparation. The runtime does not install them. Override service base URLs with the generated twin endpoint and use its generated token. Inspect the application client's configuration; changing credentials alone does not redirect a production URL. Local application code has host network access, so review execution paths before running."},{slug:"troubleshooting",title:"Troubleshoot setup and tests",group:"Help and direction",headingText:"HTTP 501 or incomplete coverage",headingId:"http-501-or-incomplete-coverage",text:"Inspect contracts and the receipt's unsupported event. Unknown methods or parameters are deliberately rejected and are not proxied to production. Current Slack support excludes pagination, threads, files and OAuth. Either stay within the implemented contract or implement and validate the missing adapter operation before claiming coverage."},{slug:"troubleshooting",title:"Troubleshoot setup and tests",group:"Help and direction",headingText:"Requested failure never activated",headingId:"requested-failure-never-activated",text:"Check the application's actual method/path and recorded operations against the fault configuration. Ensure the relevant write was reached and the client has a timeout that exposes the delayed response. An untriggered requested fault makes the intended failure test incomplete. Do not remove the fault merely to obtain a passing result."},{slug:"troubleshooting",title:"Troubleshoot setup and tests",group:"Help and direction",headingText:"Same scenario version cannot be saved",headingId:"same-scenario-version-cannot-be-saved",text:"Versions are immutable. Identical content can be saved again; modified content needs a higher version. Check cross-service references for exactly one matching seeded record. Use a new world for a changed baseline and keep the previous version for comparisons."},{slug:"troubleshooting",title:"Troubleshoot setup and tests",group:"Help and direction",headingText:"World expired or disappeared",headingId:"world-expired-or-disappeared",text:"Inspect world status . Expiration closes endpoints and interrupts active execution. A world cannot be revived after termination or expiry; create another one. Extend a ready world before its TTL elapses. State is held in the host process's memory and is not recoverable after that process is lost."},{slug:"troubleshooting",title:"Troubleshoot setup and tests",group:"Help and direction",headingText:"Tests pass but the repair is unconvincing",headingId:"tests-pass-but-the-repair-is-unconvincing",text:"Inspect required outcomes, forbidden effects and protected starting records. Confirm the fault activated and that the test actually reached the failing operation. Compare scenario/specification digests and source changes. Add missing meaningful checks as a separately reviewed test change; do not pretend changing checks proves a source-only repair."},{slug:"troubleshooting",title:"Troubleshoot setup and tests",group:"Help and direction",headingText:"Receipt is stale after a patch",headingId:"receipt-is-stale-after-a-patch",text:"Run again. For a prepared one-shot bundle, rebuild and prepare the changed source first. For a reusable world, confirm the listed source files are the ones you edited. Verify the new receipt against current source, world and scenario; verification never executes application code."},{slug:"troubleshooting",title:"Troubleshoot setup and tests",group:"Help and direction",headingText:"Cloud execution is unavailable",headingId:"cloud-execution-is-unavailable",text:"Select cloud execution explicitly only when needed. API-managed cloud jobs require an operator-configured runtime. Direct E2B requires your own key and template setup. A gateway can serve accounts and synced evidence without cloud credentials; that does not mean cloud execution is provisioned. PostgreSQL and Redis worlds require cloud execution today."},{slug:"troubleshooting",title:"Troubleshoot setup and tests",group:"Help and direction",headingText:"Runs is empty",headingId:"runs-is-empty",text:"Discover and run in the intended repository, then connect the terminal and sync. Or import a run.json receipt manually. Manual imports disappear on page reload and are not uploaded. Browser connection tokens stay in page memory; reconnect if needed and use workspace refresh to load account results. For the verified end-to-end path, return to your first verified fix ."},{slug:"faq",title:"FAQ",group:"Help and direction",headingText:"",headingId:"",text:"Practical answers about discovery, supported execution, accounts and data."},{slug:"faq",title:"FAQ",group:"Help and direction",headingText:"Can I use AgentTwin now?",headingId:"can-i-use-agenttwin-now",text:"Yes, for explicitly configured bundled Node workflows using supported operations. Run npx agenttwin init with Node.js 22.12+, review discovery, prepare your real files and execute locally against supported HTTP twins, or explicitly choose a cloud sandbox. The dashboard supports individual AgentTwin accounts; users can also configure their own E2B account for direct CLI execution."},{slug:"faq",title:"FAQ",group:"Help and direction",headingText:"Does it clone my production accounts or every tool?",headingId:"does-it-clone-my-production-accounts-or-every-tool",text:"No. Discovery finds dependency and code signals. Supported services use synthetic state and fresh test credentials. A catalog entry does not imply a working vendor adapter. Provider-native account provisioning and arbitrary production-environment cloning are not implemented."},{slug:"faq",title:"FAQ",group:"Help and direction",headingText:"Is it only for refunds?",headingId:"is-it-only-for-refunds",text:"No. The product addresses workflows and agent side effects across systems. Four fault classes ship today: timeout-after-write, blackhole (a dependency going dark mid-call), server-error (repeated failures from a dependency) and duplicate-write (first-class duplicate deliveries, suppressed by idempotency keys). Seeded reproduction and named property checks apply across all of them. Refund scenarios are historical examples."},{slug:"faq",title:"FAQ",group:"Help and direction",headingText:"What happens to credentials and data?",headingId:"what-happens-to-credentials-and-data",text:"The operator’s E2B key stays on the API server. Dashboard account tokens remain in tab memory. Sync sends reviewed metadata, not source bodies or credential values. Execution uploads explicitly reviewed application files and fixtures; those files can themselves contain sensitive values, so review the bundle. No production OAuth session is reused. The terminal CLI keeps its saved login and runtime-template config only under ~/.agenttwin/ and does not scan other dotfiles or shell environments for credentials."},{slug:"faq",title:"FAQ",group:"Help and direction",headingText:"Are execution sandboxes zero-retention?",headingId:"are-execution-sandboxes-zero-retention",text:"Application sandboxes are created fresh for one run and deleted when it ends (a finite sandbox TTL is the backstop); source is not retained for recovery. What is retained is the evidence: receipts, with recorded events and before/after state, persist in your account (bounded at 30 days and 1,000 receipts per account) — that retention is the product, not an accident. There is no self-service delete-on-request pipeline for stored receipts yet; account revocation blocks new runs but does not erase history today."},{slug:"faq",title:"FAQ",group:"Help and direction",headingText:"Does init automatically run and repair every workflow?",headingId:"does-init-automatically-run-and-repair-every-workflow",text:"No. Init offers agent-assisted analysis and exports workflow candidates. Inputs, invocation, dependency mappings and assertions need review. Fix & retest exports recorded evidence for your coding agent; a rebuilt bundle and fresh execution are required to verify a repair."},{slug:"faq",title:"FAQ",group:"Help and direction",headingText:"What is saved in the browser?",headingId:"what-is-saved-in-the-browser",text:"Manual declarations, map layout and preferences persist in browser storage. Imported discovery and receipts stay in memory. Account-owned discovery and jobs persist on the API. Tokens are cleared on disconnect or reload."},{slug:"faq",title:"FAQ",group:"Help and direction",headingText:"Is the prototype a real execution?",headingId:"is-the-prototype-a-real-execution",text:"The separate prototype is scripted and uses fictional scenarios. The dashboard and CLI operate on actual imported/synced discovery and hosted run receipts. Engineering examples are not customer references."},{slug:"wedge",title:"Example: timeout after a write",group:"Help and direction",headingText:"",headingId:"",text:"A historical payment example of a general workflow fault class."},{slug:"wedge",title:"Example: timeout after a write",group:"Help and direction",headingText:"The scenario",headingId:"the-scenario",text:"A worker asks a payment provider to create a refund. The provider commits the write, but the response times out. The worker cannot tell whether the refund happened and retries. A weak implementation creates a second refund. A resilient implementation uses an idempotency key and verifies final state. sequenceDiagram participant W as Worker participant P as Payment provider W- P: Create refund (idempotency key) P- P: Commit refund P--xW: Response lost (timeout) W- P: Retry create refund Note over W,P: Weak: a second refund. Resilient: the key returns the original."},{slug:"wedge",title:"Example: timeout after a write",group:"Help and direction",headingText:"What the scenario declares",headingId:"what-the-scenario-declares",text:"--- --- Starting state One eligible payment, zero refunds. Injected condition Commit refund; discard response; allow retry. Expected outcome Exactly one refund record, one customer notification, a recoverable trace. Regression artifact Versioned starting state, fault point, input, and assertions."},{slug:"wedge",title:"Example: timeout after a write",group:"Help and direction",headingText:"Why this wedge",headingId:"why-this-wedge",text:"- Real — this failure class appears in production integrations, not only in theory. - Costly — a duplicate refund moves money and damages trust. - Hard to reproduce — it needs a write that commits and a response that never arrives. - Testable without risk — a developer should be able to reproduce it without credentials, network calls, or a real account. The CLI runtime supports all four fault classes — timeout-after-write, blackhole, server-error and duplicate-write — across the supported HTTP twins (custom JSON collections, Slack, Stripe, and the thirteen vendored twins). Seeded fault scheduling applies to every class except the declared timeout-after-write delay, which stays the user's declared spec. Hosted sandbox runs accept faults too, but a run seed and seed matrices are currently local-runtime only. Prepare and submit your actual workflow code to inspect the write count and fault activation. A custom collection test does not verify Stripe behavior."},{slug:"wedge",title:"Example: timeout after a write",group:"Help and direction",headingText:"What a reproduced failure buys you",headingId:"what-a-reproduced-failure-buys-you",text:'The fault is seeded: from one seed string, trials deterministically derive which collection faults and how long the response is withheld (plus an unfaulted control trial). Seeds cover fault selection and delays, not OS scheduling. A saved trial becomes a named regression you can require in CI, so the fix is proven against unchanged checks and the failing trial carries a seed coordinate in its receipt. In buyer\'s terms: "first failure at seed 000000008f2c41d9, reproduced exactly" replaces "the refunds double sometimes; we could never reproduce it."'},{slug:"wedge",title:"Example: timeout after a write",group:"Help and direction",headingText:"The seeded fault classes",headingId:"the-seeded-fault-classes",text:"Four fault classes ship today, each named by the loss it costs, never the mechanism. The run seed decides which matched requests get faulted, so the same seed plus the same fingerprint recreates the same schedule: - Timeout after write — the write commits, the answer vanishes mid-charge; a weak retry turns one refund into two. The declared delayMs is application-visible spec, never seeded. - Blackhole — the service goes dark mid-charge; no response at all, ever; the caller never learns whether the write committed. - Server error — the dependency starts returning 500s (seeded rejections and an optional seeded delay window), so error paths get exercised. - Duplicate write — two refunds hit at the same time; duplication itself, not a lost response inviting a retry. An idempotency key suppresses it, which is exactly the property worth asserting. Further fault types are deliberately rejected by today's schemas rather than silently ignored, and an untriggered requested fault makes a run incomplete."},{slug:"roadmap",title:"Product roadmap",group:"Help and direction",headingText:"",headingId:"",text:"Current product stage, next milestones and the evidence needed for customer readiness."},{slug:"roadmap",title:"Product roadmap",group:"Help and direction",headingText:"Available foundations",headingId:"available-foundations",text:"The source includes guided repository discovery and reviewed sharing, reusable test worlds, linked scenarios, explicit outcome checks, replay and protected regression tooling. Stripe and Slack plus thirteen additional provider adapters implement bounded subsets; detecting a provider does not establish compatibility with its full API. Four fault classes exist: timeout after a write, dropped responses, server errors and duplicate writes. Seeded selection and delays, captured-source replay, unchanged-check patch verification and bounded fault shrinking are implemented. These do not control arbitrary operating-system scheduling or guarantee deterministic model responses. The dashboard, account-scoped sync, Google/GitHub/OIDC sign-in code and organization-realm selection are implemented. Live release and enterprise acceptance are verified separately from source and local tests."},{slug:"roadmap",title:"Product roadmap",group:"Help and direction",headingText:"1. Close the release gap",headingId:"1-close-the-release-gap",text:"Version 0.3.8 is published on npm, with CLI/MCP reporting aligned and registry integrity matching the tested tarball. Verify the intended website/API rollout and live authentication acceptance. Done when: a clean installation of npx agenttwin init pairs with the right workspace and shares reviewed discovery; installed/deployed revisions and real authentication acceptance are recorded."},{slug:"roadmap",title:"Product roadmap",group:"Help and direction",headingText:"2. Run one real application workflow",headingId:"2-run-one-real-application-workflow",text:"Confirm a pilot workflow's trigger, invocation, runtime, exact service operations and persisted state. Run the actual application revision with test credentials and seeded records. Customer requirements must define the expected outcome and forbidden side effects. Done when: the supported workflow runs end to end, its coverage is visible, and unsupported behavior produces an incomplete result."},{slug:"roadmap",title:"Product roadmap",group:"Help and direction",headingText:"3. Prove provider correctness",headingId:"3-prove-provider-correctness",text:"Expand adapters around the pilot's required operations. Compare behavior with official SDKs and authorized test accounts, including authentication, pagination, mutations, errors, retries, reset and webhooks where needed. Done when: each required operation has a versioned contract, conformance evidence and explicit limitations. Adapter count alone is not the acceptance criterion."},{slug:"roadmap",title:"Product roadmap",group:"Help and direction",headingText:"4. Turn a real failure into a protected regression",headingId:"4-turn-a-real-failure-into-a-protected-regression",text:"Reproduce a meaningful failure, connect evidence to the failing operation, patch application source and rerun unchanged checks. Save the scenario and install a required pull-request check using a trusted grading baseline. Done when: the original code fails, the fix passes, a deliberately reintroduced defect fails, and candidate changes cannot weaken the grading checks. Protected browser/background and database-backed execution still need broader runner support."},{slug:"roadmap",title:"Product roadmap",group:"Help and direction",headingText:"5. Earn repeated pilot use",headingId:"5-earn-repeated-pilot-use",text:"Make onboarding and evidence understandable, measure setup effort and false positives, and observe teams using the checks across releases. Broaden runtime and provider coverage from actual workflow needs. Done when: a pilot can show measured setup time, useful defects, dependable regression results and repeat use. Synthetic demonstrations and engineering tests do not establish adoption or willingness to pay."},{slug:"roadmap",title:"Product roadmap",group:"Help and direction",headingText:"Enterprise and scaling gates",headingId:"enterprise-and-scaling-gates",text:"Implement and verify required team roles, tenant SSO enforcement, audit evidence, retention/deletion controls, monitoring and backup/restore before promising enterprise readiness. Move the single-instance store and scheduler to a suitable distributed design before scaling replicas. Any security controls required by the first pilot take priority before granting that pilot access. Shared agent memory helps the development team coordinate; it does not replace provider conformance, customer outcome checks or operational evidence. Roadmap order is a priority sequence, not a delivery-date commitment."},{slug:"roadmap",title:"Product roadmap",group:"Help and direction",headingText:"First private application slice",headingId:"first-private-application-slice",text:"On October 19, a local test of the actual calendar-reading function reproduced missed appointments on short paginated responses. The captured original fails; an application-only patch passes unchanged checks; replay still reproduces the original failure. The regression and private source stay local. This proves a calendar-read slice, with a controlled transport returning short pages. It does not establish full scheduling, Bun/SQL execution, live Google conformance or a protected customer PR check. The local protected Docker check also rejects the original calendar bundle and accepts the fixed bundle with unchanged trusted checks, even when the candidate attempts to weaken its own regression definition. Private-repository build and required-check installation remain open. Release candidate f9338a5 passed 361 CLI tests, 17 web tests, the website build and fresh tarball installation. npm published 0.3.8 , and public registry integrity matches the tested tarball. Production health is reachable, but email verification is reported disabled and full live sign-in acceptance remains open. These checks do not close P0 or establish complete pilot readiness."},{slug:"prototype",title:"Explore the browser demo",group:"Help and direction",headingText:"",headingId:"",text:"Walk through the five-step prototype: choose a world, review the replica, run, inject a fault, and read the diagnosis."},{slug:"prototype",title:"Explore the browser demo",group:"Help and direction",headingText:"The five-step walkthrough",headingId:"the-five-step-walkthrough",text:"Pick one of eight illustrative worlds and map its production stack before creating an isolated test environment. See the declared boundaries — what is masked, blocked, or captured — before running anything. Run the workflow against a clean, repeatable starting state. For example, commit a refund but discard the response, so the worker's retry has to be safe. Inspect the failed assertion and state difference, copy the fix prompt, and restore the same starting state for a regression run."},{slug:"prototype",title:"Explore the browser demo",group:"Help and direction",headingText:"Run it locally",headingId:"run-it-locally",text:"The demo is a Next.js route in the same website app. Start the development server from the repository root. cd /path/to/AgentTwin npm ci --prefix web npm run dev Open http://localhost:3000/demo/"},{slug:"prototype",title:"Explore the browser demo",group:"Help and direction",headingText:"What the prototype does not do",headingId:"what-the-prototype-does-not-do",text:"The fix prompt is a handoff for your coding agent or developer, with the observed failure and a suggested change. It does not inspect or patch customer code. The recovery preview uses a second scripted fixture. Refreshing the browser resets all session state. - No credentials are requested and no provider APIs are called. - No customer code is executed or modified. - Company names are potential customer examples, not customers or partners. Stacks, records, and incidents are invented for demonstration. For the current inventory of what exists, see What exists today ."}];var d=n(2183),c=n(58),l=n(949);let u=new Set(["the","a","an","and","or","for","of","to","in","on","at","is","are","was","were","be","it","its","you","your","with","that","this","these","those","from","how","do","does","can","i","my","we"]),p=e=>(e.toLowerCase().match(/[a-z0-9]+/g)||[]).filter(e=>e.length>1&&!u.has(e)),h=e=>e.replace(/[.*+?^${}()|[\]\\]/g,"\\$&"),g=(e,t)=>("index"===e?"/docs/":"/docs/".concat(e,"/"))+(t?"#"+t:""),f="agenttwin:docs-search-recent";function m(){try{let e=JSON.parse(localStorage.getItem(f)||"[]");return Array.isArray(e)?e.filter(e=>"string"==typeof e).slice(0,6):[]}catch(e){return[]}}let w=[{title:"Quickstart",href:"/docs/quickstart/",detail:"Run a real failure end to end"},{title:"CLI and MCP reference",href:"/docs/cli/",detail:"Commands, artifacts, exit codes"},{title:"Troubleshooting",href:"/docs/troubleshooting/",detail:"Fix setup and execution problems"},{title:"FAQ",href:"/docs/faq/",detail:"Accounts, data and boundaries"}],v=null;function y(){if(v)return v;let e=s.filter(e=>e.text).map(e=>{let t=p(e.text),n=new Map,a=new Set(p(e.title)),r=new Set(p(e.headingText)),i=new Set(p(e.slug.replace(/-/g," ")));for(let e of t)n.set(e,(n.get(e)||0)+1);return{chunk:e,tf:n,title:a,heading:r,slug:i,length:t.length}}),t=new Map;for(let{tf:n}of e)for(let e of n.keys())t.set(e,(t.get(e)||0)+1);let n=e.reduce((e,t)=>e+t.length,0)/(e.length||1)||1,a=n=>{let a=t.get(n)||0;return Math.log(1+(e.length-a+.5)/(a+.5))};return v={search:t=>{let r=[...new Set(p(t))];if(!r.length)return[];let i=t.trim().toLowerCase().replace(/\s+/g," ");return e.map(e=>{let t=1.2*(.25+.75*e.length/n),o=0;for(let n of r){let r=a(n),i=e.tf.get(n)||0;o+=2.2*i/(i+t)*r,e.title.has(n)&&(o+=3*r),e.heading.has(n)&&(o+=2*r),e.slug.has(n)&&(o+=1.2*r)}return i.includes(" ")&&(e.chunk.text.toLowerCase().includes(i)&&(o+=6),e.chunk.title.toLowerCase().includes(i)&&(o+=8),e.chunk.headingText.toLowerCase().includes(i)&&(o+=4)),{entry:e,score:o}}).filter(e=>e.score>.35).sort((e,t)=>t.score-e.score).slice(0,24).map(e=>e.entry.chunk)}}}function x(e,t){let n=s.find(e=>e.slug===t.slug&&!e.headingText),a=t=>{let n=t.toLowerCase(),a=p(e).map(e=>n.indexOf(e)).filter(e=>e>=0);return a.length?Math.min(...a):-1},r=t.text,i=a(r);if(i<0&&n&&(i=a(r=n.text)),i<0)return((null==n?void 0:n.text)||t.text).slice(0,160);let o=Math.max(0,i-60),d=r.slice(o,o+170).trim();return(o>0?"… ":"")+d+(o+170<r.length?" …":"")}function b(e){let{text:t,terms:n}=e;if(!n.length||!t)return(0,r.jsx)(r.Fragment,{children:t});let a=RegExp("(".concat(n.map(h).join("|"),")"),"gi"),i=t.split(a);return(0,r.jsx)(r.Fragment,{children:i.map((e,t)=>t%2==1?(0,r.jsx)("mark",{children:e},t):(0,r.jsx)("span",{children:e},t))})}let k=null!=(a=l.env.NEXT_PUBLIC_AGENTTWIN_API_URL)?a:"https://api.agenttwin.si",T=/\[([a-z0-9][a-z0-9_#/-]{0,79})\]/gi,I=(()=>{let e=0,t=new Map;return n=>{let a=t.get(n);return a||(a="cite-".concat(e++,"-").concat(n.replace(/[^a-z0-9_-]/gi,"-")),t.set(n,a)),a}})();function j(e){let{passages:t,pending:n,sources:a}=e;return(0,r.jsx)("ul",{className:n?"docs-ask-passages is-pending":"docs-ask-passages",children:t.map(e=>(0,r.jsx)("li",{id:a?"docs-".concat(I(e.id)):void 0,children:(0,r.jsxs)("a",{href:e.href,children:[(0,r.jsx)("strong",{children:e.title}),e.heading!==e.title&&(0,r.jsxs)("span",{children:[" › ",e.heading]}),(0,r.jsx)("span",{className:"docs-passage-text",children:e.text})]})},e.href))})}function S(e){let{open:t,onOpenChange:n}=e,[a,s]=(0,i.useState)("search"),[l,u]=(0,i.useState)(""),[h,v]=(0,i.useState)([]),[j,S]=(0,i.useState)(0),[R,A]=(0,i.useState)({kind:"idle"}),D=(0,i.useRef)(null),E=(0,i.useRef)(null),P=(0,i.useRef)(null),N=(0,i.useRef)(null),L=(0,i.useRef)(!1),q=(0,i.useRef)(""),M=(0,i.useCallback)(()=>{var e;null==(e=N.current)||e.abort(),n(!1)},[n]);(0,i.useEffect)(()=>{let e=e=>{if(document.querySelector(".docs-sidebar.is-open"))return;let t=e.target,a=(null==t?void 0:t.isContentEditable)||["INPUT","TEXTAREA","SELECT"].includes(null==t?void 0:t.tagName);("k"===e.key.toLowerCase()&&(e.metaKey||e.ctrlKey)||"/"===e.key&&!a)&&(e.preventDefault(),n("search"))};return document.addEventListener("keydown",e),()=>document.removeEventListener("keydown",e)},[n]),(0,i.useEffect)(()=>{var e,n,a,r;let i=L.current;if(L.current=t,!1===t){q.current&&(document.body.style.overflow=q.current,q.current=""),null==(n=D.current)||n.close();return}s(t),!1===i&&(q.current=document.body.style.overflow,document.body.style.overflow="hidden",null==(a=D.current)||a.showModal()),null==(e=null!=(r=("ask"===t?P:E).current)?r:E.current)||e.focus()},[t]),(0,i.useEffect)(()=>()=>{var e;return null==(e=N.current)?void 0:e.abort()},[]);let O=(0,i.useMemo)(()=>[...new Set(p(l))],[l]),H=(0,i.useMemo)(()=>l.trim()?y().search(l).map(e=>({chunk:e,snippet:x(l,e)})):[],[l]);(0,i.useEffect)(()=>S(0),[l,a]),(0,i.useEffect)(()=>{var e,t;null==(t=D.current)||null==(e=t.querySelector('[data-result="'.concat(j,'"]')))||e.scrollIntoView({block:"nearest"})},[j]),(0,i.useEffect)(()=>{!1!==t&&v(m())},[t]);let U=(0,i.useCallback)(e=>{if(!e)return void window.scrollTo({top:0,behavior:"smooth"});let t=document.getElementById(e);t&&(t.scrollIntoView({block:"start",behavior:"smooth"}),t.classList.remove("docs-flash-target"),t.offsetWidth,t.classList.add("docs-flash-target"),window.setTimeout(()=>t.classList.remove("docs-flash-target"),900))},[]),F=(0,i.useCallback)(e=>{!function(e){let t=e.trim();if(t.length<2)return;let n=[t,...m().filter(e=>e.toLowerCase()!==t.toLowerCase())].slice(0,6);try{localStorage.setItem(f,JSON.stringify(n))}catch(e){}}(l),M();let t="index"===e.slug?"/docs/":"/docs/".concat(e.slug,"/");if(window.location.pathname===t){U(e.headingId),e.headingId&&(window.location.hash=e.headingId);return}if(e.headingId)try{sessionStorage.setItem("agenttwin:docs-flash",e.headingId)}catch(e){}window.location.assign(g(e.slug,e.headingId))},[M,U,l]);(0,i.useEffect)(()=>{let e=(()=>{try{return sessionStorage.getItem("agenttwin:docs-flash")}catch(e){return null}})();if(!e)return;try{sessionStorage.removeItem("agenttwin:docs-flash")}catch(e){}let t=requestAnimationFrame(()=>window.setTimeout(()=>U(e),80));return()=>cancelAnimationFrame(t)},[U]);let W=(0,i.useCallback)(async e=>{var t;let n=e.trim();if(!n)return;let a=function(e){let t=arguments.length>1&&void 0!==arguments[1]?arguments[1]:6;return y().search(e).slice(0,t).map((t,n)=>({id:"".concat(t.slug,"#").concat(t.headingId||"p".concat(n)).slice(0,80),title:t.title,heading:t.headingText||t.title,href:g(t.slug,t.headingId),text:x(e,t).slice(0,700)}))}(n);A({kind:"loading",passages:a});let r=new AbortController;null==(t=N.current)||t.abort(),N.current=r;try{let e=await fetch("".concat(k,"/v1/ai/search"),{method:"POST",headers:{"Content-Type":"application/json"},body:JSON.stringify({question:n,passages:a.map(e=>{let{id:t,title:n,heading:a,href:r,text:i}=e;return{id:t,title:n,heading:a,snippet:i,url:r}})}),signal:r.signal});if(!e.ok)throw Error(String(e.status));let t=await e.json();if("string"!=typeof t.answer||!t.answer.trim())throw Error("no answer");A({kind:"answer",passages:a,html:function(e){let t=d.xI.parse(e,{async:!1}).replace(T,(e,t)=>'<a href="#'.concat(I(t),'" data-cite="').concat(t,'"><sup>[').concat(t,"]</sup></a>"));return c.A.sanitize(t)}(t.answer)})}catch(e){if((null==e?void 0:e.name)==="AbortError")return;A({kind:"unavailable",passages:a})}},[]),B="search"===a&&!l.trim();return(0,r.jsxs)(r.Fragment,{children:[(0,r.jsxs)("button",{type:"button","aria-label":"Search documentation",className:"docs-search-trigger",onClick:()=>n("search"),children:[(0,r.jsx)(o.I,{name:"search"}),(0,r.jsx)("span",{children:"Search documentation"}),(0,r.jsx)("kbd",{children:"⌘ K"})]}),(0,r.jsx)("dialog",{ref:D,className:"docs-search-dialog","aria-label":"Documentation search and AI answers",onCancel:M,onClose:M,onClick:e=>{e.target===e.currentTarget&&M()},children:(0,r.jsxs)("div",{className:"docs-search-dialog-content",children:[(0,r.jsxs)("div",{className:"docs-search-input",children:["ask"===a?(0,r.jsx)(o.I,{name:"sparkles",className:"docs-spark"}):(0,r.jsx)(o.I,{name:"search"}),"search"===a?(0,r.jsx)("input",{ref:E,type:"text",placeholder:"Search pages, commands, and concepts…","aria-label":"Search documentation",value:l,onChange:e=>u(e.target.value),onKeyDown:e=>{if("ArrowDown"===e.key)e.preventDefault(),S(e=>Math.min(e+1,H.length-1));else if("ArrowUp"===e.key)e.preventDefault(),S(e=>Math.max(0,e-1));else if("Enter"===e.key){var t;let n=null==(t=H[j])?void 0:t.chunk;n&&(e.preventDefault(),F(n))}else"Escape"===e.key&&(e.preventDefault(),M())}}):(0,r.jsx)("textarea",{ref:P,rows:2,placeholder:"Ask anything about AgentTwin, e.g. how do I verify a patch?","aria-label":"Ask the documentation",value:l,onChange:e=>u(e.target.value),onKeyDown:e=>{"Enter"!==e.key||e.shiftKey||(e.preventDefault(),W(l))}}),(0,r.jsxs)("div",{className:"docs-search-tabs",role:"tablist","aria-label":"Search mode",children:[(0,r.jsx)("button",{type:"button",role:"tab","aria-selected":"search"===a,onClick:()=>s("search"),children:"Search"}),(0,r.jsxs)("button",{type:"button",role:"tab","aria-selected":"ask"===a,onClick:()=>s("ask"),children:[(0,r.jsx)(o.I,{name:"sparkles"}),"Ask AI"]})]}),(0,r.jsx)("button",{type:"button","aria-label":"Close",onClick:M,children:(0,r.jsx)("kbd",{children:"Esc"})})]}),B&&(0,r.jsxs)("div",{className:"docs-search-list docs-search-welcome","aria-live":"polite",children:[h.length>0&&(0,r.jsxs)("div",{className:"docs-recent",children:[(0,r.jsx)("p",{className:"docs-search-caption",children:"Recent searches"}),h.map(e=>(0,r.jsxs)("button",{type:"button",className:"docs-recent-item",onClick:()=>u(e),children:[(0,r.jsx)(o.I,{name:"history"}),(0,r.jsx)("span",{children:e})]},e)),(0,r.jsxs)("button",{type:"button",className:"docs-recent-clear",onClick:()=>{try{localStorage.removeItem(f)}catch(e){}v([])},children:[(0,r.jsx)(o.I,{name:"close"}),"Clear recent searches"]})]}),(0,r.jsx)("p",{className:"docs-search-caption",children:"Explore documentation"}),w.map(e=>(0,r.jsxs)("a",{href:e.href,onClick:M,children:[(0,r.jsx)(o.I,{name:"book-open"}),(0,r.jsxs)("div",{children:[(0,r.jsx)("strong",{children:e.title}),(0,r.jsx)("span",{children:e.detail})]})]},e.href))]}),!B&&"search"===a&&(0,r.jsxs)("div",{className:"docs-search-list","aria-live":"polite",children:[(0,r.jsx)("p",{className:"docs-search-caption",children:H.length?"Results for “".concat(l.trim(),"”"):"No results"}),!H.length&&(0,r.jsxs)("p",{className:"docs-search-empty",children:["No matches for “",l.trim(),"”. Try a command like ",(0,r.jsx)("code",{children:"agenttwin init"})," or a topic like scenarios, or"," ",(0,r.jsx)("button",{type:"button",onClick:()=>s("ask"),children:"ask AI instead"}),"."]}),H.map((e,t)=>{let{chunk:n,snippet:a}=e;return(0,r.jsxs)("a",{href:g(n.slug,n.headingId),"data-result":t,className:j===t?"is-selected":"","aria-current":j===t?"true":void 0,onClick:e=>{e.preventDefault(),F(n)},children:[(0,r.jsx)(o.I,{name:n.headingText?"layout":"book-open"}),(0,r.jsxs)("div",{children:[(0,r.jsxs)("strong",{children:[n.title,n.headingText&&(0,r.jsxs)("span",{className:"docs-hit-heading",children:[" › ",n.headingText]})]}),(0,r.jsx)("span",{children:(0,r.jsx)(b,{text:a,terms:O})})]}),(0,r.jsx)("span",{className:"docs-hit-jump","aria-hidden":"true",children:"↵"})]},n.slug+"|"+n.headingId)})]}),"ask"===a&&(0,r.jsx)(C,{state:R,query:l,onSubmit:e=>{e.preventDefault(),W(l)},onReset:()=>{var e;null==(e=N.current)||e.abort(),A({kind:"idle"}),u("")}}),(0,r.jsxs)("div",{className:"docs-search-help",children:[(0,r.jsx)("span",{children:"↑ ↓ to navigate"}),(0,r.jsx)("span",{children:"↵ to open"}),(0,r.jsx)("span",{children:"esc to close"})]})]})})]})}function C(e){let{state:t,query:n,onSubmit:a,onReset:i}=e;return(0,r.jsxs)("div",{className:"docs-search-list docs-ask-panel","aria-live":"polite",children:[(0,r.jsxs)("form",{className:"docs-ask-form",onSubmit:a,children:[(0,r.jsxs)("button",{type:"submit",className:"docs-ask-submit",disabled:!n.trim(),children:[(0,r.jsx)(o.I,{name:"sparkles"}),"loading"===t.kind?"Asking…":"Ask"]}),(0,r.jsx)("span",{className:"docs-ask-hint",children:"Enter to ask \xb7 Shift+Enter for a new line"}),"idle"!==t.kind&&(0,r.jsx)("button",{type:"button",className:"docs-ask-reset",onClick:i,children:"New question"})]}),"loading"===t.kind&&(0,r.jsxs)(r.Fragment,{children:[(0,r.jsxs)("p",{className:"docs-ask-status docs-ask-loading",role:"status",children:["Reading the docs",(0,r.jsx)("span",{className:"docs-ask-dots","aria-hidden":"true"})]}),(0,r.jsx)(j,{passages:t.passages,pending:!0})]}),"answer"===t.kind&&(0,r.jsxs)(r.Fragment,{children:[(0,r.jsx)("article",{className:"docs-ask-answer",onClick:e=>{let t=e.target.closest("[data-cite]");if(!t)return;e.preventDefault();let n=document.getElementById("docs-ask-passage-".concat(t.dataset.cite));n&&(n.scrollIntoView({block:"nearest",behavior:"smooth"}),n.classList.add("docs-passage-focus"),window.setTimeout(()=>n.classList.remove("docs-passage-focus"),1200))},dangerouslySetInnerHTML:{__html:t.html}}),(0,r.jsx)(j,{passages:t.passages,sources:!0})]}),"unavailable"===t.kind&&(0,r.jsxs)(r.Fragment,{children:[(0,r.jsx)("p",{className:"docs-ask-status",children:"The assistant is unavailable right now. Try again shortly."}),t.passages.length>0&&(0,r.jsx)(j,{passages:t.passages})]})]})}function R(e){let{tab:t="search"}=e,[n,a]=(0,i.useState)(!1);return(0,r.jsxs)(r.Fragment,{children:[!1!==n&&(0,r.jsx)(S,{open:n,onOpenChange:a}),(0,r.jsx)("button",{type:"button",onClick:()=>a(t),"aria-haspopup":"dialog","aria-expanded":!1!==n,className:"inline-flex h-9 w-full items-center gap-2 rounded-lg border border-fd-border bg-fd-muted/50 px-3 text-sm text-fd-muted-foreground transition-colors hover:bg-fd-accent hover:text-fd-accent-foreground",children:"ask"===t?(0,r.jsxs)(r.Fragment,{children:[(0,r.jsx)(o.I,{name:"sparkles"}),(0,r.jsx)("span",{className:"flex-1 text-left",children:"Ask AI"})]}):(0,r.jsxs)(r.Fragment,{children:[(0,r.jsx)(o.I,{name:"search"}),(0,r.jsx)("span",{className:"flex-1 text-left",children:"Search docs…"}),(0,r.jsx)("kbd",{className:"bg-fd-muted px-1.5 py-0.5 text-xs font-normal",children:"⌘K"})]})})]})}},7188:()=>{"undefined"==typeof navigator||"undefined"==typeof document||navigator.clipboard||Object.defineProperty(navigator,"clipboard",{value:{writeText:e=>new Promise((t,n)=>{let a=document.createElement("textarea");a.value=e,a.setAttribute("readonly",""),a.style.cssText="position:fixed;top:-9999px;left:-9999px;opacity:0",document.body.appendChild(a),a.select();try{if(!document.execCommand("copy"))throw Error("copy_rejected");t()}catch(e){n(e)}finally{a.remove()}})},configurable:!0})},9694:(e,t,n)=>{"use strict";n.d(t,{DocsCodeBlock:()=>i});var a=n(1778),r=n(4764);function i(e){var t,n,i;let{children:o,...s}=e,d=Array.isArray(o)?o[0]:o,c=null!=(i=null==d||null==(t=d.props)?void 0:t.className)?i:"",l=null==(n=/language-([\w-]+)/.exec(c))?void 0:n[1],u="sh"===l||"bash"===l||"shell"===l||"console"===l?"Terminal":l?l.toUpperCase():"Code";return(0,a.jsx)(r.NG,{title:u,children:(0,a.jsx)("pre",{...s,children:o})})}n(7188)}},e=>{e.O(0,[8056,3916,4705,7903,4816,7358],()=>e(e.s=6804)),_N_E=e.O()}]);
+(self.webpackChunk_N_E=self.webpackChunk_N_E||[]).push([[7870],{622:()=>{},4318:(e,t,n)=>{Promise.resolve().then(n.bind(n,9694)),Promise.resolve().then(n.bind(n,6862)),Promise.resolve().then(n.bind(n,4893)),Promise.resolve().then(n.t.bind(n,622,23)),Promise.resolve().then(n.t.bind(n,6473,23)),Promise.resolve().then(n.bind(n,1833)),Promise.resolve().then(n.bind(n,6017)),Promise.resolve().then(n.bind(n,6635)),Promise.resolve().then(n.bind(n,2727)),Promise.resolve().then(n.bind(n,8748)),Promise.resolve().then(n.bind(n,6676)),Promise.resolve().then(n.bind(n,4617)),Promise.resolve().then(n.bind(n,7906)),Promise.resolve().then(n.bind(n,9293)),Promise.resolve().then(n.bind(n,9407)),Promise.resolve().then(n.bind(n,4001)),Promise.resolve().then(n.bind(n,2587)),Promise.resolve().then(n.bind(n,3969)),Promise.resolve().then(n.bind(n,3145)),Promise.resolve().then(n.bind(n,378))},4527:(e,t,n)=>{"use strict";n.d(t,{I:()=>i});var a=n(1778);let r={house:"m3 10.5 9-7.5 9 7.5M5.5 9v10.5h13V9M9.5 19.5v-6h5v6",activity:"M3 12h4l3-8 4 16 3-8h4",boxes:"m12 3 4 2v4l-4 2-4-2V5l4-2Zm-6 9 4 2v4l-4 2-4-2v-4l4-2Zm12 0 4 2v4l-4 2-4-2v-4l4-2Z",workflow:"M6 3v12a3 3 0 0 0 3 3h9M6 3 3 6m3-3 3 3m6 9 3 3 3-3","timer-off":"M12 21a8 8 0 1 0 0-16 8 8 0 0 0 0 16Zm0-12v4l-3 2M9 2h6","badge-check":"M12 3l2.2 1.6 2.7-.2.9 2.6 2.2 1.6-1 2.5 1 2.5-2.2 1.6-.9 2.6-2.7-.2L12 21l-2.2-1.6-2.7.2-.9-2.6L4 15.4l1-2.5-1-2.5 2.2-1.6.9-2.6 2.7.2L12 3Zm-2 9 1.6 1.6L15 10",shield:"M12 3l8 3v6c0 5-3.5 8-8 9-4.5-1-8-4-8-9V6l8-3Zm-3 9 2 2 4-4",layout:"M4 4h16v16H4V4Zm0 6h16M10 10v10",map:"m3 6 6-3 6 3 6-3v15l-6 3-6-3-6 3V6Zm6-3v15M15 6v15","mouse-pointer-click":"M9 9v10l2.5-2.5L14 21l1.8-.9-2.4-4.4H17L9 9Z",help:"M12 21a9 9 0 1 0 0-18 9 9 0 0 0 0 18Zm-2-11a2 2 0 1 1 2.9 1.8c-.6.3-.9.8-.9 1.4v.3M12 17h.01","book-open":"M12 5v15M12 5C9 3 5 3 2 4v15c3-1 7-1 10 1M12 5c3-2 7-2 10-1v15c-3-1-7-1-10 1",layers:"m3 8 9-5 9 5-9 5-9-5Zm0 5 9 5 9-5M3 18l9 5 9-5",compass:"M12 21a9 9 0 1 0 0-18 9 9 0 0 0 0 18Zm3.5-12.5-2 5-5 2 2-5 5-2Z","life-buoy":"M12 21a9 9 0 1 0 0-18 9 9 0 0 0 0 18Zm0-6a3 3 0 1 0 0-6 3 3 0 0 0 0 6Zm0-3-6.5-6.5M12 12l6.5 6.5M12 12 5.5 18.5M12 12l6.5-6.5",globe:"M12 21a9 9 0 1 0 0-18 9 9 0 0 0 0 18Zm-9-9h18M12 3c2.5 2.6 3.8 5.6 3.8 9S14.5 18.4 12 21c-2.5-2.6-3.8-5.6-3.8-9S9.5 5.6 12 3Z",calendar:"M4 6h16v14H4V6Zm0 5h16M8 3v4M16 3v4",play:"M8 5v14l11-7L8 5Z",sun:"M12 17a5 5 0 1 0 0-10 5 5 0 0 0 0 10Zm0-14v2M12 19v2M3 12h2M19 12h2M5.6 5.6 7 7M17 17l1.4 1.4M18.4 5.6 17 7M7 17l-1.4 1.4",moon:"M20 13.5A8 8 0 0 1 10.5 4a8 8 0 1 0 9.5 9.5Z",search:"M11 18a7 7 0 1 0 0-14 7 7 0 0 0 0 14Zm5-2 4 4",copy:"M9 9h10v10H9V9ZM5 15V5h10",menu:"M4 7h16M4 12h16M4 17h16",close:"M6 6l12 12M18 6 6 18",chevron:"m9 5 7 7-7 7",sparkles:"m12 3 1.9 5.1L19 10l-5.1 1.9L12 17l-1.9-5.1L5 10l5.1-1.9L12 3Zm7 11.5.9 2.1 2.1.9-2.1.9-.9 2.1-.9-2.1-2.1-.9 2.1-.9.9-2.1Z",history:"M12 21a9 9 0 1 0-9-9m9 0v4m-9 5 1-4 4 1M3 3v5h5","flask-conical":"M9 3h6M10 3v6L4.5 17.5A2 2 0 0 0 6.2 21h11.6a2 2 0 0 0 1.7-3.5L14 9V3M7 15h10",network:"M5 8a2.5 2.5 0 1 0 0-5 2.5 2.5 0 0 0 0 5Zm14 0a2.5 2.5 0 1 0 0-5 2.5 2.5 0 0 0 0 5ZM5 21a2.5 2.5 0 1 0 0-5 2.5 2.5 0 0 0 0 5Zm14 0a2.5 2.5 0 1 0 0-5 2.5 2.5 0 0 0 0 5ZM5 5.5h14M12 5.5V18m-7 0h14m-7 0v-4"};function i(e){let{name:t,className:n}=e;return(0,a.jsx)("svg",{viewBox:"0 0 24 24",width:16,height:16,fill:"none",stroke:"currentColor",strokeWidth:1.7,strokeLinecap:"round",strokeLinejoin:"round","aria-hidden":"true",className:n,children:(0,a.jsx)("path",{d:r[t]||r["book-open"]})})}},4893:(e,t,n)=>{"use strict";n.d(t,{DocsCopyPage:()=>s});var a=n(1778),r=n(5226),i=n(4527);async function o(e){try{var t;if(null==(t=navigator.clipboard)?void 0:t.writeText)return void await navigator.clipboard.writeText(e)}catch(e){}let n=document.createElement("textarea");n.value=e,n.setAttribute("readonly",""),n.style.cssText="position:fixed;top:-9999px;left:-9999px;opacity:0",document.body.appendChild(n);let a=document.getSelection(),r=(null==a?void 0:a.rangeCount)?a.getRangeAt(0):null;n.select();try{if(!document.execCommand("copy"))throw Error("copy_rejected")}finally{n.remove(),r&&a&&(a.removeAllRanges(),a.addRange(r))}}function s(e){let{slug:t,title:n}=e,[s,d]=(0,r.useState)("idle"),c=(0,r.useRef)(void 0);return(0,r.useEffect)(()=>()=>clearTimeout(c.current),[]),(0,a.jsxs)("button",{type:"button",className:"docs-copy-page",onClick:()=>{(async()=>{try{let e=await fetch("index"===t?"/docs/index.md":"/docs/".concat(t,".md"));if(!e.ok)throw Error("unavailable");await o(await e.text()),d("done")}catch(e){d("failed")}clearTimeout(c.current),c.current=setTimeout(()=>d("idle"),2500)})()},title:"Copy ".concat(n," as Markdown"),children:["done"===s?"Copied":"failed"===s?"Copy unavailable":"Copy page",(0,a.jsx)(i.I,{name:"copy"})]})}},6473:()=>{},6862:(e,t,n)=>{"use strict";n.d(t,{DocsSearchTrigger:()=>R});var a,r=n(1778),i=n(5226),o=n(4527);let s=[{slug:"index",title:"Welcome to AgentTwin",group:"Start here",headingText:"",headingId:"",text:"The handbook from repository discovery to a reproduced failure and a verified application fix."},{slug:"index",title:"Welcome to AgentTwin",group:"Start here",headingText:"Start with your project",headingId:"start-with-your-project",text:"Run this inside your repository with Node.js 22.12 or newer: npx agenttwin init Review the generated discovery. Init can offer an installed OpenCode session; other coding agents can use .agenttwin/AGENT-TASK.md . Analysis identifies candidates, required dependencies and missing inputs. It does not prove a workflow works. Connect your individual AgentTwin account in the dashboard . Run npx agenttwin login , complete the browser connection, then run npx agenttwin sync . Automation can supply AGENTTWIN TOKEN to send reviewed discovery metadata. You can also import .agenttwin/inventory.json manually. Discover, prepare, execute and inspect your actual code. Environment, Workflows, Runs, Settings and the account menu. Supported contracts and remaining gaps. Understand starting state, credentials and sandbox boundaries."},{slug:"index",title:"Welcome to AgentTwin",group:"Start here",headingText:"Coverage is explicit",headingId:"coverage-is-explicit",text:"The runtime supports custom HTTP collections, a bounded Slack API subset, PostgreSQL and Redis. Catalog selection declares a dependency; it does not implement a vendor adapter or create a real provider account. Unsupported behavior must be reviewed before execution. The product covers many workflows, including support, notifications, sales, payments and agent side effects. Refunds are an example, not the product boundary."},{slug:"index",title:"Welcome to AgentTwin",group:"Start here",headingText:"Read the handbook from start to finish",headingId:"read-the-handbook-from-start-to-finish",text:"Chapter What you will learn --- --- First verified fix Execute an example failure and prove a source-only repair Discover and test Move from repository signals to reviewed execution Prepare application code Build an entrypoint, configure twins and review the bundle Reusable worlds Provision, run, reset, extend and clean up Scenarios and fixtures Link synthetic identities and preserve immutable baselines Fidelity Understand operation coverage and provider limitations Safety Choose local or cloud boundaries and review credentials Evidence and retesting Diagnose failures and compare unchanged checks CLI and MCP Find commands, artifacts and coding-agent tools Troubleshooting Resolve setup, account and execution failures For a first-time user, start with the local quickstart before connecting a real project. For an existing workflow, begin with preparation. For a failed run, begin with evidence. The handbook describes current implemented contracts; planned features remain labeled in the roadmap."},{slug:"quickstart",title:"Your first verified fix",group:"Start here",headingText:"",headingId:"",text:"Run a real failure, inspect its evidence and verify a source-only repair."},{slug:"quickstart",title:"Your first verified fix",group:"Start here",headingText:"What you will accomplish",headingId:"what-you-will-accomplish",text:"The primary entry point is now: 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."},{slug:"quickstart",title:"Your first verified fix",group:"Start here",headingText:"1. Generate the example",headingId:"1-generate-the-example",text:"Run from a working directory where AgentTwin can save its local records: 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: 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."},{slug:"quickstart",title:"Your first verified fix",group:"Start here",headingText:"2. Save the baseline and create a world",headingId:"2-save-the-baseline-and-create-a-world",text:"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."},{slug:"quickstart",title:"Your first verified fix",group:"Start here",headingText:"3. Reproduce and inspect",headingId:"3-reproduce-and-inspect",text:"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."},{slug:"quickstart",title:"Your first verified fix",group:"Start here",headingText:"4. Patch application source only",headingId:"4-patch-application-source-only",text:"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. 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."},{slug:"quickstart",title:"Your first verified fix",group:"Start here",headingText:"5. Inspect in the dashboard and clean up",headingId:"5-inspect-in-the-dashboard-and-clean-up",text:"Open Runs 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. npx agenttwin world teardown --id WORLD ID --json Teardown closes the world endpoints. Keep receipts as evidence. Next, prepare your own workflow or read about scenario versions ."},{slug:"status",title:"What works today",group:"Start here",headingText:"",headingId:"",text:"Shipped capabilities, engineering verification and remaining limitations."},{slug:"status",title:"What works today",group:"Start here",headingText:"Remaining gaps",headingId:"remaining-gaps",text:"Arbitrary vendor API compatibility, real third-party account provisioning, native macOS execution, universal workflow extraction and unattended repairs are not implemented. Reviewed local Chromium recipes, bounded background completion, immutable incident regressions and a protected PR check template are available. Protected browser/background and PostgreSQL/Redis CI execution remain unsupported. Coding-agent analysis still needs reviewed invocation, fixtures and outcome expectations. The API uses a single-instance durable disk store. Distributed scheduling, billing, deletion reconciliation and complete production monitoring remain work to do."},{slug:"status",title:"What works today",group:"Start here",headingText:"Verification and data",headingId:"verification-and-data",text:"Engineering checks passed hosted execution, configured PostgreSQL/Redis assertions, account isolation/revocation, cancellation and persistence. The verified October 14 checkout passed 151 CLI tests and 17 web evidence tests. The guided npx agenttwin init control menu adds seeded timeout-after-write exploration, captured-source replay, unchanged-check patch verification and saved trial regressions. Seeds control fault selection and delays, not OS scheduling; public npx use requires the updated package to be published. Official Stripe SDK calls, runtime observation, Chromium recipes, background completion, incident imports and CI installation are covered. A real Docker check reproduced duplicate writes, passed the patched commit with unchanged checks, and ignored candidate changes to the grading specification. The packaged MCP loop reproduced duplicate writes, patched only source, reran unchanged checks, verified the receipt and exercised reset, extension and teardown. The October 18 source increment (0.3.8, not yet npm latest when checked October 19) adds thirteen vendored HTTP twins (GitHub, Linear, Notion, HubSpot, Shopify, Datadog, Gmail, Google Calendar, GitLab, Jira, Discord, Twilio, Zendesk), client-side seeded runs with exact replay , seed-matrix verdicts, the bounded shrink bisection, blackhole/server-error/duplicate-write fault classes, named property checks, and the public docs v1/ai/search endpoint; 348 CLI tests and a clean typecheck cover the release. Dashboard checks verified saved preferences, account connect/disconnect and full-width sidebar collapse on desktop and mobile. These checks are not customer adoption evidence or proof of production equivalence. The production dashboard starts with an empty inventory and receipt list. The separate prototype uses fictional scenarios; its outcomes are scripted."},{slug:"status",title:"What works today",group:"Start here",headingText:"Latest integration verification",headingId:"latest-integration-verification",text:"Main commit 79cbcd3 combines returning-user onboarding and project removal with organization SSO/Keycloak work. Its CLI and docs GitHub checks passed. Combined local verification passed 358 CLI tests (including a browser-suite rerun after installing Chromium), 17 web tests, production builds and browser onboarding/project-removal checks. Commit 3328277 adds shared-context automation with six passing focused tests and a successful GitHub metadata sync. These are recorded engineering results; this documentation update did not rerun those suites. Live OAuth/OTP acceptance, deployment provenance, clean npm onboarding and a complete real pilot remain separate gates."},{slug:"concepts",title:"Worlds, twins, and replicas",group:"Start here",headingText:"",headingId:"",text:"The vocabulary behind AgentTwin: worlds, service twins, replicas, baselines, and regression artifacts."},{slug:"concepts",title:"Worlds, twins, and replicas",group:"Start here",headingText:"Core vocabulary",headingId:"core-vocabulary",text:"Term Meaning --- --- World A set of service twins plus the shared entities and events that link them. Twin A service stand-in that implements the subset of provider behavior a workflow depends on. Replica A disposable, isolated test copy of a world, created from a baseline. Baseline The versioned starting state a run begins from and can be restored to. Fault injection A deterministic failure applied at a chosen point in a run. Manifest The declared coverage of a replica: what is verified, modeled, or unsupported. Regression artifact The saved starting state, fault point, input, and assertions from a reproduced incident."},{slug:"concepts",title:"Worlds, twins, and replicas",group:"Start here",headingText:'Why "world" and not "mock"',headingId:"why-world-and-not-mock",text:"One customer should be the same logical person in a billing system, a CRM, an inbox, and a support tool. A refund can update billing state, emit a webhook, change an internal record, and trigger a notification. A world evaluates that whole chain, not a single endpoint in isolation."},{slug:"concepts",title:"Worlds, twins, and replicas",group:"Start here",headingText:"What makes a world useful",headingId:"what-makes-a-world-useful",text:"- Shared state — related records across services represent the same people, accounts, and business events. - Observable effects — writes and asynchronous events are recorded so a developer can inspect what actually changed. - Repeatability — a baseline can be restored, a run repeated, and time or randomness controlled so failures can be compared. - Branching — one baseline can be explored under several independent scenarios without contaminating the others. - Failure controls — supported faults can occur at meaningful points, including after a service has already applied a write. - Outcome verification — correctness is checked against final world state and invariants, not only the agent's natural-language explanation. - Honest fidelity — each twin should state what is supported, what has been verified, what is unknown, and when verification last ran. Current runs use explicit fixtures, supported service contracts and fresh sandbox provisioning. Automatic shared-identity compilation, coordinated snapshots and control of all clocks or randomness are outside current coverage."},{slug:"concepts",title:"Worlds, twins, and replicas",group:"Start here",headingText:"The agent should not have to know",headingId:"the-agent-should-not-have-to-know",text:"The agent should not have to know whether it is talking to production or a test world beyond the configuration boundary. The developer, however, should always be able to tell which world is active and what that world can faithfully simulate. How a replica publishes its limits: verified, modeled, and unsupported behavior."},{slug:"workflow",title:"Discover, test and retest",group:"Use your application",headingText:"",headingId:"",text:"The usable path from repository discovery to evidence from a CLI or cloud run."},{slug:"preparation",title:"Prepare your actual application",group:"Use your application",headingText:"",headingId:"",text:"Turn a discovered candidate into an executable, reviewed test bundle."},{slug:"preparation",title:"Prepare your actual application",group:"Use your application",headingText:"Discovery is the starting point",headingId:"discovery-is-the-starting-point",text:"Run npx agenttwin init inside your application repository. Review .agenttwin/inventory.json and the workflow candidates. An entrypoint or dependency found in source is a candidate, not proof of provider access or a runnable test. Choose one narrow workflow with observable effects. Identify its built Node entrypoint, required inputs, every service operation, synthetic starting records and expected outputs. Other coding agents can use .agenttwin/AGENT-TASK.md ; discovery does not automatically supply a correct executable test."},{slug:"preparation",title:"Prepare your actual application",group:"Use your application",headingText:"Build and configure the entrypoint",headingId:"build-and-configure-the-entrypoint",text:"The runtime does not transpile TypeScript or install application dependencies. Bundle them first and list the required built files. command is an argv array beginning with node . Application file paths resolve relative to the world specification. Configure test clients with generated AGENTTWIN URL and AGENTTWIN TOKEN values. A production SDK requires a supported base-URL override and supported operations; merely replacing a token is insufficient. Use synthetic IDs and avoid copying production credentials into the bundle."},{slug:"preparation",title:"Prepare your actual application",group:"Use your application",headingText:"A preparation contract",headingId:"a-preparation-contract",text:'Save this as preparation.json beside your built workflow.mjs . Replace both discovery IDs with the actual IDs in your inventory. This example prepares a Slack notification; it is not a complete Slack replica. { "schema": "agenttwin/preparation-v1", "workflowId": "YOUR DISCOVERED WORKFLOW ID", "world": { "schema": "agenttwin/world-v1", "name": "notification", "files": "workflow.mjs" , "command": "node", "workflow.mjs" , "timeoutSeconds": 20, "services": { "name": "slack", "adapter": "slack", "collections": {"path": "/messages", "seed": }, {"path": "/channels", "seed": {"id": "C TEST", "name": "test"} } } , "assertions": {"service": "slack", "path": "/messages", "count": 1} }, "mappings": { "toolId": "YOUR DISCOVERED SLACK TOOL ID", "service": "slack", "contract": "slack", "operations": "chat.postMessage" , "reviewed": true } } Your application must send a message to the seeded channel using the generated connection information. The assertion checks one recorded message; add stronger observable checks appropriate to your workflow. Include every recorded candidate operation in reviewed mappings. Preparation rejects missing or unsupported mappings, but cannot establish that static discovery found every behavior in arbitrary source.'},{slug:"preparation",title:"Prepare your actual application",group:"Use your application",headingText:"Prepare, review, execute",headingId:"prepare-review-execute",text:"npx agenttwin prepare --file preparation.json --out .agenttwin/prepared/notification npx agenttwin contracts --file .agenttwin/prepared/notification/agenttwin.world.json --json npx agenttwin run --file .agenttwin/prepared/notification/agenttwin.world.json --json Preparation copies unchanged listed source and writes the world spec, a SHA-256 manifest and agenttwin.bundle.json . It does not execute the application. Review the upload list, bundled source, fixtures and checks before running or uploading. Local execution supports HTTP collections and bounded Slack operations. PostgreSQL and Redis need explicit cloud execution. In Workflows, select the bundle and review its upload before submitting a cloud job. See execution boundaries ."},{slug:"preparation",title:"Prepare your actual application",group:"Use your application",headingText:"Retest the right files",headingId:"retest-the-right-files",text:"For a one-shot prepared bundle, changing your original source does not update a previously copied bundle: rebuild and prepare again. For a reusable world, every run restages the files listed by that world's specification and resets its baseline. Confirm which files the spec references before patching. Do not make a failing check pass by weakening the outcome or removing the fault. Inspect evidence, patch source and compare receipts under unchanged test conditions. Understand the receipt before approving a repair."},{slug:"dashboard",title:"Dashboard guide",group:"Use your application",headingText:"",headingId:"",text:"Use the environment map, workflows, run evidence and working settings."},{slug:"dashboard",title:"Dashboard guide",group:"Use your application",headingText:"Environment",headingId:"environment",text:"Start with Connect project and npx agenttwin init . Agent-analysis and sync instructions expand when needed. The environment map appears after discovery or explicit resource selection. It shows those resources with logos and coverage labels; no demonstration services are preselected. Drag empty canvas space to pan, drag cards to move them, or use zoom, Reset view and Arrange. Search the selected-resource list to find a tool, inspect its coverage and remove it. Removal can be undone. Manual catalog selection is a declaration, not account access or provisioning. Once connected, Environment shows the project name and resource map. View all workflows opens the complete searchable candidate inventory."},{slug:"dashboard",title:"Dashboard guide",group:"Use your application",headingText:"Workflows",headingId:"workflows",text:"Review discovered entrypoints and dependencies. Prepare workflow creates a preparation task for your coding agent using the selected candidate. Package real application files and reviewed operation mappings with the CLI, then upload the resulting bundle to execute. Saved configurations store fixtures, faults and assertions separately from application files. Candidates with recorded evidence link to their run results."},{slug:"dashboard",title:"Dashboard guide",group:"Use your application",headingText:"Runs",headingId:"runs",text:"Run history contains loaded account results and any run.json files you explicitly import. Filter by repository, workflow or outcome; search by test name, revision or run ID. On phones, use Select test to switch results. Active executions and executions without a loaded receipt appear separately above the history; completed tests are not duplicated there. - Summary identifies the workflow, test configuration, repository, tested revision, runner and command. It explains the result and lists each expected outcome beside its observed value. Failed checks appear first. Failure scenarios show whether an injected condition actually activated. - Recorded steps shows observed service activity in sequence, including writes and activated failures. It is not a complete trace of every application step. - Run history lists other tests of the same workflow and repository. Select a baseline to compare checks, revisions and final collection state. Different test configurations, starting state, source digests or fault settings are highlighted; a comparison does not establish the cause of a regression. - Technical details contains execution output, state changes, runner metadata and the original receipt. Use Copy fix prompt for a failed test or Copy review prompt for a passed test. The task includes the workflow, available source entrypoint, tested revision, checks, recorded activity and output. Give it to your coding agent in the original repository, review the fix, rerun the same test and sync the new receipt. Local CLI execution is the default; use a cloud machine only when needed. You can also preview or download the task, export a result, or export the selected comparison. A passed result covers its recorded checks, not every behavior of the workflow. A failed check explains what differed; the underlying cause may still require inspecting source and logs. Missing repository or Git information is shown as Not recorded , not inferred. Imported files remain in the current browser session and are not uploaded. The API currently lists the latest 100 account jobs; Settings controls how many receipts load per refresh, and later refreshes fetch unloaded receipts."},{slug:"dashboard",title:"Dashboard guide",group:"Use your application",headingText:"Account menu",headingId:"account-menu",text:"Click the initials in the top-right corner to open account actions: Account & settings, View runs and Disconnect account. Connection status reflects the current tab. Escape or a click outside closes the menu. Disconnect is available only when an account is connected."},{slug:"dashboard",title:"Dashboard guide",group:"Use your application",headingText:"Settings",headingId:"settings",text:"Setting Effect --- --- Workspace name Changes the dashboard label and initials in this browser Default execution limit Suggested duration in coding-agent preparation tasks; each reviewed bundle keeps its own execution limit Refresh automatically Polls account discovery and active jobs while the tab is visible; manual Refresh workspace remains available Compact lists Reduces workflow and receipt row spacing Reduce motion Disables transitions and smooth scrolling; system preferences are also respected Account connection API URL, token visibility, Connect account, Refresh workspace and Disconnect Use Save preferences to persist changes or Reset defaults to restore browser preferences. Preferences are not shared team settings. Account tokens stay in memory and are cleared on reload or disconnect; they are not saved with preferences."},{slug:"dashboard",title:"Dashboard guide",group:"Use your application",headingText:"Navigation and storage",headingId:"navigation-and-storage",text:"The top navigation contains Home, Environment, Workflows, Runs and Settings. The logo returns to Home. Home uses the full-width artwork layout. Other views have a collapsible project sidebar; closing it leaves a full-width content column. Narrow screens use the top navigation and a short repository row. Documentation uses a book icon; infrastructure implementation labels do not occupy the sidebar. Manual declarations, map layout and dashboard preferences persist in browser storage. Imported discovery and receipts stay in memory. Synced discovery and submitted run evidence persist on the account’s API store. Sync sends metadata; executing a reviewed bundle uploads the selected application files. No production OAuth session or production account is cloned. Open the dashboard . The compatibility dashboard is available at the API origin ."},{slug:"dashboard",title:"Dashboard guide",group:"Use your application",headingText:"Failure scenarios",headingId:"failure-scenarios",text:"In Workflows → Advanced: saved configurations and failure scenarios → Edit configuration , select healthy execution or Timeout after write , choose a service collection, and set the response delay. Apply the scenario to the draft, save or export it, and rebuild your application bundle before uploading. Previously reviewed bundles are not changed by this editor. Timeout after write commits a write before delaying its response. Your application decides whether to retry. Inspect fault activation and final-state assertions in Runs to detect duplicate effects. Other fault types are not currently implemented. Settings includes a results-per-refresh limit for larger workspaces. Account changes clear transient resource selections, receipts, prepared uploads and upload approval. Server quotas and organization access policies are not browser preferences."},{slug:"dashboard",title:"Dashboard guide",group:"Use your application",headingText:"Guided workflow",headingId:"guided-workflow",text:"Home shows the next action for your connected project, its detected resources, workflow candidates, recent results, active work and failing assertions. The workflow assistant opens from a compact dock at the bottom of Home. The artwork fades behind the workspace and carries “What should your agent test?”. Customize lets you choose which overview cards appear; those choices and your company/name preferences are saved in this browser. Workflows shows ten candidates per page and searches the complete inventory. Selecting a workflow opens a focused preparation guide with a task for your coding agent and the upload step. Saved JSON configurations and failure controls remain under Advanced: saved configurations and failure scenarios . Preparing application files still happens in your repository; dashboard chat cannot do it automatically."},{slug:"dashboard",title:"Dashboard guide",group:"Use your application",headingText:"Repositories and chat",headingId:"repositories-and-chat",text:"Sync each repository with the same AgentTwin account. The sidebar lists synced repositories and the selected repository’s workflow candidates; selecting a repository changes its environment, saved contracts and chat context. Repository names identify inventories, so use distinct names for separate products. Run history currently spans the account. The sidebar is hidden in Settings. Open the chat dock to see its connection status. Connect your account in Settings before sending a message. Chat explains discovery metadata, saved contracts and selected run evidence; use Workflows to prepare and execute code."},{slug:"dashboard",title:"Dashboard guide",group:"Use your application",headingText:"CLI tests and Git activity",headingId:"cli-tests-and-git-activity",text:"Test reviewed bundled Node workflows through npx agenttwin run --file path/to/agenttwin.world.json from the original repository. This uses in-process HTTP twins by default. Review output and fixtures, then run npx agenttwin sync to send discovery, Git metadata and CLI results to the website. CLI execution uses your machine and is not a VM isolation boundary. Select --runtime hosted or --runtime e2b explicitly for a workflow that needs a cloud machine. PostgreSQL and Redis worlds currently require cloud execution. There is no automatic VM provisioning for discovery, chat or dashboard viewing. Home shows recorded test results, adapter activities and failed checks. Git activity shows up to 100 commits from 14 days, total repository commits, branch and HEAD. Changed workflow entrypoint paths are flagged since the previous sync. Runs retain the tested SHA and source digests; older passing tests do not prove a newer commit passes. This does not yet trace transitive changes across every workflow."},{slug:"dashboard",title:"Dashboard guide",group:"Use your application",headingText:"Workflow review",headingId:"workflow-review",text:"Workflows separates discovered code paths from recorded test evidence. Filter by activity, or choose Not tested , Needs attention , Retest changes , or Last test passed . Each card shows its dependencies and preparation needs; expand Source and setup to inspect its entrypoint and open resource setup. Test status only uses receipts with a matching workflow ID and recorded repository. Missing repository context cannot establish coverage. A changed entrypoint or newer Git revision marks a previously passing workflow for retesting. Counts reflect loaded results, not every historical test. Choose Prepare a test to preview, copy or download a task for your coding agent. The task includes the latest recorded result when available. Review the generated files and assertions, run locally, then sync. Expand cloud execution only when the workflow requires a cloud machine."},{slug:"dashboard",title:"Dashboard guide",group:"Use your application",headingText:"Time-of-day artwork",headingId:"time-of-day-artwork",text:"Home artwork spans the full width, extending behind the assistant and project banner before fading at the top of the workspace cards. Its height adjusts with the layout. It uses your browser’s local time: a bay sunrise from 5am–noon, sunny Golden Gate from noon–5pm, and the moonlit coast from 5pm–5am. It checks again when you return to the tab and once a minute while open. No location permission is needed. Customize → Preview background lets you inspect each scene; previews last for this tab session, and new visits use the automatic schedule."},{slug:"stack-loop",title:"From discovery to a verified fix",group:"Use your application",headingText:"",headingId:"",text:"Observe dependencies, run browser and service workflows, preserve incident regressions and verify committed patches."},{slug:"stack-loop",title:"From discovery to a verified fix",group:"Use your application",headingText:"Find dependencies used at runtime",headingId:"find-dependencies-used-at-runtime",text:"Run a reviewed Node application with instrumentation. By default, observed HTTP calls are recorded and blocked before transmission: agenttwin observe -- node app.mjs agenttwin services list --json agenttwin services confirm --host api.stripe.com --decision include agenttwin discover --json A confirmation adds a dependency to inventory; it does not allow requests or install an adapter. To exercise a permitted destination, explicitly pass --allow-host HOST . Observation starts with only PATH and NODE ENV=test ; use repeatable --env-key NAME for environment variables you deliberately want to forward. Request URLs, headers, payloads and application output are omitted from observations. This instruments Node fetch/http/https. Native clients, direct sockets, subprocess traffic and unexercised branches remain outside coverage. It is not an operating-system network sandbox. Discovery also identifies route callbacks and queue handlers as candidates; invocation and business expectations still require review."},{slug:"stack-loop",title:"From discovery to a verified fix",group:"Use your application",headingText:"Account for every service",headingId:"account-for-every-service",text:"After discovery, run agenttwin services coverage --json . Every application dependency appears with its required operations, available provider subset or real engine, limitations, and the next action for missing coverage. Development tooling is excluded. An available adapter does not make the customer workflow verified, and custom collections do not establish vendor compatibility. Build and validate missing operations before claiming complete workflow coverage."},{slug:"stack-loop",title:"From discovery to a verified fix",group:"Use your application",headingText:"Use verified provider operations",headingId:"use-verified-provider-operations",text:"Run agenttwin contracts --json for the operation matrix. Stripe's bounded adapter supports customer create/retrieve/list and payment-intent create/retrieve/confirm, with test payment methods, pagination, idempotency and modeled errors. Slack supports its advertised message/channel/history subset. Custom collections support explicitly defined HTTP operations. Official Stripe SDK conformance tests exercise the supported subset. No real charge is made. Subscriptions, refunds, webhooks, broader object fields and unmodeled parameters are not covered. Unsupported behavior returns 501 and makes the test incomplete."},{slug:"stack-loop",title:"From discovery to a verified fix",group:"Use your application",headingText:"Exercise the application and background work",headingId:"exercise-the-application-and-background-work",text:'A world can include a local browser recipe for a bundled Node server. Install Chromium using npx playwright install chromium from the CLI package directory. Add these fields to a complete reviewed world: { "browser": { "baseUrl": "http://127.0.0.1:4321", "steps": { "action": "goto", "path": "/" }, { "action": "click", "selector": " create-order" }, { "action": "expectText", "selector": " result", "text": "Created" } }, "background": { "service": "orders", "path": "/orders", "count": 1, "timeoutMs": 3000 } } Run with agenttwin run --file agenttwin.world.json --runtime local . The Node server starts, browser actions execute, and the background check waits for matching collection state. Receipts include browser step outcomes and a screenshot when capture succeeds. Browser requests outside the application and configured twins are blocked and recorded as incomplete coverage. Server code still has the local process\'s host access; this is not a VM sandbox. Browser/background recipes currently require local execution. Hosted submissions reject them before queuing a job. Protected Docker approval also returns incomplete for those recipes until its browser runner is implemented. Background checks do not replicate Bull, SQS or arbitrary queue semantics.'},{slug:"stack-loop",title:"From discovery to a verified fix",group:"Use your application",headingText:"Trace failures and validate a repair",headingId:"trace-failures-and-validate-a-repair",text:"Service events from local instrumented execution carry application-reported call sites. agenttwin receipt --id RUN ID --json links those events and stack frames to tested source files, checks source freshness, and produces repair hypotheses. These locations guide investigation; they do not prove a root cause. Patch application code and rerun the same fixtures, fault and outcomes. A suggestion is unvalidated until execution proves it against unchanged checks. The dashboard's Recorded steps view shows reported call sites; Technical details shows available browser evidence."},{slug:"stack-loop",title:"From discovery to a verified fix",group:"Use your application",headingText:"Turn an incident into a permanent regression",headingId:"turn-an-incident-into-a-permanent-regression",text:"Start with a scoped exported incident containing a linked scenario. The repository includes a runnable example in examples/incident-regression . agenttwin incident import --file incident.json --out reviewed-preview.json Review the redacted records and define the intended outcomes in the world. agenttwin regression save --file agenttwin.world.json \\ --id retry safety --incident reviewed-preview.json Redaction preserves matching identities across services. It is heuristic, so review unusual fields and free text before sharing. Import does not connect to production or infer business correctness. Regression definitions are immutable; change their identifier when deliberately changing the contract."},{slug:"stack-loop",title:"From discovery to a verified fix",group:"Use your application",headingText:"Add coding agents and pull requests",headingId:"add-coding-agents-and-pull-requests",text:"agenttwin mcp exposes world lifecycle, incident import, regression saving and protected checks to coding agents. For CI, commit the reviewed regression to a trusted baseline and run: agenttwin regression run \\ --regression .agenttwin/regressions/retry safety.json \\ --revision FULL CANDIDATE SHA --baseline FULL TRUSTED BASELINE SHA \\ --runtime docker --json Checks come from the baseline commit; application files come from the exact candidate commit. The candidate runs in a restricted Docker container without the grading files or Docker socket. Use a reviewed, digest-pinned image through AGENTTWIN RUNNER IMAGE . Docker checks currently support HTTP twins; unsupported infrastructure returns incomplete. Install a customer-repository workflow with separately pinned AgentTwin tooling: agenttwin ci install --tooling-revision FULL REVIEWED AGENTTWIN SHA \\ --regression .agenttwin/regressions/retry safety.json The selected tooling commit must be available on GitHub and contain these commands. The installer creates .github/workflows/agenttwin.yml once, refuses to overwrite a workflow, checks out trusted tooling separately from the application, and fetches the exact candidate commit without executing candidate installation scripts. Configure the reviewed runner image and protect the workflow through repository rules or an organization-required workflow. A template alone cannot make a check mandatory. Local process execution supplies evidence but never grants protected approval. The complete loop is: discover → confirm → prepare → reproduce → patch → rerun unchanged checks → retain the regression on future pull requests."},{slug:"worlds",title:"Reproduce, fix, and retest",group:"Build a test world",headingText:"",headingId:"",text:"Use operation contracts, shared scenarios, reusable worlds and coding-agent tools to verify a source fix."},{slug:"worlds",title:"Reproduce, fix, and retest",group:"Build a test world",headingText:"Check service support",headingId:"check-service-support",text:"agenttwin contracts --file agenttwin.world.json --json The operation matrix lists endpoints, authentication, state changes, errors and limitations for each configured service. Current adapters are custom JSON collections and a bounded Slack subset. Collection services support GET/list and POST/create with idempotency replay. Slack supports chat.postMessage and conversations.list/history through JSON or form bodies. An unmodeled operation or parameter returns HTTP 501 with X-AgentTwin-Unsupported: true , records an unsupported event and makes the test incomplete. It is never forwarded to a production API. Discovery of a provider does not establish a working twin for that provider."},{slug:"worlds",title:"Reproduce, fix, and retest",group:"Build a test world",headingText:"Save a shared scenario",headingId:"save-a-shared-scenario",text:"A scenario supplies the exact starting records across services. Its schema is agenttwin/scenario-v1 ; it contains an id, positive integer version, description, service seeds and optional shared entities. Each entity links selectors that resolve to exactly one seeded record in at least two services. For example, a CRM customer and a Slack support channel can refer to the same customer. agenttwin scenario save --file support.scenario.json --json agenttwin scenario list --json agenttwin scenario show --scenario support retry@1 --json Versions are immutable. Increment the version when fixtures change. Scenario services, adapter types and collection paths must match the world exactly. Receipts include the scenario id, version and content digest. You can also use a saved scenario in a one-shot run: agenttwin run --file agenttwin.world.json --scenario support retry@1 --json"},{slug:"worlds",title:"Reproduce, fix, and retest",group:"Build a test world",headingText:"Reuse a world while fixing source",headingId:"reuse-a-world-while-fixing-source",text:"agenttwin world create --file agenttwin.world.json --scenario support retry@1 --ttl 3600 --json agenttwin world run --id WORLD ID --json agenttwin receipt --id RUN ID --json Replace WORLD ID and RUN ID with the returned identifiers. Creation starts a background host and returns loopback service endpoints and fresh test credentials. The lifecycle is provisioning, ready, running and ready again, ending in terminated, expired or failed. Every run stages the current explicitly listed source files and resets service state to the captured baseline. Patch the original source, then run the same world again. Source digests change; the scenario and world specification remain fixed. If you change the specification or scenario, create another world. agenttwin world status --id WORLD ID --json agenttwin world reset --id WORLD ID --json agenttwin world extend --id WORLD ID --ttl 3600 --json agenttwin world teardown --id WORLD ID --json Reset clears mutable state, idempotency keys, events, delayed responses and fault activation. TTL is 1–86400 seconds; expiration closes the endpoints and interrupts active execution. Control requests require a separate token and reject browser origins. Test credentials are stored in private local session metadata; keep them local. Reusable worlds support local HTTP services. They execute Node code on your machine and provide no host network or filesystem isolation. Use one-shot hosted/E2B execution for an isolated workload or PostgreSQL/Redis. World state is held in memory; recreate a world after its host process is lost."},{slug:"worlds",title:"Reproduce, fix, and retest",group:"Build a test world",headingText:"Check outcomes and unwanted effects",headingId:"check-outcomes-and-unwanted-effects",text:'Existing assertions describe required final-state counts, optionally filtered by record fields. Add forbiddenEffects to reject particular recorded operations and preservedState to protect seeded records: { "forbiddenEffects": {"id": "no customer write", "service": "crm", "path": "/customers", "operation": "write"} , "preservedState": {"id": "keep customers", "service": "crm", "path": "/customers"} } These are fields added to a complete world specification, not a standalone specification. A forbidden-effect selector can use where ; supported operations are write, read and replay. Filtered effects without a recorded payload fail conservatively as an evidence gap. Preserved-state selectors compare matching records from before and after execution. The receipt\'s evaluation separates taskPassed from safe. An unsafe result fails the run even if every required task assertion passed. Checks include state JSON pointers and event sequence numbers. Dashboard failure explanations and fix prompts include these checks. Unsupported behavior remains incomplete, and execution errors remain errors. agenttwin verify --file .agenttwin/runs/RUN ID/run.json --world agenttwin.world.json --scenario support retry@1 --json agenttwin sync Verification checks current source/specification digests and recomputes local evidence. It does not independently attest execution. Sync uses your existing account connection and sends receipts to your dashboard; scenario storage and reusable lifecycle remain local.'},{slug:"worlds",title:"Reproduce, fix, and retest",group:"Build a test world",headingText:"Connect a coding agent",headingId:"connect-a-coding-agent",text:'Start the MCP stdio server from your repository: agenttwin mcp Configure your MCP client with command agenttwin , arguments "mcp" , and the repository as its working directory. The client can discover operation contracts, save/list scenarios, create/list worlds, read status, run a scenario, inspect receipts, reset/extend/teardown a world, and verify a run. The intended sequence is create world → run scenario → inspect run → patch application source → run scenario → verify run. The coding agent performs the patch in the original repository. AgentTwin does not silently rewrite source or weaken tests.'},{slug:"worlds",title:"Reproduce, fix, and retest",group:"Build a test world",headingText:"Try the complete loop",headingId:"try-the-complete-loop",text:"agenttwin example --out ./agenttwin-example agenttwin scenario save --file ./agenttwin-example/support.scenario.json --json agenttwin world create --file ./agenttwin-example/reusable.world.json --scenario support retry@1 --ttl 3600 --json agenttwin world run --id WORLD ID --json The example creates duplicate tickets after a lost response. Inspect its failing receipt, then fix workflow.mjs to use a stable idempotency key on the original request and retry. In this example, replacing the safe flag assignment with const safe = true activates that fix. Rerun the same world: it should contain one ticket and one Slack notification, with unchanged customer records. Keep the specification and scenario intact, verify the new receipt and tear down the world."},{slug:"scenarios",title:"Design reproducible scenarios",group:"Build a test world",headingText:"",headingId:"",text:"Seed linked identities, version fixtures and keep a stable baseline for retests."},{slug:"scenarios",title:"Design reproducible scenarios",group:"Build a test world",headingText:"World versus scenario",headingId:"world-versus-scenario",text:"The world specification defines executable files, command, services, faults and checks. A scenario supplies versioned starting records for those services. The scenario does not replace the application's code or prove provider fidelity. Use a named scenario when several tests need the same customer, order or channel identities. Choose synthetic data that captures the failure conditions. The same identifier alone is not enough: record the relationship and validate that each selector resolves to one record."},{slug:"scenarios",title:"Design reproducible scenarios",group:"Build a test world",headingText:"Complete linked fixture",headingId:"complete-linked-fixture",text:'{ "schema": "agenttwin/scenario-v1", "id": "support customer", "version": 1, "description": "One synthetic customer linked to a support channel", "services": {"name": "crm", "adapter": "json-collection", "collections": {"path": "/customers", "seed": {"id": "customer 1", "channel": "C TEST"} } }, {"name": "slack", "adapter": "slack", "collections": {"path": "/channels", "seed": {"id": "C TEST", "name": "support"} }, {"path": "/messages", "seed": } } , "entities": { "id": "customer 1", "refs": {"service": "crm", "path": "/customers", "where": {"id": "customer 1"}}, {"service": "slack", "path": "/channels", "where": {"id": "C TEST"}} } } The world using this scenario must declare the same services, adapter types and collection paths. Entity references must cover at least two services; zero or multiple matching records are invalid. The shared entity is a validated seed relationship, not automatic ongoing synchronization between unrelated adapters.'},{slug:"scenarios",title:"Design reproducible scenarios",group:"Build a test world",headingText:"Store and reuse",headingId:"store-and-reuse",text:"npx agenttwin scenario save --file support.scenario.json --json npx agenttwin scenario list --json npx agenttwin scenario show --scenario support customer@1 --json npx agenttwin run --file agenttwin.world.json --scenario support customer@1 --json Saving the same version with identical content is repeatable. Saving changed content under that version fails. Increment version when changing seeds, then create a new world for the new baseline. Stored scenarios live under .agenttwin/scenarios/ ; keep the source JSON in version control if the team needs to recreate them elsewhere."},{slug:"scenarios",title:"Design reproducible scenarios",group:"Build a test world",headingText:"Choose useful test data",headingId:"choose-useful-test-data",text:"Start with the smallest fixture that reproduces the incident: one affected identity, the relevant existing records and explicit empty collections for expected new effects. Include boundary conditions deliberately, such as a duplicate key or an existing notification. More synthetic records do not automatically mean better coverage. For a source-fix comparison, keep the same scenario ID, version and digest. For a new business requirement, version the fixture and explain why checks changed. Receipts preserve scenario provenance so these two kinds of comparison can be distinguished. Automatic production-data import, consistent redaction and live cross-service mutation propagation remain additional work. Current fixtures are reviewed files. See reusable worlds for reset and expiry behavior."},{slug:"fidelity",title:"Fidelity contract",group:"Build a test world",headingText:"",headingId:"",text:"Every replica should publish a versioned manifest that labels each operation verified, modeled, or unsupported."},{slug:"fidelity",title:"Fidelity contract",group:"Build a test world",headingText:"What the manifest records",headingId:"what-the-manifest-records",text:"- Provider version the twin was built against. - Fixture source for starting state and seed data. - Last verification date — when the behavior was last compared with reality. - Configuration fields that were captured, and which were not. - State boundaries — what the replica covers and where it ends. - Known differences from the real provider."},{slug:"fidelity",title:"Fidelity contract",group:"Build a test world",headingText:"Evidence, not just a response",headingId:"evidence-not-just-a-response",text:"A passing response cannot hide a bad write. Every run should show: 1. A trace of provider calls and state transitions, in causal order. 2. A before/after state diff across the systems involved. 3. Assertions against final state and invariants , not only the agent's explanation of what it did. The current runtime records operation coverage, source digests, service events and final-state assertions. Custom HTTP collections and the Slack subset have explicit limits; passing their checks does not establish full provider conformance. PostgreSQL and Redis run as real services in the hosted world. Isolated credentials, sanitized records, and disposable execution."},{slug:"safety",title:"Safety and isolation",group:"Build a test world",headingText:"",headingId:"",text:"Current discovery, credential and hosted execution boundaries."},{slug:"safety",title:"Safety and isolation",group:"Build a test world",headingText:"Execution boundary",headingId:"execution-boundary",text:"Application workflows execute in fresh hosted E2B sandboxes, not local containers. The runtime constructs test credentials and an explicit application environment, runs the application as a non-root user, denies new external guest network connections and checks configured final state. Sandbox deletion is requested after execution with a finite TTL backup. Custom HTTP collections and the supported Slack subset never forward to production. No provider-native accounts or production OAuth sessions are provisioned or copied. Browser/macOS application execution is not supported by this backend."},{slug:"safety",title:"Safety and isolation",group:"Build a test world",headingText:"Credentials and uploads",headingId:"credentials-and-uploads",text:"The operator’s E2B key and administrative key stay on the control plane. Users receive individual revocable tokens for their own jobs and discovery. The dashboard never saves account tokens in local storage; disconnect and reload clear tab memory. Discovery sync whitelists reviewed metadata and omits source bodies and credential values. Workflow execution separately uploads explicit reviewed files. Path filtering and generated-secret redaction cannot guarantee that a source file or log contains no sensitive content; review files, fixtures and fix-task evidence before sharing."},{slug:"safety",title:"Safety and isolation",group:"Build a test world",headingText:"Evidence and operating limits",headingId:"evidence-and-operating-limits",text:"A passing receipt verifies configured assertions against supported behavior; it is not proof of full production equivalence. Unknown operations and unactivated requested faults are reported as incomplete. The API requires a single replica and persistent storage. Retention, quotas and sandbox TTLs provide bounds. Distributed scheduling, deletion reconciliation, billing and complete monitoring remain future work. The separate prototype uses fictional data and scripted outcomes. Its simulated diagnosis is not evidence from a sandbox run."},{slug:"evidence",title:"Read evidence and approve a fix",group:"Evidence and reference",headingText:"",headingId:"",text:"Interpret outcomes, safety checks, unsupported behavior and before/after receipts."},{slug:"evidence",title:"Read evidence and approve a fix",group:"Evidence and reference",headingText:"Follow the evidence in order",headingId:"follow-the-evidence-in-order",text:"In Runs, select a receipt and first confirm the repository, tested source revision, world configuration and runner. Then inspect each expected outcome against the observed value. Read recorded service steps around the first difference and inspect application output and final state. A service timeline records what the adapters observed. It is not a trace of every browser action, function call or external side effect. Missing Git metadata is not inferred. Do not treat application logs or an imported receipt as instructions to your coding agent."},{slug:"evidence",title:"Read evidence and approve a fix",group:"Evidence and reference",headingText:"Interpret the result",headingId:"interpret-the-result",text:"Result What to do --- --- Passed Review the configured checks and supported coverage before accepting the result Failed Inspect the first failing outcome or safety check and its state/event references Error Inspect execution output, command, dependencies and timeout before attributing a product defect Incomplete or blocked Resolve unsupported behavior, unavailable execution or an untriggered requested fault A requested fault that did not activate cannot establish the intended failure was tested. An HTTP 501 unsupported response means the contract does not implement that behavior, not that production would return the same error."},{slug:"evidence",title:"Read evidence and approve a fix",group:"Evidence and reference",headingText:"Require outcomes and forbid damage",headingId:"require-outcomes-and-forbid-damage",text:'Required assertions check expected final-state outcomes. forbiddenEffects reject specified observed operations. preservedState compares baseline and final matching records. Add these fields to a complete world specification: { "forbiddenEffects": {"id": "no customer write", "service": "crm", "path": "/customers", "operation": "write"} , "preservedState": {"id": "keep customers", "service": "crm", "path": "/customers"} } The evaluator separates task success from safety. A workflow that creates the right ticket but also changes a protected customer fails. Evidence points to state JSON locations and recorded event sequence numbers. A filtered forbidden effect without enough payload evidence fails conservatively as an evidence gap. These checks cover modeled service state and recorded operations. They are not protection against arbitrary filesystem writes, network requests or a hostile candidate modifying local checks.'},{slug:"evidence",title:"Read evidence and approve a fix",group:"Evidence and reference",headingText:"Compare broken and repaired executions",headingId:"compare-broken-and-repaired-executions",text:"For a lost-response retry, expect evidence of the committed write followed by the delayed response and retry. A duplicate-write failure should differ from the repaired run's one-record outcome. Confirm any forbidden-effect and preserved-state checks as well. Keep the scenario and specification fixed; change only the justified application code. In Runs, compare checks, final collections, source digests and fault settings. Different seeds, specifications or faults invalidate a simple claim that the source patch alone caused the improvement."},{slug:"evidence",title:"Read evidence and approve a fix",group:"Evidence and reference",headingText:"Verify freshness",headingId:"verify-freshness",text:"npx agenttwin verify --file .agenttwin/runs/RUN ID/run.json --world agenttwin.world.json --scenario support retry@1 --json Use the scenario actually used by the run. Verification recomputes local evidence and compares current source/specification provenance. It does not rerun the application or independently attest that a receipt is authentic. Run again after a code change; an old passing receipt is not evidence for new source."},{slug:"evidence",title:"Read evidence and approve a fix",group:"Evidence and reference",headingText:"Share and retain the result",headingId:"share-and-retain-the-result",text:"npx agenttwin sync sends reviewed receipts to the connected account. You can also import run.json in Runs without uploading it. Fix & retest exports an evidence-based coding task; review its proposed change and run the unchanged checks again. Keep the specification, scenario source and receipts alongside the application change where appropriate. Automatic generation of permanent browser regression tests and protected independent grading are not implemented. Troubleshooting covers common evidence gaps."},{slug:"cli",title:"CLI and coding-agent reference",group:"Evidence and reference",headingText:"",headingId:"",text:"Find commands, local artifacts, exit codes and all twelve coding-agent tools."},{slug:"cli",title:"CLI and coding-agent reference",group:"Evidence and reference",headingText:"Run commands from your repository",headingId:"run-commands-from-your-repository",text:"Use npx agenttwin for an installed release, or a built checkout's CLI for checkout-only features. Node.js 22.12+ is required. --json writes structured results to stdout and logs to stderr. Substitute returned IDs for uppercase placeholders. Command Purpose --- --- init Discover dependencies and workflow candidates login Connect the terminal to your dashboard account sync Send reviewed discovery and receipts to that account example --out ./agenttwin-example Generate runnable example source and worlds prepare --file preparation.json Validate mappings and create an explicit application bundle contracts --file agenttwin.world.json --json Inspect adapter operation coverage run --file agenttwin.world.json --json Execute a one-shot local world run --runtime hosted --file agenttwin.world.json Request optional API-managed cloud execution run --runtime e2b --file agenttwin.world.json Use your own configured E2B runtime scenario save --file support.scenario.json --json Validate and save an immutable scenario version scenario list --json List saved versions and digests scenario show --scenario support retry@1 --json Read a saved fixture world create --file agenttwin.world.json --scenario support retry@1 --ttl 3600 --json Start a reusable local HTTP world world list --json List local lifecycle metadata world status --id WORLD ID --json Inspect lifecycle and connection information world run --id WORLD ID --json Reset baseline, stage current listed source and execute world reset --id WORLD ID --json Clear state, keys, events and activated faults world extend --id WORLD ID --ttl 3600 --json Set a ready world's expiry to now plus TTL world teardown --id WORLD ID --json Close services and end the world receipt --id RUN ID --json Inspect recorded checks and a source-fix task verify --file PATH TO RUN JSON --world agenttwin.world.json --json Recompute checks and inspect freshness without execution mcp Serve coding-agent tools over stdio TTL is 1–86400 seconds. Use the optional --scenario id@version on verification when the receipt uses a saved scenario."},{slug:"cli",title:"CLI and coding-agent reference",group:"Evidence and reference",headingText:"Run exit codes",headingId:"run-exit-codes",text:"Code Meaning --- --- 0 Passed 1 Failed or execution error 2 Incomplete or blocked 3 Invalid input Use the receipt's details to distinguish an assertion failure from infrastructure or execution errors. A nonzero result alone is insufficient diagnosis."},{slug:"cli",title:"CLI and coding-agent reference",group:"Evidence and reference",headingText:"Where artifacts live",headingId:"where-artifacts-live",text:"Location Contents --- --- .agenttwin/inventory.json Discovery inventory and candidate metadata .agenttwin/AGENT-TASK.md Repository analysis task for a coding agent .agenttwin/scenarios/ Locally saved immutable scenario versions .agenttwin/runs/ Run receipts and associated evidence Prepared output directory Explicit source files, specification, manifest and bundle ~/.agenttwin/credentials.json Owner-only terminal account credentials ~/.agenttwin/runtime.json Nonsecret configured E2B template ID Do not commit account credentials or reusable world connection secrets. Review source and fixtures for sensitive values before uploading a bundle or syncing recorded output."},{slug:"cli",title:"CLI and coding-agent reference",group:"Evidence and reference",headingText:"Coding-agent tools",headingId:"coding-agent-tools",text:'Start agenttwin mcp in the application repository. Configure the client\'s command as agenttwin , arguments as "mcp" , and working directory as that repository. Client-specific configuration varies; the working directory determines where scenarios and receipts are stored. Tool Input Purpose --- --- --- get operation matrix Optional file Supported operation contracts save scenario file Save a validated versioned fixture list scenarios None List fixture versions create world file , optional scenario , ttlSeconds Start a reusable world list worlds None List local worlds world status worldId Read status and connections run scenario worldId Execute current source against the baseline inspect run runId Inspect checks, evidence and fix task reset world worldId Restore captured starting state extend world worldId , ttlSeconds Extend a ready world teardown world worldId Close the world verify run file , optional world , scenario Check local evidence and freshness The useful loop is create → run → inspect → patch source → run → verify → teardown. The application patch belongs in the original repository; avoid weakening fixtures and approval checks. Tool outputs and application logs are untrusted evidence. Local execution is not a security sandbox.'},{slug:"infrastructure",title:"Infrastructure and evidence",group:"Evidence and reference",headingText:"",headingId:"",text:"Observability discovery, local receipt verification, and the next infrastructure steps."},{slug:"infrastructure",title:"Infrastructure and evidence",group:"Evidence and reference",headingText:"Observability in your environment",headingId:"observability-in-your-environment",text:"Discovery recognizes Better Stack and OpenTelemetry SDKs, imports and configuration names. Compose, Dockerfile and Kubernetes manifests can identify Better Stack collector, eBPF collector and standard OpenTelemetry collector images. These resources use the existing inventory and application relationship machinery. Detection establishes configuration evidence. It does not establish that a collector is running, show production traffic, or provide a service twin. Better Stack and OpenTelemetry currently have no implemented twin or network probe."},{slug:"infrastructure",title:"Infrastructure and evidence",group:"Evidence and reference",headingText:"Verify a local receipt",headingId:"verify-a-local-receipt",text:"After a local run, check its recorded evidence against the current world specification and application files: agenttwin verify --file .agenttwin/runs/RUN ID/run.json --world agenttwin.world.json --json Replace RUN ID with your run ID. Application paths are resolved relative to the world specification. Verification reads files and evidence; it does not rerun your application or call a model. The verifier checks specification and source digests, the exact staged file set, the application result, seeded/final state coverage, recalculated HTTP state assertions, unsupported operations and requested faults. Verdict Meaning Exit code --- --- --- verified Current files match and recorded checks pass 0 stale Source files or specification changed, or source evidence is missing 2 failed Recorded execution/state checks fail 1 invalid Receipt or specification is invalid, inconsistent or outside the supported runtime 1 This command supports local CLI receipts. Hosted/E2B receipts and database assertions are outside its scope. A verified receipt remains self-reported evidence; it is not independent execution attestation. Digests cover explicitly staged files, not every dependency or external service. The command does not update dashboard status or automatically gate sync."},{slug:"infrastructure",title:"Infrastructure and evidence",group:"Evidence and reference",headingText:"Infrastructure direction",headingId:"infrastructure-direction",text:"The next operational work is correlated telemetry for API requests, queue wait, execution duration and sandbox cleanup, followed by a durable store and queue before scaling replicas. Future scenario evaluation should separately check required outcomes and forbidden side effects. Useful references are the Better Stack collector , Claude Referee , and ArgaBench . AgentTwin's changes are original implementations. No external collector or evaluation service was installed by this work."},{slug:"troubleshooting",title:"Troubleshoot setup and tests",group:"Help and direction",headingText:"",headingId:"",text:"Resolve account, discovery, adapter, execution and verification problems."},{slug:"troubleshooting",title:"Troubleshoot setup and tests",group:"Help and direction",headingText:"Start with the failed boundary",headingId:"start-with-the-failed-boundary",text:"Identify whether the problem is discovery, account connection, preparation, service support, application execution or evidence. Keep the run ID, command, exit code and receipt. Review logs locally and redact sensitive values before sharing them."},{slug:"troubleshooting",title:"Troubleshoot setup and tests",group:"Help and direction",headingText:"CLI command is missing or Node fails",headingId:"cli-command-is-missing-or-node-fails",text:"Run node --version and inspect the CLI version/help. Node.js 22.12+ is required. In this repository, nvm use selects the checked-in runtime version. A previously published package may lack checkout-only world commands: build and use this repository's CLI rather than assuming the docs describe your old installed package."},{slug:"troubleshooting",title:"Troubleshoot setup and tests",group:"Help and direction",headingText:"Onboarding says the account could not be loaded",headingId:"onboarding-says-the-account-could-not-be-loaded",text:"Use Try again and confirm the configured AgentTwin API is reachable. A running website does not establish that the separate account API is healthy. Check the browser's failed account request and API server logs. Sign in again if the session is unauthorized. Do not change assertions or fixtures to resolve an account failure. Browser appearance preferences can be edited without a loaded account; terminal approval and account project checks require the authenticated account. Dashboard guide explains connection state and refresh."},{slug:"troubleshooting",title:"Troubleshoot setup and tests",group:"Help and direction",headingText:"Discovery finds too much or nothing",headingId:"discovery-finds-too-much-or-nothing",text:"Run init from the actual application root. Inspect recorded source and dependency evidence before accepting a candidate. Use --exclude for unused integrations and rediscover after source changes. Environment keys alone do not create supported adapters. Agent analysis and static discovery produce candidates requiring review."},{slug:"troubleshooting",title:"Troubleshoot setup and tests",group:"Help and direction",headingText:"Preparation rejects a workflow",headingId:"preparation-rejects-a-workflow",text:"Use actual discovery workflow and tool IDs. Include reviewed mappings for every recorded candidate operation. Confirm the entrypoint is built, listed files exist relative to the spec, and the command begins with node . Unsupported SDK operations require additional adapter work or a narrower test, not a fabricated mapping marked reviewed."},{slug:"troubleshooting",title:"Troubleshoot setup and tests",group:"Help and direction",headingText:"Module missing or production requests still occur",headingId:"module-missing-or-production-requests-still-occur",text:"Bundle application dependencies before preparation. The runtime does not install them. Override service base URLs with the generated twin endpoint and use its generated token. Inspect the application client's configuration; changing credentials alone does not redirect a production URL. Local application code has host network access, so review execution paths before running."},{slug:"troubleshooting",title:"Troubleshoot setup and tests",group:"Help and direction",headingText:"HTTP 501 or incomplete coverage",headingId:"http-501-or-incomplete-coverage",text:"Inspect contracts and the receipt's unsupported event. Unknown methods or parameters are deliberately rejected and are not proxied to production. Current Slack support excludes pagination, threads, files and OAuth. Either stay within the implemented contract or implement and validate the missing adapter operation before claiming coverage."},{slug:"troubleshooting",title:"Troubleshoot setup and tests",group:"Help and direction",headingText:"Requested failure never activated",headingId:"requested-failure-never-activated",text:"Check the application's actual method/path and recorded operations against the fault configuration. Ensure the relevant write was reached and the client has a timeout that exposes the delayed response. An untriggered requested fault makes the intended failure test incomplete. Do not remove the fault merely to obtain a passing result."},{slug:"troubleshooting",title:"Troubleshoot setup and tests",group:"Help and direction",headingText:"Same scenario version cannot be saved",headingId:"same-scenario-version-cannot-be-saved",text:"Versions are immutable. Identical content can be saved again; modified content needs a higher version. Check cross-service references for exactly one matching seeded record. Use a new world for a changed baseline and keep the previous version for comparisons."},{slug:"troubleshooting",title:"Troubleshoot setup and tests",group:"Help and direction",headingText:"World expired or disappeared",headingId:"world-expired-or-disappeared",text:"Inspect world status . Expiration closes endpoints and interrupts active execution. A world cannot be revived after termination or expiry; create another one. Extend a ready world before its TTL elapses. State is held in the host process's memory and is not recoverable after that process is lost."},{slug:"troubleshooting",title:"Troubleshoot setup and tests",group:"Help and direction",headingText:"Tests pass but the repair is unconvincing",headingId:"tests-pass-but-the-repair-is-unconvincing",text:"Inspect required outcomes, forbidden effects and protected starting records. Confirm the fault activated and that the test actually reached the failing operation. Compare scenario/specification digests and source changes. Add missing meaningful checks as a separately reviewed test change; do not pretend changing checks proves a source-only repair."},{slug:"troubleshooting",title:"Troubleshoot setup and tests",group:"Help and direction",headingText:"Receipt is stale after a patch",headingId:"receipt-is-stale-after-a-patch",text:"Run again. For a prepared one-shot bundle, rebuild and prepare the changed source first. For a reusable world, confirm the listed source files are the ones you edited. Verify the new receipt against current source, world and scenario; verification never executes application code."},{slug:"troubleshooting",title:"Troubleshoot setup and tests",group:"Help and direction",headingText:"Cloud execution is unavailable",headingId:"cloud-execution-is-unavailable",text:"Select cloud execution explicitly only when needed. API-managed cloud jobs require an operator-configured runtime. Direct E2B requires your own key and template setup. A gateway can serve accounts and synced evidence without cloud credentials; that does not mean cloud execution is provisioned. PostgreSQL and Redis worlds require cloud execution today."},{slug:"troubleshooting",title:"Troubleshoot setup and tests",group:"Help and direction",headingText:"Runs is empty",headingId:"runs-is-empty",text:"Discover and run in the intended repository, then connect the terminal and sync. Or import a run.json receipt manually. Manual imports disappear on page reload and are not uploaded. Browser connection tokens stay in page memory; reconnect if needed and use workspace refresh to load account results. For the verified end-to-end path, return to your first verified fix ."},{slug:"faq",title:"FAQ",group:"Help and direction",headingText:"",headingId:"",text:"Practical answers about discovery, supported execution, accounts and data."},{slug:"faq",title:"FAQ",group:"Help and direction",headingText:"Can I use AgentTwin now?",headingId:"can-i-use-agenttwin-now",text:"Yes, for explicitly configured bundled Node workflows using supported operations. Run npx agenttwin init with Node.js 22.12+, review discovery, prepare your real files and execute locally against supported HTTP twins, or explicitly choose a cloud sandbox. The dashboard supports individual AgentTwin accounts; users can also configure their own E2B account for direct CLI execution."},{slug:"faq",title:"FAQ",group:"Help and direction",headingText:"Does it clone my production accounts or every tool?",headingId:"does-it-clone-my-production-accounts-or-every-tool",text:"No. Discovery finds dependency and code signals. Supported services use synthetic state and fresh test credentials. A catalog entry does not imply a working vendor adapter. Provider-native account provisioning and arbitrary production-environment cloning are not implemented."},{slug:"faq",title:"FAQ",group:"Help and direction",headingText:"Is it only for refunds?",headingId:"is-it-only-for-refunds",text:"No. The product addresses workflows and agent side effects across systems. Four fault classes ship today: timeout-after-write, blackhole (a dependency going dark mid-call), server-error (repeated failures from a dependency) and duplicate-write (first-class duplicate deliveries, suppressed by idempotency keys). Seeded reproduction and named property checks apply across all of them. Refund scenarios are historical examples."},{slug:"faq",title:"FAQ",group:"Help and direction",headingText:"What happens to credentials and data?",headingId:"what-happens-to-credentials-and-data",text:"The operator’s E2B key stays on the API server. Dashboard account tokens remain in tab memory. Sync sends reviewed metadata, not source bodies or credential values. Execution uploads explicitly reviewed application files and fixtures; those files can themselves contain sensitive values, so review the bundle. No production OAuth session is reused. The terminal CLI keeps its saved login and runtime-template config only under ~/.agenttwin/ and does not scan other dotfiles or shell environments for credentials."},{slug:"faq",title:"FAQ",group:"Help and direction",headingText:"Are execution sandboxes zero-retention?",headingId:"are-execution-sandboxes-zero-retention",text:"Application sandboxes are created fresh for one run and deleted when it ends (a finite sandbox TTL is the backstop); source is not retained for recovery. What is retained is the evidence: receipts, with recorded events and before/after state, persist in your account (bounded at 30 days and 1,000 receipts per account) — that retention is the product, not an accident. There is no self-service delete-on-request pipeline for stored receipts yet; account revocation blocks new runs but does not erase history today."},{slug:"faq",title:"FAQ",group:"Help and direction",headingText:"Does init automatically run and repair every workflow?",headingId:"does-init-automatically-run-and-repair-every-workflow",text:"No. Init offers agent-assisted analysis and exports workflow candidates. Inputs, invocation, dependency mappings and assertions need review. Fix & retest exports recorded evidence for your coding agent; a rebuilt bundle and fresh execution are required to verify a repair."},{slug:"faq",title:"FAQ",group:"Help and direction",headingText:"What is saved in the browser?",headingId:"what-is-saved-in-the-browser",text:"Manual declarations, map layout and preferences persist in browser storage. Imported discovery and receipts stay in memory. Account-owned discovery and jobs persist on the API. Tokens are cleared on disconnect or reload."},{slug:"faq",title:"FAQ",group:"Help and direction",headingText:"Is the prototype a real execution?",headingId:"is-the-prototype-a-real-execution",text:"The separate prototype is scripted and uses fictional scenarios. The dashboard and CLI operate on actual imported/synced discovery and hosted run receipts. Engineering examples are not customer references."},{slug:"wedge",title:"Example: timeout after a write",group:"Help and direction",headingText:"",headingId:"",text:"A historical payment example of a general workflow fault class."},{slug:"wedge",title:"Example: timeout after a write",group:"Help and direction",headingText:"The scenario",headingId:"the-scenario",text:"A worker asks a payment provider to create a refund. The provider commits the write, but the response times out. The worker cannot tell whether the refund happened and retries. A weak implementation creates a second refund. A resilient implementation uses an idempotency key and verifies final state. sequenceDiagram participant W as Worker participant P as Payment provider W- P: Create refund (idempotency key) P- P: Commit refund P--xW: Response lost (timeout) W- P: Retry create refund Note over W,P: Weak: a second refund. Resilient: the key returns the original."},{slug:"wedge",title:"Example: timeout after a write",group:"Help and direction",headingText:"What the scenario declares",headingId:"what-the-scenario-declares",text:"--- --- Starting state One eligible payment, zero refunds. Injected condition Commit refund; discard response; allow retry. Expected outcome Exactly one refund record, one customer notification, a recoverable trace. Regression artifact Versioned starting state, fault point, input, and assertions."},{slug:"wedge",title:"Example: timeout after a write",group:"Help and direction",headingText:"Why this wedge",headingId:"why-this-wedge",text:"- Real — this failure class appears in production integrations, not only in theory. - Costly — a duplicate refund moves money and damages trust. - Hard to reproduce — it needs a write that commits and a response that never arrives. - Testable without risk — a developer should be able to reproduce it without credentials, network calls, or a real account. The CLI runtime supports all four fault classes — timeout-after-write, blackhole, server-error and duplicate-write — across the supported HTTP twins (custom JSON collections, Slack, Stripe, and the thirteen vendored twins). Seeded fault scheduling applies to every class except the declared timeout-after-write delay, which stays the user's declared spec. Hosted sandbox runs accept faults too, but a run seed and seed matrices are currently local-runtime only. Prepare and submit your actual workflow code to inspect the write count and fault activation. A custom collection test does not verify Stripe behavior."},{slug:"wedge",title:"Example: timeout after a write",group:"Help and direction",headingText:"What a reproduced failure buys you",headingId:"what-a-reproduced-failure-buys-you",text:'The fault is seeded: from one seed string, trials deterministically derive which collection faults and how long the response is withheld (plus an unfaulted control trial). Seeds cover fault selection and delays, not OS scheduling. A saved trial becomes a named regression you can require in CI, so the fix is proven against unchanged checks and the failing trial carries a seed coordinate in its receipt. In buyer\'s terms: "first failure at seed 000000008f2c41d9, reproduced exactly" replaces "the refunds double sometimes; we could never reproduce it."'},{slug:"wedge",title:"Example: timeout after a write",group:"Help and direction",headingText:"The seeded fault classes",headingId:"the-seeded-fault-classes",text:"Four fault classes ship today, each named by the loss it costs, never the mechanism. The run seed decides which matched requests get faulted, so the same seed plus the same fingerprint recreates the same schedule: - Timeout after write — the write commits, the answer vanishes mid-charge; a weak retry turns one refund into two. The declared delayMs is application-visible spec, never seeded. - Blackhole — the service goes dark mid-charge; no response at all, ever; the caller never learns whether the write committed. - Server error — the dependency starts returning 500s (seeded rejections and an optional seeded delay window), so error paths get exercised. - Duplicate write — two refunds hit at the same time; duplication itself, not a lost response inviting a retry. An idempotency key suppresses it, which is exactly the property worth asserting. Further fault types are deliberately rejected by today's schemas rather than silently ignored, and an untriggered requested fault makes a run incomplete."},{slug:"roadmap",title:"Product roadmap",group:"Help and direction",headingText:"",headingId:"",text:"Current product stage, next milestones and the evidence needed for customer readiness."},{slug:"roadmap",title:"Product roadmap",group:"Help and direction",headingText:"Available foundations",headingId:"available-foundations",text:"The source includes guided repository discovery and reviewed sharing, reusable test worlds, linked scenarios, explicit outcome checks, replay and protected regression tooling. Stripe and Slack plus thirteen additional provider adapters implement bounded subsets; detecting a provider does not establish compatibility with its full API. Four fault classes exist: timeout after a write, dropped responses, server errors and duplicate writes. Seeded selection and delays, captured-source replay, unchanged-check patch verification and bounded fault shrinking are implemented. These do not control arbitrary operating-system scheduling or guarantee deterministic model responses. The dashboard, account-scoped sync, Google/GitHub/OIDC sign-in code and organization-realm selection are implemented. Live release and enterprise acceptance are verified separately from source and local tests."},{slug:"roadmap",title:"Product roadmap",group:"Help and direction",headingText:"1. Close the release gap",headingId:"1-close-the-release-gap",text:"Version 0.3.8 is published on npm, with CLI/MCP reporting aligned and registry integrity matching the tested tarball. Verify the intended website/API rollout and live authentication acceptance. Done when: a clean installation of npx agenttwin init pairs with the right workspace and shares reviewed discovery; installed/deployed revisions and real authentication acceptance are recorded."},{slug:"roadmap",title:"Product roadmap",group:"Help and direction",headingText:"2. Run one real application workflow",headingId:"2-run-one-real-application-workflow",text:"Confirm a pilot workflow's trigger, invocation, runtime, exact service operations and persisted state. Run the actual application revision with test credentials and seeded records. Customer requirements must define the expected outcome and forbidden side effects. Done when: the supported workflow runs end to end, its coverage is visible, and unsupported behavior produces an incomplete result."},{slug:"roadmap",title:"Product roadmap",group:"Help and direction",headingText:"3. Prove provider correctness",headingId:"3-prove-provider-correctness",text:"Expand adapters around the pilot's required operations. Compare behavior with official SDKs and authorized test accounts, including authentication, pagination, mutations, errors, retries, reset and webhooks where needed. Done when: each required operation has a versioned contract, conformance evidence and explicit limitations. Adapter count alone is not the acceptance criterion."},{slug:"roadmap",title:"Product roadmap",group:"Help and direction",headingText:"4. Turn a real failure into a protected regression",headingId:"4-turn-a-real-failure-into-a-protected-regression",text:"Reproduce a meaningful failure, connect evidence to the failing operation, patch application source and rerun unchanged checks. Save the scenario and install a required pull-request check using a trusted grading baseline. Done when: the original code fails, the fix passes, a deliberately reintroduced defect fails, and candidate changes cannot weaken the grading checks. Protected browser/background and database-backed execution still need broader runner support."},{slug:"roadmap",title:"Product roadmap",group:"Help and direction",headingText:"5. Earn repeated pilot use",headingId:"5-earn-repeated-pilot-use",text:"Make onboarding and evidence understandable, measure setup effort and false positives, and observe teams using the checks across releases. Broaden runtime and provider coverage from actual workflow needs. Done when: a pilot can show measured setup time, useful defects, dependable regression results and repeat use. Synthetic demonstrations and engineering tests do not establish adoption or willingness to pay."},{slug:"roadmap",title:"Product roadmap",group:"Help and direction",headingText:"Enterprise and scaling gates",headingId:"enterprise-and-scaling-gates",text:"Implement and verify required team roles, tenant SSO enforcement, audit evidence, retention/deletion controls, monitoring and backup/restore before promising enterprise readiness. Move the single-instance store and scheduler to a suitable distributed design before scaling replicas. Any security controls required by the first pilot take priority before granting that pilot access. Shared agent memory helps the development team coordinate; it does not replace provider conformance, customer outcome checks or operational evidence. Roadmap order is a priority sequence, not a delivery-date commitment."},{slug:"roadmap",title:"Product roadmap",group:"Help and direction",headingText:"First private application slice",headingId:"first-private-application-slice",text:"On October 19, a local test of the actual calendar-reading function reproduced missed appointments on short paginated responses. The captured original fails; an application-only patch passes unchanged checks; replay still reproduces the original failure. The regression and private source stay local. This proves a calendar-read slice, with a controlled transport returning short pages. It does not establish full scheduling, Bun/SQL execution, live Google conformance or a protected customer PR check. The local protected Docker check also rejects the original calendar bundle and accepts the fixed bundle with unchanged trusted checks, even when the candidate attempts to weaken its own regression definition. Private-repository build and required-check installation remain open. Release candidate f9338a5 passed 361 CLI tests, 17 web tests, the website build and fresh tarball installation. npm published 0.3.8 , and public registry integrity matches the tested tarball. Production health is reachable, but email verification is reported disabled and full live sign-in acceptance remains open. These checks do not close P0 or establish complete pilot readiness."},{slug:"prototype",title:"Explore the browser demo",group:"Help and direction",headingText:"",headingId:"",text:"Walk through the five-step prototype: choose a world, review the replica, run, inject a fault, and read the diagnosis."},{slug:"prototype",title:"Explore the browser demo",group:"Help and direction",headingText:"The five-step walkthrough",headingId:"the-five-step-walkthrough",text:"Pick one of eight illustrative worlds and map its production stack before creating an isolated test environment. See the declared boundaries — what is masked, blocked, or captured — before running anything. Run the workflow against a clean, repeatable starting state. For example, commit a refund but discard the response, so the worker's retry has to be safe. Inspect the failed assertion and state difference, copy the fix prompt, and restore the same starting state for a regression run."},{slug:"prototype",title:"Explore the browser demo",group:"Help and direction",headingText:"Run it locally",headingId:"run-it-locally",text:"The demo is a Next.js route in the same website app. Start the development server from the repository root. cd /path/to/AgentTwin npm ci --prefix web npm run dev Open http://localhost:3000/demo/"},{slug:"prototype",title:"Explore the browser demo",group:"Help and direction",headingText:"What the prototype does not do",headingId:"what-the-prototype-does-not-do",text:"The fix prompt is a handoff for your coding agent or developer, with the observed failure and a suggested change. It does not inspect or patch customer code. The recovery preview uses a second scripted fixture. Refreshing the browser resets all session state. - No credentials are requested and no provider APIs are called. - No customer code is executed or modified. - Company names are potential customer examples, not customers or partners. Stacks, records, and incidents are invented for demonstration. For the current inventory of what exists, see What exists today ."}];var d=n(2183),c=n(58),l=n(949);let u=new Set(["the","a","an","and","or","for","of","to","in","on","at","is","are","was","were","be","it","its","you","your","with","that","this","these","those","from","how","do","does","can","i","my","we"]),p=e=>(e.toLowerCase().match(/[a-z0-9]+/g)||[]).filter(e=>e.length>1&&!u.has(e)),h=e=>e.replace(/[.*+?^${}()|[\]\\]/g,"\\$&"),g=(e,t)=>("index"===e?"/docs/":"/docs/".concat(e,"/"))+(t?"#"+t:""),f="agenttwin:docs-search-recent";function m(){try{let e=JSON.parse(localStorage.getItem(f)||"[]");return Array.isArray(e)?e.filter(e=>"string"==typeof e).slice(0,6):[]}catch(e){return[]}}let w=[{title:"Quickstart",href:"/docs/quickstart/",detail:"Run a real failure end to end"},{title:"CLI and MCP reference",href:"/docs/cli/",detail:"Commands, artifacts, exit codes"},{title:"Troubleshooting",href:"/docs/troubleshooting/",detail:"Fix setup and execution problems"},{title:"FAQ",href:"/docs/faq/",detail:"Accounts, data and boundaries"}],v=null;function y(){if(v)return v;let e=s.filter(e=>e.text).map(e=>{let t=p(e.text),n=new Map,a=new Set(p(e.title)),r=new Set(p(e.headingText)),i=new Set(p(e.slug.replace(/-/g," ")));for(let e of t)n.set(e,(n.get(e)||0)+1);return{chunk:e,tf:n,title:a,heading:r,slug:i,length:t.length}}),t=new Map;for(let{tf:n}of e)for(let e of n.keys())t.set(e,(t.get(e)||0)+1);let n=e.reduce((e,t)=>e+t.length,0)/(e.length||1)||1,a=n=>{let a=t.get(n)||0;return Math.log(1+(e.length-a+.5)/(a+.5))};return v={search:t=>{let r=[...new Set(p(t))];if(!r.length)return[];let i=t.trim().toLowerCase().replace(/\s+/g," ");return e.map(e=>{let t=1.2*(.25+.75*e.length/n),o=0;for(let n of r){let r=a(n),i=e.tf.get(n)||0;o+=2.2*i/(i+t)*r,e.title.has(n)&&(o+=3*r),e.heading.has(n)&&(o+=2*r),e.slug.has(n)&&(o+=1.2*r)}return i.includes(" ")&&(e.chunk.text.toLowerCase().includes(i)&&(o+=6),e.chunk.title.toLowerCase().includes(i)&&(o+=8),e.chunk.headingText.toLowerCase().includes(i)&&(o+=4)),{entry:e,score:o}}).filter(e=>e.score>.35).sort((e,t)=>t.score-e.score).slice(0,24).map(e=>e.entry.chunk)}}}function x(e,t){let n=s.find(e=>e.slug===t.slug&&!e.headingText),a=t=>{let n=t.toLowerCase(),a=p(e).map(e=>n.indexOf(e)).filter(e=>e>=0);return a.length?Math.min(...a):-1},r=t.text,i=a(r);if(i<0&&n&&(i=a(r=n.text)),i<0)return((null==n?void 0:n.text)||t.text).slice(0,160);let o=Math.max(0,i-60),d=r.slice(o,o+170).trim();return(o>0?"… ":"")+d+(o+170<r.length?" …":"")}function b(e){let{text:t,terms:n}=e;if(!n.length||!t)return(0,r.jsx)(r.Fragment,{children:t});let a=RegExp("(".concat(n.map(h).join("|"),")"),"gi"),i=t.split(a);return(0,r.jsx)(r.Fragment,{children:i.map((e,t)=>t%2==1?(0,r.jsx)("mark",{children:e},t):(0,r.jsx)("span",{children:e},t))})}let k=null!=(a=l.env.NEXT_PUBLIC_AGENTTWIN_API_URL)?a:"https://api.agenttwin.si",T=/\[([a-z0-9][a-z0-9_#/-]{0,79})\]/gi,I=(()=>{let e=0,t=new Map;return n=>{let a=t.get(n);return a||(a="cite-".concat(e++,"-").concat(n.replace(/[^a-z0-9_-]/gi,"-")),t.set(n,a)),a}})();function j(e){let{passages:t,pending:n,sources:a}=e;return(0,r.jsx)("ul",{className:n?"docs-ask-passages is-pending":"docs-ask-passages",children:t.map(e=>(0,r.jsx)("li",{id:a?"docs-".concat(I(e.id)):void 0,children:(0,r.jsxs)("a",{href:e.href,children:[(0,r.jsx)("strong",{children:e.title}),e.heading!==e.title&&(0,r.jsxs)("span",{children:[" › ",e.heading]}),(0,r.jsx)("span",{className:"docs-passage-text",children:e.text})]})},e.href))})}function S(e){let{open:t,onOpenChange:n}=e,[a,s]=(0,i.useState)("search"),[l,u]=(0,i.useState)(""),[h,v]=(0,i.useState)([]),[j,S]=(0,i.useState)(0),[R,A]=(0,i.useState)({kind:"idle"}),D=(0,i.useRef)(null),E=(0,i.useRef)(null),P=(0,i.useRef)(null),N=(0,i.useRef)(null),L=(0,i.useRef)(!1),q=(0,i.useRef)(""),M=(0,i.useCallback)(()=>{var e;null==(e=N.current)||e.abort(),n(!1)},[n]);(0,i.useEffect)(()=>{let e=e=>{if(document.querySelector(".docs-sidebar.is-open"))return;let t=e.target,a=(null==t?void 0:t.isContentEditable)||["INPUT","TEXTAREA","SELECT"].includes(null==t?void 0:t.tagName);("k"===e.key.toLowerCase()&&(e.metaKey||e.ctrlKey)||"/"===e.key&&!a)&&(e.preventDefault(),n("search"))};return document.addEventListener("keydown",e),()=>document.removeEventListener("keydown",e)},[n]),(0,i.useEffect)(()=>{var e,n,a,r;let i=L.current;if(L.current=t,!1===t){q.current&&(document.body.style.overflow=q.current,q.current=""),null==(n=D.current)||n.close();return}s(t),!1===i&&(q.current=document.body.style.overflow,document.body.style.overflow="hidden",null==(a=D.current)||a.showModal()),null==(e=null!=(r=("ask"===t?P:E).current)?r:E.current)||e.focus()},[t]),(0,i.useEffect)(()=>()=>{var e;return null==(e=N.current)?void 0:e.abort()},[]);let O=(0,i.useMemo)(()=>[...new Set(p(l))],[l]),H=(0,i.useMemo)(()=>l.trim()?y().search(l).map(e=>({chunk:e,snippet:x(l,e)})):[],[l]);(0,i.useEffect)(()=>S(0),[l,a]),(0,i.useEffect)(()=>{var e,t;null==(t=D.current)||null==(e=t.querySelector('[data-result="'.concat(j,'"]')))||e.scrollIntoView({block:"nearest"})},[j]),(0,i.useEffect)(()=>{!1!==t&&v(m())},[t]);let U=(0,i.useCallback)(e=>{if(!e)return void window.scrollTo({top:0,behavior:"smooth"});let t=document.getElementById(e);t&&(t.scrollIntoView({block:"start",behavior:"smooth"}),t.classList.remove("docs-flash-target"),t.offsetWidth,t.classList.add("docs-flash-target"),window.setTimeout(()=>t.classList.remove("docs-flash-target"),900))},[]),F=(0,i.useCallback)(e=>{!function(e){let t=e.trim();if(t.length<2)return;let n=[t,...m().filter(e=>e.toLowerCase()!==t.toLowerCase())].slice(0,6);try{localStorage.setItem(f,JSON.stringify(n))}catch(e){}}(l),M();let t="index"===e.slug?"/docs/":"/docs/".concat(e.slug,"/");if(window.location.pathname===t){U(e.headingId),e.headingId&&(window.location.hash=e.headingId);return}if(e.headingId)try{sessionStorage.setItem("agenttwin:docs-flash",e.headingId)}catch(e){}window.location.assign(g(e.slug,e.headingId))},[M,U,l]);(0,i.useEffect)(()=>{let e=(()=>{try{return sessionStorage.getItem("agenttwin:docs-flash")}catch(e){return null}})();if(!e)return;try{sessionStorage.removeItem("agenttwin:docs-flash")}catch(e){}let t=requestAnimationFrame(()=>window.setTimeout(()=>U(e),80));return()=>cancelAnimationFrame(t)},[U]);let W=(0,i.useCallback)(async e=>{var t;let n=e.trim();if(!n)return;let a=function(e){let t=arguments.length>1&&void 0!==arguments[1]?arguments[1]:6;return y().search(e).slice(0,t).map((t,n)=>({id:"".concat(t.slug,"#").concat(t.headingId||"p".concat(n)).slice(0,80),title:t.title,heading:t.headingText||t.title,href:g(t.slug,t.headingId),text:x(e,t).slice(0,700)}))}(n);A({kind:"loading",passages:a});let r=new AbortController;null==(t=N.current)||t.abort(),N.current=r;try{let e=await fetch("".concat(k,"/v1/ai/search"),{method:"POST",headers:{"Content-Type":"application/json"},body:JSON.stringify({question:n,passages:a.map(e=>{let{id:t,title:n,heading:a,href:r,text:i}=e;return{id:t,title:n,heading:a,snippet:i,url:r}})}),signal:r.signal});if(!e.ok)throw Error(String(e.status));let t=await e.json();if("string"!=typeof t.answer||!t.answer.trim())throw Error("no answer");A({kind:"answer",passages:a,html:function(e){let t=d.xI.parse(e,{async:!1}).replace(T,(e,t)=>'<a href="#'.concat(I(t),'" data-cite="').concat(t,'"><sup>[').concat(t,"]</sup></a>"));return c.A.sanitize(t)}(t.answer)})}catch(e){if((null==e?void 0:e.name)==="AbortError")return;A({kind:"unavailable",passages:a})}},[]),B="search"===a&&!l.trim();return(0,r.jsxs)(r.Fragment,{children:[(0,r.jsxs)("button",{type:"button","aria-label":"Search documentation",className:"docs-search-trigger",onClick:()=>n("search"),children:[(0,r.jsx)(o.I,{name:"search"}),(0,r.jsx)("span",{children:"Search documentation"}),(0,r.jsx)("kbd",{children:"⌘ K"})]}),(0,r.jsx)("dialog",{ref:D,className:"docs-search-dialog","aria-label":"Documentation search and AI answers",onCancel:M,onClose:M,onClick:e=>{e.target===e.currentTarget&&M()},children:(0,r.jsxs)("div",{className:"docs-search-dialog-content",children:[(0,r.jsxs)("div",{className:"docs-search-input",children:["ask"===a?(0,r.jsx)(o.I,{name:"sparkles",className:"docs-spark"}):(0,r.jsx)(o.I,{name:"search"}),"search"===a?(0,r.jsx)("input",{ref:E,type:"text",placeholder:"Search pages, commands, and concepts…","aria-label":"Search documentation",value:l,onChange:e=>u(e.target.value),onKeyDown:e=>{if("ArrowDown"===e.key)e.preventDefault(),S(e=>Math.min(e+1,H.length-1));else if("ArrowUp"===e.key)e.preventDefault(),S(e=>Math.max(0,e-1));else if("Enter"===e.key){var t;let n=null==(t=H[j])?void 0:t.chunk;n&&(e.preventDefault(),F(n))}else"Escape"===e.key&&(e.preventDefault(),M())}}):(0,r.jsx)("textarea",{ref:P,rows:2,placeholder:"Ask anything about AgentTwin, e.g. how do I verify a patch?","aria-label":"Ask the documentation",value:l,onChange:e=>u(e.target.value),onKeyDown:e=>{"Enter"!==e.key||e.shiftKey||(e.preventDefault(),W(l))}}),(0,r.jsxs)("div",{className:"docs-search-tabs",role:"tablist","aria-label":"Search mode",children:[(0,r.jsx)("button",{type:"button",role:"tab","aria-selected":"search"===a,onClick:()=>s("search"),children:"Search"}),(0,r.jsxs)("button",{type:"button",role:"tab","aria-selected":"ask"===a,onClick:()=>s("ask"),children:[(0,r.jsx)(o.I,{name:"sparkles"}),"Ask AI"]})]}),(0,r.jsx)("button",{type:"button","aria-label":"Close",onClick:M,children:(0,r.jsx)("kbd",{children:"Esc"})})]}),B&&(0,r.jsxs)("div",{className:"docs-search-list docs-search-welcome","aria-live":"polite",children:[h.length>0&&(0,r.jsxs)("div",{className:"docs-recent",children:[(0,r.jsx)("p",{className:"docs-search-caption",children:"Recent searches"}),h.map(e=>(0,r.jsxs)("button",{type:"button",className:"docs-recent-item",onClick:()=>u(e),children:[(0,r.jsx)(o.I,{name:"history"}),(0,r.jsx)("span",{children:e})]},e)),(0,r.jsxs)("button",{type:"button",className:"docs-recent-clear",onClick:()=>{try{localStorage.removeItem(f)}catch(e){}v([])},children:[(0,r.jsx)(o.I,{name:"close"}),"Clear recent searches"]})]}),(0,r.jsx)("p",{className:"docs-search-caption",children:"Explore documentation"}),w.map(e=>(0,r.jsxs)("a",{href:e.href,onClick:M,children:[(0,r.jsx)(o.I,{name:"book-open"}),(0,r.jsxs)("div",{children:[(0,r.jsx)("strong",{children:e.title}),(0,r.jsx)("span",{children:e.detail})]})]},e.href))]}),!B&&"search"===a&&(0,r.jsxs)("div",{className:"docs-search-list","aria-live":"polite",children:[(0,r.jsx)("p",{className:"docs-search-caption",children:H.length?"Results for “".concat(l.trim(),"”"):"No results"}),!H.length&&(0,r.jsxs)("p",{className:"docs-search-empty",children:["No matches for “",l.trim(),"”. Try a command like ",(0,r.jsx)("code",{children:"agenttwin init"})," or a topic like scenarios, or"," ",(0,r.jsx)("button",{type:"button",onClick:()=>s("ask"),children:"ask AI instead"}),"."]}),H.map((e,t)=>{let{chunk:n,snippet:a}=e;return(0,r.jsxs)("a",{href:g(n.slug,n.headingId),"data-result":t,className:j===t?"is-selected":"","aria-current":j===t?"true":void 0,onClick:e=>{e.preventDefault(),F(n)},children:[(0,r.jsx)(o.I,{name:n.headingText?"layout":"book-open"}),(0,r.jsxs)("div",{children:[(0,r.jsxs)("strong",{children:[n.title,n.headingText&&(0,r.jsxs)("span",{className:"docs-hit-heading",children:[" › ",n.headingText]})]}),(0,r.jsx)("span",{children:(0,r.jsx)(b,{text:a,terms:O})})]}),(0,r.jsx)("span",{className:"docs-hit-jump","aria-hidden":"true",children:"↵"})]},n.slug+"|"+n.headingId)})]}),"ask"===a&&(0,r.jsx)(C,{state:R,query:l,onSubmit:e=>{e.preventDefault(),W(l)},onReset:()=>{var e;null==(e=N.current)||e.abort(),A({kind:"idle"}),u("")}}),(0,r.jsxs)("div",{className:"docs-search-help",children:[(0,r.jsx)("span",{children:"↑ ↓ to navigate"}),(0,r.jsx)("span",{children:"↵ to open"}),(0,r.jsx)("span",{children:"esc to close"})]})]})})]})}function C(e){let{state:t,query:n,onSubmit:a,onReset:i}=e;return(0,r.jsxs)("div",{className:"docs-search-list docs-ask-panel","aria-live":"polite",children:[(0,r.jsxs)("form",{className:"docs-ask-form",onSubmit:a,children:[(0,r.jsxs)("button",{type:"submit",className:"docs-ask-submit",disabled:!n.trim(),children:[(0,r.jsx)(o.I,{name:"sparkles"}),"loading"===t.kind?"Asking…":"Ask"]}),(0,r.jsx)("span",{className:"docs-ask-hint",children:"Enter to ask \xb7 Shift+Enter for a new line"}),"idle"!==t.kind&&(0,r.jsx)("button",{type:"button",className:"docs-ask-reset",onClick:i,children:"New question"})]}),"loading"===t.kind&&(0,r.jsxs)(r.Fragment,{children:[(0,r.jsxs)("p",{className:"docs-ask-status docs-ask-loading",role:"status",children:["Reading the docs",(0,r.jsx)("span",{className:"docs-ask-dots","aria-hidden":"true"})]}),(0,r.jsx)(j,{passages:t.passages,pending:!0})]}),"answer"===t.kind&&(0,r.jsxs)(r.Fragment,{children:[(0,r.jsx)("article",{className:"docs-ask-answer",onClick:e=>{let t=e.target.closest("[data-cite]");if(!t)return;e.preventDefault();let n=document.getElementById("docs-ask-passage-".concat(t.dataset.cite));n&&(n.scrollIntoView({block:"nearest",behavior:"smooth"}),n.classList.add("docs-passage-focus"),window.setTimeout(()=>n.classList.remove("docs-passage-focus"),1200))},dangerouslySetInnerHTML:{__html:t.html}}),(0,r.jsx)(j,{passages:t.passages,sources:!0})]}),"unavailable"===t.kind&&(0,r.jsxs)(r.Fragment,{children:[(0,r.jsx)("p",{className:"docs-ask-status",children:"The assistant is unavailable right now. Try again shortly."}),t.passages.length>0&&(0,r.jsx)(j,{passages:t.passages})]})]})}function R(e){let{tab:t="search"}=e,[n,a]=(0,i.useState)(!1);return(0,r.jsxs)(r.Fragment,{children:[!1!==n&&(0,r.jsx)(S,{open:n,onOpenChange:a}),(0,r.jsx)("button",{type:"button",onClick:()=>a(t),"aria-haspopup":"dialog","aria-expanded":!1!==n,className:"inline-flex h-9 w-full items-center gap-2 rounded-lg border border-fd-border bg-fd-muted/50 px-3 text-sm text-fd-muted-foreground transition-colors hover:bg-fd-accent hover:text-fd-accent-foreground",children:"ask"===t?(0,r.jsxs)(r.Fragment,{children:[(0,r.jsx)(o.I,{name:"sparkles"}),(0,r.jsx)("span",{className:"flex-1 text-left",children:"Ask AI"})]}):(0,r.jsxs)(r.Fragment,{children:[(0,r.jsx)(o.I,{name:"search"}),(0,r.jsx)("span",{className:"flex-1 text-left",children:"Search docs…"}),(0,r.jsx)("kbd",{className:"bg-fd-muted px-1.5 py-0.5 text-xs font-normal",children:"⌘K"})]})})]})}},7188:()=>{"undefined"==typeof navigator||"undefined"==typeof document||navigator.clipboard||Object.defineProperty(navigator,"clipboard",{value:{writeText:e=>new Promise((t,n)=>{let a=document.createElement("textarea");a.value=e,a.setAttribute("readonly",""),a.style.cssText="position:fixed;top:-9999px;left:-9999px;opacity:0",document.body.appendChild(a),a.select();try{if(!document.execCommand("copy"))throw Error("copy_rejected");t()}catch(e){n(e)}finally{a.remove()}})},configurable:!0})},9694:(e,t,n)=>{"use strict";n.d(t,{DocsCodeBlock:()=>i});var a=n(1778),r=n(4764);function i(e){var t,n,i;let{children:o,...s}=e,d=Array.isArray(o)?o[0]:o,c=null!=(i=null==d||null==(t=d.props)?void 0:t.className)?i:"",l=null==(n=/language-([\w-]+)/.exec(c))?void 0:n[1],u="sh"===l||"bash"===l||"shell"===l||"console"===l?"Terminal":l?l.toUpperCase():"Code";return(0,a.jsx)(r.NG,{title:u,children:(0,a.jsx)("pre",{...s,children:o})})}n(7188)}},e=>{e.O(0,[8056,3916,4705,7903,4816,7358],()=>e(e.s=4318)),_N_E=e.O()}]);