initi AGENTS.md

AGENTS.md

@@ -0,0 +1,57 @@
+# Development Notes for lxst-relay
+
+## Quick start
+
+```bash
+# Run as script or directly (if executable)
+python lxst_relay.py --help
+
+# Run with custom config directory
+python lxst_relay.py --config /path/to/config
+
+# Optional verbose output
+python lxst_relay.py -v --config /path/to/config
+```
+
+## Architecture
+
+- Single-file Python app (`lxst_relay.py`) using CLI argparse
+- No external dependencies beyond the script (imports RNS, LXMF from system/site)
+- Each voice channel = its own Reticulum node with persistent identity
+- Channels persisted to `${configdir}/channels/<name>/identity` and admins file
+- LXMF bot handles `/create_channel <name>` commands
+
+## Commands & arguments
+
+Common:
+- `--config, -c`  : path to config directory (defaults to `~/.lxst-relay` or `/etc/lxst-relay`)
+- `--rnsconfig`   : alternative Reticulum config directory
+- `--channel, -n` : lobby channel name (default: `"default"`)
+- `--version`      : show version and exit
+- `-v, --verbose`  : increase logging verbosity
+- `--announce_interval` : seconds between network announces (0 = once at startup)
+
+## Operations
+
+- Creating a channel: Send `/create_channel <name>` to the LXMF bot
+- Listing channels: Send `/channels` or `/channels_json` to the bot
+- Admins: Creator of each channel is its admin; admins stored in `${configdir}/channels/<name>/admins`
+- Identity: Stored in `${configdir}/identity`; regenerated if missing
+
+## Gotchas
+
+- Channel names cannot contain `/` or have adjacent directories (`..`)
+- First run creates a new RNS identity in config dir
+- Signal handlers (`SIGINT`, `SIGTERM`) properly clean up participants before exit
+- No test framework; testing done manually via calls/messages or by inspecting logs
+- Logs to RNS; use `-v` and/or `--rnsconfig` to control verbosity
+- If `--rnsconfig` unset, RNS uses system-wide location; set explicitly on first run for reproducible setups
+
+## Project layout
+
+```
+lxst_relay.py       # Main application entrypoint
+lxst-relay          # Executable wrapper (generated symlink or copy)
+.git/               # Version control only
+.gitignore          # Ignore patterns
+```