# AGENTS.md

Instructions for AI agents working in this repository.

## Session Initialization

At the start of every session, before doing any other work:

1. Read `CONVENTIONS.md` and follow all conventions defined there
2. Scan `skills/` for local skill directories. Read the YAML frontmatter of each `SKILL.md` to learn what skills are available. Do not read the full skill body unless the skill is being invoked.

Do not proceed with any user requests until these steps are complete.

## Development Environment

Read `DEV.md` for the full development guide. The essentials:

### Running the Stack

```bash
bun install
bin/db-reset && bin/dev --seed
```

`bun install` materializes the workspace symlinks under `node_modules/@intx/`;
without it `make build` fails with `TS2307: Cannot find module '@intx/...'`.
The remaining command gets a clean, running system with seed data. It drops and recreates the database, runs migrations, grants permissions, starts all services (hub, sidecar, admin UI), and seeds test data.

- Hub: `http://localhost:3000`
- Admin UI: `http://localhost:5173`
- Seed login: `alice@example.com` / `password123`

### Common Operations

| Task                          | Command                 |
| ----------------------------- | ----------------------- |
| Start stack (no seed)         | `bin/dev`               |
| Start stack with seed         | `bin/dev --seed`        |
| Start stack without admin UI  | `bin/dev --no-admin-ui` |
| Full database reset           | `bin/db-reset`          |
| Full reset (DB + agent state) | `bin/db-reset --clean`  |
| Apply migrations only         | `bin/db-migrate`        |
| Seed (requires running hub)   | `bin/seed`              |
| Full build verification       | `make all`              |
| Type check only               | `make build`            |
| Bundle the admin UI           | `make build-admin-ui`   |
| Lint only                     | `make lint`             |
| Run tests only                | `make test`             |
| Admin UI e2e suite            | `make test-e2e`         |
| Auto-format                   | `make format`           |
| Regenerate API docs           | `make docs`             |

Use the `make` targets above for build, lint, test, format, and docs.
The Makefile is the authoritative entrypoint: it runs each command
directly and runs `bin/check-env` to verify the environment before each
build.

`bin/db-reset` only resets postgres. `--clean` additionally wipes
`HUB_DATA_DIR` and `SIDECAR_DATA_DIR` so the sidecar does not try to
reconnect stale agent instances against a fresh database. Use it after
any reset where the sidecar disk state no longer matches the DB.

### Database

The system uses two PostgreSQL users: a migration user (DDL, owns tables) and a hub user (read/write app user). `bin/db-reset` handles all permission grants automatically. Never run the grant steps manually; use the script.

If you need to reset the database while the stack is running, stop the stack first (Ctrl+C) or you will get "active connections" errors.

## Build Requirements

You must run the full build pipeline before declaring any task complete:

```bash
make all
```

This runs lint, type check (`tsc -b`), the admin-ui production bundle
(`vite build`), and tests in order, after verifying the environment via
`bin/check-env`. Do not run `tsc`, `eslint`, or `bun test` directly in
place of `make all` -- the Makefile is the authoritative entrypoint and
gates on `bin/check-env` first.

- `make build` runs `tsc -b --noEmit --force`, revalidating the entire
  TypeScript project graph on every run; an incremental build can pass
  while a cross-package type break sits latent
- `make build-admin-ui` runs `vite build`, catching production-bundle
  breaks that pass the type-check (the bundler resolves assets, CSS, and
  imports that `tsc` does not exercise)
- Individual package builds do not guarantee the full tree will build
- Type exports and imports may not be available until the full tree is built
- Tests may fail if dependent packages are not rebuilt

If the build fails, report the failure and identify the cause. If the failure is pre-existing and unrelated to your changes, say so explicitly and let the user decide how to proceed. Never silently skip a failing step or substitute a partial build.

## Code Reuse and Refactoring

Do not reimplement functionality that already exists in the codebase. Before writing new code:

1. Search for existing implementations that could serve the same purpose
2. If similar functionality exists, prefer refactoring it to meet the new requirements
3. Look for unexported functions in other packages that could be promoted to a shared location

When you detect that a refactor might be necessary, prompt the user with specific options and allow them to provide their own answer if none fit.

## Configuration

Do not modify configuration files (e.g. eslint, prettier, tsconfig) unless explicitly asked. Focus on writing working software, not changing the conventions that are being used.

## Personality

Do not use emojis in code or documentation. Act professionally.
