Initial push

1 files changed, 105 insertions, 0 deletions

diff --git a/docs/MAX25-OPERATOR-RUNBOOK.md b/docs/MAX25-OPERATOR-RUNBOOK.md
new file mode 100644
index 0000000..dd53b24
--- /dev/null
+++ b/docs/MAX25-OPERATOR-RUNBOOK.md
@@ -0,0 +1,105 @@
+# Operator runbook · MAX25-Stack
+
+Day-to-day operator procedures for max25d and RF backends.
+
+Public mark for SER12/PC-COM class: **BayCom/based**. Product path: **max25-bcpr** (available · default build ON). Never **Konverter** / **converter**.
+
+## Canonical paths
+
+| Component | Path / command |
+|-----------|----------------|
+| Daemon | **`./scripts/run-max25d.sh`** · `stacks/daemon/max25d` · `/usr/local/bin/max25d` |
+| Terminal | **`./scripts/run-max25-terminal.sh`** · `/usr/local/bin/max25-terminal` · `build*/bin/…` |
+| max25-bcpr-ctl | `stacks/max25-bcpr/tools/max25-bcpr-ctl` or `/usr/local/sbin/max25-bcpr-ctl` |
+| TX/RX test | `scripts/tx-rx-test.sh` |
+| Site INI | `/etc/max25/max25d.ini` · `/etc/max25/max25-bcpr.ini` |
+| Tree INI | `local/max25d.ini` (gitignored) |
+| KISS PTY | `/tmp/max25-bcpr/kiss-bc0` (from bcpr.ini `kiss_link`) |
+| Unix sock | `/run/max25/modem.sock` |
+
+**Never** `stacks/daemon/max25-terminal` (does not exist).  
+**Never** trust a leftover ELF at `stacks/terminal/max25-terminal` — use the launcher or PATH (`--help` must list `-d, --device`).
+
+## Daily workflow (BayCom/based · bcpr)
+
+```bash
+cd /home/akb/Code/10-PROJECTS/MAX25-Stack   # or your clone
+
+# 1) daemon (owns max25-bcprd when auto_start=yes) — needs socket dir
+sudo mkdir -p /run/max25
+sudo ./scripts/run-max25d.sh                 # uses local/max25d.ini or /etc/max25/max25d.ini
+# wait for: raw KISS open /tmp/max25-bcpr/kiss-bc0
+
+# 2) terminal (checks socket; picks binary with -d)
+./scripts/run-max25-terminal.sh -U /run/max25/modem.sock
+# CONNECT (F10→6) → SEND …
+```
+
+`connect failed` ⇒ max25d not running (no `/run/max25/modem.sock`). Start step 1 first.
+
+Manual bcpr (only when debugging without max25d):
+
+```bash
+sudo ./stacks/max25-bcpr/tools/max25-bcpr-ctl -c /etc/max25/max25-bcpr.ini preflight
+sudo ./stacks/max25-bcpr/tools/max25-bcpr-ctl -c /etc/max25/max25-bcpr.ini start
+sudo ./stacks/max25-bcpr/tools/max25-bcpr-ctl -c /etc/max25/max25-bcpr.ini status
+```
+
+## Device start matrix
+
+| Device | Command |
+|--------|---------|
+| TNC2C | `max25-ctl start --hardware tncs --device tnc2c` |
+| BayCom/based | max25d `[features] max25_bcpr=yes` · device `max25e0` — see [BAYCOM.md](BAYCOM.md) |
+| CRDOP | `max25-ctl start --hardware soft-modems --device soft-crdop` |
+
+## TX prove-out
+
+| Path | Command |
+|------|---------|
+| Unified | `sudo ./scripts/tx-rx-test.sh --device modem --live --tx --tx-seconds 3 -c /etc/max25/max25-bcpr.ini` |
+| max25-bcpr smoke | `sudo ./stacks/max25-bcpr/tools/max25-bcpr-ctl -c /etc/max25/max25-bcpr.ini smoke --live --tx --tx-seconds 3` |
+| Terminal | `./scripts/run-max25-terminal.sh -U /run/max25/modem.sock` → CONNECT → SEND |
+
+Details: [TX-RX-TEST.md](TX-RX-TEST.md).
+
+### TX path matrix (Zentralnerv)
+
+| Trigger | Host MCR (~3s) | Notes |
+|---------|----------------|-------|
+| Long KISS → `/tmp/max25-bcpr/kiss-bc0` (info ≈376B, slave held open) | Yes | Proven RF when LED/wattmeter watched |
+| `max25-bcpr-rxtx-smoke` / `tx-rx-test` L4 `--tx --tx-seconds 3` | Yes | Requires MCR `0xe`/`0xf` for PASS |
+| max25d unix/terminal `SEND` | Yes (shorter if payload ≤256B ≈2.2s) | Keep PTY open (max25d); do not recycle max25-bcprd outside max25d |
+| open/write/**close** KISS without hold | No / intermittent | POLLHUP race — fixed in max25-bcprd (POLLIN before HUP) |
+| Stale max25d FD after external max25-bcprd restart | No | Restart **max25d** only |
+
+Operator RF evidence (optional, not CI): radio **TX/PTT LED** + **external** wattmeter needle.
+
+**2026-07-19:** Operator confirmed RF on AX25WRK1 (TX LED / external wattmeter) during live prove-out.
+
+## Recovery matrix
+
+| Situation | First action |
+|-----------|--------------|
+| Echo-only TNC | `tnc2c-host-reset.sh` or serial watch |
+| After crash | boot-wait escalate if enabled |
+| Cold boot no `cmd:` | `tnc2c-boot-wait.sh` with DTR before power-on |
+| Power cycle | rescue fallback only |
+| Stale max25-bcpr KISS | restart **max25d** only (do not recycle max25-bcprd outside max25d) |
+
+## Status matrix
+
+| Check | Command |
+|-------|---------|
+| Daemon | `max25-ctl status` / `ss -ltn \| grep 7325` |
+| max25-bcpr | `sudo max25-bcpr-ctl -c /etc/max25/max25-bcpr.ini status` |
+| Logs | max25d stdout / site log path |
+
+## Related
+
+| Goal | Doc |
+|------|-----|
+| Linux setup | [LINUX-HOST-SETUP.md](LINUX-HOST-SETUP.md) |
+| Terminal | [MAX25-TERMINAL.md](MAX25-TERMINAL.md) |
+| BayCom/based | [BAYCOM.md](BAYCOM.md) |
+| TNC recovery | `stacks/tncs/docs/TNC-RECOVERY.md` |