15 files changed, 5556 insertions, 24 deletions

diff --git a/docs/archive/2026-01-relay-ngit-dev-migration/README.md b/docs/archive/2026-01-relay-ngit-dev-migration/README.md
new file mode 100644
index 0000000..424067c
--- /dev/null
+++ b/docs/archive/2026-01-relay-ngit-dev-migration/README.md
@@ -0,0 +1,61 @@
+# relay.ngit.dev Migration Archive (January 2026)
+
+**Status:** Reference only - not maintained
+
+This directory contains the migration guide and scripts used during the 
+relay.ngit.dev migration from ngit-relay to ngit-grasp in January 2026.
+
+## ⚠️ Important
+
+These materials are **archived for reference only**:
+
+- **Scripts are specific to the relay.ngit.dev migration context**
+- **Not designed for general use or other migrations**
+- **May not work without modification**
+- **Not maintained or supported**
+
+Do not expect these scripts to work out of the box for your migration.
+
+## What's Here
+
+- `migration-guide.md` - Lessons learned, approach, and context from the actual migration
+- `scripts/` - Analysis and validation scripts used during the migration process
+
+## Why Archive This?
+
+The relay.ngit.dev migration uncovered numerous bugs and edge cases that resulted 
+in critical production fixes. See commits in the `4bc5-relay-ngit-dev-migration-v2` 
+branch for details.
+
+These materials document:
+
+- Real-world migration challenges encountered
+- Debugging approaches that worked in practice
+- Context for production fixes merged from this branch
+- Iterative script development during active migration
+
+## Using This as Reference
+
+If you're planning a migration to ngit-grasp:
+
+1. **Read the migration guide** for conceptual approach and lessons learned
+2. **Review the scripts** to understand what kinds of analysis were needed
+3. **Expect to write your own scripts** tailored to your specific context
+4. **Test extensively** in a non-production environment first
+
+These materials show what was needed for one specific migration, not a 
+general-purpose migration toolkit.
+
+## Context
+
+This migration was completed in January 2026 and resulted in relay.ngit.dev 
+running ngit-grasp in production. The branch containing these materials also 
+includes critical fixes for:
+
+- Git protocol error handling
+- Naughty list false positives
+- Purgatory event tracking
+- Sync startup issues
+- Configuration management
+
+Those fixes are now part of the main codebase.
diff --git a/docs/archive/2026-01-relay-ngit-dev-migration/migration-guide.md b/docs/archive/2026-01-relay-ngit-dev-migration/migration-guide.md
new file mode 100644
index 0000000..abe2191
--- /dev/null
+++ b/docs/archive/2026-01-relay-ngit-dev-migration/migration-guide.md
@@ -0,0 +1,1030 @@
+# Migrate to ngit-grasp from another GRASP implementation
+
+This guide walks you through migrating a production GRASP relay to ngit-grasp. The process involves analyzing your existing data to identify repositories that need attention before switching over.
+
+## Compatibility
+
+This migration process works with any GRASP implementation that:
+
+- Stores git data in the `<npub>/<identifier>.git` directory structure
+- Uses standard GRASP events (kind 30617 announcements, kind 30618 state, kind 5 deletions)
+- Exposes a Nostr relay WebSocket endpoint
+
+**Known compatible implementations:**
+- ngit-relay (reference implementation)
+- ngit-grasp (when migrating between instances or from archive mode)
+- Other GRASP-compliant relays following the specification
+
+The migration scripts analyze Nostr events and git data directly, making them implementation-agnostic.
+
+## Quick Start
+
+Run the migration analysis with a single command:
+
+```bash
+# Basic analysis (fetches events, compares relays)
+./docs/how-to/migration-scripts/run-migration-analysis.sh \
+  --prod-relay wss://source-relay.example.com \
+  --archive-relay wss://target-relay.example.com
+
+# Full analysis (includes git sync check - run on VPS)
+./docs/how-to/migration-scripts/run-migration-analysis.sh \
+  --prod-relay wss://source-relay.example.com \
+  --archive-relay wss://target-relay.example.com \
+  --prod-git /var/lib/grasp-relay/git \
+  --archive-git /var/lib/ngit-grasp/git \
+  --service ngit-grasp.service
+```
+
+The script produces three output files:
+- `results/no-action-required.txt` - Repos ready for migration
+- `results/action-required.txt` - Repos needing intervention
+- `results/manual-investigation.txt` - Repos needing human review
+
+See [Running the Analysis](#running-the-analysis) for detailed options.
+
+## Prerequisites
+
+### Required Tools
+
+- **nak** - Nostr Army Knife for fetching events ([install](https://github.com/fiatjaf/nak))
+- **jq** - JSON processing (install via package manager)
+
+### For Full Analysis (VPS)
+
+- SSH access to the VPS running your source relay
+- Read access to git data directories
+- Access to systemd journal (for log extraction)
+
+### Verify Installation
+
+```bash
+# Check required tools
+nak --version
+jq --version
+git --version
+
+# Check optional tools (for VPS phases)
+journalctl --version
+```
+
+## Gotchas and Common Issues
+
+Before running the analysis, be aware of these common issues discovered during real migrations:
+
+### Git Must Be Installed
+
+The analysis scripts require `git` to be installed and in PATH. This may not be present on minimal VPS installations.
+
+```bash
+# Check if git is available
+which git || echo "Git not found - install it first"
+
+# Install on Debian/Ubuntu
+apt install git
+
+# Install on NixOS (add to configuration.nix)
+environment.systemPackages = [ pkgs.git ];
+```
+
+### Archive Relay May Only Be Accessible Locally
+
+If your archive relay is configured to listen only on localhost (e.g., `ws://localhost:7443`), you must run the analysis **on the VPS itself**, not from a remote machine.
+
+```bash
+# Check if archive relay is accessible
+# This will fail if run remotely against a localhost-only relay
+nak req -k 30618 --limit 1 ws://localhost:7443
+
+# Solution: SSH into the VPS and run analysis there
+ssh user@your-vps
+cd /path/to/scripts
+./run-migration-analysis.sh --archive-relay ws://localhost:7443 ...
+```
+
+### Git Data Paths May Differ from Defaults
+
+Different deployments store git data in different locations. **Always verify paths before running the analysis.**
+
+```bash
+# Find actual git data paths from service configuration
+systemctl cat ngit-relay.service | grep -E 'ExecStart|WorkingDirectory|Environment'
+systemctl cat ngit-grasp-*.service | grep -E 'ExecStart|WorkingDirectory|Environment'
+
+# Common locations:
+# - /var/lib/ngit-relay/git (default)
+# - /var/lib/ngit-grasp/git (default)
+# - /persistent/*/data/repos (custom deployments)
+
+# Verify the path exists and contains expected structure
+ls /path/to/git/npub1*/  # Should show *.git directories
+```
+
+### Phase 4 Needs the Correct Service Name
+
+> **CRITICAL:** Phase 4 extracts structured logs (`[PARSE_FAIL]`, `[PURGATORY_EXPIRED]`, `Invalid announcement` rejections) from journald. These logs **ONLY exist in ngit-grasp services**, NOT in ngit-relay services.
+
+If you specify an ngit-relay service (like `ngit-relay.service`), Phase 4 will find **zero logs** and produce empty results. This is a common mistake that wastes time and produces misleading analysis.
+
+**Correct service names (ngit-grasp):**
+- `ngit-grasp.service`
+- `ngit-grasp-relay-ngit-dev.service` (NixOS multi-instance)
+- `ngit-grasp-archive.service`
+
+**Incorrect service names (ngit-relay - NO structured logging):**
+- `ngit-relay.service`
+- `relay-ngit-dev.service`
+
+```bash
+# Find all ngit-related services
+systemctl list-units 'ngit-*' --all
+
+# Check which service has structured logging (should be ngit-grasp)
+journalctl -u ngit-grasp-*.service | grep -E '\[PARSE_FAIL\]|\[PURGATORY_EXPIRED\]|Invalid announcement' | head -5
+
+# Verify ngit-relay does NOT have structured logging
+journalctl -u ngit-relay.service | grep -E '\[PARSE_FAIL\]|\[PURGATORY_EXPIRED\]|Invalid announcement' | head -5
+# ^ This should return nothing
+
+# Use the archive service name for Phase 4
+./run-migration-analysis.sh ... --service ngit-grasp-relay-ngit-dev.service
+```
+
+The migration scripts now validate the service name and will **error** if you specify an ngit-relay service, preventing this common mistake.
+
+### Permission Issues with Service-Owned Directories
+
+Git data directories are typically owned by the service user and may require elevated permissions to read.
+
+```bash
+# Check directory permissions
+ls -la /var/lib/ngit-grasp/git
+
+# Options:
+# 1. Run as root/sudo
+sudo ./run-migration-analysis.sh ...
+
+# 2. Run as the service user
+sudo -u ngit-grasp ./run-migration-analysis.sh ...
+
+# 3. Add your user to the service group
+sudo usermod -aG ngit-grasp $USER
+# (logout/login required)
+```
+
+### Service Names Vary by Deployment
+
+NixOS multi-instance deployments use service names like `ngit-grasp-<instance>.service`. Always check actual service names.
+
+```bash
+# List all ngit services
+systemctl list-units 'ngit-*' --all --no-pager
+
+# Example output:
+# ngit-relay.service                loaded active running  ngit-relay
+# ngit-grasp-relay-ngit-dev.service loaded active running  ngit-grasp (relay-ngit-dev)
+```
+
+## Migration Overview
+
+The migration process has three stages:
+
+### Stage 1: Deploy Archive Instance
+
+Deploy ngit-grasp alongside your production relay:
+
+1. Configure ngit-grasp with:
+   - `domain` set to `<prod-domain>.internal` (temporary)
+   - `archiveService` set to your production domain
+   - Running on a different port
+
+2. Let it sync for ~1 hour to gather all events and git data
+
+### Stage 2: Analyze Data
+
+Run the migration analysis to identify:
+- Repositories successfully migrated (no action needed)
+- Repositories with incomplete data (need investigation)
+- Repositories with parse failures (may need re-announcement)
+
+### Stage 3: Switch Over
+
+Once all issues are resolved:
+1. Set `domain` to your production URL
+2. Disable archive mode
+3. Update your reverse proxy to point to ngit-grasp
+
+## Running the Analysis
+
+### Before You Start
+
+**Verify paths and service names** before running the analysis. Incorrect paths are the most common source of errors.
+
+```bash
+# 1. Find actual git data paths
+systemctl cat ngit-relay.service | grep -E 'ExecStart|data|git'
+systemctl cat ngit-grasp-*.service | grep -E 'ExecStart|data|git'
+
+# 2. Find service names
+systemctl list-units 'ngit-*' --all --no-pager
+
+# 3. Verify git data exists at the paths
+ls /path/to/prod/git/npub1*/ | head -5
+ls /path/to/archive/git/npub1*/ | head -5
+
+# 4. Check if archive relay is accessible
+nak req -k 30618 --limit 1 ws://localhost:7443  # or your archive URL
+```
+
+### Basic Usage
+
+```bash
+# Preview what will happen (dry run)
+./run-migration-analysis.sh \
+  --prod-relay wss://source-relay.example.com \
+  --archive-relay wss://target-relay.example.com \
+  --dry-run
+
+# Run the analysis
+./run-migration-analysis.sh \
+  --prod-relay wss://source-relay.example.com \
+  --archive-relay wss://target-relay.example.com
+```
+
+### Full Analysis on VPS
+
+**Important:** If your archive relay is localhost-only, you must run this on the VPS.
+
+```bash
+# First, discover your actual paths (see "Before You Start" above)
+# Then run with the correct values:
+
+./run-migration-analysis.sh \
+  --prod-relay wss://source-relay.example.com \
+  --archive-relay ws://localhost:7443 \
+  --prod-git /path/to/prod/git \
+  --archive-git /path/to/archive/git \
+  --service ngit-grasp-your-instance.service
+```
+
+### Phase Control
+
+Skip or run specific phases:
+
+```bash
+# Skip Phase 2 (use cached git sync data)
+./run-migration-analysis.sh ... --skip-phase-2
+
+# Run only Phase 1 (fetch events)
+./run-migration-analysis.sh ... --only-phase-1
+
+# Resume from Phase 3 (using existing data)
+./run-migration-analysis.sh ... --from-phase-3 --output work/migration-analysis-20260122-1430
+```
+
+### All Options
+
+| Option | Description |
+|--------|-------------|
+| `--prod-relay <url>` | Source relay WebSocket URL (required) |
+| `--archive-relay <url>` | Target relay WebSocket URL (required) |
+| `--prod-git <path>` | Git base directory for prod (enables Phase 2) |
+| `--archive-git <path>` | Git base directory for archive (enables Phase 2) |
+| `--service <name>` | Systemd service name for Phase 4 log extraction. **MUST be an ngit-grasp service** (not ngit-relay). Structured logging only exists in ngit-grasp. |
+| `--output <dir>` | Output directory (default: auto-generated) |
+| `--skip-phase-N` | Skip phase N (1-5) |
+| `--only-phase-N` | Run only phase N |
+| `--from-phase-N` | Start from phase N |
+| `--dry-run` | Show what would be executed |
+| `--continue-on-error` | Continue even if a phase fails |
+
+## Understanding Results
+
+### Summary File
+
+The `results/summary.txt` file provides an overview:
+
+```
+## Overview
+
+| Category | Count | Percentage |
+|----------|-------|------------|
+| No Action Required | 450 | 85.7% |
+| Action Required | 52 | 9.9% |
+| Manual Investigation | 23 | 4.4% |
+```
+
+### No Action Required
+
+Repositories in `no-action-required.txt` are ready for migration:
+
+```
+myrepo | npub1abc... | complete in both prod and archive
+oldrepo | npub1def... | deleted by user
+testrepo | npub1ghi... | empty/blank in both (user never pushed)
+```
+
+**Common reasons:**
+- `complete in both prod and archive` - Successfully migrated
+- `deleted by user` - User requested deletion (kind 5 event)
+- `empty/blank in both` - No git data was ever pushed
+- `purgatory expired` - System already handled the timeout
+
+### Action Required
+
+Repositories in `action-required.txt` need intervention:
+
+```
+myrepo | npub1abc... | complete in prod, missing from archive | trigger re-sync or investigate
+otherrepo | npub1def... | incomplete in both (prod=cat3, archive=cat2) | investigate git data source
+```
+
+**Common actions:**
+- **Re-sync needed**: Trigger the archive to re-fetch from the source
+- **Wait for sync**: Archive sync may still be in progress
+- **Investigate git source**: Original git data may be incomplete
+- **Fix parse failure**: Event format issue, may need re-announcement
+
+### Manual Investigation
+
+Repositories in `manual-investigation.txt` have unusual states:
+
+```
+weirdrepo | npub1abc... | in archive (cat1) but not in prod | may be new announcement or deleted from prod
+conflictrepo | npub1def... | complete in prod, missing from archive, parse failure logged | investigate parse failure
+```
+
+These require human judgment to determine the correct action.
+
+## Troubleshooting
+
+### "nak not found"
+
+Install nak from https://github.com/fiatjaf/nak:
+
+```bash
+# Using Go
+go install github.com/fiatjaf/nak@latest
+
+# Or download binary from releases
+```
+
+### "git not found"
+
+Git must be installed and in PATH:
+
+```bash
+# Check if git is available
+which git
+
+# Install on Debian/Ubuntu
+sudo apt install git
+
+# Install on NixOS (add to configuration.nix)
+environment.systemPackages = [ pkgs.git ];
+```
+
+### "Permission denied" on git directories
+
+Run with sudo or ensure your user has read access:
+
+```bash
+# Check permissions
+ls -la /var/lib/grasp-relay/git
+
+# Option 1: Run with sudo
+sudo ./run-migration-analysis.sh ...
+
+# Option 2: Run as service user
+sudo -u ngit-grasp ./run-migration-analysis.sh ...
+```
+
+### Archive relay connection failed
+
+If you get connection errors to the archive relay:
+
+```bash
+# Check if relay is running
+systemctl status ngit-grasp-*.service
+
+# Check if it's localhost-only
+# If archive is ws://localhost:7443, you MUST run on the VPS
+ssh user@your-vps
+./run-migration-analysis.sh --archive-relay ws://localhost:7443 ...
+```
+
+### Wrong git paths / "No such file or directory"
+
+Git data paths vary by deployment. Discover the actual paths:
+
+```bash
+# Find paths from service configuration
+systemctl cat ngit-relay.service | grep -E 'ExecStart|WorkingDirectory|Environment'
+systemctl cat ngit-grasp-*.service | grep -E 'ExecStart|WorkingDirectory|Environment'
+
+# Verify the path contains git repos
+ls /discovered/path/npub1*/
+```
+
+### Phase 2 takes too long
+
+The git sync check processes each repository individually (~20 minutes total). To speed up iteration:
+
+1. Run Phase 2 once and save the output
+2. Use `--skip-phase-2` for subsequent runs
+3. Use `--from-phase-3` to re-run classification with existing data
+
+### No parse failures found
+
+This is expected if:
+- ngit-grasp logging improvements aren't deployed yet
+- No events actually failed to parse
+
+The analysis will continue without log data.
+
+### Phase 4 finds no structured logs
+
+**Symptom:** Phase 4 completes but `parse-failures.txt` and `purgatory-expired.txt` are empty or contain only header comments.
+
+**Most common cause:** You're querying the wrong service (ngit-relay instead of ngit-grasp).
+
+Structured logging (`[PARSE_FAIL]`, `[PURGATORY_EXPIRED]`, `Invalid announcement` rejections) **only exists in ngit-grasp services**. If you specify an ngit-relay service, Phase 4 will find zero logs.
+
+**How to diagnose:**
+
+```bash
+# 1. Check what service you configured
+cat /path/to/output/config.txt | grep SERVICE_NAME
+
+# 2. If it contains "ngit-relay", that's the problem!
+# ngit-relay does NOT have structured logging
+
+# 3. Find the correct ngit-grasp service
+systemctl list-units 'ngit-grasp*' --all
+
+# 4. Verify the ngit-grasp service has structured logs
+journalctl -u ngit-grasp-relay-ngit-dev.service --since "7 days ago" | \
+  grep -E '\[PARSE_FAIL\]|\[PURGATORY_EXPIRED\]|Invalid announcement' | head -5
+```
+
+**How to fix:**
+
+```bash
+# Update SERVICE_NAME to the ngit-grasp archive service and re-run
+./run-migration-analysis.sh \
+  --prod-relay wss://relay.ngit.dev \
+  --archive-relay ws://localhost:7443 \
+  --service ngit-grasp-relay-ngit-dev.service \
+  --from-phase-4  # Skip phases 1-3, just re-run phase 4
+```
+
+**Other possible causes:**
+
+1. **Structured logging not deployed:** If the ngit-grasp instance doesn't have the logging improvements deployed, no structured logs will exist. Check the ngit-grasp version.
+
+2. **No events in time window:** If there genuinely were no parse failures, purgatory expiry events, or invalid announcement rejections, the files will be empty. This is valid - it means everything parsed successfully.
+
+3. **Wrong time range:** The default is 30 days. If your archive has been running longer, you may need `--since` to extend the range.
+
+**Prevention:** The migration scripts now validate the service name and will error if you specify an ngit-relay service.
+
+**Note on "Invalid announcement" rejections:** These are announcements (kind 30617) that were rejected by the write policy due to format violations. The most common reason is "multiple clone tags found" - the NIP-34 spec requires a single clone tag with multiple values, not multiple clone tags. These rejections are logged as `Event rejected by write policy ... reason=Invalid announcement: ...`.
+
+### Event counts are multiples of 250
+
+This suggests pagination may have failed. The scripts use `--paginate` by default, but if you see exactly 250, 500, 750 events, verify the relay is responding correctly.
+
+## Architecture
+
+### Analysis Phases
+
+The analysis is split into 5 modular phases:
+
+| Phase | Name | Time | Location | Description |
+|-------|------|------|----------|-------------|
+| 1 | Fetch Events | ~30s each | Local | Fetch events from both relays |
+| 2 | Git Sync Check | ~20 min each | VPS | Compare state events to git data |
+| 3 | Categorize & Compare | <1s | Local | Categorize and compare results |
+| 4 | Extract Logs | <30s | VPS | Extract parse failures and purgatory expiry |
+| 5 | Final Classification | <5s | Local | Combine all data into actionable results |
+
+### Phase Flow Diagram
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│ PHASE 1: Fetch Events (~30s, local)                             │
+│ Fetches kind 30618 (state), 30617 (announcements), 5 (deletion) │
+│ Run twice: once for prod, once for archive                      │
+└─────────────────────────────────────────────────────────────────┘
+                              ↓
+┌─────────────────────────────────────────────────────────────────┐
+│ PHASE 2: Git Sync Check (~20 mins, VPS required)                │
+│ Compares state event refs to actual git data on disk            │
+│ Categorizes into: complete, empty, partial, no-match            │
+└─────────────────────────────────────────────────────────────────┘
+                              ↓
+┌─────────────────────────────────────────────────────────────────┐
+│ PHASE 3: Categorize & Compare (fast, local)                     │
+│ Compares prod vs archive categories                             │
+│ Identifies gaps and sync issues                                 │
+└─────────────────────────────────────────────────────────────────┘
+                              ↓
+┌─────────────────────────────────────────────────────────────────┐
+│ PHASE 4: Log-Based Categories (VPS required)                    │
+│ Extracts structured logs from the archive service:              │
+│   - [PARSE_FAIL] - Events that failed to parse                  │
+│   - [PURGATORY_EXPIRED] - Repos where git data never arrived    │
+│   - "Invalid announcement" - Announcements rejected for format  │
+│     violations (e.g., multiple clone tags)                      │
+│ Provides context for why repos failed to sync                   │
+└─────────────────────────────────────────────────────────────────┘
+                              ↓
+┌─────────────────────────────────────────────────────────────────┐
+│ PHASE 5: Final Classification (fast, local)                     │
+│ Combines all data sources                                       │
+│ Outputs: no-action, action-required, manual-investigation       │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### Git Sync Categories
+
+Phase 2 categorizes repositories into 4 categories:
+
+| Category | Description | Meaning |
+|----------|-------------|---------|
+| 1 | Complete Match | All refs in state event match git data |
+| 2 | Empty/Blank | No git data available |
+| 3 | Partial Match | Some refs match, some don't |
+| 4 | No Match | Git data exists but refs don't match |
+
+### Output Directory Structure
+
+```
+work/migration-analysis-YYYYMMDD-HHMM/
+├── prod/
+│   ├── raw/
+│   │   ├── state-events.json       # Phase 1
+│   │   ├── announcements.json      # Phase 1
+│   │   └── deletions.json          # Phase 1
+│   ├── git-sync-status.tsv         # Phase 2
+│   └── category*.txt               # Phase 2/3
+├── archive/
+│   └── (same structure as prod)
+├── comparison/
+│   ├── complete-in-both.txt        # Phase 3
+│   ├── complete-prod-missing-archive.txt
+│   ├── complete-prod-incomplete-archive.txt
+│   ├── incomplete-in-both.txt
+│   ├── in-archive-not-prod.txt
+│   └── summary.txt
+├── logs/
+│   ├── parse-failures.txt          # Phase 4
+│   └── purgatory-expired.txt       # Phase 4
+└── results/
+    ├── no-action-required.txt      # Phase 5
+    ├── action-required.txt         # Phase 5
+    ├── manual-investigation.txt    # Phase 5
+    └── summary.txt                 # Phase 5
+```
+
+## Why Migration May Require Attention
+
+Different GRASP implementations may handle edge cases differently. ngit-grasp has stricter validation and better observability, which can surface issues that were previously hidden:
+
+| Aspect | Typical Source Relay | ngit-grasp |
+|--------|---------------------|------------|
+| Git data validation | May accept partial data | Requires all git data to reproduce state |
+| PR refs cleanup | May not clear `refs/nostr/<event-id>` | Properly manages PR refs |
+| Parse failures | May silently ignore | Logs structured `[PARSE_FAIL]` entries |
+| Sync timeout | May have no timeout | Purgatory expires after configurable period |
+
+These differences explain why some repositories may need attention during migration - ngit-grasp's stricter validation catches issues that other implementations may have silently accepted.
+
+## Next Steps
+
+After running the analysis:
+
+1. **Review the summary** - Check `results/summary.txt` for the overview
+2. **Address action items** - Work through `results/action-required.txt`
+3. **Investigate edge cases** - Review `results/manual-investigation.txt`
+4. **Re-run analysis** - After fixing issues, re-run to verify
+5. **Plan cutover** - Schedule the switch when all issues are resolved
+
+### When to Re-run
+
+Re-run the analysis when:
+- Archive sync has had time to complete
+- You've fixed parse failures or re-announced events
+- You want to verify fixes before cutover
+
+```bash
+# Re-run with existing Phase 2 data (faster)
+./run-migration-analysis.sh ... --skip-phase-2 --output work/migration-analysis-20260122-1430
+```
+
+## Individual Scripts
+
+For advanced usage, you can run individual phase scripts:
+
+```bash
+# Phase 1: Fetch events
+./migration-scripts/01-fetch-events.sh wss://source-relay.example.com output/prod
+
+# Phase 2: Git sync check
+./migration-scripts/10-check-git-sync.sh output/prod/raw/state-events.json /var/lib/grasp-relay/git output/prod --categorize
+
+# Phase 3a: Categorize
+./migration-scripts/20-categorize.sh output/prod/git-sync-status.tsv output/prod
+
+# Phase 3b: Compare relays
+./migration-scripts/21-compare-relays.sh output/prod output/archive output/comparison
+
+# Phase 4a: Extract parse failures
+./migration-scripts/30-extract-parse-failures.sh ngit-grasp.service output/logs
+
+# Phase 4b: Extract purgatory expiry
+./migration-scripts/31-extract-purgatory-expiry.sh ngit-grasp.service output/logs
+
+# Phase 5: Final classification
+./migration-scripts/40-classify-actions.sh work/migration-analysis-20260122-1430
+```
+
+Each script has detailed help available with `--help` or by reading the script header.
+
+## relay.ngit.dev Migration Notes
+
+This section documents the specific configuration and lessons learned from migrating relay.ngit.dev from ngit-relay to ngit-grasp. Use this as a reference for similar deployments.
+
+### Deployment Configuration
+
+| Component | Value |
+|-----------|-------|
+| **Production relay** | `wss://relay.ngit.dev` |
+| **Production service** | `ngit-relay.service` |
+| **Production git path** | `/persistent/relay-ngit-dev-ngit-relay/data/repos` |
+| **Archive relay** | `ws://localhost:7443` (localhost only) |
+| **Archive service** | `ngit-grasp-relay-ngit-dev.service` |
+| **Archive git path** | `/persistent/grasp/relay-ngit-dev/git` |
+
+### Key Differences from Defaults
+
+1. **Git paths are non-standard**: The production relay uses `/persistent/relay-ngit-dev-ngit-relay/data/repos` instead of `/var/lib/ngit-relay/git`
+
+2. **Archive is localhost-only**: The archive relay listens on `ws://localhost:7443`, not a public URL. All analysis must run on the VPS.
+
+3. **Service names include instance**: NixOS multi-instance deployment uses `ngit-grasp-relay-ngit-dev.service`, not `ngit-grasp.service`
+
+### Analysis Command
+
+```bash
+# Run on VPS (archive is localhost-only)
+./docs/how-to/migration-scripts/run-migration-analysis.sh \
+  --prod-relay wss://relay.ngit.dev \
+  --archive-relay ws://localhost:7443 \
+  --prod-git /persistent/relay-ngit-dev-ngit-relay/data/repos \
+  --archive-git /persistent/grasp/relay-ngit-dev/git \
+  --service ngit-grasp-relay-ngit-dev.service
+```
+
+### Analysis Results (January 2026)
+
+| Category | Count | Notes |
+|----------|-------|-------|
+| Complete in both | ~400 | Ready for migration |
+| Complete in prod, missing from archive | 315 | Need re-sync |
+| Empty in both | 100 | Users never pushed git data |
+| Manual investigation | 5 | Unusual states |
+| Purgatory expired | 382 | Structured logging working |
+
+### Lessons Learned
+
+1. **Always verify paths first**: The default paths in examples didn't match the actual deployment. Use `systemctl cat <service>` to find real paths.
+
+2. **Check archive accessibility**: We initially tried to run analysis remotely, but the archive relay was localhost-only. Had to SSH to VPS.
+
+3. **Use archive service for Phase 4 (CRITICAL)**: Structured logging (`[PARSE_FAIL]`, `[PURGATORY_EXPIRED]`) is **ONLY** in the ngit-grasp archive service, NOT the ngit-relay production service. Running Phase 4 against `ngit-relay.service` produces zero results because ngit-relay doesn't emit structured logs. The scripts now validate this and error if you specify an ngit-relay service.
+
+4. **Install git on VPS**: Git wasn't installed on the minimal VPS. The scripts now check for this in prerequisites.
+
+5. **Permissions matter**: Some directories required `sudo` to access. Running as root or the service user resolved this.
+
+### Next Steps for relay.ngit.dev
+
+1. **Re-sync 315 repos**: Trigger archive to re-fetch from production
+2. **Investigate 5 edge cases**: Manual review of unusual states
+3. **Monitor purgatory**: 382 expired entries indicate sync issues to investigate
+4. **Plan cutover**: Once re-sync complete, switch DNS/proxy to ngit-grasp
+
+## ngit-relay Troubleshooting
+
+This section covers common issues encountered when running ngit-relay in production, including git permission errors and repository corruption. These issues were discovered during the relay.ngit.dev migration and may affect other deployments.
+
+### Git Permission Denied Errors
+
+#### Symptoms
+
+When cloning repositories, you see:
+
+```bash
+$ git clone https://relay.ngit.dev/npub.../repo.git
+Cloning into 'repo'...
+remote: warning: unable to access '/root/.config/git/attributes': Permission denied
+```
+
+Or in container logs:
+
+```
+warning: unable to access '/root/.config/git/attributes': Permission denied
+```
+
+#### Explanation
+
+This occurs when:
+1. Git operations run as a non-root user (typically `nginx` user, UID 101)
+2. Git tries to access `/root/.config/git/attributes` for global git configuration
+3. The `/root` directory has permissions `0700` (drwx------), preventing non-root users from traversing into it
+4. Even though the `attributes` file itself may be world-readable, the nginx user cannot reach it due to parent directory permissions
+
+**Root cause:** The container runs git commands via fcgiwrap as the nginx user, but `/root` is only accessible by root.
+
+#### Quick Fix (Temporary - Does Not Survive Container Restart)
+
+This fix resolves the issue immediately but will be lost when containers restart:
+
+```bash
+# For each ngit-relay container, exec in and create the git config directory
+sudo podman exec <container-name> sh -c "mkdir -p /root/.config/git && touch /root/.config/git/attributes && chmod 644 /root/.config/git/attributes"
+
+# Example for specific containers:
+sudo podman exec gitnostr-com-ngit-relay sh -c "mkdir -p /root/.config/git && touch /root/.config/git/attributes && chmod 644 /root/.config/git/attributes"
+
+sudo podman exec relay-ngit-dev-ngit-relay sh -c "mkdir -p /root/.config/git && touch /root/.config/git/attributes && chmod 644 /root/.config/git/attributes"
+```
+
+**Important:** This fix is temporary and will be lost when the container restarts. For a permanent solution, see the NixOS configuration below.
+
+#### Permanent Fix (NixOS Configuration)
+
+For NixOS deployments, add systemd services that automatically fix `/root` permissions after each container start:
+
+```nix
+# In your ngit-relay service configuration (e.g., services/relay-ngit-dev-ngit-relay.nix)
+
+systemd.services.relay-ngit-dev-fix-root-perms = {
+  description = "Fix /root permissions in relay.ngit.dev container for git access";
+  after = [ "podman-relay-ngit-dev-ngit-relay.service" ];
+  requires = [ "podman-relay-ngit-dev-ngit-relay.service" ];
+  wantedBy = [ "multi-user.target" ];
+  serviceConfig = {
+    Type = "oneshot";
+    RemainAfterExit = true;
+    ExecStart = "${pkgs.bash}/bin/bash -c 'sleep 5 && ${pkgs.podman}/bin/podman exec relay-ngit-dev-ngit-relay chmod 711 /root'";
+    Restart = "on-failure";
+    RestartSec = "10s";
+  };
+};
+```
+
+This changes `/root` permissions from `0700` to `0711`, allowing the nginx user to traverse through `/root` to reach `/root/.config/git/`.
+
+**Why 711?**
+- `7` (owner/root): Full read/write/execute
+- `1` (group): Execute only (traverse)
+- `1` (other): Execute only (traverse)
+
+This allows non-root users to traverse through `/root` to access subdirectories, while still protecting `/root` contents from being listed or read.
+
+#### Verification
+
+After applying the fix:
+
+```bash
+# Test that cloning works without permission warnings
+git clone https://relay.ngit.dev/npub.../repo.git
+
+# Should clone successfully with no "Permission denied" warnings
+
+# Verify /root permissions inside container
+sudo podman exec relay-ngit-dev-ngit-relay ls -ld /root
+# Should show: drwx--x--x (711)
+
+# Verify nginx user can access git config
+sudo podman exec relay-ngit-dev-ngit-relay su -s /bin/sh nginx -c "cat /root/.config/git/attributes"
+# Should succeed without "Permission denied"
+```
+
+### Git Repository Corruption
+
+#### Symptoms
+
+When cloning repositories, you see:
+
+```bash
+$ git clone https://relay.ngit.dev/npub.../repo.git
+Cloning into 'repo'...
+remote: fatal: bad tree object 8b765235809eb27159657eb4c97fb37d21c29bf0
+remote: aborting due to possible repository corruption on the remote side.
+fatal: early EOF
+fatal: fetch-pack: invalid index-pack output
+```
+
+Or when running `git fsck` on the server:
+
+```
+broken link from    tree 7d60270e1904c30ae6cef7b465ef842a9f9f63c3
+              to    tree 8b765235809eb27159657eb4c97fb37d21c29bf0
+missing tree 8b765235809eb27159657eb4c97fb37d21c29bf0
+```
+
+#### Explanation
+
+Repository corruption typically occurs due to:
+
+1. **Incomplete push operations**: A git push was interrupted mid-transfer, creating a commit that references objects that were never written to disk
+2. **Permission issues during push**: The git-receive-pack process couldn't write objects due to permission problems (e.g., files owned by wrong user)
+3. **Disk/filesystem issues**: Rare cases of disk errors or filesystem corruption
+
+**Common pattern:** A commit exists with references to tree objects, but those tree objects are missing from the repository. Sometimes individual blobs (files) exist as "dangling" objects but were never properly linked into the tree structure.
+
+**Warning signs:**
+- HEAD file or objects owned by root when they should be owned by the service user (UID 101)
+- Dangling blobs in `git fsck` output
+- Recent permission denied errors in logs
+
+#### How to Fix
+
+**Step 1: Locate the corrupted repository**
+
+```bash
+# SSH to the server
+ssh dc@ngit.dev
+
+# Find the repository path
+# For relay.ngit.dev: /persistent/relay-ngit-dev-ngit-relay/data/repos/npub.../repo.git
+# For gitnostr.com: /persistent/gitnostr-com-ngit-relay/data/repos/npub.../repo.git
+
+cd /persistent/relay-ngit-dev-ngit-relay/data/repos/npub1c03rad0r6q833vh57kyd3ndu2jry30nkr0wepqfpsm05vq7he25slryrnw/axepool.git
+```
+
+**Step 2: Diagnose the corruption**
+
+```bash
+# Run git fsck to identify missing/corrupted objects
+git fsck --full
+
+# Example output:
+# broken link from    tree 7d60270e1904c30ae6cef7b465ef842a9f9f63c3
+#               to    tree 8b765235809eb27159657eb4c97fb37d21c29bf0
+# missing tree 8b765235809eb27159657eb4c97fb37d21c29bf0
+# dangling blob 94490b902c9bceb6f901cd0c7c25b685e3685d87
+
+# Check which commit references the missing object
+git log --all --oneline | head -10
+
+# Inspect the broken commit
+git cat-file -p <commit-hash>
+# This will show which tree is missing
+```
+
+**Step 3: Attempt automatic repair**
+
+Try these in order:
+
+```bash
+# Option A: Repack and garbage collect
+git gc --aggressive --prune=now
+
+# Then check if corruption is fixed
+git fsck --full
+
+# Option B: If that doesn't work, try recovering from pack files
+git unpack-objects < .git/objects/pack/*.pack
+git fsck --full
+```
+
+**Step 4: Manual reconstruction (if automatic repair fails)**
+
+If the missing tree object can be reconstructed from dangling blobs:
+
+```bash
+# 1. Identify what should be in the missing tree
+# Look at the commit message and nearby commits to understand the structure
+
+# 2. Find dangling blobs that might belong to the tree
+git fsck --full | grep "dangling blob"
+
+# 3. Examine each dangling blob to identify files
+git cat-file -p 94490b902c9bceb6f901cd0c7c25b685e3685d87
+
+# 4. Reconstruct the tree manually
+# This requires creating a new tree object with the correct structure
+# Example (advanced):
+git mktree <<EOF
+100644 blob <blob-hash> filename1.rs
+100644 blob <blob-hash> filename2.rs
+EOF
+# This outputs a new tree hash
+
+# 5. Create a new commit with the fixed tree
+git commit-tree <new-tree-hash> -p <parent-commit> -m "Reconstructed commit message"
+# This outputs a new commit hash
+
+# 6. Update the branch reference
+git update-ref refs/heads/<branch-name> <new-commit-hash>
+
+# 7. Clean up
+git gc --prune=now
+```
+
+**Step 5: Verify the fix**
+
+```bash
+# Run fsck again - should show no errors
+git fsck --full
+
+# Test clone locally
+git clone /path/to/repo.git /tmp/test-clone
+
+# Test clone via HTTP
+git clone https://relay.ngit.dev/npub.../repo.git /tmp/test-clone-http
+```
+
+**Step 6: Fix ownership and permissions**
+
+Ensure all repository files are owned by the correct user:
+
+```bash
+# For ngit-relay containers, files should be owned by UID 101 (nginx user)
+sudo chown -R 101:101 /persistent/relay-ngit-dev-ngit-relay/data/repos/npub.../repo.git
+
+# Verify
+ls -la /persistent/relay-ngit-dev-ngit-relay/data/repos/npub.../repo.git
+```
+
+**Step 7: Replicate fix to other instances (if applicable)**
+
+If you have multiple relay instances (e.g., gitnostr.com and relay.ngit.dev), replicate the fix:
+
+```bash
+# Copy the repaired pack files
+sudo cp /persistent/relay-ngit-dev-ngit-relay/data/repos/npub.../repo.git/objects/pack/* \
+        /persistent/gitnostr-com-ngit-relay/data/repos/npub.../repo.git/objects/pack/
+
+# Update the branch reference
+cd /persistent/gitnostr-com-ngit-relay/data/repos/npub.../repo.git
+git update-ref refs/heads/<branch-name> <new-commit-hash>
+
+# Fix ownership
+sudo chown -R 101:101 /persistent/gitnostr-com-ngit-relay/data/repos/npub.../repo.git
+
+# Clean up
+git gc --prune=now
+```
+
+#### Prevention
+
+To prevent future corruption:
+
+1. **Fix permission issues first**: Ensure the permission denied errors are resolved (see previous section)
+2. **Monitor for root-owned files**: Files in git repositories should be owned by UID 101, not root
+3. **Check disk health**: Run `df -h` and `smartctl` to ensure disk is healthy
+4. **Enable git fsck in monitoring**: Periodically run `git fsck` on repositories to catch corruption early
+
+```bash
+# Add to monitoring/cron (example)
+find /persistent/*/data/repos -name "*.git" -type d | while read repo; do
+  echo "Checking $repo"
+  git -C "$repo" fsck --full 2>&1 | grep -v "^Checking\|^dangling"
+done
+```
+
+#### Real-World Example: axepool.git Corruption
+
+During the relay.ngit.dev migration, the `axepool.git` repository was corrupted:
+
+**Problem:**
+- Commit `e84518b` referenced tree `8b765235...` (the `src` directory)
+- Tree `8b765235...` was missing from the repository
+- Blob `94490b90...` (mint_client.rs) existed as a dangling object but wasn't linked
+
+**Root cause:**
+- An incomplete push operation
+- Permission issues (HEAD file was owned by root)
+- The commit was created but the tree object was never written
+
+**Solution:**
+1. Identified the missing tree should contain: `lib.rs`, `main.rs`, `mint_client.rs`
+2. Found the dangling blob `94490b90...` was `mint_client.rs`
+3. Reconstructed the `src` tree with all three files
+4. Created new commit `e12bc3cf...` with the fixed tree
+5. Updated `refs/heads/add-missing-hooks` to point to the new commit
+6. Ran `git gc --prune=now` to clean up
+7. Replicated fix to gitnostr.com instance
+
+**Result:** Both relays now clone successfully with all files intact.
+
+### Additional Resources
+
+- **ngit-relay repository**: https://github.com/danconwaydev/ngit-relay
+- **Git internals documentation**: https://git-scm.com/book/en/v2/Git-Internals-Plumbing-and-Porcelain
+- **Podman documentation**: https://docs.podman.io/
diff --git a/docs/how-to/production-sync-testing.md b/docs/archive/2026-01-relay-ngit-dev-migration/production-sync-testing.md
index 3a273a7..3a273a7 100644
--- a/docs/how-to/production-sync-testing.md
+++ b/docs/archive/2026-01-relay-ngit-dev-migration/production-sync-testing.md
diff --git a/docs/archive/2026-01-relay-ngit-dev-migration/scripts/01-fetch-events.sh b/docs/archive/2026-01-relay-ngit-dev-migration/scripts/01-fetch-events.sh
new file mode 100755
index 0000000..e0d6f26
--- /dev/null
+++ b/docs/archive/2026-01-relay-ngit-dev-migration/scripts/01-fetch-events.sh
@@ -0,0 +1,206 @@
+#!/usr/bin/env bash
+#
+# 01-fetch-events.sh - Fetch nostr events from a relay for migration analysis
+#
+# PHASE 1 of the GRASP relay to ngit-grasp migration analysis pipeline.
+# Fetches kind 30618 (state), 30617 (announcement), and 5 (deletion) events.
+#
+# USAGE:
+#   ./01-fetch-events.sh <relay-url> <output-dir>
+#
+# EXAMPLES:
+#   # Fetch from production relay
+#   ./01-fetch-events.sh wss://relay.ngit.dev output/prod
+#
+#   # Fetch from archive relay
+#   ./01-fetch-events.sh wss://archive.relay.ngit.dev output/archive
+#
+#   # Full migration analysis setup
+#   mkdir -p work/migration-analysis-$(date +%Y%m%d-%H%M)
+#   ./01-fetch-events.sh wss://relay.ngit.dev work/migration-analysis-*/prod
+#   ./01-fetch-events.sh wss://archive.relay.ngit.dev work/migration-analysis-*/archive
+#
+# OUTPUT:
+#   <output-dir>/raw/state-events.json      - kind 30618 events (one per line, JSONL)
+#   <output-dir>/raw/announcements.json     - kind 30617 events (one per line, JSONL)
+#   <output-dir>/raw/deletions.json         - kind 5 events (one per line, JSONL)
+#
+# OUTPUT FORMAT:
+#   Each file contains one JSON event per line (JSONL format).
+#   Events are the raw nostr event objects as returned by the relay.
+#
+# PREREQUISITES:
+#   - nak (Nostr Army Knife) - https://github.com/fiatjaf/nak
+#   - jq (for counting/validation)
+#
+# RUNTIME: ~30 seconds per relay (depends on network and event count)
+#
+# NOTES:
+#   - Uses --paginate to ensure all events are fetched (not just first page)
+#   - If event counts are exact multiples of 250, pagination may have failed
+#   - Run Phase 1 and Phase 2 back-to-back for accurate snapshot
+#
+# SEE ALSO:
+#   docs/how-to/migrate-to-ngit-grasp.md - Full migration guide
+#
+
+set -euo pipefail
+
+# Colors for output (disabled if not a terminal)
+if [[ -t 1 ]]; then
+    RED='\033[0;31m'
+    GREEN='\033[0;32m'
+    YELLOW='\033[0;33m'
+    BLUE='\033[0;34m'
+    NC='\033[0m' # No Color
+else
+    RED=''
+    GREEN=''
+    YELLOW=''
+    BLUE=''
+    NC=''
+fi
+
+log_info() {
+    echo -e "${BLUE}[INFO]${NC} $*" >&2
+}
+
+log_success() {
+    echo -e "${GREEN}[OK]${NC} $*" >&2
+}
+
+log_warn() {
+    echo -e "${YELLOW}[WARN]${NC} $*" >&2
+}
+
+log_error() {
+    echo -e "${RED}[ERROR]${NC} $*" >&2
+}
+
+usage() {
+    echo "Usage: $0 <relay-url> <output-dir>"
+    echo ""
+    echo "Arguments:"
+    echo "  relay-url   WebSocket URL of the relay (e.g., wss://relay.ngit.dev)"
+    echo "  output-dir  Directory to store fetched events (e.g., output/prod)"
+    echo ""
+    echo "Examples:"
+    echo "  $0 wss://relay.ngit.dev output/prod"
+    echo "  $0 wss://archive.relay.ngit.dev output/archive"
+    exit 1
+}
+
+# Check prerequisites
+check_prerequisites() {
+    local missing=0
+    
+    if ! command -v nak &> /dev/null; then
+        log_error "nak not found. Install from: https://github.com/fiatjaf/nak"
+        missing=1
+    fi
+    
+    if ! command -v jq &> /dev/null; then
+        log_error "jq not found. Install with your package manager."
+        missing=1
+    fi
+    
+    if [[ $missing -eq 1 ]]; then
+        exit 1
+    fi
+}
+
+# Fetch events of a specific kind
+# Args: $1=relay, $2=kind, $3=output_file, $4=description
+fetch_kind() {
+    local relay="$1"
+    local kind="$2"
+    local output_file="$3"
+    local description="$4"
+    
+    log_info "Fetching $description (kind $kind) from $relay..."
+    
+    local start_time
+    start_time=$(date +%s)
+    
+    # Use --paginate to ensure we get all events, not just first page
+    # nak outputs one event per line (JSONL format)
+    if ! nak req -k "$kind" --paginate "$relay" > "$output_file" 2>/dev/null; then
+        log_error "Failed to fetch $description from $relay"
+        return 1
+    fi
+    
+    local end_time
+    end_time=$(date +%s)
+    local duration=$((end_time - start_time))
+    
+    # Count events
+    local count
+    count=$(wc -l < "$output_file" | tr -d ' ')
+    
+    # Warn if count is suspicious (exact multiple of 250 suggests pagination issue)
+    if [[ $count -gt 0 ]] && [[ $((count % 250)) -eq 0 ]]; then
+        log_warn "$description count ($count) is exact multiple of 250 - pagination may have failed!"
+    fi
+    
+    log_success "Fetched $count $description in ${duration}s -> $output_file"
+    
+    echo "$count"
+}
+
+# Main
+main() {
+    if [[ $# -ne 2 ]]; then
+        usage
+    fi
+    
+    local relay="$1"
+    local output_dir="$2"
+    
+    # Validate relay URL
+    if [[ ! "$relay" =~ ^wss?:// ]]; then
+        log_error "Invalid relay URL: $relay (must start with ws:// or wss://)"
+        exit 1
+    fi
+    
+    check_prerequisites
+    
+    log_info "Starting event fetch from $relay"
+    log_info "Output directory: $output_dir"
+    
+    # Create output directory structure
+    local raw_dir="$output_dir/raw"
+    mkdir -p "$raw_dir"
+    
+    local total_start
+    total_start=$(date +%s)
+    
+    # Fetch each event type
+    local state_count announcement_count deletion_count
+    
+    state_count=$(fetch_kind "$relay" 30618 "$raw_dir/state-events.json" "state events")
+    announcement_count=$(fetch_kind "$relay" 30617 "$raw_dir/announcements.json" "announcements")
+    deletion_count=$(fetch_kind "$relay" 5 "$raw_dir/deletions.json" "deletion requests")
+    
+    local total_end
+    total_end=$(date +%s)
+    local total_duration=$((total_end - total_start))
+    
+    # Summary
+    echo ""
+    log_info "=== Fetch Summary ==="
+    log_info "Relay: $relay"
+    log_info "Output: $output_dir"
+    log_info "State events (30618):    $state_count"
+    log_info "Announcements (30617):   $announcement_count"
+    log_info "Deletions (5):           $deletion_count"
+    log_info "Total time: ${total_duration}s"
+    echo ""
+    
+    # Output file listing for easy copy/paste
+    log_info "Output files:"
+    echo "  $raw_dir/state-events.json"
+    echo "  $raw_dir/announcements.json"
+    echo "  $raw_dir/deletions.json"
+}
+
+main "$@"
diff --git a/docs/archive/2026-01-relay-ngit-dev-migration/scripts/10-check-git-sync.sh b/docs/archive/2026-01-relay-ngit-dev-migration/scripts/10-check-git-sync.sh
new file mode 100755
index 0000000..b4536cb
--- /dev/null
+++ b/docs/archive/2026-01-relay-ngit-dev-migration/scripts/10-check-git-sync.sh
@@ -0,0 +1,564 @@
+#!/usr/bin/env bash
+#
+# 10-check-git-sync.sh - Compare state events to actual git data on disk
+#
+# PHASE 2 of the GRASP relay to ngit-grasp migration analysis pipeline.
+# Compares kind 30618 state events against actual git refs on disk.
+#
+# USAGE:
+#   ./10-check-git-sync.sh <state-events.json> <git-base-dir> <output-dir> [--categorize]
+#
+# EXAMPLES:
+#   # Check source relay against source git data
+#   ./10-check-git-sync.sh output/prod/raw/state-events.json /var/lib/grasp-relay/git output/prod
+#
+#   # Check target relay against target git data
+#   ./10-check-git-sync.sh output/archive/raw/state-events.json /var/lib/ngit-grasp/git output/archive
+#
+#   # Check and categorize in one step (convenience mode)
+#   ./10-check-git-sync.sh output/prod/raw/state-events.json /var/lib/grasp-relay/git output/prod --categorize
+#
+# INPUT:
+#   state-events.json  - JSONL file from Phase 1 (01-fetch-events.sh)
+#                        One kind 30618 event per line
+#   git-base-dir       - Base directory containing git repos
+#                        Structure: <git-base>/<npub>/<repo>.git/
+#
+# OUTPUT:
+#   <output-dir>/git-sync-status.tsv - Tab-separated values:
+#     repo<TAB>npub<TAB>state_refs<TAB>git_refs<TAB>matches<TAB>reason
+#
+#   With --categorize flag, also outputs:
+#     <output-dir>/category1-complete-match.txt
+#     <output-dir>/category2-empty-blank.txt
+#     <output-dir>/category3-partial-match.txt
+#     <output-dir>/category4-no-match.txt
+#
+# CATEGORIES:
+#   1. Complete Match - All refs in state event match git data perfectly
+#   2. Empty/Blank - No git data available (directory missing or empty)
+#   3. Partial Match - Some refs match, some don't
+#   4. No Match - Git data exists but commit hashes don't match
+#
+# PREREQUISITES:
+#   - nak (for npub encoding) - https://github.com/fiatjaf/nak
+#   - jq (for JSON parsing)
+#   - Read access to git directories (may need sudo)
+#
+# RUNTIME: ~20 minutes on VPS (git operations are slow)
+#
+# NOTES:
+#   - Must run on VPS with access to git directories
+#   - Progress indicator updates every 10 events
+#   - Handles packed refs (git show-ref) and loose refs
+#
+# SEE ALSO:
+#   docs/how-to/migrate-to-ngit-grasp.md - Full migration guide
+#   01-fetch-events.sh - Phase 1 script that produces input for this script
+#   20-categorize.sh - Phase 3a script that consumes output from this script
+#
+
+set -euo pipefail
+
+# Colors for output (disabled if not a terminal)
+if [[ -t 1 ]]; then
+    RED='\033[0;31m'
+    GREEN='\033[0;32m'
+    YELLOW='\033[0;33m'
+    BLUE='\033[0;34m'
+    NC='\033[0m'
+else
+    RED=''
+    GREEN=''
+    YELLOW=''
+    BLUE=''
+    NC=''
+fi
+
+log_info() {
+    echo -e "${BLUE}[INFO]${NC} $*" >&2
+}
+
+log_success() {
+    echo -e "${GREEN}[OK]${NC} $*" >&2
+}
+
+log_warn() {
+    echo -e "${YELLOW}[WARN]${NC} $*" >&2
+}
+
+log_error() {
+    echo -e "${RED}[ERROR]${NC} $*" >&2
+}
+
+log_progress() {
+    # Overwrite current line for progress updates
+    echo -ne "\r${BLUE}[PROGRESS]${NC} $*" >&2
+}
+
+usage() {
+    echo "Usage: $0 <state-events.json> <git-base-dir> <output-dir> [--categorize]"
+    echo ""
+    echo "Arguments:"
+    echo "  state-events.json  JSONL file from Phase 1 (kind 30618 events)"
+    echo "  git-base-dir       Base directory for git repos (e.g., /var/lib/grasp-relay/git)"
+    echo "  output-dir         Directory to store output files"
+    echo "  --categorize       Optional: also output category files (like Phase 3)"
+    echo ""
+    echo "Examples:"
+    echo "  $0 output/prod/raw/state-events.json /var/lib/grasp-relay/git output/prod"
+    echo "  $0 output/archive/raw/state-events.json /var/lib/ngit-grasp/git output/archive"
+    echo ""
+    echo "Output:"
+    echo "  git-sync-status.tsv - TSV with: repo, npub, state_refs, git_refs, matches, reason"
+    exit 1
+}
+
+# Check prerequisites
+check_prerequisites() {
+    local missing=0
+    
+    if ! command -v git &> /dev/null; then
+        log_error "git not found. Install with your package manager."
+        missing=1
+    fi
+    
+    if ! command -v nak &> /dev/null; then
+        log_error "nak not found. Install from: https://github.com/fiatjaf/nak"
+        log_error "Or run: nix-shell -p nak jq --run \"$0 $*\""
+        missing=1
+    fi
+    
+    if ! command -v jq &> /dev/null; then
+        log_error "jq not found. Install with your package manager."
+        missing=1
+    fi
+    
+    if [[ $missing -eq 1 ]]; then
+        exit 1
+    fi
+}
+
+# Convert hex pubkey to npub
+# Args: $1=hex_pubkey
+# Returns: npub string or empty on error
+hex_to_npub() {
+    local hex="$1"
+    nak encode npub "$hex" 2>/dev/null || echo ""
+}
+
+# Count refs in state event (only refs/heads/)
+# Args: $1=event_json
+# Returns: count
+count_state_refs() {
+    local event="$1"
+    echo "$event" | jq '[.tags[] | select(.[0] | startswith("refs/heads/"))] | length' 2>/dev/null || echo "0"
+}
+
+# Get git refs from disk
+# Args: $1=git_dir
+# Returns: count of refs/heads/ refs
+count_git_refs() {
+    local git_dir="$1"
+    
+    if [[ ! -d "$git_dir" ]]; then
+        echo "0"
+        return
+    fi
+    
+    # Try git show-ref first (handles packed refs correctly)
+    # Note: We capture output separately to avoid pipefail issues
+    local count
+    if count=$(git --git-dir="$git_dir" show-ref --heads 2>/dev/null | wc -l); then
+        echo "$count" | tr -d ' '
+        return
+    fi
+    
+    # Fallback: count loose refs (when git is not available or fails)
+    if [[ -d "$git_dir/refs/heads" ]]; then
+        find "$git_dir/refs/heads" -type f 2>/dev/null | wc -l | tr -d ' '
+    else
+        echo "0"
+    fi
+}
+
+# Get ref hash from git directory
+# Args: $1=git_dir, $2=ref_path (e.g., refs/heads/main)
+# Returns: commit hash or empty
+get_git_ref_hash() {
+    local git_dir="$1"
+    local ref_path="$2"
+    
+    # Try git show-ref first (handles packed refs)
+    local hash
+    hash=$(git --git-dir="$git_dir" show-ref --hash "$ref_path" 2>/dev/null | head -1 || echo "")
+    
+    if [[ -n "$hash" ]]; then
+        echo "$hash"
+        return
+    fi
+    
+    # Fallback: read loose ref file
+    local ref_file="$git_dir/$ref_path"
+    if [[ -f "$ref_file" ]]; then
+        cat "$ref_file" 2>/dev/null | tr -d '\n' || echo ""
+    else
+        echo ""
+    fi
+}
+
+# Compare state event refs to git refs
+# Args: $1=event_json, $2=git_dir
+# Returns: count of matching refs
+count_matching_refs() {
+    local event="$1"
+    local git_dir="$2"
+    local matching=0
+    
+    # Extract refs/heads/ tags and compare
+    while IFS= read -r ref_tag; do
+        [[ -z "$ref_tag" ]] && continue
+        
+        local ref_path expected_hash
+        ref_path=$(echo "$ref_tag" | jq -r '.[0]' 2>/dev/null || echo "")
+        expected_hash=$(echo "$ref_tag" | jq -r '.[1]' 2>/dev/null || echo "")
+        
+        # Skip if not a heads ref or hash is missing
+        [[ ! "$ref_path" =~ ^refs/heads/ ]] && continue
+        [[ -z "$expected_hash" || "$expected_hash" == "null" ]] && continue
+        
+        # Get actual hash from git
+        local actual_hash
+        actual_hash=$(get_git_ref_hash "$git_dir" "$ref_path")
+        
+        if [[ "$expected_hash" == "$actual_hash" ]]; then
+            matching=$((matching + 1))
+        fi
+    done < <(echo "$event" | jq -c '.tags[] | select(.[0] | startswith("refs/heads/"))' 2>/dev/null)
+    
+    echo "$matching"
+}
+
+# Categorize a single entry
+# Args: $1=state_refs, $2=git_refs, $3=matches, $4=reason
+# Returns: category number (1-4)
+categorize_entry() {
+    local state_refs="$1"
+    local git_refs="$2"
+    local matches="$3"
+    local reason="$4"
+    
+    # Category 2: Empty/Blank
+    if [[ -n "$reason" ]] || [[ "$git_refs" -eq 0 ]]; then
+        echo "2"
+        return
+    fi
+    
+    # Category 1: Complete Match
+    if [[ "$state_refs" -gt 0 ]] && [[ "$state_refs" -eq "$git_refs" ]] && [[ "$matches" -eq "$state_refs" ]]; then
+        echo "1"
+        return
+    fi
+    
+    # Category 4: No Match
+    if [[ "$git_refs" -gt 0 ]] && [[ "$matches" -eq 0 ]]; then
+        echo "4"
+        return
+    fi
+    
+    # Category 3: Partial Match (default for anything else with matches > 0)
+    if [[ "$matches" -gt 0 ]]; then
+        echo "3"
+        return
+    fi
+    
+    # Fallback to category 2
+    echo "2"
+}
+
+# Format entry for category file
+# Args: $1=repo, $2=npub, $3=state_refs, $4=git_refs, $5=matches, $6=reason
+format_category_line() {
+    local repo="$1"
+    local npub="$2"
+    local state_refs="$3"
+    local git_refs="$4"
+    local matches="$5"
+    local reason="$6"
+    
+    if [[ -n "$reason" ]]; then
+        echo "$repo | $npub | state_refs=$state_refs | git_refs=$git_refs | matches=$matches | reason=$reason"
+    else
+        echo "$repo | $npub | state_refs=$state_refs | git_refs=$git_refs | matches=$matches"
+    fi
+}
+
+# Process a single state event
+# Args: $1=event_json, $2=git_base
+# Outputs: TSV line to stdout
+process_event() {
+    local event="$1"
+    local git_base="$2"
+    
+    # Extract repository identifier (d tag)
+    local identifier
+    identifier=$(echo "$event" | jq -r '.tags[] | select(.[0] == "d") | .[1]' 2>/dev/null | head -1 || echo "")
+    
+    if [[ -z "$identifier" ]]; then
+        return 1
+    fi
+    
+    # Extract maintainer pubkey (hex)
+    local hex_pubkey
+    hex_pubkey=$(echo "$event" | jq -r '.pubkey' 2>/dev/null || echo "")
+    
+    if [[ -z "$hex_pubkey" ]]; then
+        return 1
+    fi
+    
+    # Convert to npub
+    local npub
+    npub=$(hex_to_npub "$hex_pubkey")
+    
+    if [[ -z "$npub" ]]; then
+        return 1
+    fi
+    
+    # Count state refs
+    local state_refs
+    state_refs=$(count_state_refs "$event")
+    
+    # Find git directory
+    local git_dir="$git_base/${npub}/${identifier}.git"
+    
+    # Check git directory status
+    local git_refs=0
+    local matches=0
+    local reason=""
+    
+    if [[ ! -d "$git_dir" ]]; then
+        reason="no_git_dir"
+    elif [[ ! -d "$git_dir/refs/heads" ]] && [[ ! -f "$git_dir/packed-refs" ]]; then
+        reason="empty_refs"
+    else
+        git_refs=$(count_git_refs "$git_dir")
+        
+        if [[ "$git_refs" -eq 0 ]]; then
+            reason="empty_refs"
+        elif [[ "$state_refs" -eq 0 ]]; then
+            reason="no_state_refs"
+        else
+            matches=$(count_matching_refs "$event" "$git_dir")
+        fi
+    fi
+    
+    # Output TSV line: repo, npub, state_refs, git_refs, matches, reason
+    printf '%s\t%s\t%s\t%s\t%s\t%s\n' "$identifier" "$npub" "$state_refs" "$git_refs" "$matches" "$reason"
+}
+
+# Main
+main() {
+    local do_categorize=0
+    local args=()
+    
+    # Parse arguments
+    for arg in "$@"; do
+        if [[ "$arg" == "--categorize" ]]; then
+            do_categorize=1
+        else
+            args+=("$arg")
+        fi
+    done
+    
+    if [[ ${#args[@]} -ne 3 ]]; then
+        usage
+    fi
+    
+    local state_events_file="${args[0]}"
+    local git_base="${args[1]}"
+    local output_dir="${args[2]}"
+    
+    # Validate inputs
+    if [[ ! -f "$state_events_file" ]]; then
+        log_error "State events file not found: $state_events_file"
+        exit 1
+    fi
+    
+    if [[ ! -d "$git_base" ]]; then
+        log_error "Git base directory not found: $git_base"
+        log_error "This script must run on the VPS with access to git directories."
+        exit 1
+    fi
+    
+    # Check read permissions
+    if ! ls "$git_base" >/dev/null 2>&1; then
+        log_error "Cannot read git base directory (permission denied): $git_base"
+        log_error "Try running with sudo or grant read permissions."
+        exit 1
+    fi
+    
+    check_prerequisites
+    
+    log_info "=== Git State Synchronization Check ==="
+    log_info "State events: $state_events_file"
+    log_info "Git base: $git_base"
+    log_info "Output: $output_dir"
+    if [[ $do_categorize -eq 1 ]]; then
+        log_info "Mode: TSV + categorization"
+    else
+        log_info "Mode: TSV only (use 20-categorize.sh for categories)"
+    fi
+    log_info "Started: $(date)"
+    echo ""
+    
+    # Create output directory
+    mkdir -p "$output_dir"
+    
+    # Output files
+    local tsv_file="$output_dir/git-sync-status.tsv"
+    
+    # Initialize TSV with header
+    echo -e "repo\tnpub\tstate_refs\tgit_refs\tmatches\treason" > "$tsv_file"
+    
+    # Initialize category files if categorizing
+    local cat1="" cat2="" cat3="" cat4=""
+    if [[ $do_categorize -eq 1 ]]; then
+        cat1="$output_dir/category1-complete-match.txt"
+        cat2="$output_dir/category2-empty-blank.txt"
+        cat3="$output_dir/category3-partial-match.txt"
+        cat4="$output_dir/category4-no-match.txt"
+        > "$cat1"
+        > "$cat2"
+        > "$cat3"
+        > "$cat4"
+    fi
+    
+    # Count total events
+    local total_events
+    total_events=$(wc -l < "$state_events_file" | tr -d ' ')
+    log_info "Processing $total_events state events..."
+    echo ""
+    
+    # Process each event
+    local count=0
+    local processed=0
+    local skipped=0
+    local count_cat1=0 count_cat2=0 count_cat3=0 count_cat4=0
+    local start_time
+    start_time=$(date +%s)
+    
+    while IFS= read -r event; do
+        count=$((count + 1))
+        
+        # Skip empty lines
+        [[ -z "$event" ]] && continue
+        
+        # Process event
+        local result
+        if result=$(process_event "$event" "$git_base"); then
+            processed=$((processed + 1))
+            
+            # Write to TSV (skip header line)
+            echo "$result" >> "$tsv_file"
+            
+            # Categorize if requested
+            if [[ $do_categorize -eq 1 ]]; then
+                # Parse result
+                IFS=$'\t' read -r repo npub state_refs git_refs matches reason <<< "$result"
+                
+                local category
+                category=$(categorize_entry "$state_refs" "$git_refs" "$matches" "$reason")
+                
+                local cat_line
+                cat_line=$(format_category_line "$repo" "$npub" "$state_refs" "$git_refs" "$matches" "$reason")
+                
+                case "$category" in
+                    1) echo "$cat_line" >> "$cat1"; count_cat1=$((count_cat1 + 1)) ;;
+                    2) echo "$cat_line" >> "$cat2"; count_cat2=$((count_cat2 + 1)) ;;
+                    3) echo "$cat_line" >> "$cat3"; count_cat3=$((count_cat3 + 1)) ;;
+                    4) echo "$cat_line" >> "$cat4"; count_cat4=$((count_cat4 + 1)) ;;
+                esac
+            fi
+        else
+            skipped=$((skipped + 1))
+        fi
+        
+        # Progress indicator every 10 events
+        if [[ $((count % 10)) -eq 0 ]]; then
+            local elapsed=$(($(date +%s) - start_time))
+            local rate=0
+            if [[ $elapsed -gt 0 ]]; then
+                rate=$((count / elapsed))
+            fi
+            local eta="?"
+            if [[ $rate -gt 0 ]]; then
+                eta=$(( (total_events - count) / rate ))
+            fi
+            log_progress "Processed $count/$total_events events (~${rate}/s, ETA: ${eta}s)..."
+        fi
+    done < "$state_events_file"
+    
+    # Clear progress line
+    echo "" >&2
+    
+    local end_time
+    end_time=$(date +%s)
+    local duration=$((end_time - start_time))
+    
+    # Summary
+    echo ""
+    log_info "=== Analysis Complete ==="
+    log_info "Finished: $(date)"
+    log_info "Duration: ${duration}s"
+    log_info "Processed: $processed events"
+    if [[ $skipped -gt 0 ]]; then
+        log_warn "Skipped: $skipped events (missing identifier or pubkey)"
+    fi
+    echo ""
+    
+    if [[ $do_categorize -eq 1 ]]; then
+        # Calculate percentages
+        local total=$((count_cat1 + count_cat2 + count_cat3 + count_cat4))
+        local pct1=0 pct2=0 pct3=0 pct4=0
+        if [[ $total -gt 0 ]]; then
+            pct1=$(awk "BEGIN {printf \"%.1f\", ($count_cat1/$total)*100}")
+            pct2=$(awk "BEGIN {printf \"%.1f\", ($count_cat2/$total)*100}")
+            pct3=$(awk "BEGIN {printf \"%.1f\", ($count_cat3/$total)*100}")
+            pct4=$(awk "BEGIN {printf \"%.1f\", ($count_cat4/$total)*100}")
+        fi
+        
+        log_info "=== Category Summary ==="
+        log_success "Category 1 (Complete Match): $count_cat1 ($pct1%)"
+        log_warn "Category 2 (Empty/Blank): $count_cat2 ($pct2%)"
+        log_warn "Category 3 (Partial Match): $count_cat3 ($pct3%)"
+        log_error "Category 4 (No Match): $count_cat4 ($pct4%)"
+        echo ""
+        
+        # Validation warning
+        if [[ $count_cat2 -eq $total ]] && [[ $total -gt 0 ]]; then
+            log_error "WARNING: 100% of repos categorized as Empty/Blank"
+            log_error "This usually indicates a permission or path issue."
+            echo ""
+            log_info "Troubleshooting:"
+            echo "  1. Verify git data exists: sudo ls -la $git_base | head -10"
+            echo "  2. Check sample repo: sudo find $git_base -name '*.git' -type d | head -1"
+            echo "  3. Re-run with sudo if not already using it"
+            echo ""
+        fi
+    fi
+    
+    log_info "Output files:"
+    echo "  $tsv_file"
+    if [[ $do_categorize -eq 1 ]]; then
+        echo "  $cat1"
+        echo "  $cat2"
+        echo "  $cat3"
+        echo "  $cat4"
+    else
+        echo ""
+        log_info "Next step: Run 20-categorize.sh to categorize results"
+        echo "  ./20-categorize.sh $tsv_file $output_dir"
+    fi
+}
+
+main "$@"
diff --git a/docs/archive/2026-01-relay-ngit-dev-migration/scripts/20-categorize.sh b/docs/archive/2026-01-relay-ngit-dev-migration/scripts/20-categorize.sh
new file mode 100755
index 0000000..b38dc00
--- /dev/null
+++ b/docs/archive/2026-01-relay-ngit-dev-migration/scripts/20-categorize.sh
@@ -0,0 +1,212 @@
+#!/usr/bin/env bash
+#
+# 20-categorize.sh - Categorize git sync status into 4 categories
+#
+# PHASE 3a of the GRASP relay to ngit-grasp migration analysis pipeline.
+# Takes git-sync-status.tsv from Phase 2 and categorizes into 4 files.
+#
+# USAGE:
+#   ./20-categorize.sh <git-sync-status.tsv> <output-dir>
+#
+# EXAMPLES:
+#   ./20-categorize.sh output/prod/git-sync-status.tsv output/prod
+#   ./20-categorize.sh output/archive/git-sync-status.tsv output/archive
+#
+# INPUT FORMAT (git-sync-status.tsv):
+#   Tab-separated values with columns:
+#   repo<TAB>npub<TAB>state_refs<TAB>git_refs<TAB>matches<TAB>reason
+#
+#   Where reason is optional and can be: no_git_dir, empty_refs, no_state_refs
+#
+# OUTPUT:
+#   <output-dir>/category1-complete-match.txt  - All refs match perfectly
+#   <output-dir>/category2-empty-blank.txt     - No git data available
+#   <output-dir>/category3-partial-match.txt   - Some refs match
+#   <output-dir>/category4-no-match.txt        - Git exists but refs don't match
+#
+# OUTPUT FORMAT:
+#   repo | npub | state_refs=N | git_refs=N | matches=N [| reason=X]
+#
+# CATEGORIES:
+#   1. Complete Match: state_refs == git_refs == matches (all > 0)
+#   2. Empty/Blank: git_refs == 0 OR reason in (no_git_dir, empty_refs, no_state_refs)
+#   3. Partial Match: matches > 0 AND matches < state_refs
+#   4. No Match: git_refs > 0 AND matches == 0
+#
+# PREREQUISITES:
+#   - awk (standard Unix tool)
+#
+# RUNTIME: < 1 second (local processing only)
+#
+# SEE ALSO:
+#   docs/how-to/migrate-to-ngit-grasp.md - Full migration guide
+#   10-check-git-sync.sh - Phase 2 script that produces input for this script
+#
+
+set -euo pipefail
+
+# Colors for output (disabled if not a terminal)
+if [[ -t 1 ]]; then
+    RED='\033[0;31m'
+    GREEN='\033[0;32m'
+    YELLOW='\033[0;33m'
+    BLUE='\033[0;34m'
+    NC='\033[0m'
+else
+    RED=''
+    GREEN=''
+    YELLOW=''
+    BLUE=''
+    NC=''
+fi
+
+log_info() {
+    echo -e "${BLUE}[INFO]${NC} $*" >&2
+}
+
+log_success() {
+    echo -e "${GREEN}[OK]${NC} $*" >&2
+}
+
+log_warn() {
+    echo -e "${YELLOW}[WARN]${NC} $*" >&2
+}
+
+log_error() {
+    echo -e "${RED}[ERROR]${NC} $*" >&2
+}
+
+usage() {
+    echo "Usage: $0 <git-sync-status.tsv> <output-dir>"
+    echo ""
+    echo "Arguments:"
+    echo "  git-sync-status.tsv  TSV file from Phase 2 (10-check-git-sync.sh)"
+    echo "  output-dir           Directory to store categorized output"
+    echo ""
+    echo "Examples:"
+    echo "  $0 output/prod/git-sync-status.tsv output/prod"
+    echo "  $0 output/archive/git-sync-status.tsv output/archive"
+    echo ""
+    echo "Input format (TSV):"
+    echo "  repo<TAB>npub<TAB>state_refs<TAB>git_refs<TAB>matches<TAB>reason"
+    echo ""
+    echo "Output files:"
+    echo "  category1-complete-match.txt  - All refs match"
+    echo "  category2-empty-blank.txt     - No git data"
+    echo "  category3-partial-match.txt   - Some refs match"
+    echo "  category4-no-match.txt        - Git exists, refs don't match"
+    exit 1
+}
+
+# Main
+main() {
+    if [[ $# -ne 2 ]]; then
+        usage
+    fi
+
+    local input_file="$1"
+    local output_dir="$2"
+
+    # Validate input file
+    if [[ ! -f "$input_file" ]]; then
+        log_error "Input file not found: $input_file"
+        exit 1
+    fi
+
+    log_info "Categorizing git sync status"
+    log_info "Input: $input_file"
+    log_info "Output: $output_dir"
+
+    # Create output directory
+    mkdir -p "$output_dir"
+
+    # Output files
+    local cat1="$output_dir/category1-complete-match.txt"
+    local cat2="$output_dir/category2-empty-blank.txt"
+    local cat3="$output_dir/category3-partial-match.txt"
+    local cat4="$output_dir/category4-no-match.txt"
+
+    # Clear previous results
+    > "$cat1"
+    > "$cat2"
+    > "$cat3"
+    > "$cat4"
+
+    # Process input file with awk
+    # Input: repo<TAB>npub<TAB>state_refs<TAB>git_refs<TAB>matches<TAB>reason
+    awk -F'\t' -v cat1="$cat1" -v cat2="$cat2" -v cat3="$cat3" -v cat4="$cat4" '
+    BEGIN {
+        count1 = 0; count2 = 0; count3 = 0; count4 = 0
+    }
+    NR == 1 && /^repo/ { next }  # Skip header if present
+    NF >= 5 {
+        repo = $1
+        npub = $2
+        state_refs = int($3)
+        git_refs = int($4)
+        matches = int($5)
+        reason = (NF >= 6) ? $6 : ""
+
+        # Format output line
+        if (reason != "") {
+            line = repo " | " npub " | state_refs=" state_refs " | git_refs=" git_refs " | matches=" matches " | reason=" reason
+        } else {
+            line = repo " | " npub " | state_refs=" state_refs " | git_refs=" git_refs " | matches=" matches
+        }
+
+        # Categorize
+        if (reason == "no_git_dir" || reason == "empty_refs" || reason == "no_state_refs" || git_refs == 0) {
+            # Category 2: Empty/Blank
+            print line >> cat2
+            count2++
+        } else if (state_refs > 0 && state_refs == git_refs && matches == state_refs) {
+            # Category 1: Complete Match
+            print line >> cat1
+            count1++
+        } else if (matches > 0 && matches < state_refs) {
+            # Category 3: Partial Match
+            print line >> cat3
+            count3++
+        } else if (git_refs > 0 && matches == 0) {
+            # Category 4: No Match
+            print line >> cat4
+            count4++
+        } else if (matches > 0) {
+            # Edge case: matches > 0 but does not fit other categories
+            # This can happen when git_refs > state_refs but all state refs match
+            # Treat as partial match
+            print line >> cat3
+            count3++
+        } else {
+            # Fallback: treat as category 2 (empty/blank)
+            print line >> cat2
+            count2++
+        }
+    }
+    END {
+        total = count1 + count2 + count3 + count4
+        print "COUNTS:" count1 ":" count2 ":" count3 ":" count4 ":" total
+    }
+    ' "$input_file" 2>&1 | while IFS= read -r line; do
+        if [[ "$line" =~ ^COUNTS: ]]; then
+            # Parse counts from awk output
+            IFS=':' read -r _ c1 c2 c3 c4 total <<< "$line"
+            
+            echo ""
+            log_info "=== Categorization Summary ==="
+            log_info "Total entries: $total"
+            log_success "Category 1 (Complete Match): $c1"
+            log_warn "Category 2 (Empty/Blank): $c2"
+            log_warn "Category 3 (Partial Match): $c3"
+            log_error "Category 4 (No Match): $c4"
+            echo ""
+            log_info "Output files:"
+            echo "  $cat1"
+            echo "  $cat2"
+            echo "  $cat3"
+            echo "  $cat4"
+        fi
+    done
+}
+
+main "$@"
diff --git a/docs/archive/2026-01-relay-ngit-dev-migration/scripts/21-compare-relays.sh b/docs/archive/2026-01-relay-ngit-dev-migration/scripts/21-compare-relays.sh
new file mode 100755
index 0000000..b9c0d30
--- /dev/null
+++ b/docs/archive/2026-01-relay-ngit-dev-migration/scripts/21-compare-relays.sh
@@ -0,0 +1,294 @@
+#!/usr/bin/env bash
+#
+# 21-compare-relays.sh - Compare prod vs archive category files to find gaps
+#
+# PHASE 3b of the GRASP relay to ngit-grasp migration analysis pipeline.
+# Compares categorized output from prod and archive to identify:
+# - Repos complete in prod but missing/incomplete in archive
+# - Repos in archive but not in prod
+# - Status differences between relays
+#
+# USAGE:
+#   ./21-compare-relays.sh <prod-dir> <archive-dir> <output-dir>
+#
+# EXAMPLES:
+#   ./21-compare-relays.sh output/prod output/archive output/comparison
+#
+# INPUT:
+#   Both prod-dir and archive-dir must contain:
+#   - category1-complete-match.txt
+#   - category2-empty-blank.txt
+#   - category3-partial-match.txt
+#   - category4-no-match.txt
+#
+# OUTPUT:
+#   <output-dir>/complete-in-both.txt           - Repos complete in both relays (no action)
+#   <output-dir>/complete-prod-missing-archive.txt - Complete in prod, not in archive cat1
+#   <output-dir>/complete-prod-incomplete-archive.txt - Complete in prod, incomplete in archive
+#   <output-dir>/incomplete-in-both.txt         - Incomplete in both relays
+#   <output-dir>/in-archive-not-prod.txt        - In archive but not in prod
+#   <output-dir>/summary.txt                    - Human-readable summary
+#
+# OUTPUT FORMAT:
+#   Each file contains lines in the format:
+#   repo | npub | prod_status | archive_status
+#
+# PREREQUISITES:
+#   - awk, sort, comm (standard Unix tools)
+#
+# RUNTIME: < 1 second (local processing only)
+#
+# SEE ALSO:
+#   docs/how-to/migrate-to-ngit-grasp.md - Full migration guide
+#   20-categorize.sh - Phase 3a script that produces input for this script
+#
+
+set -euo pipefail
+
+# Colors for output (disabled if not a terminal)
+if [[ -t 1 ]]; then
+    RED='\033[0;31m'
+    GREEN='\033[0;32m'
+    YELLOW='\033[0;33m'
+    BLUE='\033[0;34m'
+    NC='\033[0m'
+else
+    RED=''
+    GREEN=''
+    YELLOW=''
+    BLUE=''
+    NC=''
+fi
+
+log_info() {
+    echo -e "${BLUE}[INFO]${NC} $*" >&2
+}
+
+log_success() {
+    echo -e "${GREEN}[OK]${NC} $*" >&2
+}
+
+log_warn() {
+    echo -e "${YELLOW}[WARN]${NC} $*" >&2
+}
+
+log_error() {
+    echo -e "${RED}[ERROR]${NC} $*" >&2
+}
+
+usage() {
+    echo "Usage: $0 <prod-dir> <archive-dir> <output-dir>"
+    echo ""
+    echo "Arguments:"
+    echo "  prod-dir     Directory containing prod category files"
+    echo "  archive-dir  Directory containing archive category files"
+    echo "  output-dir   Directory to store comparison results"
+    echo ""
+    echo "Examples:"
+    echo "  $0 output/prod output/archive output/comparison"
+    echo ""
+    echo "Required input files in each directory:"
+    echo "  category1-complete-match.txt"
+    echo "  category2-empty-blank.txt"
+    echo "  category3-partial-match.txt"
+    echo "  category4-no-match.txt"
+    exit 1
+}
+
+# Extract repo|npub key from category line
+# Input: "repo | npub | state_refs=N | ..."
+# Output: "repo|npub"
+extract_key() {
+    awk -F' \\| ' '{print $1 "|" $2}'
+}
+
+# Build lookup table from category files
+# Args: $1=directory, $2=output_file
+build_lookup() {
+    local dir="$1"
+    local output="$2"
+    
+    # Process all 4 category files
+    for cat in 1 2 3 4; do
+        local file="$dir/category${cat}-*.txt"
+        # shellcheck disable=SC2086
+        if ls $file 1>/dev/null 2>&1; then
+            # shellcheck disable=SC2086
+            cat $file | while IFS= read -r line; do
+                key=$(echo "$line" | extract_key)
+                echo "${key}|cat${cat}|${line}"
+            done
+        fi
+    done | sort -t'|' -k1,2 > "$output"
+}
+
+# Main
+main() {
+    if [[ $# -ne 3 ]]; then
+        usage
+    fi
+
+    local prod_dir="$1"
+    local archive_dir="$2"
+    local output_dir="$3"
+
+    # Validate input directories
+    for dir in "$prod_dir" "$archive_dir"; do
+        if [[ ! -d "$dir" ]]; then
+            log_error "Directory not found: $dir"
+            exit 1
+        fi
+        if [[ ! -f "$dir/category1-complete-match.txt" ]]; then
+            log_error "Missing category1-complete-match.txt in $dir"
+            exit 1
+        fi
+    done
+
+    log_info "Comparing relay categories"
+    log_info "Prod: $prod_dir"
+    log_info "Archive: $archive_dir"
+    log_info "Output: $output_dir"
+
+    # Create output directory
+    mkdir -p "$output_dir"
+
+    # Create temp files for processing
+    local tmp_dir
+    tmp_dir=$(mktemp -d)
+    # shellcheck disable=SC2064
+    trap "rm -rf '$tmp_dir'" EXIT
+
+    log_info "Building lookup tables..."
+
+    # Build lookup tables: key|category|full_line
+    build_lookup "$prod_dir" "$tmp_dir/prod_lookup.txt"
+    build_lookup "$archive_dir" "$tmp_dir/archive_lookup.txt"
+
+    # Extract just keys for comparison
+    cut -d'|' -f1,2 "$tmp_dir/prod_lookup.txt" | sort -u > "$tmp_dir/prod_keys.txt"
+    cut -d'|' -f1,2 "$tmp_dir/archive_lookup.txt" | sort -u > "$tmp_dir/archive_keys.txt"
+
+    log_info "Comparing categories..."
+
+    # Initialize output files
+    > "$output_dir/complete-in-both.txt"
+    > "$output_dir/complete-prod-missing-archive.txt"
+    > "$output_dir/complete-prod-incomplete-archive.txt"
+    > "$output_dir/incomplete-in-both.txt"
+    > "$output_dir/in-archive-not-prod.txt"
+
+    # Process prod category 1 (complete) entries
+    while IFS='|' read -r repo npub cat full_line; do
+        key="${repo}|${npub}"
+        
+        # Look up in archive
+        archive_entry=$(grep "^${key}|" "$tmp_dir/archive_lookup.txt" 2>/dev/null | head -1 || echo "")
+        
+        if [[ -z "$archive_entry" ]]; then
+            # Not in archive at all
+            echo "$repo | $npub | prod=complete | archive=missing" >> "$output_dir/complete-prod-missing-archive.txt"
+        else
+            archive_cat=$(echo "$archive_entry" | cut -d'|' -f3)
+            if [[ "$archive_cat" == "cat1" ]]; then
+                # Complete in both
+                echo "$repo | $npub | prod=complete | archive=complete" >> "$output_dir/complete-in-both.txt"
+            else
+                # Complete in prod, incomplete in archive
+                echo "$repo | $npub | prod=complete | archive=$archive_cat" >> "$output_dir/complete-prod-incomplete-archive.txt"
+            fi
+        fi
+    done < <(grep '|cat1|' "$tmp_dir/prod_lookup.txt" | sed 's/|cat1|/|cat1|/')
+
+    # Process prod categories 2-4 (incomplete) entries
+    for cat in cat2 cat3 cat4; do
+        while IFS='|' read -r repo npub _ full_line; do
+            key="${repo}|${npub}"
+            
+            # Look up in archive
+            archive_entry=$(grep "^${key}|" "$tmp_dir/archive_lookup.txt" 2>/dev/null | head -1 || echo "")
+            
+            if [[ -z "$archive_entry" ]]; then
+                # Incomplete in prod, missing in archive
+                echo "$repo | $npub | prod=$cat | archive=missing" >> "$output_dir/incomplete-in-both.txt"
+            else
+                archive_cat=$(echo "$archive_entry" | cut -d'|' -f3)
+                if [[ "$archive_cat" != "cat1" ]]; then
+                    # Incomplete in both
+                    echo "$repo | $npub | prod=$cat | archive=$archive_cat" >> "$output_dir/incomplete-in-both.txt"
+                fi
+                # If archive is complete but prod is not, that's unusual but not an error
+            fi
+        done < <(grep "|${cat}|" "$tmp_dir/prod_lookup.txt")
+    done
+
+    # Find entries in archive but not in prod
+    comm -23 "$tmp_dir/archive_keys.txt" "$tmp_dir/prod_keys.txt" | while IFS='|' read -r repo npub; do
+        key="${repo}|${npub}"
+        archive_entry=$(grep "^${key}|" "$tmp_dir/archive_lookup.txt" 2>/dev/null | head -1 || echo "")
+        archive_cat=$(echo "$archive_entry" | cut -d'|' -f3)
+        echo "$repo | $npub | prod=missing | archive=$archive_cat" >> "$output_dir/in-archive-not-prod.txt"
+    done
+
+    # Count results
+    local count_both count_missing count_incomplete count_both_incomplete count_archive_only
+    count_both=$(wc -l < "$output_dir/complete-in-both.txt" | tr -d ' ')
+    count_missing=$(wc -l < "$output_dir/complete-prod-missing-archive.txt" | tr -d ' ')
+    count_incomplete=$(wc -l < "$output_dir/complete-prod-incomplete-archive.txt" | tr -d ' ')
+    count_both_incomplete=$(wc -l < "$output_dir/incomplete-in-both.txt" | tr -d ' ')
+    count_archive_only=$(wc -l < "$output_dir/in-archive-not-prod.txt" | tr -d ' ')
+
+    # Generate summary
+    cat > "$output_dir/summary.txt" << EOF
+# Relay Comparison Summary
+Generated: $(date -Iseconds)
+
+## Input
+- Prod: $prod_dir
+- Archive: $archive_dir
+
+## Results
+
+### No Action Required
+- Complete in both relays: $count_both
+
+### Action/Decision Required
+- Complete in prod, MISSING from archive: $count_missing
+- Complete in prod, INCOMPLETE in archive: $count_incomplete
+- Incomplete in BOTH relays: $count_both_incomplete
+
+### For Reference
+- In archive but not in prod: $count_archive_only
+
+## Files
+- complete-in-both.txt: Repos successfully migrated (no action)
+- complete-prod-missing-archive.txt: Need investigation - why not in archive?
+- complete-prod-incomplete-archive.txt: Archive sync may still be in progress
+- incomplete-in-both.txt: Git data incomplete on both relays
+- in-archive-not-prod.txt: May be deleted from prod or new to archive
+
+## Next Steps
+1. Review complete-prod-missing-archive.txt - these repos need attention
+2. Check if archive sync is still running for incomplete entries
+3. Cross-reference with deletion events (kind 5) from Phase 1
+4. Use Phase 4 logs to understand parse failures and purgatory expiry
+EOF
+
+    # Display summary
+    echo ""
+    log_info "=== Comparison Summary ==="
+    log_success "Complete in both: $count_both (no action needed)"
+    log_error "Complete in prod, MISSING from archive: $count_missing"
+    log_warn "Complete in prod, incomplete in archive: $count_incomplete"
+    log_warn "Incomplete in both: $count_both_incomplete"
+    log_info "In archive only: $count_archive_only"
+    echo ""
+    log_info "Output files:"
+    echo "  $output_dir/complete-in-both.txt"
+    echo "  $output_dir/complete-prod-missing-archive.txt"
+    echo "  $output_dir/complete-prod-incomplete-archive.txt"
+    echo "  $output_dir/incomplete-in-both.txt"
+    echo "  $output_dir/in-archive-not-prod.txt"
+    echo "  $output_dir/summary.txt"
+}
+
+main "$@"
diff --git a/docs/archive/2026-01-relay-ngit-dev-migration/scripts/22-compare-git-data.sh b/docs/archive/2026-01-relay-ngit-dev-migration/scripts/22-compare-git-data.sh
new file mode 100755
index 0000000..76521d4
--- /dev/null
+++ b/docs/archive/2026-01-relay-ngit-dev-migration/scripts/22-compare-git-data.sh
@@ -0,0 +1,390 @@
+#!/usr/bin/env bash
+#
+# 22-compare-git-data.sh - Compare actual git data between prod and archive relays
+#
+# PHASE 3c of the GRASP relay to ngit-grasp migration analysis pipeline.
+# Compares actual git commits between prod and archive to determine which is ahead.
+#
+# KEY INSIGHT:
+#   Archive (ngit-grasp) enforces GRASP - git data ALWAYS matches a state event.
+#   If archive has different/newer data than prod, it means:
+#   - A state event authorized those commits at some point
+#   - Archive is actually MORE up-to-date than prod
+#   - Migration should use archive data (it's already correct)
+#
+# USAGE:
+#   ./22-compare-git-data.sh <prod-git-base> <archive-git-base> <repo-list> <output-dir>
+#
+# EXAMPLES:
+#   ./22-compare-git-data.sh /var/lib/grasp-relay/git /var/lib/ngit-grasp/git \
+#       output/comparison/complete-prod-incomplete-archive.txt output/comparison
+#
+# INPUT:
+#   prod-git-base     Base directory for prod git repos (e.g., /var/lib/grasp-relay/git)
+#   archive-git-base  Base directory for archive git repos (e.g., /var/lib/ngit-grasp/git)
+#   repo-list         File with repos to compare (format: "repo | npub | ...")
+#
+# OUTPUT:
+#   <output-dir>/git-ancestry.tsv - Tab-separated values:
+#     repo<TAB>npub<TAB>relationship<TAB>details
+#
+#   Relationship values:
+#     archive-ahead    - Archive has all prod commits plus more (GOOD - use archive)
+#     in-sync          - Both have identical commits
+#     prod-ahead       - Prod has commits archive is missing (needs re-sync)
+#     diverged         - Both have unique commits (manual review)
+#     archive-only     - Only archive has git data
+#     prod-only        - Only prod has git data
+#     both-empty       - Neither has git data
+#
+# PREREQUISITES:
+#   - git (for ref comparison)
+#   - Read access to both git directories (may need sudo)
+#
+# RUNTIME: Depends on number of repos to compare
+#
+# SEE ALSO:
+#   docs/how-to/migrate-to-ngit-grasp.md - Full migration guide
+#   21-compare-relays.sh - Phase 3b script that identifies repos to compare
+#
+
+set -euo pipefail
+
+# Colors for output (disabled if not a terminal)
+if [[ -t 1 ]]; then
+    RED='\033[0;31m'
+    GREEN='\033[0;32m'
+    YELLOW='\033[0;33m'
+    BLUE='\033[0;34m'
+    NC='\033[0m'
+else
+    RED=''
+    GREEN=''
+    YELLOW=''
+    BLUE=''
+    NC=''
+fi
+
+log_info() {
+    echo -e "${BLUE}[INFO]${NC} $*" >&2
+}
+
+log_success() {
+    echo -e "${GREEN}[OK]${NC} $*" >&2
+}
+
+log_warn() {
+    echo -e "${YELLOW}[WARN]${NC} $*" >&2
+}
+
+log_error() {
+    echo -e "${RED}[ERROR]${NC} $*" >&2
+}
+
+log_progress() {
+    echo -ne "\r${BLUE}[PROGRESS]${NC} $*" >&2
+}
+
+usage() {
+    echo "Usage: $0 <prod-git-base> <archive-git-base> <repo-list> <output-dir>"
+    echo ""
+    echo "Arguments:"
+    echo "  prod-git-base     Base directory for prod git repos"
+    echo "  archive-git-base  Base directory for archive git repos"
+    echo "  repo-list         File with repos to compare (format: 'repo | npub | ...')"
+    echo "  output-dir        Directory to store output files"
+    echo ""
+    echo "Examples:"
+    echo "  $0 /var/lib/grasp-relay/git /var/lib/ngit-grasp/git \\"
+    echo "      output/comparison/complete-prod-incomplete-archive.txt output/comparison"
+    echo ""
+    echo "Output:"
+    echo "  git-ancestry.tsv - TSV with: repo, npub, relationship, details"
+    exit 1
+}
+
+# Get all branch refs from a git directory
+# Args: $1=git_dir
+# Returns: sorted list of "ref_name commit_hash" lines
+get_git_refs() {
+    local git_dir="$1"
+    
+    if [[ ! -d "$git_dir" ]]; then
+        return
+    fi
+    
+    git --git-dir="$git_dir" show-ref --heads 2>/dev/null | sort || true
+}
+
+# Check if commit A is ancestor of commit B
+# Args: $1=git_dir, $2=commit_a, $3=commit_b
+# Returns: 0 if A is ancestor of B, 1 otherwise
+is_ancestor() {
+    local git_dir="$1"
+    local commit_a="$2"
+    local commit_b="$3"
+    
+    git --git-dir="$git_dir" merge-base --is-ancestor "$commit_a" "$commit_b" 2>/dev/null
+}
+
+# Compare git data between prod and archive for a single repo
+# Args: $1=prod_git_dir, $2=archive_git_dir
+# Returns: relationship string
+compare_repo_git() {
+    local prod_git="$1"
+    local archive_git="$2"
+    
+    local prod_exists=false
+    local archive_exists=false
+    
+    [[ -d "$prod_git" ]] && prod_exists=true
+    [[ -d "$archive_git" ]] && archive_exists=true
+    
+    # Handle cases where one or both don't exist
+    if [[ "$prod_exists" == "false" && "$archive_exists" == "false" ]]; then
+        echo "both-empty"
+        return
+    fi
+    
+    if [[ "$prod_exists" == "false" ]]; then
+        echo "archive-only"
+        return
+    fi
+    
+    if [[ "$archive_exists" == "false" ]]; then
+        echo "prod-only"
+        return
+    fi
+    
+    # Both exist - get refs
+    local prod_refs archive_refs
+    prod_refs=$(get_git_refs "$prod_git")
+    archive_refs=$(get_git_refs "$archive_git")
+    
+    # Handle empty refs
+    if [[ -z "$prod_refs" && -z "$archive_refs" ]]; then
+        echo "both-empty"
+        return
+    fi
+    
+    if [[ -z "$prod_refs" ]]; then
+        echo "archive-only"
+        return
+    fi
+    
+    if [[ -z "$archive_refs" ]]; then
+        echo "prod-only"
+        return
+    fi
+    
+    # Compare refs - check if they're identical
+    if [[ "$prod_refs" == "$archive_refs" ]]; then
+        echo "in-sync"
+        return
+    fi
+    
+    # Refs differ - need to check ancestry
+    # Strategy: For each branch, check if one is ancestor of the other
+    # If all archive branches are ahead of or equal to prod branches, archive is ahead
+    # If all prod branches are ahead of or equal to archive branches, prod is ahead
+    # Otherwise, they've diverged
+    
+    local archive_ahead=true
+    local prod_ahead=true
+    local has_common_branch=false
+    
+    # Create temporary file to use archive as reference repo for ancestry checks
+    # We need a repo that has both sets of commits to check ancestry
+    # Use archive since it's the target and should have the superset
+    
+    # Check each prod branch against archive
+    while read -r prod_hash prod_ref; do
+        [[ -z "$prod_hash" ]] && continue
+        
+        # Get the same branch from archive
+        local archive_hash
+        archive_hash=$(echo "$archive_refs" | grep " $prod_ref$" | awk '{print $1}' || echo "")
+        
+        if [[ -z "$archive_hash" ]]; then
+            # Branch exists in prod but not archive - prod has something archive doesn't
+            # But this could be a deleted branch, so don't immediately say prod is ahead
+            continue
+        fi
+        
+        has_common_branch=true
+        
+        if [[ "$prod_hash" == "$archive_hash" ]]; then
+            # Same commit - neither ahead for this branch
+            continue
+        fi
+        
+        # Different commits - check ancestry
+        # First, try to check if prod is ancestor of archive (archive ahead)
+        if is_ancestor "$archive_git" "$prod_hash" "$archive_hash" 2>/dev/null; then
+            # Prod commit is ancestor of archive commit - archive is ahead for this branch
+            prod_ahead=false
+        elif is_ancestor "$archive_git" "$archive_hash" "$prod_hash" 2>/dev/null; then
+            # Archive commit is ancestor of prod commit - prod is ahead for this branch
+            archive_ahead=false
+        else
+            # Neither is ancestor - diverged
+            archive_ahead=false
+            prod_ahead=false
+        fi
+    done <<< "$prod_refs"
+    
+    # Also check for branches only in archive (archive has extra branches)
+    while read -r archive_hash archive_ref; do
+        [[ -z "$archive_hash" ]] && continue
+        
+        local prod_hash
+        prod_hash=$(echo "$prod_refs" | grep " $archive_ref$" | awk '{print $1}' || echo "")
+        
+        if [[ -z "$prod_hash" ]]; then
+            # Branch exists in archive but not prod - archive has something prod doesn't
+            # This means archive is ahead (has extra branches)
+            prod_ahead=false
+        fi
+    done <<< "$archive_refs"
+    
+    # Determine final relationship
+    if [[ "$has_common_branch" == "false" ]]; then
+        # No common branches - completely different
+        echo "diverged"
+        return
+    fi
+    
+    if [[ "$archive_ahead" == "true" && "$prod_ahead" == "false" ]]; then
+        echo "archive-ahead"
+    elif [[ "$prod_ahead" == "true" && "$archive_ahead" == "false" ]]; then
+        echo "prod-ahead"
+    elif [[ "$archive_ahead" == "true" && "$prod_ahead" == "true" ]]; then
+        # Both true means all common branches are identical
+        # But one might have extra branches
+        echo "in-sync"
+    else
+        echo "diverged"
+    fi
+}
+
+# Main
+main() {
+    if [[ $# -ne 4 ]]; then
+        usage
+    fi
+    
+    local prod_git_base="$1"
+    local archive_git_base="$2"
+    local repo_list="$3"
+    local output_dir="$4"
+    
+    # Validate inputs
+    if [[ ! -d "$prod_git_base" ]]; then
+        log_error "Prod git base directory not found: $prod_git_base"
+        exit 1
+    fi
+    
+    if [[ ! -d "$archive_git_base" ]]; then
+        log_error "Archive git base directory not found: $archive_git_base"
+        exit 1
+    fi
+    
+    if [[ ! -f "$repo_list" ]]; then
+        log_error "Repo list file not found: $repo_list"
+        exit 1
+    fi
+    
+    log_info "=== Git Data Comparison ==="
+    log_info "Prod git base: $prod_git_base"
+    log_info "Archive git base: $archive_git_base"
+    log_info "Repo list: $repo_list"
+    log_info "Output: $output_dir"
+    log_info "Started: $(date)"
+    echo ""
+    
+    # Create output directory
+    mkdir -p "$output_dir"
+    
+    # Output file
+    local tsv_file="$output_dir/git-ancestry.tsv"
+    
+    # Initialize TSV with header
+    echo -e "repo\tnpub\trelationship\tdetails" > "$tsv_file"
+    
+    # Count repos
+    local total_repos
+    total_repos=$(grep -c -v '^#' "$repo_list" 2>/dev/null || echo "0")
+    log_info "Processing $total_repos repos..."
+    echo ""
+    
+    # Counters
+    local count=0
+    local count_archive_ahead=0
+    local count_in_sync=0
+    local count_prod_ahead=0
+    local count_diverged=0
+    local count_archive_only=0
+    local count_prod_only=0
+    local count_both_empty=0
+    
+    # Process each repo
+    while IFS='|' read -r repo npub rest || [[ -n "$repo" ]]; do
+        # Skip comments and empty lines
+        [[ "$repo" =~ ^# ]] && continue
+        [[ -z "$repo" ]] && continue
+        
+        # Clean up whitespace
+        repo="${repo// /}"
+        npub="${npub// /}"
+        
+        [[ -z "$repo" || -z "$npub" ]] && continue
+        
+        count=$((count + 1))
+        
+        # Build git paths
+        local prod_git="$prod_git_base/${npub}/${repo}.git"
+        local archive_git="$archive_git_base/${npub}/${repo}.git"
+        
+        # Compare
+        local relationship details=""
+        relationship=$(compare_repo_git "$prod_git" "$archive_git")
+        
+        # Count by relationship
+        case "$relationship" in
+            archive-ahead) count_archive_ahead=$((count_archive_ahead + 1)) ;;
+            in-sync) count_in_sync=$((count_in_sync + 1)) ;;
+            prod-ahead) count_prod_ahead=$((count_prod_ahead + 1)) ;;
+            diverged) count_diverged=$((count_diverged + 1)) ;;
+            archive-only) count_archive_only=$((count_archive_only + 1)) ;;
+            prod-only) count_prod_only=$((count_prod_only + 1)) ;;
+            both-empty) count_both_empty=$((count_both_empty + 1)) ;;
+        esac
+        
+        # Output TSV line
+        printf '%s\t%s\t%s\t%s\n' "$repo" "$npub" "$relationship" "$details" >> "$tsv_file"
+        
+        # Progress indicator every 10 repos
+        if [[ $((count % 10)) -eq 0 ]]; then
+            log_progress "Processed $count/$total_repos repos..."
+        fi
+    done < "$repo_list"
+    
+    # Clear progress line
+    echo "" >&2
+    
+    # Summary
+    echo ""
+    log_info "=== Comparison Summary ==="
+    log_success "Archive ahead (use archive data): $count_archive_ahead"
+    log_success "In sync: $count_in_sync"
+    log_warn "Prod ahead (needs re-sync): $count_prod_ahead"
+    log_error "Diverged (manual review): $count_diverged"
+    log_info "Archive only: $count_archive_only"
+    log_info "Prod only: $count_prod_only"
+    log_info "Both empty: $count_both_empty"
+    echo ""
+    log_info "Total: $count repos"
+    log_info "Output: $tsv_file"
+}
+
+main "$@"
diff --git a/docs/archive/2026-01-relay-ngit-dev-migration/scripts/30-extract-parse-failures.sh b/docs/archive/2026-01-relay-ngit-dev-migration/scripts/30-extract-parse-failures.sh
new file mode 100755
index 0000000..d762aae
--- /dev/null
+++ b/docs/archive/2026-01-relay-ngit-dev-migration/scripts/30-extract-parse-failures.sh
@@ -0,0 +1,774 @@
+#!/usr/bin/env bash
+#
+# 30-extract-parse-failures.sh - Extract parse failure events from systemd logs
+#
+# PHASE 4a of the GRASP relay to ngit-grasp migration analysis pipeline.
+# Extracts structured [PARSE_FAIL] log entries AND "Invalid announcement"
+# rejections from journalctl.
+#
+# USAGE:
+#   ./30-extract-parse-failures.sh <service-name> <output-dir> [options]
+#
+# EXAMPLES:
+#   # Extract from ngit-grasp service (last 30 days, default)
+#   ./30-extract-parse-failures.sh ngit-grasp.service output/logs
+#
+#   # Extract with custom time range
+#   ./30-extract-parse-failures.sh ngit-grasp.service output/logs --since "2026-01-01"
+#
+#   # Extract from specific time window
+#   ./30-extract-parse-failures.sh ngit-grasp.service output/logs --since "2026-01-15" --until "2026-01-22"
+#
+# OPTIONS:
+#   --since <date>   Start date for log extraction (default: 30 days ago)
+#   --until <date>   End date for log extraction (default: now)
+#   --dry-run        Show what would be extracted without writing files
+#
+# ENRICHMENT:
+#   The script automatically enriches parse failures with repo/npub information
+#   by extracting from "Added rejected announcement" log entries which include
+#   pubkey and identifier fields. Hex pubkeys are converted to npub format using
+#   `nak encode npub <hex-pubkey>` if the nak tool is available.
+#
+# OUTPUT:
+#   <output-dir>/parse-failures.txt
+#
+# OUTPUT FORMAT (TSV):
+#   event_id<TAB>kind<TAB>reason<TAB>repo<TAB>npub
+#
+# EXPECTED LOG FORMATS:
+#   The script looks for three types of log entries:
+#
+#   1. Structured [PARSE_FAIL] entries:
+#      2026-01-22T10:30:45Z ngit-grasp[1234]: [PARSE_FAIL] kind=30618 event_id=abc123... reason="invalid refs format" repo=myrepo npub=npub1...
+#
+#   2. "Invalid announcement" rejections (write policy):
+#      Event rejected by write policy event_id=abc123... relay=wss://... kind=30617 reason=Invalid announcement: multiple clone tags found...
+#
+#   3. "Added rejected announcement" entries (for enrichment):
+#      Added rejected announcement to two-tier index event_id=abc123... kind=30617 identifier=myrepo pubkey=hex...
+#      These entries provide pubkey and identifier for enriching write policy rejections.
+#
+#   NOTE: Builder logs ("Rejected repository announcement note1xxx:") are NOT extracted
+#   because they use bech32 (note1) IDs while write policy logs use hex IDs. Extracting
+#   both would cause double-counting since deduplication only works within each format.
+#   Write policy logs contain the same events, so we don't lose any data.
+#
+#   Required fields: kind, event_id, reason
+#   Enrichment fields: repo (identifier), npub (converted from hex pubkey)
+#
+# DEPENDENCY:
+#   This script requires logging improvements in ngit-grasp to emit structured
+#   [PARSE_FAIL] log entries. Until those are implemented, this script will
+#   find no matching entries (which is handled gracefully).
+#
+#   "Invalid announcement" rejections are logged by the write policy and
+#   should be present in any ngit-grasp deployment.
+#
+#   See: docs/how-to/migrate-to-ngit-grasp.md (Dependencies section)
+#
+#   Expected Rust logging code for [PARSE_FAIL]:
+#     tracing::warn!(
+#         target: "migration",
+#         "[PARSE_FAIL] kind={} event_id={} reason=\"{}\" repo={} npub={}",
+#         event.kind, event.id, reason, identifier, npub
+#     );
+#
+# PREREQUISITES:
+#   - journalctl (systemd)
+#   - grep, awk, sed (standard Unix tools)
+#   - Access to systemd journal (may require sudo or journal group membership)
+#
+# RUNTIME: Depends on log volume, typically < 30 seconds
+#
+# SEE ALSO:
+#   docs/how-to/migrate-to-ngit-grasp.md - Full migration guide
+#   31-extract-purgatory-expiry.sh - Companion script for purgatory expiry logs
+#
+
+set -euo pipefail
+
+# Get script directory for sourcing helpers
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Source the service validation helper
+if [[ -f "$SCRIPT_DIR/validate-service.sh" ]]; then
+    source "$SCRIPT_DIR/validate-service.sh"
+fi
+
+# Colors for output (disabled if not a terminal)
+if [[ -t 1 ]]; then
+    RED='\033[0;31m'
+    GREEN='\033[0;32m'
+    YELLOW='\033[0;33m'
+    BLUE='\033[0;34m'
+    NC='\033[0m'
+else
+    RED=''
+    GREEN=''
+    YELLOW=''
+    BLUE=''
+    NC=''
+fi
+
+log_info() {
+    echo -e "${BLUE}[INFO]${NC} $*" >&2
+}
+
+log_success() {
+    echo -e "${GREEN}[OK]${NC} $*" >&2
+}
+
+log_warn() {
+    echo -e "${YELLOW}[WARN]${NC} $*" >&2
+}
+
+log_error() {
+    echo -e "${RED}[ERROR]${NC} $*" >&2
+}
+
+usage() {
+    echo "Usage: $0 <service-name> <output-dir> [options]"
+    echo ""
+    echo "Arguments:"
+    echo "  service-name  Systemd service name (e.g., ngit-grasp.service)"
+    echo "  output-dir    Directory to store extracted log data"
+    echo ""
+    echo "Options:"
+    echo "  --since <date>        Start date (default: 30 days ago)"
+    echo "  --until <date>        End date (default: now)"
+    echo "  --dry-run             Show what would be extracted without writing"
+    echo ""
+    echo "Examples:"
+    echo "  $0 ngit-grasp.service output/logs"
+    echo "  $0 ngit-grasp.service output/logs --since '2026-01-01'"
+    echo "  $0 ngit-grasp.service output/logs --since '2026-01-15' --until '2026-01-22'"
+    echo ""
+    echo "Expected log formats:"
+    echo "  [PARSE_FAIL] kind=30618 event_id=abc123 reason=\"...\" repo=myrepo npub=npub1..."
+    echo "  Event rejected by write policy event_id=abc123 ... kind=30617 reason=Invalid announcement: ..."
+    echo ""
+    echo "Enrichment:"
+    echo "  Parse failures are automatically enriched with repo/npub from"
+    echo "  'Added rejected announcement' log entries. Hex pubkeys are converted"
+    echo "  to npub format using 'nak encode npub' if available."
+    exit 1
+}
+
+# =============================================================================
+# AWK-BASED BATCH PARSING FUNCTIONS
+# =============================================================================
+# These functions use awk for efficient batch processing instead of per-line
+# grep calls. This provides ~400x speedup for large log files.
+#
+# NOTE: parse_builder_rejection_line() was removed to fix double-counting bug.
+# Builder logs use bech32 (note1) IDs while write policy logs use hex IDs.
+# Since deduplication only works within each format, extracting both caused
+# the same event to be counted twice. Write policy logs contain the same
+# events, so we don't lose any data by only extracting from that source.
+
+# Parse [PARSE_FAIL] log lines in batch using awk
+# Input: file containing log lines with [PARSE_FAIL]
+# Output: TSV lines: event_id<TAB>kind<TAB>reason<TAB>repo<TAB>npub
+parse_parse_fail_batch() {
+    local input_file="$1"
+    awk '
+    {
+        # Extract kind=VALUE
+        kind = ""
+        if (match($0, /kind=([0-9]+)/, m)) kind = m[1]
+        
+        # Extract event_id=VALUE (hex string)
+        event_id = ""
+        if (match($0, /event_id=([a-f0-9]+)/, m)) event_id = m[1]
+        
+        # Extract reason="VALUE" (quoted string)
+        reason = ""
+        if (match($0, /reason="([^"]*)"/, m)) reason = m[1]
+        
+        # Extract repo=VALUE (optional)
+        repo = ""
+        if (match($0, /repo=([^ ]+)/, m)) repo = m[1]
+        
+        # Extract npub=VALUE (optional)
+        npub = ""
+        if (match($0, /npub=([^ ]+)/, m)) npub = m[1]
+        
+        # Output if we have required fields
+        if (kind != "" && event_id != "" && reason != "") {
+            print event_id "\t" kind "\t" reason "\t" repo "\t" npub
+        }
+    }
+    ' "$input_file"
+}
+
+# Parse "Invalid announcement" rejection log lines in batch using awk
+# Input: file containing "Event rejected by write policy" log lines
+# Output: TSV lines: event_id<TAB>kind<TAB>reason<TAB><empty><TAB><empty>
+parse_write_policy_rejection_batch() {
+    local input_file="$1"
+    awk '
+    {
+        # Extract event_id=VALUE (hex string)
+        event_id = ""
+        if (match($0, /event_id=([a-f0-9]+)/, m)) event_id = m[1]
+        
+        # Extract kind=VALUE
+        kind = ""
+        if (match($0, /kind=([0-9]+)/, m)) kind = m[1]
+        
+        # Extract reason=VALUE (everything after "reason=")
+        reason = ""
+        if (match($0, /reason=(.*)$/, m)) reason = m[1]
+        
+        # Output if we have required fields (repo and npub are empty)
+        if (kind != "" && event_id != "" && reason != "") {
+            print event_id "\t" kind "\t" reason "\t\t"
+        }
+    }
+    ' "$input_file"
+}
+
+# Parse "Added rejected announcement" log lines in batch using awk
+# Input: file containing "Added rejected announcement to two-tier index" log lines
+# Output: TSV lines: event_id<TAB>identifier<TAB>pubkey_hex
+parse_rejected_announcement_batch() {
+    local input_file="$1"
+    awk '
+    {
+        # Extract event_id=VALUE (hex string)
+        event_id = ""
+        if (match($0, /event_id=([a-f0-9]+)/, m)) event_id = m[1]
+        
+        # Extract identifier=VALUE (repo name)
+        identifier = ""
+        if (match($0, /identifier=([^ ]+)/, m)) identifier = m[1]
+        
+        # Extract pubkey=VALUE (hex string)
+        pubkey = ""
+        if (match($0, /pubkey=([a-f0-9]+)/, m)) pubkey = m[1]
+        
+        # Output if we have all required fields
+        if (event_id != "" && identifier != "" && pubkey != "") {
+            print event_id "\t" identifier "\t" pubkey
+        }
+    }
+    ' "$input_file"
+}
+
+# Enrich parse failures with repo/npub by looking up event_id in "Added rejected announcement" log entries
+# This is critical because "Invalid announcement" rejections only log event_id and kind,
+# not the repo name or npub. Without enrichment, Phase 5 shows event_id|kind instead
+# of repo|npub in action-required.txt, making the output unusable.
+#
+# Arguments:
+#   $1 - parse failures file to enrich (modified in place)
+#   $2 - lookup file containing event_id -> identifier|pubkey mappings from logs
+#
+# The function:
+#   1. Uses the lookup table built from "Added rejected announcement" log entries
+#   2. For each parse failure with empty repo/npub, looks up the event_id
+#   3. Populates repo and npub columns from the lookup
+#   4. Converts hex pubkeys to npub format using `nak encode npub` if available
+#
+# OPTIMIZATION: This function uses batch processing for efficiency:
+#   - Uses awk for O(n) join instead of per-line grep (O(n*m))
+#   - Batches all pubkey->npub conversions in a single nak call
+#   - This reduces runtime from minutes to seconds for large datasets
+enrich_with_repo_npub() {
+    local parse_failures_file="$1"
+    local lookup_file="$2"
+    
+    # Validate lookup file exists and has content
+    if [[ ! -f "$lookup_file" ]] || [[ ! -s "$lookup_file" ]]; then
+        log_warn "No enrichment data available - repo/npub columns will remain empty"
+        return 0
+    fi
+    
+    log_info "Enriching parse failures with repo/npub from log entries..."
+    
+    # Check if we have nak for pubkey->npub conversion
+    local can_convert_npub=false
+    if command -v nak &> /dev/null; then
+        can_convert_npub=true
+        log_info "  Using 'nak' for pubkey->npub conversion"
+    else
+        log_warn "  'nak' not found - will use hex pubkeys instead of npub"
+    fi
+    
+    local lookup_count
+    lookup_count=$(wc -l < "$lookup_file")
+    lookup_count="${lookup_count//[^0-9]/}"
+    log_info "  Lookup table has $lookup_count entries"
+    
+    # STEP 1: Extract unique pubkeys that need conversion
+    # Get pubkeys from lookup file (column 3), deduplicate
+    local unique_pubkeys_file npub_map_file
+    unique_pubkeys_file=$(mktemp)
+    npub_map_file=$(mktemp)
+    
+    cut -f3 "$lookup_file" | sort -u > "$unique_pubkeys_file"
+    local unique_pubkey_count
+    unique_pubkey_count=$(wc -l < "$unique_pubkeys_file")
+    unique_pubkey_count="${unique_pubkey_count//[^0-9]/}"
+    log_info "  Converting $unique_pubkey_count unique pubkeys to npub format..."
+    
+    # STEP 2: Batch convert all pubkeys to npub in a single nak call
+    # nak reads hex pubkeys from stdin (one per line) and outputs npubs
+    if [[ "$can_convert_npub" == true && "$unique_pubkey_count" -gt 0 ]]; then
+        # Create mapping file: pubkey_hex<TAB>npub
+        # nak encode npub reads from stdin and outputs one npub per line
+        paste "$unique_pubkeys_file" <(nak encode npub < "$unique_pubkeys_file" 2>/dev/null) > "$npub_map_file" || {
+            # Fallback: if batch conversion fails, use hex pubkeys
+            log_warn "  Batch npub conversion failed, using hex pubkeys"
+            awk '{print $1 "\t" $1}' "$unique_pubkeys_file" > "$npub_map_file"
+        }
+    else
+        # No nak available, use hex pubkeys as-is
+        awk '{print $1 "\t" $1}' "$unique_pubkeys_file" > "$npub_map_file"
+    fi
+    
+    rm -f "$unique_pubkeys_file"
+    
+    # STEP 3: Use awk for efficient join (O(n) instead of O(n*m) grep per line)
+    # This joins parse_failures with lookup_file on event_id, then with npub_map on pubkey
+    local enriched_file
+    enriched_file=$(mktemp)
+    
+    # Copy header lines
+    grep '^#' "$parse_failures_file" > "$enriched_file" 2>/dev/null || true
+    
+    # Use awk to perform the join efficiently
+    # Input files (order matters for ARGIND):
+    #   1. npub_map_file: pubkey_hex<TAB>npub
+    #   2. lookup_file: event_id<TAB>identifier<TAB>pubkey_hex
+    #   3. parse_failures_file: event_id<TAB>kind<TAB>reason<TAB>repo<TAB>npub
+    awk -F'\t' -v OFS='\t' '
+        # Track which file we are processing
+        FNR==1 { file_num++ }
+        
+        # First file: npub_map (pubkey_hex -> npub)
+        file_num==1 {
+            npub_map[$1] = $2
+            next
+        }
+        # Second file: lookup (event_id -> identifier, pubkey_hex)
+        file_num==2 {
+            lookup_repo[$1] = $2
+            lookup_pubkey[$1] = $3
+            next
+        }
+        # Third file: parse_failures
+        /^#/ { next }  # Skip headers (already copied)
+        {
+            event_id = $1
+            kind = $2
+            reason = $3
+            repo = $4
+            npub = $5
+            
+            # If repo/npub empty, try to enrich from lookup
+            if (repo == "" && event_id in lookup_repo) {
+                repo = lookup_repo[event_id]
+            }
+            if (npub == "" && event_id in lookup_pubkey) {
+                pubkey = lookup_pubkey[event_id]
+                if (pubkey in npub_map) {
+                    npub = npub_map[pubkey]
+                } else {
+                    npub = pubkey  # Fallback to hex
+                }
+            }
+            
+            print event_id, kind, reason, repo, npub
+        }
+    ' "$npub_map_file" "$lookup_file" "$parse_failures_file" >> "$enriched_file"
+    
+    rm -f "$npub_map_file"
+    
+    # Count enriched entries
+    local enriched_count total_count
+    total_count=$(grep -v '^#' "$parse_failures_file" | wc -l)
+    total_count="${total_count//[^0-9]/}"
+    # Count entries that have non-empty repo AND npub after enrichment
+    enriched_count=$(grep -v '^#' "$enriched_file" | awk -F'\t' '$4 != "" && $5 != ""' | wc -l)
+    enriched_count="${enriched_count//[^0-9]/}"
+    
+    # Replace original with enriched version
+    mv "$enriched_file" "$parse_failures_file"
+    
+    log_info "  Enriched $enriched_count of $total_count parse failures with repo/npub"
+    log_success "Enrichment complete"
+}
+
+# Parse "Added rejected announcement" log entries to build enrichment lookup table
+# Input: log line containing "Added rejected announcement to two-tier index"
+# Output: TSV line: event_id<TAB>identifier<TAB>pubkey_hex
+parse_rejected_announcement_line() {
+    local line="$1"
+    
+    local event_id identifier pubkey_hex
+    
+    # Extract event_id=VALUE (hex string)
+    event_id=$(echo "$line" | grep -oP 'event_id=\K[a-f0-9]+' || echo "")
+    
+    # Extract identifier=VALUE (repo name)
+    identifier=$(echo "$line" | grep -oP 'identifier=\K[^ ]+' || echo "")
+    
+    # Extract pubkey=VALUE (hex string)
+    pubkey_hex=$(echo "$line" | grep -oP 'pubkey=\K[a-f0-9]+' || echo "")
+    
+    # Only output if we have all required fields
+    if [[ -n "$event_id" && -n "$identifier" && -n "$pubkey_hex" ]]; then
+        printf '%s\t%s\t%s\n' "$event_id" "$identifier" "$pubkey_hex"
+    fi
+}
+
+# Main
+main() {
+    if [[ $# -lt 2 ]]; then
+        usage
+    fi
+    
+    local service="$1"
+    local output_dir="$2"
+    shift 2
+    
+    # Default time range: last 30 days
+    local since_date
+    since_date=$(date -d "30 days ago" "+%Y-%m-%d" 2>/dev/null || date -v-30d "+%Y-%m-%d" 2>/dev/null || echo "")
+    local until_date=""
+    local dry_run=false
+    
+    # Parse options
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --since)
+                since_date="$2"
+                shift 2
+                ;;
+            --until)
+                until_date="$2"
+                shift 2
+                ;;
+            --dry-run)
+                dry_run=true
+                shift
+                ;;
+            *)
+                log_error "Unknown option: $1"
+                usage
+                ;;
+        esac
+    done
+    
+    # Validate service name format
+    if [[ ! "$service" =~ \.service$ ]]; then
+        service="${service}.service"
+    fi
+    
+    # Validate service is appropriate for structured logging
+    # This prevents the common mistake of using ngit-relay instead of ngit-grasp
+    if type validate_service_for_structured_logging &>/dev/null; then
+        # Use non-interactive mode if not a terminal, skip log check (we'll do our own)
+        local interactive="true"
+        [[ ! -t 0 ]] && interactive="false"
+        
+        if ! validate_service_for_structured_logging "$service" "false" "$interactive"; then
+            log_error "Service validation failed. Use an ngit-grasp service for structured logging."
+            exit 1
+        fi
+    else
+        # Fallback validation if helper not available
+        if [[ "$service" == *"ngit-relay"* ]]; then
+            log_error "Service name appears to be ngit-relay: $service"
+            log_error "Structured logging ([PARSE_FAIL]) only exists in ngit-grasp services."
+            log_error "Please use the ngit-grasp archive service instead."
+            log_error ""
+            log_error "To find the correct service:"
+            log_error "  systemctl list-units 'ngit-grasp*' --all"
+            exit 1
+        fi
+    fi
+    
+    log_info "Extracting parse failures from systemd logs"
+    log_info "Service: $service"
+    log_info "Output: $output_dir"
+    log_info "Time range: ${since_date:-beginning} to ${until_date:-now}"
+    
+    # Check if journalctl is available
+    if ! command -v journalctl &> /dev/null; then
+        log_error "journalctl not found. This script requires systemd."
+        exit 1
+    fi
+    
+    # Validate service exists (check if journalctl can find any logs for it)
+    # Note: We don't require the service to be running, just that it has logs
+    if ! journalctl --no-pager -u "$service" -n 1 &>/dev/null; then
+        log_warn "Could not query logs for service: $service"
+        log_warn "This may indicate the service doesn't exist or you lack permissions."
+        log_warn ""
+        log_warn "To list available ngit-grasp services:"
+        log_warn "  systemctl list-units 'ngit-grasp*' --all"
+        log_warn "  journalctl --list-boots  # Check if you have journal access"
+        log_warn ""
+        # Continue anyway - the service might exist but have no logs yet
+    fi
+    
+    # Build journalctl command
+    local journal_cmd="journalctl -u $service --no-pager -o short-iso"
+    
+    if [[ -n "$since_date" ]]; then
+        journal_cmd="$journal_cmd --since '$since_date'"
+    fi
+    
+    if [[ -n "$until_date" ]]; then
+        journal_cmd="$journal_cmd --until '$until_date'"
+    fi
+    
+    log_info "Running: $journal_cmd | grep '[PARSE_FAIL]' or 'Invalid announcement'"
+    
+    if [[ "$dry_run" == true ]]; then
+        log_info "[DRY RUN] Would extract to: $output_dir/parse-failures.txt"
+        
+        # Show sample of what would be extracted
+        log_info "Checking for matching log entries..."
+        local parse_fail_count invalid_announcement_count
+        parse_fail_count=$(eval "$journal_cmd" 2>/dev/null | grep -c '\[PARSE_FAIL\]' || echo "0")
+        parse_fail_count="${parse_fail_count//[^0-9]/}"  # Strip non-numeric characters
+        parse_fail_count="${parse_fail_count:-0}"
+        
+        invalid_announcement_count=$(eval "$journal_cmd" 2>/dev/null | grep 'Event rejected by write policy' | grep -c 'Invalid announcement' || echo "0")
+        invalid_announcement_count="${invalid_announcement_count//[^0-9]/}"
+        invalid_announcement_count="${invalid_announcement_count:-0}"
+        
+        log_info "Found $parse_fail_count [PARSE_FAIL] entries"
+        log_info "Found $invalid_announcement_count 'Invalid announcement' rejections"
+        
+        if [[ "$parse_fail_count" -eq 0 && "$invalid_announcement_count" -eq 0 ]]; then
+            log_warn "No matching entries found in logs."
+            log_warn "This is expected if ngit-grasp logging improvements are not yet deployed."
+            log_warn "See: docs/how-to/migrate-to-ngit-grasp.md (Dependencies section)"
+        fi
+        
+        exit 0
+    fi
+    
+    # Create output directory
+    mkdir -p "$output_dir"
+    
+    local output_file="$output_dir/parse-failures.txt"
+    local temp_file
+    temp_file=$(mktemp)
+    
+    # Extract and parse log entries using streaming (avoids loading all logs into memory)
+    log_info "Extracting log entries..."
+    
+    # Create temp files for intermediate results
+    local temp_stderr temp_parse_fail temp_write_policy_rejection temp_rejected_announcement
+    temp_stderr=$(mktemp)
+    temp_parse_fail=$(mktemp)
+    temp_write_policy_rejection=$(mktemp)
+    temp_rejected_announcement=$(mktemp)
+    
+    # Extract [PARSE_FAIL] entries directly to temp file (streaming)
+    log_info "  Searching for [PARSE_FAIL] entries..."
+    eval "$journal_cmd" 2>"$temp_stderr" | grep '\[PARSE_FAIL\]' > "$temp_parse_fail" || true
+    
+    local journal_stderr
+    journal_stderr=$(cat "$temp_stderr" 2>/dev/null || true)
+    if [[ -n "$journal_stderr" ]]; then
+        log_warn "journalctl reported: $journal_stderr"
+    fi
+    
+    # Extract "Event rejected by write policy" with "Invalid announcement" (streaming)
+    # NOTE: We only extract from write policy logs (hex IDs), not builder logs (note1 IDs)
+    # to avoid double-counting. Both log sources contain the same events.
+    log_info "  Searching for write policy rejections..."
+    eval "$journal_cmd" 2>/dev/null | grep 'Event rejected by write policy' | grep 'Invalid announcement' > "$temp_write_policy_rejection" || true
+    
+    # Extract "Added rejected announcement" entries for enrichment (streaming)
+    # These contain pubkey and identifier which we use to enrich write policy rejections
+    log_info "  Searching for rejected announcement entries (for enrichment)..."
+    eval "$journal_cmd" 2>/dev/null | grep 'Added rejected announcement to two-tier index' > "$temp_rejected_announcement" || true
+    
+    rm -f "$temp_stderr"
+    
+    # Check if we found anything
+    local parse_fail_line_count write_policy_line_count rejected_announcement_line_count
+    parse_fail_line_count=$(wc -l < "$temp_parse_fail")
+    parse_fail_line_count="${parse_fail_line_count//[^0-9]/}"
+    write_policy_line_count=$(wc -l < "$temp_write_policy_rejection")
+    write_policy_line_count="${write_policy_line_count//[^0-9]/}"
+    rejected_announcement_line_count=$(wc -l < "$temp_rejected_announcement")
+    rejected_announcement_line_count="${rejected_announcement_line_count//[^0-9]/}"
+    
+    log_info "  Found $parse_fail_line_count [PARSE_FAIL] log lines"
+    log_info "  Found $write_policy_line_count write policy rejection log lines"
+    log_info "  Found $rejected_announcement_line_count rejected announcement log lines (for enrichment)"
+    
+    local total_invalid_announcement_lines=$write_policy_line_count
+    
+    if [[ "$parse_fail_line_count" -eq 0 && "$total_invalid_announcement_lines" -eq 0 ]]; then
+        log_warn "No matching entries found in logs."
+        log_warn ""
+        log_warn "This is expected if ngit-grasp logging improvements are not yet deployed."
+        log_warn "The script looks for:"
+        log_warn ""
+        log_warn "  1. [PARSE_FAIL] kind=30618 event_id=abc123 reason=\"...\" repo=myrepo npub=npub1..."
+        log_warn "  2. Event rejected by write policy event_id=... kind=30617 reason=Invalid announcement: ..."
+        log_warn ""
+        log_warn "See: docs/how-to/migrate-to-ngit-grasp.md (Dependencies section)"
+        log_warn ""
+        
+        # Create empty output file with header comment
+        {
+            echo "# Parse failures and invalid announcements extracted from $service"
+            echo "# Time range: ${since_date:-beginning} to ${until_date:-now}"
+            echo "# Extracted: $(date -Iseconds)"
+            echo "#"
+            echo "# Includes:"
+            echo "#   - [PARSE_FAIL] structured log entries"
+            echo "#   - \"Invalid announcement\" rejections"
+            echo "#"
+            echo "# Format: event_id<TAB>kind<TAB>reason<TAB>repo<TAB>npub"
+            echo "# Note: repo and npub may be empty for some entries"
+            echo "#"
+            echo "# NOTE: No matching entries found."
+            echo "# This is expected if ngit-grasp logging improvements are not yet deployed."
+        } > "$output_file"
+        
+        rm -f "$temp_parse_fail" "$temp_write_policy_rejection" "$temp_rejected_announcement"
+        log_info "Created empty output file: $output_file"
+        exit 0
+    fi
+    
+    # Write header
+    {
+        echo "# Parse failures and invalid announcements extracted from $service"
+        echo "# Time range: ${since_date:-beginning} to ${until_date:-now}"
+        echo "# Extracted: $(date -Iseconds)"
+        echo "#"
+        echo "# Includes:"
+        echo "#   - [PARSE_FAIL] structured log entries"
+        echo "#   - \"Invalid announcement\" rejections"
+        echo "#"
+        echo "# Format: event_id<TAB>kind<TAB>reason<TAB>repo<TAB>npub"
+        echo "# Note: repo and npub may be empty for some entries"
+    } > "$output_file"
+    
+    # Parse [PARSE_FAIL] entries using batch awk processing
+    log_info "  Parsing [PARSE_FAIL] entries..."
+    local parse_fail_count=0
+    if [[ "$parse_fail_line_count" -gt 0 ]]; then
+        parse_parse_fail_batch "$temp_parse_fail" >> "$output_file"
+        parse_fail_count=$(grep -v '^#' "$output_file" | wc -l)
+        parse_fail_count="${parse_fail_count//[^0-9]/}"
+    fi
+    
+    # Parse write policy rejection entries using batch awk processing
+    log_info "  Parsing write policy rejection entries..."
+    local write_policy_count=0
+    if [[ "$write_policy_line_count" -gt 0 ]]; then
+        local before_count
+        before_count=$(grep -v '^#' "$output_file" 2>/dev/null | wc -l || echo "0")
+        before_count="${before_count//[^0-9]/}"
+        before_count="${before_count:-0}"
+        parse_write_policy_rejection_batch "$temp_write_policy_rejection" >> "$output_file"
+        local after_count
+        after_count=$(grep -v '^#' "$output_file" 2>/dev/null | wc -l || echo "0")
+        after_count="${after_count//[^0-9]/}"
+        after_count="${after_count:-0}"
+        write_policy_count=$((after_count - before_count))
+    fi
+    
+    local invalid_announcement_count=$write_policy_count
+    
+    # Build enrichment lookup table from "Added rejected announcement" entries
+    local enrichment_lookup_file
+    enrichment_lookup_file=$(mktemp)
+    
+    log_info "  Building enrichment lookup table..."
+    if [[ "$rejected_announcement_line_count" -gt 0 ]]; then
+        parse_rejected_announcement_batch "$temp_rejected_announcement" > "$enrichment_lookup_file"
+    fi
+    
+    rm -f "$temp_parse_fail" "$temp_write_policy_rejection" "$temp_rejected_announcement"
+    
+    # Deduplicate by event_id (first column) - keep first occurrence
+    log_info "  Deduplicating entries..."
+    local deduped_file
+    deduped_file=$(mktemp)
+    # Preserve header lines (starting with #) and deduplicate data lines
+    grep '^#' "$output_file" > "$deduped_file"
+    grep -v '^#' "$output_file" | sort -t$'\t' -k1,1 -u >> "$deduped_file"
+    mv "$deduped_file" "$output_file"
+    
+    # Deduplicate enrichment lookup table by event_id
+    if [[ -s "$enrichment_lookup_file" ]]; then
+        sort -t$'\t' -k1,1 -u "$enrichment_lookup_file" > "$enrichment_lookup_file.deduped"
+        mv "$enrichment_lookup_file.deduped" "$enrichment_lookup_file"
+    fi
+    
+    # Enrich with repo/npub from "Added rejected announcement" log entries
+    # This is critical for usability - without it, action-required.txt shows
+    # event_id|kind instead of repo|npub, making parse failures unidentifiable
+    enrich_with_repo_npub "$output_file" "$enrichment_lookup_file"
+    
+    rm -f "$enrichment_lookup_file"
+    
+    # Count final entries (excluding header lines)
+    local count
+    count=$(grep -v '^#' "$output_file" | wc -l)
+    count="${count//[^0-9]/}"  # Strip whitespace
+    count="${count:-0}"
+    
+    rm -f "$temp_file"
+    
+    # Summary
+    echo ""
+    log_info "=== Extraction Summary ==="
+    log_info "Service: $service"
+    log_info "Time range: ${since_date:-beginning} to ${until_date:-now}"
+    log_success "Extracted $count total entries"
+    log_info "  - [PARSE_FAIL] entries: $parse_fail_count"
+    log_info "  - Invalid announcement rejections: $invalid_announcement_count"
+    echo ""
+    log_info "Output file: $output_file"
+    
+    if [[ $count -gt 0 ]]; then
+        echo ""
+        log_info "Sample entries (first 5):"
+        # Use a subshell to avoid SIGPIPE issues with set -e
+        # New format: event_id<TAB>kind<TAB>reason<TAB>repo<TAB>npub
+        (grep -v '^#' "$output_file" | head -5 | while IFS=$'\t' read -r event_id kind reason repo npub; do
+            echo "  kind=$kind event_id=${event_id:0:16}... reason=\"${reason:0:60}...\""
+        done) || true
+    fi
+    
+    # Breakdown by kind
+    if [[ $count -gt 0 ]]; then
+        echo ""
+        log_info "Breakdown by event kind:"
+        # Use a subshell to avoid SIGPIPE issues with set -e
+        # kind is now column 2
+        (grep -v '^#' "$output_file" | awk -F'\t' '{print $2}' | sort | uniq -c | sort -rn | while read -r cnt kind; do
+            echo "  kind $kind: $cnt failures"
+        done) || true
+    fi
+    
+    # Breakdown by reason pattern (for invalid announcements)
+    if [[ $invalid_announcement_count -gt 0 ]]; then
+        echo ""
+        log_info "Breakdown by reason pattern:"
+        # Extract the main reason type (before the colon details)
+        (grep -v '^#' "$output_file" | awk -F'\t' '{print $3}' | sed 's/:.*//' | sort | uniq -c | sort -rn | head -10 | while read -r cnt reason; do
+            echo "  $reason: $cnt"
+        done) || true
+    fi
+    
+    # Explicit success exit
+    exit 0
+}
+
+main "$@"
diff --git a/docs/archive/2026-01-relay-ngit-dev-migration/scripts/31-extract-purgatory-expiry.sh b/docs/archive/2026-01-relay-ngit-dev-migration/scripts/31-extract-purgatory-expiry.sh
new file mode 100755
index 0000000..a0c8ad0
--- /dev/null
+++ b/docs/archive/2026-01-relay-ngit-dev-migration/scripts/31-extract-purgatory-expiry.sh
@@ -0,0 +1,408 @@
+#!/usr/bin/env bash
+#
+# 31-extract-purgatory-expiry.sh - Extract purgatory expiry events from systemd logs
+#
+# PHASE 4b of the GRASP relay to ngit-grasp migration analysis pipeline.
+# Extracts structured [PURGATORY_EXPIRED] log entries from journalctl.
+#
+# USAGE:
+#   ./31-extract-purgatory-expiry.sh <service-name> <output-dir> [options]
+#
+# EXAMPLES:
+#   # Extract from ngit-grasp service (last 30 days, default)
+#   ./31-extract-purgatory-expiry.sh ngit-grasp.service output/logs
+#
+#   # Extract with custom time range
+#   ./31-extract-purgatory-expiry.sh ngit-grasp.service output/logs --since "2026-01-01"
+#
+#   # Extract from specific time window
+#   ./31-extract-purgatory-expiry.sh ngit-grasp.service output/logs --since "2026-01-15" --until "2026-01-22"
+#
+# OPTIONS:
+#   --since <date>   Start date for log extraction (default: 30 days ago)
+#   --until <date>   End date for log extraction (default: now)
+#   --dry-run        Show what would be extracted without writing files
+#
+# OUTPUT:
+#   <output-dir>/purgatory-expired.txt
+#
+# OUTPUT FORMAT (TSV):
+#   repo<TAB>npub<TAB>timestamp<TAB>reason
+#
+# EXPECTED LOG FORMAT:
+#   The script looks for structured log entries in this format:
+#
+#   2026-01-22T10:30:45Z ngit-grasp[1234]: [PURGATORY_EXPIRED] repo=myrepo npub=npub1... reason="clone URL unreachable after 7 days"
+#
+#   Required fields: repo, npub
+#   Optional fields: reason (explains why purgatory expired)
+#
+# BACKGROUND:
+#   "Purgatory" is the state where ngit-grasp has received an announcement event
+#   but cannot yet sync the git data (e.g., clone URL unreachable, git server down).
+#   After a configurable timeout (default 7 days), the repository is marked as
+#   expired and removed from purgatory.
+#
+#   Purgatory expiry during migration analysis indicates repositories that:
+#   - Had valid announcements on the production relay
+#   - Could not be synced to the archive relay
+#   - May need manual intervention or investigation
+#
+# DEPENDENCY:
+#   This script requires logging improvements in ngit-grasp to emit structured
+#   [PURGATORY_EXPIRED] log entries. Until those are implemented, this script
+#   will find no matching entries (which is handled gracefully).
+#
+#   See: docs/how-to/migrate-to-ngit-grasp.md (Dependencies section)
+#
+#   Expected Rust logging code:
+#     tracing::warn!(
+#         target: "migration",
+#         "[PURGATORY_EXPIRED] repo={} npub={} reason=\"{}\"",
+#         identifier, npub, reason
+#     );
+#
+# PREREQUISITES:
+#   - journalctl (systemd)
+#   - grep, awk (standard Unix tools)
+#   - Access to systemd journal (may require sudo or journal group membership)
+#
+# RUNTIME: Depends on log volume, typically < 30 seconds
+#
+# SEE ALSO:
+#   docs/how-to/migrate-to-ngit-grasp.md - Full migration guide
+#   30-extract-parse-failures.sh - Companion script for parse failure logs
+#
+
+set -euo pipefail
+
+# Get script directory for sourcing helpers
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Source the service validation helper
+if [[ -f "$SCRIPT_DIR/validate-service.sh" ]]; then
+    source "$SCRIPT_DIR/validate-service.sh"
+fi
+
+# Colors for output (disabled if not a terminal)
+if [[ -t 1 ]]; then
+    RED='\033[0;31m'
+    GREEN='\033[0;32m'
+    YELLOW='\033[0;33m'
+    BLUE='\033[0;34m'
+    NC='\033[0m'
+else
+    RED=''
+    GREEN=''
+    YELLOW=''
+    BLUE=''
+    NC=''
+fi
+
+log_info() {
+    echo -e "${BLUE}[INFO]${NC} $*" >&2
+}
+
+log_success() {
+    echo -e "${GREEN}[OK]${NC} $*" >&2
+}
+
+log_warn() {
+    echo -e "${YELLOW}[WARN]${NC} $*" >&2
+}
+
+log_error() {
+    echo -e "${RED}[ERROR]${NC} $*" >&2
+}
+
+usage() {
+    echo "Usage: $0 <service-name> <output-dir> [options]"
+    echo ""
+    echo "Arguments:"
+    echo "  service-name  Systemd service name (e.g., ngit-grasp.service)"
+    echo "  output-dir    Directory to store extracted log data"
+    echo ""
+    echo "Options:"
+    echo "  --since <date>   Start date (default: 30 days ago)"
+    echo "  --until <date>   End date (default: now)"
+    echo "  --dry-run        Show what would be extracted without writing"
+    echo ""
+    echo "Examples:"
+    echo "  $0 ngit-grasp.service output/logs"
+    echo "  $0 ngit-grasp.service output/logs --since '2026-01-01'"
+    echo "  $0 ngit-grasp.service output/logs --since '2026-01-15' --until '2026-01-22'"
+    echo ""
+    echo "Expected log format:"
+    echo "  [PURGATORY_EXPIRED] repo=myrepo npub=npub1... reason=\"...\""
+    exit 1
+}
+
+# Parse a single log line and extract fields
+# Input: log line containing [PURGATORY_EXPIRED]
+# Output: TSV line: repo<TAB>npub<TAB>timestamp<TAB>reason
+parse_log_line() {
+    local line="$1"
+    
+    # Extract timestamp from the beginning of the log line
+    # Format: 2026-01-22T10:30:45+0000 or similar ISO format
+    local timestamp repo npub reason
+    
+    # Extract ISO timestamp from beginning of line
+    timestamp=$(echo "$line" | grep -oP '^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}' || echo "")
+    
+    # Extract repo=VALUE (unquoted identifier)
+    repo=$(echo "$line" | grep -oP 'repo=\K[^ ]+' || echo "")
+    
+    # Extract npub=VALUE (npub1... format)
+    npub=$(echo "$line" | grep -oP 'npub=\K[^ ]+' || echo "")
+    
+    # Extract reason="VALUE" (quoted string, optional)
+    reason=$(echo "$line" | grep -oP 'reason="\K[^"]*' || echo "")
+    
+    # Only output if we have the required fields
+    if [[ -n "$repo" && -n "$npub" ]]; then
+        printf '%s\t%s\t%s\t%s\n' "$repo" "$npub" "$timestamp" "$reason"
+    fi
+}
+
+# Main
+main() {
+    if [[ $# -lt 2 ]]; then
+        usage
+    fi
+    
+    local service="$1"
+    local output_dir="$2"
+    shift 2
+    
+    # Default time range: last 30 days
+    local since_date
+    since_date=$(date -d "30 days ago" "+%Y-%m-%d" 2>/dev/null || date -v-30d "+%Y-%m-%d" 2>/dev/null || echo "")
+    local until_date=""
+    local dry_run=false
+    
+    # Parse options
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --since)
+                since_date="$2"
+                shift 2
+                ;;
+            --until)
+                until_date="$2"
+                shift 2
+                ;;
+            --dry-run)
+                dry_run=true
+                shift
+                ;;
+            *)
+                log_error "Unknown option: $1"
+                usage
+                ;;
+        esac
+    done
+    
+    # Validate service name format
+    if [[ ! "$service" =~ \.service$ ]]; then
+        service="${service}.service"
+    fi
+    
+    # Validate service is appropriate for structured logging
+    # This prevents the common mistake of using ngit-relay instead of ngit-grasp
+    if type validate_service_for_structured_logging &>/dev/null; then
+        # Use non-interactive mode if not a terminal, skip log check (we'll do our own)
+        local interactive="true"
+        [[ ! -t 0 ]] && interactive="false"
+        
+        if ! validate_service_for_structured_logging "$service" "false" "$interactive"; then
+            log_error "Service validation failed. Use an ngit-grasp service for structured logging."
+            exit 1
+        fi
+    else
+        # Fallback validation if helper not available
+        if [[ "$service" == *"ngit-relay"* ]]; then
+            log_error "Service name appears to be ngit-relay: $service"
+            log_error "Structured logging ([PURGATORY_EXPIRED]) only exists in ngit-grasp services."
+            log_error "Please use the ngit-grasp archive service instead."
+            log_error ""
+            log_error "To find the correct service:"
+            log_error "  systemctl list-units 'ngit-grasp*' --all"
+            exit 1
+        fi
+    fi
+    
+    log_info "Extracting purgatory expiry events from systemd logs"
+    log_info "Service: $service"
+    log_info "Output: $output_dir"
+    log_info "Time range: ${since_date:-beginning} to ${until_date:-now}"
+    
+    # Check if journalctl is available
+    if ! command -v journalctl &> /dev/null; then
+        log_error "journalctl not found. This script requires systemd."
+        exit 1
+    fi
+    
+    # Validate service exists (check if journalctl can find any logs for it)
+    # Note: We don't require the service to be running, just that it has logs
+    if ! journalctl --no-pager -u "$service" -n 1 &>/dev/null; then
+        log_warn "Could not query logs for service: $service"
+        log_warn "This may indicate the service doesn't exist or you lack permissions."
+        log_warn ""
+        log_warn "To list available ngit-grasp services:"
+        log_warn "  systemctl list-units 'ngit-grasp*' --all"
+        log_warn "  journalctl --list-boots  # Check if you have journal access"
+        log_warn ""
+        # Continue anyway - the service might exist but have no logs yet
+    fi
+    
+    # Build journalctl command
+    local journal_cmd="journalctl -u $service --no-pager -o short-iso"
+    
+    if [[ -n "$since_date" ]]; then
+        journal_cmd="$journal_cmd --since '$since_date'"
+    fi
+    
+    if [[ -n "$until_date" ]]; then
+        journal_cmd="$journal_cmd --until '$until_date'"
+    fi
+    
+    log_info "Running: $journal_cmd | grep '\\[PURGATORY_EXPIRED\\]'"
+    
+    if [[ "$dry_run" == true ]]; then
+        log_info "[DRY RUN] Would extract to: $output_dir/purgatory-expired.txt"
+        
+        # Show sample of what would be extracted
+        log_info "Checking for matching log entries..."
+        local sample_count
+        sample_count=$(eval "$journal_cmd" 2>/dev/null | grep -c '\[PURGATORY_EXPIRED\]' || echo "0")
+        sample_count="${sample_count//[^0-9]/}"  # Strip non-numeric characters
+        sample_count="${sample_count:-0}"
+        log_info "Found $sample_count matching log entries"
+        
+        if [[ "$sample_count" -eq 0 ]]; then
+            log_warn "No [PURGATORY_EXPIRED] entries found in logs."
+            log_warn "This is expected if ngit-grasp logging improvements are not yet deployed."
+            log_warn "See: docs/how-to/migrate-to-ngit-grasp.md (Dependencies section)"
+        fi
+        
+        exit 0
+    fi
+    
+    # Create output directory
+    mkdir -p "$output_dir"
+    
+    local output_file="$output_dir/purgatory-expired.txt"
+    local temp_file
+    temp_file=$(mktemp)
+    
+    # Extract and parse log entries
+    log_info "Extracting log entries..."
+    
+    # Get raw log lines containing [PURGATORY_EXPIRED]
+    # Capture stderr separately to detect journalctl errors
+    local raw_lines journal_stderr journal_exit
+    local temp_stderr
+    temp_stderr=$(mktemp)
+    
+    raw_lines=$(eval "$journal_cmd" 2>"$temp_stderr" | grep '\[PURGATORY_EXPIRED\]' || true)
+    journal_exit=$?
+    journal_stderr=$(cat "$temp_stderr" 2>/dev/null || true)
+    rm -f "$temp_stderr"
+    
+    # Report any journalctl errors (but don't fail - empty logs are valid)
+    if [[ -n "$journal_stderr" ]]; then
+        log_warn "journalctl reported: $journal_stderr"
+    fi
+    
+    if [[ -z "$raw_lines" ]]; then
+        log_warn "No [PURGATORY_EXPIRED] entries found in logs."
+        log_warn ""
+        log_warn "This is expected if ngit-grasp logging improvements are not yet deployed."
+        log_warn "The structured log format required by this script:"
+        log_warn ""
+        log_warn "  [PURGATORY_EXPIRED] repo=myrepo npub=npub1... reason=\"...\""
+        log_warn ""
+        log_warn "See: docs/how-to/migrate-to-ngit-grasp.md (Dependencies section)"
+        log_warn ""
+        
+        # Create empty output file with header comment
+        {
+            echo "# Purgatory expiry events extracted from $service"
+            echo "# Time range: ${since_date:-beginning} to ${until_date:-now}"
+            echo "# Extracted: $(date -Iseconds)"
+            echo "# Format: repo<TAB>npub<TAB>timestamp<TAB>reason"
+            echo "#"
+            echo "# NOTE: No [PURGATORY_EXPIRED] entries found."
+            echo "# This is expected if ngit-grasp logging improvements are not yet deployed."
+        } > "$output_file"
+        
+        log_info "Created empty output file: $output_file"
+        exit 0
+    fi
+    
+    # Write header
+    {
+        echo "# Purgatory expiry events extracted from $service"
+        echo "# Time range: ${since_date:-beginning} to ${until_date:-now}"
+        echo "# Extracted: $(date -Iseconds)"
+        echo "# Format: repo<TAB>npub<TAB>timestamp<TAB>reason"
+    } > "$output_file"
+    
+    # Parse each line
+    local count=0
+    while IFS= read -r line; do
+        local parsed
+        parsed=$(parse_log_line "$line")
+        if [[ -n "$parsed" ]]; then
+            echo "$parsed" >> "$output_file"
+            count=$((count + 1))
+        fi
+    done <<< "$raw_lines"
+    
+    rm -f "$temp_file"
+    
+    # Summary
+    echo ""
+    log_info "=== Extraction Summary ==="
+    log_info "Service: $service"
+    log_info "Time range: ${since_date:-beginning} to ${until_date:-now}"
+    log_success "Extracted $count purgatory expiry entries"
+    echo ""
+    log_info "Output file: $output_file"
+    
+    if [[ $count -gt 0 ]]; then
+        echo ""
+        log_info "Sample entries (first 5):"
+        # Use a subshell to avoid SIGPIPE issues with set -e
+        (tail -n +5 "$output_file" | head -5 | while IFS=$'\t' read -r repo npub timestamp reason; do
+            echo "  repo=$repo npub=${npub:0:20}... timestamp=$timestamp"
+        done) || true
+    fi
+    
+    # Show unique repos affected
+    if [[ $count -gt 0 ]]; then
+        echo ""
+        local unique_repos
+        unique_repos=$(tail -n +5 "$output_file" | awk -F'\t' '{print $1}' | sort -u | wc -l)
+        log_info "Unique repositories affected: $unique_repos"
+        
+        echo ""
+        log_info "Repositories with purgatory expiry:"
+        # Use a subshell to avoid SIGPIPE issues with set -e
+        (tail -n +5 "$output_file" | awk -F'\t' '{print $1}' | sort | uniq -c | sort -rn | head -10 | while read -r cnt repo; do
+            echo "  $repo: $cnt expiry events"
+        done) || true
+        
+        local total_repos
+        total_repos=$(tail -n +5 "$output_file" | awk -F'\t' '{print $1}' | sort -u | wc -l)
+        if [[ $total_repos -gt 10 ]]; then
+            echo "  ... and $((total_repos - 10)) more repositories"
+        fi
+    fi
+    
+    # Explicit success exit
+    exit 0
+}
+
+main "$@"
diff --git a/docs/archive/2026-01-relay-ngit-dev-migration/scripts/40-classify-actions.sh b/docs/archive/2026-01-relay-ngit-dev-migration/scripts/40-classify-actions.sh
new file mode 100755
index 0000000..8b61636
--- /dev/null
+++ b/docs/archive/2026-01-relay-ngit-dev-migration/scripts/40-classify-actions.sh
@@ -0,0 +1,662 @@
+#!/usr/bin/env bash
+#
+# 40-classify-actions.sh - Classify repos by migration action required
+#
+# Implements the redesigned classification system (Option B) with user feedback:
+#
+# Tier 1: No Action Required (ready-for-migration.txt)
+#   - Complete in both (prod=cat1, archive=cat1)
+#   - Deleted by user (kind 5 event)
+#   - Empty in prod (prod=cat2, any archive status)
+#   - Archive-only (archive=any, prod=missing)
+#   - Not in prod (purgatory-only, prod=missing)
+#   - Archive ahead (archive has newer git data than prod - GRASP enforced)
+#
+# Tier 2: Action Required (needs-resync.txt)
+#   - Complete in prod, missing from archive (with purgatory context)
+#   - Complete in prod, incomplete in archive AND prod is ahead (with purgatory context)
+#
+# Tier 3: Manual Investigation (manual-review.txt)
+#   - Partial in prod (prod=cat3)
+#   - No-match in prod (prod=cat4)
+#   - Parse failures
+#   - Conflicting states
+#   - Diverged git history (both have unique commits)
+#
+# KEY INSIGHT:
+#   Archive (ngit-grasp) enforces GRASP - git data ALWAYS matches a state event.
+#   If archive has different/newer data than prod, it means:
+#   - A state event authorized those commits at some point
+#   - Archive is actually MORE up-to-date than prod
+#   - Migration should use archive data (it's already correct)
+#
+# Usage: ./40-classify-actions.sh <analysis-dir>
+#
+# Output format: repo | npub | prod_status | archive_status | context | action
+#
+
+set -euo pipefail
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+
+log_info() { echo -e "${BLUE}[INFO]${NC} $*"; }
+log_success() { echo -e "${GREEN}[OK]${NC} $*"; }
+log_warn() { echo -e "${YELLOW}[WARN]${NC} $*"; }
+log_error() { echo -e "${RED}[ERROR]${NC} $*" >&2; }
+
+# Check arguments
+if [[ $# -lt 1 ]]; then
+    echo "Usage: $0 <analysis-dir>"
+    echo "Example: $0 work/migration-analysis-20260123-200701"
+    exit 1
+fi
+
+ANALYSIS_DIR="$1"
+
+# Validate analysis directory
+if [[ ! -d "$ANALYSIS_DIR" ]]; then
+    log_error "Analysis directory not found: $ANALYSIS_DIR"
+    exit 1
+fi
+
+# Define paths
+PROD_DIR="$ANALYSIS_DIR/prod"
+ARCHIVE_DIR="$ANALYSIS_DIR/archive"
+COMPARISON_DIR="$ANALYSIS_DIR/comparison"
+LOGS_DIR="$ANALYSIS_DIR/logs"
+RESULTS_DIR="$ANALYSIS_DIR/results"
+
+# Validate required directories
+for dir in "$PROD_DIR" "$ARCHIVE_DIR" "$COMPARISON_DIR" "$LOGS_DIR"; do
+    if [[ ! -d "$dir" ]]; then
+        log_error "Required directory not found: $dir"
+        exit 1
+    fi
+done
+
+# Create results directory
+mkdir -p "$RESULTS_DIR"
+
+# Output files
+READY_FILE="$RESULTS_DIR/ready-for-migration.txt"
+RESYNC_FILE="$RESULTS_DIR/needs-resync.txt"
+REVIEW_FILE="$RESULTS_DIR/manual-review.txt"
+SUMMARY_FILE="$RESULTS_DIR/summary.txt"
+
+# Temporary files for processing
+TMP_DIR=$(mktemp -d)
+trap 'rm -rf "$TMP_DIR"' EXIT
+
+log_info "Starting classification with revised system (Option B)"
+log_info "Analysis directory: $ANALYSIS_DIR"
+
+# ============================================================================
+# Phase 1: Build lookup tables from source data
+# ============================================================================
+
+log_info "Building lookup tables..."
+
+# Build prod category lookup: repo|npub -> category
+declare -A PROD_CAT
+while IFS='|' read -r repo npub rest || [[ -n "$repo" ]]; do
+    repo="${repo// /}"  # Remove all spaces
+    npub="${npub// /}"  # Remove all spaces
+    [[ -z "$repo" || -z "$npub" ]] && continue
+    PROD_CAT["$repo|$npub"]="cat1"
+done < "$PROD_DIR/category1-complete-match.txt"
+
+while IFS='|' read -r repo npub rest || [[ -n "$repo" ]]; do
+    repo="${repo// /}"
+    npub="${npub// /}"
+    [[ -z "$repo" || -z "$npub" ]] && continue
+    PROD_CAT["$repo|$npub"]="cat2"
+done < "$PROD_DIR/category2-empty-blank.txt"
+
+while IFS='|' read -r repo npub rest || [[ -n "$repo" ]]; do
+    repo="${repo// /}"
+    npub="${npub// /}"
+    [[ -z "$repo" || -z "$npub" ]] && continue
+    PROD_CAT["$repo|$npub"]="cat3"
+done < "$PROD_DIR/category3-partial-match.txt"
+
+while IFS='|' read -r repo npub rest || [[ -n "$repo" ]]; do
+    repo="${repo// /}"
+    npub="${npub// /}"
+    [[ -z "$repo" || -z "$npub" ]] && continue
+    PROD_CAT["$repo|$npub"]="cat4"
+done < "$PROD_DIR/category4-no-match.txt"
+
+log_info "Loaded ${#PROD_CAT[@]} prod entries"
+
+# Build archive category lookup: repo|npub -> category
+declare -A ARCHIVE_CAT
+while IFS='|' read -r repo npub rest; do
+    repo="${repo// /}"
+    npub="${npub// /}"
+    [[ -z "$repo" || -z "$npub" ]] && continue
+    ARCHIVE_CAT["$repo|$npub"]="cat1"
+done < "$ARCHIVE_DIR/category1-complete-match.txt"
+
+while IFS='|' read -r repo npub rest; do
+    repo="${repo// /}"
+    npub="${npub// /}"
+    [[ -z "$repo" || -z "$npub" ]] && continue
+    ARCHIVE_CAT["$repo|$npub"]="cat2"
+done < "$ARCHIVE_DIR/category2-empty-blank.txt"
+
+while IFS='|' read -r repo npub rest; do
+    repo="${repo// /}"
+    npub="${npub// /}"
+    [[ -z "$repo" || -z "$npub" ]] && continue
+    ARCHIVE_CAT["$repo|$npub"]="cat3"
+done < "$ARCHIVE_DIR/category3-partial-match.txt"
+
+while IFS='|' read -r repo npub rest; do
+    repo="${repo// /}"
+    npub="${npub// /}"
+    [[ -z "$repo" || -z "$npub" ]] && continue
+    ARCHIVE_CAT["$repo|$npub"]="cat4"
+done < "$ARCHIVE_DIR/category4-no-match.txt"
+
+log_info "Loaded ${#ARCHIVE_CAT[@]} archive entries"
+
+# Build purgatory lookup: repo|npub -> 1 (if purgatory expired)
+declare -A PURGATORY
+PURGATORY_COUNT=0
+if [[ -f "$LOGS_DIR/purgatory-expired.txt" ]]; then
+    while IFS=$'\t' read -r repo npub timestamp reason || [[ -n "$repo" ]]; do
+        # Skip comments and empty lines
+        [[ "$repo" =~ ^# ]] && continue
+        [[ -z "$repo" || -z "$npub" ]] && continue
+        PURGATORY["$repo|$npub"]=1
+        PURGATORY_COUNT=$((PURGATORY_COUNT + 1))
+    done < "$LOGS_DIR/purgatory-expired.txt"
+fi
+log_info "Loaded $PURGATORY_COUNT purgatory entries"
+
+# Build parse failure lookup: repo|npub -> 1 (if parse failure logged)
+# Parse failures file format: event_id<TAB>kind<TAB>reason<TAB>repo<TAB>npub
+declare -A PARSE_FAIL
+PARSE_FAIL_COUNT=0
+if [[ -f "$LOGS_DIR/parse-failures.txt" ]]; then
+    while IFS=$'\t' read -r event_id kind reason repo npub || [[ -n "$event_id" ]]; do
+        # Skip comments and empty lines
+        [[ "$event_id" =~ ^# ]] && continue
+        [[ -z "$repo" || -z "$npub" ]] && continue
+        PARSE_FAIL["$repo|$npub"]=1
+        PARSE_FAIL_COUNT=$((PARSE_FAIL_COUNT + 1))
+    done < "$LOGS_DIR/parse-failures.txt"
+fi
+log_info "Loaded $PARSE_FAIL_COUNT parse failure entries"
+
+# Build deletion lookup: repo|npub -> 1 (if kind 5 deletion event)
+# Deletions are in NDJSON format with "a" tags like "30617:pubkey_hex:repo"
+# We need to convert hex pubkeys to npub format using nak
+declare -A DELETED
+
+# Helper function to process deletion file (NDJSON format)
+# Extracts unique pubkey_hex:repo pairs and converts to npub
+process_deletions() {
+    local file="$1"
+    [[ ! -f "$file" ]] && return
+    
+    # Extract unique pubkey_hex|repo pairs from NDJSON
+    # Each line is a JSON object, extract "a" tags
+    local pairs
+    pairs=$(jq -r '.tags[] | select(.[0] == "a") | .[1]' "$file" 2>/dev/null | \
+            sed 's/^30617://' | awk -F: '{print $1 "|" $2}' | sort -u)
+    
+    # Get unique hex pubkeys for batch conversion
+    local hex_keys
+    hex_keys=$(echo "$pairs" | cut -d'|' -f1 | sort -u)
+    
+    # Build hex->npub lookup via batch nak call
+    declare -A HEX_TO_NPUB
+    while read -r hex; do
+        [[ -z "$hex" ]] && continue
+        local npub
+        npub=$(nak encode npub "$hex" 2>/dev/null || echo "")
+        [[ -n "$npub" ]] && HEX_TO_NPUB["$hex"]="$npub"
+    done <<< "$hex_keys"
+    
+    # Now process pairs with cached npub values
+    while IFS='|' read -r pubkey_hex repo; do
+        [[ -z "$repo" || -z "$pubkey_hex" ]] && continue
+        local npub="${HEX_TO_NPUB[$pubkey_hex]:-}"
+        [[ -z "$npub" ]] && continue
+        DELETED["$repo|$npub"]=1
+    done <<< "$pairs"
+}
+
+# Process prod and archive deletions
+process_deletions "$PROD_DIR/raw/deletions.json"
+process_deletions "$ARCHIVE_DIR/raw/deletions.json"
+DELETED_COUNT=0
+[[ ${#DELETED[@]} -gt 0 ]] && DELETED_COUNT=${#DELETED[@]}
+log_info "Loaded $DELETED_COUNT deletion entries"
+
+# Build git ancestry lookup: repo|npub -> relationship (archive-ahead, prod-ahead, diverged, etc.)
+# This data comes from 22-compare-git-data.sh which compares actual git commits
+declare -A GIT_ANCESTRY
+GIT_ANCESTRY_COUNT=0
+if [[ -f "$COMPARISON_DIR/git-ancestry.tsv" ]]; then
+    while IFS=$'\t' read -r repo npub relationship details || [[ -n "$repo" ]]; do
+        # Skip header and comments
+        [[ "$repo" == "repo" ]] && continue
+        [[ "$repo" =~ ^# ]] && continue
+        [[ -z "$repo" || -z "$npub" ]] && continue
+        GIT_ANCESTRY["$repo|$npub"]="$relationship"
+        GIT_ANCESTRY_COUNT=$((GIT_ANCESTRY_COUNT + 1))
+    done < "$COMPARISON_DIR/git-ancestry.tsv"
+    log_info "Loaded $GIT_ANCESTRY_COUNT git ancestry entries"
+else
+    log_warn "No git-ancestry.tsv found - will not check if archive is ahead of prod"
+    log_warn "Run 22-compare-git-data.sh to enable archive-ahead detection"
+fi
+
+# ============================================================================
+# Phase 2: Build unique repo list from all sources
+# ============================================================================
+
+log_info "Building unique repo list..."
+
+declare -A ALL_REPOS
+for key in "${!PROD_CAT[@]}"; do
+    ALL_REPOS["$key"]=1
+done
+for key in "${!ARCHIVE_CAT[@]}"; do
+    ALL_REPOS["$key"]=1
+done
+for key in "${!PURGATORY[@]}"; do
+    ALL_REPOS["$key"]=1
+done
+
+log_info "Total unique repos: ${#ALL_REPOS[@]}"
+
+# ============================================================================
+# Phase 3: Classify each repo according to revised decision tree
+# ============================================================================
+
+log_info "Classifying repos..."
+
+# Counters for summary
+declare -A COUNTS
+COUNTS[ready_complete_both]=0
+COUNTS[ready_deleted]=0
+COUNTS[ready_empty_prod]=0
+COUNTS[ready_archive_only]=0
+COUNTS[ready_not_in_prod]=0
+COUNTS[ready_archive_ahead]=0
+COUNTS[resync_missing_archive]=0
+COUNTS[resync_incomplete_archive]=0
+COUNTS[review_partial_prod]=0
+COUNTS[review_nomatch_prod]=0
+COUNTS[review_parse_failure]=0
+COUNTS[review_conflicting]=0
+COUNTS[review_diverged]=0
+
+# Output arrays
+declare -a READY_LINES
+declare -a RESYNC_LINES
+declare -a REVIEW_LINES
+
+# Helper function to get context string
+get_context() {
+    local key="$1"
+    local prod_status="$2"
+    local archive_status="$3"
+    local context=""
+    
+    # Check purgatory
+    if [[ -n "${PURGATORY[$key]:-}" ]]; then
+        context="purgatory-expired"
+    fi
+    
+    # Check parse failure
+    if [[ -n "${PARSE_FAIL[$key]:-}" ]]; then
+        if [[ -n "$context" ]]; then
+            context="$context, parse-failure"
+        else
+            context="parse-failure"
+        fi
+    fi
+    
+    # Add archive context for unexpected states
+    if [[ "$prod_status" == "empty" && "$archive_status" != "missing" && "$archive_status" != "empty" ]]; then
+        if [[ -n "$context" ]]; then
+            context="$context, archive-has-data"
+        else
+            context="archive-has-data"
+        fi
+    fi
+    
+    echo "${context:-none}"
+}
+
+# Helper to convert category to human-readable status
+cat_to_status() {
+    case "$1" in
+        cat1) echo "complete" ;;
+        cat2) echo "empty" ;;
+        cat3) echo "partial" ;;
+        cat4) echo "no-match" ;;
+        missing) echo "missing" ;;
+        *) echo "$1" ;;
+    esac
+}
+
+LOOP_COUNT=0
+for key in "${!ALL_REPOS[@]}"; do
+    LOOP_COUNT=$((LOOP_COUNT + 1))
+    [[ $((LOOP_COUNT % 100)) -eq 0 ]] && log_info "Processed $LOOP_COUNT repos..."
+    IFS='|' read -r repo npub <<< "$key"
+    
+    prod_cat="${PROD_CAT[$key]:-missing}"
+    archive_cat="${ARCHIVE_CAT[$key]:-missing}"
+    prod_status=$(cat_to_status "$prod_cat")
+    archive_status=$(cat_to_status "$archive_cat")
+    
+    # Decision tree implementation
+    
+    # 1. Is there a kind 5 deletion event?
+    if [[ -n "${DELETED[$key]:-}" ]]; then
+        context=$(get_context "$key" "$prod_status" "$archive_status")
+        READY_LINES+=("$repo | $npub | $prod_status | $archive_status | $context | deleted by user")
+        COUNTS[ready_deleted]=$((COUNTS[ready_deleted] + 1))
+        continue
+    fi
+    
+    # 2. What is the prod status?
+    case "$prod_cat" in
+        missing)
+            # Not in prod
+            if [[ "$archive_cat" != "missing" ]]; then
+                # In archive but not in prod -> no action (archive-only)
+                context=$(get_context "$key" "$prod_status" "$archive_status")
+                READY_LINES+=("$repo | $npub | $prod_status | $archive_status | $context | archive-only (not in prod)")
+                COUNTS[ready_archive_only]=$((COUNTS[ready_archive_only] + 1))
+            elif [[ -n "${PURGATORY[$key]:-}" ]]; then
+                # Purgatory only, not in prod -> no action
+                context="purgatory-expired"
+                READY_LINES+=("$repo | $npub | $prod_status | $archive_status | $context | purgatory-only (not in prod)")
+                COUNTS[ready_not_in_prod]=$((COUNTS[ready_not_in_prod] + 1))
+            fi
+            # Otherwise skip (not a real repo - no data anywhere)
+            ;;
+            
+        cat2)
+            # Empty in prod -> ALWAYS no action required
+            context=$(get_context "$key" "$prod_status" "$archive_status")
+            READY_LINES+=("$repo | $npub | $prod_status | $archive_status | $context | empty in prod (user never pushed)")
+            COUNTS[ready_empty_prod]=$((COUNTS[ready_empty_prod] + 1))
+            ;;
+            
+        cat1)
+            # Complete in prod
+            if [[ "$archive_cat" == "cat1" ]]; then
+                # Complete in both -> no action
+                context=$(get_context "$key" "$prod_status" "$archive_status")
+                READY_LINES+=("$repo | $npub | $prod_status | $archive_status | $context | complete in both")
+                COUNTS[ready_complete_both]=$((COUNTS[ready_complete_both] + 1))
+            else
+                # Complete in prod, missing/incomplete in archive
+                # Check for parse failure - if so, needs manual review
+                if [[ -n "${PARSE_FAIL[$key]:-}" ]]; then
+                    context=$(get_context "$key" "$prod_status" "$archive_status")
+                    REVIEW_LINES+=("$repo | $npub | $prod_status | $archive_status | $context | complete in prod with parse failure")
+                    COUNTS[review_parse_failure]=$((COUNTS[review_parse_failure] + 1))
+                else
+                    # Check git ancestry to see if archive is actually ahead
+                    git_relationship="${GIT_ANCESTRY[$key]:-unknown}"
+                    
+                    if [[ "$git_relationship" == "archive-ahead" || "$git_relationship" == "in-sync" ]]; then
+                        # Archive has newer/same git data - this is GOOD
+                        # Archive's git data was authorized by a state event (GRASP enforced)
+                        context=$(get_context "$key" "$prod_status" "$archive_status")
+                        if [[ -n "$context" && "$context" != "none" ]]; then
+                            context="$context, git=$git_relationship"
+                        else
+                            context="git=$git_relationship"
+                        fi
+                        READY_LINES+=("$repo | $npub | $prod_status | $archive_status | $context | archive ahead (use archive data)")
+                        COUNTS[ready_archive_ahead]=$((COUNTS[ready_archive_ahead] + 1))
+                    elif [[ "$git_relationship" == "diverged" ]]; then
+                        # Git histories diverged - needs manual review
+                        context=$(get_context "$key" "$prod_status" "$archive_status")
+                        if [[ -n "$context" && "$context" != "none" ]]; then
+                            context="$context, git=diverged"
+                        else
+                            context="git=diverged"
+                        fi
+                        REVIEW_LINES+=("$repo | $npub | $prod_status | $archive_status | $context | git histories diverged (manual review)")
+                        COUNTS[review_diverged]=$((COUNTS[review_diverged] + 1))
+                    else
+                        # prod-ahead, archive-only, prod-only, both-empty, or unknown
+                        # These need resync - include purgatory context
+                        context=$(get_context "$key" "$prod_status" "$archive_status")
+                        if [[ "$git_relationship" != "unknown" ]]; then
+                            if [[ -n "$context" && "$context" != "none" ]]; then
+                                context="$context, git=$git_relationship"
+                            else
+                                context="git=$git_relationship"
+                            fi
+                        fi
+                        if [[ "$archive_cat" == "missing" ]]; then
+                            RESYNC_LINES+=("$repo | $npub | $prod_status | $archive_status | $context | trigger re-sync to archive")
+                            COUNTS[resync_missing_archive]=$((COUNTS[resync_missing_archive] + 1))
+                        else
+                            RESYNC_LINES+=("$repo | $npub | $prod_status | $archive_status | $context | trigger re-sync (archive incomplete)")
+                            COUNTS[resync_incomplete_archive]=$((COUNTS[resync_incomplete_archive] + 1))
+                        fi
+                    fi
+                fi
+            fi
+            ;;
+            
+        cat3)
+            # Partial in prod -> ALWAYS manual investigation
+            context=$(get_context "$key" "$prod_status" "$archive_status")
+            REVIEW_LINES+=("$repo | $npub | $prod_status | $archive_status | $context | partial in prod (investigate git data)")
+            COUNTS[review_partial_prod]=$((COUNTS[review_partial_prod] + 1))
+            ;;
+            
+        cat4)
+            # No-match in prod -> ALWAYS manual investigation
+            context=$(get_context "$key" "$prod_status" "$archive_status")
+            REVIEW_LINES+=("$repo | $npub | $prod_status | $archive_status | $context | no-match in prod (git corruption)")
+            COUNTS[review_nomatch_prod]=$((COUNTS[review_nomatch_prod] + 1))
+            ;;
+    esac
+done
+
+# ============================================================================
+# Phase 4: Write output files
+# ============================================================================
+
+log_info "Writing output files..."
+
+TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%S+00:00")
+
+# Write ready-for-migration.txt
+{
+    echo "# Ready for Migration - No action required"
+    echo "# Generated: $TIMESTAMP"
+    echo "# Format: repo | npub | prod_status | archive_status | context | reason"
+    echo "#"
+    for line in "${READY_LINES[@]}"; do
+        echo "$line"
+    done
+} > "$READY_FILE"
+
+# Write needs-resync.txt
+{
+    echo "# Needs Re-sync - Action required"
+    echo "# Generated: $TIMESTAMP"
+    echo "# Format: repo | npub | prod_status | archive_status | context | action"
+    echo "#"
+    echo "# Context meanings:"
+    echo "#   purgatory-expired = archive tried to sync but failed (30min timeout)"
+    echo "#   none = archive never tried or announcement missing"
+    echo "#"
+    for line in "${RESYNC_LINES[@]}"; do
+        echo "$line"
+    done
+} > "$RESYNC_FILE"
+
+# Write manual-review.txt
+{
+    echo "# Manual Review Required - Investigation needed"
+    echo "# Generated: $TIMESTAMP"
+    echo "# Format: repo | npub | prod_status | archive_status | context | reason"
+    echo "#"
+    for line in "${REVIEW_LINES[@]}"; do
+        echo "$line"
+    done
+} > "$REVIEW_FILE"
+
+# ============================================================================
+# Phase 5: Generate summary
+# ============================================================================
+
+log_info "Generating summary..."
+
+TOTAL_READY="${#READY_LINES[@]}"
+TOTAL_RESYNC="${#RESYNC_LINES[@]}"
+TOTAL_REVIEW="${#REVIEW_LINES[@]}"
+TOTAL=$((TOTAL_READY + TOTAL_RESYNC + TOTAL_REVIEW))
+
+# Calculate percentages
+if [[ $TOTAL -gt 0 ]]; then
+    PCT_READY=$(awk "BEGIN {printf \"%.1f\", ($TOTAL_READY / $TOTAL) * 100}")
+    PCT_RESYNC=$(awk "BEGIN {printf \"%.1f\", ($TOTAL_RESYNC / $TOTAL) * 100}")
+    PCT_REVIEW=$(awk "BEGIN {printf \"%.1f\", ($TOTAL_REVIEW / $TOTAL) * 100}")
+else
+    PCT_READY="0.0"
+    PCT_RESYNC="0.0"
+    PCT_REVIEW="0.0"
+fi
+
+{
+    echo "# Migration Classification Summary"
+    echo "Generated: $TIMESTAMP"
+    echo "Analysis Directory: $ANALYSIS_DIR"
+    echo ""
+    echo "## Overview"
+    echo ""
+    echo "| Category | Count | Percentage |"
+    echo "|----------|-------|------------|"
+    echo "| Ready for Migration | $TOTAL_READY | $PCT_READY% |"
+    echo "| Needs Re-sync | $TOTAL_RESYNC | $PCT_RESYNC% |"
+    echo "| Manual Review | $TOTAL_REVIEW | $PCT_REVIEW% |"
+    echo "| **Total** | **$TOTAL** | **100%** |"
+    echo ""
+    echo "## Tier 1: Ready for Migration ($TOTAL_READY repos)"
+    echo ""
+    echo "These repositories are ready for migration or don't need migration:"
+    echo ""
+    echo "| Reason | Count |"
+    echo "|--------|-------|"
+    echo "| complete in both prod and archive | ${COUNTS[ready_complete_both]} |"
+    echo "| archive ahead (has newer git data) | ${COUNTS[ready_archive_ahead]} |"
+    echo "| deleted by user | ${COUNTS[ready_deleted]} |"
+    echo "| empty in prod (user never pushed) | ${COUNTS[ready_empty_prod]} |"
+    echo "| archive-only (not in prod) | ${COUNTS[ready_archive_only]} |"
+    echo "| purgatory-only (not in prod) | ${COUNTS[ready_not_in_prod]} |"
+    echo ""
+    echo "## Tier 2: Needs Re-sync ($TOTAL_RESYNC repos)"
+    echo ""
+    echo "These repositories need re-sync to archive before migration:"
+    echo ""
+    echo "| Reason | Count | Action |"
+    echo "|--------|-------|--------|"
+    echo "| complete in prod, missing from archive | ${COUNTS[resync_missing_archive]} | trigger re-sync |"
+    echo "| complete in prod, incomplete in archive | ${COUNTS[resync_incomplete_archive]} | trigger re-sync |"
+    echo ""
+    echo "### Purgatory Context"
+    echo ""
+    echo "Repos in needs-resync.txt include purgatory context:"
+    echo "- **purgatory-expired**: Archive tried to sync but failed (30min timeout)"
+    echo "- **none**: Archive never tried or announcement missing"
+    echo ""
+    echo "## Tier 3: Manual Review ($TOTAL_REVIEW repos)"
+    echo ""
+    echo "These repositories require human investigation:"
+    echo ""
+    echo "| Reason | Count |"
+    echo "|--------|-------|"
+    echo "| partial in prod (cat3) | ${COUNTS[review_partial_prod]} |"
+    echo "| no-match in prod (cat4) | ${COUNTS[review_nomatch_prod]} |"
+    echo "| complete in prod with parse failure | ${COUNTS[review_parse_failure]} |"
+    echo "| git histories diverged | ${COUNTS[review_diverged]} |"
+    echo ""
+    echo "## Input Data Summary"
+    echo ""
+    echo "### Prod Categories"
+    echo "- Category 1 (complete): $(wc -l < "$PROD_DIR/category1-complete-match.txt")"
+    echo "- Category 2 (empty): $(wc -l < "$PROD_DIR/category2-empty-blank.txt")"
+    echo "- Category 3 (partial): $(wc -l < "$PROD_DIR/category3-partial-match.txt")"
+    echo "- Category 4 (no match): $(wc -l < "$PROD_DIR/category4-no-match.txt")"
+    echo ""
+    echo "### Archive Categories"
+    echo "- Category 1 (complete): $(wc -l < "$ARCHIVE_DIR/category1-complete-match.txt")"
+    echo "- Category 2 (empty): $(wc -l < "$ARCHIVE_DIR/category2-empty-blank.txt")"
+    echo "- Category 3 (partial): $(wc -l < "$ARCHIVE_DIR/category3-partial-match.txt")"
+    echo "- Category 4 (no match): $(wc -l < "$ARCHIVE_DIR/category4-no-match.txt")"
+    echo ""
+    echo "### Logs"
+    echo "- Parse failures: $(grep -c -v '^#' "$LOGS_DIR/parse-failures.txt" 2>/dev/null || echo 0)"
+    echo "- Purgatory expired: $(grep -c -v '^#' "$LOGS_DIR/purgatory-expired.txt" 2>/dev/null || echo 0)"
+    echo ""
+    echo "## Output Files"
+    echo ""
+    echo "- \`results/ready-for-migration.txt\` - $TOTAL_READY repos ready for migration"
+    echo "- \`results/needs-resync.txt\` - $TOTAL_RESYNC repos needing re-sync"
+    echo "- \`results/manual-review.txt\` - $TOTAL_REVIEW repos needing investigation"
+    echo "- \`results/summary.txt\` - This summary file"
+    echo ""
+    echo "## Recommended Next Steps"
+    echo ""
+    echo "1. **Review needs-resync.txt** - Trigger re-sync for these repos"
+    echo "2. **Review manual-review.txt** - Investigate unusual states"
+    echo "3. **Verify ready-for-migration.txt** - Spot-check a few repos"
+    echo "4. **Plan migration window** - Schedule cutover when action items resolved"
+} > "$SUMMARY_FILE"
+
+# ============================================================================
+# Phase 6: Print summary to console
+# ============================================================================
+
+echo ""
+log_success "Classification complete!"
+echo ""
+echo "=== Summary ==="
+echo "Ready for Migration: $TOTAL_READY ($PCT_READY%)"
+echo "  - Complete in both: ${COUNTS[ready_complete_both]}"
+echo "  - Archive ahead: ${COUNTS[ready_archive_ahead]}"
+echo "  - Deleted by user: ${COUNTS[ready_deleted]}"
+echo "  - Empty in prod: ${COUNTS[ready_empty_prod]}"
+echo "  - Archive-only: ${COUNTS[ready_archive_only]}"
+echo "  - Purgatory-only: ${COUNTS[ready_not_in_prod]}"
+echo ""
+echo "Needs Re-sync: $TOTAL_RESYNC ($PCT_RESYNC%)"
+echo "  - Missing from archive: ${COUNTS[resync_missing_archive]}"
+echo "  - Incomplete in archive: ${COUNTS[resync_incomplete_archive]}"
+echo ""
+echo "Manual Review: $TOTAL_REVIEW ($PCT_REVIEW%)"
+echo "  - Partial in prod: ${COUNTS[review_partial_prod]}"
+echo "  - No-match in prod: ${COUNTS[review_nomatch_prod]}"
+echo "  - Parse failures: ${COUNTS[review_parse_failure]}"
+echo "  - Git diverged: ${COUNTS[review_diverged]}"
+echo ""
+echo "Total: $TOTAL repos"
+echo ""
+echo "Output files:"
+echo "  $READY_FILE"
+echo "  $RESYNC_FILE"
+echo "  $REVIEW_FILE"
+echo "  $SUMMARY_FILE"
diff --git a/docs/archive/2026-01-relay-ngit-dev-migration/scripts/run-migration-analysis.sh b/docs/archive/2026-01-relay-ngit-dev-migration/scripts/run-migration-analysis.sh
new file mode 100755
index 0000000..acc5e44
--- /dev/null
+++ b/docs/archive/2026-01-relay-ngit-dev-migration/scripts/run-migration-analysis.sh
@@ -0,0 +1,779 @@
+#!/usr/bin/env bash
+#
+# run-migration-analysis.sh - Orchestrate the complete GRASP relay to ngit-grasp migration analysis
+#
+# This script runs all 5 phases of the migration analysis pipeline in sequence,
+# with proper error handling, progress reporting, and timing information.
+#
+# QUICK START:
+#   # Basic usage (local analysis only - Phases 1, 3, 5)
+#   ./run-migration-analysis.sh --prod-relay wss://relay.ngit.dev --archive-relay wss://archive.relay.ngit.dev
+#
+#   # Full analysis including git sync check (requires VPS access)
+#   ./run-migration-analysis.sh \
+#     --prod-relay wss://relay.ngit.dev \
+#     --archive-relay wss://archive.relay.ngit.dev \
+#     --prod-git /var/lib/grasp-relay/git \
+#     --archive-git /var/lib/ngit-grasp/git
+#
+# USAGE:
+#   ./run-migration-analysis.sh [options]
+#
+# REQUIRED OPTIONS:
+#   --prod-relay <url>      Production relay WebSocket URL (e.g., wss://relay.ngit.dev)
+#   --archive-relay <url>   Archive relay WebSocket URL (e.g., wss://archive.relay.ngit.dev)
+#
+# OPTIONAL OPTIONS:
+#   --prod-git <path>       Git base directory for prod (enables Phase 2)
+#   --archive-git <path>    Git base directory for archive (enables Phase 2)
+#   --service <name>        Systemd service name for log extraction (enables Phase 4)
+#   --output <dir>          Output directory (default: work/migration-analysis-YYYYMMDD-HHMM)
+#   --since <date>          Start date for log extraction (default: 30 days ago)
+#   --until <date>          End date for log extraction (default: now)
+#
+# PHASE CONTROL:
+#   --skip-phase-1          Skip event fetching (use existing data)
+#   --skip-phase-2          Skip git sync check (use existing data)
+#   --skip-phase-3          Skip categorization (use existing data)
+#   --skip-phase-4          Skip log extraction (use existing data)
+#   --skip-phase-5          Skip final classification
+#   --only-phase-N          Run only phase N (1-5)
+#   --from-phase-N          Start from phase N (skip earlier phases)
+#
+# OTHER OPTIONS:
+#   --dry-run               Show what would be executed without running
+#   --continue-on-error     Continue to next phase even if current phase fails
+#   --help                  Show this help message
+#
+# PHASES:
+#   Phase 1: Fetch events from both relays (~30s each, local)
+#   Phase 2: Check git sync status (~20 min each, requires VPS)
+#   Phase 3: Categorize and compare results (fast, local)
+#   Phase 4: Extract logs from systemd (requires VPS)
+#   Phase 5: Final classification (fast, local)
+#
+# EXAMPLES:
+#   # Dry run to see what would happen
+#   ./run-migration-analysis.sh --prod-relay wss://relay.ngit.dev --archive-relay wss://archive.relay.ngit.dev --dry-run
+#
+#   # Run only Phase 1 (fetch events)
+#   ./run-migration-analysis.sh --prod-relay wss://relay.ngit.dev --archive-relay wss://archive.relay.ngit.dev --only-phase-1
+#
+#   # Resume from Phase 3 using existing Phase 1-2 data
+#   ./run-migration-analysis.sh --prod-relay wss://relay.ngit.dev --archive-relay wss://archive.relay.ngit.dev --from-phase-3 --output work/migration-analysis-20260122-1430
+#
+#   # Full analysis on VPS with all features
+#   ./run-migration-analysis.sh \
+#     --prod-relay wss://relay.ngit.dev \
+#     --archive-relay wss://archive.relay.ngit.dev \
+#     --prod-git /var/lib/grasp-relay/git \
+#     --archive-git /var/lib/ngit-grasp/git \
+#     --service ngit-grasp.service
+#
+# SEE ALSO:
+#   docs/how-to/migrate-to-ngit-grasp.md - Full migration guide
+#
+
+set -euo pipefail
+
+# Get script directory for finding other scripts
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Colors for output (disabled if not a terminal)
+if [[ -t 1 ]]; then
+    RED='\033[0;31m'
+    GREEN='\033[0;32m'
+    YELLOW='\033[0;33m'
+    BLUE='\033[0;34m'
+    CYAN='\033[0;36m'
+    BOLD='\033[1m'
+    NC='\033[0m'
+else
+    RED=''
+    GREEN=''
+    YELLOW=''
+    BLUE=''
+    CYAN=''
+    BOLD=''
+    NC=''
+fi
+
+# Logging functions
+log_header() {
+    echo ""
+    echo -e "${BOLD}${CYAN}════════════════════════════════════════════════════════════════${NC}"
+    echo -e "${BOLD}${CYAN}  $*${NC}"
+    echo -e "${BOLD}${CYAN}════════════════════════════════════════════════════════════════${NC}"
+    echo ""
+}
+
+log_phase() {
+    echo ""
+    echo -e "${BOLD}${BLUE}┌──────────────────────────────────────────────────────────────┐${NC}"
+    echo -e "${BOLD}${BLUE}│  $*${NC}"
+    echo -e "${BOLD}${BLUE}└──────────────────────────────────────────────────────────────┘${NC}"
+}
+
+log_info() {
+    echo -e "${BLUE}[INFO]${NC} $*" >&2
+}
+
+log_success() {
+    echo -e "${GREEN}[OK]${NC} $*" >&2
+}
+
+log_warn() {
+    echo -e "${YELLOW}[WARN]${NC} $*" >&2
+}
+
+log_error() {
+    echo -e "${RED}[ERROR]${NC} $*" >&2
+}
+
+log_step() {
+    echo -e "${CYAN}  →${NC} $*" >&2
+}
+
+# Default values
+PROD_RELAY=""
+ARCHIVE_RELAY=""
+PROD_GIT=""
+ARCHIVE_GIT=""
+SERVICE_NAME=""
+OUTPUT_DIR=""
+DRY_RUN=false
+CONTINUE_ON_ERROR=false
+LOG_SINCE=""
+LOG_UNTIL=""
+
+# Phase control
+SKIP_PHASE_1=false
+SKIP_PHASE_2=false
+SKIP_PHASE_3=false
+SKIP_PHASE_4=false
+SKIP_PHASE_5=false
+ONLY_PHASE=""
+FROM_PHASE=""
+
+# Timing
+declare -A PHASE_TIMES
+
+usage() {
+    head -73 "$0" | tail -n +3 | sed 's/^# //' | sed 's/^#//'
+    exit 0
+}
+
+# Parse command line arguments
+parse_args() {
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --prod-relay)
+                PROD_RELAY="$2"
+                shift 2
+                ;;
+            --archive-relay)
+                ARCHIVE_RELAY="$2"
+                shift 2
+                ;;
+            --prod-git)
+                PROD_GIT="$2"
+                shift 2
+                ;;
+            --archive-git)
+                ARCHIVE_GIT="$2"
+                shift 2
+                ;;
+            --service)
+                SERVICE_NAME="$2"
+                shift 2
+                ;;
+            --output)
+                OUTPUT_DIR="$2"
+                shift 2
+                ;;
+            --skip-phase-1)
+                SKIP_PHASE_1=true
+                shift
+                ;;
+            --skip-phase-2)
+                SKIP_PHASE_2=true
+                shift
+                ;;
+            --skip-phase-3)
+                SKIP_PHASE_3=true
+                shift
+                ;;
+            --skip-phase-4)
+                SKIP_PHASE_4=true
+                shift
+                ;;
+            --skip-phase-5)
+                SKIP_PHASE_5=true
+                shift
+                ;;
+            --only-phase-1|--only-phase-2|--only-phase-3|--only-phase-4|--only-phase-5)
+                ONLY_PHASE="${1#--only-phase-}"
+                shift
+                ;;
+            --from-phase-1|--from-phase-2|--from-phase-3|--from-phase-4|--from-phase-5)
+                FROM_PHASE="${1#--from-phase-}"
+                shift
+                ;;
+            --dry-run)
+                DRY_RUN=true
+                shift
+                ;;
+            --continue-on-error)
+                CONTINUE_ON_ERROR=true
+                shift
+                ;;
+            --since)
+                LOG_SINCE="$2"
+                shift 2
+                ;;
+            --until)
+                LOG_UNTIL="$2"
+                shift 2
+                ;;
+            --help|-h)
+                usage
+                ;;
+            *)
+                log_error "Unknown option: $1"
+                echo "Use --help for usage information."
+                exit 1
+                ;;
+        esac
+    done
+}
+
+# Validate required arguments
+validate_args() {
+    local errors=0
+    
+    if [[ -z "$PROD_RELAY" ]]; then
+        log_error "Missing required option: --prod-relay"
+        errors=1
+    fi
+    
+    if [[ -z "$ARCHIVE_RELAY" ]]; then
+        log_error "Missing required option: --archive-relay"
+        errors=1
+    fi
+    
+    # Validate relay URLs
+    if [[ -n "$PROD_RELAY" && ! "$PROD_RELAY" =~ ^wss?:// ]]; then
+        log_error "Invalid prod relay URL: $PROD_RELAY (must start with ws:// or wss://)"
+        errors=1
+    fi
+    
+    if [[ -n "$ARCHIVE_RELAY" && ! "$ARCHIVE_RELAY" =~ ^wss?:// ]]; then
+        log_error "Invalid archive relay URL: $ARCHIVE_RELAY (must start with ws:// or wss://)"
+        errors=1
+    fi
+    
+    # Validate git paths if provided
+    if [[ -n "$PROD_GIT" && ! -d "$PROD_GIT" ]]; then
+        log_warn "Prod git directory not found: $PROD_GIT"
+        log_warn "Phase 2 will fail unless running on VPS with access to this path."
+    fi
+    
+    if [[ -n "$ARCHIVE_GIT" && ! -d "$ARCHIVE_GIT" ]]; then
+        log_warn "Archive git directory not found: $ARCHIVE_GIT"
+        log_warn "Phase 2 will fail unless running on VPS with access to this path."
+    fi
+    
+    if [[ $errors -eq 1 ]]; then
+        echo ""
+        echo "Use --help for usage information."
+        exit 1
+    fi
+}
+
+# Check prerequisites
+check_prerequisites() {
+    local missing=0
+    
+    log_info "Checking prerequisites..."
+    
+    # Required tools
+    for tool in git nak jq awk sort; do
+        if command -v "$tool" &> /dev/null; then
+            log_step "$tool: found"
+        else
+            log_error "$tool: NOT FOUND"
+            missing=1
+        fi
+    done
+    
+    # Optional tools
+    if command -v journalctl &> /dev/null; then
+        log_step "journalctl: found (Phase 4 available)"
+    else
+        log_step "journalctl: not found (Phase 4 will be skipped)"
+        SKIP_PHASE_4=true
+    fi
+    
+    if [[ $missing -eq 1 ]]; then
+        log_error "Missing required tools. Install them and try again."
+        exit 1
+    fi
+    
+    # Check scripts exist
+    for script in 01-fetch-events.sh 10-check-git-sync.sh 20-categorize.sh 21-compare-relays.sh 22-compare-git-data.sh 30-extract-parse-failures.sh 31-extract-purgatory-expiry.sh 40-classify-actions.sh; do
+        if [[ ! -x "$SCRIPT_DIR/$script" ]]; then
+            log_error "Script not found or not executable: $SCRIPT_DIR/$script"
+            missing=1
+        fi
+    done
+    
+    if [[ $missing -eq 1 ]]; then
+        exit 1
+    fi
+    
+    log_success "All prerequisites satisfied"
+}
+
+# Determine which phases to run
+determine_phases() {
+    # Handle --only-phase-N
+    if [[ -n "$ONLY_PHASE" ]]; then
+        for i in 1 2 3 4 5; do
+            if [[ "$i" != "$ONLY_PHASE" ]]; then
+                eval "SKIP_PHASE_$i=true"
+            fi
+        done
+    fi
+    
+    # Handle --from-phase-N
+    if [[ -n "$FROM_PHASE" ]]; then
+        for i in 1 2 3 4 5; do
+            if [[ "$i" -lt "$FROM_PHASE" ]]; then
+                eval "SKIP_PHASE_$i=true"
+            fi
+        done
+    fi
+    
+    # Auto-skip Phase 2 if git paths not provided
+    if [[ -z "$PROD_GIT" && -z "$ARCHIVE_GIT" ]]; then
+        if [[ "$SKIP_PHASE_2" != "true" ]]; then
+            log_warn "No git paths provided. Phase 2 (git sync check) will be skipped."
+            log_warn "Use --prod-git and --archive-git to enable Phase 2."
+            SKIP_PHASE_2=true
+        fi
+    fi
+    
+    # Auto-skip Phase 4 if service not provided
+    if [[ -z "$SERVICE_NAME" ]]; then
+        if [[ "$SKIP_PHASE_4" != "true" ]]; then
+            log_warn "No service name provided. Phase 4 (log extraction) will be skipped."
+            log_warn "Use --service to enable Phase 4."
+            SKIP_PHASE_4=true
+        fi
+    fi
+}
+
+# Setup output directory
+setup_output_dir() {
+    if [[ -z "$OUTPUT_DIR" ]]; then
+        OUTPUT_DIR="work/migration-analysis-$(date +%Y%m%d-%H%M)"
+    fi
+    
+    log_info "Output directory: $OUTPUT_DIR"
+    
+    if [[ "$DRY_RUN" == "true" ]]; then
+        log_info "[DRY RUN] Would create directory structure"
+        return
+    fi
+    
+    mkdir -p "$OUTPUT_DIR"/{prod/raw,archive/raw,comparison,logs,results}
+    
+    # Save configuration
+    cat > "$OUTPUT_DIR/config.txt" << EOF
+# Migration Analysis Configuration
+# Generated: $(date -Iseconds)
+
+PROD_RELAY=$PROD_RELAY
+ARCHIVE_RELAY=$ARCHIVE_RELAY
+PROD_GIT=$PROD_GIT
+ARCHIVE_GIT=$ARCHIVE_GIT
+SERVICE_NAME=$SERVICE_NAME
+OUTPUT_DIR=$OUTPUT_DIR
+EOF
+    
+    log_success "Created output directory structure"
+}
+
+# Run a phase with timing and error handling
+run_phase() {
+    local phase_num="$1"
+    local phase_name="$2"
+    shift 2
+    local cmd=("$@")
+    
+    local skip_var="SKIP_PHASE_$phase_num"
+    if [[ "${!skip_var}" == "true" ]]; then
+        log_phase "Phase $phase_num: $phase_name [SKIPPED]"
+        return 0
+    fi
+    
+    log_phase "Phase $phase_num: $phase_name"
+    
+    if [[ "$DRY_RUN" == "true" ]]; then
+        log_info "[DRY RUN] Would execute:"
+        for c in "${cmd[@]}"; do
+            echo "  $c"
+        done
+        return 0
+    fi
+    
+    local start_time
+    start_time=$(date +%s)
+    
+    local exit_code=0
+    
+    # Execute the command(s)
+    for c in "${cmd[@]}"; do
+        log_step "Running: $c"
+        if ! eval "$c"; then
+            exit_code=1
+            if [[ "$CONTINUE_ON_ERROR" == "true" ]]; then
+                log_warn "Command failed, continuing due to --continue-on-error"
+            else
+                log_error "Command failed"
+                break
+            fi
+        fi
+    done
+    
+    local end_time
+    end_time=$(date +%s)
+    local duration=$((end_time - start_time))
+    PHASE_TIMES[$phase_num]=$duration
+    
+    if [[ $exit_code -eq 0 ]]; then
+        log_success "Phase $phase_num completed in ${duration}s"
+    else
+        log_error "Phase $phase_num failed after ${duration}s"
+        if [[ "$CONTINUE_ON_ERROR" != "true" ]]; then
+            return 1
+        fi
+    fi
+    
+    return $exit_code
+}
+
+# Phase 1: Fetch events
+run_phase_1() {
+    local cmds=()
+    
+    # Fetch from prod relay
+    cmds+=("'$SCRIPT_DIR/01-fetch-events.sh' '$PROD_RELAY' '$OUTPUT_DIR/prod'")
+    
+    # Fetch from archive relay
+    cmds+=("'$SCRIPT_DIR/01-fetch-events.sh' '$ARCHIVE_RELAY' '$OUTPUT_DIR/archive'")
+    
+    run_phase 1 "Fetch Events (~30s each)" "${cmds[@]}"
+}
+
+# Phase 2: Git sync check
+run_phase_2() {
+    local cmds=()
+    
+    if [[ -n "$PROD_GIT" ]]; then
+        cmds+=("'$SCRIPT_DIR/10-check-git-sync.sh' '$OUTPUT_DIR/prod/raw/state-events.json' '$PROD_GIT' '$OUTPUT_DIR/prod' --categorize")
+    else
+        log_warn "Skipping prod git sync check (no --prod-git provided)"
+    fi
+    
+    if [[ -n "$ARCHIVE_GIT" ]]; then
+        cmds+=("'$SCRIPT_DIR/10-check-git-sync.sh' '$OUTPUT_DIR/archive/raw/state-events.json' '$ARCHIVE_GIT' '$OUTPUT_DIR/archive' --categorize")
+    else
+        log_warn "Skipping archive git sync check (no --archive-git provided)"
+    fi
+    
+    if [[ ${#cmds[@]} -eq 0 ]]; then
+        log_warn "No git paths provided, skipping Phase 2"
+        return 0
+    fi
+    
+    run_phase 2 "Git Sync Check (~20 min each)" "${cmds[@]}"
+}
+
+# Phase 3: Categorize and compare
+run_phase_3() {
+    local cmds=()
+    
+    # Check if we have git-sync-status.tsv files (from Phase 2)
+    # If not, we can't run categorization
+    local has_prod_sync=false
+    local has_archive_sync=false
+    
+    if [[ -f "$OUTPUT_DIR/prod/git-sync-status.tsv" ]]; then
+        has_prod_sync=true
+    fi
+    
+    if [[ -f "$OUTPUT_DIR/archive/git-sync-status.tsv" ]]; then
+        has_archive_sync=true
+    fi
+    
+    # Run categorization if we have sync data but no category files
+    if [[ "$has_prod_sync" == "true" && ! -f "$OUTPUT_DIR/prod/category1-complete-match.txt" ]]; then
+        cmds+=("'$SCRIPT_DIR/20-categorize.sh' '$OUTPUT_DIR/prod/git-sync-status.tsv' '$OUTPUT_DIR/prod'")
+    fi
+    
+    if [[ "$has_archive_sync" == "true" && ! -f "$OUTPUT_DIR/archive/category1-complete-match.txt" ]]; then
+        cmds+=("'$SCRIPT_DIR/20-categorize.sh' '$OUTPUT_DIR/archive/git-sync-status.tsv' '$OUTPUT_DIR/archive'")
+    fi
+    
+    # Run comparison if we have category files
+    if [[ -f "$OUTPUT_DIR/prod/category1-complete-match.txt" && -f "$OUTPUT_DIR/archive/category1-complete-match.txt" ]]; then
+        cmds+=("'$SCRIPT_DIR/21-compare-relays.sh' '$OUTPUT_DIR/prod' '$OUTPUT_DIR/archive' '$OUTPUT_DIR/comparison'")
+    else
+        log_warn "Missing category files for comparison."
+        log_warn "Phase 2 must complete successfully before Phase 3 can compare relays."
+        
+        # Create placeholder comparison files if they don't exist
+        if [[ "$DRY_RUN" != "true" ]]; then
+            mkdir -p "$OUTPUT_DIR/comparison"
+            for f in complete-in-both.txt complete-prod-missing-archive.txt complete-prod-incomplete-archive.txt incomplete-in-both.txt in-archive-not-prod.txt; do
+                if [[ ! -f "$OUTPUT_DIR/comparison/$f" ]]; then
+                    echo "# Placeholder - Phase 2 data not available" > "$OUTPUT_DIR/comparison/$f"
+                fi
+            done
+            echo "# Comparison not available - Phase 2 data missing" > "$OUTPUT_DIR/comparison/summary.txt"
+        fi
+    fi
+    
+    if [[ ${#cmds[@]} -eq 0 ]]; then
+        log_warn "No categorization or comparison needed (already done or missing input)"
+        return 0
+    fi
+    
+    run_phase 3 "Categorize & Compare (fast)" "${cmds[@]}"
+    
+    # Phase 3c: Compare git data between relays (requires git paths)
+    # This determines if archive is ahead of prod for repos with mismatched state
+    if [[ -n "$PROD_GIT" && -n "$ARCHIVE_GIT" ]]; then
+        # Build list of repos to compare: those where prod=complete but archive is not
+        local repos_to_compare="$OUTPUT_DIR/comparison/complete-prod-incomplete-archive.txt"
+        if [[ -f "$repos_to_compare" ]] && [[ ! -f "$OUTPUT_DIR/comparison/git-ancestry.tsv" ]]; then
+            log_info "Running git ancestry comparison (Phase 3c)..."
+            run_phase 3 "Git Ancestry Comparison" "'$SCRIPT_DIR/22-compare-git-data.sh' '$PROD_GIT' '$ARCHIVE_GIT' '$repos_to_compare' '$OUTPUT_DIR/comparison'"
+        fi
+    else
+        log_warn "Git paths not provided - skipping git ancestry comparison"
+        log_warn "Without git comparison, repos where archive is ahead will be incorrectly flagged as needing re-sync"
+    fi
+}
+
+# Phase 4: Extract logs
+run_phase_4() {
+    if [[ -z "$SERVICE_NAME" ]]; then
+        log_warn "No service name provided, skipping Phase 4"
+        return 0
+    fi
+    
+    # Validate service name before running Phase 4
+    # Structured logging only exists in ngit-grasp, not ngit-relay
+    if [[ "$SERVICE_NAME" == *"ngit-relay"* ]]; then
+        log_error "SERVICE_NAME appears to be ngit-relay: $SERVICE_NAME"
+        log_error ""
+        log_error "Phase 4 requires an ngit-grasp service with structured logging."
+        log_error "Structured logging ([PARSE_FAIL], [PURGATORY_EXPIRED]) only exists"
+        log_error "in ngit-grasp services, NOT in ngit-relay services."
+        log_error ""
+        log_error "Please update --service to use the ngit-grasp archive service."
+        log_error ""
+        log_error "To find the correct service name:"
+        log_error "  systemctl list-units 'ngit-grasp*' --all"
+        log_error ""
+        log_error "Common ngit-grasp service names:"
+        log_error "  - ngit-grasp.service"
+        log_error "  - ngit-grasp-relay-ngit-dev.service (NixOS multi-instance)"
+        log_error "  - ngit-grasp-archive.service"
+        return 1
+    fi
+    
+    # Warn if service name doesn't look like ngit-grasp
+    if [[ "$SERVICE_NAME" != *"ngit-grasp"* && "$SERVICE_NAME" != *"grasp"* ]]; then
+        log_warn "SERVICE_NAME doesn't contain 'ngit-grasp': $SERVICE_NAME"
+        log_warn "Structured logging only exists in ngit-grasp services."
+        log_warn "If this is not an ngit-grasp service, Phase 4 will find no logs."
+    fi
+    
+    local cmds=()
+    
+    # Build log extraction options
+    local log_opts=""
+    if [[ -n "$LOG_SINCE" ]]; then
+        log_opts="$log_opts --since '$LOG_SINCE'"
+    fi
+    if [[ -n "$LOG_UNTIL" ]]; then
+        log_opts="$log_opts --until '$LOG_UNTIL'"
+    fi
+    
+    cmds+=("'$SCRIPT_DIR/30-extract-parse-failures.sh' '$SERVICE_NAME' '$OUTPUT_DIR/logs' $log_opts")
+    cmds+=("'$SCRIPT_DIR/31-extract-purgatory-expiry.sh' '$SERVICE_NAME' '$OUTPUT_DIR/logs' $log_opts")
+    
+    run_phase 4 "Extract Logs (VPS required)" "${cmds[@]}"
+}
+
+# Phase 5: Final classification
+run_phase_5() {
+    # Check if we have the minimum required files
+    local can_run=true
+    
+    if [[ ! -d "$OUTPUT_DIR/prod" ]]; then
+        log_warn "Missing prod directory"
+        can_run=false
+    fi
+    
+    if [[ ! -d "$OUTPUT_DIR/archive" ]]; then
+        log_warn "Missing archive directory"
+        can_run=false
+    fi
+    
+    if [[ ! -d "$OUTPUT_DIR/comparison" ]]; then
+        log_warn "Missing comparison directory"
+        can_run=false
+    fi
+    
+    # Create logs directory with empty files if missing
+    if [[ "$DRY_RUN" != "true" ]]; then
+        mkdir -p "$OUTPUT_DIR/logs"
+        for f in parse-failures.txt purgatory-expired.txt; do
+            if [[ ! -f "$OUTPUT_DIR/logs/$f" ]]; then
+                echo "# No data - Phase 4 not run" > "$OUTPUT_DIR/logs/$f"
+            fi
+        done
+    fi
+    
+    if [[ "$can_run" == "false" ]]; then
+        log_error "Cannot run Phase 5 - missing required input directories"
+        return 1
+    fi
+    
+    run_phase 5 "Final Classification (fast)" "'$SCRIPT_DIR/40-classify-actions.sh' '$OUTPUT_DIR'"
+}
+
+# Display summary
+display_summary() {
+    log_header "Migration Analysis Complete"
+    
+    echo "Output Directory: $OUTPUT_DIR"
+    echo ""
+    
+    # Phase timing summary
+    echo "Phase Timing:"
+    local total_time=0
+    for phase in 1 2 3 4 5; do
+        local skip_var="SKIP_PHASE_$phase"
+        if [[ "${!skip_var}" == "true" ]]; then
+            echo "  Phase $phase: SKIPPED"
+        elif [[ -n "${PHASE_TIMES[$phase]:-}" ]]; then
+            local t="${PHASE_TIMES[$phase]}"
+            echo "  Phase $phase: ${t}s"
+            total_time=$((total_time + t))
+        else
+            echo "  Phase $phase: N/A"
+        fi
+    done
+    echo "  ─────────────"
+    echo "  Total: ${total_time}s"
+    echo ""
+    
+    # Results summary
+    if [[ -f "$OUTPUT_DIR/results/summary.txt" ]]; then
+        echo "Results Summary:"
+        echo ""
+        # Extract key metrics from summary
+        if grep -q "No Action Required" "$OUTPUT_DIR/results/summary.txt"; then
+            grep -A1 "No Action Required" "$OUTPUT_DIR/results/summary.txt" | head -2
+        fi
+        if grep -q "Action Required" "$OUTPUT_DIR/results/summary.txt"; then
+            grep -A1 "Action Required" "$OUTPUT_DIR/results/summary.txt" | head -2
+        fi
+        if grep -q "Manual Investigation" "$OUTPUT_DIR/results/summary.txt"; then
+            grep -A1 "Manual Investigation" "$OUTPUT_DIR/results/summary.txt" | head -2
+        fi
+        echo ""
+    fi
+    
+    # Output files
+    echo "Output Files:"
+    echo "  $OUTPUT_DIR/results/no-action-required.txt"
+    echo "  $OUTPUT_DIR/results/action-required.txt"
+    echo "  $OUTPUT_DIR/results/manual-investigation.txt"
+    echo "  $OUTPUT_DIR/results/summary.txt"
+    echo ""
+    
+    # Next steps
+    echo "Next Steps:"
+    echo "  1. Review results/summary.txt for overview"
+    echo "  2. Address items in results/action-required.txt"
+    echo "  3. Investigate items in results/manual-investigation.txt"
+    echo "  4. Plan migration window when action items are resolved"
+    echo ""
+}
+
+# Main
+main() {
+    parse_args "$@"
+    
+    log_header "GRASP Relay to ngit-grasp Migration Analysis"
+    
+    validate_args
+    check_prerequisites
+    determine_phases
+    setup_output_dir
+    
+    # Show configuration
+    log_info "Configuration:"
+    log_step "Prod relay: $PROD_RELAY"
+    log_step "Archive relay: $ARCHIVE_RELAY"
+    [[ -n "$PROD_GIT" ]] && log_step "Prod git: $PROD_GIT"
+    [[ -n "$ARCHIVE_GIT" ]] && log_step "Archive git: $ARCHIVE_GIT"
+    [[ -n "$SERVICE_NAME" ]] && log_step "Service: $SERVICE_NAME"
+    log_step "Output: $OUTPUT_DIR"
+    echo ""
+    
+    # Show phase plan
+    log_info "Phase Plan:"
+    for phase in 1 2 3 4 5; do
+        local skip_var="SKIP_PHASE_$phase"
+        if [[ "${!skip_var}" == "true" ]]; then
+            log_step "Phase $phase: SKIP"
+        else
+            log_step "Phase $phase: RUN"
+        fi
+    done
+    echo ""
+    
+    if [[ "$DRY_RUN" == "true" ]]; then
+        log_warn "DRY RUN MODE - No changes will be made"
+        echo ""
+    fi
+    
+    # Run phases
+    local overall_exit=0
+    
+    run_phase_1 || overall_exit=1
+    run_phase_2 || overall_exit=1
+    run_phase_3 || overall_exit=1
+    run_phase_4 || overall_exit=1
+    run_phase_5 || overall_exit=1
+    
+    # Display summary
+    if [[ "$DRY_RUN" != "true" ]]; then
+        display_summary
+    fi
+    
+    if [[ $overall_exit -ne 0 ]]; then
+        log_warn "Some phases failed. Review output for details."
+    fi
+    
+    exit $overall_exit
+}
+
+main "$@"
diff --git a/docs/archive/2026-01-relay-ngit-dev-migration/scripts/validate-service.sh b/docs/archive/2026-01-relay-ngit-dev-migration/scripts/validate-service.sh
new file mode 100755
index 0000000..6988af3
--- /dev/null
+++ b/docs/archive/2026-01-relay-ngit-dev-migration/scripts/validate-service.sh
@@ -0,0 +1,151 @@
+#!/usr/bin/env bash
+#
+# validate-service.sh - Validate service name for structured logging
+#
+# This helper script validates that a service name is appropriate for
+# Phase 4 log extraction. Structured logging ([PARSE_FAIL], [PURGATORY_EXPIRED])
+# only exists in ngit-grasp services, NOT in ngit-relay services.
+#
+# USAGE:
+#   Source this script and call the validation function:
+#
+#   source validate-service.sh
+#   validate_service_for_structured_logging "$SERVICE_NAME" || exit 1
+#
+# BACKGROUND:
+#   Phase 4 of the migration analysis extracts structured log entries from
+#   journald. These log entries only exist in ngit-grasp services. If you
+#   accidentally specify an ngit-relay service, Phase 4 will find no logs
+#   and produce empty results.
+#
+#   This validation prevents that common mistake by:
+#   1. Checking if the service name contains "ngit-relay" (error)
+#   2. Warning if the service name doesn't contain "ngit-grasp"
+#   3. Optionally checking if structured logs actually exist
+#
+# SEE ALSO:
+#   docs/how-to/migrate-to-ngit-grasp.md - Full migration guide
+#   30-extract-parse-failures.sh - Uses this validation
+#   31-extract-purgatory-expiry.sh - Uses this validation
+#
+
+# Colors for output (disabled if not a terminal)
+if [[ -t 1 ]]; then
+    _VS_RED='\033[0;31m'
+    _VS_YELLOW='\033[0;33m'
+    _VS_NC='\033[0m'
+else
+    _VS_RED=''
+    _VS_YELLOW=''
+    _VS_NC=''
+fi
+
+# Validates that the service name is appropriate for structured logging
+#
+# Arguments:
+#   $1 - service_name: The systemd service name to validate
+#   $2 - check_logs: Whether to check if logs actually exist (default: "true")
+#   $3 - interactive: Whether to prompt for confirmation (default: "true")
+#
+# Returns:
+#   0 - Service is valid for structured logging
+#   1 - Service is invalid or user declined to continue
+#
+# Example:
+#   validate_service_for_structured_logging "ngit-grasp.service" || exit 1
+#   validate_service_for_structured_logging "ngit-grasp.service" "false"  # Skip log check
+#   validate_service_for_structured_logging "ngit-grasp.service" "true" "false"  # Non-interactive
+#
+validate_service_for_structured_logging() {
+    local service_name="$1"
+    local check_logs="${2:-true}"
+    local interactive="${3:-true}"
+    
+    # Check if service name looks like ngit-relay (ERROR - wrong service type)
+    if [[ "$service_name" == *"ngit-relay"* ]]; then
+        echo -e "${_VS_RED}ERROR: Service name appears to be ngit-relay: $service_name${_VS_NC}" >&2
+        echo "" >&2
+        echo "Structured logging ([PARSE_FAIL], [PURGATORY_EXPIRED]) only exists in" >&2
+        echo "ngit-grasp services, NOT in ngit-relay services." >&2
+        echo "" >&2
+        echo "Please use the ngit-grasp archive service instead." >&2
+        echo "" >&2
+        echo "To find the correct service name:" >&2
+        echo "  systemctl list-units 'ngit-grasp*' --all" >&2
+        echo "" >&2
+        echo "Common ngit-grasp service names:" >&2
+        echo "  - ngit-grasp.service" >&2
+        echo "  - ngit-grasp-relay-ngit-dev.service (NixOS multi-instance)" >&2
+        echo "  - ngit-grasp-archive.service" >&2
+        return 1
+    fi
+    
+    # Check if service name looks like ngit-grasp (WARNING if not)
+    if [[ "$service_name" != *"ngit-grasp"* && "$service_name" != *"grasp"* ]]; then
+        echo -e "${_VS_YELLOW}WARNING: Service name doesn't contain 'ngit-grasp': $service_name${_VS_NC}" >&2
+        echo "" >&2
+        echo "Structured logging ([PARSE_FAIL], [PURGATORY_EXPIRED]) only exists in" >&2
+        echo "ngit-grasp services." >&2
+        echo "" >&2
+        
+        if [[ "$interactive" == "true" ]]; then
+            read -p "Continue anyway? (y/N) " -n 1 -r
+            echo
+            if [[ ! $REPLY =~ ^[Yy]$ ]]; then
+                return 1
+            fi
+        else
+            echo "Non-interactive mode: proceeding despite warning" >&2
+        fi
+    fi
+    
+    # Optionally check if structured logs actually exist
+    if [[ "$check_logs" == "true" ]]; then
+        # Check if journalctl is available
+        if ! command -v journalctl &> /dev/null; then
+            echo -e "${_VS_YELLOW}WARNING: journalctl not available, cannot verify logs exist${_VS_NC}" >&2
+            return 0
+        fi
+        
+        # Check for structured log entries
+        # IMPORTANT: Use --no-pager to prevent hanging when run non-interactively (e.g., via SSH)
+        local has_parse_fail has_purgatory
+        has_parse_fail=$(journalctl --no-pager -u "$service_name" --since "7 days ago" 2>/dev/null | grep -c '\[PARSE_FAIL\]' || echo "0")
+        has_purgatory=$(journalctl --no-pager -u "$service_name" --since "7 days ago" 2>/dev/null | grep -c '\[PURGATORY_EXPIRED\]' || echo "0")
+        
+        # Strip any non-numeric characters (grep -c can have trailing whitespace)
+        has_parse_fail="${has_parse_fail//[^0-9]/}"
+        has_purgatory="${has_purgatory//[^0-9]/}"
+        has_parse_fail="${has_parse_fail:-0}"
+        has_purgatory="${has_purgatory:-0}"
+        
+        if [[ "$has_parse_fail" -eq 0 && "$has_purgatory" -eq 0 ]]; then
+            echo -e "${_VS_YELLOW}WARNING: No structured logs found in $service_name (last 7 days)${_VS_NC}" >&2
+            echo "" >&2
+            echo "This may indicate:" >&2
+            echo "  1. Wrong service (should be ngit-grasp archive service, not ngit-relay)" >&2
+            echo "  2. Structured logging not yet deployed to this ngit-grasp instance" >&2
+            echo "  3. No parse failures or purgatory expiry events in the time window" >&2
+            echo "" >&2
+            echo "To verify you have the right service:" >&2
+            echo "  systemctl list-units 'ngit-grasp*' --all" >&2
+            echo "  journalctl -u <service> | grep -E '\\[PARSE_FAIL\\]|\\[PURGATORY_EXPIRED\\]' | head -5" >&2
+            echo "" >&2
+            
+            if [[ "$interactive" == "true" ]]; then
+                read -p "Continue anyway? (y/N) " -n 1 -r
+                echo
+                if [[ ! $REPLY =~ ^[Yy]$ ]]; then
+                    return 1
+                fi
+            else
+                echo "Non-interactive mode: proceeding despite warning" >&2
+            fi
+        fi
+    fi
+    
+    return 0
+}
+
+# Export the function so it can be used after sourcing
+export -f validate_service_for_structured_logging
diff --git a/docs/how-to/README.md b/docs/how-to/README.md
index ba58c08..087ae53 100644
--- a/docs/how-to/README.md
+++ b/docs/how-to/README.md
@@ -110,18 +110,6 @@ How-to guides are **recipes** that show you how to solve specific problems or ac
 
 ---
 
-### Migrate from ngit-relay
-**Status:** 🔜 Planned
-
-**Problem:** Switch from reference implementation  
-**You'll learn:**
-- Export data from ngit-relay
-- Import to ngit-grasp
-- Update repository URLs
-- Verify migration
-
----
-
 ## How to Use How-To Guides
 
 1. **Find your problem** - Browse or search for what you need
diff --git a/docs/reference/configuration.md b/docs/reference/configuration.md
index b24b498..b09b20f 100644
--- a/docs/reference/configuration.md
+++ b/docs/reference/configuration.md
@@ -1041,10 +1041,10 @@ Per-connection limits (built-in to relay-builder, not configurable):
 
 ### Logging Configuration
 
-#### `RUST_LOG`
+#### `NGIT_LOG_LEVEL`
 
-**Description:** Logging level and filters (standard Rust environment variable)  
-**Type:** String (log level or filter)  
+**Description:** Logging level and filters for application logging  
+**Type:** String (log level or filter expression)  
 **Default:** `info`  
 **Required:** No
 
@@ -1052,17 +1052,17 @@ Per-connection limits (built-in to relay-builder, not configurable):
 
 ```bash
 # Simple levels
-RUST_LOG=error    # Errors only
-RUST_LOG=warn     # Warnings and errors
-RUST_LOG=info     # Info, warnings, errors
-RUST_LOG=debug    # Debug and above
-RUST_LOG=trace    # Everything
+NGIT_LOG_LEVEL=error    # Errors only
+NGIT_LOG_LEVEL=warn     # Warnings and errors
+NGIT_LOG_LEVEL=info     # Info, warnings, errors (default)
+NGIT_LOG_LEVEL=debug    # Debug and above
+NGIT_LOG_LEVEL=trace    # Everything (very verbose)
 
-# Module-specific
-RUST_LOG=ngit_grasp=debug,actix_web=info
+# Module-specific filtering
+NGIT_LOG_LEVEL=ngit_grasp=debug,actix_web=info
 
 # Complex filters
-RUST_LOG=debug,hyper=info,tokio=warn
+NGIT_LOG_LEVEL=debug,hyper=info,tokio=warn
 ```
 
 **Log levels (most to least verbose):**
@@ -1073,12 +1073,25 @@ RUST_LOG=debug,hyper=info,tokio=warn
 4. `warn` - Warnings about potential issues
 5. `error` - Errors only
 
+**CLI flag:**
+
+```bash
+ngit-grasp --log-level trace
+```
+
 **Production recommendation:**
 
 ```bash
-RUST_LOG=info,ngit_grasp=debug
+NGIT_LOG_LEVEL=info
 ```
 
+**Notes:**
+
+- Uses Rust's `tracing` crate filter syntax
+- Supports module-level filtering (e.g., `ngit_grasp=debug,hyper=info`)
+- `trace` level can significantly impact performance
+- For production, `info` or `warn` is recommended
+
 ---
 
 ### Security Configuration (Planned)