docs: Comprehensive README updates across all folders

- Updated main README.md with recovery file feature and improved installation instructions
- Enhanced all folder READMEs with comprehensive documentation:
  - src/popup/components/README.md - Complete component documentation
  - src/sidepanel/components/README.md - Feed component details
  - src/contexts/README.md - Context API usage
  - src/offscreen/README.md - Offscreen document architecture
  - src/profile/README.md - Profile renderer details
  - src/styles/README.md - Styling and Tailwind guide
  - src/test/README.md - Test setup and mocks
  - src/utils/README.md - Added recovery file and singleton docs
  - src/background/README.md - Enhanced with logging and error handling
  - src/content/README.md - Added security and memory management
  - src/popup/README.md - Added features and keyboard shortcuts
  - src/sidepanel/README.md - Added features and performance notes
  - src/README.md - Enhanced with entry points and development guide
  - icons/README.md - Complete icon documentation
  - docs/README.md - Documentation index

All READMEs now include:
- What the folder/project is
- What it can do
- How to use features
- Architecture/technical details
- Code examples
- Related files and links
- Best practices

Author: JOHN

README.md

@@ -2,7 +2,7 @@
 
 A powerful Chrome extension that lets you **draw graffiti on web pages**, create text annotations, bookmark URLs, and share everything through the decentralized Pubky network. All your data syncs to your personal Pubky homeserver - no third-party tracking!
 
