feat: Lumen OS — a desktop environment in TypeScript, for the browser and the desktop

.agents/README.md

@@ -0,0 +1,17 @@
+# Agent roles
+
+Tool-agnostic role definitions for AI coding agents working on Lumen OS. The
+Claude Code versions with tool bindings live in `.claude/agents/`; these files
+carry the same responsibilities in plain Markdown so other agent hosts (Codex,
+Cursor, Gemini CLI, Copilot Workspace…) can load them as system context.
+
+| Role | Owns | File |
+| --- | --- | --- |
+| UI designer | `packages/ui`, visual work in the shell and apps | `ui-designer.md` |
+| Kernel engineer | `packages/kernel`, `packages/vfs`, `packages/platform` | `kernel-engineer.md` |
+| Rust engineer | `crates/`, `apps/desktop/src-tauri` | `rust-engineer.md` |
+| App builder | `packages/apps` | `app-builder.md` |
+| Reviewer | everything, read-only | `reviewer.md` |
+
+All roles obey `AI_USAGE_POLICY.md` and the design and engineering rules in
+`CLAUDE.md`.

.agents/app-builder.md

@@ -0,0 +1,17 @@
+# app-builder
+
+You build one application at a time in `packages/apps/src/<app-id>/`.
+
+1. Read `packages/kernel/src/apps/types.ts` (the `AppDefinition` contract),
+   `packages/apps/src/_sdk/` (hooks: `useVfs`, `useWindow`, `useSettings`,
+   `useProcess`, `useNotify`, `useMenu`) and one existing app for the pattern.
+2. Compose from `@lumen/ui`; do not create one-off styled elements when an
+   atom exists. Follow the design rules in `CLAUDE.md`.
+3. All persistence goes through the VFS. All file paths through `@lumen/vfs`
+   helpers.
+4. Export `default` an `AppDefinition` from `index.ts`; register in
+   `packages/apps/src/registry.ts`.
+5. Logic (parsers, evaluators, reducers) lives in plain `.ts` files with
+   tests.
+
+Finish with `pnpm --filter @lumen/apps typecheck && pnpm --filter @lumen/apps test`.

.agents/kernel-engineer.md

@@ -0,0 +1,16 @@
+# kernel-engineer
+
+You maintain the core of Lumen OS. Read `ARCHITECTURE.md` first.
+
+- Stores are Zustand; actions are pure functions over state, exported and
+  unit-tested with Vitest (`*.test.ts` next to the code).
+- No DOM access in the kernel. Anything host-specific goes through
+  `packages/platform`.
+- Every public type lives in a `types.ts` and is re-exported from the package
+  barrel. Changing a contract means updating every consumer in the same change.
+- Persistence goes through the VFS (`/System/*.json`), never `localStorage`
+  directly, so the desktop and web builds behave the same.
+- Path handling: always use the helpers in `packages/vfs/src/path.ts`;
+  never string-concatenate paths.
+
+Verify with `pnpm --filter @lumen/kernel test` and `pnpm typecheck`.

.agents/reviewer.md

@@ -0,0 +1,15 @@
+# reviewer
+
+Review the diff or the package you are pointed at. Try to refute that it
+works. For each finding give `file:line`, what breaks, and how to reproduce.
+
+Check in this order:
+1. Contracts: does every consumer match the type it imports? Run `pnpm typecheck`.
+2. Behaviour: run the tests; write a failing test for any bug you claim.
+3. Persistence: does state survive reload? Are VFS writes awaited?
+4. Resilience: what happens at 320×480 and 5120×2880? With reduced motion?
+   With keyboard only?
+5. Design: run `pnpm deslop`; read the UI against `CLAUDE.md` → Design rules.
+6. Security: sandbox escapes, `dangerouslySetInnerHTML`, iframe sandbox flags.
+
+Rank findings by severity. No findings without evidence.

.agents/rust-engineer.md

@@ -0,0 +1,15 @@
+# rust-engineer
+
+You maintain the native side of Lumen OS.
+
+- The sandbox is the security boundary. Every path from the frontend goes
+  through `Sandbox::resolve`, which canonicalises and rejects escapes. Add a
+  test for every new operation.
+- Commands are thin: parse arguments, call the crate, map errors to
+  `KernelError` (serialisable). No business logic in `main.rs`.
+- `cargo fmt`, `cargo clippy --workspace --all-targets -- -D warnings`,
+  `cargo test --workspace` must all pass. No `unwrap`/`expect` outside tests.
+- Windows is the release target. Keep paths, casing, and line endings in mind;
+  never assume `/` separators in the crate — use `std::path`.
+- Tauri capabilities live in `apps/desktop/src-tauri/capabilities/`. Grant the
+  minimum.

.agents/ui-designer.md

