Initial commit: RA-H Open Source Edition

Local-first knowledge management system with BYO API keys. Features: - 3-panel UI (Nodes | Focus | Helpers) - SQLite + sqlite-vec for vector search - Agent system (Easy/Hard mode orchestrators) - Content extraction (YouTube, PDF, web) - Integrate workflow for connection discovery - Dimension system with auto-assignment Tech stack: - Next.js 15 + TypeScript + Tailwind CSS - Anthropic (Claude) + OpenAI (GPT) via Vercel AI SDK Setup: npm install && npm rebuild better-sqlite3 scripts/dev/bootstrap-local.sh npm run dev MIT License
2025-12-15 16:14:28 +11:00
commit 733d1c3407
226 changed files with 46231 additions and 0 deletions
@@ -0,0 +1,173 @@
+# Contributing to RA-H
+
+Thank you for your interest in contributing to RA-H! This guide explains how to work inside the private repo that powers the packaged Mac app.
+
+> **Licensing note:** By contributing, you agree that your contributions are provided under the [PolyForm Noncommercial License 1.0.0](LICENSE). If you need a commercial exception, contact hello@ra-h.app before submitting changes.
+
+## 🎯 Ways to Contribute
+
+- **🐛 Bug Reports**: Found a bug? Let us know!
+- **💡 Feature Requests**: Have ideas for new features?
+- **📝 Documentation**: Help improve our docs
+- **🔧 Code Contributions**: Fix bugs or implement features
+- **🧪 Testing**: Help us test new features and find edge cases
+
+## 🚀 Getting Started
+
+### Development Setup
+Begin with `docs/development/process/0_kickstart.md` for internal context. When touching the desktop build, read `docs/development/process/6_macpack.md` so you follow the packaging checklist. `docs/9_open-source.md` simply tracks the future BYO-key repo idea; there is no public OSS workflow today.
+
+### Development Workflow
+**Important**: We use Claude Code for all development. Follow the 7-step workflow documented in `docs/development/process/1_workflow.md`:
+
+1. **Review** - Read handoff and workflow docs
+2. **Branch** - Create feature branch (NEVER work on main)
+3. **Plan** - Write PRD and get approval  
+4. **Implement** - Code with user testing
+5. **Document** - Update handoff and CLAUDE.md
+6. **Commit** - Save and merge to main
+7. **Cleanup** - Delete branch, confirm clean state
+
+### Quick Commands
+```bash
+# Start new feature
+git checkout main && git pull && git checkout -b feature/your-name
+
+# Basic development
+npm run build && npm run type-check && npm run lint
+
+# Clean generated artefacts before committing
+npm run clean:local
+```
+
+## 📝 Code Standards
+
+### TypeScript
+- Use strict TypeScript - no `any` types unless absolutely necessary
+- Provide proper type definitions for all functions and objects
+- Use meaningful interface names
+
+### React/Next.js
+- Use functional components with hooks
+- Follow Next.js App Router patterns
+- Use proper error boundaries
+
+### Database
+- All database operations must use the service layer (`/src/services/database/`)
+- No direct SQL in components - use service methods
+- Include proper error handling
+
+### Styling
+- Use Tailwind CSS utilities
+- Follow the existing color scheme (dark theme)
+- Ensure responsive design
+
+## 🏗️ Project Architecture
+
+See `docs/overview.md` for complete system architecture.
+
+### Key Patterns
+- Use service layer for all database operations
+- Components organized by feature area
+- Helpers are JSON-configured AI assistants
+- All development follows 7-step Claude Code workflow
+
+
+## 🧪 Testing
+Manual testing is primary - use `npm run build && npm run type-check && npm run lint` to verify changes.
+
+## 📚 Documentation
+
+### What to Document
+- New features and their usage
+- API endpoint changes
+- Database schema modifications
+- Breaking changes
+
+### Documentation Style
+- Use clear, concise language
+- Include code examples
+- Add screenshots for UI changes
+- Keep README.md updated
+
+## 🚨 Issue Reporting
+
+### Bug Reports
+Include:
+- Steps to reproduce
+- Expected vs actual behavior
+- Environment details (OS, Node version, etc.)
+- Screenshots if applicable
+- Error messages/logs
+
+### Feature Requests
+Include:
+- Clear problem description
+- Proposed solution
+- Use cases
+- Alternatives considered
+
+## 🔍 Pull Request Process
+
+### Before Submitting
+- [ ] Tests pass locally
+- [ ] Code follows our style guide
+- [ ] Documentation updated if needed
+- [ ] Branch is up to date with main
+
+### PR Template
+We'll provide a template, but include:
+- **Description**: What does this PR do?
+- **Type**: Bug fix, feature, docs, etc.
+- **Testing**: How was this tested?
+- **Screenshots**: For UI changes
+
+### Review Process
+1. Automated checks must pass
+2. At least one maintainer review required
+3. Address feedback promptly
+4. Squash commits before merge
+
+## 🏷️ Labels and Tagging
+
+We use these labels:
+- `bug` - Something isn't working
+- `enhancement` - New feature or request
+- `documentation` - Improvements to docs
+- `good first issue` - Good for newcomers
+- `help wanted` - Extra attention needed
+- `priority: high/medium/low` - Priority levels
+
+## 💬 Communication
+
+### Channels
+- **Issues**: Bug reports and feature requests
+- **Discussions**: General questions and ideas
+- **Pull Requests**: Code review discussions
+
+### Code of Conduct
+- Be respectful and inclusive
+- Focus on constructive feedback
+- Help others learn and grow
+- Follow our [Code of Conduct](CODE_OF_CONDUCT.md)
+
+## 🎉 Recognition
+
+Contributors will be:
+- Listed in our README acknowledgments
+- Mentioned in release notes
+- Invited to join our contributors team
+
+## 📞 Getting Help
+
+Stuck? Need help?
+- Check existing issues and discussions
+- Create a new discussion for questions
+- Tag maintainers in issues if urgent
+- Join our community discussions
+
+---
+
+**Happy Contributing!** 🚀
+
+Your contributions help make RA-H better for everyone. Thank you for being part of our open-source community!