diff --git a/implementation-guide-taproot-assets-l402-fastapi.md b/implementation-guide-taproot-assets-l402-fastapi.md
index cd92a46..dda6497 100644
--- a/implementation-guide-taproot-assets-l402-fastapi.md
+++ b/implementation-guide-taproot-assets-l402-fastapi.md
@@ -2,9 +2,12 @@
 
 **Project:** Timmy Agent  
 **Date:** March 18, 2026  
+**Validated against:** tapd v0.7.x / litd v0.14.x / LND v0.20.0-beta (December 2025 release cycle)  
 **Scope:** Concrete architecture and code paths for TIMMY token minting, Lightning channel integration, L402 payment gating, and FastAPI/Python wiring  
 **Convention:** `⚠️ NOT PRODUCTION-READY` marks anything that is alpha, testnet-only, or has a known breaking limitation. `✅ MAINNET` marks confirmed production-viable paths.
 
+> **Proto field caveat:** gRPC stubs must be regenerated from the `.proto` files of each tapd release. Field names and message structures may change between minor versions. Always run `python -m grpc_tools.protoc` against the proto files from the exact tapd version you are running, and re-validate field names in the Python snippets below against your generated stubs before production use.
+
 ---
 
 ## Prerequisites and Stack Versions
@@ -410,6 +413,10 @@ TAPD_TLS    = Path(os.getenv("TAPD_TLS_PATH",  "~/.taproot-assets/tls.cert")).ex
 TAPD_MAC    = Path(os.getenv("TAPD_MAC_PATH",   "~/.taproot-assets/data/mainnet/admin.macaroon")).expanduser()
 TIMMY_ID    = bytes.fromhex(os.getenv("TIMMY_ASSET_ID", ""))  # 32-byte asset id hex
 MACAROON_ROOT_KEY = bytes.fromhex(os.getenv("MACAROON_ROOT_KEY", secrets.token_hex(32)))
+# ⚠️ PRODUCTION REQUIREMENT: MACAROON_ROOT_KEY must be a stable, persistent secret stored in an
+# environment variable or secrets manager. The default fallback (secrets.token_hex) generates a
+# new random key on every process restart, which INVALIDATES ALL PREVIOUSLY ISSUED MACAROONS.
+# Set MACAROON_ROOT_KEY once at deployment and never rotate it without invalidating active sessions.
 
 # ── tapd gRPC channel ────────────────────────────────────────────────────────
 def _tapd_creds():
@@ -700,4 +707,22 @@ The Lightning Labs team declared **forward compatibility** starting with the v0.
 
 ---
 
-*Sources: Lightning Labs official tapd documentation and API reference (lightning.engineering), tapd GitHub repository (v0.7), LND v0.20 release notes, Taproot Assets Builder's Guide, echennells/taproot_assets LNbits extension, pymacaroons library documentation, L402 specification (lightning.engineering/posts), Voltage/Joltz/LnFi edge node announcements.*
+## References
+
+| Claim | Source | Date |
+|-------|--------|------|
+| LND v0.20 required for tapd v0.7 | [Lightning Labs API Docs — tapd](https://lightning.engineering/api-docs/api/taproot-assets/) | Dec 2025 |
+| tapd v0.7 mainnet release | [tapd GitHub releases](https://github.com/lightninglabs/taproot-assets/releases) | Dec 2025 |
+| TA Lightning channel support live mainnet v0.6 | [Lightning Labs blog — Taproot Assets v0.6](https://lightning.engineering/posts/2025-06-taproot-assets-v0-6/) | Jun 2025 |
+| BTC + TA channels in same UTXO | [Taproot Assets Builder's Guide](https://docs.lightning.engineering/lightning-network-tools/taproot-assets) | 2025 |
+| RFQ protocol mainnet, multi-path receive (20 channels) | tapd v0.6 release notes | Jun 2025 |
+| AddressV2 static reusable addresses | tapd v0.7 release notes | Dec 2025 |
+| Edge node operators: Voltage, Amboss, Joltz, Speed, LnFi | [Voltage blog](https://voltage.cloud), [Joltz docs](https://joltz.app) | 2025–2026 |
+| Aperture L402 sats-only (no native TA payment support) | [Aperture GitHub](https://github.com/lightninglabs/aperture) — no TA payment backend | Mar 2026 |
+| LNbits TA extension (echennells) | [echennells/taproot_assets GitHub](https://github.com/echennells/taproot_assets) | 2025 |
+| Data loss warning — LND seed insufficient for TA restore | [tapd official docs safety warning](https://docs.lightning.engineering/lightning-network-tools/taproot-assets) | 2025 |
+| Multi-path send not implemented in v0.7 | tapd v0.7 release notes / GitHub milestones | Dec 2025 |
+| Alpha software warning, bugs and missing backup mechanisms | [tapd docs](https://docs.lightning.engineering/lightning-network-tools/taproot-assets) | 2025 |
+| pymacaroons library | [pymacaroons PyPI](https://pypi.org/project/pymacaroons/) | — |
+| L402 specification | [lightning.engineering/posts/2023-06-07-l402](https://lightning.engineering/posts/2023-06-07-l402/) | Jun 2023 |
+| LangChainBitcoin L402 Python | [lightninglabs/LangChainBitcoin](https://github.com/lightninglabs/LangChainBitcoin) | 2023 |