tanstack

CLAUDE.md

@@ -0,0 +1,51 @@
+# 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         |