1 files changed, 177 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..a835822
--- /dev/null
+++ b/README.md
@@ -0,0 +1,177 @@
+# dborg - DB.org.ai CLI
+
+CLI tool for querying the DB.org.ai API services.
+
+## Project Structure
+
+```
+dborg/
+├── cmd/                    # CLI commands
+│   ├── admin.go           # Admin commands (build tag: admin)
+│   ├── npd.go             # NPD breach data search
+│   ├── root.go            # Root command configuration
+│   ├── sl.go              # Stealer logs search
+│   ├── usrsx.go           # Username availability check
+│   └── x.go               # Twitter/X username history
+├── internal/              # Private application code
+│   ├── client/            # API client implementation
+│   │   ├── admin.go       # Admin API methods
+│   │   ├── client.go      # Base HTTP client
+│   │   ├── client_test.go # Client tests
+│   │   ├── npd.go         # NPD API methods
+│   │   ├── sl.go          # Stealer logs API methods
+│   │   ├── usrsx.go       # Username check API methods
+│   │   └── x.go           # Twitter/X API methods
+│   ├── config/            # Configuration management
+│   │   ├── config.go      # Config structure
+│   │   └── errors.go      # Custom errors
+│   ├── models/            # Data models
+│   │   ├── admin.go       # Admin response types
+│   │   ├── npd.go         # NPD response types
+│   │   ├── sl.go          # Stealer logs types
+│   │   ├── usrsx.go       # Username check types
+│   │   └── x.go           # Twitter/X types
+│   └── utils/             # Utility functions
+│       └── output.go      # Output formatting helpers
+├── go.mod
+├── go.sum
+├── main.go
+├── Makefile
+└── README.md
+```
+
+## Installation
+
+```bash
+go install
+```
+
+To build with admin commands:
+
+```bash
+make build-admin
+```
+
+Or:
+
+```bash
+go build -tags admin -o dborg .
+```
+
+## Configuration
+
+Set your API key:
+
+```bash
+export DBORG_API_KEY=your_api_key_here
+```
+
+Or pass it with each command:
+
+```bash
+dborg --api-key YOUR_KEY [command]
+```
+
+## Commands
+
+### NPD - Search NPD breach data
+
+```bash
+dborg npd --firstname John --lastname Doe --max_hits 20
+```
+
+Available flags:
+- `--id`, `--firstname`, `--lastname`, `--middlename`
+- `--dob`, `--ssn`, `--phone1`
+- `--address`, `--city`, `--st`, `--zip`, `--county_name`
+- `--name_suff`, `--aka1fullname`, `--aka2fullname`, `--aka3fullname`
+- `--alt1dob`, `--alt2dob`, `--alt3dob`, `--startdat`
+- `--max_hits` (default: 10)
+- `--sort_by`
+
+### SL - Search stealer logs
+
+```bash
+dborg sl "domain.com" --max_hits 20 --format json
+```
+
+Available flags:
+- `--max_hits` (default: 10)
+- `--sort_by` (ingest_timestamp or date_posted)
+- `--ingest_start_date`, `--ingest_end_date`
+- `--posted_start_date`, `--posted_end_date`
+- `--format` (json, ulp, up, pul, etc.)
+
+### USRSX - Check username availability
+
+```bash
+dborg usrsx username123 --sites GitHub,Twitter --max_tasks 100
+```
+
+Available flags:
+- `--sites` (comma-separated list)
+- `--fuzzy` (enable fuzzy validation)
+- `--max_tasks` (default: 50)
+
+### X - Twitter/X username history
+
+```bash
+dborg x elonmusk
+```
+
+### Admin Commands (requires build tag)
+
+Only available when built with `-tags admin`:
+
+```bash
+dborg admin list
+dborg admin create john_doe --credits 1000 --unlimited
+dborg admin delete API_KEY
+dborg admin credits API_KEY 500
+dborg admin disable API_KEY
+dborg admin disable API_KEY --enable
+```
+
+## Architecture Benefits
+
+The refactored structure provides:
+
+1. **Separation of Concerns**: API logic is separated from CLI commands
+2. **Testability**: Components can be easily unit tested
+3. **Maintainability**: Clear organization makes code easier to maintain
+4. **Reusability**: Client can be reused in other Go applications
+5. **Error Handling**: Centralized error handling with custom error types
+6. **Configuration Management**: Single source of truth for configuration
+7. **Type Safety**: Strongly typed models for API requests/responses
+
+## Building
+
+Standard build (no admin commands):
+```bash
+make build
+```
+
+Build with admin commands:
+```bash
+make build-admin
+```
+
+Run tests:
+```bash
+go test ./...
+```
+
+Clean:
+```bash
+make clean
+```
+
+## Development
+
+The codebase follows Go best practices:
+
+- Internal packages for private implementation
+- Interface-based design for testability
+- Structured error handling
+- Clear separation between CLI and business logic
+- Comprehensive type definitions for API interactions