Restructure chat service, web routes, and add test suite

Split monolithic chat service into modular structure with Matrix client
support, extract web server into per-resource route modules, introduce
bootstrap/main-loop separation, and add comprehensive vitest coverage
across services, repositories, and utilities. Adds project docs and
CLAUDE.md agent instructions.

agents.md

@@ -19,16 +19,34 @@ Refactor code to improve maintainability, testability, and clarity. Break down l
 - **Zod Validation**: Use `zod` (already in deps) to validate external data (config files, API responses).
 - **Async/Await**: properly handle promises. Use `p-queue` or `p-retry` for rate-limited operations.
 
-### 4. Project Specifics
-- **Tech Stack**: Node.js, TypeScript, Playwright, Express, SQLite.
+### 4. Test-Driven Development (TDD) — REQUIRED
+All new functionality and bug fixes MUST follow the red-green-refactor cycle. This is non-negotiable.
+
+- **Red**: Write a failing test FIRST that describes the desired behavior. Run it and confirm it fails for the expected reason.
+- **Green**: Write the minimum production code needed to make the test pass. No extra features, no speculative abstractions.
+- **Refactor**: With tests green, clean up implementation and tests. Re-run the suite after each change.
+
+**Rules**:
+- Never commit production code without an accompanying test that fails without it.
+- Tests live in `tests/` (mirroring `src/` structure) and run via `vitest` (`npm test`).
+- Use dependency injection so collaborators (DB, HTTP, browser, clock) can be faked — do not mock what you don't own; wrap third-party APIs in a thin interface and fake the interface.
+- Prefer behavior-focused tests (inputs → outputs / observable side effects) over tests that pin internal structure.
+- Bug fixes start with a regression test that reproduces the bug.
+- If a change is genuinely untestable (e.g. a one-line config tweak), state that explicitly in the PR/commit rather than skipping silently.
+
+### 5. Project Specifics
+- **Tech Stack**: Node.js, TypeScript, Playwright, Express, SQLite, Vitest.
 - **Directories**: 
   - `src/services/` for business logic.
   - `src/web/` for Express server and UI.
   - `src/browser/` for Playwright interactions.
+  - `tests/` for vitest specs, mirroring `src/` layout.
 - **Logging**: Use `winston` for structured logging. Do not use `console.log` in production code.
 
 ## Workflow for Agents
 1. **Analyze**: Before writing code, read the file and understand the context.
-2. **Plan**: Identify what needs to change. Check if the change violates SRP.
-3. **Refactor**: Create new files if necessary. Don't be afraid to create new small files.
-4. **Verify**: Ensure types check out (`npm run build` or `tsc`).
+2. **Plan**: Identify what needs to change. Check if the change violates SRP. Identify the test(s) that will drive the change.
+3. **Write failing test (Red)**: Add a vitest spec that captures the new behavior or reproduces the bug. Run `npm test` and confirm it fails for the right reason.
+4. **Implement (Green)**: Write the smallest change that makes the test pass. Create new small files when SRP calls for it.
+5. **Refactor**: Tidy the implementation and the test with the suite green. Re-run tests after each refactor step.
+6. **Verify**: Ensure the full suite passes (`npm test`) and types check (`npm run build` or `tsc --noEmit`).