# PROJECT: "OS" – An AI-native web operating system

Build a single-page web application that feels and behaves like a real desktop
operating system (inspirations: macOS, Windows 11, Ubuntu/GNOME). It is NOT a mockup –
windows, apps, and state actually work. At its heart is an AI that generates missing
applications on demand and integrates them seamlessly into the system.

## TECH STACK
- React + TypeScript + Vite
- Tailwind CSS for the design system
- Zustand (or Context) for global state (windows, processes, filesystem)
- Framer Motion for window animations
- Persistence via IndexedDB (virtual filesystem + installed apps survive reload)
- Anthropic Messages API for the AI (model: claude-sonnet-4-6), streaming where possible

## CORE EXPERIENCE (the most important part)
1. On startup: boot sequence (short, stylish, with logo + progress), then login/lockscreen,
   then the desktop.
2. Desktop with wallpaper, icons, menu bar at the top (or taskbar at the bottom), clock, status icons.
3. A "dock"/"start menu" with the available apps.
4. A central AI ("the assistant" / Spotlight-style command bar, via Cmd+Space):
   The user types e.g. "I need a text editor" or "build me a Pomodoro app".
   - If the app already exists → open it.
   - If it does NOT exist → the AI generates a complete, working app component,
     "installs" it (icon appears in the dock + filesystem), and opens it immediately.

## THE APP-GENERATING AI (the centerpiece – build it carefully)
- The AI receives a system prompt containing:
  a) the design system (design tokens, allowed components, color/spacing rules),
  b) an app-manifest specification (name, icon, default window size, category),
  c) the instruction to return a self-contained, runnable React component as a string.
- Response format: strict JSON (no markdown, no backticks):
  { "name", "icon", "category", "defaultSize", "code" }
- The returned component code is executed safely at runtime
  (e.g. via Babel-standalone transform + a controlled scope with provided
  libraries/hooks). Apps may access ONLY the allowed system APIs
  (see System SDK below) – no direct DOM/network access outside the SDK.
- Generated apps are persisted in IndexedDB and loaded automatically on the next start.
- Error handling: if generated code crashes, an error boundary catches it and
  offers to let the AI repair the code automatically ("self-healing").

## SYSTEM SDK (what generated apps are allowed to use)
Provide a clean API that is injected into every generated app:
- os.fs        → virtual filesystem (read/write/list/delete) via IndexedDB
- os.window    → set window title, close, resize
- os.ai        → apps can call the AI themselves (e.g. a notes app asks for a summary)
- os.notify    → system notifications
- os.storage   → key-value persistence per app
- os.theme     → read the current design tokens (so apps adapt to the theme)

## WINDOW MANAGER (must feel real)
- Movable, resizable windows with a title bar (minimize/maximize/close).
- Z-index stacking: the active window comes to the front.
- Snap-to-edge (dock windows to the screen edge → half/full screen).
- Minimize into the dock with animation, restore animation.
- Multiple instances, multiple apps at the same time.
- Optional: Mission-Control / overview view (all windows tiled).

## DESIGN SYSTEM (consistency is mandatory)
- Define central design tokens (colors, radii, shadows, blur/glass, typography, spacing).
- ALL apps – including generated ones – look like they came from one mold: same buttons,
  inputs, window chrome, iconography.
- Aesthetic suggestion (swappable): warm amber "NEON NOODLE OS" – dark background,
  glassy panels with a subtle glow, monospace accents, smooth animations.
  (If you can think of something better, propose your own coherent design language.)
- Frosted-glass effects (backdrop-blur), light/dark-mode toggle in the system settings.

## PRE-INSTALLED APPS (as a design reference + baseline kit)
- Files (file manager for the virtual FS)
- Terminal (with a few real commands: ls, cat, mkdir, "ai <prompt>")
- Settings (theme, wallpaper, light/dark, "manage installed apps")
- The AI assistant (chat window + Spotlight command bar)
- "App Builder" – explicitly shows how the AI generates apps (for the demo/wow effect)

## NICE-TO-HAVE (if there's time/room)
- App-store view with AI-suggested app ideas.
- Right-click context menus on the desktop and in apps.
- Sound design (boot chime, clicks) – subtle, can be turned off.
- Apps can send each other data (inter-process via an os bus).

## IMPLEMENTATION REQUIREMENTS
- Cleanly modularized: kernel/ (state, fs, window-manager, ai), system-ui/, apps/, design/.
- The API key is NOT hard-coded (environment variable or handled by the host).
- Write it so I can start it locally with `npm run dev`.
- Begin with a brief architecture overview, then build iteratively:
  first boot + desktop + window manager, then a static app, then the AI generation.

Goal: on first launch I say "build me a calculator" and 5 seconds later a fully
functional calculator that fits the OS perfectly is sitting on the desktop.