From 697e77da4f55b45140b5a44c1878caea1b5cc00d Mon Sep 17 00:00:00 2001
From: Kieran Klukas <kieranklukas@cedarville.edu>
Date: Wed, 25 Feb 2026 19:13:03 -0500
Subject: [PATCH] feat: add release workflow

---
 .github/workflows/release.yml | 76 +++++++++++++++++++++++++++++++++++
 README.md                     | 37 ++++++++++++++++-
 2 files changed, 112 insertions(+), 1 deletion(-)
 create mode 100644 .github/workflows/release.yml

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
new file mode 100644
index 0000000..9fb31bb
--- /dev/null
+++ b/.github/workflows/release.yml
@@ -0,0 +1,76 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: write
+
+jobs:
+  build:
+    strategy:
+      matrix:
+        include:
+          - target: aarch64-apple-darwin
+            os: macos-latest
+            name: ectf-tools-aarch64-apple-darwin
+          - target: x86_64-apple-darwin
+            os: macos-latest
+            name: ectf-tools-x86_64-apple-darwin
+          - target: x86_64-unknown-linux-gnu
+            os: ubuntu-latest
+            name: ectf-tools-x86_64-unknown-linux-gnu
+          - target: aarch64-unknown-linux-gnu
+            os: ubuntu-latest
+            name: ectf-tools-aarch64-unknown-linux-gnu
+
+    runs-on: ${{ matrix.os }}
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install Rust
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          targets: ${{ matrix.target }}
+
+      - name: Install cross-compilation tools
+        if: matrix.target == 'aarch64-unknown-linux-gnu'
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y gcc-aarch64-linux-gnu
+
+      - name: Build
+        env:
+          CARGO_TARGET_AARCH64_UNKNOWN_LINUX_GNU_LINKER: aarch64-linux-gnu-gcc
+        run: cargo build --release --target ${{ matrix.target }}
+
+      - name: Package
+        run: |
+          cd target/${{ matrix.target }}/release
+          tar czf ../../../${{ matrix.name }}.tar.gz ectf-tools
+          cd ../../..
+
+      - name: Upload artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: ${{ matrix.name }}
+          path: ${{ matrix.name }}.tar.gz
+
+  release:
+    needs: build
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Download artifacts
+        uses: actions/download-artifact@v4
+        with:
+          merge-multiple: true
+
+      - name: Create release
+        uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true
+          files: "*.tar.gz"
diff --git a/README.md b/README.md
index bcd006f..2399b4d 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,41 @@
 # rust-ectf-tools
 
-ectf tools rebuilt in rust
+Drop-in replacement for MITRE's `uvx ectf tools` host tools, rewritten in Rust with reliable serial I/O. Uses raw termios instead of pyserial to avoid macOS CDC-ACM data corruption bugs.
+
+## Usage
+
+```bash
+cargo build --release
+```
+
+```bash
+# List files on the HSM
+./target/release/ectf-tools /dev/tty.usbmodemXXX list 1a2b3c
+
+# Write a file
+./target/release/ectf-tools /dev/tty.usbmodemXXX write 1a2b3c 0 0x4321 myfile.bin
+
+# Read a file
+./target/release/ectf-tools /dev/tty.usbmodemXXX read 1a2b3c 1 ./output/
+
+# Interrogate a connected HSM
+./target/release/ectf-tools /dev/tty.usbmodemXXX interrogate 1a2b3c
+
+# Listen for another HSM
+./target/release/ectf-tools /dev/tty.usbmodemXXX listen
+
+# Receive a file from another HSM
+./target/release/ectf-tools /dev/tty.usbmodemXXX receive 1a2b3c 0 1
+```
+
+### Verbosity
+
+- `-v` — protocol-level debug (headers, ACKs, chunk sizes)
+- `-vv` — raw byte-level trace with xxd-style hexdump
+
+## Why not pyserial?
+
+pyserial has known data corruption issues on macOS with CDC-ACM devices (like the MAX78000). This tool opens the serial port directly with proper termios configuration, flushes the input buffer on open, and uses `O_NONBLOCK` to avoid blocking on carrier detect.
 
 <p align="center">
     <img src="https://raw.githubusercontent.com/taciturnaxolotl/carriage/main/.github/images/line-break.svg" />