docs: update process and contributor guidance

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/<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

@@ -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
+## Core Stack
-- Next.js 15 + TypeScript + Tailwind CSS
+- Next.js 15 + TypeScript + Tailwind
-- SQLite + sqlite-vec (vector search)
+- SQLite + sqlite-vec
-- Anthropic (Claude) + OpenAI (GPT) models via Vercel AI SDK
+- BYO API keys (OpenAI/Anthropic)
-- 3-panel UI: Nodes | Focus | Helpers
 
-## 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
+## Key Paths
-**Orchestrator (Easy Mode):** GPT-5 Mini - DEFAULT - fast, cheap orchestration
+- `src/services/database/` - data layer
-**Orchestrator (Hard Mode):** Claude Sonnet 4.5 - deep reasoning (toggle via UI)
+- `src/tools/` - MCP tool implementations
-**Oracle (Wise ra-h):** GPT-5 - complex workflows, multi-step planning
+- `src/config/guides/` - built-in guide content
-**Delegates:** GPT-4o mini - spawned for write operations, extraction, batch tasks
+- `app/api/` - API routes
 
-Tools available: queryNodes, queryEdge, searchContentEmbeddings, webSearch, think, executeWorkflow, createNode, updateNode, createEdge, updateEdge, youtubeExtract, websiteExtract, paperExtract
+## Docs
-
+- `docs/README.md`
-## Workflows System
+- `docs/0_overview.md`
-- **Code-first registry:** Defined in `src/services/workflows/registry.ts`
+- `docs/2_schema.md`
-- **Integrate workflow:** Database-wide connection discovery for focused nodes
+- `docs/4_tools-and-guides.md`
-  - 5-step process: plan → ground → search → contextualize → append
+- `docs/6_ui.md`
-  - Finds 3-8 strong connections across your database
+- `docs/8_mcp.md`
-
-## 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

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

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

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

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/<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.
+- `ra-h_os` accepts direct contributions.
-- If a change should exist in the private repo, it will be ported upstream.
+- Maintainers may port relevant changes between public and private repos.
 - Public contributions will not be overwritten by syncs.