docs: Add comprehensive flow tracking and mark unfinished flows

- Create FLOWS.md with complete inventory of all 16 flows in codebase
- Mark 5 complete, 7 partial, and 4 not started flows
- Add [UNFINISHED FLOW] TODO markers to affected files:
  - wine-launcher.sh: VM launcher not implemented
  - execute.ts: Non-JS/TS language support missing
  - app-registry.ts: Stub implementation only
  - OAUTH_IMPLEMENTATION.md: Unlink endpoint needed
  - DEPLOYMENT_STATUS.md: Railway deployment pending
- Add FLOWS.md reference to PROJECT_RUNDOWN.md

DEPLOYMENT_STATUS.md

@@ -126,14 +126,16 @@ After deployment:
 
 ---
 
-## Next Steps
+## Next Steps (UNFINISHED DEPLOYMENT FLOW)
+
+> **Note:** These items are tracked in `/FLOWS.md` - update both documents when completing items.
 
 1. ✅ Railway config created
-2. ⏳ Deploy to Railway
+2. ⏳ **[UNFINISHED]** Deploy to Railway
-3. ⏳ Configure custom domain
+3. ⏳ **[UNFINISHED]** Configure custom domain
-4. ⏳ Update Warden bot config
+4. ⏳ **[UNFINISHED]** Update Warden bot config
-5. ⏳ Test end-to-end flow
+5. ⏳ **[UNFINISHED]** Test end-to-end flow
-6. ⏳ Monitor logs and metrics
+6. ⏳ **[UNFINISHED]** Monitor logs and metrics
 
 ---
 

FLOWS.md

