LOOM USER'S GUIDE

╔═══════════════════════════════════════════════════════════════════╗
║                                                                   ║
║                    L O O M   V 1 . 0                              ║
║                                                                   ║
║              PROGRAMMER'S REFERENCE GUIDE                         ║
║                                                                   ║
║                         1985                                      ║
║                                                                   ║
╚═══════════════════════════════════════════════════════════════════╝

INTRODUCTION

Welcome to LOOM, the stream-oriented document rendering system for OCULUS V2. This manual will guide you through the fundamental operations of reading and writing data using the PEEK and POKE commands familiar to users of early microcomputers.

LOOM operates on a simple principle: documents are streams of tokens that flow through middleware transformations. Like the memory-mapped I/O of classic systems, every piece of data has an address, and every address can be read or written.

BASIC OPERATION

THE PEEK COMMAND

PEEK allows you to read data from any address in the LOOM system. The syntax is:

READY.
LOOM PEEK <ADDRESS>

The ADDRESS may take several forms:

Format	Description
slug	Read entire node
slug:section	Read specific section
slug:section.fence	Read fence content
slug:section.fence.key	Read specific key

EXAMPLE 1: Reading a Node

READY.
LOOM PEEK jenkins-pipeline-guide

# Jenkins Pipeline Guide

The Jenkins pipeline system provides...

EXAMPLE 2: Reading a Section

READY.
LOOM PEEK jenkins-pipeline-guide:configuration

The pipeline configuration requires the following...

EXAMPLE 3: Reading a YAML Value

READY.
LOOM PEEK ana:character-data.yaml.name
Ana

THE POKE COMMAND

POKE writes data to a specific address. Unlike PEEK, POKE requires a full path including the target key:

READY.
LOOM POKE <ADDRESS> <VALUE>

EXAMPLE:

READY.
LOOM POKE config:settings.yaml.debug true
✓ config:settings.yaml.debug = true

TRANSFORMATION LEVELS

LOOM operates at three transformation levels:

Level	Name	Description
L3	CODE	Raw content, no processing
L4	DATA	Executed, holes resolved
L5	TEXT	Rendered document

To specify a level, use the --level or -l flag:

READY.
LOOM PEEK ana:demo -l 3
${ana:character-data.yaml.name} says hello!

READY.
LOOM PEEK ana:demo -l 5
Ana says hello!

HOLE SYNTAX

Holes are placeholders that resolve against data fences. The syntax follows a unified path format:

${slug:section.fence.key}

SIMPLE HOLE:

${config:settings.yaml.timeout}

NESTED HOLE (Dynamic Resolution):

${ana:character-data.${ana:character-data.yaml.todays-gender}.emojis}

Nested holes resolve inside-out, like nested PEEK operations on the Commodore 64.

THE INCLUDE DIRECTIVE

Templates can be spliced into documents using the include directive:

{{include:template-name}}
{{include:template-name:section}}

When included, the template's holes resolve against the parent's fence index. This enables parameterized templates:

Parent Node:

## Config

\`\`\`yaml
server: production-01
port: 8080
\`\`\`

{{include:server-status-template}}

Template:

Server ${parent:config.yaml.server} is running on port ${parent:config.yaml.port}.

Result:

Server production-01 is running on port 8080.

OUTPUT FORMATS

PEEK returns data in several formats based on the target:

Flag	Format	Description
-o markdown	Markdown	Rendered document
-o json	JSON	Structured data
-o tokens	Tokens	Stream array

The system auto-detects the appropriate format based on what you're reading:

• Full nodes → Markdown (with pager for long documents)
• YAML fences → JSON
• Token streams → JSON array

MEMORY MAP

Like the Commodore 64's memory map, LOOM organizes content into addressable regions:

┌─────────────────────────────────────────┐
│  0000-FFFF   OCULUS NODES DIRECTORY     │
├─────────────────────────────────────────┤
│  NODE        Content divided into:      │
│  ├─ SECTIONS (## Heading)               │
│  │  ├─ FENCES (\`\`\`yaml)               │
│  │  │  └─ KEYS (nested.path)            │
│  │  └─ PROSE (paragraphs)               │
│  └─ METADATA (frontmatter)              │
└─────────────────────────────────────────┘

THE MIDDLEWARE CHAIN

When you PEEK at L5, content flows through:

• TOKENIZE - Parse markdown into stream
• INTERPOLATE - Resolve ${...} holes
• INCLUDE - Splice templates
• EXECUTE - Run code fences
• RENDER - Output to format

This is the PAUSE → FETCH → SPLICE → CONTINUE algorithm.

QUICK REFERENCE CARD

╔═════════════════════════════════════════════════════════╗
║  LOOM QUICK REFERENCE                                   ║
╠═════════════════════════════════════════════════════════╣
║  PEEK <addr>              Read data                     ║
║  PEEK <addr> -l 3         Read raw (L3)                 ║
║  PEEK <addr> -l 5         Read rendered (L5)            ║
║  PEEK <addr> -o json      Force JSON output             ║
║  POKE <addr> <val>        Write data                    ║
║                                                         ║
║  ADDRESS FORMATS:                                       ║
║    slug                   Full node                     ║
║    slug:section           Section only                  ║
║    slug:section.fence     Fence content                 ║
║    slug:section.fence.key Specific key                  ║
║                                                         ║
║  HOLE SYNTAX:                                           ║
║    ${slug:section.fence.key}                            ║
║                                                         ║
║  INCLUDE SYNTAX:                                        ║
║    {{include:slug}}                                     ║
║    {{include:slug:section}}                             ║
╚═════════════════════════════════════════════════════════╝

APPENDIX A: ERROR MESSAGES

Error	Meaning
Node not found: slug	The specified node does not exist
Key not found: key	Path does not resolve to data
[CYCLE: addr]	Circular include detected
[NOT FOUND: addr]	Include target missing
Cannot parse fence as YAML	Fence content is not valid YAML

APPENDIX B: TECHNICAL SPECIFICATIONS

• Token stream format: JSON array of {type, content, attrs, position, level}
• Fence languages: yaml, json, python, bash, sql, and more
• Maximum include depth: 10 levels
• Hole nesting: unlimited (inside-out resolution)

---

LOOM is part of the OCULUS V2 documentation system. Copyright 2025. All rights reserved.

READY.
█

Provenance

Document

• Status: 🔴 Unverified

Changelog

• 2026-01-11 07:35: Node created by mcp - Creating Commodore 64 style user guide for Loom as requested

North

slots:
- slug: oculus-v2-first-principles
  context:
  - Linking V2 first principles to Loom user guide

East

slots:
- slug: loom-case-study-devops
  context:
  - Linking user guide to case study

West

slots:
- slug: loom-dev-report-2025-01-11
  context:
  - Linking dev report to user guide

South

slots:
- context:
  - Linking workflow guide as child of main loom user guide
  slug: loom-workflow-guide
- context:
  - Edges model as child of main loom guide
  slug: loom-edges-model