fix: OS release prep - bootstrap script, deps, docs
- Fix bootstrap script (.env.example.local → .env.example) - Fix @langchain/core version conflict (^1.0.1 → ^0.3.0) - Add settings:open event listener for LocalKeyGate button - Pin Next.js to 15.1.3 (was "latest") - Default runtime to 'local' mode - Remove desktop app references from UI text - Rewrite MCP docs for web-only context - Add SECURITY.md, CODE_OF_CONDUCT.md, CHANGELOG.md - Add docs/README.md, docs/TROUBLESHOOTING.md - Update README with platform support table 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
“BeeRad”
co-authored by
Claude Opus 4.5
Claude Opus 4.5
parent
ffbd47563e
commit
0e6bf12ad3
@@ -0,0 +1,22 @@
|
|||||||
|
# Changelog
|
||||||
|
|
||||||
|
All notable changes to this project will be documented in this file.
|
||||||
|
|
||||||
|
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
|
||||||
|
|
||||||
|
## [0.1.0] - 2025-01-XX
|
||||||
|
|
||||||
|
### Added
|
||||||
|
- Initial open source release
|
||||||
|
- BYO-key authentication (OpenAI, Anthropic)
|
||||||
|
- Full 3-panel interface (Nodes | Focus | Chat)
|
||||||
|
- Vector search with sqlite-vec
|
||||||
|
- Integrate workflow for connection discovery
|
||||||
|
- Content extraction (YouTube, PDF, web)
|
||||||
|
- Easy/Hard mode toggle (GPT vs Claude)
|
||||||
|
- MCP server for external AI assistants
|
||||||
|
- Local SQLite database with embeddings
|
||||||
|
|
||||||
|
### Notes
|
||||||
|
- macOS only for v0.1.0 (Linux/Windows support coming)
|
||||||
|
- Requires Node.js 18+ and native build tools for better-sqlite3
|
||||||
@@ -0,0 +1,31 @@
|
|||||||
|
# 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.
|
||||||
@@ -1,64 +1,121 @@
|
|||||||
# RA-H Open Source
|
# RA-H Open Source
|
||||||
|
|
||||||
|
[](LICENSE)
|
||||||
|
[](https://nodejs.org/)
|
||||||
|
|
||||||
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.
|
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.
|
||||||
|
|
||||||
|
## 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 |
|
||||||
|
|
||||||
|
> **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
|
## 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.
|
- **3-Panel interface** – Explore nodes, focus, and chat with the orchestrator in one view
|
||||||
- **Local SQLite + sqlite-vec** – Semantic search, workflows, and memories run on your machine.
|
- **Bring-your-own keys** – Works with your Anthropic/OpenAI keys only; nothing is sent to RA-H
|
||||||
- **Content extraction** – YouTube, PDF, and web extraction pipelines included.
|
- **Local SQLite + sqlite-vec** – Semantic search, workflows, and embeddings run on your machine
|
||||||
- **Extensible workflows** – Integrate workflow + tool registry ship intact for further hacking.
|
- **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
|
## Getting Started
|
||||||
|
|
||||||
### Prerequisites
|
### Prerequisites
|
||||||
- Node.js 20+
|
- Node.js 18+
|
||||||
- npm 10+
|
- npm 9+
|
||||||
- SQLite with `sqlite-vec` extension (prebuilt macOS binary is under `vendor/sqlite-extensions/vec0.dylib`; see `docs/2_schema.md` for build instructions on Linux/Windows)
|
- macOS (for pre-built sqlite-vec binary)
|
||||||
|
|
||||||
### Install & Bootstrap
|
### Install & Bootstrap
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
git clone https://github.com/bradwmorris/ra-h_os.git
|
git clone https://github.com/bradwmorris/ra-h_os.git
|
||||||
cd ra-h_os
|
cd ra-h_os
|
||||||
npm install
|
npm install
|
||||||
scripts/dev/bootstrap-local.sh # seeds SQLite schema + local env template
|
npm rebuild better-sqlite3
|
||||||
npm run dev # http://localhost:3000
|
scripts/dev/bootstrap-local.sh
|
||||||
|
npm run dev
|
||||||
```
|
```
|
||||||
|
|
||||||
When the UI loads, open **Settings → API Keys** and paste your OpenAI/Anthropic keys. They are stored locally via `src/services/storage/apiKeys.ts`.
|
Open http://localhost:3000, then go to **Settings → API Keys** and add your OpenAI/Anthropic keys.
|
||||||
|
|
||||||
### Environment
|
### Environment
|
||||||
- `.env.example` documents every supported variable and defaults to `NEXT_PUBLIC_DEPLOYMENT_MODE=local`.
|
|
||||||
- Custom database paths: set `SQLITE_DB_PATH` and `SQLITE_VEC_EXTENSION_PATH`.
|
- `.env.example` documents all supported variables
|
||||||
- No `.env.local` ships with the repo—run the bootstrap script to create yours.
|
- Run the bootstrap script to create `.env.local`
|
||||||
|
- Custom paths: set `SQLITE_DB_PATH` and `SQLITE_VEC_EXTENSION_PATH`
|
||||||
|
|
||||||
## Project Layout
|
## Project Layout
|
||||||
|
|
||||||
```
|
```
|
||||||
app/ Next.js App Router entrypoints
|
app/ Next.js App Router entrypoints
|
||||||
components/ UI building blocks (auth/tauri removed)
|
src/
|
||||||
docs/ Architecture + schema docs (updated for local mode)
|
components/ UI building blocks
|
||||||
scripts/ Local dev helpers (bootstrap, sqlite backup/restore, audits)
|
services/ Agents, embeddings, ingestion, storage, workflows
|
||||||
src/services/ Agents, embeddings, ingestion, storage, workflows
|
tools/ Agent tools (queryNodes, etc.)
|
||||||
vendor/sqlite-extensions/vec0.dylib macOS sqlite-vec build
|
config/ Prompts, workflows
|
||||||
|
apps/mcp-server/ MCP server for external AI assistants
|
||||||
|
docs/ Architecture + schema docs
|
||||||
|
scripts/ Local dev helpers (bootstrap, sqlite backup/restore)
|
||||||
|
vendor/ Pre-built binaries (sqlite-vec, yt-dlp)
|
||||||
```
|
```
|
||||||
|
|
||||||
## Development Scripts
|
## Development Scripts
|
||||||
- `npm run dev` – Local Next.js dev server (local mode forced)
|
|
||||||
- `npm run build` / `npm start` – Production build/start in local-only mode
|
| Command | Description |
|
||||||
- `npm run lint`, `npm run type-check` – Quality gates
|
|---------|-------------|
|
||||||
- `npm run sqlite:backup` / `npm run sqlite:restore` – Database snapshots
|
| `npm run dev` | Local 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
|
## Documentation
|
||||||
- `docs/0_overview.md` – Product background
|
|
||||||
- `docs/1_architecture.md` – Agents, tools, and workflow internals
|
|
||||||
- `docs/2_schema.md` – SQLite schema + sqlite-vec setup
|
|
||||||
- `docs/4_tools-and-workflows.md` – Tool registry + workflow guide
|
|
||||||
- `docs/9_open-source.md` – Local BYO-key process tracking
|
|
||||||
|
|
||||||
Private runbooks, Supabase CRM docs, and Mac packaging instructions were removed from this tree. See `docs/os_docs/2025-02-09-open-source-porting-notes.md` for details on what was changed from the private repo.
|
- [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
|
||||||
|
- [docs/8_mcp.md](docs/8_mcp.md) – MCP server setup
|
||||||
|
|
||||||
|
## Advanced Setup (Linux/Windows)
|
||||||
|
|
||||||
|
The app works on Linux/Windows but requires manually compiled binaries:
|
||||||
|
|
||||||
|
### sqlite-vec (required for vector search)
|
||||||
|
|
||||||
|
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` (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
|
||||||
|
|
||||||
## Contributing
|
## Contributing
|
||||||
Issues and PRs are welcome! Please open a draft PR with context on the feature/fix, list any new environment requirements, and include manual test notes. See `CONTRIBUTING.md` for the lightweight guidelines.
|
|
||||||
|
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
|
||||||
|
|
||||||
## License
|
## License
|
||||||
Released under the [MIT License](LICENSE). By contributing you agree that your code is provided under the same license.
|
|
||||||
|
Released under the [MIT License](LICENSE).
|
||||||
|
|||||||
+34
@@ -0,0 +1,34 @@
|
|||||||
|
# Security Policy
|
||||||
|
|
||||||
|
## Reporting a Vulnerability
|
||||||
|
|
||||||
|
If you discover a security vulnerability, please report it privately:
|
||||||
|
|
||||||
|
1. **Do NOT open a public issue**
|
||||||
|
2. Email: security@ra-h.app (or use GitHub Security Advisories)
|
||||||
|
3. Include: description, steps to reproduce, potential impact
|
||||||
|
|
||||||
|
We will respond within 48 hours and work with you on a fix.
|
||||||
|
|
||||||
|
## Supported Versions
|
||||||
|
|
||||||
|
| Version | Supported |
|
||||||
|
|---------|-----------|
|
||||||
|
| 0.1.x | ✅ |
|
||||||
|
|
||||||
|
## Security Considerations
|
||||||
|
|
||||||
|
### API Keys
|
||||||
|
- API keys are stored locally in your browser's localStorage
|
||||||
|
- Keys are never sent to any server except the respective AI provider (OpenAI, Anthropic)
|
||||||
|
- Clear your browser data to remove stored keys
|
||||||
|
|
||||||
|
### Local Database
|
||||||
|
- All data is stored locally in SQLite at `~/Library/Application Support/RA-H/db/rah.sqlite`
|
||||||
|
- No data is sent to external servers (except AI API calls with your keys)
|
||||||
|
- Back up this file to preserve your data
|
||||||
|
|
||||||
|
### MCP Server
|
||||||
|
- The MCP server binds only to `127.0.0.1` (localhost)
|
||||||
|
- Do not expose it to external networks
|
||||||
|
- Only connect trusted AI assistants
|
||||||
+76
-29
@@ -1,45 +1,92 @@
|
|||||||
# RA-H MCP Connector Setup
|
# RA-H MCP Server Setup
|
||||||
|
|
||||||
The desktop app now ships with a local Model Context Protocol (MCP) server so any MCP‑compatible assistant (Claude, ChatGPT, Gemini, Codex, etc.) can read/write your RA-H graph. Everything runs on `127.0.0.1` and never leaves your Mac.
|
RA-H includes a local Model Context Protocol (MCP) server that lets any MCP-compatible assistant (Claude, ChatGPT, Gemini, etc.) read/write your knowledge graph. Everything runs on `127.0.0.1` and never leaves your machine.
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
|
||||||
|
The MCP server is a standalone Node.js process that bridges external AI assistants to your local RA-H database. In the open source version, you run this server manually alongside the Next.js dev server.
|
||||||
|
|
||||||
## Quick Start
|
## Quick Start
|
||||||
|
|
||||||
1. Launch the RA-H desktop app (it boots the Next.js sidecar + MCP bridge automatically).
|
### 1. Start the Next.js Server
|
||||||
2. Open **Settings → External Agents** inside RA-H and copy the connector URL (example: `http://127.0.0.1:44145/mcp`).
|
|
||||||
3. In Claude, ChatGPT, or any other assistant:
|
|
||||||
- open the MCP/connectors panel,
|
|
||||||
- choose **Add connector → HTTP**,
|
|
||||||
- paste the copied URL and name it “RA-H”.
|
|
||||||
4. Talk naturally. Examples:
|
|
||||||
- “Summarize this chat and add it to RA-H under Strategy + Q1 Execution.”
|
|
||||||
- “Search RA-H for what I already wrote about Apollo launch delays.”
|
|
||||||
|
|
||||||
The assistant calls two tools behind the scenes:
|
```bash
|
||||||
|
npm run dev
|
||||||
|
```
|
||||||
|
|
||||||
|
This starts the web app at `http://localhost:3000`.
|
||||||
|
|
||||||
|
### 2. Start the MCP Server
|
||||||
|
|
||||||
|
In a separate terminal:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
node apps/mcp-server/server.js
|
||||||
|
```
|
||||||
|
|
||||||
|
The MCP server will start on port `44145` by default.
|
||||||
|
|
||||||
|
### 3. Connect Your Assistant
|
||||||
|
|
||||||
|
1. Open **Settings → External Agents** in RA-H and copy the connector URL: `http://127.0.0.1:44145/mcp`
|
||||||
|
2. In Claude, ChatGPT, or your assistant:
|
||||||
|
- Open the MCP/connectors panel
|
||||||
|
- Choose **Add connector → HTTP**
|
||||||
|
- Paste the URL and name it "RA-H"
|
||||||
|
|
||||||
|
### 4. Use It
|
||||||
|
|
||||||
|
Talk naturally:
|
||||||
|
- "Summarize this chat and add it to RA-H under Strategy + Q1 Execution."
|
||||||
|
- "Search RA-H for what I already wrote about Apollo launch delays."
|
||||||
|
|
||||||
|
## Available Tools
|
||||||
|
|
||||||
| Tool | Description |
|
| Tool | Description |
|
||||||
| --- | --- |
|
|------|-------------|
|
||||||
| `rah_add_node` | Adds a new entry (title/content/dimensions) to the local SQLite graph and triggers the auto-embed queue. |
|
| `rah_add_node` | Adds a new entry (title/content/dimensions) to the local SQLite graph and triggers auto-embedding. |
|
||||||
| `rah_search_nodes` | Searches existing nodes (title/content/dimensions) before deciding whether to create something new. |
|
| `rah_search_nodes` | Searches existing nodes (title/content/dimensions) before deciding whether to create something new. |
|
||||||
|
|
||||||
## Guardrails
|
## Claude Desktop (STDIO Connector)
|
||||||
|
|
||||||
- The MCP server only binds to `127.0.0.1` and is meant for **your** agents. Do not expose it beyond your machine.
|
Claude Desktop expects STDIO-based servers. Point it at:
|
||||||
- Anything the assistant writes is immediately persisted to `~/Library/Application Support/RA-H/db/rah.sqlite`. Review the RA-H activity panel if something looks off.
|
|
||||||
- Disable the connector by setting `RAH_ENABLE_MCP=false` before launching the app (UI toggle coming soon).
|
|
||||||
- The `/status` endpoint returns health info if you need diagnostics: `curl http://127.0.0.1:44145/status`.
|
|
||||||
|
|
||||||
### Claude Desktop (STDIO Connector)
|
|
||||||
|
|
||||||
Claude’s configuration window expects STDIO-based servers. To let Claude start a connector directly, point it at:
|
|
||||||
|
|
||||||
```
|
```
|
||||||
node /Users/<you>/Desktop/dev/ra-h/apps/mcp-server/stdio-server.js
|
node /path/to/ra-h_os/apps/mcp-server/stdio-server.js
|
||||||
```
|
```
|
||||||
|
|
||||||
This script speaks MCP over stdin/stdout (no HTTP listener), so Claude can manage it through `claude_desktop_config.json` or the “Add MCP Server” CLI flow. Keep the main RA-H app running so the STDIO bridge can call `http://127.0.0.1:3000/api/nodes`.
|
This speaks MCP over stdin/stdout. Add it to `claude_desktop_config.json` or use the "Add MCP Server" CLI flow. Keep the Next.js server running so the STDIO bridge can call `http://127.0.0.1:3000/api/nodes`.
|
||||||
|
|
||||||
## Development Notes
|
## Configuration
|
||||||
|
|
||||||
- Implementation lives in `apps/mcp-server/server.js` (HTTP transport + tool definitions). It proxies through the existing `/api/nodes/*` routes, so validation + auto-embed behavior stays consistent.
|
| Environment Variable | Default | Description |
|
||||||
- The Mac sidecar (`apps/mac/scripts/sidecar-launcher.js`) bootstraps the MCP server and keeps `~/Library/Application Support/RA-H/config/mcp-status.json` updated for the Settings panel/API.
|
|---------------------|---------|-------------|
|
||||||
- To run the server standalone (for MCP Inspector, etc.): `node apps/mcp-server/server.js` (requires the Next.js sidecar to be running so the API endpoints respond).
|
| `MCP_PORT` | `44145` | Port for the HTTP MCP server |
|
||||||
|
| `RAH_ENABLE_MCP` | `true` | Set to `false` to disable MCP |
|
||||||
|
|
||||||
|
## Security Notes
|
||||||
|
|
||||||
|
- The MCP server only binds to `127.0.0.1` — it's meant for **your** local agents only
|
||||||
|
- Do not expose it beyond your machine
|
||||||
|
- Anything the assistant writes is immediately persisted to your local SQLite database
|
||||||
|
- Review the RA-H activity panel if something looks unexpected
|
||||||
|
|
||||||
|
## Troubleshooting
|
||||||
|
|
||||||
|
### Server won't start
|
||||||
|
- Ensure the Next.js dev server is running first
|
||||||
|
- Check if port 44145 is already in use: `lsof -i :44145`
|
||||||
|
|
||||||
|
### Connection fails in assistant
|
||||||
|
- Verify both servers are running (Next.js on 3000, MCP on 44145)
|
||||||
|
- Try the health endpoint: `curl http://127.0.0.1:44145/status`
|
||||||
|
|
||||||
|
### Tools not working
|
||||||
|
- The MCP server proxies through `/api/nodes/*` routes — ensure the Next.js server responds
|
||||||
|
- Check the terminal running the MCP server for error logs
|
||||||
|
|
||||||
|
## Development
|
||||||
|
|
||||||
|
- Implementation: `apps/mcp-server/server.js` (HTTP transport + tool definitions)
|
||||||
|
- STDIO variant: `apps/mcp-server/stdio-server.js`
|
||||||
|
- The server proxies through existing `/api/nodes/*` routes, so validation and auto-embed behavior stays consistent
|
||||||
|
|||||||
@@ -0,0 +1,21 @@
|
|||||||
|
# Documentation
|
||||||
|
|
||||||
|
## Quick Start
|
||||||
|
See the main [README.md](../README.md) for setup instructions.
|
||||||
|
|
||||||
|
## Architecture
|
||||||
|
|
||||||
|
| Document | Description |
|
||||||
|
|----------|-------------|
|
||||||
|
| [0_overview.md](0_overview.md) | System overview and philosophy |
|
||||||
|
| [1_architecture.md](1_architecture.md) | Technical architecture |
|
||||||
|
| [2_schema.md](2_schema.md) | Database schema and sqlite-vec setup |
|
||||||
|
| [3_context-and-memory.md](3_context-and-memory.md) | Context system |
|
||||||
|
| [4_tools-and-workflows.md](4_tools-and-workflows.md) | Agent tools and workflows |
|
||||||
|
| [5_logging-and-evals.md](5_logging-and-evals.md) | Logging infrastructure |
|
||||||
|
| [6_ui.md](6_ui.md) | UI components and patterns |
|
||||||
|
| [8_mcp.md](8_mcp.md) | MCP server setup |
|
||||||
|
| [9_open-source.md](9_open-source.md) | Open source specific notes |
|
||||||
|
|
||||||
|
## Troubleshooting
|
||||||
|
See [TROUBLESHOOTING.md](TROUBLESHOOTING.md) for common issues.
|
||||||
@@ -0,0 +1,100 @@
|
|||||||
|
# Troubleshooting
|
||||||
|
|
||||||
|
## Installation Issues
|
||||||
|
|
||||||
|
### `npm install` fails
|
||||||
|
|
||||||
|
**Symptom:** Error during native module compilation
|
||||||
|
|
||||||
|
**Fix:** Install build tools:
|
||||||
|
```bash
|
||||||
|
# macOS
|
||||||
|
xcode-select --install
|
||||||
|
|
||||||
|
# Linux
|
||||||
|
sudo apt install build-essential python3
|
||||||
|
|
||||||
|
# Windows
|
||||||
|
npm install -g windows-build-tools
|
||||||
|
```
|
||||||
|
|
||||||
|
### `npm rebuild better-sqlite3` fails
|
||||||
|
|
||||||
|
**Symptom:** Native module rebuild errors
|
||||||
|
|
||||||
|
**Fix:**
|
||||||
|
1. Ensure Node.js 18+ is installed
|
||||||
|
2. Delete `node_modules` and reinstall:
|
||||||
|
```bash
|
||||||
|
rm -rf node_modules package-lock.json
|
||||||
|
npm install
|
||||||
|
npm rebuild better-sqlite3
|
||||||
|
```
|
||||||
|
|
||||||
|
## Runtime Issues
|
||||||
|
|
||||||
|
### App won't start
|
||||||
|
|
||||||
|
**Symptom:** Error on `npm run dev`
|
||||||
|
|
||||||
|
**Fixes:**
|
||||||
|
1. Run the bootstrap script first: `scripts/dev/bootstrap-local.sh`
|
||||||
|
2. Check `.env.local` exists (copy from `.env.example` if missing)
|
||||||
|
3. Ensure database directory exists: `~/Library/Application Support/RA-H/db/`
|
||||||
|
|
||||||
|
### Vector search returns no results
|
||||||
|
|
||||||
|
**Symptom:** Semantic search doesn't find matches
|
||||||
|
|
||||||
|
**Fixes:**
|
||||||
|
1. Ensure `sqlite-vec` extension is loading (check console for errors)
|
||||||
|
2. Verify `SQLITE_VEC_EXTENSION_PATH` in `.env.local` points to `vendor/sqlite-extensions/vec0.dylib`
|
||||||
|
3. Note: sqlite-vec only works on macOS currently. Linux/Windows users need to compile it manually.
|
||||||
|
|
||||||
|
### API key validation fails
|
||||||
|
|
||||||
|
**Symptom:** "Invalid key" error in Settings
|
||||||
|
|
||||||
|
**Fixes:**
|
||||||
|
1. Verify key format:
|
||||||
|
- OpenAI: starts with `sk-`
|
||||||
|
- Anthropic: starts with `sk-ant-`
|
||||||
|
2. Check key has correct permissions/credits
|
||||||
|
3. Try regenerating the key in provider dashboard
|
||||||
|
|
||||||
|
### Chat returns errors
|
||||||
|
|
||||||
|
**Symptom:** Error messages when chatting
|
||||||
|
|
||||||
|
**Fixes:**
|
||||||
|
1. Check API keys are valid (Settings → API Keys)
|
||||||
|
2. Verify internet connection
|
||||||
|
3. Check browser console for specific error messages
|
||||||
|
|
||||||
|
## Database Issues
|
||||||
|
|
||||||
|
### Database locked
|
||||||
|
|
||||||
|
**Symptom:** "SQLITE_BUSY" errors
|
||||||
|
|
||||||
|
**Fix:** Only run one instance of RA-H at a time. Close any other terminals running the app.
|
||||||
|
|
||||||
|
### Missing tables
|
||||||
|
|
||||||
|
**Symptom:** "no such table" errors
|
||||||
|
|
||||||
|
**Fix:** Re-run the schema script:
|
||||||
|
```bash
|
||||||
|
scripts/database/sqlite-ensure-app-schema.sh ~/Library/Application\ Support/RA-H/db/rah.sqlite
|
||||||
|
```
|
||||||
|
|
||||||
|
## Platform-Specific
|
||||||
|
|
||||||
|
### Linux/Windows
|
||||||
|
|
||||||
|
The bundled `vec0.dylib` and `yt-dlp` binaries are macOS-only. For other platforms:
|
||||||
|
|
||||||
|
1. **sqlite-vec**: Build from source at https://github.com/asg017/sqlite-vec
|
||||||
|
2. **yt-dlp**: Download from https://github.com/yt-dlp/yt-dlp/releases
|
||||||
|
|
||||||
|
See the main README for detailed instructions.
|
||||||
+2
-2
@@ -12,8 +12,8 @@ const nextConfig = {
|
|||||||
ignoreBuildErrors: false,
|
ignoreBuildErrors: false,
|
||||||
},
|
},
|
||||||
eslint: {
|
eslint: {
|
||||||
// Temporarily ignore lint during builds for beta packaging
|
// Temporarily ignore lint during builds
|
||||||
// TODO: Fix remaining ~150 lint errors in follow-up PR
|
// TODO: Fix remaining lint errors in follow-up PR
|
||||||
ignoreDuringBuilds: true,
|
ignoreDuringBuilds: true,
|
||||||
},
|
},
|
||||||
}
|
}
|
||||||
|
|||||||
+3
-3
@@ -24,7 +24,7 @@
|
|||||||
"@ai-sdk/anthropic": "^2.0.27",
|
"@ai-sdk/anthropic": "^2.0.27",
|
||||||
"@ai-sdk/openai": "^2.0.22",
|
"@ai-sdk/openai": "^2.0.22",
|
||||||
"@ai-sdk/react": "^2.0.26",
|
"@ai-sdk/react": "^2.0.26",
|
||||||
"@langchain/core": "^1.0.1",
|
"@langchain/core": "^0.3.0",
|
||||||
"@langchain/textsplitters": "^0.1.0",
|
"@langchain/textsplitters": "^0.1.0",
|
||||||
"@radix-ui/react-checkbox": "^1.1.1",
|
"@radix-ui/react-checkbox": "^1.1.1",
|
||||||
"@radix-ui/react-dropdown-menu": "^2.1.1",
|
"@radix-ui/react-dropdown-menu": "^2.1.1",
|
||||||
@@ -36,7 +36,7 @@
|
|||||||
"class-variance-authority": "^0.7.0",
|
"class-variance-authority": "^0.7.0",
|
||||||
"clsx": "^2.1.1",
|
"clsx": "^2.1.1",
|
||||||
"lucide-react": "^0.468.0",
|
"lucide-react": "^0.468.0",
|
||||||
"next": "latest",
|
"next": "15.1.3",
|
||||||
"next-themes": "^0.4.3",
|
"next-themes": "^0.4.3",
|
||||||
"openai": "^4.103.0",
|
"openai": "^4.103.0",
|
||||||
"pdf-parse": "^1.1.1",
|
"pdf-parse": "^1.1.1",
|
||||||
@@ -60,7 +60,7 @@
|
|||||||
"autoprefixer": "^10.4.20",
|
"autoprefixer": "^10.4.20",
|
||||||
"esbuild": "^0.23.1",
|
"esbuild": "^0.23.1",
|
||||||
"eslint": "^8.57.0",
|
"eslint": "^8.57.0",
|
||||||
"eslint-config-next": "latest",
|
"eslint-config-next": "15.1.3",
|
||||||
"postcss": "^8.4.49",
|
"postcss": "^8.4.49",
|
||||||
"prettier": "^3.3.3",
|
"prettier": "^3.3.3",
|
||||||
"tailwindcss": "^3.4.17",
|
"tailwindcss": "^3.4.17",
|
||||||
|
|||||||
@@ -3,7 +3,7 @@ set -euo pipefail
|
|||||||
|
|
||||||
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
||||||
REPO_DIR="$(cd "${SCRIPT_DIR}/../.." && pwd)"
|
REPO_DIR="$(cd "${SCRIPT_DIR}/../.." && pwd)"
|
||||||
ENV_TEMPLATE="${REPO_DIR}/.env.example.local"
|
ENV_TEMPLATE="${REPO_DIR}/.env.example"
|
||||||
TARGET_ENV="${REPO_DIR}/.env.local"
|
TARGET_ENV="${REPO_DIR}/.env.local"
|
||||||
SQLITE_SEED_SCRIPT="${REPO_DIR}/scripts/database/sqlite-ensure-app-schema.sh"
|
SQLITE_SEED_SCRIPT="${REPO_DIR}/scripts/database/sqlite-ensure-app-schema.sh"
|
||||||
|
|
||||||
@@ -12,7 +12,7 @@ log() {
|
|||||||
}
|
}
|
||||||
|
|
||||||
if [ ! -f "$ENV_TEMPLATE" ]; then
|
if [ ! -f "$ENV_TEMPLATE" ]; then
|
||||||
echo "Error: ${ENV_TEMPLATE} not found. Make sure .env.example.local exists." >&2
|
echo "Error: ${ENV_TEMPLATE} not found. Make sure .env.example exists." >&2
|
||||||
exit 1
|
exit 1
|
||||||
fi
|
fi
|
||||||
|
|
||||||
|
|||||||
@@ -503,7 +503,7 @@ export default function RAHChat({
|
|||||||
borderRadius: '6px',
|
borderRadius: '6px',
|
||||||
lineHeight: 1.4
|
lineHeight: 1.4
|
||||||
}}>
|
}}>
|
||||||
{quotaError?.message ?? 'Your monthly allowance has been used. Upgrade your plan to keep chatting with RA-H.'}
|
{quotaError?.message ?? 'Rate limit reached. Please wait a moment and try again.'}
|
||||||
</div>
|
</div>
|
||||||
)}
|
)}
|
||||||
<TerminalInput
|
<TerminalInput
|
||||||
|
|||||||
@@ -112,6 +112,16 @@ export default function ThreePanelLayout() {
|
|||||||
return () => window.removeEventListener('keydown', handleKeyDown);
|
return () => window.removeEventListener('keydown', handleKeyDown);
|
||||||
}, [setNodesCollapsed, setChatCollapsed]);
|
}, [setNodesCollapsed, setChatCollapsed]);
|
||||||
|
|
||||||
|
// Listen for settings:open events (from LocalKeyGate)
|
||||||
|
useEffect(() => {
|
||||||
|
const handleSettingsOpen = (e: CustomEvent<{ tab?: SettingsTab }>) => {
|
||||||
|
setSettingsInitialTab(e.detail?.tab || 'apikeys');
|
||||||
|
setShowSettings(true);
|
||||||
|
};
|
||||||
|
window.addEventListener('settings:open', handleSettingsOpen as EventListener);
|
||||||
|
return () => window.removeEventListener('settings:open', handleSettingsOpen as EventListener);
|
||||||
|
}, []);
|
||||||
|
|
||||||
|
|
||||||
// SSE connection for real-time updates
|
// SSE connection for real-time updates
|
||||||
useEffect(() => {
|
useEffect(() => {
|
||||||
|
|||||||
@@ -34,7 +34,7 @@ export default function ExternalAgentsPanel() {
|
|||||||
setError(null);
|
setError(null);
|
||||||
} catch (err) {
|
} catch (err) {
|
||||||
console.error('Failed to load MCP status', err);
|
console.error('Failed to load MCP status', err);
|
||||||
setError('Unable to read local MCP status. Open the desktop app to bootstrap it.');
|
setError('MCP server not running. See docs/8_mcp.md for setup instructions.');
|
||||||
setStatus(initialStatus);
|
setStatus(initialStatus);
|
||||||
} finally {
|
} finally {
|
||||||
setLoading(false);
|
setLoading(false);
|
||||||
@@ -84,7 +84,7 @@ export default function ExternalAgentsPanel() {
|
|||||||
<div>
|
<div>
|
||||||
<div style={{ fontSize: '14px', color: '#94a3b8' }}>Connector URL</div>
|
<div style={{ fontSize: '14px', color: '#94a3b8' }}>Connector URL</div>
|
||||||
<div style={{ fontSize: '18px', color: connectorUrl ? '#fff' : '#64748b', marginTop: '4px' }}>
|
<div style={{ fontSize: '18px', color: connectorUrl ? '#fff' : '#64748b', marginTop: '4px' }}>
|
||||||
{loading ? 'Loading…' : connectorUrl ?? 'Unavailable (start the RA-H desktop app)'}
|
{loading ? 'Loading…' : connectorUrl ?? 'Unavailable (MCP server not running)'}
|
||||||
</div>
|
</div>
|
||||||
{status.last_updated && (
|
{status.last_updated && (
|
||||||
<div style={{ fontSize: '12px', color: '#475569', marginTop: '6px' }}>
|
<div style={{ fontSize: '12px', color: '#475569', marginTop: '6px' }}>
|
||||||
|
|||||||
@@ -1,4 +1,4 @@
|
|||||||
const rawDeploymentMode = (process.env.NEXT_PUBLIC_DEPLOYMENT_MODE || 'cloud').toLowerCase();
|
const rawDeploymentMode = (process.env.NEXT_PUBLIC_DEPLOYMENT_MODE || 'local').toLowerCase();
|
||||||
const backendFlagEnabled = process.env.NEXT_PUBLIC_ENABLE_SUBSCRIPTION_BACKEND === 'true';
|
const backendFlagEnabled = process.env.NEXT_PUBLIC_ENABLE_SUBSCRIPTION_BACKEND === 'true';
|
||||||
|
|
||||||
export type DeploymentMode = 'local' | 'cloud';
|
export type DeploymentMode = 'local' | 'cloud';
|
||||||
|
|||||||
+1
-1
@@ -33,5 +33,5 @@
|
|||||||
}
|
}
|
||||||
},
|
},
|
||||||
"include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
|
"include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
|
||||||
"exclude": ["node_modules", "dist", ".next", "apps/mac/src-tauri/target", "backups"]
|
"exclude": ["node_modules", "dist", ".next", "backups", "vitest.config.ts"]
|
||||||
}
|
}
|
||||||
|
|||||||
Reference in New Issue
Block a user