Initial commit

skills/xstate-v5/references/README.md

@@ -0,0 +1,93 @@
+# XState v5 Reference Documentation
+
+Comprehensive reference materials for XState v5 implementation and analysis in **backend applications**.
+
+## Available References
+
+### [Core API](./core-api.md)
+
+Complete API reference for XState v5 including:
+
+- Machine creation (`createMachine`, `setup`)
+- Actor management (`createActor`, lifecycle methods)
+- State configuration and transitions
+- Actions, guards, and services
+- Utility functions and type helpers
+
+### [Actors](./actors.md)
+
+Deep dive into the actor model:
+
+- Actor types (state machine, promise, callback, transition, observable)
+- Actor lifecycle and communication
+- Spawning vs invoking actors
+- Actor systems and orchestration
+- Error handling and persistence
+
+### [Common Patterns](./patterns.md)
+
+Production-ready patterns and solutions:
+
+- Loading states with retry logic
+- Form validation and submission
+- Authentication flows
+- Pagination and data fetching
+- Wizard/stepper interfaces
+- Parallel states and history
+- Debouncing and queue processing
+- Modal/dialog management
+- Connection handling with reconnection
+
+### [TypeScript Integration](./typescript.md)
+
+Complete TypeScript usage guide:
+
+- Setup pattern with strong typing
+- Type inference and helpers
+- Generic machine factories
+- Event assertions and discriminated unions
+- Backend service types
+- Migration from v4 typegen
+
+### [Testing Strategies](./testing.md)
+
+Backend testing approaches:
+
+- Unit testing state machines
+- Testing with xstate-audition
+- Mocking external services and databases
+- Testing async backend operations
+- Performance testing for server environments
+- Best practices for backend testing
+
+## Quick Start
+
+For new XState v5 implementations, start with:
+
+1. **[TypeScript Integration](./typescript.md)** - Set up proper typing
+2. **[Core API](./core-api.md)** - Learn the fundamental APIs
+3. **[Common Patterns](./patterns.md)** - Apply proven solutions
+4. **[Testing Strategies](./testing.md)** - Ensure reliability
+
+## External Resources
+
+- [Official XState Documentation](https://stately.ai/docs/xstate)
+- [XState Visualizer](https://stately.ai/viz)
+- [XState Catalog](https://xstate-catalogue.com/)
+- [xstate-audition](https://boneskull.github.io/xstate-audition/) - Model-based testing
+
+## Version Requirements
+
+- **XState**: v5.x
+- **TypeScript**: 5.0 or greater
+- **Node.js**: 18+ recommended
+
+## Contributing
+
+To add or update reference documentation:
+
+1. Follow the existing markdown structure
+2. Include practical code examples
+3. Document both best practices and anti-patterns
+4. Keep examples TypeScript-first
+5. Test all code examples for accuracy