# Repository Guidelines

## Project Structure & Module Organization

This is a Nx monorepo with Bun package manager.

- `apps/builder/` - Visual flow editor (Running on port 3000)
- `apps/viewer/` - Runtime that executes bots (Running on port 3001)
- `apps/landing-page/` - Commercial website landing page
- `apps/workflows/` - Durable workflows server
- `apps/docs/` - Documentation
- `packages/` - All feature-driven modules, shared libs, schemas, UI package.

## Commands

All scripts must be ran with `bunx nx`:

- Typescript project references can be automatically updated with `bunx nx sync`.
- Most of the scripts are inferred with nx plugins. A few examples:
  - fastest way to typecheck `builder` and/or `viewer`: run root `bunx nx typecheck` (runs `tsc --build --emitDeclarationOnly`)
  - typecheck a particular package: `bunx nx typecheck package_name`.
  - test a package: `bunx nx test package_name`
  - typecheck all afffected packages: `bunx nx affected -t typecheck` (**IMPORTANT**: Rely first on IDE's TS server diagnostics first for faster feedback loop)
- To check format and lint, run: `bunx nx format-and-lint` (with `--write --unsafe` to run autofix)
- Never run plain `bunx tsc`, use `bunx nx`
- Avoid running multiple Vitest test targets in a single Nx command such as `bunx nx run-many -t test` or `bunx nx affected -t test`. Each Nx test target starts its own Vitest process and its own global setup.
- When multiple Vitest projects need to share the same global setup and database container, run the root workspace test target instead: `bunx nx test`.
- To run one Vitest project through the shared root runner, use `bunx nx test <project-name>`.

## Coding style

- Write Effect code whenever possible. We use Effect V4 Beta. **IMPORTANT** Always inspect the Effect source through `opensrc` first (see "Source Code Reference" below) — start from `LLMS.md` at the source tree root and follow the linked docs. Never guess at Effect patterns.
- Never use `as`. You should always narrow / parse the value to get the right type.
- Rely heavily on type inference, we tend not to declare types.
- Prefer files exporting a single primary function and the file name should match the exported function name. On that file, the main exported function is at the top while local helpers are at the bottom.
- Use very explicit variable names.
- Extract a helper function only if the logic is used at least twice in the main function.
- Declare a variable only if it is used at least twice.

## Source Code Reference

To check the source code and documentation of a dependency, run `bunx opensrc path <package-name>` (e.g. `bunx opensrc path lexical`) to get the local path to its cached source, then read or grep files under that path (e.g. `cat $(bunx opensrc path lexical)/README.md`). For beta / pre-release versions, always pin the exact version with `<package>@<version>` (e.g. `bunx opensrc path effect@<exact-beta-version>`).

`opensrc path` returns the package directory. Repo-level docs like `LLMS.md` live at the source tree root, so go up from the package path to find them (e.g. `cat $(bunx opensrc path effect@...)/../LLMS.md`).

**IMPORTANT** Do not use `node_modules/` as your primary source for understanding dependency internals. Always prefer `opensrc` for the original source implementation. Use `node_modules/` only when you specifically need the installed runtime/distribution output.

## Workflow

- Use `trash` instead of `rm` when deleting files or directories.
- To navigate to an authenticated session with Playwright, you need to inject cookies from `apps/viewer/src/test/.auth/user.json`.
- Do not pass those stored cookie objects directly to `browserContext.addCookies()`. Remap them to a minimal Playwright shape such as `{ name, value, url: "http://localhost:3000", expires, httpOnly, secure, sameSite }`.
- Prefer `http://localhost:3000` over `127.0.0.1:3000` when reusing that auth file, since the saved session cookies are scoped for `localhost`.