docs: insider references either explain themselves or go

docs/api-surface.md

@@ -7,7 +7,7 @@ The MicroVM API ships as an SDK service model. Three copies are available and mu
 | Source | Use |
 |--------|-----|
 | `service-2.json` vendored in KubeMicroVM's `operator-aws-client` | Machine-readable operation list, shapes, paginators. What the inventory was extracted from |
-| aws-sdk-go-v2 generated client | The wire-parity reference, the role fly-go plays for mudflaps |
+| aws-sdk-go-v2 generated client | The wire-parity reference — the provider-generated client that decides field truth |
 | AWS API reference docs | Human-readable semantics, error taxonomy |
 
 Cross-checked 2026-07-29 (#2). aws-sdk-go-v2 ships both services (`service/lambdamicrovms`, `service/lambdacore`; Smithy models `lambda-microvms.json` and `lambda-core.json` under `codegen/sdk-codegen/aws-models/`). Operation lists and every enum match the vendored copies exactly. The SDK's Smithy models are canonical for the wire-parity contract from here, since AWS publishes them continuously. The sigv4 signing name is `lambda` for both services (sdkIds `Lambda Microvms`, `Lambda Core`), which is what the conformance harness signs with.
@@ -178,6 +178,6 @@ Two situations remain unrecorded because nothing reaches them. A `PENDING` VM an
 
 ## Health and introspection
 
-`/_m80/health` reports implemented operations against the model inventory, the mudflaps convention, plus the regions the store has been asked about. `/_m80/vm/{microvmId}/` reaches a VM's endpoint stub without forging a `Host` header. `POST /_m80/inject` arms a failure — a build that settles `FAILED`, or a connector that settles `FAILED` with one of the seven reason codes — and answers 404 naming the flag unless m80 was started with `-enable-injection`. See [Lifecycle](lifecycle.md#drift-levers).
+`/_m80/health` reports implemented operations against the model inventory, plus the regions the store has been asked about. `/_m80/vm/{microvmId}/` reaches a VM's endpoint stub without forging a `Host` header. `POST /_m80/inject` arms a failure — a build that settles `FAILED`, or a connector that settles `FAILED` with one of the seven reason codes — and answers 404 naming the flag unless m80 was started with `-enable-injection`. See [Lifecycle](lifecycle.md#drift-levers).
 
 There is no clock endpoint. Transitions run on an injected clock and Go tests advance it directly, but nothing exposes that over HTTP, so a black-box client cannot skip a delay — it waits, or it starts m80 with a shorter `-build-delay`. An earlier draft of this page described a `/_m80/clock` hook that was never built.

docs/floci.md

@@ -4,7 +4,7 @@
 
 | Concern | Home | Why |
 |---------|------|-----|
-| Full-fidelity service emulation | m80 | Owned cadence against a churning preview-fresh API, small container the KubeMicroVM community can adopt, mudflaps mold |
+| Full-fidelity service emulation | m80 | Owned cadence against a churning preview-fresh API, small container the KubeMicroVM community can adopt — the [mudflaps](https://github.com/INTENTIUS/mudflaps) mold (m80's sibling emulator, for the Fly.io Machines API) |
 | `AWS::Lambda::MicrovmImage` and `AWS::Lambda::NetworkConnector` through CloudFormation | floci | CFN emulation can only live where the CFN engine lives. chant's `MicrovmApp` and the kit's image stack deploy through CFN |
 | Conformance contract | shared suite | See [conformance.md](conformance.md) |
 

docs/lifecycle.md

@@ -14,7 +14,7 @@ Three layers, each with its own state enum.
 
 Versions also carry `MicrovmImageVersionStatus` (`ACTIVE`, `INACTIVE`), a separate axis from build progress. Architecture is `ARM_64` on `GRAVITON` only, m80 rejects anything else the way the service would.
 
-Build takes a deterministic delay on the injected clock, default a few seconds of wall time when no test clock is attached, so demos feel real and tests run instant. A failure injection knob forces `FAILED` for compensation testing, the same lever mudflaps grew in v0.5.0 for deploy-failure injection, which chant Ops testing needed.
+Build takes a deterministic delay on the injected clock, default a few seconds of wall time when no test clock is attached, so demos feel real and tests run instant. A failure injection knob forces `FAILED` for compensation testing.
 
 Deletion is asynchronous, recorded live: `DeleteMicrovmImage` answers `200` with `state: DELETING`, the image stays listable until the delete drains, and its name stays reserved (a create during the window gets `400 "already exists"`). A delete while the first build is still running is refused outright with `400 "Cannot delete MicroVM image in its current state"`. m80 models both: the DELETING window on the clock, and the mid-build refusal.
 
@@ -55,15 +55,15 @@ Recording these at all needed a harness change. A step's `until` block polls to
 | Resume | `SUSPENDED` back to `RUNNING` restores the state marker, a monotonic counter clients can read through the endpoint stub to prove state survived |
 | Terminate | Terminal. Subsequent mutations return `400 ValidationException`, recorded — neither modeled conflict type |
 
-Transient states settle on the injected clock with short deterministic delays, the mudflaps pattern verbatim. The clock hook advances time in tests, so a suspend-after-15-minutes policy is testable in microseconds.
+Transient states settle on the injected clock with short deterministic delays — a pattern proven in [mudflaps](https://github.com/INTENTIUS/mudflaps) before it was built here. The clock hook advances time in tests, so a suspend-after-15-minutes policy is testable in microseconds.
 
 ## Network connectors
 
 `NetworkConnectorState`: `PENDING`, `ACTIVE`, `INACTIVE`, `FAILED`, `DELETING`, `DELETE_FAILED`, with a reason-code enum (`InvalidSubnet`, `InvalidSecurityGroup`, `SubnetOutOfIPAddresses`, `InsufficientRolePermissions`, `Ec2RequestLimitExceeded`, `DisallowedByVpcEncryptionControl`, `InternalError`) shared by state and last-update status. The reason codes are a gift, each one is a realistic failure m80 can inject without inventing anything, and KubeMicroVM's MicroVMNetwork reconciler has visible handling to exercise.
 
 ## Drift levers
 
-KubeMicroVM's drift detection and auto-suspend features watch for the service changing state underneath the CRs, so m80 can fail things the real service would only fail by bad luck. This is m80's version of mudflaps' failure injection, a feature the real service will never offer a test suite.
+KubeMicroVM's drift detection and auto-suspend features watch for the service changing state underneath the CRs, so m80 can fail things the real service would only fail by bad luck. This is failure injection doing what the real service never will for a test suite: breaking on request.
 
 Two levers: `images.Service.FailNextBuild` forces the next build of a named image to `FAILED`, and `connectors.Service.FailNext` settles the next connector of a given name into `FAILED` carrying any of the seven reason codes. Neither can be provoked against real AWS on demand — you cannot ask EC2 to run a subnet out of addresses — which is the whole reason they exist.
 

docs/scope.md

@@ -20,7 +20,7 @@ The Lambda MicroVMs control plane and the minimal data-plane edges a client can
 
 | Not emulated | Why |
 |--------------|-----|
-| Actually running guest code | m80 is control-plane. The endpoint stub is observable, not a VM. mudflaps drew the same line and it held |
+| Actually running guest code | m80 is control-plane. The endpoint stub is observable, not a VM. [mudflaps](https://github.com/INTENTIUS/mudflaps) — the same idea for the Fly.io Machines API — drew the same line and it held |
 | CloudFormation | Lives in floci where the CFN engine is, see [floci.md](floci.md) |
 | Replica pools, classes, sidecar injection | KubeMicroVM operator constructs, above the service API |
 | IAM evaluation | Roles and ARNs are accepted and echoed, never evaluated |
@@ -40,7 +40,7 @@ Some requests reach neither: the model permits them and nothing was ever recorde
 
 ## Fidelity anchors
 
-Wire shapes come from the AWS SDK service model. KubeMicroVM vendors the model JSON in `operator-aws-client/src/main/resources/codegen-resources/service-2.json`, and aws-sdk-go-v2 generates from the same source. Field parity with the generated Go client is the contract, mirroring mudflaps' fly-go rule.
+Wire shapes come from the AWS SDK service model. KubeMicroVM vendors the model JSON in `operator-aws-client/src/main/resources/codegen-resources/service-2.json`, and aws-sdk-go-v2 generates from the same source. Field parity with the generated Go client is the contract: the provider publishes that client continuously, so it is the wire-truth reference nothing hand-written can drift from.
 
 Behavioral truth comes from the AWS docs and, where docs are silent, from probing the real service and recording the answer in the conformance suite. Silence in the docs is never license to invent.