From 46ac8d9bde9f96f3a1a053687035b87d60188bf9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9CBeeRad=E2=80=9D?= Date: Sat, 7 Mar 2026 11:44:21 +1100 Subject: [PATCH] docs: update process and contributor guidance --- AGENTS.md | 51 ++++++++++++++++++++++++ CLAUDE.md | 67 +++++++++++--------------------- CONTRIBUTING.md | 8 ++-- README.md | 3 +- docs/development/docs-process.md | 2 +- docs/development/process.md | 10 +++-- 6 files changed, 87 insertions(+), 54 deletions(-) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..154f52f --- /dev/null +++ b/AGENTS.md @@ -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/` + - `fix/` + - `docs/` +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. + diff --git a/CLAUDE.md b/CLAUDE.md index b7e5213..4a15adc 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -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` diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 37fcec3..1a1099e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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 diff --git a/README.md b/README.md index 527b7c5..a8b46c1 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/docs/development/docs-process.md b/docs/development/docs-process.md index 66cdd77..afb5ab1 100644 --- a/docs/development/docs-process.md +++ b/docs/development/docs-process.md @@ -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 diff --git a/docs/development/process.md b/docs/development/process.md index c0a021d..29c93a7 100644 --- a/docs/development/process.md +++ b/docs/development/process.md @@ -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/`, `fix/`, `feat/`. - 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.