# Claude Code Project Instructions

## Platform Requirement: Linux Only

**CRITICAL**: This application is designed to run **exclusively on Linux**. See [ADR-014](docs/adr/0014-containerization-and-deployment-strategy.md) for full details.

### Test Execution Rules

1. **ALL tests MUST be executed on Linux** - either in the Dev Container or on a Linux host
2. **NEVER run tests directly on Windows** - test results from Windows are unreliable
3. **Always use the Dev Container for testing** when developing on Windows

### How to Run Tests Correctly

```bash
# If on Windows, first open VS Code and "Reopen in Container"
# Then run tests inside the container:
npm test           # Run all unit tests
npm run test:unit  # Run unit tests only
npm run test:integration  # Run integration tests (requires DB/Redis)
```

### Why Linux Only?

- Path separators: Code uses POSIX-style paths (`/`) which may break on Windows
- Shell scripts in `scripts/` directory are Linux-only
- External dependencies like `pdftocairo` assume Linux installation paths
- Unix-style file permissions are assumed throughout

### Test Result Interpretation

- Tests that **pass on Windows but fail on Linux** = **BROKEN tests** (must be fixed)
- Tests that **fail on Windows but pass on Linux** = **PASSING tests** (acceptable)

## Development Workflow

1. Open project in VS Code
2. Use "Reopen in Container" (Dev Containers extension required)
3. Wait for container initialization to complete
4. Run `npm test` to verify environment is working
5. Make changes and run tests inside the container

## Quick Reference

| Command                    | Description                  |
| -------------------------- | ---------------------------- |
| `npm test`                 | Run all unit tests           |
| `npm run test:unit`        | Run unit tests only          |
| `npm run test:integration` | Run integration tests        |
| `npm run dev:container`    | Start dev server (container) |
| `npm run build`            | Build for production         |