AGENTS.md

1# apps/AGENTS.md
2 
3Follow the root `AGENTS.md` first. This file only records module-level boundaries for `apps/`.
4 
5## Active apps
6 
7- `apps/web`: Next.js 16 App Router + React 18 web runtime. Entrypoints live in `apps/web/app/`; the main client shell is `apps/web/src/App.tsx`. During local `tools-dev` web runs, `apps/web/next.config.ts` rewrites `/api/*`, `/artifacts/*`, and `/frames/*` to `OD_PORT`.
8- `apps/daemon`: Express + SQLite local daemon and `od` bin. It owns REST/SSE APIs, agent CLI spawning, skills, design systems, artifact persistence, static serving, and daemon-managed data. Before describing or changing daemon data paths, read the root `AGENTS.md` section **Daemon data directory contract**; it is mandatory and must not be restated here.
9- `apps/desktop`: Electron shell. Desktop does not guess the web port; it reads runtime status through sidecar IPC and opens the reported web URL.
10- `apps/packaged`: Thin packaged Electron runtime entry. It starts packaged daemon/web sidecars, registers the `od://` entry protocol, and delegates desktop host behavior to `apps/desktop`.
11- `apps/landing-page`: Standalone static Astro marketing and public catalog site. It reads canonical repository content at build time, deploys independently, and must not import product-runtime internals from the other apps.
12 
13## Daemon layout
14 
15- `apps/daemon/src/` contains only daemon app source.
16- `apps/daemon/tests/` contains daemon tests.
17- `apps/daemon/src/sidecar/` contains the daemon sidecar entry.
18- CLI/agent argument definition changes belong in `apps/daemon/src/runtimes/defs/`; stdout parser changes belong with the matching runtime helpers and parser tests.
19 
20### Router layout
21 
22- Existing daemon domain endpoints belong in the matching daemon route file; avoid adding route handlers directly to `apps/daemon/src/server.ts` unless the route is bootstrap-wide or has no clear domain owner.
23- New route registrars should be wired into the matching semantic section in `server.ts`; keep sections broad and reuse existing sections before adding a new one.
24- Bootstrap-wide routes describe daemon availability or startup metadata shared by every domain. `/api/health` and `/api/version` stay in `server.ts` because they only report process-level status.
25- Domain routes describe a product capability or data model. `/api/active` belongs in `apps/daemon/src/routes/active-context.ts` because transient UI focus is its own domain, while chat routes own persistent conversation and run state.
26- Add endpoints to an existing route file when they share the same domain language and dependency set. Split a new module under `apps/daemon/src/routes/` when the endpoint introduces a distinct domain or has little dependency overlap with existing route modules.
27 
28## Test layout
29 
30- App tests live in each app's `tests/` directory, sibling to `src/`; preserve source-relative subpaths inside `tests/` when useful.
31- Keep app `src/` directories source-only; do not add new `*.test.ts` or `*.test.tsx` files under `src/`.
32- `apps/web/tests/` contains web-owned Vitest tests and uses `*.test.ts` / `*.test.tsx`.
33- Playwright UI automation belongs in `e2e/ui/`; do not add Playwright suites or UI automation helper scripts under `apps/web`.
34 
35## Sidecar awareness
36 
37- App business layers must not import sidecar packages or branch on `runtime.mode`, `namespace`, `ipc`, or `source`.
38- Keep sidecar awareness in `apps/<app>/sidecar` or the desktop sidecar entry wrapper.
39 
40## Packaged runtime
41 
42- `apps/nextjs` has been removed; do not restore it.
43- Packaged web uses Next.js SSR through the web sidecar; do not put Next output under daemon `OD_RESOURCE_ROOT`.
44- Packaged `OD_RESOURCE_ROOT` is for daemon non-Next read-only resources. The authoritative bundled-tree list lives in `tools/pack/src/resources.ts` and currently includes skills, design templates, design systems, craft, official and registry plugin data, frames, community pets, prompt templates, and baked plugin-preview metadata.
45- Packaged data/log/runtime/cache paths must be namespace-scoped and must not depend on daemon or web ports.
46- Daemon↔web packaged traffic still uses an HTTP origin/port because Next.js dev server and SSR proxy paths assume HTTP origins; switching to Unix sockets would require patching Next internals. The invariant is that data/log/runtime/cache paths never embed ports.
47 
48## Common app commands
49 
50```bash
51pnpm --filter @open-design/web typecheck
52pnpm --filter @open-design/web test
53pnpm --filter @open-design/daemon typecheck
54pnpm --filter @open-design/daemon test
55pnpm --filter @open-design/daemon build
56pnpm --filter @open-design/desktop typecheck
57pnpm --filter @open-design/desktop build
58pnpm --filter @open-design/packaged typecheck
59pnpm --filter @open-design/packaged build
60pnpm --filter @open-design/landing-page typecheck
61pnpm --filter @open-design/landing-page build:static
62```
63