docs: update README to accurately reflect current implementation state

README.md

@@ -1,35 +1,203 @@
 # WEFT OS
 
-WEFT OS is a Linux-based operating system effort built around a Smithay compositor, a Servo-rendered system shell, and a Wasmtime-based application runtime.
+WEFT OS is an operating system project that treats **authority boundaries** as the primary design problem.
 
-## Current repository scope
+At a high level, the system is organized around three roles:
 
-This repository currently contains:
+- a **Wayland compositor** (Rust + Smithay) that owns surfaces, stacking, and input routing
+- a **system shell renderer** that aims to render the desktop UI from HTML/CSS via Servo (as a Wayland client)
+- an **application supervisor** that owns app lifecycle and brokers app sessions
 
-- the baseline Rust workspace
+The thesis is not “the desktop is a web page.”
-- public engineering documentation derived from the authoritative blueprint
-- initial design documents for the shell protocol boundary and the Wasm–Servo channel
-- local and CI validation paths for repository bootstrap work
 
-It does not yet contain a compositor, shell, or application runtime implementation.
+The thesis is:
 
-## Source of truth
+- a system UI can be rendered using web technologies
+- without collapsing the OS into a single privileged UI process
+- if the compositor and runtime boundaries remain explicit and enforced
 
-The authoritative technical reference for this repository is `docu_dev/WEFT-OS-COMPREHENSIVE-BLUEPRINT.md`.
+This repository is intentionally rigorous about distinguishing:
 
-Historical blueprint documents exist in `docu_dev/`, but they are not implementation authority where they conflict with the comprehensive blueprint.
+- what is **implemented today**
+- what is the **design direction**
 
-## Privacy boundary
+That distinction is critical for meaningful community contribution.
 
-`docu_dev/` is a private coordination area used during development. It is intentionally ignored by git and is not part of the tracked public repository surface.
+## Current status (verifiable from source)
 
-## Development model
+This repo is a Rust workspace (edition **2024**) with `unsafe_code` **forbidden** at the workspace lint level.
 
-- Primary development host: Windows workstation
+It contains working scaffolding and partial implementations for:
-- Primary runtime target: Linux VM or QEMU guest
-- Core system language: Rust
 