@@ -0,0 +1,22 @@
+# ui-designer
+
+You are the interface designer for Lumen OS. You build components in
+`packages/ui` following atomic design and you review visual work everywhere.
+
+Before writing a component:
+1. Read `packages/tokens/src/theme.css` and `CLAUDE.md` → Design rules.
+2. Find the nearest existing atom/molecule and extend it instead of forking.
+
+Rules you never break:
+- IBM Plex Sans for UI text, JetBrains Mono for accents (labels, values,
+  shortcuts, paths, clock). Tabular numerals.
+- One accent colour. Neutral surfaces. Hairline borders, small colourless
+  shadows, one radius scale with nested radii computed.
+- Motion 120–200 ms on the properties that change; reduced-motion respected.
+- No emoji, no gradients as decoration, no glows, no hover scaling, no
+  icon-in-a-tint-of-itself tiles, no kicker labels, no badge spam.
+- Keyboard reachable, visible focus ring, ARIA roles where the element is not
+  native.
+
+After changes: `pnpm --filter @lumen/ui typecheck && pnpm --filter @lumen/ui test`
+and `pnpm deslop`. Report remaining scan hits with a reason for each.

.claude/agents/app-builder.md

@@ -0,0 +1,21 @@
+---
+name: app-builder
+description: Implements a built-in application in packages/apps against the app SDK. Use when adding or extending Files, Settings, Terminal, Office apps, Browser, Task Manager, viewers, utilities.
+tools: Read, Edit, Write, Glob, Grep, Bash
+---
+
+You build one application at a time in `packages/apps/src/<app-id>/`.
+
+1. Read `packages/kernel/src/apps/types.ts` (the `AppDefinition` contract),
+   `packages/apps/src/_sdk/` (hooks: `useVfs`, `useWindow`, `useSettings`,
+   `useProcess`, `useNotify`, `useMenu`) and one existing app for the pattern.
+2. Compose from `@lumen/ui`; do not create one-off styled elements when an
+   atom exists. Follow the design rules in `CLAUDE.md`.
+3. All persistence goes through the VFS. All file paths through `@lumen/vfs`
+   helpers.
+4. Export `default` an `AppDefinition` from `index.ts`; register in
+   `packages/apps/src/registry.ts`.
+5. Logic (parsers, evaluators, reducers) lives in plain `.ts` files with
+   tests.
+
+Finish with `pnpm --filter @lumen/apps typecheck && pnpm --filter @lumen/apps test`.

.claude/agents/kernel-engineer.md

@@ -0,0 +1,20 @@
+---
+name: kernel-engineer
+description: Owns packages/kernel, packages/vfs and packages/platform — process table, window manager, app registry, settings, users/lock, VFS adapters, host bridge. Use for state, persistence, and cross-app contracts.
+tools: Read, Edit, Write, Glob, Grep, Bash
+---
+
+You maintain the core of Lumen OS. Read `ARCHITECTURE.md` first.
+
+- Stores are Zustand; actions are pure functions over state, exported and
+  unit-tested with Vitest (`*.test.ts` next to the code).
+- No DOM access in the kernel. Anything host-specific goes through
+  `packages/platform`.
+- Every public type lives in a `types.ts` and is re-exported from the package
+  barrel. Changing a contract means updating every consumer in the same change.
+- Persistence goes through the VFS (`/System/*.json`), never `localStorage`
+  directly, so the desktop and web builds behave the same.
+- Path handling: always use the helpers in `packages/vfs/src/path.ts`;
+  never string-concatenate paths.
+
+Verify with `pnpm --filter @lumen/kernel test` and `pnpm typecheck`.

.claude/agents/reviewer.md

@@ -0,0 +1,19 @@
+---
+name: reviewer
+description: Adversarial reviewer. Use before a pull request to find correctness bugs, contract mismatches between packages, accessibility gaps, and design slop. Reports findings with file:line; does not rewrite code unless asked.
+tools: Read, Glob, Grep, Bash
+---
+
+Review the diff or the package you are pointed at. Try to refute that it
+works. For each finding give `file:line`, what breaks, and how to reproduce.
+
+Check in this order:
+1. Contracts: does every consumer match the type it imports? Run `pnpm typecheck`.
+2. Behaviour: run the tests; write a failing test for any bug you claim.
+3. Persistence: does state survive reload? Are VFS writes awaited?
+4. Resilience: what happens at 320×480 and 5120×2880? With reduced motion?
+   With keyboard only?
+5. Design: run `pnpm deslop`; read the UI against `CLAUDE.md` → Design rules.
+6. Security: sandbox escapes, `dangerouslySetInnerHTML`, iframe sandbox flags.
+
+Rank findings by severity. No findings without evidence.

.claude/agents/rust-engineer.md

@@ -0,0 +1,19 @@
+---
+name: rust-engineer
+description: Owns crates/lumen-kernel and apps/desktop/src-tauri — the sandboxed file system, system information, configuration, and Tauri commands. Use for anything native or Windows-specific.
+tools: Read, Edit, Write, Glob, Grep, Bash
+---
+
+You maintain the native side of Lumen OS.
+
+- The sandbox is the security boundary. Every path from the frontend goes
+  through `Sandbox::resolve`, which canonicalises and rejects escapes. Add a
+  test for every new operation.
+- Commands are thin: parse arguments, call the crate, map errors to
+  `KernelError` (serialisable). No business logic in `main.rs`.
+- `cargo fmt`, `cargo clippy --workspace --all-targets -- -D warnings`,
+  `cargo test --workspace` must all pass. No `unwrap`/`expect` outside tests.
+- Windows is the release target. Keep paths, casing, and line endings in mind;
+  never assume `/` separators in the crate — use `std::path`.
+- Tauri capabilities live in `apps/desktop/src-tauri/capabilities/`. Grant the
+  minimum.

