termapy 0.76.0__tar.gz → 0.77.0__tar.gz

{termapy-0.76.0 → termapy-0.77.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: termapy
-Version: 0.76.0
+Version: 0.77.0
 Summary: A TUI serial terminal with ANSI color support, built on Textual and pyserial
 Keywords: serial,terminal,tui,textual,pyserial,embedded,xmodem,ymodem
 Author: Chuck Bass
@@ -16,6 +16,7 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
 Classifier: Topic :: Communications
 Classifier: Topic :: System :: Hardware
 Classifier: Topic :: Terminals :: Serial
@@ -50,7 +51,7 @@ Description-Content-Type: text/markdown
 
 **Powered by:** [![Textual](https://img.shields.io/badge/Textual-TUI-blue?logo=python)](https://textual.textualize.io/) [![pySerial](https://img.shields.io/badge/pySerial-serial%20I%2FO-orange?logo=python)](https://pyserial.readthedocs.io/) [![zensical](https://img.shields.io/badge/zensical-docs-green)](https://github.com/hucker/zensical)
 
-**Built with:** ![python](https://img.shields.io/badge/python-3.11--3.14-blue) [![uv](https://img.shields.io/badge/uv-package%20manager-blueviolet?logo=astral)](https://docs.astral.sh/uv/) [![pytest](https://img.shields.io/badge/pytest-testing-yellow?logo=pytest)](https://pytest.org/) [![coverage](https://img.shields.io/badge/coverage-72%25-yellow)](https://coverage.readthedocs.io/)
+**Built with:** ![python](https://img.shields.io/badge/python-3.11--3.15-blue) [![uv](https://img.shields.io/badge/uv-package%20manager-blueviolet?logo=astral)](https://docs.astral.sh/uv/) [![pytest](https://img.shields.io/badge/pytest-testing-yellow?logo=pytest)](https://pytest.org/) [![coverage](https://img.shields.io/badge/coverage-84%25-brightgreen)](https://coverage.readthedocs.io/)
 
 Pronounced "ter-map-ee"
 
@@ -153,6 +154,8 @@ Termapy runs with your privileges and does whatever you — or a connected MCP c
 | Network sockets (`socket://`, `rfc2217://`) | `TERMAPY_MCP_NET_EGRESS=1` |
 | Environment variables (`/env`, `$(env.X)`) | `TERMAPY_MCP_ENV_ENABLED=1` |
 
+Each flag takes any boolean token (`1`, `on`, `true`, `yes`, ...); a value outside that vocabulary refuses to start, naming the variable, rather than silently meaning off.
+
 <details>
 <summary><strong>The basics</strong> - keyboard shortcuts, title bar, REPL commands</summary>
 
@@ -194,15 +197,15 @@ The most common ones:
 
 | Command                              | Description                                         |
 | ------------------------------------ | --------------------------------------------------- |
-| `/help [cmd]`                        | List commands or show help for one                  |
+| `/help {cmd}`                        | List commands or show help for one                  |
 | `/port.list`                         | List available serial ports                         |
 | `/port.connect {name} {baud} {mode}` | Connect with optional baud rate and mode (e.g. N81) |
 | `/port.info`                         | Show port status and parameters                     |
-| `/cfg [key [value]]`                 | Open Cfg picker (bare TUI), or get/set values       |
-| `/ss.svg [name]`                     | Save SVG screenshot                                 |
+| `/cfg {key {value}}`                 | Open Cfg picker (bare TUI), or get/set values       |
+| `/ss.svg {name}`                     | Save SVG screenshot                                 |
 | `/cls`                               | Clear the terminal                                  |
 | `/run {filename}`                    | Open Run picker (bare TUI), or run a named script   |
-| `/term.echo [on \| off]`             | Local echo of device commands sent to the wire      |
+| `/term.echo {on\|off\|toggle}`        | Local echo of device commands sent to the wire      |
 | `/grep <pattern>`                    | Search scrollback                                   |
 | `/exit`                              | Exit termapy                                        |
 
@@ -211,9 +214,9 @@ The most common ones:
 
 | Command                              | Description                                                                   |
 | ------------------------------------ | ----------------------------------------------------------------------------- |
-| `/help [cmd]`                        | List commands or show extended help for one                                   |
+| `/help {cmd}`                        | List commands or show extended help for one                                   |
 | `/help.dev <cmd>`                    | Show a command handler's Python docstring                                     |
-| `/port {name}`                       | Open Port picker (bare TUI), list subcommands (bare CLI), or open by name     |
+| `/port {name}`                       | Open Port picker (bare TUI), list ports (bare CLI), or open by name           |
 | `/port.help`                         | Same as `/help port`                                                          |
 | `/port.list`                         | List available serial ports                                                   |
 | `/port.connect {name} {baud} {mode}` | Connect with optional baud and mode (e.g. /port.connect COM3 9600 N81)        |
@@ -225,21 +228,21 @@ The most common ones:
 | `/port.parity {value}`               | Show or set parity (hardware only)                                            |
 | `/port.stop_bits {value}`            | Show or set stop bits (hardware only)                                         |
 | `/port.flow_control {m}`             | Show or set flow control: none, rtscts, xonxoff, manual                       |
-| `/port.dtr {0\|1}`                   | Show or set DTR line                                                          |
-| `/port.rts {0\|1}`                   | Show or set RTS line                                                          |
+| `/port.dtr {on\|off}`                | Show or set DTR line                                                          |
+| `/port.rts {on\|off}`                | Show or set RTS line                                                          |
 | `/port.cts`                          | Show CTS state (read-only)                                                    |
 | `/port.dsr`                          | Show DSR state (read-only)                                                    |
 | `/port.ri`                           | Show RI state (read-only)                                                     |
 | `/port.cd`                           | Show CD state (read-only)                                                     |
 | `/port.break {ms}`                   | Send break signal (default 250ms)                                             |
-| `/cfg [key [value]]`                 | Open Cfg picker (bare TUI), dump JSON (bare CLI), or get/set with args        |
+| `/cfg {key {value}}`                 | Open Cfg picker (bare TUI), list configs (bare CLI), or get/set with args     |
 | `/cfg.auto <key> <value>`            | Set an in-memory config key immediately (no confirmation)                     |
 | `/cfg.list`                          | List all config files                                                         |
 | `/cfg.load <name>`                   | Switch to a different config by name                                          |
 | `/cfg.show`                          | Open the current config file in the system viewer                             |
 | `/cfg.help`                          | Same as `/help cfg`                                                           |
-| `/ss.svg [name]`                     | Save SVG screenshot                                                           |
-| `/ss.txt [name]`                     | Save text screenshot                                                          |
+| `/ss.svg {name}`                     | Save SVG screenshot                                                           |
+| `/ss.txt {name} {N}`                 | Save text screenshot (all, or an N-line slice)                                |
 | `/ss.list`                           | List screenshots, newest first, with size and age                             |
 | `/ss.explore`                        | Open the screenshot folder in the system file explorer                        |
 | `/cls`                               | Clear the terminal screen                                                     |
@@ -258,34 +261,51 @@ The most common ones:
 | `/show.cfg`                          | Show the current config file                                                  |
 | `/term`                              | Terminal display / session toggles (echo, line_no, timestamps, ...)           |
 | `/term.info`                         | Snapshot the state of every `/term.*` toggle                                  |
-| `/term.echo [on \| off]`             | Local echo of device commands sent to the wire (persisted via cfg `echo`)     |
-| `/term.echo_repl [on \| off]`        | Local echo of REPL (slash) commands, session only; off inside scripts         |
-| `/term.line_no [on \| off]`          | Toggle line numbers in serial output (TUI only)                               |
-| `/term.eol.markers [on \| off]`      | Toggle visible `\r` `\n` markers for line-ending troubleshooting              |
-| `/term.output {level}`               | Show or set output level (silent/quiet/normal/verbose)                        |
-| `/term.timestamps [on \| off]`       | Toggle `[HH:MM:SS.mmm]` timestamp prefix                                      |
-| `/term.hex [on \| off]`              | Toggle hex display of incoming bytes                                          |
+| `/term.echo {on\|off\|toggle}`        | Local echo of device commands sent to the wire (persisted via cfg `echo`)     |
+| `/term.echo_repl {on\|off\|toggle}`   | Local echo of REPL (slash) commands, session only; off inside scripts         |
+| `/term.line_no {on\|off\|toggle}`     | Toggle line numbers in serial output (TUI only)                               |
+| `/term.eol.markers {on\|off\|toggle}` | Toggle visible `\r` `\n` markers for line-ending troubleshooting              |
+| `/term.output {level\|cycle}`        | Show or set output level (silent/quiet/normal/verbose)                        |
+| `/term.timestamps {on\|off\|toggle}`  | Toggle `[HH:MM:SS.mmm]` timestamp prefix                                      |
+| `/term.hex {on\|off\|toggle}`         | Toggle hex display of incoming bytes                                          |
 | `/term.encoding {name}`              | Show or set byte-decoding encoding (utf-8, latin-1, ...)                      |
-| `/term.send_bare_enter [on \| off]`  | Send line ending on empty Enter                                               |
+| `/term.json {compact\|indent\|color\|cycle}` | How JSON answers print: one line, indented, or indented and colored |
+| `/term.send_bare_enter {on\|off\|toggle}` | Send line ending on empty Enter                                          |
 | `/edit <file>`                       | Edit a project file (`run/`/`proto/` path)                                    |
 | `/edit.cfg`                          | Edit the current config file                                                  |
 | `/edit.log`                          | Open the session log in the system viewer                                     |
 | `/edit.info`                         | Open the info report in the system viewer                                     |
 | `/os <cmd>`                          | Run a shell command (10s timeout, requires `TERMAPY_OS_CMD_ENABLED=1` in env) |
 | `/grep <pattern>`                    | Search scrollback for regex matches (case-insensitive, skips own output)      |
-| `/cfg.info {--display}`              | Show project summary (folder tree + config + buttons); `--display` opens the full report |
-| `/proto`                             | Open Proto picker (bare TUI) or show long-help (bare CLI)                     |
+| `/cfg.info {--display}`              | Write and show the project report (folder tree, config, buttons, log and history tails); also written at exit; `--display` opens it |
+| `/proto`                             | Open Proto picker (bare TUI) or list proto/ (bare CLI)                        |
 | `/proto.help`                        | Same as `/help proto`                                                         |
 | `/proto.send <hex>`                  | Send raw hex bytes and/or quoted text, display response as hex (see below)    |
 | `/proto.run <file>`                  | Run a binary protocol test script (.pro) with pass/fail                       |
 | `/proto.list`                        | List .pro files in proto/, newest first, with size and age                    |
 | `/proto.rename <old> <new>`          | Rename a protocol script (`.pro` kept; never overwrites)                      |
-| `/proto.hex [on \| off]`             | Toggle hex display mode for serial I/O                                        |
+| `/proto.hex {on\|off\|toggle}`        | Same flag as `/term.hex`                                                      |
 | `/proto.crc.list {pat}`              | List available CRC algorithms (optional glob filter)                          |
 | `/proto.crc.info <name>`             | Show CRC algorithm parameters and description                                 |
-| `/proto.crc.calc <n> {d}`            | Compute CRC over hex bytes, text, or file; omit data to verify check string   |
-| `/proto.crc.find <pkt>`              | Identify CRC algorithm from a captured packet (bin= hex or asc= text)         |
+| `/proto.crc.calc <n> {d}`            | Compute CRC over hex bytes, quoted text, or a file; omit data to verify check string |
+| `/proto.crc.find bin=<hex>\|asc=<text>\|cmd=<trigger>` | Identify CRC algorithm from a captured packet, text, or a command's reply |
 | `/proto.info`                        | Print current protocol state                                                  |
+| `/mem.dump <target> {len} {type}`    | Hexdump or typed word columns at an address or symbol                         |
+| `/mem.read <target> {type}`          | One typed value: scalar, char, register field, bit or slice                   |
+| `/mem.write <target> <hex>`          | Write hex bytes, or set a register field/bit (audited; destructive over MCP)  |
+| `/mem.or <target> <mask>`            | Boolean ops on one word (also `.and`, `.clear`, `.xor`, `.not`); atomic via `MEM.M` where expressible |
+| `/mem.str <target> {max}`            | Read a NUL-terminated string as a first-class value                           |
+| `/mem.info`                          | Memory access config: dialect, block limit, width, endian, atomic modify      |
+| `/sym <addr\|name>`                  | Symbol table: name to address, or address to `name+offset`                   |
+| `/sym.import {file} {format=<value>}` | Convert a linker map to `sym/<cfg>.symbols.json` and load it (bare: re-import the same map) |
+| `/sym.info`                          | Show the loaded symbol table: file, source, counts by section, range          |
+| `/sym.load {path}`                   | Load a symbol table (default: the cfg sidecar `/sym.import` writes)           |
+| `/sym.search <pattern>`              | Search symbols by name: exact, glob, regex, or substring                      |
+| `/sym.unload`                        | Clear the loaded symbol table                                                 |
+| `/dev.import <file> {format=<value>} {category=<value>} {to=<value>} {use=on\|off}` | Convert a vendor register description (CMSIS-SVD) into this config's `lib/` and reference it from `dev/` (`to=global` shares it) |
+| `/dev.lib {pattern}`                 | List the parts the libraries hold (available, not loaded), with their layer  |
+| `/dev.list`                          | List the devices this config has loaded, with layer and placement            |
+| `/dev.use <part> {at=<value>}`       | Add a library part to this config; `at=NAME@ADDR ...` places a relocatable one |
 | `/var {name}`                        | List user variables, or show one by name                                      |
 | `/var.set <NAME> <value>`            | Set a user variable                                                           |
 | `/var.clear`                         | Clear all user variables                                                      |
@@ -297,7 +317,7 @@ The most common ones:
 | `/cap.struct <f> ...`                | Capture binary data, decode with format spec to CSV                           |
 | `/cap.hex <f> ...`                   | Capture hex text lines, decode with format spec to CSV                        |
 | `/cap.stop`                          | Stop an active capture                                                        |
-| `/raw <text>`                        | Send text to serial with no variable expansion or transforms                  |
+| `/raw <text>`                        | Send text exactly as typed: no line ending, expansion or transforms           |
 | `/exit`                              | Exit termapy                                                                  |
 
 </details>
@@ -315,12 +335,13 @@ Everything termapy creates (configs, scripts, test files, plugins, logs) lives i
 
 ```text
 termapy_cfg/
-├── plugin/                             # global plugins (all configs)
+├── plugin/                             # global plugins (all configs), once you add one
 └── demo/
     ├── demo.cfg                        # config file
+    ├── demo_legacy.profile.json        # /mem.* through the device's own `mem` grammar
     ├── demo.log                        # session log
     ├── demo.history                    # command history
-    ├── ss/                             # screenshots
+    ├── demo.md                         # project report (/cfg.info), rewritten at exit
     ├── run/                            # script files for /run
     │   ├── at_demo.run
     │   ├── smoke_test.run
@@ -331,16 +352,14 @@ termapy_cfg/
     │   ├── probe.py
     │   ├── temp_plot.py
     │   └── traffic.py
-    ├── cap/                            # data capture output files
-    ├── prof/                           # /run.profile timing CSVs
-    ├── viz/                            # per-config packet visualizers
+    ├── sym/                            # symbol tables (demo.symbols.json, auto-loaded)
     └── proto/                          # protocol test scripts
         ├── at_test.pro
         ├── bitfield_inline.pro
         └── modbus_inline.pro
 ```
 
-Your own configs follow the same layout. Create one with `Cfg` → `New` and termapy builds the folder structure automatically.
+Your own configs follow the same layout, minus the demo content: a new config is its `.cfg` beside the log and history. Data folders appear on first use (`ss/` at the first screenshot, `cap/` at the first capture, `prof/` at the first `/run.profile`, `viz/` when you drop a visualizer in), and a folder you empty is removed at the next load, so a plain terminal session never sees a folder it has no use for.
 
 ### Version control
 
@@ -356,19 +375,18 @@ Since COM port names differ between machines, use `$(env.NAME)` placeholders in
 
 ```json
 {
-    "port": "$(env.COMPORT|COM4)",
-    "baud_rate": 115200,
+    "serial": {"port": "$(env.COMPORT|COM4)", "baud_rate": 115200},
     "auto_connect": true
 }
 ```
 
-On a machine with `COMPORT=COM7`, termapy connects to COM7. On a machine without `COMPORT` set, it falls back to COM4. The config file on disk keeps the raw `$(env.COMPORT|COM4)` template. It's expanded in memory at load time, so your checked-in config stays portable.
+On a machine with `COMPORT=COM7`, termapy connects to COM7. On a machine without `COMPORT` set, it falls back to COM4. The config file on disk keeps the raw `$(env.COMPORT|COM4)` template. It's expanded in memory at load time, so your checked-in config stays portable. A boolean key can be templated the same way (`"echo": "$(env.ECHO|false)"`); the expanded text is read with the boolean vocabulary (`on`, `off`, `true`, `false`, `yes`, `no`, `1`, `0`, ...), and a value outside it refuses the load naming the key.
 
-Environment variables work in any string config value, not just `port`:
+Environment variables work in any string config value, not just `serial.port`:
 
 ```json
 {
-    "port": "$(env.COMPORT|COM4)",
+    "serial": {"port": "$(env.COMPORT|COM4)"},
     "title": "$(env.DEVICE_NAME|Dev Board)",
     "log_file": "$(env.LOG_DIR|logs)/session.log"
 }
@@ -449,7 +467,7 @@ Any datetime variable takes an optional `strftime` format after a colon — `$(D
 
 **vs. environment variables:** `$(env.NAME)` pulls from the OS environment and works in config files. `$(NAME)` is for user-defined session variables in commands and scripts. Both use the `$(...)` syntax. The `env.` prefix is required to access environment variables explicitly.
 
-**Escaping:** Use `\$` to prevent expansion of a single reference, or `/raw` to skip expansion for an entire line.
+**Escaping:** Use `\$` to prevent expansion of a single reference, or `/term.send` to send an entire line without expansion (`/raw` does the same with no line ending).
 
 Add a `.gitignore` for session files you don't need to track:
 
@@ -500,13 +518,12 @@ When you create a new config, termapy writes a complete `.cfg` file with all def
 
 ```json
 {
-    "port": "COM4",
-    "baud_rate": 115200,
+    "serial": {"port": "COM4", "baud_rate": 115200},
     "auto_connect": true,
     "auto_reconnect": true,
     "title": "Sensor A",
     "border_color": "blue",
-    "on_connect_cmd": "rev \n help dev"
+    "on_connect_cmd": "/run startup"
 }
 ```
 
@@ -534,13 +551,11 @@ Add toolbar buttons that send commands, run scripts, or chain multiple actions.
 
 ### Hardware line control
 
-Set `flow_control` to `"manual"` to get DTR, RTS, and Break buttons in the toolbar. This is useful for devices that use these lines for reset or bootloader entry:
+Set `serial.flow_control` to `"manual"` to get DTR, RTS, and Break buttons in the toolbar. This is useful for devices that use these lines for reset or bootloader entry:
 
 ```json
 {
-    "port": "COM4",
-    "baud_rate": 115200,
-    "flow_control": "manual",
+    "serial": {"port": "COM4", "baud_rate": 115200, "flow_control": "manual"},
     "title": "Hardware Debug"
 }
 ```
@@ -551,7 +566,7 @@ Set `flow_control` to `"manual"` to get DTR, RTS, and Break buttons in the toolb
 <!-- validate-config-keys -->
 ```json
 {
-    "config_version": 29,
+    "config_version": 30,
     "title": "",
     "border_color": "",
     "max_lines": 10000,
@@ -602,6 +617,7 @@ Set `flow_control` to `"manual"` to get DTR, RTS, and Break buttons in the toolb
     "hex": false,
     "request_mode": false,
     "request_err_pattern": "(?i)^(ERROR|ERR|FAULT)\\b",
+    "json_style": "compact",
     "strip_device_echo": false,
     "max_grep_lines": 100,
     "file_xfer_root": "",
@@ -761,18 +777,22 @@ expect_fmt = "Title:Modbus_Response Slave:H1 Func:H2 Bytes:U3 R0:U4-5 R1:U6-7 CR
 
 Each column is `Name:TypeBytes` where the type controls how bytes are displayed:
 
-| Type   | Description               | Example               | Display            |
-| ------ | ------------------------- | --------------------- | ------------------ |
-| `H`    | Hex (uppercase)           | `H1` / `H3-4`         | `0A` / `0A 2B`     |
-| `h`    | Hex (lowercase)           | `h1`                  | `0a`               |
-| `U`    | Unsigned int (big-endian) | `U3-4`                | `7`                |
-| `I`    | Signed int (big-endian)   | `I3-4`                | `-1`               |
-| `S`    | ASCII string              | `S3-10`               | `HELLO`            |
-| `B`    | Bit field (integer)       | `B4-5.0-2`            | `3`                |
-| `b`    | Bit field (binary string) | `b4-5.0-15`           | `0000101000101011` |
-| `F`    | IEEE 754 float            | `F3-6`                | `3.14`             |
-| `_`    | Padding (skip bytes)      | `_3-4`                | *(hidden)*         |
-| `crc*` | CRC auto-check            | `CRC:crc16-modbus_le` | `OK` / `FAIL`      |
+<!-- format-types:start (generated by scripts/sync_format_tables.py from protocol/type_codes.py -- do not edit by hand) -->
+
+| Code   | Meaning          | Example            | Output       |
+| ------ | ---------------- | ------------------ | ------------ |
+| `H`    | Hex bytes        | `H1`, `H3-4`       | `0A`, `01FF` |
+| `h`    | Hex, per byte    | `h3-4`             | `01 FF`      |
+| `U`    | Unsigned integer | `U1`, `U3-4`       | `10`, `256`  |
+| `I`    | Signed integer   | `I1`, `I3-4`       | `-1`, `+127` |
+| `S`    | ASCII string     | `S1-5`             | `Hello`      |
+| `F`    | IEEE 754 float   | `F1-4`             | `3.14`       |
+| `B`    | Bit field        | `B1.3`, `B1-2.7-9` | `1`, `5`     |
+| `b`    | Bit field, bits  | `b1.0-7`           | `00000110`   |
+| `_`    | Padding (hidden) | `_3-4`             | *(skipped)*  |
+| `crc*` | CRC verify       | `crc16-modbus`     | pass/fail    |
+
+<!-- format-types:end -->
 
 Byte indices are 1-based. Ranges use `-` (e.g. `U3-4` = bytes 3-4). **Byte order is controlled by the index direction.** This is how you handle big-endian vs little-endian protocols:
 
@@ -942,7 +962,7 @@ Passing a `.run` file to `--cli` automatically infers the config from the file's
 
 - Rich colored output (toggle with `/term.color on|off` or `--no-color`)
 - Command history shared with TUI (up/down arrows, persisted across sessions)
-- Tab completion for REPL commands
+- Tab completion for REPL commands and for the file names they take (`/run`, `/proto.run`, `/cap.dump`, ...)
 - Script execution with `/run` (same scripts work in both TUI and CLI)
 - `/delay` with progress bar for waits of a second or longer (Ctrl+C to cancel)
 - All `/port`, `/cfg`, `/var`, `/env`, `/proto.crc`, `/edit` commands work
@@ -983,6 +1003,10 @@ It's also a reversible toggle from inside the TUI, like `/cli` <-> `/tui`: `/vt1
 <details>
 <summary><strong>Extending termapy</strong> - plugins, subcommands, visualizers</summary>
 
+### Symbols, memory and parts
+
+`/sym.import build/mem.map` turns your linker map into names, so `/mem.read gTemp` reads a variable by name instead of by address. `/dev.import part.svd` does the same for the silicon: a vendor CMSIS-SVD becomes a **device file** -- every register of the part with its bit fields -- stored once in the config's `lib/` and referenced from its `dev/`, so `/mem.read PORT_GROUP0_DIR` works and a checked-in config folder carries its parts. A part on the external bus (two ADCs, an FPGA block) is written once with register offsets and placed per board: `/dev.use acme-adc16 at=ADC1@0x60000000 ADC2@0x60001000`. Registers are live silicon, not variables, so `/mem.*` refuses bulk reads over them, refuses reads of write-only registers, and logs the rest. The device side is the MEM wire spec (`examples/firmware/termapy_mem.c`, a drop-in) or a profile block describing your monitor's own peek/poke grammar. See the Symbols, Devices and Memory help pages.
+
 ### Plugins
 
 Every built-in command (`/help`, `/cfg`, `/grep`, all of them) is itself a plugin loaded from the same folder you'd drop your own into. If something was hard to build as a plugin, the API was wrong. [Dogfooding](https://en.wikipedia.org/wiki/Eating_your_own_dog_food) all the way down.
@@ -1013,86 +1037,9 @@ COMMAND = Command(
 3. **Per-config:** `termapy_cfg/<name>/plugin/*.py`, specific to one config
 4. **App hooks:** frontend-specific commands (`/ss`, `/delay`, `/run`, etc.)
 
-<details>
-<summary>Subcommands</summary>
-
-Use `sub_commands` for related operations. Users invoke them with dot notation (`/tool.run`):
-
-```python
-from termapy.plugins import Command
-
-def _run(ctx, args):
-    ctx.io.status(f"Running {args}...")
+Resolution is the same in every frontend (TUI, CLI, MCP server) and reruns on every config switch; a folder plugin can never take an app hook's name.
 
-def _status(ctx, args):
-    ctx.io.result("All good.")
-
-# ── COMMAND (must be at end of file) ──────────────────────────────────────────
-COMMAND = Command(
-    name="tool",
-    help="A tool with subcommands.",
-    sub_commands={
-        "run":    Command(args="<file>", help="Run a file.", handler=_run),
-        "status": Command(help="Show status.", handler=_status),
-    },
-)
-```
-
-The user types `/tool.run myfile` or `/tool.status`.
-
-</details>
-
-<details>
-<summary>PluginContext API</summary>
-
-The `ctx` object passed to every handler is a thin shell over **five capability handles**, each owning one domain:
-
-| Member                            | Description                                                       |
-| --------------------------------- | ----------------------------------------------------------------- |
-| `ctx.cfg`                         | Current config (read-only mapping)                                |
-| `ctx.config_path`                 | Path to the current `.cfg` config file                            |
-| `ctx.io.result(text, color)`      | The command's answer; shown at quiet+ (suppressed at silent)      |
-| `ctx.io.output(text, color)`      | Bulk data: listings, dumps; shown at normal+                      |
-| `ctx.io.status(text)`             | Progress chatter; shown only at verbose                           |
-| `ctx.io.result_markup(text)`      | Like `result` but text is Rich markup (`[red]X[/]`)               |
-| `ctx.io.output_markup(text)`      | Like `output` but text is Rich markup                             |
-| `ctx.io.status_markup(text)`      | Like `status` but text is Rich markup                             |
-| `ctx.io.notify(text)`             | Always-works fallback notification (toast in TUI, plain in CLI)   |
-| `ctx.io.log(prefix, text)`        | Write to session log: `">"` TX, `"<"` RX, `"#"` status            |
-| `ctx.serial.is_connected`         | Bool: serial port is open                                         |
-| `ctx.serial.write(data)`          | Send bytes to the serial port (auto-logged as TX)                 |
-| `ctx.serial.read_raw(timeout_ms)` | Read raw bytes with timeout framing (returns `bytes`)             |
-| `ctx.serial.drain()`              | Drain pending RX data                                             |
-| `ctx.serial.wait_idle()`          | Wait until serial output settles                                  |
-| `ctx.serial.io()`                 | Context manager for exclusive serial I/O                          |
-| `ctx.serial.rx_observer()`        | Context manager: passive RX byte tap                              |
-| `ctx.serial.tx_observer()`        | Context manager: passive TX byte tap                              |
-| `ctx.fs.ss_dir`                   | Screenshot directory (`Path`)                                     |
-| `ctx.fs.scripts_dir`              | Scripts directory (`Path`)                                        |
-| `ctx.fs.proto_dir`                | Proto-test directory (`Path`)                                     |
-| `ctx.fs.cap_dir`                  | Capture-output directory (`Path`)                                 |
-| `ctx.fs.open_file(path)`          | Open in system viewer/editor (gated on `gui_apps` capability)     |
-| `ctx.ui.confirm(message)`         | Yes/Cancel dialog (TUI-only; declare `confirm_dialog` capability) |
-| `ctx.ui.notify(text)`             | TUI-strict notification (declare `ui_notify`)                     |
-| `ctx.ui.clear_screen()`           | Clear the terminal output (declare `tui_mode`)                    |
-| `ctx.ui.screenshot(path)`         | Save an SVG screenshot (declare `screen_capture`)                 |
-| `ctx.dispatch(cmd)`               | Re-route a command through the full pipeline                      |
-| `ctx.ns(name)`                    | Get/create a session-scoped state dict                            |
-| `ctx.plugin_cfg(name)`            | Get a per-plugin persistent config dict                           |
-
-**Capability gating.** Methods on `ctx.ui` and `ctx.fs.open_file` are gated on `CapabilitySet` flags. Calling a gated method without declaring the capability raises `MissingCapability`, which the dispatcher converts to `CmdResult.fail`. Declare what your command needs:
-
-```python
-COMMAND = Command(
-    name="ask", help="Prompt user.",
-    needs=CapabilitySet(confirm_dialog=True),  # refuse to dispatch in CLI
-    handler=_handler,
-)
-```
-
-There is also `ctx.internal`, a privileged escape hatch for built-ins (config save, capture, port control, engine forwarders, etc.). This is used by built-in commands and may change between versions, so external plugins should avoid it.
-
-</details>
+Subcommands (`/tool.run`, `/tool.status`), typed parameters, scriptable return values, the full `PluginContext` API with its five handles and capability gating, and the `ctx.internal` escape hatch that built-ins use are all in the [Writing plugins](src/termapy/help/writing-plugins.md) guide, which also ships in the in-app help.
 
 <details>
 <summary>Example plugins</summary>
@@ -1104,7 +1051,6 @@ See `examples/plugins/` for working examples:
 - **timestamp.py:** print the current date/time
 - **ping.py:** send a command and measure response time
 - **traffic.py:** passive RX/TX byte tap (count, hexdump, rate, snoop) -- also shipped with `--demo`
-- **pic_map.py:** decode a PIC memory map
 
 More complete examples ship with `--demo`: `probe.py` demonstrates the drain → write → read → parse cycle for device interaction; `traffic.py` (with `/traffic.count`, `/traffic.hexdump`, `/traffic.rate`, `/traffic.snoop`) demonstrates the passive RX/TX observer pattern via the `ctx.serial.rx_observer()` / `ctx.serial.tx_observer()` context managers. Run `/help probe` or `/help traffic` to see the documentation, or `/help.dev <name>` for the source docstrings.
 
@@ -1140,16 +1086,22 @@ Actual:   01 00 C9 FF FE 0A  ->  ID:01  Temp:201   Signed:-2   Status:0A
 <details>
 <summary>Supported types</summary>
 
+<!-- format-types:start (generated by scripts/sync_format_tables.py from protocol/type_codes.py -- do not edit by hand) -->
+
 | Code   | Meaning          | Example            | Output       |
 | ------ | ---------------- | ------------------ | ------------ |
 | `H`    | Hex bytes        | `H1`, `H3-4`       | `0A`, `01FF` |
+| `h`    | Hex, per byte    | `h3-4`             | `01 FF`      |
 | `U`    | Unsigned integer | `U1`, `U3-4`       | `10`, `256`  |
 | `I`    | Signed integer   | `I1`, `I3-4`       | `-1`, `+127` |
-| `S`    | ASCII string     | `S5-12`            | `Hello...`   |
+| `S`    | ASCII string     | `S1-5`             | `Hello`      |
 | `F`    | IEEE 754 float   | `F1-4`             | `3.14`       |
 | `B`    | Bit field        | `B1.3`, `B1-2.7-9` | `1`, `5`     |
-| `_`    | Padding (hidden) | `_:_3-4`           | *(skipped)*  |
-| `crc*` | CRC verify       | `CRC:crc16-modbus_le` | pass/fail |
+| `b`    | Bit field, bits  | `b1.0-7`           | `00000110`   |
+| `_`    | Padding (hidden) | `_3-4`             | *(skipped)*  |
+| `crc*` | CRC verify       | `crc16-modbus`     | pass/fail    |
+
+<!-- format-types:end -->
 
 Integers support 1, 2, 3, 4, and 8 byte widths. Floats are 4-byte (F32) or 8-byte (F64).
 
@@ -1239,30 +1191,19 @@ From the REPL:
 <details>
 <summary><strong>Portability</strong></summary>
 
-Developed and tested on **Windows**. Basic usage verified on **macOS** (serial, ANSI rendering, screenshots). macOS support is **alpha** until further testing. **Linux** is exercised by GitHub Actions CI on every push (the full test suite, including the CLI gold-standard integration test, runs on Ubuntu against Python 3.11 through 3.14), but interactive use on Linux has not been hand-verified by the author.
+Developed and tested on **Windows**. Basic usage verified on **macOS** (serial, ANSI rendering, screenshots). macOS support is **alpha** until further testing. **Linux** is exercised by GitHub Actions CI on every push (the full test suite, including the CLI gold-standard integration test, runs on Ubuntu against Python 3.11 through 3.15), but interactive use on Linux has not been hand-verified by the author.
 
 </details>
 
 <details>
 <summary><strong>Architecture</strong> - threading model</summary>
 
-Textual runs on a single async event loop. Termapy uses `@work(thread=True)` for blocking operations, posting UI updates via `call_from_thread()`.
-
-| Worker              | Lifetime    | Purpose                                                 |
-| ------------------- | ----------- | ------------------------------------------------------- |
-| `SerialEngine.read_loop()` | Long-lived | The reader thread (`start_reader` / `stop_reader`); hands RX to the UI without blocking |
-| `_run_reconnect()`  | Short-lived | Retries serial connection every 2.5s until success      |
-| `_run_lines()`      | Short-lived | Sends multiple commands with inter-command delay        |
-| `_run_script()`     | Short-lived | Executes a `.run` script file line by line              |
-| `_send_test()`      | Short-lived | Runs a single protocol test case (`proto_debug.py`)     |
-| `_run_cmds()`       | Short-lived | Sends setup/teardown commands for protocol tests (`proto_debug.py`) |
-
-Only the reader is long-lived. At most two workers run concurrently: the serial reader plus one command/script/test worker.
+Every command runs on a worker thread, the serial reader is the only long-lived thread, and the UI thread never parks on a lock a worker holds. The one description of the threads, their hand-offs, and the rules each relies on is the [Threading model](ARCHITECTURE.md#threading-model) section of ARCHITECTURE.md.
 
 </details>
 
 <details>
-<summary><strong>Test coverage</strong> - 3394 tests, 72% core-module coverage</summary>
+<summary><strong>Test coverage</strong> - 4913 tests, 84% core-module coverage</summary>
 
 Run the full suite with `uv run pytest`. (The count above is the one place it
 is tracked; `release_prep` refreshes it each release.)
@@ -1279,7 +1220,7 @@ generator permutation.
 
 **Built-in plugins:** broad coverage via `test_builtins.py` plus per-plugin test files (`test_var.py`, `test_env_var.py`, `test_xmodem.py`, `test_ymodem.py`, `test_app_plugin.py`, `test_proto_send_crc.py`, etc.).
 
-**UI code:** `app.py` is driven headless by `tests/test_app_pilot.py` (Textual Pilot boots the real app), and the dialogs have Pilot tests of their own; `proto_debug.py` is still exercised manually. The headline coverage figure is **core-module** coverage, measured with `dialogs/`, the `builtins/` package top level, and vendored code **omitted** (see `[tool.coverage.run]` in `pyproject.toml`) — so it is *not* whole-repo coverage. Counting the whole repo (only vendored third-party code omitted) is lower, and that gap is exactly this untested UI layer. The omit is deliberate — the focus has been on extracting business logic into unit-testable modules and keeping the UI as thin delegation — but the headline number is core-module, not overall.
+**UI code:** `app.py` is driven headless by `tests/test_app_pilot*.py` (Textual Pilot boots the real app), every dialog by `tests/test_dialogs*.py` (each pushed into a bare host app), and `proto_debug.py` has Pilot coverage for its Run and Stop controls and is otherwise exercised manually. The headline coverage figure is measured with the `builtins/` package top level and vendored code **omitted** (see `[tool.coverage.run]` in `pyproject.toml`): `builtins/` are plugins covered behaviorally through the commands they register, `vendor/` is third-party. `app.py` and `dialogs/` are counted, so the UI layer's number is real and movable rather than a flattering omission.
 
 </details>
 
@@ -1290,9 +1231,9 @@ All tests run automatically on push to `main` and on pull requests via GitHub Ac
 
 | Job          | What it does                                                                                      |
 | ------------ | ------------------------------------------------------------------------------------------------- |
-| **test**     | Runs `pytest` across Python 3.11, 3.12, 3.13, and 3.14                                            |
+| **test**     | Runs `pytest` across Python 3.11, 3.12, 3.13, 3.14, and 3.15                                      |
 | **coverage** | Runs `pytest --cov` on Python 3.14 and uploads to [Codecov](https://codecov.io/gh/hucker/termapy) |
-| **audit**    | Runs `pip-audit` to check for known vulnerabilities in dependencies                               |
+| **audit**    | Audits `uv.lock` with `pip-audit` (every extra and group; `scripts/audit_lock.py`)               |
 
 The CI badge at the top of this README reflects the current status of the test workflow. See [`.github/workflows/tests.yml`](.github/workflows/tests.yml) for the full configuration.