🎓 Oculus User Guide

Welcome to Oculus - your navigable mind palace for infrastructure documentation and knowledge management.

What is Oculus?

Oculus is a markdown-based graph navigation system that lets you:

• Navigate through interconnected documentation nodes like a text adventure
• Execute components that fetch live data and render it beautifully
• Link related concepts with cardinal directions (north/south/east/west)
• Embed dynamic components (fortunes, Magic 8-Ball, slot machines, etc.)

Quick Start

# Navigate to a node
oculus goto tutorial-room

# Look at current position
oculus look

# Create a new node
oculus create my-node

# Link nodes together
oculus link my-node north tutorial-room

Core Concepts

1. Nodes

Everything in Oculus is a node - a markdown file with:

• Content (headers, text, code blocks)
• Metadata (YAML frontmatter)
• Slots (navigation links in 4 directions)
• Components (dynamic, executable elements)

2. Navigation

Move through your knowledge graph using cardinal directions:

• North: Usually hierarchical parent or overview
• South: Usually detailed/child nodes
• East/West: Usually related/sibling nodes

3. Components

Executable markdown blocks that fetch and display data:

• :::fortune::: - Random wisdom
• :::magic8ball::: - Mystical answers
• :::slotmachine::: - Spin the reels
• Custom components you create

4. The Sprouting Pattern (Jack and the Beanstalk)

Oculus processes nodes through progressive enhancement stages like Jack's beanstalk growing from seed to castle:

• 🌱 SEED (raw) - The magic bean: raw markdown, no processing
• 🌿 SPROUT (substituted) - Growing overnight: variables ${...} resolved
• 🪴 STALK (interpolated) - Climbing to the sky: includes {{include:...}} assembled
• ☁️ CLOUDS (rendered) - Breaking through clouds: fences executed, components rendered
• 🏰 CASTLE (interactive) - The giant's castle: web components hydrated (future)

You can jump in at any level - the "Fortnite pattern" - and Oculus will catch you by building the previous stages automatically.

Guide Categories

This guide is organized into focused topics. Navigate using the slots below to explore specific areas.

Getting Started → See slots.north CLI Commands → See slots.east Component System → See slots.south Advanced Topics → See slots.west

North

slots:
- getting-started

South

slots:
- component-system
- template-guide
- interpolation-guide
- alias-guide

East

slots:
- cli-commands
- agentic-user-guide
- jira-how-to

West

slots:
- navigation-slots
- navigation-conventions
- troubleshooting