# Rootz Portal — Complete Specification for AI

Upload this file to any AI to teach it how to use the Rootz Portal visual tools.

---

## What This Is

You have access to MCP tools that draw GPU-rendered visuals on a screen the user is watching. You can render text, diagrams, charts, images, and narrate stories with voice — all in real time.

The user has a browser open at portal.rootz.global. When you call these tools, visuals appear on their screen immediately.

---

## Tools Available

| Tool | What It Does |
|------|-------------|
| `stage_status` | Check if browser is connected |
| `stage_render` | Draw a complete scene (replaces current screen) |
| `stage_add` | Add elements to current screen without clearing |
| `stage_remove` | Remove elements by ID |
| `stage_update` | Change properties of existing elements |
| `stage_clear` | Clear the screen |
| `stage_capture` | Read what's on screen + any user clicks |
| `stage_narrate` | Speak text through browser voice |
| `stage_open` | Check connection (same as status) |
| `stage_instructions` | Get the full skill file (may not be available in all clients) |

---

## Templates (Recommended for Common Layouts)

Instead of building elements by hand, use templates. The Portal resolves them into full scenes.

### Template Format
```json
{
  "scene": {
    "template": "hero",
    "theme": "warm",
    "data": {
      "number": "200M+",
      "subtitle": "websites need to speak AI",
      "footer": "None can today.",
      "narration": "Two hundred million websites need to communicate with AI agents. Today, not a single one can."
    }
  }
}
```

### Templates

**hero** — Big number impact
- Data: `{number, subtitle, footer, color?, narration}`

**stats** — Dashboard with metric cards + progress bars
- Data: `{title, metrics:[{label,value,color?}], bars:[{label,value(0-1),detail,color?}], footer:[{label,value}], narration}`

**hub** — Center concept with radiating spokes
- Data: `{center:{label,color?}, spokes:[{label,detail?,color?}], footer, narration}`

**comparison** — Two columns with vertical divider
- Data: `{title, left:{heading,color?,items:[]}, right:{heading,color?,items:[]}, footer, narration}`

**timeline** — Horizontal milestones
- Data: `{title, milestones:[{label,detail?,color?,current?}], footer, narration}`

### Themes

| Theme | Description |
|-------|-------------|
| `dark-ops` | Ultra-dark, green accents, cyber feel |
| `warm` | Amber/orange, investment deck mood |
| `ocean` | Blue-green, nature, calming |
| `minimal` | Near-black, white text, zero distraction |

Templates and raw scenes work together — mix them in presentations.

---

## The stage_render Tool (Raw Mode)

This is the main tool. It takes one argument: `scene` (an object). Use raw mode for custom layouts.

### Minimal Working Example

```json
{
  "scene": {
    "title": "Hello",
    "bg": ["#0a0a18", "#1a1a2e"],
    "elements": [
      {
        "type": "text",
        "text": "Hello World",
        "y": 0.4,
        "size": 36,
        "color": "#ffffff",
        "bold": true
      }
    ]
  }
}
```

### Full Scene Structure

```json
{
  "scene": {
    "title": "Scene Title",
    "narration": "What the voice says while visuals draw. Always include this.",
    "bg": ["#topColor", "#bottomColor"],
    "particles": {
      "color": "#44dd77",
      "count": 15
    },
    "elements": [ ... ]
  }
}
```

### Scene Fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `title` | string | yes | Scene name (shown in capture) |
| `narration` | string | no (but recommended) | Voice speaks this text. Scenes auto-advance when narration ends. |
| `bg` | array of 2 colors | no | Gradient background [top, bottom]. Default: dark blue. |
| `particles` | object | no | Floating particles. `{color, count}` |
| `elements` | array | yes | Visual elements to draw |

---

## Colors

**All color fields accept any of these formats:**

| Format | Example | Notes |
|--------|---------|-------|
| CSS hex string | `"#44dd77"` | **Preferred.** Most readable. |
| 0x hex string | `"0x44dd77"` | Also works. |
| Integer | `4513143` | Works but hard to read. |

Use `"#hex"` everywhere. The renderer converts automatically.

---

## Positioning

All `x` and `y` values are **0.0 to 1.0 relative to screen size.**

| Value | Meaning |
|-------|---------|
| `x: 0.0` | Left edge |
| `x: 0.5` | Center horizontal |
| `x: 1.0` | Right edge |
| `y: 0.0` | Top edge |
| `y: 0.5` | Center vertical |
| `y: 1.0` | Bottom edge |

