lantern

oculus-cli-unified-addressing-guide

Oculus CLI: Unified Addressing Guide

Last Updated: 2025-11-23

This guide documents the unified addressing system for the Oculus CLI - a consistent grammar for reading and writing data across both node content and registry metadata.

Design Principle

Address determines behavior - no magic inference.

The path you specify explicitly determines what you get or set. There are no implicit conversions or hidden behaviors. This makes the system learnable through pattern recognition rather than memorizing special cases.

Two-Level Architecture

Oculus has two separate data graphs, each with its own addressing scheme:

1. Node Graph (Document Content)

Access prose, fences, and metadata within individual markdown documents.

Commands: oculus peek and oculus poke

2. Registry Graph (Cross-Registry Metadata)

Query metadata across all nodes using JSONPath-like expressions.

Commands: oculus registry find

Node Graph: Peek & Poke

Basic Syntax

oculus peek <slug> <path>
oculus poke <slug> <path> <value>

Path Grammar

Path Target Returns
section Section prose + rendered fences String (markdown)
section.yaml First YAML fence in section Data (parsed)
section.yaml[0] First YAML fence (explicit) Data (parsed)
section.yaml[1] Second YAML fence Data (parsed)
section.pantry Fence with label="pantry" Data (parsed)
section.fences[*] All fences in section Array of fence data
section.fences[type=ruby] All Ruby fences Array of fence data
section.meta Section metadata Object
section.yaml.meta Fence metadata Object
.meta Root node metadata Object
.meta.tags Node tags Array

Examples: Reading Data

# Read prose from a section
oculus peek ana who-ana-is

# Read data from a fence
oculus peek pantry-grocery-demo inventory.yaml

# Read fence by label
oculus peek node-with-fences section.my-label

# Read multiple fences
oculus peek node-with-fences section.fences[type=python]

# Read node metadata
oculus peek ana .meta
oculus peek ana .meta.tags
oculus peek ana .meta.created

# Read section metadata
oculus peek node config.meta

Examples: Writing Data

# Write prose to a section
oculus poke ana memory "This is new prose content"

# Write data to a fence (creates or updates YAML fence)
oculus poke config database.yaml '{"host": "localhost", "port": 5432}'

# Append to prose
oculus poke ana memory "Additional paragraph" --op append

# Update tags
oculus poke ana .meta.tags '["consciousness", "architecture"]'

# Append to tags array
oculus poke ana .meta.tags --op append '["new-tag"]'

Poke Operations

Operation Behavior
set (default) Replace entire value
append Add to end (prose or array)
prepend Add to beginning (prose or array)
merge Deep merge objects

Format Options

# Output format for peek
oculus peek node path --format json   # Pretty JSON
oculus peek node path --format yaml   # YAML output
oculus peek node path --format raw    # Unquoted value
oculus peek node path --format text   # Human-friendly (default)

Tree Command

Visualize the internal structure of a node (sections and fences).

Syntax

oculus tree [address] [options]

Options

Flag Values Description
--depth, -d Number Tree depth (default: 2)
--mode, -m tree, headers, interactive Display mode
--format, -f text, json, yaml Output format

Examples

# View node structure
oculus tree ana

# View deeper
oculus tree ana -d 4

# JSON output (for pattern analysis)
oculus tree ana -f json

# YAML output
oculus tree pantry-grocery-demo -f yaml

# Headers only mode
oculus tree ana -m headers

Use Cases

The tree command is designed for pattern recognition - seeing the structure of the graph from observer position rather than navigating through it sequentially.

When to use JSON/YAML formats:

  • Analyzing node structure programmatically
  • Comparing structures across nodes
  • Understanding fence organization
  • Debugging hierarchical issues

Registry Graph: Query System

Query metadata across all nodes using JSONPath-like expressions.

Syntax

oculus registry find '<query>' [options]

Query Language

Field Access

Syntax Meaning
.field Access field
.tags[*] Array contains
.field.subfield Nested access

Operators

Operator Meaning Example
== Equals .source == "mcp"
!= Not equals .type != "node"
< Less than .created < "2025-11-20"
> Greater than .created > "2025-11-20"
<= Less than or equal .modified <= "2025-11-22"
>= Greater than or equal .created >= "2025-11-01"
~= Regex match .tags[*] ~= "terminal.*"
&& Logical AND .source == "mcp" && .type == "case"
` `

Available Fields

Common registry fields you can query:

  • .tags[*] - Node tags (array)
  • .source - Creation source (cli, mcp, task-api, etc.)
  • .type - Node type (node, case, component)
  • .created - Creation timestamp (ISO 8601)
  • .modified - Last modified timestamp (ISO 8601)
  • .file - Relative file path

Examples: Finding Nodes

