eco_os/readme.hints.md

# EcoOS Project Hints

## Project Structure

```
eco_os/
├── ecoos_daemon/       # Daemon source code (Deno/TypeScript)
├── isobuild/           # ISO build configuration (Dockerfile, hooks, includes)
├── isotest/            # Test scripts (run-test.sh, screenshot.sh, stop.sh)
└── .nogit/             # Generated files (not in git)
    ├── iso/            # Built ISO (ecoos.iso)
    ├── vm/             # QEMU files (disk, sockets, logs)
    └── screenshots/    # VM screenshots
```

## Build & Test Commands (package.json)

```bash
# Build ISO (auto-rebuilds daemon first)
pnpm run build

# Test ISO in QEMU
pnpm run test

# Take screenshot
pnpm run test:screenshot

# Stop QEMU VM
pnpm run test:stop

# Clean build artifacts
pnpm run clean

# Daemon development (watch mode)
pnpm run daemon:dev

# Bundle daemon to binary
pnpm run daemon:bundle
```

## Current Network Configuration

Using **systemd-networkd** (NOT NetworkManager) with DHCP:

- Config file: `/etc/systemd/network/10-wired.network`
- Matches: `ens*`, `enp*`, `eth*`
- Uses DHCP (QEMU user networking provides DHCP)

The installer (`install.sh`) creates this config explicitly during installation.

## Browser: Chromium (not Firefox, not Google Chrome)

The project uses **Chromium** for the kiosk browser.

### Key Files
- `isobuild/config/hooks/normal/0060-install-chromium.hook.chroot` - Installs Chromium dependencies
- `ecoos_daemon/ts/daemon/process-manager.ts` - Launches Chromium with Wayland support

### Why Chromium from Debian?
Ubuntu 24.04 made `chromium-browser` snap-only. Snap doesn't work in live-build chroot environments.
The hook adds Debian sid repo temporarily to install the real Chromium package.

## Sway Configuration

Sway config is **generated dynamically** by the daemon at runtime, NOT from a static file.

The daemon writes the config to `~/.config/sway/config` before starting Sway with `-c` flag.

### Chromium Kiosk Flags
```
--ozone-platform=wayland
--kiosk
--no-first-run
--disable-infobars
--disable-session-crashed-bubble
--disable-restore-session-state
```

### Chromium app_id on Wayland
Chromium identifies as `chromium-browser` or `Chromium-browser` in Sway.

## eco-daemon Binary

The binary at `isobuild/config/includes.chroot/opt/eco/bin/eco-daemon` is compiled from `ecoos_daemon/` using Deno.

**Note:** `pnpm run build` automatically rebuilds the daemon before building the ISO.

## ISO Boot Menu

1. Install EcoOS (auto-selects in 10s) - Default
2. EcoOS Live (Try without installing)
3. EcoOS Live (Safe Mode)

## CRITICAL: Sway + QEMU Display Fix

**ISSUE**: Sway shows gray/black screen with windows not rendering properly in QEMU.

**FIX**: In `isotest/run-test.sh`, use `-vga qxl` instead of `-device virtio-vga`

Source: ArchWiki Sway page, GitHub issue swaywm/sway#6210

## CRITICAL: Hook Permissions

**ISSUE**: Chromium not installed in ISO.

**FIX**: All hook files must be `chmod +x`:
```bash
chmod +x isobuild/config/hooks/normal/*.hook.chroot
```

If hooks aren't executable, live-build SKIPS them silently!

## Serial Console Debugging

Use socat to connect to QEMU serial console:
```bash
socat - UNIX-CONNECT:.nogit/vm/serial.sock
```

Login: `ecouser/ecouser`, then `sudo -i` for root.

## Lesson: ALWAYS RESEARCH BEFORE FIXING

When encountering issues:
1. DO NOT assume the same fix will work repeatedly
2. DO research the issue online first
3. Check ArchWiki, GitHub issues, official docs
4. Understand WHY the fix works
5. Document findings in readme.hints.md

## Testing Protocol

- Take screenshots every 10 seconds during testing, NOT 45+ seconds
- Use serial console for debugging network/service issues
- Check `ip addr` on guest to verify network interface has IP