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,4 +1,4 @@
-# RA-H Open Source - Knowledge Management System
+# RA-OS - Knowledge Management System

 ## 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.
@@ -1,17 +1,17 @@
-# RA-H Light
+# RA-OS

 A lightweight local knowledge graph UI with MCP server. Connect your AI coding agents to a personal knowledge base. BYO API keys, no cloud dependencies.

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

-RA-H Light is a stripped-down version of RA-H focused on being a **knowledge management backend for AI agents**. It provides:
+RA-OS is a stripped-down version of RA-H focused on being a **knowledge management backend for AI agents**. It provides:

 - **2-panel UI** – Nodes list + focus panel for viewing/editing knowledge
 - **SQLite + sqlite-vec** – Local vector database with semantic search
 - **MCP Server** – Connect Claude Code, Cursor, or any MCP-compatible AI assistant
 - **Workflows** – Editable JSON workflows for multi-step operations

-**What's removed:** Built-in chat agents, voice features, delegation system. RA-H Light is designed for technical users who want to bring their own AI agents via MCP.
+**What's removed:** Built-in chat agents, voice features, delegation system. RA-OS is designed for technical users who want to bring their own AI agents via MCP.

 ## Platform Support

@@ -37,7 +37,7 @@ Open http://localhost:3000 → **Settings → API Keys** → add your OpenAI key

 ## Connecting AI Agents via MCP

-RA-H Light exposes an MCP server that external AI assistants can use to read/write your knowledge graph.
+RA-OS exposes an MCP server that external AI assistants can use to read/write your knowledge graph.

 ### Claude Code Integration

@@ -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.
@@ -1,5 +1,5 @@
 {
-  "project": "rah-light",
+  "project": "rah-os",
  "context": "Stripping ra-h_os to a lightweight 2-panel knowledge graph UI with MCP server. Remove chat agents, voice, delegation system, memory pipeline. Keep: nodes/edges/dimensions CRUD, MCP server, workflows, extraction tools. The goal is a simple UI that technical users can run and connect their own agents to via MCP. Auth/subscription already removed from ra-h_os.",
  "userStories": [
    {
@@ -188,7 +188,7 @@
        "No references to removed features"
      ],
      "passes": true,
-      "notes": "Renamed to RA-H Light. Added 'What is RA-H Light?' section explaining it's for AI agent knowledge management. Added MCP integration section with Claude Code setup example and all 11 tools listed. Removed all references to chat agents, voice, 3-panel interface, content extraction."
+      "notes": "Renamed to RA-OS. Added 'What is RA-OS?' section explaining it's for AI agent knowledge management. Added MCP integration section with Claude Code setup example and all 11 tools listed. Removed all references to chat agents, voice, 3-panel interface, content extraction."
    },
    {
      "id": "15",
@@ -1,4 +1,4 @@
-# Ralph Progress Log - RA-H Light Strip-Down
+# Ralph Progress Log - RA-OS Strip-Down
 Started: Thu 29 Jan 2026 15:00:36 AEDT
 Branch: feature/rah-light
 Goal: Strip ra-h_os to lightweight 2-panel UI + MCP server
@@ -228,8 +228,8 @@ Goal: Strip ra-h_os to lightweight 2-panel UI + MCP server
 - Files modified:
  - README.md (complete rewrite)
 - Changes:
-  - Renamed from "RA-H Open Source" to "RA-H Light"
-  - Added "What is RA-H Light?" section explaining the stripped-down purpose
+- Renamed from "RA-H Open Source" to "RA-OS"
+- Added "What is RA-OS?" section explaining the stripped-down purpose
  - Explicitly list what's removed: chat agents, voice, delegation
  - Added comprehensive MCP integration section:
    - Claude Code setup with JSON config example
@@ -240,7 +240,7 @@ Goal: Strip ra-h_os to lightweight 2-panel UI + MCP server
  - Kept: quick start, platform support, commands, docs links, Linux/Windows setup
 - Learnings:
  - The README is the primary entry point - important to set expectations clearly
-  - MCP integration is now the main selling point of RA-H Light
+- MCP integration is now the main selling point of RA-OS
  - Users need clear setup instructions for Claude Code integration

 ## Story 15: Final verification
@@ -250,7 +250,7 @@ Goal: Strip ra-h_os to lightweight 2-panel UI + MCP server
  - npm run type-check: SUCCESS (no errors)
  - npm run dev: SUCCESS (starts on localhost:3000)
  - UI loads: SUCCESS (HTML renders with LeftToolbar, nodes panel visible)
- Summary of RA-H Light:
+- Summary of RA-OS:
  - Total files deleted: ~50+ files across chat, voice, delegation systems
  - Total lines removed: ~5000+ lines of code
  - Remaining functionality: nodes/edges/dimensions CRUD, workflows, MCP server (11 tools)
@@ -261,7 +261,7 @@ Goal: Strip ra-h_os to lightweight 2-panel UI + MCP server

 # SPRINT COMPLETE

-All 15 stories passed. RA-H Light is now a minimal knowledge graph UI with MCP server:
+All 15 stories passed. RA-OS is now a minimal knowledge graph UI with MCP server:

 - **Removed:** Chat agents, voice features, delegation system, Anthropic integration
 - **Kept:** Node/Edge/Dimension CRUD, workflows, MCP server, embeddings, search
@@ -1,6 +1,6 @@
-# Ralph Autonomous Agent - RA-H Light Strip-Down
+# Ralph Autonomous Agent - RA-OS Strip-Down

-You are an autonomous coding agent stripping down ra-h_os to create RA-H Light — a minimal knowledge graph UI with MCP server.
+You are an autonomous coding agent stripping down ra-h_os to create RA-OS — a minimal knowledge graph UI with MCP server.

 ## Your Task