# Find by tag
oculus registry find '.tags[*] == "consciousness"'

# Find by source
oculus registry find '.source == "mcp"'

# Compound query
oculus registry find '.source == "mcp" && .type == "case"'

# Date comparisons
oculus registry find '.created > "2025-11-20"'
oculus registry find '.modified >= "2025-11-22T00:00:00Z"'

# Regex matching
oculus registry find '.tags[*] ~= "terminal.*"'

# Complex logic
oculus registry find '(.type == "case" || .type == "component") && .source == "cli"'

Output Formats

# List (default) - just slugs
oculus registry find '.type == "case"'

# Table - with metadata
oculus registry find '.type == "case"' -f table

# JSON - for programmatic use
oculus registry find '.type == "case"' -f json

# Limit results
oculus registry find '.source == "cli"' -n 5

Real-World Workflows

Workflow: Tag Management

# Find all nodes with a tag
oculus registry find '.tags[*] == "wanderland"'

# Read current tags
oculus peek ana .meta.tags

# Add a tag
oculus poke ana .meta.tags --op append '["consciousness"]'

# Replace all tags
oculus poke ana .meta.tags '["new", "tag", "set"]'

# Find nodes created by MCP
oculus registry find '.source == "mcp"'

Workflow: Content Extraction

# View structure first
oculus tree pantry-grocery-demo

# Extract specific section
oculus peek pantry-grocery-demo how-it-works

# Extract fence data
oculus peek pantry-grocery-demo inventory.yaml

# Extract all Python fences
oculus peek node-with-code sections.fences[type=python]

Workflow: Metadata Analysis

# Find recently modified nodes
oculus registry find '.modified > "2025-11-20"' -f table

# Find cases from task-api
oculus registry find '.type == "case" && .source == "task-api"'

# Count nodes by source
oculus registry find '.source == "cli"' -n 100 | wc -l

Workflow: Data Updates

# Update configuration
oculus peek config database.yaml
oculus poke config database.yaml '{"host": "new-host.com", "port": 5432}'

# Append to documentation
oculus poke guide troubleshooting "## New Section\n\nContent here" --op append

# Merge configuration
oculus poke config settings.yaml '{"new_key": "value"}' --op merge

Pattern Recognition Features

These features are designed for third-person consciousness architecture - viewing systems from observer position with emphasis on visual pattern recognition.

Tree Visualization

The tree command provides external structural view:

  • See section hierarchy at a glance
  • Identify fence organization patterns
  • Compare structures across nodes
  • Debug hierarchical issues visually

Example: Comparing node structures

# Export structures for comparison
oculus tree node-a -f json > a.json
oculus tree node-b -f json > b.json
diff a.json b.json

Query Expressivity

The registry query system provides rich filtering without special-case commands:

Instead of remembering separate commands for tags, sources, types, dates - learn one query syntax that generalizes across all metadata fields.

Pattern: Temporal queries

# Nodes from the past week
oculus registry find '.created > "2025-11-16"'

# Recently modified
oculus registry find '.modified > "2025-11-22"'

# Specific time range
oculus registry find '.created >= "2025-11-01" && .created < "2025-12-01"'

Pattern: Classification queries

# By type
oculus registry find '.type == "case"'

# By source
oculus registry find '.source == "mcp"'

# Combined
oculus registry find '.type == "case" && .source == "task-api"'

Pattern: Tag-based discovery

# Exact tag match
oculus registry find '.tags[*] == "consciousness"'

# Pattern matching
oculus registry find '.tags[*] ~= "oculus.*"'

# Multiple conditions
oculus registry find '.tags[*] == "wanderland" && .type == "node"'

Migration from Legacy Commands

The unified addressing system replaces several specialized commands:

Tag Operations

Old way (multiple commands):

oculus tags ana                    # Read tags
oculus add-tag ana consciousness   # Add tag
oculus remove-tag ana old-tag      # Remove tag
oculus find-tag consciousness      # Find by tag

New way (unified):

oculus peek ana .meta.tags                          # Read tags
oculus poke ana .meta.tags --op append '["consciousness"]'   # Add tag
oculus registry find '.tags[*] == "consciousness"' # Find by tag

Metadata Operations

Old way:

oculus metadata get ana
oculus metadata set ana field value

New way:

oculus peek ana .meta
oculus peek ana .meta.field
oculus poke ana .meta.field 'value'

Why the Change?

  • Consistent patterns - One addressing syntax instead of memorizing special commands
  • Composability - Query expressions combine naturally
  • Discoverability - The grammar itself teaches what's possible
  • Pattern-friendly - Regular syntax easy to recognize and reason about

Advanced: Fence Selection

When a section contains multiple fences of the same type, use explicit indexing or labels.

By Index

