docs: roo code /init stripped down AGENTS.md

1 files changed, 79 insertions, 750 deletions

diff --git a/AGENTS.md b/AGENTS.md
index 7c2ac19..e25299c 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,802 +1,131 @@
-# AI Agent Guidelines for ngit-grasp
-
-**Purpose:** Ensure AI agents (and humans) maintain consistent documentation practices and avoid common pitfalls.
-
-**Last Updated:** November 4, 2025
-
----
-
-## 📁 Documentation Structure
-
-### Overview
-
-We use the **[Diátaxis](https://diataxis.fr/) framework** for all documentation. This prevents documentation sprawl by organizing content into four clear categories based on purpose and audience.
-
-```
-ngit-grasp/
-├── README.md                    # Project overview (keep updated)
-├── AGENTS.md                    # This file - agent guidelines
-├── CHANGELOG.md                 # User-facing changes (semver)
-│
-├── work/                        # Temporary session files (.gitignore'd)
-│   ├── README.md               # Only file committed to git
-│   └── *.md                    # Session notes, status, plans (temporary)
-│
-├── docs/                        # All documentation (Diátaxis structure)
-│   ├── README.md               # Navigation guide with quadrant diagram
-│   │
-│   ├── tutorials/              # Learning-oriented (practical + learning)
-│   │   ├── getting-started.md  # First-time setup
-│   │   └── first-audit.md      # Running your first audit
-│   │
-│   ├── how-to/                 # Task-oriented (practical + working)
-│   │   ├── deploy.md           # Production deployment
-│   │   ├── nix-flakes.md       # Nix environment setup
-│   │   ├── test-compliance.md  # Running compliance tests
-│   │   └── upgrade-nostr-sdk.md # SDK upgrade guide
-│   │
-│   ├── reference/              # Information-oriented (theoretical + working)
-│   │   ├── git-protocol.md     # Git Smart HTTP protocol
-│   │   ├── grasp-protocol.md   # GRASP specification
-│   │   ├── configuration.md    # All config options
-│   │   ├── test-strategy.md    # Testing reference
-│   │   └── api.md              # Internal API docs
-│   │
-│   ├── explanation/            # Understanding-oriented (theoretical + learning)
-│   │   ├── architecture.md     # System design overview
-│   │   ├── inline-authorization.md # Why inline auth?
-│   │   ├── comparison.md       # vs ngit-relay
-│   │   └── decisions.md        # Design decisions
-│   │
-│   ├── archive/                # Historical session notes
-│   │   └── YYYY-MM-DD-*.md     # Completed work
-│   │
-│   └── learnings/              # DEPRECATED - migrated to Diátaxis
-│       └── README.md           # Migration notice
-│
-├── grasp-audit/                # Audit tool subproject
-│   ├── README.md              # Main audit docs
-│   └── docs/                  # Follows same Diátaxis structure
-│       ├── tutorials/
-│       ├── how-to/
-│       ├── reference/
-│       └── explanation/
-│
-└── .ai/                        # AI assistant context (ignored in git)
-    └── history/               # Conversation history
-```
+# AGENTS.md
 
-### Diátaxis Framework
-
-All documentation MUST fit into one of four categories:
-
-**📚 Tutorials** (`docs/tutorials/`)
-- **Purpose:** Learning-oriented, teach by doing
-- **Audience:** Newcomers, beginners
-- **Style:** Step-by-step lessons with guaranteed outcomes
-- **Examples:** Getting Started, First Audit
-- **Question:** "Can you teach me to...?"
-
-**🔧 How-To Guides** (`docs/how-to/`)
-- **Purpose:** Task-oriented, solve problems
-- **Audience:** Users with basic knowledge
-- **Style:** Practical recipes and solutions
-- **Examples:** Deploy, Configure, Troubleshoot
-- **Question:** "How do I...?"
-
-**📖 Reference** (`docs/reference/`)
-- **Purpose:** Information-oriented, technical facts
-- **Audience:** Users looking up specific information
-- **Style:** Dry, factual, comprehensive
-- **Examples:** API docs, Config options, Protocols
-- **Question:** "What is...?"
-
-**💡 Explanation** (`docs/explanation/`)
-- **Purpose:** Understanding-oriented, clarify concepts
-- **Audience:** Users wanting deeper understanding
-- **Style:** Discussion, context, alternatives
-- **Examples:** Architecture, Design Decisions, Comparisons
-- **Question:** "Why...?"
-
-**See:** [Diátaxis documentation](https://diataxis.fr/) for detailed guidance.
-
-### File Type Guidelines
-
-**Markdown (.md):**
-- Primary format for all documentation
-- Easy to read in plain text and rendered
-- Supports code blocks, links, tables
-- Version control friendly
-
-**Text (.txt):**
-- Only for visual ASCII art summaries
-- Must be archived after session (never permanent)
-- Examples: status boxes, visual diagrams
-- Archive to `docs/archive/YYYY-MM-DD-name.txt`
-
-**Other formats:**
-- Avoid unless absolutely necessary
-- If needed, document in README.md why
-
----
-
-## 📋 Document Lifecycle
-
-### 1. Working Documents (work/ Directory)
-
-**Purpose:** Session-specific temporary files  
-**Location:** `work/` directory (.gitignore'd)  
-**Lifecycle:** Created → Used → Archived or Deleted  
-**Retention:** Archive valuable content, delete rest at session end
-
-**Examples:**
-- `work/session-notes.md` → Session notes and progress
-- `work/status.md` → Current status report
-- `work/migration-plan.md` → Planning document
-- `work/visual-summary.txt` → ASCII art summaries
-
-**Rules:**
-- ✅ Create ALL session-specific docs in `work/`
-- ✅ Use descriptive names (no date prefix needed)
-- ✅ Archive valuable content to `docs/archive/YYYY-MM-DD-name.md`
-- ✅ Delete obsolete files at session end
-- ✅ Keep `work/` clean (empty except README.md when not in session)
-- ❌ Don't commit `work/` contents to git (except README.md)
-- ❌ Don't reference `work/` docs from permanent documentation
-- ❌ Don't let `work/` accumulate files between sessions
-
-**Why work/ instead of root:**
-- Keeps root clean (only README.md, AGENTS.md, CHANGELOG.md)
-- Clear separation: permanent vs. temporary
-- Not committed to git (reduces noise)
-- Easy to clean up (just `rm -rf work/*`)
-
-### 2. Permanent Documentation (docs/)
-
-**Purpose:** Long-term reference, architecture, guides  
-**Location:** `docs/` (organized by Diátaxis category)  
-**Lifecycle:** Created → Maintained → Updated  
-**Retention:** Permanent (version controlled)
-
-**Structure:**
-- `docs/tutorials/` - Learning-oriented lessons
-- `docs/how-to/` - Task-oriented guides
-- `docs/reference/` - Information-oriented facts
-- `docs/explanation/` - Understanding-oriented discussion
-
-**Examples:**
-- `docs/tutorials/getting-started.md` - First-time setup
-- `docs/how-to/deploy.md` - Deployment guide
-- `docs/reference/configuration.md` - Config options
-- `docs/explanation/architecture.md` - System design
-
-**Rules:**
-- ✅ Categorize by Diátaxis framework (tutorial/how-to/reference/explanation)
-- ✅ Keep updated as project evolves
-- ✅ Use clear structure and headings
-- ✅ Link between related docs
-- ❌ Don't duplicate information (use links)
-- ❌ Don't include session-specific details
-- ❌ Don't put docs in wrong category (see Diátaxis guide)
-
-### 3. Archive (docs/archive/)
-
-**Purpose:** Historical record, completed phases  
-**Location:** `docs/archive/`  
-**Lifecycle:** Moved from root → Archived  
-**Retention:** Permanent (for reference)
-
-**Examples:**
-- `docs/archive/2025-11-04-tag-migration.md`
-- `docs/archive/2025-11-03-architecture-investigation.md`
-
-**Rules:**
-- ✅ Rename with date prefix when archiving
-- ✅ Add "ARCHIVED" marker at top
-- ✅ Extract learnings to docs/learnings/ first
-- ❌ Don't modify after archiving
-- ❌ Don't reference in active documentation
-
-### 4. Learnings (DEPRECATED)
-
-**Status:** `docs/learnings/` is deprecated - content migrated to Diátaxis structure
-
-**Migration:**
-- Gotchas and patterns → `docs/how-to/`
-- Technical details → `docs/reference/`
-- Understanding concepts → `docs/explanation/`
-
-**Examples:**
-- `learnings/nix-flakes.md` → `how-to/nix-flakes.md`
-- `learnings/nostr-sdk.md` → `reference/nostr-sdk-upgrade.md`
-- `learnings/git-http-backend.md` → `reference/git-protocol.md`
-
-**Rules:**
-- ❌ Don't create new files in `docs/learnings/`
-- ✅ Migrate existing content to appropriate Diátaxis category
-- ✅ Add redirect notice in old location
-
----
-
-## 🔄 Cleanup Process
-
-### When to Clean Up
-
-**Trigger:** End of session OR `work/` has >5 files  
-**Frequency:** End of each session (mandatory)  
-**Responsibility:** AI agents should proactively clean up before session end
-
-### Cleanup Steps
-
-1. **Review work/ Directory**
-   ```bash
-   # List all working docs
-   ls -la work/
-   ```
-
-2. **Extract to Diátaxis Categories**
-   - Review each doc in `work/`
-   - Extract valuable content to appropriate category:
-     - Gotchas/solutions → `docs/how-to/`
-     - Technical facts → `docs/reference/`
-     - Concepts/design → `docs/explanation/`
-     - Lessons → `docs/tutorials/`
-
-3. **Archive Important Session Docs**
-   ```bash
-   # Archive valuable session docs with date prefix
-   mv work/migration-complete.md docs/archive/2025-11-04-migration-complete.md
-   mv work/visual-summary.txt docs/archive/2025-11-04-visual-summary.txt
-   ```
-
-4. **Delete Temporary Files**
-   ```bash
-   # Delete obsolete working docs
-   rm work/status.md
-   rm work/notes.md
-   
-   # Or clean everything
-   rm -rf work/*
-   # (work/README.md is safe - in .gitignore exception)
-   ```
-
-5. **Verify Clean State**
-   ```bash
-   # Root should only have these:
-   ls *.md
-   # README.md
-   # AGENTS.md
-   # (CHANGELOG.md when created)
-   
-   # work/ should be empty (except README.md)
-   ls work/
-   # README.md
-   ```
-
-6. **Commit Changes**
-   - Commit new permanent docs
-   - Commit archived docs
-   - Note: work/ contents not committed (gitignored)
-
-### Example Cleanup
+This file provides guidance to agents when working with code in this repository.
 
-```bash
-# Before cleanup (messy root!)
-ls *.md
-# README.md
-# AGENTS.md
-# CURRENT_STATUS.md
-# DIATAXIS_MIGRATION.md
-# SUMMARY.md
-# SESSION_NOTES.md
-# ... (many more)
-
-# After cleanup (clean root!)
-ls *.md
-# README.md
-# AGENTS.md
+## Project Structure
 
-# Working files in work/ during session
-ls work/
-# README.md
-# session-notes.md
-# status.md
-
-# After session cleanup
-ls work/
-# README.md
-# (all session files archived or deleted)
-
-# Archived
-ls docs/archive/ | tail -5
-# 2025-11-04-diataxis-migration.md
-# 2025-11-04-diataxis-complete.md
-# 2025-11-04-diataxis-migration-visual.txt
-# 2025-11-04-session-summary.md
-# ...
-
-# Permanent docs in Diátaxis structure
-ls docs/tutorials/
-# getting-started.md
-# first-audit.md
-
-ls docs/how-to/
-# nix-flakes.md
-# deploy.md
-```
+**Workspace with Two Rust Projects:**
+- Root: `ngit-grasp` (main GRASP relay implementation)
+- `grasp-audit/`: Separate subproject with own `Cargo.toml` and `flake.nix`
 
----
+Cannot build grasp-audit from root - must `cd grasp-audit` first.
 
-## 🚨 Common Gotchas
+## Build & Test
 
-### Nix Flakes
+### Nix Flakes (Non-Standard)
 
-**Always use `nix develop`, not `nix-shell`**
+**CRITICAL:** Use `nix develop`, NOT `nix-shell` (we use flake.nix, not shell.nix)
 
 ```bash
 # ✅ Correct
 cd grasp-audit
-nix develop
 nix develop -c cargo build
+nix develop -c cargo test
 
 # ❌ Wrong
 nix-shell
 nix-shell --run "cargo build"
 ```
 
-**Why:** We use `flake.nix`, not `shell.nix`. See `docs/learnings/nix-flakes.md`.
-
-**Flake Commands:**
-```bash
-# Show flake outputs
-nix flake show
-
-# Update flake inputs
-nix flake update
-
-# Build package
-nix build
-
-# Run package
-nix run
-```
-
-### Git Subprojects
+### Running Tests
 
-**grasp-audit is a subproject with its own flake**
+**Integration tests require relay running:**
 
 ```bash
-# ✅ Correct - enter grasp-audit environment
-cd grasp-audit
-nix develop
-cargo build
-
-# ❌ Wrong - can't build from root
-cd ngit-grasp
-cargo build  # This won't find grasp-audit
-```
-
-**Why:** `grasp-audit/` has its own `Cargo.toml` and `flake.nix`.
+# Start ngit-relay first (tests run on port 18081)
+docker run --rm -p 18081:8081 -e NGIT_BIND_ADDRESS=0.0.0.0:8081 ghcr.io/decentralizedclimate/ngit-relay:latest
 
-### nostr-sdk Versions
-
-**We use nostr-sdk 0.43.x (latest stable)**
-
-```toml
-# ✅ Correct
-[dependencies]
-nostr-sdk = "0.43"
-
-# ❌ Wrong
-nostr-sdk = "0.35"  # Old version, breaking changes
+# From grasp-audit directory
+nix develop -c cargo test --lib test_grasp01_nostr_relay_against_relay -- --ignored --nocapture
 ```
 
-**Why:** We upgraded from 0.35 to 0.43. See `docs/learnings/nostr-sdk.md` for migration notes.
+Tests marked `#[ignore]` need relay - unit tests don't.
 
-**Common Breaking Changes:**
-- `EventBuilder::new()` signature changed
-- Tag API changed to `Tag::custom()`
-- Filter API changed
-- See archived upgrade docs for details
-
-### Testing Patterns
-
-**Integration tests require relay**
+### Running Single Test
 
 ```bash
-# ✅ Correct - start relay first
-docker run --rm -p 7000:7000 scsibug/nostr-rs-relay
-
-# Then run tests
-cd grasp-audit
-nix develop -c cargo test --ignored
-
-# ❌ Wrong - integration tests will fail
-cargo test --ignored  # No relay running
+# From grasp-audit/
+nix develop -c cargo test --lib specific_test_name -- --nocapture
 ```
 
-**Test Organization:**
-```rust
-// Unit tests (no relay needed)
-#[cfg(test)]
-mod tests {
-    #[test]
-    fn test_something() { }
-}
-
-// Integration tests (relay required)
-#[cfg(test)]
-mod tests {
-    #[test]
-    #[ignore]  // Requires relay
-    fn test_against_relay() { }
-}
-```
-
-### Documentation Updates
-
-**Keep README.md synchronized**
-
-When you:
-- Complete a major feature → Update README.md status
-- Change architecture → Update docs/ARCHITECTURE.md
-- Add dependencies → Update README.md tech stack
-- Change workflow → Update docs/GETTING_STARTED.md
+## Code Patterns
 
-**Don't:**
-- Create duplicate documentation
-- Leave stale status markers
-- Forget to update CHANGELOG.md for user-facing changes
+### nostr-sdk 0.43 Breaking Changes (vs 0.35)
 
----
+**Field access, not method calls:**
 
-## 📄 File Format Guidelines
-
-### When to Use .txt Files
-
-**Use .txt ONLY for:**
-- ASCII art visual summaries
-- Box diagrams with Unicode characters
-- Terminal-style status displays
-
-**Examples of appropriate .txt content:**
-```
-╔════════════════════════════════════════╗
-║  STATUS: ✅ COMPLETE                   ║
-╚════════════════════════════════════════╝
-```
-
-**Rules:**
-- ✅ Create in root during session for visual impact
-- ✅ Archive immediately after session ends
-- ✅ Use descriptive names: `CLEANUP_VISUAL_SUMMARY.txt`
-- ❌ Never keep .txt files in root long-term
-- ❌ Don't use .txt for regular documentation
-- ❌ Don't duplicate information (use .md instead)
-
-**Lifecycle:**
-```
-Create .txt → Use in session → Archive immediately
+```rust
+// ❌ WRONG (0.35 API)
+event.id()
+event.tags()
+for tag in &event.tags { }
+
+// ✅ CORRECT (0.43 API) 
+event.id          // Direct field access
+event.tags        // Direct field access
+event.tags.iter() // Iterator method
 ```
 
-### When to Use .md Files
-
-**Use .md for ALL documentation:**
-- Architecture docs
-- Session summaries
-- Status reports
-- Learnings
-- Planning documents
-- API documentation
-- User guides
-
-**Why markdown is preferred:**
-- Renders nicely on GitHub/GitLab
-- Supports code blocks with syntax highlighting
-- Easy to link between documents
-- Better for long-form content
-- Version control friendly
-
----
-
-## 📝 Writing Guidelines
-
-### Markdown Style
-
-```markdown
-# Title (H1 - only one per file)
-
-**Date:** YYYY-MM-DD  
-**Status:** [WIP|COMPLETE|ARCHIVED]
-
-## Section (H2)
-
-### Subsection (H3)
-
-**Bold** for emphasis, `code` for commands/code.
-
-- Bullet lists for items
-- Keep consistent style
-
-1. Numbered lists for sequences
-2. Use when order matters
-
-✅ Use emoji for status (sparingly)
-❌ Don't overuse emoji
+**Tag API changed:**
+```rust
+// ❌ WRONG (0.35)
+Tag::Generic(TagKind::Custom("clone".into()), vec![...])
 
-\`\`\`bash
-# Code blocks with language
-cargo build
-\`\`\`
+// ✅ CORRECT (0.43)
+Tag::custom(TagKind::custom("clone"), vec![...])
 ```
 
-### Status Markers
-
-- `[WIP]` - Work in progress
-- `[COMPLETE]` - Finished, may be archived
-- `[ARCHIVED]` - Moved to archive, historical only
-- `✅` - Success/complete
-- `❌` - Failure/incorrect
-- `⏳` - In progress
-- `🔜` - Planned/next
-
-### Document Headers
-
-```markdown
-# Document Title
-
-**Purpose:** One-line purpose  
-**Date:** YYYY-MM-DD  
-**Status:** [WIP|COMPLETE|ARCHIVED]  
-**Related:** Links to related docs
-
----
+**EventBuilder signature changed:**
+```rust
+// ❌ WRONG (0.35)
+EventBuilder::new(kind, content, &[tags])
 
-## Content starts here
+// ✅ CORRECT (0.43)
+EventBuilder::new(kind, content).tags(tags)
 ```
 
----
-
-## 🤖 AI Agent Responsibilities
-
-### Before Creating New Documents
-
-1. **Check if document already exists**
-   ```bash
-   find . -name "*keyword*.md"
-   ```
-
-2. **Check if information can be added to existing doc**
-   - Prefer updating over creating
-   - Use sections/subsections
-
-3. **Determine correct location**
-   - Session-specific? → `work/` (temporary, gitignored)
-   - Teaching beginners? → `docs/tutorials/`
-   - Solving a problem? → `docs/how-to/`
-   - Technical reference? → `docs/reference/`
-   - Explaining concepts? → `docs/explanation/`
-   - Historical? → `docs/archive/`
-
-4. **Ask the Diátaxis questions:**
-   - "Can you teach me to...?" → Tutorial
-   - "How do I...?" → How-To
-   - "What is...?" → Reference
-   - "Why...?" → Explanation
-
-5. **Use descriptive names**
-   - Working docs: `session-notes.md`, `status.md` (in `work/`)
-   - Archived docs: `YYYY-MM-DD-description.md` (in `docs/archive/`)
-   - Tutorials: `getting-started.md`, `first-audit.md`
-   - How-To: `deploy.md`, `nix-flakes.md`
-   - Reference: `configuration.md`, `api.md`
-   - Explanation: `architecture.md`, `decisions.md`
-
-6. **Choose correct file format**
-   - Use `.md` for all documentation (default)
-   - Use `.txt` ONLY for ASCII art visual summaries
-   - Archive `.txt` files immediately after session
-
-### During Development
-
-1. **Update status markers**
-   - Mark WIP → COMPLETE when done
-   - Update README.md status section
-
-2. **Extract learnings as you go**
-   - Add gotchas to docs/learnings/
-   - Don't wait until cleanup
-
-3. **Keep documentation DRY**
-   - Link to existing docs
-   - Don't duplicate information
-
-### End of Session
-
-1. **Clean up work/ directory (MANDATORY)**
-   - Archive valuable session docs to `docs/archive/YYYY-MM-DD-*.md`
-   - Delete temporary status reports
-   - Extract content to Diátaxis categories if needed
-   - Verify `work/` is empty (except README.md)
-
-2. **Create session summary (if valuable)**
-   - Archive to `docs/archive/YYYY-MM-DD-session-summary.md`
-   - Include: accomplishments, next steps, blockers
-
-3. **Update permanent docs**
-   - Sync README.md with reality
-   - Update relevant docs/ files
-   - Commit changes
-
-4. **Verify clean state**
-   ```bash
-   ls *.md  # Should only show README.md, AGENTS.md
-   ls work/  # Should only show README.md
-   ```
-
-### Cleanup Time (End of Session)
-
-1. **Review work/ directory**
-   ```bash
-   ls -la work/
-   ```
-
-2. **Extract content to appropriate Diátaxis category:**
-   - Gotchas/solutions → `docs/how-to/`
-   - Technical facts → `docs/reference/`
-   - Concepts/design → `docs/explanation/`
-   - Lessons → `docs/tutorials/`
-
-3. **Archive valuable session docs**
-   ```bash
-   mv work/important-notes.md docs/archive/2025-11-04-session-notes.md
-   mv work/visual-summary.txt docs/archive/2025-11-04-visual-summary.txt
-   ```
-
-4. **Delete temporary files**
-   ```bash
-   rm work/status.md
-   rm work/temp-notes.md
-   ```
-
-5. **Verify clean state**
-   ```bash
-   ls *.md  # Only README.md, AGENTS.md
-   ls work/  # Only README.md
-   ```
-
-6. **Commit permanent changes**
-   - Commit new/updated permanent docs
-   - Commit archived docs
-   - Note: work/ not committed (gitignored)
-
----
-
-## 🎯 Quality Checklist
-
-### For Every Document
-
-- [ ] Clear purpose stated at top
-- [ ] Date included
-- [ ] Status marker present
-- [ ] Proper heading hierarchy (H1 → H2 → H3)
-- [ ] Code blocks have language specified
-- [ ] Links are valid and relative
-- [ ] No duplicate information
-- [ ] Spell-checked and readable
-
-### For Working Documents
-
-- [ ] Descriptive filename with date
-- [ ] Will be archived or deleted when done
-- [ ] Not duplicating permanent docs
-- [ ] Learnings extracted to docs/learnings/
-
-### For Permanent Documents
-
-- [ ] In correct docs/ subdirectory
-- [ ] Linked from docs/README.md
-- [ ] Updated as project evolves
-- [ ] No session-specific details
-- [ ] Serves long-term purpose
-
-### For Archived Documents
-
-- [ ] Moved to docs/archive/
-- [ ] Renamed with date prefix
-- [ ] ARCHIVED marker at top (for .md files)
-- [ ] Learnings extracted first (for .md files)
-- [ ] Not referenced in active docs
-
-### For .txt Files
+See `docs/archive/2025-11-04-nostr-sdk-upgrade.md` for full migration.
 
-- [ ] Contains only ASCII art/visual summaries
-- [ ] Created in root for session use
-- [ ] Archived immediately after session
-- [ ] Not used for regular documentation
-- [ ] Descriptive filename with purpose clear
-
----
+## Documentation
 
-## 📚 Reference Documents
-
-### Must Read
-- **This file (AGENTS.md)** - Guidelines for documentation
-- **README.md** - Project overview
-- **docs/README.md** - Documentation navigation
-
-### Key Technical Docs
-- **docs/ARCHITECTURE.md** - System design
-- **docs/TEST_STRATEGY.md** - Testing approach
-- **docs/GETTING_STARTED.md** - Setup guide
+**Diátaxis Framework Used:**
+- `docs/tutorials/` - Learning-oriented
+- `docs/how-to/` - Task-oriented  
+- `docs/reference/` - Information-oriented
+- `docs/explanation/` - Understanding-oriented
 
-### Learnings (Gotchas)
-- **docs/learnings/nix-flakes.md** - Nix flake patterns
-- **docs/learnings/nostr-sdk.md** - nostr-sdk notes
-- **docs/learnings/git-http-backend.md** - Git protocol tips
+**Session files go in `work/` (gitignored except README.md)**
+- Archive valuable content to `docs/archive/YYYY-MM-DD-*.md` at session end
+- Delete temporary files
+- Keep root clean (only README.md, AGENTS.md)
 
----
-
-## 🔗 Quick Links
+## Critical Gotchas
 
-- [Project README](README.md)
-- [Documentation Index](docs/README.md)
-- [Architecture](docs/ARCHITECTURE.md)
-- [Learnings](docs/learnings/)
-- [Archive](docs/archive/)
+1. **Workspace compilation:** Can't `cargo build` from root for grasp-audit
+2. **Nix environment:** Must use `nix develop`, not `nix-shell`
+3. **nostr-sdk API:** Fields not methods in 0.43
+4. **Test isolation:** Integration tests need relay, marked with `#[ignore]`
+5. **Work directory:** All session docs go in `work/`, NOT root
+6. **Archive naming:** Use `YYYY-MM-DD-description.md` format
 
----
+## File Restrictions by Mode
 
-## 💡 Tips for Success
+Code mode can only edit files matching specific patterns (enforced by system):
+- Example: Architect mode restricted to `\.md$` files only
+- Attempting to edit restricted files causes FileRestrictionError
+- Check mode configuration if edit attempts fail unexpectedly
 
-1. **Less is more** - Prefer updating over creating
-2. **Archive often** - Keep root clean
-3. **Extract learnings** - Make knowledge reusable
-4. **Link, don't duplicate** - DRY applies to docs too
-5. **Date everything** - Context is important
-6. **Use descriptive names** - Future you will thank you
-7. **Check before creating** - Document might already exist
-8. **Update as you go** - Don't wait for cleanup time
-9. **Use .md by default** - Only use .txt for ASCII art
-10. **Archive .txt immediately** - Don't let them linger
+## Quick Reference
 
----
-
-## 🚀 Next Steps
-
-After reading this:
-
-1. **Review current documentation structure**
-   ```bash
-   ls -la *.md
-   ls -la docs/
-   ```
-
-2. **Identify cleanup candidates**
-   - Completed working docs
-   - Obsolete duplicates
-   - Session summaries
-
-3. **Extract learnings**
-   - Review completed docs
-   - Add to docs/learnings/
-
-4. **Archive and clean**
-   - Move to docs/archive/
-   - Delete obsolete files
-   - Update links
-
-5. **Commit changes**
-   ```bash
-   git add .
-   git commit -m "docs: cleanup and reorganization"
-   ```
-
----
+```bash
+# Build grasp-audit
+cd grasp-audit && nix develop -c cargo build
 
-**Remember:** Good documentation structure is like good code structure - it makes everything easier.
+# Run all tests (requires relay on 18081)
+cd grasp-audit && nix develop -c cargo test --ignored
 
----
+# Run single test
+cd grasp-audit && nix develop -c cargo test --lib test_name -- --nocapture
 
-*Last updated: November 4, 2025*  
-*Status: ✅ Active guidelines*
+# Check session files
+ls work/  # Should only have README.md when clean
\ No newline at end of file