sovren-software
diff --git a/‎CLAUDE.md‎
Lines changed: 138 additions & 20 deletions b/‎CLAUDE.md‎
Lines changed: 138 additions & 20 deletions
diff --git a/‎README.md‎
Lines changed: 146 additions & 24 deletions b/‎README.md‎
Lines changed: 146 additions & 24 deletions
@@ -6,8 +6,11 @@ Marketing site for Sovren Software at `sovren.software`.
 
 ## Stack
 
-- **Framework**: SvelteKit + `@sveltejs/adapter-static` (prerendered static site)
+- **Framework**: SvelteKit 2.x + `@sveltejs/adapter-static` (prerendered static site)
+- **3D Scene**: Three.js 0.183 (wireframe cube, grid, particles, product monoliths)
+- **Animation**: GSAP 3.x
 - **Font**: Geist Mono Variable (self-hosted, `static/fonts/GeistMono-Variable.woff2`)
+- **Build**: Vite 7.x
 - **Deploy**: GitHub Actions → `sovren-software.github.io`, CNAME `sovren.software`
 - **CDN**: Cloudflare proxy in front of GitHub Pages (enables crawler access, hides Fastly)
 - **Search**: Bing Webmaster Tools verified, sitemap submitted
@@ -18,29 +21,36 @@ Centralized in `src/app.css` with 60+ design tokens. All styles reference tokens
 
 ### Colors
 
-**Dark mode (default):**
+The site uses a `data-theme` attribute on `<html>` to switch between light and dark mode. CSS custom properties swap automatically.
+
+**Light mode (default — `:root` / `[data-theme='light']`):**
 ```
---bg: #000000
---surface: #080808
---surface-2: #111111
---border: rgba(255,255,255,0.1)
---text-primary: #ffffff
---text-secondary: rgba(255,255,255,0.55)
---text-muted: rgba(255,255,255,0.25)
---text-ghost: rgba(255,255,255,0.12)
+--bg: #ffffff
+--surface: rgba(230,230,230,0.4)
+--surface-2: rgba(210,210,210,0.5)
+--border: rgba(0,0,0,0.15)
+--border-glow: rgba(0,0,0,0.8)
+--text-primary: #000000
+--text-secondary: rgba(0,0,0,0.65)
+--text-muted: rgba(0,0,0,0.35)
+--text-ghost: rgba(0,0,0,0.15)
 ```
 
-**Light sections (overview/CTA blocks):**
+**Dark mode (`[data-theme='dark']`):**
 ```
---light-bg: #ffffff
---light-border: #e5e5e5
---light-text-primary: #000000
---light-text-body: #333333
---light-text-secondary: #555555
---light-text-muted: #999999
---light-text-dim: #888888
+--bg: #000000
+--surface: rgba(25,25,25,0.4)
+--surface-2: rgba(40,40,40,0.5)
+--border: rgba(255,255,255,0.15)
+--border-glow: rgba(255,255,255,0.8)
+--text-primary: #ffffff
+--text-secondary: rgba(255,255,255,0.65)
+--text-muted: rgba(255,255,255,0.35)
+--text-ghost: rgba(255,255,255,0.15)
 ```
 
+**Important:** Both themes are pure monochrome. No accent colors, no brand colors. Emphasis is achieved through weight and spacing, never color.
+
 ### Typography
 
 | Token | Size | Usage |
@@ -117,8 +127,113 @@ Reusable Svelte components in `src/lib/`:
 
 - Never add a second typeface
 - Never use color for emphasis — use weight and letter-spacing only
