From e539324c64a2331f136b348b8eda226e8bca6147 Mon Sep 17 00:00:00 2001
From: Conan Scott <conanscott@gmail.com>
Date: Wed, 4 Mar 2026 10:14:38 +0000
Subject: [PATCH] Update README.md

---
 README.md | 102 ++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 100 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index f7b3960..94e0800 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,101 @@
-# st-flow-tests
+# ST Flow Tests
 
-Canonical test harness for SecureTransport AR flows
\ No newline at end of file
+Canonical test harness for Axway SecureTransport Advanced Routing flows.
+
+## Purpose
+
+This repo provides:
+- **Fixture files** — deterministic test inputs with known content and checksums
+- **Test runner** — automated upload → route → verify cycle via SFTP and ST API
+- **Flow specs** — declarative YAML definitions of reference AR flows
+- **Machine context** — structured metadata for AI agents building/testing flows
+
+## Quick Start
+
+```bash
+# Configure environment
+cp env.example .env
+# Edit .env with your ST host, credentials, SFTP target, and partner destination
+
+# Install dependencies
+pip install -r requirements.txt
+
+# Run full test suite against a configured flow
+python scripts/run_tests.py --spec specs/compress-pgp-passthrough.yaml --env .env
+```
+
+## Test Suite Structure
+
+```
+fixtures/          # Canonical input files (committed, never regenerated)
+  test.txt         # Plain text — expected: compressed to .zip
+  test.md          # Markdown — expected: PGP encrypted to .md.pgp
+  test.csv         # CSV — expected: pass-through, unchanged
+  test.pdf         # PDF stub — expected: pass-through, unchanged
+  test.jpg         # JPEG stub — expected: pass-through, unchanged
+
+specs/             # Declarative flow definitions
+  compress-pgp-passthrough.yaml   # Reference 3-step flow
+  schema.md        # Spec format documentation
+
+scripts/
+  run_tests.py     # Main test runner
+  st_env_snapshot.py   # Query live ST environment for context injection
+  st_deploy.py     # Idempotent deploy from spec YAML
+
+results/           # Test run output (gitignored)
+  .gitkeep
+```
+
+## Test Matrix
+
+| Fixture | Expected Transformation | Verification Method |
+|---------|------------------------|---------------------|
+| `test.txt` | Compressed → `test.txt.zip` | Filename suffix + size increase |
+| `test.md` | PGP encrypted → `test.md.pgp` | Filename suffix + binary PGP header `0xC1` |
+| `test.csv` | Pass-through — unchanged | Filename exact match + byte-for-byte size |
+| `test.pdf` | Pass-through — unchanged | Filename exact match + byte-for-byte size |
+| `test.jpg` | Pass-through — unchanged | Filename exact match + byte-for-byte size |
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `ST_HOST` | ST admin host (e.g. `192.168.0.245`) |
+| `ST_ADMIN_PORT` | Admin API port (default `444`) |
+| `ST_ADMIN_USER` | Admin username |
+| `ST_ADMIN_PASS` | Admin password |
+| `ST_SFTP_HOST` | ST SFTP host |
+| `ST_SFTP_PORT` | SFTP port (default `8022`) |
+| `ST_SFTP_USER` | SFTP upload account |
+| `ST_SFTP_PASS` | SFTP upload password |
+| `ST_SFTP_UPLOAD_DIR` | Remote upload directory (e.g. `/skill-test`) |
+| `PARTNER_SSH_HOST` | Partner destination host |
+| `PARTNER_SSH_PORT` | Partner SSH port |
+| `PARTNER_SSH_USER` | Partner SSH user |
+| `PARTNER_SSH_KEY` | Path to partner SSH private key |
+| `PARTNER_DEST_DIR` | Partner destination directory to verify |
+| `ROUTING_TIMEOUT_SEC` | Seconds to wait for routing to complete (default `30`) |
+
+## Fixture Checksums (SHA-256)
+
+Fixtures are committed with known content. Verify before running:
+
+```bash
+sha256sum fixtures/*
+```
+
+Expected values are recorded in `fixtures/CHECKSUMS`.
+
+## Adding a New Test Case
+
+1. Add the fixture file to `fixtures/` with deterministic content
+2. Update `fixtures/CHECKSUMS`
+3. Add a row to the test matrix in `MACHINE.md`
+4. The runner auto-discovers all fixtures — no code changes needed for new file types
+
+## Relation to st-flows Skill
+
+This repo is the **validation layer** for flows built using the `st-flows` agent skill.
+The flow specs in `specs/` are the declarative source of truth for what the agent builds.
+The test runner confirms the built flow behaves as specified.