ra-h-os/docs/6_ui.md

User Interface

How to navigate and use RA-OS's interface.

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 skills, database views, logs, tools, and MCP setup.

---

2-Panel Layout

┌─────────────┬─────────────────────────┐
│   NODES     │        FOCUS            │
│   Panel     │        Panel            │
│             │                         │
│ • Search    │ • Tabbed workspace      │
│ • Filters   │ • Node content          │
│ • Folders   │ • Connections           │
│             │                         │
└─────────────┴─────────────────────────┘

---

Left Panel: Nodes

Browse and manage your knowledge base.

Features

• Search bar — Cmd+K opens global search modal
• Dimension filters — Multi-select dimension tags
• Node list — Scrollable list of filtered nodes
• Folder view toggle — Switch between list and folder views

Node Display

Each node shows:

• Title + description preview
• Dimension tags (with custom icons)
• Last updated timestamp
• Node ID badge

Folder View

Click the folder icon to open the Folder View Overlay:

Two Modes:

1. Folders Mode — Browse by dimension folders

   • Each dimension shows as a folder card
   • Drag nodes to folders to add dimensions
   • Click to view nodes in that dimension

2. Filtered View Mode — Multi-dimension filtering with views

   • Add multiple dimension filters
   • Choose view layout (List, Grid, Kanban)
   • Save views for quick access

---

Filtered View System

View Modes

Mode	Description
List	Nodes grouped by dimension with section headers
Grid	Cards in responsive grid, grouped by dimension
Kanban	Columns per dimension, drag to move between

Compound Filters (AND Logic)

Add secondary filters to columns:

1. Add a filter (e.g., "inbox")
2. Click the [+ AND] button next to the dimension name
3. Select secondary dimension (e.g., "research")
4. Column now shows only nodes with BOTH dimensions

Saved Views

Save filter + view combinations:

1. Configure your filters and view mode
2. Click the save icon
3. Name your view
4. Access from the "Saved Views" dropdown

Drag-and-Drop

• Reorder nodes within views
• Move between Kanban columns (updates dimensions)
• Drag from nodes list to dimension folders

---

Right Panel: Focus

Active workspace for the node(s) you're working with.

Tabbed Interface

• Primary tab — Main focused node
• Additional tabs — Related nodes opened from links
• Tab controls — Close (×), reorder, switch

Node Detail View

Section	Content
Header	Title, node ID, trash icon
Content	Full markdown content with syntax highlighting
Metadata	Created, updated, type, link
Dimensions	Editable dimension tags
Connections	Incoming/outgoing edges

Content Rendering

• Markdown support
• [NODE:id:"title"] renders as clickable links
• Syntax highlighting for code blocks
• YouTube embeds (if link is YouTube URL)

---

Search (Cmd+K)

Global search modal with 4-tier relevance:

1. Exact title match — Highest priority
2. Title substring — High priority
3. FTS content match — Medium priority
4. Semantic embedding — Conceptual matches

Features:

• Type-ahead instant results
• Keyboard navigation (↑↓, Enter)
• Click or Enter to open in Focus panel

---

Settings Panel

Access: Settings cog icon (top-right)

Tabs

Tab	Purpose
API Keys	Configure OpenAI/Tavily keys
Skills	View, edit, create skills
Tools	View available tools
Database	Full node table with filters/sorting
Logs	Activity feed (last 100 entries)
Context	Context/system information viewer
Agents	External agent (MCP) configuration

---

Map View

Visual graph of your knowledge network.

Features:

• Force-directed layout with pan/zoom
• Node size proportional to edge count
• Top 15 nodes labeled (title + dimensions)
• Click node to highlight connections
• Selection shows connected nodes in green

---

Database View

Full table view of all nodes.

Columns:

• Node (title + ID)
• Dimensions (folder badges)
• Edges (count)
• Updated (timestamp)

Features:

• Search by title/content
• Filter by dimensions
• Sort by updated/edges/created
• Pagination

---

Dimension Icons

Each dimension can have a custom Lucide icon.

To set:

1. Open Folder View → hover over dimension
2. Click edit (pencil) icon
3. Choose icon from curated options
4. Icons persist in localStorage

---

Node References

Format: [NODE:id:"title"]

Rendering:

• Clickable labels in node content
• Hover shows preview tooltip
• Click opens in Focus panel

---

Keyboard Shortcuts

Shortcut	Action
Cmd+K	Open search
Escape	Close modals/overlays

---

Design System

Colors

• Background: #0a0a0a (near black)
• Accent: Green (#22c55e) for actions, selections
• Text: White (primary), neutral-400 (secondary)

Typography

• Font: Geist (monospace feel)
• Sizes: 11-14px for UI, larger for content

Buttons

• Primary: White bg, black text
• Secondary: Transparent, border, white text
• Toggle: 28×28px, subtle border, icon only