#2

20 files changed, 1061 insertions, 0 deletions

diff --git a/docs/ARDOP.md b/docs/ARDOP.md
new file mode 100644
index 0000000..8196523
--- /dev/null
+++ b/docs/ARDOP.md
@@ -0,0 +1,27 @@
+# ARDOP plugin · HyBBX 2.8.0
+
+HyBBX transport plugin for ARDOP modem paths — external modem ownership.
+
+## Status matrix
+
+| Item | Value |
+|------|-------|
+| CMake | `HYBBX_PLUGIN_ARDOP=ON` (default) |
+| INI | `[networks] ardop=yes` when modem available |
+| RF prep | External ARDOP stack — not MAX25 CRDOP |
+| Host role | Secondary typical |
+
+## Config matrix
+
+| Item | Value |
+|------|-------|
+| Transport section | `[transport.ardopN]` per instance |
+| Circuit link | `circuit_host`, `link_id`, `link_password` |
+| Protocol | ARDOP session bridge to HBX |
+
+## Related
+
+| Goal | Doc |
+|------|-----|
+| Topology | [TOPOLOGY.md](TOPOLOGY.md) |
+| CRDOP (soft modem) | [CRDOP.md](CRDOP.md) |
diff --git a/docs/BAYCOM.md b/docs/BAYCOM.md
new file mode 100644
index 0000000..14ef442
--- /dev/null
+++ b/docs/BAYCOM.md
@@ -0,0 +1,57 @@
+# BayCom/based · HyBBX
+
+Public mark: **BayCom/based**. Never **Konverter** / **converter**.
+
+**Transport plugin** (`plugins/baycom/`) for PC-COM / SER12-class hardware via MAX25. SER12 L1 (HDLC + UART modem-control) lives in **MAX25 max25-bcpr** (device **`max25e0`**) — not inside HyBBX `packet_radio`.
+
+## Status: available and usable
+
+| Item | Value |
+|------|-------|
+| Build | `HYBBX_PLUGIN_BAYCOM=ON` (**default**) |
+| Enable | `[networks] baycom=yes` + `[transport.baycom1]` |
+| Standalone Main | `[instance] standalone=yes` — local RF with TNC + BayCom on one host |
+| KISS device | **`/tmp/max25-bcpr/kiss-bc0`** (max25d releases PTY after prep) |
+| Start order | **max25d first** → `[max25] check=yes` → hybbxd |
+| INI examples | `share/hybbx-standalone.ini.example` · `share/hybbx/baycom-ser12-host.ini.example` |
+
+`packet_radio` rejects `tnc=baycom` / `tnc=pccom` (not TNC profiles). Use the **baycom** transport for PC-COM.
+
+## Minimal INI
+
+```ini
+[instance]
+standalone = yes
+
+[networks]
+ax25 = yes
+baycom = yes
+
+[transport.baycom1]
+backend = kiss
+device = /tmp/max25-bcpr/kiss-bc0
+serial_baud = 1200
+frequency_mhz = 26.675
+
+[max25]
+check = yes
+host = 127.0.0.1
+port = 7325
+```
+
+## Operator notes
+
+| Rule | Detail |
+|------|--------|
+| RX before TX | Prove decode / Soft-DCD before live TX on PC-COM |
+| Circuit | BayCom link connects to internal HBX hub (`circuit_host` / `circuit_port`) |
+| Broadcast | AX.25 auto-beacon includes baycom link when circuit QoS qualifies |
+
+## Related
+
+| Goal | Doc |
+|------|-----|
+| TNC serial (`packet_radio`) | [TNCS.md](TNCS.md) |
+| Manual | [MANUAL.md](MANUAL.md) |
+| MAX25 BayCom/based | MAX25-Stack [docs/BAYCOM.md](../MAX25-Stack/docs/BAYCOM.md) · device `max25e0` |
+| Co-host runbook | [MASTER-GUIDE.md](MASTER-GUIDE.md) |
diff --git a/docs/BUILD.md b/docs/BUILD.md
new file mode 100644
index 0000000..52d6592
--- /dev/null
+++ b/docs/BUILD.md
@@ -0,0 +1,44 @@
+# Build · HyBBX 2.8.0
+
+POSIX+ build reference. Platforms: [PLATFORMS.md](PLATFORMS.md).
+
+## Build matrix
+
+| Step | Command |
+|------|---------|
+| Release build | `cmake -B build -DCMAKE_BUILD_TYPE=Release && cmake --build build` |
+| Run | `./scripts/hybbx.sh` |
+| Test | `-DHYBBX_BUILD_TESTS=ON` → `ctest --test-dir build` |
+| Telnet smoke | `telnet 127.0.0.1 2323` |
+| SSH smoke | `ssh 127.0.0.1 -p 3232` |
+
+## CMake options matrix
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `HYBBX_BUILD_DAEMON` | ON | `hybbxd` + core |
+| `HYBBX_BUILD_CLIENTS` | ON | CLI clients |
+| `HYBBX_PLUGIN_PACKET_RADIO` | ON | Packet radio |
+| `HYBBX_PLUGIN_BAYCOM` | ON | BayCom plugin (v2.8.0 built; runtime off) |
+| `HYBBX_PLUGIN_MAINS_PROXY` | OFF | Main-to-Main mesh proxy |
+| `HYBBX_PLUGIN_ARDOP` | ON | ARDOP plugin |
+| `HYBBX_PLUGIN_CRDOP` | ON | CRDOP plugin |
+| `HYBBX_PLUGIN_SSH` | ON | SSH (libssh) |
+| `HYBBX_PLUGIN_WEBSOCKET` | ON | WebSocket proxy |
+| `HYBBX_BUILD_TESTS` | OFF | Unit tests |
+| `HYBBX_STORAGE_SQLITE` | ON | SQLite backend |
+
+## Config matrix
+
+| Item | Value |
+|------|-------|
+| Live INI | `./local/hybbx.ini` (gitignored) |
+| Templates | `share/hybbx-*.ini.example` |
+| Secrets | `./local/` only — never commit |
+
+## Related
+
+| Goal | Doc |
+|------|-----|
+| Platforms | [PLATFORMS.md](PLATFORMS.md) |
+| Developer | [DEVELOPMENT.md](DEVELOPMENT.md) |
diff --git a/docs/CLIENTS.md b/docs/CLIENTS.md
new file mode 100644
index 0000000..476afc6
--- /dev/null
+++ b/docs/CLIENTS.md
@@ -0,0 +1,28 @@
+# Clients · HyBBX 2.8.0
+
+User-facing connection clients for HyBBX sessions.
+
+## Client matrix
+
+| Client | Transport | Default port |
+|--------|-----------|--------------|
+| `hybbx-telnet` | TCP telnet | 2323 |
+| `hybbx-ssh` | SSH (libssh) | 3232 |
+| `hybbx-terminal` | HBX circuit | 7323 |
+| Web browser | WebSocket via reverse proxy | site-specific |
+
+## Session matrix
+
+| Item | Value |
+|------|-------|
+| Wire format | Plain text lines + `/` commands |
+| ANSI | `[traffic] ansi=yes` optional |
+| Guest login | `[service] auto_login=yes` |
+| Registered users | `/login` after connect |
+
+## Related
+
+| Goal | Doc |
+|------|-----|
+| WebSocket setup | [WEBSOCKET.md](WEBSOCKET.md) |
+| Manual | [MANUAL.md](MANUAL.md) |
diff --git a/docs/COMMANDS.md b/docs/COMMANDS.md
new file mode 100644
index 0000000..bb664e7
--- /dev/null
+++ b/docs/COMMANDS.md
@@ -0,0 +1,36 @@
+# Commands · HyBBX 2.8.0
+
+Slash-command reference — five access levels: Sysop → Admin → Mod → User → Guest.
+
+## Level matrix
+
+| Level | Typical commands |
+|-------|------------------|
+| Sysop | `/broadcast`, `/broadcast ax25`, `/shutdown` |
+| Admin | `/usercreate`, `/activate`, `/promote`, `/demote` |
+| Mod | moderation subset |
+| User | `/mail`, `/chat`, `/who` |
+| Guest | `/help`, `/menu` (filtered) |
+
+## RF command matrix
+
+| Command | Scope | Level |
+|---------|-------|-------|
+| `/broadcast <msg>` | Local online users | Sysop |
+| `/broadcast ax25` | Sequential RF beacon | Sysop |
+
+## Registry matrix
+
+| Item | Path |
+|------|------|
+| Command definitions | `share/commands.yaml` |
+| Area definitions | `share/areas.yaml` |
+| `/index` | Lists all commands (every account) |
+| `/who` (v2.8.0) | Interactive users only — not RF sessions |
+
+## Related
+
+| Goal | Doc |
+|------|-----|
+| Manual | [MANUAL.md](MANUAL.md) |
+| Security | [SECURITY.md](SECURITY.md) |
diff --git a/docs/CRDOP.md b/docs/CRDOP.md
new file mode 100644
index 0000000..0eb333e
--- /dev/null
+++ b/docs/CRDOP.md
@@ -0,0 +1,35 @@
+# CRDOP plugin · HyBBX 2.8.0
+
+HyBBX transport for MAX25-SoftModem (CRDOP) — acoustic AX.25 over soundcard.
+
+## Integration matrix
+
+| Layer | Owner |
+|-------|-------|
+| Soft-modem prep, TCP 8515/8516 | MAX25 `soft-crdop` |
+| HyBBX transport | `crdop` plugin |
+| INI merge | `share/hybbx/crdop-host.ini.example` |
+
+## Config matrix
+
+| Item | Value |
+|------|-------|
+| Enable | `[networks] crdop=yes` |
+| CMake | `HYBBX_PLUGIN_CRDOP=ON` (default) |
+| `modem_host` | MAX25 host (loopback or LAN) |
+| `modem_port` | `8515` (control) |
+
+## Start order matrix
+
+| # | Action |
+|---|--------|
+| 1 | `max25-ctl start --hardware soft-modems --device soft-crdop` |
+| 2 | Merge CRDOP host INI fragment |
+| 3 | Start HyBBX with `[networks] crdop=yes` |
+
+## Related
+
+| Goal | Doc |
+|------|-----|
+| MAX25 CRDOP | MAX25-Stack `docs/CRDOP.md` |
+| Manual | [MANUAL.md](MANUAL.md) |
diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md
new file mode 100644
index 0000000..c7a8182
--- /dev/null
+++ b/docs/DEVELOPMENT.md
@@ -0,0 +1,37 @@
+# Development · HyBBX 2.8.0
+
+Contributor build, test, and code layout reference.
+
+## Workflow matrix
+
+| Step | Command |
+|------|---------|
+| Debug build | `cmake -B build -DCMAKE_BUILD_TYPE=Debug && cmake --build build` |
+| Tests | `-DHYBBX_BUILD_TESTS=ON && ctest --test-dir build` |
+| Clients only | `-DHYBBX_CLIENTS_ONLY=ON` |
+| Format / lint | project scripts in `scripts/` |
+
+## Layout matrix
+
+| Path | Content |
+|------|---------|
+| `src/` | Daemon core |
+| `plugins/` | Transport plugins |
+| `include/hybbx/` | Public headers |
+| `share/` | INI templates, YAML registries |
+| `tests/` | Unit tests (opt-in build) |
+
+## v2.8.0 dev notes matrix
+
+| Topic | Rule |
+|-------|------|
+| MAX25 boundary | No BayCom/PC-COM in `packet_radio` |
+| Local TNC tests | Mock max25d `:7325` recommended |
+| Live secrets | `./local/` only |
+
+## Related
+
+| Goal | Doc |
+|------|-----|
+| Build | [BUILD.md](BUILD.md) |
+| Contributing | [../CONTRIBUTING.md](../CONTRIBUTING.md) |
diff --git a/docs/DUAL-TNC-OPERATOR-GUIDE.md b/docs/DUAL-TNC-OPERATOR-GUIDE.md
new file mode 100644
index 0000000..421a183
--- /dev/null
+++ b/docs/DUAL-TNC-OPERATOR-GUIDE.md
@@ -0,0 +1,179 @@
+<!-- AUTO-SYNC 2026-08-01 — vault: projects/integration/2026-07-13-master-operator-guide.md -->
+<!-- Re-sync: /home/akb/Code/0-RESEARCHES/tools/vault-sync-slave-docs.sh -->
+
+# Dual-TNC operator guide · HyBBX
+
+**Shipped guide** — canonical edits in research vault `projects/integration/2026-07-13-master-operator-guide.md`; run sync script after change.
+
+## Summary
+
+Linear operator sequence for a **standalone Main** host with **one or two local TNCs** (dual-TNC pattern): MAX25 prep first, HyBBX second, RF verification last. Applies to any dual-TNC reference station — adjust device paths and INI per site.
+
+---
+
+## 1. Scope
+
+| In scope | Out of scope |
+|----------|--------------|
+| Single-host standalone Main + local `packet_radio` | Remote Secondary + Main split (see HyBBX TOPOLOGY) |
+| TNC2C / PK-TNC2 class (TheFirmware) | BayCom-only or CRDOP-only sites (see MAX25 master) |
+| MAX25 prep → HyBBX → `/broadcast ax25` | mains_proxy mesh |
+
+Boundary SSoT: [2026-07-12-max25-hybbx-boundary-final.md](2026-07-12-max25-hybbx-boundary-final.md).
+
+---
+
+## 2. Responsibility split
+
+| Phase | MAX25 | HyBBX |
+|-------|-------|-------|
+| TNC cold boot (DTR+RTS at power-on) | `tnc2c-boot-wait.sh` / max25d | — |
+| Host MYCALL, TXDELAY, `kiss on` | max25d or boot-wait | — |
+| Serial port ownership in operation | max25d (optional) **or** HyBBX after prep | Opens `/dev/ttyS*` after prep |
+| max25d TCP probe | Listens `:7325` | `[max25] check=yes` |
+| KISS DATA / UI frames / PTT path | — | `packet_radio` plugin |
+| User sessions, `/broadcast ax25` | — | Main + HBX loopback |
+
+**One process per `/dev/tty*`** — never minicom + boot-wait + HyBBX concurrently.
+
+---
+
+## 3. Pre-flight checklist
+
+| # | Check | Pass criterion |
+|---|-------|----------------|
+| 1 | MAX25 scripts installed | `MAX25-Stack/stacks/tncs/tnc2c-boot-wait.sh` executable |
+| 2 | HyBBX built with `packet_radio` | `hybbxd` starts, plugin loads |
+| 3 | INI merged | Vault template: `share/` INI examples |
+| 4 | `[broadcast] ax25_mycall` set | Valid callsign for on-air source |
+| 5 | `kiss_entry=none` on each `[transport.packet_radioN]` | MAX25 owns KISS entry |
+| 6 | Unique `link_id` per transport | Matches circuit bridge registry |
+| 7 | Radio wired, antenna safe | Bench or low-power test first |
+| 8 | Radio squelch profile | **Primary:** SQ **on** (manual/ASQ) while local DCD/decode OK; open SQ only if needed; fringe/DX → Secondary or second Main — RFG/FMQ **off**; SSoT: [../../hardware/radio-equipment/2026-07-14-packet-radio-squelch-rfg-profiles.md](../../hardware/radio-equipment/2026-07-14-packet-radio-squelch-rfg-profiles.md) |
+
+Extended checklist: [2026-07-12-max25-tnc-prep-check.md](2026-07-12-max25-tnc-prep-check.md).
+
+---
+
+## 4. Linear start sequence
+
+### Step A — Stop conflicting owners
+
+```bash
+pkill hybbxd || true
+# ensure no minicom/screen on /dev/ttyS4 / ttyS5
+```
+
+### Step B — MAX25 TNC prep (per port)
+
+For each TNC (example ports — replace per site):
+
+```bash
+cd /path/to/MAX25-Stack/stacks/tncs
+
+# TNC unit A (cold boot or stuck host)
+./tnc2c-boot-wait.sh --device /dev/ttyS4 --recover-only
+# or full boot-wait with power cycle if DTR was low at cold start
+
+# TNC unit B (PK-TNC2)
+./pktnc2-boot-wait.sh --device /dev/ttyS5 --recover-only
+```
+
+**Optional:** start `max25d` instead of one-shot scripts — enables serial watch and M25/1:
+
+```bash
+max25-ctl start --hardware tncs --device tnc2c
+ss -ltn | grep 7325    # expect LISTEN on 7325
+```
+
+Note: one `max25d` instance = one RF backend in v1; dual-TNC sites often use **scripts per port** then HyBBX as serial owner. See vault prep check for dual-TNC pattern.
+
+### Step C — Verify MAX25 reachability
+
+```bash
+nc -zv 127.0.0.1 7325    # when max25d running
+# or: confirm boot-wait log shows TheFirmware banner + KISS ready
+```
+
+### Step D — Start HyBBX
+
+```bash
+hybbxd -c /path/to/hybbx.ini
+# or: hybbx-start
+```
+
+**Expected log sequence:**
+
+1. `max25d reachable` (if `[max25] check=yes`)
+2. `KISS attach (MAX25 prep assumed)` per `[transport.packet_radioN]`
+3. Circuit hub listening `:7323`
+
+### Step E — RF verification
+
+| Test | Command / action | Pass |
+|------|------------------|------|
+| Local user session | `hybbx-telnet -H 127.0.0.1` | Login OK |
+| Manual RF beacon | `/broadcast ax25` (Sysop) | Log `RF TX`; PTT at radio |
+| On-air decode | Remote monitor or second radio | AX.25 UI frame with `ax25_mycall` |
+| Dual link gap | Two transports configured | ~60 s between links (sequential) |
+
+RF debug timeline: [../hybbx/2026-07-12-site-rf-broadcast-investigation.md](../hybbx/2026-07-12-site-rf-broadcast-investigation.md).
+
+---
+
+## 5. INI pointers (dual local TNC)
+
+Site INI: merge `share/` examples per deployment.
+
+| Section | Keys to verify |
+|---------|----------------|
+| `[networks]` | `circuit=yes`, `ax25=yes` |
+| `[transport.circuit]` | `port=7323`, `max_links` ≥ transport count |
+| `[transport.packet_radio1]` | `device`, `tnc`, `link_id`, `link_password`, `kiss_entry=none`, `persist=255` |
+| `[transport.packet_radio2]` | same pattern — different `device`, `link_id` |
+| `[broadcast]` | `ax25_mycall`, `ax25_auto_message`, `ax25_dest` |
+| `[max25]` | `check=yes`, `host=127.0.0.1`, `port=7325` |
+
+HyBBX shipped templates: `hyBBX/share/hybbx-standalone.ini.example`.
+
+---
+
+## 6. Recovery without full host reboot
+
+| Symptom | Action |
+|---------|--------|
+| Echo-only on one TNC | Stop HyBBX → `--recover-only` on that port → restart HyBBX |
+| max25d `error-host` | Serial watch auto-repair; or manual `tnc2c-host-reset.sh --kiss` |
+| No PTT, log shows `RF TX` | Check FCS strip, `persist=255`, MYCALL prep — vault RF investigation |
+| Stuck after HyBBX crash | KISS return frame before re-prep; do not skip MAX25 step |
+
+Runbook: [operations/runbooks/tnc-recovery-without-power-cycle.md](../../operations/runbooks/tnc-recovery-without-power-cycle.md).
+
+---
+
+## 7. Reboot order (reference station)
+
+After host power cycle:
+
+1. **Physical:** TNC power with DTR high (boot-wait script running **before** or **during** TNC power-on)
+2. **MAX25:** boot-wait per TNC (mandatory for TNC2C cold boot)
+3. **HyBBX:** start immediately after successful prep (HyBBX re-asserts RTS/DTR)
+4. **Verify:** `/broadcast ax25` within 5 min of uptime
+
+Do **not** start HyBBX before TNC host mode is confirmed — HyBBX cannot recover Landolt cold-boot without DTR sequencing.
+
+---
+
+## Related
+
+| Topic | Path |
+|-------|------|
+| MAX25 ↔ HyBBX boundary | [2026-07-12-max25-hybbx-boundary-final.md](2026-07-12-max25-hybbx-boundary-final.md) |
+| TNC prep checklist | [2026-07-12-max25-tnc-prep-check.md](2026-07-12-max25-tnc-prep-check.md) |
+| HyBBX master guide | [../hybbx/2026-07-13-master-documentation.md](../hybbx/2026-07-13-master-documentation.md) |
+| MAX25 master guide | [../max25-stack/2026-07-13-master-documentation.md](../max25-stack/2026-07-13-master-documentation.md) |
+| RF investigation | [../hybbx/2026-07-12-site-rf-broadcast-investigation.md](../hybbx/2026-07-12-site-rf-broadcast-investigation.md) |
+| Production INI | `share/` INI examples |
+| TNC recovery runbook | [operations/runbooks/tnc-recovery-without-power-cycle.md](../../operations/runbooks/tnc-recovery-without-power-cycle.md) |
+| TNC2multi 1200/9600 (Amateurfunk) | [hardware/tnc2multi/2026-07-14-tnc2multi-modulation-1200-9600.md](../../hardware/tnc2multi/2026-07-14-tnc2multi-modulation-1200-9600.md) |
+| Packet Squelch/RFG (Primary/Secondary) | [hardware/radio-equipment/2026-07-14-packet-radio-squelch-rfg-profiles.md](../../hardware/radio-equipment/2026-07-14-packet-radio-squelch-rfg-profiles.md) |
diff --git a/docs/ENTERTAIN.md b/docs/ENTERTAIN.md
new file mode 100644
index 0000000..cbdec78
--- /dev/null
+++ b/docs/ENTERTAIN.md
@@ -0,0 +1,25 @@
+# Entertain Area · HyBBX 2.8.0
+
+Optional Main-only plugins for games and apps — not on Secondary RF hosts.
+
+## Plugin matrix
+
+| Plugin | Status | Notes |
+|--------|--------|-------|
+| Entertain Area framework | opt-in CMake | Main hosts only |
+| Chess / games | deferred | future or doc removal |
+
+## Config matrix
+
+| Item | Value |
+|------|-------|
+| Enable | `-DHYBBX_PLUGIN_ENTERTAIN=ON` (when available) |
+| Host role | Main only — Secondary runs RF transports |
+| User access | Level-gated via `[areas]` / `share/areas.yaml` |
+
+## Related
+
+| Goal | Doc |
+|------|-----|
+| Topology | [TOPOLOGY.md](TOPOLOGY.md) |
+| Commands | [COMMANDS.md](COMMANDS.md) |
diff --git a/docs/LICENSING.md b/docs/LICENSING.md
new file mode 100644
index 0000000..662505f
--- /dev/null
+++ b/docs/LICENSING.md
@@ -0,0 +1,26 @@
+# Licensing · HyBBX 2.8.0
+
+HyBBX and shipped components — license reference.
+
+## License matrix
+
+| Component | License |
+|-----------|---------|
+| HyBBX core + plugins | GPL-3.0 — [LICENSE.txt](../LICENSE.txt) |
+| Bundled crypto (tinysha256, tinyaes, monocypher) | respective upstream licenses |
+| Optional OpenSSL / libsodium | upstream licenses when enabled |
+
+## Distribution matrix
+
+| Item | Rule |
+|------|------|
+| Source offer | GPL-3.0 compliance required for derivatives |
+| Operator config | `./local/` — not part of distribution |
+| Third-party deps | Document in build output / package metadata |
+
+## Related
+
+| Goal | Doc |
+|------|-----|
+| Build options | [BUILD.md](BUILD.md) |
+| Root README | [../README.md](../README.md) |
diff --git a/docs/MAINS_PROXY.md b/docs/MAINS_PROXY.md
new file mode 100644
index 0000000..7573cbe
--- /dev/null
+++ b/docs/MAINS_PROXY.md
@@ -0,0 +1,37 @@
+# mains_proxy · HyBBX 2.8.0
+
+Opt-in mesh linking Main or Secondary instances for `/proxymail` and `/proxychat`.
+
+## Feature matrix
+
+| Feature | Supported |
+|---------|-----------|
+| `/proxymail` cross-site | yes |
+| `/proxychat` cross-site | yes |
+| User account sync | no |
+| Sysop actions over proxy | no |
+| Raw Main-to-Main TCP bypass | no — HBX/Circuit only |
+
+## Build matrix
+
+| Item | Value |
+|------|-------|
+| CMake | `-DHYBBX_PLUGIN_MAINS_PROXY=ON` |
+| INI | `[networks] mains_proxy=yes` |
+| Template | `share/hybbx-mesh.ini.example` |
+| Auth | Same as Secondary — `link_id`, `link_password` |
+
+## Topology matrix
+
+| Peer A | Peer B | Transport |
+|--------|--------|-----------|
+| Main | Main | HBX circuit client |
+| Main | Secondary | HBX circuit client |
+| Secondary | Secondary | via Main hub (typical) |
+
+## Related
+
+| Goal | Doc |
+|------|-----|
+| Topology | [TOPOLOGY.md](TOPOLOGY.md) |
+| Manual | [MANUAL.md](MANUAL.md) |
diff --git a/docs/MANUAL.md b/docs/MANUAL.md
new file mode 100644
index 0000000..699e638
--- /dev/null
+++ b/docs/MANUAL.md
@@ -0,0 +1,63 @@
+# Operator manual · HyBBX 2.8.0
+
+Telnet, SSH, WebSocket operator reference. INI templates in `share/` — copy to `./local/hybbx.ini`.
+
+## Template matrix
+
+| Template | Use |
+|----------|-----|
+| `hybbx-standalone.ini.example` | Main + local TNC (one host) |
+| `hybbx-main.ini.example` | Main; RF on remote Secondary |
+| `hybbx-mesh.ini.example` | Main + `mains_proxy` mesh |
+| `hybbx-secondary.ini.example` | Secondary RF host |
+
+## Topology matrix
+
+| Role | `[networks]` typical | Hosts |
+|------|----------------------|-------|
+| **Main** | `circuit=yes`, `ax25=no` | Users, HBX hub |
+| **Secondary** | `circuit=no`, `ax25=yes` | TNC/RF; `circuit_host` → Main |
+| **Standalone Main** | `ax25=yes` on same box | Lab / single-host |
+
+## Core INI sections matrix
+
+| Section | Key keys |
+|---------|----------|
+| `[service]` | `name`, `max_online`, `prompt` |
+| `[storage]` | `backend=flatfile\|sqlite` |
+| `[networks]` | `ax25`, `baycom`, `crdop`, `circuit`, `ssh`, `websocket` |
+| `[transport.telnet]` | `bind`, `port=2323` |
+| `[transport.circuit]` | `port=7323`, `max_links` |
+| `[transport.packet_radioN]` | `device`, `tnc`, `protocol=kiss`, `kiss_entry=none` |
+| `[broadcast]` | `ax25_mycall`, `ax25_auto_message`, `ax25_dest` |
+| `[max25]` | `check=yes`, `host`, `port=7325` |
+| `[security]` | `bantime`, `maxretry`, `ban_backend` |
+
+## v2.8.0 RF keys matrix
+
+| Key | Value | Notes |
+|-----|-------|-------|
+| `kiss_entry` | `none` | MAX25 owns KISS entry |
+| `kiss_exit` | `none` | No `kiss off` on shutdown |
+| `[max25] check` | `yes` | Local TNC start fails if max25d down |
+
+## BayCom/based (via MAX25)
+
+Built by default. Enable `[networks] baycom=yes`; KISS device **`/tmp/max25-bcpr/kiss-bc0`**. Standalone template: `share/hybbx-standalone.ini.example`. Start max25d before HyBBX; prove RX before live TX. Full detail: [BAYCOM.md](BAYCOM.md).
+
+## Daemon matrix
+
+| Item | Value |
+|------|-------|
+| Binary | `hybbxd` |
+| Start | `hybbx-start` or `hybbxd -c hybbx.ini` |
+| Detached | `hybbx-start --screen` / `--tmux` |
+| First start | Sysop created with random password on console |
+
+## Related
+
+| Goal | Doc |
+|------|-----|
+| Topology | [TOPOLOGY.md](TOPOLOGY.md) |
+| Security | [SECURITY.md](SECURITY.md) |
+| Build | [BUILD.md](BUILD.md) |
diff --git a/docs/MASTER-GUIDE.md b/docs/MASTER-GUIDE.md
new file mode 100644
index 0000000..53895af
--- /dev/null
+++ b/docs/MASTER-GUIDE.md
@@ -0,0 +1,211 @@
+<!-- AUTO-SYNC 2026-08-01 — vault: projects/hybbx/2026-07-13-master-documentation.md -->
+<!-- Re-sync: /home/akb/Code/0-RESEARCHES/tools/vault-sync-slave-docs.sh -->
+
+# HyBBX — Master operator guide
+
+**Shipped guide** — canonical edits in research vault `projects/hybbx/2026-07-13-master-documentation.md`; run sync script after change.
+
+## Summary
+
+Single linear guide: what HyBBX is, how to install and configure it, attach RF via MAX25 prep, run clients and commands. Shipped product docs in `docs/` remain **frozen reference** — depth investigations live.
+
+---
+
+## 1. Role and architecture
+
+HyBBX (**hyBBX** — hybrid Mailbox build System X) is a **plannable (hy)BBX network system**: closed and self-contained BBX networking; the Internet is used primarily for interconnection and logical work; Internet and external services are fully extensible via **plugins** ([§0.17](../../AGENT-INDEX.md#017-hybbx-product-positioning-static-rule)).
+
+Technically: a **text-first BBX/mail/chat** daemon (`hybbxd`) with optional RF transports. Users connect via telnet (`:2323`), SSH (`:3232`), or WebSocket proxy. RF paths use transport plugins that bridge serial/KISS or kernel modems to **HBX** (Hybrid Bridge eXchange) on the circuit hub (`:7323`).
+
+```
+Users (telnet/SSH/WebSocket) ──► Main (storage, mail, HBX hub :7323)
+                                        ▲
+                                        │ HBX/TCP
+                                   Secondary (packet_radio / baycom / crdop)
+                                        │
+                                   TNC / modem (after MAX25 prep)
+```
+
+| Role | `[networks]` | Hosts |
+|------|--------------|-------|
+| **Main** | `circuit=yes`, `ax25=no` (typical) | Users, HBX hub |
+| **Secondary** | `circuit=no`, `ax25=yes` | RF near TNC; `circuit_host` → Main |
+| **Standalone Main** | `ax25=yes` on same box | Lab / single-host (e.g. dual local TNC) |
+
+**HBX/Circuit** — sole inter-node transport. Application core never sees raw KISS or on-air AX.25; only typed HBX frames on TCP.
+
+Frozen reference: `docs/TOPOLOGY.md`, `docs/MANUAL.md`.
+
+---
+
+## 2. Install and build
+
+| Step | Action |
+|------|--------|
+| Build | `hyBBX/scripts/build.sh` or CMake per `docs/BUILD.md` |
+| Binary | `hybbxd` — start via `hybbx-start` or `hybbxd -c hybbx.ini` |
+| Detached | `hybbx-start --screen` / `--tmux`; attach: `hybbxd --screen --attach` |
+| INI templates | `hyBBX/share/hybbx-standalone.ini.example`, `hybbx-main.ini.example`, `hybbx-secondary.ini.example`, `hybbx-mesh.ini.example` |
+
+First start creates Sysop in `users/users.ini` with a one-time random password on the console.
+
+---
+
+## 3. INI — operator essentials
+
+Full key tables: frozen `docs/MANUAL.md`. Vault INI copy (reference station): `share/` INI examples.
+
+### Core sections
+
+| Section | Purpose |
+|---------|---------|
+| `[service]` | Name, session limit, prompt |
+| `[storage]` | `flatfile` or `sqlite`; user shards under `users/` |
+| `[networks]` | Enable plugins: `ax25`, `baycom`, `crdop`, `circuit`, `ssh`, `websocket` |
+| `[transport.telnet]` | Bind, port `2323` |
+| `[transport.circuit]` | HBX hub port `7323`, `max_links` (default 8, max 16) |
+| `[transport.packet_radioN]` | TNC instance — device, `tnc=` profile, `protocol=kiss` |
+| `[broadcast]` | `ax25_mycall`, `ax25_auto_message`, `ax25_dest` |
+| `[max25]` | `check=yes` — probe max25d TCP `:7325` before local serial open |
+
+### RF on Main vs Secondary
+
+| Layout | TNC keys on Main `[transport.packet_radioN]` |
+|--------|-----------------------------------------------|
+| Remote Secondary | Bridge registry only (`link_id`, password) — no `device` |
+| Local TNC (standalone) | Full keys: `device`, `tnc`, `baud`, `serial_line`, `rts_dtr` |
+
+Bridge-registry rows without `device` are skipped at start (no serial open).
+
+---
+
+## 4. TNC attach (MAX25 contract) — v2.8.0
+
+**Order:** MAX25 prep **before** HyBBX for local serial TNC. One process per `/dev/tty*`. HyBBX **attach-only** on KISS (`kiss_entry=none` after max25d prep).
+
+| Layer | Owner | Action |
+|-------|-------|--------|
+| Boot-wait, DTR/RTS, MYCALL, `kiss on` | MAX25 | `max25-ctl start --hardware tncs` or `tnc2c-boot-wait.sh` |
+| max25d reachability | HyBBX `[max25] check=yes` | TCP `:7325` — **required** for local TNC (start fails if down) |
+| KISS attach | HyBBX `packet_radio` | `kiss_entry=none` (default with MAX25) |
+| AX.25 UI build, HBX bridge, broadcast | HyBBX | `broadcast.c`, `packet_radio.c`, `tnc.c` |
+| BayCom/based plugin | HyBBX | Built by default; `[networks] baycom=yes` when RF used — [operational status](../integration/2026-08-01-baycom-pccom-operational-status.md) |
+
+HyBBX builds outbound UI frames from `[broadcast] ax25_mycall` — it does **not** send host `MYCALL` to the TNC (MAX25 does that at prep).
+
+| INI key | Production value | Notes |
+|---------|------------------|-------|
+| `kiss_entry` | `none` | TNC already in KISS after MAX25 |
+| `kiss_exit` | `none` | Shutdown does not send `kiss off` |
+| `persist` | `255` on CB | CSMA — avoid random defer on busy channel |
+| `protocol` | `kiss` | Required for Secondary RF |
+| `[max25] check` | `yes` | Local serial edges only |
+
+TNC profiles in `packet_radio`: `tnc2c`, `tnc2`, `pk232`, … — see shipped `docs/TNCS.md`. BayCom/based transport: **built by default**, **available and usable** — enable `[networks] baycom=yes`; KISS **`/tmp/max25-bcpr/kiss-bc0`**; standalone/co-host verified 2026-07-31 / 2026-08-01.
+
+Release prep: [2026-07-14-v2.8.0-release-prep.md](2026-07-14-v2.8.0-release-prep.md).
+
+Recovery without power cycle: internal research note) · MAX25 `stacks/tncs/docs/TNC-RECOVERY.md`.
+
+---
+
+## 5. RF, broadcast, and HBX
+
+### Auto-beacon and manual broadcast
+
+| Command | Scope | Sysop |
+|---------|-------|-------|
+| `/broadcast <msg>` | Local logged-in users (telnet/SSH/WebSocket) | yes |
+| `/broadcast ax25` | Sequential RF beacon per link (`ax25_auto_message`; 60 s gap) | yes |
+
+RF path: Main → HBX → Secondary link → KISS → TNC → on-air.
+
+### Standalone Main production facts
+
+Dual local TNC + optional BayCom on one host — shipped: [BAYCOM.md](BAYCOM.md) · [DUAL-TNC-OPERATOR-GUIDE.md](DUAL-TNC-OPERATOR-GUIDE.md). Vault depth: [co-host runbook](../integration/2026-07-31-standalone-cohost-runbook.md) · [BayCom operational status](../integration/2026-08-01-baycom-pccom-operational-status.md).
+
+| Issue class | Vault SSoT fix |
+|-------------|----------------|
+| No PTT despite `RF TX` log | FCS strip, MYCALL before KISS, UNPROTO path, `persist=255` |
+| Circuit queue dropped beacons | Bypass low-prio queue for AX.25 broadcast TX |
+| `ax25_dest=*` invalid | Map to `QST` |
+| TNC stuck after crash | KISS return frame `0xC0 0xFF 0xC0` before prep |
+
+### BayCom and CRDOP plugins
+
+| MAX25 hardware | HyBBX plugin | INI |
+|----------------|--------------|-----|
+| `hardware/modems` | `baycom` | `[networks] baycom=yes` — merge `share/hybbx/baycom-ser12-host.ini.example` |
+| **BayCom/based** (max25-bcpr via MAX25) | available · default build | Standalone Main or co-host (TNC + PC-COM); KISS `/tmp/max25-bcpr/kiss-bc0` — [plugin](2026-07-18-baycom-based-plugin-via-max25.md) · [operational status](../integration/2026-08-01-baycom-pccom-operational-status.md) |
+| `hardware/soft-modems` | `crdop` | `[networks] crdop=yes` — merge `share/hybbx/crdop-host.ini.example` |
+
+Frozen: `docs/BAYCOM.md`, `docs/CRDOP.md` · MAX25 contract: `docs/HYBBX.md`. Public mark for SER12 class: **BayCom/based** (never Konverter/converter).
+
+---
+
+## 6. Clients
+
+| Client | Transport | Default port |
+|--------|-----------|--------------|
+| `hybbx-telnet` | TCP | 2323 |
+| `hybbx-ssh` | SSH (libssh) | 3232 |
+| `hybbx-terminal` | HBX circuit | 7323 |
+| Web browser | WebSocket via reverse proxy | per site |
+
+Frozen: `docs/CLIENTS.md`, `docs/WEBSOCKET.md`.
+
+---
+
+## 7. Commands and access levels
+
+Five levels: Sysop → Admin → Mod → User → Guest. `/help`, `/menu` filtered by level; `/index` lists all commands for every account.
+
+| Sysop RF | `/broadcast`, `/broadcast ax25`, `/shutdown` |
+|----------|-----------------------------------------------|
+| Admin | `/usercreate`, `/activate`, `/promote`, `/demote` |
+
+Frozen: `docs/COMMANDS.md`, `share/commands.yaml`, `share/areas.yaml`.
+
+---
+
+## 8. Operator start order (with MAX25)
+
+Linear sequence for standalone Main + local TNC:
+
+1. **MAX25 prep** — boot-wait or `max25d` per TNC port (or verify `ss -ltn | grep 7325`)
+2. **HyBBX** — `hybbxd -c hybbx.ini` with `kiss_entry=none`, `[max25] check=yes`
+3. **Verify** — log: `max25d reachable` → `KISS attach (MAX25 prep assumed)` → `RF TX` on `/broadcast ax25`
+4. **RF check** — PTT and on-air decode at remote station
+
+Integration detail: [DUAL-TNC-OPERATOR-GUIDE.md](DUAL-TNC-OPERATOR-GUIDE.md).
+
+---
+
+## 9. Future roadmap (deferred)
+
+Aligned with MAX25 [V2.0.0-SCOPE](../../10-PROJECTS/docs/V2.0.0-SCOPE.md) **Later** row — **no product commits** until operator orders a separate track.
+
+| Later | Status |
+|-------|--------|
+| **`/aichat`** — AI / assistant session command | **deferred** |
+| AI / assistant integration (backends, APIs) | **deferred** |
+| like-features | **deferred** |
+
+Full map: [2026-07-14-hybbx-future-roadmap.md](2026-07-14-hybbx-future-roadmap.md).
+
+**v2.8.0:** `/who` lists **interactive users only** (telnet/SSH/WebSocket) — plugin/RF connection sessions are not users.
+
+---
+
+## Related
+
+| Topic | Path |
+|-------|------|
+| RF investigation SSoT | [2026-07-12-site-rf-broadcast-investigation.md](2026-07-12-site-rf-broadcast-investigation.md) |
+| tnc.c recovery integration | [2026-07-13-tnc-recovery-integration.md](2026-07-13-tnc-recovery-integration.md) |
+| INI operator notes | [2026-07-12-ini-operator-notes.md](2026-07-12-ini-operator-notes.md) |
+| MAX25 boundary | [../integration/2026-07-12-max25-hybbx-boundary-final.md](../integration/2026-07-12-max25-hybbx-boundary-final.md) |
+| Dual-TNC operator flow | [DUAL-TNC-OPERATOR-GUIDE.md](DUAL-TNC-OPERATOR-GUIDE.md) |
+| Frozen product docs | `docs/` (read-only) |
+| Production INI (vault) | `share/` INI examples |
+| TNC hardware SSoT | [hardware/tnc2c/CONFIRMED.md](../../hardware/tnc2c/CONFIRMED.md) |
diff --git a/docs/PLATFORMS.md b/docs/PLATFORMS.md
new file mode 100644
index 0000000..f74ff86
--- /dev/null
+++ b/docs/PLATFORMS.md
@@ -0,0 +1,28 @@
+# Platforms · HyBBX 2.8.0
+
+POSIX+ first — Linux, *BSD, AmigaOS 3.9+, macOS, Windows.
+
+## Platform matrix
+
+| Platform | Daemon | Telnet client | packet_radio | SSH |
+|----------|--------|---------------|--------------|-----|
+| Linux | yes | yes | yes | yes (libssh) |
+| FreeBSD / NetBSD / OpenBSD | yes | yes | yes | yes |
+| AmigaOS 3.9+ | partial | yes | yes | no |
+| macOS | yes | yes | yes | yes |
+| Windows | yes | yes | limited | yes |
+
+## AmigaOS matrix
+
+| Item | Value |
+|------|-------|
+| Cross-build | `./scripts/build-amiga-telnet.sh` |
+| Daemon plugins | telnet + packet_radio only |
+| Full feature set | Linux / *BSD recommended |
+
+## Related
+
+| Goal | Doc |
+|------|-----|
+| Build | [BUILD.md](BUILD.md) |
+| Manual | [MANUAL.md](MANUAL.md) |
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 0000000..bff6b9c
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,32 @@
+# Documentation index · HyBBX 2.8.0
+
+One-line role: compact doc map — start at MASTER-GUIDE for linear operator flow.
+
+## Doc index matrix
+
+| Role | Document |
+|------|----------|
+| Master operator guide | [MASTER-GUIDE.md](MASTER-GUIDE.md) |
+| Dual-TNC operator flow | [DUAL-TNC-OPERATOR-GUIDE.md](DUAL-TNC-OPERATOR-GUIDE.md) |
+| Full manual | [MANUAL.md](MANUAL.md) |
+| Topology | [TOPOLOGY.md](TOPOLOGY.md) |
+| TNC profiles | [TNCS.md](TNCS.md) |
+| Clients | [CLIENTS.md](CLIENTS.md) |
+| Commands | [COMMANDS.md](COMMANDS.md) |
+| BayCom transport plugin | [BAYCOM.md](BAYCOM.md) |
+| CRDOP | [CRDOP.md](CRDOP.md) |
+| ARDOP | [ARDOP.md](ARDOP.md) |
+| Build | [BUILD.md](BUILD.md) |
+| Platforms | [PLATFORMS.md](PLATFORMS.md) |
+| Security | [SECURITY.md](SECURITY.md) |
+| WebSocket | [WEBSOCKET.md](WEBSOCKET.md) |
+| Developer | [DEVELOPMENT.md](DEVELOPMENT.md) |
+
+## Related
+
+| Goal | Doc |
+|------|-----|
+| Build | [BUILD.md](BUILD.md) |
+| RF attach | [TNCS.md](TNCS.md) |
+
+- [TMODEM.md](TMODEM.md) — T-Modem-c1224 attach via MAX25
diff --git a/docs/SECURITY.md b/docs/SECURITY.md
new file mode 100644
index 0000000..ed0b3f0
--- /dev/null
+++ b/docs/SECURITY.md
@@ -0,0 +1,38 @@
+# Security · HyBBX 2.8.0
+
+Built-in `[security]` — network protection and abuse in one subsystem.
+
+## Layer matrix
+
+| Layer | What | Ban? |
+|-------|------|------|
+| **Soft limits** | RF pacing, message size, traffic shaping | **No** |
+| **Abuse** | Brute-force, connection flood, excessive spam | **Yes** — short IP/CALLID cool-down |
+
+## Soft limit matrix
+
+| Area | Keys | Effect |
+|------|------|--------|
+| `[traffic]` | `baud`, `pace_output`, `line_width` | Output pacing |
+| `[chat]` | `message_max` | Truncate oversized lines |
+| `[mail]` | `max_messages`, `body_max` | Mailbox caps |
+| AX.25 broadcast | fixed | Min 900 s auto cycle; 60 s between links |
+
+## Ban trigger matrix
+
+| Target | Event | Default threshold |
+|--------|-------|-------------------|
+| **IP** | `login_fail` | 5 / 10 min |
+| **IP** | `link_auth_fail` | 5 / 10 min |
+| **IP** | `rate_limit` | 30 / 60 s |
+| **CALLID** | `link_auth_fail` | same as login |
+| **CALLID** | `ban_callid=` config | immediate, permanent |
+
+CALLID = AX.25 callsign or HBX `link_id`. Optional `iptables`/`nftables` via `ban_backend`.
+
+## Related
+
+| Goal | Doc |
+|------|-----|
+| Manual `[security]` | [MANUAL.md](MANUAL.md) |
+| Topology link auth | [TOPOLOGY.md](TOPOLOGY.md) |
diff --git a/docs/TMODEM.md b/docs/TMODEM.md
new file mode 100644
index 0000000..71aa0ed
--- /dev/null
+++ b/docs/TMODEM.md
@@ -0,0 +1,32 @@
+# T-Modem-c1224 — HyBBX attach
+
+**AS-IS** · prototype. Public term: **BBX** (not BBS). Never **AX25SRV** in public copy.
+
+## Role
+
+HyBBX does **not** run T-Modem L1. Attach to a running **max25d** that has device id **`tmodem`** enabled (USB KISS half-TNC from T-Modem-c1224 Pico firmware).
+
+| Layer | Owns |
+|-------|------|
+| T-Modem-c1224 FW | HDLC + bitbang + chip AFSK + PTT |
+| MAX25-Stack max25d | Device `tmodem` · `kiss-raw-serial` on `/dev/ttyACM*` |
+| HyBBX | Network/BBX attach to max25d only |
+
+Not BayCom/based. Not SER12.
+
+## Example (default off)
+
+```ini
+[networks]
+tmodem = no
+```
+
+When max25d already serves `tmodem`, prefer the existing **max25** / host attach path used for other MAX25 devices — enable only after max25d RX proof (RX before TX).
+
+## Related
+
+| Doc | Path |
+|-----|------|
+| MAX25 DEV | MAX25-Stack `docs/DEV/TMODEM-C1224.md` |
+| BayCom/based (different) | [BAYCOM.md](BAYCOM.md) |
+| TNCs | [TNCS.md](TNCS.md) |
diff --git a/docs/TNCS.md b/docs/TNCS.md
new file mode 100644
index 0000000..c2b156b
--- /dev/null
+++ b/docs/TNCS.md
@@ -0,0 +1,56 @@
+# TNC profiles · HyBBX 2.8.0
+
+Single `packet_radio` transport — up to 8 instances per process. MAX25 owns RF prep; HyBBX attach-only in v2.8.0.
+
+## packet_radio / MAX25 matrix
+
+| Rule | Value |
+|------|-------|
+| `kiss_entry` | `none` (default) — MAX25 sends `kiss on` |
+| `[max25] check` | `yes` — probe max25d `:7325` before serial open |
+| Serial ownership | One process per `/dev/tty*` |
+
+## Host protocol matrix
+
+| Protocol | INI `protocol=` | Use |
+|----------|-----------------|-----|
+| KISS | `kiss` (default) | Secondary RF — recommended after MAX25 prep |
+| TNC2 host converse | `hostmode`, `host`, `tnc2` | Interactive host session |
+| 6PACK | `sixpack` | DF6BU 6PACK over serial |
+
+## KISS entry/exit matrix
+
+| INI key | Values | v2.8.0 default |
+|---------|--------|----------------|
+| `kiss_entry` | `none`, `kiss_on`, `esc_at_k`, `auto` | `none` |
+| `kiss_exit` | `none`, `kiss_off`, `kiss_frame`, `auto` | `none` |
+
+## TNC profile matrix (packet_radio)
+
+| Profile | Aliases | Serial | KISS attach | RTS/DTR |
+|---------|---------|--------|-------------|---------|
+| `tnc2c` | `tnc2-c` | 7E1 | `none` | boot-wait |
+| `tnc2` | `pktnc2`, `pk-tnc2`, `tapr`, `thefirmware` | 8N1 | `none` | boot-wait |
+| `pk232` | `pk-232`, `aea` | 8N1 | `none` | off |
+| `mfj1278` | `mfj-1278` | 7E1 | `none` | off |
+| `kantronics` | `kpc`, `kpc3` | 8N1 | `none` | off |
+| `generic` | `tnc` | 8N1 | `none` | off |
+
+BayCom hardware: optional [`baycom`](BAYCOM.md) transport plugin — not a `packet_radio` TNC profile.
+
+## AX.25 source matrix
+
+| Item | Owner |
+|------|-------|
+| Host `MYCALL` on TNC | MAX25 (prep) |
+| Outbound UI source | HyBBX `[broadcast] ax25_mycall` |
+| KISS DATA FCS | Stripped by HyBBX — TNC adds CRC on air |
+| `persist` on CB | `255` recommended — CSMA defer avoidance |
+
+## Related
+
+| Goal | Doc |
+|------|-----|
+| Manual | [MANUAL.md](MANUAL.md) |
+| BayCom plugin | [BAYCOM.md](BAYCOM.md) |
+| Dual-TNC | [DUAL-TNC-OPERATOR-GUIDE.md](DUAL-TNC-OPERATOR-GUIDE.md) |
diff --git a/docs/TOPOLOGY.md b/docs/TOPOLOGY.md
new file mode 100644
index 0000000..0336c9d
--- /dev/null
+++ b/docs/TOPOLOGY.md
@@ -0,0 +1,43 @@
+# Topology · HyBBX 2.8.0
+
+Main, Secondary, and mains-proxy mesh layout.
+
+## Role matrix
+
+| Role | Process | Typical `[networks]` | Hosts |
+|------|---------|----------------------|-------|
+| **Main** | `hybbxd` | `circuit=yes` | Users, storage, HBX hub `:7323` |
+| **Secondary** | `hybbxd` (remote) | `circuit=no`, `ax25=yes` | RF; HBX client to Main |
+| **Standalone Main** | `hybbxd` | `ax25=yes` on same box | Lab / dual local TNC |
+
+## RF attachment matrix
+
+| Layout | TNC host | Main `[transport.packet_radioN]` |
+|--------|----------|----------------------------------|
+| Remote Secondary | Secondary (`device`, `tnc`, `circuit_host`) | Bridge registry only (`link_id`, password) |
+| Local TNC on Main | Same box as users | Full TNC keys (`device`, `tnc`, …) |
+
+## HBX/Circuit matrix
+
+| Item | Value |
+|------|-------|
+| Protocol | HBX v1 — magic `HBX` |
+| Default port | `7323` |
+| Max links | 16 (default `max_links=8`) |
+| Auth | Per-link `link_password` |
+| Scope | Sole inter-node transport — core never sees raw KISS |
+
+## Broadcast matrix
+
+| Command | Scope | Level |
+|---------|-------|-------|
+| `/broadcast <msg>` | Local logged-in users | Sysop |
+| `/broadcast ax25` | Sequential RF beacon (60 s link gap) | Sysop |
+
+## Related
+
+| Goal | Doc |
+|------|-----|
+| Manual | [MANUAL.md](MANUAL.md) |
+| Mesh proxy | [MAINS_PROXY.md](MAINS_PROXY.md) |
+| Dual-TNC | [DUAL-TNC-OPERATOR-GUIDE.md](DUAL-TNC-OPERATOR-GUIDE.md) |
diff --git a/docs/WEBSOCKET.md b/docs/WEBSOCKET.md
new file mode 100644
index 0000000..7a19b03
--- /dev/null
+++ b/docs/WEBSOCKET.md
@@ -0,0 +1,27 @@
+# WebSocket · HyBBX 2.8.0
+
+WebSocket forward-proxy for browser and rich clients — core stays text-first.
+
+## Transport matrix
+
+| Item | Value |
+|------|-------|
+| Plugin | `HYBBX_PLUGIN_WEBSOCKET=ON` (default) |
+| Default port | `4591` (plain); wss with OpenSSL |
+| INI | `[networks] websocket=yes`, `[transport.websocket]` |
+| Reverse proxy | nginx/caddy TLS termination typical |
+
+## Security matrix
+
+| Item | Value |
+|------|-------|
+| User auth | Same as telnet — session login |
+| TLS | Optional `-DHYBBX_CRYPTO_OPENSSL=ON` for wss |
+| Link auth | Separate from HBX circuit auth |
+
+## Related
+
+| Goal | Doc |
+|------|-----|
+| Clients | [CLIENTS.md](CLIENTS.md) |
+| Security | [SECURITY.md](SECURITY.md) |