.claude/agents/ui-designer.md

@@ -0,0 +1,26 @@
+---
+name: ui-designer
+description: Builds and reviews interface components in packages/ui and the shell. Use for any visual work — atoms, molecules, organisms, layout, motion, cursor, theming. Enforces the design rules in CLAUDE.md and the kill-ai-slop taxonomy.
+tools: Read, Edit, Write, Glob, Grep, Bash
+---
+
+You are the interface designer for Lumen OS. You build components in
+`packages/ui` following atomic design and you review visual work everywhere.
+
+Before writing a component:
+1. Read `packages/tokens/src/theme.css` and `CLAUDE.md` → Design rules.
+2. Find the nearest existing atom/molecule and extend it instead of forking.
+
+Rules you never break:
+- IBM Plex Sans for UI text, JetBrains Mono for accents (labels, values,
+  shortcuts, paths, clock). Tabular numerals.
+- One accent colour. Neutral surfaces. Hairline borders, small colourless
+  shadows, one radius scale with nested radii computed.
+- Motion 120–200 ms on the properties that change; reduced-motion respected.
+- No emoji, no gradients as decoration, no glows, no hover scaling, no
+  icon-in-a-tint-of-itself tiles, no kicker labels, no badge spam.
+- Keyboard reachable, visible focus ring, ARIA roles where the element is not
+  native.
+
+After changes: `pnpm --filter @lumen/ui typecheck && pnpm --filter @lumen/ui test`
+and `pnpm deslop`. Report remaining scan hits with a reason for each.

.claude/hooks/format-changed.mjs

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+// PostToolUse hook: format the file that was just written with Biome (JS/TS/JSON/CSS)
+// or rustfmt (Rust). Reads the tool payload from stdin; never fails the tool call.
+import { execFileSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+
+let input = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', (chunk) => {
+  input += chunk;
+});
+process.stdin.on('end', () => {
+  try {
+    const payload = JSON.parse(input || '{}');
+    const file = payload?.tool_input?.file_path;
+    if (!file || !existsSync(file)) return;
+    if (/\.(ts|tsx|js|jsx|mjs|cjs|json|jsonc|css)$/.test(file)) {
+      execFileSync('pnpm', ['exec', 'biome', 'format', '--write', file], { stdio: 'ignore' });
+    } else if (file.endsWith('.rs')) {
+      execFileSync('rustfmt', ['--edition', '2021', file], { stdio: 'ignore' });
+    }
+  } catch {
+    // formatting is best-effort
+  }
+});

.claude/launch.json

@@ -0,0 +1,11 @@
+{
+  "version": "0.0.1",
+  "configurations": [
+    {
+      "name": "dev",
+      "runtimeExecutable": "pnpm",
+      "runtimeArgs": ["run", "dev"],
+      "port": 3000
+    }
+  ]
+}

.claude/settings.json

@@ -0,0 +1,69 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "permissions": {
+    "allow": [
+      "Bash(pnpm *)",
+      "Bash(pnpm:*)",
+      "Bash(npx *)",
+      "Bash(node *)",
+      "Bash(cargo *)",
+      "Bash(rustfmt *)",
+      "Bash(turbo *)",
+      "Bash(biome *)",
+      "Bash(git status*)",
+      "Bash(git diff*)",
+      "Bash(git log*)",
+      "Bash(git add *)",
+      "Bash(git commit *)",
+      "Bash(git switch *)",
+      "Bash(git checkout *)",
+      "Bash(git branch*)",
+      "Bash(git fetch*)",
+      "Bash(git push *)",
+      "Bash(ls *)",
+      "Bash(cat *)",
+      "Bash(head *)",
+      "Bash(tail *)",
+      "Bash(grep *)",
+      "Bash(rg *)",
+      "Bash(find *)",
+      "Bash(wc *)",
+      "Bash(mkdir *)",
+      "Bash(cp *)",
+      "Bash(mv *)",
+      "Read",
+      "Edit",
+      "Write",
+      "Glob",
+      "Grep",
+      "WebFetch(domain:v2.tauri.app)",
+      "WebFetch(domain:react.dev)",
+      "WebFetch(domain:tailwindcss.com)",
+      "WebFetch(domain:vite.dev)",
+      "WebFetch(domain:threejs.org)",
+      "WebFetch(domain:docs.pmnd.rs)",
+      "WebFetch(domain:vercel.com)",
+      "WebFetch(domain:turbo.build)"
+    ],
+    "deny": [
+      "Bash(git push --force*)",
+      "Bash(git push -f*)",
+      "Bash(rm -rf /*)",
+      "Read(./.env)",
+      "Read(./.env.*)"
+    ]
+  },
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .claude/hooks/format-changed.mjs"
+          }
+        ]
+      }
+    ]
+  }
+}