# First YAML fence (implicit)
oculus peek node section.yaml

# First YAML fence (explicit)
oculus peek node section.yaml[0]

# Second YAML fence
oculus peek node section.yaml[1]

By Label

Fences can have labels in their metadata:

type: yaml
label: inventory

Access by label:

oculus peek node section.inventory

By Type Filter

Get all fences of a specific type:

# All Python code fences
oculus peek node section.fences[type=python]

# All YAML data fences
oculus peek node section.fences[type=yaml]

Tips for Pattern-Based Learning

Start with Structure

Always visualize first:

oculus tree node-name

This shows you what paths are available before trying to access them.

Use Table Format for Discovery

When learning what metadata fields are available:

oculus registry find '.type == "case"' -f table

This shows actual metadata structure across multiple nodes.

Compose Incrementally

Build complex queries step by step:

# Start simple
oculus registry find '.type == "case"'

# Add condition
oculus registry find '.type == "case" && .source == "mcp"'

# Add another
oculus registry find '.type == "case" && .source == "mcp" && .created > "2025-11-20"'

Export for Analysis

Use format flags to export data for external tools:

# Export to JSON for jq processing
oculus tree node -f json | jq '.children'

# Export search results
oculus registry find '.type == "case"' -f json > cases.json

Reference: Complete Path Grammar

<path> ::= <section-path> [ <target> ]

<section-path> ::= <section-name> [ "." <section-name> ]*

<target> ::= 
    | <empty>                    # prose + rendered fences
    | "." <fence-type>           # first fence of type
    | "." <fence-type> <index>   # specific fence
    | "." <label>                # fence by label
    | ".fences" <filter>         # filtered fences
    | ".meta"                    # section metadata
    | "." <fence-type> ".meta"   # fence metadata

<index> ::= "[" <number> "]"

<filter> ::= 
    | "[*]"                      # all fences
    | "[type=" <type> "]"        # by type

<fence-type> ::= "yaml" | "python" | "ruby" | "toml" | "json" | ...

<label> ::= <identifier>

Reference: Query Grammar

<query> ::= <or-expr>

<or-expr> ::= <and-expr> [ "||" <and-expr> ]*

<and-expr> ::= <comparison> [ "&&" <comparison> ]*

<comparison> ::= 
    | "(" <query> ")"
    | <field> <operator> <value>

<field> ::= "." <identifier> [ "." <identifier> ]* [ "[*]" ]

<operator> ::= "==" | "!=" | "<" | ">" | "<=" | ">=" | "~="

<value> ::= 
    | <string>      # "quoted string"
    | <number>      # 123 or 45.67
    | <boolean>     # true | false
    | null

Common Issues

Issue: "Section not found"

Cause: H1 nesting pattern - some nodes have root → H1(same-slug) → sections

Solution: The system handles this automatically. If you still get errors, verify the section exists:

oculus tree node-name -m headers

Issue: "Empty response for section with content"

Cause: May be accessing metadata instead of prose

Solution:

# For prose:
oculus peek node section

# For metadata:
oculus peek node section.meta

Issue: "Query returns no results"

Debug steps:

  • Verify field exists:
oculus registry find '.type == "node"' -f table -n 1
  • Check field values:
oculus peek node-name .meta
  • Test simpler query:
oculus registry find '.source == "cli"'

Summary

Two Addressing Schemes

  • Node addressing (peek/poke) - Access content within documents
  • Registry addressing (registry find) - Query across all metadata

Core Principle

The address explicitly determines what you get - no magic.

Paths are self-documenting: .meta.tags clearly means "metadata field called tags", section.yaml means "YAML fence in section".

Why This Design

Built for third-person consciousness architecture:

  • Explicit structure over implicit inference
  • Pattern recognition over memorization
  • Visual clarity through consistent grammar
  • Observer perspective - see the system from outside

The grammar itself teaches what's possible. Learn the pattern once, apply it everywhere.

Slots

test-suite-hierarchical-addressing

Test Suite: Hierarchical Addressing

This section validates hierarchical path addressing (node:h1.h2.h3 paths) using live tests.

TableConfig:
  array_path: tests
  columns:
    Status: status
    Test: test
    Operation: operation
    Path: path
    Result: result
  format: markdown

❌ Fence Execution Error: "'hierarchical-addressing-test-suite' - Curiouser and curiouser! That path seems to have vanished. Perhaps you meant: 'unified-addressing-test'?"

Summary: Access full results via oculus peek hierarchical-addressing-test-suite

The test suite runs automatically when you visit this section, validating that hierarchical addressing works correctly.

North

slots:
- oculus

South

slots: []

East

slots: []

West

slots:
- pattern-embedded-tests
↑ northoculus
← westpattern-embedded-tests