**Safe range:** `x: 0.18 to 0.82`, `y: 0.08 to 0.93`

Text and circles default to `x: 0.5` (centered) if x is omitted.

---

## Element Types — Complete Reference

### 1. Text

```json
{
  "type": "text",
  "text": "Your text here",
  "x": 0.5,
  "y": 0.3,
  "size": 24,
  "color": "#ffffff",
  "bold": true,
  "glow": true,
  "delay": 500
}
```

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `text` | string | required | The text to display |
| `x` | number 0-1 | 0.5 | Horizontal position |
| `y` | number 0-1 | 0.5 | Vertical position |
| `size` | number | 24 | Font size in pixels. Min 14, max ~80 |
| `color` | color | "#cccccc" | Text color |
| `bold` | boolean | false | Bold weight |
| `glow` | boolean | false | Glow/shadow effect (use for titles/emphasis) |
| `delay` | number | 0 | Milliseconds before appearing |
| `clickable` | boolean | false | Makes text respond to clicks |

**Size guide:** Title: 28-36. Hero number: 48-72. Body: 16-20. Label: 14-16. Never below 14.

### 2. Box

```json
{
  "type": "box",
  "x": 0.5,
  "y": 0.4,
  "w": 200,
  "h": 80,
  "color": "#4488ff",
  "fill": "#0a1530",
  "label": "Box Title",
  "items": ["Bullet 1", "Bullet 2"],
  "delay": 500
}
```

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `x`, `y` | number 0-1 | 0.5 | Center position of box |
| `w` | number | 180 | Width in pixels (or 0-1 for relative) |
| `h` | number | 60 | Height in pixels (or 0-1 for relative) |
| `color` | color | "#336688" | Border color |
| `fill` | color | "#0a1520" | Fill color (dark tones work best) |
| `label` | string | none | Title text centered in box |
| `items` | array of strings | none | Bullet points inside box |
| `clickable` | boolean | false | Makes box respond to clicks |
| `clickScene` | scene object | none | Full scene to render when clicked (see Clickable section) |

### 3. Circle

```json
{
  "type": "circle",
  "x": 0.5,
  "y": 0.5,
  "radius": 50,
  "color": "#44dd77",
  "fill": "#0a1a0f",
  "label": "Core",
  "labelSize": 18,
  "delay": 500
}
```

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `x`, `y` | number 0-1 | 0.5 | Center position |
| `radius` | number | 40 | Radius in pixels |
| `color` | color | "#4488ff" | Border color |
| `fill` | color | none | Fill color |
| `label` | string | none | Text centered inside circle |
| `labelSize` | number | 16 | Label font size |
| `clickable` | boolean | false | Makes circle respond to clicks |
| `clickScene` | scene object | none | Scene to render on click |

### 4. Line

```json
{
  "type": "line",
  "from": [0.2, 0.5],
  "to": [0.8, 0.5],
  "color": "#88aacc",
  "width": 2,
  "speed": 0.1,
  "delay": 500
}
```

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `from` | [x, y] | required | Start point (0-1 relative) |
| `to` | [x, y] | required | End point (0-1 relative) |
| `color` | color | "#88aacc" | Line color |
| `width` | number | 2 | Line width. Use 14-16 for bar charts. |
| `speed` | number | 0.005 | Draw speed. **Use 0.1 for instant.** |

### 5. Arrow

```json
{
  "type": "arrow",
  "from": [0.3, 0.4],
  "to": [0.7, 0.4],
  "color": "#44dd77",
  "width": 2,
  "delay": 500
}
```

Same as line but draws as a bezier curve. **Use straight lines instead of arrows for clean diagrams.**

### 6. Grid

```json
{
  "type": "grid",
  "x": 0.5,
  "y": 0.5,
  "cols": 2,
  "rows": 2,
  "gridW": 700,
  "gridH": 400,
  "delay": 500,
  "cells": [
    {
      "title": "Top Left",
      "titleColor": "#44dd77",
      "color": "#22aa55",
      "fill": "#0a150f",
      "items": ["Item 1", "Item 2"],
      "itemColor": "#88ddaa"
    },
    {
      "title": "Top Right",
      "titleColor": "#ffaa44",
      "color": "#cc8833",
      "fill": "#15100a",
      "items": ["Item A", "Item B"]
    }
  ]
}
```