@@ -0,0 +1,311 @@
+# AeThex-OS: Complete Flows Inventory
+
+> **Last Updated:** January 4, 2026
+> **Purpose:** Track all flows, workflows, and processes in the codebase with completion status
+
+---
+
+## Summary
+
+| Category | Total | Complete | Partial | Not Started |
+|----------|-------|----------|---------|-------------|
+| CI/CD Workflows | 3 | 2 | 1 | 0 |
+| Authentication Flows | 2 | 1 | 1 | 0 |
+| API Flows | 3 | 1 | 2 | 0 |
+| Sales Funnel Features | 5 | 0 | 1 | 4 |
+| Runtime Flows | 2 | 1 | 1 | 0 |
+| Deployment Flows | 1 | 0 | 1 | 0 |
+| **TOTAL** | **16** | **5** | **7** | **4** |
+
+**Overall Completion: ~50%**
+
+---
+
+## CI/CD Workflows
+
+### 1. GitHub Actions - Build ISO
+- **File:** `.github/workflows/build-iso.yml`
+- **Status:** ⚠️ PARTIAL
+- **Flow Steps:**
+  1. ✅ Trigger on manual dispatch or push to main
+  2. ✅ Build client (npm run build)
+  3. ⚠️ Build ISO (creates placeholder if build script fails)
+  4. ✅ Verify ISO artifact
+  5. ✅ Upload artifacts (90-day retention)
+  6. ✅ Create GitHub Release (optional)
+- **Issue:** Creates placeholder artifacts when `script/build-linux-iso.sh` fails (lines 59-61)
+- **TODO:** Ensure build script handles all edge cases without placeholders
+
+---
+
+### 2. GitHub Actions - Deploy Docs
+- **File:** `.github/workflows/deploy-docs.yml`
+- **Status:** ✅ COMPLETE
+- **Flow Steps:**
+  1. ✅ Trigger on push to main with `docs/**` changes
+  2. ✅ Checkout code
+  3. ✅ Setup GitHub Pages
+  4. ✅ Upload artifact from `docs/` directory
+  5. ✅ Deploy to GitHub Pages
+
+---
+
+### 3. GitLab CI/CD Pipeline
+- **File:** `.gitlab-ci.yml`
+- **Status:** ✅ COMPLETE
+- **Stages:**
+  - ✅ `build`: Installs dependencies, runs npm build, executes full ISO build
+  - ✅ `release`: Creates GitLab releases on tags
+
+---
+
+## Authentication Flows
+
+### 4. Basic Auth Flow
+- **File:** `server/routes.ts`
+- **Status:** ✅ COMPLETE
+- **Endpoints:**
+  - ✅ `POST /api/auth/login` - Session creation
+  - ✅ `POST /api/auth/signup` - User registration
+  - ✅ `GET /api/auth/session` - Verify auth status
+  - ✅ `POST /api/auth/logout` - End session
+
+---
+
+### 5. OAuth 2.0 Identity Linking Flow
+- **File:** `server/oauth-handlers.ts`, `server/routes.ts`
+- **Status:** ⚠️ PARTIAL (Core complete, missing features)
+- **Implemented:**
+  - ✅ `POST /api/oauth/link/:provider` - Start OAuth flow
+  - ✅ `GET /api/oauth/callback/:provider` - OAuth callback handler
+  - ✅ State token validation (5-minute TTL)
+  - ✅ PKCE support for Roblox OAuth
+  - ✅ Duplicate identity detection
+- **UNFINISHED (docs/OAUTH_IMPLEMENTATION.md:271-278):**
+  - [ ] **HIGH:** Implement unlink endpoint: `DELETE /api/oauth/unlink/:provider`
+  - [ ] **HIGH:** Add frontend UI for identity linking (Settings page)
+  - [ ] **HIGH:** Redis/database for state storage (replace in-memory Map)
+  - [ ] **MEDIUM:** Rate limiting on OAuth endpoints
+  - [ ] **MEDIUM:** Logging/monitoring for OAuth events
+  - [ ] **LOW:** Refresh token support
+  - [ ] **LOW:** Additional providers (Twitter/X, Google, Steam)
+
+---
+
+## API Flows
+
+### 6. Mode Preference Flow
+- **File:** `server/routes.ts`
+- **Status:** ✅ COMPLETE
+- **Endpoints:**
+  - ✅ `GET /api/user/mode-preference` - Retrieve user mode
+  - ✅ `PUT /api/user/mode-preference` - Update user mode
+
+---
+
+### 7. Code Execution API
+- **File:** `api/execute.ts`
+- **Status:** ⚠️ PARTIAL
+- **Implemented:**
+  - ✅ JavaScript execution
+  - ✅ TypeScript execution
+- **UNFINISHED (lines 25-29):**
+  - [ ] Python execution
+  - [ ] Go execution
+  - [ ] Rust execution
+  - [ ] Other languages return placeholder: "Execution not yet supported in cloud environment"
+
+---
+
+### 8. App Registry System
+- **File:** `client/src/shared/app-registry.ts`
+- **Status:** ⚠️ STUB ONLY
+- **Issues:**
+  - Line 1: "Minimal app registry stub to satisfy imports and provide types"
+  - Line 14: `AppRegistry` is empty `{}`
+  - Line 37-40: `canAccessRoute()` always returns `true` (placeholder)
+- **UNFINISHED:**
+  - [ ] Populate `AppRegistry` with actual app definitions
+  - [ ] Implement proper role-based access control in `canAccessRoute()`
+  - [ ] Add app capability checks
+
+---
+
+## Sales Funnel Features
+
+> **Reference:** `PROJECT_RUNDOWN.md` lines 99-176
+
+### 9. INTEL Folder
+- **Status:** ❌ NOT IMPLEMENTED
+- **Purpose:** Weaponize Naavik research report as "secret knowledge"
+- **TODO (PROJECT_RUNDOWN.md:184-189):**
+  - [ ] Add `INTEL` folder icon to desktop
+  - [ ] Create `CROSS_PLATFORM_REPORT.TXT` file app
+  - [ ] Write content summarizing Naavik research
+  - [ ] Link to analysis
+
+---
+
+### 10. System Upgrade Alert
+- **Status:** ❌ NOT IMPLEMENTED
+- **Purpose:** Sell Foundry ($500) as OS "permission upgrade"
+- **TODO (PROJECT_RUNDOWN.md:190-195):**
+  - [ ] Add flashing system tray icon
+  - [ ] Create upgrade notification component
+  - [ ] Design modal/window with Foundry pitch
+  - [ ] Add iFrame or link to `.studio` Foundry page
+
+---
+
+### 11. Network Neighborhood App
+- **Status:** ❌ NOT IMPLEMENTED
+- **Purpose:** Show user directory, gamify joining
+- **TODO (PROJECT_RUNDOWN.md:196-201):**
+  - [ ] Create `NETWORK` desktop icon
+  - [ ] Build user directory window
+  - [ ] Show current members (You, Dylan, Trevor)
+  - [ ] Add locked slots with "Requires Architect Access"
+  - [ ] Connect to actual user database
+
+---
+
+### 12. My Computer / Drives
+- **Status:** ❌ NOT IMPLEMENTED
+- **Purpose:** Show value of owning a .aethex domain
+- **TODO (PROJECT_RUNDOWN.md:202-208):**
+  - [ ] Add `THIS PC` / `MY COMPUTER` icon
+  - [ ] Show Drive C (Local) and Drive D (.aethex TLD)
+  - [ ] Implement "not mounted" error for TLD drive
+  - [ ] Add call-to-action to join Foundry
+
+---
+
+### 13. Enhanced Login Screen
+- **Status:** ⚠️ PARTIAL (basic login exists)
+- **Purpose:** Dramatize system access with Passport initialization
+- **TODO (PROJECT_RUNDOWN.md:209-213):**
+  - [ ] Upgrade boot sequence with Passport initialization
+  - [ ] Add "Detecting cross-platform identity" animation
+  - [ ] Make login feel more like system access
+
+---
+
+## Runtime Flows
+
+### 14. Linux ISO Build Flow
+- **File:** `script/build-linux-iso.sh` and variants
+- **Status:** ✅ COMPLETE (containerized edition)
+- **Flow Steps:**
+  1. ✅ Clean build directory
+  2. ✅ Check/install dependencies
+  3. ✅ Download Ubuntu Mini ISO base
+  4. ✅ Build application layer in chroot
+  5. ✅ Create AeThex user with auto-login
+  6. ✅ Configure LightDM
+  7. ✅ Copy application files
+  8. ✅ Install Node dependencies
+  9. ✅ Create systemd services
+  10. ✅ Configure Firefox kiosk mode
+  11. ✅ Create SquashFS filesystem
+  12. ✅ Setup BIOS/UEFI boot
+  13. ✅ Create hybrid ISO
+
+---
+
+### 15. Windows Runtime (Wine Launcher)
+- **File:** `os/runtimes/windows/wine-launcher.sh`
+- **Status:** ⚠️ PARTIAL
+- **Implemented:**
+  - ✅ Wine installation check
+  - ✅ Wine prefix setup
+  - ✅ Attempt to run .exe with Wine
+- **UNFINISHED (line 22):**
+  ```bash
+  # Launch QEMU/KVM Windows VM (TODO: implement)
+  notify-send "VM launcher not implemented yet"
+  ```
+  - [ ] Implement QEMU/KVM Windows VM fallback
+  - [ ] VM image management
+  - [ ] Hardware passthrough configuration
+
+---
+
+## Deployment Flows
+
+### 16. Railway Deployment
+- **File:** `DEPLOYMENT_STATUS.md`
+- **Status:** ⚠️ PARTIAL (config ready, not deployed)
+- **Completed:**
+  - ✅ Railway config created (`railway.json`, `nixpacks.toml`)
+  - ✅ Database schema ready
+  - ✅ Documentation complete
+- **UNFINISHED (DEPLOYMENT_STATUS.md:131-136):**
+  - [ ] Deploy to Railway
+  - [ ] Configure custom domain
+  - [ ] Update Warden bot config
+  - [ ] Test end-to-end flow
+  - [ ] Monitor logs and metrics
+
+---
+
+## Backend/Multiplayer Features (Future)
+
+> **Reference:** `PROJECT_RUNDOWN.md` lines 214-226
+
+### Planned Features (Not Started)
+- [ ] WebSocket presence system
+- [ ] Cursor sharing
+- [ ] Real-time notifications for multiplayer
+- [ ] Discord bridge
+- [ ] Track upgrade clicks analytics
+- [ ] Log INTEL folder opens
+
+---
+
+## Files Requiring TODO Markers
+
+| File | Line | Issue |
+|------|------|-------|
+| `os/runtimes/windows/wine-launcher.sh` | 22 | VM launcher not implemented |
+| `api/execute.ts` | 25-29 | Non-JS/TS languages unsupported |
+| `client/src/shared/app-registry.ts` | 1, 14, 37-40 | Stub implementation only |
+| `docs/OAUTH_IMPLEMENTATION.md` | 259 | Unlink endpoint needed |
+| `DEPLOYMENT_STATUS.md` | 132-136 | Deployment pending |
+
+---
+
+## Quick Reference: Unfinished Items by Priority
+
+### Critical (Blocking Features)
+1. OAuth unlink endpoint
+2. App Registry implementation
+3. Railway deployment
+
+### High Priority (Sales Funnel)
+4. INTEL Folder
+5. System Upgrade Alert
+6. Network Neighborhood
+7. My Computer / Drives
+
+### Medium Priority
+8. Code execution for additional languages
+9. Windows VM launcher
+10. OAuth rate limiting
+
+### Low Priority
+11. Enhanced login screen
+12. Multiplayer features
+13. Additional OAuth providers
+
+---
+
+## How to Use This Document
+
+1. **Before starting work:** Check this document to understand what's complete
+2. **After completing a flow:** Update the status and remove from TODO lists
+3. **When adding new flows:** Add an entry with status and implementation steps
+4. **Regular audits:** Review quarterly to identify stale items
+
+---
+
+*Generated by automated flow analysis. See commit history for updates.*

