docs(azure): document Docker IGVM reproducibility

.agents/index.md

@@ -0,0 +1,13 @@
+---
+okf_version: "0.1"
+---
+
+# .agents — MigTD institutional knowledge
+
+* [Agent guide](../AGENTS.md) - **Read first.** Core rules, session ritual, and links into everything below.
+* [Knowledge index](knowledge/index.md) - All topical reference/playbook files (workflow, domain facts, build/release/test).
+
+# Skills
+
+* [migtd-review](skills/migtd-review/SKILL.md) - Security and correctness review playbook, triage scripts, and CI gauntlet.
+* [migtd-port](skills/migtd-port/SKILL.md) - Playbook for forward-porting Microsoft-fork changes onto an intel/main-based branch.

.agents/knowledge/anti-patterns.md

@@ -0,0 +1,30 @@
+---
+type: Reference
+title: Anti-patterns — Things To NOT Do
+description: Collected pushback items from past sessions — a checklist of mistakes to avoid repeating.
+tags: [anti-patterns, checklist]
+timestamp: 2026-07-10T19:26:55+00:00
+---
+
+# Anti-patterns — Things To NOT Do
+
+> Condensed in the root [agent guide](../../AGENTS.md). See
+> [Domain Facts](domain-facts.md) and [Code Style](code-style.md).
+
+- ❌ Forget the DCO `Signed-off-by` trailer.
+- ❌ Bundle unrelated changes into one commit.
+- ❌ Use `expect()` / `unwrap()` in production paths.
+- ❌ Rename parameters/fields gratuitously during a refactor.
+- ❌ Add a feature gate when "always-on" is the obvious right answer.
+- ❌ Dump full quotes or large buffers at log level INFO/DEBUG.
+- ❌ Re-flag VMM DoS as a finding.
+- ❌ Re-open the singleton-vector hypothesis for the cert_rot timeout.
+- ❌ Increase a buffer size to *work around* a bug instead of fixing the bug.
+- ❌ Run multiple `migtdemu.sh` invocations concurrently.
+- ❌ Force-push without `--force-with-lease=<branch>:<sha>`.
+- ❌ Force-push to `intel/*` or `ms/*` / `upstream/*` remotes.
+- ❌ Run `cargo fmt` repo-wide; only touch files you modified.
+- ❌ Add `.clawpatch/` or `.copilot-review-issues/` to source control
+  (gitignored).
+- ❌ Touch code in a sibling clone (e.g. `../MigTD2`) from the wrong checkout
+  — another agent may be working there.

.agents/knowledge/architecture-overview.md

@@ -0,0 +1,58 @@
+---
+type: Reference
+title: MigTD Architecture Overview (Azure Build)
+description: Agent-oriented map of MigTD's main functional areas for the Azure IGVM build — flow, transport, attestation, policy v2, and error codes — with pointers into source.
+tags: [architecture, azure, spdm, policy-v2, migration]
+timestamp: 2026-07-13T22:37:00+00:00
+---
+
+# MigTD Architecture Overview (Azure Build)
+
+Canonical source: [doc/MigTD_Functionality_Summary.md](../../doc/MigTD_Functionality_Summary.md)
+(335 lines, kept up to date independently — read it in full before making
+architectural changes). This file is a **navigation aid**: what exists where,
+so you know which doc/source to open next.
+
+## What MigTD is
+
+A `no_std` Rust TDX **Service TD** (`SERVTD_TYPE = 0`) that mutually
+remote-attests a migration source (MigTD-S) and destination (MigTD-D) over
+**SPDM**, evaluates both against **policy v2**, and exchanges the **Migration
+Session Key (MSK)** so the VMM can live-migrate a user TD. Entry point:
+`src/migtd/src/lib.rs` (`_start`) → `main()` in
+`src/migtd/src/bin/migtd/main.rs`.
+
+## Where things live (map, not detail)
+
+| Area | Source | Doc |
+|---|---|---|
+| End-to-end flow, MSK read/write, version negotiation | `src/migtd/src/bin/migtd/main.rs`, `migration/session.rs` | §2 |
+| VMM interface (`vmcall-raw` GHCI, request dispatch) | `src/migtd/src/migration/{data,session,event}.rs` | §3 |
+| Quote generation/verification (`igvm-attest`) | `src/attestation/src/{igvmattest,quote,attest}.rs` | §4 |
+| Measurement / event log | `src/migtd/src/event_log.rs` | §4 |
+| SPDM mutual attestation + secure session | `src/migtd/src/spdm/`, `migration/spdm_session.rs` | §5 |
+| Policy v2 evaluation | `src/policy/`, `src/migtd/src/mig_policy.rs` | §6, [policy-v2-workflow.md](policy-v2-workflow.md) |
+| TD binding / rebinding | `migration/servtd_ext.rs`, `migration/rebinding.rs` | §7, [init-tdinfo-servtd-ext.md](init-tdinfo-servtd-ext.md) |
+| Crypto (ECDSA P-384, X.509, COSE_Sign1) | `src/crypto/` | §9 |
+| Async runtime (no_std executor / tokio under emu) | `src/async/` | §10 |
+| Build/hashing tools | `tools/migtd-hash`, `tools/migtd-policy-generator`, etc. | §11, §12 |
+| AzCVMEmu emulation mode | `src/migtd/src/bin/migtd/cvmemu.rs` | §13, [azcvmemu-build-and-run.md](azcvmemu-build-and-run.md) |
+
+## Migration error codes (host-visible) — quick lookup
+
+| Code | Cause |
+|:----:|-------|
+| 1 | VMM-provided data not as expected |
+| 3 | Out of memory |
+| 4 | TDX module error (often mismatched `SERVTD_INFO_HASH`) |
+| 5 | Failed to establish host communication channel |
+| 6 | SPDM/secure-session error (remote quote verification or handshake aborted) |
+| 7 | Unable to obtain the quote |
+| 8 | Remote quote does not satisfy the migration policy |
+
+## Explicitly out of scope of the Azure-focused doc
+
+The implemented optional one-hash TCB-mapping / CoRIM endorsement path
+(`servtd_corim`) and
+non-Azure options (RA-TLS, virtio/vsock transports, `bin` image format) — see
+[doc/MigTD_Functionality_Summary.md](../../doc/MigTD_Functionality_Summary.md) scope note.

