From 4520861aa1121f18c8127abcf2b8053baea4914c Mon Sep 17 00:00:00 2001
From: Amolith <amolith@secluded.site>
Date: Fri, 19 Sep 2025 19:04:59 -0600
Subject: [PATCH] docs: add agents.md

---
 AGENTS.md | 79 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 79 insertions(+)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000000000000000000000000000000000000..3d8325e06a27c0fa000d634b607670ce85d68392
--- /dev/null
+++ b/AGENTS.md
@@ -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