docs: add guidance to keep architecture docs updated

- Added CRITICAL warning section to AGENTS.md about treating architecture
  docs as living documents
- Mark 'Keep Architecture Docs Updated' item as fixed in grasp-01 learnings
- Mark 'Document actual architecture' technical debt item as fixed

This addresses a key learning from GRASP-01 where docs described plans
rather than implementation, causing confusion.

2 files changed, 15 insertions, 2 deletions

diff --git a/AGENTS.md b/AGENTS.md
index 236602b..6fbec69 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -172,6 +172,17 @@ fn test_audit_tags_automatically_added() {
 
 ## Documentation
 
+**⚠️ CRITICAL: Keep Architecture Docs Updated**
+
+Architecture and design documents are LIVING DOCUMENTS. When implementation diverges from the documented plan:
+
+1. **Update the doc IMMEDIATELY** - Don't wait until "later"
+2. **Document what was actually built**, not what was originally planned
+3. **Note why decisions changed** - Future readers need this context
+4. **Files to watch:** `docs/explanation/architecture.md`, `docs/explanation/decisions.md`
+
+This was a key learning from GRASP-01: docs described plans, not implementation, causing confusion.
+
 **Diátaxis Framework Used:**
 
 - `docs/tutorials/` - Learning-oriented
diff --git a/docs/learnings/grasp-01-implementation.md b/docs/learnings/grasp-01-implementation.md
index 719f751..14ab452 100644
--- a/docs/learnings/grasp-01-implementation.md
+++ b/docs/learnings/grasp-01-implementation.md
@@ -150,12 +150,14 @@ This enables parallel CI runs without interference.
 
 ## What I'd Do Differently
 
-### 1. Keep Architecture Docs Updated
+### 1. ~~Keep Architecture Docs Updated~~ ✅ FIXED
 
 **What happened:** Architecture design docs were essential to start - they guided the implementation. But as we made decisions (e.g., hyper instead of actix-web), the docs weren't updated to reflect reality.
 
 **Better approach:** Treat architecture docs as living documents. When implementation diverges from the plan, update the doc immediately. The initial design document was valuable and should remain, but it should reflect what was built.
 
+**Resolution:** Added prominent warning to [`AGENTS.md`](../../AGENTS.md) with explicit guidance to keep architecture docs updated as living documents.
+
 ### 2. ~~Smaller Nip34WritePolicy~~ ✅ DONE
 
 **What happened:** The `Nip34WritePolicy` grew to ~900 lines handling all event types.
@@ -192,7 +194,7 @@ The main [`Nip34WritePolicy`](src/nostr/builder.rs:51) now delegates to these su
 
 1. ~~**Split `Nip34WritePolicy`**~~ ✅ DONE - Split into sub-policies in [`src/nostr/policy/`](src/nostr/policy/mod.rs:1)
 2. **Add unit tests for policy logic** - Currently relies on integration tests
-3. **Document actual architecture** - Docs describe plans, not implementation
+3. ~~**Document actual architecture**~~ ✅ FIXED - Added guidance to AGENTS.md to keep docs updated as living documents
 
 ### Medium Priority