/reality - Token-Efficient Codebase Queries

"Query the reality, not the full codebase."

Purpose

Provide token-optimized, read-only access to codebase knowledge extracted by /ride. Enables agents to query another codebase's API surface, interfaces, and entry points using minimal tokens while remaining grounded in actual code.

Invocation

# Show index (routing hub)
/reality

# Query specific reality file
/reality api-surface
/reality types
/reality interfaces
/reality structure
/reality entry-points

# Cross-repo queries
/reality --repo ../smart-contracts api-surface
/reality --repo /path/to/backend types

Prerequisites

• Loa must be mounted (.loa-version.json exists)
• Reality files must be generated by /ride
• Target repo must have grimoires/loa/reality/ directory

Available Reality Files

File	Purpose	Token Budget
index.md	Routing hub with codebase summary	< 500
api-surface.md	Public function signatures, API endpoints	< 2000
types.md	Type definitions, schemas	< 2000
interfaces.md	Integration patterns, webhooks	< 1000
structure.md	Directory tree with annotations	< 1000
entry-points.md	Main files, CLI commands, routes	< 500

Routing Logic

No Arguments: Show Index

When invoked without arguments, display the index.md routing hub:

## Reality Index

[Content of grimoires/loa/reality/index.md]

---

**Query specific files:**
- `/reality api-surface` - Public API functions
- `/reality types` - Type definitions
- `/reality interfaces` - Integration patterns
- `/reality structure` - Directory layout
- `/reality entry-points` - Starting points

With File Name: Read Specific File

When invoked with a known file name:

1. Validate file exists in grimoires/loa/reality/
2. Read file content
3. Format response with citation and freshness

Cross-Repo: --repo Flag

When --repo flag is provided:

1. Resolve path (relative or absolute)
2. Verify target repo has .loa-version.json (Loa mounted)
3. Verify target repo has grimoires/loa/reality/ directory
4. Read requested file from target repo
5. Format response with cross-repo citation

Response Format

All responses include:

# Reality: [file-name]

> **Source**: grimoires/loa/reality/[file].md
> **Generated**: [timestamp] ([N] days ago)
> **Commit**: [short hash]

[File content]

---

**Follow-up queries:**
- `/reality [other-file]` - [description]

Freshness Checking

Reality files include generation timestamps. The command:

1. Parses .reality-meta.json for generated_at
2. Calculates days since generation
3. Displays warning if > 7 days old:

**Stale Reality Warning**

Reality files were generated [N] days ago (threshold: 7 days).
Code may have changed. Consider re-running `/ride` for fresh analysis.

---

Error Handling

Scenario	Response
No reality folder	"No reality exists. Run /ride first to generate codebase analysis."
Stale reality (> 7 days)	Warning displayed, content still shown
Invalid file name	"Unknown reality file: [name]. Available: api-surface, types, interfaces, structure, entry-points"
Cross-repo not found	"Repository not found at path: [path]. Verify path exists."
Cross-repo no Loa	"Target repository is not a Loa project. No .loa-version.json found."
Cross-repo no reality	"No reality exists in target repo at [path]. Run /ride there first."

Implementation Notes

Path Resolution for --repo

resolve_repo_path() {
  local input_path="$1"

  # Handle relative paths
  if [[ "$input_path" == ../* || "$input_path" == ./* ]]; then
    realpath "$input_path" 2>/dev/null || {
      echo "ERROR: Cannot resolve path: $input_path"
      return 1
    }
  else
    # Absolute path - use as-is
    echo "$input_path"
  fi
}

Reality File Validation

validate_reality() {
  local repo_path="${1:-.}"
  local reality_dir="$repo_path/grimoires/loa/reality"

  # Check Loa is mounted
  if [[ ! -f "$repo_path/.loa-version.json" ]]; then
    echo "ERROR: Not a Loa project"
    return 1
  fi

  # Check reality exists
  if [[ ! -d "$reality_dir" ]]; then
    echo "ERROR: No reality folder"
    return 1
  fi

  # Check index exists
  if [[ ! -f "$reality_dir/index.md" ]]; then
    echo "ERROR: Reality incomplete - missing index.md"
    return 1
  fi

  return 0
}

llms.txt Philosophy

This command implements the llms.txt proposal:

"The idea is to have a single file that serves as a 'hub' to help the LLM understand the codebase, and then have 'spokes' that provide more specific information."

• Hub: index.md with routing table
• Spokes: Specialized files for specific domains
• Progressive disclosure: Query what you need, not everything

Related Commands

• /ride - Generate reality files from codebase analysis
• /plan-and-analyze - Uses reality files for brownfield detection
• /mount - Install Loa on a repository

Next Step

If reality doesn't exist:

/ride

Then query:

/reality api-surface