docs: standardize RA-OS naming and add process docs

2026-02-01 09:47:33 +11:00
parent 6c510096a3
commit 16db5b61b6
13 changed files with 134 additions and 38 deletions
@@ -1,8 +1,8 @@
-# RA-H Light Overview
+# RA-OS Overview

-## What is RA-H Light?
+## What is RA-OS?

-RA-H Light is a minimal knowledge graph UI with MCP server integration. It provides a local-first knowledge management system designed to be extended by external AI agents via the Model Context Protocol.
+RA-OS is a minimal knowledge graph UI with MCP server integration. It provides a local-first knowledge management system designed to be extended by external AI agents via the Model Context Protocol.

 **Open Source:** [github.com/bradwmorris/ra-h_os](https://github.com/bradwmorris/ra-h_os)

@@ -10,7 +10,7 @@ RA-H Light is a minimal knowledge graph UI with MCP server integration. It provi

 **Local-first** — Your knowledge network belongs to you. Everything runs locally in a SQLite database you control.

-**Agent-agnostic** — No built-in AI chat. Instead, RA-H Light exposes an MCP server that any AI agent (Claude Code, custom agents) can connect to.
+**Agent-agnostic** — No built-in AI chat. Instead, RA-OS exposes an MCP server that any AI agent (Claude Code, custom agents) can connect to.

 **Simple & focused** — 2-panel UI for browsing and editing your knowledge graph. No bloat.

@@ -56,7 +56,7 @@ RA-H Light is a minimal knowledge graph UI with MCP server integration. It provi

 ## MCP Integration

-RA-H Light is designed to be the knowledge backend for your AI workflows:
+RA-OS is designed to be the knowledge backend for your AI workflows:

 ```json
 {
@@ -2,13 +2,13 @@

 > MCP tools for external agents and the guides system for context sharing.

-**How it works:** RA-H Light exposes tools via MCP that external AI agents can call to read, create, and update your knowledge graph. Guides are markdown documents that help external agents understand your knowledge base.
+**How it works:** RA-OS exposes tools via MCP that external AI agents can call to read, create, and update your knowledge graph. Guides are markdown documents that help external agents understand your knowledge base.

 ---

 ## MCP Tools

-RA-H Light provides MCP tools for external agents:
+RA-OS provides MCP tools for external agents:

 ### Node Operations

@@ -166,7 +166,7 @@ Your guide content here...

 ## API Routes

-RA-H Light exposes REST APIs that MCP tools call internally:
+RA-OS exposes REST APIs that MCP tools call internally:

 | Route | Method | Purpose |
 |-------|--------|---------|
@@ -1,8 +1,8 @@
 # User Interface

-> How to navigate and use RA-H Light's interface.
+> How to navigate and use RA-OS's interface.

-**How it works:** RA-H Light uses a 2-panel layout: browse nodes on the left, work with focused content on the right. Settings give you access to workflows, database views, a knowledge map, and more.
+**How it works:** RA-OS uses a 2-panel layout: browse nodes on the left, work with focused content on the right. Settings give you access to workflows, database views, a knowledge map, and more.

 ---

@@ -2,13 +2,13 @@

 > How to connect Claude Code and other AI assistants to your knowledge base.

-**How it works:** RA-H Light runs a local MCP (Model Context Protocol) server. This lets any MCP-compatible assistant — like Claude Code — search your notes, add new knowledge, and manage your knowledge graph. Everything stays local; nothing goes to the cloud.
+**How it works:** RA-OS runs a local MCP (Model Context Protocol) server. This lets any MCP-compatible assistant — like Claude Code — search your notes, add new knowledge, and manage your knowledge graph. Everything stays local; nothing goes to the cloud.

 ---

 ## Quick Start

-1. Start RA-H Light: `npm run dev`
+1. Start RA-OS: `npm run dev`
 2. Configure your AI assistant (see below)
 3. Use naturally: "Search RA-H for my notes on X" or "Add this to RA-H"

@@ -47,9 +47,9 @@ Add to your `~/.claude.json` or Claude Code settings:
 }
 ```

-Replace `/path/to/ra-h_os` with the actual path to your RA-H Light installation.
+Replace `/path/to/ra-h_os` with the actual path to your RA-OS installation.

-**Note:** RA-H Light must be running (`npm run dev`) for the MCP server to work.
+**Note:** RA-OS must be running (`npm run dev`) for the MCP server to work.

 ---

@@ -119,7 +119,7 @@ curl http://127.0.0.1:44145/status

 ### "Connection refused"

-1. Make sure RA-H Light is running: `npm run dev`
+1. Make sure RA-OS is running: `npm run dev`
 2. Check the port isn't blocked: `lsof -i :44145`
 3. Verify the server started: check terminal output

@@ -1,10 +1,10 @@
-# RA-H Light
+# RA-OS

-This is **RA-H Light** — a minimal, local-first knowledge graph UI with MCP server integration.
+This is **RA-OS** — a minimal, local-first knowledge graph UI with MCP server integration.

-## What is RA-H Light?
+## What is RA-OS?

-RA-H Light is a stripped-down version of [RA-H](https://ra-h.app) focused on:
+RA-OS is a stripped-down version of [RA-H](https://ra-h.app) focused on:

 - **2-panel UI** for browsing and editing your knowledge graph
 - **MCP server** so external AI agents (like Claude Code) can access your notes
@@ -13,7 +13,7 @@ RA-H Light is a stripped-down version of [RA-H](https://ra-h.app) focused on:

 ## What's NOT Included

-RA-H Light intentionally excludes:
+RA-OS intentionally excludes:

 - Chat interface (use external agents via MCP)
 - Voice features
@@ -1,10 +1,19 @@
-# RA-H Light Documentation
+# RA-OS Documentation
+
+```
+ ██████╗  █████╗       ██╗  ██╗
+ ██╔══██╗██╔══██╗      ██║  ██║
+ ██████╔╝███████║█████╗███████║
+ ██╔══██╗██╔══██║╚════╝██╔══██║
+ ██║  ██║██║  ██║      ██║  ██║
+ ╚═╝  ╚═╝╚═╝  ╚═╝      ╚═╝  ╚═╝
+```

 ## Quick Links

 | Doc | Description |
 |-----|-------------|
-| [Overview](./0_overview.md) | What is RA-H Light, design philosophy |
+| [Overview](./0_overview.md) | What is RA-OS, design philosophy |
 | [Schema](./2_schema.md) | Database schema, node/edge structure |
 | [Tools & Workflows](./4_tools-and-workflows.md) | MCP tools, workflow system |
 | [Logging & Evals](./5_logging-and-evals.md) | Debugging, evaluation framework |
@@ -12,6 +21,8 @@
 | [MCP](./8_mcp.md) | Connect Claude Code and external agents |
 | [About](./9_open-source.md) | What's included, contributing |
 | [Troubleshooting](./TROUBLESHOOTING.md) | Common issues and fixes |
+| [Development](./development/process.md) | Dev workflow and PR checklist |
+| [Docs Process](./development/docs-process.md) | How to maintain docs |

 ## Getting Started

@@ -0,0 +1,37 @@
+# Documentation Process (RA-OS)
+
+Docs should be short, accurate, and easy to scan. Prefer clarity over completeness.
+
+## Where Things Live
+
+- `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/8_mcp.md` — setup + troubleshooting for MCP.
+
+## Update Rules
+
+- If behavior changes, update the relevant doc and the docs index.
+- If MCP tools change, update both the tools table and the schemas.
+- If the UI changes meaningfully, update `docs/6_ui.md`.
+- Keep naming consistent: **RA-OS** only.
+
+## Style Guidelines
+
+- Use short sections and bullets.
+- Keep code blocks minimal and copy-pastable.
+- Use ASCII art sparingly (hero or section headers only).
+- Avoid hype and marketing tone in docs.
+
+## Media
+
+- Place screenshots/GIFs in `docs/assets/`.
+- Keep GIFs under 5MB.
+- Prefer static screenshots when possible.
+
+## Docs QA
+
+- Read each changed doc top-to-bottom.
+- Verify all paths and commands.
+- Ensure the quick start still works on a clean clone.
@@ -0,0 +1,48 @@
+# Development Process (RA-OS)
+
+This repo is the open-source build of RA-H. Keep changes focused, reviewable, and easy to sync upstream.
+
+## Branching
+
+- Create a feature branch off `main` for all changes.
+- Use short, descriptive names: `docs-...`, `fix-...`, `feat-...`.
+- Avoid direct commits to `main`.
+
+## Local Setup
+
+```bash
+git clone https://github.com/bradwmorris/ra-h_os.git
+cd ra-h_os
+npm install
+npm rebuild better-sqlite3
+scripts/dev/bootstrap-local.sh
+npm run dev
+```
+
+## Dev Loop
+
+1. Reproduce or define the change.
+2. Implement in a small, isolated diff.
+3. Run checks (see below).
+4. Update docs if behavior or UX changes.
+
+## Checks
+
+```bash
+npm run type-check
+npm run lint
+npm run build
+```
+
+## PR Checklist
+
+- Clear description of the change and why it matters.
+- Screenshots or GIFs for UI changes.
+- Docs updated if the public-facing behavior changed.
+- Checks pass locally.
+
+## 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.
+- Public contributions will not be overwritten by syncs.