+
+
+
+{/if}
+```
+
+## Best Practices
+
+### Security
+
+1. **Never store secret keys in plain text** - Use secure storage
+2. **Prefer NIP-07** - Let extensions manage keys
+3. **Clear keys on logout** - Don't leave in memory
+4. **Validate before signing** - Check event content
+
+### User Experience
+
+1. **Show signing status** - Loading states
+2. **Handle rejections gracefully** - User may cancel
+3. **Provide fallbacks** - Multiple login options
+4. **Remember preferences** - Store signer type
+
+### Error Handling
+
+```javascript
+async function safeSign(signer, event) {
+ try {
+ return await signer.signEvent(event);
+ } catch (error) {
+ if (error.message.includes('rejected')) {
+ console.log('User rejected signing');
+ return null;
+ }
+ if (error.message.includes('timeout')) {
+ console.log('Signing timed out');
+ return null;
+ }
+ throw error;
+ }
+}
+```
+
+### Permission Checking
+
+```javascript
+function hasEncryptionSupport(signer) {
+ return typeof signer.nip04Encrypt === 'function' ||
+ typeof signer.nip44Encrypt === 'function';
+}
+
+function getEncryptionMethod(signer) {
+ // Prefer NIP-44
+ if (typeof signer.nip44Encrypt === 'function') {
+ return 'nip44';
+ }
+ if (typeof signer.nip04Encrypt === 'function') {
+ return 'nip04';
+ }
+ return null;
+}
+```
+
+## Common Patterns
+
+### Signer Detection
+
+```javascript
+async function detectSigners() {
+ const available = [];
+
+ // Check NIP-07
+ if (typeof window !== 'undefined' && window.nostr) {
+ available.push({
+ type: 'nip07',
+ name: 'Browser Extension',
+ create: () => new Nip07Signer()
+ });
+ }
+
+ // Check stored credentials
+ const storedKey = localStorage.getItem('nsec');
+ if (storedKey) {
+ available.push({
+ type: 'stored',
+ name: 'Saved Key',
+ create: () => new SimpleSigner(storedKey)
+ });
+ }
+
+ return available;
+}
+```
+
+### Auto-Reconnect for NIP-46
+
+```javascript
+class ReconnectingNip46Signer {
+ constructor(options) {
+ this.options = options;
+ this.signer = null;
+ }
+
+ async connect() {
+ this.signer = new Nip46Signer(this.options);
+ await this.signer.connect();
+ }
+
+ async signEvent(event) {
+ try {
+ return await this.signer.signEvent(event);
+ } catch (error) {
+ if (error.message.includes('disconnected')) {
+ await this.connect();
+ return await this.signer.signEvent(event);
+ }
+ throw error;
+ }
+ }
+}
+```
+
+### Signer Type Persistence
+
+```javascript
+const SIGNER_KEY = 'nostr_signer_type';
+
+function saveSigner(type, data) {
+ localStorage.setItem(SIGNER_KEY, JSON.stringify({ type, data }));
+}
+
+async function restoreSigner() {
+ const saved = localStorage.getItem(SIGNER_KEY);
+ if (!saved) return null;
+
+ const { type, data } = JSON.parse(saved);
+
+ switch (type) {
+ case 'nip07':
+ if (window.nostr) {
+ return new Nip07Signer();
+ }
+ break;
+ case 'simple':
+ // Don't store secret keys!
+ break;
+ case 'nip46':
+ const signer = new Nip46Signer(data);
+ await signer.connect();
+ return signer;
+ }
+
+ return null;
+}
+```
+
+## Troubleshooting
+
+### Common Issues
+
+**Extension not detected:**
+- Wait for page load
+- Check window.nostr exists
+- Verify extension is enabled
+
+**Signing rejected:**
+- User cancelled in extension
+- Handle gracefully with error message
+
+**NIP-46 connection fails:**
+- Check relay is accessible
+- Verify remote signer is online
+- Check secret matches
+
+**Encryption not supported:**
+- Check signer has encrypt methods
+- Fall back to alternative method
+- Show user appropriate error
+
+## References
+
+- **applesauce GitHub**: https://github.com/hzrd149/applesauce
+- **NIP-07 Specification**: https://github.com/nostr-protocol/nips/blob/master/07.md
+- **NIP-46 Specification**: https://github.com/nostr-protocol/nips/blob/master/46.md
+- **nostr-tools**: https://github.com/nbd-wtf/nostr-tools
+
+## Related Skills
+
+- **nostr-tools** - Event creation and signing utilities
+- **applesauce-core** - Event stores and queries
+- **nostr** - Nostr protocol fundamentals
+- **svelte** - Building Nostr UIs
diff --git a/.claude/skills/cypher/SKILL.md b/.claude/skills/cypher/SKILL.md
new file mode 100644
index 00000000..e8ae91b2
--- /dev/null
+++ b/.claude/skills/cypher/SKILL.md
@@ -0,0 +1,395 @@
+---
+name: cypher
+description: This skill should be used when writing, debugging, or discussing Neo4j Cypher queries. Provides comprehensive knowledge of Cypher syntax, query patterns, performance optimization, and common mistakes. Particularly useful for translating between domain models and graph queries.
+---
+
+# Neo4j Cypher Query Language
+
+## Purpose
+
+This skill provides expert-level guidance for writing Neo4j Cypher queries, including syntax, patterns, performance optimization, and common pitfalls. It is particularly tuned for the patterns used in this ORLY Nostr relay codebase.
+
+## When to Use
+
+Activate this skill when:
+- Writing Cypher queries for Neo4j
+- Debugging Cypher syntax errors
+- Optimizing query performance
+- Translating Nostr filter queries to Cypher
+- Working with graph relationships and traversals
+- Creating or modifying schema (indexes, constraints)
+
+## Core Cypher Syntax
+
+### Clause Order (CRITICAL)
+
+Cypher requires clauses in a specific order. Violating this causes syntax errors:
+
+```cypher
+// CORRECT order of clauses
+MATCH (n:Label) // 1. Pattern matching
+WHERE n.prop = value // 2. Filtering
+WITH n, count(*) AS cnt // 3. Intermediate results (resets scope)
+OPTIONAL MATCH (n)-[r]-() // 4. Optional patterns
+CREATE (m:NewNode) // 5. Node/relationship creation
+SET n.prop = value // 6. Property updates
+DELETE r // 7. Deletions
+RETURN n.prop AS result // 8. Return clause
+ORDER BY result DESC // 9. Ordering
+SKIP 10 LIMIT 20 // 10. Pagination
+```
+
+### The WITH Clause (CRITICAL)
+
+The `WITH` clause is required to transition between certain operations:
+
+**Rule: Cannot use MATCH after CREATE without WITH**
+
+```cypher
+// WRONG - MATCH after CREATE without WITH
+CREATE (e:Event {id: $id})
+MATCH (ref:Event {id: $refId}) // ERROR!
+CREATE (e)-[:REFERENCES]->(ref)
+
+// CORRECT - Use WITH to carry variables forward
+CREATE (e:Event {id: $id})
+WITH e
+MATCH (ref:Event {id: $refId})
+CREATE (e)-[:REFERENCES]->(ref)
+```
+
+**Rule: WITH resets the scope**
+
+Variables not included in WITH are no longer accessible:
+
+```cypher
+// WRONG - 'a' is lost after WITH
+MATCH (a:Author), (e:Event)
+WITH e
+WHERE a.pubkey = $pubkey // ERROR: 'a' not defined
+
+// CORRECT - Include all needed variables
+MATCH (a:Author), (e:Event)
+WITH a, e
+WHERE a.pubkey = $pubkey
+```
+
+### Node and Relationship Patterns
+
+```cypher
+// Nodes
+(n) // Anonymous node
+(n:Label) // Labeled node
+(n:Label {prop: value}) // Node with properties
+(n:Label:OtherLabel) // Multiple labels
+
+// Relationships
+-[r]-> // Directed, anonymous
+-[r:TYPE]-> // Typed relationship
+-[r:TYPE {prop: value}]-> // With properties
+-[r:TYPE|OTHER]-> // Multiple types (OR)
+-[*1..3]-> // Variable length (1 to 3 hops)
+-[*]-> // Any number of hops
+```
+
+### MERGE vs CREATE
+
+**CREATE**: Always creates new nodes/relationships (may create duplicates)
+
+```cypher
+CREATE (n:Event {id: $id}) // Creates even if id exists
+```
+
+**MERGE**: Finds or creates (idempotent)
+
+```cypher
+MERGE (n:Event {id: $id}) // Finds existing or creates new
+ON CREATE SET n.created = timestamp()
+ON MATCH SET n.accessed = timestamp()
+```
+
+**Best Practice**: Use MERGE for reference nodes, CREATE for unique events
+
+```cypher
+// Reference nodes - use MERGE (idempotent)
+MERGE (author:Author {pubkey: $pubkey})
+
+// Unique events - use CREATE (after checking existence)
+CREATE (e:Event {id: $eventId, ...})
+```
+
+### OPTIONAL MATCH
+
+Returns NULL for non-matching patterns (like LEFT JOIN):
+
+```cypher
+// Find events, with or without tags
+MATCH (e:Event)
+OPTIONAL MATCH (e)-[:TAGGED_WITH]->(t:Tag)
+RETURN e.id, collect(t.value) AS tags
+```
+
+### Conditional Creation with FOREACH
+
+To conditionally create relationships:
+
+```cypher
+// FOREACH trick for conditional operations
+OPTIONAL MATCH (ref:Event {id: $refId})
+FOREACH (ignoreMe IN CASE WHEN ref IS NOT NULL THEN [1] ELSE [] END |
+ CREATE (e)-[:REFERENCES]->(ref)
+)
+```
+
+### Aggregation Functions
+
+```cypher
+count(*) // Count all rows
+count(n) // Count non-null values
+count(DISTINCT n) // Count unique values
+collect(n) // Collect into list
+collect(DISTINCT n) // Collect unique values
+sum(n.value) // Sum values
+avg(n.value) // Average
+min(n.value), max(n.value) // Min/max
+```
+
+### String Operations
+
+```cypher
+// String matching
+WHERE n.name STARTS WITH 'prefix'
+WHERE n.name ENDS WITH 'suffix'
+WHERE n.name CONTAINS 'substring'
+WHERE n.name =~ 'regex.*pattern' // Regex
+
+// String functions
+toLower(str), toUpper(str)
+trim(str), ltrim(str), rtrim(str)
+substring(str, start, length)
+replace(str, search, replacement)
+```
+
+### List Operations
+
+```cypher
+// IN clause
+WHERE n.kind IN [1, 7, 30023]
+WHERE n.pubkey IN $pubkeyList
+
+// List comprehension
+[x IN list WHERE x > 0 | x * 2]
+
+// UNWIND - expand list into rows
+UNWIND $pubkeys AS pubkey
+MERGE (u:User {pubkey: pubkey})
+```
+
+### Parameters
+
+Always use parameters for values (security + performance):
+
+```cypher
+// CORRECT - parameterized
+MATCH (e:Event {id: $eventId})
+WHERE e.kind IN $kinds
+
+// WRONG - string interpolation (SQL injection risk!)
+MATCH (e:Event {id: '" + eventId + "'})
+```
+
+## Schema Management
+
+### Constraints
+
+```cypher
+// Uniqueness constraint (also creates index)
+CREATE CONSTRAINT event_id_unique IF NOT EXISTS
+FOR (e:Event) REQUIRE e.id IS UNIQUE
+
+// Composite uniqueness
+CREATE CONSTRAINT card_unique IF NOT EXISTS
+FOR (c:Card) REQUIRE (c.customer_id, c.observee_pubkey) IS UNIQUE
+
+// Drop constraint
+DROP CONSTRAINT event_id_unique IF EXISTS
+```
+
+### Indexes
+
+```cypher
+// Single property index
+CREATE INDEX event_kind IF NOT EXISTS FOR (e:Event) ON (e.kind)
+
+// Composite index
+CREATE INDEX event_kind_created IF NOT EXISTS
+FOR (e:Event) ON (e.kind, e.created_at)
+
+// Drop index
+DROP INDEX event_kind IF EXISTS
+```
+
+## Common Query Patterns
+
+### Find with Filter
+
+```cypher
+// Multiple conditions with OR
+MATCH (e:Event)
+WHERE e.kind IN $kinds
+ AND (e.id = $id1 OR e.id = $id2)
+ AND e.created_at >= $since
+RETURN e
+ORDER BY e.created_at DESC
+LIMIT $limit
+```
+
+### Graph Traversal
+
+```cypher
+// Find events by author
+MATCH (e:Event)-[:AUTHORED_BY]->(a:Author {pubkey: $pubkey})
+RETURN e
+
+// Find followers of a user
+MATCH (follower:NostrUser)-[:FOLLOWS]->(user:NostrUser {pubkey: $pubkey})
+RETURN follower.pubkey
+
+// Find mutual follows (friends)
+MATCH (a:NostrUser {pubkey: $pubkeyA})-[:FOLLOWS]->(b:NostrUser)
+WHERE (b)-[:FOLLOWS]->(a)
+RETURN b.pubkey AS mutual_friend
+```
+
+### Upsert Pattern
+
+```cypher
+MERGE (n:Node {key: $key})
+ON CREATE SET
+ n.created_at = timestamp(),
+ n.value = $value
+ON MATCH SET
+ n.updated_at = timestamp(),
+ n.value = $value
+RETURN n
+```
+
+### Batch Processing with UNWIND
+
+```cypher
+// Create multiple nodes from list
+UNWIND $items AS item
+CREATE (n:Node {id: item.id, value: item.value})
+
+// Create relationships from list
+UNWIND $follows AS followed_pubkey
+MERGE (followed:NostrUser {pubkey: followed_pubkey})
+MERGE (author)-[:FOLLOWS]->(followed)
+```
+
+## Performance Optimization
+
+### Index Usage
+
+1. **Start with indexed properties** - Begin MATCH with most selective indexed field
+2. **Use composite indexes** - For queries filtering on multiple properties
+3. **Profile queries** - Use `PROFILE` prefix to see execution plan
+
+```cypher
+PROFILE MATCH (e:Event {kind: 1})
+WHERE e.created_at > $since
+RETURN e LIMIT 100
+```
+
+### Query Optimization Tips
+
+1. **Filter early** - Put WHERE conditions close to MATCH
+2. **Limit early** - Use LIMIT as early as possible
+3. **Avoid Cartesian products** - Connect patterns or use WITH
+4. **Use parameters** - Enables query plan caching
+
+```cypher
+// GOOD - Filter and limit early
+MATCH (e:Event)
+WHERE e.kind IN $kinds AND e.created_at >= $since
+WITH e ORDER BY e.created_at DESC LIMIT 100
+OPTIONAL MATCH (e)-[:TAGGED_WITH]->(t:Tag)
+RETURN e, collect(t)
+
+// BAD - Late filtering
+MATCH (e:Event), (t:Tag)
+WHERE e.kind IN $kinds
+RETURN e, t LIMIT 100
+```
+
+## Reference Materials
+
+For detailed information, consult the reference files:
+
+- **references/syntax-reference.md** - Complete Cypher syntax guide with all clause types, operators, and functions
+- **references/common-patterns.md** - Project-specific patterns for ORLY Nostr relay including event storage, tag queries, and social graph traversals
+- **references/common-mistakes.md** - Frequent Cypher errors and how to avoid them
+
+## ORLY-Specific Patterns
+
+This codebase uses these specific Cypher patterns:
+
+### Event Storage Pattern
+
+```cypher
+// Create event with author relationship
+MERGE (a:Author {pubkey: $pubkey})
+CREATE (e:Event {
+ id: $eventId,
+ serial: $serial,
+ kind: $kind,
+ created_at: $createdAt,
+ content: $content,
+ sig: $sig,
+ pubkey: $pubkey,
+ tags: $tags
+})
+CREATE (e)-[:AUTHORED_BY]->(a)
+```
+
+### Tag Query Pattern
+
+```cypher
+// Query events by tag (Nostr #
+ {notes?.map(note => (
+
+ )
+}
+```
+
+## 🔍 Common Patterns Quick Reference
+
+### Safe NDK Access
+```typescript
+const ndk = ndkActions.getNDK()
+if (!ndk) throw new Error('NDK not initialized')
+```
+
+### Subscription Cleanup
+```typescript
+useEffect(() => {
+ const sub = ndk.subscribe(filter, { closeOnEose: false })
+ sub.on('event', handleEvent)
+ return () => sub.stop() // Critical!
+}, [ndk])
+```
+
+### Error Handling
+```typescript
+try {
+ await event.sign()
+ await event.publish()
+} catch (error) {
+ console.error('Publishing failed:', error)
+ throw new Error('Failed to publish. Check connection.')
+}
+```
+
+### Tag Filtering
+```typescript
+// ✅ Correct (note the # prefix for tag filters)
+{ kinds: [16], '#order': [orderId] }
+
+// ❌ Wrong
+{ kinds: [16], 'order': [orderId] }
+```
+
+## 🛠 Development Tools
+
+### VS Code Integration
+These skill files work with:
+- Cursor AI for code completion
+- Claude for code assistance
+- GitHub Copilot with context
+
+### Debugging Tips
+```typescript
+// Check connection
+console.log('Connected relays:',
+ Array.from(ndk.pool?.relays.values() || [])
+ .filter(r => r.status === 1)
+ .map(r => r.url)
+)
+
+// Verify signer
+console.log('Signer:', ndk.signer)
+console.log('Active user:', ndk.activeUser)
+
+// Event inspection
+console.log('Event:', {
+ id: event.id,
+ kind: event.kind,
+ tags: event.tags,
+ sig: event.sig
+})
+```
+
+## 📊 Statistics
+
+- **Total Documentation**: ~50KB
+- **Code Examples**: 5 complete modules
+- **Patterns Documented**: 50+
+- **Common Issues Covered**: 15+
+- **Based On**: Real production code
+
+## 🔗 Additional Resources
+
+### Official NDK Resources
+- **GitHub**: https://github.com/nostr-dev-kit/ndk
+- **Documentation**: https://ndk.fyi
+- **NPM**: `@nostr-dev-kit/ndk`
+
+### Nostr Protocol
+- **NIPs**: https://github.com/nostr-protocol/nips
+- **Nostr**: https://nostr.com
+
+### Related Tools
+- **TanStack Query**: React state management
+- **TanStack Router**: Type-safe routing
+- **Radix UI**: Accessible components
+
+## 💡 Tips for Using This Skill
+
+1. **Start Small**: Begin with quick-reference.md for syntax
+2. **Go Deep**: Read ndk-skill.md section by section
+3. **Copy Examples**: Use examples/ as templates
+4. **Debug Issues**: Check troubleshooting.md first
+5. **Stay Updated**: Patterns based on production usage
+
+## 🤝 Contributing
+
+This skill is maintained based on the Plebeian Market codebase. To improve it:
+
+1. Document new patterns you discover
+2. Add solutions to common problems
+3. Update examples with better approaches
+4. Keep synchronized with NDK updates
+
+## 📝 Version Info
+
+- **Skill Version**: 1.0.0
+- **NDK Version**: Latest (based on production usage)
+- **Last Updated**: November 2025
+- **Codebase**: Plebeian Market
+
+---
+
+**Ready to build with NDK?** Start with `quick-reference.md` or dive into `examples/01-initialization.ts`!
+
diff --git a/.claude/skills/ndk/README.md b/.claude/skills/ndk/README.md
new file mode 100644
index 00000000..2a13dc47
--- /dev/null
+++ b/.claude/skills/ndk/README.md
@@ -0,0 +1,38 @@
+# NDK (Nostr Development Kit) Claude Skill
+
+This skill provides comprehensive knowledge about working with the Nostr Development Kit (NDK) library.
+
+## Files
+
+- **ndk-skill.md** - Complete reference documentation with patterns from production usage
+- **quick-reference.md** - Quick lookup guide for common NDK tasks
+- **examples/** - Code examples extracted from the Plebeian Market codebase
+
+## Usage
+
+When working with NDK-related code, reference these documents to:
+- Understand initialization patterns
+- Learn authentication flows (NIP-07, NIP-46, private keys)
+- Implement event creation and publishing
+- Set up subscriptions for real-time updates
+- Query events with filters
+- Handle users and profiles
+- Integrate with TanStack Query
+
+## Key Topics Covered
+
+1. NDK Initialization & Configuration
+2. Authentication & Signers
+3. Event Creation & Publishing
+4. Querying Events
+5. Real-time Subscriptions
+6. User & Profile Management
+7. Tag Handling
+8. Replaceable Events
+9. Relay Management
+10. Integration with React/TanStack Query
+11. Error Handling & Best Practices
+12. Performance Optimization
+
+All examples are based on real production code from the Plebeian Market application.
+
diff --git a/.claude/skills/ndk/examples/01-initialization.ts b/.claude/skills/ndk/examples/01-initialization.ts
new file mode 100644
index 00000000..bada6d6b
--- /dev/null
+++ b/.claude/skills/ndk/examples/01-initialization.ts
@@ -0,0 +1,162 @@
+/**
+ * NDK Initialization Patterns
+ *
+ * Examples from: src/lib/stores/ndk.ts
+ */
+
+import NDK from '@nostr-dev-kit/ndk'
+
+// ============================================================
+// BASIC INITIALIZATION
+// ============================================================
+
+const basicInit = () => {
+ const ndk = new NDK({
+ explicitRelayUrls: ['wss://relay.damus.io', 'wss://relay.nostr.band']
+ })
+
+ return ndk
+}
+
+// ============================================================
+// PRODUCTION PATTERN - WITH MULTIPLE NDK INSTANCES
+// ============================================================
+
+const productionInit = (relays: string[], zapRelays: string[]) => {
+ // Main NDK instance for general operations
+ const ndk = new NDK({
+ explicitRelayUrls: relays
+ })
+
+ // Separate NDK for zap operations (performance optimization)
+ const zapNdk = new NDK({
+ explicitRelayUrls: zapRelays
+ })
+
+ return { ndk, zapNdk }
+}
+
+// ============================================================
+// CONNECTION WITH TIMEOUT
+// ============================================================
+
+const connectWithTimeout = async (
+ ndk: NDK,
+ timeoutMs: number = 10000
+): PromiseLoading profile...
+ }
+
+ const info = extractProfileInfo(profile)
+
+ return (
+
+ {info.avatar && 
}
+
+ )
+}
+
+// ============================================================
+// FOLLOW/UNFOLLOW USER
+// ============================================================
+
+const followUser = async (ndk: NDK, pubkeyToFollow: string) => {
+ if (!ndk.signer) {
+ throw new Error('No signer available')
+ }
+
+ // Fetch current contact list (kind 3)
+ const currentUser = await ndk.signer.user()
+ const contactListFilter = {
+ kinds: [3],
+ authors: [currentUser.pubkey]
+ }
+
+ const existingEvents = await ndk.fetchEvents(contactListFilter)
+ const existingContactList = existingEvents.size > 0
+ ? Array.from(existingEvents)[0]
+ : null
+
+ // Get existing p tags
+ const existingPTags = existingContactList
+ ? existingContactList.tags.filter(tag => tag[0] === 'p')
+ : []
+
+ // Check if already following
+ const alreadyFollowing = existingPTags.some(tag => tag[1] === pubkeyToFollow)
+ if (alreadyFollowing) {
+ console.log('Already following this user')
+ return
+ }
+
+ // Create new contact list with added user
+ const event = new NDKEvent(ndk)
+ event.kind = 3
+ event.content = existingContactList?.content || ''
+ event.tags = [
+ ...existingPTags,
+ ['p', pubkeyToFollow]
+ ]
+
+ await event.sign()
+ await event.publish()
+
+ console.log('✅ Now following user')
+}
+
+// ============================================================
+// USAGE EXAMPLE
+// ============================================================
+
+async function profileExample(ndk: NDK) {
+ // Fetch by different identifiers
+ const profile1 = await fetchProfileByNpub(ndk, 'npub1...')
+ const profile2 = await fetchProfileByNip05(ndk, 'user@domain.com')
+ const profile3 = await fetchProfileByPubkey(ndk, 'hex pubkey...')
+
+ // Extract display info
+ const info = extractProfileInfo(profile1)
+ console.log('Display name:', info.displayName)
+ console.log('Avatar:', info.avatar)
+
+ // Update own profile
+ await updateProfile(ndk, {
+ name: 'My Name',
+ about: 'My bio',
+ picture: 'https://example.com/avatar.jpg',
+ lud16: 'me@getalby.com'
+ })
+
+ // Follow someone
+ await followUser(ndk, 'pubkey to follow')
+}
+
+export {
+ fetchProfileByNpub,
+ fetchProfileByPubkey,
+ fetchProfileByNip05,
+ fetchProfileByIdentifier,
+ getCurrentUser,
+ extractProfileInfo,
+ updateProfile,
+ fetchMultipleProfiles,
+ convertPubkeyFormats,
+ useProfile,
+ followUser
+}
+
diff --git a/.claude/skills/ndk/examples/README.md b/.claude/skills/ndk/examples/README.md
new file mode 100644
index 00000000..25b990a3
--- /dev/null
+++ b/.claude/skills/ndk/examples/README.md
@@ -0,0 +1,94 @@
+# NDK Examples Index
+
+Complete code examples extracted from the Plebeian Market production codebase.
+
+## Available Examples
+
+### 01-initialization.ts
+- Basic NDK initialization
+- Multiple NDK instances (main + zap relays)
+- Connection with timeout protection
+- Connection status checking
+- Full initialization flow with error handling
+
+### 02-authentication.ts
+- NIP-07 browser extension login
+- Private key signer
+- NIP-46 remote signer (Bunker)
+- Auto-login from localStorage
+- Saving auth credentials
+- Logout functionality
+- Getting current user
+
+### 03-publishing-events.ts
+- Basic note publishing
+- Events with tags (mentions, hashtags, replies)
+- Product listings (parameterized replaceable events)
+- Order creation events
+- Status update events
+- Batch publishing
+- Custom signer usage
+- Comprehensive error handling
+
+### 04-querying-subscribing.ts
+- Basic fetch queries
+- Multiple author queries
+- Tag filtering
+- Time range filtering
+- Event ID lookup
+- Real-time subscriptions
+- Subscription cleanup patterns
+- React integration hooks
+- React Query integration
+- Waiting for specific events
+- Payment monitoring
+
+### 05-users-profiles.ts
+- Fetch profile by npub
+- Fetch profile by hex pubkey
+- Fetch profile by NIP-05
+- Universal identifier lookup
+- Get current user
+- Extract profile information
+- Update user profile
+- Batch fetch multiple profiles
+- Convert between pubkey formats (hex/npub)
+- React hooks for profiles
+- Follow/unfollow users
+
+## Usage
+
+Each file contains:
+- Fully typed TypeScript code
+- JSDoc comments explaining the pattern
+- Error handling examples
+- Integration patterns with React/TanStack Query
+- Real-world usage examples
+
+All examples are based on actual production code from the Plebeian Market application.
+
+## Running Examples
+
+```typescript
+import { initializeNDK } from './01-initialization'
+import { loginWithExtension } from './02-authentication'
+import { publishBasicNote } from './03-publishing-events'
+
+// Initialize NDK
+const { ndk, isConnected } = await initializeNDK()
+
+if (isConnected) {
+ // Authenticate
+ const { user } = await loginWithExtension(ndk)
+
+ // Publish
+ await publishBasicNote(ndk, 'Hello Nostr!')
+}
+```
+
+## Additional Resources
+
+- See `../ndk-skill.md` for detailed documentation
+- See `../quick-reference.md` for quick lookup
+- Check the main codebase for more complex patterns
+
diff --git a/.claude/skills/ndk/ndk-skill.md b/.claude/skills/ndk/ndk-skill.md
new file mode 100644
index 00000000..680fb433
--- /dev/null
+++ b/.claude/skills/ndk/ndk-skill.md
@@ -0,0 +1,701 @@
+# NDK (Nostr Development Kit) - Claude Skill Reference
+
+## Overview
+
+NDK is the primary Nostr development kit with outbox-model support, designed for building Nostr applications with TypeScript/JavaScript. This reference is based on analyzing production usage in the Plebeian Market codebase.
+
+## Core Concepts
+
+### 1. NDK Initialization
+
+**Basic Pattern:**
+```typescript
+import NDK from '@nostr-dev-kit/ndk'
+
+// Simple initialization
+const ndk = new NDK({
+ explicitRelayUrls: ['wss://relay.damus.io', 'wss://relay.nostr.band']
+})
+
+await ndk.connect()
+```
+
+**Store-based Pattern (Production):**
+```typescript
+// From src/lib/stores/ndk.ts
+const ndk = new NDK({
+ explicitRelayUrls: relays || defaultRelaysUrls,
+})
+
+// Separate NDK for zaps on specialized relays
+const zapNdk = new NDK({
+ explicitRelayUrls: ZAP_RELAYS,
+})
+
+// Connect with timeout protection
+const connectPromise = ndk.connect()
+const timeoutPromise = new Promise((_, reject) =>
+ setTimeout(() => reject(new Error('Connection timeout')), timeoutMs)
+)
+await Promise.race([connectPromise, timeoutPromise])
+```
+
+### 2. Authentication & Signers
+
+NDK supports multiple signer types for different authentication methods:
+
+#### NIP-07 (Browser Extension)
+```typescript
+import { NDKNip07Signer } from '@nostr-dev-kit/ndk'
+
+const signer = new NDKNip07Signer()
+await signer.blockUntilReady()
+ndk.signer = signer
+
+const user = await signer.user()
+```
+
+#### Private Key Signer
+```typescript
+import { NDKPrivateKeySigner } from '@nostr-dev-kit/ndk'
+
+const signer = new NDKPrivateKeySigner(privateKeyHex)
+await signer.blockUntilReady()
+ndk.signer = signer
+
+const user = await signer.user()
+```
+
+#### NIP-46 (Remote Signer / Bunker)
+```typescript
+import { NDKNip46Signer } from '@nostr-dev-kit/ndk'
+
+const localSigner = new NDKPrivateKeySigner(localPrivateKey)
+const remoteSigner = new NDKNip46Signer(ndk, bunkerUrl, localSigner)
+await remoteSigner.blockUntilReady()
+ndk.signer = remoteSigner
+
+const user = await remoteSigner.user()
+```
+
+**Key Points:**
+- Always call `blockUntilReady()` before using a signer
+- Store signer reference in your state management
+- Set `ndk.signer` to enable signing operations
+- Use `await signer.user()` to get the authenticated user
+
+### 3. Event Creation & Publishing
+
+#### Basic Event Pattern
+```typescript
+import { NDKEvent } from '@nostr-dev-kit/ndk'
+
+// Create event
+const event = new NDKEvent(ndk)
+event.kind = 1 // Kind 1 = text note
+event.content = "Hello Nostr!"
+event.tags = [
+ ['t', 'nostr'],
+ ['p', recipientPubkey]
+]
+
+// Sign and publish
+await event.sign() // Uses ndk.signer automatically
+await event.publish()
+
+// Get event ID after signing
+console.log(event.id)
+```
+
+#### Production Pattern with Error Handling
+```typescript
+// From src/publish/orders.tsx
+const event = new NDKEvent(ndk)
+event.kind = ORDER_PROCESS_KIND
+event.content = orderNotes || ''
+event.tags = [
+ ['p', sellerPubkey],
+ ['subject', `Order for ${productName}`],
+ ['type', 'order-creation'],
+ ['order', orderId],
+ ['amount', totalAmount],
+ ['item', productRef, quantity.toString()],
+]
+
+// Optional tags
+if (shippingRef) {
+ event.tags.push(['shipping', shippingRef])
+}
+
+try {
+ await event.sign(signer) // Can pass explicit signer
+ await event.publish()
+ return event.id
+} catch (error) {
+ console.error('Failed to publish event:', error)
+ throw error
+}
+```
+
+**Key Points:**
+- Create event with `new NDKEvent(ndk)`
+- Set `kind`, `content`, and `tags` properties
+- Optional: Set `created_at` timestamp (defaults to now)
+- Call `await event.sign()` before publishing
+- Call `await event.publish()` to broadcast to relays
+- Access `event.id` after signing for the event hash
+
+### 4. Querying Events with Filters
+
+#### fetchEvents() - One-time Fetch
+```typescript
+import { NDKFilter } from '@nostr-dev-kit/ndk'
+
+// Simple filter
+const filter: NDKFilter = {
+ kinds: [30402], // Product listings
+ authors: [merchantPubkey],
+ limit: 50
+}
+
+const events = await ndk.fetchEvents(filter)
+// Returns Set{info.displayName}
+ {info.bio &&{info.bio}
} + {info.nip05 && ✓ {info.nip05}} + {info.lightningAddress && ⚡ {info.lightningAddress}} +