Issue #3 Expand the sample wiki with one more real-world gotcha

examples/sample-repo/.almanac/pages/payment-idempotency-keys.md

@@ -0,0 +1,13 @@
+---
+title: Payment Idempotency Keys
+summary: "Always pass an idempotency key when calling the payment provider to safely retry authorizations."
+topics: [gotchas, payments]
+files:
+  - src/payments.ts
+---
+
+# Payment Idempotency Keys
+
+When retrying an authorization request with the payment provider, it is critical to use an idempotency key. This ensures that the payment provider will not charge the customer twice if the first request succeeded but we timed out while waiting for the response.
+
+Agents editing [[src/payments.ts]] should ensure that any calls to the provider include an idempotency key generated at the beginning of the checkout session.

examples/sample-repo/src/payments.ts

@@ -1,7 +1,7 @@
-export async function authorizePayment(amountCents: number): Promise<string> {
+export async function authorizePayment(amountCents: number, idempotencyKey?: string): Promise<string> {
   if (amountCents <= 0) {
     throw new Error("amountCents must be positive");
   }
 
-  return "receipt_sample";
+  return "receipt_sample_" + (idempotencyKey || "none");
 }