-[![Version](https://img.shields.io/badge/version-1.0.0-blue.svg)](https://github.com/yourusername/graphiti)
+[![Version](https://img.shields.io/badge/version-1.0.0-blue.svg)](https://github.com/BitcoinErrorLog/graphiti)
 [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 
 ## ✨ Features
@@ -48,12 +48,13 @@ See what your network is sharing:
 - Post your own content with tags
 - Engage with your decentralized network
 
-### 🔐 **Privacy-First Authentication**
-Secure QR-based authentication:
+### 🔐 **Privacy-First Authentication & Key Management**
+Secure QR-based authentication with key backup:
 - Scan QR code with Pubky Ring mobile app
 - No passwords, no tracking
 - Your keys, your data
 - Sessions stored locally
+- **Recovery file export** - Backup your keys with encrypted recovery files
 - Full control over your identity
 
 ### 🛠️ **Developer Tools**
@@ -68,18 +69,21 @@ Built-in debugging and monitoring:
 
 ### Installation (For Users)
 
-**Option 1: Install from ZIP**
-1. Download `graphiti-extension.zip`
-2. Extract to a folder
+**Option 1: Install from ZIP (Recommended)**
+1. Download `graphiti-extension.zip` from the repository
+2. Extract the zip file to a folder (e.g., `graphiti-extension`)
 3. Open Chrome → `chrome://extensions`
-4. Enable "Developer mode"
-5. Click "Load unpacked" → Select the `dist` folder
-6. Done! 🎉
+4. Enable "Developer mode" (toggle in top-right)
+5. Click "Load unpacked"
+6. Select the extracted folder (not the zip file itself)
+7. Done! 🎉
+
+**Note:** The zip file contains the pre-built extension. You don't need to build it yourself.
 
 **Option 2: Build from Source**
 ```bash
 # Clone the repository
-git clone https://github.com/yourusername/graphiti.git
+git clone https://github.com/BitcoinErrorLog/graphiti.git
 cd graphiti
 
 # Install dependencies
@@ -197,6 +201,25 @@ npm run build
 - **Annotations** - Text annotations on this page
 - **Your Content** - Your own posts and annotations
 
+### Profile Management
+
+**Edit Your Profile:**
+1. Click the extension icon
+2. Click "✏️ Edit Profile"
+3. Update your name, bio, avatar, status, and links
+4. Click "Save Profile" to sync to your homeserver
+
+**Export Recovery File (Key Backup):**
+1. Click the extension icon
+2. Click "✏️ Edit Profile"
+3. Scroll to "Key Backup" section
+4. Click "🔐 Export Recovery File"
+5. Enter a strong passphrase (min 8 chars, letters + numbers)
+6. Confirm the passphrase
+7. File downloads automatically (`pubky-recovery-YYYY-MM-DD.recovery`)
+
+**Important:** Store your recovery file securely! You'll need it and your passphrase to restore your keys if you lose access to your device.
+
 ## 🏗️ Architecture
 
 ### Technology Stack
@@ -584,11 +607,15 @@ MIT License - see [LICENSE](LICENSE) file for details
 - **Pubky Team** - For the innovative protocol and SDK
 - **Open Source Community** - For amazing tools and libraries
 
-## 📞 Support
+## 📞 Support & Documentation
 
-- **Issues:** [GitHub Issues](https://github.com/yourusername/graphiti/issues)
-- **Docs:** See `/docs` folder for detailed documentation
-- **Debug:** Use built-in debug panel in extension
+- **Issues:** [GitHub Issues](https://github.com/BitcoinErrorLog/graphiti/issues)
+- **Documentation:** See `/docs` folder for detailed technical documentation
+- **Features:** See [FEATURES.md](FEATURES.md) for complete feature documentation
+- **Security:** See [SECURITY.md](SECURITY.md) for security information
+- **Contributing:** See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines
+- **Changelog:** See [CHANGELOG.md](CHANGELOG.md) for version history
+- **Debug:** Use built-in debug panel in extension (click 🔧 in popup)
 
 ## 🌟 Star History
 

docs/README.md

@@ -1,20 +1,119 @@
 # Graphiti Documentation
 
-This folder contains the documentation for the Graphiti Chrome Extension.
+Comprehensive technical documentation for the Graphiti Chrome Extension.
 
 ## Documentation Structure
 
-- **[UTF16_HASH_ENCODING.md](UTF16_HASH_ENCODING.md)** - Technical specification for the UTF-16 URL hash tag encoding
-- **[ARCHITECTURE.md](ARCHITECTURE.md)** - System architecture and component overview
-- **[API_REFERENCE.md](API_REFERENCE.md)** - API client documentation
-- **[TESTING.md](TESTING.md)** - Test documentation and running tests
+This folder contains detailed documentation covering architecture, APIs, testing, and technical specifications.
+
+## Core Documentation
+
+### [ARCHITECTURE.md](ARCHITECTURE.md)
+System architecture and component overview:
+- Extension architecture
+- Component relationships
+- Data flow diagrams
+- Technology stack
+- Design patterns
+
+### [API_REFERENCE.md](API_REFERENCE.md)
+API client documentation:
+- Pubky API SDK usage
+- Nexus API client
+- Storage utilities
+- Crypto functions
+- Validation utilities
+- Code examples
+
+### [TESTING.md](TESTING.md)
+Complete testing guide:
+- Test setup and configuration
+- Writing tests
+- Running tests
+- Test coverage
+- E2E testing with Playwright
+- Best practices
+
+### [UTF16_HASH_ENCODING.md](UTF16_HASH_ENCODING.md)
+Technical specification for URL hash tag encoding:
+- UTF-16 encoding algorithm
+- Privacy-preserving URL hashing
+- Implementation details
+- Security considerations
+
+### [DEVELOPMENT.md](DEVELOPMENT.md)
+Development setup and workflow:
+- Prerequisites
+- Installation
+- Development workflow
+- Environment variables
+- Debugging
+- Hot reload
+
+### [DEPLOYMENT.md](DEPLOYMENT.md)
+Deployment and distribution:
+- Building for production
+- Chrome Web Store submission
+- Version management
+- Release process
+
+### [PERFORMANCE.md](PERFORMANCE.md)
+Performance optimization guide:
+- Bundle size optimization
+- Lazy loading
+- Code splitting
+- Performance monitoring
+- Best practices
+
+### [CONTRIBUTING_DETAILED.md](CONTRIBUTING_DETAILED.md)
+Detailed contribution guidelines:
+- Code style
+- Git workflow
+- PR process
+- Review process
+
+### [DEPENDENCY_UPGRADE_PLAN.md](DEPENDENCY_UPGRADE_PLAN.md)
+Dependency upgrade planning:
+- Upgrade priorities
+- Breaking changes tracking
+- Security updates
+- Upgrade process
 
 ## Quick Links
 
 - [Main README](../README.md) - Getting started guide
-- [Features](../FEATURES.md) - Complete feature documentation
+- [FEATURES.md](../FEATURES.md) - Complete feature documentation
+- [SECURITY.md](../SECURITY.md) - Security information
+- [CONTRIBUTING.md](../CONTRIBUTING.md) - Contribution guidelines
+- [CHANGELOG.md](../CHANGELOG.md) - Version history
 
 ## Archive
 
-The [archive/](archive/) folder contains historical development notes that were used during development. These are preserved for reference but may be outdated.
+The [archive/](archive/) folder contains:
+- Historical development notes
+- Duplicate files (gitignored)
+- Remnant documentation from development
+
+These files are preserved for reference but may be outdated.
+
+## Documentation Standards
+
+All documentation should:
+- Be clear and concise
+- Include code examples
+- Use proper markdown formatting
+- Be kept up to date
+- Include relevant links
+
+## Contributing to Documentation
+
+When adding features:
+1. Update relevant documentation files
+2. Add code examples
+3. Update API references
+4. Add to CHANGELOG.md if user-facing
+
+## See Also
 
+- [Root README](../README.md) - Main project documentation
+- [Source Code README](../src/README.md) - Source code structure

icons/README.md

@@ -1,17 +1,27 @@
 # Extension Icons
 
-Icons for the Graphiti Chrome extension.
+Icons for the Graphiti Chrome Extension at various sizes required by Chrome.
+
+## Overview
+
+The extension uses a consistent icon design across all sizes. Icons are provided in both PNG (for Chrome) and SVG (for scalable use) formats.
 
 ## Files
 
-- `icon.svg` - Source SVG icon
-- `icon16.png` - 16×16 toolbar icon
-- `icon48.png` - 48×48 extension management
-- `icon128.png` - 128×128 Chrome Web Store
-- `icon*.svg` - SVG versions at each size
+| File | Size | Usage |
+|------|------|-------|
+| `icon.svg` | Source | Source SVG file |
+| `icon16.png` | 16×16 | Toolbar icon |
+| `icon16.svg` | 16×16 | SVG version |
+| `icon48.png` | 48×48 | Extension management page |
+| `icon48.svg` | 48×48 | SVG version |
+| `icon128.png` | 128×128 | Chrome Web Store |
+| `icon128.svg` | 128×128 | SVG version |
 
 ## Usage in Manifest
 
+Icons are referenced in `manifest.json`:
+
 ```json
 {
   "icons": {
@@ -28,21 +38,60 @@ Icons for the Graphiti Chrome extension.
 }
 ```
 
+## Design
+
+The icon features:
+- **Gradient Design** - Purple to blue gradient background
+- **Rounded Corners** - Modern, friendly appearance
+- **Flat Style** - Clean, minimalist design
+- **High Contrast** - Works well at small sizes
+- **Consistent Branding** - Matches extension theme
+
+## Icon Sizes
+
+Chrome requires specific sizes:
+- **16×16** - Toolbar icon (most common view)
+- **48×48** - Extension management page (`chrome://extensions`)
+- **128×128** - Chrome Web Store listing
+
 ## Generating Icons
 
-Icon generation tools are available in `docs/archive/`:
-- `create-png-icons.js` - Script to create PNG icons
+If you need to regenerate icons:
+
+**Option 1: Use Source SVG**
+1. Edit `icon.svg` in a vector editor
+2. Export at required sizes
+3. Save as PNG files
+
+**Option 2: Use Generation Scripts**
+Scripts are available in `docs/archive/`:
+- `create-png-icons.js` - Node.js script to create PNG icons
 - `generate-icons.html` - HTML-based icon generator
 
-## Design
+## Best Practices
 
-The icon uses a gradient design with:
-- Purple to blue gradient
-- Rounded corners
-- Modern flat style
-- Works well at small sizes
+1. **Keep Source SVG** - Always maintain the source SVG file
+2. **Optimize PNGs** - Compress PNG files for smaller size
+3. **Test at All Sizes** - Verify icons look good at 16px, 48px, and 128px
+4. **Consistent Design** - All sizes should look like the same icon
+5. **High Quality** - Use high-resolution source for crisp rendering
 
-## See Also
+## File Sizes
 
-- [manifest.json](../manifest.json)
+Typical file sizes:
+- SVG: ~2-5 KB
+- PNG 16×16: ~1-2 KB
+- PNG 48×48: ~3-5 KB
+- PNG 128×128: ~8-15 KB
+
+## Accessibility
+
+Icons should:
+- Have sufficient contrast
+- Be recognizable at small sizes
+- Work in both light and dark themes (if applicable)
+
+## See Also
 
+- [manifest.json](../manifest.json) - Icon configuration
+- [Chrome Icon Guidelines](https://developer.chrome.com/docs/extensions/mv3/user_interface/#icons)

src/README.md

@@ -67,9 +67,66 @@ After running `npm run build`, compiled files are in `dist/`:
 | Popup | `popup/main.tsx` | Extension popup React app |
 | Sidepanel | `sidepanel/main.tsx` | Feed viewer React app |
 
+## Entry Points
+
+| Entry Point | Source File | Purpose |
+|-------------|-------------|---------|
+| Background | `background/background.ts` | Service worker, extension lifecycle |
+| Content | `content/content.ts` | Page injection, drawing, annotations |
+| Popup | `popup/main.tsx` | Extension popup React app |
+| Sidepanel | `sidepanel/main.tsx` | Feed viewer React app |
+| Profile | `profile/profile-renderer.ts` | Profile page renderer |
+| Offscreen | `offscreen/offscreen.ts` | Offscreen document for SDK |
+
+## Build Output
+
+After running `npm run build`, compiled files are in `dist/`:
+
+- `background.js` - Service worker
+- `content.js` - Content script
+- `popup.html` + assets - Popup UI
+- `sidepanel.html` + assets - Side panel UI
+- `src/profile/profile-renderer.html` - Profile renderer
+- `src/offscreen/offscreen.js` - Offscreen document
+
+## Development
+
+### Adding New Features
+
+**New Utility:**
+1. Create file in `utils/`
+2. Export functions/classes
+3. Add TypeScript types
+4. Write tests in `utils/__tests__/`
+
+**New Component:**
+1. Create in `popup/components/` or `sidepanel/components/`
+2. Use React + TypeScript
+3. Style with Tailwind CSS
+4. Import and use in parent component
+
+**New Content Script Feature:**
+1. Create manager class in `content/`
+2. Initialize in `content.ts`
+3. Handle messages from background
+4. Use inline styles to avoid conflicts
+
+## Testing
+
+Tests are located in `__tests__/` directories:
+- Unit tests for utilities
+- Integration tests for API clients
+- Component tests for React components
+
+Run tests with:
+```bash
+npm test
+```
+
 ## See Also
 
 - [Root README](../README.md) - Getting started
 - [FEATURES.md](../FEATURES.md) - Feature documentation
 - [docs/](../docs/) - Technical documentation
+- [CONTRIBUTING.md](../CONTRIBUTING.md) - Contribution guidelines