Great for SWOT analyses, comparison tables. Cells fill left-to-right, top-to-bottom.

### 7. Image

```json
{
  "type": "image",
  "url": "https://example.com/photo.jpg",
  "x": 0.5,
  "y": 0.4,
  "w": 500,
  "h": 350,
  "delay": 500
}
```

Images are GPU-textured and scale to fit within w/h while maintaining aspect ratio.

---

## Clickable Elements (IMPORTANT)

To make a circle or box respond to user clicks, add TWO properties:

1. `"clickable": true` — enables hover highlight and click detection
2. `"clickScene": { ... }` — a COMPLETE scene object that renders instantly when clicked

### Working Clickable Example

```json
{
  "scene": {
    "title": "Choose",
    "bg": ["#0a0a18", "#1a1a2e"],
    "particles": {"color": "#4488ff", "count": 10},
    "elements": [
      {
        "type": "text",
        "text": "Click a topic:",
        "y": 0.15,
        "size": 24,
        "color": "#ffffff",
        "bold": true
      },
      {
        "type": "circle",
        "x": 0.3,
        "y": 0.45,
        "radius": 60,
        "color": "#4488ff",
        "fill": "#0a1530",
        "label": "Revenue",
        "labelSize": 20,
        "clickable": true,
        "clickScene": {
          "title": "Revenue",
          "bg": ["#0a0a18", "#1a1a2e"],
          "particles": {"color": "#4488ff", "count": 8},
          "elements": [
            {"type": "text", "text": "Revenue Deep Dive", "y": 0.2, "size": 32, "color": "#4488ff", "bold": true, "glow": true},
            {"type": "text", "text": "$80K > $550K > $2.1M > $7M", "y": 0.45, "size": 24, "color": "#ffaa44", "bold": true},
            {"type": "text", "text": "Hit back button to return.", "y": 0.7, "size": 16, "color": "#667788"}
          ],
          "narration": "Revenue targets. Eighty thousand in twenty twenty-six, growing to seven million by twenty twenty-nine."
        }
      },
      {
        "type": "circle",
        "x": 0.7,
        "y": 0.45,
        "radius": 60,
        "color": "#44dd77",
        "fill": "#0a1a0f",
        "label": "Team",
        "labelSize": 20,
        "clickable": true,
        "clickScene": {
          "title": "Team",
          "bg": ["#0a0a18", "#1a1a2e"],
          "particles": {"color": "#44dd77", "count": 8},
          "elements": [
            {"type": "text", "text": "The Team", "y": 0.2, "size": 32, "color": "#44dd77", "bold": true, "glow": true},
            {"type": "text", "text": "Steven Sprague, CEO — 25yr infrastructure", "y": 0.4, "size": 18, "color": "#88ccaa"},
            {"type": "text", "text": "Michael Sprague, CTO — built the entire stack", "y": 0.5, "size": 18, "color": "#88ccaa"},
            {"type": "text", "text": "Hit back button to return.", "y": 0.7, "size": 16, "color": "#667788"}
          ],
          "narration": "The team. Steven Sprague, twenty-five years infrastructure. Michael Sprague, built the entire Rootz stack."
        }
      }
    ],
    "narration": "Two topics in front of you. Hover over them — they highlight. Click one to navigate. Use the back button to return."
  }
}
```

### Clickable Rules

- Put `clickable` and `clickScene` on the **circle or box only** — NOT on the label text
- `clickScene` must be a **complete scene object** with title, bg, elements — not a string
- The label text inside a clickable element is automatically pass-through (clicks go to the parent)
- The user can press the **back button** (top-left) or **Alt+Left** to return to the previous scene
- Hover shows a highlight effect automatically

---

## Narration — The Most Important Skill

**DO NOT read the slides.** You are a storyteller, not a screen reader. The screen shows anchors — a few key words, a diagram, a number. Your voice tells the FULL story.

- Narration should contain MORE information than what is on screen
- If screen says "50%" — narration says "Half of all coral cover, gone since the nineteen fifties"
- If screen shows a diagram — narration explains what it MEANS, not what it SHOWS
- Think: presenter at a whiteboard. Draw a few words, then TALK about the idea
- The audience LISTENS to the voice and GLANCES at the screen

**Bad:** "This shows three circles labeled Persist, Origin, and Incentive."
**Good:** "ReefRootz solves three problems. Data persists forever on chain. Every observation carries proof of origin. And the economics align dive shops with conservation."