-## Validation
+- `weft-compositor`
+  - starts with a **winit** backend when `--winit` is passed or when a display environment is detected
+  - includes a Linux-only path for a **DRM/KMS** backend
+  - integrates a custom Wayland protocol XML under `protocol/` and generates server bindings
+- `weft-servo-shell`
+  - connects to a Wayland compositor and locates `system-ui.html`
+  - **Servo embedding is not yet implemented** (the entry point currently errors intentionally)
+- `weft-appd`
+  - listens on a Unix socket for IPC
+  - exposes a local WebSocket endpoint (127.0.0.1) for clients
+  - maintains a simple app session registry and supervises a runtime process
+- `weft-runtime`
+  - resolves an app “package” directory and expects an `app.wasm` file
+  - prints `READY` and exits cleanly as a placeholder
+  - **Wasmtime integration is not yet implemented**
+
+Public engineering documentation lives under `docs/architecture/`.
+
+## What WEFT OS is trying to build (in-depth architecture)
+
+WEFT OS is best understood as a set of promises. Those promises are implemented as explicit boundaries.
+
+### 1) The compositor is the authority
+
+In WEFT, the compositor is not “the thing that draws windows.”
+
+It is the component that answers (consistently) the questions that become security and reliability properties:
+
+- which surfaces exist
+- which surfaces are visible, and where
+- which surface receives input
+- what happens when a client misbehaves or dies
+
+Wayland’s model makes this boundary practical: clients do not get global visibility by default.
+
+Smithay is used to build this compositor because it provides structured protocol handling and a place for centralized state, which makes it easier to express policy explicitly.
+
+### 2) The shell is a document, but not a sovereign
+
+WEFT’s system shell is intended to be an HTML/CSS UI rendered via Servo, running as a Wayland client.
+
+This choice is not about using “web UI” for novelty.
+
+It is about:
+
+- treating layout and animation as a disciplined constraint system
+- leveraging a widely understood UI language
+- while keeping system authority out of the UI runtime
+
+The shell must be able to crash without automatically taking the whole session with it.
+
+That requires the compositor to remain authoritative.
+
+### 3) Apps are supervised sessions, not ambient processes
+
+WEFT treats application launch as the moment where the system can be honest about authority.
+
+The intended model is:
+
+- the OS creates an app session
+- the OS launches the app’s runtime participant
+- the OS launches the app’s UI participant
+- the OS brokers their relationship
+
+In this repo today, `weft-appd` provides the session registry and launch/supervision skeleton.
+
+### 4) WebAssembly is an OS runtime model (not a browser feature)
+
+WebAssembly is used in WEFT as a way to make “no ambient authority” plausible.
+
+The core idea is capability-shaped access:
+
+- a path string is not permission
+- holding a handle is permission
+
+This repo does not yet integrate Wasmtime, but it includes a runtime placeholder (`weft-runtime`) designed to evolve into a host-controlled Wasmtime embedder.
+
+### 5) The core/UI channel is brokered (and must stay that way)
+
+WEFT’s app model assumes the app has two isolated parts:
+
+- a Wasm core
+- an HTML UI
+
+Those two still need to exchange events and state.
+
+The direction documented in `docs/architecture/wasm-servo-channel.md` is:
+
+- a brokered message channel owned by `weft-appd`
+- structured, validated messages
+- explicit backpressure and bounded payloads
+- session teardown on process death
+
+The channel is explicitly not treated as a capability transport.
+
+### 6) Storage and packages are integrity and authority problems
+
+WEFT’s storage stance is shaped by two goals:
+
+- the OS should be able to answer “what is running?”
+- apps should not get filesystem traversal by default
+
+The design direction emphasizes immutable payloads, separation of code and writable data, and mediated user-intent file access (portal-style) rather than ambient path access.
+
+Not all of this is implemented in this repository today.
+
+It is included here because it defines what “substantial contribution” means: work that preserves explicit boundaries.
+
+## Collaboration: let’s find the hard answers together
+
+If you want to contribute, don’t start by asking “what feature should we add.”
+
+Start by asking:
+
+- what promise are we trying to make?
+- what would count as evidence that we can keep it?
+
+### High-value open problems
+
+These are the areas where contribution has the highest leverage:
+
+- **Servo embedding for a shell-grade Wayland client**
+  - input correctness, event loop integration, stable embedding surface
+- **Shell/compositor boundary**
+  - the smallest protocol surface that keeps authority correct
+  - object lifecycle and stale identifier rejection
+- **Wasm ↔ UI channel implementation**
+  - brokered transport, validation, backpressure, observability
+- **Wasmtime integration in `weft-runtime`**
+  - host-controlled execution, resource limits, and capability-shaped IO
+- **Failure and recovery behavior**
+  - compositor restart behavior
+  - shell restart behavior
+  - app crash containment
+
+If you disagree with the premises, that’s also useful.
+
+The most valuable criticism is the one that points at a boundary and says:
+
+- “this is where the promise will break”
+
+## Runtime knobs (verifiable from source)
+
+This repo is early, but some runtime configuration already exists in code. These values are listed here so contributors can run components consistently and so future work doesn’t accidentally break the contract.
+
+### `weft-servo-shell`
+
+- `WEFT_SYSTEM_UI_HTML`
+  - If set, `weft-servo-shell` will use this path as the `system-ui.html` entry point.
+- `WAYLAND_DISPLAY`
+  - Must be set; `weft-servo-shell` uses it to connect to the running compositor.
+
+### `weft-appd`
+
+- `WEFT_APPD_SOCKET`
+  - If set, overrides the Unix socket path used for IPC.
+- `WEFT_APPD_WS_PORT`
+  - If set, overrides the local WebSocket port (defaults to `7410`).
+- `XDG_RUNTIME_DIR`
+  - Required; used to place runtime files such as the default Unix socket location.
+
+### `weft-runtime`
+
+- `WEFT_APP_STORE`
+  - If set, overrides the app package store root.
+
+## Development and validation
+
+### Validation
 
 On Windows PowerShell:
 
@@ -43,10 +211,13 @@ On Linux:
 ./infra/scripts/check.sh
 ```
 
-## Repository layout
+These scripts run formatting, clippy, and workspace tests (with `weft-compositor` excluded on non-Linux hosts).
+
+### Repository layout
 
 ```text
 crates/      Rust workspace members
 docs/        Public engineering documentation
 infra/       Validation scripts and VM workflow material
+protocol/    Wayland protocol XML definitions
 ```