The companion guide editor

Outcome

You can browse the companion guides bound to your trading partners, drill into a guide's transaction tree to see exactly which segments and elements it customizes, and preview how a sample transaction would look before and after the guide is applied.

Prerequisites

Scope	What it lets you do
edi.companion-guide.read	View list / detail / preview
edi.companion-guide.write	Edit rules, clone, activate

A registered trading partner whose payer publishes a companion guide. See 2.1 — Onboard a new trading partner.

Where it lives

/companion-guides in the edi-app. The list shows every guide registered across your tenant, with columns for partner, applicable transaction (837P, 837I, 270, 278, 835), effective window, and version number.

The detail page

Click into /companion-guides/:guideId. The page is split into three panes:

Pane	What it does
Transaction tree	Walks the canonical X12 structure for the guide's target transaction. Every segment a rule touches is highlighted. Click a segment to open its rule.
Rule list	Tabular view of every rule in the guide. Sortable by location, rule type, status.
Live preview	Drop a sample transaction (or pick one from /transactions); the pane shows the original on the left and the after-applicator on the right with a per-segment diff.

Steps to read an existing guide

1. Open the guide at /companion-guides/:guideId. The header shows partner, transaction, effective window.

2. Walk the transaction tree from ISA down. Highlighted segments carry rules; the count of rules per segment appears as a badge.

3. Click a highlighted segment — RuleEditDialog opens read-only. Inspect the rule's type (override / suppress / validate / append) and the value spec.

4. Use Live preview to see the rule in action. Drop a sample 837 (or copy one from /transactions); the pane diffs original vs. transformed.

Steps to author a rule

1. Open the guide with edi.companion-guide.write scope.

2. Right-click a segment in the transaction tree → + Add rule. The RuleEditDialog opens for create.

3. Pick the rule type — see 7.2 — Rule types & applicator. The dialog adapts the visible fields based on the type.

4. Fill the spec:

   Rule type	Required fields
   override	Element index (e.g. NM103), new value (literal or template).
   suppress	Element / segment selector.
   validate	Element / segment selector + validation expression.
   append	Position selector + new segment to insert.

5. Save. The rule appears in the rule list and the segment lights up in the tree.

6. Verify with Live preview. Drop the sample transaction; confirm the diff matches your intent.

Live preview semantics

The preview backend lives at POST /companion-guides/:id/preview in the edi-gateway and runs applyCompanionGuide() from packages/x12/src/companion-guides/applicator.ts against your sample. It returns:

Field	Content
before	The raw input transaction.
after	The transaction with this guide's rules applied.
appliedRules	Per rule: rule ID, location, action taken (override / suppress / validate-pass / validate-fail / append).
validationErrors	Any validate rules that failed against the sample.

The preview is read-only — no changes persist anywhere; sample data is not stored.

Validation

Check	Expected
New / edited rule appears in the rule list	Yes, immediately.
Preview diff matches intent	Yes.
Tree-segment count badge increments	Yes.
Existing transactions are not retroactively modified	Yes — guides apply at generate / parse time only.

Troubleshooting

Symptom	Cause	Fix
Save returns segment not in target transaction	Selector references a segment that does not exist in the guide's transaction shape	Confirm via the tree; segment IDs are the X12 IDs (NM1, CLM).
Preview shows no diff after rule add	Rule's selector did not match the sample	Loosen the selector, or confirm the sample carries the segment in the position you expect.
Validate rule fires unexpectedly	Validation expression is too strict	Edit the expression; validate rules accept a small DSL (see 7.2).
Tree pane shows blank for transaction kind	Guide's transaction_set_id is set to a value the tree doesn't render	Confirm transaction_set_id is one of 837P, 837I, 270, 271, 278, 835.

Next

7.2 — Rule types & applicator