SyslogSolution/ra-h-os
7
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: streamline repo docs, point to ra-h.app/docs

Browse Source 
- Delete CODE_OF_CONDUCT.md (generic boilerplate)
- Simplify README.md, link to ra-h.app/docs as primary
- Simplify CONTRIBUTING.md
- Fix bug_report.md (was referencing PostgreSQL, uses SQLite)
- Gut bloated PR template
- Simplify feature_request.md
- Update docs/README.md to point to website
- Update docs/9_open-source.md
This commit is contained in:
“BeeRad”
2026-01-05 12:57:03 +11:00
parent 0f408bc907
commit 3951d9daf4
8 changed files with 119 additions and 362 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.github/ISSUE_TEMPLATE/bug_report.md
+16 -40
View File
@@ -1,53 +1,29 @@
---
name: Bug report
about: Create a report to help us improve
about: Report a bug
title: '[BUG] '
labels: bug
assignees: ''
---
## Bug Description
A clear and concise description of what the bug is.
## What happened?
## Steps to Reproduce
Steps to reproduce the behavior:
1. Go to '...'
2. Click on '....'
3. Scroll down to '....'
4. See error
## Steps to reproduce
1.
2.
3.
## Expected Behavior
A clear and concise description of what you expected to happen.
## Actual Behavior
A clear and concise description of what actually happened.
## Screenshots
If applicable, add screenshots to help explain your problem.
## Expected behavior
## Environment
- OS: [e.g., macOS 13.5, Ubuntu 22.04, Windows 11]
- Node.js Version: [e.g., 18.17.0]
- Browser: [e.g., Chrome 115, Firefox 116, Safari 16.6]
- RA-H Version: [e.g., 0.1.0]
- OS: [e.g., macOS 14.0]
- Node.js: [e.g., 18.17.0]
- Browser: [e.g., Chrome 120]
## Database Information
- PostgreSQL Version: [if known]
- Docker Version: [if using Docker]
- Any error messages from database logs
## Error messages
```
Paste any error messages here
```
## Additional Context
- Error messages (include full stack traces if available)
- Console output
- Network tab information (if API-related)
- Any other context about the problem
## Possible Solution
If you have ideas on how to fix the issue, please describe them here.
## Checklist
- [ ] I have searched existing issues to ensure this is not a duplicate
- [ ] I have provided all the requested information
- [ ] I can reproduce this issue consistently
- [ ] I have included error messages and logs where applicable
## Screenshots
If applicable.
.github/ISSUE_TEMPLATE/feature_request.md
+7 -43
View File
@@ -1,52 +1,16 @@
---
name: Feature request
about: Suggest an idea for this project
about: Suggest an idea
title: '[FEATURE] '
labels: enhancement
assignees: ''
---
## Problem Statement
A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
## Problem
What are you trying to solve?
## Proposed Solution
A clear and concise description of what you want to happen.
## Proposed solution
What would you like to see?
## Alternative Solutions
A clear and concise description of any alternative solutions or features you've considered.
## Use Cases
Describe specific use cases where this feature would be helpful:
1. Use case 1: [description]
2. Use case 2: [description]
## Implementation Ideas
If you have ideas on how this could be implemented, please describe them:
- Frontend changes needed
- Backend/API changes needed
- Database schema changes
- New dependencies required
## Priority
How important is this feature to you?
- [ ] Nice to have
- [ ] Important for my workflow
- [ ] Critical for adoption
## Mockups/Examples
If applicable, add mockups, wireframes, or examples to help explain your request.
## Additional Context
Add any other context, links to similar features in other apps, or screenshots about the feature request here.
## Acceptance Criteria
What would need to be true for this feature to be considered complete?
- [ ] Criteria 1
- [ ] Criteria 2
- [ ] Criteria 3
## Related Issues
Are there any existing issues that relate to this request?
- Fixes #
- Related to #
## Alternatives considered
Any other approaches you've thought about?
.github/pull_request_template.md
+12 -118
View File
@@ -1,125 +1,19 @@
# Pull Request
## Description
Brief description of what this PR does and why.
## What does this PR do?
## Type of Change
Please delete options that are not relevant.
## Type
- [ ] Bug fix
- [ ] New feature
- [ ] Documentation
- [ ] Refactor
- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
- [ ] Documentation update
- [ ] Code refactoring (no functional changes)
- [ ] Performance improvement
- [ ] Test coverage improvement
## Related issue
Closes #
## Related Issues
Closes #[issue number]
Related to #[issue number]
## Changes Made
- [ ] Change 1: Description
- [ ] Change 2: Description
- [ ] Change 3: Description
## How Has This Been Tested?
Please describe the tests that you ran to verify your changes:
- [ ] Unit tests
- [ ] Integration tests
- [ ] Manual testing
- [ ] API endpoint testing (if applicable)
- [ ] Database operations verified
- [ ] UI/UX testing (if applicable)
### Test Configuration
- Node.js version: [e.g., 18.17.0]
- Operating System: [e.g., macOS 13.5]
- Database: [e.g., PostgreSQL 15 with pgvector]
## Screenshots/Videos
If applicable, add screenshots or videos to demonstrate the changes.
### Before
[Screenshot/description of before state]
### After
[Screenshot/description of after state]
## Database Changes
- [ ] No database changes
- [ ] Schema changes (describe below)
- [ ] Migration required
- [ ] Seeds/fixtures updated
If database changes are made, describe them:
```sql
-- Example of schema changes
```
## API Changes
- [ ] No API changes
- [ ] New endpoints added
- [ ] Existing endpoints modified
- [ ] Breaking changes to API
If API changes are made, describe them:
```typescript
// Example of API changes
```
## Performance Impact
- [ ] No performance impact expected
- [ ] Performance improvement
- [ ] Potential performance impact (explain below)
## Security Considerations
- [ ] No security implications
- [ ] Security improvement
- [ ] Potential security impact (explain below)
## Documentation
- [ ] Documentation updated
- [ ] No documentation changes needed
- [ ] Documentation to be updated in separate PR
## Testing done
## Checklist
- [ ] My code follows the style guidelines of this project
- [ ] I have performed a self-review of my code
- [ ] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [ ] My changes generate no new warnings or errors
- [ ] I have added tests that prove my fix is effective or that my feature works
- [ ] New and existing unit tests pass locally with my changes
- [ ] Any dependent changes have been merged and published
## Deployment Notes
Special instructions for deploying this change:
- [ ] No special deployment requirements
- [ ] Environment variables need to be updated
- [ ] Database migration required
- [ ] External service configuration needed
## Breaking Changes
If this introduces breaking changes, describe the migration path:
## Additional Notes
Any additional information that reviewers should know:
---
## For Reviewers
### Review Focus Areas
Please pay special attention to:
- [ ] Code quality and style
- [ ] Test coverage
- [ ] Performance implications
- [ ] Security considerations
- [ ] Documentation accuracy
### Testing Instructions
Specific steps for reviewers to test this change:
1. Step 1
2. Step 2
3. Step 3
- [ ] `npm run build` passes
- [ ] `npm run type-check` passes
- [ ] `npm run lint` passes
CODE_OF_CONDUCT.md
-31
View File
@@ -1,31 +0,0 @@
# Contributor Covenant Code of Conduct
## Our Pledge
We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.
## Our Standards
Examples of behavior that contributes to a positive environment:
* Demonstrating empathy and kindness toward other people
* Being respectful of differing opinions, viewpoints, and experiences
* Giving and gracefully accepting constructive feedback
* Accepting responsibility and apologizing to those affected by our mistakes
* Focusing on what is best for the overall community
Examples of unacceptable behavior:
* The use of sexualized language or imagery, and sexual attention or advances of any kind
* Trolling, insulting or derogatory comments, and personal or political attacks
* Public or private harassment
* Publishing others' private information without explicit permission
* Other conduct which could reasonably be considered inappropriate in a professional setting
## Enforcement
Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the project maintainers. All complaints will be reviewed and investigated promptly and fairly.
## Attribution
This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.1.
CONTRIBUTING.md
+12 -24
View File
@@ -1,24 +1,18 @@
# Contributing to RA-H Open Source
# Contributing
This is the **open source mirror** of a private repository. Features are developed privately and synced here periodically.
This is the open source mirror of a private repository. Features are developed privately and synced here.
## How to Contribute
**Full docs:** [ra-h.app/docs](https://ra-h.app/docs)
### Bug Reports & Feature Requests
Open an [issue](../../issues). Include:
- What you expected vs what happened
- Steps to reproduce (for bugs)
- Your environment (OS, Node version, browser)
## What We Accept
### Code Contributions
We accept pull requests for:
- **Bug fixes** - especially ones you've encountered
- **Documentation improvements** - typos, clarifications, examples
- **Small enhancements** - that don't require architectural changes
- **Bug fixes** – especially ones you've encountered
- **Doc improvements** – typos, clarifications, examples
- **Small enhancements** – that don't require architectural changes
For **larger features**, open an issue first to discuss. Major features are typically implemented in the private repo and synced here.
For larger features, open an issue first. Major features are typically implemented in the private repo and synced here.
## Development Setup
## Setup
```bash
git clone https://github.com/bradwmorris/ra-h_os.git
@@ -29,8 +23,6 @@ scripts/dev/bootstrap-local.sh
npm run dev
```
Open http://localhost:3000 and add your API keys.
## Before Submitting a PR
```bash
@@ -50,18 +42,14 @@ All three must pass.
## What Happens to Your Contribution
1. We review and merge to this repo
2. If applicable, we port the fix to the private repo
1. We review and merge here
2. If applicable, we port to the private repo
3. Future syncs won't overwrite your contribution
## Code of Conduct
Be respectful. No harassment, trolling, or personal attacks. Focus on constructive feedback.
## License
By contributing, you agree your work is licensed under [MIT](LICENSE).
## Questions?
Open a [discussion](../../discussions) or check existing issues.
Check [ra-h.app/docs](https://ra-h.app/docs) or open an issue.
README.md
+46 -70
View File
@@ -1,38 +1,19 @@
# RA-H Open Source
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![Node.js 18+](https://img.shields.io/badge/Node.js-18%2B-green.svg)](https://nodejs.org/)
A local-first AI research workspace. Full 3-panel interface, vector search, content ingestion, workflows, and conversation agents. BYO API keys, no cloud dependencies.
A local-first research workspace with the complete RA-H three-panel interface, vector search, content ingestion, workflows, and conversation agents. This edition removes the Mac packaging, hosted authentication, and subscription backend so you can run everything locally with your own API keys.
**Full Documentation:** [ra-h.app/docs](https://ra-h.app/docs)
## Platform Support
| Platform | Status | Notes |
|----------|--------|-------|
| **macOS (Apple Silicon)** | ✅ Fully Supported | M1/M2/M3/M4 Macs |
| **macOS (Intel)** | ✅ Fully Supported | Pre-2020 Macs |
| **Linux** | 🚧 Coming Soon | Requires manual sqlite-vec build |
| **Windows** | 🚧 Coming Soon | Requires manual sqlite-vec build |
| Platform | Status |
|----------|--------|
| macOS (Apple Silicon) | ✅ Supported |
| macOS (Intel) | ✅ Supported |
| Linux | 🚧 Coming (requires manual sqlite-vec build) |
| Windows | 🚧 Coming (requires manual sqlite-vec build) |
> **Note:** The bundled `sqlite-vec` and `yt-dlp` binaries are macOS-only. Linux/Windows users can still run the app but need to compile sqlite-vec manually. See [Advanced Setup](#advanced-setup-linuxwindows) below.
## Features
- **3-Panel interface** – Explore nodes, focus, and chat with the orchestrator in one view
- **Bring-your-own keys** – Works with your Anthropic/OpenAI keys only; nothing is sent to RA-H
- **Local SQLite + sqlite-vec** – Semantic search, workflows, and embeddings run on your machine
- **Content extraction** – YouTube, PDF, and web extraction pipelines included
- **Extensible workflows** – Integrate workflow + tool registry ship intact for further hacking
- **MCP Server** – Connect Claude, ChatGPT, or any MCP-compatible assistant to your knowledge graph
## Getting Started
### Prerequisites
- Node.js 18+
- npm 9+
- macOS (for pre-built sqlite-vec binary)
### Install & Bootstrap
## Quick Start
```bash
git clone https://github.com/bradwmorris/ra-h_os.git
@@ -43,79 +24,74 @@ scripts/dev/bootstrap-local.sh
npm run dev
```
Open http://localhost:3000, then go to **Settings → API Keys** and add your OpenAI/Anthropic keys.
Open http://localhost:3000 → **Settings → API Keys** → add your OpenAI/Anthropic keys.
### Environment
## Features
- `.env.example` documents all supported variables
- Run the bootstrap script to create `.env.local`
- Custom paths: set `SQLITE_DB_PATH` and `SQLITE_VEC_EXTENSION_PATH`
- **3-Panel interface** – Nodes, focus, and chat in one view
- **BYO keys** – Your Anthropic/OpenAI keys only; nothing sent to RA-H
- **Local SQLite + sqlite-vec** – Semantic search and embeddings on your machine
- **Content extraction** – YouTube, PDF, web pipelines included
- **Workflows** – Editable JSON workflows for common tasks
- **MCP Server** – Connect Claude Code, ChatGPT, or any MCP-compatible assistant
## Project Layout
```
app/ Next.js App Router entrypoints
app/ Next.js App Router
src/
components/ UI building blocks
services/ Agents, embeddings, ingestion, storage, workflows
tools/ Agent tools (queryNodes, etc.)
components/ UI
services/ Agents, embeddings, ingestion, storage
tools/ Agent tools
config/ Prompts, workflows
apps/mcp-server/ MCP server for external AI assistants
docs/ Architecture + schema docs
scripts/ Local dev helpers (bootstrap, sqlite backup/restore)
docs/ Local docs (mirrors ra-h.app/docs)
scripts/ Dev helpers
vendor/ Pre-built binaries (sqlite-vec, yt-dlp)
```
## Development Scripts
## Commands
| Command | Description |
|---------|-------------|
| `npm run dev` | Local dev server at localhost:3000 |
| `npm run dev` | Dev server at localhost:3000 |
| `npm run build` | Production build |
| `npm run type-check` | TypeScript validation |
| `npm run lint` | ESLint check |
| `npm run sqlite:backup` | Database snapshot |
| `npm run sqlite:restore` | Restore from backup |
## Documentation
- [docs/README.md](docs/README.md) – Documentation index
- [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) – Common issues and fixes
- [docs/0_overview.md](docs/0_overview.md) – Product background
- [docs/1_architecture.md](docs/1_architecture.md) – Technical architecture
- [docs/2_schema.md](docs/2_schema.md) – Database schema + sqlite-vec
**Primary:** [ra-h.app/docs](https://ra-h.app/docs)
Local reference:
- [docs/0_overview.md](docs/0_overview.md) – Overview
- [docs/1_architecture.md](docs/1_architecture.md) – Architecture
- [docs/2_schema.md](docs/2_schema.md) – Database schema
- [docs/8_mcp.md](docs/8_mcp.md) – MCP server setup
- [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) – Common issues
## Advanced Setup (Linux/Windows)
## Linux/Windows Setup
The app works on Linux/Windows but requires manually compiled binaries:
The bundled `sqlite-vec` and `yt-dlp` binaries are macOS-only. For other platforms:
### sqlite-vec (required for vector search)
**sqlite-vec** (required for vector search):
1. Clone https://github.com/asg017/sqlite-vec
2. Build for your platform
3. Place at `vendor/sqlite-extensions/vec0.so` (Linux) or `vec0.dll` (Windows)
4. Set `SQLITE_VEC_EXTENSION_PATH` in `.env.local`
1. Clone: https://github.com/asg017/sqlite-vec
2. Build for your platform (see their README)
3. Place binary at:
- Linux: `vendor/sqlite-extensions/vec0.so`
- Windows: `vendor/sqlite-extensions/vec0.dll`
4. Update `SQLITE_VEC_EXTENSION_PATH` in `.env.local`
**yt-dlp** (required for YouTube extraction):
1. Download from https://github.com/yt-dlp/yt-dlp/releases
2. Place at `vendor/bin/yt-dlp`
3. `chmod +x vendor/bin/yt-dlp` (Linux)
### yt-dlp (required for YouTube extraction)
1. Download from: https://github.com/yt-dlp/yt-dlp/releases
2. Place at `vendor/bin/yt-dlp` (or `yt-dlp.exe` on Windows)
3. Make executable: `chmod +x vendor/bin/yt-dlp` (Linux)
**What works without sqlite-vec:** UI, node CRUD, basic search, chat, content extraction
**What requires sqlite-vec:** Semantic/vector search, embedding-based agent tools
Without sqlite-vec: UI, node CRUD, basic search, chat, and content extraction still work. Vector/semantic search requires it.
## Contributing
Issues and PRs are welcome! Please read:
- [CONTRIBUTING.md](CONTRIBUTING.md) – Contribution guidelines
- [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) – Community standards
- [SECURITY.md](SECURITY.md) – Vulnerability reporting
See [CONTRIBUTING.md](CONTRIBUTING.md). Issues and PRs welcome.
## License
Released under the [MIT License](LICENSE).
[MIT](LICENSE)
docs/9_open-source.md
+9 -6
View File
@@ -1,6 +1,8 @@
# RA-H Open Source
This is the open source, BYO-key (bring your own API keys) version of RA-H.
**Full docs:** [ra-h.app/docs](https://ra-h.app/docs)
This is the open source, BYO-key version of RA-H.
## What's Included
@@ -8,6 +10,7 @@ This is the open source, BYO-key (bring your own API keys) version of RA-H.
- Local SQLite storage with vector search
- Complete agent system (ra-h, mini-rah, wise-rah)
- All tools and workflows
- MCP server for external AI assistants
- Settings panel with API key management
## What's Not Included
@@ -17,14 +20,14 @@ This is the open source, BYO-key (bring your own API keys) version of RA-H.
- Subscription/payment system
- Auto-updates
## Relationship to Private Repo
## Relationship to Main Repo
This repo is a **mirror** of the private `ra-h` repository. Features are developed privately and synced here periodically.
This repo is a mirror of the private `ra-h` repository. Features are developed privately and synced here.
- **Contributions welcome** - See [CONTRIBUTING.md](../CONTRIBUTING.md)
- **Bug reports** - Open an issue on GitHub
- **Feature requests** - Open an issue; major features are typically built in the private repo first
- **Bug reports** - Open an issue
- **Feature requests** - Open an issue; major features typically built privately first
## Setup
See the main [README.md](../README.md) for installation instructions.
See [README.md](../README.md) for installation.
docs/README.md
+17 -30
View File
@@ -1,46 +1,33 @@
# RA-H Documentation
Technical documentation for RA-H — AI-powered knowledge management.
**Primary documentation:** [ra-h.app/docs](https://ra-h.app/docs)
The website docs are the source of truth. These local docs are a reference mirror.
## Quick Links
- **Full Docs:** [ra-h.app/docs](https://ra-h.app/docs)
- **Website:** [ra-h.app](https://ra-h.app)
- **Download:** [ra-h.app/download](https://ra-h.app/download)
- **Open Source:** [github.com/bradwmorris/ra-h_os](https://github.com/bradwmorris/ra-h_os)
- **GitHub:** [github.com/bradwmorris/ra-h_os](https://github.com/bradwmorris/ra-h_os)
## Documentation Index
## Local Reference
| # | Document | Description |
|---|----------|-------------|
| 0 | [Overview](./0_overview.md) | What is RA-H, design philosophy, tech stack |
| 0 | [Overview](./0_overview.md) | What is RA-H, design philosophy |
| 1 | [Architecture](./1_architecture.md) | Agent hierarchy, system design |
| 2 | [Schema](./2_schema.md) | Database schema, nodes, edges, embeddings |
| 3 | [Context & Memory](./3_context-and-memory.md) | Auto-context system, how agents see your knowledge |
| 4 | [Tools & Workflows](./4_tools-and-workflows.md) | Available tools, editable workflows |
| 5 | [Logging & Evals](./5_logging-and-evals.md) | Debugging, evaluation framework |
| 6 | [UI](./6_ui.md) | 3-panel layout, views, Settings |
| 7 | [Voice](./7_voice.md) | Voice interface (STT/TTS) |
| 8 | [MCP Server](./8_mcp.md) | External agent connector (Claude Code, etc.) |
| 9 | [Open Source](./9_open-source.md) | Sync strategy, repo differences |
| 3 | [Context & Memory](./3_context-and-memory.md) | Auto-context system |
| 4 | [Tools & Workflows](./4_tools-and-workflows.md) | Available tools, workflows |
| 5 | [Logging & Evals](./5_logging-and-evals.md) | Debugging, evaluation |
| 6 | [UI](./6_ui.md) | 3-panel layout, views |
| 7 | [Voice](./7_voice.md) | Voice interface |
| 8 | [MCP Server](./8_mcp.md) | External agent connector |
## For Users
## Troubleshooting
Start here:
1. [Overview](./0_overview.md) — What RA-H is and how it works
2. [MCP Server](./8_mcp.md) — Connect Claude Code to your knowledge base
See [TROUBLESHOOTING.md](./TROUBLESHOOTING.md) for common issues.
## For Developers
## Questions?
If you're contributing or self-hosting:
1. [Architecture](./1_architecture.md) — Understand the agent hierarchy
2. [Schema](./2_schema.md) — Database structure
3. [Tools & Workflows](./4_tools-and-workflows.md) — How to extend RA-H
4. [Open Source](./9_open-source.md) — Contribution workflow
## Development Process
Internal development docs are in `docs/development/`:
- `process/` — Workflow, handoff, kickstart
- `backlog/` — Task backlog
- `prd-*.md` — Product requirement documents
- `completed/` — Archived PRDs
Check [ra-h.app/docs](https://ra-h.app/docs) or open an issue on GitHub.