1 files changed, 71 insertions, 0 deletions
diff --git a/docs/explanation/README.md b/docs/explanation/README.md
index cc3ec49..f477b73 100644
--- a/docs/explanation/README.md
+++ b/docs/explanation/README.md
@@ -80,6 +80,77 @@ Explanation documentation helps you **understand concepts** and design decisions
 ---
+### [Purgatory Design](purgatory-design.md)
+**In-memory holding area for events awaiting git data**
+**Topics:**
+- The "which arrives first?" problem
+- Separate storage for state vs PR events
+- Late binding for state events
+- Bidirectional waiting for PR events
+- Authorization during push
+**Read when:** You want to understand how ngit-grasp handles out-of-order event/git data arrival
+---
+### [GRASP-02 Proactive Sync](grasp-02-proactive-sync.md)
+**Relay-to-relay synchronization for repository discovery**
+**Topics:**
+- Negentropy-based event sync
+- Repository announcement discovery
+- Relay management and reconnection
+- Layer 2 filtering
+- Bootstrap and dynamic relay discovery
+**Read when:** You want to understand how ngit-grasp discovers and syncs repositories across relays
+---
+### [GRASP-02 Purgatory Git Data Fetching](grasp-02-proactive-sync-purgatory-git-data.md)
+**Proactive git data fetching from remote servers**
+**Topics:**
+- Identifier-based batching
+- Exponential backoff with fresh start
+- Domain throttling (5 concurrent, 30/min)
+- Debounced delays (3min user, 500ms sync)
+- 30-minute expiry
+- Mock-based testability
+**Read when:** You want to understand how purgatory automatically fetches missing git data
+---
+### [Unified Git Data Sync](unify-git-data-sync.md)
+**Shared processing for git push and purgatory sync paths**
+**Topics:**
+- Why unify push and sync processing
+- OID syncing to owner repos
+- Ref alignment logic
+- Event release from purgatory
+- WebSocket notification
+**Read when:** You want to understand how git data is processed consistently regardless of arrival method
+---
+### [Monitoring Overview](monitoring.md)
+**Prometheus metrics and observability**
+**Topics:**
+- Metrics philosophy
+- Connection tracking
+- Git operation metrics
+- Nostr event metrics
+- Privacy considerations
+**Read when:** You want to understand how to monitor ngit-grasp in production
+---
 ## Planned Explanation Documentation
 ### GRASP Protocol Design

diff --git a/docs/explanation/README.md b/docs/explanation/README.md index cc3ec49..f477b73 100644 --- a/docs/explanation/README.md +++ b/docs/explanation/README.md
@@ -80,6 +80,77 @@ Explanation documentation helps you understand concepts and design decisions
80		80
81	---	81	---
82		82
		83	### [Purgatory Design](purgatory-design.md)
		84	In-memory holding area for events awaiting git data
		85
		86	Topics:
		87	- The "which arrives first?" problem
		88	- Separate storage for state vs PR events
		89	- Late binding for state events
		90	- Bidirectional waiting for PR events
		91	- Authorization during push
		92
		93	Read when: You want to understand how ngit-grasp handles out-of-order event/git data arrival
		94
		95	---
		96
		97	### [GRASP-02 Proactive Sync](grasp-02-proactive-sync.md)
		98	Relay-to-relay synchronization for repository discovery
		99
		100	Topics:
		101	- Negentropy-based event sync
		102	- Repository announcement discovery
		103	- Relay management and reconnection
		104	- Layer 2 filtering
		105	- Bootstrap and dynamic relay discovery
		106
		107	Read when: You want to understand how ngit-grasp discovers and syncs repositories across relays
		108
		109	---
		110
		111	### [GRASP-02 Purgatory Git Data Fetching](grasp-02-proactive-sync-purgatory-git-data.md)
		112	Proactive git data fetching from remote servers
		113
		114	Topics:
		115	- Identifier-based batching
		116	- Exponential backoff with fresh start
		117	- Domain throttling (5 concurrent, 30/min)
		118	- Debounced delays (3min user, 500ms sync)
		119	- 30-minute expiry
		120	- Mock-based testability
		121
		122	Read when: You want to understand how purgatory automatically fetches missing git data
		123
		124	---
		125
		126	### [Unified Git Data Sync](unify-git-data-sync.md)
		127	Shared processing for git push and purgatory sync paths
		128
		129	Topics:
		130	- Why unify push and sync processing
		131	- OID syncing to owner repos
		132	- Ref alignment logic
		133	- Event release from purgatory
		134	- WebSocket notification
		135
		136	Read when: You want to understand how git data is processed consistently regardless of arrival method
		137
		138	---
		139
		140	### [Monitoring Overview](monitoring.md)
		141	Prometheus metrics and observability
		142
		143	Topics:
		144	- Metrics philosophy
		145	- Connection tracking
		146	- Git operation metrics
		147	- Nostr event metrics
		148	- Privacy considerations
		149
		150	Read when: You want to understand how to monitor ngit-grasp in production
		151
		152	---
		153
83	## Planned Explanation Documentation	154	## Planned Explanation Documentation
84		155
85	### GRASP Protocol Design	156	### GRASP Protocol Design