# Changelog All notable changes to this documentation set are recorded here. Format follows [Keep a Changelog](https://keepachangelog.com/); this set is versioned independently of the code. ## [Unreleased] ### Changed - Updated Particle Realms Studio to the six-stage recipe workflow: recipe-backed demos, Simulate-first tuning, project schema v2, typed recipe plans, native `ParticleSimWorld` adapters, bounded evidence paths, and CSE/sandbox persistence. Legacy Artist/Twin sidecars remain losslessly compatible without appearing as workspaces. - Expanded Recipe into a full-width visual typed builder with add/remove/connect/disconnect operations, draggable persisted node positions, exact invalid-draft diagnostics, last-valid execution-plan retention, a bounded measured native-readback preview, and direct navigation to the authoritative Simulate canvas. Scoped dialog styling now prevents the Recipe workspace from inheriting modal width and height constraints. - Changed Simulate to keep its tuning drawer closed until explicitly requested and replaced user-selectable particle tiers with an automatic, measured population controller targeting stable 60 FPS. Population uses smoothed cadence, hysteresis, cooldown, workgroup quantization, and only internal device/runtime safety ceilings. ### Added - Initial restructured documentation set in `MD/` (single source of truth). - Zero-build HTML viewer (`viewer/`) with sidebar nav, search, in-page TOC, code copy, and Mermaid support, plus a built-in fallback Markdown renderer. - **Viewer QoL pass:** collapsible/nested API-reference tree (lazy-rendered, per-folder counts), sidebar filter box (`Ctrl+Shift+F`) with highlighted matches, custom themed scrollbars, breadcrumbs, reading-progress bar, back-to-top button, collapse-all control, and persisted open/scroll state via `localStorage`. Active reference pages auto-expand their folders and scroll into view. - **AI-safe & human-safe pass:** `AGENTS.md` (agent boundaries/commands), `llms.txt` + `llms-full.txt` (llmstxt.org discovery standard) generated by `tools/build_llms.py`, YAML frontmatter support across the viewer + build tools (title/description/updated; reference pages stamped `kind: reference` + `source`), a [AI & Accessibility](contributing/ai-and-accessibility.md) conventions page, a home-page accuracy/safety notice, per-page **View source** links, and accessibility upgrades (`prefers-reduced-motion`, `aria-current`/`aria-expanded`). - **Discovery & metadata pass:** `robots.txt` (allows crawlers, references `sitemap.xml` + the `llms.txt` indexes); a repo-wide root `AGENTS.md` for coding agents (the `MD/AGENTS.md` one stays docs-scoped); git-based "last updated" fallback — `tools/build_docs.py` now emits `_config/git-dates.json` and the viewer uses it when a page has no `updated` frontmatter; and hand-authored `title`/`description`/`updated` frontmatter on every curated page (Getting Started, Concepts, all five subsystems, and Contributing). - **Author attribution:** [Author & Credits](about/credits.md) page, a persistent "Built by Jake Wehmeier" viewer footer credit, and SPDX license headers across the docs tooling and the wider source tree (see root `AUTHORS`, `LICENSE`, and `LICENSES/`). - **Ported website guides:** the curated guides from `tests/guide` were hand-ported into MD as the single source of truth — a new **Guides (How-To)** section ([Capabilities — What You Can Build](guides/capabilities.md), [Engine Stack Usage](guides/engine-stack-usage.md)) plus Engine deep-dives ([Virtual GPU](engine/vgpu.md), [ECS v2](engine/ecs.md), [Rendering](engine/rendering.md), [Shaders & WGSL](engine/shaders.md), [Particle System](engine/particles.md), [Physics](engine/physics.md), [GPU Physics Engine](engine/gpu-physics.md), [Math Library](engine/math.md), [Audio](engine/audio.md)). - **Website single-source docs:** the public site's **Guide** and **API** tabs now embed the MD zero-build viewer (`tests/guide/index.html` + `tests/api/index.html` are thin shells over `MD/viewer/`), backed by a new [API Reference](api/index.md) hub. `bundle_engine.py` now ships `MD/` into `release/site/MD/` on every build (fresh cache, no manual copy) for both the website embeds and the WebGPU OS `DocsApp`, refreshing the search index first; the dev `../../MD/` embed path is rewritten to `../MD/` for the release layout. - **Hand-authored notes overlay for the API reference:** notes now live *outside* the generated pages in `MD/_notes/`, so the ~1700 reference files stay purely generated (regenerable from scratch) while prose is never clobbered. `tools/extract_api.py` injects them below the `` marker on every run: **per-page notes** (`_notes//.md`) and **reusable shared blocks** (`_notes/_shared.json`) applied to many pages by glob — write common context once instead of copying it onto every page. **Expanded to 13 shared blocks** with detailed runnable examples: GPU device sharing, package trust tiers, AGI training loop, Plauna lifecycle, ECS pattern (complex queries, system groups, events), audio graph (asset loading, spatial audio, mixing buses), physics integration (raycasting, constraints, CCD), input handling, voxel world, world streaming, math conventions, command bus, and editor extensions — covering **~1000+ pages**. **Added 8 per-page overlays** for high-traffic modules: MathVec3, MathMat4, MathQuat, MathScalar, MathRandom, Renderer, Camera, Shader, PackageLoader, and NetworkArchitecture — each with complete API examples and gotchas. The viewer's `rewriteLinks` gained docroot-absolute (`/path.md`) link support so shared blocks link correctly from pages at any depth; `_notes/` is excluded from the search index and bundle. - **Single-file deploy bundle:** `tools/build_bundle.py` packs the nav, search index, git-dates, every Markdown page, and the reference indexes into one gzipped `_config/docs-bundle.json.gz` (~1700 files → 1 file, 5.8 MB → 1.2 MB). The viewer fetches and gunzips it in-browser (`DecompressionStream`), serving all pages from memory; it falls back to per-file fetch when the bundle is absent (dev). The release build now ships only the viewer + vendored libs + the single bundle, keeping deploys well under static-host file caps (e.g. Cloudflare Pages' 1000-file limit). The viewer's fallback Markdown renderer also gained GFM table support so tables render without the vendored `marked` library. - Navigation manifest `_config/nav.json` consumed by all viewers. - Python tooling (`tools/`): `fetch_vendor.py` (offline vendor libs), `build_docs.py` (search index + nav validation), `extract_api.py` (hybrid API-reference generation with preserved hand-notes). - Getting Started: overview, install, quickstart, glossary, FAQ. - Whole-stack concepts: architecture overview, history & evolution, boot sequence, GPU device sharing, security & trust model, data flow. - Per-subsystem docs (overview/architecture/getting-started/index) for engine, editor, plauna, agi, and webgpu-os; AGI training guide; WebGPU OS app catalog (35 apps). - Contributing standards: style guide, writing checklist, page templates, API reference standard, diagram guide, contribution workflow. - Page templates in `_templates/`. - MkDocs Material configuration (`_config/mkdocs.yml`). ### Notes - Existing docs under `docs/`, `webgpu-os/docs/`, `engine/docs/`, and per-component `.md` files remain in place as read-only reference sources. ## [0.1.0] — 2026-06-05 ### Added - Documentation overhaul scaffolding and plan baseline.