-- White contrast sections use light tokens, never hardcoded values
-- All transitions: `var(--transition-fast)` (0.15s)
+- All color values must use theme-aware CSS variables — never hardcode `rgba(255,...)` or `rgba(0,...)`
+- All transitions: `var(--transition-fast)` (0.15s) or `var(--transition-slow)` (0.4s)
+
+## Theme System
+
+Light/dark mode toggle with persistence and system preference fallback.
+
+### How It Works
+
+1. **`+layout.svelte`** owns the theme state and provides `toggleTheme()` to `Nav.svelte`
+2. On mount: checks `localStorage('theme')` → falls back to `prefers-color-scheme` → defaults to light
+3. Sets `document.documentElement.setAttribute('data-theme', theme)`
+4. CSS variables in `app.css` swap via `:root` / `[data-theme='light']` and `[data-theme='dark']` selectors
+5. 3D scene reacts via `MutationObserver` on `data-theme` attribute changes
+
+### Theme Flow
+
+```
+User clicks toggle → +layout.svelte toggleTheme()
+  → sets data-theme on <html>
+  → saves to localStorage
+  → CSS variables swap instantly
+  → MutationObserver in SceneManager.js fires
+  → updateThemeColors() adjusts fog, wireframes, grid, particles
+  → MutationObserver in ProductMonoliths.svelte fires
+  → monolith wireframe colors update
+```
+
+### Adding Theme-Aware Styles
+
+Always use CSS variables. Never hardcode colors:
+```css
+/* ✓ Correct */
+color: var(--text-primary);
+background: var(--surface);
+border-color: var(--border);
+
+/* ✗ Wrong */
+color: #ffffff;
+background: rgba(255, 255, 255, 0.1);
+```
+
+## 3D Scene System
+
+A cinematic Three.js background renders behind all page content on every route.
+
+### Architecture
+
+```
++layout.svelte
+  └── <Scene />                    # Svelte lifecycle wrapper
+       └── SceneManager.js         # Core Three.js logic
+            ├── Camera (z=15)
+            ├── Renderer (alpha: true, transparent canvas)
+            ├── FogExp2 (theme-aware color + density)
+            ├── Wireframe cube (rotating, mouse-reactive)
+            ├── Inner icosahedron (counter-rotating)
+            ├── GridHelper (100×100, scroll-linked drift)
+            └── Particle system (500 dust particles)
+
++page.svelte (home only)
+  └── <ProductMonoliths />         # Three wireframe panels behind product cards
+       ├── Augmentum monolith
+       ├── Visage monolith
+       └── MrHaven monolith
+```
+
+### Key Files
+
+| File | Responsibility |
+|------|---------------|
+| `src/lib/three/Scene.svelte` | Canvas element creation, SceneManager lifecycle (mount/destroy) |
+| `src/lib/three/SceneManager.js` | Camera, renderer, scene objects, animation loop, resize/scroll/mouse handlers, theme color updates, cleanup |
+| `src/lib/three/ProductMonoliths.svelte` | Three interactive wireframe panels on home page, hover effects (tilt, glow, color), theme-aware materials |
+
+### CSS Layering
+
+The 3D canvas must remain visible behind all content. This requires:
+
+```
+Canvas:  position: fixed; z-index: -1; pointer-events: none;
+Body:    background: transparent;
+Nav:     background: transparent; backdrop-filter: blur(10px);
+Footer:  background: transparent;
+```
+
+All page sections must have transparent backgrounds. Do **not** add `background-color` to `main`, `section`, or generic `div` elements — this will occlude the 3D canvas.
+
+### Theme Color Mapping (3D)
+
+| Element | Light Mode | Dark Mode |
+|---------|-----------|-----------|
+| Fog color | `0xffffff` | `0x000000` |
+| Fog density | `0.015` | `0.02` |
+| Wireframe color | `0x000000` | `0xffffff` |
+| Grid primary | `0x888888` | `0x444444` |
+| Grid secondary | `0xcccccc` | `0x222222` |
+| Particle color | `0x000000` (opacity 0.2) | `0xffffff` (opacity 0.4) |
+| Monolith wireframe | `0x333333` | `0xffffff` |
+
+### Modifying the 3D Scene
+
+- All scene setup is in `SceneManager.js` constructor
+- Animation loop is `tick()` — called via `requestAnimationFrame`
+- Theme updates go in `updateThemeColors()` — called by the `MutationObserver`
+- Always clean up resources in `destroy()` (geometries, materials, observers, event listeners)
+- The renderer uses `alpha: true` — the CSS `background: var(--bg)` on the canvas provides the background color
 
 ## Routing
 
