diff --git a/lamassu-next/README.md b/lamassu-next/README.md
new file mode 100644
index 0000000..7350f37
--- /dev/null
+++ b/lamassu-next/README.md
@@ -0,0 +1,158 @@
+# Lamassu Next
+
+A Nostr-native Lightning ATM system. KYC-free, open source, auditable.
+
+## Prerequisites
+
+- [Nix](https://nixos.org/download.html) with flakes enabled
+- [devenv](https://devenv.sh/getting-started/)
+- [Docker](https://docs.docker.com/get-docker/) and Docker Compose
+
+## Quick Start
+
+```bash
+# 1. Clone the repository
+git clone ssh://forgejo@git.atitlan.io/aiolabs/lamassu-next.git
+cd lamassu-next
+
+# 2. Enter the development environment
+devenv shell
+
+# 3. Install dependencies
+pnpm install
+
+# 4. Start infrastructure (bitcoind, LND, Lightning.Pub, strfry relay)
+infra-up
+
+# 5. Fund the regtest wallet and set up Lightning channel
+mine-blocks 101
+setup-channel
+
+# 6. Validate everything is working
+test-setup
+```
+
+If `test-setup` shows all green, you're ready to develop!
+
+## Development Commands
+
+### Core
+
+| Command | Description               |
+| ------- | ------------------------- |
+| `dev`   | Start development servers |
+| `build` | Build all packages        |
+| `test`  | Run unit tests            |
+
+### Infrastructure
+
+| Command        | Description               |
+| -------------- | ------------------------- |
+| `infra-up`     | Start all Docker services |
+| `infra-down`   | Stop all Docker services  |
+| `infra-status` | Show service status       |
+| `infra-logs`   | Follow service logs       |
+
+### Bitcoin/Lightning
+
+| Command               | Description                        |
+| --------------------- | ---------------------------------- |
+| `btccli`              | Bitcoin CLI (regtest)              |
+| `lncli`               | LND CLI (Lightning.Pub's node)     |
+| `lncli-alice`         | LND CLI (Alice's node)             |
+| `mine-blocks [n]`     | Mine regtest blocks (default: 1)   |
+| `setup-channel`       | Open channel between Alice and LND |
+| `alice-pay <invoice>` | Pay invoice from Alice's node      |
+
+### Testing (E2E)
+
+| Command                | Description                      |
+| ---------------------- | -------------------------------- |
+| `test-setup`           | Validate test environment        |
+| `test-payment [sats]`  | Run e2e payment test             |
+| `fund-atm [sats]`      | Fund ATM account (default: 100k) |
+| `alice-invoice [sats]` | Create invoice on Alice's node   |
+| `node-info`            | Show node pubkeys and channels   |
+
+## Architecture
+
+```
+lamassu-next/
+├── apps/
+│   ├── machine/          # Tauri + Vue 3 ATM kiosk (planned)
+│   └── dashboard/        # Operator dashboard (planned)
+├── packages/
+│   ├── nostr-client/     # Nostr client (NIP-01, NIP-42, NIP-44)
+│   ├── clink/            # CLINK protocol (kinds 21001-21003)
+│   ├── lightning/        # Lightning.Pub RPC client
+│   ├── state-machine/    # XState v5 ATM state machine
+│   ├── cashu/            # Cashu ecash (placeholder)
+│   └── ui-shared/        # Shared Vue components (placeholder)
+└── docker/               # Development infrastructure
+```
+
+## Infrastructure Services
+
+| Service       | Container             | Port  | Description           |
+| ------------- | --------------------- | ----- | --------------------- |
+| strfry        | lamassu-relay         | 7777  | Nostr relay           |
+| bitcoind      | lamassu-bitcoind      | 18443 | Bitcoin (regtest)     |
+| LND           | lamassu-lnd           | 10009 | Lightning.Pub's node  |
+| LND Alice     | lamassu-lnd-alice     | 10010 | Test payment source   |
+| Lightning.Pub | lamassu-lightning-pub | 1776  | Nostr-native accounts |
+| PostgreSQL    | lamassu-postgres      | 5432  | Database              |
+
+## Testing E2E Payment Flow
+
+After running `test-setup`, you can test the full cash-in flow:
+
+```bash
+# Create an invoice on Alice (simulating customer wallet)
+alice-invoice 1000
+
+# Copy the invoice and test payment via Lightning.Pub
+test-payment 1000
+```
+
+## Troubleshooting
+
+If payments hang or fail, see `packages/lightning/TROUBLESHOOTING.md` for common issues and solutions.
+
+### Common Issues
+
+**Services won't start:**
+
+```bash
+infra-down
+docker system prune -f
+infra-up
+```
+
+**Channel not active:**
+
+```bash
+mine-blocks 6  # Confirm pending channels
+node-info      # Check channel status
+```
+
+**LND not synced:**
+
+```bash
+lncli getinfo  # Check synced_to_chain
+mine-blocks 1  # Trigger sync
+```
+
+## Key Concepts
+
+- **CLINK**: Protocol for Lightning payments over Nostr (kinds 21001-21003)
+- **Lightning.Pub**: Nostr-native account system wrapping LND
+- **NIP-44**: Encryption standard for private Nostr messages
+- **Kind 21000**: Lightning.Pub RPC events
+
+## Contributing
+
+See `CLAUDE.md` for development guidelines and code style.
+
+## License
+
+MIT