@postman/postman-plugin 0.5.0 → 0.6.0-rc.0

package/README.md

@@ -235,8 +235,8 @@ exercise failure paths.
 `postman init` is idempotent and safe to run in any project. Run it before API
 engineering work to create the relevant local directories and make Postman
 skills available to guide the task, even if the project is already initialized.
-See [bootstrap](https://github.com/postmanlabs/postman-plugin/blob/main/skills/bootstrap/SKILL.md#start-with-postman-init) for setup
-options and workspace binding.
+See [workspaces](https://github.com/postmanlabs/postman-plugin/blob/main/skills/workspaces/SKILL.md) for init's
+workspace options and binding.
 
 Work done in a Postman folder produces artifacts: collection runs, lint
 results, request history, mock deployments. When that folder is connected to a

package/dist/hosts/factory.js

@@ -2,17 +2,43 @@ import { GIT_URL, REPO, isSameRepo, redact } from '../source.js';
 import { blocked, guard, mustProbeText, mustRun } from './shared.js';
 import { result } from './types.js';
 const MARKETPLACE = 'postman-plugin', PLUGIN_ID = `postman@${MARKETPLACE}`, SCOPE = 'user', NEXT = 'Restart Droid for the change to take effect.';
+function rowsOfWrappedTable(text) {
+    const lines = text.split(/\r?\n/), headerAt = lines.findIndex((line) => /^[A-Z]+(?: [A-Z]+)*(?: {2,}[A-Z]+(?: [A-Z]+)*)+\s*$/.test(line));
+    if (headerAt === -1) {
+        return [];
+    }
+    const columns = [...lines[headerAt].matchAll(/[A-Z]+(?: [A-Z]+)*/g)].map((match) => ({ name: match[0], start: match.index })), rows = [];
+    for (const line of lines.slice(headerAt + 1)) {
+        const cells = columns.map(({ start }, i) => line.slice(start, columns[i + 1]?.start).trim()), previous = rows.at(-1), continuesPrevious = !cells[0];
+        if (!continuesPrevious) {
+            rows.push(Object.fromEntries(columns.map(({ name }, i) => [name, cells[i]])));
+        }
+        else if (previous) {
+            columns.forEach(({ name }, i) => { previous[name] += cells[i]; });
+        }
+    }
+    return rows;
+}
+export function installedPlugins(droidPluginList) {
+    const bracketedScopes = droidPluginList.split(/\r?\n/)
+        .map((line) => /^\s*(\S+@\S+)\s+\[(\w+)\]/.exec(line))
+        .filter((match) => match !== null)
+        .map(([, plugin, scope]) => `${plugin} [${scope}]`);
+    return bracketedScopes.length ?
+        bracketedScopes :
+        rowsOfWrappedTable(droidPluginList).map((row) => `${row.PLUGIN} [${row.SOURCE}]`);
+}
 function hasInstalledPlugin(text) {
-    return text.split('\n').some((line) => new RegExp(`^${PLUGIN_ID}\\s+\\[${SCOPE}\\]`).test(line.trimStart()));
+    return installedPlugins(text).includes(`${PLUGIN_ID} [${SCOPE}]`);
 }
 function marketplaceSource(text) {
-    for (const line of text.split('\n')) {
+    for (const line of text.split(/\r?\n/)) {
         const match = /^\s*(\S+)\s+\(\d+ plugins?\)\s+(.+?)(?:\s+"[^"]*")?\s*$/.exec(line);
         if (match && match[1] === MARKETPLACE) {
             return match[2];
         }
     }
-    return null;
+    return rowsOfWrappedTable(text).find((row) => row.MARKETPLACE === MARKETPLACE)?.SOURCE ?? null;
 }
 function sourceWithoutFactoryPrefix(source) {
     return source.replace(/^(?:github|url):/, '');

package/hooks/session-start-context.md

@@ -3,7 +3,7 @@ You have the Postman plugin.
 
 Before responding to any non-trivial API engineering task — designing, implementing, mocking, testing, monitoring, documenting, or deploying an API or Postman Flow — load the `postman:api-engineer` skill and follow it. It is the default entry point and routes to the specific postman skills from there. Pure questions and trivial one-line edits don't need it.
 
-When the intent is already specific, you may enter directly into the relevant skill instead: `postman:bootstrap` (link this repo to a Postman workspace), `postman:api-mocking`, `postman:api-testing`, `postman:api-monitoring`, `postman:flows`, `postman:ci-integration`, `postman:api-discovery`, `postman:ai-readiness`, `postman:performance-testing`, `postman:api-documentation`, `postman:variables` (where a value or secret belongs and how to reference it).
+When the intent is already specific, you may enter directly into the relevant skill instead: `postman:api-mocking`, `postman:api-testing`, `postman:api-monitoring`, `postman:flows`, `postman:ci-integration`, `postman:api-discovery`, `postman:ai-readiness`, `postman:performance-testing`, `postman:api-documentation`, `postman:variables` (where a value or secret belongs and how to reference it).
 
 If you were dispatched as a subagent to execute a specific task, ignore this block — `postman:api-engineer` governs the orchestrating session, and it already shaped your dispatch.
 

package/mcp.pi.json

@@ -6,8 +6,8 @@
       "description": "Postman workspaces, collections, specs, environments, mocks and monitors",
       "headers": {
         "X-Source": "postman-pi-plugin",
-        "X-Plugin-Version": "0.5.0",
-        "User-Agent": "postman-pi-plugin/0.5.0"
+        "X-Plugin-Version": "0.6.0-rc.0",
+        "User-Agent": "postman-pi-plugin/0.6.0-rc.0"
       }
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@postman/postman-plugin",
-  "version": "0.5.0",
+  "version": "0.6.0-rc.0",
   "description": "Postman's API engineering skills for coding agents: a Pi package, and an npx installer that sets up Claude Code, Codex, Cursor, Kimi Code, Factory Droid, OpenCode and Pi.",
   "type": "module",
   "license": "Apache-2.0",

package/skills/api-discovery/SKILL.md

@@ -10,6 +10,11 @@ must invent. Relationship context broadens investigation beyond the checkout:
 passing this service's own tests does not establish that its consumers can
 still use a changed interface.
 
+Postman search, the Context Graph and dependency downloads work only for a
+signed-in CLI. Check `postman status` before the first of them and sign in if
+it reports signed out. If signing in isn't possible, don't run them; say which
+sources were skipped.
+
 1. Choose the source by the question:
 
    | Need | Use |
@@ -47,8 +52,8 @@ still use a changed interface.
    not be present yet. The query uses the authenticated API key's team, not
    the repository's workspace binding; changing that binding cannot fix a
    query against the wrong organization's context.
-5. Use **bootstrap**'s "Owning workspace versus dependency" distinction
-   before importing. For a dependency, `postman dependency add
+5. Before importing, tell this repository's owning workspace from a
+   dependency. For a dependency, `postman dependency add
    <collection|environment|mock> <name-or-id>` declares and downloads the
    selected resource without rebinding the repository. Prefer the discovered
    ID; `--workspace <id>` disambiguates names. If the graph only identified a

package/skills/api-documentation/SKILL.md

@@ -14,8 +14,7 @@ with changes reviewable alongside code.
    interface for tooling; a Postman collection adds runnable requests,
    examples, and assertions. Maintain both when both uses matter, with an
    explicit direction of generation or synchronization so they do not become
-   competing definitions. Local edits need **bootstrap** only when setup or
-   bindings are unresolved.
+   competing definitions.
 2. When the spec is authoritative, reuse its operations with
    `postman spec generate collection <spec-path-or-id> -n "<collection-name>"`.
    Inspect the generated result before replacing an existing collection:
@@ -34,7 +33,7 @@ with changes reviewable alongside code.
    to keep credentials out of reusable requests and examples.
 5. Choose delivery by audience. Local artifacts support Git review;
    publishing to the bound workspace makes them available to teammates with
-   access (see **bootstrap**). A workspace push does not itself publish a
+   access. A workspace push does not itself publish a
    public docs page or change permissions. For a public documentation link,
    use **postman-mcp-server**'s documentation workflow and the available
    publishing tool; establish the intended audience before public exposure.

package/skills/api-engineer/SKILL.md

@@ -16,10 +16,9 @@ guesswork each time work resumes.
    regression. Reuse the existing contract; update it where behavior changes.
    Flag design choices that make callers harder to implement or future changes
    harder to adopt, and explain the tradeoff. See **api-documentation**.
-2. Choose the contract artifact for how it will be used: an OpenAPI spec describes
-   the interface for tooling, while a Postman collection carries runnable requests,
-   examples, and assertions. Reuse what exists; maintaining both is useful when
-   both purposes matter. See **api-documentation**.
+2. A Postman collection records the contract in a form that runs. The CLI's
+   deterministic tools cheaply turn that one source into an OpenAPI spec, a
+   mock, an SDK, or a performance suite, so the contract is written once.
 3. Match verification to the behavior at risk. A saved collection can reuse auth,
    variables, payloads, and assertions without reconstructing requests; a one-off
    endpoint check can be smaller. Check the changed behavior and relevant existing
@@ -40,10 +39,8 @@ guesswork each time work resumes.
    your API, publish a mock of it in your service's own workspace, where their
    simulations look first; see **api-mocking**.
 6. Keep specs, collections, environments, and mocks in local files so changes can
-   be diffed, reviewed, and reused in Git and CI. Use **bootstrap** when setup or
-   workspace bindings are unresolved: reuse an existing local layout, pull the
-   current service's existing workspace, or initialize a new project when neither
-   exists.
+   be diffed, reviewed, and reused in Git and CI. `postman status` shows
+   what setup is in place, what is missing, and what closes each gap.
 7. `postman init` gives API engineering work a ready state. It scaffolds local structure: `postman/`
    directories for API artifacts. It installs skills in `postman/skills` folder with guidance on  designing, implementing, and validating APIs.
    The command is idempotent and safe to rerun in an initialized project.
@@ -73,16 +70,17 @@ gap, such as an untested behavior or a consumer affected by an interface change.
 Decline unnecessary setup or scope and explain why it would not help the task.
 
 Important: If a CLI command says an operation isn't allowed because credits
-or usage are exhausted, or the current plan does not permit it, follow
-**bootstrap**'s "Subscription or usage limit" section instead of retrying or
-trying to find a workaround.
+or usage are exhausted, or the current plan does not permit it, stop
+retrying and tell the user that signing up or upgrading their plan is what
+lifts it.
 
 ## Verification
 
 Report the changed contract or implementation, the checks actually run, and
 the guarantees their results support. Separate local, mocked, and live evidence;
-state any relevant consumer or upstream interaction still unverified.
+state any relevant consumer or upstream interaction still unverified. Run
+`postman status` last to confirm the setup the work relied on is still in place.
 
-If actual use exposes a CLI gap or misleading skill, see **bootstrap**'s
-"Reporting CLI and skill gaps" section so the defect can be addressed for future
-work.
+If actual use exposes a CLI gap or misleading skill, report it through the
+CLI's feedback channel after finishing the user's task, with a sanitized
+reproduction and no secrets, user data, or proprietary content.

package/skills/api-mocking/SKILL.md

@@ -21,8 +21,10 @@ Several APIs at once, for a service, a frontend or a test suite? Use
 
 When the API belongs to another team, look for their published mock before
 writing one: theirs encodes their contract and their service's state; yours
-encodes a guess. It needs `postman login`; signed out, build one and say the
-owner search was skipped.
+encodes a guess.
+
+Every step below needs a signed-in CLI. Check `postman status` first; signed
+out, skip to building one and say the owner search was skipped.
 
 1. Find the owner's workspace with `postman search workspaces "<service>" -o json`.
    Name the service plainly, as your code does, not by what it returns: a

package/skills/api-monitoring/SKILL.md

@@ -19,43 +19,53 @@ exercise the guarantees users depend on.
    the linked workspace unless one is supplied. Inspect command-specific
    `-h` and available service options for supported schedules and limits.
    Creation starts an immediate run by default; `--no-run-now` avoids that
-   when only scheduling was requested. A schedule expressed in the host's
-   default timezone can fire at the wrong operational time.
+   when only scheduling was requested. Pass `--timezone` with the zone the
+   user means (for example `America/New_York`); without it the schedule uses
+   the zone of the machine running the CLI. Leave the month field as `*`; to
+   limit a schedule to certain months, write them as three-letter names such
+   as `jan`, not numbers.
 3. Choose a Postman region for a reachable public API. Use a self-hosted
    runner when the target is reachable only inside the user's network;
    running one adds infrastructure to maintain. `postman runner regions`
-   provides valid hosted locations and `runner list` provides registered
-   private runner IDs. `monitor create/update --runner` accepts either;
+   provides valid hosted locations and `runner list --json` the full IDs of
+   registered private runners. `monitor create/update --runner` accepts either;
    multiple locations help distinguish API failures from regional reachability.
-4. Preserve monitor identity when updating schedule or run settings.
-   `monitor update` cannot change its collection or environment and does not
-   pause it; use `pause`/`resume` for that. A different collection/environment
-   requires a replacement, so plan the handoff before deleting the old
-   monitor and its continuity. Permanent deletion needs explicit intent.
+4. Update a monitor in place to keep its run history.
+   `monitor update` cannot change the collection, and cannot pause or resume
+   the monitor: use `monitor pause`/`monitor resume` for that. `update -e`
+   swaps the environment and `--clear-environment` removes it. A different
+   collection requires a replacement, so plan the handoff before deleting the
+   old monitor and its continuity. Permanent deletion needs explicit intent.
 5. Use `postman monitor run <id>` for an immediate verdict, such as after a
    deploy. `--async` returns a job handle when the caller need not wait.
-   The CLI timeout caps waiting, not execution; after a timeout, inspect
-   the submitted job instead of sending duplicate traffic or reporting failure.
-6. Diagnose at the level of the evidence. `monitor jobs list <monitor-id>`
-   finds jobs, `monitor jobs get <job-id>` shows terminal state and regional
-   outcomes, and `monitor runs get <run-id>` shows assertions within an
-   attempt. A failing region, a connection error, and a failed assertion
-   imply different fixes. Preserve normal exit-code failures for CI gates.
+   The CLI timeout caps waiting, not execution: after a timeout, read the job
+   with `monitor jobs get <job-id>`; its state is the verdict.
+6. Answer each failure question at its level. `monitor jobs list
+   <monitor-id>` finds jobs, `monitor jobs get <job-id>` shows terminal state
+   and regional outcomes, and `monitor runs get <run-id>` shows assertions
+   within an attempt. A failing region, a connection error, and a failed
+   assertion imply different fixes. For a trend across runs, such as which
+   request got slow, use `monitor metrics <monitor-id>`. In a CI gate, run
+   `monitor run` without `-x`, so a failed run fails the build.
 
-For discovery, `monitor list` supports workspace and collection filters;
-use its returned cursor for pagination rather than offset. Its runner filter
+For discovery, `monitor list` supports workspace and collection filters; to
+page it, pass `--cursor` with the value from the previous page. Its runner filter
 is for a self-hosted ID and cannot be combined with other filters; a page-local
 name filter does not establish absence across all pages.
 
-For a private runner, use `runner start` with the registered ID and key and
-verify that it connects before assigning runs. Inspect its help for proxy,
-private CA, residency, and health-metric options only when the network requires
-them. Runner activity is reported by default; `--no-report-events` disables
-that reporting when the task requires it. Use **bootstrap** for unresolved
-authentication rather than placing runner keys in repository files.
+For a private runner, use `runner start` with the ID and key from the runner
+created in Postman, and verify it is reporting in before assigning runs: a
+recent `Last ping` in `runner list` (`lastPingAt` under `--json`; `never`
+means it has not connected). Inspect its help for proxy, private CA,
+residency, and health-metric options only when the network requires them.
+Runner activity is reported by default; `--no-report-events` disables that
+reporting when the task requires it. Pass the runner key at runtime, from the
+user or a secret store (for example `--key "$RUNNER_KEY"`), and keep it out of
+files in the repository. If a `monitor` or `runner list` command fails on
+authentication, sign in.
 
 ## Verification
 
 Report the actual monitor configuration or terminal job/run outcome, including
 where it executed and which checks failed. A created monitor, accepted job,
-or connected runner alone does not prove the API passed its health checks.
+or a runner reporting in alone does not prove the API passed its health checks.

package/skills/api-simulation/SKILL.md

@@ -1,27 +1,50 @@
 ---
 name: api-simulation
-description: Runs your code for real against stand-ins for the HTTP services it calls, served together as one environment on one local port or one deployed URL, whether that code is a service you're changing, a frontend, a test suite or a demo. Use when you add or change code that calls other services and need to run it, test it, prove a fix or reproduce an upstream failure (timeouts, 5xx, 409, 429) end to end, locally or in CI, without the real services because they're unreachable, need credentials, cost money, have side effects or don't exist yet. Also answers what happens to a request, or to the data it writes, when a service it calls goes down, is slow or returns errors ("what happens to a booking if the email service is down?"), by running each failure instead of reading the code. Applies even when nobody says mock or simulation. To give a frontend or another team a stand-in for an API, use api-mocking. Covers `postman simulation`.
+description: Runs services, frontends, tests or demos against stand-ins for their HTTP dependencies, served as one environment locally or at a deployed URL. Use when you add or change code that calls other services and need to run it, test it, prove a fix or reproduce an upstream failure (timeouts, 5xx, 409, 429) end to end, locally or in CI, without the real services because they're unreachable, need credentials, cost money, have side effects or don't exist yet. Also answers what happens to a request, or to the data it writes, when a service it calls goes down, is slow or returns errors ("what happens to a booking if the email service is down?"), by exercising relevant failures and observing caller outcomes. Applies even when nobody says mock or simulation, and a `postman/simulations/` directory in the repository is itself a reason to load this before changing code it covers. To give a frontend or another team a stand-in for an API, use api-mocking. Covers `postman simulation`.
 ---
 
 # API Simulation
 
-A simulation serves several mocks as one environment, each reached by its
-routeKey: as a path prefix by default, or as an `x-mock-slug` header when the
-caller's paths can't change.
-
-Run your code against it rather than stubbing its HTTP client in tests or
-calling the real services. A stub skips the client, config, timeouts and
-error handling that will run in production; the real services need
-credentials and leave side effects. A simulation runs that code over real
-HTTP, the same way in CI, and its log shows what each dependency was asked.
-
-Do only what the task needs. If a `.sim.yaml` in `postman/simulations/`
-already covers it, run that one, and read the `<name>.context.md` beside it
-first: it holds the commands, the preconditions and the failures earlier runs
-hit, so reading it costs less than rebuilding any of that from the `.sim.yaml`
-and the handlers. One request through the changed path proves a change; build
-failure variants only when asked how the code fails or when it must survive a
-failure.
+Simulation lets you control how dependencies behave and explore how your code
+responds to different outcomes. This makes it easier to test assumptions
+repeatedly without real calls changing data, spending money, or notifying
+someone. Simulation context records those assumptions, the evidence supporting
+them, and what remains unknown. As sessions build on this context, it helps
+surface incorrect assumptions and avoid repeated investigation.
+
+Together, the simulation and its context provide a place to explore changes
+and identify what still needs validation against the real dependencies.
+
+Check whether an existing simulation in `postman/simulations/` covers the
+dependency interactions relevant to the task. Reusing its mocks and wiring
+can avoid rebuilding an environment; extend it only where the behavior you
+need to exercise is missing.
+
+The `<name>.context.yaml` beside a simulation records those assumptions, their
+supporting evidence, and unresolved questions so later sessions can build on
+earlier findings. For example, a timeout from `/payments` does not establish
+whether the payment failed or completed before the response arrived. The
+context file will document what has been established about the real provider
+and identify what still needs verification.
+
+A simulation serves several mocks as one environment: by default behind a
+proxy that answers for the dependencies' own hostnames, so the code under test
+keeps the base URLs it ships with, or on one local port where each member is
+reached by its routeKey.
+
+Simulation adds value when the result depends on real HTTP behavior, such as
+client configuration, serialization, timeouts or retries, and the real
+dependencies are unavailable or unsuitable for the exercise. Stubbing the
+HTTP client can bypass those behaviors. Choose verification that exercises
+what matters to the task: an existing test may already answer a local logic
+question, while a claim about the provider may need its contract or a real
+service check. A simulation's log shows what each stand-in was asked.
+
+Define the expected outcome and what observation would distinguish correct
+from incorrect behavior, including side effects when relevant. A request
+through the changed path shows that it ran; its response and resulting state
+determine whether the expectation held. Choose boundary and failure cases
+from the behavior changed and the consequences of getting it wrong.
 
 `postman simulation` needs CLI 1.70.0 or later (`postman --version`; an older
 CLI answers `postman simulation -h` with its general help).
@@ -33,7 +56,9 @@ CLI answers `postman simulation -h` with its general help).
   shared code; ask about the repo by its `git remote` name, because a close
   name matches another repo.
 - **Each member needs a mock: see `api-mocking`,** which looks for the owning
-  team's published mock before building one. For a question, one built from
+  team's published mock before building one. Finding and pulling an owner's
+  mock needs a signed-in CLI; check `postman status` first, and signed out,
+  build each mock and record that the owner search was skipped. For a question, one built from
   the contract will do; one that invents responses can send the caller down a
   path the real service never would. In a mock you build, answer `501` for calls this path
   doesn't make: a `404` reads to the caller like a real "not found".
@@ -52,45 +77,37 @@ The run is a server that never exits, so a foreground command never returns.
 Start it in the background, its log in a file:
 
 ```bash
-postman simulation run postman/simulations/checkout-dev.sim.yaml --port 4900 --output ndjson > sim.ndjson 2> sim.err &
+postman simulation run postman/simulations/checkout-dev.sim.yaml --proxy --output ndjson > sim.ndjson 2> sim.err &
 ```
 
-`--port` is optional. It's up when `sim.ndjson` has a `listening` event; a
-start-up error is in `sim.err`. That event carries the bound port and each
-member's address, so take the base URLs from it rather than from the port you
-asked for. Stop it with
+`--proxy` is how to run it unless something below rules it out: nothing about
+the code changes for the run — not a base URL, not a config file, not an SDK's
+built-in host — and because nothing the proxy answers for has to resolve, an
+internal hostname with no DNS record works.
+
+It's up when `sim.ndjson` has a `listening` event; a start-up error is in
+`sim.err`, a busy proxy port among them. Stop it with
 `pkill -INT -f "simulation run .*<file>.sim.yaml"`. Nothing reloads: restart
 it after a mock edit.
 
-Point the caller at it without changing what the code does once deployed.
-Under path routing, swap only the host and keep the path:
-`https://catalog.internal.example.com/v2` becomes
-`http://127.0.0.1:4900/catalog/v2`; a dropped `/v2` is the usual cause of a
-`404`. A hard-coded base URL should read an environment variable with
-today's value as the default. If the code mustn't change at all, run it
-behind the proxy instead, below.
-
-## Through a proxy, when no base URL can change
-
-`simulation run <file.sim.yaml> --proxy` puts the members behind a local
-forward proxy that answers for the dependencies' own hostnames, so the code
-keeps the base URLs it ships with. Any other host passes through to the real
-service. Reach for it when hostnames are hard-coded, built from config the
-change shouldn't touch, or owned by an SDK — and because nothing it answers
-for has to resolve, an internal hostname with no DNS record works.
-
 Read `postman simulation run --help` before driving it. The flags, what the
 caller's own process needs in order to reach the proxy, and what to do about a
 client that ignores it are all there and change with the CLI, so take them
 from the command rather than from here.
 
-Two things decide whether a proxied run proves anything. A member with no
-`origin:` in the `.sim.yaml` is never matched, so its traffic reaches the real
+What decides whether a proxied run proves anything is `origin:`. A member with
+none in the `.sim.yaml` is never matched, so its traffic reaches the real
 service and a run can come up having intercepted nothing — `simulation create`
 copies that field from the mock's manifest, so editing the manifest alone
 won't fix it ([reference/sim_yaml_schema.md](reference/sim_yaml_schema.md)).
-And conditions don't apply here: member `scenarios` are ignored, so failures
-need the one-port run.
+
+## Running it on one port instead
+
+`--port` puts every member on one local port, each addressable by its routeKey,
+with the code under test pointed at that port. Reach for it when a client has
+no proxy setting to honour, and when you want to address a member yourself —
+each one keeps a stable URL for the whole run, so a mock's control routes and
+its individual responses are a curl away.
 
 ## Reading the log
 
@@ -98,8 +115,8 @@ A passing test command doesn't show the dependency path ran: read
 `sim.ndjson`. A member with no `request` events isn't wired or isn't on this
 path. Some answers come from the simulation itself and mean wiring, not code:
 
-- `404 Unknown simulation member`: a base URL lost its routeKey, or a client
-  sent the wrong `x-mock-slug`.
+- `404 Unknown simulation member`, on a one-port run: a base URL lost its
+  routeKey, or a client sent the wrong `x-mock-slug`.
 - `501`, or a generated mock's `404 Endpoint not defined`: a call the mock
   doesn't model yet.
 - `502 Proxy error`: the member's process died, usually an async throw in a
@@ -108,12 +125,20 @@ path. Some answers come from the simulation itself and mean wiring, not code:
 
 ## When a dependency goes down
 
-Run it rather than reason from the code: each way of going down takes a
-different path through the caller, and a stub skips the client code that
-picks the path. Fail the one dependency in each shape that matters, a run
-each, with the others answering normally:
+Choose failures from the outcome the user needs to understand. A failure
+before a write, a timeout after a write may have completed, and a failure
+during compensation can expose different risks: lost work, duplicate writes
+or unreleased resources. Read the caller to identify relevant paths, then
+exercise the ones whose runtime behavior remains uncertain.
 
-- **Unreachable:** point its base URL at a port nothing listens on.
+Isolating one failure helps attribute the result. Combine failures or model
+partial completion when the question depends on their interaction. The
+injection must represent the event being investigated: delaying a response
+alone does not establish whether a write completed before the timeout.
+Examples of available techniques:
+
+- **Unreachable:** point its base URL at a port nothing listens on. This one
+  needs the one-port run, since under `--proxy` the base URLs are the point.
 - **Hanging:** give its member a `latency` condition longer than the
   client's timeout. If the client sets none, that is the finding: Node's
   `fetch` waits about five minutes, so say so rather than wait it out.
@@ -131,19 +156,24 @@ stock reserved and never released.
 
 ## Its context document
 
-Every simulation is created with a `<name>.context.md` beside it, holding what
-running this one has taught: the commands that start it and prove it's up, the
-preconditions and what breaks when one fails, what it takes for granted about
-the dependencies themselves, the data seeded to test with, the failures earlier
-runs already hit, and what a passing run still doesn't prove. The `.sim.yaml` says what the simulation is, not how it behaves, so
-this is the file that saves a session the search. A new one is mostly
-`@todo`s, which are the questions a first real run answers.
-
-Every line passes one test — the repo doesn't already state it — so it stays
-about a screenful, and a claim carries the date and the run that established
-it, because the log it came from isn't committed. Its sections and conventions
-are in [reference/context_file.md](reference/context_file.md); read that
-before writing it back.
+Every simulation is created with a `<name>.context.yaml` beside it, holding
+what the code is believed to rely on about the dependencies it calls — who the
+caller is taken to be, which plan or permission is assumed, the order calls go
+in, what gets retried, the shape of the data — and what each belief rests on.
+The `.sim.yaml` says what the simulation is, not what the services it stands in
+for do, so this is the record that saves a session the search.
+
+Read relevant claims before investigating the dependencies, and assess whether
+their evidence still applies to this task. Write what you established back
+into the document before you finish. Each claim carries a `status`,
+the `reason` the evidence adds up to it, the `verification` that was done and
+what it showed, and a `source` to re-check it against, so the next session can
+tell a claim a contract promises from one a request actually demonstrated.
+Preserve existing claims and their evidence when updating the file, including
+unresolved assumptions and historical findings. Its fixed schema and guidance
+on evidence and reuse are in
+[reference/context_file.md](reference/context_file.md); read that before
+writing to it.
 
 ## Keeping it
 
@@ -173,16 +203,21 @@ first. It fails on a pulled member, which keeps its owner's `id:`; copy it to
 
 ## Before you say it works
 
-Claim nothing until what you're testing actually ran: a service printed
-that it's listening and answered your request, or the frontend or test
-suite finished, and its calls are in the log. If its start command exited
-or hung, the run proved nothing; say so and why. Say what a pass proves,
+Claim a simulation passes only after the code under test ran and you observed
+the expected response or state change. Use its calls in the log to confirm
+the dependency path was exercised; for injected failures, use the caller
+outcomes described above. If startup failed or the relevant path never ran,
+report that limitation. Say what a pass proves,
 your code against these stand-ins rather than the real services, what still
 needs the real service before release, and where each mock came from,
 including when you skipped the owner's.
 
-Then write the run back into `<name>.context.md`, so the next session starts
-where this one ended: the `@todo`s it answered, whatever it found wrong, a
-precondition you had to discover, what broke and why, and which members served
-or stayed silent — the last is a line every run adds, so a member silent across
-several runs reads as a pattern rather than a one-off.
+Then write what you established back into `<name>.context.yaml`, so the next
+session starts where this one ended. Add or update claims that help a later
+session reuse the findings. For each claim the run settled or contradicted,
+update its `status`, the `verification` that was done and the `source` to
+re-check it against. Scope what you claim to what you actually
+exercised — "held in the scenarios run" rather than "works" — since the record
+is read later as evidence, and the two don't mean the same thing.
+[reference/context_file.md](reference/context_file.md) has what each field is
+for.