@@ -0,0 +1,79 @@
+# AGENTS.md
+
+This file provides guidance to LLM-based agents when working with code in this repository.
+
+## Project Overview
+
+This is a Ruby-based XMPP/telecommunications service (SGX JMP) that handles VoIP services, SIM management, payment processing, and Snikket XMPP server provisioning. It's built with EventMachine for async I/O, Roda for web interfaces, and integrates with Bandwidth, Braintree, and various crypto payment systems.
+
+## Architecture
+
+- **Entry Points**: `sgx_jmp.rb` (main XMPP component) and `web.rb` (HTTP interface)
+- **Core Libraries**: Located in `lib/` directory containing domain objects, repositories, and business logic
+- **Forms**: UI forms in `forms/` directory using a custom form system
+- **Database**: PostgreSQL with Sqitch migrations in `schemas/`
+- **Configuration**: Dhall-based config system (`config.dhall`, typed by `config-schema.dhall`)
+- **Tests**: Minitest-based tests in `test/` directory
+
+## Development Commands
+
+### Testing
+```bash
+bundle exec rake test # Run all tests
+bundle exec rake # Default task (runs tests)
+bundle exec ruby test/test_specific.rb # Run specific test file
+```
+
+### Linting
+```bash
+bundle exec rake lint # Run RuboCop linter
+bundle exec rubocop # Direct RuboCop invocation
+```
+
+### Development Workflow
+```bash
+bundle install --path=.gems # Install dependencies locally
+bundle exec rake entr # Auto-run tests and linting on file changes
+```
+
+### Database Setup
+```bash
+cd schemas
+sqitch deploy # Deploy database migrations
+sqitch revert # Revert migrations
+```
+
+### Configuration
+```bash
+cp config.dhall.sample config.dhall
+# Edit config.dhall for local development
+make config-schema.dhall # Generate config schema
+```
+
+### Running the Application
+```bash
+bundle exec ruby sgx_jmp.rb ./config.dhall # Start main XMPP component
+bundle exec ruby web.rb ./config.dhall # Start web interface
+```
+
+## Key Components
+
+- **Customer Management**: `Customer`, `CustomerRepo`, billing and plan management
+- **VoIP Integration**: Bandwidth SDK integration, call routing, CDR processing
+- **Payment Processing**: Braintree, crypto (BTC/BCH), PayPal integration
+- **SIM Management**: Physical and eSIM provisioning, inventory tracking
+- **Snikket Integration**: XMPP server provisioning and management
+- **Number Porting**: LNP (Local Number Portability) workflows
+
+## Database
+
+Uses PostgreSQL with Sqitch for schema management. Key tables include customers, transactions, plans, CDR (call detail records), and SIM inventory. Database migrations are in `schemas/deploy/`.
+
+## Development Notes
+
+- Uses EventMachine for async I/O - wrap blocking operations in `EM.defer`
+- Dhall configuration provides type safety for config files
+- Custom form system in `forms/` with Slim templates
+- Repository pattern for data access
+- Value objects with `value_semantics` gem
+- Redis for caching and real-time data