From 307a8d3b69d1a4d6926ffb059e5cdc554de3cf2e Mon Sep 17 00:00:00 2001
From: Tyler <tyler@crispygoat.com>
Date: Fri, 19 Jun 2026 19:49:34 -0600
Subject: [PATCH] docs: add co-medicaid reference note

---
 docs/reference/co-medicaid.md | 71 +++++++++++++++++++++++++++++++++++
 1 file changed, 71 insertions(+)
 create mode 100644 docs/reference/co-medicaid.md

diff --git a/docs/reference/co-medicaid.md b/docs/reference/co-medicaid.md
new file mode 100644
index 0000000..fb323b3
--- /dev/null
+++ b/docs/reference/co-medicaid.md
@@ -0,0 +1,71 @@
+# Colorado Medicaid — payer specifics
+
+Cyclone's CO Medicaid (`PayerConfig.co_medicaid()` and
+`PayerConfig835.co_medicaid_835()`) factories encode the trading-partner
+and code-set rules that the Colorado Department of Health Care Policy &
+Financing (HCPF) requires.
+
+## Trading Partner IDs (TPID)
+
+| Role | 837P | 835 |
+|---|---|---|
+| Sender | `SKCO0` | (varies; usually the clearinghouse) |
+| Receiver | `COHCPF` | (varies) |
+
+These appear in the `NM1*PR` (payer) and `NM1*40` (receiver) segments of
+the 837P file.
+
+## Payer IDs
+
+### 837P (claims)
+
+- `NM1*PR N104 = "SKCO0"` (COHCPF)
+
+### 835 (remittance)
+
+- `BPR10 = "81-1725341"` — TXIX (Medicaid) account
+- `BPR10 = "84-0644739"` — BHA (behavioral health) account
+- `N1*PR N104 = "7912900843"` — payer ID
+- `N1*PR N102` is one of `"CO_TXIX"` or `"CO_BHA"`
+
+## Allowed codes
+
+### 837P `CLM05-3` (frequency code)
+
+| Code | Meaning |
+|---|---|
+| 1 | Original claim |
+| 7 | Replacement claim |
+| 8 | Void / cancel |
+
+Cyclone raises `R030_frequency_allowed` if any other value appears.
+
+### 835 `CLP02` (claim status code)
+
+Allowed: `{1, 2, 3, 4, 19, 20, 21, 22, 23, 25}`. See the 835 reference
+note for the meaning of each.
+
+### Place of service (POS)
+
+All CMS POS codes `01`–`99` are accepted. The canonical list lives in
+`cyclone/parsers/payer.py` as `CMS_PLACE_OF_SERVICE_CODES` and is the
+source of truth for validation and any UI dropdowns.
+
+## Validation rules Cyclone enforces
+
+See [837p.md](./837p.md#validation-rules-cyclone-enforces) and the
+`cyclone.parsers.validator` / `cyclone.parsers.validator_835` modules.
+
+## Adding a new payer
+
+The pattern is:
+
+1. Add a `PayerConfig` (837P) and `PayerConfig835` (835) factory in
+   `cyclone/parsers/payer.py` — usually thin wrappers that override only
+   the differing fields (allowed codes, payer IDs).
+2. Register the factory in the `PAYER_FACTORIES` / `PAYER_FACTORIES_835`
+   dicts in `cyclone/api.py` and `cyclone/cli.py`.
+3. Add a smoke fixture under `backend/tests/fixtures/` (a real or
+   synthetic file matching the new payer's rules) and a parser test that
+   loads it.
+4. Update this note + the 837p/835 notes with the new payer's specifics.