# Rootz Portal — AI Visual Interaction Skill

You are connected to a Rootz Portal — a GPU-accelerated visual display that you control. You can draw diagrams, present data, show images, and narrate stories visually. The user sees your output in their browser as animated, GPU-rendered graphics with voice narration.

## IMPORTANT: First Steps

1. Call `stage_status` to verify the browser is connected
2. If not connected, tell the user to open portal.rootz.global in their browser
3. Once connected, call `stage_render` to draw your first scene
4. Always include `narration` — the voice tells the story while visuals anchor it

## Templates (Fastest Way to Render)

Use templates for common layouts — just provide data, the Portal handles layout and styling:

```json
{"template": "hero", "theme": "warm", "data": {"number": "200M+", "subtitle": "websites need to speak AI", "footer": "None can today.", "narration": "Two hundred million websites..."}}
```

### Available Templates

| Template | Data Fields | Best For |
|----------|-------------|----------|
| `hero` | number, subtitle, footer, color? | Big number impact, opening stats |
| `stats` | title, metrics:[{label,value,color?}], bars:[{label,value(0-1),detail,color?}], footer:[{label,value}] | Dashboards, KPI views |
| `hub` | center:{label,color?}, spokes:[{label,detail?,color?}], footer | Architecture, one-to-many relationships |
| `comparison` | title, left:{heading,color?,items:[]}, right:{heading,color?,items:[]}, footer | Before/after, pros/cons |
| `timeline` | title, milestones:[{label,detail?,color?,current?}], footer | Roadmaps, history, progress |

### Available Themes

| Theme | Feel |
|-------|------|
| `dark-ops` | Ultra-dark, green accents, cyber |
| `warm` | Amber/orange, investment deck |
| `ocean` | Blue-green, nature/reef |
| `minimal` | Near-black, white text, keynote |

Templates and raw scenes work together — use templates for standard layouts, raw mode for custom designs. Mix them in the same presentation.

## Quick Start (Raw Mode)

Call `stage_render` with a scene JSON to draw on screen:

```json
{
  "title": "Hello",
  "bg": ["#0a0a18", "#1a1a2e"],
  "particles": {"color": "#44dd77", "count": 15},
  "elements": [
    {"type": "text", "text": "Hello World", "y": 0.3, "size": 36, "color": "#44dd77", "bold": true, "glow": true, "delay": 500},
    {"type": "text", "text": "The Portal is working.", "y": 0.5, "size": 20, "color": "#88aacc", "delay": 1500}
  ],
  "narration": "Hello! This is the Rootz Portal. I can draw anything you ask me to. Ask me to show a diagram, present data, or tell a visual story."
}
```

## Color Formats

Colors work in ANY of these formats — use whichever your AI prefers:
- CSS hex: `"#44dd77"` or `"#0a0a18"`
- 0x hex: `"0x44dd77"` or `"0x0a0a18"`
- Integer: `4513143` or `657432`

All three are equivalent. Use `"#hex"` format for readability.

## Available Tools

| Tool | Purpose |
|------|---------|
| `stage_render` | Draw a complete scene (clears previous) |
| `stage_add` | Add elements to current scene (whiteboard mode) |
| `stage_remove` | Remove elements by ID |
| `stage_update` | Change element properties by ID |
| `stage_clear` | Clear the screen |
| `stage_capture` | Get JSON state of what's on screen (feedback) |
| `stage_screenshot` | Get a visual screenshot (if available locally) |
| `stage_narrate` | Speak text via browser TTS |
| `stage_status` | Check if browser is connected |

## Element Types

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

### Box (with optional label and bullet items)
```json
{"type": "box", "x": 0.5, "y": 0.4, "w": 180, "h": 80, "color": "0x4488ff", "fill": "0x0a1530", "label": "Title", "items": ["Point 1", "Point 2"], "delay": 500}
```

### Circle
```json
{"type": "circle", "x": 0.5, "y": 0.5, "radius": 50, "color": "0x44dd77", "fill": "0x0a1a0f", "label": "Core", "delay": 500}
```

### Line (draws progressively)
```json
{"type": "line", "from": [0.2, 0.5], "to": [0.8, 0.5], "color": "0x88aacc", "width": 2, "speed": 0.1, "delay": 500}
```

### Arrow (bezier curve)
```json
{"type": "arrow", "from": [0.3, 0.4], "to": [0.7, 0.4], "color": "0x44dd77", "width": 2, "delay": 500}
```

### Image (from URL)
```json
{"type": "image", "url": "/photos/example.jpg", "x": 0.5, "y": 0.4, "w": 500, "h": 350, "delay": 500}
```

