From 464a31be09a738a823dfd56db73815b65ce9115c Mon Sep 17 00:00:00 2001
From: Tyler <tyler@crispygoat.com>
Date: Fri, 19 Jun 2026 16:01:25 -0600
Subject: [PATCH] docs(backend): README with install, CLI, and programmatic
 usage

---
 backend/README.md | 68 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 68 insertions(+)
 create mode 100644 backend/README.md

diff --git a/backend/README.md b/backend/README.md
new file mode 100644
index 0000000..6aaf6e7
--- /dev/null
+++ b/backend/README.md
@@ -0,0 +1,68 @@
+# Cyclone Backend — X12 837P Parser
+
+Python module + CLI for parsing X12 837P professional claim files into one
+validated JSON per claim. Output is consumed by the Cyclone Vite/React
+frontend (later via a FastAPI service).
+
+## Install
+
+```bash
+cd backend
+python -m venv .venv
+. .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+## CLI
+
+```bash
+python -m cyclone.cli parse-837 path/to/837p.txt --output-dir ./claims
+```
+
+Options:
+- `--payer {co_medicaid,generic_837p}` — default `co_medicaid`
+- `--strict` — promote warnings to errors
+- `--max-retries N` — stub in v1 (no auto-fix yet)
+- `--include-raw-segments / --no-raw-segments` — default: include
+- `--log-level {DEBUG,INFO,WARNING,ERROR}`
+
+Exit codes:
+- `0` — every claim parsed
+- `2` — file-level failure (no envelope, no claims)
+- `1` — unexpected exception
+
+## Output
+
+```
+claims/
+├── claim-991102977-20260611-CLM001.json   # one per claim
+├── claim-991102977-20260611-CLM002.json
+└── summary.json                            # batch summary
+```
+
+## Programmatic use
+
+```python
+from pathlib import Path
+from cyclone.parsers.parse_837 import parse
+from cyclone.parsers.payer import PayerConfig
+from cyclone.parsers.writer import write_outputs
+
+result = parse(Path("input.txt").read_text(), PayerConfig.co_medicaid())
+write_outputs(result, Path("./claims"))
+print(f"passed={result.summary.passed} failed={result.summary.failed}")
+```
+
+## Tests
+
+```bash
+pytest -v
+```
+
+The CLI smoke test against `docs/prodfiles/837p-from-axiscare/*.txt` is
+auto-skipped if no production files are present.
+
+## Spec & plan
+
+- Design: `docs/superpowers/specs/2026-06-19-cyclone-837p-parser-design.md`
+- Plan: `docs/superpowers/plans/2026-06-19-cyclone-837p-parser.md`