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

docs: update process and contributor guidance

Browse Source
This commit is contained in:
“BeeRad”
2026-03-07 11:44:27 +11:00
parent 467a588713
commit 46ac8d9bde
6 changed files with 87 additions and 54 deletions
Download Patch File Download Diff File Expand all files Collapse all files
AGENTS.md
+51
View File
@@ -0,0 +1,51 @@
# RA-OS Agent Workflow (Open Source)
This file is the source of truth for AI agents and contributors working in this repository.
## Scope
- This workflow applies to `ra-h_os` only.
- Do not require private-repo docs, handoffs, or backlog files to complete work here.
## Working Rules
1. Start from `main` and create a branch:
- `feat/<short-name>`
- `fix/<short-name>`
- `docs/<short-name>`
2. Keep changes small and reviewable.
3. If behavior changes, update docs in the same PR.
4. Do not commit directly to `main`.
## Standard Dev Loop
1. Reproduce/define the problem.
2. Implement the minimal correct change.
3. Run local checks.
4. Update docs and screenshots if needed.
5. Open PR with clear summary and test notes.
## Required Checks
```bash
npm run type-check
npm run lint
npm run build
```
## Docs Map
- `README.md` - product overview + quick start
- `docs/README.md` - docs index
- `docs/4_tools-and-guides.md` - MCP tools + guides
- `docs/6_ui.md` - UI behavior
- `docs/8_mcp.md` - MCP setup and troubleshooting
- `docs/development/process.md` - contributor process
- `docs/development/docs-process.md` - docs maintenance process
## Upstream Relationship
- `ra-h_os` accepts direct contributions.
- Maintainers may sync relevant changes between public and private repos.
- Public contributions should remain attributable and not be overwritten.
CLAUDE.md
+22 -45
View File
@@ -1,15 +1,14 @@
# RA-OS - Knowledge Management System
# RA-OS
## What This Is
LLM-powered knowledge management system built for emergence and flexibility. This is the **open source, self-hosted version** with BYO (bring your own) API keys.
Open-source, local-first knowledge graph app with MCP integration.
## Tech Stack
- Next.js 15 + TypeScript + Tailwind CSS
- SQLite + sqlite-vec (vector search)
- Anthropic (Claude) + OpenAI (GPT) models via Vercel AI SDK
- 3-panel UI: Nodes | Focus | Helpers
## Core Stack
- Next.js 15 + TypeScript + Tailwind
- SQLite + sqlite-vec
- BYO API keys (OpenAI/Anthropic)
## Quick Start
## Run Locally
```bash
git clone https://github.com/bradwmorris/ra-h_os.git
cd ra-h_os
@@ -19,42 +18,20 @@ scripts/dev/bootstrap-local.sh
npm run dev
```
Open http://localhost:3000 and enter your API keys (OpenAI + Anthropic).
## Source of Truth for Workflow
- `AGENTS.md` - agent and contributor workflow
- `CONTRIBUTING.md` - PR and contribution policy
## Agent System
**Orchestrator (Easy Mode):** GPT-5 Mini - DEFAULT - fast, cheap orchestration
**Orchestrator (Hard Mode):** Claude Sonnet 4.5 - deep reasoning (toggle via UI)
**Oracle (Wise ra-h):** GPT-5 - complex workflows, multi-step planning
**Delegates:** GPT-4o mini - spawned for write operations, extraction, batch tasks
## Key Paths
- `src/services/database/` - data layer
- `src/tools/` - MCP tool implementations
- `src/config/guides/` - built-in guide content
- `app/api/` - API routes
Tools available: queryNodes, queryEdge, searchContentEmbeddings, webSearch, think, executeWorkflow, createNode, updateNode, createEdge, updateEdge, youtubeExtract, websiteExtract, paperExtract
## Workflows System
- **Code-first registry:** Defined in `src/services/workflows/registry.ts`
- **Integrate workflow:** Database-wide connection discovery for focused nodes
- 5-step process: plan → ground → search → contextualize → append
- Finds 3-8 strong connections across your database
## Database
- SQLite at `~/Library/Application Support/RA-H/db/rah.sqlite`
- Schema defined in `docs/2_schema.md`
- Health check: `GET /api/health/db`
## Key Files
- `src/services/agents/` - Agent executors and delegation
- `src/tools/` - All available tools
- `src/config/prompts/` - Agent system prompts
- `src/services/workflows/` - Workflow definitions
- `src/components/` - React components
## Documentation
- `docs/0_overview.md` - System overview
- `docs/1_architecture.md` - Architecture details
- `docs/2_schema.md` - Database schema
- `docs/4_tools-and-workflows.md` - Tools reference
## Contributing
See `CONTRIBUTING.md` for guidelines. Issues and PRs welcome!
## License
MIT - see LICENSE file
## Docs
- `docs/README.md`
- `docs/0_overview.md`
- `docs/2_schema.md`
- `docs/4_tools-and-guides.md`
- `docs/6_ui.md`
- `docs/8_mcp.md`
CONTRIBUTING.md
+5 -3
View File
@@ -1,6 +1,6 @@
# Contributing
This is the open source mirror of a private repository. Features are developed privately and synced here.
This is the open source build of RA-H. It accepts direct contributions, and maintainers may sync relevant changes with a private upstream.
**Full docs:** [ra-h.app/docs](https://ra-h.app/docs)
@@ -10,7 +10,7 @@ This is the open source mirror of a private repository. Features are developed p
- **Doc improvements** – typos, clarifications, examples
- **Small enhancements** – that don't require architectural changes
For larger features, open an issue first. Major features are typically implemented in the private repo and synced here.
For larger features, open an issue first so scope and direction are clear.
## Setup
@@ -33,6 +33,8 @@ npm run lint
All three must pass.
Agent/contributor workflow: see `AGENTS.md`.
## Code Style
- TypeScript with strict types (avoid `any`)
@@ -43,7 +45,7 @@ All three must pass.
## What Happens to Your Contribution
1. We review and merge here
2. If applicable, we port to the private repo
2. If applicable, maintainers port the change to the private repo
3. Future syncs won't overwrite your contribution
## License
README.md
+2 -1
View File
@@ -208,8 +208,9 @@ Without sqlite-vec, everything works except semantic/vector search.
---
## More
## Community
- **Discord:** [discord.gg/3cpQj6Jtc9](https://discord.gg/3cpQj6Jtc9) — ask questions, share your setup, get help
- **Full docs:** [ra-h.app/docs/open-source](https://ra-h.app/docs/open-source)
- **Issues:** [github.com/bradwmorris/ra-h_os/issues](https://github.com/bradwmorris/ra-h_os/issues)
- **License:** MIT
docs/development/docs-process.md
+1 -1
View File
@@ -7,7 +7,7 @@ Docs should be short, accurate, and easy to scan. Prefer clarity over completene
- `README.md` — one-page product + quick start.
- `docs/README.md` — docs index (add new docs here).
- `docs/0_overview.md` — product overview + core concepts.
- `docs/4_tools-and-workflows.md` — MCP tools + guides.
- `docs/4_tools-and-guides.md` — MCP tools + guides.
- `docs/8_mcp.md` — setup + troubleshooting for MCP.
## Update Rules
docs/development/process.md
+6 -4
View File
@@ -1,11 +1,13 @@
# Development Process (RA-OS)
This repo is the open-source build of RA-H. Keep changes focused, reviewable, and easy to sync upstream.
This repo is the open-source build of RA-H. Keep changes focused, reviewable, and easy to maintain.
`AGENTS.md` is the source of truth for agent/contributor workflow in this repository.
## Branching
- Create a feature branch off `main` for all changes.
- Use short, descriptive names: `docs-...`, `fix-...`, `feat-...`.
- Use short, descriptive names: `docs/<short-name>`, `fix/<short-name>`, `feat/<short-name>`.
- Avoid direct commits to `main`.
## Local Setup
@@ -43,6 +45,6 @@ npm run build
## Sync Policy (Private Upstream)
- Changes land in `ra-h_os` first.
- If a change should exist in the private repo, it will be ported upstream.
- `ra-h_os` accepts direct contributions.
- Maintainers may port relevant changes between public and private repos.
- Public contributions will not be overwritten by syncs.