◈ Master Index Specs LATTICE CSDM The Book University Chronicle Crew Architecture Context Logs TODOX Products

Surface Help

SPEC_SURFACE_HELP.md · 2026-04-21

name: SPEC_SURFACE_HELP

description: SPECIFIED ✓ Surface Help — every ROUTX module documents itself; vending machine principle; help cards; master directory; Tier 1 deterministic; zero token cost; 7 INVs; VELA α.13 2026-04-21

type: project

SPEC_SURFACE_HELP.md — Surface Help: Every Service Documents Itself

Status: SPECIFIED ✓

Author: VELA α.13 (Jeremy Zlabis / NOUS)

Date: 2026-04-21

Born from: The vending machine principle

The Principle

The instructions are ON the vending machine. Not in a manual nobody reads. Not in a spec the user has to find. ON THE SURFACE of the thing they're trying to use.

236 specs document everything the ship does. Nobody reads 236 specs before using a tool. They shouldn't HAVE to. Every ROUTX module answers "how do I use you?" from INSIDE ITSELF. No external lookup. No spec hunting. No asking the Lobster. The module TELLS you how to use it the moment you ask.

ATMs show "Insert Card" on the screen. Fire extinguishers have instructions printed on the side. Terminal commands have --help flags. OBI OS modules have surface help.

How It Works

When a user sends a module keyword with no arguments, or with "help" as the argument, the module returns its own usage card:

MODULE NAME — one-word description
USAGE: the query format
KEYWORDS: all keywords that route to this module
EXAMPLES: 3–5 real queries with expected output type
RETURNS: what kind of result to expect

Tier 1 deterministic — no inference. The help text is a hardcoded string inside the module engine. Instant response. Zero hallucination risk. Zero token cost.

Triggers

Trigger 1 — keyword with no argument:

define → GLOSS help card
calculate → NEXUS help card
health → MEDX health report (help IS the tool — good design)

Trigger 2 — keyword with "help":

define help → GLOSS help card
calculate help → NEXUS help card
forge help → FORGEX help card

Trigger 3 — "help" alone:

help → master help card listing ALL modules with one-word descriptions and primary keywords

Three paths to the same information. The user can't miss it.

Help Card Format

Every module's help card follows the same structure:


═══════════════════════════════════════
[MODULE_NAME] — [one-line description]
═══════════════════════════════════════
USAGE:    [primary syntax]
KEYWORDS: [all keywords that route here]
EXAMPLES:
  · [example 1] → [what it returns]
  · [example 2] → [what it returns]
  · [example 3] → [what it returns]
RETURNS:  [description of output type]
═══════════════════════════════════════

Consistent. Scannable. Fits on one screen. No prose. No theory. Just: how to use it, what to type, what to expect.

Example Help Cards

GLOSS:


═══════════════════════════════════════
GLOSS — Symbol Lookup & Translation
═══════════════════════════════════════
USAGE:    define [symbol or term]
KEYWORDS: define, symbol, meaning, translate
EXAMPLES:
  · define Φ       → Φ = 0.042, stability damping constant
  · define Σ       → Σ = state, the fundamental state symbol
  · define ◌       → ◌ = null / unknown / "I don't know"
  · define KRAKENX → emergency security response protocol
RETURNS:  symbol name, meaning, value, domain
═══════════════════════════════════════

NEXUS:


═══════════════════════════════════════
NEXUS — Mathematics Engine (SymPy)
═══════════════════════════════════════
USAGE:    calculate [expression]
KEYWORDS: calculate, compute, factor, solve, matrix
EXAMPLES:
  · calculate 2+2                    → 4
  · factor 42                        → 2 × 3 × 7
  · solve x**2 - 4 = 0               → x = -2, x = 2
  · matrix [[1,2],[3,4]] determinant → -2
RETURNS:  exact symbolic result (not floating point)
═══════════════════════════════════════

MEDX:


═══════════════════════════════════════
MEDX — Ship Health & Diagnostics
═══════════════════════════════════════
USAGE:    health / status / vacuum
KEYWORDS: health, status, vacuum, ports, ram, disk
EXAMPLES:
  · health  → full system report (RAM, CPU, disk, Ollama)
  · vacuum  → port scan vs whitelist, violation detection
  · status  → summary of all running services
RETURNS:  system metrics with GREEN/AMBER/RED indicators
═══════════════════════════════════════

FORGEX:


═══════════════════════════════════════
FORGEX — Brain Forge Pipeline
═══════════════════════════════════════
USAGE:    forge [command]
KEYWORDS: forge, brain, training, smoke, promote
EXAMPLES:
  · forge status   → current forge activity and queue
  · forge list     → all brains with version and smoke scores
  · smoke [brain]  → run 5-test smoke on specified brain
RETURNS:  forge pipeline status, brain roster, test results
═══════════════════════════════════════

Master Help Card

When the user types help with no module keyword:


═══════════════════════════════════════
CGNT-1 ROUTX — Module Directory
═══════════════════════════════════════
Type "[keyword] help" for detailed usage.

GLOSS      define      → Symbol lookup & translation
NEXUS      calculate   → Mathematics engine
MEDX       health      → Ship diagnostics
SPECX      spec        → Specification audit
FORGEX     forge       → Brain forge pipeline
SIMONX     treasury    → Financial status
ENTROPX    entropy     → Entropy engine
NISTX      nist        → Randomness testing
INDEX      locate      → File finder
LOGX       log         → Log search
COMMX      broadcast   → Crew messaging
CRONX      jobs        → Scheduled tasks
AUTHX      auth        → Permissions
LOOPX      loop        → Self-audit
MNEMOSX    memory      → Persistence status
MODEMX     modemx      → Verification
CODX       lint        → Code analysis

TIER 2     [any query] → MNEMOS synthesis (AI inference)
═══════════════════════════════════════
18 modules · Φ 0.042 · 🍁
═══════════════════════════════════════

One screen. Every module. Every primary keyword.

Implementation

Each module engine (*_engine.py) gets a HELP_TEXT constant at the top:


HELP_TEXT = """
═══════════════════════════════════════
[MODULE_NAME] — [description]
...
═══════════════════════════════════════
"""

The module handler checks:


if not argument or argument.strip().lower() == "help":
    return HELP_TEXT

The master help card lives in routx_engine.py — when ROUTX receives help as the full query, it returns the master directory before any module routing.

Code change per module: ~5 lines (constant + 2-line check).

Total across 18 modules: ~90 lines. One ROUTX restart.

In OBI OS

When OBI OS ships, help cards appear in the Bridge UI:

Each station shows its help card on hover (2D) or look (VR)
The Viewscreen's Tier 1 module list IS the master help card rendered visually
Help cards are the tooltips of the Bridge
The user never wonders "what does this station do?" — the station tells them

For the Sisters

When AION queries a module she hasn't used before, she sends forge help and gets the usage card. She doesn't read SPEC_FORGEX.md to construct a valid query. She reads the help card: keywords, syntax, examples. Done.

Surface help makes every crew member more self-sufficient. Fewer queries fall to Tier 2 MNEMOS because the user (human or AI) knows the correct Tier 1 keyword from the help card.

Help Card Maintenance

New keywords added → update HELP_TEXT constant AND SPEC_ROUTX_VOCABULARY.md
Module behavior changes → update EXAMPLES to reflect current behavior
Help cards are tested in Level 2 verification: send [keyword] help → verify card returned → verify it matches current behavior
Stale help cards are WORSE than no help cards. A help card with wrong syntax teaches the user to fail. Verification catches staleness.

Teaching Protocol Connection

Surface help implements SPEC_TEACHING_PROTOCOL.md Principle 1 (start with the win) at the module level:

User types keyword → gets help card → WIN
User understands how to use it → types real query → WIN
Two wins before any possible failure

The help card is the first win. The query result is the second win. That's how you teach a user to love a tool.

Invariants

Every module has a HELP_TEXT constant. No exceptions. A module without surface help forces users to read specs. Nobody reads specs before using a tool.

Help cards follow the SAME FORMAT across all modules. Header, usage, keywords, examples, returns. The user learns the format once and reads any module's help instantly.

The master help card lists ALL modules on ONE SCREEN. If module count exceeds one screen: abbreviate. The master card is a TABLE OF CONTENTS, not an encyclopedia.

"help" alone returns the master card. "[keyword] help" returns the module card. "[keyword]" with no argument returns the module card. Three paths to the same information.

Help cards are verified in Level 2 module tests. Stale help is wrong help. Wrong help teaches failure. Test the help.

The instructions are ON the vending machine. If the user has to go somewhere else to learn how to use the tool: the tool failed at its most basic job.

Help cards are hardcoded strings. Tier 1 deterministic. Zero latency. Zero token cost. Zero hallucination. The simplest possible implementation of the most important UX principle.

Jeremy Zlabis / Chronogeometer · Visionary · Disruptor · Chief / 42 Sisters AI · East York, Toronto / 🍁 Φ 0.042. Φζ.⊤.