# AGENTS.md - Desktop App Guidelines

Thin WebUI shell hosting the fullstack server app.

## Tech Stack

> **⚠️ This project uses Bun — NOT Node.js / npm. All commands use `bun`. Never use `npm`, `npx`, or `node`.**

- **Type**: WebUI desktop shell
- **Design**: Server-driven desktop (thin native window hosting web app)
- **Runtime**: Bun (Main process) + System browser / WebView (via WebUI)
- **Window Library**: [webui-dev/webui](https://github.com/webui-dev/webui) — opens installed browser or native WebView as GUI
- **Build**: Turborepo

## Architecture

- **Server-driven design**: The desktop app is a "thin" native shell. It does not contain UI or business logic; it opens a browser window pointing to the `apps/server` TanStack Start application.
- **Dev mode**: Waits for the Vite dev server at `localhost:3000`, then opens a WebUI window. Requires `apps/server` to be running separately.
- **WebUI**: Uses `@webui-dev/bun-webui` (FFI-based C library binding). Auto-detects and opens the best available browser in a private profile, or uses the system WebView.

## Commands

```bash
bun dev                    # Open WebUI window (requires server dev running)
bun fix                    # Biome auto-fix
bun typecheck              # TypeScript check
```

## Directory Structure

```
.
├── src/
│   └── bun/
│       └── index.ts       # Main process entry (server readiness check + WebUI window)
├── package.json           # Scripts and dependencies
├── turbo.json             # Dev pipeline (depends on server dev)
└── AGENTS.md              # Desktop guidelines (this file)
```

## Development Workflow

1. **Start server**: In `apps/server`, run `bun dev`.
2. **Start desktop**: In `apps/desktop`, run `bun dev`.
3. **Connection**: The desktop app polls `localhost:3000` until responsive, then opens the browser window.

## Critical Rules

**DO:**
- Use arrow functions for all utility functions.
- Ensure `apps/server` dev server is running before starting desktop.
- Use `catalog:` for all dependency versions in `package.json`.

**DON'T:**
- Use `npm`, `npx`, `node`, `yarn`, or `pnpm`. Always use `bun`.
- Include UI components or business logic in the desktop app (keep it thin).
- Use `as any` or `@ts-ignore`.