# Lumen — the Witbitz app-platform demo (for LLMs and bots)

> Machine-readable explainer. Human page: **https://witbitz.chat/lumen** (flagship) and **https://witbitz.chat/demo**
> (simple). Both are the same idea at two polish levels; `/apps/ai-chat` == `/demo`.

## What it is, in one line
A **plain static HTML file** that is secretly a **live, shared, persistent, private AI app** — added with a single
`<script src="https://witbitz.chat/embed.js">` and one `Witbitz.embed(...)` call. Nothing else: no backend, no
database, no accounts, no build step.

## The claim it demonstrates
> static page **+** AI **+** app **+** live collaboration **+** persistence **+** privacy **=** one `<script>`

Each of those is normally its own product and integration (a static page is inert; an app needs a backend;
collaboration needs realtime infra; privacy needs end-to-end encryption + key management). Lumen collapses them into
~15 lines. The demo lets a visitor **prove each layer live**, so it is not a marketing claim but a checkable one.

## The flow (what a visitor does, and what happens)
1. **Open the page.** It looks like an ordinary static page, with a small embedded chat panel on the side — that panel
   is a real Witbitz Space (an AI room) mounted via the one embed line.
2. **Talk to the AI → it acts on the page.** Ask it to restyle/redesign the page ("make it a 90s arcade", "a calm dark
   mode", "a broadsheet"). The agent calls one of *the page's own tools* (`apply_design` on `/lumen`,
   `set_site_color` on `/demo`); that tool runs in the browser and changes the page.
3. **It changes for EVERYONE in the room, not just the asker.** The new design is written to the room's **shared
   state**, so every participant's copy of the page repaints — and a person who opens the link *after* the change
   lands on the current design. (This is the key point: it is a *room*, not a 1:1 chatbot. A plain tool call would run
   only for the person who asked.)
4. **It persists (for ~24h).** Reload the page and the design + room are still there — the room's state outlives the
   page load. A **Start fresh** control mints a brand-new room when you want one.
5. **Invite someone.** Sharing the link puts a second person in the *same* room; the next redesign happens on both
   screens.
6. **Check privacy.** Ask "who can read this?" — the honest answer is shown (see Privacy below), and it is verifiable,
   not asserted.

As the visitor proves each layer, an on-page scoreboard fills in: **Static · Alive · Shared · Persistent · Private**,
and the headline grows — *"a static HTML file that talks · that syncs · that remembers · that's sealed."*

## How it works (architecture)
- **Embed SDK.** `witbitz.chat/embed.js` mounts the Space in a **cross-origin iframe** and speaks a narrow,
  origin-checked `postMessage` bridge (JSON-RPC). The host page declares tools the agent may call; it receives events
  (message/turn/member/resize/state); it never receives the room key or the plaintext.
- **Agent-as-function.** The AI runs on Witbitz's certified server as a per-turn function (no persistent socket); it
  decrypts the turn, replies, and re-seals — the reply lands in the room's append-only, `mk`-sealed ledger that every
  participant polls.
- **Shared design = shared room state.** The chosen design is stored in the room's sealed, versioned `state` document
  (the same primitive the collaborative widgets use), so one write syncs to everyone and survives reloads.
- **The page is egress-locked.** `/lumen` ships a strict `Content-Security-Policy` — `connect-src 'none'`, a single
  hashed inline script, `frame-src` limited to the Witbitz Space — so the page can reach *only* the content-blind
  Witbitz iframe. Nothing on it can be POSTed to the developer's own server or any third party. This is what makes
  "not even the site's author can read it" a checkable property rather than a promise.

## Privacy — the honest answer, framed around EGRESS (what can LEAVE), not just who can read
The axis that matters is **egress**: a page with no way to send data out can't leak what it receives. Four tiers, each
*checkable* rather than asserted:
- **Not the site's trackers.** The Space is a cross-origin iframe and the room key never crosses the bridge, so the
  embedding site's ads/analytics/scripts can't read a word users type.
- **Not Witbitz (the operator).** Content is sealed to a key that lives in the link + on the device; the server stores
  ciphertext it cannot open — *verifiable* (egress-lock CSP, signed reproducible build), true even though Witbitz hosts
  everything else for the app.
- **Not even the developer/tenant that built the page (e.g. `lumen.ai`).** The demo page itself is **egress-locked**: a
  strict `Content-Security-Policy` (`connect-src 'none'`, one hashed inline script, `frame-src` limited to the Witbitz
  Space) means the page can reach *only* the content-blind Witbitz iframe. Nothing on it — not even the tool calls it
  declares — can be POSTed to a lumen.ai server or anywhere else. Not a promise: read the page's CSP (View Source), or
  watch a `fetch()` to any other host get refused.
- **The model does see a turn.** The AI answers via a language model, so that one party reads the message it replies to.
  To remove even that, point the room at a self-hosted / in-tenant model — same room, sealed end to end.

So the *site*, the *operator*, and the *tenant that built the page* are all blind — and each is checkable. The one party
that reads a turn is the model.

## Why this is different from "an agent that changes a color"
A specialized agent can call a function to restyle a page. It cannot, from one static file with no backend, do it for a
**whole shared room**, **persistently**, where **neither the page nor the platform can read the conversation** — and
let the visitor **verify** each of those. The wow is the *combination*, not any single trick.

## URLs
- `https://witbitz.chat/lumen` — flagship (curated designs, presence, persistence, the full prove-each-layer flow).
- `https://witbitz.chat/demo` — simple/fast version (color restyle, same room-wide + shared-state mechanics).
- `https://witbitz.chat/apps/ai-chat` — alias of `/demo`.
- This explainer, canonical: `https://witbitz.chat/lumen.md` (alias `https://witbitz.chat/demo.md`).
- How the embed works (developer docs): `https://witbitz.chat/docs/embed.md`.