docs: architecture describes what is built now

kernel (threads, demand paging, TLB shootdowns, dynamic linking, RAM direct map), syscalls, filesystem (/proc, /sys,
/dev), terminals (12, VT handshake, ptys), networking (r8169 through LDLS), LDLS (module sets; Linux code may ship),
devices (what stays in the kernel; hybrid.md's lasting content), boot (the loader's placement of the kernel),
graphics (fbdev, GMMOS, QR 1-40), audio (ALSA over OSS), debugging, usb. New: packages.md (the apk root) and
desktop.md (Xorg on the framebuffer).

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EVRhxi9zpdW2uDUN4FVcao

docs/architecture/desktop.md

@@ -0,0 +1,74 @@
+# The desktop: Xorg on the framebuffer
+
+The desktop is X11, on the framebuffer: Alpine's `xorg-server` with the `fbdev` video
+driver and the `evdev` input driver, Window Maker as the window manager, and `xterm`.
+`startx` runs `wmaker`. Nothing here is written by SchOS except the kernel interfaces it
+stands on and four small files in `tools/posix/mkaroot.sh`.
+
+## Why X and not Wayland
+
+Every Wayland compositor worth running — labwc, and everything built on wlroots — needs
+DRM/KMS, libinput, udev and libseat. DRM/KMS is the largest of them by far: a kernel graphics
+subsystem, and in practice a great deal taken from Linux. Xorg runs on a plain framebuffer
+through `fbdev` and reads input through `evdev`, both interfaces SchOS already had. That is
+the shorter road to a desktop by a long way, and it brings the window managers with it.
+DRM/KMS is not planned; libinput, udev and libseat are worth having for their own sake and
+may come later.
+
+## What it stands on
+
+| | |
+|---|---|
+| **fbdev** | `/dev/fb0` speaks Linux's fbdev ([graphics.md](graphics.md#devfb0-and-how-xorg-draws)) |
+| **evdev** | `/dev/input/event0` (every keyboard) and `event1` (every mouse and touchpad) with Linux's queries, LED writes and key/button/relative-axis bits |
+| **VTs** | `/dev/tty0`, `VT_SETMODE(VT_PROCESS)`, `KD_GRAPHICS`, the release/acquire handshake ([terminals.md](terminals.md)) |
+| **dlopen** | Xorg loads its drivers as modules, so `exec` does dynamic linking ([kernel.md](kernel.md)) |
+| **sysfs** | `/sys/bus/pci/devices/*/{boot_vga,enable,graphics/fb0}`, which libpciaccess reads |
+| **ptys** | `xterm` runs its shell on a pseudo-terminal |
+| **Unix sockets** | the X11 socket, abstract names, `SO_PEERCRED`, `flock` |
+| **headers** | `<linux/*.h>` in the build sysroot, as `ports/linux-headers` |
+
+`cmd/xready` checks every one of the kernel calls Xorg makes before it draws anything — the
+evdev queries, the fbdev calls, the console calls, and the `/sys` files — one at a time, on a
+terminal of its own, and puts everything back. The calls were written against what the
+programs are documented to do; each step past it found one that was not, which is what running
+the real program is for.
+
+## The four files
+
+- **`/root/.xserverrc`** starts `X` on the VT `startx` was started from (startx works that
+  out only when `uname -s` says Linux, and SchOS's says SchIFT) with **`-dumbSched`**. Xorg
+  normally reads input on a thread of its own; when SchOS had no threads the server crashed
+  the first time a client disconnected, in `pthread_join` on a thread that was never made, and
+  `-dumbSched` is Xorg's own switch for input on the main loop. Threads exist now; the switch
+  is still on, and nobody has run the server without it since.
+- **`/root/.xinitrc`** is `exec wmaker`. Without it xinit falls back to twm and an xterm, which
+  are not in the image.
+- **`/etc/X11/xorg.conf.d/10-schos.conf`** names the input devices. Alpine's Xorg asks udev for
+  them, SchOS has no udev, and X came up with no keyboard and no mouse: the pointer did not
+  move and nothing could end the session. SchOS has exactly two input nodes whatever the
+  machine, so a fixed list is the whole answer (`AutoAddDevices` off, Ctrl+Alt+Backspace
+  enabled).
+- **`/etc/asound.conf`** is for sound, not X ([audio.md](audio.md)).
+
+## Using it
+
+Twelve virtual terminals, switched with Ctrl+Alt+F1–F12 — on the console and under X
+alike, because X owns the keyboard while it runs and switches only with that chord. `startx` on
+a terminal runs the desktop there; Ctrl+Alt+Backspace ends the session and gives the terminal
+back. Window Maker, `xterm`, `xeyes`, `xclock`, `xcalc`, DejaVu fonts; SDL 2 games
+(`lbreakouthd`) and NetSurf, a GTK 3 browser, run in it.
+
+Touchpads that sit on an I2C bus (most laptops) are driven by `kernel/acpi/i2c_hid.c`, found
+through ACPI, and reach X as a mouse: pointer, click and tap.
+
+## What it does not do
+
+- **No acceleration.** Software rendering to the framebuffer: no DRM, no glamor, no DRI, no
+  OpenGL beyond what software gives. GPU drivers are a plan ([../plan/gpu.md](../plan/gpu.md)).
+- **No udev.** Input devices are named in a config file, not found; `/sys` has no `devices`
+  tree and no uevent socket.
+- **Touchpads are mice**: no two-finger scroll, no gestures, no palm rejection.
+- **No resolution change from inside X.** The mode is the console's; `schmode` changes the
+  `vgpud` head only, and the loader's menu is where a real panel's mode is chosen.
+- **Not a security boundary.** X runs as root on a system that enforces no file permissions.