Initial push

1 files changed, 264 insertions, 0 deletions

diff --git a/docs/MASTER-GUIDE.md b/docs/MASTER-GUIDE.md
new file mode 100644
index 0000000..17a395d
--- /dev/null
+++ b/docs/MASTER-GUIDE.md
@@ -0,0 +1,264 @@
+<!-- AUTO-SYNC 2026-08-01 — vault: projects/max25-stack/2026-07-13-master-documentation.md -->
+<!-- Re-sync: /home/akb/Code/0-RESEARCHES/tools/vault-sync-slave-docs.sh -->
+
+# MAX25-Stack — Master operator guide
+
+**Shipped guide** — canonical edits in research vault `projects/max25-stack/2026-07-13-master-documentation.md`; run sync script after change.
+
+## Summary
+
+Single linear guide: MAX25 layer model, `max25d`, devices (TNC, BayCom, CRDOP), M25/1 protocol, TNC recovery, FreeBSD split, HyBBX boundary. Shipped docs in `docs/` and `stacks/tncs/docs/` remain **frozen reference**.
+
+---
+
+## 1. What MAX25 is
+
+**Main AX.25 Stack (MAX25)** — standalone packet-radio stack with HyBBX-compatible plugin boundaries. Owns RF prep (boot-wait, KISS entry, BayCom kernel lifecycle, CRDOP audio). HyBBX consumes prepared devices via transport plugins.
+
+```
+max25-terminal / max25-client  (F10 menu, M25/1)
+         │
+max25d — Main + Secondaries (:7325 M25/1)
+         │
+HyBBX (external) — packet_radio | baycom | crdop
+         │
+Hardware — tnc2c | baycom-ser12 | soft-crdop
+```
+
+Frozen: `docs/ARCHITECTURE.md`, `docs/README.md`.
+
+---
+
+## 2. Host layout — Main + Secondaries
+
+| Role | Count | Function |
+|------|-------|----------|
+| **Main** | 1× | Stack hub, HyBBX attach point, M25/1 `:7325` |
+| **Secondary** | 0–5+ | Additional `max25d` instances — one RF backend each |
+
+**Linux rules (when netdev ships):**
+
+| Item | Name |
+|------|------|
+| TUN interface | **`max25d0`** only |
+| BayCom kernel netdev | **`bcsf0`** unchanged |
+
+**Example split:** FreeBSD Main (CRDOP/TCP/IP hub) + Linux Secondary (TNC/BayCom). Not mandatory — single Linux host is the primary v1 layout.
+
+Vault matrix: [2026-07-13-max25-freebsd-tnc-baycom-full-feature-matrix.md](2026-07-13-max25-freebsd-tnc-baycom-full-feature-matrix.md).
+
+---
+
+## 3. Install and site configuration
+
+```bash
+git clone <repo> MAX25-Stack && cd MAX25-Stack
+./scripts/build.sh
+sudo cmake --install build --prefix /usr/local   # or user prefix
+```
+
+| File | Purpose |
+|------|---------|
+| `~/.config/max25/max25d.ini` | Devices, TCP, auth, serial watch |
+| `share/max25/max25d.ini.example` | Template |
+| `share/hybbx/*-host.ini.example` | HyBBX attach fragments |
+
+```ini
+[devices]
+tnc2c = serial:/dev/ttyUSB0
+; soft-crdop = crdop:default
+```
+
+Frozen runbook: `docs/MAX25-OPERATOR-RUNBOOK.md`, `docs/LINUX-HOST-SETUP.md`.
+
+---
+
+## 4. Start stack — by device type
+
+### TNC (tnc2c, pktnc2)
+
+```bash
+max25-ctl start --hardware tncs --device tnc2c
+# or: stacks/tncs/tnc2c-boot-wait.sh
+```
+
+Boot-wait: DTR+RTS high during power-on (Landolt TNC2C). Software recovery ladder before power cycle.
+
+### BayCom/based (max25-bcpr userspace SER12)
+
+**Available and usable** — default build ON (`MAX25_BUILD_MAX25_BCPR=ON`). Device **`max25e0`**. KISS release **`/tmp/max25-bcpr/kiss-bc0`**.
+
+```bash
+max25-ctl start --mode hybbx-cohost    # or hybbx-host / standalone
+# max25-bcpr-ctl when running daemon directly
+```
+
+HyBBX attach: `[networks] baycom=yes` · `[transport.baycom1] device=/tmp/max25-bcpr/kiss-bc0`.
+
+SSoT: [2026-08-01-baycom-pccom-operational-status.md](../integration/2026-08-01-baycom-pccom-operational-status.md) · [cohost runbook](../integration/2026-07-31-standalone-cohost-runbook.md).
+
+Legacy kernel path (`baycom-pr` / `baycom_ser_fdx`) — removed from product; freeze notes in shipped `docs/BAYCOM-FREEZES.md` only.
+
+### CRDOP (soft modem)
+
+```bash
+max25-ctl start --hardware soft-modems --device soft-crdop
+# TCP 8515 (control) / 8516 (data)
+```
+
+Vault dev master: [2026-07-13-crdop-development-master.md](2026-07-13-crdop-development-master.md).
+
+Verify: `max25-ctl status` · `ss -ltn | grep 7325`.
+
+---
+
+## 5. M25/1 and operator terminal
+
+| Item | Value |
+|------|-------|
+| Protocol | M25/1 text commands on TCP `:7325` |
+| Client | `max25-terminal` — `SET DEVICE`, `CONNECT`, `SEND` |
+| Codec | In-tree `ax25_codec.py` — no kernel AX.25 required |
+
+Frozen: `docs/MAX25-TERMINAL.md`, `include/max25/protocol.md`.
+
+---
+
+## 6. TNC recovery (software-first)
+
+Power cycle is **rescue fallback** only when DTR was low at cold boot or hardware hang.
+
+| Situation | First action |
+|-----------|--------------|
+| Echo-only (`INFO` → `INFO`) | `tnc2c-host-reset.sh` or max25d serial watch |
+| After prep `error-host` | Auto boot-wait escalate (if enabled) |
+| Cold boot, no `cmd:` | `tnc2c-boot-wait.sh` with DTR before power-on |
+
+**Software ladder** (TheFirmware TF 2.7): KISS return → JHOST 0 → ESC V → ESC QRES → ESC `@K` → MYCALL.
+
+| Layer | Responsibility |
+|-------|----------------|
+| `max25d` / boot-wait | DTR, recovery, `kiss on`, serial watch |
+| HyBBX `packet_radio` | Attach only — `kiss_entry=none` |
+
+Vault SSoT: [2026-07-13-thefirmware-native-recovery-sequence.md](2026-07-13-thefirmware-native-recovery-sequence.md) · [hardware/tnc2c/2026-07-13-kiss-host-without-power-cycle.md](../../hardware/tnc2c/2026-07-13-kiss-host-without-power-cycle.md).
+
+max25d INI defaults: `serial_watch=yes`, `stack_recover_only=yes`, `serial_bootwait_escalate=yes`.
+
+Known failure mode (power-cycle still required): [2026-07-13-max25d-tnc-recovery-power-cycle-root-cause.md](2026-07-13-max25d-tnc-recovery-power-cycle-root-cause.md).
+
+Frozen: `MAX25-Stack/stacks/tncs/docs/TNC-RECOVERY.md`.
+
+---
+
+## 7. BayCom/based ↔ max25d
+
+```
+Radio ← UART ← max25-bcprd (userspace SER12+HDLC) ← KISS PTY /tmp/max25-bcpr/kiss-bc0 ← HyBBX baycom / max25d
+```
+
+| Fact | Value |
+|------|--------|
+| Ship status | **Available · usable** — default build ON |
+| Device id | **`max25e0`** (forks `max25e0:bcN`) |
+| HyBBX cohost | `mode=hybbx-cohost` · verified standalone Main co-host 2026-07-31 / 2026-08-01 |
+| RX before TX | Prove decode before live TX — [RX rule](../../operations/2026-07-19-rx-before-tx-rule.md) |
+
+| Use BayCom/based when | Use TNC when |
+|-----------------------|--------------|
+| PC-COM / SER12 on real 8250 UART | TNC2C, PK-TNC2, USB serial KISS |
+| max25-bcpr userspace path | Boot-wait + firmware KISS |
+
+Alias compatibility: [2026-07-13-baycom-max25d-alias-compatibility.md](2026-07-13-baycom-max25d-alias-compatibility.md).
+
+Shipped: `docs/BAYCOM.md` · vault SSoT: [2026-08-01-baycom-pccom-operational-status.md](../integration/2026-08-01-baycom-pccom-operational-status.md).
+
+---
+
+## 8. CRDOP
+
+MAX25-SoftModem (`soft-crdop`) — acoustic AX.25 over soundcard. FreeBSD uses OSS; Linux uses ALSA.
+
+| Host | CRDOP role |
+|------|------------|
+| Linux | RF backend in `max25d` |
+| FreeBSD | Primary softmodem path (no kernel BayCom/TNC in stack defaults) |
+
+**Upstream (operator · 2026-07-25):** modulation development on **T-Modem-384b** HW → **soft import** into this MAX25 soft path (**no** HW modem IC on MAX25). HyBBX boundary unchanged. SSoT: [384b identity § flow](../../operations/2026-07-25-t-modem-384b-identity.md#development-flow-operator--2026-07-25) · [CRDOP master](2026-07-13-crdop-development-master.md).
+
+Frozen: `docs/CRDOP.md`, `stacks/crdop/docs/`.
+
+---
+
+## 9. FreeBSD and platform split
+
+| Component | Linux | FreeBSD |
+|-----------|-------|---------|
+| `max25d` + RF (TNC/BayCom) | ✅ | ❌ (daemon Linux-first in v1) |
+| `max25-terminal` | ✅ | ✅ (remote to Linux `:7325`) |
+| CRDOP standalone / OSS | ALSA | OSS (DEV-Level 1 port) |
+| Kernel BayCom `bcsf0` | ✅ | ❌ |
+
+No native FreeBSD kernel AX.25 — userspace KISS/M25/1 only. Vault: [2026-07-13-max25-freebsd-tnc-baycom-full-feature-matrix.md](2026-07-13-max25-freebsd-tnc-baycom-full-feature-matrix.md).
+
+Frozen: `docs/FREEBSD-AX25.md`, `docs/PLATFORMS.md`.
+
+---
+
+## 10. HyBBX boundary
+
+**MAX25 before HyBBX.** One serial owner per port.
+
+| MAX25 owns | HyBBX owns |
+|------------|------------|
+| Boot-wait, MYCALL, `kiss on`, max25-bcpr prep, CRDOPC | `[max25] check`, KISS attach, AX.25 UI, HBX, broadcast |
+
+```bash
+max25-ctl start --hardware tncs --device tnc2c   # 1
+ss -ltn | grep 7325                               # 2
+hybbxd -c hybbx.ini                               # 3 — kiss_entry=none
+```
+
+Vault: [../integration/2026-07-12-max25-hybbx-boundary-final.md](../integration/2026-07-12-max25-hybbx-boundary-final.md).
+
+Frozen: `docs/HYBBX.md`, `docs/PACKET-RADIO.md`.
+
+---
+
+## 11. Virtual netdev (planned)
+
+TUN **`max25d0`** — IPv4 `127.0.0.25/8`, IPv6 `::25/128`. DEV-Level 1 scaffold; `[netdev] enabled=no` default.
+
+Vault analysis: [2026-07-13-max25-tcpip-virtual-netdev-hbx-analysis.md](2026-07-13-max25-tcpip-virtual-netdev-hbx-analysis.md).
+
+Frozen: `docs/NETDEV.md`.
+
+---
+
+## 12. Troubleshooting
+
+| Symptom | Check |
+|---------|-------|
+| Serial busy | One owner — stop minicom; max25d **or** HyBBX |
+| TNC silent / echo-only | Recovery ladder; DTR at boot |
+| max25d unreachable | HyBBX skips local TNC when `[max25] check=yes` |
+| BayCom KISS open failed (io) | KISS path `/tmp/max25-bcpr/kiss-bc0`; max25d `mode=hybbx-cohost`; HyBBX in `dialout` — [root-cause](../integration/2026-07-31-baycom-kiss-open-io-root-cause.md) |
+| CRDOP TCP fail | Ports 8515/8516; `crdopc` running |
+
+Release audit: [2026-07-12-max25-v1.0.0-release-audit.md](2026-07-12-max25-v1.0.0-release-audit.md).
+
+---
+
+## Related
+
+| Topic | Path |
+|-------|------|
+| FreeBSD + feature matrix SSoT | [2026-07-13-max25-freebsd-tnc-baycom-full-feature-matrix.md](2026-07-13-max25-freebsd-tnc-baycom-full-feature-matrix.md) |
+| TF native recovery SSoT | [2026-07-13-thefirmware-native-recovery-sequence.md](2026-07-13-thefirmware-native-recovery-sequence.md) |
+| max25d power-cycle root cause | [2026-07-13-max25d-tnc-recovery-power-cycle-root-cause.md](2026-07-13-max25d-tnc-recovery-power-cycle-root-cause.md) |
+| CRDOP development | [2026-07-13-crdop-development-master.md](2026-07-13-crdop-development-master.md) |
+| HyBBX integration guide | [../hybbx/2026-07-13-master-documentation.md](../hybbx/2026-07-13-master-documentation.md) |
+| Dual-TNC operator flow | [DUAL-TNC-OPERATOR-GUIDE.md](DUAL-TNC-OPERATOR-GUIDE.md) |
+| TNC2multi integration | [2026-07-14-tnc2multi-max25-integration.md](2026-07-14-tnc2multi-max25-integration.md) |
+| Linux kernel AX.25 ecosystem gap | [reference/2026-07-13-linux-kernel-ax25-ecosystem-gap.md](../../reference/2026-07-13-linux-kernel-ax25-ecosystem-gap.md) |
+| Frozen product docs | `docs/`, `stacks/tncs/docs/` |