# Repository Guidelines

## Project Structure & Module Organization

`cmd/webterm/` contains the CLI entrypoint. Core server, session, Docker, replay, screenshot, and static-serving code lives in `webterm/`. Shared internal helpers live in `internal/`. Frontend terminal code is in `webterm/static/js/terminal.ts`, with the bundled output committed as `webterm/static/js/terminal.js`. Static assets such as fonts, icons, and WASM files live under `webterm/static/`. Documentation and reference media live in `docs/`.

## Build, Test, and Development Commands

- `make install-dev`: install Go and frontend dependencies.
- `make build`: typecheck and bundle frontend assets.
- `make build-fast`: rebuild frontend without TypeScript checking.
- `make build-go`: compile `bin/webterm`.
- `go run ./cmd/webterm`: start the server locally on `http://localhost:8080`.
- `make test`: run all Go tests.
- `make race`: run Go tests with the race detector.
- `make check`: run lint, tests, and coverage.
- `./update.sh`: rebuild, install, and restart the user service.

## Coding Style & Naming Conventions

Use `gofmt` for Go formatting; run `make format` before submitting Go-heavy changes. Follow existing Go naming: exported identifiers use `CamelCase`, internal helpers use `camelCase`, and tests live beside source files. TypeScript in `webterm/static/js/` uses strict mode, 2-space indentation, and direct DOM-oriented code rather than framework abstractions. Keep generated bundles in sync with source changes.

## Testing Guidelines

Go tests use the standard `testing` package. Name tests `TestXxx` and fuzz tests `FuzzXxx`; keep them next to the code they validate. Prefer focused unit tests for `webterm/` and `internal/` changes. Run `make test` for normal work and `make check` before opening a PR. Frontend changes should at minimum pass `bun run typecheck` via `make build`.

## Debugging Rule

Before making a second patch for the same bug, identify the exact callsite that causes the side effect. Trace the real owner of the behavior end-to-end, including library or dependency code when needed, instead of only patching app-level symptoms.

## Commit & Pull Request Guidelines

Recent history uses short imperative subjects, sometimes with prefixes such as `feat:`, `fix:`, and `deps:`. Keep commits focused, e.g. `fix: restore websocket reconnect on hidden-tab resume`. PRs should explain user-visible behavior, note test coverage, and include screenshots or recordings for terminal/UI changes. Link related issues when applicable.

## Security & Configuration Tips

By default, the service binds to port `8080`; review `~/.config/systemd/user/webterm.service` before exposing it remotely. Use HTTPS for browser microphone features. Static assets are embedded by default, but `WEBTERM_STATIC_PATH` can override them in development.