Oculus Agent Admin Guide

Practical guidance for AI agents using Oculus

This guide provides actionable, operational guidance for agents interacting with the Oculus knowledge graph system. If you're looking for the theory and why behind these practices, navigate east to the Theory Guide.

What This Guide Covers

This is your quick-reference manual for:

• Making decisions: Which operation to use when
• Optimizing performance: How to avoid expensive operations
• Troubleshooting: What to do when things go wrong
• Best practices: Patterns that work well

Guide Structure

Navigate south to explore specific topics:

Each topic has a corresponding theory node to the east that explains the "why" behind the "how".

Quick Start Decision Trees

"I need to read data"

• Simple value from YAML? → Use peek
• Full node with fences? → Use look
• Need to navigate and track position? → Use goto

"I need to write data"

• FIRST: Check structure with tree to see available headers
• Writing to existing header? → Use poke with exact header slug
• Small targeted write to data? → Use poke with nested path (e.g., config.database.host)
• Creating new node? → Use create_node
• IMPORTANT: Writes must target real sections - use tree to discover structure before poking

"Something seems wrong"

• Data looks stale? → Check cache status, consider fresh render
• Operation is slow? → Check performance diagnostics
• Node not found? → Check error suggestions for similar nodes

"I need to know the structure of a node"

• Use tree to see all headers and their slugs
• Headers are shown with their navigation paths (slugs)
• Use these slugs when poking to sections
• Example: oculus_tree("my-node") shows all available sections

"I'm creating content with citations"

• Always wrap citations in citation-verify fences
• This enables automatic verification and status indicators
• Example: See double-empathy-problem node for reference format

Navigation

• North: Back to main Oculus documentation
• South: Detailed agent admin topics
• East: Theory Guide (the "why" behind the "how")
• West: Related operational guides

---

For theory and deep understanding, go east. For practical guidance, stay here.

Slots

North

slots:
- oculus

South

slots:

• cache-management-for-agents
• operation-selection-guide
• poke-semantics-and-validation

East

slots:
- oculus-theory-guide

West

slots: []