From 3951d9daf43854c321d9348baf43bde3a12ee0d4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9CBeeRad=E2=80=9D?= Date: Mon, 5 Jan 2026 12:57:03 +1100 Subject: [PATCH] docs: streamline repo docs, point to ra-h.app/docs - 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 --- .github/ISSUE_TEMPLATE/bug_report.md | 56 +++------- .github/ISSUE_TEMPLATE/feature_request.md | 50 ++------- .github/pull_request_template.md | 130 ++-------------------- CODE_OF_CONDUCT.md | 31 ------ CONTRIBUTING.md | 36 ++---- README.md | 116 ++++++++----------- docs/9_open-source.md | 15 ++- docs/README.md | 47 +++----- 8 files changed, 119 insertions(+), 362 deletions(-) delete mode 100644 CODE_OF_CONDUCT.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index 8f1f798..48c3b99 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -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 \ No newline at end of file +## Screenshots +If applicable. diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md index 8f5c926..3ac9875 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.md +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -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 # \ No newline at end of file +## Alternatives considered +Any other approaches you've thought about? diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 529fae5..3b4a020 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -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 \ No newline at end of file +- [ ] `npm run build` passes +- [ ] `npm run type-check` passes +- [ ] `npm run lint` passes diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md deleted file mode 100644 index 15dc4dd..0000000 --- a/CODE_OF_CONDUCT.md +++ /dev/null @@ -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. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8723714..37fcec3 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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. diff --git a/README.md b/README.md index 1f62ae1..7551e6d 100644 --- a/README.md +++ b/README.md @@ -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) diff --git a/docs/9_open-source.md b/docs/9_open-source.md index cdad25e..0456f0e 100644 --- a/docs/9_open-source.md +++ b/docs/9_open-source.md @@ -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. diff --git a/docs/README.md b/docs/README.md index fa22d74..30981e0 100644 --- a/docs/README.md +++ b/docs/README.md @@ -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.