# WebGPU OS Documentation > Unified documentation for the WebGPU OS stack — a GPU-first, browser-resident operating system composed of five reusable subsystems: the engine (WebGPU runtime + ECS), the editor (scene/asset IDE), Plauna (hybrid DOM/GPU UI framework), AGI (reinforcement-learning rig + WebGPU tensors), and webgpu-os (kernel + shell + packages + apps). This MD/ folder is the single source of truth; the same Markdown is served by a zero-build HTML viewer, a MkDocs Material site, and a `docs` app inside the OS. Discovery status: `llms.txt` is a supplemental, emerging convention. The canonical evidence remains the linked Markdown, generated API catalogs, and repository source. Source of truth: the `MD/` folder. Generated API reference lives under `/reference/**` (produced by `tools/extract_api.py`). Agents: read `AGENTS.md` before editing — it defines boundaries (e.g. never edit generated content above the `` marker). Naming note: older material may call the project "Particle Engine"; the current umbrella is the WebGPU OS stack. Machine API catalog: `api-index.json` lists source paths, browser import specifiers, source hashes, detected exports, signatures, and summaries. Its import paths target source mode served from the repository root; the compact production site loads compiled bundles and may not expose raw modules. Streaming discovery: `docs-chunks.jsonl` provides bounded documentation chunks and `api-symbols.jsonl` provides one module or exported symbol per line for incremental indexing without loading the full catalogs. Platform downloads: https://github.com/BTSpaniel/particlerealms.engine publishes browser-ready distribution artifacts, including compressed `.gz` bundles; it is not the source tree used to generate the API catalog. Optional master server source: https://github.com/BTSpaniel/particlerealms.engine-master-server implements the separate discovery, admission, encrypted-signaling, TURN, and trusted-node service. It is never gameplay authority. ## Machine-readable indexes - [Documentation chunks](docs-chunks.jsonl): Bounded, source-labelled records for incremental retrieval and embedding. - [API modules and symbols](api-symbols.jsonl): One source-backed module or detected export per line. - [Combined API catalog](api-index.json): Complete module records with source hashes, imports, signatures, and summary coverage. - [XML sitemap](sitemap.xml): Canonical public routes for crawlers. ## Getting Started - [Overview](https://particlerealms.online/MD/getting-started/overview.md): This page explains what the stack is, who each part is for, and where to go next. Read it first if you are new to the project. - [Install & Run](https://particlerealms.online/MD/getting-started/install.md): This page covers prerequisites and how to serve the stack and these docs locally. Everything runs in the browser — there is no compile step. - [Quickstart](https://particlerealms.online/MD/getting-started/quickstart.md): This guide boots the WebGPU OS and opens an app. It assumes you have completed Install & Run. - [Glossary](https://particlerealms.online/MD/getting-started/glossary.md): Terms used throughout this documentation. Each term is defined once here and linked from the pages that use it. - [FAQ & Troubleshooting](https://particlerealms.online/MD/getting-started/faq.md): Common questions and fixes. If something here is wrong or missing, follow the Contribution Workflow to update it. ## Guides (How-To) - [Capabilities — What You Can Build](https://particlerealms.online/MD/guides/capabilities.md): What the stack can actually build: browser-native WebGPU games, simulation sandboxes, tools, editors, UI systems, AI training experiments, and deployable single-file runtimes. Use this page to pick… - [Engine Stack Usage](https://particlerealms.online/MD/guides/engine-stack-usage.md): Version targets: Engine 0.8.1-alpha, Editor 0.6.0-alpha, Plauna 0.2.0-alpha, AGI Core 0.1.0-alpha. ## Concepts (Whole Stack) - [Architecture Overview](https://particlerealms.online/MD/concepts/architecture-overview.md): This page is the big picture: how the engine, editor, Plauna, AGI, and the WebGPU OS compose into one system. Read it before diving into any single subsystem. - [History & Evolution](https://particlerealms.online/MD/concepts/history-evolution.md): This is the canonical story of how the stack grew. Understanding the order in which the layers appeared explains why the boundaries sit where they do — and why webgpu-os/ is glue rather than a… - [Boot Sequence](https://particlerealms.online/MD/concepts/boot-sequence.md): How the WebGPU OS comes up, from the HTML page to a mounted desktop. This reflects webgpu-os/boot.js and the bootWebGpuOS() function in webgpu-os/index.js. - [GPU Device Sharing](https://particlerealms.online/MD/concepts/gpu-device-sharing.md): The whole OS runs against a single WebGPU device shared by the shell and every app. This page explains the model and where it lives. It expands the notes in webgpu-os/docs/ARCHITECTURE.md. - [Security & Trust Model](https://particlerealms.online/MD/concepts/security-model.md): How the OS contains code it runs. Apps and mods are capability-gated and packages carry a trust verdict; the two combine so that untrusted code is contained even if it declares broad permissions.… - [Data Flow](https://particlerealms.online/MD/concepts/data-flow.md): How state moves through the stack: ECS state, persistence, the virtual filesystem, inter-app messaging, and optional multi-user sync. This page orients you before the per-subsystem references. - [Schema Evolution & Expand-Contract](https://particlerealms.online/MD/concepts/schema-evolution.md): Particle Realms treats every durable or independently deployed data boundary as a versioned contract. This includes SQLite tables, JSON files, browser storage, OPFS trees, binary saves, network… - [Particle State Channels](https://particlerealms.online/MD/concepts/state-channels.md): Particle State Channels define where shared state lives and how views receive it. This guide is for app, game, and UI authors who need one authoritative state path across Plauna, ECS, WebGPU OS… ## Engine - [Overview](https://particlerealms.online/MD/engine/overview.md): The engine (engine/) is the foundation of the whole stack: a pure-browser, GPU-first runtime providing the WebGPU device, frame graph, ECS, rendering, simulation, networking, and audio that every… - [Architecture](https://particlerealms.online/MD/engine/architecture.md): How the engine's modules compose. The engine is organized as independent subsystems that communicate through the ECS and an event bus, all running on a single shared WebGPU device. - [Getting Started](https://particlerealms.online/MD/engine/getting-started.md): Bring the engine up in a browser and understand the bootstrap entry points. Assumes Install & Run is done. - [Virtual GPU (vGPU)](https://particlerealms.online/MD/engine/vgpu.md): VirtualGPU is the unified GPU abstraction layer that powers every system in the engine. It wraps raw WebGPU with automatic caching, pooling, and resource management — turning ~20 lines of boilerplate… - [ECS v2](https://particlerealms.online/MD/engine/ecs.md): Entity-Component-System architecture: entities are IDs, components are data, systems are functions. No inheritance and no scene graph — just fast, flat, data-oriented design. - [Rendering](https://particlerealms.online/MD/engine/rendering.md): GPU-driven rendering with meshes, lights, materials, shader modes, and multi-pass compositing. All rendering is built on the Virtual GPU (vGPU) abstraction. - [MorphField R2](https://particlerealms.online/MD/engine/morphfield.md): MorphField is an additive, opt-in Engine renderer for semantic fields, sparse residuals, oriented kernels, and validated surface caches. A public Nexel describes scene intent. The compiler produces… - [Shaders & WGSL](https://particlerealms.online/MD/engine/shaders.md): A modular WGSL shader system with composition, preprocessing, a shared library of reusable modules, and the ShaderComposer for assembling complex shaders from parts. - [Particle System](https://particlerealms.online/MD/engine/particles.md): The engine's flagship subsystem: large-scale GPU particles with physics, thermal simulation, chemistry, SPH fluids, SDF collision, flocking, and volumetric rendering. Everything runs on compute… - [Galaxy Mythic Spiral Atlas](https://particlerealms.online/MD/engine/galaxy-mythic-spiral-atlas.md): Galaxy Mythic Spiral Atlas is an adaptive GPU orbital-tracer demo in the Playground. It combines observed spiral-galaxy structure with five deliberately enhanced fantasy studies. This page is for… - [Curl Noise Flow Atlas](https://particlerealms.online/MD/engine/curl-noise-flow-atlas.md): Curl Noise Flow Atlas is an adaptive GPU tracer demo in the Playground. It combines a shared periodic curl field with Particle Storm's high-count compute-density architecture and five authored flow… - [Kuramoto Resonance Field](https://particlerealms.online/MD/engine/kuramoto-resonance-field.md): The Kuramoto Resonance Field demos turn collective phase synchronization into a large, interactive HDR sculpture. The CPU and GPU versions share the same five studies and renderer, but they integrate… - [Particle Long-Range Solvers](https://particlerealms.online/MD/engine/particle-long-range.md): The particle simulation has four mutually exclusive long-range force backends. Use FMM for a large open domain, PME for a periodic domain, direct summation as the small-system accuracy oracle, and… - [Physics & Simulation](https://particlerealms.online/MD/engine/physics.md): GPU-accelerated cloth, rope, fluid volumes, and rigid-body physics. All solvers run on compute shaders via vGPU. - [GPU Physics Engine](https://particlerealms.online/MD/engine/gpu-physics.md): A WebGPU compute-based physics engine with full PhysX 5.4.1 feature parity: 15 modules in engine/sim/physics/gpu/ (~400 KB total), all shaders in WGSL. It is a parallel implementation — no PhysX code… - [Math Library](https://particlerealms.online/MD/engine/math.md): 350+ pure functions for vectors, matrices, quaternions, geometric primitives, GPU data packing, and interpolation. All exported via EngineBootstrap.js and MathImports.js. - [Math Contract](https://particlerealms.online/MD/engine/math-contract.md): This page defines the rules new engine, editor, Plauna, AGI, and WebGPU OS code must follow when it uses shared math. It locks the current runtime behavior before MathEngine grows beyond the existing… - [Audio](https://particlerealms.online/MD/engine/audio.md): A fully procedural audio engine with node-graph synthesis, material-to-sound mapping, spatial audio, and real-time particle-driven sound generation — no pre-recorded samples required. - [Index](https://particlerealms.online/MD/engine/index.md): The WebGPU runtime foundation of the stack. Source: engine/. - [Engine API Reference (1756 pages)](https://particlerealms.online/MD/engine/reference/_index.json): Machine-readable index of the generated per-symbol API reference. ## Editor - [Overview](https://particlerealms.online/MD/editor/overview.md): The editor (editor/) is the scene and asset authoring IDE built on the engine. It was the first major application on top of the runtime and established the panel/workbench and project-filesystem… - [Architecture](https://particlerealms.online/MD/editor/architecture.md): How the editor is organized. The editor is a single-page application whose EditorApp orchestrates the viewport, panels, and project state on top of the engine. - [Getting Started](https://particlerealms.online/MD/editor/getting-started.md): Open the editor and learn where things live. Assumes Install & Run is done. - [Index](https://particlerealms.online/MD/editor/index.md): Scene and asset authoring IDE built on the engine. Source: editor/. - [Editor API Reference (155 pages)](https://particlerealms.online/MD/editor/reference/_index.json): Machine-readable index of the generated per-symbol API reference. ## Plauna (UI Framework) - [Overview](https://particlerealms.online/MD/plauna/overview.md): Plauna (plauna/) is a browser-first hybrid DOM/GPU UI framework and workbench. It extends the engine with advanced UI: DOM-free text measurement, GPU surfaces, a dockable workspace, and ECS-driven UI… - [Architecture](https://particlerealms.online/MD/plauna/architecture.md): How Plauna renders and manages UI. State lives in a UI ECS world; a visual tree is reconciled to DOM and/or GPU surfaces through a dirty-tracking pipeline. - [Getting Started](https://particlerealms.online/MD/plauna/getting-started.md): Initialize Plauna and create UI. This mirrors the examples in plauna/README.md. Assumes Install & Run is done. - [Index](https://particlerealms.online/MD/plauna/index.md): Hybrid DOM/GPU UI framework and workbench. Source: plauna/. - [Plauna (UI Framework) API Reference (125 pages)](https://particlerealms.online/MD/plauna/reference/_index.json): Machine-readable index of the generated per-symbol API reference. ## AGI (AI / Rigging) - [Overview](https://particlerealms.online/MD/agi/overview.md): AGI (agi/) is a reinforcement-learning animation rigging system: a "Doc Octavius"-style mechanical parasite rig that injects into a humanoid ragdoll and learns to control it through RL. It ships its… - [Architecture](https://particlerealms.online/MD/agi/architecture.md): How AGI is layered: a WebGPU tensor library at the bottom, neural networks above it, an RL control loop on top, and the rig visuals + Studio around it. - [Getting Started](https://particlerealms.online/MD/agi/getting-started.md): Launch AGI Studio and start a training run. Based on agi/README.md. Assumes Install & Run is done. - [Training Guide](https://particlerealms.online/MD/agi/training-guide.md): How to train the parasite rig from standing to full locomotion, and how to fix common problems. Condensed from agi/README.md and agi/TRAININGGUIDE.md. - [Index](https://particlerealms.online/MD/agi/index.md): Reinforcement-learning animation rigging ("parasite rig") with a WebGPU tensor library and AGI Studio. Source: agi/. - [AGI (AI / Rigging) API Reference (245 pages)](https://particlerealms.online/MD/agi/reference/_index.json): Machine-readable index of the generated per-symbol API reference. ## WebGPU OS - [Overview](https://particlerealms.online/MD/webgpu-os/overview.md): WebGPU OS (webgpu-os/) is the composition layer that turns the engine, Plauna, AGI, and editor into a GPU-first, desktop-like OS that boots in a single browser tab. It provides a kernel, a shell, a… - [Architecture](https://particlerealms.online/MD/webgpu-os/architecture.md): The kernel, shell, package system, storage, and drivers — and how an app moves from a folder or .prpkg to a running, capability-gated panel. - [Realm Network](https://particlerealms.online/MD/webgpu-os/realm-network.md): The Realm Network adds portable identity, immutable content, resumable links, semantic replication, offline branches, governance, bounded task exchange, and safe Realm discovery to the WebGPU OS. It… - [Navi Architecture and Delivery](https://particlerealms.online/MD/webgpu-os/navi-architecture-and-delivery.md): This page defines the target Navi architecture and the gated delivery plan for engineers working on WebGPU OS and AI Echo. It is a design contract. A checked design item means its decision is frozen.… - [AI Echo Live Patch](https://particlerealms.online/MD/webgpu-os/ai-echo-live-patch.md): AI Echo Live Patch lets the resident Navi inspect and update a mounted interface without rebuilding the OS. It edits registered WebGPU OS app surfaces, selected shell surfaces, AI Echo itself, and… - [AI Echo Artifact Studio](https://particlerealms.online/MD/webgpu-os/ai-echo-artifact-studio.md): AI Echo can turn substantial responses into durable work products that open beside the conversation. Documents, code, data, tables, charts, declarative interfaces, and static web presentations remain… - [AI Echo Clicks and Clankers](https://particlerealms.online/MD/webgpu-os/ai-echo-clicks-and-clankers.md): AI Echo supports a hybrid browser workflow. A person can keep using the visible page, while the Navi can discover typed page actions or perform bounded semantic controls through the WebGPU OS browser… - [AppForge Contracts](https://particlerealms.online/MD/webgpu-os/appforge-contracts.md): AppForge is the deterministic assembly layer inside WebGPU OS. It does not replace the kernel, shell, package manager, permission model, or current apps. It registers reusable parts, scores them with… - [Getting Started](https://particlerealms.online/MD/webgpu-os/getting-started.md): Boot the OS and build a minimal app. Assumes Install & Run is done. - [App Catalog](https://particlerealms.online/MD/webgpu-os/app-catalog.md): Every app shipped in the OS, grouped by purpose. The authoritative registry is webgpu-os/apps/index.json; each app's manifest (apps//manifest.json) declares its entry, surface, permissions, and… - [Modular Pinball Parts](https://particlerealms.online/MD/webgpu-os/pinball-parts.md): The pinball parts system turns each physical mechanism into a reusable, immutable part definition. This guide is for engine contributors who build parts and table authors who assemble those parts… - [Smith Lab](https://particlerealms.online/MD/webgpu-os/smith-lab.md): Smith Lab is the os.smith-lab RF learning and design application. It combines an accessible Smith Chart academy, deterministic matching-network synthesis, bounded Touchstone import, and synchronized… - [Particle Realms Studio](https://particlerealms.online/MD/webgpu-os/particle-realms-studio.md): Particle Realms Studio is the WebGPU OS runtime for running, tuning, validating, and inspecting recipe-built particle simulations. The portable project and typed recipe formats are shared authoring… - [Particle Studio User Guide](https://particlerealms.online/MD/webgpu-os/particle-studio-user-guide.md): Particle Realms Studio is the Particle Sandbox application inside WebGPU OS. It provides six workspaces for selecting, running, safely tuning, inspecting, and comparing particle projects. Full brush… - [Particle Studio Architecture](https://particlerealms.online/MD/webgpu-os/particle-studio-architecture.md): Particle Realms Studio is a WebGPU OS application, not a separate native desktop editor. ParticleApp owns its lifecycle and composes the Studio shell, versioned project, GPU runtime, evidence stores,… - [Particle Studio Integration Map](https://particlerealms.online/MD/webgpu-os/particle-studio-integration-map.md): This map shows the active Particle Realms Studio paths and the boundaries that remain host or engine integration work. It distinguishes direct GPU state, bounded readback, measured evidence, authored… - [Particle Recipe Schema](https://particlerealms.online/MD/webgpu-os/particle-recipe-schema.md): Particle recipes use the strict JSON schema particle-realms.simulation-recipe.graph version 1. The graph is an authored, typed description. Compilation produces a deterministic… - [Particle Studio Preset Authoring](https://particlerealms.online/MD/webgpu-os/particle-studio-preset-authoring.md): Particle Realms presets are curated source records in ParticleLabCatalog.js. The catalog currently contains 40 immutable built-in presets. It is not a user-installable preset marketplace, and… - [Particle Studio Fidelity and Validation](https://particlerealms.online/MD/webgpu-os/particle-studio-fidelity-and-validation.md): Particle Realms Studio separates an attractive interactive result from a validated result. A functioning GPU path, deterministic seed, high particle count, smooth frame rate, or imported reference… - [Particle Studio Telemetry](https://particlerealms.online/MD/webgpu-os/particle-studio-telemetry.md): Particle Realms Studio accepts measured values; it does not generate missing measurements. Runtime metrics, sensor evidence, and external references use separate contracts so derived values cannot… - [Particle Studio External Studies](https://particlerealms.online/MD/webgpu-os/particle-studio-external-studies.md): Particle Studio can retain and compare bounded local scalar-series studies in CSV or JSON. An external study is reference evidence with its own provenance; it never automatically validates the active… - [Particle Studio Performance](https://particlerealms.online/MD/webgpu-os/particle-studio-performance.md): Particle Realms Studio chooses a runtime from granted browser and device capabilities. Particle count alone is not a performance guarantee, and no single frame-rate claim applies across modes, GPUs,… - [Particle Studio Test Plan](https://particlerealms.online/MD/webgpu-os/particle-studio-test-plan.md): This plan verifies current repository behavior and records gaps against the broader Simulation Studio design pack. Passing structural and runtime tests does not establish scientific validity or… - [Index](https://particlerealms.online/MD/webgpu-os/index.md): GPU-first compositor, shell, kernel, and package system that boots in a browser tab. Source: webgpu-os/. - [WebGPU OS API Reference (322 pages)](https://particlerealms.online/MD/webgpu-os/reference/_index.json): Machine-readable index of the generated per-symbol API reference. ## API - [API Reference](https://particlerealms.online/MD/api/index.md): The stack's API is documented in two complementary forms: ## About - [Author & Credits](https://particlerealms.online/MD/about/credits.md): The entire WebGPU OS stack — the engine, the editor, Plauna, AGI, and the WebGPU OS that composes them — was designed and built by Jake Wehmeier. ## Optional Secondary material — safe to skip when a shorter context is needed. - [Docs Style Guide](https://particlerealms.online/MD/contributing/docs-style-guide.md): How to write docs for this project so they are clear, consistent, accessible, and easy for both AI tools and humans to read. - [Writing Checklist](https://particlerealms.online/MD/contributing/writing-checklist.md): Run through this before merging any documentation change. It operationalizes the Docs Style Guide. - [Page Templates](https://particlerealms.online/MD/contributing/page-templates.md): Copy-paste skeletons for new pages. The full files live in MD/templates/; this page explains when to use each and shows the shape. - [API Reference Standard](https://particlerealms.online/MD/contributing/api-reference-standard.md): The reference is hybrid: tools/extractapi.py generates per-file signature stubs from source; contributors add prose and examples in a separate notes/ overlay tree that the extractor injects below the… - [AI & Accessibility](https://particlerealms.online/MD/contributing/ai-and-accessibility.md): This documentation is built to be AI-safe (readable by and guiding to LLM agents) and human-safe (accessible, accurate, and clear). This page records those conventions. They draw on the emerging… - [Diagram Guide](https://particlerealms.online/MD/contributing/diagram-guide.md): Diagrams help readers grasp complex flows faster. This project uses Mermaid so diagrams live in Markdown, are versioned with text, and render in all three viewers. - [Contribution Workflow](https://particlerealms.online/MD/contributing/doc-contribution-workflow.md): How to add or change documentation and keep it from drifting. Docs are treated as code: edited in Markdown, validated by tooling, and reviewed. - [Agent Guide (AGENTS.md)](https://particlerealms.online/MD/AGENTS.md): This MD/ folder is the single source of truth for the WebGPU OS stack documentation. The stack has five subsystems: engine, editor, plauna, agi, and webgpu-os. Start at index.md for the human entry… - [Changelog](https://particlerealms.online/MD/CHANGELOG.md): All notable changes to this documentation set are recorded here. Format follows Keep a Changelog; this set is versioned independently of the code.