.cursorrules

# Zoeyr Project Cursor Rules

## Communication & Testing
- Be direct, professional, and technically accurate
- **CRITICAL**: Implement unit tests and end-to-end tests instead of examples
- Unit tests first; e2e tests when unit tests don't provide sufficient coverage
- Point out conflicts with existing code
- ❌ **NEVER** create bash scripts - use testable Rust code instead

## CRITICAL Standards

### Type Safety
- ✅ Use strongly-typed enums for network serialization
- ✅ Leverage Rust's type system for compile-time error catching
- ❌ No string-based type discrimination or magic strings

### Data Structures
- ✅ Use `BTreeMap`/`BTreeSet` for all serializable structures (deterministic ordering)
- ❌ No `HashMap`/`HashSet` unless measured performance requirement

### Imports
- ✅ Top-level imports with alias renaming for conflicts (`use foo::Bar as FooBar`)
- ❌ No full-path type definitions (`foo::bar::Baz`) in function bodies
- ❌ **NEVER** add re-exports for convenience (`pub use foo::Bar`) - breaks Flutter Rust Bridge

### Serialization
- ✅ **ALWAYS** use `postcard` for serialization (`postcard::to_stdvec()`, `postcard::from_bytes()`)
- ❌ **NEVER** use `serde_json` except for human-readable config or external JSON APIs
- Use `postcard = { workspace = true }` in Cargo.toml

## Code Reuse

### CRITICAL: Always extend existing types before creating new ones
1. **Search first**: Check `app-primitives`, `wire-protocol`, `state-machine` for similar types
2. **Extend existing**: Add fields/variants to existing structs/enums when possible
3. **Only create new types when**: Explicitly requested, fundamentally different domain, or incompatible requirements

## Problem Escalation

### When to escalate to user instead of compromising:
- API evolution conflicts requiring architectural decisions
- Missing dependencies or broken toolchain
- Breaking changes to existing functionality
- Ambiguous requirements needing user preference

**Provide**: Progress summary, specific problem, attempted solutions, next steps, clean code state

## Testing & Quality

### CRITICAL: Before completion, MUST run:
1. `cargo nextest run --all` (fix all failing tests)
2. `cargo +nightly clippy --all --tests --examples --allow-dirty --allow-staged --fix`
3. Fix remaining clippy issues
4. NEVER write examples unless explicitly asked to

### Test Requirements
- Unit tests for new functions/methods/modules
- Integration tests for user-facing functionality  
- Test error paths and edge cases
- Test serialization round trips with postcard
- Descriptive test names explaining what is tested

## Documentation

### Requirements
- ✅ Write clear inline documentation (`///` doc comments) for public APIs
- ✅ Update existing READMEs when making user-facing changes
- ❌ Don't create new markdown files unless explicitly requested

---

## WORKFLOW SUMMARY
1. Search existing codebase for similar types/patterns first
2. Extend existing types/infrastructure when possible  
3. Use postcard for serialization (never serde_json)
4. Write comprehensive unit/integration tests
5. Add inline documentation for public APIs
6. Run `cargo nextest run --all` and fix failures
7. Run clippy and fix all issues
8. Update existing docs if needed