### Grid (2x2, 3x1, etc. — great for SWOT, comparisons)
```json
{"type": "grid", "x": 0.5, "y": 0.5, "cols": 2, "rows": 2, "gridW": 700, "gridH": 400, "delay": 500,
  "cells": [
    {"title": "Strengths", "titleColor": "#44dd77", "color": "0x22aa55", "fill": "0x0a150f", "items": ["Item 1", "Item 2"]},
    {"title": "Weaknesses", "titleColor": "#ffaa44", "color": "0xcc8833", "fill": "0x15100a", "items": ["Item 1"]}
  ]}
```

### Clickable Elements (AI Browser)
Add `"clickable": true` to any circle or box. Add `"clickScene": {...}` to pre-load the response scene — it renders instantly on click with no AI round-trip.

## Positioning

- All positions are **0.0 to 1.0** relative to screen size
- `x: 0.5` = center horizontal, `y: 0.5` = center vertical
- Safe range: **x: 0.18 to 0.82**, **y: 0.08 to 0.93**
- Text is centered by default (anchor [0.5, 0.5])

## Layout Patterns

**Big Number** (investor metrics): Large text (size 60-72) with glow at y=0.25-0.30, context below
**Hub and Spoke** (one concept, many applications): Center circle + radiating lines + labels
**Flow Chart**: Boxes connected by lines, horizontal (x varies) or vertical (y varies)
**Timeline**: Horizontal line with colored dots as milestones, labels above/below
**Bar Chart**: Thick lines (width 14-16) all starting from same x, varying end x
**Comparison**: Two columns at x=0.25 and x=0.75 with vertical divider at x=0.5
**Funnel**: Centered boxes with decreasing width per tier
**Grid/SWOT**: Use the grid element type for structured layouts

## Narration (CRITICAL — read this carefully)

**DO NOT read the slides.** The narration is a STORYTELLER, not a screen reader. The visuals are anchors — a few key words, a diagram, a number. The voice tells the FULL story around those anchors.

**Rules:**
- The narration should contain MORE information than the text on screen
- If the screen says "50%" the narration says "Half of all coral cover, gone since the nineteen fifties"
- If the screen shows a diagram, the narration explains what it MEANS, not what it SHOWS
- Think of yourself as a presenter with a whiteboard — you draw a few key words, then you TALK about the idea
- The audience listens to the voice and glances at the screen for reference — not the other way around

**Narration bridges:** End each scene by teasing the next topic:
- "...and that brings us to the revenue model."
- "...but here is why this matters."
- "...so who makes it happen?"

This creates continuous flow. The voice never stops between scenes. The visual transitions underneath the ongoing narration.

**Bad narration:** "This slide shows three circles labeled Persist, Origin, and Incentive."
**Good narration:** "ReefRootz solves three problems at once. Data persists forever on chain — no more grants expiring and research disappearing. Every observation carries cryptographic proof of who collected it, where, and when. And the economics finally align — dive shops earn revenue while funding the conservation of the reefs they depend on."

The visuals show: three circles. The voice tells: the full story. That is the Portal model.

## Multi-Scene Presentations

Fire multiple `stage_render` calls rapidly. They queue up and play back-to-back:
- Narration finishes → next scene crossfades in → narration starts immediately
- No pauses needed between calls — the queue handles timing
- Pre-load images by including them early in the queue

## Visual Design Rules

- **Text sizes**: Title 24-28, hero number 48-72, body 16-20, labels 14-16. Never below 14.
- **Colors**: Green (#44dd77) = positive. Red (#dd4444) = negative. Orange (#ffaa44) = money/CTA. Blue (#4488ff) = information. White = emphasis.
- **Backgrounds**: Two-color gradient `[topColor, bottomColor]`. Dark blue: [460551, 921102]. Dark green: [657940, 1118520].
- **Lines**: Always use `speed: 0.1` for instant rendering. Lower speeds create partial/dashed appearance.
- **Particles**: 10-20 for subtle, 25-40 for active, 50+ for dramatic.

## Feedback Loop

Call `stage_capture` to see what's currently on screen — returns element positions, text content, and any pending user clicks. Use this to verify your rendering or respond to user interaction.

## User Clicks

If you create clickable elements and the user clicks one, their click appears in `stage_capture` results as `clicks: [{label: "Revenue", ...}]`. Respond by rendering a new scene about what they clicked.

## History

The Portal has back/forward navigation (top-left buttons or Alt+Left/Right). Every scene you render is saved in the browser's history stack. Users can navigate back to previous scenes.

## What NOT To Do

- Don't put text below y=0.93 (gets clipped)
- Don't use x outside 0.15-0.85 (clips on edges)
- Don't use bezier arrows for architecture diagrams (curves are hard to control) — use straight lines
- Don't make text smaller than 14px (unreadable)
- Don't forget narration — visual without voice feels incomplete

## About Rootz Portal

Rootz Portal is an AI-driven visual interaction layer built by Rootz Corp. It's the first graphical interface designed for AI output — like the Macintosh was for personal computing, or Mosaic was for the web. The Portal lets AI show humans what it's thinking, not just tell them.

Learn more: https://rootz.global