reorder: everythinggg

docs/01-get-started/01-setup-openxr.md

@@ -0,0 +1,37 @@
+---
+sidebar_position: 1
+---
+
+# Setup OpenXR Runtime
+
+:::info
+if you want to test stardust in flatscreen mode (in a window) without a headset or other OpenXR device, you can skip this step and start with [trying out telescope](bundled).
+:::
+
+Check the [hardware table](https://lvra.gitlab.io/docs/hardware/) to ensure your hardware and headset are compatible:
+
+## SteamVR
+
+You will likely want to use [Monado](#monado) instead, but if you need to the instructions are available.
+
+:::warning
+If you are on NixOS please consult https://lvra.gitlab.io/docs/distros/nixos/ before installing SteamVR.
+:::
+
+https://lvra.gitlab.io/docs/steamvr/ is a good starting point, but be aware that the stardust server cannot run as an overlay on top of other games due to SteamVR not implementing the OpenXR Overlay extension.
+
+## Monado
+
+If you've got a wired headset, this is generally the way to go.
+
+### NixOS
+
+It's generally easiest to follow the instructions at https://lvra.gitlab.io/docs/distros/nixos/ to install properly to the system.
+
+### Other distros
+
+[Envision](https://lvra.gitlab.io/docs/fossvr/envision/) is the XR launcher (like a minecraft launcher) of choice for open source XR and is overall better in practice than SteamVR.
+
+# Test OpenXR Runtime
+
+Try running [XRGears](https://gitlab.freedesktop.org/monado/demos/xrgears) and see if it works, you can get it from the system's package manager often.

docs/01-get-started/02-bundled.md

@@ -0,0 +1,30 @@
+---
+sidebar_position: 2
+---
+
+# Bundled setup
+
+Telescope is a bundled Stardust setup that lets you 1-click run all the essentials for testing a setup out on an existing 2D computer.
+
+## Nix
+
+### Install Nix
+
+For easy development and distribution this project uses the [nix package manager](https://nix.dev/).<br/>
+This allows to ensure all dependency requirements are met.
+
+If you do not have nix installed follow the instructions at https://nixos.org/download/#nix-install-linux.
+:::warning
+Make sure to have [flakes enabled](https://nixos.wiki/wiki/flakes).
+:::
+
+### Run Telescope
+
+Because telescope itself is a nix flake, you simply have to run
+```sh
+nix run github:StardustXR/telescope
+```
+
+## Non-nix
+
+An AppImage generated from the nix flake is currently WIP. Please check back later or do a [manual build.](manual)

docs/01-get-started/03-manual.md

@@ -0,0 +1,26 @@
+---
+sidebar_position: 3
+---
+
+# Manual build/installation
+
+Make sure all repos are cloned on the same branch (e.g. all main or all dev branch) to ensure stardust protocol compatibility.
+
+## Server
+Run and maybe install the server from https://github.com/StardustXR/server.
+Follow the README.
+
+## Clients
+
+After the server is running, you'll need to run some clients. Here's a demo showing some off:
+![A showcase of some different clients](/img/docs/clients/demo_01.mp4)
+
+Non-exhaustive list of clients:
+- [**flatland**](https://github.com/StardustXR/flatland): 3D panel UI (like window manager) for intercting with all your 2D apps
+![A flat panel containing the prism launcher](/img/docs/clients/flatland.png)
+- [**protostar**](https://github.com/StardustXR/protostar): App launcher library and examples including futuristic hexagon launcher
+- [**black hole**](https://github.com/StardustXR/black-hole): Universal minimization of Stardust objects
+- [**gravity**](https://github.com/StardustXR/gravity): Launch programs with a certain offset in 3D space
+- [**magnetar**](https://github.com/StardustXR/magnetar): Example workspaces client
+- [**atmosphere**](https://github.com/StardustXR/atmosphere): 3D environment with natural momentum-based movement
+- [**comet**](https://github.com/StardustXR/comet): Annotate in 3D wherever you want amongst your other apps!

docs/01-get-started/_category_.json

@@ -0,0 +1,4 @@
+{
+	"label": "Get Started",
+	"position": 1
+}

docs/02-dive-deeper/01-brief-overview.md

@@ -2,9 +2,9 @@
 sidebar_position: 1
 ---
 
-# Overview
+# Brief Overview
 
-Stardust XR _(formerly known as Stardust)_ is an XR [display server](https://itsfoss.com/display-server) designed for Linux-based systems<!-- (possibly most unix-based too, but untested)-->.<br/>
+Stardust XR is an XR [display server](https://itsfoss.com/display-server) designed for Linux-based systems<!-- (possibly most unix-based too, but untested)-->.<br/>
 Unlike traditional display servers that focus on 2D screens, Stardust XR introduces new conventions to utilize unbounded 3D space in virtual or real environments.
 
 ## Priorities
@@ -24,7 +24,64 @@ Unlike traditional display servers that focus on 2D screens, Stardust XR introdu
 
 ## Architecture
 
-![simplified architecture diagram](/img/docs/simplified-architecture.png)
+```mermaid
+graph LR
+    OpenXR
+
+    OpenXR -->|Frame Data| StereoKit
+    OpenXR -->|Input Data| StereoKit
+
+    subgraph Server[Stardust Server]
+    		StereoKit[StereoKit]
+        InternalSceneGraph[Internal Scenegraph]
+        WC1[Wayland Client 1]
+        DBusConnection[D-Bus Connection]
+
+        ClientSceneGraph -->|Drawable Objects| StereoKit
+        StereoKit -->|Controller, Hand & HMD Data| InternalSceneGraph
+        InternalSceneGraph -->|Panel Items| ClientSceneGraph
+        InternalSceneGraph -->|Controller, Hand & HMD Export| DBusConnection
+        WC1 -->|Panel Item| InternalSceneGraph
+        WC1 -->|Textures| StereoKit
+        StereoKit -->|EGL Context| WC1
+        ClientSceneGraph --> C1
+
+        subgraph C1[Stardust Client 1]
+        	ClientSceneGraph[Client Scenegraph]
+        end
+    end
+
+    StardustSocket[Stardust Socket]
+    SessionBus[D-Bus Session Bus]
+    WaylandSocket[Wayland Socket]
+
+    WC1 --> WaylandSocket
+    WaylandSocket --> WC1
+    DBusConnection --> SessionBus
+    C1 --> StardustSocket
+
+    subgraph StardustClient[Stardust Client 1]
+        Fusion
+        Molecules
+        UserCode[User Code]
+
+        Fusion --> Molecules
+        Fusion --> UserCode
+        Molecules --> UserCode
+
+        subgraph Fusion
+            libstardustxr[stardust-xr library]
+        end
+    end
+
+    StardustSocket --> libstardustxr
+    SessionBus -->|HMD Spatial Reference| Fusion
+
+
+    WaylandClient[Wayland Client]
+    WaylandSocket --> WaylandClient
+    WaylandClient --> WaylandSocket
+```
 
 ## Projects & Components
 

docs/02-dive-deeper/03-make-clients.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 4
+sidebar_position: 3
 ---
 
 # Making Clients

docs/02-dive-deeper/_category_.json

@@ -0,0 +1,4 @@
+{
+	"label": "Dive deeper",
+	"position": 2
+}

docs/02-getting-started/01-tutorial.md

@@ -1,86 +0,0 @@
----
-sidebar_position: 1
----
-
-# Tutorial
-
-## Setup OpenXR
-
-:::note
-if you have no headset or other OpenXR device, you can skip this step and start with [installing nix](#install-nix).
-:::
-
-### SteamVR
-
-#### Archlinux
-
-TODO
-
-#### NixOS
-
-TODO
-
-#### Others
-
-TODO: collect links for setup on different distrons
-
-### [Monado](https://monado.dev/)
-
-#### Archlinux
-
-TODO
-
-#### NixOS
-
-TODO
-
-#### Others
-
-TODO: collect links for setup on different distrons
-
-## Install nix
-
-For easy development and distribution this project uses the [nix package manager](https://nix.dev/).<br/>
-This allows to ensure all dependency requirements are met.
-
-:::info
-Make sure to have [flakes enabled](https://nixos.wiki/wiki/flakes).
-:::
-
-You can install nix on all common linux systems:
-
-#### Archlinux
-
-```shell
-# install git and nix
-sudo pacman -Sy git nix
-# enable flakes
-echo 'experimental-features = nix-command flakes' | sudo tee -a /etc/nix/nix.conf
-# enable nix daemon service
-sudo systemctl enable nix-daemon.service
-# add the current user to nix-users group
-sudo usermod -aG nix-users $(id -un)
-# reboot to apply user and service changes
-sudo systemctl reboot
-```
-
-#### NixOS
-
-TODO
-
-#### Others
-
-TODO: collect links for setup on different distrons
-
-## Run Demo
-
-1. clone https://github.com/StardustXR/telescope
-2. make sure your OpenXR device works (if 2D mode is not used)
-3. run `nix run .`
-
-## Run wayland client
-
-```shell
-# run demo.mp4 video in a loop within Stardust
-WAYLAND_DISPLAY=wayland-0 DISPLAY= mpv Downloads/demo.mp4 --loop
-```

docs/02-getting-started/03-setup.md

@@ -1,17 +0,0 @@
----
-sidebar_position: 3
----
-
-# Setup
-
-First you need to install and run the server from https://github.com/StardustXR/server. Follow the README. If you have issues getting OpenXR to work, try running https://gitlab.freedesktop.org/monado/demos/xrgears first.
-
-After the server is running, you'll need to run some clients. Here's a demo showing some off:
-![A showcase of some different clients](/img/docs/clients/demo_01.mp4)
-
-Non-exhaustive list of clients:
-- [Flatland](https://github.com/StardustXR/flatland): A panel item UI (XR equivalent of a window manager) so you can interact with your apps using virtual touchscreens. To show Wayland apps, run them with the proper `WAYLAND_DISPLAY` environment variable, in the server's startup script, or use a stardust launcher such as gravity or protostar. Flatland works great in 3DoF or 6DoF with direct touch and pointer interaction.
-![A flat panel containing the prism launcher](/img/docs/clients/flatland.png)
-- [Gravity](https://github.com/StardustXR/gravity): Command line tool to launch programs inside of stardust at a particular offset in space. This is nestable so you can run a script using gravity, and then gravity inside that script to make a whole composed setup out of thin air! It also ensures that everything launched through it will properly connect to the stardust server, such as wayland clients.
-- [Protostar](https://github.com/StardustXR/protostar): Prototype app launcher library/examples. Grab app icons and drop them in space to launch apps where they're dropped.
-- [Magnetar](https://github.com/StardustXR/magnetar): Workspaces in 3D. Any object inside the rings will move with them, so you can move a bunch of stuff out of the way temporarily when you don't need it.

docs/02-getting-started/_category_.json

@@ -1,4 +0,0 @@
-{
-	"label": "Getting Started",
-	"position": 2
-}