# EcoOS Project Hints

## Build & Test Commands (package.json)

```bash
# Build the Docker image (do this after config changes)
npm run build:docker

# Build the ISO (requires Docker image)
npm run build

# Test ISO in QEMU
npm run test

# Take screenshot
npm run test:screenshot

# Stop QEMU VM
npm run test:stop

# Clean build artifacts
npm run clean

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

# Start daemon directly
npm run daemon:start

# Bundle daemon to binary
npm 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: Google Chrome (not Firefox)

The project uses **Google Chrome** for the kiosk browser, NOT Firefox.

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

## 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.

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

### Chrome app_id on Wayland
Chrome identifies as `google-chrome` or `Google-chrome` in Sway.

## eco-daemon Binary

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

**After changing daemon code, rebuild with:**
```bash
npm run daemon:bundle
cp ecoos_daemon/bundle/eco-daemon isobuild/config/includes.chroot/opt/eco/bin/
```

## 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**: Chrome 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:isotest/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