# Repository Guidelines

## Project Structure

This is an experimental TJWater Agent service. Runtime TypeScript lives in
`src/`; opencode agent assets live in `.opencode/`; tests live in `tests/`.
The project intentionally has no `cli/` directory and no user-auth middleware.

Key boundaries:

- `src/context/` owns local request context.
- `src/uiEnvelope/` owns the `agent-ui@1` protocol, registry, and tool mapping.
- `src/routes/` owns HTTP/SSE wiring.
- `src/results/`, `src/sessions/`, `src/memory/`, and `src/learning/` keep their existing persistence responsibilities.

Generated `data/`, `logs/`, and dependency folders must not be committed.

## Commands

Use Bun:

```bash
bun install
bun run dev
bun run check
bun test tests/**/*.test.ts
```

`bun run dev` starts `src/server.ts` in watch mode. `bun run check` runs
TypeScript checks for the main project and `.opencode`.

## Coding Notes

Use TypeScript ESM and keep types explicit at module boundaries. Preserve the
local service patterns before adding new abstractions. Do not reintroduce
free-form CLI command execution; future backend access should use typed tools or
adapters.

## Tests

Add focused Bun tests for route behavior, runtime/session state, result refs,
and UIEnvelope mapping. Tests must not depend on mutable files under `data/`.

## Security

This experimental service has no user authentication. Do not add secrets,
tokens, passwords, API keys, session dumps, or generated result references to
the repository.