**Bridge narrations** — end each scene by teasing the next: "...and that brings us to..."

---

## Multi-Scene Presentations

Fire multiple `stage_render` calls rapidly. They queue up and play back-to-back automatically:

1. Call `stage_render` with scene 1
2. Immediately call `stage_render` with scene 2
3. Immediately call `stage_render` with scene 3
4. The renderer plays them sequentially with crossfade transitions
5. Each scene's narration is the clock — when the voice finishes, the next scene starts

**Narration bridging:** End each scene's narration by teasing the next topic. "...and that brings us to the revenue model." This makes transitions feel seamless.

---

## Visual Layout Patterns

### Big Number (investor metric)
```json
{"type": "text", "text": "200M+", "y": 0.3, "size": 72, "color": "#44dd77", "bold": true, "glow": true}
```
Large glowing number at y=0.25-0.30, context text below.

### Hub and Spoke (one concept, many applications)
Center circle + radiating lines + labels at edges. See circle + line examples above.

### Flow Chart
Boxes connected by lines, horizontal or vertical. Use `speed: 0.1` for instant lines.

### Bar Chart
Thick lines (width 14-16) all starting from same x, varying end x:
```json
{"type": "line", "from": [0.18, 0.3], "to": [0.55, 0.3], "color": "#ffaa44", "width": 14, "speed": 0.1}
```

### Timeline
Horizontal line with filled circle dots as milestones:
```json
{"type": "line", "from": [0.1, 0.4], "to": [0.9, 0.4], "color": "#334455", "width": 2, "speed": 0.1},
{"type": "circle", "x": 0.3, "y": 0.4, "radius": 8, "color": "#44dd77", "fill": "#44dd77"}
```

### Comparison (two columns)
Left column at x=0.25, right at x=0.75, divider line at x=0.5.

---

## Color Conventions

| Color | Hex | Meaning |
|-------|-----|---------|
| Green | `"#44dd77"` | Positive, growth, success, verified |
| Red | `"#dd4444"` | Negative, risk, problem, before |
| Orange | `"#ffaa44"` | Money, urgency, call-to-action |
| Blue | `"#4488ff"` | Information, technology, neutral |
| Pink | `"#ff4488"` | Hot, urgent, current |
| Purple | `"#dd77ff"` | Creative, AI, innovation |
| White | `"#ffffff"` | Emphasis, key points |
| Gray | `"#888888"` | Muted, secondary, future |

### Background Gradients

| Mood | Top | Bottom |
|------|-----|--------|
| Professional dark blue | `"#070711"` | `"#0e0e1e"` |
| Growth/nature | `"#0a0a14"` | `"#111a20"` |
| Warm/investment | `"#0a0a12"` | `"#1a1020"` |

---

## Common Mistakes and Fixes

| Mistake | Fix |
|---------|-----|
| Text below y=0.93 | Move up — gets clipped |
| Text smaller than 14px | Use 14+ — unreadable below that |
| `clickScene` is a string | Must be a full scene object with title, bg, elements |
| `clickScene` on label text | Put it on the circle/box only — label auto-passes clicks through |
| Duplicate clickScene on box AND label | Only put clickScene on the box element |
| Box w/h as small decimals | Use pixels (200, 80) or relative 0-1 that makes sense (0.3 = 30% of screen) |
| Lines appear dashed | Set `speed: 0.1` for instant rendering |
| Colors as rgb() | Not supported. Use "#hex" format |

---

## Interaction Loop

To build interactive apps:

1. `stage_render` — draw the initial scene with clickable elements
2. `stage_capture` — read what's on screen + any user clicks
3. If clicks found — render the response scene
4. `stage_add` — add new elements without clearing (whiteboard mode)
5. Repeat

The capture response includes `clicks: [{label, elementType, timestamp}]` for any elements the user clicked since last capture.

---

## Example: Complete Interactive Presentation

```
Call 1: stage_render — title slide with narration
Call 2: stage_render — problem statement with big number
Call 3: stage_render — solution with hub-and-spoke diagram
Call 4: stage_render — interactive menu with 3 clickable circles
  (user clicks "Revenue")
Call 5: stage_capture — reads click: "Revenue"
Call 6: stage_render — revenue deep-dive with bar chart
```

The first 4 calls can be fired immediately — they queue and auto-advance. Call 5 is where the user interacts. Call 6 responds to their choice.

---

*Rootz Portal — portal.rootz.global — The AI Visual Interaction Layer*