.agents/knowledge/azcvmemu-build-and-run.md

@@ -0,0 +1,62 @@
+---
+type: Reference
+title: AzCVMEmu Build & Run — Agent Cheat Sheet
+description: Feature-flag combinations, prerequisites, and migtdemu.sh invocations for building/running MigTD as a standard Rust app under Azure CVM Emulation.
+tags: [azcvmemu, build, emu, tpm]
+timestamp: 2026-07-13T22:37:00+00:00
+---
+
+# AzCVMEmu Build & Run — Agent Cheat Sheet
+
+Canonical source: [doc/AzCVMEmu.md](../../doc/AzCVMEmu.md). Read that in full for
+architecture rationale; this is the command/decision cheat sheet.
+
+## Feature flag → mode
+
+| Cargo features (with `--no-default-features`) | Attestation | Requires |
+|---|---|---|
+| `AzCVMEmu` | Real Azure IMDS attestation | Azure TDX CVM + TPM2-TSS |
+| `AzCVMEmu,test_mock_report` | Mock TD reports/quotes, full attestation flow | Any Linux |
+| `AzCVMEmu,igvm-attest` | `servtd_get_quote` path | Azure TDX CVM + TPM2-TSS |
+| `AzCVMEmu,igvm-attest,test_mock_report` | IGVM attest + mock | Any Linux |
+| `AzCVMEmu,test_disable_ra_and_accept_all` | Attestation bypassed entirely | Any Linux |
+
+`AzCVMEmu` implies `main` + `vmcall-raw` (don't add them explicitly) and
+**only** works with the `vmcall-raw` transport.
+
+## Preferred invocation: `migtdemu.sh`
+
+```bash
+./migtdemu.sh --skip-ra --both --no-sudo --log-level info          # no attestation, any Linux
+./migtdemu.sh --mock-report --both                                  # full attestation, mock data
+./migtdemu.sh --igvm-attest --mock-report --both                    # servtd_get_quote path
+./migtdemu.sh --policy-v2 --policy-file <f> --policy-issuer-chain-file <f> --both
+./migtdemu.sh --features spdm_attestation --both
+```
+
+`--both` runs destination in the background then source in the foreground;
+destination logs go to `dest.out.log`. See
+[verification-and-checklist.md](verification-and-checklist.md) for the
+**do-not-run-concurrently** rule (hardcoded port 8001, `taskset -c 0`, shared
+`target/release/migtd`).
+
+## TPM2-TSS gotcha
+
+Runtime TPM2-TSS (`libtss2-esys`, `libtss2-tcti-device0`) is needed **unless**
+you use `--skip-ra` (`test_disable_ra_and_accept_all`), which uses mock TD
+reports/quotes and needs no TPM at all. The script auto-sets
+`TSS2_TCTI=device:/dev/tpmrm0` and enables sudo automatically when
+`/dev/tpmrm0` exists and permissions are insufficient (not needed for
+`--mock-report` or `--skip-ra`).
+
+## Manual run requires two env vars
+
+```bash
+export MIGTD_POLICY_FILE="/path/to/policy.json"
+export MIGTD_ROOT_CA_FILE="/path/to/root_ca.cer"
+```
+
+Missing/nonexistent files → hard exit. See
+`deps/td-shim-AzCVMEmu/README.md` for the emulation-layer implementation
+details (RTMR extension as no-op, REPORTDATA bypass rationale — cross-check
+against [Security Bypasses](security-bypasses.md)).