# Repository Guidelines

## Project Structure & Module Organization

This repository is an npm workspace for Jacques. Main packages live in `core/`, `server/`, `cli/`, and `gui-v2/`.

- `core/src/`: shared business logic, archive, session, context, cache, and adapter code
- `server/src/`: WebSocket/HTTP server, terminal/session management, routes, auth, and platform integration
- `cli/src/`: terminal UI and CLI commands
- `gui-v2/src/`: Vite/React web UI
- `hooks/`, `skills/`, `docs/`, and `assets/`: integrations, packaged skills, documentation, and screenshots

Build output is written to package-local `dist/` directories. Keep source edits inside `src/` unless you are intentionally changing scripts or docs.

## Build, Test, and Development Commands

Use Node 20+ and install from the repo root:

- `npm install`: install all workspace dependencies
- `npm run build:all`: compile `core`, `server`, `cli`, and `gui-v2`
- `npm run start:server`: run the built server on port `4243`
- `npm run dev:gui`: start the Vite GUI with hot reload
- `npm run dev:server`, `npm run dev:cli`, `npm run dev:core`: watch-mode TypeScript builds per package
- `npm run test:core`, `npm run test:cli`, `npm test`: run Jest suites for `core`, `cli`, and `server`

For package-specific work, run commands inside that package, for example `cd gui-v2 && npm run test`.

## Coding Style & Naming Conventions

The codebase is TypeScript-first with ESM modules and explicit `.js` import suffixes in source. Follow the existing style: 2-space indentation, semicolons, and single quotes in TS files unless a file already uses another style.

Naming patterns:

- React components: `PascalCase.tsx`
- utilities/services/modules: `kebab-case.ts`
- tests: colocated `*.test.ts` or `*.test.tsx`

There is no repo-wide ESLint or Prettier config checked in, so match nearby files before introducing formatting changes.

## Testing Guidelines

Jest is used in `core/`, `server/`, and `cli/`; `gui-v2` uses Vitest. Add tests next to the implementation they cover, such as `server/src/handlers/session-handler.test.ts`.

Prefer focused unit tests for parsing, routing, terminal/session behavior, and hooks. Keep fixtures minimal and cover regressions for bug fixes before opening a PR.

## Commit & Pull Request Guidelines

Recent history favors short, imperative subjects, often with a PR number, for example `Agents V2 (#24)` or `Fix startup crash on corrupt runnerFavorites...`. Keep commit titles specific and under a single sentence.

Pull requests should include:

- a brief problem/solution summary
- linked issue or context when available
- test coverage notes (`npm test`, `npm run test:core`, etc.)
- screenshots or terminal captures for `gui-v2` or CLI behavior changes