PROJECT_RUNDOWN.md

@@ -15,6 +15,8 @@
 - ✅ Capacitor mobile apps (iOS/Android)
 - 🔄 **Need to implement: Sales funnel features**
 
+> **📋 For complete flow tracking, see [FLOWS.md](./FLOWS.md)** - comprehensive list of all implemented and unfinished flows.
+
 ---
 
 ## 📊 The Architecture

api/execute.ts

@@ -22,7 +22,12 @@ export default async function handler(req: VercelRequest, res: VercelResponse) {
       return;
     }
 
-    // For other languages, return a placeholder
+    // TODO: [UNFINISHED FLOW] Add support for additional languages
+    // Priority languages to implement:
+    //   - Python (via pyodide or server-side execution)
+    //   - Go (via server-side compilation)
+    //   - Rust (via server-side compilation)
+    // See: FLOWS.md section "Code Execution API"
     res.status(200).json({
       output: `// Language: ${language}\n// Execution not yet supported in cloud environment\n// Run locally for full support`,
       status: 'info'

client/src/shared/app-registry.ts

@@ -1,3 +1,11 @@
+// TODO: [UNFINISHED FLOW] This is a minimal stub - full implementation required
+// Required implementation:
+//   1. Populate AppRegistry with actual app definitions from os.tsx
+//   2. Implement proper role-based access control
+//   3. Add app capability checks
+//   4. Connect to user permission system
+// See: FLOWS.md section "App Registry System"
+
 // Minimal app registry stub to satisfy imports and provide types
 export type AppId = string;
 
@@ -34,7 +42,11 @@ export enum Realm {
   Network = "network"
 }
 
-// Minimal route access check placeholder (always allows)
+// TODO: [UNFINISHED FLOW] Implement proper route access control
+// This placeholder always allows access - needs real implementation:
+//   - Check user roles against route requirements
+//   - Validate user capabilities
+//   - Enforce realm restrictions (foundation/studio/network)
 export function canAccessRoute(_user: unknown, _route?: string): boolean {
   return true;
 }

docs/OAUTH_IMPLEMENTATION.md

@@ -268,10 +268,12 @@ function getRedirectUri(provider: string): string {
 
 ---
 
-## 🚧 TODO / Future Improvements
+## 🚧 TODO / Future Improvements (UNFINISHED FLOWS)
+
+> **Note:** These items are tracked in `/FLOWS.md` - update both documents when completing items.
 
 ### High Priority
-- [ ] Implement unlink endpoint: `DELETE /api/oauth/unlink/:provider`
+- [ ] **[UNFINISHED]** Implement unlink endpoint: `DELETE /api/oauth/unlink/:provider`
 - [ ] Add frontend UI for identity linking (Settings page)
 - [ ] Redis/database for state storage (replace in-memory Map)
 - [ ] Rate limiting on OAuth endpoints

os/runtimes/windows/wine-launcher.sh

@@ -19,7 +19,14 @@ wine "$EXE_FILE" 2>&1 | tee /tmp/wine-debug.log
 if [ $? -ne 0 ]; then
   zenity --question --text="Wine failed. Use Windows VM instead?"
   if [ $? -eq 0 ]; then
-    # Launch QEMU/KVM Windows VM (TODO: implement)
+    # TODO: [UNFINISHED FLOW] Implement QEMU/KVM Windows VM launcher
+    # Required steps:
+    #   1. Check for QEMU/KVM installation
+    #   2. Download or locate Windows VM image
+    #   3. Configure hardware passthrough (GPU, USB)
+    #   4. Launch VM with proper networking
+    #   5. Pass the .exe file to the VM for execution
+    # See: FLOWS.md section "Windows Runtime (Wine Launcher)"
     notify-send "VM launcher not implemented yet"
   fi
 fi