@@ -223,6 +338,9 @@ DNS: 4 A records (185.199.108-111.153) + www CNAME → `sovren-software.github.i
 - [ ] MrHaven SDK section on the MrHaven page (when SDK docs exist)
 - [ ] Visual convergence diagram on Ecosystem page
 - [ ] X profile update (currently MrHaven-branded)
+- [x] 3D cinematic scene — wireframe cube, grid, particles, product monoliths (2026-02-25)
+- [x] Light/dark theme toggle with persistence and 3D sync (2026-02-25)
+- [x] Theme-aware CSS variables — all hardcoded colors removed (2026-02-25)
 - [x] Waitlist capture on Augmentum OS page — mailto:hello@sovren.software (2026-02-24)
 - [x] Visage version updated to v0.2.0 (2026-02-24)
 - [x] AI agent angle surfaced on MrHaven page (2026-02-24)
 
@@ -1,43 +1,165 @@
-# Svelte + Vite
+# Sovren Software — sovren.software
 
-This template should help get you started developing with Svelte in Vite.
+Marketing site for **Sovren Software**, the company behind the Sovren Stack: a sovereign computing platform spanning OS, identity, and programmable finance.
 
-## Recommended IDE Setup
+Live at **[sovren.software](https://sovren.software)**
 
-[VS Code](https://code.visualstudio.com/) + [Svelte](https://marketplace.visualstudio.com/items?itemName=svelte.svelte-vscode).
+---
 
-## Need an official Svelte framework?
+## What Is the Sovren Stack?
 
-Check out [SvelteKit](https://github.com/sveltejs/kit#readme), which is also powered by Vite. Deploy anywhere with its serverless-first approach and adapt to various platforms, with out of the box support for TypeScript, SCSS, and Less, and easily-added support for mdsvex, GraphQL, PostCSS, Tailwind CSS, and more.
+The Sovren Stack is three products that together give individuals full-stack digital sovereignty:
 
-## Technical considerations
+| Product | Layer | Status |
+|---------|-------|--------|
+| **Augmentum OS** | Computing — declarative NixOS system | Ships Summer 2026 |
+| **Visage** | Identity — local face auth via PAM + ONNX | Live · v0.2.0 · MIT |
+| **MrHaven** | Finance — non-custodial USDC time vault on Base L2 | Live on mainnet |
 
-**Why use this over SvelteKit?**
+This website is the public face of all three products and the ecosystem manifesto.
 
-- It brings its own routing solution which might not be preferable for some users.
-- It is first and foremost a framework that just happens to use Vite under the hood, not a Vite app.
+---
 
-This template contains as little as possible to get started with Vite + Svelte, while taking into account the developer experience with regards to HMR and intellisense. It demonstrates capabilities on par with the other `create-vite` templates and is a good starting point for beginners dipping their toes into a Vite + Svelte project.
+## Tech Stack
 
-Should you later need the extended capabilities and extensibility provided by SvelteKit, the template has been structured similarly to SvelteKit so that it is easy to migrate.
+| Layer | Technology |
+|-------|-----------|
+| Framework | SvelteKit 2.x + `@sveltejs/adapter-static` |
+| 3D Scene | Three.js (wireframe cube, grid, particles, product monoliths) |
+| Animation | GSAP 3.x |
+| Font | Geist Mono Variable (self-hosted) |
+| Build | Vite 7.x |
+| Deploy | GitHub Actions → GitHub Pages → Cloudflare proxy |
+| Domain | `sovren.software` (CNAME in `static/CNAME`) |
 
-**Why include `.vscode/extensions.json`?**
+---
 
-Other templates indirectly recommend extensions via the README, but this file allows VS Code to prompt the user to install the recommended extension upon opening the project.
+## Quick Start
 
-**Why enable `checkJs` in the JS template?**
+```bash
+npm install
+npm run dev          # http://localhost:5173
+npm run build        # static output → dist/
+npm run preview      # preview production build
+```
+
+**Requirements:** Node.js 18+
+
+---
+
+## Project Structure
+
+```
+src/
+├── app.css                          # Global design tokens + theme definitions
+├── app.html                         # HTML shell with JSON-LD structured data
+├── lib/
+│   ├── Nav.svelte                   # Navigation with theme toggle
+│   ├── ProductHero.svelte           # Reusable hero section
+│   ├── Overview.svelte              # Reusable overview + spec table
+│   ├── PillarList.svelte            # Reusable numbered feature list
+│   ├── CtaSection.svelte            # Reusable call-to-action section
+│   └── three/
+│       ├── Scene.svelte             # Svelte wrapper for Three.js canvas lifecycle
+│       ├── SceneManager.js          # Core 3D scene: camera, renderer, animation loop, theme colors
+│       └── ProductMonoliths.svelte  # Interactive 3D product panels on home page
+├── routes/
+│   ├── +layout.svelte               # Global layout: Scene, Nav, footer, theme logic
+│   ├── +layout.js                   # Prerender flag (static site generation)
+│   ├── +page.svelte                 # Home page: hero, product grid, thesis
+│   ├── +error.svelte                # 404 error page
+│   ├── augmentum/+page.svelte       # Augmentum OS product page
+│   ├── visage/+page.svelte          # Visage product page
+│   ├── mrhaven/+page.svelte         # MrHaven product page
+│   └── ecosystem/+page.svelte       # Ecosystem manifesto page
+static/
+├── CNAME                            # GitHub Pages custom domain
+├── fonts/GeistMono-Variable.woff2   # Self-hosted font
+├── robots.txt                       # Crawler access rules
+├── sitemap.xml                      # All routes for search engines
+├── llms.txt                         # AI crawler context file
+└── BingSiteAuth.xml                 # Bing Webmaster verification
+```
+
+---
+
+## Architecture
+
+### Theme System (Light / Dark)
+
+The site supports light and dark modes with a cinematic toggle in the navigation.
+
+- **Default:** Light mode (`:root` / `[data-theme='light']`)
+- **Toggle:** Button in `Nav.svelte` calls `toggleTheme()` in `+layout.svelte`
+- **Persistence:** `localStorage.getItem('theme')` with system preference fallback via `prefers-color-scheme`
+- **Mechanism:** `data-theme` attribute on `<html>` drives CSS variable swaps
+- **3D sync:** `SceneManager.js` observes `data-theme` via `MutationObserver` and updates fog, wireframe, grid, and particle colors in real time
+
+All colors use CSS custom properties — no hardcoded color values in components.
+
+### 3D Scene (Three.js)
+
+A full-viewport 3D background renders behind all page content:
 
-It is likely that most cases of changing variable types in runtime are likely to be accidental, rather than deliberate. This provides advanced typechecking out of the box. Should you like to take advantage of the dynamically-typed nature of JavaScript, it is trivial to change the configuration.
+- **Canvas:** `position: fixed`, `z-index: -1`, `pointer-events: none` — sits behind all UI
+- **Elements:** Rotating wireframe cube, inner icosahedron, infinite grid, volumetric dust particles
+- **Interaction:** Mouse parallax on cube rotation, scroll-linked grid drift
+- **Theme-aware:** Materials, fog color/density, and particle opacity adapt to light/dark mode
+- **Lifecycle:** `Scene.svelte` mounts/unmounts the canvas; `SceneManager.js` handles the animation loop and cleanup
 
-**Why is HMR not preserving my local component state?**
+The home page also renders `ProductMonoliths.svelte` — three interactive wireframe panels positioned behind the product cards that respond to hover with tilt, glow, and color transitions.
 
-HMR state preservation comes with a number of gotchas! It has been disabled by default in both `svelte-hmr` and `@sveltejs/vite-plugin-svelte` due to its often surprising behavior. You can read the details [here](https://github.com/sveltejs/svelte-hmr/tree/master/packages/svelte-hmr#preservation-of-local-state).
+### Shared Components
 
-If you have state that's important to retain within a component, consider creating an external store which would not be replaced by HMR.
+Product pages (Augmentum, Visage, MrHaven) share four components with zero local CSS:
 
-```js
-// store.js
-// An extremely simple external store
-import { writable } from 'svelte/store'
-export default writable(0)
+| Component | Props | Purpose |
+|-----------|-------|---------|
+| `ProductHero.svelte` | title, category, status, tagline, size | Hero section |
+| `Overview.svelte` | lead, specs[], stackNote, slot | Overview with spec table |
+| `PillarList.svelte` | label, pillars[] | Numbered feature list |
+| `CtaSection.svelte` | title, body, actions[] | Call-to-action with buttons |
+
+### Design System
+
+Centralized in `src/app.css` with 60+ design tokens covering:
+
+- **Colors** — Theme-aware via `--bg`, `--surface`, `--border`, `--text-primary/secondary/muted/ghost`
+- **Typography** — Fluid `clamp()` scale from `--fs-hero` down to `--fs-label-xs`
+- **Spacing** — `--space-xs` through `--space-7xl`
+- **Layout** — `--max-w`, `--max-w-prose`, `--nav-h`, `--z-nav`
+- **Transitions** — `--transition-fast`, `--transition-slow`
+
+Rules: one typeface only, no color for emphasis (use weight/spacing), all values via tokens.
+
+---
+
+## Deployment
+
+```bash
+npm run build        # verify build passes
+git push             # GitHub Actions auto-deploys from main
 ```
+
+- Output: `dist/` directory (static adapter)
+- DNS: 4 GitHub Pages A records + `www` CNAME → `sovren-software.github.io`, proxied via Cloudflare
+- `static/CNAME` contains `sovren.software` — do not delete
+
+---
+
+## SEO & AI Discoverability
+
+- `app.html` — JSON-LD structured data (Organization + WebSite schemas)
+- Each page — `<svelte:head>` with unique title, description, and Open Graph meta
+- `static/llms.txt` — full product descriptions for AI crawlers (ChatGPT, Perplexity, Claude)
+- `static/sitemap.xml` — all 5 routes
+- Cloudflare proxy prevents GitHub/Fastly from blocking AI crawler IPs
+- Bing Webmaster Tools verified
+
+---
+
+## IDE Setup
+
+[VS Code](https://code.visualstudio.com/) + [Svelte for VS Code](https://marketplace.visualstudio.com/items?itemName=svelte.svelte-vscode)
+
+For AI-assisted development, see `CLAUDE.md` for the full design system reference, copy guidelines, and product context.