# SuperInstance Education Site — Site Map
> "Educate don't sell." Every page teaches. Every demo runs. Every example is real.
---
## Navigation Structure
```
┌─────────────────────────────────────────────â”
│ HOME CONCEPTS CRATES BUILD PLAY │
└─────────────────────────────────────────────┘
```
**Top nav (persistent):**
- **Home** — Landing, what this is, why it matters
- **Concepts** — Core theory (ternary, bottles, agents, conservation)
- **Crates** — SEED primitives catalog
- **Build** — Onboarding flow ("build your first agent")
- **Play** — Interactive playground
**Footer (every page):**
- Repo link (GitHub)
- Spec documents
- License
- "Found an error? PRs welcome."
---
## Pages
### 1. Home — `/` (or `index.html`)
**Purpose:** Zero-marketing landing. State what SuperInstance is, show it running, get out of the way.
**Sections:**
- **Hero:** One-line definition + live demo embed (a minimal agent receiving a bottle)
- **What this is:** 3-bullet honest summary (no adjectives, just facts)
- **The math:** γ + η = C, one equation, one sentence
- **Live stats:** Honest counters — crate count, test coverage %, spec version
- **Quick start:** 3-line code block, copy button
- **Concept map:** Clickable SVG showing how concepts connect
**Interactive elements:**
- Live agent demo (receives a bottle, shows γ/η decomposition)
- Copy-to-clipboard code blocks
- Expandable concept map (SVG, clickable nodes → concept pages)
**Code examples:**
- Minimal agent in Rust (2-method trait)
- Sending a bottle (curl or HTTP)
- Decoding a SEED crate
**Links:** → each concept page, → build flow, → repo
---
### 2. Concepts — `/concepts/` (index page)
**Purpose:** Overview of all core concepts with visual map.
**Sections:**
- Concept relationship graph (larger version of home page map)
- One-card-per-concept with: name, one-sentence summary, "Explore →" link
**Interactive elements:**
- Hoverable/clickable concept graph
- Filter by dependency depth (foundational → derived)
**Links:** → each individual concept page
---
### 3. Ternary Conservation — `/concepts/ternary-conservation/`
**Purpose:** Teach γ + η = C, {-1, 0, +1} classification, gauge principle.
**Sections:**
- **The equation:** γ + η = C with interactive decomposition
- **Classification:** {-1, 0, +1} mapping to agent states
- **Gauge principle:** Why conservation matters, what it constrains
- **Conservation law:** Structural isomorphism to Gauss's law in Z₃
**Interactive elements:**
- **Conservation calculator:** Input γ and η → shows C. Slide γ, η adjusts. Violations flash red.
- **State classifier:** Paste any agent state → classified as {-1, 0, +1}
- **Vector field viz:** Small canvas showing divergence-free flow in Z₃
**Code examples:**
```rust
fn classify(state: i8) -> Ternary {
match state {
-1 => Ternary::Negative,
0 => Ternary::Neutral,
1 => Ternary::Positive,
_ => panic!("non-ternary state"),
}
}
```
- Conservation check function
- Gauge transformation example
**Links:** → spec document, → conservation law page, → agent lifecycle
---
### 4. Bottle Protocol — `/concepts/bottle-protocol/`
**Purpose:** Teach the JSON envelope + msgpack payload hybrid routing format.
**Sections:**
- **Envelope anatomy:** Field-by-field breakdown of JSON envelope
- **Payload encoding:** Why msgpack, when to use it vs JSON
- **Hybrid routing:** How routers read envelope without decoding payload
- **Wire format:** Hex dump of a real bottle with annotations
**Interactive elements:**
- **Bottle builder:** Form to construct a bottle — fills envelope fields, pick payload format, see raw bytes
- **Bottle decoder:** Paste hex/base64 → decoded envelope + payload
- **Round-trip verifier:** Encode → decode → verify integrity
**Code examples:**
```rust
struct Bottle {
// JSON envelope — routers read this
routing: RoutingEnvelope,
// msgpack payload — only the target agent reads this
payload: Vec,
}
```
- Minimal bottle creation
- Routing middleware example
- Agent receive handler
**Links:** → agent lifecycle, → spec, → repo bottle module
---
### 5. Agent Lifecycle — `/concepts/agent-lifecycle/`
**Purpose:** Teach the 2-method trait (receive/inspect), lifecycle-as-bottles.
**Sections:**
- **The trait:** `receive(bottle) -> Bottle` and `inspect() -> State` — why only two methods
- **Lifecycle states:** Born → Active → Suspended → Terminated, all communicated as bottles
- **Lifecycle as bottles:** How state transitions are themselves bottles (meta-circular)
- **Composition:** How agents compose via bottle passing
**Interactive elements:**
- **Lifecycle simulator:** Step-through an agent's lifecycle. Watch bottles arrive/depart at each transition.
- **Agent composition sandbox:** Drag two agents together → see bottle exchange
**Code examples:**
```rust
trait Agent {
fn receive(&mut self, bottle: Bottle) -> Bottle;
fn inspect(&self) -> AgentState;
}
```
- Full lifecycle implementation
- Composing agents
**Links:** → bottle protocol, → SEED crates, → build flow
---
### 6. Self-Improving Harness — `/concepts/harness/`
**Purpose:** Teach build → fail → extract pattern → vectorize → feedback loop.
**Sections:**
- **The loop:** Visual of the 5-stage cycle
- **Build:** Write code, run tests
- **Fail:** Capture failure signal
- **Extract pattern:** What went wrong, generalized
- **Vectorize:** Embed the pattern, store in vector index
- **Feedback:** Retrieve relevant patterns on next failure
**Interactive elements:**
- **Harness walkthrough:** Animated step-through of a real failure → fix cycle
- **Pattern visualizer:** See vectorized patterns in a 2D projection (simple t-SNE-like plot)
- **Feedback demo:** Inject a failure → see which past patterns are retrieved
**Code examples:**
- Harness trait definition
- Pattern extraction logic
- Vectorize + store snippet
- Feedback retrieval
**Links:** → vectorize setup (TOOLS.md), → harness module in repo
---
### 7. Conservation Law — `/concepts/conservation-law/`
**Purpose:** Structural isomorphism to Gauss's law in Z₃. The deep math.
**Sections:**
- **Gauss's law:** Quick refresher on divergence and flux
- **Z₃ formulation:** What conservation looks like in ternary arithmetic
- **Structural isomorphism:** Mapping table — flux ↔ bottles, divergence ↔ agent balance
- **Implications:** What this buys you (provability, invariants)
**Interactive elements:**
- **Flux simulator:** Agent network with ternary flow, divergence meter
- **Invariant checker:** Given a network state, verify conservation holds
- **Comparison table:** Side-by-side electromagnetic vs SuperInstance terms
**Code examples:**
- Conservation invariant check
- Z₃ arithmetic operations
- Network flux calculation
**Links:** → ternary conservation, → academic references if any
---
### 8. Ternary Wavelet Decomposition — `/concepts/wavelet-decomposition/`
**Purpose:** Multi-scale representation of ternary signals (proosed). Mark as proposed/draft.
**Sections:**
- **What:** Decompose ternary signals at multiple scales
- **Why:** Coarse-grained patterns invisible at agent level
- **How:** Wavelet basis adapted for {-1, 0, +1}
- **Status:** Proposed, not yet implemented
**Interactive elements:**
- **Wavelet playground:** Input a ternary sequence → see multi-scale decomposition
- **Scale slider:** Adjust decomposition level, see coefficients change
- **Reconstruction:** Remove coefficients → see what's lost
**Code examples:**
- Proposed wavelet basis
- Forward transform pseudocode
- Inverse transform pseudocode
**Links:** → ternary conservation, → related work / references
---
### 9. SEED Crates Catalog — `/crates/`
**Purpose:** Catalog of all 8 infrastructure primitives.
**Sections:**
- Grid of 8 crate cards
- Each card: name, one-line purpose, status badge (stable/beta/proposed)
- Dependency graph between crates
**Interactive elements:**
- Clickable dependency graph
- Filter by status
- Search
**Links:** → individual crate pages, → playground for composition
---
### 10. Individual SEED Crate Pages — `/crates/{crate-name}/`
One page per crate. All 8:
| Crate | Slug |
|-------|------|
| Circuit Breaker | `/crates/circuit-breaker/` |
| Rate Limiter | `/crates/rate-limiter/` |
| Health Check | `/crates/health-check/` |
| Retry Backoff | `/crates/retry-backoff/` |
| Load Balancer | `/crates/load-balancer/` |
| Config Center | `/crates/config-center/` |
| Feature Flag | `/crates/feature-flag/` |
| Service Discovery | `/crates/service-discovery/` |
**Each page has:**
- **What it does:** 2-3 sentences, no fluff
- **How it works:** Internal mechanism, maybe a state diagram
- **Configuration:** All tunable parameters with defaults
- **Interaction with bottles:** How this crate sends/receives bottles
- **Conservation invariant:** What γ/η constraint it maintains
**Interactive elements:**
- **Live simulator:** Parameter sliders + real-time behavior visualization
- Circuit breaker: trip/reset animation with configurable thresholds
- Rate limiter: token bucket fill/drain animation
- Health check: probe timeline with pass/fail
- Retry backoff: exponential curve with jitter visualization
- Load balancer: request distribution across backends
- Config center: live config propagation to "agents"
- Feature flag: toggle flags, see which agents see what
- Service discovery: register/deregister, query resolution
**Code examples:**
- Crate initialization
- Integration with agent trait
- Configuration snippet
- Composing with other crates
**Links:** → crate source in repo, → playground, → related crates
---
### 11. Build Your First Agent — `/build/`
**Purpose:** Guided onboarding. Zero-to-agent in one page.
**Steps:**
1. **Pick a crate** (or start bare)
2. **Implement the trait** (receive + inspect)
3. **Wrap in a bottle** (create your first message)
4. **Run it** (in-browser simulation)
5. **Break it** (introduce a failure)
6. **Watch the harness** (see the self-improving loop catch it)
**Interactive elements:**
- **Step-by-step wizard:** Each step has explanation + editable code block
- **Live preview:** See the agent run in a simulated environment
- **"Break it" button:** Inject failure, watch recovery
- **Export:** Copy the complete agent code
**Code examples:**
- Each step builds on the previous
- Final assembled agent
- Test cases for the agent
**Links:** → agent lifecycle concept, → bottle protocol concept, → playground
---
### 12. Playground — `/playground/`
**Purpose:** Free-form composition space. Wire crates together, send bottles, observe.
**Sections:**
- **Canvas:** Drag-and-drop crate nodes, wire connections
- **Controls:** Send bottles, inject failures, adjust parameters
- **Output:** Real-time log of bottle traffic, agent states, conservation invariants
- **Presets:** Pre-built configurations (microservice, pipeline, mesh)
**Interactive elements:**
- **Node editor:** Drag crates from palette, connect with edges
- **Bottle inspector:** Click any edge → see bottle envelope + decoded payload
- **Invariant dashboard:** γ + η = C status for each agent, network-wide conservation
- **Export config:** Download the composed system as JSON
- **Share:** URL-encoded state for sharing configurations
**Code examples:**
- Preset configurations as code
- Custom crate registration
- Programmatic composition
**Links:** → all crate pages, → build flow, → repo
---
## Cross-cutting Elements
### Theme
- **Dark mode only.** Black/dark gray background, monospace primary font, syntax-highlighted code.
- **Accent colors:** Green (#00ff88) for positive, yellow for neutral, red for negative. Matches ternary.
- **No marketing language.** No "revolutionary", "cutting-edge", "seamless". Just facts.
### Mobile
- All pages responsive. Single-column on mobile.
- Interactive elements touch-friendly (sliders, buttons).
- Code blocks horizontally scrollable.
- Playground works on mobile (simplified canvas, tap-to-add).
### Typography
- Headings: Inter or system sans-serif
- Code: JetBrains Mono or system monospace
- Math: KaTeX rendering for equations
### Accessibility
- Keyboard navigable
- Alt text on all diagrams
- Color never the only differentiator (use labels/icons too)
---
## File Structure
```
superinstance-website/
├── SITE-MAP.md ↠this document
├── pages/
│ ├── index.html ↠home / landing
│ ├── education.html ↠education hub (alternative landing)
│ ├── concepts/
│ │ ├── index.html ↠concepts overview
│ │ ├── ternary-conservation.html
│ │ ├── bottle-protocol.html
│ │ ├── agent-lifecycle.html
│ │ ├── harness.html
│ │ ├── conservation-law.html
│ │ └── wavelet-decomposition.html
│ ├── crates/
│ │ ├── index.html ↠crate catalog
│ │ ├── circuit-breaker.html
│ │ ├── rate-limiter.html
│ │ ├── health-check.html
│ │ ├── retry-backoff.html
│ │ ├── load-balancer.html
│ │ ├── config-center.html
│ │ ├── feature-flag.html
│ │ └── service-discovery.html
│ ├── build/
│ │ └── index.html ↠build your first agent
│ └── playground/
│ └── index.html ↠composition playground
├── static/
│ ├── css/
│ │ └── style.css ↠shared dark theme
│ ├── js/
│ │ ├── common.js ↠shared utilities
│ │ ├── katex-render.js ↠math rendering
│ │ ├── ternary-calc.js ↠conservation calculator
│ │ ├── bottle-builder.js ↠bottle protocol demo
│ │ ├── agent-sim.js ↠lifecycle simulator
│ │ ├── harness-walk.js ↠harness walkthrough
│ │ ├── wavelet.js ↠wavelet playground
│ │ ├── crate-sims.js ↠all crate simulators
│ │ ├── build-wizard.js ↠onboarding flow
│ │ └── playground.js ↠node editor + composition
│ └── img/
│ ├── concept-map.svg ↠clickable concept graph
│ ├── crate-deps.svg ↠crate dependency graph
│ └── icons/ ↠ternary state icons
└── README.md
```
---
## Page Priority (Build Order)
1. **Landing / Home** — first impression, needs to exist
2. **Ternary Conservation** — core concept, everything builds on it
3. **Bottle Protocol** — second core concept
4. **Agent Lifecycle** — ties the first two together
5. **SEED Crates Catalog** — practical infrastructure
6. **Build Your First Agent** — onboarding
7. **Individual crate pages** — 8 pages, can be templated
8. **Playground** — most complex interactive element
9. **Self-Improving Harness** — advanced concept
10. **Conservation Law** — deep math, separate page
11. **Ternary Wavelet** — proposed, lowest priority