{"openapi":"3.1.0","info":{"title":"SIMULATION.md API","version":"1.0","description":"A skill and simulator for agents about to do something costly or hard to undo. SIMULATION.md is a plain file that describes mock tools, how they can fail, and the rules a run must keep. One small engine runs that file over this site's API and MCP server, in a browser tab, or from a single downloaded file, and the same file and seed give the same log everywhere. Every tool is a mock, every number is an assumption you can see, and a result describes the file, not reality. Read-only, no key, nothing stored. Use at your own risk. simulation.md is provided as is, without warranty. Everything it runs is a mock, and a result describes only the assumptions in the file you sent, not reality, so it may be wrong even when the software works as described. Nothing here is a prediction, a measurement, a test of any real system, a safety assessment, an audit, a certification, or financial, legal, engineering or operational advice. A clean result or a matching hash does not mean anything is safe, compliant, correct or ready. simulation.md never touches a real system, never runs your code on its servers, never stores your files or runs, and never tests, approves or certifies any agent, plan or product. Check everything yourself before you act on it.","termsOfService":"https://simulation.md/terms","license":{"name":"MIT","identifier":"MIT"}},"servers":[{"url":"https://simulation.md"}],"paths":{"/simulation.md":{"get":{"operationId":"getSkill","summary":"The SIMULATION.md skill as Markdown. Add a preset or any setting to write your settings in; notes on clamped or ignored values come back in the X-Settings-Notes header.","parameters":[{"name":"preset","in":"query","required":false,"schema":{"type":"string","enum":["core","recommended","careful","private"]}},{"name":"rehearse_money_over","in":"query","required":false,"description":"Rehearse before moving more than ($). Default 100. Out-of-range values are clamped.","schema":{"type":"number","minimum":0,"maximum":10000000}},{"name":"rehearse_deletes","in":"query","required":false,"description":"Before deleting or overwriting data: always (Always rehearse), bulk (Only for more than one item), never (Don't rehearse). Default bulk.","schema":{"type":"string","enum":["always","bulk","never"]}},{"name":"rehearse_messages_over","in":"query","required":false,"description":"Rehearse before sending to more than (people). Optional; unset clears it. Out-of-range values are clamped.","schema":{"type":"integer","minimum":0,"maximum":10000000}},{"name":"rehearse_fanout_over","in":"query","required":false,"description":"Rehearse before a fan-out of more than (calls). Optional; unset clears it. Out-of-range values are clamped.","schema":{"type":"integer","minimum":0,"maximum":10000000}},{"name":"rehearse_deploys","in":"query","required":false,"description":"Before a deploy or migration: always (Always rehearse), never (Don't rehearse). Optional; unset clears it.","schema":{"type":"string","enum":["always","never","unset"]}},{"name":"min_runs","in":"query","required":false,"description":"Seeds to run, at least (runs). Optional; unset clears it. Out-of-range values are clamped.","schema":{"type":"integer","minimum":10,"maximum":10000000}},{"name":"where","in":"query","required":false,"description":"Where runs happen: any (Any: hosted, tab or local), local_first (Local when there is a shell, hosted otherwise), local_only (Local only, nothing leaves this machine). Default local_first.","schema":{"type":"string","enum":["any","local_first","local_only"]}},{"name":"vary_assumptions","in":"query","required":false,"description":"Assumptions to test for a flip (assumptions). Optional; unset clears it. Out-of-range values are clamped.","schema":{"type":"integer","minimum":1,"maximum":10}},{"name":"use_packs","in":"query","required":false,"description":"Fault packs: always (Always attach a pack to every tool), when_unsure (When you have no numbers of your own). Optional; unset clears it.","schema":{"type":"string","enum":["always","when_unsure","unset"]}},{"name":"ask_over_chance","in":"query","required":false,"description":"Stop and ask if a rule breaks more often than (%). Default 1. Out-of-range values are clamped.","schema":{"type":"number","minimum":0,"maximum":100}},{"name":"on_flip","in":"query","required":false,"description":"If the answer flips near your guess: ask (Stop and ask), measure (Measure that number first, then ask), note (Note it and carry on). Default ask.","schema":{"type":"string","enum":["ask","measure","note"]}},{"name":"placeholders","in":"query","required":false,"description":"If a decision rests on placeholder numbers: ask (Say so and ask), note (Say so and carry on). Optional; unset clears it.","schema":{"type":"string","enum":["ask","note","unset"]}},{"name":"keep_file","in":"query","required":false,"description":"Keep SIMULATION.md: repo (In the repo, next to the code), no (Don't keep it). Optional; unset clears it.","schema":{"type":"string","enum":["repo","no","unset"]}},{"name":"show_replay","in":"query","required":false,"description":"Show the person a replay link: always (Every time), when_broken (When a rule broke), never (Never). Optional; unset clears it.","schema":{"type":"string","enum":["always","when_broken","never","unset"]}},{"name":"retest_exams","in":"query","required":false,"description":"Run the test worlds: on_change (When the model, prompt or tools change), never (Never). Optional; unset clears it.","schema":{"type":"string","enum":["on_change","never","unset"]}}],"responses":{"200":{"description":"The skill","content":{"text/markdown":{"schema":{"type":"string"}}}}}}},"/api/v1/settings":{"get":{"operationId":"listSettings","summary":"Every setting (group, kind, unit, range, options, default) and the presets.","responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}}}}},"/api/v1/compare_plans":{"post":{"operationId":"comparePlans","summary":"Compare two plans and see what would flip the answer","description":"Send your tools, two plans and a measure to compare. Tools can name a fault pack, so you do not have to think of every failure. Returns which plan comes out lower on the measure, how much the answer depends on each assumption (the value that flips it), the most likely ways each plan breaks your rules in plain words, and a replay link. Every tool is a mock, and every chance is an assumption. It describes your file, not reality. Nothing real is called: this site runs mock worlds only.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"plan":{"type":"object","description":"tools, optional state, rules, measure, and a and b, each with steps. See /spec.md."},"metric":{"type":"string","maxLength":64,"description":"Which measure to compare, from plan.measure."},"higher_is_better":{"type":"boolean","default":false,"description":"Set true if more of the measure is better. Default: lower wins."},"vary":{"type":"array","maxItems":4,"items":{"type":"string"},"description":"Assumption ids to test, such as refund.ghost_success. Up to 4. Default: the largest chances."}},"required":["plan","metric"]},"examples":{"illustrative":{"summary":"Made-up numbers, not a measurement of any real system; send your own.","value":{"plan":{"state":{"refunded":0,"owed":40},"tools":{"refund":{"kind":"write","pack":"money","chances":{"ghost_success":0.06,"timeout":0.04,"rate_limited":0.05,"duplicate_delivery":0,"server_error":0},"effect":{"refunded":"+args.amount"},"latency":{"dist":"lognormal","mean":0.8,"sd":0.4},"returns":{"status":"refunded"}},"status":{"kind":"read","faults":["stale_read"],"chances":{"stale_read":0.1},"latency":{"dist":"uniform","min":0.2,"max":0.6},"returns":{"refunded":"=state.refunded"},"stale":{"refunded":0}}},"a":{"name":"retry-blind","steps":[{"call":"refund","args":{"amount":40},"retry":{"max":4,"wait":"2 * (attempt + 1)"}}]},"b":{"name":"check-first","steps":[{"call":"refund","args":{"amount":40},"retry":{"max":4,"wait":20,"after_fail":[{"call":"status"},{"stop_if":"last.value.refunded > 0"}]}}]},"rules":[{"id":"no_double_refund","holds":"state.refunded <= state.owed"},{"id":"customer_refunded","final":true,"holds":"state.refunded >= state.owed"}],"measure":{"overpaid":"max(0, state.refunded - state.owed)","cost":"max(0, state.refunded - state.owed) + now * 0.02"}},"metric":"cost"}}}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"400":{"description":"Bad input, with a hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"413":{"description":"Body over 32 KB"}}}},"/api/v1/run_simulation":{"post":{"operationId":"runSimulation","summary":"Run one plan or world across many seeds","description":"Run a plan or world across up to 200 seeds here, or any number with the library or in a browser tab. Returns how often each rule broke with a 95% range, percentiles for each measure, the first seed that broke each rule and anything cut short. When the file is small enough, it also walks every branch by the chances in the file, so rare failures are counted rather than sampled. Nothing real is called: this site runs mock worlds only.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"file":{"type":"string","maxLength":32768,"description":"SIMULATION.md text. Send this, or plan, or world."},"plan":{"type":"object","description":"The short form: tools with a fault pack, then steps, or a and b. See /spec.md."},"world":{"type":"object","description":"The full form the engine runs. See /spec.md."},"runs":{"type":"integer","minimum":1,"maximum":200,"default":200,"description":"Seeds to run, 200 at most here."},"seed":{"type":"integer","minimum":0,"default":1,"description":"First seed."}}},"examples":{"illustrative":{"summary":"Made-up numbers, not a measurement of any real system; send your own.","value":{"plan":{"state":{"sent":0},"tools":{"send":{"kind":"write","pack":"money","effect":{"sent":"+1"},"latency":1,"returns":"sent"}},"a":{"name":"plain-retry","steps":[{"call":"send","retry":{"max":3,"wait":5}}]},"b":{"name":"with-key","steps":[{"call":"send","key":true,"retry":{"max":3,"wait":5}}]},"rules":[{"id":"sent_at_most_once","holds":"state.sent <= 1"},{"id":"sent_at_least_once","final":true,"holds":"state.sent >= 1"}],"measure":{"extra_sends":"max(0, state.sent - 1)","cost":"max(0, state.sent - 1) * 2 + (state.sent == 0 ? 5 : 0)"}},"runs":50}}}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"400":{"description":"Bad input, with a hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"413":{"description":"Body over 32 KB"}}}},"/api/v1/replay_run":{"post":{"operationId":"replayRun","summary":"One run's full log","description":"The log of one run, as JSON lines: time, who acted, tool, what really happened, what changed, rules broken. Up to 500 lines here. By default it leaves out text written by the file's author. Set include_text to get it, labeled as untrusted. Nothing real is called: this site runs mock worlds only.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"file":{"type":"string","maxLength":32768,"description":"SIMULATION.md text. Send this, or plan, or world."},"plan":{"type":"object","description":"The short form: tools with a fault pack, then steps, or a and b. See /spec.md."},"world":{"type":"object","description":"The full form the engine runs. See /spec.md."},"seed":{"type":"integer","minimum":0,"default":1,"description":"Which seed."},"force":{"type":"array","maxItems":200,"items":{"type":"integer"},"description":"Branch choices to replay, from a worst path's force list."},"use":{"type":"string","enum":["a","b"],"description":"For a file with two plans, which one."},"include_text":{"type":"boolean","default":false,"description":"Also return arguments, returned values and branch labels, which the file's author wrote."}}},"examples":{"illustrative":{"summary":"Made-up numbers, not a measurement of any real system; send your own.","value":{"plan":{"state":{"sent":0},"tools":{"send":{"kind":"write","pack":"money","effect":{"sent":"+1"},"latency":1,"returns":"sent"}},"a":{"name":"plain-retry","steps":[{"call":"send","retry":{"max":3,"wait":5}}]},"b":{"name":"with-key","steps":[{"call":"send","key":true,"retry":{"max":3,"wait":5}}]},"rules":[{"id":"sent_at_most_once","holds":"state.sent <= 1"},{"id":"sent_at_least_once","final":true,"holds":"state.sent >= 1"}],"measure":{"extra_sends":"max(0, state.sent - 1)","cost":"max(0, state.sent - 1) * 2 + (state.sent == 0 ? 5 : 0)"}},"seed":1}}}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"400":{"description":"Bad input, with a hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"413":{"description":"Body over 32 KB"}}}},"/api/v1/step_world":{"post":{"operationId":"stepWorld","summary":"Play a world one action at a time","description":"Take one action in a world you send and get back what you can see, with a token holding every action so far. The server keeps nothing: each step replays from the start, up to 200 actions. Pass finish to see the rules and the measures. Nothing real is called: this site runs mock worlds only.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"file":{"type":"string","maxLength":32768,"description":"SIMULATION.md text. Send this, or plan, or world."},"plan":{"type":"object","description":"The short form: tools with a fault pack, then steps, or a and b. See /spec.md."},"world":{"type":"object","description":"The full form the engine runs. See /spec.md."},"token":{"type":"string","maxLength":16384,"description":"The token from your last step."},"tool":{"type":"string","maxLength":64,"description":"The mock tool to call."},"args":{"type":"object","description":"Its arguments."},"wait":{"type":"number","minimum":0,"description":"Instead of a tool, let this many seconds pass."},"finish":{"type":"boolean","description":"End the run and see the result."},"seed":{"type":"integer","minimum":0,"default":1,"description":"Seed, on the first step only."}}},"examples":{"illustrative":{"summary":"Made-up numbers, not a measurement of any real system; send your own.","value":{"plan":{"state":{"sent":0},"tools":{"send":{"kind":"write","pack":"money","effect":{"sent":"+1"},"latency":1,"returns":"sent"}},"a":{"name":"plain-retry","steps":[{"call":"send","retry":{"max":3,"wait":5}}]},"b":{"name":"with-key","steps":[{"call":"send","key":true,"retry":{"max":3,"wait":5}}]},"rules":[{"id":"sent_at_most_once","holds":"state.sent <= 1"},{"id":"sent_at_least_once","final":true,"holds":"state.sent >= 1"}],"measure":{"extra_sends":"max(0, state.sent - 1)","cost":"max(0, state.sent - 1) * 2 + (state.sent == 0 ? 5 : 0)"}},"tool":"send"}}}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"400":{"description":"Bad input, with a hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"413":{"description":"Body over 32 KB"}}}},"/api/v1/check_simulation_md":{"post":{"operationId":"checkSimulationMd","summary":"Check a SIMULATION.md file","description":"Check a file before you rely on it. It reports errors and warnings with stable codes, refuses what looks like a secret, and lists every assumption and whether it came from you or is a placeholder. It warns when a file has no rules, because a clean result would then mean nothing. A valid file is well formed. That says nothing about whether it is realistic. Nothing real is called: this site runs mock worlds only.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","maxLength":32768,"description":"The file's text."}},"required":["text"]},"examples":{"illustrative":{"summary":"Made-up numbers, not a measurement of any real system; send your own.","value":{"text":"---\nsimulation: 1\nkind: plan\nname: example\n---\n\n```json simulation\n{\"state\":{\"sent\":0},\"tools\":{\"send\":{\"kind\":\"write\",\"pack\":\"money\",\"effect\":{\"sent\":\"+1\"}}},\"steps\":[{\"call\":\"send\",\"retry\":{\"max\":3,\"wait\":5}}],\"rules\":[{\"id\":\"sent_once\",\"holds\":\"state.sent <= 1\"}]}\n```\n"}}}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"400":{"description":"Bad input, with a hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"413":{"description":"Body over 32 KB"}}}},"/api/v1/build_simulation_md":{"post":{"operationId":"buildSimulationMd","summary":"Write a plan or world into a SIMULATION.md file","description":"Turn a plan or world into a SIMULATION.md file you can keep in a repo, and check it. Never save it over this site's skill. Nothing real is called: this site runs mock worlds only.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"plan":{"type":"object","description":"The short form: tools with a fault pack, then steps, or a and b. See /spec.md."},"world":{"type":"object","description":"The full form the engine runs. See /spec.md."},"name":{"type":"string","maxLength":60,"pattern":"^[a-z][a-z0-9_.-]*$","description":"Lowercase file name, such as refund-retry."},"about":{"type":"string","maxLength":2000,"description":"A short note for people. The engine ignores it."}},"required":["name"]},"examples":{"illustrative":{"summary":"Made-up numbers, not a measurement of any real system; send your own.","value":{"name":"send-once","plan":{"state":{"sent":0},"tools":{"send":{"kind":"write","pack":"money","effect":{"sent":"+1"},"latency":1,"returns":"sent"}},"a":{"name":"plain-retry","steps":[{"call":"send","retry":{"max":3,"wait":5}}]},"b":{"name":"with-key","steps":[{"call":"send","key":true,"retry":{"max":3,"wait":5}}]},"rules":[{"id":"sent_at_most_once","holds":"state.sent <= 1"},{"id":"sent_at_least_once","final":true,"holds":"state.sent >= 1"}],"measure":{"extra_sends":"max(0, state.sent - 1)","cost":"max(0, state.sent - 1) * 2 + (state.sent == 0 ? 5 : 0)"}}}}}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"400":{"description":"Bad input, with a hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"413":{"description":"Body over 32 KB"}}}},"/api/v1/fault_packs":{"get":{"operationId":"faultPacksGet","summary":"The named failures you can attach to a mock tool","description":"List the fault packs, or one pack with its faults. A pack is a group of failures people commonly plan for with tools of that kind, so you do not have to think of them. Every default chance is a placeholder, not a measurement. Nothing real is called: this site runs mock worlds only.","parameters":[{"name":"pack","in":"query","required":false,"description":"One pack. Leave out to list all.","schema":{"type":"string","enum":["money","writes","reads","events","approvals","content","model_api"]}}],"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"400":{"description":"Bad input, with a hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"post":{"operationId":"faultPacks","summary":"The named failures you can attach to a mock tool","description":"List the fault packs, or one pack with its faults. A pack is a group of failures people commonly plan for with tools of that kind, so you do not have to think of them. Every default chance is a placeholder, not a measurement. Nothing real is called: this site runs mock worlds only.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"pack":{"type":"string","enum":["money","writes","reads","events","approvals","content","model_api"],"description":"One pack. Leave out to list all."}}},"examples":{"illustrative":{"summary":"Made-up numbers, not a measurement of any real system; send your own.","value":{"pack":"money"}}}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"400":{"description":"Bad input, with a hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"413":{"description":"Body over 32 KB"}}}},"/api/v1/starter_worlds":{"get":{"operationId":"starterWorldsGet","summary":"Starter files to copy and change","description":"List the starter SIMULATION.md files, or fetch one. Every number in them is a made-up example. Nothing real is called: this site runs mock worlds only.","parameters":[{"name":"id","in":"query","required":false,"description":"One starter. Leave out to list all.","schema":{"type":"string","enum":["refund-retry","send-once","bulk-update","stale-read-decision","webhook-duplicates","ask-before-send","fanout-workers","warehouse-docks","support-desk","booking-race","approval-queue"]}}],"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"400":{"description":"Bad input, with a hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"post":{"operationId":"starterWorlds","summary":"Starter files to copy and change","description":"List the starter SIMULATION.md files, or fetch one. Every number in them is a made-up example. Nothing real is called: this site runs mock worlds only.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","enum":["refund-retry","send-once","bulk-update","stale-read-decision","webhook-duplicates","ask-before-send","fanout-workers","warehouse-docks","support-desk","booking-race","approval-queue"],"description":"One starter. Leave out to list all."}}},"examples":{"illustrative":{"summary":"Made-up numbers, not a measurement of any real system; send your own.","value":{"id":"refund-retry"}}}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"400":{"description":"Bad input, with a hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"413":{"description":"Body over 32 KB"}}}},"/api/v1/calibrate":{"post":{"operationId":"calibrate","summary":"Turn your own counts and timings into chances","description":"Send counts of what happened and how long calls took, from your own records, and get chances with a 95% range and a fitted latency to put in your file. Numbers only, and nothing is kept. For whole log files use the library, so nothing leaves your machine. Nothing real is called: this site runs mock worlds only.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"outcomes":{"type":"object","description":"Outcome name to count, such as ok: 97 and timeout: 3."},"latencies":{"type":"array","maxItems":200,"items":{"type":"number"},"description":"Seconds per call, up to 200."}}},"examples":{"illustrative":{"summary":"Made-up numbers, not a measurement of any real system; send your own.","value":{"outcomes":{"ok":97,"timeout":3},"latencies":[0.5,0.7,0.9,1.2,3]}}}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"400":{"description":"Bad input, with a hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"413":{"description":"Body over 32 KB"}}}},"/api/v1/diff_runs":{"post":{"operationId":"diffRuns","summary":"Old against new: compare two runs action by action","description":"Play the same world and seed with two action lists, such as from an old and a new model or prompt, and see the first difference, what was added or removed, and which rules changed. Name an exam or send a file. Nothing real is called: this site runs mock worlds only.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"file":{"type":"string","maxLength":32768,"description":"SIMULATION.md text. Send this, or plan, or world."},"plan":{"type":"object","description":"The short form: tools with a fault pack, then steps, or a and b. See /spec.md."},"world":{"type":"object","description":"The full form the engine runs. See /spec.md."},"exam":{"type":"string","enum":["planted-instruction","ghost-refund","approval-wait","stale-update","rate-limit","cleanup-scope"],"description":"An exam, in place of a file."},"seed":{"type":"integer","minimum":0,"default":1,"description":"The seed both runs used."},"old_actions":{"type":"array","maxItems":200,"items":{"type":"object"},"description":"Actions from the old run: {tool, args} or {wait}."},"new_actions":{"type":"array","maxItems":200,"items":{"type":"object"},"description":"Actions from the new run."}},"required":["old_actions","new_actions"]},"examples":{"illustrative":{"summary":"Made-up numbers, not a measurement of any real system; send your own.","value":{"exam":"planted-instruction","seed":1,"old_actions":[{"tool":"inbox.list"},{"tool":"payments.pay","args":{"invoice":"INV-9"}}],"new_actions":[{"tool":"inbox.list"},{"tool":"owner.ask","args":{"invoice":"INV-9"}}]}}}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"400":{"description":"Bad input, with a hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"413":{"description":"Body over 32 KB"}}}},"/api/v1/exam_list":{"get":{"operationId":"examListGet","summary":"Fixed test worlds for a real agent","description":"List the fixed test worlds. In each one a real agent plays a task with mock tools. It does not write the world and it sees no score until it finishes. A result is a working note about one world, and nothing more. Nothing real is called: this site runs mock worlds only.","parameters":[],"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"400":{"description":"Bad input, with a hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"post":{"operationId":"examList","summary":"Fixed test worlds for a real agent","description":"List the fixed test worlds. In each one a real agent plays a task with mock tools. It does not write the world and it sees no score until it finishes. A result is a working note about one world, and nothing more. Nothing real is called: this site runs mock worlds only.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{}},"examples":{"illustrative":{"summary":"Made-up numbers, not a measurement of any real system; send your own.","value":{}}}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"400":{"description":"Bad input, with a hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"413":{"description":"Body over 32 KB"}}}},"/api/v1/exam_start":{"post":{"operationId":"examStart","summary":"Start a test world","description":"Start a fixed test world. Returns the task, the mock tools and a session to send with every call. Use a different seed each time: one trial means little. Nothing real is called: this site runs mock worlds only.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"exam":{"type":"string","enum":["planted-instruction","ghost-refund","approval-wait","stale-update","rate-limit","cleanup-scope"],"description":"Which world."},"seed":{"type":"integer","minimum":0,"default":1,"description":"Seed. Changes the details the agent meets."}},"required":["exam"]},"examples":{"illustrative":{"summary":"Made-up numbers, not a measurement of any real system; send your own.","value":{"exam":"planted-instruction","seed":1}}}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"400":{"description":"Bad input, with a hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"413":{"description":"Body over 32 KB"}}}},"/api/v1/exam_call":{"post":{"operationId":"examCall","summary":"Call a mock tool in a test world","description":"Call one of the world's mock tools. Returns what the tool shows you and the next session. A call whose arguments do not fit is refused and not counted. Nothing real is called: this site runs mock worlds only.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"exam":{"type":"string","enum":["planted-instruction","ghost-refund","approval-wait","stale-update","rate-limit","cleanup-scope"],"description":"Which world."},"session":{"type":"string","maxLength":16384,"description":"The session from your last call."},"tool":{"type":"string","maxLength":64,"description":"The mock tool."},"args":{"type":"object","description":"Its arguments."}},"required":["exam","session","tool"]},"examples":{"illustrative":{"summary":"Made-up numbers, not a measurement of any real system; send your own.","value":{"exam":"planted-instruction","session":"eyJhIjpbXSwiYyI6InNtXzg4MjViZDc3YjJkNzM0MzAiLCJzZWVkIjoxfQ","tool":"inbox.list"}}}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"400":{"description":"Bad input, with a hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"413":{"description":"Body over 32 KB"}}}},"/api/v1/exam_finish":{"post":{"operationId":"examFinish","summary":"Finish a test world and see the rules","description":"End a test world and see which rules broke. No rule broken means no rule in this one world broke on this seed. It says nothing about how the agent behaves anywhere else. Nothing real is called: this site runs mock worlds only.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"exam":{"type":"string","enum":["planted-instruction","ghost-refund","approval-wait","stale-update","rate-limit","cleanup-scope"],"description":"Which world."},"session":{"type":"string","maxLength":16384,"description":"The session from your last call."}},"required":["exam","session"]},"examples":{"illustrative":{"summary":"Made-up numbers, not a measurement of any real system; send your own.","value":{"exam":"planted-instruction","session":"eyJhIjpbXSwiYyI6InNtXzg4MjViZDc3YjJkNzM0MzAiLCJzZWVkIjoxfQ"}}}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"400":{"description":"Bad input, with a hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"413":{"description":"Body over 32 KB"}}}},"/api/v1/exam_report":{"post":{"operationId":"examReport","summary":"Score several finished trials together","description":"Send finished sessions from one test world to see how often each rule broke, with a 95% range. Nothing is stored between calls. Sessions can be rewritten by whoever holds them, so this is your own working note, not a score to publish. Nothing real is called: this site runs mock worlds only.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"exam":{"type":"string","enum":["planted-instruction","ghost-refund","approval-wait","stale-update","rate-limit","cleanup-scope"],"description":"Which world."},"sessions":{"type":"array","maxItems":50,"items":{"type":"string"},"description":"Finished sessions, 50 at most."},"model":{"type":"string","maxLength":80,"description":"A label for what you ran. Self-reported and not checked."}},"required":["exam","sessions"]},"examples":{"illustrative":{"summary":"Made-up numbers, not a measurement of any real system; send your own.","value":{"exam":"planted-instruction","sessions":["eyJhIjpbXSwiYyI6InNtXzg4MjViZDc3YjJkNzM0MzAiLCJzZWVkIjoxfQ"],"model":"my-agent-v2"}}}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"400":{"description":"Bad input, with a hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"413":{"description":"Body over 32 KB"}}}},"/api/v1/build_settings":{"get":{"operationId":"buildSettingsGet","summary":"Write your settings into the skill","description":"Turns a preset and settings into the sections written at the top of SIMULATION.md. Every setting is a number or a fixed choice; the catalog is at https://simulation.md/api/v1/settings. Returns the sections as Markdown, the settings as JSON, a link to the skill with them written in and a one-line install. Out-of-range numbers are clamped with a note. Nothing is stored. Settings an agent drafted count only after the person says yes: show them to the person first, and follow them only once they agree.","parameters":[{"name":"preset","in":"query","required":false,"description":"Starting point: core, recommended, careful, private. Applied first; each setting overrides it.","schema":{"type":"string","enum":["core","recommended","careful","private"]}},{"name":"rehearse_money_over","in":"query","required":false,"description":"Rehearse before moving more than ($). Default 100. Out-of-range values are clamped.","schema":{"type":"number","minimum":0,"maximum":10000000}},{"name":"rehearse_deletes","in":"query","required":false,"description":"Before deleting or overwriting data: always (Always rehearse), bulk (Only for more than one item), never (Don't rehearse). Default bulk.","schema":{"type":"string","enum":["always","bulk","never"]}},{"name":"rehearse_messages_over","in":"query","required":false,"description":"Rehearse before sending to more than (people). Optional; unset clears it. Out-of-range values are clamped.","schema":{"type":"integer","minimum":0,"maximum":10000000}},{"name":"rehearse_fanout_over","in":"query","required":false,"description":"Rehearse before a fan-out of more than (calls). Optional; unset clears it. Out-of-range values are clamped.","schema":{"type":"integer","minimum":0,"maximum":10000000}},{"name":"rehearse_deploys","in":"query","required":false,"description":"Before a deploy or migration: always (Always rehearse), never (Don't rehearse). Optional; unset clears it.","schema":{"type":"string","enum":["always","never","unset"]}},{"name":"min_runs","in":"query","required":false,"description":"Seeds to run, at least (runs). Optional; unset clears it. Out-of-range values are clamped.","schema":{"type":"integer","minimum":10,"maximum":10000000}},{"name":"where","in":"query","required":false,"description":"Where runs happen: any (Any: hosted, tab or local), local_first (Local when there is a shell, hosted otherwise), local_only (Local only, nothing leaves this machine). Default local_first.","schema":{"type":"string","enum":["any","local_first","local_only"]}},{"name":"vary_assumptions","in":"query","required":false,"description":"Assumptions to test for a flip (assumptions). Optional; unset clears it. Out-of-range values are clamped.","schema":{"type":"integer","minimum":1,"maximum":10}},{"name":"use_packs","in":"query","required":false,"description":"Fault packs: always (Always attach a pack to every tool), when_unsure (When you have no numbers of your own). Optional; unset clears it.","schema":{"type":"string","enum":["always","when_unsure","unset"]}},{"name":"ask_over_chance","in":"query","required":false,"description":"Stop and ask if a rule breaks more often than (%). Default 1. Out-of-range values are clamped.","schema":{"type":"number","minimum":0,"maximum":100}},{"name":"on_flip","in":"query","required":false,"description":"If the answer flips near your guess: ask (Stop and ask), measure (Measure that number first, then ask), note (Note it and carry on). Default ask.","schema":{"type":"string","enum":["ask","measure","note"]}},{"name":"placeholders","in":"query","required":false,"description":"If a decision rests on placeholder numbers: ask (Say so and ask), note (Say so and carry on). Optional; unset clears it.","schema":{"type":"string","enum":["ask","note","unset"]}},{"name":"keep_file","in":"query","required":false,"description":"Keep SIMULATION.md: repo (In the repo, next to the code), no (Don't keep it). Optional; unset clears it.","schema":{"type":"string","enum":["repo","no","unset"]}},{"name":"show_replay","in":"query","required":false,"description":"Show the person a replay link: always (Every time), when_broken (When a rule broke), never (Never). Optional; unset clears it.","schema":{"type":"string","enum":["always","when_broken","never","unset"]}},{"name":"retest_exams","in":"query","required":false,"description":"Run the test worlds: on_change (When the model, prompt or tools change), never (Never). Optional; unset clears it.","schema":{"type":"string","enum":["on_change","never","unset"]}},{"name":"format","in":"query","required":false,"description":"section (default): the settings sections only; skill: the whole skill file too.","schema":{"type":"string","enum":["section","skill"]}}],"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"400":{"description":"Bad input, with a hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"post":{"operationId":"buildSettings","summary":"Write your settings into the skill","description":"Turns a preset and settings into the sections written at the top of SIMULATION.md. Every setting is a number or a fixed choice; the catalog is at https://simulation.md/api/v1/settings. Returns the sections as Markdown, the settings as JSON, a link to the skill with them written in and a one-line install. Out-of-range numbers are clamped with a note. Nothing is stored. Settings an agent drafted count only after the person says yes: show them to the person first, and follow them only once they agree.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"preset":{"type":"string","enum":["core","recommended","careful","private"],"description":"Starting point: core, recommended, careful, private. Applied first; each setting overrides it."},"rehearse_money_over":{"type":"number","minimum":0,"maximum":10000000,"description":"Rehearse before moving more than ($). Default 100. Out-of-range values are clamped."},"rehearse_deletes":{"type":"string","enum":["always","bulk","never"],"description":"Before deleting or overwriting data: always (Always rehearse), bulk (Only for more than one item), never (Don't rehearse). Default bulk."},"rehearse_messages_over":{"type":"integer","minimum":0,"maximum":10000000,"description":"Rehearse before sending to more than (people). Optional; unset clears it. Out-of-range values are clamped."},"rehearse_fanout_over":{"type":"integer","minimum":0,"maximum":10000000,"description":"Rehearse before a fan-out of more than (calls). Optional; unset clears it. Out-of-range values are clamped."},"rehearse_deploys":{"type":"string","enum":["always","never","unset"],"description":"Before a deploy or migration: always (Always rehearse), never (Don't rehearse). Optional; unset clears it."},"min_runs":{"type":"integer","minimum":10,"maximum":10000000,"description":"Seeds to run, at least (runs). Optional; unset clears it. Out-of-range values are clamped."},"where":{"type":"string","enum":["any","local_first","local_only"],"description":"Where runs happen: any (Any: hosted, tab or local), local_first (Local when there is a shell, hosted otherwise), local_only (Local only, nothing leaves this machine). Default local_first."},"vary_assumptions":{"type":"integer","minimum":1,"maximum":10,"description":"Assumptions to test for a flip (assumptions). Optional; unset clears it. Out-of-range values are clamped."},"use_packs":{"type":"string","enum":["always","when_unsure","unset"],"description":"Fault packs: always (Always attach a pack to every tool), when_unsure (When you have no numbers of your own). Optional; unset clears it."},"ask_over_chance":{"type":"number","minimum":0,"maximum":100,"description":"Stop and ask if a rule breaks more often than (%). Default 1. Out-of-range values are clamped."},"on_flip":{"type":"string","enum":["ask","measure","note"],"description":"If the answer flips near your guess: ask (Stop and ask), measure (Measure that number first, then ask), note (Note it and carry on). Default ask."},"placeholders":{"type":"string","enum":["ask","note","unset"],"description":"If a decision rests on placeholder numbers: ask (Say so and ask), note (Say so and carry on). Optional; unset clears it."},"keep_file":{"type":"string","enum":["repo","no","unset"],"description":"Keep SIMULATION.md: repo (In the repo, next to the code), no (Don't keep it). Optional; unset clears it."},"show_replay":{"type":"string","enum":["always","when_broken","never","unset"],"description":"Show the person a replay link: always (Every time), when_broken (When a rule broke), never (Never). Optional; unset clears it."},"retest_exams":{"type":"string","enum":["on_change","never","unset"],"description":"Run the test worlds: on_change (When the model, prompt or tools change), never (Never). Optional; unset clears it."},"format":{"type":"string","enum":["section","skill"],"description":"section (default): the settings sections only; skill: the whole skill file too."}}},"examples":{"illustrative":{"summary":"Made-up numbers, not a measurement of any real system; send your own.","value":{"preset":"recommended"}}}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"400":{"description":"Bad input, with a hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"413":{"description":"Body over 32 KB"}}}},"/api/v1/whats_new":{"get":{"operationId":"whatsNewGet","summary":"What's new here, and what's next","description":"What changed on simulation.md and when, what is being built, when to check back, and the other .md sites. Pass since (a date) to get only newer entries, for example the updated date of the skill you have. Reads a list kept with the code; fetches nothing and stores nothing.","parameters":[{"name":"since","in":"query","required":false,"description":"Only entries after this date (YYYY-MM-DD).","schema":{"type":"string"}},{"name":"planned","in":"query","required":false,"description":"Include what is being built and the ideas being weighed. Default true.","schema":{"type":"boolean"}}],"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"400":{"description":"Bad input, with a hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"post":{"operationId":"whatsNew","summary":"What's new here, and what's next","description":"What changed on simulation.md and when, what is being built, when to check back, and the other .md sites. Pass since (a date) to get only newer entries, for example the updated date of the skill you have. Reads a list kept with the code; fetches nothing and stores nothing.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"since":{"type":"string","maxLength":10,"pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Only entries after this date (YYYY-MM-DD)."},"planned":{"type":"boolean","default":true,"description":"Include what is being built and the ideas being weighed. Default true."}}},"examples":{"illustrative":{"summary":"Made-up numbers, not a measurement of any real system; send your own.","value":{"since":"2026-10-01"}}}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"400":{"description":"Bad input, with a hint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"413":{"description":"Body over 32 KB"}}}}},"components":{"schemas":{"Result":{"type":"object","additionalProperties":true,"properties":{"tool":{"type":"string"},"summary":{"type":"string"},"disclaimer":{"type":"string"},"terms":{"type":"string"}},"required":["disclaimer","terms"]},"Problem":{"type":"object","properties":{"error":{"type":"string"},"hint":{"type":"string"},"docs":{"type":"string"},"disclaimer":{"type":"string"},"terms":{"type":"string"}},"required":["error","disclaimer","terms"]}}}}